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

package/lib/ui/PresentationWrapper.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo, useState } from 'react';
+import { useDocumentAttributes } from './internal/document-attributes.js';
+import { SurfaceGate } from './internal/SurfaceGate.js';
+import { SurfaceScope } from './internal/SurfaceScope.js';
+import { useTypedPastState } from './internal/useTypedPastState.js';
+import { PresentationContext, } from './PresentationContext.js';
+import { useHostChannel } from './useHostChannel.js';
+/**
+ * The session, or the news that there is none, gates first paint like the
+ * rest: a deck that painted before knowing would flash its 'no session yet'
+ * placeholders at a room that is mid-game.
+ */
+const REQUIRED_MESSAGES = [
+    'setPresentation',
+    'setSettings',
+    'setTheme',
+    'setLocale',
+    'setAssetUrls',
+];
+/**
+ * Wrap a presentation bundle (§6.15). Read-only: there is nothing here to
+ * write with, and the host would refuse it if there were.
+ */
+export function PresentationWrapper({ children, fallback = _jsx("div", { children: "Loading..." }), targetWindow = window.parent, }) {
+    const [game, setGame] = useState(undefined);
+    const [session, setSession] = useState(null);
+    const [settings, setSettings] = useState(undefined);
+    const [theme, setTheme] = useState(undefined);
+    const [locale, setLocale] = useState(undefined);
+    const { isInitialized, expectedParentOrigin, getPastState: getPastStateRaw, getAssetUrl, assetUrls, sessionKey, } = useHostChannel({
+        targetWindow,
+        label: 'PresentationWrapper',
+        requiredMessages: REQUIRED_MESSAGES,
+        onMessage: (msg, { markReceived }) => {
+            if (msg.type === 'setPresentation') {
+                setGame(msg.payload.game);
+                setSession(msg.payload.session);
+                markReceived('setPresentation');
+            }
+            else if (msg.type === 'setSettings') {
+                setSettings(msg.payload);
+                markReceived('setSettings');
+            }
+            else if (msg.type === 'setTheme') {
+                setTheme(msg.payload);
+                markReceived('setTheme');
+            }
+            else if (msg.type === 'setLocale') {
+                setLocale(msg.payload);
+                markReceived('setLocale');
+            }
+        },
+    });
+    useDocumentAttributes(locale?.locale, theme?.mode);
+    const hasSession = session !== null;
+    const guardedRaw = useCallback((query) => hasSession
+        ? getPastStateRaw(query)
+        : Promise.reject(new Error('There is no session, so there are no past rounds to read')), [hasSession, getPastStateRaw]);
+    const getPastState = useTypedPastState(guardedRaw);
+    const value = useMemo(() => game && theme && locale
+        ? {
+            game,
+            session: session,
+            settings: settings ?? {},
+            theme,
+            locale,
+            getPastState,
+            getAssetUrl,
+        }
+        : undefined, [game, session, settings, theme, locale, getPastState, getAssetUrl]);
+    const storageScope = useMemo(() => ({
+        sessionKey,
+        surface: 'presentation',
+        viewer: 'facilitator',
+    }), [sessionKey]);
+    return (_jsx(SurfaceGate, { expectedParentOrigin: expectedParentOrigin, ready: isInitialized && value !== undefined, fallback: fallback, children: _jsx(SurfaceScope, { storage: storageScope, assetUrls: assetUrls, getAssetUrl: getAssetUrl, locale: locale?.locale, getPastState: getPastState, children: _jsx(PresentationContext.Provider, { value: value, children: children }) }) }));
+}

package/lib/ui/SessionUserInterfaceCallbacksContext.d.ts

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

package/lib/ui/SessionUserInterfaceCallbacksContext.js

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

package/lib/ui/SessionUserInterfaceDataContext.d.ts

@@ -0,0 +1,103 @@
+import type { ContextUpdate } from '../build/context-merge.js';
+import type { TimerState } from '../build/timer.js';
+import type { SetDataOptions } from './UserInterfaceDataContext.js';
+/**
+ * Session-level data context for session user interfaces.
+ *
+ * Unlike the player data context (which holds a single team's context),
+ * this holds `SessionData`: the shared store once, and every team's own
+ * context keyed by teamId.
+ */
+export type TeamState<TTeamContext = Record<string, unknown>> = {
+    /**
+     * This team's own context, projected onto the capabilities this surface
+     * declared in `reads` and `writes`. Team and private scope only: shared
+     * capabilities are in `SessionData.shared`, once.
+     */
+    context: TTeamContext;
+    /** The number of ticks this team has completed: the same count a player surface reads as `completedTicks`. */
+    completedTicks: number;
+    /**
+     * Timer state for this team: the same `TimerState` a player surface reads
+     * from `useUserInterfaceTimer()`.
+     */
+    timer: TimerState;
+    /**
+     * Monotonic version of this team's state, incremented by the host on every
+     * delivery. The wrapper reads it to detect an update it never received and
+     * ask for a fresh snapshot.
+     *
+     * Required, so the wrapper always has a baseline to compare a delta
+     * against. It was optional briefly, which bought one branch that adopted a
+     * delta unconditionally when no baseline existed: silent last-write-wins,
+     * and the only place in the delta design that resolved a conflict by
+     * guessing. A surface never reads this field; `makeTeamState` exists so a
+     * test fixture need not think about it.
+     */
+    revision: number;
+};
+export type SharedState<TSharedContext = Record<string, unknown>> = {
+    /**
+     * The session's shared store, projected onto the shared-scope capabilities
+     * this surface declared in `reads` and `writes`. One value per capability,
+     * however many teams there are, and present when there are none.
+     */
+    context: TSharedContext;
+    /**
+     * Monotonic version of the shared state, incremented by the host on every
+     * delivery, read by the wrapper exactly as it reads `TeamState.revision`.
+     */
+    revision: number;
+};
+/**
+ * Everything a session surface is shown of the session's state.
+ *
+ * Type it with the generated `SessionData` in the surface's `types.ts`, which
+ * fills both parameters from the surface's declarations.
+ */
+export type SessionData<TTeamContext = Record<string, unknown>, TSharedContext = Record<string, unknown>> = {
+    /** The shared store, once for the session. */
+    shared: SharedState<TSharedContext>;
+    /** Per-team state keyed by teamId (e.g. "team-1") */
+    teams: Record<string, TeamState<TTeamContext>>;
+};
+type SessionUserInterfaceDataContextValue<T extends SessionData<object, object>, A, S extends Record<string, unknown> = Record<string, unknown>, W extends Record<string, unknown> = Record<string, unknown>> = {
+    sessionData: T;
+    /** The settings resources this surface declared, keyed by identifier (§8). */
+    settings: A;
+    /**
+     * Write context data. The two-argument form deep-merges into one team's
+     * context (send only the fields you changed — object values merge
+     * recursively, arrays and scalars replace). The one-argument form writes
+     * shared-scope capabilities session-wide: the host fans the value out to
+     * every team atomically, and only capabilities this UI declares in
+     * `writes` are accepted. Type the shared form with the generated
+     * `SharedWrites` as `S`, and the team form with the generated `TeamWrites`
+     * as `W`, so a team write naming a shared capability fails to compile
+     * rather than being refused at run time.
+     *
+     * Both forms take `deletes`, paths removed after the update merges, as a
+     * player surface's `setData` does. A team form's delete must name a
+     * team-scope capability this UI declares in `writes`, and a shared form's
+     * a shared one; anything else is refused.
+     *
+     * ```typescript
+     * setData(teamId, {}, { deletes: [['pinboard', 'Notes', noteId]] });
+     * setData({}, { deletes: ['market.Offers.o-17'] });
+     * ```
+     */
+    setData: {
+        (teamId: string, update: ContextUpdate<W>, options?: SetDataOptions): Promise<void>;
+        (update: ContextUpdate<S>, options?: SetDataOptions): Promise<void>;
+    };
+};
+declare const SessionUserInterfaceDataContext: import("react").Context<SessionUserInterfaceDataContextValue<SessionData<object, object>, unknown, Record<string, unknown>, Record<string, unknown>> | undefined>;
+/**
+ * The session's data and the session surface's `setData`.
+ *
+ * Type it with the generated types in the surface's `types.ts`:
+ * `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()`.
+ * Each parameter may be left at its default, which accepts any capability.
+ */
+declare function useSessionUserInterfaceData<T extends SessionData<object, object> = SessionData, A = unknown, S extends Record<string, unknown> = Record<string, unknown>, W extends Record<string, unknown> = Record<string, unknown>>(): SessionUserInterfaceDataContextValue<T, A, S, W>;
+export { useSessionUserInterfaceData, SessionUserInterfaceDataContext };

package/lib/ui/SessionUserInterfaceDataContext.js

@@ -0,0 +1,17 @@
+import { createContext, useContext } from 'react';
+const SessionUserInterfaceDataContext = createContext(undefined);
+/**
+ * The session's data and the session surface's `setData`.
+ *
+ * Type it with the generated types in the surface's `types.ts`:
+ * `useSessionUserInterfaceData<SessionData, Settings, SharedWrites, TeamWrites>()`.
+ * Each parameter may be left at its default, which accepts any capability.
+ */
+function useSessionUserInterfaceData() {
+    const ctx = useContext(SessionUserInterfaceDataContext);
+    if (!ctx) {
+        throw new Error('useSessionUserInterfaceData must be used inside a SessionUserInterfaceWrapper');
+    }
+    return ctx;
+}
+export { useSessionUserInterfaceData, SessionUserInterfaceDataContext };

package/lib/ui/SessionUserInterfaceHookFailuresContext.d.ts

@@ -0,0 +1,44 @@
+import type { HookSignal } from '../build/resource-schema.js';
+/**
+ * A hook chain that threw, reported to the session surface after the fact.
+ *
+ * Hooks fire *after* the runtime applies the lifecycle change, so a throwing
+ * hook never prevents the change: a participant that moved has moved, and the
+ * mutation that moved them has already settled `ok: true`. What failed is a
+ * consequence, not the mutation, which is why this arrives as its own push
+ * rather than as a failed `mutation:response`.
+ *
+ * Whether the session is left inconsistent depends on what the hook was doing.
+ * A hook seeding per-participant state is the usual case, and the usual
+ * remedy is to tell the facilitator that this team's state may be stale rather
+ * than to retry anything.
+ */
+export interface SessionHookFailure {
+    /** The signal whose chain threw, e.g. `participantMove`. */
+    signal: HookSignal;
+    /** The team whose context the failing chain was running against. */
+    teamId: string;
+    /** The error the hook threw, as the host reported it. */
+    message: string;
+}
+/**
+ * Value exposed to consumers of {@link useSessionUserInterfaceHookFailures}.
+ *
+ * `failures` accumulates until cleared, because a facilitator who looked away
+ * should still find out that something went wrong. `clearFailures` empties the
+ * buffer once they have been shown.
+ */
+export interface SessionUserInterfaceHookFailuresValue {
+    failures: SessionHookFailure[];
+    clearFailures: () => void;
+}
+export declare const SessionUserInterfaceHookFailuresContext: import("react").Context<SessionUserInterfaceHookFailuresValue | undefined>;
+/**
+ * Subscribe to hook chains that threw anywhere in the session.
+ *
+ * The host also surfaces these to the operator in its own chrome, so a surface
+ * that renders nothing is not hiding them. Render them anyway when your game's
+ * hooks carry state the surface displays: the facilitator who caused the
+ * failure is looking at your surface, not the host's.
+ */
+export declare const useSessionUserInterfaceHookFailures: () => SessionUserInterfaceHookFailuresValue;

package/lib/ui/SessionUserInterfaceHookFailuresContext.js

@@ -0,0 +1,15 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSessionUserInterfaceHookFailures',
+    wrapperName: 'SessionUserInterfaceWrapper',
+});
+export const SessionUserInterfaceHookFailuresContext = Context;
+/**
+ * Subscribe to hook chains that threw anywhere in the session.
+ *
+ * The host also surfaces these to the operator in its own chrome, so a surface
+ * that renders nothing is not hiding them. Render them anyway when your game's
+ * hooks carry state the surface displays: the facilitator who caused the
+ * failure is looking at your surface, not the host's.
+ */
+export const useSessionUserInterfaceHookFailures = useValue;

package/lib/ui/SessionUserInterfaceHostOverlaysContext.d.ts

@@ -0,0 +1,23 @@
+import type { HostOverlay } from '../build/callbacks.js';
+export type { HostOverlay };
+export declare const SessionUserInterfaceHostOverlaysContext: import("react").Context<HostOverlay[]>;
+/**
+ * Hook listing the host overlays this host offers for this session.
+ *
+ * Render a control only for an overlay in this list. An empty list is the
+ * honest default before the host has answered, and also the correct answer for
+ * a host that delegates none of them, so a surface that renders a guide button
+ * unconditionally shows a facilitator a button that cannot work.
+ *
+ * ```tsx
+ * const overlays = useSessionUserInterfaceHostOverlays();
+ * const { openHostOverlay } = useSessionUserInterfaceCallbacks();
+ *
+ * {overlays.includes('facilitator-guide') && (
+ *     <Button onClick={() => void openHostOverlay('facilitator-guide')}>Guide</Button>
+ * )}
+ * ```
+ *
+ * @returns The overlays this host offers, empty until the host answers
+ */
+export declare const useSessionUserInterfaceHostOverlays: () => HostOverlay[];

package/lib/ui/SessionUserInterfaceHostOverlaysContext.js

@@ -0,0 +1,23 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext([]);
+export const SessionUserInterfaceHostOverlaysContext = Context;
+/**
+ * Hook listing the host overlays this host offers for this session.
+ *
+ * Render a control only for an overlay in this list. An empty list is the
+ * honest default before the host has answered, and also the correct answer for
+ * a host that delegates none of them, so a surface that renders a guide button
+ * unconditionally shows a facilitator a button that cannot work.
+ *
+ * ```tsx
+ * const overlays = useSessionUserInterfaceHostOverlays();
+ * const { openHostOverlay } = useSessionUserInterfaceCallbacks();
+ *
+ * {overlays.includes('facilitator-guide') && (
+ *     <Button onClick={() => void openHostOverlay('facilitator-guide')}>Guide</Button>
+ * )}
+ * ```
+ *
+ * @returns The overlays this host offers, empty until the host answers
+ */
+export const useSessionUserInterfaceHostOverlays = useValue;

package/lib/ui/SessionUserInterfaceLocaleContext.d.ts

@@ -0,0 +1,11 @@
+export type SessionUserInterfaceLocale = {
+    locale: string;
+};
+export declare const SessionUserInterfaceLocaleContext: import("react").Context<SessionUserInterfaceLocale | undefined>;
+/**
+ * Hook to access the current locale in a manage session user interface component.
+ *
+ * @returns Current locale object with locale string
+ * @throws Error if used outside SessionUserInterfaceWrapper
+ */
+export declare const useSessionUserInterfaceLocale: () => SessionUserInterfaceLocale;

package/lib/ui/SessionUserInterfaceLocaleContext.js

@@ -0,0 +1,13 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSessionUserInterfaceLocale',
+    wrapperName: 'SessionUserInterfaceWrapper',
+});
+export const SessionUserInterfaceLocaleContext = Context;
+/**
+ * Hook to access the current locale in a manage session user interface component.
+ *
+ * @returns Current locale object with locale string
+ * @throws Error if used outside SessionUserInterfaceWrapper
+ */
+export const useSessionUserInterfaceLocale = useValue;

package/lib/ui/SessionUserInterfaceMetaContext.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The session's identity and lifecycle state, pushed on connect and again
+ * whenever any of it changes.
+ */
+export type SessionMeta = {
+    sessionId: string;
+    /** Operator-facing session name. */
+    name: string;
+    /**
+     * The session is frozen and the host will refuse every mutation.
+     *
+     * A courtesy signal, not a security boundary: the host enforces the freeze
+     * itself on every write. Use it to disable controls and explain why, rather
+     * than offering affordances that will be denied.
+     */
+    readOnly: boolean;
+    /**
+     * Whether the session's waiting room is open. This is the read side of
+     * `setWaitingRoom`. The host usually renders its own waiting-room control
+     * too, so render from this value rather than from an optimistic local one.
+     */
+    waitingRoomOpen: boolean;
+    /**
+     * The code participants enter to join, or `null` when joining needs none
+     * or the runtime does not show one. How joining is secured is the
+     * runtime's choice, so this need not be a PIN, and a game must render it
+     * as an opaque string. Never embedded in a join URL: a facilitator reads
+     * the two out separately.
+     */
+    joinPin: string | null;
+};
+export declare const SessionUserInterfaceMetaContext: import("react").Context<SessionMeta | undefined>;
+/**
+ * Hook to access the session's identity and lifecycle state.
+ *
+ * @returns The current {@link SessionMeta}
+ * @throws Error if used outside SessionUserInterfaceWrapper
+ */
+export declare const useSessionUserInterfaceMeta: () => SessionMeta;

package/lib/ui/SessionUserInterfaceMetaContext.js

@@ -0,0 +1,13 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSessionUserInterfaceMeta',
+    wrapperName: 'SessionUserInterfaceWrapper',
+});
+export const SessionUserInterfaceMetaContext = Context;
+/**
+ * Hook to access the session's identity and lifecycle state.
+ *
+ * @returns The current {@link SessionMeta}
+ * @throws Error if used outside SessionUserInterfaceWrapper
+ */
+export const useSessionUserInterfaceMeta = useValue;

package/lib/ui/SessionUserInterfaceParticipantsContext.d.ts

@@ -0,0 +1,12 @@
+import type { Participant } from '../build/callbacks.js';
+export declare const SessionUserInterfaceParticipantsContext: import("react").Context<Participant[] | undefined>;
+/**
+ * Hook to access all participants across all teams in the session.
+ *
+ * Each participant has a `teamId` field for grouping by team. Updates
+ * reactively as participants join or leave.
+ *
+ * @returns Array of all participants across all teams
+ * @throws Error if used outside SessionUserInterfaceWrapper
+ */
+export declare const useSessionUserInterfaceParticipants: () => Participant[];

package/lib/ui/SessionUserInterfaceParticipantsContext.js

@@ -0,0 +1,16 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useSessionUserInterfaceParticipants',
+    wrapperName: 'SessionUserInterfaceWrapper',
+});
+export const SessionUserInterfaceParticipantsContext = Context;
+/**
+ * Hook to access all participants across all teams in the session.
+ *
+ * Each participant has a `teamId` field for grouping by team. Updates
+ * reactively as participants join or leave.
+ *
+ * @returns Array of all participants across all teams
+ * @throws Error if used outside SessionUserInterfaceWrapper
+ */
+export const useSessionUserInterfaceParticipants = useValue;

package/lib/ui/SessionUserInterfaceTeamConfigurationContext.d.ts

@@ -0,0 +1,53 @@
+import type { SessionMode } from '../build/signatures.js';
+/**
+ * How teams work in this session: the interaction mode, and the bounds the host
+ * will hold the surface to.
+ *
+ * Every bound here is for rendering honest affordances, not for enforcement.
+ * The host checks all of them itself on every mutation, so a surface that
+ * disables its own 'add team' control at the maximum is being polite, not
+ * authoritative, and must still handle a denial.
+ */
+export type TeamConfiguration = {
+    mode: SessionMode;
+    /**
+     * Minimum team count the game is designed for. Enforced by the host at
+     * session creation only, and advisory thereafter, so treat it as guidance
+     * to display rather than a rule to block on.
+     */
+    min?: number;
+    /**
+     * The **effective** maximum team count, already resolved by the host as the
+     * lower of the game's declared maximum and the platform's own ceiling. It
+     * is not the number the manifest declared, and a surface that sourced the
+     * manifest value instead would disable its controls at the wrong point.
+     */
+    max: number;
+    /**
+     * Per-team participant guidance. Advisory: the host does not currently
+     * bound joining or participant moves on these, so use them for guidance
+     * text rather than to block a move.
+     */
+    perTeam?: {
+        minParticipants?: number;
+        maxParticipants?: number;
+    };
+};
+/**
+ * The value a surface holds before the host has sent `setTeamConfiguration`.
+ *
+ * `max: 0` is deliberately a value no game could mean, so a surface reading it
+ * is reading a bound that never applied. It should be unreachable in practice:
+ * `setTeamConfiguration` gates a session surface's first paint (#365), so the
+ * host has always spoken before any component renders. It survives as the
+ * context's default because a defaulted context needs one, and because a test
+ * rendering this provider directly should not silently inherit real bounds.
+ */
+export declare const DEFAULT_TEAM_CONFIGURATION: TeamConfiguration;
+export declare const SessionUserInterfaceTeamConfigurationContext: import("react").Context<TeamConfiguration>;
+/**
+ * Hook to access the session's interaction mode and team bounds.
+ *
+ * @returns The current {@link TeamConfiguration}
+ */
+export declare const useSessionUserInterfaceTeamConfiguration: () => TeamConfiguration;

package/lib/ui/SessionUserInterfaceTeamConfigurationContext.js

@@ -0,0 +1,23 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+/**
+ * The value a surface holds before the host has sent `setTeamConfiguration`.
+ *
+ * `max: 0` is deliberately a value no game could mean, so a surface reading it
+ * is reading a bound that never applied. It should be unreachable in practice:
+ * `setTeamConfiguration` gates a session surface's first paint (#365), so the
+ * host has always spoken before any component renders. It survives as the
+ * context's default because a defaulted context needs one, and because a test
+ * rendering this provider directly should not silently inherit real bounds.
+ */
+export const DEFAULT_TEAM_CONFIGURATION = {
+    mode: 'independent',
+    max: 0,
+};
+const { Context, useValue } = createDefaultedContext(DEFAULT_TEAM_CONFIGURATION);
+export const SessionUserInterfaceTeamConfigurationContext = Context;
+/**
+ * Hook to access the session's interaction mode and team bounds.
+ *
+ * @returns The current {@link TeamConfiguration}
+ */
+export const useSessionUserInterfaceTeamConfiguration = useValue;

package/lib/ui/SessionUserInterfaceTeamLinksContext.d.ts

@@ -0,0 +1,56 @@
+/**
+ * A team's facilitator-only links: how participants join it, and how to watch
+ * it without joining.
+ *
+ * These are facilitator-only. The host sends them to the session surface and to
+ * nothing else, because a join URL together with the session PIN is joinable
+ * capability. That is why they travel on their own message rather than riding
+ * on `TeamInfo`, which player surfaces also receive.
+ *
+ * There is no session-level entry. Every one names a team.
+ */
+export type TeamLinks = {
+    teamId: string;
+    /**
+     * The join URL to render.
+     *
+     * A host may have several forms of the same link — a shortened one, a
+     * longer one on another domain, a canonical one carrying opaque ids — and
+     * choosing between them, including deciding a short link has expired, is
+     * the host's business. It sends the form it wants used, so a game never has
+     * to know which form it received. Encode *this* one in a QR code: the host
+     * chose the short form because a denser code is harder to scan across a
+     * room.
+     */
+    joinUrl: string;
+    /**
+     * An alternative for the one failure a game can help with: some networks
+     * block URL shorteners, and the facilitator who discovers that is standing
+     * in front of your surface. Absent when the host has no distinct
+     * alternative.
+     *
+     * Show it on request rather than beside `joinUrl` with equal weight. Two
+     * URLs on a projector is worse than one.
+     */
+    fallbackJoinUrl?: string;
+    /**
+     * Opens the team's player surface as an observer: a facilitator watching
+     * without joining, with no participant identity and no presence.
+     *
+     * Always present. Observing is required of every compliant host, because a
+     * facilitator has to be able to see what a team sees and a session UI that
+     * owns the canvas leaves nowhere else to put that. It admits nobody to the
+     * session, so unlike a join URL it is tooling rather than capability.
+     */
+    observeUrl: string;
+};
+export declare const SessionUserInterfaceTeamLinksContext: import("react").Context<TeamLinks[]>;
+/**
+ * Hook to access each team's join and observe links.
+ *
+ * Does not gate first paint, so the list is empty until the host delivers it.
+ * Render a placeholder for that first frame rather than assuming a link exists.
+ *
+ * @returns One {@link TeamLinks} per team, or an empty array before they arrive
+ */
+export declare const useSessionUserInterfaceTeamLinks: () => TeamLinks[];

package/lib/ui/SessionUserInterfaceTeamLinksContext.js

@@ -0,0 +1,12 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext([]);
+export const SessionUserInterfaceTeamLinksContext = Context;
+/**
+ * Hook to access each team's join and observe links.
+ *
+ * Does not gate first paint, so the list is empty until the host delivers it.
+ * Render a placeholder for that first frame rather than assuming a link exists.
+ *
+ * @returns One {@link TeamLinks} per team, or an empty array before they arrive
+ */
+export const useSessionUserInterfaceTeamLinks = useValue;

package/lib/ui/SessionUserInterfaceTeamsContext.d.ts

@@ -0,0 +1,13 @@
+import type { TeamInfo } from '../build/callbacks.js';
+export type { TeamInfo };
+export declare const SessionUserInterfaceTeamsContext: import("react").Context<TeamInfo[]>;
+/**
+ * Hook to access the session's teams, sorted by stable index.
+ *
+ * The interaction mode and team bounds live in
+ * `useSessionUserInterfaceTeamConfiguration()` rather than here, so there is
+ * one home for how teams work and one for which teams exist.
+ *
+ * @returns Array of {@link TeamInfo}
+ */
+export declare const useSessionUserInterfaceTeams: () => TeamInfo[];

package/lib/ui/SessionUserInterfaceTeamsContext.js

@@ -0,0 +1,13 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext([]);
+export const SessionUserInterfaceTeamsContext = Context;
+/**
+ * Hook to access the session's teams, sorted by stable index.
+ *
+ * The interaction mode and team bounds live in
+ * `useSessionUserInterfaceTeamConfiguration()` rather than here, so there is
+ * one home for how teams work and one for which teams exist.
+ *
+ * @returns Array of {@link TeamInfo}
+ */
+export const useSessionUserInterfaceTeams = useValue;

package/lib/ui/SessionUserInterfaceThemeContext.d.ts

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

package/lib/ui/SessionUserInterfaceThemeContext.js

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

package/lib/ui/SessionUserInterfaceThemePreferenceContext.d.ts

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

package/lib/ui/SessionUserInterfaceThemePreferenceContext.js

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