# Design — audio-shipped-file-size-cleanup

This change is a pure mechanical refactor across three packages. The design is the **split strategy** per file: every public symbol stays exported from its current module path; the splits happen *below* the public surface.

---

## 1. `@suaveplan/audio-timeline` — `engine/engine.ts` (548 → ≤300)

`TimelineEngine` is the single class in this file and currently owns:

- Construction + adapter wiring (`setAdapter`, `dispose`)
- Track CRUD (`addTrack`, `removeTrack`, `updateTrack`, `setTracks`)
- Clip CRUD (`addClip`, `removeClip`, `updateClip`, `splitClip`, `joinClip`)
- Mixer mutations (`setMasterVolume`, `setTrackVolume`, `setTrackMute`, `setTrackSolo`, `setTrackPan`)
- Transport (`play`, `pause`, `stop`, `seek`, `setLoop`, `setTempo`)
- Snapshot / restore + undo/redo dispatch
- Event emission

### Proposed split

Keep `TimelineEngine` in `engine.ts` as the public class, but extract helper modules called from its methods:

```text
src/engine/
  engine.ts                        ← class shell + delegating methods (≤300)
  engine-tracks.ts                 ← addTrack/removeTrack/updateTrack/setTracks helpers
  engine-tracks.md
  engine-clips.ts                  ← addClip/removeClip/updateClip/splitClip/joinClip helpers
  engine-clips.md
  engine-mixer.ts                  ← setMasterVolume/setTrackVolume/Mute/Solo/Pan helpers
  engine-mixer.md
  engine-transport.ts              ← play/pause/stop/seek/setLoop/setTempo helpers
  engine-transport.md
  engine.test.ts                   ← class-level invariants only (≤500)
  engine-tracks.test.ts            ← extracted track tests
  engine-clips.test.ts             ← extracted clip tests
  engine-mixer.test.ts             ← extracted mixer tests
  engine-transport.test.ts         ← extracted transport tests
```

Each helper module exports pure functions of `(state, args) => newState` (where `state` is `TimelineEngine`'s internal record) plus any side-effect-free derived values. `TimelineEngine` methods become 1–3 liners that call the helper and forward the result. This pattern matches how `audio-core`'s `process/` directory is structured.

The original `engine.test.ts` splits along the same four axes; the residual `engine.test.ts` keeps construction, adapter wiring, snapshot/restore, undo/redo dispatch, and event emission tests — the cross-cutting concerns no single helper owns.

---

## 2. `@suaveplan/audio-transport` — `transport/transport.ts` (419 → ≤300)

`Transport` is the single class and owns:

- Construction + clock injection
- BPM + time-signature + PPQ state
- Tick advance + lookahead scheduling loop
- Schedule / cancel API
- Loop region + swing
- Tempo automation

### Proposed split

```text
src/transport/
  transport.ts                     ← class shell (≤300)
  transport-schedule.ts            ← schedule/cancel/lookahead helpers
  transport-schedule.md
  transport-tempo.ts               ← BPM + tempo automation + tick conversion helpers
  transport-tempo.md
  transport.test.ts                ← stays as-is (already under cap)
```

No test splitting needed — `transport.test.ts` is already within the 500-line cap.

---

## 3. `@suaveplan/audio-metadata` — `parsers/id3v2/id3v2.ts` (536 → ≤300)

`id3v2.ts` is the most over-budget src file. It owns:

- Magic-byte detection
- Header + extended-header parsing
- Frame iteration
- Per-frame-type decoders (TXXX, T..., COMM, USLT, APIC, UFID, WCOM, WCOP, …)
- Text-encoding decoders (ISO-8859-1, UTF-16, UTF-16BE, UTF-8)
- Unsynchronisation reversal

### Proposed split

```text
src/parsers/id3v2/
  id3v2.ts                         ← public parseId3v2() + frame dispatch (≤300)
  id3v2-header.ts                  ← header + extended-header parsing
  id3v2-header.md
  id3v2-frames-text.ts             ← T... / TXXX text frame decoders
  id3v2-frames-text.md
  id3v2-frames-binary.ts           ← APIC / UFID / GEOB binary frame decoders
  id3v2-frames-binary.md
  id3v2-frames-url.ts              ← W... URL frame decoders
  id3v2-frames-url.md
  id3v2-text-encoding.ts           ← ISO-8859-1 / UTF-16 / UTF-16BE / UTF-8 decoders
  id3v2-text-encoding.md
  id3v2-unsync.ts                  ← unsynchronisation reversal
  id3v2-unsync.md
  id3v2.test.ts                    ← integration parses on real fixture files (≤500)
  id3v2-header.test.ts             ← header-specific
  id3v2-frames-text.test.ts        ← text-frame-specific
  id3v2-frames-binary.test.ts      ← binary-frame-specific
  id3v2-frames-url.test.ts         ← url-frame-specific
  id3v2-text-encoding.test.ts      ← encoding-specific
  id3v2-unsync.test.ts             ← unsync-specific
```

The split mirrors the spec sections of the ID3v2.4 standard, so the file boundaries match how future maintainers will reason about the format.

### `id3v2.test.ts` (1340 → 7 files of ≤500 each)

The current `id3v2.test.ts` mixes header tests, every frame type, encoding round-trips, and integration parses. Splitting by frame family (per the source split above) gives ~150–200 lines per file. The residual `id3v2.test.ts` keeps the end-to-end "parse a real fixture file" cases.

---

## 4. `@suaveplan/audio-metadata` — `parsers/mp4-atom/mp4-atom.ts` (351 → ≤300)

Lightest split. The file owns atom-walking + per-atom decoders (`ftyp`, `moov`, `mvhd`, `mdat`, `ilst` and the iTunes metadata sub-atoms). Extract the iTunes-specific decoders:

```text
src/parsers/mp4-atom/
  mp4-atom.ts                      ← public parseMp4Atom() + container walker (≤300)
  mp4-atom-itunes.ts               ← iTunes/ilst metadata decoders
  mp4-atom-itunes.md
  mp4-atom.test.ts                 ← container + non-iTunes tests (≤500)
  mp4-atom-itunes.test.ts          ← iTunes-specific
```

---

## 5. `@suaveplan/audio-metadata` — `parsers/ogg-vorbis/ogg-vorbis.test.ts` (803 → ≤500)

Source file is already within cap. Only the test file needs splitting:

```text
src/parsers/ogg-vorbis/
  ogg-vorbis.ts                    ← unchanged
  ogg-vorbis.test.ts               ← page parsing + comment header (≤500)
  ogg-vorbis-frames.test.ts        ← extracted frame-level tests
```

---

## 6. Cross-cutting rules for the split

- **Public surface is invariant.** Every existing `export` from `<pkg>/src/index.ts` must continue to resolve to the same symbol with the same signature. The split is *internal*.
- **Subpath exports unchanged.** The `package.json` `exports` map for each package keeps every existing entry. New internal helper modules are NOT added to `exports` — they are implementation details.
- **Barrels use explicit named re-exports** (§6a). No `export * from` in new feature barrels.
- **Sibling `.md` files** added for every new `.ts` per §4 (200-word minimum, six required sections).
- **Coverage stays 100/100/100/100** per `vitest.config.ts` thresholds.
- **No new behavior.** A diff of `dist/*.d.ts` must show only path changes — no type-shape changes.

## 7. Risk

Low. The packages have no published consumers; the refactor is mechanical; the tests are the contract and they all must continue to pass. The largest file (`id3v2.test.ts` at 1340 lines) is the highest-leverage win: shrinking it makes the format-spec correspondence explicit and gives future maintainers per-frame-family focus.

The one non-mechanical risk is in `audio-timeline/engine.ts` — extracting helper modules implies extracting a `TimelineEngineState` shape, which is currently inlined as private class fields. The helpers operate on that shape; if the extraction inadvertently widens the visibility of private state, the public surface widens. Mitigation: keep `TimelineEngineState` as a non-exported type in `engine-state.ts` (or inline in `engine.ts`) and pass it explicitly to helpers; do not export it.