pixelweaver 0.1.0

package/src/lib/canvas/pixel-buffer.test.ts

@@ -0,0 +1,249 @@
+import { describe, it, expect, beforeAll } from 'vitest';
+import { PixelBuffer } from './pixel-buffer.js';
+
+// jsdom does not provide ImageData; polyfill it for tests
+beforeAll(() => {
+  if (typeof globalThis.ImageData === 'undefined') {
+    // Minimal ImageData polyfill: stores width, height, and a data copy
+    (globalThis as Record<string, unknown>)["ImageData"] = class ImageData {
+      readonly width: number;
+      readonly height: number;
+      readonly data: Uint8ClampedArray;
+      constructor(data: Uint8ClampedArray, width: number, height: number) {
+        this.width = width;
+        this.height = height;
+        this.data = new Uint8ClampedArray(data);
+      }
+    };
+  }
+});
+
+describe('PixelBuffer', () => {
+  it('should create a buffer of the correct size, initialized to transparent', () => {
+    const buf = new PixelBuffer(4, 3);
+    expect(buf.width).toBe(4);
+    expect(buf.height).toBe(3);
+    expect(buf.data.length).toBe(4 * 3 * 4);
+
+    // Every byte should be 0 (transparent black)
+    for (let i = 0; i < buf.data.length; i++) {
+      expect(buf.data[i]).toBe(0);
+    }
+  });
+
+  it('should roundtrip setPixel / getPixel', () => {
+    const buf = new PixelBuffer(8, 8);
+    buf.setPixel(3, 5, 10, 20, 30, 255);
+    expect(buf.getPixel(3, 5)).toEqual([10, 20, 30, 255]);
+  });
+
+  it('should not crash on out-of-bounds setPixel', () => {
+    const buf = new PixelBuffer(4, 4);
+    // These should be silent no-ops
+    buf.setPixel(-1, 0, 255, 0, 0, 255);
+    buf.setPixel(0, -1, 255, 0, 0, 255);
+    buf.setPixel(4, 0, 255, 0, 0, 255);
+    buf.setPixel(0, 4, 255, 0, 0, 255);
+    buf.setPixel(100, 100, 255, 0, 0, 255);
+
+    // Buffer should still be all zeros
+    for (let i = 0; i < buf.data.length; i++) {
+      expect(buf.data[i]).toBe(0);
+    }
+  });
+
+  it('should return [0,0,0,0] for out-of-bounds getPixel', () => {
+    const buf = new PixelBuffer(4, 4);
+    buf.fill(255, 128, 64, 255);
+
+    expect(buf.getPixel(-1, 0)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(0, -1)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(4, 0)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(0, 4)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(999, 999)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should fill the entire buffer with a color', () => {
+    const buf = new PixelBuffer(3, 2);
+    buf.fill(100, 150, 200, 255);
+
+    for (let y = 0; y < 2; y++) {
+      for (let x = 0; x < 3; x++) {
+        expect(buf.getPixel(x, y)).toEqual([100, 150, 200, 255]);
+      }
+    }
+  });
+
+  it('should fillRect within the specified region only', () => {
+    const buf = new PixelBuffer(8, 8);
+    buf.fillRect(2, 3, 3, 2, 255, 0, 0, 255);
+
+    // Pixels inside the rect
+    expect(buf.getPixel(2, 3)).toEqual([255, 0, 0, 255]);
+    expect(buf.getPixel(3, 3)).toEqual([255, 0, 0, 255]);
+    expect(buf.getPixel(4, 3)).toEqual([255, 0, 0, 255]);
+    expect(buf.getPixel(2, 4)).toEqual([255, 0, 0, 255]);
+    expect(buf.getPixel(3, 4)).toEqual([255, 0, 0, 255]);
+    expect(buf.getPixel(4, 4)).toEqual([255, 0, 0, 255]);
+
+    // Pixels outside the rect should remain transparent
+    expect(buf.getPixel(1, 3)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(5, 3)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(2, 2)).toEqual([0, 0, 0, 0]);
+    expect(buf.getPixel(2, 5)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should clip fillRect to buffer bounds', () => {
+    const buf = new PixelBuffer(4, 4);
+    // Rect extends past right and bottom edges
+    buf.fillRect(2, 2, 10, 10, 0, 255, 0, 255);
+
+    expect(buf.getPixel(2, 2)).toEqual([0, 255, 0, 255]);
+    expect(buf.getPixel(3, 3)).toEqual([0, 255, 0, 255]);
+    expect(buf.getPixel(1, 1)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should clone into an independent copy', () => {
+    const buf = new PixelBuffer(4, 4);
+    buf.setPixel(1, 1, 255, 0, 0, 255);
+
+    const cloned = buf.clone();
+
+    // Same content
+    expect(cloned.getPixel(1, 1)).toEqual([255, 0, 0, 255]);
+    expect(cloned.width).toBe(4);
+    expect(cloned.height).toBe(4);
+
+    // Modify original -- clone should be unaffected
+    buf.setPixel(1, 1, 0, 0, 0, 0);
+    expect(cloned.getPixel(1, 1)).toEqual([255, 0, 0, 255]);
+
+    // Modify clone -- original should be unaffected
+    cloned.setPixel(2, 2, 0, 255, 0, 255);
+    expect(buf.getPixel(2, 2)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should extract a sub-region with getRegion', () => {
+    const buf = new PixelBuffer(8, 8);
+    buf.fillRect(2, 2, 4, 4, 100, 200, 50, 255);
+
+    const region = buf.getRegion(2, 2, 4, 4);
+
+    expect(region.width).toBe(4);
+    expect(region.height).toBe(4);
+
+    // Every pixel in the region should have the filled color
+    for (let y = 0; y < 4; y++) {
+      for (let x = 0; x < 4; x++) {
+        expect(region.getPixel(x, y)).toEqual([100, 200, 50, 255]);
+      }
+    }
+  });
+
+  it('should handle getRegion that extends beyond buffer bounds', () => {
+    const buf = new PixelBuffer(4, 4);
+    buf.fill(255, 128, 64, 255);
+
+    // Region extends past bottom-right
+    const region = buf.getRegion(2, 2, 4, 4);
+    expect(region.width).toBe(4);
+    expect(region.height).toBe(4);
+
+    // In-bounds portion has data
+    expect(region.getPixel(0, 0)).toEqual([255, 128, 64, 255]);
+    expect(region.getPixel(1, 1)).toEqual([255, 128, 64, 255]);
+
+    // Out-of-bounds portion is transparent
+    expect(region.getPixel(2, 2)).toEqual([0, 0, 0, 0]);
+    expect(region.getPixel(3, 3)).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should paste with full alpha overwrite', () => {
+    const dst = new PixelBuffer(8, 8);
+    dst.fill(50, 50, 50, 255);
+
+    const src = new PixelBuffer(2, 2);
+    src.fill(255, 0, 0, 255);
+
+    dst.paste(src, 3, 3);
+
+    expect(dst.getPixel(3, 3)).toEqual([255, 0, 0, 255]);
+    expect(dst.getPixel(4, 4)).toEqual([255, 0, 0, 255]);
+    // Unaffected pixels remain original
+    expect(dst.getPixel(2, 2)).toEqual([50, 50, 50, 255]);
+  });
+
+  it('should paste with alpha blending', () => {
+    const dst = new PixelBuffer(4, 4);
+    dst.fill(0, 0, 0, 255); // opaque black background
+
+    const src = new PixelBuffer(1, 1);
+    // 50% transparent red
+    src.setPixel(0, 0, 255, 0, 0, 128);
+
+    dst.paste(src, 1, 1);
+
+    const [r, g, b, a] = dst.getPixel(1, 1);
+    // With ~50% red over black, red channel should be roughly 128
+    expect(r).toBeGreaterThan(120);
+    expect(r).toBeLessThan(135);
+    expect(g).toBe(0);
+    expect(b).toBe(0);
+    expect(a).toBe(255);
+  });
+
+  it('should skip fully transparent source pixels during paste', () => {
+    const dst = new PixelBuffer(4, 4);
+    dst.fill(100, 100, 100, 255);
+
+    const src = new PixelBuffer(2, 2);
+    // Only top-left pixel is opaque; rest are transparent
+    src.setPixel(0, 0, 255, 0, 0, 255);
+
+    dst.paste(src, 1, 1);
+
+    expect(dst.getPixel(1, 1)).toEqual([255, 0, 0, 255]);
+    // Transparent source pixels should not overwrite destination
+    expect(dst.getPixel(2, 1)).toEqual([100, 100, 100, 255]);
+  });
+
+  describe('inBounds', () => {
+    const buf = new PixelBuffer(10, 5);
+
+    it('should return true for valid coordinates', () => {
+      expect(buf.inBounds(0, 0)).toBe(true);
+      expect(buf.inBounds(9, 4)).toBe(true);
+      expect(buf.inBounds(5, 2)).toBe(true);
+    });
+
+    it('should return false for coordinates outside bounds', () => {
+      expect(buf.inBounds(-1, 0)).toBe(false);
+      expect(buf.inBounds(0, -1)).toBe(false);
+      expect(buf.inBounds(10, 0)).toBe(false);
+      expect(buf.inBounds(0, 5)).toBe(false);
+      expect(buf.inBounds(10, 5)).toBe(false);
+    });
+  });
+
+  it('should create correct ImageData via toImageData', () => {
+    const buf = new PixelBuffer(2, 2);
+    buf.setPixel(0, 0, 255, 0, 0, 255);
+    buf.setPixel(1, 1, 0, 255, 0, 255);
+
+    const imgData = buf.toImageData();
+
+    expect(imgData.width).toBe(2);
+    expect(imgData.height).toBe(2);
+    expect(imgData.data.length).toBe(2 * 2 * 4);
+
+    // Pixel (0,0) = red
+    expect(imgData.data[0]).toBe(255);
+    expect(imgData.data[1]).toBe(0);
+    expect(imgData.data[2]).toBe(0);
+    expect(imgData.data[3]).toBe(255);
+
+    // toImageData returns a copy, not a reference
+    imgData.data[0] = 0;
+    expect(buf.getPixel(0, 0)[0]).toBe(255);
+  });
+});

package/src/lib/canvas/pixel-buffer.ts

@@ -0,0 +1,151 @@
+/**
+ * PixelBuffer -- manages raw RGBA pixel data for a canvas.
+ *
+ * Backed by a Uint8ClampedArray of size width * height * 4.
+ * Each pixel is 4 consecutive bytes: [R, G, B, A].
+ * Coordinate (0,0) is top-left.
+ */
+export class PixelBuffer {
+  readonly width: number;
+  readonly height: number;
+  readonly data: Uint8ClampedArray;
+
+  constructor(width: number, height: number, data?: Uint8ClampedArray) {
+    this.width = width;
+    this.height = height;
+    this.data = data ?? new Uint8ClampedArray(width * height * 4);
+  }
+
+  /** Check if (x, y) is within the buffer bounds. */
+  inBounds(x: number, y: number): boolean {
+    return x >= 0 && x < this.width && y >= 0 && y < this.height;
+  }
+
+  /** Get the byte offset for a pixel at (x, y). */
+  private offset(x: number, y: number): number {
+    return (y * this.width + x) * 4;
+  }
+
+  /** Read the RGBA values at (x, y). Returns [0,0,0,0] if out of bounds. */
+  getPixel(x: number, y: number): [r: number, g: number, b: number, a: number] {
+    if (!this.inBounds(x, y)) return [0, 0, 0, 0];
+    const i = this.offset(x, y);
+    // Typed-array indexing is technically `number | undefined` under
+    // noUncheckedIndexedAccess; the `?? 0` fallback is never taken in practice.
+    return [this.data[i] ?? 0, this.data[i + 1] ?? 0, this.data[i + 2] ?? 0, this.data[i + 3] ?? 0];
+  }
+
+  /** Write RGBA values at (x, y). No-op if out of bounds. */
+  setPixel(x: number, y: number, r: number, g: number, b: number, a: number): void {
+    if (!this.inBounds(x, y)) return;
+    const i = this.offset(x, y);
+    this.data[i] = r;
+    this.data[i + 1] = g;
+    this.data[i + 2] = b;
+    this.data[i + 3] = a;
+  }
+
+  /** Fill the entire buffer with a single color. */
+  fill(r: number, g: number, b: number, a: number): void {
+    for (let i = 0; i < this.data.length; i += 4) {
+      this.data[i] = r;
+      this.data[i + 1] = g;
+      this.data[i + 2] = b;
+      this.data[i + 3] = a;
+    }
+  }
+
+  /** Fill a rectangular region with a single color. Clips to bounds. */
+  fillRect(x: number, y: number, w: number, h: number, r: number, g: number, b: number, a: number): void {
+    const x0 = Math.max(0, x);
+    const y0 = Math.max(0, y);
+    const x1 = Math.min(this.width, x + w);
+    const y1 = Math.min(this.height, y + h);
+
+    for (let py = y0; py < y1; py++) {
+      for (let px = x0; px < x1; px++) {
+        const i = this.offset(px, py);
+        this.data[i] = r;
+        this.data[i + 1] = g;
+        this.data[i + 2] = b;
+        this.data[i + 3] = a;
+      }
+    }
+  }
+
+  /** Create an independent copy of this buffer. */
+  clone(): PixelBuffer {
+    return new PixelBuffer(this.width, this.height, new Uint8ClampedArray(this.data));
+  }
+
+  /** Extract a rectangular sub-region as a new PixelBuffer. Clips to bounds. */
+  getRegion(x: number, y: number, w: number, h: number): PixelBuffer {
+    const result = new PixelBuffer(w, h);
+    for (let dy = 0; dy < h; dy++) {
+      for (let dx = 0; dx < w; dx++) {
+        const sx = x + dx;
+        const sy = y + dy;
+        if (this.inBounds(sx, sy)) {
+          const srcOff = this.offset(sx, sy);
+          const dstOff = (dy * w + dx) * 4;
+          result.data[dstOff] = this.data[srcOff] ?? 0;
+          result.data[dstOff + 1] = this.data[srcOff + 1] ?? 0;
+          result.data[dstOff + 2] = this.data[srcOff + 2] ?? 0;
+          result.data[dstOff + 3] = this.data[srcOff + 3] ?? 0;
+        }
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Paste another PixelBuffer onto this one at (destX, destY).
+   * Uses standard alpha blending: result = src * srcA + dst * (1 - srcA).
+   */
+  paste(source: PixelBuffer, destX: number, destY: number): void {
+    for (let sy = 0; sy < source.height; sy++) {
+      for (let sx = 0; sx < source.width; sx++) {
+        const dx = destX + sx;
+        const dy = destY + sy;
+        if (!this.inBounds(dx, dy)) continue;
+
+        const srcOff = (sy * source.width + sx) * 4;
+        const dstOff = this.offset(dx, dy);
+
+        // Typed-array indexing is `number | undefined` under
+        // noUncheckedIndexedAccess; `?? 0` fallbacks never trigger in practice.
+        const sr = source.data[srcOff] ?? 0;
+        const sg = source.data[srcOff + 1] ?? 0;
+        const sb = source.data[srcOff + 2] ?? 0;
+        const srcA = (source.data[srcOff + 3] ?? 0) / 255;
+        if (srcA === 0) continue;
+
+        if (srcA === 1) {
+          // Fully opaque: overwrite
+          this.data[dstOff] = sr;
+          this.data[dstOff + 1] = sg;
+          this.data[dstOff + 2] = sb;
+          this.data[dstOff + 3] = source.data[srcOff + 3] ?? 0;
+        } else {
+          // Alpha blend
+          const dr = this.data[dstOff] ?? 0;
+          const dg = this.data[dstOff + 1] ?? 0;
+          const db = this.data[dstOff + 2] ?? 0;
+          const dstA = (this.data[dstOff + 3] ?? 0) / 255;
+          const outA = srcA + dstA * (1 - srcA);
+          if (outA === 0) continue;
+
+          this.data[dstOff] = Math.round((sr * srcA + dr * dstA * (1 - srcA)) / outA);
+          this.data[dstOff + 1] = Math.round((sg * srcA + dg * dstA * (1 - srcA)) / outA);
+          this.data[dstOff + 2] = Math.round((sb * srcA + db * dstA * (1 - srcA)) / outA);
+          this.data[dstOff + 3] = Math.round(outA * 255);
+        }
+      }
+    }
+  }
+
+  /** Create an ImageData suitable for canvas rendering. */
+  toImageData(): ImageData {
+    return new ImageData(new Uint8ClampedArray(this.data), this.width, this.height);
+  }
+}

package/src/lib/canvas/render-state.svelte.ts

@@ -0,0 +1,18 @@
+/**
+ * Render State -- shared reactive buffer that CanvasViewport reads from.
+ *
+ * Holds the current composited PixelBuffer (the final result of flattening
+ * all visible layers). Updated by the canvas-init plugin after each command.
+ */
+
+import type { PixelBuffer } from './pixel-buffer';
+
+let buffer = $state<PixelBuffer | null>(null);
+
+export function getRenderBuffer(): PixelBuffer | null {
+  return buffer;
+}
+
+export function setRenderBuffer(b: PixelBuffer | null): void {
+  buffer = b;
+}

package/src/lib/canvas/shape-preview-state.svelte.ts

@@ -0,0 +1,36 @@
+/**
+ * Shape Preview State -- reactive singleton for live rubber-band previews.
+ *
+ * Shape tools (rect, ellipse, diamond, line) set the preview during drag;
+ * CanvasViewport reads it each frame and draws a visual overlay on the
+ * 2D context after the main render pass.
+ *
+ * All coordinates are in canvas pixel space (integer pixel indices).
+ */
+
+export interface ShapePreview {
+  type: 'rect' | 'ellipse' | 'diamond' | 'line';
+  startX: number;
+  startY: number;
+  endX: number;
+  endY: number;
+  color: string;   // hex color from the active foreground
+  filled: boolean;
+}
+
+let preview = $state<ShapePreview | null>(null);
+
+/** Read the current preview (null when no drag is in progress). */
+export function getShapePreview(): ShapePreview | null {
+  return preview;
+}
+
+/** Set or update the preview during a shape drag. */
+export function setShapePreview(p: ShapePreview): void {
+  preview = p;
+}
+
+/** Clear the preview (call on pointer-up after dispatching the draw command). */
+export function clearShapePreview(): void {
+  preview = null;
+}

package/src/lib/canvas/tile-mode.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Tests for the tile/wrap mode coordinate wrapping logic.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { wrapCoordinate } from './tile-mode.js';
+
+describe('wrapCoordinate', () => {
+  const W = 8;
+  const H = 8;
+
+  it('returns coordinates unchanged when already in bounds', () => {
+    expect(wrapCoordinate(0, 0, W, H)).toEqual({ x: 0, y: 0 });
+    expect(wrapCoordinate(3, 5, W, H)).toEqual({ x: 3, y: 5 });
+    expect(wrapCoordinate(7, 7, W, H)).toEqual({ x: 7, y: 7 });
+  });
+
+  it('wraps positive overflow', () => {
+    expect(wrapCoordinate(8, 0, W, H)).toEqual({ x: 0, y: 0 });
+    expect(wrapCoordinate(9, 0, W, H)).toEqual({ x: 1, y: 0 });
+    expect(wrapCoordinate(0, 8, W, H)).toEqual({ x: 0, y: 0 });
+    expect(wrapCoordinate(0, 10, W, H)).toEqual({ x: 0, y: 2 });
+  });
+
+  it('wraps negative coordinates', () => {
+    expect(wrapCoordinate(-1, 0, W, H)).toEqual({ x: 7, y: 0 });
+    expect(wrapCoordinate(0, -1, W, H)).toEqual({ x: 0, y: 7 });
+    expect(wrapCoordinate(-1, -1, W, H)).toEqual({ x: 7, y: 7 });
+    expect(wrapCoordinate(-8, 0, W, H)).toEqual({ x: 0, y: 0 });
+  });
+
+  it('wraps large negative offsets', () => {
+    expect(wrapCoordinate(-9, -17, W, H)).toEqual({ x: 7, y: 7 });
+    expect(wrapCoordinate(-16, 0, W, H)).toEqual({ x: 0, y: 0 });
+  });
+
+  it('wraps large positive offsets', () => {
+    expect(wrapCoordinate(16, 24, W, H)).toEqual({ x: 0, y: 0 });
+    expect(wrapCoordinate(19, 27, W, H)).toEqual({ x: 3, y: 3 });
+  });
+
+  it('handles non-square dimensions', () => {
+    expect(wrapCoordinate(-1, -1, 4, 6)).toEqual({ x: 3, y: 5 });
+    expect(wrapCoordinate(5, 7, 4, 6)).toEqual({ x: 1, y: 1 });
+  });
+
+  it('wraps edge values (exactly at boundary)', () => {
+    // x = width should wrap to 0
+    expect(wrapCoordinate(W, 0, W, H)).toEqual({ x: 0, y: 0 });
+    // y = height should wrap to 0
+    expect(wrapCoordinate(0, H, W, H)).toEqual({ x: 0, y: 0 });
+  });
+});

package/src/lib/canvas/tile-mode.ts

@@ -0,0 +1,92 @@
+/**
+ * Tile/Wrap Mode -- provides coordinate wrapping and a 3x3 tiled preview
+ * for seamless sprite/texture creation.
+ *
+ * When tile mode is active, drawing coordinates that go out of bounds wrap
+ * around to the opposite edge.  The renderer shows the main canvas tiled
+ * in a 3x3 grid so the user can see seam continuity.
+ */
+
+import type { PixelBuffer } from './pixel-buffer.js';
+
+// --- Coordinate wrapping ---
+
+/**
+ * Wrap a coordinate pair so it falls within [0, width) x [0, height).
+ * Handles negative values and overflow.
+ *
+ * Uses true modulo (not JS remainder) so that negative inputs wrap correctly:
+ *   wrapCoordinate(-1, 0, 8, 8)  =>  { x: 7, y: 0 }
+ */
+export function wrapCoordinate(
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+): { x: number; y: number } {
+  return {
+    x: ((x % width) + width) % width,
+    y: ((y % height) + height) % height,
+  };
+}
+
+// --- Tile preview renderer ---
+
+/**
+ * Render the 8 surrounding ghost tiles for the tiled preview.
+ *
+ * The center tile is already drawn by the main renderCanvas() call, so this
+ * function only draws the surrounding 8 tiles at reduced opacity so the user
+ * can distinguish the primary canvas from its repeats.
+ *
+ * Expects an offscreen canvas or ImageBitmap-based approach to be set up
+ * by the caller for the pixel data.  This function uses putImageData + drawImage
+ * to avoid creating its own offscreen resources (keeps it a pure render helper).
+ *
+ * @param ctx    - Destination 2D context.
+ * @param buffer - The pixel buffer to tile.
+ * @param zoom   - Zoom factor.
+ * @param panX   - Horizontal pan offset in screen pixels.
+ * @param panY   - Vertical pan offset in screen pixels.
+ */
+export function renderTilePreview(
+  ctx: CanvasRenderingContext2D,
+  buffer: PixelBuffer,
+  zoom: number,
+  panX: number,
+  panY: number,
+): void {
+  const tileW = buffer.width * zoom;
+  const tileH = buffer.height * zoom;
+
+  // Build a temporary canvas with the pixel data at 1:1, then scale it.
+  // We create a small temporary canvas here to keep this function self-contained.
+  const tmp = new OffscreenCanvas(buffer.width, buffer.height);
+  const tmpCtx = tmp.getContext('2d');
+  if (!tmpCtx) return;
+  tmpCtx.putImageData(buffer.toImageData(), 0, 0);
+
+  ctx.imageSmoothingEnabled = false;
+
+  // Draw the 8 surrounding ghost tiles.  The center tile (dx===0, dy===0)
+  // is already rendered by the main renderCanvas() call, so we skip it to
+  // avoid double-drawing (which makes semi-transparent pixels too opaque).
+  ctx.globalAlpha = 0.3;
+  for (let dy = -1; dy <= 1; dy++) {
+    for (let dx = -1; dx <= 1; dx++) {
+      if (dx === 0 && dy === 0) continue;
+
+      ctx.drawImage(
+        tmp,
+        0, 0, buffer.width, buffer.height,
+        panX + dx * tileW,
+        panY + dy * tileH,
+        tileW,
+        tileH,
+      );
+    }
+  }
+
+  // Reset alpha
+  ctx.globalAlpha = 1.0;
+}

package/src/lib/canvas/viewport-utils.ts

@@ -0,0 +1,24 @@
+/**
+ * Viewport Utilities -- DOM helpers for locating and measuring the canvas
+ * viewport element. Used by view commands that need to pivot zoom around
+ * the viewport center.
+ */
+
+/**
+ * Get the center of the canvas viewport element in local element coordinates.
+ * Returns [0, 0] if the viewport element isn't mounted yet (e.g. during
+ * early command dispatch before Svelte has mounted the canvas).
+ */
+export function viewportCenter(): [number, number] {
+  const el = document.querySelector<HTMLElement>('.canvas-viewport');
+  if (!el) return [0, 0];
+  return [el.clientWidth / 2, el.clientHeight / 2];
+}
+
+/**
+ * Get the canvas viewport element itself, or null if it isn't mounted yet.
+ * Used by fit_to_view / center_canvas which need the bounding rect.
+ */
+export function getViewportElement(): HTMLElement | null {
+  return document.querySelector<HTMLElement>('.canvas-viewport');
+}

package/src/lib/canvas/zoom-utils.ts

@@ -0,0 +1,31 @@
+/**
+ * Zoom Utilities -- shared zoom step logic used by both the scroll-wheel
+ * zoom in input-handler.ts and the menu-driven zoom commands in view-commands.ts.
+ *
+ * Keeping these in one place ensures both paths step through the same
+ * discrete zoom levels and stay in sync.
+ */
+
+/** Predefined zoom steps, from smallest to largest. */
+export const ZOOM_STEPS = [1, 2, 3, 4, 6, 8, 12, 16, 24, 32] as const;
+
+/** Default zoom level used by "Reset Zoom". */
+export const DEFAULT_ZOOM = 8;
+
+/** Find the next zoom step strictly greater than current. Clamped to max. */
+export function zoomStepUp(current: number): number {
+  for (const step of ZOOM_STEPS) {
+    if (step > current) return step;
+  }
+  // ZOOM_STEPS has fixed length > 0, so this is never undefined.
+  return ZOOM_STEPS[ZOOM_STEPS.length - 1] ?? DEFAULT_ZOOM;
+}
+
+/** Find the next zoom step strictly less than current. Clamped to min. */
+export function zoomStepDown(current: number): number {
+  for (let i = ZOOM_STEPS.length - 1; i >= 0; i--) {
+    const step = ZOOM_STEPS[i];
+    if (step !== undefined && step < current) return step;
+  }
+  return ZOOM_STEPS[0];
+}