@plaintake/scenario 1.2.1

package/dist/index.js

@@ -0,0 +1,753 @@
+// ../schema/src/errors.ts
+var EXIT_CODES = {
+  ok: 0,
+  assertion: 1,
+  usage: 2,
+  toolchain: 3,
+  capture: 4,
+  render: 5,
+  verification: 6
+};
+var DemoError = class extends Error {
+  kind;
+  exitCode;
+  details;
+  constructor(kind, message, details = {}) {
+    super(message);
+    this.name = "DemoError";
+    this.kind = kind;
+    this.exitCode = EXIT_CODES[kind];
+    this.details = details;
+  }
+};
+
+// ../schema/src/event.ts
+import { z } from "zod";
+var NanosString = z.string().regex(/^\d+$/, "must be a digit-only nanosecond string");
+var DemoEventTypeSchema = z.enum([
+  "session.start",
+  "session.finish",
+  "chapter",
+  "step.start",
+  "step.finish",
+  "assertion.pass",
+  "assertion.fail",
+  "privacy.mask",
+  /*
+   * A bounded stretch where the recorder was waiting on something it does not drive.
+   * One member, not two, because a handoff and a plain condition answer the same question a
+   * reader of events.ndjson has — *why is the video sitting still here?* — and `payload.kind`
+   * separates them exactly as `step.finish` already carries `holdMs`.
+   *
+   * Appended once, when the wait ends, so `tEndNs` is a real reading rather than a
+   * placeholder: the `assertion.pass` shape, not the `step.start`/`step.finish` pair.
+   */
+  "human.wait"
+]);
+var TargetSchema = z.object({
+  role: z.string().optional(),
+  accessibleName: z.string().optional(),
+  selector: z.string().optional(),
+  rect: z.object({ x: z.number(), y: z.number(), width: z.number(), height: z.number() }).optional()
+});
+var DemoEventSchema = z.object({
+  schema: z.literal("agent-demo.event/v1"),
+  seq: z.number().int().nonnegative(),
+  tStartNs: NanosString,
+  tEndNs: NanosString.optional(),
+  type: DemoEventTypeSchema,
+  stableId: z.string().min(1).optional(),
+  title: z.string().optional(),
+  subtitle: z.string().optional(),
+  target: TargetSchema.optional(),
+  payload: z.record(z.string(), z.unknown()).optional()
+});
+
+// ../schema/src/json-schema.ts
+import { z as z3 } from "zod";
+
+// ../schema/src/scenario.ts
+import { z as z2 } from "zod";
+var ScenarioIntroSchema = z2.object({
+  lines: z2.array(z2.string().min(1)).min(1).max(2, "intro.lines takes at most two lines \u2014 a third would have to shrink the type to fit"),
+  narration: z2.string().min(1).optional(),
+  durationMs: z2.number().int().positive().max(15e3, "intro.durationMs must be at most 15000ms").optional()
+});
+var ScenarioCameraSchema = z2.object({
+  maxZoom: z2.number().min(1, "camera.maxZoom must be at least 1 (no zoom)").max(1.6, "camera.maxZoom must be at most 1.6 \u2014 beyond that the upscaled capture turns UI text to mush").optional(),
+  margin: z2.number().min(0, "camera.margin must be at least 0").max(2, "camera.margin must be at most 2 (as a fraction of the target, per side)").optional(),
+  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 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"),
+  title: z2.string().min(1),
+  language: z2.string().min(2).default("en"),
+  viewport: z2.object({
+    width: z2.literal(1920),
+    height: z2.literal(1080),
+    deviceScaleFactor: z2.literal(1)
+  }),
+  locale: z2.literal("en-US"),
+  timezoneId: z2.literal("UTC"),
+  colorScheme: z2.literal("light"),
+  reducedMotion: z2.literal("reduce"),
+  /** Exact console error strings the scenario tolerates. Anything else fails the run. */
+  allowedConsoleErrors: z2.array(z2.string()).default([]),
+  /*
+   * Whether this scenario hands the real browser window to a person, and in which phase.
+   *
+   * Declared here rather than discovered when `demo.handoff()` is first called, because an
+   * unavailable capability must be refused *before* Chromium starts — and what a `run()`
+   * body is going to do is not knowable then. Four things read it: whether Chromium launches
+   * headed, whether a Playwright trace is recorded at all, the refusals in `runScenario`, and
+   * which phase may legally call `demo.handoff()`.
+   *
+   * Headedness derives from this and from nothing else. There is deliberately no `--headed`
+   * flag: one would let the shipped examples be recorded headed, and S2 measured that headed
+   * and headless Chromium put glyphs on different pixels — so `make reproduce` would compare
+   * two videos that were never meant to match.
+   *
+   * The same precedent as everywhere else here: a `.default()`, so every scenario written
+   * before this parses unchanged.
+   */
+  handoff: z2.enum(["none", "preflight", "session"]).default("none"),
+  /*
+   * How long a handoff waits for the person before giving up. Not a patience limit —
+   * past a few minutes, a block is indistinguishable from a hang, and the person is better
+   * served by a failure that names the wait than by a recorder that sits there.
+   *
+   * In the schema rather than only in the runtime so `validate` catches an out-of-range
+   * value with no browser and no waiting.
+   */
+  handoffTimeoutMs: z2.number().int().min(5e3, "handoffTimeoutMs must be at least 5000ms").max(
+    3e5,
+    "handoffTimeoutMs must be at most 300000ms (5 minutes) \u2014 past that a wait is indistinguishable from a hang"
+  ).default(12e4),
+  /*
+   * The opening card. Optional on the same precedent, like `handoff` above: every scenario
+   * written before this parses unchanged, and one that declares no intro renders exactly
+   * the video it always did.
+   *
+   * Note this is the field that makes an intro *possible* at all — Zod strips unknown keys
+   * (`scenario/src/define.ts`), so before it existed an `intro:` block in a demo file was
+   * discarded in silence rather than refused.
+   */
+  intro: ScenarioIntroSchema.optional(),
+  /*
+   * Framing overrides for this scenario's pages. Optional like everything above it, and
+   * inert when absent: the defaults are the constants the camera has always used.
+   *
+   * Note this is read only when the camera is on at all (`--camera zoom`). A scenario
+   * recorded flat carries these harmlessly.
+   */
+  camera: ScenarioCameraSchema.optional()
+});
+
+// ../schema/src/manifest.ts
+import { z as z4 } from "zod";
+var Sha256 = z4.string().regex(/^[0-9a-f]{64}$/);
+var BundleManifestSchema = z4.object({
+  schema: z4.literal("agent-demo.bundle/v1"),
+  status: z4.enum(["passed", "failed"]),
+  scenario: z4.object({ id: z4.string().min(1), sourceSha256: Sha256 }),
+  toolchain: z4.object({
+    node: z4.string(),
+    playwright: z4.string(),
+    chromiumRevision: z4.string(),
+    ffmpeg: z4.string(),
+    /** May be the literal "unknown" — never a fabricated version. */
+    libass: z4.string(),
+    fontSha256: Sha256,
+    containerImage: z4.string().optional()
+  }),
+  environment: z4.object({
+    os: z4.string(),
+    /** Part of the reproducibility claim: byte-identity holds per architecture. */
+    architecture: z4.string(),
+    locale: z4.literal("en-US"),
+    timezone: z4.literal("UTC"),
+    viewport: z4.tuple([z4.literal(1920), z4.literal(1080)]),
+    deviceScaleFactor: z4.literal(1)
+  }),
+  assertions: z4.array(z4.object({ id: z4.string().min(1), status: z4.enum(["passed", "failed"]) })),
+  artifacts: z4.array(
+    z4.object({
+      path: z4.string().regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/, "must be a relative POSIX path"),
+      sha256: Sha256,
+      bytes: z4.number().int().nonnegative(),
+      role: z4.enum(["source", "derived"])
+    })
+  )
+});
+
+// ../schema/src/render-plan.ts
+import { z as z5 } from "zod";
+var CueSchema = z5.object({
+  id: z5.string().min(1),
+  startMs: z5.number().int().nonnegative(),
+  endMs: z5.number().int().positive(),
+  lines: z5.array(z5.string()).min(1).max(2)
+});
+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),
+  backgroundColor: HEX_COLOUR,
+  textColor: HEX_COLOUR,
+  assPath: z5.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),
+  backgroundColor: HEX_COLOUR,
+  textColor: HEX_COLOUR,
+  assPath: z5.literal("captions/intro.ass")
+});
+var ChapterMarkSchema = z5.object({
+  startMs: z5.number().int().nonnegative(),
+  endMs: z5.number().int().positive(),
+  title: z5.string().min(1)
+});
+var ChaptersSchema = z5.object({
+  metadataPath: z5.literal("render/chapters.ffmetadata"),
+  marks: z5.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)
+  ),
+  {
+    // Contiguity is enforced rather than tolerated: a gap or an overlap produces a
+    // chapter list that players render inconsistently, and there is no legitimate way
+    // for the derivation to generate one.
+    message: "marks must start at 0 and tile the content contiguously",
+    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(),
+  /**
+   * 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.
+   */
+  scale: z5.number().int().min(1).max(100).optional()
+});
+var CursorSchema = z5.object({
+  assPath: z5.literal("captions/cursor.ass"),
+  points: z5.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)
+  ),
+  {
+    // The derivation emits points in event order, one per targeted step, so an overlap
+    // or an out-of-order point can only mean the derivation is broken — fail the plan
+    // rather than render a cursor that travels backwards in time.
+    message: "points must be ordered, arrive before departing, and not overlap",
+    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 CameraSchema = z5.object({
+  commandPath: z5.literal("render/camera.cmd"),
+  shots: z5.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
+    // either cannot silently reintroduce M10's odd-geometry masking.
+    shot.w % 2 === 0 && shot.h % 2 === 0 && shot.w % 32 === 0 && shot.h === shot.w * 9 / 16 && shot.x + shot.w <= 1920 && shot.y + shot.h <= 1080
+  ),
+  {
+    // Odd geometry is silently masked down on yuv420p (M10), and a window that is not
+    // exact 16:9 or leaves the 1920x1080 frame cannot feed the `scale=1920:1080` the
+    // camera command is built around. Reject at parse time rather than discover it in
+    // a rendered frame.
+    message: "every shot window must be even in x, y, w and h (M10), w a multiple of 32, h exactly 9w/16, and inside the 1920x1080 frame",
+    path: ["shots"]
+  }
+).refine(
+  ({ shots }) => shots[0]?.enterMs === 0 && shots[0]?.holdFromMs === 0 && shots[0]?.x === 0 && shots[0]?.y === 0 && shots[0]?.w === 1920 && shots[0]?.h === 1080 && shots.every(
+    (shot, index) => shot.holdFromMs >= shot.enterMs && (index === 0 || shots[index - 1].holdFromMs <= shot.enterMs)
+  ),
+  {
+    // The shots are the timeline: a gap between one shot's hold and the next shot's
+    // ease would leave the previous window on screen with nothing frozen saying so, and
+    // pinning shot 0 to the full frame keeps "no zoom yet" a shot rather than an
+    // implicit default the renderer would have to know about.
+    message: "shots must tile the timeline: shot 0 is the full frame held from 0, each shot enters at or after the previous shot is held, and no ease ends before it starts",
+    path: ["shots"]
+  }
+);
+var SpeechClipSchema = z5.object({
+  id: z5.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
+   * the same thing at the point of use; this says it at the point of freezing.
+   *
+   * The grammar is deliberately a *subset* of `assertBundleRelative`'s, which is why `:` is
+   * excluded even though a file name may legally contain one. A colon is forbidden in any path
+   * that reaches an FFmpeg argument, and two guards that disagree are worse than either alone:
+   * the looser one is upstream, so a plan carrying `speech/clips/step:3.wav` would parse, be
+   * frozen, and only then be refused at render time — a whole recording thrown away for a
+   * 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"])
+});
+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 SpeechSchema = z5.object({
+  trackPath: z5.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
+   * format: that package depends on this one for `DemoError`, so importing it back would
+   * 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),
+  engine: SpeechEngineSchema.optional()
+}).refine(
+  ({ clips }) => new Set(clips.map((clip) => clip.id)).size === clips.length && clips.every(
+    (clip, index) => index === 0 || clips[index - 1].atMs + clips[index - 1].durationMs <= clip.atMs
+  ),
+  {
+    /*
+     * Ordered and non-overlapping, enforced rather than tolerated — which is also what makes
+     * the mixer a *layout* rather than a mix, with no summing, no clipping and no limiter to
+     * make deterministic. Two clips overlapping would be two voices talking over each other,
+     * which no derivation should ever produce: the recorder holds each step open for its own
+     * clip. Duplicate ids would collide on one file path.
+     */
+    message: "clips must have unique ids and be laid out in order without overlapping",
+    path: ["clips"]
+  }
+).refine(({ clips, engine }) => engine !== void 0 || clips.every((clip) => clip.source === "file"), {
+  // A synthesised clip with no record of what synthesised it is the one state this block
+  // exists to prevent. The converse is fine: an engine recorded on an all-file track is
+  // merely redundant, not misleading.
+  message: "engine must be recorded whenever any clip was synthesised",
+  path: ["engine"]
+});
+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()
+  }),
+  video: z5.object({
+    width: z5.literal(1920),
+    height: z5.literal(1080),
+    fps: z5.literal(30),
+    pixelFormat: z5.literal("yuv420p"),
+    /*
+     * Everything before the closing card: the opening card, if there is one, plus the
+     * recorded content. Not the content alone.
+     *
+     * That is the definition the rest of the plan already depends on, rather than a
+     * convenience. Every other timestamp here — cue, cursor point, camera shot, chapter
+     * mark — is an offset into the finished video, so the number they are bounded by has to
+     * be one too. It is also where the outro starts (`writeCaptions`), where the cursor and
+     * camera tracks are told the picture ends, and what the last chapter mark tiles up to;
+     * defining it as the content alone would have put an intro's length into all four
+     * call sites separately.
+     *
+     * 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()
+  }),
+  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)
+  }),
+  /**
+   * How the burned-in captions were drawn. This is the **source** of
+   * `captions/captions.ass` rather than a note written alongside it, so a bundle describes
+   * its own appearance and the two cannot disagree.
+   *
+   * Every field added here carries a default, and each default is the value that preceded
+   * it: an opaque outline, no box, `BorderStyle 1`. A plan frozen before this therefore
+   * parses to exactly the style it was rendered with. It was never a compatibility event in
+   * either direction — a render consumes the frozen ASS file rather than this block, so an
+   * 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(),
+    /** 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),
+    boxColor: HEX_COLOUR.default("#000000"),
+    /*
+     * Opaque, which under the `BorderStyle 1` default draws nothing at all: `BackColour` is
+     * the *shadow* colour there, and `Shadow` is 0. `&H00000000` is both the historical value
+     * 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)
+  }),
+  ffmpeg: z5.object({
+    base: z5.array(z5.string()),
+    soft: z5.array(z5.string()),
+    hard: z5.array(z5.string())
+  }),
+  intro: IntroSchema.optional(),
+  outro: OutroSchema.optional(),
+  chapters: ChaptersSchema.optional(),
+  cursor: CursorSchema.optional(),
+  camera: CameraSchema.optional(),
+  speech: SpeechSchema.optional()
+});
+
+// ../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);
+var envelope = (kind) => ({
+  schema: z6.literal("agent-demo.result/v1"),
+  kind: z6.literal(kind),
+  ok: z6.boolean(),
+  /** Human-readable failures. Empty iff ok. */
+  problems: z6.array(z6.string())
+});
+var ArtifactRefSchema = z6.object({
+  path: RELATIVE_POSIX,
+  sha256: Sha2562,
+  bytes: z6.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(),
+    /**
+     * 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()
+  }),
+  subtitles: z6.array(z6.object({ codec: z6.string(), language: z6.string(), title: z6.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()
+    })
+  ),
+  /** 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()
+    })
+  )
+});
+var ToolchainSchema = z6.object({
+  node: z6.string(),
+  playwright: z6.string(),
+  chromiumRevision: z6.string(),
+  ffmpeg: z6.string(),
+  /** May be the literal "unknown" — never fabricated. */
+  libass: z6.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({
+  ...envelope("validate"),
+  /** Absent when the scenario could not be loaded at all. */
+  scenario: z6.object({
+    id: z6.string(),
+    title: z6.string(),
+    language: z6.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"),
+    sha256: Sha2562
+  }).optional()
+});
+var RunCommandResultSchema = z6.object({
+  ...envelope("run"),
+  bundleDir: DISPLAY_PATH,
+  status: StatusSchema,
+  cueCount: z6.number().int().nonnegative(),
+  /** Zero on the Free Tier, and zero for a scenario with no `chapter` calls. */
+  chapterCount: z6.number().int().nonnegative(),
+  /**
+   * How many lines the video speaks. Zero for a silent run, which is the default.
+   *
+   * The only place this fact surfaces. A narrated bundle is otherwise indistinguishable from a
+   * silent one without probing the MP4 — and the failure worth catching is `--speech on` on a
+   * 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)
+});
+var RenderCommandResultSchema = z6.object({
+  ...envelope("render"),
+  bundleDir: DISPLAY_PATH,
+  variants: VariantsSchema,
+  streams: z6.object({
+    base: StreamSummarySchema.optional(),
+    soft: StreamSummarySchema.optional(),
+    hard: StreamSummarySchema.optional()
+  }),
+  outputs: z6.array(ArtifactRefSchema)
+});
+var VerificationReportSchema = z6.object({
+  ...envelope("verify"),
+  bundleDir: DISPLAY_PATH,
+  artifactCount: z6.number().int().nonnegative()
+});
+var InspectResultSchema = z6.object({
+  ...envelope("inspect"),
+  bundleDir: DISPLAY_PATH,
+  status: StatusSchema,
+  scenario: z6.object({ id: z6.string(), sourceSha256: Sha2562 }),
+  toolchain: ToolchainSchema,
+  video: z6.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(),
+    /**
+     * 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
+     * leaving the reader to subtract.
+     *
+     * **These do not sum to `durationMs` exactly.** `durationMs` is measured from the
+     * rendered container while these come from the plan, and 361 frames at 30fps is 12,033ms
+     * against a planned 12,034 — under one frame of rounding. No probe of the finished MP4
+     * can separate content frames from card frames, so the split has to be declared.
+     *
+     * `contentDurationMs` is the recording alone, with both cards taken off — which is what
+     * 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()
+  }),
+  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()
+  }),
+  /** 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() })),
+  /**
+   * The narration this bundle carries, or absent for a silent one.
+   *
+   * Absent rather than a zero-clip object, matching the plan field it is read from — and matching
+   * what the distinction means: a silent bundle has no narration, not an empty one.
+   *
+   * `voice` is present only when something was synthesised. An author-supplied voiceover has no
+   * 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(),
+    /** Total speech, excluding the silence between clips. Not the video's length. */
+    spokenMs: z6.number().int().nonnegative(),
+    /** How many clips the author supplied rather than the model producing. */
+    suppliedCount: z6.number().int().nonnegative(),
+    voice: z6.string().optional()
+  }).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(),
+  /** Everything the manifest accounts for. What "delete this bundle" would reclaim. */
+  bundleBytes: z6.number().int().nonnegative()
+});
+var DoctorResultSchema = z6.object({
+  ...envelope("doctor"),
+  /**
+   * The PlainTake build this is. Here rather than in `ToolchainSchema` on purpose:
+   * that record is written into a bundle and hashed, so a version in it would change every
+   * 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(),
+  /**
+   * Whether this FFmpeg can encode AAC, which is what a narrated bundle is muxed with.
+   *
+   * Reported but **not** folded into `problems`, so its absence never fails `doctor`. AAC is
+   * needed by a bundle that carries narration and by nothing else, so a build without it is
+   * perfectly usable for the silent default — and `toolchainProblems` already refuses the render
+   * 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()),
+  /**
+   * Whether spoken narration could be produced right now, and what is missing if not.
+   *
+   * Separate from `problems` for the same reason as `hasAac`: the voice model is a one-time
+   * opt-in download, so its absence is a *state*, not a fault. `ready` is the same question
+   * `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(),
+    /** Installed voices, in catalogue order. Empty means the model cannot speak yet. */
+    voices: z6.array(z6.string()),
+    /** What is missing, in the same words a refused run would use. Empty when ready. */
+    notes: z6.array(z6.string())
+  })
+});
+var okMatchesProblems = (value) => value.ok === (value.problems.length === 0);
+var ActivateReasonSchema = z6.enum([
+  "empty-key",
+  "not-found",
+  "revoked",
+  "offline",
+  "unexpected-response",
+  "not-configured"
+]);
+var ActivateResultSchema = z6.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()
+  }).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
+  // switch on `ok` and know which optional fields exist without checking each one.
+  (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({
+    ...envelope("licence"),
+    tier: z6.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()
+  }),
+  z6.object({
+    ...envelope("licence"),
+    tier: z6.literal("pro"),
+    subject: z6.string().min(1),
+    activatedAt: z6.string().min(1),
+    uses: z6.number().int().nonnegative()
+  })
+]).refine(okMatchesProblems, "ok must be true iff problems is empty");
+
+// ../schema/src/zod-format.ts
+import { ZodError } from "zod";
+function isZodError(error) {
+  return error instanceof ZodError;
+}
+function formatZodError(error) {
+  return error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+}
+
+// src/define.ts
+function defineDemo(input) {
+  if (typeof input?.run !== "function") {
+    throw new DemoError("usage", "defineDemo requires a run function");
+  }
+  if (input.preflight !== void 0 && typeof input.preflight !== "function") {
+    throw new DemoError("usage", "defineDemo: preflight must be a function when present");
+  }
+  if (input.warmup !== void 0 && typeof input.warmup !== "function") {
+    throw new DemoError("usage", "defineDemo: warmup must be a function when present");
+  }
+  let meta;
+  try {
+    meta = ScenarioMetaSchema.parse(input);
+  } catch (error) {
+    if (isZodError(error)) throw new DemoError("usage", formatZodError(error));
+    throw error;
+  }
+  return {
+    ...meta,
+    run: input.run,
+    // Re-attached conditionally, so a scenario without one has no `preflight` key at all
+    // rather than a key whose value is `undefined` — `record()` tests for the key.
+    // `warmup` follows the same rule for the same reason.
+    ...input.preflight === void 0 ? {} : { preflight: input.preflight },
+    ...input.warmup === void 0 ? {} : { warmup: input.warmup }
+  };
+}
+export {
+  defineDemo
+};