@swiftbrowser/web 0.17.8 → 0.18.1

package/src/renderer.ts

@@ -49,6 +49,10 @@ import {
 import {
   CanvasTextMeasurer,
   LayoutPass,
+  defaultFont,
+  resolveFont,
+  textHeight,
+  wrapText,
   type LayoutEnvironment,
   type LayoutNode,
   type LayoutResult,
@@ -58,11 +62,15 @@ import { LayoutReporter } from './layoutEvents';
 import { createGaugeRing, isCircularGauge, updateGaugeRing } from './gaugeRing';
 import { bitmapStore, showBitmap } from './bitmaps';
 import { clearRichText, runTemplates } from './richText';
+import { markDeleteBackward, wantsDeleteBackward } from './editorSelection';
+import { applyPlainEditorSelection, focusPlainEditor, isPlainEditor, listenToPlainEditors } from './plainEditor';
+import { applyRichEditor, createRichEditor, focusRichEditor, isRichEditor, listenToRichEditors, richEditorText } from './richEditor';
 import { applyLayout, setTabHidden, type BoxChange } from './layoutDom';
 import { BarMorph } from './barMorph';
 import { ghostClone } from './ghost';
 import { ExternalDrops } from './dragDrop';
 import { InteractionController, type InteractionHost } from './interaction';
+import { TapCounter } from './gestureComposition';
 import { PressEffects } from './press';
 import { symbolOf, textOf, unwrapStyledNode } from './nodeQueries';
 import {
@@ -86,6 +94,7 @@ import {
   type FontWeight,
   type GaugeProps,
   type GeometryEvent,
+  type ScrollGeometryEvent,
   type GestureProps,
   type GridProps,
   type GridRowProps,
@@ -151,6 +160,7 @@ import {
 import { filledSymbolName, renderSymbol } from './symbols';
 import { applyPathShape, hasPathFrames, playPathFrames } from './pathShape';
 import { VideoEvents, applyVideo, stopVideos } from './video';
+import { loadableURL } from './hostRequests';
 import { PinchController } from './pinch';
 import { applyCanvas, createCanvasElement } from './canvasDrawing';
 import { scrollToTarget } from './scrollTo';
@@ -166,6 +176,9 @@ import { colorMultiplyFilter } from './colorMultiply';
 import { largeTitleOf, largeTitleTextOf } from './largeTitle';
 import { applyEdgeEffect } from './scrollEdge';
 import { discardScrollOffsets, readScrollOffsets, trackScroller } from './scrollSync';
+import { drawScrollTransitions, setScrollTransition } from './scrollTransition';
+import { ScrollGeometryReporter, readScrollGeometry } from './scrollGeometry';
+import { drawPinnedViews, setPinnedViews } from './pinnedViews';
 import { DEFAULT_TYPE_SIZE, TEXT_STYLE_WEIGHT, resolveTextStyle, textStyleVar } from './typography';
 
 export type EventCallback = (event: RendererEvent) => void;
@@ -391,12 +404,21 @@ export class Renderer {
   private readonly hover: HoverTracker;
   /** A frame check of the `reportsFrame` readers is queued for the next animation frame (after a scroll). */
   private frameCheckQueued = false;
+  /** `reportsGeometry` scroll views (src/scrollGeometry.ts): their ids, the last report of each, and whether a check waits for the next frame. */
+  private readonly scrollReporters = new Set<ElementId>();
+  private readonly scrollGeometry = new ScrollGeometryReporter();
+  private scrollGeometryQueued = false;
+  /** `scrollview`s whose `scrollOffset` command is new this pass: scrolled after its layout (`performOffsetScrolls`), and the serial each last carried out. */
+  private pendingOffsets: ElementId[] = [];
+  private readonly offsetSerials = new Map<ElementId, number>();
   private readonly hostContents = new Map<ElementId, HTMLElement>();
   /** The `host` elements, adopted or still waiting for their content. */
   private readonly hosts = new Set<ElementId>();
   private readonly hostSizes = new WeakMap<HTMLElement, { width: number; height: number }>();
   private readonly hostMeasures = new Map<string, { width: number; height: number }>();
   private readonly stopHostChanges: () => void;
+  private readonly stopRichEditors: () => void;
+  private readonly stopPlainEditors: () => void;
   /**
    * The root takes its content's height (`LayoutEnvironment.contentHeight`):
    * a SwiftUI island in a page's own layout. Set before the first commit.
@@ -445,7 +467,7 @@ export class Renderer {
   /** The elements whose size is reported (`geometry`, or `reportsSize` props): what `collectGeometry` visits. */
   private readonly geometryReporters = new Set<ElementId>();
   /** `geometry` and `layout` events collected by layout passes, sent once the ops are applied. */
-  private pendingGeometry: (GeometryEvent | LayoutEvent)[] = [];
+  private pendingGeometry: (GeometryEvent | LayoutEvent | ScrollGeometryEvent)[] = [];
   /** Phase 6: dedupes `layout` events per element (src/layoutEvents.ts). */
   private readonly layoutReporter = new LayoutReporter();
   /** Nesting depth of `applyOps` (events are flushed when it returns to 0). */
@@ -493,6 +515,7 @@ export class Renderer {
     const hit = event.target as HTMLElement | null;
     const target = hit?.closest<HTMLElement>(
       '.sb-button, .sb-navlink, .sb-navbar-back, .sb-navbar-more, .sb-navsplit-toggle, .sb-switch, .sb-sheet-scrim, ' +
+        '.sb-toggle[data-sb-toggle-style="button"], .sb-toolbar .sb-toggle:not([data-sb-toggle-style]), ' +
         '.sb-tabbar-item, .sb-segment, .sb-picker-option, .sb-picker-menu-item, .sb-picker[data-sb-style="menu"], ' +
         '.sb-menu, .sb-tapgesture, .sb-stepper-button, .sb-alert-scrim, .sb-alert-ok, ' +
         // Phase 8: swipe action buttons, the edit-mode row control and selectable rows (the row sends `tap` itself)
@@ -618,12 +641,13 @@ export class Renderer {
       this.onEvent({ type: 'tap', id });
       return;
     }
-    if (target.classList.contains('sb-switch')) {
+    if (target.classList.contains('sb-switch') || target.classList.contains('sb-toggle')) {
+      // The switch, or a toggle drawn as a button (the whole of it).
       const toggle = target.closest<HTMLElement>('.sb-toggle');
       const id = Number(toggle?.dataset[ID_ATTR]);
       if (!toggle || !Number.isInteger(id)) return;
       event.preventDefault();
-      const value = target.getAttribute('aria-checked') !== 'true';
+      const value = toggle.dataset['sbOn'] !== 'true';
       // Flip optimistically so the switch animates right away; Swift's
       // `update` confirms (or reverts) the state.
       setSwitchState(toggle, value);
@@ -633,23 +657,38 @@ export class Renderer {
     const id = Number(target.dataset[ID_ATTR]);
     if (!Number.isInteger(id)) return;
     event.preventDefault();
-    if (target.hasAttribute('data-sb-tap-location')) {
-      // `onTapGesture { point in }`: the point in the element's own
-      // coordinates (points; the device frame may be scaled).
-      const rect = target.getBoundingClientRect();
-      const scale = target.offsetWidth > 0 ? rect.width / target.offsetWidth : 1;
-      const x = Math.round(((event.clientX - rect.left) / (scale || 1)) * 100) / 100;
-      const y = Math.round(((event.clientY - rect.top) / (scale || 1)) * 100) / 100;
-      this.onEvent({ type: 'tap', id, x, y });
+    if (target.classList.contains('sb-tapgesture')) {
+      // `onTapGesture(count: 2)`: the innermost double tap on the way up
+      // counts the clicks; the innermost single tap waits for it.
+      const multi = target.closest<HTMLElement>('.sb-tapgesture[data-sb-tap-count]');
+      const single = target.closest<HTMLElement>('.sb-tapgesture:not([data-sb-tap-count])');
+      this.taps.click(multi, Number(multi?.dataset['sbTapCount'] ?? 1), single, { x: event.clientX, y: event.clientY });
       return;
     }
     this.onEvent({ type: 'tap', id });
   };
 
+  /** A `tapgesture` fires: with `location`, the click's point in the element's own coordinates (points; the device frame may be scaled). */
+  private readonly taps = new TapCounter<HTMLElement, { x: number; y: number }>((el, point) => {
+    const id = Number(el.dataset[ID_ATTR]);
+    if (!Number.isInteger(id)) return;
+    if (el.hasAttribute('data-sb-tap-location')) {
+      const rect = el.getBoundingClientRect();
+      const scale = el.offsetWidth > 0 ? rect.width / el.offsetWidth : 1;
+      const x = Math.round(((point.x - rect.left) / (scale || 1)) * 100) / 100;
+      const y = Math.round(((point.y - rect.top) / (scale || 1)) * 100) / 100;
+      this.onEvent({ type: 'tap', id, x, y });
+      return;
+    }
+    this.onEvent({ type: 'tap', id });
+  });
+
   /**
    * Phase 12: after a commit, the bound text fields (`data-sb-focus`) take or
    * give up focus to match what Swift asked for. The `focus` event the move
-   * raises is echoed back so the state and the DOM agree.
+   * raises is echoed back so the state and the DOM agree. A field the app
+   * focuses is scrolled into view (`revealFocused`), as SwiftUI shows a
+   * field its `@FocusState` focuses.
    */
   private syncFocus(): void {
     const active = document.activeElement;
@@ -658,11 +697,30 @@ export class Renderer {
       // `preventScroll`: a field in a sheet still sliding in sits below the
       // screen, and the browser would scroll the whole screen to reveal it,
       // blanking the page until something scrolls it back.
-      if (wanted && active !== input) input.focus({ preventScroll: true });
-      else if (!wanted && active === input) input.blur();
+      if (wanted && active !== input) {
+        if (isRichEditor(input)) focusRichEditor(input);
+        else if (isPlainEditor(input)) focusPlainEditor(input);
+        else input.focus({ preventScroll: true });
+        this.revealFocused(input);
+      } else if (!wanted && active === input) input.blur();
     }
   }
 
+  /**
+   * Scrolls the scroll views and lists around a text input as little as
+   * shows it, from the layout's frames (src/scrollTo.ts), never the page:
+   * the frames are where the views rest, so a sheet still sliding in is no
+   * reason to scroll, and in device mode they already stop above the
+   * keyboard, which the focus raised before this ran (`watchKeyboard`
+   * reports its known height on `focusin`, and `setKeyboard` lays out).
+   */
+  private revealFocused(input: HTMLElement): void {
+    const result = this.layoutResult;
+    const id = Number(input.dataset[ID_ATTR]);
+    if (!result || !Number.isInteger(id)) return;
+    scrollToTarget(this, result, id, undefined, false);
+  }
+
   /**
    * `.scrollDismissesKeyboard`: scrolling a list or scroll view marked
    * `data-sb-dismisses-keyboard` takes the focus from the text input being
@@ -672,16 +730,34 @@ export class Renderer {
     const scroller = event.target;
     if (!(scroller instanceof HTMLElement) || scroller.dataset['sbDismissesKeyboard'] !== 'true') return;
     const active = document.activeElement;
-    if ((active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement) && scroller.contains(active)) active.blur();
+    if ((active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement || isRichEditor(active)) && scroller.contains(active)) (active as HTMLElement).blur();
+  };
+
+  /**
+   * A press anywhere but another text input leaves the text being edited
+   * focused, as on iOS, where only a text input takes the first responder
+   * (a Bold button acts on the selection still there; a stepper, a row or
+   * the space beside the editor leaves the keyboard up): the mouse down
+   * that would move the focus does nothing else.
+   */
+  private readonly onControlMouseDown = (event: MouseEvent): void => {
+    const active = document.activeElement;
+    const editing = active instanceof HTMLInputElement || active instanceof HTMLTextAreaElement || isRichEditor(active);
+    if (!editing || !this.root.contains(active)) return;
+    const target = event.target as HTMLElement | null;
+    if (target && !target.closest('input, textarea, [contenteditable]')) event.preventDefault();
   };
 
   /** Phase 12: a bound field (`data-sb-focus`) reports focus changes. */
   private readonly onFocusChange = (event: FocusEvent): void => {
+    // A screen's `keyboard` toolbars show while one of its text inputs is
+    // focused: the focus moving is a layout change there.
+    if (this.commits > 0 && this.hasKeyboardToolbars()) this.layout();
     // A bound `texteditor` (UIKit's text views) reports focus like a field.
     const input = event.target as HTMLElement | null;
     const isField =
       (input instanceof HTMLInputElement || input instanceof HTMLTextAreaElement) && input.classList.contains('sb-textfield');
-    const isEditor = input instanceof HTMLTextAreaElement && input.classList.contains('sb-texteditor');
+    const isEditor = (input instanceof HTMLTextAreaElement || isRichEditor(input)) && input!.classList.contains('sb-texteditor');
     if (!input || (!isField && !isEditor)) return;
     if (input.dataset['sbFocus'] === undefined || !this.root.contains(input)) return;
     const id = Number(input.dataset[ID_ATTR]);
@@ -718,7 +794,8 @@ export class Renderer {
     if (
       !target.classList.contains('sb-navlink') &&
       !target.classList.contains('sb-menu') &&
-      !(target.classList.contains('sb-picker') && target.dataset['sbStyle'] === 'menu')
+      !(target.classList.contains('sb-picker') && target.dataset['sbStyle'] === 'menu') &&
+      !(target.classList.contains('sb-toggle') && target.dataset['sbToggleStyle'] === 'button')
     ) {
       return;
     }
@@ -743,6 +820,23 @@ export class Renderer {
     }
   };
 
+  /**
+   * Backspace in a `textfield` or plain `texteditor` with `deleteBackward`,
+   * nothing selected and the caret at the start: the key deletes nothing
+   * and the app hears `deletebackward` (the rich editor's own `beforeinput`
+   * does the same, src/richEditor.ts).
+   */
+  private readonly onBeforeInput = (event: InputEvent): void => {
+    if (event.inputType !== 'deleteContentBackward') return;
+    const input = event.target;
+    if (!(input instanceof HTMLInputElement || input instanceof HTMLTextAreaElement) || !this.root.contains(input) || !wantsDeleteBackward(input)) return;
+    if (input.selectionStart !== 0 || input.selectionEnd !== 0) return;
+    const id = Number(input.dataset[ID_ATTR]);
+    if (!Number.isInteger(id)) return;
+    event.preventDefault();
+    this.onEvent({ type: 'deletebackward', id });
+  };
+
   private readonly onInput = (event: Event): void => {
     const input = event.target as HTMLInputElement | null;
     if (!input || !this.root.contains(input)) return;
@@ -754,7 +848,8 @@ export class Renderer {
     const owner = isField ? input : input.closest<HTMLElement>('.sb-searchfield');
     const id = Number(owner?.dataset[ID_ATTR]);
     if (!Number.isInteger(id)) return;
-    this.onEvent({ type: 'text', id, value: input.value });
+    const value = isRichEditor(input) ? richEditorText(input) : input.value;
+    this.onEvent({ type: 'text', id, value });
   };
 
   /**
@@ -879,7 +974,9 @@ export class Renderer {
     // created detached and moved around freely.
     root.addEventListener('click', this.onClick);
     root.addEventListener('pointerdown', this.onRowPress);
+    root.addEventListener('mousedown', this.onControlMouseDown);
     root.addEventListener('keydown', this.onKeyDown);
+    root.addEventListener('beforeinput', this.onBeforeInput);
     root.addEventListener('input', this.onInput);
     root.addEventListener('focusin', this.onFocusChange);
     root.addEventListener('focusout', this.onFocusChange);
@@ -949,8 +1046,48 @@ export class Renderer {
       });
     }
     this.stopHostChanges = onHostContentChange(() => this.hostContentChanged());
+    const editorId = (el: HTMLElement): number | null => {
+      const id = Number(el.dataset[ID_ATTR]);
+      return Number.isInteger(id) ? id : null;
+    };
+    this.stopRichEditors = listenToRichEditors(root, editorId, (event) => this.onEvent(event));
+    // After `onInput` above, so a keystroke's `text` goes before its `selection`.
+    this.stopPlainEditors = listenToPlainEditors(root, editorId, (event) => this.onEvent(event));
     this.hover = new HoverTracker(root, (id, value) => this.onEvent({ type: 'hover', id, value }));
     root.addEventListener('scroll', this.queueFrameCheck, { capture: true, passive: true });
+    // Scroll transitions and pinned views follow the scroll in the frame it is drawn in.
+    root.addEventListener('scroll', drawScrollTransitions, { capture: true, passive: true });
+    root.addEventListener('scroll', drawPinnedViews, { capture: true, passive: true });
+    root.addEventListener('scroll', this.queueScrollGeometryCheck, { capture: true, passive: true });
+  }
+
+  /**
+   * `reportsGeometry` scroll views report where they are once per animation
+   * frame while anything scrolls (the offsets change without a layout pass).
+   */
+  private readonly queueScrollGeometryCheck = (): void => {
+    if (this.scrollGeometryQueued || this.commits === 0 || this.scrollReporters.size === 0) return;
+    this.scrollGeometryQueued = true;
+    requestAnimationFrame(() => {
+      this.scrollGeometryQueued = false;
+      if (!this.layoutResult) return;
+      this.collectScrollGeometry(this.layoutResult);
+      if (this.applying === 0) this.flushGeometry();
+    });
+  };
+
+  /** Queue a `scrollgeometry` event for every reporting scroll view whose geometry changed. */
+  private collectScrollGeometry(result: LayoutResult): void {
+    for (const id of this.scrollReporters) {
+      const el = this.elements.get(id);
+      if (!el || !el.isConnected) continue;
+      const frame = result.frames.get(id);
+      if (!frame) continue; // inside a hidden tab
+      const covered = result.chrome.get(id)?.['bottomInset'];
+      const bottomInset = covered ? Math.max(0, frame.y + frame.height - covered.y) : 0;
+      const event = this.scrollGeometry.report(id, readScrollGeometry(el, frame, result.contentSizes.get(id), bottomInset));
+      if (event) this.pendingGeometry.push(event);
+    }
   }
 
   /**
@@ -1080,11 +1217,16 @@ export class Renderer {
           // from the page's last layout, without them.
           this.root.dispatchEvent(new CustomEvent('sb:precommit', { detail: { commits: this.commits + 1 } }));
           const changes = this.layout();
-          this.animator.commitNextFrame(pass, op.animation, changes);
+          const completion = op.completion;
+          this.animator.commitNextFrame(pass, op.animation, changes, typeof completion === 'number' ? (started) => this.completeAnimation(completion, started) : undefined);
           this.beginBarMorphsNextFrame();
           this.commits += 1;
+          const focusedBefore = this.focusedFieldId();
           this.syncFocus();
+          // The focus the app moved shows or hides a screen's keyboard bar.
+          if (this.focusedFieldId() !== focusedBefore && this.hasKeyboardToolbars()) this.layout();
           this.performScrolls(op.animation != null);
+          this.performOffsetScrolls(op.animation != null);
           this.checkLazySpacers();
           this.openPendingMenu();
           this.root.dispatchEvent(
@@ -1100,6 +1242,26 @@ export class Renderer {
     }
   }
 
+  /**
+   * `withAnimation(_:completionCriteria:_:completion:)`: the pass's `commit`
+   * carried a completion serial; once the animations its commit started have
+   * ended (at once when it started none) the app hears `animationcomplete`.
+   * An animation that never ends (`repeatForever`) counts as ended after one
+   * run of its duration, as `.logicallyComplete` does.
+   */
+  private completeAnimation(serial: number, started: readonly globalThis.Animation[]): void {
+    const ended = started.map((animation) => {
+      const timing = animation.effect?.getComputedTiming();
+      const end = timing?.endTime;
+      if (typeof end === 'number' && Number.isFinite(end)) return animation.finished.then(() => undefined, () => undefined);
+      const run = (Number(timing?.delay) || 0) + (Number(timing?.duration) || 0);
+      return new Promise<void>((resolve) => window.setTimeout(resolve, run));
+    });
+    const send = (): void => this.onEvent({ type: 'animationcomplete', serial });
+    if (ended.length === 0) send();
+    else void Promise.all(ended).then(send, send);
+  }
+
   /**
    * Whether the pass starting at `ops[start]` can animate: its `commit` has
    * an animation, or one of its updates changes an `animationToken`
@@ -1276,8 +1438,28 @@ export class Renderer {
   setKeyboard(height: number): void {
     const next = Number.isFinite(height) && height > 0 ? Math.round(height) : 0;
     if (next === this.keyboard) return;
+    const rose = next > this.keyboard;
     this.keyboard = next;
-    if (this.commits > 0) this.layout();
+    if (this.commits === 0) return;
+    this.layout();
+    // The keyboard covers more: the text input being edited comes out from under it, as iOS keeps it above the keyboard.
+    const active = document.activeElement;
+    if (rose && active instanceof HTMLElement && this.root.contains(active) && (active.classList.contains('sb-textfield') || active.classList.contains('sb-texteditor'))) {
+      this.revealFocused(active);
+    }
+  }
+
+  /**
+   * The size `text` in `fontProps` (a Font JSON object over the body font)
+   * takes wrapped to `width` (one line when null), with the typography the
+   * layout engine lays `text` elements out with: for an app that paginates
+   * or sizes from its text (@swiftbrowser/react's `measureText`).
+   */
+  measureText(text: string, fontProps: unknown, width: number | null): { width: number; height: number; lines: number } {
+    const env = this.layoutEnvironment();
+    const font = resolveFont(fontProps, defaultFont(env), env);
+    const wrapped = wrapText(text, font, width, null, this.measurer);
+    return { width: wrapped.width, height: textHeight(wrapped.lines.length, font), lines: wrapped.lines.length };
   }
 
   /**
@@ -1293,6 +1475,7 @@ export class Renderer {
   layoutEnvironment(): LayoutEnvironment {
     const screen = this.resizeObserver ? (this.rootSize ??= this.readRootSize()) : this.readRootSize();
     if (!this.safeArea) this.safeArea = readSafeArea(this.root);
+    const focused = this.focusedFieldId();
     return {
       screen: { ...screen },
       safeArea: this.safeArea,
@@ -1302,9 +1485,25 @@ export class Renderer {
       assets: this.assets,
       ...(this.contentHeight ? { contentHeight: true } : {}),
       ...(this.keyboard > 0 ? { keyboard: this.keyboard } : {}),
+      ...(focused !== null ? { focusedField: focused } : {}),
     };
   }
 
+  /** The element id of the text input being edited in the root (a field, an editor or a search field's input), or null. */
+  private focusedFieldId(): number | null {
+    const active = typeof document === 'undefined' ? null : document.activeElement;
+    if (!(active instanceof HTMLElement) || !this.root.contains(active)) return null;
+    const owner = active.classList.contains('sb-searchfield-input') ? active.closest<HTMLElement>('.sb-searchfield') : active;
+    if (!owner || !(owner.classList.contains('sb-textfield') || owner.classList.contains('sb-texteditor') || owner.classList.contains('sb-searchfield'))) return null;
+    const id = Number(owner.dataset[ID_ATTR]);
+    return Number.isInteger(id) ? id : null;
+  }
+
+  /** Whether a screen has `keyboard` toolbars: their bar follows the focus, so a focus change lays out again. */
+  private hasKeyboardToolbars(): boolean {
+    return this.root.querySelector('.sb-toolbar[data-sb-placement="keyboard"]') !== null;
+  }
+
   private readRootSize(): { width: number; height: number } {
     return {
       width: this.root.clientWidth || DEFAULT_SCREEN.width,
@@ -1481,7 +1680,10 @@ export class Renderer {
       }
       this.root.style.height = `${bottom + env.safeArea.bottom}px`;
     }
+    drawScrollTransitions();
+    drawPinnedViews();
     this.collectGeometry(result);
+    this.collectScrollGeometry(result);
     this.collectLayouts(result);
     if (this.applying === 0) this.flushGeometry();
     this.queueVisibilityCheck();
@@ -1731,12 +1933,18 @@ export class Renderer {
     this.closeMenu();
     this.root.removeEventListener('click', this.onClick);
     this.root.removeEventListener('pointerdown', this.onRowPress);
+    this.root.removeEventListener('mousedown', this.onControlMouseDown);
     this.root.removeEventListener('keydown', this.onKeyDown);
+    this.root.removeEventListener('beforeinput', this.onBeforeInput);
     this.root.removeEventListener('input', this.onInput);
     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.queueFrameCheck, true);
+    this.root.removeEventListener('scroll', drawScrollTransitions, true);
+    this.root.removeEventListener('scroll', drawPinnedViews, true);
+    this.root.removeEventListener('scroll', this.queueScrollGeometryCheck, true);
     this.root.removeEventListener('scroll', this.onPositionScroll, true);
     this.root.removeEventListener('scrollend', this.onPositionScrollEnd, true);
     this.root.removeEventListener('touchstart', this.onPositionTouchStart, true);
@@ -1753,8 +1961,11 @@ export class Renderer {
     this.resizeObserver?.disconnect();
     this.hostObserver?.disconnect();
     this.stopHostChanges();
+    this.stopRichEditors();
+    this.stopPlainEditors();
     this.hover.dispose();
     this.root.removeEventListener('scroll', this.queueFrameCheck, true);
+    this.root.removeEventListener('scroll', drawScrollTransitions, true);
     this.root.removeEventListener('change', this.onChange);
     this.root.removeEventListener('pointerdown', this.onSliderPointerDown);
     this.reset();
@@ -1768,8 +1979,14 @@ export class Renderer {
     if (id === ROOT_ID) throw new RendererError('Element 0 is the root and cannot be created', op);
     if (this.elements.has(id)) throw new RendererError(`Element ${id} already exists`, op);
     if (!ALL_KINDS.has(kind)) throw new RendererError(`Unknown element kind ${String(kind)}`, op);
-    // A vertical `textfield` is a `<textarea>` (its axis is fixed at creation).
-    const el = kind === 'textfield' && (props as TextFieldProps).axis === 'vertical' ? createMultilineField() : createShell(kind);
+    // A vertical `textfield` is a `<textarea>` (its axis is fixed at creation),
+    // a `texteditor` with runs the rich editor (src/richEditor.ts).
+    const el =
+      kind === 'textfield' && (props as TextFieldProps).axis === 'vertical'
+        ? createMultilineField()
+        : kind === 'texteditor' && Array.isArray((props as TextEditorProps).runs)
+          ? createRichEditor()
+          : createShell(kind);
     el.className = `sb-${kind}`;
     el.dataset[ID_ATTR] = String(id);
     el.dataset[KIND_ATTR] = kind;
@@ -2011,8 +2228,20 @@ export class Renderer {
     this.onEvent({ type: 'scrollposition', id: target });
   }
 
-  /** A `styled` whose style carries a `scrollTo` not seen before is scrolled to after this pass's layout. */
+  /**
+   * A `styled` whose style carries a `scrollTo` not seen before is scrolled
+   * to after this pass's layout; so is a `scrollview` whose `scrollOffset`
+   * command is new. A `scrollview` with `reportsGeometry` is noted to report.
+   */
   private noteScroll(id: ElementId, kind: ElementKind, props: ElementProps): void {
+    if (kind === 'scrollview') {
+      const scroll = props as ScrollViewProps;
+      if (scroll.reportsGeometry === true) this.scrollReporters.add(id);
+      else this.scrollReporters.delete(id);
+      const serial = scroll.scrollOffset?.serial;
+      if (typeof serial === 'number' && serial > (this.offsetSerials.get(id) ?? 0)) this.pendingOffsets.push(id);
+      return;
+    }
     if (kind !== 'styled') return;
     const serial = (props as StyledProps)?.style?.scrollTo?.serial;
     if (typeof serial !== 'number' || serial <= this.scrollSerial) return;
@@ -2070,6 +2299,33 @@ export class Renderer {
     for (const { command } of commands) this.scrollSerial = Math.max(this.scrollSerial, command.serial);
   }
 
+  /**
+   * `scrollOffset` (a `.scrollPosition` bound to a point, `scrollTo(x:y:)`):
+   * each scroll view with a command not carried out yet scrolls to it,
+   * smoothly when the pass's commit is animated; an axis the command leaves
+   * out keeps its offset. The view reports its position afresh when it next
+   * settles, as after a `scrollTo` to a target.
+   */
+  private performOffsetScrolls(animated: boolean): void {
+    if (this.pendingOffsets.length === 0) return;
+    const ids = this.pendingOffsets;
+    this.pendingOffsets = [];
+    for (const id of ids) {
+      const el = this.elements.get(id);
+      const command = (this.nodes.get(id)?.props as Partial<ScrollViewProps> | undefined)?.scrollOffset;
+      if (!el || !command || !(command.serial > (this.offsetSerials.get(id) ?? 0))) continue;
+      this.offsetSerials.set(id, command.serial);
+      const left = typeof command.x === 'number' && Number.isFinite(command.x) ? Math.max(0, command.x) : el.scrollLeft;
+      const top = typeof command.y === 'number' && Number.isFinite(command.y) ? Math.max(0, command.y) : el.scrollTop;
+      if (animated && typeof el.scrollTo === 'function') el.scrollTo({ left, top, behavior: 'smooth' });
+      else {
+        el.scrollLeft = left;
+        el.scrollTop = top;
+      }
+      this.reportedPositions.delete(el);
+    }
+  }
+
   private update(id: ElementId, props: ElementProps, op: Op): void {
     if (id === ROOT_ID) {
       // Phase 12: the root carries no element props; an update of it is the
@@ -2397,6 +2653,9 @@ export class Renderer {
     this.boxes.delete(id);
     this.dirty.delete(id);
     this.reportedGeometry.delete(id);
+    this.scrollReporters.delete(id);
+    this.scrollGeometry.forget(id);
+    this.offsetSerials.delete(id);
     this.geometryReporters.delete(id);
     this.layoutReporter.forget(id);
     const node = this.nodes.get(id);
@@ -2689,7 +2948,10 @@ function createShell(kind: ElementKind): HTMLElement {
       bar.append(back, inlineTitle, div('sb-navbar-trailing'), more);
       const body = div('sb-navscreen-body');
       const slot = div('sb-slot sb-navscreen-content');
-      body.append(div('sb-navbar-large-title'), slot);
+      // The `keyboard` toolbars' bar (chrome `keyboardBar`), under their items.
+      const keyboardBar = div('sb-keyboard-bar');
+      keyboardBar.hidden = true;
+      body.append(div('sb-navbar-large-title'), slot, keyboardBar);
       // Phase 8: a 24px strip along the leading edge of a pushed screen
       // that, on touch devices, keeps the browser from scrolling so a swipe
       // back can start there (styles.css; the controller forwards plain taps).
@@ -3015,15 +3277,14 @@ function listRowOf(el: HTMLElement, root: HTMLElement): HTMLElement | null {
 
 /** Controls a row may hold besides its button for the row to stay the button's: none. */
 const ROW_CONTROLS =
-  'input, textarea, .sb-navlink, .sb-switch, .sb-picker, .sb-stepper, .sb-slider, .sb-menu, .sb-tapgesture, .sb-link, .sb-datepicker';
+  'input, textarea, [contenteditable], .sb-navlink, .sb-switch, .sb-picker, .sb-stepper, .sb-slider, .sb-menu, .sb-tapgesture, .sb-link, .sb-datepicker';
 
 /**
  * A list row holding one button (with other views beside it, or under a
  * modifier) taps the button wherever it is tapped, as a UITableView cell
  * does on iOS; a row that is the button itself is that already. Not a
- * `.plain` or `.borderless` button (both arrive as `plain`), which SwiftUI
- * keeps to its own label in a row, a disabled one, or a row with other
- * controls.
+ * `.plain` or `.borderless` button, which SwiftUI keeps to its own label in
+ * a row, a disabled one, or a row with other controls.
  */
 function rowAction(el: HTMLElement, root: HTMLElement): HTMLElement | null {
   const row = listRowOf(el, root);
@@ -3031,7 +3292,7 @@ function rowAction(el: HTMLElement, root: HTMLElement): HTMLElement | null {
   const buttons = row.querySelectorAll<HTMLElement>('.sb-button');
   if (buttons.length !== 1) return null;
   const button = buttons[0]!;
-  if (button.dataset['sbStyle'] === 'plain' || button.closest('[data-sb-disabled]')) return null;
+  if (button.dataset['sbStyle'] === 'plain' || button.dataset['sbStyle'] === 'borderless' || button.closest('[data-sb-disabled]')) return null;
   if (row.querySelector(ROW_CONTROLS)) return null;
   return button;
 }
@@ -3449,6 +3710,9 @@ function applyTextEditor(area: HTMLTextAreaElement, props: TextEditorProps): voi
   // Bound focus, as for a `textfield` (moved in `syncFocus` after the commit).
   if (typeof props.focused === 'boolean') area.dataset['sbFocus'] = String(props.focused);
   else delete area.dataset['sbFocus'];
+  markDeleteBackward(area, props.deleteBackward === true);
+  // A bound selection, under the rich editor's rules (src/plainEditor.ts).
+  applyPlainEditorSelection(area, props);
 }
 
 // ---------------------------------------------------------------------------
@@ -3482,10 +3746,12 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
     case 'vstack':
       applyVStack(el, props as VStackProps);
       applyScrollTarget(el, (props as VStackProps).scrollTarget === true);
+      setPinnedViews(el, (props as VStackProps).pinned);
       break;
     case 'hstack':
       applyHStack(el, props as HStackProps);
       applyScrollTarget(el, (props as HStackProps).scrollTarget === true);
+      setPinnedViews(el, (props as HStackProps).pinned);
       break;
     case 'spacer':
       applySpacer(el, props as SpacerProps);
@@ -3502,10 +3768,15 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
     case 'image':
       applyImage(el, props as ImageProps, assets);
       break;
-    case 'tapgesture':
-      // `location`: the tap is sent with its point (`onTapGesture { point in }`).
-      el.toggleAttribute('data-sb-tap-location', (props as TapGestureProps | undefined)?.location === true);
+    case 'tapgesture': {
+      // `location`: the tap is sent with its point (`onTapGesture { point in }`); `count`: the taps it takes.
+      const tap = props as TapGestureProps | undefined;
+      el.toggleAttribute('data-sb-tap-location', tap?.location === true);
+      const count = Math.floor(tap?.count ?? 1);
+      if (count > 1) el.dataset['sbTapCount'] = String(count);
+      else delete el.dataset['sbTapCount'];
       break;
+    }
     case 'divider':
     case 'navstack':
     case 'geometry':
@@ -3535,7 +3806,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 === 'largeTitle' ? placement : 'trailing';
+        placement === 'leading' || placement === 'principal' || placement === 'bottom' || placement === 'largeTitle' || placement === 'keyboard' ? placement : 'trailing';
       // A `ToolbarSpacer`: draws nothing.
       el.toggleAttribute('data-sb-spacer', typeof (props as ToolbarProps).spacer === 'string');
       break;
@@ -3595,9 +3866,22 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
     case 'textfield':
       applyTextField(el as HTMLInputElement | HTMLTextAreaElement, props as TextFieldProps);
       break;
-    case 'toggle':
-      setSwitchState(el, Boolean((props as ToggleProps).isOn));
+    case 'toggle': {
+      const toggle = props as ToggleProps;
+      // `switch` is marked too, so a bar draws it as a switch, not its own toggle.
+      if (toggle.style === 'button' || toggle.style === 'switch') el.dataset['sbToggleStyle'] = toggle.style;
+      else delete el.dataset['sbToggleStyle'];
+      if (toggle.style === 'button') {
+        el.setAttribute('role', 'button');
+        el.tabIndex = 0;
+      } else if (el.getAttribute('role') === 'button') {
+        el.removeAttribute('role');
+        el.removeAttribute('aria-pressed');
+        el.removeAttribute('tabindex');
+      }
+      setSwitchState(el, Boolean(toggle.isOn));
       break;
+    }
     case 'navscreen':
       applyNavScreen(el, props as NavScreenProps);
       break;
@@ -3627,12 +3911,14 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
       const grid = props as LazyVGridProps;
       el.dataset['sbAlignment'] = grid.alignment ?? 'center';
       el.dataset['sbColumns'] = String(Array.isArray(grid.columns) ? grid.columns.length : 0);
+      setPinnedViews(el, grid.pinned);
       break;
     }
     case 'lazyhgrid': {
       const grid = props as LazyHGridProps;
       el.dataset['sbAlignment'] = grid.alignment ?? 'center';
       el.dataset['sbRows'] = String(Array.isArray(grid.rows) ? grid.rows.length : 0);
+      setPinnedViews(el, grid.pinned);
       break;
     }
     case 'gauge':
@@ -3709,7 +3995,8 @@ function applyKindProps(el: HTMLElement, kind: ElementKind, props: ElementProps,
       applyDatePicker(el, (props as DatePickerProps) ?? {});
       break;
     case 'texteditor':
-      applyTextEditor(el as HTMLTextAreaElement, (props as TextEditorProps) ?? {});
+      if (isRichEditor(el)) applyRichEditor(el, (props as TextEditorProps) ?? {});
+      else applyTextEditor(el as HTMLTextAreaElement, (props as TextEditorProps) ?? {});
       break;
     case 'sectionheader':
     case 'sectionfooter':
@@ -3759,6 +4046,7 @@ function runTemplate(run: TextRun, assets: AssetCatalog): HTMLElement {
   }
   const s = el.style;
   if (run.foreground !== undefined) s.color = styleToCSS(run.foreground as ShapeStyle, 'text').solid;
+  if (run.background !== undefined) s.backgroundColor = styleToCSS(run.background as ShapeStyle, 'paint').solid ?? '';
   const lines: string[] = [];
   let lineColor: unknown;
   if (run.underline) {
@@ -3999,28 +4287,36 @@ function applyImage(el: HTMLElement, props: ImageProps, assets: AssetCatalog): v
   if (isUrlImage(props)) {
     // Phase 13: the page decoded this URL for `AsyncImage` already, so the
     // <img> shows at once; the layout engine sized the box from the props.
+    // A `file:` URL of the app's files loads at the object URL the files
+    // host makes of it (hostRequests.ts `loadableURL`), once it has.
     delete el.dataset['sbSymbol'];
     delete el.dataset['sbAsset'];
+    const changed = el.dataset['sbUrl'] !== props.url;
     el.dataset['sbUrl'] = props.url;
     if (props.resizable) el.dataset['sbResizable'] = '';
     else delete el.dataset['sbResizable'];
     // React's opt-in to the browser's own image interactions (styles.css).
     const web = props.webInteractions === true;
     el.toggleAttribute('data-sb-web', web);
+    const url = props.url;
     const existing = el.firstElementChild;
     if (existing instanceof HTMLImageElement) {
       existing.draggable = web;
-      if (existing.getAttribute('src') !== props.url && existing.dataset['sbPending'] !== props.url) {
-        swapImageSource(existing, props.url);
+      if (changed) {
+        const loadable = loadableURL(url);
+        if (typeof loadable === 'string') swapImageSource(existing, loadable);
+        else void loadable.then((src) => el.dataset['sbUrl'] === url && swapImageSource(existing, src));
       }
       return;
     }
     const img = document.createElement('img');
-    img.src = props.url;
+    const loadable = loadableURL(url);
+    if (typeof loadable === 'string') img.src = loadable;
+    else void loadable.then((src) => el.dataset['sbUrl'] === url && img.setAttribute('src', src));
     img.alt = '';
     img.draggable = web;
     img.decoding = 'async';
-    found(props.url, img);
+    found(url, img);
     return;
   }
   delete el.dataset['sbUrl'];
@@ -4131,6 +4427,7 @@ function applyTextField(input: HTMLInputElement | HTMLTextAreaElement, props: Te
   }
   if (props.submit === true) input.dataset['sbSubmit'] = 'true';
   else delete input.dataset['sbSubmit'];
+  markDeleteBackward(input, props.deleteBackward === true);
   if (typeof props.submitLabel === 'string' && props.submitLabel.length > 0) input.enterKeyHint = props.submitLabel;
   else input.removeAttribute('enterkeyhint');
   applyTextInputHints(input, props);
@@ -4202,6 +4499,7 @@ function applySearchField(el: HTMLElement, props: SearchFieldProps): void {
 
 function setSwitchState(toggle: HTMLElement, isOn: boolean): void {
   toggle.dataset['sbOn'] = String(isOn);
+  if (toggle.dataset['sbToggleStyle'] === 'button') toggle.setAttribute('aria-pressed', String(isOn));
   const sw = toggle.querySelector<HTMLElement>(':scope > .sb-switch');
   sw?.setAttribute('aria-checked', String(isOn));
 }
@@ -4498,6 +4796,9 @@ export function applyStyle(el: HTMLElement, style: Style): void {
     s.pointerEvents = 'none';
     el.dataset['sbHitTesting'] = 'false';
   }
+  // `.contentShape(Rectangle())`: the box takes input across its area, which a box already does; marked for the stylesheet and tests.
+  if (style.contentShape) el.dataset['sbContentShape'] = style.contentShape;
+  else delete el.dataset['sbContentShape'];
   // Hover, tooltips, cursors, symbol effects and matched geometry ids (pointerEffects.ts).
   applyPointerAndEffects(el, style);
 
@@ -4522,9 +4823,17 @@ export function applyStyle(el: HTMLElement, style: Style): void {
   if (style.blendMode) s.mixBlendMode = style.blendMode;
   else if (s.mixBlendMode) s.mixBlendMode = '';
   // `.zIndex`: in front of siblings with a lower index (boxes are positioned).
-  // CSS takes integers; ×1000 keeps fractional indices (0.5) apart.
-  if (style.zIndex != null && Number.isFinite(style.zIndex)) s.zIndex = String(Math.round(style.zIndex * 1000));
-  else if (s.zIndex) s.zIndex = '';
+  // CSS takes integers; ×1000 keeps fractional indices (0.5) apart. The
+  // stack it is in stacks its children on its own (styles.css,
+  // `[data-sb-z]`), so a negative index orders the box among its siblings
+  // only, as SwiftUI's does, and never sends it behind the views around.
+  if (style.zIndex != null && Number.isFinite(style.zIndex)) {
+    s.zIndex = String(Math.round(style.zIndex * 1000));
+    el.dataset['sbZ'] = '';
+  } else if (s.zIndex) {
+    s.zIndex = '';
+    delete el.dataset['sbZ'];
+  }
 
   // Phase 3 text and layout hints (the engine reads them from the node tree).
   if (style.layoutPriority != null && Number.isFinite(style.layoutPriority)) {
@@ -4570,6 +4879,8 @@ export function applyStyle(el: HTMLElement, style: Style): void {
     const { x, y } = style.gridCellAnchor;
     el.dataset['sbGridCellAnchor'] = `${x} ${y}`;
   }
+  // `.scrollTransition`: drawn over the effects above as the box scrolls (scrollTransition.ts).
+  setScrollTransition(el, style);
 }
 
 // Colors and ShapeStyles resolve in src/styles.ts; re-exported for callers of the renderer.