@satinhq/kit 0.0.0-stage → 0.1.0-beta.0

package/dist/reachability/model.d.ts

@@ -0,0 +1,94 @@
+/** The result of the app server reachability probe. */
+export type ReachabilityStatus = 'device-offline' | 'server-unreachable' | 'reachable';
+/** The server probe result, including an unknown initial state. */
+export type ReachabilityStateStatus = ReachabilityStatus | 'unknown';
+/** Whether a destination remains usable without the app server. */
+export type ReachabilityRoutePolicy = 'local-first' | 'requires-server';
+/** The framework connectivity presentation to show for a failed probe. */
+export type ReachabilitySurface = 'banner' | 'full-screen' | 'none';
+/** The endpoint and deadlines used to probe the app server. */
+export interface ReachabilityProbeConfig {
+    readonly method: 'GET' | 'HEAD';
+    readonly timeoutMs: number;
+    readonly url: string;
+}
+/** The server probe and presentation policy for an app that requires connectivity. */
+export interface ServerReachabilityConfig {
+    readonly defaultRoutePolicy: ReachabilityRoutePolicy;
+    readonly probe: ReachabilityProbeConfig;
+    readonly routes: Readonly<Record<string, ReachabilityRoutePolicy>>;
+    readonly surfaces: {
+        readonly localFirst: Exclude<ReachabilitySurface, 'full-screen'>;
+        readonly requiresServer: ReachabilitySurface;
+    };
+}
+export type ReachabilityProfile = {
+    readonly connectivity: 'local';
+} | {
+    readonly connectivity: 'server';
+    readonly reachability: ServerReachabilityConfig;
+};
+export type ProbeTrigger = 'browser-online' | 'explicit-recheck' | 'initial' | 'resume';
+export type ReachabilityEvent = {
+    readonly type: 'browser-offline';
+} | {
+    readonly type: 'browser-online';
+} | {
+    readonly outcome: 'aborted' | 'network-failure' | 'response';
+    readonly type: 'fetch-outcome';
+} | {
+    readonly probeId: number;
+    readonly result: 'reachable' | 'unreachable';
+    readonly type: 'probe-result';
+} | {
+    readonly navigatorOnline: boolean;
+    readonly type: 'resume';
+} | {
+    readonly type: 'recheck';
+} | {
+    readonly route: string;
+    readonly type: 'route-changed';
+};
+export type ReachabilityCommand = {
+    readonly type: 'hide-surface';
+} | {
+    readonly probe: ReachabilityProbeConfig;
+    readonly probeId: number;
+    readonly trigger: ProbeTrigger;
+    readonly type: 'probe';
+} | {
+    readonly reason: Exclude<ReachabilityStatus, 'reachable'>;
+    readonly surface: Exclude<ReachabilitySurface, 'none'>;
+    readonly type: 'show-surface';
+};
+/** The connectivity presentation currently shown to the user. */
+export interface ReachabilityPresentation {
+    readonly reason: Exclude<ReachabilityStatus, 'reachable'>;
+    readonly surface: Exclude<ReachabilitySurface, 'none'>;
+}
+/** The connectivity state of an app that does not require an app server. */
+export interface LocalReachabilityState {
+    readonly connectivity: 'local';
+    readonly status: 'local';
+}
+/** The last server probe, retry and connectivity presentation state. */
+export interface ServerReachabilityState {
+    readonly config: ServerReachabilityConfig;
+    readonly connectivity: 'server';
+    readonly navigatorOnline: boolean;
+    readonly nextProbeId: number;
+    readonly pendingProbeId: number | undefined;
+    readonly presentedSurface: ReachabilityPresentation | undefined;
+    readonly route: string;
+    readonly status: ReachabilityStateStatus;
+}
+export type ReachabilityState = LocalReachabilityState | ServerReachabilityState;
+export interface ReachabilityReduction {
+    readonly commands: readonly ReachabilityCommand[];
+    readonly state: ReachabilityState;
+}
+export declare function createReachabilityState(profile: ReachabilityProfile, input: {
+    readonly navigatorOnline: boolean;
+    readonly route: string;
+}): ReachabilityReduction;
+export declare function reduceReachability(state: ReachabilityState, event: ReachabilityEvent): ReachabilityReduction;

package/dist/reachability/model.js

@@ -0,0 +1,131 @@
+function routePolicy(state) {
+    return state.config.routes[state.route] ?? state.config.defaultRoutePolicy;
+}
+function desiredSurface(state) {
+    if (state.status === 'reachable' || state.status === 'unknown')
+        return undefined;
+    const surface = routePolicy(state) === 'requires-server'
+        ? state.config.surfaces.requiresServer
+        : state.config.surfaces.localFirst;
+    if (surface === 'none')
+        return undefined;
+    return { reason: state.status, surface };
+}
+function surfacesEqual(left, right) {
+    return left?.reason === right?.reason && left?.surface === right?.surface;
+}
+function settleSurface(previous, next) {
+    const presentedSurface = desiredSurface(next);
+    const state = { ...next, presentedSurface };
+    if (!previous || surfacesEqual(previous.presentedSurface, presentedSurface)) {
+        return { commands: [], state };
+    }
+    if (!presentedSurface) {
+        return { commands: [{ type: 'hide-surface' }], state };
+    }
+    return {
+        commands: [{ type: 'show-surface', ...presentedSurface }],
+        state,
+    };
+}
+function startProbe(state, trigger) {
+    const probeId = state.nextProbeId;
+    return {
+        command: {
+            probe: state.config.probe,
+            probeId,
+            trigger,
+            type: 'probe',
+        },
+        state: {
+            ...state,
+            nextProbeId: probeId + 1,
+            pendingProbeId: probeId,
+        },
+    };
+}
+export function createReachabilityState(profile, input) {
+    if (profile.connectivity === 'local') {
+        return {
+            commands: [],
+            state: { connectivity: 'local', status: 'local' },
+        };
+    }
+    const base = {
+        config: profile.reachability,
+        connectivity: 'server',
+        navigatorOnline: input.navigatorOnline,
+        nextProbeId: 1,
+        pendingProbeId: undefined,
+        presentedSurface: undefined,
+        route: input.route,
+        status: input.navigatorOnline ? 'unknown' : 'device-offline',
+    };
+    const settled = settleSurface(undefined, base);
+    if (!input.navigatorOnline) {
+        const surface = settled.state.presentedSurface;
+        return {
+            commands: surface ? [{ type: 'show-surface', ...surface }] : [],
+            state: settled.state,
+        };
+    }
+    const probe = startProbe(settled.state, 'initial');
+    return { commands: [probe.command], state: probe.state };
+}
+export function reduceReachability(state, event) {
+    if (state.connectivity === 'local')
+        return { commands: [], state };
+    if (event.type === 'route-changed') {
+        return settleSurface(state, { ...state, route: event.route });
+    }
+    if (event.type === 'browser-offline') {
+        return settleSurface(state, {
+            ...state,
+            navigatorOnline: false,
+            pendingProbeId: undefined,
+            status: 'device-offline',
+        });
+    }
+    if (event.type === 'browser-online') {
+        const probe = startProbe({ ...state, navigatorOnline: true }, 'browser-online');
+        return { commands: [probe.command], state: probe.state };
+    }
+    if (event.type === 'resume') {
+        if (!event.navigatorOnline) {
+            return settleSurface(state, {
+                ...state,
+                navigatorOnline: false,
+                pendingProbeId: undefined,
+                status: 'device-offline',
+            });
+        }
+        const probe = startProbe({ ...state, navigatorOnline: true }, 'resume');
+        return { commands: [probe.command], state: probe.state };
+    }
+    if (event.type === 'recheck') {
+        if (!state.navigatorOnline)
+            return { commands: [], state };
+        const probe = startProbe(state, 'explicit-recheck');
+        return { commands: [probe.command], state: probe.state };
+    }
+    if (event.type === 'fetch-outcome') {
+        if (event.outcome === 'aborted' || !state.navigatorOnline)
+            return { commands: [], state };
+        return settleSurface(state, {
+            ...state,
+            pendingProbeId: undefined,
+            status: event.outcome === 'response'
+                ? 'reachable'
+                : state.navigatorOnline
+                    ? 'server-unreachable'
+                    : 'device-offline',
+        });
+    }
+    if (event.probeId !== state.pendingProbeId)
+        return { commands: [], state };
+    return settleSurface(state, {
+        ...state,
+        pendingProbeId: undefined,
+        status: event.result === 'reachable' ? 'reachable' : 'server-unreachable',
+    });
+}

package/dist/reachability/react.d.ts

@@ -0,0 +1,29 @@
+import { type ComponentType, type PropsWithChildren } from 'react';
+import type { ReachabilityProfile, ReachabilitySurface } from './model.js';
+export interface OfflinePresentationProps {
+    readonly reason: 'device-offline' | 'server-unreachable';
+    readonly surface: Exclude<ReachabilitySurface, 'none'>;
+    readonly goBack?: () => void;
+    readonly checking: boolean;
+    readonly recheck: () => void;
+}
+export declare function OfflinePresentation({ reason, surface, checking, recheck, goBack, }: OfflinePresentationProps): import("react").JSX.Element;
+export declare function ReachabilityProvider({ profile, offlinePresentation, children, }: PropsWithChildren<{
+    profile: ReachabilityProfile;
+    offlinePresentation?: ComponentType<OfflinePresentationProps>;
+}>): import("react").JSX.Element;
+/** The server status and visible offline presentation, with fetch and retry helpers. */
+export declare function useReachability(): {
+    recheck: () => void;
+    reportFetchOutcome: (outcome: 'response' | 'network-failure' | 'aborted') => void;
+    fetch: typeof fetch;
+    state: {
+        status: "local" | import("./model.js").ReachabilityStateStatus;
+        presentation: import("./model.js").ReachabilityPresentation | undefined;
+    };
+};
+/** Mounted once by NavigatorHost, observing its actual top screen ID. */
+export declare function ReachabilityRoute({ route, children, goBack, }: PropsWithChildren<{
+    route: string;
+    goBack?: () => void;
+}>): import("react").JSX.Element;

package/dist/reachability/react.js

@@ -0,0 +1,69 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TabActivityContext } from '../tabs/context.js';
+import { createContext, createElement, useContext, useEffect, useLayoutEffect, useMemo, useSyncExternalStore, } from 'react';
+import { Pressable } from '../press/Pressable.js';
+import { ContentUnavailableView } from '../public/controls.js';
+import { browserReachabilityEnvironment, createReachabilityController } from './controller.js';
+export function OfflinePresentation({ reason, surface, checking, recheck, goBack, }) {
+    const title = reason === 'device-offline' ? 'You’re offline' : 'Server unavailable';
+    const description = reason === 'device-offline'
+        ? 'Connect to a network to use this screen.'
+        : 'This screen needs a connection to the app server.';
+    const actions = (_jsxs(_Fragment, { children: [goBack && _jsx(Pressable, { onPress: goBack, children: "Back" }), _jsx(Pressable, { onPress: recheck, disabled: checking, children: checking ? 'Checking…' : 'Try again' })] }));
+    return (_jsx("section", { "data-satin-offline": surface, role: "status", "aria-live": "polite", children: surface === 'full-screen' ? (_jsx(ContentUnavailableView, { title: title, description: description, children: actions })) : (_jsxs(_Fragment, { children: [_jsx("strong", { children: title }), _jsx("p", { children: description }), actions] })) }));
+}
+const ReachabilityContext = createContext(null);
+const PresentationContext = createContext(OfflinePresentation);
+const localController = createReachabilityController({ connectivity: 'local' }, '', browserReachabilityEnvironment);
+export function ReachabilityProvider({ profile, offlinePresentation = OfflinePresentation, children, }) {
+    const controller = useMemo(() => createReachabilityController(profile, '', browserReachabilityEnvironment), [profile]);
+    useEffect(() => {
+        controller.start();
+        return () => controller.dispose();
+    }, [controller]);
+    return (_jsx(ReachabilityContext, { value: controller, children: _jsx(PresentationContext, { value: offlinePresentation, children: children }) }));
+}
+/** Whether the app can reach its network and server: the live state, a way to re-check, and a way
+ * to report a fetch's outcome so Satin learns about failures early. */
+// This hook shares the provider context and does not create components.
+// oxlint-disable-next-line react/only-export-components
+function useReachabilityController() {
+    const controller = useContext(ReachabilityContext) ?? localController;
+    const state = useSyncExternalStore(controller.subscribe, controller.getSnapshot, controller.getSnapshot);
+    return {
+        state,
+        recheck: controller.recheck,
+        reportFetchOutcome: controller.reportFetchOutcome,
+        fetch: controller.fetch,
+    };
+}
+/** The server status and visible offline presentation, with fetch and retry helpers. */
+export function useReachability() {
+    const { state, ...commands } = useReachabilityController();
+    return {
+        ...commands,
+        state: {
+            status: state.status,
+            presentation: state.connectivity === 'server' ? state.presentedSurface : undefined,
+        },
+    };
+}
+/** Mounted once by NavigatorHost, observing its actual top screen ID. */
+export function ReachabilityRoute({ route, children, goBack, }) {
+    const controller = useContext(ReachabilityContext) ?? localController;
+    const tabActive = useContext(TabActivityContext);
+    const Presentation = useContext(PresentationContext);
+    const { state, recheck } = useReachabilityController();
+    useLayoutEffect(() => {
+        if (tabActive)
+            controller.setRoute(route);
+    }, [controller, route, tabActive]);
+    const shown = state.connectivity === 'server' ? state.presentedSurface : undefined;
+    return (_jsxs(_Fragment, { children: [_jsx("div", { "data-satin-route-content": "true", inert: shown?.surface === 'full-screen' ? true : undefined, children: children }), shown &&
+                createElement(Presentation, {
+                    ...shown,
+                    goBack,
+                    checking: state.connectivity === 'server' && state.pendingProbeId !== undefined,
+                    recheck,
+                })] }));
+}

package/dist/restoration/navigation.d.ts

@@ -0,0 +1,9 @@
+import type { ScreenRegistry } from '../navigation/registry.js';
+import type { NavigatorState, ScreenEntry } from '../navigation/types.js';
+import type { SceneRestoration } from './scene.js';
+export interface NavigatorRestoration {
+    scene: SceneRestoration;
+    key: string;
+}
+export declare function readNavigation(restoration: NavigatorRestoration, registry: ScreenRegistry, root: string): ScreenEntry[];
+export declare function saveNavigation(restoration: NavigatorRestoration, registry: ScreenRegistry, state: NavigatorState): void;

package/dist/restoration/navigation.js

@@ -0,0 +1,55 @@
+import { createRouteCodec } from '../navigation/routeCodec.js';
+export function readNavigation(restoration, registry, root) {
+    const saved = restoration.scene.read(`navigation:${restoration.key}`);
+    if (!Array.isArray(saved) || saved[0]?.screen !== root)
+        return [];
+    const codec = createRouteCodec(registry), keys = new Set(), entries = [];
+    for (const value of saved.slice(0, 64)) {
+        const route = codec.decode(value);
+        if (!route ||
+            registry.resolve(route.screen)?.restoration?.persist === false ||
+            typeof value.key !== 'string' ||
+            !value.key ||
+            value.key.length > 200 ||
+            keys.has(value.key))
+            break;
+        keys.add(value.key);
+        const scroll = new Map();
+        if (Array.isArray(value.scroll))
+            for (const item of value.scroll.slice(0, 64)) {
+                if (Array.isArray(item) &&
+                    typeof item[0] === 'string' &&
+                    Number.isFinite(item[1]?.x) &&
+                    Number.isFinite(item[1]?.y))
+                    scroll.set(item[0], { x: item[1].x, y: item[1].y });
+            }
+        entries.push({
+            key: value.key,
+            screenId: route.screen,
+            params: route.params,
+            presentation: 'push',
+            scrollSnapshot: scroll,
+            transition: { phase: 'settled', controller: { progress: 1, finish() { }, cancel() { } } },
+        });
+    }
+    return entries;
+}
+export function saveNavigation(restoration, registry, state) {
+    // A flush includes accepted pushes. An unresolved interactive pop retains
+    // its outgoing route; automatic exits project the accepted destination.
+    const entries = state.entries.filter(entry => entry.transition.phase !== 'exiting' ||
+        ['held', 'cancelling'].includes(entry.transition.controller.interactionPhase ?? ''));
+    const codec = createRouteCodec(registry), saved = [];
+    for (const entry of entries.slice(0, 64)) {
+        const route = codec.decode({
+            screen: entry.screenId,
+            params: entry.params,
+            version: registry.resolve(entry.screenId)?.restoration?.version,
+        });
+        if (!route || registry.resolve(route.screen)?.restoration?.persist === false)
+            break;
+        saved.push({ ...route, key: entry.key, scroll: [...(entry.scrollSnapshot ?? [])] });
+    }
+    restoration.scene.retainEntries(restoration.key, state.entries.map(entry => entry.key));
+    restoration.scene.write(`navigation:${restoration.key}`, saved);
+}

package/dist/restoration/react.d.ts

@@ -0,0 +1,6 @@
+import { type SetStateAction } from 'react';
+import { type SceneRestoration, type StateSchema } from './scene.js';
+/** Application/scene values such as the selected tab. Declare schemas outside render. */
+export declare function useRestoredState<T>(scene: SceneRestoration, key: string, schema: StateSchema<T>): readonly [T, (next: SetStateAction<T>) => void];
+/** Entry-scoped state: repeated pushes of the same screen keep independent drafts. */
+export declare function useSceneStorage<T>(key: string, schema: StateSchema<T>): readonly [T, (next: SetStateAction<T>) => void];

package/dist/restoration/react.js

@@ -0,0 +1,21 @@
+import { useCallback, useContext, useSyncExternalStore } from 'react';
+import { NavigatorContext, ScreenContext } from '../navigation/navigationContext.js';
+import { cloneSceneValue, readSceneValue, } from './scene.js';
+/** Application/scene values such as the selected tab. Declare schemas outside render. */
+export function useRestoredState(scene, key, schema) {
+    const get = useCallback(() => readSceneValue(scene, key, schema), [scene, key, schema]);
+    const value = useSyncExternalStore(scene.subscribe, get, get);
+    const set = useCallback((next) => {
+        const value = typeof next === 'function' ? next(get()) : next;
+        const cloned = cloneSceneValue(value, schema);
+        scene.write(key, { version: schema.version, value: cloned });
+    }, [scene, key, schema, get]);
+    return [value, set];
+}
+/** Entry-scoped state: repeated pushes of the same screen keep independent drafts. */
+export function useSceneStorage(key, schema) {
+    const navigator = useContext(NavigatorContext), screen = useContext(ScreenContext);
+    if (!navigator?.restoration || !screen)
+        throw new Error('useSceneStorage requires a restoring NavigatorHost');
+    return useRestoredState(navigator.restoration.scene, `entry:${navigator.restoration.key}:${screen.key}:${key}`, schema);
+}

package/dist/restoration/routes.d.ts

@@ -0,0 +1,22 @@
+import type { ScreenRegistry } from '../navigation/registry.js';
+import { type NavigatorStore } from '../navigation/store.js';
+import { type SceneRestoration, type StateSchema } from './scene.js';
+export declare const tabSelectionSchema: StateSchema<string>;
+/** Call before mount. Explicit launch intent wins over the checkpoint. */
+export declare function prepareSceneRoutes(options: {
+    scene: SceneRestoration;
+    scope: string;
+    navigators: Record<string, NavigatorStore>;
+    registry: ScreenRegistry;
+    defaultTab: string;
+    url?: string;
+}): {
+    openURL(input: string): boolean;
+    selectionKey: string;
+    selectionSchema: {
+        version: number;
+        initial: string;
+        validate: (value: unknown) => value is string;
+    };
+    connect(): () => void;
+};

package/dist/restoration/routes.js

@@ -0,0 +1,166 @@
+import { connectPushRoutes, consumeSceneLaunchURL, createRouteIntentQueue, } from '../push/urlProjection.js';
+import { navigatorTransitionRuntime } from '../navigation/store.js';
+import { createRouteCodec, sameRouteParams } from '../navigation/routeCodec.js';
+import { decodePushRoute } from '../push/routes.js';
+import { readSceneValue } from './scene.js';
+export const tabSelectionSchema = {
+    version: 1,
+    initial: '',
+    validate: (value) => typeof value === 'string',
+};
+/** Call before mount. Explicit launch intent wins over the checkpoint. */
+export function prepareSceneRoutes(options) {
+    const { scene, navigators } = options;
+    const codec = createRouteCodec(options.registry);
+    const tabKey = 'selected-tab';
+    const rules = codec.pushRules(Object.keys(navigators));
+    const current = () => {
+        const saved = readSceneValue(scene, tabKey, tabSelectionSchema);
+        return Object.hasOwn(navigators, saved) ? saved : options.defaultTab;
+    };
+    const select = (tab) => scene.write(tabKey, { version: 1, value: tab });
+    if (!Object.hasOwn(navigators, options.defaultTab))
+        throw new Error('Missing default navigator');
+    const scope = new URL(options.scope, typeof location === 'undefined' ? 'https://satin.invalid' : location.origin).href;
+    const url = options.url ?? (typeof location === 'undefined' ? scope : location.href);
+    const deliveryKey = 'route-deliveries';
+    const pending = new Map();
+    const durable = () => {
+        const ids = scene.readPersisted(deliveryKey);
+        return Array.isArray(ids)
+            ? ids.filter((id) => typeof id === 'string').slice(-128)
+            : [];
+    };
+    const seen = () => [...new Set([...durable(), ...pending.keys()])].slice(-128);
+    let accepted;
+    const record = (id) => {
+        if (!accepted)
+            return;
+        pending.set(id, accepted);
+        scene.write(deliveryKey, seen());
+        // Navigators register their preparations at construction, before this one.
+        // Do not persist a ledger entry for a route omitted by a schema/cap or a
+        // navigator that did not opt into this scene's restoration.
+        scene.checkpoint(deliveryKey, () => {
+            const ids = durable();
+            for (const [id, target] of pending) {
+                if (ids.includes(id))
+                    pending.delete(id);
+                else {
+                    if (target.navigator[navigatorTransitionRuntime].hasCheckpointEntry(scene, target.key))
+                        ids.push(id);
+                }
+            }
+            scene.write(deliveryKey, ids.slice(-128));
+        }, () => false);
+    };
+    const accept = (route, cold = false) => {
+        accepted = undefined;
+        const tab = route.tab ?? current(), navigator = navigators[tab];
+        if (!navigator)
+            return false;
+        const target = codec.decode({
+            screen: route.screen,
+            version: route.version,
+            params: route.params,
+        });
+        if (!target)
+            return false;
+        const entries = navigator.getState().entries;
+        const previous = entries.findLastIndex(entry => entry.screenId === target.screen && sameRouteParams(entry.params, target.params));
+        if (previous >= 0) {
+            if (!navigator[navigatorTransitionRuntime].activateEntry(entries[previous].key))
+                return false;
+            if (navigator.getState().entries.at(-1)?.key !== entries[previous].key)
+                return false;
+            accepted = { navigator, key: entries[previous].key };
+            select(tab);
+            return true;
+        }
+        const path = entries.map(entry => ({
+            screen: entry.screenId,
+            params: entry.params,
+            version: options.registry.resolve(entry.screenId)?.restoration?.version ?? 0,
+        }));
+        if (!(cold
+            ? navigator.activatePath([...path, target])
+            : navigator.push(target.screen, target.params)))
+            return false;
+        const entry = navigator.getState().entries.at(-1);
+        if (!entry || entry.screenId !== target.screen || !sameRouteParams(entry.params, target.params))
+            return false;
+        accepted = { navigator, key: entry.key };
+        select(tab);
+        return true;
+    };
+    const openPath = (input) => {
+        const path = codec.decodeURL(input, scope);
+        if (path === null)
+            return false;
+        const requested = new URL(input, scope).searchParams.get('satin-tab');
+        const tab = requested && Object.hasOwn(navigators, requested) ? requested : current();
+        if (!navigators[tab].activatePath(path))
+            return false;
+        select(tab);
+        return true;
+    };
+    const subscribeNavigation = (listener) => {
+        const stops = [
+            ...Object.values(navigators).map(navigator => navigator.subscribe(listener)),
+            scene.subscribe(listener),
+        ];
+        return () => stops.forEach(stop => stop());
+    };
+    const queue = createRouteIntentQueue(subscribeNavigation);
+    let nextPath = 0;
+    const cold = decodePushRoute(url, scope, rules);
+    if (cold && !seen().includes(cold.id) && accept(cold.route, true))
+        record(cold.id);
+    if (!cold) {
+        if (openPath(url))
+            consumeSceneLaunchURL(url);
+    }
+    return {
+        openURL(input) {
+            const push = decodePushRoute(input, scope, rules);
+            if (push) {
+                queue.enqueue(`push:${push.id}`, () => {
+                    if (seen().includes(push.id))
+                        return true;
+                    if (!accept(push.route))
+                        return false;
+                    record(push.id);
+                    return true;
+                });
+                return true;
+            }
+            if (codec.decodeURL(input, scope) === null)
+                return false;
+            queue.enqueue(`path:${++nextPath}`, () => openPath(input));
+            return true;
+        },
+        selectionKey: tabKey,
+        selectionSchema: {
+            ...tabSelectionSchema,
+            initial: options.defaultTab,
+            validate: (value) => typeof value === 'string' && Object.hasOwn(navigators, value),
+        },
+        connect() {
+            const disconnectScene = scene.connect();
+            const disconnectRoutes = connectPushRoutes({
+                scope,
+                routes: rules,
+                navigate: accept,
+                queue,
+                hasAccepted: id => seen().includes(id),
+                didAccept: record,
+                canAcknowledge: id => durable().includes(id),
+                subscribeNavigation,
+            });
+            return () => {
+                disconnectRoutes();
+                disconnectScene();
+            };
+        },
+    };
+}

package/dist/restoration/scene.d.ts

@@ -0,0 +1,44 @@
+/** Small UI checkpoints, read before mount and written in quiet tasks. */
+export interface StateSchema<T> {
+    readonly version: number;
+    readonly initial: T;
+    readonly validate: (value: unknown) => value is T;
+}
+export interface SceneRestoration {
+    /** Flush on suspension; ordinary writes coalesce outside scroll/transition frames. */
+    connect(): () => void;
+    /** Internal: capture the latest navigator only when a checkpoint is due. */
+    checkpoint(key: string, prepare: () => void, blocked: () => boolean, forceBlocked?: () => boolean): void;
+    /** Lifecycle/testing boundary. Returns whether the checkpoint reached storage. */
+    flush(): boolean;
+    /** Internal: last successfully stored checkpoint, excluding pending edits. */
+    readPersisted(key: string): unknown;
+    read(key: string): unknown;
+    /** True means accepted in memory; flush/diagnostics report durable storage. */
+    write(key: string, value: unknown): boolean;
+    remove(key: string): void;
+    /** Internal entry garbage collection, committed by the next checkpoint write. */
+    retainEntries(navigator: string, keys: readonly string[]): void;
+    subscribe(listener: () => void): () => void;
+    reset(): void;
+    readonly diagnostics: {
+        readonly restored: boolean;
+        readonly readMs: number;
+        readonly writeMs: number;
+        readonly bytes: number;
+        readonly error: string | null;
+    };
+}
+export declare function createSceneRestoration(options: {
+    id: string;
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+    /** No automatic expiry by default. Explicit reset is a deliberate exit. */
+    maxAbsenceMs?: number;
+    maxBytes?: number;
+    now?: () => number;
+}): SceneRestoration;
+export declare function readSceneValue<T>(scene: SceneRestoration | undefined, key: string, schema: StateSchema<T>): T;
+/** UI checkpoints accept JSON values only, without lossy Date/Map/function coercion. */
+export declare function isSerializableState(value: unknown, ancestors?: Set<object>, depth?: number): boolean;
+/** Validate the actual stored representation, including the app's schema. */
+export declare function cloneSceneValue<T>(value: T, schema?: StateSchema<T>): T;