@scenar/core 0.1.18 → 0.1.20-rc.1

package/README.md

@@ -60,6 +60,25 @@ The engine identifies interactive elements via data attributes. These constants
 - `NarrationEntry` — `{ src, durationMs }` for one audio clip.
 - `NarrationManifest` — `{ steps: (NarrationEntry | null)[] }`.
 
+### Embed protocol (v1)
+
+The wire contract for a packed scenario delivered as a cross-origin iframe. The embedded player emits events; the host page sends commands. Every message carries a fixed source tag and version, and receivers ignore anything that does not match — the global `message` channel is shared with the host and every other widget on the page.
+
+- `SCENAR_EMBED_SOURCE` — `"scenar-embed"`, stamped on every message.
+- `SCENAR_EMBED_PROTOCOL_VERSION` — `1`. Bumped only on a breaking message-shape change.
+- `ScenarEmbedEvent` — events the player emits (`ready`, `resize`, `started`, `paused`, `stepchange`, `progress`, `completed`, `audioBlocked`, `error`).
+- `ScenarEmbedCommand` — commands the host sends (`play`, `pause`, `seek`, `setMuted`, `setVolume`, `prefetch`, `destroy`).
+- `frameEmbedEvent(event)` / `frameEmbedCommand(command)` — stamp a message with the source + version envelope, ready to post.
+- `parseEmbedEvent(data)` / `parseEmbedCommand(data)` — the schema boundary: validate an inbound `MessageEvent.data` and return the typed message, or `null`. Origin and source-window checks live in the receiver.
+- `ScenarEmbedEventMessage` / `ScenarEmbedCommandMessage` — a framed message (event/command plus the envelope) as it travels over `postMessage`.
+
+### Embed host controller
+
+- `createEmbedHostController(target, options?)` — a framework-free driver for an embedded player. It sends commands to the iframe and forwards validated events to `options.onEvent`. Both directions are pinned to `target.origin` (derive it with `new URL(embedUrl).origin`). The same controller backs both the React console preview and a vanilla `embed.js` loader, so host behavior never forks.
+- `ScenarEmbedHostController` — the returned handle: `play`, `pause`, `seek`, `setMuted`, `setVolume`, `prefetch`, `destroy`. `destroy()` tells the embed to stop and detaches the message listener; the host still owns the iframe element.
+- `ScenarEmbedHostTarget` — `{ iframe, origin }`, the embed this controller drives.
+- `ScenarEmbedHostOptions` — `{ onEvent? }`, invoked for every well-formed event from the pinned embed.
+
 ## License
 
 Apache-2.0

package/embed/host-controller.d.ts

@@ -0,0 +1,53 @@
+import { type ScenarEmbedEvent } from "./protocol.js";
+/**
+ * The embed iframe this controller drives. Commands post to its
+ * `contentWindow`, read at send time because it changes across (re)loads.
+ */
+export interface ScenarEmbedHostTarget {
+    readonly iframe: HTMLIFrameElement;
+    /**
+     * The embed's exact origin — scheme + host + port, no path
+     * (e.g. `https://d-<deployId>.scenarusercontent.net`). Both inbound events
+     * and outbound commands are pinned to it. Derive it from the embed URL with
+     * `new URL(embedUrl).origin`.
+     */
+    readonly origin: string;
+}
+export interface ScenarEmbedHostOptions {
+    /** Invoked for every well-formed event received from the pinned embed. */
+    readonly onEvent?: (event: ScenarEmbedEvent) => void;
+}
+/** Imperative handle for driving an embedded player from its host page. */
+export interface ScenarEmbedHostController {
+    play(): void;
+    pause(): void;
+    seek(timeMs: number): void;
+    setMuted(muted: boolean): void;
+    setVolume(volume: number): void;
+    prefetch(): void;
+    /**
+     * Tell the embed to stop (best effort) and detach the host message listener.
+     * The host still owns the iframe element; remove it separately for full
+     * teardown.
+     */
+    destroy(): void;
+}
+/**
+ * Drive an embedded {@link https://www.npmjs.com/package/@scenar/react | ScenarioPlayer}
+ * from its host page over the `scenar` embed postMessage protocol (v1).
+ *
+ * This is the exact inverse of `useScenarEmbedBridge` (the embed-side runtime in
+ * `@scenar/react`): it sends the commands that bridge receives and receives the
+ * events that bridge sends. It is framework-free so both the React console
+ * preview and a vanilla `embed.js` loader share one host implementation.
+ *
+ * Security: unlike the embed side — which cannot know its host's origin ahead of
+ * time and so pins on the first inbound message — the host already knows the
+ * embed's exact origin, so this controller pins from the start. An inbound
+ * message is accepted only when it both comes from this iframe's window
+ * (`event.source === iframe.contentWindow`) and carries the pinned `origin`.
+ * The global `message` channel is shared with the host page and every other
+ * widget, so both checks are required.
+ */
+export declare function createEmbedHostController(target: ScenarEmbedHostTarget, options?: ScenarEmbedHostOptions): ScenarEmbedHostController;
+//# sourceMappingURL=host-controller.d.ts.map

package/embed/host-controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-controller.d.ts","sourceRoot":"","sources":["../../src/embed/host-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,gBAAgB,EAGtB,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CACtD;AAED,2EAA2E;AAC3E,MAAM,WAAW,yBAAyB;IACxC,IAAI,IAAI,IAAI,CAAC;IACb,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;IAC/B,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,IAAI,IAAI,CAAC;IACjB;;;;OAIG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,qBAAqB,EAC7B,OAAO,GAAE,sBAA2B,GACnC,yBAAyB,CA+B3B"}

package/embed/host-controller.js

@@ -0,0 +1,52 @@
+import { frameEmbedCommand, parseEmbedEvent, } from "./protocol.js";
+/**
+ * Drive an embedded {@link https://www.npmjs.com/package/@scenar/react | ScenarioPlayer}
+ * from its host page over the `scenar` embed postMessage protocol (v1).
+ *
+ * This is the exact inverse of `useScenarEmbedBridge` (the embed-side runtime in
+ * `@scenar/react`): it sends the commands that bridge receives and receives the
+ * events that bridge sends. It is framework-free so both the React console
+ * preview and a vanilla `embed.js` loader share one host implementation.
+ *
+ * Security: unlike the embed side — which cannot know its host's origin ahead of
+ * time and so pins on the first inbound message — the host already knows the
+ * embed's exact origin, so this controller pins from the start. An inbound
+ * message is accepted only when it both comes from this iframe's window
+ * (`event.source === iframe.contentWindow`) and carries the pinned `origin`.
+ * The global `message` channel is shared with the host page and every other
+ * widget, so both checks are required.
+ */
+export function createEmbedHostController(target, options = {}) {
+    const { iframe, origin } = target;
+    const { onEvent } = options;
+    const canListen = typeof window !== "undefined";
+    const send = (command) => {
+        iframe.contentWindow?.postMessage(frameEmbedCommand(command), origin);
+    };
+    const onMessage = (event) => {
+        if (event.source !== iframe.contentWindow)
+            return;
+        if (event.origin !== origin)
+            return;
+        const parsed = parseEmbedEvent(event.data);
+        if (!parsed)
+            return;
+        onEvent?.(parsed);
+    };
+    if (canListen)
+        window.addEventListener("message", onMessage);
+    return {
+        play: () => send({ type: "play" }),
+        pause: () => send({ type: "pause" }),
+        seek: (timeMs) => send({ type: "seek", timeMs }),
+        setMuted: (muted) => send({ type: "setMuted", muted }),
+        setVolume: (volume) => send({ type: "setVolume", volume }),
+        prefetch: () => send({ type: "prefetch" }),
+        destroy: () => {
+            send({ type: "destroy" });
+            if (canListen)
+                window.removeEventListener("message", onMessage);
+        },
+    };
+}
+//# sourceMappingURL=host-controller.js.map

package/embed/host-controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-controller.js","sourceRoot":"","sources":["../../src/embed/host-controller.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,iBAAiB,EACjB,eAAe,GAChB,MAAM,eAAe,CAAC;AAsCvB;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAA6B,EAC7B,UAAkC,EAAE;IAEpC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IAClC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;IAC5B,MAAM,SAAS,GAAG,OAAO,MAAM,KAAK,WAAW,CAAC;IAEhD,MAAM,IAAI,GAAG,CAAC,OAA2B,EAAQ,EAAE;QACjD,MAAM,CAAC,aAAa,EAAE,WAAW,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC;IACxE,CAAC,CAAC;IAEF,MAAM,SAAS,GAAG,CAAC,KAAmB,EAAQ,EAAE;QAC9C,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,aAAa;YAAE,OAAO;QAClD,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,OAAO;QACpC,MAAM,MAAM,GAAG,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3C,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC;IACpB,CAAC,CAAC;IAEF,IAAI,SAAS;QAAE,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAE7D,OAAO;QACL,IAAI,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAClC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACpC,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;QAChD,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;QACtD,SAAS,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;QAC1D,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC1C,OAAO,EAAE,GAAG,EAAE;YACZ,IAAI,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;YAC1B,IAAI,SAAS;gBAAE,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;QAClE,CAAC;KACF,CAAC;AACJ,CAAC"}

package/embed/protocol.d.ts

@@ -0,0 +1,117 @@
+/**
+ * The `scenar` embed postMessage protocol (v1).
+ *
+ * A packed scenario is delivered as a cross-origin iframe. This module is the
+ * wire contract between the embedded player and its host page: the events the
+ * player emits and the commands the host may send. It is pure (no React, no
+ * DOM) and lives in `@scenar/core` so every surface shares one definition — the
+ * React embed-side runtime (`useScenarEmbedBridge` in `@scenar/react`), the
+ * framework-free host driver ({@link createEmbedHostController}), and any future
+ * host loader (`embed.js` / oEmbed).
+ *
+ * Every message is stamped with a fixed {@link SCENAR_EMBED_SOURCE} and the
+ * protocol {@link SCENAR_EMBED_PROTOCOL_VERSION}. Receivers MUST ignore any
+ * message whose `source`/`v` do not match — the global `message` channel is
+ * shared with the host and every other framed widget on the page.
+ */
+/** Discriminator stamped on every scenar embed message. */
+export declare const SCENAR_EMBED_SOURCE = "scenar-embed";
+/** Protocol version. Bump only on a breaking change to the message shapes. */
+export declare const SCENAR_EMBED_PROTOCOL_VERSION = 1;
+/**
+ * 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.
+ * - `resize` — the rendered content height changed (dynamic-height hosts).
+ * - `started` / `paused` / `completed` — transport state transitions.
+ * - `stepchange` — the active step changed.
+ * - `progress` — fine-grained playback position (throttled by the emitter).
+ * - `audioBlocked` — the browser blocked narration audio; the host may surface
+ *   its own affordance or call `setMuted`.
+ * - `error` — an unrecoverable runtime error, with a human-readable message.
+ */
+export type ScenarEmbedEvent = {
+    readonly type: "ready";
+    readonly totalSteps: number;
+    readonly hasNarration: boolean;
+} | {
+    readonly type: "resize";
+    readonly widthPx: number;
+    readonly heightPx: number;
+} | {
+    readonly type: "started";
+} | {
+    readonly type: "paused";
+} | {
+    readonly type: "stepchange";
+    readonly stepIndex: number;
+    readonly totalSteps: number;
+} | {
+    readonly type: "progress";
+    readonly stepIndex: number;
+    readonly totalSteps: number;
+    readonly fraction: number;
+} | {
+    readonly type: "completed";
+} | {
+    readonly type: "audioBlocked";
+} | {
+    readonly type: "error";
+    readonly message: string;
+};
+/**
+ * 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.
+ */
+export type ScenarEmbedCommand = {
+    readonly type: "play";
+} | {
+    readonly type: "pause";
+} | {
+    readonly type: "seek";
+    readonly timeMs: number;
+} | {
+    readonly type: "setMuted";
+    readonly muted: boolean;
+} | {
+    readonly type: "setVolume";
+    readonly volume: number;
+} | {
+    readonly type: "prefetch";
+} | {
+    readonly type: "destroy";
+};
+/** Envelope fields stamped on every message of either direction. */
+interface ScenarEmbedEnvelope {
+    readonly source: typeof SCENAR_EMBED_SOURCE;
+    readonly v: typeof SCENAR_EMBED_PROTOCOL_VERSION;
+}
+/** A fully-framed event message as it travels over `postMessage`. */
+export type ScenarEmbedEventMessage = ScenarEmbedEvent & ScenarEmbedEnvelope;
+/** A fully-framed command message as it travels over `postMessage`. */
+export type ScenarEmbedCommandMessage = ScenarEmbedCommand & ScenarEmbedEnvelope;
+/** Stamp an event with the source + version envelope, ready to post. */
+export declare function frameEmbedEvent(event: ScenarEmbedEvent): ScenarEmbedEventMessage;
+/** Stamp a command with the source + version envelope, ready to post. */
+export declare function frameEmbedCommand(command: ScenarEmbedCommand): ScenarEmbedCommandMessage;
+/**
+ * Parse an inbound `MessageEvent.data` into a typed command, or return `null`.
+ *
+ * This is the schema boundary: it rejects anything that is not a well-formed
+ * scenar command of the matching version, including unknown command types and
+ * commands missing or mistyping their required fields. Origin/source-window
+ * checks live in the receiver; this function validates the payload shape only.
+ */
+export declare function parseEmbedCommand(data: unknown): ScenarEmbedCommand | null;
+/**
+ * Parse an inbound `MessageEvent.data` into a typed event, or return `null`.
+ *
+ * The symmetric counterpart to {@link parseEmbedCommand} for host-side code
+ * consuming the player's events.
+ */
+export declare function parseEmbedEvent(data: unknown): ScenarEmbedEvent | null;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/embed/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/embed/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,iBAAiB,CAAC;AAElD,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAAE,GACvF;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChF;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACxF;IACE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAAC;AAEjC,oEAAoE;AACpE,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,MAAM,EAAE,OAAO,mBAAmB,CAAC;IAC5C,QAAQ,CAAC,CAAC,EAAE,OAAO,6BAA6B,CAAC;CAClD;AAED,qEAAqE;AACrE,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;AAE7E,uEAAuE;AACvE,MAAM,MAAM,yBAAyB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAEjF,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,uBAAuB,CAEhF;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,yBAAyB,CAExF;AAcD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,IAAI,CAkB1E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,gBAAgB,GAAG,IAAI,CAqCtE"}

package/embed/protocol.js

@@ -0,0 +1,111 @@
+/**
+ * The `scenar` embed postMessage protocol (v1).
+ *
+ * A packed scenario is delivered as a cross-origin iframe. This module is the
+ * wire contract between the embedded player and its host page: the events the
+ * player emits and the commands the host may send. It is pure (no React, no
+ * DOM) and lives in `@scenar/core` so every surface shares one definition — the
+ * React embed-side runtime (`useScenarEmbedBridge` in `@scenar/react`), the
+ * framework-free host driver ({@link createEmbedHostController}), and any future
+ * host loader (`embed.js` / oEmbed).
+ *
+ * Every message is stamped with a fixed {@link SCENAR_EMBED_SOURCE} and the
+ * protocol {@link SCENAR_EMBED_PROTOCOL_VERSION}. Receivers MUST ignore any
+ * message whose `source`/`v` do not match — the global `message` channel is
+ * shared with the host and every other framed widget on the page.
+ */
+/** Discriminator stamped on every scenar embed message. */
+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;
+/** Stamp an event with the source + version envelope, ready to post. */
+export function frameEmbedEvent(event) {
+    return { source: SCENAR_EMBED_SOURCE, v: SCENAR_EMBED_PROTOCOL_VERSION, ...event };
+}
+/** Stamp a command with the source + version envelope, ready to post. */
+export function frameEmbedCommand(command) {
+    return { source: SCENAR_EMBED_SOURCE, v: SCENAR_EMBED_PROTOCOL_VERSION, ...command };
+}
+function isScenarEnvelope(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const record = data;
+    return (record["source"] === SCENAR_EMBED_SOURCE && record["v"] === SCENAR_EMBED_PROTOCOL_VERSION);
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/**
+ * Parse an inbound `MessageEvent.data` into a typed command, or return `null`.
+ *
+ * This is the schema boundary: it rejects anything that is not a well-formed
+ * scenar command of the matching version, including unknown command types and
+ * commands missing or mistyping their required fields. Origin/source-window
+ * checks live in the receiver; this function validates the payload shape only.
+ */
+export function parseEmbedCommand(data) {
+    if (!isScenarEnvelope(data))
+        return null;
+    const type = data["type"];
+    switch (type) {
+        case "play":
+        case "pause":
+        case "prefetch":
+        case "destroy":
+            return { type };
+        case "seek":
+            return isFiniteNumber(data["timeMs"]) ? { type, timeMs: data["timeMs"] } : null;
+        case "setMuted":
+            return typeof data["muted"] === "boolean" ? { type, muted: data["muted"] } : null;
+        case "setVolume":
+            return isFiniteNumber(data["volume"]) ? { type, volume: data["volume"] } : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Parse an inbound `MessageEvent.data` into a typed event, or return `null`.
+ *
+ * The symmetric counterpart to {@link parseEmbedCommand} for host-side code
+ * consuming the player's events.
+ */
+export function parseEmbedEvent(data) {
+    if (!isScenarEnvelope(data))
+        return null;
+    const type = data["type"];
+    switch (type) {
+        case "started":
+        case "paused":
+        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 "resize":
+            return isFiniteNumber(data["widthPx"]) && isFiniteNumber(data["heightPx"])
+                ? { type, widthPx: data["widthPx"], heightPx: data["heightPx"] }
+                : null;
+        case "stepchange":
+            return isFiniteNumber(data["stepIndex"]) && isFiniteNumber(data["totalSteps"])
+                ? { type, stepIndex: data["stepIndex"], totalSteps: data["totalSteps"] }
+                : null;
+        case "progress":
+            return isFiniteNumber(data["stepIndex"]) &&
+                isFiniteNumber(data["totalSteps"]) &&
+                isFiniteNumber(data["fraction"])
+                ? {
+                    type,
+                    stepIndex: data["stepIndex"],
+                    totalSteps: data["totalSteps"],
+                    fraction: data["fraction"],
+                }
+                : null;
+        case "error":
+            return typeof data["message"] === "string" ? { type, message: data["message"] } : null;
+        default:
+            return null;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/embed/protocol.js.map

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

package/index.d.ts

@@ -13,4 +13,8 @@ export { getStepDurationMs } from "./timeline/step-duration.js";
 export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, VIEWPORT_SETTLE_MS, } from "./timing/constants.js";
 export { findScrollParent, scrollTargetIntoView, scrollTargetIntoViewInstant, } from "./dom/scroll.js";
 export { CURSOR_TARGET_ATTRIBUTE, SCROLL_TARGET_ATTRIBUTE, HOVER_STATE_ATTRIBUTE, DRAG_STATE_ATTRIBUTE, cursorTargetSelector, scrollTargetSelector, } from "./targeting/data-attributes.js";
+export { SCENAR_EMBED_SOURCE, SCENAR_EMBED_PROTOCOL_VERSION, frameEmbedEvent, frameEmbedCommand, parseEmbedCommand, parseEmbedEvent, } from "./embed/protocol.js";
+export type { ScenarEmbedEvent, ScenarEmbedCommand, ScenarEmbedEventMessage, ScenarEmbedCommandMessage, } from "./embed/protocol.js";
+export { createEmbedHostController } from "./embed/host-controller.js";
+export type { ScenarEmbedHostController, ScenarEmbedHostTarget, ScenarEmbedHostOptions, } from "./embed/host-controller.js";
 //# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,UAAU,EACV,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAGtE,YAAY,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EACV,UAAU,EACV,UAAU,EACV,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAGnC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAG9E,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAGtE,YAAY,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAGrE,YAAY,EAAE,YAAY,EAAE,MAAM,qCAAqC,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,gBAAgB,EAChB,kBAAkB,EAClB,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC;AACvE,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC"}

package/index.js

@@ -11,4 +11,8 @@ export { CLICK_DELAY_MS, TYPE_CHAR_DELAY_MS, HOVER_HOLD_MS, DRAG_SETTLE_MS, VIEW
 export { findScrollParent, scrollTargetIntoView, scrollTargetIntoViewInstant, } from "./dom/scroll.js";
 // Data-attribute targeting contract
 export { CURSOR_TARGET_ATTRIBUTE, SCROLL_TARGET_ATTRIBUTE, HOVER_STATE_ATTRIBUTE, DRAG_STATE_ATTRIBUTE, cursorTargetSelector, scrollTargetSelector, } from "./targeting/data-attributes.js";
+// Embed postMessage protocol (v1) — the cross-origin iframe wire contract
+export { SCENAR_EMBED_SOURCE, SCENAR_EMBED_PROTOCOL_VERSION, frameEmbedEvent, frameEmbedCommand, parseEmbedCommand, parseEmbedEvent, } from "./embed/protocol.js";
+// Embed host controller — framework-free driver for an embedded player
+export { createEmbedHostController } from "./embed/host-controller.js";
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,sEAAsE;AAgBtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAItE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,uBAAuB;AACvB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4BAA4B;AAC5B,sEAAsE;AAgBtE,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAItE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAIrE,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAEhE,mBAAmB;AACnB,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAE/B,uBAAuB;AACvB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAEzB,oCAAoC;AACpC,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,GACrB,MAAM,gCAAgC,CAAC;AAExC,0EAA0E;AAC1E,OAAO,EACL,mBAAmB,EACnB,6BAA6B,EAC7B,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAQ7B,uEAAuE;AACvE,OAAO,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scenar/core",
-  "version": "0.1.18",
+  "version": "0.1.20-rc.1",
   "description": "Pure TypeScript types, timing, and utilities for the Scenar scenario engine.",
   "license": "Apache-2.0",
   "type": "module",

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

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createEmbedHostController } from "./host-controller.js";
+import {
+  SCENAR_EMBED_PROTOCOL_VERSION,
+  SCENAR_EMBED_SOURCE,
+  type ScenarEmbedEvent,
+  frameEmbedEvent,
+} from "./protocol.js";
+
+const EMBED_ORIGIN = "https://d-abc123.scenarusercontent.net";
+
+let iframe: HTMLIFrameElement;
+let post: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  iframe = document.createElement("iframe");
+  document.body.appendChild(iframe);
+  // An attached jsdom iframe has a real contentWindow; spy on its postMessage
+  // so command framing/target-origin are observable without a live navigation.
+  post = vi.spyOn(iframe.contentWindow as Window & typeof globalThis, "postMessage");
+  post.mockImplementation(() => {});
+});
+
+afterEach(() => {
+  iframe.remove();
+  vi.restoreAllMocks();
+});
+
+function dispatchFromEmbed(
+  data: unknown,
+  origin: string = EMBED_ORIGIN,
+  source: Window | null = iframe.contentWindow,
+): void {
+  window.dispatchEvent(new MessageEvent("message", { data, origin, source }));
+}
+
+describe("createEmbedHostController — commands", () => {
+  it("frames each command and posts it to the pinned embed origin", () => {
+    const controller = createEmbedHostController({ iframe, origin: EMBED_ORIGIN });
+
+    controller.play();
+    expect(post).toHaveBeenLastCalledWith(
+      { source: SCENAR_EMBED_SOURCE, v: SCENAR_EMBED_PROTOCOL_VERSION, type: "play" },
+      EMBED_ORIGIN,
+    );
+
+    controller.seek(1500);
+    expect(post).toHaveBeenLastCalledWith(
+      expect.objectContaining({ type: "seek", timeMs: 1500 }),
+      EMBED_ORIGIN,
+    );
+
+    controller.setMuted(true);
+    expect(post).toHaveBeenLastCalledWith(
+      expect.objectContaining({ type: "setMuted", muted: true }),
+      EMBED_ORIGIN,
+    );
+
+    controller.setVolume(0.25);
+    expect(post).toHaveBeenLastCalledWith(
+      expect.objectContaining({ type: "setVolume", volume: 0.25 }),
+      EMBED_ORIGIN,
+    );
+
+    controller.destroy();
+  });
+});
+
+describe("createEmbedHostController — inbound events", () => {
+  it("relays well-formed events from the pinned embed", () => {
+    const onEvent = vi.fn<(event: ScenarEmbedEvent) => void>();
+    createEmbedHostController({ iframe, origin: EMBED_ORIGIN }, { onEvent });
+
+    dispatchFromEmbed(frameEmbedEvent({ type: "ready", totalSteps: 3, hasNarration: true }));
+    expect(onEvent).toHaveBeenCalledWith({ type: "ready", totalSteps: 3, hasNarration: true });
+
+    dispatchFromEmbed(frameEmbedEvent({ type: "progress", stepIndex: 1, totalSteps: 3, fraction: 0.5 }));
+    expect(onEvent).toHaveBeenLastCalledWith({
+      type: "progress",
+      stepIndex: 1,
+      totalSteps: 3,
+      fraction: 0.5,
+    });
+  });
+
+  it("ignores events from a foreign origin", () => {
+    const onEvent = vi.fn<(event: ScenarEmbedEvent) => void>();
+    createEmbedHostController({ iframe, origin: EMBED_ORIGIN }, { onEvent });
+
+    dispatchFromEmbed(frameEmbedEvent({ type: "started" }), "https://evil.example");
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+
+  it("ignores events from a different source window", () => {
+    const onEvent = vi.fn<(event: ScenarEmbedEvent) => void>();
+    createEmbedHostController({ iframe, origin: EMBED_ORIGIN }, { onEvent });
+
+    // Correct origin but the message comes from the host window, not the iframe.
+    dispatchFromEmbed(frameEmbedEvent({ type: "started" }), EMBED_ORIGIN, window);
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+
+  it("ignores malformed or foreign-protocol payloads", () => {
+    const onEvent = vi.fn<(event: ScenarEmbedEvent) => void>();
+    createEmbedHostController({ iframe, origin: EMBED_ORIGIN }, { onEvent });
+
+    dispatchFromEmbed({ source: "other-widget", v: 1, type: "ready", totalSteps: 1, hasNarration: false });
+    dispatchFromEmbed({ source: SCENAR_EMBED_SOURCE, v: 999, type: "started" });
+    dispatchFromEmbed({ hello: "world" });
+    dispatchFromEmbed("started");
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+});
+
+describe("createEmbedHostController — teardown", () => {
+  it("destroy() tells the embed to stop and detaches the listener", () => {
+    const onEvent = vi.fn<(event: ScenarEmbedEvent) => void>();
+    const controller = createEmbedHostController({ iframe, origin: EMBED_ORIGIN }, { onEvent });
+
+    controller.destroy();
+    expect(post).toHaveBeenLastCalledWith(
+      expect.objectContaining({ type: "destroy" }),
+      EMBED_ORIGIN,
+    );
+
+    dispatchFromEmbed(frameEmbedEvent({ type: "started" }));
+    expect(onEvent).not.toHaveBeenCalled();
+  });
+});

package/src/embed/host-controller.ts

@@ -0,0 +1,95 @@
+import {
+  type ScenarEmbedCommand,
+  type ScenarEmbedEvent,
+  frameEmbedCommand,
+  parseEmbedEvent,
+} from "./protocol.js";
+
+/**
+ * The embed iframe this controller drives. Commands post to its
+ * `contentWindow`, read at send time because it changes across (re)loads.
+ */
+export interface ScenarEmbedHostTarget {
+  readonly iframe: HTMLIFrameElement;
+  /**
+   * The embed's exact origin — scheme + host + port, no path
+   * (e.g. `https://d-<deployId>.scenarusercontent.net`). Both inbound events
+   * and outbound commands are pinned to it. Derive it from the embed URL with
+   * `new URL(embedUrl).origin`.
+   */
+  readonly origin: string;
+}
+
+export interface ScenarEmbedHostOptions {
+  /** Invoked for every well-formed event received from the pinned embed. */
+  readonly onEvent?: (event: ScenarEmbedEvent) => void;
+}
+
+/** Imperative handle for driving an embedded player from its host page. */
+export interface ScenarEmbedHostController {
+  play(): void;
+  pause(): void;
+  seek(timeMs: number): void;
+  setMuted(muted: boolean): void;
+  setVolume(volume: number): void;
+  prefetch(): void;
+  /**
+   * Tell the embed to stop (best effort) and detach the host message listener.
+   * The host still owns the iframe element; remove it separately for full
+   * teardown.
+   */
+  destroy(): void;
+}
+
+/**
+ * Drive an embedded {@link https://www.npmjs.com/package/@scenar/react | ScenarioPlayer}
+ * from its host page over the `scenar` embed postMessage protocol (v1).
+ *
+ * This is the exact inverse of `useScenarEmbedBridge` (the embed-side runtime in
+ * `@scenar/react`): it sends the commands that bridge receives and receives the
+ * events that bridge sends. It is framework-free so both the React console
+ * preview and a vanilla `embed.js` loader share one host implementation.
+ *
+ * Security: unlike the embed side — which cannot know its host's origin ahead of
+ * time and so pins on the first inbound message — the host already knows the
+ * embed's exact origin, so this controller pins from the start. An inbound
+ * message is accepted only when it both comes from this iframe's window
+ * (`event.source === iframe.contentWindow`) and carries the pinned `origin`.
+ * The global `message` channel is shared with the host page and every other
+ * widget, so both checks are required.
+ */
+export function createEmbedHostController(
+  target: ScenarEmbedHostTarget,
+  options: ScenarEmbedHostOptions = {},
+): ScenarEmbedHostController {
+  const { iframe, origin } = target;
+  const { onEvent } = options;
+  const canListen = typeof window !== "undefined";
+
+  const send = (command: ScenarEmbedCommand): void => {
+    iframe.contentWindow?.postMessage(frameEmbedCommand(command), origin);
+  };
+
+  const onMessage = (event: MessageEvent): void => {
+    if (event.source !== iframe.contentWindow) return;
+    if (event.origin !== origin) return;
+    const parsed = parseEmbedEvent(event.data);
+    if (!parsed) return;
+    onEvent?.(parsed);
+  };
+
+  if (canListen) window.addEventListener("message", onMessage);
+
+  return {
+    play: () => send({ type: "play" }),
+    pause: () => send({ type: "pause" }),
+    seek: (timeMs) => send({ type: "seek", timeMs }),
+    setMuted: (muted) => send({ type: "setMuted", muted }),
+    setVolume: (volume) => send({ type: "setVolume", volume }),
+    prefetch: () => send({ type: "prefetch" }),
+    destroy: () => {
+      send({ type: "destroy" });
+      if (canListen) window.removeEventListener("message", onMessage);
+    },
+  };
+}

package/src/embed/protocol.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from "vitest";
+import {
+  SCENAR_EMBED_PROTOCOL_VERSION,
+  SCENAR_EMBED_SOURCE,
+  frameEmbedCommand,
+  frameEmbedEvent,
+  parseEmbedCommand,
+  parseEmbedEvent,
+} from "./protocol.js";
+
+describe("frameEmbedEvent / frameEmbedCommand", () => {
+  it("stamps the source and version envelope", () => {
+    const msg = frameEmbedEvent({ type: "started" });
+    expect(msg).toEqual({
+      source: SCENAR_EMBED_SOURCE,
+      v: SCENAR_EMBED_PROTOCOL_VERSION,
+      type: "started",
+    });
+  });
+
+  it("preserves the command payload fields", () => {
+    const msg = frameEmbedCommand({ type: "seek", timeMs: 1500 });
+    expect(msg).toMatchObject({ source: SCENAR_EMBED_SOURCE, type: "seek", timeMs: 1500 });
+  });
+});
+
+describe("parseEmbedCommand", () => {
+  const wrap = (payload: Record<string, unknown>) => ({
+    source: SCENAR_EMBED_SOURCE,
+    v: SCENAR_EMBED_PROTOCOL_VERSION,
+    ...payload,
+  });
+
+  it("accepts well-formed parameterless commands", () => {
+    for (const type of ["play", "pause", "prefetch", "destroy"] as const) {
+      expect(parseEmbedCommand(wrap({ type }))).toEqual({ type });
+    }
+  });
+
+  it("accepts seek with a finite timeMs", () => {
+    expect(parseEmbedCommand(wrap({ type: "seek", timeMs: 250 }))).toEqual({
+      type: "seek",
+      timeMs: 250,
+    });
+  });
+
+  it("accepts setMuted with a boolean and setVolume with a number", () => {
+    expect(parseEmbedCommand(wrap({ type: "setMuted", muted: true }))).toEqual({
+      type: "setMuted",
+      muted: true,
+    });
+    expect(parseEmbedCommand(wrap({ type: "setVolume", volume: 0.4 }))).toEqual({
+      type: "setVolume",
+      volume: 0.4,
+    });
+  });
+
+  it("rejects a foreign source", () => {
+    expect(parseEmbedCommand({ source: "other-widget", v: 1, type: "play" })).toBeNull();
+  });
+
+  it("rejects a mismatched protocol version", () => {
+    expect(parseEmbedCommand({ source: SCENAR_EMBED_SOURCE, v: 999, type: "play" })).toBeNull();
+  });
+
+  it("rejects an unknown command type", () => {
+    expect(parseEmbedCommand(wrap({ type: "explode" }))).toBeNull();
+  });
+
+  it("rejects commands missing or mistyping required fields", () => {
+    expect(parseEmbedCommand(wrap({ type: "seek" }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "seek", timeMs: "soon" }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "seek", timeMs: Number.NaN }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "setMuted", muted: "yes" }))).toBeNull();
+    expect(parseEmbedCommand(wrap({ type: "setVolume" }))).toBeNull();
+  });
+
+  it("rejects non-object inputs", () => {
+    expect(parseEmbedCommand(null)).toBeNull();
+    expect(parseEmbedCommand("play")).toBeNull();
+    expect(parseEmbedCommand(42)).toBeNull();
+  });
+});
+
+describe("parseEmbedEvent", () => {
+  const wrap = (payload: Record<string, unknown>) => ({
+    source: SCENAR_EMBED_SOURCE,
+    v: SCENAR_EMBED_PROTOCOL_VERSION,
+    ...payload,
+  });
+
+  it("round-trips an event through frame + parse", () => {
+    const framed = frameEmbedEvent({ type: "stepchange", stepIndex: 2, totalSteps: 5 });
+    expect(parseEmbedEvent(framed)).toEqual({ type: "stepchange", stepIndex: 2, totalSteps: 5 });
+  });
+
+  it("validates the ready payload", () => {
+    expect(parseEmbedEvent(wrap({ type: "ready", totalSteps: 3, hasNarration: true }))).toEqual({
+      type: "ready",
+      totalSteps: 3,
+      hasNarration: true,
+    });
+    expect(parseEmbedEvent(wrap({ type: "ready", totalSteps: 3 }))).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

@@ -0,0 +1,173 @@
+/**
+ * The `scenar` embed postMessage protocol (v1).
+ *
+ * A packed scenario is delivered as a cross-origin iframe. This module is the
+ * wire contract between the embedded player and its host page: the events the
+ * player emits and the commands the host may send. It is pure (no React, no
+ * DOM) and lives in `@scenar/core` so every surface shares one definition — the
+ * React embed-side runtime (`useScenarEmbedBridge` in `@scenar/react`), the
+ * framework-free host driver ({@link createEmbedHostController}), and any future
+ * host loader (`embed.js` / oEmbed).
+ *
+ * Every message is stamped with a fixed {@link SCENAR_EMBED_SOURCE} and the
+ * protocol {@link SCENAR_EMBED_PROTOCOL_VERSION}. Receivers MUST ignore any
+ * message whose `source`/`v` do not match — the global `message` channel is
+ * shared with the host and every other framed widget on the page.
+ */
+
+/** Discriminator stamped on every scenar embed message. */
+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;
+
+/**
+ * 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.
+ * - `resize` — the rendered content height changed (dynamic-height hosts).
+ * - `started` / `paused` / `completed` — transport state transitions.
+ * - `stepchange` — the active step changed.
+ * - `progress` — fine-grained playback position (throttled by the emitter).
+ * - `audioBlocked` — the browser blocked narration audio; the host may surface
+ *   its own affordance or call `setMuted`.
+ * - `error` — an unrecoverable runtime error, with a human-readable message.
+ */
+export type ScenarEmbedEvent =
+  | { readonly type: "ready"; readonly totalSteps: number; readonly hasNarration: boolean }
+  | { readonly type: "resize"; readonly widthPx: number; readonly heightPx: number }
+  | { readonly type: "started" }
+  | { readonly type: "paused" }
+  | { readonly type: "stepchange"; readonly stepIndex: number; readonly totalSteps: number }
+  | {
+      readonly type: "progress";
+      readonly stepIndex: number;
+      readonly totalSteps: number;
+      readonly fraction: number;
+    }
+  | { readonly type: "completed" }
+  | { readonly type: "audioBlocked" }
+  | { readonly type: "error"; readonly message: string };
+
+/**
+ * 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.
+ */
+export type ScenarEmbedCommand =
+  | { readonly type: "play" }
+  | { readonly type: "pause" }
+  | { readonly type: "seek"; readonly timeMs: number }
+  | { readonly type: "setMuted"; readonly muted: boolean }
+  | { readonly type: "setVolume"; readonly volume: number }
+  | { readonly type: "prefetch" }
+  | { readonly type: "destroy" };
+
+/** Envelope fields stamped on every message of either direction. */
+interface ScenarEmbedEnvelope {
+  readonly source: typeof SCENAR_EMBED_SOURCE;
+  readonly v: typeof SCENAR_EMBED_PROTOCOL_VERSION;
+}
+
+/** A fully-framed event message as it travels over `postMessage`. */
+export type ScenarEmbedEventMessage = ScenarEmbedEvent & ScenarEmbedEnvelope;
+
+/** A fully-framed command message as it travels over `postMessage`. */
+export type ScenarEmbedCommandMessage = ScenarEmbedCommand & ScenarEmbedEnvelope;
+
+/** Stamp an event with the source + version envelope, ready to post. */
+export function frameEmbedEvent(event: ScenarEmbedEvent): ScenarEmbedEventMessage {
+  return { source: SCENAR_EMBED_SOURCE, v: SCENAR_EMBED_PROTOCOL_VERSION, ...event };
+}
+
+/** Stamp a command with the source + version envelope, ready to post. */
+export function frameEmbedCommand(command: ScenarEmbedCommand): ScenarEmbedCommandMessage {
+  return { source: SCENAR_EMBED_SOURCE, v: SCENAR_EMBED_PROTOCOL_VERSION, ...command };
+}
+
+function isScenarEnvelope(data: unknown): data is Record<string, unknown> & ScenarEmbedEnvelope {
+  if (typeof data !== "object" || data === null) return false;
+  const record = data as Record<string, unknown>;
+  return (
+    record["source"] === SCENAR_EMBED_SOURCE && record["v"] === SCENAR_EMBED_PROTOCOL_VERSION
+  );
+}
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/**
+ * Parse an inbound `MessageEvent.data` into a typed command, or return `null`.
+ *
+ * This is the schema boundary: it rejects anything that is not a well-formed
+ * scenar command of the matching version, including unknown command types and
+ * commands missing or mistyping their required fields. Origin/source-window
+ * checks live in the receiver; this function validates the payload shape only.
+ */
+export function parseEmbedCommand(data: unknown): ScenarEmbedCommand | null {
+  if (!isScenarEnvelope(data)) return null;
+  const type = data["type"];
+  switch (type) {
+    case "play":
+    case "pause":
+    case "prefetch":
+    case "destroy":
+      return { type };
+    case "seek":
+      return isFiniteNumber(data["timeMs"]) ? { type, timeMs: data["timeMs"] } : null;
+    case "setMuted":
+      return typeof data["muted"] === "boolean" ? { type, muted: data["muted"] } : null;
+    case "setVolume":
+      return isFiniteNumber(data["volume"]) ? { type, volume: data["volume"] } : null;
+    default:
+      return null;
+  }
+}
+
+/**
+ * Parse an inbound `MessageEvent.data` into a typed event, or return `null`.
+ *
+ * The symmetric counterpart to {@link parseEmbedCommand} for host-side code
+ * consuming the player's events.
+ */
+export function parseEmbedEvent(data: unknown): ScenarEmbedEvent | null {
+  if (!isScenarEnvelope(data)) return null;
+  const type = data["type"];
+  switch (type) {
+    case "started":
+    case "paused":
+    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 "resize":
+      return isFiniteNumber(data["widthPx"]) && isFiniteNumber(data["heightPx"])
+        ? { type, widthPx: data["widthPx"], heightPx: data["heightPx"] }
+        : null;
+    case "stepchange":
+      return isFiniteNumber(data["stepIndex"]) && isFiniteNumber(data["totalSteps"])
+        ? { type, stepIndex: data["stepIndex"], totalSteps: data["totalSteps"] }
+        : null;
+    case "progress":
+      return isFiniteNumber(data["stepIndex"]) &&
+        isFiniteNumber(data["totalSteps"]) &&
+        isFiniteNumber(data["fraction"])
+        ? {
+            type,
+            stepIndex: data["stepIndex"],
+            totalSteps: data["totalSteps"],
+            fraction: data["fraction"],
+          }
+        : null;
+    case "error":
+      return typeof data["message"] === "string" ? { type, message: data["message"] } : null;
+    default:
+      return null;
+  }
+}

package/src/index.ts

@@ -52,3 +52,27 @@ export {
   cursorTargetSelector,
   scrollTargetSelector,
 } from "./targeting/data-attributes.js";
+
+// Embed postMessage protocol (v1) — the cross-origin iframe wire contract
+export {
+  SCENAR_EMBED_SOURCE,
+  SCENAR_EMBED_PROTOCOL_VERSION,
+  frameEmbedEvent,
+  frameEmbedCommand,
+  parseEmbedCommand,
+  parseEmbedEvent,
+} from "./embed/protocol.js";
+export type {
+  ScenarEmbedEvent,
+  ScenarEmbedCommand,
+  ScenarEmbedEventMessage,
+  ScenarEmbedCommandMessage,
+} from "./embed/protocol.js";
+
+// Embed host controller — framework-free driver for an embedded player
+export { createEmbedHostController } from "./embed/host-controller.js";
+export type {
+  ScenarEmbedHostController,
+  ScenarEmbedHostTarget,
+  ScenarEmbedHostOptions,
+} from "./embed/host-controller.js";