pixelweaver 0.1.0

package/src/lib/iso/seam-checker.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { checkSeams, suggestSeamFixes } from './seam-checker.js';
+
+describe('seam-checker', () => {
+  describe('checkSeams', () => {
+    it('should return no issues for a uniformly colored tile', () => {
+      const buf = new PixelBuffer(4, 4);
+      buf.fill(100, 200, 50, 255);
+      const issues = checkSeams(buf);
+      expect(issues).toHaveLength(0);
+    });
+
+    it('should return no issues when opposite edges match (non-uniform)', () => {
+      // Top and bottom rows match, left and right columns match,
+      // but interior is different
+      const buf = new PixelBuffer(4, 4);
+      buf.fill(0, 0, 0, 255);
+
+      // Set top row and bottom row to the same distinct color
+      for (let x = 0; x < 4; x++) {
+        buf.setPixel(x, 0, 255, 0, 0, 255);
+        buf.setPixel(x, 3, 255, 0, 0, 255);
+      }
+      // Set left and right columns to the same distinct color
+      for (let y = 0; y < 4; y++) {
+        buf.setPixel(0, y, 0, 255, 0, 255);
+        buf.setPixel(3, y, 0, 255, 0, 255);
+      }
+
+      const issues = checkSeams(buf);
+      expect(issues).toHaveLength(0);
+    });
+
+    it('should detect top-bottom mismatch', () => {
+      const buf = new PixelBuffer(4, 4);
+      buf.fill(100, 100, 100, 255);
+      // Make bottom row different from top row
+      buf.setPixel(2, 3, 200, 200, 200, 255);
+
+      const issues = checkSeams(buf);
+      const topIssues = issues.filter((i) => i.edge === 'top');
+      expect(topIssues.length).toBeGreaterThan(0);
+      // Specifically at position 2
+      const issue = topIssues.find((i) => i.position === 2);
+      expect(issue).toBeDefined();
+      expect(issue?.color1).not.toBe(issue?.color2);
+    });
+
+    it('should detect left-right mismatch', () => {
+      const buf = new PixelBuffer(4, 4);
+      buf.fill(50, 50, 50, 255);
+      // Make right column pixel different from left column
+      buf.setPixel(3, 1, 250, 250, 250, 255);
+
+      const issues = checkSeams(buf);
+      const leftIssues = issues.filter((i) => i.edge === 'left');
+      expect(leftIssues.length).toBeGreaterThan(0);
+      const issue = leftIssues.find((i) => i.position === 1);
+      expect(issue).toBeDefined();
+    });
+
+    it('should report all mismatched positions', () => {
+      const buf = new PixelBuffer(3, 3);
+      buf.fill(0, 0, 0, 255);
+
+      // Make top and bottom rows differ at every position
+      for (let x = 0; x < 3; x++) {
+        buf.setPixel(x, 0, 100, 0, 0, 255);
+        buf.setPixel(x, 2, 200, 0, 0, 255);
+      }
+      // Make left and right columns differ at every position
+      for (let y = 0; y < 3; y++) {
+        buf.setPixel(0, y, buf.getPixel(0, y)[0], 100, 0, 255);
+        buf.setPixel(2, y, buf.getPixel(2, y)[0], 200, 0, 255);
+      }
+
+      const issues = checkSeams(buf);
+      const topIssues = issues.filter((i) => i.edge === 'top');
+      const leftIssues = issues.filter((i) => i.edge === 'left');
+      // All 3 top-bottom and all 3 left-right should mismatch
+      expect(topIssues.length).toBe(3);
+      expect(leftIssues.length).toBe(3);
+    });
+  });
+
+  describe('suggestSeamFixes', () => {
+    it('should suggest averaged colors for mismatched edges', () => {
+      const buf = new PixelBuffer(2, 2);
+      // Top row: (100, 100, 100, 255)
+      buf.setPixel(0, 0, 100, 100, 100, 255);
+      buf.setPixel(1, 0, 100, 100, 100, 255);
+      // Bottom row: (200, 200, 200, 255)
+      buf.setPixel(0, 1, 200, 200, 200, 255);
+      buf.setPixel(1, 1, 200, 200, 200, 255);
+
+      const issues = checkSeams(buf);
+      const topIssues = issues.filter((i) => i.edge === 'top');
+      expect(topIssues.length).toBeGreaterThan(0);
+
+      const fixes = suggestSeamFixes(topIssues);
+      expect(fixes).toHaveLength(topIssues.length);
+
+      for (const fix of fixes) {
+        // Average of 100 and 200 = 150; average of 255 and 255 = 255
+        expect(fix.suggestedColor).toBe('#969696FF');
+      }
+    });
+
+    it('should return empty array when there are no issues', () => {
+      const fixes = suggestSeamFixes([]);
+      expect(fixes).toHaveLength(0);
+    });
+
+    it('should preserve edge and position from the original issue', () => {
+      const issues = [
+        { edge: 'top' as const, position: 3, color1: '#ff0000ff', color2: '#00ff00ff' },
+      ];
+      const fixes = suggestSeamFixes(issues);
+      expect(fixes[0]?.edge).toBe('top');
+      expect(fixes[0]?.position).toBe(3);
+      // Average of (255,0,0,255) and (0,255,0,255) = (128,128,0,255)
+      expect(fixes[0]?.suggestedColor).toBe('#808000FF');
+    });
+  });
+});

package/src/lib/iso/seam-checker.ts

@@ -0,0 +1,93 @@
+/**
+ * Seam Checker -- detects and suggests fixes for tile edge mismatches.
+ *
+ * For a tile to tessellate seamlessly, opposite edges must have matching pixels:
+ *   - top row must match bottom row
+ *   - left column must match right column
+ *
+ * This module checks those constraints and suggests color-averaged fixes.
+ */
+
+import type { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { rgbaToHex, hexToRgba } from '../color/color-utils.js';
+
+/** A single pixel-level seam mismatch between opposite edges. */
+export interface SeamIssue {
+  edge: 'top' | 'right' | 'bottom' | 'left';
+  position: number;   // pixel index along the edge
+  color1: string;     // hex color on this edge
+  color2: string;     // hex color on the opposite edge
+}
+
+/** A suggested fix: the averaged color to apply at the given edge position. */
+export interface SeamFix {
+  edge: string;
+  position: number;
+  suggestedColor: string;
+}
+
+/**
+ * Check if a tile's edges are seamless for tiling.
+ *
+ * Compares top<->bottom and left<->right pixel by pixel.
+ * Returns an array of SeamIssue for every mismatched pixel.
+ * An empty array means the tile is fully seamless.
+ */
+export function checkSeams(buffer: PixelBuffer): SeamIssue[] {
+  const issues: SeamIssue[] = [];
+  const { width, height } = buffer;
+
+  // Top row vs bottom row
+  for (let x = 0; x < width; x++) {
+    const [tr, tg, tb, ta] = buffer.getPixel(x, 0);
+    const [br, bg, bb, ba] = buffer.getPixel(x, height - 1);
+    if (tr !== br || tg !== bg || tb !== bb || ta !== ba) {
+      issues.push({
+        edge: 'top',
+        position: x,
+        color1: rgbaToHex(tr, tg, tb, ta),
+        color2: rgbaToHex(br, bg, bb, ba),
+      });
+    }
+  }
+
+  // Left column vs right column
+  for (let y = 0; y < height; y++) {
+    const [lr, lg, lb, la] = buffer.getPixel(0, y);
+    const [rr, rg, rb, ra] = buffer.getPixel(width - 1, y);
+    if (lr !== rr || lg !== rg || lb !== rb || la !== ra) {
+      issues.push({
+        edge: 'left',
+        position: y,
+        color1: rgbaToHex(lr, lg, lb, la),
+        color2: rgbaToHex(rr, rg, rb, ra),
+      });
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Suggest fixes for seam issues by averaging the two mismatched colors.
+ *
+ * For each issue, produces a suggested color that is the component-wise
+ * average of color1 and color2.
+ */
+export function suggestSeamFixes(issues: SeamIssue[]): SeamFix[] {
+  return issues.map((issue) => {
+    const c1 = hexToRgba(issue.color1);
+    const c2 = hexToRgba(issue.color2);
+    const avg = {
+      r: Math.round((c1.r + c2.r) / 2),
+      g: Math.round((c1.g + c2.g) / 2),
+      b: Math.round((c1.b + c2.b) / 2),
+      a: Math.round((c1.a + c2.a) / 2),
+    };
+    return {
+      edge: issue.edge,
+      position: issue.position,
+      suggestedColor: rgbaToHex(avg.r, avg.g, avg.b, avg.a),
+    };
+  });
+}

package/src/lib/iso/tessellation.ts

@@ -0,0 +1,67 @@
+/**
+ * Tile Tessellation -- generates isometric grids and renders PixelBuffer tiles.
+ *
+ * Uses iso-math for coordinate conversion and draws tiles onto a 2D canvas context.
+ */
+
+import type { PixelBuffer } from '../canvas/pixel-buffer.js';
+import { isoToScreen } from './iso-math.js';
+
+/** A positioned tile in an isometric tessellation. */
+export interface TessellationCell {
+  col: number;
+  row: number;
+  screenX: number;
+  screenY: number;
+}
+
+/**
+ * Generate screen positions for an NxM isometric tile grid.
+ *
+ * Tiles are ordered row-by-row, top-to-bottom (painter's order for flat grids).
+ * The returned screenX/screenY is the top-center anchor of each tile diamond.
+ */
+export function generateTessellation(
+  cols: number,
+  rows: number,
+  tileWidth: number,
+  tileHeight: number,
+): TessellationCell[] {
+  const cells: TessellationCell[] = [];
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      const { x, y } = isoToScreen(col, row, tileWidth, tileHeight);
+      cells.push({ col, row, screenX: x, screenY: y });
+    }
+  }
+  return cells;
+}
+
+/**
+ * Render tessellated tiles onto a canvas using a PixelBuffer as the tile source.
+ *
+ * Each tile is drawn by converting the PixelBuffer to ImageData and painting it
+ * at the correct screen position, adjusted by the given camera offsets.
+ * The tile is drawn so that its top-center aligns with the isometric anchor.
+ */
+export function renderTessellation(
+  ctx: CanvasRenderingContext2D,
+  tile: PixelBuffer,
+  cols: number,
+  rows: number,
+  tileWidth: number,
+  tileHeight: number,
+  offsetX: number,
+  offsetY: number,
+): void {
+  const imageData = tile.toImageData();
+  const cells = generateTessellation(cols, rows, tileWidth, tileHeight);
+
+  for (const cell of cells) {
+    // Anchor the tile so its top-center diamond point matches screenX/screenY.
+    // The tile image's (tileWidth/2, 0) should land at (screenX, screenY).
+    const drawX = cell.screenX - tileWidth / 2 + offsetX;
+    const drawY = cell.screenY + offsetY;
+    ctx.putImageData(imageData, drawX, drawY);
+  }
+}

package/src/lib/layers/compositor.test.ts

@@ -0,0 +1,193 @@
+import { describe, it, expect } from 'vitest';
+import { composite } from './compositor.js';
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import type { Layer } from './layer-types.js';
+import { createPixelLayer, createGroupLayer } from './layer-types.js';
+
+// --- Helpers ---
+
+/** Create a solid-color pixel buffer. */
+function solidBuffer(w: number, h: number, r: number, g: number, b: number, a: number): PixelBuffer {
+  const buf = new PixelBuffer(w, h);
+  buf.fill(r, g, b, a);
+  return buf;
+}
+
+// --- Tests ---
+
+describe('composite', () => {
+  it('should return a transparent buffer when there are no visible layers', () => {
+    const result = composite([], new Map(), 4, 4);
+    expect(result.width).toBe(4);
+    expect(result.height).toBe(4);
+    // All pixels should be transparent (0,0,0,0)
+    for (let i = 0; i < result.data.length; i++) {
+      expect(result.data[i]).toBe(0);
+    }
+  });
+
+  it('should output a single visible layer as-is', () => {
+    const layer = createPixelLayer('Layer');
+    const data = new Map<string, PixelBuffer>();
+    data.set(layer.id, solidBuffer(2, 2, 255, 0, 0, 255));
+
+    const result = composite([layer], data, 2, 2);
+    const pixel = result.getPixel(0, 0);
+    expect(pixel).toEqual([255, 0, 0, 255]);
+  });
+
+  it('should not include hidden layers', () => {
+    const visible = createPixelLayer('Visible');
+    const hidden = createPixelLayer('Hidden');
+    hidden.visible = false;
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(visible.id, solidBuffer(2, 2, 255, 0, 0, 255));
+    data.set(hidden.id, solidBuffer(2, 2, 0, 255, 0, 255));
+
+    const result = composite([visible, hidden], data, 2, 2);
+    // Only red should be visible (hidden green is skipped)
+    const pixel = result.getPixel(0, 0);
+    expect(pixel).toEqual([255, 0, 0, 255]);
+  });
+
+  it('should composite two layers with normal blend (top covers bottom)', () => {
+    const bottom = createPixelLayer('Bottom');
+    const top = createPixelLayer('Top');
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(bottom.id, solidBuffer(2, 2, 255, 0, 0, 255)); // red
+    data.set(top.id, solidBuffer(2, 2, 0, 0, 255, 255)); // blue, fully opaque
+
+    // Bottom is first in array (drawn first), top is second (drawn on top)
+    const result = composite([bottom, top], data, 2, 2);
+    const pixel = result.getPixel(0, 0);
+    // Blue fully opaque on top should cover red completely
+    expect(pixel).toEqual([0, 0, 255, 255]);
+  });
+
+  it('should blend a layer with 50% opacity correctly', () => {
+    const bottom = createPixelLayer('Bottom');
+    const top = createPixelLayer('Top');
+    top.opacity = 50;
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(bottom.id, solidBuffer(2, 2, 0, 0, 0, 255)); // black
+    data.set(top.id, solidBuffer(2, 2, 255, 255, 255, 255)); // white at 50% opacity
+
+    const result = composite([bottom, top], data, 2, 2);
+    const pixel = result.getPixel(0, 0);
+    // White at 50% over black should give ~128 gray
+    // srcA = 255 * 0.5 = 128 -> sA = 128/255 ~ 0.502
+    // outA = 0.502 + 1 * (1 - 0.502) = 1.0
+    // outR = (255 * 0.502 + 0 * 1 * 0.498) / 1.0 = 128
+    expect(pixel[0]).toBeGreaterThanOrEqual(127);
+    expect(pixel[0]).toBeLessThanOrEqual(129);
+    expect(pixel[3]).toBe(255);
+  });
+
+  it('should apply group opacity to all children', () => {
+    const child = createPixelLayer('Child');
+    const group: Layer = {
+      ...createGroupLayer('Group'),
+      children: [child],
+      opacity: 50,
+    };
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(child.id, solidBuffer(2, 2, 255, 255, 255, 255)); // white
+
+    // Bottom: black background
+    const bg = createPixelLayer('BG');
+    data.set(bg.id, solidBuffer(2, 2, 0, 0, 0, 255));
+
+    const result = composite([bg, group], data, 2, 2);
+    const pixel = result.getPixel(0, 0);
+    // Group at 50% with white child over black BG -> ~128 gray
+    expect(pixel[0]).toBeGreaterThanOrEqual(127);
+    expect(pixel[0]).toBeLessThanOrEqual(129);
+  });
+
+  it('should skip children of hidden groups', () => {
+    const child = createPixelLayer('Child');
+    const group: Layer = {
+      ...createGroupLayer('Group'),
+      children: [child],
+      visible: false,
+    };
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(child.id, solidBuffer(2, 2, 255, 0, 0, 255));
+
+    const result = composite([group], data, 2, 2);
+    // Nothing should be rendered
+    const pixel = result.getPixel(0, 0);
+    expect(pixel).toEqual([0, 0, 0, 0]);
+  });
+
+  it('should apply multiply blend mode', () => {
+    const bottom = createPixelLayer('Bottom');
+    const top = createPixelLayer('Top');
+    top.blendMode = 'multiply';
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(bottom.id, solidBuffer(1, 1, 200, 200, 200, 255));
+    data.set(top.id, solidBuffer(1, 1, 128, 128, 128, 255));
+
+    const result = composite([bottom, top], data, 1, 1);
+    const pixel = result.getPixel(0, 0);
+    // multiply: base * blend / 255 = 200 * 128 / 255 ~ 100
+    // With rounding: (200 * 128 + 127) / 255 = 25727 / 255 = 100
+    expect(pixel[0]).toBeGreaterThanOrEqual(99);
+    expect(pixel[0]).toBeLessThanOrEqual(101);
+  });
+
+  it('should apply screen blend mode', () => {
+    const bottom = createPixelLayer('Bottom');
+    const top = createPixelLayer('Top');
+    top.blendMode = 'screen';
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(bottom.id, solidBuffer(1, 1, 100, 100, 100, 255));
+    data.set(top.id, solidBuffer(1, 1, 100, 100, 100, 255));
+
+    const result = composite([bottom, top], data, 1, 1);
+    const pixel = result.getPixel(0, 0);
+    // screen: 255 - (255-100)*(255-100)/255 = 255 - 155*155/255 = 255 - 94 = 161
+    // With rounding: 255 - (155*155+127)/255 = 255 - 24152/255 = 255 - 94 = 161
+    expect(pixel[0]).toBeGreaterThanOrEqual(160);
+    expect(pixel[0]).toBeLessThanOrEqual(162);
+  });
+
+  it('should apply overlay blend mode', () => {
+    const bottom = createPixelLayer('Bottom');
+    const top = createPixelLayer('Top');
+    top.blendMode = 'overlay';
+
+    const data = new Map<string, PixelBuffer>();
+    // base < 128: uses multiply formula
+    data.set(bottom.id, solidBuffer(1, 1, 64, 64, 64, 255));
+    data.set(top.id, solidBuffer(1, 1, 128, 128, 128, 255));
+
+    const result = composite([bottom, top], data, 1, 1);
+    const pixel = result.getPixel(0, 0);
+    // overlay with base=64 (<128): 2*64*128/255 = 16384/255 ~ 64
+    // With rounding: (2*64*128+127)/255 = 16511/255 = 64
+    expect(pixel[0]).toBeGreaterThanOrEqual(63);
+    expect(pixel[0]).toBeLessThanOrEqual(65);
+  });
+
+  it('should handle semi-transparent layer over transparent background', () => {
+    const layer = createPixelLayer('Semi');
+
+    const data = new Map<string, PixelBuffer>();
+    data.set(layer.id, solidBuffer(1, 1, 255, 0, 0, 128));
+
+    const result = composite([layer], data, 1, 1);
+    const pixel = result.getPixel(0, 0);
+    expect(pixel[0]).toBe(255);
+    expect(pixel[1]).toBe(0);
+    expect(pixel[2]).toBe(0);
+    expect(pixel[3]).toBe(128);
+  });
+});

package/src/lib/layers/compositor.ts

@@ -0,0 +1,175 @@
+/**
+ * Layer Compositor -- flattens the layer tree into a single output PixelBuffer.
+ *
+ * Walks the tree bottom-to-top, compositing each visible pixel layer onto
+ * the output. Groups are recursively composited into an intermediate buffer,
+ * then blended onto the output with the group's opacity and blend mode.
+ *
+ * All math is integer-based (pixel values 0-255).
+ */
+
+import { PixelBuffer } from '../canvas/pixel-buffer.js';
+import type { Layer, BlendMode } from './layer-types.js';
+
+// --- Blend mode implementations ---
+// Each takes a base channel value and a blend channel value (both 0-255)
+// and returns the blended result (0-255).
+
+function blendNormal(_base: number, blend: number): number {
+  return blend;
+}
+
+function blendMultiply(base: number, blend: number): number {
+  return (base * blend + 127) / 255 | 0;
+}
+
+function blendScreen(base: number, blend: number): number {
+  return 255 - ((255 - base) * (255 - blend) + 127) / 255 | 0;
+}
+
+function blendOverlay(base: number, blend: number): number {
+  // If base < 128: multiply mode (2 * base * blend / 255)
+  // If base >= 128: screen mode (255 - 2 * (255-base) * (255-blend) / 255)
+  if (base < 128) {
+    return (2 * base * blend + 127) / 255 | 0;
+  }
+  return 255 - ((2 * (255 - base) * (255 - blend) + 127) / 255 | 0);
+}
+
+/** Get the blend function for a given blend mode. */
+function getBlendFn(mode: BlendMode): (base: number, blend: number) => number {
+  switch (mode) {
+    case 'normal':
+      return blendNormal;
+    case 'multiply':
+      return blendMultiply;
+    case 'screen':
+      return blendScreen;
+    case 'overlay':
+      return blendOverlay;
+  }
+}
+
+/**
+ * Blend a source pixel onto a destination pixel using source-over alpha compositing
+ * with a given blend mode. Modifies dst in place.
+ *
+ * @param dst - destination buffer
+ * @param di - byte offset into dst
+ * @param srcR, srcG, srcB, srcA - source pixel (srcA is 0-255, pre-opacity-adjusted)
+ * @param blendFn - the blend mode function for RGB channels
+ */
+function compositePixel(
+  dst: Uint8ClampedArray,
+  di: number,
+  srcR: number,
+  srcG: number,
+  srcB: number,
+  srcA: number,
+  blendFn: (base: number, blend: number) => number,
+): void {
+  if (srcA === 0) return;
+
+  // Uint8ClampedArray indexing is `number | undefined` under
+  // noUncheckedIndexedAccess; `?? 0` fallbacks never trigger for in-bounds i.
+  const dstR = dst[di] ?? 0;
+  const dstG = dst[di + 1] ?? 0;
+  const dstB = dst[di + 2] ?? 0;
+  const dstA = dst[di + 3] ?? 0;
+
+  // Normalize alpha to 0-1 range for compositing math
+  const sA = srcA / 255;
+  const dA = dstA / 255;
+
+  const outA = sA + dA * (1 - sA);
+  if (outA === 0) return;
+
+  // Apply blend mode to RGB channels
+  const blendedR = blendFn(dstR, srcR);
+  const blendedG = blendFn(dstG, srcG);
+  const blendedB = blendFn(dstB, srcB);
+
+  // Source-over compositing
+  dst[di] = Math.round((blendedR * sA + dstR * dA * (1 - sA)) / outA);
+  dst[di + 1] = Math.round((blendedG * sA + dstG * dA * (1 - sA)) / outA);
+  dst[di + 2] = Math.round((blendedB * sA + dstB * dA * (1 - sA)) / outA);
+  dst[di + 3] = Math.round(outA * 255);
+}
+
+/**
+ * Composite a single layer's pixel data onto a destination buffer.
+ */
+function compositeLayer(
+  dst: PixelBuffer,
+  src: PixelBuffer,
+  opacity: number,
+  blendMode: BlendMode,
+): void {
+  const blendFn = getBlendFn(blendMode);
+  const opacityFactor = opacity / 100;
+  const size = dst.width * dst.height * 4;
+
+  for (let i = 0; i < size; i += 4) {
+    const srcA = Math.round((src.data[i + 3] ?? 0) * opacityFactor);
+    if (srcA === 0) continue;
+
+    compositePixel(
+      dst.data,
+      i,
+      src.data[i] ?? 0,
+      src.data[i + 1] ?? 0,
+      src.data[i + 2] ?? 0,
+      srcA,
+      blendFn,
+    );
+  }
+}
+
+/**
+ * Recursively composite a list of layers into a buffer.
+ * Groups are composited into an intermediate buffer first, then blended
+ * onto the result with the group's opacity and blend mode.
+ */
+function compositeTree(
+  tree: Layer[],
+  pixelData: Map<string, PixelBuffer>,
+  width: number,
+  height: number,
+): PixelBuffer {
+  const result = new PixelBuffer(width, height);
+
+  for (const layer of tree) {
+    if (!layer.visible) continue;
+
+    if (layer.type === 'pixel') {
+      const data = pixelData.get(layer.id);
+      if (!data) continue;
+      compositeLayer(result, data, layer.opacity, layer.blendMode);
+    } else if (layer.children) {
+      // Recursively composite the group's children into an intermediate buffer
+      const groupBuffer = compositeTree(layer.children, pixelData, width, height);
+      // Then blend the group result onto the output with the group's opacity and blend mode
+      compositeLayer(result, groupBuffer, layer.opacity, layer.blendMode);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Composite all visible layers into a single PixelBuffer.
+ *
+ * @param tree - the root-level layer list (bottom-to-top order)
+ * @param pixelData - pixel data for each layer, keyed by layer ID
+ * @param width - canvas width in pixels
+ * @param height - canvas height in pixels
+ * @returns a new PixelBuffer with all visible layers composited
+ */
+export function composite(
+  tree: Layer[],
+  pixelData: Map<string, PixelBuffer>,
+  width: number,
+  height: number,
+): PixelBuffer {
+  return compositeTree(tree, pixelData, width, height);
+}