phonux 0.1.0

package/panelWindow.js

@@ -0,0 +1,243 @@
+import { computeRowOrder, deriveAnchorsFromOrder } from './panelRowOrder.js';
+import { DEFAULT_PANEL_SIZE, TIER_SIZES } from './panelTiers.js';
+export { effectiveMaxPanels } from './panelCapacity.js';
+/** History's own seeded entry: never collapsible (an always-shown column), never listed (it must not list itself), always live, locked by default (the host's close path honours `locked`); raised, so a left-exiting park slides under it; anchoredEnter, which against itself resolves 'right'; no anchor: it is the root every anchor leads to. Same default tier/size as every other entry: a permanent column carries a tier like any other. @internal */
+export function createHistoryPanel(rootId) {
+    return {
+        id: rootId, url: '', title: 'History', live: true, locked: true,
+        view: 'history', collapsible: false, listed: false, layer: 'raised', anchoredEnter: true,
+        formFactor: 'phone', size: DEFAULT_PANEL_SIZE,
+    };
+}
+/** `request` with its defaults filled against `panels`: History, and one past the highest priority already on that side (`self` excluded). */
+function fillAnchor(panels, rootId, request, self) {
+    const panel = request.panel ?? rootId;
+    if (request.priority !== undefined)
+        return { panel, position: request.position, priority: request.priority };
+    const positional = new Map(deriveAnchorsFromOrder(panels, rootId).map((p) => [p.id, p.anchor]));
+    let max = -1;
+    for (const p of panels) {
+        const a = p.anchor ?? positional.get(p.id);
+        if (p.id !== self && p.id !== rootId && a && a.panel === panel && a.position === request.position)
+            max = Math.max(max, a.priority);
+    }
+    return { panel, position: request.position, priority: max + 1 };
+}
+/** `id` re-anchored per `request` (defaults as for appendPanel), the row re-ordered to match. The SAME array for an unknown id or a `collapsible: false` entry. @internal */
+export function reanchorPanel(panels, id, request, rootId) {
+    const target = panels.find((p) => p.id === id);
+    if (!target || !target.collapsible)
+        return panels;
+    const anchor = fillAnchor(panels, rootId, request, id);
+    return computeRowOrder(panels.map((p) => (p.id === id ? { ...p, anchor } : p)), rootId);
+}
+/**
+ * Builds a brand-new, live 'extra' panel immutably and places it by `info.anchor` (default: right of
+ * History, past every panel already there -- the row's far right end). History is seeded directly, never
+ * through this function. `permanent` forces `collapsible:false` and `listed:false` (overriding any `info.listed`
+ * passed) since such a column must supply its own close control, never the row's trash; `locked`
+ * stays false regardless so that control keeps working with no extra plumbing (the host's close path gates
+ * only on `locked`).
+ * @internal
+ */
+export function appendPanel(panels, info, id, rootId) {
+    const formFactor = info.permanent ? 'phone' : (info.formFactor ?? 'phone');
+    const entry = {
+        id,
+        url: info.url,
+        ...(info.title !== undefined ? { title: info.title } : {}),
+        ...(info.hostData !== undefined ? { hostData: info.hostData } : {}),
+        live: true,
+        locked: false,
+        view: info.view ?? 'web',
+        collapsible: !info.permanent,
+        listed: info.permanent ? false : (info.listed ?? true),
+        ...(info.params !== undefined ? { params: info.params } : {}),
+        anchor: fillAnchor(panels, rootId, info.anchor ?? { position: 'right' }),
+        layer: info.layer ?? 'base',
+        anchoredEnter: info.anchoredEnter ?? false,
+        // Every entry carries a tier; a permanent column's is always 'phone'.
+        formFactor,
+        size: formFactor === 'phone' ? DEFAULT_PANEL_SIZE : { ...TIER_SIZES[formFactor] },
+    };
+    return computeRowOrder([...panels, entry], rootId);
+}
+/**
+ * The id of the live collapsible panel farthest (by array index) from `fromIndex`, or null with none live.
+ * Ties go to the lower index (the strict `>` keeps the first). From an append (`fromIndex` = the new length)
+ * that is the LEFT end of the live range; from an open nearest History or a revive left of the range, the
+ * RIGHT end. promoteToLive and the host's open/restore park both pick through this. `exclude`
+ * exempts the panel being opened or restored, which is already live in the array the caller passes, and any
+ * panel another action in the same update must keep live.
+ * @internal
+ */
+export function farthestLiveCollapsibleId(panels, fromIndex, exclude = new Set()) {
+    let bestId = null;
+    let bestDist = -1;
+    panels.forEach((p, i) => {
+        if (!p.collapsible || !p.live || exclude.has(p.id))
+            return;
+        const dist = Math.abs(i - fromIndex);
+        if (dist > bestDist) {
+            bestDist = dist;
+            bestId = p.id;
+        }
+    });
+    return bestId;
+}
+/**
+ * Which side of the row a park/reveal at `id` reads as, for the exit/enter animation: 'left' when `id`'s
+ * own array index sits below every OTHER live collapsible panel's index, 'right' otherwise (a parked panel
+ * between two live ones included). Computed fresh from array position every time, never a persisted flag,
+ * so an append's park always reads 'left' and a park for an open anchored nearest History reads 'right'.
+ * @internal
+ */
+export function sideOfLiveRange(panels, id) {
+    const ownIndex = panels.findIndex((p) => p.id === id);
+    let firstOtherLiveIndex = Number.POSITIVE_INFINITY;
+    panels.forEach((p, i) => {
+        if (p.collapsible && p.live && p.id !== id)
+            firstOtherLiveIndex = Math.min(firstOtherLiveIndex, i);
+    });
+    return ownIndex < firstOtherLiveIndex ? 'left' : 'right';
+}
+/** The row-slot index of the LEFTMOST (lowest-index) live collapsible panel, or -1 if none are live. @internal */
+export function leftmostLiveIndex(panels) {
+    for (let i = 0; i < panels.length; i++)
+        if (panels[i].collapsible && panels[i].live)
+            return i;
+    return -1;
+}
+/** The row-slot index of the RIGHTMOST (highest-index) live collapsible panel, or -1 if none are live. @internal */
+export function rightmostLiveIndex(panels) {
+    let found = -1;
+    panels.forEach((p, i) => {
+        if (p.collapsible && p.live)
+            found = i;
+    });
+    return found;
+}
+/** The first PARKED collapsible panel strictly after `index` -- a rightward gesture's own "next one to bring in", or null with nothing parked on that side. @internal */
+export function firstParkedAfter(panels, index) {
+    for (let i = index + 1; i < panels.length; i++)
+        if (panels[i].collapsible && !panels[i].live)
+            return panels[i];
+    return null;
+}
+/** The last PARKED collapsible panel strictly before `index` -- a leftward gesture's own "next one to bring in", or null with nothing parked on that side. @internal */
+export function lastParkedBefore(panels, index) {
+    for (let i = index - 1; i >= 0; i--)
+        if (panels[i].collapsible && !panels[i].live)
+            return panels[i];
+    return null;
+}
+/**
+ * Activating ANY panel (live or parked) flips `live` in place, never moving the entry's array position.
+ * Returns `null` for an unknown id or one already live (a legitimate no-op, not an error). When promoting
+ * `id` would exceed `capacity`, demotes exactly one OTHER live panel: whichever `farthestLiveCollapsibleId`
+ * picks from `id`'s own index, the same far rule an open/restore parks by. Never demotes a
+ * `collapsible: false` entry or any id in `keep`.
+ * @internal
+ */
+export function promoteToLive(panels, id, capacity, keep = new Set()) {
+    const target = panels.find((p) => p.id === id);
+    if (!target || target.live)
+        return null;
+    const ownIndex = panels.findIndex((p) => p.id === id);
+    const liveCountAfter = panels.filter((p) => p.collapsible && p.live).length + 1;
+    let next = panels.map((p) => (p.id === id ? { ...p, live: true } : p));
+    if (liveCountAfter > capacity) {
+        // `panels` (pre-promotion): `id` itself still reads live:false there, so it is naturally excluded
+        // from the search without needing `keep`.
+        const demote = farthestLiveCollapsibleId(panels, ownIndex, keep);
+        if (demote) {
+            next = next.map((p) => (p.id === demote ? { ...p, live: false } : p));
+        }
+    }
+    return next;
+}
+/**
+ * Closes one panel COMPLETELY: it leaves the array, live or parked, so it leaves the row and History
+ * together. Returns what a caller needs to log it and to undo it -- the array without it, the panel itself
+ * and the index it had -- or `null` for an unknown `id` (already closed, cleared): nothing to do, not an
+ * error. Every panel anchored to it takes over its own anchor, so they close up in the place it held.
+ * @internal
+ */
+export function closePanel(panels, id, rootId) {
+    const index = panels.findIndex((p) => p.id === id);
+    if (index < 0)
+        return null;
+    const closed = panels[index];
+    const inherited = closed.anchor ?? deriveAnchorsFromOrder(panels, rootId)[index].anchor;
+    const rest = panels.filter((p) => p.id !== id).map((p) => (inherited && p.anchor?.panel === id ? { ...p, anchor: { ...inherited } } : p));
+    return { remaining: computeRowOrder(rest, rootId), closed, index };
+}
+/**
+ * Moves `id` one PRESENT slot (`!collapsible || live`, PanelRow's filter) toward `direction`, past
+ * whichever present panel sits there, History included; a parked panel between the two shifts one array slot,
+ * keeping firstParkedAfter/lastParkedBefore/sideOfLiveRange meaningful. Every anchor is then re-read from the
+ * new order. The SAME array for every no-op: unknown id, a `collapsible: false` source (an always-shown column
+ * is never dragged), a parked panel, or one already at that edge.
+ * @internal
+ */
+export function movePanel(panels, id, direction, rootId) {
+    const present = panels.filter((p) => !p.collapsible || p.live);
+    const presentIndex = present.findIndex((p) => p.id === id);
+    if (presentIndex < 0 || !present[presentIndex].collapsible)
+        return panels;
+    const neighbor = present[direction === 'left' ? presentIndex - 1 : presentIndex + 1];
+    if (!neighbor)
+        return panels;
+    const from = panels.findIndex((p) => p.id === id);
+    const to = panels.findIndex((p) => p.id === neighbor.id);
+    const next = panels.slice();
+    const [entry] = next.splice(from, 1);
+    next.splice(to, 0, entry);
+    return deriveAnchorsFromOrder(next, rootId);
+}
+/**
+ * How many movePanel hops a horizontal drag of `offsetX` px asks for (+right/-left). A hop past a neighbour
+ * moves the dragged panel by that NEIGHBOUR's span (its width plus `gap`), so each hop lands half-way across
+ * the next neighbour's span, counted from where the previous hop ended; the dragged panel's own width never
+ * enters it. Exactly half a span is a hop either way, and this never returns -0.
+ * @public
+ */
+export function reorderStepsForOffset(offsetX, neighbors, gap) {
+    const distance = Math.abs(offsetX);
+    let travelled = 0;
+    let steps = 0;
+    for (const width of offsetX > 0 ? neighbors.right : neighbors.left) {
+        const span = width + gap;
+        if (distance < travelled + span / 2)
+            break;
+        travelled += span;
+        steps++;
+    }
+    return steps === 0 ? 0 : Math.sign(offsetX) * steps;
+}
+/**
+ * `id` at `next`'s tier, its `size` REPLACED by a fresh copy of that tier's TIER_SIZES entry. Returns the SAME
+ * array reference for every no-op: an unknown id, a `collapsible: false` entry (History or a permanent column,
+ * movePanel's own source guard), or a panel already at `next`. A parked panel may change tier and stays parked.
+ * @internal
+ */
+export function setFormFactor(panels, id, next) {
+    const target = panels.find((p) => p.id === id);
+    if (!target || !target.collapsible || (target.formFactor ?? 'phone') === next)
+        return panels;
+    return panels.map((p) => (p.id === id ? { ...p, formFactor: next, size: { ...TIER_SIZES[next] } } : p));
+}
+/**
+ * Reverses closePanel for one panel: puts `panel` back at `index` (clamped to the current length, so a shorter
+ * array still takes it), unchanged -- a pure spread, no `hostData` reset (the host's undo does that itself: only
+ * it knows what "unmounted when it closed" means for the opaque blob). An id already present leaves `panels`
+ * unchanged (a double undo never duplicates). Live or parked is whatever `panel.live` says. Anchors are
+ * re-read from the result: its old anchor may no longer describe that index.
+ * @internal
+ */
+export function restorePanel(panels, panel, index, rootId) {
+    if (panels.some((p) => p.id === panel.id))
+        return panels;
+    const at = Math.max(0, Math.min(index, panels.length));
+    return deriveAnchorsFromOrder([...panels.slice(0, at), { ...panel }, ...panels.slice(at)], rootId);
+}

package/panels/usePanelClosing.d.ts

@@ -0,0 +1,58 @@
+import { type Dispatch, type SetStateAction } from 'react';
+import type { JsonValue } from '../hostApi.js';
+import { type PanelWindow } from '../panelWindow.js';
+import type { UsePanelManagerResult } from './usePanelManager.js';
+/** The undo toast stays up for 10 seconds, one window, restarted by every close. */
+export declare const UNDO_WINDOW_MS = 10000;
+export interface UsePanelClosingResult {
+    /** Closes a view completely and opens (or restarts) the 10 s undo window. Unknown or already-closed id: does nothing. */
+    close: (id: string) => void;
+    /** Restores every view closed inside the window, last closed first, each at its old index; a live one comes back live. */
+    undoClose: () => void;
+    /** The views closed inside the window, oldest first; non-null exactly while the window is open. */
+    recentlyClosed: PanelWindow[] | null;
+    /**
+     * Ids leaving through THIS hook's `close()`, never usePanelManager's auto-collapse (which only flips `live`):
+     * PanelRow reads it for each exiting PanelRowSlot's `exitDirection` (down for a close, left for a park).
+     * See `close()` for why an id must land here BEFORE the panel leaves `panels`.
+     */
+    closingIds: ReadonlySet<string>;
+}
+/**
+ * A close (drag down, or History's trash) removes the view COMPLETELY, reports it through `onPanelsClosed` and offers
+ * Undo for 10 s. Takes the CURRENT render's values, so nothing here may be memoised, and `close` reads the index from
+ * that render: two closes before one re-render would undo in the wrong order (discrete gestures re-render between
+ * events), so a caller that batches closes needs one setPanels for the lot. Log ids are `<closedAt>#<panel id>`: panel
+ * ids restart each launch, and a host undoing by id would otherwise also delete an older launch's entry.
+ */
+export declare function usePanelClosing(panels: PanelWindow[], setPanels: Dispatch<SetStateAction<PanelWindow[]>>, revealPanelProactively: UsePanelManagerResult['revealPanelProactively'], rootId: string, 
+/**
+ * Called once per successful close with the id that just left and `closePanel`'s `remaining`, the array right
+ * after it, computed from THIS render's `panels` like everything else in `close()`.
+ */
+onAfterClose?: (id: string, remaining: PanelWindow[]) => void, 
+/**
+ * Called per panel `undoClose` restores LIVE (the branch that calls `revealPanelProactively`): with
+ * usePanelManager.ts's `revealMostRecentlyCollapsed`, one of the two paths that enter from the anchor's side.
+ */
+onRestoreLive?: (id: string) => void, 
+/**
+ * Called with the ids the undo window's NATURAL elapse just finalized (Undo calls stopWindow() instead), so a
+ * caller can tell a restored close from one nothing will ever undo.
+ */
+onWindowElapsed?: (ids: string[]) => void, 
+/** Called once per successful close with the log entry: `id` is the log id, `title` already falls back to the url, then 'Untitled panel'. */
+onPanelsClosed?: (entry: {
+    id: string;
+    title: string;
+    url: string;
+    closedAt: string;
+}) => void, 
+/** Called once per `undoClose` batch with the log ids of every close the batch restores, in close order. */
+onPanelsRestored?: (logIds: string[]) => void, 
+/**
+ * Called once per restored panel with the `hostData` it closed carrying; its return value is what the panel comes
+ * back with (`undefined` drops the key). Unset leaves `hostData` exactly as it closed: only the host knows what
+ * the opaque blob pointed at, and whether that outlived the close.
+ */
+resetHostDataOnRestore?: (hostData: JsonValue | undefined, panel: PanelWindow) => JsonValue | undefined): UsePanelClosingResult;

package/panels/usePanelClosing.js

@@ -0,0 +1,140 @@
+import { useEffect, useRef, useState } from 'react';
+import { flushSync } from 'react-dom';
+import { closePanel, restorePanel } from '../panelWindow.js';
+/** The undo toast stays up for 10 seconds, one window, restarted by every close. */
+export const UNDO_WINDOW_MS = 10_000;
+/** `panel` carrying `hostData`; `undefined` leaves no `hostData` key at all, the same shape appendPanel produces. */
+function withHostData(panel, hostData) {
+    const next = { ...panel };
+    if (hostData === undefined)
+        delete next.hostData;
+    else
+        next.hostData = hostData;
+    return next;
+}
+/**
+ * A close (drag down, or History's trash) removes the view COMPLETELY, reports it through `onPanelsClosed` and offers
+ * Undo for 10 s. Takes the CURRENT render's values, so nothing here may be memoised, and `close` reads the index from
+ * that render: two closes before one re-render would undo in the wrong order (discrete gestures re-render between
+ * events), so a caller that batches closes needs one setPanels for the lot. Log ids are `<closedAt>#<panel id>`: panel
+ * ids restart each launch, and a host undoing by id would otherwise also delete an older launch's entry.
+ */
+export function usePanelClosing(panels, setPanels, revealPanelProactively, rootId, 
+/**
+ * Called once per successful close with the id that just left and `closePanel`'s `remaining`, the array right
+ * after it, computed from THIS render's `panels` like everything else in `close()`.
+ */
+onAfterClose, 
+/**
+ * Called per panel `undoClose` restores LIVE (the branch that calls `revealPanelProactively`): with
+ * usePanelManager.ts's `revealMostRecentlyCollapsed`, one of the two paths that enter from the anchor's side.
+ */
+onRestoreLive, 
+/**
+ * Called with the ids the undo window's NATURAL elapse just finalized (Undo calls stopWindow() instead), so a
+ * caller can tell a restored close from one nothing will ever undo.
+ */
+onWindowElapsed, 
+/** Called once per successful close with the log entry: `id` is the log id, `title` already falls back to the url, then 'Untitled panel'. */
+onPanelsClosed, 
+/** Called once per `undoClose` batch with the log ids of every close the batch restores, in close order. */
+onPanelsRestored, 
+/**
+ * Called once per restored panel with the `hostData` it closed carrying; its return value is what the panel comes
+ * back with (`undefined` drops the key). Unset leaves `hostData` exactly as it closed: only the host knows what
+ * the opaque blob pointed at, and whether that outlived the close.
+ */
+resetHostDataOnRestore) {
+    const [closed, setClosed] = useState([]);
+    // Mirrors `closed` synchronously (never via an effect): the timer callback below fires from a closure
+    // created at the LAST close() call, whose own render still saw `closed` BEFORE that call's own setClosed
+    // took effect -- reading this ref instead always sees every entry the window is actually holding when it fires.
+    const closedRef = useRef([]);
+    const setClosedBoth = (next) => {
+        closedRef.current = next;
+        setClosed(next);
+    };
+    const [closingIds, setClosingIds] = useState(new Set());
+    const timer = useRef(null);
+    // Ids closed in the current window: a second close of the same id (a gesture callback that outlived a trash click) is ignored.
+    const claimed = useRef(new Set());
+    useEffect(() => () => {
+        if (timer.current)
+            clearTimeout(timer.current);
+    }, []);
+    const stopWindow = () => {
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = null;
+        claimed.current.clear();
+    };
+    const close = (id) => {
+        const found = closePanel(panels, id, rootId);
+        // History defaults locked (no unlock control exists yet): a locked entry's close is a no-op, the one
+        // list's own lock gate -- every entry (History included) goes through this same close().
+        if (!found || claimed.current.has(id) || found.closed.locked)
+            return;
+        claimed.current.add(id);
+        // Commits ALONE, before the removal: AnimatePresence takes an exiting child's `exit` from its LAST props
+        // before it left, and a plain setState would batch with the setPanels below into one commit that never
+        // has the panel both present AND marked.
+        flushSync(() => setClosingIds((prev) => new Set(prev).add(id)));
+        const closedAt = new Date().toISOString();
+        const logId = `${closedAt}#${id}`;
+        setPanels((prev) => closePanel(prev, id, rootId)?.remaining ?? prev);
+        onAfterClose?.(id, found.remaining);
+        // A url-less custom panel has nothing sensible to fall back to: 'Untitled panel', never an empty string.
+        onPanelsClosed?.({ id: logId, title: found.closed.title || found.closed.url || 'Untitled panel', url: found.closed.url, closedAt });
+        setClosedBoth([...closedRef.current, { panel: found.closed, index: found.index, logId }]);
+        if (timer.current)
+            clearTimeout(timer.current);
+        timer.current = setTimeout(() => {
+            timer.current = null;
+            claimed.current.clear();
+            const elapsedIds = closedRef.current.map((e) => e.panel.id);
+            setClosedBoth([]);
+            onWindowElapsed?.(elapsedIds);
+        }, UNDO_WINDOW_MS);
+    };
+    const undoClose = () => {
+        if (closed.length === 0)
+            return;
+        const batch = closed;
+        stopWindow();
+        setClosedBoth([]);
+        // Last closed first: each index was taken from the array as it was when THAT view closed, so undoing in reverse re-creates it.
+        let working = panels;
+        for (const { panel, index } of [...batch].reverse()) {
+            if (working.some((p) => p.id === panel.id))
+                continue;
+            // restorePanel is a pure spread and phonux never reads inside hostData, so the host's own reset runs
+            // here, once per panel, and its result is what every call below restores.
+            const restoringPanel = resetHostDataOnRestore ? withHostData(panel, resetHostDataOnRestore(panel.hostData, panel)) : panel;
+            if (panel.live) {
+                // This restore is one of the two "reappearance" paths that enters from the anchor's side -- mark it
+                // BEFORE revealPanelProactively's own setPanels call, same ordering reasoning as usePanelManager.ts's
+                // own markEnteringViaAnchor call site.
+                onRestoreLive?.(panel.id);
+                // Through the same room-making rule as opening a view: the live view farthest from it is parked if the row is full.
+                revealPanelProactively(working, (prev) => restorePanel(prev, restoringPanel, index, rootId));
+            }
+            else {
+                setPanels((prev) => restorePanel(prev, restoringPanel, index, rootId));
+            }
+            working = restorePanel(working, restoringPanel, index, rootId);
+        }
+        // A restored id is no longer closing: a stale mark would slide a LATER park of it down instead of left. An
+        // id never restored keeps its mark, harmlessly: ids never repeat in a session (useProvidePanels.ts's nextWindowId).
+        setClosingIds((prev) => {
+            const ids = batch.map((e) => e.panel.id).filter((restoredId) => prev.has(restoredId));
+            if (ids.length === 0)
+                return prev;
+            const next = new Set(prev);
+            for (const restoredId of ids)
+                next.delete(restoredId);
+            return next;
+        });
+        onPanelsRestored?.(batch.map((e) => e.logId));
+    };
+    return { close, undoClose, recentlyClosed: closed.length > 0 ? closed.map((e) => e.panel) : null, closingIds };
+}

package/panels/usePanelManager.d.ts

@@ -0,0 +1,74 @@
+import type { Dispatch, SetStateAction } from 'react';
+import type { FormFactor } from '../hostApi.js';
+import { type PanelWindow } from '../panelWindow.js';
+export interface UsePanelManagerResult {
+    revealPanelProactively: (panelsNow: PanelWindow[], apply: (prev: PanelWindow[]) => PanelWindow[]) => void;
+    handleActivatePanel: (id: string) => void;
+    /**
+     * Removes `id` from the collapse-order stack if it is there. useProvidePanels.ts's `onAfterClose` calls it
+     * for whatever id usePanelClosing just closed, live or parked, so a closed panel -- or one later restored
+     * by `undoClose` -- never leaves a stale entry a later reveal could resurrect. A no-op for an id not on the
+     * stack.
+     */
+    forgetCollapsed: (id: string) => void;
+    /**
+     * Given the panels array immediately AFTER a close, reveals the most recently parked panel that fits
+     * beside the live ones (the capacity RISE's own settle rule), or none; one that doesn't fit stays on the
+     * stack for a later close. With equal widths the most recent one fits exactly when any does. Also drops
+     * any stack entry that no longer points at a parked panel -- the backstop for `clearAll()`, which wipes
+     * panels without going through `forgetCollapsed`.
+     */
+    revealMostRecentlyCollapsed: (panelsAfterClose: PanelWindow[]) => void;
+    /**
+     * Ids (re)entering `live` via `revealMostRecentlyCollapsed` or usePanelClosing.ts's `undoClose` of a LIVE
+     * panel (its `onRestoreLive`). PanelRow consults it only when `id` has no `enterSideById` entry: an
+     * explicit gesture/capacity-rise side always wins.
+     */
+    enteringViaAnchorIds: ReadonlySet<string>;
+    /** Marks `id` as entering via the anchor formula -- see `enteringViaAnchorIds`'s own doc comment for who calls this and why. */
+    markEnteringViaAnchor: (id: string) => void;
+    /**
+     * Drops any stale `enterSideById`/`exitRightIds` entry `id` picked up from an EARLIER park (ids cycle
+     * live/parked repeatedly over a session) -- every path that revives a panel via the anchor formula must
+     * call this FIRST, or a stale explicit side would win over the anchor formula (PanelRow's own
+     * precedence) and the revived panel would slide in from the wrong side.
+     */
+    clearEnterSide: (id: string) => void;
+    /**
+     * The row gesture (wheel or arrow key, wired in `useRowScrollGesture.ts`): 'right' promotes the first parked
+     * panel after the current rightmost live panel and parks the LEFTMOST live one; 'left' is the mirror. One
+     * reveal per call, in one commit: when the revealed panel is wider than the one parked, the next live
+     * panels on the same side park too until the row settles, never a panel another action in the same update
+     * keeps live. With nothing parked on that side, does nothing (no `setPanels` at all).
+     */
+    scrollRow: (direction: 'left' | 'right') => void;
+    /**
+     * Moves `id` one row-slot toward `direction`: move-by-one, not move-to-index, so no raw array position crosses
+     * the PanelsAPI boundary. See `movePanel` (panelWindow.ts) for the no-op contract.
+     */
+    reorderPanel: (id: string, direction: 'left' | 'right') => void;
+    /**
+     * PanelsAPI.setFormFactor: panelWindow.ts's `setFormFactor` through setPanels. If the row no longer fits,
+     * the same update parks what the capacity reconcile's DROP would (`fewestParksThatSettle`), keeping `id` and
+     * every other panel acted on in this handler live, so no committed row overflows. False for a no-op (see
+     * `setFormFactor`), which changes nothing.
+     */
+    resizePanel: (id: string, next: FormFactor) => boolean;
+    /**
+     * Explicit enter sides set by `scrollRow` and the capacity-rise reconcile -- PanelRow's own
+     * `enterSideById` prop. Wins over `enteringViaAnchorIds`/`anchoredEnter`: those two describe "enters via
+     * the anchor formula" as a boolean, which cannot express "enters from the LEFT because a rightward
+     * gesture revealed it", the case this exists for.
+     */
+    enterSideById: ReadonlyMap<string, 'left' | 'right'>;
+    /**
+     * Ids currently parking with an exit to the RIGHT; every other park defaults to 'left', so only this
+     * minority needs a mark. Set via `flushSync` BEFORE the parking `setPanels` call: AnimatePresence reads
+     * an exiting child's `exit` prop from its LAST render before it left `present`, and a plain `setState`
+     * here would batch with that commit instead of rendering "still present, but marked" first.
+     */
+    exitRightIds: ReadonlySet<string>;
+}
+export declare function usePanelManager(panels: PanelWindow[], setPanels: Dispatch<SetStateAction<PanelWindow[]>>, storedMaxPanels: number | null, phoneWidth: number, containerWidth: number, 
+/** 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: number, rootId: string): UsePanelManagerResult;