pixelweaver 0.1.0

package/src/lib/animation/spritesheet-export.ts

@@ -0,0 +1,314 @@
+/**
+ * Spritesheet Export -- arranges frames into a spritesheet image with metadata.
+ *
+ * Supports horizontal strip, grid, and atlas layouts. Generates metadata
+ * in PixelWeaver, TexturePacker, Aseprite, and CSS sprite formats.
+ */
+
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { composite } from '../layers/compositor.js';
+import type { Frame } from './frame-model.svelte.js';
+import type { Layer } from '../layers/layer-types.js';
+
+// --- Types ---
+
+export type LayoutType = 'horizontal' | 'grid' | 'atlas';
+export type MetadataFormat = 'pixelweaver' | 'texturepacker' | 'aseprite' | 'css';
+
+export interface ExportOptions {
+  layout: LayoutType;
+  columns?: number;
+  padding: number;
+  tagId?: string;
+  metadataFormat: MetadataFormat;
+}
+
+export interface LayoutResult {
+  width: number;
+  height: number;
+  positions: { x: number; y: number }[];
+}
+
+// --- Layout calculators ---
+
+export function calculateHorizontalLayout(
+  frameCount: number,
+  frameWidth: number,
+  frameHeight: number,
+  padding: number,
+): LayoutResult {
+  const positions: { x: number; y: number }[] = [];
+  for (let i = 0; i < frameCount; i++) {
+    positions.push({
+      x: i * (frameWidth + padding),
+      y: 0,
+    });
+  }
+  return {
+    width: frameCount * frameWidth + Math.max(0, frameCount - 1) * padding,
+    height: frameHeight,
+    positions,
+  };
+}
+
+export function calculateGridLayout(
+  frameCount: number,
+  frameWidth: number,
+  frameHeight: number,
+  columns: number,
+  padding: number,
+): LayoutResult {
+  const cols = Math.max(1, columns);
+  const rows = Math.ceil(frameCount / cols);
+  const positions: { x: number; y: number }[] = [];
+
+  for (let i = 0; i < frameCount; i++) {
+    const col = i % cols;
+    const row = Math.floor(i / cols);
+    positions.push({
+      x: col * (frameWidth + padding),
+      y: row * (frameHeight + padding),
+    });
+  }
+
+  return {
+    width: cols * frameWidth + Math.max(0, cols - 1) * padding,
+    height: rows * frameHeight + Math.max(0, rows - 1) * padding,
+    positions,
+  };
+}
+
+// --- Metadata generators ---
+
+export function generatePixelweaverMeta(
+  layout: LayoutResult,
+  frames: Frame[],
+  options: ExportOptions,
+): string {
+  return JSON.stringify(
+    {
+      format: 'pixelweaver',
+      version: '1.0.0',
+      spritesheet: {
+        width: layout.width,
+        height: layout.height,
+        layout: options.layout,
+        padding: options.padding,
+      },
+      frames: frames.map((frame, i) => ({
+        index: i,
+        x: layout.positions[i]?.x ?? 0,
+        y: layout.positions[i]?.y ?? 0,
+        durationMs: frame.durationMs,
+      })),
+    },
+    null,
+    2,
+  );
+}
+
+export function generateTexturePackerMeta(
+  layout: LayoutResult,
+  frames: Frame[],
+  canvasWidth: number,
+  canvasHeight: number,
+): string {
+  // TexturePacker JSON Hash format
+  const frameEntries: Record<string, object> = {};
+  for (let i = 0; i < frames.length; i++) {
+    const pos = layout.positions[i];
+    const fr = frames[i];
+    if (!pos || !fr) continue;
+    frameEntries[`frame_${String(i)}`] = {
+      frame: { x: pos.x, y: pos.y, w: canvasWidth, h: canvasHeight },
+      rotated: false,
+      trimmed: false,
+      spriteSourceSize: { x: 0, y: 0, w: canvasWidth, h: canvasHeight },
+      sourceSize: { w: canvasWidth, h: canvasHeight },
+      duration: fr.durationMs ?? 100,
+    };
+  }
+
+  return JSON.stringify(
+    {
+      frames: frameEntries,
+      meta: {
+        app: 'PixelWeaver',
+        version: '1.0.0',
+        format: 'RGBA8888',
+        size: { w: layout.width, h: layout.height },
+        scale: 1,
+      },
+    },
+    null,
+    2,
+  );
+}
+
+export function generateAsepriteMeta(
+  layout: LayoutResult,
+  frames: Frame[],
+  canvasWidth: number,
+  canvasHeight: number,
+): string {
+  // Aseprite JSON format
+  const frameEntries: Record<string, object> = {};
+  for (let i = 0; i < frames.length; i++) {
+    const pos = layout.positions[i];
+    const fr = frames[i];
+    if (!pos || !fr) continue;
+    frameEntries[`sprite ${String(i)}.ase`] = {
+      frame: { x: pos.x, y: pos.y, w: canvasWidth, h: canvasHeight },
+      rotated: false,
+      trimmed: false,
+      spriteSourceSize: { x: 0, y: 0, w: canvasWidth, h: canvasHeight },
+      sourceSize: { w: canvasWidth, h: canvasHeight },
+      duration: fr.durationMs ?? 100,
+    };
+  }
+
+  return JSON.stringify(
+    {
+      frames: frameEntries,
+      meta: {
+        app: 'http://www.aseprite.org/',
+        version: '1.3',
+        image: 'spritesheet.png',
+        format: 'RGBA8888',
+        size: { w: layout.width, h: layout.height },
+        scale: '1',
+        frameTags: [],
+        layers: [],
+        slices: [],
+      },
+    },
+    null,
+    2,
+  );
+}
+
+export function generateCssMeta(
+  layout: LayoutResult,
+  frames: Frame[],
+  canvasWidth: number,
+  canvasHeight: number,
+): string {
+  const lines: string[] = [];
+
+  // Base class
+  lines.push(`.sprite {`);
+  lines.push(`  width: ${String(canvasWidth)}px;`);
+  lines.push(`  height: ${String(canvasHeight)}px;`);
+  lines.push(`  background-image: url('spritesheet.png');`);
+  lines.push(`  background-repeat: no-repeat;`);
+  lines.push(`}`);
+  lines.push('');
+
+  // Per-frame classes
+  for (let i = 0; i < frames.length; i++) {
+    const pos = layout.positions[i];
+    if (!pos) continue;
+    lines.push(`.sprite-frame-${String(i)} {`);
+    lines.push(`  background-position: -${String(pos.x)}px -${String(pos.y)}px;`);
+    lines.push(`}`);
+    if (i < frames.length - 1) lines.push('');
+  }
+
+  // CSS animation keyframes
+  lines.push('');
+  lines.push(`@keyframes sprite-animation {`);
+  const totalDuration = frames.reduce(
+    (sum, f) => sum + (f.durationMs ?? 100),
+    0,
+  );
+  let cumulativeTime = 0;
+  for (let i = 0; i < frames.length; i++) {
+    const pct = Math.round((cumulativeTime / totalDuration) * 100);
+    const pos = layout.positions[i];
+    const fr = frames[i];
+    if (!pos || !fr) continue;
+    lines.push(`  ${String(pct)}% { background-position: -${String(pos.x)}px -${String(pos.y)}px; }`);
+    cumulativeTime += fr.durationMs ?? 100;
+  }
+  lines.push(`}`);
+
+  return lines.join('\n');
+}
+
+// --- Main export function ---
+
+/**
+ * Export frames as a spritesheet with metadata.
+ *
+ * Composites each frame's visible layers into a single buffer,
+ * then arranges them according to the layout options.
+ */
+export function exportSpritesheet(
+  frames: Frame[],
+  layerTree: Layer[],
+  options: ExportOptions,
+): { image: PixelBuffer; metadata: string } {
+  if (frames.length === 0) {
+    throw new Error('No frames to export.');
+  }
+
+  // Determine frame dimensions from the first frame's first pixel buffer
+  let canvasWidth = 0;
+  let canvasHeight = 0;
+  for (const frame of frames) {
+    for (const [, buffer] of frame.pixelData) {
+      canvasWidth = buffer.width;
+      canvasHeight = buffer.height;
+      break;
+    }
+    if (canvasWidth > 0) break;
+  }
+
+  // Fallback: if no pixel data, use 1x1
+  if (canvasWidth === 0) canvasWidth = 1;
+  if (canvasHeight === 0) canvasHeight = 1;
+
+  // Calculate layout
+  let layout: LayoutResult;
+  if (options.layout === 'horizontal') {
+    layout = calculateHorizontalLayout(frames.length, canvasWidth, canvasHeight, options.padding);
+  } else if (options.layout === 'atlas') {
+    // Auto-square grid: compute columns as ceil(sqrt(n)) so the sheet is roughly square
+    const cols = Math.ceil(Math.sqrt(frames.length));
+    layout = calculateGridLayout(frames.length, canvasWidth, canvasHeight, cols, options.padding);
+  } else {
+    const cols = options.columns ?? Math.ceil(Math.sqrt(frames.length));
+    layout = calculateGridLayout(frames.length, canvasWidth, canvasHeight, cols, options.padding);
+  }
+
+  // Create output buffer
+  const output = new PixelBuffer(layout.width, layout.height);
+
+  // Composite each frame and paste into the output
+  for (let i = 0; i < frames.length; i++) {
+    const frame = frames[i];
+    const pos = layout.positions[i];
+    if (!frame || !pos) continue;
+    const composited = composite(layerTree, frame.pixelData, canvasWidth, canvasHeight);
+    output.paste(composited, pos.x, pos.y);
+  }
+
+  // Generate metadata
+  let metadata: string;
+  switch (options.metadataFormat) {
+    case 'pixelweaver':
+      metadata = generatePixelweaverMeta(layout, frames, options);
+      break;
+    case 'texturepacker':
+      metadata = generateTexturePackerMeta(layout, frames, canvasWidth, canvasHeight);
+      break;
+    case 'aseprite':
+      metadata = generateAsepriteMeta(layout, frames, canvasWidth, canvasHeight);
+      break;
+    case 'css':
+      metadata = generateCssMeta(layout, frames, canvasWidth, canvasHeight);
+      break;
+  }
+
+  return { image: output, metadata };
+}

package/src/lib/canvas/CanvasViewport.svelte

@@ -0,0 +1,216 @@
+<!--
+  CanvasViewport -- the main rendering surface for pixel editing.
+
+  Creates an HTML <canvas> that fills its container, connects the input
+  handler for zoom/pan/cursor tracking, and runs a requestAnimationFrame
+  loop to keep the display in sync with state.
+-->
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { canvasState } from './canvas-state.svelte.js';
+  import { renderCanvas, renderGrid, renderCursor, renderShapePreview, renderIsoGuide } from './canvas-renderer.js';
+  import { getShapePreview } from './shape-preview-state.svelte.js';
+  import { renderTilePreview } from './tile-mode.js';
+  import { renderOnionSkin } from './onion-skin.js';
+  import { bindInputHandler } from './input-handler.js';
+  import { getRenderBuffer } from './render-state.svelte.js';
+  import { ZOOM_STEPS } from './zoom-utils.js';
+  import { getFrames, getCurrentFrameIndex } from '../animation/frame-model.svelte.js';
+  import { getLayers } from '../layers/layer-tree.svelte.js';
+  import { composite } from '../layers/compositor.js';
+  import ContextMenu from '../ui/ContextMenu.svelte';
+
+  // --- Canvas element ref and rendering ---
+  let canvasEl: HTMLCanvasElement;
+  let animFrameId: number;
+
+  // --- Context menu state ---
+  let contextMenu = $state<{ x: number; y: number } | null>(null);
+
+  function handleContextMenu(e: MouseEvent) {
+    e.preventDefault();
+    contextMenu = { x: e.clientX, y: e.clientY };
+  }
+
+  /** Resize the canvas element to match its CSS size (retina-aware). */
+  function resizeCanvas(): void {
+    const rect = canvasEl.getBoundingClientRect();
+    const dpr = window.devicePixelRatio || 1;
+    const w = Math.round(rect.width * dpr);
+    const h = Math.round(rect.height * dpr);
+
+    if (canvasEl.width !== w || canvasEl.height !== h) {
+      canvasEl.width = w;
+      canvasEl.height = h;
+    }
+  }
+
+  /**
+   * Fit the canvas to the viewport and center it (called once on mount).
+   * Picks the largest zoom step that keeps the canvas within 90% of the
+   * viewport, then offsets so the canvas is centered.
+   */
+  function fitAndCenterCanvas(): void {
+    const rect = canvasEl.getBoundingClientRect();
+    if (rect.width === 0 || rect.height === 0) return;
+
+    const padding = 0.9; // use 90% of viewport
+    const maxW = rect.width * padding;
+    const maxH = rect.height * padding;
+
+    // Pick the largest zoom step where the canvas still fits
+    let bestZoom: number = ZOOM_STEPS[0];
+    for (const step of ZOOM_STEPS) {
+      if (canvasState.canvasWidth * step <= maxW && canvasState.canvasHeight * step <= maxH) {
+        bestZoom = step;
+      }
+    }
+    canvasState.zoom = bestZoom;
+
+    // Center at the chosen zoom
+    const canvasPixelW = canvasState.canvasWidth * bestZoom;
+    const canvasPixelH = canvasState.canvasHeight * bestZoom;
+    canvasState.panX = Math.round((rect.width - canvasPixelW) / 2);
+    canvasState.panY = Math.round((rect.height - canvasPixelH) / 2);
+  }
+
+  /** The render loop: clears, draws pixels, grid, and cursor each frame. */
+  function renderLoop(): void {
+    resizeCanvas();
+
+    const ctx = canvasEl.getContext('2d');
+    if (!ctx) return;
+
+    // Account for device pixel ratio in transforms
+    const dpr = window.devicePixelRatio || 1;
+    ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+
+    // Main render pass -- use the shared composited buffer from render-state
+    const buffer = getRenderBuffer();
+    if (buffer) {
+      renderCanvas(ctx, buffer, canvasState.zoom, canvasState.panX, canvasState.panY);
+    } else {
+      // No buffer yet (plugin not loaded); clear to workspace background
+      const { width: cw, height: ch } = ctx.canvas;
+      const style = getComputedStyle(document.documentElement);
+      ctx.fillStyle = style.getPropertyValue('--bg-canvas').trim() || '#121212';
+      ctx.fillRect(0, 0, cw, ch);
+    }
+
+    // Onion skin: draw ghosts of adjacent frames behind the current frame
+    if (canvasState.onionSkin) {
+      const frames = getFrames();
+      const curIdx = getCurrentFrameIndex();
+      if (frames.length > 1) {
+        const layers = getLayers();
+        const w = canvasState.canvasWidth;
+        const h = canvasState.canvasHeight;
+        const prevFrame = curIdx > 0 ? frames[curIdx - 1] : undefined;
+        const nextFrame = curIdx < frames.length - 1 ? frames[curIdx + 1] : undefined;
+        const prevBuffer = prevFrame ? composite(layers, prevFrame.pixelData, w, h) : null;
+        const nextBuffer = nextFrame ? composite(layers, nextFrame.pixelData, w, h) : null;
+        renderOnionSkin(ctx, prevBuffer, nextBuffer, canvasState.zoom, canvasState.panX, canvasState.panY);
+      }
+    }
+
+    // Tile mode: draw 3x3 ghost grid around the canvas so the user can check seam continuity
+    if (canvasState.tileMode && buffer) {
+      renderTilePreview(ctx, buffer, canvasState.zoom, canvasState.panX, canvasState.panY);
+    }
+
+    // Shape preview overlay (rubber-band during shape tool drags)
+    const shapePreview = getShapePreview();
+    if (shapePreview) {
+      renderShapePreview(ctx, shapePreview, canvasState.zoom, canvasState.panX, canvasState.panY);
+    }
+
+    // Isometric diamond guide overlay
+    if (canvasState.isoGuide) {
+      const isoW = buffer?.width ?? canvasState.canvasWidth;
+      const isoH = buffer?.height ?? canvasState.canvasHeight;
+      renderIsoGuide(ctx, isoW, isoH, canvasState.zoom, canvasState.panX, canvasState.panY);
+    }
+
+    // Grid overlay (only at high zoom, when enabled); use canvas dimensions when buffer is absent
+    if (canvasState.showGrid) {
+      const gridW = buffer?.width ?? canvasState.canvasWidth;
+      const gridH = buffer?.height ?? canvasState.canvasHeight;
+      renderGrid(ctx, gridW, gridH, canvasState.zoom, canvasState.panX, canvasState.panY);
+    }
+
+    // Cursor overlay (only when cursor is over the canvas)
+    if (canvasState.cursorInBounds) {
+      renderCursor(
+        ctx,
+        canvasState.cursorX,
+        canvasState.cursorY,
+        canvasState.zoom,
+        canvasState.panX,
+        canvasState.panY,
+      );
+    }
+
+    animFrameId = requestAnimationFrame(renderLoop);
+  }
+
+  onMount(() => {
+    const unbindInput = bindInputHandler(canvasEl);
+
+    // Defer fitAndCenterCanvas until dockview has finished layout.
+    // ResizeObserver fires early when the element first gets size but before
+    // dockview distributes space, so we wait 300ms after first non-zero size.
+    let fitTimer: ReturnType<typeof setTimeout> | undefined;
+    const resizeObs = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (!entry) return;
+      const { width, height } = entry.contentRect;
+      if (width > 0 && height > 0) {
+        clearTimeout(fitTimer);
+        fitTimer = setTimeout(() => {
+          fitAndCenterCanvas();
+          resizeObs.disconnect();
+        }, 300);
+      }
+    });
+    resizeObs.observe(canvasEl);
+
+    animFrameId = requestAnimationFrame(renderLoop);
+
+    return () => {
+      cancelAnimationFrame(animFrameId);
+      resizeObs.disconnect();
+      unbindInput();
+    };
+  });
+</script>
+
+<canvas
+  bind:this={canvasEl}
+  class="canvas-viewport"
+  tabindex="0"
+  role="application"
+  aria-label={`Pixel canvas, ${String(canvasState.canvasWidth)} by ${String(canvasState.canvasHeight)}`}
+  oncontextmenu={handleContextMenu}
+></canvas>
+
+{#if contextMenu}
+  <ContextMenu
+    menuPath="context/canvas"
+    x={contextMenu.x}
+    y={contextMenu.y}
+    onClose={() => contextMenu = null}
+  />
+{/if}
+
+<style>
+  .canvas-viewport {
+    display: block;
+    width: 100%;
+    height: 100%;
+    /* Prevent the canvas from being selectable or showing text cursor */
+    user-select: none;
+    touch-action: none;
+    outline: none;
+    cursor: crosshair;
+  }
+</style>

package/src/lib/canvas/canvas-init-plugin.ts

@@ -0,0 +1,178 @@
+/**
+ * Canvas Init Plugin -- bootstraps the layer tree, frame model, compositor,
+ * and dispatcher context so the canvas can render real pixel data.
+ *
+ * Sets up:
+ *   - A default pixel layer ("Layer 1")
+ *   - A default frame (frame 0) with a PixelBuffer for that layer
+ *   - A reactive getActiveBuffer() in the dispatcher context
+ *   - A recomposite hook that fires after every command execution
+ */
+
+import type { PluginModule } from '../core/plugin-loader.js';
+import {
+  addLayer,
+  getLayers,
+  getActiveLayerId,
+  getAllPixelLayers,
+} from '../layers/layer-tree.svelte.js';
+import {
+  addFrame,
+  getCurrentFrame,
+  getCurrentFrameIndex,
+  getFrames,
+} from '../animation/frame-model.svelte.js';
+import { composite } from '../layers/compositor.js';
+import { canvasState, MAX_CANVAS_SIZE, MIN_CANVAS_SIZE } from './canvas-state.svelte.js';
+import { PixelBuffer } from './pixel-buffer.js';
+import { setContext, onUndo } from '../core/dispatcher.js';
+import { setRenderBuffer } from './render-state.svelte.js';
+
+export const canvasInitPlugin: PluginModule = {
+  name: 'builtin/canvas-init',
+  version: '1.0.0',
+  description: 'Initializes layers, frames, compositor, and dispatcher context',
+
+  register(api) {
+    // 1. Create a default pixel layer
+    const defaultLayer = addLayer('Layer 1');
+
+    // 2. Ensure at least one frame exists
+    if (getFrames().length === 0) {
+      addFrame();
+    }
+
+    // 3. Ensure the current frame has a PixelBuffer for the default layer
+    const frame = getCurrentFrame();
+    if (!frame.pixelData.has(defaultLayer.id)) {
+      frame.pixelData.set(
+        defaultLayer.id,
+        new PixelBuffer(canvasState.canvasWidth, canvasState.canvasHeight),
+      );
+    }
+
+    // 4. Provide a reactive getter for the active layer's buffer to the dispatcher context.
+    //    Commands use this to know which buffer to draw into.
+    //    setActiveBuffer lets effects that change buffer dimensions (rotate
+    //    90/270 on non-square canvases, scale) replace the active layer's
+    //    pixel data with a new buffer. It updates the canvas size to match
+    //    the new buffer and writes the buffer into the current frame under
+    //    the active layer id. Effects must snapshot the old dimensions and
+    //    pixel data themselves so undo can restore them via setActiveBuffer.
+    setContext({
+      getActiveBuffer: () => {
+        const currentFrame = getCurrentFrame();
+        const layerId = getActiveLayerId();
+        let buf = currentFrame.pixelData.get(layerId);
+        if (!buf) {
+          buf = new PixelBuffer(canvasState.canvasWidth, canvasState.canvasHeight);
+          currentFrame.pixelData.set(layerId, buf);
+        }
+        return buf;
+      },
+      setActiveBuffer: (buffer: PixelBuffer) => {
+        const currentFrame = getCurrentFrame();
+        const layerId = getActiveLayerId();
+        assertBufferSize(buffer);
+        // Update canvas dimensions to match the new buffer.
+        canvasState.canvasWidth = buffer.width;
+        canvasState.canvasHeight = buffer.height;
+        // Swap in the new buffer for the active layer in the current frame.
+        currentFrame.pixelData.set(layerId, buffer);
+      },
+      getActiveLayerId: () => {
+        // getCurrentFrame() throws when there are no frames, so reaching
+        // this line guarantees a frame exists. When there's a frame but
+        // no layer, getActiveLayerId() returns the empty string in
+        // layer-tree, which we preserve for effects that want to
+        // diagnose "no active layer" vs "no frame" (the latter surfaces
+        // as a thrown exception from getCurrentFrame above).
+        getCurrentFrame();
+        return getActiveLayerId();
+      },
+      getActiveFrameIndex: () => getCurrentFrameIndex(),
+      setBufferForLayer: (frameIndex: number, layerId: string, buffer: PixelBuffer) => {
+        // Write a buffer into an explicit (frameIndex, layerId) pair --
+        // used by effects on undo, and by whole-canvas ops that iterate
+        // all pairs. Resizes the canvas to the buffer dims; callers doing
+        // multi-pair updates must make sure the final write reflects the
+        // intended canvas size (or update canvas dims themselves after).
+        const frames = getFrames();
+        if (frameIndex < 0 || frameIndex >= frames.length) return;
+        const frame = frames[frameIndex];
+        if (!frame) return;
+        assertBufferSize(buffer);
+        canvasState.canvasWidth = buffer.width;
+        canvasState.canvasHeight = buffer.height;
+        frame.pixelData.set(layerId, buffer);
+      },
+      getAllFrameLayerBuffers: () => {
+        // Used by whole-canvas effects to iterate every (frame, pixel-layer)
+        // pair. Only yields pairs where the frame actually has a buffer for
+        // that layer -- group layers and layers without buffers are skipped.
+        const result: Array<{ frameIndex: number; layerId: string; buffer: PixelBuffer }> = [];
+        const allFrames = getFrames();
+        const pixelLayers = getAllPixelLayers();
+        for (let frameIndex = 0; frameIndex < allFrames.length; frameIndex++) {
+          const frame = allFrames[frameIndex];
+          if (!frame) continue;
+          for (const layer of pixelLayers) {
+            const buf = frame.pixelData.get(layer.id);
+            if (buf) {
+              result.push({ frameIndex, layerId: layer.id, buffer: buf });
+            }
+          }
+        }
+        return result;
+      },
+      setCanvasSize: (width: number, height: number) => {
+        // Let whole-canvas effects update canvas dims once after writing
+        // all per-layer buffers. Goes through canvasState's setter which
+        // clamps to [MIN_CANVAS_SIZE, MAX_CANVAS_SIZE]; effects must have
+        // already ensured buffers fit (via assertBufferSize).
+        canvasState.canvasWidth = width;
+        canvasState.canvasHeight = height;
+      },
+    });
+
+    /**
+     * Throw if a buffer falls outside the allowed canvas size range. Extracted
+     * so setActiveBuffer and setBufferForLayer share the same guard -- the
+     * silent-clamp bug this replaces affected any path that writes into
+     * frame.pixelData without going through canvasState first.
+     */
+    function assertBufferSize(buffer: PixelBuffer): void {
+      if (
+        buffer.width < MIN_CANVAS_SIZE ||
+        buffer.width > MAX_CANVAS_SIZE ||
+        buffer.height < MIN_CANVAS_SIZE ||
+        buffer.height > MAX_CANVAS_SIZE
+      ) {
+        throw new Error(
+          `setActiveBuffer: buffer dimensions ${String(buffer.width)}x${String(buffer.height)} ` +
+          `are outside the allowed range [${String(MIN_CANVAS_SIZE)}, ${String(MAX_CANVAS_SIZE)}]`,
+        );
+      }
+    }
+
+    // 5. Recomposite: flatten all visible layers into the shared render buffer
+    function recomposite(): void {
+      const currentFrame = getCurrentFrame();
+      const layers = getLayers();
+      const result = composite(
+        layers,
+        currentFrame.pixelData,
+        canvasState.canvasWidth,
+        canvasState.canvasHeight,
+      );
+      setRenderBuffer(result);
+    }
+
+    // 6. Recomposite after every command execution and after undo
+    api.onCommand(() => { recomposite(); });
+    onUndo(() => { recomposite(); });
+
+    // 7. Initial composite so the canvas has something to render immediately
+    recomposite();
+  },
+};