@palmerama/hd-canvas 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 palmerama
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# hd-canvas
+
+A TypeScript library for generative art with **HDR color**, configurable **paper sizes**, and **print-quality export**.
+
+Build artwork with unbounded float colors (values > 1.0 = super-bright HDR), preview it on screen with zoom/pan, and export print-ready PNGs at 300+ DPI with embedded resolution metadata.
+
+## Features
+
+- **Float32/Float64 HDR color buffers** — unbounded RGBA values, no 8-bit clamping during creation
+- **Paper size presets** — A0–A6, US Letter/Legal/Tabloid with DPI-aware pixel calculations
+- **Tone mapping** — Reinhard, ACES filmic, clamp, or custom algorithms to compress HDR → LDR on export
+- **Print-ready PNG export** — pHYs chunk injection for correct DPI metadata, 8-bit and 16-bit output
+- **Canvas 2D bridge** — draw with the familiar `fillRect`, `arc`, `fillText` API, auto-tiled for large formats
+- **Zoom/pan preview** — scroll-wheel zoom centered on cursor, click-drag pan, keyboard shortcuts, visible-region-only rendering
+- **Blend modes** — normal (alpha composite), additive, multiply — layer effects in HDR space
+- **Zero native dependencies** — pure JS PNG encoding via `fast-png`, runs in browser and Node.js
+
+## Install
+
+```bash
+npm install hd-canvas
+```
+
+## Quick Start
+
+```typescript
+import {
+  HDCanvas,
+  attachExportPipeline,
+  PreviewRenderer,
+} from 'hd-canvas';
+
+// 1. Create a canvas — A3 paper at 300 DPI
+const canvas = new HDCanvas({ paperSize: 'A3', dpi: 300 });
+
+// 2. Draw with HDR float colors
+for (let y = 0; y < canvas.heightPx; y++) {
+  for (let x = 0; x < canvas.widthPx; x++) {
+    const intensity = Math.random() * 3.0; // HDR: values > 1.0
+    canvas.setPixel(x, y, intensity, intensity * 0.6, 0.1, 1.0);
+  }
+}
+
+// 3. Preview on screen (browser only)
+const preview = new PreviewRenderer(canvas, {
+  container: document.getElementById('preview')!,
+});
+
+// 4. Export print-ready PNG
+attachExportPipeline(canvas);
+const blob = await canvas.export({ toneMap: 'aces', exposure: 0.5 });
+```
+
+## API Reference
+
+### Core
+
+#### `HDCanvas`
+
+The main class. Wraps a `ColorBuffer` with paper size and DPI configuration.
+
+```typescript
+const canvas = new HDCanvas({
+  paperSize: 'A4',           // or 'A3', 'letter', 'tabloid', etc.
+  dpi: 300,                  // default: 300
+  colorDepth: 32,            // 32 (Float32) or 64 (Float64), default: 32
+  orientation: 'portrait',   // 'portrait' or 'landscape', default: 'portrait'
+});
+
+canvas.widthPx;    // pixel width (e.g., 2480 for A4 @ 300 DPI)
+canvas.heightPx;   // pixel height (e.g., 3508 for A4 @ 300 DPI)
+canvas.dpi;        // configured DPI
+canvas.memoryBytes; // buffer memory usage in bytes
+```
+
+#### Pixel Drawing
+
+```typescript
+// Set a pixel (RGBA, unbounded floats)
+canvas.setPixel(x, y, r, g, b, a);
+
+// Read a pixel back
+const [r, g, b, a] = canvas.getPixel(x, y);
+
+// Blend onto existing content
+canvas.blendPixel(x, y, r, g, b, a, 'normal');  // alpha composite
+canvas.blendPixel(x, y, r, g, b, a, 'add');     // additive (glow effects)
+canvas.blendPixel(x, y, r, g, b, a, 'multiply'); // multiply (shadows)
+
+// Fill entire buffer
+canvas.clear(0, 0, 0, 1); // solid black
+
+// Region operations
+const region = canvas.getRegion(x, y, width, height); // extract sub-buffer
+canvas.putRegion(x, y, region);                        // paste sub-buffer
+```
+
+#### `ColorBuffer`
+
+The raw float pixel buffer. Used directly for advanced operations.
+
+```typescript
+import { ColorBuffer } from 'hd-canvas';
+
+const buf = new ColorBuffer(1920, 1080, 32); // width, height, depth
+buf.setPixel(0, 0, 1.5, 0.3, 0.0, 1.0);    // HDR orange
+buf.data; // Float32Array — direct access for bulk operations
+```
+
+#### Paper Sizes
+
+```typescript
+import { PAPER_SIZES, sizeToPx, resolvePaperSize, estimateBufferBytes } from 'hd-canvas';
+
+// All presets: A0–A6, letter, legal, tabloid
+PAPER_SIZES.A4;     // { widthMM: 210, heightMM: 297 }
+PAPER_SIZES.letter; // { widthMM: 215.9, heightMM: 279.4 }
+
+// Calculate pixel dimensions
+sizeToPx({ widthMM: 210, heightMM: 297 }, 300);
+// → { width: 2480, height: 3508 }
+
+// Resolve with orientation
+resolvePaperSize('A3', 'landscape');
+// → { widthMM: 420, heightMM: 297 }
+
+// Estimate memory before allocating
+estimateBufferBytes('A0', 300, 32); // ~2.07 GB for Float32
+estimateBufferBytes('A0', 300, 64); // ~4.14 GB for Float64
+```
+
+### Canvas 2D Bridge
+
+Draw with the familiar Canvas 2D API — shapes, text, paths, gradients — then continue with HDR pixel operations on top.
+
+```typescript
+// Draw convenience shapes with Canvas 2D
+canvas.drawWith2D((ctx) => {
+  ctx.fillStyle = '#1a1a2e';
+  ctx.fillRect(0, 0, canvas.widthPx, canvas.heightPx);
+
+  ctx.strokeStyle = 'white';
+  ctx.lineWidth = 3;
+  ctx.beginPath();
+  ctx.arc(canvas.widthPx / 2, canvas.heightPx / 2, 200, 0, Math.PI * 2);
+  ctx.stroke();
+
+  ctx.font = '72px serif';
+  ctx.fillStyle = 'white';
+  ctx.fillText('Hello HD', 100, 400);
+});
+
+// Then layer HDR effects on top
+canvas.blendPixel(x, y, 2.0, 0.5, 0.0, 0.8, 'add'); // HDR glow
+```
+
+**Options:**
+
+```typescript
+canvas.drawWith2D(callback, {
+  mode: 'blend',              // 'overwrite' (default) or 'blend'
+  blendMode: 'normal',        // 'normal', 'add', or 'multiply' (when mode is 'blend')
+  region: { x, y, width, height }, // draw into a sub-region only
+});
+```
+
+> **Note:** Canvas 2D is 8-bit, so this is for convenience shapes/text. For HDR drawing, use the pixel API directly. Large canvases (A0+) are automatically tiled at 4096px for browser compatibility.
+
+### Preview
+
+Interactive zoom/pan preview for browser environments.
+
+```typescript
+import { PreviewRenderer } from 'hd-canvas';
+
+const preview = new PreviewRenderer(canvas, {
+  container: document.getElementById('preview')!,
+});
+
+preview.refresh(); // re-render after drawing changes
+preview.destroy(); // clean up event listeners
+```
+
+**Controls:**
+- Scroll wheel: zoom (centered on cursor)
+- Click + drag: pan
+- `+` / `-` keys: zoom in/out
+- `0` key: reset zoom
+- Double-click: fit to view
+
+### Tone Mapping
+
+Compress HDR float values to displayable/exportable range.
+
+```typescript
+import { ToneMapper, reinhard, aces, clamp } from 'hd-canvas';
+
+// Use standalone functions
+reinhard(2.0);  // → 0.667 (smooth compression)
+aces(2.0);      // → 0.928 (filmic look)
+clamp(2.0);     // → 1.0 (hard clip)
+
+// Or the full pipeline
+const mapper = new ToneMapper({
+  algorithm: 'aces',    // 'reinhard', 'aces', 'clamp', or custom function
+  exposure: 1.0,        // stops: multiply by 2^exposure before mapping
+  gamma: 2.2,           // sRGB gamma correction (default: 2.2)
+  outputDepth: 8,       // 8 → Uint8Array, 16 → Uint16Array
+});
+
+const ldrPixels = mapper.map(canvas.buffer); // Uint8Array RGBA
+```
+
+**Custom tone mapping:**
+
+```typescript
+const mapper = new ToneMapper({
+  algorithm: (v: number) => Math.sqrt(Math.min(1, v)), // square root compression
+  gamma: 1.0,
+});
+```
+
+### Export
+
+Print-ready PNG export with DPI metadata.
+
+```typescript
+import { attachExportPipeline, exportBuffer, exportAndDownload } from 'hd-canvas';
+
+// Option 1: Attach to HDCanvas (recommended)
+attachExportPipeline(canvas);
+const blob = await canvas.export({
+  toneMap: 'aces',     // tone mapping algorithm
+  exposure: 0.5,       // exposure adjustment (stops)
+  gamma: 2.2,          // gamma correction
+});
+
+// Option 2: Export with progress tracking
+attachExportPipeline(canvas, (percent) => {
+  console.log(`Export: ${percent}%`);
+});
+
+// Option 3: Standalone function (no HDCanvas needed)
+const blob2 = exportBuffer(colorBuffer, {
+  dpi: 300,
+  toneMap: 'reinhard',
+  exposure: 0,
+  gamma: 2.2,
+});
+
+// Option 4: Export + browser download in one call
+await exportAndDownload(canvas, { toneMap: 'aces' }, 'my-artwork.png');
+```
+
+#### PNG Exporter (low-level)
+
+```typescript
+import { PNGExporter, dpiToPixelsPerMeter } from 'hd-canvas';
+
+const exporter = new PNGExporter();
+
+// 8-bit export
+const result = exporter.export(uint8Data, {
+  width: 2480,
+  height: 3508,
+  dpi: 300,
+  depth: 8,
+});
+// result.data: Uint8Array (raw PNG bytes)
+// result.mimeType: 'image/png'
+// result.filename: 'artwork-2480x3508-300dpi.png'
+
+// 16-bit export for maximum quality
+const result16 = exporter.export(uint16Data, {
+  width: 2480,
+  height: 3508,
+  dpi: 300,
+  depth: 16,
+});
+
+// DPI conversion utility
+dpiToPixelsPerMeter(300); // → 11811
+```
+
+## Examples
+
+### Generative Flow Field
+
+```typescript
+import { HDCanvas, attachExportPipeline } from 'hd-canvas';
+
+const canvas = new HDCanvas({ paperSize: 'A3', dpi: 300 });
+canvas.clear(0.02, 0.02, 0.05, 1.0); // near-black background
+
+// Generate flow field with HDR highlights
+for (let i = 0; i < 50000; i++) {
+  let x = Math.random() * canvas.widthPx;
+  let y = Math.random() * canvas.heightPx;
+
+  for (let step = 0; step < 100; step++) {
+    const angle = noise2D(x * 0.001, y * 0.001) * Math.PI * 4;
+    x += Math.cos(angle) * 2;
+    y += Math.sin(angle) * 2;
+
+    if (x < 0 || x >= canvas.widthPx || y < 0 || y >= canvas.heightPx) break;
+
+    // Additive blending creates natural HDR glow at intersections
+    canvas.blendPixel(
+      Math.floor(x), Math.floor(y),
+      0.02, 0.015, 0.03,  // subtle per-step contribution
+      0.5,                  // semi-transparent
+      'add'                 // accumulates beyond 1.0 = HDR
+    );
+  }
+}
+
+// ACES tone mapping compresses the HDR glow beautifully
+attachExportPipeline(canvas);
+const blob = await canvas.export({ toneMap: 'aces', exposure: 1.5 });
+```
+
+### Layered Composition
+
+```typescript
+const canvas = new HDCanvas({ paperSize: 'letter', dpi: 300 });
+
+// Layer 1: Canvas 2D background
+canvas.drawWith2D((ctx) => {
+  const grad = ctx.createLinearGradient(0, 0, 0, canvas.heightPx);
+  grad.addColorStop(0, '#0a0a2e');
+  grad.addColorStop(1, '#1a0a3e');
+  ctx.fillStyle = grad;
+  ctx.fillRect(0, 0, canvas.widthPx, canvas.heightPx);
+});
+
+// Layer 2: HDR particle system (blend on top)
+for (const particle of particles) {
+  canvas.blendPixel(
+    particle.x, particle.y,
+    particle.energy * 2.0,  // HDR intensity
+    particle.energy * 0.8,
+    particle.energy * 0.3,
+    0.6,
+    'add'
+  );
+}
+
+// Layer 3: Canvas 2D text overlay (blend mode preserves HDR underneath)
+canvas.drawWith2D((ctx) => {
+  ctx.font = 'bold 120px sans-serif';
+  ctx.fillStyle = 'rgba(255, 255, 255, 0.9)';
+  ctx.fillText('ENERGY', 100, canvas.heightPx / 2);
+}, { mode: 'blend' });
+```
+
+### Custom Paper Size
+
+```typescript
+const canvas = new HDCanvas({
+  paperSize: { widthMM: 300, heightMM: 300 }, // 30cm square
+  dpi: 600,  // high quality
+  colorDepth: 64,  // Float64 for maximum precision
+});
+```
+
+## Paper Size Reference
+
+| Size | Dimensions (mm) | Pixels @ 300 DPI | Memory (Float32) |
+|------|-----------------|-------------------|-------------------|
+| A6 | 105 × 148 | 1240 × 1748 | 8.3 MB |
+| A5 | 148 × 210 | 1748 × 2480 | 16.6 MB |
+| A4 | 210 × 297 | 2480 × 3508 | 33.3 MB |
+| A3 | 297 × 420 | 3508 × 4961 | 66.6 MB |
+| A2 | 420 × 594 | 4961 × 7016 | 133 MB |
+| A1 | 594 × 841 | 7016 × 9933 | 267 MB |
+| A0 | 841 × 1189 | 9933 × 14043 | 534 MB |
+| Letter | 215.9 × 279.4 | 2550 × 3300 | 32.2 MB |
+| Legal | 215.9 × 355.6 | 2550 × 4200 | 41.0 MB |
+| Tabloid | 279.4 × 431.8 | 3300 × 5100 | 64.5 MB |
+
+> Memory shown is for the pixel buffer only (4 × Float32 per pixel). Float64 doubles these values.
+
+## Architecture
+
+```
+hd-canvas/
+  src/
+    core/
+      ColorBuffer.ts    — Float32/Float64 RGBA pixel buffer
+      PaperSize.ts      — Paper size registry + DPI calculations
+      HDCanvas.ts       — Main class, wires everything together
+    preview/
+      PreviewRenderer.ts — Zoom/pan interactive preview
+      FitStrategy.ts     — Contain/cover fitting math
+    bridge/
+      Canvas2DBridge.ts  — Canvas 2D API → float buffer bridge
+    export/
+      ToneMapper.ts      — HDR → LDR tone mapping algorithms
+      PNGExporter.ts     — PNG encoding with DPI metadata
+      ExportPipeline.ts  — Glue: tone map → encode → Blob
+    index.ts             — Unified public API
+```
+
+**Design principles:**
+- **Dependency injection** — preview and export are pluggable, core has no DOM dependency
+- **Interface segregation** — export pipeline codes against `IColorBuffer`, not the full `ColorBuffer`
+- **Fail hard** — out-of-bounds pixels, invalid dimensions, and bad options throw immediately
+- **One code path** — no duplicated logic, no silent fallbacks
+
+## License
+
+MIT

package/dist/bridge/Canvas2DBridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Canvas2DBridge — Draw with the familiar Canvas 2D API into an HDR float buffer
+ *
+ * Creates a temporary offscreen canvas at full resolution (or tiled for large
+ * formats), passes the 2D context to a user callback, reads back ImageData,
+ * and writes into the ColorBuffer as float values (0–255 → 0.0–1.0).
+ *
+ * This is a one-way bridge: Canvas 2D → float buffer. The 2D context is 8-bit,
+ * so this is for convenience shapes/text, not HDR input.
+ */
+import { ColorBuffer, type BlendMode } from '../core/ColorBuffer.js';
+export interface DrawWith2DOptions {
+    /** How to combine with existing buffer content. Default: 'overwrite' */
+    mode?: 'overwrite' | 'blend';
+    /** Blend mode when mode is 'blend'. Default: 'normal' */
+    blendMode?: BlendMode;
+    /** Region to draw into (default: full canvas). */
+    region?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+/**
+ * Execute a Canvas 2D drawing callback and write the result into a ColorBuffer.
+ *
+ * For buffers larger than MAX_TILE_SIZE in either dimension, the drawing is
+ * automatically tiled: the callback is invoked once per tile with the context
+ * translated so the user draws in full-canvas coordinates.
+ */
+export declare function drawWith2D(buffer: ColorBuffer, callback: (ctx: CanvasRenderingContext2D) => void, options?: DrawWith2DOptions): void;
+/** Exported for testing */
+export declare const _internals: {
+    MAX_TILE_SIZE: number;
+};
+//# sourceMappingURL=Canvas2DBridge.d.ts.map

package/dist/bridge/Canvas2DBridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Canvas2DBridge.d.ts","sourceRoot":"","sources":["../../src/bridge/Canvas2DBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAErE,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC;IAC7B,yDAAyD;IACzD,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,kDAAkD;IAClD,MAAM,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAClE;AASD;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,CAAC,GAAG,EAAE,wBAAwB,KAAK,IAAI,EACjD,OAAO,GAAE,iBAAsB,GAC9B,IAAI,CA8BN;AAgGD,2BAA2B;AAC3B,eAAO,MAAM,UAAU;;CAAoB,CAAC"}

package/dist/bridge/Canvas2DBridge.js

@@ -0,0 +1,116 @@
+/**
+ * Canvas2DBridge — Draw with the familiar Canvas 2D API into an HDR float buffer
+ *
+ * Creates a temporary offscreen canvas at full resolution (or tiled for large
+ * formats), passes the 2D context to a user callback, reads back ImageData,
+ * and writes into the ColorBuffer as float values (0–255 → 0.0–1.0).
+ *
+ * This is a one-way bridge: Canvas 2D → float buffer. The 2D context is 8-bit,
+ * so this is for convenience shapes/text, not HDR input.
+ */
+/**
+ * Maximum tile dimension in pixels. Conservative to support all major browsers.
+ * Chrome: ~16384, Firefox: ~11180, Safari: ~4096.
+ * We use 4096 for maximum compatibility.
+ */
+const MAX_TILE_SIZE = 4096;
+/**
+ * Execute a Canvas 2D drawing callback and write the result into a ColorBuffer.
+ *
+ * For buffers larger than MAX_TILE_SIZE in either dimension, the drawing is
+ * automatically tiled: the callback is invoked once per tile with the context
+ * translated so the user draws in full-canvas coordinates.
+ */
+export function drawWith2D(buffer, callback, options = {}) {
+    const mode = options.mode ?? 'overwrite';
+    const blendMode = options.blendMode ?? 'normal';
+    // Determine the target region
+    const region = options.region ?? { x: 0, y: 0, width: buffer.width, height: buffer.height };
+    validateRegion(region, buffer.width, buffer.height);
+    const { x: rx, y: ry, width: rw, height: rh } = region;
+    // Determine if we need tiling
+    if (rw <= MAX_TILE_SIZE && rh <= MAX_TILE_SIZE) {
+        // Single pass — no tiling needed
+        drawTile(buffer, callback, rx, ry, rw, rh, mode, blendMode);
+    }
+    else {
+        // Tiled rendering
+        for (let ty = 0; ty < rh; ty += MAX_TILE_SIZE) {
+            const tileH = Math.min(MAX_TILE_SIZE, rh - ty);
+            for (let tx = 0; tx < rw; tx += MAX_TILE_SIZE) {
+                const tileW = Math.min(MAX_TILE_SIZE, rw - tx);
+                drawTile(buffer, callback, rx + tx, ry + ty, tileW, tileH, mode, blendMode);
+            }
+        }
+    }
+}
+/**
+ * Draw a single tile: create an offscreen canvas, invoke the callback with
+ * a translated context, read back pixels, write into the buffer.
+ */
+function drawTile(buffer, callback, tileX, tileY, tileW, tileH, mode, blendMode) {
+    // Create offscreen canvas for this tile
+    const offscreen = document.createElement('canvas');
+    offscreen.width = tileW;
+    offscreen.height = tileH;
+    const ctx = offscreen.getContext('2d');
+    if (!ctx) {
+        throw new Error('Failed to get 2D rendering context for offscreen canvas');
+    }
+    // Translate so the user draws in full-canvas coordinates
+    ctx.translate(-tileX, -tileY);
+    // Clip to the tile region (prevents drawing outside tile bounds)
+    ctx.beginPath();
+    ctx.rect(tileX, tileY, tileW, tileH);
+    ctx.clip();
+    // Let the user draw
+    callback(ctx);
+    // Read back pixels
+    const imageData = ctx.getImageData(0, 0, tileW, tileH);
+    const pixels = imageData.data; // Uint8ClampedArray, RGBA
+    // Write into the float buffer
+    const inv255 = 1 / 255;
+    if (mode === 'overwrite') {
+        for (let row = 0; row < tileH; row++) {
+            for (let col = 0; col < tileW; col++) {
+                const srcIdx = (row * tileW + col) * 4;
+                const r = pixels[srcIdx] * inv255;
+                const g = pixels[srcIdx + 1] * inv255;
+                const b = pixels[srcIdx + 2] * inv255;
+                const a = pixels[srcIdx + 3] * inv255;
+                buffer.setPixel(tileX + col, tileY + row, r, g, b, a);
+            }
+        }
+    }
+    else {
+        // Blend mode — alpha composite onto existing content
+        for (let row = 0; row < tileH; row++) {
+            for (let col = 0; col < tileW; col++) {
+                const srcIdx = (row * tileW + col) * 4;
+                const r = pixels[srcIdx] * inv255;
+                const g = pixels[srcIdx + 1] * inv255;
+                const b = pixels[srcIdx + 2] * inv255;
+                const a = pixels[srcIdx + 3] * inv255;
+                // Skip fully transparent pixels (common optimization)
+                if (a === 0)
+                    continue;
+                buffer.blendPixel(tileX + col, tileY + row, r, g, b, a, blendMode);
+            }
+        }
+    }
+    // Clean up — remove references to allow GC
+    offscreen.width = 0;
+    offscreen.height = 0;
+}
+function validateRegion(region, bufferWidth, bufferHeight) {
+    const { x, y, width, height } = region;
+    if (x < 0 || y < 0 || width <= 0 || height <= 0) {
+        throw new RangeError(`Region must have non-negative origin and positive dimensions, got (${x},${y} ${width}×${height})`);
+    }
+    if (x + width > bufferWidth || y + height > bufferHeight) {
+        throw new RangeError(`Region (${x},${y} ${width}×${height}) exceeds buffer bounds ${bufferWidth}×${bufferHeight}`);
+    }
+}
+/** Exported for testing */
+export const _internals = { MAX_TILE_SIZE };
+//# sourceMappingURL=Canvas2DBridge.js.map

package/dist/bridge/Canvas2DBridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Canvas2DBridge.js","sourceRoot":"","sources":["../../src/bridge/Canvas2DBridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAaH;;;;GAIG;AACH,MAAM,aAAa,GAAG,IAAI,CAAC;AAE3B;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CACxB,MAAmB,EACnB,QAAiD,EACjD,UAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,WAAW,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC;IAEhD,8BAA8B;IAC9B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC;IAE5F,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAEpD,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC;IAEvD,8BAA8B;IAC9B,IAAI,EAAE,IAAI,aAAa,IAAI,EAAE,IAAI,aAAa,EAAE,CAAC;QAC/C,iCAAiC;QACjC,QAAQ,CAAC,MAAM,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC;SAAM,CAAC;QACN,kBAAkB;QAClB,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,aAAa,EAAE,CAAC;YAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YAC/C,KAAK,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,EAAE,IAAI,aAAa,EAAE,CAAC;gBAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC/C,QAAQ,CACN,MAAM,EAAE,QAAQ,EAChB,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,EAChB,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,SAAS,CAChB,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,SAAS,QAAQ,CACf,MAAmB,EACnB,QAAiD,EACjD,KAAa,EACb,KAAa,EACb,KAAa,EACb,KAAa,EACb,IAA2B,EAC3B,SAAoB;IAEpB,wCAAwC;IACxC,MAAM,SAAS,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IACnD,SAAS,CAAC,KAAK,GAAG,KAAK,CAAC;IACxB,SAAS,CAAC,MAAM,GAAG,KAAK,CAAC;IAEzB,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACvC,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;IAC7E,CAAC;IAED,yDAAyD;IACzD,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IAE9B,iEAAiE;IACjE,GAAG,CAAC,SAAS,EAAE,CAAC;IAChB,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACrC,GAAG,CAAC,IAAI,EAAE,CAAC;IAEX,oBAAoB;IACpB,QAAQ,CAAC,GAAG,CAAC,CAAC;IAEd,mBAAmB;IACnB,MAAM,SAAS,GAAG,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,0BAA0B;IAEzD,8BAA8B;IAC9B,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC;IAEvB,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;YACrC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;gBACrC,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;gBACvC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAE,GAAG,MAAM,CAAC;gBACnC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,MAAM,CAAC;gBACvC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,MAAM,CAAC;gBACvC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,MAAM,CAAC;gBACvC,MAAM,CAAC,QAAQ,CAAC,KAAK,GAAG,GAAG,EAAE,KAAK,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,qDAAqD;QACrD,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;YACrC,KAAK,IAAI,GAAG,GAAG,CAAC,EAAE,GAAG,GAAG,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC;gBACrC,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;gBACvC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,CAAE,GAAG,MAAM,CAAC;gBACnC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,MAAM,CAAC;gBACvC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,MAAM,CAAC;gBACvC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,GAAG,MAAM,CAAC;gBAEvC,sDAAsD;gBACtD,IAAI,CAAC,KAAK,CAAC;oBAAE,SAAS;gBAEtB,MAAM,CAAC,UAAU,CAAC,KAAK,GAAG,GAAG,EAAE,KAAK,GAAG,GAAG,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,SAAS,CAAC,KAAK,GAAG,CAAC,CAAC;IACpB,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,cAAc,CACrB,MAA+D,EAC/D,WAAmB,EACnB,YAAoB;IAEpB,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACvC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,UAAU,CAClB,sEAAsE,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,MAAM,GAAG,CACnG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,GAAG,KAAK,GAAG,WAAW,IAAI,CAAC,GAAG,MAAM,GAAG,YAAY,EAAE,CAAC;QACzD,MAAM,IAAI,UAAU,CAClB,WAAW,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,MAAM,2BAA2B,WAAW,IAAI,YAAY,EAAE,CAC7F,CAAC;IACJ,CAAC;AACH,CAAC;AAED,2BAA2B;AAC3B,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,aAAa,EAAE,CAAC"}

package/dist/core/ColorBuffer.d.ts

@@ -0,0 +1,41 @@
+/**
+ * ColorBuffer — Float32/Float64 RGBA pixel buffer
+ *
+ * The foundation of the HD Canvas framework. Stores pixel data as
+ * unbounded floats (0.0–1.0 is "standard" range, >1.0 is HDR).
+ * Row-major layout, 4 floats per pixel (R, G, B, A).
+ */
+export type ColorDepth = 32 | 64;
+export type BlendMode = 'normal' | 'add' | 'multiply';
+export type RGBA = [r: number, g: number, b: number, a: number];
+/** Minimal interface for reading pixel data — used by the export pipeline. */
+export interface IColorBuffer {
+    readonly width: number;
+    readonly height: number;
+    readonly depth: ColorDepth;
+    readonly data: Float32Array | Float64Array;
+}
+export declare class ColorBuffer implements IColorBuffer {
+    readonly width: number;
+    readonly height: number;
+    readonly depth: ColorDepth;
+    readonly data: Float32Array | Float64Array;
+    constructor(width: number, height: number, depth?: ColorDepth);
+    /** Byte size of the underlying typed array */
+    get byteLength(): number;
+    private offset;
+    setPixel(x: number, y: number, r: number, g: number, b: number, a?: number): void;
+    getPixel(x: number, y: number): RGBA;
+    /**
+     * Blend a color onto the existing pixel using the specified blend mode.
+     * All modes use standard alpha compositing for the alpha channel.
+     */
+    blendPixel(x: number, y: number, r: number, g: number, b: number, a: number, mode?: BlendMode): void;
+    /** Fill the entire buffer with a single color (default: transparent black) */
+    clear(r?: number, g?: number, b?: number, a?: number): void;
+    /** Extract a rectangular region as a new ColorBuffer */
+    getRegion(x: number, y: number, w: number, h: number): ColorBuffer;
+    /** Write a ColorBuffer region into this buffer at the given position */
+    putRegion(x: number, y: number, region: ColorBuffer): void;
+}
+//# sourceMappingURL=ColorBuffer.d.ts.map

package/dist/core/ColorBuffer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ColorBuffer.d.ts","sourceRoot":"","sources":["../../src/core/ColorBuffer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,UAAU,GAAG,EAAE,GAAG,EAAE,CAAC;AACjC,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,KAAK,GAAG,UAAU,CAAC;AACtD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC;AAEhE,8EAA8E;AAC9E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;CAC5C;AAED,qBAAa,WAAY,YAAW,YAAY;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,CAAC;gBAE/B,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,UAAe;IAgBjE,8CAA8C;IAC9C,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,OAAO,CAAC,MAAM;IASd,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,GAAE,MAAY,GAAG,IAAI;IAQtF,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,IAAI;IAUpC;;;OAGG;IACH,UAAU,CACR,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,IAAI,GAAE,SAAoB,GACzB,IAAI;IAgDP,8EAA8E;IAC9E,KAAK,CAAC,CAAC,GAAE,MAAU,EAAE,CAAC,GAAE,MAAU,EAAE,CAAC,GAAE,MAAU,EAAE,CAAC,GAAE,MAAU,GAAG,IAAI;IASvE,wDAAwD;IACxD,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,WAAW;IAmBlE,wEAAwE;IACxE,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,IAAI;CAa3D"}