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

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

@@ -0,0 +1,7 @@
+import { type MutableRefObject } from 'react';
+/**
+ * Mirror the latest render's `value` into a ref so a stable callback can read
+ * it synchronously without re-subscribing. The ref is updated on every render
+ * (not in an effect), so it is current the moment the callback runs.
+ */
+export declare function useLatestRef<T>(value: T): MutableRefObject<T>;

package/lib/ui/internal/useLatestRef.js

@@ -0,0 +1,11 @@
+import { useRef } from 'react';
+/**
+ * Mirror the latest render's `value` into a ref so a stable callback can read
+ * it synchronously without re-subscribing. The ref is updated on every render
+ * (not in an effect), so it is current the moment the callback runs.
+ */
+export function useLatestRef(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}

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

@@ -0,0 +1,19 @@
+import { type ContextDeletePath } from '../../build/context-merge.js';
+import type { MutationCommit } from '../mutation-commit.js';
+/**
+ * The optimistic record-merge shared by the participant and session
+ * wrappers. Mirrors the latest `value`, deep-merges an update into it
+ * synchronously (matching the host's §9.5 merge semantics, so a minimal
+ * nested patch never blanks untouched siblings locally), pushes the merged
+ * value into local state, and forwards only the update to `send` — the host
+ * applies it to its current context. Deletions are applied locally in the same
+ * order the host applies them, after the merge, so the optimistic view and the
+ * host's context agree about a removed key as well as a changed one. Each call
+ * sends its own delta;
+ * deltas are never accumulated across calls, so a rejected write is not
+ * resent inside later payloads. The returned callback's identity depends only
+ * on `send`.
+ */
+export declare function useOptimisticMerge<T extends Record<string, unknown>>(value: T, setValue: (next: T) => void, send: (update: Partial<T>, deletes?: ContextDeletePath[]) => Promise<MutationCommit>): (update: Partial<T>, options?: {
+    deletes?: ContextDeletePath[];
+}) => Promise<MutationCommit>;

package/lib/ui/internal/useOptimisticMerge.js

@@ -0,0 +1,28 @@
+import { useCallback } from 'react';
+import { applyContextUpdate } from '../../build/context-merge.js';
+import { useLatestRef } from './useLatestRef.js';
+/**
+ * The optimistic record-merge shared by the participant and session
+ * wrappers. Mirrors the latest `value`, deep-merges an update into it
+ * synchronously (matching the host's §9.5 merge semantics, so a minimal
+ * nested patch never blanks untouched siblings locally), pushes the merged
+ * value into local state, and forwards only the update to `send` — the host
+ * applies it to its current context. Deletions are applied locally in the same
+ * order the host applies them, after the merge, so the optimistic view and the
+ * host's context agree about a removed key as well as a changed one. Each call
+ * sends its own delta;
+ * deltas are never accumulated across calls, so a rejected write is not
+ * resent inside later payloads. The returned callback's identity depends only
+ * on `send`.
+ */
+export function useOptimisticMerge(value, setValue, send) {
+    const valueRef = useLatestRef(value);
+    return useCallback((update, options) => {
+        const merged = applyContextUpdate(valueRef.current, update, options?.deletes);
+        valueRef.current = merged;
+        setValue(merged);
+        return send(update, options?.deletes);
+    }, 
+    // valueRef is stable; setValue is a React state setter (stable).
+    [send, setValue, valueRef]);
+}

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

@@ -0,0 +1,52 @@
+import type { HostOverlay } from '../../build/callbacks.js';
+/**
+ * The timer/lifecycle control messages on the session channel. A structural
+ * subset of that iframe→host union, so the wrapper's typed `sendMutation`
+ * accepts it. Every one is awaitable.
+ */
+type SurfaceControlMessage = {
+    type: 'pauseTimer';
+    requestId?: string;
+    teamId?: string;
+} | {
+    type: 'resumeTimer';
+    requestId?: string;
+    teamId?: string;
+} | {
+    type: 'resetGame';
+    requestId?: string;
+    teamId?: string;
+} | {
+    type: 'undoTick';
+    requestId?: string;
+    teamId?: string;
+} | {
+    type: 'extendTick';
+    requestId?: string;
+    teamId?: string;
+    byMs: number;
+} | {
+    type: 'openHostOverlay';
+    requestId?: string;
+    overlay: HostOverlay;
+    target?: string;
+};
+interface SurfaceControlChannel {
+    sendMutation: (message: SurfaceControlMessage) => Promise<void>;
+}
+export interface SurfaceControls {
+    pauseTimer: (teamId?: string) => Promise<void>;
+    resumeTimer: (teamId?: string) => Promise<void>;
+    resetGame: (teamId?: string) => Promise<void>;
+    undoTick: (teamId?: string) => Promise<void>;
+    extendTick: (byMs: number, teamId?: string) => Promise<void>;
+    openHostOverlay: (overlay: HostOverlay, target?: string) => Promise<void>;
+}
+/**
+ * The pause/resume/reset/undo controls on the session wrapper. Each carries an
+ * optional `teamId`; omitting it applies the action to every team. Each control
+ * is independently memoised, so consumers' dependency arrays see stable
+ * identities.
+ */
+export declare function useSurfaceControls(channel: SurfaceControlChannel): SurfaceControls;
+export {};

package/lib/ui/internal/useSurfaceControls.js

@@ -0,0 +1,19 @@
+import { useCallback } from 'react';
+/**
+ * The pause/resume/reset/undo controls on the session wrapper. Each carries an
+ * optional `teamId`; omitting it applies the action to every team. Each control
+ * is independently memoised, so consumers' dependency arrays see stable
+ * identities.
+ */
+export function useSurfaceControls(channel) {
+    const { sendMutation } = channel;
+    const pauseTimer = useCallback((teamId) => sendMutation({ type: 'pauseTimer', teamId }), [sendMutation]);
+    const resumeTimer = useCallback((teamId) => sendMutation({ type: 'resumeTimer', teamId }), [sendMutation]);
+    const resetGame = useCallback((teamId) => sendMutation({ type: 'resetGame', teamId }), [sendMutation]);
+    const undoTick = useCallback((teamId) => sendMutation({ type: 'undoTick', teamId }), [sendMutation]);
+    // `byMs` leads: it is the argument every caller passes, where teamId is
+    // the one most omit.
+    const extendTick = useCallback((byMs, teamId) => sendMutation({ type: 'extendTick', byMs, teamId }), [sendMutation]);
+    const openHostOverlay = useCallback((overlay, target) => sendMutation({ type: 'openHostOverlay', overlay, target }), [sendMutation]);
+    return { pauseTimer, resumeTimer, resetGame, undoTick, extendTick, openHostOverlay };
+}

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

@@ -0,0 +1,17 @@
+import type { PastStateEntry, PastStateQuery } from '../../build/callbacks.js';
+type RawPastStateReader = (query: PastStateQuery<Record<string, unknown>>) => Promise<PastStateEntry<Record<string, unknown>>[]>;
+/**
+ * Re-expose the channel's untyped `getPastState` as the generic callback a
+ * surface declares, so `getPastState<Context>(query)` narrows both halves:
+ * each entry's `context`, and the `capabilityIds` the query may name.
+ *
+ * The channel is untyped because it does not know the game's `Context`; the
+ * cast is the one place that knowledge is reintroduced, and it is safe because
+ * the host projects onto the same declarations the type was generated from.
+ *
+ * One hook serves both surfaces. The player and session variants differ only
+ * in what `teams` defaults to, which the host resolves, so the signature is
+ * identical on both.
+ */
+export declare function useTypedPastState(raw: RawPastStateReader): <T = Record<string, unknown>>(query: PastStateQuery<T>) => Promise<PastStateEntry<T>[]>;
+export {};

package/lib/ui/internal/useTypedPastState.js

@@ -0,0 +1,17 @@
+import { useCallback } from 'react';
+/**
+ * Re-expose the channel's untyped `getPastState` as the generic callback a
+ * surface declares, so `getPastState<Context>(query)` narrows both halves:
+ * each entry's `context`, and the `capabilityIds` the query may name.
+ *
+ * The channel is untyped because it does not know the game's `Context`; the
+ * cast is the one place that knowledge is reintroduced, and it is safe because
+ * the host projects onto the same declarations the type was generated from.
+ *
+ * One hook serves both surfaces. The player and session variants differ only
+ * in what `teams` defaults to, which the host resolves, so the signature is
+ * identical on both.
+ */
+export function useTypedPastState(raw) {
+    return useCallback((query) => raw(query), [raw]);
+}

package/lib/ui/mutation-commit.d.ts

@@ -0,0 +1,32 @@
+/**
+ * What a committed mutation reports back.
+ *
+ * The surface holds the tick it was showing when the participant composed the
+ * write, and the host answers with the tick it committed into. When those
+ * differ the round advanced first, so the write landed in the round *after*
+ * the one on screen: not lost, but not the round the participant meant either.
+ *
+ * Only the committed tick crosses the boundary. The composed tick is the
+ * surface's own state, so it never has to be sent and the host is never asked
+ * to trust it.
+ *
+ * That is worth telling them about, and before this there was no way to know.
+ * Both serialisation strategies produce it — one queues the write past the
+ * tick, the other re-applies it against the tick's result — and neither said
+ * so (SPECIFICATION.md §9.5).
+ *
+ * Only the participant context write reports the pair; every other mutation
+ * resolves with `late: false` and no ticks.
+ */
+export type MutationCommit = {
+    /** The tick the write committed into, when the host reported one. */
+    committedAtTick?: number;
+    /** The tick the surface was showing when the write was composed. */
+    composedAtTick?: number;
+    /**
+     * True when the round advanced between composing the write and committing
+     * it, so the write counts for the next round rather than the one the
+     * participant was looking at.
+     */
+    late: boolean;
+};

package/lib/ui/mutation-commit.js

@@ -0,0 +1 @@
+export {};

package/lib/ui/mutation-outcome.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Typed outcomes for fallible UI state mutations.
+ *
+ * Mutating callbacks (`setData`, `updateSettings`, `requestTick`, `undoTick`,
+ * `resetGame`) return a promise that resolves once the operation has committed
+ * and rejects with a {@link MutationError} carrying a discriminated
+ * {@link MutationOutcome}. Games branch on `outcome.kind` to tell the
+ * participant what happened; `useMutationReporter` does this for them.
+ *
+ * A surface never retries a mutation on its own (SPECIFICATION.md §12.5.1). A
+ * `conflict` means the host has already retried and given up, so the most a
+ * surface does is offer the participant a 'Try again' control, which
+ * `useMutationReporter` provides as `failure.retry`.
+ */
+import type { ValidationRejection } from '../build/validators.js';
+/**
+ * The reason a mutation failed.
+ *
+ * - `conflict` — the write kept losing a race with a tick and the host, having
+ *   retried it itself, gave up. A person may try again; a surface MUST NOT
+ *   retry it automatically. The dev server serialises writes against ticks, so
+ *   it never emits this unless one is armed deliberately.
+ * - `superseded` — what the operation addressed has already moved on, because
+ *   somebody else did the same thing. Terminal, and not a failure: the caller
+ *   got the state they asked for. A double-pressed tick button is the archetype.
+ * - `validation-rejected` — a validator rejected the write; carries the same
+ *   rejections delivered to {@link useUserInterfaceValidationRejections}.
+ * - `denied` — the operation was not permitted (e.g. a write of a capability
+ *   the surface does not declare in `writes`).
+ * - `tick-failed` — the tick could not run (tick limit reached, game complete,
+ *   or the executor threw).
+ * - `error` — anything else unexpected.
+ */
+export type MutationOutcome = {
+    kind: 'conflict';
+    message?: string;
+} | {
+    kind: 'superseded';
+    message: string;
+    committedAtTick?: number;
+} | {
+    kind: 'validation-rejected';
+    rejections: ValidationRejection[];
+    message?: string;
+} | {
+    kind: 'denied';
+    message: string;
+} | {
+    kind: 'tick-failed';
+    message: string;
+} | {
+    kind: 'error';
+    message: string;
+};
+/** The message a {@link MutationError} carries for an outcome. */
+export declare function describeMutationOutcome(outcome: MutationOutcome): string;
+/**
+ * Error a fallible mutation promise rejects with. Inspect {@link outcome} (or
+ * the shorthand {@link kind}) to branch on the failure reason.
+ */
+export declare class MutationError extends Error {
+    readonly outcome: MutationOutcome;
+    constructor(outcome: MutationOutcome);
+    /** Shorthand for `outcome.kind`. */
+    get kind(): MutationOutcome['kind'];
+}

package/lib/ui/mutation-outcome.js

@@ -0,0 +1,49 @@
+/**
+ * Typed outcomes for fallible UI state mutations.
+ *
+ * Mutating callbacks (`setData`, `updateSettings`, `requestTick`, `undoTick`,
+ * `resetGame`) return a promise that resolves once the operation has committed
+ * and rejects with a {@link MutationError} carrying a discriminated
+ * {@link MutationOutcome}. Games branch on `outcome.kind` to tell the
+ * participant what happened; `useMutationReporter` does this for them.
+ *
+ * A surface never retries a mutation on its own (SPECIFICATION.md §12.5.1). A
+ * `conflict` means the host has already retried and given up, so the most a
+ * surface does is offer the participant a 'Try again' control, which
+ * `useMutationReporter` provides as `failure.retry`.
+ */
+/** The message a {@link MutationError} carries for an outcome. */
+export function describeMutationOutcome(outcome) {
+    switch (outcome.kind) {
+        case 'conflict':
+            return outcome.message ?? 'The write conflicted with a concurrent tick';
+        case 'validation-rejected':
+            return (outcome.message ??
+                outcome.rejections[0]?.message ??
+                'The write was rejected by a validator');
+        case 'superseded':
+        case 'denied':
+        case 'tick-failed':
+        case 'error':
+            return outcome.message;
+    }
+}
+/**
+ * Error a fallible mutation promise rejects with. Inspect {@link outcome} (or
+ * the shorthand {@link kind}) to branch on the failure reason.
+ */
+export class MutationError extends Error {
+    outcome;
+    constructor(outcome) {
+        super(describeMutationOutcome(outcome));
+        this.name = 'MutationError';
+        this.outcome = outcome;
+        // Restore the prototype chain so `instanceof` works after transpilation
+        // to ES5-targeted output.
+        Object.setPrototypeOf(this, MutationError.prototype);
+    }
+    /** Shorthand for `outcome.kind`. */
+    get kind() {
+        return this.outcome.kind;
+    }
+}

package/lib/ui/request-id.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A correlation id for one host↔iframe request, in any browsing context.
+ *
+ * `crypto.randomUUID` exists only in a **secure context**: HTTPS, or an origin
+ * the browser treats as potentially trustworthy, which `localhost` is and a LAN
+ * address is not. So a surface opened on a phone at `http://192.168.1.157:3000`
+ * — the normal way anyone tests a participant screen on a real device — threw
+ * `crypto.randomUUID is not a function` on mount, before it had painted
+ * anything. The dev server serves plain HTTP by design, and the platform serves
+ * HTTPS, which is why this only ever failed on the one setup nobody runs CI on.
+ *
+ * `crypto.getRandomValues` is **not** gated on a secure context, so the
+ * fallback is a real version 4 UUID rather than a weaker shape. The last resort
+ * exists for a context with no `crypto` at all (an old embedded webview, a test
+ * double): these ids correlate a request with its reply within one page, so
+ * uniqueness is what they need and unpredictability is a bonus.
+ */
+export declare function newRequestId(): string;

package/lib/ui/request-id.js

@@ -0,0 +1,44 @@
+/**
+ * A correlation id for one host↔iframe request, in any browsing context.
+ *
+ * `crypto.randomUUID` exists only in a **secure context**: HTTPS, or an origin
+ * the browser treats as potentially trustworthy, which `localhost` is and a LAN
+ * address is not. So a surface opened on a phone at `http://192.168.1.157:3000`
+ * — the normal way anyone tests a participant screen on a real device — threw
+ * `crypto.randomUUID is not a function` on mount, before it had painted
+ * anything. The dev server serves plain HTTP by design, and the platform serves
+ * HTTPS, which is why this only ever failed on the one setup nobody runs CI on.
+ *
+ * `crypto.getRandomValues` is **not** gated on a secure context, so the
+ * fallback is a real version 4 UUID rather than a weaker shape. The last resort
+ * exists for a context with no `crypto` at all (an old embedded webview, a test
+ * double): these ids correlate a request with its reply within one page, so
+ * uniqueness is what they need and unpredictability is a bonus.
+ */
+const HEX = Array.from({ length: 256 }, (_, byte) => byte.toString(16).padStart(2, '0'));
+export function newRequestId() {
+    const api = globalThis.crypto;
+    if (typeof api?.randomUUID === 'function')
+        return api.randomUUID();
+    if (typeof api?.getRandomValues === 'function') {
+        return uuidFrom(api.getRandomValues(new Uint8Array(16)));
+    }
+    const bytes = new Uint8Array(16);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Math.floor(Math.random() * 256);
+    }
+    return uuidFrom(bytes);
+}
+/** RFC 9562 §5.4: sixteen random bytes, with the version and variant stamped in. */
+function uuidFrom(bytes) {
+    bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+    bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+    const hex = (index) => HEX[bytes[index] ?? 0];
+    const group = (from, to) => {
+        let out = '';
+        for (let index = from; index < to; index += 1)
+            out += hex(index);
+        return out;
+    };
+    return `${group(0, 4)}-${group(4, 6)}-${group(6, 8)}-${group(8, 10)}-${group(10, 16)}`;
+}