@downdraft/engine 0.0.0 → 0.1.1

package/libraries/recast/src/library.ts

@@ -0,0 +1,91 @@
+// ============================================================================
+// RecastLib — declarative engine library descriptor for @downdraft/engine/libraries/recast
+//
+// Games declare `libraries: [RecastLib]` (or with config override) in their
+// GameModule. The host creates the RecastBackend + RecastCrowdSystem
+// (sim-side only — recast has no renderer component) and exposes them via
+// typed tokens.
+//
+// Games that need full control can still import RecastBackend,
+// RecastCrowdSystem, and RecastAgent directly (escape hatch).
+// ============================================================================
+
+import { resourceToken, type EngineLibrary } from "@downdraft/engine";
+import { RecastBackend } from "./backend";
+import { RecastCrowdSystem } from "./crowd-system";
+
+// ── Config ──
+
+export interface RecastLibConfig {
+  /** Default agent radius. Default: 0.5. */
+  agentRadius?: number;
+  /** Default agent height. Default: 1.8. */
+  agentHeight?: number;
+  /** Max crowd agents. Default: 512. */
+  maxAgents?: number;
+  /** Max agent radius for the recast Crowd ctor. Default: 0.6. */
+  maxAgentRadius?: number;
+  /** Seconds without progress before an agent flips to `stuck`. `0` disables. Default: 2. */
+  stuckTimeout?: number;
+  /** Min per-tick displacement (m) counting as progress for stuck detection. Default: 0.05. */
+  stuckMoveEpsilon?: number;
+  /** Horizontal distance (m) from the snapped target counted as arrived. Default: 0.5. */
+  arrivalDistance?: number;
+  /** Max distance (m) from path endpoint to target for it to count as reachable. `0` disables the reachability check. Default: 1.5. */
+  reachabilityTolerance?: number;
+}
+
+// ── Typed tokens (DI) ──
+
+/** Token for the sim-side recast backend (navmesh + query). Inject in sim systems that need pathfinding. */
+export const RecastNavMeshTok = resourceToken<RecastBackend>("recast:navmesh");
+/** Token for the sim-side recast crowd system. Inject in sim systems that drive agents. */
+export const RecastCrowdTok = resourceToken<RecastCrowdSystem>("recast:crowd");
+
+// ── Descriptor ──
+
+export const RecastLib: EngineLibrary<RecastLibConfig> = {
+  name: "recast",
+  version: "1.0.0",
+
+  // No SAB channels — recast is sim-only, results synced via main SimBuffer.
+  sabChannels: [],
+
+  provides: [RecastNavMeshTok, RecastCrowdTok],
+
+  sim: {
+    async create(config, ctx) {
+      const backend = new RecastBackend();
+      await backend.init();
+      const crowd = new RecastCrowdSystem(backend, {
+        maxAgents: config.maxAgents ?? 512,
+        maxAgentRadius: config.maxAgentRadius ?? 0.6,
+        stuckTimeout: config.stuckTimeout,
+        stuckMoveEpsilon: config.stuckMoveEpsilon,
+        arrivalDistance: config.arrivalDistance,
+        reachabilityTolerance: config.reachabilityTolerance,
+      });
+      ctx.provide(RecastNavMeshTok, backend);
+      ctx.provide(RecastCrowdTok, crowd);
+      return { backend, crowd };
+    },
+    dispose(system) {
+      const { backend, crowd } = system as { backend: RecastBackend; crowd: RecastCrowdSystem };
+      crowd.destroy();
+      backend.destroy();
+    },
+    // tick is game-specific (calls crowd.update via the registered ECS system,
+    // setTarget per agent, repathing, etc.) — games wire this via onReady.
+  },
+
+  tickPhase: "post-physics",
+
+  // No renderer setup — recast is entirely sim-side.
+
+  defaultConfig: {
+    agentRadius: 0.5,
+    agentHeight: 1.8,
+    maxAgents: 512,
+    maxAgentRadius: 0.6,
+  },
+};

package/libraries/recast/src/types.ts

@@ -0,0 +1,86 @@
+// ============================================================================
+// Shared types for @downdraft/engine/libraries/recast
+// ============================================================================
+
+export type Vec3 = [number, number, number];
+
+/**
+ * Configuration passed to {@link RecastBackend.buildNavMesh} (forwarded to
+ * recast-navigation's `generateSoloNavMesh` as `SoloNavMeshGeneratorConfig`).
+ * All fields optional — recast supplies sensible defaults.
+ */
+export interface RecastNavMeshConfig {
+  /** Voxel cell size (cs). Default from recast: 0.2. */
+  cs?: number;
+  /** Voxel cell height (ch). Default from recast: 0.2. */
+  ch?: number;
+  /** Maximum slope angle considered walkable, in degrees. Default: 45. */
+  walkableSlopeAngle?: number;
+  /** Minimum ceiling height (agent height) in world units. Default: 2. */
+  walkableHeight?: number;
+  /** Maximum ledge height considered climbable. Default: 0.4. */
+  walkableClimb?: number;
+  /** Agent radius (walkable radius). Default: 0.6. */
+  walkableRadius?: number;
+  /** Maximum edge length. Default: 12. */
+  maxEdgeLen?: number;
+  /** Maximum simplification error. Default: 1.3. */
+  maxSimplificationError?: number;
+  /** Minimum region area. Default: 8. */
+  minRegionArea?: number;
+  /** Region merge area. Default: 20. */
+  mergeRegionArea?: number;
+  /** Max vertices per polygon. Default: 6. */
+  maxVertsPerPoly?: number;
+  /** Detail sample distance. Default: 6. */
+  detailSampleDist?: number;
+  /** Detail sample max error. Default: 1. */
+  detailSampleMaxError?: number;
+  /** Build BV tree. Default: true. */
+  buildBvTree?: boolean;
+}
+
+/**
+ * Per-agent parameters. Mirrors recast-navigation's `CrowdAgentParams` but
+ * uses the engine's `Vec3`-free scalar form (agents are positioned via the
+ * ECS, not via a recast Vector3).
+ */
+export interface RecastAgentParams {
+  radius?: number;
+  height?: number;
+  maxAcceleration?: number;
+  maxSpeed?: number;
+  collisionQueryRange?: number;
+  pathOptimizationRange?: number;
+  separationWeight?: number;
+  updateFlags?: number;
+  obstacleAvoidanceType?: number;
+  queryFilterType?: number;
+}
+
+/**
+ * ECS component data for a recast crowd agent. Stored on the entity alongside
+ * `PhysicsTransform`; the crowd system reads/writes both each tick.
+ */
+export interface RecastAgentData {
+  [key: string]: unknown;
+  /** recast crowd agent index (returned by `Crowd.addAgent`). -1 = not added. */
+  agentId: number;
+  radius: number;
+  height: number;
+  maxSpeed: number;
+  maxAcceleration: number;
+  target: Vec3 | null;
+  /**
+   * Lifecycle state of the agent's current move goal:
+   * - `idle`     — no move target.
+   * - `seeking`  — has a reachable target, crowd is steering toward it.
+   * - `arrived`  — within `arrivalDistance` of the (snapped) target.
+   * - `stuck`    — has a target but has made no appreciable progress for
+   *                `stuckTimeout` seconds (e.g. target snapped to an
+   *                unreachable navmesh island, or the agent is wedged against
+   *                geometry). Games should react by clearing / reassigning.
+   */
+  state: "idle" | "seeking" | "arrived" | "stuck";
+  velocity: Vec3;
+}

package/libraries/sand/README.md

@@ -0,0 +1,25 @@
+# `@downdraft/engine/libraries/sand`
+
+Falling-sand simulation — cellular automata world, material palette, rule engine, and parallel step pools (SandLib descriptor).
+
+## Install
+
+```sh
+bun add @downdraft/engine/libraries/sand
+```
+
+## Key exports
+
+- `DEFAULT_GRAVITY`
+- `DEFAULT_TEMP`
+- `FIELD`
+- `FLAG_ANCHORED`
+- `FLAG_POPPED`
+- `FLAG_SPARK`
+- `FLAG_UPDATED`
+- `FLAG_UPDATED_BIT`
+- `FluidGrid`
+- `GRAVEL_DISTURB_SETTLE_TICKS`
+- …and 42 more
+
+See the [Downdraft engine repository](https://github.com/knackstedt/downdraft) for architecture docs and examples.

package/libraries/sand/src/cell.ts

@@ -0,0 +1,43 @@
+// ============================================================================
+// Cell packing helpers — shared between the sand simulation and consumers.
+//
+// A cell is packed into a single uint32:
+//   bits  0-7  : material id (0..255)
+//   bits  8-15 : lifetime (0..255)
+//   bits 16-23 : flags (shade bits 0-1, FLAG_UPDATED bit 2, FLAG_SPARK bit 3,
+//                        FLAG_POPPED bit 5)
+//   bits 24-31 : unused (reserved)
+// ============================================================================
+
+export interface Cell {
+  mat: number;
+  lifetime: number;
+  flags: number;
+}
+
+export const FLAG_UPDATED = 0x04; // bit 2 — cell was updated this frame
+export const FLAG_SPARK = 0x08; // bit 3 — this fire is a spark (expires to empty, not smoke)
+export const FLAG_ANCHORED = 0x10; // bit 4 — fire stays put (wax flame, doesn't rise/drift)
+export const FLAG_POPPED = 0x20; // bit 5 — popcorn that has already popped (won't re-pop)
+export const SHADE_MASK = 0x03; // bits 0-1 — shade index (0-3)
+
+// Precomputed bit position of FLAG_UPDATED within the packed uint32 flags field.
+// OR-ing this into a packed cell value sets FLAG_UPDATED without re-packing.
+export const FLAG_UPDATED_BIT = FLAG_UPDATED << 16;
+
+export function pack(cell: Cell): number {
+  return (cell.mat & 0xff) | ((cell.lifetime & 0xff) << 8) | ((cell.flags & 0xff) << 16);
+}
+
+export function unpack(v: number): Cell {
+  return {
+    mat: v & 0xff,
+    lifetime: (v >> 8) & 0xff,
+    flags: (v >> 16) & 0xff,
+  };
+}
+
+/** Pack a cell value from raw components without allocating a Cell object. */
+export function packCell(mat: number, lifetime: number, flags: number): number {
+  return (mat & 0xff) | ((lifetime & 0xff) << 8) | ((flags & 0xff) << 16);
+}

package/libraries/sand/src/fields.ts

@@ -0,0 +1,29 @@
+// ============================================================================
+// Shared per-cell physics field layout.
+//
+// Each cell carries 4 field bytes alongside its packed material cell:
+//   [gravity:u8, temp:u8, reserved:u8, reserved:u8]
+//
+// Wind/velocity is no longer stored per-cell. It's handled by the coarse-grid
+// FluidGrid (fluid-grid.ts) at 1/4 resolution, which provides proper pressure
+// relaxation and sustained airflow. The reserved bytes are kept for SAB layout
+// compatibility (avoiding save migration) but are unused.
+//
+// These constants are shared between the sand simulation (sand-world.ts) and
+// any game-specific SharedArrayBuffer bridge (e.g. a game's sim-buffer.ts
+// or a game's chunk SAB). Games keep their own SAB layout but reference
+// these field offsets so the indexing stays consistent.
+// ============================================================================
+
+export const FIELD = {
+  GRAVITY: 0,
+  TEMP: 1,
+  // Bytes 2-3 are reserved (formerly WIND_X/WIND_Y, now handled by FluidGrid).
+  // Kept for SAB layout compatibility — do not repurpose without updating
+  // grid-sim-buffer.ts fieldCellBytes and all save files.
+  RESERVED_2: 2,
+  RESERVED_3: 3,
+} as const;
+
+export const DEFAULT_GRAVITY = 128; // u8, 128 = 1.0x
+export const DEFAULT_TEMP = 128; // u8, 128 = 1.0

package/libraries/sand/src/fluid-grid.ts

@@ -0,0 +1,261 @@
+// ============================================================================
+// FluidGrid — coarse-grid pressure/velocity fluid simulation.
+//
+// Replaces the per-cell wind field system with a proper fluid dynamics
+// simulation at 1/4 resolution. Each coarse cell covers 4×4 fine cells.
+//
+// The simulation runs a simplified Navier-Stokes step each frame:
+//   1. Pressure relaxation — pressure diffuses to neighbors
+//   2. Velocity from pressure gradient — velX/velY derived from pressure diffs
+//   3. Velocity damping — velocities decay slightly each frame
+//
+// This enables sustained airflow (fans), pressure equalization (gas flows
+// from high to low pressure), and realistic explosion shockwaves.
+//
+// Per-cell wind is sampled from the coarse grid via bilinear interpolation
+// in tryMove(), replacing the old per-cell WIND_X/WIND_Y fields.
+//
+// Inspired by the Dan-Ball dust2.js fluid simulation, which uses a similar
+// coarse-grid pressure/velocity approach at 1/4 particle resolution.
+// ============================================================================
+
+const COARSE_SCALE = 4; // each coarse cell = 4×4 fine cells
+
+export class FluidGrid {
+  // Coarse grid dimensions
+  readonly cw: number;
+  readonly ch: number;
+
+  // Pressure + velocity fields (Float32Array for performance)
+  pressure: Float32Array;
+  velX: Float32Array;
+  velY: Float32Array;
+
+  // Double-buffered temp arrays for relaxation steps
+  private pressureNext: Float32Array;
+  private velXNext: Float32Array;
+  private velYNext: Float32Array;
+
+  // Solid mask — coarse cells blocked by walls/stone don't participate.
+  // 1 = solid (blocked), 0 = fluid (participates).
+  private solid: Uint8Array;
+
+  // Dirty flag — skip the step() entirely when no impulses or pressure exists.
+  private dirty = false;
+
+  constructor(fineW: number, fineH: number) {
+    this.cw = Math.ceil(fineW / COARSE_SCALE);
+    this.ch = Math.ceil(fineH / COARSE_SCALE);
+    const n = this.cw * this.ch;
+    this.pressure = new Float32Array(n);
+    this.velX = new Float32Array(n);
+    this.velY = new Float32Array(n);
+    this.pressureNext = new Float32Array(n);
+    this.velXNext = new Float32Array(n);
+    this.velYNext = new Float32Array(n);
+    this.solid = new Uint8Array(n);
+  }
+
+  /** Mark a fine-grid cell as solid (wall/stone). Blocks fluid flow. */
+  setSolid(fineX: number, fineY: number): void {
+    const cx = (fineX / COARSE_SCALE) | 0;
+    const cy = (fineY / COARSE_SCALE) | 0;
+    if (cx >= 0 && cx < this.cw && cy >= 0 && cy < this.ch) {
+      this.solid[cy * this.cw + cx] = 1;
+    }
+  }
+
+  /** Clear the solid flag for a fine-grid cell. */
+  clearSolid(fineX: number, fineY: number): void {
+    const cx = (fineX / COARSE_SCALE) | 0;
+    const cy = (fineY / COARSE_SCALE) | 0;
+    if (cx >= 0 && cx < this.cw && cy >= 0 && cy < this.ch) {
+      this.solid[cy * this.cw + cx] = 0;
+    }
+  }
+
+  /**
+   * Apply an impulse at a fine-grid position. Adds to the velocity field
+   * with linear falloff from the center. Used for explosions, fans, etc.
+   */
+  applyImpulse(fineX: number, fineY: number, radius: number, strengthX: number, strengthY: number): void {
+    const ccx = (fineX / COARSE_SCALE) | 0;
+    const ccy = (fineY / COARSE_SCALE) | 0;
+    const cr = Math.ceil(radius / COARSE_SCALE);
+    const cr2 = cr * cr;
+    for (let dy = -cr; dy <= cr; dy++) {
+      const ny = ccy + dy;
+      if (ny < 0 || ny >= this.ch) continue;
+      for (let dx = -cr; dx <= cr; dx++) {
+        const nx = ccx + dx;
+        if (nx < 0 || nx >= this.cw) continue;
+        const dist2 = dx * dx + dy * dy;
+        if (dist2 > cr2) continue;
+        const falloff = 1 - Math.sqrt(dist2) / (cr + 1);
+        const idx = ny * this.cw + nx;
+        if (this.solid[idx]) continue;
+        this.velX[idx] += strengthX * falloff;
+        this.velY[idx] += strengthY * falloff;
+        // Pressure impulse for shockwave effect
+        this.pressure[idx] += Math.abs(strengthX + strengthY) * falloff * 0.3;
+      }
+    }
+    this.dirty = true;
+  }
+
+  /**
+   * Sample horizontal velocity at a fine-grid position using bilinear
+   * interpolation. Returns a velocity in cells/frame units.
+   *
+   * Fast-path: when the fluid grid is not dirty (no active impulses/pressure),
+   * all velocities are zero — skip the bilinear math entirely. This eliminates
+   * ~90% of calls in normal play (no explosions = no fluid activity), which
+   * was the #1 CPU hot spot in profiling (13.3% of total sampled time).
+   */
+  sampleVelX(fineX: number, fineY: number): number {
+    if (!this.dirty) return 0;
+    const fx = fineX / COARSE_SCALE - 0.5;
+    const fy = fineY / COARSE_SCALE - 0.5;
+    const x0 = Math.floor(fx);
+    const y0 = Math.floor(fy);
+    const tx = fx - x0;
+    const ty = fy - y0;
+    const x1 = x0 + 1;
+    const y1 = y0 + 1;
+    const v00 = this.safeVelX(x0, y0);
+    const v10 = this.safeVelX(x1, y0);
+    const v01 = this.safeVelX(x0, y1);
+    const v11 = this.safeVelX(x1, y1);
+    return (1 - tx) * (1 - ty) * v00 + tx * (1 - ty) * v10 +
+           (1 - tx) * ty * v01 + tx * ty * v11;
+  }
+
+  /** Sample vertical velocity at a fine-grid position. */
+  sampleVelY(fineX: number, fineY: number): number {
+    if (!this.dirty) return 0;
+    const fx = fineX / COARSE_SCALE - 0.5;
+    const fy = fineY / COARSE_SCALE - 0.5;
+    const x0 = Math.floor(fx);
+    const y0 = Math.floor(fy);
+    const tx = fx - x0;
+    const ty = fy - y0;
+    const x1 = x0 + 1;
+    const y1 = y0 + 1;
+    const v00 = this.safeVelY(x0, y0);
+    const v10 = this.safeVelY(x1, y0);
+    const v01 = this.safeVelY(x0, y1);
+    const v11 = this.safeVelY(x1, y1);
+    return (1 - tx) * (1 - ty) * v00 + tx * (1 - ty) * v10 +
+           (1 - tx) * ty * v01 + tx * ty * v11;
+  }
+
+  /** Get the raw velocity magnitude at a coarse cell (for debugging/visualization). */
+  getPressure(cx: number, cy: number): number {
+    if (cx < 0 || cx >= this.cw || cy < 0 || cy >= this.ch) return 0;
+    return this.pressure[cy * this.cw + cx];
+  }
+
+  /** Whether any fluid activity exists (for skipping the step when idle). */
+  isActive(): boolean {
+    return this.dirty;
+  }
+
+  /** Clear all fields (e.g. on world clear/resize). */
+  clear(): void {
+    this.pressure.fill(0);
+    this.velX.fill(0);
+    this.velY.fill(0);
+    this.pressureNext.fill(0);
+    this.velXNext.fill(0);
+    this.velYNext.fill(0);
+    this.solid.fill(0);
+    this.dirty = false;
+  }
+
+  /**
+   * Run one simulation step:
+   *   1. Pressure relaxation (diffuse to neighbors)
+   *   2. Velocity from pressure gradient
+   *   3. Velocity damping
+   *
+   * Skipped entirely when no impulses have been applied and all fields are
+   * near-zero (the dirty flag tracks this).
+   */
+  step(): void {
+    if (!this.dirty) return;
+    const cw = this.cw, ch = this.ch;
+    const pressure = this.pressure;
+    const velX = this.velX, velY = this.velY;
+    const pressureNext = this.pressureNext;
+    const velXNext = this.velXNext, velYNext = this.velYNext;
+    const solid = this.solid;
+
+    // --- 1. Pressure relaxation (diffuse) ---
+    // Each cell's pressure moves toward the average of its neighbors.
+    // This is a single Jacobi iteration — enough for visual fluid flow.
+    for (let y = 0; y < ch; y++) {
+      for (let x = 0; x < cw; x++) {
+        const idx = y * cw + x;
+        if (solid[idx]) { pressureNext[idx] = 0; continue; }
+        let sum = pressure[idx] * 2; // self-weight
+        let count = 2;
+        if (x > 0 && !solid[idx - 1]) { sum += pressure[idx - 1]; count++; }
+        if (x < cw - 1 && !solid[idx + 1]) { sum += pressure[idx + 1]; count++; }
+        if (y > 0 && !solid[idx - cw]) { sum += pressure[idx - cw]; count++; }
+        if (y < ch - 1 && !solid[idx + cw]) { sum += pressure[idx + cw]; count++; }
+        pressureNext[idx] = sum / count;
+      }
+    }
+
+    // --- 2. Velocity from pressure gradient ---
+    // velX -= (P[x+1] - P[x-1]) * dt
+    // velY -= (P[y+1] - P[y-1]) * dt
+    // Pressure naturally pushes flow from high to low.
+    const pressureGrad = 0.15;
+    for (let y = 0; y < ch; y++) {
+      for (let x = 0; x < cw; x++) {
+        const idx = y * cw + x;
+        if (solid[idx]) { velXNext[idx] = 0; velYNext[idx] = 0; continue; }
+        const pL = x > 0 && !solid[idx - 1] ? pressureNext[idx - 1] : pressureNext[idx];
+        const pR = x < cw - 1 && !solid[idx + 1] ? pressureNext[idx + 1] : pressureNext[idx];
+        const pU = y > 0 && !solid[idx - cw] ? pressureNext[idx - cw] : pressureNext[idx];
+        const pD = y < ch - 1 && !solid[idx + cw] ? pressureNext[idx + cw] : pressureNext[idx];
+        velXNext[idx] = velX[idx] - (pR - pL) * pressureGrad;
+        velYNext[idx] = velY[idx] - (pD - pU) * pressureGrad;
+      }
+    }
+
+    // --- 3. Damping + pressure decay ---
+    // Velocities decay ~10% per frame. Pressure decays faster (it's a
+    // transient impulse, not a sustained field). This prevents impulses
+    // from persisting forever and keeps the sim stable.
+    const velDamping = 0.9;
+    const pressureDamping = 0.85;
+    let anyActive = false;
+    for (let i = 0; i < cw * ch; i++) {
+      velX[i] = velXNext[i] * velDamping;
+      velY[i] = velYNext[i] * velDamping;
+      pressure[i] = pressureNext[i] * pressureDamping;
+      if (Math.abs(velX[i]) > 0.01 || Math.abs(velY[i]) > 0.01 || Math.abs(pressure[i]) > 0.01) {
+        anyActive = true;
+      }
+    }
+
+    // Clear dirty flag if everything has decayed to near-zero.
+    this.dirty = anyActive;
+  }
+
+  // --- Internal helpers ---
+
+  private safeVelX(cx: number, cy: number): number {
+    if (cx < 0 || cx >= this.cw || cy < 0 || cy >= this.ch) return 0;
+    const idx = cy * this.cw + cx;
+    return this.solid[idx] ? 0 : this.velX[idx];
+  }
+
+  private safeVelY(cx: number, cy: number): number {
+    if (cx < 0 || cx >= this.cw || cy < 0 || cy >= this.ch) return 0;
+    const idx = cy * this.cw + cx;
+    return this.solid[idx] ? 0 : this.velY[idx];
+  }
+}

package/libraries/sand/src/grid-dims.ts

@@ -0,0 +1,74 @@
+// ============================================================================
+// computeGridDims — shared grid dimension calculator for sand/grid games
+// ============================================================================
+//
+// Both falling-sand and sandjongg (and any future grid-based sand game) need
+// to compute sand grid dimensions from canvas buffer pixels. The math is
+// identical except for the base cell size, max grid bounds, and optional
+// alignment. This shared utility eliminates the duplication.
+//
+
+export interface ComputeGridDimsOptions {
+  /** Target canvas buffer pixels per grid cell (before DPR scaling). Higher = larger grains. */
+  baseCellPx: number;
+  /** Maximum grid width in cells (SAB is allocated at this size). */
+  maxGridW: number;
+  /** Maximum grid height in cells (SAB is allocated at this size). */
+  maxGridH: number;
+  /** Minimum grid dimension in cells. Default: 32. */
+  minDim?: number;
+  /**
+   * Align grid dimensions to a multiple of this value (e.g. 4 for 4-byte
+   * alignment of per-row buffers). Default: 1 (no alignment).
+   */
+  align?: number;
+}
+
+/**
+ * Compute sand grid dimensions from canvas buffer dimensions (CSS × DPR).
+ *
+ * The grid is sized so that each cell covers `baseCellPx * dpr` canvas pixels,
+ * keeping cell density consistent across HiDPI displays. If the computed size
+ * exceeds `maxGridW`/`maxGridH`, both dimensions are scaled down proportionally
+ * to preserve the aspect ratio (guarantees square cells).
+ *
+ * @param canvasW  Canvas backing-store width (CSS width × DPR).
+ * @param canvasH  Canvas backing-store height (CSS height × DPR).
+ * @param options  Configuration (base cell size, max grid, alignment).
+ * @returns `{ w, h }` grid dimensions in cells.
+ */
+export function computeGridDims(
+  canvasW: number,
+  canvasH: number,
+  options: ComputeGridDimsOptions,
+): { w: number; h: number } {
+  const { baseCellPx, maxGridW, maxGridH } = options;
+  const minDim = options.minDim ?? 32;
+  const align = options.align ?? 1;
+
+  const dpr = typeof window !== "undefined" ? (window.devicePixelRatio || 1) : 1;
+  const cellPx = baseCellPx * dpr;
+
+  let w = Math.floor(canvasW / cellPx);
+  let h = Math.floor(canvasH / cellPx);
+
+  // Clamp to minimums.
+  w = Math.max(minDim, w);
+  h = Math.max(minDim, h);
+
+  // If either dimension exceeds the max, scale BOTH proportionally
+  // to preserve aspect ratio (guarantees 1:1 cells).
+  if (w > maxGridW || h > maxGridH) {
+    const scale = Math.min(maxGridW / w, maxGridH / h);
+    w = Math.max(minDim, Math.floor(w * scale));
+    h = Math.max(minDim, Math.floor(h * scale));
+  }
+
+  // Align to a multiple of `align` (e.g. 4 for Uint32Array row alignment).
+  if (align > 1) {
+    w = Math.floor(w / align) * align;
+    h = Math.floor(h / align) * align;
+  }
+
+  return { w, h };
+}