c64bridge 1.0.3 → 1.0.5

package/dist/c64Client.js

@@ -11,7 +11,8 @@ import { createSocket } from "node:dgram";
 import { networkInterfaces } from "node:os";
 import axios from "axios";
 import { basicToPrg } from "./tools/translation/basicTokenizer.js";
-import { assemblyToPrg } from "./tools/translation/assembler.js";
+import { assemblyToPrg, prgEntryAddress } from "./tools/translation/assembler.js";
+import { stripHexByteSeparators } from "./tools/hex.js";
 import { petsciiToAscii, screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
 import { createAllFacades, createFacade, } from "./device.js";
@@ -302,9 +303,6 @@ export class C64Client {
         }
         writeDiagnosticEvent("client_switch_backend", { backend: type });
     }
-    async shouldUseC64uMockBypass() {
-        return process.env.C64_TEST_TARGET === "mock" && (await this.getBackendType()) === "c64u";
-    }
     async withViceMonitor(fn) {
         const backend = await this.requireViceBackend();
         return backend.withMonitor(fn);
@@ -546,7 +544,8 @@ export class C64Client {
      * tokens, and setting BASIC's TXTTAB/VARTAB/ARYTAB/STREND to the code
      * range corrupts the workspace. Instead this loads the assembled bytes
      * without running them, then types `SYS <entry>` to transfer control
-     * directly to the first assembled instruction, whatever its address.
+     * to the entry point: the target of a leading SYS stub at $0801, or else
+     * the lowest assembled address.
      */
     async uploadAndRunAsm(program) {
         try {
@@ -554,7 +553,16 @@ export class C64Client {
             if (prg.length < 2) {
                 return { success: false, details: { message: "Assembled program produced no output" } };
             }
-            const entryAddress = prg.readUInt16LE(0);
+            const entryAddress = prgEntryAddress(prg);
+            if (entryAddress === 0x0801) {
+                // Loading makes BASIC relink $0801 as program lines, which overwrites raw code there.
+                return {
+                    success: false,
+                    details: {
+                        message: "Machine code at $0801 is overwritten when BASIC relinks the loaded program. Omit the origin to get a BASIC SYS stub automatically, start the code with a BASIC SYS line, or assemble at another address such as $C000.",
+                    },
+                };
+            }
             const facade = await this.facadePromise;
             const loadResult = await facade.loadPrg(prg);
             if (!loadResult.success) {
@@ -573,13 +581,6 @@ export class C64Client {
     }
     async runPrg(prg) {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
-                const payload = Buffer.isBuffer(prg) ? prg : Buffer.from(prg);
-                const response = await this.api.v1.runnersRunPrgCreate(":run_prg", payload, {
-                    headers: { "Content-Type": "application/octet-stream" },
-                });
-                return { success: true, details: response.data };
-            }
             const facade = await this.facadePromise;
             const res = await facade.runPrg(prg);
             return { success: res.success, details: res.details };
@@ -659,10 +660,6 @@ export class C64Client {
     }
     async reset() {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
-                const response = await this.api.v1.machineResetUpdate(":reset");
-                return { success: true, details: response.data };
-            }
             const facade = await this.facadePromise;
             const res = await facade.reset();
             return { success: res.success, details: res.details };
@@ -673,10 +670,6 @@ export class C64Client {
     }
     async reboot() {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
-                const response = await this.api.v1.machineRebootUpdate(":reboot");
-                return { success: true, details: response.data };
-            }
             const facade = await this.facadePromise;
             const res = await facade.reboot();
             return { success: res.success, details: res.details };
@@ -794,7 +787,8 @@ export class C64Client {
             return { success: false, details: { message: "Voice must be 1..3" } };
         }
         const system = options.system ?? "PAL";
-        const hz = options.frequencyHz ?? (options.note ? this.noteNameToHz(options.note) : 440);
+        // The tool schema documents that a note name overrides frequencyHz.
+        const hz = options.note ? this.noteNameToHz(options.note) : options.frequencyHz ?? 440;
         const freq16 = this.hzToSidFrequency(hz, system);
         const freqLo = freq16 & 0xff;
         const freqHi = (freq16 >> 8) & 0xff;
@@ -857,10 +851,6 @@ export class C64Client {
     }
     async pause(pinnedFacade) {
         try {
-            if (!pinnedFacade && await this.shouldUseC64uMockBypass()) {
-                const res = await this.api.v1.machinePauseUpdate(":pause");
-                return { success: true, details: res.data };
-            }
             const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.pause();
         }
@@ -870,10 +860,6 @@ export class C64Client {
     }
     async resume(pinnedFacade) {
         try {
-            if (!pinnedFacade && await this.shouldUseC64uMockBypass()) {
-                const res = await this.api.v1.machineResumeUpdate(":resume");
-                return { success: true, details: res.data };
-            }
             const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.resume();
         }
@@ -981,10 +967,6 @@ export class C64Client {
     }
     async menuButton() {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
-                const res = await this.api.v1.machineMenuButtonUpdate(":menu_button");
-                return { success: true, details: res.data };
-            }
             const facade = await this.facadePromise;
             return await facade.menuButton();
         }
@@ -1006,10 +988,6 @@ export class C64Client {
     }
     async debugregRead() {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
-                const res = await this.api.v1.machineDebugregList(":debugreg");
-                return { success: true, value: res.data.value, details: res.data };
-            }
             const facade = await this.facadePromise;
             return await facade.debugregRead();
         }
@@ -1019,10 +997,6 @@ export class C64Client {
     }
     async debugregWrite(value) {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
-                const res = await this.api.v1.machineDebugregUpdate(":debugreg", { value });
-                return { success: true, value: res.data.value, details: res.data };
-            }
             const facade = await this.facadePromise;
             return await facade.debugregWrite(value);
         }
@@ -1083,10 +1057,6 @@ export class C64Client {
         try {
             if (!drive || !path)
                 throw new Error("Drive and path are required");
-            if (await this.shouldUseC64uMockBypass()) {
-                const res = await this.api.v1.drivesLoadRomUpdate(drive, ":load_rom", { file: path });
-                return { success: true, details: res.data };
-            }
             const facade = await this.facadePromise;
             const result = await facade.driveLoadRom(drive, path);
             return { success: result.success, details: result.details };
@@ -1141,6 +1111,9 @@ export class C64Client {
             if (facade.type === "vice") {
                 return this.captureViceFrames(requestedCount);
             }
+            if (facade.type !== "c64u") {
+                throw new Error("Video frame capture is only available on C64U/U64 and VICE; U2 has no video stream");
+            }
             return this.captureC64uVideoFrames(facade, requestedCount, {
                 reuseSession: options?.reuseSession === true,
                 keepAliveMs: Math.max(0, Math.trunc(options?.keepAliveMs ?? 0)),
@@ -2181,8 +2154,7 @@ export class C64Client {
         if (trimmed.length === 0) {
             throw new Error("Expected non-empty byte string");
         }
-        const withoutPrefix = trimmed.startsWith("$") ? trimmed.slice(1) : trimmed;
-        const cleaned = withoutPrefix.replace(/[\s_]/g, "").toLowerCase();
+        const cleaned = stripHexByteSeparators(trimmed).toLowerCase();
         if (cleaned.length === 0) {
             throw new Error("No hexadecimal data provided");
         }
@@ -2412,9 +2384,12 @@ export function buildPrinterBasicProgram(opts) {
             ln += 10;
             continue;
         }
-        const chunks = chunkString(logical, 45);
+        // Chunk by the length of the expression, not the text: CHR$ splicing can make
+        // an expression up to ten times longer, and a BASIC line must stay short
+        // (the ROM's LINKPRG scans each line with an 8-bit index).
+        const chunks = chunkByExpressionLength(logical, (text) => printerTextExpression(text, target, saddr), PRINTER_EXPRESSION_MAX);
         for (let i = 0; i < chunks.length; i += 1) {
-            const chunk = basicStringExpression(chunks[i]);
+            const chunk = printerTextExpression(chunks[i], target, saddr);
             const tail = i < chunks.length - 1 ? ";" : ""; // avoid CR between chunks within the same logical line
             lines.push(`${ln} PRINT#1,${chunk}${tail}`);
             ln += 10;
@@ -2429,21 +2404,53 @@ export function buildPrinterBasicProgram(opts) {
     lines.push(`${ln} CLOSE1`);
     return lines.join("\n");
 }
-function chunkString(input, maxLen) {
-    if (input.length <= maxLen)
-        return [input];
+/** Longest PRINT#1 expression per BASIC line; keeps each line under the 80-character input limit. */
+const PRINTER_EXPRESSION_MAX = 64;
+function chunkByExpressionLength(input, expression, maxLen) {
     const parts = [];
-    let i = 0;
-    while (i < input.length) {
-        parts.push(input.slice(i, i + maxLen));
-        i += maxLen;
+    let current = "";
+    for (const char of input) {
+        if (current && expression(current + char).length > maxLen) {
+            parts.push(current);
+            current = "";
+        }
+        current += char;
     }
+    if (current)
+        parts.push(current);
     return parts;
 }
-function basicStringExpression(input) {
-    // BASIC V2 has no doubled-quote escaping. Splice literal quote characters
-    // through CHR$(34), including leading/trailing/consecutive quote cases.
-    return input.split('"').map((part) => `"${part}"`).join(";CHR$(34);");
+/**
+ * BASIC V2 has no doubled-quote escaping, so quotes are spliced in as CHR$(34).
+ * String literals also store a-z as the PETSCII letters $41-$5A, so printer
+ * text that needs other codes is spliced in with CHR$: an Epson printer takes
+ * ASCII, so lowercase stays $61-$7A; a Commodore printer in lowercase mode
+ * (secondary address 7) prints $41-$5A as lowercase and $C1-$DA as capitals.
+ */
+function printerTextExpression(input, target, secondaryAddress) {
+    const needsChr = (char) => {
+        if (target === "epson" && char >= "a" && char <= "z")
+            return char.charCodeAt(0);
+        if (target === "commodore" && secondaryAddress === 7 && char >= "A" && char <= "Z")
+            return char.charCodeAt(0) + 0x80;
+        return undefined;
+    };
+    const pieces = [];
+    let literal = "";
+    for (const char of input) {
+        const code = char === '"' ? 34 : needsChr(char);
+        if (code === undefined) {
+            literal += char;
+            continue;
+        }
+        if (literal)
+            pieces.push(`"${literal}"`);
+        literal = "";
+        pieces.push(`CHR$(${code})`);
+    }
+    if (literal || pieces.length === 0)
+        pieces.push(`"${literal}"`);
+    return pieces.join(";");
 }
 export function buildCommodoreBitmapBasicProgram(opts) {
     const repeats = Math.max(1, Math.floor(opts.repeats ?? 1));

package/dist/config.js

@@ -4,13 +4,6 @@ import os from "node:os";
 import { fileURLToPath } from "url";
 const DEFAULT_HOST = "c64u";
 const DEFAULT_PORT = 80;
-const DEFAULT_CONFIG = {
-    c64_host: DEFAULT_HOST,
-    baseUrl: buildBaseUrl(DEFAULT_HOST, DEFAULT_PORT),
-    c64_port: DEFAULT_PORT,
-    vicePrewarm: false,
-    backendConfig: {},
-};
 export function loadConfig() {
     const configPath = process.env.C64BRIDGE_CONFIG;
     const cwdConfigPath = join(process.cwd(), ".c64bridge.json");
@@ -39,61 +32,105 @@ export function loadConfig() {
     rawConfig ?? (rawConfig = {});
     // New schema: choose the configured Ultimate hardware profile; retain
     // c64u and legacy fields as the default when C64_MODE is not set to u2.
-    const c64u = rawConfig?.c64u;
-    const u2 = rawConfig?.u2;
+    const c64u = ultimateSection(rawConfig?.c64u);
+    const u2 = ultimateSection(rawConfig?.u2);
     const useU2 = process.env.C64_MODE?.trim().toLowerCase() === "u2";
-    const hardware = useU2 ? (u2 ?? c64u) : (c64u ?? u2);
+    // Legacy top-level endpoint fields describe the single Ultimate of a
+    // pre-profile config, so they configure a backend only when the document
+    // has neither a c64u nor a u2 section. Each backend otherwise uses its own
+    // section, so one device's host, port or password never reaches the other.
+    const legacyUltimateEndpoint = !c64u && !u2 && LEGACY_ENDPOINT_KEYS.some((key) => hasLegacyValue(rawConfig?.[key]));
+    const ultimate = {
+        c64u: resolveUltimateEndpoint("c64u", c64u, c64u || !u2 ? rawConfig : undefined),
+        u2: resolveUltimateEndpoint("u2", u2 ?? c64u, u2 ? undefined : rawConfig),
+    };
+    // The selected profile reported by loadConfig keeps the documented fallback
+    // between sections and to the legacy fields.
+    const selected = useU2
+        ? resolveUltimateEndpoint("u2", u2 ?? c64u, rawConfig)
+        : resolveUltimateEndpoint("c64u", c64u ?? u2, rawConfig);
     const vice = rawConfig?.vice;
-    const parsedC64uHost = parseEndpoint(configuredString(hardware?.host));
-    const parsedC64uHostname = parseEndpoint(configuredString(hardware?.hostname));
-    const parsedLegacyHost = parseEndpoint(configuredString(rawConfig?.c64_host));
-    const parsedLegacyIp = parseEndpoint(configuredString(rawConfig?.c64_ip));
-    const parsedEnvHost = parseEndpoint(configuredString(useU2 ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST));
+    const config = {
+        c64_host: selected.c64_host,
+        baseUrl: selected.baseUrl,
+        c64_port: selected.port,
+        networkPassword: selected.networkPassword,
+        vicePrewarm: firstDefined(configuredBoolean(process.env.VICE_PREWARM), configuredBoolean(vice?.prewarm), configuredBoolean(rawConfig?.vicePrewarm)) ?? false,
+        ultimate,
+        legacyUltimateEndpoint,
+        backendConfig: {
+            ...(c64u ? { c64u } : {}),
+            ...(u2 ? { u2 } : {}),
+            ...(rawConfig?.vice && typeof rawConfig.vice === "object" && !Array.isArray(rawConfig.vice) ? { vice: rawConfig.vice } : {}),
+        },
+    };
+    return config;
+}
+/** Top-level fields from the pre-profile config schema that name an endpoint. */
+const LEGACY_ENDPOINT_KEYS = ["baseUrl", "c64_host", "c64_ip", "c64_port"];
+function hasLegacyValue(value) {
+    return (typeof value === "string" && value.trim().length > 0) || (typeof value === "number" && Number.isFinite(value));
+}
+function ultimateSection(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * The single host/port/password precedence for an Ultimate profile, used by
+ * loadConfig() and by every C64U/U2 backend construction:
+ * env > section host/hostname/port > legacy top-level c64_host/c64_ip/c64_port
+ * > section baseUrl > legacy top-level baseUrl > defaults. Passwords: env >
+ * section > legacy top-level networkPassword.
+ */
+export function resolveUltimateEndpoint(profile, section, legacy) {
+    const envHost = profile === "u2" ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST;
+    const envPort = profile === "u2" ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT;
+    const envPassword = profile === "u2" ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD;
+    const parsedSectionHost = parseEndpoint(configuredString(section?.host));
+    const parsedSectionHostname = parseEndpoint(configuredString(section?.hostname));
+    const parsedLegacyHost = parseEndpoint(configuredString(legacy?.c64_host));
+    const parsedLegacyIp = parseEndpoint(configuredString(legacy?.c64_ip));
+    const parsedEnvHost = parseEndpoint(configuredString(envHost));
     const parsedBaseOverrides = [
-        parseEndpoint(normaliseBaseUrl(hardware?.baseUrl)),
-        parseEndpoint(normaliseBaseUrl(rawConfig?.baseUrl)),
+        parseEndpoint(normaliseBaseUrl(configuredString(section?.baseUrl))),
+        parseEndpoint(normaliseBaseUrl(configuredString(legacy?.baseUrl))),
     ];
     const hostCandidates = [
         parsedEnvHost.hostname,
-        parsedC64uHost.hostname,
-        parsedC64uHostname.hostname,
+        parsedSectionHost.hostname,
+        parsedSectionHostname.hostname,
         parsedLegacyHost.hostname,
         parsedLegacyIp.hostname,
         ...parsedBaseOverrides.map((entry) => entry.hostname),
     ];
     const portCandidates = [
-        configuredPort(useU2 ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT),
+        configuredPort(envPort),
         parsedEnvHost.port,
-        configuredPort(hardware?.port),
-        parsedC64uHost.port,
-        parsedC64uHostname.port,
-        configuredPort(rawConfig?.c64_port),
+        configuredPort(section?.port),
+        parsedSectionHost.port,
+        parsedSectionHostname.port,
+        configuredPort(legacy?.c64_port),
         parsedLegacyHost.port,
         parsedLegacyIp.port,
         ...parsedBaseOverrides.map((entry) => entry.port),
     ];
     const host = firstDefined(...hostCandidates) ?? DEFAULT_HOST;
     const port = firstDefined(...portCandidates) ?? DEFAULT_PORT;
-    const baseUrl = buildBaseUrl(host, port);
     const hostLabel = formatHost(host);
-    const hostWithPort = port === DEFAULT_PORT ? hostLabel : `${hostLabel}:${port}`;
-    const config = {
-        c64_host: hostWithPort,
-        baseUrl,
-        c64_port: port,
-        networkPassword: firstDefined(configuredString(useU2 ? process.env.U2_PASSWORD ?? process.env.C64U_PASSWORD : process.env.C64U_PASSWORD), configuredString(hardware?.networkPassword), configuredString(rawConfig?.networkPassword)),
-        vicePrewarm: firstDefined(configuredBoolean(process.env.VICE_PREWARM), configuredBoolean(vice?.prewarm), configuredBoolean(rawConfig?.vicePrewarm)) ?? false,
-        backendConfig: {
-            ...(rawConfig?.c64u && typeof rawConfig.c64u === "object" && !Array.isArray(rawConfig.c64u) ? { c64u: rawConfig.c64u } : {}),
-            ...(rawConfig?.u2 && typeof rawConfig.u2 === "object" && !Array.isArray(rawConfig.u2) ? { u2: rawConfig.u2 } : {}),
-            ...(rawConfig?.vice && typeof rawConfig.vice === "object" && !Array.isArray(rawConfig.vice) ? { vice: rawConfig.vice } : {}),
-        },
+    return {
+        host,
+        port,
+        baseUrl: buildBaseUrl(host, port),
+        c64_host: port === DEFAULT_PORT ? hostLabel : `${hostLabel}:${port}`,
+        networkPassword: firstDefined(nonEmptyString(envPassword), nonEmptyString(section?.networkPassword), nonEmptyString(legacy?.networkPassword)),
     };
-    return config;
 }
 function configuredString(value) {
     return typeof value === "string" ? value.trim() : undefined;
 }
+function nonEmptyString(value) {
+    const trimmed = configuredString(value);
+    return trimmed ? trimmed : undefined;
+}
 function configuredPort(value) {
     if (typeof value === "number" && Number.isInteger(value) && value > 0 && value <= 65535) {
         return value;