@pluot/core 0.1.0 → 0.1.1

package/src/functional-dom-2d-camera.ts

@@ -0,0 +1,214 @@
+// Functional/stateless adaptation of dom-2d-camera.
+//
+// License copied from https://github.com/flekschas/dom-2d-camera/blob/master/LICENSE.md
+//
+// This software is released under the MIT license:
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy of
+// this software and associated documentation files (the "Software"), to deal in
+// the Software without restriction, including without limitation the rights to
+// use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+// the Software, and to permit persons to whom the Software is furnished to do so,
+// subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+// FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+// COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+// IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+// CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+import { mat4, vec2 } from 'gl-matrix';
+import { ViewportParams } from './viewport.js';
+
+
+export type CameraMatrix = Float32Array;
+
+// Camera configuration constants (matching dom-2d-camera defaults)
+const isFixed = false;
+const isNdc = true;
+const isPan = true;
+const isPanInverted = [false, true];
+const panSpeed = 1;
+const isRotate = true;
+const rotateSpeed = 1;
+const defaultMouseDownMoveAction = "pan";
+const mouseDownMoveModKey = "alt";
+const isZoom = true;
+const zoomSpeed = 1;
+
+// Derived settings
+const isPanX = Array.isArray(isPan) ? Boolean(isPan[0]) : Boolean(isPan);
+const isPanY = Array.isArray(isPan) ? Boolean(isPan[1]) : Boolean(isPan);
+const isPanXInverted = Array.isArray(isPanInverted) ? Boolean(isPanInverted[0]) : Boolean(isPanInverted);
+const isPanYInverted = Array.isArray(isPanInverted) ? Boolean(isPanInverted[1]) : Boolean(isPanInverted);
+const isZoomX = Array.isArray(isZoom) ? Boolean(isZoom[0]) : Boolean(isZoom);
+const isZoomY = Array.isArray(isZoom) ? Boolean(isZoom[1]) : Boolean(isZoom);
+const panOnMouseDownMove = defaultMouseDownMoveAction === "pan";
+
+const KEY_MAP: Record<string, string> = {
+  alt: "altKey",
+  cmd: "metaKey",
+  ctrl: "ctrlKey",
+  meta: "metaKey",
+  shift: "shiftKey",
+};
+
+
+// --- Aspect ratio helpers ---
+
+function computeAspectRatioFactors(vp: ViewportParams) {
+  const aspectRatio = vp.width / vp.height;
+  let xFactor = 1.0;
+  let yFactor = 1.0;
+
+  if (vp.aspectRatioMode === "Contain") {
+    if (aspectRatio > 1.0) xFactor = 1.0 / aspectRatio;
+    else if (aspectRatio < 1.0) yFactor = aspectRatio;
+  } else if (vp.aspectRatioMode === "Cover") {
+    if (aspectRatio > 1.0) yFactor = aspectRatio;
+    else if (aspectRatio < 1.0) xFactor = 1.0 / aspectRatio;
+  }
+
+  let xAlignTranslation = 0.0;
+  let yAlignTranslation = 0.0;
+  if (vp.aspectRatioAlignmentMode === "Start") {
+    xAlignTranslation = xFactor - 1.0;
+    yAlignTranslation = yFactor - 1.0;
+  } else if (vp.aspectRatioAlignmentMode === "End") {
+    xAlignTranslation = 1.0 - xFactor;
+    yAlignTranslation = 1.0 - yFactor;
+  }
+
+  return { xFactor, yFactor, xAlignTranslation, yAlignTranslation };
+}
+
+
+
+// --- Event handlers ---
+
+export function onWheel(viewportParams: ViewportParams, prevCameraMatrix: CameraMatrix, event: WheelEvent): CameraMatrix {
+  event.preventDefault();
+  if ((!isZoomX && !isZoomY) || isFixed) return prevCameraMatrix;
+
+  const { width: plotWidth, height: plotHeight, margins } = viewportParams;
+  const width = plotWidth - ((margins?.marginLeft ?? 0) + (margins?.marginRight ?? 0));
+  const height = plotHeight - ((margins?.marginBottom ?? 0) + (margins?.marginTop ?? 0));
+  const { xFactor, yFactor, xAlignTranslation, yAlignTranslation } = computeAspectRatioFactors(viewportParams);
+
+  const deltaModeScale = event.deltaMode === 1 ? 12 : 1;
+  const scrollDist = deltaModeScale * (event.deltaY || event.deltaX || 0);
+  if (!scrollDist) return prevCameraMatrix;
+
+  const dZ = zoomSpeed * Math.exp(scrollDist / height);
+
+  const px = isNdc
+    ? ((-1 + (event.offsetX / width) * 2) - xAlignTranslation) * (1.0 / xFactor)
+    : event.offsetX;
+  const py = isNdc
+    ? ((1 - (event.offsetY / height) * 2) - yAlignTranslation) * (1.0 / yFactor)
+    : event.offsetY;
+
+  let dx = isZoomX ? 1 / dZ : 1;
+  let dy = isZoomY ? 1 / dZ : 1;
+
+  if (dx <= 0 || dy <= 0 || (dx === 1 && dy === 1)) return prevCameraMatrix;
+
+  const view = mat4.clone(prevCameraMatrix);
+  const s = mat4.fromScaling(mat4.create(), new Float32Array([dx, dy, 1]));
+  const p = new Float32Array([px, py, 0]);
+  const a = mat4.fromTranslation(mat4.create(), p);
+  const aInv = mat4.invert(mat4.create(), a)!;
+
+  // view = a * s * aInv * prevCameraMatrix  (scale about mouse pivot)
+  mat4.multiply(view, aInv, view);
+  mat4.multiply(view, s, view);
+  mat4.multiply(view, a, view);
+
+  return view as unknown as CameraMatrix;
+}
+
+export function onMouseMove(viewportParams: ViewportParams, prevCameraMatrix: CameraMatrix, event: MouseEvent): CameraMatrix {
+  const { width: plotWidth, height: plotHeight, margins } = viewportParams;
+  const width = plotWidth - ((margins?.marginLeft ?? 0) + (margins?.marginRight ?? 0));
+  const height = plotHeight - ((margins?.marginBottom ?? 0) + (margins?.marginTop ?? 0));
+  const { xFactor, yFactor } = computeAspectRatioFactors(viewportParams);
+
+  const isLeftMousePressed = (event.buttons & 1) !== 0;
+  const isMouseDownMoveModActive = Boolean((event as unknown as Record<string, boolean>)[KEY_MAP[mouseDownMoveModKey]]);
+
+  const view = mat4.clone(prevCameraMatrix);
+  let changed = false;
+
+  // Pan
+  if (
+    (isPanX || isPanY) &&
+    isLeftMousePressed &&
+    ((panOnMouseDownMove && !isMouseDownMoveModActive) ||
+      (!panOnMouseDownMove && isMouseDownMoveModActive))
+  ) {
+    const dX = isPanXInverted ? -event.movementX : event.movementX;
+    const dY = isPanYInverted ? -event.movementY : event.movementY;
+    const tx = isPanX ? (isNdc ? ((panSpeed * dX) / width) * 2 * (1.0 / xFactor) : panSpeed * dX) : 0;
+    const ty = isPanY ? (isNdc ? ((panSpeed * dY) / height) * 2 * (1.0 / yFactor) : -(panSpeed * dY)) : 0;
+
+    if (tx !== 0 || ty !== 0) {
+      const t = mat4.fromTranslation(mat4.create(), new Float32Array([tx, ty, 0]));
+      mat4.multiply(view, t, view);
+      changed = true;
+    }
+  }
+
+  // Rotate
+  if (
+    isRotate &&
+    isLeftMousePressed &&
+    ((panOnMouseDownMove && isMouseDownMoveModActive) ||
+      (!panOnMouseDownMove && !isMouseDownMoveModActive)) &&
+    (Math.abs(event.movementX) + Math.abs(event.movementY)) > 0
+  ) {
+    const wh = width / 2;
+    const hh = height / 2;
+    const x1 = (event.offsetX - event.movementX) - wh;
+    const y1 = hh - (event.offsetY - event.movementY);
+    const x2 = event.offsetX - wh;
+    const y2 = hh - event.offsetY;
+
+    if (x1 * x1 + y1 * y1 > 0 && x2 * x2 + y2 * y2 > 0) {
+      const radians = vec2.angle([x1, y1], [x2, y2]);
+      const cross = x1 * y2 - x2 * y1;
+      const rad = rotateSpeed * radians * Math.sign(cross);
+      if (rad !== 0) {
+        const r = mat4.fromRotation(mat4.create(), rad, new Float32Array([0, 0, 1]));
+        mat4.multiply(view, r, view);
+        changed = true;
+      }
+    }
+  }
+
+  return changed ? view as unknown as CameraMatrix : prevCameraMatrix;
+}
+
+// These handlers don't modify the camera matrix in the functional approach.
+// Button state is read from event.buttons in onMouseMove; modifier key state
+// is read from event.altKey/etc. in onMouseMove.
+
+export function onMouseDown(_viewportParams: ViewportParams, prevCameraMatrix: CameraMatrix, _event: MouseEvent): CameraMatrix {
+  return prevCameraMatrix;
+}
+
+export function onMouseUp(_viewportParams: ViewportParams, prevCameraMatrix: CameraMatrix, _event: MouseEvent): CameraMatrix {
+  return prevCameraMatrix;
+}
+
+export function onKeyDown(_viewportParams: ViewportParams, prevCameraMatrix: CameraMatrix, _event: KeyboardEvent): CameraMatrix {
+  return prevCameraMatrix;
+}
+
+export function onKeyUp(_viewportParams: ViewportParams, prevCameraMatrix: CameraMatrix, _event: KeyboardEvent): CameraMatrix {
+  return prevCameraMatrix;
+}

package/src/index.ts

@@ -7,7 +7,7 @@ export {
   setStoreByName,
   getStore,
 } from './core.js';
-export { default as create2dCamera } from "./dom-2d-camera.js";
-export { default as create3dCamera } from "./3d-view-controls.js";
 export { checkWebGpuFeatureDetection } from './feature-detection.js';
 export { getBounds, getCameraMatrixFromBounds } from './viewport.js';
+export { onMouseMove as onMouseMove2d, onWheel as onWheel2d } from './functional-dom-2d-camera.js';
+export { onMouseMove as onMouseMove3d, onWheel as onWheel3d } from './functional-3d-view-controls.js';

package/src/lru-store.ts

@@ -45,6 +45,9 @@ export class LruStore<S extends AsyncReadable> implements AsyncReadable {
 
   // We need a way to synchronously peek at the promise state (a-la Bun's peek or Effect's Deferred.poll).
   // We can probably do something more sophisticated but will try this first.
+  // TODO: should this map be stored on the Rust side instead, so that the peeking can be performed without
+  // the JS function call? Instead, JS would "push" the promise states by calling a Rust function upon any
+  // promise state change, via a new function exposed from Rust such as `wasm.push_promise_state(key, 'fulfilled')`
   #promise_states: Map<string, 'pending' | 'fulfilled' | 'rejected'>;
 
   constructor(store: S, maxSize = 100) {

package/src/viewport.test.ts

@@ -0,0 +1,262 @@
+import { describe, it, expect } from 'vitest';
+import { getBounds, getCameraMatrixFromBounds } from './viewport.js';
+import type { AspectRatioMode, AspectRatioAlignmentMode, ViewportParams } from './viewport.js';
+
+function identityCamera(): Float32Array {
+  return new Float32Array([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+  ]);
+}
+
+function zoomCamera(zoom: number): Float32Array {
+  return new Float32Array([
+    zoom, 0,    0, 0,
+    0,    zoom, 0, 0,
+    0,    0,    1, 0,
+    0,    0,    0, 1,
+  ]);
+}
+
+function zoomAndTranslateCamera(zoom: number, tx: number, ty: number): Float32Array {
+  return new Float32Array([
+    zoom, 0,    0, 0,
+    0,    zoom, 0, 0,
+    0,    0,    1, 0,
+    tx,   ty,   0, 1,
+  ]);
+}
+
+function makeViewport(
+  width: number,
+  height: number,
+  aspectRatioMode: AspectRatioMode,
+  aspectRatioAlignmentMode: AspectRatioAlignmentMode = 'Center',
+): ViewportParams {
+  return { width, height, aspectRatioMode, aspectRatioAlignmentMode };
+}
+
+function expectArrayCloseTo(actual: Float32Array, expected: Float32Array, numDigits = 5): void {
+  expect(actual.length).toBe(expected.length);
+  for (let i = 0; i < actual.length; i++) {
+    expect(actual[i]).toBeCloseTo(expected[i], numDigits);
+  }
+}
+
+// =================== getBounds ===================
+
+describe('getBounds', () => {
+  it('identity camera, square, Ignore → full [0, 1] range', () => {
+    const b = getBounds(identityCamera(), makeViewport(100, 100, 'Ignore'));
+    expect(b.xMin).toBeCloseTo(0);
+    expect(b.xMax).toBeCloseTo(1);
+    expect(b.yMin).toBeCloseTo(0);
+    expect(b.yMax).toBeCloseTo(1);
+  });
+
+  it('2x zoom, square, Ignore → [0.25, 0.75]', () => {
+    const b = getBounds(zoomCamera(2), makeViewport(100, 100, 'Ignore'));
+    expect(b.xMin).toBeCloseTo(0.25);
+    expect(b.xMax).toBeCloseTo(0.75);
+    expect(b.yMin).toBeCloseTo(0.25);
+    expect(b.yMax).toBeCloseTo(0.75);
+  });
+
+  it('0.5x zoom (zoomed out 2x), square, Ignore → [-0.5, 1.5]', () => {
+    const b = getBounds(zoomCamera(0.5), makeViewport(100, 100, 'Ignore'));
+    expect(b.xMin).toBeCloseTo(-0.5);
+    expect(b.xMax).toBeCloseTo(1.5);
+    expect(b.yMin).toBeCloseTo(-0.5);
+    expect(b.yMax).toBeCloseTo(1.5);
+  });
+
+  it('wide (200×100), Contain → x extends to [-0.5, 1.5], y stays [0, 1]', () => {
+    const b = getBounds(identityCamera(), makeViewport(200, 100, 'Contain'));
+    expect(b.xMin).toBeCloseTo(-0.5);
+    expect(b.xMax).toBeCloseTo(1.5);
+    expect(b.yMin).toBeCloseTo(0);
+    expect(b.yMax).toBeCloseTo(1);
+  });
+
+  it('tall (100×200), Contain → x stays [0, 1], y extends to [-0.5, 1.5]', () => {
+    const b = getBounds(identityCamera(), makeViewport(100, 200, 'Contain'));
+    expect(b.xMin).toBeCloseTo(0);
+    expect(b.xMax).toBeCloseTo(1);
+    expect(b.yMin).toBeCloseTo(-0.5);
+    expect(b.yMax).toBeCloseTo(1.5);
+  });
+
+  it('wide (200×100), Cover → x stays [0, 1], y shrinks to [0.25, 0.75]', () => {
+    const b = getBounds(identityCamera(), makeViewport(200, 100, 'Cover'));
+    expect(b.xMin).toBeCloseTo(0);
+    expect(b.xMax).toBeCloseTo(1);
+    expect(b.yMin).toBeCloseTo(0.25);
+    expect(b.yMax).toBeCloseTo(0.75);
+  });
+
+  it('with margins, square (100×100), Ignore → [0, 1] × [0, 1]', () => {
+    const viewport: ViewportParams = {
+      ...makeViewport(100, 100, 'Ignore'),
+      margins: { marginLeft: 20, marginBottom: 20 },
+    };
+    const b = getBounds(identityCamera(), viewport);
+    expect(b.xMin).toBeCloseTo(0);
+    expect(b.xMax).toBeCloseTo(1);
+    expect(b.yMin).toBeCloseTo(0);
+    expect(b.yMax).toBeCloseTo(1);
+  });
+});
+
+// =================== getCameraMatrixFromBounds ===================
+
+describe('getCameraMatrixFromBounds', () => {
+  it('full [0, 1] range → identity camera', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: 0, xMax: 1, yMin: 0, yMax: 1 },
+      identityCamera(),
+      makeViewport(100, 100, 'Ignore'),
+    );
+    expectArrayCloseTo(camera, identityCamera());
+  });
+
+  it('[0.25, 0.75] × [0.25, 0.75] → 2x zoom camera', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: 0.25, xMax: 0.75, yMin: 0.25, yMax: 0.75 },
+      identityCamera(),
+      makeViewport(100, 100, 'Ignore'),
+    );
+    expectArrayCloseTo(camera, zoomCamera(2));
+  });
+
+  it('[-0.5, 1.5] × [-0.5, 1.5] → 0.5x zoom (zoomed out 2x)', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: -0.5, xMax: 1.5, yMin: -0.5, yMax: 1.5 },
+      identityCamera(),
+      makeViewport(100, 100, 'Ignore'),
+    );
+    expectArrayCloseTo(camera, zoomCamera(0.5));
+  });
+
+  it('x-offset bounds → zoom=1, translateX=0.5, translateY=0', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: -0.25, xMax: 0.75, yMin: 0, yMax: 1 },
+      identityCamera(),
+      makeViewport(100, 100, 'Ignore'),
+    );
+    expectArrayCloseTo(camera, zoomAndTranslateCamera(1, 0.5, 0));
+  });
+
+  it('zoom + translation bounds → zoom=2, translateX=0.5, translateY=0.25', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: 0.125, xMax: 0.625, yMin: 0.1875, yMax: 0.6875 },
+      identityCamera(),
+      makeViewport(100, 100, 'Ignore'),
+    );
+    expectArrayCloseTo(camera, zoomAndTranslateCamera(2, 0.5, 0.25));
+  });
+
+  it('wide Contain bounds [-0.5, 1.5] × [0, 1] → identity camera', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: -0.5, xMax: 1.5, yMin: 0, yMax: 1 },
+      identityCamera(),
+      makeViewport(200, 100, 'Contain'),
+    );
+    expectArrayCloseTo(camera, identityCamera());
+  });
+
+  it('tall Contain bounds [0, 1] × [-0.5, 1.5] → identity camera', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: 0, xMax: 1, yMin: -0.5, yMax: 1.5 },
+      identityCamera(),
+      makeViewport(100, 200, 'Contain'),
+    );
+    expectArrayCloseTo(camera, identityCamera());
+  });
+
+  it('wide Cover bounds [0, 1] × [0.25, 0.75] → identity camera', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: 0, xMax: 1, yMin: 0.25, yMax: 0.75 },
+      identityCamera(),
+      makeViewport(200, 100, 'Cover'),
+    );
+    expectArrayCloseTo(camera, identityCamera());
+  });
+
+  it('asymmetric ranges, Ignore → independent x/y zoom', () => {
+    const camera = getCameraMatrixFromBounds(
+      { xMin: 0, xMax: 0.5, yMin: 0, yMax: 1 },
+      identityCamera(),
+      makeViewport(100, 100, 'Ignore'),
+    );
+    expectArrayCloseTo(camera, new Float32Array([
+      2, 0, 0, 0,
+      0, 1, 0, 0,
+      0, 0, 1, 0,
+      1, 0, 0, 1,
+    ]));
+  });
+
+  it('partial bounds (x-axis only) preserves y from prevCameraMatrix', () => {
+    const prevCamera = zoomAndTranslateCamera(2, 0.5, 0.25);
+    const viewport = makeViewport(100, 100, 'Ignore');
+    const prevBounds = getBounds(prevCamera, viewport);
+
+    const camera = getCameraMatrixFromBounds(
+      { xMin: 0, xMax: 1 },
+      prevCamera,
+      viewport,
+    );
+    const newBounds = getBounds(camera, viewport);
+
+    expect(newBounds.xMin).toBeCloseTo(0);
+    expect(newBounds.xMax).toBeCloseTo(1);
+    expect(newBounds.yMin).toBeCloseTo(prevBounds.yMin);
+    expect(newBounds.yMax).toBeCloseTo(prevBounds.yMax);
+  });
+});
+
+// =================== getBounds / getCameraMatrixFromBounds roundtrip ===================
+
+describe('getBounds / getCameraMatrixFromBounds roundtrip', () => {
+  it('identity camera → bounds → identity camera', () => {
+    const viewport = makeViewport(100, 100, 'Ignore');
+    const bounds = getBounds(identityCamera(), viewport);
+    const camera = getCameraMatrixFromBounds(bounds, identityCamera(), viewport);
+    expectArrayCloseTo(camera, identityCamera());
+  });
+
+  it('2x zoom camera → bounds → 2x zoom camera', () => {
+    const viewport = makeViewport(100, 100, 'Ignore');
+    const camera0 = zoomCamera(2);
+    const bounds = getBounds(camera0, viewport);
+    const camera1 = getCameraMatrixFromBounds(bounds, identityCamera(), viewport);
+    expectArrayCloseTo(camera1, camera0);
+  });
+
+  it('wide Contain viewport, identity camera → bounds → identity camera', () => {
+    const viewport = makeViewport(200, 100, 'Contain');
+    const bounds = getBounds(identityCamera(), viewport);
+    const camera = getCameraMatrixFromBounds(bounds, identityCamera(), viewport);
+    expectArrayCloseTo(camera, identityCamera());
+  });
+
+  it('zoom + translation → bounds → same camera', () => {
+    const viewport = makeViewport(100, 100, 'Ignore');
+    const camera0 = zoomAndTranslateCamera(2, 0.5, 0.25);
+    const bounds = getBounds(camera0, viewport);
+    const camera1 = getCameraMatrixFromBounds(bounds, identityCamera(), viewport);
+    expectArrayCloseTo(camera1, camera0);
+  });
+
+  it('with margins, identity camera → bounds → identity camera', () => {
+    const viewport: ViewportParams = {
+      ...makeViewport(100, 100, 'Ignore'),
+      margins: { marginLeft: 20, marginBottom: 20 },
+    };
+    const bounds = getBounds(identityCamera(), viewport);
+    const camera = getCameraMatrixFromBounds(bounds, identityCamera(), viewport);
+    expectArrayCloseTo(camera, identityCamera());
+  });
+});

package/src/viewport.ts

@@ -29,7 +29,44 @@ export type Bounds = {
   yMax?: number;
 };
 
-// Calculate the visible data range based on camera view and viewport parameters.
+/**
+ * Calculate the visible data range based on camera view and viewport parameters.
+ *
+ * Bounds are expressed in normalized data coordinates where 0.0 is the
+ * left/top edge of the data and 1.0 is the right/bottom edge.
+ *
+ * @param cameraMatrix - The current camera matrix, typically from the renderer's
+ *   current state.
+ * @param viewportParams - Describes the canvas size, aspect-ratio handling, and
+ *   margins.
+ * @returns The visible data range as `{ xMin, xMax, yMin, yMax }` in normalized
+ *   data coordinates.
+ *
+ * @example
+ * ```ts
+ * import { getBounds } from "@pluot/core";
+ *
+ * const viewport = {
+ *   width: 800,
+ *   height: 600,
+ *   aspectRatioMode: "Contain",
+ *   aspectRatioAlignmentMode: "Center",
+ *   margins: { marginTop: 10, marginRight: 10, marginBottom: 10, marginLeft: 10 },
+ * };
+ *
+ * // Identity camera matrix (full data range visible).
+ * const identity = new Float32Array([
+ *   1, 0, 0, 0,
+ *   0, 1, 0, 0,
+ *   0, 0, 1, 0,
+ *   0, 0, 0, 1,
+ * ]);
+ *
+ * const bounds = getBounds(identity, viewport);
+ * // bounds.xMin, bounds.xMax, bounds.yMin, bounds.yMax are all in [0, 1]
+ * // for the identity matrix with "Contain" mode.
+ * ```
+ */
 export function getBounds(cameraMatrix: Float32Array, viewportParams: ViewportParams): Required<Bounds> {
   const zoomX = cameraMatrix[0];
   const zoomY = cameraMatrix[5];
@@ -76,8 +113,59 @@ export function getBounds(cameraMatrix: Float32Array, viewportParams: ViewportPa
   return { xMin, xMax, yMin, yMax };
 }
 
-// Given data bounds, compute the corresponding camera matrix.
-// Missing bound values are filled in from prevCameraMatrix.
+/**
+ * Given data bounds, compute the corresponding camera matrix.
+ * Missing bound values are filled in from `prevCameraMatrix` so partial updates
+ * (e.g. panning only the X axis) work without resetting the other axis.
+ *
+ * Bounds are expressed in normalized data coordinates where 0.0 is the
+ * left/top edge of the data and 1.0 is the right/bottom edge.
+ *
+ * @param bounds - The desired visible data range. Any omitted fields are
+ *   preserved from `prevCameraMatrix`.
+ * @param prevCameraMatrix - The current camera matrix, used to fill in any
+ *   omitted bound values. Typically the matrix returned by a previous call or
+ *   the renderer's current state.
+ * @param viewportParams - Describes the canvas size, aspect-ratio handling, and
+ *   margins so the zoom level can be computed correctly.
+ * @returns A column-major 4×4 `Float32Array` suitable for passing directly to
+ *   the renderer as the camera matrix.
+ *
+ * @example
+ * ```ts
+ * import { getCameraMatrixFromBounds } from "@pluot/core";
+ *
+ * const viewport = {
+ *   width: 800,
+ *   height: 600,
+ *   aspectRatioMode: "Contain",
+ *   aspectRatioAlignmentMode: "Center",
+ *   margins: { marginTop: 10, marginRight: 10, marginBottom: 10, marginLeft: 10 },
+ * };
+ *
+ * // Identity camera matrix (full data range visible).
+ * const identity = new Float32Array([
+ *   1, 0, 0, 0,
+ *   0, 1, 0, 0,
+ *   0, 0, 1, 0,
+ *   0, 0, 0, 1,
+ * ]);
+ *
+ * // Zoom into the top-left quadrant of the data.
+ * const cameraMatrix = getCameraMatrixFromBounds(
+ *   { xMin: 0.0, xMax: 0.5, yMin: 0.0, yMax: 0.5 },
+ *   identity,
+ *   viewport,
+ * );
+ *
+ * // Pan to shift only the X axis, keeping Y unchanged.
+ * const pannedMatrix = getCameraMatrixFromBounds(
+ *   { xMin: 0.1, xMax: 0.6 },
+ *   cameraMatrix,
+ *   viewport,
+ * );
+ * ```
+ */
 export function getCameraMatrixFromBounds(bounds: Bounds, prevCameraMatrix: Float32Array, viewportParams: ViewportParams): Float32Array {
   // Fill in missing bounds from the previous camera matrix.
   const currentBounds = getBounds(prevCameraMatrix, viewportParams);