c64bridge 0.7.4 → 0.8.0

package/dist/tools/graphics.js

@@ -1,5 +1,6 @@
 import { Buffer } from "node:buffer";
 import { createPetsciiArt } from "../petsciiArt.js";
+import { importImageAsVicBitmap } from "../vicBitmap.js";
 import { defineToolModule, OPERATION_DISCRIMINATOR, } from "./types.js";
 import { booleanSchema, numberSchema, objectSchema, optionalSchema, stringSchema, } from "./schema.js";
 import { jsonResult, textResult } from "./responses.js";
@@ -49,6 +50,37 @@ function decodeSpriteString(value, path) {
         throw new ToolValidationError("Unable to parse sprite hex string", { path, cause: error });
     }
 }
+function parseAddressValue(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const normalised = trimmed.startsWith("$") ? `0x${trimmed.slice(1)}` : trimmed;
+    const parsed = Number(normalised);
+    if (!Number.isInteger(parsed) || parsed < 0 || parsed > 0xFFFF) {
+        return null;
+    }
+    return parsed;
+}
+const addressSchema = {
+    jsonSchema: {
+        description: "Absolute C64 memory address, provided as an integer or hex string such as $2000.",
+        type: ["integer", "string"],
+    },
+    parse(value, path) {
+        const resolvedPath = path ?? "$";
+        if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 0xFFFF) {
+            return value;
+        }
+        if (typeof value === "string") {
+            const parsed = parseAddressValue(value);
+            if (parsed !== null) {
+                return parsed;
+            }
+        }
+        throw new ToolValidationError("Address must be an integer or hex string within $0000-$FFFF", { path: resolvedPath });
+    },
+};
 const spriteBytesSchema = {
     jsonSchema: {
         description: "63-byte sprite definition provided as base64/hex string or array of bytes.",
@@ -90,7 +122,7 @@ const spriteBytesSchema = {
     },
 };
 const spriteArgsSchema = objectSchema({
-    description: "Generate a PRG that displays a single sprite using raw sprite data.",
+    description: "Display a single sprite by writing supplied sprite data into RAM and patching the relevant VIC-II registers.",
     properties: {
         sprite: spriteBytesSchema,
         index: numberSchema({
@@ -221,7 +253,7 @@ const petsciiImageArgsSchema = objectSchema({
             maximum: 15,
         })),
         dryRun: booleanSchema({
-            description: "When true, skip uploading the BASIC program to the C64.",
+            description: "When true, skip uploading the generated BASIC program to the C64.",
             default: false,
         }),
         bitmap: optionalSchema(bitmapSchema),
@@ -251,6 +283,49 @@ const renderPetsciiScreenArgsSchema = objectSchema({
     required: ["text"],
     additionalProperties: false,
 });
+const vicBitmapModeSchema = {
+    jsonSchema: {
+        description: "Bitmap encoding mode to generate for the VIC-II display.",
+        type: "string",
+        enum: ["hires", "multicolor"],
+    },
+    parse(value, path) {
+        if (value === "hires" || value === "multicolor") {
+            return value;
+        }
+        throw new ToolValidationError("Bitmap format must be either hires or multicolor", { path: path ?? "$" });
+    },
+};
+const generateBitmapArgsSchema = objectSchema({
+    description: "Import an image file, convert it to a VIC-II bitmap, write it into RAM, and enable bitmap mode.",
+    properties: {
+        imagePath: stringSchema({
+            description: "Filesystem path of the source image (PNG, JPEG, BMP, GIF, TIFF, and other Jimp-supported formats).",
+            minLength: 1,
+        }),
+        format: vicBitmapModeSchema,
+        bitmapAddress: optionalSchema(addressSchema, 0x2000),
+        screenAddress: optionalSchema(addressSchema, 0x0400),
+        borderColor: optionalSchema(numberSchema({
+            description: "Border colour index (0-15).",
+            integer: true,
+            minimum: 0,
+            maximum: 15,
+        }), 0),
+        backgroundColor: optionalSchema(numberSchema({
+            description: "Background colour index (0-15). Used for multicolor mode and aspect-ratio padding.",
+            integer: true,
+            minimum: 0,
+            maximum: 15,
+        }), 0),
+        preserveAspect: booleanSchema({
+            description: "Preserve the source image aspect ratio and pad with the background colour.",
+            default: true,
+        }),
+    },
+    required: ["imagePath", "format"],
+    additionalProperties: false,
+});
 function stripOperationDiscriminator(value) {
     const { [OPERATION_DISCRIMINATOR]: _ignored, ...rest } = value;
     return rest;
@@ -258,7 +333,7 @@ function stripOperationDiscriminator(value) {
 async function executeGenerateSprite(rawArgs, ctx) {
     try {
         const parsed = spriteArgsSchema.parse(rawArgs ?? {});
-        ctx.logger.info("Generating sprite PRG", {
+        ctx.logger.info("Rendering sprite", {
             index: parsed.index,
             x: parsed.x,
             y: parsed.y,
@@ -274,11 +349,11 @@ async function executeGenerateSprite(rawArgs, ctx) {
             multicolour: parsed.multicolour,
         });
         if (!result.success) {
-            throw new ToolExecutionError("C64 firmware reported failure while running sprite PRG", {
+            throw new ToolExecutionError("C64 firmware reported failure while rendering sprite", {
                 details: normaliseFailure(result.details),
             });
         }
-        return textResult("Sprite PRG generated and executed successfully.", {
+        return textResult("Sprite rendered successfully.", {
             success: true,
             index: parsed.index,
             x: parsed.x,
@@ -293,7 +368,9 @@ async function executeGenerateSprite(rawArgs, ctx) {
         if (error instanceof ToolError) {
             return toolErrorResult(error);
         }
-        return unknownErrorResult(error);
+        return toolErrorResult(new ToolExecutionError("Unable to render sprite", {
+            details: normaliseFailure(error instanceof Error ? { message: error.message } : error),
+        }));
     }
 }
 async function executeRenderPetscii(rawArgs, ctx) {
@@ -322,7 +399,75 @@ async function executeRenderPetscii(rawArgs, ctx) {
         if (error instanceof ToolError) {
             return toolErrorResult(error);
         }
-        return unknownErrorResult(error);
+        return toolErrorResult(new ToolExecutionError("Unable to render PETSCII screen", {
+            details: normaliseFailure(error instanceof Error ? { message: error.message } : error),
+        }));
+    }
+}
+async function executeGenerateBitmap(rawArgs, ctx) {
+    try {
+        const parsed = generateBitmapArgsSchema.parse(rawArgs ?? {});
+        ctx.logger.info("Rendering bitmap", {
+            imagePath: parsed.imagePath,
+            format: parsed.format,
+            bitmapAddress: parsed.bitmapAddress,
+            screenAddress: parsed.screenAddress,
+            preserveAspect: parsed.preserveAspect,
+        });
+        const prepared = await importImageAsVicBitmap({
+            imagePath: parsed.imagePath,
+            mode: parsed.format,
+            preserveAspect: parsed.preserveAspect,
+            backgroundColor: parsed.backgroundColor,
+            borderColor: parsed.borderColor,
+        });
+        const result = await ctx.client.displayBitmap(prepared, {
+            bitmapAddress: parsed.bitmapAddress,
+            screenAddress: parsed.screenAddress,
+        });
+        if (!result.success) {
+            throw new ToolExecutionError("C64 firmware reported failure while displaying bitmap image", {
+                details: normaliseFailure(result.details),
+            });
+        }
+        const details = toRecord(result.details) ?? {};
+        const data = {
+            mode: prepared.mode,
+            imagePath: parsed.imagePath,
+            sourceWidth: prepared.sourceWidth,
+            sourceHeight: prepared.sourceHeight,
+            logicalWidth: prepared.logicalWidth,
+            logicalHeight: prepared.logicalHeight,
+            displayWidth: prepared.displayWidth,
+            displayHeight: prepared.displayHeight,
+            backgroundColor: prepared.backgroundColor,
+            borderColor: prepared.borderColor,
+            bitmapAddress: details.bitmapAddress ?? null,
+            screenAddress: details.screenAddress ?? null,
+            colorRamAddress: details.colorRamAddress ?? null,
+            bank: details.bank ?? null,
+            registers: details.registers ?? null,
+            bitmapBytes: prepared.bitmapData.length,
+            screenBytes: prepared.screenRam.length,
+            colorRamBytes: prepared.colorRam.length,
+        };
+        return jsonResult(data, {
+            success: true,
+            mode: prepared.mode,
+            bank: details.bank ?? null,
+            bitmapAddress: details.bitmapAddress ?? null,
+            screenAddress: details.screenAddress ?? null,
+            sourceWidth: prepared.sourceWidth,
+            sourceHeight: prepared.sourceHeight,
+        });
+    }
+    catch (error) {
+        if (error instanceof ToolError) {
+            return toolErrorResult(error);
+        }
+        return toolErrorResult(new ToolExecutionError("Unable to import or display bitmap image", {
+            details: normaliseFailure(error instanceof Error ? { message: error.message } : error),
+        }));
     }
 }
 async function executeCreatePetscii(rawArgs, ctx) {
@@ -392,9 +537,10 @@ async function executeCreatePetscii(rawArgs, ctx) {
     }
 }
 export const graphicsOperationHandlers = {
-    create_petscii: async (args, ctx) => executeCreatePetscii(stripOperationDiscriminator(args), ctx),
-    render_petscii: async (args, ctx) => executeRenderPetscii(stripOperationDiscriminator(args), ctx),
-    generate_sprite: async (args, ctx) => executeGenerateSprite(stripOperationDiscriminator(args), ctx),
+    render_petscii_art: async (args, ctx) => executeCreatePetscii(stripOperationDiscriminator(args), ctx),
+    render_bitmap: async (args, ctx) => executeGenerateBitmap(stripOperationDiscriminator(args), ctx),
+    render_petscii_text: async (args, ctx) => executeRenderPetscii(stripOperationDiscriminator(args), ctx),
+    render_sprite: async (args, ctx) => executeGenerateSprite(stripOperationDiscriminator(args), ctx),
 };
 export const graphicsModule = defineToolModule({
     domain: "graphics",
@@ -412,9 +558,9 @@ export const graphicsModule = defineToolModule({
     ],
     tools: [
         {
-            name: "generate_sprite",
-            description: "Generate and execute a PRG that displays a sprite from raw 63-byte data. See c64://specs/vic for registers.",
-            summary: "Uploads minimal machine code to copy sprite data, configure VIC-II, and render a sprite.",
+            name: "render_sprite",
+            description: "Display supplied 63-byte sprite data at the requested position and colour by writing memory and patching VIC-II registers directly. See c64://specs/vic for registers.",
+            summary: "Writes sprite data into RAM, updates the sprite pointer table, and patches VIC-II registers to render a sprite preview.",
             inputSchema: spriteArgsSchema.jsonSchema,
             relatedResources: ["c64://specs/vic"],
             relatedPrompts: ["graphics-demo", "assembly-program"],
@@ -431,13 +577,31 @@ export const graphicsModule = defineToolModule({
                 "Use when the user supplies sprite bytes or asks to preview graphics quickly; describe resulting coordinates and colours.",
                 "Remind the user that sprites live in banked memory so further tweaks may require write_memory calls.",
             ],
+            supportedPlatforms: ["c64u", "vice"],
             async execute(args, ctx) {
                 return executeGenerateSprite(args, ctx);
             },
         },
         {
-            name: "render_petscii",
-            description: "Render PETSCII text to the screen with optional border/background colours. See c64://specs/basic.",
+            name: "render_bitmap",
+            description: "Import an image file, convert it to a VIC-II bitmap, write it into RAM, and display it.",
+            summary: "Decodes a source image, quantizes it into C64 colours, writes bitmap/screen/color RAM, and displays it in hires or multicolor bitmap mode.",
+            inputSchema: generateBitmapArgsSchema.jsonSchema,
+            relatedResources: ["c64://specs/vic", "c64://context/bootstrap"],
+            relatedPrompts: ["graphics-demo"],
+            tags: ["bitmap", "vic", "image"],
+            workflowHints: [
+                "Use when the user wants to display an external image on screen rather than generate PETSCII art.",
+                "Call out the selected bitmap and screen RAM addresses so follow-up memory inspection or raster work stays grounded.",
+            ],
+            supportedPlatforms: ["c64u", "vice"],
+            async execute(args, ctx) {
+                return executeGenerateBitmap(args, ctx);
+            },
+        },
+        {
+            name: "render_petscii_text",
+            description: "Display PETSCII text with optional border and background colours. See c64://specs/basic.",
             summary: "Generates a BASIC program that clears the screen, sets colours, and prints text.",
             inputSchema: renderPetsciiScreenArgsSchema.jsonSchema,
             relatedResources: ["c64://specs/basic", "c64://context/bootstrap"],
@@ -455,13 +619,14 @@ export const graphicsModule = defineToolModule({
                 "Call after generating PETSCII text or when the user wants border/background colour changes applied.",
                 "Echo the colour indices and mention CLEAR + PRINT so the user knows what ran.",
             ],
+            supportedPlatforms: ["c64u", "vice"],
             async execute(args, ctx) {
                 return executeRenderPetscii(args, ctx);
             },
         },
         {
-            name: "create_petscii",
-            description: "Create PETSCII art from prompts or text, optionally run it on the C64, and return metadata including PETSCII codes and glyphs. See c64://specs/basic, c64://specs/vic, and c64://specs/charset.",
+            name: "render_petscii_art",
+            description: "Create PETSCII art from prompts, text, or bitmap input, and optionally display it on the C64. Returns metadata including PETSCII codes and glyphs. See c64://specs/basic, c64://specs/vic, and c64://specs/charset.",
             summary: "Synthesises PETSCII art, generates a BASIC program with preview metadata (petsciiCodes, glyphs, dimensions), and uploads it unless dry-run is requested.",
             inputSchema: petsciiImageArgsSchema.jsonSchema,
             relatedResources: ["c64://specs/basic", "c64://specs/vic", "c64://specs/charset"],
@@ -480,6 +645,7 @@ export const graphicsModule = defineToolModule({
                 "Response includes petsciiCodes array and glyphs for character-level inspection.",
                 "Provide follow-up suggestions like saving the PRG or capturing the screen after rendering.",
             ],
+            supportedPlatforms: ["c64u", "vice"],
             async execute(args, ctx) {
                 return executeCreatePetscii(args, ctx);
             },

package/dist/tools/machineControl.js

@@ -26,7 +26,7 @@ function normaliseFailure(details) {
 }
 const resetArgsSchema = createNoArgsSchema("No arguments required to reset the C64.");
 const rebootArgsSchema = createNoArgsSchema("No arguments required to reboot the C64 firmware.");
-const pauseArgsSchema = createNoArgsSchema("No arguments required to pause the machine via DMA.");
+const pauseArgsSchema = createNoArgsSchema("No arguments required to pause the machine.");
 const resumeArgsSchema = createNoArgsSchema("No arguments required to resume the machine after a pause.");
 const poweroffArgsSchema = createNoArgsSchema("No arguments required to power off the machine.");
 const menuButtonArgsSchema = createNoArgsSchema("No arguments required to toggle the Ultimate menu button.");
@@ -54,6 +54,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Use when the user wants a quick restart without losing power; mention that memory contents may persist.",
             ],
+            supportedPlatforms: ["c64u", "vice"],
             async execute(args, ctx) {
                 try {
                     resetArgsSchema.parse(args ?? {});
@@ -91,6 +92,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Choose reboot when configuration changed or hardware is stuck; warn that it will interrupt any running program.",
             ],
+            supportedPlatforms: ["c64u", "vice"],
             async execute(args, ctx) {
                 try {
                     rebootArgsSchema.parse(args ?? {});
@@ -117,8 +119,8 @@ export const machineControlModule = defineToolModule({
         },
         {
             name: "pause",
-            description: "Pause the machine using DMA halt. See memory safety checklist in c64://context/bootstrap.",
-            summary: "Suspends CPU execution until resumed.",
+            description: "Pause the machine on Ultimate hardware. See memory safety checklist in c64://context/bootstrap.",
+            summary: "Suspends CPU execution on Ultimate hardware until resumed.",
             inputSchema: pauseArgsSchema.jsonSchema,
             tags: ["pause"],
             prerequisites: [],
@@ -128,6 +130,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Pause when the user needs a stable memory snapshot; remind them to resume to continue execution.",
             ],
+            supportedPlatforms: ["c64u"],
             async execute(args, ctx) {
                 try {
                     pauseArgsSchema.parse(args ?? {});
@@ -154,8 +157,8 @@ export const machineControlModule = defineToolModule({
         },
         {
             name: "resume",
-            description: "Resume the machine after a DMA pause.",
-            summary: "Releases the DMA halt so the CPU can continue.",
+            description: "Resume the machine after an Ultimate hardware pause.",
+            summary: "Releases the Ultimate hardware pause so the CPU can continue.",
             inputSchema: resumeArgsSchema.jsonSchema,
             tags: ["resume"],
             prerequisites: ["pause"],
@@ -165,6 +168,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Call after a pause or diagnostic halt and confirm the machine is running again.",
             ],
+            supportedPlatforms: ["c64u"],
             async execute(args, ctx) {
                 try {
                     resumeArgsSchema.parse(args ?? {});
@@ -202,6 +206,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Use when the user explicitly requests power off; remind them to power on manually or via drive controls afterwards.",
             ],
+            supportedPlatforms: ["c64u", "vice"],
             async execute(args, ctx) {
                 try {
                     poweroffArgsSchema.parse(args ?? {});
@@ -239,6 +244,7 @@ export const machineControlModule = defineToolModule({
             workflowHints: [
                 "Use when the user needs to open or close the Ultimate menu; suggest following up with drive operations if relevant.",
             ],
+            supportedPlatforms: ["c64u"],
             async execute(args, ctx) {
                 try {
                     menuButtonArgsSchema.parse(args ?? {});

package/dist/tools/memory.js

@@ -75,6 +75,10 @@ function resolveAddressLabel(details, fallback) {
 function resolveLength(details) {
     return typeof details.length === "number" ? details.length : undefined;
 }
+function supportsMachinePause(ctx) {
+    const platformId = ctx.platform?.id;
+    return platformId !== "vice";
+}
 const readScreenArgsSchema = objectSchema({
     description: "No arguments are required for reading the current screen contents.",
     properties: {},
@@ -111,7 +115,7 @@ const writeMemoryArgsSchema = objectSchema({
             pattern: /^[\s_0-9A-Fa-f$]+$/,
         }),
         verify: booleanSchema({
-            description: "When true, pause and verify the write by reading back the affected range.",
+            description: "When true, verify the write by reading before and after the change; Ultimate hardware also pauses during verification.",
             default: false,
         }),
         expected: optionalSchema(stringSchema({
@@ -208,15 +212,18 @@ async function executeWriteMemory(rawArgs, ctx) {
                 details: detailRecord,
             });
         }
+        const canPause = supportsMachinePause(ctx);
         let paused = false;
         try {
-            const pauseResult = await ctx.client.pause();
-            if (!pauseResult.success) {
-                throw new ToolExecutionError("C64 firmware reported failure while pausing", {
-                    details: normaliseFailure(pauseResult.details),
-                });
+            if (canPause) {
+                const pauseResult = await ctx.client.pause();
+                if (!pauseResult.success) {
+                    throw new ToolExecutionError("C64 firmware reported failure while pausing", {
+                        details: normaliseFailure(pauseResult.details),
+                    });
+                }
+                paused = true;
             }
-            paused = true;
             const expectedBytes = expectedInfo?.bytes ?? new Uint8Array();
             const maskBytes = maskInfo?.bytes;
             const readLength = Math.max(1, Math.max(writeInfo.bytes.length, expectedBytes.length));
@@ -306,6 +313,7 @@ async function executeWriteMemory(rawArgs, ctx) {
                 details: detailRecord,
                 verified: true,
                 verification: verificationMetadata,
+                paused,
             });
         }
         finally {
@@ -344,6 +352,7 @@ export const memoryOperationHandlers = {
 export const memoryModule = defineToolModule({
     domain: "memory",
     summary: "Screen, main memory, and low-level inspection utilities.",
+    supportedPlatforms: ["c64u", "vice"],
     resources: [
         "c64://context/bootstrap",
         "c64://specs/basic",
@@ -387,7 +396,7 @@ export const memoryModule = defineToolModule({
             relatedResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
             relatedPrompts: ["memory-debug", "assembly-program"],
             tags: ["memory", "hex"],
-            prerequisites: ["pause"],
+            prerequisites: [],
             examples: [
                 {
                     name: "Read screen memory",
@@ -406,12 +415,12 @@ export const memoryModule = defineToolModule({
         {
             name: "write",
             description: "Write a hexadecimal byte sequence into main memory at the specified address. See c64://context/bootstrap for safety rules.",
-            summary: "Resolves symbols, validates hex data, and writes bytes to RAM via Ultimate firmware.",
+            summary: "Resolves symbols, validates hex data, and writes bytes to RAM.",
             inputSchema: writeMemoryArgsSchema.jsonSchema,
             relatedResources: ["c64://context/bootstrap", "c64://specs/assembly", "c64://docs/index"],
             relatedPrompts: ["memory-debug", "assembly-program"],
             tags: ["memory", "hex", "write"],
-            prerequisites: ["pause", "read"],
+            prerequisites: ["read"],
             examples: [
                 {
                     name: "Write to screen",