@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.1

package/dist/help-examples.d.ts

@@ -0,0 +1,125 @@
+/**
+ * One-line JSON for a copy-paste example, derived from the pretty-printed
+ * literal so the two can never disagree.
+ */
+export declare function compact(example: string): string;
+/** Indent every line of a multi-line block by two spaces (help-text layout). */
+export declare function indent(block: string): string;
+export declare const packageExample: string;
+export declare const capabilityExample: string;
+export declare const settingsExample: string;
+export declare const settingsUpdateExample: string;
+export declare const engineExample: string;
+export declare const userInterfaceExample: string;
+export declare const setupExample: string;
+export declare const setupUpdateExample: string;
+export declare const scenarioEditorExample: string;
+export declare const scenarioEditorUpdateExample: string;
+export declare const packageUpdateExample: string;
+export declare const capabilityUpdateExample: string;
+export declare const engineUpdateExample: string;
+export declare const userInterfaceUpdateExample: string;
+export declare const tickControllerExample: string;
+export declare const tickControllerUpdateExample: string;
+export declare const hookExample: string;
+export declare const hookUpdateExample: string;
+export declare const validatorExample: string;
+export declare const validatorUpdateExample: string;
+export declare const endpointExample: string;
+export declare const endpointUpdateExample: string;
+export declare const sessionUserInterfaceExample: string;
+export declare const sessionUserInterfaceUpdateExample: string;
+export declare const waitingRoomUserInterfaceExample: string;
+export declare const waitingRoomUserInterfaceUpdateExample: string;
+export declare const presentationExample: string;
+export declare const presentationUpdateExample: string;
+export declare const scenarioExample: string;
+export declare const scenarioUpdateExample: string;
+export declare const facilitatorGuideExample: string;
+export declare const facilitatorGuideUpdateExample: string;
+/**
+ * The one example per resource type and command, looked up by type.
+ *
+ * Three families of example used to be written separately: the `--help` text
+ * (wired to these literals by #448), the `Expected format` block a `new` or
+ * `update` prints when it cannot parse its input, and the expected shape a
+ * schema-validation failure prints. Only the first was ever checked, so the
+ * other two rotted where an author is already stuck — thirteen of them still
+ * showed the dotted identifiers the CLI has rejected since #433. All three now
+ * render from here (#473).
+ */
+export declare const RESOURCE_EXAMPLES: {
+    readonly package: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly capability: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly settings: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly engine: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly ui: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly setup: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly scenario_editor: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly tick_controller: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly session: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly waiting_room: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly presentation: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly scenario: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly guide: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly hook: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly validator: {
+        readonly new: string;
+        readonly update: string;
+    };
+    readonly endpoint: {
+        readonly new: string;
+        readonly update: string;
+    };
+};
+/** A resource type with a documented example. */
+export type ExampledResourceType = keyof typeof RESOURCE_EXAMPLES;
+/**
+ * The example for a type and command.
+ *
+ * Every caller reaches an example this way, so a type registered without one is
+ * a compile error rather than a message that quietly says nothing.
+ */
+export declare function resourceExample(type: ExampledResourceType, command: 'new' | 'update'): string;

package/dist/host/adapter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The side effects a host channel delegates to its embedder.
+ *
+ * The channel owns the §12 protocol: the handshake, the initial batch,
+ * correlation, framing, and teardown. It owns none of the work those messages
+ * ask for, because that work is where the SDK dev server and a production
+ * platform genuinely differ — one calls into an in-process executor, the other
+ * into an HTTP API. Everything an embedder must supply is here, and it is the
+ * only place the two implementations diverge.
+ *
+ * Every method may throw. The channel catches, frames the failure as the
+ * protocol's `ok: false` response for that request, and keeps the port open: a
+ * failing endpoint must not take the surface down with it.
+ */
+import type { PastStateEntry, PastStateQuery, Participant } from '@seriousgaming/sdk';
+/** Who is asking. Supplied to every adapter call so it can authorise. */
+export interface RequestOrigin {
+    /** Identifier of the UI bundle mounted in this frame. */
+    uiIdentifier: string;
+    /** The team whose surface this is, where the surface belongs to one. */
+    teamId?: string;
+    /** The participant this render is identified as, absent for an observer. */
+    participantId?: string;
+}
+export interface HostAdapter {
+    /**
+     * Invoke a server-side endpoint (§6.12).
+     *
+     * The adapter is responsible for the `endpoints` allowlist, request and
+     * response schema validation, and execution. The channel only correlates.
+     * Resolve with the response; on failure throw an `EndpointError` carrying
+     * the call's `EndpointFailure`, which the channel sends as it stands. Any
+     * other throw reaches the surface as `{ kind: 'error' }` with nothing
+     * applied.
+     */
+    callEndpoint?(request: {
+        endpointIdentifier: string;
+        request: unknown;
+    }, origin: RequestOrigin): Promise<unknown>;
+    /**
+     * Store an uploaded file and return its `blob:<id>` reference (§16.2).
+     *
+     * The lifecycle bucket is the host's to assign from the surface kind; the
+     * guest has no say in it.
+     */
+    uploadBlob?(file: {
+        data: ArrayBuffer;
+        name: string;
+        mimeType: string;
+    }, origin: RequestOrigin): Promise<string>;
+    /**
+     * Answer a read-only history query (§12.5).
+     *
+     * The adapter resolves `query.teams` and bounds `capabilityIds` server-side.
+     * An unreachable tick or team is an absent row, not a fault, so the normal
+     * answer to a query that reaches nothing is an empty array.
+     */
+    getPastState?(query: PastStateQuery, origin: RequestOrigin): Promise<PastStateEntry[]>;
+    /**
+     * Every team's current roster, flattened (§12.5).
+     *
+     * Gated by the bundle's `crossTeamParticipants` declaration, which the
+     * adapter checks: an undeclared surface is answered with an empty array
+     * rather than an error.
+     */
+    getAllTeamsParticipants?(origin: RequestOrigin): Promise<Participant[]>;
+}

package/dist/host/host-channel.d.ts

@@ -0,0 +1,222 @@
+/**
+ * The host half of the §12 host ↔ iframe protocol, with no framework in it.
+ *
+ * The guest half of this channel is `useHostChannel` and the wrapper components
+ * in `@seriousgaming/sdk/ui`. The two halves hold their own
+ * definitions of the wire protocol, and `protocol.parity.test.ts` refuses to
+ * compile when they disagree, so neither end can change alone.
+ *
+ * It owns the lifecycle and nothing else:
+ *
+ * - the window-level `ready` / `init` handshake, origin-pinned per §12.2
+ * - a bounded handshake, so a frame that has navigated itself away is detected
+ *   rather than left spinning (§16.6)
+ * - the required initial batch per surface kind (§12.6)
+ * - reconnection: close the old port, fresh channel, re-send the batch (§12.7)
+ * - correlation and framing for every request in both directions
+ * - diffing, so an unchanged slice is not re-pushed
+ *
+ * Everything those messages actually *do* is the embedder's, through
+ * {@link HostAdapter}. That split is what lets one implementation serve both
+ * the SDK dev server and a production runtime.
+ *
+ * Platform-facing: exported from `@seriousgaming/sdk-tools/host` so the dev
+ * server and the Serious Gaming platform can share one implementation; the
+ * shape may change in a minor release.
+ */
+import type { HostAdapter, RequestOrigin } from './adapter.js';
+import { type SurfaceKind } from './surfaces.js';
+/** Any host → guest port message. Narrowed by the surface's own union. */
+export interface HostMessage {
+    type: string;
+    [key: string]: unknown;
+}
+/** Any guest → host port message. */
+export interface GuestMessage {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * The bits of `window` the channel touches.
+ *
+ * Injected rather than reached for, so the whole handshake is exercisable in a
+ * unit test with two fake windows and a real `MessageChannel`, which is what
+ * moves this off Playwright.
+ */
+export interface WindowLike {
+    addEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+    removeEventListener(type: 'message', listener: (event: MessageEvent) => void): void;
+}
+/** The bit of an iframe element the channel touches. */
+export interface FrameLike {
+    readonly contentWindow: {
+        postMessage(message: unknown, targetOrigin: string, transfer?: Transferable[]): void;
+    } | null;
+    /**
+     * The element's `load` event, fired for every document the frame loads.
+     * A frame without it is bounded on its first load only.
+     */
+    addEventListener?(type: 'load', listener: () => void): void;
+    removeEventListener?(type: 'load', listener: () => void): void;
+}
+/** Why a channel tore itself down. */
+export type TeardownReason = 
+/** No `ready` arrived within the handshake bound (§16.6). */
+'handshake-timeout'
+/** `dispose()` was called. */
+ | 'disposed';
+export interface HostChannelOptions {
+    /** The frame this channel is bound to. */
+    iframe: FrameLike;
+    /** Which surface the frame is rendering (§12.6). */
+    surface: SurfaceKind;
+    /** Identifier of the UI bundle mounted in the frame, for adapter calls. */
+    uiIdentifier: string;
+    /**
+     * Origin the frame is served from. Used as `targetOrigin` on `init`, and
+     * matched against the incoming `ready` (§12.2).
+     */
+    iframeOrigin: string;
+    /**
+     * The run's storage key, sent on every `init` (§12.2): opaque, the same for
+     * every surface of one run and for its whole life, different for every
+     * other run, the walkthrough beside it included, and never anything the
+     * host would accept as naming the session.
+     */
+    sessionKey: string;
+    /** Window to listen for the `ready` handshake on. Defaults to `window`. */
+    window?: WindowLike;
+    /** Side effects. A channel with no adapter answers every request as failed. */
+    adapter?: HostAdapter;
+    /** Identity carried into adapter calls. */
+    origin?: Omit<RequestOrigin, 'uiIdentifier'>;
+    /** An observer render receives no `setParticipant` (§13.3). */
+    observer?: boolean;
+    /**
+     * How long to wait for `ready` before treating the frame as gone. A frame
+     * that has navigated itself to a third-party page never handshakes, and
+     * neither the sandbox attribute nor CSP prevents that, so this bound is the
+     * only way to detect it (§16.6). Defaults to 10 seconds.
+     */
+    handshakeTimeoutMs?: number;
+    /** Guest messages the channel does not answer itself. */
+    onMessage?(message: GuestMessage): void;
+    /** Called each time the handshake completes, reconnections included. */
+    onConnect?(): void;
+    /** Called when the channel gives up on the frame. */
+    onTeardown?(reason: TeardownReason): void;
+    /** Where diagnostics go. Defaults to `console`. */
+    logger?: Pick<Console, 'warn' | 'error'>;
+}
+export declare class HostChannel {
+    private readonly options;
+    private readonly host;
+    private readonly logger;
+    private port;
+    private readyListener;
+    private loadListener;
+    private handshakeTimer;
+    private disposed;
+    /**
+     * Last payload sent per message type, serialised.
+     *
+     * `setState` compares against this so an unchanged slice is not re-pushed.
+     * At a large cohort the session payload is the thing that grows, and
+     * re-sending a whole snapshot because one team's tick moved is the cost
+     * §12.4.2 warns about.
+     */
+    private lastSent;
+    /**
+     * The last value of each state message, in the order the types were first
+     * sent, replayed whole on every reconnect (§12.7 step 3).
+     *
+     * A reloading frame has seen nothing, and the embedder has no reason to
+     * push again: its state has not changed, only the frame under it. Without
+     * this the guest re-handshakes into silence and blocks its first paint for
+     * good, which is what a surface fixed after a crash used to do (#564).
+     *
+     * Only the state slices are kept. A one-shot the host sent once, such as a
+     * validator's refusal or an asset-auth request, belongs to the moment it
+     * happened, and replaying it would show the new frame a rejection of a
+     * submission it never made.
+     */
+    private sticky;
+    /** One-shot messages queued until the handshake completes, flushed in order. */
+    private outbound;
+    /** In-flight host → guest requests, keyed by `requestId`. */
+    private pending;
+    private requestCounter;
+    constructor(options: HostChannelOptions);
+    /** True once the guest has handshaked and the port is open. */
+    get connected(): boolean;
+    /**
+     * Push one message, queueing it until the handshake completes.
+     *
+     * Queueing rather than dropping is what lets an embedder build the initial
+     * batch as soon as it mounts the frame, without racing the guest's `ready`.
+     */
+    send(message: HostMessage): void;
+    /**
+     * Push a state slice: delivered now if the guest is listening, and kept so
+     * a frame that reloads is told the same thing again.
+     */
+    private sendState;
+    /**
+     * Push a message only when its payload differs from the last one sent of
+     * that type. Returns true when it went out.
+     */
+    sendIfChanged(message: HostMessage): boolean;
+    /**
+     * Send the initial batch (§12.6), verifying it carries every message the
+     * surface blocks its first paint on.
+     *
+     * The guest enforces the same list for itself by simply not painting. That
+     * failure mode is a frame stuck on its loading state with nothing to say
+     * why, which is a bad afternoon; failing here names the missing message.
+     */
+    sendInitialBatch(messages: readonly HostMessage[]): void;
+    /**
+     * Send a request the guest answers, resolving when it does.
+     *
+     * Only `refreshAssetAuth` uses this today (§16.4): the host hands the frame
+     * a token and the frame reports back whether redeeming it worked.
+     */
+    request(message: {
+        type: string;
+    } & Record<string, unknown>, timeoutMs?: number): Promise<void>;
+    dispose(): void;
+    private listenForReady;
+    /**
+     * Bound every document the frame loads, not only the first.
+     *
+     * A frame that connected and then replaced its own document leaves the
+     * host holding a port nobody answers, so `connected` alone proves nothing.
+     * A document's `ready` may land either side of its `load`, so a live port
+     * is pinged as well: a `pong` shows the document that handshaked is still
+     * the one in the frame, and a fresh `ready` shows a reload.
+     */
+    private listenForLoads;
+    private armHandshakeTimer;
+    /**
+     * Open a fresh port and hand the guest its end.
+     *
+     * Runs on every `ready`, not only the first: a reload or HMR re-announces,
+     * and §12.7 requires the old port closed, a new channel created, and the
+     * whole initial batch re-sent rather than the live port re-identified.
+     */
+    private connect;
+    private closePort;
+    private clearHandshakeTimer;
+    private rejectPending;
+    private receive;
+    /**
+     * Run one guest request against the adapter and frame the answer.
+     *
+     * A throwing adapter becomes an `ok: false` response on the same
+     * `requestId`, never an unhandled rejection and never a dropped request:
+     * the guest's promise has to settle either way or the surface waits forever.
+     */
+    private answer;
+    /** Route one request to its adapter method and shape the success payload. */
+    private dispatch;
+}

package/dist/host/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The host half of the host ↔ iframe protocol (§12).
+ *
+ * Reachable as `@seriousgaming/sdk-tools/host`.
+ *
+ * Platform-facing. Game authors never write a host and never import from
+ * here; this exists so the dev server and the Serious Gaming platform share one
+ * implementation of §12 instead of transcribing the same 900 lines of prose
+ * twice. It carries the channel, the surface table, the adapter an embedder
+ * supplies, and the host's definition of the wire messages. The guest half is
+ * the UI wrappers in `@seriousgaming/sdk/ui`. The shapes
+ * may change in a minor release.
+ */
+export { HostChannel } from './host-channel.js';
+export type { FrameLike, GuestMessage, HostChannelOptions, HostMessage, TeardownReason, WindowLike, } from './host-channel.js';
+export type { HostAdapter, RequestOrigin } from './adapter.js';
+export { isPlayerSurface, requiredMessagesFor, SURFACES, type SurfaceDescriptor, type SurfaceKind, } from './surfaces.js';
+export { UI_PROTOCOL_VERSION } from './protocol.js';
+export type { AssetUrls, HostSettingsEditorPortMessage, HostPortMessage, HostPresentationPortMessage, HostSessionPortMessage, HostWindowMessage, IFrameSettingsEditorPortMessage, IFrameMessage, IFramePortMessage, IFramePresentationPortMessage, IFrameSessionPortMessage, } from './protocol.js';
+export { contrastTextFor, THEME_COLOR_ROLES, withContrastText, type ModeColoursInput, type ThemeInput, } from './theme.js';