c64bridge 0.9.3 → 1.0.1

package/dist/c64Client.js

@@ -10,14 +10,69 @@ import { createSocket } from "node:dgram";
 import axios from "axios";
 import { basicToPrg } from "./tools/translation/basicTokenizer.js";
 import { assemblyToPrg } from "./tools/translation/assembler.js";
-import { screenCodesToAscii } from "./petscii.js";
+import { petsciiToAscii, screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
-import { createAllFacades, createFacade } from "./device.js";
+import { createAllFacades, createFacade, } from "./device.js";
 import { Api } from "../generated/c64/index.js";
 import { createLoggingHttpClient } from "./loggingHttpClient.js";
 import { withDiagnosticSpan, writeDiagnosticEvent } from "./diagnostics.js";
 import { C64U_NTSC_AUDIO_SAMPLE_RATE, C64U_PAL_AUDIO_SAMPLE_RATE, collectCompleteVideoFrames, parseAudioPacket, parseVideoPacket, } from "./streamCapture.js";
 import { buildVicBitmapRegisters, resolveVicBitmapMemoryLayout, } from "./vicBitmap.js";
+/** Raised when the KERNAL keyboard buffer did not drain before another chunk
+ * could safely be queued. Callers must report this as partial delivery. */
+export class KeyboardQueueDrainTimeoutError extends Error {
+    constructor(delivered, requested, timeoutMs) {
+        super(`Keyboard queue did not drain after ${timeoutMs}ms; delivered ${delivered} of ${requested} byte(s). Resume the machine and retry the remaining input.`);
+        this.name = "KeyboardQueueDrainTimeoutError";
+        this.delivered = delivered;
+        this.requested = requested;
+        this.timeoutMs = timeoutMs;
+    }
+}
+function menuMatrixIncludes(matrix, expected) {
+    // Firmware supplies the character matrix followed by its colour matrix. The
+    // documented wire format is raw bytes, so only inspect the first 40×25
+    // character cells when that complete layout is present.
+    const characters = matrix.length >= 2000 ? matrix.subarray(0, 1000) : matrix;
+    const normalizedExpected = expected.replace(/\s+/g, " ").toUpperCase();
+    return [screenCodesToAscii(characters), petsciiToAscii(characters)]
+        .some((text) => text.replace(/\s+/g, " ").toUpperCase().includes(normalizedExpected));
+}
+function selectedMenuRow(matrix) {
+    // The firmware contract exposes a 40x25 character matrix followed by its
+    // colour matrix. A selected menu row is rendered with one uniform colour
+    // distinct from the normal rows. Reject malformed/ambiguous matrices.
+    if (matrix.length < 2000)
+        return null;
+    const colours = matrix.subarray(1000, 2000);
+    const rows = [];
+    for (let row = 0; row < 25; row += 1) {
+        const cells = colours.subarray(row * 40, row * 40 + 40);
+        if (cells.length === 40 && cells.every((value) => value === cells[0]))
+            rows.push(row);
+    }
+    if (rows.length === 0)
+        return null;
+    const normal = new Map();
+    for (const row of rows)
+        normal.set(colours[row * 40], (normal.get(colours[row * 40]) ?? 0) + 1);
+    const [colour, count] = [...normal.entries()].sort((a, b) => b[1] - a[1])[0] ?? [];
+    if (colour === undefined || count === undefined)
+        return null;
+    const selected = rows.filter((row) => colours[row * 40] !== colour);
+    return selected.length === 1 ? selected[0] : null;
+}
+function selectedMenuRowIncludes(matrix, expected) {
+    const row = selectedMenuRow(matrix);
+    if (row === null)
+        return false;
+    const text = [screenCodesToAscii(matrix.subarray(row * 40, row * 40 + 40)), petsciiToAscii(matrix.subarray(row * 40, row * 40 + 40))]
+        .map((value) => value.replace(/\s+/g, " ").toUpperCase());
+    return text.some((value) => value.includes(expected.replace(/\s+/g, " ").toUpperCase()));
+}
+function isMissingEndpoint(error) {
+    return axios.isAxiosError(error) && error.response?.status === 404;
+}
 const TEXT_SCREEN_COLUMNS = 40;
 const TEXT_SCREEN_ROWS = 25;
 const TEXT_SCREEN_SIZE = TEXT_SCREEN_COLUMNS * TEXT_SCREEN_ROWS;
@@ -45,6 +100,7 @@ export class C64Client {
         this.warmupPromises = new Map();
         this.greetingDd00Cache = new Map();
         this.greetingDd00Warmups = new Map();
+        this.machineInputCapabilityProbes = new Map();
         this.c64uVideoCaptureSession = null;
         this.activeType = "c64u";
         this.baseUrl = baseUrl;
@@ -66,13 +122,15 @@ export class C64Client {
             preferredC64uNetworkPassword: options.networkPassword,
         });
         this.facadePromise = allFacadesPromise.then(({ primary }) => primary.facade);
-        this.initPromise = allFacadesPromise.then(({ primary, secondary, secondaryType }) => {
+        this.initPromise = allFacadesPromise.then(({ primary, facades }) => {
             const primaryPromise = Promise.resolve(primary.facade);
             this.activeType = primary.selected;
             this.facadePromise = primaryPromise;
             this.allFacades.set(primary.selected, primaryPromise);
-            if (secondary && secondaryType) {
-                this.allFacades.set(secondaryType, Promise.resolve(secondary));
+            for (const [type, facade] of facades) {
+                if (type !== primary.selected) {
+                    this.allFacades.set(type, Promise.resolve(facade));
+                }
             }
         });
     }
@@ -86,10 +144,48 @@ export class C64Client {
     async getBackendType() {
         return this.getActiveBackendType();
     }
+    /**
+     * Snapshot the facade currently active for this invocation. A multi-step
+     * flow (pause/read/write/resume, or repeated polling) must resolve the
+     * facade once and reuse that same instance for every step, so a concurrent
+     * `switchBackend` cannot retarget an operation already underway.
+     */
+    async pinFacade() {
+        return this.facadePromise;
+    }
     async getActiveBackendType() {
         await this.initPromise;
         return this.activeType;
     }
+    /**
+     * Discover native endpoint availability without changing machine state.
+     * `machine:input` has a safe GET probe; `machine:menu_screen` is only
+     * distinguishable from an inactive menu once a menu is visible.
+     */
+    async getNativeEndpointCapabilities() {
+        const facade = await this.facadePromise;
+        if (facade.type === "vice") {
+            return { machineInput: "unavailable", machineMenuScreen: "unavailable" };
+        }
+        if (facade.type === "u2") {
+            return { machineInput: "unavailable", machineMenuScreen: "unknown" };
+        }
+        let probe = this.machineInputCapabilityProbes.get(facade.type);
+        if (!probe) {
+            probe = facade.getInputState()
+                .then(() => "available")
+                .catch((error) => isMissingEndpoint(error) ? "unavailable" : "unknown");
+            this.machineInputCapabilityProbes.set(facade.type, probe);
+            // A transport error is not a capability result. Keep confirmed states,
+            // but make a later resource read retry rather than poisoning the cache.
+            void probe.then((result) => {
+                if (result === "unknown" && this.machineInputCapabilityProbes.get(facade.type) === probe) {
+                    this.machineInputCapabilityProbes.delete(facade.type);
+                }
+            });
+        }
+        return { machineInput: await probe, machineMenuScreen: "unknown" };
+    }
     getAvailableBackends() {
         return Array.from(this.allFacades.keys());
     }
@@ -362,9 +458,37 @@ export class C64Client {
             };
         }
     }
+    /**
+     * Assemble, load, and execute a pure machine-code program. Loading a PRG
+     * with LOAD+RUN (the generic path used by {@link runPrg}) is only correct
+     * for tokenized BASIC text: RUN misinterprets raw 6510 opcodes as BASIC
+     * 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.
+     */
     async uploadAndRunAsm(program) {
-        const prg = assemblyToPrg(program);
-        return this.runPrg(prg);
+        try {
+            const prg = assemblyToPrg(program);
+            if (prg.length < 2) {
+                return { success: false, details: { message: "Assembled program produced no output" } };
+            }
+            const entryAddress = prg.readUInt16LE(0);
+            const facade = await this.facadePromise;
+            const loadResult = await facade.loadPrg(prg);
+            if (!loadResult.success) {
+                return { success: false, details: loadResult.details };
+            }
+            const sysCommand = Buffer.from(`SYS${entryAddress}\r`, "ascii");
+            const injectResult = await this.injectKeyboardQueue(sysCommand, { pinnedFacade: facade });
+            return {
+                success: true,
+                details: { load: loadResult.details, entryAddress, delivered: injectResult.delivered },
+            };
+        }
+        catch (error) {
+            return { success: false, details: this.normaliseError(error) };
+        }
     }
     async runPrg(prg) {
         try {
@@ -480,13 +604,13 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async readMemory(addressInput, lengthInput) {
+    async readMemory(addressInput, lengthInput, pinnedFacade) {
         try {
             const resolved = resolveAddressSymbol(addressInput);
             const address = resolved ?? this.parseNumeric(addressInput);
             const length = this.parseNumeric(lengthInput);
             validateMemoryRange(address, length);
-            const rawBytes = await this.readMemoryRaw(address, length);
+            const rawBytes = await this.readMemoryRaw(address, length, pinnedFacade);
             const bytes = rawBytes.slice(0, length);
             return {
                 success: true,
@@ -504,7 +628,7 @@ export class C64Client {
             };
         }
     }
-    async writeMemory(addressInput, bytesInput) {
+    async writeMemory(addressInput, bytesInput, pinnedFacade) {
         try {
             const resolved = resolveAddressSymbol(addressInput);
             const address = resolved ?? this.parseNumeric(addressInput);
@@ -513,7 +637,7 @@ export class C64Client {
             // Prefer PUT with hex data for up to 128 bytes; fall back to POST binary for larger writes
             const addrStr = this.formatAddress(address);
             try {
-                const facade = await this.facadePromise;
+                const facade = pinnedFacade ?? await this.facadePromise;
                 await facade.writeMemory(address, dataBuffer);
                 return {
                     success: true,
@@ -557,10 +681,10 @@ export class C64Client {
         }
     }
     // --- SID/Music helpers ---
-    async sidSetVolume(volume) {
+    async sidSetVolume(volume, pinnedFacade) {
         const clamped = Math.max(0, Math.min(15, Math.floor(volume)));
         const byte = Buffer.from([clamped]);
-        return this.writeMemory("$D418", this.bytesToHex(byte));
+        return this.writeMemory("$D418", this.bytesToHex(byte), pinnedFacade);
     }
     async sidReset(hard = false) {
         try {
@@ -583,7 +707,7 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async sidNoteOn(options) {
+    async sidNoteOn(options, pinnedFacade) {
         const voice = options.voice ?? 1;
         if (voice < 1 || voice > 3) {
             return { success: false, details: { message: "Voice must be 1..3" } };
@@ -616,7 +740,7 @@ export class C64Client {
         const base = 0xd400 + (voice - 1) * 7;
         const bytes = Buffer.from([freqLo, freqHi, pwLo, pwHi, ctrl, ad, sr]);
         try {
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             await facade.writeMemory(base, bytes);
             return { success: true };
         }
@@ -624,13 +748,13 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async sidNoteOff(voice) {
+    async sidNoteOff(voice, pinnedFacade) {
         if (voice < 1 || voice > 3) {
             return { success: false, details: { message: "Voice must be 1..3" } };
         }
         const ctrlAddr = 0xd400 + (voice - 1) * 7 + 4;
         try {
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             await facade.writeMemory(ctrlAddr, Buffer.from([0x00]));
             return { success: true };
         }
@@ -650,26 +774,26 @@ export class C64Client {
         const facade = await this.facadePromise;
         return facade.info();
     }
-    async pause() {
+    async pause(pinnedFacade) {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
+            if (!pinnedFacade && await this.shouldUseC64uMockBypass()) {
                 const res = await this.api.v1.machinePauseUpdate(":pause");
                 return { success: true, details: res.data };
             }
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.pause();
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
         }
     }
-    async resume() {
+    async resume(pinnedFacade) {
         try {
-            if (await this.shouldUseC64uMockBypass()) {
+            if (!pinnedFacade && await this.shouldUseC64uMockBypass()) {
                 const res = await this.api.v1.machineResumeUpdate(":resume");
                 return { success: true, details: res.data };
             }
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.resume();
         }
         catch (error) {
@@ -685,6 +809,95 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
+    /**
+     * Start from a clean machine state. C64U/U64 firmware exposes this only in
+     * the Tool Menu; U2-family firmware uses its equivalent REST reboot and
+     * VICE is restarted when it is managed by c64bridge.
+     */
+    async powerCycle() {
+        let menuOpened = false;
+        let cleanup;
+        let pinnedFacade;
+        try {
+            const facade = await this.facadePromise;
+            pinnedFacade = facade;
+            if (facade.type === "u2") {
+                const result = await facade.reboot();
+                return { ...result, details: { strategy: "reboot", result: result.details } };
+            }
+            if (facade.type === "vice") {
+                const result = await facade.powerCycle();
+                return { ...result, details: { strategy: "fresh_start", result: result.details } };
+            }
+            const endpoints = await this.getNativeEndpointCapabilities();
+            if (endpoints.machineInput !== "available") {
+                return {
+                    success: false,
+                    details: {
+                        code: "native_input_unavailable",
+                        message: "C64U/U64 Power Cycle requires machine:input and machine:menu_screen, which this firmware does not currently expose.",
+                        fallback: "Use c64_system reboot if a firmware reboot is acceptable, or power cycle from the device itself.",
+                    },
+                };
+            }
+            const menuResult = await facade.menuButton();
+            if (!menuResult.success) {
+                throw new Error("Unable to open the Ultimate menu for power cycling");
+            }
+            menuOpened = true;
+            const initial = await this.readVerifiedMenuScreen(facade, "open Ultimate menu");
+            await this.requirePowerCycleInput(facade, ["f1"]);
+            await this.readVerifiedMenuScreen(facade, "open Tool Menu", "TOOL MENU", initial);
+            await this.requirePowerCycleInput(facade, ["return"]);
+            let current = await this.readVerifiedMenuScreen(facade, "enter Tool Menu", "POWER CYCLE");
+            for (let index = 0; index < 4; index += 1) {
+                await this.requirePowerCycleInput(facade, ["cursor_up_down"]);
+                current = await this.readVerifiedMenuScreen(facade, `move to Power Cycle (${index + 1}/4)`, "POWER CYCLE", current);
+            }
+            if (!selectedMenuRowIncludes(current, "POWER CYCLE")) {
+                throw new Error("Unable to verify that POWER CYCLE is the selected Tool Menu item; final RETURN was not sent.");
+            }
+            await this.requirePowerCycleInput(facade, ["return"]);
+            return { success: true, details: { strategy: "tool_menu", verifiedMenu: "Tool Menu", selectedItem: "Power Cycle" } };
+        }
+        catch (error) {
+            if (menuOpened) {
+                try {
+                    cleanup = await pinnedFacade?.menuButton() ?? { success: false, details: "No facade available for menu cleanup" };
+                }
+                catch (cleanupError) {
+                    cleanup = { success: false, details: this.normaliseError(cleanupError) };
+                }
+            }
+            if (isMissingEndpoint(error)) {
+                return {
+                    success: false,
+                    details: {
+                        code: "native_menu_screen_unavailable",
+                        message: "C64U/U64 Power Cycle could not verify Tool Menu navigation because machine:menu_screen is unavailable.",
+                        fallback: "Use c64_system reboot if a firmware reboot is acceptable, or power cycle from the device itself.",
+                    },
+                };
+            }
+            return { success: false, details: { error: this.normaliseError(error), cleanup: cleanup ?? { success: false, details: "menu cleanup was not attempted" } } };
+        }
+    }
+    async requirePowerCycleInput(facade, inputs) {
+        await facade.sendInputEvents({ events: [{ kind: "keyboard", inputs, transition: "tap" }] });
+    }
+    async readVerifiedMenuScreen(facade, phase, requiredText, previous) {
+        const matrix = await facade.readMenuScreen();
+        if (matrix.length === 0) {
+            throw new Error(`Unable to ${phase}: machine:menu_screen returned an empty matrix`);
+        }
+        if (previous && Buffer.compare(Buffer.from(previous), Buffer.from(matrix)) === 0) {
+            throw new Error(`Unable to ${phase}: machine:menu_screen did not change after menu input`);
+        }
+        if (requiredText && !menuMatrixIncludes(matrix, requiredText)) {
+            throw new Error(`Unable to ${phase}: machine:menu_screen did not contain '${requiredText}'`);
+        }
+        return matrix;
+    }
     async menuButton() {
         try {
             if (await this.shouldUseC64uMockBypass()) {
@@ -698,6 +911,18 @@ export class C64Client {
             return { success: false, details: this.normaliseError(error) };
         }
     }
+    async readMenuScreen() {
+        const facade = await this.facadePromise;
+        return facade.readMenuScreen();
+    }
+    async getInputState() {
+        const facade = await this.facadePromise;
+        return facade.getInputState();
+    }
+    async sendInputEvents(batch) {
+        const facade = await this.facadePromise;
+        return facade.sendInputEvents(batch);
+    }
     async debugregRead() {
         try {
             if (await this.shouldUseC64uMockBypass()) {
@@ -1466,10 +1691,10 @@ export class C64Client {
      * raw binary bytes or JSON with a base64 payload.
      * Public to allow advanced polling and monitoring use cases.
      */
-    async readMemoryRaw(address, length) {
+    async readMemoryRaw(address, length, pinnedFacade) {
         validateMemoryRange(address, length);
         try {
-            const facade = await this.facadePromise;
+            const facade = pinnedFacade ?? await this.facadePromise;
             return await facade.readMemory(address, length);
         }
         catch (facadeError) {
@@ -1498,11 +1723,11 @@ export class C64Client {
      * Public so tools that need to drive cross-platform machine state (e.g.
      * keyboard-buffer injection) can avoid backend-specific paths.
      */
-    async writeMemoryRaw(address, bytes) {
+    async writeMemoryRaw(address, bytes, pinnedFacade) {
         if (!Number.isInteger(address) || address < 0 || address > 0xffff) {
             throw new Error("Address must be within 0x0000 - 0xFFFF");
         }
-        const facade = await this.facadePromise;
+        const facade = pinnedFacade ?? await this.facadePromise;
         const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
         validateMemoryRange(address, buf.length);
         await facade.writeMemory(address, buf);
@@ -1526,32 +1751,39 @@ export class C64Client {
             ? bytes
             : Buffer.from(bytes instanceof Uint8Array ? bytes : Uint8Array.from(bytes));
         if (data.length === 0) {
-            return;
+            return { delivered: 0 };
         }
         const chunkSize = Math.max(1, Math.min(10, options?.chunkSize ?? 10));
         const pollMs = Math.max(1, options?.drainPollMs ?? 8);
         const totalTimeoutMs = Math.max(50, options?.drainTimeoutMs ?? 2000);
-        const facade = await this.facadePromise;
+        const facade = options?.pinnedFacade ?? await this.facadePromise;
         const KEYD = 0x0277; // KERNAL keyboard buffer base
         const NDX = 0x00C6; // pending byte count
+        let delivered = 0;
         for (let offset = 0; offset < data.length; offset += chunkSize) {
             const slice = data.subarray(offset, Math.min(data.length, offset + chunkSize));
             // Write the bytes into the queue first so KERNAL never reads a stale
             // length+old-byte combination.
             await facade.writeMemory(KEYD, Buffer.from(slice));
             await facade.writeMemory(NDX, Buffer.from([slice.length]));
-            // Drain: wait for KERNAL to consume the queue. If the machine is paused
-            // or otherwise not running, give up after the timeout and continue —
-            // higher layers can decide whether that is a failure for their context.
+            // Drain before another write.  Overwriting a non-empty KERNAL queue loses
+            // user input, so a timeout is an explicit partial-delivery failure.
             const drainStart = Date.now();
+            let drained = false;
             while (Date.now() - drainStart < totalTimeoutMs) {
                 const ndx = await facade.readMemory(NDX, 1);
                 if ((ndx[0] ?? 0) === 0) {
+                    drained = true;
                     break;
                 }
                 await new Promise((resolve) => setTimeout(resolve, pollMs));
             }
+            delivered += slice.length;
+            if (!drained) {
+                throw new KeyboardQueueDrainTimeoutError(delivered, data.length, totalTimeoutMs);
+            }
         }
+        return { delivered };
     }
     async viceExitMonitor() {
         await this.withViceMonitor((client) => client.exitMonitor());
@@ -1563,6 +1795,9 @@ export class C64Client {
         const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
         await this.withViceMonitor((client) => client.memSet(address, buf));
     }
+    async viceJoyportSet(port, activeLowMask) {
+        await this.withViceMonitor((client) => client.joyportSet(port, activeLowMask));
+    }
     async viceMemGet(address, length) {
         const end = (address + length - 1) & 0xffff;
         return this.withViceMonitor((client) => client.memGet(address, end));
@@ -1761,7 +1996,7 @@ export class C64Client {
     }
     hzToSidFrequency(hz, system = "PAL") {
         const phi2 = system === "PAL" ? 985248 : 1022727;
-        const value = Math.round((hz * 65536) / phi2);
+        const value = Math.round((hz * 16777216) / phi2);
         // Clamp to 16-bit
         return Math.max(0, Math.min(0xffff, value));
     }
@@ -1942,7 +2177,7 @@ function buildSingleSpriteProgram(opts) {
     const source = lines.join("\n");
     return assemblyToPrg(source, { fileName: "sprite_gen.asm", loadAddress: 0x0801 });
 }
-function buildPetsciiScreenBasic(opts) {
+export function buildPetsciiScreenBasic(opts) {
     const border = toByte(opts.borderColor ?? 6); // default blue-ish
     const bg = toByte(opts.backgroundColor ?? 0); // default black
     // Clear screen, set colours, print text starting at 1,1
@@ -1951,7 +2186,7 @@ function buildPetsciiScreenBasic(opts) {
     const program = [
         `10 POKE 53280,${border}:POKE 53281,${bg}:PRINT CHR$(147)`,
         `20 PRINT "${sanitized}"`,
-        `30 GETA$:IFA$<>""THENEND:REM wait for key then end`,
+        `30 GETA$:IFA$=""THEN30:END:REM wait for key then end`,
     ].join("\n");
     return program;
 }
@@ -1977,11 +2212,11 @@ export function buildPrinterBasicProgram(opts) {
             ln += 10;
             continue;
         }
-        const chunks = chunkString(logical, 60);
+        const chunks = chunkString(logical, 45);
         for (let i = 0; i < chunks.length; i += 1) {
-            const chunk = escapeBasicQuotes(chunks[i]);
+            const chunk = basicStringExpression(chunks[i]);
             const tail = i < chunks.length - 1 ? ";" : ""; // avoid CR between chunks within the same logical line
-            lines.push(`${ln} PRINT#1,"${chunk}"${tail}`);
+            lines.push(`${ln} PRINT#1,${chunk}${tail}`);
             ln += 10;
         }
     }
@@ -2005,9 +2240,10 @@ function chunkString(input, maxLen) {
     }
     return parts;
 }
-function escapeBasicQuotes(input) {
-    // In Commodore BASIC, embed a double quote by doubling it
-    return input.replace(/"/g, '""');
+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);");
 }
 export function buildCommodoreBitmapBasicProgram(opts) {
     const repeats = Math.max(1, Math.floor(opts.repeats ?? 1));

package/dist/config.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "fs";
 import { dirname, join } from "path";
+import os from "node:os";
 import { fileURLToPath } from "url";
 const DEFAULT_HOST = "c64u";
 const DEFAULT_PORT = 80;
@@ -8,16 +9,16 @@ const DEFAULT_CONFIG = {
     baseUrl: buildBaseUrl(DEFAULT_HOST, DEFAULT_PORT),
     c64_port: DEFAULT_PORT,
     vicePrewarm: false,
+    backendConfig: {},
 };
-let cachedConfig = null;
 export function loadConfig() {
-    if (cachedConfig) {
-        return cachedConfig;
-    }
     const configPath = process.env.C64BRIDGE_CONFIG;
-    const repoConfigPath = join(dirname(fileURLToPath(import.meta.url)), "..", ".c64bridge.json");
-    const homeConfigPath = process.env.HOME ? `${process.env.HOME}/.c64bridge.json` : null;
-    const candidatePaths = [configPath, repoConfigPath, homeConfigPath];
+    const cwdConfigPath = join(process.cwd(), ".c64bridge.json");
+    const homeConfigPath = join(os.homedir(), ".c64bridge.json");
+    // Legacy package-adjacent config is deliberately last: it is useful for
+    // source checkouts but must never override a project or user config.
+    const legacyPackageConfigPath = join(dirname(fileURLToPath(import.meta.url)), "..", ".c64bridge.json");
+    const candidatePaths = [configPath, cwdConfigPath, homeConfigPath, legacyPackageConfigPath];
     let rawConfig;
     for (const candidatePath of candidatePaths) {
         if (!candidatePath) {
@@ -29,21 +30,27 @@ export function loadConfig() {
         }
         catch (error) {
             if (error.code !== "ENOENT") {
-                throw error;
+                // Deliberately omit file contents/credentials. Configuration mistakes
+                // should not prevent the MCP server from exposing a recoverable path.
+                console.error(`[c64bridge] ignoring configuration '${candidatePath}': ${error instanceof Error ? error.message : String(error)}`);
             }
         }
     }
     rawConfig ?? (rawConfig = {});
-    // New schema: prefer c64u.{host,port,baseUrl}; keep legacy fields as fallback
+    // 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 useU2 = process.env.C64_MODE?.trim().toLowerCase() === "u2";
+    const hardware = useU2 ? (u2 ?? c64u) : (c64u ?? u2);
     const vice = rawConfig?.vice;
-    const parsedC64uHost = parseEndpoint(configuredString(c64u?.host));
-    const parsedC64uHostname = parseEndpoint(configuredString(c64u?.hostname));
+    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(process.env.C64U_HOST));
+    const parsedEnvHost = parseEndpoint(configuredString(useU2 ? process.env.U2_HOST ?? process.env.C64U_HOST : process.env.C64U_HOST));
     const parsedBaseOverrides = [
-        parseEndpoint(normaliseBaseUrl(c64u?.baseUrl)),
+        parseEndpoint(normaliseBaseUrl(hardware?.baseUrl)),
         parseEndpoint(normaliseBaseUrl(rawConfig?.baseUrl)),
     ];
     const hostCandidates = [
@@ -55,9 +62,9 @@ export function loadConfig() {
         ...parsedBaseOverrides.map((entry) => entry.hostname),
     ];
     const portCandidates = [
-        configuredPort(process.env.C64U_PORT),
+        configuredPort(useU2 ? process.env.U2_PORT ?? process.env.C64U_PORT : process.env.C64U_PORT),
         parsedEnvHost.port,
-        configuredPort(c64u?.port),
+        configuredPort(hardware?.port),
         parsedC64uHost.port,
         parsedC64uHostname.port,
         configuredPort(rawConfig?.c64_port),
@@ -74,10 +81,14 @@ export function loadConfig() {
         c64_host: hostWithPort,
         baseUrl,
         c64_port: port,
-        networkPassword: firstDefined(configuredString(process.env.C64U_PASSWORD), configuredString(c64u?.networkPassword), configuredString(rawConfig?.networkPassword)),
+        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 } : {}),
+        },
     };
-    cachedConfig = config;
     return config;
 }
 function configuredString(value) {
@@ -162,5 +173,6 @@ function formatHost(host) {
     return host;
 }
 export function __resetConfigCacheForTests() {
-    cachedConfig = null;
+    // Kept as a no-op compatibility hook: config is intentionally reloaded for
+    // each construction so startup and facade creation cannot disagree.
 }