memlnaut-nisps/docs/specs/plans/browser-mode-coverage-spec.md

kind	status
plan	active

Browser Mode Coverage Honesty — audio topology as declared, verified truth

Dated 2026-07-21. Spec for plans/simplification-plan.md §6.5b (audit finding A2), written spec-first per plan §6 — proposal only, no phase adopted. Companion decisions live in §8. Absorbs the old ALIGNMENT "browser-only engines incomplete / mic input" defect.

Every claim below was checked against the tree at fd0aee2. Measurements are reproducible; the exact commands are given. Where I could not verify something I say so instead of asserting it.

---

§0 What is actually true today (measured, not inferred)

Two independent probes, both run 2026-07-21:

1. Native, engines compiled straight from nisps/engines/*.hpp (g++ -std=gnu++20 -O2 -I nisps).
2. The committed WASM artifact manifold/public/nisps.{js,wasm}, driven through the exact C ABI the AudioWorklet uses (nisps_engine_create / set_params / process_block), loaded with the same glue dance as manifold/tests/loss-history.test.ts.

Both were run for 2 s at 48 kHz with all params 0.5, first with a silent input, then with a 0.3-amplitude 220 Hz sine. Output RMS (left channel):

engine	silent in	sine in	native == wasm
paf_synth	0.000000000	(ignores input)	yes
channel_strip	0.000000000	0.446555	yes (≤1e-6)
xiasri	0.000000000	0.848909	yes (≤1e-6)
verb_fx	0.000346808	0.267881	yes (≤1e-6)
memlcelium	0.399765	(ignores input)	yes
breakor	0.000000000	—	yes
elysiamorf	0.000000000	—	yes
analysis	0.000000000	0.000000000	yes
thru	0.000000000	—	yes

Reading that against what the browser host actually supplies:

• Nothing is ever connected to the worklet's audio input. EngineHost constructs the node with numberOfInputs: 1 (manifold/src/engine/engine-host.ts:117) and connects it to the destination (:121), but there is no getUserMedia, MediaStream, or createMediaStreamSource anywhere in manifold/src (grep: zero hits). The worklet already reads inputs[0] (manifold/src/engine/worklet/nisps-processor.ts:266-271) and zero-fills when absent — so the DSP side is done and the gap is one main-thread connection.
• The engine C ABI has four entry points only: create / destroy / set_params / process_block (nisps/wasm/bindings.cpp:1074-1108, exported at scripts/build-wasm.sh:70-71). There is no note_on, no set_playing, no update_bpm, no pop_events, no feature readback.

Therefore, of the nine schema-backed modes, exactly two produce audio in the browser today: memlcelium and slp_workshop (which share the memlcelium engine).

mode	why it is silent / inert in the browser
paf_synth	Note-gated. process() multiplies by env_.play() and the ADSR idles in WaitToTrig → exactly 0 (nisps/engines/paf_synth.hpp:114, nisps/dsp/env.hpp). Only note_on starts it (:132-138), and no browser path calls it.
channel_strip	Pure input processor; no audio input connected.
verb_fx	Pure input processor; RMS 3.5e-4 from a zero input is residual, not a signal.
xiasri	Pure input processor; no audio input connected.
breakor	Event-only by design (nisps/engines/breakor.hpp:81-109 returns {0,0}). playing_ defaults true (:159) so it does tick and enqueue, but pop_events is not exported, so the 64-slot EventQueue fills and silently drops (nisps/core/event_queue.hpp:44-49).
elysiamorf	Same shape (nisps/engines/elysiamorf.hpp:100-104, playing_ = true at :136).
sound_analysis_midi	Needs mic and a features readback. AnalysisEngine::process returns silence and exposes features() / copy_features() (nisps/engines/analysis.hpp:129, :188-196) — neither is exported.
visualizer (manifold-only)	Correctly silent: it is a visual mode on thru.
c15 (manifold-only)	Already honest — placeholder: true, badge: 'soon' (manifold/src/console/model.ts:301-313).

How the table was produced

Both probes were throwaway scripts in /tmp, not committed — §5 step 2 turns them into permanent tests, which is the point of this document. Their shape, so they can be rebuilt in ten minutes:

• Native. One .cpp including nisps/engines/*.hpp; per engine: default-construct, setup(48000.f), set_params with a param_count()-sized vector of 0.5f, then 96 000 calls to process({s, s}) accumulating y.L² + y.R²; s is 0 or 0.3 · sin(2π·220·i/48000). Built with g++ -std=gnu++20 -O2 -I nisps.
• Committed WASM. A bun script using the same glue-loading dance as manifold/tests/loss-history.test.ts:34-45 (new Function(...) over public/nisps.js, then factory({ wasmBinary: public/nisps.wasm })), then M.cwrap for nisps_engine_create, nisps_engine_set_params, nisps_engine_process_block, nisps_engine_destroy; engine id written as NUL-terminated ASCII into a 32-byte _malloc buffer exactly as the worklet does (nisps-processor.ts:217-230); 750 blocks × 128 frames.

The two agreed to ≤1e-6 on every engine — incidental corroboration that WASM parity holds on a path scripts/parity-check.sh does not cover.

---

§1 Where the brief and the audit are wrong

Trust the code over these documents, including this one.

1. "4 modes that structurally cannot run" is an undercount. Audit A2 names breakor, elysiamorf, xiasri, sound_analysis_midi. channel_strip and verb_fx are in exactly the same position as xiasri — all three are pure input processors with no input connected — and paf_synth, the catalogue's flagship, is silent for a third reason the audit's four-way enum cannot even express. The real number is 7 of 9.
2. "The UI presents them as available" is false today. There is no instrument-mode picker in Manifold at all. ConsoleApp.tsx:326-329 says so explicitly; ctx.modes / ctx.setModeId are plumbed with no renderer (manifold/src/console/types.ts:50-57, 64-66); the Dock's "Mode" selector is the output backend picker, not the instrument (manifold/src/console/output-mode.ts:1-18). The only way to reach another mode is window.__mf.setMode() under ?debug=1. Consequence for sequencing: the dishonesty is latent. It fires the moment §6.5c builds the picker. 5b is therefore a prerequisite of 5c, and a "badge" alone would ship a component no user can see. What 5b must deliver is the data plus the capabilities, so that 5c's picker has something true to render and most modes no longer need a warning at all.
3. The parity harness's PAFSynth stage is vacuous. tests/cpp/parity_check.cpp:175-190 runs PAFSynth for 128 frames with silent input and no note_on, then averages — both sides push exactly 0.0, 0.0. Stage 3 compares zero to zero. (Stage 4, ChannelStrip, at least feeds a 0.25 DC step.) This is on top of the known limits the brief states. A parity PASS is not evidence for anything in this document.
4. §7.2's DriverConfig work changed the firmware, not the browser. Mode::driver_config() is now part of the nisps::Mode concept (nisps/core/concepts.hpp:74-80), defaults to engine().driver_config() in ModeBase (nisps/modes/base.hpp:145-165), and firmware brings the codec up from it (firmware/MEMLNaut-NISPS/glue/audio_driver.hpp). Mic vs line is real on hardware. Nothing in manifold/ or nisps/wasm/bindings.cpp reads DriverConfig — the WASM bridge never calls it. So yes, the browser side is the remaining gap for routing, but see the next point, which is why 5b cannot simply reuse DriverConfig.
5. DriverConfig is not a topology declaration and must not be pressed into service as one. It is a codec-negotiation record: mic_input, mic_gain_db, line_level, output_volume, sample_rate (nisps/core/types.hpp:50-71, struct at :65). It correlates with topology by accident — the three input-processing engines all set line_level = 6u — but paf_synth also deviates (output_volume = 0.9f) while consuming no input, breakor/elysiamorf return a default {} identical to a mode that expresses no opinion, and analysis's mic_input = true is about which codec pin, not about whether audio input is required. Inferring topology from line_level != 3 would be a guess dressed as a fact. Topology needs its own declaration.

---

§2 The model

§2.1 Why not the flat four-class enum

The plan proposes generator | audio-in-fx | event-only | analysis. That enum cannot express paf_synth, which is a generator that produces nothing without note events — the single biggest user-visible gap in the catalogue. Three independent facts are being conflated:

axis	question	values
input	does the engine need an audio input signal to do its job?	none | required
output	what does the engine emit?	audio | events | none
trigger	does it need note events to sound?	free | notes

The four familiar class names survive as a derived label, not stored data:

output === 'events'                    → "Event sequencer"
output === 'none' && input==='required'→ "Analysis"
input  === 'required'                  → "Audio FX"
otherwise                              → "Generator"

§2.2 The declared values

mode	input	output	trigger	derived label
paf_synth	none	audio	notes	Generator
channel_strip	required	audio	free	Audio FX
verb_fx	required	audio	free	Audio FX
xiasri	required	audio	free	Audio FX
memlcelium	none	audio	free	Generator
slp_workshop	none	audio	free	Generator
breakor	none	events	free	Event sequencer
elysiamorf	none	events	free	Event sequencer
sound_analysis_midi	required	none	free	Analysis

§2.3 Host capability, and a derived verdict — not a hard-coded badge

The catalogue must never carry a hand-maintained "works in browser" flag: it would be wrong the day a capability lands. Instead, the browser declares what it can currently provide, and support is computed:

interface HostAudioCapabilities {
  audioInput: boolean;        // a MediaStream is connected to the worklet node
  noteTrigger: boolean;       // nisps_engine_note_on/off exist and are wired
  eventDrain: boolean;        // worklet → host event channel exists
  analysisFeatures: boolean;  // analysis feature readback exists
}

type ModeSupport =
  | { ok: true }
  | { ok: false; reason: 'needs-audio-input' | 'needs-note-source' | 'hardware-only'; detail: string };

modeSupport(schema.audio, host) is a pure function; the UI renders its result. As each capability in §5 lands, its flag flips to true and modes stop being labelled — no catalogue edit, no badge list to maintain. Today the flags are { audioInput: <runtime>, noteTrigger: false, eventDrain: false, analysisFeatures: false }.

---

§3 Where the truth lives

In schemas/modes/<mode>.json, as a new required audio object; codegen emits C++ and TS.

Rejected alternatives, with reasons:

• A hand-written topology map in manifold/src/console/model.ts (the audit's suggested fix) — this is a seventh hand-maintained mode registry, straight against Phase 3, which just finished deleting six of them (simplification-plan.md §4). It also puts a fact about C++ engines in TypeScript, where no C++ test can check it.
• A WASM export nisps_engine_topology(id) — MF_MODES is built at module load (model.ts:267-316); making it await WASM would make the whole catalogue async for a static fact.
• Deriving it from DriverConfig — see §1.5.

§3.1 Schema shape

Added to schemas/schema.json (required gains "audio", additionalProperties: false preserved):

"audio": {
  "type": "object",
  "required": ["input", "output", "trigger"],
  "additionalProperties": false,
  "properties": {
    "input":   { "enum": ["none", "required"] },
    "output":  { "enum": ["audio", "events", "none"] },
    "trigger": { "enum": ["free", "notes"] },
    "dsp_engine_id": {
      "type": "string", "pattern": "^[a-z][a-z0-9_]*$",
      "description": "The engine that occupies the audio path for this mode. Defaults to the mode's engine_id; declared only when the mode's ModeBase engine slot is a NoOp and a separately-composed engine owns the audio (sound_analysis_midi → analysis)."
    }
  }
}

dsp_engine_id is optional and is set on exactly one mode, sound_analysis_midi: "analysis". It exists to delete a hard-coded exception — see §6.

§3.2 Codegen anchors

codegen/generate.ts, mirroring what ui already does — each of these is one line-group:

what	anchor
input TS type for a schema file	interface ModeSchema at :93-126 (its ui block is :116-120)
C++ enums + struct AudioConfig in schema_types.hpp	beside enum class PrimaryInput :264-272 / struct UIConfig :273-277
AudioConfig audio; member on ParamSchema	struct ParamSchema at :288-300
per-mode inline constexpr AudioConfig k<Mode>Audio	beside the // UI block, :503-518
TS AudioConfig interface + ModeSchema.audio	export interface UIConfig at :374-378
TS per-mode emission	beside :631-635

Regenerate with cd codegen && bun run generate.ts; the golden snapshot codegen/tests/golden/paf_synth_schema.{hpp,ts} must be updated in the same change, and CI's codegen dirty-diff gate (added in plan §1.3) will fail on anything stale.

---

§4 Invariants

Beyond the repo-wide constraints (platform-neutral allocation-free nisps/, 1e-5 parity, both codegen outputs in one change, RT-safe worklet/dual-core comms), this area has its own:

1. Declared topology is verified by behaviour, never by comment. Every value in §2.2 is asserted by a test that drives the engine (§5 step 2). Adding an engine or a mode without a topology declaration must fail to build; declaring one falsely must fail a test.
2. The support verdict is derived, never stored. No "browser-ok" boolean in a schema, a catalogue, or an overlay. See §2.3.
3. nisps/ gains no browser-only concept. audio is a schema/codegen fact consumed by the generated ParamSchema and by tests. Firmware behaviour must not change: no engine or mode source file changes in step 1, and nisps_modes_tests / nisps_dsp_engine_tests must stay green with no edits to existing cases.
4. Microphone input is opt-in, per session, and never auto-enabled. Mic → worklet → destination is an acoustic feedback loop through the room. Enabling requires an explicit user gesture and a headphones warning; the mic is disconnected on EngineHost.stop() and on mode switch away from an input: 'required' mode.
5. No new audio-thread allocation. Anything crossing worklet↔main (events, analysis features) uses a pre-allocated channel. postMessage of a freshly-allocated typed array per render quantum is not acceptable; COOP/COEP are already set for manifold (see vite.config.ts / ONBOARDING.md §2), so SharedArrayBuffer is available and is the intended mechanism.
6. The exclusive InputMode picker stays exclusive and stays ML-only. internal | gamepad | midi (manifold/src/console/Drawers.tsx:284-288) selects the ML input source. Microphone audio is not an ML input source (except transitively for sound_analysis_midi, whose features would enter through the engine, not through input-layer.ts). Do not add a fourth entry.
7. Silence must be explained, not shipped. If a mode is selectable and cannot sound, the UI says which capability is missing. "It just doesn't make a noise" is the bug this document exists to remove.

---

§5 Implementation sequence

Each step is independently landable and independently verifiable. Steps 1–3 are the honest minimum; 4–6 are scoped by the decisions in §8.

Step 1 — declare topology (schema + codegen, both languages)

Edit schemas/schema.json (§3.1) and all nine schemas/modes/*.json with the §2.2 values, plus dsp_engine_id: "analysis" on sound_analysis_midi. Extend codegen/generate.ts at the §3.2 anchors. Regenerate; commit nisps/modes/generated/, manifold/src/modes/generated/, and the codegen golden.

No behaviour changes. Note honestly: ui.primary_input / show_voice_space_selector / show_synth_visualizer are generated into both languages and read by nothing outside codegen and its golden (verified by grep across manifold/src, nisps/, firmware/). audio must not repeat that — it acquires two consumers in steps 2 and 3 of this same plan.

Verification: bash scripts/build-cpp-tests.sh (generated headers still compile into nisps_modes_tests); cd codegen && bun run test (golden + curve-drift); cd manifold && bun run typecheck; bun run codegen/generate.ts twice → no diff (idempotence).

Step 2 — make the declaration honest (two behavioural tests)

2a. tests/cpp/test_mode_audio_topology.cpp, added to the nisps_modes_tests target (nisps/CMakeLists.txt:119-144 — that target already has the repo root on its include path and already links the generated schemas). For every generated mode schema, resolve audio.dsp_engine_id ?? engine_id to its C++ engine type and assert:

declared	assertion
input: 'none'	output is identical driven silent vs driven with a noise bed (the engine ignores its input). For output: 'none' engines, compare features() instead of audio.
input: 'required'	output RMS with the noise bed exceeds output RMS with silence by > 1e-2.
output: 'audio'	with the mode's sounding precondition satisfied (a note_on when trigger === 'notes', a noise bed when input === 'required'), RMS > 1e-3.
output: 'events'	RMS is exactly 0 under both drives and pop_events() yields > 0 events within 2 s at the default tempo.
output: 'none'	RMS is exactly 0 under both drives.
trigger: 'notes'	RMS is exactly 0 before note_on, and > 1e-3 within 1 s after note_on(60, 100).
trigger: 'free'	covered by the output: 'audio' row.

Drive params pseudo-randomly in [0.05, 0.95] from a fixed-seed nisps::Rng, not all-0.5 — that vector is a degenerate corner and is precisely why parity_check.cpp stage 3 tests nothing (simplification-plan.md §6.5f(3) made the same call for the bench).

The engine_id → C++ type resolution is a switch local to the test. Guard it: assert the set of resolved ids equals the set of ids across all generated schemas, so a new engine cannot be added without the test noticing.

2b. manifold/tests/engine-topology.test.ts (bun test, picked up by the existing bun test src tests/*.test.ts glob — do not change that script). The §0 WASM probe, promoted: drive the committed manifold/public/nisps.{js,wasm} through nisps_engine_* and assert the same table at the browser's own ABI. This is the layer parity-check does not cover and the layer the deploy actually ships.

Verification: bash scripts/build-cpp-tests.sh (5 ctest targets green); cd manifold && bun run test. Both are hardware-free and run in CI. If a §2.2 value is wrong, this is where it surfaces.

Step 3 — surface the truth in Manifold

• manifold/src/console/model.ts: MFMode gains audio: AudioConfig (derived in modeFromSchema, :246-259 — one line, straight off the schema).
• New manifold/src/console/mode-support.ts: HostAudioCapabilities, modeSupport(), and modeClassLabel() (§2.1/§2.3). Pure, unit-testable, no React.
• ConsoleApp builds the capability record from what the engine actually exposes (today: audioInput from engine.audio.hasAudioInput, the other three literal false constants that get deleted as steps 4–6 land) and puts it on ConsoleCtx.
• Render: a support chip in the synth ModeConfig block (manifold/src/console/Drawers.tsx:549-570, the "Transport" section — it already names the active mode), stating why the active mode cannot sound. When 5c builds the picker it reads the same modeSupport() for its per-entry badge and for disabling hardware-only entries.

Verification: unit test for modeSupport() over all nine modes × the current capability record (bun test); bun run typecheck; e2e — extend manifold/tests/e2e/schema-modes.spec.ts, which already switches modes through window.__mf, to assert the chip's text for one mode per class.

Step 4 — wire microphone input (makes the Audio FX class real)

This is the cheapest real capability in the document: the worklet already consumes inputs[0] (§0), so no nisps/ change, no new WASM export, no worklet change.

• EngineHost: setAudioInput(stream: MediaStream | null) — hold a MediaStreamAudioSourceNode, connect(this.node) / disconnect(); handle "called before start()" by stashing the stream and connecting once the node exists; drop it in stop().
• EngineApi.audio gains setAudioInput() + hasAudioInput (manifold/src/engine/engine-api.ts:95-102, 203-207).
• UI in the synth Transport block beside the play button, rendered only when the active mode declares input: 'required': an "Audio input" toggle that calls navigator.mediaDevices.getUserMedia({ audio: { echoCancellation: false, noiseSuppression: false, autoGainControl: false } }) — the three defaults must be off or the codec fights the DSP — with a headphones warning (invariant 4) and a clear denied/unavailable state. Requires a secure context: production is HTTPS, dev is http://localhost:5273, both fine.
• Device picker: out of scope, default device only. Note it.

Verification, honestly graded:

• Strong: step 2b already proves these three engines transform a driven input correctly at the committed-WASM layer.
• Medium: an e2e with --use-fake-device-for-media-stream --use-fake-ui-for-media-stream and context.grantPermissions(['microphone']) can assert engine.audio.hasAudioInput === true and that the mode chip clears. That proves wiring, not audibility.
• Weak / not automatable here: that sound actually comes out of the speakers with a real mic. The worklet's output is not observable from the page. This needs an operator listening check, once, per engine. Say so in the commit rather than implying the gates cover it.

Step 5 — paf_synth note triggering (gated on decision §8.1)

Two exports, nisps_engine_note_on(void*, int note, int vel) and nisps_engine_note_off(void*, int note), dispatched with if constexpr (requires { e->note_on(n, v); }) so only engines that have them respond (today: paf_synth alone). The chain is worklet-side, which differs from the main-thread five-layer chain — the main thread never creates engines:

1. EMSCRIPTEN_KEEPALIVE in nisps/wasm/bindings.cpp (beside :1089-1108)
2. EXPORTED_FUNCTIONS in scripts/build-wasm.sh:70-71
3. WasmInstance.exports interface + a pickFn(...) in init_ and the re-export in the this.instance = { exports: { … } } shim (nisps-processor.ts:29-42, :145-165, :176-188)
4. HostToWorkletMessage union + onMessage_ branch (engine-host.ts:35-53, nisps-processor.ts:72-90)
5. EngineHost.noteOn/noteOff → EngineAudioApi (engine-api.ts:95-102, :203)

Miss a layer and it fails at runtime, not compile time. manifold/src/engine/types.ts:159-167 also declares the engine ABI for the main-thread module; it is unused by wasm-iml.ts — decide whether to keep it symmetric or leave it alone, but do not assume it is load-bearing.

RT safety: notes arrive on the worklet's existing port, handled between render quanta exactly as params already are — bounded, no allocation inside process().

Trigger sources: manifold/src/inputs/midi-input-source.ts:204-211 already emits note:<n> press/release actions with velocity from WebMIDI; ConsoleApp binds actions to verdicts today, so routing note actions to engine.audio.noteOn/Off is a small addition there. Add one on-screen momentary "Note" button in the Transport block as the no-hardware fallback.

Note for context: on firmware, paf_synth is also note-driven — glue/midi_io.hpp:41-50 routes MIDI note-in to mode.note_on. The browser gap is not a divergence from hardware behaviour, it is the absence of the same route.

Verification: extend tests/cpp/test_mode_audio_topology.cpp's trigger: 'notes' row (already specified in step 2a — it will already be green before this step, since it tests the C++ engine, not the browser); add a manifold/tests/engine-topology.test.ts case asserting the exported note functions exist and produce non-zero output through the committed WASM; e2e asserting the chip clears after a synthetic note. Audibility again needs an ear.

Step 6 — event-only and analysis modes (gated on decisions §8.2 / §8.3)

Default position: label them hardware-only and stop. That is honest, costs nothing, and the label disappears by itself when a capability lands (§2.3).

If instead they are to be made real:

• Event-only (breakor, elysiamorf) needs (a) nisps_engine_pop_events, nisps_engine_set_playing, nisps_engine_update_bpm across the step-5 chain; (b) a worklet→main event channel — a SharedArrayBuffer ring written by the worklet and drained on the main thread's rAF (invariant 5; COOP/COEP are already set); (c) transport UI (play/stop/bpm) and a route from events to midi-backend.ts that bypasses the per-param output path entirely, because these modes emit notes, not parameter values. This overlaps 5a: on firmware the mode layer owns the event drain (nisps/modes/breakor.hpp:42-46, glue/midi_io.hpp:53-63), so building a second, browser-only orchestration here is exactly the duplication 5a exists to remove. Sequence it after 5a.
• Analysis (sound_analysis_midi) needs step 4 plus nisps_engine_copy_features plus a worklet→main path for six floats per control tick (same SAB channel) plus routing those into ML input slots 0–5 alongside joy_* in slots 6–9 — which is input-layer.ts's composition contract and touches the exclusive-source picker (invariant 6, and the dormant multi-source decision, §7.7 of the plan). Not a small item; do not smuggle it into 5b.

---

§6 Proposed deletion

One, with its consumer named:

modeEngineId()'s hard-coded exception — manifold/src/console/model.ts:392-395:

export function modeEngineId(modeId: string): string {
  if (modeId === 'sound_analysis_midi') return 'analysis';
  return MF_MODES.find((m) => m.id === modeId)?.engineId ?? 'thru';
}

Consumer: ConsoleApp.tsx:242 (engine.audio.setBackend(...)). Replaced by schema.audio.dsp_engine_id ?? schema.engine_id (§3.1). This is the same class of hand-exception Phase 3 spent two days removing, and it is the only place in the app where a mode's audio engine is decided by an if.

Nothing else in this document deletes anything. In particular, do not delete nisps/engines/ sequencer or analysis code because the browser cannot use it — firmware runs all of it.

---

§7 Adjacent, verified, deliberately out of scope

Two findings from the same files. Recording them so the implementer does not rediscover them mid-change; neither is part of 5b.

1. SCHEMA_MODE_OVERLAYS.input duplicates ui.primary_input and has already drifted. model.ts:229-244 hand-declares breakor: { input: 'joystick' } while schemas/modes/breakor.json declares "primary_input": "xy_pad". The overlay value is live — ConsoleApp.tsx:814 feeds it to resolveInputMap() (settings/settings-store.ts:146-153) to pick the input-map shape — so the two sources disagree about a rendered behaviour. Fixing it means deriving MFMode.input from the schema and deleting the overlay field.
2. ui is generated into both languages and consumed by nothing. primary_input, show_voice_space_selector, show_synth_visualizer have zero readers outside codegen/ and its golden. Either wire them (item 1 above wires primary_input) or delete them. Doing this in the same commit as step 1 is cheaper than separately — same files, same regeneration — but it is a different decision and should be asked for explicitly.

---

§8 Operator decisions

These genuinely need a call; everything else in this document I decided and justified above.

1. paf_synth note triggering (step 5): build it, or label the flagship mode "needs a note source"? This is the most user-visible silence in the catalogue and the most likely to be read as "the app is broken". Building it is two exports plus a UI button, and the MIDI note plumbing already exists. Labelling it is free but leaves the best-developed engine unusable in the browser. Recommendation: build it. Counter-argument worth weighing: note routing is arguably 5a's territory (firmware does it in ModeBase/midi_io.hpp), so building it here creates a small browser-only path that 5a will later absorb.
2. Event-only modes (breakor, elysiamorf): label hardware-only, or build the event channel? Recommendation: label now, build after 5a — the browser-side orchestration is precisely what 5a is meant to stop hand-writing.
3. sound_analysis_midi: label hardware-only, or build the analysis path? It needs mic + feature readback + ML-input composition, and it collides with the dormant multi-source input decision (plan §7.7). Recommendation: label now.
4. audio.dsp_engine_id — adopt the field (and delete the modeEngineId exception), or keep the exception and give the test a local special case? Adopting it is the single-source answer and is what §3.1/§6 assume; the cost is one more optional schema field used by exactly one mode.
5. Bundle the §7 ui clean-up into step 1? Same files and same regeneration, so bundling is cheaper — but it widens a change that is otherwise purely additive.
6. How much microphone UX? Step 4 ships default-device-only with no picker and no input meter. A device picker and a level meter are obvious follow-ons; say now whether they are wanted, since a meter needs a tap on the input node that the current host does not have.

---

§9 What this plan does not do

• It does not build the instrument-mode picker. That is §6.5c (plans/curated-presets-spec.md); this plan gives it truthful data, and 5c should not ship a picker without it.
• It does not touch nisps/modes/ orchestration. That is §6.5a (plans/mode-layer-reunification.md), which is also where the browser event pump belongs — see §5 step 6 and decision §8.2.
• It does not change firmware behaviour in any step. Every mode remains fully functional on hardware.
• It does not improve the parity harness, despite §1.3. Fixing stage 3 to trigger a note before averaging is a one-line change with a golden-baseline consequence; it belongs with whoever next touches tests/cpp/parity_check.cpp, and would bump kVersion (:93).