command.js: autocomplete by candidate window

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

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

.gitignore

@@ -9,6 +9,8 @@ buildapp/out/TerranBASIC*
 buildapp/TerranBASIC_linux.*
 buildapp/TerranBASIC_macOS.*
 buildapp/TerranBASIC_windows.*
+*.o
+*.a
 
 # Java native errors
 hs_err_pid*
@@ -60,7 +62,15 @@ 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/*

.idea/artifacts/TerranBASIC.xml

@@ -21,36 +21,54 @@
       <element id="extracted-dir" path="$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-reflect/1.8.21/kotlin-reflect-1.8.21.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-test/1.8.21/kotlin-test-1.8.21.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$MAVEN_REPOSITORY$/org/jetbrains/kotlin/kotlin-stdlib-common/1.8.21/kotlin-stdlib-common-1.8.21.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/graal-sdk-22.3.1.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/icu4j-71.1.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-22.3.1-edit.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-scriptengine-22.3.1.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-22.3.1-edit.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-api-22.3.1.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/polyglot-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-language-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-scriptengine-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-api-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-runtime-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-compiler-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/compiler-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/compiler-management-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/word-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/icu4j-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/collections-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/nativeimage-23.1.10.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/jniutils-23.1.10.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/gdx-1.12.1.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-3.3.3.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-stb-3.3.3.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-glfw-3.3.3.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-22.3.1-javadoc.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-22.3.1-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-language-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-language-23.1.10-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/gdx-1.12.1-javadoc.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/gdx-1.12.1-sources.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/icu4j-71.1-javadoc.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/icu4j-71.1-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/icu4j-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/icu4j-23.1.10-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-openal-3.3.3.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-opengl-3.3.3.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-3.3.3-javadoc.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-3.3.3-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-jemalloc-3.3.3.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-22.3.1-javadoc.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-22.3.1-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-23.1.10-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/TerranVirtualDisk-src.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/jorbis-0.0.17-javadoc.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/jorbis-0.0.17-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-stb-3.3.3-javadoc.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-stb-3.3.3-sources.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/graal-sdk-22.3.1-javadoc.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/graal-sdk-22.3.1-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/polyglot-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/polyglot-23.1.10-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-api-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-api-23.1.10-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-runtime-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-runtime-23.1.10-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/collections-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/collections-23.1.10-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/nativeimage-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/nativeimage-23.1.10-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/jniutils-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/jniutils-23.1.10-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/jlayer-1.0.1-gdx-javadoc.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/jlayer-1.0.1-gdx-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-glfw-3.3.3-javadoc.jar" path-in-jar="/" />
@@ -62,15 +80,15 @@
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-openal-3.3.3-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-opengl-3.3.3-javadoc.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-opengl-3.3.3-sources.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-api-22.3.1-javadoc.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/truffle-api-22.3.1-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/regex-23.1.10-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-3.3.3-natives-windows.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-jemalloc-3.3.3-javadoc.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-jemalloc-3.3.3-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-stb-3.3.3-natives-linux.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-stb-3.3.3-natives-macos.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-scriptengine-22.3.1-javadoc.jar" path-in-jar="/" />
-      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-scriptengine-22.3.1-sources.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-scriptengine-23.1.10-javadoc.jar" path-in-jar="/" />
+      <element id="extracted-dir" path="$PROJECT_DIR$/lib/js-scriptengine-23.1.10-sources.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-glfw-3.3.3-natives-linux.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/lwjgl-glfw-3.3.3-natives-macos.jar" path-in-jar="/" />
       <element id="extracted-dir" path="$PROJECT_DIR$/lib/gdx-jnigen-loader-2.3.1-javadoc.jar" path-in-jar="/" />

.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/misc.xml

@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <project version="4">
-  <component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="17" project-jdk-type="JavaSDK">
+  <component name="ProjectRootManager" version="2" languageLevel="JDK_21" default="true" project-jdk-name="21" project-jdk-type="JavaSDK">
     <output url="file://$PROJECT_DIR$/out" />
   </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>

.idea/vcs.xml

@@ -2,5 +2,7 @@
 <project version="4">
   <component name="VcsDirectoryMappings">
     <mapping directory="$PROJECT_DIR$" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$/assets/disk0/home/tetrino" vcs="Git" />
+    <mapping directory="$PROJECT_DIR$/assets/disk0/home/tvnes" vcs="Git" />
   </component>
 </project>

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

@@ -0,0 +1,547 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**tsvm** is a virtual machine that mimics 8-bit era computer architecture and runs programs written in JavaScript. The project includes:
+- The virtual machine core
+- Reference BIOS implementation
+- TVDOS (operating system)
+- Videotron2K video display controller emulator
+- TerranBASIC integration
+- Multiple platform build system
+
+## Documentations
+
+Documentation for TSVM and TVDOS are available on `./doc/*.tex` as machine-readable format.
+
+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
+
+- **tsvm_core/**: Core virtual machine implementation in Kotlin
+  - `VM.kt`: Main virtual machine class with memory management and peripheral slots
+  - `peripheral/`: Hardware peripherals (graphics adapters, disk drives, TTY, audio, etc.)
+  - `vdc/`: Videotron2K video display controller
+  - Various delegates for JavaScript integration via GraalVM
+
+- **tsvm_executable/**: Main emulator application
+  - `VMGUI.kt`: LibGDX-based GUI implementation
+  - `TsvmEmulator.java`: Main application entry point
+  - Menu systems for configuration, audio, memory management
+
+- **TerranBASICexecutable/**: TerranBASIC interpreter application
+  - `TerranBASIC.java`: Entry point for BASIC interpreter
+  - `VMGUI.kt`: GUI for BASIC environment
+
+### Key Technologies
+
+- **Kotlin/Java**: Primary implementation language
+- **LibGDX**: Graphics and windowing framework
+- **GraalVM**: JavaScript execution engine for running programs in the VM
+- **LWJGL**: Native library bindings
+- **IntelliJ IDEA**: Development environment (*.iml module files)
+
+### Virtual Hardware
+
+The VM emulates various peripherals through the `peripheral/` package:
+- Graphics adapters with different capabilities
+- Disk drives (including TevdDiskDrive for custom disk format)
+- TTY terminals and character LCD displays
+- Audio devices and MP2 audio environment
+- Network modems and serial interfaces
+- Memory management units
+
+## Build and Development
+
+### Building Applications
+
+Use the build scripts in `buildapp/`:
+- `build_app_linux_x86.sh` - Linux x86_64 AppImage
+- `build_app_linux_arm.sh` - Linux ARM64 AppImage  
+- `build_app_mac_x86.sh` - macOS Intel
+- `build_app_mac_arm.sh` - macOS Apple Silicon
+- `build_app_windows_x86.sh` - Windows x86
+
+### Prerequisites
+
+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
+
+### Development Commands
+
+- **Build JAR**: Use IntelliJ IDEA build system to compile modules
+- **Run Emulator**: Execute `TsvmEmulator.java` main method or use built JAR
+- **Run TerranBASIC**: Execute `TerranBASIC.java` main method
+- **Package Apps**: Run appropriate build script from `buildapp/` directory
+
+### Assets and File System
+
+- `assets/disk0/`: Virtual disk content including TVDOS system files
+- `assets/bios/`: BIOS ROM files and implementations
+- `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:
+- Assembly-like programming language
+- 6 general registers (r1-r6) and special registers (tmr, frm, px, py, c1-c6)
+- Scene-based programming model
+- Drawing commands (plot, fillin, goto, fillscr)
+- Conditional execution with postfixes (zr, nz, gt, ls, ge, le)
+
+Programs are structured with SCENE blocks and executed with perform commands.
+
+## Memory Management
+
+- VM supports up to USER_SPACE_SIZE memory
+- 64-byte malloc units with reserved blocks
+- Peripheral slots (1-8 configurable)
+- Memory-mapped I/O for peripheral access
+- JavaScript programs run in sandboxed GraalVM context
+
+### Peripheral Memory Addressing
+
+Peripheral memories can be accessed using `vm.peek()` and `vm.poke()` functions, which takes absolute address.
+
+- Peripherals take up negative number of the memory space, and their addressing is in backwards (e.g. Slot 1 starts at -1048577 and ends at -2097152)
+- Peripherals take up two memory regions: MMIO area and Memory Space area; MMIO is accessed by PeriBase (and its children) using `mmio_read()` and `mmio_write()`, and the Memory Space is accessed using `peek()` and `poke()`.
+  - Peripheral at slot *n* takes following addresses
+    1. MMIO area (-131072×n)-1 to -131072×(n+1)
+    2. Memory Space area -(1048576×n)-1 to (-1048576×(n+1))
+
+## Testing
+
+- Use example programs in `My_BASIC_Programs/` for BASIC testing
+- JavaScript test programs available in `assets/disk0/`
+- Videotron2K assembly examples in documentation
+
+## Notes
+
+- 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
+
+#### Legacy iPF Format
+- Format documentation on `terranmon.txt` (search for "TSVM MOV file format" and "TSVM Interchangeable Picture Format (aka iPF Type 1/2)")
+- Video Encoder implementation on `assets/disk0/tvdos/bin/encodemov.js` (iPF Format 1 and 2) and `assets/disk0/tvdos/bin/encodemov2.js` (iPF Format 1-delta)
+  - Actual encoding/decoding code is in `GraphicsJSR223Delegate.kt`
+- Audio uses standard MP2
+
+#### TEV Format (TSVM Enhanced Video)
+- **Modern video codec** optimized for TSVM hardware with 60-80% better compression than iPF
+- **C Encoder**: `video_encoder/encoder_tev.c` - Hardware-accelerated encoder with motion compensation and DCT
+  - How to build: `make clean && make`
+  - **Rate Control**: Supports both quality mode (`-q 0-4`) and bitrate mode (`-b N` kbps)
+- **JS Decoder**: `assets/disk0/tvdos/bin/playtev.js` - Native decoder for TEV format playback
+  - How to build: `must be done manually by the user; the TSVM is not machine-interactable`
+- **Hardware accelerated decoding**: Extended GraphicsJSR223Delegate.kt with TEV functions:
+  - `tevDecode()` - The main decoding function (now accepts rate control factor)
+  - `tevIdct8x8()` - Fast 8×8 DCT transforms
+  - `tevMotionCopy8x8()` - Sub-pixel motion compensation
+- **Features**:
+  - 16×16 DCT blocks (vs 4×4 in iPF) for better compression
+  - Motion compensation with ±8 pixel search range
+  - YCoCg-R 4:2:0 Chroma subsampling (more aggressive quantisation on Cg channel)
+  - Full 8-Bit RGB colour for increased visual fidelity, rendered down to TSVM-compliant 4-Bit RGB with dithering upon playback
+- **Usage Examples**:
+  ```bash
+  # Quality mode
+  ./encoder_tev -i input.mp4 -o output.tev -q 3
+
+  # Playback
+  playtev output.tev
+  ```
+- **Format documentation**: `terranmon.txt` (search for "TSVM Enhanced Video (TEV) Format")
+- **Version**: 2.1 (includes rate control factor in all video packets)
+
+#### TAV Format (TSVM Advanced Video)
+- **Successor to TEV**: DWT-based video codec using wavelet transforms instead of DCT
+- **C Encoder**: `video_encoder/encoder_tav.c` - Multi-wavelet encoder with perceptual quantisation
+  - How to build: `make tav`
+  - **Wavelet Support**: Multiple wavelet types for different compression characteristics
+- **JS Decoder**: `assets/disk0/tvdos/bin/playtav.js` - Native decoder for TAV format playback
+- **Hardware accelerated decoding**: Extended GraphicsJSR223Delegate.kt with TAV functions
+- **Packet analyser**: `video_encoder/tav_inspector.c` - Debugging tool that parses TAV packets into human-readable form
+- **Features**:
+  - **Multiple Wavelet Types**: 5/3 reversible, 9/7 irreversible, CDF 13/7, DD-4, Haar
+  - **Single-tile encoding**: One large DWT tile for optimal quality (no blocking artifacts)
+  - **Perceptual quantisation**: HVS-optimized coefficient scaling
+  - **YCoCg-R colour space**: Efficient chroma representation with "simulated" subsampling using anisotropic quantisation (search for "ANISOTROPY_MULT_CHROMA" on the encoder)
+  - **6-level DWT decomposition**: Deep frequency analysis for better compression (deeper levels possible but 6 is the maximum for the default TSVM size)
+  - **Significance Map Compression**: Improved coefficient storage format exploiting sparsity for 16-18% additional compression (2025-09-29 update)
+  - **Concatenated Maps Layout**: Cross-channel compression optimisation for additional 1.6% improvement (2025-09-29 enhanced)
+- **Usage Examples**:
+  ```bash
+  # Different wavelets
+  ./encoder_tav -i input.mp4 -w 0 -o output.tav    # 5/3 reversible (lossless capable)
+  ./encoder_tav -i input.mp4 -w 1 -o output.tav    # 9/7 irreversible (default, best compression)
+  ./encoder_tav -i input.mp4 -w 2 -o output.tav    # CDF 13/7 (experimental)
+  ./encoder_tav -i input.mp4 -w 16 -o output.tav   # DD-4 (four-point interpolating)
+  ./encoder_tav -i input.mp4 -w 255 -o output.tav  # Haar (demonstration)
+
+  # Quality levels (0-5)
+  ./encoder_tav -i input.mp4 -q 0 -o output.tav         # Lowest quality, smallest file
+  ./encoder_tav -i input.mp4 -q 5 -o output.tav         # Highest quality, largest file
+
+  # Temporal 3D DWT (GOP-based encoding)
+  ./encoder_tav -i input.mp4 --temporal-dwt -o output.tav
+
+  # Playback
+  playtav output.tav
+  ```
+
+**CRITICAL IMPLEMENTATION NOTES**:
+
+**Wavelet Coefficient Layout**:
+- TAV uses **2D Spatial Layout** in memory: `[LL, LH, HL, HH, LH, HL, HH, ...]` for each decomposition level
+- **Forward transform must output**: `temp[0...half-1] = low-pass`, `temp[half...length-1] = high-pass`
+- **Inverse transform must expect**: Same 2D spatial layout and exactly reverse forward operations
+- **Common mistake**: Assuming linear layout leads to grid/checkerboard artifacts
+
+**Wavelet Implementation Pattern**:
+- All wavelets must follow the **exact same structure** as the working 5/3 implementation:
+  ```c
+  // Forward: 1. Predict step, 2. Update step
+  temp[half + i] = data[odd_index] - prediction;  // High-pass
+  temp[i] = data[even_index] + update;            // Low-pass
+
+  // Inverse: Reverse order - 1. Undo update, 2. Undo predict
+  temp[i] -= update;                              // Undo low-pass update
+  temp[half + i] += prediction;                   // Undo high-pass predict
+  ```
+- **Boundary handling**: Use symmetric extension for filter taps beyond array bounds
+- **Reconstruction**: Interleave even/odd samples: `data[2*i] = low[i], data[2*i+1] = high[i]`
+
+**Debugging Grid Artifacts**:
+- **Symptom**: Checkerboard or grid patterns in decoded video
+- **Cause**: Mismatch between encoder/decoder coefficient layout or lifting step operations
+- **Solution**: Ensure forward and inverse transforms use identical coefficient indexing and reverse operations exactly
+
+**Supported Wavelets**:
+- **0**: 5/3 reversible (lossless when unquantised, JPEG 2000 standard)
+- **1**: 9/7 irreversible (best compression, CDF 9/7 variant, default choice)
+- **2**: CDF 13/7 (experimental, simplified implementation)
+- **16**: DD-4 (four-point interpolating Deslauriers-Dubuc, for still images)
+- **255**: Haar (demonstration only, simplest possible wavelet)
+
+- **Format documentation**: `terranmon.txt` (search for "TSVM Advanced Video (TAV) Format")
+- **Version**: Current (perceptual quantisation, multi-wavelet support, EZBC compression)
+
+#### TAV Temporal 3D DWT (GOP Unified Encoding)
+
+Implemented on 2025-10-15 for improved temporal compression through group-of-pictures (GOP) encoding:
+
+**Key Features**:
+- **3D DWT**: Applies DWT in both spatial (2D) and temporal (1D) dimensions for optimal spacetime compression
+- **Unified GOP Preprocessing**: Single EZBC tree for all frames and channels in a GOP (width×height×N_frames×3_channels)
+- **GOP Size**: Typically 8 frames (configurable), with scene change detection for adaptive GOPs
+- **Single-frame Fallback**: GOP size of 1 automatically uses traditional I-frame encoding
+
+**Packet Format**:
+- **0x12 (GOP_UNIFIED)**: `[gop_size][compressed_size][compressed_data]`
+- **0xFC (GOP_SYNC)**: `[frame_count]` - Indicates N frames were decoded from GOP block
+- **Timecode Emission**: One timecode packet per GOP (not per frame)
+
+**Technical Implementation**:
+```c
+// Unified preprocessing structure (encoder_tav.c:2371-2509)
+[All_Y_maps][All_Co_maps][All_Cg_maps][All_Y_values][All_Co_values][All_Cg_values]
+// Where maps are grouped by channel across all GOP frames for optimal Zstd compression
+```
+
+**Usage**:
+```bash
+# Enable temporal 3D DWT
+./encoder_tav -i input.mp4 --temporal-dwt -o output.tav
+
+# Inspect GOP structure
+./tav_inspector output.tav -v
+```
+
+**Compression Benefits**:
+- **Temporal Coherence**: Exploits similarity across consecutive frames
+- **Unified Compression**: Zstd compresses entire GOP as single block, finding patterns across time
+- **Adaptive GOPs**: Scene change detection ensures optimal GOP boundaries
+
+#### TAD Format (TSVM Advanced Audio)
+- **Perceptual audio codec** for TSVM using CDF 9/7 biorthogonal wavelets
+- **C Encoder**: `video_encoder/encoder_tad.c` - Core Encoder library; `video_encoder/encoder_tad_standalone.c` - Standalone encoder with FFmpeg integration
+  - How to build: `make tad`
+  - **Quality Levels**: 0-5 (0=lowest quality/smallest, 5=highest quality/largest; designed to be in sync with TAV encoder)
+- **C Decoders**:
+  - `video_encoder/decoder_tad.c` - Shared decoder library with `tad32_decode_chunk()` function
+  - `video_encoder/decoder_tad.h` - Exports shared decoder API
+  - `video_encoder/decoder_tav.c` - TAV decoder that uses shared TAD decoder for audio packets
+  - **Shared Architecture** (Fixed 2025-11-10): Both standalone TAD and TAV decoders now use the same `tad32_decode_chunk()` implementation, eliminating code duplication and ensuring identical output
+- **Kotlin Decoder**: `AudioAdapter.kt` - Hardware-accelerated TAD decoder for TSVM runtime
+  - **Quantisation Fix** (2025-11-10): Fixed BASE_QUANTISER_WEIGHTS to use channel-specific 2D array (Mid/Side) instead of single 1D array, resolving severe audio distortion
+- **Features**:
+  - **32 KHz stereo**: TSVM audio hardware native format
+  - **Variable chunk sizes**: Any size ≥1024 samples, including non-power-of-2 (e.g., 32016 for TAV 1-second GOPs)
+  - **Pre-emphasis filter**: First-order IIR filter (α=0.5) shifts quantisation noise to lower frequencies
+  - **Gamma compression**: Dynamic range compression (γ=0.5) before quantisation
+  - **M/S stereo decorrelation**: Exploits stereo correlation for better compression
+  - **9-level CDF 9/7 DWT**: Fixed 9 decomposition levels for all chunk sizes
+  - **Perceptual quantisation**: Channel-specific (Mid/Side) frequency-dependent weights with lambda companding (λ=6.0)
+  - **EZBC encoding**: Binary tree embedded zero block coding exploits coefficient sparsity (86.9% Mid, 97.8% Side)
+  - **Zstd compression**: Level 7 on concatenated EZBC bitstreams for additional compression
+  - **Non-power-of-2 support**: Fixed 2025-10-30 to handle arbitrary chunk sizes correctly
+- **Usage Examples**:
+  ```bash
+  # Encode with default quality (Q3)
+  encoder_tad -i input.mp4 -o output.tad
+
+  # Encode with highest quality
+  encoder_tad -i input.mp4 -o output.tad -q 5
+
+  # Encode without Zstd compression
+  encoder_tad -i input.mp4 -o output.tad --no-zstd
+
+  # Verbose output with statistics
+  encoder_tad -i input.mp4 -o output.tad -v
+
+  # Decode back to PCM16
+  decoder_tad -i input.tad -o output.pcm
+  ```
+- **Format documentation**: `terranmon.txt` (search for "TSVM Advanced Audio (TAD) Format")
+- **Version**: 1.1 (EZBC encoding with non-power-of-2 support, updated 2025-10-30; decoder architecture and Kotlin quantisation weights fixed 2025-11-10; documentation updated 2025-11-10 to reflect pre-emphasis and EZBC)
+
+**TAD Encoding Pipeline**:
+1. **Pre-emphasis filter** (α=0.5) - Shifts quantisation noise toward lower frequencies
+2. **Gamma compression** (γ=0.5) - Dynamic range compression
+3. **M/S decorrelation** - Transforms L/R to Mid/Side
+4. **9-level CDF 9/7 DWT** - Wavelet decomposition (fixed 9 levels)
+5. **Perceptual quantisation** - Lambda companding (λ=6.0) with channel-specific weights
+6. **EZBC encoding** - Binary tree embedded zero block coding per channel
+7. **Zstd compression** (level 7) - Additional compression on concatenated EZBC bitstreams
+
+**TAD Compression Performance**:
+- **Target Compression**: 2:1 against PCMu8 baseline (4:1 against PCM16LE input)
+- **Achieved Compression**: 2.51:1 against PCMu8 at quality level 3
+- **Audio Quality**: Preserves full 0-16 KHz bandwidth
+- **Coefficient Sparsity**: 86.9% zeros in Mid channel, 97.8% in Side channel (typical)
+- **EZBC Benefits**: Exploits sparsity, progressive refinement, spatial clustering
+
+**TAD Integration with TAV**:
+TAD is designed as an includable API for TAV video encoder integration. The variable chunk size
+support enables synchronized audio/video encoding where audio chunks can match video GOP boundaries.
+TAV embeds TAD-compressed audio using packet type 0x24 with Zstd compression.
+
+**TAD Hardware Acceleration**:
+TSVM accelerates TAD decoding with AudioAdapter.kt (backend) and AudioJSR223Delegate.kt (API):
+- Backend decoder in AudioAdapter.kt with non-power-of-2 chunk size support (fixed 2025-10-30)
+- API functions in AudioJSR223Delegate.kt for JavaScript access
+- Supports chunk sizes from 1024 to 32768+ samples (any size ≥1024)
+- Fixed 9-level CDF 9/7 inverse DWT with correct length tracking for non-power-of-2 sizes
+
+**Critical Implementation Note (Fixed 2025-10-30)**:
+Multi-level inverse DWT must pre-calculate the exact sequence of lengths from forward transform:
+```kotlin
+val lengths = IntArray(levels + 1)
+lengths[0] = chunk_size
+for (i in 1..levels) {
+    lengths[i] = (lengths[i - 1] + 1) / 2
+}
+// Apply inverse DWT using lengths[level] for each level
+```
+Using simple doubling (`length *= 2`) is incorrect for non-power-of-2 sizes and causes
+mirrored subband artifacts.
+
+**TAD Decoding Pipeline**:
+1. **Zstd decompression** - Decompress concatenated EZBC bitstreams
+2. **EZBC decoding** - Binary tree decoder reconstructs quantised int8 coefficients per channel
+3. **Lambda decompanding** - Inverse Laplacian CDF mapping with channel-specific weights
+4. **9-level inverse CDF 9/7 DWT** - Wavelet reconstruction with proper non-power-of-2 length tracking
+5. **M/S to L/R conversion** - Transform Mid/Side back to Left/Right
+6. **Gamma expansion** (γ⁻¹=2.0) - Restore dynamic range
+7. **De-emphasis filter** (α=0.5) - Reverse pre-emphasis, remove frequency shaping
+8. **PCM32f to PCM8** - Noise-shaped dithering for final 8-bit output
+
+**Critical Quantisation Weights Note (Fixed 2025-11-10)**:
+The TAD decoder MUST use channel-specific quantisation weights for Mid (channel 0) and Side (channel 1) channels. The Kotlin decoder (AudioAdapter.kt) originally used a single 1D weight array, which caused severe audio distortion. The correct implementation uses a 2D array:
+
+```kotlin
+// CORRECT (Fixed 2025-11-10)
+private val BASE_QUANTISER_WEIGHTS = arrayOf(
+    floatArrayOf( // Mid channel (0)
+        4.0f, 2.0f, 1.8f, 1.6f, 1.4f, 1.2f, 1.0f, 1.0f, 1.3f, 2.0f
+    ),
+    floatArrayOf( // Side channel (1)
+        6.0f, 5.0f, 2.6f, 2.4f, 1.8f, 1.3f, 1.0f, 1.0f, 1.6f, 3.2f
+    )
+)
+
+// During dequantisation:
+val weight = BASE_QUANTISER_WEIGHTS[channel][sideband] * quantiserScale
+coeffs[i] = normalisedVal * TAD32_COEFF_SCALARS[sideband] * weight
+```
+
+The different weights for Mid and Side channels reflect the perceptual importance of different frequency bands in each channel. Using incorrect weights causes:
+- DC frequency underamplification (using 1.0 instead of 4.0/6.0)
+- Incorrect stereo imaging and extreme side channel distortion
+- Severe frequency response errors that manifest as "clipping-like" distortion
+
+## Virtual Consoles (vtmgr)
+
+Linux-style virtual consoles for TVDOS: up to 6 independent shell sessions,
+switched with **Alt-1..Alt-6** or the **`chvt N`** builtin, **Alt-0** to exit.
+Implemented entirely in JS — **no tsvm_core changes**.
+
+### Architecture
+
+- **Dispatcher**: `assets/disk0/tvdos/sbin/vtmgr.js`. Launched directly by the
+  `TVDOS.SYS` boot block (only when `!_TVDOS_IS_VT_PANE`); when it exits (Alt-0)
+  the boot block runs `AUTOEXEC.BAT` as the bare fallback shell. Owns the
+  physical keyboard and screen. Each VT runs in its own GraalVM context/thread
+  via the existing `parallel.spawnNewContext` / `attachProgram` / `launch` API
+  (see `VMJSR223Delegate.kt` `class Parallel`). VT 1 spawns at boot; VT 2-6 are
+  lazy-spawned on first switch and re-spawned if their shell exits.
+- **Concurrency model**: truly concurrent — switching works mid-command, not
+  just at the prompt. Background panes keep running (no `Thread.suspend`; it is
+  unusable on JDK 21). A cooperative gate inside the shimmed `con.getch` parks
+  panes blocked on input; CPU-bound background panes are allowed to run.
+- **Shared memory**: one `sys.malloc` region holds a control block (active VT,
+  switch request, debounce, spawned-bits) plus, per VT, an input ring buffer and
+  a 7682-byte text-plane buffer mirroring the GPU text-area layout
+  (cursor 2 + fore 2560 + back 2560 + char 2560).
+- **Compositor** (30 Hz): blits the active VT's text plane to the physical GPU
+  text area via `sys.memcpy`, and pushes that VT's cursor-visibility into the GPU
+  blink bit (MMIO attribute byte 6, addressed at `-1 - (131072*gpuSlot + 6)`).
+- **Boot config split (`commandrc` + `AUTOEXEC.BAT`)**: environment setup and
+  app-launch are split into two files so panes can replay one without the other.
+  `\commandrc` holds the `set` commands (PATH/INCLPATH/HELPPATH/KEYBOARD) and is
+  run by the `TVDOS.SYS` boot block in **every** context (boot and pane) — it has
+  no `.BAT` extension, so the boot block runs it line-by-line (`set` mutates the
+  shared `_TVDOS.variables`, so the effect persists). `\AUTOEXEC.BAT` is the
+  **per-console launch** script (Korean IME `tvdos/i18n/korean`, then
+  `command -fancy`); it is run once per console — by each pane's bootstrap, and
+  by the boot block as the post-vtmgr fallback. No env snapshot/replay anymore;
+  each pane gets PATH/KEYBOARD/etc. natively from `commandrc`, and Korean IME
+  (a per-context `unicode.uniprint` handler) now registers in every pane.
+- **Per-pane bootstrap**: each pane re-evals `TVDOS.SYS` (with `_TVDOS_IS_VT_PANE`
+  set — which makes the boot block run `commandrc` but skip the vtmgr/AUTOEXEC
+  launch — and a `_BIOS` stub captured live from the main context) then runs
+  `command -c \AUTOEXEC.BAT`, all in ONE direct `eval` so the launcher shares
+  scope with `_TVDOS`/`files`/`execApp`.
+
+### Output/input shimming (in the pane bootstrap)
+
+`con` and the global `print`/`println` family are plain JS, so the bootstrap
+overrides them to read/write the per-VT shared-memory buffers instead of the
+physical GPU. **`sys` and `graphics` are host objects and CANNOT be overridden
+from JS** — this is the key constraint that shapes everything below.
+
+- The shimmed `print` is a faithful JS port of the GPU's TTY interpreter
+  (`GlassTty.acceptChar` + `GraphicsAdapter` handlers): control bytes, the
+  `\x84<decimal>u` "emit char by code" escape (used by `con.prnch`), CSI cursor
+  moves / erase / SGR colours, and the `?25` cursor-visibility private sequence.
+  A swallow-only parser is NOT enough — TVDOS apps drive the screen through
+  these `print` escapes.
+- `con.move`/`con.getyx` are **1-based** (mirroring `graphics.setCursorYX`'s
+  `cx-1` and `getCursorYX`'s `cx+1`); `con.addch` does NOT advance the cursor
+  (matches `graphics.putSymbol`), while `con.prnch` DOES.
+- `command.js`'s `shell.execute` reassigns the global print family to
+  `shell.stdio.out.*`, which call `sys.print` (→ physical GPU). `shell.stdio.out`
+  was made to delegate to a `globalThis.__VT_OUT` hook when present (set by the
+  bootstrap); outside a VT the hook is absent and the path is byte-identical.
+
+### Direct-VRAM apps need a VT-aware base (the `vaddr` pattern)
+
+Apps that write the text area directly via `graphics.getGpuMemBase()` (rather
+than `con.*`/`print`) bypass the shims and paint the physical screen, invading
+whatever VT is visible. They must resolve text-area byte `m` through a
+VT-aware base:
+
+```js
+// physical: backward  (byte m at gpuBase - m)   — getDev inverts to forward-native
+// VT pane:  forward   (byte m at VT_TEXT_PLANE + m, the pane buffer the compositor blits)
+const VT = (typeof globalThis.VT_TEXT_PLANE !== 'undefined')
+const VRAM_BASE = VT ? globalThis.VT_TEXT_PLANE : (graphics.getGpuMemBase() - 253950)
+const VRAM_SGN  = VT ? 1 : -1
+function vaddr(m) { return VRAM_BASE + VRAM_SGN * m }
+```
+
+`sys.memcpy`/`sys.pokeBytes` copy forward in the resolved native memory, so this
+works for both directions. The physical branch is identical to the original
+arithmetic (no regression outside vtmgr). Applied so far in
+`assets/disk0/tvdos/bin/taut.js` and `assets/disk0/hopper/include/aa.mjs`
+(used by `bb.js`). Any future direct-VRAM app needs the same one-line `vaddr`.
+
+### Files
+
+- New: `assets/disk0/tvdos/sbin/vtmgr.js` (dispatcher + per-pane bootstrap)
+- `assets/disk0/tvdos/bin/command.js`: `chvt` builtin, `[N]` prompt prefix for
+  VT 2-6, `shell.stdio.out` → `__VT_OUT` delegation
+- `assets/disk0/tvdos/TVDOS.SYS`: boot block runs `\commandrc` (env) in every
+  context, then — only when `!_TVDOS_IS_VT_PANE` — launches `tvdos/sbin/vtmgr`
+  and, on its exit, `\AUTOEXEC.BAT` as the fallback shell
+- `assets/disk0/commandrc`: env-only `set` commands (PATH/INCLPATH/HELPPATH/KEYBOARD)
+- `assets/disk0/AUTOEXEC.BAT`: per-console launch (Korean IME + `command -fancy`)
+- `assets/disk0/tvdos/bin/taut.js`, `assets/disk0/hopper/include/aa.mjs`:
+  `vaddr` VT-aware direct-VRAM addressing
+
+### Gotcha: injectIntChk vs. embedded source
+
+`execApp`/`require` run a program's source through `injectIntChk` (TVDOS.SYS),
+which sed-rewrites the **first** `while`/`for`/`do` of each kind to call a
+per-exec `tvdosSIGTERM_<hash>()` SIGTERM check. When vtmgr embeds the pane
+bootstrap as a string literal, one of those rewrites can land inside the literal
+— and the pane context has no such symbol. vtmgr strips them from the bootstrap
+string with `raw.replace(/tvdosSIGTERM_[A-Za-z0-9_]+\(\);?/g, '')`. Any future
+code that builds executable source as a string literal must do the same.

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,8 +1,11 @@
-echo "Starting TVDOS..."
+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
 
-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 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/dumpfont.js

@@ -8,31 +8,32 @@ if (!exec_args[1]) {
     return 1
 }
 
-let lowfilename = exec_args[1] + "_low.chr"
-let highfilename = exec_args[1] + "_high.chr"
+const fullFilePath = _G.shell.resolvePathInput(exec_args[1]).full
+let lowfilename = fullFilePath + "_low.chr"
+let highfilename = fullFilePath + "_high.chr"
 
 let workarea = sys.malloc(1920)
 
 // dump low rom
 sys.poke(-1299460, 16)
 for (let i = 0; i < 1920; i++) {
-    let byte = sys.peek(-1300607 - i)
+    let byte = sys.peek(-133121 - i)
     sys.poke(workarea + i, byte)
 }
 
-filesystem.open("A", lowfilename, "W")
-dma.ramToCom(workarea, filesystem._toPorts("A")[0], 1920)
+const lowfile = files.open(lowfilename)
+lowfile.pwrite(workarea, 1920, 0)
 println("Wrote CHR rom " + lowfilename)
 
 // dump high rom
 sys.poke(-1299460, 17)
 for (let i = 0; i < 1920; i++) {
-    let byte = sys.peek(-1300607 - i)
+    let byte = sys.peek(-133121 - i)
     sys.poke(workarea + i, byte)
 }
 
-filesystem.open("A", highfilename, "W")
-dma.ramToCom(workarea, filesystem._toPorts("A")[0], 1920)
+const highfile = files.open(highfilename)
+highfile.pwrite(workarea, 1920, 0)
 println("Wrote CHR rom " + highfilename)
 
 sys.free(workarea)

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/home/hangulprint.js

@@ -1,2 +1,2 @@
-println("몬스터 시트라, 이 이름은 특이하게 생긴 프랑스 자동차나 스칸디나비아 보드카에서 온 것은 아닙니다. 고대부터 유래된 과일 시트론에서 영감을 받아 태어난 이 제품은 레몬과 비슷하지만 더 원초적이고 투박합니다. 마치 몬스터 에너지처럼요. 이 고대의 과일과 선조들에게서 영감을 얻은 우리는 전형적인 드링크를 새롭게 해석한 울트라 시트라를 만들었습니다. 울트라 시트라는 새콤달콤한 맛이 입안에서 잔잔하게 퍼지며 상쾌한 맛으로 마무리하죠. 저칼로리에 무설탕이지만 몬스터 에너지만의 블렌드는 변함없이 가득 담겨있답니다.")
-println("멕시코에서는 매년 할로윈 이후 '죽은 자의 날'을 기념합니다. 신비한 분위기 속의 메리골드 꽃과 추억들은 떠난 이들을 축제로 이끕니다. 누구나 매혹될 이국적인 천사의 주스 블렌드, 망고 로코. 환상적인 맛과 몬스터 에너지 만의 마법으로 파티는 계속될 것입니다.")
+unicode.println("몬스터 시트라, 이 이름은 특이하게 생긴 프랑스 자동차나 스칸디나비아 보드카에서 온 것은 아닙니다. 고대부터 유래된 과일 시트론에서 영감을 받아 태어난 이 제품은 레몬과 비슷하지만 더 원초적이고 투박합니다. 마치 몬스터 에너지처럼요. 이 고대의 과일과 선조들에게서 영감을 얻은 우리는 전형적인 드링크를 새롭게 해석한 울트라 시트라를 만들었습니다. 울트라 시트라는 새콤달콤한 맛이 입안에서 잔잔하게 퍼지며 상쾌한 맛으로 마무리하죠. 저칼로리에 무설탕이지만 몬스터 에너지만의 블렌드는 변함없이 가득 담겨있답니다.")
+unicode.println("멕시코에서는 매년 할로윈 이후 '죽은 자의 날'을 기념합니다. 신비한 분위기 속의 메리골드 꽃과 추억들은 떠난 이들을 축제로 이끕니다. 누구나 매혹될 이국적인 천사의 주스 블렌드, 망고 로코. 환상적인 맛과 몬스터 에너지 만의 마법으로 파티는 계속될 것입니다.")

assets/disk0/home/hdk/compile.js

@@ -1,6 +1,6 @@
 if (exec_args[1] === undefined) {
     println("Usage: compile -le/-lo myfile.js")
-    println("    The compiled and linked file will be myfile.out")
+    println("    The compiled and linked file will be myfile.exc")
     return 1
 }
 
@@ -14,7 +14,7 @@ if (exec_args[2]) {
         _G.shell.execute(`rm ${tempFilename}.gz`)
 
         _G.shell.execute(`link -${exec_args[1][2]} ${tempFilename}.bin`)
-        _G.shell.execute(`mv ${tempFilename}.out ${filenameWithoutExt}.out`)
+        _G.shell.execute(`mv ${tempFilename}.exc ${filenameWithoutExt}.exc`)
         _G.shell.execute(`rm ${tempFilename}.bin`)
 }
 // with no linking

assets/disk0/home/hdk/decompile.js

@@ -1,6 +1,6 @@
 if (exec_args[1] === undefined) {
-    println("Usage: decompile myfile.bin")
-    println("The compiled file will be myfile.bin.js")
+    println("Usage: decompile myfile.exc")
+    println("The compiled file will be myfile.exc.js")
     return 1
 }
 _G.shell.execute(`enc ${exec_args[1]} ${exec_args[1]}.gz`)

assets/disk0/home/hdk/enc.js

@@ -1,3 +1,5 @@
+// a simple, symmetric obfuscator with infinite-length key
+
 function seq(s) {
     let out = ""
     let cnt = 0

assets/disk0/home/hdk/link.js

@@ -11,7 +11,6 @@ let infile = files.open(infilePath)
 
 if (!infile.exists) throw Error("No such file: " + infilePath)
 
-let outfile = files.open(infilePath.substringBeforeLast(".") + ".out")
 let outMode = exec_args[1].toLowerCase()
 
 let type = {
@@ -21,6 +20,13 @@ let type = {
     "-c": "\x04"
 }
 
+let ext = {
+    "-r": ".exc", // executable
+    "-e": ".exc", // executable
+    "-o": ".lib", // library
+    "-c": ".cob"  // core object
+}
+
 function toI32(num) {
     const buffer = new ArrayBuffer(4)
     const view = new DataView(buffer)
@@ -40,6 +46,7 @@ let addr = 0
 if (exec_args[3] !== undefined && exec_args[3].toLowerCase() == "-a" && exec_args[4] !== undefined)
     addr = parseInt(exec_args[4], 16)
 
+let outfile = files.open(infilePath.substringBeforeLast(".") + ext[exec_args[3].toLowerCase()])
 outfile.sappend("\x20\xC0\xCC\x0A")
 outfile.sappend(type[outMode] || "\x00")
 outfile.bappend(toI24(addr))

assets/disk0/home/hdk/load.js

@@ -1,5 +1,5 @@
 if (exec_args[1] === undefined) {
-    println("Usage: load myfile.out")
+    println("Usage: load myfile.exc")
     println("   This will load the binary image onto the Core Memory")
     return 1
 }

assets/disk0/home/jpdectest.js

@@ -2,26 +2,18 @@ if (!exec_args[1]) {
     printerrln("Usage: jpdectest image.jpg")
 }
 
-filesystem.open("A", exec_args[1], "R")
+const fullFilePath = _G.shell.resolvePathInput(exec_args[1])
+const file = files.open(fullFilePath.full)
+const fileLen = file.size
+const infile = sys.malloc(file.size); file.pread(infile, fileLen, 0)
 
-let status = com.getStatusCode(0)
-let infile = undefined
-if (0 != status) return status
-
-
-let fileLen = filesystem.getFileLen("A")
-println(`DMA reading ${fileLen} bytes from disk...`)
-infile = sys.malloc(fileLen)
-dma.comToRam(0, 0, infile, fileLen)
-
-
-println("decoding")
+//println("decoding")
 
 // decode
 const [imgw, imgh, channels, imageData] = graphics.decodeImageResample(infile, fileLen, -1, -1)
 
-println(`dim: ${imgw}x${imgh}`)
-println(`converting to displayable format...`)
+//println(`dim: ${imgw}x${imgh}`)
+//println(`converting to displayable format...`)
 
 // convert colour
 graphics.setGraphicsMode(0)

assets/disk0/home/jpdectesthigh.js

@@ -2,26 +2,18 @@ if (!exec_args[1]) {
     printerrln("Usage: jpdectesthigh image.jpg")
 }
 
-filesystem.open("A", exec_args[1], "R")
+const fullFilePath = _G.shell.resolvePathInput(exec_args[1])
+const file = files.open(fullFilePath.full)
+const fileLen = file.size
+const infile = sys.malloc(file.size); file.pread(infile, fileLen, 0)
 
-let status = com.getStatusCode(0)
-let infile = undefined
-if (0 != status) return status
-
-
-let fileLen = filesystem.getFileLen("A")
-println(`DMA reading ${fileLen} bytes from disk...`)
-infile = sys.malloc(fileLen)
-dma.comToRam(0, 0, infile, fileLen)
-
-
-println("decoding")
+//println("decoding")
 
 // decode
 const [imgw, imgh, channels, imageData] = graphics.decodeImageResample(infile, fileLen, -1, -1)
 
-println(`dim: ${imgw}x${imgh}`)
-println(`converting to displayable format...`)
+//println(`dim: ${imgw}x${imgh}`)
+//println(`converting to displayable format...`)
 
 // convert colour
 graphics.setGraphicsMode(4)

assets/disk0/home/playrawpcm.js

@@ -4,7 +4,7 @@ music.pread(samples, 65534)
 
 audio.setPcmMode(0)
 audio.setMasterVolume(0, 255)
-audio.putPcmDataByPtr(samples, 65534, 0)
+audio.putPcmDataByPtr(0, samples, 65534, 0)
 audio.setLoopPoint(0, 65534)
 audio.play(0)*/
 
@@ -127,7 +127,7 @@ while (sampleSize > 0) {
             let readLength = (sampleSize < BLOCK_SIZE) ? sampleSize : BLOCK_SIZE
             readBytes(readLength, decodePtr)
 
-            audio.putPcmDataByPtr(decodePtr, readLength, 0)
+            audio.putPcmDataByPtr(0, decodePtr, readLength, 0)
             audio.setSampleUploadLength(0, readLength)
             audio.startSampleUpload(0)
 

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/HSDPADRV.SYS

@@ -1,7 +1,7 @@
 ///////////////////////////////////////////////////////////////////////////////
 // High Speed Disk Peripheral Adapter (HSDPA) Driver for TVDOS
 // This driver treats each disk from HSDPA as a single large file
-// Created by Claude on 2025-08-16
+// Created by CuriousTorvald and Claude on 2025-08-16
 ///////////////////////////////////////////////////////////////////////////////
 
 // Add TAPE device names to reserved names
@@ -117,8 +117,9 @@ for (let tapeIndex = 0; tapeIndex < 4; tapeIndex++) {
     
     // Get file size - for HSDPA tapes, we don't know the size ahead of time
     // So we return a very large number to indicate it's available
+    // Using Number.MAX_SAFE_INTEGER to support files >2GB
     driver.getFileLen = (fd) => {
-        return 0x7FFFFFFF // Return max positive 32-bit integer
+        return Number.MAX_SAFE_INTEGER // 2^53 - 1 (9007199254740991) - safe for JS arithmetic
     }
     
     // Sequential read from tape

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
 }
@@ -870,11 +877,21 @@ Object.freeze(_TVDOS.DRV.FS.DEVPT)
 _TVDOS.DRV.FS.DEVFBIPF = {}
 
 _TVDOS.DRV.FS.DEVFBIPF.pwrite = (fd, infilePtr, count, _2) => {
-    let decodefun = ([graphics.decodeIpf1, graphics.decodeIpf2])[sys.peek(infilePtr + 13)]
+    let flags = sys.peek(infilePtr+12)
+    let ipfType = sys.peek(infilePtr+13)
+    let isProgressive = (flags & 0x80) != 0
+    let hasAlpha = (flags & 0x01) != 0
+
+    // Select decode function based on type and progressive flag
+    let decodefun
+    if (isProgressive) {
+        decodefun = ([graphics.decodeIpf1Progressive, graphics.decodeIpf2Progressive])[ipfType]
+    } else {
+        decodefun = ([graphics.decodeIpf1, graphics.decodeIpf2])[ipfType]
+    }
+
     let width = sys.peek(infilePtr+8) | (sys.peek(infilePtr+9) << 8)
     let height = sys.peek(infilePtr+10) | (sys.peek(infilePtr+11) << 8)
-    let hasAlpha = (sys.peek(infilePtr+12) != 0)
-    let ipfType = sys.peek(infilePtr+13)
     let imgLen = sys.peek(infilePtr+24) | (sys.peek(infilePtr+25) << 8) | (sys.peek(infilePtr+26) << 16) | (sys.peek(infilePtr+27) << 24)
 
     let ipfbuf = sys.malloc(imgLen)
@@ -924,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))
     }
 }
 
@@ -973,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)
 
@@ -1014,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 = {}
@@ -1225,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;
@@ -1252,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)
 
@@ -1366,12 +1286,12 @@ unicode.getUniprint = (c) => {
             return unicode.uniprint[k]
 }}
 
-print = function(str) {
+unicode.print = (str) => {
     if ((typeof str === 'string' || str instanceof String) && str.length > 0) {
+
         let cp = unicode.utf8toCodepoints(str)
         cp.forEach(c => {
             let q = unicode.getUniprint(c)
-
             if (q == undefined || !q[0](c)) {
                 con.addch(4)
                 con.curs_right()
@@ -1381,6 +1301,34 @@ print = function(str) {
             }
         })
     }
+    else {
+        sys.print(str)
+    }
+}
+
+unicode.println = (str) => {
+    unicode.print(str+'\n\n')
+}
+
+unicode.strlen = (str) => {
+    // Convert string to an array of codepoints using spread operator
+    // This correctly handles surrogate pairs and counts each codepoint as one
+    return unicode.utf8toCodepoints(str).length
+}
+
+unicode.visualStrlen = (str) => {
+    function isTripleWidth(c) {
+        return (0xAC00 <= c && c <= 0xD7FF) && [1,4,8,10,13].includes(((c - 0xAC00) / 588)|0)
+    }
+
+    function isDoubleWidth(c) {
+        return (0x3000 <= c && c <= 0x303f) || (0x3100 <= c && c <= 0x312f) || (0x3200 <= c && c <= 0x33ff) ||
+        (0xAC00 <= c && c <= 0xD7FF) || (0xFE30 <= c && c <= 0xFE4F) || (0xFF00 <= c && c <= 0xff60)
+    }
+
+    // Convert string to an array of codepoints using spread operator
+    // This correctly handles surrogate pairs and counts each codepoint as one
+    return unicode.utf8toCodepoints(str).reduce((acc, c) => acc + (isTripleWidth(c) ? 3 : isDoubleWidth(c) ? 2 : 1), 0)
 }
 
 Object.freeze(unicode);
@@ -1494,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'
@@ -1509,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);
 }
 
 
@@ -1526,9 +1471,40 @@ try {
     serial.println("Warning: Could not load HSDPA driver: " + e.message)
 }
 
-// Boot script
-serial.println(`TVDOS.SYS initialised on VM ${sys.getVmId()}, running boot script...`);
+// Boot script. The work is split across two files:
+//   \commandrc    -- environment (`set` commands); run in EVERY context.
+//   \AUTOEXEC.BAT -- per-console launch (IME + interactive shell).
+// vtmgr re-evaluates TVDOS.SYS inside each per-VT pane; a pane sets
+// _TVDOS_IS_VT_PANE so it only replays the environment here and leaves the
+// AUTOEXEC launch to vtmgr's pane bootstrap (which avoids recursively
+// spawning vtmgr inside a pane).
+{
+    let cmdsrc = files.open("A:/tvdos/bin/command.js").sread()
+    let runBatch = (path) => eval(`var _BAT=function(exec_args){${cmdsrc}\n};_BAT`)(["", "-c", path])
 
-let cmdfile = files.open("A:/tvdos/bin/command.js")
-eval(`var _AUTOEXEC=function(exec_args){${cmdfile.sread()}\n};` +
-      `_AUTOEXEC`)(["", "-c", "\\AUTOEXEC.BAT"])
+    // Environment first, boot and pane alike. Gives every pane the same
+    // PATH / KEYBOARD / etc. natively, with no env-snapshot replay needed.
+    // \commandrc has no .BAT extension (so command.js's batch-file path,
+    // which keys off the extension, won't pick it up); run it line-by-line.
+    // `set` mutates the shared _TVDOS.variables, so the effect persists across
+    // the per-line shell invocations. Skip blanks and `rem` comments.
+    let rcFile = files.open("A:/commandrc")
+    if (rcFile.exists) {
+        rcFile.sread().split('\n').forEach((line) => {
+            let t = line.trim()
+            if (t.length > 0 && !/^rem(\s|$)/i.test(t)) runBatch(line)
+        })
+    }
+
+    if (typeof _TVDOS_IS_VT_PANE === "undefined" || !_TVDOS_IS_VT_PANE) {
+        serial.println(`TVDOS.SYS initialised on VM ${sys.getVmId()}, running boot script...`);
+        // Boot console: hand the screen to the virtual-console multiplexer.
+        // When it exits (Alt-0), fall through to AUTOEXEC so the console is
+        // never left bare.
+        runBatch("tvdos/sbin/vtmgr")
+        runBatch("\\AUTOEXEC.BAT")
+    }
+    else {
+        serial.println(`TVDOS.SYS re-initialised in VT pane on VM ${sys.getVmId()}`);
+    }
+}

assets/disk0/tvdos/bin/command.js

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

assets/disk0/tvdos/bin/hop.alias

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

assets/disk0/tvdos/bin/hopper.js

@@ -0,0 +1,956 @@
+/**
+ * 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/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/microtone.alias

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

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

@@ -1,236 +0,0 @@
-println("DEPRECATION NOTICE: MP3 Playback function will be removed for following reason")
-println("\tMP3 does not really fit in the time TSVM targets to emulate")
-return 1
-
-
-const Mp3 = require('mp3dec')
-const pcm = require("pcm")
-const interactive = exec_args[2] && exec_args[2].toLowerCase() == "-i"
-
-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)
-    }
-
-    /*readFull(n) {
-        throw Error()
-        let ptr = this.seq.readBytes(n)
-        return 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
-    }
-
-    readByteNumbers(n) {
-        let ptr = this.seq.readBytes(n)
-        try {
-            let s = []
-            for (let i = 0; i < n; i++) {
-                if (i >= this.length) break
-                s.push(sys.peek(ptr + i))
-            }
-            sys.free(ptr)
-            return s
-        }
-        catch (e) {
-            println(`n: ${n}; ptr: ${ptr}`)
-            println(e)
-        }
-    }
-
-    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 remaining() {
-        return this.length - this.getReadCount()
-    }*/
-}
-
-
-
-con.curs_set(0)
-let [cy, cx] = con.getyx()
-let [__, CONSOLE_WIDTH] = con.getmaxyx()
-let paintWidth = CONSOLE_WIDTH - 16
-if (interactive) {
-    println("Decoding...")
-}
-
-
-printdbg("pre-decode...")
-let filebuf = new SequentialFileBuffer(_G.shell.resolvePathInput(exec_args[1]).full)
-const FILE_SIZE = filebuf.length
-let decoder = Mp3.newDecoder(filebuf)
-if (decoder === null) throw Error("decoder is null")
-
-const HEADER_SIZE = decoder.headerSize + 3
-const FRAME_SIZE = decoder.frameSize // only works reliably for CBR
-
-//serial.println(`header size: ${HEADER_SIZE}`)
-//serial.println(`frame size: ${FRAME_SIZE}`)
-
-audio.resetParams(0)
-audio.purgeQueue(0)
-audio.setPcmMode(0)
-audio.setPcmQueueCapacityIndex(0, 5) // queue size is now 24
-const QUEUE_MAX = audio.getPcmQueueCapacity(0)
-audio.setMasterVolume(0, 255)
-audio.play(0)
-
-let decodedLength = 0
-let readPtr = sys.malloc(8000)
-let decodePtr = sys.malloc(12000)
-
-function bytesToSec(i) {
-    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 decodeAndResample(inPtr, outPtr, inputLen) {
-    // TODO resample
-    for (let k = 0; k < inputLen / 2; k+=2) {
-        let sample = [
-            pcm.u16Tos16(sys.peek(inPtr + k*2 + 0) | (sys.peek(inPtr + k*2 + 1) << 8)),
-            pcm.u16Tos16(sys.peek(inPtr + k*2 + 2) | (sys.peek(inPtr + k*2 + 3) << 8))
-        ]
-        sys.poke(outPtr + k, pcm.s16Tou8(sample[0]))
-        sys.poke(outPtr + k + 1, pcm.s16Tou8(sample[1]))
-        // soothing visualiser(????)
-//        printvis(`${sampleToVisual(sample[0])} | ${sampleToVisual(sample[1])}`)
-    }
-}
-
-
-function printPlayBar() {
-}
-
-let stopPlay = false
-con.curs_set(0)
-if (interactive) {
-    con.move(cy, cy)
-    println("Push and hold Backspace to exit")
-}
-[cy, cx] = con.getyx()
-function printPlayBar(currently) {
-    if (interactive) {
-//        let currently = decodedLength
-        let total = FILE_SIZE - HEADER_SIZE
-
-        let currentlySec = Math.round(bytesToSec(currently))
-        let totalSec = Math.round(bytesToSec(total))
-
-        con.move(cy, 1)
-        print(' '.repeat(15))
-        con.move(cy, 1)
-
-        print(`${secToReadable(currentlySec)} / ${secToReadable(totalSec)}`)
-
-        con.move(cy, 15)
-        print(' ')
-        let progressbar = '\x84205u'.repeat(paintWidth + 1)
-        print(progressbar)
-
-        con.mvaddch(cy, 16 + Math.round(paintWidth * (currently / total)), 0xDB)
-    }
-}
-let t1 = sys.nanoTime()
-let errorlevel = 0
-let bufRealTimeLen = 36
-try {
-    decoder.decode((ptr, len, pos)=>{
-
-        if (interactive) {
-            sys.poke(-40, 1)
-            if (sys.peek(-41) == 67) {
-                stopPlay = true
-                throw "STOP"
-            }
-        }
-
-        printPlayBar(pos)
-
-        let t2 = sys.nanoTime()
-
-        decodedLength += len
-
-//        serial.println(`Audio queue size: ${audio.getPosition(0)}/${QUEUE_MAX}`)
-
-        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})`)
-//                serial.println(`Queue full, waiting until the queue has some space (${audio.getPosition(0)}/${QUEUE_MAX})`)
-                sys.sleep(bufRealTimeLen)
-            }
-        }
-
-
-
-        decodeAndResample(ptr, decodePtr, len)
-
-        audio.putPcmDataByPtr(decodePtr, len >> 1, 0)
-        audio.setSampleUploadLength(0, len >> 1)
-        audio.startSampleUpload(0)
-
-
-        let decodingTime = (t2 - t1) / 1000000.0
-        bufRealTimeLen = (len >> 1) / 64000.0 * 1000
-        t1 = t2
-
-        printdbg(`Decoded ${decodedLength} bytes; target: ${bufRealTimeLen} ms, lag: ${decodingTime - bufRealTimeLen} ms`)
-
-
-    }) // now you got decoded PCM data
-}
-catch (e) {
-    if (e != "STOP") {
-        printerrln(e)
-        errorlevel = 1
-    }
-}
-finally {
-    //audio.stop(0)
-    sys.free(readPtr)
-    sys.free(decodePtr)
-}
-
-return errorlevel

assets/disk0/tvdos/bin/playmv1.js

@@ -1,4 +1,4 @@
-// usage: playmov moviefile.mov [/i]
+// usage: playmv1 moviefile.mv1 [/i]
 const SND_BASE_ADDR = audio.getBaseAddr()
 const interactive = exec_args[2] && exec_args[2].toLowerCase() == "-i"
 const WIDTH = 560
@@ -326,7 +326,7 @@ while (!stopPlay && seqread.getReadCount() < FILE_LENGTH) {
                     // RAW PCM packets (decode on the fly)
                     else if (packetType == 0x1000 || packetType == 0x1001) {
                         let frame = seqread.readBytes(readLength)
-                        audio.putPcmDataByPtr(frame, readLength, 0)
+                        audio.putPcmDataByPtr(0, frame, readLength, 0)
                         audio.setSampleUploadLength(0, readLength)
                         audio.startSampleUpload(0)
                         sys.free(frame)

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

@@ -0,0 +1,214 @@
+// playtad — TAD (TSVM Advanced Audio) player with the shared playgui visualiser.
+// Usage: playtad <file.tad> [-i | -d]
+//   -i   Interactive mode (visualiser + progress bar; hold Backspace to exit)
+//   -d   Dump mode (print the first three chunks to serial for debugging)
+
+const SND_BASE_ADDR = audio.getBaseAddr()
+const SND_MEM_ADDR  = audio.getMemAddr()
+// tadInputBin 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
+
+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 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) {
+        if (Array.isArray(path)) throw Error("arg #1 is path(string), not array")
+        this.path = path
+        this.file = files.open(path)
+        this.length = this.file.size
+        this.seq = require("seqread")
+        this.seq.prepare(path)
+    }
+    readBytes(size, ptr) { return this.seq.readBytes(size, ptr) }
+    readByte() {
+        const ptr = this.seq.readBytes(1)
+        const val = sys.peek(ptr)
+        sys.free(ptr)
+        return val
+    }
+    readShort() {
+        const ptr = this.seq.readBytes(2)
+        const val = sys.peek(ptr) | (sys.peek(ptr + 1) << 8)
+        sys.free(ptr)
+        return val
+    }
+    readInt() {
+        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
+    }
+    unread(diff) {
+        const newSkipLen = this.seq.getReadCount() - diff
+        this.seq.prepare(this.path)
+        this.seq.skip(newSkipLen)
+    }
+    rewind() { this.seq.prepare(this.path) }
+    getReadCount() { return this.seq.getReadCount() }
+}
+
+const filebuf   = new SequentialFileBuffer(_G.shell.resolvePathInput(exec_args[1]).full)
+const FILE_SIZE = filebuf.length
+
+if (FILE_SIZE < 7) {
+    serial.println(`ERROR: File too small (${FILE_SIZE} bytes). Expected TAD format.`)
+    return 1
+}
+
+// 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()
+
+if (firstSampleCount < 0 || firstSampleCount > 65536) {
+    serial.println(`ERROR: Invalid sample count ${firstSampleCount}. File may be corrupted.`)
+    return 1
+}
+if (firstMaxIndex < 0 || firstMaxIndex > 255) {
+    serial.println(`ERROR: Invalid max index ${firstMaxIndex}. File may be corrupted.`)
+    return 1
+}
+if (firstPayloadSize < 1 || firstPayloadSize > 65536) {
+    serial.println(`ERROR: Invalid payload size ${firstPayloadSize}. File may be corrupted.`)
+    return 1
+}
+
+filebuf.rewind()
+
+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: ${firstSampleCount} samples, Q${firstMaxIndex}, ${firstPayloadSize} bytes payload`)
+    serial.println(`Chunk Duration: ${bufRealTimeLen} ms`)
+    serial.println(``)
+}
+
+let bytes_left    = FILE_SIZE
+let decodedLength = 0
+let chunkNumber   = 0
+
+function bytesToSec(i) {
+    return Math.round((i / FILE_SIZE) * (FILE_SIZE / AVG_CHUNK_SIZE) * (bufRealTimeLen / 1000))
+}
+
+audio.resetParams(0)
+audio.purgeQueue(0)
+audio.setPcmMode(0)
+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 }
+
+        const sampleCount = filebuf.readShort()
+        const maxIndex    = filebuf.readByte()
+        const payloadSize = filebuf.readInt()
+
+        if (sampleCount < 0 || sampleCount > 65536) {
+            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}.`)
+            errorlevel = 1; break
+        }
+        if (payloadSize < 1 || payloadSize > 65536) {
+            serial.println(`ERROR: Chunk ${chunkNumber}: Invalid payload size ${payloadSize}.`)
+            errorlevel = 1; break
+        }
+        if (payloadSize + 7 > bytes_left) {
+            serial.println(`ERROR: Chunk ${chunkNumber}: Chunk size exceeds remaining file size.`)
+            errorlevel = 1; break
+        }
+
+        if (dumpCoeffs && chunkNumber < 3) {
+            serial.println(`=== Chunk ${chunkNumber} ===`)
+            serial.println(`  Sample Count: ${sampleCount}`)
+            serial.println(`  Max Index: ${maxIndex}`)
+            serial.println(`  Payload Size: ${payloadSize} bytes`)
+        }
+
+        // Read entire chunk (header + payload) into TAD input buffer.
+        filebuf.unread(7)
+        filebuf.readBytes(7 + payloadSize, TAD_INPUT_ADDR)
+
+        audio.tadDecode()
+        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) {
+            // 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)
+            }
+        }
+
+        const chunkSize = 7 + payloadSize
+        bytes_left    -= chunkSize
+        decodedLength += chunkSize
+        chunkNumber++
+
+        if (dumpCoeffs && chunkNumber >= 3) {
+            serial.println(`... (remaining chunks omitted)`)
+        }
+    }
+} catch (e) {
+    printerrln(e)
+    errorlevel = 1
+} finally {
+    if (interactive) gui.audioClose()
+}
+
+return errorlevel

assets/disk0/tvdos/bin/playtev.js

@@ -1,16 +1,17 @@
-// Created by Claude on 2025-08-18.
+// Created by CuriousTorvald and Claude on 2025-08-18.
 // TSVM Enhanced Video (TEV) Format Decoder - YCoCg-R 4:2:0 Version
 // Usage: playtev moviefile.tev [options]
 // Options: -i (interactive), -debug-mv (show motion vector debug visualization)
 //          -deinterlace=algorithm (yadif or bwdif, default: yadif)
-//          -nodeblock (disble deblocking filter)
+//          -nodeblock (disable post-processing deblocking filter)
+//          -boundaryaware (enable boundary-aware decoding to prevent artifacts at DCT level)
 
 const WIDTH = 560
 const HEIGHT = 448
 const BLOCK_SIZE = 16  // 16x16 blocks for YCoCg-R
 const TEV_MAGIC = [0x1F, 0x54, 0x53, 0x56, 0x4D, 0x54, 0x45, 0x56] // "\x1FTSVM TEV"
 const TEV_VERSION_YCOCG = 2  // YCoCg-R version
-const TEV_VERSION_XYB = 3    // XYB version
+const TEV_VERSION_ICtCp = 3    // ICtCp version
 const SND_BASE_ADDR = audio.getBaseAddr()
 const pcm = require("pcm")
 const MP2_FRAME_SIZE = [144,216,252,288,360,432,504,576,720,864,1008,1152,1440,1728]
@@ -25,7 +26,8 @@ const TEV_MODE_MOTION = 0x03
 const TEV_PACKET_IFRAME = 0x10
 const TEV_PACKET_PFRAME = 0x11
 const TEV_PACKET_AUDIO_MP2 = 0x20
-const TEV_PACKET_SUBTITLE = 0x30
+const TEV_PACKET_SUBTITLE = 0x30       // Legacy SSF (frame-locked)
+const TEV_PACKET_SUBTITLE_TC = 0x31    // SSF-TC (timecode-based)
 const TEV_PACKET_SYNC = 0xFF
 
 // Subtitle opcodes (SSF format)
@@ -41,11 +43,16 @@ let subtitleVisible = false
 let subtitleText = ""
 let subtitlePosition = 0  // 0=bottom center (default)
 
+// SSF-TC subtitle event buffer
+let subtitleEvents = []  // Array of {timecode_ns, index, opcode, text}
+let nextSubtitleEventIndex = 0  // Next event to check
+
 // Parse command line options
 let interactive = false
 let debugMotionVectors = false
 let deinterlaceAlgorithm = "yadif"
-let enableDeblocking = true  // Default: enabled (use -nodeblock to disable)
+let enableDeblocking = false  // Default: disabled (use -deblock to enable)
+let enableBoundaryAwareDecoding = false  // Default: disabled (use -boundaryaware to enable) // suitable for still frame and slide shows, absolutely unsuitable for videos
 
 if (exec_args.length > 2) {
     for (let i = 2; i < exec_args.length; i++) {
@@ -54,8 +61,10 @@ if (exec_args.length > 2) {
             interactive = true
         } else if (arg === "-debug-mv") {
             debugMotionVectors = true
-        } else if (arg === "-nodeblock") {
-            enableDeblocking = false
+        } else if (arg === "-deblock") {
+            enableDeblocking = true
+        } else if (arg === "-boundaryaware") {
+            enableBoundaryAwareDecoding = true
         } else if (arg.startsWith("-deinterlace=")) {
             deinterlaceAlgorithm = arg.substring(13)
         }
@@ -70,18 +79,17 @@ let notifHideTimer = 0
 const NOTIF_SHOWUPTIME = 3000000000
 let [cy, cx] = con.getyx()
 
-let seqreadserial = require("seqread")
-let seqreadtape = require("seqreadtape")
+let gui = require("playgui")
 let seqread = undefined
 let fullFilePathStr = fullFilePath.full
 
 // Select seqread driver to use
 if (fullFilePathStr.startsWith('$:/TAPE') || fullFilePathStr.startsWith('$:\\TAPE')) {
-    seqread = seqreadtape
+    seqread = require("seqreadtape")
     seqread.prepare(fullFilePathStr)
     seqread.seek(0)
 } else {
-    seqread = seqreadserial
+    seqread = require("seqread")
     seqread.prepare(fullFilePathStr)
 }
 
@@ -97,6 +105,9 @@ audio.purgeQueue(0)
 audio.setPcmMode(0)
 audio.setMasterVolume(0, 255)
 
+// set colour zero as half-opaque black
+graphics.setPalette(0, 0, 0, 0, 9)
+
 // Subtitle display functions
 function clearSubtitleArea() {
     // Clear the subtitle area at the bottom of the screen
@@ -268,6 +279,99 @@ function displaySubtitle(text, position = 0) {
     con.color_pair(oldFgColor, oldBgColor)
 }
 
+// Parse SSF-TC subtitle packet and add to event buffer (0x31)
+function parseSubtitlePacketTC(packetSize) {
+    // Read subtitle index (24-bit, little-endian)
+    let indexByte0 = seqread.readOneByte()
+    let indexByte1 = seqread.readOneByte()
+    let indexByte2 = seqread.readOneByte()
+    let index = indexByte0 | (indexByte1 << 8) | (indexByte2 << 16)
+
+    // Read timecode (64-bit, little-endian)
+    let timecode_ns = 0
+    for (let i = 0; i < 8; i++) {
+        let byte = seqread.readOneByte()
+        timecode_ns += byte * Math.pow(2, i * 8)
+    }
+
+    // Read opcode
+    let opcode = seqread.readOneByte()
+    let remainingBytes = packetSize - 12  // Subtract 3 (index) + 8 (timecode) + 1 (opcode)
+
+    // Read text if present
+    let text = null
+    if (remainingBytes > 1 && (opcode === SSF_OP_SHOW || (opcode >= 0x10 && opcode <= 0x2F))) {
+        let textBytes = seqread.readBytes(remainingBytes)
+        text = ""
+        for (let i = 0; i < remainingBytes - 1; i++) {  // -1 for null terminator
+            let byte = sys.peek(textBytes + i)
+            if (byte === 0) break
+            text += String.fromCharCode(byte)
+        }
+        sys.free(textBytes)
+    } else if (remainingBytes > 0) {
+        // Skip remaining bytes
+        let skipBytes = seqread.readBytes(remainingBytes)
+        sys.free(skipBytes)
+    }
+
+    // Add event to buffer
+    subtitleEvents.push({
+        timecode_ns: timecode_ns,
+        index: index,
+        opcode: opcode,
+        text: text
+    })
+}
+
+// Process subtitle events based on current playback time
+function processSubtitleEvents(currentTimeNs) {
+    // Process all events whose timecode has been reached
+    while (nextSubtitleEventIndex < subtitleEvents.length) {
+        let event = subtitleEvents[nextSubtitleEventIndex]
+
+        if (event.timecode_ns > currentTimeNs) {
+            break  // Haven't reached this event yet
+        }
+
+        // Execute the subtitle event
+        switch (event.opcode) {
+            case SSF_OP_SHOW:
+                subtitleText = event.text || ""
+                subtitleVisible = true
+                displaySubtitle(subtitleText, subtitlePosition)
+                break
+
+            case SSF_OP_HIDE:
+                subtitleVisible = false
+                subtitleText = ""
+                clearSubtitleArea()
+                break
+
+            case SSF_OP_MOVE:
+                if (event.text && event.text.length > 0) {
+                    let newPosition = event.text.charCodeAt(0)
+                    if (newPosition >= 0 && newPosition <= 8) {
+                        subtitlePosition = newPosition
+                        if (subtitleVisible && subtitleText.length > 0) {
+                            clearSubtitleArea()
+                            displaySubtitle(subtitleText, subtitlePosition)
+                        }
+                    }
+                }
+                break
+
+            case SSF_OP_UPLOAD_LOW_FONT:
+            case SSF_OP_UPLOAD_HIGH_FONT:
+                // Font upload handled during packet parsing
+                break
+        }
+
+        nextSubtitleEventIndex++
+    }
+}
+
+// Process legacy frame-locked subtitle packet (0x30)
 function processSubtitlePacket(packetSize) {
     // Read subtitle packet data according to SSF format
     // uint24 index + uint8 opcode + variable arguments
@@ -384,15 +488,15 @@ if (!magicMatching) {
 
 // Read header
 let version = seqread.readOneByte()
-if (version !== TEV_VERSION_YCOCG && version !== TEV_VERSION_XYB) {
-    println(`Unsupported TEV version: ${version} (expected ${TEV_VERSION_YCOCG} for YCoCg-R or ${TEV_VERSION_XYB} for XYB)`)
+if (version !== TEV_VERSION_YCOCG && version !== TEV_VERSION_ICtCp) {
+    println(`Unsupported TEV version: ${version} (expected ${TEV_VERSION_YCOCG} for YCoCg-R or ${TEV_VERSION_ICtCp} for ICtCp)`)
     return 1
 }
 
-let colorSpace = (version === TEV_VERSION_XYB) ? "XYB" : "YCoCg-R"
+let colorSpace = (version === TEV_VERSION_ICtCp) ? "ICtCp" : "YCoCg"
 if (interactive) {
     con.move(1,1)
-    println(`Push and hold Backspace to exit | TEV Format ${version} (${colorSpace}) | Deblocking: ${enableDeblocking ? 'ON' : 'OFF'}`)
+    println(`Push and hold Backspace to exit | ${colorSpace} | Deblock: ${enableDeblocking ? 'ON' : 'OFF'} | EdgeAware: ${enableBoundaryAwareDecoding ? 'ON' : 'OFF'}`);
 }
 
 let width = seqread.readShort()
@@ -417,6 +521,7 @@ serial.println(`  FPS: ${(isNTSC) ? (fps * 1000 / 1001) : fps}`)
 serial.println(`  Duration: ${totalFrames / fps}`)
 serial.println(`  Audio: ${hasAudio ? "Yes" : "No"}`)
 serial.println(`  Resolution: ${width}x${height}, ${isInterlaced ? "interlaced" : "progressive"}`)
+serial.println(`  Quality: Y=${qualityY}, Co=${qualityCo}, Cg=${qualityCg}`)
 
 
 // DEBUG interlace raw output
@@ -436,13 +541,14 @@ function updateDataRateBin(rate) {
     }
 }
 
-function getVideoRate(rate) {
+function getVideoRate() {
     let baseRate = videoRateBin.reduce((a, c) => a + c, 0)
     let mult = fps / videoRateBin.length
     return baseRate * mult
 }
 
 let FRAME_TIME = 1.0 / fps
+let FRAME_TIME_NS = (1000000000.0 / fps)  // Frame time in nanoseconds for subtitle timing
 // Ultra-fast approach: always render to display, use dedicated previous frame buffer
 const FRAME_PIXELS = width * height
 
@@ -577,11 +683,12 @@ function rotateFieldBuffers() {
 }
 
 let frameDuped = false
+let currentFrameType = "I"
 
 // Main decoding loop - simplified for performance
 try {
     let t1 = sys.nanoTime()
-    while (!stopPlay && seqread.getReadCount() < FILE_LENGTH && trueFrameCount < totalFrames) {
+    while (!stopPlay && seqread.getReadCount() < FILE_LENGTH /*&& trueFrameCount < totalFrames*/) {
 
         // Handle interactive controls
         if (interactive) {
@@ -609,7 +716,7 @@ try {
                 PREV_RGB_ADDR = temp
 
             } else if (packetType == TEV_PACKET_IFRAME || packetType == TEV_PACKET_PFRAME) {
-                // Video frame packet (always includes rate control factor)
+                // Video frame packet
                 let payloadLen = seqread.readInt()
                 let compressedPtr = seqread.readBytes(payloadLen)
                 updateDataRateBin(payloadLen)
@@ -624,11 +731,6 @@ try {
 
                 // Decompress using gzip
                 // Optimized buffer size calculation for TEV YCoCg-R blocks
-                let blocksX = (width + 15) >> 4  // 16x16 blocks
-                let blocksY = (height + 15) >> 4
-                let tevBlockSize = 1 + 4 + 2 + (256 * 2) + (64 * 2) + (64 * 2) // mode + mv + cbp + Y(16x16) + Co(8x8) + Cg(8x8)
-                let decompressedSize = Math.max(payloadLen * 4, blocksX * blocksY * tevBlockSize) // More efficient sizing
-
                 let actualSize
                 let decompressStart = sys.nanoTime()
                 try {
@@ -643,7 +745,7 @@ try {
                     continue
                 }
 
-                // Hardware-accelerated TEV decoding to RGB buffers (YCoCg-R or XYB based on version)
+                // Hardware-accelerated TEV decoding to RGB buffers (YCoCg-R or ICtCp based on version)
                 try {
                     // duplicate every 1000th frame (pass a turn every 1000n+501st) if NTSC
                     if (!isNTSC || frameCount % 1000 != 501 || frameDuped) {
@@ -655,14 +757,14 @@ try {
                         if (isInterlaced) {
                             // For interlaced: decode current frame into currentFieldAddr
                             // For display: use prevFieldAddr as current, currentFieldAddr as next
-                            graphics.tevDecode(blockDataPtr, nextFieldAddr, currentFieldAddr, width, decodingHeight, [qualityY, qualityCo, qualityCg], trueFrameCount, debugMotionVectors, version, enableDeblocking)
+                            graphics.tevDecode(blockDataPtr, nextFieldAddr, currentFieldAddr, width, decodingHeight, qualityY, qualityCo, qualityCg, trueFrameCount, debugMotionVectors, version, enableDeblocking, enableBoundaryAwareDecoding)
                             graphics.tevDeinterlace(trueFrameCount, width, decodingHeight, prevFieldAddr, currentFieldAddr, nextFieldAddr, CURRENT_RGB_ADDR, deinterlaceAlgorithm)
 
                             // Rotate field buffers for next frame: NEXT -> CURRENT -> PREV
                             rotateFieldBuffers()
                         } else {
                             // Progressive or first frame: normal decoding without temporal prediction
-                            graphics.tevDecode(blockDataPtr, CURRENT_RGB_ADDR, PREV_RGB_ADDR, width, decodingHeight, [qualityY, qualityCo, qualityCg], trueFrameCount, debugMotionVectors, version, enableDeblocking)
+                            graphics.tevDecode(blockDataPtr, CURRENT_RGB_ADDR, PREV_RGB_ADDR, width, decodingHeight, qualityY, qualityCo, qualityCg, trueFrameCount, debugMotionVectors, version, enableDeblocking, enableBoundaryAwareDecoding)
                         }
 
                         decodeTime = (sys.nanoTime() - decodeStart) / 1000000.0  // Convert to milliseconds
@@ -670,7 +772,7 @@ try {
 
                         // Upload RGB buffer to display framebuffer with dithering
                         let uploadStart = sys.nanoTime()
-                        graphics.uploadRGBToFramebuffer(CURRENT_RGB_ADDR, width, height, frameCount, true)
+                        graphics.uploadRGBToFramebuffer(CURRENT_RGB_ADDR, width, height, frameCount, false)
                         uploadTime = (sys.nanoTime() - uploadStart) / 1000000.0  // Convert to milliseconds
                     }
                     else {
@@ -679,6 +781,12 @@ try {
                         serial.println(`Frame ${frameCount}: Duplicating previous frame`)
                     }
 
+                    // Process SSF-TC subtitle events based on current playback time
+                    if (subtitleEvents.length > 0) {
+                        let currentTimeNs = frameCount * FRAME_TIME_NS
+                        processSubtitleEvents(currentTimeNs)
+                    }
+
                     // Defer audio playback until a first frame is sent
                     if (isInterlaced) {
                         // fire audio after frame 1
@@ -710,6 +818,8 @@ try {
                     serial.println(`Frame ${frameCount}: Decompress=${decompressTime.toFixed(1)}ms, Decode=${decodeTime.toFixed(1)}ms, Upload=${uploadTime.toFixed(1)}ms, Bias=${biasTime.toFixed(1)}ms, Total=${totalTime.toFixed(1)}ms`)
                 }
 
+                currentFrameType = packetType == TEV_PACKET_IFRAME ? "I" : "P"
+
             } else if (packetType == TEV_PACKET_AUDIO_MP2) {
                 // MP2 Audio packet
                 let audioLen = seqread.readInt()
@@ -724,9 +834,14 @@ try {
                 audio.mp2UploadDecoded(0)
 
             } else if (packetType == TEV_PACKET_SUBTITLE) {
-                // Subtitle packet
+                // Legacy frame-locked subtitle packet (0x30)
                 let packetSize = seqread.readInt()
                 processSubtitlePacket(packetSize)
+
+            } else if (packetType == TEV_PACKET_SUBTITLE_TC) {
+                // SSF-TC subtitle packet (0x31) - parse and buffer for later playback
+                let packetSize = seqread.readInt()
+                parseSubtitlePacketTC(packetSize)
             } else if (packetType == 0x00) {
                 // Silently discard, faulty subtitle creation can cause this as 0x00 is used as an argument terminator
             } else {
@@ -743,27 +858,37 @@ try {
         if (interactive) {
             notifHideTimer += (t2 - t1)
             if (!notifHidden && notifHideTimer > (NOTIF_SHOWUPTIME + FRAME_TIME)) {
-                con.move(1, 1)
-                print(' '.repeat(79))
+                // clearing function here
                 notifHidden = true
             }
 
-            if (!hasSubtitle) {
-                con.move(31, 1)
-                graphics.setTextFore(161)
-                print(`Frame: ${frameCount}/${totalFrames} (${((frameCount / akku2 * 100)|0) / 100}f)         `)
-                con.move(32, 1)
-                graphics.setTextFore(161)
-                print(`VRate: ${(getVideoRate() / 1024 * 8)|0} kbps                               `)
-                con.move(1, 1)
+
+            con.color_pair(253, 0)
+            let guiStatus = {
+                fps: fps,
+                videoRate: getVideoRate(),
+                frameCount: frameCount,
+                totalFrames: totalFrames,
+                frameMode: currentFrameType,
+                qY: qualityY,
+                qCo: qualityCo,
+                qCg: qualityCg,
+                akku: akku2,
+                fileName: fullFilePathStr,
+                fileOrd: 1,
+                resolution: `${width}x${height}${(isInterlaced) ? 'i' : ''}`,
+                colourSpace: colorSpace,
+                currentStatus: 1
             }
+            gui.printBottomBar(guiStatus)
+            gui.printTopBar(guiStatus, 1)
         }
 
         t1 = t2
     }
 }
 catch (e) {
-    printerrln(`TEV ${colorSpace} decode error: ${e}`)
+    serial.printerr(`TEV ${colorSpace} decode error: ${e}`)
     errorlevel = 1
 }
 finally {
@@ -781,7 +906,10 @@ finally {
     if (interactive) {
         //con.clear()
     }
+
+    // set colour zero as opaque black
 }
 
+graphics.setPalette(0, 0, 0, 0, 0)
 con.move(cy, cx) // restore cursor
 return errorlevel

assets/disk0/tvdos/bin/playucf.js

@@ -0,0 +1,358 @@
+// TSVM Universal Cue Format (UCF) Player
+// Created by CuriousTorvald and Claude on 2025-09-22
+// Usage: playucf cuefile.ucf [options]
+// Options: -i (interactive mode)
+
+if (!exec_args[1]) {
+    serial.println("Usage: playucf cuefile.ucf [options]")
+    serial.println("Options: -i (interactive mode)")
+    return 1
+}
+
+const interactive = exec_args[2] && exec_args[2].toLowerCase() == "-i"
+const fullFilePath = _G.shell.resolvePathInput(exec_args[1])
+
+if (!files.open(fullFilePath.full).exists) {
+    serial.println(`Error: File not found: ${fullFilePath.full}`)
+    return 2
+}
+
+// UCF Format constants
+const UCF_MAGIC = [0x1F, 0x54, 0x53, 0x56, 0x4D, 0x55, 0x43, 0x46] // "\x1FTSVM UCF"
+const UCF_VERSION = 1
+const ADDRESSING_EXTERNAL = 0x01
+const ADDRESSING_INTERNAL = 0x02
+
+// Media player mappings based on file extensions
+const PLAYER_MAP = {
+    'mp2': 'playmp2',
+    'wav': 'playwav',
+    'pcm': 'playpcm',
+    'mv1': 'playmv1',
+    'mv2': 'playtev',
+    'mv3': 'playtav'
+}
+
+// Helper class for UCF file reading with internal addressing support
+class UCFSequentialReader {
+    constructor(path, baseOffset = 0) {
+        this.path = path
+        this.baseOffset = baseOffset
+        this.currentOffset = 0
+
+        // Detect if this is a TAPE device path
+        if (path.startsWith("$:/TAPE") || path.startsWith("$:\\TAPE")) {
+            this.seq = require("seqreadtape")
+        } else {
+            this.seq = require("seqread")
+        }
+
+        this.seq.prepare(path)
+
+        // Skip to the base offset for internal addressing
+        if (baseOffset > 0) {
+            this.seq.skip(baseOffset)
+            this.currentOffset = baseOffset
+        }
+    }
+
+    readBytes(length) {
+        this.currentOffset += length
+        return this.seq.readBytes(length)
+    }
+
+    readOneByte() {
+        this.currentOffset += 1
+        return this.seq.readOneByte()
+    }
+
+    readShort() {
+        this.currentOffset += 2
+        return this.seq.readShort()
+    }
+
+    readString(length) {
+        this.currentOffset += length
+        return this.seq.readString(length)
+    }
+
+    skip(n) {
+        this.currentOffset += n
+        this.seq.skip(n)
+    }
+
+    // Skip to absolute position from base offset
+    seekTo(position) {
+        let targetOffset = this.baseOffset + position
+        if (targetOffset < this.currentOffset) {
+            // Need to rewind and seek forward
+            this.seq.prepare(this.path)
+            this.currentOffset = 0
+            if (targetOffset > 0) {
+                this.seq.skip(targetOffset)
+                this.currentOffset = targetOffset
+            }
+        } else if (targetOffset > this.currentOffset) {
+            // Skip forward
+            let skipAmount = targetOffset - this.currentOffset
+            this.seq.skip(skipAmount)
+            this.currentOffset = targetOffset
+        }
+    }
+
+    getPosition() {
+        return this.currentOffset - this.baseOffset
+    }
+}
+
+// Parse UCF file
+serial.println(`Playing UCF: ${fullFilePath.full}`)
+
+let reader = new UCFSequentialReader(fullFilePath.full)
+
+// Read and validate magic
+let magic = []
+for (let i = 0; i < 8; i++) {
+    magic.push(reader.readOneByte())
+}
+
+let magicValid = true
+for (let i = 0; i < 8; i++) {
+    if (magic[i] !== UCF_MAGIC[i]) {
+        magicValid = false
+        break
+    }
+}
+
+if (!magicValid) {
+    serial.println("Error: Invalid UCF magic signature")
+    return 3
+}
+
+// Read header
+let version = reader.readOneByte()
+if (version !== UCF_VERSION) {
+    serial.println(`Error: Unsupported UCF version: ${version} (expected ${UCF_VERSION})`)
+    return 4
+}
+
+let numElements = reader.readShort()
+// Skip reserved bytes (5 bytes)
+reader.skip(5)
+
+serial.println(`UCF Version: ${version}, Elements: ${numElements}`)
+
+// Parse cue elements
+let cueElements = []
+for (let i = 0; i < numElements; i++) {
+    let element = {}
+
+    element.addressingModeAndIntent = reader.readOneByte()
+    element.addressingMode = element.addressingModeAndIntent & 15
+    let nameLength = reader.readShort()
+    element.name = reader.readString(nameLength)
+
+    if (element.addressingMode === ADDRESSING_EXTERNAL) {
+        let pathLength = reader.readShort()
+        element.path = reader.readString(pathLength)
+        serial.println(`Element ${i + 1}: ${element.name} -> ${element.path} (external)`)
+    } else if (element.addressingMode === ADDRESSING_INTERNAL) {
+        // Read 48-bit offset (6 bytes, little endian)
+        let offsetBytes = []
+        for (let j = 0; j < 6; j++) {
+            offsetBytes.push(reader.readOneByte())
+        }
+
+        element.offset = 0
+        for (let j = 0; j < 6; j++) {
+            element.offset |= (offsetBytes[j] << (j * 8))
+        }
+
+        serial.println(`Element ${i + 1}: ${element.name} -> offset ${element.offset} (internal)`)
+    } else {
+        serial.println(`Error: Unknown addressing mode: ${element.addressingMode}`)
+        return 5
+    }
+
+    cueElements.push(element)
+}
+
+// Function to get file extension
+function getFileExtension(filename) {
+    let lastDot = filename.lastIndexOf('.')
+    if (lastDot === -1) return ''
+    return filename.substring(lastDot + 1).toLowerCase()
+}
+
+// Function to determine player for a file
+function getPlayerForFile(filename) {
+    let ext = getFileExtension(filename)
+    return PLAYER_MAP[ext] || null
+}
+
+// Function to create a temporary file for internal addressing
+function createTempFileForInternal(element, ucfPath) {
+    // Create a unique temporary filename
+    let tempFilename = `$:\\TMP\\temp_ucf_${Date.now()}_${element.name.replace(/[^a-zA-Z0-9]/g, '_')}`
+
+    // For internal addressing, we abuse seqread by creating a "virtual" file view
+    // We'll return a special path that our modified exec environment can handle
+    return {
+        isTemporary: true,
+        path: tempFilename,
+        ucfPath: ucfPath,
+        offset: element.offset,
+        name: element.name
+    }
+}
+
+// Play each cue element in sequence
+for (let i = 0; i < cueElements.length; i++) {
+    let element = cueElements[i]
+
+    serial.println(`\nPlaying element ${i + 1}/${numElements}: ${element.name}`)
+
+    if (interactive && i > 0) {
+        serial.print("Press ENTER to continue, 'q' to quit: ")
+        let input = serial.readLine()
+        if (input && input.toLowerCase().startsWith('q')) {
+            serial.println("Playback stopped by user")
+            break
+        }
+    }
+
+    let playerFile = null
+    let targetPath = null
+
+    if (element.addressingMode === ADDRESSING_EXTERNAL) {
+        // External addressing - resolve relative path
+        let elementPath = element.path
+        if (!elementPath.startsWith('A:\\') && !elementPath.startsWith('A:/')) {
+            // Relative path - resolve relative to UCF file location
+            let ucfDir = fullFilePath.full.substring(0, fullFilePath.full.lastIndexOf('\\'))
+            targetPath = ucfDir + '\\' + elementPath.replace(/\//g, '\\')
+        } else {
+            targetPath = elementPath
+        }
+
+        if (!files.open(targetPath).exists) {
+            serial.println(`Warning: External file not found: ${targetPath}`)
+            continue
+        }
+
+        playerFile = getPlayerForFile(element.name)
+    } else if (element.addressingMode === ADDRESSING_INTERNAL) {
+        // Internal addressing - create temporary file reference
+        let tempFile = createTempFileForInternal(element, fullFilePath.full)
+        targetPath = tempFile.path
+        playerFile = getPlayerForFile(element.name)
+
+        // For internal addressing, we need to extract the data to a temporary location
+        // or use a specialized player that can handle offset-based reading
+        // Since we can't easily create temp files, we'll modify the exec_args for the player
+
+        // Create a new UCF reader positioned at the file offset
+        let fileReader = new UCFSequentialReader(fullFilePath.full, element.offset)
+
+        // We need to somehow pass this to the player...
+        // The most elegant solution is to create a wrapper that temporarily modifies
+        // the file system view or uses a custom SequentialFileBuffer
+
+        // For now, let's use a simpler approach: save exec_args and restore them
+        let originalExecArgs = [...exec_args]
+
+        // Modify the global environment to provide the offset reader
+        let originalFilesOpen = files.open
+
+        files.open = function(path) {
+            if (path === targetPath || path.endsWith(targetPath)) {
+                // Return a mock file object that uses our offset reader
+                return {
+                    exists: true,
+                    size: 2147483648, // Arbitrary large size
+                    path: path,
+                    _ucfReader: fileReader
+                }
+            }
+            return originalFilesOpen.call(this, path)
+        }
+
+        // Also modify seqread require to use our reader
+        let originalRequire = require
+        require = function(moduleName) {
+            if (moduleName === "seqread" || moduleName === "seqreadtape") {
+                return {
+                    prepare: function(path) {
+                        if (path === targetPath || path.endsWith(targetPath)) {
+                            // Already prepared in fileReader
+                            return 0
+                        }
+                        return fileReader.seq.prepare(path)
+                    },
+                    readBytes: function(length, ptr) { return fileReader.readBytes(length, ptr) },
+                    readOneByte: function() { return fileReader.readOneByte() },
+                    readShort: function() { return fileReader.readShort() },
+                    readInt: function() { return fileReader.seq.readInt() },
+                    readFourCC: function() { return fileReader.seq.readFourCC() },
+                    readString: function(length) { return fileReader.readString(length) },
+                    skip: function(n) { return fileReader.skip(n) },
+                    getReadCount: function() { return fileReader.getPosition() },
+                    fileHeader: fileReader.seq.fileHeader
+                }
+            }
+            return originalRequire.call(this, moduleName)
+        }
+
+        try {
+            // Execute the player with modified environment
+            exec_args[1] = targetPath
+            if (playerFile) {
+                let playerPath = `A:${_TVDOS.variables.DOSDIR}/bin/${playerFile}.js`
+                if (files.open(playerPath).exists) {
+                    eval(files.readText(playerPath))
+                } else {
+                    serial.println(`Warning: Player not found: ${playerFile}`)
+                }
+            } else {
+                serial.println(`Warning: No player found for file type: ${element.name}`)
+            }
+        } catch (e) {
+            serial.println(`Error playing ${element.name}: ${e.message}`)
+        } finally {
+            // Restore original environment
+            files.open = originalFilesOpen
+            require = originalRequire
+            exec_args = originalExecArgs
+        }
+
+        continue
+    }
+
+    if (!playerFile) {
+        serial.println(`Warning: No player found for file type: ${element.name}`)
+        continue
+    }
+
+    // Execute the appropriate player
+    let playerPath = `A:${_TVDOS.variables.DOSDIR}/bin/${playerFile}.js`
+    if (!files.open(playerPath).exists) {
+        serial.println(`Warning: Player script not found: ${playerPath}`)
+        continue
+    }
+
+    // Save and modify exec_args for the player
+    let originalExecArgs = [...exec_args]
+    exec_args[1] = targetPath
+
+    try {
+        eval(files.readText(playerPath))
+    } catch (e) {
+        serial.println(`Error playing ${element.name}: ${e.message}`)
+    } finally {
+        // Restore original exec_args
+        exec_args = originalExecArgs
+    }
+}
+
+serial.println("\nUCF playback completed")
+return 0

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(decodePtr, decodedSampleLength, 0)
-                    audio.setSampleUploadLength(0, decodedSampleLength)
-                    audio.startSampleUpload(0)
-
-                    sys.spin()
-                }
-
-                audio.play(0)
-            }
-
-            let remainingBytes = FILE_SIZE - 8 - seqread.getReadCount()
-            printdbg(`readLength = ${readLength}; remainingBytes2 = ${remainingBytes}; seqread.getReadCount() = ${seqread.getReadCount()}; startOffset + chunkSize = ${startOffset + chunkSize}`)
-
-
-            sys.sleep(10)
-        }
-    }
-    else {
-        seqread.skip(chunkSize)
-    }
-
-
-    let remainingBytes = FILE_SIZE - 8 - seqread.getReadCount()
-    printdbg(`remainingBytes2 = ${remainingBytes}`)
-    sys.spin()
-}
-}
-catch (e) {
+} catch (e) {
     printerrln(e)
     errorlevel = 1
-}
-finally {
-    //audio.stop(0)
-    if (readPtr !== undefined) sys.free(readPtr)
+} finally {
+    if (readPtr   !== undefined) sys.free(readPtr)
     if (decodePtr !== undefined) sys.free(decodePtr)
+    if (interactive) gui.audioClose()
 }
 
 return errorlevel

assets/disk0/tvdos/bin/taut_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,171 @@
+if (!_G.TAUT) _G.TAUT = {};
+let help = {}
+
+let ts = require("typesetter")
+
+////////////////////////////////////////////////////////////////////////////////////////////////////
+
+/*
+Tags:
+<b> - print the text in emphasis colour (colVoiceHdr aka 230)
+<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 = '\u00B4\u00B5'.repeat((_G.TAUT.HELPMSG_WIDTH) >>> 1) + '\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/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/i18n/korean.js

@@ -1,37 +1,3 @@
-let status = 0
-let workarea = sys.malloc(1920)
-
-// install LOCHRROM
-let hangulRomL = files.open("A:/tvdos/i18n/hang_lo.chr")
-if (!hangulRomL.exists) {
-    printerrln("hang_lo.chr not found")
-    sys.free(workarea)
-    return status
-}
-//dma.comToRam(filesystem._toPorts("A")[0], 0, workarea, 1920)
-hangulRomL.pread(workarea, 1920, 0)
-for (let i = 0; i < 1920; i++) sys.poke(-1300607 - i, sys.peek(workarea + i))
-sys.poke(-1299460, 18)
-
-
-// install HICHRROM
-let hangulRomH = files.open("A:/tvdos/i18n/hang_hi.chr")
-if (!hangulRomH.exists) {
-    printerrln("hang_hi.chr not found")
-    sys.free(workarea)
-    sys.poke(-1299460, 20) // clean up the crap
-    return status
-}
-//dma.comToRam(filesystem._toPorts("A")[0], 0, workarea, 1920)
-hangulRomH.pread(workarea, 1920, 0)
-for (let i = 0; i < 1920; i++) sys.poke(-1300607 - i, sys.peek(workarea + i))
-sys.poke(-1299460, 19)
-
-
-
-sys.free(workarea)
-
-graphics.setHalfrowMode(true)
 /*
  * A character is defined as one of:
  * 1. [I,x] (Initial only)
@@ -100,7 +66,37 @@ i:{ // Cell Indices: [c0,c2]
 18:[5,0],
 19:[5,11],
 20:[0,14]
-},f:{ // Cell Indices: [c3,c5]
+},fvert:{ // Cell Indices: [c3,c5] for non-horizontal vowels (ㅏ,ㅐ,ㅑ,ㅒ and compound vowels)
+// c3,c5:[null,ㄱ,ㄴ,ㄷ,...]
+0:[0,0],
+1:[0,1],
+2:[1,1],
+3:[1,7],
+4:[0,2],
+5:[2,9],
+6:[2,14],
+7:[0,3],
+8:[0,4],
+9:[4,1],
+10:[4,5],
+11:[4,6],
+12:[4,7],
+13:[4,12],
+14:[4,13],
+15:[4,14],
+16:[0,5],
+17:[0,6],
+18:[6,7],
+19:[0,7],
+20:[7,7],
+21:[0,8],
+22:[0,9],
+23:[0,10],
+24:[0,11],
+25:[0,12],
+26:[0,13],
+27:[0,14]
+},fhorz:{ // Cell Indices: [c3,c5] for horizontal vowels (ㅗ,ㅛ,ㅜ,ㅠ,ㅡ)
 // c3,c5:[null,ㄱ,ㄴ,ㄷ,...]
 0:[0,0],
 1:[1,0],
@@ -151,7 +147,7 @@ function toLineChar(i,p,f) {
     let out = []
     let ibuf = charmap.i[i]
     let pbuf = charmap.p[p]
-    let fbuf = charmap.f[f]
+    let fbuf = ([8,12,13,17,18].includes(p)) ? charmap.fhorz[f] : charmap.fvert[f]
     let dbl = 2*(ibuf.length == 2) // 0 or 2
     /* 0 | 0 */out[0] = ibuf[0]
     /* x | 2 */out[2] = ibuf[1]
@@ -189,7 +185,9 @@ let printHangul = (char) => {
         if (i % 2 == 0)
             con.curs_down()
         else
-           cursReturn()
+            cursReturn()
+
+        //if (graphics.getCursorYX()[1] == 1) con.curs_down();
     })
 }
 
@@ -217,17 +215,18 @@ if (unicode.uniprint) {
                 let f = (c - 0xAC00) % 28
                 let char = toLineChar(i,p,f)
                 let w = Math.ceil(char.length / 2.0)|0
-                if (con.getyx()[1] + w > termw) println()
+                if (con.getyx()[1] + w > termw) print('\n\n');
                 printHangul(char)
             }
         }
     ])
 
-    println("조합한글 커널모듈이 로드되었습니다.")
-    return 0
-}
-else {
-    println("Failed to load Assembly Hangul kernel module: incompatible DOS version")
-    return 1
+    unicode.uniprint.unshift([
+        c => 0x20 == c,
+        c => {
+            if (con.getyx()[1] >= termw) print('\n\n');
+            else print(' ')
+        }
+    ])
 }
 

assets/disk0/tvdos/i18n/korean_font_upload.js

@@ -0,0 +1,30 @@
+let status = 0
+let workarea = sys.malloc(1920)
+
+// install LOCHRROM
+let hangulRomL = files.open("A:/tvdos/i18n/hang_lo.chr")
+if (!hangulRomL.exists) {
+    printerrln("hang_lo.chr not found")
+    sys.free(workarea)
+    return status
+}
+hangulRomL.pread(workarea, 1920, 0)
+for (let i = 0; i < 1920; i++) sys.poke(-133121 - i, sys.peek(workarea + i))
+sys.poke(-1299460, 18)
+
+
+// install HICHRROM
+let hangulRomH = files.open("A:/tvdos/i18n/hang_hi.chr")
+if (!hangulRomH.exists) {
+    printerrln("hang_hi.chr not found")
+    sys.free(workarea)
+    sys.poke(-1299460, 20) // clean up the crap
+    return status
+}
+hangulRomH.pread(workarea, 1920, 0)
+for (let i = 0; i < 1920; i++) sys.poke(-133121 - i, sys.peek(workarea + i))
+sys.poke(-1299460, 19)
+
+
+
+sys.free(workarea)

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

@@ -0,0 +1,305 @@
+/*
+ * getopt.js: node.js implementation of POSIX getopt() (and then some)
+ *
+ * Copyright 2011 David Pacheco. All rights reserved.
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+var ASSERT = require('assert').ok;
+
+function goError(msg)
+{
+	return (new Error('getopt: ' + msg));
+}
+
+/*
+ * The BasicParser is our primary interface to the outside world.  The
+ * documentation for this object and its public methods is contained in
+ * the included README.md.
+ */
+function goBasicParser(optstring, argv, optind)
+{
+	var ii;
+
+	ASSERT(optstring || optstring === '', 'optstring is required');
+	ASSERT(optstring.constructor === String, 'optstring must be a string');
+	ASSERT(argv, 'argv is required');
+	ASSERT(argv.constructor === Array, 'argv must be an array');
+
+	this.gop_argv = new Array(argv.length);
+	this.gop_options = {};
+	this.gop_aliases = {};
+	this.gop_optind = optind !== undefined ? optind : 2;
+	this.gop_subind = 0;
+
+	for (ii = 0; ii < argv.length; ii++) {
+		ASSERT(argv[ii].constructor === String,
+		    'argv must be string array');
+		this.gop_argv[ii] = argv[ii];
+	}
+
+	this.parseOptstr(optstring);
+}
+
+exports.BasicParser = goBasicParser;
+
+/*
+ * Parse the option string and update the following fields:
+ *
+ *	gop_silent	Whether to log errors to stderr.  Silent mode is
+ *			indicated by a leading ':' in the option string.
+ *
+ *	gop_options	Maps valid single-letter-options to booleans indicating
+ *			whether each option is required.
+ *
+ *	gop_aliases	Maps valid long options to the corresponding
+ *			single-letter short option.
+ */
+goBasicParser.prototype.parseOptstr = function (optstr)
+{
+	var chr, cp, alias, arg, ii;
+
+	ii = 0;
+	if (optstr.length > 0 && optstr[0] == ':') {
+		this.gop_silent = true;
+		ii++;
+	} else {
+		this.gop_silent = false;
+	}
+
+	while (ii < optstr.length) {
+		chr = optstr[ii];
+		arg = false;
+
+		if (!/^[\w\d\u1000-\u1100]$/.test(chr))
+			throw (goError('invalid optstring: only alphanumeric ' +
+			    'characters and unicode characters between ' +
+			    '\\u1000-\\u1100 may be used as options: ' + chr));
+
+		if (ii + 1 < optstr.length && optstr[ii + 1] == ':') {
+			arg = true;
+			ii++;
+		}
+
+		this.gop_options[chr] = arg;
+
+		while (ii + 1 < optstr.length && optstr[ii + 1] == '(') {
+			ii++;
+			cp = optstr.indexOf(')', ii + 1);
+			if (cp == -1)
+				throw (goError('invalid optstring: missing ' +
+				    '")" to match "(" at char ' + ii));
+
+			alias = optstr.substring(ii + 1, cp);
+			this.gop_aliases[alias] = chr;
+			ii = cp;
+		}
+
+		ii++;
+	}
+};
+
+goBasicParser.prototype.optind = function ()
+{
+	return (this.gop_optind);
+};
+
+/*
+ * For documentation on what getopt() does, see README.md.  The following
+ * implementation invariants are maintained by getopt() and its helper methods:
+ *
+ *	this.gop_optind		Refers to the element of gop_argv that contains
+ *				the next argument to be processed.  This may
+ *				exceed gop_argv, in which case the end of input
+ *				has been reached.
+ *
+ *	this.gop_subind		Refers to the character inside
+ *				this.gop_options[this.gop_optind] which begins
+ *				the next option to be processed.  This may never
+ *				exceed the length of gop_argv[gop_optind], so
+ *				when incrementing this value we must always
+ *				check if we should instead increment optind and
+ *				reset subind to 0.
+ *
+ * That is, when any of these functions is entered, the above indices' values
+ * are as described above.  getopt() itself and getoptArgument() may both be
+ * called at the end of the input, so they check whether optind exceeds
+ * argv.length.  getoptShort() and getoptLong() are called only when the indices
+ * already point to a valid short or long option, respectively.
+ *
+ * getopt() processes the next option as follows:
+ *
+ *	o If gop_optind > gop_argv.length, then we already parsed all arguments.
+ *
+ *	o If gop_subind == 0, then we're looking at the start of an argument:
+ *
+ *	    o Check for special cases like '-', '--', and non-option arguments.
+ *	      If present, update the indices and return the appropriate value.
+ *
+ *	    o Check for a long-form option (beginning with '--').  If present,
+ *	      delegate to getoptLong() and return the result.
+ *
+ *	    o Otherwise, advance subind past the argument's leading '-' and
+ *	      continue as though gop_subind != 0 (since that's now the case).
+ *
+ *	o Delegate to getoptShort() and return the result.
+ */
+goBasicParser.prototype.getopt = function ()
+{
+	if (this.gop_optind >= this.gop_argv.length)
+		/* end of input */
+		return (undefined);
+
+	var arg = this.gop_argv[this.gop_optind];
+
+	if (this.gop_subind === 0) {
+		if (arg == '-' || arg === '' || arg[0] != '-')
+			return (undefined);
+
+		if (arg == '--') {
+			this.gop_optind++;
+			this.gop_subind = 0;
+			return (undefined);
+		}
+
+		if (arg[1] == '-')
+			return (this.getoptLong());
+
+		this.gop_subind++;
+		ASSERT(this.gop_subind < arg.length);
+	}
+
+	return (this.getoptShort());
+};
+
+/*
+ * Implements getopt() for the case where optind/subind point to a short option.
+ */
+goBasicParser.prototype.getoptShort = function ()
+{
+	var arg, chr;
+
+	ASSERT(this.gop_optind < this.gop_argv.length);
+	arg = this.gop_argv[this.gop_optind];
+	ASSERT(this.gop_subind < arg.length);
+	chr = arg[this.gop_subind];
+
+	if (++this.gop_subind >= arg.length) {
+		this.gop_optind++;
+		this.gop_subind = 0;
+	}
+
+	if (!(chr in this.gop_options))
+		return (this.errInvalidOption(chr));
+
+	if (!this.gop_options[chr])
+		return ({ option: chr });
+
+	return (this.getoptArgument(chr));
+};
+
+/*
+ * Implements getopt() for the case where optind/subind point to a long option.
+ */
+goBasicParser.prototype.getoptLong = function ()
+{
+	var arg, alias, chr, eq;
+
+	ASSERT(this.gop_subind === 0);
+	ASSERT(this.gop_optind < this.gop_argv.length);
+	arg = this.gop_argv[this.gop_optind];
+	ASSERT(arg.length > 2 && arg[0] == '-' && arg[1] == '-');
+
+	eq = arg.indexOf('=');
+	alias = arg.substring(2, eq == -1 ? arg.length : eq);
+	if (!(alias in this.gop_aliases))
+		return (this.errInvalidOption(alias));
+
+	chr = this.gop_aliases[alias];
+	ASSERT(chr in this.gop_options);
+
+	if (!this.gop_options[chr]) {
+		if (eq != -1)
+			return (this.errExtraArg(alias));
+
+		this.gop_optind++; /* eat this argument */
+		return ({ option: chr });
+	}
+
+	/*
+	 * Advance optind/subind for the argument value and retrieve it.
+	 */
+	if (eq == -1)
+		this.gop_optind++;
+	else
+		this.gop_subind = eq + 1;
+
+	return (this.getoptArgument(chr));
+};
+
+/*
+ * For the given option letter 'chr' that takes an argument, assumes that
+ * optind/subind point to the argument (or denote the end of input) and return
+ * the appropriate getopt() return value for this option and argument (or return
+ * the appropriate error).
+ */
+goBasicParser.prototype.getoptArgument = function (chr)
+{
+	var arg;
+
+	if (this.gop_optind >= this.gop_argv.length)
+		return (this.errMissingArg(chr));
+
+	arg = this.gop_argv[this.gop_optind].substring(this.gop_subind);
+	this.gop_optind++;
+	this.gop_subind = 0;
+	return ({ option: chr, optarg: arg });
+};
+
+goBasicParser.prototype.errMissingArg = function (chr)
+{
+	if (this.gop_silent)
+		return ({ option: ':', optopt: chr });
+
+	process.stderr.write('option requires an argument -- ' + chr + '\n');
+	return ({ option: '?', optopt: chr, error: true });
+};
+
+goBasicParser.prototype.errInvalidOption = function (chr)
+{
+	if (!this.gop_silent)
+		process.stderr.write('illegal option -- ' + chr + '\n');
+
+	return ({ option: '?', optopt: chr, error: true });
+};
+
+/*
+ * This error is not specified by POSIX, but neither is the notion of specifying
+ * long option arguments using "=" in the same argv-argument, but it's common
+ * practice and pretty convenient.
+ */
+goBasicParser.prototype.errExtraArg = function (chr)
+{
+	if (!this.gop_silent)
+		process.stderr.write('option expects no argument -- ' +
+		    chr + '\n');
+
+	return ({ option: '?', optopt: chr, error: true });
+};

assets/disk0/tvdos/include/gl.mjs

@@ -1,7 +1,7 @@
-/*
-TVDOS Graphics Library
-
-Has no affiliation with OpenGL by Khronos Group
+/**
+ * LibGL — TVDOS Graphics Library
+ * Has no affiliation with OpenGL by Khronos Group
+ * @author CuriousTorvald
  */
 
 
@@ -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/pcm.mjs

@@ -1,3 +1,8 @@
+/**
+ * LibPCM — PCM decoder for TSVM
+ * @author CuriousTorvald
+ */
+
 const HW_SAMPLING_RATE = 32000
 function printdbg(s) { if (0) serial.println(s) }
 function printvis(s) { if (0) println(s) }
@@ -29,7 +34,7 @@ function s16Tou8(i) {
 }
 function u16Tos16(i) { return (i > 32767) ? i - 65536 : i }
 function randomRound(k) {
-    let rnd = (Math.random() + Math.random()) / 2.0 // this produces triangular distribution
+    let rnd = Math.random() // note to self: no triangular here
     return (rnd < (k - (k|0))) ? Math.ceil(k) : Math.floor(k)
 }
 function lerp(start, end, x) {

assets/disk0/tvdos/include/psg.mjs

@@ -0,0 +1,414 @@
+/**
+ * LibPSG — PSG emulator and mixer for TSVM
+ * Software-mixes various PSG channels and sends them to sound device as PCM
+ * @author CuriousTorvald
+ */
+
+const HW_SAMPLING_RATE = 32000
+
+function clamp(val, low, hi) { return (val < low) ? low : (val > hi) ? hi : val }
+function clampS16(i) { return clamp(i, -32768, 32767) }
+const uNybToSnyb = [0,1,2,3,4,5,6,7,-8,-7,-6,-5,-4,-3,-2,-1]
+// returns: [unsigned high, unsigned low, signed high, signed low]
+function getNybbles(b) { return [b >> 4, b & 15, uNybToSnyb[b >> 4], uNybToSnyb[b & 15]] }
+function s8Tou8(i) { return i + 128 }
+function s16Tou8(i) {
+//    return s8Tou8((i >> 8) & 255)
+    // apply dithering
+    let ufval = (i / 65536.0) + 0.5
+    let ival = randomRound(ufval * 255.0)
+    return ival|0
+}
+function u16Tos16(i) { return (i > 32767) ? i - 65536 : i }
+function randomRound(k) {
+    let rnd = Math.random() // note to self: no triangular here
+    return (rnd < (k - (k|0))) ? Math.ceil(k) : Math.floor(k)
+}
+function lerp(start, end, x) {
+    return (1 - x) * start + x * end
+}
+function lerpAndRound(start, end, x) {
+    return Math.round(lerp(start, end, x))
+}
+
+
+
+// output format: immediately uploadable into TSVM audio adapter
+
+// ── Internal helpers ────────────────────────────────────────────────────────
+
+function secToSamples(sec) { return Math.round(HW_SAMPLING_RATE * sec) }
+
+function isNative(buf) { return buf.native }
+
+function readU8(buf, ch, i) {
+    return isNative(buf) ? (sys.peek(buf[ch] + i) & 255) : buf[ch][i]
+}
+function writeU8(buf, ch, i, v) {
+    if (isNative(buf)) sys.poke(buf[ch] + i, v)
+    else buf[ch][i] = v
+}
+
+// ── Buffer management ───────────────────────────────────────────────────────
+
+function makeBuffer(length) {
+    // returns [Uint8Array, Uint8Array] (stereo) that will be used to collect samples made by LibPSG.
+    // Length: seconds. Number of elements: round(HW_SAMPLING_RATE * length)
+    const n = secToSamples(length)
+    const L = new Uint8Array(n)
+    const R = new Uint8Array(n)
+    L.fill(128)
+    R.fill(128)
+    return { 0: L, 1: R, samples: n, native: false }
+}
+
+function makeBufferNative(length) {
+    // returns native buffer object (stereo) that will be used to collect samples made by LibPSG.
+    // Length: seconds. Number of elements: round(HW_SAMPLING_RATE * length)
+    // Free with freeBufferNative() when done.
+    const n = secToSamples(length)
+    const L = sys.malloc(n); sys.memset(L, 128, n)
+    const R = sys.malloc(n); sys.memset(R, 128, n)
+    return { 0: L, 1: R, samples: n, native: true }
+}
+
+function freeBufferNative(buf) {
+    sys.free(buf[0])
+    sys.free(buf[1])
+}
+
+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)
+    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)
+    }
+}
+
+// ── Shared mix core ─────────────────────────────────────────────────────────
+
+// sampleFn(i) must return a float in [-1, 1].
+// Mixing maths: decode u8 → s16, apply op, clamp, dither back to u8.
+function mixInto(buf, lengthSec, offsetSec, op, amp, pan, sampleFn) {
+    const startIdx = secToSamples(offsetSec)
+    const n = secToSamples(lengthSec)
+    // Linear pan law: centre (pan=0) → both channels at full amp
+    const gainL = Math.max(0, Math.min(1, 1.0 - pan))
+    const gainR = Math.max(0, Math.min(1, 1.0 + pan))
+    const opCode = (op === 'sub') ? 1 : (op === 'mul') ? 2 : 0  // default: add
+    for (let i = 0; i < n; i++) {
+        const v = sampleFn(i)           // oscillator value in [-1, 1]
+        const oscBase = v * amp * 32767
+        const oscL = Math.round(oscBase * gainL) | 0
+        const oscR = Math.round(oscBase * gainR) | 0
+        for (let ch = 0; ch < 2; ch++) {
+            const osc = (ch === 0) ? oscL : oscR
+            const cur = (readU8(buf, ch, startIdx + i) - 128) << 8
+            let out
+            switch (opCode) {
+                case 0: out = cur + osc; break
+                case 1: out = cur - osc; break
+                case 2: out = (cur * osc) >> 15; break
+            }
+            writeU8(buf, ch, startIdx + i, s16Tou8(clampS16(out)))
+        }
+    }
+}
+
+// ── Waveform generators ─────────────────────────────────────────────────────
+
+function makeSquare(buf, length, offset, freq, duty, op, amp, pan, phaseOffset) {
+    // buffer: [Uint8Array, Uint8Array] or native buffer
+    // length: in seconds
+    // offset: in seconds
+    // duty: 0.0 to 1.0. default 0.5 (fraction of period where output is +1)
+    // freq: Hz
+    // 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,
+    //              not to the buffer write position — use to ensure phase continuity
+    //              across successive calls (e.g. frame boundaries).
+    if (duty == null) duty = 0.5
+    if (op   == null) op   = 'add'
+    if (amp  == null) amp  = 0.5
+    if (pan  == null) pan  = 0.0
+    const tBase = (phaseOffset || 0) + offset
+    mixInto(buf, length, offset, op, amp, pan, function(i) {
+        const phase = ((tBase + i / HW_SAMPLING_RATE) * freq) % 1
+        return (phase < duty) ? 1.0 : -1.0
+    })
+}
+
+function makeTriangle(buf, length, offset, freq, duty, op, amp, pan, phaseOffset) {
+    // buffer: [Uint8Array, Uint8Array] or native buffer
+    // length: in seconds
+    // offset: in seconds
+    // duty: skew. -1.0 = falling sawtooth, 0.0 = symmetric triangle, 1.0 = rising sawtooth
+    // freq: Hz
+    // 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
+    // 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 phase = ((tBase + i / HW_SAMPLING_RATE) * freq) % 1
+        if (riseFrac <= 0) {
+            return 1.0 - 2.0 * phase                               // falling saw
+        } else if (riseFrac >= 1) {
+            return -1.0 + 2.0 * phase                              // rising saw
+        } else if (phase < riseFrac) {
+            return -1.0 + 2.0 * (phase / riseFrac)                 // rising slope
+        } else {
+            return 1.0 - 2.0 * ((phase - riseFrac) / (1.0 - riseFrac)) // falling slope
+        }
+    })
+}
+
+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.
+    // length: in seconds
+    // offset: in seconds
+    // duty: skew. -1.0 = falling sawtooth, 0.0 = symmetric triangle, 1.0 = rising sawtooth
+    // freq: Hz
+    // 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 phase = ((tBase + i / HW_SAMPLING_RATE) * freq) % 1
+        let v
+        if (riseFrac <= 0) {
+            v = 1.0 - 2.0 * phase
+        } else if (riseFrac >= 1) {
+            v = -1.0 + 2.0 * phase
+        } else if (phase < riseFrac) {
+            v = -1.0 + 2.0 * (phase / riseFrac)
+        } else {
+            v = 1.0 - 2.0 * ((phase - riseFrac) / (1.0 - riseFrac))
+        }
+        // Quantise to 16 levels (NES triangle 4-bit DAC: 0..15 → -1..+1)
+        const level = Math.max(0, Math.min(15, Math.round((v + 1.0) * 7.5)))
+        return level / 7.5 - 1.0
+    })
+}
+
+// ── LFSR helpers (for noise types 1 and 2) ─────────────────────────────────
+
+function lfsrStep(state, mode) {
+    // mode 0 (long/NES mode 0): feedback tap at bit 1; period 32767
+    // mode 1 (short/NES mode 1): feedback tap at bit 6; period 93 (metallic/tonal)
+    const bit0   = state & 1
+    const bitTap = (mode === 0) ? (state >> 1) & 1 : (state >> 6) & 1
+    const feed   = bit0 ^ bitTap
+    return ((feed << 14) | (state >> 1)) & 0x7FFF
+}
+
+function lfsrAdvance(state, steps, mode) {
+    for (let k = 0; k < steps; k++) state = lfsrStep(state, mode)
+    return state
+}
+
+// NES APU documented LFSR periods
+const LFSR_PERIOD_LONG  = 32767  // mode 0
+const LFSR_PERIOD_SHORT = 93     // mode 1
+
+function makeNoise(buf, length, offset, freq, type, op, amp, pan, phaseOffset) {
+    // buffer: [Uint8Array, Uint8Array] or native buffer
+    // length: in seconds
+    // offset: in seconds
+    // type:
+    //   -1: 8-bit white noise (random float per period, sample-and-hold)
+    //    0: 1-bit white noise (random ±1 per period, sample-and-hold)
+    //    1: 1-bit LFSR long mode  — NES mode 0, tap=bit0^bit1, period 32767 (full-spectrum)
+    //    2: 1-bit LFSR short mode — NES mode 1, tap=bit0^bit6, period 93 (metallic/tonal)
+    // freq: Hz (clock rate of the noise generator)
+    // 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/LFSR calc only —
+    //              see makeSquare for details.
+    //
+    // LFSR types (1 and 2) are deterministic given (phaseOffset+offset, freq): calling
+    // with monotonically advancing phaseOffset+offset produces a seamless noise stream
+    // across frames. White noise types (-1, 0) are random per call.
+    if (op  == null) op  = 'add'
+    if (amp == null) amp = 0.5
+    if (pan == null) pan = 0.0
+    const tBase = (phaseOffset || 0) + offset
+
+    if (type === -1) {
+        // 8-bit white: new random float in [-1, 1] each clock period
+        let prevClock = -1
+        let noiseVal = 0.0
+        mixInto(buf, length, offset, op, amp, pan, function(i) {
+            const currentClock = Math.floor((tBase + i / HW_SAMPLING_RATE) * freq) | 0
+            if (currentClock !== prevClock) {
+                prevClock = currentClock
+                noiseVal = Math.random() * 2.0 - 1.0
+            }
+            return noiseVal
+        })
+    } else if (type === 0) {
+        // 1-bit white: random ±1 each clock period
+        let prevClock = -1
+        let noiseVal = 1.0
+        mixInto(buf, length, offset, op, amp, pan, function(i) {
+            const currentClock = Math.floor((tBase + i / HW_SAMPLING_RATE) * freq) | 0
+            if (currentClock !== prevClock) {
+                prevClock = currentClock
+                noiseVal = (Math.random() >= 0.5) ? 1.0 : -1.0
+            }
+            return noiseVal
+        })
+    } else {
+        // LFSR-based noise (types 1 and 2)
+        const mode   = (type === 2) ? 1 : 0
+        const period = (mode === 0) ? LFSR_PERIOD_LONG : LFSR_PERIOD_SHORT
+        // Advance to deterministic position for this tBase so consecutive frame
+        // calls with monotonically advancing phaseOffset produce a seamless noise stream.
+        const startClock = Math.floor(tBase * freq) | 0
+        let lfsr      = lfsrAdvance(1, startClock % period, mode)
+        let prevClock = startClock
+        mixInto(buf, length, offset, op, amp, pan, function(i) {
+            const currentClock = Math.floor((tBase + i / HW_SAMPLING_RATE) * freq) | 0
+            const delta = currentClock - prevClock
+            if (delta > 0) {
+                const steps = delta % period
+                if (steps > 0) lfsr = lfsrAdvance(lfsr, steps, mode)
+                prevClock = currentClock
+            }
+            return (lfsr & 1) ? 1.0 : -1.0
+        })
+    }
+}
+
+function makeAliasedTriangleNES(buf, length, offset, freq, duty, op, amp, pan, phaseOffset) {
+    // NES APU triangle — quantised to the authentic 32-step, 4-bit (0..15) staircase.
+    // The 32-step sequence is: 15,14,...,1,0, 0,1,...,14,15 (descending then ascending).
+    // This mirrors the real NES triangle DAC which has 32 equal-height steps per period.
+    // duty parameter is accepted for API symmetry but ignored (NES triangle is always symmetric).
+    // phaseOffset: optional absolute-time base (seconds) — see makeSquare for details.
+    if (op  == null) op  = 'add'
+    if (amp == null) amp = 0.5
+    if (pan == null) pan = 0.0
+    const tBase = (phaseOffset || 0) + offset
+    mixInto(buf, length, offset, op, amp, pan, function(i) {
+        const phase = ((tBase + i / HW_SAMPLING_RATE) * freq) % 1
+        const step32 = Math.floor(phase * 32) | 0  // 0..31
+        // step 0..15: descend from 15 to 0; step 16..31: ascend from 0 to 15
+        const level = (step32 < 16) ? (15 - step32) : (step32 - 16)
+        return level / 7.5 - 1.0  // map 0..15 → -1..+1
+    })
+}
+
+// ── Send to audio hardware ──────────────────────────────────────────────────
+
+function sendBuffer(buf, playhead, offsetSec, lengthSec, stagingPtr) {
+    // Interleaves the L and R channels into a staging region (LRLRLR…) and uploads
+    // to the audio adapter pcmBin via the standard putPcmDataByPtr pipeline.
+    //
+    // offsetSec:  start of region to send (default: 0)
+    // lengthSec:  duration to send (default: entire buffer from offsetSec)
+    // stagingPtr: optional caller-owned native buffer (≥ min(chunk, 32768) * 2 bytes).
+    //             Pass a pre-allocated pointer to avoid malloc/free per call —
+    //             useful for the per-frame tvnes pattern.
+    //
+    // The function auto-chunks at 32768 stereo samples (pcmBin capacity).
+    // Blocks briefly if the audio queue is saturated (queue depth > 2).
+    const start = (offsetSec != null) ? secToSamples(offsetSec) : 0
+    const total = (lengthSec != null) ? secToSamples(lengthSec) : (buf.samples - start)
+    const MAX_CHUNK = 32768  // pcmBin = 65536 bytes; stereo → max 32768 samples per upload
+    const ownsStaging = (stagingPtr == null)
+    if (ownsStaging) stagingPtr = sys.malloc(Math.min(total, MAX_CHUNK) * 2)
+
+    let remaining = total
+    let cursor    = start
+    while (remaining > 0) {
+        const take = Math.min(remaining, MAX_CHUNK)
+        // Interleave L, R into staging buffer
+        for (let i = 0; i < take; i++) {
+            sys.poke(stagingPtr + 2 * i,     readU8(buf, 0, cursor + i))
+            sys.poke(stagingPtr + 2 * i + 1, readU8(buf, 1, cursor + i))
+        }
+        // Wait for room in the playback queue (mirrors playwav.js idiom)
+        // while (audio.getPosition(playhead) > 2) sys.sleep(2)
+        audio.putPcmDataByPtr(playhead, stagingPtr, take * 2, 0)
+        audio.setSampleUploadLength(playhead, take * 2)
+        audio.startSampleUpload(playhead)
+        remaining -= take
+        cursor    += take
+    }
+
+    if (ownsStaging) sys.free(stagingPtr)
+}
+
+// Lazily-allocated JS-side interleave scratch; shared across sendBufferFast calls.
+let _sendFastScratch = null
+
+function sendBufferFast(buf, playhead, offsetSec, lengthSec, stagingPtr) {
+    // Like sendBuffer but interleaves L/R via a JS Uint8Array + one sys.pokeBytes per chunk,
+    // instead of ~2n sys.poke calls.  Requires a non-native (JS-backed) buffer.
+    // Falls back to sendBuffer for native buffers.
+    if (isNative(buf)) { sendBuffer(buf, playhead, offsetSec, lengthSec, stagingPtr); return }
+
+    const start = (offsetSec != null) ? secToSamples(offsetSec) : 0
+    const total = (lengthSec != null) ? secToSamples(lengthSec) : (buf.samples - start)
+    const MAX_CHUNK = 32768
+    const ownsStaging = (stagingPtr == null)
+    if (ownsStaging) stagingPtr = sys.malloc(Math.min(total, MAX_CHUNK) * 2)
+
+    const scratchNeeded = Math.min(total, MAX_CHUNK) * 2
+    if (_sendFastScratch == null || _sendFastScratch.length < scratchNeeded) {
+        _sendFastScratch = new Uint8Array(scratchNeeded)
+    }
+
+    let remaining = total
+    let cursor    = start
+    while (remaining > 0) {
+        const take = Math.min(remaining, MAX_CHUNK)
+        const L = buf[0], R = buf[1], sc = _sendFastScratch
+        for (let i = 0; i < take; i++) {
+            sc[2 * i]     = L[cursor + i]
+            sc[2 * i + 1] = R[cursor + i]
+        }
+        sys.pokeBytes(stagingPtr, sc.subarray(0, take * 2), take * 2)
+        // while (audio.getPosition(playhead) > 2) sys.sleep(2)
+        audio.putPcmDataByPtr(playhead, stagingPtr, take * 2, 0)
+        audio.setSampleUploadLength(playhead, take * 2)
+        audio.startSampleUpload(playhead)
+        remaining -= take
+        cursor    += take
+    }
+
+    if (ownsStaging) sys.free(stagingPtr)
+}
+
+exports = {
+    HW_SAMPLING_RATE,
+    makeBuffer, makeBufferNative, freeBufferNative, clearBuffer,
+    makeSquare, makeTriangle, makeAliasedTriangle, makeAliasedTriangleNES, makeNoise,
+    sendBuffer, sendBufferFast
+}