c64bridge 1.0.2 → 1.0.4

package/dist/audio/record_and_analyze_audio.js

@@ -1,9 +1,13 @@
 import { parseSidwave, midiToHz } from "../sidwave.js";
-export async function recordAndAnalyzeAudio(params) {
-    const duration = Math.max(0.5, Math.min(120, Number(params.durationSeconds || 0)));
+export function normalizeAudioDuration(durationSeconds) {
+    const duration = Number(durationSeconds);
     if (!Number.isFinite(duration)) {
         throw new Error("durationSeconds must be a number");
     }
+    return Math.max(0.5, Math.min(120, duration));
+}
+export async function recordAndAnalyzeAudio(params) {
+    const duration = normalizeAudioDuration(params.durationSeconds);
     // Capture PCM from default microphone using naudiodon (PortAudio)
     const sampleRate = 44100;
     const channelCount = 1;
@@ -52,9 +56,49 @@ export async function recordAndAnalyzeAudio(params) {
     });
     const pcm16 = Buffer.concat(chunks);
     const float32 = convertInt16ToFloat32(pcm16);
-    const analysis = await analyzePcm(float32, sampleRate, params.expectedSidwave);
+    const analysis = await analyzePcm(float32, sampleRate, "microphone", params.expectedSidwave);
     return analysis;
 }
+/**
+ * Analyzes interleaved 16-bit stereo PCM captured from the Ultimate audio stream.
+ *
+ * The stream carries a large constant offset per channel even when silent
+ * (for example left 26900, right 20000). The mean of each channel is removed
+ * before analysis; otherwise the RMS measures the offset instead of the audio level.
+ * Analyze channel energy separately, since a mono mix can cancel opposite-phase
+ * audio and falsely verify silence. Pitch and level follow the louder channel in each window.
+ */
+export async function analyzeStereoStream(interleaved, sampleRate, expectedSidwave) {
+    const [left, right] = stereoToCenteredChannels(interleaved);
+    return analyzePcm(left, sampleRate, "ultimate-stream", expectedSidwave, right);
+}
+function stereoToCenteredChannels(interleaved) {
+    const frames = Math.floor(interleaved.length / 2);
+    const left = new Float32Array(frames);
+    const right = new Float32Array(frames);
+    if (frames === 0) {
+        return [left, right];
+    }
+    let leftSum = 0;
+    let rightSum = 0;
+    for (let i = 0; i < frames; i += 1) {
+        leftSum += interleaved[i * 2];
+        rightSum += interleaved[i * 2 + 1];
+    }
+    const leftMean = leftSum / frames;
+    const rightMean = rightSum / frames;
+    for (let i = 0; i < frames; i += 1) {
+        left[i] = (interleaved[i * 2] - leftMean) / 32768;
+        right[i] = (interleaved[i * 2 + 1] - rightMean) / 32768;
+    }
+    return [left, right];
+}
+export function stereoToCenteredMono(interleaved) {
+    const [left, right] = stereoToCenteredChannels(interleaved);
+    for (let i = 0; i < left.length; i += 1)
+        left[i] = (left[i] + right[i]) / 2;
+    return left;
+}
 function convertInt16ToFloat32(buf) {
     const len = Math.floor(buf.length / 2);
     const out = new Float32Array(len);
@@ -64,7 +108,7 @@ function convertInt16ToFloat32(buf) {
     }
     return out;
 }
-async function analyzePcm(signal, sampleRate, expectedSidwave) {
+async function analyzePcm(signal, sampleRate, source, expectedSidwave, secondChannel) {
     let Pitchfinder;
     let Meyda = null;
     try {
@@ -87,13 +131,28 @@ async function analyzePcm(signal, sampleRate, expectedSidwave) {
     const yin = Pitchfinder.YIN({ sampleRate });
     const frames = [];
     for (let i = 0; i + windowSize <= signal.length; i += hopSize) {
-        const win = signal.subarray(i, i + windowSize);
-        const rms = computeRms(win, Meyda, sampleRate, windowSize);
+        let win = signal.subarray(i, i + windowSize);
+        let rms = computeRms(win, Meyda, sampleRate, windowSize);
+        if (secondChannel) {
+            const otherWin = secondChannel.subarray(i, i + windowSize);
+            const otherRms = computeRms(otherWin, Meyda, sampleRate, windowSize);
+            if (otherRms > rms) {
+                rms = otherRms;
+                win = otherWin;
+            }
+        }
         const minRms = 0.01; // simple noise gate
         let freq = null;
         if (rms >= minRms) {
             try {
-                const f = yin(win);
+                // pitchfinder's YIN seeds its difference sum with 1, making low-level
+                // normalized PCM produce spurious ultrasonic pitches. Normalize only
+                // the detector input; RMS and the noise gate retain the original level.
+                let peak = 0;
+                for (const value of win)
+                    peak = Math.max(peak, Math.abs(value));
+                const pitchInput = peak > 0 ? Float32Array.from(win, (value) => value / peak) : win;
+                const f = yin(pitchInput);
                 if (Number.isFinite(f) && f > 20 && f < 8000)
                     freq = f;
             }
@@ -175,7 +234,7 @@ async function analyzePcm(signal, sampleRate, expectedSidwave) {
     return {
         sidwave: 1.0,
         analysis: {
-            source: "microphone",
+            source,
             durationSeconds: signal.length / sampleRate,
             voices,
             global_metrics: {
@@ -189,7 +248,7 @@ async function analyzePcm(signal, sampleRate, expectedSidwave) {
 }
 // Test-only helper: bypasses microphone capture and analyzes provided PCM buffer.
 export async function analyzePcmForTest(signal, sampleRate, expectedSidwave) {
-    return analyzePcm(signal, sampleRate, expectedSidwave);
+    return analyzePcm(signal, sampleRate, "microphone", expectedSidwave);
 }
 function groupSegments(frames, _sampleRate) {
     const segments = [];
@@ -286,10 +345,19 @@ function noteNameToMidiSafe(note) {
 function computeRms(win, Meyda, sampleRate, bufferSize) {
     try {
         if (Meyda && typeof Meyda.extract === "function") {
-            const features = Meyda.extract(["rms"], win, { sampleRate, bufferSize });
-            const val = Number(features?.rms ?? 0);
-            if (Number.isFinite(val))
-                return val;
+            // Rectangular windows give plain sample RMS. Restore Meyda's shared setting
+            // synchronously so other consumers retain their window configuration.
+            const previousWindow = Meyda.windowingFunction;
+            try {
+                Meyda.windowingFunction = "rect";
+                const features = Meyda.extract(["rms"], win, { sampleRate, bufferSize });
+                const val = Number(features?.rms ?? 0);
+                if (Number.isFinite(val))
+                    return val;
+            }
+            finally {
+                Meyda.windowingFunction = previousWindow;
+            }
         }
     }
     catch { }

package/dist/c64Client.js

@@ -6,7 +6,9 @@ Licensed under the GNU General Public License v2.0 or later.
 See <https://www.gnu.org/licenses/> for details.
 */
 import { Buffer } from "node:buffer";
+import { execFile } from "node:child_process";
 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";
@@ -16,6 +18,7 @@ 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 { analyzeStereoStream, normalizeAudioDuration, recordAndAnalyzeAudio, } from "./audio/record_and_analyze_audio.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
@@ -29,6 +32,84 @@ export class KeyboardQueueDrainTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+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
+// (VIDEO_FMT_NTSC_FREQ in the firmware colour timings); the other values use the PAL clock.
+const NTSC_CLOCK_SYSTEM_MODES = new Set(["NTSC", "PAL-60", "PAL-60/L"]);
+/**
+ * Reads the current System Mode from a config response. The firmware answers
+ * `{ "<category>": { "<item>": { "current": "PAL", ... } } }`; a bare `{ value }` is also accepted.
+ */
+export function readSystemMode(response) {
+    const record = (value) => value && typeof value === "object" ? value : null;
+    const category = record(record(response)?.[C64U_SYSTEM_MODE_CATEGORY]);
+    const node = category?.[C64U_SYSTEM_MODE_ITEM] ?? response;
+    const raw = typeof node === "string" ? node : record(node)?.current ?? record(node)?.value;
+    return typeof raw === "string" && raw.trim() !== "" ? raw.trim() : null;
+}
+export function audioSampleRateForSystemMode(mode) {
+    return mode !== null && NTSC_CLOCK_SYSTEM_MODES.has(mode.toUpperCase())
+        ? C64U_NTSC_AUDIO_SAMPLE_RATE
+        : C64U_PAL_AUDIO_SAMPLE_RATE;
+}
+// A partial capture must still hold one analysis window (2048 stereo frames).
+const MIN_PARTIAL_AUDIO_VALUES = 2048 * 2;
+const STREAM_HOST_RESOLVE_ERROR = "Network Host Resolve Error";
+const NEIGHBOR_PRIME_TIMEOUT_MS = 4000;
+/**
+ * The Ultimate firmware resolves a unicast stream target through its ARP cache
+ * and answers 404 "Network Host Resolve Error" immediately when the client is
+ * not cached. Accepts both a thrown HTTP error and an unsuccessful result.
+ */
+function isStreamHostResolveFailure(failure) {
+    const body = axios.isAxiosError(failure) ? failure.response?.data : failure;
+    if (body === undefined || body === null) {
+        return false;
+    }
+    try {
+        return JSON.stringify(body).includes(STREAM_HOST_RESOLVE_ERROR);
+    }
+    catch {
+        return false;
+    }
+}
+/** Hostnames come from configuration; accept only plain host or address characters so they cannot act as ping options. */
+export function pingableHost(hostname) {
+    const host = hostname.replace(/^\[(.*)\]$/, "$1");
+    return /^[A-Za-z0-9][A-Za-z0-9._:%-]*$/.test(host) ? host : null;
+}
+/** True when `host` is an address of one of this machine's network interfaces. */
+export function isLocalAddress(host) {
+    const wanted = host.replace(/^\[(.*)\]$/, "$1").toLowerCase();
+    return Object.values(networkInterfaces()).some((entries) => (entries ?? []).some((entry) => entry.address.toLowerCase() === wanted));
+}
+/** Host part of a `host:port` stream target, or null when it cannot be split. */
+export function streamTargetHost(target) {
+    const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(target);
+    if (bracketed) {
+        return bracketed[1];
+    }
+    const colon = target.indexOf(":");
+    if (colon === -1) {
+        return target.length > 0 ? target : null;
+    }
+    // Exactly one colon separates host and port; several colons are a bare IPv6 address.
+    if (colon !== target.lastIndexOf(":")) {
+        return target;
+    }
+    return colon > 0 ? target.slice(0, colon) : null;
+}
+function neighborPrimeArgs(host) {
+    switch (process.platform) {
+        case "win32":
+            return ["-n", "1", "-w", "2000", host];
+        case "darwin":
+            return ["-c", "1", "-t", "2", host];
+        default:
+            return ["-c", "1", "-W", "2", host];
+    }
+}
 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
@@ -1026,7 +1107,7 @@ export class C64Client {
     async streamStart(stream, ip) {
         try {
             const facade = await this.facadePromise;
-            return await facade.streamStart(stream, ip);
+            return await this.startStreamResolvingHost(facade, stream, ip);
         }
         catch (error) {
             return { success: false, details: this.normaliseError(error) };
@@ -1060,6 +1141,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)),
@@ -1074,6 +1158,25 @@ export class C64Client {
         }
         return this.captureC64uAudioSamples(facade, requestedPairs);
     }
+    /**
+     * Records and analyzes audio. On the C64 Ultimate the PCM comes from the
+     * device audio stream; other backends have no stream, so the host microphone is used.
+     */
+    async recordAndAnalyzeAudio(params) {
+        const durationSeconds = normalizeAudioDuration(params.durationSeconds);
+        const facade = await this.facadePromise;
+        if (facade.type !== "c64u") {
+            return recordAndAnalyzeAudio(params);
+        }
+        const sampleRateHz = await this.getC64uAudioSampleRate(facade);
+        const samplePairs = Math.ceil(durationSeconds * sampleRateHz);
+        const capture = await this.captureC64uAudioSamples(facade, samplePairs, {
+            timeoutMs: Math.ceil(durationSeconds * 1500) + 2000,
+            sampleRateHz,
+            acceptPartial: true,
+        });
+        return analyzeStereoStream(capture.samples, capture.sampleRateHz, params.expectedSidwave);
+    }
     async configsList() {
         const facade = await this.facadePromise;
         return facade.configsList();
@@ -1223,7 +1326,7 @@ export class C64Client {
         try {
             await this.bindCaptureSocket(socket, bindAddress);
             const target = this.socketEndpoint(socket, bindAddress);
-            await this.ensureStreamSuccess(await facade.streamStart("video", target), "start video stream");
+            await this.ensureStreamSuccess(await this.startStreamResolvingHost(facade, "video", target), "start video stream");
             const frames = await new Promise((resolve, reject) => {
                 const timeoutMs = Math.max(1500, count * 750);
                 const timer = setTimeout(() => {
@@ -1313,7 +1416,7 @@ export class C64Client {
             this.rejectC64uVideoCaptureWaiters(session, err);
         });
         try {
-            await this.ensureStreamSuccess(await facade.streamStart("video", target), "start video stream");
+            await this.ensureStreamSuccess(await this.startStreamResolvingHost(facade, "video", target), "start video stream");
         }
         catch (error) {
             session.closed = true;
@@ -1447,44 +1550,76 @@ export class C64Client {
         }
         throw lastError instanceof Error ? lastError : new Error(String(lastError ?? "VICE display capture failed"));
     }
-    async captureC64uAudioSamples(facade, samplePairs) {
+    async captureC64uAudioSamples(facade, samplePairs, options) {
         const host = new URL(this.baseUrl).hostname;
         const bindAddress = await this.resolveLocalCaptureAddress(host);
         const socket = createSocket("udp4");
         const chunks = [];
         let collectedValues = 0;
-        let stopError = null;
+        const neededValues = samplePairs * 2;
+        let captureError = null;
+        let captureSettled = false;
+        let notifyCapture = () => { };
+        let socketBound = false;
+        let streamAttempted = false;
+        let failed = false;
+        // The firmware can emit UDP before its REST response reaches us. Listen
+        // before starting, and cap collection even while start/config/stop requests are pending.
+        const onMessage = (msg) => {
+            if (captureSettled || captureError || collectedValues >= neededValues)
+                return;
+            try {
+                const packet = parseAudioPacket(msg);
+                if (packet.samples.length % 2 !== 0)
+                    throw new Error("Audio packet contains an incomplete stereo sample pair");
+                const samples = packet.samples.subarray(0, neededValues - collectedValues);
+                chunks.push(samples);
+                collectedValues += samples.length;
+            }
+            catch (error) {
+                captureError = error instanceof Error ? error : new Error(String(error));
+            }
+            notifyCapture();
+        };
+        const onError = (error) => {
+            captureError = error;
+            notifyCapture();
+        };
+        socket.on("message", onMessage);
+        socket.on("error", onError);
         try {
             await this.bindCaptureSocket(socket, bindAddress);
+            socketBound = true;
             const target = this.socketEndpoint(socket, bindAddress);
-            await this.ensureStreamSuccess(await facade.streamStart("audio", target), "start audio stream");
-            const neededValues = samplePairs * 2;
+            streamAttempted = true;
+            await this.ensureStreamSuccess(await this.startStreamResolvingHost(facade, "audio", target), "start audio stream");
             await new Promise((resolve, reject) => {
-                const timeoutMs = Math.max(1000, Math.ceil(samplePairs / 192) * 500);
+                const timeoutMs = options?.timeoutMs ?? Math.max(1000, Math.ceil(samplePairs / 192) * 500);
                 const timer = setTimeout(() => {
+                    captureSettled = true;
+                    // UDP drops packets, so a count-based capture can fall short. Analysis accepts what arrived.
+                    if (options?.acceptPartial && collectedValues >= MIN_PARTIAL_AUDIO_VALUES) {
+                        resolve();
+                        return;
+                    }
                     reject(new Error(`Timed out after ${timeoutMs}ms while capturing ${samplePairs} audio sample pair(s)`));
                 }, timeoutMs);
-                socket.on("message", (msg) => {
-                    try {
-                        const packet = parseAudioPacket(Buffer.from(msg));
-                        chunks.push(packet.samples);
-                        collectedValues += packet.samples.length;
-                        if (collectedValues >= neededValues) {
-                            clearTimeout(timer);
-                            resolve();
-                        }
-                    }
-                    catch (error) {
+                notifyCapture = () => {
+                    if (captureSettled)
+                        return;
+                    if (captureError || collectedValues >= neededValues) {
+                        captureSettled = true;
                         clearTimeout(timer);
-                        reject(error);
+                        if (captureError)
+                            reject(captureError);
+                        else
+                            resolve();
                     }
-                });
-                socket.once("error", (error) => {
-                    clearTimeout(timer);
-                    reject(error);
-                });
+                };
+                notifyCapture();
             });
-            const samples = new Int16Array(samplePairs * 2);
+            const capturedPairs = Math.min(samplePairs, Math.floor(collectedValues / 2));
+            const samples = new Int16Array(capturedPairs * 2);
             let offset = 0;
             for (const chunk of chunks) {
                 const remaining = samples.length - offset;
@@ -1497,32 +1632,37 @@ export class C64Client {
             return {
                 backend: "c64u",
                 channels: 2,
-                sampleRateHz: await this.getC64uAudioSampleRate(facade),
-                samplePairs,
+                sampleRateHz: options?.sampleRateHz ?? await this.getC64uAudioSampleRate(facade),
+                samplePairs: capturedPairs,
                 samples,
             };
         }
+        catch (error) {
+            failed = true;
+            throw error;
+        }
         finally {
+            captureSettled = true;
+            notifyCapture = () => { };
+            socket.off("message", onMessage);
+            if (socketBound)
+                socket.close();
             try {
-                await this.ensureStreamSuccess(await facade.streamStop("audio"), "stop audio stream");
+                if (streamAttempted)
+                    await this.ensureStreamSuccess(await facade.streamStop("audio"), "stop audio stream");
             }
             catch (error) {
-                stopError = error instanceof Error ? error : new Error(String(error));
-            }
-            socket.close();
-            if (stopError) {
-                throw stopError;
+                // Preserve the capture/start error, while still reporting cleanup diagnostics.
+                if (!failed)
+                    throw error;
+                writeDiagnosticEvent("audio_capture_stop_failed", { error: this.normaliseError(error) });
             }
         }
     }
     async getC64uAudioSampleRate(facade) {
         try {
-            const response = await facade.configGet("Video", "Mode");
-            const raw = response?.value ?? response;
-            const mode = typeof raw === "string" ? raw.trim().toUpperCase() : "";
-            if (mode.includes("NTSC")) {
-                return C64U_NTSC_AUDIO_SAMPLE_RATE;
-            }
+            const response = await facade.configGet(C64U_SYSTEM_MODE_CATEGORY, C64U_SYSTEM_MODE_ITEM);
+            return audioSampleRateForSystemMode(readSystemMode(response));
         }
         catch {
             // Fall back to PAL below.
@@ -1568,6 +1708,69 @@ export class C64Client {
         }
         return `${bindAddress}:${address.port}`;
     }
+    /**
+     * Starts a stream. When the device answers "Network Host Resolve Error", sends
+     * one ICMP echo to the device so it has to address a reply to this host, then
+     * retries the start once.
+     */
+    async startStreamResolvingHost(facade, stream, target) {
+        let firstResult;
+        let firstError;
+        try {
+            const result = await facade.streamStart(stream, target);
+            if (result.success || !isStreamHostResolveFailure(result.details)) {
+                return result;
+            }
+            firstResult = result;
+        }
+        catch (error) {
+            if (!isStreamHostResolveFailure(error)) {
+                throw error;
+            }
+            firstError = error;
+        }
+        // A ping from this host only helps when the stream target is this host: the device then has to
+        // address the echo reply to it and learns its address. Any other target stays unresolvable.
+        const targetHost = streamTargetHost(target);
+        if (targetHost === null || !isLocalAddress(targetHost)) {
+            if (firstResult) {
+                return firstResult;
+            }
+            throw firstError;
+        }
+        const host = new URL(this.baseUrl).hostname;
+        writeDiagnosticEvent("stream_start_host_resolve_retry", { stream, target, host });
+        await this.primeDeviceNeighborCache(host);
+        try {
+            const retry = await facade.streamStart(stream, target);
+            if (retry.success || !isStreamHostResolveFailure(retry.details)) {
+                return retry;
+            }
+        }
+        catch (error) {
+            if (!isStreamHostResolveFailure(error)) {
+                throw error;
+            }
+        }
+        throw new Error(`The Ultimate at ${host} could not resolve stream target ${target} (${STREAM_HOST_RESOLVE_ERROR}) even after pinging it from this host. ` +
+            "Check that this host is on the same network as the device, or use a multicast target.");
+    }
+    /** Best effort: ping failure (missing binary, blocked ICMP) is ignored and the caller retries anyway. */
+    async primeDeviceNeighborCache(host) {
+        const pingHost = pingableHost(host);
+        if (!pingHost) {
+            writeDiagnosticEvent("stream_start_ping_failed", { host, message: "host is not a plain hostname or address" });
+            return;
+        }
+        await new Promise((resolve) => {
+            execFile("ping", neighborPrimeArgs(pingHost), { timeout: NEIGHBOR_PRIME_TIMEOUT_MS, windowsHide: true }, (error) => {
+                if (error) {
+                    writeDiagnosticEvent("stream_start_ping_failed", { host, message: error.message });
+                }
+                resolve();
+            });
+        });
+    }
     async ensureStreamSuccess(result, action) {
         if (result.success) {
             return;

package/dist/device.js

@@ -632,10 +632,6 @@ export class ViceBackend {
     }
     async powerCycle() { return this.nuclearReset(); }
     async nuclearReset() {
-        const poweroffResult = await this.poweroff();
-        if (!poweroffResult.success) {
-            return poweroffResult;
-        }
         if (!this.manageProcess) {
             return {
                 success: false,
@@ -645,6 +641,10 @@ export class ViceBackend {
                 },
             };
         }
+        const poweroffResult = await this.poweroff();
+        if (!poweroffResult.success) {
+            return poweroffResult;
+        }
         try {
             await this.ensureProcess();
             return { success: true };
@@ -694,7 +694,10 @@ export class ViceBackend {
             return drives;
         });
     }
-    async driveMount(drive, imagePath) {
+    async driveMount(drive, imagePath, options) {
+        if (options?.type !== undefined || options?.mode !== undefined) {
+            throw unsupported("driveMount type/mode overrides; omit these options on VICE");
+        }
         const n = parseDriveNumber(drive);
         await this.withClient(async (client) => {
             await client.resourceSet(`Drive${n}CPUEnabled`, 1);
@@ -760,8 +763,18 @@ export class ViceBackend {
         };
     }
     async configGet(_category, item) {
-        if (!item)
-            throw unsupported("configGet without item name");
+        if (!item) {
+            if (_category !== "VICE")
+                throw new Error(`Unknown VICE configuration category '${_category}'`);
+            const inventory = await this.configsList();
+            return this.withClient(async (client) => {
+                const values = {};
+                for (const name of inventory.categories[0].items) {
+                    values[name] = (await client.resourceGet(name)).value;
+                }
+                return values;
+            });
+        }
         return await this.withClient(async (client) => {
             const res = await client.resourceGet(item);
             return { category: _category, item, value: res.value, type: res.type };
@@ -771,9 +784,7 @@ export class ViceBackend {
         let parsed = value;
         await this.withClient(async (client) => {
             const current = await client.resourceGet(item);
-            parsed = current.type === "int" ? Number(value) : value;
-            if (current.type === "int" && !Number.isFinite(parsed))
-                throw new Error(`VICE resource '${item}' requires an integer value`);
+            parsed = parseViceConfigValue(value, current.type, item);
             await client.resourceSet(item, parsed);
         });
         return { success: true, details: { item, value: parsed } };
@@ -784,11 +795,8 @@ export class ViceBackend {
             for (const [category, items] of Object.entries(payload)) {
                 for (const [item, value] of Object.entries(items)) {
                     try {
-                        const str = String(value ?? "");
                         const current = await client.resourceGet(item);
-                        const parsed = current.type === "int" ? Number(str) : str;
-                        if (current.type === "int" && !Number.isFinite(parsed))
-                            throw new Error(`VICE resource '${item}' requires an integer value`);
+                        const parsed = parseViceConfigValue(value, current.type, item);
                         await client.resourceSet(item, parsed);
                         results.push({ item: `${category}/${item}`, success: true });
                     }
@@ -814,6 +822,16 @@ export class ViceBackend {
 }
 ViceBackend.supervisors = new Map();
 ViceBackend.cleanupRegistered = false;
+function parseViceConfigValue(value, type, item) {
+    if (type !== "int")
+        return String(value ?? "");
+    const parsed = value === true || value === "true" ? 1
+        : value === false || value === "false" ? 0 : Number(value);
+    if (!Number.isInteger(parsed) || parsed < -0x80000000 || parsed > 0x7fffffff) {
+        throw new Error(`VICE resource '${item}' requires a 32-bit integer value`);
+    }
+    return parsed;
+}
 function unsupported(name) { const err = new Error(`Operation '${name}' is not supported by the VICE backend in phase one`); err.code = "UNSUPPORTED"; return err; }
 /** Ultimate file APIs treat slash as a path separator. Encode each name once,
  * preserving leading and nested separators for firmware routing. */