# Bunker Editor 0.1 — portable architecture

The editor is a new website component. Firmware 1.0 is unchanged, SHA-256
`db0b50d0ae9c3bfccee76e3b93de09fffa55389169278a0c5899dad9c79e6bb8`.

| Module | Responsibility | Reuse path |
| --- | --- | --- |
| core/music.mjs | Notes, 32 scales, motifs, seeded GROW, phrase JSON v1 | Runs without DOM, MIDI or audio; reusable in web/native-hosted JS; algorithms can be ported to C++ later. |
| core/protocol.mjs | Felucca SysEx codec, strict validation, reply matching, single-flight queue | Reusable unchanged with any byte transport. |
| core/device.mjs | Identify/read device, descriptors, parameters, sound recipes, stopped phrase writes/readback, undo conflict check | Shared application service for browser or native shell. |
| adapters/web-midi.mjs | Explicit port choice, SysEx permission, disconnect handling, same-origin editor/installer lock | Replace with a native CoreMIDI/USB bridge on iOS/iPadOS/macOS. |
| adapters/offline.mjs | Silent local model for sketching and file exchange | UI development and offline phrase composition. It does not simulate audio or autonomous EVOLVE. |
| app.mjs + editor.css | Responsive DOM interface | Reuse in a web view or replace with native UI. |
| data.json | Engine/parameter tables generated by the actual C source; Bunker library and scales | Reproducible with tools/build_editor_data.py; actual hardware descriptors take priority. |

Transport contract: `send(Uint8Array)`, `onData(bytes)`, `onClose()`, `close()`.
Requests are asynchronous, one in flight, with an 8 ms gap. Slider changes are sent
on committed change rather than every pointer movement. A timeout closes the session;
queued writes are rejected and never replayed automatically. The device reports clamped
values; the editor detects mismatches. Bulk sequence writes stop transport, refuse armed
recording, write bounded 64-step messages, then read back. They are not atomic across USB.
On failure, reconnect/read and use the exported pre-edit phrase; do not claim rollback
occurred without successful readback. Undo refuses a subsequently changed sequence.

The editor uses existing runtime commands, not the firmware-update or sample-flash
protocol. Firmware may persist its current session through its existing autosave behaviour;
there is no claim that changing a parameter can never lead to a later firmware-managed save.
Cross-origin editors cannot be excluded by our same-origin Web Lock: close them manually.

Editor 0.1 deliberately covers the ambient workflow: all four tracks, 64 recipes,
factory preset selection, engine macros, envelope/effects/modulation controls, EVOLVE,
24 motif templates, 32 scales, GROW per selected track, note/chord/velocity/chance/
ratchet/nudge editing, phrase import/export and phrase undo. Full WORLD resets remain
on the hardware. There is no direct remote call to the hardware's GROW button; browser
GROW computes notes locally and writes them via the existing sequencer protocol. A seeded
browser variation is reproducible but is not advertised as sharing the hardware's RNG state.
FM6 operator-bank editing, sample management, song-chain authoring, motion editing and
full device backup are outside this editor's first version (use device/upstream tools and
our backup page). No automatic live tracking of hardware changes: press Read from FM-1.

## Future products, not yet delivered

1. Native macOS and iPad/iPhone shells: use the same music core and application service,
   implement native MIDI permissions/ports, lifecycle and file access. Test suspended/
   resumed connections and each supported USB configuration. Installing a web page alone
   is not a native CoreMIDI implementation.
2. DAW controller plug-in: wrap editor/state in a native AU/VST3 host, implement parameter
   IDs, host automation, saved state, tempo/MIDI routing and main/audio-thread separation.
   Browser timers/USB I/O must never run on a real-time audio callback.
3. Standalone software instrument plug-in: additionally integrate and validate the native
   DSP with sample-rate/block-size handling, multichannel routing and offline rendering.
   The existing browser simulator is useful evidence, not a finished AU/VST product.

Keep the GPL-3.0-only and all component notices with derivative distributions. Native
packaging, signing, platform review and plugin licensing requirements must be evaluated
for those future distributions.

## Reproduce verification

```sh
python3 tools/build_editor_data.py
cc -O1 -w -Ifirmware/build/gen -Ifirmware/firmware/src -o firmware/build/host/editor_bridge tests/editor_bridge.c -lm
node tests/editor.test.mjs
```

The bridge includes the real firmware handler through the upstream host test harness.
It checks requests and state, not physical USB timing or actual on-device CPU headroom.
Generated firmware tables must exist as documented in the firmware build instructions.