duet-ui 0.3.0 → 0.4.0-rc.2

package/dist/chrome.js

@@ -2,56 +2,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useEffect, useLayoutEffect, 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 { glassTheme, themeVars } from "./theme.js";
+import { DUO, columnBand, isSplit, pageInsets, islandBox, magnet, morphBox, plan, stable } from "./geometry.js";
+import { emulatedSignals, epoch, readSignals, settling, watchSignals } from "./signals.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,
-        userAgent: navigator.userAgent,
-        touchPoints: navigator.maxTouchPoints,
-        standalone: navigator.standalone === true || matchMedia("(display-mode: standalone)").matches,
-    };
-}
+const envInset = (side) => { const e = emulatedSignals(); return e ? `${side === "right" ? e.insetRight : e.insetLeft}px` : `env(safe-area-inset-${side})`; };
 // 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";
@@ -90,35 +49,33 @@ function switchSide(el, side) {
 }
 let snap = null, snapKey = "";
 const damper = { flips: [] };
-let pinTimer;
-function read() {
-    const s = signals(), c = stable(damper, s, preferredSide(isSplit(s)), performance.now());
+let pinTimer, landTimer;
+// The damper keeps history, so it is fed once per signal change (refresh, from the watcher), never from React's
+// getSnapshot (read), which React may call several times per render.
+function refresh() {
+    const s = readSignals(), c = stable(damper, s, preferredSide(isSplit(s)), performance.now(), settling(), epoch());
     // 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);
+    // So is a landing after a fold or turn (LAND_HOLD), which no resize may follow.
+    if (damper.landUntil !== undefined && !landTimer)
+        landTimer = setTimeout(() => { landTimer = undefined; listeners.forEach((f) => f()); }, damper.landUntil - performance.now() + 10);
     const k = JSON.stringify(c);
     if (k !== snapKey)
         [snapKey, snap] = [k, c];
+}
+function read() {
+    if (!snap)
+        refresh();
     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 f = () => { refresh(); cb(); };
+    listeners.add(f);
+    const unwatch = watchSignals(f);
+    return () => { listeners.delete(f); unwatch(); };
 }
-const ssr = { mode: "column", duo: true, browser: "safari", device: "duo", standalone: false, layout: "narrow", side: "right", width: 382, height: 580, offsetTop: 0, screenWidth: 466, screenHeight: 678, insetTop: 0, insetBottom: 0 };
+const ssr = { mode: "column", duo: true, browser: "safari", device: "duo", standalone: false, layout: "narrow", side: "right", width: 382, height: 580, stableHeight: 580, offsetTop: 0, screenWidth: 466, screenHeight: 678, insetTop: 0, insetBottom: 0 };
 export function useDuet() {
     return useSyncExternalStore(subscribe, read, () => ssr);
 }
@@ -162,13 +119,18 @@ function useMinimized(on, scroller) {
 }
 /** 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
+ *  the document itself from scrolling, so the layer never moves. Without children the document scrolls, and the
+ *  layer rides it on a CSS scroll timeline (duet.css, duet-follow): Safari runs that with the scroll itself, so
+ *  it holds through momentum and smooth programmatic scrolls, where a transform set from scroll events lags and
+ *  drifts (#55; simulator, 2026-10-26: up to 300pt during scrollIntoView, under 2pt on the timeline).
+ *  The keyframe ends at the timeline's scroll range (--duet-scroll-max); a fixed 100000px range drifted ~12pt in
+ *  momentum. Browsers without scroll timelines get the transform. 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`). */
+ *  shows only its own column, and a tap there names the side (`tapSide`). A left-hand column (closed landscape,
+ *  turned left) works the same way, with the document spanning that column alone. */
 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.
@@ -189,19 +151,87 @@ function viewport(key, value) {
 }
 if (typeof document !== "undefined")
     viewport("shrink-to-fit", "no");
-function useColumnLayer(on, split, column) {
+// Leaving the column, the sideways scroll the layer pinned stays behind: from a split left pane turned into the tall
+// window (inline), the document kept scrollX -84 with nothing to scroll, and Safari then painted the pill's glass but
+// not its unselected tab icons (e2e round 4, splitturn-left-to90). So when the mode leaves the column (not while the
+// column is only hidden mid-turn), the scroll goes back to 0, again as Safari restores the old offset on the resize.
+function useColumnLayer(on, split, left, column, inColumn) {
     const refs = [useRef(null), useRef(null)];
+    const was = useRef(inColumn);
+    useEffect(() => {
+        const left = was.current && !inColumn;
+        was.current = inColumn;
+        if (!left || emulatedSignals())
+            return;
+        const reset = () => { if (Math.round(scrollX) !== 0)
+            scrollTo({ left: 0, top: scrollY, behavior: "instant" }); };
+        const t = [0, 300, 1000].map((ms) => setTimeout(reset, ms));
+        return () => t.forEach(clearTimeout);
+    }, [inColumn]);
     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);
+        const root = document.documentElement;
+        for (const el of els)
+            el.dataset.follow = "";
+        // A page reset such as `* { animation: none !important }` (common under reduced motion) drops the timeline.
+        const timeline = typeof CSS !== "undefined" && CSS.supports("animation-timeline: scroll()") && getComputedStyle(els[0]).animationName === "duet-follow";
+        if (!timeline)
             for (const el of els)
-                el.style.transform = scrollY ? `translateY(${scrollY}px)` : "";
+                delete el.dataset.follow;
+        // The keyframe ends at the timeline's own scroll range, which in Safari is scrollHeight - innerHeight: when the
+        // URL bar collapses innerHeight grows 18px but clientHeight does not, and scrollHeight - clientHeight drifted
+        // 6pt 1000pt down (simulator, 2026-10-26). Content can outgrow the body (absolute, overflowing), so every
+        // scroll re-measures as well as resizes.
+        let max = "";
+        const range = () => {
+            const m = `${Math.max(0, root.scrollHeight - innerHeight)}px`;
+            if (m !== max) {
+                max = m;
+                for (const el of els)
+                    el.style.setProperty("--duet-scroll-max", m);
+            }
+        };
+        const sizes = timeline ? new ResizeObserver(range) : undefined;
+        if (sizes) {
+            range();
+            sizes.observe(root);
+            sizes.observe(document.body);
+        }
+        // The layer's positions are document coordinates, from an absolute box at the document's left edge. A page whose
+        // <body> (or <html>) is positioned makes that its containing block, which body margins, or the margins that move
+        // the page beside a left column (pageInsets), move off the document's edge: measured, and undone with
+        // `translate` (the scroll timeline animates `transform`, which composes with it).
+        const align = () => {
+            refs.forEach((ref, i) => {
+                const el = ref.current;
+                if (!el)
+                    return;
+                el.style.translate = "";
+                const off = Math.round(el.getBoundingClientRect().left + scrollX - (split && i ? column : 0));
+                if (off)
+                    el.style.translate = `${-off}px 0`;
+            });
+        };
+        const follow = (e) => {
+            if (e?.type !== "scroll")
+                align();
+            // The layer widens the document, and a swipe that runs off the end of a sideways scroller chains to it
+            // (touch-action stops at the scroller), leaving page and controls panned off their rails: hold it.
+            // An emulating host already frames both columns; pinning there loops in iOS Safari, whose frame overflows a few px.
+            const x = split || left ? column : 0;
+            // Instant: under a page's `scroll-behavior: smooth` a plain scrollTo animates, and each scroll event restarted
+            // it, so the controls crept into the column over seconds (#66, back from /probe in a split left pane).
+            if (!emulatedSignals() && Math.round(scrollX) !== x)
+                scrollTo({ left: x, top: scrollY, behavior: "instant" });
+            if (timeline)
+                range();
+            else
+                for (const el of els)
+                    el.style.transform = scrollY ? `translateY(${scrollY}px)` : "";
         };
         const tap = (e) => {
             if (e.clientX >= 0 && e.clientX < innerWidth)
@@ -219,21 +249,28 @@ function useColumnLayer(on, split, column) {
             }
         };
         follow();
-        // Safari restores or resets the sideways scroll on load and resize.
+        // Safari restores or resets the sideways scroll on load, resize and a back/forward cache restore.
         const t = [0, 300, 1000].map((ms) => setTimeout(follow, ms));
         addEventListener("scroll", follow, { passive: true });
         addEventListener("resize", follow);
+        addEventListener("pageshow", follow);
         addEventListener("pointerdown", tap);
         return () => {
             html.touchAction = prev;
-            for (const el of els)
+            sizes?.disconnect();
+            for (const el of els) {
                 el.style.transform = "";
+                el.style.translate = "";
+                el.style.removeProperty("--duet-scroll-max");
+                delete el.dataset.follow;
+            }
             t.forEach(clearTimeout);
             removeEventListener("scroll", follow);
             removeEventListener("resize", follow);
+            removeEventListener("pageshow", follow);
             removeEventListener("pointerdown", tap);
         };
-    }, [on, split, column]); // eslint-disable-line react-hooks/exhaustive-deps -- refs are stable
+    }, [on, split, left, 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
@@ -322,6 +359,23 @@ export function Duet(props) {
     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);
+    // The first render is the server's guess (ssr) and the window geometry settles over the next second (subscribe):
+    // until then the controls jump to where they belong instead of gliding in from the guess.
+    const [settled, setSettled] = useState(false);
+    // A back/forward cache restore keeps the old state but not the old window (a split pane, a turn), so it settles
+    // afresh: the controls land where they belong instead of gliding there.
+    useEffect(() => {
+        let t = setTimeout(() => setSettled(true), 1100);
+        const restored = (e) => {
+            if (!e.persisted)
+                return;
+            clearTimeout(t);
+            setSettled(false);
+            t = setTimeout(() => setSettled(true), 1100);
+        };
+        addEventListener("pageshow", restored);
+        return () => { clearTimeout(t); removeEventListener("pageshow", restored); };
+    }, []);
     const glideTimer = useRef(0);
     useEffect(() => () => { clearTimeout(glideTimer.current); if (press.current)
         clearTimeout(press.current.timer); }, []);
@@ -348,13 +402,27 @@ export function Duet(props) {
     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);
+    const inner = p.children !== undefined; // the inner scroller, which runs on under Safari's column
+    const reserve = p.reserve !== false;
     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.
+        // column's frame already spans it), so the inset there is the column's width; a tab has no safe areas, so the
+        // other edge is 0. Without children the document is the page, and Duet places it beside the column itself
+        // (pageInsets): nothing for the page to do.
         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");
+        // Controls hidden for good in this window (the turned preview) take no room; hidden while moving keeps the
+        // last insets, so the page does not reflow twice in one turn.
+        const { left, right, shift } = pageInsets({
+            mode: ctx.mode, side: ctx.side, split, screenWidth: ctx.screenWidth, width: ctx.width, hiddenPreview: ctx.hidden === "preview",
+            inner, emulated: !!emulatedSignals(), reserve, env: envInset,
+        });
+        // The document is scrolled one column across (useColumnLayer): margins on <html> move the page into the visible
+        // viewport. <html>'s own margins, so the page's body margins, widths and max-widths are untouched, centred
+        // content centres in the visible pane, and position: fixed (already viewport relative) is unaffected.
+        r.marginLeft = shift ? `${shift}px` : "";
+        r.marginRight = shift ? `${-shift}px` : "";
+        document.documentElement.toggleAttribute("data-duet-reserve", !!shift);
         // --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);
@@ -362,15 +430,29 @@ export function Duet(props) {
         }
         // 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");
+        r.setProperty("--duet-inset-top", ctx.mode === "strip" && ctx.standalone ? `${DUO.edgeBlur}px` : "0px");
         // Safari's URL pill floats below the layout viewport (the column holds nothing above the page), so the scroller
         // runs on under it like a document that scrolls, and the last content scrolls clear of it.
         r.setProperty("--duet-inset-bottom", ctx.mode === "column" ? `${Math.max(0, ctx.screenHeight - ctx.height)}px` : "0px");
+        // Safari's column buttons paint over the page: a popover that reaches into the column keeps its top at or below
+        // this (columnBand). Split view takes the lower of the two panes' limits, since nothing tells which pane it is.
+        const bands = sides.map((side) => columnBand({ ...ctx, side }));
+        r.setProperty("--duet-safe-top-column", `${Math.max(0, ...bands.map((b) => b?.top ?? 0))}px`);
+        // The page's height without Safari's URL bar bouncing it mid-scroll (Context.stableHeight), like 100svh.
+        r.setProperty("--duet-vh", `${ctx.stableHeight}px`);
         document.documentElement.dataset.duetMode = ctx.mode;
-        document.documentElement.toggleAttribute("data-duet-emulated", !!emulated);
+        document.documentElement.toggleAttribute("data-duet-emulated", !!emulatedSignals());
         document.documentElement.toggleAttribute("data-duet-split", split);
-    }, [ctx.mode, ctx.side, ctx.screenWidth, ctx.screenHeight, ctx.width, ctx.height, split]);
-    const [nav, nav2] = useColumnLayer(ctx.mode === "column", split, column);
+    }, [ctx.mode, ctx.side, ctx.hidden === "preview", ctx.screenWidth, ctx.screenHeight, ctx.width, ctx.height, ctx.stableHeight, split, inner, reserve]);
+    useEffect(() => () => {
+        const h = document.documentElement;
+        h.style.marginLeft = "";
+        h.style.marginRight = "";
+        h.removeAttribute("data-duet-reserve");
+    }, []);
+    // Mid-turn the layer is clipped out of the document (duet.css) and lets go of the sideways scroll; the landing
+    // takes it up again, scrolled one column across for a left column.
+    const [nav, nav2] = useColumnLayer(ctx.mode === "column" && ctx.hidden !== "moving", split, ctx.side === "left", column, ctx.mode === "column");
     useEffect(() => {
         // Any touch outside the chrome closes an open menu, like a native context menu.
         if (!menu)
@@ -408,7 +490,8 @@ export function Duet(props) {
     };
     useLayout(() => { if (scroller.current && selected !== undefined)
         scroller.current.scrollTop = scrolls.current.get(selected) ?? 0; }, [selected]);
-    const badge = (a) => a.badge !== undefined && a.badge !== "" && _jsx("span", { className: "duet-badge", children: a.badge });
+    const theme = themeVars(p);
+    const badge = (a) => a.badge !== undefined && a.badge !== "" && _jsx("span", { className: "duet-badge", "data-tone": a.badgeTone === "neutral" ? "neutral" : undefined, 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)
@@ -517,15 +600,13 @@ export function Duet(props) {
         // 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` };
+            const { x0, ...box } = islandBox(pl, b, n, side);
+            return { ...box, "--x0": `${x0}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.
+        // Morph: the button grows into a labelled list, clear of Safari's column buttons (morphBox).
         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 { x0, y0, scroll, ...box } = morphBox(side === ctx.side ? ctx : { ...ctx, side }, pl, b, n);
+            return { ...box, "--x0": `${x0}px`, "--y0": `${y0}px`, ...(scroll && { overflowY: "auto", overscrollBehavior: "contain" }) };
         };
         const shownLeading = leading.slice(0, leading.length - pl.menu.leading);
         const shownActions = actions.slice(0, actions.length - pl.menu.actions);
@@ -544,10 +625,10 @@ export function Duet(props) {
                     } }] : []),
             ...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 && (
+        return (_jsxs("nav", { ref: i ? nav2 : nav, className: "duet", "data-mode": ctx.mode, "data-side": side, "data-settling": !settled || ctx.confidence !== "sure" || undefined, "data-hidden": ctx.hidden, "data-confidence": ctx.confidence, "data-keyboard": ctx.keyboard || undefined, style: { ...theme, ...(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)] }));
+    return (_jsxs(GlassProvider, { defaultTheme: glassTheme(p.appearance, p.dark), children: [p.children !== undefined && _jsx("div", { ref: scroller, className: "duet-scroller", children: p.children }), sides.map(bar), ctx.mode === "column" && !emulatedSignals() && sides.map((side) => _jsx("span", { className: "duet-guard", "data-side": side, "aria-hidden": true }, side))] }));
 }

package/dist/duet.css

@@ -1,6 +1,20 @@
 /* iOS 27 Duo strip controls on GlassyUI surfaces. Colours sampled from the native lab captures.
    Theme follows GlassyUI's [data-lg-theme] on <html> (system light/dark unless forced), with the media
-   query as the fallback before hydration. */
+   query as the fallback before hydration.
+
+   Theme tokens, a stable surface: set them on .duet (or any ancestor) in your own CSS, or through the
+   tint, appearance and icons props, which write the same vars.
+     --duet-tint            accent: selected tab, active menu item, primary button (system blue)
+     --duet-ink             text and default icon colour (black / white)
+     --duet-icon            icon colour when not selected (--duet-ink)
+     --duet-icon-size       icons in round buttons, groups and menus (22px)
+     --duet-tab-icon-size   icons in the tab pill (24px)
+     --duet-icon-weight     stroke width of SVG line icons (2)
+     --duet-badge, --duet-badge-neutral, --duet-badge-ink   badge fills (alert, neutral) and text
+     --duet-solid           opaque surface: menus in Safari's column, the badge's ring
+     --duet-frost, --duet-menu   glass veil of controls and of menus
+     --duet-sel, --duet-lift     selection and press highlight
+   Icons size and weigh your own SVGs and font glyphs (font-size: 1em); the system glyphs keep theirs. */
 .duet {
   -webkit-text-size-adjust: 100%; text-size-adjust: 100%;
   --duet-solid: rgb(246 247 250);
@@ -13,6 +27,8 @@
   --duet-menu: rgb(255 255 255 / 0.55);
   --duet-ink: #000;
   --duet-tint: #0088ff;
+  --duet-icon-size: 22px; --duet-tab-icon-size: 24px; --duet-icon-weight: 2;
+  --duet-badge: #ff3b30; --duet-badge-neutral: #6e6e73; --duet-badge-ink: #fff;
   color: var(--duet-ink);
   -webkit-tap-highlight-color: transparent;
   /* A held press would otherwise start text selection and iOS's loupe instead of the lift. */
@@ -23,18 +39,24 @@
   :root:not([data-lg-theme="light"]) .duet {
     --duet-solid: rgb(38 38 40); --duet-ring: rgb(255 255 255 / 0.16);
     --duet-frost: rgb(0 0 0 / 0.24); --duet-lift: rgb(255 255 255 / 0.16);
-    --duet-sel: rgb(0 0 0 / 0.22); --duet-menu: rgb(0 0 0 / 0.4); --duet-ink: #fff;
+    --duet-sel: rgb(0 0 0 / 0.22); --duet-menu: rgb(0 0 0 / 0.4); --duet-ink: #fff; --duet-badge-neutral: #636366;
   }
 }
 [data-lg-theme="dark"] .duet {
   --duet-solid: rgb(38 38 40); --duet-ring: rgb(255 255 255 / 0.16);
   --duet-frost: rgb(0 0 0 / 0.24); --duet-lift: rgb(255 255 255 / 0.16);
-    --duet-sel: rgb(0 0 0 / 0.22); --duet-menu: rgb(0 0 0 / 0.4); --duet-ink: #fff;
+    --duet-sel: rgb(0 0 0 / 0.22); --duet-menu: rgb(0 0 0 / 0.4); --duet-ink: #fff; --duet-badge-neutral: #636366;
 }
 .duet button {
   appearance: none; border: 0; background: none; color: inherit; padding: 0; margin: 0; cursor: pointer;
   display: flex; align-items: center; justify-content: center;
 }
+/* Your icons: one size per context and one weight, like SF Symbols in a native bar. */
+.duet :is(.duet-item, .duet-tab, .duet-menu-item) { color: var(--duet-icon, var(--duet-ink)); font-size: var(--duet-icon-size); }
+.duet .duet-tab { font-size: var(--duet-tab-icon-size); }
+.duet :is(.duet-item, .duet-menu-item) > svg:not([data-duet-glyph]) { width: var(--duet-icon-size); height: var(--duet-icon-size); stroke-width: var(--duet-icon-weight); }
+.duet .duet-tab > svg:not([data-duet-glyph]) { width: var(--duet-tab-icon-size); height: var(--duet-tab-icon-size); stroke-width: var(--duet-icon-weight); }
+.duet .duet-primary .duet-item { color: var(--duet-tint); }
 .duet-glass {
   position: fixed; z-index: 50; box-sizing: border-box; border-radius: 999px; color: var(--duet-ink);
   box-shadow: 0 4px 14px rgb(0 0 0 / 0.06);
@@ -144,9 +166,10 @@
 .duet-glass:has(.duet-badge) { overflow: visible; contain: layout style; }
 .duet .duet-badge {
   position: absolute; top: 2px; left: calc(50% + 5px); min-width: 18px; height: 18px; padding: 0 5px; box-sizing: border-box;
-  border-radius: 9px; background: #ff3b30; color: #fff; font: 600 12px/18px -apple-system, system-ui; text-align: center;
+  border-radius: 9px; background: var(--duet-badge); color: var(--duet-badge-ink); font: 600 12px/18px -apple-system, system-ui; text-align: center;
   font-variant-numeric: tabular-nums; pointer-events: none; box-shadow: 0 0 0 1.5px var(--duet-solid);
 }
+.duet .duet-badge[data-tone="neutral"] { background: var(--duet-badge-neutral); }
 .duet[data-side="right"] .duet-badge { left: auto; right: calc(50% + 5px); }
 .duet-accessory { display: flex; align-items: center; padding: 0 18px; font: 600 17px -apple-system, system-ui; gap: 12px; }
 .duet-accessory { transition: opacity 0.2s, transform 0.2s; }
@@ -190,10 +213,16 @@
 .duet[data-drag="held"], .duet[data-drag="switch"] { transition: none; }
 /* Switching sides moves every control in the same frame: nothing glides across the page on its own. */
 .duet[data-drag="switch"] * { transition: none !important; }
+/* Mid fold or turn (Context.hidden "moving") and in the turned in-app preview ("preview"): not drawn. */
+.duet[data-hidden] { visibility: hidden; pointer-events: none; }
+/* Loading, and while the window settles after a fold, turn or resize: the controls appear where they settle, without transitions or entrance animations. */
+/* The root itself keeps its animation: in Safari's column it is the scroll follow (duet-follow), not an entrance. */
+.duet[data-settling], .duet[data-settling] * { transition: none !important; }
+.duet[data-settling] * { animation: none !important; }
 .duet[data-drag="free"] { transition: --duet-drag 0.12s ease-out; }
 .duet-menu-item { width: 46.5px; height: 43px; flex: none; border-radius: 999px; }
 /* Destructive items (blueprint): only in "…", last, red, set apart by a hairline in the labelled list. */
-.duet-menu-item[data-destructive] { color: #ff3b30; }
+.duet .duet-menu-item[data-destructive] { color: #ff3b30; }
 .duet-menu[data-style="morph"] > .duet-menu-item[data-sep] { box-shadow: 0 -0.5px 0 var(--duet-ring); border-top-left-radius: 0; border-top-right-radius: 0; }
 /* The primary action: the one tinted button, so the thumb finds it. */
 .duet-primary { color: var(--duet-tint); }
@@ -208,8 +237,9 @@
 .duet[data-side="left"] .duet-menu[data-style="morph"] { flex-direction: column; }
 .duet-menu[data-style="morph"] > .duet-menu-item {
   width: auto; height: 44px; border-radius: 16px; display: flex; align-items: center; justify-content: flex-start; gap: 12px; padding: 0 12px;
-  font: 400 17px -apple-system, system-ui; text-align: left; white-space: nowrap;
+  font-weight: 400; text-align: left; white-space: nowrap;
 }
+.duet-menu[data-style="morph"] .duet-menu-label { font-size: 17px; color: var(--duet-ink); }
 .duet-menu[data-style="morph"] > .duet-menu-item > svg { flex: none; }
 .duet-menu-label { overflow: hidden; text-overflow: ellipsis; }
 .duet-menu[data-style="morph"] > .duet-menu-item { animation: duet-rise 0.15s 0.02s ease-out both; }
@@ -224,10 +254,11 @@ html:has(> body .duet-scroller), html:has(> body .duet-scroller) > body { height
 .duet-scroller { position: fixed; inset: 0; overflow-y: auto; overscroll-behavior: contain; box-sizing: border-box; }
 /* The page spans the whole window and the controls float over it (blueprint rules 14/15): backgrounds run on
    under the controls, and only text and buttons keep clear, by the insets (--duet-inset-left/right), through
-   column() or bleed(). Safari's column only shows in-document content and clips fixed boxes at the viewport
-   edge, so there the scroller is an in-document box that runs on under the column. The document still never
-   scrolls, so the chrome layer never moves. */
-html[data-duet-mode="column"] .duet-scroller { position: absolute; width: calc(100% + var(--duet-inset-right)); bottom: auto; height: calc(100% + var(--duet-inset-bottom)); }
+   column() or bleed(). Safari's column paints in-document content that overflows the layout viewport, but no
+   fixed box reaches it: a fixed box stops at the viewport edge, and one covering the middle of that edge has its
+   colour painted over the column instead (the guard below). So there the scroller is an in-document box that runs
+   on under the column. The document still never scrolls, so the chrome layer never moves. */
+html[data-duet-mode="column"] .duet-scroller { position: absolute; width: calc(100% + var(--duet-inset-left) + var(--duet-inset-right)); bottom: auto; height: calc(100% + var(--duet-inset-bottom)); }
 /* That overflow widens the document, and touch-action on <html> stops at this scroll container, so without its own
    a sideways swipe pans the whole page, chrome and all, into the column. Carousels inside are scrollers of their own
    and still pan. */
@@ -235,9 +266,8 @@ html[data-duet-mode="column"] .duet-scroller { touch-action: pan-y; }
 /* Safari's URL pill floats under the page's bottom edge: the scroller runs on under it (above) and this spacer lets
    the last content scroll clear of it. */
 .duet-scroller::after { content: ""; display: block; height: var(--duet-inset-bottom, 0px); }
-/* Split pane: a column on each side (the pane's own is on its outer edge, which the page cannot see); the
-   document is scrolled one column across (chrome.tsx). */
-html[data-duet-mode="column"][data-duet-split] .duet-scroller { width: calc(100% + var(--duet-inset-left) + var(--duet-inset-right)); }
+/* A column on the left (closed landscape turned left, or a split pane, which spans one on each side since its own
+   is on its outer edge, which the page cannot see): the document is scrolled one column across (chrome.tsx). */
 /* Emulated (the site's web Duo): the frame already spans the column and runs under the pill. */
 html[data-duet-mode="column"][data-duet-emulated] .duet-scroller { width: 100%; height: 100%; }
 
@@ -247,14 +277,52 @@ html[data-duet-mode="column"][data-duet-emulated] .duet-scroller { width: 100%;
    column buttons are a veil over that colour that follows the system appearance, not the page (sampled
    over dark and cream pages); ours match so the two sets read as one. The accessory sits over the page,
    not the column, so it keeps real glass; menus unroll over page content without blur, so they stay opaque. */
+/* The keyboard leaves Safari's column in place but covers its lower part; the controls step aside while typing. */
+.duet[data-mode="column"][data-keyboard] { visibility: hidden; }
+/* The layer only paints in the column as long as it widens the document (overflow-x clip, a clip margin or rtl
+   all stop the paint), and Safari zooms out to that width when a text field takes focus (to 0.94, column held).
+   So from focus, before the zoom and the keyboard, the layer is clipped out of the document width. */
+html:has(:read-write:focus) .duet[data-mode="column"] { overflow: clip; visibility: hidden; }
 .duet[data-mode="column"] { position: absolute; top: 0; left: 0; width: 0; height: 0; z-index: 50; }
-:root .duet[data-mode="column"] .duet-glass:not(.duet-accessory) {
-  --duet-col: rgb(240 239 236 / 0.55); --duet-solid: rgb(246 247 250); --duet-ink: #000; --duet-edge: 0.3; --duet-rim: 0.15;
+/* A page's full-screen fixed overlay (a modal scrim, `position: fixed; inset: 0`) would hide the whole column,
+   controls included: Safari 26 hit-tests the middle of each viewport edge, 4px in, for a fixed or sticky box
+   (LocalFrameView::fixedContainerEdges) and, when one covers it, paints that box's colour, or plain chrome behind a
+   backdrop-filter, over the inset beyond that edge, Safari's column included, instead of the page's in-document
+   content. The guard is a small fixed box straddling that point on the column's edge, above every page layer, so
+   the hit test lands on it instead: too small to count as a container itself, it has none above it, and the column
+   keeps showing the controls. That hit test skips layers with nothing fixed or sticky in them, so the guard is fixed
+   and outside the layer; it keeps a (transparent) background, since a box with no background, no backdrop and no
+   children counts as transparent and the hit test then retries without it, honouring pointer-events. It takes no
+   taps (simulator, 2026-10-27, #79). */
+.duet-guard {
+  position: fixed; z-index: 2147483647; top: 50%; width: 16px; height: 64px; margin-top: -32px; pointer-events: none;
+  background-image: linear-gradient(transparent, transparent);
 }
+.duet-guard[data-side="right"] { right: -8px; }
+.duet-guard[data-side="left"] { left: -8px; }
+/* Mid-turn or mid-fold the layer still carries the last posture's positions (the old screen's column), which would
+   widen the document past the new window, and Safari then zooms the page to fit it (scale 1.14 unfolding from
+   closed landscape into the tall window, e2e round 2). Clipped, it adds no width until the window lands. */
+.duet[data-mode="column"][data-hidden="moving"] { overflow: clip; }
+/* No children (no .duet-scroller): the document scrolls, and the layer rides it on a scroll timeline that Safari
+   runs with the scroll itself, so it holds through momentum and smooth scrollTo/scrollIntoView (chrome.tsx sets
+   data-follow and --duet-scroll-max, the document's scroll range, or a transform where this is unsupported). */
+.duet[data-mode="column"][data-follow] { animation: duet-follow linear both; animation-timeline: scroll(root block); }
+@keyframes duet-follow { from { transform: translateY(0); } to { transform: translateY(var(--duet-scroll-max, 0px)); } }
+/* The rubber band at either end moves the document past its scroll range, where the timeline (clamped to it) cannot
+   follow, so the layer rode the bounce: up to 160pt over Safari's own column buttons, or out of the column (#76). The
+   document there does not rubber-band, like a page with children, whose document never scrolls. Zero specificity, so
+   a page's own overscroll-behavior wins. */
+:where(html[data-duet-mode="column"]:has(> body .duet[data-follow])) { overscroll-behavior-y: none; }
+/* A swipe that runs off the end of a sideways scroller chains to the widened document and pans it, chrome and
+   all, into the column. Zero specificity, so a page's own overscroll-behavior wins. */
+:where(html[data-duet-mode="column"]) :where(*) { overscroll-behavior-x: contain; }
+/* Menus open over the page, not the column, so they keep the page's appearance (the base tokens). */
+:root .duet[data-mode="column"] .duet-glass:not(.duet-accessory) { --duet-col: rgb(240 239 236 / 0.55); --duet-edge: 0.3; --duet-rim: 0.15; }
+:root .duet[data-mode="column"] .duet-glass:not(.duet-accessory, .duet-menu) { --duet-solid: rgb(246 247 250); --duet-ink: #000; }
 @media (prefers-color-scheme: dark) {
-  :root .duet[data-mode="column"] .duet-glass:not(.duet-accessory) {
-    --duet-col: rgb(90 89 84 / 0.43); --duet-solid: rgb(38 38 40); --duet-ink: #fff; --duet-edge: 0.6; --duet-rim: 0;
-  }
+  :root .duet[data-mode="column"] .duet-glass:not(.duet-accessory) { --duet-col: rgb(90 89 84 / 0.43); --duet-edge: 0.6; --duet-rim: 0; }
+  :root .duet[data-mode="column"] .duet-glass:not(.duet-accessory, .duet-menu) { --duet-solid: rgb(38 38 40); --duet-ink: #fff; }
 }
 .duet[data-mode="column"] .duet-glass { position: absolute; }
 /* Rim, measured at device pixels against Safari's buttons on cream and near-black pages, light and dark UI.