feat: scale-aware step-jump capture, live stage-status timeline, richer session report

Finishes the auto-tune overhaul with the smaller adaptivity/UX items:

- src/model/scale.ts: the manual/wizard step-jump capture's distance and
  feedrate are now derived from the axis's actual steps-per-mm and
  microstepping (a "step jump" means the same physical thing — a handful of
  whole motor steps, over roughly the same amount of time — on a coarse
  leadscrew axis and a fine belt axis alike), replacing the fixed "16 full
  steps" formula's hardcoded F18000 feed.
- Live stage-status timeline: a chip row (Preflight → P → D → I → A → V →
  Verify) shows each stage's live pending/running/done/failed state during
  an auto-tune run, via a new onStage callback on TuneEffects.
- Richer session report: TuneSession now carries the Ku/Tu found during
  seeding, the calibration moves preflight actually ran, and whether the
  run's PID was restored from a snapshot — so a downloaded report explains
  what auto-tune did, not just what it ended up with.

Author: jaysuk

src/__tests__/autorun.test.ts

@@ -432,3 +432,50 @@ describe("runAutoTune — final verification", () => {
 		expect(result.evaluation).toBeUndefined();
 	});
 });
+
+describe("runAutoTune — stage-status callbacks", () => {
+	it("reports preflight, every term, and verify as running then done on a clean axis run", async () => {
+		const stages: Array<string> = [];
+		const onStage = vi.fn((stage: string, state: string) => stages.push(`${stage}:${state}`));
+		const { effects } = fakeEffects({ onStage });
+		const result = await runAutoTune(effects, basePid(), { cycles: 1, hasAxis: true });
+		expect(result.ok).toBe(true);
+		for (const stage of ["preflight", "p", "d", "i", "a", "v", "verify"]) {
+			expect(stages).toContain(`${stage}:running`);
+			expect(stages).toContain(`${stage}:done`);
+		}
+		// Every stage must report "running" before it reports "done".
+		for (const stage of ["preflight", "p", "d", "i", "a", "v", "verify"]) {
+			expect(stages.indexOf(`${stage}:running`)).toBeLessThan(stages.indexOf(`${stage}:done`));
+		}
+	});
+
+	it("marks the failing stage as failed, and never starts a later stage in the same run", async () => {
+		const stages: Array<string> = [];
+		const onStage = vi.fn((stage: string, state: string) => stages.push(`${stage}:${state}`));
+		let preflightDone = false;
+		const captureSignal = vi.fn(async () => {
+			if (!preflightDone) { preflightDone = true; return GOOD_SIGNAL; } // let preflight's probe succeed
+			return null; // everything afterwards (seeding + the P ramp) fails outright
+		});
+		const { effects } = fakeEffects({ onStage, captureSignal });
+		const result = await runAutoTune(effects, basePid(), { cycles: 1, hasAxis: true });
+		expect(result.ok).toBe(false);
+		expect(stages).toContain("preflight:done");
+		const failedStages = stages.filter((s) => s.endsWith(":failed"));
+		expect(failedStages.length).toBe(1); // exactly one stage fails, and the run stops there
+		expect(stages).not.toContain("i:running");
+		expect(stages).not.toContain("a:running");
+		expect(stages).not.toContain("v:running");
+		expect(stages).not.toContain("verify:running");
+	});
+
+	it("reports preflight as failed when the driver never starts tracking", async () => {
+		const stages: Array<string> = [];
+		const onStage = vi.fn((stage: string, state: string) => stages.push(`${stage}:${state}`));
+		const { effects } = fakeEffects({ onStage, captureSignal: vi.fn(async () => sig({ stats: { movePeak: 500 } })) });
+		const result = await runAutoTune(effects, basePid(), { cycles: 1, hasAxis: true, calibrationMoveIds: [] });
+		expect(result.ok).toBe(false);
+		expect(stages).toEqual(["preflight:running", "preflight:failed"]);
+	});
+});

src/__tests__/scale.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+
+import { mmPerFullStep, stepJumpDistanceMm, stepJumpFeedMmPerMin } from "../model/scale";
+
+describe("mmPerFullStep", () => {
+	it("computes mm-per-full-step from steps-per-mm (incl. microstepping) and the microstepping factor", () => {
+		// 1280 steps/mm at 16x microstepping = 80 full steps/mm = 0.0125 mm per full step.
+		expect(mmPerFullStep({ stepsPerMm: 1280, microstepping: 16 })).toBeCloseTo(0.0125, 6);
+	});
+	it("falls back to a sane default when the object model hasn't reported values yet", () => {
+		expect(mmPerFullStep({})).toBeCloseTo(16 / 80, 6);
+		expect(mmPerFullStep({ stepsPerMm: 0, microstepping: undefined })).toBeCloseTo(16 / 80, 6);
+	});
+	it("ignores non-finite or non-positive readings and falls back", () => {
+		expect(mmPerFullStep({ stepsPerMm: Number.NaN, microstepping: -5 })).toBeCloseTo(16 / 80, 6);
+	});
+});
+
+describe("stepJumpDistanceMm", () => {
+	it("scales with the axis resolution — a coarser axis needs a bigger jump for the same step count", () => {
+		const fine = stepJumpDistanceMm({ stepsPerMm: 1280, microstepping: 16 });   // 80 full steps/mm
+		const coarse = stepJumpDistanceMm({ stepsPerMm: 160, microstepping: 16 });  // 10 full steps/mm
+		expect(coarse).toBeGreaterThan(fine);
+		expect(coarse).toBeCloseTo(fine * 8, 6); // 8x coarser pitch → 8x the distance for the same step count
+	});
+	it("never returns a distance below the floor, even at extreme resolution", () => {
+		expect(stepJumpDistanceMm({ stepsPerMm: 100000, microstepping: 1 })).toBeGreaterThanOrEqual(0.1);
+	});
+	it("defaults to 16 full steps, but honours an explicit step count", () => {
+		const scale = { stepsPerMm: 1280, microstepping: 16 };
+		expect(stepJumpDistanceMm(scale, 32)).toBeCloseTo(stepJumpDistanceMm(scale, 16) * 2, 6);
+	});
+});
+
+describe("stepJumpFeedMmPerMin", () => {
+	it("scales feed with distance so the move takes roughly the same time regardless of scale", () => {
+		const small = stepJumpFeedMmPerMin(0.2);
+		const large = stepJumpFeedMmPerMin(2.0);
+		expect(large).toBeGreaterThan(small);
+	});
+	it("clamps to a sane floor for a tiny distance", () => {
+		expect(stepJumpFeedMmPerMin(0.001)).toBeGreaterThanOrEqual(600);
+	});
+	it("clamps to a sane ceiling for a large distance", () => {
+		expect(stepJumpFeedMmPerMin(1000)).toBeLessThanOrEqual(30000);
+	});
+});

src/components/ClosedLoopTuning.vue

@@ -159,6 +159,12 @@
 								<v-spacer />
 								<span class="text-caption text-medium-emphasis">{{ autoStatus }}</span>
 							</div>
+							<div v-if="autoRunning || tuneSession" class="d-flex flex-wrap ga-1 mt-2">
+								<v-chip v-for="s in STAGE_ORDER" :key="s.id" size="small"
+										:color="stageColor(stageStates[s.id])"
+										:variant="stageStates[s.id] === 'pending' ? 'outlined' : 'flat'"
+										:prepend-icon="stageIcon(stageStates[s.id])">{{ s.label }}</v-chip>
+							</div>
 							<div class="d-flex flex-wrap ga-1 mt-2">
 								<v-chip v-for="t in pidSummary" :key="t.term" size="small"
 										:color="autoRunning && wizardStep.term === t.term ? 'primary' : undefined"
@@ -436,6 +442,7 @@ import CaptureChart from "./CaptureChart.vue";
 import { evaluateTune, gradeColor, severityColor, severityIcon, type Term, type TuneEvaluation } from "../model/evaluate";
 import { CAPTURE_DIR, CONFIG_FILE, DOCS, LS_STATE, PLUGIN_ID } from "../model/constants";
 import { upsertTuneBlock } from "../model/config";
+import { stepJumpDistanceMm, stepJumpFeedMmPerMin } from "../model/scale";
 import {
 	buildCalibrationCommand, buildCaptureCommand, buildModeCommand, buildPidCommand,
 	CALIBRATION_MOVES, CAPTURE_VARIABLES, DEFAULT_MODE_D, ENCODER_TYPES, MODE_LABELS,
@@ -449,7 +456,7 @@ import {
 } from "../model/limits";
 import { WIZARD_STEPS, type Recommendation } from "../model/wizard";
 import { computeTuneSignal, type TuneSignal } from "../model/signal";
-import { runAutoTune as runAutoTuneCore, type TuneEffects } from "../model/autorun";
+import { runAutoTune as runAutoTuneCore, type AutoRunResult, type StageId, type StageState, type TuneEffects } from "../model/autorun";
 import { applying, applyUpdateNow, checking, dismissCurrentUpdate, pendingReload, runUpdateCheck, setUpdateChecksEnabled, updateChecksEnabled, updateState } from "../model/updateCheck";
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -529,6 +536,30 @@ const autoRunning = ref(false);
 const autoCancel = ref(false);
 const autoStatus = ref("");
 const autoLog = ref<Array<string>>([]);
+
+// Stage-status timeline: preflight → P → D → I → A → V → verify (P–V repeat every cycle).
+const STAGE_ORDER: Array<{ id: StageId; label: string }> = [
+	{ id: "preflight", label: "Preflight" }, { id: "p", label: "P" }, { id: "d", label: "D" },
+	{ id: "i", label: "I" }, { id: "a", label: "A" }, { id: "v", label: "V" }, { id: "verify", label: "Verify" },
+];
+const stageStates = reactive<Record<StageId, StageState>>({ preflight: "pending", p: "pending", d: "pending", i: "pending", a: "pending", v: "pending", verify: "pending" });
+function resetStageStates(): void { for (const s of STAGE_ORDER) { stageStates[s.id] = "pending"; } }
+function stageColor(state: StageState): string | undefined {
+	switch (state) {
+		case "running": return "primary";
+		case "done": return "success";
+		case "failed": return "error";
+		default: return undefined;
+	}
+}
+function stageIcon(state: StageState): string {
+	switch (state) {
+		case "running": return "mdi-progress-clock";
+		case "done": return "mdi-check-circle";
+		case "failed": return "mdi-close-circle";
+		default: return "mdi-circle-outline";
+	}
+}
 const avDistance = ref(saved.avDistance ?? 50);   // mm — A/V test move length
 const avFeed = ref(saved.avFeed ?? 6000);          // mm/min — A/V test move feedrate
 const cycles = ref(saved.cycles ?? 3);             // how many times to iterate P→D→I
@@ -578,6 +609,12 @@ interface TuneSession {
 	startedAt: string; finishedAt?: string; driver: string | null; mode: LoopMode | null;
 	encoderType: EncoderType; cycles: number; finalPid?: PidConfig; log: Array<string>;
 	captures: Array<SessionCapture>; evaluation?: TuneEvaluation | null;
+	/** Ultimate gain/period found during Ku/Tu seeding, when it succeeded. */
+	ku?: number; tu?: number;
+	/** Calibration moves (M569.6 V-ids) actually run during preflight. */
+	preflightActions?: Array<string>;
+	/** True if the run failed/was cancelled and the pre-run PID snapshot was restored. */
+	restored?: boolean;
 }
 const tuneSession = ref<TuneSession | null>(null);
 function recordSessionCapture(phase: string, value: number | undefined, metrics: unknown): void {
@@ -893,9 +930,7 @@ async function captureStep(): Promise<StepMetrics | null> {
 	const stepVars = varIds(["measuredMotorSteps", "targetMotorSteps", "currentError", "pidPTerm"]);
 	let c: ParsedCapture | null;
 	if (ax?.letter) {
-		const stepsPerMm = Number(ax.stepsPerMm) || 80;
-		const micro = Number(ax.microstepping?.value) || 16;
-		const desired = Math.max(0.1, (micro / stepsPerMm) * 16);   // ~16 full steps ≈ a step jump
+		const desired = stepJumpDistanceMm({ stepsPerMm: Number(ax.stepsPerMm), microstepping: Number(ax.microstepping?.value) });
 		let dist = desired;
 		let sign: 1 | -1 = 1;
 		if (limits) {
@@ -904,9 +939,10 @@ async function captureStep(): Promise<StepMetrics | null> {
 			dist = plan.distance; sign = plan.sign;
 		}
 		const signedDist = sign * dist;
-		const move = `G91 G1 H2 ${ax.letter}${signedDist.toFixed(3)} F18000 G90`;
+		const feed = stepJumpFeedMmPerMin(dist).toFixed(0);
+		const move = `G91 G1 H2 ${ax.letter}${signedDist.toFixed(3)} F${feed} G90`;
 		c = await runCapture({ driver: selectedDriver.value ?? "", samples: samples.value, activate: 1, rate: sampleRate.value, variables: stepVars, manoeuvre: 0, move });
-		try { await machineStore.sendCode(`G91 G1 H2 ${ax.letter}${(-signedDist).toFixed(3)} F18000 G90`, false, false); } catch { /* return move */ }
+		try { await machineStore.sendCode(`G91 G1 H2 ${ax.letter}${(-signedDist).toFixed(3)} F${feed} G90`, false, false); } catch { /* return move */ }
 	} else {
 		c = await runCapture({ driver: selectedDriver.value ?? "", samples: samples.value, activate: 0, rate: sampleRate.value, variables: stepVars, manoeuvre: 64 });
 	}
@@ -993,6 +1029,7 @@ function buildTuneEffects(): TuneEffects {
 			wizardIndex.value = WIZARD_STEPS.findIndex((s) => s.term === term);
 			recordSessionCapture(term, value, metric);
 		},
+		onStage: (stage, state) => { stageStates[stage] = state; },
 		isCancelled: () => autoCancel.value,
 		delay,
 	};
@@ -1017,15 +1054,17 @@ async function runAutoTune(): Promise<void> {
 	autoRunning.value = true;
 	autoCancel.value = false;
 	autoLog.value = [];
+	resetStageStates();
 	viewKeys.value = ["measuredMotorSteps", "targetMotorSteps", "currentError"];
 	const totalCycles = Math.max(1, Math.round(cycles.value || 1));
 	const hasAxis = !!axisLetterForDriver();
 	tuneSession.value = {
 		startedAt: new Date().toISOString(), driver: selectedDriver.value, mode: currentMode.value,
 		encoderType: encoderType.value, cycles: totalCycles, log: [], captures: [],
 	};
+	let result: AutoRunResult | undefined;
 	try {
-		const result = await runAutoTuneCore(buildTuneEffects(), { ...pid }, { cycles: totalCycles, hasAxis, calibrationMoveIds: requiredMoveIds.value });
+		result = await runAutoTuneCore(buildTuneEffects(), { ...pid }, { cycles: totalCycles, hasAxis, calibrationMoveIds: requiredMoveIds.value });
 		Object.assign(pid, result.pid);
 		if (result.ok) {
 			const gradeNote = result.evaluation ? ` Final grade: ${result.evaluation.grade} (${result.evaluation.score}/100).` : "";
@@ -1045,7 +1084,11 @@ async function runAutoTune(): Promise<void> {
 			tuneSession.value.finishedAt = new Date().toISOString();
 			tuneSession.value.finalPid = { ...pid };
 			tuneSession.value.log = [...autoLog.value];
-			tuneSession.value.evaluation = evaluation.value;
+			tuneSession.value.evaluation = result?.evaluation ?? evaluation.value;
+			tuneSession.value.ku = result?.ku;
+			tuneSession.value.tu = result?.tu;
+			tuneSession.value.preflightActions = result?.preflightActions;
+			tuneSession.value.restored = result?.restored;
 		}
 	}
 }

src/model/autorun.ts

@@ -63,10 +63,16 @@ export interface TuneEffects {
 	status(line: string): void;
 	/** Notified after every capture that feeds a decision (session recording, wizard-step highlighting). */
 	onAttempt?(term: PidTerm, value: number, metric: TuneSignal | StepMetrics): void;
+	/** Notified on stage transitions (preflight → P → D → I → A → V → verify) — drives a progress UI. */
+	onStage?(stage: StageId, state: StageState): void;
 	isCancelled(): boolean;
 	delay(ms: number): Promise<void>;
 }
 
+/** The stages auto-tune moves through, in order (P–V repeat every cycle). */
+export type StageId = "preflight" | PidTerm | "verify";
+export type StageState = "pending" | "running" | "done" | "failed";
+
 export type SeedRule = "tyreus-luyben" | "zn-classic" | "amigo";
 
 export interface AutoRunOptions {
@@ -379,7 +385,9 @@ async function runAxisCycle(
 		const startValue = cycle === 1
 			? (isFeedForward ? strategy.start : (seeded[strategy.term] ?? strategy.start))
 			: pid[strategy.term];
+		effects.onStage?.(strategy.term, "running");
 		const result = await runSignalTerm(effects, strategy, pid, medianOf, verifyRetries, startValue);
+		effects.onStage?.(strategy.term, result.ok ? "done" : "failed");
 		attempts.push(...result.attempts);
 		if (!result.ok) { return { ok: false, reason: result.reason, attempts, ku, tu }; }
 		if (result.finalSignal) { lastSignal = result.finalSignal; }
@@ -393,7 +401,9 @@ async function runExtruderCycle(effects: TuneEffects, pid: PidConfig, cycle: num
 	for (const strategy of AUTOTUNE_SEQUENCE) {
 		if (effects.isCancelled()) { return { ok: false, reason: "Cancelled.", attempts }; }
 		const startValue = cycle === 1 ? strategy.start : pid[strategy.term];
+		effects.onStage?.(strategy.term, "running");
 		const result = await runStepTerm(effects, strategy, pid, startValue);
+		effects.onStage?.(strategy.term, result.ok ? "done" : "failed");
 		attempts.push(...result.attempts);
 		if (!result.ok) { return { ok: false, reason: result.reason, attempts }; }
 	}
@@ -547,7 +557,9 @@ export async function runAutoTune(effects: TuneEffects, startPid: PidConfig, opt
 	let ok = true;
 	let reason: string | undefined;
 	try {
+		effects.onStage?.("preflight", "running");
 		const pre = await preflight(effects, opts.hasAxis, opts.calibrationMoveIds ?? []);
+		effects.onStage?.("preflight", pre.ok ? "done" : "failed");
 		preflightActions = pre.actions;
 		if (!pre.ok) {
 			// Preflight's own probe may already have applied a baseline PID to the firmware — fall through
@@ -588,11 +600,14 @@ export async function runAutoTune(effects: TuneEffects, startPid: PidConfig, opt
 	}
 
 	let evaluation: TuneEvaluation | undefined;
+	effects.onStage?.("verify", "running");
 	try {
 		const verification = await runFinalVerification(effects, pid);
 		evaluation = verification.evaluation;
+		effects.onStage?.("verify", "done");
 	} catch (e) {
 		effects.log(`Final verification skipped: ${e instanceof Error ? e.message : String(e)}`);
+		effects.onStage?.("verify", "failed");
 	}
 	return { ok: true, pid, attempts, ku, tu, preflightActions, evaluation };
 }

src/model/scale.ts

@@ -0,0 +1,53 @@
+/**
+ * Machine-scale-aware capture parameters — pure, unit-tested, so a "step jump" test move means the same
+ * physical thing (a handful of whole motor steps, over roughly the same amount of time) on a coarse-pitch
+ * leadscrew axis and a fine-pitch belt axis alike, instead of a fixed distance/feedrate tuned against
+ * whatever machine the plugin happened to be developed on.
+ */
+
+export interface AxisScaleInfo {
+	/** Steps-per-mm INCLUDING microstepping (RRF `M92` value — the object model's `axis.stepsPerMm`). */
+	stepsPerMm?: number;
+	/** Microstepping factor (RRF `M350` value — the object model's `axis.microstepping.value`). */
+	microstepping?: number;
+}
+
+// Fallbacks for when the object model hasn't reported a value yet — a common, unremarkable 20-tooth
+// GT2/80-steps-per-mm-equivalent belt axis at 16x, so a missing reading degrades to a reasonable jump
+// rather than an error.
+const DEFAULT_STEPS_PER_MM = 80;
+const DEFAULT_MICROSTEPPING = 16;
+
+function resolve(value: number | undefined, fallback: number): number {
+	return value != null && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+
+/** mm covered by one full (whole) motor step, given the axis's configured resolution. */
+export function mmPerFullStep(scale: AxisScaleInfo): number {
+	const stepsPerMm = resolve(scale.stepsPerMm, DEFAULT_STEPS_PER_MM);
+	const microstepping = resolve(scale.microstepping, DEFAULT_MICROSTEPPING);
+	return microstepping / stepsPerMm;
+}
+
+const DEFAULT_STEP_JUMP_FULL_STEPS = 16;
+const MIN_STEP_JUMP_MM = 0.1;
+
+/** Distance (mm) covered by `fullSteps` whole motor steps — the size of a genuine "step jump" test move. */
+export function stepJumpDistanceMm(scale: AxisScaleInfo, fullSteps = DEFAULT_STEP_JUMP_FULL_STEPS): number {
+	return Math.max(MIN_STEP_JUMP_MM, mmPerFullStep(scale) * fullSteps);
+}
+
+const STEP_JUMP_TIME_S = 0.05;    // aim for the jump itself to take about this long, at any machine scale
+const STEP_JUMP_FEED_MIN = 600;   // mm/min floor — a tiny jump still gets a sane, resolvable feedrate
+const STEP_JUMP_FEED_MAX = 30000; // mm/min ceiling — stay within what a typical machine can actually reach
+
+/**
+ * Feedrate (mm/min) for a step-jump test move, scaled so the move itself takes roughly the same amount
+ * of time regardless of the axis's resolution — replacing a fixed feedrate that made a coarse-pitch
+ * axis's "step" move too fast to resolve in the capture window, and a fine-pitch axis's too slow to
+ * look anything like a step.
+ */
+export function stepJumpFeedMmPerMin(distanceMm: number): number {
+	const feed = (distanceMm / STEP_JUMP_TIME_S) * 60;
+	return Math.min(STEP_JUMP_FEED_MAX, Math.max(STEP_JUMP_FEED_MIN, feed));
+}