c64bridge 1.0.4 → 1.0.6

package/dist/c64Client.js

@@ -11,7 +11,9 @@ 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 { assemblyToPrgDetailed, prgEntryAddress } from "./tools/translation/assembler.js";
+import { stripHexByteSeparators } from "./tools/hex.js";
+import { SIDWAVE_PLAY_ADDRESS } from "./sidwaveCompiler.js";
 import { petsciiToAscii, screenCodesToAscii } from "./petscii.js";
 import { resolveAddressSymbol } from "./knowledge.js";
 import { createAllFacades, createFacade, } from "./device.js";
@@ -32,6 +34,8 @@ export class KeyboardQueueDrainTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+/** JOYPORT_ID_IO_SIMULATION in joyport.h (the same in VICE 3.9 and 3.10). */
+const VICE_JOYPORT_IO_SIMULATION = 37;
 const C64U_SYSTEM_MODE_CATEGORY = "U64 Specific Settings";
 const C64U_SYSTEM_MODE_ITEM = "System Mode";
 // System Mode values that run the machine clock at the NTSC frequency
@@ -183,6 +187,8 @@ export class C64Client {
         this.greetingDd00Warmups = new Map();
         this.machineInputCapabilityProbes = new Map();
         this.c64uVideoCaptureSession = null;
+        /** VICE joyport device ids to restore when a joystick press ends. */
+        this.viceJoyportSavedDevice = new Map();
         this.activeType = "c64u";
         this.baseUrl = baseUrl;
         const headers = options.networkPassword ? { "X-Password": options.networkPassword } : undefined;
@@ -302,9 +308,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,15 +549,26 @@ 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 first assembled instruction.
      */
     async uploadAndRunAsm(program) {
         try {
-            const prg = assemblyToPrg(program);
+            const assembled = assemblyToPrgDetailed(program);
+            const prg = assembled.prg;
             if (prg.length < 2) {
                 return { success: false, details: { message: "Assembled program produced no output" } };
             }
-            const entryAddress = prg.readUInt16LE(0);
+            const entryAddress = assembled.entryAddress;
+            if (prg.readUInt16LE(0) === 0x0801 && prgEntryAddress(prg) === 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 +587,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 +666,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 +676,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 };
@@ -770,31 +769,65 @@ export class C64Client {
     async sidReset(hard = false) {
         try {
             const facade = await this.facadePromise;
+            // Unhooking a running SIDWAVE player is best-effort: a failed read must not stop the SID being silenced.
+            const stoppedSidwavePlayer = await this.stopSidwaveIrqPlayer(facade).catch(() => false);
             if (hard) {
                 const span = 0x19;
                 const ff = Buffer.alloc(span, 0xff);
                 const zz = Buffer.alloc(span, 0x00);
                 await facade.writeMemory(0xd400, ff);
                 await facade.writeMemory(0xd400, zz);
-                return { success: true };
+                return { success: true, ...(stoppedSidwavePlayer ? { details: { stoppedSidwavePlayer } } : {}) };
             }
             await facade.writeMemory(0xd404, Buffer.from([0x00]));
             await facade.writeMemory(0xd40b, Buffer.from([0x00]));
             await facade.writeMemory(0xd412, Buffer.from([0x00]));
             await facade.writeMemory(0xd418, Buffer.from([0x00]));
-            return { success: true };
+            return { success: true, ...(stoppedSidwavePlayer ? { details: { stoppedSidwavePlayer } } : {}) };
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
         }
     }
+    /**
+     * A SIDWAVE PRG keeps playing from the IRQ after the SID is silenced. Its
+     * IRQ handler is "JSR play / JMP $EA31", and its play vector at $0813 is
+     * "JMP play". When $0314 points at such a handler, point it back at the
+     * KERNAL handler so silencing sticks; other programs' IRQ handlers are left
+     * alone. Both vector bytes go in one write.
+     */
+    async stopSidwaveIrqPlayer(facade) {
+        const vector = await facade.readMemory(0x0314, 2);
+        const handler = (vector[0] ?? 0) | ((vector[1] ?? 0) << 8);
+        // A handler too close to $FFFF cannot hold the 6-byte SIDWAVE handler (and the read would cross $FFFF).
+        if (handler === 0xea31 || handler > 0xfffa)
+            return false;
+        const code = await facade.readMemory(handler, 6);
+        const playVector = await facade.readMemory(SIDWAVE_PLAY_ADDRESS, 3);
+        const isSidwaveHandler = code[0] === 0x20 && code[3] === 0x4c && code[4] === 0x31 && code[5] === 0xea
+            && playVector[0] === 0x4c && playVector[1] === code[1] && playVector[2] === code[2];
+        if (!isSidwaveHandler)
+            return false;
+        await facade.writeMemory(0x0314, Uint8Array.of(0x31, 0xea));
+        return true;
+    }
     async sidNoteOn(options, pinnedFacade) {
         const voice = options.voice ?? 1;
         if (voice < 1 || voice > 3) {
             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;
+        // The 16-bit frequency register tops out at about 3848 Hz on PAL and 3995 Hz
+        // on NTSC (B7 is already above the PAL limit); report it instead of clamping.
+        const maxHz = (0xffff * (system === "PAL" ? 985248 : 1022727)) / 16777216;
+        if (hz > maxHz + 0.5) {
+            return {
+                success: false,
+                details: { message: `${options.note ?? `${hz} Hz`} (${hz.toFixed(1)} Hz) is above the SID's highest ${system} frequency of ${maxHz.toFixed(1)} Hz` },
+            };
+        }
         const freq16 = this.hzToSidFrequency(hz, system);
         const freqLo = freq16 & 0xff;
         const freqHi = (freq16 >> 8) & 0xff;
@@ -857,10 +890,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 +899,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 +1006,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 +1027,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 +1036,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 +1096,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 };
@@ -2001,6 +2010,43 @@ export class C64Client {
     async viceJoyportSet(port, activeLowMask) {
         await this.withViceMonitor((client) => client.joyportSet(port, activeLowMask));
     }
+    /**
+     * Hold joystick lines on a VICE control port. Binary Monitor command 0xA2
+     * only drives VICE's "I/O simulation" joyport device, so that device is
+     * attached for the duration of the press and the previous device is
+     * restored on release. The device reads bits 5-7 as low, which the
+     * keyboard scan sees as extra keys, so it must not stay attached.
+     *
+     * While a press is held: on port 1 the keyboard scan sees phantom keys
+     * (for example SHIFT+C=, which toggles the character set); on port 2,
+     * $DC00 reads with bits 5-7 clear (up = $1E where a joystick gives $7E),
+     * so programs that compare the whole byte will not see the input.
+     */
+    async viceJoystickPress(port, activeLowMask) {
+        await this.withViceMonitor(async (client) => {
+            const resource = `JoyPort${port}Device`;
+            // Read the device every time: after a VICE restart the saved state is stale.
+            const current = await client.resourceGet(resource);
+            const currentId = current.type === "int" ? current.value : Number(current.value);
+            if (currentId !== VICE_JOYPORT_IO_SIMULATION) {
+                this.viceJoyportSavedDevice.set(port, currentId);
+                await client.resourceSet(resource, VICE_JOYPORT_IO_SIMULATION);
+            }
+            // Attaching the device clears its lines to 0 (everything pressed), so set them in the same monitor session.
+            await client.joyportSet(port, activeLowMask);
+        });
+    }
+    /** Release a VICE control port and restore the joyport device it had before the press. */
+    async viceJoystickRelease(port) {
+        await this.withViceMonitor(async (client) => {
+            await client.joyportSet(port, 0xff);
+            const saved = this.viceJoyportSavedDevice.get(port);
+            if (saved !== undefined) {
+                await client.resourceSet(`JoyPort${port}Device`, saved);
+                this.viceJoyportSavedDevice.delete(port);
+            }
+        });
+    }
     async viceMemGet(address, length) {
         const end = (address + length - 1) & 0xffff;
         return this.withViceMonitor((client) => client.memGet(address, end));
@@ -2184,8 +2230,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");
         }
@@ -2300,86 +2345,6 @@ function buildGreetingScreenRam(message) {
     writeScreenLine(screenRam, 3, "READY.");
     return screenRam;
 }
-function buildSingleSpriteProgram(opts) {
-    const index = Math.max(0, Math.min(7, opts.spriteIndex ?? 0));
-    const mx = Math.max(0, Math.min(511, opts.x ?? 100));
-    const xLo = mx & 0xff;
-    const xMsbBit = (mx & 0x100) ? (1 << index) : 0;
-    const y = toByte(opts.y, 100);
-    const color = toByte(opts.color, 1);
-    const multicolour = !!opts.multicolour;
-    const spriteData = Buffer.from(opts.spriteBytes);
-    if (spriteData.length !== 63) {
-        throw new Error("spriteBytes must be exactly 63 bytes");
-    }
-    // We'll assemble a tiny machine-code program that:
-    // - Copies 63 bytes to a safe sprite data page ($2000 by default)
-    // - Sets screen memory base to $0400, sprite pointer to point into $2000
-    // - Positions and enables the sprite
-    // - Loops forever
-    // This avoids relying on KERNAL calls and works from a cold start.
-    const SPRITE_BASE = 0x2000; // must be 64-byte aligned
-    const POINTER_PAGE = 0x07f8 + index; // sprite pointer table location
-    const pointerValue = (SPRITE_BASE >> 6) & 0xff;
-    // Place code starting at $0801 so it runs as a program via SYS.
-    // We'll create an assembler source and reuse assemblyToPrg.
-    const lines = [];
-    lines.push("* = $0801");
-    // Tiny BASIC loader header not needed; we will use pure ML and jump via RESET runner which executes by SYS 2061
-    // Build code at $0810 to avoid conflicting with potential KERNAL vectors
-    lines.push("* = $0810");
-    lines.push("\nstart:");
-    // Copy 63 bytes from inlined table to SPRITE_BASE
-    lines.push("  LDY #$00");
-    lines.push("copy_loop:");
-    lines.push("  LDA sprite_data,Y");
-    lines.push(`  STA $${hex16(SPRITE_BASE)},Y`);
-    lines.push("  INY");
-    lines.push("  CPY #$3F");
-    lines.push("  BNE copy_loop");
-    // Set sprite pointer, color, coordinates, enable
-    lines.push(`  LDA #$${pointerValue.toString(16).toUpperCase().padStart(2, "0")}`);
-    lines.push(`  STA $${(POINTER_PAGE).toString(16).toUpperCase()}`);
-    lines.push(`  LDA #$${color.toString(16).toUpperCase().padStart(2, "0")}`);
-    lines.push(`  STA $${hex16(0xD027 + index)}`);
-    lines.push(`  LDA #$${xLo.toString(16).toUpperCase().padStart(2, "0")}`);
-    lines.push(`  STA $${(0xD000 + index * 2).toString(16).toUpperCase()}`);
-    lines.push(`  LDA #$${y.toString(16).toUpperCase().padStart(2, "0")}`);
-    lines.push(`  STA $${(0xD001 + index * 2).toString(16).toUpperCase()}`);
-    // MSB X if needed
-    if (xMsbBit) {
-        const bit = xMsbBit;
-        lines.push(`  LDA $D010`);
-        lines.push(`  ORA #$${bit.toString(16).toUpperCase().padStart(2, "0")}`);
-        lines.push(`  STA $D010`);
-    }
-    // Multicolour toggle per-sprite
-    if (multicolour) {
-        const bit = 1 << index;
-        lines.push(`  LDA $D01C`);
-        lines.push(`  ORA #$${bit.toString(16).toUpperCase().padStart(2, "0")}`);
-        lines.push(`  STA $D01C`);
-    }
-    // Enable sprite
-    {
-        const bit = 1 << index;
-        lines.push(`  LDA $D015`);
-        lines.push(`  ORA #$${bit.toString(16).toUpperCase().padStart(2, "0")}`);
-        lines.push(`  STA $D015`);
-    }
-    // Idle loop
-    lines.push("forever: JMP forever");
-    // Sprite data table
-    lines.push("\nsprite_data:");
-    for (let i = 0; i < 63; i += 3) {
-        const a = spriteData[i] ?? 0;
-        const b = spriteData[i + 1] ?? 0;
-        const c = spriteData[i + 2] ?? 0;
-        lines.push(`  .byte $${hex2(a)},$${hex2(b)},$${hex2(c)}`);
-    }
-    const source = lines.join("\n");
-    return assemblyToPrg(source, { fileName: "sprite_gen.asm", loadAddress: 0x0801 });
-}
 export function buildPetsciiScreenBasic(opts) {
     const border = toByte(opts.borderColor ?? 6); // default blue-ish
     const bg = toByte(opts.backgroundColor ?? 0); // default black
@@ -2415,9 +2380,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;
@@ -2432,21 +2400,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));
@@ -2544,9 +2544,3 @@ export function buildCommodoreDllBasicProgram(opts) {
     lines.push(`${ln} CLOSE1`);
     return lines.join("\n");
 }
-function hex2(n) {
-    return (n & 0xff).toString(16).toUpperCase().padStart(2, "0");
-}
-function hex16(n) {
-    return (n & 0xffff).toString(16).toUpperCase().padStart(4, "0");
-}

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,120 @@ 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);
+    // When the host comes from a baseUrl, keep its scheme and path (for example
+    // https://proxy/c64u), applying only an explicit port override. An explicit
+    // host builds http://host:port as documented.
+    const baseOnly = parsedBaseOverrides.find((entry) => entry.hostname !== undefined);
+    const explicitHost = firstDefined(...hostCandidates.slice(0, -parsedBaseOverrides.length));
+    const explicitPort = firstDefined(...portCandidates.slice(0, -parsedBaseOverrides.length));
+    const keepBaseUrl = baseOnly?.fullUrl !== undefined && explicitHost === undefined;
+    const schemeDefaultPort = keepBaseUrl && baseOnly.fullUrl.startsWith("https:") ? 443 : DEFAULT_PORT;
+    const port = firstDefined(...portCandidates) ?? schemeDefaultPort;
     const hostLabel = formatHost(host);
-    const hostWithPort = port === DEFAULT_PORT ? hostLabel : `${hostLabel}:${port}`;
-    const config = {
-        c64_host: hostWithPort,
+    let baseUrl = buildBaseUrl(host, port);
+    if (keepBaseUrl) {
+        const url = new URL(baseOnly.fullUrl);
+        if (explicitPort !== undefined)
+            url.port = String(explicitPort);
+        baseUrl = stripTrailingSlash(url.toString());
+    }
+    return {
+        host,
+        port,
         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 } : {}),
-        },
+        c64_host: port === schemeDefaultPort ? 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;
@@ -144,7 +196,9 @@ function parseEndpoint(value) {
         const hostname = url.hostname || undefined;
         const port = url.port ? configuredPort(url.port) : undefined;
         const baseUrl = stripTrailingSlash(`${url.protocol}//${url.host}`);
-        return { hostname, port, baseUrl };
+        // Scheme and path prefix kept, for an Ultimate reached through a reverse proxy.
+        const fullUrl = stripTrailingSlash(`${url.protocol}//${url.host}${url.pathname}`);
+        return { hostname, port, baseUrl, fullUrl };
     }
     catch {
         return {};