@swiftbrowser/web 0.9.3 → 0.9.5

package/README.md

@@ -247,7 +247,38 @@ chrome, `#screen` fills `100dvw × 100dvh` at (0, 0), the layout environment's
 `getComputedStyle` (`renderer.setSafeArea`). They are non-zero only in
 standalone (home screen) mode or landscape, which is what a native app would
 get. `resize`, `orientationchange` and `visualViewport` resizes re-run the
-engine (debounced 100ms, `renderer.viewportChanged`). The color scheme follows
+engine (debounced 100ms, `renderer.viewportChanged`). The on-screen keyboard
+does not resize `#screen` in iOS Safari (nor in a browser whose
+`interactive-widget` is `resizes-visual`): the layout viewport keeps its
+height and the browser shrinks (and pans) the visual viewport instead. (A
+browser that does shrink the layout viewport for the keyboard goes through
+the resize path above, and measures no keyboard.) `watchKeyboard` measures the
+keyboard as the layout viewport's height less the visual one's, on every
+`visualViewport` resize or scroll (once per frame, not debounced: the iOS
+keyboard animates over a quarter of a second). The layout viewport's height
+is `#device`'s (`100dvh`), not `window.innerHeight`, which iOS Safari shrinks
+to the visual viewport's height while the keyboard is up. The browser's pan
+to the focused field is not subtracted (Safari pans by the keyboard's whole
+height for a field at the screen's bottom, which would read as no keyboard)
+but undone: the page is scrolled back to its origin once the pan has held
+still for a few frames, since Safari animates it with the keyboard's slide
+and scrolling against that showed as a judder. Better still, the pan
+mostly never happens: Safari pans only when the keyboard would cover the
+field, so on focus the keyboard's last measured height (kept per layout
+height in `localStorage`, so the next page load has it too) is reported at
+once and the content is laid out above the keyboard before it shows; the
+measurement then confirms or corrects it, and a reading of 0 in the second
+after the focus is the keyboard not up yet. When the field loses focus and
+no other text input takes it, 0 is reported as the keyboard starts down.
+For a second after a text input gains or loses focus the viewport is read
+every frame as well, in case its events come late or not at all;
+`?debug=viewport` shows the numbers read, over the app, for checking a
+phone's browser. The height goes to
+`renderer.setKeyboard`, which the engine takes as a bottom safe-area inset
+(`LayoutEnvironment.keyboard`; docs/ops-protocol.md, `ignoresKeyboard`): a
+field or a chat's composer rises above the keyboard and a scroll view
+anchored to its end keeps the last line in view, as on iOS, while a tab bar
+under the keyboard stays put. The color scheme follows
 `prefers-color-scheme` (and its changes), the Dynamic Type size is `large`, and
 the `environment` event carries both as usual. `touch-action: manipulation`
 and `-webkit-text-size-adjust: 100%` stop double-tap zoom and text inflation;
@@ -292,6 +323,25 @@ remains for the landing page and for `/app/` without a parameter. In the
 `/manifest.webmanifest` is the app's, and the page is titled by the app's
 display name alone.
 
+## Browser history
+
+`src/browserHistory.ts` mirrors the app's navigation in the browser's history
+on the app page: pushing a screen or presenting a sheet adds an entry, and the
+browser's back (a phone's edge swipe, the toolbar button, Alt+Left) pops or
+dismisses it through the same `tap` the bar's back button and the sheet's
+scrim send, so Swift's state stays the source of truth. A pop the app makes
+itself takes the history back with it, and forward returns to the entry that
+matches rather than re-pushing. Depth is read from the DOM after every
+`commit`: the presented sheets plus the pushed screens of each visible stack
+(the selected tab's, both columns of a split view, the top sheet's). The URL
+is left alone. While it is on, the renderer's own edge swipe ignores touch and
+pen: the browser's edge swipe is the swipe back, and it arrives as a
+`popstate` (a mouse drag from the edge still pops through the renderer).
+Its own `history.go` after a pop the app made itself is remembered until the
+`popstate` lands, so commits meanwhile do not go back again.
+An island has it on by default and opts out with `mount(..., { history: false })`
+(`<SwiftUIView history={false}>` in @swiftbrowser/react).
+
 ## Deploying (Cloudflare Pages)
 
 `npm run build` writes a static site to `dist/`: `index.html`, `app/index.html`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.9.3",
+  "version": "0.9.5",
   "type": "module",
   "description": "SwiftBrowser web renderer and dev server: applies render ops from a Swift/Wasm app to the DOM inside an iPhone frame.",
   "repository": {

package/src/browserHistory.ts

@@ -0,0 +1,268 @@
+/**
+ * The browser's history as the app's navigation: pushing a screen or
+ * presenting a sheet adds a history entry, and the browser's back (a
+ * phone's edge swipe, the toolbar button, Alt+Left) pops or dismisses it,
+ * as the bar's own back button would. Forward cannot re-push a screen, so a
+ * forward step lands back where the app is.
+ *
+ * Depth is read from the DOM after every commit: the presented sheets, plus
+ * the pushed screens of every visible stack (the selected tab's, both
+ * columns of a split view, the top sheet's). Pops go through the same event
+ * the back button and the scrim send, so the app's own state stays the
+ * source of truth; the page's URL is never touched, and an app that maps
+ * screens to paths should set them with `replaceState` on the entry the
+ * renderer made.
+ *
+ * A two-column split view pushes nothing when its sidebar's selection
+ * changes, so that is an entry of its own: choosing another sidebar row
+ * (one the selection moves to, not the first choice) adds one, and back or
+ * forward taps the row the entry recorded, through the same `tap` a finger
+ * sends. In a compact width the selection pushes the detail, a level like
+ * any other.
+ *
+ * While enabled, the renderer's own edge swipe to pop is off for touch and
+ * pen: the browser's edge swipe (Safari's, Android's back gesture) is the
+ * swipe back, and it lands here as a `popstate`. A mouse drag from the edge
+ * still pops through the renderer, since no browser turns one into history.
+ */
+import type { Renderer } from './renderer';
+
+interface HistoryState {
+  /** Our marker; entries without it belong to the page or the app. */
+  sbHistory: true;
+  /** How many levels (screens and sheets) are above the base in this entry. */
+  sbDepth: number;
+  /** The selected sidebar rows of the visible two-column split views (`sbId`s, comma-separated; absent or empty for none). */
+  sbSelection?: string;
+}
+
+/** What the renderer's elements need to say for this to read them (`sbId`, `sbDepth` datasets). */
+const stateOf = (value: unknown): HistoryState | null => (typeof value === 'object' && value !== null && (value as HistoryState).sbHistory === true ? (value as HistoryState) : null);
+
+function shown(win: Window, el: HTMLElement): boolean {
+  if (el.hidden || el.getClientRects().length === 0) return false;
+  return win.getComputedStyle(el).visibility !== 'hidden';
+}
+
+export class BrowserHistory {
+  private readonly win: Window;
+  /** Levels the latest `popstate` still asks to dismiss, one commit at a time. */
+  private pendingPops = 0;
+  /** `popstate` events to ignore: the ones our own `history.go` causes. */
+  private ignorePops = 0;
+  /**
+   * The depth our own `history.go` is travelling to while its `popstate` is
+   * still on its way (`go` is asynchronous): commits meanwhile compare
+   * against it, so a second commit does not go back a second time.
+   */
+  private movingTo: number | null = null;
+  private movingTimer: ReturnType<typeof setTimeout> | null = null;
+  /** A `popstate` asked for the entry's sidebar selection: the change it brings is recorded, not pushed. */
+  private restoringSelection = false;
+  private enabled = false;
+
+  constructor(
+    private readonly renderer: Renderer,
+    private readonly root: HTMLElement,
+    win: Window = window,
+  ) {
+    this.win = win;
+  }
+
+  /** Marks the current entry as the base and starts mirroring pushes and pops. */
+  enable(): void {
+    if (this.enabled) return;
+    this.enabled = true;
+    const current = stateOf(this.win.history.state);
+    if (!current) this.win.history.replaceState({ ...(this.win.history.state ?? {}), ...this.entry(0, this.selection()) }, '');
+    this.renderer.interaction.nativeBackGesture = true;
+    this.root.addEventListener('sb:commit', this.onCommit);
+    this.win.addEventListener('popstate', this.onPopState);
+    this.sync();
+  }
+
+  dispose(): void {
+    if (!this.enabled) return;
+    this.enabled = false;
+    this.renderer.interaction.nativeBackGesture = false;
+    if (this.movingTimer) clearTimeout(this.movingTimer);
+    this.movingTo = null;
+    this.root.removeEventListener('sb:commit', this.onCommit);
+    this.win.removeEventListener('popstate', this.onPopState);
+  }
+
+  /** The levels above the base the app shows now: sheets, plus pushed screens in each visible stack of the top layer. */
+  depth(): number {
+    const sheets = this.sheets();
+    const top = sheets.at(-1) ?? this.root;
+    let depth = sheets.length;
+    for (const stack of this.stacks(top)) depth += this.topDepth(stack);
+    return depth;
+  }
+
+  /** The selected sidebar rows of the visible two-column split views, as an entry records them. */
+  selection(): string {
+    const ids: string[] = [];
+    for (const split of this.root.querySelectorAll<HTMLElement>('.sb-navsplit')) {
+      if (!shown(this.win, split)) continue;
+      // The sidebar column is the first stack; its selectable rows carry the selection.
+      const sidebar = split.querySelector<HTMLElement>('.sb-navstack');
+      if (!sidebar) continue;
+      for (const row of sidebar.querySelectorAll<HTMLElement>('.sb-listrow[data-sb-selectable][data-sb-selected]')) {
+        const id = row.dataset['sbId'];
+        if (id !== undefined) ids.push(id);
+      }
+    }
+    return ids.join(',');
+  }
+
+  /** Taps the sidebar rows an entry recorded as selected that are not selected now; false when none can be. */
+  private selectRows(recorded: string): boolean {
+    const current = new Set(this.selection().split(',').filter(Boolean));
+    let tapped = false;
+    for (const id of recorded.split(',').filter(Boolean)) {
+      if (current.has(id)) continue;
+      const row = this.root.querySelector<HTMLElement>(`.sb-listrow[data-sb-selectable][data-sb-id="${id}"]`);
+      if (!row || !shown(this.win, row)) continue;
+      this.renderer.tap(Number(id));
+      tapped = true;
+    }
+    return tapped;
+  }
+
+  private sheets(): HTMLElement[] {
+    return [...this.root.querySelectorAll<HTMLElement>(':scope > .sb-sheet')].filter((sheet) => shown(this.win, sheet));
+  }
+
+  /** The visible navigation stacks within `container`, not those inside a deeper sheet. */
+  private stacks(container: HTMLElement): HTMLElement[] {
+    return [...container.querySelectorAll<HTMLElement>('.sb-navstack')].filter((stack) => shown(this.win, stack) && stack.closest('.sb-sheet') === (container.classList.contains('sb-sheet') ? container : null));
+  }
+
+  private topScreen(stack: HTMLElement): HTMLElement | null {
+    const screens = stack.querySelectorAll<HTMLElement>(':scope > .sb-slot > .sb-navscreen');
+    return screens.length ? screens[screens.length - 1]! : null;
+  }
+
+  private topDepth(stack: HTMLElement): number {
+    const top = this.topScreen(stack);
+    return top ? Number(top.dataset['sbDepth'] ?? '0') || 0 : 0;
+  }
+
+  /** Asks the app to dismiss one level: the top sheet when nothing is pushed inside it, else the deepest visible stack's top screen. */
+  private dismissOne(): boolean {
+    const sheets = this.sheets();
+    const top = sheets.at(-1) ?? this.root;
+    const stacks = this.stacks(top)
+      .map((stack) => ({ stack, depth: this.topDepth(stack) }))
+      .filter((s) => s.depth > 0)
+      .sort((a, b) => b.depth - a.depth);
+    const deepest = stacks[0];
+    if (deepest) {
+      const screen = this.topScreen(deepest.stack);
+      const id = Number(screen?.dataset['sbId']);
+      if (!Number.isInteger(id)) return false;
+      this.renderer.tap(id); // what the back button sends
+      return true;
+    }
+    const sheet = sheets.at(-1);
+    const id = Number(sheet?.dataset['sbId']);
+    if (!Number.isInteger(id)) return false;
+    this.renderer.tap(id); // a dismiss request, as the scrim's tap
+    return true;
+  }
+
+  private recorded(): number {
+    return this.movingTo ?? stateOf(this.win.history.state)?.sbDepth ?? 0;
+  }
+
+  private recordedSelection(): string {
+    return stateOf(this.win.history.state)?.sbSelection ?? '';
+  }
+
+  private entry(depth: number, selection: string): HistoryState {
+    return selection ? { sbHistory: true, sbDepth: depth, sbSelection: selection } : { sbHistory: true, sbDepth: depth };
+  }
+
+  /** Our own `history.go`, remembered until its `popstate` lands (or a moment passes without one: a `go` past the ends fires none). */
+  private go(delta: number, to: number): void {
+    this.ignorePops += 1;
+    this.movingTo = to;
+    if (this.movingTimer) clearTimeout(this.movingTimer);
+    this.movingTimer = setTimeout(() => {
+      if (this.movingTo === null) return;
+      this.movingTo = null;
+      this.ignorePops = Math.max(0, this.ignorePops - 1);
+    }, 1000);
+    this.win.history.go(delta);
+  }
+
+  private arrived(): void {
+    this.movingTo = null;
+    if (this.movingTimer) clearTimeout(this.movingTimer);
+    this.movingTimer = null;
+  }
+
+  private readonly onCommit = (): void => this.sync();
+
+  /** After a commit: new levels get entries; levels the app dismissed itself take the history back with them; a moved sidebar selection is an entry too. */
+  sync(): void {
+    if (!this.enabled) return;
+    const depth = this.depth();
+    const recorded = this.recorded();
+    const selection = this.selection();
+    if (this.pendingPops > 0) {
+      // Dismissing for a `popstate`: the entry already names the target depth.
+      if (depth > recorded) {
+        if (!this.dismissOne()) this.pendingPops = 0;
+        else this.pendingPops -= 1;
+      } else this.pendingPops = 0;
+      return;
+    }
+    if (depth > recorded) {
+      for (let level = recorded + 1; level <= depth; level++) this.win.history.pushState(this.entry(level, selection), '');
+    } else if (depth < recorded) {
+      // The app popped or dismissed on its own (back button, swipe, code): leave those entries.
+      this.go(depth - recorded, depth);
+    } else if (this.movingTo === null && selection !== this.recordedSelection()) {
+      // The same levels, another sidebar selection. The first choice (from
+      // none) and the one a `popstate` asked for belong to the entry at hand;
+      // a move from one row to another is a new entry.
+      const history = this.win.history;
+      if (this.restoringSelection || !this.recordedSelection()) {
+        const { sbSelection: _, ...rest } = (history.state ?? {}) as Partial<HistoryState>;
+        history.replaceState({ ...rest, ...this.entry(depth, selection) }, '');
+      } else history.pushState(this.entry(depth, selection), '');
+    }
+    this.restoringSelection = false;
+  }
+
+  private readonly onPopState = (event: PopStateEvent): void => {
+    if (this.ignorePops > 0) {
+      this.ignorePops -= 1;
+      this.arrived();
+      return;
+    }
+    const target = stateOf(event.state);
+    if (!target) return; // an entry of the page's own (before the base, or the app's router): not ours
+    const depth = this.depth();
+    if (target.sbDepth < depth) {
+      // Back: dismiss one level now, the rest as each commit lands.
+      this.pendingPops = depth - target.sbDepth;
+      if (!this.dismissOne()) this.pendingPops = 0;
+      else this.pendingPops -= 1;
+    } else if (target.sbDepth > depth) {
+      // Forward: a screen cannot be re-pushed; return to the entry that matches.
+      this.go(depth - target.sbDepth, depth);
+      return;
+    }
+    // The entry's sidebar selection, where it differs: tap the rows it names
+    // (back and forward alike, a row can be chosen again). What the app
+    // shows after that is recorded on this entry rather than pushed.
+    const recorded = target.sbSelection ?? '';
+    if (recorded !== this.selection()) {
+      this.restoringSelection = true;
+      this.selectRows(recorded);
+    }
+  };
+}

package/src/deviceMode.ts

@@ -85,3 +85,242 @@ export function watchViewport(onChange: () => void, debounceMs = 100): () => voi
     vv?.removeEventListener('resize', schedule);
   };
 }
+
+/** What `keyboardHeight` reads of the visual viewport (`window.visualViewport`). */
+export interface VisualViewportLike {
+  height: number;
+  scale: number;
+}
+
+/**
+ * The height of the on-screen keyboard over the bottom of the layout
+ * viewport, in CSS px: 0 while it is down. `layoutHeight` is the layout
+ * viewport's height: the height of the root element that fills it
+ * (`100dvh`), not `window.innerHeight`, which iOS Safari shrinks to the
+ * visual viewport's height while the keyboard is up (an iPhone read inner
+ * 352, visual 352, and the root still 692 tall). iOS Safari (and a browser
+ * whose `interactive-widget` is `resizes-visual`) does not shrink the layout
+ * viewport for the keyboard; it shrinks the visual viewport to the part of
+ * the screen above the keyboard and pans it down the page so the focused
+ * field shows. The keyboard is therefore the difference of the two heights.
+ * The pan (`offsetTop`) is not subtracted: Safari pans by the keyboard's
+ * full height when the field is at the bottom of the screen, which would
+ * read as no keyboard at all; `watchKeyboard` undoes the pan instead. A
+ * browser that shrinks the layout viewport for the keyboard measures 0 here
+ * and resizes the root. A pinch zoom shrinks the visual viewport too, so a
+ * scale other than 1 counts as no keyboard.
+ */
+export function keyboardHeight(layoutHeight: number, vv: VisualViewportLike | null | undefined): number {
+  if (!vv || !Number.isFinite(vv.height) || !Number.isFinite(layoutHeight) || Math.abs((vv.scale || 1) - 1) > 0.01) return 0;
+  const covered = layoutHeight - vv.height;
+  return covered > 0 ? Math.round(covered) : 0;
+}
+
+export interface WatchKeyboardOptions {
+  /** The element that fills the layout viewport (`#device`): its height is the layout viewport's. */
+  root: HTMLElement;
+  /** Gets every reading (the `?debug=viewport` readout). */
+  onRead?: ((reading: ViewportReading) => void) | undefined;
+  /** Where the last measured height is kept for the next focus (and the next page load); `localStorage` by default, null for none. */
+  storage?: Pick<Storage, 'getItem' | 'setItem'> | null | undefined;
+}
+
+/**
+ * Call `onChange` with the keyboard's height (`keyboardHeight`) whenever the
+ * visual viewport resizes or pans, once per animation frame: the iOS
+ * keyboard animates over a quarter of a second and sends several resizes,
+ * so unlike `watchViewport` this does not debounce. A text input gaining or
+ * losing focus is what raises or drops the keyboard, so for a second after
+ * either the viewport is read every frame as well, in case its events come
+ * late or not at all.
+ *
+ * The browser pans the page to the focused field when the keyboard would
+ * cover it, which would leave the top of the screen (the navigation bar)
+ * scrolled off, and it does so while the keyboard slides, so undoing the
+ * pan as it happens shows as a judder. Better that it never happens: on
+ * focus the keyboard's last measured height (kept per layout height, in
+ * `localStorage` so the next page load has it too) is reported at once,
+ * before the keyboard shows, so the app has laid its content out above the
+ * keyboard, field included, by the time the browser decides whether to pan.
+ * The measurement then confirms or corrects it; a reading of 0 during the
+ * second after the focus is the keyboard not up yet, not a correction. A
+ * pan that does happen (the first focus ever, a keyboard taller than the
+ * last) is scrolled back, once it has held still for a few frames: Safari
+ * animates its pan with the keyboard's slide, and scrolling against that
+ * animation showed as a judder. (Safari's pan is a window scroll, `scrollY`
+ * 340 for a 340 keyboard on an iPhone; moving the root to counter a pan read
+ * from `visualViewport.offsetTop` was tried and dipped the content mid-slide
+ * on passing offsets.) When the field loses focus and no other text input
+ * has it, 0 is reported at once too, as the keyboard starts down. Returns a
+ * function that stops listening.
+ */
+export function watchKeyboard(onChange: (height: number) => void, options: WatchKeyboardOptions): () => void {
+  const vv = window.visualViewport;
+  if (!vv) return () => {};
+  const { root, onRead } = options;
+  const storage = options.storage === undefined ? safeLocalStorage() : options.storage;
+  let frame: number | undefined;
+  let last = 0;
+  /** While set, the viewport is read every frame until this time (performance.now() ms). */
+  let pollUntil = 0;
+  /** While set, a reading of 0 is the keyboard not up yet (a focus just reported the known height). */
+  let anticipatingUntil = 0;
+  let blurTimer: ReturnType<typeof setTimeout> | undefined;
+  let lastEvent = '';
+  /** The pan read last frame (`scrollY:offsetTop`) and for how many frames in a row it has held. */
+  let lastPan = '';
+  let panHeld = 0;
+  const storageKey = (): string => `sb-keyboard-${root.clientHeight}`;
+  const knownHeight = (): number => {
+    const value = Number(storage?.getItem(storageKey()) ?? 0);
+    return Number.isFinite(value) && value > 0 ? value : 0;
+  };
+  const remember = (height: number): void => {
+    try {
+      storage?.setItem(storageKey(), String(height));
+    } catch {
+      // Storage full or blocked: the next focus measures instead of anticipating.
+    }
+  };
+  const report = (height: number): void => {
+    if (height === last) return;
+    last = height;
+    onChange(height);
+  };
+  const update = (): void => {
+    frame = undefined;
+    const layoutHeight = root.clientHeight;
+    const height = keyboardHeight(layoutHeight, vv);
+    const up = height > 0 || (last > 0 && performance.now() < anticipatingUntil);
+    const panNow = `${Math.round(window.scrollY)}:${Math.round(vv.offsetTop)}`;
+    panHeld = panNow === lastPan ? panHeld + 1 : 0;
+    lastPan = panNow;
+    const settled = panHeld >= PAN_SETTLE_FRAMES;
+    if (up && settled && (window.scrollY !== 0 || window.scrollX !== 0)) window.scrollTo(0, 0);
+    onRead?.({
+      layoutHeight,
+      innerHeight: window.innerHeight,
+      visualHeight: vv.height,
+      scale: vv.scale,
+      offsetTop: vv.offsetTop,
+      pageTop: vv.pageTop,
+      scrollY: window.scrollY,
+      keyboard: height,
+      event: lastEvent,
+    });
+    // The readout wants every frame; otherwise only the second after a focus change.
+    if (onRead || performance.now() < pollUntil) schedule();
+    if (height > 0) {
+      anticipatingUntil = 0;
+      remember(height);
+      report(height);
+    } else if (performance.now() >= anticipatingUntil) {
+      report(0);
+    }
+  };
+  const schedule = (): void => {
+    if (frame === undefined) frame = requestAnimationFrame(update);
+  };
+  const onViewport = (event: Event): void => {
+    lastEvent = `visualViewport ${event.type}`;
+    // Read on for a moment after a change, to see the pan hold still.
+    pollUntil = Math.max(pollUntil, performance.now() + PAN_SETTLE_MS);
+    schedule();
+  };
+  const isTextInput = (target: EventTarget | Element | null): boolean =>
+    target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement;
+  const onFocus = (event: FocusEvent): void => {
+    if (!isTextInput(event.target)) return;
+    lastEvent = event.type;
+    pollUntil = performance.now() + FOCUS_POLL_MS;
+    if (blurTimer !== undefined) clearTimeout(blurTimer);
+    blurTimer = undefined;
+    if (event.type === 'focusin') {
+      const known = knownHeight();
+      if (known > 0) {
+        anticipatingUntil = pollUntil;
+        report(known);
+      }
+    } else {
+      anticipatingUntil = 0;
+      // The focus may be moving to another text input (its `focusin` follows at once): wait a moment.
+      blurTimer = setTimeout(() => {
+        blurTimer = undefined;
+        if (!isTextInput(document.activeElement)) report(0);
+      }, BLUR_SETTLE_MS);
+    }
+    schedule();
+  };
+  vv.addEventListener('resize', onViewport);
+  vv.addEventListener('scroll', onViewport);
+  document.addEventListener('focusin', onFocus);
+  document.addEventListener('focusout', onFocus);
+  return () => {
+    if (frame !== undefined) cancelAnimationFrame(frame);
+    if (blurTimer !== undefined) clearTimeout(blurTimer);
+    pollUntil = 0;
+    anticipatingUntil = 0;
+    vv.removeEventListener('resize', onViewport);
+    vv.removeEventListener('scroll', onViewport);
+    document.removeEventListener('focusin', onFocus);
+    document.removeEventListener('focusout', onFocus);
+  };
+}
+
+/** `localStorage`, or null where reading it throws (a private window, blocked site data). */
+function safeLocalStorage(): Storage | null {
+  try {
+    return window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+/** After a text input loses focus, how long to wait for another to take it before reporting the keyboard down. */
+const BLUR_SETTLE_MS = 60;
+
+/** How many frames in a row the browser's pan must hold still before it is scrolled back. */
+const PAN_SETTLE_FRAMES = 3;
+
+/** How long after a visual viewport event the viewport keeps being read every frame, to see the pan settle. */
+const PAN_SETTLE_MS = 250;
+
+/** How long after a text input gains or loses focus the viewport is read every frame (the keyboard's animation and some). */
+const FOCUS_POLL_MS = 1000;
+
+/** One reading of the viewport, for the `?debug=viewport` readout. */
+export interface ViewportReading {
+  /** The root's height: the layout viewport's. */
+  layoutHeight: number;
+  innerHeight: number;
+  visualHeight: number;
+  scale: number;
+  /** The visual viewport's offset within the layout viewport: the browser's pan to the focused field. */
+  offsetTop: number;
+  pageTop: number;
+  scrollY: number;
+  keyboard: number;
+  /** The event that led to this reading (`visualViewport resize`, `focusin`…), empty before the first. */
+  event: string;
+}
+
+/**
+ * `?debug=viewport`: a small readout over the app with the numbers the
+ * keyboard measurement reads, for checking a phone's browser (which has no
+ * console to hand). It follows the visual viewport (a fixed element is
+ * panned with the layout viewport, off the top of the screen, when the
+ * browser pans to a field). Returns the function that updates it.
+ */
+export function installViewportReadout(): (reading: ViewportReading) => void {
+  const el = document.createElement('pre');
+  el.className = 'sb-viewport-readout';
+  el.setAttribute('aria-hidden', 'true');
+  document.body.appendChild(el);
+  return (r) => {
+    el.style.transform = `translateY(${Math.round(r.offsetTop)}px)`;
+    el.textContent =
+      `root ${window.innerWidth}×${r.layoutHeight}  inner ${r.innerHeight}  visual ${Math.round(r.visualHeight)}  scale ${r.scale.toFixed(3)}\n` +
+      `offsetTop ${Math.round(r.offsetTop)}  pageTop ${Math.round(r.pageTop)}  scrollY ${Math.round(r.scrollY)}\n` +
+      `keyboard ${r.keyboard}  ${r.event || 'no event yet'}  ${new Date().toLocaleTimeString()}`;
+  };
+}

package/src/interaction.ts

@@ -202,6 +202,14 @@ export class InteractionController {
   private session: Session | null = null;
   private openSwipe: OpenSwipe | null = null;
   private swipeBack: SwipeBackState | null = null;
+  /**
+   * The browser's own back gesture is in charge (browserHistory.ts mirrors
+   * navigation in the history): the renderer's edge swipe then ignores touch
+   * and pen, whose edge swipe the browser turns into a `popstate` that pops,
+   * so running both would pop twice. A mouse drag from the edge still pops
+   * here: no browser navigates on one.
+   */
+  nativeBackGesture = false;
   /** Wheel-driven swipe of a row: the host, its live offset and the idle timer that settles it. */
   private wheelSwipe: { host: SwipeHost; offset: number; timer: number } | null = null;
   /** Wheel-driven pull at the top of a refreshable scroller. */
@@ -426,7 +434,8 @@ export class InteractionController {
     }
     const byPress = event.pointerType !== 'mouse';
     const screen = target.closest<HTMLElement>('.sb-navscreen');
-    if (screen && screen.dataset['sbNavPosition'] === 'top' && Number(screen.dataset['sbDepth'] ?? '0') > 0 && !this.swipeBack) {
+    const browserSwipes = this.nativeBackGesture && event.pointerType !== 'mouse';
+    if (!browserSwipes && screen && screen.dataset['sbNavPosition'] === 'top' && Number(screen.dataset['sbDepth'] ?? '0') > 0 && !this.swipeBack) {
       const rect = screen.getBoundingClientRect();
       const id = Number(screen.dataset[ID_ATTR]);
       if (event.clientX - rect.left <= SWIPE_BACK_EDGE && Number.isInteger(id)) {