@plaintake/scenario 1.7.0 → 1.9.0

package/dist/index.js

@@ -51,7 +51,18 @@ var DemoEventTypeSchema = z.enum([
    * `step.start`/`step.finish` exactly as before; the `actor` field below records which
    * actor performed the step.
    */
-  "turn"
+  "turn",
+  /*
+   * A full-frame motion-graphics cut-away: `demo.explain(...)` stops the screencast, splices
+   * in a PlainMotion-rendered scene at this point on the timeline, and resumes the recording
+   * on the same page, same actor. A member of its own for the same reason `turn` is one: a
+   * cut-away is not a step — no target, no verb, no hold — and its `payload` carries the
+   * whole authored request (id, narration, scene props, cues) because the scene is compiled
+   * from that payload *after* capture ends, never drawn live. The event marks the boundary
+   * the way a `turn` marks its hand-off, so a run that dies mid-explain leaves a log that
+   * says where the cut was going to fall.
+   */
+  "explain"
 ]);
 var TargetSchema = z.object({
   role: z.string().optional(),
@@ -97,7 +108,34 @@ var ScenarioCameraSchema = z2.object({
   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()
+  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(),
+  /*
+   * The voices this scenario may switch to mid-run, beyond the run-wide default `--voice`
+   * picks. A step names one with `demo.step({ voice })` or an actor with `demo.actor(id,
+   * { voice })`; a name that is not the default and not in this list is refused at record
+   * time with the fix in the message.
+   *
+   * Declared up front rather than discovered as steps run, for the same reason `handoff`
+   * is: the worker is configured with its voice list once, before Chromium starts, and an
+   * unknown voice found mid-recording would be minutes of footage thrown away over a list
+   * the scenario could have stated in its metadata. Declaring them also lets `openNarrator`
+   * preflight every voice's `.bin` eagerly, so a missing download is a refusal before the
+   * browser opens, not a dead step 40 seconds into a capture.
+   *
+   * Memory is why the list is the author's to keep short: the engine pre-loads every voice
+   * in this list the moment it opens (the first synthesised step) and holds them until the
+   * narrator closes. One voice measures ~500 MB resident, a second loaded alongside it
+   * ~750 MB — roughly +250 MB per additional voice, not 500 MB times the count. A scenario
+   * that declares voices but supplies a WAV for every step never opens the engine at all and
+   * pays none of this. `min(1)` because an empty list can only be a mistake — it is
+   * indistinguishable from declaring nothing, which is `undefined`'s job.
+   *
+   * One language per run: every voice named here, the default included, must map to the same
+   * language, derived from the voice's prefix (`speechLanguageOfRun` in `@plaintake/speech`).
+   * A mix is refused at record time with both sides named — the run's pronunciation
+   * dictionary is configured once, for the one language it speaks.
+   */
+  voices: z2.array(z2.string().min(1, "speech.voices entries must be non-empty voice names")).min(1, "speech.voices must name at least one voice \u2014 an empty list declares nothing, so omit it").optional()
 });
 var ScenarioMetaSchema = z2.object({
   schema: z2.literal("agent-demo.scenario/v1"),
@@ -207,7 +245,14 @@ var BundleManifestSchema = z4.object({
     /** May be the literal "unknown" — never a fabricated version. */
     libass: z4.string(),
     fontSha256: Sha256,
-    containerImage: z4.string().optional()
+    containerImage: z4.string().optional(),
+    /**
+     * The plainmotion CLI's own `--version` string, present exactly when a scenario called
+     * `demo.explain()` at least once — a run that never cut away never spawned it, and
+     * `containerImage`'s own optionality is the precedent for saying so with an absent field
+     * rather than a fabricated one.
+     */
+    plainmotion: z4.string().optional()
   }),
   environment: z4.object({
     os: z4.string(),
@@ -385,6 +430,11 @@ var TransitionCardSchema = z5.object({
   textColor: HEX_COLOUR,
   assPath: z5.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 HighlightRectSchema = z5.object({
   id: z5.string().min(1),
   x: z5.number().int().min(0),
@@ -432,7 +482,23 @@ var SpeechClipSchema = z5.object({
   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"])
+  source: z5.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
+   * author-supplied clip — a `file` clip has no synthesiser, so there is no voice to record,
+   * and inventing the engine's would be the same lie `SpeechEngineSchema`'s comment refuses
+   * to tell about `modelSha256`.
+   *
+   * Evidence only, like the whole `engine` block: nothing reads it to make a decision. It is
+   * the per-clip answer to "this clip sounds different from its neighbours, why", which a
+   * mixed-voice bundle could not otherwise give — the engine block names one voice, and the
+   * WAV cannot be asked.
+   *
+   * 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()
 });
 var SpeechEngineSchema = z5.object({
   name: z5.string().min(1),
@@ -468,10 +534,12 @@ var SpeechSchema = z5.object({
     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"), {
+).refine(({ clips, engine }) => engine !== void 0 || clips.every((clip) => clip.source !== "synth"), {
   // 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.
+  // merely redundant, not misleading. An `explain` clip is exempt rather than overlooked:
+  // it was synthesised by plainmotion, whose identity the manifest's toolchain block
+  // carries — the `engine` here would name a synthesiser that never touched it.
   message: "engine must be recorded whenever any clip was synthesised",
   path: ["engine"]
 });
@@ -663,49 +731,98 @@ var RenderPlanSchema = z5.object({
   highlight: HighlightSchema.optional(),
   speech: SpeechSchema.optional(),
   /**
-   * The multi-actor demo's cast, its capture timeline cut into per-actor windows, the
-   * cards drawn at each hand-off, and the badge track naming the active actor throughout —
-   * four fields that carry one capability and so, like every other optional block above,
-   * are present or absent together (enforced by the first refinement below). Absent means
-   * a single-actor demo, which is every plan before this and the default after it.
+   * The capture timeline cut into windows — of a genuine multi-actor cast, of an implicit
+   * single actor pausing for explain cut-aways, or both at once. `segments` is the one
+   * field of the five below that a segmented capture *always* carries; the other four are
+   * two independent, narrower capabilities layered on top of it:
+   *
+   * - `actors`/`transitionCards`/`badgesAssPath` — the multi-actor demo's cast, the cards
+   *   drawn at each hand-off, and the badge track naming the active actor throughout. Three
+   *   fields that carry one capability and so, like every other optional block above, are
+   *   present or absent together (the first refinement below) — and never without
+   *   `segments`, which they reference by `actorId` (the second). Absent means no genuine
+   *   cast: every explain-only demo, and every plan before multi-actor demos existed.
+   * - `explainSegments` — the frozen scenes cut into the gaps between `segments`, present
+   *   whenever a scenario called `demo.explain()` at all, with or without a cast alongside
+   *   it — never without `segments` either (the third refinement), for the same reason.
+   *
+   * Every gap between adjacent `segments` is claimed by exactly one occupant, a card or an
+   * explain scene, never both and never neither (the fifth refinement) — which is also why
+   * `segments` can appear with `transitionCards` and `explainSegments` both absent only when
+   * `segments.length === 1` never occurs (`SegmentSchema`'s own `.min(2)` on the array rules
+   * 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()
+  badgesAssPath: z5.literal("captions/badges.ass").optional(),
+  explainSegments: z5.array(ExplainSegmentPlanSchema).min(1).optional()
 }).refine(
   (plan) => {
-    const capabilityFields = [plan.actors, plan.segments, plan.transitionCards, plan.badgesAssPath];
-    return capabilityFields.every((field) => field !== void 0) || capabilityFields.every((field) => field === void 0);
+    const castFields = [plan.actors, plan.transitionCards, plan.badgesAssPath];
+    return castFields.every((field) => field !== void 0) || castFields.every((field) => field === void 0);
   },
   {
     // The same "carries its capability" discipline every optional block above already
     // follows: a plan naming actors with nowhere to draw their badges (or vice versa)
     // cannot render, so it is refused at the parse rather than discovered mid-encode.
-    message: "actors, segments, transitionCards and badgesAssPath must be present together or absent together",
+    message: "actors, transitionCards and badgesAssPath must be present together or absent together",
     path: ["actors"]
   }
+).refine((plan) => plan.actors === void 0 || plan.segments !== void 0, {
+  // A cast with nowhere to draw its own windows — `segment.actorId` is what a badge or a
+  // transition card is drawn against — cannot render.
+  message: "actors requires segments \u2014 a cast with no capture windows of its own cannot render",
+  path: ["actors"]
+}).refine((plan) => plan.explainSegments === void 0 || plan.segments !== void 0, {
+  // An explain scene occupies a gap between two segments; with no segments there is no
+  // gap for it to occupy.
+  message: "explainSegments requires segments \u2014 an explain scene with no gap to occupy cannot render",
+  path: ["explainSegments"]
+}).refine(
+  (plan) => {
+    if (plan.segments === void 0) return true;
+    const { segments } = plan;
+    return segments[0]?.startMs === 0 && segments.every(
+      (segment, index) => segment.endMs > segment.startMs && (index === 0 || segments[index - 1]?.endMs === segment.startMs)
+    );
+  },
+  {
+    // Mirrors `ChaptersSchema`'s own tiling refine: segments must start at 0 and tile the
+    // source contiguously, the same reason a gap or overlap in chapter marks is refused
+    // rather than tolerated — true of every segmented capture, cast or castless alike.
+    message: "segments must tile raw/session.webm contiguously from 0",
+    path: ["segments"]
+  }
+).refine(
+  (plan) => {
+    if (plan.segments === void 0) return true;
+    const gapCount = (plan.transitionCards?.length ?? 0) + (plan.explainSegments?.length ?? 0);
+    return gapCount === plan.segments.length - 1;
+  },
+  {
+    // The count a hand-off or an explain between each pair of adjacent segments implies —
+    // every gap claimed by exactly one occupant, restated here in one refine because
+    // `transitionCards` and `explainSegments` share the gaps between the very same
+    // `segments` array (see `ExplainSegmentPlanSchema`'s own doc on how the renderer tells
+    // the two apart without either array carrying an explicit gap index).
+    message: "transitionCards.length plus explainSegments.length must equal segments.length - 1 \u2014 every gap between segments must be claimed by exactly one card or explain scene",
+    path: ["segments"]
+  }
 ).refine(
   (plan) => {
-    if (plan.actors === void 0 || plan.segments === void 0 || plan.transitionCards === void 0 || plan.badgesAssPath === void 0) {
+    if (plan.actors === void 0 || plan.segments === void 0 || plan.transitionCards === void 0) {
       return true;
     }
     const { actors, segments, transitionCards } = plan;
     const namesDeclaredActor = (actorId) => actors.some((actor) => actor.id === actorId);
-    return transitionCards.length === segments.length - 1 && segments[0]?.startMs === 0 && segments.every(
-      (segment, index) => segment.endMs > segment.startMs && (index === 0 || segments[index - 1]?.endMs === segment.startMs) && namesDeclaredActor(segment.actorId)
-    ) && transitionCards.every(
+    return segments.every((segment) => namesDeclaredActor(segment.actorId)) && transitionCards.every(
       (card) => namesDeclaredActor(card.fromActorId) && namesDeclaredActor(card.toActorId)
     );
   },
   {
-    // Mirrors `ChaptersSchema`'s tiling refine: segments must start at 0 and tile the
-    // source contiguously, the same reason a gap or overlap in chapter marks is refused
-    // rather than tolerated. `transitionCards.length === segments.length - 1` is the
-    // count a hand-off between each pair of adjacent segments implies, and every
-    // `segment.actorId`/`transitionCard.fromActorId`/`transitionCard.toActorId` must name
-    // a declared actor or there is nobody for the recorder to have handed the context to.
-    message: "segments must tile raw/session.webm contiguously from 0, transitionCards.length must equal segments.length - 1, and every segment.actorId, transitionCard.fromActorId and transitionCard.toActorId must name a declared actor",
+    message: "every segment.actorId, transitionCard.fromActorId and transitionCard.toActorId must name a declared actor",
     path: ["segments"]
   }
 );
@@ -869,6 +986,19 @@ var PruneCommandResultSchema = z6.object({
    * be reclaimed if every candidate succeeded. */
   bytesReclaimed: z6.number().int().nonnegative()
 });
+var ImportCommandResultSchema = z6.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(),
+  /** 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(),
+  /** 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())
+});
 var InspectResultSchema = z6.object({
   ...envelope("inspect"),
   bundleDir: DISPLAY_PATH,
@@ -957,6 +1087,22 @@ var InspectResultSchema = z6.object({
      * independently from `segments` for the reason above. */
     turnCount: z6.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
+   * with none — every bundle recorded before `demo.explain()` existed, and still the default
+   * after it, so this stays absent rather than an empty array, the same distinction `actors`
+   * above and `narration` further up both draw.
+   *
+   * Sourced from `plan.explainSegments` alone, never the scenario file, for the same reason
+   * `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()
+    })
+  ).min(1).optional(),
   /** The rendered MP4s, from the manifest, so hashes are not recomputed. */
   outputs: z6.array(ArtifactRefSchema),
   assertions: z6.array(AssertionSchema),
@@ -1003,6 +1149,22 @@ var DoctorResultSchema = z6.object({
     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())
+  }),
+  /**
+   * Whether the plainmotion CLI is on `PATH`, for a scenario that wants to call
+   * `demo.explain()`. The same stance `hasAac`/`speech` above already take: absence is a
+   * *state*, not a fault — the overwhelming majority of scenarios never cut away to an
+   * explain scene, so `doctor` must not fail an otherwise-healthy installation over a binary
+   * most runs will never invoke. `assertPlainmotion` (`recorder-playwright`) is the same
+   * 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's own `--version` output. Absent when not installed. */
+    version: z6.string().optional(),
+    /** Why the probe failed, in the same words a run's own refusal would use. Absent when installed. */
+    note: z6.string().optional()
   })
 });
 var okMatchesProblems = (value) => value.ok === (value.problems.length === 0);

package/dist/schema/event.d.ts

@@ -10,6 +10,7 @@ export declare const DemoEventTypeSchema: z.ZodEnum<{
     "privacy.mask": "privacy.mask";
     "human.wait": "human.wait";
     turn: "turn";
+    explain: "explain";
 }>;
 export declare const TargetSchema: z.ZodObject<{
     role: z.ZodOptional<z.ZodString>;
@@ -38,6 +39,7 @@ export declare const DemoEventSchema: z.ZodObject<{
         "privacy.mask": "privacy.mask";
         "human.wait": "human.wait";
         turn: "turn";
+        explain: "explain";
     }>;
     stableId: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;

package/dist/schema/manifest.d.ts

@@ -17,6 +17,7 @@ export declare const BundleManifestSchema: z.ZodObject<{
         libass: z.ZodString;
         fontSha256: z.ZodString;
         containerImage: z.ZodOptional<z.ZodString>;
+        plainmotion: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     environment: z.ZodObject<{
         os: z.ZodString;

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

@@ -238,6 +238,33 @@ export declare const TransitionCardSchema: z.ZodObject<{
     assPath: z.ZodString;
 }, z.core.$strip>;
 export type TransitionCard = z.infer<typeof TransitionCardSchema>;
+/**
+ * One frozen explain scene's real render file, occupying one of the gaps between `segments`.
+ *
+ * **Never carries an explicit gap index, for the same reason `TransitionCardSchema` never
+ * has: both arrays are purely positional among their own homogeneous class of gap, in
+ * left-to-right gap-encounter order — the same discipline `transitionCards` already keeps.**
+ * Which of the `segments.length - 1` gaps is a card and which is an explain scene follows
+ * deterministically from whether the two segments either side of it share an `actorId`: a
+ * `demo.turn()` boundary always changes who is filming (`runtime.ts` refuses a turn to the
+ * actor already holding the browser), and a `demo.explain()` boundary never does (the same
+ * actor's capture merely pauses for the cut-away) — so an "actor changed" gap is always a
+ * card, and an "actor unchanged" gap is always an explain, and the renderer recovers the
+ * interleaving from that invariant rather than from a stored index. `segments` may also
+ * carry no `actorId` at all — the no-cast, explain-only case — in which every gap is,
+ * necessarily, an explain (there is no hand-off to draw a card for).
+ *
+ * `segmentPath` is the one thing a card's own `assPath` is not: a real file to decode as an
+ * extra input, not a generated `color=` source — `durationMs` is carried alongside for
+ * validation and tooling (`plaintake inspect`), but the file itself is the render's
+ * authority on its own frame count.
+ */
+export declare const ExplainSegmentPlanSchema: z.ZodObject<{
+    id: z.ZodString;
+    segmentPath: z.ZodString;
+    durationMs: z.ZodNumber;
+}, z.core.$strip>;
+export type ExplainSegmentPlan = z.infer<typeof ExplainSegmentPlanSchema>;
 /**
  * How long a `demo.turn(actor, { card })` transition card is on screen when its own
  * `durationMs` was omitted.
@@ -318,6 +345,14 @@ export type HighlightRect = z.infer<typeof HighlightRectSchema>;
  *
  * `source` distinguishes a synthesised clip from an author-supplied WAV, because they are the
  * same bytes by the time they reach here and the distinction is not otherwise recoverable.
+ *
+ * `explain` is the third provenance: a cut-away scene's narration, synthesised by *plainmotion*
+ * at record time rather than by this project's own narrator. It never requires the `engine`
+ * block below, because that block describes one synthesiser — the recorder's kokoro worker —
+ * and these clips were made by the other one; plainmotion's identity is recorded where the
+ * rest of its contribution is, the manifest's toolchain block. The rule the refine below
+ * actually states is "every clip must be accounted for": `synth` is accounted for by `engine`,
+ * `file` by the author who supplied it, `explain` by the toolchain.
  */
 export declare const SpeechClipSchema: z.ZodObject<{
     id: z.ZodString;
@@ -325,9 +360,11 @@ export declare const SpeechClipSchema: z.ZodObject<{
     atMs: z.ZodNumber;
     durationMs: z.ZodNumber;
     source: z.ZodEnum<{
+        explain: "explain";
         file: "file";
         synth: "synth";
     }>;
+    voice: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 /**
  * What produced the synthesised clips. Evidence only — nothing reads it to make a decision,
@@ -369,9 +406,11 @@ export declare const SpeechSchema: z.ZodObject<{
         atMs: z.ZodNumber;
         durationMs: z.ZodNumber;
         source: z.ZodEnum<{
+            explain: "explain";
             file: "file";
             synth: "synth";
         }>;
+        voice: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     engine: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
@@ -611,9 +650,11 @@ export declare const RenderPlanSchema: z.ZodObject<{
             atMs: z.ZodNumber;
             durationMs: z.ZodNumber;
             source: z.ZodEnum<{
+                explain: "explain";
                 file: "file";
                 synth: "synth";
             }>;
+            voice: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         engine: z.ZodOptional<z.ZodObject<{
             name: z.ZodString;
@@ -642,6 +683,11 @@ export declare const RenderPlanSchema: z.ZodObject<{
         assPath: z.ZodString;
     }, z.core.$strip>>>;
     badgesAssPath: z.ZodOptional<z.ZodLiteral<"captions/badges.ass">>;
+    explainSegments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        segmentPath: z.ZodString;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type RenderPlan = z.infer<typeof RenderPlanSchema>;
 export type Cue = z.infer<typeof CueSchema>;

package/dist/schema/results.d.ts

@@ -281,6 +281,37 @@ export declare const PruneCommandResultSchema: z.ZodObject<{
     ok: z.ZodBoolean;
     problems: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * `import <trace.zip> --output <draft.demo.ts>`'s result. The trace is a Playwright
+ * recording from any suite, not necessarily PlainTake's own; the output is a *draft*
+ * scenario the author is expected to edit, and every field here exists to say how far
+ * short of finished it is.
+ *
+ * **`ok`/`problems` mean "a draft was written", nothing more.** A draft that does not
+ * parse yet is still a successful import — `validates: false` carries that verdict, the
+ * same way `diff`'s `ok` is deliberately untied from `identical`. The two honest failure
+ * classes are an unreadable or corrupt zip (exit 6, `diff`'s code for "artifacts could
+ * not be read back out") and a readable trace with no importable action in it (exit 1 —
+ * the content failed, not the container).
+ *
+ * `warnings` is deliberately not `problems`: multi-page traces, redacted values,
+ * unimported methods and the standing review-for-secrets note are things the author must
+ * know to act on, not faults that made the command lie about having run. Every result
+ * carries at least one warning — "the trace records everything typed, review before
+ * committing" — because a draft that silently embedded a typed password would be worse
+ * than one that loudly asks to be read.
+ */
+export declare const ImportCommandResultSchema: z.ZodObject<{
+    tracePath: z.ZodString;
+    outputPath: z.ZodString;
+    stepCount: z.ZodNumber;
+    validates: z.ZodBoolean;
+    warnings: z.ZodArray<z.ZodString>;
+    schema: z.ZodLiteral<"agent-demo.result/v1">;
+    kind: z.ZodLiteral<"import">;
+    ok: z.ZodBoolean;
+    problems: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 export declare const InspectResultSchema: z.ZodObject<{
     bundleDir: z.ZodString;
     status: z.ZodEnum<{
@@ -332,6 +363,10 @@ export declare const InspectResultSchema: z.ZodObject<{
         labels: z.ZodArray<z.ZodString>;
         turnCount: z.ZodNumber;
     }, z.core.$strip>>;
+    explainScenes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>>>;
     outputs: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         sha256: z.ZodString;
@@ -365,6 +400,11 @@ export declare const DoctorResultSchema: z.ZodObject<{
         voices: z.ZodArray<z.ZodString>;
         notes: z.ZodArray<z.ZodString>;
     }, z.core.$strip>;
+    plainmotion: z.ZodObject<{
+        installed: z.ZodBoolean;
+        version: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
     schema: z.ZodLiteral<"agent-demo.result/v1">;
     kind: z.ZodLiteral<"doctor">;
     ok: z.ZodBoolean;
@@ -418,11 +458,12 @@ 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 ImportCommandResult = z.infer<typeof ImportCommandResultSchema>;
 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 | InspectResult | DoctorResult | ActivateResult | LicenceResult;
+export type DemoResult = ValidationResult | RunCommandResult | CheckCommandResult | RenderCommandResult | VerificationReport | 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

@@ -52,20 +52,15 @@ export declare const ScenarioCameraSchema: z.ZodObject<{
 }, 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.
+ * 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.
  *
- * 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.
+ * 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
+ * framing rather than adding `maxZoom` directly to the metadata object, and it leaves room to
+ * grow if narration ever gains another scenario-level knob without another 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
@@ -77,6 +72,7 @@ export type ScenarioCamera = z.infer<typeof ScenarioCameraSchema>;
  */
 export declare const ScenarioSpeechSchema: z.ZodObject<{
     speed: z.ZodOptional<z.ZodNumber>;
+    voices: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type ScenarioSpeech = z.infer<typeof ScenarioSpeechSchema>;
 export declare const ScenarioMetaSchema: z.ZodObject<{
@@ -113,6 +109,7 @@ export declare const ScenarioMetaSchema: z.ZodObject<{
     }, z.core.$strip>>;
     speech: z.ZodOptional<z.ZodObject<{
         speed: z.ZodOptional<z.ZodNumber>;
+        voices: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
     pronunciations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 }, z.core.$strip>;

package/dist/types.d.ts

@@ -33,6 +33,20 @@ export type DemoStep = {
     highlight?: boolean | {
         label?: string;
     };
+    /**
+     * Speaks this step's subtitle with a different voice than the run-wide default `--voice`
+     * picks. The voice must be one this run declared: either the default, or an entry in the
+     * scenario metadata's `speech.voices` list — anything else is refused at record time with
+     * the declaration named as the fix, rather than surfacing as an unsupported voice minutes
+     * into a recording.
+     *
+     * Precedence is step over actor over default: `demo.actor(id, { voice })` sets the voice
+     * for that actor's every step, and this field overrides it for one step alone. Applies
+     * only to synthesised narration (`--speech on`): an author-supplied WAV (`--speech file`,
+     * or a file in `narration/` that shadows this step) is already recorded audio, and no voice
+     * changes it.
+     */
+    voice?: string;
     /** Extra presentation hold after the action completes, in whole milliseconds. */
     holdMs?: number;
     run: () => Promise<unknown>;
@@ -125,6 +139,142 @@ export type DemoHandoff = PreflightHandoff & {
      */
     mask?: string;
 };
+/**
+ * A node in a `process` explain scene: a step in the flow being drawn. The `id` is the
+ * entity a cue's `target` names, so it is authored and stable — never generated.
+ */
+export type ExplainNode = {
+    id: string;
+    label: string;
+};
+/** A directed edge between two `process` nodes, drawn as the flow it names. */
+export type ExplainConnection = {
+    id: string;
+    from: string;
+    to: string;
+    label?: string;
+};
+/** One side of a `comparison` explain scene: what this alternative is called, and its points. */
+export type ExplainColumn = {
+    heading: string;
+    points: string[];
+};
+/** A named group of imported svg parts a `diagram` scene's cue can target as one thing. */
+export type ExplainRegion = {
+    id: string;
+    of: string[];
+};
+/**
+ * The five motion-graphics scenes an explain cut-away can be, mirroring PlainMotion's scene
+ * registry prop-for-prop (`title`/`process`/`comparison`/`diagram`/`recap`). PlainTake does
+ * not draw these — it compiles each one through the `plainmotion` CLI and splices the frozen
+ * result into the recording — so this union is a structural mirror of PlainMotion's own
+ * schemas, and the deep validation (character caps, list bounds, phrase resolution) belongs
+ * to PlainMotion at run time, not to this package's types. What `validate` checks without a
+ * browser is the shape around the scene: id, narration, a known `type`.
+ *
+ * Geometry is deliberately absent. Where a pixel appears is the scene layout's decision,
+ * exactly as it is in a `plainmotion.yaml`; an author says what exists and what the
+ * narration points at, and nothing about inches.
+ */
+export type ExplainScene = {
+    type: 'title';
+    headline: string;
+    subtitle?: string;
+} | {
+    type: 'process';
+    /** Defaults to `horizontal`. */
+    direction?: 'horizontal' | 'vertical';
+    /** Two to five nodes. */
+    nodes: ExplainNode[];
+    connections?: ExplainConnection[];
+    /** A line above the row, naming the flow. */
+    title?: string;
+    /** A supporting line beneath the row. */
+    caption?: string;
+} | {
+    type: 'comparison';
+    title?: string;
+    left: ExplainColumn;
+    right: ExplainColumn;
+} | {
+    type: 'diagram';
+    /** Path to an svg, relative to the scenario file. Imported as-drawn; only annotated here. */
+    src: string;
+    title?: string;
+    caption?: string;
+    regions?: ExplainRegion[];
+} | {
+    type: 'recap';
+    title?: string;
+    items: string[];
+};
+/**
+ * What a cue does to the viewer's attention. The same vocabulary PlainMotion defines —
+ * deliberately small, and deliberately not easing curves or tween internals: an author says
+ * what should happen; how that is expressed is the renderer's job.
+ */
+export type ExplainCueAction = 'reveal' | 'hide' | 'emphasize' | 'deemphasize' | 'draw' | 'focus';
+/**
+ * When a cue fires: bound to words in the narration, resolved against the timings the speech
+ * model measures. Rewriting a sentence moves the animation with it instead of silently
+ * desynchronising — which is why there is no numeric `at` offset here the way PlainMotion's
+ * own cue schema allows one. An explain scene always speaks (its narration is the scene's
+ * clock), so a phrase is the only anchor that survives a rewording, and an offset that could
+ * not is not offered.
+ *
+ * A phrase that does not occur in the narration is a validation error at run time, never a
+ * no-op.
+ */
+export type ExplainCue = {
+    atPhrase: string;
+    action: ExplainCueAction;
+    target: string;
+};
+/**
+ * A full-frame motion-graphics cut-away in the middle of a browser demo — "explain while
+ * demoing". `demo.explain()` stops the screencast, splices in a PlainMotion-rendered scene
+ * (`title`/`process`/`comparison`/`diagram`/`recap`), and resumes the recording on the same
+ * page: the cut-away is a boundary on the timeline, the same mechanism a multi-actor `turn`
+ * uses, so nothing about the recording's determinism or re-renderability changes. The scene
+ * is compiled and rendered after capture finishes, from a generated one-scene project — the
+ * only inputs that matter are the ones right here.
+ *
+ * Free on every tier, like every authoring verb. Requires the `plainmotion` CLI on `PATH`
+ * at record time (`plaintake doctor` reports whether it is there); a bundle that carries an
+ * explain segment re-renders without it, the same way it re-renders without a browser.
+ */
+export type DemoExplain = {
+    /**
+     * Stable, authored — the same rule every other id here follows. It becomes the directory
+     * the frozen artifacts live in (`explain/<id>/segment.mp4` and its plainmotion plan) and
+     * the generated scene's own id, so it must read as plainmotion ids do: lower-case
+     * alphanumeric and hyphens, starting alphanumeric. Checked at run time, with the offending
+     * id named.
+     */
+    id: string;
+    /** Human label for the cut-away, shown in `inspect` and diagnostics. Not drawn in the video. */
+    title: string;
+    /**
+     * What the scene says. The source of truth for both the audio and the caption — there is
+     * no separate caption field, for the same reason PlainMotion has none: two strings that
+     * are supposed to say the same thing will eventually disagree, and the one the viewer
+     * hears is the one that matters. The measured speech is also the scene's duration: the
+     * cut-away lasts exactly as long as it takes to say this, plus its lead-in and lead-out.
+     */
+    narration: string;
+    /** Which motion-graphics scene to draw, and its content. See `ExplainScene`. */
+    scene: ExplainScene;
+    /** Optional animation cues, bound to phrases of `narration`. See `ExplainCue`. */
+    cues?: ExplainCue[];
+    /**
+     * Speaks this scene's narration with a different voice than the run-wide default `--voice`
+     * picks — the same contract as `DemoStep.voice`: the voice must be one this run declared
+     * (the default, or an entry in `speech.voices`), or the run is refused with the fix named.
+     * Applies only when the engine is doing the speaking (`--speech on`).
+     */
+    voice?: string;
+};
 /**
  * Presentation fields shared by every `Actor` verb below — the same subset of `DemoStep`
  * that is still the caller's to supply once `target` and `action` no longer are: a verb's
@@ -154,6 +304,8 @@ export type ActorStepMeta = {
     highlight?: boolean | {
         label?: string;
     };
+    /** See `DemoStep.voice` — one verb-call override, ahead of this actor's own `voice`. */
+    voice?: string;
 };
 /**
  * A named participant in a multi-actor demo: its own Playwright `BrowserContext`, its own
@@ -287,10 +439,17 @@ export interface DemoContext extends PreflightContext {
      * special-casing the first one: a single-actor scenario written before actors existed keeps
      * working unchanged, and turning it into a two-actor one only costs the second
      * `demo.actor()` call, not a rewrite of the first actor's steps.
+     *
+     * `voice` is the narration half of giving an actor an identity: every step this actor's
+     * verbs record speaks with it, unless the step itself names a different one (see
+     * `DemoStep.voice` for precedence and the `speech.voices` declaration requirement). Like
+     * the first call's other options, it is the one that counts — a second `demo.actor` with
+     * the same id returns the existing actor unchanged.
      */
     actor(id: string, opts?: {
         label?: string;
         contextOptions?: BrowserContextOptions;
+        voice?: string;
     }): Promise<Actor>;
     /**
      * Marks a hand-off from whichever actor currently holds the browser to `actor`, parking the
@@ -315,6 +474,25 @@ export interface DemoContext extends PreflightContext {
             durationMs?: number;
         };
     }): Promise<void>;
+    /**
+     * Cuts away from the browser recording to a full-frame motion-graphics scene — a diagram
+     * of where the key lives, a process flow, a recap — then back to the same page, same
+     * actor, same state. The screencast stops at the boundary and resumes after it, exactly as
+     * a `turn` does minus the actor switch, so the cut-away occupies its own slot on the
+     * timeline and nothing it covers is ever captured.
+     *
+     * The scene is not drawn live: it is compiled and rendered by the `plainmotion` CLI after
+     * capture finishes, from the request's own fields, and spliced in at render time as a
+     * frozen 1920×1080@30 segment — which is what keeps the bundle re-renderable without
+     * `plainmotion`, without a browser, and byte-identically. Its narration is spoken by the
+     * same engine as the rest of the recording (`--speech on`), lands in the same caption
+     * track, and is the scene's clock: the cut-away lasts exactly as long as it takes to say.
+     *
+     * Like a `turn`, an explain is a boundary, never an excision — nothing around it is cut —
+     * and it does not create a chapter; call `demo.chapter()` where you want one. Free on
+     * every tier.
+     */
+    explain(request: DemoExplain): Promise<void>;
 }
 export type DemoRunArgs = {
     page: Page;

package/package.json

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