duet-ui 0.0.0-stage → 0.1.0

package/dist/chrome.js

@@ -0,0 +1,494 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { ArrowLeftRight, ChevronLeft, Ellipsis, Search, X } from "./icons.js";
+import { DUO, INLINE_WIDTH, ISLAND, MORPH, isSplit, magnet, plan, stable } from "./geometry.js";
+import { GlassProvider } from "./glassyui/glass-provider.js";
+import { GlassSurface } from "./glassyui/glass-surface.js";
+import "./duet.css";
+// --- context ------------------------------------------------------------------------------------
+// A desktop page that draws a Duo around this page in an iframe (the site's web Duo) sends the signals the
+// real device would give: `postMessage({ type: "duet:signals", signals }, origin)`. Same origin only. The page
+// says `duet:ready` once it listens, so the host answers then instead of guessing when the page has loaded.
+let emulated = null;
+if (typeof window !== "undefined" && window.top !== window) {
+    addEventListener("message", (e) => {
+        if (e.source !== parent || e.origin !== location.origin || e.data?.type !== "duet:signals")
+            return;
+        emulated = e.data.signals;
+        listeners.forEach((f) => f());
+    });
+    parent.postMessage({ type: "duet:ready" }, location.origin);
+}
+/** The safe-area inset on one side as CSS: the real env() value, or the emulated one. */
+const envInset = (side) => emulated ? `${side === "right" ? emulated.insetRight : emulated.insetLeft}px` : `env(safe-area-inset-${side})`;
+let probe = null;
+function signals() {
+    if (emulated)
+        return emulated;
+    if (!probe) {
+        probe = document.createElement("div");
+        probe.style.cssText = "position:fixed;visibility:hidden;pointer-events:none;"
+            + "padding:env(safe-area-inset-top) env(safe-area-inset-right) env(safe-area-inset-bottom) env(safe-area-inset-left)";
+        document.body.appendChild(probe);
+    }
+    const pad = getComputedStyle(probe);
+    return {
+        innerWidth: innerWidth,
+        innerHeight: innerHeight,
+        outerWidth: outerWidth,
+        outerHeight: outerHeight,
+        visualHeight: visualViewport?.height ?? innerHeight,
+        insetTop: parseFloat(pad.paddingTop) || 0,
+        insetBottom: parseFloat(pad.paddingBottom) || 0,
+        screenWidth: innerWidth > innerHeight ? Math.max(screen.width, screen.height) : Math.min(screen.width, screen.height),
+        screenHeight: innerWidth > innerHeight ? Math.min(screen.width, screen.height) : Math.max(screen.width, screen.height),
+        insetRight: parseFloat(pad.paddingRight) || 0,
+        insetLeft: parseFloat(pad.paddingLeft) || 0,
+        framed: window.top !== window,
+        pixelRatio: devicePixelRatio,
+        standalone: navigator.standalone === true || matchMedia("(display-mode: standalone)").matches,
+    };
+}
+// Inline: the side is the user's, remembered per site, and apart for split view (Safari's column is on the pane's
+// outer edge, which the page cannot see, so the controls follow it once moved there).
+const sideKey = (split) => split ? "duet-side-split" : "duet-side";
+const preferred = new Map();
+const listeners = new Set();
+/** undefined until the user moves the controls: then detect() picks the side for the context. */
+function preferredSide(split) {
+    const key = sideKey(split);
+    if (!preferred.has(key)) {
+        try {
+            const v = localStorage.getItem(key);
+            preferred.set(key, v === "left" || v === "right" ? v : null);
+        }
+        catch {
+            preferred.set(key, null);
+        }
+    }
+    return preferred.get(key) ?? undefined;
+}
+function setPreferredSide(side) {
+    const key = sideKey(!!snap?.split);
+    preferred.set(key, side);
+    try {
+        localStorage.setItem(key, side);
+    }
+    catch { }
+    listeners.forEach((f) => f());
+}
+/** Moves the inline controls to `side` in one frame: data-drag="switch" holds every transition off until the
+ *  new layout has painted (CSS), so no control glides across the page on its own. */
+function switchSide(el, side) {
+    el.dataset.drag = "switch";
+    setPreferredSide(side);
+    requestAnimationFrame(() => requestAnimationFrame(() => { if (el.dataset.drag === "switch")
+        delete el.dataset.drag; }));
+}
+let snap = null, snapKey = "";
+const damper = { flips: [] };
+let pinTimer;
+function read() {
+    const s = signals(), c = stable(damper, s, preferredSide(isSplit(s)), performance.now());
+    // A pin lifts on its own time, with no resize to re-read on.
+    if (damper.pinned && !pinTimer)
+        pinTimer = setTimeout(() => { pinTimer = undefined; listeners.forEach((f) => f()); }, damper.until - performance.now() + 20);
+    const k = JSON.stringify(c);
+    if (k !== snapKey)
+        [snapKey, snap] = [k, c];
+    return snap;
+}
+function subscribe(cb) {
+    // Safe-area insets and outerWidth settle up to ~400ms after resize and rotation.
+    const on = () => { cb(); setTimeout(cb, 300); setTimeout(cb, 600); };
+    addEventListener("resize", on);
+    addEventListener("orientationchange", on);
+    visualViewport?.addEventListener("resize", on);
+    // A fresh Safari tab can hydrate before its window geometry settles, with no resize afterwards.
+    const t = [0, 300, 1000].map((ms) => setTimeout(cb, ms));
+    listeners.add(cb);
+    return () => {
+        listeners.delete(cb);
+        t.forEach(clearTimeout);
+        removeEventListener("resize", on);
+        removeEventListener("orientationchange", on);
+        visualViewport?.removeEventListener("resize", on);
+    };
+}
+const ssr = { mode: "column", duo: true, layout: "narrow", side: "right", width: 382, height: 580, offsetTop: 0, screenWidth: 466, screenHeight: 678, insetTop: 0, insetBottom: 0 };
+export function useDuet() {
+    return useSyncExternalStore(subscribe, read, () => ssr);
+}
+function useMinimized(on, scroller) {
+    const [min, setMin] = useState(false);
+    useEffect(() => {
+        if (!on)
+            return;
+        // Captured, so a scroll inside the page (a pane of <DuetPanes>) counts as well as the scroller's own; each
+        // scrolling element keeps its own last position.
+        const target = scroller.current ?? window, last = new WeakMap();
+        const f = (e) => {
+            const el = e.target instanceof Element ? e.target : null, y = el ? el.scrollTop : scrollY, key = el ?? window;
+            const d = y - (last.get(key) ?? 0);
+            if (Math.abs(d) > 8) {
+                setMin(d > 0 && y > 40);
+                last.set(key, y);
+            }
+        };
+        target.addEventListener("scroll", f, { passive: true, capture: true });
+        return () => target.removeEventListener("scroll", f, { capture: true });
+    }, [on, scroller]);
+    return on && min;
+}
+/** Safari tab: fixed content is clipped to the page viewport (so is sticky), but in-document content paints
+ *  into Safari's column. So the chrome is an absolute layer at the document top, and the inner scroller keeps
+ *  the document itself from scrolling, so the layer never moves. A scroll-driven transform lags momentum
+ *  scrolling and drifts (issue #1); `follow` only covers pages without the scroller. Touches there reach the page
+ *  but are not hit-tested to our elements, and Safari keeps the touch end (no pointerup, no click), so we route
+ *  them by coordinates on pointerdown. Nothing in the column scrolls, so a touch there is always a tap.
+ *  Split pane: the column is on the pane's outer edge, which the page cannot see, so the document spans a column
+ *  on each side, scrolled 84 across, and the controls are drawn in both (refs[0] left, refs[1] right). Each pane
+ *  shows only its own column, and a tap there names the side (`tapSide`). */
+let tapSide = "right";
+/** Without shrink-to-fit=no Safari zooms a split pane out to fit the layer's overflow, which reads as another
+ *  window size and flips the mode. It applies even when set late, but must land before the first column paint. */
+function noShrink() {
+    const meta = document.querySelector("meta[name=viewport]");
+    if (meta && !/shrink-to-fit/.test(meta.content))
+        meta.content += ",shrink-to-fit=no";
+}
+if (typeof document !== "undefined")
+    noShrink();
+function useColumnLayer(on, split, column) {
+    const refs = [useRef(null), useRef(null)];
+    useEffect(() => {
+        const els = refs.map((r) => r.current).filter((el) => !!el);
+        if (!on || !els.length)
+            return;
+        const html = document.documentElement.style, prev = html.touchAction;
+        html.touchAction = "pan-y"; // the layer widens the document; keep the page from panning sideways
+        const follow = () => {
+            if (split && Math.round(scrollX) !== column)
+                scrollTo(column, scrollY);
+            for (const el of els)
+                el.style.transform = scrollY ? `translateY(${scrollY}px)` : "";
+        };
+        const tap = (e) => {
+            if (e.clientX >= 0 && e.clientX < innerWidth)
+                return; // inside the viewport, normal hit-testing applies
+            const el = split ? refs[e.clientX < 0 ? 0 : 1].current : refs[0].current;
+            if (split)
+                tapSide = e.clientX < 0 ? "left" : "right";
+            // Skip a button that became an open menu: the menu covers it, and its own slot sits on top.
+            for (const b of el?.querySelectorAll(":not([data-unrolled]) > button") ?? []) {
+                const r = b.getBoundingClientRect();
+                if (e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom) {
+                    b.click();
+                    return;
+                }
+            }
+        };
+        follow();
+        // Safari restores or resets the sideways scroll on load and resize.
+        const t = [0, 300, 1000].map((ms) => setTimeout(follow, ms));
+        addEventListener("scroll", follow, { passive: true });
+        addEventListener("resize", follow);
+        addEventListener("pointerdown", tap);
+        return () => {
+            html.touchAction = prev;
+            for (const el of els)
+                el.style.transform = "";
+            t.forEach(clearTimeout);
+            removeEventListener("scroll", follow);
+            removeEventListener("resize", follow);
+            removeEventListener("pointerdown", tap);
+        };
+    }, [on, split, column]); // eslint-disable-line react-hooks/exhaustive-deps -- refs are stable
+    return refs;
+}
+/** Inline: drag any control across the middle of the page to move the strip to that side. The controls
+ *  follow the finger (--duet-drag); a drag never becomes a tap. */
+function useSideDrag(side, nav, onStart) {
+    useEffect(() => {
+        const el = nav.current;
+        if (!side || !el)
+            return;
+        let x0 = null, y0 = 0, dragging = false, free = false;
+        const down = (e) => { if (e.target.closest(".duet-glass:not(.duet-menu)")) {
+            x0 = e.clientX;
+            y0 = e.clientY;
+            dragging = false;
+        } };
+        const move = (e) => {
+            if (x0 === null)
+                return;
+            // Only a deliberate sideways swipe picks the strip up: a scrub along the rail, or a wobbly tap, never does.
+            const dx = Math.abs(e.clientX - x0), dy = Math.abs(e.clientY - y0);
+            if (!dragging && dy > 12 && dy > dx) {
+                x0 = null;
+                return;
+            }
+            if (!dragging && dx > 24 && dx > 2 * dy) {
+                dragging = true;
+                onStart();
+            }
+            if (!dragging)
+                return;
+            const m = magnet(side, e.clientX - x0);
+            if (m.free !== free) {
+                free = m.free;
+                el.dataset.drag = free ? "free" : "held";
+            }
+            el.style.setProperty("--duet-drag", `${m.offset}px`);
+        };
+        const up = (e) => {
+            if (x0 === null)
+                return;
+            x0 = null;
+            const to = e.clientX < innerWidth / 2 ? "left" : "right";
+            const flip = dragging && free && to !== side;
+            if (flip)
+                el.dataset.drag = "switch";
+            else
+                delete el.dataset.drag;
+            el.style.removeProperty("--duet-drag");
+            if (flip)
+                switchSide(el, to);
+            free = false;
+        };
+        const click = (e) => { if (dragging) {
+            e.stopPropagation();
+            e.preventDefault();
+            dragging = false;
+        } };
+        el.addEventListener("pointerdown", down);
+        addEventListener("pointermove", move);
+        addEventListener("pointerup", up);
+        addEventListener("pointercancel", up);
+        el.addEventListener("click", click, true);
+        return () => {
+            el.removeEventListener("pointerdown", down);
+            removeEventListener("pointermove", move);
+            removeEventListener("pointerup", up);
+            removeEventListener("pointercancel", up);
+            el.removeEventListener("click", click, true);
+        };
+    }, [side, nav]); // eslint-disable-line react-hooks/exhaustive-deps -- onStart only resets menu and scrub state
+}
+// --- rendering ----------------------------------------------------------------------------------
+export function Duet(p) {
+    const ctx = useDuet();
+    const scroller = useRef(null);
+    const minimized = useMinimized(!!p.minimizeOnScroll, scroller);
+    const [menu, setMenuNow] = useState(null);
+    // The menu that is rolling back into its button; it stays mounted until its animation ends.
+    const [closing, setClosing] = useState(null);
+    // Index of the tab under the finger while scrubbing the full pill, like Apple News' tab bar.
+    const [scrub, setScrub] = useState(null);
+    // A touch on the full pill is a tap until it is held or dragged; only then does the pill swell into a scrub.
+    const press = useRef(null);
+    // A tap glides the lens to the new tab as a clear magnifier, without swelling the pill, like Apple News.
+    const [glide, setGlide] = useState(false);
+    const glideTimer = useRef(0);
+    useEffect(() => () => { clearTimeout(glideTimer.current); if (press.current)
+        clearTimeout(press.current.timer); }, []);
+    const setMenu = (n) => {
+        if (menu && menu !== n)
+            setClosing(matchMedia("(prefers-reduced-motion: reduce)").matches ? null : menu);
+        if (n && closing === n)
+            setClosing(null);
+        setMenuNow(n);
+    };
+    const actions = (p.actions ?? []).filter((a) => !a.destructive), destructive = (p.actions ?? []).filter((a) => a.destructive);
+    const leading = p.leading ?? [];
+    const tabItems = p.tabs ? [...p.tabs.items, ...(p.tabs.search ? [p.tabs.search] : [])] : [];
+    const spec = p.close
+        ? { back: true, leading: 0, actions: 0, tabs: 0, searchButton: false, accessory: false, minimized, menuExtra: 0 }
+        : {
+            back: !!p.back, leading: leading.length, actions: actions.length, tabs: tabItems.length,
+            searchButton: !p.tabs && !!p.searchButton, accessory: !!p.accessory, minimized,
+            menuExtra: (ctx.mode === "inline" ? 1 : 0) + destructive.length, primary: !!p.primary,
+        };
+    // Split pane in column mode: the controls are drawn in both of Safari's possible columns (useColumnLayer).
+    const split = ctx.mode === "column" && !!ctx.split, column = ctx.screenWidth - ctx.width;
+    const sides = split ? ["left", "right"] : [ctx.side];
+    const planFor = (side) => plan(side === ctx.side ? ctx : { ...ctx, side }, spec);
+    // The copy whose column opened the menu draws it; the other copy's column is in the other pane.
+    const [menuSide, setMenuSide] = useState(ctx.side);
+    useEffect(() => {
+        // The page spans the window and the controls float over it; these insets are how far text and buttons keep
+        // clear on each edge (layout.ts). In Safari's column the scroller runs on under the column (an emulated
+        // column's frame already spans it), so either way the inset there is the column's width.
+        const r = document.documentElement.style;
+        const inset = ctx.mode === "strip" ? envInset(ctx.side) : ctx.mode === "inline" ? `${INLINE_WIDTH}px` : `${ctx.screenWidth - ctx.width}px`;
+        const right = ctx.side === "right" || split ? inset : envInset("right"), left = ctx.side === "left" || split ? inset : envInset("left");
+        // --duet-edge-*: the window's insets, kept for panes, which set --duet-inset-* to their own.
+        for (const [k, v] of [["right", right], ["left", left]]) {
+            r.setProperty(`--duet-inset-${k}`, v);
+            r.setProperty(`--duet-edge-${k}`, v);
+        }
+        // iOS blurs the top of a Home Screen web app (scroll-edge effect) without reporting a safe-area
+        // inset, closed and unfolded; pages pad their top content by this much to stay sharp.
+        r.setProperty("--duet-inset-top", ctx.mode === "strip" ? `${DUO.edgeBlur}px` : "0px");
+        document.documentElement.dataset.duetMode = ctx.mode;
+        document.documentElement.toggleAttribute("data-duet-emulated", !!emulated);
+        document.documentElement.toggleAttribute("data-duet-split", split);
+    }, [ctx.mode, ctx.side, ctx.screenWidth, ctx.width, split]);
+    const [nav, nav2] = useColumnLayer(ctx.mode === "column", split, column);
+    useEffect(() => {
+        // Any touch outside the chrome closes an open menu, like a native context menu.
+        if (!menu)
+            return;
+        const close = (e) => {
+            if (![nav, nav2].some((n) => n.current?.contains(e.target)) && e.clientX >= 0 && e.clientX < innerWidth)
+                setMenu(null);
+        };
+        addEventListener("pointerdown", close);
+        return () => removeEventListener("pointerdown", close);
+    }, [menu, nav, nav2]); // eslint-disable-line react-hooks/exhaustive-deps -- setMenu only reads menu
+    useSideDrag(ctx.mode === "inline" ? ctx.side : null, nav, () => { setMenu(null); setScrub(null); });
+    const selected = p.tabs?.selected;
+    const badge = (a) => a.badge !== undefined && a.badge !== "" && _jsx("span", { className: "duet-badge", children: a.badge });
+    const tint = (a) => a.tint ? { "--duet-tint": a.tint } : undefined;
+    const item = (a) => _jsxs("button", { className: "duet-item", "aria-label": a.label, onClick: a.onPress, children: [a.icon, badge(a)] }, a.id);
+    const toggle = (m) => () => { if (split)
+        setMenuSide(tapSide); setMenu(menu === m ? null : m); };
+    const backButton = p.back && _jsx("button", { className: "duet-item", "aria-label": p.back.label ?? "Back", onClick: p.back.onPress, children: _jsx(ChevronLeft, { size: 24, strokeWidth: 2.2 }) });
+    const moreButton = _jsx("button", { className: "duet-item", "aria-label": "More", "aria-expanded": menu === "more", onClick: toggle("more"), children: _jsx(Ellipsis, { size: 22 }) });
+    const searchButton = _jsx("button", { className: "duet-item", "aria-label": "Search", onClick: p.searchButton, children: _jsx(Search, { size: 22 }) });
+    // Minimized, the selected tab opens the full list, like tapping a minimized native tab bar. In the full
+    // pill a touch selects on release (scrub below); clicks still select for keyboards and routed column taps.
+    const tabButton = (t, min, i) => (_jsxs("button", { role: "tab", "aria-selected": t.id === selected, "aria-label": t.label, className: "duet-tab", "data-on": (scrub === null ? t.id === selected : scrub === i) || undefined, "data-tint": t.tint ? "" : undefined, style: { ...tint(t), "--j": i }, onClick: (e) => { if (min)
+            toggle("tabs")();
+        else if (scrub === null && e.detail === 0)
+            glideTo(t.id); }, children: [t.icon, min && badge(t)] }, t.id));
+    // The lens keeps its glass while it travels or settles, then melts back into the selection.
+    const settle = () => {
+        setGlide(true);
+        clearTimeout(glideTimer.current);
+        glideTimer.current = window.setTimeout(() => setGlide(false), 420);
+    };
+    const glideTo = (id) => {
+        if (id !== selected)
+            settle();
+        p.tabs.onSelect(id);
+    };
+    // Scrub: holding or dragging on the full pill swells it and shows labels; a lens follows the finger over the
+    // tabs and the tab under it lights up; lifting selects it. A quick tap just glides the lens to the tab.
+    // Pointer capture keeps the drag even off the pill.
+    const HOLD_MS = 250, SLOP = 8, SWELL = { x: 16, y: 12 };
+    const endPress = () => { if (press.current)
+        clearTimeout(press.current.timer); press.current = null; };
+    const tabAt = (pill, y) => {
+        const tabs = [...pill.querySelectorAll(":scope > .duet-tab")];
+        let best = 0;
+        tabs.forEach((b, i) => { const r = b.getBoundingClientRect(); if (y >= r.top)
+            best = i; });
+        return best;
+    };
+    const scrubbing = {
+        onPointerDown: (e) => {
+            if (e.button)
+                return;
+            const pill = e.currentTarget;
+            pill.setPointerCapture(e.pointerId);
+            endPress();
+            const timer = window.setTimeout(() => { if (press.current)
+                setScrub(tabAt(pill, press.current.y)); }, HOLD_MS);
+            press.current = { y0: e.clientY, y: e.clientY, timer };
+        },
+        onPointerMove: (e) => {
+            if (press.current)
+                press.current.y = e.clientY;
+            if (scrub !== null)
+                setScrub(tabAt(e.currentTarget, e.clientY));
+            else if (press.current && Math.abs(e.clientY - press.current.y0) > SLOP) {
+                clearTimeout(press.current.timer);
+                setScrub(tabAt(e.currentTarget, e.clientY));
+            }
+        },
+        onPointerUp: (e) => {
+            const tapped = press.current && scrub === null;
+            endPress();
+            if (scrub !== null) {
+                const t = tabItems[scrub];
+                setScrub(null);
+                settle();
+                if (t)
+                    p.tabs.onSelect(t.id);
+            }
+            else if (tapped) {
+                const t = tabItems[tabAt(e.currentTarget, e.clientY)];
+                if (t)
+                    glideTo(t.id);
+            }
+        },
+        onPointerCancel: () => { endPress(); setScrub(null); },
+    };
+    // Held, the rail grows for real (wider towards the page, taller upwards), not just scaled, so the labels
+    // have room and clear its round ends, as Apple News and Music do.
+    const swell = (b, on, side) => !on ? b
+        : { ...b, top: b.top - SWELL.y, height: b.height + SWELL.y, width: b.width + SWELL.x, left: side === "right" ? b.left - SWELL.x : b.left };
+    const lensAt = scrub ?? Math.max(0, tabItems.findIndex((t) => t.id === selected));
+    // Menus only unroll from separate round buttons: "…" and the minimized tab.
+    const anchors = (pl) => ({ more: pl.more, tabs: pl.tabs?.min ? pl.tabs : undefined });
+    // A menu whose button went away mid-roll (a tab change scrolls to the top and un-minimizes the tab bar)
+    // never fires its animationend; drop it, or its button stays hidden as "unrolled".
+    const gone = anchors(planFor(split ? menuSide : ctx.side));
+    const closingGone = (closing === "tabs" && !gone.tabs) || (closing === "more" && !gone.more);
+    useEffect(() => { if (closingGone)
+        setClosing(null); }, [closingGone]);
+    // Island: icons only; the "…" island ends in a close slot where the "…" was, so the button reads as unrolled.
+    // Morph: icon and label rows; a touch outside closes it, so it needs no close row.
+    const morph = p.menuStyle === "morph";
+    const menuEl = (kind, anchor, items, radio, menuAt, morphAt) => {
+        if ((menu !== kind && closing !== kind) || !anchor)
+            return null;
+        const close = kind === "more" && !morph, rolling = menu !== kind;
+        return (_jsxs(GlassSurface, { preset: "control", className: "duet-glass duet-menu", role: "menu", "data-style": morph ? "morph" : undefined, style: morph ? morphAt(anchor, items.length) : menuAt(anchor, items.length + (close ? 1 : 0)), "data-closing": rolling || undefined, onAnimationEnd: (e) => { if (rolling && (e.animationName === "duet-roll" || e.animationName === "duet-unmorph"))
+                setClosing(null); }, children: [items.map((a, i) => (_jsxs("button", { role: radio ? "menuitemradio" : "menuitem", "aria-checked": radio ? a.id === selected : undefined, "aria-label": a.label, className: "duet-menu-item", "data-on": (radio && a.id === selected) || undefined, "data-destructive": a.destructive || undefined, "data-sep": (a.destructive && i > 0 && !items[i - 1].destructive) || undefined, "data-tint": a.tint ? "" : undefined, style: { ...tint(a), ...(rolling ? undefined : { animationDelay: `${morph ? 0.12 + 0.04 * i : 0.14 + 0.06 * (items.length - i)}s` }) }, onClick: () => { setMenu(null); if (radio)
+                        p.tabs.onSelect(a.id);
+                    else
+                        a.onPress?.(); }, children: [a.icon, morph && _jsx("span", { className: "duet-menu-label", children: a.label }), badge(a)] }, a.id))), close && _jsx("button", { className: "duet-menu-item", "aria-label": "Close", onClick: () => setMenu(null), children: _jsx(X, { size: 20 }) })] }));
+    };
+    const bar = (side, i) => {
+        const pl = planFor(side), left = side === "left", anchor = anchors(pl);
+        const at = (b) => ({ top: b.top, left: pl.left, width: DUO.control, height: b.height });
+        // A menu is the button that opens it unrolling sideways, like the Dynamic Island: a pill of icon slots
+        // as tall as the button, outer edge on the button's, widening towards the page centre only.
+        const menuAt = (b, n) => {
+            const w = 2 * ISLAND.pad + n * ISLAND.item;
+            return { top: b.top + b.height / 2 - DUO.control / 2, left: left ? pl.left : pl.left + DUO.control - w, width: w, height: DUO.control, "--x0": `${pl.left}px` };
+        };
+        // Morph: the button grows into a labelled list, outer edge on the button's, top on its top; opening upwards
+        // instead when the list would run off the bottom of the screen.
+        const morphAt = (b, n) => {
+            const w = MORPH.width, h = 2 * MORPH.pad + n * MORPH.row, y0 = b.top + b.height / 2 - DUO.control / 2;
+            const top = y0 + h > ctx.height - MORPH.pad ? Math.max(MORPH.pad, y0 + DUO.control - h) : y0;
+            return { top, left: left ? pl.left : pl.left + DUO.control - w, width: w, height: h, "--x0": `${pl.left}px`, "--y0": `${y0}px` };
+        };
+        const shownLeading = leading.slice(0, leading.length - pl.menu.leading);
+        const shownActions = actions.slice(0, actions.length - pl.menu.actions);
+        const more = [
+            ...(pl.menu.primary && p.primary ? [p.primary] : []),
+            ...(pl.menu.back && p.back ? [{ id: "duet-back", label: p.back.label ?? "Back", icon: _jsx(ChevronLeft, { size: 20 }), onPress: p.back.onPress }] : []),
+            ...leading.slice(shownLeading.length), ...actions.slice(shownActions.length),
+            ...(ctx.mode === "inline" ? [{ id: "duet-side", label: `Move controls ${left ? "right" : "left"}`, icon: _jsx(ArrowLeftRight, { size: 20 }), onPress: () => {
+                        // The menu goes at once, without rolling back into "…": its button is about to move, and would stay hidden
+                        // as "unrolled" until a roll that no longer lines up with it.
+                        setMenuNow(null);
+                        setClosing(null);
+                        setScrub(null);
+                        if (nav.current)
+                            switchSide(nav.current, left ? "right" : "left");
+                    } }] : []),
+            ...destructive,
+        ];
+        return (_jsxs("nav", { ref: i ? nav2 : nav, className: "duet", "data-mode": ctx.mode, "data-side": side, style: split && i ? { left: column } : undefined, children: [p.close && pl.back && (_jsx(GlassSurface, { preset: "control", className: "duet-glass duet-round duet-close", "data-duet-slot": "close", style: at(pl.back), children: _jsx("button", { className: "duet-item", "aria-label": p.close.label ?? "Close", onClick: p.close.onPress, children: _jsx(X, { size: 22, strokeWidth: 2.2 }) }) })), !p.close && p.back && pl.back && _jsx(GlassSurface, { preset: "control", className: "duet-glass duet-round", "data-duet-slot": "back", style: at(pl.back), children: backButton }), !p.close && p.primary && pl.primary && (_jsx(GlassSurface, { preset: "control", className: "duet-glass duet-round duet-primary", "data-duet-slot": "primary", style: { ...at(pl.primary), ...tint(p.primary) }, children: item(p.primary) })), pl.leading && _jsx(GlassSurface, { preset: "control", className: "duet-glass duet-group", "data-duet-slot": "leading", style: at(pl.leading), children: shownLeading.map(item) }), pl.actions && _jsx(GlassSurface, { preset: "control", className: "duet-glass duet-group", "data-duet-slot": "actions", style: at(pl.actions), children: shownActions.map(item) }), !p.close && pl.more && more.length > 0 && _jsx(GlassSurface, { preset: "control", className: "duet-glass duet-round", "data-duet-slot": "more", style: at(pl.more), "data-unrolled": menu === "more" || closing === "more" || undefined, children: moreButton }), p.tabs && pl.tabs && (_jsxs(GlassSurface, { preset: "control", className: "duet-glass duet-pill", "data-duet-slot": "tabs", role: "tablist", style: { ...swell(at(pl.tabs), scrub !== null && !pl.tabs.min, side), "--li": lensAt }, "data-min": pl.tabs.min || undefined, "data-scrub": scrub !== null || undefined, "data-glide": (glide && scrub === null) || undefined, "data-unrolled": menu === "tabs" || closing === "tabs" || undefined, ...(pl.tabs.min ? {} : scrubbing), children: [!pl.tabs.min && (
+                        // The lens magnifies a copy of the tab column, slid so it lines up with the real one; the real tabs
+                        // are masked out under the lens (CSS), so only the enlarged copy shows through it.
+                        _jsx("span", { className: "duet-lens", "aria-hidden": true, children: _jsx("span", { className: "duet-lens-view", children: _jsx("span", { className: "duet-lens-col", children: tabItems.map((t, i) => _jsx("span", { className: "duet-tab", "data-on": i === lensAt || undefined, style: tint(t), children: t.icon }, t.id)) }) }) })), !pl.tabs.min && _jsx("span", { className: "duet-pill-badges", "aria-hidden": true, children: tabItems.map((t) => _jsx("span", { children: badge(t) }, t.id)) }), pl.tabs.min ? tabItems.filter((t) => t.id === selected).map((t) => tabButton(t, true, 0)) : tabItems.map((t, i) => tabButton(t, false, i))] })), pl.searchButton && _jsx(GlassSurface, { preset: "control", className: "duet-glass duet-round", "data-duet-slot": "search", style: at(pl.searchButton), children: searchButton }), (!split || side === menuSide) && menuEl("more", anchor.more, more, false, menuAt, morphAt), p.tabs && (!split || side === menuSide) && menuEl("tabs", anchor.tabs, tabItems, true, menuAt, morphAt), p.accessory && pl.accessory && !i && (_jsx(GlassSurface, { preset: "control", className: "duet-glass duet-accessory", "data-duet-slot": "accessory", style: pl.accessory, "data-covered": menu === "tabs" || undefined, children: p.accessory }))] }, side));
+    };
+    return (_jsxs(GlassProvider, { defaultTheme: p.dark === undefined ? undefined : p.dark ? "dark" : "light", children: [p.children !== undefined && _jsx("div", { ref: scroller, className: "duet-scroller", children: p.children }), sides.map(bar)] }));
+}

package/dist/duet-panes.d.ts

@@ -0,0 +1,45 @@
+import { type ReactNode } from "react";
+import { type DuetItem } from "./chrome.tsx";
+export interface DuetPanesProps {
+    /** The path of screens, shallowest first, e.g. ["mailboxes", "inbox", "message"]. */
+    path: string[];
+    /** The focused pane. Narrow shows it alone; wide shows it with the pane before it. */
+    at: string;
+    /** The focused pane takes the whole window (the pane bar's full-screen toggle). */
+    expanded?: boolean;
+    /** Each pane's content by id. Every pane stays mounted, so its state and scroll survive folding and
+     *  navigation; panes off screen are inert. */
+    panes: Record<string, ReactNode>;
+}
+/** A path of screens that follows the fold: one pane closed or in split view, two adjacent panes unfolded.
+ *  Going deeper slides along the path; unfolding slides the neighbouring pane in, folding plays it backwards.
+ *  Each pane gets its own --duet-inset-left/right: only a pane on the controls' edge keeps clear of them, so
+ *  column() and bleed() inside a pane work as they do on a whole page. */
+export declare function DuetPanes({ path, at, expanded, panes }: DuetPanesProps): import("react").JSX.Element;
+/** Navigation state for <DuetPanes>: `go` focuses a pane, `back` is ready for <Duet back>: it leaves full
+ *  screen first, then steps back along the path, and is false when that would change nothing on screen.
+ *  `expanded`/`toggle` drive the full-screen toggle and `close` closes the focused pane (back to the pair
+ *  before it), both ready for <DuetPaneBar>. */
+export declare function usePanes(path: string[], initial?: string): {
+    readonly at: string;
+    readonly go: (id: string) => void;
+    readonly layout: import("./geometry.ts").Layout;
+    readonly expanded: boolean;
+    readonly toggle: () => void;
+    readonly close: (() => void) | undefined;
+    readonly back: false | {
+        onPress: () => void;
+    };
+};
+export interface DuetPaneBarProps {
+    /** Close the pane, e.g. usePanes().close. Omitted: no close button. */
+    onClose?: () => void;
+    /** Full-screen toggle, e.g. usePanes().toggle. Shown only where two panes fit. */
+    onToggle?: () => void;
+    expanded?: boolean;
+    /** Items for the "…" menu. Destructive ones go last, in red, after a separator. */
+    more?: DuetItem[];
+}
+/** The pane's own controls, a small pill at its top right: close, full screen, and "…". It sticks to the top of
+ *  the pane as it scrolls, and keeps clear of the strip when the pane is on the controls' edge. */
+export declare function DuetPaneBar({ onClose, onToggle, expanded, more }: DuetPaneBarProps): import("react").JSX.Element | null;

package/dist/duet-panes.js

@@ -0,0 +1,62 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { useDuet } from "./chrome.js";
+import { Ellipsis, Maximize, Minimize, X } from "./icons.js";
+import { backFrom, panes as paneWindow } from "./panes.js";
+/** A path of screens that follows the fold: one pane closed or in split view, two adjacent panes unfolded.
+ *  Going deeper slides along the path; unfolding slides the neighbouring pane in, folding plays it backwards.
+ *  Each pane gets its own --duet-inset-left/right: only a pane on the controls' edge keeps clear of them, so
+ *  column() and bleed() inside a pane work as they do on a whole page. */
+export function DuetPanes({ path, at, expanded = false, panes }) {
+    const { layout } = useDuet();
+    const w = paneWindow(path, at, layout, expanded);
+    const last = w.start + w.count - 1;
+    return (_jsx("div", { className: "duet-panes", "data-layout": layout, children: _jsx("div", { className: "duet-panes-track", style: { "--start": w.start, "--n": w.count }, children: path.map((id, i) => {
+                const shown = w.visible.includes(id);
+                const insets = {
+                    "--duet-inset-left": i <= w.start ? "var(--duet-edge-left, 0px)" : "0px",
+                    "--duet-inset-right": i >= last ? "var(--duet-edge-right, 0px)" : "0px",
+                };
+                return _jsx("section", { className: "duet-pane", style: insets, "data-pane": id, "data-at": id === at || undefined, inert: !shown, "aria-hidden": !shown, children: panes[id] }, id);
+            }) }) }));
+}
+/** Navigation state for <DuetPanes>: `go` focuses a pane, `back` is ready for <Duet back>: it leaves full
+ *  screen first, then steps back along the path, and is false when that would change nothing on screen.
+ *  `expanded`/`toggle` drive the full-screen toggle and `close` closes the focused pane (back to the pair
+ *  before it), both ready for <DuetPaneBar>. */
+export function usePanes(path, initial = path[0]) {
+    const [at, setAt] = useState(initial);
+    const [expanded, setExpanded] = useState(false);
+    const { layout } = useDuet();
+    const go = (id) => { setAt(id); setExpanded(false); };
+    const to = backFrom(path, at, layout);
+    const prev = path[path.indexOf(at) - 1];
+    return {
+        at, go, layout, expanded,
+        toggle: () => setExpanded((e) => !e),
+        close: prev === undefined ? undefined : () => go(prev),
+        back: expanded && layout === "wide" ? { onPress: () => setExpanded(false) } : to !== null && { onPress: () => go(to) },
+    };
+}
+/** The pane's own controls, a small pill at its top right: close, full screen, and "…". It sticks to the top of
+ *  the pane as it scrolls, and keeps clear of the strip when the pane is on the controls' edge. */
+export function DuetPaneBar({ onClose, onToggle, expanded = false, more = [] }) {
+    const { layout } = useDuet();
+    const [open, setOpen] = useState(false);
+    const ref = useRef(null);
+    useEffect(() => {
+        if (!open)
+            return;
+        const off = (e) => { if (!ref.current?.contains(e.target))
+            setOpen(false); };
+        addEventListener("pointerdown", off, true);
+        return () => removeEventListener("pointerdown", off, true);
+    }, [open]);
+    const items = [...more.filter((m) => !m.destructive), ...more.filter((m) => m.destructive)];
+    const pick = (m) => () => { setOpen(false); m.onPress?.(); };
+    const full = !!onToggle && layout === "wide";
+    if (!onClose && !full && !items.length)
+        return null;
+    return (_jsxs("div", { className: "duet-pane-bar", ref: ref, children: [_jsxs("div", { className: "duet-pane-pill", children: [onClose && _jsx("button", { "aria-label": "Close", onClick: onClose, children: _jsx(X, { size: 18 }) }), full && _jsx("button", { "aria-label": expanded ? "Exit full screen" : "Full screen", "aria-pressed": expanded, onClick: onToggle, children: expanded ? _jsx(Minimize, { size: 17 }) : _jsx(Maximize, { size: 17 }) }), items.length > 0 && _jsx("button", { "aria-label": "More", "aria-expanded": open, onClick: () => setOpen(!open), children: _jsx(Ellipsis, { size: 20 }) })] }), open && (_jsx("div", { className: "duet-pane-menu", role: "menu", children: items.map((m, i) => (_jsxs("button", { role: "menuitem", onClick: pick(m), "data-destructive": m.destructive || undefined, "data-sep": (m.destructive && !items[i - 1]?.destructive && i > 0) || undefined, children: [_jsx("span", { children: m.label }), m.icon] }, m.id))) }))] }));
+}