first commit

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

@@ -0,0 +1,35 @@
+# Engine Clip Helpers
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+The `clip.ts` module contains the internal bridge between `TimelineEngine` public methods and the pure `clip-operations.ts` helpers. It wraps each operation with OTel span recording, histogram timing, and event emission so the engine class stays focused on orchestration.
+
+## Features
+
+- `engineAddClip` appends a clip and emits `clipChange`
+- `engineRemoveClip` filters a clip and emits `clipChange`
+- `engineMoveClip` applies constrained drags, skips no-ops, and records duration
+- `engineTrimClip` trims a boundary and records a `timeline.clip_operation` span
+- `engineSplitClip` splits a clip and records a `timeline.clip_operation` span
+
+## Usage
+
+These helpers are used internally by `TimelineEngine`. Consumers interact with the engine's public methods instead.
+
+## API Reference
+
+| Export | Signature | Description |
+|--------|-----------|-------------|
+| `engineAddClip` | `(deps, trackId, clip) => void` | Add clip |
+| `engineRemoveClip` | `(deps, trackId, clipId) => void` | Remove clip |
+| `engineMoveClip` | `(deps, trackId, clipId, delta) => number` | Move clip |
+| `engineTrimClip` | `(deps, trackId, clipId, boundary, delta) => void` | Trim clip |
+| `engineSplitClip` | `(deps, trackId, clipId, atSample) => void` | Split clip |
+
+## Implementation Notes
+
+The `ClipDeps` interface decouples the helpers from the engine class, making them testable in isolation. Histograms record `audio_timeline_clip_operation_duration_ms` for every trim and split. No-op moves (where the constrained delta is zero) skip both the undo push and the event emission, keeping the history clean. OTel spans include the operation name, track id, and clip id so that performance traces can pinpoint slow interactions.