phonux 0.1.0

package/dragToClose.js

@@ -0,0 +1,151 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Drag a view's grab handle DOWN to close it; with `reorder`, also sideways to reorder. It knows nothing about
+ * panels or the app. onClose MUST remove the view: a close never unlocks the scroll ancestors. Also offer a
+ * button calling the same onClose (WCAG 2.5.7). The full contract: DESIGN.md, "`DragToClose`".
+ */
+import * as React from 'react';
+import { animate, motion, useDragControls, useIsPresent, useMotionValue, useReducedMotion } from 'motion/react';
+/** The first this many px of either axis decide which one the gesture locks to. */
+const DIRECTION_LOCK_PX = 8;
+/** The tunables, in one place. Distances in px, velocities in px/s, positive = downward. @public */
+export const DRAG_CLOSE = {
+    /** Close once dragged this fraction of the view's height ... */
+    distanceFraction: 0.25,
+    /** ... but never less than this: a click that slips a few px is not a close. */
+    minDistancePx: 80,
+    /** A flick closes early: at least this fast at release ... */
+    flickVelocity: 700,
+    /** ... and at least this far. */
+    flickMinDistancePx: 40,
+    /** Released while moving back UP faster than this (negative): the user changed their mind. */
+    cancelVelocity: -300,
+    /** Seconds the box takes to leave the screen. */
+    exitSeconds: 0.18,
+    snapBack: { type: 'spring', stiffness: 520, damping: 42 },
+};
+/** The whole close rule, pure. Never closes on an upward or zero offset, or when released moving back up. @public */
+export function shouldCloseOnRelease({ offsetY, velocityY, height }) {
+    if (!(offsetY > 0) || velocityY <= DRAG_CLOSE.cancelVelocity)
+        return false;
+    const distance = Math.max(DRAG_CLOSE.minDistancePx, DRAG_CLOSE.distanceFraction * (Number.isFinite(height) ? height : 0));
+    if (offsetY >= distance)
+        return true;
+    return offsetY >= DRAG_CLOSE.flickMinDistancePx && velocityY >= DRAG_CLOSE.flickVelocity;
+}
+const INTERACTIVE = 'button, a, input, select, textarea, [role="button"]';
+/** @public */
+export function DragToClose({ onClose, reorder, children, }) {
+    const controls = useDragControls();
+    const y = useMotionValue(0);
+    const x = useMotionValue(0);
+    const box = React.useRef(null);
+    const reduceMotion = useReducedMotion();
+    const running = React.useRef(null);
+    const locked = React.useRef([]);
+    const closeRef = React.useRef(onClose);
+    closeRef.current = onClose;
+    const closing = React.useRef(false); // a release has decided to close: the exit runs and takes no more presses
+    // Set once the first DIRECTION_LOCK_PX decides; null until then, and always for a vertical-only handle.
+    const axisLock = React.useRef(null);
+    // overflow-y: hidden while a drag is live: the transformed box would otherwise add a scrollbar.
+    const lockScrollParents = () => {
+        for (let el = box.current?.parentElement ?? null; el; el = el.parentElement) {
+            const overflowY = window.getComputedStyle(el).overflowY;
+            if (overflowY === 'auto' || overflowY === 'scroll') {
+                locked.current.push([el, el.style.overflowY]);
+                el.style.overflowY = 'hidden';
+            }
+        }
+    };
+    const unlockScrollParents = () => {
+        for (const [el, previous] of locked.current.splice(0))
+            el.style.overflowY = previous;
+    };
+    React.useEffect(() => () => {
+        running.current?.stop();
+        unlockScrollParents();
+    }, []);
+    // An undo while AnimatePresence still holds this box revives the SAME instance: parked, locked, refusing presses. A layout effect that
+    // writes the DOM itself, not on Motion's next frame: the host scrolls a revived view into view in this same commit and must find it at rest.
+    const isPresent = useIsPresent();
+    const wasPresent = React.useRef(true);
+    React.useLayoutEffect(() => {
+        const revived = isPresent && !wasPresent.current;
+        wasPresent.current = isPresent;
+        if (!revived)
+            return;
+        closing.current = false;
+        unlockScrollParents();
+        y.jump(0); // also stops an exit that is still running: its end would call onClose for a box that is back
+        x.jump(0);
+        if (box.current)
+            box.current.style.transform = 'none';
+    }, [isPresent]);
+    const handle = {
+        onPointerDown: (event) => {
+            if (event.button !== 0 || event.target.closest(INTERACTIVE) || closing.current)
+                return; // a press would stop the exit: onClose would never run
+            if (running.current) {
+                running.current.stop();
+                running.current = null;
+                unlockScrollParents();
+            } // stop() never settles the spring's promise, so its own unlock would not run
+            controls.start(event); // a real drag locks again in onDragStart
+        },
+        // pan-x: a horizontal swipe still scrolls the row; a vertical one is this gesture's.
+        sx: { cursor: 'grab', touchAction: 'pan-x', userSelect: 'none', '&:active': { cursor: 'grabbing' } },
+    };
+    return (_jsx(motion.div, { ref: box, "data-drag-to-close": "", drag: reorder ? true : 'y', dragControls: controls, dragListener: false, dragMomentum: false, dragConstraints: { top: 0, bottom: 0 }, dragElastic: { top: 0, bottom: 1 }, style: reorder ? { x, y } : { y }, onDragStart: () => {
+            axisLock.current = null;
+            lockScrollParents();
+        }, onDrag: reorder
+            ? (_event, info) => {
+                if (axisLock.current === null && (Math.abs(info.offset.x) >= DIRECTION_LOCK_PX || Math.abs(info.offset.y) >= DIRECTION_LOCK_PX)) {
+                    axisLock.current = Math.abs(info.offset.x) >= Math.abs(info.offset.y) ? 'x' : 'y';
+                }
+                // Zero the losing axis every tick instead of toggling `drag`: Motion keeps reading the axis prop's
+                // value from before the gesture began.
+                if (axisLock.current === 'x')
+                    y.set(0);
+                else if (axisLock.current === 'y')
+                    x.set(0);
+            }
+            : undefined, onDragEnd: (_event, info) => {
+            const lockedAxis = axisLock.current;
+            axisLock.current = null;
+            if (reorder && lockedAxis === 'x') {
+                reorder.onDragEnd(info.offset.x);
+                if (reduceMotion) {
+                    x.jump(0); // jump, not set: it also stops the inertia Motion itself just started on x
+                    return unlockScrollParents();
+                }
+                const back = animate(x, 0, DRAG_CLOSE.snapBack);
+                running.current = back;
+                void back.then(unlockScrollParents);
+                return; // never a close: shouldCloseOnRelease is not even consulted for a horizontal-locked release
+            }
+            if (reorder)
+                x.jump(0); // residual sub-threshold horizontal drift from a gesture that never locked (or locked vertical)
+            const rect = box.current?.getBoundingClientRect();
+            const height = rect?.height ?? 0;
+            if (shouldCloseOnRelease({ offsetY: info.offset.y, velocityY: info.velocity.y, height })) {
+                if (reduceMotion)
+                    return closeRef.current();
+                const toBottom = Math.max(height, window.innerHeight - (rect?.top ?? 0));
+                const exit = animate(y, toBottom, { duration: DRAG_CLOSE.exitSeconds, ease: 'easeIn' });
+                running.current = exit;
+                closing.current = true;
+                void exit.then(() => closeRef.current());
+            }
+            else if (reduceMotion) {
+                animate(y, 0, { duration: 0 }); // not y.set(0): Motion's own constraint return is animating y and would win
+                unlockScrollParents();
+            }
+            else {
+                const back = animate(y, 0, DRAG_CLOSE.snapBack);
+                running.current = back;
+                void back.then(unlockScrollParents);
+            }
+        }, children: children(handle) }));
+}

package/fakeHost.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Recording fakes of every API in hostApi.tsx, for testing a view with no host and no desktop bridge:
+ * `createFakeHost({ panels: { panelList: [...] } })`, render under `<HostProvider>`, interact, then assert on
+ * `host.calls`. Every method records `{ api, method, args }` in call order and does nothing else (async ones
+ * resolve). The fakes hold no state: a test wanting a different live value re-renders with new overrides. An
+ * override replaces a whole member (a nested object such as `closedPagesViewer` too), and an overridden
+ * method no longer records. Why it lives here: DESIGN.md, "Testing without a host".
+ */
+import { type Host } from './hostApi.js';
+export type { Host, PhoneSize, DetectedPhone, ClosedPageEntry, JsonValue, FormFactor, PanelSize, PanelSummary, CreatePanelOptions, SettingsAPI, HistoryAPI, PanelsAPI, PhoneDeviceAPI } from './hostApi.js';
+export type { SnapshotsAPI, ViewId, ViewSnapshot } from './snapshots.js';
+export type { PhoneModel } from './phoneModels.js';
+/** @public */
+export interface FakeCall {
+    api: keyof Host;
+    method: string;
+    args: unknown[];
+}
+/** Replacement members, per API. @public */
+export type FakeOverrides = {
+    [K in keyof Host]?: Partial<Host[K]>;
+};
+/** @public */
+export interface FakeHost extends Host {
+    /** Every method call any of the fakes received, in order. */
+    readonly calls: FakeCall[];
+}
+/** @public @deprecated use FakeHost */
+export type FakePhoneAPIs = FakeHost;
+/** @public */
+export declare function createFakeHost(overrides?: FakeOverrides): FakeHost;
+/** @public @deprecated use createFakeHost -- same function, so identity checks keep working. */
+export declare const createFakePhoneAPIs: typeof createFakeHost;

package/fakeHost.js

@@ -0,0 +1,85 @@
+/**
+ * Recording fakes of every API in hostApi.tsx, for testing a view with no host and no desktop bridge:
+ * `createFakeHost({ panels: { panelList: [...] } })`, render under `<HostProvider>`, interact, then assert on
+ * `host.calls`. Every method records `{ api, method, args }` in call order and does nothing else (async ones
+ * resolve). The fakes hold no state: a test wanting a different live value re-renders with new overrides. An
+ * override replaces a whole member (a nested object such as `closedPagesViewer` too), and an overridden
+ * method no longer records. Why it lives here: DESIGN.md, "Testing without a host".
+ */
+import { PHONE_MODELS } from './phoneModels.js';
+import { DEFAULT_PHONE_SIZE, } from './hostApi.js';
+/** @public */
+export function createFakeHost(overrides = {}) {
+    const calls = [];
+    const log = (api, method, args) => {
+        calls.push({ api, method, args });
+    };
+    const settings = {
+        maxPanelsOnScreen: null,
+        fitCount: 4,
+        // Matches the app's own single-fixed-column (History-only) default; a test with more permanent columns
+        // overrides this explicitly.
+        minPanelsOnScreen: 2,
+        setMaxPanelsOnScreen: async (n) => log('settings', 'setMaxPanelsOnScreen', [n]),
+        settingsColumn: {
+            visible: false,
+            show: () => log('settings', 'settingsColumn.show', []),
+            hide: () => log('settings', 'settingsColumn.hide', []),
+        },
+    };
+    const history = {
+        loadClosedPages: async () => {
+            log('history', 'loadClosedPages', []);
+            return [];
+        },
+        closedPagesViewer: {
+            isOpen: false,
+            loading: false,
+            entries: [],
+            open: () => log('history', 'closedPagesViewer.open', []),
+            close: () => log('history', 'closedPagesViewer.close', []),
+        },
+        locked: true,
+        closed: false,
+        close: () => log('history', 'close', []),
+    };
+    const panels = {
+        panelList: [],
+        // Explicitly optional (not inferred from PanelsAPI's own overloaded `create`): an inferred-required
+        // parameter would no longer satisfy the interface's zero-arg overload.
+        create: (options) => log('panels', 'create', options !== undefined ? [options] : []),
+        activate: (id) => log('panels', 'activate', [id]),
+        move: (id, direction) => log('panels', 'move', [id, direction]),
+        setFormFactor: (id, next) => log('panels', 'setFormFactor', [id, next]),
+        reanchor: (id, anchor) => log('panels', 'reanchor', [id, anchor]),
+        close: (id) => log('panels', 'close', [id]),
+        recentlyClosed: null,
+        undoClose: () => log('panels', 'undoClose', []),
+        clearAll: () => log('panels', 'clearAll', []),
+    };
+    // Never logs, unlike every other member: React calls get()/subscribe() on every render, so logging would add
+    // `calls` entries to every test that merely renders a capturable Panel. get() always answers null.
+    const snapshots = {
+        get: () => null,
+        subscribe: () => () => { },
+    };
+    const device = {
+        size: DEFAULT_PHONE_SIZE,
+        defaultSize: DEFAULT_PHONE_SIZE,
+        models: PHONE_MODELS,
+        chooseModel: async (modelId) => log('device', 'chooseModel', [modelId]),
+        detectedPhone: null,
+        dismissDetectedPhone: () => log('device', 'dismissDetectedPhone', []),
+        resizeForDetectedPhone: (modelId) => log('device', 'resizeForDetectedPhone', [modelId]),
+    };
+    return {
+        settings: { ...settings, ...overrides.settings },
+        history: { ...history, ...overrides.history },
+        panels: { ...panels, ...overrides.panels },
+        device: { ...device, ...overrides.device },
+        snapshots: { ...snapshots, ...overrides.snapshots },
+        calls,
+    };
+}
+/** @public @deprecated use createFakeHost -- same function, so identity checks keep working. */
+export const createFakePhoneAPIs = createFakeHost;

package/hostApi.d.ts

@@ -0,0 +1,247 @@
+/**
+ * The public surface a view is written against: any component rendering a phone-shaped column
+ * (Settings, History, a live panel, or a third party's) reads what it needs from `useHost()`,
+ * renders a `<Panel>`, and never touches the desktop bridge, `localStorage` or any other app
+ * internal (see DESIGN.md). The host mounts ONE `<HostProvider>`; a test uses the same provider
+ * with `fakeHost.ts`'s fakes. The provider value is REBUILT EVERY RENDER (see HostProvider).
+ */
+import * as React from 'react';
+import type { PhoneModel } from './phoneModels.js';
+import type { SnapshotsAPI } from './snapshots.js';
+/** A phone size. `modelId` 'default' means the app's built-in size, not a PHONE_MODELS entry. @public */
+export interface PhoneSize {
+    modelId: string;
+    width: number;
+    height: number;
+}
+/** The app's built-in size: upgrading must never silently resize anyone who has not chosen a model. @public */
+export declare const DEFAULT_PHONE_SIZE: PhoneSize;
+/** A phone-like USB device the app has just seen for the first time. @public */
+export interface DetectedPhone {
+    vendorId: number;
+    productId: number;
+}
+/** One entry of the persisted "Closed Pages" log. @public */
+export interface ClosedPageEntry {
+    id: string;
+    title: string;
+    url: string;
+    /** ISO-8601, UTC. */
+    closedAt: string;
+}
+/** JSON-serializable by construction -- the minimum shape any future persistence layer could round-trip (see DESIGN.md). @public */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/** A panel's own visual tier. The app gives every panel 'phone' by default. @public */
+export type FormFactor = 'phone' | 'tablet' | 'desktop';
+/**
+ * A panel's own rendered size, carrying its tier alongside the pixels so a size value stays meaningful on its
+ * own (e.g. passed to Panel/PanelFrame's optional `size` prop without also passing a separate formFactor).
+ * `height: 'fill'` lets a tier fill its container's height instead of a fixed pixel value.
+ * @public
+ */
+export interface PanelSize {
+    formFactor: FormFactor;
+    width: number;
+    height: number | 'fill';
+}
+/**
+ * What a view may know about a panel. The app's own panel record is structurally assignable to it.
+ * `formFactor`/`size` are optional so a hand-built or third-party summary without them stays valid, even
+ * though every panel the app itself creates carries both -- see DESIGN.md.
+ * @public
+ */
+export interface PanelSummary<P = JsonValue> {
+    readonly id: string;
+    readonly url: string;
+    readonly title?: string;
+    /** Mounted in the row now (false = parked, listed in History only). */
+    readonly live: boolean;
+    /** Whether a drag-down close is offered for this panel. A live/spawned panel is always false. */
+    readonly locked: boolean;
+    /** Opaque per-panel data a create() caller supplied; undefined for built-ins. */
+    readonly params?: P;
+    /** This panel's own visual tier. */
+    readonly formFactor?: FormFactor;
+    /** This panel's own rendered size. Panel/PanelFrame do not read it: a view passes it to their separate `size` prop for a non-phone tier (a phone panel follows useHost().device.size instead). */
+    readonly size?: PanelSize;
+}
+/** @public */
+export interface SettingsAPI {
+    /** The stored "max panels on screen" choice: `null` means "follow the fit count" (the default). Live: a view re-renders when it changes. */
+    readonly maxPanelsOnScreen: number | null;
+    /** How many panels (History plus web panels together) the window can currently show -- `null` while unmeasured (no cap yet). */
+    readonly fitCount: number | null;
+    /** The lowest legal `maxPanelsOnScreen` choice: every permanent column (`collapsible:false`) plus at least one web panel. Never below 2 (History alone already counts as one). */
+    readonly minPanelsOnScreen: number;
+    /** Clamped to [minPanelsOnScreen, fitCount] on read; `null` resets to "follow the fit count". Applies at once, then persists. Never rejects: with no desktop bridge the choice lasts this session only. */
+    setMaxPanelsOnScreen(n: number | null): Promise<void>;
+    /** Settings' own sections render inside History's body when this is true (History's gear toggles it), rather than as a separate column. Starts false: a fresh session opens on History's own row list. `show()`/`hide()` last for the session. */
+    readonly settingsColumn: {
+        readonly visible: boolean;
+        show(): void;
+        hide(): void;
+    };
+}
+/** @public */
+export interface HistoryAPI {
+    /** The persisted Closed Pages log (every view ever closed, oldest first). NEVER rejects: any failure, including no desktop bridge, resolves to []. */
+    loadClosedPages(): Promise<readonly ClosedPageEntry[]>;
+    /** The Closed Pages overlay. `open()` (re)fetches through loadClosedPages(). */
+    readonly closedPagesViewer: {
+        readonly isOpen: boolean;
+        readonly loading: boolean;
+        readonly entries: readonly ClosedPageEntry[];
+        open(): void;
+        close(): void;
+    };
+    /** Whether a drag-down close or an API close does anything for History; defaults true. */
+    readonly locked: boolean;
+    readonly closed: boolean;
+    /** A no-op while `locked` (today, always -- see `locked`). */
+    close(): void;
+}
+/**
+ * `PanelsAPI.create`'s options bag, named so useProvidePanels.ts and fakeHost.ts can each annotate
+ * their own `options` parameter explicitly (see `create`'s overload comment).
+ * @public
+ */
+export interface CreatePanelOptions {
+    view?: string;
+    title?: string;
+    params?: JsonValue;
+    listed?: boolean;
+    /** Where the new entry sits: on `position`'s side of `panel` (default History), `priority` lower = nearer (default: past the far end of that side). Default `{ position: 'right' }`. */
+    anchor?: {
+        panel?: string;
+        position: 'left' | 'right';
+        priority?: number;
+    };
+    /** Which stacking tier the new entry's row slot sits in. Default 'base'. */
+    layer?: 'base' | 'raised';
+    /** Whether the new entry's reappearance always resolves through the anchor formula instead of unconditionally entering from the right. Default false. */
+    anchoredEnter?: boolean;
+    /**
+     * Makes the new entry a permanent column: `collapsible:false` (never parked by a row gesture or capacity,
+     * never a drag source, and counted in `minPanelsOnScreen`'s floor) and `listed:false`, forced regardless of
+     * any `listed` also passed -- a permanent column must supply its own close control (History's own
+     * precedent), never the framework's History-row trash. `locked` stays false always: closing it through its
+     * own control still works. Default false.
+     */
+    permanent?: boolean;
+    /** The new panel's tier (see `setFormFactor`). Ignored with `permanent`: a permanent column is always 'phone'. Default 'phone'. */
+    formFactor?: FormFactor;
+}
+/** @public */
+export interface PanelsAPI {
+    /** Every panel, live or parked, in array order. History lists them as given; the row shows the live ones. */
+    readonly panelList: readonly PanelSummary[];
+    /**
+     * Appends a live panel; zero-arg is the blank-web-panel default. `view` selects the rendered component
+     * (registerView/resolveView) -- an unregistered key renders a placeholder, never a crash. No raw
+     * `collapsible`/`locked` key: `permanent` (CreatePanelOptions) is the only door to a permanent column, and
+     * `locked` is never settable at all. At capacity, the live panel farthest from it is parked, as for any
+     * non-permanent panel.
+     */
+    create(): void;
+    /**
+     * Two overloads, not one `create(options?: CreatePanelOptions)` -- see DESIGN.md for why a single
+     * optional-arg signature would collide with a bare `onClick={panels.create}` reference.
+     */
+    create(options: CreatePanelOptions): void;
+    /** Make a panel live in place, without reordering the row. May park the live panel farthest from it. */
+    activate(id: string): void;
+    /**
+     * Moves `id` one row-slot toward `direction`, swapping past whichever OTHER currently-shown panel sits there,
+     * History and any permanent column included -- the row's drag-to-reorder gesture calls this underneath. Every
+     * panel is then re-anchored to History where it stands. No-op for an id that is unknown, parked, itself a
+     * permanent column (e.g. History), or already at that edge of the row.
+     */
+    move(id: string, direction: 'left' | 'right'): void;
+    /**
+     * Resizes `id` to `next`'s tier in place: it stays mounted and live, its content the same node, and the row
+     * reflows around it. If the row no longer fits, OTHER panels park, never this one -- also when one handler
+     * resizes, opens or activates several panels, unless the earlier of them already fill the row. No-op for an
+     * unknown id, a permanent column (e.g. History), or a panel already at `next`. See DESIGN.md for the tiers.
+     */
+    setFormFactor(id: string, next: FormFactor): void;
+    /**
+     * Re-places `id`, live or parked, by `anchor` (defaults as for CreatePanelOptions.anchor) and reorders the row
+     * to match. On its own it never parks or reveals: which panels fit depends on their widths, never their order.
+     * No-op for an unknown id or a permanent column (e.g. History). See DESIGN.md for the anchor model.
+     */
+    reanchor(id: string, anchor: {
+        panel?: string;
+        position: 'left' | 'right';
+        priority?: number;
+    }): void;
+    /** Close a view completely, live or parked: it leaves the row and History at once, a closed event is appended to the persisted log (HistoryAPI), and it can be undone for 10 s (recentlyClosed, undoClose). Also accepts History's own fixed-panel id (HistoryAPI.close is the same mechanism, offered per-panel so a view need not know the id) -- an id not in `panelList` and not History's id, or a LOCKED fixed panel's id, does nothing. */
+    close(id: string): void;
+    /** The views closed within the current undo window, oldest first; non-null exactly while it is open (10 s after the LAST close). Drives the "Closed N pages / Undo" toast. */
+    readonly recentlyClosed: readonly PanelSummary[] | null;
+    /** Undo every close in `recentlyClosed`: each view returns at its old place (a live one comes back live, parking the live one farthest from it if the row is full) and its log entry is removed. Does nothing when the window is closed. */
+    undoClose(): void;
+    /** Forget every panel. Not logged and not undoable. */
+    clearAll(): void;
+}
+/** @public */
+export interface PhoneDeviceAPI {
+    /** The size every PanelFrame renders at. Live. */
+    readonly size: PhoneSize;
+    /** The built-in size (`modelId` 'default'), for a "Default (390 × 700)" choice. */
+    readonly defaultSize: PhoneSize;
+    /** Selectable models. 'default' is not among them. */
+    readonly models: readonly PhoneModel[];
+    /** Applies at once, then persists. 'default' resets. Never rejects: with no desktop bridge the choice lasts this session only. */
+    chooseModel(modelId: string): Promise<void>;
+    /** Non-null exactly while the one-time "phone connected" notice should show. */
+    readonly detectedPhone: DetectedPhone | null;
+    dismissDetectedPhone(): void;
+    /** Resize to `modelId` and dismiss the notice. */
+    resizeForDetectedPhone(modelId: string): void;
+}
+/** @public @deprecated use PhoneDeviceAPI */
+export type DeviceAPI = PhoneDeviceAPI;
+/** @public */
+export interface Host {
+    readonly settings: SettingsAPI;
+    readonly history: HistoryAPI;
+    readonly panels: PanelsAPI;
+    readonly device: PhoneDeviceAPI;
+    /** Optional, unlike every other member: without it useViewSnapshot (snapshots.ts) shows no picture instead
+     * of throwing, so a host that does not capture need not supply a no-op. */
+    readonly snapshots?: SnapshotsAPI;
+}
+/** @public @deprecated use Host */
+export type PhoneAPIs = Host;
+/** Thrown by useHost() when no provider is mounted, so a view rendered without a host fails loudly instead of rendering defaults. @public */
+export declare class HostMissingProviderError extends Error {
+    constructor(hook?: string);
+}
+/** @public @deprecated use HostMissingProviderError -- same class, so `instanceof` works under either name. */
+export declare const PhoneAPIsMissingProviderError: typeof HostMissingProviderError;
+/**
+ * Mount once, at the host. `host` is passed straight through as the context
+ * value: NEVER memoise it here or where it is built. The handlers behind it
+ * close over render-time state (the panel list, the column count), so a
+ * memoised bag hands views stale closures.
+ * @public
+ */
+export declare function HostProvider({ host, children }: {
+    host: Host;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/**
+ * @deprecated use HostProvider (its prop is `host`, not `apis`). This is a distinct thin wrapper, not the
+ * same value as HostProvider, because the prop itself renamed.
+ * @public
+ */
+export declare function PhoneAPIsProvider({ apis, children }: {
+    apis: Host;
+    children: React.ReactNode;
+}): React.JSX.Element;
+/** The one hook a view uses to reach the rest of the app. Call API methods from event handlers; do not capture one in an effect with empty deps. @public */
+export declare function useHost(): Host;
+/** @public @deprecated use useHost -- same function, so identity checks keep working. */
+export declare const usePhoneAPIs: typeof useHost;

package/hostApi.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The public surface a view is written against: any component rendering a phone-shaped column
+ * (Settings, History, a live panel, or a third party's) reads what it needs from `useHost()`,
+ * renders a `<Panel>`, and never touches the desktop bridge, `localStorage` or any other app
+ * internal (see DESIGN.md). The host mounts ONE `<HostProvider>`; a test uses the same provider
+ * with `fakeHost.ts`'s fakes. The provider value is REBUILT EVERY RENDER (see HostProvider).
+ */
+import * as React from 'react';
+import { OverlayProvider } from './windowOverlay.js';
+import { ViewStateProvider } from './viewState.js';
+/** The app's built-in size: upgrading must never silently resize anyone who has not chosen a model. @public */
+export const DEFAULT_PHONE_SIZE = { modelId: 'default', width: 390, height: 700 };
+// ---------------------------------------------------------------------------
+// Provider and hook
+// ---------------------------------------------------------------------------
+/** Thrown by useHost() when no provider is mounted, so a view rendered without a host fails loudly instead of rendering defaults. @public */
+export class HostMissingProviderError extends Error {
+    constructor(hook = 'useHost') {
+        super(`${hook}() was called outside a <HostProvider>. A view must render under the provider the host mounts; ` +
+            'in a test, wrap it in <HostProvider host={createFakeHost()}> (createFakeHost comes from the phonux/testing entry point).');
+        this.name = 'HostMissingProviderError';
+    }
+}
+/** @public @deprecated use HostMissingProviderError -- same class, so `instanceof` works under either name. */
+export const PhoneAPIsMissingProviderError = HostMissingProviderError;
+const HostContext = React.createContext(null);
+/**
+ * Mount once, at the host. `host` is passed straight through as the context
+ * value: NEVER memoise it here or where it is built. The handlers behind it
+ * close over render-time state (the panel list, the column count), so a
+ * memoised bag hands views stale closures.
+ * @public
+ */
+export function HostProvider({ host, children }) {
+    return (_jsx(HostContext.Provider, { value: host, children: _jsx(OverlayProvider, { children: _jsx(ViewStateProvider, { children: children }) }) }));
+}
+/**
+ * @deprecated use HostProvider (its prop is `host`, not `apis`). This is a distinct thin wrapper, not the
+ * same value as HostProvider, because the prop itself renamed.
+ * @public
+ */
+export function PhoneAPIsProvider({ apis, children }) {
+    return _jsx(HostProvider, { host: apis, children: children });
+}
+/** The one hook a view uses to reach the rest of the app. Call API methods from event handlers; do not capture one in an effect with empty deps. @public */
+export function useHost() {
+    const host = React.useContext(HostContext);
+    if (host === null)
+        throw new HostMissingProviderError();
+    return host;
+}
+/** @public @deprecated use useHost -- same function, so identity checks keep working. */
+export const usePhoneAPIs = useHost;

package/index.d.ts

@@ -0,0 +1,46 @@
+export { DEFAULT_PHONE_SIZE, HostMissingProviderError, HostProvider, useHost, } from './hostApi.js';
+export type { PhoneSize, DetectedPhone, ClosedPageEntry, JsonValue, FormFactor, PanelSize, PanelSummary, CreatePanelOptions, SettingsAPI, HistoryAPI, PanelsAPI, PhoneDeviceAPI, Host, } from './hostApi.js';
+export { useViewSnapshot, CaptureRegistryContext, CaptureRegistryProvider, noopCaptureTrigger } from './snapshots.js';
+export type { ViewId, ViewSnapshot, SnapshotsAPI, CaptureRegistry, CaptureTrigger } from './snapshots.js';
+export { useViewState, ViewStateMissingProviderError } from './viewState.js';
+export type { UseViewState } from './viewState.js';
+export { PhoneAPIsMissingProviderError, PhoneAPIsProvider, usePhoneAPIs, } from './hostApi.js';
+export type { DeviceAPI, PhoneAPIs } from './hostApi.js';
+export { registerView, resolveView } from './viewRegistry.js';
+export type { ViewComponent, ViewProps } from './viewRegistry.js';
+/** @deprecated use registerView/resolveView/ViewComponent */
+export { registerPanelView, resolvePanelView } from './viewRegistry.js';
+export type { PanelComponent } from './viewRegistry.js';
+export { Panel, DRAG_CLOSE, DragToClose, shouldCloseOnRelease, WindowOverlay, OverlaySlot, OVERLAY_Z, OverlayProvider, OverlayStore, } from './Panel.js';
+export type { PanelProps, DragHandleProps, ReleaseMeasure, ReorderHandle, OverlaySlotName, WindowOverlayProps, Item, Entry, } from './Panel.js';
+/** @deprecated use Panel/PanelProps */
+export { PhoneView } from './Panel.js';
+export type { PhoneViewProps } from './Panel.js';
+export { default as PanelFrame } from './PanelFrame.js';
+export { PANEL_CORNER_RADIUS_UNITS, panelCornerRadiusPx, panelFrameScrollSx, panelFrameBareSx, PanelHeader, PanelHeaderRow, } from './PanelFrame.js';
+export type { PanelFrameProps, PanelHeaderProps, PanelHeaderRowProps, } from './PanelFrame.js';
+/** @deprecated use PanelFrame, PanelHeader, PanelHeaderRow and their PANEL_ and panel-prefixed siblings above */
+export { default as PhoneFrame } from './PanelFrame.js';
+export { PHONE_CORNER_RADIUS_UNITS, phoneCornerRadiusPx, phoneFrameScrollSx, phoneFrameBareSx, PhoneFrameHeader, PhoneFrameHeaderRow, } from './PanelFrame.js';
+export type { PhoneFrameProps, PhoneFrameHeaderProps, PhoneFrameHeaderRowProps, } from './PanelFrame.js';
+export { PHONE_MODELS, findPhoneModel, vendorLabelForUsbVendorId } from './phoneModels.js';
+export type { PhoneModel } from './phoneModels.js';
+export { PhoneDetectPrompt } from './PhoneDetectPrompt.js';
+export type { PhoneDetectPromptProps } from './PhoneDetectPrompt.js';
+export { computeRowOrder, deriveAnchorsFromOrder } from './panelRowOrder.js';
+export type { PanelAnchor } from './panelRowOrder.js';
+export { summarisePanel } from './panelRowEntry.js';
+export type { NeighborWidths, PanelRowEntry } from './panelRowEntry.js';
+export { DEFAULT_PANEL_SIZE, TIER_SIZES, panelWidthOf } from './panelTiers.js';
+export { computeMaxLiveWidth, computeRowLayout } from './panelRowLayout.js';
+export type { RowLayoutInput, RowLayoutResult } from './panelRowLayout.js';
+export { PanelRow, usePanelCloseEligible, usePanelNeighborWidths, usePanelPinned, usePanelReorderEligible } from './PanelRow.js';
+export { GAP, PANEL_TRANSITION, PanelRowSlot, PanelSizeBox } from './PanelRowSlot.js';
+export { Workspace } from './Workspace.js';
+export type { WorkspaceProps } from './Workspace.js';
+export { useProvidePanels } from './panels/useProvidePanels.js';
+export type { PanelsInput, ProvidedPanels } from './panels/useProvidePanels.js';
+export type { PanelWindow } from './panelWindow.js';
+export { reorderStepsForOffset } from './panelWindow.js';
+export { createDefaultTheme } from './defaultTheme.js';
+export type { WorkspacePanelState, WorkspaceState, WorkspaceStorage } from './workspaceState.js';

package/index.js

@@ -0,0 +1,30 @@
+// The public surface of phonux: a name that moves or changes kind here breaks every consumer. test/phonux-barrel.test.ts pins the value
+// names; only tsc checks type names (releaseMeasure.typecheck.ts pins one). DESIGN.md says why some exports stay off this list.
+export { DEFAULT_PHONE_SIZE, HostMissingProviderError, HostProvider, useHost, } from './hostApi.js';
+export { useViewSnapshot, CaptureRegistryContext, CaptureRegistryProvider, noopCaptureTrigger } from './snapshots.js';
+export { useViewState, ViewStateMissingProviderError } from './viewState.js';
+// Deprecated aliases: same value as their new-name counterpart, kept until removed.
+export { PhoneAPIsMissingProviderError, PhoneAPIsProvider, usePhoneAPIs, } from './hostApi.js';
+export { registerView, resolveView } from './viewRegistry.js';
+/** @deprecated use registerView/resolveView/ViewComponent */
+export { registerPanelView, resolvePanelView } from './viewRegistry.js';
+export { Panel, DRAG_CLOSE, DragToClose, shouldCloseOnRelease, WindowOverlay, OverlaySlot, OVERLAY_Z, OverlayProvider, OverlayStore, } from './Panel.js';
+/** @deprecated use Panel/PanelProps */
+export { PhoneView } from './Panel.js';
+export { default as PanelFrame } from './PanelFrame.js';
+export { PANEL_CORNER_RADIUS_UNITS, panelCornerRadiusPx, panelFrameScrollSx, panelFrameBareSx, PanelHeader, PanelHeaderRow, } from './PanelFrame.js';
+/** @deprecated use PanelFrame, PanelHeader, PanelHeaderRow and their PANEL_ and panel-prefixed siblings above */
+export { default as PhoneFrame } from './PanelFrame.js';
+export { PHONE_CORNER_RADIUS_UNITS, phoneCornerRadiusPx, phoneFrameScrollSx, phoneFrameBareSx, PhoneFrameHeader, PhoneFrameHeaderRow, } from './PanelFrame.js';
+export { PHONE_MODELS, findPhoneModel, vendorLabelForUsbVendorId } from './phoneModels.js';
+export { PhoneDetectPrompt } from './PhoneDetectPrompt.js';
+export { computeRowOrder, deriveAnchorsFromOrder } from './panelRowOrder.js';
+export { summarisePanel } from './panelRowEntry.js';
+export { DEFAULT_PANEL_SIZE, TIER_SIZES, panelWidthOf } from './panelTiers.js';
+export { computeMaxLiveWidth, computeRowLayout } from './panelRowLayout.js';
+export { PanelRow, usePanelCloseEligible, usePanelNeighborWidths, usePanelPinned, usePanelReorderEligible } from './PanelRow.js';
+export { GAP, PANEL_TRANSITION, PanelRowSlot, PanelSizeBox } from './PanelRowSlot.js';
+export { Workspace } from './Workspace.js';
+export { useProvidePanels } from './panels/useProvidePanels.js';
+export { reorderStepsForOffset } from './panelWindow.js';
+export { createDefaultTheme } from './defaultTheme.js';