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

package/lib/ui/testing.js

@@ -0,0 +1,572 @@
+import { render } from '@testing-library/react';
+import { createElement } from 'react';
+import { applyContextUpdate } from '../build/context-merge.js';
+import { DEFAULT_SURFACE_TIMER } from './internal/surface-timer.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 { 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 { 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 { AssetContext } from './useAsset.js';
+import { PastStateContext } from './usePastState.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';
+import { ViewerStorageContext } from './useViewerStorage.js';
+// Each `contrastText` is the black or white a host would pick (§12.3): the one
+// of the two contrasting more with its colour, at 4.6:1 or better throughout.
+const DEFAULT_LIGHT_COLORS = {
+    primary: '#1976d2',
+    secondary: '#9c27b0',
+    success: '#4caf50',
+    error: '#f44336',
+    warning: '#ff9800',
+    info: '#2196f3',
+    contrastText: {
+        primary: '#ffffff',
+        secondary: '#ffffff',
+        success: '#000000',
+        error: '#000000',
+        warning: '#000000',
+        info: '#000000',
+    },
+};
+const DEFAULT_DARK_COLORS = {
+    primary: '#90caf9',
+    secondary: '#ce93d8',
+    success: '#66bb6a',
+    error: '#f44336',
+    warning: '#ffa726',
+    info: '#29b6f6',
+    contrastText: {
+        primary: '#000000',
+        secondary: '#000000',
+        success: '#000000',
+        error: '#000000',
+        warning: '#000000',
+        info: '#000000',
+    },
+};
+/** What `useViewerStorage` namespaces by in a render with no host. */
+const DEFAULT_SESSION_KEY = 'test-session-key';
+/**
+ * Creates a valid UserInterfaceTheme for use in tests.
+ *
+ * @example
+ * // Basic usage — light mode with default MUI palette
+ * <UserInterfaceThemeContext.Provider value={createMockTheme()}>
+ *
+ * @example
+ * // Override mode or colours
+ * <UserInterfaceThemeContext.Provider value={createMockTheme({ mode: 'dark' })}>
+ */
+export function createMockTheme(overrides) {
+    return {
+        mode: 'light',
+        light: DEFAULT_LIGHT_COLORS,
+        dark: DEFAULT_DARK_COLORS,
+        ...overrides,
+    };
+}
+/**
+ * Creates a valid SettingsEditorTheme for use in tests.
+ *
+ * @example
+ * <SettingsEditorThemeContext.Provider value={createMockSettingsEditorTheme()}>
+ */
+export function createMockSettingsEditorTheme(overrides) {
+    return {
+        mode: 'light',
+        light: DEFAULT_LIGHT_COLORS,
+        dark: DEFAULT_DARK_COLORS,
+        ...overrides,
+    };
+}
+/**
+ * Creates a valid SessionUserInterfaceTheme for use in tests.
+ */
+export function createMockSessionTheme(overrides) {
+    return {
+        mode: 'light',
+        light: DEFAULT_LIGHT_COLORS,
+        dark: DEFAULT_DARK_COLORS,
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// Stub factory — creates a no-op function (or async no-op) suitable for use
+// as a default callback in test helpers. Consumers can override individual
+// callbacks via the options object.
+// ---------------------------------------------------------------------------
+const noop = () => { };
+const asyncNoop = async () => { };
+// Default mock for `getPastState`, which answers with what the query reaches
+// rather than with a nullable value: an empty result is 'nothing reviewable',
+// so a surface under test renders its empty state rather than having to guard
+// a null. Tests that exercise review screens override it via `callbacks`.
+const asyncEmpty = async () => [];
+const asyncEmptyReference = async () => '';
+const asyncEmptyAsset = async () => ({
+    data: new Uint8Array(),
+    mimeType: 'application/octet-stream',
+    name: '',
+});
+// ---------------------------------------------------------------------------
+// Default values reused across render helpers
+// ---------------------------------------------------------------------------
+const DEFAULT_LOCALE = { locale: 'en' };
+// Sentinel prefixes for test helpers. The wrappers themselves no longer carry
+// a default — production hosts must declare prefixes via setAssetUrls. Tests
+// only need *some* prefix so that `getAssetUrl` returns a deterministic value;
+// override via the `blobPrefix` / `scenarioAssetPrefix` / `sharedAssetPrefix`
+// options.
+const DEFAULT_BLOB_URL_PREFIX = 'test:blob:';
+const DEFAULT_ASSET_URL_PREFIX = 'test:asset:';
+const DEFAULT_SHARED_ASSET_URL_PREFIX = 'test:shared:';
+// A live, unfrozen, PIN-less session with the waiting room closed: the state a
+// facilitator surface spends nearly all its time in, so tests opt in to the
+// awkward cases rather than out of them.
+const DEFAULT_SESSION_META = {
+    sessionId: 'session-1',
+    name: 'Test session',
+    readOnly: false,
+    waitingRoomOpen: false,
+    joinPin: null,
+};
+/**
+ * Bounds a rendered surface sees when a test does not supply its own.
+ *
+ * Unlike the wrapper's pre-handshake default, this stands in for bounds the
+ * host has already sent, so it is a plausible session rather than the
+ * unreachable `max: 0` (#365). A test asserting on behaviour at the maximum
+ * must pass its own `teamConfiguration`: the helper's number is a convenience,
+ * never the thing under test.
+ */
+const DEFAULT_TEAM_CONFIGURATION = {
+    mode: 'independent',
+    max: 8,
+};
+const BLOB_PREFIX = 'blob:';
+const ASSET_PREFIX = 'asset:';
+const SHARED_PREFIX = 'shared:';
+/**
+ * Construct a `getAssetUrl` stub that mirrors the SDK wrappers' production
+ * behaviour: dispatch on the reference prefix and concatenate with the
+ * matching URL prefix. Used by every render helper below.
+ */
+function makeGetAssetUrl(blobPrefix, scenarioAssetPrefix, sharedAssetPrefix) {
+    return (reference) => {
+        if (reference.startsWith(BLOB_PREFIX)) {
+            return blobPrefix + reference.slice(BLOB_PREFIX.length);
+        }
+        if (reference.startsWith(SHARED_PREFIX)) {
+            return sharedAssetPrefix + reference.slice(SHARED_PREFIX.length);
+        }
+        if (reference.startsWith(ASSET_PREFIX)) {
+            return scenarioAssetPrefix + reference.slice(ASSET_PREFIX.length);
+        }
+        throw new Error(`Invalid asset reference "${reference}": expected an "asset:", "shared:", or "blob:" prefix`);
+    };
+}
+/**
+ * Creates a valid Participant for use in tests — the caller's own
+ * identity, as returned by `useUserInterfaceParticipant()`.
+ *
+ * @example
+ * // The caller, with a custom name
+ * renderUserInterface(<App />, { participant: createMockParticipant({ name: 'Alice' }) });
+ */
+export function createMockParticipant(overrides) {
+    return {
+        id: '1',
+        name: 'Participant 1',
+        index: 0,
+        connected: true,
+        teamId: 'team-1',
+        ...overrides,
+    };
+}
+/**
+ * Creates a roster of participants for use in tests — the list returned by
+ * `useUserInterfaceParticipants()` (and the session equivalent, which
+ * shares the same shape). Ids, names, and indices follow the runtime's
+ * conventions (`id` is `String(index + 1)`, `name` is `Participant N`), and
+ * every entry is `connected` by default.
+ *
+ * @example
+ * // A team of three, all online
+ * renderUserInterface(<App />, { participants: createMockParticipants(3) });
+ */
+export function createMockParticipants(count = 1, teamId = 'team-1') {
+    return Array.from({ length: count }, (_, index) => ({
+        id: String(index + 1),
+        name: `Participant ${index + 1}`,
+        index,
+        connected: true,
+        teamId,
+    }));
+}
+/**
+ * A `TeamState` for a session-surface fixture, with the fields a test rarely
+ * cares about filled in.
+ *
+ * `revision` is the reason this exists. It is required, because the wrapper
+ * needs a baseline to compare an `updateTeamState` delta against, but no
+ * surface ever reads it, so making every fixture carry one would be friction
+ * for a field with no meaning to the test.
+ *
+ * Type it with the surface's generated `TeamContext`, and a shared capability
+ * left on a team's fixture fails to compile, as reading one through a team
+ * does in the surface. Capabilities the fixture leaves out are absent.
+ *
+ * ```typescript
+ * import type { TeamContext } from '../types';
+ *
+ * createMockTeamState<TeamContext>({ context: { price: { Price: 5 } } });
+ * ```
+ */
+export function createMockTeamState(overrides) {
+    const { context, ...rest } = overrides ?? {};
+    return {
+        context: (context ?? {}),
+        completedTicks: 0,
+        timer: DEFAULT_SURFACE_TIMER,
+        revision: 1,
+        ...rest,
+    };
+}
+/**
+ * A `SharedState` for a session-surface fixture: the shared store's context,
+ * with a `revision` filled in for the same reason {@link createMockTeamState}
+ * fills one. Type it with the surface's generated `SharedContext`.
+ *
+ * ```typescript
+ * createMockSharedState<SharedContext>({ context: { market: { Price: 5 } } });
+ * ```
+ */
+export function createMockSharedState(overrides) {
+    const { context, ...rest } = overrides ?? {};
+    return {
+        context: (context ?? {}),
+        revision: 1,
+        ...rest,
+    };
+}
+/**
+ * A `setData` for a stateful test harness that writes the way the host does:
+ * objects merge recursively, arrays, scalars and `null` replace whole, and
+ * any `deletes` are removed after the merge.
+ *
+ * A hand-rolled `{ ...previous, ...patch }` does not. It replaces a whole
+ * capability with whatever the patch names, so a minimal write (the shape
+ * every concurrency-safe surface sends) appears to wipe every field it did
+ * not mention. Tests then fail on writes that are correct in production, or
+ * worse, pass on writes that are not (#520).
+ *
+ * ```tsx
+ * const [data, setLocal] = useState(mockData);
+ * const setData = mergingSetData(setLocal);
+ * setData({}, { deletes: [`pinboard.Notes.${noteId}`] });
+ * ```
+ *
+ * Wrap it in a `vi.fn()` when the test also asserts on the payload.
+ */
+export function mergingSetData(setLocal) {
+    // `T extends object` rather than `Record<string, unknown>`: a generated
+    // `Context` is an interface, and an interface has no implicit index
+    // signature, so the tighter constraint would reject the one type every
+    // caller actually holds. The merge only ever reads own enumerable keys.
+    return (patch, options) => setLocal((previous) => applyContextUpdate(previous, patch, options?.deletes));
+}
+const DEFAULT_PARTICIPANT = createMockParticipant();
+const DEFAULT_TIMER = DEFAULT_SURFACE_TIMER;
+/**
+ * Resolve the own team a rendered player surface should see, mirroring the
+ * fallback order the real wrapper applies: an explicit value wins, otherwise the
+ * participant's team is resolved against the team list. An observer render (no
+ * participant) yields `null` unless `ownTeam` is given, matching a host that does
+ * not send `setOwnTeam`.
+ */
+function resolveOwnTeam(options) {
+    if (options.ownTeam !== undefined)
+        return options.ownTeam;
+    const participant = options.participant !== undefined
+        ? options.participant
+        : options.viewerRole === 'observer'
+            ? null
+            : DEFAULT_PARTICIPANT;
+    if (!participant)
+        return null;
+    return (options.teams ?? []).find((team) => team.teamId === participant.teamId) ?? null;
+}
+function provide(context, value) {
+    return (child) => createElement(context.Provider, { value }, child);
+}
+function wrapProviders(providers, child) {
+    return providers.reduceRight((acc, wrap) => wrap(acc), child);
+}
+/**
+ * Renders a component wrapped in all UserInterface context providers with
+ * sensible defaults. Override any context value via the options object.
+ *
+ * Returns the standard `@testing-library/react` render result plus the mock
+ * `setData` and resolved `callbacks` for assertions.
+ *
+ * Callbacks you do not supply default to no-ops rather than spies, so pass your
+ * own `vi.fn()` for any you intend to assert on.
+ *
+ * @example
+ * ```tsx
+ * const requestTick = vi.fn();
+ * const { setData } = renderUserInterface(<App />, {
+ *   data: { 'com.example.cap': { Score: 42 } },
+ *   settings: { scoring: { MaxScore: 100 } },
+ *   callbacks: { requestTick },
+ * });
+ *
+ * fireEvent.click(screen.getByText('Submit'));
+ * expect(requestTick).toHaveBeenCalled();
+ * ```
+ */
+export function renderUserInterface(ui, options = {}) {
+    const resolvedSetData = options.setData ?? noop;
+    // The context's `setData` resolves with a commit; a mock usually returns
+    // nothing, so answer as an on-time write unless the mock says otherwise.
+    const contextSetData = async (...args) => (await Reflect.apply(resolvedSetData, undefined, args)) ?? { late: false };
+    const blobPrefix = options.blobPrefix ?? DEFAULT_BLOB_URL_PREFIX;
+    const scenarioAssetPrefix = options.scenarioAssetPrefix ?? DEFAULT_ASSET_URL_PREFIX;
+    const sharedAssetPrefix = options.sharedAssetPrefix ?? DEFAULT_SHARED_ASSET_URL_PREFIX;
+    const resolvedCallbacks = {
+        requestTick: asyncNoop,
+        renameOwnTeam: asyncNoop,
+        uploadBlob: asyncEmptyReference,
+        getAssetUrl: makeGetAssetUrl(blobPrefix, scenarioAssetPrefix, sharedAssetPrefix),
+        readAsset: asyncEmptyAsset,
+        getPastState: asyncEmpty,
+        getAllTeamsParticipants: async () => [],
+        setThemePreference: noop,
+        endpoints: {},
+        ...options.callbacks,
+    };
+    const dataValue = {
+        data: (options.data ?? {}),
+        settings: options.settings ?? {},
+        completedTicks: options.completedTicks ?? 0,
+        isRoundProcessing: options.isRoundProcessing ?? false,
+        setData: contextSetData,
+    };
+    const participant = options.participant !== undefined
+        ? options.participant
+        : options.viewerRole === 'observer'
+            ? null
+            : DEFAULT_PARTICIPANT;
+    const providers = [
+        provide(ViewerStorageContext, {
+            sessionKey: options.sessionKey ?? DEFAULT_SESSION_KEY,
+            surface: 'player',
+            viewer: participant?.id ?? options.viewerRole ?? 'participant',
+        }),
+        provide(AssetContext, {
+            getAssetUrl: resolvedCallbacks.getAssetUrl,
+            locale: (options.locale ?? DEFAULT_LOCALE).locale,
+        }),
+        provide(PastStateContext, resolvedCallbacks.getPastState),
+        provide(UserInterfaceThemeContext, options.theme ?? createMockTheme()),
+        provide(UserInterfaceThemePreferenceContext, options.themePreference ?? 'system'),
+        provide(UserInterfaceLocaleContext, options.locale ?? DEFAULT_LOCALE),
+        provide(UserInterfaceViewerRoleContext, options.viewerRole ?? 'participant'),
+        provide(UserInterfaceRunKindContext, options.runKind ?? 'session'),
+        // An observer has no caller identity, so the participant defaults to
+        // null in that role unless the caller overrides it explicitly.
+        provide(UserInterfaceParticipantContext, participant),
+        provide(UserInterfaceParticipantsContext, options.participants ?? []),
+        provide(UserInterfaceTeamsContext, options.teams ?? []),
+        provide(UserInterfaceOwnTeamContext, resolveOwnTeam(options)),
+        provide(UserInterfaceOwnTeamJoinLinkContext, options.ownTeamJoinLink ?? null),
+        provide(UserInterfaceTimerContext, options.timer ?? DEFAULT_TIMER),
+        provide(UserInterfaceValidationContext, {
+            rejections: options.validationRejections ?? [],
+            clearRejections: options.clearRejections ?? noop,
+        }),
+        provide(UserInterfaceDataContext, dataValue),
+        provide(UserInterfaceCallbacksContext, resolvedCallbacks),
+    ];
+    const result = render(wrapProviders(providers, ui));
+    return { ...result, setData: resolvedSetData, callbacks: resolvedCallbacks };
+}
+/**
+ * Renders a component wrapped in every settings editor context provider: the
+ * `setup` slot and the `scenario_editor` slot share them.
+ *
+ * `updateSettings` defaults to a no-op rather than a spy, so pass your own
+ * `vi.fn()` to assert on it.
+ *
+ * @example
+ * ```tsx
+ * const updateSettings = vi.fn();
+ * renderSettingsEditor(<App />, {
+ *   settings: { engine: { MaxPlayers: 10 } },
+ *   updateSettings,
+ * });
+ *
+ * fireEvent.change(screen.getByLabelText('Max Players'), { target: { value: '20' } });
+ * expect(updateSettings).toHaveBeenCalled();
+ * ```
+ */
+export function renderSettingsEditor(ui, options = {}) {
+    const resolvedUpdateSettings = (options.updateSettings ?? asyncNoop);
+    const blobPrefix = options.blobPrefix ?? DEFAULT_BLOB_URL_PREFIX;
+    const scenarioAssetPrefix = options.scenarioAssetPrefix ?? DEFAULT_ASSET_URL_PREFIX;
+    const sharedAssetPrefix = options.sharedAssetPrefix ?? DEFAULT_SHARED_ASSET_URL_PREFIX;
+    const resolvedCallbacks = {
+        uploadBlob: asyncEmptyReference,
+        getAssetUrl: makeGetAssetUrl(blobPrefix, scenarioAssetPrefix, sharedAssetPrefix),
+        readAsset: asyncEmptyAsset,
+        setThemePreference: noop,
+        requestPlay: noop,
+        endpoints: {},
+        ...options.callbacks,
+    };
+    const settings = options.settings ?? {};
+    const editorValue = {
+        settings,
+        updateSettings: resolvedUpdateSettings,
+        configures: options.configures ?? Object.keys(settings),
+    };
+    const providers = [
+        provide(ViewerStorageContext, {
+            sessionKey: options.sessionKey ?? DEFAULT_SESSION_KEY,
+            surface: 'settings-editor',
+            viewer: 'facilitator',
+        }),
+        provide(AssetContext, {
+            getAssetUrl: resolvedCallbacks.getAssetUrl,
+            locale: (options.locale ?? DEFAULT_LOCALE).locale,
+        }),
+        provide(SettingsEditorThemeContext, options.theme ?? createMockSettingsEditorTheme()),
+        provide(SettingsEditorThemePreferenceContext, options.themePreference ?? 'system'),
+        provide(SettingsEditorLocaleContext, options.locale ?? DEFAULT_LOCALE),
+        provide(SettingsEditorContext, editorValue),
+        provide(SettingsEditorCallbacksContext, resolvedCallbacks),
+    ];
+    const result = render(wrapProviders(providers, ui));
+    return { ...result, updateSettings: resolvedUpdateSettings, callbacks: resolvedCallbacks };
+}
+/**
+ * Renders a component wrapped in all SessionUserInterface context providers.
+ *
+ * Callbacks you do not supply default to no-ops rather than spies, so pass your
+ * own `vi.fn()` for any you intend to assert on.
+ *
+ * @example
+ * ```tsx
+ * const resetGame = vi.fn();
+ * renderSessionUserInterface(<SessionDashboard />, {
+ *   sessionData: { teams: { 'team-1': createMockTeamState() } },
+ *   teams: [{ teamId: 'team-1', index: 0, name: 'Team 1' }],
+ *   callbacks: { resetGame },
+ * });
+ *
+ * fireEvent.click(screen.getByText('Reset All'));
+ * expect(resetGame).toHaveBeenCalled();
+ * ```
+ */
+export function renderSessionUserInterface(ui, options = {}) {
+    const resolvedSetData = options.setData ?? noop;
+    // The shared-scope form calls the mock with the update alone, as the host's
+    // own `setData` is called.
+    const contextSetData = async (...args) => {
+        Reflect.apply(resolvedSetData, undefined, args);
+    };
+    const blobPrefix = options.blobPrefix ?? DEFAULT_BLOB_URL_PREFIX;
+    const scenarioAssetPrefix = options.scenarioAssetPrefix ?? DEFAULT_ASSET_URL_PREFIX;
+    const sharedAssetPrefix = options.sharedAssetPrefix ?? DEFAULT_SHARED_ASSET_URL_PREFIX;
+    const resolvedCallbacks = {
+        uploadBlob: asyncEmptyReference,
+        getAssetUrl: makeGetAssetUrl(blobPrefix, scenarioAssetPrefix, sharedAssetPrefix),
+        readAsset: asyncEmptyAsset,
+        getPastState: asyncEmpty,
+        requestTick: asyncNoop,
+        pauseTimer: asyncNoop,
+        resumeTimer: asyncNoop,
+        resetGame: asyncNoop,
+        undoTick: asyncNoop,
+        extendTick: asyncNoop,
+        openHostOverlay: asyncNoop,
+        setWaitingRoom: asyncNoop,
+        resetWalkthrough: asyncNoop,
+        createTeam: asyncNoop,
+        renameTeam: asyncNoop,
+        renameParticipant: asyncNoop,
+        moveParticipant: asyncNoop,
+        deleteTeam: asyncNoop,
+        setThemePreference: noop,
+        endpoints: {},
+        ...options.callbacks,
+    };
+    const dataValue = {
+        // The provider holds the untyped shape; the surface's own
+        // `useSessionUserInterfaceData<SessionData>` types it back.
+        sessionData: {
+            shared: (options.sessionData?.shared ?? createMockSharedState()),
+            teams: (options.sessionData?.teams ?? {}),
+        },
+        settings: options.settings ?? {},
+        setData: contextSetData,
+    };
+    const providers = [
+        provide(ViewerStorageContext, {
+            sessionKey: options.sessionKey ?? DEFAULT_SESSION_KEY,
+            surface: 'session',
+            viewer: 'facilitator',
+        }),
+        provide(AssetContext, {
+            getAssetUrl: resolvedCallbacks.getAssetUrl,
+            locale: (options.locale ?? DEFAULT_LOCALE).locale,
+        }),
+        provide(PastStateContext, resolvedCallbacks.getPastState),
+        provide(SessionUserInterfaceThemeContext, options.theme ?? createMockSessionTheme()),
+        provide(SessionUserInterfaceThemePreferenceContext, options.themePreference ?? 'system'),
+        provide(SessionUserInterfaceLocaleContext, options.locale ?? DEFAULT_LOCALE),
+        provide(SessionUserInterfaceParticipantsContext, options.participants ?? []),
+        provide(SessionUserInterfaceTeamsContext, options.teams ?? []),
+        provide(SessionUserInterfaceTeamConfigurationContext, options.teamConfiguration ?? DEFAULT_TEAM_CONFIGURATION),
+        provide(SessionUserInterfaceMetaContext, options.sessionMeta ?? DEFAULT_SESSION_META),
+        provide(SessionUserInterfaceTeamLinksContext, options.teamLinks ?? []),
+        provide(UserInterfaceRunKindContext, options.runKind ?? 'session'),
+        provide(SessionUserInterfaceHostOverlaysContext, options.hostOverlays ?? []),
+        provide(SessionUserInterfaceWalkthroughLinkContext, options.walkthroughLink ?? null),
+        provide(SessionUserInterfaceHookFailuresContext, {
+            failures: options.hookFailures ?? [],
+            clearFailures: options.clearHookFailures ?? noop,
+        }),
+        provide(SessionUserInterfaceDataContext, dataValue),
+        provide(SessionUserInterfaceCallbacksContext, resolvedCallbacks),
+    ];
+    const result = render(wrapProviders(providers, ui));
+    return { ...result, setData: resolvedSetData, callbacks: resolvedCallbacks };
+}

package/lib/ui/tick-snapshot.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Error a `getPastState` call rejects with on a genuine read fault.
+ *
+ * `getPastState` (§12) answers with the rows its query reaches, so every
+ * *expected* miss — a tick at or above the head, an undone or reset tick, an
+ * out-of-range tick, an unknown team, a capability the surface may not read —
+ * is simply an absent row. It rejects with a `TickSnapshotError` only when the
+ * read itself fails: the host is not connected, the connection resets
+ * mid-flight, or the host reports an unexpected fault. This is deliberately
+ * distinct from `MutationError`, which is for fallible *writes*; a read never
+ * conflicts, is never rejected by a validator, and is never denied.
+ *
+ * ```typescript
+ * try {
+ *     const [past] = await callbacks.getPastState({ fromTick: day });
+ *     if (!past) {
+ *         // expected: that day is not reviewable (out of range, undone, reset)
+ *     }
+ * } catch (e) {
+ *     if (e instanceof TickSnapshotError) {
+ *         // transport/host fault — surface a retry affordance
+ *     }
+ * }
+ * ```
+ */
+export declare class TickSnapshotError extends Error {
+    constructor(message: string);
+}

package/lib/ui/tick-snapshot.js

@@ -0,0 +1,34 @@
+/**
+ * Error a `getPastState` call rejects with on a genuine read fault.
+ *
+ * `getPastState` (§12) answers with the rows its query reaches, so every
+ * *expected* miss — a tick at or above the head, an undone or reset tick, an
+ * out-of-range tick, an unknown team, a capability the surface may not read —
+ * is simply an absent row. It rejects with a `TickSnapshotError` only when the
+ * read itself fails: the host is not connected, the connection resets
+ * mid-flight, or the host reports an unexpected fault. This is deliberately
+ * distinct from `MutationError`, which is for fallible *writes*; a read never
+ * conflicts, is never rejected by a validator, and is never denied.
+ *
+ * ```typescript
+ * try {
+ *     const [past] = await callbacks.getPastState({ fromTick: day });
+ *     if (!past) {
+ *         // expected: that day is not reviewable (out of range, undone, reset)
+ *     }
+ * } catch (e) {
+ *     if (e instanceof TickSnapshotError) {
+ *         // transport/host fault — surface a retry affordance
+ *     }
+ * }
+ * ```
+ */
+export class TickSnapshotError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'TickSnapshotError';
+        // Restore the prototype chain so `instanceof` works after transpilation
+        // to ES5-targeted output.
+        Object.setPrototypeOf(this, TickSnapshotError.prototype);
+    }
+}