phonux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jojos-Creations
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Panel.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The shared shell every column in the row renders through -- Settings, History and each live
+ * panel build their own content, then hand it to Panel for the `position: relative` +
+ * `width: phoneWidth` wrapper box and PanelHeaderRow's floating title pill above it. Deliberately
+ * a SHELL, not a content container: it does not render PanelFrame itself, so a caller's `children`
+ * (already one or more PanelFrame elements) needs no change to move under Panel.
+ */
+import * as React from 'react';
+import { type BoxProps } from '@mui/material/Box';
+import { type PanelHeaderRowProps } from './PanelFrame.js';
+import { type PanelSize } from './hostApi.js';
+import { type ViewId } from './snapshots.js';
+export { HostMissingProviderError, HostProvider, useHost } from './hostApi.js';
+export type { Host } from './hostApi.js';
+/** @deprecated use HostMissingProviderError, HostProvider, useHost */
+export { PhoneAPIsMissingProviderError, PhoneAPIsProvider, usePhoneAPIs } from './hostApi.js';
+/** @deprecated use Host */
+export type { PhoneAPIs } from './hostApi.js';
+export { DRAG_CLOSE, DragToClose, shouldCloseOnRelease, type DragHandleProps, type ReleaseMeasure, type ReorderHandle } from './dragToClose.js';
+export { WindowOverlay, OverlaySlot, OVERLAY_Z, OverlayProvider, OverlayStore, type OverlaySlotName, type WindowOverlayProps, type Item, type Entry } from './windowOverlay.js';
+/** @public */
+export interface PanelProps extends Omit<BoxProps, 'children' | 'sx' | 'title'> {
+    /**
+     * The header pill's title. Omitted entirely (not passed at all) renders
+     * NO header row, rather than forcing the view into
+     * PanelHeaderRow's own "Untitled" placeholder. Pass an
+     * explicit falsy value (e.g. `''`) to get that placeholder on purpose.
+     */
+    title?: React.ReactNode;
+    actions?: React.ReactNode;
+    /**
+     * Extra PanelHeaderRow props beyond title/actions -- the drag handle
+     * of a DragToClose view (`onPointerDown`, `sx`), `data-*` attributes, etc. The `data-${string}` index signature is
+     * needed because TS's "data-* is always valid" leniency only applies to
+     * attributes written directly on a JSX element -- it does not extend to a
+     * plain object literal like this one being checked against
+     * PanelHeaderRowProps before it ever reaches JSX.
+     */
+    headerProps?: Omit<PanelHeaderRowProps, 'title' | 'actions'> & {
+        [key: `data-${string}`]: string | boolean | undefined;
+    };
+    /**
+     * The grab handle for dragging this Panel (DragToClose's `onPointerDown`/`sx`), rendered as its OWN
+     * element filling the gap between the header and the frame -- never spread onto `headerProps` -- so a
+     * click on the title text or an action icon in the header is never mistaken for a drag start. Omitted
+     * (the usual case for a locked view, e.g. History) renders no grab bar at all.
+     */
+    grabProps?: Omit<BoxProps, 'children'> & {
+        [key: `data-${string}`]: string | boolean | undefined;
+    };
+    /**
+     * Content positioned absolutely over this view (History's own "+" Fab,
+     * bottom-right) -- rendered as a plain sibling of `children` inside this
+     * component's own `position: relative` box, which is already the
+     * positioning context an `overlay` needs.
+     */
+    overlay?: React.ReactNode;
+    sx?: BoxProps['sx'];
+    children: React.ReactNode;
+    /**
+     * Registers this Panel's own root element with the desktop's capture registry (see snapshots.ts's
+     * CaptureRegistryContext) so the host can later ask for a picture of it by id. Omitted: never registered.
+     */
+    viewId?: ViewId;
+    /** 'never' opts a Panel with a viewId out of registration entirely -- default 'auto'. */
+    capture?: 'auto' | 'never';
+    /** This panel's own size instead of the shared useHost().device.size. Omitted: the width comes from device.size, read live -- see DESIGN.md. */
+    size?: PanelSize;
+}
+/** @public @deprecated use PanelProps */
+export type PhoneViewProps = PanelProps;
+/** @public */
+export declare function Panel({ title, actions, headerProps, grabProps, overlay, sx, children, viewId, capture, size, ...rest }: PanelProps): React.JSX.Element;
+/** @public @deprecated use Panel */
+export declare const PhoneView: typeof Panel;
+export default Panel;

package/Panel.js

@@ -0,0 +1,45 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The shared shell every column in the row renders through -- Settings, History and each live
+ * panel build their own content, then hand it to Panel for the `position: relative` +
+ * `width: phoneWidth` wrapper box and PanelHeaderRow's floating title pill above it. Deliberately
+ * a SHELL, not a content container: it does not render PanelFrame itself, so a caller's `children`
+ * (already one or more PanelFrame elements) needs no change to move under Panel.
+ */
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import { PANEL_HEADER_GAP_PX, PanelHeaderRow } from './PanelFrame.js';
+import { useHost } from './hostApi.js';
+import { CaptureRegistryContext } from './snapshots.js';
+// One import path for a view author: the contracts, the provider and the hook.
+export { HostMissingProviderError, HostProvider, useHost } from './hostApi.js';
+/** @deprecated use HostMissingProviderError, HostProvider, useHost */
+export { PhoneAPIsMissingProviderError, PhoneAPIsProvider, usePhoneAPIs } from './hostApi.js';
+export { DRAG_CLOSE, DragToClose, shouldCloseOnRelease } from './dragToClose.js';
+export { WindowOverlay, OverlaySlot, OVERLAY_Z, OverlayProvider, OverlayStore } from './windowOverlay.js';
+/** @public */
+export function Panel({ title, actions, headerProps, grabProps, overlay, sx, children, viewId, capture = 'auto', size, ...rest }) {
+    const { device } = useHost();
+    const registry = React.useContext(CaptureRegistryContext);
+    const rootRef = React.useRef(null);
+    React.useEffect(() => {
+        // No registry (a bare <HostProvider>, as in most tests) or opted out: registering is a no-op, never a throw.
+        if (!registry || !viewId || capture === 'never' || !rootRef.current)
+            return undefined;
+        return registry.register(viewId, rootRef.current, 'viewport');
+    }, [registry, viewId, capture]);
+    return (_jsxs(Box, { sx: { position: 'relative', width: size?.width ?? device.size.width, ...sx }, ...rest, ref: rootRef, children: [title !== undefined && _jsx(PanelHeaderRow, { title: title, actions: actions, ...headerProps }), grabProps && (_jsx(Box, { "data-panel-grab-bar": "", ...grabProps, sx: {
+                    position: 'absolute',
+                    bottom: '100%',
+                    left: 0,
+                    right: 0,
+                    height: `${PANEL_HEADER_GAP_PX}px`,
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    ...grabProps.sx,
+                }, children: _jsx(Box, { "aria-hidden": "true", sx: { width: 32, height: 4, borderRadius: 2, bgcolor: 'divider' } }) })), children, overlay] }));
+}
+/** @public @deprecated use Panel */
+export const PhoneView = Panel;
+export default Panel;

package/PanelFrame.d.ts

@@ -0,0 +1,154 @@
+/**
+ * The shared phone-shaped card every view renders inside, so every section reads as one
+ * silhouette instead of near-identical border/radius/background declarations drifting apart.
+ * Fixed size by default; `expanded` is only the tap-to-expand fullscreen overlay. The inset, scrollbar
+ * and header-pill rules below are explained in DESIGN.md ("PanelFrame's inset, scrollbar and header pill").
+ */
+import * as React from 'react';
+import { type BoxProps } from '@mui/material/Box';
+import { type Theme } from '@mui/material/styles';
+import { type PanelSize } from './hostApi.js';
+/** @public */
+export interface PanelFrameProps extends Omit<BoxProps, 'children'> {
+    children: React.ReactNode;
+    /** Fill the available space instead of the fixed phone size (the tap-to-expand overlay). */
+    expanded?: boolean;
+    /** This panel's own size instead of the shared useHost().device.size. Omitted: width and height come from device.size, read live -- see DESIGN.md. `height: 'fill'` renders as `100%` rather than a pixel value. */
+    size?: PanelSize;
+}
+/** @public @deprecated use PanelFrameProps */
+export type PhoneFrameProps = PanelFrameProps;
+/** The phone's corner radius in theme shape units (4 x 6px = 24px). The frame's corners and the header
+ * pills' semicircular ends both derive from it, so they cannot drift apart. @public */
+export declare const PANEL_CORNER_RADIUS_UNITS = 4;
+/** @public @deprecated use PANEL_CORNER_RADIUS_UNITS */
+export declare const PHONE_CORNER_RADIUS_UNITS = 4;
+/** That radius in px for `theme`; a header pill is twice this tall (exact semicircles). @public */
+export declare const panelCornerRadiusPx: (theme: Theme) => number;
+/** @public @deprecated use panelCornerRadiusPx */
+export declare const phoneCornerRadiusPx: (theme: Theme) => number;
+/** The header pill's gap above the frame, in px -- also the grab bar's own height (Panel.tsx),
+ * since the grab bar fills that whole strip. One constant so the two can't drift apart, and sized to WCAG
+ * 2.5.8's 24px minimum pointer-target height even though the drawn pill inside it is thinner. @internal */
+export declare const PANEL_HEADER_GAP_PX = 24;
+/**
+ * Keeps content inset the same from the border on every side, scrollbar or not: `scrollbar-gutter: stable`
+ * reserves the bar's strip, so the right padding is pre-shrunk by its width. A nested scroller needs its own
+ * copy of the `::-webkit-scrollbar` rules below, which style only the element they are set on.
+ * @public
+ */
+export declare const panelFrameScrollSx: {
+    readonly overflowX: "hidden";
+    readonly overflowY: "auto";
+    readonly scrollbarGutter: "stable";
+    readonly pt: "12px";
+    readonly pb: "12px";
+    readonly pl: "12px";
+    readonly pr: "4px";
+    readonly '&::-webkit-scrollbar': {
+        readonly width: 8;
+    };
+    readonly '&::-webkit-scrollbar-track': {
+        readonly background: "transparent";
+    };
+    readonly '&::-webkit-scrollbar-thumb': {
+        readonly background: "rgba(255, 255, 255, 0.25)";
+        readonly borderRadius: number;
+    };
+    readonly '&::-webkit-scrollbar-thumb:hover': {
+        readonly background: "rgba(255, 255, 255, 0.4)";
+    };
+};
+/** @public @deprecated use panelFrameScrollSx */
+export declare const phoneFrameScrollSx: {
+    readonly overflowX: "hidden";
+    readonly overflowY: "auto";
+    readonly scrollbarGutter: "stable";
+    readonly pt: "12px";
+    readonly pb: "12px";
+    readonly pl: "12px";
+    readonly pr: "4px";
+    readonly '&::-webkit-scrollbar': {
+        readonly width: 8;
+    };
+    readonly '&::-webkit-scrollbar-track': {
+        readonly background: "transparent";
+    };
+    readonly '&::-webkit-scrollbar-thumb': {
+        readonly background: "rgba(255, 255, 255, 0.25)";
+        readonly borderRadius: number;
+    };
+    readonly '&::-webkit-scrollbar-thumb:hover': {
+        readonly background: "rgba(255, 255, 255, 0.4)";
+    };
+};
+/**
+ * For a caller doing its own scrolling one level deeper (an embedded web view, a transcript under a
+ * pinned input bar): cancels PanelFrame's own padding AND its reserved scrollbar strip, so
+ * neither is reserved twice. Every property is a longhand -- MUI resolves `p`/`pr` and
+ * `overflow`/`overflowY` independently, so a shorthand spread over a longhand does not reliably win.
+ * @public
+ */
+export declare const panelFrameBareSx: {
+    readonly pt: 0;
+    readonly pr: 0;
+    readonly pb: 0;
+    readonly pl: 0;
+    readonly overflowX: "hidden";
+    readonly overflowY: "hidden";
+    readonly scrollbarGutter: "auto";
+};
+/** @public @deprecated use panelFrameBareSx */
+export declare const phoneFrameBareSx: {
+    readonly pt: 0;
+    readonly pr: 0;
+    readonly pb: 0;
+    readonly pl: 0;
+    readonly overflowX: "hidden";
+    readonly overflowY: "hidden";
+    readonly scrollbarGutter: "auto";
+};
+/**
+ * Two nested boxes: the OUTER owns border, radius and size and clips to the rounded corner; the INNER owns
+ * the padding and is the scroll container. `panelFrameScrollSx` forces a classic scrollbar, because an
+ * overlay one floats over content with an inset no padding can cancel (DESIGN.md).
+ * @public
+ */
+declare const PanelFrame: React.ForwardRefExoticComponent<Omit<PanelFrameProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+/** @public */
+export interface PanelHeaderProps extends Omit<BoxProps, 'children'> {
+    children: React.ReactNode;
+}
+/** @public @deprecated use PanelHeaderProps */
+export type PhoneFrameHeaderProps = PanelHeaderProps;
+/**
+ * A header that floats ABOVE a PanelFrame (`position: absolute; bottom: calc(100% + gap)`), so its parent must
+ * be `position: relative`. Internal layout is not baked in (callers differ): pass `sx`, layered on top. A plain
+ * `Box`, since `Paper`'s polymorphic `component` typing collides with `Omit<BoxProps, ...>`. Drag wiring and
+ * any grab cursor belong on `Panel`'s `grabProps`, never here.
+ * @public
+ */
+export declare function PanelHeader({ children, sx, ...rest }: PanelHeaderProps): React.JSX.Element;
+/** @public @deprecated use PanelHeader */
+export declare const PhoneFrameHeader: typeof PanelHeader;
+/** @public */
+export interface PanelHeaderRowProps extends Omit<PanelHeaderProps, 'children' | 'title'> {
+    /** Left-aligned, ellipsis-truncated. Falsy renders a placeholder ("Untitled") instead of
+     * nothing, so the pill never blanks for a view with no title yet. */
+    title: React.ReactNode;
+    /** Right-aligned, never truncated. Falsy renders a placeholder icon slot instead of nothing,
+     * so a conditional like `isRunning && <IconButton .../>` still keeps the pill's full shape. */
+    actions?: React.ReactNode;
+}
+/** @public @deprecated use PanelHeaderRowProps */
+export type PhoneFrameHeaderRowProps = PanelHeaderRowProps;
+/**
+ * The title-left/actions-right row shape every PanelHeader caller wants, as one shared layout
+ * instead of each call site reimplementing near-identical flex/ellipsis markup. Placeholder
+ * substitution lives HERE, not in each caller, so every caller gets it for free.
+ * @public
+ */
+export declare function PanelHeaderRow({ title, actions, sx, ...rest }: PanelHeaderRowProps): React.JSX.Element;
+/** @public @deprecated use PanelHeaderRow */
+export declare const PhoneFrameHeaderRow: typeof PanelHeaderRow;
+export default PanelFrame;

package/PanelFrame.js

@@ -0,0 +1,160 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * The shared phone-shaped card every view renders inside, so every section reads as one
+ * silhouette instead of near-identical border/radius/background declarations drifting apart.
+ * Fixed size by default; `expanded` is only the tap-to-expand fullscreen overlay. The inset, scrollbar
+ * and header-pill rules below are explained in DESIGN.md ("PanelFrame's inset, scrollbar and header pill").
+ */
+import * as React from 'react';
+import Box from '@mui/material/Box';
+import MoreHorizIcon from '@mui/icons-material/MoreHoriz';
+import { useHost } from './hostApi.js';
+/** The classic (non-overlay) scrollbar this app draws for itself, in px. */
+const SCROLLBAR_PX = 8;
+/** How far content sits from the frame's own border, on every side, in px. */
+const CONTENT_INSET_PX = 12;
+/** The phone's corner radius in theme shape units (4 x 6px = 24px). The frame's corners and the header
+ * pills' semicircular ends both derive from it, so they cannot drift apart. @public */
+export const PANEL_CORNER_RADIUS_UNITS = 4;
+/** @public @deprecated use PANEL_CORNER_RADIUS_UNITS */
+export const PHONE_CORNER_RADIUS_UNITS = PANEL_CORNER_RADIUS_UNITS;
+/** That radius in px for `theme`; a header pill is twice this tall (exact semicircles). @public */
+export const panelCornerRadiusPx = (theme) => PANEL_CORNER_RADIUS_UNITS * Number(theme.shape.borderRadius);
+/** @public @deprecated use panelCornerRadiusPx */
+export const phoneCornerRadiusPx = panelCornerRadiusPx;
+/** The header pill's gap above the frame, in px -- also the grab bar's own height (Panel.tsx),
+ * since the grab bar fills that whole strip. One constant so the two can't drift apart, and sized to WCAG
+ * 2.5.8's 24px minimum pointer-target height even though the drawn pill inside it is thinner. @internal */
+export const PANEL_HEADER_GAP_PX = 24;
+/**
+ * Keeps content inset the same from the border on every side, scrollbar or not: `scrollbar-gutter: stable`
+ * reserves the bar's strip, so the right padding is pre-shrunk by its width. A nested scroller needs its own
+ * copy of the `::-webkit-scrollbar` rules below, which style only the element they are set on.
+ * @public
+ */
+export const panelFrameScrollSx = {
+    overflowX: 'hidden',
+    overflowY: 'auto',
+    scrollbarGutter: 'stable',
+    pt: `${CONTENT_INSET_PX}px`,
+    pb: `${CONTENT_INSET_PX}px`,
+    pl: `${CONTENT_INSET_PX}px`,
+    pr: `${CONTENT_INSET_PX - SCROLLBAR_PX}px`,
+    // Forces a classic (non-overlay) scrollbar: an overlay one reserves no layout width, which
+    // would break the padding math above. Track transparent, thumb a low-contrast fill.
+    '&::-webkit-scrollbar': { width: SCROLLBAR_PX },
+    '&::-webkit-scrollbar-track': { background: 'transparent' },
+    '&::-webkit-scrollbar-thumb': {
+        background: 'rgba(255, 255, 255, 0.25)',
+        borderRadius: SCROLLBAR_PX / 2,
+    },
+    '&::-webkit-scrollbar-thumb:hover': { background: 'rgba(255, 255, 255, 0.4)' },
+};
+/** @public @deprecated use panelFrameScrollSx */
+export const phoneFrameScrollSx = panelFrameScrollSx;
+/**
+ * For a caller doing its own scrolling one level deeper (an embedded web view, a transcript under a
+ * pinned input bar): cancels PanelFrame's own padding AND its reserved scrollbar strip, so
+ * neither is reserved twice. Every property is a longhand -- MUI resolves `p`/`pr` and
+ * `overflow`/`overflowY` independently, so a shorthand spread over a longhand does not reliably win.
+ * @public
+ */
+export const panelFrameBareSx = {
+    pt: 0,
+    pr: 0,
+    pb: 0,
+    pl: 0,
+    overflowX: 'hidden',
+    overflowY: 'hidden',
+    scrollbarGutter: 'auto',
+};
+/** @public @deprecated use panelFrameBareSx */
+export const phoneFrameBareSx = panelFrameBareSx;
+/**
+ * Two nested boxes: the OUTER owns border, radius and size and clips to the rounded corner; the INNER owns
+ * the padding and is the scroll container. `panelFrameScrollSx` forces a classic scrollbar, because an
+ * overlay one floats over content with an inset no padding can cancel (DESIGN.md).
+ * @public
+ */
+const PanelFrame = React.forwardRef(function PanelFrame({ children, expanded, size, sx, ...rest }, ref) {
+    const deviceSize = useHost().device.size;
+    const width = size?.width ?? deviceSize.width;
+    const height = size?.height === 'fill' ? '100%' : (size?.height ?? deviceSize.height);
+    return (_jsx(Box, { ref: ref, "data-phone-frame": "", ...rest, sx: {
+            // border-box: row-layout width math elsewhere treats device.size as this box's real
+            // rendered size; content-box would add border+padding on top, silently under-fitting.
+            boxSizing: 'border-box',
+            border: '1px solid',
+            borderColor: 'divider',
+            borderRadius: PANEL_CORNER_RADIUS_UNITS,
+            bgcolor: 'background.paper',
+            display: 'flex',
+            flexDirection: 'column',
+            overflow: 'hidden',
+            flexShrink: 0,
+            ...(expanded ? { width: '100%', height: '100%' } : { width, height }),
+        }, children: _jsx(Box, { sx: {
+                flex: 1,
+                minHeight: 0,
+                display: 'flex',
+                flexDirection: 'column',
+                ...panelFrameScrollSx,
+                ...sx,
+            }, children: children }) }));
+});
+/**
+ * A header that floats ABOVE a PanelFrame (`position: absolute; bottom: calc(100% + gap)`), so its parent must
+ * be `position: relative`. Internal layout is not baked in (callers differ): pass `sx`, layered on top. A plain
+ * `Box`, since `Paper`'s polymorphic `component` typing collides with `Omit<BoxProps, ...>`. Drag wiring and
+ * any grab cursor belong on `Panel`'s `grabProps`, never here.
+ * @public
+ */
+export function PanelHeader({ children, sx, ...rest }) {
+    return (_jsx(Box, { ...rest, sx: {
+            position: 'absolute',
+            bottom: `calc(100% + ${PANEL_HEADER_GAP_PX}px)`,
+            left: 0,
+            right: 0,
+            // Twice the phone's own corner radius, so each end is an exact semicircle; from the theme, never a
+            // raw 48. Fixed, so however the content wraps the pill keeps its shape.
+            height: (theme) => 2 * panelCornerRadiusPx(theme),
+            display: 'flex',
+            alignItems: 'center',
+            // bgcolor + border: MUI Paper variant="outlined"'s look, shaped as a pill.
+            bgcolor: 'background.paper',
+            border: '1px solid',
+            borderColor: 'divider',
+            borderRadius: PANEL_CORNER_RADIUS_UNITS,
+            // 12px, PanelFrame's own content inset, so a header's text lines up with the frame's content below.
+            px: 1.5,
+            fontSize: 13,
+            color: 'common.white',
+            ...sx,
+        }, children: children }));
+}
+/** @public @deprecated use PanelHeader */
+export const PhoneFrameHeader = PanelHeader;
+/** Deliberately narrow (mirrors JSX's own falsy-child rules, not a general emptiness check) so a
+ * real value like `0` or whitespace is never mistaken for "no content". */
+function isEmptyHeaderContent(node) {
+    return node === undefined || node === null || node === false || node === '';
+}
+/** A dimmed "Untitled" reads as "intentionally blank" rather than a loading glitch or missing data. */
+const PLACEHOLDER_TITLE = (_jsx(Box, { component: "span", "data-header-placeholder-title": "", sx: { color: 'text.disabled' }, children: "Untitled" }));
+/** A dimmed "more" glyph reads as "no actions here" rather than a missing icon, and keeps the
+ * row's right edge occupied so the pill's shape never depends on whether any were passed. */
+const PLACEHOLDER_ACTIONS = (_jsx(Box, { "data-header-placeholder-action": "", "aria-hidden": "true", sx: { display: 'flex', alignItems: 'center', color: 'text.disabled' }, children: _jsx(MoreHorizIcon, { fontSize: "small" }) }));
+/**
+ * The title-left/actions-right row shape every PanelHeader caller wants, as one shared layout
+ * instead of each call site reimplementing near-identical flex/ellipsis markup. Placeholder
+ * substitution lives HERE, not in each caller, so every caller gets it for free.
+ * @public
+ */
+export function PanelHeaderRow({ title, actions, sx, ...rest }) {
+    const resolvedTitle = isEmptyHeaderContent(title) ? PLACEHOLDER_TITLE : title;
+    const resolvedActions = isEmptyHeaderContent(actions) ? PLACEHOLDER_ACTIONS : actions;
+    return (_jsxs(PanelHeader, { ...rest, sx: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 1, ...sx }, children: [_jsx(Box, { sx: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', minWidth: 0 }, children: resolvedTitle }), _jsx(Box, { sx: { display: 'flex', alignItems: 'center', gap: 0.25, flexShrink: 0 }, children: resolvedActions })] }));
+}
+/** @public @deprecated use PanelHeaderRow */
+export const PhoneFrameHeaderRow = PanelHeaderRow;
+export default PanelFrame;

package/PanelRow.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One AnimatePresence over ONE array: each PRESENT entry (an always-shown column regardless of `live`, a
+ * collapsible one only while `live`) in its own animated slot, in the array's order. Not a view. Renders ONE
+ * root, this Box.
+ */
+import * as React from 'react';
+import { type NeighborWidths, type PanelRowEntry } from './panelRowEntry.js';
+/** True only for a `collapsible` entry (e.g. a plain web panel): an always-shown column (the root, or a
+ * `permanent:true` custom column) is never a reorder source. Unprovided resolves to false: a view mounted
+ * with no `PanelRow` above it never reorders.
+ * @public */
+export declare const usePanelReorderEligible: () => boolean;
+/** False only for an always-shown column (`collapsible:false`): the built-in 'web' view must never wrap such
+ * an entry in a framework close handle (CreatePanelOptions.permanent's 'own control only' guarantee).
+ * Unprovided resolves to true: a view mounted directly (as tests do) is an ordinary collapsible panel.
+ * @public */
+export declare const usePanelCloseEligible: () => boolean;
+/** The widths this entry's drag can cross (reorderStepsForOffset's input). Unprovided: none, so no hop.
+ * @public */
+export declare const usePanelNeighborWidths: () => NeighborWidths;
+/** Anchored left of the row's root, read from the anchor every render so a drag across the root changes it too. Unprovided: false.
+ * @public */
+export declare const usePanelPinned: () => boolean;
+/**
+ * The row: every present entry in its own animated slot, in the array's order, each rendered by its registered view.
+ * @public
+ */
+export declare function PanelRow({ entries, rootId, closingIds, enteringViaAnchorIds, exitRightIds, enterSideById, maxLiveWidth, }: {
+    /** The raw one-list array (PanelRowEntry, not PanelSummary): `view` alone picks the component (resolveView
+     * never returns nothing), independent of `layer` (stacking) and `anchoredEnter` (enter direction). */
+    entries: readonly PanelRowEntry[];
+    /** The row's root entry: an entry with no anchor orients against it, and `usePanelPinned` means left of it. */
+    rootId: string;
+    /** Ids being closed: each exits DOWN. Kept off PanelsAPI on purpose. */
+    closingIds: ReadonlySet<string>;
+    /** Ids (re)joining `live` by a reveal or an undo: each enters from its anchor's side. Any other entry
+     * enters from the right unless its own `anchoredEnter` says otherwise. */
+    enteringViaAnchorIds: ReadonlySet<string>;
+    /** Ids parking with an exit to the RIGHT; every other park exits LEFT. */
+    exitRightIds?: ReadonlySet<string>;
+    /** An explicit enter side per id, winning over the anchor formula: a scroll gesture knows which side a reveal
+     * must enter from, which the boolean anchor formula cannot express. */
+    enterSideById?: ReadonlyMap<string, 'left' | 'right'>;
+    /** The widest one live panel can be in this row (see computeMaxLiveWidth). Omitted: no cap. */
+    maxLiveWidth?: number;
+}): React.ReactElement;

package/PanelRow.js

@@ -0,0 +1,98 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * One AnimatePresence over ONE array: each PRESENT entry (an always-shown column regardless of `live`, a
+ * collapsible one only while `live`) in its own animated slot, in the array's order. Not a view. Renders ONE
+ * root, this Box.
+ */
+import * as React from 'react';
+import { AnimatePresence } from 'motion/react';
+import Box from '@mui/material/Box';
+import { useHost } from './hostApi.js';
+import { summarisePanel } from './panelRowEntry.js';
+import { anchorTargetOf, resolveEnterDirection } from './panelRowOrder.js';
+import { GAP, PanelRowSlot } from './PanelRowSlot.js';
+import { panelWidthOf } from './panelTiers.js';
+import { resolveView } from './viewRegistry.js';
+import { useViewState } from './viewState.js';
+/** A 'raised' slot sits above a 'base' one: a LEFT-exiting park crosses a raised panel's footprint on the way out (a close exits DOWN and never does). */
+const RAISED_LAYER_Z_INDEX = 2;
+const BASE_LAYER_Z_INDEX = 1;
+const EMPTY_SET = new Set();
+const EMPTY_MAP = new Map();
+const NO_NEIGHBORS = { left: [], right: [] };
+/** The view's summary with `size.width` at the width the row renders it, so a view passing `panel.size` to Panel stays inside its slot. */
+function renderedSummary(p, width) {
+    const summary = summarisePanel(p);
+    return summary.size && summary.size.width !== width && (p.formFactor ?? 'phone') !== 'phone' ? { ...summary, size: { ...summary.size, width } } : summary;
+}
+/**
+ * Per-slot facts a view cannot read itself: it only receives `PanelSummary`, which has no `collapsible` or
+ * `anchor`, on purpose (hostApi.tsx). No provider above (a view mounted directly, as in tests) is `undefined`,
+ * deliberately not `false`: each hook below resolves that case to its OWN default.
+ */
+const PanelSlotContext = React.createContext(undefined);
+/** True only for a `collapsible` entry (e.g. a plain web panel): an always-shown column (the root, or a
+ * `permanent:true` custom column) is never a reorder source. Unprovided resolves to false: a view mounted
+ * with no `PanelRow` above it never reorders.
+ * @public */
+export const usePanelReorderEligible = () => React.useContext(PanelSlotContext)?.collapsible ?? false;
+/** False only for an always-shown column (`collapsible:false`): the built-in 'web' view must never wrap such
+ * an entry in a framework close handle (CreatePanelOptions.permanent's 'own control only' guarantee).
+ * Unprovided resolves to true: a view mounted directly (as tests do) is an ordinary collapsible panel.
+ * @public */
+export const usePanelCloseEligible = () => React.useContext(PanelSlotContext)?.collapsible ?? true;
+/** The widths this entry's drag can cross (reorderStepsForOffset's input). Unprovided: none, so no hop.
+ * @public */
+export const usePanelNeighborWidths = () => React.useContext(PanelSlotContext)?.neighborWidths ?? NO_NEIGHBORS;
+/** Anchored left of the row's root, read from the anchor every render so a drag across the root changes it too. Unprovided: false.
+ * @public */
+export const usePanelPinned = () => React.useContext(PanelSlotContext)?.pinned ?? false;
+/**
+ * The row: every present entry in its own animated slot, in the array's order, each rendered by its registered view.
+ * @public
+ */
+export function PanelRow({ entries, rootId, closingIds, enteringViaAnchorIds, exitRightIds = EMPTY_SET, enterSideById = EMPTY_MAP, maxLiveWidth = Number.POSITIVE_INFINITY, }) {
+    const { device, panels } = useHost();
+    const phoneWidth = device.size.width;
+    const phoneHeight = device.size.height;
+    // Ids never repeat, so a panel in neither list can never be shown again and its view state is released.
+    useViewState.useRetainOnly([...entries, ...(panels.recentlyClosed ?? [])].map((p) => p.id));
+    const present = entries.filter((p) => !p.collapsible || p.live);
+    // Every present entry's OWN width, in row order. An always-shown column needs no special case: setFormFactor
+    // no-ops on a collapsible:false id, so panelWidthOf gives it `phoneWidth`.
+    const widths = present.map((p) => panelWidthOf(p, phoneWidth, maxLiveWidth));
+    // Each slot's rest x: every PRECEDING item's own width plus one gap, so a wider item pushes the rest right.
+    const leftOffsets = [];
+    let runningOffset = 0;
+    for (const width of widths) {
+        leftOffsets.push(runningOffset);
+        runningOffset += width + GAP;
+    }
+    const reservedWidth = Math.max(0, widths.reduce((sum, width) => sum + width + GAP, 0) - GAP);
+    // Nearest first on each side, an always-shown column included: movePanel swaps past one like any neighbour.
+    const neighborWidthsAt = (index) => {
+        const side = (step) => {
+            const out = [];
+            for (let i = index + step; i >= 0 && i < present.length; i += step)
+                out.push(widths[i]);
+            return out;
+        };
+        return { left: side(-1), right: side(1) };
+    };
+    // Per panel, and searched in `present`: each slot's own `index` below counts in that same array.
+    const anchorIndexOf = (p) => present.findIndex((x) => x.id === anchorTargetOf(p, rootId));
+    return (
+    // Always mounted: an exiting entry needs AnimatePresence to animate inside, and `initial={false}` must see
+    // what is present at app start to skip animating a restored session. `display: none` (not width 0) so an
+    // empty row consumes no flex `gap` from its siblings.
+    _jsx(Box, { sx: {
+            position: 'relative',
+            flexShrink: 0,
+            height: phoneHeight,
+            display: present.length > 0 ? 'block' : 'none',
+            width: reservedWidth,
+        }, children: _jsx(AnimatePresence, { initial: false, children: present.map((p, index) => {
+                const Component = resolveView(p.view);
+                return (_jsx(PanelSlotContext.Provider, { value: { collapsible: p.collapsible, neighborWidths: neighborWidthsAt(index), pinned: anchorTargetOf(p, rootId) === rootId && p.anchor?.position === 'left' }, children: _jsx(PanelRowSlot, { leftOffset: leftOffsets[index], width: widths[index], phoneHeight: phoneHeight, enterDirection: enterSideById.get(p.id) ?? ((p.anchoredEnter ?? false) || enteringViaAnchorIds.has(p.id) ? resolveEnterDirection(anchorIndexOf(p), index) : 'right'), exitDirection: closingIds.has(p.id) ? 'down' : exitRightIds.has(p.id) ? 'right' : 'left', zIndex: (p.layer ?? 'base') === 'raised' ? RAISED_LAYER_Z_INDEX : BASE_LAYER_Z_INDEX, children: _jsx(useViewState.Provider, { value: p.id, children: _jsx(Component, { panel: renderedSummary(p, widths[index]) }) }) }) }, p.id));
+            }) }) }));
+}