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

package/lib/ui/UserInterfaceDataContext.d.ts

@@ -0,0 +1,78 @@
+import type { ContextDeletePath, ContextUpdate } from '../build/context-merge.js';
+import type { MutationCommit } from './mutation-commit.js';
+/**
+ * What a write can do beyond merging fields.
+ */
+export type SetDataOptions = {
+    /**
+     * Paths to remove, applied after the patch merges. A merge cannot express
+     * deletion, so this is how an entry leaves a collection: removing the key
+     * rather than leaving a `null` behind that every reader has to skip and
+     * every snapshot carries for the rest of the session.
+     *
+     * ```typescript
+     * setData({}, { deletes: [`pinboard.Notes.${noteId}`] });
+     * ```
+     */
+    deletes?: ContextDeletePath[];
+};
+type UserInterfaceDataContextValue<T, A> = {
+    data: T;
+    /**
+     * The settings resources this surface declared in `settings`, keyed by
+     * identifier (§8). Fixed when play starts, and read-only.
+     */
+    settings: A;
+    /**
+     * The number of ticks this team has completed: `0` until the first tick
+     * commits, and `N - 1` while round N is played. `data` is the board the
+     * last completed tick left. Use it as the upper bound (exclusive)
+     * of a review scrubber: `getPastState({ fromTick: t })` returns a board for
+     * `0 <= t < completedTicks` and nothing at or above it. It decreases on undo,
+     * which is also the cue to evict any cached snapshots above the new head.
+     */
+    completedTicks: number;
+    /**
+     * Whether a round is being processed right now.
+     *
+     * Set while the host is running a tick, and cleared when it commits. A
+     * surface uses it to say what is happening: at a large cohort a lockstep
+     * tick takes long enough to notice, and a participant did not press the
+     * button, so an unexplained pause reads as the screen having broken.
+     *
+     * It does **not** mean writes are closed, and a host must not start
+     * refusing them on account of having sent it. What a mid-tick write then
+     * does depends on how the runtime serialises (SPECIFICATION.md §9.7): one
+     * that queues applies it after the tick commits, so the next tick consumes
+     * it; one using optimistic concurrency re-applies it against the tick's
+     * result, or reports a `conflict` once its own retries are spent. Either
+     * way the write is not dropped, but it belongs to the round *after* the
+     * one the participant was looking at.
+     *
+     * So disabling a submit control on this is about which round a decision
+     * counts for, not about losing it. Both choices are conformant.
+     */
+    isRoundProcessing: boolean;
+    /**
+     * Deep-merge an update into this UI's context: send only the fields you
+     * changed — object values merge recursively, arrays and scalars replace.
+     * Resolves once the host confirms the write; rejects with a
+     * `MutationError` when it is refused (by a validator, say) or loses a race
+     * with a tick.
+     *
+     * Await it. The local view merges the change the moment it is sent, so a
+     * write the host refuses leaves the participant looking at a decision the
+     * game never received, with nothing on screen to say so. `useMutationReporter`
+     * does the awaiting and hands you the failure to render. An unawaited write
+     * still compiles, and is a hazard rather than a convenience.
+     *
+     * Resolves with the tick the write committed into, when the host reports
+     * one. Compare it against the `completedTicks` you were rendering: a higher
+     * value means the round advanced first, so the write belongs to the round
+     * after the one the participant was looking at.
+     */
+    setData: (update: ContextUpdate<T>, options?: SetDataOptions) => Promise<MutationCommit>;
+};
+declare const UserInterfaceDataContext: import("react").Context<UserInterfaceDataContextValue<unknown, unknown> | undefined>;
+declare function useUserInterfaceData<T, A>(): UserInterfaceDataContextValue<T, A>;
+export { useUserInterfaceData, UserInterfaceDataContext };

package/lib/ui/UserInterfaceDataContext.js

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+// The actual context; we use `any` internally, but types are enforced in the hook
+const UserInterfaceDataContext = createContext(undefined);
+function useUserInterfaceData() {
+    const ctx = useContext(UserInterfaceDataContext);
+    if (!ctx) {
+        throw new Error('useUserInterfaceData must be used inside a UserInterfaceWrapper');
+    }
+    return ctx; // generic cast
+}
+export { useUserInterfaceData, UserInterfaceDataContext };

package/lib/ui/UserInterfaceLocaleContext.d.ts

@@ -0,0 +1,13 @@
+export type UserInterfaceLocale = {
+    locale: string;
+};
+export declare const UserInterfaceLocaleContext: import("react").Context<UserInterfaceLocale | undefined>;
+/**
+ * Hook to access the current locale in a user interface component.
+ * The locale is provided by the dev server based on the game's
+ * supported locales.
+ *
+ * @returns Current locale object with locale string
+ * @throws Error if used outside UserInterfaceWrapper
+ */
+export declare const useUserInterfaceLocale: () => UserInterfaceLocale;

package/lib/ui/UserInterfaceLocaleContext.js

@@ -0,0 +1,15 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useUserInterfaceLocale',
+    wrapperName: 'UserInterfaceWrapper',
+});
+export const UserInterfaceLocaleContext = Context;
+/**
+ * Hook to access the current locale in a user interface component.
+ * The locale is provided by the dev server based on the game's
+ * supported locales.
+ *
+ * @returns Current locale object with locale string
+ * @throws Error if used outside UserInterfaceWrapper
+ */
+export const useUserInterfaceLocale = useValue;

package/lib/ui/UserInterfaceOwnTeamContext.d.ts

@@ -0,0 +1,25 @@
+import type { TeamInfo } from './SessionUserInterfaceTeamsContext.js';
+export declare const UserInterfaceOwnTeamContext: import("react").Context<TeamInfo | null>;
+/**
+ * Hook returning the team whose surface this user interface is rendering.
+ *
+ * Distinct from {@link ./UserInterfaceTeamsContext.useUserInterfaceTeams}, which
+ * lists *every* team in the session with no marker of which one is the caller's.
+ *
+ * Before #332 the only route to own-team identity was
+ * `useUserInterfaceParticipant()?.teamId`, which #319 made `null` for an
+ * observing facilitator. A player UI that needed its own `teamId` — to split a
+ * `useUserInterfaceCrossTeamData()` result into 'mine' and 'theirs', to label a board, or to
+ * key a write — therefore worked when played and broke when observed. The host
+ * always knows which team's surface it mounted, so it now says so directly and
+ * the value is present for participants and observers alike.
+ *
+ * Returns `null` only when the host supplies neither an own team nor a
+ * participant to derive one from, which in practice means an observer on a host
+ * that predates this message. Guard for it if you target such a host; against
+ * the dev server and any runtime implementing the current protocol it is always
+ * populated on a player surface.
+ *
+ * @returns The caller's own team, or `null` when the host does not supply one
+ */
+export declare const useUserInterfaceOwnTeam: () => TeamInfo | null;

package/lib/ui/UserInterfaceOwnTeamContext.js

@@ -0,0 +1,26 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext(null);
+export const UserInterfaceOwnTeamContext = Context;
+/**
+ * Hook returning the team whose surface this user interface is rendering.
+ *
+ * Distinct from {@link ./UserInterfaceTeamsContext.useUserInterfaceTeams}, which
+ * lists *every* team in the session with no marker of which one is the caller's.
+ *
+ * Before #332 the only route to own-team identity was
+ * `useUserInterfaceParticipant()?.teamId`, which #319 made `null` for an
+ * observing facilitator. A player UI that needed its own `teamId` — to split a
+ * `useUserInterfaceCrossTeamData()` result into 'mine' and 'theirs', to label a board, or to
+ * key a write — therefore worked when played and broke when observed. The host
+ * always knows which team's surface it mounted, so it now says so directly and
+ * the value is present for participants and observers alike.
+ *
+ * Returns `null` only when the host supplies neither an own team nor a
+ * participant to derive one from, which in practice means an observer on a host
+ * that predates this message. Guard for it if you target such a host; against
+ * the dev server and any runtime implementing the current protocol it is always
+ * populated on a player surface.
+ *
+ * @returns The caller's own team, or `null` when the host does not supply one
+ */
+export const useUserInterfaceOwnTeam = useValue;

package/lib/ui/UserInterfaceOwnTeamJoinLinkContext.d.ts

@@ -0,0 +1,52 @@
+/**
+ * How to join *this* surface's team.
+ *
+ * Every player surface receives this, participants and observers alike, so a
+ * lobby screen or a tablet left on a table can draw a join code without the
+ * facilitator's surface being the only place the link exists.
+ *
+ * It is deliberately not the facilitator's `TeamLinks`. That type lists every
+ * team and carries `observeUrl`, and both belong to the session surface alone.
+ * This one names no team because there is nothing to name: it is the team whose
+ * surface is rendering.
+ *
+ * The session PIN is not here and never travels to a player surface. A join URL
+ * alone admits nobody to a session that requires one, so what a player screen
+ * can give away is bounded by whether the operator set a PIN.
+ */
+export type OwnTeamJoinLink = {
+    /**
+     * 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 is the host's business, exactly as it is for the
+     * facilitator's copy. It sends the form it wants used, and it may send a
+     * player surface a different form than it sends the facilitator. Encode
+     * *this* one in a QR code: the host chose the short form because a denser
+     * code is harder to scan across a table.
+     */
+    joinUrl: string;
+    /**
+     * An alternative for the one failure a game can help with: some networks
+     * block URL shorteners. On a facilitator surface the person who discovers
+     * that is standing right there; on a kiosk it is a walk-up with nobody to
+     * ask, so offer a way through rather than a dead code. Absent when the host
+     * has no distinct alternative.
+     *
+     * Show it on request rather than beside `joinUrl` with equal weight. Two
+     * URLs on a lobby card is worse than one.
+     */
+    fallbackJoinUrl?: string;
+};
+export declare const UserInterfaceOwnTeamJoinLinkContext: import("react").Context<OwnTeamJoinLink | null>;
+/**
+ * Hook returning how to join this surface's own team.
+ *
+ * Does not gate first paint, so it is `null` until the host delivers it. Render
+ * a placeholder for that first frame rather than assuming a link exists, and
+ * keep rendering one on a host that never sends it.
+ *
+ * @returns The own team's join link, or `null` before it arrives
+ */
+export declare const useUserInterfaceOwnTeamJoinLink: () => OwnTeamJoinLink | null;

package/lib/ui/UserInterfaceOwnTeamJoinLinkContext.js

@@ -0,0 +1,13 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext(null);
+export const UserInterfaceOwnTeamJoinLinkContext = Context;
+/**
+ * Hook returning how to join this surface's own team.
+ *
+ * Does not gate first paint, so it is `null` until the host delivers it. Render
+ * a placeholder for that first frame rather than assuming a link exists, and
+ * keep rendering one on a host that never sends it.
+ *
+ * @returns The own team's join link, or `null` before it arrives
+ */
+export const useUserInterfaceOwnTeamJoinLink = useValue;

package/lib/ui/UserInterfaceParticipantContext.d.ts

@@ -0,0 +1,16 @@
+import type { Participant } from '../build/callbacks.js';
+export declare const UserInterfaceParticipantContext: import("react").Context<Participant | null | undefined>;
+/**
+ * Hook to access the current participant in a user interface component.
+ * The participant is provided by the platform and contains information about
+ * the person currently viewing this UI.
+ *
+ * Returns `null` when the surface is being observed rather than played (see
+ * {@link ./UserInterfaceViewerRoleContext.useUserInterfaceViewerRole}): an observer is a
+ * facilitator watching the team without joining, so there is no caller
+ * identity. Guard for `null` before reading its fields.
+ *
+ * @returns Current participant object, or `null` when observing
+ * @throws Error if used outside UserInterfaceWrapper
+ */
+export declare const useUserInterfaceParticipant: () => Participant | null;

package/lib/ui/UserInterfaceParticipantContext.js

@@ -0,0 +1,24 @@
+import { createRequiredContext } from './internal/createContexts.js';
+// The provided value is `Participant | null`: a real identity for
+// a participant, `null` for an observer (who has no caller identity). The
+// `undefined` sentinel is reserved for "read outside the wrapper", so the hook
+// still throws on misuse while returning `null` legitimately under observation.
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useUserInterfaceParticipant',
+    wrapperName: 'UserInterfaceWrapper',
+});
+export const UserInterfaceParticipantContext = Context;
+/**
+ * Hook to access the current participant in a user interface component.
+ * The participant is provided by the platform and contains information about
+ * the person currently viewing this UI.
+ *
+ * Returns `null` when the surface is being observed rather than played (see
+ * {@link ./UserInterfaceViewerRoleContext.useUserInterfaceViewerRole}): an observer is a
+ * facilitator watching the team without joining, so there is no caller
+ * identity. Guard for `null` before reading its fields.
+ *
+ * @returns Current participant object, or `null` when observing
+ * @throws Error if used outside UserInterfaceWrapper
+ */
+export const useUserInterfaceParticipant = useValue;

package/lib/ui/UserInterfaceParticipantsContext.d.ts

@@ -0,0 +1,12 @@
+import type { Participant } from '../build/callbacks.js';
+export declare const UserInterfaceParticipantsContext: import("react").Context<Participant[]>;
+/**
+ * Hook to access the list of participants currently known for this team.
+ *
+ * Updates reactively as participants join or leave.
+ * The list includes the caller's own entry and every other participant on the
+ * same team.
+ *
+ * @returns Array of participants for this team
+ */
+export declare const useUserInterfaceParticipants: () => Participant[];

package/lib/ui/UserInterfaceParticipantsContext.js

@@ -0,0 +1,13 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext([]);
+export const UserInterfaceParticipantsContext = Context;
+/**
+ * Hook to access the list of participants currently known for this team.
+ *
+ * Updates reactively as participants join or leave.
+ * The list includes the caller's own entry and every other participant on the
+ * same team.
+ *
+ * @returns Array of participants for this team
+ */
+export const useUserInterfaceParticipants = useValue;

package/lib/ui/UserInterfaceRunKindContext.d.ts

@@ -0,0 +1,31 @@
+import type { RunKind } from '../build/signatures.js';
+export type { RunKind };
+export declare const UserInterfaceRunKindContext: import("react").Context<RunKind>;
+/**
+ * Hook returning whether this surface belongs to the game being played or to a
+ * walkthrough beside it (§5.7).
+ *
+ * A walkthrough is a solo run of something built for a group: one team, one
+ * participant, from tick 0, isolated from the session it sits beside. Use this
+ * to fill in the social context that is genuinely absent — rival teams on a
+ * leaderboard, teammates in a presence list — and to hide anything that would
+ * spoil the real run. Do not use it to change how the surface plays: the
+ * walkthrough exists to demonstrate the game, and one that behaves differently
+ * demonstrates a different game.
+ *
+ * The value the engine reads is the same one this returns, and neither changes
+ * for the life of the run, so a decision taken here cannot disagree with one
+ * taken in logic.
+ *
+ * Always present, defaulting to `'session'` so a host that predates
+ * walkthroughs (and never sends `setRunKind`) reads the case every existing
+ * game already behaves correctly on.
+ *
+ * ```tsx
+ * const runKind = useRunKind();
+ * const rivals = runKind === 'walkthrough' ? demonstrationRivals : data.market.rivals;
+ * ```
+ *
+ * @returns The kind of run this surface belongs to
+ */
+export declare const useRunKind: () => RunKind;

package/lib/ui/UserInterfaceRunKindContext.js

@@ -0,0 +1,31 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext('session');
+export const UserInterfaceRunKindContext = Context;
+/**
+ * Hook returning whether this surface belongs to the game being played or to a
+ * walkthrough beside it (§5.7).
+ *
+ * A walkthrough is a solo run of something built for a group: one team, one
+ * participant, from tick 0, isolated from the session it sits beside. Use this
+ * to fill in the social context that is genuinely absent — rival teams on a
+ * leaderboard, teammates in a presence list — and to hide anything that would
+ * spoil the real run. Do not use it to change how the surface plays: the
+ * walkthrough exists to demonstrate the game, and one that behaves differently
+ * demonstrates a different game.
+ *
+ * The value the engine reads is the same one this returns, and neither changes
+ * for the life of the run, so a decision taken here cannot disagree with one
+ * taken in logic.
+ *
+ * Always present, defaulting to `'session'` so a host that predates
+ * walkthroughs (and never sends `setRunKind`) reads the case every existing
+ * game already behaves correctly on.
+ *
+ * ```tsx
+ * const runKind = useRunKind();
+ * const rivals = runKind === 'walkthrough' ? demonstrationRivals : data.market.rivals;
+ * ```
+ *
+ * @returns The kind of run this surface belongs to
+ */
+export const useRunKind = useValue;

package/lib/ui/UserInterfaceTeamsContext.d.ts

@@ -0,0 +1,12 @@
+import type { TeamInfo } from './SessionUserInterfaceTeamsContext.js';
+export declare const UserInterfaceTeamsContext: import("react").Context<TeamInfo[]>;
+/**
+ * Hook to access basic metadata about all teams in the session.
+ *
+ * Each entry contains the team's identifier and display name. This gives
+ * player UIs awareness of the broader session without exposing other teams'
+ * game state.
+ *
+ * @returns Array of team info objects
+ */
+export declare const useUserInterfaceTeams: () => TeamInfo[];

package/lib/ui/UserInterfaceTeamsContext.js

@@ -0,0 +1,13 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+const { Context, useValue } = createDefaultedContext([]);
+export const UserInterfaceTeamsContext = Context;
+/**
+ * Hook to access basic metadata about all teams in the session.
+ *
+ * Each entry contains the team's identifier and display name. This gives
+ * player UIs awareness of the broader session without exposing other teams'
+ * game state.
+ *
+ * @returns Array of team info objects
+ */
+export const useUserInterfaceTeams = useValue;

package/lib/ui/UserInterfaceThemeContext.d.ts

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

package/lib/ui/UserInterfaceThemeContext.js

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

package/lib/ui/UserInterfaceThemePreferenceContext.d.ts

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

package/lib/ui/UserInterfaceThemePreferenceContext.js

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

package/lib/ui/UserInterfaceTimerContext.d.ts

@@ -0,0 +1,10 @@
+import type { TimerState } from '../build/timer.js';
+export declare const UserInterfaceTimerContext: import("react").Context<TimerState>;
+/**
+ * Hook to access the host's automatic tick timer state from inside a user
+ * interface component. Always returns a value — when `enabled` is false,
+ * no countdown should be displayed.
+ *
+ * @returns Current timer snapshot
+ */
+export declare const useUserInterfaceTimer: () => TimerState;

package/lib/ui/UserInterfaceTimerContext.js

@@ -0,0 +1,12 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+import { DEFAULT_SURFACE_TIMER } from './internal/surface-timer.js';
+const { Context, useValue } = createDefaultedContext(DEFAULT_SURFACE_TIMER);
+export const UserInterfaceTimerContext = Context;
+/**
+ * Hook to access the host's automatic tick timer state from inside a user
+ * interface component. Always returns a value — when `enabled` is false,
+ * no countdown should be displayed.
+ *
+ * @returns Current timer snapshot
+ */
+export const useUserInterfaceTimer = useValue;

package/lib/ui/UserInterfaceValidationContext.d.ts

@@ -0,0 +1,25 @@
+import type { ValidationRejection } from '../build/validators.js';
+/**
+ * Value exposed to consumers of {@link useUserInterfaceValidationRejections}.
+ *
+ * `rejections` is the list of `{ validatorIdentifier, message }` records from
+ * the most recent UI mutation the host gated as invalid. The runtime returns
+ * every rejection on a single submission (form-style, not short-circuit), so
+ * consumers always render the full list rather than a single message.
+ *
+ * `clearRejections` empties the buffer — call it after rendering the messages
+ * (e.g. when the user dismisses a toast, or when the form value changes).
+ */
+export interface UserInterfaceValidationContextValue {
+    rejections: ValidationRejection[];
+    clearRejections: () => void;
+}
+export declare const UserInterfaceValidationContext: import("react").Context<UserInterfaceValidationContextValue | undefined>;
+/**
+ * Subscribe to validator rejections from the host. Rejections are surfaced
+ * when a UI-submitted mutation (via `setData`) violates one or more
+ * validators declared in the game (§15 of the SDK specification). They are
+ * delivered as a single batch per submission; the runtime collects every
+ * failing validator's verdict and returns them together.
+ */
+export declare const useUserInterfaceValidationRejections: () => UserInterfaceValidationContextValue;

package/lib/ui/UserInterfaceValidationContext.js

@@ -0,0 +1,14 @@
+import { createRequiredContext } from './internal/createContexts.js';
+const { Context, useValue } = createRequiredContext({
+    hookName: 'useUserInterfaceValidationRejections',
+    wrapperName: 'UserInterfaceWrapper',
+});
+export const UserInterfaceValidationContext = Context;
+/**
+ * Subscribe to validator rejections from the host. Rejections are surfaced
+ * when a UI-submitted mutation (via `setData`) violates one or more
+ * validators declared in the game (§15 of the SDK specification). They are
+ * delivered as a single batch per submission; the runtime collects every
+ * failing validator's verdict and returns them together.
+ */
+export const useUserInterfaceValidationRejections = useValue;

package/lib/ui/UserInterfaceViewerRoleContext.d.ts

@@ -0,0 +1,14 @@
+import type { ViewerRole } from '../build/signatures.js';
+export type { ViewerRole };
+export declare const UserInterfaceViewerRoleContext: import("react").Context<ViewerRole>;
+/**
+ * Hook returning whether the current viewer is a `'participant'` or an
+ * `'observer'`. Use it to adapt a player or shell UI for observation — for
+ * example to show a debrief overlay, reveal otherwise-hidden state, or gate a
+ * genuinely read-only view. When it returns `'observer'`,
+ * {@link ./UserInterfaceParticipantContext.useUserInterfaceParticipant}
+ * returns `null`.
+ *
+ * @returns The current viewer role
+ */
+export declare const useUserInterfaceViewerRole: () => ViewerRole;

package/lib/ui/UserInterfaceViewerRoleContext.js

@@ -0,0 +1,17 @@
+import { createDefaultedContext } from './internal/createContexts.js';
+// Always present, defaulting to 'participant' so a host that never sends
+// `setViewerRole` reads the safe common case. Delivered to player and shell
+// user interfaces only; the facilitator surfaces are never observed.
+const { Context, useValue } = createDefaultedContext('participant');
+export const UserInterfaceViewerRoleContext = Context;
+/**
+ * Hook returning whether the current viewer is a `'participant'` or an
+ * `'observer'`. Use it to adapt a player or shell UI for observation — for
+ * example to show a debrief overlay, reveal otherwise-hidden state, or gate a
+ * genuinely read-only view. When it returns `'observer'`,
+ * {@link ./UserInterfaceParticipantContext.useUserInterfaceParticipant}
+ * returns `null`.
+ *
+ * @returns The current viewer role
+ */
+export const useUserInterfaceViewerRole = useValue;

package/lib/ui/UserInterfaceWrapper.d.ts

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