duet-ui 0.3.0 → 0.4.0-rc.2

package/dist/geometry.js

@@ -31,7 +31,13 @@ export const SAFARI = { rows: 2, pill: DUO.pillPad + 2 * DUO.pillItem,
      *  under the same status column as a closed tab and grows the same way (bare: 124, recording: 178, a
      *  2-slot music activity: ~224), so it takes the closed tab's worst case. The pill sits DUO.bottom above
      *  the window bottom. */
-    splitTop: { left: 23.5, right: DUO.top + DUO.island } };
+    splitTop: { left: 23.5, right: DUO.top + DUO.island },
+    /** Closed landscape (Duo Lab simulator, iOS 27.1, 2026-10-26): the column is on the side the Duo is turned to,
+     *  48pt centre line from that edge as in portrait, and its buttons sit differently on each side. `top`: the back
+     *  slot's top (reader under it, a step apart); `pill`: the +/tabs pill's top. Turned left (angle 90) the island
+     *  heads the column and pushes the back slot down; turned right (270) it sits at the column's foot, under the
+     *  pill. Measured with a bare island: how Live Activities grow it in landscape is not yet known. */
+    landscape: { left: { top: 81.5, pill: 327 }, right: { top: 23.5, pill: 279 } } };
 /** Menu island slots: a button unrolls into a pill of these (Safari's own pill items are 50; 46.5 keeps
  *  every slot above the 44pt touch target). */
 export const ISLAND = { pad: 3, item: 46.5 };
@@ -41,13 +47,66 @@ export const MORPH = { width: 240, row: 44, pad: 6 };
  *  951, a split-view pane 385, closed landscape 594, closed Safari 382. */
 export const WIDE = 600;
 const layoutOf = (pageWidth) => pageWidth >= WIDE ? "wide" : "narrow";
-/** In-app Safari preview on the closed Duo (simulator, iOS 27.1, and device screenshot 2026-10-25): the page
- *  window is a fixed 375x667 at 3x, a size no iPhone has natively, and the preview's own buttons (close,
- *  reader, back, share/reload/Safari) sit in the column beside it, which the page cannot paint into (it
- *  clips at its edge). So controls go inline, on the left by default, away from the preview's column. */
-const PREVIEW = { width: 375, height: 667, pixelRatio: 3 };
-export const isPreview = (s) => !s.standalone && s.pixelRatio === PREVIEW.pixelRatio
-    && s.outerWidth === PREVIEW.width && s.outerHeight === PREVIEW.height;
+/** In-app Safari preview (SFSafariViewController) on the closed Duo. Its own buttons (close, reader, back, and a
+ *  share/reload/Safari pill) fill a column beside the page like a tab's. In portrait Duet's controls go into the free
+ *  gap of that column, between its reader/menu button and its back button (PREVIEW.gap, columnBand); turned, that
+ *  gap is ~26pt, too small for a button, so they go inline on the side away from the preview's column. Two
+ *  windows say preview (docs/research-notes.md, "In-app Safari preview"):
+ *  - iOS 27.1 (simulator, 2026-10-26, every presentation but a sheet): the closed screen's 466x678 window with an
+ *    84pt column like a tab's, but only 75pt below the page (382x603) and the page reaching the screen bottom
+ *    (safe-area-inset-bottom 34). A closed tab has 98pt (80 with the compact URL bar) and inset 0.
+ * *  - The page sheet, the common presentation (real Duo, iOS 18.7, Messages, 2026-10-26; simulator, iOS 27.1): a
+ *    450x670 window inside the 466x678 screen, page 366x600 (column 84, chrome 70), inset 34. The inset lands
+ *    ~100ms after the first sample (0, then 34), so stable() lets the verdict rise to preview at first (PREVIEW_RISE).
+ *    Turned, the sheet is 662x458 in the 678x466 screen, page 578x388, inset 34, its column on the side the Duo
+ *    is turned to (simulator, iOS 27.1, 2026-10-26).
+ *  - Full screen turned (simulator, iOS 27.1, e2e round 2): the 678x466 window, page 678x391 (no column, chrome 75),
+ *    inset bottom 34, the buttons in a safe-area inset of 84 on the side the Duo is turned to.
+ *    No tab is smaller than the screen: closed 466x678, open 951x669, a split pane 469x669 (wider than the 466
+ *    screen Safari keeps reporting), all inset 0 in every state measured.
+ *  - Older builds (device screenshot 2026-10-25): a fixed 375x667 window at 3x, a size no iPhone has natively. */
+/** chrome: a band around the 75pt measured, clear of a tab's 98 and 80 (compact or scrolled URL bar). A compact
+ *  split pane (75) has another window size. stable() also keeps a tab's verdict while it scrolls, so a tab whose
+ *  chrome drifts into the band mid-scroll is not taken for the preview. sheetInset: how far inside the screen, on
+ *  each side, a window must be to count as a sheet (16x8 measured; a split pane is 3pt wider than the screen). */
+/** gap: the free band of the preview's portrait column, in screen points (the same in the sheet and full screen,
+ *  simulator iOS 27.1 and real Duo iOS 18.7, 2026-10-26): its reader/menu button's bottom and its back button's top.
+ *  146pt, room for two buttons ("…" and the selected tab) with DUO.gap around them. Measured with a bare island:
+ *  how Live Activities move the preview's buttons is not yet known. */
+const PREVIEW = { width: 375, height: 667, pixelRatio: 3, chrome: [73, 77], sheetInset: 4, gap: { top: 282, bottom: 428 } };
+/** Why the signals read as the in-app preview, for probes and logs; undefined when they do not. */
+export function previewReason(s) {
+    if (s.standalone || browserOf(s.userAgent) !== "safari")
+        return;
+    if (s.pixelRatio === PREVIEW.pixelRatio && s.outerWidth === PREVIEW.width && s.outerHeight === PREVIEW.height)
+        return "375x667 window at 3x";
+    const chrome = s.outerHeight - s.innerHeight;
+    // The sheet on the open screen (e2e round 3/4: 653x661 wide, 653x869 tall, no column, inset 0 or 34): no Safari
+    // window has these sizes.
+    if (UNFOLDED_SHEETS.some(([a, b]) => Math.abs(s.outerWidth - a) <= 1 && Math.abs(s.outerHeight - b) <= 1)
+        && s.outerWidth - s.innerWidth <= 2 && within(chrome, LANDED.chrome))
+        return `${s.outerWidth}x${s.outerHeight} sheet on the open screen, inset ${s.insetBottom}`;
+    // A tab measured inset 0 in every state (fresh, scrolled, keyboard, landscape); the preview 34.
+    if (s.insetBottom < 20)
+        return;
+    // Turned full screen (iOS 27.1, every presentation but a sheet): the whole 678x466 window, no page column (the
+    // preview's buttons sit in a safe-area inset instead, left at 90, right at 270), 75pt chrome. A turned tab has
+    // 98 with its column, or 126 fresh (inset 34 after a fold), so the chrome band alone tells them apart.
+    if (within(chrome, PREVIEW.chrome) && Math.abs(s.outerWidth - DUO_SIZES[0][1]) <= 1 && Math.abs(s.outerHeight - DUO_SIZES[0][0]) <= 1
+        && Math.abs(s.innerWidth - s.outerWidth) <= 1)
+        return `678x466 window, ${chrome}pt chrome, inset ${s.insetBottom}, turned`;
+    if (!hasColumn(s))
+        return;
+    if (within(chrome, PREVIEW.chrome) && Math.abs(s.outerWidth - DUO_SIZES[0][0]) <= 1 && Math.abs(s.outerHeight - DUO_SIZES[0][1]) <= 1)
+        return `466x678 window, ${chrome}pt chrome, inset ${s.insetBottom}`;
+    // The sheet: a window inside the closed screen on both sides, in either orientation.
+    const [w, h] = DUO_SIZES[0], m = PREVIEW.sheetInset;
+    const short = (a, b) => Math.min(a, b), long = (a, b) => Math.max(a, b);
+    if (short(s.screenWidth, s.screenHeight) === w && long(s.screenWidth, s.screenHeight) === h
+        && short(s.outerWidth, s.outerHeight) <= w - m && long(s.outerWidth, s.outerHeight) <= h - m)
+        return `${s.outerWidth}x${s.outerHeight} sheet in the ${s.screenWidth}x${s.screenHeight} screen, inset ${s.insetBottom}`;
+}
+export const isPreview = (s) => previewReason(s) !== undefined;
 /** Window and screen sizes only the Duo has, as [short, long] sides: the closed screen (Safari's `screen.*` keeps
  *  466x678 after unfolding, so it holds in every Safari state), the open screen, and a split-view pane's window.
  *  Other phones and desktops never match, so apps can switch to a Duo layout on it alone. */
@@ -99,54 +158,201 @@ export const isSplit = (s) => !s.standalone && isIOS(s) !== false && Math.abs(s.
  *  pane on the open Duo (469x669 outer, 385x571 inner) has the same column on its outer edge, so either
  *  side of the page. In-document content paints into it once the document spans both columns (84 + 385 + 84)
  *  and is scrolled 84 across, with `shrink-to-fit=no` in the viewport meta, or Safari zooms the pane out to
- *  fit the wider document (simulator probes, 2026-10-25). Windowed Safari (floating, or beside the Home Screen)
- *  keeps the column at other window sizes (device 2026-10-25: 453x661 and 450x670 outer, 369x591 inner), and a
- *  pane with the compact URL bar has 75pt of chrome, so any portrait Safari window on the Duo with the column counts. */
-const SAFARI_COLUMN = { width: [80, 88], chrome: [68, 102] };
+ *  fit the wider document (simulator probes, 2026-10-25). A device trace (2026-10-25) read the column at other
+ *  window sizes (453x661 and 450x670 outer, 369x591 and 366x600 inner), then taken for windowed Safari; 450x670
+ *  with inset 34 is the in-app preview's sheet (isPreview), which goes inline. A pane with the compact URL bar has
+ *  75pt of chrome, so any portrait Safari window on the Duo with the column counts. */
+// The largest Dynamic Type grows the bottom bar to 106pt (382x572 in 466x678, e2e round 3).
+const SAFARI_COLUMN = { width: [80, 88], chrome: [68, 110] };
 const within = (v, [a, b]) => v >= a && v <= b;
-/** preferred: the side the user picked for inline controls, if any. */
-export function detect(s, preferred, allowColumn = true) {
+const hasColumn = (s) => within(s.outerWidth - s.innerWidth, SAFARI_COLUMN.width) && within(s.outerHeight - s.innerHeight, SAFARI_COLUMN.chrome);
+/** Side inset of a Home Screen app on the Duo: 84 measured (closed portrait). iPhones have up to 59 in landscape. */
+const STRIP_INSET = 76;
+/** The keyboard (or anything else) covers the bottom of the page: the visual viewport is shorter than the layout one.
+ *  WebKit can report a negative visual height after the preview's sheet is folded from the open screen (-78 for a
+ *  600pt page, e2e round 3, held until the next resize); no viewport is that short, so it is not a keyboard. */
+export const keyboardUp = (s) => s.visualHeight > 0 && s.visualHeight < s.innerHeight - 1;
+/** preferred: the side the user picked for inline controls, if any. preview: the in-app preview verdict, when the
+ *  caller holds a sticky one (stable()). */
+export function detect(s, preferred, allowColumn = true, preview = isPreview(s)) {
     const duo = isDuo(s), browser = browserOf(s.userAgent), device = deviceOf(s), standalone = s.standalone;
     // Only a Home Screen app owns the strip: a Safari tab reports the column as an 84pt inset for a frame while folding.
-    if (s.standalone && (s.insetRight >= 60 || s.insetLeft >= 60)) {
-        return { mode: "strip", duo, browser, device, standalone, layout: layoutOf(s.innerWidth), side: s.insetRight >= 60 ? "right" : "left", width: s.innerWidth, height: s.innerHeight, offsetTop: Math.max(0, s.screenHeight - s.innerHeight), screenWidth: s.screenWidth, screenHeight: s.screenHeight, insetTop: s.insetTop, insetBottom: s.insetBottom };
+    const keyboard = keyboardUp(s);
+    const kb = keyboard ? { keyboard } : {};
+    if (s.standalone && duo && (s.insetRight >= STRIP_INSET || s.insetLeft >= STRIP_INSET)) {
+        return { ...kb, mode: "strip", duo, browser, device, standalone, layout: layoutOf(s.innerWidth), side: s.insetRight >= STRIP_INSET ? "right" : "left", width: s.innerWidth, height: s.innerHeight, stableHeight: s.innerHeight, offsetTop: Math.max(0, s.screenHeight - s.innerHeight), screenWidth: s.screenWidth, screenHeight: s.screenHeight, insetTop: s.insetTop, insetBottom: s.insetBottom };
     }
-    const base = { duo, browser, device, standalone, width: s.innerWidth, height: s.innerHeight, offsetTop: 0, insetTop: s.insetTop, insetBottom: s.insetBottom };
+    const base = { ...kb, duo, browser, device, standalone, width: s.innerWidth, height: s.innerHeight, stableHeight: s.innerHeight, offsetTop: 0, insetTop: s.insetTop, insetBottom: s.insetBottom };
+    // Closed landscape: the column is on the side the Duo is turned to, and the turn is the only signal for it.
+    const landscape = s.innerWidth > s.innerHeight;
+    const turned = s.angle === 90 ? "left" : s.angle === 270 ? "right" : undefined;
+    const closed = Math.abs(s.outerWidth - DUO_SIZES[0][1]) <= 1 && Math.abs(s.outerHeight - DUO_SIZES[0][0]) <= 1;
+    const columnSide = !landscape ? "right" : closed ? turned : undefined;
     // Other iOS browsers draw their own chrome where Safari has its column: inline for them.
-    const column = allowColumn && !s.standalone && !s.framed && browser === "safari"
-        && within(s.outerWidth - s.innerWidth, SAFARI_COLUMN.width)
-        && within(s.outerHeight - s.innerHeight, SAFARI_COLUMN.chrome)
-        && s.innerHeight > s.innerWidth // landscape moves Safari's column buttons around
-        && s.visualHeight >= s.innerHeight - 1; // keyboard up
+    // An in-app preview has the column signature too: in portrait its column has a gap Duet's controls fit in
+    // (columnBand); turned, it has none, so the preview goes inline there.
+    // Pinch zoom puts innerWidth in zoomed px, so the column signature means nothing then (stable() holds instead).
+    // The keyboard leaves Safari's column in place (only the visual viewport shrinks), so it does not change the mode.
+    const split = isSplit(s);
+    const column = allowColumn && !!columnSide && !s.standalone && !s.framed && browser === "safari" && (!preview || !landscape)
+        && hasColumn(s) && (s.scale ?? 1) === 1;
     // Safari's page viewport starts at screen top and ends above its address bar (382x580 of 466x678).
-    if (column && isSplit(s))
+    if (column && split)
         return { ...base, mode: "column", layout: layoutOf(s.innerWidth), side: "right", screenWidth: s.outerWidth, screenHeight: s.outerHeight, split: true };
     if (column && duo)
-        return { ...base, mode: "column", layout: layoutOf(s.innerWidth), side: "right", screenWidth: s.outerWidth, screenHeight: s.outerHeight };
-    const preview = isPreview(s), split = isSplit(s);
-    return { ...base, mode: "inline", layout: layoutOf(s.innerWidth), side: preferred ?? (preview ? "left" : "right"), screenWidth: s.innerWidth, screenHeight: s.innerHeight, ...(preview && { preview }), ...(split && { split }) };
+        return { ...base, mode: "column", layout: layoutOf(s.innerWidth), side: columnSide, screenWidth: s.outerWidth, screenHeight: s.outerHeight, ...(preview && { preview }) };
+    // The turned full-screen preview (default and full styles, iOS 27.1): its buttons all sit in a top bar, and the 84pt
+    // safe-area inset on the side the Duo is turned to (left at 90, right at 270) is page area nothing native uses
+    // below that bar. The controls take it, like a Home Screen app's strip (e2e round 4: the sheet turned has only a
+    // ~26pt gap in its column, so it stays hidden).
+    const band = s.insetLeft >= STRIP_INSET ? "left" : s.insetRight >= STRIP_INSET ? "right" : undefined;
+    if (preview && landscape && closed && band && browser === "safari" && !s.standalone && !s.framed)
+        return { ...base, mode: "strip", layout: layoutOf(s.innerWidth - INLINE_WIDTH), side: band, screenWidth: s.innerWidth, screenHeight: s.innerHeight, preview };
+    // A preview inline: away from its own column (on the side the Duo is turned to, else the right).
+    // On the open screen the sheet has no column of its own: inline right, like a full-width tab, and never hidden.
+    const onClosed = Math.min(s.outerWidth, s.outerHeight) <= DUO_SIZES[0][0] + 1 && Math.max(s.outerWidth, s.outerHeight) <= DUO_SIZES[0][1] + 1;
+    const away = preview && onClosed ? (landscape && turned === "left" ? "right" : "left") : "right";
+    return { ...base, mode: "inline", layout: layoutOf(s.innerWidth), side: preferred ?? away, screenWidth: s.innerWidth, screenHeight: s.innerHeight, ...(preview && { preview }), ...(preview && onClosed && landscape && browser === "safari" && !s.standalone && { hidden: "preview" }), ...(split && { split }) };
+}
+/** Every window a Safari page on the Duo lands in, as measured (docs/research-notes.md): `page` is how much
+ *  narrower the page is than the window (0, or Safari's 84pt column), `chrome` how much shorter (the address bar:
+ *  closed 98 or 80 compact, open and fresh landscape 126, split pane 98, preview 70 to 75). A sample outside these
+ *  is a fold, unfold or turn caught halfway: the viewport lands first and the window up to ~2s later (rotation 90 to
+ *  0, simulator 2026-10-26: 678x340, 466x498, 382x498, then 382x580 in 466x678). */
+/** How far inside the closed screen the preview's sheet may be: 16x8 measured. */
+const SHEET_SLACK = 40;
+/** The in-app preview's sheet on the open screen, wide and tall posture (simulator, iOS 27.1). */
+const UNFOLDED_SHEETS = [[653, 661], [653, 869]];
+const LANDED = { page: [[0, 2], [83, 85]], chrome: [0, 160], columnChrome: 110 };
+/** True while a Safari page on the Duo is between postures: the page and its window disagree on orientation, the
+ *  turn (screen.orientation.angle) disagrees with the page, or page and window are not a pair Safari settles in
+ *  (LANDED, or the window is not a Duo window or the preview's sheet). Only asked while the window settles
+ *  (signals.ts settling(), at most SETTLE.cap), so a state never measured cannot hide the controls for good. */
+export function inTransit(s) {
+    if (s.standalone || s.framed || browserOf(s.userAgent) !== "safari" || isIOS(s) === false || !isDuo(s))
+        return false;
+    // The preview's sheet on the open screen: a near-square window of its own, no column, its page wider than tall in
+    // the wide posture (e2e round 3: 653x661 wide, 653x869 tall).
+    if (s.outerWidth - s.innerWidth <= LANDED.page[0][1] && within(s.outerHeight - s.innerHeight, LANDED.chrome)
+        && UNFOLDED_SHEETS.some(([a, b]) => Math.abs(s.outerWidth - a) <= 1 && Math.abs(s.outerHeight - b) <= 1))
+        return false;
+    const landscape = s.innerWidth > s.innerHeight;
+    if (landscape !== s.outerWidth > s.outerHeight)
+        return true;
+    const [w, h] = DUO_SIZES[0], m = PREVIEW.sheetInset, short = Math.min(s.outerWidth, s.outerHeight), long = Math.max(s.outerWidth, s.outerHeight);
+    // The turn speaks for the closed screen only: the open screen is landscape at angle 0.
+    const closed = short <= w + 1 && long <= h + 1;
+    if (closed && s.angle !== undefined && s.angle % 90 === 0 && (s.angle % 180 === 90) !== landscape)
+        return true;
+    const page = s.outerWidth - s.innerWidth, chrome = s.outerHeight - s.innerHeight;
+    if (!LANDED.page.some((r) => within(page, r)) || !within(chrome, LANDED.chrome))
+        return true;
+    // Safari's column is 84pt in every window measured, and comes with its bottom URL bar (chrome 98, 106 at the largest
+    // Dynamic Type, preview 70 to 75), never with the 126pt bars of a full open window. Anything else is a stale layout
+    // handed a new window (e2e round 3: entering split view, 867x543 in 951x669 for ~200ms before the pane; going home
+    // from a split pane, the pane's 385x571 page in the closed screen's 466x678 window, an 81pt "column").
+    if (page >= LANDED.page[1][0] && chrome > LANDED.columnChrome)
+        return true;
+    // A Duo window, or the preview's sheet (a window a few points inside the closed screen; its inset lands ~100ms late,
+    // so sizes alone decide).
+    const sheet = short <= w - m && long <= h - m && short >= w - SHEET_SLACK && long >= h - SHEET_SLACK;
+    return !duoSize(s.outerWidth, s.outerHeight) && !sheet;
 }
 const FLIP_WINDOW = 2000;
 export const PIN_TTL = 3000;
-export function stable(d, s, preferred, now) {
+/** Longest pin: a loop that keeps resuming doubles the wait up to this. */
+export const PIN_MAX = 60000;
+/** How long after a window first shows (stable signals or epoch changed) its verdict may still rise to preview:
+ *  the real sheet's bottom inset reads 0 on the first sample and 34 ~100ms later (device, 2026-10-26). */
+export const PREVIEW_RISE = 1000;
+/** How long a landing after a fold or turn caught halfway must hold before the controls show there: unfolding from
+ *  closed landscape passes through the closed portrait window (382x580 in 466x678, angle 0) for ~90ms before the
+ *  open one (simulator, e2e round 2), a state that reads as landed and would flash the column for a frame. */
+export const LAND_HOLD = 150;
+/** settling: the window is still moving after a geometry event (signals.ts settling()). A fold lands the viewport
+ *  first and outerWidth up to ~2s later, flipping the mode on the way at an unchanged window size, so flips then are
+ *  the transition, not a loop, and do not count.
+ *  epoch: signals.ts epoch(), bumped on pageshow and when the page becomes visible again.
+ *
+ *  Signals come in two kinds. Stable ones (window size, page width, turn, standalone, frame, epoch) change only on
+ *  load, fold, rotation or a new page show, and a mode they ask for is taken at once. Drifting ones (page height
+ *  with the URL bar or find bar, the visual viewport with the keyboard, pinch zoom) move while the user scrolls or
+ *  types, and never move the controls mid-gesture: a mode only they ask for waits until the window settles, and
+ *  under pinch zoom the last context holds.
+ *
+ *  The preview verdict is sticky the same way: a page that loaded as a tab stays a tab while it scrolls, since the
+ *  URL bar collapsing changes only the page height. A tab becomes a preview only on a stable change or in the
+ *  first PREVIEW_RISE ms of a window (the sheet's late inset); a preview becomes a tab as soon as the rule stops
+ *  matching (Open in Safari). */
+export function stable(d, s, preferred, now, settling = false, epoch = 0) {
     const key = `${s.outerWidth}x${s.outerHeight}`;
+    // Pinch zoom holds the context committed in this window. A scale off 1 in another window is WebKit's, not the
+    // user's: folding the open preview sheet (653 wide, its document briefly 935) onto the closed screen leaves
+    // visualViewport.scale at 1.0152 with the visual viewport as wide as the page (366), held until the next
+    // gesture (e2e round 4, pvu-open-unfolded-fold). Holding there kept the open screen's inline controls, drawn off
+    // the closed screen, so a window change reads the signals as unzoomed.
+    if ((s.scale ?? 1) !== 1 && d.last) {
+        if (d.lastKey === key) {
+            const keyboard = keyboardUp(s) || undefined;
+            return { ...d.last, keyboard, confidence: "held" };
+        }
+        s = { ...s, scale: 1 };
+    }
+    const stableKey = `${key} ${s.innerWidth} ${s.angle ?? 0} ${s.standalone} ${!!s.framed} ${epoch}`, raw = isPreview(s);
+    if (stableKey !== d.previewKey)
+        d.previewAt = now;
+    const rising = now - (d.previewAt ?? now) < PREVIEW_RISE;
+    if (d.preview === undefined || !raw || stableKey !== d.previewKey || rising)
+        d.preview = raw;
+    d.previewKey = stableKey;
+    const preview = d.preview;
     // A loop keeps the window size; a fold or rotation passes through other sizes, so only same-size flips count.
     if (d.key !== key)
         Object.assign(d, { key, pinned: undefined, ttl: undefined, flips: [] });
     if (d.pinned && now >= d.until)
         Object.assign(d, { pinned: undefined, flips: [] });
-    let c = detect(s, preferred, !d.pinned);
-    if (d.mode && c.mode !== d.mode) {
+    let c = detect(s, preferred, !d.pinned, preview);
+    // Halfway through a fold or turn: hidden, and nothing committed, so the landing is taken as a stable change. The
+    // last context's geometry stays whole: mixing its screenWidth with the half-turned width made the page's insets
+    // jump mid-turn (84, 0, 212, 296px on a left column turn, -485px on an unfold; final review, 2026-10-27).
+    const moving = () => ({ ...(d.last ?? c), keyboard: c.keyboard, hidden: "moving", confidence: "moving" });
+    if (settling && inTransit(s)) {
+        Object.assign(d, { moving: true, landKey: undefined, landUntil: undefined });
+        return moving();
+    }
+    // Landed after a transit: hidden until the landing holds LAND_HOLD (the caller re-reads at landUntil).
+    if (settling && d.moving) {
+        if (d.landKey !== stableKey)
+            Object.assign(d, { landKey: stableKey, landAt: now, landUntil: now + LAND_HOLD });
+        if (now < d.landUntil)
+            return moving();
+    }
+    Object.assign(d, { moving: undefined, landKey: undefined, landUntil: undefined });
+    // The preview verdict counts as stable: a preview handed to a tab (Open in Safari) moves at once.
+    if (d.last && c.mode !== d.last.mode && settling && stableKey === d.stableKey && !!d.last.preview === preview) {
+        const { width, height, insetTop, insetBottom, keyboard } = c;
+        return { ...d.last, width, height, insetTop, insetBottom, keyboard, confidence: "held" };
+    }
+    d.stableKey = stableKey;
+    if (d.mode && c.mode !== d.mode && !settling) {
         d.flips = [...d.flips.filter((t) => now - t < FLIP_WINDOW), now];
         if (d.flips.length >= 3) {
             // Doubles only when the loop resumes as the last pin lifts; a later pane move starts from PIN_TTL again.
-            d.ttl = d.ttl && d.until !== undefined && now - d.until < FLIP_WINDOW ? d.ttl * 2 : PIN_TTL;
+            d.ttl = d.ttl && d.until !== undefined && now - d.until < FLIP_WINDOW ? Math.min(d.ttl * 2, PIN_MAX) : PIN_TTL;
             Object.assign(d, { pinned: key, until: now + d.ttl });
-            c = detect(s, preferred, false);
+            c = detect(s, preferred, false, preview);
         }
     }
     d.mode = c.mode;
-    return c;
+    c = { ...c, confidence: settling ? "settling" : "sure" };
+    // A mobile browser's URL bar grows and shrinks the viewport as the page scrolls, while the window keeps its
+    // width and orientation. A desktop window has no such bar: its height is the user's, so it stays current.
+    d.lastKey = key;
+    if (c.device === "desktop")
+        return d.last = c;
+    const h = `${s.innerWidth}${s.outerWidth > s.outerHeight ? "L" : "P"}`, heights = d.heights ??= {};
+    heights[h] = Math.min(heights[h] ?? Infinity, s.innerHeight);
+    return d.last = { ...c, stableHeight: heights[h] };
 }
 /** Inline side drag, like a magnet: the controls resist leaving their edge (rubber band up to MAGNET.hold),
  *  then let go and follow the finger once it pulls MAGNET.release past the start. Released past the middle
@@ -165,18 +371,89 @@ export function magnet(side, dx) {
 }
 /** Width the inline strip takes from the page (same column width as Safari's). */
 export const INLINE_WIDTH = 84;
+/** Where the page goes beside the controls, and the insets left for it to keep clear by (chrome.tsx writes them on
+ *  <html>). In Safari's column without children the document is the page, and Duet owns its layout (`reserve`, the
+ *  default): when the document spans a column on the left (a split pane, which spans one on each side, or a left
+ *  column closed) it is scrolled one column across, so the page is moved right by that column (`shift`, margins on
+ *  <html>) and lands exactly in the visible viewport, beside the controls, with nothing to keep clear (insets 0).
+ *  Before, a page that ignored the insets ran under the controls on the left and left a column-wide gap on the
+ *  right (RegTail, split pane, 2026-10-27). With `reserve: false` the page runs under the column and keeps clear by
+ *  the insets itself. With children the scroller runs on under the column and pads by the insets; an emulated
+ *  column (the site's web Duo) already frames both columns and is never scrolled across. */
+export function pageInsets(o) {
+    const column = o.screenWidth - o.width, split = o.mode === "column" && o.split;
+    if (o.mode === "column" && !o.inner && !o.emulated && o.reserve)
+        return { left: "0px", right: "0px", shift: split || o.side === "left" ? column : 0 };
+    const inset = o.hiddenPreview ? "0px" : o.mode === "strip" ? o.env(o.side) : o.mode === "inline" ? `${INLINE_WIDTH}px` : `${column}px`;
+    const other = (side) => o.mode === "column" ? "0px" : o.env(side);
+    // Without children nothing runs under a right column: the document is laid out in the viewport (simulator,
+    // 2026-10-26: 84px of padding left a 100px gap).
+    const under = o.mode !== "column" || o.inner || o.emulated;
+    return {
+        right: (o.side === "right" || split) && under ? inset : other("right"),
+        left: o.side === "left" || split ? inset : other("left"),
+        shift: 0,
+    };
+}
+/** Closed landscape Safari tab: its column's buttons sit apart from portrait's (SAFARI.landscape). */
+const landscapeColumn = (c) => !c.split && !c.preview && c.screenWidth > c.screenHeight;
 const groupHeight = (n) => DUO.control + (n - 1) * DUO.groupItem;
+/** Safari's column buttons are an exclusion zone like the insets: native chrome always paints over the page, so
+ *  nothing of ours shows over its back + reader rows or its +/tabs pill. `top`: the reader row's bottom plus
+ *  DUO.gap, at its worst-case (island-pushed) position. `bottom`: DUO.gap above the pill. `reach`: how far the
+ *  island can push the rows, so with a bare island the free band starts that much higher; Live Activities, which
+ *  nothing tells the page, take it back. Column mode only; landscape rows are measured with a bare island. */
+export function columnBand(c) {
+    if (c.mode !== "column")
+        return undefined;
+    const rows = SAFARI.rows * (DUO.control + DUO.gap), pill = c.screenHeight - DUO.bottom - SAFARI.pill - DUO.gap;
+    // In-app preview: the gap in its column, from screen points to the page's (the page reaches the screen bottom).
+    if (c.preview) {
+        const y0 = DUO_SIZES[0][1] - c.height;
+        return { top: PREVIEW.gap.top + DUO.gap - y0, bottom: PREVIEW.gap.bottom - DUO.gap - y0, reach: 0 };
+    }
+    if (c.split)
+        return { top: SAFARI.splitTop[c.side] + rows, bottom: pill, reach: c.side === "right" ? DUO.island : 0 };
+    if (landscapeColumn(c))
+        return { top: SAFARI.landscape[c.side].top + rows, bottom: SAFARI.landscape[c.side].pill - DUO.gap, reach: 0 };
+    return { top: DUO.top + DUO.island + rows, bottom: pill, reach: DUO.island };
+}
+/** Morph menu placement: the button grows into a labelled list, outer edge on the button's, opening down from
+ *  its top or up from its bottom. Where it crosses Safari's column it stays inside the column band (flush with
+ *  the column, as Safari's own menus open); a list too tall for that band moves wholly over the page, beside the
+ *  column, where it may rise to the top; one too tall even there caps its height and scrolls. x0/y0: the button's
+ *  top-left, where the morph starts. */
+export function morphBox(c, p, b, n) {
+    const w = MORPH.width, full = 2 * MORPH.pad + n * MORPH.row, x0 = p.left, y0 = b.top + b.height / 2 - DUO.control / 2;
+    const place = (lo, hi) => {
+        const height = Math.min(full, hi - lo), down = y0 >= lo && y0 + height <= hi;
+        return { top: Math.min(Math.max(down ? y0 : y0 + DUO.control - height, lo), hi - height), height };
+    };
+    const flush = c.side === "left" ? p.left : p.left + DUO.control - w;
+    const viewport = [c.insetTop + MORPH.pad, c.height - MORPH.pad];
+    if (p.columnTop !== undefined && p.columnBottom !== undefined && full > p.columnBottom - p.columnTop) {
+        // Beside the column: its page-side edge a pad in from the column's inner edge.
+        const column = c.screenWidth - c.width, left = c.side === "left" ? column + MORPH.pad : c.width - MORPH.pad - w;
+        return { left, width: w, ...place(...viewport), scroll: full > viewport[1] - viewport[0], x0, y0 };
+    }
+    const band = p.columnTop !== undefined && p.columnBottom !== undefined ? [p.columnTop, Math.min(p.columnBottom, viewport[1])] : viewport;
+    return { left: flush, width: w, ...place(...band), scroll: full > band[1] - band[0], x0, y0 };
+}
+/** Island menu placement: the button stretches sideways into a pill as tall as itself, outer edge on the
+ *  button's. In the column it never rises above columnTop. */
+export function islandBox(p, b, n, side) {
+    const w = 2 * ISLAND.pad + n * ISLAND.item, top = Math.max(b.top + b.height / 2 - DUO.control / 2, p.columnTop ?? -Infinity);
+    return { top, left: side === "left" ? p.left : p.left + DUO.control - w, width: w, height: DUO.control, x0: p.left };
+}
 export function plan(c, s) {
     // column: screen coordinates (the layer is in-document), in the band Safari's column never uses: below
     // its back + reader rows at their worst-case (island-pushed) position, above its +/tabs pill. strip and
     // inline: viewport coordinates.
-    const top = c.mode === "strip" ? DUO.top + DUO.island - c.offsetTop
-        : c.mode === "column" && c.split ? SAFARI.splitTop[c.side] + SAFARI.rows * (DUO.control + DUO.gap)
-            : c.mode === "column" ? DUO.top + DUO.island + SAFARI.rows * (DUO.control + DUO.gap)
-                : c.insetTop + DUO.gap;
-    const bottom = c.mode === "strip" ? c.height - DUO.bottom
-        : c.mode === "column" ? c.screenHeight - DUO.bottom - SAFARI.pill - DUO.gap
-            : c.height - Math.max(c.insetBottom, DUO.gap);
+    const col = columnBand(c);
+    // The turned preview's strip is a page band below its native top bar, with the home indicator's inset below.
+    const strip = c.mode === "strip" && !c.preview;
+    const top = col ? col.top : strip ? DUO.top + DUO.island - c.offsetTop : c.insetTop + DUO.gap;
+    const bottom = col ? col.bottom : strip ? c.height - DUO.bottom : c.height - Math.max(c.insetBottom, DUO.gap);
     const centerX = c.side === "left" ? DUO.centerFromEdge : (c.mode === "column" ? c.screenWidth : c.width) - DUO.centerFromEdge;
     const step = DUO.control + DUO.gap;
     // Safari's column band (146pt) holds two separate round buttons: the selected tab and "…" (or the one
@@ -199,7 +476,9 @@ export function plan(c, s) {
         const parts = [back ? DUO.control : 0, primaryTop && primary ? DUO.control : 0, leading ? groupHeight(leading) : 0, actions ? groupHeight(actions) : 0, menuCount() ? DUO.control : 0].filter(Boolean);
         return parts.reduce((a, b) => a + b, 0) + Math.max(0, parts.length - 1) * DUO.gap;
     };
-    while (height() > floor() - top) {
+    // With nothing above it, the low primary slot needs only its own room, not a gap under the stack.
+    const fitsFrom = (t) => height() ? height() <= floor() - t : !(primaryLow && primary) || lowTop >= t;
+    while (!fitsFrom(top)) {
         if (actions)
             actions--;
         else if (leading)
@@ -211,6 +490,27 @@ export function plan(c, s) {
         else
             break;
     }
+    // The free middle of Safari's column: before folding, the primary action and leading items may rise into the
+    // zone the island only takes with Live Activities, the stack packed down onto the tabs so it rises as little as
+    // it can. Only they do: back mirrors Safari's own, and "…" stays under the reader row so its menu opens clear of
+    // Safari's buttons (morphBox).
+    const reachTop = top - (col?.reach ?? 0);
+    const reaches = () => fitsFrom(reachTop) && (!menuCount() || floor() - DUO.control >= top);
+    if (reachTop < top && fitsFrom(top) && !back) {
+        if (s.primary && !primary) {
+            primary = true;
+            if (!reaches())
+                primary = false;
+        }
+        while (leading < s.leading) {
+            leading++;
+            if (!reaches()) {
+                leading--;
+                break;
+            }
+        }
+    }
+    const fits = () => fitsFrom(top) || (reachTop < top && reaches());
     const p = { centerX, left: centerX - DUO.control / 2, menu: { primary: !!s.primary && !primary, back: s.back && !back, leading: s.leading - leading, actions: s.actions - actions } };
     if (s.tabs)
         p.tabs = { top: bottom - bottomH, height: bottomH, min: tabsMin };
@@ -218,8 +518,11 @@ export function plan(c, s) {
         p.searchButton = { top: bottom - DUO.control, height: DUO.control };
     if (primaryLow && primary)
         p.primary = { top: lowTop, height: DUO.control };
-    let y = top;
-    if (height() <= floor() - top) {
+    if (col)
+        Object.assign(p, { columnTop: top, columnBottom: bottom });
+    // Risen into the island's reach: packed down onto the floor instead of hanging from the top.
+    let y = fitsFrom(top) ? top : floor() - height();
+    if (fits()) {
         if (back) {
             p.back = { top: y, height: DUO.control };
             y += step;
@@ -251,7 +554,9 @@ function accessory(c, s, centerX, bottom) {
         return { accessory: { left: c.screenWidth - c.width + DUO.gap, width: c.width - 2 * DUO.gap, top: c.height - DUO.gap - DUO.accessory.height, height: DUO.accessory.height } };
     const floor = c.mode === "column" ? c.height - DUO.gap : bottom;
     // Mirrored on the left: inner edge clear of the column, outer edge DUO.accessory.left from the screen edge.
-    const left = c.side === "left" ? centerX + DUO.control / 2 + DUO.accessory.gapToColumn : DUO.accessory.left;
-    const right = c.side === "left" ? c.width - DUO.accessory.left : c.mode === "column" ? c.width - DUO.gap : centerX - DUO.control / 2 - DUO.accessory.gapToColumn;
+    // In Safari's column it spans the page, a gap from its edge on the column's side.
+    const column = c.screenWidth - c.width;
+    const left = c.mode === "column" && c.side === "left" ? column + DUO.gap : c.side === "left" ? centerX + DUO.control / 2 + DUO.accessory.gapToColumn : DUO.accessory.left;
+    const right = c.mode === "column" && c.side === "left" ? c.screenWidth - DUO.accessory.left : c.side === "left" ? c.width - DUO.accessory.left : c.mode === "column" ? c.width - DUO.gap : centerX - DUO.control / 2 - DUO.accessory.gapToColumn;
     return { accessory: { left, width: right - left, top: floor - DUO.accessory.height, height: DUO.accessory.height } };
 }

package/dist/icons.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const icon = (paths) => function Icon({ size = 22, strokeWidth = 2 }) {
-    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: strokeWidth, strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, children: paths }));
+    return (_jsx("svg", { width: size, height: size, viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: strokeWidth, strokeLinecap: "round", strokeLinejoin: "round", "data-duet-glyph": "", "aria-hidden": true, children: paths }));
 };
 export const ChevronLeft = icon(_jsx("path", { d: "m15 18-6-6 6-6" }));
 export const Ellipsis = icon(_jsxs(_Fragment, { children: [_jsx("circle", { cx: "12", cy: "12", r: "1" }), _jsx("circle", { cx: "19", cy: "12", r: "1" }), _jsx("circle", { cx: "5", cy: "12", r: "1" })] }));

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { Duet, DuoCookie, useDuet, type DuetProps, type DuetItem, type DuetTab } from "./chrome.tsx";
+export { glassTheme, themeVars, type Appearance, type DuetIcons, type DuetTheme } from "./theme.ts";
+export { epoch, readSignals, settling, watchSignals } from "./signals.ts";
 export { bleed, column } from "./layout.ts";
 export { DuetPanes, DuetPaneBar, usePanes, type DuetPanesProps, type DuetPaneBarProps } from "./duet-panes.tsx";
 export { panes, backFrom, type PaneWindow } from "./panes.ts";
-export { browserOf, detect, deviceOf, isDuo, isIOS, isSplit, plan, magnet, DUO, INLINE_WIDTH, MAGNET, WIDE, type Browser, type Context, type Device, type Layout, type Mode, type Plan, type Side, type Signals, type Spec } from "./geometry.ts";
+export { browserOf, detect, deviceOf, isDuo, isIOS, isPreview, isSplit, previewReason, plan, stable, PIN_MAX, PIN_TTL, columnBand, morphBox, islandBox, magnet, pageInsets, DUO, INLINE_WIDTH, MAGNET, WIDE, type Browser, type Context, type Device, type Layout, type Mode, type Plan, type Side, type Signals, type Spec } from "./geometry.ts";

package/dist/index.js

@@ -1,5 +1,7 @@
 export { Duet, DuoCookie, useDuet } from "./chrome.js";
+export { glassTheme, themeVars } from "./theme.js";
+export { epoch, readSignals, settling, watchSignals } from "./signals.js";
 export { bleed, column } from "./layout.js";
 export { DuetPanes, DuetPaneBar, usePanes } from "./duet-panes.js";
 export { panes, backFrom } from "./panes.js";
-export { browserOf, detect, deviceOf, isDuo, isIOS, isSplit, plan, magnet, DUO, INLINE_WIDTH, MAGNET, WIDE } from "./geometry.js";
+export { browserOf, detect, deviceOf, isDuo, isIOS, isPreview, isSplit, previewReason, plan, stable, PIN_MAX, PIN_TTL, columnBand, morphBox, islandBox, magnet, pageInsets, DUO, INLINE_WIDTH, MAGNET, WIDE } from "./geometry.js";

package/dist/signals.d.ts

@@ -0,0 +1,28 @@
+import type { Signals } from "./geometry.ts";
+/** The signals a host page sends into this iframe, if any (see above). */
+export declare const emulatedSignals: () => Signals | null;
+/** The current signals, read from the window (or the emulating host page). Browser only. */
+export declare function readSignals(): Signals;
+/** Geometry after an event is not final: a fold moves outerWidth up to ~2s after the viewport, and nothing fires when
+ *  it lands. So every event starts a settle: poll every `poll` ms until outer, inner and visual sizes hold for `quiet`
+ *  ms, re-reading on each change and once at the end. A page far narrower or wider than its window (more than `lag`
+ *  apart: Safari's column is 84) is a fold caught halfway, so it does not count as holding until `cap`. After `cap` ms
+ *  settling() turns false even if sizes still move, but polling goes on until they hold, so a real feedback loop
+ *  cannot keep restarting the settle. */
+export declare const SETTLE: {
+    readonly poll: 100;
+    readonly quiet: 500;
+    readonly cap: 2000;
+    readonly lag: 100;
+};
+/** Bumped on pageshow and whenever the page becomes visible: the page may now be in another container (the in-app
+ *  preview's "Open in Safari" hands it to a tab without reloading), so stable() decides the preview afresh. */
+export declare const epoch: () => number;
+export declare const settling: () => boolean;
+/** Calls `cb` whenever the signals may have changed, so it can call readSignals() and detect() again: on resize,
+ *  rotation (a turn from one landscape to the other keeps the window size, so screen.orientation too), the keyboard
+ *  (visualViewport), and on pageshow and visibilitychange, as when an in-app preview's "Open in Safari" hands the
+ *  page to a Safari tab without reloading it. Each event, and the call itself (a fresh tab settles with no event),
+ *  starts a settle (SETTLE): `cb` runs at once, on every size change while it polls, and once when sizes hold.
+ *  Returns the unsubscribe. Browser only. */
+export declare function watchSignals(cb: () => void): () => void;