@alexkroman1/aai-cli 13.3.0 → 14.0.0

package/dist/templates/spoken-summary/workflows/summarize.ts

@@ -18,7 +18,7 @@
  * - **`stepSpeak`** synthesizes from inside a step. The session TTS surface
  *   cannot: a `TtsSession` is an event stream wired into a live pipeline's
  *   playback, and a step has no turn to be part of and has to return a VALUE.
- * - **`writeUpload`** puts that value somewhere. A run's OUTPUT is read back as
+ * - **`stepWriteUpload`** puts that value somewhere. A run's OUTPUT is read back as
  *   JSON, so audio cannot travel in one — the same rule that keeps a
  *   recording's bytes out of a run's INPUT, arriving at the other end of the
  *   run. The bytes go to the store, the output carries the id, and the page
@@ -49,9 +49,9 @@
  * expensive one.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { report, stepSpeak, TRANSCRIBE_API, writeUpload } from "@alexkroman1/aai/step";
-import { stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { stepReport, stepSpeak, stepWriteUpload, TRANSCRIBE_API } from "@alexkroman1/aai/step";
+import { stepGenerateJsonOrFail } from "@alexkroman1/aai/step-errors";
 import { countWords, omitUndefined } from "@alexkroman1/aai/utils";
 // ERASED at build time, so the body can name the schema's own output type without
 // a runtime cycle back through `agent.ts` — the same mechanism `client.tsx` uses
@@ -128,7 +128,7 @@ export type SpokenSummary = {
 /** Transcribe a recording, summarize it, and read the summary back. */
 export async function spokenSummaryFlow(
   input: WorkflowInputOf<typeof spokenSummary>,
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<SpokenSummary> {
   const transcript = await transcribe(input.recording, ctx);
   const summary = await ctx.step("summarize", () => summarize(transcript.text));
@@ -157,7 +157,7 @@ export async function spokenSummaryFlow(
  * re-derives exactly the same sequence. It takes the `ctx` for that reason: a
  * helper that reaches the journal has to be handed the handle.
  */
-async function transcribe(recording: string, ctx: WorkflowCtx): Promise<Transcript> {
+async function transcribe(recording: string, ctx: WorkflowContext): Promise<Transcript> {
   // `maxAttempts: 6` was `uploadToProvider.maxRetries = 5` — five retries after
   // the first attempt. It is the one step here worth extra patience: it streams
   // the whole recording, so a transient failure is expensive to reach again.
@@ -187,8 +187,8 @@ async function transcribe(recording: string, ctx: WorkflowCtx): Promise<Transcri
 export async function summarize(
   text: string,
 ): Promise<{ headline: string; points: string[]; spoken: string }> {
-  await report("Summarizing the transcript.");
-  const reply = await stepGenerateJsonClassified(
+  await stepReport("Summarizing the transcript.");
+  const reply = await stepGenerateJsonOrFail(
     "Summarize this transcript of a recording.\n\n" +
       "Answer with JSON only, in this shape:\n" +
       `{"headline": "...", "points": ["..."], "spoken": "..."}\n\n` +
@@ -204,7 +204,7 @@ export async function summarize(
       system: "You summarize recordings. You answer with JSON and nothing else.",
       schema: SummaryReply,
     },
-    // The `Classified` caller is `stepGenerateJson` plus `throwStepError`, which
+    // The `OrFail` caller is `stepGenerateJson` plus `throwStepError`, which
     // reads the gateway's own status: a 429 is worth another attempt and a 400
     // is not, and that is what tells the DevKit which.
   );
@@ -226,7 +226,7 @@ export async function speak(
   voice?: string,
 ): Promise<{ audio: string; durationMs: number }> {
   const spoken = await stepSpeak(script, omitUndefined({ voice }));
-  const stored = await writeUpload(spoken.audio, {
+  const stored = await stepWriteUpload(spoken.audio, {
     // Named, because this is what a person sees on the download link rather
     // than an opaque id — and typed, because the byte route serves the type it
     // was given and a browser will not play a file it was handed as bytes.
@@ -234,7 +234,7 @@ export async function speak(
     type: "audio/wav",
   });
 
-  await report(
+  await stepReport(
     `Recorded a ${Math.round(spoken.durationMs / 1000)}s summary in ${spoken.voice}'s voice.`,
   );
   return { audio: stored.id, durationMs: spoken.durationMs };

package/dist/templates/spoken-summary/workflows/transcribe.ts

@@ -12,7 +12,7 @@
  *
  * **Every one of them is four lines, because the SDK owns the endpoint.**
  * `stepTranscribeUpload` / `stepTranscribeSubmit` / `stepTranscribePoll` on
- * `@alexkroman1/aai/step` — reached here through their `*Classified` callers on
+ * `@alexkroman1/aai/step` — reached here through their `*OrFail` callers on
  * `@alexkroman1/aai/step-errors` — carry the URL, the raw-key auth, the windowed
  * streaming upload, the PLURAL `speech_models` field and the failure
  * classification — all of which this file used to spell out, and all of which
@@ -40,11 +40,11 @@
  * the one leg that should be as boring as possible.
  */
 
-import { report, uploadInfo } from "@alexkroman1/aai/step";
+import { stepReport, stepUploadInfo } from "@alexkroman1/aai/step";
 import {
-  stepTranscribePollClassified,
-  stepTranscribeSubmitClassified,
-  stepTranscribeUploadClassified,
+  stepTranscribePollOrFail,
+  stepTranscribeSubmitOrFail,
+  stepTranscribeUploadOrFail,
 } from "@alexkroman1/aai/step-errors";
 import { countWords, formatBytes } from "@alexkroman1/aai/utils";
 
@@ -85,24 +85,24 @@ export type Transcript = {
  * expires before the next step runs; that costs one fresh upload, once, instead
  * of five.
  *
- * The `Classified` callers on `@alexkroman1/aai/step-errors` are the SDK's own
+ * The `OrFail` callers on `@alexkroman1/aai/step-errors` are the SDK's own
  * `stepTranscribe*` plus `throwStepError` and nothing else, which is what turns
  * the SDK's `TranscribeError` into the DevKit's verdict — a missing key and a
  * 400 stop, a 429 waits as long as the service asked. Every step here ends the
  * same way for the same reason.
  */
 export async function uploadToProvider(uploadId: string): Promise<{ audioUrl: string }> {
-  const stored = await uploadInfo(uploadId);
-  await report(
+  const stored = await stepUploadInfo(uploadId);
+  await stepReport(
     `Uploading ${stored.name || uploadId} (${formatBytes(stored.size)}) for transcription.`,
   );
-  return await stepTranscribeUploadClassified(uploadId);
+  return await stepTranscribeUploadOrFail(uploadId);
 }
 
 /** Create the transcription job, and answer with the id that outlives this run. */
 export async function createJob(audioUrl: string): Promise<{ id: string }> {
-  const job = await stepTranscribeSubmitClassified(audioUrl);
-  await report(`Transcribing — job ${job.id}.`);
+  const job = await stepTranscribeSubmitOrFail(audioUrl);
+  await stepReport(`Transcribing — job ${job.id}.`);
   return job;
 }
 
@@ -119,11 +119,11 @@ export async function pollTranscript(
   uploadId: string,
   id: string,
 ): Promise<{ done: false } | { done: true; transcript: Transcript }> {
-  const progress = await stepTranscribePollClassified(id);
+  const progress = await stepTranscribePollOrFail(id);
   if (!progress.done) return { done: false };
 
-  const stored = await uploadInfo(uploadId);
-  await report(`Transcribed ${countWords(progress.transcript.text)} words.`);
+  const stored = await stepUploadInfo(uploadId);
+  await stepReport(`Transcribed ${countWords(progress.transcript.text)} words.`);
   return {
     done: true,
     transcript: {

package/dist/templates/support-line/client.tsx

@@ -1,5 +1,6 @@
+import { plural } from "@alexkroman1/aai/utils";
 import "@alexkroman1/aai-ui/styles.css";
-import { AutoScroll, client, useAgentState } from "@alexkroman1/aai-ui";
+import { AutoScroll, mountClient, useAgentState } from "@alexkroman1/aai-ui";
 import { PRODUCT, supportProjection } from "./shared.ts";
 
 /**
@@ -19,7 +20,7 @@ function TraceSidebar() {
       <div>
         <h3 className="text-sm font-bold uppercase tracking-wide opacity-60">{support.product}</h3>
         <p className="text-xs opacity-50">
-          {support.asked.length} question{support.asked.length === 1 ? "" : "s"} this call
+          {support.asked.length} {plural(support.asked.length, "question")} this call
           {support.ticket ? ` · ticket ${support.ticket}` : ""}
         </p>
       </div>
@@ -97,7 +98,7 @@ function TraceSidebar() {
   );
 }
 
-client({
+mountClient({
   // Derived, not typed twice: `PRODUCT` comes off `knowledge.json`, which is
   // what `agent.ts` names the agent and greets with. A knowledge base swapped
   // for another product otherwise leaves the browser tab advertising the old

package/dist/templates/support-line/prompts.ts

@@ -40,8 +40,6 @@ export const binaryScore = z.object({
   reason: z.string().max(200).describe("One short sentence of justification"),
 });
 
-export type BinaryScore = z.infer<typeof binaryScore>;
-
 /** Their `retrieval_grader`: deliberately NOT a stringent test. */
 export const DOC_GRADER_SYSTEM = [
   "You are a grader assessing whether a retrieved support document is relevant",

package/dist/templates/transcription-workflow/agent.test.ts

@@ -20,9 +20,9 @@
 
 import { readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { readUpload, type UploadRange } from "@alexkroman1/aai/step";
+import { stepReadUpload, type UploadRange } from "@alexkroman1/aai/step";
 import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
-import { createWorkflowCtx } from "@alexkroman1/aai/testing";
+import { createWorkflowContext } from "@alexkroman1/aai/testing";
 import {
   installStubReporter,
   installStubStepFetch,
@@ -41,6 +41,7 @@ import {
   requestFormat,
 } from "./workflows/downsample.ts";
 import { cuttable, heavierThanNormalized, normalizeRecording } from "./workflows/normalize.ts";
+import { stitchChunks, stitchTranscript, TRANSCRIPT_STREAM } from "./workflows/stitch.ts";
 import {
   expectedSegments,
   nextPollDelay,
@@ -54,9 +55,6 @@ import {
 import {
   mergeTranscript,
   splitRecording,
-  stitchChunks,
-  stitchTranscript,
-  TRANSCRIPT_STREAM,
   type Transcript,
   transcribeFlow,
   transcribeSegment,
@@ -88,9 +86,9 @@ const UPLOAD_ID = "upl_test";
 const STARTED_AT = 1_000_000;
 
 /**
- * Publish one in-memory upload, the way `createServer` publishes a real store.
+ * Publish one in-memory upload, the way `createRuntimeServer` publishes a real store.
  *
- * This is the seam that makes a step testable at all: `readUpload` reads a
+ * This is the seam that makes a step testable at all: `stepReadUpload` reads a
  * process-wide slot rather than dialling anything, so a spec supplies its own
  * bytes with no server, no database and no HTTP.
  */
@@ -898,7 +896,7 @@ describe("transcribeSegment", () => {
     // What makes the run's answer streamable rather than only its narration: the
     // page stitches whatever has arrived, so the transcript renders growing
     // instead of appearing when the last segment does. The reporter is the SDK's
-    // published slot, which is the same seam `report()` goes through.
+    // published slot, which is the same seam `stepReport()` goes through.
     const reported = installStubReporter();
     stubProvider();
 
@@ -964,7 +962,7 @@ describe("transcribeSegment", () => {
     // `transcribeStreamFlow`'s own `transcribeSegment` call carries the same
     // budget and is asserted with that flow, not here — this drives only
     // `transcribeFlow`.
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       runSteps: false,
       results: {
         normalizeRecording: { recording: UPLOAD_ID, converted: false },
@@ -1116,7 +1114,7 @@ describe("the streaming flow", () => {
 
   test("segmentStored refuses a window that STRADDLES a hole", () => {
     // A run is contiguous, so containment in one is the whole test — and it has to
-    // be, because `readUpload` clamps to the run a read starts in. A segment
+    // be, because `stepReadUpload` clamps to the run a read starts in. A segment
     // spanning two runs would come back short and be transcribed as a fragment,
     // which is a wrong transcript rather than a failed one.
     const at = poll(
@@ -1191,12 +1189,12 @@ describe("the streaming flow", () => {
   });
 
   test("a segment reads SHORT rather than failing when its bytes have not landed", async () => {
-    // The property the whole flow rests on, and it predates streaming: `readUpload`
+    // The property the whole flow rests on, and it predates streaming: `stepReadUpload`
     // clamps its window to what is stored. So a body that asks slightly early gets
     // what exists — which is why the body checks `end <= size` and can trust the
     // clamp for the final segment of a file that came up short.
     publishPartial(1000, 320_000);
-    const slice = await readUpload(UPLOAD_ID, { start: 44, end: 44 + 320_000 });
+    const slice = await stepReadUpload(UPLOAD_ID, { start: 44, end: 44 + 320_000 });
     expect(slice.bytes.length).toBe(1000);
     expect(slice.end).toBe(44 + 1000);
   });
@@ -1356,6 +1354,16 @@ describe("normalizing the recording", () => {
    * later in `splitRecording` with a message about a header; a `timeout`
    * classified as fatal is a run that gives up on work that would have finished.
    */
+  // Point the toolchain at nothing, so this block really is what its doc says:
+  // a unit test that spawns no binary. Without it a developer with ffmpeg
+  // installed runs a different test from CI, which has none — and the one
+  // assertion below that reaches `normalizeRecording` is about a reporter line
+  // emitted BEFORE the spawn. `unstubEnvs` is repo-wide, so there is no teardown.
+  beforeEach(() => {
+    vi.stubEnv("AAI_FFMPEG_PATH", "/nonexistent/ffmpeg");
+    vi.stubEnv("AAI_FFPROBE_PATH", "/nonexistent/ffprobe");
+  });
+
   test("a canonical WAV is cuttable, so the desk converts nothing", () => {
     expect(cuttable(wavFile(MONO_16K, 32_000), 44 + 32_000)).toBe(true);
   });

package/dist/templates/transcription-workflow/agent.ts

@@ -40,7 +40,7 @@
  * `POST /workflows/uploads` (the browser does this for you: `uploads` below is
  * what makes `<WorkflowFields>` render a file picker, and `useWorkflowSubmit`
  * stores the file before starting the run), the input carries the returned id,
- * and each step reads exactly the window it needs with `readUpload` — which is
+ * and each step reads exactly the window it needs with `stepReadUpload` — which is
  * what keeps sixty steps from moving the same recording sixty times.
  *
  * None of that is this template's code. Uploads are the SDK's, for the reason
@@ -118,7 +118,7 @@ export const transcribe = workflow({
   }),
   // The one line that makes the form take a file: `<WorkflowFields>` renders a
   // picker for this property, `useWorkflowSubmit` stores the chosen file, and
-  // the steps read it back with `readUpload`.
+  // the steps read it back with `stepReadUpload`.
   uploads: ["recording"],
   run: transcribeFlow,
 });

package/dist/templates/transcription-workflow/client.tsx

@@ -56,7 +56,7 @@
  * rather than a fourth option. A single request moves a file at one connection's
  * throughput, which over any distance is a fraction of the link — so the SDK cuts
  * the file into megabyte-aligned parts and sends four at once. Nothing about the
- * workflow changes: the agent reassembles them, `readUpload` reads the same
+ * workflow changes: the agent reassembles them, `stepReadUpload` reads the same
  * windows, and the streaming flow still watches the file grow (what it polls is the
  * CONTIGUOUS prefix, which is honest whether one connection or four are filling
  * it).
@@ -83,7 +83,7 @@
  * - **The page stitches with the RUN's own function.** `stitchChunks` is
  *   `workflows/stitch.ts`, imported by both, so the live text and the stored one
  *   cannot drift into two different transcripts of one recording.
- * - **It is a SEPARATE stream from the progress log.** `report()`'s lines go to
+ * - **It is a SEPARATE stream from the progress log.** `stepReport()`'s lines go to
  *   the default one, which `<WorkflowProgress>` renders verbatim; objects in
  *   there would come out as `[object Object]` between the sentences.
  * - **The finished run wins.** Once `output` exists the panel renders that
@@ -193,7 +193,7 @@ import "@alexkroman1/aai-ui/styles.css";
 import {
   Form,
   isTerminal,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
   useWorkflowRuns,
@@ -270,10 +270,6 @@ function TranscriptionDesk() {
   // piece of state for all three hooks, because it describes the UPLOAD and every
   // mode has one — see the module doc.
   const [parallel, setParallel] = useState(true);
-  // Did THIS load press Transcribe? A reload cannot have, and it is the only way
-  // the page can tell "working on what you just sent" from "picking up where you
-  // left off" — the hooks report the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
   // ALL THREE hooks are called every render, because a hook may not be conditional —
   // and that costs nothing here: none of them does anything until its `submit` is
   // called, and `useWorkflowRun` underneath them holds no id until then either.
@@ -292,7 +288,13 @@ function TranscriptionDesk() {
   // store — so it is the SAME hook against a different workflow. Only the streaming
   // mode needs the other one, because only it needs the id before the bytes.
   const active = mode === "streaming" ? streamed : mode === "batch" ? batched : stored;
-  const { submitForm, run, upload, pending, error, reset, pauseUpload, resumeUpload } = active;
+  // `startedHere` comes off the ACTIVE hook rather than being one flag for the
+  // page, and that is a fix rather than a tidy-up: a single piece of page state
+  // survived a mode switch, so pressing Transcribe in one mode and then
+  // switching made the other mode's panel claim the reader had started its run.
+  // Per-hook, switching modes shows the truth about the run being shown.
+  const { submitForm, run, upload, pending, error, reset, pauseUpload, resumeUpload, startedHere } =
+    active;
   // History is per WORKFLOW, so the list follows the mode: two flows that produce
   // the same output are still two different things to have run, and merging them
   // would put a run under a heading that cannot explain it.
@@ -349,7 +351,6 @@ function TranscriptionDesk() {
       <Form
         onSubmit={(values) => {
           total.start();
-          setStartedHere(true);
           // Written at SUBMIT rather than on the radio, so the remembered mode
           // is always the mode a run exists under — which is the only thing the
           // next load can use it for.
@@ -369,8 +370,8 @@ function TranscriptionDesk() {
       </Form>
 
       <TotalLatency
-        elapsedMs={total.elapsedMs}
-        running={total.running}
+        startedAt={total.startedAt}
+        frozenMs={total.frozenMs}
         runMs={run?.status === "completed" ? run.output.elapsedMs : undefined}
       />
 
@@ -394,8 +395,8 @@ function TranscriptionDesk() {
           onClear={() => {
             // A recovered run is dismissed as deliberately as one this load
             // started: the lookup is a mount-time act, so `reset()` is not
-            // undone by a second one and Clear really does clear.
-            setStartedHere(false);
+            // undone by a second one and Clear really does clear. `reset()`
+            // also clears `startedHere`, which this page used to mirror here.
             reset();
             total.clear();
           }}
@@ -500,4 +501,4 @@ function UploadPicker({
   );
 }
 
-page({ name: "Transcription Desk", component: TranscriptionDesk });
+mountPage({ name: "Transcription Desk", component: TranscriptionDesk });

package/dist/templates/transcription-workflow/recover.ts

@@ -14,7 +14,7 @@
  * `client.tsx` down to the page's shape:
  *
  * - **A template's spec is what makes its exemplar code true**, and none of this
- *   can be tested from a `client.tsx`. That file ends in a `page()` call and
+ *   can be tested from a `client.tsx`. That file ends in a `mountPage()` call and
  *   imports a stylesheet, and this package's suites have no DOM at all: the
  *   vitest `include` matches `.test.ts` and not `.test.tsx`, and the scaffold
  *   declares no React testing library — so a `client.test.tsx` would be

package/dist/templates/transcription-workflow/run-panel.tsx

@@ -21,6 +21,7 @@
 import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
 import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
+  Facts,
   isTerminal,
   useWorkflowProgress,
   WORKFLOW_STATUS_LABELS,
@@ -136,7 +137,7 @@ export function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onCle
           above, and the reason both exist: the status is `running` for the whole
           fan-out, so a sixty-segment recording and a one-segment recording look
           identical while they run. These lines come from the run itself
-          (`report()` in `workflows/transcribe.ts`), and they REPLAY, so looking a
+          (`stepReport()` in `workflows/transcribe.ts`), and they REPLAY, so looking a
           finished run up in the panel below shows how it got there. */}
       <WorkflowProgress runId={run.runId} />
 
@@ -150,15 +151,25 @@ export function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onCle
           object with optional fields. */}
       {run.status === "completed" && (
         <>
-          <p className="text-xs opacity-60">
-            {run.output.segments} {plural(run.output.segments, "segment")} ·{" "}
-            {formatDuration(run.output.durationMs)} of audio · took{" "}
-            {formatDuration(run.output.elapsedMs)} · {run.output.words} words
-          </p>
+          <Facts
+            size="xs"
+            items={[
+              `${run.output.segments} ${plural(run.output.segments, "segment")}`,
+              `${formatDuration(run.output.durationMs)} of audio`,
+              `took ${formatDuration(run.output.elapsedMs)}`,
+              `${run.output.words} words`,
+            ]}
+          />
           <pre className="whitespace-pre-wrap text-sm leading-relaxed">{run.output.transcript}</pre>
         </>
       )}
-      {run.status === "failed" && <p className="text-red-600">{run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error in
+          `client.tsx`: this is the outcome the reader waited minutes for. */}
+      {run.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          {run.error}
+        </p>
+      )}
     </section>
   );
 }
@@ -186,17 +197,26 @@ function LiveTranscript({ runId }: { runId: string }) {
   // Memoized on the ARRAY, which the hook appends to per read: stitching is a
   // seam search per segment, and a fan-out re-renders this panel on every
   // progress poll whether or not anything arrived.
-  const transcript = useMemo(() => stitchChunks(progress), [progress]);
+  //
+  // The word count and the coverage are derived in the SAME memo, not below
+  // it: both are functions of `progress` alone, and `countWords` rescans a
+  // transcript that reaches ~14k words on a feature-length recording.
+  //
+  // `covered` is the furthest point reached, not the count: segments land out
+  // of order, so "6 segments" says nothing about how much is covered.
+  const { transcript, words, covered } = useMemo(() => {
+    const stitched = stitchChunks(progress);
+    return {
+      transcript: stitched,
+      words: countWords(stitched),
+      covered: progress.reduce((furthest, chunk) => Math.max(furthest, chunk.endMs), 0),
+    };
+  }, [progress]);
   if (progress.length === 0) return null;
 
-  // The furthest point reached, not the count: segments land out of order, so
-  // "6 segments" says nothing about how much of the recording is covered.
-  const covered = Math.max(...progress.map((chunk) => chunk.endMs));
   return (
     <div className="flex flex-col gap-2">
-      <p className="text-xs opacity-60">
-        {countWords(transcript)} words so far · through {formatDuration(covered)}
-      </p>
+      <Facts size="xs" items={[`${words} words so far`, `through ${formatDuration(covered)}`]} />
       <pre className="whitespace-pre-wrap text-sm leading-relaxed opacity-80">{transcript}</pre>
     </div>
   );

package/dist/templates/transcription-workflow/total-latency.tsx

@@ -15,6 +15,7 @@
  */
 
 import { formatDuration } from "@alexkroman1/aai/utils";
+import { Facts } from "@alexkroman1/aai-ui";
 import { useCallback, useEffect, useRef, useState } from "react";
 
 /**
@@ -29,12 +30,17 @@ const STOPWATCH_TICK_MS = 250;
 /** What {@link useTotalLatency} reports. */
 export type TotalLatency = {
   /**
-   * Milliseconds since the submit — ticking while the submission is in flight,
-   * frozen at the finish, and undefined before the first one.
+   * The mark the clock started at, or undefined before the first submit.
+   *
+   * The raw mark rather than an elapsed duration, and that is the load-bearing
+   * part: an elapsed number is stale the instant it is computed, so a page
+   * holding one has to re-render to keep it true — which is what used to drive
+   * the whole tree at 4 Hz. {@link TotalLatency} turns these two marks into a
+   * duration, and only that section re-renders.
    */
-  elapsedMs: number | undefined;
-  /** Whether the clock is still running, which is what makes the label honest. */
-  running: boolean;
+  startedAt: number | undefined;
+  /** The elapsed time at the moment the run settled, once it has. */
+  frozenMs: number | undefined;
   /** Start (or restart) the clock. Called from the form's own submit handler. */
   start: () => void;
   /** Drop it, for a panel that no longer describes the submission it timed. */
@@ -53,7 +59,10 @@ export type TotalLatency = {
  *
  * - **The interval re-renders; it does not accumulate.** The elapsed time is read
  *   from the clock at render, so a tick the tab throttled or dropped cannot make
- *   the number lag behind real time.
+ *   the number lag behind real time. The interval lives in {@link TotalLatency}
+ *   rather than here, because a hook called from the page makes its ticks the
+ *   PAGE's re-renders — the form, the upload bar, the run panel and the whole
+ *   history list, four times a second, to move one duration string.
  * - **`performance.now()`, not `Date.now()`.** It is monotonic, so a clock
  *   correction (NTP, a laptop waking up) cannot make a transcription look
  *   instant — or negative.
@@ -61,8 +70,6 @@ export type TotalLatency = {
 export function useTotalLatency(inFlight: boolean): TotalLatency {
   const [startedAt, setStartedAt] = useState<number | undefined>(undefined);
   const [frozenMs, setFrozenMs] = useState<number | undefined>(undefined);
-  // Re-render trigger only — see the doc above.
-  const [, tick] = useState(0);
   // Whether `inFlight` has been seen true since the last `start()`. Without it,
   // a start that lands one render before the submission reports itself in flight
   // would freeze the clock at zero instead of running it.
@@ -72,8 +79,7 @@ export function useTotalLatency(inFlight: boolean): TotalLatency {
     if (startedAt === undefined || frozenMs !== undefined) return;
     if (inFlight) {
       began.current = true;
-      const id = setInterval(() => tick((n) => n + 1), STOPWATCH_TICK_MS);
-      return () => clearInterval(id);
+      return;
     }
     // Measured here rather than at render, so the frozen number is the one at the
     // moment the run settled rather than whenever this page next drew.
@@ -93,8 +99,8 @@ export function useTotalLatency(inFlight: boolean): TotalLatency {
   }, []);
 
   return {
-    elapsedMs: frozenMs ?? (startedAt === undefined ? undefined : performance.now() - startedAt),
-    running: startedAt !== undefined && frozenMs === undefined,
+    startedAt,
+    frozenMs,
     start,
     clear,
   };
@@ -114,17 +120,31 @@ export function useTotalLatency(inFlight: boolean): TotalLatency {
  * notices it finished. Clamped at zero, because the two numbers come from two
  * different clocks on two different machines and a few milliseconds the wrong way
  * would otherwise print a negative.
+ *
+ * The stopwatch interval lives HERE rather than in {@link useTotalLatency}, so a
+ * running clock re-renders this section and nothing else.
  */
 export function TotalLatency({
-  elapsedMs,
-  running,
+  startedAt,
+  frozenMs,
   runMs,
 }: {
-  elapsedMs: number | undefined;
-  running: boolean;
+  startedAt: number | undefined;
+  frozenMs: number | undefined;
   runMs: number | undefined;
 }) {
-  if (elapsedMs === undefined) return null;
+  // Re-render trigger only: the elapsed time is read from the clock below, so a
+  // tick the tab throttled or dropped cannot make the number lag real time.
+  const [, tick] = useState(0);
+  const running = startedAt !== undefined && frozenMs === undefined;
+  useEffect(() => {
+    if (!running) return;
+    const id = setInterval(() => tick((n) => n + 1), STOPWATCH_TICK_MS);
+    return () => clearInterval(id);
+  }, [running]);
+
+  if (startedAt === undefined) return null;
+  const elapsedMs = frozenMs ?? performance.now() - startedAt;
   const outside = runMs === undefined ? undefined : Math.max(0, elapsedMs - runMs);
   return (
     <section className="flex flex-wrap items-baseline justify-between gap-x-4 gap-y-1 rounded-md border px-5 py-3">
@@ -134,9 +154,15 @@ export function TotalLatency({
       <span className="flex flex-wrap items-baseline gap-x-3 gap-y-1">
         <span className="text-sm tabular-nums">{formatDuration(elapsedMs)}</span>
         {runMs !== undefined && outside !== undefined && (
-          <span className="text-xs tabular-nums opacity-60">
-            {formatDuration(outside)} before the run · {formatDuration(runMs)} inside it
-          </span>
+          <Facts
+            size="xs"
+            as="span"
+            className="tabular-nums"
+            items={[
+              `${formatDuration(outside)} before the run`,
+              `${formatDuration(runMs)} inside it`,
+            ]}
+          />
         )}
       </span>
     </section>