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

package/lib/ui/SessionUserInterfaceWalkthroughLinkContext.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Where to open the walkthrough run (§5.7).
+ *
+ * Facilitator-only, like {@link ./SessionUserInterfaceTeamLinksContext.TeamLinks},
+ * and unlike them it names no team: a walkthrough holds exactly one, so there
+ * is nothing to choose. The host sends it to the session surface and to nothing
+ * else.
+ */
+export type WalkthroughLink = {
+    /**
+     * The URL to open, which mounts the walkthrough's player surface.
+     *
+     * Open it in a new tab or window rather than in the session surface's own
+     * canvas: a facilitator demonstrating puts this on a projector while
+     * keeping the session in front of them.
+     */
+    url: string;
+};
+export declare const SessionUserInterfaceWalkthroughLinkContext: import("react").Context<WalkthroughLink | null>;
+/**
+ * Hook returning where to open the walkthrough, or `null` until the host has
+ * said.
+ *
+ * Every host offers a walkthrough (§5.7), so the link always arrives; `null` is
+ * only the moment before it does. Gate the control on the link, so a surface
+ * never shows a button with nowhere to go.
+ *
+ * ```tsx
+ * const walkthrough = useSessionUserInterfaceWalkthroughLink();
+ * const { resetWalkthrough } = useSessionUserInterfaceCallbacks();
+ *
+ * {walkthrough && (
+ *     <>
+ *         <Button href={walkthrough.url} target="_blank" rel="noreferrer">Walkthrough</Button>
+ *         <Button onClick={() => void resetWalkthrough()}>Reset it</Button>
+ *     </>
+ * )}
+ * ```
+ *
+ * @returns Where to open the walkthrough, or `null` before the host has said
+ */
+export declare const useSessionUserInterfaceWalkthroughLink: () => WalkthroughLink | null;

package/lib/ui/SessionUserInterfaceWalkthroughLinkContext.js

@@ -0,0 +1,26 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext(null);
+export const SessionUserInterfaceWalkthroughLinkContext = Context;
+/**
+ * Hook returning where to open the walkthrough, or `null` until the host has
+ * said.
+ *
+ * Every host offers a walkthrough (§5.7), so the link always arrives; `null` is
+ * only the moment before it does. Gate the control on the link, so a surface
+ * never shows a button with nowhere to go.
+ *
+ * ```tsx
+ * const walkthrough = useSessionUserInterfaceWalkthroughLink();
+ * const { resetWalkthrough } = useSessionUserInterfaceCallbacks();
+ *
+ * {walkthrough && (
+ *     <>
+ *         <Button href={walkthrough.url} target="_blank" rel="noreferrer">Walkthrough</Button>
+ *         <Button onClick={() => void resetWalkthrough()}>Reset it</Button>
+ *     </>
+ * )}
+ * ```
+ *
+ * @returns Where to open the walkthrough, or `null` before the host has said
+ */
+export const useSessionUserInterfaceWalkthroughLink = useValue;

package/lib/ui/SessionUserInterfaceWrapper.d.ts

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react';
+interface SessionUserInterfaceWrapperProps {
+    children?: ReactNode;
+    fallback?: ReactNode;
+    targetWindow?: Window;
+}
+declare function SessionUserInterfaceWrapper({ children, fallback, targetWindow, }: SessionUserInterfaceWrapperProps): import("react").JSX.Element;
+export default SessionUserInterfaceWrapper;

package/lib/ui/SessionUserInterfaceWrapper.js

@@ -0,0 +1,321 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { applyContextUpdate } from '../build/context-merge.js';
+import { useDocumentAttributes } from './internal/document-attributes.js';
+import { DEFAULT_SURFACE_TIMER } from './internal/surface-timer.js';
+import { SurfaceGate } from './internal/SurfaceGate.js';
+import { SurfaceScope } from './internal/SurfaceScope.js';
+import { useLatestRef } from './internal/useLatestRef.js';
+import { useSurfaceControls } from './internal/useSurfaceControls.js';
+import { useTypedPastState } from './internal/useTypedPastState.js';
+import { SessionUserInterfaceCallbacksContext } from './SessionUserInterfaceCallbacksContext.js';
+import { SessionUserInterfaceDataContext, } from './SessionUserInterfaceDataContext.js';
+import { SessionUserInterfaceHookFailuresContext, } from './SessionUserInterfaceHookFailuresContext.js';
+import { SessionUserInterfaceHostOverlaysContext, } from './SessionUserInterfaceHostOverlaysContext.js';
+import { SessionUserInterfaceLocaleContext, } from './SessionUserInterfaceLocaleContext.js';
+import { SessionUserInterfaceMetaContext, } from './SessionUserInterfaceMetaContext.js';
+import { SessionUserInterfaceParticipantsContext } from './SessionUserInterfaceParticipantsContext.js';
+import { DEFAULT_TEAM_CONFIGURATION, SessionUserInterfaceTeamConfigurationContext, } from './SessionUserInterfaceTeamConfigurationContext.js';
+import { SessionUserInterfaceTeamLinksContext, } from './SessionUserInterfaceTeamLinksContext.js';
+import { SessionUserInterfaceTeamsContext, } from './SessionUserInterfaceTeamsContext.js';
+import { SessionUserInterfaceThemeContext, } from './SessionUserInterfaceThemeContext.js';
+import { SessionUserInterfaceThemePreferenceContext } from './SessionUserInterfaceThemePreferenceContext.js';
+import { SessionUserInterfaceWalkthroughLinkContext, } from './SessionUserInterfaceWalkthroughLinkContext.js';
+import { useHostChannel } from './useHostChannel.js';
+import { UserInterfaceRunKindContext } from './UserInterfaceRunKindContext.js';
+/**
+ * Teams, participants and join links are pushed but do not gate first paint: a
+ * surface can render its frame around an empty roster, and holding the whole
+ * canvas back for a join link nobody has scanned yet is worse than a
+ * placeholder.
+ *
+ * `setTeamConfiguration` is the exception among the pushed values, because its
+ * default cannot be rendered honestly. A surface that paints before bounds
+ * arrive holds `max: 0`, and the obvious `teams.length < max` check then reads
+ * as 'this session is full' and disables the control it guards (#365). There is
+ * no placeholder for a bound, so the surface waits for the real one.
+ */
+const REQUIRED_MESSAGES = [
+    'setSessionMeta',
+    'setSessionData',
+    'setSettings',
+    'setTheme',
+    'setLocale',
+    'setAssetUrls',
+    'setTeamConfiguration',
+];
+/**
+ * Merge one team's delivered state into the session view.
+ *
+ * The revision decides what happens, and the three cases are all reachable in
+ * practice:
+ *
+ * - **In sequence** (exactly one ahead of what is held, and a first delivery
+ *   for a team added mid-session counts): apply it.
+ * - **Behind or equal**: a redelivery, or a delta that raced the snapshot that
+ *   already superseded it. Ignore it. Applying it would move the surface
+ *   backwards, which is worse than doing nothing.
+ * - **Ahead by more than one**: an update was lost. The held state for that
+ *   team is now unreliable and cannot be repaired from a delta, so the caller
+ *   asks the host for a fresh snapshot.
+ *
+ * Returning `null` for the gap case keeps the decision here, where the rule is
+ * written down, rather than splitting it between this function and its caller.
+ */
+function mergeTeamState(previous, teamId, state) {
+    const held = previous.teams[teamId]?.revision ?? 0;
+    if (state.revision <= held)
+        return previous;
+    if (state.revision > held + 1)
+        return null;
+    return { ...previous, teams: { ...previous.teams, [teamId]: state } };
+}
+/** {@link mergeTeamState} for the shared store, by the same three cases. */
+function mergeSharedState(previous, state) {
+    const held = previous.shared.revision;
+    if (state.revision <= held)
+        return previous;
+    if (state.revision > held + 1)
+        return null;
+    return { ...previous, shared: state };
+}
+/** An empty `deletes` is left off the wire, as a player surface leaves it off. */
+function deletesField(deletes) {
+    return deletes?.length ? { deletes } : {};
+}
+const EMPTY_SESSION_DATA = { shared: { context: {}, revision: 0 }, teams: {} };
+function SessionUserInterfaceWrapper({ children, fallback = _jsx("div", { children: "Loading..." }), targetWindow = window.parent, }) {
+    const [sessionData, setSessionDataState] = useState(EMPTY_SESSION_DATA);
+    const [settings, setSettingsState] = useState(undefined);
+    const [theme, setThemeState] = useState(undefined);
+    const [locale, setLocaleState] = useState(undefined);
+    const [participants, setParticipantsState] = useState([]);
+    const [teams, setTeamsState] = useState([]);
+    const [sessionMeta, setSessionMetaState] = useState(undefined);
+    const [teamLinks, setTeamLinksState] = useState([]);
+    // Fixed for the life of the run; 'session' is by far the common answer,
+    // so it never gates first paint.
+    const [runKind, setRunKindState] = useState('session');
+    // null until the host answers: a surface gates its control on this.
+    const [walkthroughLink, setWalkthroughLinkState] = useState(null);
+    const [hookFailures, setHookFailures] = useState([]);
+    const [teamConfiguration, setTeamConfigurationState] = useState(DEFAULT_TEAM_CONFIGURATION);
+    // Empty is the honest default and also the right answer for a host that
+    // delegates none, so this does not gate first paint.
+    const [hostOverlays, setHostOverlaysState] = useState([]);
+    /**
+     * Whether a `resyncSessionData` is outstanding. A gap usually means several
+     * deltas were lost, so without this one lost update would send a request
+     * per subsequent delta until the snapshot landed. Cleared by the snapshot
+     * arriving, which is the only thing that resolves the gap.
+     */
+    const resyncPendingRef = useRef(false);
+    const { isInitialized, expectedParentOrigin, postMessage, sendMutation, uploadBlob, readAsset, getPastState: getPastStateRaw, getAssetUrl, assetUrls, setThemePreference, endpoints, themePreference, sessionKey, } = useHostChannel({
+        targetWindow,
+        label: 'SessionUserInterfaceWrapper',
+        requiredMessages: REQUIRED_MESSAGES,
+        onMessage: (msg, { markReceived }) => {
+            if (msg.type === 'setSessionData') {
+                setSessionDataState({
+                    shared: msg.payload?.shared ?? EMPTY_SESSION_DATA.shared,
+                    teams: msg.payload?.teams ?? {},
+                });
+                // A snapshot is by definition current, so any resync it was
+                // sent in answer to is now settled.
+                resyncPendingRef.current = false;
+                markReceived('setSessionData');
+            }
+            else if (msg.type === 'updateTeamState') {
+                const merged = mergeTeamState(sessionDataRef.current, msg.teamId, msg.state);
+                if (merged === null) {
+                    requestResync();
+                    return;
+                }
+                sessionDataRef.current = merged;
+                setSessionDataState(merged);
+            }
+            else if (msg.type === 'updateSharedState') {
+                const merged = mergeSharedState(sessionDataRef.current, msg.state);
+                if (merged === null) {
+                    requestResync();
+                    return;
+                }
+                sessionDataRef.current = merged;
+                setSessionDataState(merged);
+            }
+            else if (msg.type === 'setSessionMeta') {
+                setSessionMetaState(msg.payload);
+                markReceived('setSessionMeta');
+            }
+            else if (msg.type === 'setSettings') {
+                setSettingsState(msg.payload);
+                markReceived('setSettings');
+            }
+            else if (msg.type === 'setTheme') {
+                setThemeState(msg.payload);
+                markReceived('setTheme');
+            }
+            else if (msg.type === 'setLocale') {
+                setLocaleState(msg.payload);
+                markReceived('setLocale');
+            }
+            else if (msg.type === 'setTeamList') {
+                setTeamsState(msg.payload);
+            }
+            else if (msg.type === 'setTeamConfiguration') {
+                setTeamConfigurationState(msg.payload);
+                markReceived('setTeamConfiguration');
+            }
+            else if (msg.type === 'setRunKind') {
+                setRunKindState(msg.runKind);
+            }
+            else if (msg.type === 'setWalkthroughLink') {
+                setWalkthroughLinkState(msg.payload);
+            }
+            else if (msg.type === 'setTeamLinks') {
+                setTeamLinksState(msg.payload);
+            }
+            else if (msg.type === 'setAvailableOverlays') {
+                setHostOverlaysState(msg.overlays);
+            }
+            else if (msg.type === 'hookFailed') {
+                // Accumulate: a facilitator who looked away should still find
+                // out that something went wrong.
+                setHookFailures((prev) => [...prev, msg.payload]);
+            }
+            else if (msg.type === 'setParticipantList') {
+                setParticipantsState(msg.participants);
+            }
+        },
+    });
+    // Mirror the latest optimistic session data so setData can merge
+    // synchronously and return a correctly-correlated promise (a state updater
+    // would run too late to capture the sendMutation promise). The delta
+    // handler reads it too, so two updates arriving before a re-render each
+    // merge onto the previous one rather than onto stale state.
+    const sessionDataRef = useLatestRef(sessionData);
+    /**
+     * Ask the host for a fresh full snapshot after a per-team revision arrived
+     * out of sequence. The surface keeps rendering what it holds meanwhile: one
+     * team's state being a beat stale is better than blanking a facilitator's
+     * screen, and the snapshot repairs it either way.
+     */
+    const requestResync = useCallback(() => {
+        if (resyncPendingRef.current)
+            return;
+        resyncPendingRef.current = true;
+        postMessage({ type: 'resyncSessionData' });
+    }, [postMessage]);
+    const setData = useCallback((teamIdOrUpdate, updateOrOptions, maybeOptions) => {
+        const prev = sessionDataRef.current;
+        if (typeof teamIdOrUpdate !== 'string') {
+            // Shared write: one value for the session, so it merges into
+            // the shared store the surface holds once.
+            const update = teamIdOrUpdate;
+            const deletes = updateOrOptions?.deletes;
+            const next = {
+                ...prev,
+                shared: {
+                    ...prev.shared,
+                    context: applyContextUpdate(prev.shared.context, update, deletes),
+                },
+            };
+            sessionDataRef.current = next;
+            setSessionDataState(next);
+            return sendMutation({
+                type: 'updateSharedData',
+                payload: update,
+                ...deletesField(deletes),
+            });
+        }
+        const teamId = teamIdOrUpdate;
+        const update = updateOrOptions ?? {};
+        const deletes = maybeOptions?.deletes;
+        const teamState = prev.teams[teamId] ?? {
+            context: {},
+            completedTicks: 0,
+            timer: DEFAULT_SURFACE_TIMER,
+            revision: 0,
+        };
+        const mergedContext = applyContextUpdate(teamState.context, update, deletes);
+        const next = {
+            ...prev,
+            teams: {
+                ...prev.teams,
+                [teamId]: { ...teamState, context: mergedContext },
+            },
+        };
+        sessionDataRef.current = next;
+        setSessionDataState(next);
+        return sendMutation({
+            type: 'updateSessionData',
+            teamId,
+            payload: update,
+            ...deletesField(deletes),
+        });
+    }, [sendMutation]);
+    const requestTick = useCallback((teamId) => sendMutation({ type: 'requestTick', teamId }), [sendMutation]);
+    const getPastState = useTypedPastState(getPastStateRaw);
+    useDocumentAttributes(locale?.locale, theme?.mode);
+    const { pauseTimer, resumeTimer, resetGame, undoTick, extendTick, openHostOverlay } = useSurfaceControls({ sendMutation });
+    // Session-wide, so it is not part of useSurfaceControls, whose messages all
+    // carry an optional teamId.
+    const setWaitingRoom = useCallback((open) => sendMutation({ type: 'setWaitingRoom', open }), [sendMutation]);
+    const resetWalkthrough = useCallback(() => sendMutation({ type: 'resetWalkthrough' }), [sendMutation]);
+    const createTeam = useCallback((name) => sendMutation({ type: 'createTeam', name }), [sendMutation]);
+    const renameTeam = useCallback((teamId, name) => sendMutation({ type: 'renameTeam', teamId, name }), [sendMutation]);
+    const renameParticipant = useCallback((participantId, name) => sendMutation({ type: 'renameParticipant', participantId, name }), [sendMutation]);
+    const moveParticipant = useCallback((participantId, teamId) => sendMutation({ type: 'moveParticipant', participantId, teamId }), [sendMutation]);
+    const deleteTeam = useCallback((teamId) => sendMutation({ type: 'deleteTeam', teamId }), [sendMutation]);
+    const hookFailuresValue = useMemo(() => ({ failures: hookFailures, clearFailures: () => setHookFailures([]) }), [hookFailures]);
+    const dataContextValue = useMemo(() => ({ sessionData, settings, setData }), [sessionData, settings, setData]);
+    const callbacksContextValue = useMemo(() => ({
+        requestTick,
+        uploadBlob,
+        getAssetUrl,
+        readAsset,
+        getPastState,
+        setThemePreference,
+        pauseTimer,
+        resumeTimer,
+        resetGame,
+        undoTick,
+        extendTick,
+        openHostOverlay,
+        setWaitingRoom,
+        resetWalkthrough,
+        createTeam,
+        renameTeam,
+        renameParticipant,
+        moveParticipant,
+        deleteTeam,
+        endpoints,
+    }), [
+        requestTick,
+        uploadBlob,
+        getAssetUrl,
+        readAsset,
+        getPastState,
+        setThemePreference,
+        pauseTimer,
+        resumeTimer,
+        resetGame,
+        undoTick,
+        extendTick,
+        openHostOverlay,
+        setWaitingRoom,
+        resetWalkthrough,
+        createTeam,
+        renameTeam,
+        renameParticipant,
+        moveParticipant,
+        deleteTeam,
+        endpoints,
+    ]);
+    const storageScope = useMemo(() => ({ sessionKey, surface: 'session', viewer: 'facilitator' }), [sessionKey]);
+    return (_jsx(SurfaceGate, { expectedParentOrigin: expectedParentOrigin, ready: isInitialized &&
+            theme !== undefined &&
+            locale !== undefined &&
+            sessionMeta !== undefined, fallback: fallback, children: _jsx(SurfaceScope, { storage: storageScope, assetUrls: assetUrls, getAssetUrl: getAssetUrl, locale: locale?.locale, getPastState: getPastState, children: _jsx(SessionUserInterfaceDataContext.Provider, { value: dataContextValue, children: _jsx(SessionUserInterfaceThemeContext.Provider, { value: theme, children: _jsx(SessionUserInterfaceThemePreferenceContext.Provider, { value: themePreference, children: _jsx(SessionUserInterfaceLocaleContext.Provider, { value: locale, children: _jsx(SessionUserInterfaceMetaContext.Provider, { value: sessionMeta, children: _jsx(SessionUserInterfaceTeamsContext.Provider, { value: teams, children: _jsx(SessionUserInterfaceTeamConfigurationContext.Provider, { value: teamConfiguration, children: _jsx(UserInterfaceRunKindContext.Provider, { value: runKind, children: _jsx(SessionUserInterfaceWalkthroughLinkContext.Provider, { value: walkthroughLink, children: _jsx(SessionUserInterfaceTeamLinksContext.Provider, { value: teamLinks, children: _jsx(SessionUserInterfaceHostOverlaysContext.Provider, { value: hostOverlays, children: _jsx(SessionUserInterfaceParticipantsContext.Provider, { value: participants, children: _jsx(SessionUserInterfaceCallbacksContext.Provider, { value: callbacksContextValue, children: _jsx(SessionUserInterfaceHookFailuresContext.Provider, { value: hookFailuresValue, children: children }) }) }) }) }) }) }) }) }) }) }) }) }) }) }) }));
+}
+export default SessionUserInterfaceWrapper;

package/lib/ui/SettingsEditorCallbacksContext.d.ts

@@ -0,0 +1,3 @@
+import type { SettingsEditorCallbacks } from '../build/callbacks.js';
+export declare const SettingsEditorCallbacksContext: import("react").Context<SettingsEditorCallbacks | undefined>;
+export declare const useSettingsEditorCallbacks: () => SettingsEditorCallbacks;

package/lib/ui/SettingsEditorCallbacksContext.js

@@ -0,0 +1,7 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSettingsEditorCallbacks',
+    wrapperName: 'SettingsEditorWrapper',
+});
+export const SettingsEditorCallbacksContext = Context;
+export const useSettingsEditorCallbacks = useValue;

package/lib/ui/SettingsEditorContext.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a settings editor edits: the `setup` slot and the `scenario_editor`
+ * slot share it (§6.5).
+ */
+export type SettingsEditorValue<T> = {
+    /**
+     * The resolved values of the settings this editor `configures`, keyed by
+     * settings identifier, with any edits made so far merged in.
+     */
+    settings: T;
+    /**
+     * Merge an update into the settings. Only what changed reaches the host
+     * (§8.2). Resolves once the host confirms the write; rejects with a
+     * `MutationError` when it is refused (settings validation, say) or fails.
+     *
+     * Await it: a screen that drops a refusal leaves the facilitator believing
+     * a setting took when it did not, and they will not find out until the
+     * session runs. `useMutationReporter` does the awaiting and hands you the
+     * failure to render.
+     */
+    updateSettings: (update: Partial<T>) => Promise<void>;
+    /** Identifiers of the settings resources this editor edits. */
+    configures: string[];
+};
+declare const SettingsEditorContext: import("react").Context<SettingsEditorValue<unknown> | undefined>;
+/**
+ * The settings a `setup` or `scenario_editor` slot edits, and the way to
+ * change them. Pass the generated `Settings` type from the slot's `types.ts`.
+ *
+ * @throws Error if used outside SettingsEditorWrapper
+ */
+declare function useSettingsEditor<T>(): SettingsEditorValue<T>;
+export { useSettingsEditor, SettingsEditorContext };

package/lib/ui/SettingsEditorContext.js

@@ -0,0 +1,16 @@
+import { createContext, useContext } from 'react';
+const SettingsEditorContext = createContext(undefined);
+/**
+ * The settings a `setup` or `scenario_editor` slot edits, and the way to
+ * change them. Pass the generated `Settings` type from the slot's `types.ts`.
+ *
+ * @throws Error if used outside SettingsEditorWrapper
+ */
+function useSettingsEditor() {
+    const ctx = useContext(SettingsEditorContext);
+    if (!ctx) {
+        throw new Error('useSettingsEditor must be used inside a SettingsEditorWrapper');
+    }
+    return ctx;
+}
+export { useSettingsEditor, SettingsEditorContext };

package/lib/ui/SettingsEditorLocaleContext.d.ts

@@ -0,0 +1,13 @@
+export type SettingsEditorLocale = {
+    locale: string;
+};
+export declare const SettingsEditorLocaleContext: import("react").Context<SettingsEditorLocale | undefined>;
+/**
+ * Hook to access the current locale in a settings editor (the `setup` or
+ * `scenario_editor` slot). The host picks it from the game's supported
+ * locales.
+ *
+ * @returns Current locale object with locale string
+ * @throws Error if used outside SettingsEditorWrapper
+ */
+export declare const useSettingsEditorLocale: () => SettingsEditorLocale;

package/lib/ui/SettingsEditorLocaleContext.js

@@ -0,0 +1,15 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSettingsEditorLocale',
+    wrapperName: 'SettingsEditorWrapper',
+});
+export const SettingsEditorLocaleContext = Context;
+/**
+ * Hook to access the current locale in a settings editor (the `setup` or
+ * `scenario_editor` slot). The host picks it from the game's supported
+ * locales.
+ *
+ * @returns Current locale object with locale string
+ * @throws Error if used outside SettingsEditorWrapper
+ */
+export const useSettingsEditorLocale = useValue;

package/lib/ui/SettingsEditorThemeContext.d.ts

@@ -0,0 +1,9 @@
+import { type SurfaceModeColors } from './internal/createContexts.js';
+export type SettingsEditorModeColors = SurfaceModeColors;
+export type SettingsEditorTheme = {
+    mode: 'dark' | 'light';
+    dark: SettingsEditorModeColors;
+    light: SettingsEditorModeColors;
+};
+export declare const SettingsEditorThemeContext: import("react").Context<SettingsEditorTheme | undefined>;
+export declare const useSettingsEditorTheme: () => SettingsEditorTheme;

package/lib/ui/SettingsEditorThemeContext.js

@@ -0,0 +1,7 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSettingsEditorTheme',
+    wrapperName: 'SettingsEditorWrapper',
+});
+export const SettingsEditorThemeContext = Context;
+export const useSettingsEditorTheme = useValue;

package/lib/ui/SettingsEditorThemePreferenceContext.d.ts

@@ -0,0 +1,3 @@
+import type { ThemePreference } from '../build/callbacks.js';
+export declare const SettingsEditorThemePreferenceContext: import("react").Context<ThemePreference | undefined>;
+export declare const useSettingsEditorThemePreference: () => ThemePreference;

package/lib/ui/SettingsEditorThemePreferenceContext.js

@@ -0,0 +1,7 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSettingsEditorThemePreference',
+    wrapperName: 'SettingsEditorWrapper',
+});
+export const SettingsEditorThemePreferenceContext = Context;
+export const useSettingsEditorThemePreference = useValue;

package/lib/ui/SettingsEditorWrapper.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+interface SettingsEditorWrapperProps {
+    children?: ReactNode;
+    fallback?: ReactNode;
+    targetWindow?: Window;
+}
+/**
+ * The wrapper for both settings editors, the `setup` slot and the
+ * `scenario_editor` slot (§6.5). Each slot is its own bundle, so a screen
+ * knows which it is without being told: the host sends the same batch to both.
+ */
+declare function SettingsEditorWrapper({ children, fallback, targetWindow, }: SettingsEditorWrapperProps): import("react").JSX.Element;
+export default SettingsEditorWrapper;

package/lib/ui/SettingsEditorWrapper.js

@@ -0,0 +1,74 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { changedFrom, deepMergeContext } from '../build/context-merge.js';
+import { useDocumentAttributes } from './internal/document-attributes.js';
+import { SurfaceGate } from './internal/SurfaceGate.js';
+import { SurfaceScope } from './internal/SurfaceScope.js';
+import { SettingsEditorCallbacksContext } from './SettingsEditorCallbacksContext.js';
+import { SettingsEditorContext } from './SettingsEditorContext.js';
+import { SettingsEditorLocaleContext, } from './SettingsEditorLocaleContext.js';
+import { SettingsEditorThemeContext } from './SettingsEditorThemeContext.js';
+import { SettingsEditorThemePreferenceContext } from './SettingsEditorThemePreferenceContext.js';
+import { useHostChannel } from './useHostChannel.js';
+const REQUIRED_MESSAGES = ['setSettings', 'setTheme', 'setLocale', 'setAssetUrls'];
+/**
+ * The wrapper for both settings editors, the `setup` slot and the
+ * `scenario_editor` slot (§6.5). Each slot is its own bundle, so a screen
+ * knows which it is without being told: the host sends the same batch to both.
+ */
+function SettingsEditorWrapper({ children, fallback = _jsx("div", { children: "Loading..." }), targetWindow = window.parent, }) {
+    const [settings, setSettingsState] = useState(undefined);
+    const [configures, setConfigures] = useState([]);
+    const [theme, setThemeState] = useState(undefined);
+    const [locale, setLocaleState] = useState(undefined);
+    const { isInitialized, expectedParentOrigin, postMessage, sendMutation, uploadBlob, readAsset, getAssetUrl, assetUrls, setThemePreference, endpoints, themePreference, sessionKey, } = useHostChannel({
+        targetWindow,
+        label: 'SettingsEditorWrapper',
+        requiredMessages: REQUIRED_MESSAGES,
+        onMessage: (msg, { markReceived }) => {
+            if (msg.type === 'setSettings') {
+                setSettingsState(msg.payload);
+                // `setSettings` carries exactly what this editor configures
+                // (§8.3), so its keys are the list: there is no second message
+                // to drift from it.
+                setConfigures(Object.keys(msg.payload));
+                markReceived('setSettings');
+            }
+            else if (msg.type === 'setTheme') {
+                setThemeState(msg.payload);
+                markReceived('setTheme');
+            }
+            else if (msg.type === 'setLocale') {
+                setLocaleState(msg.payload);
+                markReceived('setLocale');
+            }
+        },
+    });
+    // Mirror the latest optimistic settings so updateSettings can merge
+    // synchronously and return a correctly-correlated promise (a state updater
+    // would run too late to capture the sendMutation promise).
+    const settingsRef = useRef(undefined);
+    settingsRef.current = settings;
+    const updateSettings = useCallback((update) => {
+        const current = settingsRef.current ?? {};
+        const merged = deepMergeContext(current, update);
+        // Only what changed goes to the host (§8.2): a UI that spreads the
+        // settings it was given would otherwise send every value back as
+        // a facilitator override.
+        const changed = changedFrom(update, current) ?? {};
+        settingsRef.current = merged;
+        setSettingsState(merged);
+        return sendMutation({ type: 'updateSettings', payload: changed });
+    }, [sendMutation]);
+    useDocumentAttributes(locale?.locale, theme?.mode);
+    const requestPlay = useCallback(() => postMessage({ type: 'requestPlay' }), [postMessage]);
+    const editorContextValue = useMemo(() => ({ settings, updateSettings, configures }), [settings, updateSettings, configures]);
+    const callbacksContextValue = useMemo(() => ({ uploadBlob, getAssetUrl, readAsset, setThemePreference, endpoints, requestPlay }), [uploadBlob, getAssetUrl, readAsset, setThemePreference, endpoints, requestPlay]);
+    const storageScope = useMemo(() => ({
+        sessionKey,
+        surface: 'settings-editor',
+        viewer: 'facilitator',
+    }), [sessionKey]);
+    return (_jsx(SurfaceGate, { expectedParentOrigin: expectedParentOrigin, ready: isInitialized && theme !== undefined && locale !== undefined, fallback: fallback, children: _jsx(SurfaceScope, { storage: storageScope, assetUrls: assetUrls, getAssetUrl: getAssetUrl, locale: locale?.locale, children: _jsx(SettingsEditorContext.Provider, { value: editorContextValue, children: _jsx(SettingsEditorThemeContext.Provider, { value: theme, children: _jsx(SettingsEditorThemePreferenceContext.Provider, { value: themePreference, children: _jsx(SettingsEditorLocaleContext.Provider, { value: locale, children: _jsx(SettingsEditorCallbacksContext.Provider, { value: callbacksContextValue, children: children }) }) }) }) }) }) }));
+}
+export default SettingsEditorWrapper;

package/lib/ui/UserInterfaceCallbacksContext.d.ts

@@ -0,0 +1,3 @@
+import type { UserInterfaceCallbacks } from '../build/callbacks.js';
+export declare const UserInterfaceCallbacksContext: import("react").Context<UserInterfaceCallbacks | undefined>;
+export declare const useUserInterfaceCallbacks: () => UserInterfaceCallbacks;

package/lib/ui/UserInterfaceCallbacksContext.js

@@ -0,0 +1,7 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useUserInterfaceCallbacks',
+    wrapperName: 'UserInterfaceWrapper',
+});
+export const UserInterfaceCallbacksContext = Context;
+export const useUserInterfaceCallbacks = useValue;