@plaintake/scenario 1.3.0 → 1.5.0

package/dist/index.js

@@ -79,6 +79,9 @@ var ScenarioCameraSchema = z2.object({
   easeMs: z2.number().int().min(133, "camera.easeMs must be at least 133ms").max(2e3, "camera.easeMs must be at most 2000ms").optional(),
   minDwellMs: z2.number().int().min(0, "camera.minDwellMs must be at least 0").max(5e3, "camera.minDwellMs must be at most 5000ms").optional()
 });
+var ScenarioSpeechSchema = z2.object({
+  speed: z2.number().min(0.5, "speech.speed must be at least 0.5 (half speed)").max(2, "speech.speed must be at most 2.0 (double speed) \u2014 an unmeasured, conservative ceiling").optional()
+});
 var ScenarioMetaSchema = z2.object({
   schema: z2.literal("agent-demo.scenario/v1"),
   id: z2.string().regex(/^[a-z0-9][a-z0-9-]*$/, "must be a lowercase kebab-case id"),
@@ -142,7 +145,34 @@ var ScenarioMetaSchema = z2.object({
    * Note this is read only when the camera is on at all (`--camera zoom`). A scenario
    * recorded flat carries these harmlessly.
    */
-  camera: ScenarioCameraSchema.optional()
+  camera: ScenarioCameraSchema.optional(),
+  /*
+   * Scenario-level narration speed. Optional and inert when absent, the same precedent as
+   * `camera` above: a scenario that says nothing about speed narrates at 1x, exactly as every
+   * scenario written before this field existed always has. See `ScenarioSpeechSchema`'s own
+   * comment for the field's shape and the reasoning behind `speed`'s bounds.
+   */
+  speech: ScenarioSpeechSchema.optional(),
+  /*
+   * A text-substitution dictionary applied to narration immediately before synthesis — not the
+   * vendored en-us phoneme dictionary `install-voice` fetches (a different thing entirely: that
+   * one is a fixed grapheme-to-phoneme table the engine consults for every word; this one is
+   * authored per scenario, substitutes whole words, and is applied by `narrate.ts` before the
+   * text ever reaches the engine). `{ SQL: 'sequel' }` makes the voice say "sequel" while the
+   * caption keeps reading "SQL" — captions read from `step.subtitle`/recorded events, an
+   * entirely separate pipeline this dictionary never touches.
+   *
+   * Keys must be non-empty, so an accidental `{ '': 'x' }` is refused here rather than silently
+   * matching nothing at synthesis time. Values may be empty: an empty value mutes the matched
+   * word out of the spoken line, which is a deliberate if narrow use — nothing else in the DSL
+   * offers a way to drop a word from the audio without also dropping it from the caption.
+   * Word-boundary, case-insensitive matching; see `applyPronunciations` in
+   * `recorder-playwright/src/narrate.ts`, the one place this dictionary is actually applied,
+   * for the exact matching rule.
+   *
+   * Optional and inert when absent, the same precedent as everything else on this schema.
+   */
+  pronunciations: z2.record(z2.string().min(1, "pronunciation keys must not be empty"), z2.string()).optional()
 });
 
 // ../schema/src/manifest.ts
@@ -234,12 +264,36 @@ var CursorPointSchema = z5.object({
   action: z5.enum(["click", "type", "point"]),
   rippleMs: z5.number().int().nonnegative().optional(),
   /**
-   * Counter-scale percent, so the cursor stays one size on screen while the camera
-   * magnifies its window — up to 1.6x — and the emitter compensates with `\fscx`/`\fscy`.
-   * Absent means 100, so it carries no default: a cursor bundle from before the camera
-   * existed still parses and regenerates byte-for-byte.
+   * 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
+   * the output. Two things do, and they compose into one number:
+   *
+   * - **The camera magnifies it.** The cursor is drawn before the crop, so a zoomed shot
+   *   enlarges the pointer with the page — up to 1.6x. That alone only ever *shrinks* the
+   *   correction, which is why this field's ceiling was 100 for as long as the camera was
+   *   the only thing acting on it.
+   * - **The letterbox shrinks it.** Under `--aspect`, the finished 16:9 frame is scaled
+   *   down onto `video.letterbox` before being padded into the taller output, and the
+   *   cursor `ass` runs upstream of that scale — so a 12x19-unit arrow arrives at the
+   *   viewer smaller than it was drawn, which is the exact failure this field exists to
+   *   prevent. The correction is the inverse of that scale, and it telescopes with the
+   *   camera's into a single ratio of the active window to the letterbox width:
+   *
+   *   ```
+   *   scale% = round(100 * active.w / letterbox.width)
+   *   ```
+   *
+   *   A 9:16 full-frame shot is `round(100 * 1920 / 1080)` = **178**, so the old `max(100)`
+   *   rejected the corrected value outright. 400 is the ceiling now: not a computed bound —
+   *   the shipped geometry tops out at 178 — but a loose one that still catches a derivation
+   *   off by an order of magnitude rather than freezing it into a plan.
+   *
+   * Absent means 100, so it carries no default. A 16:9 plan has no letterbox and computes
+   * `100 * 1920 / 1920` = 100, which the emitter's omit-defaults rule drops exactly as it
+   * 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(100).optional()
+  scale: z5.number().int().min(1).max(400).optional()
 });
 var CursorSchema = z5.object({
   assPath: z5.literal("captions/cursor.ass"),
@@ -295,6 +349,35 @@ var CameraSchema = z5.object({
     path: ["shots"]
   }
 );
+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()
+}).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
+  // 1920x1080 canvas the spotlight is cut from, or the hole would miss the frame it is
+  // meant to sit inside.
+  message: "the rect must stay inside the 1920x1080 frame",
+  path: ["x"]
+});
+var HighlightSchema = z5.object({
+  assPath: z5.literal("captions/highlight.ass"),
+  rects: z5.array(HighlightRectSchema).min(1)
+}).refine(
+  ({ rects }) => rects.every(
+    (rect, index) => rect.endMs > rect.startMs && (index === 0 || rects[index - 1].endMs <= rect.startMs)
+  ),
+  {
+    message: "rects must be ordered, non-overlapping, and end after they start",
+    path: ["rects"]
+  }
+);
 var SpeechClipSchema = z5.object({
   id: z5.string().min(1),
   /*
@@ -364,11 +447,84 @@ var RenderPlanSchema = z5.object({
     sha256: z5.string().regex(/^[0-9a-f]{64}$/),
     durationMs: z5.number().int().nonnegative()
   }),
+  /**
+   * The frame. **Three geometries live here and they are not the same thing**, which is the
+   * whole reason this block stopped being two literals:
+   *
+   * - `capture` is the crop space — the fixed 1920x1080 Chromium always records at, DPR 1,
+   *   which never varies and is not allowed to (`AGENTS.md` §1 constraint 3). Everything
+   *   upstream of the output is expressed in it: cursor points, camera windows, highlight
+   *   rects. It is `.default()`ed
+   *   rather than required so a plan frozen before the field existed parses to exactly the
+   *   space it was rendered in, and the arguments derived from it come out byte-identical.
+   * - `width`/`height` are the **output** frame: 1920x1080 for 16:9, 1080x1920 for 9:16,
+   *   1080x1080 for 1:1. They are no longer literals because that is the one number
+   *   `--aspect` moves.
+   * - `letterbox` is where the finished 16:9 picture is laid inside that output, plus the
+   *   colour filling the rest. Absent on 16:9, where output and capture coincide and there
+   *   is nothing to pad.
+   *
+   * **It letterboxes; it does not crop.** A true 9:16 crop of a 1920x1080 capture is 607px
+   * wide and throws away 68% of the UI, which is useless for a product demo. Scaling the
+   * finished frame down and padding it into the taller output keeps every pixel, puts the
+   * captions in the empty band instead of over the video, and — because none of it touches
+   * capture — makes a bundle already recorded re-cuttable to vertical without re-recording, the
+   * same property soft subtitles have. The one exception is the captions themselves: a `Cue`
+   * carries the lines the planner already *wrapped*, so a bundle whose lines were wrapped for a
+   * wider frame is refused by `recutPlan` rather than re-cut into text that overruns the band.
+   *
+   * **`letterbox` is one object, not a box and a colour side by side.** Every other optional
+   * capability in this plan — `intro`, `outro`, `chapters`, `cursor`, `camera`, `highlight`,
+   * `speech` — is a single optional object carrying everything it needs, and this follows
+   * them. Two independent optional siblings would have made "a box with no fill" and "a fill
+   * with no box" representable in the *type*, leaving a runtime refinement as the only thing
+   * standing between a derivation and a plan nothing can render; as one object the invalid
+   * pair is unconstructable and `tsc` says so at every call site.
+   *
+   * **It is deliberately not called a "plate".** That word is taken: the dark box behind the
+   * captions is the plate everywhere else in this codebase — `AGENTS.md`, `probe.ts`,
+   * `args.ts`, the hard-subtitle acceptance thresholds — and the two would sit within a few
+   * lines of each other in the filtergraph. `/v1` is frozen for good (capabilities are
+   * additive fields, never a version bump), so a wire name here is effectively permanent and
+   * worth spending the thought on now rather than after two more slices read it.
+   *
+   * **The box is 1080x608 and that is a measured, accepted 0.08% stretch.** Scaling
+   * 1920x1080 to `w=1080` gives `h = 607.5`, which is neither integer nor even. 608 is taken
+   * instead, stretching the picture vertically by `608/607.5` = 1.00082 — 0.08%, well under
+   * the ~1% at which a stretch becomes visible on a face or a circle, and this tool records
+   * web UIs. The exact-16:9 alternative, 1056x594, is **rejected**: it is correct on paper
+   * and wrong on screen, because a 1056-wide box in a 1080-wide output leaves a 12px
+   * pillarbox bar down each side — bars inside a design whose entire purpose is to put the
+   * bars somewhere useful.
+   *
+   * **Every dimension here is even, and the two halves fail differently.** On `yuv420p` the
+   * chroma planes are half-resolution, so an odd `letterbox` `x`/`y`/`width`/`height` is
+   * silently truncated down a pixel by FFmpeg rather than refused — the invisible 1px
+   * misalignment `CameraSchema` cites (M10) for its own crop window, and the reason it keeps
+   * an evenness check on `w`/`h` that `%32` and `9w/16` already imply. An odd **output**
+   * `width`/`height` is the opposite: `libx264` hard-fails the encode with `width not
+   * divisible by 2`. That is the loud case, and leaving it unguarded while guarding the quiet
+   * 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.literal(1920),
-    height: z5.literal(1080),
+    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),
+      /**
+       * 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
+       * grammar admits no metacharacter.
+       */
+      padColor: HEX_COLOUR
+    }).optional(),
     /*
      * Everything before the closing card: the opening card, if there is one, plus the
      * recorded content. Not the content alone.
@@ -386,7 +542,19 @@ var RenderPlanSchema = z5.object({
      */
     durationMs: z5.number().int().positive(),
     tailPadMs: z5.number().int().nonnegative()
-  }),
+  }).refine(
+    ({ width, height, letterbox }) => letterbox === void 0 || letterbox.x + letterbox.width <= width && letterbox.y + letterbox.height <= height,
+    {
+      // The same containment `CameraShotSchema` enforces against the 1920x1080 capture and
+      // `HighlightRectSchema` against the canvas it cuts a hole in — except the bound here
+      // is a sibling field rather than a constant, which is exactly why it has to live on
+      // `video` and not on `letterbox` itself. A box hanging off the frame is not a
+      // rendering FFmpeg refuses; `pad` quietly clips it, so the plan would freeze a
+      // picture nobody ever sees the edge of.
+      message: "the letterbox box must fit inside the output frame",
+      path: ["letterbox"]
+    }
+  ),
   captions: z5.object({
     language: z5.string().min(2),
     srtPath: z5.literal("captions/captions.srt"),
@@ -425,7 +593,26 @@ 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: z5.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.
+     *
+     * `2` is bottom-centre — the only thing captions have ever done here, and the default,
+     * so a plan frozen before this field regenerates its ASS byte-for-byte. `8` is
+     * top-centre, and it exists for the letterbox: a 9:16 picture sits **high** in the output
+     * rather than centred, because a centred one leaves a 656px bottom bar and puts a
+     * bottom-anchored caption 600px from the content it describes, which reads as two
+     * unrelated things. Anchoring the band to the top of the pad instead keeps the words
+     * next to the picture they explain.
+     *
+     * The union is closed to those two rather than opened to all nine `\an` codes: a
+     * caption band spans the full width by construction, so every left- or right-anchored
+     * code (1, 3, 4, 6, 7, 9) describes a band this renderer cannot produce, and the one
+     * 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)
   }),
   ffmpeg: z5.object({
     base: z5.array(z5.string()),
@@ -437,6 +624,7 @@ var RenderPlanSchema = z5.object({
   chapters: ChaptersSchema.optional(),
   cursor: CursorSchema.optional(),
   camera: CameraSchema.optional(),
+  highlight: HighlightSchema.optional(),
   speech: SpeechSchema.optional()
 });
 
@@ -543,6 +731,19 @@ var RunCommandResultSchema = z6.object({
   assertions: z6.array(AssertionSchema),
   outputs: z6.array(ArtifactRefSchema)
 });
+var CheckAssertionSchema = AssertionSchema.extend({ message: z6.string().optional() });
+var CheckCommandResultSchema = z6.object({
+  ...envelope("check"),
+  bundleDir: DISPLAY_PATH,
+  status: StatusSchema,
+  assertions: z6.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() }))
+});
 var RenderCommandResultSchema = z6.object({
   ...envelope("render"),
   bundleDir: DISPLAY_PATH,
@@ -559,6 +760,33 @@ var VerificationReportSchema = z6.object({
   bundleDir: DISPLAY_PATH,
   artifactCount: z6.number().int().nonnegative()
 });
+var DifferenceCategorySchema = z6.enum(["step", "assertion", "target", "timing", "caption"]);
+var DiffCommandResultSchema = z6.object({
+  ...envelope("diff"),
+  bundleA: DISPLAY_PATH,
+  bundleB: DISPLAY_PATH,
+  identical: z6.boolean(),
+  differences: z6.array(z6.object({ category: DifferenceCategorySchema, detail: z6.string() }))
+});
+var PruneCandidateSchema = z6.object({
+  path: DISPLAY_PATH,
+  bytes: z6.number().int().nonnegative(),
+  scenarioId: z6.string().optional()
+});
+var PruneCommandResultSchema = z6.object({
+  ...envelope("prune"),
+  dryRun: z6.boolean(),
+  /** What was removed (confirmed) or would be (dry run) — never includes a `failed` entry. */
+  candidates: z6.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() })),
+  /** 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() })),
+  /** What `candidates` account for: bytes actually reclaimed if `dryRun` is false, or would
+   * be reclaimed if every candidate succeeded. */
+  bytesReclaimed: z6.number().int().nonnegative()
+});
 var InspectResultSchema = z6.object({
   ...envelope("inspect"),
   bundleDir: DISPLAY_PATH,

package/dist/schema/render-plan.d.ts

@@ -85,8 +85,18 @@ export declare const ChaptersSchema: z.ZodObject<{
 export type Chapters = z.infer<typeof ChaptersSchema>;
 export type ChapterMark = z.infer<typeof ChapterMarkSchema>;
 /**
- * One point on the cursor track. `x`/`y` are the centre of the step's `target`
- * rect, in PlayRes (= viewport) pixels, so the same coordinates libass will draw at.
+ * One point on the cursor track. `x`/`y` are the centre of the step's `target` rect, in capture
+ * pixels — the 1920x1080 space the cursor ASS declares as its own PlayRes and the space the
+ * camera derivation reads these same numbers in.
+ *
+ * They are the **measured position**, not necessarily the emitted one. `toCursorAss` pulls the
+ * anchor back where the arrow's body would otherwise leave the frame, and how far it has to pull
+ * depends on `scale` — which depends on the output shape, and so is not a property of the
+ * recording at all. Keeping the containment fix at the drawing rather than in the frozen value is
+ * what makes `recutPlan` a lossless round trip: re-cutting to `9:16` and back reproduces the
+ * point it started from, where an in-place clamp moved an edge-flush anchor and could not move it
+ * back.
+ *
  * `arriveMs` is when the cursor reaches the point — no later than the step's start, and
  * pulled earlier for clicks so the arrow is parked and visible before it ripples — and
  * `departMs` is when it may leave for the next point, pulled back from the step's finish
@@ -180,6 +190,52 @@ export declare const CameraSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Camera = z.infer<typeof CameraSchema>;
 export type CameraShot = z.infer<typeof CameraShotSchema>;
+/**
+ * One dimmed-frame-with-a-hole window: a step's measured target rect, frozen exactly as
+ * `CursorPointSchema` freezes a target's centre, and for the same reason. `renderer-ffmpeg`'s
+ * `highlightTrackFromEvents` re-reading `events/events.ndjson` at render time would violate
+ * the invariant every other derived render file already obeys — `captions/highlight.ass` has
+ * to be a pure function of the plan, so the rect a step measured has to survive plan freeze
+ * as a rect, not merely as a decision to draw one.
+ *
+ * `startMs`/`endMs` bound the whole step, not a retimed lead/rest/glide the way a cursor
+ * point is — a spotlight has no motion to choreograph, so unlike `CursorPointSchema` there is
+ * nothing here to pull earlier or hold open.
+ *
+ * `label` is the optional callout text a scenario may attach (`highlight: { label: '...' }`).
+ * Absent means the spotlight alone, exactly what `highlight: true` (no object) asks for.
+ */
+export declare const HighlightRectSchema: z.ZodObject<{
+    id: z.ZodString;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    startMs: z.ZodNumber;
+    endMs: z.ZodNumber;
+    label: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * The highlight track. A rect **list**, ordered and non-overlapping on the same discipline
+ * `CursorSchema`'s points already enforce — the derivation emits one entry per highlighted
+ * step, in event order, so an overlap or an out-of-order entry can only mean the derivation
+ * is broken.
+ */
+export declare const HighlightSchema: z.ZodObject<{
+    assPath: z.ZodLiteral<"captions/highlight.ass">;
+    rects: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+        startMs: z.ZodNumber;
+        endMs: z.ZodNumber;
+        label: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type Highlight = z.infer<typeof HighlightSchema>;
+export type HighlightRect = z.infer<typeof HighlightRectSchema>;
 /**
  * One frozen narration clip and where it lands on the timeline.
  *
@@ -271,6 +327,9 @@ export type ChaptersInput = {
 /** The camera decision as the application layer supplies it; `commandPath` is filled in
  * by `buildRenderPlan`, exactly as `CursorInput` and `ChaptersInput` work. */
 export type CameraInput = Omit<Camera, 'commandPath'>;
+/** The highlight decision as the application layer supplies it; `assPath` is filled in by
+ * `buildRenderPlan`, exactly as `CursorInput` works. */
+export type HighlightInput = Omit<Highlight, 'assPath'>;
 /**
  * The branding decision as the application layer supplies it: everything about the card
  * except where its ASS file lives, which `buildRenderPlan` fills in. Declared here rather
@@ -327,9 +386,19 @@ export declare const RENDER_PLAN_SCHEMA = "agent-demo.render/v1";
  * fails at the parse, naming the value it should have — which is a better outcome than the
  * ladder's, where the same bundle failed while carrying arguments that would have rendered.
  *
- * A plan using no optional capability remains byte-identical to what every earlier version
- * produced, so `scripts/make-golden-bundle.sh` regenerates the committed golden bundle
- * exactly — the version string was already `/v1` there.
+ * A plan using no optional capability still executes byte-identically to what every earlier
+ * version produced — the version string was already `/v1` there, and more to the point
+ * `ffmpeg.base`/`soft`/`hard` are unchanged, so the `demo.mp4` a re-render yields is the same
+ * file down to the byte.
+ *
+ * **The plan's own JSON is a weaker claim, and deliberately so.** Adding a field with a Zod
+ * `.default()` materialises it on parse, so `stableStringify` writes it and
+ * `render/render-plan.json` gains bytes the committed golden fixture does not have — which is
+ * what `style`'s defaults (`marginSide`, `boxOpacity`, …) already did once, and what
+ * `video.capture` and `style.alignment` do now. That makes the *plan file* differ from the
+ * committed golden until `scripts/make-golden-bundle.sh` is re-run; it does not touch the
+ * rendered output, because nothing derived from those defaults reaches an argument array. The
+ * reproducibility claim this project actually makes is about the video, and it holds.
  */
 export declare const RenderPlanSchema: z.ZodObject<{
     schema: z.ZodLiteral<"agent-demo.render/v1">;
@@ -339,10 +408,21 @@ export declare const RenderPlanSchema: z.ZodObject<{
         durationMs: z.ZodNumber;
     }, z.core.$strip>;
     video: z.ZodObject<{
-        width: z.ZodLiteral<1920>;
-        height: z.ZodLiteral<1080>;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
         fps: z.ZodLiteral<30>;
         pixelFormat: z.ZodLiteral<"yuv420p">;
+        capture: z.ZodDefault<z.ZodObject<{
+            width: z.ZodLiteral<1920>;
+            height: z.ZodLiteral<1080>;
+        }, z.core.$strip>>;
+        letterbox: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            padColor: z.ZodString;
+        }, z.core.$strip>>;
         durationMs: z.ZodNumber;
         tailPadMs: z.ZodNumber;
     }, z.core.$strip>;
@@ -371,6 +451,7 @@ export declare const RenderPlanSchema: z.ZodObject<{
         outlineOpacity: z.ZodDefault<z.ZodNumber>;
         boxColor: z.ZodDefault<z.ZodString>;
         boxOpacity: z.ZodDefault<z.ZodNumber>;
+        alignment: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<2>, z.ZodLiteral<8>]>>;
     }, z.core.$strip>;
     ffmpeg: z.ZodObject<{
         base: z.ZodArray<z.ZodString>;
@@ -428,6 +509,19 @@ export declare const RenderPlanSchema: z.ZodObject<{
             h: z.ZodNumber;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    highlight: z.ZodOptional<z.ZodObject<{
+        assPath: z.ZodLiteral<"captions/highlight.ass">;
+        rects: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+            startMs: z.ZodNumber;
+            endMs: z.ZodNumber;
+            label: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
     speech: z.ZodOptional<z.ZodObject<{
         trackPath: z.ZodLiteral<"speech/narration.wav">;
         sampleRate: z.ZodLiteral<24000>;

package/dist/schema/results.d.ts

@@ -52,6 +52,30 @@ export declare const RunCommandResultSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     problems: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+export declare const CheckCommandResultSchema: z.ZodObject<{
+    bundleDir: z.ZodString;
+    status: z.ZodEnum<{
+        passed: "passed";
+        failed: "failed";
+    }>;
+    assertions: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodEnum<{
+            passed: "passed";
+            failed: "failed";
+        }>;
+        message: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    diagnostics: z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        cueId: z.ZodString;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"check">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 export declare const RenderCommandResultSchema: z.ZodObject<{
     bundleDir: z.ZodString;
     variants: z.ZodEnum<{
@@ -177,6 +201,85 @@ export declare const VerificationReportSchema: z.ZodObject<{
     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
+ * instead of reading one.
+ *
+ * **`ok` is not tied to whether drift was found.** `verify`'s `ok` means "the hashes
+ * matched" because a mismatch there is always a fault — the one thing a bundle promises is
+ * that it has not been tampered with. `diff` promises no such thing: it exists precisely
+ * because two recordings of the same scenario are *expected* to differ sometimes (an
+ * intentional code change) and expected to agree other times (a re-recording taken to prove
+ * nothing moved), and neither outcome is a failure of the comparison itself. So `ok` here
+ * means "the comparison completed" — both bundles were readable and their event logs
+ * parsed — exactly the stance `doctor` takes on a missing voice model ("a state, not a
+ * fault"). `identical` is the explicit boolean a caller who wants a verdict reads instead:
+ * a CI script gating on drift checks `identical`, not `ok`. `problems` is reserved for what
+ * `ok: false` actually means here — a bundle that could not be diffed at all, which reuses
+ * `verify`'s exit code 6 (`apps/cli/src/args.ts`'s USAGE table) since it is the same failure
+ * class: bundle artifacts that could not be read back out.
+ */
+export declare const DiffCommandResultSchema: z.ZodObject<{
+    bundleA: z.ZodString;
+    bundleB: z.ZodString;
+    identical: z.ZodBoolean;
+    differences: z.ZodArray<z.ZodObject<{
+        category: z.ZodEnum<{
+            assertion: "assertion";
+            target: "target";
+            step: "step";
+            timing: "timing";
+            caption: "caption";
+        }>;
+        detail: z.ZodString;
+    }, z.core.$strip>>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"diff">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * `prune`'s result. Selection never touches disk by itself — `dryRun: true` (the default,
+ * absent `--yes`) means `candidates` names what *would* be removed and every one of them is
+ * still on disk. `dryRun: false` means `candidates` names what actually *was* removed —
+ * **best-effort, not atomic**: `--yes` attempts every selected candidate and does not stop
+ * at the first failure, so one bundle a filesystem refuses to delete (permissions, a busy
+ * handle) never blocks cleanup of the rest. `candidates` and `bytesReclaimed` report only
+ * what is actually gone; a selected candidate `rm` could not remove lands in `failed`
+ * instead, with its own path still on disk and the reason why. `ok` is false and the exit
+ * code non-zero whenever `failed` is non-empty, so a caller can never mistake a partial run
+ * for either a clean one or an empty one — the state is always visible, never silently
+ * dropped or misreported as "nothing happened".
+ *
+ * `skipped` is deliberately separate from both `failed` and `problems` — a directory that
+ * `deletionProblem` refuses, or whose manifest cannot be read, was never attempted at all;
+ * it is `prune` correctly declining to guess, not a failed deletion. `problems` stays
+ * reserved for what makes the *whole* command fail (the same envelope invariant every other
+ * result carries): an unreadable workspace root, or — as of `failed` existing — a summary of
+ * how many selected candidates a confirmed run could not actually delete.
+ */
+export declare const PruneCommandResultSchema: z.ZodObject<{
+    dryRun: z.ZodBoolean;
+    candidates: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        bytes: z.ZodNumber;
+        scenarioId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    skipped: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    failed: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    bytesReclaimed: z.ZodNumber;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"prune">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 export declare const InspectResultSchema: z.ZodObject<{
     bundleDir: z.ZodString;
     status: z.ZodEnum<{
@@ -304,13 +407,16 @@ export declare const LicenceResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 export type ArtifactRef = z.infer<typeof ArtifactRefSchema>;
 export type ValidationResult = z.infer<typeof ValidationResultSchema>;
 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 DiffCommandResult = z.infer<typeof DiffCommandResultSchema>;
+export type PruneCommandResult = z.infer<typeof PruneCommandResultSchema>;
 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 | RenderCommandResult | VerificationReport | InspectResult | DoctorResult | ActivateResult | LicenceResult;
+export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | DiffCommandResult | PruneCommandResult | 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

@@ -51,6 +51,34 @@ export declare const ScenarioCameraSchema: z.ZodObject<{
     minDwellMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type ScenarioCamera = z.infer<typeof ScenarioCameraSchema>;
+/**
+ * Scenario-level narration speed — the one dial this DSL exposes onto the voice, and
+ * deliberately the only one. No pitch, no per-step override, no SSML: see
+ * `docs/release-checklist.md`'s "no speed, no pitch, no per-step voice, no per-step override,
+ * and no SSML" note, of which this closes exactly the first item and nothing else. A per-step
+ * override would mean preloading more than one voice at once; `engine.ts` measured a single
+ * voice at ~500 MB resident, rising to ~750 MB with a second loaded alongside it — roughly
+ * +250 MB per *additional* voice, not 500 MB multiplied by the voice count — a real
+ * architecture change this is deliberately not taking on.
+ *
+ * Nested under `speech` rather than a bare top-level `speed` field: it names what is being
+ * tuned (the narration) apart from the DSL's other top-level concerns, matching how `camera`
+ * groups framing rather than adding `maxZoom` directly to the metadata object, and it leaves
+ * room to grow if narration ever gains a second scenario-level knob without a second unrelated
+ * top-level field appearing beside it.
+ *
+ * `speed` has no measured bound anywhere in this codebase — grepped before picking one: only a
+ * hardcoded `speed: 1` default and one `speed: 1.1` in a cache test existed before this field
+ * did. Unlike `camera.maxZoom`'s 1.6 (measured against a real page that lost its left third),
+ * there is no such measurement to cite for narration speed, so 0.5–2.0 is a clearly-labelled,
+ * conservative guess at the range most TTS engines expose a multiplier over, not a fact. A
+ * scenario that genuinely needs something outside it is real signal to revisit this bound with
+ * a measurement, the way `maxZoom`'s eventually got one.
+ */
+export declare const ScenarioSpeechSchema: z.ZodObject<{
+    speed: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type ScenarioSpeech = z.infer<typeof ScenarioSpeechSchema>;
 export declare const ScenarioMetaSchema: z.ZodObject<{
     schema: z.ZodLiteral<"agent-demo.scenario/v1">;
     id: z.ZodString;
@@ -83,6 +111,10 @@ export declare const ScenarioMetaSchema: z.ZodObject<{
         easeMs: z.ZodOptional<z.ZodNumber>;
         minDwellMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    speech: z.ZodOptional<z.ZodObject<{
+        speed: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    pronunciations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;
 /** Which phase, if any, hands the browser over. Read by the recorder and the surfaces. */
 export type HandoffMode = z.infer<typeof ScenarioMetaSchema>['handoff'];

package/dist/types.d.ts

@@ -15,6 +15,23 @@ export type DemoStep = {
     target?: Locator;
     /** Declared interaction kind, recorded on step.start and consumed by the cursor track. */
     action?: DemoAction;
+    /**
+     * Dims everything except this step's target rect, with an optional callout label. Recorded
+     * on step.start alongside `target`/`action` and consumed by the render-time highlight
+     * track — never performed or drawn during capture, which would break byte-reproducibility.
+     * Free on every tier, unlike the camera. `true` draws the spotlight alone; `{ label }` adds
+     * a callout beside it. Absent means off, which is what every scenario written before this
+     * field existed still renders — the same precedent `action` and `holdMs` set.
+     *
+     * Requires `target` to be measurable: a step that asks for a highlight but whose target's
+     * bounding box could not be measured is reported as a diagnostic rather than silently
+     * skipped, because unlike a cursor or camera point (which draws on any step, targeted or
+     * not, and simply has nothing to draw without a rect) this is an explicit request that went
+     * unfulfilled.
+     */
+    highlight?: boolean | {
+        label?: string;
+    };
     /** Extra presentation hold after the action completes, in whole milliseconds. */
     holdMs?: number;
     run: () => Promise<unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plaintake/scenario",
-  "version": "1.3.0",
+  "version": "1.5.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",