@dxos/react-ui-canvas 0.8.4-main.84f28bd → 0.8.4-main.8baae0fced

package/src/components/CellGrid/CellGrid.tsx

@@ -0,0 +1,266 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { RegistryContext } from '@effect-atom/atom-react';
+import React, { useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useResizeDetector } from 'react-resize-detector';
+
+import type { ThemedClassName } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
+
+import { Ruler, TrackHeader } from './headers';
+import { attachPointerHandlers, attachWheelHandlers, type PointerHandlers } from './input';
+import { drawCells, drawOverlay, type OverlayStyle, type RenderCell, type StaticLayerStyle } from './render';
+import type { CellGridAtoms } from './state/atoms';
+import type { Cell, Headers, Row } from './state/types';
+
+export type CellGridProps<T = unknown> = ThemedClassName<
+  PointerHandlers & {
+    atoms: CellGridAtoms<T>;
+    rows: ReadonlyArray<Row>;
+    renderCell: RenderCell<T>;
+    headers?: Partial<Headers> | false;
+    staticStyle?: Partial<StaticLayerStyle>;
+    overlayStyle?: Partial<OverlayStyle>;
+  }
+>;
+
+const defaultHeaders: Headers = { left: 80, top: 24 };
+
+const defaultStaticStyle: StaticLayerStyle = {
+  gridLine: 'rgba(128,128,128,0.25)',
+  rowBand: 'rgba(128,128,128,0.06)',
+};
+
+const defaultOverlayStyle: OverlayStyle = {
+  playhead: 'rgb(220, 38, 38)',
+  selectionFill: 'rgba(59, 130, 246, 0.15)',
+  selectionStroke: 'rgb(59, 130, 246)',
+};
+
+const setupCanvas = (canvas: HTMLCanvasElement, width: number, height: number): CanvasRenderingContext2D | null => {
+  const dpr = window.devicePixelRatio || 1;
+  canvas.width = Math.max(1, Math.floor(width * dpr));
+  canvas.height = Math.max(1, Math.floor(height * dpr));
+  canvas.style.width = `${width}px`;
+  canvas.style.height = `${height}px`;
+  const ctx = canvas.getContext('2d');
+  if (!ctx) {
+    return null;
+  }
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  return ctx;
+};
+
+/**
+ * Canvas-based 2D grid where cells contain pluggable shapes. Suitable for music sequencers,
+ * time-series data viz, and similar workloads at ~1k visible cells per viewport.
+ */
+export const CellGrid = <T,>({
+  atoms,
+  rows,
+  renderCell,
+  headers: headersProp,
+  staticStyle: staticStyleProp,
+  overlayStyle: overlayStyleProp,
+  classNames,
+  onCellToggle,
+  onSelectionCommit,
+}: CellGridProps<T>) => {
+  const registry = useContext(RegistryContext);
+
+  const headers = useMemo<Headers>(() => {
+    if (headersProp === false) {
+      return { left: 0, top: 0 };
+    }
+    return { ...defaultHeaders, ...(headersProp ?? {}) };
+  }, [headersProp]);
+
+  const staticStyle = useMemo<StaticLayerStyle>(
+    () => ({ ...defaultStaticStyle, ...(staticStyleProp ?? {}) }),
+    [staticStyleProp],
+  );
+  const overlayStyle = useMemo<OverlayStyle>(
+    () => ({ ...defaultOverlayStyle, ...(overlayStyleProp ?? {}) }),
+    [overlayStyleProp],
+  );
+
+  const { ref: containerRef, width = 0, height = 0 } = useResizeDetector<HTMLDivElement>();
+  const staticCanvasRef = useRef<HTMLCanvasElement>(null);
+  const overlayCanvasRef = useRef<HTMLCanvasElement>(null);
+  const overlayInputRef = useRef<HTMLDivElement>(null);
+
+  const [staticCtx, setStaticCtx] = useState<CanvasRenderingContext2D | null>(null);
+  const [overlayCtx, setOverlayCtx] = useState<CanvasRenderingContext2D | null>(null);
+
+  // Track header rerenders for the React-side ruler/track-header.
+  const [viewportState, setViewportState] = useState(() => registry.get(atoms.viewport));
+
+  // Resize canvases on container resize.
+  useEffect(() => {
+    if (!width || !height) {
+      return;
+    }
+    if (staticCanvasRef.current) {
+      const ctx = setupCanvas(staticCanvasRef.current, width, height);
+      setStaticCtx(ctx);
+    }
+    if (overlayCanvasRef.current) {
+      const ctx = setupCanvas(overlayCanvasRef.current, width, height);
+      setOverlayCtx(ctx);
+    }
+  }, [width, height]);
+
+  // Mirror viewport into React state so headers re-render on scroll/zoom.
+  useEffect(() => registry.subscribe(atoms.viewport, (next) => setViewportState(next)), [registry, atoms.viewport]);
+
+  // Static-layer redraw on (cells, viewport, rows, headers, style, size) change.
+  useEffect(() => {
+    if (!staticCtx || !width || !height) {
+      return;
+    }
+    let raf: number | null = null;
+    const schedule = () => {
+      if (raf !== null) {
+        return;
+      }
+      raf = requestAnimationFrame(() => {
+        raf = null;
+        drawCells({
+          ctx: staticCtx,
+          size: { width, height },
+          viewport: registry.get(atoms.viewport),
+          headers,
+          rows,
+          cells: registry.get(atoms.cells),
+          renderCell,
+          style: staticStyle,
+        });
+      });
+    };
+    schedule();
+    const unsubCells = registry.subscribe(atoms.cells, schedule);
+    const unsubViewport = registry.subscribe(atoms.viewport, schedule);
+    return () => {
+      if (raf !== null) {
+        cancelAnimationFrame(raf);
+      }
+      unsubCells();
+      unsubViewport();
+    };
+  }, [staticCtx, width, height, registry, atoms.cells, atoms.viewport, headers, rows, renderCell, staticStyle]);
+
+  // Overlay rAF loop while playhead or active selection drag.
+  useEffect(() => {
+    if (!overlayCtx || !width || !height) {
+      return;
+    }
+    let raf: number | null = null;
+    let stopped = false;
+
+    const paint = () => {
+      drawOverlay({
+        ctx: overlayCtx,
+        size: { width, height },
+        viewport: registry.get(atoms.viewport),
+        headers,
+        selection: registry.get(atoms.selection),
+        playhead: registry.get(atoms.playhead),
+        style: overlayStyle,
+      });
+    };
+
+    const isAnimating = () => registry.get(atoms.playhead) !== null;
+
+    const loop = () => {
+      if (stopped) {
+        return;
+      }
+      paint();
+      if (isAnimating()) {
+        raf = requestAnimationFrame(loop);
+      } else {
+        raf = null;
+      }
+    };
+
+    const kick = () => {
+      paint();
+      if (raf === null && isAnimating()) {
+        raf = requestAnimationFrame(loop);
+      }
+    };
+
+    kick();
+    const unsubSelection = registry.subscribe(atoms.selection, () => paint());
+    const unsubPlayhead = registry.subscribe(atoms.playhead, kick);
+    const unsubViewport = registry.subscribe(atoms.viewport, () => paint());
+
+    return () => {
+      stopped = true;
+      if (raf !== null) {
+        cancelAnimationFrame(raf);
+      }
+      unsubSelection();
+      unsubPlayhead();
+      unsubViewport();
+    };
+  }, [overlayCtx, width, height, registry, atoms.selection, atoms.playhead, atoms.viewport, headers, overlayStyle]);
+
+  // Input wiring. Keep the callbacks in a ref so the listener attachment is stable
+  // across consumer re-renders — otherwise an in-progress drag is torn down when
+  // the parent's onCellToggle identity changes (e.g. after the very mutation we
+  // just triggered), and subsequent pointermove events see drag === null.
+  const callbacksRef = useRef<PointerHandlers>({ onCellToggle, onSelectionCommit });
+  callbacksRef.current = { onCellToggle, onSelectionCommit };
+  useEffect(() => {
+    const element = overlayInputRef.current;
+    if (!element) {
+      return;
+    }
+    const detachPointer = attachPointerHandlers(element, {
+      registry,
+      atoms,
+      headers,
+      handlers: {
+        onCellToggle: (coord, mode) => callbacksRef.current.onCellToggle?.(coord, mode),
+        onSelectionCommit: (range) => callbacksRef.current.onSelectionCommit?.(range),
+      },
+    });
+    const detachWheel = attachWheelHandlers(element, { registry, atoms, headers });
+    return () => {
+      detachPointer();
+      detachWheel();
+    };
+  }, [registry, atoms, headers]);
+
+  return (
+    <div ref={containerRef} className={mx('relative w-full h-full overflow-hidden bg-baseSurface', classNames)}>
+      {/*
+        Canvases are nudged up + left 1 CSS pixel so the gridlines (drawn at the TOP
+        and LEFT edges of each cell) sit on top of the frozen header dividers — the
+        TrackHeader's right border and bottom-row box-shadow, which both render 1px
+        inside the box. Without this offset the canvas gridlines land 1px down/right
+        of the header dividers and the columns read as misaligned.
+      */}
+      <canvas ref={staticCanvasRef} className='absolute inset-0 pointer-events-none' style={{ top: -1, left: -1 }} />
+      <canvas ref={overlayCanvasRef} className='absolute inset-0 pointer-events-none' style={{ top: -1, left: -1 }} />
+      <div
+        ref={overlayInputRef}
+        className='absolute inset-0 touch-none'
+        style={{ paddingLeft: headers.left, paddingTop: headers.top }}
+      />
+      {headers.top > 0 && <Ruler viewport={viewportState} headers={headers} width={width} />}
+      {headers.left > 0 && <TrackHeader viewport={viewportState} headers={headers} rows={rows} height={height} />}
+      {headers.top > 0 && headers.left > 0 && (
+        <div
+          className='absolute top-0 left-0 border-b border-r border-neutral-200 dark:border-neutral-700 bg-baseSurface'
+          style={{ width: headers.left, height: headers.top }}
+        />
+      )}
+    </div>
+  );
+};
+
+export type { Cell };

package/src/components/CellGrid/headers/Ruler.tsx

@@ -0,0 +1,71 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React, { useMemo } from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+import type { Headers, Viewport } from '../state/types';
+import { cellWidth } from '../state/viewport';
+
+export type RulerProps = {
+  viewport: Viewport;
+  headers: Headers;
+  width: number;
+  /** Number of columns to label between major ticks. */
+  majorEvery?: number;
+  classNames?: string;
+};
+
+/**
+ * Frozen top ruler. Ticks reflect the current viewport scroll and zoom.
+ */
+export const Ruler = ({ viewport, headers, width, majorEvery = 4, classNames }: RulerProps) => {
+  // Clamp to >= 1 — a zero or negative `majorEvery` makes `col % majorEvery`
+  // NaN / always-zero and breaks major-tick detection.
+  const safeMajorEvery = Math.max(1, Math.floor(majorEvery));
+  const ticks = useMemo(() => {
+    const w = cellWidth(viewport);
+    if (w < 1 || width <= headers.left) {
+      return [];
+    }
+    const innerWidth = width - headers.left;
+    const startCol = Math.floor(viewport.scrollX / w);
+    const endCol = Math.ceil((viewport.scrollX + innerWidth) / w);
+    const result: Array<{ col: number; x: number; major: boolean }> = [];
+    for (let col = startCol; col <= endCol; col++) {
+      result.push({
+        col,
+        x: headers.left + col * w - viewport.scrollX,
+        major: col % safeMajorEvery === 0,
+      });
+    }
+    return result;
+  }, [viewport, headers.left, width, safeMajorEvery]);
+
+  return (
+    <div
+      className={mx(
+        'absolute top-0 left-0 right-0 border-b border-neutral-200 dark:border-neutral-700 bg-baseSurface select-none overflow-hidden',
+        classNames,
+      )}
+      style={{ height: headers.top }}
+    >
+      {ticks.map(({ col, x, major }) => (
+        <div
+          key={col}
+          className={mx(
+            'absolute top-0 bottom-0 text-[10px] text-neutral-500 dark:text-neutral-400',
+            major
+              ? 'border-l border-neutral-400 dark:border-neutral-500'
+              : 'border-l border-neutral-200 dark:border-neutral-700',
+          )}
+          style={{ transform: `translateX(${x}px)` }}
+        >
+          {major ? <span className='absolute left-1 top-0'>{col}</span> : null}
+        </div>
+      ))}
+    </div>
+  );
+};

package/src/components/CellGrid/headers/TrackHeader.tsx

@@ -0,0 +1,58 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import React from 'react';
+
+import { mx } from '@dxos/ui-theme';
+
+import type { Headers, Row, Viewport } from '../state/types';
+
+export type TrackHeaderProps = {
+  viewport: Viewport;
+  headers: Headers;
+  rows: ReadonlyArray<Row>;
+  height: number;
+  classNames?: string;
+};
+
+/**
+ * Frozen left column listing row labels. Translates vertically in sync with viewport scroll.
+ *
+ * Row dividers and alternating shading intentionally MATCH the canvas — opaque borders
+ * and opaque alternating fills make the labels look out of phase with the cell area
+ * even when the y-positions align. We mirror the canvas's transparent-overlay model
+ * here so the frozen column reads as a direct continuation of the grid.
+ */
+export const TrackHeader = ({ viewport, headers, rows, height, classNames }: TrackHeaderProps) => {
+  return (
+    <div
+      className={mx(
+        'absolute left-0 border-r border-neutral-200 dark:border-neutral-700 select-none overflow-hidden',
+        classNames,
+      )}
+      style={{ top: headers.top, width: headers.left, height: Math.max(0, height - headers.top) }}
+    >
+      <div style={{ transform: `translateY(${-viewport.scrollY}px)` }}>
+        {rows.map((row, index) => (
+          <div
+            key={row.id}
+            className='flex items-center px-2 text-xs text-neutral-700 dark:text-neutral-300'
+            style={{
+              height: viewport.cellHeight,
+              // Match the canvas's row-band: a translucent gray overlay on odd rows,
+              // transparent on even rows. The container's overall background bleeds
+              // through, so the labels stay legible in both themes.
+              backgroundColor: index % 2 === 0 ? 'transparent' : 'rgba(128, 128, 128, 0.08)',
+              // Match the canvas gridline color (rgba(128, 128, 128, 0.25)). Use a
+              // half-pixel inset to keep crisp single-pixel rendering on retina.
+              boxShadow: 'inset 0 -1px 0 rgba(128, 128, 128, 0.25)',
+            }}
+          >
+            {row.label ?? row.id}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+};

package/src/components/CellGrid/headers/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './Ruler';
+export * from './TrackHeader';

package/src/components/CellGrid/index.ts

@@ -0,0 +1,9 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './CellGrid';
+export * from './headers';
+export * from './input';
+export * from './render';
+export * from './state';

package/src/components/CellGrid/input/index.ts

@@ -0,0 +1,6 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+export * from './pointer';
+export * from './wheel';

package/src/components/CellGrid/input/pointer.ts

@@ -0,0 +1,208 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { Registry } from '@effect-atom/atom-react';
+
+import type { CellGridAtoms } from '../state/atoms';
+import type { Cell, CellCoord, Headers, SelectionRange, Tool } from '../state/types';
+import { cellKey, hitTestCell } from '../state/viewport';
+
+/**
+ * 'set' / 'unset' are idempotent — the receiver must add or remove the cell
+ * regardless of current state. 'toggle' flips it. Drag operations always pick
+ * a fixed mode (set or unset) based on the cell under the initial pointerdown
+ * so the user paints a uniform stroke instead of flipping each cell.
+ */
+export type ToggleMode = 'set' | 'unset' | 'toggle';
+
+export type PointerHandlers = {
+  onCellToggle?: (coord: CellCoord, mode: ToggleMode) => void;
+  onSelectionCommit?: (range: SelectionRange) => void;
+};
+
+type DragState =
+  | { kind: 'toggle'; mode: 'set' | 'unset'; touched: Set<string> }
+  | { kind: 'select'; origin: CellCoord }
+  | { kind: 'pan'; lastX: number; lastY: number };
+
+export type PointerControllerOptions<T> = {
+  registry: Registry.Registry;
+  atoms: CellGridAtoms<T>;
+  headers: Headers;
+  handlers: PointerHandlers;
+};
+
+/**
+ * Attach pointer handlers to an element. Returns an unsubscribe.
+ */
+export const attachPointerHandlers = <T>(
+  element: HTMLElement,
+  { registry, atoms, headers, handlers }: PointerControllerOptions<T>,
+): (() => void) => {
+  let drag: DragState | null = null;
+
+  const local = (event: PointerEvent) => {
+    const rect = element.getBoundingClientRect();
+    return { x: event.clientX - rect.left, y: event.clientY - rect.top };
+  };
+
+  // setPointerCapture throws for synthetic / untrusted PointerEvents (e.g. those
+  // dispatched by tests). Capture is a best-effort UX nicety — never let it abort
+  // the click path.
+  const tryCapture = (pointerId: number) => {
+    try {
+      element.setPointerCapture(pointerId);
+    } catch {
+      // Ignore — drag tracking still works without capture.
+    }
+  };
+
+  const onPointerDown = (event: PointerEvent) => {
+    // Middle-mouse or space-held pan: pan tool regardless of `tool` atom.
+    if (event.button === 1 || (event.button === 0 && event.altKey)) {
+      drag = { kind: 'pan', lastX: event.clientX, lastY: event.clientY };
+      tryCapture(event.pointerId);
+      event.preventDefault();
+      return;
+    }
+
+    if (event.button !== 0) {
+      return;
+    }
+
+    const viewport = registry.get(atoms.viewport);
+    const point = local(event);
+    const coord = hitTestCell(viewport, headers, point);
+    if (!coord) {
+      return;
+    }
+
+    const tool = registry.get(atoms.tool) as Tool;
+    tryCapture(event.pointerId);
+
+    switch (tool) {
+      case 'toggle':
+      case 'resize': {
+        // Inspect the cells atom under the pointer to decide whether the gesture
+        // is a paint (set) or an erase (unset). Subsequent drag movements apply the
+        // same operation idempotently to every cell the cursor crosses.
+        const cells = registry.get(atoms.cells) as ReadonlyMap<string, unknown>;
+        const key = cellKey(coord.col, coord.row);
+        const mode: 'set' | 'unset' = cells.has(key) ? 'unset' : 'set';
+        handlers.onCellToggle?.(coord, mode);
+        drag = { kind: 'toggle', mode, touched: new Set([key]) };
+        break;
+      }
+      case 'select': {
+        drag = { kind: 'select', origin: coord };
+        registry.set(atoms.selection, {
+          range: { col0: coord.col, row0: coord.row, col1: coord.col, row1: coord.row },
+        });
+        break;
+      }
+    }
+  };
+
+  const onPointerMove = (event: PointerEvent) => {
+    if (!drag) {
+      return;
+    }
+    if (drag.kind === 'pan') {
+      const dx = event.clientX - drag.lastX;
+      const dy = event.clientY - drag.lastY;
+      drag.lastX = event.clientX;
+      drag.lastY = event.clientY;
+      registry.update(atoms.viewport, (current) => ({
+        ...current,
+        scrollX: Math.max(0, current.scrollX - dx),
+        scrollY: Math.max(0, current.scrollY - dy),
+      }));
+      return;
+    }
+
+    const viewport = registry.get(atoms.viewport);
+    const coord = hitTestCell(viewport, headers, local(event));
+    if (!coord) {
+      return;
+    }
+
+    if (drag.kind === 'toggle') {
+      // Apply the drag's chosen mode to every cell the cursor enters, across rows,
+      // de-duplicating per cell so we don't fire the same coord twice.
+      const key = cellKey(coord.col, coord.row);
+      if (!drag.touched.has(key)) {
+        drag.touched.add(key);
+        handlers.onCellToggle?.(coord, drag.mode);
+      }
+    } else if (drag.kind === 'select') {
+      registry.set(atoms.selection, {
+        range: { col0: drag.origin.col, row0: drag.origin.row, col1: coord.col, row1: coord.row },
+      });
+    }
+  };
+
+  const releaseCapture = (event: PointerEvent) => {
+    if (element.hasPointerCapture(event.pointerId)) {
+      element.releasePointerCapture(event.pointerId);
+    }
+  };
+
+  const onPointerUp = (event: PointerEvent) => {
+    if (!drag) {
+      return;
+    }
+    if (drag.kind === 'select') {
+      const range = registry.get(atoms.selection).range;
+      if (range) {
+        handlers.onSelectionCommit?.(range);
+      }
+    }
+    drag = null;
+    releaseCapture(event);
+  };
+
+  // pointercancel signals an interrupted gesture (system gesture, palm rejection,
+  // capture lost). Per the Pointer Events spec this should clean up local state
+  // ONLY and not be treated as a successful completion — so we never commit a
+  // selection from cancel.
+  const onPointerCancel = (event: PointerEvent) => {
+    drag = null;
+    releaseCapture(event);
+  };
+
+  element.addEventListener('pointerdown', onPointerDown);
+  element.addEventListener('pointermove', onPointerMove);
+  element.addEventListener('pointerup', onPointerUp);
+  element.addEventListener('pointercancel', onPointerCancel);
+
+  return () => {
+    element.removeEventListener('pointerdown', onPointerDown);
+    element.removeEventListener('pointermove', onPointerMove);
+    element.removeEventListener('pointerup', onPointerUp);
+    element.removeEventListener('pointercancel', onPointerCancel);
+  };
+};
+
+/**
+ * Utility for consumers: toggle, set, or unset membership of a cell in the cells atom.
+ */
+export const toggleCell = <T>(
+  registry: Registry.Registry,
+  atoms: CellGridAtoms<T>,
+  coord: CellCoord,
+  factory: (coord: CellCoord) => Cell<T>,
+  mode: ToggleMode = 'toggle',
+): void => {
+  registry.update(atoms.cells, (current) => {
+    const next = new Map(current);
+    const key = cellKey(coord.col, coord.row);
+    const exists = next.has(key);
+    if (mode === 'set' || (mode === 'toggle' && !exists)) {
+      next.set(key, factory(coord));
+    } else if (mode === 'unset' || (mode === 'toggle' && exists)) {
+      next.delete(key);
+    }
+    return next;
+  });
+};

package/src/components/CellGrid/input/wheel.ts

@@ -0,0 +1,68 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import type { Registry } from '@effect-atom/atom-react';
+
+import type { CellGridAtoms } from '../state/atoms';
+import type { Headers } from '../state/types';
+import { cellWidth } from '../state/viewport';
+
+const MIN_ZOOM = 0.25;
+const MAX_ZOOM = 8;
+
+export type WheelControllerOptions<T> = {
+  registry: Registry.Registry;
+  atoms: CellGridAtoms<T>;
+  headers: Headers;
+};
+
+/**
+ * Attach wheel handlers. Vertical wheel scrolls y; shift+wheel scrolls x;
+ * cmd/ctrl+wheel zooms x around the cursor.
+ */
+export const attachWheelHandlers = <T>(
+  element: HTMLElement,
+  { registry, atoms, headers }: WheelControllerOptions<T>,
+): (() => void) => {
+  const onWheel = (event: WheelEvent) => {
+    if (event.ctrlKey || event.metaKey) {
+      event.preventDefault();
+      // Zoom around cursor x.
+      const rect = element.getBoundingClientRect();
+      const x = event.clientX - rect.left;
+      const factor = Math.exp(-event.deltaY / 200);
+      registry.update(atoms.viewport, (current) => {
+        const nextZoom = Math.max(MIN_ZOOM, Math.min(MAX_ZOOM, current.zoomX * factor));
+        if (nextZoom === current.zoomX) {
+          return current;
+        }
+        const w = cellWidth(current);
+        const worldX = (x - headers.left + current.scrollX) / w;
+        const nextW = current.baseCellWidth * nextZoom;
+        const nextScrollX = Math.max(0, worldX * nextW - (x - headers.left));
+        return { ...current, zoomX: nextZoom, scrollX: nextScrollX };
+      });
+      return;
+    }
+
+    const dx = event.shiftKey ? event.deltaY : event.deltaX;
+    const dy = event.shiftKey ? 0 : event.deltaY;
+    const current = registry.get(atoms.viewport);
+    const nextScrollX = Math.max(0, current.scrollX + dx);
+    const nextScrollY = Math.max(0, current.scrollY + dy);
+
+    // Only consume the wheel event if we're actually scrolling within the grid.
+    // When the user wheels up at the top (scrollY === 0 && dy < 0) or wheels left
+    // at the left edge, let the event bubble to the parent so the page or
+    // enclosing container can scroll instead of swallowing the gesture.
+    if (nextScrollX === current.scrollX && nextScrollY === current.scrollY) {
+      return;
+    }
+    event.preventDefault();
+    registry.set(atoms.viewport, { ...current, scrollX: nextScrollX, scrollY: nextScrollY });
+  };
+
+  element.addEventListener('wheel', onWheel, { passive: false });
+  return () => element.removeEventListener('wheel', onWheel);
+};