@plaintake/scenario 1.12.0 → 1.14.0

package/dist/index.js

@@ -274,37 +274,73 @@ var BundleManifestSchema = z4.object({
   )
 });
 
-// ../schema/src/render-plan.ts
+// ../schema/src/narration-index.ts
 import { z as z5 } from "zod";
-var CueSchema = z5.object({
+var NARRATION_INDEX_SCHEMA = "agent-demo.narration-index/v1";
+var NarrationIndexClipSchema = z5.object({
+  /** The step id, which is also the clip id and the cache filename stem. */
   id: z5.string().min(1),
-  startMs: z5.number().int().nonnegative(),
-  endMs: z5.number().int().positive(),
-  lines: z5.array(z5.string()).min(1).max(2)
+  /**
+   * The marker-free, normalised line — `clipFor`'s `text`. Never empty: the runtime does not call
+   * the narrator for a step that normalises to nothing, so an empty line here is a corrupt index.
+   */
+  text: z5.string().min(1),
+  /**
+   * The author's `[pause]` segments, present only when a marker actually split the line — which is
+   * two or more pieces, never one. When present it is what the cache key is built from (the pieces
+   * join by NUL), so it must round-trip exactly or a warmed marked line lands under a different key
+   * from the one the recording will look for.
+   */
+  breaks: z5.array(z5.string().min(1)).min(2).optional(),
+  /**
+   * The resolved voice, present only when it was not the run's default (`speech.voice` below).
+   * Absent means "spoken by the default", exactly as it does on the frozen plan's per-clip voice.
+   */
+  voice: z5.string().min(1).optional()
 });
-var HEX_COLOUR = z5.string().regex(/^#[0-9A-Fa-f]{6}$/, "must be a #RRGGBB colour");
-var OutroSchema = z5.object({
-  durationMs: z5.number().int().positive().max(15e3),
-  lines: z5.array(z5.string().min(1)).min(1).max(2),
+var NarrationIndexSchema = z5.object({
+  schema: z5.literal(NARRATION_INDEX_SCHEMA),
+  speech: z5.object({
+    voice: z5.string().min(1),
+    voices: z5.array(z5.string().min(1)).optional(),
+    speed: z5.number().positive(),
+    dtype: z5.string().min(1),
+    pronunciations: z5.record(z5.string().min(1), z5.string()).optional()
+  }),
+  clips: z5.array(NarrationIndexClipSchema).min(1)
+});
+
+// ../schema/src/render-plan.ts
+import { z as z6 } from "zod";
+var CueSchema = z6.object({
+  id: z6.string().min(1),
+  startMs: z6.number().int().nonnegative(),
+  endMs: z6.number().int().positive(),
+  lines: z6.array(z6.string()).min(1).max(2)
+});
+var HEX_COLOUR = z6.string().regex(/^#[0-9A-Fa-f]{6}$/, "must be a #RRGGBB colour");
+var OutroSchema = z6.object({
+  durationMs: z6.number().int().positive().max(15e3),
+  lines: z6.array(z6.string().min(1)).min(1).max(2),
   backgroundColor: HEX_COLOUR,
   textColor: HEX_COLOUR,
-  assPath: z5.literal("captions/outro.ass")
+  assPath: z6.literal("captions/outro.ass")
 });
-var IntroSchema = z5.object({
-  durationMs: z5.number().int().positive().max(15e3),
-  lines: z5.array(z5.string().min(1)).min(1).max(2),
+var IntroSchema = z6.object({
+  durationMs: z6.number().int().positive().max(15e3),
+  lines: z6.array(z6.string().min(1)).min(1).max(2),
   backgroundColor: HEX_COLOUR,
   textColor: HEX_COLOUR,
-  assPath: z5.literal("captions/intro.ass")
+  assPath: z6.literal("captions/intro.ass")
 });
-var ChapterMarkSchema = z5.object({
-  startMs: z5.number().int().nonnegative(),
-  endMs: z5.number().int().positive(),
-  title: z5.string().min(1)
+var ChapterMarkSchema = z6.object({
+  startMs: z6.number().int().nonnegative(),
+  endMs: z6.number().int().positive(),
+  title: z6.string().min(1)
 });
-var ChaptersSchema = z5.object({
-  metadataPath: z5.literal("render/chapters.ffmetadata"),
-  marks: z5.array(ChapterMarkSchema).min(1)
+var ChaptersSchema = z6.object({
+  metadataPath: z6.literal("render/chapters.ffmetadata"),
+  marks: z6.array(ChapterMarkSchema).min(1)
 }).refine(
   ({ marks }) => marks[0]?.startMs === 0 && marks.every(
     (mark, index) => mark.endMs > mark.startMs && (index === 0 || marks[index - 1]?.endMs === mark.startMs)
@@ -317,14 +353,14 @@ var ChaptersSchema = z5.object({
     path: ["marks"]
   }
 );
-var CursorPointSchema = z5.object({
-  id: z5.string().min(1),
-  x: z5.number().int().min(0).max(1920),
-  y: z5.number().int().min(0).max(1080),
-  arriveMs: z5.number().int().nonnegative(),
-  departMs: z5.number().int().nonnegative(),
-  action: z5.enum(["click", "type", "point"]),
-  rippleMs: z5.number().int().nonnegative().optional(),
+var CursorPointSchema = z6.object({
+  id: z6.string().min(1),
+  x: z6.number().int().min(0).max(1920),
+  y: z6.number().int().min(0).max(1080),
+  arriveMs: z6.number().int().nonnegative(),
+  departMs: z6.number().int().nonnegative(),
+  action: z6.enum(["click", "type", "point"]),
+  rippleMs: z6.number().int().nonnegative().optional(),
   /**
    * Size-correction percent, applied by the emitter with `\fscx`/`\fscy`, so the arrow
    * stays one size on screen whatever the frame does to it between the cursor filter and
@@ -355,11 +391,11 @@ var CursorPointSchema = z5.object({
    * always did — so a cursor bundle from before the camera, or from before the letterbox,
    * still parses and regenerates byte-for-byte.
    */
-  scale: z5.number().int().min(1).max(400).optional()
+  scale: z6.number().int().min(1).max(400).optional()
 });
-var CursorSchema = z5.object({
-  assPath: z5.literal("captions/cursor.ass"),
-  points: z5.array(CursorPointSchema).min(1)
+var CursorSchema = z6.object({
+  assPath: z6.literal("captions/cursor.ass"),
+  points: z6.array(CursorPointSchema).min(1)
 }).refine(
   ({ points }) => points.every(
     (point, index) => point.arriveMs <= point.departMs && (point.rippleMs === void 0 || point.rippleMs >= point.arriveMs) && (index === 0 || points[index - 1].departMs <= point.arriveMs && points[index - 1].arriveMs < point.arriveMs)
@@ -372,18 +408,18 @@ var CursorSchema = z5.object({
     path: ["points"]
   }
 );
-var CameraShotSchema = z5.object({
-  id: z5.string().min(1),
-  enterMs: z5.number().int().nonnegative(),
-  holdFromMs: z5.number().int().nonnegative(),
-  x: z5.number().int().min(0),
-  y: z5.number().int().min(0),
-  w: z5.number().int().positive(),
-  h: z5.number().int().positive()
+var CameraShotSchema = z6.object({
+  id: z6.string().min(1),
+  enterMs: z6.number().int().nonnegative(),
+  holdFromMs: z6.number().int().nonnegative(),
+  x: z6.number().int().min(0),
+  y: z6.number().int().min(0),
+  w: z6.number().int().positive(),
+  h: z6.number().int().positive()
 });
-var CameraSchema = z5.object({
-  commandPath: z5.literal("render/camera.cmd"),
-  shots: z5.array(CameraShotSchema).min(1)
+var CameraSchema = z6.object({
+  commandPath: z6.literal("render/camera.cmd"),
+  shots: z6.array(CameraShotSchema).min(1)
 }).refine(
   ({ shots }) => shots.every(
     (shot) => shot.x % 2 === 0 && shot.y % 2 === 0 && // Implied by the %32 and 9w/16 rules below; kept so a future relaxation of
@@ -411,39 +447,39 @@ var CameraSchema = z5.object({
     path: ["shots"]
   }
 );
-var ActorSchema = z5.object({
-  id: z5.string().min(1),
-  label: z5.string().min(1)
+var ActorSchema = z6.object({
+  id: z6.string().min(1),
+  label: z6.string().min(1)
 });
-var SegmentSchema = z5.object({
-  id: z5.string().min(1),
-  actorId: z5.string().min(1),
-  startMs: z5.number().int().nonnegative(),
-  endMs: z5.number().int().positive()
+var SegmentSchema = z6.object({
+  id: z6.string().min(1),
+  actorId: z6.string().min(1),
+  startMs: z6.number().int().nonnegative(),
+  endMs: z6.number().int().positive()
 });
-var TransitionCardSchema = z5.object({
-  fromActorId: z5.string().min(1),
-  toActorId: z5.string().min(1),
-  durationMs: z5.number().int().positive().max(15e3),
-  lines: z5.array(z5.string().min(1)).min(1).max(2),
+var TransitionCardSchema = z6.object({
+  fromActorId: z6.string().min(1),
+  toActorId: z6.string().min(1),
+  durationMs: z6.number().int().positive().max(15e3),
+  lines: z6.array(z6.string().min(1)).min(1).max(2),
   backgroundColor: HEX_COLOUR,
   textColor: HEX_COLOUR,
-  assPath: z5.string().regex(/^captions\/turn-[0-9]+\.ass$/)
+  assPath: z6.string().regex(/^captions\/turn-[0-9]+\.ass$/)
 });
-var ExplainSegmentPlanSchema = z5.object({
-  id: z5.string().min(1),
-  segmentPath: z5.string().regex(/^explain\/[a-z0-9][a-z0-9-]*\/segment\.mp4$/),
-  durationMs: z5.number().int().positive()
+var ExplainSegmentPlanSchema = z6.object({
+  id: z6.string().min(1),
+  segmentPath: z6.string().regex(/^explain\/[a-z0-9][a-z0-9-]*\/segment\.mp4$/),
+  durationMs: z6.number().int().positive()
 });
-var HighlightRectSchema = z5.object({
-  id: z5.string().min(1),
-  x: z5.number().int().min(0),
-  y: z5.number().int().min(0),
-  width: z5.number().int().positive(),
-  height: z5.number().int().positive(),
-  startMs: z5.number().int().nonnegative(),
-  endMs: z5.number().int().positive(),
-  label: z5.string().min(1).optional(),
+var HighlightRectSchema = z6.object({
+  id: z6.string().min(1),
+  x: z6.number().int().min(0),
+  y: z6.number().int().min(0),
+  width: z6.number().int().positive(),
+  height: z6.number().int().positive(),
+  startMs: z6.number().int().nonnegative(),
+  endMs: z6.number().int().positive(),
+  label: z6.string().min(1).optional(),
   /**
    * The rect the spotlight glides *from*, when this window's cutout should animate rather
    * than cut straight to the held `x`/`y`/`width`/`height` — the pre-reveal position a
@@ -455,11 +491,11 @@ var HighlightRectSchema = z5.object({
    * whole span — so every plan frozen before this field existed, and every window a future
    * derivation decides not to glide, is unaffected by construction.
    */
-  from: z5.object({
-    x: z5.number().int().min(0),
-    y: z5.number().int().min(0),
-    width: z5.number().int().positive(),
-    height: z5.number().int().positive()
+  from: z6.object({
+    x: z6.number().int().min(0),
+    y: z6.number().int().min(0),
+    width: z6.number().int().positive(),
+    height: z6.number().int().positive()
   }).optional(),
   /**
    * The absolute video-ms at which the glide from `from` completes and the spotlight
@@ -468,7 +504,7 @@ var HighlightRectSchema = z5.object({
    * has to be real time left to glide across) and no later than `endMs` (the window
    * cannot settle after it has already closed).
    */
-  settleMs: z5.number().int().positive().optional()
+  settleMs: z6.number().int().positive().optional()
 }).refine(({ x, y, width, height }) => x + width <= 1920 && y + height <= 1080, {
   // Unlike CameraShotSchema's crop window, a highlight rect is drawn by libass, not fed to
   // `crop` — there is no yuv420p even-pixel rule to enforce — but it still has to fit the
@@ -498,9 +534,9 @@ var HighlightRectSchema = z5.object({
   message: "settleMs must be strictly after startMs and no later than endMs",
   path: ["settleMs"]
 });
-var HighlightSchema = z5.object({
-  assPath: z5.literal("captions/highlight.ass"),
-  rects: z5.array(HighlightRectSchema).min(1)
+var HighlightSchema = z6.object({
+  assPath: z6.literal("captions/highlight.ass"),
+  rects: z6.array(HighlightRectSchema).min(1)
 }).refine(
   ({ rects }) => rects.every(
     (rect, index) => rect.endMs > rect.startMs && (index === 0 || rects[index - 1].endMs <= rect.startMs)
@@ -510,8 +546,8 @@ var HighlightSchema = z5.object({
     path: ["rects"]
   }
 );
-var SpeechClipSchema = z5.object({
-  id: z5.string().min(1),
+var SpeechClipSchema = z6.object({
+  id: z6.string().min(1),
   /*
    * Bundle-relative and unescapable by construction: no slash, no leading dot, so `..` and
    * an absolute path are both unrepresentable. The renderer's `assertBundleRelative` says
@@ -525,10 +561,10 @@ var SpeechClipSchema = z5.object({
    * character the recorder could have replaced. `narration.test.ts` asserts the two agree on a
    * table of candidates, because a comment cannot.
    */
-  path: z5.string().regex(/^speech\/clips\/[A-Za-z0-9][A-Za-z0-9._-]*\.wav$/),
-  atMs: z5.number().int().nonnegative(),
-  durationMs: z5.number().int().positive(),
-  source: z5.enum(["synth", "file", "explain"]),
+  path: z6.string().regex(/^speech\/clips\/[A-Za-z0-9][A-Za-z0-9._-]*\.wav$/),
+  atMs: z6.number().int().nonnegative(),
+  durationMs: z6.number().int().positive(),
+  source: z6.enum(["synth", "file", "explain"]),
   /*
    * Which voice synthesised this clip, when it was not the plan-wide default that
    * `engine.voice` names. Absent on every clip of a one-voice recording and on every
@@ -544,16 +580,16 @@ var SpeechClipSchema = z5.object({
    * Optional and additive: every bundle frozen before per-step voices existed carries no
    * `voice` on any clip and must keep verifying, which is what `optional()` buys.
    */
-  voice: z5.string().min(1).optional()
+  voice: z6.string().min(1).optional()
 });
-var SpeechEngineSchema = z5.object({
-  name: z5.string().min(1),
-  version: z5.string().min(1),
-  modelSha256: z5.string().regex(/^[0-9a-f]{64}$/),
-  voice: z5.string().min(1)
+var SpeechEngineSchema = z6.object({
+  name: z6.string().min(1),
+  version: z6.string().min(1),
+  modelSha256: z6.string().regex(/^[0-9a-f]{64}$/),
+  voice: z6.string().min(1)
 });
-var SpeechSchema = z5.object({
-  trackPath: z5.literal("speech/narration.wav"),
+var SpeechSchema = z6.object({
+  trackPath: z6.literal("speech/narration.wav"),
   /*
    * 24 kHz mono, because that is what Kokoro emits and nothing on this path resamples.
    * Written as literals rather than imported from `@plaintake/audio`, which owns the
@@ -561,9 +597,9 @@ var SpeechSchema = z5.object({
    * be the cycle `no-circular` refuses. `packages/audio/src/wav.test.ts` asserts the two
    * agree, since a comment cannot.
    */
-  sampleRate: z5.literal(24e3),
-  channels: z5.literal(1),
-  clips: z5.array(SpeechClipSchema).min(1),
+  sampleRate: z6.literal(24e3),
+  channels: z6.literal(1),
+  clips: z6.array(SpeechClipSchema).min(1),
   engine: SpeechEngineSchema.optional()
 }).refine(
   ({ clips }) => new Set(clips.map((clip) => clip.id)).size === clips.length && clips.every(
@@ -589,14 +625,14 @@ var SpeechSchema = z5.object({
   message: "engine must be recorded whenever any clip was synthesised",
   path: ["engine"]
 });
-var ThemeSchema = z5.object({ accentColor: HEX_COLOUR });
+var ThemeSchema = z6.object({ accentColor: HEX_COLOUR });
 var RENDER_PLAN_SCHEMA = "agent-demo.render/v1";
-var RenderPlanSchema = z5.object({
-  schema: z5.literal(RENDER_PLAN_SCHEMA),
-  source: z5.object({
-    path: z5.literal("raw/session.webm"),
-    sha256: z5.string().regex(/^[0-9a-f]{64}$/),
-    durationMs: z5.number().int().nonnegative()
+var RenderPlanSchema = z6.object({
+  schema: z6.literal(RENDER_PLAN_SCHEMA),
+  source: z6.object({
+    path: z6.literal("raw/session.webm"),
+    sha256: z6.string().regex(/^[0-9a-f]{64}$/),
+    durationMs: z6.number().int().nonnegative()
   }),
   /**
    * The frame. **Three geometries live here and they are not the same thing**, which is the
@@ -658,17 +694,17 @@ var RenderPlanSchema = z5.object({
    * one would be backwards — a plan is frozen once and rendered later, so both belong at the
    * parse, not at the encode.
    */
-  video: z5.object({
-    width: z5.number().int().positive().multipleOf(2),
-    height: z5.number().int().positive().multipleOf(2),
-    fps: z5.literal(30),
-    pixelFormat: z5.literal("yuv420p"),
-    capture: z5.object({ width: z5.literal(1920), height: z5.literal(1080) }).default({ width: 1920, height: 1080 }),
-    letterbox: z5.object({
-      width: z5.number().int().positive().multipleOf(2),
-      height: z5.number().int().positive().multipleOf(2),
-      x: z5.number().int().nonnegative().multipleOf(2),
-      y: z5.number().int().nonnegative().multipleOf(2),
+  video: z6.object({
+    width: z6.number().int().positive().multipleOf(2),
+    height: z6.number().int().positive().multipleOf(2),
+    fps: z6.literal(30),
+    pixelFormat: z6.literal("yuv420p"),
+    capture: z6.object({ width: z6.literal(1920), height: z6.literal(1080) }).default({ width: 1920, height: 1080 }),
+    letterbox: z6.object({
+      width: z6.number().int().positive().multipleOf(2),
+      height: z6.number().int().positive().multipleOf(2),
+      x: z6.number().int().nonnegative().multipleOf(2),
+      y: z6.number().int().nonnegative().multipleOf(2),
       /**
        * The fill for everything the box does not cover. `#RRGGBB` for the reason
        * `OutroSchema`'s colours are: the value reaches an FFmpeg filtergraph, and that
@@ -691,8 +727,8 @@ var RenderPlanSchema = z5.object({
      * With no intro it is exactly what it always was, which is what keeps a plan without
      * one byte-identical to what earlier versions wrote.
      */
-    durationMs: z5.number().int().positive(),
-    tailPadMs: z5.number().int().nonnegative()
+    durationMs: z6.number().int().positive(),
+    tailPadMs: z6.number().int().nonnegative()
   }).refine(
     ({ width, height, letterbox }) => letterbox === void 0 || letterbox.x + letterbox.width <= width && letterbox.y + letterbox.height <= height,
     {
@@ -706,12 +742,12 @@ var RenderPlanSchema = z5.object({
       path: ["letterbox"]
     }
   ),
-  captions: z5.object({
-    language: z5.string().min(2),
-    srtPath: z5.literal("captions/captions.srt"),
-    vttPath: z5.literal("captions/captions.vtt"),
-    assPath: z5.literal("captions/captions.ass"),
-    cues: z5.array(CueSchema)
+  captions: z6.object({
+    language: z6.string().min(2),
+    srtPath: z6.literal("captions/captions.srt"),
+    vttPath: z6.literal("captions/captions.vtt"),
+    assPath: z6.literal("captions/captions.ass"),
+    cues: z6.array(CueSchema)
   }),
   /**
    * How the burned-in captions were drawn. This is the **source** of
@@ -725,18 +761,18 @@ var RenderPlanSchema = z5.object({
    * older reader ignoring fields it does not know still executes the same frozen arguments
    * over the same frozen ASS. That observation generalises to the schema as a whole.
    */
-  style: z5.object({
-    fontFile: z5.literal("assets/fonts/NotoSans-Regular.ttf"),
-    fontName: z5.literal("Noto Sans"),
-    fontSize: z5.number().int().positive(),
-    textColor: z5.string(),
-    outlineColor: z5.string(),
+  style: z6.object({
+    fontFile: z6.literal("assets/fonts/NotoSans-Regular.ttf"),
+    fontName: z6.literal("Noto Sans"),
+    fontSize: z6.number().int().positive(),
+    textColor: z6.string(),
+    outlineColor: z6.string(),
     /** ASS `Outline`: a stroke width under `BorderStyle 1`, box padding under `BorderStyle 4`. */
-    outlineWidth: z5.number().int().nonnegative(),
-    marginBottom: z5.number().int().nonnegative(),
-    marginSide: z5.number().int().nonnegative().default(80),
-    borderStyle: z5.union([z5.literal(1), z5.literal(4)]).default(1),
-    outlineOpacity: z5.number().min(0).max(1).default(1),
+    outlineWidth: z6.number().int().nonnegative(),
+    marginBottom: z6.number().int().nonnegative(),
+    marginSide: z6.number().int().nonnegative().default(80),
+    borderStyle: z6.union([z6.literal(1), z6.literal(4)]).default(1),
+    outlineOpacity: z6.number().min(0).max(1).default(1),
     boxColor: HEX_COLOUR.default("#000000"),
     /*
      * Opaque, which under the `BorderStyle 1` default draws nothing at all: `BackColour` is
@@ -744,7 +780,7 @@ var RenderPlanSchema = z5.object({
      * and ASS's own default, so a plan frozen before this field existed regenerates its ASS
      * byte-for-byte rather than byte-for-byte-except-one-field-nobody-can-see.
      */
-    boxOpacity: z5.number().min(0).max(1).default(1),
+    boxOpacity: z6.number().min(0).max(1).default(1),
     /**
      * ASS `\an` alignment: which edge of the frame the caption block is anchored to, and
      * therefore which margin `marginBottom` is measured from.
@@ -763,12 +799,12 @@ var RenderPlanSchema = z5.object({
      * remaining code, middle-centre (5), would put the words back over the picture — which
      * is the thing the letterbox exists to stop.
      */
-    alignment: z5.union([z5.literal(2), z5.literal(8)]).default(2)
+    alignment: z6.union([z6.literal(2), z6.literal(8)]).default(2)
   }),
-  ffmpeg: z5.object({
-    base: z5.array(z5.string()),
-    soft: z5.array(z5.string()),
-    hard: z5.array(z5.string())
+  ffmpeg: z6.object({
+    base: z6.array(z6.string()),
+    soft: z6.array(z6.string()),
+    hard: z6.array(z6.string())
   }),
   intro: IntroSchema.optional(),
   outro: OutroSchema.optional(),
@@ -825,11 +861,11 @@ var RenderPlanSchema = z5.object({
    * it out): a lone, unsegmented capture has no gap to claim in the first place, and needs
    * none of these five fields at all.
    */
-  actors: z5.array(ActorSchema).min(2).optional(),
-  segments: z5.array(SegmentSchema).min(2).optional(),
-  transitionCards: z5.array(TransitionCardSchema).min(1).optional(),
-  badgesAssPath: z5.literal("captions/badges.ass").optional(),
-  explainSegments: z5.array(ExplainSegmentPlanSchema).min(1).optional()
+  actors: z6.array(ActorSchema).min(2).optional(),
+  segments: z6.array(SegmentSchema).min(2).optional(),
+  transitionCards: z6.array(TransitionCardSchema).min(1).optional(),
+  badgesAssPath: z6.literal("captions/badges.ass").optional(),
+  explainSegments: z6.array(ExplainSegmentPlanSchema).min(1).optional()
 }).refine(
   (plan) => {
     const castFields = [plan.actors, plan.transitionCards, plan.badgesAssPath];
@@ -900,95 +936,95 @@ var RenderPlanSchema = z5.object({
 );
 
 // ../schema/src/results.ts
-import { z as z6 } from "zod";
-var RELATIVE_POSIX = z6.string().regex(/^[A-Za-z0-9.][A-Za-z0-9._/-]*$/, "must be a relative POSIX path").refine((value) => !value.split("/").includes(".."), "must not traverse upwards");
-var Sha2562 = z6.string().regex(/^[0-9a-f]{64}$/);
-var DISPLAY_PATH = z6.string().min(1);
+import { z as z7 } from "zod";
+var RELATIVE_POSIX = z7.string().regex(/^[A-Za-z0-9.][A-Za-z0-9._/-]*$/, "must be a relative POSIX path").refine((value) => !value.split("/").includes(".."), "must not traverse upwards");
+var Sha2562 = z7.string().regex(/^[0-9a-f]{64}$/);
+var DISPLAY_PATH = z7.string().min(1);
 var envelope = (kind) => ({
-  schema: z6.literal("agent-demo.result/v1"),
-  kind: z6.literal(kind),
-  ok: z6.boolean(),
+  schema: z7.literal("agent-demo.result/v1"),
+  kind: z7.literal(kind),
+  ok: z7.boolean(),
   /** Human-readable failures. Empty iff ok. */
-  problems: z6.array(z6.string())
+  problems: z7.array(z7.string())
 });
-var ArtifactRefSchema = z6.object({
+var ArtifactRefSchema = z7.object({
   path: RELATIVE_POSIX,
   sha256: Sha2562,
-  bytes: z6.number().int().nonnegative()
+  bytes: z7.number().int().nonnegative()
 });
-var StreamSummarySchema = z6.object({
-  container: z6.enum(["mp4", "webm", "other"]),
-  durationMs: z6.number().int().nonnegative(),
-  video: z6.object({
-    codec: z6.string(),
-    width: z6.number().int(),
-    height: z6.number().int(),
-    pixelFormat: z6.string(),
-    fps: z6.number().int(),
-    frames: z6.number().int(),
+var StreamSummarySchema = z7.object({
+  container: z7.enum(["mp4", "webm", "other"]),
+  durationMs: z7.number().int().nonnegative(),
+  video: z7.object({
+    codec: z7.string(),
+    width: z7.number().int(),
+    height: z7.number().int(),
+    pixelFormat: z7.string(),
+    fps: z7.number().int(),
+    frames: z7.number().int(),
     /**
      * The video stream's own duration, as distinct from the container's above. The
      * constant-rate check measures frames against this, because a padded narration track makes
      * the container's duration the audio's. Zero for a WebM, which carries no per-track
      * duration at all.
      */
-    durationMs: z6.number().int().nonnegative()
+    durationMs: z7.number().int().nonnegative()
   }),
-  subtitles: z6.array(z6.object({ codec: z6.string(), language: z6.string(), title: z6.string() })),
+  subtitles: z7.array(z7.object({ codec: z7.string(), language: z7.string(), title: z7.string() })),
   /** Properties, not a count — a narration track muxed in stereo or at the wrong rate
    * still counts as one stream. */
-  audio: z6.array(
-    z6.object({
-      codec: z6.string(),
-      sampleRate: z6.number().int().nonnegative(),
-      channels: z6.number().int().nonnegative()
+  audio: z7.array(
+    z7.object({
+      codec: z7.string(),
+      sampleRate: z7.number().int().nonnegative(),
+      channels: z7.number().int().nonnegative()
     })
   ),
   /** Titled chapters make FFmpeg's MP4 muxer add a `bin_data` track beside the `chpl` atom. */
-  dataStreams: z6.number().int().nonnegative(),
-  chapters: z6.array(
-    z6.object({
-      startMs: z6.number().int().nonnegative(),
-      endMs: z6.number().int().nonnegative(),
-      title: z6.string()
+  dataStreams: z7.number().int().nonnegative(),
+  chapters: z7.array(
+    z7.object({
+      startMs: z7.number().int().nonnegative(),
+      endMs: z7.number().int().nonnegative(),
+      title: z7.string()
     })
   )
 });
-var ToolchainSchema = z6.object({
-  node: z6.string(),
-  playwright: z6.string(),
-  chromiumRevision: z6.string(),
-  ffmpeg: z6.string(),
+var ToolchainSchema = z7.object({
+  node: z7.string(),
+  playwright: z7.string(),
+  chromiumRevision: z7.string(),
+  ffmpeg: z7.string(),
   /** May be the literal "unknown" — never fabricated. */
-  libass: z6.string(),
+  libass: z7.string(),
   fontSha256: Sha2562
 });
-var AssertionSchema = z6.object({ id: z6.string().min(1), status: z6.enum(["passed", "failed"]) });
-var StatusSchema = z6.enum(["passed", "failed"]);
-var VariantsSchema = z6.enum(["soft", "hard"]);
-var ValidationResultSchema = z6.object({
+var AssertionSchema = z7.object({ id: z7.string().min(1), status: z7.enum(["passed", "failed"]) });
+var StatusSchema = z7.enum(["passed", "failed"]);
+var VariantsSchema = z7.enum(["soft", "hard"]);
+var ValidationResultSchema = z7.object({
   ...envelope("validate"),
   /** Absent when the scenario could not be loaded at all. */
-  scenario: z6.object({
-    id: z6.string(),
-    title: z6.string(),
-    language: z6.string(),
+  scenario: z7.object({
+    id: z7.string(),
+    title: z7.string(),
+    language: z7.string(),
     /**
      * Whether this scenario needs a person, and in which phase. Reported so an author
      * — or an agent reading `--json` — learns that a scenario cannot run unattended
      * without first trying to run it. Defaulted, so a result written before this parses.
      */
-    handoff: z6.enum(["none", "preflight", "session"]).default("none"),
+    handoff: z7.enum(["none", "preflight", "session"]).default("none"),
     sha256: Sha2562
   }).optional()
 });
-var RunCommandResultSchema = z6.object({
+var RunCommandResultSchema = z7.object({
   ...envelope("run"),
   bundleDir: DISPLAY_PATH,
   status: StatusSchema,
-  cueCount: z6.number().int().nonnegative(),
+  cueCount: z7.number().int().nonnegative(),
   /** Zero on the Free Tier, and zero for a scenario with no `chapter` calls. */
-  chapterCount: z6.number().int().nonnegative(),
+  chapterCount: z7.number().int().nonnegative(),
   /**
    * How many lines the video speaks. Zero for a silent run, which is the default.
    *
@@ -997,93 +1033,100 @@ var RunCommandResultSchema = z6.object({
    * scenario whose steps carry no `subtitle`, which produces a perfectly valid silent video and
    * would look like the feature being broken rather than like nothing having been written to say.
    */
-  narratedCount: z6.number().int().nonnegative(),
-  diagnostics: z6.array(z6.object({ code: z6.string(), cueId: z6.string(), detail: z6.string() })),
-  assertions: z6.array(AssertionSchema),
-  outputs: z6.array(ArtifactRefSchema)
+  narratedCount: z7.number().int().nonnegative(),
+  diagnostics: z7.array(z7.object({ code: z7.string(), cueId: z7.string(), detail: z7.string() })),
+  assertions: z7.array(AssertionSchema),
+  outputs: z7.array(ArtifactRefSchema)
 });
-var CheckAssertionSchema = AssertionSchema.extend({ message: z6.string().optional() });
-var CheckCommandResultSchema = z6.object({
+var CheckAssertionSchema = AssertionSchema.extend({ message: z7.string().optional() });
+var CheckCommandResultSchema = z7.object({
   ...envelope("check"),
   bundleDir: DISPLAY_PATH,
   status: StatusSchema,
-  assertions: z6.array(CheckAssertionSchema),
+  assertions: z7.array(CheckAssertionSchema),
   /**
    * Handoff notes only. Cue, chapter, cursor and camera diagnostics are all derived from a
    * render plan that `check` never builds — fabricating them would report on capabilities
    * this command cannot see.
    */
-  diagnostics: z6.array(z6.object({ code: z6.string(), cueId: z6.string(), detail: z6.string() }))
+  diagnostics: z7.array(z7.object({ code: z7.string(), cueId: z7.string(), detail: z7.string() }))
 });
-var RenderCommandResultSchema = z6.object({
+var RenderCommandResultSchema = z7.object({
   ...envelope("render"),
   bundleDir: DISPLAY_PATH,
   variants: VariantsSchema,
-  streams: z6.object({
+  streams: z7.object({
     base: StreamSummarySchema.optional(),
     soft: StreamSummarySchema.optional(),
     hard: StreamSummarySchema.optional()
   }),
-  outputs: z6.array(ArtifactRefSchema)
+  outputs: z7.array(ArtifactRefSchema)
 });
-var VerificationReportSchema = z6.object({
+var VerificationReportSchema = z7.object({
   ...envelope("verify"),
   bundleDir: DISPLAY_PATH,
-  artifactCount: z6.number().int().nonnegative()
+  artifactCount: z7.number().int().nonnegative()
 });
-var DifferenceCategorySchema = z6.enum(["step", "assertion", "target", "timing", "caption", "actor"]);
-var DiffCommandResultSchema = z6.object({
+var WarmCommandResultSchema = z7.object({
+  ...envelope("warm"),
+  bundleDir: DISPLAY_PATH,
+  clipCount: z7.number().int().nonnegative(),
+  synthesizedCount: z7.number().int().nonnegative(),
+  cachedCount: z7.number().int().nonnegative()
+});
+var DifferenceCategorySchema = z7.enum(["step", "assertion", "target", "timing", "caption", "actor"]);
+var DiffCommandResultSchema = z7.object({
   ...envelope("diff"),
   bundleA: DISPLAY_PATH,
   bundleB: DISPLAY_PATH,
-  identical: z6.boolean(),
-  differences: z6.array(z6.object({ category: DifferenceCategorySchema, detail: z6.string() }))
+  identical: z7.boolean(),
+  differences: z7.array(z7.object({ category: DifferenceCategorySchema, detail: z7.string() }))
 });
-var PruneCandidateSchema = z6.object({
+var PruneCandidateSchema = z7.object({
   path: DISPLAY_PATH,
-  bytes: z6.number().int().nonnegative(),
-  scenarioId: z6.string().optional()
+  bytes: z7.number().int().nonnegative(),
+  scenarioId: z7.string().optional()
 });
-var PruneCommandResultSchema = z6.object({
+var PruneCommandResultSchema = z7.object({
   ...envelope("prune"),
-  dryRun: z6.boolean(),
+  dryRun: z7.boolean(),
   /** What was removed (confirmed) or would be (dry run) — never includes a `failed` entry. */
-  candidates: z6.array(PruneCandidateSchema),
+  candidates: z7.array(PruneCandidateSchema),
   /** A discovered bundle that was never attempted, and why — never silently dropped. */
-  skipped: z6.array(z6.object({ path: DISPLAY_PATH, reason: z6.string() })),
+  skipped: z7.array(z7.object({ path: DISPLAY_PATH, reason: z7.string() })),
   /** A selected candidate `rm` was attempted on and could not remove, and why. Always empty
    * on a dry run, since nothing is attempted until `--yes`. */
-  failed: z6.array(z6.object({ path: DISPLAY_PATH, reason: z6.string() })),
+  failed: z7.array(z7.object({ path: DISPLAY_PATH, reason: z7.string() })),
   /** What `candidates` account for: bytes actually reclaimed if `dryRun` is false, or would
    * be reclaimed if every candidate succeeded. */
-  bytesReclaimed: z6.number().int().nonnegative()
+  bytesReclaimed: z7.number().int().nonnegative()
 });
-var ImportCommandResultSchema = z6.object({
+var ImportCommandResultSchema = z7.object({
   ...envelope("import"),
   tracePath: DISPLAY_PATH,
   outputPath: DISPLAY_PATH,
   /** How many `demo.step` calls the draft carries. Zero only on the failure path. */
-  stepCount: z6.number().int().nonnegative(),
+  stepCount: z7.number().int().nonnegative(),
   /** Whether the written draft already passes `plaintake validate`. Best-effort: a draft
    * that fails is still written, still a success, and its problems are warnings here. */
-  validates: z6.boolean(),
+  validates: z7.boolean(),
   /** Author-facing advice: multi-page traces, redactions, unimported trace calls, and the
    * standing review-for-secrets line. Never empty on success. */
-  warnings: z6.array(z6.string())
+  warnings: z7.array(z7.string())
 });
-var InspectResultSchema = z6.object({
+var InspectResultSchema = z7.object({
   ...envelope("inspect"),
   bundleDir: DISPLAY_PATH,
   status: StatusSchema,
-  scenario: z6.object({ id: z6.string(), sourceSha256: Sha2562 }),
+  scenario: z7.object({ id: z7.string(), sourceSha256: Sha2562 }),
   toolchain: ToolchainSchema,
-  video: z6.object({
+  video: z7.object({
     /** The whole output: the cards, if any, plus the content between them. */
-    durationMs: z6.number().int(),
-    frames: z6.number().int(),
-    width: z6.number().int(),
-    height: z6.number().int(),
-    fps: z6.number().int(),
+    durationMs: z7.number().int(),
+    frames: z7.number().int(),
+    width: z7.number().int(),
+    height: z7.number().int(),
+    fps: z7.number().int(),
     /**
      * Split out because `durationMs` alone is misleading once a card exists: 12,034ms of
      * output can be 9,034ms of recording. The parts are reported separately rather than
@@ -1098,20 +1141,20 @@ var InspectResultSchema = z6.object({
      * the word means, and is worth stating because the plan's own `video.durationMs` is a
      * different number that includes the opening card.
      */
-    contentDurationMs: z6.number().int().nonnegative(),
-    introDurationMs: z6.number().int().nonnegative().default(0),
-    outroDurationMs: z6.number().int().nonnegative()
+    contentDurationMs: z7.number().int().nonnegative(),
+    introDurationMs: z7.number().int().nonnegative().default(0),
+    outroDurationMs: z7.number().int().nonnegative()
   }),
-  captions: z6.object({
-    language: z6.string(),
-    cueCount: z6.number().int().nonnegative(),
-    characterCount: z6.number().int().nonnegative(),
-    medianCueMs: z6.number().int().nonnegative(),
-    shortestCueMs: z6.number().int().nonnegative(),
-    longestCueMs: z6.number().int().nonnegative()
+  captions: z7.object({
+    language: z7.string(),
+    cueCount: z7.number().int().nonnegative(),
+    characterCount: z7.number().int().nonnegative(),
+    medianCueMs: z7.number().int().nonnegative(),
+    shortestCueMs: z7.number().int().nonnegative(),
+    longestCueMs: z7.number().int().nonnegative()
   }),
   /** Measured from the rendered MP4 where possible, declared from the plan otherwise. */
-  chapters: z6.array(z6.object({ startMs: z6.number().int().nonnegative(), title: z6.string() })),
+  chapters: z7.array(z7.object({ startMs: z7.number().int().nonnegative(), title: z7.string() })),
   /**
    * The narration this bundle carries, or absent for a silent one.
    *
@@ -1122,13 +1165,13 @@ var InspectResultSchema = z6.object({
    * model behind it, and inventing a voice id for it would make the one field that answers "why
    * does this sound different" answer wrongly.
    */
-  narration: z6.object({
-    clipCount: z6.number().int().positive(),
+  narration: z7.object({
+    clipCount: z7.number().int().positive(),
     /** Total speech, excluding the silence between clips. Not the video's length. */
-    spokenMs: z6.number().int().nonnegative(),
+    spokenMs: z7.number().int().nonnegative(),
     /** How many clips the author supplied rather than the model producing. */
-    suppliedCount: z6.number().int().nonnegative(),
-    voice: z6.string().optional()
+    suppliedCount: z7.number().int().nonnegative(),
+    voice: z7.string().optional()
   }).optional(),
   /**
    * The multi-actor demo's cast, or absent for a single-actor bundle — every bundle
@@ -1145,19 +1188,19 @@ var InspectResultSchema = z6.object({
    * the field a reader of this JSON would already trust as the timeline, not from a second
    * field that only agrees with it by a schema-level invariant this result does not surface.
    */
-  actors: z6.object({
+  actors: z7.object({
     /** `plan.actors.length`. Reported alongside `labels` rather than left for a caller to
      * compute, matching `narration.clipCount` sitting beside `narration` above for the
      * same reason: the count is the fact most callers want first, before the list. */
-    count: z6.number().int().min(2),
+    count: z7.number().int().min(2),
     /** In `plan.actors` order — the cast list a badge or transition card would draw, not
      * deduplicated or sorted. */
-    labels: z6.array(z6.string().min(1)).min(2),
+    labels: z7.array(z7.string().min(1)).min(2),
     /** Hand-offs, not participants: one fewer than `plan.segments.length`, since a
      * segment is a window one actor already holds and a turn is the cut between two of
      * them — the same count `plan.transitionCards.length` carries, arrived at
      * independently from `segments` for the reason above. */
-    turnCount: z6.number().int().nonnegative()
+    turnCount: z7.number().int().nonnegative()
   }).refine((value) => value.count === value.labels.length, "actors.count must equal actors.labels.length").optional(),
   /**
    * The explain scenes this bundle cut away to, in composite order, or absent for a bundle
@@ -1169,20 +1212,20 @@ var InspectResultSchema = z6.object({
    * `actors` is sourced from the plan rather than re-read from `demo.explain()` calls: a
    * bundle whose scenario has since been edited or deleted still inspects correctly.
    */
-  explainScenes: z6.array(
-    z6.object({
-      id: z6.string().min(1),
-      durationMs: z6.number().int().positive()
+  explainScenes: z7.array(
+    z7.object({
+      id: z7.string().min(1),
+      durationMs: z7.number().int().positive()
     })
   ).min(1).optional(),
   /** The rendered MP4s, from the manifest, so hashes are not recomputed. */
-  outputs: z6.array(ArtifactRefSchema),
-  assertions: z6.array(AssertionSchema),
-  artifactCount: z6.number().int().nonnegative(),
+  outputs: z7.array(ArtifactRefSchema),
+  assertions: z7.array(AssertionSchema),
+  artifactCount: z7.number().int().nonnegative(),
   /** Everything the manifest accounts for. What "delete this bundle" would reclaim. */
-  bundleBytes: z6.number().int().nonnegative()
+  bundleBytes: z7.number().int().nonnegative()
 });
-var DoctorResultSchema = z6.object({
+var DoctorResultSchema = z7.object({
   ...envelope("doctor"),
   /**
    * The PlainTake build this is. Here rather than in `ToolchainSchema` on purpose:
@@ -1190,12 +1233,12 @@ var DoctorResultSchema = z6.object({
    * manifest on every release and break the byte-for-byte golden bundle. `doctor` is the
    * one command a bug report is asked for, which makes it the right place.
    */
-  version: z6.string(),
-  ffmpeg: z6.string(),
-  ffprobe: z6.string(),
-  libass: z6.string(),
-  hasLibass: z6.boolean(),
-  hasX264: z6.boolean(),
+  version: z7.string(),
+  ffmpeg: z7.string(),
+  ffprobe: z7.string(),
+  libass: z7.string(),
+  hasLibass: z7.boolean(),
+  hasX264: z7.boolean(),
   /**
    * Whether this FFmpeg can encode AAC, which is what a narrated bundle is muxed with.
    *
@@ -1205,8 +1248,8 @@ var DoctorResultSchema = z6.object({
    * that actually needs it, with a fix string. Failing `doctor` here would be telling someone
    * their installation is broken for a capability they may never turn on.
    */
-  hasAac: z6.boolean(),
-  filters: z6.array(z6.string()),
+  hasAac: z7.boolean(),
+  filters: z7.array(z7.string()),
   /**
    * Whether spoken narration could be produced right now, and what is missing if not.
    *
@@ -1215,12 +1258,12 @@ var DoctorResultSchema = z6.object({
    * `openNarrator` asks before a run, answered by the same function (`speechAssetProblems`), so
    * `doctor` cannot say speech is fine and then a run refuse it.
    */
-  speech: z6.object({
-    ready: z6.boolean(),
+  speech: z7.object({
+    ready: z7.boolean(),
     /** Installed voices, in catalogue order. Empty means the model cannot speak yet. */
-    voices: z6.array(z6.string()),
+    voices: z7.array(z7.string()),
     /** What is missing, in the same words a refused run would use. Empty when ready. */
-    notes: z6.array(z6.string())
+    notes: z7.array(z7.string())
   }),
   /**
    * Whether the plainmotion CLI is on `PATH`, for a scenario that wants to call
@@ -1231,16 +1274,16 @@ var DoctorResultSchema = z6.object({
    * probe a run's own first `demo.explain()` pays, so `doctor` cannot say plainmotion is fine
    * and then a run refuse it.
    */
-  plainmotion: z6.object({
-    installed: z6.boolean(),
+  plainmotion: z7.object({
+    installed: z7.boolean(),
     /** plainmotion's own `--version` output. Absent when not installed. */
-    version: z6.string().optional(),
+    version: z7.string().optional(),
     /** Why the probe failed, in the same words a run's own refusal would use. Absent when installed. */
-    note: z6.string().optional()
+    note: z7.string().optional()
   })
 });
 var okMatchesProblems = (value) => value.ok === (value.problems.length === 0);
-var ActivateReasonSchema = z6.enum([
+var ActivateReasonSchema = z7.enum([
   "empty-key",
   "not-found",
   "revoked",
@@ -1248,16 +1291,16 @@ var ActivateReasonSchema = z6.enum([
   "unexpected-response",
   "not-configured"
 ]);
-var ActivateResultSchema = z6.object({
+var ActivateResultSchema = z7.object({
   ...envelope("activate"),
   /** Present only when ok is false, so a machine reader can distinguish the classes. */
   reason: ActivateReasonSchema.optional(),
   /** Present only on success — a failed activation has no record. The key itself is
    * deliberately absent: the caller already has it, and stdout may be logged. */
-  licence: z6.object({
-    subject: z6.string().min(1),
-    activatedAt: z6.string().min(1),
-    uses: z6.number().int().nonnegative()
+  licence: z7.object({
+    subject: z7.string().min(1),
+    activatedAt: z7.string().min(1),
+    uses: z7.number().int().nonnegative()
   }).optional()
 }).refine(okMatchesProblems, "ok must be true iff problems is empty").refine(
   // Making the "present only when" comments above literally true, so a reader can
@@ -1265,22 +1308,22 @@ var ActivateResultSchema = z6.object({
   (value) => value.reason !== void 0 === !value.ok && (value.licence === void 0 || value.ok),
   "reason appears iff ok is false, and licence only on success"
 );
-var LicenceResultSchema = z6.discriminatedUnion("tier", [
-  z6.object({
+var LicenceResultSchema = z7.discriminatedUnion("tier", [
+  z7.object({
     ...envelope("licence"),
-    tier: z6.literal("free"),
+    tier: z7.literal("free"),
     /**
      * Why a present-but-unusable record degraded to free, in readLicense's own words.
      * Must never quote a filesystem path: assertNoAbsolutePaths exempts only `problems`.
      */
-    problem: z6.string().optional()
+    problem: z7.string().optional()
   }),
-  z6.object({
+  z7.object({
     ...envelope("licence"),
-    tier: z6.literal("pro"),
-    subject: z6.string().min(1),
-    activatedAt: z6.string().min(1),
-    uses: z6.number().int().nonnegative()
+    tier: z7.literal("pro"),
+    subject: z7.string().min(1),
+    activatedAt: z7.string().min(1),
+    uses: z7.number().int().nonnegative()
   })
 ]).refine(okMatchesProblems, "ok must be true iff problems is empty");
 

package/dist/schema/index.d.ts

@@ -2,6 +2,7 @@ export * from './errors.js';
 export * from './event.js';
 export * from './json-schema.js';
 export * from './manifest.js';
+export * from './narration-index.js';
 export * from './render-plan.js';
 export * from './results.js';
 export * from './scenario.js';

package/dist/schema/narration-index.d.ts

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+/**
+ * The warm index: the ordered set of synthesis requests a narrated recording made, written into
+ * the bundle so the clips can be re-synthesised **before** a later re-recording rather than during
+ * it.
+ *
+ * It exists because synthesis sits on the capture's critical path — a clip is produced while the
+ * screencast rolls, and a cache-cold run (a fresh machine, CI, or the one after a
+ * `SPEECH_ENGINE_VERSION` bump) therefore records every synthesis stall into the video as extra
+ * silence. `plaintake warm` reads this file and drives the *same* narrator's `clipFor` for each
+ * entry with no browser and no target app, filling `~/.cache/plaintake/speech` so the next
+ * recording is all cache hits and its length is a function of the demo, not of the machine.
+ *
+ * **It is inputs, not audio.** Every field here is something the recorder knew *before* it
+ * synthesised — the line, the split, the voice, the run's speed and dtype — so warming combines it
+ * with whatever engine identity the code carries *now*. That is the whole point: after a version
+ * bump the text is unchanged, so warming the old index re-synthesises correctly under the new
+ * engine. What is deliberately absent is anything version-stamped (`modelSha256`, the engine
+ * version): those come from the current build, never from the file.
+ *
+ * Only `synth`-sourced clips appear. A `--speech file` clip is the author's own audio with nothing
+ * to synthesise, and an `explain` scene is plainmotion's, not this narrator's.
+ */
+export declare const NARRATION_INDEX_SCHEMA = "agent-demo.narration-index/v1";
+/**
+ * One synthesis request, carrying exactly the fields `StepNarrator.clipFor` takes — so warming is a
+ * replay of the call the recording already made, not a second code path that has to be kept in step
+ * with how a line becomes a cache key.
+ */
+export declare const NarrationIndexClipSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+    breaks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    voice: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type NarrationIndexClip = z.infer<typeof NarrationIndexClipSchema>;
+/**
+ * The whole index: the run-wide voice controls, then one entry per synthesised clip. `speech` holds
+ * everything a narrator needs to reconstruct the same cache keys *except* the engine identity — the
+ * default voice, any extra declared voices, the speed and dtype the run resolved, and the
+ * scenario's own pronunciation dictionary (merged under the built-in defaults again at warm time,
+ * exactly as `openNarrator` merges it at record time).
+ */
+export declare const NarrationIndexSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"agent-demo.narration-index/v1">;
+    speech: z.ZodObject<{
+        voice: z.ZodString;
+        voices: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        speed: z.ZodNumber;
+        dtype: z.ZodString;
+        pronunciations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>;
+    clips: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        breaks: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        voice: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type NarrationIndex = z.infer<typeof NarrationIndexSchema>;

package/dist/schema/results.d.ts

@@ -201,6 +201,23 @@ export declare const VerificationReportSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     problems: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * `warm <bundleDir>`'s result. Warming synthesises a bundle's narration into the shared clip cache
+ * with no browser and no target app, so the next recording is cache hits rather than synthesis
+ * stalls padding the video — hence the two counts: how many clips it had to synthesise now, and how
+ * many the cache already held. `ok` is a plain success (the cache was filled), unlike `verify` where
+ * it is a verdict; a failure — a missing index, an uninstalled model with work to do — throws.
+ */
+export declare const WarmCommandResultSchema: z.ZodObject<{
+    bundleDir: z.ZodString;
+    clipCount: z.ZodNumber;
+    synthesizedCount: z.ZodNumber;
+    cachedCount: z.ZodNumber;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"warm">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 /**
  * `diff <bundleA> <bundleB>`'s result. Two `DISPLAY_PATH`s rather than `verify`'s and
  * `inspect`'s single `bundleDir`, because this is the one command that compares two bundles
@@ -456,6 +473,7 @@ export type RunCommandResult = z.infer<typeof RunCommandResultSchema>;
 export type CheckCommandResult = z.infer<typeof CheckCommandResultSchema>;
 export type RenderCommandResult = z.infer<typeof RenderCommandResultSchema>;
 export type VerificationReport = z.infer<typeof VerificationReportSchema>;
+export type WarmCommandResult = z.infer<typeof WarmCommandResultSchema>;
 export type DiffCommandResult = z.infer<typeof DiffCommandResultSchema>;
 export type PruneCommandResult = z.infer<typeof PruneCommandResultSchema>;
 export type ImportCommandResult = z.infer<typeof ImportCommandResultSchema>;
@@ -463,7 +481,7 @@ export type InspectResult = z.infer<typeof InspectResultSchema>;
 export type DoctorResult = z.infer<typeof DoctorResultSchema>;
 export type ActivateResult = z.infer<typeof ActivateResultSchema>;
 export type LicenceResult = z.infer<typeof LicenceResultSchema>;
-export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | DiffCommandResult | PruneCommandResult | ImportCommandResult | InspectResult | DoctorResult | ActivateResult | LicenceResult;
+export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | WarmCommandResult | DiffCommandResult | PruneCommandResult | ImportCommandResult | InspectResult | DoctorResult | ActivateResult | LicenceResult;
 /**
  * Renders a filesystem location for display in a result, relative to `root` when it
  * lies inside it.

package/dist/schema/scenario.d.ts

@@ -53,8 +53,11 @@ export declare const ScenarioCameraSchema: z.ZodObject<{
 export type ScenarioCamera = z.infer<typeof ScenarioCameraSchema>;
 /**
  * Scenario-level narration controls. Two dials, no more: the reading speed, and the set of
- * voices the scenario is allowed to switch between mid-run. No pitch, no SSML — see
- * `docs/release-checklist.md`'s "no speed, no pitch, no SSML" note.
+ * voices the scenario is allowed to switch between mid-run. No pitch, no general SSML — see
+ * `docs/release-checklist.md`'s "no speed, no pitch, no SSML" note. The one in-line exception is
+ * the `[pause]` break marker an author may write inside a `subtitle`/`intro.narration` (parsed
+ * in the recorder, not here): a single, bounded place-marker with no length, deliberately not a
+ * door to general markup.
  *
  * Nested under `speech` rather than bare top-level fields: it names what is being tuned (the
  * narration) apart from the DSL's other top-level concerns, matching how `camera` groups

package/dist/types.d.ts

@@ -11,6 +11,12 @@ export type DemoAction = 'click' | 'type' | 'point' | 'scroll';
 export type DemoStep = {
     id: string;
     title: string;
+    /**
+     * The on-screen caption and, under `--speech on`, the spoken line — one string for both. Write
+     * a `[pause]` inside it to force the voice to break at that point on a long line the model would
+     * otherwise mistime; the marker is stripped from the caption and marks a place, not a length.
+     * See `public/docs/scenarios.md` → Narration breaks.
+     */
     subtitle?: string;
     /** Locator whose bounding box is recorded on step.start. Never used to perform the action. */
     target?: Locator;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaintake/scenario",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Authoring SDK for PlainTake demo scenarios: defineDemo and the scenario DSL types. Install for editor autocomplete; the PlainTake binary ships a runtime fallback.",
   "license": "MIT",
   "type": "module",