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

package/lib/ui/ui-protocol.js

@@ -0,0 +1,50 @@
+/**
+ * The host ↔ iframe MessagePort protocol (§12), as the guest speaks it.
+ *
+ * The wrappers in this package import these unions (via
+ * {@link ./useHostChannel}). Game code never handles a wire message, so no
+ * entry point exports them: the host's definition of the same protocol lives
+ * with the host library in `@seriousgaming/sdk-tools/host`,
+ * and `protocol.parity.test.ts` there fails to compile the moment the two
+ * disagree. Extend a union here and extend the host's in the same change.
+ */
+/**
+ * Version of the host↔iframe handshake protocol. Both ends stamp it on the
+ * `ready`/`init` window messages and warn (without blocking) when the peer's
+ * declared version differs, so a host and an SDK build that have drifted apart
+ * surface a diagnostic instead of failing silently. Bump on any
+ * backwards-incompatible change to the handshake or port message contract.
+ *
+ * Version 2 adds `updateTeamState`: a host may deliver an ongoing session-data
+ * change as one team's state rather than the whole session's, and a session
+ * wrapper merges it. `setSessionData` remains the full snapshot on handshake
+ * and on resync, so a host that only ever sends the snapshot is still
+ * conformant.
+ *
+ * Version 3 gives shared state its own channel: `SessionData` carries the
+ * shared store once as `shared`, each team's `context` carries team scope
+ * only, and `updateSharedState` delivers a change to the store as one message
+ * rather than one per team.
+ *
+ * Version 4 gives each concept one name (#634): the context push `setData`
+ * becomes `stateChanged`, carrying `completedTicks` where it carried `tick`;
+ * `updateConfig` becomes `updateSettings`; a settings editor receives
+ * `setSettings` in place of `setResolvedConfiguration`; `extendTick` carries
+ * `byMs`; `pauseTimer` and `resumeTimer` carry a `requestId`; timers are one
+ * `TimerState` in milliseconds; participants and teams share one shape; and
+ * a failed `callEndpoint:response` carries an `EndpointFailure` (`outcome`,
+ * `applied`, `failedStep`) where it carried an `error` string (#636); and
+ * configuration UIs become the `setup` and `scenario_editor` slots, which are
+ * sent no `setConfigurationSurface` (#637). `init` carries the `sessionKey` a
+ * surface namespaces its own storage by, and every theme colour carries a
+ * `contrastText` (#638).
+ * Version 3 never shipped, so version 4 is the version that ships with
+ * manifest version 3, and a host serving an earlier package speaks the
+ * version that package was built for.
+ *
+ * There is deliberately no capability-negotiation list here. The version alone
+ * is the gate, and it can be, because no published package predates the
+ * feature: it ships in the same release as manifest version 2, and a host
+ * serving a version 1 package sends full snapshots to it.
+ */
+export const UI_PROTOCOL_VERSION = 4;

package/lib/ui/useAsset.d.ts

@@ -0,0 +1,80 @@
+/** What a wrapper tells {@link useAssetUrl} and {@link useAsset} about its surface. */
+export interface AssetScope {
+    /**
+     * Resolve an `asset:`, `shared:` or `blob:` reference to a URL, as the
+     * surface's `getAssetUrl` callback does. Undefined until the host has sent
+     * the surface its asset URLs.
+     */
+    getAssetUrl: ((reference: string) => string) | undefined;
+    /** The surface's locale, which {@link useAsset} looks for a localised copy in. */
+    locale: string | undefined;
+}
+/**
+ * Provided by every surface wrapper. Exported for the test helpers, which
+ * provide it without a host; game code reads it through {@link useAssetUrl}
+ * and {@link useAsset}.
+ */
+export declare const AssetContext: import("react").Context<AssetScope | undefined>;
+/**
+ * The URL an `asset:`, `shared:` or `blob:` reference resolves to, for an
+ * `<img>`, `<video>` or link.
+ *
+ * Undefined until the host has sent the surface its asset URLs, and for an
+ * absent reference, so a component renders a placeholder rather than catching
+ * a throw. A reference without one of the three prefixes still throws, as
+ * `getAssetUrl` does: it is a mistake in the game, not a state to wait out.
+ *
+ * ```tsx
+ * const src = useAssetUrl(settings.storyline.Avatar);
+ * return src ? <img src={src} alt="CEO" /> : null;
+ * ```
+ */
+export declare function useAssetUrl(reference: string | null | undefined): string | undefined;
+/** How {@link useAsset} reads the response body. */
+export type AssetFormat = 'json' | 'text' | 'blob';
+export interface UseAssetOptions<F extends AssetFormat = AssetFormat> {
+    /** `'json'` parses the body, `'text'` returns it as a string, `'blob'` as a `Blob`. */
+    as: F;
+    /**
+     * The locale to look for a localised copy in. Defaults to the surface's
+     * locale; `false` reads the reference as given and nothing else.
+     */
+    locale?: string | false;
+}
+export interface AssetState<T> {
+    /** The asset's contents. Undefined until loaded, and while a new reference loads. */
+    data: T | undefined;
+    /** Why the asset could not be read: no copy was found, or the body did not parse. */
+    error: Error | undefined;
+    loading: boolean;
+}
+/**
+ * The references {@link useAsset} tries, most specific first: the locale as a
+ * directory immediately before the file name, then its language alone, then
+ * the reference as given. `asset:documents/intro.md` in `fr-CA` tries
+ * `asset:documents/fr-CA/intro.md`, `asset:documents/fr/intro.md` and
+ * `asset:documents/intro.md`.
+ *
+ * A `blob:` reference names one uploaded file, so it has no localised copies.
+ */
+export declare function localisedReferences(reference: string, locale: string | false): string[];
+/**
+ * Fetch an asset and read its body, preferring a copy in the surface's locale.
+ *
+ * Looks for the locale's copy first, then its language's, then the reference
+ * as given (see {@link localisedReferences}), so the untranslated file is the
+ * fallback and a translation is added by dropping a file beside it. Waits for
+ * the host's asset URLs rather than throwing, refetches when the reference or
+ * locale changes, and never lets a slower, older request overwrite a newer one.
+ *
+ * ```tsx
+ * const { data: briefing, error, loading } = useAsset<Briefing>('asset:content/briefing.json', {
+ *     as: 'json',
+ * });
+ * ```
+ *
+ * @param reference An `asset:`, `shared:` or `blob:` reference; nothing is fetched while it is absent
+ */
+export declare function useAsset<T = unknown>(reference: string | null | undefined, options: UseAssetOptions<'json'>): AssetState<T>;
+export declare function useAsset(reference: string | null | undefined, options: UseAssetOptions<'text'>): AssetState<string>;
+export declare function useAsset(reference: string | null | undefined, options: UseAssetOptions<'blob'>): AssetState<Blob>;

package/lib/ui/useAsset.js

@@ -0,0 +1,139 @@
+import { createContext, useContext, useEffect, useMemo, useState } from 'react';
+/**
+ * Provided by every surface wrapper. Exported for the test helpers, which
+ * provide it without a host; game code reads it through {@link useAssetUrl}
+ * and {@link useAsset}.
+ */
+export const AssetContext = createContext(undefined);
+function useAssetScope(hookName) {
+    const scope = useContext(AssetContext);
+    if (scope === undefined) {
+        throw new Error(`${hookName} must be used inside a surface wrapper`);
+    }
+    return scope;
+}
+/**
+ * The URL an `asset:`, `shared:` or `blob:` reference resolves to, for an
+ * `<img>`, `<video>` or link.
+ *
+ * Undefined until the host has sent the surface its asset URLs, and for an
+ * absent reference, so a component renders a placeholder rather than catching
+ * a throw. A reference without one of the three prefixes still throws, as
+ * `getAssetUrl` does: it is a mistake in the game, not a state to wait out.
+ *
+ * ```tsx
+ * const src = useAssetUrl(settings.storyline.Avatar);
+ * return src ? <img src={src} alt="CEO" /> : null;
+ * ```
+ */
+export function useAssetUrl(reference) {
+    const { getAssetUrl } = useAssetScope('useAssetUrl');
+    if (!reference || !getAssetUrl)
+        return undefined;
+    return getAssetUrl(reference);
+}
+/**
+ * The references {@link useAsset} tries, most specific first: the locale as a
+ * directory immediately before the file name, then its language alone, then
+ * the reference as given. `asset:documents/intro.md` in `fr-CA` tries
+ * `asset:documents/fr-CA/intro.md`, `asset:documents/fr/intro.md` and
+ * `asset:documents/intro.md`.
+ *
+ * A `blob:` reference names one uploaded file, so it has no localised copies.
+ */
+export function localisedReferences(reference, locale) {
+    if (locale === false || locale === '' || reference.startsWith('blob:'))
+        return [reference];
+    const colon = reference.indexOf(':');
+    if (colon < 0)
+        return [reference];
+    const scheme = reference.slice(0, colon + 1);
+    const path = reference.slice(colon + 1);
+    const slash = path.lastIndexOf('/');
+    const directory = slash < 0 ? '' : path.slice(0, slash + 1);
+    const file = path.slice(slash + 1);
+    const language = locale.split('-')[0];
+    const locales = language && language !== locale ? [locale, language] : [locale];
+    return [...locales.map((each) => `${scheme}${directory}${each}/${file}`), reference];
+}
+async function readBody(response, format) {
+    if (format === 'json')
+        return response.json();
+    if (format === 'text')
+        return response.text();
+    return response.blob();
+}
+export function useAsset(reference, options) {
+    const { getAssetUrl, locale: surfaceLocale } = useAssetScope('useAsset');
+    const format = options.as;
+    const locale = options.locale ?? surfaceLocale ?? false;
+    // Resolved during render and keyed by the URLs themselves, so a resolver
+    // whose identity changes without its prefixes changing fetches nothing.
+    const plan = useMemo(() => {
+        if (!reference || !getAssetUrl)
+            return undefined;
+        try {
+            return { urls: localisedReferences(reference, locale).map(getAssetUrl) };
+        }
+        catch (cause) {
+            return { error: cause instanceof Error ? cause : new Error(String(cause)) };
+        }
+    }, [reference, locale, getAssetUrl]);
+    const key = plan === undefined ? '' : 'urls' in plan ? `${format}\n${plan.urls.join('\n')}` : '';
+    const [loaded, setLoaded] = useState(undefined);
+    useEffect(() => {
+        if (key === '')
+            return;
+        const [, ...urls] = key.split('\n');
+        const controller = new AbortController();
+        void (async () => {
+            let failure;
+            for (const url of urls) {
+                let response;
+                try {
+                    response = await fetch(url, {
+                        credentials: 'include',
+                        signal: controller.signal,
+                    });
+                }
+                catch (cause) {
+                    if (controller.signal.aborted)
+                        return;
+                    failure = cause instanceof Error ? cause : new Error(String(cause));
+                    continue;
+                }
+                if (!response.ok) {
+                    failure = new Error(`Failed to fetch asset (${response.status})`);
+                    continue;
+                }
+                try {
+                    const data = await readBody(response, format);
+                    if (!controller.signal.aborted)
+                        setLoaded({ key, data, error: undefined });
+                }
+                catch (cause) {
+                    if (controller.signal.aborted)
+                        return;
+                    const error = cause instanceof Error ? cause : new Error(String(cause));
+                    setLoaded({ key, data: undefined, error });
+                }
+                return;
+            }
+            if (!controller.signal.aborted) {
+                setLoaded({ key, data: undefined, error: failure ?? new Error('Asset not found') });
+            }
+        })();
+        return () => controller.abort();
+        // `format` is part of `key`.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [key]);
+    if (plan !== undefined && 'error' in plan) {
+        return { data: undefined, error: plan.error, loading: false };
+    }
+    if (!reference)
+        return { data: undefined, error: undefined, loading: false };
+    if (key === '' || loaded?.key !== key) {
+        return { data: undefined, error: undefined, loading: true };
+    }
+    return { data: loaded.data, error: loaded.error, loading: false };
+}

package/lib/ui/useEndpointCallbacks.d.ts

@@ -0,0 +1,31 @@
+import { type EndpointFailure } from '../build/endpoints.js';
+/**
+ * Returned by {@link useEndpointCallbacks} — a proxy-backed map where any
+ * property access resolves to an async function that posts a `callEndpoint`
+ * message over the supplied port. Designed to mirror the typed `Endpoints`
+ * interface emitted by per-UI generated `types.ts`. A failed call rejects with
+ * an {@link EndpointError}.
+ */
+export type EndpointCallable = (request: unknown) => Promise<unknown>;
+export type EndpointCallbacksMap = Record<string, EndpointCallable>;
+/**
+ * Build the host ↔ iframe endpoint plumbing shared across UI wrappers.
+ *
+ * Exposes:
+ * - `endpoints` — proxy-backed map used as `callbacks.endpoints[id](request)`.
+ * - `handleEndpointResponse(msg)` — call from the wrapper's port `onmessage`
+ *   for `callEndpoint:response` payloads.
+ * - `resetPending()` — drop all in-flight calls on connection reset.
+ */
+export declare function useEndpointCallbacks(getPort: () => MessagePort | null): {
+    endpoints: EndpointCallbacksMap;
+    handleEndpointResponse: (msg: {
+        requestId: string;
+        ok: true;
+        response: unknown;
+    } | ({
+        requestId: string;
+        ok: false;
+    } & EndpointFailure)) => void;
+    resetPending: () => void;
+};

package/lib/ui/useEndpointCallbacks.js

@@ -0,0 +1,68 @@
+import { useCallback, useMemo, useRef } from 'react';
+import { EndpointError } from '../build/endpoints.js';
+import { newRequestId } from './request-id.js';
+/** A failure the host never answered, so it reported nothing applied. */
+function unreached(message) {
+    return new EndpointError({ outcome: { kind: 'error', message }, applied: [] });
+}
+/**
+ * Build the host ↔ iframe endpoint plumbing shared across UI wrappers.
+ *
+ * Exposes:
+ * - `endpoints` — proxy-backed map used as `callbacks.endpoints[id](request)`.
+ * - `handleEndpointResponse(msg)` — call from the wrapper's port `onmessage`
+ *   for `callEndpoint:response` payloads.
+ * - `resetPending()` — drop all in-flight calls on connection reset.
+ */
+export function useEndpointCallbacks(getPort) {
+    const pendingRef = useRef(new Map());
+    const callEndpoint = useCallback((endpointIdentifier, request) => {
+        const port = getPort();
+        if (!port) {
+            return Promise.reject(unreached('Not connected to host'));
+        }
+        return new Promise((resolve, reject) => {
+            const requestId = newRequestId();
+            pendingRef.current.set(requestId, { resolve, reject });
+            port.postMessage({
+                type: 'callEndpoint',
+                requestId,
+                endpointIdentifier,
+                request,
+            });
+        });
+    }, [getPort]);
+    const endpoints = useMemo(() => new Proxy({}, {
+        get: (_target, prop) => {
+            if (typeof prop !== 'string')
+                return undefined;
+            return (request) => callEndpoint(prop, request);
+        },
+    }), [callEndpoint]);
+    const handleEndpointResponse = useCallback((msg) => {
+        const pending = pendingRef.current.get(msg.requestId);
+        if (!pending)
+            return;
+        if (msg.ok) {
+            pending.resolve(msg.response);
+        }
+        else {
+            pending.reject(new EndpointError({
+                outcome: msg.outcome ?? {
+                    kind: 'error',
+                    message: 'The endpoint call failed',
+                },
+                applied: msg.applied ?? [],
+                ...(msg.failedStep ? { failedStep: msg.failedStep } : {}),
+            }));
+        }
+        pendingRef.current.delete(msg.requestId);
+    }, []);
+    const resetPending = useCallback(() => {
+        // Whether the host applied anything before the connection went is
+        // unknown here: `applied` lists what the host reported, which is none.
+        pendingRef.current.forEach(({ reject }) => reject(unreached('Connection reset')));
+        pendingRef.current.clear();
+    }, []);
+    return { endpoints, handleEndpointResponse, resetPending };
+}

package/lib/ui/useHostChannel.d.ts

@@ -0,0 +1,90 @@
+import { PastStateEntry, PastStateQuery, ReadAssetResponse, ThemePreference, Participant } from '../build/callbacks.js';
+import type { MutationCommit } from './mutation-commit.js';
+import { type AssetUrls } from './ui-protocol.js';
+import { type EndpointCallbacksMap } from './useEndpointCallbacks.js';
+/** Helpers passed to a wrapper's per-message handler. */
+export interface HostChannelHelpers {
+    /** Record that a required message has arrived (drives `isInitialized`). */
+    markReceived: (type: string) => void;
+    /** Post a raw message back to the host over the active port. */
+    postMessage: (message: unknown) => void;
+}
+export interface UseHostChannelOptions<THostMessage extends {
+    type: string;
+}> {
+    /** Window the iframe posts its `ready` handshake to (usually `window.parent`). */
+    targetWindow: Window;
+    /** Console label for handshake logging. */
+    label: string;
+    /** Message types that must all arrive before `isInitialized` becomes true. */
+    requiredMessages: readonly string[];
+    /**
+     * Handle a channel-specific host message (everything the hook does not own:
+     * `stateChanged`, `setSettings`, `setTheme`, `setLocale`,
+     * `validationRejected`, …). Call `helpers.markReceived(type)` for required
+     * messages.
+     */
+    onMessage?: (message: THostMessage, helpers: HostChannelHelpers) => void;
+    /** Called on every (re)connection, before the new port is wired. */
+    onReset?: () => void;
+}
+export interface UseHostChannelReturn<TIFrameMessage> {
+    expectedParentOrigin: string | null;
+    isInitialized: boolean;
+    /**
+     * The opaque key the host named this run by on `init` (§12.2), for
+     * namespacing the surface's own storage. Undefined until the handshake
+     * completes, and on a host that sends none.
+     */
+    sessionKey: string | undefined;
+    /** Post a typed iframe→host message over the active port. */
+    postMessage: (message: TIFrameMessage) => void;
+    /**
+     * Post a fallible mutation and await its commit. Resolves once the host
+     * confirms the write/operation; rejects with a {@link MutationError}.
+     */
+    sendMutation: (message: TIFrameMessage) => Promise<void>;
+    /**
+     * As {@link sendMutation}, but resolving with what the host reported about
+     * the commit. Only the context write needs it: a write carries the tick it
+     * was composed against, and the answer says which tick it landed in (§9.5).
+     */
+    sendMutationReportingCommit: (message: TIFrameMessage) => Promise<MutationCommit>;
+    themePreference: ThemePreference;
+    setThemePreference: (preference: ThemePreference) => void;
+    uploadBlob: (file: File) => Promise<string>;
+    readAsset: (reference: string) => Promise<ReadAssetResponse>;
+    /**
+     * Read committed past state. Untyped here: the channel does not know
+     * the game's `Context`, so each wrapper re-exposes it generically.
+     *
+     * The host resolves the query, including which teams `own` means for
+     * the surface, so one signature serves the participant and session
+     * channels alike.
+     */
+    getPastState: (query: PastStateQuery<Record<string, unknown>>) => Promise<PastStateEntry<Record<string, unknown>>[]>;
+    /**
+     * Read the current participant roster of every team. Resolves with one flat
+     * entry per participant across all teams (each tagged with its `teamId`);
+     * rejects on a transport/host fault. A point-in-time snapshot, not a live
+     * subscription. Available on the participant channel only.
+     */
+    getAllTeamsParticipants: () => Promise<Participant[]>;
+    getAssetUrl: (reference: string) => string;
+    assetUrls: AssetUrls | undefined;
+    endpoints: EndpointCallbacksMap;
+}
+/**
+ * Iframe-side counterpart to the host's `useIframeChannel`. Owns the half of the
+ * host↔iframe protocol every UI wrapper shares: the two-phase handshake, port
+ * lifecycle and HMR reset, the per-callback pending-promise maps (blob upload,
+ * endpoints, tick snapshots), asset-URL resolution and `refreshAssetAuth`,
+ * theme-preference relay, and required-message gating.
+ *
+ * Each wrapper supplies its `requiredMessages` and an `onMessage` handler for the
+ * channel-specific messages (`stateChanged`/`setSettings`/`setTheme`/…) and keeps its
+ * own state and context providers.
+ */
+export declare function useHostChannel<THostMessage extends {
+    type: string;
+}, TIFrameMessage>(options: UseHostChannelOptions<THostMessage>): UseHostChannelReturn<TIFrameMessage>;