@scenar/core 0.9.1 → 0.11.0

package/scenario/apply-title-cards.js

@@ -0,0 +1,113 @@
+/**
+ * Card synthesis: expand a scenario's steps (and narration manifest)
+ * with its configured intro/outro title cards.
+ *
+ * This is THE one place card steps are constructed. It runs exactly
+ * once per playback surface, at bundle assembly — the generated render
+ * and pack entries, the CLI's `loadBundle`, and (for direct React
+ * integrators) one documented call between `createScenario()` and the
+ * player. Authoring surfaces (`createScenario`, `loadScenarioFromProto`)
+ * carry the `titleCards` config through untouched, exactly like
+ * `soundtrack` — so expanded output never carries the config and double
+ * expansion is impossible by data flow.
+ *
+ * The positional manifests stay keyed to AUTHORED steps everywhere
+ * (`scenar narrate` and `scenar presenter` never see cards); this
+ * function pads `null` entries at the injected positions — narration
+ * and presenter in the same single pass — so the expanded manifests
+ * line up with the expanded steps. Existing manifests therefore stay
+ * valid when an author adds cards later — no regeneration required.
+ */
+import { FINAL_DWELL_MS } from "../timeline/compute-step-timeline.js";
+import { TITLE_CARD_DURATION_DEFAULT_MS, } from "./title-cards.js";
+/**
+ * A card step's `data` placeholder. Card steps are rendered by the
+ * player's built-in card component — the integrator's render callback
+ * (the only reader of `data`) is never invoked for them, so no real
+ * `T` value is ever needed. See the `ScenarioStep.card` doc contract.
+ */
+function cardStepData() {
+    return undefined;
+}
+/**
+ * Expand `steps` (and the index-parallel narration and presenter
+ * manifests, when they exist) with the configured intro/outro cards.
+ *
+ * - **Intro**: prepended at index 0 with `delayMs: 0`; the card's
+ *   visible time is encoded as the following step's transition delay
+ *   (`max(authored delayMs, card duration)`), which is exactly how
+ *   `computeStepTimeline` reads step 0's duration.
+ * - **Outro**: appended with `delayMs: FINAL_DWELL_MS`, so the last
+ *   authored step keeps precisely the closing dwell it has today (or
+ *   its narration, whichever is longer) before the card appears. The
+ *   card's own visible time is its `durationMs` — `computeStepTimeline`
+ *   reads a final card step's duration as the closing dwell. The outro
+ *   carries two housekeeping interactions at step entry (`clear_cursor`
+ *   and a viewport reset) so a scenario ending with a visible cursor or
+ *   an active zoom never leaks that state onto the card. Neither action
+ *   maps to a sound effect.
+ *
+ * Pure and non-mutating. When `titleCards` configures no card, the
+ * inputs are returned as-is (byte-identical no-op).
+ */
+export function applyTitleCards(steps, narrationManifest, titleCards, presenterManifest) {
+    const intro = titleCards?.intro;
+    const outro = titleCards?.outro;
+    if (!intro && !outro) {
+        return { steps, narrationManifest, presenterManifest };
+    }
+    const expandedSteps = [...steps];
+    let manifestEntries = narrationManifest ? [...narrationManifest.steps] : undefined;
+    let presenterEntries = presenterManifest ? [...presenterManifest.steps] : undefined;
+    if (intro && expandedSteps.length > 0) {
+        const introDurationMs = intro.durationMs ?? TITLE_CARD_DURATION_DEFAULT_MS;
+        const firstAuthored = expandedSteps[0];
+        expandedSteps[0] = {
+            ...firstAuthored,
+            delayMs: Math.max(firstAuthored.delayMs, introDurationMs),
+        };
+        expandedSteps.unshift({
+            delayMs: 0,
+            data: cardStepData(),
+            card: { kind: "intro", ...pickCardContent(intro) },
+        });
+        manifestEntries?.unshift(null);
+        presenterEntries?.unshift(null);
+    }
+    if (outro) {
+        expandedSteps.push({
+            delayMs: FINAL_DWELL_MS,
+            data: cardStepData(),
+            card: { kind: "outro", ...pickCardContent(outro) },
+            interactions: [
+                { atPercent: 0, type: "clear_cursor" },
+                { atPercent: 0, type: "viewport_transition", viewportReset: true },
+            ],
+        });
+        manifestEntries?.push(null);
+        presenterEntries?.push(null);
+    }
+    return {
+        steps: expandedSteps,
+        narrationManifest: manifestEntries ? { steps: manifestEntries } : undefined,
+        presenterManifest: presenterEntries ? { steps: presenterEntries } : undefined,
+    };
+}
+/**
+ * Copy only the known card fields, so a config object carrying strays
+ * (e.g. a loosely-typed steps.ts export) never smuggles them into the
+ * step list.
+ */
+function pickCardContent(card) {
+    const content = { title: card.title };
+    if (card.subtitle !== undefined)
+        content.subtitle = card.subtitle;
+    if (card.logoSrc !== undefined)
+        content.logoSrc = card.logoSrc;
+    if (card.ctaText !== undefined)
+        content.ctaText = card.ctaText;
+    if (card.durationMs !== undefined)
+        content.durationMs = card.durationMs;
+    return content;
+}
+//# sourceMappingURL=apply-title-cards.js.map

package/scenario/apply-title-cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-title-cards.js","sourceRoot":"","sources":["../../src/scenario/apply-title-cards.ts"],"names":[],"mappings":"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"}

package/scenario/bundle.d.ts

@@ -7,6 +7,8 @@
  * scenario into a single typed value.
  */
 import type { NarrationManifest } from "../narration/types.js";
+import type { PresenterManifest } from "../presenter/types.js";
+import type { Soundtrack } from "./soundtrack.js";
 import type { ScenarioStep } from "./types.js";
 /**
  * Everything the engine needs to play one scenario.
@@ -24,5 +26,18 @@ export interface ScenarioBundle<T> {
      * narration (timing is purely delay-based).
      */
     readonly narrationManifest?: NarrationManifest;
+    /**
+     * Audio treatment: background music with narration ducking and
+     * interaction sound effects.  When `undefined`, the scenario plays
+     * silent apart from narration.
+     */
+    readonly soundtrack?: Soundtrack;
+    /**
+     * Pre-built presenter manifest mapping step indices to avatar clip
+     * URLs and durations (generated by `scenar presenter`).  When
+     * `undefined`, the scenario plays without the presenter — zero
+     * presenter DOM, zero fetched bytes.
+     */
+    readonly presenterManifest?: PresenterManifest;
 }
 //# sourceMappingURL=bundle.d.ts.map

package/scenario/bundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/scenario/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD"}
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../../src/scenario/bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;IAC/C;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD"}

package/scenario/soundtrack.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The scenario's audio treatment beyond narration: optional background
+ * music with narration ducking, and optional interaction sound effects.
+ *
+ * Runtime mirror of the proto `SoundtrackConfig` (`ai.scenar.scenario.v1`),
+ * field for field, in camelCase — the same 1:1 relationship `StepAction`
+ * has with its proto message. Music and sound effects are independent:
+ * a scenario may use either without the other.
+ */
+export interface Soundtrack {
+    /**
+     * Background music asset reference. Like narration clip srcs, a
+     * relative path resolves against the scenario's own location; an
+     * absolute URL passes through unchanged. MP3 is the supported format.
+     * When `undefined`, the scenario has no music.
+     */
+    readonly musicSrc?: string;
+    /**
+     * Base music level while no narration is playing (0–1).
+     * Defaults to {@link MUSIC_VOLUME_DEFAULT}.
+     */
+    readonly musicVolume?: number;
+    /**
+     * Absolute music level while a narration clip plays (0–1) — the level
+     * the music ducks to, not a multiplier of {@link musicVolume}.
+     * Defaults to {@link DUCKING_VOLUME_DEFAULT}.
+     */
+    readonly duckingVolume?: number;
+    /**
+     * Enables the engine's built-in interaction sound effects (click and
+     * keystroke). Requires an explicit `true` — adding music alone never
+     * introduces sound effects.
+     */
+    readonly sfx?: boolean;
+}
+/**
+ * Default base music level. Clearly audible under silence without
+ * competing with interface sound effects.
+ */
+export declare const MUSIC_VOLUME_DEFAULT = 0.25;
+/**
+ * Default ducked music level while narration plays. Present but firmly
+ * under the voice.
+ */
+export declare const DUCKING_VOLUME_DEFAULT = 0.08;
+//# sourceMappingURL=soundtrack.d.ts.map

package/scenario/soundtrack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soundtrack.d.ts","sourceRoot":"","sources":["../../src/scenario/soundtrack.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,sBAAsB,OAAO,CAAC"}

package/scenario/soundtrack.js

@@ -0,0 +1,11 @@
+/**
+ * Default base music level. Clearly audible under silence without
+ * competing with interface sound effects.
+ */
+export const MUSIC_VOLUME_DEFAULT = 0.25;
+/**
+ * Default ducked music level while narration plays. Present but firmly
+ * under the voice.
+ */
+export const DUCKING_VOLUME_DEFAULT = 0.08;
+//# sourceMappingURL=soundtrack.js.map

package/scenario/soundtrack.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"soundtrack.js","sourceRoot":"","sources":["../../src/scenario/soundtrack.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAEzC;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,CAAC"}

package/scenario/title-cards.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Intro and outro title cards framing a scenario.
+ *
+ * Runtime mirror of the proto `TitleCardsConfig` / `TitleCard`
+ * (`ai.scenar.scenario.v1`), field for field, in camelCase — the same
+ * 1:1 relationship `Soundtrack` has with its proto message.
+ *
+ * Cards are synthesized steps: {@link applyTitleCards} injects them
+ * into the step list at bundle assembly, so chapter markers, scrubbing,
+ * video duration, and the music envelope account for them with no
+ * card-specific timing code. The player renders card steps with its
+ * built-in card component — the scenario's render function is never
+ * called for them.
+ */
+/** One card's content — deliberately small; a card, not a page builder. */
+export interface TitleCard {
+    /** Headline text. The one required field. */
+    readonly title: string;
+    /** Supporting line rendered under the title. */
+    readonly subtitle?: string;
+    /**
+     * Logo image asset reference. Like narration and music srcs, a
+     * relative path resolves against the scenario's own location; an
+     * absolute URL passes through unchanged. Raster web formats only
+     * (png, jpg/jpeg, gif, webp, avif) — the deploy contract excludes
+     * svg as active content.
+     */
+    readonly logoSrc?: string;
+    /**
+     * Call-to-action text rendered as a distinct pill. Display-only —
+     * not a link. Typically used on the outro.
+     */
+    readonly ctaText?: string;
+    /**
+     * How long the card stays on screen, in milliseconds.
+     * Defaults to {@link TITLE_CARD_DURATION_DEFAULT_MS}.
+     */
+    readonly durationMs?: number;
+}
+/**
+ * The scenario-level card configuration: an intro card, an outro card,
+ * or both. Either field may be set independently; neither set is a no-op.
+ */
+export interface TitleCards {
+    /** Opening card shown before the first authored step. */
+    readonly intro?: TitleCard;
+    /** Closing card shown after the last authored step. */
+    readonly outro?: TitleCard;
+}
+/**
+ * The card marker carried by a synthesized card step
+ * ({@link ScenarioStep.card}). `kind` records which side of the
+ * scenario the card frames so the renderer can style intro and outro
+ * distinctly if it chooses.
+ */
+export interface StepCard extends TitleCard {
+    readonly kind: "intro" | "outro";
+}
+/**
+ * Default card visible time. Long enough to read a title and subtitle,
+ * short enough to not delay the content.
+ */
+export declare const TITLE_CARD_DURATION_DEFAULT_MS = 3000;
+//# sourceMappingURL=title-cards.d.ts.map

package/scenario/title-cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"title-cards.d.ts","sourceRoot":"","sources":["../../src/scenario/title-cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,2EAA2E;AAC3E,MAAM,WAAW,SAAS;IACxB,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;CAClC;AAED;;;GAGG;AACH,eAAO,MAAM,8BAA8B,OAAQ,CAAC"}

package/scenario/title-cards.js

@@ -0,0 +1,20 @@
+/**
+ * Intro and outro title cards framing a scenario.
+ *
+ * Runtime mirror of the proto `TitleCardsConfig` / `TitleCard`
+ * (`ai.scenar.scenario.v1`), field for field, in camelCase — the same
+ * 1:1 relationship `Soundtrack` has with its proto message.
+ *
+ * Cards are synthesized steps: {@link applyTitleCards} injects them
+ * into the step list at bundle assembly, so chapter markers, scrubbing,
+ * video duration, and the music envelope account for them with no
+ * card-specific timing code. The player renders card steps with its
+ * built-in card component — the scenario's render function is never
+ * called for them.
+ */
+/**
+ * Default card visible time. Long enough to read a title and subtitle,
+ * short enough to not delay the content.
+ */
+export const TITLE_CARD_DURATION_DEFAULT_MS = 3_000;
+//# sourceMappingURL=title-cards.js.map

package/scenario/title-cards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"title-cards.js","sourceRoot":"","sources":["../../src/scenario/title-cards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAiDH;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,KAAK,CAAC"}

package/scenario/types.d.ts

@@ -5,6 +5,7 @@
  * playback engine. They are framework-agnostic — no React, no DOM.
  */
 import type { StepAction } from "./step-action.js";
+import type { StepCard } from "./title-cards.js";
 /**
  * A single step in a scenario timeline.
  *
@@ -16,8 +17,12 @@ export interface ScenarioStep<T> {
     /** Data snapshot at this point in the timeline. */
     readonly data: T;
     /**
-     * Narration script for TTS generation. Consumed by the build script
-     * to produce audio files — not rendered at runtime.
+     * Narration script for this step. Consumed by `scenar narrate` to
+     * produce audio files, and rendered at runtime as the step's caption
+     * when the player has captions enabled (a presentation preference —
+     * the `captions` player prop, the `?captions=1` embed param, or
+     * `scenar render --captions`). Steps without narration play
+     * uncaptioned.
      */
     readonly narration?: string;
     /**
@@ -29,6 +34,22 @@ export interface ScenarioStep<T> {
      * share the same atPercent, they fire in array order.
      */
     readonly interactions?: readonly StepAction[];
+    /**
+     * Marks this step for the presenter track. When true, `scenar presenter`
+     * generates an avatar clip lip-synced to this step's narration audio,
+     * and both outputs show the clip picture-in-picture while the step is
+     * active — the interactive embed and the exported video alike.
+     *
+     * Requires `narration`: the presenter clip is derived from the step's
+     * narration audio by definition, so a step without narration cannot
+     * opt in (validated at load time).
+     *
+     * Playback never calls an AI service. Like narration audio, presenter
+     * clips are generated at compile time by the CLI and consumed as fixed
+     * assets through a positional manifest; a scenario whose clips have
+     * not been generated yet simply plays without the presenter.
+     */
+    readonly presenter?: boolean;
     /**
      * Names this step as a still-capture point for `scenar shoot`.
      *
@@ -45,5 +66,18 @@ export interface ScenarioStep<T> {
      * bundle. Steps without a `shot` are simply walked through.
      */
     readonly shot?: string;
+    /**
+     * Marks this step as an engine-synthesized title card. Only
+     * `applyTitleCards` constructs card steps — authors configure cards
+     * through the scenario-level `titleCards` config, never by hand.
+     *
+     * The player renders card steps with its built-in card component and
+     * never calls the scenario's render function for them, so a card
+     * step's `data` is a placeholder that is never read. Card steps
+     * announce activation through the player's `onCardStepChange`
+     * callback instead of `onStepChange` — the engine cannot fabricate a
+     * real `T` for the latter.
+     */
+    readonly card?: StepCard;
 }
 //# sourceMappingURL=types.d.ts.map

package/scenario/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scenario/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;GAIG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,UAAU,EAAE,CAAC;IAC9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1B"}

package/src/embed/host-controller.test.ts

@@ -62,6 +62,12 @@ describe("createEmbedHostController — commands", () => {
       EMBED_ORIGIN,
     );
 
+    controller.setHostScale(0.7);
+    expect(post).toHaveBeenLastCalledWith(
+      expect.objectContaining({ type: "setHostScale", scale: 0.7 }),
+      EMBED_ORIGIN,
+    );
+
     controller.destroy();
   });
 });

package/src/embed/host-controller.ts

@@ -32,6 +32,13 @@ export interface ScenarEmbedHostController {
   seek(timeMs: number): void;
   setMuted(muted: boolean): void;
   setVolume(volume: number): void;
+  /**
+   * Report the scale factor the host is rendering the iframe at (1 = native),
+   * so the player's chrome layer can counter-scale its transport controls
+   * back to native pixel size. Sent by hosts running the iframe-as-screen
+   * mode; players without the capability ignore it.
+   */
+  setHostScale(scale: number): void;
   prefetch(): void;
   /**
    * Tell the embed to stop (best effort) and detach the host message listener.
@@ -86,6 +93,7 @@ export function createEmbedHostController(
     seek: (timeMs) => send({ type: "seek", timeMs }),
     setMuted: (muted) => send({ type: "setMuted", muted }),
     setVolume: (volume) => send({ type: "setVolume", volume }),
+    setHostScale: (scale) => send({ type: "setHostScale", scale }),
     prefetch: () => send({ type: "prefetch" }),
     destroy: () => {
       send({ type: "destroy" });

package/src/embed/protocol.test.ts

@@ -55,6 +55,21 @@ describe("parseEmbedCommand", () => {
     });
   });
 
+  it("accepts setHostScale with a positive finite scale", () => {
+    expect(parseEmbedCommand(wrap({ type: "setHostScale", scale: 0.7 }))).toEqual({
+      type: "setHostScale",
+      scale: 0.7,
+    });
+  });
+
+  it("rejects setHostScale with a missing, non-finite, or non-positive scale", () => {
+    expect(parseEmbedCommand(wrap({ type: "setHostScale" }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "setHostScale", scale: "big" }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "setHostScale", scale: Number.NaN }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "setHostScale", scale: 0 }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "setHostScale", scale: -1 }))).toBeNull();
+  });
+
   it("rejects a foreign source", () => {
     expect(parseEmbedCommand({ source: "other-widget", v: 1, type: "play" })).toBeNull();
   });
@@ -103,6 +118,44 @@ describe("parseEmbedEvent", () => {
     expect(parseEmbedEvent(wrap({ type: "ready", totalSteps: 3 }))).toBeNull();
   });
 
+  it("accepts a ready payload carrying a well-formed canonical viewport", () => {
+    expect(
+      parseEmbedEvent(
+        wrap({
+          type: "ready",
+          totalSteps: 3,
+          hasNarration: false,
+          viewport: { widthPx: 1440, heightPx: 900 },
+        }),
+      ),
+    ).toEqual({
+      type: "ready",
+      totalSteps: 3,
+      hasNarration: false,
+      viewport: { widthPx: 1440, heightPx: 900 },
+    });
+  });
+
+  it("still accepts a ready payload without a viewport (pre-viewport bundles)", () => {
+    const parsed = parseEmbedEvent(wrap({ type: "ready", totalSteps: 3, hasNarration: false }));
+    expect(parsed).toEqual({ type: "ready", totalSteps: 3, hasNarration: false });
+    // The field must be genuinely absent, not present-and-undefined — hosts
+    // branch on `event.viewport` to decide iframe-as-screen adoption.
+    expect(parsed && "viewport" in parsed).toBe(false);
+  });
+
+  it("rejects a ready payload whose viewport is malformed", () => {
+    const base = { type: "ready", totalSteps: 3, hasNarration: false };
+    expect(parseEmbedEvent(wrap({ ...base, viewport: "1440x900" }))).toBeNull();
+    expect(parseEmbedEvent(wrap({ ...base, viewport: { widthPx: 1440 } }))).toBeNull();
+    expect(
+      parseEmbedEvent(wrap({ ...base, viewport: { widthPx: 0, heightPx: 900 } })),
+    ).toBeNull();
+    expect(
+      parseEmbedEvent(wrap({ ...base, viewport: { widthPx: "1440", heightPx: 900 } })),
+    ).toBeNull();
+  });
+
   it("rejects foreign source and unknown event types", () => {
     expect(parseEmbedEvent({ source: "x", v: 1, type: "started" })).toBeNull();
     expect(parseEmbedEvent(wrap({ type: "imploded" }))).toBeNull();

package/src/embed/protocol.ts

@@ -21,11 +21,31 @@ export const SCENAR_EMBED_SOURCE = "scenar-embed";
 /** Protocol version. Bump only on a breaking change to the message shapes. */
 export const SCENAR_EMBED_PROTOCOL_VERSION = 1;
 
+/**
+ * The canonical viewport a packed scenario was authored and bundled at, in CSS
+ * pixels — the same numbers `scenar pack` bakes into the bundle and records in
+ * `scenario.json`.
+ *
+ * Carried on `ready` so a host can lay the iframe out at this exact size and
+ * scale it as one unit (the iframe-as-screen mode in `@scenar/embed`): the
+ * embedded document's media queries then resolve against the canonical width,
+ * so responsive components render the same variant they would in a real
+ * browser window of that size — instead of the narrow variant the host
+ * column's width would select.
+ */
+export interface ScenarEmbedViewport {
+  readonly widthPx: number;
+  readonly heightPx: number;
+}
+
 /**
  * Events the embedded player emits to the host (embed -> host).
  *
  * - `ready` — the player has mounted; carries scenario shape the host can use
- *   to size or label the frame.
+ *   to size or label the frame. `viewport` (when the bundle knows it) is the
+ *   canonical size the scenario was packed at — see {@link ScenarEmbedViewport}.
+ *   Optional for compatibility: bundles packed before the field existed omit
+ *   it, and hosts must treat its absence as "fit content inside the iframe".
  * - `resize` — the rendered content height changed (dynamic-height hosts).
  * - `started` / `paused` / `completed` — transport state transitions.
  * - `stepchange` — the active step changed.
@@ -35,7 +55,12 @@ export const SCENAR_EMBED_PROTOCOL_VERSION = 1;
  * - `error` — an unrecoverable runtime error, with a human-readable message.
  */
 export type ScenarEmbedEvent =
-  | { readonly type: "ready"; readonly totalSteps: number; readonly hasNarration: boolean }
+  | {
+      readonly type: "ready";
+      readonly totalSteps: number;
+      readonly hasNarration: boolean;
+      readonly viewport?: ScenarEmbedViewport;
+    }
   | { readonly type: "resize"; readonly widthPx: number; readonly heightPx: number }
   | { readonly type: "started" }
   | { readonly type: "paused" }
@@ -53,8 +78,17 @@ export type ScenarEmbedEvent =
 /**
  * Commands the host may send to the embedded player (host -> embed).
  *
- * State-setting commands (`setMuted`, `setVolume`) are idempotent by design so
- * a host never has to track the player's internal state to stay in sync.
+ * State-setting commands (`setMuted`, `setVolume`, `setHostScale`) are
+ * idempotent by design so a host never has to track the player's internal
+ * state to stay in sync.
+ *
+ * `setHostScale` accompanies the iframe-as-screen mode: when the host lays
+ * the iframe out at the canonical viewport and scales it as one unit, every
+ * pixel inside — including the player's transport controls — shrinks by that
+ * factor. The player's chrome layer counter-scales by `1 / scale` so controls
+ * keep rendering at native pixel size (the ViewportChrome contract), which
+ * only the host can enable because a cross-origin document cannot observe the
+ * transform applied to its own frame.
  */
 export type ScenarEmbedCommand =
   | { readonly type: "play" }
@@ -62,6 +96,7 @@ export type ScenarEmbedCommand =
   | { readonly type: "seek"; readonly timeMs: number }
   | { readonly type: "setMuted"; readonly muted: boolean }
   | { readonly type: "setVolume"; readonly volume: number }
+  | { readonly type: "setHostScale"; readonly scale: number }
   | { readonly type: "prefetch" }
   | { readonly type: "destroy" };
 
@@ -122,11 +157,35 @@ export function parseEmbedCommand(data: unknown): ScenarEmbedCommand | null {
       return typeof data["muted"] === "boolean" ? { type, muted: data["muted"] } : null;
     case "setVolume":
       return isFiniteNumber(data["volume"]) ? { type, volume: data["volume"] } : null;
+    case "setHostScale":
+      return isFiniteNumber(data["scale"]) && data["scale"] > 0
+        ? { type, scale: data["scale"] }
+        : null;
     default:
       return null;
   }
 }
 
+/**
+ * Parse the optional `viewport` field of a `ready` payload. Absent -> the
+ * event simply has no viewport (a pre-viewport bundle). Present but malformed
+ * -> the whole event is rejected, exactly like a mistyped required field: a
+ * half-valid message is a protocol violation, not a degraded mode.
+ */
+function parseReadyViewport(
+  value: unknown,
+): { viewport?: ScenarEmbedViewport } | null {
+  if (value === undefined) return {};
+  if (typeof value !== "object" || value === null) return null;
+  const record = value as Record<string, unknown>;
+  return isFiniteNumber(record["widthPx"]) &&
+    record["widthPx"] > 0 &&
+    isFiniteNumber(record["heightPx"]) &&
+    record["heightPx"] > 0
+    ? { viewport: { widthPx: record["widthPx"], heightPx: record["heightPx"] } }
+    : null;
+}
+
 /**
  * Parse an inbound `MessageEvent.data` into a typed event, or return `null`.
  *
@@ -142,10 +201,19 @@ export function parseEmbedEvent(data: unknown): ScenarEmbedEvent | null {
     case "completed":
     case "audioBlocked":
       return { type };
-    case "ready":
-      return isFiniteNumber(data["totalSteps"]) && typeof data["hasNarration"] === "boolean"
-        ? { type, totalSteps: data["totalSteps"], hasNarration: data["hasNarration"] }
-        : null;
+    case "ready": {
+      if (!isFiniteNumber(data["totalSteps"]) || typeof data["hasNarration"] !== "boolean") {
+        return null;
+      }
+      const parsedViewport = parseReadyViewport(data["viewport"]);
+      if (parsedViewport === null) return null;
+      return {
+        type,
+        totalSteps: data["totalSteps"],
+        hasNarration: data["hasNarration"],
+        ...parsedViewport,
+      };
+    }
     case "resize":
       return isFiniteNumber(data["widthPx"]) && isFiniteNumber(data["heightPx"])
         ? { type, widthPx: data["widthPx"], heightPx: data["heightPx"] }