@swifttui/web 0.0.9 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swifttui/web",
-  "version": "0.0.9",
+  "version": "0.0.12",
   "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();
@@ -216,6 +216,72 @@ test("runtime redraws only damaged cells when a compatible frame includes damage
   }
 });
 
+test("runtime redraws spanning cells that overlap a dirty range", async () => {
+  const dom = installFakeDOM();
+  try {
+    const bridge = new BrowserWASIBridge({
+      sceneId: "main",
+      columns: 6,
+      rows: 1,
+    });
+    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,
+        fontFamily: "Test Mono",
+      },
+      bridge,
+      onInput: () => {},
+    });
+
+    await runtime.mount();
+
+    const canvas = dom.canvases[0]!;
+    const context = canvas.context;
+    bridge.stdout.write(encoder.encode(surfaceRecord({
+      version: 1,
+      width: 6,
+      height: 1,
+      styles: [null],
+      rows: [
+        [[0, "Wide", 4, 0], [4, "Z", 1, 0]],
+      ],
+      images: [],
+    })));
+
+    context.operations = [];
+    bridge.stdout.write(encoder.encode(surfaceRecord({
+      version: 1,
+      width: 6,
+      height: 1,
+      styles: [null],
+      rows: [
+        [[0, "wide", 4, 0], [4, "Z", 1, 0]],
+      ],
+      images: [],
+      damage: {
+        textRows: [[0, [[2, 3]]]],
+        requiresFullTextRepaint: false,
+        requiresFullGraphicsReplay: false,
+      },
+    })));
+
+    expect(context.operations).toContainEqual({
+      type: "clearRect",
+      x: 20,
+      y: 0,
+      width: 10,
+      height: 27,
+    });
+    expect(fillTextOperations(context, "wide")).toHaveLength(1);
+    expect(fillTextOperations(context, "Z")).toEqual([]);
+  } finally {
+    dom.restore();
+  }
+});
+
 test("runtime clears stale overlay text when dirty rects remove an overlay", async () => {
   const dom = installFakeDOM();
   try {
@@ -1145,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 {
@@ -1377,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>;
@@ -57,6 +77,18 @@ interface DirtyRect {
   height: number;
 }
 
+interface DirtyCellRange {
+  start: number;
+  end: number;
+}
+
+type DirtyRowRanges = "full" | DirtyCellRange[];
+
+interface DirtyRegion {
+  rects: DirtyRect[];
+  rows: Map<number, DirtyRowRanges>;
+}
+
 export class WebHostSceneRuntime {
   readonly descriptor: WebHostSceneDescriptor;
   readonly element: HTMLElement;
@@ -66,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;
@@ -96,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;
@@ -262,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`;
@@ -378,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;
       }
 
@@ -500,8 +547,8 @@ export class WebHostSceneRuntime {
     }
 
     const frame = this.currentFrame;
-    const dirtyRects = frame ? this.dirtyRectsForDamage(damage, frame) : undefined;
-    if (dirtyRects?.length === 0) {
+    const dirtyRegion = frame ? this.dirtyRegionForDamage(damage, frame) : undefined;
+    if (dirtyRegion?.rects.length === 0) {
       return;
     }
 
@@ -510,8 +557,8 @@ export class WebHostSceneRuntime {
     context.textBaseline = "alphabetic";
 
     context.fillStyle = webTUITerminalBackgroundColor(this.currentStyle);
-    if (dirtyRects) {
-      for (const rect of dirtyRects) {
+    if (dirtyRegion) {
+      for (const rect of dirtyRegion.rects) {
         context.clearRect(rect.x, rect.y, rect.width, rect.height);
         context.fillRect(rect.x, rect.y, rect.width, rect.height);
       }
@@ -524,26 +571,43 @@ export class WebHostSceneRuntime {
       return;
     }
 
-    this.drawRows(context, frame, dirtyRects);
-    this.drawImages(context, frame.images ?? [], dirtyRects);
+    this.drawRows(context, frame, dirtyRegion);
+    this.drawImages(context, frame.images ?? [], dirtyRegion);
   }
 
   private drawRows(
     context: CanvasRenderingContext2D,
     frame: WebHostSurfaceFrame,
-    dirtyRects?: DirtyRect[]
+    dirtyRegion?: DirtyRegion
   ): void {
+    if (dirtyRegion) {
+      for (const [y, ranges] of dirtyRegion.rows) {
+        const row = frame.rows[y] ?? [];
+        this.drawRow(context, frame, row, y, ranges);
+      }
+      return;
+    }
+
     for (let y = 0; y < frame.rows.length; y += 1) {
       const row = frame.rows[y] ?? [];
-      for (const cell of row) {
-        const [x, text, span, styleIndex] = cell;
-        const cellRect = this.cellRect(x, y, span);
-        if (dirtyRects && !dirtyRects.some((rect) => rectsIntersect(rect, cellRect))) {
-          continue;
-        }
-        const style = frame.styles[styleIndex] ?? undefined;
-        this.drawCell(context, x, y, text, span, style);
+      this.drawRow(context, frame, row, y);
+    }
+  }
+
+  private drawRow(
+    context: CanvasRenderingContext2D,
+    frame: WebHostSurfaceFrame,
+    row: WebHostSurfaceFrame["rows"][number],
+    y: number,
+    ranges?: DirtyRowRanges
+  ): void {
+    for (const cell of row) {
+      const [x, text, span, styleIndex] = cell;
+      if (ranges !== undefined && !cellIntersectsRanges(x, span, ranges)) {
+        continue;
       }
+      const style = frame.styles[styleIndex] ?? undefined;
+      this.drawCell(context, x, y, text, span, style);
     }
   }
 
@@ -564,17 +628,17 @@ export class WebHostSceneRuntime {
   private drawImages(
     context: CanvasRenderingContext2D,
     images: WebHostSurfaceImage[],
-    dirtyRects?: DirtyRect[]
+    dirtyRegion?: DirtyRegion
   ): void {
     for (const image of images) {
-      this.drawImage(context, image, dirtyRects);
+      this.drawImage(context, image, dirtyRegion);
     }
   }
 
   private drawImage(
     context: CanvasRenderingContext2D,
     image: WebHostSurfaceImage,
-    dirtyRects?: DirtyRect[]
+    dirtyRegion?: DirtyRegion
   ): void {
     const decodedImage = this.cachedImage(image);
     if (!decodedImage) {
@@ -586,13 +650,10 @@ export class WebHostSceneRuntime {
     if (boundsWidth <= 0 || boundsHeight <= 0 || clipWidth <= 0 || clipHeight <= 0) {
       return;
     }
-    const imageRect = {
-      x: clipX * this.cellWidth,
-      y: clipY * this.cellHeight,
-      width: clipWidth * this.cellWidth,
-      height: clipHeight * this.cellHeight,
-    };
-    if (dirtyRects && !dirtyRects.some((rect) => rectsIntersect(rect, imageRect))) {
+    if (
+      dirtyRegion
+      && !dirtyRegionIntersectsCellRect(dirtyRegion, clipX, clipY, clipWidth, clipHeight)
+    ) {
       return;
     }
 
@@ -686,23 +747,28 @@ export class WebHostSceneRuntime {
     context.globalAlpha = 1;
   }
 
-  private dirtyRectsForDamage(
+  private dirtyRegionForDamage(
     damage: WebHostSurfaceDamage | undefined,
     frame: WebHostSurfaceFrame
-  ): DirtyRect[] | undefined {
+  ): DirtyRegion | undefined {
     if (!damage || damage.requiresFullTextRepaint || damage.requiresFullGraphicsReplay) {
       return undefined;
     }
 
     const rects: DirtyRect[] = [];
+    const rows = new Map<number, DirtyRowRanges>();
     for (const [row, ranges] of damage.textRows) {
       if (row < 0 || row >= frame.height) {
         continue;
       }
       if (ranges.length === 0) {
         rects.push(this.cellRect(0, row, frame.width));
+        rows.set(row, "full");
         continue;
       }
+      const rowRanges: DirtyCellRange[] = rows.get(row) === "full"
+        ? []
+        : [...(rows.get(row) as DirtyCellRange[] | undefined ?? [])];
       for (const [start, end] of ranges) {
         const lowerBound = Math.max(0, Math.min(frame.width, Math.floor(start)));
         const upperBound = Math.max(lowerBound, Math.min(frame.width, Math.ceil(end)));
@@ -710,9 +776,13 @@ export class WebHostSceneRuntime {
           continue;
         }
         rects.push(this.cellRect(lowerBound, row, upperBound - lowerBound));
+        rowRanges.push({ start: lowerBound, end: upperBound });
+      }
+      if (rows.get(row) !== "full" && rowRanges.length > 0) {
+        rows.set(row, normalizeCellRanges(rowRanges));
       }
     }
-    return rects;
+    return { rects, rows };
   }
 
   private cellRect(
@@ -769,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 {
@@ -924,14 +1029,96 @@ function normalizedWheelDelta(
   return 0;
 }
 
-function rectsIntersect(
-  lhs: DirtyRect,
-  rhs: DirtyRect
+/**
+ * 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[] {
+  const sorted = ranges
+    .filter((range) => range.end > range.start)
+    .sort((lhs, rhs) => lhs.start - rhs.start || lhs.end - rhs.end);
+  const normalized: DirtyCellRange[] = [];
+  for (const range of sorted) {
+    const previous = normalized[normalized.length - 1];
+    if (previous && range.start <= previous.end) {
+      previous.end = Math.max(previous.end, range.end);
+      continue;
+    }
+    normalized.push({ ...range });
+  }
+  return normalized;
+}
+
+function cellIntersectsRanges(
+  x: number,
+  span: number,
+  ranges: DirtyRowRanges
 ): boolean {
-  return lhs.x < rhs.x + rhs.width
-    && lhs.x + lhs.width > rhs.x
-    && lhs.y < rhs.y + rhs.height
-    && lhs.y + lhs.height > rhs.y;
+  if (ranges === "full") {
+    return true;
+  }
+  const start = Math.floor(x);
+  const end = start + Math.max(1, Math.ceil(span));
+  return ranges.some((range) => start < range.end && end > range.start);
+}
+
+function dirtyRegionIntersectsCellRect(
+  region: DirtyRegion,
+  x: number,
+  y: number,
+  width: number,
+  height: number
+): boolean {
+  const startRow = Math.max(0, Math.floor(y));
+  const endRow = Math.max(startRow, Math.ceil(y + height));
+  const rectRange = {
+    start: Math.floor(x),
+    end: Math.floor(x) + Math.max(1, Math.ceil(width)),
+  };
+  for (let row = startRow; row < endRow; row += 1) {
+    const ranges = region.rows.get(row);
+    if (!ranges) {
+      continue;
+    }
+    if (cellIntersectsRanges(rectRange.start, rectRange.end - rectRange.start, ranges)) {
+      return true;
+    }
+  }
+  return false;
 }
 
 function resolvedForeground(

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 {