phonux 0.1.0

package/panels/useRowScrollGesture.js

@@ -0,0 +1,70 @@
+/**
+ * The row's scroll gesture: a wheel swipe or an arrow key moves the row one step, bringing a parked panel back from
+ * whichever side it sits on.
+ *
+ * Native `addEventListener`, not React's `onWheel`: React's wheel listener is passive, so the `preventDefault()` that
+ * keeps a horizontal swipe from also scrolling the page vertically would do nothing.
+ *
+ * `scrollRow` is read through a ref and never re-subscribed: it is a fresh closure every render (nothing here may be
+ * memoised), and tearing the listeners down would lose the momentum lock's timer on every re-render, including the
+ * one `scrollRow` itself causes.
+ */
+import { useEffect, useRef } from 'react';
+/** A trackpad swipe arrives as a burst of small wheel deltas with a momentum tail; Chromium cannot tell a momentum event from a fresh user one. Locking on the first event of a burst and unlocking only after this long of silence (not a shorter one -- gaps inside a real momentum stream can exceed 150 ms) keeps one swipe to one step. */
+const GESTURE_LOCK_MS = 350;
+export function useRowScrollGesture(overflowContainerRef, scrollRow) {
+    const scrollRowRef = useRef(scrollRow);
+    scrollRowRef.current = scrollRow;
+    useEffect(() => {
+        const container = overflowContainerRef.current;
+        if (!container)
+            return;
+        let locked = false;
+        let unlockTimer = null;
+        const armUnlock = () => {
+            if (unlockTimer)
+                clearTimeout(unlockTimer);
+            unlockTimer = setTimeout(() => {
+                locked = false;
+            }, GESTURE_LOCK_MS);
+        };
+        const onWheel = (e) => {
+            // A tilt wheel or two-finger swipe reports deltaX; Shift+wheel usually still reports deltaY, so treat
+            // Shift+deltaY as a horizontal ask too. Plain vertical wheel is left to overflowY:'auto'.
+            const horizontal = Math.abs(e.deltaX) > Math.abs(e.deltaY) || (e.shiftKey && e.deltaY !== 0);
+            if (!horizontal)
+                return;
+            const amount = Math.abs(e.deltaX) > Math.abs(e.deltaY) ? e.deltaX : e.deltaY;
+            if (amount === 0)
+                return;
+            e.preventDefault();
+            if (!locked) {
+                locked = true;
+                scrollRowRef.current(amount > 0 ? 'right' : 'left');
+            }
+            armUnlock();
+        };
+        const onKeyDown = (e) => {
+            if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight')
+                return;
+            if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey)
+                return;
+            const target = e.target;
+            const tag = target?.tagName;
+            if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT' || target?.isContentEditable)
+                return;
+            scrollRowRef.current(e.key === 'ArrowRight' ? 'right' : 'left');
+        };
+        container.addEventListener('wheel', onWheel, { passive: false });
+        window.addEventListener('keydown', onKeyDown);
+        return () => {
+            container.removeEventListener('wheel', onWheel);
+            window.removeEventListener('keydown', onKeyDown);
+            if (unlockTimer)
+                clearTimeout(unlockTimer);
+        };
+        // `overflowContainerRef` is a stable ref object (a useRef in the host's row shell): this effect attaches once,
+        // at mount, and reads the latest `scrollRow` through `scrollRowRef` instead of re-subscribing to it.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [overflowContainerRef]);
+}

package/panels/useWorkspacePersistence.d.ts

@@ -0,0 +1,14 @@
+import type { Dispatch, SetStateAction } from 'react';
+import type { JsonValue } from '../hostApi.js';
+import type { PanelWindow } from '../panelWindow.js';
+import type { WorkspaceStorage } from '../workspaceState.js';
+/** How long the panel list must stay unchanged before it is saved. A change inside that time restarts it. */
+export declare const WORKSPACE_SAVE_QUIET_MS = 500;
+export declare function useWorkspacePersistence(i: {
+    storage: WorkspaceStorage | undefined;
+    panels: PanelWindow[];
+    setPanels: Dispatch<SetStateAction<PanelWindow[]>>;
+    rootId: string;
+    freshId: () => string;
+    defaultHostData: (() => JsonValue) | undefined;
+}): void;

package/panels/useWorkspacePersistence.js

@@ -0,0 +1,74 @@
+/**
+ * Keeps the panel list between launches through a host's `WorkspaceStorage`: one restore at mount, then a
+ * debounced save of every committed change. With no storage it does nothing: no state, no promise, no timer.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { computeRowOrder } from '../panelRowOrder.js';
+import { hydrateWorkspaceState, isWorkspaceState, projectWorkspaceState } from '../workspaceState.js';
+/** How long the panel list must stay unchanged before it is saved. A change inside that time restarts it. */
+export const WORKSPACE_SAVE_QUIET_MS = 500;
+export function useWorkspacePersistence(i) {
+    const { panels, setPanels } = i;
+    // Everything but the list itself is read once, at mount.
+    const { storage, rootId, freshId, defaultHostData } = useRef(i).current;
+    // State, not a ref: opening the gate must re-run the save effect, or a change committed while load() was
+    // pending (with nothing to restore) would never be saved.
+    const [settled, setSettled] = useState(false);
+    // The JSON last saved or restored; a projection equal to it is not saved again.
+    const lastSaved = useRef(null);
+    useEffect(() => {
+        if (storage === undefined)
+            return;
+        // StrictMode runs this effect twice; only the run that is not cancelled may apply its result.
+        let cancelled = false;
+        // The executor runs at once, so a load() that throws reads as a rejection: no saved state.
+        new Promise((resolve) => resolve(storage.load())).then((loaded) => {
+            if (cancelled)
+                return;
+            let restored = [];
+            if (loaded !== null) {
+                if (isWorkspaceState(loaded)) {
+                    // Drawn here, never inside an updater: React may run an updater twice.
+                    restored = hydrateWorkspaceState(loaded, freshId, rootId).map((p) => {
+                        const hostData = defaultHostData?.();
+                        return hostData === undefined ? p : { ...p, hostData };
+                    });
+                }
+                else {
+                    console.warn('Ignored the saved workspace: it is not a version 1 workspace file.');
+                }
+            }
+            // The baseline is what the restored list projects to, not the file: saved ids differ from fresh ones,
+            // and comparing against the file would save at every launch.
+            lastSaved.current = JSON.stringify(projectWorkspaceState(restored, rootId));
+            // Appended after what is already there, so a panel created while load() was pending survives.
+            if (restored.length > 0)
+                setPanels((prev) => computeRowOrder([...prev, ...restored], rootId));
+            setSettled(true);
+        }, () => {
+            if (cancelled)
+                return;
+            lastSaved.current = JSON.stringify(projectWorkspaceState([], rootId));
+            setSettled(true);
+        });
+        return () => {
+            cancelled = true;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- mount only: the inputs are read once
+    }, []);
+    useEffect(() => {
+        if (storage === undefined || !settled)
+            return;
+        const state = projectWorkspaceState(panels, rootId);
+        const json = JSON.stringify(state);
+        if (json === lastSaved.current)
+            return;
+        // No flush on unmount or quit: a change in the last quiet period is lost, never a torn write.
+        const timer = setTimeout(() => {
+            lastSaved.current = json;
+            storage.save(state);
+        }, WORKSPACE_SAVE_QUIET_MS);
+        return () => clearTimeout(timer);
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- storage and rootId never change
+    }, [panels, settled]);
+}

package/phoneModels.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A known phone model and its CSS-pixel frame size, as PHONE_MODELS lists them for the Settings dropdown and
+ * the USB-detect prompt.
+ * @public
+ */
+export interface PhoneModel {
+    id: string;
+    label: string;
+    width: number;
+    height: number;
+}
+/**
+ * Hand-copied from phonux-app's vendor/device-specs/viewport-sizes.json; keep
+ * the two in sync by hand (that directory's README.md says which entries are verbatim). No 'default' entry:
+ * that is DEFAULT_PHONE_SIZE (hostApi.tsx), so upgrading never resizes anyone who has not chosen a model.
+ * @public
+ */
+export declare const PHONE_MODELS: readonly PhoneModel[];
+/** @public */
+export declare function findPhoneModel(id: string): PhoneModel | undefined;
+/**
+ * A short, friendly noun phrase for a just-detected USB vendor id, for the connect prompt's copy. Never more
+ * specific than "iPhone" or "Android phone": a bare USB vendor/product id cannot tell the exact model.
+ * @public
+ */
+export declare function vendorLabelForUsbVendorId(vendorId: number): string;

package/phoneModels.js

@@ -0,0 +1,43 @@
+/**
+ * A known phone model and its CSS-pixel frame size, as PHONE_MODELS lists them for the Settings dropdown and
+ * the USB-detect prompt.
+ * @public
+ */
+/**
+ * Hand-copied from phonux-app's vendor/device-specs/viewport-sizes.json; keep
+ * the two in sync by hand (that directory's README.md says which entries are verbatim). No 'default' entry:
+ * that is DEFAULT_PHONE_SIZE (hostApi.tsx), so upgrading never resizes anyone who has not chosen a model.
+ * @public
+ */
+export const PHONE_MODELS = [
+    { id: 'iphone8', label: 'iPhone 8 / SE (2nd/3rd gen) (375 × 667)', width: 375, height: 667 },
+    { id: 'iphonex', label: 'iPhone X (375 × 812)', width: 375, height: 812 },
+    { id: 'iphonexr', label: 'iPhone XR (414 × 896)', width: 414, height: 896 },
+    { id: 'iphone11', label: 'iPhone 11 (414 × 896)', width: 414, height: 896 },
+    { id: 'iphone1214', label: 'iPhone 12/13/14 (390 × 844)', width: 390, height: 844 },
+    { id: 'iphonepromax', label: 'iPhone 14/15 Pro Max (430 × 932)', width: 430, height: 932 },
+    { id: 'samsunggalaxys10', label: 'Samsung Galaxy S10 (360 × 740)', width: 360, height: 740 },
+    { id: 'galaxys21', label: 'Samsung Galaxy S21/S22 (360 × 800)', width: 360, height: 800 },
+    { id: 'galaxys23ultra', label: 'Samsung Galaxy S23 Ultra (384 × 824)', width: 384, height: 824 },
+    { id: 'googlepixel3', label: 'Google Pixel 3 (393 × 786)', width: 393, height: 786 },
+    { id: 'pixel67', label: 'Google Pixel 6/7 (412 × 915)', width: 412, height: 915 },
+    { id: 'pixel8pro', label: 'Google Pixel 8 Pro (412 × 892)', width: 412, height: 892 },
+    { id: 'oneplus11', label: 'OnePlus 11 (412 × 919)', width: 412, height: 919 },
+];
+/** @public */
+export function findPhoneModel(id) {
+    return PHONE_MODELS.find((m) => m.id === id);
+}
+/**
+ * A short, friendly noun phrase for a just-detected USB vendor id, for the connect prompt's copy. Never more
+ * specific than "iPhone" or "Android phone": a bare USB vendor/product id cannot tell the exact model.
+ * @public
+ */
+export function vendorLabelForUsbVendorId(vendorId) {
+    if (vendorId === 0x05ac)
+        return 'an iPhone';
+    const knownAndroidVendors = new Set([0x18d1, 0x04e8, 0x12d1, 0x2717, 0x2a70, 0x0bb4, 0x22b8, 0x1004, 0x0fce, 0x2ae5]);
+    if (knownAndroidVendors.has(vendorId))
+        return 'an Android phone';
+    return 'a phone';
+}

package/snapshots.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A view's picture, captured only by the host at fixed moments (park/close, History opening), never by a view.
+ * Why the DOM-redraw engine lives in the host, not here: DESIGN.md, "Snapshots: a picture is data,
+ * capturing one is not".
+ */
+import * as React from 'react';
+/** A panel's PanelSummary.id, or a fixed id ('settings' | 'history') for the non-panel columns. @public */
+export type ViewId = string;
+/** @public */
+export interface ViewSnapshot {
+    readonly viewId: ViewId;
+    /** A data: or blob: URL for an <img>; opaque -- never parsed, never persisted verbatim. */
+    readonly src: string;
+    readonly width: number;
+    /** CSS px of the VIEW photographed, not of the resulting image's pixel dimensions. */
+    readonly height: number;
+    readonly extent: 'viewport' | 'full';
+    /** Epoch ms. */
+    readonly capturedAt: number;
+    /** Marks a picture outdated by a change the host knows of (phone size, theme, panel content); nothing sets it true yet. */
+    readonly stale: boolean;
+}
+/** Read-only, and STABLE across renders unlike the rest of Host: a field rebuilt per render would re-render every view on each snapshot, not just the one showing it. @public */
+export interface SnapshotsAPI {
+    get(viewId: ViewId): ViewSnapshot | null;
+    /** For useSyncExternalStore. */
+    subscribe(viewId: ViewId, listener: () => void): () => void;
+}
+/** How a view reads a picture. Re-renders only when ITS viewId's picture changes: subscribe is keyed per id. @public */
+export declare function useViewSnapshot(viewId: ViewId): ViewSnapshot | null;
+/**
+ * How Panel hands its DOM node to the capture engine, in its own context and never on Host: every Host member lets a
+ * view act on itself or read shared state, but "hand me your DOM node" would expose its subtree to something else.
+ * @public
+ */
+export interface CaptureRegistry {
+    /** Returns an unregister function. Registering the same viewId again (e.g. a re-mount, or a body-swap) replaces the previous entry. */
+    register(viewId: ViewId, el: HTMLElement, extent: 'viewport' | 'full'): () => void;
+}
+/**
+ * What a host hands phonux to call at a park or close: (re)capture a view's picture, or drop it. phonux only says
+ * WHEN; what a capture is stays host code (see the DOM-redraw note above). @public
+ */
+export interface CaptureTrigger {
+    /** (Re)captures whatever is registered for this id; a no-op if nothing is. Never throws, even if the engine does. */
+    capture(viewId: ViewId): void;
+    /** Discard viewId's stored picture, e.g. once its undo window elapses without being restored. A no-op if nothing was stored. */
+    evict(viewId: ViewId): void;
+}
+/** The trigger a provider uses when its host supplies none: phonux never produces a real capture itself. @public */
+export declare const noopCaptureTrigger: CaptureTrigger;
+/** @public */
+export declare const CaptureRegistryContext: React.Context<CaptureRegistry | null>;
+/** Rendered only by a host that captures pictures, around HostProvider. Without it (a bare HostProvider, as in most tests) Panel registers nothing. @public */
+export declare function CaptureRegistryProvider({ registry, children }: {
+    registry: CaptureRegistry;
+    children: React.ReactNode;
+}): React.ReactElement;

package/snapshots.js

@@ -0,0 +1,22 @@
+/**
+ * A view's picture, captured only by the host at fixed moments (park/close, History opening), never by a view.
+ * Why the DOM-redraw engine lives in the host, not here: DESIGN.md, "Snapshots: a picture is data,
+ * capturing one is not".
+ */
+import * as React from 'react';
+import { useHost } from './hostApi.js';
+const NO_SNAPSHOT = null;
+/** How a view reads a picture. Re-renders only when ITS viewId's picture changes: subscribe is keyed per id. @public */
+export function useViewSnapshot(viewId) {
+    const { snapshots } = useHost();
+    // Host.snapshots is optional: a host without it shows no picture and never throws.
+    return React.useSyncExternalStore((onStoreChange) => (snapshots ? snapshots.subscribe(viewId, onStoreChange) : () => { }), () => (snapshots ? snapshots.get(viewId) : NO_SNAPSHOT), () => (snapshots ? snapshots.get(viewId) : NO_SNAPSHOT));
+}
+/** The trigger a provider uses when its host supplies none: phonux never produces a real capture itself. @public */
+export const noopCaptureTrigger = { capture: () => { }, evict: () => { } };
+/** @public */
+export const CaptureRegistryContext = React.createContext(null);
+/** Rendered only by a host that captures pictures, around HostProvider. Without it (a bare HostProvider, as in most tests) Panel registers nothing. @public */
+export function CaptureRegistryProvider({ registry, children }) {
+    return React.createElement(CaptureRegistryContext.Provider, { value: registry }, children);
+}

package/viewRegistry.d.ts

@@ -0,0 +1,23 @@
+/** Maps a panel's open-string `view` to the component that renders it. Why the fallback: DESIGN.md, "The panel-view registry". */
+import * as React from 'react';
+import type { JsonValue, PanelSummary } from './hostApi.js';
+/** A View's own props: what it reads about the panel it renders inside. @public */
+export type ViewProps<P = JsonValue> = {
+    panel: PanelSummary<P>;
+};
+/** What any View -- built-in or third-party -- is rendered as. @public */
+export type ViewComponent<P = JsonValue> = React.ComponentType<ViewProps<P>>;
+/** @public @deprecated use ViewComponent */
+export type PanelComponent<P = JsonValue> = ViewComponent<P>;
+/**
+ * Registers (or replaces) `key`'s component; this module registers nothing itself. Declare `P` with a `type`,
+ * never an `interface`: an interface has no implicit index signature, so it never satisfies `JsonValue`.
+ * @public
+ */
+export declare function registerView<P extends JsonValue>(key: string, Component: ViewComponent<P>): void;
+/** @public @deprecated use registerView */
+export declare const registerPanelView: typeof registerView;
+/** Never throws, never returns nothing: an unregistered key is a typo or a plugin missing THIS session, not a corrupt layout. @public */
+export declare function resolveView(key: string): ViewComponent;
+/** @public @deprecated use resolveView */
+export declare const resolvePanelView: typeof resolveView;

package/viewRegistry.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+const registry = new Map();
+/** One placeholder instance per unregistered key: AnimatePresence tracks a rendered element's own identity, so a fresh component type on every resolve would remount it on every render instead of once. */
+const placeholders = new Map();
+/**
+ * Registers (or replaces) `key`'s component; this module registers nothing itself. Declare `P` with a `type`,
+ * never an `interface`: an interface has no implicit index signature, so it never satisfies `JsonValue`.
+ * @public
+ */
+export function registerView(key, Component) {
+    registry.set(key, Component);
+}
+/** @public @deprecated use registerView */
+export const registerPanelView = registerView;
+function placeholderFor(key) {
+    const cached = placeholders.get(key);
+    if (cached)
+        return cached;
+    function UnregisteredPanelPlaceholder({ panel }) {
+        return (_jsxs("div", { "data-unregistered-panel-view": key, children: [_jsx("span", { children: panel.title ?? 'Untitled panel' }), _jsx("span", { "data-unregistered-panel-view-key": "", children: key })] }));
+    }
+    placeholders.set(key, UnregisteredPanelPlaceholder);
+    return UnregisteredPanelPlaceholder;
+}
+/** Never throws, never returns nothing: an unregistered key is a typo or a plugin missing THIS session, not a corrupt layout. @public */
+export function resolveView(key) {
+    return registry.get(key) ?? placeholderFor(key);
+}
+/** @public @deprecated use resolveView */
+export const resolvePanelView = resolveView;

package/viewState.d.ts

@@ -0,0 +1,32 @@
+/**
+ * useViewState: per-view state that survives the view's own panel being parked (unmounted) and revived.
+ * Why it is shaped this way: DESIGN.md, "`useViewState`: per-view state that outlives a park, not a restart".
+ */
+import * as React from 'react';
+import type { JsonValue } from './hostApi.js';
+/** Thrown by useViewState() unless it renders under BOTH wrappers a host's panel row supplies. @public */
+export declare class ViewStateMissingProviderError extends Error {
+    constructor(missing: 'host' | 'view id');
+}
+/** Mounted once by HostProvider, beside OverlayProvider. Not on the barrel: app code never needs its own store. @internal */
+export declare function ViewStateProvider({ children }: {
+    children: React.ReactNode;
+}): React.ReactElement;
+/**
+ * useViewState's type, spelled out so the public declaration names none of this file's private helpers.
+ * Callers see these call signatures, not useViewStateImpl's, so the JSON bound that counts is the one here.
+ * @public
+ */
+export interface UseViewState {
+    <T>(key: [T] extends [JsonValue] ? string : never, initial: T): [T, (next: T | ((prev: T) => T)) => void];
+    <T extends JsonValue>(key: string, initial: T): [T, (next: T | ((prev: T) => T)) => void];
+    Provider: React.Provider<string | null>;
+    useRetainOnly: (panelIds: Iterable<string>) => void;
+}
+/**
+ * The one hook a view uses for state that must survive its own panel parking and reviving: same
+ * `[value, setValue]` pair and same type inference as `React.useState`, but `initial` must be JSON-shaped.
+ * `Provider` and `useRetainOnly` are the host's side (PanelRow.tsx), never called by a view.
+ * @public
+ */
+export declare const useViewState: UseViewState;

package/viewState.js

@@ -0,0 +1,135 @@
+/**
+ * useViewState: per-view state that survives the view's own panel being parked (unmounted) and revived.
+ * Why it is shaped this way: DESIGN.md, "`useViewState`: per-view state that outlives a park, not a restart".
+ */
+import * as React from 'react';
+/** Ambient id of the panel currently rendering; read only by useViewState, set only by useViewState.Provider. */
+const ViewIdContext = React.createContext(null);
+/** Thrown by useViewState() unless it renders under BOTH wrappers a host's panel row supplies. @public */
+export class ViewStateMissingProviderError extends Error {
+    constructor(missing) {
+        super(`useViewState() was called ${missing === 'host' ? 'outside a <HostProvider>, which holds the state' : 'with no ambient view id'}. ` +
+            'A view must render where its host mounts it, under both <HostProvider> and <useViewState.Provider value={panelId}>; ' +
+            'a test calling a view\'s hooks directly must wrap it in both: ' +
+            '<HostProvider host={createFakeHost()}><useViewState.Provider value="some-id">...</useViewState.Provider></HostProvider>.');
+        this.name = 'ViewStateMissingProviderError';
+    }
+}
+/** Keyed by panel id first, so two views that pick the same key never share a cell. */
+class ViewStateStore {
+    panels = new Map();
+    /** Released while a view was still mounted (mid exit animation): dropped once its last listener leaves. */
+    released = new Set();
+    cellFor(panelId, key) {
+        let byKey = this.panels.get(panelId);
+        if (!byKey) {
+            byKey = new Map();
+            this.panels.set(panelId, byKey);
+        }
+        let cell = byKey.get(key);
+        if (!cell) {
+            cell = { value: undefined, listeners: new Set() };
+            byKey.set(key, cell);
+        }
+        return cell;
+    }
+    get(panelId, key) {
+        return this.panels.get(panelId)?.get(key)?.value;
+    }
+    set(panelId, key, value) {
+        const cell = this.cellFor(panelId, key);
+        if (cell.value === value)
+            return;
+        cell.value = value;
+        for (const listener of [...cell.listeners])
+            listener();
+    }
+    subscribe(panelId, key, listener) {
+        const cell = this.cellFor(panelId, key);
+        cell.listeners.add(listener);
+        return () => {
+            cell.listeners.delete(listener);
+            this.dropIfReleased(panelId);
+        };
+    }
+    hasPanelOutside(keep) {
+        for (const panelId of this.panels.keys())
+            if (!keep.has(panelId))
+                return true;
+        return false;
+    }
+    /** Never notifies: a still-mounted view keeps showing its value until it unmounts. */
+    releaseAllExcept(keep) {
+        for (const panelId of this.released)
+            if (keep.has(panelId))
+                this.released.delete(panelId);
+        for (const panelId of [...this.panels.keys()]) {
+            if (keep.has(panelId))
+                continue;
+            this.released.add(panelId);
+            this.dropIfReleased(panelId);
+        }
+    }
+    dropIfReleased(panelId) {
+        if (!this.released.has(panelId))
+            return;
+        for (const cell of this.panels.get(panelId)?.values() ?? [])
+            if (cell.listeners.size > 0)
+                return;
+        this.panels.delete(panelId);
+        this.released.delete(panelId);
+    }
+}
+const StoreContext = React.createContext(null);
+/** Mounted once by HostProvider, beside OverlayProvider. Not on the barrel: app code never needs its own store. @internal */
+export function ViewStateProvider({ children }) {
+    const [store] = React.useState(() => new ViewStateStore()); // pure constructor: StrictMode's double init is harmless
+    return React.createElement(StoreContext.Provider, { value: store }, children);
+}
+function useViewStateImpl(key, initial) {
+    const panelId = React.useContext(ViewIdContext);
+    const store = React.useContext(StoreContext);
+    if (store === null)
+        throw new ViewStateMissingProviderError('host');
+    if (panelId === null)
+        throw new ViewStateMissingProviderError('view id');
+    // A ref, not `initial` itself: a fresh object each render must neither change the snapshot (useSyncExternalStore
+    // needs a stable one) nor the setter's identity (useState's setter never changes).
+    const firstInitial = React.useRef(initial);
+    const read = React.useCallback(() => {
+        const stored = store.get(panelId, key);
+        return stored === undefined ? firstInitial.current : stored; // not `??`: null is a real stored value
+    }, [store, panelId, key]);
+    const subscribe = React.useCallback((onChange) => store.subscribe(panelId, key, onChange), [store, panelId, key]);
+    const value = React.useSyncExternalStore(subscribe, read, read);
+    const setValue = React.useCallback((next) => {
+        // JsonValue never includes a function, so this check can never mistake a real value for an updater.
+        store.set(panelId, key, typeof next === 'function' ? next(read()) : next);
+    }, [store, panelId, key, read]);
+    return [value, setValue];
+}
+/**
+ * For the host's panel row, once per HostProvider: `panelIds` is every panel that can still be shown again
+ * (the row's own list plus `PanelsAPI.recentlyClosed`); every other panel's state is released.
+ */
+function useRetainOnly(panelIds) {
+    const store = React.useContext(StoreContext);
+    if (store === null)
+        throw new ViewStateMissingProviderError('host');
+    const keep = new Set(panelIds);
+    React.useEffect(() => {
+        if (!store.hasPanelOutside(keep))
+            return;
+        // A task later, and cancelled by any newer commit: undoClose can commit once with a restored id in
+        // neither list (recentlyClosed already null) before the commit that puts it back in the row.
+        const timer = setTimeout(() => store.releaseAllExcept(keep), 0);
+        return () => clearTimeout(timer);
+    });
+}
+/**
+ * The one hook a view uses for state that must survive its own panel parking and reviving: same
+ * `[value, setValue]` pair and same type inference as `React.useState`, but `initial` must be JSON-shaped.
+ * `Provider` and `useRetainOnly` are the host's side (PanelRow.tsx), never called by a view.
+ * @public
+ */
+export const useViewState = Object.assign(useViewStateImpl, { Provider: ViewIdContext.Provider, useRetainOnly });

package/windowOverlay.d.ts

@@ -0,0 +1,87 @@
+/**
+ * WindowOverlay: how a view shows something over the WINDOW (a dialog, a full-screen viewer, a toast) with no
+ * host wiring and no Portal. It registers its children with a store, and the host's two OverlaySlots render
+ * them. Usage, why content is hoisted, and the numbered contract the content must keep (the layer adds no
+ * wrapper, so it cannot enforce it): DESIGN.md, "`WindowOverlay`: window-level content with no Portal".
+ * Not to be confused with Panel's `overlay` prop, which decorates ONE view and is clipped to it.
+ */
+import * as React from 'react';
+/**
+ * Where hoisted content renders (a PLACE the host chooses, never the view).
+ *   'dialog': the row's first children. Modal-ish, window-sized (scrims, dialogs, full-screen viewers).
+ *   'toast':  the window root, after the scroll container. Transient notices (snackbars).
+ * @public
+ */
+export type OverlaySlotName = 'dialog' | 'toast';
+/**
+ * The z-index each slot's content applies to ITS OWN root. WindowOverlay adds no wrapper element,
+ * so it cannot set it for you. dialog 2000 clears the host's 1400 drag strip (the Closed Pages viewer);
+ * toast 1400 is MUI's snackbar band (the undo toast).
+ * @public
+ */
+export declare const OVERLAY_Z: {
+    readonly dialog: 2000;
+    readonly toast: 1400;
+};
+/** @public */
+export interface WindowOverlayProps {
+    /** Default 'dialog'. */
+    slot?: OverlaySlotName;
+    /**
+     * Default true. false = nothing registered, removed IMMEDIATELY. Content that must animate out
+     * (MUI Snackbar) stays registered and takes its own `open`.
+     */
+    open?: boolean;
+    children: React.ReactNode;
+}
+/** @public */
+export interface Entry {
+    slot: OverlaySlotName;
+    node: React.ReactNode;
+}
+/** @public */
+export interface Item {
+    id: string;
+    node: React.ReactNode;
+}
+/** External store, NOT React state: a registration re-renders neither the host nor any view. @public */
+export declare class OverlayStore {
+    private entries;
+    private listeners;
+    private slots;
+    private warned;
+    private snap;
+    /** Count of listener notifications (test seam: pins the same-node short-circuit). */
+    notifications: number;
+    set(id: string, entry: Entry): void;
+    remove(id: string): void;
+    mountSlot(name: OverlaySlotName): () => void;
+    hasSlot(name: OverlaySlotName): boolean;
+    /** True once per slot name per store: the caller logs the "no slot" error only the first time. */
+    firstWarning(name: OverlaySlotName): boolean;
+    subscribe: (l: () => void) => (() => void);
+    read(slot: OverlaySlotName): readonly Item[];
+    /** Ids in registration order across both slots (test seam). */
+    ids(): string[];
+    private rebuild;
+    private emit;
+}
+/**
+ * Rendered by HostProvider, so a host adds nothing. The store is never part of the app-supplied Host bag
+ * (nothing about an overlay is app-specific). `store` is a TEST SEAM: a test passes its own to read `notifications`/`ids()`.
+ * @public
+ */
+export declare function OverlayProvider({ children, store: injected }: {
+    children: React.ReactNode;
+    store?: OverlayStore;
+}): React.JSX.Element;
+/** Mounted by the HOST once per slot. Emits NO element: hoisted overlays become its parent's direct children. @public */
+export declare const OverlaySlot: React.NamedExoticComponent<{
+    name: OverlaySlotName;
+}>;
+/**
+ * Render this anywhere in a view, at any depth. Its children appear in the matching OverlaySlot.
+ * With no provider, or under renderToStaticMarkup (no effects), the children render IN PLACE instead.
+ * @public
+ */
+export declare function WindowOverlay({ slot, open, children }: WindowOverlayProps): React.JSX.Element | null;