first commit

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

@@ -0,0 +1,36 @@
+# Engine Zoom Helpers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `zoom.ts` module bridges `TimelineEngine` zoom, selection, and loop public methods to the pure `timeline-operations.ts` and `zoom.ts` helpers. It manages internal state updates and event emission so the engine class stays focused on high-level orchestration.
+
+## Features
+
+- `engineZoomIn` / `engineZoomOut` step through the zoom table and emit `zoomChange`
+- `engineSetZoomLevel` snaps to the nearest table entry
+- `engineSetSelection` normalises ranges and emits `selectionChange`
+- `engineSetLoopRegion` updates loop bounds and forwards to adapter
+- `engineSetLoopEnabled` toggles loop and forwards to adapter
+
+## Usage
+
+These helpers are used internally by `TimelineEngine`. Consumers call `engine.zoomIn()` etc.
+
+## API Reference
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `engineZoomIn` | `(deps) => void` | Zoom in |
+| `engineZoomOut` | `(deps) => void` | Zoom out |
+| `engineSetZoomLevel` | `(deps, samplesPerPixel) => void` | Set zoom |
+| `engineSetSelection` | `(deps, start, end) => void` | Set selection |
+| `engineSetLoopRegion` | `(deps, start, end) => void` | Set loop region |
+| `engineSetLoopEnabled` | `(deps, enabled) => void` | Toggle loop |
+
+## Implementation Notes
+
+The `ZoomDeps` interface isolates the helpers from the engine class, making them testable in isolation. Loop changes are forwarded to the adapter immediately so the audio backend can update its loop markers. Selection changes are clamped to the current document duration so invalid ranges cannot be created. Zoom changes only affect the view and do not touch the arrangement, which is why they bypass the undo stack entirely.