@protoyard/player 0.0.0-stage → 1.1.0

package/dist/boot/validation/store.js

@@ -0,0 +1,82 @@
+import { Dexie } from 'dexie';
+/**
+ * Validation metrics, stored per blueprint in the browser
+ * (`protoyard.<namespace>.validation`), next to the blueprint's data and
+ * control databases and never sent anywhere. They can be downloaded as a
+ * `protoyard-validation-metrics` v1 file for `protoyard quick report`.
+ */
+export const VALIDATION_METRICS_FORMAT = 'protoyard-validation-metrics';
+export const VALIDATION_METRICS_VERSION = 1;
+export function validationDatabaseName(namespace) {
+    return `protoyard.${namespace}.validation`;
+}
+const TASK_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const OUTCOMES = new Set(['success', 'gave-up', 'timed-out']);
+const isCount = (value) => Number.isInteger(value) && value >= 0;
+const isInstant = (value) => typeof value === 'string' && !Number.isNaN(Date.parse(value));
+/** Checks an attempt before it is stored (the player has no schema library). */
+export function assertAttempt(value) {
+    const ok = typeof value.taskId === 'string' &&
+        value.taskId.length <= 48 &&
+        TASK_ID.test(value.taskId) &&
+        OUTCOMES.has(value.outcome) &&
+        isCount(value.durationMs) &&
+        isCount(value.steps) &&
+        isInstant(value.startedAt) &&
+        isInstant(value.endedAt);
+    if (!ok)
+        throw new TypeError('Invalid validation attempt.');
+    const { taskId, outcome, durationMs, steps, startedAt, endedAt } = value;
+    return { taskId, outcome, durationMs, steps, startedAt, endedAt };
+}
+class ValidationDatabase extends Dexie {
+    attempts;
+    constructor(name, options) {
+        super(name, options);
+        this.version(1).stores({ attempts: '++id, taskId, startedAt' });
+    }
+}
+export function openValidationStore(namespace, options = {}) {
+    const db = new ValidationDatabase(validationDatabaseName(namespace), {
+        ...(options.indexedDB ? { indexedDB: options.indexedDB } : {}),
+        ...(options.IDBKeyRange ? { IDBKeyRange: options.IDBKeyRange } : {}),
+    });
+    return {
+        async record(attempt) {
+            await db.attempts.add(assertAttempt(attempt));
+        },
+        async list() {
+            const rows = await db.attempts.orderBy('id').toArray();
+            return rows.map(({ id: _id, ...attempt }) => attempt);
+        },
+        clear: async () => {
+            await db.attempts.clear();
+        },
+        close: () => db.close(),
+    };
+}
+/** The download file: tasks and attempts, nothing else from the prototype. */
+export function metricsFile(input) {
+    return {
+        format: VALIDATION_METRICS_FORMAT,
+        version: VALIDATION_METRICS_VERSION,
+        blueprint: { name: input.name, namespace: input.namespace },
+        exportedAt: (input.now ?? (() => new Date()))().toISOString(),
+        tasks: input.tasks.map(({ id, prompt }) => ({ id, prompt })),
+        attempts: input.attempts.map(assertAttempt),
+    };
+}
+/** Saves the metrics file through the browser's download, with no upload. */
+export function downloadMetrics(file, doc = document) {
+    const name = `${file.blueprint.namespace}-validation-metrics.json`;
+    const url = URL.createObjectURL(new Blob([`${JSON.stringify(file, null, 2)}\n`], { type: 'application/json' }));
+    const link = doc.createElement('a');
+    link.href = url;
+    link.download = name;
+    link.rel = 'noopener';
+    doc.body.append(link);
+    link.click();
+    link.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 0);
+    return name;
+}

package/dist/boot/worker/generate-worker-runtime.d.ts

@@ -0,0 +1,7 @@
+import type { GenerateWorldReply, GenerateWorldRequest } from './protocol.ts';
+export interface GeneratorWorkerScope {
+    addEventListener(type: 'message', listener: (event: MessageEvent<GenerateWorldRequest>) => void): void;
+    postMessage(message: GenerateWorldReply): void;
+}
+export declare function handleGenerateWorldRequest(request: GenerateWorldRequest): Promise<GenerateWorldReply>;
+export declare function installGenerateWorldWorker(scope: GeneratorWorkerScope): void;

package/dist/boot/worker/generate-worker-runtime.js

@@ -0,0 +1,20 @@
+import { generateBlueprintWorld } from "./generate-world-core.js";
+export async function handleGenerateWorldRequest(request) {
+    try {
+        return {
+            ok: true,
+            world: await generateBlueprintWorld(request.blueprint, request.scenario),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: error instanceof Error ? error.message : 'World generation failed.',
+        };
+    }
+}
+export function installGenerateWorldWorker(scope) {
+    scope.addEventListener('message', (event) => {
+        void handleGenerateWorldRequest(event.data).then((reply) => scope.postMessage(reply));
+    });
+}

package/dist/boot/worker/generate-world-core.d.ts

@@ -0,0 +1,4 @@
+import type { Blueprint } from '@protoyard/blueprint';
+import type { GenerateContext, Scenario, WorldSeed } from '@protoyard/core';
+/** Build a blueprint world from serializable inputs in the worker or fallback chunk. */
+export declare function generateBlueprintWorld(blueprint: Blueprint, scenario: Scenario, context?: GenerateContext): Promise<WorldSeed>;

package/dist/boot/worker/generate-world-core.js

@@ -0,0 +1,8 @@
+/** Build a blueprint world from serializable inputs in the worker or fallback chunk. */
+export async function generateBlueprintWorld(blueprint, scenario, context) {
+    const { createBlueprintGenerator } = await import('@protoyard/blueprint/generator');
+    if (context)
+        return createBlueprintGenerator(blueprint).generate(context);
+    const { createGenerateContextAsync } = await import('@protoyard/scenarios');
+    return createBlueprintGenerator(blueprint).generate(await createGenerateContextAsync(scenario));
+}

package/dist/boot/worker/generate-world.d.ts

@@ -0,0 +1,32 @@
+import type { Blueprint } from '@protoyard/blueprint';
+import type { GenerateContext, PrototypeDefinition, Scenario, WorldSeed } from '@protoyard/core';
+import type { GenerateWorldReply, GenerateWorldRequest } from './protocol.ts';
+export interface GenerateWorldWorker {
+    onmessage: ((event: MessageEvent<GenerateWorldReply>) => void) | null;
+    onerror: ((event: ErrorEvent) => void) | null;
+    postMessage(message: GenerateWorldRequest): void;
+    terminate(): void;
+}
+/**
+ * A generation error the worker reported (`{ ok: false }`): the blueprint or
+ * scenario cannot be generated, so running it again on the main thread would
+ * only fail a second time while blocking the page.
+ */
+export declare class WorldGenerationError extends Error {
+    constructor(message: string);
+}
+export interface WorkerGenerationOptions {
+    /** Test seam; browsers use the module worker by default. */
+    createWorker?: () => GenerateWorldWorker;
+}
+/**
+ * Generate from blueprint + scenario data. The main thread takes over only
+ * when the worker is unavailable: it cannot be created, or it fails to start
+ * or run (`onerror`). A generation error the worker reports is thrown as a
+ * {@link WorldGenerationError}, never generated a second time. The main-thread
+ * fallback is a lazy chunk, so the generator is absent from the player's
+ * initial graph.
+ */
+export declare function generatePlayerWorld(blueprint: Blueprint, scenario: Scenario, options?: WorkerGenerationOptions, fallbackContext?: GenerateContext): Promise<WorldSeed>;
+/** Keep the runtime contract; only the data needed by the worker crosses threads. */
+export declare function withWorkerGeneration(definition: PrototypeDefinition, blueprint: Blueprint, options?: WorkerGenerationOptions): PrototypeDefinition;

package/dist/boot/worker/generate-world.js

@@ -0,0 +1,80 @@
+/**
+ * A generation error the worker reported (`{ ok: false }`): the blueprint or
+ * scenario cannot be generated, so running it again on the main thread would
+ * only fail a second time while blocking the page.
+ */
+export class WorldGenerationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorldGenerationError';
+    }
+}
+function createBrowserWorker() {
+    if (typeof Worker === 'undefined')
+        throw new Error('Web Workers are unavailable.');
+    return new Worker(new URL('./generate.worker.js', import.meta.url), {
+        type: 'module',
+    });
+}
+async function generateOnMainThread(blueprint, scenario, context) {
+    const { generateBlueprintWorld } = await import("./generate-world-core.js");
+    return generateBlueprintWorld(blueprint, scenario, context);
+}
+async function generateWithWorker(worker, request) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            worker.terminate();
+        };
+        worker.onmessage = ({ data }) => {
+            finish();
+            if (data.ok)
+                resolve(data.world);
+            else
+                reject(new WorldGenerationError(data.message));
+        };
+        worker.onerror = (event) => {
+            event.preventDefault();
+            finish();
+            reject(new Error(event.message || 'World generation worker failed.'));
+        };
+        try {
+            worker.postMessage(request);
+        }
+        catch (error) {
+            finish();
+            reject(error);
+        }
+    });
+}
+/**
+ * Generate from blueprint + scenario data. The main thread takes over only
+ * when the worker is unavailable: it cannot be created, or it fails to start
+ * or run (`onerror`). A generation error the worker reports is thrown as a
+ * {@link WorldGenerationError}, never generated a second time. The main-thread
+ * fallback is a lazy chunk, so the generator is absent from the player's
+ * initial graph.
+ */
+export async function generatePlayerWorld(blueprint, scenario, options = {}, fallbackContext) {
+    try {
+        const worker = (options.createWorker ?? createBrowserWorker)();
+        return await generateWithWorker(worker, { blueprint, scenario });
+    }
+    catch (error) {
+        if (error instanceof WorldGenerationError)
+            throw error;
+        return generateOnMainThread(blueprint, scenario, fallbackContext);
+    }
+}
+/** Keep the runtime contract; only the data needed by the worker crosses threads. */
+export function withWorkerGeneration(definition, blueprint, options = {}) {
+    return {
+        ...definition,
+        generate: (context) => generatePlayerWorld(blueprint, context.scenario, options, context),
+        // Scenario loads call this, so the main thread never builds a context.
+        generateWorld: (scenario) => generatePlayerWorld(blueprint, scenario, options),
+    };
+}

package/dist/boot/worker/generate.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/boot/worker/generate.worker.js

@@ -0,0 +1,2 @@
+import { installGenerateWorldWorker, } from "./generate-worker-runtime.js";
+installGenerateWorldWorker(self);

package/dist/boot/worker/protocol.d.ts

@@ -0,0 +1,13 @@
+import type { Blueprint } from '@protoyard/blueprint';
+import type { Scenario, WorldSeed } from '@protoyard/core';
+export interface GenerateWorldRequest {
+    blueprint: Blueprint;
+    scenario: Scenario;
+}
+export type GenerateWorldReply = {
+    ok: true;
+    world: WorldSeed;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/embed/client.d.ts

@@ -0,0 +1,51 @@
+import { type PlayerIssue, type PlayerMessage } from './protocol.ts';
+/**
+ * The embedding side of `protoyard-player/1`, for pages that frame the
+ * player (protoyard.app/play, `protoyard quick` iterate):
+ *
+ *   const player = connectPlayer({ frame: iframe, playerOrigin: 'https://protoyard.app' });
+ *   await player.ready;
+ *   const { namespace } = await player.load(blueprint);
+ *   await player.replace(editedBlueprint); // live iterate
+ *
+ * The frame's URL must name this page's origin in `?embedder=`. Messages are
+ * accepted only from the frame's window at `playerOrigin`.
+ */
+export declare class PlayerEmbedError extends Error {
+    readonly issues: PlayerIssue[];
+    constructor(message: string, issues?: PlayerIssue[]);
+}
+/** The host window surface the client needs (tests pass a fake). */
+export interface ClientWindow {
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+export interface ConnectPlayerOptions {
+    /** The iframe running the player (or anything exposing its window). */
+    frame: {
+        contentWindow: {
+            postMessage(message: unknown, targetOrigin: string): void;
+        } | null;
+    };
+    /** The player's exact origin; never `*`. */
+    playerOrigin: string;
+    window?: ClientWindow;
+    /** How long `ready` and each request may take (default 30 s). */
+    timeoutMs?: number;
+}
+export interface PlayerConnection {
+    /** Resolves with the player's `ready` message. */
+    ready: Promise<Extract<PlayerMessage, {
+        type: 'ready';
+    }>>;
+    load(blueprint: unknown): Promise<{
+        namespace: string;
+        name: string;
+    }>;
+    replace(blueprint: unknown): Promise<{
+        namespace: string;
+        name: string;
+    }>;
+    close(): void;
+}
+export declare function connectPlayer(options: ConnectPlayerOptions): PlayerConnection;

package/dist/embed/client.js

@@ -0,0 +1,101 @@
+import { isPlayerMessage, PLAYER_PROTOCOL, } from "./protocol.js";
+/**
+ * The embedding side of `protoyard-player/1`, for pages that frame the
+ * player (protoyard.app/play, `protoyard quick` iterate):
+ *
+ *   const player = connectPlayer({ frame: iframe, playerOrigin: 'https://protoyard.app' });
+ *   await player.ready;
+ *   const { namespace } = await player.load(blueprint);
+ *   await player.replace(editedBlueprint); // live iterate
+ *
+ * The frame's URL must name this page's origin in `?embedder=`. Messages are
+ * accepted only from the frame's window at `playerOrigin`.
+ */
+export class PlayerEmbedError extends Error {
+    issues;
+    constructor(message, issues = []) {
+        super(message);
+        this.name = 'PlayerEmbedError';
+        this.issues = issues;
+    }
+}
+export function connectPlayer(options) {
+    const { playerOrigin } = options;
+    if (playerOrigin === '*' || !/^https?:\/\/[^/]+$/.test(playerOrigin)) {
+        throw new PlayerEmbedError(`playerOrigin must be an exact http(s) origin, got "${playerOrigin}".`);
+    }
+    const host = options.window ?? globalThis;
+    const timeoutMs = options.timeoutMs ?? 30_000;
+    const waiting = new Map();
+    let sequence = 0;
+    let closed = false;
+    let markReady = () => { };
+    let failReady = () => { };
+    const ready = new Promise((resolve, reject) => {
+        markReady = resolve;
+        failReady = reject;
+    });
+    const readyTimer = setTimeout(() => failReady(new PlayerEmbedError('The player did not report ready in time.')), timeoutMs);
+    const onMessage = (event) => {
+        if (event.origin !== playerOrigin)
+            return;
+        if (!options.frame.contentWindow || event.source !== options.frame.contentWindow)
+            return;
+        const data = event.data;
+        if (!isPlayerMessage(data))
+            return;
+        if (data.type === 'ready') {
+            clearTimeout(readyTimer);
+            markReady(data);
+            return;
+        }
+        const entry = waiting.get(data.id);
+        if (!entry)
+            return;
+        waiting.delete(data.id);
+        if (data.type === 'loaded')
+            entry.resolve({ namespace: data.namespace, name: data.name });
+        else
+            entry.reject(new PlayerEmbedError(data.issues[0]?.message ?? 'The player refused the blueprint.', data.issues));
+    };
+    host.addEventListener('message', onMessage);
+    function send(type, blueprint) {
+        if (closed)
+            return Promise.reject(new PlayerEmbedError('The connection is closed.'));
+        const target = options.frame.contentWindow;
+        if (!target)
+            return Promise.reject(new PlayerEmbedError('The player frame has no window yet.'));
+        sequence += 1;
+        const id = `req-${sequence}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                waiting.delete(id);
+                reject(new PlayerEmbedError(`The player did not answer ${type} in time.`));
+            }, timeoutMs);
+            waiting.set(id, {
+                resolve(value) {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject(error) {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            });
+            target.postMessage({ protocol: PLAYER_PROTOCOL, type, id, blueprint }, playerOrigin);
+        });
+    }
+    return {
+        ready,
+        load: (blueprint) => send('load', blueprint),
+        replace: (blueprint) => send('replace', blueprint),
+        close() {
+            closed = true;
+            clearTimeout(readyTimer);
+            host.removeEventListener('message', onMessage);
+            for (const entry of waiting.values())
+                entry.reject(new PlayerEmbedError('The connection is closed.'));
+            waiting.clear();
+        },
+    };
+}

package/dist/embed/index.d.ts

@@ -0,0 +1,32 @@
+import type { AnyBlueprint } from '@protoyard/blueprint';
+import { type EmbedListener } from './listener.ts';
+import type { PlayerRequestType } from './protocol.ts';
+export { connectPlayer, type PlayerConnection, PlayerEmbedError } from './client.ts';
+export { createEmbedListener, type EmbedListener } from './listener.ts';
+export { DEFAULT_ALLOWLIST, embedderOrigins, exactOrigin } from './origins.ts';
+export { checkRequest, isPlayerMessage, MAX_MESSAGE_BLUEPRINT_BYTES, PLAYER_PROTOCOL, type PlayerIssue, type PlayerMessage, type PlayerRequestType, } from './protocol.ts';
+/** Something `startEmbed` can tear down before running the next blueprint. */
+export interface RunningPrototype {
+    namespace: string;
+    destroy(): Promise<void>;
+}
+export interface StartEmbedOptions {
+    window: Window;
+    /**
+     * Swaps the running prototype for a validated blueprint, when the caller
+     * owns what is running (the player's run.ts, which live reload also swaps):
+     * it tears down the current prototype itself, so the embed keeps no copy.
+     */
+    replace?(blueprint: AnyBlueprint, type: PlayerRequestType): Promise<RunningPrototype>;
+    /** Without `replace`: boots a validated blueprint (in the player: `bootPlayer`). */
+    boot?(blueprint: AnyBlueprint, type: PlayerRequestType): Promise<RunningPrototype>;
+    /** Without `replace`: what is running now, if anything, torn down before each boot. */
+    current?: RunningPrototype | null;
+}
+/**
+ * Turns the embed protocol on for a framed player: listens to its parent
+ * on the allowed origins and swaps the running prototype on each accepted
+ * `load` or `replace`. Returns null (and listens to nothing) when the page is
+ * not framed, so a top-level player never accepts messages.
+ */
+export declare function startEmbed(options: StartEmbedOptions): EmbedListener | null;

package/dist/embed/index.js

@@ -0,0 +1,37 @@
+import { createEmbedListener } from "./listener.js";
+import { embedderOrigins } from "./origins.js";
+export { connectPlayer, PlayerEmbedError } from "./client.js";
+export { createEmbedListener } from "./listener.js";
+export { DEFAULT_ALLOWLIST, embedderOrigins, exactOrigin } from "./origins.js";
+export { checkRequest, isPlayerMessage, MAX_MESSAGE_BLUEPRINT_BYTES, PLAYER_PROTOCOL, } from "./protocol.js";
+/**
+ * Turns the embed protocol on for a framed player: listens to its parent
+ * on the allowed origins and swaps the running prototype on each accepted
+ * `load` or `replace`. Returns null (and listens to nothing) when the page is
+ * not framed, so a top-level player never accepts messages.
+ */
+export function startEmbed(options) {
+    const win = options.window;
+    if (!win.parent || win.parent === win)
+        return null;
+    const origins = embedderOrigins(win.location.search, win.location.origin);
+    if (origins.length === 0)
+        return null;
+    const { replace, boot } = options;
+    if (!replace && !boot)
+        throw new Error('startEmbed needs replace() or boot().');
+    let current = options.current ?? null;
+    return createEmbedListener({
+        window: win,
+        parent: win.parent,
+        origins,
+        async apply(blueprint, type) {
+            if (replace)
+                return { namespace: (await replace(blueprint, type)).namespace };
+            await current?.destroy();
+            current = null;
+            current = await boot(blueprint, type);
+            return { namespace: current.namespace };
+        },
+    });
+}

package/dist/embed/listener.d.ts

@@ -0,0 +1,37 @@
+import { type AnyBlueprint } from '@protoyard/blueprint';
+import { type PlayerMessage, type PlayerRequestType } from './protocol.ts';
+/** The window surface the listener needs (tests pass a fake). */
+export interface EmbedWindow {
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+/** The parent the player answers; `postMessage` always names an exact origin. */
+export interface EmbedParent {
+    postMessage(message: PlayerMessage, targetOrigin: string): void;
+}
+export interface EmbedListenerOptions {
+    window: EmbedWindow;
+    parent: EmbedParent;
+    /** Exact origins allowed to send requests (see `embedderOrigins`). */
+    origins: readonly string[];
+    /**
+     * Runs a validated blueprint. Resolves with what the parent is told; a
+     * throw is reported as `boot-failed`, never as success.
+     */
+    apply(blueprint: AnyBlueprint, type: PlayerRequestType): Promise<{
+        namespace: string;
+    }>;
+    maxBytes?: number;
+}
+export interface EmbedListener {
+    /** Settles when no request is running or waiting (tests). */
+    idle(): Promise<void>;
+    stop(): void;
+}
+/**
+ * Listens for `protoyard-player/1` requests from the parent window and
+ * answers each one exactly once. Requests run one at a time; while one runs,
+ * only the newest waiting request is kept (live iterate sends many
+ * `replace`s), and the dropped one is answered `superseded`.
+ */
+export declare function createEmbedListener(options: EmbedListenerOptions): EmbedListener;

package/dist/embed/listener.js

@@ -0,0 +1,91 @@
+import { loadUntrustedDocument } from '@protoyard/blueprint';
+import { checkRequest, MAX_MESSAGE_BLUEPRINT_BYTES, PLAYER_PROTOCOL, playerIssue, } from "./protocol.js";
+/**
+ * Listens for `protoyard-player/1` requests from the parent window and
+ * answers each one exactly once. Requests run one at a time; while one runs,
+ * only the newest waiting request is kept (live iterate sends many
+ * `replace`s), and the dropped one is answered `superseded`.
+ */
+export function createEmbedListener(options) {
+    const origins = new Set(options.origins);
+    const maxBytes = options.maxBytes ?? MAX_MESSAGE_BLUEPRINT_BYTES;
+    let running = null;
+    let waiting = null;
+    let stopped = false;
+    const reply = (message, origin) => {
+        if (!stopped)
+            options.parent.postMessage(message, origin);
+    };
+    const fail = (id, issues, origin) => reply({ protocol: PLAYER_PROTOCOL, type: 'error', id, issues }, origin);
+    async function run({ request, origin }) {
+        // Any kind (ADR-036): apps keep the app loader; decks, pages and docs their own caps.
+        const loaded = await loadUntrustedDocument(request.blueprint, { maxBytes });
+        if (!loaded.success) {
+            fail(request.id, loaded.issues, origin);
+            return;
+        }
+        try {
+            const { namespace } = await options.apply(loaded.blueprint, request.type);
+            reply({
+                protocol: PLAYER_PROTOCOL,
+                type: 'loaded',
+                id: request.id,
+                namespace,
+                name: loaded.blueprint.name,
+            }, origin);
+        }
+        catch (error) {
+            fail(request.id, [
+                playerIssue('boot-failed', `The blueprint is valid but the prototype did not start: ${error instanceof Error ? error.message : String(error)}`.slice(0, 500), 'Check the blueprint in `protoyard blueprint validate`, then send it again.'),
+            ], origin);
+        }
+    }
+    function drain() {
+        if (running || !waiting || stopped)
+            return;
+        const next = waiting;
+        waiting = null;
+        running = run(next).finally(() => {
+            running = null;
+            drain();
+        });
+    }
+    const onMessage = (event) => {
+        if (stopped)
+            return;
+        // Only the parent, and only from an allowed origin: everything else is ignored.
+        if (event.source !== options.parent)
+            return;
+        if (!origins.has(event.origin))
+            return;
+        const check = checkRequest(event.data, maxBytes);
+        if (check.kind === 'ignore')
+            return;
+        if (check.kind === 'reject') {
+            fail(check.id, check.issues, event.origin);
+            return;
+        }
+        if (waiting) {
+            fail(waiting.request.id, [
+                playerIssue('superseded', 'A newer blueprint arrived before this one started.', 'Nothing to do: the newest blueprint is the one that runs.'),
+            ], waiting.origin);
+        }
+        waiting = { request: check.request, origin: event.origin };
+        drain();
+    };
+    options.window.addEventListener('message', onMessage);
+    for (const origin of origins) {
+        reply({ protocol: PLAYER_PROTOCOL, type: 'ready', accepts: ['load', 'replace'], maxBytes }, origin);
+    }
+    return {
+        async idle() {
+            while (running || waiting)
+                await (running ?? Promise.resolve());
+        },
+        stop() {
+            stopped = true;
+            waiting = null;
+            options.window.removeEventListener('message', onMessage);
+        },
+    };
+}

package/dist/embed/origins.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Which pages may hand the player a blueprint (the embedding decision on
+ * `postMessage` origins): the player's own origin, plus origins named in
+ * `?embedder=` that ALSO match the build-time allowlist. Matching is on the
+ * exact serialized origin (`scheme://host[:port]`); `*`, `null`, paths,
+ * credentials and non-http(s) schemes never qualify.
+ */
+/** A build-time allowlist rule: an exact origin, or a host on any port. */
+export type AllowRule = {
+    origin: string;
+} | {
+    host: string;
+    schemes: ('http:' | 'https:')[];
+};
+/** protoyard.app, and local development on any port. */
+export declare const DEFAULT_ALLOWLIST: readonly AllowRule[];
+/**
+ * The CSP `frame-ancestors` sources for `rules`, so the pages allowed to
+ * frame the player are exactly the pages allowed to send it a blueprint
+ * (`vite.config.ts` builds PLAYER_FRAME_ANCESTORS from DEFAULT_ALLOWLIST).
+ */
+export declare function frameAncestorSources(rules: readonly AllowRule[]): string[];
+/** The canonical origin `value` names, or null when it is not exactly an origin. */
+export declare function exactOrigin(value: string): string | null;
+export declare function allowedByRules(origin: string, rules: readonly AllowRule[]): boolean;
+/**
+ * The origins the player listens to. `search` is `location.search`;
+ * `?embedder=` may repeat. `selfOrigin` is `location.origin` (dropped when it
+ * is opaque, e.g. a `file:` page reports "null").
+ */
+export declare function embedderOrigins(search: string, selfOrigin: string, rules?: readonly AllowRule[]): string[];