@plaintake/scenario 1.6.0 → 1.7.0

package/dist/index.js

@@ -42,7 +42,16 @@ 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"
 ]);
 var TargetSchema = z.object({
   role: z.string().optional(),
@@ -60,7 +69,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
@@ -349,6 +366,25 @@ 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 HighlightRectSchema = z5.object({
   id: z5.string().min(1),
   x: z5.number().int().min(0),
@@ -625,8 +661,54 @@ var RenderPlanSchema = z5.object({
   cursor: CursorSchema.optional(),
   camera: CameraSchema.optional(),
   highlight: HighlightSchema.optional(),
-  speech: SpeechSchema.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.
+   */
+  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()
+}).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);
+  },
+  {
+    // 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",
+    path: ["actors"]
+  }
+).refine(
+  (plan) => {
+    if (plan.actors === void 0 || plan.segments === void 0 || plan.transitionCards === void 0 || plan.badgesAssPath === 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(
+      (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",
+    path: ["segments"]
+  }
+);
 
 // ../schema/src/results.ts
 import { z as z6 } from "zod";
@@ -760,7 +842,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,
@@ -846,6 +928,35 @@ 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 rendered MP4s, from the manifest, so hashes are not recomputed. */
   outputs: z6.array(ArtifactRefSchema),
   assertions: z6.array(AssertionSchema),

package/dist/schema/event.d.ts

@@ -9,6 +9,7 @@ export declare const DemoEventTypeSchema: z.ZodEnum<{
     "assertion.fail": "assertion.fail";
     "privacy.mask": "privacy.mask";
     "human.wait": "human.wait";
+    turn: "turn";
 }>;
 export declare const TargetSchema: z.ZodObject<{
     role: z.ZodOptional<z.ZodString>;
@@ -36,6 +37,7 @@ export declare const DemoEventSchema: z.ZodObject<{
         "assertion.fail": "assertion.fail";
         "privacy.mask": "privacy.mask";
         "human.wait": "human.wait";
+        turn: "turn";
     }>;
     stableId: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
@@ -52,6 +54,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/render-plan.d.ts

@@ -190,6 +190,77 @@ 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>;
+/**
+ * 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
@@ -339,6 +410,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.
  *
@@ -543,6 +622,26 @@ 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">>;
 }, 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";
@@ -326,6 +327,11 @@ 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>>;
     outputs: z.ZodArray<z.ZodObject<{
         path: z.ZodString;
         sha256: z.ZodString;

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;
@@ -124,6 +125,124 @@ export type DemoHandoff = PreflightHandoff & {
      */
     mask?: 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;
+    };
+};
+/**
+ * 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 +272,49 @@ 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.
+     */
+    actor(id: string, opts?: {
+        label?: string;
+        contextOptions?: BrowserContextOptions;
+    }): 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>;
 }
 export type DemoRunArgs = {
     page: Page;

package/package.json

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