@plaintake/scenario 1.6.0 → 1.9.0

package/dist/index.js

@@ -42,7 +42,27 @@ var DemoEventTypeSchema = z.enum([
    * 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"
+  "human.wait",
+  /*
+   * An actor hand-off: `demo.turn(actor, ...)` parking the outgoing actor's `BrowserContext`
+   * and activating the incoming one. A member of its own rather than folded into
+   * `step.start`/`step.finish`, because a hand-off is not a step — it has no `target` and
+   * narrates no action of its own. Verb steps taken during a turn keep using
+   * `step.start`/`step.finish` exactly as before; the `actor` field below records which
+   * actor performed the step.
+   */
+  "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(),
@@ -60,7 +80,15 @@ var DemoEventSchema = z.object({
   title: z.string().optional(),
   subtitle: z.string().optional(),
   target: TargetSchema.optional(),
-  payload: z.record(z.string(), z.unknown()).optional()
+  payload: z.record(z.string(), z.unknown()).optional(),
+  /**
+   * Which actor performed this event, for a `turn` hand-off or a verb step taken during one.
+   * Absent means the scenario's default actor — a single-actor event log never sets this, so
+   * it stays byte-identical to every log recorded before actors existed. No `.default()`
+   * here: the default actor's id is an application-layer notion the recorder resolves, not a
+   * value this schema should invent and materialise on parse.
+   */
+  actor: z.string().min(1).optional()
 });
 
 // ../schema/src/json-schema.ts
@@ -80,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"),
@@ -190,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(),
@@ -349,6 +411,30 @@ var CameraSchema = z5.object({
     path: ["shots"]
   }
 );
+var ActorSchema = z5.object({
+  id: z5.string().min(1),
+  label: z5.string().min(1)
+});
+var SegmentSchema = z5.object({
+  id: z5.string().min(1),
+  actorId: z5.string().min(1),
+  startMs: z5.number().int().nonnegative(),
+  endMs: z5.number().int().positive()
+});
+var TransitionCardSchema = z5.object({
+  fromActorId: z5.string().min(1),
+  toActorId: z5.string().min(1),
+  durationMs: z5.number().int().positive().max(15e3),
+  lines: z5.array(z5.string().min(1)).min(1).max(2),
+  backgroundColor: HEX_COLOUR,
+  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),
@@ -396,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),
@@ -432,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"]
 });
@@ -625,8 +729,103 @@ var RenderPlanSchema = z5.object({
   cursor: CursorSchema.optional(),
   camera: CameraSchema.optional(),
   highlight: HighlightSchema.optional(),
-  speech: SpeechSchema.optional()
-});
+  speech: SpeechSchema.optional(),
+  /**
+   * 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(),
+  explainSegments: z5.array(ExplainSegmentPlanSchema).min(1).optional()
+}).refine(
+  (plan) => {
+    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, 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) {
+      return true;
+    }
+    const { actors, segments, transitionCards } = plan;
+    const namesDeclaredActor = (actorId) => actors.some((actor) => actor.id === actorId);
+    return segments.every((segment) => namesDeclaredActor(segment.actorId)) && transitionCards.every(
+      (card) => namesDeclaredActor(card.fromActorId) && namesDeclaredActor(card.toActorId)
+    );
+  },
+  {
+    message: "every segment.actorId, transitionCard.fromActorId and transitionCard.toActorId must name a declared actor",
+    path: ["segments"]
+  }
+);
 
 // ../schema/src/results.ts
 import { z as z6 } from "zod";
@@ -760,7 +959,7 @@ var VerificationReportSchema = z6.object({
   bundleDir: DISPLAY_PATH,
   artifactCount: z6.number().int().nonnegative()
 });
-var DifferenceCategorySchema = z6.enum(["step", "assertion", "target", "timing", "caption"]);
+var DifferenceCategorySchema = z6.enum(["step", "assertion", "target", "timing", "caption", "actor"]);
 var DiffCommandResultSchema = z6.object({
   ...envelope("diff"),
   bundleA: DISPLAY_PATH,
@@ -787,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,
@@ -846,6 +1058,51 @@ var InspectResultSchema = z6.object({
     suppliedCount: z6.number().int().nonnegative(),
     voice: z6.string().optional()
   }).optional(),
+  /**
+   * The multi-actor demo's cast, or absent for a single-actor bundle — every bundle
+   * recorded before actors existed, and still the default for most scenarios after, so
+   * this stays absent rather than a zero-cast object, the same distinction `narration`
+   * above draws between "silent" and "nothing to report".
+   *
+   * Sourced from the frozen plan's `actors`/`segments` fields, never the scenario file:
+   * `inspectCommand` (`apps/cli/src/commands.ts`) reads only the render plan and manifest,
+   * so a bundle whose scenario has since been edited or deleted still inspects correctly.
+   * Not sourced from `plan.transitionCards`, even though `transitionCards.length` and
+   * `segments.length - 1` are provably equal by the render plan's own refinement: `segments`
+   * is the more primal fact — the capture's own cut points — so `turnCount` is derived from
+   * the field a reader of this JSON would already trust as the timeline, not from a second
+   * field that only agrees with it by a schema-level invariant this result does not surface.
+   */
+  actors: z6.object({
+    /** `plan.actors.length`. Reported alongside `labels` rather than left for a caller to
+     * compute, matching `narration.clipCount` sitting beside `narration` above for the
+     * same reason: the count is the fact most callers want first, before the list. */
+    count: z6.number().int().min(2),
+    /** In `plan.actors` order — the cast list a badge or transition card would draw, not
+     * deduplicated or sorted. */
+    labels: z6.array(z6.string().min(1)).min(2),
+    /** Hand-offs, not participants: one fewer than `plan.segments.length`, since a
+     * segment is a window one actor already holds and a turn is the cut between two of
+     * them — the same count `plan.transitionCards.length` carries, arrived at
+     * independently from `segments` for the reason above. */
+    turnCount: z6.number().int().nonnegative()
+  }).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),
@@ -892,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

@@ -9,6 +9,8 @@ export declare const DemoEventTypeSchema: z.ZodEnum<{
     "assertion.fail": "assertion.fail";
     "privacy.mask": "privacy.mask";
     "human.wait": "human.wait";
+    turn: "turn";
+    explain: "explain";
 }>;
 export declare const TargetSchema: z.ZodObject<{
     role: z.ZodOptional<z.ZodString>;
@@ -36,6 +38,8 @@ export declare const DemoEventSchema: z.ZodObject<{
         "assertion.fail": "assertion.fail";
         "privacy.mask": "privacy.mask";
         "human.wait": "human.wait";
+        turn: "turn";
+        explain: "explain";
     }>;
     stableId: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
@@ -52,6 +56,7 @@ export declare const DemoEventSchema: z.ZodObject<{
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    actor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type DemoEvent = z.infer<typeof DemoEventSchema>;
 export type DemoEventType = z.infer<typeof DemoEventTypeSchema>;

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

@@ -190,6 +190,104 @@ export declare const CameraSchema: z.ZodObject<{
 }, z.core.$strip>;
 export type Camera = z.infer<typeof CameraSchema>;
 export type CameraShot = z.infer<typeof CameraShotSchema>;
+/**
+ * One participant in a multi-actor demo, each with its own Playwright `BrowserContext` —
+ * `AGENTS.md` §1 constraint 3 guarantees at most one is ever active at a single instant.
+ * `id` is what `SegmentSchema.actorId` and `TransitionCardSchema.fromActorId`/`toActorId`
+ * reference; `label` is the human-readable name a badge or a transition card draws.
+ */
+export declare const ActorSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+}, z.core.$strip>;
+export type Actor = z.infer<typeof ActorSchema>;
+/**
+ * One contiguous window of `raw/session.webm` during which a single actor held the (one,
+ * at most) active `BrowserContext`. `startMs`/`endMs` are source-relative — the same space
+ * `source.durationMs` and the `trim=duration=...` FFmpeg argument already operate in — not
+ * a file path: the concatenation of raw capture segments into the one `raw/session.webm`
+ * this plan's `source` names has already happened by the time this schema is populated, so
+ * there is deliberately no `rawFile`/path field here, unlike what an earlier design draft
+ * suggested. A segment describes how that single file is internally structured, never a
+ * second file to read.
+ */
+export declare const SegmentSchema: z.ZodObject<{
+    id: z.ZodString;
+    actorId: z.ZodString;
+    startMs: z.ZodNumber;
+    endMs: z.ZodNumber;
+}, z.core.$strip>;
+export type Segment = z.infer<typeof SegmentSchema>;
+/**
+ * A full-frame card drawn between two actors' segments on a hand-off — structurally
+ * `Intro`/`Outro`'s sibling, down to the same `HEX_COLOUR` injection guard on its colours,
+ * plus which actor is handing off to which.
+ *
+ * Unlike the single well-known `captions/intro.ass`/`captions/outro.ass`, a demo can have
+ * many hand-offs, so `assPath` cannot be one literal. It is a regex-constrained family
+ * instead — `SpeechClipSchema.path`'s discipline applied to its own N-member family:
+ * constrained enough that no filtergraph metacharacter or path traversal is representable.
+ */
+export declare const TransitionCardSchema: z.ZodObject<{
+    fromActorId: z.ZodString;
+    toActorId: z.ZodString;
+    durationMs: z.ZodNumber;
+    lines: z.ZodArray<z.ZodString>;
+    backgroundColor: z.ZodString;
+    textColor: z.ZodString;
+    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.
+ *
+ * Lives here, beside `TransitionCardSchema`, rather than in either package that resolves it:
+ * `packages/recorder-playwright/src/pipeline.ts`'s `transitionCardDurationMs` reads it at
+ * derivation time, before `transitionCards` exists, to offset later segments; the renderer
+ * that eventually draws a frozen `RenderPlanSchema.transitionCards` entry with no
+ * `durationMs` of its own needs the same number. `AGENTS.md` §2 forbids `renderer-ffmpeg`
+ * from importing `recorder-playwright` (the reverse edge already exists, so importing back
+ * would be the cycle `no-circular` refuses), so a bare constant defined in either package
+ * would be unreachable from the other — both already depend on `@plaintake/schema`, which is
+ * why it is defined here instead.
+ *
+ * Matches `DEFAULT_INTRO_MS` and `FREE_TIER_OUTRO.durationMs`
+ * (`packages/license/src/branding.ts`), both already 3000ms for the same shape of decision —
+ * a full-frame card with a line or two to read, defaulted absent an author- or
+ * configuration-supplied length. Not imported from `@plaintake/license`: that package
+ * resolves *licensed* branding, and a transition card is never licence-gated (the camera is
+ * the one capability still Pro-gated; see `AGENTS.md`), so a shared import would be the wrong
+ * fix for a coincidence, not a rule the two packages share.
+ */
+export declare const TRANSITION_CARD_DEFAULT_MS = 3000;
 /**
  * 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
@@ -247,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;
@@ -254,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,
@@ -298,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;
@@ -339,6 +449,14 @@ export type HighlightInput = Omit<Highlight, 'assPath'>;
 export type OutroInput = Omit<Outro, 'assPath'>;
 /** The opening card as the application layer supplies it, exactly as `OutroInput` works. */
 export type IntroInput = Omit<Intro, 'assPath'>;
+/**
+ * The transition card decision as the application layer supplies it — `pipeline.ts`, in
+ * practice, which resolves a hand-off's concrete `durationMs` via `transitionCardDurationMs`
+ * before this is ever built, exactly as `intro`/`outro` durations are resolved before
+ * `buildRenderPlan` is called. `assPath` is filled in by `buildRenderPlan`, indexed by
+ * position in the array against the schema's own `captions/turn-[0-9]+\.ass` family.
+ */
+export type TransitionCardInput = Omit<TransitionCard, 'assPath'>;
 /**
  * The one value a plan's `schema` field ever holds.
  *
@@ -532,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;
@@ -543,6 +663,31 @@ export declare const RenderPlanSchema: z.ZodObject<{
             voice: z.ZodString;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    actors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+    }, z.core.$strip>>>;
+    segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        actorId: z.ZodString;
+        startMs: z.ZodNumber;
+        endMs: z.ZodNumber;
+    }, z.core.$strip>>>;
+    transitionCards: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        fromActorId: z.ZodString;
+        toActorId: z.ZodString;
+        durationMs: z.ZodNumber;
+        lines: z.ZodArray<z.ZodString>;
+        backgroundColor: z.ZodString;
+        textColor: z.ZodString;
+        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

@@ -228,6 +228,7 @@ export declare const DiffCommandResultSchema: z.ZodObject<{
         category: z.ZodEnum<{
             assertion: "assertion";
             target: "target";
+            actor: "actor";
             step: "step";
             timing: "timing";
             caption: "caption";
@@ -280,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<{
@@ -326,6 +358,15 @@ export declare const InspectResultSchema: z.ZodObject<{
         suppliedCount: z.ZodNumber;
         voice: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
+    actors: z.ZodOptional<z.ZodObject<{
+        count: z.ZodNumber;
+        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;
@@ -359,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;
@@ -412,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

@@ -1,12 +1,13 @@
 import type { ScenarioMeta } from './schema/index.js';
-import type { Locator, Page } from 'playwright-core';
+import type { BrowserContextOptions, Locator, Page } from 'playwright-core';
 /**
  * What kind of interaction `run()` performs, declared rather than observed. Like
  * `target`, this is metadata the recorder records and never performs — it tells the
- * cursor track what to draw at the target (`click` a ripple, `type`/`point` a settle).
- * Absent means `point`: the cursor still moves to the target, nothing pulses.
+ * cursor track what to draw at the target (`click` a ripple, `type`/`point`/`scroll` a
+ * settle — none of the three pulse, only `click` does). Absent means `point`: the cursor
+ * still moves to the target, nothing pulses.
  */
-export type DemoAction = 'click' | 'type' | 'point';
+export type DemoAction = 'click' | 'type' | 'point' | 'scroll';
 export type DemoStep = {
     id: string;
     title: string;
@@ -32,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>;
@@ -124,6 +139,262 @@ 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
+ * argument list already gives the target (when it has one), and the verb's own name already
+ * gives the action. Only how the step presents is left to ask for.
+ *
+ * `title` is optional here where `DemoStep.title` is required, on purpose: a verb call that
+ * narrates nothing — a background click with no caption — is meant to stay a one-liner,
+ * not force every single interaction through the same captioning `demo.step()` requires.
+ */
+export type ActorStepMeta = {
+    /**
+     * Stable id for the step this call records, the same role `DemoStep.id` plays and for the
+     * same reasons: it becomes the `stableId` on this step's `step.start`/`step.finish` events,
+     * the key a target-miss or an abort diagnostic names, and — via `clipFileName(id)` — the
+     * exact filename an author drops into `narrationDir` for a `--speech file` WAV. Absent
+     * means the runtime synthesizes one; supply your own when you need that identity to stay
+     * stable across runs — a hand-chosen id does not shift when an earlier call in the same
+     * turn is added, removed or reordered the way a synthesized one might.
+     */
+    id?: string;
+    title?: string;
+    subtitle?: string;
+    /** See `DemoStep.holdMs`. */
+    holdMs?: number;
+    /** See `DemoStep.highlight`, including the "requires a measurable target" rule. */
+    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
+ * page, and a handle of verbs that each perform a Playwright action *and* record the
+ * render-track annotation that action needs — the pairing `demo.step()` otherwise leaves an
+ * author to assemble by hand (a `target`, a declared `action`, a `run`). `admin.click(button)`
+ * does both in one call; there is no separate bookkeeping step the way there is today.
+ *
+ * `page` is the same escape hatch `DemoRunArgs.page` already is: anything the named verbs
+ * below don't model — a Playwright call with no render-track equivalent — is still reachable
+ * through it, at the same cost reaching past `demo.step()` into raw Playwright already has
+ * today: nothing about the call is recorded automatically.
+ *
+ * Every verb that takes a `Locator` records that locator's measured rect on `step.start`, the
+ * same rect `DemoStep.target` records; a verb with nothing to point at (`goto`, and `scroll`'s
+ * delta form) records none, exactly as a `DemoStep` with no `target` does.
+ *
+ * Same name, different thing from `@plaintake/schema`'s `Actor`: that one is the frozen
+ * `{ id, label }` render-plan record a *finished* run leaves behind; this one is the live,
+ * verb-bearing handle a scenario's `run()` calls while a session is still recording.
+ */
+export type Actor = {
+    /** Raw Playwright escape hatch. See this type's own doc comment. */
+    page: Page;
+    goto(url: string, meta?: ActorStepMeta): Promise<void>;
+    click(target: Locator, meta?: ActorStepMeta): Promise<void>;
+    /**
+     * Fills `target` with `text`. Masking a field's *value* once it exists is `mask`'s job,
+     * not this verb's — `type` only ever records that typing happened, never what was typed.
+     */
+    type(target: Locator, text: string, meta?: ActorStepMeta): Promise<void>;
+    /**
+     * Presses `key` while `target` holds focus — Playwright's `locator.press`, not the
+     * page-global `page.keyboard.press`. A demo step points at something; a key press with
+     * nothing to point at is exactly what `actor.page.keyboard.press(key)` remains for, at
+     * the same recorded-nothing cost as any other reach past a named verb.
+     */
+    press(target: Locator, key: string, meta?: ActorStepMeta): Promise<void>;
+    /**
+     * Scrolls the page or a specific element into view — two different Playwright calls,
+     * `locator.scrollIntoViewIfNeeded()` and `page.mouse.wheel(deltaX, deltaY)`, behind one
+     * verb, chosen by which shape `where` is. Named `where` rather than `target` because the
+     * delta form is not a target — nothing measurable sits behind a pixel offset — where every
+     * other verb's `target` names a `Locator` and nothing else. A `Locator` scrolls that element
+     * into view and records its rect exactly as `click`/`hover` do; a `{ deltaX?, deltaY? }`
+     * delta scrolls the viewport by that many pixels (either defaulting to 0) and records no
+     * target, exactly as `goto` does.
+     */
+    scroll(where: Locator | {
+        deltaX?: number;
+        deltaY?: number;
+    }, meta?: ActorStepMeta): Promise<void>;
+    hover(target: Locator, meta?: ActorStepMeta): Promise<void>;
+    /**
+     * Mirrors `locator.selectOption`'s common case: one value or several. Anything its fuller
+     * overload set covers that a plain value or value list cannot is `step`'s or `page`'s to
+     * reach instead.
+     */
+    select(target: Locator, value: string | string[], meta?: ActorStepMeta): Promise<void>;
+    /**
+     * Reuses `DemoAssertion` verbatim. The only thing this adds over `DemoContext.assert` is
+     * which actor the recorded event is attributed to.
+     */
+    assert(assertion: DemoAssertion): Promise<void>;
+    /**
+     * Escape hatch for an interaction none of the named verbs above model, bound to this actor
+     * exactly as `DemoContext.step` is bound to the default one.
+     */
+    step(step: DemoStep): Promise<void>;
+    /**
+     * Reuses `DemoMask` verbatim. Actor-scoped: applies to this actor's own `BrowserContext`
+     * only. Each actor's context is its own page, its own DOM and its own selectors, so a mask
+     * registered here has nothing to do in a context it was never registered against.
+     */
+    mask(mask: DemoMask): Promise<void>;
+    /**
+     * Another `Page` on this actor's own `BrowserContext` — the multi-tab counterpart to
+     * `demo.actor`'s multi-context one, still governed by the same one-active-page-at-a-time
+     * rule within this actor's own turn.
+     */
+    newTab(): Promise<Page>;
+    /**
+     * Hands the real browser window to a person during this actor's turn. Reuses `DemoHandoff`
+     * verbatim; the only difference from `DemoContext.handoff` is that a handoff can originate
+     * from any actor's turn, not only the default one a scenario would fall back to if none
+     * were ever named — a person can be handed the browser whoever currently holds it.
+     */
+    handoff(request: DemoHandoff): Promise<void>;
+};
 /**
  * What a scenario may do before recording starts.
  *
@@ -153,6 +424,75 @@ export interface DemoContext extends PreflightContext {
     assert(assertion: DemoAssertion): Promise<void>;
     mask(mask: DemoMask): Promise<void>;
     pause(ms: number): Promise<void>;
+    /**
+     * Returns a handle for a named actor, standing up its `BrowserContext` and `Page` the first
+     * time `id` is seen. Async, not a synchronous handle: `browser.newContext()` and
+     * `context.newPage()` are themselves async Playwright calls, and there is no way to hand
+     * back an `Actor` whose `page` is already a real, working page without awaiting them first
+     * — so authors write `const admin = await demo.actor('admin')`. See `turn` for what makes
+     * an actor's context the active one.
+     *
+     * The first `id` a scenario ever calls this with reuses the implicit default context and
+     * page every scenario already runs on, rather than opening a second one nobody asked for,
+     * so in practice that call resolves immediately — there is no new `BrowserContext` to wait
+     * on. The signature stays `Promise<Actor>` for every actor regardless, rather than
+     * 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
+     * outgoing `BrowserContext` and activating the incoming one. Async because, like `chapter`
+     * and `pause`, it is itself an event on the render timeline, not just a bookkeeping call.
+     *
+     * `opts.card`, when given, plays a full-frame transition card between the two actors'
+     * segments — the `lines` it names, an optional spoken `narration`, held for `durationMs`.
+     *
+     * Omitting `opts.card` is allowed, but still draws a card: `RenderPlanSchema.transitionCards`
+     * requires exactly one entry per hand-off with non-empty `lines`, so a card-less turn's card
+     * is synthesised at render time as `Now: <label>`, naming the incoming actor by the `label`
+     * it was given to `demo.actor()`, held for the same default duration an explicit card with no
+     * `durationMs` of its own gets. The persistent corner badge names the active actor throughout
+     * either way; `opts.card` only ever changes whether that hand-off also gets a full-frame beat
+     * of its own, and what it says.
+     */
+    turn(actor: Actor, opts?: {
+        card?: {
+            lines: string[];
+            narration?: string;
+            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.6.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",