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

package/lib/ui/useHostChannel.js

@@ -0,0 +1,338 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { readExpectedParentOrigin } from './expectedParentOrigin.js';
+import { MutationError } from './mutation-outcome.js';
+import { newRequestId } from './request-id.js';
+import { TickSnapshotError } from './tick-snapshot.js';
+import { UI_PROTOCOL_VERSION } from './ui-protocol.js';
+import { useEndpointCallbacks } from './useEndpointCallbacks.js';
+const BLOB_PREFIX = 'blob:';
+const ASSET_PREFIX = 'asset:';
+const SHARED_PREFIX = 'shared:';
+const STANDARD_TYPES = new Set([
+    'ping',
+    'setAssetUrls',
+    'refreshAssetAuth',
+    'uploadBlob:response',
+    'callEndpoint:response',
+    'getPastState:response',
+    'getAllTeamsParticipants:response',
+    'mutation:response',
+    'themePreferenceChanged',
+]);
+/**
+ * Iframe-side counterpart to the host's `useIframeChannel`. Owns the half of the
+ * host↔iframe protocol every UI wrapper shares: the two-phase handshake, port
+ * lifecycle and HMR reset, the per-callback pending-promise maps (blob upload,
+ * endpoints, tick snapshots), asset-URL resolution and `refreshAssetAuth`,
+ * theme-preference relay, and required-message gating.
+ *
+ * Each wrapper supplies its `requiredMessages` and an `onMessage` handler for the
+ * channel-specific messages (`stateChanged`/`setSettings`/`setTheme`/…) and keeps its
+ * own state and context providers.
+ */
+export function useHostChannel(options) {
+    const { targetWindow } = options;
+    const expectedParentOrigin = useMemo(() => readExpectedParentOrigin(), []);
+    const portRef = useRef(null);
+    const receivedRef = useRef(new Set());
+    const [isInitialized, setIsInitialized] = useState(false);
+    const pendingBlob = useRef(new Map());
+    const pendingMutation = useRef(new Map());
+    const pendingPastState = useRef(new Map());
+    const pendingAllTeamsParticipants = useRef(new Map());
+    const [assetUrls, setAssetUrlsState] = useState(undefined);
+    const assetUrlsRef = useRef(undefined);
+    const [themePreference, setThemePreferenceState] = useState('system');
+    const [sessionKey, setSessionKey] = useState(undefined);
+    const { endpoints, handleEndpointResponse, resetPending: resetEndpointPending, } = useEndpointCallbacks(() => portRef.current);
+    // Refs for stable closures so the handshake effect runs once.
+    const optionsRef = useRef(options);
+    optionsRef.current = options;
+    const handleEndpointResponseRef = useRef(handleEndpointResponse);
+    handleEndpointResponseRef.current = handleEndpointResponse;
+    const resetEndpointPendingRef = useRef(resetEndpointPending);
+    resetEndpointPendingRef.current = resetEndpointPending;
+    useEffect(() => {
+        if (!expectedParentOrigin)
+            return;
+        targetWindow.postMessage({ type: 'ready', protocolVersion: UI_PROTOCOL_VERSION }, expectedParentOrigin);
+        const handleMessage = (event) => {
+            if (event.origin !== expectedParentOrigin)
+                return;
+            if (event.data?.type !== 'init')
+                return;
+            const peerVersion = event.data?.protocolVersion;
+            if (typeof peerVersion === 'number' && peerVersion !== UI_PROTOCOL_VERSION) {
+                console.warn(`[${optionsRef.current.label}] host↔iframe protocol version mismatch: ` +
+                    `host ${peerVersion}, iframe ${UI_PROTOCOL_VERSION}`);
+            }
+            const port = event.ports[0];
+            if (!port)
+                return;
+            const key = event.data?.sessionKey;
+            setSessionKey(typeof key === 'string' && key.length > 0 ? key : undefined);
+            portRef.current = port;
+            receivedRef.current = new Set();
+            // Reject any in-flight calls from the previous connection.
+            pendingBlob.current.forEach(({ reject }) => reject(new Error('Connection reset')));
+            pendingBlob.current.clear();
+            pendingMutation.current.forEach(({ reject }) => reject(new MutationError({ kind: 'error', message: 'Connection reset' })));
+            pendingMutation.current.clear();
+            pendingPastState.current.forEach(({ reject }) => reject(new TickSnapshotError('Connection reset')));
+            pendingPastState.current.clear();
+            pendingAllTeamsParticipants.current.forEach(({ reject }) => reject(new Error('Connection reset')));
+            pendingAllTeamsParticipants.current.clear();
+            resetEndpointPendingRef.current();
+            optionsRef.current.onReset?.();
+            setIsInitialized(false);
+            const label = optionsRef.current.label;
+            const markReceived = (type) => {
+                receivedRef.current.add(type);
+            };
+            const helpers = {
+                markReceived,
+                postMessage: (message) => port.postMessage(message),
+            };
+            port.onmessage = (portEvent) => {
+                const raw = portEvent.data;
+                if (raw?.type && STANDARD_TYPES.has(raw.type)) {
+                    const msg = raw;
+                    switch (msg.type) {
+                        case 'ping':
+                            port.postMessage({ type: 'pong' });
+                            break;
+                        case 'setAssetUrls':
+                            setAssetUrlsState(msg.payload);
+                            assetUrlsRef.current = msg.payload;
+                            markReceived('setAssetUrls');
+                            break;
+                        case 'refreshAssetAuth': {
+                            const current = assetUrlsRef.current;
+                            const requestId = msg.requestId;
+                            if (!current) {
+                                port.postMessage({
+                                    type: 'refreshAssetAuth:response',
+                                    requestId,
+                                    ok: false,
+                                    error: 'setAssetUrls not yet received',
+                                });
+                                break;
+                            }
+                            void fetch(current.assetAuthRedeemUrl, {
+                                method: 'POST',
+                                credentials: 'include',
+                                headers: { 'Content-Type': 'application/json' },
+                                body: JSON.stringify({ token: msg.token }),
+                            }).then((res) => {
+                                port.postMessage(res.ok
+                                    ? {
+                                        type: 'refreshAssetAuth:response',
+                                        requestId,
+                                        ok: true,
+                                    }
+                                    : {
+                                        type: 'refreshAssetAuth:response',
+                                        requestId,
+                                        ok: false,
+                                        error: `redeem failed (${res.status})`,
+                                    });
+                            }, (err) => {
+                                port.postMessage({
+                                    type: 'refreshAssetAuth:response',
+                                    requestId,
+                                    ok: false,
+                                    error: err instanceof Error ? err.message : 'redeem failed',
+                                });
+                            });
+                            break;
+                        }
+                        case 'uploadBlob:response':
+                            resolvePending(pendingBlob.current, msg, (m) => m.reference);
+                            break;
+                        case 'callEndpoint:response':
+                            handleEndpointResponseRef.current(msg);
+                            break;
+                        case 'getPastState:response': {
+                            const pending = pendingPastState.current.get(msg.requestId);
+                            if (pending) {
+                                pendingPastState.current.delete(msg.requestId);
+                                if (msg.ok) {
+                                    pending.resolve(msg.entries);
+                                }
+                                else {
+                                    pending.reject(new TickSnapshotError(msg.error));
+                                }
+                            }
+                            break;
+                        }
+                        case 'getAllTeamsParticipants:response':
+                            resolvePending(pendingAllTeamsParticipants.current, msg, (m) => m.participants);
+                            break;
+                        case 'mutation:response': {
+                            const pending = pendingMutation.current.get(msg.requestId);
+                            if (pending) {
+                                pendingMutation.current.delete(msg.requestId);
+                                if (msg.ok) {
+                                    pending.resolve({
+                                        committedAtTick: msg.committedAtTick,
+                                        late: false,
+                                    });
+                                }
+                                else {
+                                    pending.reject(new MutationError(msg.outcome));
+                                }
+                            }
+                            break;
+                        }
+                        case 'themePreferenceChanged':
+                            setThemePreferenceState(msg.preference);
+                            break;
+                    }
+                }
+                else if (optionsRef.current.onMessage) {
+                    optionsRef.current.onMessage(raw, helpers);
+                }
+                else {
+                    // A non-standard message arrived but this wrapper wired no
+                    // handler for it — surface it in dev rather than dropping it
+                    // silently (browsers hide console.debug by default).
+                    console.debug(`[${label}] Ignoring message with no handler: ${raw?.type ?? '(no type)'}`);
+                }
+                if (optionsRef.current.requiredMessages.every((t) => receivedRef.current.has(t))) {
+                    setIsInitialized(true);
+                }
+            };
+            port.start();
+        };
+        window.addEventListener('message', handleMessage);
+        return () => window.removeEventListener('message', handleMessage);
+    }, [targetWindow, expectedParentOrigin]);
+    const postMessage = useCallback((message) => {
+        portRef.current?.postMessage(message);
+    }, []);
+    /**
+     * Post a fallible mutation message and resolve once the host confirms the
+     * commit, or reject with a {@link MutationError} carrying the typed
+     * outcome. A `requestId` is injected so the host can correlate its
+     * `mutation:response` back to this call; existing fire-and-forget callers
+     * that ignore the returned promise keep working unchanged.
+     */
+    const sendMutationReportingCommit = useCallback((message) => {
+        const port = portRef.current;
+        if (!port) {
+            return Promise.reject(new MutationError({ kind: 'error', message: 'Not connected to host' }));
+        }
+        return new Promise((resolve, reject) => {
+            const requestId = newRequestId();
+            pendingMutation.current.set(requestId, { resolve, reject });
+            port.postMessage({ ...message, requestId });
+        });
+    }, []);
+    const sendMutation = useCallback((message) => sendMutationReportingCommit(message).then(() => undefined), [sendMutationReportingCommit]);
+    const setThemePreference = useCallback((preference) => {
+        portRef.current?.postMessage({ type: 'setThemePreference', preference });
+    }, []);
+    const uploadBlob = useCallback(async (file) => {
+        const port = portRef.current;
+        if (!port)
+            throw new Error('Not connected to host');
+        return new Promise((resolve, reject) => {
+            const requestId = newRequestId();
+            pendingBlob.current.set(requestId, { resolve, reject });
+            file.arrayBuffer()
+                .then((data) => {
+                port.postMessage({
+                    type: 'uploadBlob',
+                    requestId,
+                    data,
+                    name: file.name,
+                    mimeType: file.type,
+                }, [data]);
+            })
+                .catch(reject);
+        });
+    }, []);
+    const getAssetUrl = useCallback((reference) => {
+        if (!assetUrls) {
+            throw new Error('getAssetUrl called before setAssetUrls was received');
+        }
+        if (reference.startsWith(BLOB_PREFIX)) {
+            return assetUrls.blobPrefix + reference.slice(BLOB_PREFIX.length);
+        }
+        if (reference.startsWith(SHARED_PREFIX)) {
+            return assetUrls.sharedAssetPrefix + reference.slice(SHARED_PREFIX.length);
+        }
+        if (reference.startsWith(ASSET_PREFIX)) {
+            return assetUrls.scenarioAssetPrefix + reference.slice(ASSET_PREFIX.length);
+        }
+        throw new Error(`Invalid asset reference "${reference}": expected an "asset:", "shared:", or "blob:" prefix`);
+    }, [assetUrls]);
+    const readAsset = useCallback(async (reference) => {
+        const url = getAssetUrl(reference);
+        const res = await fetch(url, { credentials: 'include' });
+        if (!res.ok) {
+            throw new Error(`Failed to fetch asset (${res.status})`);
+        }
+        const buffer = await res.arrayBuffer();
+        const mimeType = res.headers.get('Content-Type') ?? 'application/octet-stream';
+        const nameHeader = res.headers.get('X-Asset-Name');
+        const name = nameHeader
+            ? decodeURIComponent(nameHeader)
+            : (reference.split('/').pop() ?? reference);
+        return { data: new Uint8Array(buffer), mimeType, name };
+    }, [getAssetUrl]);
+    const getPastState = useCallback((query) => {
+        const port = portRef.current;
+        if (!port) {
+            return Promise.reject(new TickSnapshotError('Not connected to host'));
+        }
+        return new Promise((resolve, reject) => {
+            const requestId = newRequestId();
+            pendingPastState.current.set(requestId, { resolve, reject });
+            // The host resolves `teams`, including what 'own' means for
+            // this surface: a player channel has one team and a session
+            // channel has none, and neither is the iframe's to assert.
+            port.postMessage({ type: 'getPastState', requestId, query });
+        });
+    }, []);
+    const getAllTeamsParticipants = useCallback(() => {
+        const port = portRef.current;
+        if (!port) {
+            return Promise.reject(new Error('Not connected to host'));
+        }
+        return new Promise((resolve, reject) => {
+            const requestId = newRequestId();
+            pendingAllTeamsParticipants.current.set(requestId, { resolve, reject });
+            port.postMessage({ type: 'getAllTeamsParticipants', requestId });
+        });
+    }, []);
+    return {
+        expectedParentOrigin,
+        isInitialized,
+        sessionKey,
+        postMessage,
+        sendMutation,
+        sendMutationReportingCommit,
+        themePreference,
+        setThemePreference,
+        uploadBlob,
+        readAsset,
+        getPastState,
+        getAllTeamsParticipants,
+        getAssetUrl,
+        assetUrls,
+        endpoints,
+    };
+}
+function resolvePending(map, msg, getValue) {
+    const pending = map.get(msg.requestId);
+    if (!pending)
+        return;
+    map.delete(msg.requestId);
+    if (msg.ok) {
+        pending.resolve(getValue(msg));
+    }
+    else {
+        pending.reject(new Error(msg.error));
+    }
+}

package/lib/ui/useMutationReporter.d.ts

@@ -0,0 +1,100 @@
+import type { MutationCommit } from './mutation-commit.js';
+import { type MutationOutcome } from './mutation-outcome.js';
+/**
+ * A mutation that failed in a way the participant needs to know about.
+ */
+export type MutationFailure = {
+    /** Why the host refused the write. */
+    outcome: MutationOutcome;
+    /** What the participant was trying to do, if the caller named it. */
+    action?: string;
+    /**
+     * Present on a `conflict` alone: run the same operation again, resolving as
+     * {@link MutationReporter.run} does. For a 'Try again' control a person
+     * presses, never to be called automatically (SPECIFICATION.md §12.5.1). By
+     * the time a `conflict` reaches a surface the host has already retried and
+     * given up, so what changes the answer is a person deciding to try again.
+     * Absent for every other outcome, none of which a second attempt changes.
+     */
+    retry?: () => Promise<boolean>;
+};
+export type MutationReporter = {
+    /**
+     * Run a fallible mutation and wait for the host to commit it. Resolves true
+     * on commit, false once it has failed. Stable across renders, so it is safe
+     * in an effect's dependency list.
+     *
+     * `action` is an optional label for the attempt, carried back on
+     * {@link MutationFailure} so one notice can say which control failed.
+     */
+    run: (mutate: () => Promise<unknown>, action?: string) => Promise<boolean>;
+    /** True while a write is in flight. Disable the control that started it. */
+    pending: boolean;
+    /**
+     * Set when the last committed write landed in a later round than the one
+     * the participant was looking at: they submitted as the tick fired, so the
+     * decision counts for the next round rather than the one on screen. Not a
+     * failure — the write is in — but worth saying out loud, because nothing
+     * else on screen distinguishes it from a decision that arrived in time.
+     *
+     * Null when the last write landed in the round it was composed for, or
+     * when the host reported no tick.
+     */
+    late: MutationCommit | null;
+    /** The failure still to be shown to the participant, or null. */
+    failure: MutationFailure | null;
+    /** Clear the failure and the late notice, so the participant can try again. */
+    dismiss: () => void;
+};
+/**
+ * Runs a fallible mutation (`setData`, `requestTick`, and the rest) so that a
+ * failure reaches the participant instead of vanishing.
+ *
+ * Fire-and-forget is the trap this closes. 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.
+ *
+ * **It never retries on its own, deliberately.** A runtime using optimistic
+ * concurrency retries a losing write itself before it ever reports one
+ * (SPECIFICATION.md §9.7), so by the time a `conflict` reaches a surface the
+ * host has already tried and given up, and a surface MUST NOT retry it
+ * automatically (§12.5.1). On a `conflict` the failure carries
+ * {@link MutationFailure.retry} instead, which re-runs the same operation when
+ * a person asks for it: offer it as a 'Try again' button.
+ *
+ * Render {@link MutationReporter.failure} somewhere the participant will see
+ * it. The copy is yours: it is game language, and it needs localising.
+ *
+ * **A validator rejection arrives twice.** Once here as a `validation-rejected`
+ * outcome, and once through `useUserInterfaceValidationRejections`, which
+ * carries the validator's own message and is the better thing to show. A
+ * surface rendering both puts two notices on screen for one refusal, the
+ * generic one over the specific one. Filter that kind out here and let the
+ * rejection channel explain it:
+ *
+ * ```tsx
+ * const unexplained =
+ *     failure && failure.outcome.kind !== 'validation-rejected' ? failure : null;
+ * ```
+ *
+ * What is left is what only this reports: `denied`, `tick-failed`, `conflict`
+ * and `error`, none of which broadcast anything a surface could otherwise
+ * notice.
+ *
+ * ```tsx
+ * const { run, pending, failure, dismiss } = useMutationReporter();
+ *
+ * <Button
+ *     disabled={pending}
+ *     onClick={() => run(() => setData({ decisions: { Price } }), 'price')}
+ * />
+ * {failure && (
+ *     <Notice onClose={dismiss}>
+ *         {t('write-failed')}
+ *         {failure.retry && <Button onClick={failure.retry}>{t('try-again')}</Button>}
+ *     </Notice>
+ * )}
+ * ```
+ */
+export declare function useMutationReporter(): MutationReporter;

package/lib/ui/useMutationReporter.js

@@ -0,0 +1,97 @@
+import { useCallback, useMemo, useState } from 'react';
+import { MutationError } from './mutation-outcome.js';
+/**
+ * Runs a fallible mutation (`setData`, `requestTick`, and the rest) so that a
+ * failure reaches the participant instead of vanishing.
+ *
+ * Fire-and-forget is the trap this closes. 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.
+ *
+ * **It never retries on its own, deliberately.** A runtime using optimistic
+ * concurrency retries a losing write itself before it ever reports one
+ * (SPECIFICATION.md §9.7), so by the time a `conflict` reaches a surface the
+ * host has already tried and given up, and a surface MUST NOT retry it
+ * automatically (§12.5.1). On a `conflict` the failure carries
+ * {@link MutationFailure.retry} instead, which re-runs the same operation when
+ * a person asks for it: offer it as a 'Try again' button.
+ *
+ * Render {@link MutationReporter.failure} somewhere the participant will see
+ * it. The copy is yours: it is game language, and it needs localising.
+ *
+ * **A validator rejection arrives twice.** Once here as a `validation-rejected`
+ * outcome, and once through `useUserInterfaceValidationRejections`, which
+ * carries the validator's own message and is the better thing to show. A
+ * surface rendering both puts two notices on screen for one refusal, the
+ * generic one over the specific one. Filter that kind out here and let the
+ * rejection channel explain it:
+ *
+ * ```tsx
+ * const unexplained =
+ *     failure && failure.outcome.kind !== 'validation-rejected' ? failure : null;
+ * ```
+ *
+ * What is left is what only this reports: `denied`, `tick-failed`, `conflict`
+ * and `error`, none of which broadcast anything a surface could otherwise
+ * notice.
+ *
+ * ```tsx
+ * const { run, pending, failure, dismiss } = useMutationReporter();
+ *
+ * <Button
+ *     disabled={pending}
+ *     onClick={() => run(() => setData({ decisions: { Price } }), 'price')}
+ * />
+ * {failure && (
+ *     <Notice onClose={dismiss}>
+ *         {t('write-failed')}
+ *         {failure.retry && <Button onClick={failure.retry}>{t('try-again')}</Button>}
+ *     </Notice>
+ * )}
+ * ```
+ */
+export function useMutationReporter() {
+    const [pending, setPending] = useState(false);
+    const [failure, setFailure] = useState(null);
+    const [late, setLate] = useState(null);
+    const run = useCallback(async function attempt(mutate, action) {
+        setFailure(null);
+        setLate(null);
+        setPending(true);
+        try {
+            const commit = (await mutate());
+            if (commit?.late)
+                setLate(commit);
+            return true;
+        }
+        catch (error) {
+            const outcome = outcomeOf(error);
+            setFailure({
+                outcome,
+                ...(action === undefined ? {} : { action }),
+                ...(outcome.kind === 'conflict' ? { retry: () => attempt(mutate, action) } : {}),
+            });
+            return false;
+        }
+        finally {
+            setPending(false);
+        }
+    }, []);
+    const dismiss = useCallback(() => {
+        setFailure(null);
+        setLate(null);
+    }, []);
+    return useMemo(() => ({ run, pending, failure, late, dismiss }), [run, pending, failure, late, dismiss]);
+}
+/**
+ * A rejected mutation carries a {@link MutationOutcome}. Anything else reaching
+ * here is a bug rather than a refusal, and is reported as one rather than
+ * swallowed: a surface that shows nothing is the failure mode this exists to
+ * remove.
+ */
+function outcomeOf(error) {
+    if (error instanceof MutationError)
+        return error.outcome;
+    return { kind: 'error', message: error instanceof Error ? error.message : String(error) };
+}

package/lib/ui/usePastState.d.ts

@@ -0,0 +1,39 @@
+import type { PastStateEntry, PastStateQuery } from '../build/callbacks.js';
+/** The surface's `getPastState` callback, as {@link usePastState} calls it. */
+export type PastStateReader = <T = Record<string, unknown>>(query: PastStateQuery<T>) => Promise<PastStateEntry<T>[]>;
+/**
+ * Provided by the wrappers whose surfaces can read past state: the player,
+ * session and presentation wrappers. Exported for the test helpers, which
+ * provide it without a host; game code reads it through {@link usePastState}.
+ */
+export declare const PastStateContext: import("react").Context<PastStateReader | undefined>;
+export interface PastStateResult<T> {
+    /**
+     * The entries the latest completed read returned. Empty until the first
+     * read completes, and kept on screen while a new query loads.
+     */
+    entries: PastStateEntry<T>[];
+    /** Why the latest read failed, until one succeeds. */
+    error: Error | undefined;
+    /** True while a read is in flight. */
+    loading: boolean;
+    /** Read the current query again, for a surface that knows the history has moved on. */
+    refetch: () => void;
+}
+/**
+ * Read committed past state (`getPastState`) and keep it in step with the
+ * query.
+ *
+ * Reads again when the query changes, compared by value so an inline object
+ * literal is fine. Only the latest read's answer is kept: a slow answer to an
+ * earlier query never replaces a newer one. The previous entries stay on
+ * screen while a new query loads, so a scrubber moving through rounds does not
+ * flash empty between them. Pass `null` to read nothing yet.
+ *
+ * Available on the player, session and presentation surfaces.
+ *
+ * ```tsx
+ * const { entries, loading } = usePastState<Context>({ fromTick: day, capabilityIds: ['sales'] });
+ * ```
+ */
+export declare function usePastState<T = Record<string, unknown>>(query: PastStateQuery<T> | null | undefined): PastStateResult<T>;

package/lib/ui/usePastState.js

@@ -0,0 +1,63 @@
+import { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+/**
+ * Provided by the wrappers whose surfaces can read past state: the player,
+ * session and presentation wrappers. Exported for the test helpers, which
+ * provide it without a host; game code reads it through {@link usePastState}.
+ */
+export const PastStateContext = createContext(undefined);
+/**
+ * Read committed past state (`getPastState`) and keep it in step with the
+ * query.
+ *
+ * Reads again when the query changes, compared by value so an inline object
+ * literal is fine. Only the latest read's answer is kept: a slow answer to an
+ * earlier query never replaces a newer one. The previous entries stay on
+ * screen while a new query loads, so a scrubber moving through rounds does not
+ * flash empty between them. Pass `null` to read nothing yet.
+ *
+ * Available on the player, session and presentation surfaces.
+ *
+ * ```tsx
+ * const { entries, loading } = usePastState<Context>({ fromTick: day, capabilityIds: ['sales'] });
+ * ```
+ */
+export function usePastState(query) {
+    const getPastState = useContext(PastStateContext);
+    if (getPastState === undefined) {
+        throw new Error('usePastState must be used inside a UserInterfaceWrapper, SessionUserInterfaceWrapper or PresentationWrapper');
+    }
+    const key = query ? JSON.stringify(query) : '';
+    const [entries, setEntries] = useState([]);
+    const [error, setError] = useState(undefined);
+    const [loading, setLoading] = useState(key !== '');
+    const [generation, setGeneration] = useState(0);
+    const latest = useRef(0);
+    useEffect(() => {
+        if (key === '') {
+            setLoading(false);
+            return;
+        }
+        const request = ++latest.current;
+        setLoading(true);
+        getPastState(JSON.parse(key)).then((result) => {
+            if (request !== latest.current)
+                return;
+            setEntries(result);
+            setError(undefined);
+            setLoading(false);
+        }, (cause) => {
+            if (request !== latest.current)
+                return;
+            setError(cause instanceof Error ? cause : new Error(String(cause)));
+            setLoading(false);
+        });
+        return () => {
+            // An unmounted surface, or one whose query has moved on, takes no
+            // answer from this read.
+            if (latest.current === request)
+                latest.current++;
+        };
+    }, [key, generation, getPastState]);
+    const refetch = useCallback(() => setGeneration((previous) => previous + 1), []);
+    return { entries, error, loading, refetch };
+}