command.js: autocomplete by candidate window

Bite-sized tasks for the spec at
docs/superpowers/specs/2026-05-24-fsh-interactive-widgets-design.md.
Verification uses node --check for JS syntax and a final manual smoke
test in the emulator; the TSVM cannot be machine-invoked.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

CLAUDE.md

@@ -165,6 +165,14 @@ Peripheral memories can be accessed using `vm.peek()` and `vm.poke()` functions,
 
 - The 'gzip' namespace in TSVM's JS programs is a misnomer: the actual 'gzip' functions (defined in CompressorDelegate.kt) call Zstd functions.
 
+## Taud Tracker Engine
+
+The Taud playback engine lives in `tsvm_core/src/net/torvald/tsvm/peripheral/AudioAdapter.kt`.
+
+### Critical Implementation Notes
+
+**Re-bind the local `inst` after any mid-tick `triggerNote`.** `applyTrackerTick` binds `var inst = instruments[voice.instrumentId]` once at the top of the per-voice loop. When the note-delay (`S$Dx`) deferred trigger fires mid-tick, `triggerNote` swaps the voice's `instrumentId` — but the rest of that tick (playback-rate recompute at the `computePlaybackRate(inst, finalPitch)` line, `advanceEnvelope`, `advancePfEnvelope`, `advanceAutoVibrato`, and the fadeout / filter-env reads of `inst.*`) keeps using the captured binding. The damage on a **never-triggered voice** (`instrumentId == 0` → stale `inst = instruments[0]`, whose `samplingRate == 0`) is that `playbackRate` is overwritten with `0.0`, freezing the sample at its start for the trigger tick — perceived as "the first delayed note on a fresh channel doesn't fire" (canonical: WHEN.taud cue 0 voice 13 pattern 0x0A row 16, inst `0x11` SD2 on a fresh play). On a warm voice the stale `inst` is a real instrument with non-zero rate, so the note sounds (at the wrong rate for one tick — a sub-perceptual glitch). Re-bind `inst = instruments[voice.instrumentId]` immediately after the note-delay fire block. Any future in-tick trigger paths (currently only S$Dx) must do the same.
+
 ## TVDOS
 
 ### TVDOS Movie Formats
@@ -428,3 +436,112 @@ The different weights for Mid and Side channels reflect the perceptual importanc
 - DC frequency underamplification (using 1.0 instead of 4.0/6.0)
 - Incorrect stereo imaging and extreme side channel distortion
 - Severe frequency response errors that manifest as "clipping-like" distortion
+
+## Virtual Consoles (vtmgr)
+
+Linux-style virtual consoles for TVDOS: up to 6 independent shell sessions,
+switched with **Alt-1..Alt-6** or the **`chvt N`** builtin, **Alt-0** to exit.
+Implemented entirely in JS — **no tsvm_core changes**.
+
+### Architecture
+
+- **Dispatcher**: `assets/disk0/tvdos/sbin/vtmgr.js`. Launched directly by the
+  `TVDOS.SYS` boot block (only when `!_TVDOS_IS_VT_PANE`); when it exits (Alt-0)
+  the boot block runs `AUTOEXEC.BAT` as the bare fallback shell. Owns the
+  physical keyboard and screen. Each VT runs in its own GraalVM context/thread
+  via the existing `parallel.spawnNewContext` / `attachProgram` / `launch` API
+  (see `VMJSR223Delegate.kt` `class Parallel`). VT 1 spawns at boot; VT 2-6 are
+  lazy-spawned on first switch and re-spawned if their shell exits.
+- **Concurrency model**: truly concurrent — switching works mid-command, not
+  just at the prompt. Background panes keep running (no `Thread.suspend`; it is
+  unusable on JDK 21). A cooperative gate inside the shimmed `con.getch` parks
+  panes blocked on input; CPU-bound background panes are allowed to run.
+- **Shared memory**: one `sys.malloc` region holds a control block (active VT,
+  switch request, debounce, spawned-bits) plus, per VT, an input ring buffer and
+  a 7682-byte text-plane buffer mirroring the GPU text-area layout
+  (cursor 2 + fore 2560 + back 2560 + char 2560).
+- **Compositor** (30 Hz): blits the active VT's text plane to the physical GPU
+  text area via `sys.memcpy`, and pushes that VT's cursor-visibility into the GPU
+  blink bit (MMIO attribute byte 6, addressed at `-1 - (131072*gpuSlot + 6)`).
+- **Boot config split (`commandrc` + `AUTOEXEC.BAT`)**: environment setup and
+  app-launch are split into two files so panes can replay one without the other.
+  `\commandrc` holds the `set` commands (PATH/INCLPATH/HELPPATH/KEYBOARD) and is
+  run by the `TVDOS.SYS` boot block in **every** context (boot and pane) — it has
+  no `.BAT` extension, so the boot block runs it line-by-line (`set` mutates the
+  shared `_TVDOS.variables`, so the effect persists). `\AUTOEXEC.BAT` is the
+  **per-console launch** script (Korean IME `tvdos/i18n/korean`, then
+  `command -fancy`); it is run once per console — by each pane's bootstrap, and
+  by the boot block as the post-vtmgr fallback. No env snapshot/replay anymore;
+  each pane gets PATH/KEYBOARD/etc. natively from `commandrc`, and Korean IME
+  (a per-context `unicode.uniprint` handler) now registers in every pane.
+- **Per-pane bootstrap**: each pane re-evals `TVDOS.SYS` (with `_TVDOS_IS_VT_PANE`
+  set — which makes the boot block run `commandrc` but skip the vtmgr/AUTOEXEC
+  launch — and a `_BIOS` stub captured live from the main context) then runs
+  `command -c \AUTOEXEC.BAT`, all in ONE direct `eval` so the launcher shares
+  scope with `_TVDOS`/`files`/`execApp`.
+
+### Output/input shimming (in the pane bootstrap)
+
+`con` and the global `print`/`println` family are plain JS, so the bootstrap
+overrides them to read/write the per-VT shared-memory buffers instead of the
+physical GPU. **`sys` and `graphics` are host objects and CANNOT be overridden
+from JS** — this is the key constraint that shapes everything below.
+
+- The shimmed `print` is a faithful JS port of the GPU's TTY interpreter
+  (`GlassTty.acceptChar` + `GraphicsAdapter` handlers): control bytes, the
+  `\x84<decimal>u` "emit char by code" escape (used by `con.prnch`), CSI cursor
+  moves / erase / SGR colours, and the `?25` cursor-visibility private sequence.
+  A swallow-only parser is NOT enough — TVDOS apps drive the screen through
+  these `print` escapes.
+- `con.move`/`con.getyx` are **1-based** (mirroring `graphics.setCursorYX`'s
+  `cx-1` and `getCursorYX`'s `cx+1`); `con.addch` does NOT advance the cursor
+  (matches `graphics.putSymbol`), while `con.prnch` DOES.
+- `command.js`'s `shell.execute` reassigns the global print family to
+  `shell.stdio.out.*`, which call `sys.print` (→ physical GPU). `shell.stdio.out`
+  was made to delegate to a `globalThis.__VT_OUT` hook when present (set by the
+  bootstrap); outside a VT the hook is absent and the path is byte-identical.
+
+### Direct-VRAM apps need a VT-aware base (the `vaddr` pattern)
+
+Apps that write the text area directly via `graphics.getGpuMemBase()` (rather
+than `con.*`/`print`) bypass the shims and paint the physical screen, invading
+whatever VT is visible. They must resolve text-area byte `m` through a
+VT-aware base:
+
+```js
+// physical: backward  (byte m at gpuBase - m)   — getDev inverts to forward-native
+// VT pane:  forward   (byte m at VT_TEXT_PLANE + m, the pane buffer the compositor blits)
+const VT = (typeof globalThis.VT_TEXT_PLANE !== 'undefined')
+const VRAM_BASE = VT ? globalThis.VT_TEXT_PLANE : (graphics.getGpuMemBase() - 253950)
+const VRAM_SGN  = VT ? 1 : -1
+function vaddr(m) { return VRAM_BASE + VRAM_SGN * m }
+```
+
+`sys.memcpy`/`sys.pokeBytes` copy forward in the resolved native memory, so this
+works for both directions. The physical branch is identical to the original
+arithmetic (no regression outside vtmgr). Applied so far in
+`assets/disk0/tvdos/bin/taut.js` and `assets/disk0/hopper/include/aa.mjs`
+(used by `bb.js`). Any future direct-VRAM app needs the same one-line `vaddr`.
+
+### Files
+
+- New: `assets/disk0/tvdos/sbin/vtmgr.js` (dispatcher + per-pane bootstrap)
+- `assets/disk0/tvdos/bin/command.js`: `chvt` builtin, `[N]` prompt prefix for
+  VT 2-6, `shell.stdio.out` → `__VT_OUT` delegation
+- `assets/disk0/tvdos/TVDOS.SYS`: boot block runs `\commandrc` (env) in every
+  context, then — only when `!_TVDOS_IS_VT_PANE` — launches `tvdos/sbin/vtmgr`
+  and, on its exit, `\AUTOEXEC.BAT` as the fallback shell
+- `assets/disk0/commandrc`: env-only `set` commands (PATH/INCLPATH/HELPPATH/KEYBOARD)
+- `assets/disk0/AUTOEXEC.BAT`: per-console launch (Korean IME + `command -fancy`)
+- `assets/disk0/tvdos/bin/taut.js`, `assets/disk0/hopper/include/aa.mjs`:
+  `vaddr` VT-aware direct-VRAM addressing
+
+### Gotcha: injectIntChk vs. embedded source
+
+`execApp`/`require` run a program's source through `injectIntChk` (TVDOS.SYS),
+which sed-rewrites the **first** `while`/`for`/`do` of each kind to call a
+per-exec `tvdosSIGTERM_<hash>()` SIGTERM check. When vtmgr embeds the pane
+bootstrap as a string literal, one of those rewrites can land inside the literal
+— and the pane context has no such symbol. vtmgr strips them from the bootstrap
+string with `raw.replace(/tvdosSIGTERM_[A-Za-z0-9_]+\(\);?/g, '')`. Any future
+code that builds executable source as a string literal must do the same.

TAUD_NOTE_EFFECTS.md

@@ -1,10 +1,22 @@
 # Taud Tracker Effect Command Reference
 
-Taud is a tracker-style music format derived from ScreamTracker 3's pattern command set, extended to 16-bit effect arguments and a 4096-tone equal-temperament pitch grid. This document defines every effect command a Taud engine must implement. Each command entry has three parts: a plain explanation for composers, compatibility notes for converting patterns from ScreamTracker 3 (ST3), ImpulseTracker (IT), FastTracker 2 (FT2) or ProTracker (PT), and implementation details for engine writers.
+Taud is a tracker-style music format derived from ScreamTracker 3's pattern command set, extended to 16-bit effect arguments and a 4096-tone equal-temperament pitch grid. This document defines every effect command a Taud engine **MUST** implement. Each command entry has three parts: a plain explanation for composers, compatibility notes for converting patterns from ScreamTracker 3 (ST3), ImpulseTracker (IT), FastTracker 2 (FT2) or ProTracker (PT), and implementation details for engine writers.
+
+## Conformance language
+
+The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **NOT RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) and [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174) when, and only when, they appear in all capitals and bold. Lowercase uses of these words carry their ordinary English meaning and impose no normative requirement.
+
+In short:
+
+- **MUST** / **MUST NOT** / **REQUIRED** / **SHALL** / **SHALL NOT** — absolute requirements / prohibitions. A conforming implementation **SHALL** observe every such rule; an implementation that violates one is non-conforming.
+- **SHOULD** / **SHOULD NOT** / **RECOMMENDED** / **NOT RECOMMENDED** — strong guidance. An implementation **MAY** deviate in particular circumstances, but the full implications **MUST** be understood and weighed before doing so.
+- **MAY** / **OPTIONAL** — truly optional. Implementations that include the feature and implementations that omit it are equally conforming, and each **MUST** be prepared to interoperate with the other (with reduced functionality where the optional feature is the means of interoperation).
+
+The "Plain" paragraph of each effect description is non-normative tutorial text; the **Compatibility** and **Implementation** paragraphs carry the normative requirements, expressed through the keywords above.
 
 ---
 
-## 0. Tracker Terminologies
+## 0. Tracker terminologies
 
 This manual extensively uses "tracker lingo" that may not sound intuitive to the modern DAW users. This section covers some of the tracker lingo to get the concepts better understood for those who have never used trackers.
 
@@ -16,7 +28,7 @@ This manual extensively uses "tracker lingo" that may not sound intuitive to the
 
 * **Row.** One horizontal slot within a pattern, at most one note event per channel. A row's duration is `speed × tick_duration` — see Speed and Tempo below.
 
-* **Ticks.** A row spans several ticks dictated by a "tick rate". All note effects happen on those ticks while playing. Some effects (notably sliding effects, excluding fine slides) require more than one ticks for operation, and **they will not get applied when tick rate is set to 1.**
+* **Ticks.** A row spans several ticks dictated by a "tick rate". All note effects happen on those ticks while playing. Some effects (notably sliding effects, excluding fine slides) require more than one tick for operation, and **MUST NOT** be applied when the tick rate is set to 1.
 
 * **Speed vs. Tempo.** Two independent timing knobs. **Speed** (effect A) is the number of ticks per row; **tempo** (effect T) sets the duration of one tick, conventionally expressed as BPM. To slow the song globally without changing how often per-tick effects update, lower the tempo. To give per-tick effects more iterations per row (denser vibrato, longer slides per row), raise the speed. The default is speed 6, tempo $64 → 125 BPM → 50 Hz tick rate → 120 ms per row.
 
@@ -34,7 +46,7 @@ This manual extensively uses "tracker lingo" that may not sound intuitive to the
 
 * **Note off, note cut, note fade.** Three distinct ways a note ends. **Note cut** (`^^^` or S$Cx) silences instantly. **Note off** (`===` or an NNA = NoteOff) releases the sustain loop and lets the volume envelope's release segment play out, then fades. **Note fade** keeps the sustain loop running but begins the fadeout decay — for soft tail-offs that still sound sustained.
 
-* **NNA — New Note Action.** What happens to a still-playing note when a fresh note arrives on the same channel. Options are Cut (drop the old voice), Continue (let it ring through), Note Off (release it), or Note Fade (begin fadeout). The displaced voice becomes a background **ghost** voice — still audible but no longer addressable from the pattern. This is the tracker's substitute for polyphony across DAW MIDI clips.
+* **NNA — New Note Action.** What happens to a still-playing note when a fresh note arrives on the same channel. Options are Cut (drop the old voice), Continue (let it ring through), Note Off (release it), or Note Fade (begin fadeout). The displaced voice becomes a background *ghost* voice — still audible but no longer addressable from the pattern. This is the tracker's substitute for polyphony across DAW MIDI clips.
 
 * **Portamento.** Automatic pitch glide toward a target note (effect G). A row carrying both a note *and* a G does **not** re-trigger the sample; instead the note becomes the target and the already-sounding sample slides into it. Distinct from generic pitch slides (E/F), which move pitch by a fixed amount per tick with no target.
 
@@ -52,15 +64,15 @@ This manual extensively uses "tracker lingo" that may not sound intuitive to the
 
 ## 1. Sound device
 
-- **Bit depth:** 8-bit unsigned throughout, including the final mixdown.
-- **Sample rate:** fixed at 32000 Hz.
-- **Output channels:** strictly stereo; the mix bus always produces a two-channel frame even for mono-source samples.
+- **Bit depth:** 8-bit unsigned throughout, including the final mixdown. Conforming implementations **MUST** deliver 8-bit unsigned samples at the output stage.
+- **Sample rate:** fixed at 32000 Hz. Conforming implementations **MUST** produce output at exactly this rate; resampling to another playback rate is the responsibility of the host environment, not of the Taud engine.
+- **Output channels:** strictly stereo; the mix bus **MUST** always produce a two-channel frame, even for mono-source samples.
 
-Internal accumulators may widen to 16 or 32 bits during mixing and effect computation, but stored samples and final output are 8-bit.
+Internal accumulators **MAY** widen to 16 or 32 bits during mixing and effect computation, but stored samples and final output **MUST** be 8-bit.
 
 ## 2. Pitch system — 4096-TET
 
-One octave spans **4096 pitch units** ($1000 exactly). A 12-TET semitone therefore equals **4096 ÷ 12 ≈ 341.333 units** (≈ $0155.55), which is not an integer; this irrationality is a deliberate consequence of choosing a microtonal native grid. Implementations store channel pitch as a signed integer in Taud units, and convert to playback rate using
+One octave spans **4096 pitch units** ($1000 exactly). A 12-TET semitone therefore equals **4096 ÷ 12 ≈ 341.333 units** (≈ $0155.55), which is not an integer; this irrationality is a deliberate consequence of choosing a microtonal native grid. Implementations **MUST** store channel pitch as a signed integer in Taud units, and **MUST** convert to playback rate using
 
 ```
 playback_rate = reference_rate × 2 ^ (pitch_units / 4096)
@@ -83,13 +95,13 @@ Commonly used intervals in Taud units are listed below; all are rounded to the n
 
 ## 3. Volume system
 
-Per-note and per-channel volume runs from **$00 (silent) to $3F (full)**, a 6-bit range narrower than ST3's 0..$40. Global volume (effect V) runs 0..$FF; this wider range lets the mix bus scale the summed channel output without disturbing individual note volumes. The per-frame mix chain per channel is
+Per-note and per-channel volume runs from **$00 (silent) to $3F (full)**, a 6-bit range narrower than ST3's 0..$40. Global volume (effect V) runs 0..$FF; this wider range lets the mix bus scale the summed channel output without disturbing individual note volumes. Conforming engines **MUST** implement the per-frame mix chain per channel as
 
 ```
 mix = sample × note_vol × channel_vol × global_vol >> normalisation_shift
 ```
 
-with saturation applied before the 8-bit stereo output.
+with saturation applied before the 8-bit stereo output. Internal accumulators **MAY** widen during this computation (see §1), but the saturating clip to the 8-bit range **MUST** be performed at the boundary.
 
 `note_vol` and `channel_vol` are **two independent multiplicative axes** mirroring IT's `chan->volume` and `chan->global_volume`:
 
@@ -127,7 +139,7 @@ Most effects recall their last non-zero argument when re-issued with $0000. Unli
 
 Every other memory-carrying effect (D, I, J, K, L, N, O, P, Q, and others) has a private slot.
 
-**Effects without recall (literal zero).** A few effects do *not* recall on $0000 — the argument is taken at face value. **M** (set channel volume), **V** (set global volume), and the volume- / panning-column SET selectors all behave this way: writing `M $0000` or `V $0000` is a literal "set to silence", not a memory recall. Converters lifting from source trackers that *do* share memory (notably ST3, where the `$00` argument may cohabit with D/E/F/etc.'s shared slot) MUST eagerly resolve the recall to an explicit value before emitting, since the Taud engine takes M / V arguments verbatim.
+**Effects without recall (literal zero).** A few effects do *not* recall on $0000 — the argument **MUST** be taken at face value. **M** (set channel volume), **V** (set global volume), and the volume- / panning-column SET selectors all behave this way: writing `M $0000` or `V $0000` is a literal "set to silence", not a memory recall. Converters lifting from source trackers that *do* share memory (notably ST3, where the `$00` argument may cohabit with D/E/F/etc.'s shared slot) **MUST** eagerly resolve the recall to an explicit value before emitting, since the Taud engine takes M / V arguments verbatim.
 
 ## 7. Opcode and argument format
 
@@ -143,7 +155,7 @@ Opcodes are single base-36 digits (0-9, then A-Z); arguments are 16-bit hexadeci
 
 **Compatibility.** ST3 `Axx` maps one-to-one: Taud `A $xx00`. ST3 `A00` is a no-op; Taud `A $0000` is likewise ignored. ProTracker `Fxx` with `xx < $20` maps to Taud `A $xx00`; `Fxx` with `xx ≥ $20` maps to T instead (see T).
 
-**Implementation.** If the high byte is non-zero, write it to `ticks_per_row`; the low byte is reserved and must be zero. The change takes effect from the row on which the A command appears. There is no memory for A.
+**Implementation.** If the high byte is non-zero, the engine **MUST** write it to `ticks_per_row`; the low byte is reserved and **MUST** be zero. The change takes effect from the row on which the A command appears. There is no memory for A.
 
 ---
 
@@ -151,11 +163,11 @@ Opcodes are single base-36 digits (0-9, then A-Z); arguments are 16-bit hexadeci
 
 **Plain.** Finishes the current row, then continues playback at row 0 of the pattern at cue position $xxyy. Use this to create song-level jumps, loops, or branching structures.
 
-**Compatibility.** ST3 `Bxx` jumps to an 8-bit cue and maps to Taud `B $00xx`. The extended 16-bit range means Taud songs may have up to $10000 cue entries.
+**Compatibility.** ST3 `Bxx` jumps to an 8-bit cue and maps to Taud `B $00xx`. The extended 16-bit range means Taud songs **MAY** have up to $10000 cue entries.
 
-**Implementation.** On the last tick of the current row, set the next cue index to the argument and the next row to 0. If the argument exceeds the song length, wrap to the song's defined restart position (cue $0000 by default). Jumps are detected by a visited `(cue, row)` set so that pathological loops do not prevent song-length computation, though they do not interrupt actual playback. There is no memory for B.
+**Implementation.** On the last tick of the current row, the engine **MUST** set the next cue index to the argument and the next row to 0. If the argument exceeds the song length, the engine **MUST** wrap to the song's defined restart position (cue $0000 by default). Jumps **SHOULD** be detected by a visited `(cue, row)` set so that pathological loops do not prevent song-length computation, though they **MUST NOT** interrupt actual playback. There is no memory for B.
 
-**Simultaneous B and C on the same row.** If a B command appears in the same row as a C command (on any channel), both fire: B chooses the cue, C chooses the row within that cue. If the two commands appear on different channels, channel priority is **ascending channel index** — the lowest-numbered channel carrying either effect wins its parameter. If both appear on the same channel row (only possible if one is a volume-column equivalent), the effect column takes precedence.
+**Simultaneous B and C on the same row.** If a B command appears in the same row as a C command (on any channel), both **MUST** fire: B chooses the cue, C chooses the row within that cue. If the two commands appear on different channels, channel priority is **ascending channel index** — the lowest-numbered channel carrying either effect wins its parameter. If both appear on the same channel row (only possible if one is a volume-column equivalent), the effect column **MUST** take precedence.
 
 ---
 
@@ -163,9 +175,9 @@ Opcodes are single base-36 digits (0-9, then A-Z); arguments are 16-bit hexadeci
 
 **Plain.** Finishes the current row, then skips ahead to row $xxyy of the **next** pattern in the cue sequence.
 
-**Compatibility.** ST3 stores `Cxx` as **BCD** (so on-disk `$10` means decimal row 10); Taud stores the argument as plain binary. When converting from ST3, decode with `row = (byte >> 4) × 10 + (byte & $0F)`. Valid ST3 source bytes are those representing decimal 0..63; out-of-range BCD bytes should clamp to row 0 on import. When exporting back to ST3, encode with `byte = ((row / 10) << 4) | (row % 10)`, clamped at row 63.
+**Compatibility.** ST3 stores `Cxx` as **BCD** (so on-disk `$10` means decimal row 10); Taud stores the argument as plain binary. When converting from ST3, converters **MUST** decode with `row = (byte >> 4) × 10 + (byte & $0F)`. Valid ST3 source bytes are those representing decimal 0..63; out-of-range BCD bytes **SHOULD** clamp to row 0 on import. When exporting back to ST3, converters **MUST** encode with `byte = ((row / 10) << 4) | (row % 10)`, clamped at row 63.
 
-**Implementation.** On the last tick of the current row, advance the cue index by 1 (or honour a co-occurring B), then set the next row to the argument. If the argument exceeds the destination pattern's row count, start the destination pattern at row 0. There is no memory for C.
+**Implementation.** On the last tick of the current row, the engine **MUST** advance the cue index by 1 (or honour a co-occurring B), then set the next row to the argument. If the argument exceeds the destination pattern's row count, the engine **MUST** start the destination pattern at row 0. There is no memory for C.
 
 ---
 
@@ -237,9 +249,9 @@ Coarse and fine modes are distinguished by the high nibble of the argument:
 - **MONOTONE source** (Taud `ff = 2`):
   - MONOTONE `2xx` → Taud `E $00xx` **verbatim** (Hz/tick). The engine converts the stored pitch to frequency, subtracts the argument, and converts back. MONOTONE has no fine-slide form; converters never emit `E $Fxxx` for ff=2 sources.
 
-The mode flag therefore controls **two** decoder behaviours simultaneously: (a) which numeric scale the converter should have used when emitting coarse arguments, and (b) which arithmetic the engine performs on those arguments per tick. Converters MUST set bits 0-1 (`ff`) of the song-table flags byte to match the units they emit, and MUST NOT mix scales within one Taud song.
+The mode flag therefore controls **two** decoder behaviours simultaneously: (a) which numeric scale the converter ought to have used when emitting coarse arguments, and (b) which arithmetic the engine performs on those arguments per tick. Converters **MUST** set bits 0-1 (`ff`) of the song-table flags byte to match the units they emit, and **MUST NOT** mix scales within one Taud song.
 
-Because E and F share memory in Taud (narrower than ST3's broad shared memory), an ST3 song that used `E00` or `F00` to recall a D, G, or Q argument will break on import; the converter must eagerly resolve ST3 recalls into explicit Taud arguments rather than relying on memory.
+Because E and F share memory in Taud (narrower than ST3's broad shared memory), an ST3 song that used `E00` or `F00` to recall a D, G, or Q argument will break on import; the converter **MUST** eagerly resolve ST3 recalls into explicit Taud arguments rather than relying on memory.
 
 **Implementation.** Per-tick processing:
 
@@ -299,10 +311,10 @@ Glissando control (S $1x) snaps the output pitch to the nearest semitone after e
 
 The unit of `$xxxx` depends on the song-table tone mode (effect `1`, bits 0-1):
 
-- `ff = 0` (linear) and `ff = 1` (Amiga): 4096-TET pitch units per tick. Amiga sources should be converted to linear units on G, since the original PT G slide already operated semi-linearly within a small range and the shared-memory pitfall of E/F does not apply here.
+- `ff = 0` (linear) and `ff = 1` (Amiga): 4096-TET pitch units per tick. Amiga sources **SHOULD** be converted to linear units on G, since the original PT G slide already operated semi-linearly within a small range and the shared-memory pitfall of E/F does not apply here.
 - `ff = 2` (linear-frequency): Hz/tick. The engine walks the channel's *frequency* toward the target note's frequency by `±$xxxx` Hz each non-first tick. This is MONOTONE's `3xx` behaviour verbatim (MTSRC/MT_PLAY.PAS:620-630).
 
-**Compatibility.** ST3 `Gxx` uses an 8-bit value in period-table units; convert to Taud using the same `round(× 64/3)` scale as E/F coarse (1/16 semitone per ST3 slide unit). Amiga-mode G sources should be treated as linear. MONOTONE `3xx` → Taud `G $00xx` verbatim under ff=2. G has its **own** memory slot in both ST3 and Taud, so conversion is straightforward and does not suffer the shared-memory problem of E/F.
+**Compatibility.** ST3 `Gxx` uses an 8-bit value in period-table units; converters **MUST** convert to Taud using the same `round(× 64/3)` scale as E/F coarse (1/16 semitone per ST3 slide unit). Amiga-mode G sources **SHOULD** be treated as linear. MONOTONE `3xx` → Taud `G $00xx` verbatim under ff=2. G has its **own** memory slot in both ST3 and Taud, so conversion is straightforward and does not suffer the shared-memory problem of E/F.
 
 **Implementation.**
 
@@ -464,9 +476,9 @@ The `tick_within_row mod 3` counter resets every row start (so every row begins
 
 ## K $xy00 — Dual: vibrato continuation and volume slide $xy
 
-**Plain.** Continues the previously started vibrato (H or U) without retriggering it, while applying a volume slide of `$xy` per non-first tick. Fine volume slides are not available in this form. The K command is implemented sorely for tracker compatibility — new compositions should prefer an explicit `H $0000` (vibrato recall) plus a volume-column slide (`1.$xy` / `2.$xy`), which carries the same semantics with one less hidden dependency.
+**Plain.** Continues the previously started vibrato (H or U) without retriggering it, while applying a volume slide of `$xy` per non-first tick. Fine volume slides are not available in this form. The K command is implemented solely for tracker compatibility — new compositions **SHOULD** prefer an explicit `H $0000` (vibrato recall) plus a volume-column slide (`1.$xy` / `2.$xy`), which carries the same semantics with one less hidden dependency.
 
-**Compatibility.** ST3 / IT `Kxy` map directly to Taud `K $xy00`: the source's `xy` argument byte goes verbatim into the high byte of the Taud argument. ProTracker / FT2 / XM `6xy` map identically. Source-tracker memory cohorts that share K's argument with D (notably the ST3 single-slot shared memory and IT's D/K/L vol-slide cohort) MUST be resolved eagerly by the converter — emit explicit arguments rather than relying on cohort sharing, since Taud's K has its own private slot.
+**Compatibility.** ST3 / IT `Kxy` map directly to Taud `K $xy00`: the source's `xy` argument byte goes verbatim into the high byte of the Taud argument. ProTracker / FT2 / XM `6xy` map identically. Source-tracker memory cohorts that share K's argument with D (notably the ST3 single-slot shared memory and IT's D/K/L vol-slide cohort) **MUST** be resolved eagerly by the converter — converters **MUST** emit explicit arguments rather than relying on cohort sharing, since Taud's K has its own private slot.
 
 **Implementation.** On row parse:
 
@@ -500,9 +512,9 @@ The slide writes the per-note axis (same as D); `channel_vol` is untouched. K ha
 
 ## L $xy00 — Dual: tone portamento continuation and volume slide $xy
 
-**Plain.** Continues the previously started tone portamento (G) without retriggering, while applying a volume slide of `$xy` per non-first tick. Fine volume slides are not available here. Like K, L is implemented sorely for tracker compatibility — new compositions should prefer an explicit `G $0000` plus a volume-column slide.
+**Plain.** Continues the previously started tone portamento (G) without retriggering, while applying a volume slide of `$xy` per non-first tick. Fine volume slides are not available here. Like K, L is implemented solely for tracker compatibility — new compositions **SHOULD** prefer an explicit `G $0000` plus a volume-column slide.
 
-**Compatibility.** ST3 / IT `Lxy` map directly to Taud `L $xy00`. ProTracker / FT2 / XM `5xy` map identically. As with K, source cohort recalls (ST3 shared memory; IT D/K/L vol-slide cohort) MUST be resolved eagerly by the converter; Taud's L has its own private slot.
+**Compatibility.** ST3 / IT `Lxy` map directly to Taud `L $xy00`. ProTracker / FT2 / XM `5xy` map identically. As with K, source cohort recalls (ST3 shared memory; IT D/K/L vol-slide cohort) **MUST** be resolved eagerly by the converter; Taud's L has its own private slot.
 
 **Implementation.** Identical machinery to K with `G` swapped for the LFO update:
 
@@ -535,7 +547,7 @@ The slide writes the per-note axis (same as D); `channel_vol` is untouched. L ha
 
 **Plain.** Sets the per-channel volume axis (`channel_vol`, see §3) to `$xx`, in the same 6-bit `$00..$3F` range as a note's default volume. M is the analog of IT's `Mxx`, which writes `chan->global_volume` — it does **not** disturb the per-note volume (`note_vol`) set by the volume column or seeded from the instrument default. A vol-col SET of $02 on a note row followed by an `M $4000` on the next row therefore plays the channel at `2/63 × $3F/63 ≈ 3%` of full, *not* at full — exactly as IT would.
 
-**Compatibility.** IT `Mxx` maps directly: the source byte is taken **verbatim** with a clamp to `$3F` (IT's $40 cap snaps down by one). ST3 has no native M; OpenMPT/Schism's S3M-with-IT-extensions does, and the same verbatim-with-clamp rule applies on import. M has **no memory** — `M $0000` is a literal "set channel volume to silence", not a recall. Source-tracker shared-memory recalls (e.g., ST3's single-slot shared memory) MUST be eagerly resolved by the converter before emit.
+**Compatibility.** IT `Mxx` maps directly: the source byte **MUST** be taken **verbatim** with a clamp to `$3F` (IT's $40 cap snaps down by one). ST3 has no native M; OpenMPT/Schism's S3M-with-IT-extensions does, and the same verbatim-with-clamp rule applies on import. M has **no memory** — `M $0000` is a literal "set channel volume to silence", not a recall. Source-tracker shared-memory recalls (e.g., ST3's single-slot shared memory) **MUST** be eagerly resolved by the converter before emit.
 
 **Implementation.**
 
@@ -651,9 +663,9 @@ The volume modifier table, **computed with arithmetic (no LUT)**, is:
 | 6 | vol × 2 / 3 | E | vol × 3 / 2 |
 | 7 | vol × 1 / 2 | F | vol × 2 |
 
-Multiplicative cases use integer arithmetic: `vol × 2 / 3` is `(vol × 2) / 3` (truncated); `vol × 3 / 2` is `(vol × 3) / 2`; `vol × 1 / 2` is `vol >> 1`; `vol × 2` is `vol << 1`. All results clip to $00..$3F after.
+Multiplicative cases **MUST** use integer arithmetic: `vol × 2 / 3` is `(vol × 2) / 3` (truncated); `vol × 3 / 2` is `(vol × 3) / 2`; `vol × 1 / 2` is `vol >> 1`; `vol × 2` is `vol << 1`. All results **MUST** clip to $00..$3F after.
 
-A note previously silenced by a cut (`^^^` or `SCx` earlier in the row) is not retriggered, matching ST3's `kST3RetrigAfterNoteCut` rule.
+A note previously silenced by a cut (`^^^` or `SCx` earlier in the row) **MUST NOT** be retriggered, matching ST3's `kST3RetrigAfterNoteCut` rule.
 
 ---
 
@@ -661,7 +673,7 @@ A note previously silenced by a cut (`^^^` or `SCx` earlier in the row) is not r
 
 **Plain.** Modulates volume with an LFO, symmetrically with H's pitch modulation. `$xx` is LFO speed, `$yy` depth; the waveform is selected by S $4x.
 
-**Compatibility.** ST3 `Rxy` uses nibbles; convert by nibble-repeat. ST3's volume cap is $40; Taud's is $3F — very deep tremolo that would have briefly clipped at $40 in ST3 may clip slightly earlier in Taud. R has its own memory slot (not shared with H/U).
+**Compatibility.** ST3 `Rxy` uses nibbles; converters **MUST** convert by nibble-repeat. ST3's volume cap is $40; Taud's is $3F — very deep tremolo that would have briefly clipped at $40 in ST3 **MAY** clip slightly earlier in Taud. R has its own memory slot (not shared with H/U).
 
 **Implementation.** Identical machinery to H with a larger shift to fit the narrower volume range:
 
@@ -691,7 +703,7 @@ Taud splits T by which byte carries the value:
 
 **Plain.** Sets the Taud tempo byte to `$xx`. The resulting BPM is `$xx + $19`: Taud byte $00 → 25 BPM, $64 → 125 BPM (default), $FF → 280 BPM.
 
-**Compatibility.** ST3 `Txx` (where `xx ∈ $20..$FF`) stores BPM directly; convert with `taud_byte = xx − $18`. Taud byte $07 corresponds to ST3's minimum BPM of 32; Taud bytes below $07 are inexpressible in ST3 and should round up to $07 (BPM 32) when exporting. OpenMPT's extended tempo slides (`T $0x` down, `T $1x` up) in S3M files map to Taud T $00xx — see below.
+**Compatibility.** ST3 `Txx` (where `xx ∈ $20..$FF`) stores BPM directly; converters **MUST** convert with `taud_byte = xx − $18`. Taud byte $07 corresponds to ST3's minimum BPM of 32; Taud bytes below $07 are inexpressible in ST3 and **SHOULD** round up to $07 (BPM 32) when exporting. OpenMPT's extended tempo slides (`T $0x` down, `T $1x` up) in S3M files map to Taud T $00xx — see below.
 
 ProTracker `Fxx` with `xx ≥ $20` maps to Taud `T $(xx − $19)00`; `Fxx` with `xx < $20` maps to A (speed) instead.
 
@@ -701,7 +713,7 @@ ProTracker `Fxx` with `xx ≥ $20` maps to Taud `T $(xx − $19)00`; `Fxx` with
 
 **Plain.** Adjusts the tempo continuously during the row. `$00_0y` (low nibble under a zero high nibble within the low byte) slides BPM down by `$y` per non-first tick; `$00_1y` slides up. Out-of-range encodings ($00_20 through $00_FF) are reserved and behave as no-ops.
 
-**Compatibility.** ST3 itself has only the set form; the slide forms originate in the OpenMPT/Schism extension of S3M. On export to strict ST3, slide forms are unrepresentable and should be approximated as an equivalent set-tempo on a later row.
+**Compatibility.** ST3 itself has only the set form; the slide forms originate in the OpenMPT/Schism extension of S3M. On export to strict ST3, slide forms are unrepresentable and **SHOULD** be approximated as an equivalent set-tempo on a later row.
 
 **Implementation.**
 
@@ -731,9 +743,9 @@ A tempo slide's memory slot is separate from the set-tempo path and is private t
 
 **Plain.** Sets the global mix bus volume (0..$FF). $00 is silence; $FF is full. The default is $80.
 
-**Compatibility.** ST3's global volume is 0..$40; convert with `taud_v = st3_v × 4`, clamped at $FF. On export, `st3_v = taud_v >> 2`, clamped at $40. IT's global volume is 0..$80; convert with `taud_v = it_v × 2`, clamped at $FF. On IT, the very first `V 00` command must be resolved as the song's initial global volume.
+**Compatibility.** ST3's global volume is 0..$40; converters **MUST** convert with `taud_v = st3_v × 4`, clamped at $FF. On export, `st3_v = taud_v >> 2`, clamped at $40. IT's global volume is 0..$80; converters **MUST** convert with `taud_v = it_v × 2`, clamped at $FF. On IT, the very first `V 00` command **MUST** be resolved as the song's initial global volume.
 
-**Implementation.** Write the high byte to `global_volume` on the row the command appears. The low byte is reserved. ST3's `kST3NoMutedChannels` rule applies: V on a muted channel is ignored by ST3; for strict-compatible playback Taud follows suit, but new Taud compositions should avoid muting channels that carry global effects.
+**Implementation.** The engine **MUST** write the high byte to `global_volume` on the row the command appears. The low byte is reserved. ST3's `kST3NoMutedChannels` rule applies: V on a muted channel is ignored by ST3; for strict-compatible playback Taud **MUST** follow suit, but new Taud compositions **SHOULD NOT** mute channels that carry global effects.
 
 ---
 
@@ -761,7 +773,7 @@ A tempo slide's memory slot is separate from the set-tempo path and is private t
 
 **Plain.** Modulates panning with an LFO, symmetrically with H's pitch modulation. `$xx` is LFO speed, `$yy` depth; the waveform is selected by S $5x.
 
-**Compatibility.** IT `Yxy` uses nibbles; convert by nibble-repeat. IT's panning cap is $40; Taud's is $3F — very deep vibrato that would have briefly clipped at $40 in IT may clip slightly earlier in Taud. Y has its own memory slot.
+**Compatibility.** IT `Yxy` uses nibbles; converters **MUST** convert by nibble-repeat. IT's panning cap is $40; Taud's is $3F — very deep vibrato that would have briefly clipped at $40 in IT **MAY** clip slightly earlier in Taud. Y has its own memory slot.
 
 **Implementation.** Identical machinery to H with a larger shift to fit the narrower volume range:
 
@@ -792,7 +804,7 @@ Boundary rules:
 - The block stops at the end of the pattern: a ditto whose nominal span would overflow the pattern's row count clips silently at the final row.
 - `$xx = $00`, `$yy = $00`, and any `$xx` greater than the row index on which the ditto sits are all treated as no-ops — there is nothing valid to copy from.
 - A `7` cell appearing inside a source block is **not** recursively expanded: when that source row is pasted into a destination, its effect column is treated as empty. This keeps expansion single-pass and prevents unbounded nesting.
-- Flow-control effects (B, C, S$Bx, S$Ex) that fall inside a source block still fire when their copy lands on a destination row, since the engine sees them as ordinary effect cells after expansion. Composers and converters should avoid placing S$Bx loop bounds wholly inside a ditto'd range — the loop counter is per-voice and the same destination row would be revisited twice with the same state.
+- Flow-control effects (B, C, S$Bx, S$Ex) that fall inside a source block still fire when their copy lands on a destination row, since the engine sees them as ordinary effect cells after expansion. Composers and converters **SHOULD NOT** place S$Bx loop bounds wholly inside a ditto'd range — the loop counter is per-voice and the same destination row would be revisited twice with the same state.
 
 **Compatibility.** Unique to Taud — no ST3/IT/PT equivalent. The effect has no memory.
 
@@ -872,7 +884,7 @@ Effect dispatch sees the synthesised effect, never the literal `7` opcode of the
 - `8 $0000` disables both stages and resets the shared clipping mode to clamp.
 - `8 $x000` updates only the shared clipping mode and leaves the active depth/skip undisturbed — useful for switching between clamp/fold/wrap mid-pattern without retyping the whole argument. The same form on effect 9 has identical semantics.
 
-**Compatibility.** Unique to Taud — no ST3/IT/PT equivalent. The effect has no memory: every cell that names effect 8 must spell out its full argument (apart from the `$x000` shorthand described above). `8 $1100` ⇒ 1-bit, no skip, fold-clipped — a useful sanity check pattern.
+**Compatibility.** Unique to Taud — no ST3/IT/PT equivalent. The effect has no memory: every cell that names effect 8 **MUST** spell out its full argument (apart from the `$x000` shorthand described above). `8 $1100` ⇒ 1-bit, no skip, fold-clipped — a useful sanity check pattern.
 
 **Implementation.** Per-voice state: `bitcrusherDepth` (0..15; 0 = quantiser off), `bitcrusherSkip` (0..255), `bitcrusherCounter` (mod skip+1), `bitcrusherHeld` (last emitted sample), and `clipMode` (0..2, shared with effect 9). On row parse:
 
@@ -931,7 +943,7 @@ The voice-FX state is preserved verbatim by the NNA-ghost copier, so the post-NN
 
 ## 9 $x0zz — Overdrive
 
-**Plain.** Amplifies the voice's post-filter signal and routes it through the shared clipper. With `x = 0` (clamp) the effect is a hard-knee soft-clipping distortion; with `x = 1` (fold) it becomes a wave-folder; with `x = 2` (wrap) it produces aggressive aliased fuzz with sawtooth-style discontinuities at the rails. Volume is *not* re-normalised after clipping — `9 $00FF` clamp-clipped plays at roughly the same loudness as the dry voice once everything saturates. The middle nibble is reserved and must be zero.
+**Plain.** Amplifies the voice's post-filter signal and routes it through the shared clipper. With `x = 0` (clamp) the effect is a hard-knee soft-clipping distortion; with `x = 1` (fold) it becomes a wave-folder; with `x = 2` (wrap) it produces aggressive aliased fuzz with sawtooth-style discontinuities at the rails. Volume **MUST NOT** be re-normalised after clipping — `9 $00FF` clamp-clipped plays at roughly the same loudness as the dry voice once everything saturates. The middle nibble is reserved and **MUST** be zero.
 
 - **x — clipping mode** (shared with effect 8): `0` clamp, `1` fold, `2` wrap (see effect 8 for the precise transfer functions). Values 3..F are reserved and treated as clamp.
 - **zz — amplification index**, range $00..$FF. The applied gain is `(16 + zz) / 16`, so `$00` is 1.0× (effect inactive), `$10` is 2.0× (+6 dBFS), `$F0` is 16.0× (+24 dBFS), and `$FF` is 16.9375× (≈ +24.55 dBFS).
@@ -975,7 +987,7 @@ S is a multiplexing opcode; the **high nibble of the high byte** selects the sub
 
 **Plain.** `$0100` turns filter off; `$0000` turns it on. The parameter of the filter is dependent on the current interpolation mode: follows Amiga 1200 LPF on 1200 mode, Amiga 500 LPF on 500 mode. For other interpolation modes, this command is no-op. (see § Effects that modifies global behaviour)
 
-**Compatibility.** ST3/IT `S00`/`S01` and PT `E00`/`E01` maps directly. To actually hear the effect, the interpolation mode must be set to one of the two Amiga modes.
+**Compatibility.** ST3/IT `S00`/`S01` and PT `E00`/`E01` map directly. To actually hear the effect, the interpolation mode **MUST** be set to one of the two Amiga modes.
 
 **Implementation.** Per-playhead boolean `ledFilterOn` (default off). Writes from row are gated on `interpolationMode ∈ {Amiga 500, Amiga 1200}`; in linear / no-interp / default modes the filter chain is bypassed entirely so the toggle is a silent no-op. The post-mix LPF chain runs on the stereo bus (left/right state per playhead) before dithering: in Amiga 500 mode a 1-pole RC LPF (R = 360 Ω, C = 0.1 µF, fc ≈ 4421 Hz) is always applied; in Amiga 1200 mode that LPF is bypassed (cutoff ~34 kHz, well above 32 kHz Nyquist — matches `pt2_paula.c`). When the LED toggle is on, an additional 2-pole Sallen-Key LPF (R1=R2=10 kΩ, C1=6800 pF, C2=3900 pF, fc ≈ 3091 Hz, Q ≈ 0.660) is run after the mode LPF. Coefficients precomputed once at SAMPLING_RATE; recurrence follows musicdsp.org #38 with `pt2_rcfilters.c` parameter mapping.
 
@@ -983,7 +995,7 @@ S is a multiplexing opcode; the **high nibble of the high byte** selects the sub
 
 ## S $1x00 — PT/ST3/IT Glissando control
 
-**Plain.** `$1000` turns glissando off; `$1100` turns it on. When on, tone portamento (G) output is quantised to the nearest semitone ($0155 approximation) before being sent to the mixer. The internal G pitch counter still advances smoothly; only the audible pitch steps. **This command is implemented sorely for ST3/IT compatibility** and therefore only works in 12-TET context.
+**Plain.** `$1000` turns glissando off; `$1100` turns it on. When on, tone portamento (G) output **MUST** be quantised to the nearest semitone ($0155 approximation) before being sent to the mixer. The internal G pitch counter **MUST** still advance smoothly; only the audible pitch steps. **This command is implemented solely for ST3/IT compatibility** and therefore only works in 12-TET context.
 
 **Compatibility.** ST3/IT `S10`/`S11` and PT `E30`/`E31` maps directly. In Taud, "nearest semitone" uses the best integer approximation: round `pitch / $155` to the nearest integer, multiply by $155; equivalently, `snapped = (pitch + $AB) / $155 × $155`. Because $155 is an approximation of 4096/12, accumulated rounding across many octaves will drift by up to a few cents; this is documented behaviour and intentional given the microtonal grid.
 
@@ -995,7 +1007,7 @@ S is a multiplexing opcode; the **high nibble of the high byte** selects the sub
 
 **Plain.** Overrides the current note's fine-tune by applying a fixed 4096-TET offset. The index `$x` selects one of sixteen predefined pitch offsets, following ScreamTracker 3's Hz-based fine-tune table but expressed directly in Taud units. This command is implemented for ST3 compatibility.
 
-**Compatibility.** The index scheme matches ST3 exactly: `$8` is the baseline (no change), `$0..$7` are progressively flatter, `$9..$F` are progressively sharper. The Hz reference values come from the ST3 User's Manual and are reproduced here for auditability; the Taud offset is `log2(Hz / 8363) × 4096`, rounded to the nearest integer. **Format converters are advised to apply offset to the note value directly.**
+**Compatibility.** The index scheme matches ST3 exactly: `$8` is the baseline (no change), `$0..$7` are progressively flatter, `$9..$F` are progressively sharper. The Hz reference values come from the ST3 User's Manual and are reproduced here for auditability; the Taud offset is `log2(Hz / 8363) × 4096`, rounded to the nearest integer. **Format converters SHOULD apply the offset to the note value directly.**
 
 | $x | Reference Hz | Taud offset |
 |---|---|---|
@@ -1140,7 +1152,7 @@ The background pool is reaped when a ghost's `fadeoutVolume` drops to zero or it
 
 **Compatibility.** ST3 `SBx` maps directly. ProTracker `E6x` maps to Taud `S $Bx00`.
 
-ST3 has a long-documented bug where pattern delay (SEx) inside a pattern-loop range causes the loop counter to decrement multiple times per visit, producing unintended behaviour. **Taud fixes this bug.** On import, ST3 songs that relied on the bug will loop fewer times in Taud. Converters that want bit-exact ST3 playback should emit a warning when SBx and SEx appear in the same channel within a loop range, or optionally flatten loops by duplicating rows.
+ST3 has a long-documented bug where pattern delay (SEx) inside a pattern-loop range causes the loop counter to decrement multiple times per visit, producing unintended behaviour. **Taud fixes this bug.** On import, ST3 songs that relied on the bug will loop fewer times in Taud. Converters that want bit-exact ST3 playback **SHOULD** emit a warning when SBx and SEx appear in the same channel within a loop range, and **MAY** flatten loops by duplicating rows.
 
 **Implementation.** State per channel: `loop_start_row` (defaulting to 0 at each pattern entry) and `loop_count` (defaulting to 0).
 
@@ -1162,7 +1174,7 @@ on row event (S $Bx00):
 on pattern change: loop_start_row = 0; loop_count = 0
 ```
 
-The crucial bug fix relative to ST3: the loop-counter decrement happens **once per actual row playback**, not once per tick-0 invocation. When SBx shares a row with SEx (pattern delay), the pattern-delay machinery replays the row as a unit, but the SBx state machine treats the whole delay group as a single visit. Implement this by gating the SBx decrement on `pattern_delay_repetition == 0`.
+The crucial bug fix relative to ST3: the loop-counter decrement **MUST** happen **once per actual row playback**, not once per tick-0 invocation. When SBx shares a row with SEx (pattern delay), the pattern-delay machinery replays the row as a unit, but the SBx state machine **MUST** treat the whole delay group as a single visit. Engines **SHOULD** implement this by gating the SBx decrement on `pattern_delay_repetition == 0`.
 
 ---
 
@@ -1172,7 +1184,7 @@ The crucial bug fix relative to ST3: the loop-counter decrement happens **once p
 
 **Compatibility.** ST3 `SCx` maps directly. ProTracker `ECx` also maps directly. ST3 ignores `SC0` (treats it as no cut at all); Taud preserves this.
 
-**Implementation.** On tick `$x`, set `output_volume = 0` but leave `base_volume` unchanged. If `$x ≥ speed`, the cut never fires. If `$x == 0`, the command is ignored. Set the `note_was_cut` flag so a later Q retrigger on the same row is suppressed.
+**Implementation.** On tick `$x`, the engine **MUST** set `output_volume = 0` but **MUST** leave `base_volume` unchanged. If `$x ≥ speed`, the cut **MUST NOT** fire. If `$x == 0`, the command **MUST** be ignored. The engine **MUST** set the `note_was_cut` flag so that a later Q retrigger on the same row is suppressed.
 
 ---
 
@@ -1180,9 +1192,9 @@ The crucial bug fix relative to ST3: the loop-counter decrement happens **once p
 
 **Plain.** Delays the triggering of the note (and any co-row instrument, offset, and volume event) until tick `$x`. Until then, any currently playing note continues.
 
-**Compatibility.** ST3 `SDx` maps directly. ProTracker `EDx` also maps directly. `SD0` plays the note normally on tick 0. If `$x ≥ speed`, the note never plays on this row and does not carry over to the next row. Some trackers allow playback of "malformed" note delays (`$x` greater than current tick speed). Taud discards those notes. If such note events have been encountered during conversion, they must be corrected on the converter.
+**Compatibility.** ST3 `SDx` maps directly. ProTracker `EDx` also maps directly. `SD0` plays the note normally on tick 0. If `$x ≥ speed`, the note **MUST NOT** play on this row and **MUST NOT** carry over to the next row. Some trackers allow playback of "malformed" note delays (`$x` greater than current tick speed); Taud **MUST** discard those notes. If such note events have been encountered during conversion, they **MUST** be corrected by the converter.
 
-**Implementation.** On row parse, defer the note-trigger event (including sample selection, volume, offset, and any volume-column effect) until tick `$x`. On tick `$x`, execute the deferred trigger. When combined with pattern delay (S $Ex00), the deferred trigger re-fires at the start of each row repetition — matching ST3's `kRowDelayWithNoteDelay` behaviour. If `$x` is greater than current tick speed, the note must be discarded (see compatibility notes above)
+**Implementation.** On row parse, the engine **MUST** defer the note-trigger event (including sample selection, volume, offset, and any volume-column effect) until tick `$x`. On tick `$x`, the engine **MUST** execute the deferred trigger. When combined with pattern delay (S $Ex00), the deferred trigger **MUST** re-fire at the start of each row repetition — matching ST3's `kRowDelayWithNoteDelay` behaviour. If `$x` is greater than the current tick speed, the note **MUST** be discarded (see compatibility notes above).
 
 ---
 
@@ -1190,7 +1202,7 @@ The crucial bug fix relative to ST3: the loop-counter decrement happens **once p
 
 **Plain.** Repeats the current row `$x` additional times (so `$x = 0` means no repeat and the row plays once; `$x = 3` means the row plays four times total). Notes do not retrigger across repetitions, but per-tick effects re-run and tick-0 events (fine slides, delayed notes) re-fire on each repetition.
 
-**Compatibility.** ST3 `SEx` maps directly. ProTracker `EEx` also maps directly. Simultaneous SEx on multiple channels: ST3 uses the first SEx in **pan order** (L1..L8 then R1..R8); **Taud uses the first SEx in ascending channel-index order** for predictability. Converters that encounter ST3 songs relying on the pan-order rule should emit a warning.
+**Compatibility.** ST3 `SEx` maps directly. ProTracker `EEx` also maps directly. Simultaneous SEx on multiple channels: ST3 uses the first SEx in **pan order** (L1..L8 then R1..R8); **Taud uses the first SEx in ascending channel-index order** for predictability. Converters that encounter ST3 songs relying on the pan-order rule **SHOULD** emit a warning.
 
 Q retrigger counters do **not** reset between SEx repetitions.
 
@@ -1202,7 +1214,7 @@ Q retrigger counters do **not** reset between SEx repetitions.
 
 **Plain.** Produces a hiss-like progressive inversion of the sample loop, toggling individual bytes over time for a gritty textural effect. Setting `$x = 0` turns the effect off; higher `$x` advances the inversion faster.
 
-**Compatibility.** ProTracker `EFx` is destructive — it XORs bytes directly in the sample data, permanently corrupting the sample. **Taud's implementation is non-destructive**: the XOR is applied at playback time through a per-instrument bit-mask, leaving source samples pristine. ST3 does not implement SFx at all and will parse Taud's S $Fx00 as a no-op; converters targeting ST3 should drop the effect. ProTracker `EFx` imports as Taud `S $Fyyy`, where `yyy = funk_table[x]`.
+**Compatibility.** ProTracker `EFx` is destructive — it XORs bytes directly in the sample data, permanently corrupting the sample. **Taud's implementation MUST be non-destructive**: the XOR **MUST** be applied at playback time through a per-instrument bit-mask, leaving source samples pristine. ST3 does not implement SFx at all and will parse Taud's S $Fx00 as a no-op; converters targeting ST3 **SHOULD** drop the effect. ProTracker `EFx` imports as Taud `S $Fyyy`, where `yyy = funk_table[x]`.
 
 **Implementation.** Each instrument carries a `funk_mask` bit array, one bit per byte of the loop region, all zero at song start. A per-channel counter `funk_accumulator` and a per-channel `funk_write_pos` track progress.
 
@@ -1224,7 +1236,7 @@ on sample byte read during loop playback:
         output_byte = raw_byte
 ```
 
-`S $F000` clears `funk_accumulator` but leaves `funk_mask` intact (the accumulated inversion pattern persists). **On every fresh note trigger**, `funk_write_pos` resets to 0 (matching PT2's `n_wavestart = n_loopstart`); `funk_accumulator` and `funk_speed` persist across notes. The `funk_mask` itself is **only cleared on cue-start reset** (i.e. song-start / stop-and-replay) — within a single playback session it accumulates as PT2's destructive in-place edits would, but a clean replay always reproduces the same audio without needing to reload the song from disk.
+`S $F000` **MUST** clear `funk_accumulator` but **MUST** leave `funk_mask` intact (the accumulated inversion pattern persists). **On every fresh note trigger**, `funk_write_pos` **MUST** reset to 0 (matching PT2's `n_wavestart = n_loopstart`); `funk_accumulator` and `funk_speed` **MUST** persist across notes. The `funk_mask` itself **MUST** be cleared only on cue-start reset (i.e. song-start / stop-and-replay) — within a single playback session it accumulates as PT2's destructive in-place edits would, but a clean replay **MUST** reproduce the same audio without needing to reload the song from disk.
 
 ---
 
@@ -1239,7 +1251,7 @@ Each cell carries a 6-bit value field plus a 2-bit selector field for the volume
 
 Volume-column effects do not consume the main effect slot; a cell can carry both (for instance, a tone portamento in the effect slot and a volume slide in the volume column). Because the volume column writes the per-note axis, an `M $xx00` on the same or following row sets the per-channel axis independently — the two multiply at the mixer (see §3 / §M).
 
-When the converter folds an ST3 K, L, M, or N effect into the volume column, the slide-up / slide-down nibbles map to selectors 1 / 2 (clamped to 6 bits — values above $3F clip). Note that *converted* M and N still target `note_vol` here (vol-col semantics) — to preserve the original per-channel intent, emit them in the main effect column instead.
+When the converter folds an ST3 K, L, M, or N effect into the volume column, the slide-up / slide-down nibbles map to selectors 1 / 2 (clamped to 6 bits — values above $3F clip). Note that *converted* M and N still target `note_vol` here (vol-col semantics) — to preserve the original per-channel intent, converters **MUST** emit them in the main effect column instead.
 
 NOTE: **`3.00` — is No-op**
 
@@ -1254,7 +1266,7 @@ The panning column uses the same 6-bit value + 2-bit selector layout:
 - **`2.$xx` — Pan slide left** by `$xx` per non-first tick (4-bit).
 - **`3.$Sx` — Fine pan slide** on tick 0 only, same direction-bit encoding as the volume column's selector 3.
 
-NOTE: **`3.00` — is No-op**. When Set Pan and S $80xx are both present, S-command takes precedence.
+NOTE: **`3.00` — is No-op**. When Set Pan and S $80xx are both present, S-command **MUST** take precedence.
 
 ---
 
@@ -1272,7 +1284,7 @@ Effects in this section modifies the behaviour of the mixer. Primary intention o
 - ff = 1: Amiga (cycle-based) tone mode. Pitch shift will behave like ProTracker/ScreamTracker. **Coarse and fine E/F arguments are stored as raw tracker period units** (the unscaled byte/nibble from the source PT/S3M/IT file) and applied in Amiga period space. Tone portamento (G) remains linear regardless of mode.
 - ff = 2: Linear-frequency tone mode (MONOTONE compat). **E, F, and G arguments are stored as Hz/tick** (a signed change in audible frequency per song tick), and the engine converts the channel's stored 4096-TET pitch back to a frequency, adds/subtracts the argument, then converts back to 4096-TET. Reference is fixed at 12-TET A4 = 440 Hz / C4 ≈ 261.6256 Hz, which matches MONOTONE's MT_PLAY.PAS `notesHz` table (A0 = 27.5 Hz, equal-temperament). Unlike Amiga mode, *all three* slide effects use the new arithmetic — Monotone's `1xx`, `2xx`, and `3xx` are all in Hz/tick (see MTSRC/MT_PLAY.PAS:606-630).
 
-- rrr = 0: Yes interpolation. Actual interpolation algorithm is implementation-dependent, but recommended to use either Fast Sinc or Linear.
+- rrr = 0: Yes interpolation. The actual interpolation algorithm is implementation-dependent; Fast Sinc or Linear is **RECOMMENDED**.
 - rrr = 1: No interpolation.
 - rrr = 2: Amiga 500 interpolation.
 - rrr = 3: Amiga 1200 interpolation.
@@ -1326,30 +1338,30 @@ This table maps each PT effect to its Taud equivalent. Arguments follow PT's two
 
 These quirks of ST3 are worth preserving or flagging when importing S3M files into Taud:
 
-**Shared memory across effects.** In ST3, a single memory slot backs D, E, F, I, J, K, L, Q, R, and S. A `$00` argument on any of these recalls whichever effect last wrote a non-zero argument. Taud narrows this to four cohorts (EF / G / HU / R) plus private slots. The converter must **eagerly resolve ST3 recalls** — walking the pattern in playback order, tracking the shared memory value, and emitting explicit Taud arguments wherever an ST3 recall crosses a cohort boundary. Otherwise a Taud player will either recall the wrong value or recall $0000.
+**Shared memory across effects.** In ST3, a single memory slot backs D, E, F, I, J, K, L, Q, R, and S. A `$00` argument on any of these recalls whichever effect last wrote a non-zero argument. Taud narrows this to four cohorts (EF / G / HU / R) plus private slots. The converter **MUST** **eagerly resolve ST3 recalls** — walking the pattern in playback order, tracking the shared memory value, and emitting explicit Taud arguments wherever an ST3 recall crosses a cohort boundary. Otherwise a Taud player will either recall the wrong value or recall $0000.
 
 **M / N / P (channel volume and panning).** S3M files produced by IT-aware tools embed M (set channel volume), N (channel volume slide), and P (channel panning slide) using the IT semantics described in §M / §N / §P. These are emitted verbatim into Taud (with M's argument byte clamped to $3F). N and P each have private memory; M is literal-zero. ST3 itself never wrote M / N / P, so legacy S3M files contain none.
 
-**Cxx BCD encoding.** ST3 stores pattern-break row numbers as BCD on disk (`$10` means decimal 10). Taud uses binary. Decode on import; encode on export. Out-of-range BCD bytes (decimal 64 or higher) clamp to row 0.
+**Cxx BCD encoding.** ST3 stores pattern-break row numbers as BCD on disk (`$10` means decimal 10). Taud uses binary. Converters **MUST** decode on import and encode on export. Out-of-range BCD bytes (decimal 64 or higher) **SHOULD** clamp to row 0.
 
-**Tempo range.** ST3 accepts tempos $20..$FF (BPM 32..255); Taud accepts bytes $00..$FF (BPM 25..280). Imported ST3 tempos must be shifted down by $19; Taud tempos below $07 and above $E6 cannot be represented in ST3 and should clamp on export.
+**Tempo range.** ST3 accepts tempos $20..$FF (BPM 32..255); Taud accepts bytes $00..$FF (BPM 25..280). Imported ST3 tempos **MUST** be shifted down by $19; Taud tempos below $07 and above $E6 cannot be represented in ST3 and **SHOULD** clamp on export.
 
-**SBx + SEx interaction.** ST3 miscounts loop iterations when pattern delay is active inside a pattern loop; Taud fixes this. Songs that depended on the bug for their intended playback will loop fewer times in Taud. Flag such songs on import.
+**SBx + SEx interaction.** ST3 miscounts loop iterations when pattern delay is active inside a pattern loop; Taud fixes this. Songs that depended on the bug for their intended playback will loop fewer times in Taud. Converters **SHOULD** flag such songs on import.
 
-**Simultaneous SEx priority.** ST3 uses pan order (L1..L8, R1..R8); Taud uses ascending channel-index order. Rare; flag on import if multiple channels carry SEx in the same row.
+**Simultaneous SEx priority.** ST3 uses pan order (L1..L8, R1..R8); Taud uses ascending channel-index order. Rare; converters **SHOULD** flag on import if multiple channels carry SEx in the same row.
 
-**Muted channels.** ST3 skips all effect processing on muted channels (no volume change, no tempo change, no jumps); Taud follows this rule for strict compatibility but recommends that new compositions avoid muting channels that carry global effects.
+**Muted channels.** ST3 skips all effect processing on muted channels (no volume change, no tempo change, no jumps); Taud **MUST** follow this rule for strict compatibility, but new compositions **SHOULD NOT** mute channels that carry global effects.
 
 **Volume cap.** ST3's volume caps at $40; Taud's at $3F. Notes that reached $40 in ST3 (a rare edge) will play marginally quieter in Taud.
 
-**Global volume scale.** ST3's 0..$40 maps to Taud's 0..$FF with a ×4 scale on import, truncated ÷4 on export.
+**Global volume scale.** ST3's 0..$40 maps to Taud's 0..$FF with a ×4 scale on import and a truncated ÷4 on export. Converters **MUST** apply these scales.
 
 **Linear pitch slides.** ST3's slide arithmetic is period-based; Taud supports both linear and period-based and selects between them via the song-table `f` flag. Conversion rules:
 
 - Clear `linear_slides`. Both coarse (Exx/Fxx) and fine/extra-fine (EFx/EEx/FFx/FEx) are stored **verbatim** as raw ST3 period units — coarse as `E/F $00xx`, fine as `E/F $F00x` — with no scaling. Taud `f` flag is **set**; the engine applies both forms in Amiga period space at playback, exactly recovering the source's period-step count and the non-linear pitch character.
-- G (tone portamento) is always converted with `round(× 64/3)` and treated as linear, regardless of mode.
+- G (tone portamento) **MUST** always be converted with `round(× 64/3)` and treated as linear, regardless of mode.
 
-**Default tempo byte.** Taud's default $64 equals 125 BPM under the $19 offset; this is not the same as ST3's `$7D` default, which maps to Taud `$64` after subtracting $19. Converters must remap on both import and export.
+**Default tempo byte.** Taud's default $64 equals 125 BPM under the $19 offset; this is not the same as ST3's `$7D` default, which maps to Taud `$64` after subtracting $19. Converters **MUST** remap on both import and export.
 
 ---
 
@@ -1361,7 +1373,7 @@ This section documents important implementation details that are not covered by
 
 Taud's volume fadeout is a single linear decay applied per song tick after key-off (or NNA Note-Fade). It is **the only retirement mechanism** for sustained voices when the volume envelope holds non-zero or has no terminating zero node — without a non-zero stored fadeout, such voices play forever.
 
-The 12-bit stored fadeout lives at instrument-record bytes 172 (low 8 bits) and 173 (low nibble = high 4 bits; high nibble reserved). Range 0..4095. The engine maintains a per-voice `fadeoutVolume ∈ [0, 1]` initialised to 1.0 on note-on, and once per song tick while the voice is keyed off:
+The 12-bit stored fadeout lives at instrument-record bytes 172 (low 8 bits) and 173 (low nibble = high 4 bits; high nibble reserved). Range 0..4095. The engine **MUST** maintain a per-voice `fadeoutVolume ∈ [0, 1]` initialised to 1.0 on note-on, and once per song tick while the voice is keyed off **MUST**:
 
 ```
 fadeoutVolume -= storedFadeout / 1024.0
@@ -1386,7 +1398,7 @@ There is no separate "use fadeout" flag — both extremes share the same field,
 - `storedFadeout = 32` → fade ≈ 640 ms
 - `storedFadeout = 1024` → ~20 ms (one tick)
 
-**Converter unit conversion.** Source trackers each expose fadeout in their own unit; converters scale the source value into Taud's 0..4095 field.
+**Converter unit conversion.** Source trackers each expose fadeout in their own unit; converters **MUST** scale the source value into Taud's 0..4095 field.
 
 - **IT** (`it2taud.py`): IT files store fadeout as a 16-bit field at instrument-record offset `0x14`, range 0..1024 per ITTECH (some loaders accept up to 2048). Schism's per-tick decrement is `stored / 1024` — identical to Taud's unit. **Pass-through with clamp:**
   ```python
@@ -1416,7 +1428,7 @@ There is no separate "use fadeout" flag — both extremes share the same field,
   - For tone portamento (G), `tonePortaSpeed` is also in Hz/tick: each tick walks `freq` toward `noteValToFreq(target)` by `±tonePortaSpeed` until the target frequency is reached.
   - Like Amiga mode, the per-voice intermediate frequency is cached across ticks (no round-trip rounding) and reseeded on note trigger, S$2x finetune, fine slides, and the start of a fresh multi-tick coarse slide.
 
-**Initialisation from the song table.** The same flags byte is stored in the song-table entry (see file format §Song Table). A Taud player should write this byte to MMIO playhead register 7 before starting playback; the mixer then applies it as the initial state on every reset, and subsequent in-pattern `1` effects may override it.
+**Initialisation from the song table.** The same flags byte is stored in the song-table entry (see file format §Song Table). A Taud player **MUST** write this byte to MMIO playhead register 7 before starting playback; the mixer then applies it as the initial state on every reset, and subsequent in-pattern `1` effects **MAY** override it.
 
 ---
 

assets/disk0/AUTOEXEC.BAT

@@ -1,12 +1,11 @@
-echo "Starting TVDOS..."
-
-rem put set-xxx commands here:
-set PATH=\tvdos\installer;\tvdos\tuidev;\tbas;\hopper\bin;$PATH
-set INCLPATH=\hopper\include;$INCLPATH
-set HELPPATH=\hopper\help;$HELPPATH
-set KEYBOARD=us_colemak
-
-rem this line specifies which shell to be presented after the boot precess:
+rem AUTOEXEC.BAT -- per-console launch script. Run once for every console:
+rem each virtual-console pane runs it (via vtmgr's bootstrap), and the boot
+rem shell runs it as the fallback once vtmgr exits (Alt-0). Environment setup
+rem (`set` commands) lives in \commandrc, which TVDOS.SYS runs before this.
+rem
+rem Korean IME registers a per-CONTEXT handler (unicode.uniprint), so it must
+rem run per-console here rather than once at boot.
 tvdos/i18n/korean
-zfm
+
+rem The interactive shell for this console.
 command -fancy

assets/disk0/commandrc

@@ -0,0 +1,9 @@
+rem commandrc -- environment setup, run by TVDOS.SYS in EVERY context
+rem (the boot shell AND every virtual-console pane). Put `set` commands and
+rem other env-only configuration here. Do NOT launch apps from this file:
+rem app launches belong in AUTOEXEC.BAT (run per-console by vtmgr).
+
+set PATH=\tvdos\installer;\tvdos\tuidev;\tbas;\hopper\bin;$PATH
+set INCLPATH=\hopper\include;$INCLPATH
+set HELPPATH=\hopper\help;$HELPPATH
+set KEYBOARD=us_colemak

assets/disk0/home/config/zfmrc

@@ -1,5 +0,0 @@
-[EXEC_FUNS]
-nes,A:/home/tvnes/tvnes.js {0}
-
-[COL_HL_EXT]
-nes,156

assets/disk0/home/fsh.js

@@ -1,24 +1,181 @@
-graphics.setBackground(2,1,3);
-graphics.resetPalette();
+graphics.setBackground(2,1,3)
+graphics.resetPalette()
+const GL = require("gl")
+const win = require("wintex")
+const keysym = require("keysym")
 
 function captureUserInput() {
-    sys.poke(-40, 1);
+    sys.poke(-40, 1)
 }
 
 function getKeyPushed(keyOrder) {
-    return sys.peek(-41 - keyOrder);
+    return sys.peek(-41 - keyOrder)
 }
 
-let _fsh = {};
-_fsh.titlebarTex = new GL.Texture(2, 14, base64.atob("/u/+/v3+/f39/f39/f39/f39/P39/Pz8/Pv7+w=="));
-_fsh.scrdim = con.getmaxyx();
-_fsh.scrwidth = _fsh.scrdim[1];
-_fsh.scrheight = _fsh.scrdim[0];
-_fsh.brandName = "f\xb3Sh";
+function readMousePos() {
+    let lx = sys.peek(-33) & 0xFF
+    let hx = sys.peek(-34) & 0xFF
+    let ly = sys.peek(-35) & 0xFF
+    let hy = sys.peek(-36) & 0xFF
+    return [(hx << 8) | lx, (hy << 8) | ly]
+}
+
+function readMouseButtons() {
+    return sys.peek(-37) & 0xFF
+}
+
+// Returns true if any of the eight key event buffer slots holds keycode `kc`.
+function isKeyDown(kc) {
+    for (let i = 0; i < 8; i++) {
+        if ((sys.peek(-41 - i) & 0xFF) === kc) return true
+    }
+    return false
+}
+
+let _fsh = {}
+
+// Config file path
+_fsh.CONFIG_PATH = "A:/home/config/fshrc"
+
+// Widget row caps (must match the loop bounds in draw())
+_fsh.TODO_MAX_ROWS = 13       // todoWidget draws i = 0..12
+_fsh.QA_MAX_ROWS = 22         // quickAccessWidget draws i = 0..21
+_fsh.TODO_TEXT_WIDTH = 24     // visible characters per todo row
+_fsh.QA_LABEL_WIDTH = 24      // visible characters per QA label
+_fsh.QA_CMD_WIDTH = 60        // command path field width in dialog
+
+// Highlight foreground for keyboard focus on widget lists. The background
+// stays transparent (255) so the wallpaper continues to show through.
+_fsh.HL_FG = 230
+_fsh.HL_BG = 255
+
+// Default Quick Access entries when fshrc is missing or empty
+_fsh.DEFAULT_QA = [
+    ["Files",     "/tvdos/bin/zsh.js"],
+    ["Editor",    "/tvdos/bin/edit.js"],
+    ["BASIC",     "/tbas/basic.js"],
+    ["DOS Shell", "/tvdos/bin/command.js /fancy"]
+]
+
+// Mouse button bits (MMIO[36] layout per IOSpace.kt)
+_fsh.MB_LEFT = 1
+_fsh.MB_RIGHT = 2
+
+// Current focus: null or {widgetId: string, index: number}.
+// Index uses the same convention as hitTest: 0..length-1 are entries,
+// `length` is the "+ Click to add" row.
+_fsh.focus = null
+
+// Parse fshrc text into {todos: [[text, done], ...], qa: [[label, cmd], ...]}.
+// Returns null for both arrays when input is empty/whitespace.
+_fsh.parseConfig = function(text) {
+    let todos = []
+    let qa = []
+    let section = null
+    if (!text) return {todos: todos, qa: qa}
+    let lines = text.split("\n")
+    for (let i = 0; i < lines.length; i++) {
+        let line = lines[i]
+        // strip trailing \r if any
+        if (line.length && line.charCodeAt(line.length - 1) === 13) {
+            line = line.substring(0, line.length - 1)
+        }
+        if (line.length === 0) continue
+        if (line.charAt(0) === "[") {
+            let close = line.indexOf("]")
+            if (close > 0) {
+                let name = line.substring(1, close).trim().toUpperCase()
+                if (name === "TODO" || name === "QUICK_ACCESS") section = name
+                else section = null  // unknown section: ignore until next header
+            }
+            continue
+        }
+        if (section === "TODO") {
+            if (line.length < 2) continue
+            let marker = line.charAt(0)
+            if ((marker === "+" || marker === "-") && line.charAt(1) === " ") {
+                todos.push([line.substring(2), marker === "+"])
+            }
+        } else if (section === "QUICK_ACCESS") {
+            let comma = line.indexOf(",")
+            if (comma <= 0) continue     // need a non-empty label
+            let label = line.substring(0, comma)
+            let cmd = line.substring(comma + 1)
+            qa.push([label, cmd])
+        }
+    }
+    return {todos: todos, qa: qa}
+}
+
+// Build fshrc text from in-memory model. Inverse of parseConfig.
+_fsh.serializeConfig = function(todos, qa) {
+    let out = "[TODO]\n"
+    for (let i = 0; i < todos.length; i++) {
+        let t = todos[i]
+        out += (t[1] ? "+ " : "- ") + t[0] + "\n"
+    }
+    out += "\n[QUICK_ACCESS]\n"
+    for (let i = 0; i < qa.length; i++) {
+        out += qa[i][0] + "," + qa[i][1] + "\n"
+    }
+    return out
+}
+
+// Read fshrc; populate todoWidget.todoList and quickAccessWidget.entries.
+// Falls back to defaults on missing/empty/malformed file.
+_fsh.loadConfig = function() {
+    let f = files.open(_fsh.CONFIG_PATH)
+    let parsed = {todos: [], qa: []}
+    if (f.exists) {
+        try {
+            parsed = _fsh.parseConfig(f.sread())
+        } catch (e) {
+            serial.printerr("fsh.loadConfig: parse failed: " + e)
+            parsed = {todos: [], qa: []}
+        }
+    }
+    todoWidget.todoList = parsed.todos
+    quickAccessWidget.entries = (parsed.qa.length > 0)
+        ? parsed.qa
+        : _fsh.DEFAULT_QA.slice()   // copy so saves don't mutate the constant
+}
+
+// Persist the current in-memory todos + QA entries to fshrc.
+_fsh.saveConfig = function() {
+    try {
+        let f = files.open(_fsh.CONFIG_PATH)
+        if (!f.exists) f.mkFile()
+        f.swrite(_fsh.serializeConfig(todoWidget.todoList, quickAccessWidget.entries))
+    } catch (e) {
+        serial.printerr("fsh.saveConfig: write failed: " + e)
+    }
+}
+
+
+// Map (mouse char x, mouse char y) to a row index for a widget drawn at
+// (xoff, yoff) with `length` existing entries and `maxRows` total rows.
+// Returns null / {kind:"add"} / {kind:"item", index: i}.
+_fsh.hitTestList = function(charX, charY, xoff, yoff, textWidth, length, maxRows) {
+    // Each row sits at (yoff + i + 2, xoff..xoff + textWidth + 1).
+    // Column range: icon at xoff, text at xoff+2 .. xoff+1+textWidth.
+    // Allow clicks anywhere on the row's char cells (icon + text region).
+    let relY = charY - yoff - 2
+    if (relY < 0 || relY >= maxRows) return null
+    if (charX < xoff || charX > xoff + 1 + textWidth) return null
+    if (relY < length) return {kind: "item", index: relY}
+    if (relY === length) return {kind: "add"}
+    return null
+}
+
+_fsh.titlebarTex = new GL.Texture(2, 14, base64.atob("/u/+/v3+/f39/f39/f39/f39/P39/Pz8/Pv7+w=="))
+_fsh.scrdim = con.getmaxyx()
+_fsh.scrwidth = _fsh.scrdim[1]
+_fsh.scrheight = _fsh.scrdim[0]
+_fsh.brandName = "f\xb3Sh"
 _fsh.brandLogoTexSmall = new GL.Texture(24, 14, gzip.decomp(base64.atob(
 "H4sIAAAAAAAAAPv/Hy/4Qbz458+fIeILQQBIwoSh6qECuMVBukCmIJkDVQ+RQNgLE0MX/w+1lyhxqIUwTLJ/sQMAcIXsbVABAAA="
-)));
-_fsh.scrlayout = ["com.fsh.clock","com.fsh.calendar","com.fsh.todo_list", "com.fsh.quick_access"];
+)))
+_fsh.scrlayout = ["com.fsh.clock","com.fsh.calendar","com.fsh.todo_list", "com.fsh.quick_access"]
 
 _fsh.drawWallpaper = function() {
     let wp = files.open("A:/home/wall.bytes")
@@ -28,85 +185,85 @@ _fsh.drawWallpaper = function() {
     wp.pread(b, 250880, 0)
     dma.ramToFrame(b, 0, 250880)
     sys.free(b)
-};
+}
 
 _fsh.drawTitlebar = function(titletext) {
-    GL.drawTexPattern(_fsh.titlebarTex, 0, 0, 560, 14);
+    GL.drawTexPattern(_fsh.titlebarTex, 0, 0, 560, 14)
     if (titletext === undefined || titletext.length == 0) {
-        con.move(1,1);
-        print(" ".repeat(_fsh.scrwidth));
-        GL.drawTexImageOver(_fsh.brandLogoTexSmall, 268, 0);
+        con.move(1,1)
+        print(" ".repeat(_fsh.scrwidth))
+        GL.drawTexImageOver(_fsh.brandLogoTexSmall, 268, 0)
     }
     else {
-        con.color_pair(240, 255);
-        GL.drawTexPattern(_fsh.titlebarTex, 268, 0, 24, 14);
-        con.move(1, 1 + (_fsh.scrwidth - titletext.length) / 2);
-        print(titletext);
+        con.color_pair(240, 255)
+        GL.drawTexPattern(_fsh.titlebarTex, 268, 0, 24, 14)
+        con.move(1, 1 + (_fsh.scrwidth - titletext.length) / 2)
+        print(titletext)
     }
-    con.color_pair(254, 255);
-};
+    con.color_pair(254, 255)
+}
 
 
 _fsh.Widget = function(id, w, h) {
-    this.identifier = id;
-    this.width = w;
-    this.height = h;
+    this.identifier = id
+    this.width = w
+    this.height = h
 
     if (!this.identifier) {
-        this.identifier = "";
+        this.identifier = ""
     }
 
-    //this.update = function() {};
+    //this.update = function() {}
     /**
      * Params charXoff and charYoff are ZERO-BASED!
      */
-    this.draw = function(charXoff, charYoff) {};
+    this.draw = function(charXoff, charYoff) {}
 }
 
 _fsh.widgets = {}
 _fsh.registerNewWidget = function(widget) {
-    _fsh.widgets[widget.identifier] = widget;
+    _fsh.widgets[widget.identifier] = widget
 }
 
-let clockWidget = new _fsh.Widget("com.fsh.clock", _fsh.scrwidth - 8, 7*2);
+let clockWidget = new _fsh.Widget("com.fsh.clock", _fsh.scrwidth - 8, 7*2)
 clockWidget.numberSheet = new GL.SpriteSheet(19, 22, new GL.Texture(190, 22, gzip.decomp(base64.atob(
 "H4sIAAAAAAAAAMWVW3LEMAgE739aHcFJJV5ZMD2I9ToVfcl4GBr80HF8r/FaR1ozMuIyoUu87lEXI0al5qVR5AebSwchSaNE6Nyo1Nw5HXF3SfPT4Bshl"+
 "EycA8RD96mLlHbuhTgOrfLnUDZspafbSQWk56WEGvQEtWaWwgb8iz7a8AOXhsraO/q9Qw2/GnXovfVN+q2wM/p/oddn2cjF239GX3y11+SWCtc6FTHC1v"+
 "TVPkDPWWn0w+DDz93UX9v9mF5KIsQ6OdN2KJoB4ui1bXXr0AMp0YfiQo//4XhpK8555dsNehAqVS5uhb5iHn3Kko769J59KmLBe/TSR7hcsd+hr+HnrwR"+
 "9uvRF9+D3MP14gN7lqx+8OuNT+uqt3NFX3SN9fTbeeHNq+C29pRWzX5+Rcm7SZyjOKJ/2hkSPqul4xN279DrSYvCrNu2NI7ZMp1ouBxK3KBVVnEeAUWbK"+
 "MUDn5DPsPxmUqHZQjGpy2hergM3EVBAAAA=="
-))));
+))))
 
-clockWidget.clockColon = new GL.Texture(4, 3, base64.atob("7+/v7+/v7+/v7+/v"));
-clockWidget.monthNames = ["Spring", "Summer", "Autumn", "Winter"];
-clockWidget.dayNames = ["Mondag  ", "Tysdag  ", "Midtveke", "Torsdag ", "Fredag  ", "Laurdag ", "Sundag  ", "Verddag "];
+clockWidget.clockColon = new GL.Texture(4, 3, base64.atob("7+/v7+/v7+/v7+/v"))
+clockWidget.monthNames = ["Spring", "Summer", "Autumn", "Winter"]
+clockWidget.dayNames = ["Mondag  ", "Tysdag  ", "Midtveke", "Torsdag ", "Fredag  ", "Laurdag ", "Sundag  ", "Verddag "]
 clockWidget.draw = function(charXoff, charYoff) {
-    con.color_pair(254, 255);
-    let xoff = charXoff * 7;
-    let yoff = charYoff * 14 + 3;
-    let timeInMinutes = ((sys.currentTimeInMills() / 60000)|0);
-    let mins = timeInMinutes % 60;
-    let hours = ((timeInMinutes / 60)|0) % 24;
-    let ordinalDay = ((timeInMinutes / (60*24))|0) % 120;
-    let visualDay = (ordinalDay % 30) + 1;
-    let months = ((timeInMinutes / (60*24*30))|0) % 4;
-    let dayName = ordinalDay % 7; // 0 for Mondag
-    if (ordinalDay == 119) dayName = 7; // Verddag
-    let years = ((timeInMinutes / (60*24*30*120))|0) + 125;
+    con.color_pair(254, 255)
+    let xoff = charXoff * 7
+    let yoff = charYoff * 14 + 3
+    let timeInMinutes = ((sys.currentTimeInMills() / 60000)|0)
+    let mins = timeInMinutes % 60
+    let hours = ((timeInMinutes / 60)|0) % 24
+    let ordinalDay = ((timeInMinutes / (60*24))|0) % 120
+    let visualDay = (ordinalDay % 30) + 1
+    let months = ((timeInMinutes / (60*24*30))|0) % 4
+    let dayName = ordinalDay % 7 // 0 for Mondag
+    if (ordinalDay == 119) dayName = 7 // Verddag
+    let years = ((timeInMinutes / (60*24*30*120))|0) + 125
     // draw timepiece
-    GL.drawSprite(clockWidget.numberSheet, (hours / 10)|0, 0, xoff, yoff, 1);
-    GL.drawSprite(clockWidget.numberSheet, hours % 10, 0, xoff + 24, yoff, 1);
-    GL.drawTexImage(clockWidget.clockColon, xoff + 48, yoff + 5, 1);
-    GL.drawTexImage(clockWidget.clockColon, xoff + 48, yoff + 14, 1);
-    GL.drawSprite(clockWidget.numberSheet, (mins / 10)|0, 0, xoff + 57, yoff, 1);
-    GL.drawSprite(clockWidget.numberSheet, mins % 10, 0, xoff + 81, yoff, 1);
+    GL.drawSprite(clockWidget.numberSheet, (hours / 10)|0, 0, xoff, yoff, 1)
+    GL.drawSprite(clockWidget.numberSheet, hours % 10, 0, xoff + 24, yoff, 1)
+    GL.drawTexImage(clockWidget.clockColon, xoff + 48, yoff + 5, 1)
+    GL.drawTexImage(clockWidget.clockColon, xoff + 48, yoff + 14, 1)
+    GL.drawSprite(clockWidget.numberSheet, (mins / 10)|0, 0, xoff + 57, yoff, 1)
+    GL.drawSprite(clockWidget.numberSheet, mins % 10, 0, xoff + 81, yoff, 1)
     // print month and date
-    con.move(1 + charYoff, 17 + charXoff);
-    print(clockWidget.monthNames[months]+" "+visualDay);
+    con.move(1 + charYoff, 17 + charXoff)
+    print(clockWidget.monthNames[months]+" "+visualDay)
     // print year and dayname
-    con.move(2 + charYoff, 17 + charXoff);
-    print("\xE7"+years+" "+clockWidget.dayNames[dayName]);
-};
+    con.move(2 + charYoff, 17 + charXoff)
+    print("\xE7"+years+" "+clockWidget.dayNames[dayName])
+}
 
 
 let calendarWidget = new _fsh.Widget("com.fsh.calendar", (_fsh.scrwidth - 8) / 2, 7*6)
@@ -171,70 +328,284 @@ calendarWidget.draw = function(charXoff, charYoff) {
 let todoWidget = new _fsh.Widget("com.fsh.todo_list", (_fsh.scrwidth - 8) / 2, 7*10)
 todoWidget.todoList = [["Hello, world!", true]]
 todoWidget.draw = function(charXoff, charYoff) {
+    let focusIndex = (_fsh.focus && _fsh.focus.widgetId === todoWidget.identifier)
+        ? _fsh.focus.index : -1
+
     con.color_pair(254, 255)
     let xoff = charXoff * 7
     let yoff = charYoff * 14 + 3
 
     con.move(charYoff, charXoff)
-    print("========== TODO ==========")
+    print('\u00CD'.repeat(10)+" TODO "+'\u00CD'.repeat(10))
 
     for (let i = 0; i <= 12; i++) {
-        let list = todoWidget.todoList[i] || ["Click to add", null]
+        let list = todoWidget.todoList[i] || ["Click to add"+" ".repeat(_fsh.TODO_TEXT_WIDTH - 12), null]
+        let isFocused = (i === focusIndex)
 
-        if (list[1] === null) con.color_pair(249, 255)
+        if (isFocused) con.color_pair(_fsh.HL_FG, _fsh.HL_BG)
+        else if (list[1] === null) con.color_pair(249, 255)
         else con.color_pair(254, 255)
 
         con.move(charYoff + i + 2, charXoff)
         con.addch((list[1] === null) ? 43 : (list[1]) ? 0x9F : 0x9E)
 
         if (i > todoWidget.todoList.length) {
+            // Filler row \u2014 keep underscores but don't highlight (can't focus here)
+            con.color_pair(254, 255)
             for (let k = 0; k < 24; k++) {
                 con.mvaddch(charYoff + i + 2, charXoff + 2 + k, 95)
             }
         }
         else {
             con.move(charYoff + i + 2, charXoff + 2)
-            print(`${list[0]}`)
+            // Pad text to TODO_TEXT_WIDTH so the highlight bar covers full row
+            let text = `${list[0]}`
+            if (text.length > _fsh.TODO_TEXT_WIDTH) text = text.substring(0, _fsh.TODO_TEXT_WIDTH)
+            if (isFocused) text = text + " ".repeat(_fsh.TODO_TEXT_WIDTH - text.length)
+            print(text)
         }
     }
 }
 
 let quickAccessWidget = new _fsh.Widget("com.fsh.quick_access", (_fsh.scrwidth - 8) / 2, 7*20)
-quickAccessWidget.entries = [
-    ["Files", "/tvdos/bin/explorer.js"],
+quickAccessWidget.entries = [ // TODO read from /home/config/fshrc
+    ["Files", "/tvdos/bin/zfm.js"],
     ["Editor", "/tvdos/bin/edit.js"],
     ["BASIC", "/tbas/basic.js"],
-    ["DOS Shell", "/tvdos/bin/command.js /fancy"]
+    ["DOS Shell", "/tvdos/bin/command.js -fancy"]
 ]
 quickAccessWidget.draw = function(charXoff, charYoff) {
+    let focusIndex = (_fsh.focus && _fsh.focus.widgetId === quickAccessWidget.identifier)
+        ? _fsh.focus.index : -1
+
     con.color_pair(254, 255)
     let xoff = charXoff * 7
     let yoff = charYoff * 14 + 3
 
     con.move(charYoff, charXoff)
-    print("====== QUICK ACCESS ======")
+    print('\u00CD'.repeat(6)+" QUICK ACCESS "+'\u00CD'.repeat(6))
 
     for (let i = 0; i <= 21; i++) {
-        let list = quickAccessWidget.entries[i] || ["Click to add", null]
+        let list = quickAccessWidget.entries[i] || ["Click to add"+" ".repeat(_fsh.QA_LABEL_WIDTH - 12), null]
+        let isFocused = (i === focusIndex)
 
-        if (list[1] === null) con.color_pair(249, 255)
+        if (isFocused) con.color_pair(_fsh.HL_FG, _fsh.HL_BG)
+        else if (list[1] === null) con.color_pair(249, 255)
         else con.color_pair(254, 255)
 
         con.move(charYoff + i + 2, charXoff)
         con.addch((list[1] === null) ? 0xF9 : (list[1]) ? 7 : 0x7F)
 
         if (i > quickAccessWidget.entries.length) {
+            con.color_pair(254, 255)
             for (let k = 0; k < 24; k++) {
                 con.mvaddch(charYoff + i + 2, charXoff + 2 + k, 95)
             }
         }
         else {
             con.move(charYoff + i + 2, charXoff + 2)
-            print(`${list[0]}`)
+            let text = `${list[0]}`
+            if (text.length > _fsh.QA_LABEL_WIDTH) text = text.substring(0, _fsh.QA_LABEL_WIDTH)
+            if (isFocused) text = text + " ".repeat(_fsh.QA_LABEL_WIDTH - text.length)
+            print(text)
         }
     }
 }
 
+todoWidget.hitTest = function(charX, charY, xoff, yoff) {
+    return _fsh.hitTestList(charX, charY, xoff, yoff,
+        _fsh.TODO_TEXT_WIDTH, todoWidget.todoList.length, _fsh.TODO_MAX_ROWS)
+}
+
+quickAccessWidget.hitTest = function(charX, charY, xoff, yoff) {
+    return _fsh.hitTestList(charX, charY, xoff, yoff,
+        _fsh.QA_LABEL_WIDTH, quickAccessWidget.entries.length, _fsh.QA_MAX_ROWS)
+}
+
+
+// Re-render the whole shell. Use after a dialog closes (which clobbered
+// the underlying char cells) or after execApp returns.
+_fsh.redrawAll = function() {
+    con.color_pair(254, 255)
+    con.clear()
+    graphics.clearPixels(255)
+    graphics.clearPixels2(255)
+    graphics.setFramebufferScroll(0, 0)
+    _fsh.drawWallpaper()
+    _fsh.drawTitlebar()
+    _fsh.widgets["com.fsh.clock"].draw(25, 3)
+    _fsh.widgets["com.fsh.calendar"].draw(12, 8)
+    _fsh.widgets["com.fsh.todo_list"].draw(10, 17)
+    _fsh.widgets["com.fsh.quick_access"].draw(47, 8)
+}
+
+_fsh.openAddTodoDialog = function() {
+    let res = win.showDialog({
+        title: "New Todo",
+        fields: [{label: "Text:", initial: "", width: _fsh.TODO_TEXT_WIDTH}],
+        allowDelete: false
+    })
+    _fsh.redrawAll()
+    if (res.action !== "ok") return
+    let text = res.values[0].trim()
+    if (text.length === 0) return
+    if (todoWidget.todoList.length >= _fsh.TODO_MAX_ROWS) return
+    todoWidget.todoList.push([text, false])
+    _fsh.saveConfig()
+}
+
+_fsh.openEditTodoDialog = function(index) {
+    let entry = todoWidget.todoList[index]
+    if (!entry) return
+    let res = win.showDialog({
+        title: "Edit Todo",
+        fields: [{label: "Text:", initial: entry[0], width: _fsh.TODO_TEXT_WIDTH}],
+        allowDelete: true
+    })
+    _fsh.redrawAll()
+    if (res.action === "cancel") return
+    if (res.action === "delete") {
+        todoWidget.todoList.splice(index, 1)
+        _fsh.saveConfig()
+        return
+    }
+    let text = res.values[0].trim()
+    if (text.length === 0) return
+    todoWidget.todoList[index] = [text, entry[1]]
+    _fsh.saveConfig()
+}
+
+_fsh.openAddQaDialog = function() {
+    let res = win.showDialog({
+        title: "New Quick Access",
+        fields: [
+            {label: "Label:",   initial: "", width: _fsh.QA_LABEL_WIDTH},
+            {label: "Command:", initial: "", width: _fsh.QA_CMD_WIDTH}
+        ],
+        allowDelete: false
+    })
+    _fsh.redrawAll()
+    if (res.action !== "ok") return
+    let label = res.values[0].trim()
+    let cmd = res.values[1].trim()
+    if (label.length === 0 || cmd.length === 0) return
+    if (quickAccessWidget.entries.length >= _fsh.QA_MAX_ROWS) return
+    quickAccessWidget.entries.push([label, cmd])
+    _fsh.saveConfig()
+}
+
+_fsh.openEditQaDialog = function(index) {
+    let entry = quickAccessWidget.entries[index]
+    if (!entry) return
+    let res = win.showDialog({
+        title: "Edit Quick Access",
+        fields: [
+            {label: "Label:",   initial: entry[0], width: _fsh.QA_LABEL_WIDTH},
+            {label: "Command:", initial: entry[1], width: _fsh.QA_CMD_WIDTH}
+        ],
+        allowDelete: true
+    })
+    _fsh.redrawAll()
+    if (res.action === "cancel") return
+    if (res.action === "delete") {
+        quickAccessWidget.entries.splice(index, 1)
+        _fsh.saveConfig()
+        return
+    }
+    let label = res.values[0].trim()
+    let cmd = res.values[1].trim()
+    if (label.length === 0 || cmd.length === 0) return
+    quickAccessWidget.entries[index] = [label, cmd]
+    _fsh.saveConfig()
+}
+
+_fsh.toggleTodoDone = function(index) {
+    let entry = todoWidget.todoList[index]
+    if (!entry) return
+    entry[1] = !entry[1]
+    _fsh.saveConfig()
+}
+
+// Launch a Quick Access entry. cmd is the verbatim string the user typed.
+// We split on first space to derive a program path + args; if the path
+// has no leading "/", we treat it as relative to the current drive.
+_fsh.launchEntry = function(label, cmd) {
+    let firstSpace = cmd.indexOf(" ")
+    let progPath = (firstSpace >= 0) ? cmd.substring(0, firstSpace) : cmd
+    let argTail = (firstSpace >= 0) ? cmd.substring(firstSpace + 1) : ""
+    let fullPath = progPath.startsWith("/") ? ("A:" + progPath) : progPath
+
+    try {
+        let f = files.open(fullPath)
+        if (!f.exists) {
+            serial.printerr("fsh.launchEntry: not found: " + fullPath)
+            return
+        }
+        let code = f.sread()
+        let tokens = [progPath].concat(argTail.length ? argTail.split(" ") : [])
+
+        // erase all pixels and draw wallpaper
+        con.reset_graphics()
+        con.clear()
+        graphics.clearPixels(255)
+        graphics.clearPixels2(255)
+        _fsh.drawWallpaper()
+        con.curs_set(1)
+
+        execApp(code, tokens)
+    } catch (e) {
+        serial.printerr("fsh.launchEntry: " + label + " failed: " + e)
+    }
+    con.curs_set(0)
+    graphics.setBackground(2,1,3)
+    graphics.resetPalette()
+    // Apps (e.g. zfm) may switch to graphics mode 0; restore mode 3 so the
+    // clock widget on framebuffer 2 is composited again.
+    graphics.setGraphicsMode(3)
+    _fsh.redrawAll()
+}
+
+// Layout map: widget positions hard-coded to match the draw calls below.
+_fsh.layouts = {
+    "com.fsh.todo_list":    {xoff: 10, yoff: 17, widget: null},
+    "com.fsh.quick_access": {xoff: 47, yoff: 8,  widget: null}
+}
+
+// Find which widget (if any) was hit by (charX, charY). Returns
+// {widgetId, hit} or null.
+_fsh.findHit = function(charX, charY) {
+    let ids = ["com.fsh.todo_list", "com.fsh.quick_access"]
+    for (let i = 0; i < ids.length; i++) {
+        let id = ids[i]
+        let layout = _fsh.layouts[id]
+        let widget = _fsh.widgets[id]
+        let hit = widget.hitTest(charX, charY, layout.xoff, layout.yoff)
+        if (hit) return {widgetId: id, hit: hit}
+    }
+    return null
+}
+
+_fsh.dispatchLeft = function(widgetId, hit) {
+    if (hit.kind === "add") {
+        if (widgetId === "com.fsh.todo_list") _fsh.openAddTodoDialog()
+        else                                  _fsh.openAddQaDialog()
+        return
+    }
+    // hit.kind === "item"
+    if (widgetId === "com.fsh.todo_list") {
+        _fsh.toggleTodoDone(hit.index)
+    } else {
+        let entry = quickAccessWidget.entries[hit.index]
+        if (entry) _fsh.launchEntry(entry[0], entry[1])
+    }
+}
+
+_fsh.dispatchRight = function(widgetId, hit) {
+    if (hit.kind !== "item") return
+    if (widgetId === "com.fsh.todo_list") _fsh.openEditTodoDialog(hit.index)
+    else                                  _fsh.openEditQaDialog(hit.index)
+}
+
 
 // change graphics mode and check if it's supported
 graphics.setGraphicsMode(3)
@@ -260,29 +631,130 @@ _fsh.drawWallpaper()
 _fsh.drawTitlebar()
 
 
-// TEST
-con.move(2,1);
-print("fSh is very much in-dev! Hit backspace to exit")
+// Load persisted state before the first draw
+_fsh.loadConfig();
+
+// keyEventBuffers (read via sys.peek(-41-i)) holds *raw libGDX keycodes*,
+// not the cooked TSVM scancodes that con.getch() returns. Existing fsh.js
+// already uses 67 for Backspace (libGDX DEL); follow the same scheme here.
+const KEY_ESC    = keysym.ESCAPE
+const KEY_ENTER  = keysym.ENTER
+const KEY_UP     = keysym.UP
+const KEY_DOWN   = keysym.DOWN
+const KEY_LEFT   = keysym.LEFT
+const KEY_RIGHT  = keysym.RIGHT
+const KEY_LSHIFT = keysym.SHIFT_LEFT
+const KEY_RSHIFT = keysym.SHIFT_RIGHT
+
+let prevButtons = 0
+let prevMouseCharX = -1
+let prevMouseCharY = -1
+let keyLatch = {}   // {keycode: true} while the key is held — debounces "just pressed"
 
-// TODO update for events: key down (updates some widgets), timer (updates clock and calendar widgets)
 while (true) {
-    captureUserInput();
-    if (getKeyPushed(0) == 67) break;
+    captureUserInput()
 
-    _fsh.widgets["com.fsh.clock"].draw(25, 3);
-    _fsh.widgets["com.fsh.calendar"].draw(12, 8);
-    _fsh.widgets["com.fsh.todo_list"].draw(10, 17);
-    _fsh.widgets["com.fsh.quick_access"].draw(47, 8);
+    // -- keyboard --
+    if (isKeyDown(KEY_ESC)) break;
 
-    sys.spin();sys.spin()
+    let shiftDown = isKeyDown(KEY_LSHIFT) || isKeyDown(KEY_RSHIFT)
+    let enterPressed = false
+
+    // Edge-detect each navigation key
+    function edge(kc) {
+        let down = isKeyDown(kc)
+        let was  = !!keyLatch[kc]
+        keyLatch[kc] = down
+        return down && !was
+    }
+
+    if (edge(KEY_ENTER)) enterPressed = true;
+    let navUp    = edge(KEY_UP)
+    let navDown  = edge(KEY_DOWN)
+    let navLeft  = edge(KEY_LEFT)
+    let navRight = edge(KEY_RIGHT)
+
+    // -- mouse --
+    // MMIO returns VM-screen pixel coords (origin at the top-left of the framebuffer).
+    // Widget xoff/yoff are passed straight into con.move(y, x), which is 1-indexed, so
+    // we offset by +1 here. Without this the click registers one cell up-and-left from
+    // where the user's pointer is, because pixel 0 = con.move(1, 1).
+    let pos = readMousePos()
+    let charX = (pos[0] / 7  | 0) + 1
+    let charY = (pos[1] / 14 | 0) + 1
+    let mouseMoved = (charX !== prevMouseCharX || charY !== prevMouseCharY)
+    prevMouseCharX = charX
+    prevMouseCharY = charY
+
+    let buttons = readMouseButtons()
+    let leftEdge  = ((buttons & _fsh.MB_LEFT)  !== 0) && ((prevButtons & _fsh.MB_LEFT)  === 0)
+    let rightEdge = ((buttons & _fsh.MB_RIGHT) !== 0) && ((prevButtons & _fsh.MB_RIGHT) === 0)
+    prevButtons = buttons
+
+    // -- focus update --
+    if (navUp || navDown || navLeft || navRight) {
+        if (!_fsh.focus) _fsh.focus = {widgetId: "com.fsh.todo_list", index: 0}
+        if (navUp || navDown) {
+            let layout = _fsh.layouts[_fsh.focus.widgetId]
+            let maxRows = (_fsh.focus.widgetId === "com.fsh.todo_list")
+                ? _fsh.TODO_MAX_ROWS : _fsh.QA_MAX_ROWS
+            let length = (_fsh.focus.widgetId === "com.fsh.todo_list")
+                ? todoWidget.todoList.length : quickAccessWidget.entries.length
+            let maxIdx = Math.min(length, maxRows - 1)
+            let next = _fsh.focus.index + (navDown ? 1 : -1)
+            if (next < 0) next = 0
+            if (next > maxIdx) next = maxIdx
+            _fsh.focus.index = next
+        } else {
+            // Left/right switches widget
+            let other = (_fsh.focus.widgetId === "com.fsh.todo_list")
+                ? "com.fsh.quick_access" : "com.fsh.todo_list"
+            let otherLength = (other === "com.fsh.todo_list")
+                ? todoWidget.todoList.length : quickAccessWidget.entries.length
+            let otherMaxRows = (other === "com.fsh.todo_list")
+                ? _fsh.TODO_MAX_ROWS : _fsh.QA_MAX_ROWS
+            let otherMaxIdx = Math.min(otherLength, otherMaxRows - 1)
+            _fsh.focus = {widgetId: other, index: Math.min(_fsh.focus.index, otherMaxIdx)}
+        }
+    } else if (mouseMoved) {
+        let h = _fsh.findHit(charX, charY)
+        _fsh.focus = h ? {widgetId: h.widgetId, index: h.hit.kind === "add"
+                            ? ((h.widgetId === "com.fsh.todo_list")
+                                ? todoWidget.todoList.length
+                                : quickAccessWidget.entries.length)
+                            : h.hit.index} : null
+    }
+
+    // -- mouse click dispatch --
+    if (leftEdge) {
+        let h = _fsh.findHit(charX, charY)
+        if (h) _fsh.dispatchLeft(h.widgetId, h.hit)
+    } else if (rightEdge) {
+        let h = _fsh.findHit(charX, charY)
+        if (h) _fsh.dispatchRight(h.widgetId, h.hit)
+    }
+
+    // -- keyboard dispatch (synthesise click at focus) --
+    if (enterPressed && _fsh.focus) {
+        let length = (_fsh.focus.widgetId === "com.fsh.todo_list")
+            ? todoWidget.todoList.length : quickAccessWidget.entries.length
+        let hit = (_fsh.focus.index < length)
+            ? {kind: "item", index: _fsh.focus.index}
+            : (_fsh.focus.index === length ? {kind: "add"} : null)
+        if (hit) {
+            if (shiftDown) _fsh.dispatchRight(_fsh.focus.widgetId, hit)
+            else           _fsh.dispatchLeft(_fsh.focus.widgetId, hit)
+        }
+    }
+
+    // -- redraw --
+    _fsh.widgets["com.fsh.clock"].draw(25, 3)
+    _fsh.widgets["com.fsh.calendar"].draw(12, 8)
+    _fsh.widgets["com.fsh.todo_list"].draw(10, 17)
+    _fsh.widgets["com.fsh.quick_access"].draw(47, 8)
+
+    sys.spin(); sys.spin()
 }
 
-con.move(3,1);
-con.color_pair(201,255);
-print("cya!");
-
-let konsht = 3412341241;
-println(konsht);
-
-let pppp = graphics.getCursorYX();
-println(pppp.toString());
+con.reset_graphics()
+con.clear()

assets/disk0/tvdos/TVDOS.SYS

@@ -1114,13 +1114,18 @@ inputwork.repeatCount = 0;
  * where:
  *  "key_down", <key symbol string>, <repeat count>, keycode0, keycode1 .. keycode7
  *  "key_change", <key symbol string (what went up)>, 0, keycode0, keycode1 .. keycode7 (remaining keys that are held down)
- *  "mouse_down", pos-x, pos-y, 1 // yes there's only one mouse button :p
- *  "mouse_up", pos-x, pos-y, 0
- *  "mouse_move", pos-x, pos-y, <button down?>, oldpos-x, oldpos-y
+ *  "mouse_down",  pos-x, pos-y, <button mask: 1=left, 2=right, 4=middle>, keycode0..keycode7
+ *  "mouse_up",    pos-x, pos-y, <button mask of the released button>,    keycode0..keycode7
+ *  "mouse_move",  pos-x, pos-y, <currently-held button mask>, oldpos-x, oldpos-y, keycode0..keycode7
+ *  "mouse_wheel", pos-x, pos-y, <-1 for wheel up, +1 for wheel down>,     keycode0..keycode7
+ *
+ * Button mask values come from MMIO[36] bits 0..2 (terranmon.txt:52-58). The wheel
+ * bits (6, 7) latch in hardware and clear on read, so a one-shot detent fires once.
+ * Every mouse event carries the currently-held key buffer (same shape as key_down)
+ * so handlers can detect modifiers like Shift+wheel via `event.includes(<keysym>)`.
  */
 input.withEvent = function(callback) {
 
-    // TODO mouse event
     function arrayEq(a,b) {
         for (let i = 0; i < a.length; ++i) {
             if (a[i] !== b[i]) return false;
@@ -1141,7 +1146,33 @@ input.withEvent = function(callback) {
 
     sys.poke(-40, 255);
     let keys = [sys.peek(-41),sys.peek(-42),sys.peek(-43),sys.peek(-44),sys.peek(-45),sys.peek(-46),sys.peek(-47),sys.peek(-48)];
-    let mouse = [sys.peek(-33) | (sys.peek(-34) << 8), sys.peek(-35) | (sys.peek(-36) << 8), sys.peek(-37)];
+    let mx = (sys.peek(-33) & 0xFF) | ((sys.peek(-34) & 0xFF) << 8);
+    let my = (sys.peek(-35) & 0xFF) | ((sys.peek(-36) & 0xFF) << 8);
+    let mb = sys.peek(-37) & 0xFF; // bits 0..2 = L/R/M held, bit 6 = wheel up, bit 7 = wheel down
+    let mouse = [mx, my, mb];
+
+    // --- mouse dispatch ---
+    let oldMouse = inputwork.oldMouse;
+    let hasOld   = oldMouse && oldMouse.length === 3;
+    let oldBtns  = hasOld ? (oldMouse[2] & 0x07) : 0;
+    let curBtns  = mb & 0x07;
+    let wheelUp  = (mb & 0x40) !== 0;
+    let wheelDn  = (mb & 0x80) !== 0;
+
+    if (wheelUp) callback(["mouse_wheel", mx, my, -1].concat(keys));
+    if (wheelDn) callback(["mouse_wheel", mx, my,  1].concat(keys));
+
+    let pressed  = curBtns & ~oldBtns;
+    let released = oldBtns & ~curBtns;
+    for (let b = 1; b <= 4; b <<= 1) {
+        if (pressed  & b) callback(["mouse_down", mx, my, b].concat(keys));
+        if (released & b) callback(["mouse_up",   mx, my, b].concat(keys));
+    }
+    if (hasOld && (mx !== oldMouse[0] || my !== oldMouse[1])) {
+        callback(["mouse_move", mx, my, curBtns, oldMouse[0], oldMouse[1]].concat(keys));
+    }
+    // --- end mouse dispatch ---
+
     let keyChanged = !arrayEq(keys, inputwork.oldKeys)
     let keyDiff = arrayDiff(keys, inputwork.oldKeys)
 
@@ -1440,9 +1471,40 @@ try {
     serial.println("Warning: Could not load HSDPA driver: " + e.message)
 }
 
-// Boot script
-serial.println(`TVDOS.SYS initialised on VM ${sys.getVmId()}, running boot script...`);
+// Boot script. The work is split across two files:
+//   \commandrc    -- environment (`set` commands); run in EVERY context.
+//   \AUTOEXEC.BAT -- per-console launch (IME + interactive shell).
+// vtmgr re-evaluates TVDOS.SYS inside each per-VT pane; a pane sets
+// _TVDOS_IS_VT_PANE so it only replays the environment here and leaves the
+// AUTOEXEC launch to vtmgr's pane bootstrap (which avoids recursively
+// spawning vtmgr inside a pane).
+{
+    let cmdsrc = files.open("A:/tvdos/bin/command.js").sread()
+    let runBatch = (path) => eval(`var _BAT=function(exec_args){${cmdsrc}\n};_BAT`)(["", "-c", path])
 
-let cmdfile = files.open("A:/tvdos/bin/command.js")
-eval(`var _AUTOEXEC=function(exec_args){${cmdfile.sread()}\n};` +
-      `_AUTOEXEC`)(["", "-c", "\\AUTOEXEC.BAT"])
+    // Environment first, boot and pane alike. Gives every pane the same
+    // PATH / KEYBOARD / etc. natively, with no env-snapshot replay needed.
+    // \commandrc has no .BAT extension (so command.js's batch-file path,
+    // which keys off the extension, won't pick it up); run it line-by-line.
+    // `set` mutates the shared _TVDOS.variables, so the effect persists across
+    // the per-line shell invocations. Skip blanks and `rem` comments.
+    let rcFile = files.open("A:/commandrc")
+    if (rcFile.exists) {
+        rcFile.sread().split('\n').forEach((line) => {
+            let t = line.trim()
+            if (t.length > 0 && !/^rem(\s|$)/i.test(t)) runBatch(line)
+        })
+    }
+
+    if (typeof _TVDOS_IS_VT_PANE === "undefined" || !_TVDOS_IS_VT_PANE) {
+        serial.println(`TVDOS.SYS initialised on VM ${sys.getVmId()}, running boot script...`);
+        // Boot console: hand the screen to the virtual-console multiplexer.
+        // When it exits (Alt-0), fall through to AUTOEXEC so the console is
+        // never left bare.
+        runBatch("tvdos/sbin/vtmgr")
+        runBatch("\\AUTOEXEC.BAT")
+    }
+    else {
+        serial.println(`TVDOS.SYS re-initialised in VT pane on VM ${sys.getVmId()}`);
+    }
+}

assets/disk0/tvdos/bin/command.js

@@ -30,7 +30,18 @@ function makeHash() {
 const shellID = makeHash()
 
 function print_prompt_text() {
+    // VT pane indicator: shown for VT 2..6, not VT 1 (the default) so the
+    // unmodified prompt is what users see when they never touch virtual
+    // consoles. VT_NUM is set by vtmgr's pane bootstrap.
+    let vtPrefix = ""
+    if (typeof VT_NUM !== "undefined" && VT_NUM > 1) vtPrefix = "[" + VT_NUM + "] "
     if (goFancy) {
+        if (vtPrefix) {
+            con.color_pair(161,253)
+            print(`\u00DD${VT_NUM}`)
+            con.color_pair(253,161)
+            con.addch(16);con.curs_right()
+        }
         con.color_pair(239,161)
         print(" "+CURRENT_DRIVE+":")
         con.color_pair(161,253)
@@ -49,9 +60,9 @@ function print_prompt_text() {
     else {
 //        con.color_pair(253,255)
         if (errorlevel != 0 && errorlevel != "undefined" && errorlevel != undefined)
-            print(CURRENT_DRIVE + ":\\" + shell_pwd.join("\\") + " [" + errorlevel + "]" + PROMPT_TEXT)
+            print(vtPrefix + CURRENT_DRIVE + ":\\" + shell_pwd.join("\\") + " [" + errorlevel + "]" + PROMPT_TEXT)
         else
-            print(CURRENT_DRIVE + ":\\" + shell_pwd.join("\\") + PROMPT_TEXT)
+            print(vtPrefix + CURRENT_DRIVE + ":\\" + shell_pwd.join("\\") + PROMPT_TEXT)
     }
 }
 
@@ -620,6 +631,21 @@ shell.coreutils = {
     },
     panic: function(args) {
         throw Error("Panicking command.js")
+    },
+    chvt: function(args) {
+        // Request a switch to another virtual console. Only meaningful when
+        // running inside a pane spawned by vtmgr (VT_CTRL_ADDR is set by the
+        // pane bootstrap). Outside that environment this is a no-op error.
+        if (args[1] === undefined) { printerrln("Usage: chvt N (1..6)"); return 1 }
+        let n = parseInt(args[1])
+        if (isNaN(n) || n < 1 || n > 6) { printerrln("chvt: N must be in 1..6"); return 1 }
+        if (typeof VT_CTRL_ADDR === "undefined") {
+            printerrln("chvt: not running under vtmgr (no VT context)"); return 1
+        }
+        // CTRL_SWITCH_REQUEST is byte +1 of the shared CTRL area. Dispatcher
+        // picks this up on its next 30 Hz tick and performs the switch.
+        sys.poke(VT_CTRL_ADDR + 1, n)
+        return 0
     }
 }
 // define command aliases here
@@ -636,10 +662,14 @@ shell.coreutils.where = shell.coreutils.which
 Object.freeze(shell.coreutils)
 shell.stdio = {
     out: {
-        print:      function(s) { sys.print(s) },
-        println:    function(s) { if (s === undefined) sys.print("\n"); else sys.print(s+"\n") },
-        printerr:   function(s) { sys.print("\x1B[31m"+s+"\x1B[m") },
-        printerrln: function(s) { if (s === undefined) sys.print("\n"); else sys.print("\x1B[31m"+s+"\x1B[m\n") },
+        // When running inside a vtmgr virtual console, __VT_OUT routes output
+        // to the pane's text-plane buffer instead of the physical GPU (which
+        // the compositor would otherwise overwrite). Outside a VT the hook is
+        // absent and these fall through to sys.print exactly as before.
+        print:      function(s) { if (globalThis.__VT_OUT) globalThis.__VT_OUT.print(s); else sys.print(s) },
+        println:    function(s) { if (globalThis.__VT_OUT) globalThis.__VT_OUT.println(s); else { if (s === undefined) sys.print("\n"); else sys.print(s+"\n") } },
+        printerr:   function(s) { if (globalThis.__VT_OUT) globalThis.__VT_OUT.printerr(s); else sys.print("\x1B[31m"+s+"\x1B[m") },
+        printerrln: function(s) { if (globalThis.__VT_OUT) globalThis.__VT_OUT.printerrln(s); else { if (s === undefined) sys.print("\n"); else sys.print("\x1B[31m"+s+"\x1B[m\n") } },
     },
     pipe: {
         print:      function(s) { if (shell.getPipe() === undefined) throw Error("No pipe opened"); shell.appendToCurrentPipe(s);  },
@@ -955,6 +985,180 @@ shell.removePipe = function() {
 Object.freeze(shell)
 _G.shell = shell
 
+///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+// TAB AUTOCOMPLETION
+//
+// Invoked by TAB at the interactive prompt. Only active when BOTH:
+//   1. wintex.mjs is available (provides the selection popup), AND
+//   2. goFancy == true.
+// One candidate  -> expand immediately (no popup).
+// Many candidates -> wintex popup; user scrolls and selects, or Esc/Cancel to
+//                    discard. The popup over-draws the screen without saving
+//                    what was beneath it, so we snapshot the text plane before
+//                    and copy it back after (the shell can't just redraw like a
+//                    full-screen TUI — there's scrollback above the prompt).
+///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
+
+// Lazily-resolved wintex module. undefined = not probed yet, null = unavailable.
+let _acWin = undefined
+function getAutocompleteWin() {
+    if (_acWin !== undefined) return _acWin
+    _acWin = null
+    try {
+        let w = require("wintex") // resolved through INCLPATH (\tvdos\include\wintex.mjs)
+        if (w && typeof w.showDialog === "function") _acWin = w
+    } catch (e) {
+        debugprintln("command.js > autocomplete: wintex unavailable: " + e)
+    }
+    return _acWin
+}
+
+// List a directory's entries, swallowing any IO error.
+function _acListDir(fullPath) {
+    try {
+        let f = files.open(fullPath)
+        if (!f.exists || !f.isDirectory) return []
+        return f.list() || []
+    } catch (e) { return [] }
+}
+
+// Strip a trailing PATHEXT extension so command names show without ".js" etc.
+function _acStripExt(name) {
+    let lower = name.toLowerCase()
+    let exts = (_TVDOS.variables.PATHEXT || "").split(';').filter(function(e){ return e.length > 0 })
+    for (let i = 0; i < exts.length; i++) {
+        let e = exts[i].toLowerCase()
+        if (lower.endsWith(e)) return name.substring(0, name.length - e.length)
+    }
+    return name
+}
+
+// Candidates for the command position (first word, no path separators):
+// shell built-ins + runnable files found along the current dir, drive root and PATH.
+function _acCommandCandidates(prefix) {
+    let lower = prefix.toLowerCase()
+    let seen = {}
+    let out = []
+    function add(name) {
+        let k = name.toLowerCase()
+        if (seen[k]) return
+        seen[k] = true
+        out.push({ label: name, value: name + ' ', isDir: false })
+    }
+
+    // shell built-ins (and their aliases)
+    Object.keys(shell.coreutils).forEach(function(k) {
+        if (k.toLowerCase().startsWith(lower)) add(k)
+    })
+
+    // runnable files: search the same places shell.execute does, in the same order
+    let exts = (_TVDOS.variables.PATHEXT || "").split(';')
+        .filter(function(e){ return e.length > 0 }).map(function(e){ return e.toLowerCase() })
+    let dirFulls = [shell.resolvePathInput('.').full] // current directory first
+    _TVDOS.getPath().forEach(function(d) {
+        dirFulls.push((d === '' || d === undefined) ? `${CURRENT_DRIVE}:\\` : shell.resolvePathInput(d).full)
+    })
+    dirFulls.forEach(function(full) {
+        _acListDir(full).forEach(function(it) {
+            if (it.isDirectory) return
+            let nameLower = (it.name || '').toLowerCase()
+            if (!exts.some(function(e){ return nameLower.endsWith(e) })) return // only runnables
+            let stripped = _acStripExt(it.name)
+            if (stripped.toLowerCase().startsWith(lower)) add(stripped)
+        })
+    })
+    return out
+}
+
+// Candidates for a path argument. The word may carry a directory prefix
+// (kept verbatim) and a partial basename that we match against the directory.
+function _acPathCandidates(word) {
+    let sepIdx = Math.max(word.lastIndexOf('\\'), word.lastIndexOf('/'))
+    let dirPart, basePart, listArg
+    if (sepIdx >= 0) {
+        dirPart  = word.substring(0, sepIdx + 1) // includes the trailing separator
+        basePart = word.substring(sepIdx + 1)
+        listArg  = dirPart
+    } else {
+        dirPart  = ''
+        basePart = word
+        listArg  = '.'
+    }
+    let resolved = shell.resolvePathInput(listArg)
+    if (resolved === undefined) return []
+    let sep = (dirPart.length > 0 && dirPart.charAt(dirPart.length - 1) === '/') ? '/' : '\\'
+    let lower = basePart.toLowerCase()
+    let out = []
+    _acListDir(resolved.full).forEach(function(it) {
+        let name = it.name || ''
+        if (!name.toLowerCase().startsWith(lower)) return
+        out.push({
+            // directories get a trailing separator so completion can continue into them;
+            // files get a trailing space so the next argument can be typed straight away.
+            label: name + (it.isDirectory ? '\\' : ''),
+            value: dirPart + name + (it.isDirectory ? sep : ' '),
+            isDir: it.isDirectory
+        })
+    })
+    return out
+}
+
+// Work out what is being completed at `caret` within `line`.
+// Returns { wordStart, word, candidates } (candidates sorted by label).
+function computeCompletion(line, caret) {
+    let wordStart = caret
+    while (wordStart > 0 && line.charAt(wordStart - 1) !== ' ') wordStart -= 1
+    let word = line.substring(wordStart, caret)
+    let isFirstWord = (line.substring(0, wordStart).trim().length === 0)
+    let hasPathSep = (word.indexOf('\\') >= 0 || word.indexOf('/') >= 0 || word.indexOf(':') >= 0)
+    let candidates = (isFirstWord && !hasPathSep) ? _acCommandCandidates(word) : _acPathCandidates(word)
+    candidates.sort(function(a, b) { return (a.label < b.label) ? -1 : (a.label > b.label) ? 1 : 0 })
+    return { wordStart: wordStart, word: word, candidates: candidates }
+}
+
+// --- text-plane snapshot/restore (so the popup leaves no artefacts) ---------
+// In a vtmgr pane the shimmed con/print draw into the pane buffer
+// (globalThis.VT_TEXT_PLANE, forward layout); on the physical console they
+// draw into the GPU text area (mapped at getGpuMemBase()-253950). vaddr(0) is
+// that base in either case; sys.memcpy reads/writes it forward-native.
+// NOTE: 7681, not the full 7682-byte text area: relPtrInDev() bounds-checks
+// `from+len` inclusively, so the final byte (bottom-right char cell, never
+// touched by a centred popup) is unreachable by a single memcpy.
+const _AC_TEXTAREA_BYTES = 7681
+let _acTextBase = null
+let _acScratchPtr = 0
+function _acTextAreaBase() {
+    if (_acTextBase === null) {
+        _acTextBase = (typeof globalThis.VT_TEXT_PLANE !== 'undefined')
+            ? globalThis.VT_TEXT_PLANE
+            : (graphics.getGpuMemBase() - 253950)
+    }
+    return _acTextBase
+}
+function _acSnapshotScreen() {
+    if (_acScratchPtr === 0) _acScratchPtr = sys.malloc(_AC_TEXTAREA_BYTES)
+    sys.memcpy(_acTextAreaBase(), _acScratchPtr, _AC_TEXTAREA_BYTES)
+}
+function _acRestoreScreen() {
+    if (_acScratchPtr === 0) return
+    sys.memcpy(_acScratchPtr, _acTextAreaBase(), _AC_TEXTAREA_BYTES)
+}
+
+// Modal popup of candidates. Returns the chosen item, or null if discarded.
+function _acShowPopup(win, candidates) {
+    let res = win.showDialog({
+        title: `Complete (${candidates.length})`,
+        list: {
+            items: candidates,
+            height: Math.min(12, candidates.length),
+            onActivate: function(item, idx, key) { return 'select' }
+        },
+        buttons: [{ label: 'Cancel', action: 'cancel' }]
+    })
+    if (res && res.action === 'select' && res.listItem) return res.listItem
+    return null
+}
+
 ///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
 
 // ensure USERCONFIGPATH directory exists
@@ -1012,23 +1216,133 @@ if (goInteractive) {
         print_prompt_text()
 
         var cmdbuf = ""
+        var caret = 0 // insertion point within cmdbuf, 0..cmdbuf.length
+
+        // Self-contained line editor with a movable caret (so command.js does
+        // NOT depend on wintex being installed). The prompt has just been
+        // printed, so the current cursor marks where the editable text begins.
+        // We track that anchor and rebuild the on-screen line from it, decoding
+        // line-wrap ourselves so the maths holds in both the physical console
+        // and a vtmgr pane (whose con.move CLAMPS x instead of wrapping it).
+        let [baseY, baseX] = con.getyx() // 1-based
+        let termCols = con.getmaxyx()[1]
+
+        // absolute (y,x) on screen for caret index `idx`
+        function caretPos(idx) {
+            let abs = (baseX - 1) + idx
+            return [baseY + ((abs / termCols) | 0), (abs % termCols) + 1]
+        }
+        function gotoCaret() {
+            let [cy, cx] = caretPos(caret)
+            con.move(cy, cx)
+        }
+        // reprint cmdbuf from index `from` to the end, optionally padding with
+        // `clearTrail` blanks to wipe characters left over by a now-shorter
+        // line, then park the hardware cursor back on the caret.
+        function refresh(from, clearTrail) {
+            let [py, px] = caretPos(from)
+            con.move(py, px)
+            print(cmdbuf.substring(from))
+            for (let i = 0; i < clearTrail; i++) print(" ")
+            gotoCaret()
+        }
+        // replace the whole buffer (used by history recall)
+        function setBuf(next) {
+            let oldLen = cmdbuf.length
+            cmdbuf = next
+            caret = cmdbuf.length
+            refresh(0, Math.max(0, oldLen - cmdbuf.length))
+        }
+
+        // Replace the word [wordStart, caret) with `value`, keeping any text to
+        // the right of the caret, then reprint the line from `wordStart`.
+        function applyCompletion(wordStart, value) {
+            let oldLen = cmdbuf.length
+            cmdbuf = cmdbuf.substring(0, wordStart) + value + cmdbuf.substring(caret)
+            caret = wordStart + value.length
+            con.color_pair(shell.usrcfg.textCol, 255)
+            refresh(wordStart, Math.max(0, oldLen - cmdbuf.length))
+        }
+
+        // TAB handler. No-op unless fancy mode is on and wintex is installed.
+        function tryAutocomplete() {
+            if (!goFancy) return
+            let win = getAutocompleteWin()
+            if (!win) return
+
+            let comp = computeCompletion(cmdbuf, caret)
+            let cands = comp.candidates
+            if (cands.length === 0) return
+            if (cands.length === 1) { applyCompletion(comp.wordStart, cands[0].value); return }
+
+            _acSnapshotScreen()
+            let chosen = _acShowPopup(win, cands)
+            _acRestoreScreen()
+
+            // The popup drives input through input.withEvent (physical held-key
+            // state), which bypasses the buffer con.getch reads. Inside a vtmgr
+            // pane the dispatcher keeps draining physical keystrokes into this
+            // pane's input ring the whole time the popup is open, so the navigation
+            // keys (and the closing Enter) would otherwise surface as phantom input
+            // afterwards. Flush them. (On the physical console readKey self-clears,
+            // so this is harmless there.)
+            con.resetkeybuf()
+
+            // The popup hid the caret and clobbered colours; restore the prompt
+            // editing state. The screen content is already back from the snapshot.
+            con.curs_set(1)
+            con.color_pair(shell.usrcfg.textCol, 255)
+            gotoCaret()
+
+            if (chosen) applyCompletion(comp.wordStart, chosen.value)
+        }
 
         while (true) {
             let key = con.getch()
 
             // printable chars
             if (key >= 32 && key <= 126) {
-                var s = String.fromCharCode(key)
-                cmdbuf += s
-                print(s)
+                let s = String.fromCharCode(key)
+                let atEnd = (caret === cmdbuf.length)
+                cmdbuf = cmdbuf.substring(0, caret) + s + cmdbuf.substring(caret)
+                caret += 1
+                if (atEnd) print(s) // fast path: simple append
+                else refresh(caret - 1, 0)
             }
-            // backspace
-            else if (key === con.KEY_BACKSPACE && cmdbuf.length > 0) {
-                cmdbuf = cmdbuf.substring(0, cmdbuf.length - 1)
-                print(String.fromCharCode(key))
+            // TAB: autocomplete (fancy mode + wintex only; otherwise a no-op)
+            else if (key === con.KEY_TAB) {
+                tryAutocomplete()
+            }
+            // backspace: delete the char to the left of the caret
+            else if (key === con.KEY_BACKSPACE && caret > 0) {
+                cmdbuf = cmdbuf.substring(0, caret - 1) + cmdbuf.substring(caret)
+                caret -= 1
+                refresh(caret, 1)
+            }
+            // forward delete: delete the char under the caret
+            else if (key === con.KEY_DELETE && caret < cmdbuf.length) {
+                cmdbuf = cmdbuf.substring(0, caret) + cmdbuf.substring(caret + 1)
+                refresh(caret, 1)
+            }
+            // caret left
+            else if (key === con.KEY_LEFT) {
+                if (caret > 0) { caret -= 1; gotoCaret() }
+            }
+            // caret right
+            else if (key === con.KEY_RIGHT) {
+                if (caret < cmdbuf.length) { caret += 1; gotoCaret() }
+            }
+            // jump to start of line
+            else if (key === con.KEY_HOME) {
+                caret = 0; gotoCaret()
+            }
+            // jump to end of line
+            else if (key === con.KEY_END) {
+                caret = cmdbuf.length; gotoCaret()
             }
             // enter
             else if (key === 10 || key === con.KEY_RETURN) {
+                caret = cmdbuf.length; gotoCaret()
                 println()
 
                 errorlevel = shell.execute(cmdbuf)
@@ -1044,32 +1358,17 @@ if (goInteractive) {
             // up arrow
             else if (key === con.KEY_UP && cmdHistory.length > 0 && cmdHistoryScroll < cmdHistory.length) {
                 cmdHistoryScroll += 1
-
-                // back the cursor in order to type new cmd
-                var x = 0
-                for (x = 0; x < cmdbuf.length; x++) print(String.fromCharCode(8))
-                cmdbuf = cmdHistory[cmdHistory.length - cmdHistoryScroll]
-                // re-type the new command
-                print(cmdbuf)
-
+                setBuf(cmdHistory[cmdHistory.length - cmdHistoryScroll])
             }
             // down arrow
             else if (key === con.KEY_DOWN) {
-                if (cmdHistoryScroll > 0) {
-                    // back the cursor in order to type new cmd
-                    var x = 0
-                    for (x = 0; x < cmdbuf.length; x++) print(String.fromCharCode(8))
-                    cmdbuf = cmdHistory[cmdHistory.length - cmdHistoryScroll]
-                    // re-type the new command
-                    print(cmdbuf)
-
+                if (cmdHistoryScroll > 1) {
                     cmdHistoryScroll -= 1
+                    setBuf(cmdHistory[cmdHistory.length - cmdHistoryScroll])
                 }
-                else {
-                    // back the cursor in order to type new cmd
-                    var x = 0
-                    for (x = 0; x < cmdbuf.length; x++) print(String.fromCharCode(8))
-                    cmdbuf = ""
+                else if (cmdHistoryScroll === 1) {
+                    cmdHistoryScroll = 0
+                    setBuf("")
                 }
             }
         }

assets/disk0/tvdos/bin/playmp2.js

@@ -1,209 +1,122 @@
-const SND_BASE_ADDR = audio.getBaseAddr()
+// playmp2 — MPEG-1/2 Audio Layer II player with the shared playgui visualiser.
+// Usage: playmp2 <file.mp2> [-i]
 
+const SND_BASE_ADDR = audio.getBaseAddr()
 if (!SND_BASE_ADDR) return 10
 
-const MP2_BITRATES = ["???", 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384]
+const MP2_BITRATES     = ["???", 32, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384]
 const MP2_CHANNELMODES = ["Stereo", "Joint", "Dual", "Mono"]
+
 const pcm = require("pcm")
-const interactive = exec_args[2] && exec_args[2].toLowerCase() == "-i"
+const interactive = exec_args[2] && exec_args[2].toLowerCase() === "-i"
+const gui = interactive ? require("playgui") : null
+
 function printdbg(s) { if (0) serial.println(s) }
 
-
 class SequentialFileBuffer {
-
     constructor(path, offset, length) {
         if (Array.isArray(path)) throw Error("arg #1 is path(string), not array")
-
         this.path = path
         this.file = files.open(path)
-
         this.offset = offset || 0
         this.originalOffset = offset
         this.length = length || this.file.size
-
         this.seq = require("seqread")
         this.seq.prepare(path)
     }
-
-    readBytes(size, ptr) {
-        return this.seq.readBytes(size, ptr)
-    }
-
-    readStr(n) {
-        let ptr = this.seq.readBytes(n)
-        let s = ''
-        for (let i = 0; i < n; i++) {
-            if (i >= this.length) break
-            s += String.fromCharCode(sys.peek(ptr + i))
-        }
-        sys.free(ptr)
-        return s
-    }
-
-    unread(diff) {
-        let newSkipLen = this.seq.getReadCount() - diff
-        this.seq.prepare(this.path)
-        this.seq.skip(newSkipLen)
-    }
-
-    rewind() {
-        this.seq.prepare(this.path)
-    }
-
-    seek(p) {
-        this.seq.prepare(this.path)
-        this.seq.skip(p)
-    }
-
-    get byteLength() {
-        return this.length
-    }
-
-    get fileHeader() {
-        return this.seq.fileHeader
-    }
-
-    /*get remaining() {
-        return this.length - this.getReadCount()
-    }*/
+    readBytes(size, ptr) { return this.seq.readBytes(size, ptr) }
+    get fileHeader() { return this.seq.fileHeader }
 }
 
-
-
-
-
-let filebuf = new SequentialFileBuffer(_G.shell.resolvePathInput(exec_args[1]).full)
-const FILE_SIZE = filebuf.length// - 100
-const FRAME_SIZE = audio.mp2GetInitialFrameSize(filebuf.fileHeader)
+const filebuf       = new SequentialFileBuffer(_G.shell.resolvePathInput(exec_args[1]).full)
+const FILE_SIZE     = filebuf.length
+const FRAME_SIZE    = audio.mp2GetInitialFrameSize(filebuf.fileHeader)
 const MEDIA_BITRATE = MP2_BITRATES[filebuf.fileHeader[2] >>> 4]
-const MEDIA_CHANNEL_MODE = MP2_CHANNELMODES[filebuf.fileHeader[3] >>> 6]
+const MEDIA_CHANNEL = MP2_CHANNELMODES[filebuf.fileHeader[3] >>> 6]
 
+// mediaDecodedBin sits at MMIO offset 64 in the audio peripheral and holds
+// 2304 bytes (1152 stereo u8 samples per MP2 frame).  Peripheral memory grows
+// toward 0 so the canonical pointer is SND_BASE_ADDR - 64.
+//
+// IMPORTANT: single-byte sys.peek on this address hits AudioAdapter.peek()
+// which maps the lower offsets to sampleBin, not mediaDecodedBin (the
+// MMIO/Memory-Space split — see CLAUDE.md).  To get the decoded PCM into the
+// visualiser, we sys.memcpy mediaDecodedBin → a RAM scratch buffer; memcpy
+// uses VM.getDev internally which DOES route the MMIO read correctly.
+//
+// VM.getDev's range check on mediaDecodedBin (relPtrInDev) is half-open and
+// won't let us copy the full 2304 bytes — we copy 2302 (one stereo sample
+// short of the frame, invisible at visualiser resolution).
+const MP2_DECODED_ADDR    = SND_BASE_ADDR - 64
+const MP2_VIS_COPY_BYTES  = 2302
+const MP2_VIS_SAMPLE_COUNT = MP2_VIS_COPY_BYTES >> 1   // 1151
+const mp2VisScratch = interactive ? sys.malloc(MP2_VIS_COPY_BYTES) : 0
 
-let bytes_left = FILE_SIZE
+let bytes_left    = FILE_SIZE
 let decodedLength = 0
 
-
-//serial.println(`Frame size: ${FRAME_SIZE}`)
-
-
-con.curs_set(0)
-let [__, CONSOLE_WIDTH] = con.getmaxyx()
-if (interactive) {
-    let [cy, cx] = con.getyx()
-    // file name
-    con.mvaddch(cy, 1)
-    con.prnch(0xC9);con.prnch(0xCD);con.prnch(0xB5)
-    print(filebuf.file.name)
-    con.prnch(0xC6);con.prnch(0xCD)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 26 - filebuf.file.name.length))
-    con.prnch(0xB5)
-    print("Hold Bksp to Exit")
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBB)
-
-    // L R pillar
-    con.prnch(0xBA)
-    con.mvaddch(cy+1, CONSOLE_WIDTH, 0xBA)
-
-    // media info
-    let mediaInfoStr = `MP2 ${MEDIA_CHANNEL_MODE} ${MEDIA_BITRATE}kbps`
-    con.move(cy+2,1)
-    con.prnch(0xC8)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 5 - mediaInfoStr.length))
-    con.prnch(0xB5)
-    print(mediaInfoStr)
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBC)
-
-    con.move(cy+1, 2)
-}
-let [cy, cx] = con.getyx()
-let paintWidth = CONSOLE_WIDTH - 20
-function bytesToSec(i) {
-    // using fixed value: FRAME_SIZE(216) bytes for 36 ms on sampling rate 32000 Hz
-    return i / (FRAME_SIZE * 1000 / bufRealTimeLen)
-}
-function secToReadable(n) {
-    let mins = ''+((n/60)|0)
-    let secs = ''+(n % 60)
-    return `${mins.padStart(2,'0')}:${secs.padStart(2,'0')}`
-}
-function printPlayBar(currently) {
-    if (interactive) {
-        let currently = decodedLength
-        let total = FILE_SIZE
-
-        let currentlySec = Math.round(bytesToSec(currently))
-        let totalSec = Math.round(bytesToSec(total))
-
-        con.move(cy, 3)
-        print(' '.repeat(15))
-        con.move(cy, 3)
-
-        print(`${secToReadable(currentlySec)} / ${secToReadable(totalSec)}`)
-
-        con.move(cy, 17)
-        print(' ')
-        let progressbar = '\x84196u'.repeat(paintWidth + 1)
-        print(progressbar)
-
-        con.mvaddch(cy, 18 + Math.round(paintWidth * (currently / total)), 0xDB)
-    }
-}
-
-
+const bufRealTimeLen = 36   // one MP2 frame at 32 kHz ≈ 36 ms
 
 audio.resetParams(0)
 audio.purgeQueue(0)
 audio.setPcmMode(0)
-audio.setPcmQueueCapacityIndex(0, 2) // queue size is now 8
+audio.setPcmQueueCapacityIndex(0, 2)
 const QUEUE_MAX = audio.getPcmQueueCapacity(0)
 audio.setMasterVolume(0, 255)
 audio.play(0)
-
-
-//let mp2context = audio.mp2Init()
 audio.mp2Init()
 
-// decode frame
-let t1 = sys.nanoTime()
-let bufRealTimeLen = 36
+function bytesToSec(i) { return i / (FRAME_SIZE * 1000 / bufRealTimeLen) }
+
+if (interactive) {
+    const tag   = "MP2"
+    const title = `${filebuf.file.name}  ${MEDIA_CHANNEL} ${MEDIA_BITRATE}kbps`
+    gui.audioInit({ title, tag })
+}
+
 let stopPlay = false
 let errorlevel = 0
 try {
     while (bytes_left > 0 && !stopPlay) {
-
-        if (interactive) {
-            sys.poke(-40, 1)
-            if (sys.peek(-41) == 67) {
-                stopPlay = true
-            }
-        }
-
-        printPlayBar()
-
+        if (interactive && gui.audioIsExitRequested()) { stopPlay = true; break }
 
         filebuf.readBytes(FRAME_SIZE, SND_BASE_ADDR - 2368)
         audio.mp2Decode()
 
+        // After decode, 1152 PCMu8 stereo samples sit in mediaDecodedBin
+        // (MMIO).  Bounce them through RAM so single-byte peek in the
+        // visualiser pipeline can reach them — see MP2_DECODED_ADDR notes.
+        if (interactive) {
+            sys.memcpy(MP2_DECODED_ADDR, mp2VisScratch, MP2_VIS_COPY_BYTES)
+            gui.audioFeedPcm(mp2VisScratch, MP2_VIS_SAMPLE_COUNT)
+        }
+
         if (audio.getPosition(0) >= QUEUE_MAX) {
             while (audio.getPosition(0) >= (QUEUE_MAX >>> 1)) {
-                printdbg(`Queue full, waiting until the queue has some space (${audio.getPosition(0)}/${QUEUE_MAX})`)
+                if (interactive) gui.audioRender()
                 sys.sleep(bufRealTimeLen)
             }
         }
         audio.mp2UploadDecoded(0)
+
+        if (interactive) {
+            gui.audioSetProgress(decodedLength / FILE_SIZE,
+                                 bytesToSec(decodedLength), bytesToSec(FILE_SIZE))
+            gui.audioRender()
+        }
         sys.sleep(10)
 
-
-
-        bytes_left -= FRAME_SIZE
+        bytes_left    -= FRAME_SIZE
         decodedLength += FRAME_SIZE
     }
-}
-catch (e) {
+} catch (e) {
     printerrln(e)
     errorlevel = 1
-}
-finally {
+} finally {
+    if (interactive) {
+        if (mp2VisScratch) sys.free(mp2VisScratch)
+        gui.audioClose()
+    }
 }
 
-return errorlevel
+return errorlevel

assets/disk0/tvdos/bin/playpcm.js

@@ -1,196 +1,81 @@
-// usage: playpcm audiofile.pcm [/i]
-let fileeeee = files.open(_G.shell.resolvePathInput(exec_args[1]).full)
-let filename = fileeeee.fullPath
-function printdbg(s) { if (0) serial.println(s) }
+// playpcm — raw PCMu8 stereo player with the shared playgui visualiser.
+// Usage: playpcm <file.pcm> [-i]
 
-const interactive = exec_args[2] && exec_args[2].toLowerCase() == "-i"
-const pcm = require("pcm")
-const FILE_SIZE = files.open(filename).size
-
-
-
-function printComments() {
-    for (const [key, value] of Object.entries(comments)) {
-        printdbg(`${key}: ${value}`)
-    }
-}
-
-function GCD(a, b) {
-    a = Math.abs(a)
-    b = Math.abs(b)
-    if (b > a) {var temp = a; a = b; b = temp}
-    while (true) {
-        if (b == 0) return a
-        a %= b
-        if (a == 0) return b
-        b %= a
-    }
-}
-
-function LCM(a, b) {
-    return (!a || !b) ? 0 : Math.abs((a * b) / GCD(a, b))
-}
-
-
-
-//println("Reading...")
-//serial.println("!!! READING")
+const fileHandle = files.open(_G.shell.resolvePathInput(exec_args[1]).full)
+const filePath   = fileHandle.fullPath
 
+const interactive = exec_args[2] && exec_args[2].toLowerCase() === "-i"
+const pcm     = require("pcm")
 const seqread = require("seqread")
-seqread.prepare(filename)
-
-
-
-
+const gui     = interactive ? require("playgui") : null
 
+const FILE_SIZE = files.open(filePath).size
 
 let BLOCK_SIZE = 4096
-let INFILE_BLOCK_SIZE = BLOCK_SIZE
-const QUEUE_MAX = 8 // according to the spec
+const INFILE_BLOCK_SIZE = BLOCK_SIZE
+const QUEUE_MAX = 8
 
-let nChannels = 2
-let samplingRate = pcm.HW_SAMPLING_RATE;
-let blockSize = 2;
-let bitsPerSample = 8;
-let byterate = 2*samplingRate;
-let comments = {};
-let readPtr = undefined
-let decodePtr = undefined
+const samplingRate = pcm.HW_SAMPLING_RATE
+const byterate     = 2 * samplingRate
 
-function bytesToSec(i) {
-    return i / byterate
-}
-function secToReadable(n) {
-    let mins = ''+((n/60)|0)
-    let secs = ''+(n % 60)
-    return `${mins.padStart(2,'0')}:${secs.padStart(2,'0')}`
-}
-
-let stopPlay = false
-con.curs_set(0)
-let [__, CONSOLE_WIDTH] = con.getmaxyx()
-if (interactive) {
-    let [cy, cx] = con.getyx()
-    // file name
-    con.mvaddch(cy, 1)
-    con.prnch(0xC9);con.prnch(0xCD);con.prnch(0xB5)
-    print(fileeeee.name)
-    con.prnch(0xC6);con.prnch(0xCD)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 26 - fileeeee.name.length))
-    con.prnch(0xB5)
-    print("Hold Bksp to Exit")
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBB)
-
-    // L R pillar
-    con.prnch(0xBA)
-    con.mvaddch(cy+1, CONSOLE_WIDTH, 0xBA)
-
-    // media info
-    let mediaInfoStr = `Raw PCM 512kbps`
-    con.move(cy+2,1)
-    con.prnch(0xC8)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 5 - mediaInfoStr.length))
-    con.prnch(0xB5)
-    print(mediaInfoStr)
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBC)
-
-    con.move(cy+1, 2)
-}
-let [cy, cx] = con.getyx()
-let paintWidth = CONSOLE_WIDTH - 20
-// read chunks loop
-readPtr = sys.malloc(BLOCK_SIZE * bitsPerSample / 8)
-decodePtr = sys.malloc(BLOCK_SIZE * pcm.HW_SAMPLING_RATE / samplingRate)
+function bytesToSec(i) { return i / byterate }
 
+seqread.prepare(filePath)
 
+const readPtr = sys.malloc(BLOCK_SIZE)
 audio.resetParams(0)
 audio.purgeQueue(0)
 audio.setPcmMode(0)
 audio.setMasterVolume(0, 255)
 
-let readLength = 1
-
-function printPlayBar() {
-    if (interactive) {
-        let currently = seqread.getReadCount()
-        let total = FILE_SIZE
-
-        let currentlySec = Math.round(bytesToSec(currently))
-        let totalSec = Math.round(bytesToSec(total))
-
-        con.move(cy, 3)
-        print(' '.repeat(15))
-        con.move(cy, 3)
-
-        print(`${secToReadable(currentlySec)} / ${secToReadable(totalSec)}`)
-
-        con.move(cy, 17)
-        print(' ')
-        let progressbar = '\x84196u'.repeat(paintWidth + 1)
-        print(progressbar)
-
-        con.mvaddch(cy, 18 + Math.round(paintWidth * (currently / total)), 0xDB)
-    }
+if (interactive) {
+    gui.audioInit({
+        title: `${fileHandle.name}  Raw PCM 32kHz Stereo`,
+        tag: "PCM"
+    })
 }
+
+let stopPlay = false
 let errorlevel = 0
+let readLength = 1
 try {
-while (!stopPlay && seqread.getReadCount() < FILE_SIZE && readLength > 0) {
-    if (interactive) {
-        sys.poke(-40, 1)
-        if (sys.peek(-41) == 67) {
-            stopPlay = true
-        }
-    }
+    while (!stopPlay && seqread.getReadCount() < FILE_SIZE && readLength > 0) {
+        if (interactive && gui.audioIsExitRequested()) { stopPlay = true; break }
 
+        const queueSize = audio.getPosition(0)
+        if (queueSize <= 1) {
+            for (let repeat = QUEUE_MAX - queueSize; repeat > 0; repeat--) {
+                const remainingBytes = FILE_SIZE - seqread.getReadCount()
+                readLength = (remainingBytes < INFILE_BLOCK_SIZE) ? remainingBytes : INFILE_BLOCK_SIZE
+                if (readLength <= 0) break
 
-    let queueSize = audio.getPosition(0)
-    if (queueSize <= 1) {
+                seqread.readBytes(readLength, readPtr)
 
-        printPlayBar()
+                // Raw PCMu8 stereo — sampleCount = bytes / 2.
+                if (interactive) gui.audioFeedPcm(readPtr, readLength >> 1)
 
-        // upload four samples for lag-safely
-        for (let repeat = QUEUE_MAX - queueSize; repeat > 0; repeat--) {
-            let remainingBytes = FILE_SIZE - seqread.getReadCount()
+                audio.putPcmDataByPtr(0, readPtr, readLength, 0)
+                audio.setSampleUploadLength(0, readLength)
+                audio.startSampleUpload(0)
 
-            readLength = (remainingBytes < INFILE_BLOCK_SIZE) ? remainingBytes : INFILE_BLOCK_SIZE
-            if (readLength <= 0) {
-                printdbg(`readLength = ${readLength}`)
-                break
+                if (repeat > 1) sys.sleep(10)
             }
-
-            printdbg(`offset: ${seqread.getReadCount()}/${FILE_SIZE}; readLength: ${readLength}`)
-
-            seqread.readBytes(readLength, readPtr)
-
-            audio.putPcmDataByPtr(0, readPtr, readLength, 0)
-            audio.setSampleUploadLength(0, readLength)
-            audio.startSampleUpload(0)
-
-
-            if (repeat > 1) sys.sleep(10)
-
-            printPlayBar()
+            audio.play(0)
         }
 
-        audio.play(0)
+        if (interactive) {
+            const cur = seqread.getReadCount()
+            gui.audioSetProgress(cur / FILE_SIZE, bytesToSec(cur), bytesToSec(FILE_SIZE))
+            gui.audioRender()
+        }
+        sys.sleep(10)
     }
-
-    let remainingBytes = FILE_SIZE - seqread.getReadCount()
-    printdbg(`readLength = ${readLength}; remainingBytes2 = ${remainingBytes}; seqread.getReadCount() = ${seqread.getReadCount()};`)
-
-
-    sys.sleep(10)
-}
-}
-catch (e) {
+} catch (e) {
     printerrln(e)
     errorlevel = 1
-}
-finally {
-    //audio.stop(0)
+} finally {
     if (readPtr !== undefined) sys.free(readPtr)
-    if (decodePtr !== undefined) sys.free(decodePtr)
+    if (interactive) gui.audioClose()
 }
 
 return errorlevel
-

assets/disk0/tvdos/bin/playtad.js

@@ -1,114 +1,66 @@
+// playtad — TAD (TSVM Advanced Audio) player with the shared playgui visualiser.
+// Usage: playtad <file.tad> [-i | -d]
+//   -i   Interactive mode (visualiser + progress bar; hold Backspace to exit)
+//   -d   Dump mode (print the first three chunks to serial for debugging)
+
 const SND_BASE_ADDR = audio.getBaseAddr()
-const SND_MEM_ADDR = audio.getMemAddr()
-// tadInputBin lives at audio-local offset 917504 and tadDecodedBin at 983040
-// (post-bef85f6 memory map; the old 262144 offset now hits the enlarged sampleBin).
-const TAD_INPUT_ADDR = SND_MEM_ADDR - 917504  // TAD input buffer (matches TAV packet 0x24)
-const TAD_DECODED_ADDR = SND_MEM_ADDR - 983040  // TAD decoded buffer
+const SND_MEM_ADDR  = audio.getMemAddr()
+// tadInputBin at offset 917504, tadDecodedBin at 983040.  Both addressed via
+// negative pointers — peripheral memory grows toward 0.
+const TAD_INPUT_ADDR   = SND_MEM_ADDR - 917504
+const TAD_DECODED_ADDR = SND_MEM_ADDR - 983040
 
 if (!SND_BASE_ADDR) return 10
 
-// Check for help flag or missing arguments
-if (!exec_args[1] || exec_args[1] == "-h" || exec_args[1] == "--help") {
-    serial.println("Usage: playtad <file.tad> [-i | -d] [quality]")
-    serial.println("  -i         Interactive mode (progress bar, press Backspace to exit)")
-    serial.println("  -d         Dump mode (show first 3 chunks with payload hex and decoded samples)")
-    serial.println("")
-    serial.println("Examples:")
-    serial.println("  playtad audio.tad -i        # Play with progress bar")
-    serial.println("  playtad audio.tad -d        # Dump first 3 chunks for debugging")
+if (!exec_args[1] || exec_args[1] === "-h" || exec_args[1] === "--help") {
+    serial.println("Usage: playtad <file.tad> [-i | -d]")
+    serial.println("  -i  Interactive mode (visualiser + progress bar)")
+    serial.println("  -d  Dump first three chunks for debugging")
     return 0
 }
 
-const pcm = require("pcm")
-const interactive = exec_args[2] && exec_args[2].toLowerCase() == "-i"
-const dumpCoeffs = exec_args[2] && exec_args[2].toLowerCase() == "-d"
-
-function printdbg(s) { if (0) serial.println(s) }
-
+const interactive = exec_args[2] && exec_args[2].toLowerCase() === "-i"
+const dumpCoeffs  = exec_args[2] && exec_args[2].toLowerCase() === "-d"
+const gui = interactive ? require("playgui") : null
 
 class SequentialFileBuffer {
-
-    constructor(path, offset, length) {
+    constructor(path) {
         if (Array.isArray(path)) throw Error("arg #1 is path(string), not array")
-
         this.path = path
         this.file = files.open(path)
-
-        this.offset = offset || 0
-        this.originalOffset = offset
-        this.length = length || this.file.size
-
+        this.length = this.file.size
         this.seq = require("seqread")
         this.seq.prepare(path)
     }
-
-    readBytes(size, ptr) {
-        return this.seq.readBytes(size, ptr)
-    }
-
+    readBytes(size, ptr) { return this.seq.readBytes(size, ptr) }
     readByte() {
-        let ptr = this.seq.readBytes(1)
-        let val = sys.peek(ptr)
+        const ptr = this.seq.readBytes(1)
+        const val = sys.peek(ptr)
         sys.free(ptr)
         return val
     }
-
     readShort() {
-        let ptr = this.seq.readBytes(2)
-        let val = sys.peek(ptr) | (sys.peek(ptr + 1) << 8)
+        const ptr = this.seq.readBytes(2)
+        const val = sys.peek(ptr) | (sys.peek(ptr + 1) << 8)
         sys.free(ptr)
         return val
     }
-
     readInt() {
-        let ptr = this.seq.readBytes(4)
-        let val = sys.peek(ptr) | (sys.peek(ptr + 1) << 8) | (sys.peek(ptr + 2) << 16) | (sys.peek(ptr + 3) << 24)
+        const ptr = this.seq.readBytes(4)
+        const val = sys.peek(ptr) | (sys.peek(ptr + 1) << 8) | (sys.peek(ptr + 2) << 16) | (sys.peek(ptr + 3) << 24)
         sys.free(ptr)
         return val
     }
-
-    readStr(n) {
-        let ptr = this.seq.readBytes(n)
-        let s = ''
-        for (let i = 0; i < n; i++) {
-            if (i >= this.length) break
-            s += String.fromCharCode(sys.peek(ptr + i))
-        }
-        sys.free(ptr)
-        return s
-    }
-
     unread(diff) {
-        let newSkipLen = this.seq.getReadCount() - diff
+        const newSkipLen = this.seq.getReadCount() - diff
         this.seq.prepare(this.path)
         this.seq.skip(newSkipLen)
     }
-
-    rewind() {
-        this.seq.prepare(this.path)
-    }
-
-    seek(p) {
-        this.seq.prepare(this.path)
-        this.seq.skip(p)
-    }
-
-    get byteLength() {
-        return this.length
-    }
-
-    get fileHeader() {
-        return this.seq.fileHeader
-    }
-
-    getReadCount() {
-        return this.seq.getReadCount()
-    }
+    rewind() { this.seq.prepare(this.path) }
+    getReadCount() { return this.seq.getReadCount() }
 }
 
-
-// Read TAD chunk header to determine format
-let filebuf = new SequentialFileBuffer(_G.shell.resolvePathInput(exec_args[1]).full)
+const filebuf   = new SequentialFileBuffer(_G.shell.resolvePathInput(exec_args[1]).full)
 const FILE_SIZE = filebuf.length
 
 if (FILE_SIZE < 7) {
@@ -116,12 +68,12 @@ if (FILE_SIZE < 7) {
     return 1
 }
 
-// Read first chunk header (standalone TAD format: no TAV wrapper)
-let firstSampleCount = filebuf.readShort()
-let firstMaxIndex = filebuf.readByte()
-let firstPayloadSize = filebuf.readInt()
+// Peek the first chunk header so we know the chunk size for the rough bytes-
+// to-seconds conversion shown in the progress bar.
+const firstSampleCount = filebuf.readShort()
+const firstMaxIndex    = filebuf.readByte()
+const firstPayloadSize = filebuf.readInt()
 
-// Validate first chunk
 if (firstSampleCount < 0 || firstSampleCount > 65536) {
     serial.println(`ERROR: Invalid sample count ${firstSampleCount}. File may be corrupted.`)
     return 1
@@ -135,148 +87,68 @@ if (firstPayloadSize < 1 || firstPayloadSize > 65536) {
     return 1
 }
 
-// Rewind to start
 filebuf.rewind()
 
-// Calculate approximate frame info
-const AVG_CHUNK_SIZE = 7 + firstPayloadSize  // TAD header (2+1+4) + payload
-const SAMPLE_RATE = 32000
-const bufRealTimeLen = Math.floor((firstSampleCount / SAMPLE_RATE) * 1000)  // milliseconds per chunk
+const AVG_CHUNK_SIZE = 7 + firstPayloadSize
+const SAMPLE_RATE    = 32000
+const bufRealTimeLen = Math.floor((firstSampleCount / SAMPLE_RATE) * 1000)
 
 if (dumpCoeffs) {
     serial.println(`TAD Coefficient Dump Mode`)
     serial.println(`File: ${filebuf.file.name}`)
-    serial.println(`First chunk header:`)
-    serial.println(`  Sample Count: ${firstSampleCount}`)
-    serial.println(`  Max Index: ${firstMaxIndex}`)
-    serial.println(`  Payload Size: ${firstPayloadSize} bytes`)
+    serial.println(`First chunk: ${firstSampleCount} samples, Q${firstMaxIndex}, ${firstPayloadSize} bytes payload`)
     serial.println(`Chunk Duration: ${bufRealTimeLen} ms`)
     serial.println(``)
 }
 
-
-let bytes_left = FILE_SIZE
+let bytes_left    = FILE_SIZE
 let decodedLength = 0
-let chunkNumber = 0
-
-
-con.curs_set(0)
-let [__, CONSOLE_WIDTH] = con.getmaxyx()
-if (interactive) {
-    let [cy, cx] = con.getyx()
-    // file name
-    con.mvaddch(cy, 1)
-    con.prnch(0xC9);con.prnch(0xCD);con.prnch(0xB5)
-    print(filebuf.file.name)
-    con.prnch(0xC6);con.prnch(0xCD)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 26 - filebuf.file.name.length))
-    con.prnch(0xB5)
-    print("Hold Bksp to Exit")
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBB)
-
-    // L R pillar
-    con.prnch(0xBA)
-    con.mvaddch(cy+1, CONSOLE_WIDTH, 0xBA)
-
-    // media info
-    let mediaInfoStr = `TAD Q${firstMaxIndex} ${SAMPLE_RATE/1000}kHz`
-    con.move(cy+2,1)
-    con.prnch(0xC8)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 5 - mediaInfoStr.length))
-    con.prnch(0xB5)
-    print(mediaInfoStr)
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBC)
-
-    con.move(cy+1, 2)
-}
-let [cy, cx] = con.getyx()
-let paintWidth = CONSOLE_WIDTH - 20
+let chunkNumber   = 0
 
 function bytesToSec(i) {
-    // Approximate: use first chunk's ratio
     return Math.round((i / FILE_SIZE) * (FILE_SIZE / AVG_CHUNK_SIZE) * (bufRealTimeLen / 1000))
 }
 
-function secToReadable(n) {
-    let mins = ''+((n/60)|0)
-    let secs = ''+(n % 60)
-    return `${mins.padStart(2,'0')}:${secs.padStart(2,'0')}`
-}
-
-function printPlayBar() {
-    if (interactive) {
-        let currently = decodedLength
-        let total = FILE_SIZE
-
-        let currentlySec = bytesToSec(currently)
-        let totalSec = bytesToSec(total)
-
-        con.move(cy, 3)
-        print(' '.repeat(15))
-        con.move(cy, 3)
-
-        print(`${secToReadable(currentlySec)} / ${secToReadable(totalSec)}`)
-
-        con.move(cy, 17)
-        print(' ')
-        let progressbar = '\x84196u'.repeat(paintWidth + 1)
-        print(progressbar)
-
-        con.mvaddch(cy, 18 + Math.round(paintWidth * (currently / total)), 0xDB)
-    }
-}
-
-
 audio.resetParams(0)
 audio.purgeQueue(0)
 audio.setPcmMode(0)
-audio.setPcmQueueCapacityIndex(0, 2) // queue size is now 8
+audio.setPcmQueueCapacityIndex(0, 2)
 const QUEUE_MAX = audio.getPcmQueueCapacity(0)
 audio.setMasterVolume(0, 255)
 audio.play(0)
 
+if (interactive) {
+    gui.audioInit({
+        title: `${filebuf.file.name}  TAD Q${firstMaxIndex} ${SAMPLE_RATE/1000}kHz`,
+        tag: "TAD"
+    })
+}
 
 let stopPlay = false
 let errorlevel = 0
-
 try {
     while (bytes_left > 0 && !stopPlay) {
+        if (interactive && gui.audioIsExitRequested()) { stopPlay = true; break }
 
-        if (interactive) {
-            sys.poke(-40, 1)
-            if (sys.peek(-41) == 67) {  // Backspace key
-                stopPlay = true
-            }
-        }
+        const sampleCount = filebuf.readShort()
+        const maxIndex    = filebuf.readByte()
+        const payloadSize = filebuf.readInt()
 
-        printPlayBar()
-
-        // Read TAD chunk header (standalone TAD format)
-        // Format: [sample_count][max_index][payload_size][payload]
-        let sampleCount = filebuf.readShort()
-        let maxIndex = filebuf.readByte()
-        let payloadSize = filebuf.readInt()
-
-        // Validate every chunk (not just first one)
         if (sampleCount < 0 || sampleCount > 65536) {
-            serial.println(`ERROR: Chunk ${chunkNumber}: Invalid sample count ${sampleCount}. File may be corrupted.`)
-            errorlevel = 1
-            break
+            serial.println(`ERROR: Chunk ${chunkNumber}: Invalid sample count ${sampleCount}.`)
+            errorlevel = 1; break
         }
         if (maxIndex < 0 || maxIndex > 255) {
-            serial.println(`ERROR: Chunk ${chunkNumber}: Invalid max index ${maxIndex}. File may be corrupted.`)
-            errorlevel = 1
-            break
+            serial.println(`ERROR: Chunk ${chunkNumber}: Invalid max index ${maxIndex}.`)
+            errorlevel = 1; break
         }
         if (payloadSize < 1 || payloadSize > 65536) {
-            serial.println(`ERROR: Chunk ${chunkNumber}: Invalid payload size ${payloadSize}. File may be corrupted.`)
-            errorlevel = 1
-            break
+            serial.println(`ERROR: Chunk ${chunkNumber}: Invalid payload size ${payloadSize}.`)
+            errorlevel = 1; break
         }
         if (payloadSize + 7 > bytes_left) {
-            serial.println(`ERROR: Chunk ${chunkNumber}: Chunk size ${payloadSize + 7} exceeds remaining file size ${bytes_left}`)
-            errorlevel = 1
-            break
+            serial.println(`ERROR: Chunk ${chunkNumber}: Chunk size exceeds remaining file size.`)
+            errorlevel = 1; break
         }
 
         if (dumpCoeffs && chunkNumber < 3) {
@@ -284,80 +156,59 @@ try {
             serial.println(`  Sample Count: ${sampleCount}`)
             serial.println(`  Max Index: ${maxIndex}`)
             serial.println(`  Payload Size: ${payloadSize} bytes`)
-            serial.println(`  Bytes remaining in file: ${bytes_left}`)
         }
 
-        // Rewind 7 bytes to re-read the header along with payload
-        // This allows reading the complete chunk (header + payload) in one call
+        // Read entire chunk (header + payload) into TAD input buffer.
         filebuf.unread(7)
+        filebuf.readBytes(7 + payloadSize, TAD_INPUT_ADDR)
 
-        // Read entire chunk (header + payload) to TAD input buffer
-        // This matches TAV's approach for packet 0x24
-        let totalChunkSize = 7 + payloadSize
-        filebuf.readBytes(totalChunkSize, TAD_INPUT_ADDR)
-
-        if (dumpCoeffs && chunkNumber < 3) {
-            // Dump first 32 bytes of compressed payload (skip 7-byte header)
-            serial.print(`  Compressed data (first 32 bytes): `)
-            for (let i = 0; i < Math.min(32, payloadSize); i++) {
-                let b = sys.peek(TAD_INPUT_ADDR + 7 + i)
-                serial.print(`${(b & 0xFF).toString(16).padStart(2, '0')} `)
-            }
-            serial.println('')
-        }
-
-        // Decode TAD chunk
         audio.tadDecode()
-
-        if (dumpCoeffs && chunkNumber < 3) {
-            // After decoding, the decoded PCMu8 samples are in tadDecodedBin
-            serial.println(`  Decoded ${sampleCount} samples`)
-
-            // Dump first 16 decoded samples (PCMu8 stereo interleaved)
-            serial.print(`  Decoded (first 16 L samples): `)
-            for (let i = 0; i < 16; i++) {
-                serial.print(`${sys.peek(TAD_DECODED_ADDR + i * 2) & 0xFF} `)
-            }
-            serial.println('')
-            serial.print(`  Decoded (first 16 R samples): `)
-            for (let i = 0; i < 16; i++) {
-                serial.print(`${sys.peek(TAD_DECODED_ADDR + i * 2 + 1) & 0xFF} `)
-            }
-            serial.println('')
-            serial.println('')
-        }
-
-        // Upload decoded audio to queue
         audio.tadUploadDecoded(0, sampleCount)
+        // After upload tadDecodedBin still holds the chunk until the next
+        // tadDecode call, so it's safe to keep slicing samples out of it
+        // during the playback wait below.
 
         if (!dumpCoeffs) {
-            // Sleep for the duration of the audio chunk to pace playback
-            // This prevents uploading everything at once
-            sys.sleep(bufRealTimeLen)
+            // TAD chunks are typically 1 s long, so feeding the visualiser
+            // once would freeze it for ~1 s.  Walk the chunk in 2048-sample
+            // slices (~64 ms each at 32 kHz) so the wavescope and XY-scope
+            // stay in step with what the audio engine is actually playing.
+            const chunkMs       = Math.floor((sampleCount / SAMPLE_RATE) * 1000)
+            const TAD_VIS_SLICE = 2048
+            if (interactive) {
+                gui.audioSetProgress(decodedLength / FILE_SIZE,
+                                     bytesToSec(decodedLength), bytesToSec(FILE_SIZE))
+                let sliceOff = 0
+                while (sliceOff < sampleCount && !stopPlay) {
+                    if (gui.audioIsExitRequested()) { stopPlay = true; break }
+                    const sliceN = Math.min(TAD_VIS_SLICE, sampleCount - sliceOff)
+                    // tadDecodedBin is negative-addressed: sample i sits at
+                    // TAD_DECODED_ADDR - i*2.  audioFeedPcm flips the read
+                    // direction for negative ptrs internally.
+                    gui.audioFeedPcm(TAD_DECODED_ADDR - sliceOff * 2, sliceN)
+                    gui.audioRender()
+                    sys.sleep(Math.floor((sliceN / SAMPLE_RATE) * 1000))
+                    sliceOff += sliceN
+                }
+            } else {
+                sys.sleep(chunkMs)
+            }
         }
 
-        // Chunk size = header (7 bytes) + payload
-        let chunkSize = 7 + payloadSize
-        bytes_left -= chunkSize
+        const chunkSize = 7 + payloadSize
+        bytes_left    -= chunkSize
         decodedLength += chunkSize
         chunkNumber++
 
-        // Limit coefficient dump to first 3 chunks
         if (dumpCoeffs && chunkNumber >= 3) {
             serial.println(`... (remaining chunks omitted)`)
-            // Keep playing but don't dump more
         }
     }
-}
-catch (e) {
+} catch (e) {
     printerrln(e)
     errorlevel = 1
-}
-finally {
-    if (interactive) {
-        con.move(cy + 3, 1)
-        con.curs_set(1)
-    }
+} finally {
+    if (interactive) gui.audioClose()
 }
 
 return errorlevel

assets/disk0/tvdos/bin/playtaud.js

@@ -512,7 +512,6 @@ function drawFrame() {
     colour(COL_LABEL, COL_BG)
     mvtext(ROW_TOP_BORDER, 4, ' TAUD ')
     colour(COL_DIM, COL_BG)
-    mvtext(ROW_TOP_BORDER, COLS - 7, ' v0.1 ')
 
     // Bottom border + exit hint.
     colour(COL_BORDER, COL_BG)
@@ -725,7 +724,7 @@ function spawnEventsForRow(cueIdx, rowIdx) {
             note: note, pan: pan,
             ageFrames: 0,
             peakVol: 0,
-            glyphSeed: (cueIdx * 64 + rowIdx + v * 13) & 0xFFFF
+            glyphSeed: (cueIdx * 64 + rowIdx + v * 1280) & 0xFFFF
         }
         voiceLastNote[v] = note
         voiceLastInst[v] = effInst

assets/disk0/tvdos/bin/playwav.js

@@ -1,329 +1,189 @@
-// usage: playwav audiofile.wav [/i]
-let fileeeee = files.open(_G.shell.resolvePathInput(exec_args[1]).full)
-let filename = fileeeee.fullPath
+// playwav — WAV (LPCM/ADPCM) player with the shared playgui visualiser.
+// Usage: playwav <file.wav> [-i]
+
+const fileHandle = files.open(_G.shell.resolvePathInput(exec_args[1]).full)
+const filePath   = fileHandle.fullPath
+
+const WAV_FORMATS  = ["LPCM", "ADPCM"]
+const WAV_CHANNELS = ["Mono", "Stereo", "3ch", "Quad", "4.1", "5.1", "6.1", "7.1"]
+const interactive  = exec_args[2] && exec_args[2].toLowerCase() === "-i"
+
+const seqread = require("seqread")
+const pcm     = require("pcm")
+const gui     = interactive ? require("playgui") : null
+
 function printdbg(s) { if (0) serial.println(s) }
 
-const WAV_FORMATS = ["LPCM", "ADPCM"]
-const WAV_CHANNELS = ["Mono", "Stereo", "3ch", "Quad", "4.1", "5.1", "6.1", "7.1"]
-const interactive = exec_args[2] && exec_args[2].toLowerCase() == "-i"
-const seqread = require("seqread")
-const pcm = require("pcm")
-
-
-
-function printComments() {
-    for (const [key, value] of Object.entries(comments)) {
-        printdbg(`Wave Comment ${key}: ${value}`)
-    }
-}
-
 function GCD(a, b) {
-    a = Math.abs(a)
-    b = Math.abs(b)
-    if (b > a) {var temp = a; a = b; b = temp}
+    a = Math.abs(a); b = Math.abs(b)
+    if (b > a) { const t = a; a = b; b = t }
     while (true) {
-        if (b == 0) return a
+        if (b === 0) return a
         a %= b
-        if (a == 0) return b
+        if (a === 0) return b
         b %= a
     }
 }
+function LCM(a, b) { return (!a || !b) ? 0 : Math.abs((a * b) / GCD(a, b)) }
 
-function LCM(a, b) {
-    return (!a || !b) ? 0 : Math.abs((a * b) / GCD(a, b))
-}
-
-
-
-//println("Reading...")
-//serial.println("!!! READING")
-
-seqread.prepare(filename)
-
-
-
-
-// decode header
-if (seqread.readFourCC() != "RIFF") {
-    throw Error("File not RIFF")
-}
-
-const FILE_SIZE = seqread.readInt() // size from "WAVEfmt"
-
-if (seqread.readFourCC() != "WAVE") {
-    throw Error("File is RIFF but not WAVE")
-}
+seqread.prepare(filePath)
+if (seqread.readFourCC() !== "RIFF") throw Error("File not RIFF")
+const FILE_SIZE = seqread.readInt()
+if (seqread.readFourCC() !== "WAVE") throw Error("File is RIFF but not WAVE")
 
 let BLOCK_SIZE = 0
 let INFILE_BLOCK_SIZE = 0
-const QUEUE_MAX = 8 // according to the spec
+const QUEUE_MAX = 8
 
-let pcmType;
-let nChannels;
-let samplingRate;
-let blockSize;
-let bitsPerSample;
-let byterate;
-let comments = {};
-let adpcmSamplesPerBlock;
-let readPtr = undefined
-let decodePtr = undefined
+let pcmType, nChannels, samplingRate, blockSize, bitsPerSample, byterate
+let adpcmSamplesPerBlock
+let readPtr, decodePtr
+const comments = {}
 
 function bytesToSec(i) {
     if (adpcmSamplesPerBlock) {
-        let newByteRate = samplingRate
-        let generatedSamples = i / blockSize * adpcmSamplesPerBlock
-        return generatedSamples / newByteRate
-    }
-    else {
-        return i / byterate
+        const generatedSamples = i / blockSize * adpcmSamplesPerBlock
+        return generatedSamples / samplingRate
     }
+    return i / byterate
 }
-function secToReadable(n) {
-    let mins = ''+((n/60)|0)
-    let secs = ''+(n % 60)
-    return `${mins.padStart(2,'0')}:${secs.padStart(2,'0')}`
-}
+
 function checkIfPlayable() {
-    if (pcmType != 1 && pcmType != 2) return `PCM Type not LPCM/ADPCM (${pcmType})`
+    if (pcmType !== 1 && pcmType !== 2) return `PCM Type not LPCM/ADPCM (${pcmType})`
     if (nChannels < 1 || nChannels > 2) return `Audio not mono/stereo but instead has ${nChannels} channels`
-    if (pcmType != 1 && samplingRate != pcm.HW_SAMPLING_RATE) return `Format is ADPCM but sampling rate is not ${pcm.HW_SAMPLING_RATE}: ${samplingRate}`
+    if (pcmType !== 1 && samplingRate !== pcm.HW_SAMPLING_RATE)
+        return `Format is ADPCM but sampling rate is not ${pcm.HW_SAMPLING_RATE}: ${samplingRate}`
     return "playable!"
 }
-// @return decoded sample length (not count!)
+
 function decodeInfilePcm(inPtr, outPtr, inputLen) {
-    // LPCM
-    if (1 == pcmType)
+    if (pcmType === 1)
         return pcm.decodeLPCM(inPtr, outPtr, inputLen, { nChannels, bitsPerSample, samplingRate, blockSize })
-    else if (2 == pcmType)
+    if (pcmType === 2)
         return pcm.decodeMS_ADPCM(inPtr, outPtr, inputLen, { nChannels })
-    else
-        throw Error(`PCM Type not LPCM or ADPCM (${pcmType})`)
+    throw Error(`PCM Type not LPCM or ADPCM (${pcmType})`)
 }
+
 let stopPlay = false
-
-
-con.curs_set(0)
-let [__, CONSOLE_WIDTH] = con.getmaxyx()
-function printPlayerShell() {
-if (interactive) {
-    let [cy, cx] = con.getyx()
-    // file name
-    con.mvaddch(cy, 1)
-    con.prnch(0xC9);con.prnch(0xCD);con.prnch(0xB5)
-    print(fileeeee.name)
-    con.prnch(0xC6);con.prnch(0xCD)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 26 - fileeeee.name.length))
-    con.prnch(0xB5)
-    print("Hold Bksp to Exit")
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBB)
-
-    // L R pillar
-    con.prnch(0xBA)
-    con.mvaddch(cy+1, CONSOLE_WIDTH, 0xBA)
-
-    // media info
-    let mediaInfoStr = `WAV ${WAV_FORMATS[pcmType-1]} ${WAV_CHANNELS[nChannels-1]} ${byterate*0.008*(pcmType == 2 ? 2 : 1)}kbps`
-    con.move(cy+2,1)
-    con.prnch(0xC8)
-    print("\x84205u".repeat(CONSOLE_WIDTH - 5 - mediaInfoStr.length))
-    con.prnch(0xB5)
-    print(mediaInfoStr)
-    con.prnch(0xC6);con.prnch(0xCD);con.prnch(0xBC)
-
-    con.move(cy+1, 2)
-}
-}
-let [cy, cx] = con.getyx(); cy++
-let paintWidth = CONSOLE_WIDTH - 20
-function printPlayBar(startOffset) {
-    if (interactive) {
-        let currently = seqread.getReadCount() - startOffset
-        let total = FILE_SIZE - startOffset - 8
-
-        let currentlySec = Math.round(bytesToSec(currently))
-        let totalSec = Math.round(bytesToSec(total))
-
-        con.move(cy, 3)
-        print(' '.repeat(15))
-        con.move(cy, 3)
-
-        print(`${secToReadable(currentlySec)} / ${secToReadable(totalSec)}`)
-
-        con.move(cy, 17)
-        print(' ')
-        let progressbar = '\x84196u'.repeat(paintWidth + 1)
-        print(progressbar)
-
-        con.mvaddch(cy, 18 + Math.round(paintWidth * (currently / total)), 0xDB)
-    }
-}
 let errorlevel = 0
-// read chunks loop
-try {
-while (!stopPlay && seqread.getReadCount() < FILE_SIZE - 8) {
-    let chunkName = seqread.readFourCC()
-    let chunkSize = seqread.readInt()
-    printdbg(`Reading '${chunkName}' at ${seqread.getReadCount() - 8}`)
 
-    // here be lotsa if-else
-    if ("fmt " == chunkName) {
-        pcmType = seqread.readShort()
-        nChannels = seqread.readShort()
-        samplingRate = seqread.readInt()
-        byterate = seqread.readInt()
-        blockSize = seqread.readShort()
-        bitsPerSample = seqread.readShort()
-        if (pcmType != 2) {
-            seqread.skip(chunkSize - 16)
+try {
+    while (!stopPlay && seqread.getReadCount() < FILE_SIZE - 8) {
+        const chunkName = seqread.readFourCC()
+        const chunkSize = seqread.readInt()
+        printdbg(`Reading '${chunkName}' at ${seqread.getReadCount() - 8}`)
+
+        if (chunkName === "fmt ") {
+            pcmType       = seqread.readShort()
+            nChannels     = seqread.readShort()
+            samplingRate  = seqread.readInt()
+            byterate      = seqread.readInt()
+            blockSize     = seqread.readShort()
+            bitsPerSample = seqread.readShort()
+            if (pcmType !== 2) {
+                seqread.skip(chunkSize - 16)
+            } else {
+                seqread.skip(2)
+                adpcmSamplesPerBlock = seqread.readShort()
+                seqread.skip(chunkSize - (16 + 4))
+            }
+
+            if (pcmType === 1) {
+                const incr = LCM(blockSize, samplingRate / GCD(samplingRate, pcm.HW_SAMPLING_RATE))
+                while (BLOCK_SIZE < 4096) BLOCK_SIZE += incr
+                INFILE_BLOCK_SIZE = BLOCK_SIZE * bitsPerSample / 8
+            } else if (pcmType === 2) {
+                BLOCK_SIZE = blockSize
+                INFILE_BLOCK_SIZE = BLOCK_SIZE
+            }
+
+            if (interactive) {
+                const tag = "WAV"
+                const title = fileHandle.name +
+                    `  ${WAV_FORMATS[pcmType-1]} ${WAV_CHANNELS[nChannels-1]} ${byterate*0.008*(pcmType === 2 ? 2 : 1)}kbps`
+                gui.audioInit({ title, tag })
+            }
+        }
+        else if (chunkName === "LIST") {
+            const startOffset = seqread.getReadCount()
+            const subChunkName = seqread.readFourCC()
+            while (seqread.getReadCount() < startOffset + chunkSize) {
+                if (subChunkName === "INFO") {
+                    let key = seqread.readFourCC()
+                    let valueLen = seqread.readInt()
+                    while (key.charCodeAt(0) === 0) {
+                        const kbytes = [key.charCodeAt(1), key.charCodeAt(2), key.charCodeAt(3), valueLen & 255]
+                        const klen   = [(valueLen >>> 8) & 255, (valueLen >>> 16) & 255, (valueLen >>> 24) & 255, seqread.readOneByte()]
+                        key = String.fromCharCode.apply(null, kbytes)
+                        valueLen = klen[0] | (klen[1] << 8) | (klen[2] << 16) | (klen[3] << 24)
+                    }
+                    comments[key] = seqread.readString(valueLen)
+                } else {
+                    seqread.skip(startOffset + chunkSize - seqread.getReadCount())
+                }
+            }
+        }
+        else if (chunkName === "data") {
+            const startOffset = seqread.getReadCount()
+            const reason = checkIfPlayable()
+            if (reason !== "playable!") throw Error("WAVE not playable: " + reason)
+
+            readPtr   = sys.malloc(pcmType === 2 ? BLOCK_SIZE : BLOCK_SIZE * bitsPerSample / 8)
+            decodePtr = sys.malloc(BLOCK_SIZE * pcm.HW_SAMPLING_RATE / samplingRate)
+
+            audio.resetParams(0)
+            audio.purgeQueue(0)
+            audio.setPcmMode(0)
+            audio.setMasterVolume(0, 255)
+
+            let readLength = 1
+            while (!stopPlay && seqread.getReadCount() < startOffset + chunkSize && readLength > 0) {
+                if (interactive && gui.audioIsExitRequested()) { stopPlay = true; break }
+
+                if (audio.getPosition(0) <= 1) {
+                    for (let repeat = 0; repeat < QUEUE_MAX; repeat++) {
+                        const remainingBytes = FILE_SIZE - 8 - seqread.getReadCount()
+                        readLength = (remainingBytes < INFILE_BLOCK_SIZE) ? remainingBytes : INFILE_BLOCK_SIZE
+                        if (readLength <= 0) break
+
+                        seqread.readBytes(readLength, readPtr)
+                        const decodedSampleLength = decodeInfilePcm(readPtr, decodePtr, readLength)
+
+                        // Hand the decoded PCMu8 stereo block to the visualiser
+                        // before queueing — the buffer is reused next iteration.
+                        if (interactive) gui.audioFeedPcm(decodePtr, decodedSampleLength >> 1)
+
+                        audio.putPcmDataByPtr(0, decodePtr, decodedSampleLength, 0)
+                        audio.setSampleUploadLength(0, decodedSampleLength)
+                        audio.startSampleUpload(0)
+
+                        sys.spin()
+                    }
+                    audio.play(0)
+                }
+
+                if (interactive) {
+                    const cur = seqread.getReadCount() - startOffset
+                    const tot = FILE_SIZE - startOffset - 8
+                    gui.audioSetProgress(cur / tot, bytesToSec(cur), bytesToSec(tot))
+                    gui.audioRender()
+                }
+                sys.sleep(10)
+            }
         }
         else {
-            seqread.skip(2)
-            adpcmSamplesPerBlock = seqread.readShort()
-            seqread.skip(chunkSize - (16 + 4))
+            seqread.skip(chunkSize)
         }
 
-        // define BLOCK_SIZE as integer multiple of blockSize, for LPCM
-        // ADPCM will be decoded per-block basis
-        if (1 == pcmType) {
-            // get GCD of given values; this wll make resampling headache-free
-            let blockSizeIncrement = LCM(blockSize, samplingRate / GCD(samplingRate, pcm.HW_SAMPLING_RATE))
-
-            while (BLOCK_SIZE < 4096) {
-                BLOCK_SIZE += blockSizeIncrement // for rate 44100, BLOCK_SIZE will be 4116
-            }
-            INFILE_BLOCK_SIZE = BLOCK_SIZE * bitsPerSample / 8 // for rate 44100, INFILE_BLOCK_SIZE will be 8232
-        }
-        else if (2 == pcmType) {
-            BLOCK_SIZE = blockSize
-            INFILE_BLOCK_SIZE = BLOCK_SIZE
-        }
-
-        printdbg(`Format: ${pcmType}, Channels: ${nChannels}, Rate: ${samplingRate}, BitDepth: ${bitsPerSample}`)
-        printdbg(`BLOCK_SIZE=${BLOCK_SIZE}, INFILE_BLOCK_SIZE=${INFILE_BLOCK_SIZE}`)
-        printPlayerShell()
+        sys.spin()
     }
-    else if ("LIST" == chunkName) {
-        let startOffset = seqread.getReadCount()
-        let subChunkName = seqread.readFourCC()
-        while (seqread.getReadCount() < startOffset + chunkSize) {
-            if ("INFO" == subChunkName) {
-                let key = seqread.readFourCC()
-                let valueLen = seqread.readInt()
-
-                // f-you WAVE encoders with nonstandard behaviours
-                // related: https://stackoverflow.com/questions/49537639/riff-icmt-tag-size-doesnt-seem-to-match-data
-                while (0 == key.charCodeAt(0)) {
-                    printdbg(`Previous key had more zero bytes padded than its marked length, skipping one byte...`)
-
-                    let kbytes = [key.charCodeAt(1), key.charCodeAt(2), key.charCodeAt(3), valueLen & 255]
-                    let klen = [(valueLen >>> 8) & 255, (valueLen >>> 16) & 255, (valueLen >>> 24) & 255, seqread.readOneByte()]
-
-                    key = String.fromCharCode.apply(null, kbytes)
-                    valueLen = klen[0] | (klen[1] << 8) | (klen[2] << 16) | (klen[3] << 24)
-                }
-
-                printdbg(`Reading LIST INFO ${key}[${[0,1,2,3].map((i)=>"0x"+key.charCodeAt(i).toString(16).padStart(2,'0'))}] (${valueLen} bytes): `)
-
-
-                let value = seqread.readString(valueLen)
-                printdbg("   |"+value)
-                comments[key] = value
-            }
-            else {
-                printdbg(`LIST skip subchunk ${subChunkName} (${startOffset + chunkSize - seqread.getReadCount()} bytes)`)
-                seqread.skip(startOffset + chunkSize - seqread.getReadCount())
-            }
-        }
-        printComments()
-    }
-    else if ("data" == chunkName) {
-        let startOffset = seqread.getReadCount()
-
-        printdbg(`WAVE size: ${chunkSize}, startOffset=${startOffset}`)
-        // check if the format is actually playable
-        let unplayableReason  = checkIfPlayable()
-        if (unplayableReason != "playable!") throw Error("WAVE not playable: "+unplayableReason)
-
-        if (pcmType == 2)
-            readPtr = sys.malloc(BLOCK_SIZE)
-        else
-            readPtr = sys.malloc(BLOCK_SIZE * bitsPerSample / 8)
-
-        decodePtr = sys.malloc(BLOCK_SIZE * pcm.HW_SAMPLING_RATE / samplingRate)
-
-        audio.resetParams(0)
-        audio.purgeQueue(0)
-        audio.setPcmMode(0)
-        audio.setMasterVolume(0, 255)
-
-        let readLength = 1
-        while (!stopPlay && seqread.getReadCount() < startOffset + chunkSize && readLength > 0) {
-            if (interactive) {
-                sys.poke(-40, 1)
-                if (sys.peek(-41) == 67) {
-                    stopPlay = true
-                }
-            }
-
-            printPlayBar(startOffset)
-
-            let queueSize = audio.getPosition(0)
-            if (queueSize <= 1) {
-
-
-                // upload four samples for lag-safely
-                for (let repeat = 0; repeat < QUEUE_MAX; repeat++) {
-                    let remainingBytes = FILE_SIZE - 8 - seqread.getReadCount()
-
-                    readLength = (remainingBytes < INFILE_BLOCK_SIZE) ? remainingBytes : INFILE_BLOCK_SIZE
-                    if (readLength <= 0) {
-                        printdbg(`readLength = ${readLength}`)
-                        break
-                    }
-
-                    printdbg(`offset: ${seqread.getReadCount()}/${FILE_SIZE + 8}; readLength: ${readLength}`)
-
-                    seqread.readBytes(readLength, readPtr)
-
-                    let decodedSampleLength = decodeInfilePcm(readPtr, decodePtr, readLength)
-                    printdbg(`        decodedSampleLength: ${decodedSampleLength}`)
-
-                    audio.putPcmDataByPtr(0, decodePtr, decodedSampleLength, 0)
-                    audio.setSampleUploadLength(0, decodedSampleLength)
-                    audio.startSampleUpload(0)
-
-                    sys.spin()
-                }
-
-                audio.play(0)
-            }
-
-            let remainingBytes = FILE_SIZE - 8 - seqread.getReadCount()
-            printdbg(`readLength = ${readLength}; remainingBytes2 = ${remainingBytes}; seqread.getReadCount() = ${seqread.getReadCount()}; startOffset + chunkSize = ${startOffset + chunkSize}`)
-
-
-            sys.sleep(10)
-        }
-    }
-    else {
-        seqread.skip(chunkSize)
-    }
-
-
-    let remainingBytes = FILE_SIZE - 8 - seqread.getReadCount()
-    printdbg(`remainingBytes2 = ${remainingBytes}`)
-    sys.spin()
-}
-}
-catch (e) {
+} catch (e) {
     printerrln(e)
     errorlevel = 1
-}
-finally {
-    //audio.stop(0)
-    if (readPtr !== undefined) sys.free(readPtr)
+} finally {
+    if (readPtr   !== undefined) sys.free(readPtr)
     if (decodePtr !== undefined) sys.free(decodePtr)
+    if (interactive) gui.audioClose()
 }
 
 return errorlevel

assets/disk0/tvdos/bin/taut_sampleedit.js

@@ -1,18 +1,23 @@
 /**
- * TAUT Sample Editor
- * Sub-program launched by taut.js when the Samples tab is active.
- * Rows 1-3 are owned by the parent; this program draws rows 4+.
+ * TAUT Sample Editor (stub)
+ * Sub-program launched from taut.js's Samples viewer. Rows 1-3 are owned by
+ * the parent; this program draws rows 4+.
  *
- * exec_args[1] = path to .taud file
- * Sets _G.TAUT.UI.NEXTPANEL before returning to request a panel switch.
+ * exec_args:
+ *   [1] = path to .taud file
+ *   [2] = parent panel index (where to return)
+ *   [3] = sample index to preload (-1 if none)
+ *
+ * Sets _G.TAUT.UI.NEXTPANEL on return to request a panel switch back.
  *
  * Created by minjaesong on 2026-04-27
+ * Stub editing UI added on 2026-05-26
  */
 
 const win = require("wintex")
 
-const PANEL_COUNT = 7
-const MY_PANEL   = 3 // VIEW_SAMPLES
+const PARENT_PANEL = (exec_args[2] !== undefined) ? (exec_args[2] | 0) : 3 // VIEW_SAMPLES
+const SAMPLE_IDX   = (exec_args[3] !== undefined) ? (exec_args[3] | 0) : -1
 
 const [SCRH, SCRW] = con.getmaxyx()
 const PANEL_Y = 4
@@ -21,38 +26,122 @@ const PANEL_H = SCRH - PANEL_Y
 const colStatus  = 253
 const colContent = 240
 const colHdr     = 230
+const colEmph    = 211
+const colDim     = 246
+const colBack    = 255
+const colSel     = 41
 
-function drawSampleEditContents(wo) {
+// Stub editor "fields": pretend toolbar. None of these write anything yet.
+const TOOLS = [
+    { key: 'L', label: 'Load .raw / .wav from disk' },
+    { key: 'S', label: 'Save current sample to disk' },
+    { key: 'D', label: 'Draw waveform freehand' },
+    { key: 'X', label: 'Crop / trim selection' },
+    { key: 'R', label: 'Resample' },
+    { key: 'V', label: 'Reverse' },
+    { key: 'N', label: 'Normalise to peak' },
+    { key: 'F', label: 'Fade in / out' },
+]
+
+let toolCursor = 0
+
+function drawSampleEditFrame() {
     for (let y = PANEL_Y; y < SCRH; y++) {
         con.move(y, 1)
-        con.color_pair(colContent, 255)
+        con.color_pair(colContent, colBack)
         print(' '.repeat(SCRW))
     }
+    // Title
     con.move(PANEL_Y + 1, 3)
-    con.color_pair(colHdr, 255)
-    print('[ Sample Editor ]')
-    con.move(PANEL_Y + 3, 3)
-    con.color_pair(colStatus, 255)
-    print('placeholder — not yet implemented')
+    con.color_pair(colHdr, colBack); print('[ Sample Editor ]  ')
+    con.color_pair(colEmph, colBack); print('Sample ')
+    con.color_pair(colStatus, colBack)
+    if (SAMPLE_IDX >= 0) print('#' + (SAMPLE_IDX + 1).toString(16).toUpperCase().padStart(2, '0'))
+    else                 print('(none)')
+
+    con.move(PANEL_Y + 2, 3)
+    con.color_pair(colDim, colBack)
+    print('stub editor — actions below are placeholders only.')
+}
+
+function drawToolList() {
+    const x = 5
+    const y0 = PANEL_Y + 4
+    con.move(y0, x)
+    con.color_pair(colHdr, colBack); print('Editing actions')
+    con.move(y0 + 1, x)
+    con.color_pair(colDim, colBack); print('-'.repeat(16))
+
+    for (let i = 0; i < TOOLS.length; i++) {
+        const y = y0 + 3 + i
+        const t = TOOLS[i]
+        const sel = (i === toolCursor)
+        const back = sel ? colSel : colBack
+        con.move(y, x)
+        con.color_pair(colHdr, back); print(' ' + t.key + ' ')
+        con.color_pair(colStatus, back); print('  ')
+        con.color_pair(sel ? colEmph : colStatus, back)
+        const w = SCRW - x - 6
+        const lbl = t.label.length > w ? t.label.substring(0, w) : t.label.padEnd(w)
+        print(lbl)
+    }
+
+    // Drawing-area placeholder on the right
+    const dx = 38
+    const dy0 = PANEL_Y + 4
+    const dw  = SCRW - dx - 2
+    const dh  = SCRH - dy0 - 2
+    con.move(dy0, dx)
+    con.color_pair(colHdr, colBack); print('Waveform editor')
+    con.move(dy0 + 1, dx)
+    con.color_pair(colDim, colBack); print('-'.repeat(16))
+
+    // Empty drawing rectangle made of dots
+    for (let r = 0; r < dh; r++) {
+        con.move(dy0 + 3 + r, dx)
+        con.color_pair(colDim, colBack)
+        if (r === (dh >>> 1)) print('-'.repeat(dw)) // zero line
+        else print(' '.repeat(dw))
+    }
+    con.move(dy0 + 3 + (dh >>> 1) + 1, dx)
+    con.color_pair(colDim, colBack)
+    print('(drawing surface — not yet implemented)')
 }
 
 function drawHints() {
     con.move(SCRH, 1)
-    con.color_pair(colStatus, 255)
+    con.color_pair(colStatus, colBack)
     print(' '.repeat(SCRW - 1))
     con.move(SCRH, 1)
-    con.color_pair(colHdr, 255); print('Tab ')
-    con.color_pair(colStatus, 255); print('Panel')
+    con.color_pair(colHdr, colBack); print('„28u„29u ')
+    con.color_pair(colStatus, colBack); print('Tool ')
+    con.color_pair(colHdr, colBack); print('Enter ')
+    con.color_pair(colStatus, colBack); print('Apply ')
+    con.color_pair(colHdr, colBack); print('Esc/Tab ')
+    con.color_pair(colStatus, colBack); print('Back to viewer')
+}
+
+function flashAction(idx) {
+    const t = TOOLS[idx]
+    if (!t) return
+    con.move(SCRH - 2, 5)
+    con.color_pair(colEmph, colBack)
+    print(('Action: ' + t.label + ' (stub, no-op)').padEnd(SCRW - 8))
 }
 
 function sampleEditInput(wo, event) {
-    // placeholder — no interaction yet
+    // wintex panel input — wired up but the loop below handles keys directly.
 }
 
-const panel = new win.WindowObject(1, PANEL_Y, SCRW, PANEL_H, sampleEditInput, drawSampleEditContents, undefined, ()=>{})
+function drawAll() {
+    drawSampleEditFrame()
+    drawToolList()
+    drawHints()
+}
+
+const panel = new win.WindowObject(1, PANEL_Y, SCRW, PANEL_H, sampleEditInput, drawAll, undefined, ()=>{})
 
 panel.drawContents()
-drawHints()
 
 let done = false
 while (!done) {
@@ -60,17 +149,32 @@ while (!done) {
         if (event[0] !== 'key_down') return
         const keysym     = event[1]
         const keyJustHit = (1 == event[2])
-        const shiftDown  = (event.includes(59) || event.includes(60))
 
         if (!keyJustHit) return
 
-        if (keysym === '<TAB>') {
-            _G.TAUT.UI.NEXTPANEL = (MY_PANEL + (shiftDown ? -1 : 1) + PANEL_COUNT) % PANEL_COUNT
+        if (keysym === '<ESCAPE>' || keysym === '<TAB>') {
+            _G.TAUT.UI.NEXTPANEL = PARENT_PANEL
             done = true
             return
         }
 
-        panel.processInput(event)
+        if (keysym === '<UP>')   { if (toolCursor > 0)              toolCursor--; drawToolList(); return }
+        if (keysym === '<DOWN>') { if (toolCursor < TOOLS.length-1) toolCursor++; drawToolList(); return }
+
+        if (keysym === '\n') {
+            flashAction(toolCursor)
+            return
+        }
+
+        // Direct key shortcuts
+        for (let i = 0; i < TOOLS.length; i++) {
+            if (keysym === TOOLS[i].key.toLowerCase() || keysym === TOOLS[i].key) {
+                toolCursor = i
+                drawToolList()
+                flashAction(i)
+                return
+            }
+        }
     })
 }
 

assets/disk0/tvdos/bin/zfm.js

@@ -19,7 +19,10 @@ const LIST_HEIGHT = HEIGHT - 3
 const FILESIZE_WIDTH = 7
 const FILELIST_WIDTH = WIDTH - SIDEBAR_WIDTH - 3 - FILESIZE_WIDTH
 const POPUP_WIDTH = 52 // always even number
-const POPUP_HEIGHT = 16
+
+const [SCRPW, SCRPH] = graphics.getPixelDimension()
+const CELL_PW = (SCRPW / WIDTH) | 0
+const CELL_PH = (SCRPH / WHEIGHT) | 0
 
 const COL_HL_EXT = {
     "js": 215,
@@ -69,6 +72,11 @@ const EXEC_FUNS = {
     "taud": (f) => _G.shell.execute(`playtaud "${f}"`),
 }
 
+const EDIT_FUNS = {
+    "taud": (f) => _G.shell.execute(`microtone "${f}"`),
+}
+const DEFAULT_EDITOR = `edit`
+
 function makeExecFun(template) {
     return (f) => _G.shell.execute(template.replaceAll("{0}", `"${f}"`))
 }
@@ -118,8 +126,52 @@ function loadZfmrc() {
 
 loadZfmrc()
 
+///////////////////////////////////////////////////////////////////////////////////////////////////
+// Mouse region registry
+///////////////////////////////////////////////////////////////////////////////////////////////////
+
+const MOUSE_PANEL = []
+let lastHoveredRegion = null
+
+function pixelToCell(px, py) {
+    return [(py / CELL_PH | 0) + 1, (px / CELL_PW | 0) + 1]
+}
+function regionHits(r, cy, cx) {
+    return cy >= r.y && cy < r.y + r.h && cx >= r.x && cx < r.x + r.w
+}
+function clearPanelMouseRegions() { MOUSE_PANEL.length = 0; lastHoveredRegion = null }
+function addPanelMouseRegion(x, y, w, h, handlers) { MOUSE_PANEL.push(Object.assign({x, y, w, h}, handlers)) }
+
+function dispatchMouseEvent(event) {
+    const t = event[0]
+    if (t !== 'mouse_down' && t !== 'mouse_wheel' && t !== 'mouse_up' && t !== 'mouse_move') return false
+    const [cy, cx] = pixelToCell(event[1], event[2])
+
+    if (t === 'mouse_move') {
+        let hit = null
+        for (let i = MOUSE_PANEL.length - 1; i >= 0; i--) {
+            const r = MOUSE_PANEL[i]
+            if (regionHits(r, cy, cx) && (r.onHover || r.onHoverLeave)) { hit = r; break }
+        }
+        if (hit !== lastHoveredRegion) {
+            if (lastHoveredRegion && lastHoveredRegion.onHoverLeave) lastHoveredRegion.onHoverLeave()
+            lastHoveredRegion = hit
+        }
+        if (hit && hit.onHover) { hit.onHover(cy, cx, event); return true }
+        return false
+    }
+
+    for (let i = MOUSE_PANEL.length - 1; i >= 0; i--) {
+        const r = MOUSE_PANEL[i]
+        if (!regionHits(r, cy, cx)) continue
+        if (t === 'mouse_down'  && r.onClick)   { r.onClick(cy, cx, event[3], event); return true }
+        if (t === 'mouse_wheel' && r.onWheel)   { r.onWheel(cy, cx, event[3], event); return true }
+        if (t === 'mouse_up'    && r.onRelease) { r.onRelease(cy, cx, event[3], event); return true }
+    }
+    return false
+}
+
 let windowMode = 0 // 0 == left, 1 == right
-let windowFocus = [0] // is a stack; 0: files window, 1: palette window, 2: popup window
 
 // window states
 let path = [["A:", "home"], ["A:"]]
@@ -347,11 +399,43 @@ let filesPanelDraw = (wo) => {
     con.color_pair(COL_TEXT, COL_BACK)
 
 }
+// Op panel buttons. yOff is the row offset (icon) inside the op panel frame;
+// label sits at yOff+1. Hit regions span both rows.
+// hitH is the row count for the mouse hit-box. The switch button gets a taller
+// hit-box than the others because the icon glyph above its label leaves extra
+// whitespace inside the cell above the first horizontal rule.
+const OP_BUTTONS = [
+    { id: 'switch', yOff: 0,  hitH: 5, key: 'z' },
+    { id: 'up',     yOff: 6,  hitH: 2, key: 'u' },
+    { id: 'copy',   yOff: 9,  hitH: 2, key: 'c' },
+    { id: 'move',   yOff: 12, hitH: 2, key: 'v' },
+    { id: 'delete', yOff: 15, hitH: 2, key: 'd' },
+    { id: 'mkdir',  yOff: 18, hitH: 2, key: 'k' },
+    { id: 'rename', yOff: 21, hitH: 2, key: 'r' },
+    { id: 'more',   yOff: 24, hitH: 2, key: 'm' },
+    { id: 'quit',   yOff: 27, hitH: 2, key: 'q' },
+]
+let opHover = -1
+
 let opPanelDraw = (wo) => {
-    function hr(y) {
+    function hr(i, y) {
+        // draw horizontal rule...
+        con.color_pair(COL_TEXT, 255)
         con.move(y, xp)
-        print(`\x84196u`.repeat(SIDEBAR_WIDTH - 2))
+        print(`\u00C4`.repeat(SIDEBAR_WIDTH - 2))
+
+        // if mouse is up, draw the whole box
+        if (opHover == i) {
+            let moveBack = (i == 0) ? 6 : 3
+
+            con.color_pair(COL_HLTEXT, 255)
+            con.move(y - moveBack, xp)
+             print('\u00CD'.repeat(SIDEBAR_WIDTH - 2))
+            con.move(y, xp)
+            print('\u00CD'.repeat(SIDEBAR_WIDTH - 2))
+        }
     }
+    function labCol(i) { return (opHover === i) ? COL_HLTEXT : COL_TEXT }
 
     con.color_pair(COL_TEXT, COL_BACK)
 
@@ -360,112 +444,83 @@ let opPanelDraw = (wo) => {
 
     // other panel
     con.move(yp + 2, xp + 3)
-    con.prnch((windowMode) ? 0x11 : 0x10)
+    con.color_pair(labCol(0), 255); con.prnch((windowMode) ? 0x11 : 0x10)
     con.move(yp + 3, xp)
-    print(`  \x1B[38;5;${COL_TEXT}m[\x1B[38;5;${COL_HLACTION}mZ\x1B[38;5;${COL_TEXT}m]`)
+    print(`  \x1B[38;5;${labCol(0)}m[\x1B[38;5;${COL_HLACTION}mZ\x1B[38;5;${labCol(0)}m]`)
 
-    hr(yp+5)
+    hr(0, yp+5)
 
     // go up
-    con.mvaddch(yp + 6, xp + 3, 0x18)
+    con.color_pair(labCol(1), 255); con.mvaddch(yp + 6, xp + 3, 0x18)
     con.move(yp + 7, xp)
-    print(` \x1B[38;5;${COL_TEXT}mGo \x1B[38;5;${COL_HLACTION}mU\x1B[38;5;${COL_TEXT}mp`)
+    print(` \x1B[38;5;${labCol(1)}mGo \x1B[38;5;${COL_HLACTION}mU\x1B[38;5;${labCol(1)}mp`)
 
-    hr(yp+8)
+    hr(1, yp+8)
 
     // copy
     con.move(yp + 9, xp + 2)
-    con.prnch(0xDB);con.prnch((windowMode) ? 0x1B : 0x1A);con.prnch(0xDB)
+    con.color_pair(labCol(2), 255); con.prnch(0xDB);con.prnch((windowMode) ? 0x1B : 0x1A);con.prnch(0xDB)
     con.move(yp + 10, xp)
-    print(` \x1B[38;5;${COL_HLACTION}mC\x1B[38;5;${COL_TEXT}mopy`)
+    print(` \x1B[38;5;${COL_HLACTION}mC\x1B[38;5;${labCol(2)}mopy`)
 
-    hr(yp+11)
+    hr(2, yp+11)
 
     // move
     con.move(yp + 12, xp + 2)
-    if (windowMode) con.prnch([0xDB, 0x1B, 0xB0]); else con.prnch([0xB0, 0x1A, 0xDB])
+    con.color_pair(labCol(3), 255); if (windowMode) con.prnch([0xDB, 0x1B, 0xB0]); else con.prnch([0xB0, 0x1A, 0xDB])
     con.move(yp + 13, xp)
-    print(` \x1B[38;5;${COL_TEXT}mMo\x1B[38;5;${COL_HLACTION}mv\x1B[38;5;${COL_TEXT}me`)
+    print(` \x1B[38;5;${labCol(3)}mMo\x1B[38;5;${COL_HLACTION}mv\x1B[38;5;${labCol(3)}me`)
 
-    hr(yp+14)
+    hr(3, yp+14)
 
     // delete
     con.move(yp + 15, xp + 2)
-    if (windowMode) con.prnch([0xDB, 0x1A, 0xF9]); else con.prnch([0xF9, 0x1B, 0xDB])
+    con.color_pair(labCol(4), 255); if (windowMode) con.prnch([0xDB, 0x1A, 0xF9]); else con.prnch([0xF9, 0x1B, 0xDB])
     con.move(yp + 16, xp)
-    print(` \x1B[38;5;${COL_HLACTION}mD\x1B[38;5;${COL_TEXT}melete`)
+    print(` \x1B[38;5;${COL_HLACTION}mD\x1B[38;5;${labCol(4)}melete`)
 
-    hr(yp+17)
+    hr(4, yp+17)
 
     // mkdir
     con.move(yp + 18, xp + 2)
+    con.color_pair(labCol(5), 255);
     con.prnch(0xDB)
     con.video_reverse();con.prnch(0x2B);con.video_reverse()
     con.prnch(0xDF)
     con.move(yp + 19, xp)
-    print(` \x1B[38;5;${COL_TEXT}mM\x1B[38;5;${COL_HLACTION}mk\x1B[38;5;${COL_TEXT}mDir`)
+    print(` \x1B[38;5;${labCol(5)}mM\x1B[38;5;${COL_HLACTION}mk\x1B[38;5;${labCol(5)}mDir`)
 
-    hr(yp+20)
+    hr(5, yp+20)
 
     // rename
     con.move(yp + 21, xp + 2)
-    con.prnch(0x4E);con.prnch(0x1A);con.prnch(0x52)
+    con.color_pair(labCol(6), 255); con.prnch(0x4E);con.prnch(0x1A);con.prnch(0x52)
     con.move(yp + 22, xp)
-    print(` \x1B[38;5;${COL_HLACTION}mR\x1B[38;5;${COL_TEXT}mename`)
+    print(` \x1B[38;5;${COL_HLACTION}mR\x1B[38;5;${labCol(6)}mename`)
 
-    hr(yp+23)
+    hr(6, yp+23)
 
     // the dreaded hamburger menu
     con.move(yp + 24, xp + 3)
-    con.prnch(0xf0)
+    con.color_pair(labCol(7), 255); con.prnch(0xf0)
     con.move(yp + 25, xp)
-    print(` \x1B[38;5;${COL_HLACTION}mM\x1B[38;5;${COL_TEXT}more`)
+    print(` \x1B[38;5;${COL_HLACTION}mM\x1B[38;5;${labCol(7)}more`)
 
-    hr(yp+26)
+    hr(7, yp+26)
 
     // quit
     con.move(yp + 27, xp + 3)
-    con.prnch(0x58)
+    con.color_pair(labCol(8), 255); con.prnch(0x58)
     con.move(yp + 28, xp)
-    print(` \x1B[38;5;${COL_HLACTION}mQ\x1B[38;5;${COL_TEXT}muit`)
-
+    print(` \x1B[38;5;${COL_HLACTION}mQ\x1B[38;5;${labCol(8)}muit`)
 
+    con.color_pair(COL_TEXT, 255)
 }
 
 
-let paletteDraw = (wo) => {
-    function hr(y) {
-        con.move(y, xp)
-        print(`\x84196u`.repeat(POPUP_WIDTH - 2))
-    }
-
-    con.color_pair(COL_TEXT, COL_BACK)
-
-    let xp = wo.x + 1
-    let yp = wo.y + 1
-
-    // erase first
-    for (let y = 0; y <= POPUP_HEIGHT-2; y++) {
-        con.move(yp + y, xp)
-        print(" ".repeat(POPUP_WIDTH-2))
-    }
-
-    // finally draw something
-    con.move(yp, xp)
-    print("More commands (hit m to return):")
-}
-
-
-let popupDraw = (wo) => {
-
-}
-
-///////////////////////////////////////////////////////////////////////////////////////////////////
-
 let filenavOninput = (window, event) => {
-
     let eventName = event[0]
-    if (eventName == "key_down") {
+    if (eventName !== "key_down") return
 
     let keysym = event[1]
     let keyJustHit = (1 == event[2])
@@ -474,13 +529,15 @@ let filenavOninput = (window, event) => {
 
     let scrollPeek = (LIST_HEIGHT / 3)|0
 
-    if (keyJustHit && keysym == "q") {
-        exit = true
-    }
-    else if (keyJustHit && keysym == "z") {
-        windowMode = 1 - windowMode
-        redraw() // this would double-redraw (hence no panel switching) or something if redraw() is not merely a request to do so
-    }
+    if      (keyJustHit && keysym == "q") actQuit()
+    else if (keyJustHit && keysym == "z") actSwitchPanel()
+    else if (keyJustHit && keysym == 'u') actGoUp()
+    else if (keyJustHit && keysym == 'c') actCopy()
+    else if (keyJustHit && keysym == 'v') actMove()
+    else if (keyJustHit && keysym == 'd') actDelete()
+    else if (keyJustHit && keysym == 'k') actMkdir()
+    else if (keyJustHit && keysym == 'r') actRename()
+    else if (keyJustHit && keysym == 'm') actMore()
     else if (keysym == "<UP>") {
         [cursor[windowMode], scroll[windowMode]] = win.scrollVert(-1, dirFileList[windowMode].length, LIST_HEIGHT, cursor[windowMode], scroll[windowMode], scrollPeek)
         drawFilePanel()
@@ -498,142 +555,85 @@ let filenavOninput = (window, event) => {
         drawFilePanel()
     }
     else if (keyJustHit && keycode == 66) { // enter
-        let selectedFileCache = filePanelCache[windowMode][cursor[windowMode]]
-        let selectedFile = selectedFileCache.file
-
-        //serial.println(`selectedFile = ${selectedFile.fullPath}`)
-
-        if (selectedFile.fullPath[1] == ":" && selectedFile.fullPath[2] == "\\" && selectedFile.fullPath.length == 3) {
-            path[windowMode].push(selectedFile.fullPath)
-            cursor[windowMode] = 0; scroll[windowMode] = 0
-            refreshFilePanelCache(windowMode)
-            drawFilePanel()
-        }
-        else if (selectedFileCache.isDirectory) {
-            //serial.println(`selectedFile.name = ${selectedFile.name}`)
-            path[windowMode].push(selectedFileCache.filename)
-            cursor[windowMode] = 0; scroll[windowMode] = 0
-            refreshFilePanelCache(windowMode)
-            drawFilePanel()
-        }
-        else {
-            let fileext = selectedFileCache.filename.substring(selectedFileCache.filename.lastIndexOf(".") + 1).toLowerCase()
-            let execfun = EXEC_FUNS[fileext] || ((f) => _G.shell.execute(f))
-            let errorlevel = 0
-
-            con.curs_set(1);clearScr();con.move(1,1)
-            try {
-                //serial.println(selectedFile.fullPath)
-                errorlevel = execfun(selectedFile.fullPath)
-                //serial.println("1 errorlevel = " + errorlevel)
-            }
-            catch (e) {
-                // TODO popup error
-                println(e)
-                errorlevel = 1
-                //serial.println("2 errorlevel = " + errorlevel)
-            }
-
-            if (errorlevel) {
-                println("Hit Return/Enter key to continue . . . .")
-                sys.read()
-            }
-
-            firstRunLatch = true
-            con.curs_set(0);clearScr()
-            refreshFilePanelCache(windowMode)
-            redraw()
-        }
-    }
-    else if (keyJustHit && keysym == 'u') { // no bksp: used as an exit key for playmov/playwav
-        if (path[windowMode].length >= 1) {
-            path[windowMode].pop()
-            cursor[windowMode] = 0; scroll[windowMode] = 0
-            refreshFilePanelCache(windowMode)
-            drawFilePanel()
-        }
-        else {
-            // TODO list of drives
-
-        }
-    }
-    else if (keyJustHit && keysym == 'm') {
-        makePopup(1); redraw()
-    }
-
-
-
+        actActivate()
     }
 }
 
+///////////////////////////////////////////////////////////////////////////////////////////////////
+// Popup wrappers (delegate to win.showDialog in wintex.mjs)
+///////////////////////////////////////////////////////////////////////////////////////////////////
 
-
-let paletteInput = (window, event) => {
-
-    let eventName = event[0]
-    if (eventName == "key_down") {
-
-    let keysym = event[1]
-    let keyJustHit = (1 == event[2])
-    let keycodes = [event[3],event[4],event[5],event[6],event[7],event[8],event[9],event[10]]
-    let keycode = keycodes[0]
-
-    if (keyJustHit && keysym == 'm') {
-        removePopup(); redraw()
-    }
-
-    }
+function showConfirmPopup(title, message) {
+    const res = win.showDialog({
+        title: title,
+        message: message,
+        fields: [],
+        buttons: [
+            { label: 'OK',     action: 'ok', default: true },
+            { label: 'CANCEL', action: 'cancel' },
+        ],
+    })
+    return res.action === 'ok'
 }
 
+function showInputPopup(title, prompt, defaultVal) {
+    const res = win.showDialog({
+        title: title,
+        fields: [{ label: prompt, initial: defaultVal || '', width: POPUP_WIDTH - 6 }],
+        buttons: [
+            { label: 'OK',     action: 'ok', default: true },
+            { label: 'CANCEL', action: 'cancel' },
+        ],
+    })
+    return res.action === 'ok' ? res.values[0] : null
+}
 
+function showMessagePopup(title, message) {
+    win.showDialog({
+        title: title,
+        message: message,
+        fields: [],
+        buttons: [{ label: 'OK', action: 'ok', default: true }],
+    })
+}
 
-let popupInput = (window, event) => {
+// Vertical-list popup: items are stacked rows, navigable with arrow keys /
+// mouse, selection (Enter / left-click on row) returns that item's action.
+// A single Close button sits below the list; Esc and Close both yield 'close'.
+// Thin wrapper over win.showDialog — see wintex.mjs for the underlying schema.
+function showActionListPopup(opts) {
+    const items = opts.items || []
+    const closeLabel = opts.closeLabel || 'Close'
+    const defaultIdx = items.findIndex(it => it.default)
 
+    const res = win.showDialog({
+        title: opts.title || '',
+        message: opts.message,
+        list: {
+            items: items,
+            height: items.length,
+            cursor: defaultIdx >= 0 ? defaultIdx : 0,
+            showScrollbar: false,
+            onActivate: (item) => item.action,
+        },
+        buttons: [{ label: closeLabel, action: 'close' }],
+    })
 
+    if (res.action === 'cancel') return { action: 'close' }
+    return { action: res.action }
 }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 
-let windows = [
-/*index 0: main three panels*/[
+const windows = [
     new win.WindowObject(1, 2, WIDTH - SIDEBAR_WIDTH, HEIGHT, filenavOninput, filesPanelDraw), // left panel
     new win.WindowObject(WIDTH - SIDEBAR_WIDTH+1, 2, SIDEBAR_WIDTH, HEIGHT, ()=>{}, opPanelDraw),
-//    new win.WindowObject(1, 2, SIDEBAR_WIDTH, HEIGHT, ()=>{}, opPanelDraw),
     new win.WindowObject(SIDEBAR_WIDTH + 1, 2, WIDTH - SIDEBAR_WIDTH, HEIGHT, filenavOninput, filesPanelDraw), // right panel
-],
-/*index 1: commands palette*/[
-    new win.WindowObject((WIDTH - POPUP_WIDTH) / 2, (HEIGHT - POPUP_HEIGHT) / 2, POPUP_WIDTH, POPUP_HEIGHT, paletteInput, paletteDraw, "Commands")
-],
-/*index 2: popup messages*/[
-    new win.WindowObject((WIDTH - POPUP_WIDTH) / 2, (HEIGHT - POPUP_HEIGHT) / 2, POPUP_WIDTH, POPUP_HEIGHT, popupInput, popupDraw)
-]]
+]
 
-const LEFTPANEL = windows[0][0]
-const OPPANEL = windows[0][1]
-const RIGHTPANEL = windows[0][2]
-
-let currentPopup = 0
-
-function makePopup(index) {
-    currentPopup = index
-    windowFocus.push(currentPopup)
-    for (let i = 0; i < windows.length; i++) {
-        windows[i].forEach(it => {
-            it.isHighlighted = (i == index)
-        })
-    }
-}
-
-function removePopup() {
-    windowFocus.pop()
-    const index = windowFocus.last
-    currentPopup = 0
-    for (let i = 0; i < windows.length; i++) {
-        windows[i].forEach(it => {
-            it.isHighlighted = (i == index)
-        })
-    }
-}
+const LEFTPANEL = windows[0]
+const OPPANEL = windows[1]
+const RIGHTPANEL = windows[2]
 
 function drawTitle() {
     // draw window title
@@ -651,18 +651,9 @@ function drawTitle() {
 
 
 function drawFilePanel() {
-    // set highlight status
-    const currentTopPanel = windowFocus.last()
-    if (currentTopPanel == 0) {
-        windows[0].forEach((panel, i)=>{
-            panel.isHighlighted = (i == 2 * windowMode)
-        })
-    }
-    else {
-        windows[0].forEach((panel, i)=>{
-            panel.isHighlighted = false
-        })
-    }
+    windows.forEach((panel, i) => {
+        panel.isHighlighted = (i == 2 * windowMode)
+    })
     if (windowMode) {
         RIGHTPANEL.drawContents()
         RIGHTPANEL.drawFrame()
@@ -683,14 +674,6 @@ function drawOpPanel() {
     OPPANEL.drawFrame()
 }
 
-function drawPopupPanel() {
-    if (currentPopup) {
-        windows[currentPopup][0].drawContents()
-        windows[currentPopup][0].drawFrame()
-    }
-}
-
-
 function redraw() {
     redrawRequested = true
 }
@@ -700,7 +683,7 @@ function _redraw() {
     drawTitle()
     drawFilePanel()
     drawOpPanel()
-    drawPopupPanel()
+    setupPanelMouseRegions()
 }
 
 function clearScr() {
@@ -708,6 +691,402 @@ function clearScr() {
     graphics.setBackground(34,51,68)
     graphics.clearPixels(255)
     graphics.setGraphicsMode(0)
+    con.color_pair(COL_TEXT, COL_BACK)
+}
+
+///////////////////////////////////////////////////////////////////////////////////////////////////
+// File operations and op-panel actions
+///////////////////////////////////////////////////////////////////////////////////////////////////
+
+function getCurrentDirStr(side) {
+    return path[side].concat(['']).join("\\").replaceAll('\\\\', '\\')
+}
+
+function clampCursorAfterChange() {
+    const len = dirFileList[windowMode].length
+    if (cursor[windowMode] >= len) cursor[windowMode] = Math.max(0, len - 1)
+    const maxScroll = Math.max(0, len - LIST_HEIGHT)
+    if (scroll[windowMode] > maxScroll) scroll[windowMode] = maxScroll
+    if (scroll[windowMode] < 0) scroll[windowMode] = 0
+}
+
+function actSwitchPanel() {
+    windowMode = 1 - windowMode
+    redraw()
+}
+
+function actGoUp() {
+    if (path[windowMode].length >= 1) {
+        path[windowMode].pop()
+        cursor[windowMode] = 0; scroll[windowMode] = 0
+        refreshFilePanelCache(windowMode)
+        _redraw()
+    }
+}
+
+function actActivate() {
+    let selectedFileCache = filePanelCache[windowMode][cursor[windowMode]]
+    if (!selectedFileCache || !selectedFileCache.file) return
+    let selectedFile = selectedFileCache.file
+
+    if (selectedFile.fullPath[1] == ":" && selectedFile.fullPath[2] == "\\" && selectedFile.fullPath.length == 3) {
+        path[windowMode].push(selectedFile.fullPath)
+        cursor[windowMode] = 0; scroll[windowMode] = 0
+        refreshFilePanelCache(windowMode)
+        _redraw()
+    }
+    else if (selectedFileCache.isDirectory) {
+        path[windowMode].push(selectedFileCache.filename)
+        cursor[windowMode] = 0; scroll[windowMode] = 0
+        refreshFilePanelCache(windowMode)
+        _redraw()
+    }
+    else {
+        let fileext = selectedFileCache.filename.substring(selectedFileCache.filename.lastIndexOf(".") + 1).toLowerCase()
+        let execfun = EXEC_FUNS[fileext] || ((f) => _G.shell.execute(f))
+        let errorlevel = 0
+
+        con.curs_set(1); clearScr(); con.move(1,1)
+        try {
+            errorlevel = execfun(selectedFile.fullPath)
+        }
+        catch (e) {
+            println(e)
+            errorlevel = 1
+        }
+
+        if (errorlevel) {
+            println("Hit Return/Enter key to continue . . . .")
+            sys.read()
+        }
+
+        firstRunLatch = true
+        con.curs_set(0); clearScr()
+        refreshFilePanelCache(windowMode)
+        pendingPostExecDrain = true
+        redraw()
+    }
+}
+
+function actCopy() {
+    if (path[windowMode].length === 0) return
+    const cache = filePanelCache[windowMode][cursor[windowMode]]
+    if (!cache || !cache.file) return
+    if (cache.isDirectory) { showMessagePopup('Copy', 'Directory copy is not supported.'); _redraw(); return }
+    if (path[1 - windowMode].length === 0) { showMessagePopup('Copy', 'Cannot copy to drive list view.'); _redraw(); return }
+
+    const srcPath = cache.file.fullPath
+    const dstDir = getCurrentDirStr(1 - windowMode)
+    const dstPath = dstDir + cache.file.name
+    if (srcPath === dstPath) { _redraw(); return } // both panels point to same directory
+
+    try {
+        const srcFile = files.open(srcPath)
+        const dstFile = files.open(dstPath)
+        if (!srcFile.exists) { showMessagePopup('Copy', 'Source not found.'); _redraw(); return }
+        if (dstFile.exists) {
+            if (!showConfirmPopup('Copy', `Overwrite "${cache.file.name}"?`)) { _redraw(); return }
+        }
+        if (!dstFile.exists) dstFile.mkFile()
+        dstFile.bwrite(srcFile.bread())
+        try { dstFile.flush() } catch (e) {}
+        try { dstFile.close() } catch (e) {}
+        try { srcFile.close() } catch (e) {}
+        refreshFilePanelCache(1 - windowMode)
+    }
+    catch (e) {
+        showMessagePopup('Copy failed', e.message || ('' + e))
+    }
+    _redraw()
+}
+
+function actMove() {
+    if (path[windowMode].length === 0) return
+    const cache = filePanelCache[windowMode][cursor[windowMode]]
+    if (!cache || !cache.file) return
+    if (cache.isDirectory) { showMessagePopup('Move', 'Directory move is not supported.'); _redraw(); return }
+    if (path[1 - windowMode].length === 0) { showMessagePopup('Move', 'Cannot move to drive list view.'); _redraw(); return }
+
+    const srcPath = cache.file.fullPath
+    const dstDir = getCurrentDirStr(1 - windowMode)
+    const dstPath = dstDir + cache.file.name
+    if (srcPath === dstPath) { _redraw(); return } // no-op
+
+    try {
+        const srcFile = files.open(srcPath)
+        const dstFile = files.open(dstPath)
+        if (!srcFile.exists) { showMessagePopup('Move', 'Source not found.'); _redraw(); return }
+        if (dstFile.exists) {
+            if (!showConfirmPopup('Move', `Overwrite "${cache.file.name}"?`)) { _redraw(); return }
+        }
+        if (!dstFile.exists) dstFile.mkFile()
+        dstFile.bwrite(srcFile.bread())
+        try { dstFile.flush() } catch (e) {}
+        try { dstFile.close() } catch (e) {}
+        srcFile.remove()
+        refreshFilePanelCache(windowMode)
+        refreshFilePanelCache(1 - windowMode)
+        clampCursorAfterChange()
+    }
+    catch (e) {
+        showMessagePopup('Move failed', e.message || ('' + e))
+    }
+    _redraw()
+}
+
+function actDelete() {
+    if (path[windowMode].length === 0) return
+    const cache = filePanelCache[windowMode][cursor[windowMode]]
+    if (!cache || !cache.file) return
+
+    const name = cache.file.name
+    const kind = cache.isDirectory ? 'directory' : 'file'
+    if (!showConfirmPopup('Delete', `Delete ${kind} "${name}"?`)) { _redraw(); return }
+
+    try {
+        const status = cache.file.remove()
+        if (status !== undefined && status !== 0 && status !== true) {
+            showMessagePopup('Delete failed', `Cannot delete "${name}" (status ${status}).`)
+        }
+        refreshFilePanelCache(windowMode)
+        clampCursorAfterChange()
+    }
+    catch (e) {
+        showMessagePopup('Delete failed', e.message || ('' + e))
+    }
+    _redraw()
+}
+
+function actMkdir() {
+    if (path[windowMode].length === 0) { showMessagePopup('Mkdir', 'Choose a directory first.'); _redraw(); return }
+    const name = showInputPopup('Make Directory', 'Directory name:', '')
+    if (name === null || name.length === 0) { _redraw(); return }
+
+    const dstPath = getCurrentDirStr(windowMode) + name
+    try {
+        const dstFile = files.open(dstPath)
+        if (dstFile.exists) {
+            showMessagePopup('Mkdir', `"${name}" already exists.`)
+        }
+        else {
+            const ok = dstFile.mkDir()
+            if (!ok) showMessagePopup('Mkdir failed', `Cannot create "${name}".`)
+            else refreshFilePanelCache(windowMode)
+        }
+    }
+    catch (e) {
+        showMessagePopup('Mkdir failed', e.message || ('' + e))
+    }
+    _redraw()
+}
+
+function actRename() {
+    if (path[windowMode].length === 0) return
+    const cache = filePanelCache[windowMode][cursor[windowMode]]
+    if (!cache || !cache.file) return
+    if (cache.isDirectory) { showMessagePopup('Rename', 'Directory rename is not supported.'); _redraw(); return }
+
+    const oldName = cache.file.name
+    const newName = showInputPopup('Rename', 'New name:', oldName)
+    if (newName === null || newName.length === 0 || newName === oldName) { _redraw(); return }
+
+    const dirStr = getCurrentDirStr(windowMode)
+    const srcPath = cache.file.fullPath
+    const dstPath = dirStr + newName
+
+    try {
+        const srcFile = files.open(srcPath)
+        const dstFile = files.open(dstPath)
+        if (dstFile.exists) {
+            if (!showConfirmPopup('Rename', `Overwrite "${newName}"?`)) { _redraw(); return }
+        }
+        if (!dstFile.exists) dstFile.mkFile()
+        dstFile.bwrite(srcFile.bread())
+        try { dstFile.flush() } catch (e) {}
+        try { dstFile.close() } catch (e) {}
+        srcFile.remove()
+        refreshFilePanelCache(windowMode)
+        clampCursorAfterChange()
+    }
+    catch (e) {
+        showMessagePopup('Rename failed', e.message || ('' + e))
+    }
+    _redraw()
+}
+
+function actMore() {
+    if (path[windowMode].length === 0) return
+    const cache = filePanelCache[windowMode][cursor[windowMode]]
+    if (!cache || !cache.file) return
+
+    const items = cache.isDirectory
+        ? [
+            { label: 'Open terminal here', action: 'terminal', default: true },
+        ]
+        : [
+            { label: 'Execute',            action: 'execute', default: true },
+            { label: 'Edit',               action: 'edit' },
+            { label: 'Open terminal here', action: 'terminal' },
+        ]
+
+    const res = showActionListPopup({
+        title: 'More',
+        message: cache.file.name,
+        items: items,
+    })
+    _redraw()
+
+    if (res.action === 'execute') {
+        actActivate()
+        return
+    }
+    if (res.action === 'edit') {
+        const editfun = EDIT_FUNS[cache.fileext]
+            || ((f) => _G.shell.execute(`${DEFAULT_EDITOR} "${f}"`))
+        let errorlevel = 0
+        con.curs_set(1); clearScr(); con.move(1, 1)
+        try {
+            errorlevel = editfun(cache.file.fullPath)
+        }
+        catch (e) {
+            println(e)
+            errorlevel = 1
+        }
+        if (errorlevel) {
+            println("Hit Return/Enter key to continue . . . .")
+            sys.read()
+        }
+        firstRunLatch = true
+        con.curs_set(0); clearScr()
+        refreshFilePanelCache(windowMode)
+        pendingPostExecDrain = true
+        redraw()
+        return
+    }
+    if (res.action === 'terminal') {
+        actTerminal(cache)
+    }
+}
+
+function actTerminal(cache) {
+    const targetDir = (cache && cache.isDirectory && cache.file)
+        ? cache.file.fullPath
+        : getCurrentDirStr(windowMode)
+    if (!targetDir || targetDir.length === 0) return
+
+    // TVDOS shell.parse has no working escape inside quotes (the `^` ESCAPE
+    // state is a TODO), so we can't pass a quoted path through `command -k
+    // "cd \"X\""`. The outer quotes carry the whole `cd <path>` as one token;
+    // shell.execute then re-parses it. This works for paths without spaces;
+    // paths with spaces will only cd to the first component.
+    let errorlevel = 0
+    con.curs_set(1); clearScr(); con.move(1, 1)
+    try {
+        errorlevel = _G.shell.execute(`command -k "cd ${targetDir}"`)
+    }
+    catch (e) {
+        println(e)
+        errorlevel = 1
+    }
+    if (errorlevel) {
+        println("Hit Return/Enter key to continue . . . .")
+        sys.read()
+    }
+    firstRunLatch = true
+    con.curs_set(0); clearScr()
+    refreshFilePanelCache(windowMode)
+    pendingPostExecDrain = true
+    redraw()
+}
+function actQuit() { exit = true }
+
+function invokeOpAction(id) {
+    if      (id === 'switch') actSwitchPanel()
+    else if (id === 'up')     actGoUp()
+    else if (id === 'copy')   actCopy()
+    else if (id === 'move')   actMove()
+    else if (id === 'delete') actDelete()
+    else if (id === 'mkdir')  actMkdir()
+    else if (id === 'rename') actRename()
+    else if (id === 'more')   actMore()
+    else if (id === 'quit')   actQuit()
+}
+
+///////////////////////////////////////////////////////////////////////////////////////////////////
+// Mouse region setup (file list + op buttons)
+///////////////////////////////////////////////////////////////////////////////////////////////////
+
+function setupPanelMouseRegions() {
+    clearPanelMouseRegions()
+
+    const fp = (windowMode === 0) ? LEFTPANEL : RIGHTPANEL
+    const fpX = fp.x + 1
+    const fpW = fp.width - 2
+    const fpY = fp.y + 2  // first file row (after frame top + header)
+
+    // Wheel-scroll over the file list. Wheel and keyboard are the only inputs allowed
+    // to move the scroll position; hover (below) only moves the caret.
+    addPanelMouseRegion(fpX, fpY, fpW, LIST_HEIGHT, {
+        onWheel: (cy, cx, dy) => {
+            const filesCount = dirFileList[windowMode].length
+            const maxScroll = Math.max(0, filesCount - LIST_HEIGHT)
+            let s = scroll[windowMode] + dy * 3
+            if (s > maxScroll) s = maxScroll
+            if (s < 0) s = 0
+            if (s !== scroll[windowMode]) {
+                scroll[windowMode] = s
+                drawFilePanel()
+            }
+        }
+    })
+
+    // One hover/click region per row so the caret can follow the mouse without
+    // calling scrollVert (which would re-scroll the list near the upper/lower thirds).
+    for (let i = 0; i < LIST_HEIGHT; i++) {
+        const rowIdx = i
+        addPanelMouseRegion(fpX, fpY + i, fpW, 1, {
+            onHover: () => {
+                const target = scroll[windowMode] + rowIdx
+                if (target < dirFileList[windowMode].length && cursor[windowMode] !== target) {
+                    cursor[windowMode] = target
+                    drawFilePanel()
+                }
+            },
+            onClick: (cy, cx, btn) => {
+                const target = scroll[windowMode] + rowIdx
+                if (target >= dirFileList[windowMode].length) return
+                if (btn === 1) {
+                    cursor[windowMode] = target
+                    actActivate()
+                }
+                else if (btn === 2) {
+                    cursor[windowMode] = target
+                    drawFilePanel()
+                    actMore()
+                }
+            }
+        })
+    }
+
+    // Op-panel button hover/click. Each button covers its icon row + label row.
+    const opX = OPPANEL.x + 1
+    const opW = SIDEBAR_WIDTH - 2
+    for (let i = 0; i < OP_BUTTONS.length; i++) {
+        const idx = i
+        const btn = OP_BUTTONS[i]
+        addPanelMouseRegion(opX, OPPANEL.y + 1 + btn.yOff, opW, btn.hitH || 2, {
+            onHover: () => {
+                if (opHover !== idx) { opHover = idx; drawOpPanel() }
+            },
+            onHoverLeave: () => {
+                if (opHover === idx) { opHover = -1; drawOpPanel() }
+            },
+            onClick: (cy, cx, btnNum) => {
+                if (btnNum !== 1) return
+                invokeOpAction(btn.id)
+            }
+        })
+    }
 }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
@@ -717,13 +1096,35 @@ refreshFilePanelCache(0)
 refreshFilePanelCache(1)
 _redraw()
 
+// Drain inherited mouse/key state from whoever launched us. Polling launchers
+// like fsh.js can hand off with the mouse button still held; without this,
+// input.withEvent's first call edge-detects that as a fresh mouse_down at the
+// cursor and activates whichever file row happens to sit there.
+//
+// The same problem reappears after every child app returns, but draining
+// inside the dispatcher callback is undone by TVDOS.SYS:1235 (input.withEvent
+// unconditionally writes inputwork.oldMouse = its-stale-local-snapshot at the
+// end of the outer call). So actActivate / actMore set pendingPostExecDrain
+// and the main loop calls drainInheritedInput() AFTER input.withEvent returns.
+function drainInheritedInput() { input.withEvent(() => {}) }
+drainInheritedInput()
+
 let redrawRequested = false
 let exit = false
 let firstRunLatch = true
+let pendingPostExecDrain = false
 
 while (!exit) {
     input.withEvent(event => {
 
+        if (dispatchMouseEvent(event)) {
+            if (redrawRequested) {
+                redrawRequested = false
+                _redraw()
+            }
+            return
+        }
+
         let keysym = event[1]
         let keyJustHit = (1 == event[2])
 
@@ -735,7 +1136,7 @@ while (!exit) {
             firstRunLatch = false
         }
         else {
-            windows[windowFocus.last()].forEach(it => {
+            windows.forEach(it => {
                 if (it.isHighlighted) { // double input processing without this? wtf?!
                     it.processInput(event)
                 }
@@ -747,6 +1148,16 @@ while (!exit) {
             _redraw()
         }
     })
+
+    // Re-baseline mouse state AFTER input.withEvent returns so its trailing
+    // `inputwork.oldMouse = mouse` (TVDOS.SYS:1235) doesn't overwrite the
+    // freshly-correct state with the stale snapshot taken at the start of the
+    // outer call. Without this, a child app exited by a click leaves zfm with
+    // oldBtns=0 while the user is still holding → spurious mouse_down next poll.
+    if (pendingPostExecDrain) {
+        pendingPostExecDrain = false
+        drainInheritedInput()
+    }
 }
 
 con.curs_set(1)

assets/disk0/tvdos/include/playgui.mjs

@@ -281,9 +281,997 @@ function printTopBar(status, moreInfo) {
     con.move(1, 1)
 }
 
+// ── Audio player visualiser ─────────────────────────────────────────────────
+// Shared by playwav/playmp2/playpcm/playtad.  Design follows
+// `assets/playwav_visualiser_design_2_for_tsvm.md`:
+//   * 3-row ASCII wavescope (mid signal envelope) on rows 3..5
+//   * 22-col progress dashes on the right side of the song-title row
+//   * 24-row XY-scope + wavelet-modulated persistence visualiser on rows 7..30
+//   * stereo energy bar on row 31
+//
+// The visualiser fuses two displays the design doc calls complementary:
+//   * XY-scope geometry (rotated 45° so L plots along the `\` diagonal and R
+//     along `/`) gives spatial motion and stereo image.
+//   * Haar wavelet features (transient / noise / sustain energies) steer the
+//     beam's behaviour — transients evaporate it and emit sparks, sustained
+//     content lets trails breathe longer, mid noise jitters the beam.
+//
+// The wavelet is therefore a *modulator*, not a renderer.  No FFT, no pitch
+// tracking, no per-frame allocation in the hot loop.
+
+const AG_COLS = 80
+const AG_ROWS = 32
+const AG_COL_INSIDE_L = 2
+const AG_COL_INSIDE_R = 79
+const AG_LANE_W       = 78
+
+const AG_ROW_TOP_BORDER = 1
+const AG_ROW_TITLE      = 2
+const AG_ROW_WAVE_TOP   = 3
+const AG_ROW_WAVE_BOT   = 5     // 3-row wavescope
+const AG_ROW_VIS_SEP    = 6
+const AG_ROW_VIS_TOP    = 7
+const AG_ROW_VIS_BOT    = 30    // 24-row wavelet visualiser
+const AG_ROW_STEREO     = 31
+const AG_ROW_BOT_BORDER = 32
+
+const AG_VIS_H = AG_ROW_VIS_BOT - AG_ROW_VIS_TOP + 1   // 24
+const AG_VIS_W = AG_LANE_W                              // 78
+
+// Palette (TSVM 256-colour indices)
+const AG_COL_BG       = 0
+const AG_COL_BORDER   = 250
+const AG_COL_LABEL    = 220
+const AG_COL_DIM      = 235
+const AG_COL_TITLE    = 230
+const AG_COL_VALUE    = 254
+const AG_COL_PROG_ON  = 226     // bright yellow (matches Taud)
+
+// Box-drawing constants (CP437)
+const AG_BX_TL = 0xC9, AG_BX_TR = 0xBB, AG_BX_BL = 0xC8, AG_BX_BR = 0xBC
+const AG_BX_V  = 0xBA, AG_BX_H  = 0xCD
+const AG_SEP_L = 0xC7, AG_SEP_R = 0xB6
+
+// Density stairs for visualiser + stereo bar
+const AG_STAIRS = [0x20, 0xB0, 0xB1, 0xB2, 0xDB]   // ' ', ░, ▒, ▓, █
+
+// Electron-beam colour ramp.  Index 0 = silent (background), last = freshly
+// drawn beam.  Amber-on-black mimics analog vector-scope CRT phosphor — the
+// glyph shape carries the spatial information, the colour ramp carries age.
+const AG_BEAM_PAL = [AG_COL_BG, 94, 130, 166, 220]
+
+// Five wavelet levels (Haar decomp).  These are used only as modulators —
+// they never get rendered as bars.  Indexing:
+//   AG_WL_TRANSIENT — top-octave detail (8 kHz..16 kHz at 32 kHz Fs).
+//                     Spikes on percussion attacks, vocal consonants, cymbals.
+//   AG_WL_NOISE     — upper-mid detail (4..8 kHz).  Drives beam jitter.
+//   AG_WL_BODY      — mid detail (2..4 kHz).
+//   AG_WL_TONAL     — lower-mid detail (1..2 kHz).
+//   AG_WL_BASS      — low detail (0.5..1 kHz).  Slows the decay (sustain).
+const AG_N_BANDS    = 5
+const AG_WL_TRANSIENT = 0
+const AG_WL_NOISE     = 1
+const AG_WL_BODY      = 2
+const AG_WL_TONAL     = 3
+const AG_WL_BASS      = 4
+
+// Stereo bar colour ramp (5 levels) — uses the tonal blue gradient so the
+// stereo strip reads as the "ground" beneath the wavelet cloud.
+const AG_STEREO_COL = [AG_COL_DIM, 17, 33, 75, 117]
+
+// ── State ───────────────────────────────────────────────────────────────────
+//
+// All state lives in module scope so a player just does:
+//     const gui = require('playgui')
+//     gui.audioInit({...})
+//     while (...) { ...; gui.audioFeedPcm(ptr, n); gui.audioRender(); }
+//     gui.audioClose()
+//
+// Multiple concurrent players in one process are not supported — but TVDOS
+// only runs one foreground command at a time, so that's fine.
+
+const AG_SNAPSHOT_N = 1024   // power of 2; covers ~32 ms at 32 kHz
+const ag_snapL = new Float32Array(AG_SNAPSHOT_N)
+const ag_snapR = new Float32Array(AG_SNAPSHOT_N)
+
+const AG_WORK_N = AG_SNAPSHOT_N   // scratch buffers for Haar pyramid
+const ag_workMid = new Float32Array(AG_WORK_N)
+const ag_workTmp = new Float32Array(AG_WORK_N >> 1)
+const ag_bandEnergy = new Float32Array(AG_N_BANDS)
+
+// Sub-500 Hz residual — drops out of the wavelet modulator set on purpose,
+// but we keep its RMS around to drive the bass mark.
+let ag_bassEnergy = 0
+
+// Persistence buffer — float intensity per cell, plus the glyph last written
+// there.  Decay shrinks intensity each frame; new beam samples overwrite the
+// glyph and bump intensity.
+const ag_persist      = new Float32Array(AG_VIS_H * AG_VIS_W)
+const ag_persistGlyph = new Int16Array(AG_VIS_H * AG_VIS_W)
+
+// Skip-redraw cache — only emit a cell when its glyph or colour changes.
+const ag_cellGlyph = new Int16Array(AG_VIS_H * AG_VIS_W).fill(-1)
+const ag_cellFg    = new Int16Array(AG_VIS_H * AG_VIS_W).fill(-1)
+const ag_waveGlyph = new Int16Array(AG_LANE_W * 3).fill(-1)
+const ag_stereoGlyph = new Int16Array(AG_LANE_W).fill(-1)
+const ag_stereoFg    = new Int16Array(AG_LANE_W).fill(-1)
+let ag_lastBassFg    = -1
+
+// Render rate-limiter — playmp2 spins ~32 Hz, playtad ~1 Hz, playwav ~100 Hz
+// at decode time.  Clamp visual refresh to 20 Hz so each caller can spam
+// audioRender() without worrying about pacing.
+let ag_lastRenderNs = 0
+const AG_RENDER_INTERVAL_NS = 50 * 1000 * 1000   // 50 ms
+
+// Latest progress fraction so we redraw the bar only when it changes.
+let ag_lastProgressIdx = -1
+let ag_lastTimeStr = ''
+
+// Init params held for re-use during render.
+let ag_initParams = null
+
+function ag_color(fg, bg) { con.color_pair(fg, bg) }
+function ag_mvprn(row, col, ch) { con.mvaddch(row, col, ch) }
+function ag_mvtext(row, col, s) { con.move(row, col); print(s) }
+
+function ag_pad(n, w) {
+    let s = '' + n
+    while (s.length < w) s = ' ' + s
+    return s
+}
+
+function ag_secToReadable(n) {
+    const mins = ('' + ((n / 60) | 0)).padStart(2, '0')
+    const secs = ('' + (n % 60)).padStart(2, '0')
+    return mins + ':' + secs
+}
+
+function ag_drawSeparator(row, label) {
+    ag_color(AG_COL_BORDER, AG_COL_BG)
+    ag_mvprn(row, 1, AG_SEP_L)
+    for (let x = 2; x < AG_COLS; x++) ag_mvprn(row, x, AG_BX_H)
+    ag_mvprn(row, AG_COLS, AG_SEP_R)
+    if (label) {
+        ag_color(AG_COL_LABEL, AG_COL_BG)
+        ag_mvtext(row, 5, ' ' + label + ' ')
+    }
+}
+
+function ag_drawFrame() {
+    // Top border with embedded format tag.
+    ag_color(AG_COL_BORDER, AG_COL_BG)
+    ag_mvprn(AG_ROW_TOP_BORDER, 1, AG_BX_TL)
+    for (let x = 2; x < AG_COLS; x++) ag_mvprn(AG_ROW_TOP_BORDER, x, AG_BX_H)
+    ag_mvprn(AG_ROW_TOP_BORDER, AG_COLS, AG_BX_TR)
+    if (ag_initParams.tag) {
+        ag_color(AG_COL_LABEL, AG_COL_BG)
+        ag_mvtext(AG_ROW_TOP_BORDER, 4, ' ' + ag_initParams.tag + ' ')
+    }
+
+    // Bottom border with exit hint.
+    ag_color(AG_COL_BORDER, AG_COL_BG)
+    ag_mvprn(AG_ROW_BOT_BORDER, 1, AG_BX_BL)
+    for (let x = 2; x < AG_COLS; x++) ag_mvprn(AG_ROW_BOT_BORDER, x, AG_BX_H)
+    ag_mvprn(AG_ROW_BOT_BORDER, AG_COLS, AG_BX_BR)
+    ag_color(AG_COL_DIM, AG_COL_BG)
+    ag_mvtext(AG_ROW_BOT_BORDER, 4, ' Hold BkSp to exit ')
+
+    // Side bars.
+    ag_color(AG_COL_BORDER, AG_COL_BG)
+    for (let r = 2; r < AG_ROWS; r++) {
+        ag_mvprn(r, 1, AG_BX_V)
+        ag_mvprn(r, AG_COLS, AG_BX_V)
+    }
+
+    // Inner separator over the visualiser canvas.  The wavescope strip sits
+    // flush against the title row — no separator there.
+    ag_drawSeparator(AG_ROW_VIS_SEP, 'VISUALS')
+}
+
+function ag_clearInside(row) {
+    ag_color(AG_COL_DIM, AG_COL_BG)
+    con.move(row, AG_COL_INSIDE_L)
+    print(' '.repeat(AG_LANE_W))
+}
+
+function ag_drawTitle() {
+    ag_clearInside(AG_ROW_TITLE)
+    let title = ag_initParams.title || ''
+    // Reserve 24 cols on the right for time string + progress bar.
+    if (title.length > AG_LANE_W - 26) title = title.substring(0, AG_LANE_W - 29) + '...'
+    ag_color(AG_COL_TITLE, AG_COL_BG)
+    ag_mvtext(AG_ROW_TITLE, AG_COL_INSIDE_L + 1, title)
+}
+
+// Progress: time string + 22-wide dashes ramp (matches playtaud).  Called by
+// the player via audioSetProgress; redraws only when something changed.
+function ag_drawProgress(progress, elapsedSec, totalSec) {
+    const barW = 22
+    const bx0 = AG_COL_INSIDE_R - barW
+    const filled = Math.round(progress * barW)
+
+    const timeStr = ag_secToReadable(elapsedSec) + '/' + ag_secToReadable(totalSec)
+    if (timeStr !== ag_lastTimeStr) {
+        ag_lastTimeStr = timeStr
+        ag_color(AG_COL_VALUE, AG_COL_BG)
+        ag_mvtext(AG_ROW_TITLE, bx0 - timeStr.length - 1, timeStr)
+    }
+
+    if (filled === ag_lastProgressIdx) return
+    ag_lastProgressIdx = filled
+
+    for (let i = 0; i < barW; i++) {
+        const lit = i < filled
+        ag_color(lit ? AG_COL_PROG_ON : AG_COL_DIM, AG_COL_BG)
+        ag_mvprn(AG_ROW_TITLE, bx0 + i, lit ? 0x7C /*│*/ : 0x2E /*.*/)
+    }
+}
+
+// ── PCM ingestion ───────────────────────────────────────────────────────────
+//
+// feedPcm copies the most recent SNAPSHOT_N samples from a PCMu8-stereo-
+// interleaved buffer into our snapshot.  `ptr` can be a positive heap address
+// (LPCM/ADPCM decoded buffer, raw PCM) or a negative peripheral address (TAD
+// decoded buffer, MP2 mediaDecodedBin) — TSVM peripheral memory grows toward
+// 0, so reads use a signed step `vec`.
+
+function audioFeedPcm(ptr, sampleCount) {
+    if (!sampleCount) return
+    const vec = ptr >= 0 ? 1 : -1
+    const inv128 = 1 / 128
+
+    if (sampleCount >= AG_SNAPSHOT_N) {
+        // Take last AG_SNAPSHOT_N samples — discard the rest.
+        const start = sampleCount - AG_SNAPSHOT_N
+        for (let i = 0; i < AG_SNAPSHOT_N; i++) {
+            const off = (start + i) * 2 * vec
+            ag_snapL[i] = ((sys.peek(ptr + off) & 0xFF) - 128) * inv128
+            ag_snapR[i] = ((sys.peek(ptr + off + vec) & 0xFF) - 128) * inv128
+        }
+    } else {
+        // Shift snapshot left by `sampleCount` and append all new samples.
+        const shift = sampleCount
+        const keep  = AG_SNAPSHOT_N - shift
+        for (let i = 0; i < keep; i++) {
+            ag_snapL[i] = ag_snapL[i + shift]
+            ag_snapR[i] = ag_snapR[i + shift]
+        }
+        for (let i = 0; i < shift; i++) {
+            const off = i * 2 * vec
+            ag_snapL[keep + i] = ((sys.peek(ptr + off) & 0xFF) - 128) * inv128
+            ag_snapR[keep + i] = ((sys.peek(ptr + off + vec) & 0xFF) - 128) * inv128
+        }
+    }
+}
+
+// ── Wavelet analysis ───────────────────────────────────────────────────────
+//
+// In-place Haar decomposition.  Five levels on 1024 samples gives band
+// passes (at 32 kHz): [8k..16k], [4k..8k], [2k..4k], [1k..2k], [500..1k].
+// Sub-500 Hz ends up in the approximation and is intentionally dropped —
+// otherwise the bass would dominate every track.
+
+function ag_analyseHaar() {
+    // mid = (L + R) / 2
+    for (let i = 0; i < AG_SNAPSHOT_N; i++) {
+        ag_workMid[i] = (ag_snapL[i] + ag_snapR[i]) * 0.5
+    }
+    let len = AG_SNAPSHOT_N
+    const SQ_HALF = 0.70710678   // 1/sqrt(2) keeps L2 norm
+    for (let lv = 0; lv < AG_N_BANDS; lv++) {
+        const half = len >> 1
+        let sumSq = 0
+        for (let i = 0; i < half; i++) {
+            const a = ag_workMid[i * 2]
+            const b = ag_workMid[i * 2 + 1]
+            const lo = (a + b) * SQ_HALF
+            const hi = (a - b) * SQ_HALF
+            ag_workMid[i] = lo
+            ag_workTmp[i] = hi
+            sumSq += hi * hi
+        }
+        // Higher-freq levels naturally have weaker energy in music; scale
+        // each band by an empirical gain so all five read at comparable
+        // brightness on typical material.
+        const gain = 3.0 + lv * 1.5
+        const rms = Math.sqrt(sumSq / half) * gain
+        ag_bandEnergy[lv] = rms > 1 ? 1 : rms
+        len = half
+    }
+    // Residual approximation in ag_workMid[0..len-1] holds the sub-500 Hz
+    // energy that the modulator pipeline intentionally discards.  Reuse it
+    // to drive the bass mark.
+    let bassSumSq = 0
+    for (let i = 0; i < len; i++) {
+        const v = ag_workMid[i]
+        bassSumSq += v * v
+    }
+    const bassRms = Math.sqrt(bassSumSq / len) * 1.8
+    ag_bassEnergy = bassRms > 1 ? 1 : bassRms
+}
+
+// ── Mini-AAlib (embedded, for the wavescope) ───────────────────────────────
+//
+// Stripped port of `disk0/hopper/include/aa.mjs`, sized to one job: convert a
+// small pixel-space brightness buffer into ASCII glyphs with three monochrome
+// intensities (DIM / NORMAL / BOLD).  No dither.  No brightness / contrast /
+// gamma / inversion.  No REVERSE / SPECIAL / BOLDFONT attribute support.
+// See aa.mjs for the full algorithm, credits (Jan Hubicka & the AA-group,
+// 1997), and the long-form comments — those are not duplicated here.
+//
+// Tables (params + 65536-entry LUT + filltable) are built once on first use
+// from the TSVM 7×14 font ROM, so the wavescope's glyph-selection matches the
+// brightness profile of the cells the hardware text mode actually paints.
+
+const AA_FONT_PATH = "A:/tvdos/tsvm.chr"
+const AA_NORMAL = 0
+const AA_DIM    = 1
+const AA_BOLD   = 2
+const AA_NATTRS = 3
+const AA_NCHARS = 256 * AA_NATTRS
+const AA_DIMMUL  = 5.3
+const AA_BOLDMUL = 2.7
+const AA_MUL = 8
+const AA_VAL = 13                          // uniform-cell threshold
+const AA_PRIORITY = [4, 5, 3]              // NORMAL, DIM, BOLD (matches aalib)
+
+let aa_font = null                         // { width, height, data }
+let aa_params = null                       // Uint16Array((NCHARS+1)*5)
+let aa_table = null                        // Uint16Array(65536)
+let aa_filltable = null                    // Uint16Array(256)
+
+function aa_loadFont() {
+    if (aa_font) return aa_font
+    const fh = files.open(AA_FONT_PATH)
+    if (!fh.exists) throw Error("playgui: font ROM not found: " + AA_FONT_PATH)
+    const blob = fh.bread()
+    const FW = 7, FH = 14, ROM = 1920
+    if (blob.length !== ROM && blob.length !== ROM * 2) {
+        throw Error("playgui: bad font ROM size " + blob.length)
+    }
+    const data = new Uint8Array(256 * FW * FH)
+    const halves = blob.length / ROM
+    const startHalf = (halves === 2) ? 0 : 1
+    for (let h = 0; h < halves; h++) {
+        const romStart = h * ROM
+        const charBase = (startHalf + h) * 128
+        for (let c = 0; c < 128; c++) {
+            const srcBase = romStart + c * FH
+            const dstBase = (charBase + c) * FW * FH
+            for (let r = 0; r < FH; r++) {
+                const b = blob[srcBase + r] & 0xFF
+                for (let x = 0; x < FW; x++) {
+                    data[dstBase + r * FW + x] = ((b >> (6 - x)) & 1) ? 0xFF : 0x00
+                }
+            }
+        }
+    }
+    aa_font = { width: FW, height: FH, data: data }
+    return aa_font
+}
+
+function aa_alowed(i) {
+    const c = i & 0xff
+    const attr = (i >>> 8)
+    if (attr >= AA_NATTRS) return false
+    // printable ASCII, space, or extended (>160) — keep AA_EIGHT chars so the
+    // glyph palette includes the TSVM ROM's box-drawing / shade / dot range.
+    if (!(c >= 33 && c <= 126) && c !== 0x20 && !(c > 160)) return false
+    return true
+}
+
+// (NE, NW, SE, SW) brightness for glyph `code` under `attr`. Quadrant labelling
+// follows aalib's bit-numbering quirk; the LUT lookup later swaps the halves
+// back to natural orientation. See aa.mjs:_glyphValues for the long-form note.
+function aa_glyphValues(code, attr, out) {
+    const fd = aa_font.data
+    const fw = aa_font.width
+    const fh = aa_font.height
+    const base = code * fw * fh
+    const halfW = fw >> 1
+    const halfH = fh >> 1
+    const leftW = halfW
+    const topH  = halfH
+    let v1 = 0, v2 = 0, v3 = 0, v4 = 0
+    for (let r = 0; r < topH; r++) {
+        const rowBase = base + r * fw
+        for (let x = 0; x < leftW; x++) if (fd[rowBase + x]) v2++
+        for (let x = leftW; x < fw;   x++) if (fd[rowBase + x]) v1++
+    }
+    for (let r = topH; r < fh; r++) {
+        const rowBase = base + r * fw
+        for (let x = 0; x < leftW; x++) if (fd[rowBase + x]) v4++
+        for (let x = leftW; x < fw;   x++) if (fd[rowBase + x]) v3++
+    }
+    v1 *= AA_MUL; v2 *= AA_MUL; v3 *= AA_MUL; v4 *= AA_MUL
+    if (attr === AA_DIM) {
+        v1 = (v1 + 1) / AA_DIMMUL
+        v2 = (v2 + 1) / AA_DIMMUL
+        v3 = (v3 + 1) / AA_DIMMUL
+        v4 = (v4 + 1) / AA_DIMMUL
+    } else if (attr === AA_BOLD) {
+        v1 *= AA_BOLDMUL
+        v2 *= AA_BOLDMUL
+        v3 *= AA_BOLDMUL
+        v4 *= AA_BOLDMUL
+    }
+    out[0] = v1; out[1] = v2; out[2] = v3; out[3] = v4
+}
+
+function aa_calcparams() {
+    aa_loadFont()
+    aa_params = new Uint16Array((AA_NCHARS + 1) * 5)
+    const tmp = new Float64Array(4)
+    let ma1 = 0, ma2 = 0, ma3 = 0, ma4 = 0, msum = 0
+    let mi1 = 50000, mi2 = 50000, mi3 = 50000, mi4 = 50000, misum = 50000
+    for (let i = 0; i < AA_NCHARS; i++) {
+        if (!aa_alowed(i)) continue
+        aa_glyphValues(i & 0xff, i >>> 8, tmp)
+        const v1 = tmp[0], v2 = tmp[1], v3 = tmp[2], v4 = tmp[3]
+        if (v1 > ma1) ma1 = v1
+        if (v2 > ma2) ma2 = v2
+        if (v3 > ma3) ma3 = v3
+        if (v4 > ma4) ma4 = v4
+        const s = v1 + v2 + v3 + v4
+        if (s > msum) msum = s
+        if (v1 < mi1) mi1 = v1
+        if (v2 < mi2) mi2 = v2
+        if (v3 < mi3) mi3 = v3
+        if (v4 < mi4) mi4 = v4
+        if (s < misum) misum = s
+    }
+    msum -= misum
+    mi1 = misum / 4; mi2 = misum / 4; mi3 = misum / 4; mi4 = misum / 4
+    ma1 = msum / 4;  ma2 = msum / 4;  ma3 = msum / 4;  ma4 = msum / 4
+    for (let i = 0; i < AA_NCHARS; i++) {
+        aa_glyphValues(i & 0xff, i >>> 8, tmp)
+        const v1r = tmp[0], v2r = tmp[1], v3r = tmp[2], v4r = tmp[3]
+        const sr = v1r + v2r + v3r + v4r
+        let sum = Math.floor((sr - misum) * (1020 / msum) + 0.5)
+        let v1 = Math.floor((v1r - mi1) * (255 / ma1) + 0.5)
+        let v2 = Math.floor((v2r - mi2) * (255 / ma2) + 0.5)
+        let v3 = Math.floor((v3r - mi3) * (255 / ma3) + 0.5)
+        let v4 = Math.floor((v4r - mi4) * (255 / ma4) + 0.5)
+        if (v1 > 255) v1 = 255; else if (v1 < 0) v1 = 0
+        if (v2 > 255) v2 = 255; else if (v2 < 0) v2 = 0
+        if (v3 > 255) v3 = 255; else if (v3 < 0) v3 = 0
+        if (v4 > 255) v4 = 255; else if (v4 < 0) v4 = 0
+        if (sum > 1020) sum = 1020; else if (sum < 0) sum = 0
+        aa_params[i * 5 + 0] = v1
+        aa_params[i * 5 + 1] = v2
+        aa_params[i * 5 + 2] = v3
+        aa_params[i * 5 + 3] = v4
+        aa_params[i * 5 + 4] = sum
+    }
+}
+
+function aa_pow2(x) { return x * x }
+function aa_pos(i1, i2, i3, i4) { return (i1 << 12) + (i2 << 8) + (i3 << 4) + i4 }
+function aa_dist(i1, i2, i3, i4, i5, y1, y2, y3, y4, y5) {
+    return 2 * (aa_pow2(i1 - y1) + aa_pow2(i2 - y2) + aa_pow2(i3 - y3) + aa_pow2(i4 - y4))
+           + aa_pow2(i5 - y5)
+}
+function aa_dist1(i1, i2, i3, i4, i5, y1, y2, y3, y4, y5) {
+    return aa_pow2(i1 - y1) + aa_pow2(i2 - y2) + aa_pow2(i3 - y3) + aa_pow2(i4 - y4)
+           + 2 * aa_pow2(i5 - y5)
+}
+
+function aa_mktable() {
+    if (!aa_params) aa_calcparams()
+    aa_table = new Uint16Array(65536)
+    aa_filltable = new Uint16Array(256)
+    const next = new Int32Array(65536)
+    for (let i = 0; i < 65536; i++) next[i] = i
+    let first = -1, last = -1
+    function add(i) {
+        if (next[i] === i && last !== i) {
+            if (last !== -1) { next[last] = i; last = i }
+            else { last = first = i }
+        }
+    }
+    for (let i = 0; i < AA_NCHARS; i++) {
+        if (!aa_alowed(i)) continue
+        const i1 = aa_params[i * 5 + 0]
+        const i2 = aa_params[i * 5 + 1]
+        const i3 = aa_params[i * 5 + 2]
+        const i4 = aa_params[i * 5 + 3]
+        const i5 = aa_params[i * 5 + 4]
+        const p1 = i1 >> 4, p2 = i2 >> 4, p3 = i3 >> 4, p4 = i4 >> 4
+        const p = aa_pos(p1, p2, p3, p4)
+        if (aa_table[p]) {
+            const ex = aa_table[p]
+            const ex1 = aa_params[ex * 5 + 0]
+            const ex2 = aa_params[ex * 5 + 1]
+            const ex3 = aa_params[ex * 5 + 2]
+            const ex4 = aa_params[ex * 5 + 3]
+            const ex5 = aa_params[ex * 5 + 4]
+            const pp1 = (p1 << 4) | p1
+            const pp2 = (p2 << 4) | p2
+            const pp3 = (p3 << 4) | p3
+            const pp4 = (p4 << 4) | p4
+            const ppsum = pp1 + pp2 + pp3 + pp4
+            const dNew = aa_dist(i1, i2, i3, i4, i5,  pp1, pp2, pp3, pp4, ppsum)
+            const dOld = aa_dist(ex1, ex2, ex3, ex4, ex5,  pp1, pp2, pp3, pp4, ppsum)
+            if (dNew > dOld) continue
+            if (dNew === dOld && AA_PRIORITY[(i >>> 8)] <= AA_PRIORITY[(ex >>> 8)]) continue
+        }
+        aa_table[p] = i
+        add(p)
+    }
+    for (let q = 0; q < 256; q++) {
+        let mindist = Infinity
+        let best = 0
+        for (let i = 0; i < AA_NCHARS; i++) {
+            if (!aa_alowed(i)) continue
+            const d1 = aa_dist1(aa_params[i * 5 + 0], aa_params[i * 5 + 1],
+                                aa_params[i * 5 + 2], aa_params[i * 5 + 3],
+                                aa_params[i * 5 + 4],
+                                q, q, q, q, q * 4)
+            if (d1 < mindist ||
+                (d1 === mindist && AA_PRIORITY[(i >>> 8)] > AA_PRIORITY[(best >>> 8)])) {
+                aa_filltable[q] = i
+                mindist = d1
+                best = i
+            }
+        }
+    }
+    // BFS propagation: claim neighbour slots that we cover better than whoever
+    // got there first.  Lifted verbatim from aamktabl.c via aa.mjs.
+    while (true) {
+        if (last !== -1) next[last] = last
+        else break
+        const blocked = last
+        let i = first
+        if (i === -1) break
+        first = -1; last = -1
+        let prev
+        do {
+            const m0 = (i >> 12) & 15
+            const m1 = (i >> 8) & 15
+            const m2 = (i >> 4) & 15
+            const m3 = i & 15
+            const c = aa_table[i]
+            const cp0 = aa_params[c * 5 + 0]
+            const cp1 = aa_params[c * 5 + 1]
+            const cp2 = aa_params[c * 5 + 2]
+            const cp3 = aa_params[c * 5 + 3]
+            const cp4 = aa_params[c * 5 + 4]
+            for (let dm = 0; dm < 4; dm++) {
+                for (let sgn = -1; sgn <= 1; sgn += 2) {
+                    let n0 = m0, n1 = m1, n2 = m2, n3 = m3
+                    if (dm === 0)      { n0 += sgn; if (n0 < 0 || n0 >= 16) continue }
+                    else if (dm === 1) { n1 += sgn; if (n1 < 0 || n1 >= 16) continue }
+                    else if (dm === 2) { n2 += sgn; if (n2 < 0 || n2 >= 16) continue }
+                    else               { n3 += sgn; if (n3 < 0 || n3 >= 16) continue }
+                    const index = aa_pos(n0, n1, n2, n3)
+                    const ch = aa_table[index]
+                    if (ch === c || index === blocked) continue
+                    let replace = !ch
+                    if (!replace) {
+                        const ii1 = (n0 << 4) | n0
+                        const ii2 = (n1 << 4) | n1
+                        const ii3 = (n2 << 4) | n2
+                        const ii4 = (n3 << 4) | n3
+                        const iisum = ii1 + ii2 + ii3 + ii4
+                        const dNew = aa_dist(ii1, ii2, ii3, ii4, iisum,
+                                             cp0, cp1, cp2, cp3, cp4)
+                        const dOld = aa_dist(ii1, ii2, ii3, ii4, iisum,
+                                             aa_params[ch * 5 + 0],
+                                             aa_params[ch * 5 + 1],
+                                             aa_params[ch * 5 + 2],
+                                             aa_params[ch * 5 + 3],
+                                             aa_params[ch * 5 + 4])
+                        if (dNew < dOld) replace = true
+                    }
+                    if (replace) { aa_table[index] = c; add(index) }
+                }
+            }
+            prev = i
+            i = next[i]
+            next[prev] = prev
+        } while (i !== prev)
+    }
+}
+
+// Render an imgW × imgH brightness buffer (imgW = scrW*2, imgH = scrH*2) into
+// per-cell (glyph, attr) outputs.  No dither, no params.
+function aa_render(img, scrW, scrH, tbOut, attrOut) {
+    if (!aa_table) aa_mktable()
+    const tbl = aa_table
+    const fill = aa_filltable
+    const wi = scrW * 2
+    for (let y = 0; y < scrH; y++) {
+        let pos  = 2 * y * wi
+        let pos1 = y * scrW
+        for (let x = 0; x < scrW; x++) {
+            const i1 = img[pos + 1]       // NE
+            const i2 = img[pos]           // NW
+            const i3 = img[pos + wi + 1]  // SE
+            const i4 = img[pos + wi]      // SW
+            const s = i1 + i2 + i3 + i4
+            const avg = s >> 2
+            let val
+            if (Math.abs(i1 - avg) < AA_VAL &&
+                Math.abs(i2 - avg) < AA_VAL &&
+                Math.abs(i3 - avg) < AA_VAL &&
+                Math.abs(i4 - avg) < AA_VAL) {
+                val = fill[avg]
+            } else {
+                val = tbl[((i2 >> 4) << 12) | ((i1 >> 4) << 8) |
+                          ((i4 >> 4) << 4)  |  (i3 >> 4)]
+            }
+            attrOut[pos1] = val >> 8
+            tbOut[pos1]   = val & 0xff
+            pos  += 2
+            pos1 += 1
+        }
+    }
+}
+
+// ── Wavescope (rows 3..5) ──────────────────────────────────────────────────
+//
+// Peak-detected envelope plotted into a 156×6 pixel buffer (2× cell res),
+// then converted to ASCII glyphs by the mini-AAlib above.  Mid-signal only —
+// stereo info lives on the bottom bar.
+//
+// Three monochrome intensities pick out the wave's body / peaks: DIM cells
+// are the dim trace, NORMAL cells are the bulk of the waveform, BOLD cells
+// land on the brightest patches (full-blocked peaks).  Amber → white ramp
+// mimics phosphor bloom.
+
+const AA_WAVE_W = AG_LANE_W                  // 78 cells
+const AA_WAVE_H = AG_ROW_WAVE_BOT - AG_ROW_WAVE_TOP + 1   // 3 cells
+const AA_WAVE_IW = AA_WAVE_W * 2             // 156 px
+const AA_WAVE_IH = AA_WAVE_H * 2             //   6 px
+
+const ag_waveImg  = new Uint8Array(AA_WAVE_IW * AA_WAVE_IH)
+const ag_waveTb   = new Uint8Array(AA_WAVE_W * AA_WAVE_H)
+const ag_waveAttr = new Uint8Array(AA_WAVE_W * AA_WAVE_H)
+
+// AA_NORMAL=0, AA_DIM=1, AA_BOLD=2  → amber phosphor palette.
+const AG_WAVE_FG = [166, 130, AG_COL_LABEL]
+
+function ag_drawWavescope() {
+    const N  = AG_SNAPSHOT_N
+    const IW = AA_WAVE_IW
+    const IH = AA_WAVE_IH
+    const img = ag_waveImg
+    img.fill(0)
+
+    // Per-pixel-column envelope: vertical line from max to min sample value.
+    const samplesPerCol = N / IW
+    const yScale = (IH - 1) * 0.5
+    for (let c = 0; c < IW; c++) {
+        const s = (c * samplesPerCol) | 0
+        const e = (((c + 1) * samplesPerCol) | 0)
+        let mn = 1.0, mx = -1.0
+        for (let i = s; i < e; i++) {
+            const v = (ag_snapL[i] + ag_snapR[i]) * 0.5
+            if (v < mn) mn = v
+            if (v > mx) mx = v
+        }
+        // [-1, 1] → [0, IH-1]; +1 sits at the top, -1 at the bottom.
+        let yT = ((1 - mx) * yScale + 0.5) | 0
+        let yB = ((1 - mn) * yScale + 0.5) | 0
+        if (yT < 0) yT = 0; else if (yT > IH - 1) yT = IH - 1
+        if (yB < 0) yB = 0; else if (yB > IH - 1) yB = IH - 1
+        for (let y = yT; y <= yB; y++) img[y * IW + c] = 0xFF
+    }
+
+    aa_render(img, AA_WAVE_W, AA_WAVE_H, ag_waveTb, ag_waveAttr)
+
+    // Blit, skipping cells whose packed (attr<<8 | glyph) key is unchanged.
+    for (let r = 0; r < AA_WAVE_H; r++) {
+        for (let c = 0; c < AA_WAVE_W; c++) {
+            const idx = r * AA_WAVE_W + c
+            const att = ag_waveAttr[idx]
+            const ch  = ag_waveTb[idx]
+            const key = (att << 8) | ch
+            if (ag_waveGlyph[idx] === key) continue
+            ag_waveGlyph[idx] = key
+            ag_color(AG_WAVE_FG[att] || AG_COL_LABEL, AG_COL_BG)
+            ag_mvprn(AG_ROW_WAVE_TOP + r, AG_COL_INSIDE_L + c, ch)
+        }
+    }
+}
+
+// ── XY-scope persistence visualiser (rows 7..30) ───────────────────────────
+//
+// 45°-rotated vectorscope, standard convention.  Each PCM sample plots at
+//     col = centre_col + (L − R) · SX
+//     row = centre_row + (L + R) · SY
+// giving the four canonical traces:
+//     in-phase mono (L = R)    → vertical line   ((L−R)=0, (L+R) varies)
+//     out-of-phase mono (L=−R) → horizontal line ((L+R)=0, (L−R) varies)
+//     pure L  (R = 0)          → lower-right diagonal — the `\` axis
+//     pure R  (L = 0)          → lower-left  diagonal — the `/` axis
+// (Positive mono sits below centre because screen row increases downward.)
+// The glyph per cell follows channel dominance, the cell's intensity is
+// bumped on every hit, and a global decay shrinks stale traces back to zero.
+//
+// Wavelet energies are used as *modulators* — the design's central idea:
+//
+//   transient  → faster decay + scattered spark emission
+//   bass/tonal → slower decay (sustained content breathes longer)
+//   noise      → small jitter on plot position (texture fuzz)
+//
+// TSVM terminal cells are ~2:1 (taller than wide); SX is set to ~2×SY so the
+// scope reads roughly circular under steady mono content.
+
+const AG_XY_CX = AG_VIS_W >> 1     // centre column inside visualiser canvas
+const AG_XY_CY = AG_VIS_H >> 1     // centre row
+const AG_XY_SX = 18                // (L−R) → horizontal extent ±36 cells
+const AG_XY_SY = 9                 // (L+R) → vertical   extent ±18 cells
+
+// Bass mark: 2×2 cell indicator pinned to the centre of the vectorscope so
+// the bass "subwoofer" sits underneath the beam's pivot point.  Half-blocks
+// form a compact 16×16-pixel "dot" centred in the 16×32-pixel 2×2 area.
+const AG_BASS_VIS_R0 = AG_XY_CY - 1
+const AG_BASS_VIS_C0 = AG_XY_CX - 1
+const AG_BASS_VIS_R1 = AG_BASS_VIS_R0 + 1
+const AG_BASS_VIS_C1 = AG_BASS_VIS_C0 + 1
+const AG_BASS_SCR_R  = AG_ROW_VIS_TOP + AG_BASS_VIS_R0
+const AG_BASS_SCR_C  = AG_COL_INSIDE_L + AG_BASS_VIS_C0
+
+// Glyphs.
+const AG_G_DOT  = 0xFA  // ·
+const AG_G_BSL  = 0x5C  // \\
+const AG_G_FSL  = 0x2F  // /
+const AG_G_XCR  = 0x58  // X
+const AG_G_SPK  = 0x2A  // *
+const AG_G_HBAR = 0xC4  // ─
+
+function ag_updateXYScope() {
+    // Wavelet-driven modulators, all in [0, 1].
+    const transient = ag_bandEnergy[AG_WL_TRANSIENT]
+    const noise     = ag_bandEnergy[AG_WL_NOISE]
+    const sustain   = ag_bandEnergy[AG_WL_BASS] * 0.6 + ag_bandEnergy[AG_WL_TONAL] * 0.4
+
+    // Decay: base 0.93, longer for sustained content, much shorter for sharp
+    // transients.  Clamped so a screaming hi-hat never freezes the trails and
+    // a deep pad never overflows.
+    let decay = 0.93 + 0.05 * (sustain > 1 ? 1 : sustain)
+                     - 0.10 * (transient > 1 ? 1 : transient)
+    if (decay < 0.72) decay = 0.72
+    if (decay > 0.985) decay = 0.985
+
+    // Decay all cells.
+    for (let i = 0; i < ag_persist.length; i++) {
+        ag_persist[i] *= decay
+    }
+
+    // Plot every sample in the snapshot.  Step 1 keeps lines continuous
+    // visually; with 1024 samples per ~50 ms frame, most cells get multiple
+    // hits and the persistence builds the "beam" silhouette.
+    const SX = AG_XY_SX
+    const SY = AG_XY_SY
+    const cx = AG_XY_CX
+    const cy = AG_XY_CY
+    const jitterAmt = noise * 0.06        // noise-driven beam fuzz
+    const plotBoost = 0.05
+
+    for (let i = 0; i < AG_SNAPSHOT_N; i++) {
+        const L = ag_snapL[i]
+        const R = ag_snapR[i]
+        const mono = L + R                 // vertical axis  ∈ [-2, 2]
+        const side = L - R                 // horizontal axis ∈ [-2, 2]
+        // Wavelet-driven jitter is symmetric — substitute a deterministic
+        // pseudo-random by mixing the snapshot index so we don't churn the
+        // shared Math.random() PRNG 1024× per frame.
+        const jx = (((i * 1103515245 + 12345) & 0xFFFF) / 65536 - 0.5) * jitterAmt
+        const jy = (((i * 1664525     + 1013904223) & 0xFFFF) / 65536 - 0.5) * jitterAmt
+        let col = cx + ((side + jx) * SX) | 0
+        let row = cy + ((mono + jy) * SY) | 0
+        if (col < 0 || col >= AG_VIS_W || row < 0 || row >= AG_VIS_H) continue
+
+        const absL = L < 0 ? -L : L
+        const absR = R < 0 ? -R : R
+        let glyph
+        if (absL + absR < 0.04) {
+            glyph = AG_G_DOT
+        } else if (absL > absR * 1.25) {
+            glyph = AG_G_BSL                 // L-dominant → \
+        } else if (absR > absL * 1.25) {
+            glyph = AG_G_FSL                 // R-dominant → /
+        } else {
+            glyph = AG_G_XCR                 // mixed     → X
+        }
+
+        const idx = row * AG_VIS_W + col
+        let nv = ag_persist[idx] + plotBoost
+        if (nv > 1.0) nv = 1.0
+        ag_persist[idx] = nv
+        ag_persistGlyph[idx] = glyph
+    }
+
+    // Transient spark emission — when high-freq energy peaks, scatter a few
+    // bright `*` glyphs across the canvas.  Cap at ~32 sparks to stay cheap.
+    if (transient > 0.32) {
+        const nSparks = ((transient - 0.32) * 60) | 0
+        for (let s = 0; s < nSparks && s < 32; s++) {
+            const c = (Math.random() * AG_VIS_W) | 0
+            const r = (Math.random() * AG_VIS_H) | 0
+            const idx = r * AG_VIS_W + c
+            if (ag_persist[idx] < 0.85) ag_persist[idx] = 0.85
+            ag_persistGlyph[idx] = AG_G_SPK
+        }
+    }
+}
+
+function ag_drawVisualiser() {
+    for (let r = 0; r < AG_VIS_H; r++) {
+        const rowOff = r * AG_VIS_W
+        const screenY = AG_ROW_VIS_TOP + r
+        const inBassRow = (r === AG_BASS_VIS_R0 || r === AG_BASS_VIS_R1)
+        for (let c = 0; c < AG_VIS_W; c++) {
+            // Bass mark owns its 2×2 cells — let ag_drawBassMark() paint them.
+            if (inBassRow && (c === AG_BASS_VIS_C0 || c === AG_BASS_VIS_C1)) continue
+            const idx = rowOff + c
+            const e = ag_persist[idx]
+            let levelIdx = (e * 5) | 0
+            if (levelIdx > 4) levelIdx = 4
+            if (levelIdx < 0) levelIdx = 0
+            const glyph = (levelIdx === 0) ? 0x20 : ag_persistGlyph[idx]
+            const fg    = AG_BEAM_PAL[levelIdx]
+            if (ag_cellGlyph[idx] === glyph && ag_cellFg[idx] === fg) continue
+            ag_cellGlyph[idx] = glyph
+            ag_cellFg[idx]    = fg
+            ag_color(fg, AG_COL_BG)
+            ag_mvprn(screenY, AG_COL_INSIDE_L + c, glyph)
+        }
+    }
+}
+
+// ── Bass mark (rows 29-30, cols 2-3) ───────────────────────────────────────
+// Brightness-only indicator driven by the sub-500 Hz residual of the Haar
+// pyramid.  Uses indices 1..4 of the beam palette so the dot never falls all
+// the way to background — a quiet track still shows a faint amber ember.
+
+function ag_drawBassMark() {
+    let idx = (ag_bassEnergy * 4) | 0
+    if (idx > 3) idx = 3
+    if (idx < 0) idx = 0
+    const fg = AG_BEAM_PAL[idx + 1]
+    if (fg === ag_lastBassFg) return
+    ag_lastBassFg = fg
+    ag_color(fg, AG_COL_BG)
+    ag_mvprn(AG_BASS_SCR_R,     AG_BASS_SCR_C,     0xDC)
+    ag_mvprn(AG_BASS_SCR_R,     AG_BASS_SCR_C + 1, 0xDC)
+    ag_mvprn(AG_BASS_SCR_R + 1, AG_BASS_SCR_C,     0xDF)
+    ag_mvprn(AG_BASS_SCR_R + 1, AG_BASS_SCR_C + 1, 0xDF)
+}
+
+// ── Stereo energy bar (row 31) ─────────────────────────────────────────────
+//
+// Same idea as playtaud.drawStereo() but driven by raw PCM: for each sample,
+// pan = side/|mid| → bin index, energy = sqrt(|mid|+|side|).  Gaussian-ish
+// 7-cell spread so individual sample clusters read as bars, not single spikes.
+
+function ag_drawStereo() {
+    const W = AG_LANE_W
+    const bins = new Float32Array(W)
+    const N    = AG_SNAPSHOT_N
+
+    for (let i = 0; i < N; i++) {
+        const L = ag_snapL[i]
+        const R = ag_snapR[i]
+        const mid  = (L + R) * 0.5
+        const side = (L - R) * 0.5
+        const absM = mid < 0 ? -mid : mid
+        const absS = side < 0 ? -side : side
+        // Pan estimate, clamped — `side/|mid|` blows up near silence so we
+        // floor the denominator.  This is a coarse stereo image, not a
+        // calibrated readout.
+        let pan = side / (absM + 0.02)
+        if (pan < -1) pan = -1; else if (pan > 1) pan = 1
+        const energy = Math.pow(absM + absS, 0.5)
+        if (energy <= 0) continue
+
+        let col = ((pan + 1) * 0.5 * (W - 1)) | 0
+        if (col < 0) col = 0; else if (col >= W) col = W - 1
+        bins[col] += energy
+        if (col >= 3)     bins[col - 3] += energy * 0.05
+        if (col >= 2)     bins[col - 2] += energy * 0.3
+        if (col >= 1)     bins[col - 1] += energy * 0.75
+        if (col < W - 1)  bins[col + 1] += energy * 0.75
+        if (col < W - 2)  bins[col + 2] += energy * 0.3
+        if (col < W - 3)  bins[col + 3] += energy * 0.05
+    }
+    // Calibrated for "typical" 32 kHz × 1024-sample snapshot at modest level.
+    const norm = 8.0 / N
+    for (let i = 0; i < W; i++) {
+        const v = bins[i] * norm
+        let idx = (v * 1.6) | 0
+        if (idx > 4) idx = 4
+        if (idx < 0) idx = 0
+        const glyph = AG_STAIRS[idx]
+        const fg    = AG_STEREO_COL[idx]
+        if (ag_stereoGlyph[i] === glyph && ag_stereoFg[i] === fg) continue
+        ag_stereoGlyph[i] = glyph
+        ag_stereoFg[i]    = fg
+        ag_color(fg, AG_COL_BG)
+        ag_mvprn(AG_ROW_STEREO, AG_COL_INSIDE_L + i, glyph)
+    }
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────
+//
+// audioInit({ title, tag }): paint the static frame.
+//   title : song title shown on row 2 (left)
+//   tag   : 3-5 char format label embedded in the top border (e.g. "WAV", "MP2")
+//
+// audioFeedPcm(ptr, sampleCount): hand the visualiser a fresh slice of
+//   PCMu8-stereo-interleaved samples (typically the freshly decoded chunk).
+//
+// audioSetProgress(progress, elapsedSec, totalSec): update the title-row
+//   progress bar.  Cheap — only redraws on change.
+//
+// audioRender(): repaint wavescope + visualiser + stereo bar from the latest
+//   snapshot.  Internally rate-limited to ~20 Hz so callers can invoke
+//   liberally without juggling frame timing.
+//
+// audioClose(): restore cursor + move out of the panel for a clean exit.
+
+function audioInit(params) {
+    ag_initParams = params || {}
+    ag_lastRenderNs = 0
+    ag_lastProgressIdx = -1
+    ag_lastTimeStr = ''
+    for (let i = 0; i < ag_snapL.length; i++) { ag_snapL[i] = 0; ag_snapR[i] = 0 }
+    for (let i = 0; i < ag_persist.length; i++) ag_persist[i] = 0
+    ag_persistGlyph.fill(0x20)
+    ag_cellGlyph.fill(-1); ag_cellFg.fill(-1)
+    ag_waveGlyph.fill(-1)
+    ag_stereoGlyph.fill(-1); ag_stereoFg.fill(-1)
+    ag_bassEnergy = 0
+    ag_lastBassFg = -1
+
+    con.curs_set(0)
+    con.clear()
+    ag_drawFrame()
+    ag_drawTitle()
+}
+
+function audioSetProgress(progress, elapsedSec, totalSec) {
+    if (progress < 0) progress = 0; else if (progress > 1) progress = 1
+    ag_drawProgress(progress, elapsedSec | 0, totalSec | 0)
+}
+
+function audioRender() {
+    const now = sys.nanoTime()
+    if (now - ag_lastRenderNs < AG_RENDER_INTERVAL_NS) return
+    ag_lastRenderNs = now
+
+    ag_analyseHaar()
+    ag_updateXYScope()
+    ag_drawWavescope()
+    ag_drawVisualiser()
+    ag_drawBassMark()
+    ag_drawStereo()
+}
+
+function audioClose() {
+    con.move(AG_ROW_BOT_BORDER + 1, 1)
+    con.curs_set(1)
+}
+
+// ── Exit polling ───────────────────────────────────────────────────────────
+// Mirror the Backspace-to-quit convention already in playtaud.
+
+function audioIsExitRequested() {
+    sys.poke(-40, 1)
+    return sys.peek(-41) === 67
+}
+
 exports = {
     clearSubtitleArea,
     displaySubtitle,
     printTopBar,
-    printBottomBar
+    printBottomBar,
+    audioInit,
+    audioFeedPcm,
+    audioSetProgress,
+    audioRender,
+    audioClose,
+    audioIsExitRequested
 }

assets/disk0/tvdos/include/taud.mjs

@@ -83,11 +83,13 @@ function uploadTaudFile(inFile, songIndex, playhead) {
     pos = 8
 
     // -- 3. Parse header ------------------------------------------------------
-    // version(1) + numSongs(1) + compressedSize(4) + rsvd(2) + signature(16) = 24 bytes
+    // magic(8) + version(1) + numSongs(1) + compSize(4) + projOff(4) + signature(14)
+    // = 32 bytes (terranmon.txt §Header).
     let version        = sys.peek(filePtr + pos) & 0xFF;  pos++
     let numSongs       = sys.peek(filePtr + pos) & 0xFF;  pos++
     let compressedSize = _peekU32LE(filePtr, pos);         pos += 4
-    pos += 18  // skip reserved(2) + signature(16)
+    let projOff        = _peekU32LE(filePtr, pos);         pos += 4
+    pos += 14  // signature
     // pos == 32 == TAUD_HEADER_SIZE
 
     if (songIndex < 0 || songIndex >= numSongs) {
@@ -155,6 +157,50 @@ function uploadTaudFile(inFile, songIndex, playhead) {
     audio.setSongGlobalVolume(playhead, songGlobalVolume)
     audio.setSongMixingVolume(playhead, songMixingVolume)
 
+    // -- 9. Project Data — walk Ixmp blocks for multi-sample instruments -----
+    // Terranmon spec: Project Data starts at `projOff` (zero = absent), magic is
+    // \x1ETaudPrJ + 8 reserved bytes, then a stream of FourCC + Uint32-length
+    // sections. We only consume "Ixmp" here; other sections (PNam, INam, sMet,
+    // etc.) are skipped so the player apps remain free to parse them.
+    if (projOff !== 0 && projOff + 16 <= fileSize) {
+        const projMagic = [0x1E,0x54,0x61,0x75,0x64,0x50,0x72,0x4A]  // \x1ETaudPrJ
+        let prjOk = true
+        for (let i = 0; i < 8; i++) {
+            if ((sys.peek(filePtr + projOff + i) & 0xFF) !== projMagic[i]) { prjOk = false; break }
+        }
+        if (prjOk) {
+            const PATCH_SIZE = 31
+            let p = projOff + 16  // skip magic(8) + reserved(8)
+            while (p + 8 <= fileSize) {
+                const fc = String.fromCharCode(
+                    sys.peek(filePtr + p)     & 0xFF, sys.peek(filePtr + p + 1) & 0xFF,
+                    sys.peek(filePtr + p + 2) & 0xFF, sys.peek(filePtr + p + 3) & 0xFF)
+                const secLen = _peekU32LE(filePtr, p + 4)
+                const payload = p + 8
+                if (payload + secLen > fileSize) break
+                if (fc === 'Ixmp') {
+                    // Each entry: Uint8 instId + Uint24 patchCount + (patchCount × PATCH_SIZE) bytes.
+                    let q = payload
+                    const qEnd = payload + secLen
+                    while (q + 4 <= qEnd) {
+                        const instId   = sys.peek(filePtr + q) & 0xFF; q++
+                        const cntLo    = sys.peek(filePtr + q) & 0xFF; q++
+                        const cntMid   = sys.peek(filePtr + q) & 0xFF; q++
+                        const cntHi    = sys.peek(filePtr + q) & 0xFF; q++
+                        const patchCnt = cntLo | (cntMid << 8) | (cntHi << 16)
+                        const blobLen  = patchCnt * PATCH_SIZE
+                        if (q + blobLen > qEnd) break
+                        let buf = new Array(blobLen)
+                        for (let k = 0; k < blobLen; k++) buf[k] = sys.peek(filePtr + q + k) & 0xFF
+                        audio.uploadInstrumentPatches(instId, buf)
+                        q += blobLen
+                    }
+                }
+                p = payload + secLen
+            }
+        }
+    }
+
 
     fileHandle.close()
     sys.free(filePtr)

assets/disk0/tvdos/include/wintex.mjs

@@ -65,12 +65,12 @@ class WindowObject {
             }
             if (this.titleRight !== undefined) {
                 let tt = ''+this.titleRight
-                con.move(this.y, this.x + this.width - tt.length - 2)
+                con.move(this.y + this.height - 1, this.x + this.width - tt.length - 2)
                 print(`\x84${charset[4]}u`)
                 if (this.titleBackRight !== undefined) print(`\x1B[48;5;${this.titleBackRight}m`)
                 print(`\x1B[38;5;${colourText}m${tt}`)
                 if (this.titleBackRight !== undefined) print(`\x1B[48;5;${oldBack}m`)
-                print(`\x1B[38;5;${colour}m\x84${charset[1]}u`)
+                print(`\x1B[38;5;${colour}m\x84${charset[3]}u`)
             }
 
 
@@ -180,4 +180,769 @@ function scrollHorz(dx, stringSize, stringViewSize, currentCursorPos, currentScr
     return [currentCursorPos, currentScrollPos]
 }
 
-exports = { WindowObject, scrollVert, scrollHorz }
+// ---------------------------------------------------------------------------
+// Modal dialog with optional body text, input fields, a scrollable selection
+// list, and OK/Cancel-style buttons. Layout from top to bottom:
+//   title bar, message, fields, list, buttons.
+//
+// opts = {
+//   title:   string,
+//   message: string | string[]?,             -- optional body text drawn above fields/list
+//   drawFrame: function(wo)?,                -- override for the window-frame painter;
+//                                               same contract as WindowObject's
+//                                               `drawFrame` slot. Useful when the caller
+//                                               wants its own border / title styling.
+//
+//   fields:  [{label, initial?, width, maxLength?}, ...] -- omit / [] for no input
+//                                               field. Label does NOT get auto-colon.
+//                                               `maxLength` caps insertable chars
+//                                               (default: width * 4).
+//
+//   list: {                                  -- optional vertical selection list
+//     items:     [{label, ...}, ...],        -- arbitrary user objects; only `label`
+//                                               is read by the default renderer.
+//     height:    number,                     -- visible row count.
+//     width:     number?,                    -- inner width override (default: popup w-4).
+//     cursor:    number?,                    -- initial cursor row (default: first selectable).
+//     selectable: function(item, i)->bool?,  -- default: every item selectable. Non-
+//                                               selectable rows are skipped by arrow keys.
+//                                               When NO row is selectable, arrow / PgUp
+//                                               / PgDn scroll the view instead.
+//     renderItem: function(ctx)?,            -- per-row painter; ctx exposes
+//                                               { y, x, w, item, idx, isCursor, focused,
+//                                                 listBg, selBg, fg, hlFg, dimFg }.
+//                                               Default prints `item.label`.
+//     onActivate: function(item, i, key)?,   -- fired on Enter ('\n') / Space (' ')
+//                                               / left-click ('click'); return an
+//                                               action string to close the dialog,
+//                                               or null to stay open.
+//     showScrollbar: bool?,                  -- default: auto (true when overflowing).
+//     scrollbarChars: number[6]?,            -- glyph codes for the scrollbar:
+//                                               [troughTopEmpty, troughMidEmpty,
+//                                                troughBotEmpty, troughTopFilled,
+//                                                troughMidFilled, troughBotFilled].
+//                                               Default [0xBA,0xBA,0xBA,0xDB,0xDB,0xDB]
+//                                               (CP437-safe). Callers with a custom
+//                                               charset (e.g. taut) pass their own.
+//     drawWell: bool?,                       -- draw the list background
+//     bg: number?,                           -- list background colour (default 242).
+//   },
+//
+//   buttons: [{label, action, default?}, ...] -- defaults to [OK, Cancel] (+ Delete
+//            if `allowDelete:true`)
+//   allowDelete: bool,                       -- inserts a Delete button (fsh compat)
+//   colours: {fg?, bg?, fieldBg?, dimFg?, hlFg?, focusBg?, listBg?, listSelBg?}
+//                                            -- per-call overrides
+//   disableKeyRepeat: bool,               -- when true, key won't repeat when held down
+//   onKey: function(ks, shiftDown, ctx)?,    -- escape hatch for callers that need
+//                                               extra key bindings. Runs BEFORE the
+//                                               built-in handlers. Return true to
+//                                               consume the key. `ctx` exposes
+//                                               { render, close(result),
+//                                                 getListCursor, setListCursor }.
+// }
+//
+// Returns {action, values, listCursor, listItem}: `action` is the chosen button's
+// `action` or the value returned from `onActivate` (default "ok"/"cancel"/"delete"),
+// or "cancel" on Esc; `values` is the array of field strings in field order;
+// `listCursor` is the final cursor index (-1 if there is no list); `listItem` is
+// the item at that index.
+//
+// Behaviour:
+//   - Tab / Shift+Tab and arrow Down / Up cycle focus across fields, list, and buttons.
+//     Inside the list, arrow Up / Down move the cursor between selectable rows;
+//     PgUp/PgDn move a page; Home/End jump to the first/last selectable row.
+//   - Left / Right inside a field move the caret; on the list or a button they cycle focus.
+//   - Home / End jump to start / end of the focused field.
+//   - Enter on a field jumps to the next field, then to the first button. Enter
+//     or Space on a button activates it. Enter or Space on a list row invokes
+//     `onActivate(item, idx, key)`; if that returns a string, the dialog closes
+//     with that action.
+//   - Insert at caret. Backspace deletes left of caret; Forward-Del deletes right.
+//   - Blinking caret (`con.curs_set(1)`) is positioned on the focused field and
+//     hidden when the list or a button has focus.
+//   - Mouse: left-click on a button activates it; click on a field puts focus
+//     on that field and positions the caret under the click; click on a list row
+//     moves the cursor (and fires `onActivate` if defined); mouse-wheel inside the
+//     list scrolls it. Mouse hover on a button moves focus to it (the same focus
+//     the keyboard uses).
+const _dialogScreen = con.getmaxyx()
+const _dialogPixDim = graphics.getPixelDimension()
+const _CELL_PW = (_dialogPixDim[0] / _dialogScreen[1]) | 0
+const _CELL_PH = (_dialogPixDim[1] / _dialogScreen[0]) | 0
+function _pxToCell(px, py) { return [(py / _CELL_PH | 0) + 1, (px / _CELL_PW | 0) + 1] }
+
+function showDialog(opts) {
+    const fields  = opts.fields || []
+    const values  = fields.map(f => (f.initial == null) ? '' : ('' + f.initial))
+    const cursors = values.map(v => v.length)
+
+    let oldFG = con.get_color_fore()
+    let oldBG = con.get_color_back()
+
+    let buttons
+    if (opts.buttons) {
+        buttons = opts.buttons
+    } else {
+        buttons = [{label: 'OK', action: 'ok', default: true}]
+        if (opts.allowDelete) buttons.push({label: 'Delete', action: 'delete'})
+        buttons.push({label: 'Cancel', action: 'cancel'})
+    }
+
+    const title = opts.title || ''
+    const message = opts.message
+    const messageLines = !message ? []
+        : Array.isArray(message) ? message
+        : ('' + message).split('\n')
+
+    const list = opts.list || null
+    const drawWell = list?.drawWell ?? true
+    const c         = opts.colours || {}
+    const fg        = (c.fg        != null) ? c.fg        : 254
+    const bg        = (c.bg        != null) ? c.bg        : 244
+    const fieldBg   = (c.fieldBg   != null) ? c.fieldBg   : 240
+    const dimFg     = (c.dimFg     != null) ? c.dimFg     : 249
+    const hlFg      = (c.hlFg      != null) ? c.hlFg      : 240
+    const focusBg   = (c.focusBg   != null) ? c.focusBg   : 253
+    const listBg    = (c.listBg    != null) ? c.listBg    : (drawWell) ? 243 : bg
+    const listSelBg = (c.listSelBg != null) ? c.listSelBg : focusBg
+
+    // List state
+    const listItems = list ? (list.items || []) : []
+    const listSelectable = list && list.selectable ? list.selectable : (() => true)
+    const listHeight     = list ? (list.height || Math.min(8, listItems.length)) : 0
+    const hasList        = !!list
+    const listOnActivate = list ? list.onActivate : null
+    const listBgColour   = (list && list.bg != null) ? list.bg : listBg
+    // Scrollbar glyphs: [trough top/mid/bottom empty, then top/mid/bottom filled].
+    // Default is CP437-safe (0xBA track, 0xDB thumb); callers with their own
+    // charset (e.g. taut's 0xBA..0xBF) pass a 6-item override.
+    const listScrollbarChars = (list && Array.isArray(list.scrollbarChars) && list.scrollbarChars.length >= 6)
+        ? list.scrollbarChars
+        : [0xBA, 0xBA, 0xBA, 0xDB, 0xDB, 0xDB]
+    function firstSelectable(from, dir) {
+        if (!hasList || listItems.length === 0) return -1
+        let i = from
+        for (let n = 0; n < listItems.length; n++) {
+            if (i >= 0 && i < listItems.length && listSelectable(listItems[i], i)) return i
+            i += dir
+            if (i < 0) i = listItems.length - 1
+            if (i >= listItems.length) i = 0
+        }
+        return -1
+    }
+    let listCursor = hasList
+        ? (list.cursor != null ? list.cursor : firstSelectable(0, +1))
+        : -1
+    let listScroll = 0
+
+    // Layout
+    const buttonGap = 3
+    const maxFieldW = fields.reduce((m, f) => Math.max(m, f.width), 16)
+    const longestMsg = messageLines.reduce((m, l) => Math.max(m, l.length), 0)
+    // When the caller pins `list.width`, trust it — string `.length` overcounts
+    // visual width whenever items embed ANSI escapes or TVDOS \x84NNu sequences
+    // (e.g. taut's help popup, whose rows are pre-typeset with fg-colour escapes).
+    const longestItem = hasList && list.width == null
+        ? listItems.reduce((m, it) => Math.max(m, (it.label || '').length), 0)
+        : 0
+    const titleW    = title.length + 4
+    const btnRowW   = buttons.reduce((s, b) => s + b.label.length + 4, 0) + buttonGap * Math.max(0, buttons.length - 1)
+    const listMinW  = hasList
+        ? (list.width != null ? list.width + 4 : longestItem + 6)
+        : 0
+    const w = 2+Math.max(maxFieldW + 6, titleW + 4, longestMsg + 6, btnRowW + 4, listMinW, 22)
+
+    const msgRows      = messageLines.length + (messageLines.length > 0 ? 1 : 0)
+    const fieldsBlockH = fields.length * 4
+    const listBlockH   = hasList ? listHeight + 2 : 0   // top border + rows + bottom border
+
+    let bodyRows = msgRows
+    if (fields.length > 0) bodyRows += fieldsBlockH + 1   // +1 spacing after fields
+    if (hasList)           bodyRows += listBlockH + 1     // +1 spacing after list
+    if (bodyRows === 0)    bodyRows = 1                   // at least one row above buttons
+    const buttonsRowOff = 1 + bodyRows
+    const h = buttonsRowOff + 2
+
+    const screen = con.getmaxyx()
+    const row = Math.max(2, Math.floor((screen[0] - h) / 2))
+    const col = Math.max(2, Math.floor((screen[1] - w) / 2))
+
+    // Focus layout: 0..fields.length-1 = fields, [+1 = list if present], then buttons.
+    const listFocusIdx = hasList ? fields.length : -1
+    const buttonsFocusBase = fields.length + (hasList ? 1 : 0)
+    const totalFocus = buttonsFocusBase + buttons.length
+
+    // Pick initial focus: explicit default > list > first field > first button.
+    let focusIdx = -1
+    for (let i = 0; i < buttons.length; i++) {
+        if (buttons[i].default) { focusIdx = buttonsFocusBase + i; break }
+    }
+    if (focusIdx < 0) {
+        if (fields.length > 0)  focusIdx = 0
+        else if (hasList)       focusIdx = listFocusIdx
+        else                    focusIdx = buttonsFocusBase
+    }
+    let done = null
+
+    function fieldScroll(cur, fw) { return cur < fw ? 0 : cur - fw + 1 }
+    function fieldLabelRow(i) { return row + 1 + msgRows + i * 4 }
+    function fieldBoxRow(i)   { return fieldLabelRow(i) + 1 }
+    function fieldContentRow(i) { return fieldLabelRow(i) + 2 }
+    function fieldBoxCol() { return col + 2 }
+    function fieldContentRegion(i) { return { x: fieldBoxCol() + 1, y: fieldContentRow(i), w: fields[i].width } }
+
+    function listBlockTopRow() {
+        return row + 1 + msgRows + (fields.length > 0 ? fieldsBlockH + 1 : 0)
+    }
+    function listBlockCol()  { return col + 2 }
+    function listBlockWidth() { return w - 4 }      // inner content width incl. borders
+    function listContentRow(i) { return listBlockTopRow() + 1 + (i - listScroll) }
+    function listContentCol()  { return listBlockCol() + 1 }
+    function listScrollbarNeeded() {
+        if (!hasList) return false
+        if (list.showScrollbar != null) return list.showScrollbar
+        return listItems.length > listHeight
+    }
+    function listContentInnerW() {
+        return listBlockWidth() - 2 - (listScrollbarNeeded() ? 1 : 0)
+    }
+
+    function buttonRegions() {
+        let bx = col + Math.floor((w - btnRowW) / 2)
+        return buttons.map(b => {
+            const r = { x: bx, y: row + buttonsRowOff, w: b.label.length + 4 }
+            bx += b.label.length + 4 + buttonGap
+            return r
+        })
+    }
+
+    function drawFrameBox() {
+        con.color_pair(fg, bg)
+        for (let r = row; r < row + h; r++) {
+            con.move(r, col)
+            print(' '.repeat(w))
+        }
+        const wo = new WindowObject(col, row, w, h, ()=>{}, ()=>{}, title, opts.drawFrame)
+        wo.isHighlighted = true
+        wo.titleBack = bg
+        wo.drawFrame()
+        con.color_pair(fg, bg)
+    }
+
+    function drawMessage() {
+        if (messageLines.length === 0) return
+        con.color_pair(fg, bg)
+        for (let i = 0; i < messageLines.length; i++) {
+            con.move(row + 1 + i, col + 2)
+            print(messageLines[i].padEnd(w - 4, ' '))
+        }
+    }
+
+    function drawField(i) {
+        const f = fields[i]
+        const fbCol = fieldBoxCol()
+        const fbRow = fieldBoxRow(i)
+        const fw = f.width
+        const focused = (focusIdx === i)
+        const frameFg = focused ? fg : dimFg
+
+        // Label
+        con.color_pair(fg, bg)
+        con.move(fieldLabelRow(i), fbCol)
+        print(f.label)
+
+        // Top border (3px padding w/ TSVM chr rom)
+        con.color_pair(fieldBg, bg)
+        con.move(fbRow, fbCol)
+        print('\u00EC' + '\u00A9'.repeat(fw) + '\u00ED')
+
+        // Left border (3px padding w/ TSVM chr rom)
+        con.move(fbRow + 1, fbCol)
+        print('\u00AB')
+
+        // the content
+        con.color_pair(fg, fieldBg)
+        const s = fieldScroll(cursors[i], fw)
+        const vis = values[i].substring(s, s + fw)
+        print(vis.padEnd(fw, ' '))
+
+        // Right border (3px padding w/ TSVM chr rom)
+        con.color_pair(fieldBg, bg)
+        con.move(fbRow + 1, fbCol + fw + 1)
+        print('\u00AA')
+
+        // Bottom border (3px padding w/ TSVM chr rom)
+        con.move(fbRow + 2, fbCol)
+        print('\u00F4' + '\u00AC'.repeat(fw) + '\u00F5')
+        con.color_pair(fg, bg)
+    }
+
+    function drawList() {
+        if (!hasList) return
+        const lbCol = listBlockCol()
+        const lbRow = listBlockTopRow()
+        const lw    = listBlockWidth()
+        const innerW = listContentInnerW()
+        const focused = (focusIdx === listFocusIdx)
+        const frameFg = focused ? fg : dimFg
+        const sbar = listScrollbarNeeded()
+
+        // Top border (drawField style)
+        if (drawWell) {
+            con.color_pair(listBgColour, bg)
+            con.move(lbRow, lbCol)
+            print('\u00EC' + '\u00A9'.repeat(lw - 2) + '\u00ED')
+        }
+
+        // Side borders + rows
+        for (let r = 0; r < listHeight; r++) {
+            if (drawWell) {
+                con.color_pair(listBgColour, bg)
+                con.move(lbRow + 1 + r, lbCol)
+                print('\u00AB')
+                con.move(lbRow + 1 + r, lbCol + lw - 1)
+                print('\u00AA')
+            }
+
+            const idx = listScroll + r
+            con.move(lbRow + 1 + r, lbCol + 1)
+            if (idx >= listItems.length) {
+                con.color_pair(fg, listBgColour)
+                print(' '.repeat(innerW))
+                continue
+            }
+            const it = listItems[idx]
+            const isCursor = (idx === listCursor)
+            const ctx = {
+                y: lbRow + 1 + r,
+                x: lbCol + 1,
+                w: innerW,
+                item: it,
+                idx: idx,
+                isCursor: isCursor,
+                focused: focused,
+                listBg: listBgColour,
+                selBg: listSelBg,
+                fg: fg,
+                hlFg: hlFg,
+                dimFg: dimFg,
+            }
+            if (list.renderItem) {
+                list.renderItem(ctx)
+            } else {
+                const useFg = (isCursor && focused) ? hlFg : fg
+                const useBg = (isCursor && focused) ? listSelBg : listBgColour
+                con.color_pair(useFg, useBg)
+                const label = (it.label || '').substring(0, innerW - 1)
+                print(' ' + label.padEnd(innerW - 1, ' '))
+            }
+
+            // Scrollbar column
+            if (sbar) {
+                con.color_pair(dimFg, listBgColour)
+                con.move(lbRow + 1 + r, lbCol + lw - 2)
+                const maxScroll = Math.max(1, listItems.length - listHeight)
+                const indPos = (maxScroll <= 0) ? 0 : ((listScroll * (listHeight - 1) / maxScroll) | 0)
+                // seg: 0 = top cap, 1 = middle, 2 = bottom cap; +3 selects the
+                // filled (thumb) variant over the empty (trough) one.
+                const seg = (r === 0) ? 0 : (r === listHeight - 1) ? 2 : 1
+                con.addch(listScrollbarChars[(r === indPos) ? seg + 3 : seg])
+            }
+        }
+
+        // Bottom border
+        if (drawWell) {
+            con.color_pair(listBgColour, bg)
+            con.move(lbRow + 1 + listHeight, lbCol)
+            print('\u00F4' + '\u00AC'.repeat(lw - 2) + '\u00F5')
+            con.color_pair(fg, bg)
+        }
+    }
+
+    function drawButton(i, regions) {
+        const b = buttons[i]
+        const bIdx = buttonsFocusBase + i
+        const focused = (focusIdx === bIdx)
+        const r = regions[i]
+        const useFg = focused ? hlFg : fg
+        const useBg = focused ? focusBg : bg
+        con.color_pair(useFg, useBg)
+        con.move(r.y, r.x-1)
+        if (focused) {
+            con.color_pair(useBg, bg)
+            print('\u00DE')
+            con.color_pair(useFg, useBg)
+            print('[ ' + b.label + ' ]')
+            con.color_pair(useBg, bg)
+            print('\u00DD')
+        }
+        else
+            print(' [ ' + b.label + ' ] ')
+        con.color_pair(fg, bg)
+    }
+
+    function positionCaret() {
+        if (focusIdx < fields.length) {
+            const fw = fields[focusIdx].width
+            const s = fieldScroll(cursors[focusIdx], fw)
+            con.move(fieldContentRow(focusIdx), fieldBoxCol() + 1 + (cursors[focusIdx] - s))
+            con.curs_set(1)
+        } else {
+            con.curs_set(0)
+        }
+    }
+
+    function ensureListCursorVisible() {
+        if (!hasList) return
+        if (listCursor < 0) return
+        if (listCursor < listScroll) listScroll = listCursor
+        else if (listCursor >= listScroll + listHeight) listScroll = listCursor - listHeight + 1
+        const maxScroll = Math.max(0, listItems.length - listHeight)
+        if (listScroll > maxScroll) listScroll = maxScroll
+        if (listScroll < 0) listScroll = 0
+    }
+
+    function scrollListBy(dir) {
+        const maxScroll = Math.max(0, listItems.length - listHeight)
+        let s = listScroll + dir
+        if (s < 0) s = 0
+        if (s > maxScroll) s = maxScroll
+        listScroll = s
+    }
+
+    function moveListCursor(dir) {
+        if (!hasList || listItems.length === 0) return
+        // Scroll the view when nothing in the list is selectable (e.g. a help text body).
+        if (listCursor < 0) { scrollListBy(dir); return }
+        let next = listCursor
+        for (let n = 0; n < listItems.length; n++) {
+            next += dir
+            if (next < 0 || next >= listItems.length) return
+            if (listSelectable(listItems[next], next)) {
+                listCursor = next
+                ensureListCursorVisible()
+                return
+            }
+        }
+    }
+
+    function pageListCursor(dir) {
+        if (!hasList || listItems.length === 0) return
+        if (listCursor < 0) { scrollListBy(dir * listHeight); return }
+        let target = listCursor + dir * listHeight
+        if (target < 0) target = 0
+        if (target >= listItems.length) target = listItems.length - 1
+        // Snap to nearest selectable
+        let probe = target
+        const step = dir < 0 ? -1 : 1
+        while (probe >= 0 && probe < listItems.length && !listSelectable(listItems[probe], probe)) probe += step
+        if (probe < 0 || probe >= listItems.length) probe = firstSelectable(target, -step)
+        if (probe >= 0) { listCursor = probe; ensureListCursorVisible() }
+    }
+
+    function render() {
+        drawFrameBox()
+        drawMessage()
+        for (let i = 0; i < fields.length; i++) drawField(i)
+        drawList()
+        const regs = buttonRegions()
+        for (let i = 0; i < buttons.length; i++) drawButton(i, regs)
+        positionCaret()
+    }
+
+    function moveFocus(dir) {
+        focusIdx = (focusIdx + dir + totalFocus) % totalFocus
+        render()
+    }
+
+    function activateButton(i) {
+        done = {
+            action: buttons[i].action,
+            values: values.slice(),
+            listCursor: listCursor,
+            listItem: (hasList && listCursor >= 0) ? listItems[listCursor] : null,
+        }
+    }
+
+    function activateListItem(idx, key) {
+        if (!hasList || !listOnActivate) return false
+        if (idx < 0 || idx >= listItems.length) return false
+        if (!listSelectable(listItems[idx], idx)) return false
+        const result = listOnActivate(listItems[idx], idx, key)
+        if (result == null) {
+            // Callback consumed the event but kept the dialog open (e.g. radio
+            // toggle); reflect any state changes it made.
+            render()
+            return true
+        }
+        done = {
+            action: result,
+            values: values.slice(),
+            listCursor: idx,
+            listItem: listItems[idx],
+        }
+        return true
+    }
+
+    function hitTestMouse(ev) {
+        const cell = _pxToCell(ev[1], ev[2])
+        const cy = cell[0], cx = cell[1]
+        const btnRegs = buttonRegions()
+        for (let i = 0; i < btnRegs.length; i++) {
+            const r = btnRegs[i]
+            if (cy === r.y && cx >= r.x && cx < r.x + r.w) return { kind: 'button', idx: i }
+        }
+        for (let i = 0; i < fields.length; i++) {
+            const r = fieldContentRegion(i)
+            if (cy === r.y && cx >= r.x && cx < r.x + r.w) return { kind: 'field', idx: i, cx: cx, region: r }
+        }
+        if (hasList) {
+            const lbRow = listBlockTopRow()
+            const lbCol = listBlockCol()
+            const innerW = listContentInnerW()
+            if (cy > lbRow && cy <= lbRow + listHeight && cx >= lbCol + 1 && cx < lbCol + 1 + innerW) {
+                const r = cy - (lbRow + 1)
+                const idx = listScroll + r
+                if (idx >= 0 && idx < listItems.length) return { kind: 'list', idx: idx }
+            }
+            if (cy > lbRow && cy <= lbRow + listHeight && cx >= lbCol && cx < lbCol + listBlockWidth()) {
+                return { kind: 'listblank' }
+            }
+        }
+        return null
+    }
+
+    const externalCtx = {
+        render: () => render(),
+        close: (result) => {
+            done = Object.assign({
+                action: 'cancel',
+                values: values.slice(),
+                listCursor: listCursor,
+                listItem: (hasList && listCursor >= 0) ? listItems[listCursor] : null,
+            }, result || {})
+        },
+        getListCursor: () => listCursor,
+        setListCursor: (n) => {
+            if (!hasList) return
+            if (n < 0 || n >= listItems.length) return
+            listCursor = n
+            ensureListCursorVisible()
+        },
+    }
+
+    ensureListCursorVisible()
+    render()
+
+    let eventJustReceived = true
+    while (done === null) {
+        input.withEvent(ev => {
+            if (eventJustReceived && (ev[0] === 'key_down' || ev[0] === 'mouse_down')) {
+                eventJustReceived = false; return
+            }
+
+            if (ev[0] === 'mouse_move') {
+                const hit = hitTestMouse(ev)
+                if (hit && hit.kind === 'button') {
+                    const newFocus = buttonsFocusBase + hit.idx
+                    if (newFocus !== focusIdx) {
+                        focusIdx = newFocus
+                        render()
+                    }
+                }
+                return
+            }
+            if (ev[0] === 'mouse_down') {
+                if (ev[3] !== 1) return
+                const hit = hitTestMouse(ev)
+                if (!hit) return
+                if (hit.kind === 'button') {
+                    focusIdx = buttonsFocusBase + hit.idx
+                    render()
+                    activateButton(hit.idx)
+                    return
+                }
+                if (hit.kind === 'field') {
+                    focusIdx = hit.idx
+                    const fw = fields[hit.idx].width
+                    const s = fieldScroll(cursors[hit.idx], fw)
+                    const newCur = s + (hit.cx - hit.region.x)
+                    cursors[hit.idx] = Math.min(values[hit.idx].length, Math.max(0, newCur))
+                    render()
+                    return
+                }
+                if (hit.kind === 'list') {
+                    focusIdx = listFocusIdx
+                    if (listSelectable(listItems[hit.idx], hit.idx)) {
+                        listCursor = hit.idx
+                        ensureListCursorVisible()
+                        render()
+                        if (activateListItem(hit.idx, 'click')) return
+                    } else {
+                        render()
+                    }
+                    return
+                }
+                if (hit.kind === 'listblank') {
+                    focusIdx = listFocusIdx
+                    render()
+                    return
+                }
+                return
+            }
+            if (ev[0] === 'mouse_wheel' && hasList) {
+                const hit = hitTestMouse(ev)
+                if (!hit || (hit.kind !== 'list' && hit.kind !== 'listblank')) return
+                const dy = (ev[3] | 0) * 3
+                const maxScroll = Math.max(0, listItems.length - listHeight)
+                let next = listScroll + dy
+                if (next < 0) next = 0
+                if (next > maxScroll) next = maxScroll
+                if (next !== listScroll) { listScroll = next; render() }
+                return
+            }
+            if (ev[0] !== 'key_down') return
+            if (opts.disableKeyRepeat && 1 !== ev[2]) return
+            const ks = ev[1]
+            const shiftDown = (ev.includes(59) || ev.includes(60))
+
+            if (opts.onKey && opts.onKey(ks, shiftDown, externalCtx)) return
+
+            if (ks === '<ESC>') {
+                done = {
+                    action: 'cancel',
+                    values: values.slice(),
+                    listCursor: listCursor,
+                    listItem: (hasList && listCursor >= 0) ? listItems[listCursor] : null,
+                }
+                return
+            }
+
+            if (ks === '\t' || ks === '<TAB>') { moveFocus(shiftDown ? -1 : 1); return }
+
+            // Vertical movement: arrows operate within the list when it has focus.
+            if (ks === '<UP>') {
+                if (focusIdx === listFocusIdx) { moveListCursor(-1); render() }
+                else moveFocus(-1)
+                return
+            }
+            if (ks === '<DOWN>') {
+                if (focusIdx === listFocusIdx) { moveListCursor(+1); render() }
+                else moveFocus(+1)
+                return
+            }
+            if (ks === '<PAGE_UP>') {
+                if (focusIdx === listFocusIdx) { pageListCursor(-1); render() }
+                return
+            }
+            if (ks === '<PAGE_DOWN>') {
+                if (focusIdx === listFocusIdx) { pageListCursor(+1); render() }
+                return
+            }
+
+            if (ks === '<LEFT>') {
+                if (focusIdx < fields.length) {
+                    if (cursors[focusIdx] > 0) { cursors[focusIdx] -= 1; render() }
+                } else moveFocus(-1)
+                return
+            }
+            if (ks === '<RIGHT>') {
+                if (focusIdx < fields.length) {
+                    if (cursors[focusIdx] < values[focusIdx].length) { cursors[focusIdx] += 1; render() }
+                } else moveFocus(+1)
+                return
+            }
+            if (ks === '<HOME>') {
+                if (focusIdx < fields.length) { cursors[focusIdx] = 0; render() }
+                else if (focusIdx === listFocusIdx) {
+                    const t = firstSelectable(0, +1)
+                    if (t >= 0) { listCursor = t; ensureListCursorVisible(); render() }
+                    else        { listScroll = 0; render() }
+                }
+                return
+            }
+            if (ks === '<END>') {
+                if (focusIdx < fields.length) { cursors[focusIdx] = values[focusIdx].length; render() }
+                else if (focusIdx === listFocusIdx) {
+                    const t = firstSelectable(listItems.length - 1, -1)
+                    if (t >= 0) { listCursor = t; ensureListCursorVisible(); render() }
+                    else        { listScroll = Math.max(0, listItems.length - listHeight); render() }
+                }
+                return
+            }
+
+            if (focusIdx < fields.length) {
+                if (ks === '\n') {
+                    if (focusIdx < fields.length - 1) focusIdx = focusIdx + 1
+                    else if (hasList) focusIdx = listFocusIdx
+                    else focusIdx = buttonsFocusBase
+                    render()
+                    return
+                }
+                if (ks === '\x08') {
+                    const cur = cursors[focusIdx]
+                    if (cur > 0) {
+                        const v = values[focusIdx]
+                        values[focusIdx] = v.substring(0, cur - 1) + v.substring(cur)
+                        cursors[focusIdx] = cur - 1
+                        render()
+                    }
+                    return
+                }
+                if (ks === '<DEL>') {
+                    const cur = cursors[focusIdx]
+                    const v = values[focusIdx]
+                    if (cur < v.length) {
+                        values[focusIdx] = v.substring(0, cur) + v.substring(cur + 1)
+                        render()
+                    }
+                    return
+                }
+                if (typeof ks === 'string' && ks.length === 1) {
+                    const code = ks.charCodeAt(0)
+                    const cap = fields[focusIdx].maxLength != null
+                        ? fields[focusIdx].maxLength
+                        : fields[focusIdx].width * 4
+                    if (code >= 32 && code < 256 && values[focusIdx].length < cap) {
+                        const v = values[focusIdx]
+                        const cur = cursors[focusIdx]
+                        values[focusIdx] = v.substring(0, cur) + ks + v.substring(cur)
+                        cursors[focusIdx] = cur + 1
+                        render()
+                    }
+                    return
+                }
+            } else if (focusIdx === listFocusIdx) {
+                if (ks === '\n' || ks === ' ') {
+                    if (listCursor >= 0 && activateListItem(listCursor, ks)) return
+                }
+            } else {
+                if (ks === '\n' || ks === ' ') { activateButton(focusIdx - buttonsFocusBase); return }
+            }
+        })
+    }
+
+    // Modal-dialog convention: wait for the user to release whatever key closed
+    // the dialog before handing control back. TVDOS's input strobo
+    // (TVDOS.SYS:input.withEvent) keeps re-firing `key_down` for a held key
+    // once its ~250 ms initial-press delay elapses; without this drain a brief
+    // hold on Enter inside a popup would surface as a fresh Enter to whatever
+    // the popup was covering, e.g. activating the file under zfm's More menu.
+    // A mouse close (or any path with no key held) leaves the head key at 0
+    // and skips the wait.
+    sys.poke(-40, 255)
+    const heldHead = sys.peek(-41)
+    if (heldHead !== 0) {
+        while (true) {
+            input.withEvent(() => {})
+            if (sys.peek(-41) !== heldHead) break
+        }
+    }
+
+    con.curs_set(0)
+    con.color_pair(oldFG, oldBG)
+    return done
+}
+
+exports = { WindowObject, scrollVert, scrollHorz, showDialog }

assets/disk0/tvdos/sbin/vtmgr.js

@@ -0,0 +1,561 @@
+// vtmgr — virtual console manager for TVDOS
+//
+// Spawns up to 6 independent shell sessions (virtual consoles), each in its
+// own parallel GraalVM context with its own thread. Each pane runs a real
+// `command -fancy` shell. The dispatcher (this file) owns the physical
+// keyboard, polls Alt-N hotkeys at 30 Hz, blits the active pane's text
+// plane to the GPU's text area, and routes typed characters into the
+// active pane's input ring buffer.
+//
+// Hotkeys: Alt-1..Alt-6 switch to that VT (lazy-spawn on first use).
+//          Alt-0 cleanly tears down vtmgr.
+// Builtins: `chvt N` from inside a pane writes to the switch register.
+
+// ─── shared memory layout ───────────────────────────────────────────────────
+// CTRL_AREA (64 bytes from base)
+//   +0  active_vt        u8 (1..6)
+//   +1  switch_request   u8 (0 = none, 1..6 = target; set by chvt, cleared by dispatcher)
+//   +2  debounce_held    u8
+//   +3  vt_spawned_bits  u8 (bit n-1 set if VT n is alive)
+//   +4..63 reserved
+// VT block (× MAX_VT) starting at base + 64, each VT_BLOCK_SIZE bytes
+//   +0..7 reserved (cursor & color state lives inside text plane itself)
+//   +8    queue_head       u8 (next-read index)
+//   +9    queue_tail       u8 (next-write index)
+//   +10..11 reserved
+//   +12..267 queue_data    (256-byte ring buffer; one slot lost to full/empty disambiguation)
+//   +268..271 reserved (alignment)
+//   +272..7953 text_plane (7682 bytes; mirrors GPU textArea layout exactly)
+
+const MAX_VT = 6
+const CTRL_AREA_SIZE = 64
+const VT_BLOCK_SIZE = 8000
+const TEXT_PLANE_OFFSET = 272
+const TEXT_PLANE_SIZE = 7682
+const QUEUE_DATA_OFFSET = 12
+
+const CTRL_ACTIVE_VT      = 0
+const CTRL_SWITCH_REQUEST = 1
+const CTRL_DEBOUNCE_HELD  = 2
+const CTRL_SPAWNED_BITS   = 3
+
+const GPU_TEXTAREA_OFFSET = 253950
+const TEXT_COLS = 80
+const TEXT_ROWS = 32
+
+const TP_FORE_BASE = 2
+const TP_BACK_BASE = 2 + 2560
+const TP_TEXT_BASE = 2 + 2560 + 2560
+
+const TOTAL_ALLOC_SIZE = CTRL_AREA_SIZE + MAX_VT * VT_BLOCK_SIZE
+const BASE = sys.malloc(TOTAL_ALLOC_SIZE)
+if (!BASE || BASE === 0) { printerrln("vtmgr: sys.malloc failed"); return 1 }
+for (let i = 0; i < TOTAL_ALLOC_SIZE; i++) sys.poke(BASE + i, 0)
+
+const CTRL = BASE
+function vtBlockAddr(n)     { return BASE + CTRL_AREA_SIZE + (n - 1) * VT_BLOCK_SIZE }
+function vtTextPlaneAddr(n) { return vtBlockAddr(n) + TEXT_PLANE_OFFSET }
+
+// ─── pane bootstrap ─────────────────────────────────────────────────────────
+// Read TVDOS.SYS once at startup. Each pane's bootstrap embeds the source
+// (via JSON.stringify-escaped string literal) and evaluates it together with
+// the shell-start code as ONE direct-eval call. This matters because strict-
+// mode direct eval is scope-isolated; if TVDOS.SYS and the shell launcher
+// were two separate evals, the shell launcher wouldn't see `_TVDOS`,
+// `files`, `execApp`, etc. defined by the first eval.
+
+const TVDOS_SYS_SRC = files.open("A:/tvdos/TVDOS.SYS").sread()
+
+// _BIOS is set by the real BIOS before TVDOS.SYS runs; TVDOS.SYS reads
+// _BIOS.FIRST_BOOTABLE_PORT during init. Each pane is a fresh context with no
+// BIOS, so capture the live value here (vtmgr runs in the main context where
+// _BIOS is visible) and re-declare it in every pane bootstrap.
+const BIOS_FIRST_BOOTABLE_PORT = JSON.stringify(_BIOS.FIRST_BOOTABLE_PORT)
+
+// Environment no longer needs snapshotting/replaying: each pane re-evaluates
+// TVDOS.SYS, whose boot block runs \commandrc in every context, so the pane
+// gets the same PATH / KEYBOARD / etc. natively. The pane then runs
+// \AUTOEXEC.BAT (the per-console launch script: IME + interactive shell).
+
+function makePaneBootstrap(vtNum) {
+    const TP_BASE = vtTextPlaneAddr(vtNum)
+    const VT_BLK = vtBlockAddr(vtNum)
+
+    // Launcher code runs after TVDOS.SYS in the SAME eval scope, so `files`,
+    // `eval`, `_TVDOS` etc. resolve via lexical closure. TVDOS.SYS's boot
+    // block already ran \commandrc (env) and skipped its own AUTOEXEC because
+    // the pane sets _TVDOS_IS_VT_PANE; here we run \AUTOEXEC.BAT to launch the
+    // per-console shell.
+    const SHELL_START = ";\n"
+        + "var _cmdfileSrc = files.open('A:/tvdos/bin/command.js').sread();\n"
+        + "eval('var _VTSHELL=function(exec_args){' + _cmdfileSrc + '\\n};_VTSHELL')(['', '-c', '\\\\AUTOEXEC.BAT']);\n"
+
+    const combined = TVDOS_SYS_SRC + SHELL_START
+
+    const raw = `
+globalThis.VT_NUM = ${vtNum}
+globalThis.VT_TEXT_PLANE = ${TP_BASE}
+globalThis.VT_BLOCK_ADDR = ${VT_BLK}
+globalThis.VT_CTRL_ADDR = ${CTRL}
+const TP = ${TP_BASE}
+const VT_BLK = ${VT_BLK}
+const CTRL = ${CTRL}
+const QUEUE_DATA = VT_BLK + ${QUEUE_DATA_OFFSET}
+const QUEUE_HEAD_ADDR = VT_BLK + 8
+const QUEUE_TAIL_ADDR = VT_BLK + 9
+const ACTIVE_VT_ADDR = CTRL + ${CTRL_ACTIVE_VT}
+const COLS = ${TEXT_COLS}, ROWS = ${TEXT_ROWS}
+const FORE_BASE = ${TP_FORE_BASE}, BACK_BASE = ${TP_BACK_BASE}, TEXT_BASE = ${TP_TEXT_BASE}
+
+// ── output shims (write into the per-VT text-plane buffer in shared mem) ──
+// This is a faithful JS port of the GPU's TTY interpreter (GlassTty.acceptChar
+// + GraphicsAdapter handlers). TVDOS apps drive the screen by printing control
+// bytes and escape sequences through print(), so the shim must interpret them
+// exactly as the hardware would: the \\x84<decimal>u "emit char by code" escape
+// (used by con.prnch), CSI cursor moves / erase / SGR colours, and the ?25
+// cursor-visibility private sequence.
+let curX = 0, curY = 0
+let foreCol = 254
+let backCol = 255
+
+// Per-pane cursor visibility lives at VT_BLK+2 (1 = blink on, 0 = hidden).
+// The compositor pushes the active pane's value into the GPU's blink bit.
+const CURSOR_VIS_ADDR = VT_BLK + 2
+sys.poke(CURSOR_VIS_ADDR, 1)
+
+// SGR 30-37 / 40-47 → default 8-colour palette (matches GraphicsAdapter).
+const SGR_PAL = [240, 211, 61, 230, 49, 219, 114, 254]
+
+function writeCursor() {
+    let pos = curY * COLS + curX
+    sys.poke(TP + 0, pos & 0xFF)
+    sys.poke(TP + 1, (pos >> 8) & 0xFF)
+}
+function scrollBufUp(n) {
+    if (n < 1) n = 1
+    if (n > ROWS) n = ROWS
+    for (let p of [FORE_BASE, BACK_BASE, TEXT_BASE]) {
+        for (let y = 0; y < ROWS - n; y++) {
+            for (let x = 0; x < COLS; x++) {
+                sys.poke(TP + p + y * COLS + x, sys.peek(TP + p + (y + n) * COLS + x))
+            }
+        }
+        let clearVal = (p === TEXT_BASE) ? 0 : (p === FORE_BASE ? foreCol : backCol)
+        for (let y = ROWS - n; y < ROWS; y++)
+            for (let x = 0; x < COLS; x++) sys.poke(TP + p + y * COLS + x, clearVal)
+    }
+}
+function putCharRaw(x, y, c) {
+    if (x < 0 || x >= COLS || y < 0 || y >= ROWS) return
+    let off = y * COLS + x
+    sys.poke(TP + TEXT_BASE + off, c & 0xFF)
+    sys.poke(TP + FORE_BASE + off, foreCol)
+    sys.poke(TP + BACK_BASE + off, backCol)
+}
+// Mirror of GraphicsAdapter.setCursorPos: wrap on overflow x, scroll on
+// overflow y, clamp y above the screen.
+function setCursorPos(x, y) {
+    let nx = x, ny = y
+    if (nx >= COLS) { nx = 0; ny += 1 }
+    else if (nx < 0) nx = 0
+    if (ny < 0) ny = 0
+    else if (ny >= ROWS) { scrollBufUp(ny - ROWS + 1); ny = ROWS - 1 }
+    curX = nx; curY = ny
+    writeCursor()
+}
+
+// ── TTY actions (mirror the GraphicsAdapter overrides) ────────────────────
+function ttyPrintable(c) { putCharRaw(curX, curY, c); setCursorPos(curX + 1, curY) }
+function ttyCrlf() {
+    let ny = curY + 1
+    setCursorPos(0, (ny >= ROWS) ? ROWS - 1 : ny)
+    if (ny >= ROWS) scrollBufUp(1)
+}
+function ttyBackspace() { let x = curX, y = curY; setCursorPos(x - 1, y); putCharRaw(curX, curY, 0x20) }
+function ttyTab() { setCursorPos(((curX / 8 | 0) + 1) * 8, curY) }
+function ttyResetStatus() { foreCol = 253; backCol = 255 }
+function ttyEmitChar(code) { putCharRaw(curX, curY, code); setCursorPos(curX + 1, curY) }
+function ttyCursorUp(n) { setCursorPos(curX, curY - n) }
+function ttyCursorDown(n) { let ny = curY + n; setCursorPos(curX, (ny >= ROWS) ? ROWS - 1 : ny) }
+function ttyCursorFwd(n) { setCursorPos(curX + n, curY) }
+function ttyCursorBack(n) { setCursorPos(curX - n, curY) }
+function ttyCursorNextLine(n) { let ny = curY + n; setCursorPos(0, (ny >= ROWS) ? ROWS - 1 : ny); if (ny >= ROWS) scrollBufUp(ny - ROWS + 1) }
+function ttyCursorPrevLine(n) { setCursorPos(0, curY - n) }
+function ttyCursorX(n) { setCursorPos(n, curY) }
+function ttyCursorXY(row, col) { setCursorPos(col - 1, row - 1) }
+function ttyEraseInDisp(arg) {
+    if (arg === 2) {
+        for (let i = 0; i < COLS * ROWS; i++) {
+            sys.poke(TP + TEXT_BASE + i, 0)
+            sys.poke(TP + FORE_BASE + i, foreCol)
+            sys.poke(TP + BACK_BASE + i, backCol)
+        }
+        curX = 0; curY = 0; writeCursor()
+    }
+    // other args: GraphicsAdapter TODOs (throws); we no-op for safety
+}
+function ttySgr1(arg) {
+    if (arg >= 30 && arg <= 37) foreCol = SGR_PAL[arg - 30]
+    else if (arg >= 40 && arg <= 47) backCol = SGR_PAL[arg - 40]
+    else if (arg === 7) { let t = foreCol; foreCol = backCol; backCol = t }
+    else if (arg === 0) { foreCol = 253; backCol = 255; sys.poke(CURSOR_VIS_ADDR, 1) }
+}
+function ttySgr3(a1, a2, a3) {
+    if (a1 === 38 && a2 === 5) foreCol = a3
+    else if (a1 === 48 && a2 === 5) backCol = a3
+}
+function ttyPrivH(arg) { if (arg === 25) sys.poke(CURSOR_VIS_ADDR, 1) }
+function ttyPrivL(arg) { if (arg === 25) sys.poke(CURSOR_VIS_ADDR, 0) }
+
+// ── escape-sequence state machine (mirror of GlassTty.acceptChar) ─────────
+// States: 0 INITIAL, 1 ESC, 2 CSI, 3 NUM1, 4 SEP1, 5 NUM2, 6 SEP2, 7 NUM3,
+//         8 PRIVATESEQ, 9 PRIVATENUM, 10 XCSI, 11 XNUM1
+let escState = 0
+let escArgs = []
+function isDig(c) { return c >= 0x30 && c <= 0x39 }
+function escReset() { escState = 0; escArgs.length = 0 }
+// reject() in hardware returns the char as printable; replicate by printing it
+function escRejectPrint(c) { escReset(); ttyPrintable(c) }
+
+function processByte(c) {
+    switch (escState) {
+        case 0: // INITIAL
+            if (c === 0x1B) escState = 1
+            else if (c === 0x84) escState = 10
+            else if (c === 0x0A) ttyCrlf()
+            else if (c === 0x08) ttyBackspace()
+            else if (c === 0x09) ttyTab()
+            else if (c === 0x07) { /* bell */ }
+            else if (c >= 0x00 && c <= 0x1F) { /* other control: ignored */ }
+            else ttyPrintable(c)
+            break
+        case 1: // ESC
+            if (c === 0x63) { ttyResetStatus(); escReset() }       // 'c'
+            else if (c === 0x5B) escState = 2                       // '['
+            else escRejectPrint(c)
+            break
+        case 2: // CSI
+            if (c === 0x41) { ttyCursorUp(1); escReset() }
+            else if (c === 0x42) { ttyCursorDown(1); escReset() }
+            else if (c === 0x43) { ttyCursorFwd(1); escReset() }
+            else if (c === 0x44) { ttyCursorBack(1); escReset() }
+            else if (c === 0x45) { ttyCursorNextLine(1); escReset() }
+            else if (c === 0x46) { ttyCursorPrevLine(1); escReset() }
+            else if (c === 0x47) { ttyCursorX(1); escReset() }
+            else if (c === 0x4A) { ttyEraseInDisp(0); escReset() }
+            else if (c === 0x4B) { escReset() }                    // eraseInLine: no-op
+            else if (c === 0x53) { scrollBufUp(1); escReset() }    // S
+            else if (c === 0x54) { escReset() }                    // T scrollDown: no-op
+            else if (c === 0x6D) { ttySgr1(0); escReset() }        // m
+            else if (c === 0x3F) escState = 8                      // '?'
+            else if (c === 0x3B) { escArgs.push(0); escState = 4 } // ';'
+            else if (isDig(c)) { escArgs.push(c - 0x30); escState = 3 }
+            else escRejectPrint(c)
+            break
+        case 3: // NUM1
+            if (c === 0x41) { ttyCursorUp(escArgs.pop()); escReset() }
+            else if (c === 0x42) { ttyCursorDown(escArgs.pop()); escReset() }
+            else if (c === 0x43) { ttyCursorFwd(escArgs.pop()); escReset() }
+            else if (c === 0x44) { ttyCursorBack(escArgs.pop()); escReset() }
+            else if (c === 0x45) { ttyCursorNextLine(escArgs.pop()); escReset() }
+            else if (c === 0x46) { ttyCursorPrevLine(escArgs.pop()); escReset() }
+            else if (c === 0x47) { ttyCursorX(escArgs.pop()); escReset() }
+            else if (c === 0x4A) { ttyEraseInDisp(escArgs.pop()); escReset() }
+            else if (c === 0x4B) { escArgs.pop(); escReset() }
+            else if (c === 0x53) { scrollBufUp(escArgs.pop()); escReset() }
+            else if (c === 0x54) { escArgs.pop(); escReset() }
+            else if (c === 0x6D) { ttySgr1(escArgs.pop()); escReset() }
+            else if (c === 0x3B) escState = 4
+            else if (isDig(c)) escArgs.push(escArgs.pop() * 10 + (c - 0x30))
+            else escRejectPrint(c)
+            break
+        case 4: // SEP1 (seen "n;")
+            if (isDig(c)) { escArgs.push(c - 0x30); escState = 5 }
+            else if (c === 0x48) { let a1 = escArgs.pop(); ttyCursorXY(a1, 0); escReset() }   // H
+            else if (c === 0x6D) { ttySgr1(escArgs.pop()); escReset() }                       // m (2-arg unimpl in HW)
+            else if (c === 0x3B) { escArgs.push(0); escState = 6 }
+            else escRejectPrint(c)
+            break
+        case 5: // NUM2 (seen "n;n")
+            if (isDig(c)) escArgs.push(escArgs.pop() * 10 + (c - 0x30))
+            else if (c === 0x48) { let a2 = escArgs.pop(), a1 = escArgs.pop(); ttyCursorXY(a1, a2); escReset() }
+            else if (c === 0x6D) { escArgs.pop(); escArgs.pop(); escReset() }  // 2-arg SGR unimpl in HW
+            else if (c === 0x3B) escState = 6
+            else escRejectPrint(c)
+            break
+        case 6: // SEP2 (seen "n;n;")
+            if (c === 0x6D) { let a2 = escArgs.pop(), a1 = escArgs.pop(); ttySgr3(a1, a2, 0); escReset() }
+            else if (isDig(c)) { escArgs.push(c - 0x30); escState = 7 }
+            else escRejectPrint(c)
+            break
+        case 7: // NUM3 (seen "n;n;n")
+            if (isDig(c)) escArgs.push(escArgs.pop() * 10 + (c - 0x30))
+            else if (c === 0x6D) { let a3 = escArgs.pop(), a2 = escArgs.pop(), a1 = escArgs.pop(); ttySgr3(a1, a2, a3); escReset() }
+            else escRejectPrint(c)
+            break
+        case 8: // PRIVATESEQ (seen "?")
+            if (isDig(c)) { escArgs.push(c - 0x30); escState = 9 }
+            else escRejectPrint(c)
+            break
+        case 9: // PRIVATENUM (seen "?n")
+            if (c === 0x68) { ttyPrivH(escArgs.pop()); escReset() }       // h
+            else if (c === 0x6C) { ttyPrivL(escArgs.pop()); escReset() }  // l
+            else if (isDig(c)) escArgs.push(escArgs.pop() * 10 + (c - 0x30))
+            else escRejectPrint(c)
+            break
+        case 10: // XCSI (seen \\x84)
+            if (c === 0x75) { ttyEmitChar(0); escReset() }                // 'u'
+            else if (isDig(c)) { escArgs.push(c - 0x30); escState = 11 }
+            else escRejectPrint(c)
+            break
+        case 11: // XNUM1 (seen \\x84<digits>)
+            if (c === 0x75) { ttyEmitChar(escArgs.pop()); escReset() }     // 'u'
+            else if (isDig(c)) escArgs.push(escArgs.pop() * 10 + (c - 0x30))
+            else escRejectPrint(c)
+            break
+    }
+}
+
+print = function(s) {
+    if (s === undefined || s === null) return
+    let str = '' + s
+    for (let i = 0; i < str.length; i++) processByte(str.charCodeAt(i))
+}
+println = function(s) {
+    if (s === undefined) print("\\n")
+    else print(s + "\\n")
+}
+printerr = function(s) { print(s) }
+printerrln = function(s) { println(s) }
+
+// command.js's shell.execute reassigns the global print/println/printerr/
+// printerrln to shell.stdio.out.* (which call sys.print → physical GPU,
+// bypassing these shims). Expose the buffer writers through a global hook so
+// shell.stdio.out can delegate to them when running inside a VT pane. The
+// non-VT path in command.js stays unchanged (hook is undefined there).
+globalThis.__VT_OUT = { print: print, println: println, printerr: printerr, printerrln: printerrln }
+
+// con.move / con.getyx are 1-based in TVDOS (graphics.setCursorYX does cx-1,
+// getCursorYX returns cx+1). Internal curX/curY are 0-based, so convert.
+con.move = function(y, x) {
+    curY = Math.max(0, Math.min(ROWS - 1, (y | 0) - 1))
+    curX = Math.max(0, Math.min(COLS - 1, (x | 0) - 1))
+    writeCursor()
+}
+con.getyx = function() { return [curY + 1, curX + 1] }
+con.getmaxyx = function() { return [ROWS, COLS] }
+con.color_pair = function(f, b) { foreCol = f & 0xFF; backCol = b & 0xFF }
+con.color_fore = function(n) { foreCol = n & 0xFF }
+con.color_back = function(n) { backCol = n & 0xFF }
+con.get_color_fore = function() { return foreCol }
+con.get_color_back = function() { return backCol }
+// addch writes a glyph at the cursor WITHOUT advancing — matching
+// graphics.putSymbol(). TVDOS code pairs addch with explicit curs_right();
+// advancing here would double-step and leave gaps (e.g. the fancy prompt).
+con.addch = function(c) { putCharRaw(curX, curY, c) }
+con.mvaddch = function(y, x, c) { con.move(y, x); con.addch(c) }
+con.curs_up = function(n) { n = n || 1; curY = Math.max(0, curY - n); writeCursor() }
+con.curs_down = function(n) { n = n || 1; curY = Math.min(ROWS - 1, curY + n); writeCursor() }
+con.curs_left = function(n) { n = n || 1; curX = Math.max(0, curX - n); writeCursor() }
+con.curs_right = function(n) { n = n || 1; curX = Math.min(COLS - 1, curX + n); writeCursor() }
+con.curs_set = function(arg) { sys.poke(CURSOR_VIS_ADDR, ((arg | 0) === 0) ? 0 : 1) }
+con.video_reverse = function() { /* unsupported; ANSI swallowed */ }
+con.reset_graphics = function() { foreCol = 254; backCol = 255 }
+con.clear = function() {
+    for (let i = 0; i < COLS * ROWS; i++) {
+        sys.poke(TP + TEXT_BASE + i, 0)
+        sys.poke(TP + FORE_BASE + i, foreCol)
+        sys.poke(TP + BACK_BASE + i, backCol)
+    }
+    curX = 0; curY = 0; writeCursor()
+}
+// prnch prints a glyph and DOES advance (unlike addch) — the real impl emits
+// it through print() as \\x84<code>u, so route it through the interpreter.
+con.prnch = function(c) {
+    if (Array.isArray(c)) c.forEach(x => ttyEmitChar(x))
+    else ttyEmitChar(c)
+}
+
+// ── input shims ──────────────────────────────────────────────────────────
+// Pane reads from its own ring buffer in shared mem. NEVER touches physical
+// keyboard MMIO — that's the dispatcher's exclusive territory. Cooperative
+// gate on active_vt keeps background panes parked when they call getch.
+
+function queuePop() {
+    let head = sys.peek(QUEUE_HEAD_ADDR)
+    let tail = sys.peek(QUEUE_TAIL_ADDR)
+    if (head === tail) return -1
+    let b = sys.peek(QUEUE_DATA + head)
+    sys.poke(QUEUE_HEAD_ADDR, (head + 1) & 0xFF)
+    return b
+}
+con.getch = function() {
+    while (true) {
+        if (sys.peek(ACTIVE_VT_ADDR) === VT_NUM) {
+            let k = queuePop()
+            if (k >= 0) return k
+        }
+        sys.sleep(20)
+    }
+}
+con.hitterminate = function() { return false }
+con.hiteof = function() { return false }
+con.resetkeybuf = function() { sys.poke(QUEUE_HEAD_ADDR, sys.peek(QUEUE_TAIL_ADDR)) }
+con.poll_keys = function() { return [0,0,0,0,0,0,0,0] }
+
+// ── TVDOS.SYS init flags + BIOS stub ───────────────────────────────────────
+globalThis._TVDOS_IS_VT_PANE = true
+globalThis._BIOS = { FIRST_BOOTABLE_PORT: ${BIOS_FIRST_BOOTABLE_PORT} }
+
+// ── load TVDOS.SYS and run AUTOEXEC.BAT (the per-console shell) in one direct-eval ─────
+// Strict-mode direct eval is scope-isolated, so TVDOS.SYS's \`const _TVDOS\`
+// only survives within the eval scope. The shell launcher must run inside
+// the same eval to access it (via lexical closure into nested evals).
+eval(${JSON.stringify(combined)})
+`
+    // The outer execApp's injectIntChk rewrote the first while/for/do (each
+    // kind) in our literal source to call a per-exec SIGTERM check function.
+    // Some of those rewrites landed inside this template literal — the pane
+    // has no such symbol in scope. Strip them; panes don't need SIGTERM
+    // checks (parallel.kill handles teardown).
+    return raw.replace(/tvdosSIGTERM_[A-Za-z0-9_]+\(\);?/g, '')
+}
+
+// ─── pane lifecycle ─────────────────────────────────────────────────────────
+// Lazy spawn: VT 1 at boot; VT 2-6 the first time the user requests them.
+// Re-spawn if the previous pane's thread has died (e.g. user typed `exit`).
+
+const panes = {}  // n -> { runner, thread }
+
+function isPaneAlive(n) {
+    return panes[n] && parallel.isRunning(panes[n].thread)
+}
+
+function spawnPane(n) {
+    serial.println("[vtmgr] spawning VT " + n)
+    let runner = parallel.spawnNewContext()
+    let thread = parallel.attachProgram("vt" + n, runner, makePaneBootstrap(n))
+    parallel.launch(thread)
+    panes[n] = { runner: runner, thread: thread }
+    sys.poke(CTRL + CTRL_SPAWNED_BITS, sys.peek(CTRL + CTRL_SPAWNED_BITS) | (1 << (n - 1)))
+}
+
+function ensurePane(n) {
+    if (!isPaneAlive(n)) {
+        sys.poke(CTRL + CTRL_SPAWNED_BITS, sys.peek(CTRL + CTRL_SPAWNED_BITS) & ~(1 << (n - 1)))
+        spawnPane(n)
+    }
+}
+
+ensurePane(1)
+sys.poke(CTRL + CTRL_ACTIVE_VT, 1)
+// VT 1's TVDOS.SYS eval is slow; give it room before we start compositing.
+sys.sleep(800)
+
+// ─── compositor / dispatcher loop ───────────────────────────────────────────
+// 30 Hz: blit active pane → GPU text area; honour switch_request; detect
+// Alt-N with debounce; drain typed chars into active pane's queue.
+
+const gpuBase = graphics.getGpuMemBase()
+const TEXTAREA_BASE_ABS = gpuBase - GPU_TEXTAREA_OFFSET
+function blitVt(srcAddr) {
+    sys.memcpy(srcAddr, TEXTAREA_BASE_ABS, TEXT_PLANE_SIZE - 2)
+    sys.poke(TEXTAREA_BASE_ABS - (TEXT_PLANE_SIZE - 2), sys.peek(srcAddr + TEXT_PLANE_SIZE - 2))
+    sys.poke(TEXTAREA_BASE_ABS - (TEXT_PLANE_SIZE - 1), sys.peek(srcAddr + TEXT_PLANE_SIZE - 1))
+}
+
+// GPU textmode-attribute MMIO byte (offset 6): bit 0 = blinkCursor, bit 1 =
+// rawMode, bits 4-7 = chrrom. We flip only bit 0 to match the active pane's
+// cursor visibility. getGpuMemBase() = -1 - 1MB*slot; the peripheral's MMIO
+// window sits at IOSpace offset 128KB*slot, so MMIO byte k = -1 - (128KB*slot + k).
+const gpuSlot = (((-gpuBase) - 1) / 1048576) | 0
+const GPU_MMIO_ATTR = -1 - (131072 * gpuSlot + 6)
+let lastCursorVis = -1
+function applyCursorVis(active) {
+    let vis = sys.peek(vtBlockAddr(active) + 2)
+    if (vis === lastCursorVis) return
+    let attr = sys.peek(GPU_MMIO_ATTR)
+    sys.poke(GPU_MMIO_ATTR, vis ? (attr | 1) : (attr & 0xFE))
+    lastCursorVis = vis
+}
+
+function queuePush(vtN, byte) {
+    let qBase = vtBlockAddr(vtN)
+    let head = sys.peek(qBase + 8)
+    let tail = sys.peek(qBase + 9)
+    let next = (tail + 1) & 0xFF
+    if (next === head) return false
+    sys.poke(qBase + QUEUE_DATA_OFFSET + tail, byte)
+    sys.poke(qBase + 9, next)
+    return true
+}
+
+function switchTo(n) {
+    if (n < 1 || n > MAX_VT) return
+    ensurePane(n)
+    sys.poke(CTRL + CTRL_ACTIVE_VT, n)
+}
+
+sys.poke(-39, 1)  // enable physical keyboard input collection
+
+let running = true
+while (running) {
+    let active = sys.peek(CTRL + CTRL_ACTIVE_VT)
+    if (active < 1 || active > MAX_VT) active = 1
+    blitVt(vtTextPlaneAddr(active))
+    applyCursorVis(active)
+
+    // honour chvt's switch request
+    let req = sys.peek(CTRL + CTRL_SWITCH_REQUEST)
+    if (req >= 1 && req <= MAX_VT) {
+        if (req !== active) {
+            serial.println("[vtmgr] chvt switch -> VT " + req)
+            switchTo(req)
+        }
+        sys.poke(CTRL + CTRL_SWITCH_REQUEST, 0)
+    }
+
+    // Alt-N (and Alt-0 = exit) detection
+    sys.poke(-40, 1)
+    let keys = [sys.peek(-41), sys.peek(-42), sys.peek(-43), sys.peek(-44),
+                sys.peek(-45), sys.peek(-46), sys.peek(-47), sys.peek(-48)]
+    let altHeld = keys.indexOf(57) >= 0 || keys.indexOf(58) >= 0
+    let digit = -1
+    for (let n = 0; n <= MAX_VT; n++) {
+        if (keys.indexOf(7 + n) >= 0) { digit = n; break }
+    }
+    let debounce = sys.peek(CTRL + CTRL_DEBOUNCE_HELD) !== 0
+
+    if (debounce) {
+        if (!altHeld && digit < 0) sys.poke(CTRL + CTRL_DEBOUNCE_HELD, 0)
+    }
+    else if (altHeld && digit === 0) {
+        serial.println("[vtmgr] Alt-0 -> exit")
+        running = false
+        sys.poke(CTRL + CTRL_DEBOUNCE_HELD, 1)
+        sys.poke(-39, 1)
+    }
+    else if (altHeld && digit >= 1) {
+        serial.println("[vtmgr] Alt-" + digit + " -> switching to VT " + digit)
+        switchTo(digit)
+        sys.poke(CTRL + CTRL_DEBOUNCE_HELD, 1)
+        sys.poke(-39, 1)  // swallow the digit char so it doesn't leak into the queue
+    }
+
+    if (!running) break
+
+    // drain typed chars into the active pane's queue
+    while (sys.peek(-50) !== 0) {
+        let k = sys.peek(-38)
+        if (k < 0) k += 256
+        queuePush(active, k)
+    }
+
+    sys.sleep(33)
+}
+
+for (let n = 1; n <= MAX_VT; n++) if (panes[n]) parallel.kill(panes[n].thread)
+con.color_pair(254, 255)
+con.clear()
+println("vtmgr exited.")
+return 0

it2taud.py

@@ -57,6 +57,7 @@ from taud_common import (
     normalise_sample, encode_song_entry, nearest_minifloat, compress_blob,
     CUE_INST_NOP, CUE_INST_HALT, CUE_INST_LEN, cue_instruction_len,
     build_project_data, detect_subsongs,
+    IXMP_PAN_NO_OVERRIDE,
 )
 
 
@@ -435,7 +436,10 @@ class ITInstrument:
                  'vol_env_loop', 'pan_env_loop', 'pf_env_loop',
                  'vol_env_sus', 'pan_env_sus', 'pf_env_sus',
                  'ifc', 'ifr', 'fadeout', 'pps', 'ppc', 'rv', 'rp', 'nna',
-                 'dct', 'dca')
+                 'dct', 'dca', 'keyboard')
+    # keyboard: list[int], 120 entries — keyboard[it_note] = sample_1based (0 = none).
+    # Carried verbatim from the IT file so the Ixmp emitter can build patches that
+    # cover non-canonical-sample note ranges. terranmon.txt "Ixmp" + Schism iti.c:80.
     # vol_envelope / pan_envelope / pf_envelope: list of 25 (value, minifloat_idx) tuples, or None
     # *_env_sustain: int (16-bit, 0b 0ut sssss pcb eeeee), 0 = no envelope
     # pf_is_filter: bool — pf envelope mode (False = pitch, True = filter)
@@ -478,6 +482,7 @@ def parse_instruments(data: bytes, h: ITHeader) -> list:
             kb_note = data[ptr + 0x44 + n*2]
             kb_smp  = data[ptr + 0x44 + n*2 + 1]
             keyboard.append(kb_smp)  # 0 = no sample
+        inst.keyboard = keyboard
 
         # Pick C-5 (note 60) sample; fall back to most-frequent non-zero
         c5_smp = keyboard[60] if 60 < len(keyboard) else 0
@@ -1119,6 +1124,133 @@ def _remap_bc_effects(chunks: list, chunk_map: list,
                f"subsong boundary; clamped to cue {default_target}")
 
 
+# ── Ixmp patch builder (multi-sample IT instruments) ─────────────────────────
+
+def _it_note_to_taud(note: int, clamp_low: bool = False, clamp_high: bool = False) -> int:
+    """IT note (0..119, C-5 = 60) → Taud 4096-TET noteVal anchored at TAUD_C4.
+    `clamp_low`/`clamp_high` expand the bottom/top of the keyboard to cover the
+    full Taud playable range, so patches at the keyboard's edges don't leave
+    notes outside the trigger rectangle unmatched."""
+    if clamp_low:  return 0x0000
+    if clamp_high: return 0xFFFF
+    val = round(TAUD_C4 + (note - 60) * 4096 / 12)
+    return max(0x0020, min(0xFFFF, val))
+
+
+def _build_it_ixmp_patches(inst, samples, extras_offsets) -> list:
+    """For one IT instrument, return a list of Ixmp patch dicts covering every
+    keyboard cell that maps to a NON-canonical sample. The canonical sample is
+    served by the base instrument record so no patch is emitted for it (the
+    engine falls through to the base inst when no patch matches).
+
+    Note ranges are contiguous runs of keyboard cells that point at the same
+    sample. Per the Ixmp spec each (pitch_start..pitch_end, volume_start..end)
+    rectangle MUST NOT overlap any other patch on the same instrument; this is
+    guaranteed here because the keyboard mapping itself is a partition."""
+    canonical = inst.canonical_sample
+    kbd = getattr(inst, 'keyboard', None)
+    if not kbd:
+        return []
+    # Distinct non-canonical samples referenced.
+    distinct = []
+    seen = set()
+    for kb_smp in kbd:
+        if kb_smp == 0 or kb_smp == canonical:
+            continue
+        if kb_smp not in seen and 1 <= kb_smp <= len(samples) and samples[kb_smp - 1] is not None:
+            seen.add(kb_smp); distinct.append(kb_smp)
+    if not distinct:
+        return []
+
+    patches = []
+    for smp_1based in distinct:
+        si = smp_1based - 1
+        s = samples[si]
+        if not s.sample_data:
+            continue
+        sample_ptr = extras_offsets.get(('it_smp', si))
+        if sample_ptr is None:
+            continue   # not in the pool — bin overflow or corrupt source
+
+        # Per-sample loop / sustain encoding (mirrors build_sample_inst_bin_it).
+        if s.flags & IT_SMP_SUS_LOOP:
+            ls = min(s.sus_beg, 65535); le = min(s.sus_end, 65535)
+            sustain_bit = 0x4
+            pingpong = bool(s.flags & IT_SMP_PINGPONG_SUS)
+            has_loop = True
+        elif s.has_loop:
+            ls = min(s.loop_beg, 65535); le = min(s.loop_end, 65535)
+            sustain_bit = 0x0
+            pingpong = bool(s.flags & IT_SMP_PINGPONG)
+            has_loop = True
+        else:
+            ls = 0; le = 0
+            sustain_bit = 0x0
+            pingpong = False
+            has_loop = False
+        loop_mode = (2 if (has_loop and pingpong) else (1 if has_loop else 0)) | sustain_bit
+
+        # Per-sample default volume / pan / auto-vibrato — mirrors the
+        # use_instruments inst-record path so behaviour is identical when the
+        # patch sample matches what the base instrument would have stored.
+        smp_vol  = min(getattr(s, 'vol', 64), 64)
+        dnv      = min(255, round(smp_vol * 255 / 64))
+        smp_dfp  = getattr(s, 'dfp', 0)
+        default_pan = (min(255, max(0, round((smp_dfp & 0x7F) * 255 / 64)))
+                       if (smp_dfp & 0x80) else IXMP_PAN_NO_OVERRIDE)
+        vib_speed_taud = min(255, round(getattr(s, 'av_speed', 0) * 255 / 64))
+        vib_depth_taud = min(255, round(getattr(s, 'av_depth', 0) * 255 / 64))
+        vib_rate_taud  = getattr(s, 'av_sweep', 0) & 0xFF
+        vib_wave_taud  = getattr(s, 'av_wave',  0) & 0x07
+
+        # Find contiguous IT-note ranges where the keyboard points at this sample.
+        run_start = None
+        for n in range(120):
+            if kbd[n] == smp_1based:
+                if run_start is None:
+                    run_start = n
+            else:
+                if run_start is not None:
+                    _emit_patch(patches, run_start, n - 1, sample_ptr, s,
+                                ls, le, loop_mode, default_pan, dnv,
+                                vib_speed_taud, vib_depth_taud, vib_rate_taud, vib_wave_taud)
+                    run_start = None
+        if run_start is not None:
+            _emit_patch(patches, run_start, 119, sample_ptr, s,
+                        ls, le, loop_mode, default_pan, dnv,
+                        vib_speed_taud, vib_depth_taud, vib_rate_taud, vib_wave_taud)
+    return patches
+
+
+def _emit_patch(patches, it_lo, it_hi, sample_ptr, s,
+                ls, le, loop_mode, default_pan, dnv,
+                vib_speed, vib_depth, vib_rate, vib_wave):
+    """Append one patch dict covering IT-note range [it_lo, it_hi] inclusive."""
+    taud_lo = _it_note_to_taud(it_lo, clamp_low=(it_lo == 0))
+    taud_hi = _it_note_to_taud(it_hi, clamp_high=(it_hi == 119))
+    patches.append({
+        'pitch_start':         taud_lo,
+        'pitch_end':           taud_hi,
+        'volume_start':        0,
+        'volume_end':          63,
+        'sample_ptr':          sample_ptr,
+        'sample_length':       min(s.length, 65535),
+        'play_start':          0,
+        'loop_start':          ls,
+        'loop_end':            le,
+        'sampling_rate':       min(getattr(s, 'c5_speed', 8363), 65535),
+        'sample_detune':       0,
+        'loop_mode':           loop_mode,
+        'default_pan':         default_pan,
+        'default_note_volume': dnv,
+        'vibrato_speed':       vib_speed,
+        'vibrato_sweep':       0,                  # IT-side; FT2 sweep stays 0
+        'vibrato_depth':       vib_depth,
+        'vibrato_rate':        vib_rate,
+        'vibrato_waveform':    vib_wave,
+    })
+
+
 # ── Sample / instrument bin (same as s3m2taud) ────────────────────────────────
 
 def build_sample_inst_bin_it(samples_or_proxy: list,
@@ -1190,13 +1322,29 @@ def build_sample_inst_bin_it(samples_or_proxy: list,
     sample_bin = bytearray(SAMPLEBIN_SIZE)
     offsets    = {}
     pos        = 0
+    # IT use_instruments mode points many Taud instrument slots at the same
+    # underlying sample object (e.g. seven "ChipBass.*" instruments all play
+    # "ChipBass.looped"). Write each distinct sample's PCM into the pool once and
+    # let every referencing slot share the offset, rather than emitting one
+    # identical copy per slot. `pool_order` records the distinct samples in
+    # ascending-offset order — the order taut.js's sample viewer expects SNam to
+    # follow (it dedupes instrument records by (ptr,len), sorts by ptr, and
+    # matches SNam[i+1] positionally — see taut.js buildSampleIndex).
+    written    = {}     # id(sample) -> pool offset already written
+    pool_order = []     # distinct sample objects, in pool (ascending-offset) order
     for idx, s in pcm_list:
+        shared = written.get(id(s))
+        if shared is not None:
+            offsets[idx] = shared
+            continue
         n = min(len(s.sample_data), SAMPLEBIN_SIZE - pos)
         if n <= 0:
             vprint(f"  warning: sample bin full, dropping '{s.name}'")
             offsets[idx] = 0; s.length = 0; continue
         sample_bin[pos:pos+n] = s.sample_data[:n]
         offsets[idx] = pos
+        written[id(s)] = pos
+        pool_order.append(s)
         if n < len(s.sample_data):
             vprint(f"  warning: '{s.name}' truncated {len(s.sample_data)} → {n}")
             s.length = n
@@ -1384,7 +1532,7 @@ def build_sample_inst_bin_it(samples_or_proxy: list,
 
         vprint(f"  instrument[{taud_idx}] '{s.name}' ptr:{ptr} c5spd:{s.c5_speed}")
 
-    return bytes(sample_bin) + bytes(inst_bin), offsets, ratio
+    return bytes(sample_bin) + bytes(inst_bin), offsets, ratio, pool_order
 
 
 # ── Pattern builder ───────────────────────────────────────────────────────────
@@ -1805,6 +1953,10 @@ def assemble_taud(h: ITHeader, samples: list, instruments: list,
     # Pattern cells carry IT instrument numbers; for use_instruments mode, those
     # are instrument indices; we remap to samples below.
     # Taud only knows "instrument" slots (1-based, 8-bit). We lay samples in order.
+    # Map IT sample (0-based) → IXMP patch dict template used when building the
+    # per-instrument patch list. Populated by the use_instruments branch below.
+    it_sample_patch_meta = {}
+
     if h.use_instruments:
         # Build a proxy sample list where Taud inst slot = IT inst index,
         # resolved to the canonical sample. Slot 0 unused.
@@ -1899,16 +2051,60 @@ def assemble_taud(h: ITHeader, samples: list, instruments: list,
                 'dct':        inst.dct,
                 'dca':        inst.dca,
             }
-        sampleinst_raw, _, sample_ratio = build_sample_inst_bin_it(proxy, instr_data_by_slot)
+        # ── Ixmp: pool keyboard-referenced extra samples beyond slot 255 ───────
+        # IT instruments can map different IT notes to different samples via the
+        # keyboard table (IMPI+0x44). The canonical sample is already in the proxy
+        # at the instrument's Taud slot; extras (any other sample referenced in
+        # the keyboard) get appended past index 256 so build_sample_inst_bin_it
+        # pools them (its inst-record loop skips i >= 256 — see the same file).
+        # We then look up their bin offsets via the returned offsets dict and
+        # emit one Ixmp patch per (sample, contiguous-note-range) pair.
+        extras_keys = []   # ordered list of ('it_smp', si) — index into the proxy is 256 + position
+        for ii, inst in enumerate(instruments):
+            if inst is None: continue
+            canonical = inst.canonical_sample
+            kbd = getattr(inst, 'keyboard', None) or []
+            for kb_smp in kbd:
+                if kb_smp == 0 or kb_smp == canonical:
+                    continue
+                si = kb_smp - 1
+                if 0 <= si < len(samples) and samples[si] is not None and samples[si].sample_data:
+                    key = ('it_smp', si)
+                    if key not in extras_keys:
+                        extras_keys.append(key)
+        extras_base = len(proxy)
+        for key in extras_keys:
+            proxy.append(samples[key[1]])
+
+        sampleinst_raw, bin_offsets, sample_ratio, pool_order = build_sample_inst_bin_it(proxy, instr_data_by_slot)
+        # Map ('it_smp', si) → sample-bin offset.
+        extras_offsets = {key: bin_offsets.get(extras_base + j, 0)
+                          for j, key in enumerate(extras_keys)}
+        # Also include each canonical sample at its taud-slot offset so the patch
+        # builder can reuse them when an instrument's keyboard cell references the
+        # canonical sample at a non-canonical note range.
+        for ii, inst in enumerate(instruments):
+            if inst is None: continue
+            taud_slot = ii + 1
+            if taud_slot >= 256: continue
+            canon = inst.canonical_sample
+            if canon == 0: continue
+            si = canon - 1
+            if 0 <= si < len(samples) and samples[si] is not None and ('it_smp', si) not in extras_offsets:
+                # Look up the pool offset for the canonical via the proxy slot.
+                if taud_slot in bin_offsets:
+                    extras_offsets[('it_smp', si)] = bin_offsets[taud_slot]
     else:
-        # Samples referenced directly; proxy is samples list (0-based, slot 0 unused)
+        # Samples referenced directly; proxy is samples list (0-based, slot 0 unused).
+        # No instruments in the file → no multi-sample mapping → no Ixmp patches.
         proxy = [None] + list(samples)
         inst_vols = {
             i+1: min(s.vol, 0x3F)
             for i, s in enumerate(samples)
             if s is not None
         }
-        sampleinst_raw, _, sample_ratio = build_sample_inst_bin_it(proxy)
+        sampleinst_raw, bin_offsets, sample_ratio, pool_order = build_sample_inst_bin_it(proxy)
+        extras_offsets = {}
 
     assert len(sampleinst_raw) == SAMPLEINST_SIZE
 
@@ -1961,12 +2157,36 @@ def assemble_taud(h: ITHeader, samples: list, instruments: list,
     if with_project_data:
         inst_names = [''] + [(inst.name if inst is not None else '')
                              for inst in instruments[:255]]
-        smp_names  = [''] + [(s.name if s is not None else '')
-                             for s in samples[:255]]
+        # SNam mirrors the deduplicated sample pool: one entry per distinct
+        # sample, in pool order, named after the sample itself. taut.js dedupes
+        # instrument records by (ptr,len), sorts ascending by ptr, and matches
+        # SNam[i+1] positionally to that list, so this ordering labels every
+        # sample correctly and a shared sample (e.g. "ChipBass.looped") appears
+        # exactly once instead of once per referencing instrument slot.
+        smp_names  = [''] + [(getattr(s, 'name', '') or '')
+                             for s in pool_order[:255]]
+
+        # Ixmp patches — only the use_instruments branch maps IT notes to multiple
+        # samples; the sample-mode branch has nothing to emit because there's no
+        # keyboard table on a raw IT sample.
+        ixmp_patches = {}
+        if h.use_instruments and extras_offsets:
+            for ii, inst in enumerate(instruments):
+                if inst is None: continue
+                taud_slot = ii + 1
+                if taud_slot >= 256: continue
+                patches = _build_it_ixmp_patches(inst, samples, extras_offsets)
+                if patches:
+                    ixmp_patches[taud_slot] = patches
+            if ixmp_patches:
+                vprint(f"  ixmp: {sum(len(p) for p in ixmp_patches.values())} "
+                       f"patches across {len(ixmp_patches)} instruments")
+
         proj_data = build_project_data(
             project_name=h.title,
             instrument_names=inst_names,
             sample_names=smp_names,
+            ixmp_patches=ixmp_patches or None,
         )
         if proj_data:
             proj_off = cur_off

s3m2taud.py

@@ -138,7 +138,11 @@ def parse_instruments(data: bytes, h: S3MHeader) -> list:
             continue
         inst = S3MInstrument()
         inst.itype    = data[ptr]
-        inst.filename = data[ptr+1:ptr+13].rstrip(b'\x00').decode('latin-1', errors='replace')
+        # 12-byte DOS filename field; null-terminated with possible trailing
+        # garbage after the terminator (ST3 doesn't zero the tail). Truncate at
+        # the first null. This field carries the per-sample short name (e.g.
+        # 'HIT1') as distinct from the 28-byte title at 0x30.
+        inst.filename = data[ptr+1:ptr+13].split(b'\x00', 1)[0].decode('latin-1', errors='replace')
         # memseg: 3 bytes at offsets 0x0D,0x0E,0x0F — high byte first (quirk)
         memseg_hi  = data[ptr + 0x0D]
         memseg_lo  = struct.unpack_from('<H', data, ptr + 0x0E)[0]
@@ -939,17 +943,21 @@ def assemble_taud(h: S3MHeader, instruments: list, patterns: list,
         cur_off += len(pat_comp) + len(cue_comp)
 
     # ── Project Data (optional) ──────────────────────────────────────────────
-    # S3M instruments and samples share the same slot space, so the names go
-    # into both INam and SNam (1-based; slot 0 empty).
+    # S3M instruments and samples share the same slot space, but carry two
+    # distinct name fields: the 28-byte title (inst.name → INam) and the
+    # 12-byte DOS filename (inst.filename → SNam). e.g. WHEN.s3m instrument #1
+    # is titled "(c) Purple Motion / 1994" with sample name 'HIT1'.
     proj_data = b''
     proj_off  = 0
     if with_project_data:
-        names = [''] + [(inst.name if inst is not None else '')
-                        for inst in instruments[:255]]
+        inst_names   = [''] + [(inst.name     if inst is not None else '')
+                               for inst in instruments[:255]]
+        sample_names = [''] + [(inst.filename if inst is not None else '')
+                               for inst in instruments[:255]]
         proj_data = build_project_data(
             project_name=h.title,
-            instrument_names=names,
-            sample_names=names,
+            instrument_names=inst_names,
+            sample_names=sample_names,
         )
         if proj_data:
             proj_off = cur_off

taud_common.py

@@ -543,13 +543,93 @@ def _name_table_blob(names) -> bytes:
     return b'\x1E'.join((n or '').encode('utf-8', 'replace') for n in names[:end])
 
 
+# ── Ixmp encoder (terranmon.txt §Project Data → Ixmp) ───────────────────────
+
+# Per-patch byte layout. Field offsets must match AudioJSR223Delegate.uploadInstrumentPatches
+# (Kotlin parser) and terranmon.txt "Ixmp. Instrument extra samples".
+IXMP_PATCH_SIZE     = 31
+IXMP_PAN_NO_OVERRIDE = 0xFF
+IXMP_DNV_NO_OVERRIDE = 0
+IXMP_VIBWAVE_NO_OVERRIDE = 0xFF
+
+
+def encode_ixmp_patch(p: dict) -> bytes:
+    """Encode a single patch dict into 31 bytes.
+
+    Expected keys (numeric values; defaults are applied for missing optional fields):
+        pitch_start, pitch_end        : Taud 4096-TET noteVal (Uint16)
+        volume_start, volume_end      : 0..63 (Uint8)
+        sample_ptr                    : Uint32 (sample bin offset)
+        sample_length                 : Uint16
+        play_start, loop_start, loop_end : Uint16
+        sampling_rate                 : Uint16 (same encoding as base inst byte 6-7)
+        sample_detune                 : Int16, signed 4096-TET (default 0)
+        loop_mode                     : Uint8 (default 0)
+        default_pan                   : Uint8, 0xFF = no override (default 0xFF)
+        default_note_volume           : Uint8 IT-scaled (0 = no override, default 0)
+        vibrato_speed/sweep/depth/rate: Uint8 (default 0)
+        vibrato_waveform              : Uint8 (0..7 or 0xFF for no override, default 0xFF)
+    """
+    pitch_start = max(0, min(0xFFFF, int(p['pitch_start'])))
+    pitch_end   = max(0, min(0xFFFF, int(p['pitch_end'])))
+    vol_start   = max(0, min(63,     int(p.get('volume_start', 0))))
+    vol_end     = max(0, min(63,     int(p.get('volume_end', 63))))
+    sample_ptr  = int(p['sample_ptr']) & 0xFFFFFFFF
+    sample_len  = max(0, min(0xFFFF, int(p['sample_length'])))
+    play_start  = max(0, min(0xFFFF, int(p.get('play_start', 0))))
+    loop_start  = max(0, min(0xFFFF, int(p.get('loop_start', 0))))
+    loop_end    = max(0, min(0xFFFF, int(p.get('loop_end',   0))))
+    rate        = max(0, min(0xFFFF, int(p.get('sampling_rate', 0))))
+    detune      = max(-0x8000, min(0x7FFF, int(p.get('sample_detune', 0))))
+    return struct.pack(
+        '<BHHBBIHHHHHhBBBBBBBB',
+        1,                                       # patch version
+        pitch_start, pitch_end,
+        vol_start,   vol_end,
+        sample_ptr,
+        sample_len,
+        play_start, loop_start, loop_end,
+        rate,
+        detune,
+        int(p.get('loop_mode', 0))            & 0x07,
+        int(p.get('default_pan', IXMP_PAN_NO_OVERRIDE))     & 0xFF,
+        int(p.get('default_note_volume', IXMP_DNV_NO_OVERRIDE)) & 0xFF,
+        int(p.get('vibrato_speed', 0))        & 0xFF,
+        int(p.get('vibrato_sweep', 0))        & 0xFF,
+        int(p.get('vibrato_depth', 0))        & 0xFF,
+        int(p.get('vibrato_rate',  0))        & 0xFF,
+        int(p.get('vibrato_waveform', IXMP_VIBWAVE_NO_OVERRIDE)) & 0xFF,
+    )
+
+
+def encode_ixmp_payload(patches_by_inst: dict) -> bytes:
+    """Encode a dict {instrument_id: [patch_dict, ...]} as one Ixmp section payload
+    (the body that follows the FourCC + length header). Instruments are written in
+    ascending id order. Overlapping pitch+volume rectangles within one instrument
+    are INVALID per spec and the caller is responsible for keeping them disjoint."""
+    if not patches_by_inst:
+        return b''
+    out = bytearray()
+    for inst_id in sorted(patches_by_inst):
+        patches = patches_by_inst[inst_id]
+        if not patches:
+            continue
+        out.append(int(inst_id) & 0xFF)
+        cnt = len(patches)
+        out += bytes([cnt & 0xFF, (cnt >> 8) & 0xFF, (cnt >> 16) & 0xFF])  # Uint24 LE
+        for patch in patches:
+            out += encode_ixmp_patch(patch)
+    return bytes(out)
+
+
 def build_project_data(*, project_name: str = '',
                        author: str = '',
                        copyright_str: str = '',
                        sample_names=None,
                        instrument_names=None,
                        pattern_names=None,
-                       song_metadata=None) -> bytes:
+                       song_metadata=None,
+                       ixmp_patches=None) -> bytes:
     """Build the optional PROJECT DATA section payload.
 
     Returns the full block (8-byte magic + 8 reserved bytes + concatenated
@@ -604,6 +684,9 @@ def build_project_data(*, project_name: str = '',
             smet += payload
         add(b'sMet', bytes(smet))
 
+    if ixmp_patches:
+        add(b'Ixmp', encode_ixmp_payload(ixmp_patches))
+
     if not sections:
         return b''
 

terranmon.txt

@@ -49,7 +49,13 @@ MMIO
 0..31 RO: Raw Keyboard Buffer read. Won't shift the key buffer
 32..33 RO: Mouse X pos
 34..35 RO: Mouse Y pos
-36 RO: Mouse down? (1 for TRUE, 0 for FALSE)
+36 RO: Mouse down?
+    bit 0: left
+    bit 1: right
+    bit 2: middle
+
+    bit 6: wheel up
+    bit 7: wheel down
 37 RW: Read/Write single key input. Key buffer will be shifted. Manual writing is
     usually unnecessary as such action must be automatically managed via LibGDX
     input processing.
@@ -2403,6 +2409,10 @@ TODO:
     [x] expose song table on UI (test with `insaniq2.taud`)
     [x] 0x0000 - no-op; 0x0001 - key-off; 0x0002 - note-cut 0x0010..0x001F - INT0..INTF
         [ ] establish hooks for the interrupts
+    [x] Samples and Instruments view (viewer on taut.js; editor on separate .js)
+        follow the ImpulseTracker design first, then improve from there
+    [?] Sample desig for instrument in Pitch-Volume space (one rectangle = one patch). If undefined, the old sample pointer falls thru
+        [ ] Needs .it and .xm test file to complete it2taud and xm2taud
 
 TODO - list of demo songs that MUST ship with Microtone:
     * 4THSYM (rename to Fourth Symmetriad) — excellent piece for demonstrating NNAs and filter envelopes
@@ -2461,7 +2471,7 @@ Audio Adapter MMIO
     Write 16 to initialise the MP2 context (call this before the decoding of NEW music)
     Write 1 to decode the frame as MP2
 
-    Calling with more than one bit set will result in UNDEFINED BEHAVIOUR
+    Calling with more than one bit set will result in UNDEFINED BEHAVIOUR — except for the flag 0x11, in which the hardware must initialise then immediately start decoding.
 
 41 RO: MP2 Decoder Status
     Non-zero value indicates the decoder is busy. Different value may indicate different decoder status.
@@ -2611,6 +2621,17 @@ This is a file format for Taud tracker data. Taud can be extended with Microtone
 
 Endianness: Little
 
+# Conformance language
+(RFC 2119+8174)
+- **MUST** / **MUST NOT** / **REQUIRED** / **SHALL** / **SHALL NOT** — absolute requirements / prohibitions. A conforming implementation **SHALL** observe every such rule; an implementation that violates one is non-conforming.
+- **SHOULD** / **SHOULD NOT** / **RECOMMENDED** / **NOT RECOMMENDED** — strong guidance. An implementation **MAY** deviate in particular circumstances, but the full implications **MUST** be understood and weighed before doing so.
+- **MAY** / **OPTIONAL** — truly optional. Implementations that include the feature and implementations that omit it are equally conforming, and each **MUST** be prepared to interoperate with the other (with reduced functionality where the optional feature is the means of interoperation).
+(IMPLEMENTATION DETAILS)
+- **INVALID.** Blame the encoder; decoder MUST stop decoding with appropriate errors.
+- **UNDEFINED BEHAVIOUR.** Encoder MAY encode it; decoder MAY do whatever it wants to, including spawning a daemon out of your nose.
+- **IGNORED.** Encoder MAY encode it; decoder MUST skip past it.
+- **RESERVED.** Encoder MUST NOT encode it. Decoder MUST skip past it.
+
 # File Structure
 \x1F T S V M a u d
 [HEADER]
@@ -2648,7 +2669,7 @@ Endianness: Little
     Float32 Frequency at the base note. Tracker default is 8363.0. If zero, assume the tracker default
     Uint8   Flags for Global Behaviour (effect symbol '1')
         0b 000 rrr ff
-            ff: tone mode          (0: linear pitch slides, 1: Amiga period slides, 2: linear-frequency slides, 3: reserved)
+            ff: tone mode          (0: linear pitch slides, 1: Amiga period slides, 2: linear-frequency slides, 3: RESERVED)
             rrr: interpolation mode (0: default, 1: none, 2: Amiga 500, 3: Amiga 1200, 4: SNES 4-tap Gaussian, 5: NES DPCM simulation)
     Uint8   Song global volume
         * ImpulseTracker has range of 0..128; multiply by (255/128) then round to int
@@ -2656,7 +2677,7 @@ Endianness: Little
         * ImpulseTracker has range of 0..128; multiply by (255/128) then round to int
     Uint32  Compressed size of PATTERN BIN for this song
     Uint32  Compressed size of CUE SHEET for this song
-    Byte[6] Reserved
+    Byte[6] RESERVED
 
     Taud device can queue up to 2 "playdata" in its buffer, which can be interpreted as a song.
 
@@ -2678,7 +2699,7 @@ Endianness: Little
 Project Data is just a concatenation of blocks identified by their FourCC.
 
     Byte[8] Magic (\x1E T a u d P r J)
-    Byte[8] Reserved
+    Byte[8] RESERVED
     * Repetition of
     Byte[4] Title of the section (fourcc)
     Uint32  Section length
@@ -2729,11 +2750,11 @@ prefixes:
     * Repetition of:
     Uint8   Notation index (starting from zero) used by songs
     Uint32  Size of this notation following this field
-    Uint16  Reserved for flags
+    Uint16  RESERVED for flags
     Uint16  Interval size in 4096-TET lattice (octave = 0x1000, tritave = 0x195C). If you are not using an interval system (which means you are responsible for defining every note expressible), this must be 0.
-    Uint16  Reserved for float32 interval size (should it be in 4096-TET which is inexact or frequency multiplier which is exact but difficult to implement?)
+    Uint16  RESERVED for float32 interval size (should it be in 4096-TET which is inexact or frequency multiplier which is exact but difficult to implement?)
     Uint16  Notes between interval (or octave) MINUS ONE; 12-TET will have value 11
-    Byte[8] Reserved
+    Byte[8] RESERVED
     Byte[*]     Name, null terminated. Encoding: UTF-8
     Byte[*]     Notation table. 0xFF-separated and null-terminated. Encoding: Taud charset
     Uint16[*]  Frequency table. Size of the table is defined by "Notes between interval MINUS ONE". This is a lookup table of relative pitch offsets (against the base tuning note) in 4096-TET space. Index zero of this table will be 0x0 if you read the spec right
@@ -2754,6 +2775,45 @@ prefixes:
     Uint8   Version (Ascii 'a')
     Bytes   Notation definitions (see above)
 
+* Ixmp. Instrument extra samples
+    * Repetition of:
+    Uint8   Instrument ID
+    Uint24  Count of patches
+        ** Repetition of:
+        Uint8  Patch definition version (always 1)
+        Uint16 Pitch start                 ; Taud 4096-TET noteVal (same scale as pattern-cell note)
+        Uint16 Pitch end (inclusive)
+        Uint8  Volume start                ; 0..63
+        Uint8  Volume end (inclusive)      ; 0..63
+            - Above four parameters define a rectangle over the Pitch-Volume space. See Notes 4 and 5
+        Uint32 Sample pointer
+        Uint16 Sample length
+        Uint16 Play Start (usually 0 but not always)
+        Uint16 Loop Start (can be smaller than Play Start)
+        Uint16 Loop End
+        Uint16 samplingRate                ; per-sample C-5 speed; same encoding as base instrument byte 6-7
+        Int16  sampleDetune                ; per-sample fine detune in signed 4096-TET units (XM finetune; IT samples leave 0)
+        Uint8  loopMode                    ; same encoding as base instrument byte 14 (bits 0-1 = mode, bit 2 = sustain loop)
+        Uint8  defaultPan                  ; per-sample default pan (0..255; 0x80 = centre); 0xFF = "no override"
+        Uint8  defaultNoteVolume           ; per-sample default note volume (0..255 scaled from IT 0..64); 0 = "no override"
+        Uint8  vibratoSpeed                ; per-sample auto-vibrato (mirrors base inst byte 175)
+        Uint8  vibratoSweep                ; per-sample auto-vibrato (mirrors base inst byte 176)
+        Uint8  vibratoDepth                ; per-sample auto-vibrato (mirrors base inst byte 187)
+        Uint8  vibratoRate                 ; per-sample auto-vibrato (mirrors base inst byte 188)
+        Uint8  vibratoWaveform             ; bits 0-2 only (mirrors instrumentFlag bits 2-4); 0xFF = "no override"
+
+    Notes:
+    0. this extension is made to support IT/XM instrument spec as well as partial compatibility to SF2 (Soundfont format two)
+    1. Envelopes (vol/pan/pf), fadeout, NNA / DCT / DCA, pitch-pan, filter, IGV and any other "instrument-scope" parameters all follow the base instrument definition. Only sample-scope parameters (the patch fields listed above) override.
+    2. overlapping regions are considered INVALID
+    3. multiple Ixmp blocks pointing the same instrument are considered INVALID
+    4. IT and XM does not define volumes. Keep the Volume rectangle at 0..63 — the engine clamps to that range when matching.
+    5. SF2 does define volumes (because MIDI). Convert it using `round(velocity * (63/127))`
+        On import, `initialAttenuation`, filters and ADSR shall be ignored
+    6. Patch selection at trigger time walks the patch list in order; the first patch whose rectangle contains the trigger's (noteVal, rowVolume) wins. When no patch matches, the base instrument's sample fields are used unchanged.
+    7. Sentinel values listed above ("no override") let a patch defer to the base instrument for a given field — used by converters that don't carry per-sample data for one of the dimensions (e.g. SF2 ignoring per-sample pan).
+    8. Total per-patch payload is 31 bytes.
+
 --------------------------------------------------------------------------------
 
 **S3M (ScreamTracker 3) to Taud conversion notes**

tsvm_core/src/net/torvald/tsvm/AudioJSR223Delegate.kt

@@ -140,6 +140,47 @@ class AudioJSR223Delegate(private val vm: VM) {
     fun getVoiceActive(playhead: Int, voice: Int): Boolean =
         getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19))?.active == true
 
+    /** Active-note counts per instrument id (index 0..255): how many notes are sounding *right
+     *  now* for each instrument, counting ~~BOTH~~ the live foreground voices ~~and the NNA background
+     *  ghosts in the mixer-private pool~~~. Lets visualisers colour by polyphony. The ghost pool is
+     *  mutated by the render thread, so it is read defensively by index and any transient
+     *  inconsistency is tolerated (a single best-effort frame). */
+    fun getActiveNoteCounts(playhead: Int): IntArray {
+        val counts = IntArray(256)
+        val ts = getPlayhead(playhead)?.trackerState ?: return counts
+        for (v in ts.voices) {
+            if (v.active) counts[v.instrumentId and 0xFF]++
+        }
+        // disabling NNA for now
+        /*try {
+            val bg = ts.backgroundVoices
+            for (i in 0 until bg.size) {
+                val v = bg.getOrNull(i) ?: continue
+                if (v.active) counts[v.instrumentId and 0xFF]++
+            }
+        } catch (_: Exception) { /* ghost pool mutated mid-read — counts are best-effort */ }
+        */
+        return counts
+    }
+
+    /** Funk-repeat (S$Fx) speed currently driving the voice: 0 = off, otherwise the per-tick
+     *  accumulator increment. A non-zero value on an active voice means the voice is live-inverting
+     *  its instrument's loop region right now — visualisers can use this to gate the funk overlay. */
+    fun getVoiceFunkSpeed(playhead: Int, voice: Int): Int {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return 0
+        if (!v.active) return 0
+        return v.funkSpeed
+    }
+
+    /** Snapshot of an instrument's funk-repeat XOR mask (one bit per loop-region byte; a set bit
+     *  flips that byte by 0xFF during playback). Returns the mask bytes as ints (0..255), or an
+     *  empty array when the instrument has never been funk-repeated. The render thread mutates the
+     *  live mask, so this returns a copy — the caller gets a stable single-frame view. */
+    fun getInstrumentFunkMask(slot: Int): IntArray {
+        val mask = getFirstSnd()?.instruments?.get(slot and 0xFF)?.funkMask ?: return IntArray(0)
+        return IntArray(mask.size) { mask[it].toInt() and 0xFF }
+    }
+
     /** Live noteVal (0..65535, 4096-TET) of the foreground voice — the value the mixer is using
      *  *right now* including any in-flight vibrato / arpeggio / portamento delta. Returns 0 for
      *  inactive voices. */
@@ -156,6 +197,54 @@ class AudioJSR223Delegate(private val vm: VM) {
         return v.instrumentId and 0xFF
     }
 
+    /** Current sample-frame playback position (fractional double) of the voice. Returns -1.0
+     *  when the voice is inactive so visualisers can distinguish "no cursor" from "cursor at 0". */
+    fun getVoiceSamplePos(playhead: Int, voice: Int): Double {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return -1.0
+        if (!v.active) return -1.0
+        return v.samplePos
+    }
+
+    /** Volume-envelope segment index — i.e. the node the voice is currently moving *away* from
+     *  (the next node it will hit is index + 1). Returns -1 when inactive. */
+    fun getVoiceEnvVolIndex(playhead: Int, voice: Int): Int {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return -1
+        if (!v.active) return -1
+        return v.envIndex
+    }
+    /** Seconds elapsed *into* the current volume-envelope segment (0 ≤ t < segment.offset). */
+    fun getVoiceEnvVolTime(playhead: Int, voice: Int): Double {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return 0.0
+        if (!v.active) return 0.0
+        return v.envTimeSec
+    }
+
+    /** Pan-envelope segment index — see [getVoiceEnvVolIndex]. */
+    fun getVoiceEnvPanIndex(playhead: Int, voice: Int): Int {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return -1
+        if (!v.active) return -1
+        return v.envPanIndex
+    }
+    /** Seconds elapsed into the current pan-envelope segment. */
+    fun getVoiceEnvPanTime(playhead: Int, voice: Int): Double {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return 0.0
+        if (!v.active) return 0.0
+        return v.envPanTimeSec
+    }
+
+    /** Pitch/filter-envelope segment index — see [getVoiceEnvVolIndex]. */
+    fun getVoiceEnvPitchIndex(playhead: Int, voice: Int): Int {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return -1
+        if (!v.active) return -1
+        return v.envPfIndex
+    }
+    /** Seconds elapsed into the current pitch/filter-envelope segment. */
+    fun getVoiceEnvPitchTime(playhead: Int, voice: Int): Double {
+        val v = getPlayhead(playhead)?.trackerState?.voices?.getOrNull(voice.coerceIn(0, 19)) ?: return 0.0
+        if (!v.active) return 0.0
+        return v.envPfTimeSec
+    }
+
     /** Set the starting row for the next play call, resetting per-row timing and silencing active voices. */
     fun setTrackerRow(playhead: Int, row: Int) {
         getPlayhead(playhead)?.trackerState?.let { ts ->
@@ -176,6 +265,64 @@ class AudioJSR223Delegate(private val vm: VM) {
         }
     }
 
+    /** Upload an Ixmp "extra samples" block for instrument [slot] (0-255). The payload is
+     *  a flat byte array of `count × 31` patch records — see terranmon.txt "Ixmp. Instrument
+     *  extra samples" for the on-wire field layout. Passing an empty array clears any
+     *  previously-installed patches on this instrument. */
+    fun uploadInstrumentPatches(slot: Int, bytes: IntArray) {
+        val inst = getFirstSnd()?.instruments?.get(slot and 0xFF) ?: return
+        val recordSize = 31
+        if (bytes.isEmpty() || bytes.size < recordSize) {
+            inst.extraPatches = null
+            return
+        }
+        val count = bytes.size / recordSize
+        if (count == 0) { inst.extraPatches = null; return }
+        fun u8 (o: Int) = bytes[o] and 0xFF
+        fun u16(o: Int) = (bytes[o] and 0xFF) or ((bytes[o + 1] and 0xFF) shl 8)
+        fun s16(o: Int): Int { val v = u16(o); return if (v >= 0x8000) v - 0x10000 else v }
+        fun u32(o: Int) =  (bytes[o]     and 0xFF)        or
+                          ((bytes[o + 1] and 0xFF) shl 8) or
+                          ((bytes[o + 2] and 0xFF) shl 16) or
+                          ((bytes[o + 3] and 0xFF) shl 24)
+        val patches = Array(count) { i ->
+            val o = i * recordSize
+            // Patch version byte at offset 0 is parsed but only version 1 is recognised;
+            // a future version bump would gate alternate field layouts here.
+            AudioAdapter.TaudInstPatch(
+                pitchStart        = u16(o + 1),
+                pitchEnd          = u16(o + 3),
+                volumeStart       = u8 (o + 5),
+                volumeEnd         = u8 (o + 6),
+                samplePtr         = u32(o + 7),
+                sampleLength      = u16(o + 11),
+                playStart         = u16(o + 13),
+                loopStart         = u16(o + 15),
+                loopEnd           = u16(o + 17),
+                samplingRate      = u16(o + 19),
+                sampleDetune      = s16(o + 21),
+                loopMode          = u8 (o + 23),
+                defaultPan        = u8 (o + 24),
+                defaultNoteVolume = u8 (o + 25),
+                vibratoSpeed      = u8 (o + 26),
+                vibratoSweep      = u8 (o + 27),
+                vibratoDepth      = u8 (o + 28),
+                vibratoRate       = u8 (o + 29),
+                vibratoWaveform   = u8 (o + 30)
+            )
+        }
+        inst.extraPatches = patches
+    }
+
+    /** Number of Ixmp patches currently installed on instrument [slot], or 0 if none. */
+    fun getInstrumentPatchCount(slot: Int): Int =
+        getFirstSnd()?.instruments?.get(slot and 0xFF)?.extraPatches?.size ?: 0
+
+    /** Clear any Ixmp patches previously uploaded to instrument [slot]. */
+    fun clearInstrumentPatches(slot: Int) {
+        getFirstSnd()?.instruments?.get(slot and 0xFF)?.extraPatches = null
+    }
+
     /** Upload 512 bytes (64 rows × 8 bytes) defining pattern `slot` (0-4094). */
     fun uploadPattern(slot: Int, bytes: IntArray) {
         getFirstSnd()?.playdata?.get(slot and 0xFFF)?.let { pat ->
@@ -226,6 +373,13 @@ class AudioJSR223Delegate(private val vm: VM) {
         getPlayhead(playhead)?.resetParams()
     }
 
+    /** Clear funk-repeat (S$Fx) state (per-voice run-state + per-instrument loop-inversion masks)
+     *  without disturbing tempo / volume / position. Call on a fresh play-from-start so stale funk
+     *  state from a prior playback doesn't bleed into the replay. */
+    fun resetFunkState(playhead: Int) {
+        getPlayhead(playhead)?.resetFunkState()
+    }
+
     fun purgeQueue(playhead: Int) {
         getPlayhead(playhead)?.purgeQueue()
     }

tsvm_core/src/net/torvald/tsvm/GraphicsJSR223Delegate.kt

@@ -149,17 +149,41 @@ class GraphicsJSR223Delegate(private val vm: VM) {
         }
     }
 
-    fun plotRect(x: Int, y: Int, w: Int, h: Int, colour: Int) {
+    fun plotRect(x: Int, y: Int, w: Int, h: Int, colour: Int) = plotRect(x, y, w, h, colour, 0)
+
+    /**
+     * @param eff plot effect. 0 — solid, 1 — 50% checkerboard, 2 — 25% checkerboard
+     */
+    fun plotRect(x: Int, y: Int, w: Int, h: Int, colour: Int, eff: Int) {
         val xs = min(x, x+w).toLong()
         val xe = max(x, x+w).toLong()
         val ys = min(y, y+h).toLong()
         val ye = max(y, y+h).toLong()
 
         getFirstGPU()?.let {
-            for (py in ys until ye) {
-                for (px in xs until xe) {
-                    if (px in 0 until it.config.width && py in 0 until it.config.height) {
-                        it.poke(py * it.config.width + px, colour.toByte())
+            val forYcond = if (eff == 2) (ys until ye step 2) else (ys until ye)
+
+            for (py in forYcond) {
+                when (eff) {
+                    0 -> for (px in xs until xe) {
+                        if (px in 0 until it.config.width && py in 0 until it.config.height) {
+                            it.poke(py * it.config.width + px, colour.toByte())
+                        }
+                    }
+                    1 -> {
+                        val parity = py % 2
+                        val forXcond = if (parity == 0L) (xs until xe step 2) else ((xs+1) until xe step 2)
+
+                        for (px in forXcond) {
+                            if (px in 0 until it.config.width && py in 0 until it.config.height) {
+                                it.poke(py * it.config.width + px, colour.toByte())
+                            }
+                        }
+                    }
+                    2 -> for (px in xs until xe step 2) {
+                        if (px in 0 until it.config.width && py in 0 until it.config.height) {
+                            it.poke(py * it.config.width + px, colour.toByte())
+                        }
                     }
                 }
             }
@@ -167,17 +191,41 @@ class GraphicsJSR223Delegate(private val vm: VM) {
         }
     }
 
-    fun plotRect2(x: Int, y: Int, w: Int, h: Int, colour: Int) {
+    fun plotRect2(x: Int, y: Int, w: Int, h: Int, colour: Int) = plotRect2(x, y, w, h, colour, 0)
+
+    /**
+     * @param eff plot effect. 0 — solid, 1 — 50% checkerboard, 2 — 25% checkerboard
+     */
+    fun plotRect2(x: Int, y: Int, w: Int, h: Int, colour: Int, eff: Int) {
         val xs = min(x, x+w).toLong()
         val xe = max(x, x+w).toLong()
         val ys = min(y, y+h).toLong()
         val ye = max(y, y+h).toLong()
 
         getFirstGPU()?.let {
-            for (py in ys until ye) {
-                for (px in xs until xe) {
-                    if (px in 0 until it.config.width && py in 0 until it.config.height) {
-                        it.poke(262144 + py * it.config.width + px, colour.toByte())
+            val forYcond = if (eff == 2) (ys until ye step 2) else (ys until ye)
+
+            for (py in forYcond) {
+                when (eff) {
+                    0 -> for (px in xs until xe) {
+                        if (px in 0 until it.config.width && py in 0 until it.config.height) {
+                            it.poke(262144 + py * it.config.width + px, colour.toByte())
+                        }
+                    }
+                    1 -> {
+                        val parity = py % 2
+                        val forXcond = if (parity == 0L) (xs until xe step 2) else ((xs+1) until xe step 2)
+
+                        for (px in forXcond) {
+                            if (px in 0 until it.config.width && py in 0 until it.config.height) {
+                                it.poke(py * it.config.width + px, colour.toByte())
+                            }
+                        }
+                    }
+                    2 -> for (px in xs until xe step 2) {
+                        if (px in 0 until it.config.width && py in 0 until it.config.height) {
+                            it.poke(py * it.config.width + px, colour.toByte())
+                        }
                     }
                 }
             }
@@ -195,7 +243,12 @@ class GraphicsJSR223Delegate(private val vm: VM) {
         }
     }
 
-    fun plotRectMode1(x: Int, y: Int, w: Int, h: Int, colour: Int, plane: Int) {
+    fun plotRectMode1(x: Int, y: Int, w: Int, h: Int, colour: Int, plane: Int) = plotRectMode1(x, y, w, h, colour, plane, 0)
+
+    /**
+     * @param eff plot effect. 0 — solid, 1 — 50% checkerboard, 2 — 25% checkerboard
+     */
+    fun plotRectMode1(x: Int, y: Int, w: Int, h: Int, colour: Int, plane: Int, eff: Int) {
         val xs = min(x, x+w).toLong()
         val xe = max(x, x+w).toLong()
         val ys = min(y, y+h).toLong()
@@ -205,10 +258,29 @@ class GraphicsJSR223Delegate(private val vm: VM) {
             val halfW = it.config.width / 2
             val halfH = it.config.height / 2
             val planesize = it.config.width * it.config.height / 4
-            for (py in ys until ye) {
-                for (px in xs until xe) {
-                    if (px in 0 until halfW && py in 0 until halfH) {
-                        it.poke(py * halfW + px + planesize * plane, colour.toByte())
+            val forYcond = if (eff == 2) (ys until ye step 2) else (ys until ye)
+
+            for (py in forYcond) {
+                when (eff) {
+                    0 -> for (px in xs until xe) {
+                        if (px in 0 until halfW && py in 0 until halfH) {
+                            it.poke(py * halfW + px + planesize * plane, colour.toByte())
+                        }
+                    }
+                    1 -> {
+                        val parity = py % 2
+                        val forXcond = if (parity == 0L) (xs until xe step 2) else ((xs+1) until xe step 2)
+
+                        for (px in forXcond) {
+                            if (px in 0 until halfW && py in 0 until halfH) {
+                                it.poke(py * halfW + px + planesize * plane, colour.toByte())
+                            }
+                        }
+                    }
+                    2 -> for (px in xs until xe step 2) {
+                        if (px in 0 until halfW && py in 0 until halfH) {
+                            it.poke(py * halfW + px + planesize * plane, colour.toByte())
+                        }
                     }
                 }
             }

tsvm_core/src/net/torvald/tsvm/peripheral/AudioAdapter.kt

@@ -1357,9 +1357,55 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         const val OP_Z = 0x23
     }
 
-    private fun computePlaybackRate(inst: TaudInst, noteVal: Int): Double =
-        inst.samplingRate.toDouble() / SAMPLING_RATE *
-        2.0.pow((noteVal - MIDDLE_C + inst.sampleDetuneSigned) / 4096.0)
+    // Active-sample-aware playback rate. Reads from the Voice's snapshotted sample
+    // view (set by [applyActiveSample]) so Ixmp-overlaid instruments use the patch's
+    // samplingRate / detune, not the base inst's.
+    private fun computePlaybackRate(voice: Voice, noteVal: Int): Double =
+        voice.activeSamplingRate.toDouble() / SAMPLING_RATE *
+        2.0.pow((noteVal - MIDDLE_C + voice.activeSampleDetune) / 4096.0)
+
+    /**
+     * Snapshot the sample-scope state for [voice] from either the base instrument
+     * or a resolved Ixmp patch. Called by every fresh trigger; the per-tick read
+     * sites then go through voice.active* instead of inst.* so multi-sample
+     * (IT/XM keyboard table) instruments select the right sample per note.
+     *
+     * Sentinels on the patch: defaultPan == 0xFF, defaultNoteVolume == 0,
+     * vibratoWaveform == 0xFF all defer to the base instrument. Other fields
+     * are always carried by the patch (converter responsibility).
+     */
+    private fun applyActiveSample(voice: Voice, inst: TaudInst, patch: TaudInstPatch?) {
+        if (patch == null) {
+            voice.activeSamplePtr        = inst.samplePtr
+            voice.activeSampleLength     = inst.sampleLength
+            voice.activeSamplePlayStart  = inst.samplePlayStart
+            voice.activeSampleLoopStart  = inst.sampleLoopStart
+            voice.activeSampleLoopEnd    = inst.sampleLoopEnd
+            voice.activeSamplingRate     = inst.samplingRate
+            voice.activeSampleDetune     = inst.sampleDetuneSigned
+            voice.activeLoopMode         = inst.loopMode
+            voice.activeVibratoSpeed     = inst.vibratoSpeed
+            voice.activeVibratoSweep     = inst.vibratoSweep
+            voice.activeVibratoDepth     = inst.vibratoDepth
+            voice.activeVibratoRate      = inst.vibratoRate
+            voice.activeVibratoWaveform  = inst.vibratoWaveform
+        } else {
+            voice.activeSamplePtr        = patch.samplePtr
+            voice.activeSampleLength     = patch.sampleLength
+            voice.activeSamplePlayStart  = patch.playStart
+            voice.activeSampleLoopStart  = patch.loopStart
+            voice.activeSampleLoopEnd    = patch.loopEnd
+            voice.activeSamplingRate     = patch.samplingRate
+            voice.activeSampleDetune     = patch.sampleDetune
+            voice.activeLoopMode         = patch.loopMode
+            voice.activeVibratoSpeed     = patch.vibratoSpeed
+            voice.activeVibratoSweep     = patch.vibratoSweep
+            voice.activeVibratoDepth     = patch.vibratoDepth
+            voice.activeVibratoRate      = patch.vibratoRate
+            voice.activeVibratoWaveform  =
+                if (patch.vibratoWaveform == 0xFF) inst.vibratoWaveform else patch.vibratoWaveform
+        }
+    }
 
     // Convert a 4096-TET noteVal to its Amiga-period equivalent (Double, no rounding).
     private fun noteValToAmigaPeriod(noteVal: Int): Double =
@@ -1754,16 +1800,19 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
      * 0 means full depth immediately).
      */
     private fun advanceAutoVibrato(voice: Voice, inst: TaudInst): Int {
-        // Depth from byte 187 (full 0..255). Speed from byte 175 (FT2 0..255 scale).
-        val depth0 = inst.vibratoDepth
-        if (depth0 == 0 || inst.vibratoSpeed == 0) return 0
+        // Reads come from the voice's active-sample snapshot (patch-aware) so multi-sample
+        // IT/XM instruments use the per-sample auto-vibrato that the trigger resolved to.
+        // [inst] is retained in the signature for callsite continuity but only the voice's
+        // active fields are consulted here.
+        val depth0 = voice.activeVibratoDepth
+        if (depth0 == 0 || voice.activeVibratoSpeed == 0) return 0
 
         // Two ramp-in semantics:
         //   FT2 vibratoSweep (byte 176): "ticks to fully ramp" — depth = depth0 * t / sweep.
         //   IT vibratoRate   (byte 188): "ramp acceleration" — accumulator += rate per tick,
         //                                 capped at depth0 * 256, then divided by 256.
-        val ftSweep  = inst.vibratoSweep
-        val itRate   = inst.vibratoRate
+        val ftSweep  = voice.activeVibratoSweep
+        val itRate   = voice.activeVibratoRate
         val t        = voice.autoVibTicksSinceTrigger
         val rampDepth = when {
             ftSweep != 0 -> ((depth0 * t / ftSweep).coerceAtMost(depth0))
@@ -1772,17 +1821,17 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         }
         voice.autoVibTicksSinceTrigger++
 
-        // Vibrato waveform selector lives in instrumentFlag bits 2-4.
+        // Vibrato waveform selector lives in instrumentFlag bits 2-4 (snapshotted onto voice).
         // 0=sine, 1=ramp-down, 2=square, 3=random, 4=ramp-up (FT2 only).
         // lfoSample handles 0..3; treat 4 (ramp-up) as negated ramp-down.
-        val wave = inst.vibratoWaveform
+        val wave = voice.activeVibratoWaveform
         val rawSample = if (wave == 4) -lfoSample(voice.autoVibPhase, 1)
                         else            lfoSample(voice.autoVibPhase, wave and 3)
         // 4096-TET delta. depth0 is now 0..255 (was 0..15 in old layout); the
         // shift compensates so depth ≈255 yields a similar musical excursion
         // (~±9 cents) to the old depth ≈15.
         val pitchDelta = (rawSample * rampDepth) shr 10
-        voice.autoVibPhase = (voice.autoVibPhase + inst.vibratoSpeed * 2) and 0xFF
+        voice.autoVibPhase = (voice.autoVibPhase + voice.activeVibratoSpeed * 2) and 0xFF
         return pitchDelta
     }
 
@@ -1790,10 +1839,14 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
      * Read one PCM sample (in [-1, 1]) at integer index [idx], honouring the instrument's
      * funk-repeat mask.  Out-of-range indices are clamped to the sample bounds; the
      * caller is responsible for wrapping into a loop region first if loop semantics apply.
+     *
+     * Sample-geometry reads come from the voice's active-sample snapshot so Ixmp-patched
+     * voices read the right bytes. The funk-mask continues to live on the base instrument
+     * (PT2 effect; doesn't combine with multi-sample IT/XM in practice).
      */
-    private fun readSamplePoint(inst: TaudInst, idx: Int, sampleLen: Int, binMax: Int): Double {
+    private fun readSamplePoint(voice: Voice, inst: TaudInst, idx: Int, sampleLen: Int, binMax: Int): Double {
         val i = idx.coerceIn(0, sampleLen - 1)
-        var b = sampleBin[(inst.samplePtr + i).coerceAtMost(binMax).toLong()].toUint()
+        var b = sampleBin[(voice.activeSamplePtr + i).coerceAtMost(binMax).toLong()].toUint()
         if (inst.funkMask != null && inst.sampleLoopEnd > inst.sampleLoopStart) {
             val ls = inst.sampleLoopStart
             if (i in ls until inst.sampleLoopEnd && inst.funkBit(i - ls)) b = b xor 0xFF
@@ -1804,9 +1857,9 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
     private fun fetchTrackerSample(voice: Voice, inst: TaudInst, interpMode: Int): Double {
         if (inst.index == 0) return 0.0
 
-        val sampleLen = inst.sampleLength.coerceAtLeast(1)
-        val loopStart = inst.sampleLoopStart.toDouble()
-        val loopEnd = inst.sampleLoopEnd.toDouble().coerceAtLeast(1.0)
+        val sampleLen = voice.activeSampleLength.coerceAtLeast(1)
+        val loopStart = voice.activeSampleLoopStart.toDouble()
+        val loopEnd = voice.activeSampleLoopEnd.toDouble().coerceAtLeast(1.0)
         val binMax = (SAMPLE_BIN_TOTAL - 1).toInt()  // 8 MB pool, addressed via samplePtr directly (not banked)
 
         val i0 = voice.samplePos.toInt().coerceIn(0, sampleLen - 1)
@@ -1826,7 +1879,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 // Taps span [i0 - WIDTH, i0 + WIDTH], with the kernel centred on i0+frac.
                 for (j in -SINC_WIDTH .. SINC_WIDTH) {
                     val coeff = sincTap(frac, j)
-                    if (coeff != 0.0) acc += readSamplePoint(inst, i0 + j, sampleLen, binMax) * coeff
+                    if (coeff != 0.0) acc += readSamplePoint(voice, inst, i0 + j, sampleLen, binMax) * coeff
                 }
                 acc
             }
@@ -1837,10 +1890,10 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 // formula in integer arithmetic, then map (out >> 1) back to [-1, 1].
                 // The (out & 0xffff) → int16 cast after the third tap reproduces the
                 // SNES hardware mid-sum overflow (the famous gauss "chirp").
-                val oldest = (readSamplePoint(inst, i0 - 1, sampleLen, binMax) * 32767.0).toInt()
-                val olders = (readSamplePoint(inst, i0,     sampleLen, binMax) * 32767.0).toInt()
-                val olds   = (readSamplePoint(inst, i0 + 1, sampleLen, binMax) * 32767.0).toInt()
-                val news   = (readSamplePoint(inst, i0 + 2, sampleLen, binMax) * 32767.0).toInt()
+                val oldest = (readSamplePoint(voice, inst, i0 - 1, sampleLen, binMax) * 32767.0).toInt()
+                val olders = (readSamplePoint(voice, inst, i0,     sampleLen, binMax) * 32767.0).toInt()
+                val olds   = (readSamplePoint(voice, inst, i0 + 1, sampleLen, binMax) * 32767.0).toInt()
+                val news   = (readSamplePoint(voice, inst, i0 + 2, sampleLen, binMax) * 32767.0).toInt()
                 val offset = (frac * 256.0).toInt().coerceIn(0, 255)
                 var out = (SNES_GAUSS[0xff  - offset] * oldest) shr 10
                 out    += (SNES_GAUSS[0x1ff - offset] * olders) shr 10
@@ -1868,7 +1921,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 // a mid-rail seed), reproducing DMC's coarse quantisation. Per-voice
                 // counter persists across samples and is reseeded to mid-rail on note
                 // trigger (see triggerNote).
-                val target = readSamplePoint(inst, i0, sampleLen, binMax)
+                val target = readSamplePoint(voice, inst, i0, sampleLen, binMax)
                 val targetLevel = ((target + 1.0) * 63.5).toInt().coerceIn(0, 127)
                 when {
                     targetLevel > voice.nesDpcmCounter && voice.nesDpcmCounter <= 125 ->
@@ -1881,8 +1934,8 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
             INTERP_NONE, INTERP_A500, INTERP_A1200 ->
                 // Paula-style ZOH — emit the integer-indexed sample byte without
                 // sub-sample fade. Aliasing is removed by the post-mix Amiga LPFs.
-                readSamplePoint(inst, i0, sampleLen, binMax)
-            else -> readSamplePoint(inst, i0, sampleLen, binMax)
+                readSamplePoint(voice, inst, i0, sampleLen, binMax)
+            else -> readSamplePoint(voice, inst, i0, sampleLen, binMax)
         }
 
         // While ramping out at sample end, hold position so the mixer keeps emitting the
@@ -1895,7 +1948,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
             // When the sustain bit is set, key-off escapes the loop: the sample plays past
             // loopEnd until it ends naturally (loopMode 0 semantics).
             val effectiveLoopMode =
-                if (inst.sampleLoopSustain && voice.keyOff) 0 else (inst.loopMode and 3)
+                if (voice.activeSampleLoopSustain && voice.keyOff) 0 else (voice.activeLoopMode and 3)
             when (effectiveLoopMode) {
                 0 -> if (voice.samplePos >= sampleLen) {
                     voice.samplePos = (sampleLen - 1).toDouble().coerceAtLeast(0.0)
@@ -1977,16 +2030,27 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
      * unconditionally on inst-column rows, regardless of porta). Sets
      * noteVolume only — channelVolume (IT chan->global_volume) survives.
      */
-    private fun rowVolumeFromDefault(inst: TaudInst): Int {
-        val dnv = inst.defaultNoteVolume
+    private fun rowVolumeFromDefault(inst: TaudInst, patch: TaudInstPatch? = null): Int {
+        // Patch overrides the base inst's DNV unless the sentinel (0 = no override).
+        val dnv = patch?.defaultNoteVolume?.takeIf { it != 0 } ?: inst.defaultNoteVolume
         return if (dnv == 0) 0x3F else (dnv * 63 + 127) / 255
     }
 
     private fun triggerNote(voice: Voice, noteVal: Int, instId: Int, volOverride: Int) {
         if (instId != 0) voice.instrumentId = instId
         val inst = instruments[voice.instrumentId]
+        // Resolve the Ixmp patch (if any) for this trigger. Volume axis uses the
+        // pre-patch seed so the rectangle test is well-defined; the patch's own
+        // DNV is then layered onto the final voice.noteVolume below.
+        val seedVolForLookup = when {
+            volOverride >= 0 -> volOverride.coerceIn(0, 0x3F)
+            instId != 0      -> rowVolumeFromDefault(inst, null)
+            else             -> voice.noteVolume.coerceIn(0, 0x3F)
+        }
+        val patch = inst.resolvePatch(noteVal, seedVolForLookup)
+        applyActiveSample(voice, inst, patch)
         voice.tonePortaTarget = -1   // fresh note trigger cancels any running porta
-        voice.samplePos = inst.samplePlayStart.toDouble()
+        voice.samplePos = voice.activeSamplePlayStart.toDouble()
         voice.forward = true
         voice.active = true
         voice.keyOff = false
@@ -2042,8 +2106,11 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         if (instId != 0) {
             // Default pan: applied unless the pattern row has already overridden channelPan.
             // The pan envelope's 'p' flag ("use default pan") lives in the pan LOOP word at bit 7.
+            // An Ixmp patch's defaultPan (when non-sentinel, i.e. != 0xFF) takes precedence over
+            // the base instrument's defaultPan.
             if ((inst.panEnvLoop ushr 7) and 1 != 0) {
-                voice.channelPan = inst.defaultPan
+                val patchPan = patch?.defaultPan?.takeIf { it != 0xFF }
+                voice.channelPan = patchPan ?: inst.defaultPan
                 voice.rowPan = (voice.channelPan ushr 2).coerceIn(0, 63)
             }
             // Pitch-pan separation: when PPS != 0, played notes far from PPC drift in pan.
@@ -2066,7 +2133,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         voice.basePitch = noteVal
         voice.amigaPeriod = -1.0   // fresh trigger: period state must reseed from the new noteVal
         voice.linearFreq  = -1.0   // ditto for linear-freq mode (toneMode == 2)
-        voice.playbackRate = computePlaybackRate(inst, noteVal)
+        voice.playbackRate = computePlaybackRate(voice, noteVal)
         // Fresh trigger seeds noteVolume from the per-instrument "default note volume"
         // (byte 196) when the row carried an instrument byte but no explicit V column —
         // matching IT's `chan->volume = psmp->volume` rule (Schism player/effects.c:1302
@@ -2078,9 +2145,10 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         // chan->global_volume across sample changes, so M / N writes persist.
         // Continuous per-instrument scaling lives in instGlobalVolume (byte 171), which the
         // mixer applies independently of this seed.
+        // When an Ixmp patch overrides DNV (non-sentinel), the patch wins via rowVolumeFromDefault.
         voice.noteVolume = when {
             volOverride >= 0 -> volOverride.coerceIn(0, 0x3F)
-            instId != 0     -> rowVolumeFromDefault(inst)
+            instId != 0     -> rowVolumeFromDefault(inst, patch)
             else            -> voice.noteVolume
         }
         voice.rowVolume = voice.noteVolume
@@ -2126,14 +2194,21 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
     private fun applyDuplicateCheck(ts: TrackerState, channel: Int, newInstId: Int, newNote: Int) {
         if (newInstId == 0) return
         val newInst = instruments[newInstId]
+        // For DCT=2 (sample match) we compare canonical sample identity. With Ixmp, the
+        // new note's effective sample is the patch's (or the base inst's if no patch).
+        // Volume axis defaults to full (0x3F) at this resolution point — the actual
+        // trigger volume isn't known yet and the IT DCT model is volume-agnostic anyway.
+        val newPatch = newInst.resolvePatch(newNote, 0x3F)
+        val newSmpPtr = newPatch?.samplePtr ?: newInst.samplePtr
+        val newSmpLen = newPatch?.sampleLength ?: newInst.sampleLength
 
         fun isDuplicate(v: Voice): Boolean {
             val existInst = instruments[v.instrumentId]
             return when (existInst.duplicateCheckType) {
                 1 -> v.noteVal == newNote && v.instrumentId == newInstId
                 2 -> v.instrumentId == newInstId &&
-                     existInst.samplePtr == newInst.samplePtr &&
-                     existInst.sampleLength == newInst.sampleLength
+                     v.activeSamplePtr == newSmpPtr &&
+                     v.activeSampleLength == newSmpLen
                 3 -> v.instrumentId == newInstId
                 else -> false
             }
@@ -2254,6 +2329,22 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         v.bitcrusherHeld = src.bitcrusherHeld
         v.overdriveAmp = src.overdriveAmp
         v.sourceChannel = channel
+        // Active-sample snapshot must follow the foreground voice so the ghost's per-tick
+        // playback (samplingRate, loop bounds, auto-vibrato) keeps using the patch the
+        // foreground had bound — not the base instrument it would otherwise re-derive.
+        v.activeSamplePtr        = src.activeSamplePtr
+        v.activeSampleLength     = src.activeSampleLength
+        v.activeSamplePlayStart  = src.activeSamplePlayStart
+        v.activeSampleLoopStart  = src.activeSampleLoopStart
+        v.activeSampleLoopEnd    = src.activeSampleLoopEnd
+        v.activeSamplingRate     = src.activeSamplingRate
+        v.activeSampleDetune     = src.activeSampleDetune
+        v.activeLoopMode         = src.activeLoopMode
+        v.activeVibratoSpeed     = src.activeVibratoSpeed
+        v.activeVibratoSweep     = src.activeVibratoSweep
+        v.activeVibratoDepth     = src.activeVibratoDepth
+        v.activeVibratoRate      = src.activeVibratoRate
+        v.activeVibratoWaveform  = src.activeVibratoWaveform
         return v
     }
 
@@ -2433,7 +2524,15 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 0x0000 -> {
                     if (row.instrment != 0) {
                         voice.instrumentId = row.instrment
-                        val seedVol = rowVolumeFromDefault(instruments[voice.instrumentId])
+                        // Re-resolve the patch on the new instrument against the voice's
+                        // current note so multi-sample IT/XM instruments pick up the right
+                        // sample (and per-patch DNV) even on a continue row. samplePos is
+                        // preserved — Schism csf_instrument_change reloads sample geometry
+                        // but does not retrigger.
+                        val newInst = instruments[voice.instrumentId]
+                        val newPatch = newInst.resolvePatch(voice.noteVal, voice.noteVolume)
+                        applyActiveSample(voice, newInst, newPatch)
+                        val seedVol = rowVolumeFromDefault(newInst, newPatch)
                         voice.noteVolume = seedVol
                         voice.rowVolume = seedVol
                         voice.keyOff = false
@@ -2470,7 +2569,14 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                         // and the bump persisted through the following vibrato rows).
                         if (row.instrment != 0) {
                             voice.instrumentId = row.instrment
-                            val seedVol = rowVolumeFromDefault(instruments[voice.instrumentId])
+                            // Porta + inst-byte: re-resolve the patch on the new instrument
+                            // against the voice's current note (Schism evaluates the keyboard
+                            // table at csf_instrument_change time; the porta target row.note
+                            // is only the slide destination, not the sample selector).
+                            val newInst = instruments[voice.instrumentId]
+                            val newPatch = newInst.resolvePatch(voice.noteVal, voice.noteVolume)
+                            applyActiveSample(voice, newInst, newPatch)
+                            val seedVol = rowVolumeFromDefault(newInst, newPatch)
                             voice.noteVolume = seedVol
                             voice.rowVolume = seedVol
                             voice.keyOff = false
@@ -2609,7 +2715,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                     voice.basePitch = voice.noteVal
                     voice.amigaPeriod = -1.0   // reseed on next per-tick slide
                     voice.linearFreq  = -1.0
-                    voice.playbackRate = computePlaybackRate(instruments[voice.instrumentId], voice.noteVal)
+                    voice.playbackRate = computePlaybackRate(voice, voice.noteVal)
                 } else {
                     voice.slideMode = 1; voice.slideArg = -arg
                     voice.amigaPeriod = -1.0   // reseed at the start of a fresh multi-tick slide
@@ -2628,7 +2734,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                     voice.basePitch = voice.noteVal
                     voice.amigaPeriod = -1.0
                     voice.linearFreq  = -1.0
-                    voice.playbackRate = computePlaybackRate(instruments[voice.instrumentId], voice.noteVal)
+                    voice.playbackRate = computePlaybackRate(voice, voice.noteVal)
                 } else {
                     voice.slideMode = 2; voice.slideArg = arg
                     voice.amigaPeriod = -1.0
@@ -2741,12 +2847,15 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 }
             }
             EffectOp.OP_O -> {
+                // Sample-offset O: clamps into the active sample's loop region when an O$xx
+                // value lands past loopEnd. Reads from the patch-aware active-sample view.
                 val arg = resolveArg(rawArg, voice.mem.o).also { if (rawArg != 0) voice.mem.o = it }
-                val inst = instruments[voice.instrumentId]
                 var off = arg
-                if ((inst.loopMode and 3) != 0 && inst.sampleLoopEnd > inst.sampleLoopStart && off > inst.sampleLoopEnd) {
-                    val loopLen = (inst.sampleLoopEnd - inst.sampleLoopStart).coerceAtLeast(1)
-                    off = inst.sampleLoopStart + ((off - inst.sampleLoopStart) % loopLen)
+                if ((voice.activeLoopMode and 3) != 0 &&
+                    voice.activeSampleLoopEnd > voice.activeSampleLoopStart &&
+                    off > voice.activeSampleLoopEnd) {
+                    val loopLen = (voice.activeSampleLoopEnd - voice.activeSampleLoopStart).coerceAtLeast(1)
+                    off = voice.activeSampleLoopStart + ((off - voice.activeSampleLoopStart) % loopLen)
                 }
                 voice.samplePos = off.toDouble()
             }
@@ -2837,7 +2946,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 voice.basePitch = voice.noteVal
                 voice.amigaPeriod = -1.0
                 voice.linearFreq  = -1.0
-                voice.playbackRate = computePlaybackRate(instruments[voice.instrumentId], voice.noteVal)
+                voice.playbackRate = computePlaybackRate(voice, voice.noteVal)
             }
             0x3 -> { voice.vibratoWave = x and 3; voice.vibratoRetrig = (x and 4) == 0 }
             0x4 -> { voice.tremoloWave = x and 3; voice.tremoloRetrig = (x and 4) == 0 }
@@ -2905,7 +3014,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         for (vi in 0 until ts.voices.size) {
             val voice = ts.voices[vi]
             if (!voice.active && voice.noteDelayTick < 0) continue
-            val inst = instruments[voice.instrumentId]
+            var inst = instruments[voice.instrumentId]
 
             // Note cut. Zero noteVolume / rowVolume (silence this note) but leave channelVolume
             // alone — IT's note cut stops the sample, it doesn't reset chan->global_volume.
@@ -2921,6 +3030,13 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 maybeSpawnBackgroundForNNA(ts, voice, vi)
                 triggerNote(voice, voice.delayedNote, voice.delayedInst, voice.delayedVol)
                 voice.noteDelayTick = -1
+                // triggerNote may have swapped in a new instrument; re-bind so the rest of this
+                // tick's per-voice work (playbackRate at L3090, envelope/fadeout/auto-vibrato)
+                // uses the instrument that just fired, not the one the voice held on entry. On a
+                // never-triggered voice the stale binding is instruments[0] (samplingRate 0),
+                // which would zero playbackRate and freeze the sample — the "first note on a
+                // fresh channel via S$Dx is silent" bug.
+                inst = instruments[voice.instrumentId]
             }
 
             if (!voice.active) {
@@ -3059,7 +3175,10 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 if (voice.retrigCounter >= voice.retrigInterval) {
                     voice.retrigCounter = 0
                     val retrigInst = instruments[voice.instrumentId]
-                    voice.samplePos = retrigInst.samplePlayStart.toDouble()
+                    // Use the voice's active sample's playStart (patch-aware) — without this
+                    // a Q retrigger on a multi-sample instrument would jump to the base sample
+                    // even though the voice is bound to a patch.
+                    voice.samplePos = voice.activeSamplePlayStart.toDouble()
                     voice.keyOff = false
                     voice.envIndex = 0; voice.envTimeSec = 0.0
                     voice.envPanIndex = 0; voice.envPanTimeSec = 0.0
@@ -3087,7 +3206,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
             else 0
 
             val finalPitch = (pitchToMixer + autoVibDelta + pitchEnvDelta).coerceIn(0x20, 0xFFFF)
-            voice.playbackRate = computePlaybackRate(inst, finalPitch)
+            voice.playbackRate = computePlaybackRate(voice, finalPitch)
 
             // Filter envelope (filter mode): scale baseCut by envValue (0..1, 0.5 = unity).
             // Schism filters.c:80-86 computes `cutoff_used = chan->cutoff * (flt_modifier+256)/256`
@@ -3191,7 +3310,7 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
                 ((bg.envPfValue - 0.5) * 2.0 * 16.0 * 4096.0 / 12.0).toInt()
             else 0
             val finalPitch = (bg.noteVal + autoVibDelta + pitchEnvDelta).coerceIn(0x20, 0xFFFF)
-            bg.playbackRate = computePlaybackRate(inst, finalPitch)
+            bg.playbackRate = computePlaybackRate(bg, finalPitch)
             // Filter-mode pf envelope: same scaling rule as foreground.
             if (bg.hasPfEnv && bg.pfEnvOn && bg.envPfIsFilter) {
                 val baseCut = if (inst.defaultCutoff < 255) inst.defaultCutoff else 254
@@ -3683,6 +3802,27 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         var autoVibPhase = 0               // 8-bit phase counter
         var autoVibTicksSinceTrigger = 0   // for sweep ramp-up
 
+        // Active-sample view — snapshot of either the base instrument's sample-scope
+        // fields or, when an Ixmp patch covers (noteVal, rowVolume) at trigger time,
+        // the matching TaudInstPatch overlay. Per-tick and per-row code reads from
+        // these instead of `inst.*` so multi-sample (IT keyboard table) instruments
+        // play the correct sample for the triggered note. Snapshotted by triggerNote
+        // and the equivalent paths (Q retrigger, NNA ghosting).
+        var activeSamplePtr        = 0
+        var activeSampleLength     = 0
+        var activeSamplePlayStart  = 0
+        var activeSampleLoopStart  = 0
+        var activeSampleLoopEnd    = 0
+        var activeSamplingRate     = 0
+        var activeSampleDetune     = 0     // signed 4096-TET
+        var activeLoopMode         = 0     // bits 0-1 = direction, bit 2 = sustain (matches inst byte 14)
+        var activeVibratoSpeed     = 0
+        var activeVibratoSweep     = 0
+        var activeVibratoDepth     = 0
+        var activeVibratoRate      = 0
+        var activeVibratoWaveform  = 0     // bits 0-2 only
+        val activeSampleLoopSustain: Boolean get() = (activeLoopMode and 0x04) != 0
+
         // NES 2A03 DMC counter for INTERP_NES_DPCM (interpolation mode 5).
         // 7-bit unsigned (0..127), slews ±2 per output sample as the sigma-delta
         // bitstream is generated on the fly. Seeded to mid-rail (63) on every
@@ -4094,6 +4234,20 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
             }
         }
 
+        /** Clear funk-repeat (S$Fx) state only — per-voice run-state plus the per-instrument
+         *  loop-inversion masks — without touching tempo / volume / position. taut calls this on
+         *  every fresh play-from-start so accumulated inversions and a stale funkSpeed don't bleed
+         *  from a prior session into the replay; full resetParams would also clobber bpm / tickRate /
+         *  volume, which a replay must preserve. Masks still persist across a natural song loop. */
+        fun resetFunkState() {
+            trackerState?.voices?.forEach {
+                it.funkSpeed = 0
+                it.funkAccumulator = 0
+                it.funkWritePos = 0
+            }
+            parent.instruments.forEach { it.funkMask = null }
+        }
+
         fun purgeQueue() {
             pcmQueue.clear()
             if (isPcmMode) {
@@ -4152,6 +4306,41 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
     }
 
     data class TaudInstEnvPoint(var value: Int, var offset: ThreeFiveMiniUfloat)
+
+    /**
+     * One Ixmp "extra sample" patch — overlays sample-scope state on a base instrument
+     * for a (noteVal, rowVolume) rectangle. See terranmon.txt "Ixmp. Instrument extra
+     * samples" for the on-wire layout. Envelopes, fadeout, NNA / DCT / DCA, filter,
+     * pitch-pan, IGV and other instrument-scope fields stay on the base TaudInst —
+     * only the fields below override.
+     *
+     * Sentinels: defaultPan == 0xFF, defaultNoteVolume == 0, vibratoWaveform == 0xFF
+     * all mean "inherit the base instrument's value". samplingRate == 0 would silence
+     * the patch (same semantics as base inst), so converters must always supply it.
+     */
+    data class TaudInstPatch(
+        val pitchStart: Int,
+        val pitchEnd: Int,
+        val volumeStart: Int,
+        val volumeEnd: Int,
+        val samplePtr: Int,
+        val sampleLength: Int,
+        val playStart: Int,
+        val loopStart: Int,
+        val loopEnd: Int,
+        val samplingRate: Int,
+        val sampleDetune: Int,            // signed 4096-TET
+        val loopMode: Int,                // matches base inst byte 14 (bits 0-1 = mode, bit 2 = sustain)
+        val defaultPan: Int,              // 0..255; 0xFF = no override
+        val defaultNoteVolume: Int,       // 0..255 IT-scaled; 0 = no override
+        val vibratoSpeed: Int,
+        val vibratoSweep: Int,
+        val vibratoDepth: Int,
+        val vibratoRate: Int,
+        val vibratoWaveform: Int          // 0..7; 0xFF = no override
+    ) {
+        val sampleLoopSustain: Boolean get() = (loopMode and 0x04) != 0
+    }
     /**
      * 256-byte instrument record (terranmon.txt:2001+).
      *
@@ -4276,12 +4465,31 @@ class AudioAdapter(val vm: VM) : PeriBase(VM.PERITYPE_SOUND) {
         // Byte 196 is the new "default note volume" field — see triggerNote.
         private val reserved = ByteArray(59)
 
+        // Optional Ixmp "extra sample" patches — non-null when an Ixmp block was uploaded
+        // for this instrument. Patches are scanned in order at trigger time; first hit on
+        // (noteVal, rowVolume) wins (overlapping rectangles are INVALID per spec).
+        var extraPatches: Array<TaudInstPatch>? = null
+
+        /** Walk [extraPatches] and return the first patch whose pitch+volume rectangle
+         *  contains the given trigger. Returns null when no patches are bound or none match. */
+        fun resolvePatch(noteVal: Int, rowVolume: Int): TaudInstPatch? {
+            val patches = extraPatches ?: return null
+            for (p in patches) {
+                if (noteVal in p.pitchStart..p.pitchEnd &&
+                    rowVolume in p.volumeStart..p.volumeEnd) return p
+            }
+            return null
+        }
+
         // Funk repeat (S$Fx00) bit-mask — non-destructive XOR overlay across the loop region.
         // Lazily allocated; a 1-bit flips the byte, a 0-bit leaves it intact.
         // Mask is sized for the loop length at allocation time; if the loop bounds change
         // (e.g. a new song reuses this instrument slot with different sample data) the old
         // mask is stale and must be discarded — otherwise indexing past its end crashes the
         // render thread with ArrayIndexOutOfBoundsException.
+        // Note: with Ixmp patches active the mask still indexes the BASE instrument's loop
+        // region, not the active patch's. Funk repeat (S$Fx) is a PT2 effect and doesn't
+        // coexist with multi-sample IT/XM instruments in practice.
         var funkMask: ByteArray? = null
         fun toggleFunkBit(loopOffset: Int) {
             val len = (sampleLoopEnd - sampleLoopStart).coerceAtLeast(1)

tsvm_core/src/net/torvald/tsvm/peripheral/IOSpace.kt

@@ -3,6 +3,8 @@ package net.torvald.tsvm.peripheral
 import com.badlogic.gdx.Gdx
 import com.badlogic.gdx.Input
 import com.badlogic.gdx.InputProcessor
+import com.badlogic.gdx.math.Vector2
+import com.badlogic.gdx.utils.viewport.Viewport
 import net.torvald.AddressOverflowException
 import net.torvald.DanglingPointerException
 import net.torvald.UnsafeHelper
@@ -10,6 +12,7 @@ import net.torvald.tsvm.CircularArray
 import net.torvald.tsvm.VM
 import net.torvald.tsvm.isNonZero
 import net.torvald.tsvm.toInt
+import java.util.concurrent.atomic.AtomicInteger
 import kotlin.experimental.and
 
 class IOSpace(val vm: VM) : PeriBase("io"), InputProcessor {
@@ -18,10 +21,25 @@ class IOSpace(val vm: VM) : PeriBase("io"), InputProcessor {
         return vm
     }
 
-    /** Absolute x-position of the computer GUI */
-    var guiPosX = 0
-    /** Absolute y-position of the computer GUI */
-    var guiPosY = 0
+    /**
+     * Viewport that maps screen pixels (as reported by `Gdx.input.x/y`) to the VM's
+     * logical framebuffer coordinate space. The host application owns the rendering
+     * camera, so the host is responsible for installing a viewport whose world
+     * coordinates match the VM framebuffer (origin top-left, world size = framebuffer
+     * size in pixels) and whose screen rectangle matches where the VM is drawn.
+     *
+     * If left null, `Gdx.input.x/y` is forwarded verbatim — only correct when the VM
+     * occupies the entire window at 1:1 scale.
+     */
+    var inputViewport: Viewport? = null
+    private val tmpMouseVec = Vector2()
+    // Letterbox offset and renderable area inside the inputViewport, set by the host VMGUI.
+    // After unproject, mouse pixel coords are shifted by (inputOriginX, inputOriginY) and
+    // clamped to (inputAreaW, inputAreaH) so apps see VM-screen pixel coords (0..drawWidth).
+    var inputOriginX: Int = 0
+    var inputOriginY: Int = 0
+    var inputAreaW: Int = Int.MAX_VALUE
+    var inputAreaH: Int = Int.MAX_VALUE
 
     /** Accepts a keycode */
     private val keyboardBuffer = CircularArray<Byte>(32, true)
@@ -98,7 +116,12 @@ class IOSpace(val vm: VM) : PeriBase("io"), InputProcessor {
             in 0..31 -> keyboardBuffer[(addr.toInt())] ?: -1
             in 32..33 -> (mouseX.toInt() shr (adi - 32).times(8)).toByte()
             in 34..35 -> (mouseY.toInt() shr (adi - 34).times(8)).toByte()
-            36L -> mouseDown.toInt().toByte()
+            36L -> {
+                // bit 0: left, bit 1: right, bit 2: middle, bit 6: wheel up, bit 7: wheel down
+                // Wheel bits are latched on scrolled() and cleared on read so a one-shot
+                // detent fires exactly once for the polling app.
+                (mouseButtons or wheelLatch.getAndSet(0)).toByte()
+            }
             37L -> {
                 val key = keyboardBuffer.removeTail() ?: -1
                 keyPushed = !keyboardBuffer.isEmpty  // Clear flag when buffer becomes empty
@@ -280,7 +303,9 @@ class IOSpace(val vm: VM) : PeriBase("io"), InputProcessor {
 
     private var mouseX: Short = 0
     private var mouseY: Short = 0
-    private var mouseDown = false
+    private var mouseButtons: Int = 0  // bit 0 = LEFT, bit 1 = RIGHT, bit 2 = MIDDLE
+    // bits 6 (wheel up) and 7 (wheel down) — set by scrolled(), cleared on MMIO[36] read
+    private val wheelLatch = AtomicInteger(0)
     private var systemUptime = 0L
     private var rtc = 0L
 
@@ -296,10 +321,28 @@ class IOSpace(val vm: VM) : PeriBase("io"), InputProcessor {
             keyEventBuffers.fill(0)
 
             if (isFocused) {
-                // store mouse info
-                mouseX = (Gdx.input.x + guiPosX).toShort()
-                mouseY = (Gdx.input.y + guiPosY).toShort()
-                mouseDown = Gdx.input.isTouched
+                // store mouse info; unproject through the host-provided viewport so the
+                // VM sees logical framebuffer pixels regardless of window magnification,
+                // letterboxing or sub-region placement done by an embedding GDX app.
+                val vp = inputViewport
+                val rawX: Int
+                val rawY: Int
+                if (vp != null) {
+                    tmpMouseVec.set(Gdx.input.x.toFloat(), Gdx.input.y.toFloat())
+                    vp.unproject(tmpMouseVec)
+                    rawX = tmpMouseVec.x.toInt()
+                    rawY = tmpMouseVec.y.toInt()
+                }
+                else {
+                    rawX = Gdx.input.x
+                    rawY = Gdx.input.y
+                }
+                // Subtract the letterbox origin so apps see VM-screen pixel coords (0..drawWidth).
+                mouseX = (rawX - inputOriginX).coerceIn(0, inputAreaW - 1).toShort()
+                mouseY = (rawY - inputOriginY).coerceIn(0, inputAreaH - 1).toShort()
+                mouseButtons = (if (Gdx.input.isButtonPressed(Input.Buttons.LEFT))   1 else 0) or
+                               (if (Gdx.input.isButtonPressed(Input.Buttons.RIGHT))  2 else 0) or
+                               (if (Gdx.input.isButtonPressed(Input.Buttons.MIDDLE)) 4 else 0)
 
                 // strobe keys to fill the key read buffer
                 var keysPushed = 0
@@ -313,7 +356,7 @@ class IOSpace(val vm: VM) : PeriBase("io"), InputProcessor {
                 }
             }
             else {
-                mouseDown = false
+                mouseButtons = 0
             }
         }
 
@@ -376,8 +419,15 @@ class IOSpace(val vm: VM) : PeriBase("io"), InputProcessor {
         }
     }
 
-    override fun scrolled(p0: Float, p1: Float): Boolean {
-        return false
+    override fun scrolled(amountX: Float, amountY: Float): Boolean {
+        // LibGDX: amountY > 0 = scroll DOWN (toward user), amountY < 0 = scroll UP.
+        // Latch bits 6/7 of MMIO[36]; the latch is cleared the next time MMIO[36] is read.
+        if (Gdx.input.inputProcessor !== this) return false
+        when {
+            amountY < 0f -> wheelLatch.updateAndGet { it or 0x40 }
+            amountY > 0f -> wheelLatch.updateAndGet { it or 0x80 }
+        }
+        return true
     }
 
     override fun keyUp(p0: Int): Boolean {

tsvm_executable/src/net/torvald/tsvm/VMEmuExecutable.kt

@@ -127,7 +127,9 @@ class VMEmuExecutable(val windowWidth: Int, val windowHeight: Int, var panelsX:
     internal fun moveView(oldIndex: Int, newIndex: Int?) {
         if (oldIndex != newIndex) {
             if (newIndex != null) {
-                vms[newIndex] = vms[oldIndex]
+                val moved = vms[oldIndex]
+                vms[newIndex] = moved
+                moved?.vm?.let { applyMouseInputMappingForPanel(it, newIndex) }
             }
             vms[oldIndex] = null
         }
@@ -135,6 +137,28 @@ class VMEmuExecutable(val windowWidth: Int, val windowHeight: Int, var panelsX:
 
     internal fun addVMtoView(vm: VM, profileName: String, index: Int) {
         vms[index] = VMRunnerInfo(vm, profileName)
+        applyMouseInputMappingForPanel(vm, index)
+    }
+
+    /**
+     * Wire the VM's IOSpace so the mouse pixels it sees are relative to its own
+     * GPU framebuffer rather than the whole TsvmEmulator window. Each tiled VM
+     * lives at panel (pposX, pposY) with a letterbox inside that panel, so the
+     * offset is `panel origin + (panel size − GPU size) / 2`.
+     */
+    private fun applyMouseInputMappingForPanel(vm: VM, panelIndex: Int) {
+        val gpu = vm.peripheralTable.getOrNull(1)?.peripheral as? GraphicsAdapter ?: return
+        val pposX = panelIndex % panelsX
+        val pposY = panelIndex / panelsX
+        val gpuW = gpu.config.width
+        val gpuH = gpu.config.height
+        val io = vm.getIO()
+        // TsvmEmulator draws at 1:1 pixel scale, so no GDX viewport is needed.
+        io.inputViewport = null
+        io.inputOriginX = pposX * windowWidth + (windowWidth - gpuW) / 2
+        io.inputOriginY = pposY * windowHeight + (windowHeight - gpuH) / 2
+        io.inputAreaW = gpuW
+        io.inputAreaH = gpuH
     }
 
     internal fun getCurrentlySelectedVM(): VMRunnerInfo? = if (currentVMselection == null) null else vms[currentVMselection!!]
@@ -201,6 +225,7 @@ class VMEmuExecutable(val windowWidth: Int, val windowHeight: Int, var panelsX:
         val vm1 = getVMbyProfileName("Initial VM")!!
         initVMenv(vm1, "Initial VM")
         vms[0] = VMRunnerInfo(vm1, "Initial VM")
+        applyMouseInputMappingForPanel(vm1, 0)
 
         init()
     }
@@ -307,6 +332,11 @@ class VMEmuExecutable(val windowWidth: Int, val windowHeight: Int, var panelsX:
         if (currentVMselection != null && vms[currentVMselection!!]?.vm?.id == vm.id) {
             Gdx.input.inputProcessor = vm.getIO()
         }
+
+        // peripheralTable[1] (the GPU) was disposed and re-installed; re-apply
+        // the mouse mapping so the rebooted VM keeps targeting its own panel.
+        val panelIndex = vms.indexOfFirst { it?.vm?.id == vm.id }
+        if (panelIndex >= 0) applyMouseInputMappingForPanel(vm, panelIndex)
     }
 
     private fun updateGame(delta: Float) {
@@ -434,6 +464,10 @@ class VMEmuExecutable(val windowWidth: Int, val windowHeight: Int, var panelsX:
         this.panelsX = panelsX
         this.panelsY = panelsY
         resize(windowWidth * panelsX, windowHeight * panelsY)
+        // Panel positions shifted, so every VM needs its mouse origin re-mapped.
+        vms.forEachIndexed { index, info ->
+            info?.vm?.let { applyMouseInputMappingForPanel(it, index) }
+        }
     }
 
     override fun resize(width: Int, height: Int) {

tsvm_executable/src/net/torvald/tsvm/VMGUI.kt

@@ -8,6 +8,8 @@ import com.badlogic.gdx.graphics.g2d.SpriteBatch
 import com.badlogic.gdx.graphics.g2d.TextureRegion
 import com.badlogic.gdx.graphics.glutils.FrameBuffer
 import com.badlogic.gdx.graphics.glutils.ShaderProgram
+import com.badlogic.gdx.utils.viewport.StretchViewport
+import com.badlogic.gdx.utils.viewport.Viewport
 import net.torvald.terrarum.DefaultGL32Shaders
 import net.torvald.tsvm.peripheral.*
 import net.torvald.tsvm.peripheral.GraphicsAdapter.Companion.DRAW_SHADER_VERT
@@ -48,6 +50,14 @@ class VMGUI(val loaderInfo: EmulInstance, val viewportWidth: Int, val viewportHe
     lateinit var batch: SpriteBatch
     lateinit var camera: OrthographicCamera
 
+    /**
+     * Maps window pixels to the VM framebuffer (origin top-left, world size =
+     * viewportWidth × viewportHeight). Stretches to fill the whole window so it
+     * matches the `MAGN`-scaled blit at the end of [renderGame]. Handed to
+     * [IOSpace.inputViewport] so mouse coordinates unproject correctly.
+     */
+    lateinit var inputViewport: Viewport
+
     var gpu: GraphicsAdapter? = null
     lateinit var vmRunner: VMRunner
     lateinit var coroutineJob: Thread
@@ -103,9 +113,20 @@ class VMGUI(val loaderInfo: EmulInstance, val viewportWidth: Int, val viewportHe
         gpuFBO = FrameBuffer(Pixmap.Format.RGBA8888, viewportWidth, viewportHeight, false)
         winFBO = FrameBuffer(Pixmap.Format.RGBA8888, viewportWidth, viewportHeight, false)
 
+        val inputCam = OrthographicCamera().also {
+            it.setToOrtho(true, viewportWidth.toFloat(), viewportHeight.toFloat())
+        }
+        inputViewport = StretchViewport(viewportWidth.toFloat(), viewportHeight.toFloat(), inputCam)
+        inputViewport.update(Gdx.graphics.width, Gdx.graphics.height, true)
+
         init()
     }
 
+    override fun resize(width: Int, height: Int) {
+        super.resize(width, height)
+        inputViewport.update(width, height, true)
+    }
+
     private fun init() {
         vm.init()
 
@@ -148,6 +169,11 @@ class VMGUI(val loaderInfo: EmulInstance, val viewportWidth: Int, val viewportHe
         }
 
         Gdx.input.inputProcessor = vm.getIO()
+        vm.getIO().inputViewport = inputViewport
+        vm.getIO().inputOriginX = (viewportWidth - loaderInfo.drawWidth) / 2
+        vm.getIO().inputOriginY = (viewportHeight - loaderInfo.drawHeight) / 2
+        vm.getIO().inputAreaW   = loaderInfo.drawWidth
+        vm.getIO().inputAreaH   = loaderInfo.drawHeight
 
         if (usememvwr) memvwr = Memvwr(vm)
 

xm2taud.py

@@ -16,6 +16,11 @@ Limits:
     - Multi-sample instruments use the sample selected by the *current
       note's* keymap entry; the converter materialises one Taud
       instrument slot per (XM instrument, sample-in-instrument) pair.
+      (Note: it2taud uses the alternate Ixmp project-data extension
+      instead — one Taud instrument per IT instrument, plus an Ixmp
+      patch list for the keyboard mapping. XM could be retrofitted the
+      same way to conserve Taud instrument slots; deferred until any
+      real XM file actually hits the 255-slot cap.)
 
 Pattern length policy:
     - XM patterns ≤ 64 rows → 1 Taud cue with the LEN ($02xx)