@cyanheads/pixoo-mcp-server 1.1.3 → 1.2.0

package/dist/mcp-server/tools/device-push.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @fileoverview The post-render push path shared by the three push tools: keep the
+ * rendered preview when a push fails, and flag a successful push the panel won't show.
+ * @module mcp-server/tools/device-push
+ */
+import { type PreviewWriter } from '../../renderer/preview.js';
+import type { DeviceStateSnapshot } from '../../services/pixoo/pixoo-service.js';
+/** Brightness at or below this reads as dark on the panel. */
+export declare const DIM_BRIGHTNESS = 10;
+/**
+ * Run a device push. A failed push rethrows its typed error — code, `reason`,
+ * `retryable`, and recovery hint untouched — with the preview's path added as
+ * `data.outputFiles` and named in the message: the files this call already saved, or
+ * a copy written under the OS temp dir when it saved none. Error results carry no
+ * `ctx.content` blocks, so the file is how the render outlives the failure.
+ */
+export declare function pushKeepingPreview(push: () => Promise<DeviceStateSnapshot>, savedFiles: string[], writePreview: PreviewWriter): Promise<DeviceStateSnapshot>;
+/**
+ * Name every reason a pushed render may not show on the panel, each with the call
+ * that fixes it. Undefined when the device reads as visible, or when the read-back
+ * never reached it and there is nothing to judge.
+ */
+export declare function visibilityNotice(state: DeviceStateSnapshot): string | undefined;
+//# sourceMappingURL=device-push.d.ts.map

package/dist/mcp-server/tools/device-push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-push.d.ts","sourceRoot":"","sources":["../../../src/mcp-server/tools/device-push.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,KAAK,aAAa,EAAmB,MAAM,uBAAuB,CAAC;AAC5E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAE7E,8DAA8D;AAC9D,eAAO,MAAM,cAAc,KAAK,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,OAAO,CAAC,mBAAmB,CAAC,EACxC,UAAU,EAAE,MAAM,EAAE,EACpB,YAAY,EAAE,aAAa,GAC1B,OAAO,CAAC,mBAAmB,CAAC,CAa9B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,GAAG,SAAS,CAgB/E"}

package/dist/mcp-server/tools/device-push.js

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview The post-render push path shared by the three push tools: keep the
+ * rendered preview when a push fails, and flag a successful push the panel won't show.
+ * @module mcp-server/tools/device-push
+ */
+import { McpError } from '@cyanheads/mcp-ts-core/errors';
+import { saveTempPreview } from '../../renderer/preview.js';
+/** Brightness at or below this reads as dark on the panel. */
+export const DIM_BRIGHTNESS = 10;
+/**
+ * Run a device push. A failed push rethrows its typed error — code, `reason`,
+ * `retryable`, and recovery hint untouched — with the preview's path added as
+ * `data.outputFiles` and named in the message: the files this call already saved, or
+ * a copy written under the OS temp dir when it saved none. Error results carry no
+ * `ctx.content` blocks, so the file is how the render outlives the failure.
+ */
+export async function pushKeepingPreview(push, savedFiles, writePreview) {
+    try {
+        return await push();
+    }
+    catch (err) {
+        if (!(err instanceof McpError))
+            throw err;
+        const outputFiles = savedFiles.length > 0 ? savedFiles : [await saveTempPreview(writePreview)];
+        throw new McpError(err.code, `${err.message.replace(/[^.!?]$/, '$&.')} Rendered preview saved to ${outputFiles.join(', ')}.`, { ...err.data, outputFiles }, { cause: err });
+    }
+}
+/**
+ * Name every reason a pushed render may not show on the panel, each with the call
+ * that fixes it. Undefined when the device reads as visible, or when the read-back
+ * never reached it and there is nothing to judge.
+ */
+export function visibilityNotice(state) {
+    if (!state.reachable)
+        return;
+    const problems = [];
+    if (state.screenOn === false) {
+        problems.push('the screen is off (pixoo_control_device with screen: "on")');
+    }
+    if (state.brightness !== undefined && state.brightness <= DIM_BRIGHTNESS) {
+        problems.push(`brightness is ${state.brightness} (pixoo_control_device with brightness: 80)`);
+    }
+    if (state.channel !== undefined && state.channel !== 'custom') {
+        problems.push(`the device is on the ${state.channel} channel (pixoo_control_device with channel: "custom")`);
+    }
+    if (problems.length === 0)
+        return;
+    return `Pushed, but the render may not be visible: ${problems.join('; ')}.`;
+}
+//# sourceMappingURL=device-push.js.map

package/dist/mcp-server/tools/device-push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-push.js","sourceRoot":"","sources":["../../../src/mcp-server/tools/device-push.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AACzD,OAAO,EAAsB,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAG5E,8DAA8D;AAC9D,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,IAAwC,EACxC,UAAoB,EACpB,YAA2B;IAE3B,IAAI,CAAC;QACH,OAAO,MAAM,IAAI,EAAE,CAAC;IACtB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,GAAG,YAAY,QAAQ,CAAC;YAAE,MAAM,GAAG,CAAC;QAC1C,MAAM,WAAW,GAAG,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,MAAM,eAAe,CAAC,YAAY,CAAC,CAAC,CAAC;QAC/F,MAAM,IAAI,QAAQ,CAChB,GAAG,CAAC,IAAI,EACR,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,CAAC,8BAA8B,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAC/F,EAAE,GAAG,GAAG,CAAC,IAAI,EAAE,WAAW,EAAE,EAC5B,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAA0B;IACzD,IAAI,CAAC,KAAK,CAAC,SAAS;QAAE,OAAO;IAC7B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;QAC7B,QAAQ,CAAC,IAAI,CAAC,4DAA4D,CAAC,CAAC;IAC9E,CAAC;IACD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,IAAI,cAAc,EAAE,CAAC;QACzE,QAAQ,CAAC,IAAI,CAAC,iBAAiB,KAAK,CAAC,UAAU,6CAA6C,CAAC,CAAC;IAChG,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC9D,QAAQ,CAAC,IAAI,CACX,wBAAwB,KAAK,CAAC,OAAO,wDAAwD,CAC9F,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAClC,OAAO,8CAA8C,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;AAC9E,CAAC"}

package/dist/renderer/preview.d.ts

@@ -1,5 +1,6 @@
 /**
- * @fileoverview Preview encoding utilities: PNG content blocks, contact sheets, GIF saving.
+ * @fileoverview Preview encoding utilities: PNG content blocks, contact sheets, and the
+ * PNG/GIF preview files written to PIXOO_OUTPUT_DIR or a temp directory.
  * @module renderer/preview
  */
 import { Canvas } from '@cyanheads/pixoo-toolkit';
@@ -9,26 +10,23 @@ export interface ImageContentBlock {
     mimeType: 'image/png' | 'image/gif';
     type: 'image';
 }
-/** Output files record. */
-export interface OutputFiles {
-    gif?: string;
-    preview?: string;
-}
+/** Writes a render's preview file into `dir` and resolves to the file's path. */
+export type PreviewWriter = (dir: string) => Promise<string>;
 /** Encode a single canvas as a base64 PNG content block (8× upscaled → 512px). */
 export declare function encodePreviewBlock(canvas: Canvas): ImageContentBlock;
 /**
- * Build a contact-sheet preview from animation frames.
- * Returns the middle frame encoded as a PNG (works universally across MCP clients).
- */
-export declare function buildContactSheet(frames: Canvas[]): ImageContentBlock;
-/**
- * Optionally save a preview PNG to PIXOO_OUTPUT_DIR.
- * Returns the saved path, or undefined if no output dir is configured.
- */
-export declare function savePngPreview(canvas: Canvas, baseName: string): Promise<string | undefined>;
-/**
- * Optionally save an animation GIF to PIXOO_OUTPUT_DIR.
- * Returns the saved path, or undefined if no output dir is configured.
+ * Build a contact-sheet preview: every frame, in order, tiled left-to-right and
+ * top-to-bottom in a `ceil(sqrt(n))`-column grid, each tile an integer upscale that
+ * keeps the sheet within the 512px preview budget. A single frame encodes exactly as
+ * {@link encodePreviewBlock} does.
  */
-export declare function saveGifPreview(frames: Canvas[], speed: number, baseName: string): Promise<string | undefined>;
+export declare function buildContactSheet(frames: Canvas[]): Promise<ImageContentBlock>;
+/** Save a canvas as an 8× upscaled PNG in `dir`; returns the saved path. */
+export declare function savePngPreview(canvas: Canvas, dir: string, baseName: string): Promise<string>;
+/** Save animation frames as an 8× upscaled GIF in `dir`; returns the saved path. */
+export declare function saveGifPreview(frames: Canvas[], speed: number, dir: string, baseName: string): Promise<string>;
+/** Write the preview into PIXOO_OUTPUT_DIR when one is configured; returns the paths written. */
+export declare function autoSavePreview(write: PreviewWriter): Promise<string[]>;
+/** Write the preview into a fresh directory under the OS temp dir; returns its path. */
+export declare function saveTempPreview(write: PreviewWriter): Promise<string>;
 //# sourceMappingURL=preview.d.ts.map

package/dist/renderer/preview.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/renderer/preview.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAAE,MAAM,EAAiC,MAAM,0BAA0B,CAAC;AAGjF,+BAA+B;AAC/B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,GAAG,WAAW,CAAC;IACpC,IAAI,EAAE,OAAO,CAAC;CACf;AAED,2BAA2B;AAC3B,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAIpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,iBAAiB,CASrE;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAQ7B;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B"}
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../src/renderer/preview.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,MAAM,EAA0C,MAAM,0BAA0B,CAAC;AAG1F,+BAA+B;AAC/B,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,GAAG,WAAW,CAAC;IACpC,IAAI,EAAE,OAAO,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAS7D,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAIpE;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA+BpF;AAED,4EAA4E;AAC5E,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED,oFAAoF;AACpF,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EAAE,EAChB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED,iGAAiG;AACjG,wBAAsB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAG7E;AAED,wFAAwF;AACxF,wBAAsB,eAAe,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,CAE3E"}

package/dist/renderer/preview.js

@@ -1,11 +1,18 @@
 /**
- * @fileoverview Preview encoding utilities: PNG content blocks, contact sheets, GIF saving.
+ * @fileoverview Preview encoding utilities: PNG content blocks, contact sheets, and the
+ * PNG/GIF preview files written to PIXOO_OUTPUT_DIR or a temp directory.
  * @module renderer/preview
  */
 import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
 import * as path from 'node:path';
-import { Canvas, canvasToPng, saveAnimationGif } from '@cyanheads/pixoo-toolkit';
+import { Canvas, canvasToPng, saveAnimationGif, savePng } from '@cyanheads/pixoo-toolkit';
 import { getServerConfig } from '../config/server-config.js';
+/** Edge length, in pixels, a preview image is scaled toward. */
+const PREVIEW_BUDGET_PX = 512;
+/** Gutter between contact-sheet tiles, which also fills the grid's unused cells. */
+const SHEET_GAP_PX = 2;
+const SHEET_GAP_COLOR = { r: 48, g: 48, b: 48 };
 /** Encode a single canvas as a base64 PNG content block (8× upscaled → 512px). */
 export function encodePreviewBlock(canvas) {
     const pngBuffer = canvasToPng(canvas, 8);
@@ -13,44 +20,58 @@ export function encodePreviewBlock(canvas) {
     return { type: 'image', data: base64, mimeType: 'image/png' };
 }
 /**
- * Build a contact-sheet preview from animation frames.
- * Returns the middle frame encoded as a PNG (works universally across MCP clients).
+ * Build a contact-sheet preview: every frame, in order, tiled left-to-right and
+ * top-to-bottom in a `ceil(sqrt(n))`-column grid, each tile an integer upscale that
+ * keeps the sheet within the 512px preview budget. A single frame encodes exactly as
+ * {@link encodePreviewBlock} does.
  */
-export function buildContactSheet(frames) {
-    // Return the middle frame as a representative preview
-    const midFrame = frames[Math.floor(frames.length / 2)] ?? frames[0];
-    if (!midFrame) {
-        // Empty frame set — return a black canvas
-        const fallback = new Canvas(64);
-        return encodePreviewBlock(fallback);
-    }
-    return encodePreviewBlock(midFrame);
+export async function buildContactSheet(frames) {
+    const [first] = frames;
+    if (!first || frames.length === 1)
+        return encodePreviewBlock(first ?? new Canvas(64));
+    const cols = Math.ceil(Math.sqrt(frames.length));
+    const rows = Math.ceil(frames.length / cols);
+    const scale = Math.max(1, Math.floor((PREVIEW_BUDGET_PX - (cols - 1) * SHEET_GAP_PX) / (cols * first.width)));
+    const pitch = first.width * scale + SHEET_GAP_PX;
+    const { default: sharp } = await import('sharp');
+    const png = await sharp({
+        create: {
+            width: cols * pitch - SHEET_GAP_PX,
+            height: rows * pitch - SHEET_GAP_PX,
+            channels: 3,
+            background: SHEET_GAP_COLOR,
+        },
+    })
+        .composite(frames.map((frame, i) => ({
+        input: Buffer.from(canvasToPng(frame, scale)),
+        left: (i % cols) * pitch,
+        top: Math.floor(i / cols) * pitch,
+    })))
+        .png()
+        .toBuffer();
+    return { type: 'image', data: png.toString('base64'), mimeType: 'image/png' };
 }
-/**
- * Optionally save a preview PNG to PIXOO_OUTPUT_DIR.
- * Returns the saved path, or undefined if no output dir is configured.
- */
-export async function savePngPreview(canvas, baseName) {
-    const cfg = getServerConfig();
-    if (!cfg.pixooOutputDir)
-        return;
-    await fs.mkdir(cfg.pixooOutputDir, { recursive: true });
-    const filePath = path.join(cfg.pixooOutputDir, `${baseName}.png`);
-    const { savePng } = await import('@cyanheads/pixoo-toolkit');
+/** Save a canvas as an 8× upscaled PNG in `dir`; returns the saved path. */
+export async function savePngPreview(canvas, dir, baseName) {
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${baseName}.png`);
     await savePng(canvas, filePath, 8);
     return filePath;
 }
-/**
- * Optionally save an animation GIF to PIXOO_OUTPUT_DIR.
- * Returns the saved path, or undefined if no output dir is configured.
- */
-export async function saveGifPreview(frames, speed, baseName) {
-    const cfg = getServerConfig();
-    if (!cfg.pixooOutputDir)
-        return;
-    await fs.mkdir(cfg.pixooOutputDir, { recursive: true });
-    const filePath = path.join(cfg.pixooOutputDir, `${baseName}.gif`);
+/** Save animation frames as an 8× upscaled GIF in `dir`; returns the saved path. */
+export async function saveGifPreview(frames, speed, dir, baseName) {
+    await fs.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, `${baseName}.gif`);
     await saveAnimationGif(frames, filePath, speed, 8);
     return filePath;
 }
+/** Write the preview into PIXOO_OUTPUT_DIR when one is configured; returns the paths written. */
+export async function autoSavePreview(write) {
+    const dir = getServerConfig().pixooOutputDir;
+    return dir ? [await write(dir)] : [];
+}
+/** Write the preview into a fresh directory under the OS temp dir; returns its path. */
+export async function saveTempPreview(write) {
+    return write(await fs.mkdtemp(path.join(os.tmpdir(), 'pixoo-preview-')));
+}
 //# sourceMappingURL=preview.js.map

package/dist/renderer/preview.js.map

@@ -1 +1 @@
-{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../src/renderer/preview.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAe5D,kFAAkF;AAClF,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,MAAM,SAAS,GAAG,WAAW,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACzD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;AAChE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAgB;IAChD,sDAAsD;IACtD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACpE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,0CAA0C;QAC1C,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC,CAAC;QAChC,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAc,EACd,QAAgB;IAEhB,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO;IAChC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,QAAQ,MAAM,CAAC,CAAC;IAClE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IAC7D,MAAM,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC;IACnC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAgB,EAChB,KAAa,EACb,QAAgB;IAEhB,MAAM,GAAG,GAAG,eAAe,EAAE,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,cAAc;QAAE,OAAO;IAChC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,cAAc,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,GAAG,QAAQ,MAAM,CAAC,CAAC;IAClE,MAAM,gBAAgB,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC;IACnD,OAAO,QAAQ,CAAC;AAClB,CAAC"}
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../src/renderer/preview.ts"],"names":[],"mappings":"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"}

package/dist/renderer/remote-image.d.ts

@@ -4,7 +4,7 @@
  * image elements and the pixoo_push_image tool.
  * @module renderer/remote-image
  */
-import { type RequestContext } from '@cyanheads/mcp-ts-core/utils';
+import type { Context } from '@cyanheads/mcp-ts-core';
 /** True when the string is a URL rather than a local filesystem path. */
 export declare function isRemoteSource(source: string): boolean;
 /**
@@ -14,8 +14,12 @@ export declare function isRemoteSource(source: string): boolean;
  * Private and loopback addresses are deliberately reachable: this server drives a
  * LAN device, so a NAS or local web server is a legitimate image host.
  *
+ * The download runs under `ctx.signal`: a cancelled request tears the response stream
+ * down instead of reading on to the deadline or the byte cap.
+ *
  * @throws {McpError} NotFound with `reason: 'asset_not_found'` for a non-https URL,
  *   an unreachable or non-2xx endpoint, or a response over {@link MAX_IMAGE_BYTES}.
+ * @throws {McpError} RequestCancelled when `ctx.signal` aborts while the body streams.
  */
-export declare function fetchRemoteImageToTempPng(source: string, ctx: RequestContext): Promise<string>;
+export declare function fetchRemoteImageToTempPng(source: string, ctx: Context): Promise<string>;
 //# sourceMappingURL=remote-image.d.ts.map

package/dist/renderer/remote-image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remote-image.d.ts","sourceRoot":"","sources":["../../src/renderer/remote-image.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAQrF,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;GASG;AACH,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,MAAM,CAAC,CA4CjB"}
+{"version":3,"file":"remote-image.d.ts","sourceRoot":"","sources":["../../src/renderer/remote-image.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAUtD,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAiE7F"}

package/dist/renderer/remote-image.js

@@ -23,8 +23,12 @@ export function isRemoteSource(source) {
  * Private and loopback addresses are deliberately reachable: this server drives a
  * LAN device, so a NAS or local web server is a legitimate image host.
  *
+ * The download runs under `ctx.signal`: a cancelled request tears the response stream
+ * down instead of reading on to the deadline or the byte cap.
+ *
  * @throws {McpError} NotFound with `reason: 'asset_not_found'` for a non-https URL,
  *   an unreachable or non-2xx endpoint, or a response over {@link MAX_IMAGE_BYTES}.
+ * @throws {McpError} RequestCancelled when `ctx.signal` aborts while the body streams.
  */
 export async function fetchRemoteImageToTempPng(source, ctx) {
     if (!source.startsWith('https://')) {
@@ -34,7 +38,11 @@ export async function fetchRemoteImageToTempPng(source, ctx) {
             recovery: { hint: 'Use an https URL, or pass an absolute local file path instead.' },
         });
     }
-    const resp = await fetchWithTimeout(source, FETCH_TIMEOUT_MS, ctx).catch((err) => {
+    // A throw here after the signal fired still reaches the caller as a cancellation:
+    // the handler factory reclassifies any error once the request's signal has aborted.
+    const resp = await fetchWithTimeout(source, FETCH_TIMEOUT_MS, ctx, {
+        signal: ctx.signal,
+    }).catch((err) => {
         throw notFound(`Failed to fetch image from "${source}": ${err instanceof Error ? err.message : String(err)}`, {
             reason: 'asset_not_found',
             url: source,
@@ -48,14 +56,30 @@ export async function fetchRemoteImageToTempPng(source, ctx) {
         [field]: bytes,
         recovery: { hint: 'Downscale the image before hosting it, or point at a smaller file.' },
     });
-    // content-length is advisory: it bails before the body is buffered, but the
-    // measured length is the gate that actually holds.
+    // content-length is advisory: it bails before the body is read, but the byte
+    // count taken while streaming is the gate that actually holds.
     const contentLength = Number(resp.headers.get('content-length') ?? 0);
-    if (contentLength > MAX_IMAGE_BYTES)
+    if (contentLength > MAX_IMAGE_BYTES) {
+        await resp.body?.cancel();
         throw tooLarge(contentLength, 'contentLength');
-    const buf = Buffer.from(await resp.arrayBuffer());
-    if (buf.byteLength > MAX_IMAGE_BYTES)
-        throw tooLarge(buf.byteLength, 'byteLength');
+    }
+    const chunks = [];
+    let received = 0;
+    const reader = resp.body?.getReader();
+    if (reader) {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            received += value.byteLength;
+            if (received > MAX_IMAGE_BYTES) {
+                await reader.cancel();
+                throw tooLarge(received, 'byteLength');
+            }
+            chunks.push(value);
+        }
+    }
+    const buf = Buffer.concat(chunks, received);
     const { default: sharp } = await import('sharp');
     const tmpPath = path.join(os.tmpdir(), `pixoo-img-${Date.now()}-${Math.random().toString(36).slice(2)}.png`);
     await sharp(buf).png().toFile(tmpPath);

package/dist/renderer/remote-image.js.map

@@ -1 +1 @@
-{"version":3,"file":"remote-image.js","sourceRoot":"","sources":["../../src/renderer/remote-image.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"remote-image.js","sourceRoot":"","sources":["../../src/renderer/remote-image.ts"],"names":[],"mappings":"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"}

package/dist/renderer/scene-renderer.d.ts

@@ -2,8 +2,8 @@
  * @fileoverview Scene renderer — element vocabulary, layout resolver, frame rendering.
  * @module renderer/scene-renderer
  */
-import type { RequestContext } from '@cyanheads/mcp-ts-core/utils';
-import { Canvas, downsampleSprite } from '@cyanheads/pixoo-toolkit';
+import type { Context } from '@cyanheads/mcp-ts-core';
+import { Canvas, downsampleSprite, type PixooSize } from '@cyanheads/pixoo-toolkit';
 import { type EffectName, type KeyframeMap } from './keyframes.js';
 import { type LayoutEntry, type SemanticX, type SemanticY, type TextStyle } from './text-engine.js';
 import { type PaletteName, type ThemeName } from './themes.js';
@@ -154,18 +154,23 @@ export interface SpriteElement extends BaseElement {
     y?: number;
 }
 export type SceneElement = TextElement | IconElement | RectElement | CircleElement | LineElement | ProgressElement | SparklineElement | BitmapElement | PixelsElement | ImageElement | SpriteElement;
-/** Pre-loaded asset cache for images and sprites. */
+/**
+ * Pre-loaded asset cache for images and sprites. Images are keyed by element: the
+ * loader bakes each element's fit, size, and position into its canvas, so two
+ * elements sharing a source still need a canvas each.
+ */
 export interface AssetCache {
-    images: Map<string, Canvas>;
+    images: Map<ImageElement, Canvas>;
     sprites: Map<string, Awaited<ReturnType<typeof downsampleSprite>>>;
 }
 /**
- * Preload all async assets referenced in elements.
+ * Preload all async assets referenced in elements. Images load onto a `size` canvas,
+ * the scene's own, so an image with no `w`/`h` fits the display.
  *
- * `ctx` is threaded through so a remote image fetch correlates to the
- * originating request in logs and traces.
+ * `ctx` is threaded through so a remote image fetch correlates to the originating
+ * request in logs and traces, and stops when that request is cancelled.
  */
-export declare function preloadAssets(elements: SceneElement[], ctx: RequestContext): Promise<AssetCache>;
+export declare function preloadAssets(elements: SceneElement[], ctx: Context, size: PixooSize): Promise<AssetCache>;
 /** Apply a background spec to a canvas. */
 export declare function applyBackground(canvas: Canvas, bg: BackgroundSpec): void;
 /** Render a single element onto a canvas at a specific frame. */
@@ -176,7 +181,7 @@ export declare function renderFrame(frameIdx: number, totalFrames: number, backg
     layoutEntries: LayoutEntry[];
 };
 /** Render all frames of a scene. */
-export declare function renderScene(background: BackgroundSpec, elements: SceneElement[], frameCount: number, ctx: RequestContext, size?: 16 | 32 | 64): Promise<{
+export declare function renderScene(background: BackgroundSpec, elements: SceneElement[], frameCount: number, ctx: Context, size?: PixooSize): Promise<{
     frames: Canvas[];
     layoutEntries: LayoutEntry[];
 }>;

package/dist/renderer/scene-renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scene-renderer.d.ts","sourceRoot":"","sources":["../../src/renderer/scene-renderer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"scene-renderer.d.ts","sourceRoot":"","sources":["../../src/renderer/scene-renderer.ts"],"names":[],"mappings":"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"}

package/dist/renderer/scene-renderer.js

@@ -3,7 +3,7 @@
  * @module renderer/scene-renderer
  */
 import * as fs from 'node:fs/promises';
-import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
+import { invalidParams, notFound } from '@cyanheads/mcp-ts-core/errors';
 import { Canvas, downsampleSprite, drawText, FONT_3x5, FONT_5x7, lerpColor, loadImage, measureText, renderSprite, renderSvgPath, resolveColor, } from '@cyanheads/pixoo-toolkit';
 import { ICONS } from './icons.js';
 import { compileEffect, getKeyframeValue } from './keyframes.js';
@@ -11,43 +11,64 @@ import { fetchRemoteImageToTempPng, isRemoteSource } from './remote-image.js';
 import { drawStyledText, resolveX, resolveY, } from './text-engine.js';
 import { PALETTES, THEMES } from './themes.js';
 /**
- * Preload all async assets referenced in elements.
+ * Confirm a local image or sprite-sheet path is readable before the toolkit's
+ * loader reaches it — the loader fails a missing file with an unclassified error.
  *
- * `ctx` is threaded through so a remote image fetch correlates to the
- * originating request in logs and traces.
+ * @throws {McpError} NotFound with `reason: 'asset_not_found'` when the path is
+ *   missing or unreadable.
  */
-export async function preloadAssets(elements, ctx) {
+async function assertReadableAsset(assetPath, label) {
+    try {
+        await fs.access(assetPath, fs.constants.R_OK);
+    }
+    catch (err) {
+        throw notFound(`${label} not found or unreadable: "${assetPath}".`, {
+            reason: 'asset_not_found',
+            path: assetPath,
+            recovery: { hint: 'Pass an absolute path to an existing, readable image file.' },
+        }, { cause: err });
+    }
+}
+/**
+ * Preload all async assets referenced in elements. Images load onto a `size` canvas,
+ * the scene's own, so an image with no `w`/`h` fits the display.
+ *
+ * `ctx` is threaded through so a remote image fetch correlates to the originating
+ * request in logs and traces, and stops when that request is cancelled.
+ */
+export async function preloadAssets(elements, ctx, size) {
     const cache = { images: new Map(), sprites: new Map() };
     await Promise.all(elements.map(async (el) => {
         if (el.type === 'image') {
             const source = el.source;
-            if (!cache.images.has(source)) {
-                // The toolkit's loadImage reads from disk, so a remote source is
-                // staged to a temp PNG first and unlinked once it has been read.
-                const tmpPathToCleanup = isRemoteSource(source)
-                    ? await fetchRemoteImageToTempPng(source, ctx)
-                    : undefined;
-                const localPath = tmpPathToCleanup ?? source;
-                const loadOpts = {
-                    fit: el.fit ?? 'contain',
-                    kernel: el.kernel ?? 'nearest',
-                    x: typeof el.x === 'number' ? el.x : 0,
-                    y: typeof el.y === 'number' ? el.y : 0,
-                };
-                if (el.w !== undefined)
-                    loadOpts.width = el.w;
-                if (el.h !== undefined)
-                    loadOpts.height = el.h;
-                const canvas = await loadImage(localPath, loadOpts);
-                if (tmpPathToCleanup) {
-                    fs.unlink(tmpPathToCleanup).catch(() => undefined);
-                }
-                cache.images.set(source, canvas);
+            // The toolkit's loadImage reads from disk, so a remote source is
+            // staged to a temp PNG first and unlinked once it has been read.
+            const remote = isRemoteSource(source);
+            if (!remote)
+                await assertReadableAsset(source, 'Image file');
+            const tmpPathToCleanup = remote ? await fetchRemoteImageToTempPng(source, ctx) : undefined;
+            const localPath = tmpPathToCleanup ?? source;
+            const loadOpts = {
+                size,
+                fit: el.fit ?? 'contain',
+                kernel: el.kernel ?? 'nearest',
+                x: typeof el.x === 'number' ? el.x : 0,
+                y: typeof el.y === 'number' ? el.y : 0,
+            };
+            if (el.w !== undefined)
+                loadOpts.width = el.w;
+            if (el.h !== undefined)
+                loadOpts.height = el.h;
+            const canvas = await loadImage(localPath, loadOpts);
+            if (tmpPathToCleanup) {
+                fs.unlink(tmpPathToCleanup).catch(() => undefined);
             }
+            cache.images.set(el, canvas);
         }
         else if (el.type === 'sprite') {
             const key = `${el.path}:${el.cols}:${el.rows}`;
             if (!cache.sprites.has(key)) {
+                await assertReadableAsset(el.path, 'Sprite sheet');
                 const sprite = await downsampleSprite(el.path, el.cols, el.rows);
                 cache.sprites.set(key, sprite);
             }
@@ -370,9 +391,9 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             break;
         }
         case 'image': {
-            const cachedCanvas = assets.images.get(el.source);
+            const cachedCanvas = assets.images.get(el);
             if (cachedCanvas) {
-                canvas.blit(cachedCanvas, dx, dy);
+                target.blit(cachedCanvas, dx, dy);
             }
             layoutEntries.push({
                 element: elIdx,
@@ -443,7 +464,7 @@ export function renderFrame(frameIdx, totalFrames, background, elements, assets,
 }
 /** Render all frames of a scene. */
 export async function renderScene(background, elements, frameCount, ctx, size = 64) {
-    const assets = await preloadAssets(elements, ctx);
+    const assets = await preloadAssets(elements, ctx, size);
     const allLayoutEntries = [];
     const frames = [];
     for (let i = 0; i < frameCount; i++) {