c64bridge 1.0.4 → 1.0.5

package/dist/device.js

@@ -10,9 +10,7 @@ import { createLoggingHttpClient } from "./loggingHttpClient.js";
 import { ViceClient } from "./vice/viceClient.js";
 import { waitForBasicReady } from "./vice/readiness.js";
 import { startViceProcess } from "./vice/process.js";
-import { loadConfig } from "./config.js";
-const DEFAULT_C64U_HOST = "c64u";
-const DEFAULT_C64U_PORT = 80;
+import { loadConfig, resolveUltimateEndpoint } from "./config.js";
 const DEFAULT_VICE_HOST = "127.0.0.1";
 const DEFAULT_VICE_PORT = 6502;
 function delay(ms) {
@@ -52,28 +50,44 @@ function coalesceMemoryWriteBlocks(blocks) {
     }
     return merged;
 }
+/** All C64U/U2 endpoints come from loadConfig(), so the MCP server and every
+ * backend agree on host, port and password. */
 function readConfigFile() {
-    const sections = loadConfig().backendConfig;
-    return Object.keys(sections).length === 0 ? null : {
-        c64u: sections.c64u,
-        u2: sections.u2,
+    const config = loadConfig();
+    const sections = config.backendConfig;
+    return {
+        c64u: sections.c64u || config.legacyUltimateEndpoint ? config.ultimate.c64u : undefined,
+        u2: sections.u2 ? config.ultimate.u2 : undefined,
         vice: sections.vice,
+        endpoints: config.ultimate,
     };
 }
+/** Firmware drive ids (route_drives.h DriveToSubsys, matched case-insensitively). */
+const FIRMWARE_DRIVE_IDS = new Set(["a", "b", "softiec"]);
+/** GET /v1/drives reports the soft IEC drive under this name; the drive routes call it softiec. */
+const SOFT_IEC_LISTING_ID = "iec drive";
+/** Factory bus numbers of drives a and b, used when the drive listing is unavailable. */
+const DEFAULT_DRIVE_BY_BUS_ID = { 8: "a", 9: "b" };
+/** The firmware reports a mounted image as directory (image_path) plus file name (image_file). */
+function driveImage(info) {
+    const file = typeof info.image_file === "string" ? info.image_file : "";
+    const dir = typeof info.image_path === "string" ? info.image_path : "";
+    if (file)
+        return dir ? `${dir.replace(/\/+$/, "")}/${file}` : file;
+    if (dir)
+        return dir;
+    return typeof info.image === "string" && info.image ? info.image : null;
+}
+function uploadFile(bytes, name) {
+    return new File([Uint8Array.from(bytes)], name, { type: "application/octet-stream" });
+}
 class C64uBackend {
-    constructor(config, type = "c64u") {
+    constructor(endpoint, type = "c64u") {
         this.type = type;
-        const envHost = configuredString(type === "u2" ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST);
-        const envPort = configuredPort(type === "u2" ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT);
-        const configBaseUrl = normaliseBaseUrl(config.baseUrl);
-        const parsedConfigBaseUrl = configBaseUrl ? parseEndpoint(configBaseUrl) : {};
-        const baseUrl = envHost !== undefined || envPort !== undefined
-            ? buildBaseUrl(firstDefined(envHost, configuredString(config.host), configuredString(config.hostname), parsedConfigBaseUrl.hostname) ?? DEFAULT_C64U_HOST, firstDefined(envPort, configuredPort(config.port), parsedConfigBaseUrl.port) ?? DEFAULT_C64U_PORT)
-            : resolveBaseUrl(config);
-        this.baseUrl = baseUrl;
-        this.networkPassword = firstDefined(configuredString(type === "u2" ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD), configuredString(config.networkPassword));
+        this.baseUrl = endpoint.baseUrl;
+        this.networkPassword = endpoint.networkPassword;
         const http = createLoggingHttpClient({
-            baseURL: baseUrl,
+            baseURL: this.baseUrl,
             timeout: 10000,
             headers: buildC64uHeaders(this.networkPassword),
         });
@@ -132,10 +146,15 @@ class C64uBackend {
         return this.actionResult(res.data);
     }
     async sidplayAttachment(sid, options) {
-        const form = { sid: Buffer.isBuffer(sid) ? sid : Buffer.from(sid) };
+        // The generated multipart builder JSON-encodes anything that is not a Blob,
+        // so the bytes must be File parts. The firmware ignores part names and
+        // takes the first file as the SID and the second as song lengths; the spec
+        // names both `file`. The temp file keeps the upload name, and its extension
+        // selects SID versus MUS playback.
+        const file = [uploadFile(sid, "upload.sid")];
         if (options?.songlengths)
-            form.songlengths = Buffer.isBuffer(options.songlengths) ? options.songlengths : Buffer.from(options.songlengths);
-        const res = await this.api.v1.runnersSidplayCreate(":sidplay", form, options?.songnr !== undefined ? { songnr: options.songnr } : undefined);
+            file.push(uploadFile(options.songlengths, "upload.ssl"));
+        const res = await this.api.v1.runnersSidplayCreate(":sidplay", { file }, options?.songnr !== undefined ? { songnr: options.songnr } : undefined);
         return this.actionResult(res.data);
     }
     async readMemory(address, length) {
@@ -196,32 +215,75 @@ class C64uBackend {
     async debugregWrite(value) { this.requireC64u("debugregWrite"); const res = await this.api.v1.machineDebugregUpdate(":debugreg", { value }); return { success: true, value: res.data.value, details: res.data }; }
     async version() { const res = await this.api.v1.versionList(); return res.data; }
     async info() { const res = await this.api.v1.infoList(); return res.data; }
-    async drivesList() {
+    async driveEntries() {
         const res = await this.api.v1.drivesList();
         const raw = res.data;
         const entries = Array.isArray(raw.drives)
             ? raw.drives
             : raw.drives && typeof raw.drives === "object" ? [raw.drives] : [];
-        return entries.flatMap((entry) => Object.entries(entry).map(([id, info]) => ({
+        return entries.flatMap((entry) => Object.entries(entry));
+    }
+    /**
+     * Map a drive id to the firmware's `a`, `b` or `softiec`. Bus numbers such
+     * as `drive8` or `8` are looked up by `bus_id` among drives a and b in
+     * GET /v1/drives, because a drive letter's bus number is configurable; the
+     * factory a=8, b=9 applies only when the listing is unavailable. The soft
+     * IEC drive is reachable only by name, never by bus number.
+     */
+    async resolveDriveId(drive) {
+        const lower = drive.trim().toLowerCase();
+        if (FIRMWARE_DRIVE_IDS.has(lower))
+            return lower;
+        if (lower === SOFT_IEC_LISTING_ID)
+            return "softiec";
+        const match = /^(?:drive)?\s*(\d+)$/.exec(lower);
+        if (!match)
+            return drive;
+        const busId = Number(match[1]);
+        let listed = [];
+        try {
+            listed = (await this.driveEntries()).flatMap(([id, info]) => {
+                const listedBusId = Number(info?.bus_id);
+                return (id === "a" || id === "b") && Number.isInteger(listedBusId) ? [{ id, busId: listedBusId, enabled: info?.enabled !== false }] : [];
+            });
+        }
+        catch {
+            listed = [];
+        }
+        // A disabled drive keeps its bus_id setting, so prefer the enabled drive the C64 actually sees on that bus.
+        const onBus = listed.filter((entry) => entry.busId === busId);
+        const resolved = listed.length > 0 ? (onBus.find((entry) => entry.enabled) ?? onBus[0])?.id : DEFAULT_DRIVE_BY_BUS_ID[busId];
+        if (!resolved) {
+            const known = listed.length > 0 ? listed.map((entry) => `${entry.id}=${entry.busId}`).join(", ") : "a=8, b=9";
+            throw new Error(`No drive found for '${drive}' (bus IDs: ${known})`);
+        }
+        return resolved;
+    }
+    async drivesList() {
+        const entries = await this.driveEntries();
+        return entries.map(([id, info]) => ({
             id,
             power: info.enabled === true || info.enabled === "on" || info.power === "on" ? "on" : "off",
-            image: (info.image_path ?? info.image_file ?? info.image ?? null),
+            image: driveImage(info),
             type: info.type ?? null,
             raw: info,
-        })));
+        }));
     }
-    async driveMount(d, img, options) { const res = await this.api.v1.drivesMountUpdate(d, ":mount", { image: img, type: options?.type, mode: options?.mode }); return this.actionResult(res.data); }
-    async driveRemove(d) { const res = await this.api.v1.drivesRemoveUpdate(d, ":remove"); return this.actionResult(res.data); }
-    async driveReset(d) { const res = await this.api.v1.drivesResetUpdate(d, ":reset"); return this.actionResult(res.data); }
-    async driveOn(d) { const res = await this.api.v1.drivesOnUpdate(d, ":on"); return this.actionResult(res.data); }
-    async driveOff(d) { const res = await this.api.v1.drivesOffUpdate(d, ":off"); return this.actionResult(res.data); }
-    async driveSetMode(d, mode) { const res = await this.api.v1.drivesSetModeUpdate(d, ":set_mode", { mode }); return this.actionResult(res.data); }
-    async driveLoadRom(d, romPath) { const res = await this.api.v1.drivesLoadRomUpdate(d, ":load_rom", { file: romPath }); return this.actionResult(res.data); }
+    async driveMount(d, img, options) { const res = await this.api.v1.drivesMountUpdate(await this.resolveDriveId(d), ":mount", { image: img, type: options?.type, mode: options?.mode }); return this.actionResult(res.data); }
+    async driveRemove(d) { const res = await this.api.v1.drivesRemoveUpdate(await this.resolveDriveId(d), ":remove"); return this.actionResult(res.data); }
+    async driveReset(d) { const res = await this.api.v1.drivesResetUpdate(await this.resolveDriveId(d), ":reset"); return this.actionResult(res.data); }
+    async driveOn(d) { const res = await this.api.v1.drivesOnUpdate(await this.resolveDriveId(d), ":on"); return this.actionResult(res.data); }
+    async driveOff(d) { const res = await this.api.v1.drivesOffUpdate(await this.resolveDriveId(d), ":off"); return this.actionResult(res.data); }
+    async driveSetMode(d, mode) { const res = await this.api.v1.drivesSetModeUpdate(await this.resolveDriveId(d), ":set_mode", { mode }); return this.actionResult(res.data); }
+    async driveLoadRom(d, romPath) { const res = await this.api.v1.drivesLoadRomUpdate(await this.resolveDriveId(d), ":load_rom", { file: romPath }); return this.actionResult(res.data); }
     async streamStart(s, ip) { this.requireC64u("streamStart"); const res = await this.api.v1.streamsStartUpdate(s, ":start", { ip }); return this.actionResult(res.data); }
     async streamStop(s) { this.requireC64u("streamStop"); const res = await this.api.v1.streamsStopUpdate(s, ":stop"); return this.actionResult(res.data); }
     async configsList() { const res = await this.api.v1.configsList(); return res.data; }
-    async configGet(cat, item) { const res = item ? await this.api.v1.configsDetail2(cat, item) : await this.api.v1.configsDetail(cat); return res.data; }
-    async configSet(cat, item, value) { const res = await this.api.v1.configsUpdate(cat, item, { value }); return this.actionResult(res.data); }
+    // The generated client interpolates path parameters unencoded and the firmware
+    // splits the path on "/" before decoding, so names such as "Bus Sharing - I/O1"
+    // must be percent-encoded here.
+    async configGet(cat, item) { const res = item ? await this.api.v1.configsDetail2(encodeURIComponent(cat), encodeURIComponent(item)) : await this.api.v1.configsDetail(encodeURIComponent(cat)); return res.data; }
+    async configSet(cat, item, value) { const res = await this.api.v1.configsUpdate(encodeURIComponent(cat), encodeURIComponent(item), { value }); return this.actionResult(res.data); }
     async configBatchUpdate(payload) { const res = await this.api.v1.configsCreate(payload); return this.actionResult(res.data); }
     async configLoadFromFlash() { const res = await this.api.v1.configsLoadFromFlashUpdate(":load_from_flash"); return this.actionResult(res.data); }
     async configSaveToFlash() { const res = await this.api.v1.configsSaveToFlashUpdate(":save_to_flash"); return this.actionResult(res.data); }
@@ -838,7 +900,12 @@ function unsupported(name) { const err = new Error(`Operation '${name}' is not s
 function encodeDevicePath(value) {
     return value.split("/").map((segment) => encodeURIComponent(segment)).join("/");
 }
+/** C64U drive letters with their factory bus numbers, so one drive id works on both backends. */
+const VICE_DRIVE_LETTERS = { a: 8, b: 9 };
 function parseDriveNumber(drive) {
+    const key = drive.trim().toLowerCase();
+    if (Object.prototype.hasOwnProperty.call(VICE_DRIVE_LETTERS, key))
+        return VICE_DRIVE_LETTERS[key];
     const match = /\d+/.exec(drive);
     const n = match ? parseInt(match[0], 10) : NaN;
     if (isNaN(n) || n < 8 || n > 11)
@@ -971,29 +1038,29 @@ export async function createFacade(logger, options) {
     // Caller-forced preference: use c64u with provided base URL (used by tests and server wiring)
     if (options?.preferredC64uBaseUrl) {
         const type = envMode === "u2" ? "u2" : "c64u";
-        const backend = new C64uBackend({
+        const backend = new C64uBackend(resolveUltimateEndpoint(type, {
             baseUrl: options.preferredC64uBaseUrl,
             networkPassword: options.preferredC64uNetworkPassword,
-        }, type);
+        }), type);
         logger?.info?.(`Active backend: ${type} (forced by caller)`);
         return { facade: backend, selected: type, reason: "forced by caller", details: { baseUrl: options.preferredC64uBaseUrl } };
     }
     const cfg = readConfigFile();
-    const hasC64u = Boolean(cfg?.c64u);
-    const hasU2 = Boolean(cfg?.u2);
-    const hasVice = Boolean(cfg?.vice);
+    const hasC64u = Boolean(cfg.c64u);
+    const hasU2 = Boolean(cfg.u2);
+    const hasVice = Boolean(cfg.vice);
     if (envMode === "c64u") {
-        const backend = new C64uBackend(cfg?.c64u ?? {});
+        const backend = new C64uBackend(cfg.endpoints.c64u);
         logger?.info?.("Active backend: c64u (from env override)");
         return { facade: backend, selected: "c64u", reason: "env override", details: { baseUrl: backend.getBaseUrl?.() } };
     }
     if (envMode === "u2") {
-        const backend = new C64uBackend(cfg?.u2 ?? {}, "u2");
+        const backend = new C64uBackend(cfg.endpoints.u2, "u2");
         logger?.info?.("Active backend: u2 (from env override)");
         return { facade: backend, selected: "u2", reason: "env override", details: { baseUrl: backend.getBaseUrl?.() } };
     }
     if (envMode === "vice") {
-        const backend = new ViceBackend(cfg?.vice ?? {});
+        const backend = new ViceBackend(cfg.vice ?? {});
         logger?.info?.("Active backend: vice (from env override)");
         const endpoint = backend.getEndpoint();
         return { facade: backend, selected: "vice", reason: "env override", details: { host: endpoint.host, port: endpoint.port } };
@@ -1015,17 +1082,17 @@ export async function createFacade(logger, options) {
         return { facade: backend, selected: "vice", reason: "config only", details: { host: endpoint.host, port: endpoint.port } };
     }
     // No configuration
-    const probeBase = resolveBaseUrl({});
+    const probeBase = cfg.endpoints.c64u.baseUrl;
     try {
         const res = await axios.get(probeBase, { timeout: 1500 });
         if (res.status >= 200 && res.status < 500) {
-            const backend = new C64uBackend({ baseUrl: probeBase });
+            const backend = new C64uBackend(cfg.endpoints.c64u);
             logger?.info?.("Active backend: c64u (fallback – hardware reachable)");
             return { facade: backend, selected: "c64u", reason: "fallback (reachable)", details: { baseUrl: probeBase } };
         }
     }
     catch { }
-    const backend = new ViceBackend(cfg?.vice ?? {});
+    const backend = new ViceBackend(cfg.vice ?? {});
     logger?.info?.("Active backend: vice (fallback – hardware unavailable)");
     const endpoint = backend.getEndpoint();
     return { facade: backend, selected: "vice", reason: "fallback (hardware unavailable)", details: { host: endpoint.host, port: endpoint.port } };
@@ -1036,49 +1103,31 @@ export async function createAllFacades(logger, options) {
     const primary = await createFacade(logger, process.env.C64_MODE?.toLowerCase().trim() === "u2" ? options : undefined);
     const config = readConfigFile();
     const facades = new Map([[primary.selected, primary.facade]]);
-    if (config?.c64u && primary.selected !== "c64u") {
+    if (config.c64u && primary.selected !== "c64u") {
         facades.set("c64u", new C64uBackend(config.c64u));
     }
-    if (config?.u2 && primary.selected !== "u2") {
+    if (config.u2 && primary.selected !== "u2") {
         facades.set("u2", new C64uBackend(config.u2, "u2"));
     }
-    if (config?.vice && primary.selected !== "vice") {
+    if (config.vice && primary.selected !== "vice") {
         facades.set("vice", new ViceBackend(config.vice));
     }
-    if (!facades.has("c64u") && !config?.u2 && shouldProvisionSecondaryC64u(config, options) && primary.selected !== "u2") {
-        facades.set("c64u", new C64uBackend({
-            ...(config?.c64u ?? {}),
-            ...(!config?.c64u?.baseUrl && options?.preferredC64uBaseUrl ? { baseUrl: options.preferredC64uBaseUrl } : {}),
-            ...(!config?.c64u?.networkPassword && options?.preferredC64uNetworkPassword
-                ? { networkPassword: options.preferredC64uNetworkPassword }
-                : {}),
-        }));
+    // Reached only without a configured c64u profile, so the caller's endpoint applies.
+    if (!facades.has("c64u") && !config.u2 && shouldProvisionSecondaryC64u(config, options) && primary.selected !== "u2") {
+        facades.set("c64u", new C64uBackend(resolveUltimateEndpoint("c64u", {
+            baseUrl: options?.preferredC64uBaseUrl,
+            networkPassword: options?.preferredC64uNetworkPassword,
+        })));
     }
     return { primary, facades };
 }
 function shouldProvisionSecondaryC64u(config, options) {
-    return Boolean(config?.c64u
+    return Boolean(config.c64u
         || options?.preferredC64uBaseUrl
         || configuredString(process.env.C64U_HOST)
         || configuredPort(process.env.C64U_PORT)
         || configuredString(process.env.C64U_PASSWORD));
 }
-function resolveBaseUrl(config) {
-    const explicit = normaliseBaseUrl(config.baseUrl);
-    if (explicit)
-        return explicit;
-    const hostEntries = [configuredString(config.host), configuredString(config.hostname)];
-    for (const entry of hostEntries) {
-        if (!entry)
-            continue;
-        const parsed = parseEndpoint(entry);
-        if (parsed.hostname) {
-            const port = firstDefined(configuredPort(config.port), parsed.port) ?? DEFAULT_C64U_PORT;
-            return buildBaseUrl(parsed.hostname, port);
-        }
-    }
-    return buildBaseUrl(DEFAULT_C64U_HOST, DEFAULT_C64U_PORT);
-}
 function configuredString(value) {
     if (typeof value === "string") {
         const trimmed = value.trim();
@@ -1188,42 +1237,9 @@ function configuredPort(value) {
     }
     return undefined;
 }
-function normaliseBaseUrl(value) {
-    const input = configuredString(value);
-    if (!input)
-        return undefined;
-    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(input)) {
-        return `http://${input}`;
-    }
-    return stripTrailingSlash(input);
-}
-function parseEndpoint(value) {
-    try {
-        const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
-        const url = new URL(hasScheme ? value : `http://${value}`);
-        const hostname = url.hostname || undefined;
-        const port = url.port ? configuredPort(url.port) : undefined;
-        return { hostname, port };
-    }
-    catch {
-        return {};
-    }
-}
-function buildBaseUrl(host, port) {
-    const normalizedPort = Number.isInteger(port) && port > 0 ? port : DEFAULT_C64U_PORT;
-    const hostPart = formatHost(host);
-    const suffix = normalizedPort === DEFAULT_C64U_PORT ? "" : `:${normalizedPort}`;
-    return `http://${hostPart}${suffix}`;
-}
 function buildC64uHeaders(networkPassword) {
     return networkPassword ? { "X-Password": networkPassword } : undefined;
 }
-function formatHost(host) {
-    return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
-}
-function stripTrailingSlash(input) {
-    return input.replace(/\/+$/, "");
-}
 function parseArgsList(input) {
     const args = [];
     const pattern = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|(\S+)/g;

package/dist/knowledge.js

@@ -41,7 +41,8 @@ export function formatAddress(address) {
 }
 export function resolveAddressSymbol(input) {
     const key = input.trim().toLowerCase().replace(/\s+/g, "_");
-    return SYMBOLS[key];
+    // Own keys only, so "constructor" or "toString" are not mistaken for symbols.
+    return Object.prototype.hasOwnProperty.call(SYMBOLS, key) ? SYMBOLS[key] : undefined;
 }
 export function listSymbols() {
     return Object.entries(SYMBOLS)

package/dist/petscii.js

@@ -61,8 +61,6 @@ function ensureScreenCodeMap() {
         }
         SCREEN_CODE_TO_ASCII.set(code, deriveGlyphChar(glyph));
     }
-    // Common control characters / gaps default to space to keep output tidy.
-    SCREEN_CODE_TO_ASCII.set(0x00, " ");
     screenCodeMapInitialised = true;
 }
 export function screenCodesToAscii(bytes, options) {
@@ -132,7 +130,7 @@ const NAMED_CHARS = Object.freeze({
     "cursor_left": 157,
     // Graphic glyphs (commonly referenced by name)
     // Note: Exact byte shown on screen depends on mode; these are PETSCII/CHR$ values
-    "heart": 81, // widely used PETSCII code for heart glyph
+    "heart": 115, // $73 (shifted S); $51 would print the letter Q
     "up_arrow": 94,
     "uparrow": 94,
     "left_arrow": 95,
@@ -146,7 +144,8 @@ export function listNamedPetscii() {
 }
 export function lookupNamedPetscii(name) {
     const key = name.trim().toLowerCase().replace(/\s+/g, "_");
-    return NAMED_CHARS[key];
+    // Own keys only, so names like "constructor" don't resolve to Object.prototype members.
+    return Object.prototype.hasOwnProperty.call(NAMED_CHARS, key) ? NAMED_CHARS[key] : undefined;
 }
 /**
  * Try to parse a named character token starting at the given index.
@@ -160,15 +159,16 @@ export function parseNamedCharToken(source, startIndex) {
         return null;
     }
     const close = open === "{" ? "}" : open === ":" ? ":" : ">";
-    let idx = startIndex + 1;
-    let name = "";
-    while (idx < source.length && source[idx] !== close) {
-        name += source[idx]
-            .replace(/[^A-Za-z0-9_\s-]/g, "") // restrict to sane name characters
-            .trim();
-        idx += 1;
-    }
-    if (idx >= source.length || source[idx] !== close) {
+    const idx = source.indexOf(close, startIndex + 1);
+    if (idx < 0) {
+        return null;
+    }
+    // Only sane name characters; anything else is ordinary text that happens to use the delimiters.
+    // Multi-word names such as {cursor up} need braces: ":" and "<" also appear in
+    // ordinary text ("Mode: reverse on: yes"), so they only delimit single words.
+    const name = source.slice(startIndex + 1, idx).trim();
+    const namePattern = open === "{" ? /^[A-Za-z0-9_\s-]+$/ : /^[A-Za-z0-9_-]+$/;
+    if (!namePattern.test(name)) {
         return null;
     }
     const value = lookupNamedPetscii(name.replace(/[-\s]+/g, "_"));
@@ -181,7 +181,7 @@ export function parseNamedCharToken(source, startIndex) {
  * Encode a text containing optional named tokens into PETSCII bytes.
  * Named tokens may appear as {heart}, :heart:, or <heart>.
  */
-export function encodeStringWithNames(input) {
+export function encodeStringWithNames(input, options = {}) {
     const bytes = [];
     let i = 0;
     while (i < input.length) {
@@ -191,7 +191,10 @@ export function encodeStringWithNames(input) {
             i = maybe.endIndex;
             continue;
         }
-        bytes.push(asciiToPetscii(input[i]));
+        // ASCII a-z are PETSCII graphics characters in the default character set,
+        // so callers can fold them to the letters $41-$5A. Named codes are not folded.
+        const char = input[i];
+        bytes.push(asciiToPetscii(options.foldLowercase && char >= "a" && char <= "z" ? char.toUpperCase() : char));
         i += 1;
     }
     return Uint8Array.from(bytes);

package/dist/petsciiArt.js

@@ -19,6 +19,11 @@ const POPCOUNT = (() => {
     }
     return table;
 })();
+const RVS_ON = 18;
+const RVS_OFF = 146;
+// Marks the end of a character row in the generated DATA statements.
+const ROW_END = -1;
+const SCREEN_COLUMNS = 40;
 const DEFAULT_MAX_WIDTH = 320;
 const DEFAULT_MAX_HEIGHT = 200;
 const SHAPES = [
@@ -252,10 +257,14 @@ function distanceBetween(block, glyph) {
     }
     return score;
 }
+/**
+ * Match each 8x8 block to a glyph. `glyphs` has one entry per cell; `codes` is the
+ * PETSCII stream that prints them, with each run of reverse-video glyphs (screen
+ * codes $80-$FF) wrapped in RVS ON/RVS OFF. `rowCodes` holds that stream per row.
+ */
 export function bitmapToPetsciiCodes(bitmap) {
     const { blocks, columns, rows } = splitIntoBlocks(bitmap);
     const glyphs = getChargenGlyphs();
-    const codes = [];
     const matchedGlyphs = [];
     for (const block of blocks) {
         let bestMatch;
@@ -270,11 +279,26 @@ export function bitmapToPetsciiCodes(bitmap) {
                 }
             }
         }
-        const selected = bestMatch ?? glyphs[0];
-        codes.push(selected.petsciiCode);
-        matchedGlyphs.push(selected);
+        matchedGlyphs.push(bestMatch ?? glyphs[0]);
     }
-    return { codes, glyphs: matchedGlyphs, columns, rows };
+    const rowCodes = [];
+    for (let row = 0; row < rows; row += 1) {
+        const stream = [];
+        let reverse = false;
+        for (const glyph of matchedGlyphs.slice(row * columns, (row + 1) * columns)) {
+            const glyphReverse = (glyph.screenCode & 0x80) !== 0;
+            if (glyphReverse !== reverse) {
+                stream.push(glyphReverse ? RVS_ON : RVS_OFF);
+                reverse = glyphReverse;
+            }
+            stream.push(glyph.petsciiCode);
+        }
+        if (reverse) {
+            stream.push(RVS_OFF);
+        }
+        rowCodes.push(stream);
+    }
+    return { codes: rowCodes.flat(), rowCodes, glyphs: matchedGlyphs, columns, rows };
 }
 function buildBasicProgram(params) {
     const lines = [];
@@ -288,19 +312,21 @@ function buildBasicProgram(params) {
         lines.push(`${lineNumber} POKE 646,${fg}`);
         lineNumber += 10;
     }
+    // Rows vary in length because of the RVS ON/OFF codes, so each row's DATA ends with ROW_END.
     lines.push(`${lineNumber} FORY=0TO${Math.max(0, params.rows - 1)}`);
     lineNumber += 10;
-    lines.push(`${lineNumber} FORX=0TO${Math.max(0, params.columns - 1)}`);
-    lineNumber += 10;
-    lines.push(`${lineNumber} READC:PRINT CHR$(C);`);
-    lineNumber += 10;
-    lines.push(`${lineNumber} NEXTX:PRINT`);
+    const readLine = lineNumber;
+    // POKE212,0 clears quote mode: after a printed '"' glyph the editor would
+    // otherwise draw the following RVS ON/OFF codes as characters.
+    lines.push(`${readLine} READC:IFC>=0THENPRINT CHR$(C);:POKE212,0:GOTO${readLine}`);
     lineNumber += 10;
-    lines.push(`${lineNumber} NEXTY`);
+    // A full 40-column row already wraps the cursor; an extra PRINT would leave a blank line.
+    lines.push(params.columns >= SCREEN_COLUMNS ? `${lineNumber} NEXTY` : `${lineNumber} PRINT:NEXTY`);
     lineNumber += 10;
+    const data = params.rowCodes.flatMap((row) => [...row, ROW_END]);
     const chunkSize = 16;
-    for (let i = 0; i < params.codes.length; i += chunkSize) {
-        const slice = params.codes.slice(i, i + chunkSize);
+    for (let i = 0; i < data.length; i += chunkSize) {
+        const slice = data.slice(i, i + chunkSize);
         const dataLine = slice.join(",");
         lines.push(`${lineNumber} DATA ${dataLine}`);
         lineNumber += 10;
@@ -334,7 +360,7 @@ export function createPetsciiArt(options) {
     const converted = bitmapToPetsciiCodes(bitmap);
     const codes = converted.codes;
     const program = buildBasicProgram({
-        codes,
+        rowCodes: converted.rowCodes,
         columns: converted.columns,
         rows: converted.rows,
         borderColor: options.borderColor,

package/dist/rag/indexer.js

@@ -12,7 +12,8 @@ const BASIC_DIR = path.join(ASSET_ROOT, "data/basic/examples");
 const ASM_DIR = path.join(ASSET_ROOT, "data/assembly/examples");
 const EXTERNAL_DIR = path.join(ASSET_ROOT, "external");
 const DOC_ROOT = path.join(ASSET_ROOT, "doc");
-const DOC_EXCLUDE_DIRS = new Set(["plans"]);
+// Plans and reviews are internal engineering notes, not C64 reference material.
+const DOC_EXCLUDE_DIRS = new Set(["plans", "reviews"]);
 const CONTEXT_DIR = path.join(ASSET_ROOT, "data/context");
 const BOOTSTRAP_PATH = path.join(CONTEXT_DIR, "bootstrap.md");
 const AGENTS_PATH = path.join(ASSET_ROOT, "AGENTS.md");

package/dist/sidwave.js

@@ -16,7 +16,7 @@ export function parseSidwave(input) {
     const legacy = !!obj.song;
     const header = legacy
         ? { title: obj.song?.title, tempo: obj.song?.tempo, mode: obj.song?.mode, length_bars: obj.song?.length_bars, global_fx: obj.song?.global_fx }
-        : { title: obj.title, author: obj.author, tempo: obj.tempo, mode: obj.mode, length_bars: obj, global_fx: obj.global_fx };
+        : { title: obj.title, author: obj.author, tempo: obj.tempo, mode: obj.mode, length_bars: obj.length_bars, global_fx: obj.global_fx };
     const title = header.title ?? "Untitled";
     const tempo = normalizeTempo(header.tempo);
     const mode = header.mode ?? "PAL";

package/dist/sidwaveCompiler.js

@@ -71,19 +71,15 @@ export function compileSidwaveToPrg(doc) {
             }
             if (pat.type === "arpeggio" && Array.isArray(pat.notes) && pat.notes.length) {
                 const stepFrames = Math.max(1, Math.round((pat.frame_rate ? fps / pat.frame_rate : framesPerBeat)));
-                let idx = 0;
                 for (let f = 0; f < totalFramesInSection; f += 1) {
-                    if (f % stepFrames === 0)
-                        idx = (idx + 1) % pat.notes.length;
+                    const idx = Math.floor(f / stepFrames) % pat.notes.length;
                     notesForSong.push(String(pat.notes[idx]));
                 }
             }
             else if (Array.isArray(pat.groove) && pat.groove.length) {
                 const stepFrames = framesPerBeat; // one note per beat
-                let gi = 0;
                 for (let f = 0; f < totalFramesInSection; f += 1) {
-                    if (f % stepFrames === 0)
-                        gi = (gi + 1) % pat.groove.length;
+                    const gi = Math.floor(f / stepFrames) % pat.groove.length;
                     notesForSong.push(String(pat.groove[gi]));
                 }
             }
@@ -95,10 +91,8 @@ export function compileSidwaveToPrg(doc) {
                 const lengthBeats = Math.max(1, Math.floor(pat.length ?? 1));
                 const stepFrames = framesPerBeat * lengthBeats;
                 const baseNote = "C3";
-                let mi = 0;
                 for (let f = 0; f < totalFramesInSection; f += 1) {
-                    if (f % stepFrames === 0)
-                        mi = (mi + 1) % Math.max(1, intervals.length);
+                    const mi = Math.floor(f / stepFrames) % Math.max(1, intervals.length);
                     const iv = intervals.length ? intervals[mi] : 0;
                     notesForSong.push(transposeNote(baseNote, iv));
                 }