Cockpit: explicit generation mode and corpus import from tab folders

[PhysShell]

User goal

Make corpus-backed generation available from the cockpit as explicitly and conveniently as it is from the CLI.

Today the Generate panel only reports the effective mode:

• seed-only when no CorpusMaterial is attached;
• corpus rhythms + novelty + gesture when material was supplied at process startup with --corpus DIR.

The user cannot explicitly choose the generation mode in the panel, and the web cockpit cannot build generation-ready corpus material from a folder of MIDI / Guitar Pro tabs.

This issue is an umbrella. It must be delivered as separate PR scopes rather than one UI/filesystem/generation blob.

---

PR A — explicit generation mode selector

Goal

Expose the existing generation input choice in the Generate panel without changing the generator itself.

Suggested UI:

Generation mode:
○ Seed only
● Corpus

In scope

• Add a typed generation mode to cockpit state, for example SeedOnly | Corpus.
• Seed only calls the shared generation path with no corpus material.
• Corpus calls the same shared generation path with the currently attached CorpusMaterial.
• Disable or refuse Corpus with an explicit reason when no generation-ready corpus is attached.
• When native cockpit starts with --corpus DIR, select Corpus by default.
• Browser sessions with no generation-ready material remain in Seed only.
• Preserve the existing seed-tab selector independently from generation mode.
• Capture the actual selected input in immutable run provenance.
• Changing the live selector must not rewrite or reinterpret existing candidates, history entries, global chains, or kept sidecars.

Out of scope

• No generator, scoring, reranking, DP-chain, rhythm-precedence, or corpus schema changes.
• No automatic corpus construction.
• No second generation implementation inside the cockpit.
• No changes to existing fixed-seed output for either effective mode.

Tests

Red → green commit history is required.

Cover at least:

• a fresh panel has the defined default mode;
• Seed only passes None even when corpus material is attached;
• Corpus passes the attached material;
• Corpus is unavailable or typed-refused when material is absent;
• startup with --corpus DIR selects Corpus;
• fixed seed preserves existing output in both modes;
• old run provenance remains immutable after changing the selector;
• native and wasm builds remain green.

Acceptance criteria

• The user can explicitly select Seed only or Corpus in the Generate panel.
• The panel states why corpus mode is unavailable instead of silently falling back.
• Rank 1 remains the same candidate the corresponding CLI invocation would produce.
• Actual corpus contribution, not merely attachment, remains what provenance records.
• cargo test --workspace passes.
• cargo clippy --all-targets -- -D warnings passes.
• cargo fmt --all -- --check passes.

---

PR B1 — native cockpit: build and attach a corpus from a tab folder

Goal

Let the native cockpit select a directory containing .mid, .gp3, .gp4, .gp5, and .gpx files, run the existing shared ingest/corpus-building path, and attach the resulting material without restarting with CLI flags.

In scope

• Native directory picker.
• Recursive or explicitly documented non-recursive discovery, matching one defined contract.
• Import every supported tab through the shared importer.
• Reuse the existing CLI/core ingest and corpus-building semantics. Do not reimplement musical extraction in egui code.
• Collect source bytes and generated records in the same layout expected by corpus loading.
• Build CorpusMaterial and source-tab pick-list.
• Attach the result to the running cockpit and make Corpus mode available.
• Show progress or a bounded busy state for large folders.
• Report imported, skipped, and failed files with actionable diagnostics.
• Require explicit/default metadata policy for rights status, acquisition, cohort, and redistributability. Safe defaults must remain safe.
• Private tabs and corpus data must remain local and must not be added to the repository.

Out of scope

• Web File System Access / OPFS import.
• Background watcher or automatic folder rescan.
• Silent overwrite of an existing corpus.
• New corpus schema or generator behavior.
• Automatic approval of generated corpus records unless that is already the exact CLI contract.

Tests

• deterministic file discovery order;
• supported and unsupported extension handling;
• partial failure keeps successful imports and reports every skip/failure;
• generated native corpus reloads through the existing load_corpus_dir path;
• attached material has the expected template/reference/gesture counts;
• fixed-seed generation matches CLI generation over the same built corpus;
• no corpus or source bytes are written outside the user-selected destination;
• native tests, workspace tests, clippy, and format pass.

Acceptance criteria

• A user can choose a local tab folder, build a corpus, and run corpus-backed generation without restarting the cockpit or typing a CLI command.
• The resulting corpus is reloadable by the existing CLI/native corpus loader.
• Failures are explicit; no file is silently dropped.
• Musical extraction remains in shared core/ingest code, not duplicated in the cockpit.

---

PR B2 — web cockpit: import tab folders into OPFS and restore generation material

Goal

Provide equivalent browser workflow using browser-supported file/directory selection and OPFS persistence.

This is separate from B1 because the current web corpus dock only loads serialized *.chunk.json records. Generation material also requires the source tab bytes referenced by those records.

In scope

• Select a supported directory or multi-file set in the browser.
• Import tabs through the same wasm-compatible shared importer.
• Persist both:
  • corpus records;
  • source tab bytes needed to rebuild generation material.
• Define and document a stable OPFS layout.
• Rebuild CorpusMaterial after import and after page reload.
• Attach it to the running cockpit and enable Corpus generation mode.
• Preserve the existing corpus dock and manifest workflows.
• Show progress and explicit per-file failures.

Out of scope

• Cloud upload or synchronization.
• Server-side corpus storage.
• Browser paths pretending to be native filesystem provenance.
• A second JavaScript implementation of score import or corpus extraction.

Tests

• OPFS layout round-trip;
• source bytes and records survive reload;
• generation material reconstructed after reload is deterministic;
• missing source bytes produce explicit skipped/refusal evidence;
• browser provenance records browser-defined source identity honestly;
• wasm build remains green;
• fixed-seed corpus generation matches the shared generation path.

Acceptance criteria

• The web cockpit can build a generation-ready corpus from selected tabs.
• Reloading the page restores enough data to generate with the corpus without re-importing the folder.
• The dock, manifest, and generation paths consume the same persisted records rather than three subtly different interpretations of them.

---

Delivery order

1. PR A: explicit mode selector.
2. PR B1: native folder import.
3. PR B2: web + OPFS import and restoration.

Each PR gets its own acceptance contract and red → green commit sequence. Do not merge B1/B2 into PR A merely because all three eventually produce a button in the same panel. That would couple UI state, filesystem access, persistence, corpus construction, and generation provenance into one review surface.