@alexkroman1/aai-cli 13.2.0 → 14.0.0

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.
  */
@@ -143,15 +141,19 @@ function wavFile(
   return head;
 }
 
-describe("the agent declares its three workflows and nothing else", () => {
+describe("the agent declares its three workflows", () => {
   test("under the names the REST route resolves them by", () => {
     // The page starts a run by these strings, so a rename is a runtime 400 rather
     // than a compile error — which is what makes pinning them worth a test.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual([
-      "transcribe",
-      "transcribeStream",
-      "transcribeBatch",
-    ]);
+    // `arrayContaining` rather than an exact key list: a fourth desk of your own
+    // is an invited edit and must not redden a test you did not write. These
+    // three NAMES stay pinned, deliberately — the page starts a run by each
+    // string, so renaming one is a runtime 400 rather than a compile error, and
+    // this is the only thing that says so. Rename here and in `client.tsx`
+    // together.
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(
+      expect.arrayContaining(["transcribe", "transcribeStream", "transcribeBatch"]),
+    );
     expect(agentDef.workflows?.transcribe).toBe(transcribe);
     expect(agentDef.workflows?.transcribeStream).toBe(transcribeStream);
     expect(agentDef.workflows?.transcribeBatch).toBe(transcribeBatch);
@@ -168,8 +170,12 @@ describe("the agent declares its three workflows and nothing else", () => {
   });
 
   test("with no tools, because the interface is the page and the API", () => {
-    // The point of the template: a workflow app needs no conversation. A tool
-    // reappearing here would mean the voice path had crept back in.
+    // A PIN, deliberately, and the one assertion in this file you are expected
+    // to edit rather than satisfy. `workflowApp()` declares no session, so a
+    // tool has no conversation to be called from — a name appearing here means
+    // the voice path crept back in and the tool will never run. If you want a
+    // voice agent that STARTS a workflow, `research-workflow` is that template,
+    // and this line is what tells you you are on the wrong one.
     expect(Object.keys(agentDef.tools ?? {})).toEqual([]);
   });
 
@@ -890,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();
 
@@ -956,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 },
@@ -1108,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(
@@ -1183,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);
   });
@@ -1348,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
@@ -153,15 +153,17 @@
  * ## A reload keeps two of the three runs, and the third CANNOT be kept
  *
  * The run id lives in React state, so a refresh loses it while the fan-out
- * carries on. `key` is the handle that survives that and `recover: true` is what
- * reads it back — and here it is a decision PER MODE rather than per page:
+ * carries on. A correlation KEY is the handle that survives that, and
+ * `useWorkflowSubmit` keeps one and asks for its newest run on mount — which
+ * here lands differently PER MODE:
  *
  * - **"After it uploads"** and **"Let the provider do it"** recover. Their input
  *   names a recording that is already stored, so a later load adopting the run
  *   is adopting something complete: the transcript arrives, the progress log
  *   replays, and nobody is asked to send a 600 MB file a second time.
  * - **"While it uploads" does not, and the hook REFUSES the option rather than
- *   ignoring it.** That run's input names an upload id this page load minted and
+ *   ignoring it** — `useWorkflowStream` omits `recover` from its options type
+ *   and mints no key. That run's input names an upload id this page load minted and
  *   is still filling, so a later load could only adopt a run waiting for bytes
  *   nobody is sending — and it is worse than useless: `workflows/stream.ts`
  *   fails a run whose upload stops growing (`MAX_IDLE_POLLS`), so the reload
@@ -171,10 +173,11 @@
  * The MODE is remembered too, and that is not decoration: without it a reload
  * opens on the default flow while the recovered run sits behind a radio nobody
  * pressed, so the reader sees an empty form and starts a second run — the exact
- * thing the key exists to prevent. The KEY is `useRunKey()`, which owns the
- * minting, the storage and the argument for the key being opaque rather than a
- * `?key=` parameter; `recover.ts` owns the mode, which is this page's own
- * concept, and the validation on the way back out of storage that turning a
+ * thing the key exists to prevent. The KEY is the hook's own — `use-run-key.ts`
+ * owns the minting, the storage and the argument for it being opaque rather
+ * than a `?key=` parameter, and the two submit hooks here share one because the
+ * slot is keyed by the PAGE; `recover.ts` owns the mode, which is this page's
+ * own concept, and the validation on the way back out of storage that turning a
  * stored string into a workflow name obliges.
  *
  * Two smaller consequences worth knowing. Both recovering hooks look up on
@@ -190,10 +193,9 @@ import "@alexkroman1/aai-ui/styles.css";
 import {
   Form,
   isTerminal,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
-  useRunKey,
   useWorkflowRuns,
   useWorkflowStream,
   useWorkflowSubmit,
@@ -268,38 +270,31 @@ 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);
-  // This tab's handle on its own runs — minted once and remembered, which is
-  // what a later load produces to find the run again.
-  const key = useRunKey();
-  // 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.
   //
-  // `recover` is a constant `true` on the two that take it rather than
-  // `mode === …`: the lookup is a MOUNT-time act, so arming it when a mode is
-  // picked would re-adopt a run the reader had just cleared. The streaming hook
-  // takes neither half — it refuses `recover` by type, and recording a key it
-  // will never read back would be config nothing uses.
+  // The two submit hooks recover unconditionally rather than on `mode === …`:
+  // the lookup is a MOUNT-time act, so arming it when a mode is picked would
+  // re-adopt a run the reader had just cleared. They share ONE key without
+  // saying so — the hook's slot is keyed by the page — and `find` is scoped by
+  // workflow as well as by key, so the two modes recover separate runs. The
+  // streaming hook has neither half: it refuses `recover` by type, and mints no
+  // key it would never read back.
   const streamed = useWorkflowStream<typeof transcribe>(WORKFLOWS.streaming, { parallel });
-  const stored = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.classic, {
-    parallel,
-    key,
-    recover: true,
-  });
-  const batched = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.batch, {
-    parallel,
-    key,
-    recover: true,
-  });
+  const stored = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.classic, { parallel });
+  const batched = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.batch, { parallel });
   // The batch flow uploads the same way the classic one does — the id comes from the
   // 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.
@@ -356,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.
@@ -376,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}
       />
 
@@ -401,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();
           }}
@@ -507,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>

package/dist/templates/transcription-workflow/workflows/batch.ts

@@ -53,12 +53,12 @@
  * request rather than two and the value journaled by the last poll IS the result.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { report, TRANSCRIBE_API, uploadInfo } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { stepReport, stepUploadInfo, TRANSCRIBE_API } from "@alexkroman1/aai/step";
 import {
-  stepTranscribePollClassified,
-  stepTranscribeSubmitClassified,
-  stepTranscribeUploadClassified,
+  stepTranscribePollOrFail,
+  stepTranscribeSubmitOrFail,
+  stepTranscribeUploadOrFail,
 } from "@alexkroman1/aai/step-errors";
 import { countWords, formatBytes } from "@alexkroman1/aai/utils";
 import type { Transcript } from "./transcribe.ts";
@@ -78,7 +78,7 @@ const MAX_POLLS = 360;
 /** Transcribe a recording through the async API. */
 export async function transcribeBatchFlow(
   input: { recording: string },
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<Transcript> {
   // Both at once: the clock does not depend on the upload, and issuing them
   // together costs one round trip instead of two before a byte moves. Their issue
@@ -122,24 +122,24 @@ export async function transcribeBatchFlow(
  * far smaller: if it expires before the next step runs, the run fails and a fresh one
  * re-uploads — which is what would have happened anyway, once, instead of five times.
  *
- * 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)}) to the async API.`,
   );
-  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(`Submitted — job ${job.id}.`);
+  const job = await stepTranscribeSubmitOrFail(audioUrl);
+  await stepReport(`Submitted — job ${job.id}.`);
   return job;
 }
 
@@ -156,13 +156,13 @@ export async function pollTranscript(
   id: string,
   startedAt: number,
 ): Promise<{ done: false } | { done: true; transcript: Transcript }> {
-  const progress = await stepTranscribePollClassified(id);
+  const progress = await stepTranscribePollOrFail(id);
   if (!progress.done) {
-    await report(`Transcript ${id} is ${progress.status}.`);
+    await stepReport(`Transcript ${id} is ${progress.status}.`);
     return { done: false };
   }
 
-  const stored = await uploadInfo(uploadId);
+  const stored = await stepUploadInfo(uploadId);
   const transcript = progress.transcript.text;
   return {
     done: true,

package/dist/templates/transcription-workflow/workflows/downsample.ts

@@ -152,7 +152,7 @@ export function downsampleSegment(
   const bind = sampleReaderFor(from);
   const frame = blockAlign(from);
   const inFrames = Math.floor(bytes.length / frame);
-  // A CALLER ERROR, and stated as one. `readUpload` clamps a window to what is
+  // A CALLER ERROR, and stated as one. `stepReadUpload` clamps a window to what is
   // stored, so the streaming flow can hand a short read down here; with no whole
   // frame the averaging window below is zero wide, `total / 0` is `NaN`, and
   // `setInt16` writes that as a 0 — a two-byte WAV of silence, transcribed and