@swifttui/web 0.0.10 → 0.0.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swifttui/web",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "license": "MIT",
   "module": "index.ts",
   "exports": {

package/src/WebHostSceneRuntime.test.ts

@@ -7,7 +7,7 @@ import {
 } from "./wasi/BrowserWASIBridge.ts";
 import { SharedInputQueueReader } from "./wasi/SharedInputQueue.ts";
 import { createWasmSceneRuntimeFactory } from "./wasi/WasmSceneRuntime.ts";
-import { WebHostSceneRuntime } from "./WebHostSceneRuntime.ts";
+import { WebHostSceneRuntime, type WheelMode } from "./WebHostSceneRuntime.ts";
 import { transportFixture } from "./WebHostTestFixtures.ts";
 
 const encoder = new TextEncoder();
@@ -1211,6 +1211,114 @@ test("runtime can run as a passive embed without stealing focus or wheel scroll"
   }
 });
 
+test("chain mode captures the wheel when a region under the pointer can scroll", async () => {
+  const dom = installFakeDOM();
+  try {
+    // Region covers the whole 4x2 surface; content is taller than the viewport
+    // and scrolled to the top, so a downward wheel has headroom.
+    const result = await wheelScenario({
+      wheelMode: "chain",
+      scrollRegions: [{ id: "list", rect: [0, 0, 4, 2], offset: [0, 0], content: [4, 10] }],
+      wheel: { clientX: 5, clientY: 5, deltaY: 20 },
+    });
+    expect(result.captured).toBe(true);
+    expect(result.wheelPrevented).toBe(true);
+  } finally {
+    dom.restore();
+  }
+});
+
+test("chain mode lets the wheel fall through at the region's scroll edge", async () => {
+  const dom = installFakeDOM();
+  try {
+    // Same region, but scrolled to the bottom (offset.y == maxY == 10 - 2),
+    // so a further downward wheel has no headroom and must chain to the page.
+    const result = await wheelScenario({
+      wheelMode: "chain",
+      scrollRegions: [{ id: "list", rect: [0, 0, 4, 2], offset: [0, 8], content: [4, 10] }],
+      wheel: { clientX: 5, clientY: 5, deltaY: 20 },
+    });
+    expect(result.captured).toBe(false);
+    expect(result.wheelPrevented).toBe(false);
+  } finally {
+    dom.restore();
+  }
+});
+
+test("chain mode captures an upward wheel when scrolled away from the top", async () => {
+  const dom = installFakeDOM();
+  try {
+    // At the bottom edge, downward chains but upward still has headroom.
+    const result = await wheelScenario({
+      wheelMode: "chain",
+      scrollRegions: [{ id: "list", rect: [0, 0, 4, 2], offset: [0, 8], content: [4, 10] }],
+      wheel: { clientX: 5, clientY: 5, deltaY: -20 },
+    });
+    expect(result.captured).toBe(true);
+    expect(result.wheelPrevented).toBe(true);
+  } finally {
+    dom.restore();
+  }
+});
+
+test("chain mode falls through when the pointer is outside every scroll region", async () => {
+  const dom = installFakeDOM();
+  try {
+    // Region only covers the right half (cells x>=2); wheel at cell (0,0).
+    const result = await wheelScenario({
+      wheelMode: "chain",
+      scrollRegions: [{ id: "list", rect: [2, 0, 2, 2], offset: [0, 0], content: [2, 10] }],
+      wheel: { clientX: 5, clientY: 5, deltaY: 20 },
+    });
+    expect(result.captured).toBe(false);
+    expect(result.wheelPrevented).toBe(false);
+  } finally {
+    dom.restore();
+  }
+});
+
+test("chain mode falls through when the scene publishes no scroll regions", async () => {
+  const dom = installFakeDOM();
+  try {
+    const result = await wheelScenario({
+      wheelMode: "chain",
+      wheel: { clientX: 5, clientY: 5, deltaY: 20 },
+    });
+    expect(result.captured).toBe(false);
+    expect(result.wheelPrevented).toBe(false);
+  } finally {
+    dom.restore();
+  }
+});
+
+test("capture mode always eats the wheel even without scroll regions", async () => {
+  const dom = installFakeDOM();
+  try {
+    const result = await wheelScenario({
+      wheelMode: "capture",
+      wheel: { clientX: 5, clientY: 5, deltaY: 20 },
+    });
+    expect(result.captured).toBe(true);
+    expect(result.wheelPrevented).toBe(true);
+  } finally {
+    dom.restore();
+  }
+});
+
+test("legacy captureWheelInput:true maps to capture mode", async () => {
+  const dom = installFakeDOM();
+  try {
+    const result = await wheelScenario({
+      captureWheelInput: true,
+      wheel: { clientX: 5, clientY: 5, deltaY: 20 },
+    });
+    expect(result.captured).toBe(true);
+    expect(result.wheelPrevented).toBe(true);
+  } finally {
+    dom.restore();
+  }
+});
+
 test("runtime preserves pointer movement within one cell", async () => {
   const dom = installFakeDOM();
   try {
@@ -1443,6 +1551,62 @@ async function flushPromises(): Promise<void> {
   await Promise.resolve();
 }
 
+// Drives a single wheel event over a 4x2 surface (cellWidth 10, cellHeight 27
+// under the fake DOM) with the given wheel mode and published scroll regions,
+// and reports whether the wheel was forwarded to the app and/or preventDefault'd.
+// Assumes a fake DOM is already installed by the caller.
+async function wheelScenario(options: {
+  wheelMode?: WheelMode;
+  captureWheelInput?: boolean;
+  scrollRegions?: Array<Record<string, unknown>>;
+  wheel: { clientX: number; clientY: number; deltaX?: number; deltaY?: number };
+}): Promise<{ captured: boolean; wheelPrevented: boolean }> {
+  const inputs: string[] = [];
+  const bridge = new BrowserWASIBridge({ sceneId: "main", columns: 4, rows: 2 });
+  const mount = new FakeElement("div");
+  const runtime = new WebHostSceneRuntime({
+    mount: mount as unknown as HTMLElement,
+    descriptor: { id: "main", title: "Main", isDefault: true },
+    style: { fontSize: 20 },
+    bridge,
+    onInput: (chunk) => {
+      inputs.push(decoder.decode(chunk));
+    },
+    synchronizeAccessibilityFocus: false,
+    wheelMode: options.wheelMode,
+    captureWheelInput: options.captureWheelInput,
+  });
+
+  await runtime.mount();
+  const frame: Record<string, unknown> = {
+    version: 2,
+    width: 4,
+    height: 2,
+    styles: [null],
+    rows: [[], []],
+  };
+  if (options.scrollRegions) {
+    frame.scrollRegions = options.scrollRegions;
+  }
+  bridge.stdout.write(encoder.encode(surfaceRecord(frame)));
+
+  let wheelPrevented = false;
+  runtime.terminalMount.dispatch("wheel", {
+    clientX: options.wheel.clientX,
+    clientY: options.wheel.clientY,
+    deltaX: options.wheel.deltaX ?? 0,
+    deltaY: options.wheel.deltaY ?? 0,
+    shiftKey: false,
+    altKey: false,
+    ctrlKey: false,
+    preventDefault() {
+      wheelPrevented = true;
+    },
+  });
+
+  return { captured: inputs.some((i) => i.includes("scrolled")), wheelPrevented };
+}
+
 function surfaceRecord(
   frame: Record<string, unknown>
 ): string {

package/src/WebHostSceneRuntime.ts

@@ -18,6 +18,7 @@ import {
   type WebHostOutputSink,
   type WebHostKeyInput,
   type WebHostRuntimeIssue,
+  type WebHostScrollRegion,
   type WebHostSurfaceDamage,
   type WebHostSurfaceFrame,
   type WebHostSurfaceImage,
@@ -42,9 +43,28 @@ export interface WebHostSceneRuntimeOptions {
   onInput(chunk: Uint8Array): void;
   onFrameDiagnostic?: (diagnostic: WebHostFrameDiagnosticRecord) => void;
   synchronizeAccessibilityFocus?: boolean;
+  /**
+   * How the embedded view treats mouse-wheel input.
+   * - `"capture"`: always forward the wheel to the app while the pointer is over
+   *   the surface (and `preventDefault` page scroll). Legacy default.
+   * - `"chain"`: forward the wheel only while a scrollable region under the
+   *   pointer can still scroll in that direction; otherwise let it fall through
+   *   so the page (or parent iframe) scrolls. Requires the app to publish
+   *   `scrollRegions` in its frames.
+   * - `"passive"`: never capture; the page always scrolls.
+   *
+   * Takes precedence over the legacy `captureWheelInput` flag.
+   */
+  wheelMode?: WheelMode;
+  /**
+   * Legacy boolean wheel gate. `true` → `"capture"`, `false` → `"passive"`.
+   * Prefer `wheelMode`. Ignored when `wheelMode` is set.
+   */
   captureWheelInput?: boolean;
 }
 
+export type WheelMode = "capture" | "chain" | "passive";
+
 interface CachedWebHostImage {
   image?: CanvasImageSource;
   promise?: Promise<CanvasImageSource>;
@@ -78,7 +98,7 @@ export class WebHostSceneRuntime {
   private readonly onInput: (chunk: Uint8Array) => void;
   private readonly onFrameDiagnostic?: (diagnostic: WebHostFrameDiagnosticRecord) => void;
   private readonly synchronizeAccessibilityFocus: boolean;
-  private readonly captureWheelInput: boolean;
+  private readonly wheelMode: WheelMode;
   private readonly imageCache = new Map<string, CachedWebHostImage>();
   private currentStyle: ResolvedWebHostTerminalStyle;
   private canvas?: HTMLCanvasElement;
@@ -108,7 +128,8 @@ export class WebHostSceneRuntime {
     this.onInput = options.onInput;
     this.onFrameDiagnostic = options.onFrameDiagnostic;
     this.synchronizeAccessibilityFocus = options.synchronizeAccessibilityFocus ?? true;
-    this.captureWheelInput = options.captureWheelInput ?? true;
+    this.wheelMode = options.wheelMode
+      ?? (options.captureWheelInput === false ? "passive" : "capture");
     this.element = document.createElement("section");
     this.element.className = "webhost-scene";
     this.element.dataset.sceneId = options.descriptor.id;
@@ -274,6 +295,9 @@ export class WebHostSceneRuntime {
 
     this.terminalMount.style.position = "relative";
     this.terminalMount.style.overflow = "hidden";
+    // Keep a captured wheel from rubber-banding/chaining the page; the wheel
+    // capture vs. fall-through decision lives in handleWheel.
+    this.terminalMount.style.overscrollBehavior = "contain";
     this.terminalMount.style.outline = "none";
     this.terminalMount.style.background = webTUITerminalBackgroundColor(this.currentStyle);
     this.terminalMount.style.minHeight = `${this.cellHeight * 8}px`;
@@ -390,12 +414,23 @@ export class WebHostSceneRuntime {
     };
 
     const handleWheel = (event: WheelEvent) => {
-      if (!this.captureWheelInput) {
+      if (this.wheelMode === "passive") {
         return;
       }
 
       const location = this.cellLocation(event);
       if (!location) {
+        // Pointer is outside the cell grid (sub-cell margin / gutter). Don't
+        // capture — let the wheel fall through to the page.
+        return;
+      }
+
+      // In "chain" mode, capture only while a scrollable region under the
+      // pointer can still move in this direction; otherwise let the wheel fall
+      // through so the page (or parent iframe) scrolls — iframe-like behavior.
+      // "capture" mode always forwards while over the surface (legacy).
+      if (this.wheelMode === "chain"
+        && !this.wheelTargetCanScroll(location, event.deltaX, event.deltaY)) {
         return;
       }
 
@@ -804,6 +839,41 @@ export class WebHostSceneRuntime {
     return `${italic}${weight}${this.currentStyle.fontSize}px ${this.currentStyle.fontFamily}`;
   }
 
+  /**
+   * Whether any scrollable region under `location` can still scroll in the
+   * wheel's direction. Mirrors the Swift host's scroll hit-test: a region
+   * qualifies when its viewport contains the cell AND it has remaining headroom
+   * in the delta's direction. Used by "chain" wheel mode to decide capture vs.
+   * fall-through. With no published `scrollRegions`, nothing can scroll, so the
+   * wheel chains to the page (a scene with no ScrollView stays fully passive).
+   */
+  private wheelTargetCanScroll(
+    location: { x: number; y: number },
+    deltaX: number,
+    deltaY: number
+  ): boolean {
+    const regions = this.currentFrame?.scrollRegions;
+    if (!regions || regions.length === 0) {
+      return false;
+    }
+
+    const cellX = Math.floor(location.x);
+    const cellY = Math.floor(location.y);
+    // Any region under the pointer that can move in this direction qualifies —
+    // this is what lets an outer ScrollView take over when an inner one is at
+    // its edge (nested scroll), and chains to the page only when none can.
+    for (const region of regions) {
+      const [rx, ry, rw, rh] = region.rect;
+      if (cellX < rx || cellY < ry || cellX >= rx + rw || cellY >= ry + rh) {
+        continue;
+      }
+      if (regionCanScrollInDirection(region, deltaX, deltaY)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
   private cellLocation(
     event: MouseEvent
   ): { x: number; y: number } | undefined {
@@ -959,6 +1029,42 @@ function normalizedWheelDelta(
   return 0;
 }
 
+/**
+ * Whether a published scroll region has remaining headroom in the wheel's
+ * direction, recomputing the per-direction extent from offset/content/viewport.
+ * Mirrors SwiftTUI's clamp (`min(max(0, offset), max(0, content - viewport))`)
+ * so the host and the app agree on "at edge". Wheel sign convention matches the
+ * app: `deltaY > 0` scrolls down (offset grows toward the content bottom).
+ * Diagonal wheels qualify if either axis has headroom.
+ */
+function regionCanScrollInDirection(
+  region: WebHostScrollRegion,
+  deltaX: number,
+  deltaY: number
+): boolean {
+  const [, , viewportWidth, viewportHeight] = region.rect;
+  const [offsetX, offsetY] = region.offset;
+  const [contentWidth, contentHeight] = region.content;
+  const maxX = Math.max(0, contentWidth - viewportWidth);
+  const maxY = Math.max(0, contentHeight - viewportHeight);
+  const clampedX = Math.min(Math.max(0, offsetX), maxX);
+  const clampedY = Math.min(Math.max(0, offsetY), maxY);
+
+  if (deltaY > 0 && clampedY < maxY) {
+    return true;
+  }
+  if (deltaY < 0 && clampedY > 0) {
+    return true;
+  }
+  if (deltaX > 0 && clampedX < maxX) {
+    return true;
+  }
+  if (deltaX < 0 && clampedX > 0) {
+    return true;
+  }
+  return false;
+}
+
 function normalizeCellRanges(
   ranges: DirtyCellRange[]
 ): DirtyCellRange[] {

package/src/WebHostSurfaceTransport.ts

@@ -88,6 +88,25 @@ export interface WebHostSurfaceDamage {
   requiresFullGraphicsReplay: boolean;
 }
 
+/**
+ * Per-region scroll extent published with each frame so the host can implement
+ * scroll-chaining: capture the wheel only while the region under the pointer can
+ * still scroll in the wheel's direction, otherwise let it fall through to the
+ * page. The host recomputes the per-direction headroom from `offset`/`content`/
+ * the viewport `rect`, mirroring SwiftTUI's
+ * `min(max(0, offset), max(0, content - viewport))` clamp.
+ */
+export interface WebHostScrollRegion {
+  /** identity path — same key space as accessibility node ids */
+  id: string;
+  /** viewport rect in cells: [x, y, width, height] */
+  rect: WebHostSurfaceRect;
+  /** current clamped scroll offset in cells: [x, y] */
+  offset: WebHostAccessibilityPoint;
+  /** total content size in cells: [width, height] */
+  content: WebHostSurfaceSize;
+}
+
 export interface WebHostSurfaceFrame {
   version: 1 | 2;
   sequence?: number;
@@ -99,6 +118,7 @@ export interface WebHostSurfaceFrame {
   damage?: WebHostSurfaceDamage;
   accessibilityTree?: WebHostAccessibilityNode[];
   accessibilityAnnouncements?: WebHostAccessibilityAnnouncement[];
+  scrollRegions?: WebHostScrollRegion[];
 }
 
 export type WebHostSurfaceDeltaRow = [
@@ -118,6 +138,7 @@ export interface WebHostSurfaceDeltaFrame {
   damage?: WebHostSurfaceDamage;
   accessibilityTree?: WebHostAccessibilityNode[];
   accessibilityAnnouncements?: WebHostAccessibilityAnnouncement[];
+  scrollRegions?: WebHostScrollRegion[];
 }
 
 export interface WebHostRuntimeIssue {
@@ -314,6 +335,7 @@ export class WebHostOutputDecoder {
       damage: frame.damage,
       accessibilityTree: frame.accessibilityTree,
       accessibilityAnnouncements: frame.accessibilityAnnouncements,
+      scrollRegions: frame.scrollRegions,
     };
   }
 }
@@ -444,7 +466,8 @@ function isWebHostSurfaceFrame(
     && (
       frame.accessibilityAnnouncements === undefined
         || isWebHostAccessibilityAnnouncements(frame.accessibilityAnnouncements)
-    );
+    )
+    && (frame.scrollRegions === undefined || isWebHostScrollRegions(frame.scrollRegions));
 }
 
 function isWebHostSurfaceDeltaFrame(
@@ -474,7 +497,8 @@ function isWebHostSurfaceDeltaFrame(
     && (
       frame.accessibilityAnnouncements === undefined
         || isWebHostAccessibilityAnnouncements(frame.accessibilityAnnouncements)
-    );
+    )
+    && (frame.scrollRegions === undefined || isWebHostScrollRegions(frame.scrollRegions));
 }
 
 function isWebHostSurfaceDeltaRow(
@@ -625,6 +649,25 @@ function isWebHostSurfaceImageFormat(
   return value === "png" || value === "jpeg" || value === "gif";
 }
 
+function isWebHostScrollRegions(
+  value: unknown
+): value is WebHostScrollRegion[] {
+  return Array.isArray(value) && value.every(isWebHostScrollRegion);
+}
+
+function isWebHostScrollRegion(
+  value: unknown
+): value is WebHostScrollRegion {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const region = value as Partial<WebHostScrollRegion>;
+  return typeof region.id === "string"
+    && isWebHostSurfaceRect(region.rect)
+    && isWebHostSurfaceSize(region.offset)
+    && isWebHostSurfaceSize(region.content);
+}
+
 function isWebHostSurfaceRect(
   value: unknown
 ): value is WebHostSurfaceRect {