@plaintake/scenario 1.24.0 → 1.30.0

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ScenarioMeta } from './schema/index.js';
+import type { ScenarioMeta, TerminalMetaInput } from './schema/index.js';
 import type { BrowserContextOptions, Locator, Page } from 'playwright-core';
 /**
  * What kind of interaction `run()` performs, declared rather than observed. Like
@@ -217,10 +217,10 @@ export type ExplainConnection = {
     to: string;
     label?: string;
 };
-/** One side of a `comparison` explain scene: what this alternative is called, and its points. */
+/** One side of a `comparison` explain scene: what this alternative is called, and two to six short items. */
 export type ExplainColumn = {
     heading: string;
-    points: string[];
+    items: string[];
 };
 /** A named group of imported svg parts a `diagram` scene's cue can target as one thing. */
 export type ExplainRegion = {
@@ -228,16 +228,16 @@ export type ExplainRegion = {
     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
+ * The five motion-graphics scenes an explain cut-away can be, mirroring the scene registry in
+ * `@plaintake/motion` prop-for-prop (`title`/`process`/`comparison`/`diagram`/`recap`). This
+ * package is types only — each scene is compiled and drawn after capture and spliced into the
+ * recording as a frozen segment — so this union is a structural mirror of those scene schemas,
+ * and the deep validation (character caps, list bounds, phrase resolution) belongs to the
+ * compile 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
+ * exactly as it is in any motion-graphics scene; an author says what exists and what the
  * narration points at, and nothing about inches.
  */
 export type ExplainScene = {
@@ -273,7 +273,7 @@ export type ExplainScene = {
     items: string[];
 };
 /**
- * What a cue does to the viewer's attention. The same vocabulary PlainMotion defines —
+ * What a cue does to the viewer's attention. The same vocabulary the explain compile 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.
  */
@@ -281,7 +281,7 @@ export type ExplainCueAction = 'reveal' | 'hide' | 'emphasize' | 'deemphasize' |
 /**
  * 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
+ * desynchronising — which is why there is no numeric `at` offset here the way the compile'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.
@@ -296,22 +296,23 @@ export type ExplainCue = {
 };
 /**
  * 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
+ * demoing". `demo.explain()` stops the screencast, splices in a rendered motion-graphics 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.
+ * Free on every tier, like every authoring verb. Always narrated — the narration is the
+ * scene's clock — so it needs the voice model installed at record time even when speech is
+ * off (`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
+     * the frozen artifacts live in (`explain/<id>/segment.mp4` and its frozen plan) and
+     * the generated scene's own id, so it must read as scene ids do: lower-case
      * alphanumeric and hyphens, starting alphanumeric. Checked at run time, with the offending
      * id named.
      */
@@ -320,7 +321,7 @@ export type DemoExplain = {
     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
+     * no separate caption field, for the same reason a motion-graphics scene 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.
@@ -387,6 +388,53 @@ export type ActorStepMeta = {
      */
     paddingPx?: number;
 };
+/**
+ * `ActorStepMeta` for a `TermHandle` verb, plus the one thing a terminal step can mean that a
+ * browser step cannot: `expectExit: true` says the terminal process exiting during this step is
+ * the point of it (a `quit`, an `exit`), not a capture failure.
+ */
+export type TermStepMeta = ActorStepMeta & {
+    expectExit?: boolean;
+};
+/** A rectangle of terminal cells: zero-based `row`/`col` of its top-left cell, size in cells. */
+export type TermCells = {
+    row: number;
+    col: number;
+    width: number;
+    height: number;
+};
+/**
+ * The live terminal a scenario declaring `terminal` drives, handed to `run()` as `term`. Each
+ * verb records `step.start`/`step.finish` through the same bracket `Actor` verbs use, so
+ * captions, narration, cursor, camera, highlight and chapters work unchanged.
+ */
+export type TermHandle = {
+    /**
+     * The terminal as an actor, to turn back to it with `demo.turn(term.actor)`. Only with
+     * `terminal.browser: true`; reading it otherwise throws (exit 2).
+     */
+    readonly actor: Actor;
+    /** Types `line`, then Enter. Records a step whose target is the prompt line. */
+    run(line: string, meta?: TermStepMeta): Promise<void>;
+    /** Types at a fixed per-character delay — part of the timeline, never wall-clock driven. */
+    type(text: string, meta?: TermStepMeta): Promise<void>;
+    /** `'Enter'`, `'Ctrl+C'`, or a space-separated sequence such as `'Ctrl+B c'`. */
+    press(keys: string, meta?: TermStepMeta): Promise<void>;
+    /** Same bounds and timeout semantics as `demo.waitFor`. */
+    waitForText(pattern: RegExp | string, opts?: {
+        timeoutMs?: number;
+        id?: string;
+        title?: string;
+    }): Promise<void>;
+    /** A locator over the first match on the visible screen. */
+    getByText(pattern: RegExp | string): Locator;
+    /** A locator over a rectangle of cells, refused when it is outside the grid. */
+    cells(r: TermCells): Locator;
+    /** The visible screen, one line per row. */
+    screenText(): Promise<string>;
+    /** Reuses `DemoAssertion` verbatim, recorded against the default actor like `demo.assert`. */
+    assert(assertion: DemoAssertion): Promise<void>;
+};
 /**
  * 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
@@ -539,20 +587,14 @@ export interface DemoContext extends PreflightContext {
      * `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.
+     * `opts.card: false` is a hard cut: no card and no gap. With no `opts.card` the scenario
+     * default applies: a cut for a `terminal.browser` scenario unless `terminal.transition` is
+     * `'card'`; otherwise the 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 default
+     * duration. The persistent corner badge names the active actor throughout either way.
      */
     turn(actor: Actor, opts?: {
-        card?: {
-            lines: string[];
-            narration?: string;
-            durationMs?: number;
-        };
+        card?: TurnCard | false;
     }): Promise<void>;
     /**
      * Cuts away from the browser recording to a full-frame motion-graphics scene — a diagram
@@ -561,10 +603,10 @@ export interface DemoContext extends PreflightContext {
      * 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
+     * The scene is not drawn live: it is compiled and rendered in process 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 a voice
+     * model, 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.
      *
@@ -574,10 +616,25 @@ export interface DemoContext extends PreflightContext {
      */
     explain(request: DemoExplain): Promise<void>;
 }
+/** An explicit transition card for `demo.turn`. */
+export type TurnCard = {
+    lines: string[];
+    narration?: string;
+    durationMs?: number;
+};
+/**
+ * `term` is present only when the scenario declares `terminal`; a scenario without one is
+ * handed no `term` key at all.
+ *
+ * `page` is the terminal page in a terminal scenario. `baseURL` is the web target (`--base-url`
+ * or the fixture) when `terminal.browser` is set; without it, in a terminal scenario, it is the
+ * terminal page's URL.
+ */
 export type DemoRunArgs = {
     page: Page;
     demo: DemoContext;
     baseURL: string;
+    term?: TermHandle;
 };
 /** Same property names as `DemoRunArgs`, so moving code between phases changes nothing else. */
 export type PreflightArgs = {
@@ -625,7 +682,8 @@ export type DemoDefinition = ScenarioMeta & {
  * field is one edit here instead of two that can drift apart.
  */
 type Defaulted = 'language' | 'allowedConsoleErrors' | 'handoff' | 'handoffTimeoutMs';
-export type DemoDefinitionInput = Omit<ScenarioMeta, Defaulted> & Partial<Pick<ScenarioMeta, Defaulted>> & {
+export type DemoDefinitionInput = Omit<ScenarioMeta, Defaulted | 'terminal'> & Partial<Pick<ScenarioMeta, Defaulted>> & {
+    terminal?: TerminalMetaInput;
     run(args: DemoRunArgs): Promise<void>;
 } & PreflightHook & WarmupHook;
 export {};

package/package.json

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