@cyanheads/pixoo-mcp-server 1.2.1 → 1.2.2

package/dist/renderer/remote-image.js

@@ -1,11 +1,9 @@
 /**
- * @fileoverview Remote image fetch — downloads an https image to a temp PNG for the
- * toolkit's `loadImage`, which reads from disk only. Shared by the scene renderer's
- * image elements and the pixoo_push_image tool.
+ * @fileoverview Remote image fetch — downloads an https image's encoded bytes into
+ * memory for the toolkit's image loaders. Shared by the scene renderer's image elements
+ * and the pixoo_push_image tool.
  * @module renderer/remote-image
  */
-import * as os from 'node:os';
-import * as path from 'node:path';
 import { notFound } from '@cyanheads/mcp-ts-core/errors';
 import { fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
 /** Wall-clock budget for a remote image fetch, headers through body. */
@@ -17,8 +15,9 @@ export function isRemoteSource(source) {
     return source.startsWith('https://') || source.startsWith('http://');
 }
 /**
- * Fetch an https image and write it to a temp PNG, returning the path. The caller
- * owns the file and must unlink it once `loadImage` has read it.
+ * Fetch an https image and return its bytes as served, undecoded. Nothing is written to
+ * disk: the caller passes the bytes to the toolkit's loader, where a body that is not an image
+ * fails to decode.
  *
  * 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.
@@ -27,19 +26,20 @@ export function isRemoteSource(source) {
  * 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}.
+ *   an unreachable or non-2xx endpoint, or a response over {@link MAX_IMAGE_BYTES}. The
+ *   message names the failure; the recovery is the calling tool's declared one.
  * @throws {McpError} RequestCancelled when `ctx.signal` aborts while the body streams.
  * @throws {McpError} Timeout when the body outlasts {@link FETCH_TIMEOUT_MS}, or when the
  *   `ctx.signal` abort is a caller-side deadline (a `TimeoutError` reason). A tool handler
  *   still answers the deadline as RequestCancelled: the handler factory settles any throw
  *   after the request's signal fired as a cancellation.
  */
-export async function fetchRemoteImageToTempPng(source, ctx) {
+export async function fetchRemoteImageBytes(source, ctx) {
     if (!source.startsWith('https://')) {
         throw notFound(`Only https URLs are supported. Received: "${source}".`, {
             reason: 'asset_not_found',
             url: source,
-            recovery: { hint: 'Use an https URL, or pass an absolute local file path instead.' },
+            ...ctx.recoveryFor('asset_not_found'),
         });
     }
     // A throw here after the signal fired still reaches the caller as a cancellation:
@@ -47,18 +47,14 @@ export async function fetchRemoteImageToTempPng(source, ctx) {
     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,
-            recovery: { hint: 'Check the URL is reachable and returns an image, then retry.' },
-        });
+        throw notFound(`Failed to fetch image from "${source}": ${err instanceof Error ? err.message : String(err)}`, { reason: 'asset_not_found', url: source, ...ctx.recoveryFor('asset_not_found') });
     });
     /** Both size gates fail the same way; only the field naming the measurement differs. */
     const tooLarge = (bytes, field) => notFound(`Image response too large (${bytes} bytes; limit: ${MAX_IMAGE_BYTES}).`, {
         reason: 'asset_not_found',
         url: source,
         [field]: bytes,
-        recovery: { hint: 'Downscale the image before hosting it, or point at a smaller file.' },
+        ...ctx.recoveryFor('asset_not_found'),
     });
     // content-length is advisory: it bails before the body is read, but the byte
     // count taken while streaming is the gate that actually holds.
@@ -83,10 +79,6 @@ export async function fetchRemoteImageToTempPng(source, ctx) {
             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);
-    return tmpPath;
+    return Buffer.concat(chunks, received);
 }
 //# sourceMappingURL=remote-image.js.map

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

@@ -3,9 +3,10 @@
  * @module renderer/scene-renderer
  */
 import type { Context } from '@cyanheads/mcp-ts-core';
-import { Canvas, downsampleSprite, type PixooSize } from '@cyanheads/pixoo-toolkit';
+import { type BlendMode, Canvas, downsampleSprite, type PixooSize } from '@cyanheads/pixoo-toolkit';
+import { type Finish } from './finish.js';
 import { type EffectName, type KeyframeMap } from './keyframes.js';
-import { type LayoutEntry, type SemanticX, type SemanticY, type TextStyle } from './text-engine.js';
+import { type FontVariant, type LayoutEntry, type SemanticX, type SemanticY, type TextStyle } from './text-engine.js';
 import { type PaletteName, type ThemeName } from './themes.js';
 /** Background specification. */
 export type BackgroundSpec = string | {
@@ -27,6 +28,8 @@ export interface EffectSpec {
 /** Base element properties. */
 interface BaseElement {
     animate?: KeyframeMap;
+    /** How the element's pixels combine with what lies beneath (default `normal`, source-over). */
+    blend?: BlendMode;
     dx?: number;
     dy?: number;
     effect?: EffectSpec;
@@ -36,7 +39,7 @@ interface BaseElement {
 /** Text element. */
 export interface TextElement extends BaseElement {
     color?: string;
-    font?: 'standard' | 'compact';
+    font?: FontVariant;
     style?: TextStyle;
     text: string;
     type: 'text';
@@ -66,6 +69,8 @@ export interface RectElement extends BaseElement {
         to: string;
     };
     h: number;
+    /** `borderColor` border thickness in whole pixels, growing inward (default 1). */
+    strokeWidth?: number;
     type: 'rect';
     w: number;
     x: number;
@@ -73,16 +78,24 @@ export interface RectElement extends BaseElement {
 }
 /** Circle element. */
 export interface CircleElement extends BaseElement {
+    /** Shade the outline's pixels by coverage (default false). Outline only. */
+    antialias?: boolean;
     color?: string;
     cx: number;
     cy: number;
     fill?: boolean;
     radius: number;
+    /** Outline thickness in whole pixels, centered on the circle (default 1). Outline only. */
+    strokeWidth?: number;
     type: 'circle';
 }
 /** Line element. */
 export interface LineElement extends BaseElement {
+    /** Shade the line's pixels by coverage (default false). */
+    antialias?: boolean;
     color?: string;
+    /** Thickness in whole pixels, centered on the line (default 1). */
+    strokeWidth?: number;
     type: 'line';
     x0: number;
     x1: number;
@@ -132,6 +145,8 @@ export interface PixelsElement extends BaseElement {
 }
 /** Image element. */
 export interface ImageElement extends BaseElement {
+    /** Palette finish applied to the loaded image before it is drawn. */
+    finish?: Finish;
     fit?: 'contain' | 'cover' | 'fill';
     h?: number;
     kernel?: 'nearest' | 'lanczos3' | 'mitchell';
@@ -154,21 +169,45 @@ export interface SpriteElement extends BaseElement {
     y?: number;
 }
 export type SceneElement = TextElement | IconElement | RectElement | CircleElement | LineElement | ProgressElement | SparklineElement | BitmapElement | PixelsElement | ImageElement | SpriteElement;
+/** A sprite sheet downsampled to its cell grid. */
+type SpriteSheet = Awaited<ReturnType<typeof downsampleSprite>>;
 /**
  * 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.
+ * loader bakes an image's fit, kernel, size, and position into its canvas, and a
+ * `finish` is applied to a copy of it, so elements share a canvas only when they share
+ * a source, all of those, and a finish. Sprites are keyed by {@link spriteKey}.
  */
 export interface AssetCache {
     images: Map<ImageElement, Canvas>;
-    sprites: Map<string, Awaited<ReturnType<typeof downsampleSprite>>>;
+    sprites: Map<string, SpriteSheet>;
 }
+/**
+ * The message for an image source that was read but did not decode: the source as the
+ * caller passed it, then the decoder's reason. Only the reason's first line is kept —
+ * libvips repeats itself across several lines on a corrupt header.
+ */
+export declare function decodeFailureMessage(label: string, source: string, err: unknown): string;
 /**
  * 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.
  *
+ * Each distinct load runs once per call, however many elements share it: a URL is
+ * fetched once, a sprite sheet decodes once per grid, and an image decodes once per
+ * placement — source, fit, kernel, position, and size, all of which `loadImage` bakes
+ * into its canvas. `loadImage` decodes and places in one call, so a source placed two
+ * ways decodes twice. An image's `finish` runs once per placement and finish, on the
+ * placement's canvas, which it never mutates: elements differing only in `finish` share
+ * the decode and nothing after it.
+ *
  * `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.
+ *
+ * @throws {McpError} NotFound with `reason: 'asset_not_found'` for a missing or
+ *   unreadable path, a sprite path given as a URL, or a URL that cannot be fetched.
+ * @throws {McpError} InvalidParams with `reason: 'invalid_image'` for an image source
+ *   or sprite sheet that was read but did not decode.
+ * @throws {Error} The toolkit's `Unknown color` error for an unresolvable `finish`
+ *   palette entry.
  */
 export declare function preloadAssets(elements: SceneElement[], ctx: Context, size: PixooSize): Promise<AssetCache>;
 /** Apply a background spec to a canvas. */

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":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EACL,MAAM,EACN,gBAAgB,EAOhB,KAAK,SAAS,EAKf,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAEL,KAAK,UAAU,EAGf,KAAK,WAAW,EACjB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAGL,KAAK,WAAW,EAGhB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAA+B,KAAK,WAAW,EAAU,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAEpG,gCAAgC;AAChC,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IAAE,QAAQ,EAAE;QAAE,IAAI,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,GACjE;IAAE,KAAK,EAAE,SAAS,CAAA;CAAE,CAAC;AAEzB,yCAAyC;AACzC,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,+BAA+B;AAC/B,UAAU,WAAW;IACnB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oBAAoB;AACpB,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC9B,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,CAAC,EAAE,SAAS,CAAC;IACd,CAAC,CAAC,EAAE,SAAS,CAAC;CACf;AAED,oBAAoB;AACpB,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,SAAS,CAAC;IACd,CAAC,CAAC,EAAE,SAAS,CAAC;CACf;AAED,yBAAyB;AACzB,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,GAAG,GAAG,GAAG,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,sBAAsB;AACtB,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,oBAAoB;AACpB,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,2BAA2B;AAC3B,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wBAAwB;AACxB,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;IACtB,IAAI,EAAE,WAAW,CAAC;IAClB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,wCAAwC;AACxC,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,6BAA6B;AAC7B,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,IAAI,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,qBAAqB;AACrB,MAAM,WAAW,YAAa,SAAQ,WAAW;IAC/C,GAAG,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IACnC,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAC;IAC7C,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,OAAO,CAAC;IACd,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,sBAAsB;AACtB,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,CAAC,CAAC,EAAE,SAAS,CAAC;IACd,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,YAAY,GACpB,WAAW,GACX,WAAW,GACX,WAAW,GACX,aAAa,GACb,WAAW,GACX,eAAe,GACf,gBAAgB,GAChB,aAAa,GACb,aAAa,GACb,YAAY,GACZ,aAAa,CAAC;AAElB;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAClC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC;CACpE;AAyBD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,QAAQ,EAAE,YAAY,EAAE,EACxB,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,UAAU,CAAC,CAuCrB;AAED,2CAA2C;AAC3C,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,cAAc,GAAG,IAAI,CAyCxE;AAuED,iEAAiE;AACjE,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,YAAY,EAChB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,WAAW,EAAE,GAC3B,IAAI,CAwVN;AAED,+BAA+B;AAC/B,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,cAAc,EAC1B,QAAQ,EAAE,YAAY,EAAE,EACxB,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,EAAE,GAAG,EAAE,GAAG,EAAO,GACtB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,WAAW,EAAE,CAAA;CAAE,CAYlD;AAED,oCAAoC;AACpC,wBAAsB,WAAW,CAC/B,UAAU,EAAE,cAAc,EAC1B,QAAQ,EAAE,YAAY,EAAE,EACxB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,OAAO,EACZ,IAAI,GAAE,SAAc,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,aAAa,EAAE,WAAW,EAAE,CAAA;CAAE,CAAC,CAsB7D"}
+{"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

@@ -4,51 +4,115 @@
  */
 import * as fs from 'node:fs/promises';
 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 { Canvas, downsampleSprite, drawText, FONT_3x5, lerpColor, loadImage, measureText, renderSprite, renderSvgPath, resolveColor, } from '@cyanheads/pixoo-toolkit';
+import { finishFrame } from './finish.js';
 import { ICONS } from './icons.js';
 import { compileEffect, getKeyframeValue, interpolateColorKeyframe, } from './keyframes.js';
-import { fetchRemoteImageToTempPng, isRemoteSource } from './remote-image.js';
-import { drawStyledText, resolveX, resolveY, } from './text-engine.js';
+import { fetchRemoteImageBytes, isRemoteSource } from './remote-image.js';
+import { boxFits, drawStyledText, FONT_FACES, resolveX, resolveY, } from './text-engine.js';
 import { PALETTES, THEMES } from './themes.js';
+/** The cache key of a sprite sheet: its path and grid, which fix the downsample. */
+function spriteKey(el) {
+    return `${el.path}:${el.cols}:${el.rows}`;
+}
 /**
  * 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.
  *
- * @throws {McpError} NotFound with `reason: 'asset_not_found'` when the path is
- *   missing or unreadable.
+ * @throws {McpError} NotFound with `reason: 'asset_not_found'` and the calling tool's
+ *   declared recovery when the path is missing or unreadable.
  */
-async function assertReadableAsset(assetPath, label) {
+async function assertReadableAsset(assetPath, label, ctx) {
     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 });
+        throw notFound(`${label} not found or unreadable: "${assetPath}".`, { reason: 'asset_not_found', path: assetPath, ...ctx.recoveryFor('asset_not_found') }, { cause: err });
     }
 }
+/**
+ * The message for an image source that was read but did not decode: the source as the
+ * caller passed it, then the decoder's reason. Only the reason's first line is kept —
+ * libvips repeats itself across several lines on a corrupt header.
+ */
+export function decodeFailureMessage(label, source, err) {
+    const reason = (err instanceof Error ? err.message : String(err)).split('\n')[0];
+    return `${label} "${source}" could not be decoded: ${reason}.`;
+}
+/**
+ * The error for an image source or sprite sheet that was read but did not decode — a
+ * text file, an HTML page, a truncated download. Carries the calling tool's declared
+ * `invalid_image` recovery.
+ */
+function undecodableAsset(el, err, ctx) {
+    const [label, field, value] = el.type === 'image' ? ['Image source', 'source', el.source] : ['Sprite sheet', 'path', el.path];
+    return invalidParams(decodeFailureMessage(label, value, err), { reason: 'invalid_image', [field]: value, ...ctx.recoveryFor('invalid_image') }, { cause: err });
+}
+/**
+ * An image source as `loadImage` takes it: a URL's fetched bytes, or a local path
+ * confirmed readable.
+ */
+async function readImageSource(source, ctx) {
+    if (isRemoteSource(source))
+        return fetchRemoteImageBytes(source, ctx);
+    await assertReadableAsset(source, 'Image file', ctx);
+    return source;
+}
+/**
+ * Downsample a sprite element's sheet to its grid. The sheet must be a local file;
+ * a URL is refused without being fetched.
+ */
+async function loadSpriteSheet(el, ctx) {
+    if (isRemoteSource(el.path)) {
+        throw notFound(`Sprite sheet path "${el.path}" is a URL; sprite sheets take an absolute local path.`, { reason: 'asset_not_found', path: el.path, ...ctx.recoveryFor('asset_not_found') });
+    }
+    await assertReadableAsset(el.path, 'Sprite sheet', ctx);
+    return downsampleSprite(el.path, el.cols, el.rows).catch((err) => {
+        throw undecodableAsset(el, err, ctx);
+    });
+}
+/**
+ * The in-flight load for `key`, started by `load` on first request. Every caller
+ * awaits the same promise, so a failed load rejects each of them with one error.
+ */
+function loadOnce(loads, key, load) {
+    let pending = loads.get(key);
+    if (!pending) {
+        pending = load();
+        loads.set(key, pending);
+    }
+    return pending;
+}
 /**
  * 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.
  *
+ * Each distinct load runs once per call, however many elements share it: a URL is
+ * fetched once, a sprite sheet decodes once per grid, and an image decodes once per
+ * placement — source, fit, kernel, position, and size, all of which `loadImage` bakes
+ * into its canvas. `loadImage` decodes and places in one call, so a source placed two
+ * ways decodes twice. An image's `finish` runs once per placement and finish, on the
+ * placement's canvas, which it never mutates: elements differing only in `finish` share
+ * the decode and nothing after it.
+ *
  * `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.
+ *
+ * @throws {McpError} NotFound with `reason: 'asset_not_found'` for a missing or
+ *   unreadable path, a sprite path given as a URL, or a URL that cannot be fetched.
+ * @throws {McpError} InvalidParams with `reason: 'invalid_image'` for an image source
+ *   or sprite sheet that was read but did not decode.
+ * @throws {Error} The toolkit's `Unknown color` error for an unresolvable `finish`
+ *   palette entry.
  */
 export async function preloadAssets(elements, ctx, size) {
     const cache = { images: new Map(), sprites: new Map() };
+    const sourceLoads = new Map();
+    const imageLoads = new Map();
+    const sheetLoads = new Map();
     await Promise.all(elements.map(async (el) => {
         if (el.type === 'image') {
-            const source = el.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 remote = isRemoteSource(source);
-            if (!remote)
-                await assertReadableAsset(source, 'Image file');
-            const tmpPathToCleanup = remote ? await fetchRemoteImageToTempPng(source, ctx) : undefined;
-            const localPath = tmpPathToCleanup ?? source;
-            const loadOpts = {
+            const placement = {
                 size,
                 fit: el.fit ?? 'contain',
                 kernel: el.kernel ?? 'nearest',
@@ -56,22 +120,25 @@ export async function preloadAssets(elements, ctx, size) {
                 y: typeof el.y === 'number' ? el.y : 0,
             };
             if (el.w !== undefined)
-                loadOpts.width = el.w;
+                placement.width = el.w;
             if (el.h !== undefined)
-                loadOpts.height = el.h;
-            const canvas = await loadImage(localPath, loadOpts);
-            if (tmpPathToCleanup) {
-                fs.unlink(tmpPathToCleanup).catch(() => undefined);
-            }
+                placement.height = el.h;
+            const placed = JSON.stringify([el.source, placement]);
+            const load = () => loadOnce(imageLoads, placed, async () => {
+                const image = await loadOnce(sourceLoads, el.source, () => readImageSource(el.source, ctx));
+                return loadImage(image, placement).catch((err) => {
+                    throw undecodableAsset(el, err, ctx);
+                });
+            });
+            const { finish } = el;
+            const canvas = await (finish
+                ? loadOnce(imageLoads, JSON.stringify([el.source, placement, finish]), async () => finishFrame(await load(), finish))
+                : load());
             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);
-            }
+            const key = spriteKey(el);
+            cache.sprites.set(key, await loadOnce(sheetLoads, key, () => loadSpriteSheet(el, ctx)));
         }
     }));
     return cache;
@@ -164,8 +231,81 @@ function renderIconRamp(canvas, paths, svgViewBox, targetRect, stop) {
  * The element fits when the box lies wholly on the canvas.
  */
 function placedEntry(element, type, box, canvas) {
-    const fits = box.x >= 0 && box.y >= 0 && box.x + box.w <= canvas.width && box.y + box.h <= canvas.height;
-    return { element, type, box, fits, action: 'none' };
+    return { element, type, box, fits: boxFits(box, canvas.width, canvas.height), action: 'none' };
+}
+/** The element's stroke, each option at its default when omitted. */
+function strokeOf(el) {
+    return { width: el.strokeWidth ?? 1, antialias: el.antialias ?? false };
+}
+/**
+ * Whether the toolkit draws `stroke` as a band rather than a 1px Bresenham line or
+ * midpoint circle, whose pixels stay within the endpoints or the diameter.
+ */
+function isBand({ width, antialias }) {
+    return width > 1 || antialias;
+}
+/**
+ * The box of every pixel a band line lights, on the canvas or off it — the toolkit's stroke
+ * geometry: the major axis steps from one endpoint's pixel to the other's, and each step
+ * covers `width/2 · √(1 + slope²)` either side of the centerline. Aliased, the endpoints
+ * are floored and a pixel lights when its center lies in that half-open span; anti-aliased,
+ * the endpoints are exact and a pixel lights when it overlaps the span at all.
+ */
+function bandLineBox(ex0, ey0, ex1, ey1, { width, antialias }) {
+    const snap = antialias ? (v) => v : Math.floor;
+    const [x0, y0, x1, y1] = [snap(ex0), snap(ey0), snap(ex1), snap(ey1)];
+    const xMajor = Math.abs(x1 - x0) >= Math.abs(y1 - y0);
+    const [a0, b0, a1, b1] = xMajor ? [x0, y0, x1, y1] : [y0, x0, y1, x1];
+    const slope = a1 === a0 ? 0 : (b1 - b0) / (a1 - a0);
+    const half = (width / 2) * Math.sqrt(1 + slope * slope);
+    const first = Math.floor(Math.min(a0, a1));
+    const last = Math.floor(Math.max(a0, a1));
+    // The centerline is straight, so its first and last steps bound it
+    const [m0, m1] = [b0 + (first - a0) * slope, b0 + (last - a0) * slope];
+    const lo = Math.min(m0, m1) - half;
+    const hi = Math.max(m0, m1) + half;
+    const minorFirst = antialias ? Math.floor(lo - 0.5) + 1 : Math.ceil(lo);
+    const minorSpan = (antialias ? Math.ceil(hi + 0.5) : Math.ceil(hi)) - minorFirst;
+    const majorSpan = last - first + 1;
+    return xMajor
+        ? { x: first, y: minorFirst, w: majorSpan, h: minorSpan }
+        : { x: minorFirst, y: first, w: minorSpan, h: majorSpan };
+}
+/**
+ * The box of every pixel a band ring lights: each pixel center nearer the circle's center
+ * than `radius + width/2`, or `radius + width/2 + ½` anti-aliased, where the band's
+ * coverage runs out.
+ */
+function bandRingBox(cx, cy, radius, stroke) {
+    const reach = radius + stroke.width / 2 + (stroke.antialias ? 0.5 : 0);
+    const x = Math.floor(cx - reach) + 1;
+    const y = Math.floor(cy - reach) + 1;
+    return { x, y, w: Math.ceil(cx + reach) - x, h: Math.ceil(cy + reach) - y };
+}
+/**
+ * Composite an element's own scratch layer onto the canvas. `normal` lands each pixel
+ * source-over at its alpha × `opacity`, so a soft edge keeps its falloff as the element
+ * fades. Any other mode scales the layer's alpha by `opacity`, then blits the layer in
+ * that mode.
+ */
+function compositeLayer(canvas, layer, opacity, blend) {
+    const fade = opacity / 100;
+    if (blend === 'normal') {
+        for (let y = 0; y < layer.height; y++) {
+            for (let x = 0; x < layer.width; x++) {
+                const [r, g, b, a] = layer.getPixelRgba(x, y);
+                if (a > 0)
+                    canvas.blendPixel(x, y, [r, g, b], (a / 255) * fade);
+            }
+        }
+        return;
+    }
+    if (fade < 1) {
+        const { buffer } = layer;
+        for (let i = 3; i < buffer.length; i += 4)
+            buffer[i] = Math.round((buffer[i] ?? 0) * fade);
+    }
+    canvas.blit(layer, 0, 0, { mode: blend });
 }
 /** Render a single element onto a canvas at a specific frame. */
 export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets, layoutEntries) {
@@ -173,7 +313,7 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
     const kf = el.animate
         ? el.animate
         : el.effect
-            ? compileEffect(el.effect.name, el.effect, totalFrames)
+            ? compileEffect(el.effect.name, el.effect, totalFrames, elIdx)
             : undefined;
     const visible = kf
         ? Boolean(getKeyframeValue(kf, 'visible', frameIdx, el.visible ?? true))
@@ -188,8 +328,9 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
     // A keyframed `color` stands in for the element's own `color` on this frame.
     const colorFrames = kf?.['color'];
     const keyframedColor = colorFrames ? interpolateColorKeyframe(colorFrames, frameIdx) : undefined;
-    // If opacity < 100, render to scratch canvas and blit with alpha
-    const target = opacity < 100 ? new Canvas(canvas.width) : canvas;
+    // Under opacity or a blend mode, the element draws on its own layer, composited at the end
+    const blend = el.blend ?? 'normal';
+    const target = opacity < 100 || blend !== 'normal' ? new Canvas(canvas.width) : canvas;
     switch (el.type) {
         case 'text': {
             // A copy: the per-frame color must not stick to the caller's style object.
@@ -197,10 +338,10 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             const color = keyframedColor ?? el.color;
             if (!style.color && color)
                 style.color = color;
-            const fontVariant = el.font === 'compact' ? 'compact' : 'standard';
+            const fontVariant = el.font ?? 'standard';
             const px = el.x ?? 0;
             const py = el.y ?? 0;
-            const font = fontVariant === 'compact' ? FONT_3x5 : FONT_5x7;
+            const font = FONT_FACES[fontVariant];
             const scale = style.scale ?? 1;
             const textW = measureText(el.text, { font, scale });
             const textH = font.height * scale;
@@ -282,7 +423,9 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
                 target.fillRect(x, y, el.w, el.h, resolveColor(fill));
             }
             if (el.borderColor) {
-                target.drawRect(x, y, el.w, el.h, resolveColor(el.borderColor));
+                target.drawRect(x, y, el.w, el.h, resolveColor(el.borderColor), {
+                    width: el.strokeWidth ?? 1,
+                });
             }
             layoutEntries.push(placedEntry(elIdx, 'rect', { x, y, w: el.w, h: el.h }, canvas));
             break;
@@ -292,15 +435,18 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             const cy = el.cy + dy;
             const colorSpec = keyframedColor ?? el.color;
             const color = colorSpec ? resolveColor(colorSpec) : [255, 255, 255];
+            const stroke = strokeOf(el);
             if (el.fill !== false) {
                 target.fillCircle(cx, cy, el.radius, color);
             }
             else {
-                target.drawCircle(cx, cy, el.radius, color);
+                target.drawCircle(cx, cy, el.radius, color, stroke);
             }
-            // The circle covers its center pixel plus `radius` on each side.
+            // The circle covers its center pixel plus `radius` on each side; a band ring reaches past it.
             const diameter = el.radius * 2 + 1;
-            const box = { x: cx - el.radius, y: cy - el.radius, w: diameter, h: diameter };
+            const box = el.fill === false && isBand(stroke)
+                ? bandRingBox(cx, cy, el.radius, stroke)
+                : { x: cx - el.radius, y: cy - el.radius, w: diameter, h: diameter };
             layoutEntries.push(placedEntry(elIdx, 'circle', box, canvas));
             break;
         }
@@ -311,14 +457,17 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             const y0 = el.y0 + dy;
             const x1 = el.x1 + dx;
             const y1 = el.y1 + dy;
-            target.drawLine(x0, y0, x1, y1, color);
-            // Both endpoints are drawn, so the line spans one pixel more than their distance.
-            const box = {
-                x: Math.min(x0, x1),
-                y: Math.min(y0, y1),
-                w: Math.abs(x1 - x0) + 1,
-                h: Math.abs(y1 - y0) + 1,
-            };
+            const stroke = strokeOf(el);
+            target.drawLine(x0, y0, x1, y1, color, stroke);
+            // A 1px line draws both endpoints, so it spans one pixel more than their distance.
+            const box = isBand(stroke)
+                ? bandLineBox(x0, y0, x1, y1, stroke)
+                : {
+                    x: Math.min(x0, x1),
+                    y: Math.min(y0, y1),
+                    w: Math.abs(x1 - x0) + 1,
+                    h: Math.abs(y1 - y0) + 1,
+                };
             layoutEntries.push(placedEntry(elIdx, 'line', box, canvas));
             break;
         }
@@ -441,8 +590,7 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             break;
         }
         case 'sprite': {
-            const key = `${el.path}:${el.cols}:${el.rows}`;
-            const sprite = assets.sprites.get(key);
+            const sprite = assets.sprites.get(spriteKey(el));
             if (sprite) {
                 const scale = el.scale ?? 1;
                 const spriteW = sprite.cols * scale;
@@ -468,18 +616,8 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             break;
         }
     }
-    // Blit scratch canvas onto main if we used opacity
-    if (opacity < 100 && target !== canvas) {
-        const alpha = opacity / 100;
-        for (let py_ = 0; py_ < canvas.height; py_++) {
-            for (let px_ = 0; px_ < canvas.width; px_++) {
-                const [r, g, b, a] = target.getPixelRgba(px_, py_);
-                if (a > 0) {
-                    canvas.blendPixel(px_, py_, [r, g, b], alpha);
-                }
-            }
-        }
-    }
+    if (target !== canvas)
+        compositeLayer(canvas, target, opacity, blend);
 }
 /** Render a complete frame. */
 export function renderFrame(frameIdx, totalFrames, background, elements, assets, size = 64) {