@swiftbrowser/web 0.9.11 → 0.9.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swiftbrowser/web",
-  "version": "0.9.11",
+  "version": "0.9.13",
   "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

@@ -11,7 +11,11 @@
  * 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.
+ * renderer made. When the app pops on its own, the renderer's `history.go`
+ * back is asynchronous and the app's `replaceState` for the screen it shows
+ * now runs before the move lands, on the entry being left; the renderer
+ * applies that URL again to the entry it arrives at, so the address bar
+ * follows the bar's back button as it follows the browser's.
  *
  * 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
@@ -60,6 +64,13 @@ export class BrowserHistory {
   /** A `popstate` asked for the entry's sidebar selection: the change it brings is recorded, not pushed. */
   private restoringSelection = false;
   private enabled = false;
+  /** The page's own `replaceState`, while ours stands in for it. */
+  private pageReplaceState: History['replaceState'] | null = null;
+  private pageReplaceStateWasOwn = false;
+  /** A URL the page set while our own `history.go` was on its way: meant for the entry it lands on. */
+  private landingUrl: string | URL | null = null;
+  /** A level appeared while our own `history.go` was on its way: its entry is pushed once the move lands. */
+  private syncOnArrival = false;
 
   constructor(
     private readonly renderer: Renderer,
@@ -75,10 +86,15 @@ export class BrowserHistory {
     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.watchReplaceState();
     this.renderer.interaction.nativeBackGesture = true;
     this.root.addEventListener('sb:commit', this.onCommit);
     this.win.addEventListener('popstate', this.onPopState);
-    this.sync();
+    // Enabled before the first commit (a mount, or a remount such as React's
+    // StrictMode makes in development) the screen is not drawn yet: fewer
+    // levels than the entry records is not the app popping, so only the
+    // levels already shown are pushed here and the first commit settles the rest.
+    this.sync(true);
   }
 
   dispose(): void {
@@ -87,10 +103,44 @@ export class BrowserHistory {
     this.renderer.interaction.nativeBackGesture = false;
     if (this.movingTimer) clearTimeout(this.movingTimer);
     this.movingTo = null;
+    this.landingUrl = null;
+    this.syncOnArrival = false;
+    this.unwatchReplaceState();
     this.root.removeEventListener('sb:commit', this.onCommit);
     this.win.removeEventListener('popstate', this.onPopState);
   }
 
+  /**
+   * Stands in for the page's `replaceState`: it still runs at once, and a
+   * URL given while our own `go` is on its way is remembered for the entry
+   * the move lands on.
+   */
+  private watchReplaceState(): void {
+    const history = this.win.history;
+    const original = history.replaceState;
+    this.pageReplaceState = original;
+    this.pageReplaceStateWasOwn = Object.prototype.hasOwnProperty.call(history, 'replaceState');
+    history.replaceState = (data: unknown, unused: string, url?: string | URL | null): void => {
+      if (this.movingTo !== null && url !== undefined && url !== null) this.landingUrl = url;
+      original.call(history, data, unused, url);
+    };
+  }
+
+  private unwatchReplaceState(): void {
+    const original = this.pageReplaceState;
+    if (!original) return;
+    const history = this.win.history;
+    // A browser's is the prototype's: removing ours uncovers it. A stand-in's own property is put back.
+    if (this.pageReplaceStateWasOwn) history.replaceState = original;
+    else delete (history as Partial<History>).replaceState;
+    this.pageReplaceState = null;
+  }
+
+  /** `replaceState` as the page had it, for our own entries. */
+  private replaceEntry(data: unknown, url?: string | URL | null): void {
+    (this.pageReplaceState ?? this.win.history.replaceState).call(this.win.history, data, '', url);
+  }
+
   /** 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();
@@ -192,7 +242,13 @@ export class BrowserHistory {
     this.movingTimer = setTimeout(() => {
       if (this.movingTo === null) return;
       this.movingTo = null;
+      // No move (a go past the ends fires nothing): the URL already sits on the entry at hand.
+      this.landingUrl = null;
       this.ignorePops = Math.max(0, this.ignorePops - 1);
+      if (this.syncOnArrival) {
+        this.syncOnArrival = false;
+        this.sync();
+      }
     }, 1000);
     this.win.history.go(delta);
   }
@@ -201,12 +257,21 @@ export class BrowserHistory {
     this.movingTo = null;
     if (this.movingTimer) clearTimeout(this.movingTimer);
     this.movingTimer = null;
+    // The page's URL for what it shows now, set on the entry we left: it belongs here.
+    const url = this.landingUrl;
+    this.landingUrl = null;
+    if (url !== null) this.replaceEntry(this.win.history.state, url);
+    // Levels that appeared during the move get their entries now.
+    if (this.syncOnArrival) {
+      this.syncOnArrival = false;
+      this.sync();
+    }
   }
 
   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 {
+  /** 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. `enabling`: nothing is drawn yet, so no level is taken as dismissed. */
+  sync(enabling = false): void {
     if (!this.enabled) return;
     const depth = this.depth();
     const recorded = this.recorded();
@@ -220,8 +285,15 @@ export class BrowserHistory {
       return;
     }
     if (depth > recorded) {
+      // Under our own pending `go`, a push would land relative to wherever the browser is when it runs (and
+      // Chrome moves back past it), leaving the app on an entry below what it shows: push once the move lands.
+      if (this.movingTo !== null) {
+        this.syncOnArrival = true;
+        return;
+      }
       for (let level = recorded + 1; level <= depth; level++) this.win.history.pushState(this.entry(level, selection), '');
     } else if (depth < recorded) {
+      if (enabling) return;
       // 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()) {
@@ -231,7 +303,7 @@ export class BrowserHistory {
       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) }, '');
+        this.replaceEntry({ ...rest, ...this.entry(depth, selection) });
       } else history.pushState(this.entry(depth, selection), '');
     }
     this.restoringSelection = false;

package/src/largeTitle.ts

@@ -42,6 +42,20 @@ export function largeTitleOf(screen: HTMLElement): HTMLElement | null {
   return title;
 }
 
+/**
+ * The large title's text: a span of its own, as the title element also
+ * holds a `.largeTitle` toolbar (which then hides the text, styles.css).
+ */
+export function largeTitleTextOf(title: HTMLElement): HTMLElement {
+  let text = title.querySelector<HTMLElement>(':scope > .sb-navbar-large-title-text');
+  if (!text) {
+    text = document.createElement('span');
+    text.className = 'sb-navbar-large-title-text';
+    title.prepend(text);
+  }
+  return text;
+}
+
 /** Whether a screen's large title currently scrolls inside one of its scroll views. */
 export function largeTitleScrolls(screen: HTMLElement, title: HTMLElement): boolean {
   return title.parentElement !== null && !title.parentElement.classList.contains('sb-navscreen-body') && screen.contains(title);

package/src/layout/engine.ts

@@ -3429,7 +3429,7 @@ export class LayoutPass {
     for (const spacer of parts.toolbars.filter(isSpacer)) this.hide(spacer, node);
     const barToolbars = parts.toolbars.filter((t) => {
       const placement = str(t.props['placement']);
-      return placement !== 'bottom' && placement !== 'secondary' && !isSpacer(t);
+      return placement !== 'bottom' && placement !== 'secondary' && placement !== 'largeTitle' && !isSpacer(t);
     });
     const secondaryToolbars = parts.toolbars.filter((t) => str(t.props['placement']) === 'secondary' && !isSpacer(t));
     const groups: Group[] = barToolbars.map((toolbar) => {
@@ -3624,6 +3624,28 @@ export class LayoutPass {
       if (!inlineSecondary.some((entry) => entry.toolbar === toolbar)) this.hide(toolbar, node);
       else for (const item of items) if (collapsedSecondary.some((entry) => entry.item === item)) this.hide(item, node);
     }
+    // `.largeTitle` items (iOS 26): in the large title row, in place of the
+    // title's text, from its leading margin and centered in the row; the
+    // renderer moves the toolbar into the title element, so they scroll with
+    // the content as the title does, and the bar shows the title once the row
+    // has gone under it. While the title is inline there is no row: hidden.
+    for (const toolbar of parts.toolbars) {
+      if (str(toolbar.props['placement']) !== 'largeTitle' || isSpacer(toolbar)) continue;
+      const row = chrome['largeTitle'];
+      if (!row) {
+        this.hide(toolbar, node);
+        continue;
+      }
+      const itemCtx = this.childContext(toolbar, cctx);
+      const room: Proposal = { width: Math.max(0, row.width - 2 * NAV_ITEM_MARGIN), height: null };
+      let cursor = row.x + NAV_ITEM_MARGIN;
+      for (const item of toolbar.children) {
+        const itemSize = this.measure(item, itemCtx, room);
+        this.place(item, itemCtx, room, cursor, row.y + (row.height - itemSize.height) / 2);
+        cursor += itemSize.width + NAV_ITEM_SPACING;
+      }
+      this.setFrame(toolbar, row.x, row.y, { width: row.width, height: row.height });
+    }
     if (bottomBarHeight > 0) {
       this.placeBottomToolbars(bottomToolbars, cctx, chrome, x, y + size.height - bottomBarHeight, size.width);
     }

package/src/layoutDom.ts

@@ -41,7 +41,7 @@ import type { ShapeStyle } from './protocol';
 import { applyChartChrome } from './chartDom';
 import { bitmapLaidOut } from './bitmaps';
 import { drawRichText } from './richText';
-import { bindScrollUnderBar, largeTitleOf, largeTitleScrolls } from './largeTitle';
+import { bindScrollUnderBar, largeTitleOf, largeTitleScrolls, largeTitleTextOf } from './largeTitle';
 import { bindScrollEdgeBottom } from './scrollEdge';
 import { beginScrollSyncBatch, flushScrollSyncBatch, type ScrollExtent } from './scrollSync';
 import { BAR_GLASS_KIND, TOOLBAR_ANIMATION, TOOLBAR_TRANSITION, baseTiming, timingFor, transitionStart } from './animation';
@@ -122,7 +122,14 @@ function applyFrames(ctx: LayoutDomContext, result: LayoutResult, changes: BoxCh
   /** The element's box relative to the origin its `left`/`top` use; applied when it differs from the last pass's. */
   const applyBox = (id: number, node: LayoutNode, el: HTMLElement, frame: Rect): { box: Rect; moved: boolean; previous: Rect | null } => {
     const box = drawnBox(node, boxOf(ctx, result, node, frame));
-    const origin = node.kind === 'sheet' ? { x: 0, y: 0 } : isSectionSupplement(node) ? supplementOrigin(ctx, result, id) : originOf(ctx, result, ctx.parents.get(id) ?? ROOT_ID);
+    const origin =
+      node.kind === 'sheet'
+        ? { x: 0, y: 0 }
+        : isSectionSupplement(node)
+          ? supplementOrigin(ctx, result, id)
+          : isLargeTitleToolbar(node)
+            ? largeTitleToolbarOrigin(ctx, result, id)
+            : originOf(ctx, result, ctx.parents.get(id) ?? ROOT_ID);
     const relative = { x: box.x - origin.x, y: box.y - origin.y, width: box.width, height: box.height };
     const previous = ctx.boxes.get(id) ?? null;
     boxes.set(id, relative);
@@ -233,6 +240,18 @@ function supplementOrigin(ctx: LayoutDomContext, result: LayoutResult, id: numbe
   return boxOf(ctx, result, parent, frame);
 }
 
+/** A `.largeTitle` toolbar: the renderer keeps it in its screen's large title element. */
+export function isLargeTitleToolbar(node: LayoutNode): boolean {
+  return node.kind === 'toolbar' && node.props['placement'] === 'largeTitle';
+}
+
+/** A `.largeTitle` toolbar sits in the large title element, which is placed at the screen's `largeTitle` row. */
+function largeTitleToolbarOrigin(ctx: LayoutDomContext, result: LayoutResult, id: number): { x: number; y: number } {
+  const parentId = ctx.parents.get(id) ?? ROOT_ID;
+  const row = result.chrome.get(parentId)?.['largeTitle'];
+  return row ?? originOf(ctx, result, parentId);
+}
+
 /** Screen-coordinate origin that the children of `parentId` are positioned against. */
 export function originOf(ctx: LayoutDomContext, result: LayoutResult, parentId: number): { x: number; y: number } {
   if (parentId === ROOT_ID) return { x: 0, y: 0 };
@@ -837,7 +856,8 @@ function applyChrome(
           if (texts?.['largeTitle']) {
             setFont(largeTitle, texts['largeTitle'].font);
             const line = texts['largeTitle'].lines.join('\n');
-            if (largeTitle.textContent !== line) largeTitle.textContent = line;
+            const text = largeTitleTextOf(largeTitle);
+            if (text.textContent !== line) text.textContent = line;
           }
         } else {
           largeTitle.hidden = true;

package/src/protocol.ts

@@ -897,7 +897,13 @@ export interface DecoratedProps {
 export interface MenuProps {
   deferred?: boolean;
 }
-export type ToolbarPlacement = 'trailing' | 'leading' | 'principal' | 'bottom' | 'secondary';
+/**
+ * `largeTitle` (iOS 26 `.largeTitle`): the items take the large title row in
+ * place of the title's text, scrolling with the content as the title does;
+ * the bar shows the title once the row has gone under it. Hidden while the
+ * screen's title is inline.
+ */
+export type ToolbarPlacement = 'trailing' | 'leading' | 'principal' | 'bottom' | 'secondary' | 'largeTitle';
 /**
  * `.toolbar { ToolbarItem(placement:) { ... } }`, an extra child of a
  * `navscreen` after its content. The children are the items, laid out at
@@ -1884,6 +1890,16 @@ export interface Style {
   hitTesting?: boolean;
 }
 
+export interface Style {
+  /**
+   * `.onScrollVisibilityChange(threshold:_:)`: the page sends
+   * `scrollvisibility` to the box when the share of it inside its scroll
+   * view's visible area (below a bar the view scrolls under, above a bar
+   * covering its bottom) crosses `threshold` (src/scrollVisibility.ts).
+   */
+  scrollVisibility?: { threshold: number };
+}
+
 export interface Style {
   /** `.blendMode`: the CSS `mix-blend-mode` the box is composited with. */
   blendMode?: string;
@@ -1957,6 +1973,16 @@ export interface ScrollPositionEvent {
   type: 'scrollposition';
   id: ElementId;
 }
+/**
+ * Sent to a `styled` box with `scrollVisibility`: the share of it inside its
+ * scroll view's visible area came to the threshold or above (`visible`), or
+ * fell below it. The first check after the box appears says where it is.
+ */
+export interface ScrollVisibilityEvent {
+  type: 'scrollvisibility';
+  id: ElementId;
+  visible: boolean;
+}
 /**
  * A movable `listrow` was dragged to a new place: `to` is the index among
  * its container's children (the `list`'s, or its `section`'s) before which
@@ -2002,7 +2028,7 @@ export interface DropEvent {
 }
 
 /** The Phase 8 events (merged into `RendererEvent` above). */
-export type InteractionEvent = DragEvent | PinchEvent | LongPressEvent | DeleteEvent | RefreshEvent | ScrollPositionEvent | MoveEvent | DragStartEvent | DragEndEvent | DropEvent;
+export type InteractionEvent = DragEvent | PinchEvent | LongPressEvent | DeleteEvent | RefreshEvent | ScrollPositionEvent | ScrollVisibilityEvent | MoveEvent | DragStartEvent | DragEndEvent | DropEvent;
 // Phase 8: alerts, controls, effects
 // (docs/ops-protocol.md, "Phase 8: interaction"; gestures, swipe actions,
 // context menus, list rows and refresh live in their own block)

package/src/renderer.ts

@@ -153,13 +153,14 @@ import { applyCanvas, createCanvasElement } from './canvasDrawing';
 import { scrollToTarget } from './scrollTo';
 import { POSITION_SETTLE_MS, POSITION_SNAP_WAITS, anchorPoint, positionTarget, restsOnSnapPoint, type PositionCandidate } from './scrollPosition';
 import { TouchPaging } from './touchPaging';
+import { isScrollVisible } from './scrollVisibility';
 import { applyDefaultScrollAnchor, keepScrollAnchors } from './scrollAnchor';
 import { EMPTY_CATALOG, assetColorVar, type AssetCatalog } from './assets';
 import { HIERARCHY_OPACITY, colorToCSS, effectsCSS, styleToCSS, type PaintCSS } from './styles';
 import { hostContent, onHostContentChange } from './hostContent';
 import { HoverTracker, applyPointerAndEffects, safeAreaOverlap } from './pointerEffects';
 import { colorMultiplyFilter } from './colorMultiply';
-import { largeTitleOf } from './largeTitle';
+import { largeTitleOf, largeTitleTextOf } from './largeTitle';
 import { applyEdgeEffect } from './scrollEdge';
 import { discardScrollOffsets, readScrollOffsets, trackScroller } from './scrollSync';
 import { DEFAULT_TYPE_SIZE, TEXT_STYLE_WEIGHT, resolveTextStyle, textStyleVar } from './typography';
@@ -440,6 +441,10 @@ export class Renderer {
   private pendingScrolls: ElementId[] = [];
   /** Lazy rows: the `lazyspacer`s on the page, and those already reported near the visible area. */
   private lazySpacers = new Set<ElementId>();
+  /** `styled` boxes with `scrollVisibility`, and what each was last told (src/scrollVisibility.ts). */
+  private readonly visibilityTargets = new Map<ElementId, number>();
+  private readonly visibilityReported = new Map<ElementId, boolean>();
+  private visibilityCheckQueued = false;
   private lazyReported = new Set<ElementId>();
   private lazyCheckQueued = false;
   /** The highest `scrollTo` serial seen: a command keeps its serial until the reader re-runs, and runs once. */
@@ -864,6 +869,7 @@ export class Renderer {
     root.addEventListener('focusout', this.onFocusChange);
     root.addEventListener('scroll', this.onScrollDismissKeyboard, true);
     root.addEventListener('scroll', this.queueLazyCheck, { capture: true, passive: true });
+    root.addEventListener('scroll', this.queueVisibilityCheck, { capture: true, passive: true });
     root.addEventListener('scroll', this.onPositionScroll, { capture: true, passive: true });
     root.addEventListener('scrollend', this.onPositionScrollEnd, { capture: true, passive: true });
     root.addEventListener('touchstart', this.onPositionTouchStart, { capture: true, passive: true });
@@ -1335,6 +1341,7 @@ export class Renderer {
     this.collectGeometry(result);
     this.collectLayouts(result);
     if (this.applying === 0) this.flushGeometry();
+    this.queueVisibilityCheck();
     this.afterLayout?.();
     return changes;
   }
@@ -1585,6 +1592,7 @@ export class Renderer {
     this.root.removeEventListener('focusin', this.onFocusChange);
     this.root.removeEventListener('focusout', this.onFocusChange);
     this.root.removeEventListener('scroll', this.onScrollDismissKeyboard, true);
+    this.root.removeEventListener('scroll', this.queueVisibilityCheck, true);
     this.root.removeEventListener('scroll', this.onPositionScroll, true);
     this.root.removeEventListener('scrollend', this.onPositionScrollEnd, true);
     this.root.removeEventListener('touchstart', this.onPositionTouchStart, true);
@@ -1626,6 +1634,7 @@ export class Renderer {
     if (kind === 'geometry' || (props as { reportsSize?: unknown }).reportsSize === true) this.geometryReporters.add(id);
     applyProps(el, kind, props, this.assets);
     this.noteScroll(id, kind, props);
+    this.noteVisibility(id, kind, props);
     if (kind === 'list' || kind === 'scrollview') trackScroller(el);
     if (kind === 'lazyspacer') this.lazySpacers.add(id);
     if (kind === 'host') {
@@ -1634,6 +1643,18 @@ export class Renderer {
     }
   }
 
+  /** A toolbar whose placement changed to or from `largeTitle` moves between its screen's content slot and large title. */
+  private rehomeToolbar(id: ElementId, el: HTMLElement, op: Op): void {
+    const parentId = this.parents.get(id);
+    const parent = parentId === undefined ? undefined : this.elements.get(parentId);
+    if (parentId === undefined || !parent || !parent.classList.contains('sb-navscreen') || !el.isConnected) return;
+    const expected = el.dataset['sbPlacement'] === 'largeTitle' ? (largeTitleOf(parent) ?? slotOf(parent)) : slotOf(parent);
+    if (el.parentElement === expected) return;
+    const node = this.nodes.get(id);
+    const index = node ? (this.nodes.get(parentId)?.children.indexOf(node) ?? -1) : -1;
+    if (index >= 0) this.insert(parentId, id, index, op);
+  }
+
   /** A `host` element takes the page's content element (src/hostContent.ts) and watches its size. */
   private adoptHostContent(id: ElementId, el: HTMLElement, props: HostProps): void {
     const content = hostContent(props.content);
@@ -1680,6 +1701,64 @@ export class Renderer {
     }
   }
 
+  // -------------------------------------------------------------------------
+  // `.onScrollVisibilityChange` (src/scrollVisibility.ts)
+  // -------------------------------------------------------------------------
+
+  /** A `styled` box with `scrollVisibility` is watched; any other forgets it was. */
+  private noteVisibility(id: ElementId, kind: ElementKind, props: ElementProps): void {
+    const spec = kind === 'styled' ? (props as Partial<StyledProps>)?.style?.scrollVisibility : undefined;
+    if (spec && typeof spec.threshold === 'number') {
+      this.visibilityTargets.set(id, spec.threshold);
+      return;
+    }
+    this.visibilityTargets.delete(id);
+    this.visibilityReported.delete(id);
+  }
+
+  /** After a scroll or a layout, the watched boxes are checked on the next frame (once per frame). */
+  private readonly queueVisibilityCheck = (): void => {
+    if (this.visibilityCheckQueued || this.visibilityTargets.size === 0) return;
+    this.visibilityCheckQueued = true;
+    requestAnimationFrame(() => {
+      this.visibilityCheckQueued = false;
+      this.checkVisibility();
+    });
+  };
+
+  /**
+   * Each watched box against its scroll view's visible area (the view's box
+   * less the bars it runs under), or the root's outside one: told when it
+   * comes into view or leaves it, and once when first checked.
+   */
+  private checkVisibility(): void {
+    for (const [id, threshold] of this.visibilityTargets) {
+      const el = this.elements.get(id);
+      if (!el || !el.isConnected) {
+        this.visibilityTargets.delete(id);
+        this.visibilityReported.delete(id);
+        continue;
+      }
+      const box = el.getBoundingClientRect();
+      if (box.width === 0 && box.height === 0) continue;
+      const scroller = el.parentElement?.closest<HTMLElement>('.sb-scrollview, .sb-list') ?? null;
+      const area = (scroller ?? this.root).getBoundingClientRect();
+      const viewport = { x: area.left, y: area.top, width: area.width, height: area.height };
+      if (scroller) {
+        const chrome = this.layoutResult?.chrome.get(Number(scroller.dataset[ID_ATTR]));
+        const top = chrome?.['topInset']?.height ?? 0;
+        const covered = chrome?.['bottomInset'];
+        viewport.y += top;
+        viewport.height -= top;
+        if (covered) viewport.height = Math.max(0, viewport.height - covered.height);
+      }
+      const visible = isScrollVisible({ x: box.left, y: box.top, width: box.width, height: box.height }, viewport, threshold);
+      if (this.visibilityReported.get(id) === visible) continue;
+      this.visibilityReported.set(id, visible);
+      this.onEvent({ type: 'scrollvisibility', id, visible });
+    }
+  }
+
   // -------------------------------------------------------------------------
   // `.scrollPosition(id:)` reading back (src/scrollPosition.ts)
   // -------------------------------------------------------------------------
@@ -1808,10 +1887,19 @@ export class Renderer {
       .map((id) => ({ id, command: (this.nodes.get(id)?.props as Partial<StyledProps> | undefined)?.style?.scrollTo }))
       .filter((entry): entry is { id: ElementId; command: ScrollToCommand } => entry.command !== undefined)
       .sort((a, b) => a.command.serial - b.command.serial);
+    // A page a finger set running gives way to the app's commands; a drag in progress carries on across them.
+    const fresh = commands.some(({ command }) => command.serial > this.scrollSerial);
+    if (fresh) this.touchPaging.beforeScrollCommands();
     for (const { id, command } of commands) {
       if (command.serial <= this.scrollSerial) continue;
       scrollToTarget(this, result, id, command, animated);
+      // The scroll views it moved report their position afresh when they next settle, even one they
+      // reported last: the app set its binding itself, and where the view rests may not be it.
+      for (let scroller = this.elements.get(id)?.parentElement?.closest<HTMLElement>('.sb-scrollview, .sb-list'); scroller; scroller = scroller.parentElement?.closest<HTMLElement>('.sb-scrollview, .sb-list') ?? null) {
+        this.reportedPositions.delete(scroller);
+      }
     }
+    if (fresh) this.touchPaging.afterScrollCommands();
     for (const { command } of commands) this.scrollSerial = Math.max(this.scrollSerial, command.serial);
   }
 
@@ -1901,7 +1989,9 @@ export class Renderer {
     if (kind === 'text') el.textContent = '';
     applyProps(el, kind, props, this.assets);
     this.noteScroll(id, kind, props);
+    this.noteVisibility(id, kind, props);
     if (kind === 'host') this.adoptHostContent(id, el, props as HostProps);
+    if (kind === 'toolbar') this.rehomeToolbar(id, el, op);
     const newToken = el.dataset[ANIMATION_TOKEN];
     const tokenChanged = (previous?.tokenChanged ?? false) || (newToken !== undefined && newToken !== oldToken);
     const record: UpdatedRecord = { el, before, tokenChanged };
@@ -1942,7 +2032,9 @@ export class Renderer {
     // A section's view header / footer lives beside its rows' card, in the
     // section element itself; the rows after a header are one DOM slot lower.
     const supplement = isSectionSupplement(el);
-    const container = supplement && parent.classList.contains('sb-section') ? parent : slotOf(parent);
+    // A `.largeTitle` toolbar lives in its screen's large title element, which scrolls with the content.
+    const inLargeTitle = el.dataset['sbPlacement'] === 'largeTitle' && parent.classList.contains('sb-navscreen');
+    const container = supplement && parent.classList.contains('sb-section') ? parent : inLargeTitle ? (largeTitleOf(parent) ?? slotOf(parent)) : slotOf(parent);
     // Moves: `index` is the element's position in the parent's child list
     // *after* the op is applied. Detaching first makes the index arithmetic
     // identical for fresh inserts and for moves within the same parent.
@@ -1954,9 +2046,21 @@ export class Renderer {
       const first = this.nodes.get(parentId)?.children.find((child) => child.id !== id);
       if (first?.kind === 'sectionheader') slotIndex -= 1;
     }
+    // A screen's children may live in two containers (its content slot and
+    // its large title): the next sibling in the same container is the reference.
+    const screenReference = (): Element | null => {
+      const siblings = (this.nodes.get(parentId)?.children ?? []).filter((child) => child.id !== id);
+      for (const sibling of siblings.slice(index)) {
+        const sib = this.elements.get(sibling.id);
+        if (sib && sib.parentElement === container) return sib;
+      }
+      return null;
+    };
     const reference = supplement
       ? el.classList.contains('sb-sectionheader') ? container.firstChild : null
-      : (container.children[slotIndex] ?? null);
+      : parent.classList.contains('sb-navscreen')
+        ? screenReference()
+        : (container.children[slotIndex] ?? null);
     container.insertBefore(el, reference);
     if (!wasAttached) this.pass.inserted.add(el);
     // Mirror the move in the layout tree.
@@ -3225,7 +3329,7 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
       const placement = (props as ToolbarProps).placement;
       // `secondary` items shown in the bar look like the trailing ones (glass capsules).
       el.dataset['sbPlacement'] =
-        placement === 'leading' || placement === 'principal' || placement === 'bottom' ? placement : 'trailing';
+        placement === 'leading' || placement === 'principal' || placement === 'bottom' || placement === 'largeTitle' ? placement : 'trailing';
       // A `ToolbarSpacer`: draws nothing.
       el.toggleAttribute('data-sb-spacer', typeof (props as ToolbarProps).spacer === 'string');
       break;
@@ -3855,9 +3959,17 @@ function applyNavScreen(el: HTMLElement, props: NavScreenProps): void {
   const largeTitle = largeTitleOf(el);
   // A large title that scrolls away collapses into the inline one (shown
   // with `data-sb-collapsed`, src/largeTitle.ts).
-  if (inlineTitle) inlineTitle.textContent = title;
+  if (inlineTitle) {
+    const appearing = inlineTitle.textContent === '' && title !== '' && inlineTitle.isConnected;
+    inlineTitle.textContent = title;
+    // An inline title given to an empty bar (a header row that has scrolled
+    // under it handing the bar its name) fades in as a collapsing large title does.
+    if (appearing && !large && typeof inlineTitle.animate === 'function') {
+      inlineTitle.animate([{ opacity: 0 }, { opacity: 1 }], { duration: 150, easing: 'ease' });
+    }
+  }
   if (largeTitle) {
-    largeTitle.textContent = large ? title : '';
+    largeTitleTextOf(largeTitle).textContent = large ? title : '';
     largeTitle.hidden = !large;
   }
   el.setAttribute('aria-label', title);

package/src/scrollVisibility.ts

@@ -0,0 +1,38 @@
+/**
+ * `.onScrollVisibilityChange(threshold:_:)` (iOS 18; docs/ops-protocol.md,
+ * "Scroll visibility"): a `styled` box with `scrollVisibility` is told when
+ * the share of it inside its scroll view's visible area crosses its
+ * threshold. The visible area is the scroll view's box less a bar it scrolls
+ * under (its `topInset`) and a bar covering its bottom (`bottomInset`), as
+ * content under a bar is not in view; outside a scroll view it is the root.
+ */
+
+export interface Span {
+  start: number;
+  length: number;
+}
+
+/** The share (0...1) of `target` along an axis inside `viewport`; 0 for a target of no extent. */
+export function visibleShare(target: Span, viewport: Span): number {
+  if (target.length <= 0) return 0;
+  const start = Math.max(target.start, viewport.start);
+  const end = Math.min(target.start + target.length, viewport.start + viewport.length);
+  return Math.max(0, end - start) / target.length;
+}
+
+/**
+ * Whether a box is visible: some of it is in view, and at least `threshold`
+ * of it along the scroll axes (both shares multiplied for a view scrolling
+ * both ways, the other axis counted too, as a box off to the side is not in
+ * view).
+ */
+export function isScrollVisible(
+  target: { x: number; y: number; width: number; height: number },
+  viewport: { x: number; y: number; width: number; height: number },
+  threshold: number,
+): boolean {
+  const horizontal = visibleShare({ start: target.x, length: target.width }, { start: viewport.x, length: viewport.width });
+  const vertical = visibleShare({ start: target.y, length: target.height }, { start: viewport.y, length: viewport.height });
+  const share = horizontal * vertical;
+  return share > 0 && share >= Math.min(1, Math.max(0, threshold));
+}

package/src/styles.css

@@ -751,6 +751,17 @@ svg[data-sb-symbol="progress.indicator"] > line:nth-child(8) { animation-delay:
   touch-action: pan-x pinch-zoom;
 }
 
+/* Nothing inside widens the pans the browser may make along the paging axis:
+   a button's `manipulation` would let Safari pan the view itself under a
+   quick swipe that starts on it. */
+.sb-scrollview[data-sb-snap="paging"][data-sb-axes="horizontal"] * {
+  touch-action: pan-y pinch-zoom;
+}
+
+.sb-scrollview[data-sb-snap="paging"][data-sb-axes="vertical"] * {
+  touch-action: pan-x pinch-zoom;
+}
+
 .sb-scroll-content,
 .sb-list-content {
   position: relative;
@@ -1242,6 +1253,22 @@ svg[data-sb-symbol="progress.indicator"] > line:nth-child(8) { animation-delay:
   display: none;
 }
 
+/* A `.largeTitle` toolbar (iOS 26) takes the row in place of the title's
+   text, which the bar still shows once the row has scrolled under it. Its
+   items are content, drawn as anywhere else and answering touches. */
+.sb-navbar-large-title:has(> .sb-toolbar[data-sb-placement="largeTitle"]:not([hidden])) > .sb-navbar-large-title-text {
+  visibility: hidden;
+}
+
+.sb-navbar-large-title > .sb-toolbar {
+  font-size: var(--sb-font-size-body);
+  font-weight: 400;
+  line-height: normal;
+  letter-spacing: normal;
+  white-space: normal;
+  pointer-events: auto;
+}
+
 /* The large title scrolls with the screen's root list or scroll view
    (src/largeTitle.ts moves it into it); drags on it scroll that view. There
    it is content, under the bar. */

package/src/touchPaging.ts

@@ -18,8 +18,14 @@ export const FLICK_VELOCITY = 0.3;
 export const FLICK_WINDOW_MS = 100;
 /** How far a flick carries on inside a page longer than the viewport (its velocity times this). */
 export const FLICK_RUN_MS = 250;
-/** A touch is a drag once it moved this far; the larger axis then decides whose gesture it is. */
-export const DIRECTION_SLOP = 6;
+/**
+ * A touch is a drag once it moved this far; the larger axis of that first
+ * move decides whose gesture it is. Small, and under Safari's own threshold
+ * for starting a pan: a move left to the browser lets it begin a pan, after
+ * which it cancels the touch for the page, and a drag of ours would end in
+ * a run from wherever the finger was.
+ */
+export const DIRECTION_SLOP = 3;
 
 /** Where a scroll view may rest for one page: at its start, or anywhere a page longer than the viewport fills it (`start === end` for a page the viewport's size). */
 export interface RestInterval {
@@ -120,19 +126,37 @@ interface Gesture {
   /** The finger position (along the axis) where our drag took over. */
   fromPos: number;
   samples: TouchSample[];
+  /** The page under the leading edge as of the last move, to find again after the app's scroll commands. */
+  page: Page | null;
 }
 
 interface Run {
   el: HTMLElement;
   frame: number;
-  /** The offset the last frame wrote: another writer moving the view ends the run. */
-  written: number;
+}
+
+/** Where a drag was when the app's scroll commands began: the offset, and the page under it to find again after. */
+interface Held {
+  el: HTMLElement;
+  offset: number;
+  page: Page | null;
 }
 
 const PAGING_SELECTOR = '.sb-scrollview[data-sb-snap="paging"]';
 
+export interface Page {
+  element: Element;
+  start: number;
+  length: number;
+}
+
+/** The page whose extent holds `offset` (the leading edge), if any. */
+function pageAt(el: HTMLElement, horizontal: boolean, offset: number): Page | null {
+  return pagesOf(el, horizontal).find((p) => p.start <= offset + 1 && offset < p.start + p.length) ?? null;
+}
+
 /** Pages of a paging scroll view in scroll coordinates along its axis: the children of its `scrollTargetLayout` stack, else of its content. */
-export function pagesOf(el: HTMLElement, horizontal: boolean): { start: number; length: number }[] {
+export function pagesOf(el: HTMLElement, horizontal: boolean): Page[] {
   const targets = [...el.querySelectorAll<HTMLElement>('[data-sb-scroll-target] > *')].filter((t) => t.parentElement?.closest('.sb-scrollview, .sb-list') === el);
   const children = targets.length > 0 ? targets : [...((el.firstElementChild?.children ?? []) as Iterable<Element>)];
   const box = el.getBoundingClientRect();
@@ -141,13 +165,14 @@ export function pagesOf(el: HTMLElement, horizontal: boolean): { start: number;
   const offset = horizontal ? el.scrollLeft : el.scrollTop;
   return children.map((child) => {
     const rect = child.getBoundingClientRect();
-    return horizontal ? { start: rect.left - box.left - padding + offset, length: rect.width } : { start: rect.top - box.top - padding + offset, length: rect.height };
+    return horizontal ? { element: child, start: rect.left - box.left - padding + offset, length: rect.width } : { element: child, start: rect.top - box.top - padding + offset, length: rect.height };
   });
 }
 
 export class TouchPaging {
   private gesture: Gesture | null = null;
   private run: Run | null = null;
+  private held: Held | null = null;
 
   /**
    * `onRest(el)`: the view came to rest on a page after a gesture of ours
@@ -159,7 +184,9 @@ export class TouchPaging {
     private readonly onRest: (el: HTMLElement) => void = () => {},
   ) {
     root.addEventListener('touchstart', this.onTouchStart, { passive: true });
-    root.addEventListener('touchmove', this.onTouchMove, { passive: true });
+    // Not passive: a drag of ours cancels the browser's own handling of the moves (Safari pans a
+    // scroll view under a finger whatever `touch-action` says, and the two would fight over it).
+    root.addEventListener('touchmove', this.onTouchMove, { passive: false });
     root.addEventListener('touchend', this.onTouchEnd, { passive: true });
     root.addEventListener('touchcancel', this.onTouchEnd, { passive: true });
   }
@@ -169,6 +196,67 @@ export class TouchPaging {
     return (this.gesture?.el === el && this.gesture.ours === true) || this.run?.el === el;
   }
 
+  /**
+   * The app is about to scroll (`scrollTo` commands): a run still going
+   * gives way to them, and a drag in progress notes where the view is and
+   * which page is under the finger, to carry on from there once the
+   * commands are done (`afterScrollCommands`).
+   */
+  beforeScrollCommands(): void {
+    const run = this.run;
+    if (run) {
+      this.stopRun();
+      this.onRest(run.el);
+    }
+    const g = this.gesture;
+    this.held = null;
+    if (!g?.ours) return;
+    // The page as of the drag's last move: the commands' pass has already changed the tree by now.
+    this.held = { el: g.el, offset: g.horizontal ? g.el.scrollLeft : g.el.scrollTop, page: g.page };
+  }
+
+  /**
+   * The app's scroll commands are done. A drag in progress keeps the
+   * content under the finger where it was: an app re-centring its pages
+   * on the one arrived at moves the content a page and scrolls the same
+   * page, which the command's own offset would show aligned, dropping the
+   * drag so far. The page's new places reach the DOM on the next frame
+   * (the renderer commits its layout then), so the drag carries on from
+   * them at the next frame or the next move, whichever comes first.
+   */
+  afterScrollCommands(): void {
+    const held = this.held;
+    if (!held) return;
+    const g = this.gesture;
+    if (!g?.ours || g.el !== held.el) {
+      this.held = null;
+      return;
+    }
+    requestAnimationFrame(() => this.carryOn());
+  }
+
+  /**
+   * The page that was under the finger is found again and the offset
+   * moved by what it moved; without it (a page that is gone), the drag
+   * carries on from the offset the commands set.
+   */
+  private carryOn(): void {
+    const held = this.held;
+    this.held = null;
+    const g = this.gesture;
+    if (!held || !g?.ours || g.el !== held.el) return;
+    const now = g.horizontal ? g.el.scrollLeft : g.el.scrollTop;
+    const page = held.page ? pagesOf(g.el, g.horizontal).find((p) => p.element === held.page!.element) : undefined;
+    const shift = page ? page.start - held.page!.start : now - held.offset;
+    g.from += shift;
+    if (page) {
+      const max = g.horizontal ? g.el.scrollWidth - g.el.clientWidth : g.el.scrollHeight - g.el.clientHeight;
+      const offset = Math.min(max, Math.max(0, held.offset + shift));
+      if (g.horizontal) g.el.scrollLeft = offset;
+      else g.el.scrollTop = offset;
+    }
+  }
+
   dispose(): void {
     this.root.removeEventListener('touchstart', this.onTouchStart);
     this.root.removeEventListener('touchmove', this.onTouchMove);
@@ -186,7 +274,7 @@ export class TouchPaging {
     const axes = el.dataset['sbAxes'];
     if (axes !== 'horizontal' && axes !== 'vertical') return;
     const horizontal = axes === 'horizontal';
-    this.gesture = { el, horizontal, startX: touch.clientX, startY: touch.clientY, ours: null, from: 0, fromPos: 0, samples: [] };
+    this.gesture = { el, horizontal, startX: touch.clientX, startY: touch.clientY, ours: null, from: 0, fromPos: 0, samples: [], page: null };
     // A finger on a page still running to its place catches it: the drag is
     // ours from here, and the lift runs it on to a page.
     if (this.run?.el === el) {
@@ -202,6 +290,7 @@ export class TouchPaging {
     const g = this.gesture;
     const touch = event.touches[0];
     if (!g || !touch) return;
+    if (this.held) this.carryOn();
     const pos = g.horizontal ? touch.clientX : touch.clientY;
     if (g.ours === null) {
       const dx = touch.clientX - g.startX;
@@ -218,10 +307,12 @@ export class TouchPaging {
       g.from = g.horizontal ? g.el.scrollLeft : g.el.scrollTop;
       g.fromPos = pos;
     }
+    if (event.cancelable) event.preventDefault();
     const max = g.horizontal ? g.el.scrollWidth - g.el.clientWidth : g.el.scrollHeight - g.el.clientHeight;
     const offset = Math.min(max, Math.max(0, g.from - (pos - g.fromPos)));
     if (g.horizontal) g.el.scrollLeft = offset;
     else g.el.scrollTop = offset;
+    g.page = pageAt(g.el, g.horizontal, offset);
     g.samples.push({ t: event.timeStamp, pos });
     if (g.samples.length > 20) g.samples.shift();
   };
@@ -230,6 +321,7 @@ export class TouchPaging {
     const g = this.gesture;
     if (!g) return;
     if (event.touches.length > 0) return;
+    if (this.held) this.carryOn();
     this.gesture = null;
     if (!g.ours) return;
     const el = g.el;
@@ -253,15 +345,10 @@ export class TouchPaging {
     }
     const duration = runDuration(distance);
     const started = performance.now();
+    // The run writes the offset every frame and the last write is the page itself, whatever
+    // else moved the view meanwhile (the offset Safari reads back can trail a write); only an
+    // app's own scroll command ends it early (`interrupt`).
     const step = (now: number): void => {
-      const run = this.run;
-      const current = horizontal ? el.scrollLeft : el.scrollTop;
-      // Another writer moved the view (an app re-centring on the page): the run is over.
-      if (run && Math.abs(current - run.written) > 1) {
-        this.stopRun();
-        this.onRest(el);
-        return;
-      }
       const t = (now - started) / duration;
       const offset = t >= 1 ? to : from + distance * easeOut(t);
       if (horizontal) el.scrollLeft = offset;
@@ -272,9 +359,9 @@ export class TouchPaging {
         this.onRest(el);
         return;
       }
-      this.run = { el, frame: requestAnimationFrame(step), written: offset };
+      this.run = { el, frame: requestAnimationFrame(step) };
     };
-    this.run = { el, frame: requestAnimationFrame(step), written: from };
+    this.run = { el, frame: requestAnimationFrame(step) };
   }
 
   private stopRun(): void {