first commit

docs/media/audio/audio-timeline/src/zoom/zoom.md

@@ -0,0 +1,52 @@
+# Zoom Helpers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `zoom.ts` module provides a discrete zoom table and navigation helpers for the timeline view. Zoom levels are expressed as `samplesPerPixel`; larger values show more timeline in fewer pixels. The module is pure and side-effect free, making it safe to use in reducers, audio-thread code, and React memoization.
+
+## Features
+
+- Predefined `DEFAULT_ZOOM_TABLE` with 14 powers-of-two entries (1 to 8192)
+- `zoomIn` / `zoomOut` index arithmetic with boundary capping
+- `setZoomLevel` to snap arbitrary `samplesPerPixel` values to the nearest table entry
+- `canZoomIn` / `canZoomOut` boolean predicates for UI button disabled states
+
+## Usage
+
+### Basic
+
+```ts
+import { zoomIn, zoomOut, DEFAULT_ZOOM_TABLE } from "@suaveplan/audio-timeline/zoom";
+
+let index = 0;
+index = zoomIn(DEFAULT_ZOOM_TABLE, index); // 1
+index = zoomOut(DEFAULT_ZOOM_TABLE, index); // 0
+```
+
+### Advanced
+
+```ts
+import { setZoomLevel, canZoomIn } from "@suaveplan/audio-timeline/zoom";
+
+const result = setZoomLevel(DEFAULT_ZOOM_TABLE, 150); // snaps to 128
+const canGoFiner = canZoomIn(DEFAULT_ZOOM_TABLE, result.zoomIndex);
+```
+
+## API Reference
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `DEFAULT_ZOOM_TABLE` | `readonly number[]` | Default discrete zoom table |
+| `zoomIn` | `(table, index) => number` | Increment zoom index, capped at max |
+| `zoomOut` | `(table, index) => number` | Decrement zoom index, floored at 0 |
+| `setZoomLevel` | `(table, spp) => { zoomIndex, samplesPerPixel }` | Snap to nearest table entry |
+| `canZoomIn` | `(table, index) => boolean` | True if index < max |
+| `canZoomOut` | `(table, index) => boolean` | True if index > 0 |
+
+## Implementation Notes
+
+Using a discrete table instead of a continuous float keeps zoom states comparable by simple index equality. This is useful for React memoization and for persisting user preferences. All helpers are pure and operate only on the table and index, so they can be used in reducers, tests, and even audio-thread code without side effects.