@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/templates/spoken-summary/agent.test.ts

@@ -17,9 +17,9 @@
  * its return value, and audio in one is megabytes replayed on every resume.
  */
 
-import { readUpload, uploadInfo } from "@alexkroman1/aai/step";
+import { stepReadUpload, stepUploadInfo } from "@alexkroman1/aai/step";
 import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
-import { createWorkflowCtx, stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { createWorkflowContext, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -215,14 +215,14 @@ describe("speaking", () => {
 
     const { audio } = await speak("Hello.");
 
-    await expect(uploadInfo(audio)).resolves.toMatchObject({
+    await expect(stepUploadInfo(audio)).resolves.toMatchObject({
       name: "summary.wav",
       // The byte route serves this as `Content-Type`, and a browser will not
       // play inline a file it was handed as octet-stream.
       type: "audio/wav",
       size: 44 + 4000,
     });
-    const { bytes } = await readUpload(audio, { end: 12 });
+    const { bytes } = await stepReadUpload(audio, { end: 12 });
     expect(String.fromCharCode(...bytes.subarray(0, 4))).toBe("RIFF");
     expect(String.fromCharCode(...bytes.subarray(8, 12))).toBe("WAVE");
   });
@@ -292,7 +292,7 @@ describe("the whole run", () => {
     installStubReporter();
     installStubSpeech();
 
-    const summary = await spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowCtx());
+    const summary = await spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowContext());
 
     expect(summary).toEqual({
       source: "standup.wav",
@@ -314,7 +314,7 @@ describe("the whole run", () => {
     installStubReporter();
     const speech = installStubSpeech();
 
-    await spokenSummaryFlow({ recording: UPLOAD_ID, voice: "michael" }, createWorkflowCtx());
+    await spokenSummaryFlow({ recording: UPLOAD_ID, voice: "michael" }, createWorkflowContext());
 
     expect(speech.calls[0]).toMatchObject({ text: "Spoken.", voice: "michael" });
   });
@@ -324,9 +324,9 @@ describe("the whole run", () => {
     installStubReporter();
     installStubSpeech();
 
-    await expect(spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowCtx())).rejects.toThrow(
-      "corrupt audio",
-    );
+    await expect(
+      spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowContext()),
+    ).rejects.toThrow("corrupt audio");
   });
 });
 

package/dist/templates/spoken-summary/agent.ts

@@ -24,7 +24,7 @@
  *   event stream wired into a live pipeline's playback, with a turn tracker and
  *   barge-in behind it, and a step has no turn to be part of and has to return
  *   a VALUE.
- * - **`writeUpload`** (same subpath) puts that value where a browser can reach
+ * - **`stepWriteUpload`** (same subpath) puts that value where a browser can reach
  *   it. 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.
@@ -54,7 +54,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 the step that needs the bytes streams them out with `readUpload`.
+ * and the step that needs the bytes streams them out with `stepReadUpload`.
  *
  * ## It is scriptable, which is the other half of having an API
  *
@@ -140,7 +140,7 @@ export const spokenSummary: WorkflowDef<typeof spokenSummaryInput, SpokenSummary
   input: spokenSummaryInput,
   // The one line that makes the form take a file: `<WorkflowFields>` renders a
   // picker for this property, `useWorkflowSubmit` stores the chosen file, and
-  // the step that transcribes it reads it back with `readUpload`.
+  // the step that transcribes it reads it back with `stepReadUpload`.
   uploads: ["recording"],
   run: spokenSummaryFlow,
 });

package/dist/templates/spoken-summary/client.tsx

@@ -69,9 +69,11 @@ import "@alexkroman1/aai-ui/styles.css";
 // `workflows/summarize.ts` already declares.
 import { formatDuration } from "@alexkroman1/aai/utils";
 import {
+  BulletList,
   createWorkflowApi,
+  Facts,
   Form,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
@@ -79,7 +81,6 @@ import {
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { spokenSummary } from "./agent.ts";
 
 /**
@@ -128,16 +129,11 @@ function captionsUrl(text: string, durationMs: number): string {
 }
 
 export function App() {
-  // Did THIS load start the run? A reload cannot have, and that is the only way
-  // the page can tell "working on what you just sent" from "picking up where
-  // you left off" — the hook reports the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`. The reload is the hook's own doing — see
   // the module doc for why the key it mints is the right one for this page.
-  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
-    typeof spokenSummary
-  >(WORKFLOW, { api });
+  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error, startedHere } =
+    useWorkflowSubmit<typeof spokenSummary>(WORKFLOW, { api });
   const output = run?.status === "completed" ? run.output : undefined;
   // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
   // bytes have to be FETCHED and handed to the element as an object URL — and the
@@ -153,14 +149,7 @@ export function App() {
         </p>
       </header>
 
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submitForm(values);
-        }}
-        error={error}
-        className="flex flex-col gap-4"
-      >
+      <Form onSubmit={(values) => submitForm(values)} error={error} className="flex flex-col gap-4">
         {/* Every control, from the workflow's own input schema. See the module doc. */}
         <WorkflowFields workflow={WORKFLOW} />
         <SubmitButton pending={pending} pendingLabel="Working…">
@@ -180,25 +169,27 @@ export function App() {
           nothing for `<WorkflowProgress>` to read. */}
       <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
 
-      {/* What the run itself says, from `report()` in the workflow's steps. */}
+      {/* What the run itself says, from `stepReport()` in the workflow's steps. */}
       <WorkflowProgress runId={run?.runId} api={api} />
 
-      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error: this
+          is the outcome the reader waited minutes for. */}
+      {run?.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          That one failed: {run.error}
+        </p>
+      )}
 
       {output !== undefined && (
         <article className="flex flex-col gap-5">
           <div className="flex flex-col gap-1">
             <h2 className="text-xl">{output.headline}</h2>
-            <p className="text-sm opacity-70">
-              {output.source} · {formatDuration(output.durationMs)} · {output.words} words
-            </p>
+            <Facts
+              items={[output.source, formatDuration(output.durationMs), `${output.words} words`]}
+            />
           </div>
 
-          <ul className="flex list-disc flex-col gap-1 pl-5">
-            {output.points.map((point) => (
-              <li key={point}>{point}</li>
-            ))}
-          </ul>
+          <BulletList items={output.points} />
 
           <section className="flex flex-col gap-2">
             <h3 className="text-sm font-medium opacity-70">
@@ -206,11 +197,13 @@ export function App() {
             </h3>
             {audio.pending && <p className="text-sm opacity-70">Fetching the audio…</p>}
             {audio.error !== undefined && (
-              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+              <p role="alert" className="text-red-600">
+                Could not load the audio: {audio.error}
+              </p>
             )}
             {audio.url !== undefined && (
               <>
-                <audio controls src={audio.url} className="w-full">
+                <audio aria-label="Summary read aloud" controls src={audio.url} className="w-full">
                   {/* A real caption track, not a suppression: the summary was
                       written before it was spoken, so the words are already
                       here and one cue spanning the clip is an honest
@@ -244,4 +237,4 @@ export function App() {
   );
 }
 
-page({ name: "Spoken Summary", component: App });
+mountPage({ name: "Spoken Summary", component: App });

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/agent.ts

@@ -24,4 +24,12 @@ export default agent({
   // caller's callback number, and only its reference crosses to the browser.
   syncState: supportProjection,
   greeting: `${PRODUCT} support, you're through to the automated line. What's happened?`,
+  // A support line is a PHONE line, so this one declares the carrier its number
+  // is with. Nothing serves `WS /phone` without this — the route is an
+  // allow-list, and an agent that says nothing about carriers answers none — so
+  // point a Twilio number's webhook at the deployed agent's `/phone` and the
+  // call lands in an ordinary session. `true` admits every carrier the runtime
+  // ships a codec for; a list is the narrower statement, and it is the one to
+  // copy.
+  telephony: ["twilio"],
 });

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