duet-ui 0.3.0 → 0.4.0-rc.2

package/dist/geometry.d.ts

@@ -1,12 +1,12 @@
 /** strip: Home Screen web app, iOS gives us the right-hand strip.
- *  column: Safari tab, closed portrait or a split-view pane; Safari owns the strip and we paint into the
- *  free space of its column (an undocumented WebKit behaviour, so only when every signal matches).
- *  inline: anything else (landscape, open posture full width, keyboard up, other browsers); a right-edge
- *  strip inside the page viewport. */
+ *  column: Safari tab, closed (portrait or landscape) or a split-view pane; Safari owns the strip and we paint
+ *  into the free space of its column (an undocumented WebKit behaviour, so only when every signal matches).
+ *  inline: anything else (open posture full width, other browsers); a right-edge strip inside
+ *  the page viewport. */
 export type Mode = "strip" | "column" | "inline";
 /** Which screen edge the controls hug. strip: wherever iOS puts the strip (its safe-area inset). column:
- *  always right, Safari owns it. inline: the user's choice; no API tells a split-view pane which side of
- *  the screen it is on. */
+ *  wherever Safari puts its column: right in portrait, the side the closed Duo is turned to in landscape.
+ *  inline: the user's choice; no API tells a split-view pane which side of the screen it is on. */
 export type Side = "left" | "right";
 export declare const DUO: {
     /** Strip centre line, from the right screen edge. */
@@ -49,6 +49,21 @@ export declare const SAFARI: {
         readonly left: 23.5;
         readonly right: number;
     };
+    /** 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. */
+    readonly landscape: {
+        readonly left: {
+            readonly top: 81.5;
+            readonly pill: 327;
+        };
+        readonly right: {
+            readonly top: 23.5;
+            readonly 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). */
@@ -84,12 +99,22 @@ export interface Signals {
      *  emulator's signals) restricts nothing. */
     userAgent?: string;
     touchPoints?: number;
+    /** screen.orientation.angle: in closed landscape, which way the Duo is turned and so which side Safari's column
+     *  is on (90: left, 270: right). Unknown keeps landscape inline. */
+    angle?: number;
+    /** visualViewport.scale: above 1 under pinch zoom, when innerWidth is in zoomed px and says nothing about the
+     *  column. Unknown counts as 1. */
+    scale?: number;
 }
 export interface Context {
     mode: Mode;
     side: Side;
     width: number;
     height: number;
+    /** The smallest `height` seen at this width and orientation, like CSS `100svh`: it ignores Safari's URL bar
+     *  collapsing and expanding mid-scroll, so content sized from it does not jump. On a desktop it is `height`.
+     *  Also set as `--duet-vh` (px). From `detect` alone (no history) it is `height`; `useDuet` remembers. */
+    stableHeight: number;
     /** Screen-y minus viewport-y (status area above a standalone viewport). */
     offsetTop: number;
     /** strip: screen size. column: Safari window size. inline: safe-area insets top/bottom. */
@@ -99,6 +124,19 @@ export interface Context {
     insetBottom: number;
     /** In-app Safari preview (SFSafariViewController, opened from a social or mail app). */
     preview?: boolean;
+    /** The on-screen keyboard is up (visual viewport shorter than the page). The mode stays as it was; in column
+     *  mode the controls hide until it goes down. */
+    keyboard?: boolean;
+    /** From stable() only. "sure": nothing is moving. "settling": the window is still settling after an event, so
+     *  the mode may still change. "held": the last committed context, kept while the page is pinch-zoomed or while a
+     *  drifting signal (viewport height) alone asks for another mode before the window settles. */
+    confidence?: "sure" | "settling" | "held" | "moving";
+    /** The controls are not drawn (the page keeps its full width, no inset). "moving": a fold, unfold or turn is
+     *  caught halfway (stable() only, see inTransit), so the controls hide for those frames instead of showing in a
+     *  place that is right for neither posture. "preview": the in-app preview turned to landscape, whose column has no
+     *  room for a button and where an inline strip would cover the page (docs/research-notes.md, "Preview placement in
+     *  the gap"); the preview's own back and close buttons remain, and Duet's return in portrait or in a tab. */
+    hidden?: "moving" | "preview";
     /** "wide" when the page has room for two panes side by side (the open Duo, full width), else "narrow"
      *  (closed, split view, closed landscape). From the window width, not the posture. */
     layout: Layout;
@@ -118,6 +156,8 @@ export type Layout = "narrow" | "wide";
 /** Page width from which two panes fit. The page spans the window, controls floating over it: the open Duo gives
  *  951, a split-view pane 385, closed landscape 594, closed Safari 382. */
 export declare const WIDE = 600;
+/** Why the signals read as the in-app preview, for probes and logs; undefined when they do not. */
+export declare function previewReason(s: Signals): string | undefined;
 export declare const isPreview: (s: Signals) => boolean;
 export declare const isDuo: (s: Signals) => boolean;
 /** iOS has no model in its UA, so the sizes above say Duo; the UA says iPhone. Safari's "Request Desktop Website"
@@ -136,8 +176,18 @@ export declare function deviceOf(s: Signals): Device;
  *  (device probe 2026-10-25: screenX, availLeft, insets, visualViewport and touch screenX read the same in both),
  *  though Safari's column sits on the pane's outer edge. So the inline side is remembered apart for split view. */
 export declare const isSplit: (s: Signals) => boolean;
-/** preferred: the side the user picked for inline controls, if any. */
-export declare function detect(s: Signals, preferred?: Side, allowColumn?: boolean): Context;
+/** 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 declare const keyboardUp: (s: Signals) => boolean;
+/** 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 declare function detect(s: Signals, preferred?: Side, allowColumn?: boolean, preview?: boolean): Context;
+/** 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 declare function inTransit(s: Signals): boolean;
 /** Mode flips are a feedback loop when the layout of one mode changes the signals into the other (the
  *  column layer's overflow resizing Safari's viewport). Three flips within FLIP_WINDOW pin the page to inline.
  *  Flips only count while the window keeps its size. The pin lifts when the window changes size, or after `until`: moving a split-view pane to the other side
@@ -150,9 +200,49 @@ export interface Damper {
     pinned?: string;
     until?: number;
     ttl?: number;
+    /** Smallest viewport height per width and orientation (Context.stableHeight). */
+    heights?: Record<string, number>;
+    /** Sticky in-app preview verdict, and the window it was taken in. */
+    preview?: boolean;
+    previewKey?: string;
+    previewAt?: number;
+    /** Last context returned, the stable signals it was committed under, and its window (outer size). */
+    last?: Context;
+    stableKey?: string;
+    lastKey?: string;
+    /** A fold or turn was caught halfway, and the landing (its stable signals, first seen at landAt) must hold until
+     *  landUntil before the controls show (LAND_HOLD). */
+    moving?: boolean;
+    landKey?: string;
+    landAt?: number;
+    landUntil?: number;
 }
 export declare const PIN_TTL = 3000;
-export declare function stable(d: Damper, s: Signals, preferred: Side | undefined, now: number): Context;
+/** Longest pin: a loop that keeps resuming doubles the wait up to this. */
+export declare 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 declare 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 declare 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 declare function stable(d: Damper, s: Signals, preferred: Side | undefined, now: number, settling?: boolean, epoch?: number): Context;
 /** 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
  *  of the viewport after letting go, they switch sides; otherwise they snap back. `dx` is the finger's
@@ -168,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;
@@ -222,5 +337,42 @@ export interface Plan {
         top: number;
         height: number;
     };
+    /** Column mode: the band clear of Safari's column buttons (columnBand). Menus crossing the column stay inside
+     *  it; only leading items and the primary action may rise above columnTop, into the island's reach. */
+    columnTop?: number;
+    columnBottom?: number;
 }
+/** 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 declare function columnBand(c: Context): {
+    top: number;
+    bottom: number;
+    reach: number;
+} | undefined;
+/** 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 declare function morphBox(c: Context, p: Plan, b: Box, n: number): {
+    scroll: boolean;
+    x0: number;
+    y0: number;
+    top: number;
+    height: number;
+    left: number;
+    width: 240;
+};
+/** 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 declare function islandBox(p: Plan, b: Box, n: number, side: Side): {
+    top: number;
+    left: number;
+    width: number;
+    height: 49;
+    x0: number;
+};
 export declare function plan(c: Context, s: Spec): Plan;