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

package/lib/ui/UserInterfaceWrapper.js

@@ -0,0 +1,219 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { CrossTeamDataContext } from './CrossTeamDataContext.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 { useOptimisticMerge } from './internal/useOptimisticMerge.js';
+import { useTypedPastState } from './internal/useTypedPastState.js';
+import { useHostChannel } from './useHostChannel.js';
+import { UserInterfaceCallbacksContext } from './UserInterfaceCallbacksContext.js';
+import { UserInterfaceDataContext } from './UserInterfaceDataContext.js';
+import { UserInterfaceLocaleContext } from './UserInterfaceLocaleContext.js';
+import { UserInterfaceOwnTeamContext } from './UserInterfaceOwnTeamContext.js';
+import { UserInterfaceOwnTeamJoinLinkContext, } from './UserInterfaceOwnTeamJoinLinkContext.js';
+import { UserInterfaceParticipantContext } from './UserInterfaceParticipantContext.js';
+import { UserInterfaceParticipantsContext } from './UserInterfaceParticipantsContext.js';
+import { UserInterfaceRunKindContext } from './UserInterfaceRunKindContext.js';
+import { UserInterfaceTeamsContext } from './UserInterfaceTeamsContext.js';
+import { UserInterfaceThemeContext } from './UserInterfaceThemeContext.js';
+import { UserInterfaceThemePreferenceContext } from './UserInterfaceThemePreferenceContext.js';
+import { UserInterfaceTimerContext } from './UserInterfaceTimerContext.js';
+import { UserInterfaceValidationContext } from './UserInterfaceValidationContext.js';
+import { UserInterfaceViewerRoleContext, } from './UserInterfaceViewerRoleContext.js';
+const REQUIRED_MESSAGES = [
+    'stateChanged',
+    'setSettings',
+    'setTheme',
+    'setLocale',
+    'setParticipant',
+    'setAssetUrls',
+];
+function UserInterfaceWrapper({ children, fallback = _jsx("div", { children: "Loading..." }), targetWindow = window.parent, }) {
+    const [data, setDataState] = useState({});
+    const [completedTicks, setCompletedTicks] = useState(0);
+    // Snapshot of the most recent host-confirmed data. Used to roll back local
+    // state when a UI-submitted mutation is rejected by validators — without
+    // this, the iframe would keep its optimistic value while the host's
+    // persisted state diverges.
+    const lastHostDataRef = useRef({});
+    const [settings, setSettingsState] = useState(undefined);
+    const [crossTeamData, setCrossTeamDataState] = useState([]);
+    const [theme, setThemeState] = useState(undefined);
+    const [locale, setLocaleState] = useState(undefined);
+    // `null` is a real value here, not a placeholder: an observer has no caller
+    // identity. A participant render replaces it via setParticipant; an observer
+    // render leaves it null and satisfies the participant gate via setViewerRole.
+    const [participant, setParticipantState] = useState(null);
+    const [viewerRole, setViewerRoleState] = useState('participant');
+    // Fixed for the life of the run. 'session' is what a host offering no
+    // walkthroughs means, so it never gates first paint.
+    const [runKind, setRunKindState] = useState('session');
+    const [participants, setParticipantsState] = useState([]);
+    const [teams, setTeamsState] = useState([]);
+    // The team this surface renders, as the host reported it. Populated for
+    // observers too, which is the whole point: an observer has no participant to
+    // derive a team from (#332).
+    const [hostOwnTeam, setHostOwnTeamState] = useState(null);
+    // How to join this surface's own team. Never gates first paint: a join
+    // panel renders a placeholder rather than holding up the canvas.
+    const [ownTeamJoinLink, setOwnTeamJoinLinkState] = useState(null);
+    const [timer, setTimerState] = useState(DEFAULT_SURFACE_TIMER);
+    // Not processing is the honest default and the overwhelmingly common state,
+    // so this does not gate first paint: a surface that never hears about it
+    // renders as it always did.
+    const [isRoundProcessing, setRoundProcessingState] = useState(false);
+    const [validationRejections, setValidationRejections] = useState([]);
+    const channel = useHostChannel({
+        targetWindow,
+        label: 'UserInterfaceWrapper',
+        requiredMessages: REQUIRED_MESSAGES,
+        onMessage: (msg, { markReceived }) => {
+            if (msg.type === 'stateChanged') {
+                const payload = msg.payload ?? {};
+                setDataState(payload);
+                lastHostDataRef.current = payload;
+                if (typeof msg.completedTicks === 'number') {
+                    setCompletedTicks(msg.completedTicks);
+                }
+                markReceived('stateChanged');
+            }
+            else if (msg.type === 'setCrossTeamData') {
+                setCrossTeamDataState(msg.payload ?? []);
+            }
+            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 === 'setParticipant') {
+                setParticipantState(msg.payload);
+                markReceived('setParticipant');
+            }
+            else if (msg.type === 'setViewerRole') {
+                setViewerRoleState(msg.role);
+                if (msg.role === 'observer') {
+                    // An observer has no caller identity and never receives
+                    // setParticipant, so satisfy the required-message gate here
+                    // and keep the participant null.
+                    setParticipantState(null);
+                    markReceived('setParticipant');
+                }
+            }
+            else if (msg.type === 'setRunKind') {
+                setRunKindState(msg.runKind);
+            }
+            else if (msg.type === 'setParticipantList') {
+                setParticipantsState(msg.participants);
+            }
+            else if (msg.type === 'setTeamList') {
+                setTeamsState(msg.payload);
+            }
+            else if (msg.type === 'setOwnTeam') {
+                setHostOwnTeamState(msg.payload);
+            }
+            else if (msg.type === 'setOwnTeamJoinLink') {
+                setOwnTeamJoinLinkState(msg.payload);
+            }
+            else if (msg.type === 'setTimer') {
+                setTimerState(msg.payload);
+            }
+            else if (msg.type === 'setRoundProcessing') {
+                setRoundProcessingState(msg.processing);
+            }
+            else if (msg.type === 'validationRejected') {
+                setValidationRejections(msg.rejections);
+                // Roll local state back to the host's last confirmed value so the
+                // optimistic write done by setData is discarded.
+                setDataState(lastHostDataRef.current);
+            }
+        },
+    });
+    const { isInitialized, expectedParentOrigin, sendMutation, sendMutationReportingCommit, uploadBlob, readAsset, getPastState: getPastStateRaw, getAllTeamsParticipants, getAssetUrl, assetUrls, setThemePreference, endpoints, themePreference, sessionKey, } = channel;
+    useDocumentAttributes(locale?.locale, theme?.mode);
+    const getPastState = useTypedPastState(getPastStateRaw);
+    // The tick the participant is looking at is held here and compared against
+    // the tick the host reports committing into, so the pair never leaves the
+    // surface. Read from a ref rather than closed over, or every tick would
+    // rebuild `setData` and re-render every control that depends on its
+    // identity.
+    const completedTicksRef = useLatestRef(completedTicks);
+    const setData = useOptimisticMerge(data, setDataState, useCallback((update, deletes) => {
+        const composedAtTick = completedTicksRef.current;
+        return sendMutationReportingCommit({
+            type: 'updateData',
+            payload: update,
+            ...(deletes?.length ? { deletes } : {}),
+        }).then(({ committedAtTick }) => ({
+            committedAtTick,
+            composedAtTick,
+            // Both numbers are only ever in one place at once, so the
+            // comparison lives here rather than in every caller.
+            late: typeof committedAtTick === 'number' && committedAtTick > composedAtTick,
+        }));
+    }, [sendMutationReportingCommit, completedTicksRef]));
+    const requestTick = useCallback(() => sendMutation({ type: 'requestTick' }), [sendMutation]);
+    // No teamId: the host resolves the caller's team, so a surface can only
+    // rename its own. The result arrives back through setOwnTeam/setTeamList,
+    // which is what to render rather than the name that was sent.
+    const renameOwnTeam = useCallback((name) => sendMutation({ type: 'renameOwnTeam', name }), [sendMutation]);
+    const clearValidationRejections = useCallback(() => {
+        setValidationRejections([]);
+    }, []);
+    // Memoize each context value so consumers only re-render when their slice
+    // actually changes — otherwise every state update would invalidate every
+    // context's value object identity and cascade through the whole tree.
+    const dataContextValue = useMemo(() => ({ data, settings, completedTicks, isRoundProcessing, setData }), [data, settings, completedTicks, isRoundProcessing, setData]);
+    const validationContextValue = useMemo(() => ({
+        rejections: validationRejections,
+        clearRejections: clearValidationRejections,
+    }), [validationRejections, clearValidationRejections]);
+    const callbacksContextValue = useMemo(() => ({
+        requestTick,
+        renameOwnTeam,
+        uploadBlob,
+        getAssetUrl,
+        readAsset,
+        getPastState,
+        getAllTeamsParticipants,
+        setThemePreference,
+        endpoints,
+    }), [
+        requestTick,
+        renameOwnTeam,
+        uploadBlob,
+        getAssetUrl,
+        readAsset,
+        getPastState,
+        getAllTeamsParticipants,
+        setThemePreference,
+        endpoints,
+    ]);
+    // Prefer what the host reported. The participant fallback keeps a host that
+    // predates `setOwnTeam` working for participants; only an observer on such a
+    // host is left without a team, which is the case that was already broken.
+    const ownTeam = useMemo(() => {
+        if (hostOwnTeam)
+            return hostOwnTeam;
+        if (!participant)
+            return null;
+        return teams.find((team) => team.teamId === participant.teamId) ?? null;
+    }, [hostOwnTeam, participant, teams]);
+    const participantId = participant?.id;
+    const storageScope = useMemo(() => ({
+        sessionKey,
+        surface: 'player',
+        viewer: participantId ?? viewerRole,
+    }), [sessionKey, participantId, viewerRole]);
+    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, getPastState: getPastState, children: _jsx(UserInterfaceDataContext.Provider, { value: dataContextValue, children: _jsx(CrossTeamDataContext.Provider, { value: crossTeamData, children: _jsx(UserInterfaceThemeContext.Provider, { value: theme, children: _jsx(UserInterfaceThemePreferenceContext.Provider, { value: themePreference, children: _jsx(UserInterfaceLocaleContext.Provider, { value: locale, children: _jsx(UserInterfaceRunKindContext.Provider, { value: runKind, children: _jsx(UserInterfaceViewerRoleContext.Provider, { value: viewerRole, children: _jsx(UserInterfaceParticipantContext.Provider, { value: participant, children: _jsx(UserInterfaceParticipantsContext.Provider, { value: participants, children: _jsx(UserInterfaceTeamsContext.Provider, { value: teams, children: _jsx(UserInterfaceOwnTeamContext.Provider, { value: ownTeam, children: _jsx(UserInterfaceOwnTeamJoinLinkContext.Provider, { value: ownTeamJoinLink, children: _jsx(UserInterfaceTimerContext.Provider, { value: timer, children: _jsx(UserInterfaceCallbacksContext.Provider, { value: callbacksContextValue, children: _jsx(UserInterfaceValidationContext.Provider, { value: validationContextValue, children: children }) }) }) }) }) }) }) }) }) }) }) }) }) }) }) }) }));
+}
+export default UserInterfaceWrapper;

package/lib/ui/expectedParentOrigin.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Reads the `expectedParentOrigin` query parameter from `window.location` and
+ * validates it as a bare origin string (`scheme://host[:port]`, no path/query/
+ * fragment). Returns the canonicalised origin if valid, `null` otherwise.
+ *
+ * The wrapper uses this both as the `targetOrigin` for its outbound `ready`
+ * postMessage and as the allowed `event.origin` for inbound `init`. Without it
+ * the wrapper refuses to operate (see each wrapper for the user-facing error).
+ */
+export declare function readExpectedParentOrigin(): string | null;

package/lib/ui/expectedParentOrigin.js

@@ -0,0 +1,32 @@
+/**
+ * Reads the `expectedParentOrigin` query parameter from `window.location` and
+ * validates it as a bare origin string (`scheme://host[:port]`, no path/query/
+ * fragment). Returns the canonicalised origin if valid, `null` otherwise.
+ *
+ * The wrapper uses this both as the `targetOrigin` for its outbound `ready`
+ * postMessage and as the allowed `event.origin` for inbound `init`. Without it
+ * the wrapper refuses to operate (see each wrapper for the user-facing error).
+ */
+export function readExpectedParentOrigin() {
+    const raw = new URLSearchParams(window.location.search).get('expectedParentOrigin');
+    if (!raw)
+        return null;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return null;
+    if (url.pathname !== '/' && url.pathname !== '')
+        return null;
+    if (url.search)
+        return null;
+    if (url.hash)
+        return null;
+    if (url.username || url.password)
+        return null;
+    return url.origin;
+}

package/lib/ui/index.d.ts

@@ -0,0 +1,50 @@
+export { default as UserInterfaceWrapper } from './UserInterfaceWrapper.js';
+export { useUserInterfaceData, UserInterfaceDataContext } from './UserInterfaceDataContext.js';
+export { useUserInterfaceTheme, type UserInterfaceTheme, type UserInterfaceModeColors, UserInterfaceThemeContext, } from './UserInterfaceThemeContext.js';
+export { useUserInterfaceThemePreference, UserInterfaceThemePreferenceContext, } from './UserInterfaceThemePreferenceContext.js';
+export { useUserInterfaceLocale, type UserInterfaceLocale, UserInterfaceLocaleContext, } from './UserInterfaceLocaleContext.js';
+export { useUserInterfaceParticipant, UserInterfaceParticipantContext, } from './UserInterfaceParticipantContext.js';
+export { useUserInterfaceViewerRole, type ViewerRole, UserInterfaceViewerRoleContext, } from './UserInterfaceViewerRoleContext.js';
+export { useRunKind, type RunKind, UserInterfaceRunKindContext, } from './UserInterfaceRunKindContext.js';
+export { useUserInterfaceTimer, UserInterfaceTimerContext } from './UserInterfaceTimerContext.js';
+export { useViewerStorage, ViewerStorageContext, type ViewerStorageScope, type ViewerStorageSurface, } from './useViewerStorage.js';
+export { useAssetUrl, useAsset, localisedReferences, AssetContext, type AssetFormat, type AssetScope, type AssetState, type UseAssetOptions, } from './useAsset.js';
+export { usePastState, PastStateContext, type PastStateReader, type PastStateResult, } from './usePastState.js';
+export type { ThemeColorRole, ThemeContrastText } from './internal/createContexts.js';
+export type { TimerState } from '../build/timer.js';
+export { useUserInterfaceParticipants, UserInterfaceParticipantsContext, } from './UserInterfaceParticipantsContext.js';
+export { useUserInterfaceTeams, UserInterfaceTeamsContext } from './UserInterfaceTeamsContext.js';
+export { useUserInterfaceOwnTeam, UserInterfaceOwnTeamContext, } from './UserInterfaceOwnTeamContext.js';
+export { useUserInterfaceOwnTeamJoinLink, type OwnTeamJoinLink, UserInterfaceOwnTeamJoinLinkContext, } from './UserInterfaceOwnTeamJoinLinkContext.js';
+export { useUserInterfaceCrossTeamData, CrossTeamDataContext, type CrossTeamData, } from './CrossTeamDataContext.js';
+export { useUserInterfaceCallbacks, UserInterfaceCallbacksContext, } from './UserInterfaceCallbacksContext.js';
+export { useUserInterfaceValidationRejections, type UserInterfaceValidationContextValue, UserInterfaceValidationContext, } from './UserInterfaceValidationContext.js';
+export { default as SettingsEditorWrapper } from './SettingsEditorWrapper.js';
+export { useSettingsEditor, type SettingsEditorValue, SettingsEditorContext, } from './SettingsEditorContext.js';
+export { useSettingsEditorTheme, type SettingsEditorTheme, type SettingsEditorModeColors, SettingsEditorThemeContext, } from './SettingsEditorThemeContext.js';
+export { useSettingsEditorThemePreference, SettingsEditorThemePreferenceContext, } from './SettingsEditorThemePreferenceContext.js';
+export { useSettingsEditorLocale, type SettingsEditorLocale, SettingsEditorLocaleContext, } from './SettingsEditorLocaleContext.js';
+export { useSettingsEditorCallbacks, SettingsEditorCallbacksContext, } from './SettingsEditorCallbacksContext.js';
+export { default as SessionUserInterfaceWrapper } from './SessionUserInterfaceWrapper.js';
+export { useSessionUserInterfaceData, SessionUserInterfaceDataContext, type SessionData, type SharedState, type TeamState, } from './SessionUserInterfaceDataContext.js';
+export { useSessionUserInterfaceTheme, type SessionUserInterfaceTheme, type SessionUserInterfaceModeColors, SessionUserInterfaceThemeContext, } from './SessionUserInterfaceThemeContext.js';
+export { useSessionUserInterfaceThemePreference, SessionUserInterfaceThemePreferenceContext, } from './SessionUserInterfaceThemePreferenceContext.js';
+export { useSessionUserInterfaceLocale, type SessionUserInterfaceLocale, SessionUserInterfaceLocaleContext, } from './SessionUserInterfaceLocaleContext.js';
+export { useSessionUserInterfaceCallbacks, SessionUserInterfaceCallbacksContext, } from './SessionUserInterfaceCallbacksContext.js';
+export { useSessionUserInterfaceParticipants, SessionUserInterfaceParticipantsContext, } from './SessionUserInterfaceParticipantsContext.js';
+export { useSessionUserInterfaceHookFailures, type SessionHookFailure, type SessionUserInterfaceHookFailuresValue, SessionUserInterfaceHookFailuresContext, } from './SessionUserInterfaceHookFailuresContext.js';
+export { useSessionUserInterfaceHostOverlays, type HostOverlay, SessionUserInterfaceHostOverlaysContext, } from './SessionUserInterfaceHostOverlaysContext.js';
+export { useSessionUserInterfaceMeta, type SessionMeta, SessionUserInterfaceMetaContext, } from './SessionUserInterfaceMetaContext.js';
+export { useSessionUserInterfaceTeamLinks, type TeamLinks, SessionUserInterfaceTeamLinksContext, } from './SessionUserInterfaceTeamLinksContext.js';
+export { useSessionUserInterfaceWalkthroughLink, type WalkthroughLink, SessionUserInterfaceWalkthroughLinkContext, } from './SessionUserInterfaceWalkthroughLinkContext.js';
+export { useSessionUserInterfaceTeamConfiguration, type TeamConfiguration, SessionUserInterfaceTeamConfigurationContext, } from './SessionUserInterfaceTeamConfigurationContext.js';
+export { useSessionUserInterfaceTeams, SessionUserInterfaceTeamsContext, } from './SessionUserInterfaceTeamsContext.js';
+export { PresentationWrapper } from './PresentationWrapper.js';
+export { usePresentation, PresentationContext, type PresentationGame, type PresentationSession, type PresentationValue, } from './PresentationContext.js';
+export { MutationError, type MutationOutcome } from './mutation-outcome.js';
+export { EndpointError, type EffectStep, type EndpointFailure, type EndpointFailureOutcome, } from '../build/endpoints.js';
+export { useMutationReporter, type MutationFailure, type MutationReporter, } from './useMutationReporter.js';
+export { TickSnapshotError } from './tick-snapshot.js';
+export type { Participant, PastStateEntry, PastStateQuery, TeamInfo, TeamStateEntry, } from '../build/callbacks.js';
+export type { ContextDeletePath, ContextUpdate } from '../build/context-merge.js';
+export type { SetDataOptions } from './UserInterfaceDataContext.js';

package/lib/ui/index.js

@@ -0,0 +1,52 @@
+export { default as UserInterfaceWrapper } from './UserInterfaceWrapper.js';
+export { useUserInterfaceData, UserInterfaceDataContext } from './UserInterfaceDataContext.js';
+export { useUserInterfaceTheme, UserInterfaceThemeContext, } from './UserInterfaceThemeContext.js';
+export { useUserInterfaceThemePreference, UserInterfaceThemePreferenceContext, } from './UserInterfaceThemePreferenceContext.js';
+export { useUserInterfaceLocale, UserInterfaceLocaleContext, } from './UserInterfaceLocaleContext.js';
+export { useUserInterfaceParticipant, UserInterfaceParticipantContext, } from './UserInterfaceParticipantContext.js';
+export { useUserInterfaceViewerRole, UserInterfaceViewerRoleContext, } from './UserInterfaceViewerRoleContext.js';
+export { useRunKind, UserInterfaceRunKindContext, } from './UserInterfaceRunKindContext.js';
+export { useUserInterfaceTimer, UserInterfaceTimerContext } from './UserInterfaceTimerContext.js';
+export { useViewerStorage, ViewerStorageContext, } from './useViewerStorage.js';
+export { useAssetUrl, useAsset, localisedReferences, AssetContext, } from './useAsset.js';
+export { usePastState, PastStateContext, } from './usePastState.js';
+export { useUserInterfaceParticipants, UserInterfaceParticipantsContext, } from './UserInterfaceParticipantsContext.js';
+export { useUserInterfaceTeams, UserInterfaceTeamsContext } from './UserInterfaceTeamsContext.js';
+export { useUserInterfaceOwnTeam, UserInterfaceOwnTeamContext, } from './UserInterfaceOwnTeamContext.js';
+export { useUserInterfaceOwnTeamJoinLink, UserInterfaceOwnTeamJoinLinkContext, } from './UserInterfaceOwnTeamJoinLinkContext.js';
+export { useUserInterfaceCrossTeamData, CrossTeamDataContext, } from './CrossTeamDataContext.js';
+export { useUserInterfaceCallbacks, UserInterfaceCallbacksContext, } from './UserInterfaceCallbacksContext.js';
+export { useUserInterfaceValidationRejections, UserInterfaceValidationContext, } from './UserInterfaceValidationContext.js';
+export { default as SettingsEditorWrapper } from './SettingsEditorWrapper.js';
+export { useSettingsEditor, SettingsEditorContext, } from './SettingsEditorContext.js';
+export { useSettingsEditorTheme, SettingsEditorThemeContext, } from './SettingsEditorThemeContext.js';
+export { useSettingsEditorThemePreference, SettingsEditorThemePreferenceContext, } from './SettingsEditorThemePreferenceContext.js';
+export { useSettingsEditorLocale, SettingsEditorLocaleContext, } from './SettingsEditorLocaleContext.js';
+export { useSettingsEditorCallbacks, SettingsEditorCallbacksContext, } from './SettingsEditorCallbacksContext.js';
+export { default as SessionUserInterfaceWrapper } from './SessionUserInterfaceWrapper.js';
+export { useSessionUserInterfaceData, SessionUserInterfaceDataContext, } from './SessionUserInterfaceDataContext.js';
+export { useSessionUserInterfaceTheme, SessionUserInterfaceThemeContext, } from './SessionUserInterfaceThemeContext.js';
+export { useSessionUserInterfaceThemePreference, SessionUserInterfaceThemePreferenceContext, } from './SessionUserInterfaceThemePreferenceContext.js';
+export { useSessionUserInterfaceLocale, SessionUserInterfaceLocaleContext, } from './SessionUserInterfaceLocaleContext.js';
+export { useSessionUserInterfaceCallbacks, SessionUserInterfaceCallbacksContext, } from './SessionUserInterfaceCallbacksContext.js';
+export { useSessionUserInterfaceParticipants, SessionUserInterfaceParticipantsContext, } from './SessionUserInterfaceParticipantsContext.js';
+export { useSessionUserInterfaceHookFailures, SessionUserInterfaceHookFailuresContext, } from './SessionUserInterfaceHookFailuresContext.js';
+export { useSessionUserInterfaceHostOverlays, SessionUserInterfaceHostOverlaysContext, } from './SessionUserInterfaceHostOverlaysContext.js';
+export { useSessionUserInterfaceMeta, SessionUserInterfaceMetaContext, } from './SessionUserInterfaceMetaContext.js';
+export { useSessionUserInterfaceTeamLinks, SessionUserInterfaceTeamLinksContext, } from './SessionUserInterfaceTeamLinksContext.js';
+export { useSessionUserInterfaceWalkthroughLink, SessionUserInterfaceWalkthroughLinkContext, } from './SessionUserInterfaceWalkthroughLinkContext.js';
+export { useSessionUserInterfaceTeamConfiguration, SessionUserInterfaceTeamConfigurationContext, } from './SessionUserInterfaceTeamConfigurationContext.js';
+export { useSessionUserInterfaceTeams, SessionUserInterfaceTeamsContext, } from './SessionUserInterfaceTeamsContext.js';
+// The wire protocol the wrappers speak (./ui-protocol.ts) is deliberately not
+// exported: game code never handles a message. A host implementation takes the
+// host's definition from @seriousgaming/sdk-tools/host.
+export { PresentationWrapper } from './PresentationWrapper.js';
+export { usePresentation, PresentationContext, } from './PresentationContext.js';
+export { MutationError } from './mutation-outcome.js';
+export { EndpointError, } from '../build/endpoints.js';
+export { useMutationReporter, } from './useMutationReporter.js';
+export { TickSnapshotError } from './tick-snapshot.js';
+// The render/mock testing helpers are published from the dedicated
+// `@seriousgaming/sdk/ui/testing` subpath (see ./testing.ts)
+// so the main `/ui` entry does not pull in the optional @testing-library/react
+// peer at runtime.

package/lib/ui/internal/SurfaceGate.d.ts

@@ -0,0 +1,19 @@
+import { ReactElement, ReactNode } from 'react';
+interface SurfaceGateProps {
+    /** The pinned parent origin; a missing/malformed value is a config error. */
+    expectedParentOrigin: string | null;
+    /** Whether the wrapper has received everything it needs to render children. */
+    ready: boolean;
+    /** Shown while `ready` is false. */
+    fallback: ReactNode;
+    children: ReactNode;
+}
+/**
+ * The shared render gate every surface wrapper puts in front of its provider
+ * tree: an inline error when the asset-host origin is unconfigured, the
+ * fallback until the wrapper is `ready`, otherwise the children. Callers
+ * compute `ready` so surfaces with extra conditions (e.g. configuration's
+ * `surface`) can AND them in without a bespoke prop.
+ */
+export declare function SurfaceGate({ expectedParentOrigin, ready, fallback, children, }: SurfaceGateProps): ReactElement;
+export {};

package/lib/ui/internal/SurfaceGate.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The shared render gate every surface wrapper puts in front of its provider
+ * tree: an inline error when the asset-host origin is unconfigured, the
+ * fallback until the wrapper is `ready`, otherwise the children. Callers
+ * compute `ready` so surfaces with extra conditions (e.g. configuration's
+ * `surface`) can AND them in without a bespoke prop.
+ */
+export function SurfaceGate({ expectedParentOrigin, ready, fallback, children, }) {
+    if (!expectedParentOrigin) {
+        return (_jsx("div", { role: "alert", children: "Asset host configuration error: expectedParentOrigin missing or malformed." }));
+    }
+    if (!ready) {
+        return _jsx(_Fragment, { children: fallback });
+    }
+    return _jsx(_Fragment, { children: children });
+}

package/lib/ui/internal/SurfaceScope.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+import type { AssetUrls } from '../ui-protocol.js';
+import { type PastStateReader } from '../usePastState.js';
+import { type ViewerStorageScope } from '../useViewerStorage.js';
+/**
+ * The contexts behind the hooks every surface shares (`useViewerStorage`,
+ * `useAssetUrl`, `useAsset` and, where the surface can read history,
+ * `usePastState`), provided once per wrapper.
+ */
+export declare function SurfaceScope({ storage, assetUrls, getAssetUrl, locale, getPastState, children, }: {
+    storage: ViewerStorageScope;
+    assetUrls: AssetUrls | undefined;
+    getAssetUrl: (reference: string) => string;
+    locale: string | undefined;
+    getPastState?: PastStateReader;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/lib/ui/internal/SurfaceScope.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from 'react';
+import { AssetContext } from '../useAsset.js';
+import { PastStateContext } from '../usePastState.js';
+import { ViewerStorageContext } from '../useViewerStorage.js';
+/**
+ * The contexts behind the hooks every surface shares (`useViewerStorage`,
+ * `useAssetUrl`, `useAsset` and, where the surface can read history,
+ * `usePastState`), provided once per wrapper.
+ */
+export function SurfaceScope({ storage, assetUrls, getAssetUrl, locale, getPastState, children, }) {
+    const ready = assetUrls !== undefined;
+    const assets = useMemo(() => ({ getAssetUrl: ready ? getAssetUrl : undefined, locale }), [ready, getAssetUrl, locale]);
+    const scoped = (_jsx(ViewerStorageContext.Provider, { value: storage, children: _jsx(AssetContext.Provider, { value: assets, children: children }) }));
+    return getPastState ? (_jsx(PastStateContext.Provider, { value: getPastState, children: scoped })) : (scoped);
+}

package/lib/ui/internal/createContexts.d.ts

@@ -0,0 +1,50 @@
+import { type Context } from 'react';
+/**
+ * Colour roles shared by every surface's theme. Internal only — each surface
+ * re-declares its public `*Theme` type locally (referencing this) so the
+ * published type names are unchanged.
+ */
+export type SurfaceModeColors = {
+    primary: string;
+    secondary: string;
+    success: string;
+    error: string;
+    warning: string;
+    info: string;
+    /**
+     * The text colour to draw on each of the colours above, as an opaque
+     * `#rrggbb`, meeting WCAG AA (4.5:1) against it (§12.3).
+     */
+    contrastText: ThemeContrastText;
+};
+/** The palette roles a theme sends, each a colour a surface may paint with. */
+export type ThemeColorRole = 'primary' | 'secondary' | 'success' | 'error' | 'warning' | 'info';
+/** One text colour per palette role, for text drawn on that role's colour. */
+export type ThemeContrastText = Record<ThemeColorRole, string>;
+export interface RequiredContext<T> {
+    Context: Context<T | undefined>;
+    /** Read the value; throws with a surface-specific message if unprovided. */
+    useValue: () => T;
+}
+/**
+ * Build a context whose consumer hook throws when read outside its wrapper.
+ * Backs the boilerplate "throwing" context roles (theme, theme-preference,
+ * callbacks, locale, surface, ui-list, validation, participant(s)); each
+ * surface file wraps this and re-exports the concrete `*Context` / `use*`
+ * names so the published API is unchanged.
+ */
+export declare function createRequiredContext<T>(options: {
+    hookName: string;
+    wrapperName: string;
+}): RequiredContext<T>;
+export interface DefaultedContext<T> {
+    Context: Context<T>;
+    /** Read the value; always defined (falls back to the default). */
+    useValue: () => T;
+}
+/**
+ * Build a context that always returns a value, defaulting to `defaultValue`
+ * when unprovided. Backs the non-throwing roles (timer, basic team list,
+ * player participant list).
+ */
+export declare function createDefaultedContext<T>(defaultValue: T): DefaultedContext<T>;

package/lib/ui/internal/createContexts.js

@@ -0,0 +1,32 @@
+import { createContext, useContext } from 'react';
+/**
+ * Build a context whose consumer hook throws when read outside its wrapper.
+ * Backs the boilerplate "throwing" context roles (theme, theme-preference,
+ * callbacks, locale, surface, ui-list, validation, participant(s)); each
+ * surface file wraps this and re-exports the concrete `*Context` / `use*`
+ * names so the published API is unchanged.
+ */
+export function createRequiredContext(options) {
+    const { hookName, wrapperName } = options;
+    const ContextObject = createContext(undefined);
+    function useValue() {
+        const value = useContext(ContextObject);
+        if (value === undefined) {
+            throw new Error(`${hookName} must be used inside a ${wrapperName}`);
+        }
+        return value;
+    }
+    return { Context: ContextObject, useValue };
+}
+/**
+ * Build a context that always returns a value, defaulting to `defaultValue`
+ * when unprovided. Backs the non-throwing roles (timer, basic team list,
+ * player participant list).
+ */
+export function createDefaultedContext(defaultValue) {
+    const ContextObject = createContext(defaultValue);
+    function useValue() {
+        return useContext(ContextObject);
+    }
+    return { Context: ContextObject, useValue };
+}

package/lib/ui/internal/document-attributes.d.ts

@@ -0,0 +1,9 @@
+/** The direction a locale's text runs in. */
+export declare function textDirection(locale: string): 'ltr' | 'rtl';
+/**
+ * Keep `lang`, `dir` and `color-scheme` on the document root in step with the
+ * surface's locale and theme, so a surface gets right-to-left layout, the
+ * correct hyphenation and voice, and dark scrollbars and form controls without
+ * setting any of them itself. Each is restored when the wrapper unmounts.
+ */
+export declare function useDocumentAttributes(locale: string | undefined, mode: 'light' | 'dark' | undefined): void;

package/lib/ui/internal/document-attributes.js

@@ -0,0 +1,87 @@
+import { useEffect } from 'react';
+/**
+ * Languages written right to left, for a runtime whose `Intl.Locale` cannot
+ * say. The script decides first where the tag names one, so `ku-Arab` is
+ * right to left and `ku-Latn` is not.
+ */
+const RTL_LANGUAGES = new Set([
+    'ar',
+    'arc',
+    'ckb',
+    'dv',
+    'fa',
+    'he',
+    'iw',
+    'ks',
+    'ps',
+    'sd',
+    'ug',
+    'ur',
+    'yi',
+]);
+const RTL_SCRIPTS = new Set(['Adlm', 'Arab', 'Hebr', 'Nkoo', 'Rohg', 'Syrc', 'Thaa']);
+function fromIntl(locale) {
+    try {
+        const parsed = new Intl.Locale(locale);
+        const info = typeof parsed.getTextInfo === 'function' ? parsed.getTextInfo() : parsed.textInfo;
+        if (info?.direction === 'rtl' || info?.direction === 'ltr')
+            return info.direction;
+    }
+    catch {
+        // Not a well-formed tag: the list below still has a view.
+    }
+    return undefined;
+}
+function fromList(locale) {
+    const parts = locale.split(/[-_]/);
+    const script = parts.find((part, index) => index > 0 && /^[A-Za-z]{4}$/.test(part));
+    if (script) {
+        const normalised = script[0].toUpperCase() + script.slice(1).toLowerCase();
+        return RTL_SCRIPTS.has(normalised) ? 'rtl' : 'ltr';
+    }
+    return RTL_LANGUAGES.has(parts[0].toLowerCase()) ? 'rtl' : 'ltr';
+}
+/** The direction a locale's text runs in. */
+export function textDirection(locale) {
+    return fromIntl(locale) ?? fromList(locale);
+}
+/**
+ * Keep `lang`, `dir` and `color-scheme` on the document root in step with the
+ * surface's locale and theme, so a surface gets right-to-left layout, the
+ * correct hyphenation and voice, and dark scrollbars and form controls without
+ * setting any of them itself. Each is restored when the wrapper unmounts.
+ */
+export function useDocumentAttributes(locale, mode) {
+    useEffect(() => {
+        if (locale === undefined || typeof document === 'undefined')
+            return;
+        const root = document.documentElement;
+        const previousLang = root.getAttribute('lang');
+        const previousDir = root.getAttribute('dir');
+        root.setAttribute('lang', locale);
+        root.setAttribute('dir', textDirection(locale));
+        return () => {
+            restore(root, 'lang', previousLang);
+            restore(root, 'dir', previousDir);
+        };
+    }, [locale]);
+    useEffect(() => {
+        if (mode === undefined || typeof document === 'undefined')
+            return;
+        const style = document.documentElement.style;
+        const previous = style.getPropertyValue('color-scheme');
+        style.setProperty('color-scheme', mode);
+        return () => {
+            if (previous)
+                style.setProperty('color-scheme', previous);
+            else
+                style.removeProperty('color-scheme');
+        };
+    }, [mode]);
+}
+function restore(root, name, previous) {
+    if (previous === null)
+        root.removeAttribute(name);
+    else
+        root.setAttribute(name, previous);
+}

package/lib/ui/internal/surface-timer.d.ts

@@ -0,0 +1,3 @@
+import type { TimerState } from '../../build/timer.js';
+/** The timer a surface holds before the host sends one: nothing scheduled. */
+export declare const DEFAULT_SURFACE_TIMER: TimerState;

package/lib/ui/internal/surface-timer.js

@@ -0,0 +1,11 @@
+/** The timer a surface holds before the host sends one: nothing scheduled. */
+export const DEFAULT_SURFACE_TIMER = {
+    enabled: false,
+    paused: false,
+    nextTickAt: null,
+    intervalMs: null,
+    pausedAt: null,
+    pausedMs: 0,
+    extendedMs: 0,
+    scheduleStartedAt: null,
+};