@cyanheads/pixoo-mcp-server 1.2.0 → 1.2.2

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 } from './keyframes.js';
-import { fetchRemoteImageToTempPng, isRemoteSource } from './remote-image.js';
-import { drawStyledText, resolveX, resolveY, } from './text-engine.js';
+import { compileEffect, getKeyframeValue, interpolateColorKeyframe, } from './keyframes.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;
@@ -118,13 +185,135 @@ export function applyBackground(canvas, bg) {
     }
     canvas.clear();
 }
+/** Draw an icon's filled parts, then its stroked parts, in one color. */
+function drawIconPaths(canvas, paths, color, svgViewBox, targetRect) {
+    if (paths.fill)
+        renderSvgPath(canvas, paths.fill, color, svgViewBox, targetRect);
+    if (paths.stroke) {
+        renderSvgPath(canvas, paths.stroke, color, svgViewBox, targetRect, { mode: 'stroke' });
+    }
+}
+/**
+ * Render an icon as a top-to-bottom ramp, the way a text palette paints glyphs: the icon's
+ * top ink row takes `stop.from`, its bottom ink row `stop.to`, and each row between takes
+ * its even step. Only ink that lands on the canvas counts, so an icon clipped by an edge
+ * ramps across the rows still visible.
+ */
+function renderIconRamp(canvas, paths, svgViewBox, targetRect, stop) {
+    const mask = new Canvas(canvas.width);
+    drawIconPaths(mask, paths, [255, 255, 255], svgViewBox, targetRect);
+    const inkAt = (x, y) => mask.getPixelRgba(x, y)[3] > 0;
+    const rows = [];
+    for (let y = 0; y < mask.height; y++) {
+        for (let x = 0; x < mask.width; x++) {
+            if (inkAt(x, y)) {
+                rows.push(y);
+                break;
+            }
+        }
+    }
+    const top = rows[0];
+    const bottom = rows.at(-1);
+    if (top === undefined || bottom === undefined)
+        return;
+    const from = resolveColor(stop.from);
+    const to = resolveColor(stop.to);
+    for (const y of rows) {
+        const color = lerpColor(from, to, bottom === top ? 0 : (y - top) / (bottom - top));
+        for (let x = 0; x < mask.width; x++) {
+            if (inkAt(x, y))
+                canvas.setPixel(x, y, color);
+        }
+    }
+}
+/**
+ * The layout entry for an element drawn over `box` — its placed pixels, `dx`/`dy` included.
+ * The element fits when the box lies wholly on the canvas.
+ */
+function placedEntry(element, type, box, canvas) {
+    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) {
     // Compute keyframes / effects
     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))
@@ -136,17 +325,23 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
     const dyAnim = Number(getKeyframeValue(kf, 'dy', frameIdx, 0));
     const dx = (el.dx ?? 0) + dxAnim;
     const dy = (el.dy ?? 0) + dyAnim;
-    // If opacity < 100, render to scratch canvas and blit with alpha
-    const target = opacity < 100 ? new Canvas(canvas.width) : canvas;
+    // 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;
+    // 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': {
-            const style = el.style ?? {};
-            if (!style.color && el.color)
-                style.color = el.color;
-            const fontVariant = el.font === 'compact' ? 'compact' : 'standard';
+            // A copy: the per-frame color must not stick to the caller's style object.
+            const style = { ...el.style };
+            const color = keyframedColor ?? el.color;
+            if (!style.color && color)
+                style.color = color;
+            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;
@@ -154,29 +349,26 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             const resolvedY = resolveY(py, textH, canvas.height, dy);
             drawStyledText(target, el.text, resolvedX, resolvedY, style, fontVariant);
             layoutEntries.push({
-                element: elIdx,
-                type: 'text',
-                box: { x: resolvedX, y: resolvedY, w: textW, h: textH },
-                fits: resolvedX + textW <= canvas.width && resolvedY + textH <= canvas.height,
-                action: 'none',
+                ...placedEntry(elIdx, 'text', { x: resolvedX, y: resolvedY, w: textW, h: textH }, canvas),
                 font: fontVariant,
                 scale,
             });
             break;
         }
         case 'icon': {
-            let svgD;
+            let paths;
             let viewBox = '0 0 16 16';
             if (el.name) {
-                const iconEntry = ICONS[el.name];
+                // Own keys only: an Object.prototype name such as "constructor" is not an icon.
+                const iconEntry = Object.hasOwn(ICONS, el.name) ? ICONS[el.name] : undefined;
                 if (!iconEntry) {
                     throw invalidParams(`Unknown icon "${el.name}". Use pixoo://reference/icons to browse available icons.`, { reason: 'unknown_icon' });
                 }
-                svgD = iconEntry.d;
+                paths = iconEntry;
                 viewBox = iconEntry.viewBox;
             }
             else if (el.d) {
-                svgD = el.d;
+                paths = { fill: el.d };
                 viewBox = el.viewBox ?? '0 0 16 16';
             }
             else {
@@ -188,24 +380,26 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             const py = el.y ?? 0;
             const resolvedX = resolveX(px, w, canvas.width, dx);
             const resolvedY = resolveY(py, h, canvas.height, dy);
-            const color = el.color ? resolveColor(el.color) : [255, 255, 255];
+            // Resolved even under a palette, so a bad color still fails as invalid_color.
+            const colorSpec = keyframedColor ?? el.color;
+            const color = colorSpec ? resolveColor(colorSpec) : [255, 255, 255];
             // Parse viewBox string ("0 0 W H") to extract dimensions [W, H]
             const vbParts = viewBox.split(/\s+/).map(Number);
-            const vbW = vbParts[2] ?? 16;
-            const vbH = vbParts[3] ?? 16;
-            renderSvgPath(target, svgD, color, [vbW, vbH], [resolvedX, resolvedY, w, h]);
-            layoutEntries.push({
-                element: elIdx,
-                type: 'icon',
-                box: { x: resolvedX, y: resolvedY, w, h },
-                fits: resolvedX + w <= canvas.width && resolvedY + h <= canvas.height,
-                action: 'none',
-            });
+            const svgViewBox = [vbParts[2] ?? 16, vbParts[3] ?? 16];
+            const targetRect = [resolvedX, resolvedY, w, h];
+            if (el.palette) {
+                renderIconRamp(target, paths, svgViewBox, targetRect, PALETTES[el.palette]);
+            }
+            else {
+                drawIconPaths(target, paths, color, svgViewBox, targetRect);
+            }
+            layoutEntries.push(placedEntry(elIdx, 'icon', { x: resolvedX, y: resolvedY, w, h }, canvas));
             break;
         }
         case 'rect': {
             const x = el.x + dx;
             const y = el.y + dy;
+            const fill = keyframedColor ?? el.color;
             if (el.gradient) {
                 const from_ = resolveColor(el.gradient.from);
                 const to_ = resolveColor(el.gradient.to);
@@ -225,55 +419,56 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
                     }
                 }
             }
-            else if (el.color) {
-                target.fillRect(x, y, el.w, el.h, resolveColor(el.color));
+            else if (fill) {
+                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({
-                element: elIdx,
-                type: 'rect',
-                box: { x, y, w: el.w, h: el.h },
-                fits: x + el.w <= canvas.width && y + el.h <= canvas.height,
-                action: 'none',
-            });
+            layoutEntries.push(placedEntry(elIdx, 'rect', { x, y, w: el.w, h: el.h }, canvas));
             break;
         }
         case 'circle': {
             const cx = el.cx + dx;
             const cy = el.cy + dy;
-            const color = el.color ? resolveColor(el.color) : [255, 255, 255];
+            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);
             }
-            layoutEntries.push({
-                element: elIdx,
-                type: 'circle',
-                box: { x: cx - el.radius, y: cy - el.radius, w: el.radius * 2, h: el.radius * 2 },
-                fits: true,
-                action: 'none',
-            });
+            // 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 = 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;
         }
         case 'line': {
-            const color = el.color ? resolveColor(el.color) : [255, 255, 255];
-            target.drawLine(el.x0 + dx, el.y0 + dy, el.x1 + dx, el.y1 + dy, color);
-            layoutEntries.push({
-                element: elIdx,
-                type: 'line',
-                box: {
-                    x: Math.min(el.x0, el.x1),
-                    y: Math.min(el.y0, el.y1),
-                    w: Math.abs(el.x1 - el.x0),
-                    h: Math.abs(el.y1 - el.y0),
-                },
-                fits: true,
-                action: 'none',
-            });
+            const colorSpec = keyframedColor ?? el.color;
+            const color = colorSpec ? resolveColor(colorSpec) : [255, 255, 255];
+            const x0 = el.x0 + dx;
+            const y0 = el.y0 + dy;
+            const x1 = el.x1 + dx;
+            const y1 = el.y1 + dy;
+            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;
         }
         case 'progress': {
@@ -302,13 +497,7 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
                 const labelY = y + Math.floor((el.h - FONT_3x5.height) / 2);
                 drawText(target, el.label, labelX, labelY, [200, 200, 200], { font: FONT_3x5 });
             }
-            layoutEntries.push({
-                element: elIdx,
-                type: 'progress',
-                box: { x, y, w: el.w, h: el.h },
-                fits: true,
-                action: 'none',
-            });
+            layoutEntries.push(placedEntry(elIdx, 'progress', { x, y, w: el.w, h: el.h }, canvas));
             break;
         }
         case 'sparkline': {
@@ -320,7 +509,8 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             const min_ = Math.min(...data);
             const max_ = Math.max(...data);
             const range = max_ - min_ || 1;
-            const color = el.color ? resolveColor(el.color) : [100, 200, 255];
+            const colorSpec = keyframedColor ?? el.color;
+            const color = colorSpec ? resolveColor(colorSpec) : [100, 200, 255];
             if (el.kind === 'bar') {
                 const barW = Math.max(1, Math.floor(el.w / data.length));
                 for (let i = 0; i < data.length; i++) {
@@ -330,24 +520,19 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
                 }
             }
             else {
-                const stepX = el.w / (data.length - 1);
+                // Scaled over w − 1 and h − 1, so the line fills exactly its w × h box.
+                const stepX = (el.w - 1) / (data.length - 1);
+                const bottom = y + el.h - 1;
+                const rowOf = (v) => bottom - Math.round(((v - min_) / range) * (el.h - 1));
                 for (let i = 0; i < data.length - 1; i++) {
-                    const v0 = data[i] ?? 0;
-                    const v1 = data[i + 1] ?? 0;
                     const x0 = Math.round(x + i * stepX);
-                    const y0 = y + el.h - Math.round(((v0 - min_) / range) * el.h);
+                    const y0 = rowOf(data[i] ?? 0);
                     const x1 = Math.round(x + (i + 1) * stepX);
-                    const y1 = y + el.h - Math.round(((v1 - min_) / range) * el.h);
+                    const y1 = rowOf(data[i + 1] ?? 0);
                     target.drawLine(x0, y0, x1, y1, color);
                 }
             }
-            layoutEntries.push({
-                element: elIdx,
-                type: 'sparkline',
-                box: { x, y, w: el.w, h: el.h },
-                fits: true,
-                action: 'none',
-            });
+            layoutEntries.push(placedEntry(elIdx, 'sparkline', { x, y, w: el.w, h: el.h }, canvas));
             break;
         }
         case 'bitmap': {
@@ -366,28 +551,28 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
                     target.setPixel(x + col, y + row, resolveColor(colorStr));
                 }
             }
-            layoutEntries.push({
-                element: elIdx,
-                type: 'bitmap',
-                box: { x, y, w: el.rows[0]?.length ?? 0, h: el.rows.length },
-                fits: true,
-                action: 'none',
-            });
+            const widest = el.rows.reduce((max, row) => Math.max(max, row.length), 0);
+            layoutEntries.push(placedEntry(elIdx, 'bitmap', { x, y, w: widest, h: el.rows.length }, canvas));
             break;
         }
         case 'pixels': {
+            let minX = Number.POSITIVE_INFINITY;
+            let minY = Number.POSITIVE_INFINITY;
+            let maxX = Number.NEGATIVE_INFINITY;
+            let maxY = Number.NEGATIVE_INFINITY;
             for (const pt of el.data) {
-                const colorAnim = String(getKeyframeValue(kf, 'color', frameIdx, pt.color));
-                const c = resolveColor(colorAnim);
-                target.setPixel(pt.x + dx, pt.y + dy, c);
+                const x = pt.x + dx;
+                const y = pt.y + dy;
+                target.setPixel(x, y, resolveColor(keyframedColor ?? pt.color));
+                minX = Math.min(minX, x);
+                minY = Math.min(minY, y);
+                maxX = Math.max(maxX, x);
+                maxY = Math.max(maxY, y);
             }
-            layoutEntries.push({
-                element: elIdx,
-                type: 'pixels',
-                box: { x: 0, y: 0, w: 0, h: 0 },
-                fits: true,
-                action: 'none',
-            });
+            const box = el.data.length === 0
+                ? { x: 0, y: 0, w: 0, h: 0 }
+                : { x: minX, y: minY, w: maxX - minX + 1, h: maxY - minY + 1 };
+            layoutEntries.push(placedEntry(elIdx, 'pixels', box, canvas));
             break;
         }
         case 'image': {
@@ -395,18 +580,17 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
             if (cachedCanvas) {
                 target.blit(cachedCanvas, dx, dy);
             }
-            layoutEntries.push({
-                element: elIdx,
-                type: 'image',
-                box: { x: el.x ?? 0, y: el.y ?? 0, w: el.w ?? canvas.width, h: el.h ?? canvas.height },
-                fits: true,
-                action: 'none',
-            });
+            const box = {
+                x: (el.x ?? 0) + dx,
+                y: (el.y ?? 0) + dy,
+                w: el.w ?? canvas.width,
+                h: el.h ?? canvas.height,
+            };
+            layoutEntries.push(placedEntry(elIdx, 'image', box, canvas));
             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;
@@ -426,29 +610,14 @@ export function renderElement(canvas, el, elIdx, frameIdx, totalFrames, assets,
                     originalBodyColor: sprite.bodyColor,
                     originalDarkColor: sprite.darkColor,
                 });
-                layoutEntries.push({
-                    element: elIdx,
-                    type: 'sprite',
-                    box: { x: resolvedX, y: resolvedY, w: spriteW, h: spriteH },
-                    fits: resolvedX + spriteW <= canvas.width && resolvedY + spriteH <= canvas.height,
-                    action: 'none',
-                });
+                const box = { x: resolvedX, y: resolvedY, w: spriteW, h: spriteH };
+                layoutEntries.push(placedEntry(elIdx, 'sprite', box, canvas));
             }
             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) {