duet-ui 0.4.0-rc.1 → 0.4.0-rc.2

package/README.md

@@ -99,15 +99,37 @@ How a new reading is committed:
 
 Column mode infers from the window geometry that Safari's column is there; it never sees Safari's buttons. The 80 to 88px width difference is Safari's column (84px measured), the height difference is Safari's chrome below the page.
 
-- `position: fixed` content is clipped to the page viewport, but WebKit paints in-document content that overflows the layout viewport into Safari's column. Duet renders the controls in an absolute layer at the top of the document, widens the document by the column's width, keeps the document itself from scrolling (the page scrolls in the inner scroller) and sets `touch-action: pan-y` on `<html>` so the page does not pan sideways. This is observed WebKit behaviour, not a supported API.
+- `position: fixed` content stops at the page viewport (and a fixed box covering the middle of the viewport edge has its colour painted over the column, see [Modals and sheets in column mode](#modals-and-sheets-in-column-mode)), but WebKit paints in-document content that overflows the layout viewport into Safari's column. Duet renders the controls in an absolute layer at the top of the document, widens the document by the column's width, keeps the document itself from scrolling (the page scrolls in the inner scroller) and sets `touch-action: pan-y` on `<html>` so the page does not pan sideways. This is observed WebKit behaviour, not a supported API.
 - Without `children` the document itself scrolls, and the layer follows it on a CSS scroll timeline (`animation-timeline: scroll(root)`). Safari runs the timeline with the scroll, so the controls hold through momentum and through smooth programmatic scrolls (`scrollIntoView({ behavior: "smooth" })`, `scrollTo({ behavior: "smooth" })`): you need no scroll listener and no `behavior: "auto"` workaround. Measured on the simulator: within 1px through flings and at rest, and one frame of up to 7pt at the end of a smooth scroll (a transform set on scroll ran up to 300pt off there). The keyframe ends at `scrollHeight - innerHeight`, Safari's own timeline range, which follows its URL bar as it collapses. Without scroll-timeline support, or when a page reset like `* { animation: none !important }` removes it, Duet falls back to a transform set on scroll, which lags in momentum. Children mode stays the steadier choice.
 - The widened document can pan sideways when a swipe runs off the end of a horizontal scroller (a chip row), since `touch-action` stops at that scroller. Duet pins `scrollX` (0, or the column width when the document spans a left column) on every scroll and sets `overscroll-behavior-x: contain` on all elements at zero specificity (`:where()`), so your own value wins.
 - Touches in the column reach the page but are not hit-tested to Duet's buttons, and Safari usually keeps the touch end. Duet listens for `pointerdown`, finds the button under the touch's coordinates and clicks it, so a column button fires on touch down.
 - Placement comes from constants measured on the iPhone Duo simulator (iOS 27.1) and checked on a device: Safari's back and reader rows at the top of the column, its +/tabs pill at the bottom. A Safari update that moves its buttons or changes this painting behaviour needs new measurements.
 
+### Modals and sheets in column mode
+
+A modal or sheet on the web usually sits on a full-screen scrim: `position: fixed; inset: 0`. In Safari's column on the closed Duo that used to hide Duet's whole column layer, the close button included (#79).
+
+- **What you see:** nothing to handle. While the overlay is open, the controls stay in the column and keep working. Safari's own buttons there are unaffected either way.
+- **Cause:** Safari 26 hit-tests the middle of each viewport edge, 4px in, for a fixed or sticky box (WebKit's `LocalFrameView::fixedContainerEdges`). When one covers that point, Safari paints the box's colour, or plain chrome when the box has a `backdrop-filter`, over everything beyond that edge, Safari's column included. Duet's column layer is in-document content, so it disappears under that fill. Measured on the simulator: a scrim 3px short of the edge still hides the column, 6px short does not, and a scrim of 90% width or 40% height does not.
+- **What Duet does:** in column mode it renders a small fixed guard (`.duet-guard`, 16x64px, transparent, `pointer-events: none`, top `z-index`) straddling that point on each edge that faces a column. Safari's hit test lands on the guard, which is too small to count as a container, so it finds none and keeps painting the column normally. The guard takes no taps and paints nothing.
+- **What you must do:** nothing for visibility. For a native feel, pass `close` to `<Duet>` while the sheet is open, so the controls hold only its close button, and hide the sheet's own X in column mode:
+
+  ```tsx
+  <Duet tabs={tabs} close={open ? { label: "Close", onPress: () => setOpen(false) } : undefined}>
+  ```
+
+  ```css
+  html[data-duet-mode="column"] .sheet-x { display: none; }
+  ```
+
+  The old workaround, making the scrim `position: absolute` in column mode, still works and is no longer needed.
+- **Not covered:** `<dialog>.showModal()` puts its `::backdrop` in the browser's top layer, above any `z-index`, so it still hides the column (checked on the simulator), and the page outside a modal dialog is inert anyway, so Duet's buttons could not take taps. Use a fixed `<div>` scrim (or `dialog.show()` with your own scrim) when you want the column controls. A page box of your own with `z-index: 2147483647` over the middle of the column edge also beats the guard.
+
+Try it on the [site](https://getduet.dev/sheet).
+
 ### Split view
 
-A Safari split-view pane (469x669 window, 385x571 page) has Safari's column on the pane's outer edge, but no web signal says whether the pane is on the left or the right. In column mode Duet widens the document by a column on each side and draws the controls in both; each pane only shows its own column, and a tap there tells Duet which side it was. When a split pane falls back to `inline`, its side is remembered separately from the full-window side, so the user can move the controls next to Safari's column once. `useDuet().split` is true in a split pane.
+A Safari split-view pane (469x669 window, 385x571 page) has Safari's column on the pane's outer edge, but no web signal says whether the pane is on the left or the right. In column mode Duet widens the document by a column on each side and draws the controls in both; each pane only shows its own column, and a tap there tells Duet which side it was. The document is kept scrolled across the left column, so a pane shows document x 84 to 469. When a split pane falls back to `inline`, its side is remembered separately from the full-window side, so the user can move the controls next to Safari's column once. `useDuet().split` is true in a split pane.
 
 ### Side
 
@@ -256,7 +278,17 @@ The page spans the whole window and the controls float over it, so backgrounds r
 - `column(maxWidth, pad)`: a centred reading column. It centres on the whole window and moves aside from the controls only as far as it must. The `duet-column` class does the same in CSS (`--duet-max`, `--duet-pad`).
 - `bleed(pad)`: a full-width band (hero, sticky bar, list row). The band runs under the controls, its content is padded back beside them. `bleed(false)` runs content itself edge to edge (a map, an image). The `duet-bleed` class does the same in CSS.
 
-Duet sets the insets on `<html>` as `--duet-inset-left`, `--duet-inset-right` (the controls' width on their edge; in `column` mode without children the page does not run under a right-hand column, so that inset is 0), `--duet-inset-top` (28px in `strip` mode, for iOS's top blur in Home Screen apps, else 0) and `--duet-inset-bottom` (in `column` mode, Safari's chrome below the page: the page runs on under Safari's floating URL bar, and the scroller ends with that much space so the last content scrolls clear) and `--duet-safe-top-column` (in `column` mode, the top of the part of Safari's column clear of its back and reader buttons: keep popovers that cross the column below it). `--duet-vh` is `stableHeight` in px: size full-screen sections with `min-height: var(--duet-vh, 100svh)` so they keep their height while the URL bar collapses and expands. Inside `<DuetPanes>` each pane gets its own left and right insets: only a pane on the controls' edge is inset. `<html data-duet-mode>` holds the current mode for CSS.
+Duet sets the insets on `<html>` as `--duet-inset-left`, `--duet-inset-right` (the controls' width on their edge; 0 in `column` mode without children, see below), `--duet-inset-top` (28px in `strip` mode, for iOS's top blur in Home Screen apps, else 0) and `--duet-inset-bottom` (in `column` mode, Safari's chrome below the page: the page runs on under Safari's floating URL bar, and the scroller ends with that much space so the last content scrolls clear) and `--duet-safe-top-column` (in `column` mode, the top of the part of Safari's column clear of its back and reader buttons: keep popovers that cross the column below it). `--duet-vh` is `stableHeight` in px: size full-screen sections with `min-height: var(--duet-vh, 100svh)` so they keep their height while the URL bar collapses and expands. Inside `<DuetPanes>` each pane gets its own left and right insets: only a pane on the controls' edge is inset. `<html data-duet-mode>` holds the current mode for CSS.
+
+### Column mode without children: Duet places the page
+
+In `column` mode the controls sit in Safari's column, outside the layout viewport, so a page has nothing to keep clear of. Without `children` Duet places the page itself, so any page, including one that never calls `column()` or `bleed()`, starts just clear of the controls, keeps centred content centred in the space left and is never clipped:
+
+- The insets are 0 and the page's layout viewport is exactly the part of the window beside Safari's column.
+- Where the document spans a left column (split view, the closed Duo turned to 90), Duet keeps it scrolled across and gives `<html>` `margin-left` of the column width and the matching negative `margin-right`, so the page lands in the visible part of the window instead of under the column. `<html data-duet-reserve>` marks this. Do not set `margin` on `<html>` yourself, and do not reset `scrollX`: Duet owns it.
+- `<Duet reserve={false}>` opts out: the page runs under the column as before, and `--duet-inset-left` / `--duet-inset-right` hold the column's width for `column()`, `bleed()` or your own padding.
+
+With `children`, in `inline` and `strip` mode and in the emulated column, the page still runs under the controls and keeps clear through the insets above.
 
 ## Panes
 
@@ -293,6 +325,146 @@ export function Mail() {
 
 Try it on the [site](https://getduet.dev/panes).
 
+## Edge cases
+
+Every iOS and Safari quirk Duet handles, what you would see without the handling, and what is left for you to do. Most need nothing from you. "Without children" means a page that renders `<Duet>` without `children`, so the document itself scrolls.
+
+### Split view pane, or the closed Duo turned left
+
+- **You see:** in column mode without children, the left 84px of the page is clipped, the controls draw over the content and an empty band runs down the right.
+- **Cause:** Safari's column is on the pane's left edge (or on the left when the closed Duo is turned to 90). Duet keeps the document scrolled one column across so the left column can paint, but the page content still starts at x 0, under the column.
+- **Duet does:** places the page itself: `margin-left` of the column width and the matching negative `margin-right` on `<html>`, marked `<html data-duet-reserve>`, with both insets 0. Centred content stays centred, nothing is clipped.
+- **You do:** nothing. Don't set `margin` on `<html>` or reset `scrollX`, Duet owns both. `<Duet reserve={false}>` opts out: the page runs under the column and `--duet-inset-left` / `--duet-inset-right` hold its width for `column()`, `bleed()` or your own padding.
+- **Status:** [#77](https://github.com/JayFarei/duet/issues/77), [PR #78](https://github.com/JayFarei/duet/pull/78), 0.4.0-rc.2. See [Split view](#split-view).
+
+### Rubber band at the top or bottom of the page
+
+- **You see:** in column mode without children, the controls leave their place as a group while the page bounces at either end (sliding up to 160pt over Safari's own column buttons, or out of the column), then come back once it settles.
+- **Cause:** the controls follow the document on a CSS scroll timeline, which is clamped to the scroll range. The iOS rubber band pushes `scrollY` past that range, and the in-document layer moves with the bounce.
+- **Duet does:** while the layer follows the document, `<html>` gets `overscroll-behavior-y: none`, so the document does not rubber-band, like a page with children. Only the Duo column is affected: other modes and other devices keep the bounce.
+- **You do:** nothing. The rule has zero specificity (`:where()`), so a page's own `overscroll-behavior` still wins, and with it the controls ride the bounce again.
+- **Status:** [#76](https://github.com/JayFarei/duet/issues/76), [PR #80](https://github.com/JayFarei/duet/pull/80), 0.4.0-rc.2.
+
+### Full-screen `position: fixed` overlay or modal backdrop
+
+- **You see:** without the handling, in column mode, while a modal or sheet scrim (`position: fixed; inset: 0`) is open, every Duet control in Safari's column disappears, the close button included, so the user has no way to close the sheet from the column.
+- **Cause:** Safari 26 hit-tests a point 4px in from the middle of each viewport edge for a fixed or sticky box and, when one covers it, paints that box's colour over the inset beyond that edge, Safari's column included, instead of the page's in-document content.
+- **Duet does:** in column mode renders `.duet-guard`, a small invisible fixed box (16x64px, `pointer-events: none`, top `z-index`) on each column edge, so that hit test lands on it and the column keeps showing the controls. Your scrim stays `position: fixed`.
+- **You do:** nothing for a fixed `<div>` scrim. `<dialog>.showModal()` is not covered: its `::backdrop` sits in the top layer, above any `z-index`, so use a fixed `<div>` scrim instead. For one X, in the column, pass `close` to `<Duet>` while the sheet is open and hide the sheet's own X in column mode (`html[data-duet-mode="column"] .sheet-close { display: none; }`). See [Modals and sheets in column mode](#modals-and-sheets-in-column-mode).
+- **Status:** [#79](https://github.com/JayFarei/duet/issues/79), [PR #83](https://github.com/JayFarei/duet/pull/83), 0.4.0-rc.2.
+
+### Sideways swipe pans the page into the column
+
+- **You see:** a sideways swipe moves the whole page, controls included, into Safari's column, typically when a swipe runs off the end of a carousel or code block.
+- **Cause:** the controls widen the document by the column's width, so the document can scroll sideways, and `touch-action` on `<html>` stops at a horizontal scroller, whose overscroll chains to the document.
+- **Duet does:** sets `touch-action: pan-y` on `<html>` (and on the inner scroller with children), `overscroll-behavior-x: contain` on every element at zero specificity, and pins `scrollX` (0, or the column width for a left column) on every scroll, instantly, so a page's `scroll-behavior: smooth` can't turn it into a slow creep. Leaving the column resets `scrollX` to 0. Carousels and code blocks still scroll sideways.
+- **You do:** nothing. Your own `overscroll-behavior-x` wins over Duet's.
+- **Status:** 0.2.5 ([PR #26](https://github.com/JayFarei/duet/pull/26)). See [Column mode](#column-mode-how-it-works).
+
+### Back/forward cache restore
+
+- **You see:** after going back to a page (`pageshow` with `persisted`), the controls start in the page and slide into the column over 2 to 3s, seen in a split left pane and on the closed Duo turned left.
+- **Cause:** a back/forward cache restore keeps the page's old state but not the old window, and the `scrollX` pin was a plain `scrollTo`, which a page's `html { scroll-behavior: smooth }` animated and each scroll event restarted.
+- **Duet does:** re-reads the signals on `pageshow`, re-pins `scrollX` with `behavior: "instant"`, and turns transitions off for 1.1s after a restore, as at first mount, so the controls land in place. Normal mode changes keep their ~250ms spring.
+- **You do:** nothing.
+- **Status:** [#66](https://github.com/JayFarei/duet/issues/66), [PR #67](https://github.com/JayFarei/duet/pull/67).
+
+### In-app preview sheet
+
+- **You see:** a link opened from a social or mail app in the in-app Safari preview's page sheet got Safari-tab placement on a real Duo.
+- **Cause:** the sheet is a window inside the closed screen (450x670 on a real Duo), and its bottom safe-area inset reads 0 on the first sample and 34 about 100ms later, so the first reading looks like a tab.
+- **Duet does:** recognises a window inside the closed screen with the column signature and a bottom inset as the preview, and lets a tab verdict rise to preview during a window's first second. Turned sideways in the sheet, where the free gap is about 26pt, it hides the controls (`useDuet().hidden` is `"preview"`) so the preview's own buttons stay usable.
+- **You do:** nothing. Check `useDuet().preview` and `hidden` if your page lays out differently there.
+- **Status:** [#66](https://github.com/JayFarei/duet/issues/66), [PR #67](https://github.com/JayFarei/duet/pull/67), [#69](https://github.com/JayFarei/duet/issues/69). See [In-app preview](#in-app-preview).
+
+### Turning or folding mid-transition
+
+- **You see:** without the handling, the controls flash at the wrong edge during a turn, fold, unfold or split move, the page insets jump (up to 296px on a turn, -485px on an unfold), or Safari zooms the page to fit (scale 1.14).
+- **Cause:** there is no fold signal, and mid-transition the window passes through sizes no landed window has (inner and outer orientations disagree). The window size can land up to ~2s after the viewport, with no event. The column layer still carries the old posture's positions, which widen the document past the new window.
+- **Duet does:** keeps the last placement and hides the controls (`hidden` and `confidence` are `"moving"`) until the window lands and holds for 150ms (`LAND_HOLD`). The insets keep their last values, and the column layer is clipped out of the document width, so it adds no width until the landing. After each event it polls every 100ms until the sizes hold for 500ms, for at most 2s.
+- **You do:** nothing. If your own code reacts to `useDuet()`, ignore readings with `confidence: "moving"`.
+- **Status:** [#68](https://github.com/JayFarei/duet/issues/68), [#69](https://github.com/JayFarei/duet/issues/69), [PR #70](https://github.com/JayFarei/duet/pull/70), 0.4.0-rc.1. See [Which mode](#which-mode).
+
+### Text field focus and the on-screen keyboard
+
+- **You see:** without the handling, focusing an input in column mode makes Safari zoom out (to about 0.94), and the keyboard covers the lower column and the controls in it.
+- **Cause:** the column layer widens the document, and Safari zooms out to that width when a text field takes focus. The keyboard leaves Safari's column in place and only shrinks the visual viewport.
+- **Duet does:** from the moment a field (`:read-write:focus`, so inputs, textareas and `contenteditable`) takes focus, clips the column layer out of the document width and hides it, before the zoom and the keyboard. The keyboard never changes the mode. `useDuet().keyboard` is true while it is up, and `<Duet>` sets `data-keyboard`. In column mode the controls come back when focus leaves.
+- **You do:** nothing. Don't rely on Duet's column controls while the user types.
+- **Status:** [#61](https://github.com/JayFarei/duet/issues/61), [PR #63](https://github.com/JayFarei/duet/pull/63).
+
+### Pinch zoom
+
+- **You see:** nothing changes while the page is zoomed: the mode and placement stay put.
+- **Cause:** with `visualViewport.scale` not 1, `innerWidth` is in zoomed px, so the window signature is unreadable.
+- **Duet does:** keeps the last context (`confidence: "held"`) until the scale returns to 1. Column mode also requires scale 1, so a page that loads zoomed starts `inline`.
+- **You do:** nothing.
+- **Status:** see [Which mode](#which-mode).
+
+### Safari's URL bar collapses
+
+- **You see:** `100vh` and `innerHeight` grow and shrink by 18px while the user scrolls, so full-screen sections jump.
+- **Cause:** Safari collapses its URL bar on scroll, which changes the page height.
+- **Duet does:** reports `useDuet().stableHeight`, the smallest page height seen at this window width and orientation, and sets it as `--duet-vh`. In column mode the page runs on under the floating URL bar, and `--duet-inset-bottom` reserves that space at the end of the scroller.
+- **You do:** size full-screen sections with `min-height: var(--duet-vh, 100svh)`.
+- **Status:** see [Laying out content](#laying-out-content).
+
+### Live Activities and the top band
+
+- **You see:** an empty gap at the top of the strip or column, even when no Live Activity runs.
+- **Cause:** Live Activities grow the Dynamic Island down the strip and push Safari's buttons with it, and a page can't tell whether any are running.
+- **Duet does:** always reserves the worst case measured on device (two activities). `leading` and `primary` may rise into that space before they fold, back, actions and "…" never do. Closed landscape and the in-app preview were measured with a bare island only.
+- **You do:** nothing.
+- **Status:** see [Claimable space](#claimable-space).
+
+### Menus and popovers under Safari's buttons
+
+- **You see:** without the handling, a menu that reaches into the column is drawn under Safari's back, reader or +/tabs buttons.
+- **Cause:** Safari's native chrome always paints over the page, so `z-index` can't help.
+- **Duet does:** keeps its own menus between `columnTop` and Safari's pill, or opens them wholly over the page when they are too tall.
+- **You do:** keep your own popovers that cross the column below `--duet-safe-top-column` (0 outside column mode).
+- **Status:** see [Claimable space](#claimable-space).
+
+### Column buttons fire on touch down
+
+- **You see:** buttons in Safari's column fire as the finger lands and show no native press state.
+- **Cause:** touches in the column reach the page but are not hit-tested to elements outside the viewport, and Safari usually keeps the touch end.
+- **Duet does:** listens for `pointerdown`, finds the button under the touch's coordinates and clicks it. In a split pane, the tap also tells Duet which side the pane is on.
+- **You do:** nothing. Don't put anything that needs a long press or a drag in the column.
+- **Status:** see [Column mode](#column-mode-how-it-works).
+
+### Animations removed by a page reset
+
+- **You see:** in column mode without children, the controls lag behind momentum scroll.
+- **Cause:** a reset like `* { animation: none !important }` (common under reduced motion) removes the scroll timeline the layer follows the document on, and so does a browser without scroll-timeline support.
+- **Duet does:** falls back to a transform set on every scroll event, which lags in momentum.
+- **You do:** exclude `.duet` from the reset, or pass the page as `children` (the steadier choice in any case).
+- **Status:** [PR #56](https://github.com/JayFarei/duet/pull/56). See [Column mode](#column-mode-how-it-works).
+
+### Viewport meta and `viewport-fit=cover`
+
+- **You see:** without the handling, Safari zooms a split pane out to fit the widened document, and `strip` mode is never detected.
+- **Cause:** Safari shrinks the page to fit wide content unless the viewport meta says `shrink-to-fit=no`, and safe-area insets only reach the page with `viewport-fit=cover`. Frameworks add and rewrite viewport metas after load.
+- **Duet does:** appends `shrink-to-fit=no` on import and `viewport-fit=cover` when `<Duet>` mounts, to every viewport meta, and keeps them on metas added or rewritten later. With no viewport meta it adds `width=device-width,initial-scale=1` first.
+- **You do:** nothing, but don't set `viewport-fit=contain` or `shrink-to-fit=yes`: Duet only appends absent keys and leaves your values as they are.
+- **Status:** 0.2.0, 0.2.1. See [Viewport meta](#viewport-meta).
+
+### Mode flips back and forth
+
+- **You see:** without the handling, the controls jump between the column and the page several times a second.
+- **Cause:** column mode can feed back into the signals, for example when Safari zooms the page out to fit the wider document, the column signature disappears, `inline` removes the overflow, and the signature returns.
+- **Duet does:** after 3 mode changes within 2s at the same window size, pauses column mode for 3s, doubling each time the loop resumes right after the pause, up to 60s. Changes while the window is still settling are not counted.
+- **You do:** nothing.
+- **Status:** 0.2.1. See [Oscillation guard](#oscillation-guard).
+
+### Mode detection limits
+
+- **You see:** `inline` where you expected the column or the strip, or a Duo layout on a device that is not a Duo.
+- **Cause:** iOS gives a web page no API for the device, the fold or Safari's buttons. Duet infers everything from window and screen sizes measured on the Duo, safe-area insets, display mode and the user agent.
+- **Duet does:** uses the column only in Safari (not Chrome, Firefox, Edge or other apps' browsers), never in an iframe, and gives in-app web views (a user agent without `Safari/`) `inline`. A Duo whose reported sizes differ (display zoom, a future iOS release) gets `inline`, and an iPad or another device with matching sizes may read as a Duo.
+- **You do:** use `useDuet().duo` to switch to a Duo layout, not as proof of the device. Check `useDuet().browser` to tell why a page is `inline`. For server-rendered layouts, see [Server rendering](#server-rendering-and-hydration).
+- **Status:** 0.2.2. See [Is this an iPhone Duo?](#is-this-an-iphone-duo) and [Which mode](#which-mode).
+
 ## Limitations
 
 - **Duo detection is a heuristic** from screen and window sizes plus the user agent (see above). It can misfire on devices with matching sizes and miss a Duo whose reported sizes differ.

package/dist/chrome.d.ts

@@ -71,6 +71,12 @@ export interface DuetProps<T extends string = string> {
     /** Page content. When given, it scrolls in an inner scroller and the document itself never moves, so
      *  the chrome (and in Safari the column layer) stays still during momentum scroll and rubber-banding. */
     children?: ReactNode;
+    /** Without children, in Safari's column: Duet places the page beside the controls (default `true`). When the
+     *  document spans a column on the left (a split pane, or the closed Duo turned left) the page is moved into the
+     *  visible viewport with margins on `<html>`, and the insets are 0, so the page needs no padding of its own.
+     *  `false` lets the page run under the column instead: it keeps clear by `--duet-inset-left/right`, through
+     *  column() and bleed(). */
+    reserve?: boolean;
 }
 export declare function useDuet(): Context;
 /** Tells the server whether this browser is an iPhone Duo, so it can render the Duo layout from the first byte.

package/dist/chrome.js

@@ -3,7 +3,7 @@ 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 { glassTheme, themeVars } from "./theme.js";
-import { DUO, INLINE_WIDTH, columnBand, isSplit, islandBox, magnet, morphBox, plan, stable } from "./geometry.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";
@@ -201,7 +201,24 @@ function useColumnLayer(on, split, left, column, inColumn) {
             sizes.observe(root);
             sizes.observe(document.body);
         }
-        const follow = () => {
+        // 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.
@@ -243,6 +260,7 @@ function useColumnLayer(on, split, left, column, inColumn) {
             sizes?.disconnect();
             for (const el of els) {
                 el.style.transform = "";
+                el.style.translate = "";
                 el.style.removeProperty("--duet-scroll-max");
                 delete el.dataset.follow;
             }
@@ -385,20 +403,26 @@ export function Duet(props) {
     // 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; a tab has no safe
-        // areas, so the other edge is 0. Without children the document is the page: it is laid out in the viewport
-        // and nothing runs under a right column (simulator, 2026-10-26: 84px of padding left a 100px gap), while a
-        // left column has the document scrolled one column across, so the page runs under it.
+        // 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;
         // 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 inset = ctx.hidden === "preview" ? "0px" : ctx.mode === "strip" ? envInset(ctx.side) : ctx.mode === "inline" ? `${INLINE_WIDTH}px` : `${ctx.screenWidth - ctx.width}px`;
-        const other = (side) => ctx.mode === "column" ? "0px" : envInset(side);
-        const under = ctx.mode !== "column" || inner || !!emulatedSignals();
-        const right = (ctx.side === "right" || split) && under ? inset : other("right"), left = ctx.side === "left" || split ? inset : other("left");
+        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);
@@ -419,7 +443,13 @@ export function Duet(props) {
         document.documentElement.dataset.duetMode = ctx.mode;
         document.documentElement.toggleAttribute("data-duet-emulated", !!emulatedSignals());
         document.documentElement.toggleAttribute("data-duet-split", split);
-    }, [ctx.mode, ctx.side, ctx.hidden === "preview", ctx.screenWidth, ctx.screenHeight, ctx.width, ctx.height, ctx.stableHeight, split, inner]);
+    }, [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");
@@ -600,5 +630,5 @@ export function Duet(props) {
                         // 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: glassTheme(p.appearance, p.dark), 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

@@ -254,9 +254,10 @@ 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. */
+   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
@@ -283,6 +284,22 @@ html[data-duet-mode="column"][data-duet-emulated] .duet-scroller { width: 100%;
    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; }
+/* 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. */
@@ -292,6 +309,11 @@ html:has(:read-write:focus) .duet[data-mode="column"] { overflow: clip; visibili
    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; }

package/dist/geometry.d.ts

@@ -258,6 +258,31 @@ export declare function magnet(side: Side, dx: number): {
 };
 /** Width the inline strip takes from the page (same column width as Safari's). */
 export declare 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 declare function pageInsets(o: {
+    mode: Mode;
+    side: Side;
+    split: boolean;
+    screenWidth: number;
+    width: number;
+    hiddenPreview: boolean;
+    inner: boolean;
+    emulated: boolean;
+    reserve: boolean;
+    env: (side: Side) => string;
+}): {
+    left: string;
+    right: string;
+    shift: number;
+};
 export interface Spec {
     back: boolean;
     leading: number;

package/dist/geometry.js

@@ -371,6 +371,30 @@ 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;

package/dist/index.d.ts

@@ -4,4 +4,4 @@ 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, isPreview, isSplit, previewReason, plan, stable, PIN_MAX, PIN_TTL, columnBand, morphBox, islandBox, 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

@@ -4,4 +4,4 @@ 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, isPreview, isSplit, previewReason, plan, stable, PIN_MAX, PIN_TTL, columnBand, morphBox, islandBox, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duet-ui",
-  "version": "0.4.0-rc.1",
+  "version": "0.4.0-rc.2",
   "description": "Native-feeling controls for React web apps on the foldable iPhone: the side strip, Safari's column, split view and Home Screen apps.",
   "license": "MIT",
   "type": "module",