# MPC library review and integration record

## Source and scope

The attachment path was a zero-byte placeholder. The exact named extracted
workspace and ZIP were found in Downloads and inspected. The untouched source
ZIP is preserved as `archives/mpc-production-metadata-v0.1.1-original.zip`.
38 transitive core/parser modules were extracted into `shared/audio/mpc/inspector/`;
WAM adapters, DOM-free discovery and the optional browser picker are separated.
The original license attribution is retained. No parser/DSP algorithms were replaced.

The workspace actually has seven consumer mini apps (the original six plus Project
Editor), the Inspector UI, a picker demonstration and launcher. Their responsibilities:

| App | Proof workflow | Library capabilities |
|---|---|---|
| Drum Kit Player | Discover kits, audition pads/layers | graph/sample lookup, instrument audio |
| Drum Exporter | Dry aligned tracks/pads, sequence/project bundles | render plans, MIDI/sample exports, ZIP injection |
| MIDI Explorer | Piano roll, selected-track audition and MIDI export | projection, MIDI encode/plan, public playback |
| Sequence Jukebox | Sequence queue, seek, repeat and track mix | public playback/transport/cache lifecycle |
| Session Grid | Independent quantized clip launching | core plan/sample data, optional WAM adapter; clip orchestration remains app-owned |
| Project Library | Multi-project metadata inventory and search | discovery, graph, productionMetadataFor |
| Project Editor | Rename and validated new archive | metadata summary and non-destructive edit/export |
| Inspector | Original broad exploration/diagnostic UI | existing compatibility paths and core surface |

UI section boundaries and app state remain in the proof apps. No new unrelated
component/mobile package is introduced. Canonical runtime code is excluded from
those apps; their imports and compatibility bridges point to versioned CDN modules.

## Findings corrected

- Public export gap: MpcWamPlayback was consumed through implementation paths.
  It is now documented/exported from the public root/audio facade.
- Lifecycle gap: reset retained AudioContext and manager, with no terminal cleanup.
  Added idempotent destroy() and a guard against recreating audio after teardown;
  existing warm reset behavior is preserved.
- Browser-only construction defect: picker constructor set a host hidden attribute.
  Default hiding now happens on connection; custom element registration is guarded.
- Archive robustness: validate declared sizes/entry counts, traversal and ambiguous
  normalized ZIP paths before decompressing entries. Existing unknown-file semantics
  and non-destructive project editing remain intact.
- Packaging: no UI/test/fixture/app files in runtime distributions; explicit narrow
  facades, browser-only entry, classic loader, deterministic manifests/source maps.
- Optional dependencies: WAM host/catalog/SDK/Tone resolve to existing CDN releases;
  JSZip is shared with the already deployed MPC sampler instead of another vendor copy.
- Shared CDN preservation: audio build previously replaced the whole root catalog.
  It now merges other package entries (including existing Mobile) and retains
  unowned header rules. Regression coverage verifies this and immutable failure behavior.

- Integration regression: discovery omitted nested loose sample directories. The
  fixed ownership rule includes them for a unique project while excluding nested
  projects and other ProjectData subtrees.
- Sampler contract mismatch: saved MPC velocity ranges may start at zero; the
  existing sampler requires note-on range 1–127. New sampler.js converts a copied
  manifest with explicit disclosure and uses the existing sampler loader/DSP.

## Overlap deliberately preserved

MPC sample/mix semantics and MPC-specific MIDI/sequence planning differ from generic
Savoy file playback and streaming recording. Existing PCM WAV encoding in the
MPC offline renderer remains in place rather than changing verified render bytes
for cosmetic deduplication. WAM DSP, host lifecycle, instrument catalog, SDK/Tone
and ZIP bytes are reused. The Sampler WAM and project parser retain distinct
models with tested export/import interoperability boundaries.

## Validation boundary

Baseline: 98 tests across mini apps/shared adapters passed; Inspector had 56
passing runnable scripts and 15 failures requiring external real-project fixtures.
Those fixtures were not included in the supplied archive. The reproducible
canonical runner explicitly lists those 15 as not run and overlays the new runtime
on a disposable copy of the archived proof workspace. All runnable tests must
continue to pass before release. Focused contract tests additionally cover public
exports, read-only inputs/unknown tempo, ZIP refusal before inflation and cleanup.

Actual iPhone Safari, large personal projects and native MPC hardware acceptance
remain manual. Renamed archives must be tested in a separate copied folder; source
validation is not proof of hardware compatibility. No claim of AIR/native plugin
sound parity or continuous background audio is made.

Final browser/deployment evidence is recorded in the project STATUS files and
MPC_TEST_RESULTS.md. Use `savoy history cdn` / `savoy history mpc-lab` for exact
revisions; version pins stay immutable after publication.

MPC 1.0.0 was an initial preview pin. The corrected production release is 1.0.1;
old preview assets remain recoverable. The shared JSZip files are byte-identical.

[Final test evidence](MPC_TEST_RESULTS.md).
