doc update/command synopses

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>

.gitignore

@@ -62,9 +62,18 @@ tsvmman.pdf
 *.ilg
 *.ind
 
+assets/disk0/tvdos/bin/tautfont.png
+
+video_encoder/*
+
+.idea/vcs.xml
+
+# in-dev stuffs
 assets/disk0/home/basic/*
 assets/disk0/movtestimg/*.jpg
 assets/disk0/*.mov
 assets/diskMediabin/*
+assets/disk0/hopper/*
 
-video_encoder/*
+# TVDOS runtime caches (regenerated on the VM; never commit)
+assets/disk0/tvdos/cache/

.idea/cody_history.xml

@@ -0,0 +1,133 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ChatHistory">
+    <accountData>
+      <list>
+        <AccountData>
+          <accountId value="VXNlcjo1NTUxMzY=" />
+          <chats>
+            <list>
+              <chat>
+                <internalId value="8a32c880-d8ec-4d84-b5f7-a62b2edf63c3" />
+                <llm>
+                  <llm>
+                    <model value="anthropic/claude-3-5-sonnet-20240620" />
+                    <provider value="Anthropic" />
+                    <title value="Claude 3.5 Sonnet" />
+                    <usage>
+                      <list>
+                        <option value="chat" />
+                        <option value="edit" />
+                      </list>
+                    </usage>
+                  </llm>
+                </llm>
+              </chat>
+              <chat>
+                <internalId value="f4e7338b-57d3-44e0-b1d9-04aa2dfb4bae" />
+                <llm>
+                  <llm>
+                    <model value="anthropic/claude-3-5-sonnet-20240620" />
+                    <provider value="Anthropic" />
+                    <title value="Claude 3.5 Sonnet" />
+                    <usage>
+                      <list>
+                        <option value="chat" />
+                        <option value="edit" />
+                      </list>
+                    </usage>
+                  </llm>
+                </llm>
+              </chat>
+              <chat>
+                <internalId value="26ac815b-5db9-488b-be0b-ab174fbc5646" />
+                <llm>
+                  <llm>
+                    <model value="anthropic/claude-3-5-sonnet-20240620" />
+                    <provider value="Anthropic" />
+                    <title value="Claude 3.5 Sonnet" />
+                    <usage>
+                      <list>
+                        <option value="chat" />
+                        <option value="edit" />
+                      </list>
+                    </usage>
+                  </llm>
+                </llm>
+              </chat>
+              <chat>
+                <internalId value="8ab39b26-cdda-4256-878f-e0416e66bbea" />
+                <llm>
+                  <llm>
+                    <model value="anthropic/claude-3-5-sonnet-20240620" />
+                    <provider value="Anthropic" />
+                    <title value="Claude 3.5 Sonnet" />
+                    <usage>
+                      <list>
+                        <option value="chat" />
+                        <option value="edit" />
+                      </list>
+                    </usage>
+                  </llm>
+                </llm>
+              </chat>
+              <chat>
+                <internalId value="f79a288a-adc5-4d45-a069-4bf024d90236" />
+                <llm>
+                  <llm>
+                    <model value="anthropic/claude-3-5-sonnet-20240620" />
+                    <provider value="Anthropic" />
+                    <title value="Claude 3.5 Sonnet" />
+                    <usage>
+                      <list>
+                        <option value="chat" />
+                        <option value="edit" />
+                      </list>
+                    </usage>
+                  </llm>
+                </llm>
+              </chat>
+              <chat>
+                <internalId value="20bc02fd-c6b5-4590-a00b-b7012a630ef4" />
+                <llm>
+                  <llm>
+                    <model value="anthropic/claude-3-5-sonnet-20240620" />
+                    <provider value="Anthropic" />
+                    <title value="Claude 3.5 Sonnet" />
+                    <usage>
+                      <list>
+                        <option value="chat" />
+                        <option value="edit" />
+                      </list>
+                    </usage>
+                  </llm>
+                </llm>
+              </chat>
+            </list>
+          </chats>
+          <defaultLlm>
+            <llm>
+              <model value="anthropic/claude-3-5-sonnet-20240620" />
+              <provider value="Anthropic" />
+              <tags>
+                <list>
+                  <option value="gateway" />
+                  <option value="accuracy" />
+                  <option value="recommended" />
+                  <option value="free" />
+                </list>
+              </tags>
+              <title value="Claude 3.5 Sonnet" />
+              <usage>
+                <list>
+                  <option value="chat" />
+                  <option value="edit" />
+                </list>
+              </usage>
+            </llm>
+          </defaultLlm>
+        </AccountData>
+      </list>
+    </accountData>
+  </component>
+</project>

.idea/libraries/badlogicgames_gdx.xml

@@ -0,0 +1,11 @@
+<component name="libraryTable">
+  <library name="badlogicgames.gdx" type="repository">
+    <properties maven-id="com.badlogicgames.gdx:gdx:1.12.1" />
+    <CLASSES>
+      <root url="jar://$MAVEN_REPOSITORY$/com/badlogicgames/gdx/gdx/1.12.1/gdx-1.12.1.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/com/badlogicgames/gdx/gdx-jnigen-loader/2.3.1/gdx-jnigen-loader-2.3.1.jar!/" />
+    </CLASSES>
+    <JAVADOC />
+    <SOURCES />
+  </library>
+</component>

.idea/libraries/badlogicgames_gdx_backend_lwjgl3.xml

@@ -0,0 +1,62 @@
+<component name="libraryTable">
+  <library name="badlogicgames.gdx.backend.lwjgl3" type="repository">
+    <properties maven-id="com.badlogicgames.gdx:gdx-backend-lwjgl3:1.12.1" />
+    <CLASSES>
+      <root url="jar://$MAVEN_REPOSITORY$/com/badlogicgames/gdx/gdx-backend-lwjgl3/1.12.1/gdx-backend-lwjgl3-1.12.1.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/com/badlogicgames/gdx/gdx/1.12.1/gdx-1.12.1.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/com/badlogicgames/gdx/gdx-jnigen-loader/2.3.1/gdx-jnigen-loader-2.3.1.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-linux.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-linux-arm32.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-linux-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-macos.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-macos-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-windows.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl/3.3.3/lwjgl-3.3.3-natives-windows-x86.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3-natives-linux.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3-natives-linux-arm32.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3-natives-linux-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3-natives-macos.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3-natives-macos-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3-natives-windows.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-glfw/3.3.3/lwjgl-glfw-3.3.3-natives-windows-x86.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3-natives-linux.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3-natives-linux-arm32.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3-natives-linux-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3-natives-macos.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3-natives-macos-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3-natives-windows.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-jemalloc/3.3.3/lwjgl-jemalloc-3.3.3-natives-windows-x86.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3-natives-linux.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3-natives-linux-arm32.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3-natives-linux-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3-natives-macos.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3-natives-macos-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3-natives-windows.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-openal/3.3.3/lwjgl-openal-3.3.3-natives-windows-x86.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3-natives-linux.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3-natives-linux-arm32.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3-natives-linux-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3-natives-macos.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3-natives-macos-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3-natives-windows.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-opengl/3.3.3/lwjgl-opengl-3.3.3-natives-windows-x86.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3-natives-linux.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3-natives-linux-arm32.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3-natives-linux-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3-natives-macos.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3-natives-macos-arm64.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3-natives-windows.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/lwjgl/lwjgl-stb/3.3.3/lwjgl-stb-3.3.3-natives-windows-x86.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/com/badlogicgames/jlayer/jlayer/1.0.1-gdx/jlayer-1.0.1-gdx.jar!/" />
+      <root url="jar://$MAVEN_REPOSITORY$/org/jcraft/jorbis/0.0.17/jorbis-0.0.17.jar!/" />
+    </CLASSES>
+    <JAVADOC />
+    <SOURCES />
+  </library>
+</component>

.idea/markdown.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="MarkdownSettings">
+    <option name="previewPanelProviderInfo">
+      <ProviderInfo name="Compose (experimental)" className="com.intellij.markdown.compose.preview.ComposePanelProvider" />
+    </option>
+    <option name="splitLayout" value="SHOW_EDITOR" />
+  </component>
+</project>

.idea/runConfigurations/AppLoader.xml

@@ -0,0 +1,17 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="AppLoader" type="Application" factoryName="Application" nameIsGenerated="true">
+    <option name="ALTERNATIVE_JRE_PATH" value="21" />
+    <option name="MAIN_CLASS_NAME" value="net.torvald.tsvm.AppLoader" />
+    <module name="tsvm_executable" />
+    <option name="VM_PARAMETERS" value="-ea --upgrade-module-path=lib/compiler-23.1.10.jar:lib/compiler-management-23.1.10.jar:lib/truffle-compiler-23.1.10.jar:lib/truffle-api-23.1.10.jar:lib/truffle-runtime-23.1.10.jar:lib/polyglot-23.1.10.jar:lib/collections-23.1.10.jar:lib/word-23.1.10.jar:lib/nativeimage-23.1.10.jar:lib/jniutils-23.1.10.jar -XX:+UnlockExperimentalVMOptions -XX:+EnableJVMCI -XX:+UseZGC -XX:+UseDynamicNumberOfGCThreads --add-exports=java.base/jdk.internal.misc=jdk.internal.vm.compiler" />
+    <extension name="coverage">
+      <pattern>
+        <option name="PATTERN" value="net.torvald.tsvm.*" />
+        <option name="ENABLED" value="true" />
+      </pattern>
+    </extension>
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

.idea/runConfigurations/TerranBASIC.xml

@@ -0,0 +1,16 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TerranBASIC" type="Application" factoryName="Application" nameIsGenerated="true">
+    <option name="MAIN_CLASS_NAME" value="net.torvald.tsvm.TerranBASIC" />
+    <module name="TerranBASICexecutable" />
+    <option name="VM_PARAMETERS" value="--upgrade-module-path=lib/compiler-23.1.10.jar:lib/compiler-management-23.1.10.jar:lib/truffle-compiler-23.1.10.jar:lib/truffle-api-23.1.10.jar:lib/truffle-runtime-23.1.10.jar:lib/polyglot-23.1.10.jar:lib/collections-23.1.10.jar:lib/word-23.1.10.jar:lib/nativeimage-23.1.10.jar:lib/jniutils-23.1.10.jar -XX:+UnlockExperimentalVMOptions -XX:+EnableJVMCI --add-exports=java.base/jdk.internal.misc=jdk.internal.vm.compiler" />
+    <extension name="coverage">
+      <pattern>
+        <option name="PATTERN" value="net.torvald.tsvm.*" />
+        <option name="ENABLED" value="true" />
+      </pattern>
+    </extension>
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

.idea/runConfigurations/TsvmEmulator.xml

@@ -0,0 +1,16 @@
+<component name="ProjectRunConfigurationManager">
+  <configuration default="false" name="TsvmEmulator" type="Application" factoryName="Application" nameIsGenerated="true">
+    <option name="MAIN_CLASS_NAME" value="net.torvald.tsvm.TsvmEmulator" />
+    <module name="tsvm_executable" />
+    <option name="VM_PARAMETERS" value="-ea --upgrade-module-path=lib/compiler-23.1.10.jar:lib/compiler-management-23.1.10.jar:lib/truffle-compiler-23.1.10.jar:lib/truffle-api-23.1.10.jar:lib/truffle-runtime-23.1.10.jar:lib/polyglot-23.1.10.jar:lib/collections-23.1.10.jar:lib/word-23.1.10.jar:lib/nativeimage-23.1.10.jar:lib/jniutils-23.1.10.jar -XX:+UnlockExperimentalVMOptions -XX:+EnableJVMCI -XX:+UseZGC -XX:+UseDynamicNumberOfGCThreads --add-exports=java.base/jdk.internal.misc=jdk.internal.vm.compiler" />
+    <extension name="coverage">
+      <pattern>
+        <option name="PATTERN" value="net.torvald.tsvm.*" />
+        <option name="ENABLED" value="true" />
+      </pattern>
+    </extension>
+    <method v="2">
+      <option name="Make" enabled="true" />
+    </method>
+  </configuration>
+</component>

2taud.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env fish
+
+for f in *.mod; python3 mod2taud.py $f assets/disk0/home/music/(basename $f .mod).taud; end
+for f in *.MOD; python3 mod2taud.py $f assets/disk0/home/music/(basename $f .MOD).taud; end
+for f in *.s3m; python3 s3m2taud.py $f assets/disk0/home/music/(basename $f .s3m).taud; end
+for f in *.S3M; python3 s3m2taud.py $f assets/disk0/home/music/(basename $f .S3M).taud; end
+for f in *.it; python3 it2taud.py $f assets/disk0/home/music/(basename $f .it).taud; end
+for f in *.IT; python3 it2taud.py $f assets/disk0/home/music/(basename $f .IT).taud; end
+for f in *.xm; python3 xm2taud.py $f assets/disk0/home/music/(basename $f .xm).taud; end
+for f in *.XM; python3 xm2taud.py $f assets/disk0/home/music/(basename $f .XM).taud; end
+for f in *.mon; python3 mon2taud.py $f assets/disk0/home/music/(basename $f .mon).taud; end
+for f in *.MON; python3 mon2taud.py $f assets/disk0/home/music/(basename $f .MON).taud; end

CLAUDE.md

@@ -18,6 +18,31 @@ Documentation for TSVM and TVDOS are available on `./doc/*.tex` as machine-reada
 
 Documentatino for TSVM architecture is available on `terranmon.txt`
 
+## Reference Materials
+
+Third-party source-code references that inform TSVM implementations live in
+`reference_materials/<topic>/`. Each topic folder has a `README.md` that
+summarises the takeaway and points back into the verbatim source files.
+**Consult these before reimplementing tracker / codec / DSP behaviour from
+memory** — TSVM aims to match the audible behaviour of the originals.
+
+Current topics:
+
+- `reference_materials/tracker_filter/` — Impulse Tracker / OpenMPT / Schism
+  Tracker resonant low-pass filter source. Defines the cutoff formula, the
+  resonance damping curve, and the **IIR-only 2-pole topology** (NOT a
+  biquad — no feedforward x[n−1] / x[n−2] terms) that `AudioAdapter.kt` uses
+  for Taud playback.
+- `reference_materials/ft2-clone` — Modernised clone for the original FastTracker 2
+- `reference_materials/impulse-tracker` — The original source code for ImpulseTracker
+- `reference_materials/MilkyTracker` — FastTracker 2 compatible tracker
+- `reference_materials/schismtracker` — Open-source re-implementation of ImpulseTracker
+- `reference_materials/pt2-clone` — Open-source re-implementation of ProTracker 2
+
+When fetching new references, copy the relevant upstream files verbatim into
+a topic folder, write a `README.md` summarising the relevant maths /
+algorithms with file:line citations, and add an entry here.
+
 ## Architecture
 
 ### Core Components
@@ -68,12 +93,12 @@ Use the build scripts in `buildapp/`:
 
 ### Prerequisites
 
-1. Download JDK 17 runtimes to `~/Documents/openjdk/*` with specific naming:
-   - `jdk-17.0.1-x86` (Linux AMD64)
-   - `jdk-17.0.1-arm` (Linux Aarch64) 
-   - `jdk-17.0.1-windows` (Windows AMD64)
-   - `jdk-17.0.1.jdk-arm` (macOS Apple Silicon)
-   - `jdk-17.0.1.jdk-x86` (macOS Intel)
+1. Download JDK 21 runtimes to `~/Documents/openjdk/*` with specific naming:
+   - `jdk-21.0.1-x86` (Linux AMD64)
+   - `jdk-21.0.1-arm` (Linux Aarch64) 
+   - `jdk-21.0.1-windows` (Windows AMD64)
+   - `jdk-21.0.1.jdk-arm` (macOS Apple Silicon)
+   - `jdk-21.0.1.jdk-x86` (macOS Intel)
 
 2. Run `jlink` commands to create custom Java runtimes in `out/runtime-*` directories
 
@@ -91,6 +116,16 @@ Use the build scripts in `buildapp/`:
 - `My_BASIC_Programs/`: Example BASIC programs for testing
 - TVDOS filesystem uses custom format with specialised drivers
 
+### TSVM JavaScript Source Encoding
+
+**Do not normalise `\uXXXX` or `\xXX` escapes in .js / .mjs files that run inside
+TSVM.** TSVM's character set is not Unicode, and the JS string literal parser
+behaves differently for raw bytes vs. escape sequences. Both forms appear in
+existing code intentionally — leave each one as-is. When writing new content,
+prefer raw UTF-8 characters in string literals (e.g. write the character `ù`
+directly, rather than a `\uXXXX`-style escape) unless you are matching a
+pattern already established in the surrounding code.
+
 ## Videotron2K
 
 The Videotron2K is a specialised video display controller with:
@@ -130,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
@@ -393,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/VTMGR.SYS`. 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/VTMGR.SYS` (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.

README.md

@@ -1,8 +1,222 @@
 ![tsvm](tsvm_screenshot.png)
 
-**tsvm** /tiː.ɛs.viː.ɛm/ is a virtual machine with the architecture that mimics the 8-bit era of
-computers, and runs programs written in Javascript.
+# tsvm
 
-**tsvm** repository includes the virtual machine itself, the reference BIOS
-implementation and a DOS; BASIC is provided by the [TerranBASIC](https://github.com/curioustorvald/TerranBASIC)
-repository.
+**tsvm** /tiː.ɛs.viː.ɛm/ is a fantasy computer platform: a virtual machine whose
+architecture is inspired by the 8-bit and early 16-bit home computers, built
+from the ground up around running JavaScript as its native machine code.
+
+What started as "an 8-bit-flavoured VM that runs JS" has grown into a complete,
+self-hosted retro computing ecosystem — with its own BIOS, operating system,
+filesystem, video and audio codecs, video display coprocessor with its own
+assembly language, tracker music format, and a stack of userland tools that
+together come closer to a small alternate-history computer line than a
+single-binary emulator.
+
+This repository contains the virtual machine core, the reference BIOS
+implementations, the **TVDOS** operating system, the **Videotron2K** video
+display controller, hardware-accelerated codec backends for the **TEV / TAV /
+TAD** media formats, and the multi-platform packaging scripts. The
+[TerranBASIC](https://github.com/curioustorvald/TerranBASIC) repository
+provides the matching BASIC dialect that ships on the system disk.
+
+## What's actually in here
+
+### The virtual machine
+
+- **VM core** (`tsvm_core/`) — memory model, peripheral bus, MMIO, JS
+  sandboxing through GraalVM, watchdog, DMA engine, and cooperative scheduling.
+  Up to 8 hot-pluggable peripheral slots, each with a dedicated MMIO window
+  and memory-space window mapped into the VM's negative address range.
+- **Multiple BIOS implementations** (`assets/bios/`) — including the reference
+  `tsvmbios.js`, an OpenBIOS variant, the TBM-BIOS for TerranBASIC machines,
+  and the Pip-Boy-style `pipboot.rom`. BIOSes are first-class swappable
+  components, not a fixed boot blob.
+- **Reference monitor / debugger** (`mon.js`) for poking at memory and
+  peripherals from a running machine.
+- **Multi-platform packaging** (`buildapp/`) — scripts to produce Linux x86_64
+  / ARM64 AppImages, macOS Intel / Apple Silicon bundles, and Windows builds,
+  each with its own `jlink`-trimmed JDK 21 runtime.
+
+### Peripherals (the "hardware")
+
+Living under `tsvm_core/src/net/torvald/tsvm/peripheral/`:
+
+- **Graphics adapters** — the standard `GraphicsAdapter`, plus `TexticsAdapter`
+  for text-mode framebuffers, `ExtDisp` for external displays, and a
+  `RemoteGraphicsAdapter` for networked rendering.
+- **Audio devices** — `AudioAdapter` (the main programmable sound chip with
+  PCM channels, an Impulse Tracker-style resonant low-pass filter, and a
+  hardware-accelerated **TAD** decoder), `OpenALBufferedAudioDevice`, and the
+  `MP2Env` MPEG audio environment.
+- **Disk drives** — `TevdDiskDrive` (TEVD custom filesystem),
+  `ClusteredDiskDrive`, `TestDiskDrive`, and a latency-simulator script for
+  testing slow-storage behaviour.
+- **Networking and serial** — `HttpModem`, `HSDPA` / `HostFileHSDPA` for
+  high-speed packet I/O, `SerialStdioHost`, `BlockTransferInterface` /
+  `BlockTransferPort`.
+- **Terminals and displays** — `TTY`, `GlassTty`, `TermSim`, and a
+  `CharacterLCDdisplay` for HD44780-flavoured projects.
+- **Memory expansion** — `RamBank` for bank-switched memory, plus a
+  programmable `TestFunctionGenerator`.
+
+### Videotron2K — the video coprocessor
+
+Videotron2K is a programmable video display controller with its **own
+assembly-like language**, six general registers (`r1`–`r6`), special registers
+(`tmr`, `frm`, `px`, `py`, `c1`–`c6`), a scene-based programming model, and
+conditional postfixes (`zr`, `nz`, `gt`, `ls`, `ge`, `le`). Programs declare
+`SCENE` blocks and dispatch them with `perform`. Drawing primitives include
+`plot`, `fillin`, `fillscr`, and `goto`. See `Videotron2K.md` and the VDC
+implementation under `tsvm_core/.../vdc/`.
+
+### TVDOS — the operating system
+
+`assets/disk0/tvdos/` is a complete DOS-style userland:
+
+- **Kernel and drivers** — `TVDOS.SYS`, `HSDPADRV.SYS`, `hyve.SYS`,
+  installable drivers under `moviedev/` and `tuidev/`.
+- **Custom filesystem** — TEVD, with the on-disk format documented in
+  `tvdos/filesystem.md`.
+- **Internationalisation** — Colemak / Dvorak / QWERTY keymaps and an `i18n/`
+  resource tree.
+- **Userland binaries** (`tvdos/bin/`) — a shell (`command.js`), file tools
+  (`hexdump`, `less`, `tee`, `touch`, `printfile`, `writeto`, `defrag`,
+  `lfs`, `drives`), an editor (`edit.js`), a file manager (`zfm.js`), a
+  network fetcher (`geturl`), gzip/Zstd helpers, palette tools, and a battery
+  of media players (`playmp2`, `playpcm`, `playwav`, `playmv1`, `playtev`,
+  `playtav`, `playtad`, `playucf`).
+- **Taut tracker** — a full in-VM tracker (`taut.js`,
+  `taut_instredit.js`, `taut_sampleedit.js`, `taut_notationedit.js`,
+  `taut_fileop.js`) with its own font and chrome assets.
+
+### Codecs and media formats
+
+tsvm ships a small but serious codec lab. Encoders are written in C and live
+in `video_encoder/`; decoders are split between JavaScript players in TVDOS
+and hardware-accelerated Kotlin backends in the VM core.
+
+- **iPF (Type 1 / 2 / 1-delta)** — picture and legacy movie format. Encoders:
+  `encodeipf.js`, `encodemov.js`, `encodemov2.js`. Documented in
+  `terranmon.txt`.
+- **TEV (TSVM Enhanced Video)** — modern DCT codec with motion compensation,
+  16×16 blocks, YCoCg-R 4:2:0, and either quality-mode or bitrate-mode rate
+  control. Encoder: `video_encoder/encoder_tev.c`. Decoder: `playtev.js`,
+  with `tevDecode` / `tevIdct8x8` / `tevMotionCopy8x8` accelerated in
+  `GraphicsJSR223Delegate.kt`.
+- **TAV (TSVM Advanced Video)** — successor to TEV based on the Discrete
+  Wavelet Transform. Five wavelet types (5/3 reversible, 9/7 irreversible,
+  CDF 13/7, DD-4, Haar), 6-level decomposition, EZBC sparsity coding,
+  perceptual quantisation, and an optional **3D temporal DWT** that encodes
+  whole groups of pictures as one unified wavelet tree. Includes a packet
+  inspector (`tav_inspector.c`) and coefficient visualiser
+  (`tav_visualise_coefficients.c`).
+- **TAD (TSVM Advanced Audio)** — perceptual audio codec at 32 kHz stereo,
+  using CDF 9/7 wavelets, M/S decorrelation, gamma compression, pre-emphasis,
+  EZBC, and Zstd. Achieves ~2.5:1 compression vs. PCMu8 at quality 3 while
+  preserving the full 0–16 kHz band. Designed to be embeddable inside TAV so
+  audio chunks can align with video GOP boundaries.
+- **Taud** — tracker module format with conversion tools from
+  the major formats: `it2taud.py` (Impulse Tracker), `mod2taud.py`
+  (ProTracker / FastTracker), `s3m2taud.py` (Scream Tracker 3), plus
+  `2taud.sh` and shared helpers in `taud_common.py`. Note effects are
+  documented in `TAUD_NOTE_EFFECTS.md`. The `AudioAdapter` runs the same
+  IIR-only 2-pole resonant low-pass topology used by Impulse Tracker /
+  OpenMPT / Schism.
+- **MP2** — reference MPEG-1 Layer II environment via `MP2Env.kt` and
+  `playmp2.js`.
+
+### Languages and runtimes
+
+- **JavaScript** is the VM's native code, executed by GraalVM in a sandboxed
+  context with a curated set of host bindings (graphics, audio, filesystem,
+  DMA, compression, networking, low-level peek/poke).
+- **TerranBASIC** is provided by the
+  [TerranBASIC](https://github.com/curioustorvald/TerranBASIC) repository and
+  shipped as `tbas` on the system disk. The `TerranBASICexecutable/` subproject
+  packages a BASIC-only flavour of the machine.
+- **Videotron2K assembly** for VDC programs.
+
+### Documentation
+
+- `terranmon.txt` — the architecture reference (memory map, peripheral
+  protocol, codec bitstreams).
+- `doc/*.tex` — machine-readable LaTeX sources for the TSVM and TVDOS manuals,
+  built with `doc/makepdf.sh`.
+- `Videotron2K.md` — VDC programming guide.
+- `TAUD_NOTE_EFFECTS.md` — tracker effect reference.
+- `CLAUDE.md` — a condensed map of the project for collaborators (and
+  language-model assistants) working in the tree.
+
+## Building and running
+
+### Prerequisites
+
+JDK 21 runtimes laid out under `~/Documents/openjdk/` with platform-specific
+names:
+
+- `jdk-21.0.1-x86` — Linux AMD64
+- `jdk-21.0.1-arm` — Linux Aarch64
+- `jdk-21.0.1-windows` — Windows AMD64
+- `jdk-21.0.1.jdk-x86` — macOS Intel
+- `jdk-21.0.1.jdk-arm` — macOS Apple Silicon
+
+`jlink` is then used to produce trimmed runtimes under `out/runtime-*`.
+
+### Common entry points
+
+- **Run the emulator** — `TsvmEmulator.java` (in `tsvm_executable/`).
+- **Run TerranBASIC-only build** — `TerranBASIC.java` (in
+  `TerranBASICexecutable/`).
+- **Package an installable bundle** — pick the right script in `buildapp/`:
+    - `build_app_linux_x86.sh`
+    - `build_app_linux_arm.sh`
+    - `build_app_mac_x86.sh`
+    - `build_app_mac_arm.sh`
+    - `build_app_windows_x86.sh`
+- **Build C encoders** — in `video_encoder/`: `make` (TEV), `make tav`,
+  `make tad`.
+
+### Encoding sample media
+
+```bash
+# Quality-mode TEV encode
+./encoder_tev -i input.mp4 -o clip.tev -q 3
+
+# TAV with 9/7 wavelet, quality 4
+./encoder_tav -i input.mp4 -w 1 -q 4 -o clip.tav
+
+# TAV with 3D temporal DWT (GOP-unified encoding)
+./encoder_tav -i input.mp4 --temporal-dwt -o clip.tav
+
+# TAD audio at the highest quality
+./encoder_tad -i input.mp4 -o track.tad -q 5
+```
+
+Then, inside TVDOS:
+
+```
+A:\> playtev clip.tev
+A:\> playtav clip.tav
+A:\> playtad track.tad
+```
+
+## Repository layout
+
+```
+tsvm_core/             VM core, peripherals, VDC, JS bindings (Kotlin)
+tsvm_executable/       Main emulator GUI (LibGDX)
+TerranBASICexecutable/ For creatingTerranBASIC executable
+assets/bios/           BIOS ROMs and source
+assets/disk0/          Boot disk image, including all of TVDOS
+video_encoder/         C encoders, decoder libs, inspectors (TEV / TAV / TAD)
+ipf_encoder/           Reference iPF encoder
+doc/                   LaTeX sources for the TSVM / TVDOS manuals
+buildapp/              Per-platform packaging scripts
+My_BASIC_Programs/     Example BASIC programs
+*.py, *.sh, *.kts      Conversion tools and ad-hoc utilities
+```
+
+## Licence
+
+See `COPYING`.

TerranBASICexecutable/TerranBASICexecutable.iml

@@ -10,5 +10,7 @@
     <orderEntry type="module" module-name="tsvm_core" />
     <orderEntry type="library" name="TerranVirtualDisk" level="project" />
     <orderEntry type="library" name="lib" level="project" />
+    <orderEntry type="library" name="badlogicgames.gdx" level="project" />
+    <orderEntry type="library" name="badlogicgames.gdx.backend.lwjgl3" level="project" />
   </component>
 </module>

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

@@ -122,8 +122,39 @@ class VMGUI(val loaderInfo: EmulInstance, val viewportWidth: Int, val viewportHe
     private var rebootRequested = false
 
     private fun reboot() {
-        vmRunner.close()
-        coroutineJob.interrupt()
+        // Order is critical: stop ALL execution first, then dispose peripherals
+        // before re-initialising. Without this, the old JS thread races the new
+        // one on shared VM memory / IO state and can SIGSEGV on disposed peripherals.
+
+        // 1. Stop parallel/child contexts. park() interrupts and joins them.
+        vm.park()
+        vm.poke(-90L, -128)
+
+        // 2. Interrupt the main runner thread and cancel the GraalVM context.
+        if (::coroutineJob.isInitialized) coroutineJob.interrupt()
+        try { if (::vmRunner.isInitialized) vmRunner.close() } catch (_: Throwable) {}
+
+        // 3. Wait for the main runner thread to actually finish.
+        if (::coroutineJob.isInitialized && coroutineJob !== Thread.currentThread()) {
+            try {
+                coroutineJob.join(2000L)
+                if (coroutineJob.isAlive) {
+                    System.err.println("[VMGUI] runner ${vm.id} did not exit within 2s; proceeding anyway")
+                    coroutineJob.interrupt()
+                }
+            }
+            catch (_: InterruptedException) {
+                Thread.currentThread().interrupt()
+            }
+        }
+
+        // 4. Now it's safe to release native resources held by peripherals.
+        for (i in 1 until vm.peripheralTable.size) {
+            try {
+                vm.peripheralTable[i].peripheral?.dispose()
+            }
+            catch (_: Throwable) {}
+        }
 
         vm.init()
         init()

assets/bios/tsvmbios.js

@@ -1,5 +1,5 @@
 con.reset_graphics();con.curs_set(0);con.clear();
-graphics.resetPalette();graphics.setBackground(0,0,0);
+graphics.resetPalette();graphics.setPalette(0, 0, 0, 0, 15);graphics.setBackground(0,0,0);
 
 let logo = gzip.decomp(base64.atob("H4sICJoBTGECA3Rzdm1sb2dvLnJhdwDtneu2nCoQhPf7v6xLEMUL5lxyVk6yhxm7mmZGpfqnK7uC+gkN1TA/fhTFF+Ni8eOjwedPXsgLeSEvDPLCIC8M8sIgL+SFvJAX8kJeGOSFQV4Y5IVBXsgLeSEv5IW8MMgLow1e1i4XfH/kJR8deSEvcl48eSEvAC+RvJAXgJedvJAXOS9DR17Ii5yXSF7IC8DLTl7Ii5yX0JEX8iLnZSUv5EXOy7Nsl7yQF6h7IS/kBcheyAt5eYx+Jy/kRc7L0pEX8iLmZezIC3kR8zJ05IW8iHnxO3khL2JeDnAhL+Tlj8HoABfyQl6kqS55IS9/rrssHXkhL1Jewt6RF/Ii5GVYO4vYctouxGVLe2cXXvHg3TeN3eeu6rR9lRafl5ewGr3I6RHEOXXmMSse/PeSwTV7Vac9V2nxSXkZotmnv/ffvulYAZZ//h8HP/f+e0tC9qpK2+01WnxSXtZq372bu1oxwc/9u+mesld12lOVFp+Ul65SXtHHrl5s8HNfs+9vNdHeqrT4/rz8/kxC6mrGUJiR/hwfvIn2UKXFDfAyIhlgWSyFGenyopWo9lKlxffn5f9s122VcUHzx4casCF7VaXt9hotboCX+OsJpq56ROipj9mRczTRjlVa3AAvTmhym0QqykjHl3kqpp2qtPj+vKxY/1waoSAj/TlyDibaoUqLG+AlvG8w+h1PTUY6H+SpiPZapcX35yX18sWIN5tIDz2eP+oH5dq+Sosb4GV6z0RaY8lM2Q99MtGeq7S4AV4cOJqbm1XyjDQc5qli7X6v0uL787J8PfHv6sVobh3h2mOVFjfAi4fWIt5qIq3ZhZDVRHur0uL787J95auPTmAiPSwHOckikUx7qNLiBngZ35zsApZMzP5VNNFeqrT4/rz8zOTe3L3ILBnIOgK14aVJ3ES6Jy/z+7OX3+bwmHXUy/JUifZUpcUN8OIhJ+WtJhJmHWHaqUqL78/Lqkr+3mIi+ezI6U20Q5UWN8BL+ES2K7Nk5uzIOZtor1VafH9e/rOO0vt56RyakXp5nnqoXaXFDfAyfWLx5fe1N3lGugF5agQn6jYtboCXt1tHj664NCMdgZ7wQFvpfaS+dV6Wr8/MpgWWzJB9WYOJ9lilxQ3wMujWOt9hIi3ZwWAx0d6qtPj+vGyFz89k6UeY7TpsVdYbFUrJVS+wfxrBp2DxalIUf0gwXMytI5n2Ujp+t87LbrsQLk0TXlkye3adSG76vNAuqGqHTKT78vL6L3stL4cvZpIXSvXoPG4ytI503w55QeNoLTaJh7IJzrOSoXWkM5E4HqFxmFgO5tbRsXaZVzaQl2r57rFNswo7pkXhcq2G1pHKRLovL2Xz6T1tSwxOZQM7WaGUhwv6n2qXeh+OvNis16V5wBfeo6xQSrUqGw2tI42JdF9erPyAFB2onLdkZIVSq0b7kOBN1eK2eDH0G2eH9f5BkJHm99jvXqN9eKuDRrUxXkzrGWKPDHWr2jqKKu2jTmlRqTbGi229VArI7NVrC6W8Rlsww1eoNseLcT3mDKA4H2ZT69OruLZkBRFXbY4X63rvzYlX3x93ssv22AeNdi9xKPAWN8eLeQFvcmoTSWYd/XsV1j5EwZXZXs3wYl5ht3vpELAdZKTTi6uo9iYaalDVBnmxr/j+Zf2DJpLPLqjmr6LawlRWbXu1w0uFHUi/hiSsbEpWKLWotBdhx1FS6NUILxW2lGzS6mr3KiMdnl9FtQ/vcdSotslLjT0CMzApwayjDZrwwFO13iTjvTcvNc4jC7iJJLOORo1BBZifOturKV5qbFr777ECRo/QOurlC7ZBfoNeo9osLzU23Ue0bEp2PPOsKslCire0hV4t8VJjG5LDvmyxdfSF9xpQnwH0Re3yUuE8+BkzkWTHM6/Q0vSsKj43MJFuz0uN35tw0MxEbh3Bsx5wzmNgIt2flwq/ZxNlII7ZbDe/x/7b5ESoDW6eE6o2zov9kJSQlVXZ8cwRrD7eVGu20rXgtnmx/z2+QebcDLn1V/f19CriCg3SfwSrkpdatVOSzxuzjuTzukXVXRSbSI3wYvx7wklmyfydPz6svw7ZVdnhcPtJThtPRwSq5OXnVMLUS3LS6cmYJW18Oe2VaiumO8UmUjO8/J0zGA5KQbj80cv22E+KITT1muWUY1Xy8j8x0WpUisLl1Sk7wfWvp71C7cMO02tUA3n5Y4YwmyCzCC2ZlP3kZ9G66pH20dCymp4W0Cgv//QyIS5bKlvE25T+t3++897cWw86VUde8OgnoS+TFJhNwlWysp4wKVUjedHEa2B2XQXfUaGUZXVgVKq+znjJy7MeRvY/O/wHWQfpmkeRU/r0FMMyE+navPQf5wU6ZubZHvtnUXKEzaJWXa/MS61T6KzGI2jXrc9aR77Kjt5Br+ovzEu1U+iM8l2kgO/5Hnv74sCtQHW+MC8fOtUdeB3yk29D1joK6k5O2/OWlE2dnZflnLwsgCXzZ58UhNNeTBvyDUtMpLPzEs/JS1TUSrzaY29dhzEXqW7X5SWck5eAWDKwdQRrQylr0d77s/PizsmLw3Os/PHMS5X8bStUXS7Ly0d+tRNca5edoft6j/2z0P1q2lio+rzXOz0v8xl5mfGs9GCPvWnGe1gld6gaL8vLcEZeBjwpx6yjsoQ/Fqumy/JyxgEp4UkWaB2VJXCuXDVclpcTzqgjWoQk2WP/LPCfHlkNVNfL8nLCGZLDZ/2odVSyohAMVHd/VV7Ol/E+9gqHpdcpuxAvOoUdPvNIdO5Pr9x7fwFe3Om7F6ElA1lHehNpMlF9klpdgJezZTBRw/SIWkf678XZqI6X5aU/1RQp391LtqauAvDKPdfFSHW7LC/nMpGC1pIBrSOtieStVIfL8nKmlHdWWzJR2RFgJtJmprpcl5fzlE1takvGJ8n3W2wijWaq2f7vIry4k6QwyaktmUXdESAm0t7bqU7X5aXGKXQaI8/ZjZnyjgDRng1V04V5qXAKnQIXb1fatCOV6nJtb6kaLszLCYak5AyNHqQjkGuvpqrrlXmxP4UOTXWd5azfQ/cu1Q6mqpnh90K8fHhafdghQMuKG3bnQu3U26rGa/NifAodNBYJvlzE6Angncu0J2PVxyTrWrwYn0IHeEaSDxcwenZ0X6ZM21mrjhfnxfYUOvFQJHwPcqMnwvct0V7MVbfL82J5Cp1sJIrir1Zca7w7+K4l2oO9qr8+L19mp9AJYJmhdyCdwa2Kez7W3iqozrfg5cvmFLpXPUDalhjQbkBq9ATFDR9rjxVUv/eEl+WF8ZEgLwzywiAvDPLC509eyAt5IS8M8sIgLwzywiAv5IW8kBfyQl4Y5IVBXhjkhUFeyAt5IS/khbwwyAuDvDDIC+OWvPwFgd7gz8BmAQA="));
 
@@ -77,7 +77,7 @@ tmr = sys.nanoTime();
 while (sys.nanoTime() - tmr < 2147483648) sys.spin();
 // clear screen
 graphics.clearPixels(255);con.color_pair(239,255);
-con.clear();con.move(1,1);
+con.clear();con.move(1,1);graphics.resetPalette();
 
 ///////////////////////////////////////////////////////////////////////////////
 

assets/disk0/!BOOTSEC

@@ -1 +1 @@
-let p=_BIOS.FIRST_BOOTABLE_PORT;com.sendMessage(p[0],"DEVRST\x17");com.sendMessage(p[0],'OPENR"tvdos/hyve.SYS",'+p[1]);let r=com.getStatusCode(p[0]);if(0==r)if(com.sendMessage(p[0],"READ"),r=com.getStatusCode(p[0]),0==r){let g=com.pullMessage(p[0]);eval(g)}else println("I/O Error");else println("TVDOS.SYS not found");println("Shutting down...");println("It is now safe to turn off the power")
+let p=_BIOS.FIRST_BOOTABLE_PORT;com.sendMessage(p[0],"DEVRST\x17");com.sendMessage(p[0],'OPENR"tvdos/TVDOS.SYS",'+p[1]);let r=com.getStatusCode(p[0]);if(0==r)if(com.sendMessage(p[0],"READ"),r=com.getStatusCode(p[0]),0==r){let g=com.pullMessage(p[0]);eval(g)}else println("I/O Error");else println("TVDOS.SYS not found");println("Shutting down...");println("It is now safe to turn off the power")

assets/disk0/AUTOEXEC.BAT

@@ -1,10 +1,11 @@
-echo "Starting TVDOS..."
-
-rem put set-xxx commands here:
-set PATH=\tvdos\installer;\tvdos\tuidev;$PATH
-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/COPYING

@@ -1,4 +1,4 @@
-Copyright (c) 2020-2024 CuriousTorvald
+Copyright (c) 2020-2026 CuriousTorvald
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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/etc/motd

@@ -1,3 +1,3 @@
-TVDOS (c) 2020-2024 CuriousTorvald
+TVDOS (c) 2020-2026 CuriousTorvald
 
 TVDOS is provided "as is", without warranty of any kind; in no event shall the authors or copyright holders be liable for any claim, damages or other liabilities. Run 'less COPYING' for more information.

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/nettest.js

@@ -1,11 +1,13 @@
-let url="http:localhost/testnet/test.txt"
+/*let url="https:raw.githubusercontent.com/curioustorvald/hopper-mirror/refs/heads/master/aa.hop.per"
 
 let file = files.open("B:\\"+url)
 
 if (!file.exists) {
     printerrln("No such URL: "+url)
     return 1
-}
+}*/
 
-let text = file.sread()
+let net = require("A:/tvdos/include/net.mjs")
+let text = net.fetchText("https://raw.githubusercontent.com/curioustorvald/hopper-mirror/refs/heads/master/aa.hop.per")
+if (text === null) { printerrln("No such URL"); return 1 }
 println(text)

assets/disk0/tbas/basic.js

@@ -32,7 +32,7 @@ if (exec_args !== undefined && exec_args[1] !== undefined && exec_args[1].starts
     return 0
 }
 
-const THEVERSION = "1.2.1"
+const THEVERSION = "1.2.2"
 
 const PROD = true
 let INDEX_BASE = 0
@@ -4197,7 +4197,7 @@ bF.load = function(args) { // LOAD function
     if (args[1] === undefined) throw lang.missingOperand
     var fileOpened = fs.open(args[1], "R")
 
-
+    serial.printerr('load '+args[1])
     if (replUsrConfirmed || cmdbuf.length == 0) {
         if (!fileOpened) {
             fileOpened = fs.open(args[1]+".BAS", "R")
@@ -4241,7 +4241,7 @@ bF.yes = function() {
     }
 }
 bF.catalog = function(args) { // CATALOG function
-    if (args[1] === undefined) args[1] = "\\"
+    if (args[1] === undefined) args[1] = BASIC_HOME_PATH
     var pathOpened = fs.open(args[1], 'R')
     if (!pathOpened) {
         throw lang.noSuchFile
@@ -4251,6 +4251,57 @@ bF.catalog = function(args) { // CATALOG function
     com.sendMessage(port, "LIST")
     println(com.pullMessage(port))
 }
+// Load a file by absolute disk path (bypasses BASIC_HOME_PATH).
+// Used by COMPILE to fetch /tbas/compile.js.
+bF._slurpAbsolute = function(path) {
+    var port = _BIOS.FIRST_BOOTABLE_PORT
+    com.sendMessage(port[0], "FLUSH")
+    com.sendMessage(port[0], "CLOSE")
+    com.sendMessage(port[0], 'OPENR"' + path + '",' + port[1])
+    if (com.getStatusCode(port[0]) != 0) return undefined
+    com.sendMessage(port[0], "READ")
+    if (com.getStatusCode(port[0]) >= 128) return undefined
+    var s = com.pullMessage(port[0])
+    com.sendMessage(port[0], "FLUSH"); com.sendMessage(port[0], "CLOSE")
+    return s
+}
+bF.compile = function(args) { // COMPILE "OUT.JS" -- transpile cmdbuf to JS
+    if (args[1] === undefined) {
+        println("Usage: COMPILE \"out.js\""); return
+    }
+    if (cmdbuf.length === 0) {
+        println("No program loaded"); return
+    }
+    if (bS._compileImpl === undefined) {
+        // Lazy-load compile.js from /tbas/compile.js
+        var src = bF._slurpAbsolute("/tbas/compile.js")
+        if (src === undefined) {
+            println("Cannot load /tbas/compile.js")
+            return
+        }
+        try { eval(src) } catch (e) {
+            println("Failed to load compiler: " + e); return
+        }
+        if (bS._compileImpl === undefined) {
+            println("compile.js loaded but did not define bS._compileImpl"); return
+        }
+    }
+    var outpath = args[1]
+    // Strip surrounding quotes if any
+    if ((outpath.charAt(0) === '"' || outpath.charAt(0) === "'") &&
+        outpath.charAt(outpath.length - 1) === outpath.charAt(0)) {
+        outpath = outpath.substring(1, outpath.length - 1)
+    }
+    // Default to .js extension if missing
+    if (!/\.[A-Za-z0-9]+$/.test(outpath)) outpath += ".js"
+    try {
+        var n = bS._compileImpl(outpath)
+        println("Wrote " + n + " bytes to " + outpath)
+    } catch (e) {
+        serial.printerr(e + "\n" + (e.stack || ""))
+        println("Compile error: " + e)
+    }
+}
 Object.freeze(bF)
 
 if (exec_args !== undefined && exec_args[1] !== undefined) {

assets/disk0/tbas/compile.js

@@ -0,0 +1,564 @@
+// Terran BASIC -> JavaScript compiler
+// Loaded into basic.js's context by `bF.compile`. Re-uses bF._interpretLine
+// (tokeniser + elaborator + parser + pruner) verbatim and emits a self-
+// contained JS program that does its work via `let bS = require("tbas")`.
+//
+// On load, attaches `bS._compileImpl` to the live bS object.
+
+;(function() {
+
+// ---------- helpers ----------------------------------------------------------
+
+function isValidJsId(s) {
+    return /^[A-Z_][A-Z0-9_]*$/i.test(s)
+}
+function varRef(name) {
+    const u = String(name).toUpperCase()
+    return isValidJsId(u) ? `bS.__state.vars.${u}` : `bS.__state.vars[${JSON.stringify(u)}]`
+}
+function jsLit(v) { return JSON.stringify(v) }
+
+// Resolve a literal AST node down to a raw JS value at compile time. Used
+// for harvesting DATA constants. Only constant-propagatable types are
+// permitted; otherwise compile-time evaluation fails.
+function literalValue(node) {
+    if (!node) return undefined
+    switch (node.astType) {
+        case "num":    return Number(node.astValue)
+        case "string": return String(node.astValue)
+        case "bool":   return Boolean(node.astValue)
+        case "null":   return undefined
+        case "lit":    return String(node.astValue) // bare identifier in DATA: keep as string
+        default:
+            throw Error("DATA: unsupported literal node type: " + node.astType)
+    }
+}
+
+// Returns the maximum varIndex used at the immediate scope of a lambda body,
+// hence its arity.
+function lambdaArity(body) {
+    let maxIdx = -1
+    function walk(t, level) {
+        if (!t || !t.astType) return
+        if (t.astType === "defun_args" && t.astValue[0] === level) {
+            if (t.astValue[1] > maxIdx) maxIdx = t.astValue[1]
+        }
+        // descend into nested usrdefun (its body lives in astValue, not leaves)
+        if (t.astType === "usrdefun" && t.astValue && t.astValue.astLeaves !== undefined) {
+            walk(t.astValue, level + 1)
+        }
+        // generic descent
+        if (t.astLeaves) {
+            for (let i = 0; i < t.astLeaves.length; i++) walk(t.astLeaves[i], level)
+        }
+    }
+    walk(body, 0)
+    return maxIdx + 1
+}
+
+// ---------- expression lowering ---------------------------------------------
+
+// `depth` tracks the number of enclosing lambdas during emission. When we
+// emit a lambda we increment it; defun_args [d, i] becomes _aN_i where
+// N = depth - 1 - d  (the absolute lambda index of the binding scope).
+function compileExpr(tree, depth) {
+    if (tree === undefined || tree === null) return "undefined"
+
+    // Empty parens / wrapper node: descend into the single child
+    if (tree.astType === "null") {
+        if (tree.astLeaves && tree.astLeaves[0] !== undefined) return compileExpr(tree.astLeaves[0], depth)
+        return "undefined"
+    }
+    if (tree.astValue === undefined && tree.astLeaves && tree.astLeaves.length === 1) {
+        return compileExpr(tree.astLeaves[0], depth)
+    }
+
+    switch (tree.astType) {
+        case "num":    return String(Number(tree.astValue))
+        case "string": return jsLit(String(tree.astValue))
+        case "bool":   return tree.astValue ? "true" : "false"
+        case "lit":    return compileLit(tree)
+        case "defun_args": {
+            const d = tree.astValue[0], i = tree.astValue[1]
+            const scope = depth - 1 - d
+            if (scope < 0) throw Error("defun_args refers to a scope outside the program (depth=" + depth + ", d=" + d + ")")
+            return "_a" + scope + "_" + i
+        }
+        case "usrdefun": return compileLambdaExpr(tree, depth)
+        case "array":    return compileArrayRef(tree, depth)
+        case "function": return compileFunctionExpr(tree, depth)
+        case "op":       return compileOpExpr(tree, depth)
+        default:
+            throw Error("Cannot compile expression node of type: " + tree.astType + " (value=" + tree.astValue + ")")
+    }
+}
+
+function compileLit(tree) {
+    const name = String(tree.astValue).toUpperCase()
+    // Built-in zero-arg / pass-as-value functions: when a builtin name is
+    // referenced as a value (e.g. assigned to a variable for later use as a
+    // higher-order arg), emit a JS function reference. For a plain variable
+    // read, emit the vars table lookup.
+    // Heuristic: if the name matches a builtin we know about, prefer the
+    // function; otherwise, vars lookup.
+    if (RUNTIME_BUILTINS.has(name)) {
+        return "bS." + (isValidJsId(name) ? name : `[${jsLit(name)}]`)
+    }
+    return varRef(name)
+}
+
+function compileArrayRef(tree, depth) {
+    // tree.astValue = array variable name; tree.astLeaves = index expressions
+    if (!tree.astLeaves || tree.astLeaves.length === 0) {
+        return varRef(tree.astValue)
+    }
+    const indices = tree.astLeaves.map(l => compileExpr(l, depth))
+    return `bS.__arrGet(${varRef(tree.astValue)}, [${indices.join(",")}])`
+}
+
+function compileFunctionExpr(tree, depth) {
+    const name = String(tree.astValue).toUpperCase()
+
+    if (name === "PRINT" || name === "EMIT") {
+        // PRINT/EMIT used as expression — emit as IIFE returning undefined
+        return "(" + compilePrintLike(tree, name, depth) + ", undefined)"
+    }
+    // user function call by name: <varname>(args)  — when astType is "function"
+    // and astValue is a string that matches a variable, the parser may have
+    // generated this. Treat it as: invoke the var.
+    if (!RUNTIME_BUILTINS.has(name)) {
+        // Not a known builtin: treat as a user defined function call
+        const args = (tree.astLeaves || []).map(l => compileExpr(l, depth))
+        return `bS.__runFn(${varRef(name)}, [${args.join(",")}])`
+    }
+
+    const args = (tree.astLeaves || []).map(l => compileExpr(l, depth))
+    return `bS.${isValidJsId(name) ? name : `[${jsLit(name)}]`}(${args.join(",")})`
+}
+
+const ARITH_OP = {
+    "+":  (l,r) => `bS.__add(${l},${r})`,
+    "-":  (l,r) => `((${l})-(${r}))`,
+    "*":  (l,r) => `((${l})*(${r}))`,
+    "/":  (l,r) => `bS.__div(${l},${r})`,
+    "\\": (l,r) => `bS.__intdiv(${l},${r})`,
+    "MOD":(l,r) => `bS.__mod(${l},${r})`,
+    "^":  (l,r) => `bS.__pow(${l},${r})`,
+    "==": (l,r) => `((${l})==(${r}))`,
+    "<>": (l,r) => `((${l})!=(${r}))`,
+    "><": (l,r) => `((${l})!=(${r}))`,
+    "<":  (l,r) => `((${l})<(${r}))`,
+    ">":  (l,r) => `((${l})>(${r}))`,
+    "<=": (l,r) => `((${l})<=(${r}))`,
+    "=<": (l,r) => `((${l})<=(${r}))`,
+    ">=": (l,r) => `((${l})>=(${r}))`,
+    "=>": (l,r) => `((${l})>=(${r}))`,
+    "AND":(l,r) => `bS.AND(${l},${r})`,
+    "OR": (l,r) => `bS.OR(${l},${r})`,
+    "<<": (l,r) => `((${l})<<(${r}))`,
+    ">>": (l,r) => `((${l})>>>(${r}))`,
+    "BAND":(l,r) => `((${l})&(${r}))`,
+    "BOR": (l,r) => `((${l})|(${r}))`,
+    "BXOR":(l,r) => `((${l})^(${r}))`,
+}
+const UNARY_OP = {
+    "UNARYMINUS":   (a) => `(-(${a}))`,
+    "UNARYPLUS":    (a) => `(+(${a}))`,
+    "UNARYLOGICNOT":(a) => `(!(${a}))`,
+    "UNARYBNOT":    (a) => `(~(${a}))`,
+}
+
+function compileOpExpr(tree, depth) {
+    const op = String(tree.astValue)
+    const leaves = tree.astLeaves || []
+
+    // Unary
+    if (UNARY_OP[op] && (leaves.length === 1 || leaves[1] === undefined)) {
+        return UNARY_OP[op](compileExpr(leaves[0], depth))
+    }
+
+    // Binary arithmetic / comparison / logic
+    if (ARITH_OP[op] && leaves.length === 2) {
+        return ARITH_OP[op](compileExpr(leaves[0], depth), compileExpr(leaves[1], depth))
+    }
+
+    // Generator / range
+    if (op === "TO" && leaves.length === 2) {
+        return `new bS.__ForGen(${compileExpr(leaves[0], depth)}, ${compileExpr(leaves[1], depth)}, 1)`
+    }
+    if (op === "STEP" && leaves.length === 2) {
+        return `bS.STEP(${compileExpr(leaves[0], depth)}, ${compileExpr(leaves[1], depth)})`
+    }
+
+    // List ops
+    if ((op === "!" || op === "~" || op === "#") && leaves.length === 2) {
+        const fn = (op === "!") ? "['!']" : (op === "~") ? "['~']" : "['#']"
+        return `bS${fn}(${compileExpr(leaves[0], depth)}, ${compileExpr(leaves[1], depth)})`
+    }
+
+    // Assignment as expression — returns the assigned value
+    if (op === "=" && leaves.length === 2) {
+        return "(" + compileAssignExpr(tree, depth) + ")"
+    }
+    if (op === "IN" && leaves.length === 2) {
+        // Used inside FOR/FOREACH; compileFor unwraps these. As a value, treat
+        // as { asgnVarName, asgnValue } so a stray IN still works.
+        const name = jsLit(String(leaves[0].astValue).toUpperCase())
+        const rhs = compileExpr(leaves[1], depth)
+        return `({asgnVarName: ${name}, asgnValue: ${rhs}})`
+    }
+
+    // Functional / monad ops
+    if ((op === ">>=" || op === ">>~" || op === "." || op === "$" ||
+         op === "&"   || op === "~<"  || op === "<*>" || op === "<$>" ||
+         op === "<~>") && leaves.length === 2) {
+        return `bS[${jsLit(op)}](${compileExpr(leaves[0], depth)}, ${compileExpr(leaves[1], depth)})`
+    }
+    if (op === "@" && leaves.length === 1) {
+        // Monad return as prefix
+        return `bS.MRET(${compileExpr(leaves[0], depth)})`
+    }
+    if (op === "~>") {
+        throw Error("Compiler: bare ~> survived prune (should be usrdefun)")
+    }
+
+    throw Error("Cannot compile op '" + op + "' with " + leaves.length + " operand(s)")
+}
+
+function compileLambdaExpr(tree, depth) {
+    // tree.astType === "usrdefun"; tree.astValue holds the body AST; if
+    // tree.astLeaves is non-empty, this is an immediate application.
+    const body = tree.astValue
+    if (!body || !body.astType) throw Error("Malformed usrdefun")
+
+    const arity = lambdaArity(body)
+    const newDepth = depth + 1
+    const params = []
+    for (let i = 0; i < arity; i++) params.push("_a" + (newDepth - 1) + "_" + i)
+    const bodyJs = compileExpr(body, newDepth)
+    const arrow = `((${params.join(",")}) => (${bodyJs}))`
+
+    if (tree.astLeaves && tree.astLeaves.length > 0) {
+        const args = tree.astLeaves.map(l => compileExpr(l, depth))
+        return `${arrow}(${args.join(",")})`
+    }
+    return arrow
+}
+
+function compileAssignExpr(tree, depth) {
+    // op "=" with leaves[0] as target, leaves[1] as RHS
+    const lhs = tree.astLeaves[0]
+    const rhs = compileExpr(tree.astLeaves[1], depth)
+
+    if (lhs.astType === "lit") {
+        const name = String(lhs.astValue).toUpperCase()
+        return `(${varRef(name)} = ${rhs})`
+    }
+    // The parser emits "function" or "array" for `A(i,j) = ...` — both mean
+    // "store into element of A".
+    if (lhs.astType === "array" || lhs.astType === "function") {
+        const indices = lhs.astLeaves.map(l => compileExpr(l, depth))
+        return `(bS.__arrSet(${varRef(lhs.astValue)}, [${indices.join(",")}], ${rhs}), ${rhs})`
+    }
+    throw Error("Cannot assign to LHS of type " + lhs.astType)
+}
+
+// ---------- statement lowering ----------------------------------------------
+
+function compilePrintLike(tree, fname, depth) {
+    const leaves = (tree.astLeaves || []).slice()
+    const seps = (tree.astSeps || []).slice()
+
+    let suppressNewline = false
+    if (leaves.length > 0 && leaves[leaves.length - 1] !== undefined &&
+        leaves[leaves.length - 1].astType === "null") {
+        suppressNewline = true
+        leaves.pop()
+    }
+
+    const valueExprs = leaves.map(l => compileExpr(l, depth))
+    if (suppressNewline) valueExprs.push("bS.__PRINT_NONL")
+    const sepArr = seps.slice(0, leaves.length - 1)
+
+    return `bS.${fname}([${valueExprs.join(", ")}], ${jsLit(sepArr)})`
+}
+
+function setPc(pc) {
+    if (pc[0] === Infinity) return "pc=[Infinity,0];"
+    return "pc=[" + pc[0] + "," + pc[1] + "];"
+}
+
+function compileStatement(tree, lnum, stmt, nextPc) {
+    if (!tree) return setPc(nextPc)
+    if (tree.astType === "null" && tree.astLeaves && tree.astLeaves[0]) {
+        return compileStatement(tree.astLeaves[0], lnum, stmt, nextPc)
+    }
+
+    const isFn = (tree.astType === "function" || tree.astType === "op")
+    const fname = isFn ? String(tree.astValue).toUpperCase() : null
+
+    switch (fname) {
+    case "GOTO": {
+        const target = compileGotoTarget(tree.astLeaves[0])
+        return `pc=${target};`
+    }
+    case "GOSUB": {
+        const target = compileGotoTarget(tree.astLeaves[0])
+        return `gosubStack.push([${nextPc[0]},${nextPc[1]}]); pc=${target};`
+    }
+    case "RETURN":
+        return `pc=gosubStack.pop(); if(!pc) throw new Error("RETURN without GOSUB");`
+    case "END":
+        return "pc=[Infinity,0];"
+    case "IF":
+        return compileIf(tree, lnum, stmt, nextPc)
+    case "ON":
+        return compileOn(tree, lnum, stmt, nextPc)
+    case "FOR":
+    case "FOREACH":
+        return compileFor(tree, lnum, stmt, nextPc, fname === "FOREACH")
+    case "NEXT":
+        return compileNext(tree, lnum, stmt, nextPc)
+    case "READ": {
+        const target = tree.astLeaves[0]
+        if (target.astType !== "lit") throw Error("READ: target must be a variable")
+        return `${varRef(target.astValue)}=bS.__readData(); ${setPc(nextPc)}`
+    }
+    case "RESTORE":
+        return `bS.__state.dataCursor=0; ${setPc(nextPc)}`
+    case "DATA":
+    case "LABEL":
+        return setPc(nextPc) // harvested at compile time
+    case "DIM":
+        return compileDim(tree, lnum, stmt, nextPc)
+    case "PRINT":
+    case "EMIT":
+        return `${compilePrintLike(tree, fname, 0)}; ${setPc(nextPc)}`
+    case "OPTIONBASE":
+        return `bS.OPTIONBASE(${compileExpr(tree.astLeaves[0], 0)}); ${setPc(nextPc)}`
+    case "OPTIONDEBUG":
+        return `bS.OPTIONDEBUG(${compileExpr(tree.astLeaves[0], 0)}); ${setPc(nextPc)}`
+    case "OPTIONTRACE":
+        return `bS.OPTIONTRACE(${compileExpr(tree.astLeaves[0], 0)}); ${setPc(nextPc)}`
+    case "INPUT": {
+        // INPUT <var> -> read into var
+        const target = tree.astLeaves[tree.astLeaves.length - 1]
+        if (target.astType !== "lit") throw Error("INPUT: target must be a variable")
+        return `${varRef(target.astValue)}=bS.INPUT(); ${setPc(nextPc)}`
+    }
+    case "=":
+        return `${compileAssignExpr(tree, 0)}; ${setPc(nextPc)}`
+    case "IN":
+        // bare IN as a statement is unusual but harmless
+        return `${compileExpr(tree, 0)}; ${setPc(nextPc)}`
+    case "REM":
+        return setPc(nextPc)
+    }
+
+    // Default: evaluate as an expression for side effect, then advance
+    return `${compileExpr(tree, 0)}; ${setPc(nextPc)}`
+}
+
+function compileGotoTarget(leaf) {
+    // Always route through __resolveTarget so non-existent line numbers snap
+    // upward to the next existing line — matching basic.js's main loop,
+    // which increments lnum until it finds a populated cmdbuf entry.
+    if (leaf.astType === "num") return `bS.__resolveTarget(${Number(leaf.astValue)})`
+    if (leaf.astType === "string") return `bS.__resolveTarget(${jsLit(leaf.astValue)})`
+    if (leaf.astType === "lit") {
+        const name = String(leaf.astValue)
+        return `bS.__resolveTarget(bS.__state.gotoLabels[${jsLit(name)}]!==undefined ? ${jsLit(name)} : ${varRef(name)})`
+    }
+    return `bS.__resolveTarget(${compileExpr(leaf, 0)})`
+}
+
+function compileIf(tree, lnum, stmt, nextPc) {
+    const test = compileExpr(tree.astLeaves[0], 0)
+    const thenStmt = compileStatement(tree.astLeaves[1], lnum, stmt, nextPc)
+    const elseStmt = (tree.astLeaves[2])
+        ? compileStatement(tree.astLeaves[2], lnum, stmt, nextPc)
+        : setPc(nextPc)
+    return `if(bS.__test(${test})){${thenStmt}}else{${elseStmt}}`
+}
+
+function compileOn(tree, lnum, stmt, nextPc) {
+    // children: testExpr, jumpFnLit, target0, target1, ...
+    const testExpr = compileExpr(tree.astLeaves[0], 0)
+    const jmpFn    = String(tree.astLeaves[1].astValue).toUpperCase()
+    const targets  = tree.astLeaves.slice(2)
+
+    const cases = targets.map((t, i) => {
+        const tgt = compileGotoTarget(t)
+        if (jmpFn === "GOSUB") {
+            return `case ${i}: gosubStack.push([${nextPc[0]},${nextPc[1]}]); pc=${tgt}; break;`
+        }
+        return `case ${i}: pc=${tgt}; break;`
+    })
+    return `{const _o=(${testExpr})-bS.__state.indexBase; switch(_o){${cases.join(" ")} default: ${setPc(nextPc)}}}`
+}
+
+function compileFor(tree, lnum, stmt, nextPc, isForEach) {
+    const child = tree.astLeaves[0]
+    if (child.astType !== "op" || (child.astValue !== "=" && child.astValue !== "IN")) {
+        throw Error("FOR/FOREACH: expected = or IN, got " + child.astType + ":" + child.astValue)
+    }
+    const varname = String(child.astLeaves[0].astValue).toUpperCase()
+    let iter = compileExpr(child.astLeaves[1], 0)
+    if (isForEach) {
+        // ensure we coerce generators into arrays for FOREACH semantics
+        iter = `(function(_x){return bS.__isGenerator(_x)?bS.__genToArray(_x):_x})(${iter})`
+    }
+    // Pass nextPc — the PC of the loop body's first statement — so NEXT can
+    // jump straight back without relying on fall-through.
+    return `bS.__forSetup(${jsLit(varname)}, ${iter}, ${nextPc[0]}, ${nextPc[1]}); ${setPc(nextPc)}`
+}
+
+function compileNext(tree, lnum, stmt, nextPc) {
+    let argExpr = "undefined"
+    const leaves = tree.astLeaves || []
+    if (leaves.length === 1 && leaves[0] && leaves[0].astType === "lit") {
+        argExpr = jsLit(String(leaves[0].astValue).toUpperCase())
+    }
+    return `{const _n=bS.__forNext(${argExpr}); if(_n){pc=_n;}else{${setPc(nextPc)}}}`
+}
+
+function compileDim(tree, lnum, stmt, nextPc) {
+    // tree.astLeaves contains array constructor calls: each leaf is either
+    //   an `array` node OR a `function` node (the parser doesn't distinguish
+    //   `A(5)` from a function call until runtime). astValue is the variable
+    //   name and astLeaves are the dimension expressions.
+    const stmts = []
+    for (let i = 0; i < tree.astLeaves.length; i++) {
+        const leaf = tree.astLeaves[i]
+        if (leaf.astType !== "array" && leaf.astType !== "function") {
+            throw Error("DIM: expected array decl, got " + leaf.astType)
+        }
+        const name = String(leaf.astValue).toUpperCase()
+        const dims = leaf.astLeaves.map(l => compileExpr(l, 0))
+        stmts.push(`${varRef(name)}=bS.__dim([${dims.join(",")}]);`)
+    }
+    return stmts.join(" ") + " " + setPc(nextPc)
+}
+
+// ---------- top-level entry --------------------------------------------------
+
+// Set of builtin names exposed by tbas.mjs. Used to decide whether a `lit`
+// in expression position is a variable or a function reference.
+const RUNTIME_BUILTINS = new Set([
+    "PRINT","EMIT","INPUT","CIN",
+    "ABS","SGN","INT","FLOOR","CEIL","FIX","ROUND","SQR","CBR",
+    "SIN","COS","TAN","ASN","ACO","ATN","SINH","COSH","TANH",
+    "EXP","LOG","MIN","MAX","RND",
+    "SPC","LEFT","RIGHT","MID","CHR",
+    "LEN","HEAD","TAIL","INIT","LAST","MAP","FOLD","FILTER","ARRAY",
+    "CLS","CLPX","PLOT","GOTOYX","TEXTFORE","TEXTBACK",
+    "POKE","PEEK","GETKEYSDOWN","CPUT","CGET","CSTA",
+    "TYPEOF","OPTIONBASE","OPTIONDEBUG","OPTIONTRACE",
+    "MRET","MLIST","MJOIN",
+    "AND","OR","NOT",
+    "DO","CLEAR","END","TO","STEP",
+    "FOR","FOREACH","NEXT","IF","ON","GOTO","GOSUB","RETURN",
+    "DIM","DATA","READ","RESTORE","LABEL","REM",
+    "TEST",
+])
+
+bS._compileImpl = function(outpath) {
+    if (typeof cmdbuf === "undefined") throw Error("compile.js: cmdbuf not available")
+    if (typeof bF === "undefined")     throw Error("compile.js: bF not available")
+    if (typeof bF._interpretLine !== "function") throw Error("compile.js: bF._interpretLine not available")
+
+    // Reset parser-side state so we don't pollute the live interpreter
+    if (typeof lambdaBoundVars !== "undefined") lambdaBoundVars.length = 0
+    const savedPrescan = (typeof prescan !== "undefined") ? prescan : false
+    if (typeof prescan !== "undefined") prescan = true   // suppress execution of LABEL/DATA prescan side-effects
+
+    // ---- pass 1: parse every line ----
+    const programTrees = []   // [lnum] -> array of statements
+    for (let lnum = 0; lnum < cmdbuf.length; lnum++) {
+        const linestr = cmdbuf[lnum]
+        if (linestr === undefined) continue
+        const trees = bF._interpretLine(lnum, String(linestr).trim())
+        if (trees !== undefined) programTrees[lnum] = trees
+    }
+    if (typeof prescan !== "undefined") prescan = savedPrescan
+
+    // ---- pass 2: ordered list of populated lnums and successor table ----
+    const linenums = []
+    for (let lnum = 0; lnum < programTrees.length; lnum++) {
+        if (programTrees[lnum] !== undefined) linenums.push(lnum)
+    }
+
+    function nextPcOf(idx, stmtIdx) {
+        const lnum = linenums[idx]
+        const stmts = programTrees[lnum]
+        if (stmtIdx + 1 < stmts.length) return [lnum, stmtIdx + 1]
+        if (idx + 1 < linenums.length)  return [linenums[idx + 1], 0]
+        return [Infinity, 0]
+    }
+
+    // ---- pass 3: harvest DATA constants and LABEL definitions ----
+    const dataConsts = []
+    const labelMap = {}
+    for (let i = 0; i < linenums.length; i++) {
+        const lnum = linenums[i]
+        const stmts = programTrees[lnum]
+        for (let s = 0; s < stmts.length; s++) {
+            const t = stmts[s]
+            if (!t) continue
+            if (t.astValue === "DATA") {
+                for (let k = 0; k < t.astLeaves.length; k++) {
+                    dataConsts.push(literalValue(t.astLeaves[k]))
+                }
+            } else if (t.astValue === "LABEL") {
+                const lblNode = t.astLeaves[0]
+                if (!lblNode) throw Error("LABEL with no name on line " + lnum)
+                const lblName = String(lblNode.astValue)
+                labelMap[lblName] = [lnum, s]
+            }
+        }
+    }
+
+    // ---- pass 4: emit case bodies ----
+    const cases = []
+    for (let i = 0; i < linenums.length; i++) {
+        const lnum = linenums[i]
+        const stmts = programTrees[lnum]
+        for (let s = 0; s < stmts.length; s++) {
+            const next = nextPcOf(i, s)
+            const body = compileStatement(stmts[s], lnum, s, next)
+            cases.push(`    case ${lnum}*32+${s}: { ${body} break; }`)
+        }
+    }
+
+    // ---- pass 5: assemble final output ----
+    const firstPc = (linenums.length > 0) ? `[${linenums[0]},0]` : `[Infinity,0]`
+    const labelMapJs = "{" + Object.keys(labelMap).map(k =>
+        `${jsLit(k)}: [${labelMap[k][0]}, ${labelMap[k][1]}]`
+    ).join(", ") + "}"
+
+    const out =
+`// Compiled by Terran BASIC -> JS compiler (assets/disk0/tbas/compile.js)
+// Source line count: ${linenums.length}
+let bS = require("tbas")
+bS.__reset()
+bS.__data(${jsLit(dataConsts)})
+bS.__labels(${labelMapJs})
+bS.__setLines(${jsLit(linenums)})
+let pc = ${firstPc}
+const gosubStack = []
+while (pc[0] !== Infinity) {
+  switch (pc[0]*32 + pc[1]) {
+${cases.join("\n")}
+    default: pc = [Infinity, 0]; break;
+  }
+}
+`
+
+    // ---- write to disk via basic.js's fs (writes under BASIC_HOME_PATH) ----
+    const opened = fs.open(outpath, "W")
+    if (!opened) throw Error("Cannot open " + outpath + " for writing")
+    fs.write(out)
+    return out.length
+}
+
+})();

assets/disk0/tracker_play.js

@@ -0,0 +1,21 @@
+const taud = require("taud")
+
+const fullFilePath = _G.shell.resolvePathInput(exec_args[1])
+if (fullFilePath === undefined) {
+    println(`Usage: ${exec_args[0]} path_to.taud`)
+    return 1
+}
+
+const PLAYHEAD = 0
+
+println("Playing "+fullFilePath.full)
+
+audio.resetParams(PLAYHEAD)
+audio.purgeQueue(PLAYHEAD)
+audio.stop(PLAYHEAD)
+
+taud.uploadTaudFile(fullFilePath.full, 0, PLAYHEAD)
+audio.setMasterVolume(PLAYHEAD, 255)
+audio.setMasterPan(PLAYHEAD, 128)
+audio.setCuePosition(PLAYHEAD, 0)
+audio.play(PLAYHEAD)

assets/disk0/tracker_test.js

@@ -0,0 +1,186 @@
+// Tracker Mode — Bach's Prelude in C Major (BWV 846)
+// Run from the TVDOS shell: js tracker_test.js
+// Uploads ~92 patterns on startup (takes a moment).
+
+// -- Note table (12-TET, 4096-TET encoding) ------------------------------------
+// C3 = 0x4000; each semitone = 4096/12 ≈ 341.33 steps; each octave = 4096 steps.
+// Sharp suffix: s (e.g. Cs3); flat aliases also provided (e.g. Db3 = Cs3).
+// Special values: Note.OFF = key-off, Note.CUT = note cut, Note.NOP = no-op.
+var Note = (function() {
+    var SEMITONE = 4096 / 12;
+    var C3 = 0x4000;
+    function n(oct, semi) { return Math.round(C3 + (oct - 3) * 4096 + semi * SEMITONE) & 0xFFFF; }
+    var t = {};
+    var names = ['C','Cs','D','Ds','E','F','Fs','G','Gs','A','As','B'];
+    var flats  = ['C','Db','D','Eb','E','F','Gb','G','Ab','A','Bb','B'];
+    for (var oct = 0; oct <= 9; oct++) {
+        for (var s = 0; s < 12; s++) {
+            t[names[s] + oct] = n(oct, s);
+            if (flats[s] !== names[s]) t[flats[s] + oct] = n(oct, s);
+        }
+    }
+    t.NOP = 0x0000;   // no-op (empty row)
+    t.OFF = 0x0001;   // key-off
+    t.CUT = 0x0002;   // note cut (immediate)
+    return t;
+}());
+
+var PLAYHEAD = 0;
+
+// -- 1. Sample: triangle wave (256 samples @ C3) --------------------------------
+var SAMPLE_LEN = 256;
+var sampleBytes = new Array(SAMPLE_LEN);
+for (var i = 0; i < SAMPLE_LEN; i++) {
+    var phase = (i / SAMPLE_LEN) * 2.0;
+    var val_ = phase < 1.0 ? phase : 2.0 - phase;
+    sampleBytes[i] = Math.round(val_ * 254) & 0xFF;
+}
+var memBase = audio.getMemAddr();
+for (var i = 0; i < SAMPLE_LEN; i++) {
+    sys.poke(memBase - i, sampleBytes[i]);
+}
+
+// -- 2. Instrument 0 -----------------------------------------------------------
+var instBytes = new Array(64).fill(0);
+instBytes[2] = 0; instBytes[3] = 1;        // sampleLength = 256
+instBytes[4] = 0x00; instBytes[5] = 0x7D;  // samplingRate = 32000
+instBytes[10] = 0x00; instBytes[11] = 0x01;  // sampleLoopEnd = 256 (whole sample)
+instBytes[12] = 1;                           // loopMode = 1 (forward)
+instBytes[16] = 255; instBytes[17] = 0;     // envelope: vol=255, hold
+audio.uploadInstrument(1, instBytes);
+
+// -- 3. Piano-roll builder -----------------------------------------------------
+// Source convention: C1=0, C2=12, C3=24, C4=36 (i.e. C3=24, octave every 12).
+function midiToTsvm(n) {
+    var oct = Math.floor(n / 12) + 1;
+    return Math.round(0x3000 + oct * 4096 + (n % 12) * (4096 / 12)) & 0xFFFF;
+}
+
+var noteMap = {};  // absRow → TSVM note value
+var rowCursor = 0;
+
+function seq(notes, lens) {
+    for (var i = 0; i < notes.length; i++) {
+        noteMap[rowCursor] = midiToTsvm(notes[i]);
+        rowCursor += lens[i];
+    }
+}
+
+var TD = 3;  // rows per note step (= source TICK_DIVISOR)
+
+function prel(n1, n2, n3, n4, n5) {
+    seq([n1, n2, n3, n4, n5, n3, n4, n5, n1, n2, n3, n4, n5, n3, n4, n5],
+        [TD+2, TD, TD, TD-1, TD, TD, TD, TD, TD, TD, TD, TD-1, TD, TD, TD, TD]);
+}
+function end1(n1,n2,n3,n4,n5,n6,n7,n8,n9) {
+    seq([n1, n2, n3, n4, n5, n6, n5, n4, n5, n7, n8, n7, n8, n9, n8, n9],
+        [TD+2, TD, TD, TD-1, TD, TD, TD, TD, TD, TD, TD, TD-1, TD, TD, TD, TD]);
+}
+function end2(n1,n2,n3,n4,n5,n6,n7,n8,n9) {
+    seq([n1, n2, n3, n4, n5, n6, n5, n4, n5, n4, n3, n4, n7, n8, n9, n7],
+        [TD+2, TD+1, TD+1, TD+1, TD+1, TD+2, TD+2, TD+2,
+         TD+3, TD+3, TD+4, TD+4, TD+6, TD+8, TD+12, TD+24]);
+}
+function end3(ns) {
+    for (var i = 0; i < ns.length; i++) {
+        noteMap[rowCursor] = midiToTsvm(ns[i]);
+        rowCursor += 1;
+    }
+    for (var i = 0; i < TD*2; i++) {
+        noteMap[rowCursor] = Note.NOP
+        rowCursor += 1;
+    }
+}
+
+// -- 4. Build the piece --------------------------------------------------------
+rowCursor = 16 * TD;  // 160-row intro silence
+
+prel(24,28,31,36,40);
+prel(24,26,33,38,41);
+prel(23,26,31,38,41);
+prel(24,28,31,36,40);
+prel(24,28,33,40,45);
+prel(24,26,30,33,38);
+prel(23,26,31,38,43);
+prel(23,24,28,31,36);
+prel(21,24,28,31,36);
+prel(14,21,26,30,36);
+prel(19,23,26,31,35);
+prel(19,22,28,31,37);
+prel(17,21,26,33,38);
+prel(17,20,26,29,35);
+prel(16,19,24,31,36);
+prel(16,17,21,24,29);
+prel(14,17,21,24,29);
+prel( 7,14,19,23,29);
+prel(12,16,19,24,28);
+prel(12,19,22,24,28);
+prel( 5,17,21,24,28);
+prel( 6,12,21,24,27);
+prel( 8,17,23,24,26);
+prel( 7,17,19,23,26);
+prel( 7,16,19,24,28);
+prel( 7,14,19,24,29);
+prel( 7,14,19,23,29);
+prel( 7,15,21,24,30);
+prel( 7,16,19,24,31);
+prel( 7,14,19,24,29);
+prel( 7,14,19,23,29);
+prel( 0,12,19,22,28);
+end1( 0,12,17,21,24,29,21,17,14);
+end2( 0,11,31,35,38,41,26,29,28);
+end3([0,12,28,31,36]);
+
+noteMap[rowCursor] = Note.OFF;    // key-off at start of final silence
+rowCursor += 16 * TD - 5;         // 155 more rows of silence
+
+var totalRows = rowCursor;         // 5836
+var NUM_ROWS = 64;
+var numPatterns = Math.ceil(totalRows / NUM_ROWS);  // 92
+
+// -- 5. Build and upload patterns ----------------------------------------------
+for (var p = 0; p < numPatterns; p++) {
+    var patBytes = new Array(512).fill(0);
+    for (var r = 0; r < NUM_ROWS; r++) {
+        var absRow = p * NUM_ROWS + r;
+        var noteVal = (noteMap[absRow] !== undefined) ? noteMap[absRow] : Note.NOP;
+        var isOn = (noteVal !== Note.NOP && noteVal !== Note.OFF && noteVal !== Note.CUT);
+        var off = r * 8;
+        patBytes[off]     = noteVal & 0xFF;
+        patBytes[off + 1] = (noteVal >> 8) & 0xFF;
+        patBytes[off + 2] = 1;              // instrument 1
+        patBytes[off + 3] = 63;  // volume
+        patBytes[off + 4] = 31;  // pan (centre)
+    }
+    audio.uploadPattern(p, patBytes);
+}
+
+// -- 6. Cue sheet: one entry per pattern, last halts -------------------------
+// Cue format: 32 bytes, 20 voices with 12-bit pattern numbers packed as:
+//   bytes 0-9:  low nybbles (byte i = voice i*2 in hi-nybble, voice i*2+1 in lo-nybble)
+//   bytes 10-19: mid nybbles (same packing)
+//   bytes 20-29: high nybbles (same packing)
+//   byte 30: instruction (0=NOP, 1=Halt)
+// Voice 0 plays pattern c; voices 1-19 are disabled (0xFFF).
+for (var c = 0; c < numPatterns; c++) {
+    var cueBytes = new Array(32).fill(0xFF);
+    // voice 0 = c (12-bit), voice 1 = 0xFFF → byte0=(c&0xF)<<4|0xF
+    cueBytes[0]  = ((c & 0xF) << 4) | 0xF;           // lo nybbles v0,v1
+    cueBytes[10] = (((c >> 4) & 0xF) << 4) | 0xF;    // mid nybbles v0,v1
+    cueBytes[20] = (((c >> 8) & 0xF) << 4) | 0xF;    // hi nybbles v0,v1
+    cueBytes[30] = (c === numPatterns - 1) ? 0x01 : 0;
+    audio.uploadCue(c, cueBytes);
+}
+
+// -- 7. Playback ---------------------------------------------------------------
+// BPM=500, tickRate=1: 1 row = 5 ms; 10 rows/step × 16 steps/bar ≈ 75 bars/min.
+audio.setTrackerMode(PLAYHEAD);
+audio.setBPM(PLAYHEAD, 250);
+audio.setTickRate(PLAYHEAD, 6);
+audio.setMasterVolume(PLAYHEAD, 255);
+audio.setMasterPan(PLAYHEAD, 128);
+audio.setCuePosition(PLAYHEAD, 0);
+audio.play(PLAYHEAD);
+
+println("Bach's Prelude in C Major -- " + numPatterns + " patterns loaded.");
+println("Stop: audio.stop(" + PLAYHEAD + ")");

assets/disk0/tvdos/TVDOS.SYS

@@ -55,10 +55,12 @@ class PmemFSfile {
         // string representation (preferable)
         if (typeof bytes === 'string' || bytes instanceof String) {
             this.data = bytes
+            this.length = bytes.length
         }
         // Javascript array OR JVM byte[]
         else if (Array.isArray(bytes) || bytes.toString().startsWith("[B")) {
-            this.bdata = bytes[i]
+            this.bdata = bytes
+            this.length = bytes.length
         }
         else {
             throw Error("Invalid type for directory")
@@ -76,10 +78,10 @@ class PmemFSfile {
 
     dataAsBytes() {
         if (this.bdata !== undefined) return this.bdata
-        this.bdata = new Int8Array(this.data.length)
+        this.bdata = new Uint8Array(this.data.length)
         for (let i = 0; i < this.data.length; i++) {
             let p = this.data.charCodeAt(i)
-            this.bdata[i] = (p > 127) ? p - 255 : p
+            this.bdata[i] = p
         }
         return this.bdata
     }
@@ -147,10 +149,12 @@ _TVDOS.variables = {
     LANG: "EN",
     KEYBOARD: "us_qwerty",
     PATH: "\\tvdos\\bin;\\home",
-    PATHEXT: ".com;.bat;.app;.js",
+    INCLPATH: "\\tvdos\\include;\\home",
+    PATHEXT: ".com;.bat;.app;.js;.alias",
     HELPPATH: "\\tvdos\\help",
     OS_NAME: "TSVM Disk Operating System",
-    OS_VERSION: _TVDOS.VERSION
+    OS_VERSION: _TVDOS.VERSION,
+    USERCONFIGPATH: "\\home\\config",
 };
 Object.freeze(_TVDOS);
 
@@ -162,16 +166,16 @@ class TVDOSFileDescriptor {
 
     constructor(path0, driverID) {
         if (path0.startsWith("$")) {
-            let path1 = path0.substring(3)
-            let slashPos = path1.indexOf("/")
+            let path1 = path0.replaceAll("/", "\\").substring(3)
+            let slashPos = path1.indexOf("\\")
             let devName = path1.substring(0, (slashPos < 0) ? path1.length : slashPos)
 
             if (!files.reservedNames.includes(devName)) {
                 throw Error(`${devName} is not a valid device file`)
             }
 
-            this._driveLetter = undefined
-            this._path = path0
+            this._driveLetter = '$'
+            this._path = '\\' + path1
             this._driverID = `DEV${devName}`
             this._driver = _TVDOS.DRV.FS[`DEV${devName}`] // can't just put `driverID` here
         }
@@ -225,8 +229,9 @@ class TVDOSFileDescriptor {
     }
 
     /** reads the file bytewise and puts it to the specified memory address
-     * @param count optional -- how many bytes to read
-     * @param offset optional -- how many bytes to skip initially
+     * @param ptr -- where the bytes should be dumped
+     * @param count -- how many bytes to read
+     * @param offset -- how many bytes to skip initially from the file
      */
     pread(ptr, count, offset) {
         this.driver.pread(this, ptr, count, offset)
@@ -241,7 +246,9 @@ class TVDOSFileDescriptor {
     }
 
     /** writes the bytes stored in the memory[ptr .. ptr+count-1] to file[offset .. offset+count-1]
-     * - @param offset is optional
+     * @param ptr -- where the bytes are
+     * @param count -- how many bytes to write
+     * @param offset -- position in the file
      */
     pwrite(ptr, count, offset) {
         this.driver.pwrite(this, ptr, count, offset)
@@ -420,11 +427,11 @@ _TVDOS.DRV.FS.SERIAL.sread = (fd) => {
 }
 _TVDOS.DRV.FS.SERIAL.bread = (fd) => {
     let str = _TVDOS.DRV.FS.SERIAL.sread(fd)
-    let bytes = new Int8Array(str.length)
+    let bytes = []//new Int8Array(str.length)
     for (let i = 0; i < str.length; i++) {
 //        let p = str.charCodeAt(i)
 //        bytes[i] = (p > 127) ? p - 255 : p
-        bytes[i] = str.charCodeAt(i)
+        bytes.push(str.charCodeAt(i))
     }
     return bytes
 }
@@ -934,8 +941,9 @@ _TVDOS.DRV.FS.DEVTMP.bread = (fd) => {
 _TVDOS.DRV.FS.DEVTMP.pread = (fd, ptr, count, offset) => {
     if (_TVDOS.TMPFS[fd.path] === undefined) throw Error(`No such file: ${fd.fullPath}`)
     let str = _TVDOS.TMPFS[fd.path].dataAsString()
-    for (let i = 0; i < count - (offset || 0); i++) {
-        sys.poke(ptr + i, String.charCodeAt(i + (offset || 0)))
+    let off = offset || 0
+    for (let i = 0; i < count; i++) {
+        sys.poke(ptr + i, str.charCodeAt(off + i))
     }
 }
 
@@ -983,6 +991,7 @@ _TVDOS.DRV.FS.DEVTMP.remove = (fd) => {
     return true
 }
 _TVDOS.DRV.FS.DEVTMP.exists = (fd) => (_TVDOS.TMPFS[fd.path] !== undefined)
+_TVDOS.DRV.FS.DEVTMP.getFileLen = (fd) => (_TVDOS.TMPFS[fd.path].length)
 
 Object.freeze(_TVDOS.DRV.FS.DEVTMP)
 
@@ -1024,136 +1033,6 @@ _TVDOS.DRV.FS.NET.exists = (fd) => {
     return (0 == com.getStatusCode(port[0]))
 }
 
-///////////////////////////////////////////////////////////////////////////////
-
-
-// Legacy Serial filesystem, !!pending for removal!!
-
-
-/*const filesystem = {};
-
-filesystem._toPorts = (driveLetter) => {
-    if (driveLetter.toUpperCase === undefined) {
-        throw Error("'"+driveLetter+"' (type: "+typeof driveLetter+") is not a valid drive letter");
-    }
-    var port = _TVDOS.DRIVES[driveLetter.toUpperCase()];
-    if (port === undefined) {
-        throw Error("Drive letter '" + driveLetter.toUpperCase() + "' does not exist");
-    }
-    return port
-};
-filesystem._close = (portNo) => {
-    com.sendMessage(portNo, "CLOSE")
-}
-filesystem._flush = (portNo) => {
-    com.sendMessage(portNo, "FLUSH")
-}
-
-// @return disk status code (0 for successful operation)
-//         throws if:
-//             - java.lang.NullPointerException if path is null
-//             - Error if operation mode is not "R", "W" nor "A"
-filesystem.open = (driveLetter, path, operationMode) => {
-    var port = filesystem._toPorts(driveLetter);
-
-    filesystem._flush(port[0]); filesystem._close(port[0]);
-
-    var mode = operationMode.toUpperCase();
-    if (mode != "R" && mode != "W" && mode != "A") {
-        throw Error("Unknown file opening mode: " + mode);
-    }
-
-    com.sendMessage(port[0], "OPEN"+mode+'"'+path+'",'+port[1]);
-    return com.getStatusCode(port[0]);
-};
-filesystem.getFileLen = (driveLetter) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "GETLEN");
-    var response = com.getStatusCode(port[0]);
-    if (135 == response) {
-        throw Error("File not opened");
-    }
-    if (response < 0 || response >= 128) {
-        throw Error("Reading a file failed with "+response);
-    }
-    return Number(com.pullMessage(port[0]));
-};
-// @return the entire contents of the file in String
-filesystem.readAll = (driveLetter) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "READ");
-    var response = com.getStatusCode(port[0]);
-    if (135 == response) {
-        throw Error("File not opened");
-    }
-    if (response < 0 || response >= 128) {
-        throw Error("Reading a file failed with "+response);
-    }
-    return com.pullMessage(port[0]);
-};
-filesystem.readAllBytes = (driveLetter) => {
-    var str = filesystem.readAll(driveLetter);
-    var bytes = new Uint8Array(str.length);
-    for (let i = 0; i < str.length; i++) {
-        bytes[i] = str.charCodeAt(i);
-    }
-    return bytes;
-};
-filesystem.write = (driveLetter, string) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "WRITE"+string.length);
-    var response = com.getStatusCode(port[0]);
-    if (135 == response) {
-        throw Error("File not opened");
-    }
-    if (response < 0 || response >= 128) {
-        throw Error("Writing a file failed with "+response);
-    }
-    com.sendMessage(port[0], string);
-    filesystem._flush(port[0]); filesystem._close(port[0]);
-};
-filesystem.writeBytes = (driveLetter, bytes) => {
-    var string = btostr(bytes); // no spreading: has length limit
-    filesystem.write(driveLetter, string);
-};
-filesystem.isDirectory = (driveLetter) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "LISTFILES");
-    var response = com.getStatusCode(port[0]);
-    return (response === 0);
-};
-filesystem.mkDir = (driveLetter) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "MKDIR");
-    var response = com.getStatusCode(port[0]);
-
-    if (response < 0 || response >= 128) {
-        var status = com.getDeviceStatus(port[0]);
-        throw Error("Creating a directory failed with ("+response+"): "+status.message+"\n");
-    }
-    return (response === 0); // possible status codes: 0 (success), 1 (fail)
-};
-filesystem.touch = (driveLetter) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "TOUCH");
-    var response = com.getStatusCode(port[0]);
-    return (response === 0);
-};
-filesystem.mkFile = (driveLetter) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "MKFILE");
-    var response = com.getStatusCode(port[0]);
-    return (response === 0);
-};
-filesystem.remove = (driveLetter) => {
-    var port = filesystem._toPorts(driveLetter);
-    com.sendMessage(port[0], "DELETE");
-    var response = com.getStatusCode(port[0]);
-    return (response === 0);
-};
-Object.freeze(filesystem);*/
-
-
 ///////////////////////////////////////////////////////////////////////////////
 
 const files = {}
@@ -1235,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;
@@ -1262,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)
 
@@ -1532,9 +1442,6 @@ let requireFromMemory = (ptr) => {
 }*/
 
 
-var GL = require("A:/tvdos/include/gl.mjs")
-
-
 // @param cmdsrc JS source code
 // @param args arguments for the program, must be Array, and args[0] is always the name of the program, e.g.
 //        for command line 'echo foo bar', args[0] must be 'echo'
@@ -1547,7 +1454,7 @@ var execApp = (cmdsrc, args, appname) => {
 `var ${appname}=function(exec_args){${injectIntChk(cmdsrc, intchkFunName)}\n};` +
 `${appname}`); // making 'exec_args' a app-level global
 
-        execAppPrg(args);
+        return execAppPrg(args);
 }
 
 
@@ -1564,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/VTMGR.SYS")
+        runBatch("\\AUTOEXEC.BAT")
+    }
+    else {
+        serial.println(`TVDOS.SYS re-initialised in VT pane on VM ${sys.getVmId()}`);
+    }
+}

assets/disk0/tvdos/VTMGR.SYS

@@ -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

assets/disk0/tvdos/bin/color.js.synopsis

@@ -0,0 +1,16 @@
+{
+  "tsfVersion": "1.0",
+  "name": "color",
+  "summary": "Set the screen background and foreground colours",
+  "symbols": {
+    "code": {
+      "kind": "positional",
+      "type": "string",
+      "name": "BF",
+      "summary": "Two hex digits: background then foreground",
+      "validation": { "pattern": "^[0-9A-Fa-f]{2}$" },
+      "completion": { "method": "none" }
+    }
+  },
+  "synopsis": { "type": "reference", "symbol": "code" }
+}

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)
     }
 }
 
@@ -77,56 +88,31 @@ function printmotd() {
     let motd = motdFile.sread().trim()
     let width = con.getmaxyx()[1]
 
+    let ts = require("typesetter")
 
     if (goFancy) {
         let margin = 4
         let internalWidth = width - 2*margin
+        let textWidth = internalWidth - 2  // one space of padding inside each ribbon edge
 
-        con.color_pair(255,253) // white text, transparent back (initial ribbon)
-
-        let [cy, cx] = con.getyx()
-
-        con.mvaddch(cy, 4, 16);con.curs_right();print(' ')
-
-        const PCX_INIT = margin - 2
-        let tcnt = 0
-        let pcx = PCX_INIT
-        con.color_pair(240,253) // black text, white back (first line of text)
-        while (tcnt <= motd.length) {
-            let char = motd.charAt(tcnt)
-
-            if (char != '\n') {
-                // prevent the line starting from ' '
-                if (pcx != PCX_INIT || char != ' ') {
-                    print(motd.charAt(tcnt))
-                }
-                pcx += 1
-            }
-
-            if ('\n' == char || pcx % internalWidth == 0 && pcx != 0 || tcnt == motd.length) {
-                // current line ending
-                let [_, ncx] = con.getyx()
-                for (let k = 0; k < width - margin - ncx + 1; k++) print(' ')
-                con.color_pair(255,253) // white text, transparent back
-                con.addch(17);println()
-
-                if (tcnt == motd.length) break
-
-                // next line header
-                let [ncy, __] = con.getyx()
-                con.color_pair(255,253) // white text, transparent back
-                con.mvaddch(ncy, 4, 16);con.curs_right();print(' ');con.color_pair(240,253) // black text, white back (subsequent lines of the text)
-                pcx = PCX_INIT
-            }
-
-            tcnt += 1
-        }
-
+        let lines = ts.typeset(motd, textWidth)
+        lines.forEach(line => {
+            let [cy, _cx] = con.getyx()
+            con.color_pair(255,253) // ribbon edge: white text, transparent back
+            con.mvaddch(cy, margin, 16); con.curs_right()
+            print(' ')
+            con.color_pair(240,253) // body: black text, white back
+            print(line)
+            con.color_pair(255,253)
+            print(' ')
+            con.addch(17); println()
+        })
         con.reset_graphics()
     }
     else {
         println()
-        println(motd)
+        let lines = ts.typeset(motd, width)
+        lines.forEach(line => println(line))
     }
 
     println()
@@ -203,6 +189,19 @@ shell.replaceVarCall = function(value) {
 shell.getPwd = function() { return shell_pwd; }
 shell.getPwdString = function() { return "\\" + (shell_pwd.concat([""])).join("\\"); }
 shell.getCurrentDrive = function() { return CURRENT_DRIVE; }
+shell.runningScriptPaths = []
+shell.getFilePath = function() {
+    return shell.runningScriptPaths[shell.runningScriptPaths.length - 1]
+}
+shell.getFileDir = function() {
+    let p = shell.runningScriptPaths[shell.runningScriptPaths.length - 1]
+    if (p === undefined) return undefined
+    let lastSlash = Math.max(p.lastIndexOf('\\'), p.lastIndexOf('/'))
+    if (lastSlash < 0) return p
+    // root of a drive (e.g. "A:\foo.js" -> "A:\")
+    if (lastSlash === 2 && p[1] === ':') return p.substring(0, 3)
+    return p.substring(0, lastSlash)
+}
 // example input: echo "the string" > subdir\test.txt
 shell.parse = function(input) {
     let tokens = []
@@ -577,8 +576,76 @@ shell.coreutils = {
     ver: function(args) {
         println(welcome_text)
     },
+    which: function(args) {
+        if (args[1] === undefined) {
+            printerrln(`Usage: ${args[0].toUpperCase()} program_name`)
+            return 1
+        }
+        let cmd = args[1]
+
+        if (shell.coreutils[cmd.toLowerCase()] !== undefined) {
+            println(`${cmd}: shell built-in command`)
+            return 0
+        }
+
+        var fileExists = false
+        var searchFile
+        var searchPath = ""
+
+        if (shell.isValidDriveLetter(cmd[0]) && cmd[1] == ':') {
+            searchFile = files.open(cmd)
+            searchPath = trimStartRevSlash(searchFile.path)
+            fileExists = searchFile.exists
+        }
+        else {
+            var searchDir = (cmd.startsWith("/")) ? [""] : ["/"+shell_pwd.join("/")].concat(_TVDOS.getPath())
+
+            var pathExt = []
+            if (cmd.split(".")[1] === undefined)
+                _TVDOS.variables.PATHEXT.split(';').forEach(function(it) { pathExt.push(it); pathExt.push(it.toUpperCase()); })
+            else
+                pathExt.push("")
+
+            searchLoop:
+            for (var i = 0; i < searchDir.length; i++) {
+                for (var j = 0; j < pathExt.length; j++) {
+                    let search = searchDir[i]; if (!search.endsWith('\\')) search += '\\'
+                    searchPath = trimStartRevSlash(search + cmd + pathExt[j])
+
+                    searchFile = files.open(`${CURRENT_DRIVE}:\\${searchPath}`)
+                    if (searchFile.exists) {
+                        fileExists = true
+                        break searchLoop
+                    }
+                }
+            }
+        }
+
+        if (!fileExists) {
+            printerrln(`${cmd}: not found`)
+            return 1
+        }
+
+        println(searchFile.fullPath)
+        return 0
+    },
     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
@@ -590,14 +657,19 @@ shell.coreutils.ls = shell.coreutils.dir
 shell.coreutils.time = shell.coreutils.date
 shell.coreutils.md = shell.coreutils.mkdir
 shell.coreutils.move = shell.coreutils.mv
+shell.coreutils.where = shell.coreutils.which
 // end of command aliases
 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);  },
@@ -614,13 +686,25 @@ require = function(path) {
     if (path[1] == ":") return shell.require(path)
     else {
         // if the path starts with ".", look for the current directory
-        // if the path starts with [A-Za-z0-9], look for the DOSDIR/includes
+        // if the path starts with [A-Za-z0-9], search through INCLPATH
         if (path[0] == '.') return shell.require(shell.resolvePathInput(path).full + ".mjs")
-        else return shell.require(`A:${_TVDOS.variables.DOSDIR}/include/${path}.mjs`)
+        else {
+            let inclDirs = (_TVDOS.variables.INCLPATH || "").split(';').filter(function(it) { return it.length > 0 })
+            for (let i = 0; i < inclDirs.length; i++) {
+                let dir = inclDirs[i]
+                if (!dir.endsWith('\\') && !dir.endsWith('/')) dir += '\\'
+                let candidate = `${CURRENT_DRIVE}:${dir}${path}.mjs`
+                if (files.open(candidate).exists) return shell.require(candidate)
+            }
+            // no match found; defer to shell.require with the first entry so the error mentions a sensible path
+            let firstDir = inclDirs[0] || `${_TVDOS.variables.DOSDIR}\\include`
+            if (!firstDir.endsWith('\\') && !firstDir.endsWith('/')) firstDir += '\\'
+            return shell.require(`${CURRENT_DRIVE}:${firstDir}${path}.mjs`)
+        }
     }
 }
 
-shell.execute = function(line) {
+shell.execute = function(line, nameOverride) {
     if (0 == line.size) return
     let parsedTokens = shell.parse(line) // echo, "hai", |, less
     let statements = [] // [[echo, "hai"], [less]]
@@ -746,6 +830,8 @@ shell.execute = function(line) {
                 let programCode = searchFile.sread()
                 let extension = searchFile.extension.toUpperCase()
 
+                shell.runningScriptPaths.push(searchFile.fullPath)
+                try {
                 if ("BAT" == extension) {
                     // parse and run as batch file
                     var lines = programCode.split('\n').filter(function(it) { return it.length > 0 }) // this return is not shell's return!
@@ -753,6 +839,34 @@ shell.execute = function(line) {
                         shell.execute(line)
                     })
                 }
+                else if ("ALIAS" == extension) {
+                    // parse alias
+                    // $0: all arguments
+                    // $1..9: specific arguments
+                    // Tokens that contain whitespace or shell metacharacters must be re-quoted
+                    // before re-execution, otherwise the re-parse splits them on spaces.
+                    var quoteAliasArg = function(s) {
+                        if (s === undefined || s === null) return ""
+                        s = ''+s
+                        if (s.length === 0) return ""
+                        if (/[\s"|><&]/.test(s)) return '"' + s.replaceAll('"', '^"') + '"'
+                        return s
+                    }
+                    var lines = programCode.split('\n').filter(function(it) { return it.length > 0 }) // this return is not shell's return!
+                    lines.forEach(function(line) {
+                        var newLine = line
+
+                        // replace $1..$9
+                        for (let j = 1; j <= 9; j++) {
+                            newLine = newLine.replaceAll('$'+j, quoteAliasArg(tokens[j]))
+                        }
+
+                        // replace $0
+                        newLine = newLine.replaceAll('$0', tokens.slice(1).map(quoteAliasArg).join(' '))
+
+                        shell.execute(newLine, cmd)
+                    })
+                }
                 else if ("APP" == extension) {
                     let appexec = `A:${_TVDOS.variables.DOSDIR}\\sbin\\appexec.js`
                     let foundFile = searchFile.fullPath
@@ -767,6 +881,10 @@ shell.execute = function(line) {
                         errorlevel = 0 // reset the number
 
                         if (_G.shellProgramTitles === undefined) _G.shellProgramTitles = []
+                        if (nameOverride !== undefined) {
+                            tokens[0] = (''+nameOverride)
+                            cmd = tokens[0]
+                        }
                         _G.shellProgramTitles.push(cmd.toUpperCase())
                         sendLcdMsg(_G.shellProgramTitles[_G.shellProgramTitles.length - 1])
                         //serial.println(_G.shellProgramTitles)
@@ -806,6 +924,9 @@ shell.execute = function(line) {
                         continue
                     }
                 }
+                } finally {
+                    shell.runningScriptPaths.pop()
+                }
             }
         }
 
@@ -865,6 +986,246 @@ 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
+}
+
+// Lazily-resolved synopsis module (TSF loader/completion resolver). Held for
+// the whole session so its in-memory cache survives across keystrokes.
+// undefined = not probed yet, null = unavailable.
+let _acSyn = undefined
+function getSynopsisMod() {
+    if (_acSyn !== undefined) return _acSyn
+    _acSyn = null
+    try {
+        let m = require("synopsis") // resolved through INCLPATH (\tvdos\include\synopsis.mjs)
+        if (m && typeof m.getCompletion === "function") _acSyn = m
+    } catch (e) {
+        debugprintln("command.js > autocomplete: synopsis unavailable: " + e)
+    }
+    return _acSyn
+}
+
+// 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
+}
+
+// Candidates for an argument (not the command word). Consults the command's
+// TSF synopsis (via synopsis.mjs) for option flags, enum/list values and
+// subcommand names, and merges in filesystem entries when the synopsis says the
+// slot expects a path/file/directory. Falls back to plain path completion when
+// no synopsis exists, so behaviour is unchanged for commands without one.
+function _acArgCandidates(prefix, word) {
+    let syn = getSynopsisMod()
+    if (syn) {
+        try {
+            let toks = prefix.trim().split(/\s+/)
+            let cmd = toks[0]
+            let argToks = toks.slice(1)
+            let r = syn.getCompletion(cmd, argToks, word)
+            if (r && r.ok) {
+                let out = (r.candidates || []).slice()
+                if (r.filesystem) {
+                    _acPathCandidates(word).forEach(function(c) {
+                        if (r.filesystem === 'directory' && !c.isDir) return // dirs only
+                        out.push(c)
+                    })
+                }
+                // de-dupe by the text that would be inserted
+                let seen = {}, dedup = []
+                out.forEach(function(c) { if (seen[c.value]) return; seen[c.value] = true; dedup.push(c) })
+                return dedup
+            }
+        } catch (e) {
+            debugprintln("command.js > _acArgCandidates: " + e)
+        }
+    }
+    return _acPathCandidates(word)
+}
+
+// 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 prefix = line.substring(0, wordStart)
+    let isFirstWord = (prefix.trim().length === 0)
+    let hasPathSep = (word.indexOf('\\') >= 0 || word.indexOf('/') >= 0 || word.indexOf(':') >= 0)
+    let candidates
+    if (isFirstWord)
+        candidates = hasPathSep ? _acPathCandidates(word) : _acCommandCandidates(word)
+    else
+        candidates = _acArgCandidates(prefix, 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
+try {
+    let userConfigPath = `${CURRENT_DRIVE}:${_TVDOS.variables.USERCONFIGPATH}`
+    let userConfigDir = files.open(userConfigPath)
+    if (!userConfigDir.exists) {
+        debugprintln(`command.js > creating USERCONFIGPATH at ${userConfigPath}`)
+        userConfigDir.mkDir()
+    }
+} catch (e) {
+    debugprintln("command.js > USERCONFIGPATH creation failed: " + e.message)
+}
 
 if (exec_args[1] !== undefined) {
     // only meaningful switches would be either -c or -k anyway
@@ -909,23 +1270,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)
@@ -941,32 +1412,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/drives.js.synopsis

@@ -0,0 +1,7 @@
+{
+  "tsfVersion": "1.0",
+  "name": "drives",
+  "summary": "List connected and mounted disk drives",
+  "symbols": {},
+  "synopsis": { "type": "sequence", "children": [] }
+}

assets/disk0/tvdos/bin/edit.js.synopsis

@@ -0,0 +1,12 @@
+{
+  "tsfVersion": "1.0",
+  "name": "edit",
+  "summary": "Full-screen text editor",
+  "symbols": {
+    "file": { "kind": "positional", "type": "file", "name": "FILE", "summary": "File to edit; a new buffer when omitted" }
+  },
+  "synopsis": {
+    "type": "optional",
+    "child": { "type": "reference", "symbol": "file" }
+  }
+}

assets/disk0/tvdos/bin/geturl.js.synopsis

@@ -0,0 +1,9 @@
+{
+  "tsfVersion": "1.0",
+  "name": "geturl",
+  "summary": "Fetch a URL and print the response",
+  "symbols": {
+    "url": { "kind": "positional", "type": "url", "name": "URL", "summary": "Address to fetch" }
+  },
+  "synopsis": { "type": "reference", "symbol": "url" }
+}

assets/disk0/tvdos/bin/gzip.js.synopsis

@@ -0,0 +1,18 @@
+{
+  "tsfVersion": "1.0",
+  "name": "gzip",
+  "summary": "Compress or decompress a file (Zstd-backed)",
+  "symbols": {
+    "decompress": { "kind": "option", "short": "-d", "summary": "Decompress instead of compress" },
+    "stdout":     { "kind": "option", "short": "-c", "summary": "Write to the pipe instead of a file" },
+    "options":    { "kind": "group", "summary": "Options", "members": ["decompress", "stdout"] },
+    "file":       { "kind": "positional", "type": "file", "name": "FILE", "summary": "File to process" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      { "type": "repeat", "child": { "type": "reference", "symbol": "options" } },
+      { "type": "reference", "symbol": "file" }
+    ]
+  }
+}

assets/disk0/tvdos/bin/help.alias

@@ -0,0 +1 @@
+synopsis $0

assets/disk0/tvdos/bin/hexdump.js.synopsis

@@ -0,0 +1,12 @@
+{
+  "tsfVersion": "1.0",
+  "name": "hexdump",
+  "summary": "Print a file as a hexadecimal dump",
+  "symbols": {
+    "file": { "kind": "positional", "type": "file", "name": "FILE", "summary": "File to dump; reads from the pipe when omitted" }
+  },
+  "synopsis": {
+    "type": "optional",
+    "child": { "type": "reference", "symbol": "file" }
+  }
+}

assets/disk0/tvdos/bin/hop.alias

@@ -0,0 +1 @@
+hopper $0

assets/disk0/tvdos/bin/hopper.js

@@ -1,5 +1,956 @@
 /**
- * Hopper is a package manager for TSVM
+ * Hopper is a package manager for TVDOS
  * Created by CuriousTorvald on 2026-04-16
  */
 
+const SYSTEM_PACKEAGE_DEF_DIR  = "A:/tvdos/hopper"
+const USER_BASE_DIR            = "A:/hopper"
+const USER_PACKAGE_DEF_DIR     = `${USER_BASE_DIR}/manifests`
+const USER_PACKAGE_BIN_DIR     = `${USER_BASE_DIR}/bin`
+const USER_PACKAGE_INCLUDE_DIR = `${USER_BASE_DIR}/include`
+const MANIFEST_EXT = "hop.per"
+const MIRROR_LIST_PATH = `${SYSTEM_PACKEAGE_DEF_DIR}/mirrors.list`
+
+const net = require("net")
+
+// SYNOPSIS
+// hopper {search,se} [--provides, --requires, --description, --author] query
+//// default searches from ProperName
+// hopper {install,in} query [-v version]
+// hopper {remove,rm} query
+
+// ============================================================
+// Manifest parsing
+// ============================================================
+
+function splitList(s) {
+    if (!s) return []
+    return s.split(";").map(it => it.trim()).filter(it => it.length > 0)
+}
+
+function parseManifest(text) {
+    const m = {}
+    text.split("\n").forEach(rawLine => {
+        const line = rawLine.replace(/\r$/, "")
+        if (line.length === 0) return
+        const idx = line.indexOf(":")
+        if (idx < 0) return
+        const key = line.substring(0, idx).trim()
+        const value = line.substring(idx + 1).trim()
+        m[key] = value
+    })
+    return m
+}
+
+function readManifestFile(path) {
+    const f = files.open(path)
+    if (!f.exists || f.isDirectory) return undefined
+    const m = parseManifest(f.sread())
+    m._manifestPath = path
+    return m
+}
+
+function _listManifestsFrom(dirPath, origin) {
+    const dir = files.open(dirPath)
+    if (!dir.exists || !dir.isDirectory) return []
+    const out = []
+    dir.list().forEach(entry => {
+        if (entry.isDirectory) return
+        if (!entry.name.toLowerCase().endsWith(MANIFEST_EXT)) return
+        const m = readManifestFile(entry.fullPath)
+        if (m !== undefined) {
+            m._origin = origin
+            out.push(m)
+        }
+    })
+    return out
+}
+
+// System packages (shipped with TVDOS) live in SYSTEM_PACKAGE_DEF_DIR
+// and are read-only as far as hopper is concerned. User packages,
+// installed by `hopper install`, live under USER_PACKAGE_DEF_DIR. The
+// resolver treats both as "installed", but the install/remove paths
+// refuse to modify anything tagged `_origin === "system"`.
+function listInstalledManifests() {
+    return _listManifestsFrom(SYSTEM_PACKEAGE_DEF_DIR, "system")
+        .concat(_listManifestsFrom(USER_PACKAGE_DEF_DIR, "user"))
+}
+
+function findInstalledManifest(name) {
+    // Prefer user-installed copy when a system package with the same name
+    // also exists -- but that combination is normally refused at install.
+    const userDirect = `${USER_PACKAGE_DEF_DIR}/${name}.${MANIFEST_EXT}`
+    let m = readManifestFile(userDirect)
+    if (m !== undefined) { m._origin = "user"; return m }
+
+    const sysDirect = `${SYSTEM_PACKEAGE_DEF_DIR}/${name}.${MANIFEST_EXT}`
+    m = readManifestFile(sysDirect)
+    if (m !== undefined) { m._origin = "system"; return m }
+
+    const all = listInstalledManifests()
+    for (let i = 0; i < all.length; i++) {
+        if ((all[i].HopperPackageName || "") === name) return all[i]
+    }
+    return undefined
+}
+
+// Yes/no prompt. Empty input falls back to `defaultYes`.
+function confirm(prompt, defaultYes) {
+    const hint = defaultYes ? "[Y/n]" : "[y/N]"
+    print(`${prompt} ${hint} `)
+    const ans = (read() || "").trim().toLowerCase()
+    if (ans === "") return !!defaultYes
+    return ans === "y" || ans === "yes"
+}
+
+// ============================================================
+// Install layout helpers
+// ============================================================
+//
+// User-installed packages live under `A:/hopper/`. Files are routed
+// by extension: `.mjs` includes go under `include/`, everything else
+// (`.js`, `.alias`, `.lfs`, data blobs, ...) lands in `bin/`. The
+// downloaded manifest is saved under `manifests/` with a
+// `SystemPackagePath` field appended that lists the resulting paths.
+
+// Strip query/fragment and take the last `/`-separated component of `url`.
+function urlBasename(url) {
+    let s = String(url || "")
+    const qm = s.indexOf("?");   if (qm   >= 0) s = s.substring(0, qm)
+    const hash = s.indexOf("#"); if (hash >= 0) s = s.substring(0, hash)
+    const slash = s.lastIndexOf("/")
+    return (slash < 0) ? s : s.substring(slash + 1)
+}
+
+function routeForBasename(name) {
+    return (String(name || "").toLowerCase().endsWith(".mjs"))
+        ? USER_PACKAGE_INCLUDE_DIR
+        : USER_PACKAGE_BIN_DIR
+}
+
+// Convert a USER_BASE_DIR-relative absolute path ("A:/hopper/bin/foo.js")
+// into its declarable form ("/hopper/bin/foo.js"), matching the
+// `SystemPackagePath` convention used by the system manifests.
+function declarablePath(absPath) {
+    let p = String(absPath || "").replace(/\\/g, "/")
+    if (/^[A-Za-z]:/.test(p)) p = p.substring(2)
+    return p
+}
+
+// Parse PackageFileList (semicolon-separated full URLs) into a list of
+// download descriptors: { url, basename, localPath }.
+function parsePackageFileList(s) {
+    const out = []
+    splitList(s || "").forEach(url => {
+        const base = urlBasename(url)
+        if (base.length === 0) return
+        const dir  = routeForBasename(base)
+        out.push({ url: url, basename: base, localPath: `${dir}/${base}` })
+    })
+    return out
+}
+
+function ensureUserDirs() {
+    [USER_BASE_DIR, USER_PACKAGE_BIN_DIR, USER_PACKAGE_INCLUDE_DIR, USER_PACKAGE_DEF_DIR].forEach(p => {
+        const d = files.open(p)
+        if (!d.exists) d.mkDir()
+    })
+}
+
+// Re-emit a parsed manifest, preserving insertion order, dropping
+// internal `_*` keys, and replacing any pre-existing SystemPackagePath
+// with the locally-computed one so the field always reflects what is
+// actually on disk.
+function serializeManifest(manifestObj, installedPathStr) {
+    const lines = []
+    Object.keys(manifestObj).forEach(k => {
+        if (k.length > 0 && k[0] === "_") return
+        if (k === "SystemPackagePath") return
+        lines.push(`${k}:${manifestObj[k]}`)
+    })
+    lines.push(`SystemPackagePath:${installedPathStr}`)
+    return lines.join("\n") + "\n"
+}
+
+// Delete every file declared in `manifest.SystemPackagePath` plus the
+// manifest file itself. Wildcards are expanded via `expandSystemPath`.
+function deleteInstalledFiles(manifest) {
+    const removed = []
+    splitList(manifest.SystemPackagePath || "").forEach(p => {
+        expandSystemPath(p).forEach(abs => {
+            const fd = files.open(abs)
+            if (!fd.exists) return
+            try { fd.remove(); removed.push(abs) }
+            catch (e) { printerrln(`  ! failed to remove ${abs}: ${e}`) }
+        })
+    })
+    if (manifest._manifestPath) {
+        const mfd = files.open(manifest._manifestPath)
+        if (mfd.exists) {
+            try { mfd.remove(); removed.push(manifest._manifestPath) }
+            catch (e) { printerrln(`  ! failed to remove ${manifest._manifestPath}: ${e}`) }
+        }
+    }
+    return removed
+}
+
+// ============================================================
+// SemVer (strict X.Y.Z) and constraint matching
+// ============================================================
+//
+// Versions are strict Semantic Versioning: three non-negative integer
+// components MAJOR.MINOR.PATCH. No pre-release / build metadata.
+//
+// Constraint grammar (intentionally small, expandable later):
+//   *           any version
+//   X.*         major X, any minor/patch
+//   X.Y.*       major X, minor Y, any patch
+//   X.Y.Z       exact
+//   ^X.Y.Z      >= X.Y.Z and < (X+1).0.0  (major-compatible)
+//   ~X.Y.Z      >= X.Y.Z and < X.(Y+1).0  (minor-compatible)
+//   >=X.Y.Z / >X.Y.Z / <=X.Y.Z / <X.Y.Z / =X.Y.Z
+//
+// Multiple comma-separated constraints are AND-ed: "^1.2.0,<1.5.0".
+
+function parseVersion(v) {
+    const m = String(v || "0.0.0").trim().match(/^(\d+)\.(\d+)\.(\d+)$/)
+    if (!m) return [0, 0, 0]
+    return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)]
+}
+
+function compareVersion(a, b) {
+    const A = parseVersion(a), B = parseVersion(b)
+    for (let i = 0; i < 3; i++) {
+        if (A[i] !== B[i]) return (A[i] < B[i]) ? -1 : 1
+    }
+    return 0
+}
+
+function _matchSingleConstraint(version, c) {
+    c = c.trim()
+    if (c === "" || c === "*") return true
+
+    // Operator form: ^, ~, >=, <=, >, <, =
+    let opMatch = c.match(/^(\^|~|>=|<=|>|<|=)\s*(\d+\.\d+\.\d+)$/)
+    if (opMatch) {
+        const op = opMatch[1]
+        const target = opMatch[2]
+        const cmp = compareVersion(version, target)
+        const [tM, tm] = parseVersion(target)
+        switch (op) {
+            case "=":  return cmp === 0
+            case ">":  return cmp >  0
+            case ">=": return cmp >= 0
+            case "<":  return cmp <  0
+            case "<=": return cmp <= 0
+            case "^":  return cmp >= 0 && compareVersion(version, `${tM + 1}.0.0`) < 0
+            case "~":  return cmp >= 0 && compareVersion(version, `${tM}.${tm + 1}.0`) < 0
+        }
+    }
+
+    // Wildcard form: X.*, X.Y.*, X.x, X.Y.x, or exact X.Y.Z
+    const parts = c.split(".")
+    const vparts = parseVersion(version)
+    for (let i = 0; i < parts.length && i < 3; i++) {
+        if (parts[i] === "*" || parts[i] === "x" || parts[i] === "X") return true
+        const expected = parseInt(parts[i], 10)
+        if (isNaN(expected) || vparts[i] !== expected) return false
+    }
+    // All listed parts matched literally; remaining parts (if any) must be 0
+    for (let i = parts.length; i < 3; i++) {
+        if (vparts[i] !== 0) return false
+    }
+    return true
+}
+
+function satisfies(version, constraint) {
+    if (!constraint) return true
+    return constraint.split(",").every(c => _matchSingleConstraint(version, c))
+}
+
+function parseRequires(s) {
+    const out = []
+    splitList(s || "").forEach(entry => {
+        // "<name>" or "<name> <constraint>"
+        const idx = entry.search(/\s+/)
+        if (idx < 0) {
+            out.push({ name: entry, constraint: "*" })
+        } else {
+            out.push({ name: entry.substring(0, idx), constraint: entry.substring(idx + 1).trim() })
+        }
+    })
+    return out
+}
+
+// HopperProvides entries are "<name>" or "<name> <version>". A bare name
+// falls back to the package's own HopperPackageVersion — the same idea
+// as RPM's `Provides: aalib = 1.2.0` (where the package's real name and
+// version may differ from the virtual identity it exposes).
+function parseProvides(s, fallbackVersion) {
+    const out = []
+    splitList(s || "").forEach(entry => {
+        const idx = entry.search(/\s+/)
+        if (idx < 0) {
+            out.push({ name: entry, version: fallbackVersion })
+        } else {
+            const v = entry.substring(idx + 1).trim()
+            out.push({ name: entry.substring(0, idx), version: v || fallbackVersion })
+        }
+    })
+    return out
+}
+
+// Look up the version a candidate exposes for `name`. If `name` matches
+// the package's own name (or isn't declared in HopperProvides at all),
+// returns the package's own version.
+function providedVersionOf(candidate, name) {
+    if (candidate.provides) {
+        for (let i = 0; i < candidate.provides.length; i++) {
+            if (candidate.provides[i].name === name) return candidate.provides[i].version
+        }
+    }
+    return candidate.version
+}
+
+// ============================================================
+// Candidate index (installed + upstream)
+// ============================================================
+
+function _manifestToCandidate(m, source) {
+    const name    = m.HopperPackageName || ""
+    const version = m.HopperPackageVersion || "0.0.0"
+    const provides = parseProvides(m.HopperProvides || "", version)
+    // Every package implicitly provides itself at its own version. Only
+    // synthesise this when the manifest didn't declare it explicitly.
+    if (name && !provides.some(p => p.name === name)) {
+        provides.unshift({ name: name, version: version })
+    }
+    return {
+        name:     name,
+        version:  version,
+        requires: parseRequires(m.HopperRequires || ""),
+        provides: provides,
+        source:   source, // "installed" | "upstream"
+        manifest: m
+    }
+}
+
+// Returns map: packageName -> array<Candidate>
+function buildCandidateIndex() {
+    const idx = new Map()
+    function add(c) {
+        if (!idx.has(c.name)) idx.set(c.name, [])
+        // De-dupe (name+version+source)
+        const arr = idx.get(c.name)
+        if (arr.some(x => x.version === c.version && x.source === c.source)) return
+        arr.push(c)
+    }
+
+    listInstalledManifests().forEach(m => add(_manifestToCandidate(m, "installed")))
+    fetchRemoteCandidates().forEach(m => add(_manifestToCandidate(m, "upstream")))
+
+    return idx
+}
+
+// Anything that satisfies a requirement on `name`: a package whose own
+// HopperPackageName matches OR whose HopperProvides declares `name`.
+// Each candidate now carries `provides` as {name, version} pairs; the
+// package's own (name, version) is always present (see
+// _manifestToCandidate), so a single pass over `provides` is enough.
+function findProviders(idx, name) {
+    const out = []
+    const seen = new Set()
+    idx.forEach(candidates => {
+        candidates.forEach(c => {
+            if (seen.has(c)) return
+            if (c.provides.some(p => p.name === name)) {
+                out.push(c)
+                seen.add(c)
+            }
+        })
+    })
+    return out
+}
+
+// Sort: installed first (no churn), then highest version, then upstream order.
+function sortCandidates(cands) {
+    return cands.slice().sort((a, b) => {
+        if (a.source !== b.source) return (a.source === "installed") ? -1 : 1
+        return -compareVersion(a.version, b.version)
+    })
+}
+
+// ============================================================
+// Resolver (snapshot-based backtracking; precursor to a SAT solver)
+// ============================================================
+//
+// State: chosen :: Map<packageName, Candidate>
+// At every choice point we snapshot the whole map so that backtracking
+// also undoes any transitive picks. The candidate ordering encodes the
+// preference policy:
+//
+//   1. Keep installed if it satisfies the constraint.
+//   2. Otherwise pick the newest upstream version that satisfies.
+//   3. If newer versions cause downstream conflicts, walk older versions
+//      (downgrade) until either something fits or candidates are exhausted.
+//
+// The structure is intentionally close to DPLL: each "decision" is the
+// candidate we assign to a variable, and "unit propagation" is the
+// recursive resolve() call over each requirement. Replacing this with
+// clause learning / a watched-literals scheme later would be local.
+
+function resolveAll(idx, requirements) {
+    const chosen = new Map()
+    const issues = []
+
+    function snapshot()           { return new Map(chosen) }
+    function restore(snap)        { chosen.clear(); snap.forEach((v, k) => chosen.set(k, v)) }
+
+    function _resolve(reqName, constraint, trail) {
+        const existing = chosen.get(reqName)
+        if (existing !== undefined) {
+            const v = providedVersionOf(existing, reqName)
+            return satisfies(v, constraint)
+                ? { ok: true }
+                : { ok: false, reason: `${reqName} pinned to ${v}, but ${trail.join(" -> ")} requires ${constraint}` }
+        }
+
+        const providers = findProviders(idx, reqName)
+        if (providers.length === 0) {
+            return { ok: false, reason: `no package provides "${reqName}" (required by ${trail.join(" -> ") || "<root>"})` }
+        }
+        // Satisfaction checks the virtual version the candidate exposes
+        // for `reqName` (HopperProvides), not necessarily the package's
+        // own HopperPackageVersion.
+        const matching = sortCandidates(providers.filter(c => satisfies(providedVersionOf(c, reqName), constraint)))
+        if (matching.length === 0) {
+            const versions = providers.map(p => `${providedVersionOf(p, reqName)}[${p.source}]`).join(", ")
+            return { ok: false, reason: `no version of "${reqName}" satisfies ${constraint} (available: ${versions})` }
+        }
+
+        let lastReason = null
+        for (let i = 0; i < matching.length; i++) {
+            const cand = matching[i]
+            const snap = snapshot()
+            chosen.set(cand.name, cand)
+
+            let allOk = true
+            const subTrail = trail.concat([`${cand.name}@${cand.version}`])
+            for (let j = 0; j < cand.requires.length; j++) {
+                const req = cand.requires[j]
+                const r = _resolve(req.name, req.constraint, subTrail)
+                if (!r.ok) {
+                    allOk = false
+                    lastReason = r.reason
+                    break
+                }
+            }
+            if (allOk) return { ok: true }
+            restore(snap)
+        }
+
+        return { ok: false, reason: lastReason || `no working candidate for "${reqName}"` }
+    }
+
+    requirements.forEach(req => {
+        const r = _resolve(req.name, req.constraint, [])
+        if (!r.ok) issues.push(r.reason)
+    })
+
+    return { chosen, issues }
+}
+
+// Compare resolved assignment against currently-installed state.
+function classifyPlan(idx, chosen) {
+    const installedByName = new Map()
+    listInstalledManifests().forEach(m => installedByName.set(m.HopperPackageName, m))
+
+    const actions = []
+    chosen.forEach((cand, name) => {
+        const inst = installedByName.get(name)
+        if (cand.source === "installed") {
+            actions.push({ action: "keep", name, version: cand.version })
+        }
+        else if (inst === undefined) {
+            actions.push({ action: "install", name, version: cand.version })
+        }
+        else {
+            const cmp = compareVersion(cand.version, inst.HopperPackageVersion)
+            if      (cmp > 0) actions.push({ action: "upgrade",   name, from: inst.HopperPackageVersion, to: cand.version })
+            else if (cmp < 0) actions.push({ action: "downgrade", name, from: inst.HopperPackageVersion, to: cand.version })
+            else              actions.push({ action: "reinstall", name, version: cand.version })
+        }
+    })
+    return actions
+}
+
+function printPlan(actions, target) {
+    const changing = actions.filter(a => a.action !== "keep")
+    if (changing.length === 0) {
+        println(`Nothing to do: ${target} is already installed and satisfied.`)
+        return
+    }
+    println("Plan:")
+    changing.forEach(a => {
+        switch (a.action) {
+            case "install":   println(`  + install    ${a.name} ${a.version}`); break
+            case "upgrade":   println(`  ^ upgrade    ${a.name} ${a.from} -> ${a.to}`); break
+            case "downgrade": println(`  v downgrade  ${a.name} ${a.from} -> ${a.to}`); break
+            case "reinstall": println(`  = reinstall  ${a.name} ${a.version}`); break
+        }
+    })
+}
+
+// ============================================================
+// Remote mirrors
+// ============================================================
+//
+// `mirrors.list` lives next to the installed package manifests.
+// Each non-empty, non-`#` line is the URL prefix of a Hopper mirror.
+// The mirror MUST expose `<prefix>mirror_manifest` (key:value pairs
+// describing the mirror) and `<prefix>filelist` (CSV with rows of
+// `packagename,version,hoppermanifest-filename`).
+//
+// Trailing slash on the prefix is optional and will be added if missing.
+
+function loadMirrorList() {
+    const f = files.open(MIRROR_LIST_PATH)
+    if (!f.exists || f.isDirectory) return []
+    return f.sread().split("\n")
+        .map(line => line.replace(/\r$/, "").trim())
+        .filter(line => line.length > 0 && line[0] !== "#")
+        .map(line => line.endsWith("/") ? line : (line + "/"))
+}
+
+function parseFileList(text) {
+    const out = []
+    text.split("\n").forEach(raw => {
+        const line = raw.replace(/\r$/, "").trim()
+        if (line.length === 0 || line[0] === "#") return
+        const parts = line.split(",")
+        if (parts.length < 3) return
+        out.push({
+            name:    parts[0].trim(),
+            version: parts[1].trim(),
+            file:    parts[2].trim(),
+        })
+    })
+    return out
+}
+
+function fetchManifestsFromMirror(prefix) {
+    const mfText = net.fetchText(prefix + "mirror_manifest")
+    if (mfText === null) {
+        printerrln(`  ! could not reach mirror: ${prefix}`)
+        return []
+    }
+    const mirror = parseManifest(mfText)
+    const mirrorName = mirror.HopperMirrorName || prefix
+
+    const flText = net.fetchText(prefix + "filelist")
+    if (flText === null) {
+        printerrln(`  ! mirror "${mirrorName}" has no filelist`)
+        return []
+    }
+
+    const out = []
+    parseFileList(flText).forEach(entry => {
+        const manifestText = net.fetchText(prefix + entry.file)
+        if (manifestText === null) {
+            printerrln(`  ! mirror "${mirrorName}" missing ${entry.file}`)
+            return
+        }
+        const m = parseManifest(manifestText)
+        m._mirrorName   = mirrorName
+        m._mirrorPrefix = prefix
+        m._manifestUrl  = prefix + entry.file
+        out.push(m)
+    })
+    return out
+}
+
+// Per-invocation memoisation. Search and install both pull the same
+// data; we only want to hit the network once per `hopper ...` call.
+let _remoteCache = null
+
+function fetchRemoteCandidates() {
+    if (_remoteCache !== null) return _remoteCache
+
+    const mirrors = loadMirrorList()
+    if (mirrors.length === 0) {
+        _remoteCache = []
+        return _remoteCache
+    }
+
+    if (!net.isAvailable()) {
+        printerrln("Warning: no HTTP modem attached; remote mirrors will be skipped.")
+        _remoteCache = []
+        return _remoteCache
+    }
+
+    const out = []
+    mirrors.forEach(prefix => {
+        fetchManifestsFromMirror(prefix).forEach(m => out.push(m))
+    })
+    _remoteCache = out
+    return _remoteCache
+}
+
+// ============================================================
+// Search
+// ============================================================
+
+function fieldCandidates(manifest, field) {
+    switch (field) {
+        case "provides":    return splitList(manifest.HopperProvides || "")
+        case "requires":    return splitList(manifest.HopperRequires || "")
+        case "description": return [manifest.ProperDescription || ""]
+        case "author":      return [manifest.ProperAuthor || ""]
+        default:            return [manifest.ProperName || "", manifest.HopperPackageName || ""]
+    }
+}
+
+function matchesQuery(manifest, field, query) {
+    const q = query.toLowerCase()
+    return fieldCandidates(manifest, field).some(c => c.toLowerCase().indexOf(q) >= 0)
+}
+
+function printSearchResult(m, origin) {
+    const name = m.ProperName || m.HopperPackageName || "(unnamed)"
+    const ver  = m.HopperPackageVersion || "?"
+    println(`  [${origin}] ${name} -- ${m.HopperPackageName} ${ver}`)
+    if (m.ProperDescription) println(`           ${m.ProperDescription}`)
+}
+
+function cmdSearch(args) {
+    let field = "name"
+    let query = undefined
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i]
+        if      (a === "--provides")    field = "provides"
+        else if (a === "--requires")    field = "requires"
+        else if (a === "--description") field = "description"
+        else if (a === "--author")      field = "author"
+        else if (a.startsWith("--"))    { printerrln(`Unknown option: ${a}`); return 1 }
+        else                            query = a
+    }
+    if (query === undefined) {
+        printerrln("Usage: hopper search [--provides|--requires|--description|--author] <query>")
+        return 1
+    }
+
+    println(`Searching installed packages in ${SYSTEM_PACKEAGE_DEF_DIR} ...`)
+    const sysHits = listInstalledManifests().filter(m => matchesQuery(m, field, query))
+    if (sysHits.length === 0) println("  (no matches)")
+    else sysHits.forEach(m => printSearchResult(m, "installed"))
+
+    println("")
+    println("Searching remote mirrors ...")
+    const remote = fetchRemoteCandidates()
+    if (remote.length === 0) {
+        println("  (no mirrors configured or reachable)")
+    }
+    else {
+        const netHits = remote.filter(m => matchesQuery(m, field, query))
+        if (netHits.length === 0) println("  (no matches)")
+        else netHits.forEach(m => printSearchResult(m, m._mirrorName || "remote"))
+    }
+
+    return 0
+}
+
+// ============================================================
+// Install
+// ============================================================
+//
+// Each upstream manifest declares its payload via `PackageFileList`,
+// a semicolon-separated list of full URLs. Hopper fetches each URL and
+// drops the result in /hopper/bin (default) or /hopper/include (.mjs).
+// The locally-saved manifest gets a `SystemPackagePath` field appended
+// listing the resulting absolute paths, which is what `cmdRemove` later
+// walks to clean up.
+
+function _installOne(action, candidate) {
+    const m = candidate.manifest
+    const files_ = parsePackageFileList(m.PackageFileList)
+    if (files_.length === 0) {
+        printerrln(`  ! ${candidate.name}: upstream manifest has no PackageFileList; cannot install`)
+        return false
+    }
+
+    // Fetch first, write second: a single 404 should not leave a
+    // half-installed package behind.
+    const fetched = []
+    for (let i = 0; i < files_.length; i++) {
+        const f = files_[i]
+        println(`  fetch  ${f.url}`)
+        const body = net.fetchText(f.url)
+        if (body === null || body === undefined) {
+            printerrln(`  ! failed to fetch ${f.url}`)
+            return false
+        }
+        fetched.push({ entry: f, body: body })
+    }
+
+    // If we are replacing an existing user-installed copy, remove its
+    // old files first so a renamed payload doesn't leave orphans.
+    if (action !== "install") {
+        const oldManifestPath = `${USER_PACKAGE_DEF_DIR}/${candidate.name}.${MANIFEST_EXT}`
+        const old = readManifestFile(oldManifestPath)
+        if (old !== undefined) {
+            splitList(old.SystemPackagePath || "").forEach(p => {
+                expandSystemPath(p).forEach(abs => {
+                    const fd = files.open(abs)
+                    if (fd.exists) {
+                        try { fd.remove() }
+                        catch (e) { printerrln(`  ! could not remove old ${abs}: ${e}`) }
+                    }
+                })
+            })
+        }
+    }
+
+    // Write payload files.
+    fetched.forEach(item => {
+        const fd = files.open(item.entry.localPath)
+        if (!fd.exists) fd.mkFile()
+        fd.swrite(item.body)
+        println(`  write  ${item.entry.localPath}`)
+    })
+
+    // Save the manifest with SystemPackagePath appended.
+    const sysPath = fetched.map(item => declarablePath(item.entry.localPath)).join(";")
+    const manifestPath = `${USER_PACKAGE_DEF_DIR}/${candidate.name}.${MANIFEST_EXT}`
+    const mfd = files.open(manifestPath)
+    if (!mfd.exists) mfd.mkFile()
+    mfd.swrite(serializeManifest(m, sysPath))
+    println(`  write  ${manifestPath}`)
+    return true
+}
+
+function cmdInstall(args) {
+    let query = undefined
+    let version = undefined
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "-v") { version = args[i + 1]; i++ }
+        else if (args[i].startsWith("--")) { printerrln(`Unknown option: ${args[i]}`); return 1 }
+        else query = args[i]
+    }
+    if (query === undefined) {
+        printerrln("Usage: hopper install <package> [-v <version>]")
+        return 1
+    }
+
+    const targetConstraint = version || "*"
+    const verSuffix = (targetConstraint !== "*") ? ` (${targetConstraint})` : ""
+    println(`Resolving ${query}${verSuffix} ...`)
+
+    const idx = buildCandidateIndex()
+
+    // Sanity check: target must exist in the index (installed or upstream).
+    if (findProviders(idx, query).length === 0) {
+        printerrln(`Error: package "${query}" not found (not on upstream, not installed).`)
+        return 4
+    }
+
+    // Seed order matters: the target goes FIRST so its (possibly tight)
+    // constraints can drive upgrades of dependencies. The installed-set
+    // requirements follow at "*" so the resolver still has to keep them
+    // alive (preferring installed candidates when their version still fits,
+    // otherwise upgrading or downgrading them).
+    const seed = [{ name: query, constraint: targetConstraint }]
+    listInstalledManifests().forEach(m => {
+        if (m.HopperPackageName === query) return
+        seed.push({ name: m.HopperPackageName, constraint: "*" })
+    })
+
+    const { chosen, issues } = resolveAll(idx, seed)
+    if (issues.length > 0) {
+        printerrln("Resolution failed:")
+        issues.forEach(reason => printerrln(`  - ${reason}`))
+        printerrln("")
+        printerrln("No solution found -- not installable.")
+        return 3
+    }
+
+    const plan = classifyPlan(idx, chosen)
+    printPlan(plan, query)
+
+    const changing = plan.filter(a => a.action !== "keep")
+    if (changing.length === 0) return 0
+
+    // Pre-flight: refuse to clobber system packages, and require every
+    // upstream candidate to actually carry a payload list.
+    const blockers = []
+    changing.forEach(a => {
+        const cand = chosen.get(a.name)
+        const inst = findInstalledManifest(a.name)
+        if (inst && inst._origin === "system") {
+            blockers.push(`${a.name}: cannot ${a.action} -- a system package with that name is already installed`)
+        }
+        if (cand && cand.source === "upstream" && !(cand.manifest.PackageFileList && cand.manifest.PackageFileList.length > 0)) {
+            blockers.push(`${a.name}: upstream manifest declares no PackageFileList`)
+        }
+    })
+    if (blockers.length > 0) {
+        printerrln("Cannot proceed:")
+        blockers.forEach(b => printerrln(`  - ${b}`))
+        return 5
+    }
+
+    if (!net.isAvailable()) {
+        printerrln("No HTTP modem attached; cannot fetch package files.")
+        return 6
+    }
+
+    println("")
+    if (!confirm("Proceed with installation?", true)) {
+        println("Aborted.")
+        return 0
+    }
+
+    ensureUserDirs()
+
+    let failed = 0
+    for (let i = 0; i < changing.length; i++) {
+        const a = changing[i]
+        const cand = chosen.get(a.name)
+        if (a.action === "install" || a.action === "reinstall") {
+            println(`${a.action} ${a.name} ${a.version}`)
+        } else {
+            println(`${a.action} ${a.name} ${a.from} -> ${a.to}`)
+        }
+        if (!_installOne(a.action, cand)) {
+            failed++
+            printerrln(`  ! ${a.name}: aborted`)
+            break
+        }
+    }
+    if (failed > 0) {
+        printerrln(`${failed} package(s) failed to install.`)
+        return 7
+    }
+
+    println("Done.")
+    return 0
+}
+
+// ============================================================
+// Remove
+// ============================================================
+
+// Convert a SystemPackagePath entry (e.g. "/tvdos/bin/taut*") into a
+// concrete list of files on the A: drive. Supports a simple '*' wildcard
+// in the filename component.
+function expandSystemPath(pattern) {
+    const sysDrive = "A:"
+
+    if (pattern.indexOf("*") < 0) {
+        return [`${sysDrive}${pattern}`]
+    }
+
+    const fwd = pattern.lastIndexOf("/")
+    const bck = pattern.lastIndexOf("\\")
+    const lastSep = Math.max(fwd, bck)
+    const dirPart  = (lastSep < 0) ? "" : pattern.substring(0, lastSep)
+    const namePart = (lastSep < 0) ? pattern : pattern.substring(lastSep + 1)
+
+    const dir = files.open(`${sysDrive}${dirPart}/`)
+    if (!dir.exists || !dir.isDirectory) return []
+
+    const escaped = namePart.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*")
+    const re = new RegExp(`^${escaped}$`, "i")
+
+    const out = []
+    dir.list().forEach(entry => {
+        if (entry.isDirectory) return
+        if (re.test(entry.name)) out.push(entry.fullPath)
+    })
+    return out
+}
+
+function cmdRemove(args) {
+    const query = args[0]
+    if (query === undefined) {
+        printerrln("Usage: hopper remove <package>")
+        return 1
+    }
+
+    const m = findInstalledManifest(query)
+    if (m === undefined) {
+        printerrln(`Package not installed: ${query}`)
+        return 2
+    }
+    if (m._origin === "system") {
+        printerrln(`Cannot remove ${query}: it is a system package.`)
+        return 6
+    }
+
+    const name = m.ProperName || m.HopperPackageName || query
+    const ver  = m.HopperPackageVersion || "?"
+    println(`Preparing removal of ${name} (${m.HopperPackageName} ${ver}) ...`)
+
+    const paths = splitList(m.SystemPackagePath || "")
+    println("")
+    println("The following files will be deleted:")
+    if (paths.length === 0) {
+        println("  (manifest declares no files)")
+    }
+    paths.forEach(p => {
+        const expanded = expandSystemPath(p)
+        if (expanded.length === 0) {
+            println(`  (no match on disk) ${p}`)
+        }
+        else {
+            expanded.forEach(e => println(`  ${e}`))
+        }
+    })
+    println(`  ${m._manifestPath}`)
+
+    println("")
+    if (!confirm("Proceed with removal?", false)) {
+        println("Aborted.")
+        return 0
+    }
+
+    const removed = deleteInstalledFiles(m)
+    removed.forEach(p => println(`  removed ${p}`))
+    if (removed.length === 0) println("  (nothing was removed)")
+    return 0
+}
+
+// ============================================================
+// Dispatch
+// ============================================================
+
+function printUsage() {
+    println("Hopper - Package manager for TVDOS")
+    println("")
+    println("Usage:")
+    println("  hopper {search,se} [--provides|--requires|--description|--author] <query>")
+    println("  hopper {install,in} <package> [-v <version>]")
+    println("  hopper {remove,rm} <package>")
+}
+
+const _hopperArgs = (typeof exec_args !== "undefined" && exec_args) ? exec_args.slice(1) : []
+const _hopperCmd  = _hopperArgs[0]
+const _hopperRest = _hopperArgs.slice(1)
+
+switch (_hopperCmd) {
+    case "search":
+    case "se":
+        return cmdSearch(_hopperRest)
+    case "install":
+    case "in":
+        return cmdInstall(_hopperRest)
+    case "remove":
+    case "rm":
+        return cmdRemove(_hopperRest)
+    case undefined:
+        printUsage()
+        return 0
+    default:
+        printerrln(`Unknown command: ${_hopperCmd}`)
+        printUsage()
+        return 1
+}

assets/disk0/tvdos/bin/less.js.synopsis

@@ -0,0 +1,12 @@
+{
+  "tsfVersion": "1.0",
+  "name": "less",
+  "summary": "View text a screen at a time",
+  "symbols": {
+    "file": { "kind": "positional", "type": "file", "name": "FILE", "summary": "File to view; reads from the pipe when omitted" }
+  },
+  "synopsis": {
+    "type": "optional",
+    "child": { "type": "reference", "symbol": "file" }
+  }
+}

assets/disk0/tvdos/bin/lfs.js

@@ -15,7 +15,10 @@ Uint16  Encoding
     10 00 : UTF-8
     10 01 : UTF-16BE
     10 02 : UTF-16LE
-Byte[5] Padding
+Byte    Flags
+    0b 0000 000r
+        r: path is relative
+Bytes[4] Reserved
 
 # FileBlocks
 Uint8    File type (only 1 is used)
@@ -28,27 +31,36 @@ instead of compressing individual files)
 
 function printUsage() {
     println(`Collects files under a directory into a single archive.
-Usage: lfs [-c/-x/-t] dest.lfs path\\to\\source
+Usage: lfs [-c/-x/-t] [-r] dest.lfs path\\to\\source
 To collect a directory into myarchive.lfs:
        lfs -c myarchive.lfs path\\to\\directory
+To collect a directory into myarchive.lfs, using relative path:
+       lfs -c -r myarchive.lfs path\\to\\directory
 To extract an archive to path\\to\\my\\files:
        lfs -x myarchive.lfs path\\to\\my\\files
 To list the collected files:
        lfs -t myarchive.lfs`)
 }
 
-let option = exec_args[1]
-const lfsPath = exec_args[2]
-const dirPath = exec_args[3]
+let option = undefined
+let useRelative = false
+const positional = []
+for (let i = 1; i < exec_args.length; i++) {
+    const a = exec_args[i]
+    if (a === undefined) continue
+    const au = a.toUpperCase()
+    if (au === "-C" || au === "-X" || au === "-T") option = au
+    else if (au === "-R") useRelative = true
+    else positional.push(a)
+}
+const lfsPath = positional[0]
+const dirPath = positional[1]
 
-
-if (option === undefined || lfsPath === undefined || option.toUpperCase() != "-T" && dirPath === undefined) {
+if (option === undefined || lfsPath === undefined || (option != "-T" && dirPath === undefined)) {
     printUsage()
     return 0
 }
 
-option = option.toUpperCase()
-
 
 function recurseDir(file, action) {
     if (!file.isDirectory) {
@@ -76,13 +88,14 @@ if ("-C" == option) {
         return 1
     }
 
-    let out = "TVDOSLFS\x01\x00\x00\x00\x00\x00\x00\x00"
+    const flagsByte = useRelative ? 0x01 : 0x00
+    let out = "TVDOSLFS\x01\x00\x00" + String.fromCharCode(flagsByte) + "\x00\x00\x00\x00"
     const rootDirPathLen = rootDir.fullPath.length
 
     recurseDir(rootDir, file=>{
         let f = files.open(file.fullPath)
         let flen = f.size
-        let fname = file.fullPath.substring(rootDirPathLen + 1)
+        let fname = useRelative ? file.fullPath.substring(rootDirPathLen + 1) : file.fullPath
         let plen = fname.length
 
         out += "\x01" + String.fromCharCode(
@@ -116,6 +129,8 @@ else if ("-T" == option || "-X" == option) {
         return 2
     }
 
+    const archiveRelative = (bytes.charCodeAt(11) & 0x01) !== 0
+
     if ("-X" == option && !rootDir.exists) {
         rootDir.mkDir()
     }
@@ -132,9 +147,12 @@ else if ("-T" == option || "-X" == option) {
 
         if ("-X" == option) {
             let filebytes = bytes.substring(curs, curs + filelen)
-            let outfile = files.open(`${rootDir.fullPath}\\${path}`)
+            // Fully qualified paths (e.g. "A:\foo\bar.txt") get their drive prefix
+            // stripped so the archive contents re-root under the destination dir.
+            let subPath = archiveRelative ? path : path.replace(/^[A-Za-z]:[\\\/]?/, "")
+            let outfile = files.open(`${rootDir.fullPath}\\${subPath}`)
 
-            mkDirs(files.open(`${rootDir.driveLetter}:${files.open(`${rootDir.fullPath}\\${path}`).parentPath}`))
+            mkDirs(files.open(`${outfile.driveLetter}:${outfile.parentPath}`))
             outfile.mkFile()
             outfile.swrite(filebytes)
         }

assets/disk0/tvdos/bin/lfs.js.synopsis

@@ -0,0 +1,34 @@
+{
+  "tsfVersion": "1.0",
+  "name": "lfs",
+  "summary": "Create, extract or list a Linear File Strip (.lfs) archive",
+  "description": "Bundles a directory tree into a single TVDOS Linear File Strip archive, or unpacks one. Exactly one mode must be given: -c creates ARCHIVE from PATH, -x extracts ARCHIVE into PATH, and -t lists the files in ARCHIVE (PATH is not used). Individual files are stored uncompressed; gzip the whole .lfs to compress it.",
+  "symbols": {
+    "create":   { "kind": "option", "short": "-c", "summary": "Create an archive from a directory" },
+    "extract":  { "kind": "option", "short": "-x", "summary": "Extract an archive into a directory" },
+    "list":     { "kind": "option", "short": "-t", "summary": "List the files stored in an archive" },
+    "relative": { "kind": "option", "short": "-r", "summary": "Store paths relative to the source directory (with -c)" },
+    "archive":  { "kind": "positional", "type": "file", "name": "ARCHIVE", "summary": "The .lfs archive file" },
+    "path":     { "kind": "positional", "type": "directory", "name": "PATH", "summary": "Source directory (-c) or destination directory (-x); unused for -t" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      {
+        "type": "choice",
+        "children": [
+          { "type": "reference", "symbol": "create" },
+          { "type": "reference", "symbol": "extract" },
+          { "type": "reference", "symbol": "list" }
+        ]
+      },
+      { "type": "optional", "child": { "type": "reference", "symbol": "relative" } },
+      { "type": "reference", "symbol": "archive" },
+      { "type": "optional", "child": { "type": "reference", "symbol": "path" } }
+    ]
+  },
+  "constraints": [
+    { "type": "cardinality", "symbols": ["create", "extract", "list"], "minimum": 1, "maximum": 1 },
+    { "type": "requires", "subject": "relative", "targets": ["create"] }
+  ]
+}

assets/disk0/tvdos/bin/microtone.alias

@@ -0,0 +1 @@
+taut $0

assets/disk0/tvdos/bin/movprobe.js.synopsis

@@ -0,0 +1,9 @@
+{
+  "tsfVersion": "1.0",
+  "name": "movprobe",
+  "summary": "Print metadata about a movie file",
+  "symbols": {
+    "file": { "kind": "positional", "type": "file", "name": "FILE", "summary": "Movie file to inspect" }
+  },
+  "synopsis": { "type": "reference", "symbol": "file" }
+}

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/playmp2.js.synopsis

@@ -0,0 +1,17 @@
+{
+  "tsfVersion": "1.0",
+  "name": "playmp2",
+  "summary": "Play an MP2 audio file",
+  "symbols": {
+    "interactive": { "kind": "option", "short": "-i", "summary": "Interactive mode (visualiser)" },
+    "options":     { "kind": "group", "summary": "Options", "members": ["interactive"] },
+    "file":        { "kind": "positional", "type": "file", "name": "FILE", "summary": "MP2 file to play" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      { "type": "reference", "symbol": "file" },
+      { "type": "repeat", "child": { "type": "reference", "symbol": "options" } }
+    ]
+  }
+}

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,112 +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()
-const TAD_INPUT_ADDR = SND_MEM_ADDR - 262144  // TAD input buffer (matches TAV packet 0x24)
-const TAD_DECODED_ADDR = SND_MEM_ADDR - 262144 + 65536  // 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) {
@@ -114,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
@@ -133,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) {
@@ -282,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/playtad.js.synopsis

@@ -0,0 +1,21 @@
+{
+  "tsfVersion": "1.0",
+  "name": "playtad",
+  "summary": "Play a TAD audio file",
+  "symbols": {
+    "interactive": { "kind": "option", "short": "-i", "summary": "Interactive mode (visualiser and progress bar)" },
+    "dump":        { "kind": "option", "short": "-d", "summary": "Dump coefficients (diagnostic)" },
+    "options":     { "kind": "group", "summary": "Options", "members": ["interactive", "dump"] },
+    "file":        { "kind": "positional", "type": "file", "name": "FILE", "summary": "TAD file to play" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      { "type": "reference", "symbol": "file" },
+      { "type": "repeat", "child": { "type": "reference", "symbol": "options" } }
+    ]
+  },
+  "constraints": [
+    { "type": "conflicts", "symbols": ["interactive", "dump"] }
+  ]
+}

assets/disk0/tvdos/bin/playtav.js

@@ -18,7 +18,7 @@ const ADDRESSING_INTERNAL = 0x02
 const SND_BASE_ADDR = audio.getBaseAddr()
 const SND_MEM_ADDR = audio.getMemAddr()
 const pcm = require("pcm")
-const AUDIO_DEVICE = 3
+const AUDIO_DEVICE = 0
 const MP2_FRAME_SIZE = [144,216,252,288,360,432,504,576,720,864,1008,1152,1440,1728]
 const TAV_TEMPORAL_LEVELS = 2
 
@@ -158,9 +158,6 @@ audio.purgeQueue(AUDIO_DEVICE)
 audio.setPcmMode(AUDIO_DEVICE)
 audio.setMasterVolume(AUDIO_DEVICE, 255)
 
-// set colour zero as half-opaque black
-graphics.setPalette(0, 0, 0, 0, 7)
-
 // Parse SSF-TC subtitle packet and add to event buffer (0x31)
 function parseSubtitlePacketTC(packetSize) {
     // Read subtitle index (24-bit, little-endian)
@@ -1749,7 +1746,9 @@ try {
                     tadInitialised = true
                 }
 
-                seqread.readBytes(payloadLen, SND_MEM_ADDR - 262144)
+                // tadInputBin lives at audio-local offset 917504 (post-bef85f6 memory map);
+                // the previous 262144 offset now points into the enlarged sampleBin.
+                seqread.readBytes(payloadLen, SND_MEM_ADDR - 917504)
                 audio.tadDecode()
                 audio.tadUploadDecoded(AUDIO_DEVICE, sampleLen)
             }
@@ -2463,6 +2462,6 @@ finally {
     audio.purgeQueue(AUDIO_DEVICE)
 }
 
-graphics.setPalette(0, 0, 0, 0, 0)
+graphics.resetPalette()
 con.move(cy, cx) // restore cursor
 return errorlevel

assets/disk0/tvdos/bin/playtav.js.synopsis

@@ -0,0 +1,23 @@
+{
+  "tsfVersion": "1.0",
+  "name": "playtav",
+  "summary": "Play a TAV video file",
+  "symbols": {
+    "interactive": { "kind": "option", "short": "-i", "summary": "Interactive mode" },
+    "filmGrain": {
+      "kind": "option",
+      "long": "--filter-film-grain",
+      "summary": "Apply a film-grain filter",
+      "value": { "name": "LEVEL", "type": "integer", "required": false, "summary": "Grain intensity" }
+    },
+    "options": { "kind": "group", "summary": "Options", "members": ["interactive", "filmGrain"] },
+    "file":    { "kind": "positional", "type": "file", "name": "FILE", "summary": "TAV file to play" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      { "type": "reference", "symbol": "file" },
+      { "type": "repeat", "child": { "type": "reference", "symbol": "options" } }
+    ]
+  }
+}

assets/disk0/tvdos/bin/playtev.js.synopsis

@@ -0,0 +1,18 @@
+{
+  "tsfVersion": "1.0",
+  "name": "playtev",
+  "summary": "Play a TEV video file",
+  "symbols": {
+    "interactive": { "kind": "option", "short": "-i", "summary": "Interactive mode" },
+    "debugMv":     { "kind": "option", "long": "-debug-mv", "summary": "Show motion-vector debug overlay" },
+    "options":     { "kind": "group", "summary": "Options", "members": ["interactive", "debugMv"] },
+    "file":        { "kind": "positional", "type": "file", "name": "FILE", "summary": "TEV file to play" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      { "type": "reference", "symbol": "file" },
+      { "type": "repeat", "child": { "type": "reference", "symbol": "options" } }
+    ]
+  }
+}

assets/disk0/tvdos/bin/playucf.js

@@ -307,7 +307,7 @@ for (let i = 0; i < cueElements.length; i++) {
             // Execute the player with modified environment
             exec_args[1] = targetPath
             if (playerFile) {
-                let playerPath = `A:\\tvdos\\bin\\${playerFile}.js`
+                let playerPath = `A:${_TVDOS.variables.DOSDIR}/bin/${playerFile}.js`
                 if (files.open(playerPath).exists) {
                     eval(files.readText(playerPath))
                 } else {
@@ -334,7 +334,7 @@ for (let i = 0; i < cueElements.length; i++) {
     }
 
     // Execute the appropriate player
-    let playerPath = `A:\\tvdos\\bin\\${playerFile}.js`
+    let playerPath = `A:${_TVDOS.variables.DOSDIR}/bin/${playerFile}.js`
     if (!files.open(playerPath).exists) {
         serial.println(`Warning: Player script not found: ${playerPath}`)
         continue

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/playwav.js.synopsis

@@ -0,0 +1,17 @@
+{
+  "tsfVersion": "1.0",
+  "name": "playwav",
+  "summary": "Play a WAV audio file",
+  "symbols": {
+    "interactive": { "kind": "option", "short": "-i", "summary": "Interactive mode (visualiser)" },
+    "options":     { "kind": "group", "summary": "Options", "members": ["interactive"] },
+    "file":        { "kind": "positional", "type": "file", "name": "FILE", "summary": "WAV file to play" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      { "type": "reference", "symbol": "file" },
+      { "type": "repeat", "child": { "type": "reference", "symbol": "options" } }
+    ]
+  }
+}

assets/disk0/tvdos/bin/printfile.js.synopsis

@@ -0,0 +1,9 @@
+{
+  "tsfVersion": "1.0",
+  "name": "printfile",
+  "summary": "Print a text file with line numbers",
+  "symbols": {
+    "file": { "kind": "positional", "type": "file", "name": "FILE", "summary": "Text file to print" }
+  },
+  "synopsis": { "type": "reference", "symbol": "file" }
+}

assets/disk0/tvdos/bin/synopsis.js

@@ -0,0 +1,180 @@
+/*
+ * synopsis.js -- system-wide help / tldr.
+ *
+ * Prints a command's human-targeted one-line summary and an auto-generated
+ * synopsis (usage line, arguments, options and constraints) derived from its
+ * TSF .synopsis document via the `synopsis` library (synopsis.mjs).
+ *
+ * Usage: synopsis PROGRAM
+ *        synopsis            (describes itself)
+ */
+
+let syn
+try {
+    syn = require("synopsis")
+} catch (e) {
+    printerrln("synopsis: the 'synopsis' library is not installed")
+    return 1
+}
+
+const termW = (con.getmaxyx()[1]) || 80
+
+// Word-wrap plain text to `width`, returning an array of lines.
+function wrap(text, width) {
+    if (!text) return []
+    if (width < 8) width = 8
+    let words = ('' + text).split(/\s+/).filter(function (w) { return w.length })
+    let lines = [], line = ''
+    words.forEach(function (w) {
+        if (line.length === 0) line = w
+        else if (line.length + 1 + w.length <= width) line += ' ' + w
+        else { lines.push(line); line = w }
+    })
+    if (line.length) lines.push(line)
+    return lines
+}
+
+// Print a "left  summary" row: the summary is wrapped into the right column and
+// continuation lines are aligned under it. An over-wide `left` spills onto its
+// own line.
+function row(left, summary, leftW, indent) {
+    let pad = ' '.repeat(indent)
+    let gap = 2
+    let sumW = Math.max(8, termW - indent - leftW - gap)
+    let wrapped = wrap(summary, sumW)
+    if (left.length > leftW) {
+        println(pad + left)
+        wrapped.forEach(function (l) { println(pad + ' '.repeat(leftW + gap) + l) })
+    } else {
+        let first = wrapped.length ? wrapped[0] : ''
+        println(pad + left + ' '.repeat(leftW - left.length + gap) + first)
+        for (let i = 1; i < wrapped.length; i++)
+            println(pad + ' '.repeat(leftW + gap) + wrapped[i])
+    }
+}
+
+// ---- resolve the target ----------------------------------------------------
+let token = (exec_args[1] !== undefined && exec_args[1] !== '') ? exec_args[1] : "synopsis"
+
+let model = syn.getModel(token)
+if (!model) {
+    printerrln(`synopsis: no synopsis found for '${token}'`)
+    return 1
+}
+
+// Display name for a referenced symbol id (used by the constraints section).
+function symDisplay(id) {
+    let s = model.symbols[id]
+    if (!s) return id
+    if (s.kind === 'option')     return s.long || s.short || id
+    if (s.kind === 'positional') return s.name || id
+    if (s.kind === 'subcommand') return s.name || id
+    return id
+}
+
+// Append a "{a, b, c}" hint of permitted values to a summary, if any.
+function withValues(summary, values) {
+    if (!values || !values.length) return summary || ''
+    let vs = values.map(function (v) {
+        return (v && typeof v === 'object' && ('value' in v)) ? v.value : v
+    }).join(', ')
+    return (summary ? summary + '  ' : '') + '{' + vs + '}'
+}
+
+// Left-column text for an option, e.g. "-o, --output=FILE".
+function optionLeft(e) {
+    let forms = []
+    if (e.short) forms.push(e.short)
+    if (e.long)  forms.push(e.long)
+    let s = forms.join(', ')
+    if (e.hasValue) {
+        let vn = (e.value && (e.value.name || e.value.type)) || 'VALUE'
+        if (e.long) s += e.valueRequired ? '=' + vn : '[=' + vn + ']'
+        else        s += e.valueRequired ? ' ' + vn : ' [' + vn + ']'
+    }
+    return s
+}
+function optionSummary(e) {
+    let s = e.summary || ''
+    if (e.negatable) s += (s ? ' ' : '') + '(negatable)'
+    if (e.value && e.value.values && e.value.values.length) s = withValues(s, e.value.values)
+    return s
+}
+
+function constraintText(c) {
+    let names = (c.symbols || []).map(symDisplay)
+    if (c.type === 'conflicts')  return 'Mutually exclusive: ' + names.join(', ')
+    if (c.type === 'requires')   return symDisplay(c.subject) + ' requires ' + (c.targets || []).map(symDisplay).join(', ')
+    if (c.type === 'implies')    return symDisplay(c.subject) + ' implies ' + (c.targets || []).map(symDisplay).join(', ')
+    if (c.type === 'cardinality') {
+        let mn = c.minimum, mx = c.maximum, q
+        if (mn === 1 && mx === 1) q = 'Exactly one of'
+        else if (mn === 1 && mx === undefined) q = 'At least one of'
+        else if (mn === undefined && mx === 1) q = 'At most one of'
+        else q = `Between ${mn} and ${mx} of`
+        return q + ': ' + names.join(', ')
+    }
+    return null
+}
+
+// ---- gather rows -----------------------------------------------------------
+let argEntries = model.positionals.map(function (p) {
+    return { left: (p.name || p.id) + (p.repeatable ? '...' : ''), summary: withValues(p.summary, p.values) }
+})
+let optEntries = model.flags.map(function (e) {
+    return { left: optionLeft(e), summary: optionSummary(e) }
+})
+let subEntries = model.subcommands.map(function (s) {
+    return { left: s.name, summary: s.summary || '' }
+})
+
+// shared left-column width (capped so a long flag does not push everything out)
+let leftW = 4
+argEntries.concat(optEntries, subEntries).forEach(function (e) { if (e.left.length > leftW) leftW = e.left.length })
+if (leftW > 30) leftW = 30
+
+// ---- render ----------------------------------------------------------------
+let title = model.name || token
+println(model.summary ? `${title} - ${model.summary}` : title)
+println()
+
+let usage = syn.getUsage(token)
+if (usage) {
+    println("Usage:")
+    println("    " + usage)
+    println()
+}
+
+if (model.description) {
+    wrap(model.description, termW).forEach(function (l) { println(l) })
+    println()
+}
+
+if (subEntries.length) {
+    println("Commands:")
+    subEntries.forEach(function (e) { row(e.left, e.summary, leftW, 4) })
+    println()
+}
+
+if (argEntries.length) {
+    println("Arguments:")
+    argEntries.forEach(function (e) { row(e.left, e.summary, leftW, 4) })
+    println()
+}
+
+if (optEntries.length) {
+    println("Options:")
+    optEntries.forEach(function (e) { row(e.left, e.summary, leftW, 4) })
+    println()
+}
+
+if (model.constraints && model.constraints.length) {
+    let lines = model.constraints.map(constraintText).filter(function (t) { return t })
+    if (lines.length) {
+        println("Constraints:")
+        lines.forEach(function (l) { println("    " + l) })
+        println()
+    }
+}
+
+return 0

assets/disk0/tvdos/bin/synopsis.js.synopsis

@@ -0,0 +1,13 @@
+{
+  "tsfVersion": "1.0",
+  "name": "synopsis",
+  "summary": "Print a command's summary and auto-generated synopsis",
+  "description": "Prints the one-line summary and an auto-generated usage line for PROGRAM, derived from its TSF .synopsis document, together with its arguments, options and constraints. With no PROGRAM, describes itself.",
+  "symbols": {
+    "program": { "kind": "positional", "type": "command", "name": "PROGRAM", "summary": "Command to describe; describes synopsis itself when omitted" }
+  },
+  "synopsis": {
+    "type": "optional",
+    "child": { "type": "reference", "symbol": "program" }
+  }
+}

assets/disk0/tvdos/bin/taut_fileop.js

@@ -0,0 +1,77 @@
+/**
+ * TAUT File Operations
+ * Sub-program launched by taut.js when the File tab is active.
+ * 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.
+ *
+ * Created by minjaesong on 2026-04-27
+ */
+
+const win = require("wintex")
+
+const PANEL_COUNT = 7
+const MY_PANEL   = 6 // VIEW_FILE
+
+const [SCRH, SCRW] = con.getmaxyx()
+const PANEL_Y = 4
+const PANEL_H = SCRH - PANEL_Y
+
+const colStatus  = 253
+const colContent = 240
+const colHdr     = 230
+
+function drawFileOpContents(wo) {
+    for (let y = PANEL_Y; y < SCRH; y++) {
+        con.move(y, 1)
+        con.color_pair(colContent, 255)
+        print(' '.repeat(SCRW))
+    }
+    con.move(PANEL_Y + 1, 3)
+    con.color_pair(colHdr, 255)
+    print('[ File ]')
+    con.move(PANEL_Y + 3, 3)
+    con.color_pair(colStatus, 255)
+    print('placeholder — not yet implemented')
+}
+
+function drawHints() {
+    con.move(SCRH, 1)
+    con.color_pair(colStatus, 255)
+    print(' '.repeat(SCRW - 1))
+    con.move(SCRH, 1)
+    con.color_pair(colHdr, 255); print('Tab ')
+    con.color_pair(colStatus, 255); print('Panel')
+}
+
+function fileOpInput(wo, event) {
+    // placeholder — no interaction yet
+}
+
+const panel = new win.WindowObject(1, PANEL_Y, SCRW, PANEL_H, fileOpInput, drawFileOpContents, undefined, ()=>{})
+
+panel.drawContents()
+drawHints()
+
+let done = false
+while (!done) {
+    input.withEvent(event => {
+        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
+            done = true
+            return
+        }
+
+        panel.processInput(event)
+    })
+}
+
+return 0

assets/disk0/tvdos/bin/taut_helpmsg.js

@@ -0,0 +1,172 @@
+if (!_G.TAUT) _G.TAUT = {};
+let help = {}
+
+let ts = require("typesetter")
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/*
+Tags:
+<b> - print the text in emphasis colour (colVoiceHdr aka 230)
+<s> - print the text in deemphasis colour (248)
+<c> - centre the line. If the line spans multiple lines, centre each line
+<r> - align right
+<l> - align left
+<o> - create virtual typesetting box. Left anchor: where the text cursor is. Right anchor: end of the line
+&microtone; - replace with the brand string (<col 211>Micro</col><col 239>tone</col>)
+
+&bul; - replace with bullet (\u00F9)
+&ddot; - replace with double-dot (\u008419u)
+&mdot; - replace with BIGDOT (\u00FA)
+&updn; - up-down arrow (\u008418u)
+&udlr; - four direction arrow (\u008428u\u008429u)
+
+&keyoffsym; - pattern view key-off symbol (\u00A0\u00B1\u00B1\u00A1)
+&notecutsym; - pattern view note-cut symbol (\u00A4\u00A4\u00A4\u00A4)
+
+&demisharp;
+&sharp;
+&sesquisharp;
+&doublesharp;
+&triplesharp;
+&quadsharp;
+&demiflat;
+&flat;
+&sesquiflat;
+&doubleflat;
+&tripleflat;
+&quadflat;
+&accuptick;
+&accdntick;
+&accupup;
+&accdndn;
+
+&nbsp; - nonbreakable space (only meaningful for typesetters)
+&shy; - soft hyphen (only meaningful for typesetters)
+
+default alignment: fully justified
+ */
+
+let helpNotation = `<c>CONTROL NOTATION</c>
+<c>\u00B7${'\u00B8'.repeat(16)}\u00B9</c>
+&microtone; <O>shortcuts differentiate normal and shifted shortcuts.</O>
+&bul;<b>a</b>&ddot;<b>z</b> : <O>alphabet without shift-in</O>
+&bul;<b>A</b>&ddot;<b>Z</b> : <O>alphabet with shift-in</O>
+&bul;<b>^q</b> : <O>hit 'q' with control key</O>
+&bul;<b>^Q</b> : <O>hit 'q' with control and shift key</O>
+`
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+let helpJam = `<c>NOTE JAMMING</c>
+<c>\u00B7${'\u00B8'.repeat(12)}\u00B9</c>
+Push keys to play or insert notes.
+&nbsp;w&nbsp;e&nbsp;&nbsp;&nbsp;t&nbsp;y&nbsp;u
+a&nbsp;s&nbsp;d&nbsp;f&nbsp;g&nbsp;h&nbsp;j&nbsp;k
+`
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+let helpCommon = `<c>COMMON CONTROLS</c>
+<c>\u00B7${'\u00B8'.repeat(15)}\u00B9</c>
+&bul;<b>!</b> : <O>show this help message</O>
+&bul;<b>Y</b> : <O>plays the entire song from the current cue</O>
+&bul;<b>U</b> : <O>plays the current cue then stop</O>
+&bul;<b>I</b> : <O>plays the current row</O>
+&bul;<b>O</b> : <O>stops the playback</O>
+&bul;<b>tab</b> : <O>switchs forward a tab</O>
+&bul;<b>TAB</b> : <O>switchs backward a tab</O>
+&bul;<b>q</b> : <O>closes &microtone;</O>
+`
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+let helpTimeline = `<c>TIMELINE VIEW</c>
+<c>\u00B7${'\u00B8'.repeat(13)}\u00B9</c>
+Timeline has two distinct modes: view and edit mode. Two modes are toggled using the space bar.
+
+<b>&nbsp;VIEW MODE</b>
+<b>\u00B7${'\u00B8'.repeat(9)}\u00B9</b>
+&bul;Note jamming : <O>plays the note</O>
+&bul;<b>&udlr;</b> : <O>moves the viewing cursor by voices and rows</O>
+&bul;<b>pg&updn;</b> : <O>goes to previous/next cue</O>
+&bul;<b>W</b>&mdot;<b>E</b>&mdot;<b>R</b> : <O>toggles timeline view mode. W-most detailed, R-most abridged</O>
+&bul;<b>n</b> : <O>toggles soloing of the selected voice</O>
+&bul;<b>m</b> : <O>toggles muting of the selected voice</O>
+&bul;<b>[</b>&mdot;<b>]</b> : <O>changes tick rate of playhead</O>
+
+<b>&nbsp;EDIT MODE</b>
+<b>\u00B7${'\u00B8'.repeat(9)}\u00B9</b>
+&bul;Note jamming : <O>(note column) inserts the note</O>
+&bul;<b>{</b>&mdot;<b>}</b> : <O>(note column) lowers/raises a note by one octave (or period)</O>
+&bul;<b>[</b>&mdot;<b>]</b> : <O>(note column) lowers/raises a note by one unit</O>
+&bul;<b>z</b> : <O>(note column) inserts a key-off &keyoffsym;</O>
+&bul;<b>x</b> : <O>(note column) inserts a note-cut &notecutsym;</O>
+&bul;<b>.</b> : <O>clears fields</O>
+&bul;<b>bksp</b> : <O>deletes one character on the selected column</O>
+&bul;<b>0</b>&ddot;<b>9</b> <b>a</b>&ddot;<b>f</b> : <O>inserts a (hexa)decimal number</O>
+&bul;<b>0</b>&ddot;<b>9</b> <b>a</b>&ddot;<b>z</b> : <O>(fx column) inserts an effect</O>
+&bul;<b>^</b>&mdot;<b>v</b> : <O>(volume column) slide up/down</O>
+&bul;<b>&lt;</b>&mdot;<b>&gt;</b>: <O>(panning column) slide left/right</O>
+&bul;<b>-</b>&mdot;<b>=</b> : <O>(vol/pan col) fine slide down/up</O>
+&bul;<b>&udlr;</b> : <O>moves the viewing cursor by columns and rows</O>
+&bul;<b>pg&updn;</b> : <O>goes to previous/next cue</O>
+
+<b>&nbsp;ACCIDENTALS</b>
+<b>\u00B7${'\u00B8'.repeat(11)}\u00B9</b>
+&demisharp;&nbsp;&sharp;&nbsp;&doublesharp;&nbsp;&triplesharp;&nbsp;&quadsharp;&nbsp;&demiflat;&nbsp;&flat;&nbsp;&doubleflat;&nbsp;&tripleflat;&nbsp;&nbsp;&accuptick;&nbsp;&nbsp;&accupup;&nbsp;&nbsp;&accdntick;&nbsp;&nbsp;&accdndn;
+<b>C&nbsp;&nbsp;c&nbsp;&nbsp;cx&nbsp;x&nbsp;&nbsp;xx&nbsp;B&nbsp;&nbsp;b&nbsp;&nbsp;bb&nbsp;bbb&nbsp;^&nbsp;&nbsp;^^&nbsp;v&nbsp;&nbsp;vv</b>
+
+<b>&nbsp;GLOBAL EDIT</b>
+<b>\u00B7${'\u00B8'.repeat(11)}\u00B9</b>
+&bul;<b>Q</b> : <O>retunes current song into different tuning and strategy. In general, nearest-note works best for macrotonals, nearest-harmonic and nearest-delta works best for highly microtonals (31+); 17- and 19-TET takes nearest-harmonic pretty well, while 22-TET seem to only benefit from the nearest-note</O>
+`
+
+let helpProjectFlags = `<c>MIXER FLAGS</c>
+<c>\u00B7${'\u00B8'.repeat(11)}\u00B9</c>
+Mixer flags define how should the mixer behave.
+
+<b>&nbsp;TONE MODE</b>
+<b>\u00B7${'\u00B8'.repeat(9)}\u00B9</b>
+&bul;Linear pitch : <O>pitch shift effects operate on linear pitch scale. The default and recommended setting for a new project</O>
+&bul;Amiga pitch : <O>pitch shift effects operate on Amiga period scale. Backwards compatible setting for MOD/S3M/XM/IT formats</O>
+&bul;Linear freq : <O>pitch shift effects operate on linear frequency scale. Backwards compatible setting for MONOTONE format</O>
+
+<b>&nbsp;INTERPOLATION</b>
+<b>\u00B7${'\u00B8'.repeat(13)}\u00B9</b>
+&bul;Default : <O>three-tap fast sinc interpolation. The default and recommended setting for a new project</O>
+&bul;None : <O>zeroth-order hold</O>
+&bul;A500 : <O>emulates what Paula chip of Amiga 500 does. <b>S 0x00</b> effects only work with this and Amiga 1200 mode</O>
+&bul;A1200 : <O>emulates what Paula chip of Amiga 1200 does</O>
+&bul;SNES : <O>four-tap gaussian interpolation used by SNES</O>
+&bul;DPCM : <O>simulates Differential Pulse Code Modulation used by NES</O>
+`
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+// assemble help text pieces to complete help message
+
+const HRULE = '<s>' + '\u00B3'.repeat(_G.TAUT.HELPMSG_WIDTH) + '</s>\n'
+
+// taut.js's popup uses (HELP_COL_TEXT on background) as the default colour pair.
+// The shared typesetter module owns the palette and the markup expander.
+function typeset(text) {
+    return ts.typeset(text, _G.TAUT.HELPMSG_WIDTH)
+}
+
+let helpMessages = [ // index: taut.js PANEL_NAMES
+    /* Timeline */[helpJam, helpTimeline, helpCommon, helpNotation].join(HRULE),
+    /* Cues */[helpCommon, helpNotation].join(HRULE), // placeholder
+    /* Patterns */[helpCommon, helpNotation].join(HRULE), // placeholder
+    /* Samples */[helpCommon, helpNotation].join(HRULE), // placeholder
+    /* Instruments */[helpCommon, helpNotation].join(HRULE), // placeholder
+    /* Project */[helpProjectFlags, helpCommon, helpNotation].join(HRULE), // placeholder
+    /* File */[helpCommon, helpNotation].join(HRULE), // placeholder
+]
+
+help.MSG_BY_TABS = helpMessages.map(it => typeset(it))
+help.typeset     = typeset
+help.COL_TEXT    = ts.COL_TEXT
+help.COL_EMPH    = ts.COL_EMPH
+
+if (!_G.TAUT.HELPMSG) _G.TAUT.HELPMSG=help;

assets/disk0/tvdos/bin/taut_instredit.js

@@ -0,0 +1,77 @@
+/**
+ * TAUT Instrument Editor
+ * Sub-program launched by taut.js when the Instrmnt tab is active.
+ * 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.
+ *
+ * Created by minjaesong on 2026-04-27
+ */
+
+const win = require("wintex")
+
+const PANEL_COUNT = 7
+const MY_PANEL   = 4 // VIEW_INSTRMNT
+
+const [SCRH, SCRW] = con.getmaxyx()
+const PANEL_Y = 4
+const PANEL_H = SCRH - PANEL_Y
+
+const colStatus  = 253
+const colContent = 240
+const colHdr     = 230
+
+function drawInstEditContents(wo) {
+    for (let y = PANEL_Y; y < SCRH; y++) {
+        con.move(y, 1)
+        con.color_pair(colContent, 255)
+        print(' '.repeat(SCRW))
+    }
+    con.move(PANEL_Y + 1, 3)
+    con.color_pair(colHdr, 255)
+    print('[ Instrument Editor ]')
+    con.move(PANEL_Y + 3, 3)
+    con.color_pair(colStatus, 255)
+    print('placeholder — not yet implemented')
+}
+
+function drawHints() {
+    con.move(SCRH, 1)
+    con.color_pair(colStatus, 255)
+    print(' '.repeat(SCRW - 1))
+    con.move(SCRH, 1)
+    con.color_pair(colHdr, 255); print('Tab ')
+    con.color_pair(colStatus, 255); print('Panel')
+}
+
+function instEditInput(wo, event) {
+    // placeholder — no interaction yet
+}
+
+const panel = new win.WindowObject(1, PANEL_Y, SCRW, PANEL_H, instEditInput, drawInstEditContents, undefined, ()=>{})
+
+panel.drawContents()
+drawHints()
+
+let done = false
+while (!done) {
+    input.withEvent(event => {
+        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
+            done = true
+            return
+        }
+
+        panel.processInput(event)
+    })
+}
+
+return 0

assets/disk0/tvdos/bin/taut_sampleedit.js

@@ -0,0 +1,181 @@
+/**
+ * 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
+ *   [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 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
+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
+
+// 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, colBack)
+        print(' '.repeat(SCRW))
+    }
+    // Title
+    con.move(PANEL_Y + 1, 3)
+    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, colBack)
+    print(' '.repeat(SCRW - 1))
+    con.move(SCRH, 1)
+    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) {
+    // wintex panel input — wired up but the loop below handles keys directly.
+}
+
+function drawAll() {
+    drawSampleEditFrame()
+    drawToolList()
+    drawHints()
+}
+
+const panel = new win.WindowObject(1, PANEL_Y, SCRW, PANEL_H, sampleEditInput, drawAll, undefined, ()=>{})
+
+panel.drawContents()
+
+let done = false
+while (!done) {
+    input.withEvent(event => {
+        if (event[0] !== 'key_down') return
+        const keysym     = event[1]
+        const keyJustHit = (1 == event[2])
+
+        if (!keyJustHit) return
+
+        if (keysym === '<ESCAPE>' || keysym === '<TAB>') {
+            _G.TAUT.UI.NEXTPANEL = PARENT_PANEL
+            done = true
+            return
+        }
+
+        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
+            }
+        }
+    })
+}
+
+return 0

assets/disk0/tvdos/bin/tautbtn.r8

@@ -0,0 +1 @@
+<EFBFBD><EFBFBD>洄洄洄洄洄泚<EFBFBD>泚<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>_<EFBFBD>_

assets/disk0/tvdos/bin/tautbtn0.r8

@@ -0,0 +1 @@
+<EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD><EFBFBD>

assets/disk0/tvdos/bin/tee.js.synopsis

@@ -0,0 +1,9 @@
+{
+  "tsfVersion": "1.0",
+  "name": "tee",
+  "summary": "Copy a pipe's stream to a file and pass it on",
+  "symbols": {
+    "file": { "kind": "positional", "type": "path", "name": "FILE", "summary": "File to write the stream to" }
+  },
+  "synopsis": { "type": "reference", "symbol": "file" }
+}

assets/disk0/tvdos/bin/touch.js.synopsis

@@ -0,0 +1,17 @@
+{
+  "tsfVersion": "1.0",
+  "name": "touch",
+  "summary": "Update a file's modification time, creating it if absent",
+  "symbols": {
+    "noCreate": { "kind": "option", "short": "-c", "summary": "Do not create the file if it does not exist" },
+    "options":  { "kind": "group", "summary": "Options", "members": ["noCreate"] },
+    "file":     { "kind": "positional", "type": "path", "name": "FILE", "summary": "File to touch" }
+  },
+  "synopsis": {
+    "type": "sequence",
+    "children": [
+      { "type": "repeat", "child": { "type": "reference", "symbol": "options" } },
+      { "type": "reference", "symbol": "file" }
+    ]
+  }
+}

assets/disk0/tvdos/bin/writeto.js.synopsis

@@ -0,0 +1,9 @@
+{
+  "tsfVersion": "1.0",
+  "name": "writeto",
+  "summary": "Write a pipe's stream to a file",
+  "symbols": {
+    "file": { "kind": "positional", "type": "path", "name": "FILE", "summary": "File to write the stream to" }
+  },
+  "synopsis": { "type": "reference", "symbol": "file" }
+}

assets/disk0/tvdos/hopper/getopt.hop.per

@@ -0,0 +1,11 @@
+HopperManifestVersion:1
+HopperPackageName:getopt
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:getopt;
+HopperRequires:
+ProperName:getopt.js
+ProperAuthor:David Pacheco
+ProperDescription:node.js implementation of POSIX getopt() (and then some)
+Licence:MIT
+SystemPackagePath:/tvdos/include/getopt.mjs

assets/disk0/tvdos/hopper/libfs.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:libfs
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:libfs;
+HopperRequires:tvdos 1.*;
+ProperName:LibFS
+ProperAuthor:CuriousTorvald
+ProperDescription:NodeJS-compatible Filesystem module for TVDOS
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/fs.mjs

assets/disk0/tvdos/hopper/libgl.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:libgl
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:libgl;
+HopperRequires:
+ProperName:LibGL
+ProperAuthor:CuriousTorvald
+ProperDescription:TVDOS Graphics Library
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/gl.mjs

assets/disk0/tvdos/hopper/libpcm.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:libpcm
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:libpcm;
+HopperRequires:
+ProperName:LibPCM
+ProperAuthor:CuriousTorvald
+ProperDescription:PCM decoder for TSVM
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/pcm.mjs

assets/disk0/tvdos/hopper/libpsg.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:libpsg
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:libpsg;
+HopperRequires:
+ProperName:LibPSG
+ProperAuthor:CuriousTorvald
+ProperDescription:Programmable sound generator library for TSVM
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/psg.mjs

assets/disk0/tvdos/hopper/libseqread.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:libseqread
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:libseqread;
+HopperRequires:tvdos 1.*;
+ProperName:LibSeqread
+ProperAuthor:CuriousTorvald
+ProperDescription:Sequentially read files from disk drive
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/seqread.mjs;/tvdos/include/seqreadtape.mjs

assets/disk0/tvdos/hopper/libtaud.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:libtaud
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:libtaud;
+HopperRequires:tvdos 1.*;
+ProperName:LibTaud
+ProperAuthor:CuriousTorvald
+ProperDescription:Helper functions for interaction between Taud format and TSVM Tracker
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/taud.mjs

assets/disk0/tvdos/hopper/libterranbasic.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:libterranbasic
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:libterranbasic;
+HopperRequires:
+ProperName:LibTerranBasic
+ProperAuthor:CuriousTorvald
+ProperDescription:Terran BASIC runtime helper for compiled programs
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/tbas.mjs

assets/disk0/tvdos/hopper/microtone.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:microtone
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:microtone;
+HopperRequires:tvdos 1.*;wintex 1.*;libtaud 1.*;libgl 1.*
+ProperName:Microtone
+ProperAuthor:CuriousTorvald
+ProperDescription:Microtonal tracker for TSVM
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/bin/microtone.alias;/tvdos/bin/taut*

assets/disk0/tvdos/hopper/mirrors.list

@@ -0,0 +1,17 @@
+# Hopper Mirror List
+#
+# One mirror per non-empty, non-comment line.
+# Each entry is the remote URL prefix from which Hopper can fetch
+#     <prefix>mirror_manifest
+#     <prefix>filelist
+#     <prefix><package>.hop.per   (one per row of filelist)
+#
+# `mirror_manifest` declares HopperMirrorName, HopperMirrorMaintainer
+# and HopperMirrorRemotePrefix; `filelist` is CSV of
+#     packagename,version,hoppermanifest-filename
+#
+# Lines starting with `#` and empty lines are ignored.
+# A trailing slash on the prefix is optional; Hopper will add one
+# if missing.
+
+https://raw.githubusercontent.com/curioustorvald/hopper-mirror/refs/heads/master/

assets/disk0/tvdos/hopper/textedit.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:textedit
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:edit;
+HopperRequires:tvdos 1.*
+ProperName:edit.js
+ProperAuthor:CuriousTorvald
+ProperDescription:TVDOS default text editor
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/bin/edit.js

assets/disk0/tvdos/hopper/tvdos.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:tvdos
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:tvdos;
+HopperRequires:
+ProperName:TVDOS
+ProperAuthor:CuriousTorvald
+ProperDescription:TSVM Disk Operating System
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/TVDOS.SYS;/tvdos/hyve.SYS;/tvdos/HSDPADRV.SYS;/tvdos/bin/command.js;/tvdos/sbin/sysctl.js;/tvdos/include/font.mjs;/tvdos/include/keysym.mjs;/tvdos/include/mload.mjs;/tvdos/include/playgui.mjs;/tvdos/include/typesetter.mjs

assets/disk0/tvdos/hopper/wintex.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:wintex
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:wintex;
+HopperRequires:
+ProperName:WinTex
+ProperAuthor:CuriousTorvald
+ProperDescription:TUI window management and renderer
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/include/wintex.mjs

assets/disk0/tvdos/hopper/zfm.hop.per

@@ -0,0 +1,12 @@
+HopperManifestVersion:1
+HopperPackageName:zfm
+HopperPackageVersion:1.0.0
+HopperPackageMaintainer:CuriousTorvald
+HopperProvides:zfm;
+HopperRequires:tvdos 1.*;wintex 1.*
+ProperName:ZFM
+ProperAuthor:CuriousTorvald
+ProperDescription:Z File Manager - Dual-panel file manager for TVDOS
+Licence:MIT
+SupportMe:https://github.com/sponsors/curioustorvald/
+SystemPackagePath:/tvdos/bin/zfm*

assets/disk0/tvdos/include/font.mjs

@@ -0,0 +1,31 @@
+function setHighRom(fullPath) {
+    const fontFile = files.open(fullPath)
+
+    // upload font
+    const fontData = fontFile.bread()
+    for (let i = 0; i < 1920; i++) sys.poke(-133121 - i, fontData[i])
+    sys.poke(-1299460, 19) // write to high rom
+
+    fontFile.close()
+}
+
+function setLowRom(fullPath) {
+    const fontFile = files.open(fullPath)
+
+    // upload font
+    const fontData = fontFile.bread()
+    for (let i = 0; i < 1920; i++) sys.poke(-133121 - i, fontData[i])
+    sys.poke(-1299460, 18) // write to low rom
+
+    fontFile.close()
+}
+
+function resetHighRom() {
+    sys.poke(-1299460, 21)
+}
+
+function resetLowRom() {
+    sys.poke(-1299460, 20)
+}
+
+exports = { setHighRom, setLowRom, resetHighRom, resetLowRom }

assets/disk0/tvdos/include/gl.mjs

@@ -45,7 +45,7 @@ exports.SpriteSheet = function(tilew, tileh, tex) {
         return ty;
     };
 };
-exports.drawTexPattern = function(texture, x, y, width, height, framebuffer, fgcol, bgcol) {
+exports.drawTexPattern = function(texture, x, y, width = texture.width, height = texture.height, framebuffer = false, fgcol, bgcol) {
     if (!(texture instanceof exports.Texture) && !(texture instanceof exports.MonoTex)) throw Error("Texture is not a GL Texture types");
 
     let paint = (!framebuffer) ? graphics.plotPixel : graphics.plotPixel2

assets/disk0/tvdos/include/keysym.mjs

@@ -0,0 +1,80 @@
+/**
+ * These are key symbols returned by `input.withEvent`, NOT `con.getch()`
+ */
+
+exports = {
+NUM_0:7,
+NUM_1:8,
+NUM_2:9,
+NUM_3:10,
+NUM_4:11,
+NUM_5:12,
+NUM_6:13,
+NUM_7:14,
+NUM_8:15,
+NUM_9:16,
+A:29,
+ALT_LEFT:57,
+ALT_RIGHT:58,
+APOSTROPHE:75,
+AT:77,
+B:30,
+BACK:4,
+BACKSLASH:73,
+C:31,
+CAPS_LOCK:115,
+COMMA:55,
+D:32,
+DEL:67,
+BACKSPACE:67,
+FORWARD_DEL:112,
+DOWN:20,
+LEFT:21,
+RIGHT:22,
+UP:19,
+E:33,
+ENTER:66,
+EQUALS:70,
+F:34,
+G:35,
+GRAVE:68,
+H:36,
+HOME:3,
+I:37,
+J:38,
+K:39,
+L:40,
+LEFT_BRACKET:71,
+M:41,
+MINUS:69,
+N:42,
+O:43,
+P:44,
+PERIOD:56,
+PLUS:81,
+Q:45,
+R:46,
+RIGHT_BRACKET:72,
+S:47,
+SEMICOLON:74,
+SHIFT_LEFT:59,
+SHIFT_RIGHT:60,
+SLASH:76,
+SPACE:62,
+SYM:63, // on MacOS, this is Command (⌘)
+T:48,
+TAB:61,
+U:49,
+V:50,
+W:51,
+X:52,
+Y:53,
+Z:54,
+CONTROL_LEFT:129,
+CONTROL_RIGHT:130,
+ESCAPE:111,
+END:123,
+INSERT:124,
+PAGE_UP:92,
+PAGE_DOWN:93,
+}

assets/disk0/tvdos/include/lfs.mjs

@@ -0,0 +1,171 @@
+/*
+ * lfs.mjs — programmatic extractor for TVDOS Linear File Strip archives.
+ *
+ *   let lfs = require("A:/tvdos/include/lfs.mjs")
+ *
+ *   // Pull one entry out:
+ *   let fd  = lfs.extractOne("A:/path/archive.lfs", "wanted.bin")
+ *   // → file descriptor for $:/TMP/<random>/wanted.bin
+ *
+ *   // Unpack the whole archive:
+ *   let dir = lfs.extractAll("A:/path/archive.lfs")
+ *   // → directory descriptor for $:/TMP/<random>/
+ *
+ * Both functions accept an `autoDecompress` boolean (default true). When
+ * a payload's first four bytes match the gzip (1F 8B 08 xx) or zstd
+ * (28 B5 2F FD) magic, the payload is inflated through gzip.decomp()
+ * before being written. The check is done on the payload bytes — the
+ * archived filename is irrelevant.
+ *
+ * Both functions require a relative-path archive (one produced by
+ * `lfs -c -r`); fully qualified archives carry drive letters that would
+ * not make sense rerooted under $:/TMP.
+ */
+
+const TMP_ROOT     = "$:/TMP"
+const HASH_ALPHABET = "YBNDRFG8EJKMCPQXOTLVWIS2A345H769"
+const HASH_LEN     = 32
+const LFS_HEADER   = "TVDOSLFS\x01"
+const LFS_HEADER_LEN = 16
+const LFS_FLAG_RELATIVE = 0x01
+
+
+function _makeHash(n) {
+    let s = ""
+    const m = HASH_ALPHABET.length
+    for (let i = 0; i < n; i++) s += HASH_ALPHABET[Math.floor(Math.random() * m)]
+    return s
+}
+
+function _isCompressed(s) {
+    if (s.length < 4) return false
+    const b0 = s.charCodeAt(0), b1 = s.charCodeAt(1)
+    const b2 = s.charCodeAt(2), b3 = s.charCodeAt(3)
+    if (b0 === 0x1f && b1 === 0x8b && b2 === 0x08) return true            // gzip
+    if (b0 === 0x28 && b1 === 0xb5 && b2 === 0x2f && b3 === 0xfd) return true  // zstd
+    return false
+}
+
+function _decompress(payload) {
+    // gzip.decomp transparently handles both gzip and zstd; returns Java byte[].
+    return btostr(gzip.decomp(payload))
+}
+
+function _readArchive(lfsPath) {
+    const fd = files.open(lfsPath)
+    if (!fd.exists)     throw new Error("LFS archive not found: " + lfsPath)
+    if (fd.isDirectory) throw new Error("LFS archive is a directory: " + lfsPath)
+
+    const bytes = fd.sread()
+    try { fd.close() } catch (_) {}
+
+    if (bytes.substring(0, LFS_HEADER.length) !== LFS_HEADER)
+        throw new Error("Not an LFS archive: " + lfsPath)
+
+    const flags = bytes.charCodeAt(11)
+    if ((flags & LFS_FLAG_RELATIVE) === 0)
+        throw new Error("LFS archive does not use relative paths: " + lfsPath)
+
+    return bytes
+}
+
+function _allocTmpDir() {
+    const path = TMP_ROOT + "/" + _makeHash(HASH_LEN)
+    const dir  = files.open(path)
+    dir.mkDir()
+    return { fd: dir, path: path }
+}
+
+function _normPath(p) {
+    return p.replace(/\//g, "\\")
+}
+
+function _writeFile(destDirPath, archivePath, payload) {
+    const parts = _normPath(archivePath).split("\\").filter(p => p.length > 0)
+    if (parts.length === 0) return null
+
+    const leaf = parts.pop()
+    let curPath = destDirPath
+    for (let i = 0; i < parts.length; i++) {
+        curPath = curPath + "/" + parts[i]
+        const cur = files.open(curPath)
+        if (!cur.exists) cur.mkDir()
+    }
+    const outfile = files.open(curPath + "/" + leaf)
+    if (!outfile.exists) outfile.mkFile()
+    outfile.swrite(payload)
+    return outfile
+}
+
+
+function extractOne(lfsPath, filename, autoDecompress) {
+    if (autoDecompress === undefined) autoDecompress = true
+    if (filename === undefined || filename === null || filename === "")
+        throw new Error("filename is required")
+
+    const bytes  = _readArchive(lfsPath)
+    const needle = _normPath(filename)
+
+    let curs = LFS_HEADER_LEN
+    while (curs < bytes.length) {
+        const fileType = bytes.charCodeAt(curs)
+        const pathlen  = (bytes.charCodeAt(curs+1) << 8) | bytes.charCodeAt(curs+2)
+        curs += 3
+        const path = bytes.substring(curs, curs + pathlen)
+        curs += pathlen
+        const filelen = (bytes.charCodeAt(curs) << 24)
+                      | (bytes.charCodeAt(curs+1) << 16)
+                      | (bytes.charCodeAt(curs+2) << 8)
+                      |  bytes.charCodeAt(curs+3)
+        curs += 4
+
+        if (_normPath(path) === needle) {
+            let payload = bytes.substring(curs, curs + filelen)
+            if (autoDecompress && _isCompressed(payload)) payload = _decompress(payload)
+
+            const dest  = _allocTmpDir()
+            const leaf  = needle.split("\\").pop()
+            const outfile = files.open(dest.path + "/" + leaf)
+            if (!outfile.exists) outfile.mkFile()
+            outfile.swrite(payload)
+            return outfile
+        }
+
+        curs += filelen
+    }
+
+    throw new Error("File not found in archive: " + filename)
+}
+
+
+function extractAll(lfsPath, autoDecompress) {
+    if (autoDecompress === undefined) autoDecompress = true
+
+    const bytes = _readArchive(lfsPath)
+    const dest  = _allocTmpDir()
+
+    let curs = LFS_HEADER_LEN
+    while (curs < bytes.length) {
+        const fileType = bytes.charCodeAt(curs)
+        const pathlen  = (bytes.charCodeAt(curs+1) << 8) | bytes.charCodeAt(curs+2)
+        curs += 3
+        const path = bytes.substring(curs, curs + pathlen)
+        curs += pathlen
+        const filelen = (bytes.charCodeAt(curs) << 24)
+                      | (bytes.charCodeAt(curs+1) << 16)
+                      | (bytes.charCodeAt(curs+2) << 8)
+                      |  bytes.charCodeAt(curs+3)
+        curs += 4
+
+        let payload = bytes.substring(curs, curs + filelen)
+        if (autoDecompress && _isCompressed(payload)) payload = _decompress(payload)
+        _writeFile(dest.path, path, payload)
+
+        curs += filelen
+    }
+
+    return dest.fd
+}
+
+
+exports = { extractOne, extractAll }

assets/disk0/tvdos/include/net.mjs

@@ -0,0 +1,123 @@
+/*
+ * net.mjs — Internet text-fetch helper for TVDOS
+ *
+ * Wraps the HttpModem peripheral (driven by `_TVDOS.DRV.FS.NET`, see
+ * TVDOS.SYS:1001-1034) behind a small, regular-URL-friendly API. The
+ * helper looks up whichever drive letter the boot probe assigned to the
+ * HTTP modem and translates ordinary URLs (`https://host/path`) into the
+ * scheme-without-double-slash form (`https:host/path`) that the modem
+ * expects on the wire.
+ *
+ * Usage
+ * -----
+ *     let net = require("A:/tvdos/include/net.mjs")
+ *
+ *     if (!net.isAvailable())
+ *         printerrln("No HTTP modem attached")
+ *
+ *     let body = net.fetchText("https://example.com/index.html")
+ *     if (body === null) printerrln("Fetch failed")
+ *     else println(body)
+ */
+
+
+let _cachedDrive = null
+
+/** Scan TVDOS drive table for an HTTP-typed device. Returns the drive
+ *  letter (e.g. "B") or null. */
+function _findHttpDrive() {
+    if (typeof _TVDOS === 'undefined' || !_TVDOS.DRIVEINFO) return null
+    if (_cachedDrive !== null && _TVDOS.DRIVEINFO[_cachedDrive] &&
+        _TVDOS.DRIVEINFO[_cachedDrive].type === 'HTTP')
+        return _cachedDrive
+
+    for (let letter in _TVDOS.DRIVEINFO) {
+        let info = _TVDOS.DRIVEINFO[letter]
+        if (info && info.type === 'HTTP') {
+            _cachedDrive = letter
+            return letter
+        }
+    }
+    return null
+}
+
+/** Convert a regular URL into the form the HTTP modem accepts:
+ *  - strip the `//` between scheme and authority
+ *  - drop any URL fragment
+ *  - assume `https` when no scheme is provided
+ */
+function _normaliseUrl(url) {
+    if (typeof url !== 'string')
+        throw new TypeError("url must be a string")
+    let s = url.trim()
+    if (s.length === 0) throw new Error("url is empty")
+
+    // Drop fragment — the modem speaks to the server, # is client-side.
+    let hash = s.indexOf('#')
+    if (hash >= 0) s = s.substring(0, hash)
+
+    // scheme://host/path  →  scheme:host/path
+    let m = s.match(/^([a-zA-Z][a-zA-Z0-9+.\-]*):\/\/(.*)$/)
+    if (m) return m[1].toLowerCase() + ':' + m[2]
+
+    // Already in scheme:host/path form (the modem's native shape)
+    if (/^[a-zA-Z][a-zA-Z0-9+.\-]*:[^/]/.test(s)) return s
+
+    // No scheme — default to https
+    if (!/^[a-zA-Z][a-zA-Z0-9+.\-]*:/.test(s))
+        return 'https:' + s.replace(/^\/\//, '')
+
+    return s
+}
+
+
+let net = {}
+
+/** Returns the drive letter currently bound to the HTTP modem, or null
+ *  when no such device is attached. */
+net.getHttpDrive = function () {
+    return _findHttpDrive()
+}
+
+/** True iff an HTTP modem is reachable through TVDOS. */
+net.isAvailable = function () {
+    return _findHttpDrive() !== null
+}
+
+/** Translate a URL into the `<drive>:\<modem-url>` form that
+ *  `files.open()` would route through `_TVDOS.DRV.FS.NET`. Useful when
+ *  another component wants the descriptor directly. Throws if no HTTP
+ *  modem is attached. */
+net.toModemPath = function (url) {
+    let drive = _findHttpDrive()
+    if (drive === null) throw new Error("No HTTP modem device is attached")
+    return drive + ':\\' + _normaliseUrl(url)
+}
+
+/** Open a TVDOS file descriptor backed by the HTTP modem for the given
+ *  URL. The descriptor's sread()/bread() trigger the actual fetch.
+ *  Throws if no HTTP modem is attached. */
+net.open = function (url) {
+    return files.open(net.toModemPath(url))
+}
+
+/** Fetch the body of `url` as a string. Returns the response text on
+ *  success, or null when the modem reports a non-zero status (bad URL,
+ *  I/O error, etc.). Throws if no HTTP modem is attached. */
+net.fetchText = function (url) {
+    let fd = net.open(url)
+    let text = fd.sread()
+    try { fd.close() } catch (_) {}
+    return (text === undefined) ? null : text
+}
+
+/** Like fetchText, but throws an Error instead of returning null on
+ *  fetch failure. */
+net.fetchTextOrThrow = function (url) {
+    let body = net.fetchText(url)
+    if (body === null) throw new Error("Failed to fetch URL: " + url)
+    return body
+}
+
+
+exports = net

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/psg.mjs

@@ -81,9 +81,12 @@ function clearBuffer(buf, offsetSec, lengthSec) {
     // Re-silence a buffer region (fill with 128) for re-use across frames.
     const start = (offsetSec != null) ? secToSamples(offsetSec) : 0
     const total = (lengthSec != null) ? secToSamples(lengthSec) : (buf.samples - start)
-    for (let i = 0; i < total; i++) {
-        writeU8(buf, 0, start + i, 128)
-        writeU8(buf, 1, start + i, 128)
+    if (!buf.native) {
+        buf[0].fill(128, start, start + total)
+        buf[1].fill(128, start, start + total)
+    } else {
+        sys.memset(buf[0] + start, 128, total)
+        sys.memset(buf[1] + start, 128, total)
     }
 }
 
@@ -142,7 +145,7 @@ function makeSquare(buf, length, offset, freq, duty, op, amp, pan, phaseOffset)
     })
 }
 
-function makeTriangle(buf, length, offset, freq, duty, op, amp, pan) {
+function makeTriangle(buf, length, offset, freq, duty, op, amp, pan, phaseOffset) {
     // buffer: [Uint8Array, Uint8Array] or native buffer
     // length: in seconds
     // offset: in seconds
@@ -151,6 +154,8 @@ function makeTriangle(buf, length, offset, freq, duty, op, amp, pan) {
     // op: add / mul / sub; default: add
     // amp: 0.0 to 1.0; default: 0.5
     // pan: -1.0 to 1.0; default: 0.0
+    // phaseOffset: optional absolute-time base (seconds) added to phase calc only —
+    //              see makeSquare for details.
     if (duty == null) duty = 0.0
     if (op   == null) op   = 'add'
     if (amp  == null) amp  = 0.5
@@ -158,9 +163,9 @@ function makeTriangle(buf, length, offset, freq, duty, op, amp, pan) {
     // riseFrac: fraction of period spent rising from -1 to +1
     // 0.0 → falling saw, 0.5 → symmetric triangle, 1.0 → rising saw
     const riseFrac = (duty + 1.0) * 0.5
+    const tBase = (phaseOffset || 0) + offset
     mixInto(buf, length, offset, op, amp, pan, function(i) {
-        const t = offset + i / HW_SAMPLING_RATE
-        const phase = (t * freq) % 1
+        const phase = ((tBase + i / HW_SAMPLING_RATE) * freq) % 1
         if (riseFrac <= 0) {
             return 1.0 - 2.0 * phase                               // falling saw
         } else if (riseFrac >= 1) {
@@ -173,7 +178,7 @@ function makeTriangle(buf, length, offset, freq, duty, op, amp, pan) {
     })
 }
 
-function makeAliasedTriangle(buf, length, offset, freq, duty, op, amp, pan) {
+function makeAliasedTriangle(buf, length, offset, freq, duty, op, amp, pan, phaseOffset) {
     // buffer: [Uint8Array, Uint8Array] or native buffer
     // Famicom-style triangle — output is quantised to 16 DAC levels (4-bit, NES APU style).
     // The staircase quantisation introduces harmonics that mimic NES character.
@@ -184,14 +189,16 @@ function makeAliasedTriangle(buf, length, offset, freq, duty, op, amp, pan) {
     // op: add / mul / sub; default: add
     // amp: 0.0 to 1.0; default: 0.5
     // pan: -1.0 to 1.0; default: 0.0
+    // phaseOffset: optional absolute-time base (seconds) added to phase calc only —
+    //              see makeSquare for details.
     if (duty == null) duty = 0.0
     if (op   == null) op   = 'add'
     if (amp  == null) amp  = 0.5
     if (pan  == null) pan  = 0.0
     const riseFrac = (duty + 1.0) * 0.5
+    const tBase = (phaseOffset || 0) + offset
     mixInto(buf, length, offset, op, amp, pan, function(i) {
-        const t = offset + i / HW_SAMPLING_RATE
-        const phase = (t * freq) % 1
+        const phase = ((tBase + i / HW_SAMPLING_RATE) * freq) % 1
         let v
         if (riseFrac <= 0) {
             v = 1.0 - 2.0 * phase

assets/disk0/tvdos/include/synopsis.mjs

@@ -0,0 +1,581 @@
+/*
+ * synopsis.mjs -- TVDOS Synopsis Format (TSF) loader, cache and completion
+ * resolver.
+ *
+ * A TSF document (see the "Command Synopsis Format" chapter of the manual and
+ * tvdos_synopsis_format_draft.md) is a JSON file describing a command's
+ * command-line interface: its options, positional arguments, subcommands,
+ * argument types, completion sources and validation constraints.  This module
+ * turns those documents into the answers command.js needs while the user is
+ * typing -- chiefly "what can come next at the caret?".
+ *
+ * Where the documents live
+ * ------------------------
+ *   * Apps          : colocated with the executable, full filename + ".synopsis"
+ *                     e.g. \tvdos\bin\geturl.js  ->  \tvdos\bin\geturl.js.synopsis
+ *   * Built-in       : the shell coreutils are not files, so their synopses live
+ *     coreutils       in a dedicated directory, \tvdos\synopsis\<name>.synopsis.
+ *                     Aliases (ls -> dir, rm -> del, ...) resolve to the
+ *                     canonical command's file automatically.
+ *
+ * Caching (two layers)
+ * --------------------
+ * Parsing JSON and compiling a completion model on every TAB would be wasteful,
+ * so results are cached:
+ *   1. In memory, for the life of the shell session (command.js keeps the
+ *      require() handle, so this object persists across keystrokes).
+ *   2. On disk, under \tvdos\cache\synopsis\, as a compiled-model blob.  The
+ *      TSVM file layer exposes no reliable modification time, so the cache is
+ *      validated against the source file's *byte size* plus a CACHE_VERSION
+ *      stamp.  A source edit that preserves the byte count will not invalidate
+ *      the disk cache -- an accepted trade-off.  Every disk operation is
+ *      best-effort: a failure never breaks completion, it just falls back to
+ *      re-parsing.
+ *
+ * Public API
+ * ----------
+ *   getCompletion(commandToken, prefixTokens, word) -> result | { ok:false }
+ *   getModel(commandToken)            -> compiled model | null
+ *   getSummary(commandToken)          -> one-line summary | null
+ *   getUsage(commandToken)            -> generated usage string | null
+ *   resolveSynopsisPath(commandToken) -> full path | null
+ *   registerProvider(name, fn)        -> register an `internal` completion source
+ *   clearCache()                      -> drop the in-memory caches
+ */
+
+const TSF_VERSION   = "1.0"
+const CACHE_VERSION = 1                         // bump when compile()'s output shape changes
+const SYN_DIR       = "\\tvdos\\synopsis"        // built-in / coreutil synopses
+const CACHE_PARENT  = "\\tvdos\\cache"
+const CACHE_DIR     = "\\tvdos\\cache\\synopsis" // compiled-model disk cache
+
+///////////////////////////////////////////////////////////////////////////////
+// small local helpers (deliberately mirror command.js internals)
+///////////////////////////////////////////////////////////////////////////////
+
+function drive() { return (typeof _G !== "undefined" && _G.shell) ? _G.shell.getCurrentDrive() : "A" }
+
+function trimStartRevSlash(s) {
+    let cnt = 0
+    while (cnt < s.length && s[cnt] === '\\') cnt += 1
+    return s.substring(cnt)
+}
+
+function isValidDriveLetter(l) {
+    if (typeof l === 'string' || l instanceof String) {
+        let lc = l.charCodeAt(0)
+        return (l == '$' || 65 <= lc && lc <= 90 || 97 <= lc && lc <= 122)
+    }
+    return false
+}
+
+function fileExists(p) { try { return files.open(p).exists } catch (e) { return false } }
+function fileSize(p)   { try { return files.open(p).size | 0 } catch (e) { return 0 } }
+function readText(p)   { try { let f = files.open(p); return f.exists ? f.sread() : null } catch (e) { return null } }
+
+let _cacheDirReady = false
+function ensureCacheDir() {
+    if (_cacheDirReady) return
+    let d = drive()
+    let segs = [CACHE_PARENT, CACHE_DIR]
+    for (let i = 0; i < segs.length; i++) {
+        try { let f = files.open(`${d}:${segs[i]}`); if (!f.exists) f.mkDir() } catch (e) { /* best-effort */ }
+    }
+    _cacheDirReady = true
+}
+function writeText(p, s) {
+    try { ensureCacheDir(); files.open(p).swrite(s); return true } catch (e) { return false }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// executable + synopsis-path resolution
+///////////////////////////////////////////////////////////////////////////////
+
+// Find the runnable file a bare command name would resolve to, mirroring the
+// search order command.js uses (current directory, then PATH, with PATHEXT).
+function findExecutable(cmd) {
+    let d = drive()
+    if (isValidDriveLetter(cmd[0]) && cmd[1] === ':') {
+        try { let f = files.open(cmd); return f.exists ? f.fullPath : null } catch (e) { return null }
+    }
+    let pwd = (typeof _G !== "undefined" && _G.shell) ? _G.shell.getPwd() : [""]
+    let searchDir = (cmd.charAt(0) === '/') ? [""] : ["/" + pwd.join("/")].concat(_TVDOS.getPath())
+    let pathExt = []
+    if (cmd.split(".")[1] === undefined) {
+        (_TVDOS.variables.PATHEXT || "").split(';').forEach(function (it) {
+            if (it.length) { pathExt.push(it); pathExt.push(it.toUpperCase()) }
+        })
+    } else {
+        pathExt.push("")
+    }
+    for (let i = 0; i < searchDir.length; i++) {
+        for (let j = 0; j < pathExt.length; j++) {
+            let search = searchDir[i]; if (!search.endsWith('\\')) search += '\\'
+            let sp = trimStartRevSlash(search + cmd + pathExt[j])
+            try { let f = files.open(`${d}:\\${sp}`); if (f.exists) return f.fullPath } catch (e) { /* keep looking */ }
+        }
+    }
+    return null
+}
+
+// Resolve a command token to the full path of its .synopsis document, or null.
+function resolveSynopsisPath(token) {
+    if (!token) return null
+    let d = drive()
+    let lower = token.toLowerCase()
+
+    // built-in coreutil? -> \tvdos\synopsis\<name>.synopsis
+    // try the typed name first, then any alias that shares the same function so
+    // `ls` finds dir.synopsis without a duplicate file.
+    if (typeof _G !== "undefined" && _G.shell && _G.shell.coreutils &&
+        typeof _G.shell.coreutils[lower] === 'function') {
+        let fn = _G.shell.coreutils[lower]
+        let names = [lower]
+        Object.keys(_G.shell.coreutils).forEach(function (k) {
+            if (_G.shell.coreutils[k] === fn && names.indexOf(k) < 0) names.push(k)
+        })
+        for (let i = 0; i < names.length; i++) {
+            let p = `${d}:${SYN_DIR}\\${names[i]}.synopsis`
+            if (fileExists(p)) return p
+        }
+        return null
+    }
+
+    // app -> <executable>.synopsis colocated with the program
+    let exe = findExecutable(token)
+    if (!exe) return null
+    let p = exe + ".synopsis"
+    return fileExists(p) ? p : null
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// TSF compilation -- raw document -> completion model
+///////////////////////////////////////////////////////////////////////////////
+
+function compile(doc) {
+    if (!doc || typeof doc !== 'object') return null
+    let symbols = doc.symbols || {}
+
+    // ---- options: every symbol of kind "option" is an offerable flag ----
+    let flags = []      // one entry per option symbol
+    let flagMap = {}    // flag string ("-r", "--recursive", "--no-recursive") -> entry
+    Object.keys(symbols).forEach(function (id) {
+        let s = symbols[id]
+        if (!s || s.kind !== 'option') return
+        let value = s.value || null
+        let hasValue = !!value
+        let entry = {
+            id: id,
+            long: s.long || null,
+            short: s.short || null,
+            summary: s.summary || '',
+            negatable: !!s.negatable,
+            hasValue: hasValue,
+            valueRequired: hasValue ? (value.required !== false) : false,
+            value: value
+        }
+        flags.push(entry)
+        if (entry.long)  flagMap[entry.long]  = entry
+        if (entry.short) flagMap[entry.short] = entry
+        if (entry.negatable && entry.long) flagMap['--no-' + entry.long.replace(/^--/, '')] = entry
+    })
+
+    // ---- positionals + subcommands, in grammar order ----
+    let positionals = []
+    let subcommands = []
+    let seenSub = {}
+    function walk(node, inRepeat) {
+        if (!node || typeof node !== 'object') return
+        switch (node.type) {
+            case 'sequence':
+            case 'choice':
+                (node.children || []).forEach(function (c) { walk(c, inRepeat) }); break
+            case 'optional':  walk(node.child, inRepeat); break
+            case 'repeat':    walk(node.child, true); break
+            case 'oneOrMore': walk(node.child, true); break
+            case 'reference': {
+                let sym = symbols[node.symbol]
+                if (!sym) return
+                if (sym.kind === 'positional') {
+                    positionals.push({
+                        id: node.symbol,
+                        name: sym.name || node.symbol,
+                        type: sym.type || 'string',
+                        values: sym.values || null,
+                        completion: sym.completion || null,
+                        summary: sym.summary || '',
+                        repeatable: !!inRepeat
+                    })
+                } else if (sym.kind === 'subcommand') {
+                    if (!seenSub[node.symbol]) {
+                        seenSub[node.symbol] = true
+                        subcommands.push({ name: sym.name || node.symbol, summary: sym.summary || '', tsf: sym.tsf || null })
+                    }
+                }
+                break // option / group references add no positional ordering
+            }
+            default: break
+        }
+    }
+    walk(doc.synopsis, false)
+
+    return {
+        cacheVersion: CACHE_VERSION,
+        tsfVersion: doc.tsfVersion || null,
+        name: doc.name || null,
+        summary: doc.summary || '',
+        description: doc.description || '',
+        symbols: symbols,
+        synopsisNode: doc.synopsis || null,
+        flags: flags,
+        flagMap: flagMap,
+        positionals: positionals,
+        subcommands: subcommands,
+        constraints: doc.constraints || []
+    }
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// loading + caching
+///////////////////////////////////////////////////////////////////////////////
+
+let _mem = {}          // synopsisPath -> { srcSize, model }
+let _resolveMemo = {}  // "drive|pwd|token" -> synopsisPath | null
+
+function cacheKey(p) {
+    // FNV-1a 32-bit hash, prefixed with a sanitised basename for readability.
+    let h = 2166136261
+    for (let i = 0; i < p.length; i++) { h ^= p.charCodeAt(i); h = (h * 16777619) >>> 0 }
+    let base = (p.split(/[\\/]/).pop() || 'syn').replace(/[^A-Za-z0-9._-]/g, '_')
+    return base + '_' + ('00000000' + h.toString(16)).slice(-8)
+}
+function cachePath(synPath) { return `${drive()}:${CACHE_DIR}\\${cacheKey(synPath)}.json` }
+
+function loadModel(synPath) {
+    if (!synPath) return null
+    let srcSize = fileSize(synPath)
+
+    // 1. in-memory
+    let mem = _mem[synPath]
+    if (mem && mem.srcSize === srcSize) return mem.model
+
+    // 2. disk cache (size + version validated)
+    let cachedText = readText(cachePath(synPath))
+    if (cachedText) {
+        try {
+            let c = JSON.parse(cachedText)
+            if (c && c.cacheVersion === CACHE_VERSION && c.srcSize === srcSize && c.model) {
+                _mem[synPath] = { srcSize: srcSize, model: c.model }
+                return c.model
+            }
+        } catch (e) { /* corrupt cache -> re-parse */ }
+    }
+
+    // 3. parse the source
+    let src = readText(synPath)
+    if (src === null) return null
+    let doc
+    try { doc = JSON.parse(src) }
+    catch (e) { try { serial.printerr("synopsis: bad JSON in " + synPath + ": " + e) } catch (_) {} ; return null }
+    let model = compile(doc)
+    if (!model) return null
+
+    _mem[synPath] = { srcSize: srcSize, model: model }
+    writeText(cachePath(synPath), JSON.stringify({ cacheVersion: CACHE_VERSION, srcSize: srcSize, model: model }))
+    return model
+}
+
+function getModel(token) {
+    if (!token) return null
+    let key = drive() + '|' + ((typeof _G !== "undefined" && _G.shell) ? _G.shell.getPwdString() : '') + '|' + token
+    let synPath
+    if (Object.prototype.hasOwnProperty.call(_resolveMemo, key)) synPath = _resolveMemo[key]
+    else { synPath = resolveSynopsisPath(token); _resolveMemo[key] = synPath }
+    return synPath ? loadModel(synPath) : null
+}
+
+function clearCache() { _mem = {}; _resolveMemo = {}; _cacheDirReady = false }
+
+///////////////////////////////////////////////////////////////////////////////
+// internal completion providers (for `"completion": { "method": "internal" }`)
+///////////////////////////////////////////////////////////////////////////////
+
+let _providers = {}
+function registerProvider(name, fn) { _providers[name] = fn }
+function safeProvider(name, word, model) {
+    let fn = _providers[name]
+    if (!fn) return []
+    try { return fn(word, model) || [] } catch (e) { return [] }
+}
+
+// "commands" -- runnable command names (coreutils + PATH executables).
+registerProvider('commands', function (word) {
+    word = (word || '').toLowerCase()
+    let out = [], seen = {}
+    function add(n) { let k = n.toLowerCase(); if (seen[k]) return; seen[k] = true; out.push(n) }
+    if (typeof _G !== "undefined" && _G.shell && _G.shell.coreutils)
+        Object.keys(_G.shell.coreutils).forEach(function (k) { if (k.toLowerCase().indexOf(word) === 0) add(k) })
+    try {
+        let d = drive()
+        let exts = (_TVDOS.variables.PATHEXT || "").split(';')
+            .filter(function (e) { return e.length }).map(function (e) { return e.toLowerCase() })
+        _TVDOS.getPath().forEach(function (dir) {
+            let full = (dir === '') ? `${d}:\\` : `${d}:${dir.charAt(0) === '\\' ? dir : '\\' + dir}`
+            try {
+                let f = files.open(full); if (!f.exists || !f.isDirectory) return
+                ;(f.list() || []).forEach(function (it) {
+                    if (it.isDirectory) return
+                    let nl = (it.name || '').toLowerCase()
+                    if (!exts.some(function (e) { return nl.endsWith(e) })) return
+                    let nm = it.name
+                    exts.forEach(function (e) { if (nm.toLowerCase().endsWith(e)) nm = nm.substring(0, nm.length - e.length) })
+                    if (nm.toLowerCase().indexOf(word) === 0) add(nm)
+                })
+            } catch (e) { /* skip unreadable dir */ }
+        })
+    } catch (e) { /* ignore */ }
+    return out
+})
+
+// "envvars" -- environment variable names.
+registerProvider('envvars', function (word) {
+    word = word || ''
+    try {
+        return Object.keys(_TVDOS.variables || {}).filter(function (k) {
+            return k.toLowerCase().indexOf(word.toLowerCase()) === 0
+        })
+    } catch (e) { return [] }
+})
+
+///////////////////////////////////////////////////////////////////////////////
+// completion query
+///////////////////////////////////////////////////////////////////////////////
+
+// Turn a `values` array (bare values or { value, summary } objects) into
+// completion candidates whose value matches `word` as a prefix.
+function valuesToCandidates(values, word) {
+    if (!values) return []
+    word = word || ''
+    let out = []
+    values.forEach(function (v) {
+        let val, sum
+        if (v && typeof v === 'object' && ('value' in v)) { val = '' + v.value; sum = v.summary || '' }
+        else { val = '' + v; sum = '' }
+        if (val.indexOf(word) === 0) out.push({ label: val, value: val + ' ', summary: sum, isDir: false })
+    })
+    return out
+}
+
+// Candidates implied by an argument descriptor (a positional, or an option's
+// `value`).  Returns { candidates, filesystem } where `filesystem` is false or
+// one of 'path' | 'file' | 'directory' -- a request that the caller ALSO offer
+// matching filesystem entries.
+function descriptorCandidates(desc, word, model) {
+    word = word || ''
+    let none = { candidates: [], filesystem: false }
+    if (!desc) return none
+
+    let method = (desc.completion && desc.completion.method) || (desc.type === 'enum' ? 'enum' : null)
+
+    // explicit completion block
+    if (method === 'none') return none
+    if (method === 'enum') return { candidates: valuesToCandidates(desc.values, word), filesystem: false }
+    if (method === 'list') {
+        let items = (desc.completion && (desc.completion.items || desc.completion.values)) || desc.values || []
+        return { candidates: valuesToCandidates(items, word), filesystem: false }
+    }
+    if (method === 'internal') {
+        let prov = desc.completion && desc.completion.provider
+        return { candidates: valuesToCandidates(safeProvider(prov, word, model), word), filesystem: false }
+    }
+    // method 'command' (run a program for candidates) is intentionally not
+    // executed here -- side-effect / latency safety -- so it falls through to
+    // the type defaults below.
+
+    // no completion block (or unhandled method): default behaviour by type
+    switch (desc.type) {
+        case 'path':      return { candidates: [], filesystem: 'path' }
+        case 'file':      return { candidates: [], filesystem: 'file' }
+        case 'directory': return { candidates: [], filesystem: 'directory' }
+        case 'boolean':   return { candidates: valuesToCandidates(['true', 'false'], word), filesystem: false }
+        case 'command':   return { candidates: valuesToCandidates(safeProvider('commands', word, model), word), filesystem: false }
+        case 'enum':      return { candidates: valuesToCandidates(desc.values, word), filesystem: false }
+        case 'user':      if (_providers['users'])  return { candidates: valuesToCandidates(safeProvider('users', word, model), word), filesystem: false }; break
+        case 'group':     if (_providers['groups']) return { candidates: valuesToCandidates(safeProvider('groups', word, model), word), filesystem: false }; break
+        default: break
+    }
+    // string / integer / float / url / hostname / unknown: a soft `values`
+    // list may still help; otherwise there is nothing to offer.
+    if (desc.values) return { candidates: valuesToCandidates(desc.values, word), filesystem: false }
+    return none
+}
+
+// Every textual form a flag may be typed as (long, short, and the --no- form).
+function flagForms(entry) {
+    let forms = []
+    if (entry.long)  forms.push(entry.long)
+    if (entry.short) forms.push(entry.short)
+    if (entry.negatable && entry.long) forms.push('--no-' + entry.long.replace(/^--/, ''))
+    return forms
+}
+
+// Count how many positional arguments `tokens` (the args already typed before
+// the caret) have consumed, skipping option flags and the values they take.
+function countPositionals(tokens, model) {
+    let n = 0, skip = false
+    for (let i = 0; i < tokens.length; i++) {
+        let t = tokens[i]
+        if (skip) { skip = false; continue }       // this token was an option's value
+        if (t.length > 0 && t.charAt(0) === '-') {
+            if (t.indexOf('=') >= 0) continue         // inline value -- no following value token
+            let e = model.flagMap[t]
+            if (e && e.hasValue && e.valueRequired) skip = true
+            continue
+        }
+        n++
+    }
+    return n
+}
+
+function finalise(r) { return { ok: true, candidates: r.candidates, filesystem: r.filesystem } }
+
+/*
+ * Main entry point used by command.js.
+ *
+ *   commandToken : the command (first word on the line)
+ *   prefixTokens : the argument tokens already typed, in order, EXCLUDING the
+ *                  word currently under the caret
+ *   word         : the partial word under the caret (may be "")
+ *
+ * Returns { ok:false } when there is no synopsis for the command (the caller
+ * should fall back to its own default completion).  Otherwise returns
+ *   { ok:true, candidates:[{label,value,summary,isDir}], filesystem:<flag> }
+ * where `filesystem` (false | 'path' | 'file' | 'directory') asks the caller to
+ * additionally offer matching filesystem entries.
+ */
+function getCompletion(commandToken, prefixTokens, word) {
+    let model = getModel(commandToken)
+    if (!model) return { ok: false }
+    word = word || ''
+    prefixTokens = prefixTokens || []
+
+    // (1) the caret is on an option flag
+    if (word.length > 0 && word.charAt(0) === '-') {
+        // inline value form:  --flag=partial
+        if (word.indexOf('--') === 0 && word.indexOf('=') >= 0) {
+            let eq = word.indexOf('=')
+            let flagPart = word.substring(0, eq)
+            let valPart = word.substring(eq + 1)
+            let entry = model.flagMap[flagPart]
+            if (entry && entry.hasValue) {
+                let r = descriptorCandidates(entry.value, valPart, model)
+                r.candidates = r.candidates.map(function (c) {
+                    return { label: c.label, value: flagPart + '=' + c.value.replace(/ $/, '') + ' ', summary: c.summary, isDir: false }
+                })
+                return { ok: true, candidates: r.candidates, filesystem: false }
+            }
+            return { ok: true, candidates: [], filesystem: false }
+        }
+        // list flags matching the prefix
+        let out = []
+        model.flags.forEach(function (e) {
+            flagForms(e).forEach(function (f) {
+                if (f.indexOf(word) === 0) out.push({ label: f, value: f + ' ', summary: e.summary, isDir: false })
+            })
+        })
+        return { ok: true, candidates: out, filesystem: false }
+    }
+
+    // (2) the caret is on the value of the immediately preceding option
+    let prev = prefixTokens.length > 0 ? prefixTokens[prefixTokens.length - 1] : null
+    if (prev && prev.charAt(0) === '-' && prev.indexOf('=') < 0) {
+        let entry = model.flagMap[prev]
+        if (entry && entry.hasValue && entry.valueRequired)
+            return finalise(descriptorCandidates(entry.value, word, model))
+    }
+
+    // (3) a positional argument (or a subcommand in the first slot)
+    let posIndex = countPositionals(prefixTokens, model)
+    if (posIndex === 0 && model.subcommands.length > 0) {
+        let out = model.subcommands
+            .filter(function (s) { return s.name.indexOf(word) === 0 })
+            .map(function (s) { return { label: s.name, value: s.name + ' ', summary: s.summary, isDir: false } })
+        return { ok: true, candidates: out, filesystem: false }
+    }
+    let desc = null
+    if (model.positionals.length > 0) {
+        if (posIndex < model.positionals.length) desc = model.positionals[posIndex]
+        else {
+            let last = model.positionals[model.positionals.length - 1]
+            if (last && last.repeatable) desc = last
+        }
+    }
+    // No descriptor for this slot -> let the caller use its default completion.
+    if (!desc) return { ok: false }
+    return finalise(descriptorCandidates(desc, word, model))
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// generated help (per the spec, usage text is derived output, not normative)
+///////////////////////////////////////////////////////////////////////////////
+
+function grammarToText(node, symbols) {
+    if (!node || typeof node !== 'object') return ''
+    switch (node.type) {
+        case 'sequence':
+            return (node.children || []).map(function (c) { return grammarToText(c, symbols) })
+                .filter(function (s) { return s.length }).join(' ')
+        case 'choice':
+            return '(' + (node.children || []).map(function (c) { return grammarToText(c, symbols) }).join(' | ') + ')'
+        case 'optional':
+            return '[' + grammarToText(node.child, symbols) + ']'
+        case 'repeat': {
+            // a repeat over a group is the familiar [OPTION...] slot
+            let child = node.child
+            if (child && child.type === 'reference' && symbols[child.symbol] && symbols[child.symbol].kind === 'group')
+                return '[' + grammarToText(child, symbols) + '...]'
+            return grammarToText(child, symbols) + '...'
+        }
+        case 'oneOrMore': {
+            let t = grammarToText(node.child, symbols)
+            return t + ' [' + t + '...]'
+        }
+        case 'reference': {
+            let s = symbols[node.symbol]
+            if (!s) return node.symbol
+            if (s.kind === 'group')      return 'OPTION'
+            if (s.kind === 'option')     return s.long || s.short || node.symbol
+            if (s.kind === 'subcommand') return s.name || node.symbol
+            if (s.kind === 'positional') return s.name || node.symbol
+            return node.symbol
+        }
+        default: return ''
+    }
+}
+
+function getUsage(token) {
+    let m = getModel(token)
+    if (!m) return null
+    let body = grammarToText(m.synopsisNode, m.symbols)
+    return ((m.name || token) + (body ? ' ' + body : '')).trim()
+}
+
+function getSummary(token) {
+    let m = getModel(token)
+    return m ? (m.summary || '') : null
+}
+
+///////////////////////////////////////////////////////////////////////////////
+// Module exports
+///////////////////////////////////////////////////////////////////////////////
+
+exports = {
+    getCompletion,
+    getModel,
+    getSummary,
+    getUsage,
+    resolveSynopsisPath,
+    registerProvider,
+    clearCache,
+    TSF_VERSION,
+}