phonux 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "phonux",
+  "version": "0.1.0",
+  "description": "A phone-shaped view host for React: write a view against a small set of host APIs, register it, and render it in one HostProvider.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "@mui/material": "^9.3.1",
+    "@mui/icons-material": "^9.3.1",
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.1",
+    "motion": "^13.3.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./testing": {
+      "types": "./fakeHost.d.ts",
+      "import": "./fakeHost.js"
+    }
+  }
+}

package/panelCapacity.d.ts

@@ -0,0 +1,15 @@
+/**
+ * How many panels the row keeps live at once, from the stored setting, the fit count and the seated
+ * permanent-column count. Pure and free of device state, so it is testable without a window.
+ */
+/**
+ * The live cap on how many panels (every permanent column plus web panels together) may be live at once,
+ * from the stored setting, the current fit count and how many permanent columns (`collapsible:false`, e.g.
+ * History) are seated right now. `fitCount === null` means unmeasured: no cap at all (Infinity) -- the first
+ * commit, and every jsdom test that never calls measure(). Otherwise the floor of `fixedColumnCount + 1` wins
+ * over a stored value or a fit count below it (every permanent column plus at least one web panel stays on
+ * screen even at the narrowest legal window), and a stored value above the fit count is capped at the fit
+ * count. At `fixedColumnCount === 1` (History alone) this floor is 2.
+ * @internal
+ */
+export declare function effectiveMaxPanels(stored: number | null, fitCount: number | null, fixedColumnCount: number): number;

package/panelCapacity.js

@@ -0,0 +1,19 @@
+/**
+ * How many panels the row keeps live at once, from the stored setting, the fit count and the seated
+ * permanent-column count. Pure and free of device state, so it is testable without a window.
+ */
+/**
+ * The live cap on how many panels (every permanent column plus web panels together) may be live at once,
+ * from the stored setting, the current fit count and how many permanent columns (`collapsible:false`, e.g.
+ * History) are seated right now. `fitCount === null` means unmeasured: no cap at all (Infinity) -- the first
+ * commit, and every jsdom test that never calls measure(). Otherwise the floor of `fixedColumnCount + 1` wins
+ * over a stored value or a fit count below it (every permanent column plus at least one web panel stays on
+ * screen even at the narrowest legal window), and a stored value above the fit count is capped at the fit
+ * count. At `fixedColumnCount === 1` (History alone) this floor is 2.
+ * @internal
+ */
+export function effectiveMaxPanels(stored, fitCount, fixedColumnCount) {
+    if (fitCount === null)
+        return Number.POSITIVE_INFINITY;
+    return Math.max(fixedColumnCount + 1, Math.min(stored ?? fitCount, fitCount));
+}

package/panelRowEntry.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The row's own record of one panel, and the one projection from it to what a view may see. The row needs
+ * layout fields a view must never read, so the two are separate types (see DESIGN.md, PanelSummary).
+ */
+import type { JsonValue, PanelSummary } from './hostApi.js';
+import type { PanelAnchor } from './panelRowOrder.js';
+/**
+ * One entry of a panel row: everything a view sees (PanelSummary) plus the layout fields only the row reads.
+ * @public
+ */
+export interface PanelRowEntry<P = JsonValue> extends PanelSummary<P> {
+    /** The registered view that renders this entry. An unregistered name renders a placeholder, never a crash. */
+    readonly view: string;
+    /** False for an always-shown column: the row never parks it and it is never a drag source. */
+    readonly collapsible: boolean;
+    /** Where this entry sits in the row. Undefined for the row's root; any other entry without one stays where it stands. */
+    readonly anchor?: PanelAnchor;
+    /** Which of the row's two stacking tiers this entry's slot sits in. Default 'base'. */
+    readonly layer?: 'base' | 'raised';
+    /** Whether a reappearance enters from its anchor's side instead of from the right. Default false. */
+    readonly anchoredEnter?: boolean;
+}
+/**
+ * The widths of the present panels a drag can cross, nearest first on each side. An always-shown column is
+ * included: only the dragged panel must be collapsible.
+ * @public
+ */
+export interface NeighborWidths {
+    readonly left: readonly number[];
+    readonly right: readonly number[];
+}
+/**
+ * A row entry narrowed to what a view may see. Every place that hands a panel to a view goes through this one
+ * function, so no view ever sees a layout field; `formFactor` and `size` are forwarded.
+ * @public
+ */
+export declare const summarisePanel: ({ id, url, title, live, locked, params, formFactor, size }: PanelRowEntry) => PanelSummary;

package/panelRowEntry.js

@@ -0,0 +1,11 @@
+/**
+ * A row entry narrowed to what a view may see. Every place that hands a panel to a view goes through this one
+ * function, so no view ever sees a layout field; `formFactor` and `size` are forwarded.
+ * @public
+ */
+export const summarisePanel = ({ id, url, title, live, locked, params, formFactor, size }) => ({
+    id, url, title, live, locked, params,
+    // Absent, not undefined, when the record lacks them: a summary never lists a key its record never had.
+    ...(formFactor !== undefined ? { formFactor } : {}),
+    ...(size !== undefined ? { size } : {}),
+});

package/panelRowLayout.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Pure row-layout arithmetic: the row's centring margin, how many live panels fit, and how wide one may be.
+ * Zero DOM imports, so test/panel-layout.test.ts runs it under plain node.
+ */
+/** One row's measurements: what computeRowLayout and computeMaxLiveWidth read. @public */
+export interface RowLayoutInput {
+    /** The row container's measured width. The caller measures it, so this function touches no DOM. */
+    containerWidth: number;
+    /** The default/live phone width -- every FIXED row item is exactly this wide (a permanent column never
+     * changes form factor), and it is also the width assumed for a hypothetical slot beyond `liveWidths` --
+     * see `maxLiveThatFit`'s own doc comment. */
+    phoneWidth: number;
+    /** The row's own gap between adjacent items (PanelRowSlot's `GAP`). */
+    gap: number;
+    /** How many always-rendered (non-collapsible) slots the row holds: a plain count, so this function stays
+     * free of the caller's panel state. */
+    fixedItemCount: number;
+    /**
+     * Each LIVE collapsible panel's own width, in row order -- a 'tablet'/'desktop' panel contributes its own
+     * (wider) width instead of `phoneWidth`, so it alone lowers how many more panels fit. An empty array (no
+     * live panel known yet) still yields the full `phoneWidth`-based ceiling -- see `maxLiveThatFit`.
+     */
+    liveWidths: readonly number[];
+}
+/** How many live panels fit in one row, and where that row starts so it is centered. @public */
+export interface RowLayoutResult {
+    /**
+     * How many live panels the row can show at most: those of `liveWidths` that fit in row order, plus, when all
+     * of them fit, however many more `phoneWidth` slots fit in the budget left. With every entry exactly
+     * `phoneWidth` this does not depend on `liveWidths.length`, so `[]` (nothing live yet) gives the same ceiling.
+     * The host's panel capacity and SettingsAPI's `fitCount` both derive from this.
+     */
+    maxLiveThatFit: number;
+    /** `liveWidths.length`, capped at `maxLiveThatFit`: the centering math's view of what renders. Which
+     * entries render is decided by `live`, not here. */
+    effectiveLiveCount: number;
+    /** The fixed items' width plus the first `effectiveLiveCount` entries' own widths (each plus one gap). */
+    rowTotalWidth: number;
+    /** The `marginLeft` that centers `rowTotalWidth` in the row's available width, floored at 0 when the fixed
+     * items alone are wider. */
+    computedRowMarginLeft: number;
+}
+/**
+ * The row's centering math. `fixedItemCount` must come from the same array the row renders, never a
+ * hand-mirrored copy of its conditions, or a drifted count silently mis-centers the row by half an item.
+ * `maxLiveThatFit` is the one "how many fit" answer, so a wider panel lowers the count instead of overflowing.
+ * @public
+ */
+export declare function computeRowLayout({ containerWidth, phoneWidth, gap, fixedItemCount, liveWidths }: RowLayoutInput): RowLayoutResult;
+/**
+ * The widest ONE live panel can be beside the fixed items and still fit: `computeRowLayout`'s live budget less
+ * that panel's gap. `panelWidthOf` caps a tablet/desktop panel at this, so its tier width is a maximum and a
+ * wide panel never overflows a narrow window. Never below `phoneWidth`: when not even a phone fits, a narrower
+ * "tablet" would not fit either. Infinity while unmeasured (`containerWidth` 0), as every reader treats 0.
+ * @public
+ */
+export declare function computeMaxLiveWidth(input: Omit<RowLayoutInput, 'liveWidths'>): number;

package/panelRowLayout.js

@@ -0,0 +1,52 @@
+/**
+ * Pure row-layout arithmetic: the row's centring margin, how many live panels fit, and how wide one may be.
+ * Zero DOM imports, so test/panel-layout.test.ts runs it under plain node.
+ */
+/**
+ * The row's centering math. `fixedItemCount` must come from the same array the row renders, never a
+ * hand-mirrored copy of its conditions, or a drifted count silently mis-centers the row by half an item.
+ * `maxLiveThatFit` is the one "how many fit" answer, so a wider panel lowers the count instead of overflowing.
+ * @public
+ */
+export function computeRowLayout({ containerWidth, phoneWidth, gap, fixedItemCount, liveWidths }) {
+    const { availableForRow, fixedWidth, usedBudget } = rowBudget({ containerWidth, phoneWidth, gap, fixedItemCount });
+    // Stopping at the first width that does not fit answers "how many of THESE fit", which the host's overflow
+    // enforcement reads. Only when all fit are phoneWidth slots added: without them an empty `liveWidths` would
+    // report 0 rather than how many phone panels fit.
+    let runningWidth = 0;
+    let fittingCount = 0;
+    for (const width of liveWidths) {
+        const itemSpan = width + gap;
+        if (runningWidth + itemSpan > usedBudget)
+            break;
+        runningWidth += itemSpan;
+        fittingCount++;
+    }
+    const extraSlots = fittingCount === liveWidths.length ? Math.max(0, Math.floor((usedBudget - runningWidth) / (phoneWidth + gap))) : 0;
+    const maxLiveThatFit = Math.max(0, fittingCount + extraSlots);
+    const effectiveLiveCount = Math.min(liveWidths.length, maxLiveThatFit);
+    let effectiveLiveWidth = 0;
+    for (let i = 0; i < effectiveLiveCount; i++)
+        effectiveLiveWidth += liveWidths[i] + gap;
+    const rowTotalWidth = fixedWidth + effectiveLiveWidth;
+    const computedRowMarginLeft = Math.max(0, (availableForRow - rowTotalWidth) / 2);
+    return { maxLiveThatFit, effectiveLiveCount, rowTotalWidth, computedRowMarginLeft };
+}
+/** The row's width, the fixed items' share of it, and what is left for live panels (each counted with its own gap). */
+function rowBudget({ containerWidth, phoneWidth, gap, fixedItemCount }) {
+    const availableForRow = Math.max(0, containerWidth - 2 * gap);
+    const fixedWidth = fixedItemCount * phoneWidth + (fixedItemCount - 1) * gap;
+    return { availableForRow, fixedWidth, usedBudget: availableForRow - fixedWidth };
+}
+/**
+ * The widest ONE live panel can be beside the fixed items and still fit: `computeRowLayout`'s live budget less
+ * that panel's gap. `panelWidthOf` caps a tablet/desktop panel at this, so its tier width is a maximum and a
+ * wide panel never overflows a narrow window. Never below `phoneWidth`: when not even a phone fits, a narrower
+ * "tablet" would not fit either. Infinity while unmeasured (`containerWidth` 0), as every reader treats 0.
+ * @public
+ */
+export function computeMaxLiveWidth(input) {
+    if (input.containerWidth === 0)
+        return Number.POSITIVE_INFINITY;
+    return Math.max(input.phoneWidth, rowBudget(input).usedBudget - input.gap);
+}

package/panelRowOrder.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Row order as anchor metadata: every entry but the row's root names the entry it sits beside, the side, and
+ * how near. computeRowOrder turns anchors into an order; deriveAnchorsFromOrder turns an order back into anchors.
+ * The root's id is always a parameter, never a constant here: which entry is the root is the app's choice.
+ */
+/**
+ * An entry's place in the row: on `position`'s side of the entry `panel`, ranked by `priority` among the
+ * entries on that same side of that same entry. Lower is nearer; ties keep the current row order.
+ * @public
+ */
+export interface PanelAnchor {
+    panel: string;
+    position: 'left' | 'right';
+    priority: number;
+}
+/**
+ * The entries in the order their anchors describe: a walk from the root, each entry's left side (farthest
+ * first), then the entry, then its right side (nearest first). Priorities come back renumbered from 0 per side
+ * of each entry, so a priority of -1 always lands nearest. An anchor naming a missing entry, or one in a cycle,
+ * falls back to the root's right side (keeping its priority) instead of recursing forever or dropping the entry.
+ * @public
+ */
+export declare function computeRowOrder<T extends {
+    id: string;
+    anchor?: PanelAnchor;
+}>(panels: readonly T[], rootId: string): T[];
+/**
+ * Every non-root entry re-anchored to the root from its current array position, so computeRowOrder reproduces
+ * this exact order.
+ * @public
+ */
+export declare function deriveAnchorsFromOrder<T extends {
+    id: string;
+    anchor?: PanelAnchor;
+}>(panels: readonly T[], rootId: string): T[];
+export type EnterDirection = 'left' | 'right';
+/** The id of the entry `panel` orients its enter animation against: its anchor's, or the root's when it has none. */
+export declare function anchorTargetOf(panel: {
+    anchor?: PanelAnchor;
+}, rootId: string): string;
+/**
+ * Which side a reappearing entry enters from: the side its anchor entry sits on. Both indexes must count in the
+ * SAME present list the row renders, never the raw array, which miscounts whenever an entry is parked. -1 for
+ * either (not present) falls back to 'right', the row's default; the root against itself compares equal, so 'right'.
+ */
+export declare function resolveEnterDirection(anchorIndex: number, ownIndex: number): EnterDirection;

package/panelRowOrder.js

@@ -0,0 +1,105 @@
+/**
+ * Row order as anchor metadata: every entry but the row's root names the entry it sits beside, the side, and
+ * how near. computeRowOrder turns anchors into an order; deriveAnchorsFromOrder turns an order back into anchors.
+ * The root's id is always a parameter, never a constant here: which entry is the root is the app's choice.
+ */
+const sameAnchor = (a, b) => !!a && a.panel === b.panel && a.position === b.position && a.priority === b.priority;
+/** Spreads the whole record: every other field must survive a re-anchor untouched. */
+const withAnchor = (p, anchor) => (sameAnchor(p.anchor, anchor) ? p : { ...p, anchor });
+/** Every non-root entry's anchor as read off its array position alone: the root's side, 0 = nearest. With no root present, every entry reads 'right'. */
+function positionalAnchors(panels, rootId) {
+    const root = panels.findIndex((p) => p.id === rootId);
+    const out = new Map();
+    panels.forEach((p, i) => {
+        if (p.id !== rootId)
+            out.set(p.id, i < root ? { panel: rootId, position: 'left', priority: root - 1 - i } : { panel: rootId, position: 'right', priority: i - root - 1 });
+    });
+    return out;
+}
+/**
+ * The entries in the order their anchors describe: a walk from the root, each entry's left side (farthest
+ * first), then the entry, then its right side (nearest first). Priorities come back renumbered from 0 per side
+ * of each entry, so a priority of -1 always lands nearest. An anchor naming a missing entry, or one in a cycle,
+ * falls back to the root's right side (keeping its priority) instead of recursing forever or dropping the entry.
+ * @public
+ */
+export function computeRowOrder(panels, rootId) {
+    const byId = new Map(panels.map((p) => [p.id, p]));
+    const rowIndex = new Map(panels.map((p, i) => [p.id, i]));
+    const positional = positionalAnchors(panels, rootId);
+    const declared = (p) => p.anchor ?? positional.get(p.id);
+    const fallback = new Set();
+    const visiting = new Set();
+    const resolved = new Set();
+    const resolve = (id, path) => {
+        if (resolved.has(id))
+            return;
+        if (visiting.has(id)) {
+            for (const member of path.slice(path.indexOf(id)))
+                fallback.add(member);
+            return;
+        }
+        visiting.add(id);
+        const target = declared(byId.get(id)).panel;
+        if (target !== rootId) {
+            if (byId.has(target))
+                resolve(target, [...path, id]);
+            else
+                fallback.add(id);
+        }
+        visiting.delete(id);
+        resolved.add(id);
+    };
+    const effective = (p) => (fallback.has(p.id) ? { panel: rootId, position: 'right', priority: declared(p).priority } : declared(p));
+    const sides = new Map();
+    for (const p of panels) {
+        if (p.id === rootId)
+            continue;
+        resolve(p.id, []);
+    }
+    for (const p of panels) {
+        if (p.id === rootId)
+            continue;
+        const { panel, position } = effective(p);
+        const side = sides.get(panel) ?? { left: [], right: [] };
+        side[position].push(p);
+        sides.set(panel, side);
+    }
+    // Nearest first; on a tie the entry nearer in the current row wins (later on the left, earlier on the right).
+    const nearestFirst = (list, position) => [...list].sort((a, b) => effective(a).priority - effective(b).priority || (position === 'right' ? 1 : -1) * (rowIndex.get(a.id) - rowIndex.get(b.id)));
+    const out = [];
+    const walk = (id, self) => {
+        const side = sides.get(id);
+        const left = nearestFirst(side?.left ?? [], 'left');
+        for (let k = left.length - 1; k >= 0; k--)
+            walk(left[k].id, withAnchor(left[k], { panel: id, position: 'left', priority: k }));
+        if (self)
+            out.push(self);
+        nearestFirst(side?.right ?? [], 'right').forEach((p, k) => walk(p.id, withAnchor(p, { panel: id, position: 'right', priority: k })));
+    };
+    walk(rootId, byId.get(rootId));
+    return out;
+}
+/**
+ * Every non-root entry re-anchored to the root from its current array position, so computeRowOrder reproduces
+ * this exact order.
+ * @public
+ */
+export function deriveAnchorsFromOrder(panels, rootId) {
+    const positional = positionalAnchors(panels, rootId);
+    return panels.map((p) => (p.id === rootId ? p : withAnchor(p, positional.get(p.id))));
+}
+/** The id of the entry `panel` orients its enter animation against: its anchor's, or the root's when it has none. */
+export function anchorTargetOf(panel, rootId) {
+    return panel.anchor?.panel ?? rootId;
+}
+/**
+ * Which side a reappearing entry enters from: the side its anchor entry sits on. Both indexes must count in the
+ * SAME present list the row renders, never the raw array, which miscounts whenever an entry is parked. -1 for
+ * either (not present) falls back to 'right', the row's default; the root against itself compares equal, so 'right'.
+ */
+export function resolveEnterDirection(anchorIndex, ownIndex) {
+    if (anchorIndex < 0 || ownIndex < 0)
+        return 'right';
+    return anchorIndex < ownIndex ? 'left' : 'right';
+}

package/panelTiers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Panel tiers: each form factor's own size, and the one rule for how wide a panel is in the row. Pure, and
+ * free of live device state, so the row's state functions stay pure too.
+ */
+import { type FormFactor, type PanelSize } from './hostApi.js';
+import type { PanelRowEntry } from './panelRowEntry.js';
+/**
+ * The size every panel starts at: the phone tier at the built-in phone size.
+ * @public
+ */
+export declare const DEFAULT_PANEL_SIZE: PanelSize;
+/**
+ * Each tier's own size. The 'phone' entry is only a placeholder: a phone panel renders at the live phone size.
+ * 'fill' is the row's own height. Frozen because every panel starts out referencing these same objects.
+ * @public
+ */
+export declare const TIER_SIZES: Readonly<Record<FormFactor, PanelSize>>;
+/**
+ * A panel's own width in the row. A phone panel always takes the live `phoneWidth`, never its stored size, which
+ * is only a placeholder. A tablet or desktop panel takes its stored width, capped at `maxLiveWidth` so it always
+ * fits beside the row's fixed columns.
+ * @public
+ */
+export declare function panelWidthOf(p: Pick<PanelRowEntry, 'formFactor' | 'size'>, phoneWidth: number, maxLiveWidth: number): number;

package/panelTiers.js

@@ -0,0 +1,29 @@
+/**
+ * Panel tiers: each form factor's own size, and the one rule for how wide a panel is in the row. Pure, and
+ * free of live device state, so the row's state functions stay pure too.
+ */
+import { DEFAULT_PHONE_SIZE } from './hostApi.js';
+/**
+ * The size every panel starts at: the phone tier at the built-in phone size.
+ * @public
+ */
+export const DEFAULT_PANEL_SIZE = Object.freeze({ formFactor: 'phone', width: DEFAULT_PHONE_SIZE.width, height: DEFAULT_PHONE_SIZE.height });
+/**
+ * Each tier's own size. The 'phone' entry is only a placeholder: a phone panel renders at the live phone size.
+ * 'fill' is the row's own height. Frozen because every panel starts out referencing these same objects.
+ * @public
+ */
+export const TIER_SIZES = Object.freeze({
+    phone: DEFAULT_PANEL_SIZE,
+    tablet: Object.freeze({ formFactor: 'tablet', width: 768, height: 'fill' }),
+    desktop: Object.freeze({ formFactor: 'desktop', width: 1200, height: 'fill' }),
+});
+/**
+ * A panel's own width in the row. A phone panel always takes the live `phoneWidth`, never its stored size, which
+ * is only a placeholder. A tablet or desktop panel takes its stored width, capped at `maxLiveWidth` so it always
+ * fits beside the row's fixed columns.
+ * @public
+ */
+export function panelWidthOf(p, phoneWidth, maxLiveWidth) {
+    return (p.formFactor ?? 'phone') === 'phone' ? phoneWidth : Math.min(p.size?.width ?? phoneWidth, maxLiveWidth);
+}

package/panelWindow.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The `PanelWindow` model -- one browsing panel in the unified row -- and every pure state-transition
+ * function that operates on a `PanelWindow[]` array.
+ */
+import type { FormFactor, JsonValue, PanelSize } from './hostApi.js';
+import type { NeighborWidths } from './panelRowEntry.js';
+import type { PanelAnchor } from './panelRowOrder.js';
+export type { FormFactor, JsonValue, PanelSize };
+export type { PanelAnchor };
+export type { NeighborWidths };
+export { effectiveMaxPanels } from './panelCapacity.js';
+/**
+ * One browsing panel in the unified row: either live in the row or parked, never both. Parking only flips
+ * `live`; it never removes the entry from the array, only `closePanel` does.
+ * @public
+ */
+export interface PanelWindow {
+    id: string;
+    url: string;
+    title?: string;
+    /** Host-supplied and opaque: every function here only copies it through, never reads or branches on it. Its
+     * shape is a host-side agreement `JsonValue` cannot enforce. */
+    hostData?: JsonValue;
+    /** Mounted in the row right now. `false` means parked: still in this array, just not rendered. */
+    live: boolean;
+    /** Whether DragToClose's drag-down gesture may close this panel at all. Every panel created by `appendPanel` is unlocked. */
+    locked: boolean;
+    /** Which component renders this entry (phonux's registry, resolveView) -- read ONLY by the row (PanelRow); every park/close site reads `collapsible`/`listed`/`locked` instead, never this. An open string, not a closed union: an unregistered value renders a placeholder, never a crash. */
+    view: string;
+    /** Capacity parks (an open, a revive, the row gesture, a capacity drop) may park this entry; `false` marks an always-shown column exempt from all of them. */
+    collapsible: boolean;
+    /** Appears in the public `panelList` (History's own row list, and PanelsAPI). */
+    listed: boolean;
+    /** Opaque per-panel data a create() caller supplied (PanelsAPI.create's `params`); undefined for built-ins. summarisePanel threads it to PanelSummary.params; no behavior site here reads it. */
+    params?: JsonValue;
+    /** Where this entry sits in the row (computeRowOrder). Undefined only for History, the root; a hand-built record without one reads as anchored where it already stands, and computeRowOrder writes that anchor. */
+    anchor?: PanelAnchor;
+    /** Which of the row's two stacking tiers this entry's slot sits in -- read ONLY by PanelRow's per-slot zIndex. Default 'base'. */
+    layer?: 'base' | 'raised';
+    /** Whether this entry's reappearance always resolves through the anchor formula (resolveEnterDirection) instead of unconditionally entering from the right -- read ONLY by PanelRow's enterDirection. Default false. */
+    anchoredEnter?: boolean;
+    /** This panel's own visual tier; createHistoryPanel/appendPanel always set it. Optional so a record built by hand without it still typechecks. */
+    formFactor?: FormFactor;
+    /** This panel's own rendered size (a host's panel component passes it to Panel/PanelFrame for a non-phone tier). Optional for the same reason as `formFactor`. */
+    size?: PanelSize;
+}
+/** 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 declare function createHistoryPanel(rootId: string): PanelWindow;
+/**
+ * Per-call metadata create() may set beyond a bare url/source. No raw `collapsible`/`locked` key: `permanent`
+ * is the only door to `collapsible:false` (see `appendPanel`'s own doc comment for what it forces), and
+ * `locked` is never settable at all -- create() can never make an unclosable panel.
+ * @internal
+ */
+export interface AppendPanelOptions {
+    view?: string;
+    title?: string;
+    params?: JsonValue;
+    /** Copied through to the new entry's `hostData` unchanged; absent means the entry carries no `hostData` key at all (never an explicit `undefined`). */
+    hostData?: JsonValue;
+    listed?: boolean;
+    /** `panel` defaults to History, `priority` to one past the far end of that side. Default \{ position: 'right' \}. */
+    anchor?: {
+        panel?: string;
+        position: 'left' | 'right';
+        priority?: number;
+    };
+    layer?: 'base' | 'raised';
+    anchoredEnter?: boolean;
+    /** See `CreatePanelOptions.permanent` (hostApi.tsx) for the full contract; `appendPanel` is what enforces it. */
+    permanent?: boolean;
+    /** The new panel's tier. Ignored for a permanent column, which is always 'phone'. Default 'phone'. */
+    formFactor?: FormFactor;
+}
+/** @internal */
+export type AnchorRequest = NonNullable<AppendPanelOptions['anchor']>;
+/** `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 declare function reanchorPanel(panels: PanelWindow[], id: string, request: AnchorRequest, rootId: string): PanelWindow[];
+/**
+ * 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 declare function appendPanel(panels: PanelWindow[], info: {
+    url: string;
+} & AppendPanelOptions, id: string, rootId: string): PanelWindow[];
+/**
+ * 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 declare function farthestLiveCollapsibleId(panels: PanelWindow[], fromIndex: number, exclude?: ReadonlySet<string>): string | null;
+/**
+ * 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 declare function sideOfLiveRange(panels: PanelWindow[], id: string): 'left' | 'right';
+/** The row-slot index of the LEFTMOST (lowest-index) live collapsible panel, or -1 if none are live. @internal */
+export declare function leftmostLiveIndex(panels: PanelWindow[]): number;
+/** The row-slot index of the RIGHTMOST (highest-index) live collapsible panel, or -1 if none are live. @internal */
+export declare function rightmostLiveIndex(panels: PanelWindow[]): number;
+/** 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 declare function firstParkedAfter(panels: PanelWindow[], index: number): PanelWindow | 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 declare function lastParkedBefore(panels: PanelWindow[], index: number): PanelWindow | 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 declare function promoteToLive(panels: PanelWindow[], id: string, capacity: number, keep?: ReadonlySet<string>): PanelWindow[] | null;
+/**
+ * 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 declare function closePanel(panels: PanelWindow[], id: string, rootId: string): {
+    remaining: PanelWindow[];
+    closed: PanelWindow;
+    index: number;
+} | null;
+/**
+ * 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 declare function movePanel(panels: PanelWindow[], id: string, direction: 'left' | 'right', rootId: string): PanelWindow[];
+/**
+ * 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 declare function reorderStepsForOffset(offsetX: number, neighbors: NeighborWidths, gap: number): number;
+/**
+ * `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 declare function setFormFactor(panels: PanelWindow[], id: string, next: FormFactor): PanelWindow[];
+/**
+ * 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 declare function restorePanel(panels: PanelWindow[], panel: PanelWindow, index: number, rootId: string): PanelWindow[];