phonux 0.1.0

package/panels/usePanelManager.js

@@ -0,0 +1,403 @@
+/**
+ * The panel capacity machinery: how many live collapsible panels the row shows at once (`capacity`),
+ * parking/revealing to stay at it, revive-with-demotion (`handleActivatePanel`), and the row gesture
+ * (`scrollRow`) that brings a hidden panel back from either side. Every hide is a park (`live: false`,
+ * never a removal) pushed onto `collapseOrderRef`, so `revealMostRecentlyCollapsed` keeps working
+ * regardless of which path did the parking.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { flushSync } from 'react-dom';
+import { GAP } from '../PanelRowSlot.js';
+import { computeMaxLiveWidth, computeRowLayout } from '../panelRowLayout.js';
+import { panelWidthOf } from '../panelTiers.js';
+import { effectiveMaxPanels, firstParkedAfter, lastParkedBefore, leftmostLiveIndex, farthestLiveCollapsibleId, movePanel, promoteToLive, rightmostLiveIndex, setFormFactor, sideOfLiveRange, } from '../panelWindow.js';
+export function usePanelManager(panels, setPanels, storedMaxPanels, phoneWidth, containerWidth, 
+/** How many always-rendered, non-webview columns the row currently has (`count(!collapsible)` over the provider's own list, unless its host overrides it). */
+fixedColumnCount, rootId) {
+    /** The live-collapsible ceiling for a row whose live set has these widths (row order). */
+    const capacityFor = (liveWidths) => {
+        // `containerWidth === 0` means unmeasured (the first commit, and every jsdom test that never calls
+        // measure()): null means no cap and no reconcile, never "zero panels fit".
+        const fitCount = containerWidth === 0
+            ? null
+            : fixedColumnCount + computeRowLayout({ containerWidth, phoneWidth, gap: GAP, fixedItemCount: fixedColumnCount, liveWidths }).maxLiveThatFit;
+        const effectiveMax = effectiveMaxPanels(storedMaxPanels, fitCount, fixedColumnCount);
+        // Floor of 1 keeps the panel just opened on screen even at the narrowest legal width (effectiveMaxPanels
+        // already floors at fixedColumnCount + 1, so this bites only when the fixed columns alone reach effectiveMax).
+        return effectiveMax === Number.POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : Math.max(1, effectiveMax - fixedColumnCount);
+    };
+    // The same cap every other width reader passes, from the same row inputs.
+    const maxLiveWidth = computeMaxLiveWidth({ containerWidth, phoneWidth, gap: GAP, fixedItemCount: fixedColumnCount });
+    const widthOf = (p) => panelWidthOf(p, phoneWidth, maxLiveWidth);
+    /** Whether `set` (live collapsible panels, row order) can stay live as it is: the one test both reconcile branches settle against. */
+    const settles = (set) => set.length <= capacityFor(set.map(widthOf));
+    const capacity = capacityFor(panels.filter((p) => p.collapsible && p.live).map(widthOf));
+    /**
+     * Parked ids in park order, most recent last. A ref, not state: only handlers and the reconcile effect below
+     * read it, so a push or pop need not re-render.
+     */
+    const collapseOrderRef = useRef([]);
+    /**
+     * The panels the next capacity-reconcile DROP must keep live, in the order they were acted on: each one just
+     * resized, opened or activated, so acting on a panel never parks it, and each of several actions in one
+     * update keeps its own. The value is the array the action read: a reconcile still on it ran before the action.
+     */
+    const keepLiveRef = useRef(new Map());
+    const markKeepLive = (id) => {
+        keepLiveRef.current = new Map(keepLiveRef.current).set(id, panels);
+    };
+    const keptIds = () => new Set(keepLiveRef.current.keys());
+    /** Tiers resizePanel queued on `seen` that have not reached `panels` yet, so a later action in the same handler can price them. */
+    const pendingTiersRef = useRef({ seen: null, tiers: new Map() });
+    /** `row` (read in this render) with those tiers applied. */
+    const withPendingTiers = (row) => {
+        const { seen, tiers } = pendingTiersRef.current;
+        return seen === panels ? [...tiers].reduce((acc, [id, tier]) => setFormFactor(acc, id, tier), row) : row;
+    };
+    /** `next`, plus in the same update whatever the reconcile's DROP would park, so no committed row overflows. */
+    const settledKeeping = (next, keep) => {
+        const live = next.filter((p) => p.collapsible && p.live);
+        if (settles(live))
+            return next;
+        const parked = new Set(fewestParksThatSettle(live, widthOf, settles, keep));
+        return parked.size === 0 ? next : next.map((p) => (parked.has(p.id) ? { ...p, live: false } : p));
+    };
+    /** Nonzero inside this hook's own flushSync: a reconcile run there is mid-handler, before later actions land. */
+    const flushingRef = useRef(0);
+    const flushOwn = (update) => {
+        flushingRef.current++;
+        try {
+            flushSync(update);
+        }
+        finally {
+            flushingRef.current--;
+        }
+    };
+    const enteringViaAnchorRef = useRef(new Set());
+    const markEnteringViaAnchor = (id) => {
+        enteringViaAnchorRef.current = new Set(enteringViaAnchorRef.current).add(id);
+    };
+    const forgetEnteringViaAnchor = (id) => {
+        if (!enteringViaAnchorRef.current.has(id))
+            return;
+        const next = new Set(enteringViaAnchorRef.current);
+        next.delete(id);
+        enteringViaAnchorRef.current = next;
+    };
+    const enterSideRef = useRef(new Map());
+    const [exitRightIds, setExitRightIds] = useState(new Set());
+    /** Every path that makes an id live must forget any stale exit-right mark from a PREVIOUS park of the same id -- ids cycle live/parked repeatedly over a session. Put here, once, so no reveal path can skip it. */
+    const purgeExitRight = (id) => {
+        setExitRightIds((prev) => {
+            if (!prev.has(id))
+                return prev;
+            const next = new Set(prev);
+            next.delete(id);
+            return next;
+        });
+    };
+    /** No flushSync needed: the mark only has to be in the commit that mounts the slot, like enteringViaAnchorRef's. */
+    const setEnterSide = (id, side) => {
+        enterSideRef.current = new Map(enterSideRef.current).set(id, side);
+        purgeExitRight(id);
+    };
+    /** Forces the NEXT mount of `id` back to the default (anchor formula / right), overriding a stale gesture mark from an earlier reveal of the same id. */
+    const clearEnterSide = (id) => {
+        if (enterSideRef.current.has(id)) {
+            const next = new Map(enterSideRef.current);
+            next.delete(id);
+            enterSideRef.current = next;
+        }
+        purgeExitRight(id);
+    };
+    /** flushSync BEFORE the parking setPanels -- see `UsePanelManagerResult.exitRightIds`'s own doc comment for why. */
+    const markExitRight = (id) => {
+        flushOwn(() => setExitRightIds((prev) => new Set(prev).add(id)));
+    };
+    const pushCollapsed = (ids) => {
+        const parkedSet = new Set(ids);
+        collapseOrderRef.current = [...collapseOrderRef.current.filter((x) => !parkedSet.has(x)), ...ids];
+    };
+    const forgetCollapsed = (id) => {
+        collapseOrderRef.current = collapseOrderRef.current.filter((x) => x !== id);
+    };
+    /**
+     * Before a panel is shown -- a new one from PanelsAPI.create(), or usePanelClosing's undo restoring a LIVE
+     * one -- parks whatever is necessary to stay at capacity (by count, then by width), in the SAME update that
+     * reveals it. `apply` is called once, purely (no side effect), against `panelsNow` to learn the id and array
+     * position of whatever it adds/restores; the real commit re-runs it against the LATEST state instead of
+     * trusting this snapshot.
+     */
+    const revealPanelProactively = (panelsNow, apply) => {
+        const afterInsert = apply(panelsNow);
+        const targetId = afterInsert.find((p) => !panelsNow.some((q) => q.id === p.id))?.id;
+        if (targetId !== undefined)
+            markKeepLive(targetId);
+        const keep = [...keptIds()];
+        const settledApply = (prev) => settledKeeping(apply(prev), keep);
+        if (targetId === undefined || capacity === Number.POSITIVE_INFINITY) {
+            setPanels(settledApply);
+            return;
+        }
+        const targetIndex = afterInsert.findIndex((p) => p.id === targetId);
+        const liveCollapsibleCountAfter = afterInsert.filter((p) => p.collapsible && p.live).length;
+        const overCapacity = Math.max(0, liveCollapsibleCountAfter - capacity);
+        if (overCapacity === 0) {
+            setPanels(settledApply);
+            return;
+        }
+        const toPark = [];
+        const exempt = keptIds();
+        let scratch = afterInsert;
+        for (let i = 0; i < overCapacity; i++) {
+            const id = farthestLiveCollapsibleId(scratch, targetIndex, exempt);
+            if (!id)
+                break;
+            toPark.push(id);
+            scratch = scratch.map((p) => (p.id === id ? { ...p, live: false } : p));
+        }
+        if (toPark.length === 0) {
+            setPanels(settledApply);
+            return;
+        }
+        const rightParks = toPark.filter((id) => sideOfLiveRange(afterInsert, id) === 'right');
+        if (rightParks.length > 0) {
+            flushOwn(() => setExitRightIds((prev) => {
+                const next = new Set(prev);
+                for (const id of rightParks)
+                    next.add(id);
+                return next;
+            }));
+        }
+        pushCollapsed(toPark);
+        const parkedSet = new Set(toPark);
+        setPanels((current) => settledKeeping(apply(current).map((p) => (parkedSet.has(p.id) ? { ...p, live: false } : p)), keep));
+    };
+    /**
+     * Clicking ANY row -- live or parked alike -- activates it (promoteToLive's own doc
+     * comment has the full "make/keep it live, preserve array order" spec).
+     */
+    const handleActivatePanel = (id) => {
+        const target = panels.find((p) => p.id === id);
+        if (!target || target.live)
+            return;
+        markKeepLive(id);
+        const keep = [...keptIds()];
+        // A manual History-row activation enters from the right (or by its own `anchoredEnter`), so it drops any
+        // anchor-entry or gesture-side mark left from an earlier reveal of this id.
+        forgetEnteringViaAnchor(id);
+        clearEnterSide(id);
+        const before = panels;
+        const result = promoteToLive(panels, id, capacity, keptIds());
+        if (!result)
+            return;
+        forgetCollapsed(id);
+        const demoted = result.find((p) => !p.live && before.find((prev) => prev.id === p.id)?.live);
+        if (!demoted) {
+            // An updater, not `result`: `result` is built from this render's array and would drop an update queued
+            // earlier in the same handler.
+            setPanels((prev) => settledKeeping(promoteToLive(prev, id, Number.POSITIVE_INFINITY) ?? prev, keep));
+            return;
+        }
+        if (sideOfLiveRange(before, demoted.id) === 'right')
+            markExitRight(demoted.id);
+        pushCollapsed([demoted.id]);
+        // Applied in two functional updates, in this order: `id` goes live first (no demotion yet -- capacity
+        // Infinity guarantees that for this call only), then the panel it displaces is parked.
+        setPanels((prev) => promoteToLive(prev, id, Number.POSITIVE_INFINITY) ?? prev);
+        setPanels((current) => settledKeeping(current.map((p) => (p.id === demoted.id ? { ...p, live: false } : p)), keep));
+    };
+    /** See `UsePanelManagerResult.scrollRow`'s own doc comment. */
+    const scrollRow = (direction) => {
+        const reveal = direction === 'right' ? firstParkedAfter(panels, rightmostLiveIndex(panels)) : lastParkedBefore(panels, leftmostLiveIndex(panels));
+        if (!reveal)
+            return;
+        const kept = keptIds();
+        markKeepLive(reveal.id);
+        // A resize earlier in this handler is priced at its new tier, or the row committed below could overflow.
+        const sized = withPendingTiers(panels);
+        const live = sized.filter((p) => p.collapsible && p.live);
+        const farFirst = (direction === 'right' ? live : [...live].reverse()).filter((p) => !kept.has(p.id));
+        const toPark = new Set();
+        const rowAfter = () => sized.filter((p) => p.collapsible && (p.live || p.id === reveal.id) && !toPark.has(p.id));
+        // At least the one panel the gesture swaps out, then more only while the row with `reveal` would not settle.
+        for (const p of farFirst) {
+            if (toPark.size > 0 && settles(rowAfter()))
+                break;
+            toPark.add(p.id);
+        }
+        setEnterSide(reveal.id, direction);
+        // A leftward gesture parks off the RIGHT edge: mark those BEFORE the setPanels below, in their own commit.
+        if (direction === 'left' && toPark.size > 0)
+            flushOwn(() => setExitRightIds((prev) => new Set([...prev, ...toPark])));
+        pushCollapsed([...toPark]);
+        forgetCollapsed(reveal.id);
+        setPanels((prev) => prev.map((p) => (toPark.has(p.id) ? { ...p, live: false } : p.id === reveal.id ? { ...p, live: true } : p)));
+    };
+    /** See `UsePanelManagerResult.reorderPanel`'s own doc comment. */
+    const reorderPanel = (id, direction) => {
+        setPanels((prev) => movePanel(prev, id, direction, rootId));
+    };
+    /** See `UsePanelManagerResult.resizePanel`'s own doc comment. */
+    const resizePanel = (id, next) => {
+        if (setFormFactor(panels, id, next) === panels)
+            return false;
+        const wasLive = panels.find((p) => p.id === id)?.live === true;
+        markKeepLive(id);
+        const keep = [...keptIds()];
+        const pending = pendingTiersRef.current.seen === panels ? pendingTiersRef.current.tiers : [];
+        pendingTiersRef.current = { seen: panels, tiers: new Map(pending).set(id, next) };
+        if (wasLive) {
+            purgeExitRight(id);
+            forgetCollapsed(id);
+        }
+        setPanels((prev) => {
+            const resized = setFormFactor(prev, id, next);
+            // An earlier call in this same handler may have queued a park of it (its exit mark and stack entry are
+            // dropped above): a resize never parks its own panel, so that park is cancelled before anything commits.
+            const own = wasLive && resized.some((p) => p.id === id && !p.live) ? resized.map((p) => (p.id === id ? { ...p, live: true } : p)) : resized;
+            return settledKeeping(own, keep);
+        });
+        return true;
+    };
+    /**
+     * Reconciles the live set against `capacity` whenever either changes -- an effect, since it must act on a
+     * measurement that just changed, not one this render was given. Both branches judge a candidate set by `settles`,
+     * never `capacity` as a count: `capacity` prices every not-yet-live slot at `phoneWidth`, so WHICH panels park or
+     * return decides whether the rest fits, and a set that does not settle re-triggers a branch next render. A DROP
+     * parks `fewestParksThatSettle` and exits 'left' (flushSync cannot mark a right exit first from a passive effect).
+     * A RISE reveals from the top of `collapseOrderRef`; one that doesn't settle stays on the stack for an OLDER, narrower one.
+     */
+    const committedRef = useRef(panels);
+    useEffect(() => {
+        // `settledKeeping` parks inside a state update, where no call-time code sees which panels it chose: the
+        // stack learns of any park not already on it from the commit itself.
+        const before = committedRef.current;
+        committedRef.current = panels;
+        const unrecorded = panels.filter((p) => p.collapsible && !p.live && !collapseOrderRef.current.includes(p.id) && before.some((q) => q.id === p.id && q.live));
+        if (unrecorded.length > 0)
+            pushCollapsed(unrecorded.map((p) => p.id));
+        const keepIds = [];
+        const waiting = new Map();
+        // A mark still on the array its action read waits for that action to land. Inside flushOwn every mark
+        // outlives this reconcile: the rest of its handler has not landed yet.
+        for (const [id, seen] of keepLiveRef.current) {
+            if (seen !== panels)
+                keepIds.push(id);
+            if (seen === panels || flushingRef.current > 0)
+                waiting.set(id, seen);
+        }
+        keepLiveRef.current = waiting;
+        if (capacity === Number.POSITIVE_INFINITY)
+            return;
+        const live = panels.filter((p) => p.collapsible && p.live);
+        if (live.length > capacity) {
+            const toPark = fewestParksThatSettle(live, widthOf, settles, keepIds);
+            if (toPark.length === 0)
+                return;
+            pushCollapsed(toPark);
+            const parkedSet = new Set(toPark);
+            setPanels((current) => current.map((p) => (parkedSet.has(p.id) ? { ...p, live: false } : p)));
+        }
+        else if (live.length < capacity && collapseOrderRef.current.length > 0) {
+            const stack = collapseOrderRef.current;
+            const revealed = new Set();
+            const remaining = [];
+            for (let i = stack.length - 1; i >= 0; i--) {
+                const id = stack[i];
+                const candidate = panels.find((p) => p.id === id);
+                if (!candidate || candidate.live)
+                    continue; // stale entry (closed, or already live some other way) -- drop it
+                if (settles(panels.filter((p) => p.collapsible && (p.live || revealed.has(p.id) || p.id === id))))
+                    revealed.add(id);
+                else
+                    remaining.unshift(id);
+            }
+            if (revealed.size === 0)
+                return;
+            collapseOrderRef.current = remaining;
+            for (const id of revealed)
+                setEnterSide(id, sideOfLiveRange(panels, id));
+            setPanels((current) => current.map((p) => (revealed.has(p.id) ? { ...p, live: true } : p)));
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [capacity, panels]);
+    /** See `UsePanelManagerResult.revealMostRecentlyCollapsed`'s own doc comment for the full contract. */
+    const revealMostRecentlyCollapsed = (panelsAfterClose) => {
+        // Priced like scrollRow: a resize earlier in this handler is not in `panelsAfterClose` yet.
+        const sized = withPendingTiers(panelsAfterClose);
+        const stack = collapseOrderRef.current;
+        const remaining = [];
+        let candidateId = null;
+        for (let i = stack.length - 1; i >= 0; i--) {
+            const id = stack[i];
+            const candidate = panelsAfterClose.find((p) => p.id === id);
+            if (!candidate || candidate.live)
+                continue; // stale entry (closed, or already live some other way) -- drop it
+            if (candidateId === null && settles(sized.filter((p) => p.collapsible && (p.live || p.id === id))))
+                candidateId = id;
+            else
+                remaining.unshift(id);
+        }
+        collapseOrderRef.current = remaining;
+        if (candidateId === null)
+            return;
+        const revealId = candidateId;
+        // Clear before marking, as `clearEnterSide`'s contract requires: a stale explicit side would win over the anchor.
+        clearEnterSide(revealId);
+        // One of the two "reappearance" paths that enter from the anchor's side -- mark it BEFORE the setPanels
+        // call below; no flushSync, since the mark only has to be in the commit that mounts the slot.
+        markEnteringViaAnchor(revealId);
+        setPanels((current) => promoteToLive(current, revealId, Number.POSITIVE_INFINITY) ?? current);
+    };
+    return {
+        revealPanelProactively,
+        handleActivatePanel,
+        forgetCollapsed,
+        revealMostRecentlyCollapsed,
+        enteringViaAnchorIds: enteringViaAnchorRef.current,
+        markEnteringViaAnchor,
+        clearEnterSide,
+        scrollRow,
+        reorderPanel,
+        resizePanel,
+        enterSideById: enterSideRef.current,
+        exitRightIds,
+    };
+}
+/**
+ * The ids (row order) to park so the live panels left settle: as FEW as possible, and among equally few the
+ * LEFTMOST -- so a row of equal widths parks exactly its leftmost excess, and a wide panel parks alone when
+ * that is what leaves the most panels live. Each of `keepIds` (in the order they were acted on) is never
+ * parked, whatever that costs the others, unless the ones before it already fill the row.
+ */
+function fewestParksThatSettle(live, widthOf, settles, keepIds = []) {
+    const narrowestFirst = (set) => [...set].sort((a, b) => widthOf(a) - widthOf(b));
+    const inRowOrder = (set) => live.filter((p) => set.includes(p));
+    // The first kept panel alone always settles (capacity is >= 1).
+    const mustKeep = [];
+    for (const id of keepIds) {
+        const p = live.find((q) => q.id === id);
+        if (p && !mustKeep.includes(p) && settles(inRowOrder([...mustKeep, p])))
+            mustKeep.push(p);
+    }
+    const candidates = live.filter((p) => !mustKeep.includes(p));
+    // Whether a set settles depends only on its size and its width sum, so the k narrowest candidates are the
+    // cheapest k to keep: if they do not settle, no k do.
+    let keep = candidates.length;
+    while (keep > 0 && mustKeep.length + keep > 1 && !settles(inRowOrder([...mustKeep, ...narrowestFirst(candidates).slice(0, keep)])))
+        keep--;
+    const kept = [...mustKeep];
+    const toPark = [];
+    candidates.forEach((p, i) => {
+        const stillToKeep = keep - (kept.length - mustKeep.length);
+        const rest = candidates.slice(i + 1);
+        // Park `p` only if what is left to its right can still complete a set that settles.
+        const canPark = toPark.length < candidates.length - keep && rest.length >= stillToKeep && settles(inRowOrder([...kept, ...narrowestFirst(rest).slice(0, stillToKeep)]));
+        if (canPark)
+            toPark.push(p.id);
+        else
+            kept.push(p);
+    });
+    return toPark;
+}

package/panels/useProvidePanels.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The app's implementation of PanelsAPI: the panel list, create/activate/close/undo/clear-all. Wraps
+ * usePanelManager, composes usePanelClosing and owns the row's scroll gesture. panelList and recentlyClosed hold
+ * PanelSummary objects built here, never PanelWindow records (phonux-app's provide-panels test pins their key set); `entries`
+ * is the raw list, hostData included, for the app and PanelRow only: an app keeps it out of the bag its views read,
+ * and the row's numbers (fixedViewCount, liveWidths, maxLiveWidth) beside it.
+ */
+import { type RefObject } from 'react';
+import type { JsonValue, PanelsAPI } from '../hostApi.js';
+import { type CaptureTrigger } from '../snapshots.js';
+import { type PanelWindow } from '../panelWindow.js';
+import type { WorkspaceStorage } from '../workspaceState.js';
+/**
+ * What an app hands `useProvidePanels`: the row's measured inputs, plus the behaviour only the host can decide
+ * (where closes are logged, what `hostData` means).
+ * @public
+ */
+export interface PanelsInput {
+    /** The list the provider starts with, read once on mount (the host seeds its always-shown columns here); the provider owns the list from then on. Default: empty. */
+    initialEntries?: readonly PanelWindow[];
+    /** The id of the row's root entry, the one every anchor leads to -- threaded through to every panelWindow.ts call that needs it. */
+    rootId: string;
+    /** The stored "max panels on screen" choice (`null` = follow the fit count) -- SettingsAPI's own value. */
+    storedMaxPanels: number | null;
+    /** The phone frame's current width: the unit a default-sized panel is priced in. */
+    phoneWidth: number;
+    /** Overrides `count(!collapsible)` over the provider's own list, which is the default: a host that prices the row from a count it already holds passes it through so usePanelManager always agrees with it. */
+    fixedViewCount?: number;
+    /** The host's measured row width (0 before the first measurement) -- usePanelManager derives the fit count and capacity from this, the same inputs SettingsAPI.fitCount uses. */
+    containerWidth: number;
+    /** The row's scroll container: the gesture's wheel listener attaches here. */
+    overflowContainerRef: RefObject<HTMLDivElement | null>;
+    /** Defaults to phonux's `noopCaptureTrigger`: a host that wants real pictures passes its own. */
+    capture?: CaptureTrigger;
+    /** Called when setFormFactor really resizes a panel, so the host can glide the row's margin with it. */
+    onPanelResize?: () => void;
+    /** Called once per close with its closed-pages log entry; the host decides where that log lives. See usePanelClosing.ts. */
+    onPanelsClosed?: (entry: {
+        id: string;
+        title: string;
+        url: string;
+        closedAt: string;
+    }) => void;
+    /** Called once per undo batch with the log ids it restores. See usePanelClosing.ts. */
+    onPanelsRestored?: (logIds: string[]) => void;
+    /** Called once per restored panel; the return value becomes its `hostData` (`undefined` drops the key). Unset keeps what it closed with. phonux never reads inside `hostData`, so what needs resetting after an undo is the host's call. */
+    resetHostDataOnRestore?: (hostData: JsonValue | undefined, panel: PanelWindow) => JsonValue | undefined;
+    /** Builds the `hostData` of every panel `create()` opens, and of every panel restored from `storage`. Unset: new panels carry none. */
+    defaultHostData?: () => JsonValue;
+    /** Where the workspace is kept between launches: loaded once at mount, then saved after every change that settles. Unset: nothing is loaded or saved. */
+    storage?: WorkspaceStorage;
+}
+/**
+ * PanelsAPI plus the inputs PanelRow and the workspace read: the raw list, the exit/enter animation sets and the
+ * row's numbers. They stay OFF PanelsAPI on purpose: that interface is the narrow surface a third-party view is
+ * written against (hostApi.tsx's header).
+ * @public
+ */
+export interface ProvidedPanels extends PanelsAPI {
+    /** The provider's one panel list, raw (not summarised): the row's input, never part of PanelsAPI. */
+    readonly entries: readonly PanelWindow[];
+    /** How many always-rendered columns the row has: `PanelsInput.fixedViewCount` when passed, else `count(!collapsible)` over `entries`. Capacity and `SettingsAPI.fitCount` are priced from it. */
+    readonly fixedViewCount: number;
+    /** Each live collapsible panel's own width in row order, capped at `maxLiveWidth`: the row's centring margin and `SettingsAPI.fitCount` read the same array capacity is priced from. */
+    readonly liveWidths: readonly number[];
+    /** The widest one live panel can be in this row; `Infinity` until the row is measured (`containerWidth` 0). */
+    readonly maxLiveWidth: number;
+    /** Ids being closed: each exits DOWN before it leaves `entries`. */
+    readonly closingIds: ReadonlySet<string>;
+    /** Ids (re)joining `live` by a reveal or an undo: each enters from its anchor's side. */
+    readonly enteringViaAnchorIds: ReadonlySet<string>;
+    /** See usePanelManager.ts's `UsePanelManagerResult.exitRightIds` for the full contract. */
+    readonly exitRightIds: ReadonlySet<string>;
+    /** See usePanelManager.ts's `UsePanelManagerResult.enterSideById` for the full contract. */
+    readonly enterSideById: ReadonlyMap<string, 'left' | 'right'>;
+}
+/**
+ * Builds the `PanelsAPI` an app hands its views. The provider owns the panel list, seeded once from `initialEntries`.
+ * Call it with this render's inputs and never memoise the result: its handlers close over this render's list.
+ * @public
+ */
+export declare function useProvidePanels(i: PanelsInput): ProvidedPanels;

package/panels/useProvidePanels.js

@@ -0,0 +1,142 @@
+/**
+ * The app's implementation of PanelsAPI: the panel list, create/activate/close/undo/clear-all. Wraps
+ * usePanelManager, composes usePanelClosing and owns the row's scroll gesture. panelList and recentlyClosed hold
+ * PanelSummary objects built here, never PanelWindow records (phonux-app's provide-panels test pins their key set); `entries`
+ * is the raw list, hostData included, for the app and PanelRow only: an app keeps it out of the bag its views read,
+ * and the row's numbers (fixedViewCount, liveWidths, maxLiveWidth) beside it.
+ */
+import { useEffect, useRef, useState } from 'react';
+import { GAP } from '../PanelRowSlot.js';
+import { computeMaxLiveWidth } from '../panelRowLayout.js';
+import { summarisePanel } from '../panelRowEntry.js';
+import { panelWidthOf } from '../panelTiers.js';
+import { noopCaptureTrigger } from '../snapshots.js';
+import { appendPanel, reanchorPanel } from '../panelWindow.js';
+import { usePanelClosing } from './usePanelClosing.js';
+import { usePanelManager } from './usePanelManager.js';
+import { useRowScrollGesture } from './useRowScrollGesture.js';
+import { useWorkspacePersistence } from './useWorkspacePersistence.js';
+/** Ids for panels this app creates itself. A module counter, bumped only from event handlers and the restore callback (never from a state initialiser or updater), so StrictMode's double invocation cannot skip one. */
+let nextWindowId = 1;
+const freshId = () => String(nextWindowId++);
+/**
+ * Duck-typed (a `preventDefault` function): a bare `onClick={panels.create}` reference passes the click
+ * event positionally, so this discards it rather than spreading `view` into the new panel (see DESIGN.md).
+ */
+function isEventLike(value) {
+    return typeof value === 'object' && value !== null && typeof value.preventDefault === 'function';
+}
+/**
+ * Builds the `PanelsAPI` an app hands its views. The provider owns the panel list, seeded once from `initialEntries`.
+ * Call it with this render's inputs and never memoise the result: its handlers close over this render's list.
+ * @public
+ */
+export function useProvidePanels(i) {
+    const capture = i.capture ?? noopCaptureTrigger;
+    const [panels, setPanels] = useState(() => [...(i.initialEntries ?? [])]);
+    const fixedViewCount = i.fixedViewCount ?? panels.filter((p) => !p.collapsible).length;
+    // Filters over the whole list, never an array position: a panel anchored left of History changes none of these.
+    const maxLiveWidth = computeMaxLiveWidth({ containerWidth: i.containerWidth, phoneWidth: i.phoneWidth, gap: GAP, fixedItemCount: fixedViewCount });
+    const liveWidths = panels.filter((p) => p.collapsible && p.live).map((p) => panelWidthOf(p, i.phoneWidth, maxLiveWidth));
+    const { revealPanelProactively, handleActivatePanel, forgetCollapsed, revealMostRecentlyCollapsed, enteringViaAnchorIds, markEnteringViaAnchor, clearEnterSide, scrollRow, reorderPanel, resizePanel, enterSideById, exitRightIds, } = usePanelManager(panels, setPanels, i.storedMaxPanels, i.phoneWidth, i.containerWidth, fixedViewCount, i.rootId);
+    // The row's wheel/arrow-key gesture is wired here, not in the host, so a host stays free of effects and refs.
+    useRowScrollGesture(i.overflowContainerRef, scrollRow);
+    useWorkspacePersistence({ storage: i.storage, panels, setPanels, rootId: i.rootId, freshId, defaultHostData: i.defaultHostData });
+    // Diffs the one list instead of capturing per call site: usePanelManager parks from several sites with no single
+    // "on park" hook, and a per-site call would silently miss any site not touched.
+    const prevLiveRef = useRef(new Map());
+    useEffect(() => {
+        const prev = prevLiveRef.current;
+        for (const p of panels) {
+            if (prev.get(p.id) === true && !p.live)
+                capture.capture(p.id);
+        }
+        prevLiveRef.current = new Map(panels.map((p) => [p.id, p.live]));
+    }, [panels, capture]);
+    // clearAll only records ids here: React may run its updater during render, where evict would notify other components.
+    const clearedIds = useRef(new Set());
+    useEffect(() => {
+        for (const id of clearedIds.current)
+            capture.evict(id);
+        clearedIds.current.clear();
+    }, [panels, capture]);
+    // After usePanelManager: undo makes room for a live view through its revealPanelProactively. `onAfterClose`
+    // forgets the closed id (it may have been parked), then offers the freed room to the most recently parked panel.
+    const closing = usePanelClosing(panels, setPanels, revealPanelProactively, i.rootId, (id, remaining) => {
+        forgetCollapsed(id);
+        revealMostRecentlyCollapsed(remaining);
+    }, 
+    // A restored LIVE panel can carry a stale gesture-enter-side/exit-right mark from an earlier park of
+    // the same id; clear it before marking entering-via-anchor (usePanelManager's own clear-then-mark order).
+    (id) => {
+        clearEnterSide(id);
+        markEnteringViaAnchor(id);
+    }, 
+    // A closed-and-not-restored panel's picture must not outlive its undo window; usePanelClosing.ts alone
+    // knows which ids the window's NATURAL elapse (never Undo) just finalized.
+    (ids) => {
+        for (const id of ids)
+            capture.evict(id);
+    }, i.onPanelsClosed, i.onPanelsRestored, i.resetHostDataOnRestore);
+    const api = {
+        // `listed` excludes History: it must not list itself (a host's history column renders every entry here as a
+        // clickable row).
+        panelList: panels.filter((p) => p.listed).map(summarisePanel),
+        create: (options) => {
+            // `options` is explicitly optional here (not left to infer from `create`'s own overloaded interface
+            // member) -- an implementation inferred as requiring it would no longer satisfy the zero-arg overload.
+            const safeOptions = isEventLike(options) ? undefined : options;
+            const id = freshId();
+            // Built here, outside the updater below: React may run an updater twice, and the host's builder is not required to be pure.
+            const hostData = i.defaultHostData?.();
+            // "Panel N", not "about:blank": every panel needs a distinguishable title, for testing. options?.title
+            // overrides it; the explicit `title:` below (after the spread) is what makes that override win either way.
+            revealPanelProactively(panels, (prev) => appendPanel(prev, { url: 'about:blank', hostData, ...safeOptions, title: safeOptions?.title ?? `Panel ${id}` }, id, i.rootId));
+        },
+        activate: handleActivatePanel,
+        move: reorderPanel,
+        setFormFactor: (id, next) => {
+            if (resizePanel(id, next))
+                i.onPanelResize?.();
+        },
+        // No keep-live mark and no settle step: settles() reads only the live set's widths and count, never its
+        // order, so a reorder cannot unsettle a row, and a DROP later in the handler may park this panel as any other.
+        reanchor: (id, anchor) => setPanels((prev) => reanchorPanel(prev, id, anchor, i.rootId)),
+        close: (id) => {
+            // Fires on every close() call, even an unknown or locked id's no-op below: a harmless extra attempt,
+            // and gating it exactly would need a second callback into usePanelClosing.ts.
+            capture.capture(id);
+            closing.close(id);
+        },
+        recentlyClosed: closing.recentlyClosed?.map(summarisePanel) ?? null,
+        undoClose: closing.undoClose,
+        // Drops every collapsible panel, never History (the always-shown column). Its picture goes now, not at an undo
+        // window: a dropped panel can never be shown again. The ids come from the updater's own list, because this
+        // render's `panels` misses a panel created earlier in the same batch.
+        clearAll: () => setPanels((prev) => {
+            for (const p of prev)
+                if (p.collapsible)
+                    clearedIds.current.add(p.id);
+            return prev.filter((p) => !p.collapsible);
+        }),
+        entries: panels,
+        fixedViewCount,
+        liveWidths,
+        maxLiveWidth,
+        closingIds: closing.closingIds,
+        enteringViaAnchorIds,
+        exitRightIds,
+        enterSideById,
+    };
+    // Test-only hook: a host's end-to-end tests reach the API here, since no production UI calls create({ permanent })
+    // or reanchor(). Gated on MODE 'test', which only a host's test build sets. An effect with no deps array, not a
+    // render-body assignment: StrictMode double-invokes render bodies, and a test must always reach the LATEST closure.
+    useEffect(() => {
+        // Structural cast: the package builds without Vite's ambient types, so `import.meta.env` is untyped here.
+        const mode = import.meta.env?.MODE;
+        if (typeof window === 'undefined' || mode !== 'test')
+            return;
+        window.__panelsApiForTests = api;
+    });
+    return api;
+}

package/panels/useRowScrollGesture.d.ts

@@ -0,0 +1,2 @@
+import type { RefObject } from 'react';
+export declare function useRowScrollGesture(overflowContainerRef: RefObject<HTMLDivElement | null>, scrollRow: (direction: 'left' | 'right') => void): void;