@cyanheads/pixoo-mcp-server 1.2.1 → 1.2.2

package/AGENTS.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** pixoo-mcp-server
-**Version:** 1.2.1
+**Version:** 1.2.2
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.9`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0 (protocol revision 2026-07-28 alongside the 2025 era)
@@ -187,6 +187,7 @@ Pixoo-specific error reasons declared on tools:
 | `device_rejected` | `ServiceUnavailable` | Firmware returned non-zero `error_code` | — |
 | `no_device_configured` | `InvalidParams` | Device tool called without `PIXOO_IP` | — |
 | `asset_not_found` | `NotFound` | Image/sprite path or URL unreadable | — |
+| `invalid_image` | `InvalidParams` | Image source or sprite path read but not decodable | — |
 | `invalid_color` | `InvalidParams` | `resolveColor` throw — invalid color name or format | — |
 | `unknown_icon` | `InvalidParams` | Icon name not in registry | — |
 | `discovery_failed` | `ServiceUnavailable` | Divoom cloud unreachable | `true` |
@@ -234,11 +235,13 @@ src/
     text-engine.ts                      # Gradient ramp + shadow + outline text engine, overflow handling
     scene-renderer.ts                   # Element vocabulary, layout resolver, frame rendering
     keyframes.ts                        # Keyframe interpolation + animation preset compiler
+    finish.ts                           # Palette finish (quantize + dither) for one frame, or frames sharing one palette
     preview.ts                          # PNG/contact-sheet/GIF encoding
-    remote-image.ts                     # https image fetch to a temp file for the toolkit loader; stops on ctx.signal
+    remote-image.ts                     # https image fetch into memory for the toolkit loader; stops on ctx.signal
   mcp-server/
     tools/
       device-push.ts                    # Shared post-render push: preview kept on failure, visibility notice
+      finish-schema.ts                  # Shared `finish` input schema (colors | palette, plus dither)
     tools/definitions/
       pixoo-display-text.tool.ts
       pixoo-compose-scene.tool.ts

package/CLAUDE.md

@@ -1,7 +1,7 @@
 # Developer Protocol
 
 **Server:** pixoo-mcp-server
-**Version:** 1.2.1
+**Version:** 1.2.2
 **Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.9`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` ^2.1.0 (protocol revision 2026-07-28 alongside the 2025 era)
@@ -187,6 +187,7 @@ Pixoo-specific error reasons declared on tools:
 | `device_rejected` | `ServiceUnavailable` | Firmware returned non-zero `error_code` | — |
 | `no_device_configured` | `InvalidParams` | Device tool called without `PIXOO_IP` | — |
 | `asset_not_found` | `NotFound` | Image/sprite path or URL unreadable | — |
+| `invalid_image` | `InvalidParams` | Image source or sprite path read but not decodable | — |
 | `invalid_color` | `InvalidParams` | `resolveColor` throw — invalid color name or format | — |
 | `unknown_icon` | `InvalidParams` | Icon name not in registry | — |
 | `discovery_failed` | `ServiceUnavailable` | Divoom cloud unreachable | `true` |
@@ -234,11 +235,13 @@ src/
     text-engine.ts                      # Gradient ramp + shadow + outline text engine, overflow handling
     scene-renderer.ts                   # Element vocabulary, layout resolver, frame rendering
     keyframes.ts                        # Keyframe interpolation + animation preset compiler
+    finish.ts                           # Palette finish (quantize + dither) for one frame, or frames sharing one palette
     preview.ts                          # PNG/contact-sheet/GIF encoding
-    remote-image.ts                     # https image fetch to a temp file for the toolkit loader; stops on ctx.signal
+    remote-image.ts                     # https image fetch into memory for the toolkit loader; stops on ctx.signal
   mcp-server/
     tools/
       device-push.ts                    # Shared post-render push: preview kept on failure, visibility notice
+      finish-schema.ts                  # Shared `finish` input schema (colors | palette, plus dither)
     tools/definitions/
       pixoo-display-text.tool.ts
       pixoo-compose-scene.tool.ts

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-1.2.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pixoo-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.1.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pixoo-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pixoo-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-1.2.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/pixoo-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.1.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/pixoo-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/pixoo-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.2-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -31,7 +31,7 @@ Divoom Pixoo LED matrix displays on the local network, with the Pixoo-64 as the
 |:---|:---|
 | `pixoo_display_text` | Render styled text with themes, gradients, shadows, and auto-fit, static or animated, and push it |
 | `pixoo_compose_scene` | Compose layered scenes of text, icons, widgets, shapes, bitmaps, images, and sprites, static or animated |
-| `pixoo_push_image` | Resize a local or https image to the LED grid and push it |
+| `pixoo_push_image` | Resize a local or https image to the LED grid and push it, an animated GIF or WebP as an animation |
 | `pixoo_overlay_text` | Set or clear a device-rendered scrolling text overlay |
 | `pixoo_control_device` | Read or change brightness, screen state, channel, or clock face |
 | `pixoo_discover_devices` | Find Pixoo devices and their LAN IPs through Divoom's cloud discovery |
@@ -53,15 +53,17 @@ Tools cover the same ground for tool-only clients: `pixoo_control_device` reads
 ### `pixoo_display_text` <sub>tool</sub>
 
 - `text` as a string or an array of lines; `theme` (`midnight`, `ember`, `claude`, `ice`, `neon`, `forest`, `mono`) sets the background and default palette. `style` takes a `palette` ramp (`ember`, `ice`, `neon`, `fire`, `lavender`, `claude`, `mono`) or a custom `{ from, to }`, plus `shadow`, `outline`, and `scale` 1–8; `position` is semantic or in pixels, and `align` lines up multi-line text
-- `layout[]` reports every fit decision as an `action` (`shrunk-to-compact`, `scrolling`, `truncated`, …). Single-line text falls back from the standard to the compact font unless `font` is set, and text still too wide only scrolls under `effect: "auto"` or `"scroll"`
+- `font`: `standard` (5×7) and `compact` (3×5) draw printable ASCII plus `° ← ↑ → ↓ ▲ ▼ ♥ · …`; `numerals` is an 11×18 digit face for clocks and readouts that draws 0–9, space, and `: . - + / % ° ?`, and text holding any other character fails validation, naming those characters
+- `layout[]` reports every fit decision as an `action` (`none`, `shrunk-to-compact`, or `scrolling`), the `font` used, and whether each line's box `fits` on the panel; a scrolling line's box starts at x 0, where its static frame draws it. Single-line text falls back from the standard to the compact font unless `font` is set — never to `numerals` — and text still too wide only scrolls under `effect: "auto"` or `"scroll"`
 - `effect`: `scroll` makes one pass in up to 40 frames, `auto` scrolls only on overflow, and `float` and `pulse` loop over 20 frames; `frames` reports the count, and the animation pushes as one device animation
 
 ---
 
 ### `pixoo_compose_scene` <sub>tool</sub>
 
-- Up to 50 `elements` drawn back-to-front: `text`, `icon`, `rect`, `circle`, `line`, `progress`, `sparkline`, `bitmap`, `pixels`, `image` (absolute path or https URL), `sprite` (absolute path). The `background` is a solid color, a `v` / `h` / `r` gradient, or a `theme`
-- Returns `layout[]`: each element's placed box and whether it `fits` on the panel. An absolute `output` path saves the first frame as a PNG in place of the `PIXOO_OUTPUT_DIR` auto-save. Typed failures: `asset_not_found`, `invalid_color`, `unknown_icon`, `invalid_output_path`
+- Up to 50 `elements` drawn back-to-front: `text` (in the same three fonts as `pixoo_display_text`), `icon`, `rect`, `circle`, `line`, `progress`, `sparkline`, `bitmap`, `pixels`, `image` (absolute path or https URL, with the same `finish` as `pixoo_push_image`), `sprite` (absolute path). The `background` is a solid color, a `v` / `h` / `r` gradient, or a `theme`
+- Every element takes `opacity` (each pixel lands at its own alpha × `opacity`, so soft edges fade evenly) and `blend`: `normal`, `add` (glows and light beams), `screen`, or `multiply`. `line` and outline `circle` take `strokeWidth` and `antialias`, and a `rect` border takes `strokeWidth`, growing inward; either field on a shape that draws no stroke fails validation, naming it
+- Returns `layout[]`: each element's placed box — for a wide or anti-aliased stroke, every pixel it draws — and whether it `fits` on the panel. An absolute `output` path saves the first frame as a PNG in place of the `PIXOO_OUTPUT_DIR` auto-save. Typed failures: `asset_not_found`, `invalid_image` (an image or sprite that was read but does not decode), `invalid_color`, `unknown_icon`, `invalid_output_path`
 - Animation through per-element `effect` presets (`float`, `scroll-left`, `scroll-right`, `pulse`, `blink`, `twinkle`, `drift`, `fade-in`, `fade-out`) or raw `animate` keyframes over `dx`, `dy`, `opacity` (numbers or numeric strings), `visible` (`true`/`false`), and `color` (interpolated through RGB on any element with a `color`), each track holding at least one keyframe; `frames` 1–40, `speed` 10–2000 ms per frame (default 150). An effect's `amplitude` sets the movement of `float`, `scroll-*`, and `drift`, and the 0–1 depth of the `pulse` and `twinkle` opacity dip
 
 ---
@@ -69,7 +71,9 @@ Tools cover the same ground for tool-only clients: `pixoo_control_device` reads
 ### `pixoo_push_image` <sub>tool</sub>
 
 - `source` is an absolute local path or an https URL, with downloads capped at 10 MB; `fit` is `contain` (default), `cover`, or `fill`, and `kernel` is `nearest` (default, for pixel art), `lanczos3` (photos), or `mitchell`
-- An unreadable path or URL fails as `asset_not_found`; the preview is the exact resized frame the device receives
+- A source that decodes as an animated GIF or WebP, whatever its file name, pushes as an animation of up to 40 frames, sampled evenly from a longer source. It plays at the source's total duration over the pushed frame count (150 ms when the source records no delays), or at `speed` (10–2000 ms per frame); `frames`, `sourceFrames`, and `speed` report what was pushed
+- `finish` reduces the image to a palette before the push: exactly one of `colors` (2–256, built from the image) or `palette` (1–256 hex or named colors), plus `dither` (`none`, `bayer4`, `floyd-steinberg`). Transparent pixels stay unlit, and an animation's `colors` palette is shared by every frame
+- An unreadable path or URL fails as `asset_not_found`, a source that is read but does not decode (a text file, an HTML page, a truncated download) fails as `invalid_image`, and an unresolvable `finish` palette entry fails as `invalid_color`; the preview is the exact frame the device receives, or a grid of every frame for an animation
 
 ---
 
@@ -135,7 +139,7 @@ Pixoo-specific:
 
 - All composition happens on the host in an RGBA canvas pipeline (`@cyanheads/pixoo-toolkit`); the device receives finished RGB frames
 - Pushes switch the device to the custom channel and run one at a time, spaced by `PIXOO_PUSH_MIN_INTERVAL_MS` (default 1000) so rapid pushes don't freeze the device
-- Animations cap at 40 frames, past which the device becomes unstable
+- Animations cap at 40 frames, past which the device becomes unstable; `pixoo_push_image` samples a longer GIF or WebP down to 40
 
 Agent-friendly output:
 
@@ -300,10 +304,10 @@ The Dockerfile defaults to HTTP transport, stateless session mode, and logs to `
 |:---|:---|
 | `src/index.ts` | `createApp()` entry point: registers tools and resources and initializes the Pixoo service. |
 | `src/config/` | Server-specific environment variable parsing and validation with Zod. |
-| `src/mcp-server/tools/` | Tool definitions (`*.tool.ts`) and the shared post-render push path. |
+| `src/mcp-server/tools/` | Tool definitions (`*.tool.ts`), the shared post-render push path, and the shared `finish` input schema. |
 | `src/mcp-server/resources/` | Resource definitions (`*.resource.ts`). |
 | `src/services/pixoo/` | `PixooService`: wraps `@cyanheads/pixoo-toolkit` with push pacing, result mapping, and device state reads. |
-| `src/renderer/` | Pure rendering pipeline with no device dependency: element renderers, styled-text engine, themes, icons, effect compiler, preview encoding, remote image fetch. |
+| `src/renderer/` | Pure rendering pipeline with no device dependency: element renderers, styled-text engine, themes, icons, effect compiler, palette finishing, preview encoding, remote image fetch. |
 | `tests/` | Unit and integration tests mirroring `src/`. |
 
 ## Development guide

package/changelog/1.2.x/1.2.2.md

@@ -0,0 +1,40 @@
+---
+summary: "Adopts @cyanheads/pixoo-toolkit 0.10.0: animated GIF and WebP push as animations, images take a palette finish, scene elements take blend modes and stroke widths, and text gains a numerals face. Undecodable images fail as invalid_image, and filled circles and JPEG/WebP images render differently."
+breaking: false
+security: false
+---
+
+# 1.2.2 — 2026-09-26
+
+## Added
+
+- **`finish` on `pixoo_push_image` and scene `image` elements** reduces the image to a palette: `colors` (2–256) or `palette` (1–256 colors), plus `dither` (`none`, `bayer4`, `floyd-steinberg`) ([#27](https://github.com/cyanheads/pixoo-mcp-server/issues/27)). An animation's `colors` palette is shared across frames; a bad palette entry fails as `invalid_color`.
+- **`blend` on every `pixoo_compose_scene` element** — `normal` (default), `add`, `screen`, or `multiply` ([#29](https://github.com/cyanheads/pixoo-mcp-server/issues/29)).
+- **`strokeWidth` and `antialias` on `line` and outline `circle`; `strokeWidth` on a `rect` border**, growing inward (#29). Either on a shape that draws no stroke fails `-32602` naming it; a wide or anti-aliased stroke's layout box covers every pixel drawn.
+- **`font: "numerals"`** on `pixoo_display_text` and scene `text` — an 11×18 digit face drawing 0–9, space, and `: . - + / % ° ?`; any other character fails `-32602` naming it, and auto-fit never picks it ([#30](https://github.com/cyanheads/pixoo-mcp-server/issues/30)).
+- **`pixoo_push_image` `speed` input and `frames`, `sourceFrames`, `speed` output fields** for animated sources ([#28](https://github.com/cyanheads/pixoo-mcp-server/issues/28)).
+- **`pixoo_output_dir` and `pixoo_push_min_interval_ms` options in `manifest.json`**, so a Claude Desktop bundle install can set `PIXOO_OUTPUT_DIR` and `PIXOO_PUSH_MIN_INTERVAL_MS`.
+
+## Changed
+
+- **An animated GIF or WebP given to `pixoo_push_image` pushes as an animation** instead of its first frame, whatever its file extension (#28). Up to 40 frames, sampled evenly from a longer source, play at the source's total duration over the pushed frame count.
+- **Filled `circle` elements draw a rounder disc** (`dx² + dy² ≤ r² + r`, from the toolkit), so every filled circle's pixels change.
+- **JPEG and WebP images decode at full resolution before resizing** (from the toolkit), so their pushed pixels change.
+- **An image source that is read but does not decode fails as `-32602` `invalid_image`** naming the source and the decoder's reason, instead of an unclassified `-32603`, in `pixoo_push_image` and compose `image` and `sprite` elements ([#34](https://github.com/cyanheads/pixoo-mcp-server/issues/34)).
+- **`asset_not_found` carries its tool's declared recovery hint, reworded, on both image tools**, and a sprite `path` given as a URL says sprite sheets take a local path ([#51](https://github.com/cyanheads/pixoo-mcp-server/issues/51)).
+- **https image sources load from memory** — they render when the temp dir is unwritable, and an https SVG renders like the same local file instead of rasterizing at its intrinsic size ([#23](https://github.com/cyanheads/pixoo-mcp-server/issues/23)).
+- **A partially transparent pixel under `opacity` below 100 fades at its own alpha × opacity**, so soft-edged images no longer brighten as they fade (#29).
+- **`twinkle` renders the same frames for the same input**; its jitter comes from the frame index and element position ([#50](https://github.com/cyanheads/pixoo-mcp-server/issues/50)).
+- **`pixoo_display_text` reports `fits: false` for text leaving the panel on any edge** ([#49](https://github.com/cyanheads/pixoo-mcp-server/issues/49)), and a scrolling line reports `box.x: 0`, where its frame draws it ([#55](https://github.com/cyanheads/pixoo-mcp-server/issues/55)).
+- **`standard` and `compact` draw `° ← ↑ → ↓ ▲ ▼ ♥ · …` as glyphs** instead of `?` (#30).
+- **`Object.prototype` names such as `constructor` fail as `invalid_color`** on every color input of `pixoo_compose_scene`, `pixoo_display_text`, and `pixoo_overlay_text`, which now rejects them before any device call ([#32](https://github.com/cyanheads/pixoo-mcp-server/issues/32)).
+- **`pixoo_design_brief` and the design guide** describe dithering, anti-aliasing, the new glyphs and numerals face, a glow recipe, and the Pixoo-64's measured dark and mid-level response.
+
+## Fixed
+
+- **`pixoo_compose_scene` loads each distinct asset once per call** — elements sharing a sprite sheet, or an image source and placement, share one decode, and a URL is fetched once ([#52](https://github.com/cyanheads/pixoo-mcp-server/issues/52)).
+- **Standard text at scale 2 is 14 px tall** in the design brief and guide, which said 10 px.
+
+## Dependencies
+
+- `@cyanheads/pixoo-toolkit` ^0.8.2 → ^0.10.0, exempt from the `bunfig.toml` release-age hold beside the framework

package/dist/mcp-server/resources/definitions/pixoo-design-guide.resource.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixoo-design-guide.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/pixoo-design-guide.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAwGrD,eAAO,MAAM,wBAAwB,2GAyBnC,CAAC"}
+{"version":3,"file":"pixoo-design-guide.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/pixoo-design-guide.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAY,CAAC,EAAE,MAAM,wBAAwB,CAAC;AA2GrD,eAAO,MAAM,wBAAwB,2GAyBnC,CAAC"}

package/dist/mcp-server/resources/definitions/pixoo-design-guide.resource.js

@@ -13,8 +13,10 @@ At typical viewing distance for a 64×64 LED display:
 - **Minimum eye size:** 1–2px across; 2×2 fills are more reliable than single pixels
 - **Minimum limb gap:** 2 rows between horizontal elements prevents blur
 - **Font choices:**
-  - Standard (5×7): default for all text. Readable at 1× scale. Excellent at 2× (10px tall = chunky block letters)
+  - Standard (5×7): default for all text. Readable at 1× scale. Excellent at 2× (14px tall = chunky block letters)
   - Compact (3×5): secondary text, captions, labels when space is tight
+  - Standard and compact both draw printable ASCII plus \`° ← ↑ → ↓ ▲ ▼ ♥ · …\` for units, trends, and separators
+  - Numerals (11×18): clocks and hero readouts. Draws 0–9, space, and \`: . - + / % ° ?\` only, each digit on one 13px advance so a changing value keeps its width. Auto-fit never picks it; text holding any other character is rejected, so units and labels go in their own standard or compact text element
   - Scale ≥2: decorative or hero use only — verify fit before pushing
 
 ## Palette Discipline
@@ -103,6 +105,7 @@ At typical viewing distance for a 64×64 LED display:
 - **getConfig() omits SelectIndex** on current Pixoo-64 firmware — use getChannel() for reliable channel reads
 - **Text overlays (pixoo_overlay_text)** persist across channel switches until explicitly cleared
 - **Discovery requires internet** — Divoom cloud endpoint even for local device control
+- **Dark and mid levels render darker than on a monitor** — on a Pixoo-64 at brightness 100, channel levels 0–4 stay dark, and mid-levels render darker than on an sRGB monitor, shifting muted warm colors toward red (\`#D97757\` reads red). Previews show the sRGB values pushed, not the panel's response.
 `;
 export const pixooDesignGuideResource = resource('pixoo://reference/design-guide', {
     name: 'design-guide',

package/dist/mcp-server/resources/definitions/pixoo-design-guide.resource.js.map

@@ -1 +1 @@
-{"version":3,"file":"pixoo-design-guide.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/pixoo-design-guide.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAErD,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoGpB,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAC,gCAAgC,EAAE;IACjF,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,uNAAuN;IACzN,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACpB,qEAAqE;IACrE,SAAS,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE;IAEtD,OAAO,CAAC,OAAO,EAAE,IAAI;QACnB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,gCAAgC;gBACrC,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,eAAe;gBACzB,WAAW,EACT,iFAAiF;aACpF;SACF;KACF,CAAC;CACH,CAAC,CAAC"}
+{"version":3,"file":"pixoo-design-guide.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/pixoo-design-guide.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAErD,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuGpB,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG,QAAQ,CAAC,gCAAgC,EAAE;IACjF,IAAI,EAAE,cAAc;IACpB,KAAK,EAAE,oBAAoB;IAC3B,WAAW,EACT,uNAAuN;IACzN,QAAQ,EAAE,eAAe;IACzB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;IACpB,qEAAqE;IACrE,SAAS,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE;IAEtD,OAAO,CAAC,OAAO,EAAE,IAAI;QACnB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QACjB,SAAS,EAAE;YACT;gBACE,GAAG,EAAE,gCAAgC;gBACrC,IAAI,EAAE,cAAc;gBACpB,QAAQ,EAAE,eAAe;gBACzB,WAAW,EACT,iFAAiF;aACpF;SACF;KACF,CAAC;CACH,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/pixoo-compose-scene.tool.d.ts

@@ -29,6 +29,12 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     elements: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -69,6 +75,7 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
         color: z.ZodOptional<z.ZodString>;
         font: z.ZodOptional<z.ZodEnum<{
             compact: "compact";
+            numerals: "numerals";
             standard: "standard";
         }>>;
         style: z.ZodOptional<z.ZodObject<{
@@ -92,6 +99,12 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -146,6 +159,12 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -186,9 +205,16 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
             to: z.ZodString;
         }, z.core.$strip>>;
         borderColor: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -220,9 +246,17 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
         radius: z.ZodNumber;
         color: z.ZodOptional<z.ZodString>;
         fill: z.ZodOptional<z.ZodBoolean>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        antialias: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -254,9 +288,17 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
         x1: z.ZodNumber;
         y1: z.ZodNumber;
         color: z.ZodOptional<z.ZodString>;
+        strokeWidth: z.ZodOptional<z.ZodNumber>;
+        antialias: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -303,6 +345,12 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -342,6 +390,12 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -375,6 +429,12 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -409,6 +469,12 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -450,9 +516,30 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
             mitchell: "mitchell";
             nearest: "nearest";
         }>>;
+        finish: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            colors: z.ZodNumber;
+            dither: z.ZodDefault<z.ZodEnum<{
+                bayer4: "bayer4";
+                "floyd-steinberg": "floyd-steinberg";
+                none: "none";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            palette: z.ZodArray<z.ZodString>;
+            dither: z.ZodDefault<z.ZodEnum<{
+                bayer4: "bayer4";
+                "floyd-steinberg": "floyd-steinberg";
+                none: "none";
+            }>>;
+        }, z.core.$strict>]>>;
     }, z.core.$strip>, z.ZodObject<{
         visible: z.ZodOptional<z.ZodBoolean>;
         opacity: z.ZodOptional<z.ZodNumber>;
+        blend: z.ZodOptional<z.ZodEnum<{
+            add: "add";
+            multiply: "multiply";
+            normal: "normal";
+            screen: "screen";
+        }>>;
         dx: z.ZodOptional<z.ZodNumber>;
         dy: z.ZodOptional<z.ZodNumber>;
         effect: z.ZodOptional<z.ZodObject<{
@@ -519,6 +606,7 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
         }>;
         font: z.ZodOptional<z.ZodEnum<{
             compact: "compact";
+            numerals: "numerals";
             standard: "standard";
         }>>;
         scale: z.ZodOptional<z.ZodNumber>;
@@ -559,8 +647,14 @@ export declare const pixooComposeScene: import("@cyanheads/mcp-ts-core").ToolDef
 }, {
     readonly reason: "asset_not_found";
     readonly code: JsonRpcErrorCode.NotFound;
-    readonly when: "An image or sprite path could not be read.";
-    readonly recovery: "Verify the file path exists and is readable, or check the URL is reachable.";
+    readonly when: "An image source or sprite path could not be read, a sprite path was a URL, or an image URL could not be fetched.";
+    readonly recovery: "Pass an absolute path to an existing, readable image file, or for an image source a reachable https URL serving 10 MiB or less; sprite sheets take an absolute local path.";
+    readonly thrownBy: "service";
+}, {
+    readonly reason: "invalid_image";
+    readonly code: JsonRpcErrorCode.InvalidParams;
+    readonly when: "An image source or sprite path was read but did not decode as an image.";
+    readonly recovery: "Each image source and sprite path must be a complete PNG, JPEG, GIF, WebP, AVIF, TIFF, or SVG image; a text file, an HTML page, or a truncated download will not decode.";
     readonly thrownBy: "service";
 }, {
     readonly reason: "invalid_color";

package/dist/mcp-server/tools/definitions/pixoo-compose-scene.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pixoo-compose-scene.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/pixoo-compose-scene.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAmW3E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqT5B,CAAC"}
+{"version":3,"file":"pixoo-compose-scene.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/pixoo-compose-scene.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAY,MAAM,+BAA+B,CAAC;AAwb3E,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA8T5B,CAAC"}

package/dist/mcp-server/tools/definitions/pixoo-compose-scene.tool.js

@@ -8,10 +8,12 @@ import { JsonRpcErrorCode, McpError } from '@cyanheads/mcp-ts-core/errors';
 import { Canvas, NAMED_COLORS, savePng } from '@cyanheads/pixoo-toolkit';
 import { getServerConfig } from '../../../config/server-config.js';
 import { pushKeepingPreview, visibilityNotice } from '../device-push.js';
+import { FinishSchema } from '../finish-schema.js';
 import { ICONS } from '../../../renderer/icons.js';
 import { numericValue } from '../../../renderer/keyframes.js';
 import { autoSavePreview, buildContactSheet, saveGifPreview, savePngPreview, } from '../../../renderer/preview.js';
 import { renderScene } from '../../../renderer/scene-renderer.js';
+import { describeMissingNumerals, FONT_VARIANTS, missingNumeralGlyphs, } from '../../../renderer/text-engine.js';
 import { getPixooService } from '../../../services/pixoo/pixoo-service.js';
 // --- Shared sub-schemas ---
 const EffectSchema = z
@@ -67,6 +69,10 @@ const AnimateSchema = z
 const BaseElementProps = {
     visible: z.boolean().optional().describe('Whether the element is visible (default: true).'),
     opacity: z.number().int().min(0).max(100).optional().describe('Opacity 0–100 (default: 100).'),
+    blend: z
+        .enum(['normal', 'add', 'screen', 'multiply'])
+        .optional()
+        .describe('How the element combines with what lies beneath it (default: normal, drawn over it). add sums the light of both, clamped at full brightness — for glows and light beams; screen brightens more gently; multiply darkens.'),
     dx: z.number().int().optional().describe('X offset nudge in pixels.'),
     dy: z.number().int().optional().describe('Y offset nudge in pixels.'),
     effect: EffectSchema.optional().describe('Named animation preset for this element.'),
@@ -107,15 +113,31 @@ const StyleSchema = z
 })
     .describe('Text style options.');
 // --- Element schemas ---
-const TextElementSchema = z.object({
+const TextElementSchema = z
+    .object({
     type: z.literal('text').describe('Text element type.'),
     text: z.string().describe('Text content to render.'),
     x: XPosSchema.optional().describe('X position (default: 0).'),
     y: YPosSchema.optional().describe('Y position (default: 0).'),
     color: z.string().optional().describe('Flat text color.'),
-    font: z.enum(['standard', 'compact']).optional().describe('Font variant.'),
+    font: z
+        .enum(FONT_VARIANTS)
+        .optional()
+        .describe('Font variant (default: standard): standard (5×7) or compact (3×5), each printable ASCII plus ° ← ↑ → ↓ ▲ ▼ ♥ · …; or numerals (11×18 digits for clocks and readouts), which draws only 0–9, space, and : . - + / % ° ?, so text holding any other character is rejected — put units and labels in a separate standard or compact text element.'),
     style: StyleSchema.optional().describe('Text style options.'),
     ...BaseElementProps,
+})
+    .superRefine((el, ctx) => {
+    if (el.font !== 'numerals')
+        return;
+    const missing = missingNumeralGlyphs(el.text);
+    if (missing.length === 0)
+        return;
+    ctx.addIssue({
+        code: 'custom',
+        path: ['text'],
+        message: `${describeMissingNumerals(missing)} Put units and labels in a separate text element in the standard or compact font.`,
+    });
 });
 const IconElementSchema = z.object({
     type: z.literal('icon').describe('Icon element type.'),
@@ -133,7 +155,8 @@ const IconElementSchema = z.object({
         .describe("Named palette painted as a top-to-bottom color ramp from the icon's top row to its bottom row. Takes precedence over color."),
     ...BaseElementProps,
 });
-const RectElementSchema = z.object({
+const RectElementSchema = z
+    .object({
     type: z.literal('rect').describe('Rectangle element type.'),
     x: z.number().int().describe('X coordinate.'),
     y: z.number().int().describe('Y coordinate.'),
@@ -148,17 +171,51 @@ const RectElementSchema = z.object({
     })
         .optional()
         .describe('Gradient fill.'),
-    borderColor: z.string().optional().describe('1px border color.'),
+    borderColor: z
+        .string()
+        .optional()
+        .describe('Border color. The border is drawn inside the rect, strokeWidth pixels thick.'),
+    strokeWidth: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Border thickness in whole pixels, growing inward from the rect edge (default: 1). Requires borderColor.'),
     ...BaseElementProps,
+})
+    .refine((el) => el.strokeWidth === undefined || Boolean(el.borderColor), {
+    error: 'strokeWidth sets the thickness of the borderColor border; set borderColor, or drop strokeWidth.',
+    path: ['strokeWidth'],
 });
-const CircleElementSchema = z.object({
+/** The error for a stroke field on a circle that fills, which draws no outline. */
+const filledCircleError = (field) => `${field} applies to an outline circle only; set fill: false, or drop ${field}.`;
+const CircleElementSchema = z
+    .object({
     type: z.literal('circle').describe('Circle element type.'),
     cx: z.number().int().describe('Center X coordinate.'),
     cy: z.number().int().describe('Center Y coordinate.'),
     radius: z.number().int().min(1).describe('Radius in pixels.'),
     color: z.string().optional().describe('Circle color.'),
     fill: z.boolean().optional().describe('Filled or outline only (default: true).'),
+    strokeWidth: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Outline thickness in whole pixels, centered on the circle (default: 1). Outline circles only (fill: false).'),
+    antialias: z
+        .boolean()
+        .optional()
+        .describe('Shade each outline pixel by how much of it the ring covers, for a smooth curve (default: false, hard pixel edges). Outline circles only (fill: false).'),
     ...BaseElementProps,
+})
+    .refine((el) => el.fill === false || el.strokeWidth === undefined, {
+    error: filledCircleError('strokeWidth'),
+    path: ['strokeWidth'],
+})
+    .refine((el) => el.fill === false || el.antialias === undefined, {
+    error: filledCircleError('antialias'),
+    path: ['antialias'],
 });
 const LineElementSchema = z.object({
     type: z.literal('line').describe('Line element type.'),
@@ -167,6 +224,16 @@ const LineElementSchema = z.object({
     x1: z.number().int().describe('End X coordinate.'),
     y1: z.number().int().describe('End Y coordinate.'),
     color: z.string().optional().describe('Line color.'),
+    strokeWidth: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Line thickness in whole pixels, centered on the line (default: 1).'),
+    antialias: z
+        .boolean()
+        .optional()
+        .describe('Shade each pixel by how much of it the line covers, for smooth diagonals (default: false, hard pixel edges).'),
     ...BaseElementProps,
 });
 const ProgressElementSchema = z.object({
@@ -240,6 +307,7 @@ const ImageElementSchema = z.object({
         .enum(['nearest', 'lanczos3', 'mitchell'])
         .optional()
         .describe('Resize kernel: nearest for pixel art, lanczos3 for photos (default: nearest).'),
+    finish: FinishSchema.optional(),
     ...BaseElementProps,
 });
 const SpriteElementSchema = z.object({
@@ -264,9 +332,9 @@ const ElementSchema = z
     .discriminatedUnion('type', [
     TextElementSchema.describe('Styled text element rendered at a position.'),
     IconElementSchema.describe('Built-in or custom SVG icon element.'),
-    RectElementSchema.describe('Filled or gradient rectangle element.'),
+    RectElementSchema.describe('Filled, gradient, or bordered rectangle element.'),
     CircleElementSchema.describe('Filled or outline circle element.'),
-    LineElementSchema.describe('Single-pixel line element.'),
+    LineElementSchema.describe('Straight line element, 1px wide unless strokeWidth is set.'),
     ProgressElementSchema.describe('Horizontal progress bar widget.'),
     SparklineElementSchema.describe('Sparkline chart widget (line or bar).'),
     BitmapElementSchema.describe('Bitmap element using explicit palette indices.'),
@@ -296,7 +364,7 @@ const LayoutEntrySchema = z
     action: z
         .enum(['none', 'shrunk-to-compact', 'scrolling', 'wrapped', 'truncated', 'clipped'])
         .describe('Overflow action taken by the renderer.'),
-    font: z.enum(['standard', 'compact']).optional().describe('Font variant used (text only).'),
+    font: z.enum(FONT_VARIANTS).optional().describe('Font variant used (text only).'),
     scale: z.number().optional().describe('Scale factor applied (text only).'),
 })
     .describe('Layout report entry.');
@@ -423,8 +491,15 @@ export const pixooComposeScene = tool('pixoo_compose_scene', {
         {
             reason: 'asset_not_found',
             code: JsonRpcErrorCode.NotFound,
-            when: 'An image or sprite path could not be read.',
-            recovery: 'Verify the file path exists and is readable, or check the URL is reachable.',
+            when: 'An image source or sprite path could not be read, a sprite path was a URL, or an image URL could not be fetched.',
+            recovery: 'Pass an absolute path to an existing, readable image file, or for an image source a reachable https URL serving 10 MiB or less; sprite sheets take an absolute local path.',
+            thrownBy: 'service',
+        },
+        {
+            reason: 'invalid_image',
+            code: JsonRpcErrorCode.InvalidParams,
+            when: 'An image source or sprite path was read but did not decode as an image.',
+            recovery: 'Each image source and sprite path must be a complete PNG, JPEG, GIF, WebP, AVIF, TIFF, or SVG image; a text file, an HTML page, or a truncated download will not decode.',
             thrownBy: 'service',
         },
         {