novac 2.1.1 → 2.2.0

package/kits/kitcanvas/kitdef.js

@@ -0,0 +1,914 @@
+// kitcanvas — novac drawing kit
+// Renderer-agnostic: YOU supply the renderer, kitcanvas does the drawing.
+//
+// Minimum renderer contract:
+//   renderer.width          — number
+//   renderer.height         — number
+//   renderer.setPixel(x, y, { color, alpha?, ... })
+//
+// Optional renderer extras (kitcanvas uses them if present):
+//   renderer.writeText(x, y, text, opts)
+//   renderer.clear(color?)
+//   renderer.flush()
+//   renderer.getPixel(x, y) → { color, ... }
+//   renderer.resize(w, h)
+//   renderer.save(path)      — for file-backed renderers
+//   renderer.toBuffer()      — returns raw pixel buffer
+//   renderer.toDataURL()     — returns base64 data URL
+
+'use strict';
+
+// ─── COLOR UTILS ─────────────────────────────────────────────────────────────
+
+const NAMED_COLORS = {
+  red:     [255, 0,   0  ], green:   [0,   128, 0  ], blue:    [0,   0,   255],
+  white:   [255, 255, 255], black:   [0,   0,   0  ], yellow:  [255, 255, 0  ],
+  cyan:    [0,   255, 255], magenta: [255, 0,   255], orange:  [255, 165, 0  ],
+  purple:  [128, 0,   128], pink:    [255, 192, 203], brown:   [165, 42,  42 ],
+  gray:    [128, 128, 128], grey:    [128, 128, 128], silver:  [192, 192, 192],
+  gold:    [255, 215, 0  ], lime:    [0,   255, 0  ], navy:    [0,   0,   128],
+  teal:    [0,   128, 128], maroon:  [128, 0,   0  ], olive:   [128, 128, 0  ],
+  coral:   [255, 127, 80 ], salmon:  [250, 128, 114], khaki:   [240, 230, 140],
+  indigo:  [75,  0,   130], violet:  [238, 130, 238], beige:   [245, 245, 220],
+  ivory:   [255, 255, 240], lavender:[230, 230, 250], mint:    [152, 255, 152],
+  transparent: [0, 0, 0],
+};
+
+/**
+ * Parse a color value to { r, g, b, a }.
+ * Accepts:
+ *   - named color string: 'red', 'blue', ...
+ *   - hex string: '#rgb', '#rrggbb', '#rrggbbaa'
+ *   - rgb string: 'rgb(255,0,0)'
+ *   - rgba string: 'rgba(255,0,0,0.5)'
+ *   - [r, g, b] / [r, g, b, a] array
+ *   - { r, g, b, a? } object
+ *   - number 0xRRGGBB
+ */
+function parseColor(color, alpha = 255) {
+  if (!color) return { r: 0, g: 0, b: 0, a: alpha };
+
+  if (typeof color === 'number') {
+    return { r: (color >> 16) & 0xff, g: (color >> 8) & 0xff, b: color & 0xff, a: alpha };
+  }
+
+  if (Array.isArray(color)) {
+    return { r: color[0] ?? 0, g: color[1] ?? 0, b: color[2] ?? 0, a: color[3] ?? alpha };
+  }
+
+  if (typeof color === 'object') {
+    return { r: color.r ?? 0, g: color.g ?? 0, b: color.b ?? 0, a: color.a ?? alpha };
+  }
+
+  if (typeof color === 'string') {
+    const lower = color.toLowerCase().trim();
+
+    // named
+    if (NAMED_COLORS[lower]) {
+      const [r, g, b] = NAMED_COLORS[lower];
+      return { r, g, b, a: lower === 'transparent' ? 0 : alpha };
+    }
+
+    // hex
+    if (lower.startsWith('#')) {
+      const hex = lower.slice(1);
+      if (hex.length === 3) {
+        return { r: parseInt(hex[0]+hex[0],16), g: parseInt(hex[1]+hex[1],16), b: parseInt(hex[2]+hex[2],16), a: alpha };
+      }
+      if (hex.length === 6) {
+        return { r: parseInt(hex.slice(0,2),16), g: parseInt(hex.slice(2,4),16), b: parseInt(hex.slice(4,6),16), a: alpha };
+      }
+      if (hex.length === 8) {
+        return { r: parseInt(hex.slice(0,2),16), g: parseInt(hex.slice(2,4),16), b: parseInt(hex.slice(4,6),16), a: parseInt(hex.slice(6,8),16) };
+      }
+    }
+
+    // rgb(...)
+    const rgbMatch = lower.match(/^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:\s*,\s*([\d.]+))?\s*\)$/);
+    if (rgbMatch) {
+      const a = rgbMatch[4] !== undefined ? Math.round(parseFloat(rgbMatch[4]) * 255) : alpha;
+      return { r: +rgbMatch[1], g: +rgbMatch[2], b: +rgbMatch[3], a };
+    }
+  }
+
+  throw new Error(`kitcanvas: Cannot parse color: ${JSON.stringify(color)}`);
+}
+
+function colorToHex({ r, g, b, a }) {
+  const h = n => n.toString(16).padStart(2, '0');
+  return `#${h(r)}${h(g)}${h(b)}${a !== 255 ? h(a) : ''}`;
+}
+
+function lerpColor(c1, c2, t) {
+  const a = parseColor(c1), b = parseColor(c2);
+  return {
+    r: Math.round(a.r + (b.r - a.r) * t),
+    g: Math.round(a.g + (b.g - a.g) * t),
+    b: Math.round(a.b + (b.b - a.b) * t),
+    a: Math.round(a.a + (b.a - a.a) * t),
+  };
+}
+
+// ─── CANVAS CLASS ─────────────────────────────────────────────────────────────
+
+class Canvas {
+  /**
+   * Create a Canvas backed by a renderer.
+   * @param {object} renderer - Must implement width, height, setPixel(x,y,opts).
+   */
+  constructor(renderer) {
+    if (!renderer)           throw new Error('kitcanvas: renderer is required');
+    if (!renderer.setPixel)  throw new Error('kitcanvas: renderer must implement setPixel(x, y, opts)');
+    if (renderer.width  == null) throw new Error('kitcanvas: renderer must have .width');
+    if (renderer.height == null) throw new Error('kitcanvas: renderer must have .height');
+
+    this._r     = renderer;
+    this._color = '#000000';
+    this._alpha = 255;
+    this._fill  = '#000000';
+    this._lineWidth = 1;
+    this._transform = { tx: 0, ty: 0, sx: 1, sy: 1 };
+    this._clipRect  = null;
+    this._stack     = [];
+  }
+
+  get width()  { return this._r.width; }
+  get height() { return this._r.height; }
+
+  // ── State ──────────────────────────────────────────────────────────────────
+
+  /** Set stroke color. Accepts any color format. */
+  color(c) { this._color = c; return this; }
+
+  /** Set fill color. */
+  fill(c) { this._fill = c; return this; }
+
+  /** Set stroke alpha (0-255 or 0.0-1.0). */
+  alpha(a) { this._alpha = a <= 1 ? Math.round(a * 255) : Math.round(a); return this; }
+
+  /** Set line width. */
+  lineWidth(w) { this._lineWidth = Math.max(1, Math.round(w)); return this; }
+
+  /** Save current state (color, fill, alpha, lineWidth, transform, clip). */
+  save() {
+    this._stack.push({
+      color: this._color, fill: this._fill, alpha: this._alpha,
+      lineWidth: this._lineWidth, transform: { ...this._transform },
+      clipRect: this._clipRect ? { ...this._clipRect } : null,
+    });
+    return this;
+  }
+
+  /** Restore last saved state. */
+  restore() {
+    const s = this._stack.pop();
+    if (s) Object.assign(this, { _color: s.color, _fill: s.fill, _alpha: s.alpha, _lineWidth: s.lineWidth, _transform: s.transform, _clipRect: s.clipRect });
+    return this;
+  }
+
+  /** Translate origin. */
+  translate(tx, ty) { this._transform.tx += tx; this._transform.ty += ty; return this; }
+
+  /** Scale drawing. */
+  scale(sx, sy = sx) { this._transform.sx *= sx; this._transform.sy *= sy; return this; }
+
+  /** Reset transform. */
+  resetTransform() { this._transform = { tx: 0, ty: 0, sx: 1, sy: 1 }; return this; }
+
+  /** Set clip rectangle — nothing outside is drawn. */
+  clip(x, y, w, h) { this._clipRect = { x, y, w, h }; return this; }
+
+  /** Remove clip. */
+  unclip() { this._clipRect = null; return this; }
+
+  // ── Low-level ──────────────────────────────────────────────────────────────
+
+  _tx(x) { return Math.round(x * this._transform.sx + this._transform.tx); }
+  _ty(y) { return Math.round(y * this._transform.sy + this._transform.ty); }
+
+  _inBounds(x, y) {
+    if (x < 0 || y < 0 || x >= this._r.width || y >= this._r.height) return false;
+    if (this._clipRect) {
+      const c = this._clipRect;
+      if (x < c.x || y < c.y || x >= c.x + c.w || y >= c.y + c.h) return false;
+    }
+    return true;
+  }
+
+  /**
+   * Set a single pixel.
+   * @param {number} x
+   * @param {number} y
+   * @param {object} [opts] - { color, alpha }
+   */
+  setPixel(x, y, opts = {}) {
+    const px = this._tx(x), py = this._ty(y);
+    if (!this._inBounds(px, py)) return this;
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    this._r.setPixel(px, py, { ...opts, color });
+    return this;
+  }
+
+  // ── Clear ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Clear the canvas.
+   * @param {string|Array} [color='white']
+   */
+  clear(color = 'white') {
+    if (this._r.clear) { this._r.clear(parseColor(color)); return this; }
+    const c = parseColor(color);
+    for (let y = 0; y < this._r.height; y++)
+      for (let x = 0; x < this._r.width; x++)
+        this._r.setPixel(x, y, { color: c });
+    return this;
+  }
+
+  // ── Shapes ─────────────────────────────────────────────────────────────────
+
+  /**
+   * Draw a single pixel point.
+   */
+  point(x, y, opts = {}) { return this.setPixel(x, y, opts); }
+
+  /**
+   * Draw a line using Bresenham's algorithm.
+   * @param {number} x1
+   * @param {number} y1
+   * @param {number} x2
+   * @param {number} y2
+   * @param {object} [opts]
+   */
+  line(x1, y1, x2, y2, opts = {}) {
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    const w     = Math.max(1, opts.lineWidth ?? this._lineWidth);
+    const draw  = (x, y) => {
+      for (let dy = -Math.floor(w/2); dy <= Math.floor(w/2); dy++)
+        for (let dx = -Math.floor(w/2); dx <= Math.floor(w/2); dx++) {
+          const px = this._tx(x+dx), py = this._ty(y+dy);
+          if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+        }
+    };
+
+    let [ax, ay, bx, by] = [Math.round(x1), Math.round(y1), Math.round(x2), Math.round(y2)];
+    const dx = Math.abs(bx - ax), dy = Math.abs(by - ay);
+    const sx = ax < bx ? 1 : -1,   sy = ay < by ? 1 : -1;
+    let err = dx - dy;
+    while (true) {
+      draw(ax, ay);
+      if (ax === bx && ay === by) break;
+      const e2 = 2 * err;
+      if (e2 > -dy) { err -= dy; ax += sx; }
+      if (e2 < dx)  { err += dx; ay += sy; }
+    }
+    return this;
+  }
+
+  /**
+   * Draw a rectangle outline.
+   */
+  box(x, y, w, h, opts = {}) {
+    this.line(x,     y,     x+w-1, y,     opts);
+    this.line(x+w-1, y,     x+w-1, y+h-1, opts);
+    this.line(x+w-1, y+h-1, x,     y+h-1, opts);
+    this.line(x,     y+h-1, x,     y,     opts);
+    return this;
+  }
+
+  /**
+   * Draw a filled rectangle.
+   */
+  fillBox(x, y, w, h, opts = {}) {
+    const color = parseColor(opts.color ?? this._fill, opts.alpha ?? this._alpha);
+    for (let row = y; row < y + h; row++) {
+      for (let col = x; col < x + w; col++) {
+        const px = this._tx(col), py = this._ty(row);
+        if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Draw a circle outline using Bresenham's circle algorithm.
+   */
+  circle(cx, cy, radius, opts = {}) {
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    const plot  = (x, y) => { const px = this._tx(x), py = this._ty(y); if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color }); };
+    let x = 0, y = radius, d = 3 - 2 * radius;
+    while (y >= x) {
+      plot(cx+x, cy+y); plot(cx-x, cy+y); plot(cx+x, cy-y); plot(cx-x, cy-y);
+      plot(cx+y, cy+x); plot(cx-y, cy+x); plot(cx+y, cy-x); plot(cx-y, cy-x);
+      if (d < 0) d += 4 * x + 6;
+      else { d += 4 * (x - y) + 10; y--; }
+      x++;
+    }
+    return this;
+  }
+
+  /**
+   * Draw a filled circle.
+   */
+  fillCircle(cx, cy, radius, opts = {}) {
+    const color = parseColor(opts.color ?? this._fill, opts.alpha ?? this._alpha);
+    for (let y = -radius; y <= radius; y++) {
+      const halfW = Math.round(Math.sqrt(radius * radius - y * y));
+      for (let x = -halfW; x <= halfW; x++) {
+        const px = this._tx(cx+x), py = this._ty(cy+y);
+        if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Draw an ellipse outline.
+   */
+  ellipse(cx, cy, rx, ry, opts = {}) {
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    const plot  = (x, y) => { const px = this._tx(x), py = this._ty(y); if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color }); };
+    const steps = Math.max(36, Math.round(2 * Math.PI * Math.max(rx, ry)));
+    for (let i = 0; i < steps; i++) {
+      const t = (2 * Math.PI * i) / steps;
+      plot(Math.round(cx + rx * Math.cos(t)), Math.round(cy + ry * Math.sin(t)));
+    }
+    return this;
+  }
+
+  /**
+   * Draw a filled ellipse.
+   */
+  fillEllipse(cx, cy, rx, ry, opts = {}) {
+    const color = parseColor(opts.color ?? this._fill, opts.alpha ?? this._alpha);
+    for (let y = -ry; y <= ry; y++) {
+      const halfW = Math.round(rx * Math.sqrt(1 - (y/ry)**2));
+      for (let x = -halfW; x <= halfW; x++) {
+        const px = this._tx(cx+x), py = this._ty(cy+y);
+        if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Draw a triangle outline.
+   */
+  triangle(x1, y1, x2, y2, x3, y3, opts = {}) {
+    this.line(x1, y1, x2, y2, opts);
+    this.line(x2, y2, x3, y3, opts);
+    this.line(x3, y3, x1, y1, opts);
+    return this;
+  }
+
+  /**
+   * Draw a filled triangle using scanline fill.
+   */
+  fillTriangle(x1, y1, x2, y2, x3, y3, opts = {}) {
+    const color = parseColor(opts.color ?? this._fill, opts.alpha ?? this._alpha);
+    // Sort vertices by y
+    let pts = [[x1,y1],[x2,y2],[x3,y3]].sort((a,b) => a[1]-b[1]);
+    const [[ax,ay],[bx,by],[cx,cy]] = pts;
+
+    const interpX = (y, p1, p2) => p1[1] === p2[1] ? p1[0] : p1[0] + (y - p1[1]) * (p2[0] - p1[0]) / (p2[1] - p1[1]);
+
+    for (let y = ay; y <= cy; y++) {
+      const xLeft  = y <= by ? interpX(y, [ax,ay], [bx,by]) : interpX(y, [bx,by], [cx,cy]);
+      const xRight = interpX(y, [ax,ay], [cx,cy]);
+      const xMin   = Math.round(Math.min(xLeft, xRight));
+      const xMax   = Math.round(Math.max(xLeft, xRight));
+      for (let x = xMin; x <= xMax; x++) {
+        const px = this._tx(x), py = this._ty(y);
+        if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Draw a polygon outline from an array of [x,y] points.
+   */
+  polygon(points, opts = {}) {
+    for (let i = 0; i < points.length; i++) {
+      const [x1,y1] = points[i];
+      const [x2,y2] = points[(i+1) % points.length];
+      this.line(x1, y1, x2, y2, opts);
+    }
+    return this;
+  }
+
+  /**
+   * Draw a filled polygon using scanline fill.
+   */
+  fillPolygon(points, opts = {}) {
+    const color  = parseColor(opts.color ?? this._fill, opts.alpha ?? this._alpha);
+    const ys     = points.map(p => p[1]);
+    const minY   = Math.min(...ys), maxY = Math.max(...ys);
+
+    for (let y = minY; y <= maxY; y++) {
+      const intersects = [];
+      for (let i = 0; i < points.length; i++) {
+        const [x1,y1] = points[i];
+        const [x2,y2] = points[(i+1) % points.length];
+        if ((y1 <= y && y2 > y) || (y2 <= y && y1 > y)) {
+          intersects.push(x1 + (y - y1) * (x2 - x1) / (y2 - y1));
+        }
+      }
+      intersects.sort((a,b) => a-b);
+      for (let i = 0; i < intersects.length - 1; i += 2) {
+        for (let x = Math.round(intersects[i]); x <= Math.round(intersects[i+1]); x++) {
+          const px = this._tx(x), py = this._ty(y);
+          if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+        }
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Draw a rounded rectangle.
+   */
+  roundedBox(x, y, w, h, r, opts = {}) {
+    r = Math.min(r, Math.floor(w/2), Math.floor(h/2));
+    this.line(x+r, y, x+w-r, y, opts);
+    this.line(x+r, y+h, x+w-r, y+h, opts);
+    this.line(x, y+r, x, y+h-r, opts);
+    this.line(x+w, y+r, x+w, y+h-r, opts);
+    this._arc(x+r,   y+r,   r, Math.PI,   1.5*Math.PI, opts);
+    this._arc(x+w-r, y+r,   r, 1.5*Math.PI, 2*Math.PI, opts);
+    this._arc(x+w-r, y+h-r, r, 0,         0.5*Math.PI, opts);
+    this._arc(x+r,   y+h-r, r, 0.5*Math.PI, Math.PI,   opts);
+    return this;
+  }
+
+  /**
+   * Draw an arc.
+   */
+  arc(cx, cy, radius, startAngle, endAngle, opts = {}) {
+    return this._arc(cx, cy, radius, startAngle, endAngle, opts);
+  }
+
+  _arc(cx, cy, radius, startAngle, endAngle, opts = {}) {
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    const steps = Math.max(16, Math.round(radius * Math.abs(endAngle - startAngle)));
+    for (let i = 0; i <= steps; i++) {
+      const t  = startAngle + (endAngle - startAngle) * i / steps;
+      const px = this._tx(Math.round(cx + radius * Math.cos(t)));
+      const py = this._ty(Math.round(cy + radius * Math.sin(t)));
+      if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+    }
+    return this;
+  }
+
+  /**
+   * Bezier curve — cubic.
+   */
+  bezier(x1, y1, cp1x, cp1y, cp2x, cp2y, x2, y2, opts = {}) {
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    const steps = 100;
+    for (let i = 0; i <= steps; i++) {
+      const t  = i / steps;
+      const mt = 1 - t;
+      const x  = Math.round(mt**3*x1 + 3*mt**2*t*cp1x + 3*mt*t**2*cp2x + t**3*x2);
+      const y  = Math.round(mt**3*y1 + 3*mt**2*t*cp1y + 3*mt*t**2*cp2y + t**3*y2);
+      const px = this._tx(x), py = this._ty(y);
+      if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+    }
+    return this;
+  }
+
+  /**
+   * Quadratic bezier curve.
+   */
+  quadBezier(x1, y1, cpx, cpy, x2, y2, opts = {}) {
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    const steps = 100;
+    for (let i = 0; i <= steps; i++) {
+      const t  = i / steps;
+      const mt = 1 - t;
+      const x  = Math.round(mt**2*x1 + 2*mt*t*cpx + t**2*x2);
+      const y  = Math.round(mt**2*y1 + 2*mt*t*cpy + t**2*y2);
+      const px = this._tx(x), py = this._ty(y);
+      if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+    }
+    return this;
+  }
+
+  // ── Text ───────────────────────────────────────────────────────────────────
+
+  /**
+   * Write text. Uses renderer.writeText() if available,
+   * otherwise falls back to a built-in 5×7 bitmap font.
+   */
+  text(x, y, str, opts = {}) {
+    if (this._r.writeText) {
+      const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+      this._r.writeText(this._tx(x), this._ty(y), str, { ...opts, color });
+      return this;
+    }
+    return this._bitmapText(x, y, str, opts);
+  }
+
+  _bitmapText(x, y, str, opts = {}) {
+    const color = parseColor(opts.color ?? this._color, opts.alpha ?? this._alpha);
+    const scale = opts.scale ?? 1;
+    let curX = x;
+    for (const ch of str) {
+      const glyph = FONT5X7[ch] ?? FONT5X7['?'];
+      for (let row = 0; row < 7; row++) {
+        const bits = glyph[row] ?? 0;
+        for (let col = 0; col < 5; col++) {
+          if (bits & (1 << (4 - col))) {
+            for (let sy = 0; sy < scale; sy++)
+              for (let sx = 0; sx < scale; sx++) {
+                const px = this._tx(curX + col * scale + sx);
+                const py = this._ty(y    + row  * scale + sy);
+                if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+              }
+          }
+        }
+      }
+      curX += (5 + 1) * scale;
+    }
+    return this;
+  }
+
+  // ── Effects ────────────────────────────────────────────────────────────────
+
+  /**
+   * Flood-fill from (x,y) with a color. Requires renderer.getPixel().
+   */
+  fill_(x, y, fillColor, opts = {}) {
+    if (!this._r.getPixel) throw new Error('kitcanvas: fill() requires renderer.getPixel(x, y)');
+    const color    = parseColor(fillColor ?? this._fill);
+    const target   = this._r.getPixel(this._tx(x), this._ty(y));
+    const tHex     = colorToHex(parseColor(target.color ?? target));
+    const fHex     = colorToHex(color);
+    if (tHex === fHex) return this;
+
+    const stack = [[Math.round(x), Math.round(y)]];
+    const seen  = new Set();
+
+    while (stack.length) {
+      const [cx, cy] = stack.pop();
+      const px = this._tx(cx), py = this._ty(cy);
+      if (!this._inBounds(px, py)) continue;
+      const key = `${px},${py}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      const cur = this._r.getPixel(px, py);
+      if (colorToHex(parseColor(cur.color ?? cur)) !== tHex) continue;
+      this._r.setPixel(px, py, { ...opts, color });
+      stack.push([cx+1,cy],[cx-1,cy],[cx,cy+1],[cx,cy-1]);
+    }
+    return this;
+  }
+
+  /**
+   * Draw a gradient-filled rectangle (linear, left→right or top→bottom).
+   */
+  gradient(x, y, w, h, colorFrom, colorTo, opts = {}) {
+    const dir = opts.direction ?? 'horizontal';
+    const c1  = parseColor(colorFrom), c2 = parseColor(colorTo);
+    for (let row = 0; row < h; row++) {
+      for (let col = 0; col < w; col++) {
+        const t     = dir === 'horizontal' ? col / (w - 1) : row / (h - 1);
+        const color = lerpColor(c1, c2, t);
+        const px    = this._tx(x+col), py = this._ty(y+row);
+        if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+      }
+    }
+    return this;
+  }
+
+  /**
+   * Draw a radial gradient in a circle.
+   */
+  radialGradient(cx, cy, radius, colorInner, colorOuter, opts = {}) {
+    const c1 = parseColor(colorInner), c2 = parseColor(colorOuter);
+    for (let y = -radius; y <= radius; y++) {
+      for (let x = -radius; x <= radius; x++) {
+        const dist = Math.sqrt(x*x + y*y);
+        if (dist > radius) continue;
+        const t     = dist / radius;
+        const color = lerpColor(c1, c2, t);
+        const px    = this._tx(cx+x), py = this._ty(cy+y);
+        if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+      }
+    }
+    return this;
+  }
+
+  // ── Image ops ──────────────────────────────────────────────────────────────
+
+  /**
+   * Copy a region from another Canvas onto this one.
+   * Requires source renderer.getPixel().
+   */
+  drawCanvas(srcCanvas, sx, sy, sw, sh, dx, dy, opts = {}) {
+    if (!srcCanvas._r.getPixel) throw new Error('kitcanvas: drawCanvas requires source renderer.getPixel()');
+    for (let y = 0; y < sh; y++) {
+      for (let x = 0; x < sw; x++) {
+        const pixel = srcCanvas._r.getPixel(sx+x, sy+y);
+        if (!pixel) continue;
+        const color = parseColor(pixel.color ?? pixel);
+        const px    = this._tx(dx+x), py = this._ty(dy+y);
+        if (this._inBounds(px, py)) this._r.setPixel(px, py, { ...opts, color });
+      }
+    }
+    return this;
+  }
+
+  // ── Renderer passthrough ───────────────────────────────────────────────────
+
+  /** Flush renderer (if supported). */
+  flush()       { if (this._r.flush)    this._r.flush();    return this; }
+  /** Save to file (if supported). */
+  save(path)    { if (this._r.save)     this._r.save(path); return this; }
+  /** Get raw buffer (if supported). */
+  toBuffer()    { return this._r.toBuffer   ? this._r.toBuffer()   : null; }
+  /** Get data URL (if supported). */
+  toDataURL()   { return this._r.toDataURL  ? this._r.toDataURL()  : null; }
+  /** Resize (if supported). */
+  resize(w, h)  { if (this._r.resize)   this._r.resize(w, h); return this; }
+  /** Access raw renderer. */
+  get renderer(){ return this._r; }
+}
+
+// ─── BUILT-IN RENDERERS ───────────────────────────────────────────────────────
+
+/**
+ * In-memory pixel buffer renderer.
+ * Stores pixels as { r, g, b, a } in a flat array.
+ * Useful for testing, server-side rendering, or custom export.
+ */
+class BufferRenderer {
+  constructor(width, height, background = 'white') {
+    this.width  = width;
+    this.height = height;
+    const bg    = parseColor(background);
+    this._buf   = new Array(width * height).fill(null).map(() => ({ ...bg }));
+  }
+
+  setPixel(x, y, opts) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return;
+    const color = parseColor(opts.color ?? opts);
+    this._buf[y * this.width + x] = { r: color.r, g: color.g, b: color.b, a: color.a };
+  }
+
+  getPixel(x, y) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return null;
+    return { color: { ...this._buf[y * this.width + x] } };
+  }
+
+  clear(color = { r:255, g:255, b:255, a:255 }) {
+    const c = parseColor(color);
+    this._buf.fill(null).forEach((_, i) => this._buf[i] = { ...c });
+  }
+
+  toBuffer() {
+    // Returns raw RGBA Buffer
+    const buf = Buffer.allocUnsafe(this.width * this.height * 4);
+    for (let i = 0; i < this._buf.length; i++) {
+      const { r, g, b, a } = this._buf[i];
+      buf[i*4+0] = r; buf[i*4+1] = g; buf[i*4+2] = b; buf[i*4+3] = a;
+    }
+    return buf;
+  }
+
+  toDataURL() {
+    // Returns a simple PPM-encoded data URL (works anywhere without deps)
+    const header = `P6\n${this.width} ${this.height}\n255\n`;
+    const pixels = Buffer.allocUnsafe(this.width * this.height * 3);
+    for (let i = 0; i < this._buf.length; i++) {
+      pixels[i*3+0] = this._buf[i].r;
+      pixels[i*3+1] = this._buf[i].g;
+      pixels[i*3+2] = this._buf[i].b;
+    }
+    return 'data:image/x-portable-pixmap;base64,' + Buffer.concat([Buffer.from(header), pixels]).toString('base64');
+  }
+
+  save(path) {
+    const fs  = require('fs');
+    const buf = this.toBuffer();
+    // Save as raw RGBA binary
+    fs.writeFileSync(path, buf);
+  }
+
+  toPPM() {
+    const lines = [`P3`, `${this.width} ${this.height}`, `255`];
+    for (let y = 0; y < this.height; y++) {
+      const row = [];
+      for (let x = 0; x < this.width; x++) {
+        const { r, g, b } = this._buf[y * this.width + x];
+        row.push(r, g, b);
+      }
+      lines.push(row.join(' '));
+    }
+    return lines.join('\n');
+  }
+
+  savePPM(path) {
+    require('fs').writeFileSync(path, this.toPPM());
+  }
+}
+
+/**
+ * ASCII/terminal renderer.
+ * Converts pixels to colored terminal output using ANSI 256-color or truecolor.
+ */
+class TerminalRenderer {
+  constructor(width, height) {
+    this.width  = width;
+    this.height = height;
+    this._buf   = new Array(width * height).fill({ r:0,g:0,b:0,a:0 });
+  }
+
+  setPixel(x, y, opts) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return;
+    this._buf[y * this.width + x] = parseColor(opts.color ?? opts);
+  }
+
+  getPixel(x, y) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return null;
+    return { color: { ...this._buf[y * this.width + x] } };
+  }
+
+  clear(color = { r:0,g:0,b:0,a:255 }) {
+    const c = parseColor(color);
+    this._buf = this._buf.map(() => ({ ...c }));
+  }
+
+  flush() { process.stdout.write(this.toString()); }
+
+  toString() {
+    const lines = [];
+    // Use half-block trick: each terminal row = 2 pixel rows
+    for (let y = 0; y < this.height; y += 2) {
+      let line = '';
+      for (let x = 0; x < this.width; x++) {
+        const top = this._buf[y * this.width + x] ?? { r:0,g:0,b:0 };
+        const bot = (y+1 < this.height) ? (this._buf[(y+1) * this.width + x] ?? { r:0,g:0,b:0 }) : { r:0,g:0,b:0 };
+        line += `\x1b[38;2;${top.r};${top.g};${top.b}m\x1b[48;2;${bot.r};${bot.g};${bot.b}m▀`;
+      }
+      lines.push(line + '\x1b[0m');
+    }
+    return lines.join('\n') + '\n';
+  }
+}
+
+/**
+ * SVG renderer — builds an SVG string from draw calls.
+ */
+class SVGRenderer {
+  constructor(width, height, background = 'white') {
+    this.width  = width;
+    this.height = height;
+    this._bg    = background;
+    this._elements = [];
+  }
+
+  setPixel(x, y, opts) {
+    const { r, g, b, a } = parseColor(opts.color ?? opts);
+    const fill = `rgba(${r},${g},${b},${(a/255).toFixed(3)})`;
+    this._elements.push(`<rect x="${x}" y="${y}" width="1" height="1" fill="${fill}"/>`);
+  }
+
+  writeText(x, y, text, opts = {}) {
+    const { r, g, b } = parseColor(opts.color ?? 'black');
+    const size  = opts.fontSize  ?? 12;
+    const font  = opts.fontFamily ?? 'monospace';
+    const fill  = `rgb(${r},${g},${b})`;
+    this._elements.push(`<text x="${x}" y="${y}" font-size="${size}" font-family="${font}" fill="${fill}">${text.replace(/&/g,'&amp;').replace(/</g,'&lt;')}</text>`);
+  }
+
+  clear(color) {
+    const c = parseColor(color ?? this._bg);
+    this._bg = `rgb(${c.r},${c.g},${c.b})`;
+    this._elements = [];
+  }
+
+  flush() { /* no-op for SVG */ }
+
+  toString() {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n` +
+      `<svg xmlns="http://www.w3.org/2000/svg" width="${this.width}" height="${this.height}">\n` +
+      `  <rect width="${this.width}" height="${this.height}" fill="${this._bg}"/>\n` +
+      `  ${this._elements.join('\n  ')}\n` +
+      `</svg>`;
+  }
+
+  save(path) { require('fs').writeFileSync(path, this.toString()); }
+  toDataURL() { return 'data:image/svg+xml;base64,' + Buffer.from(this.toString()).toString('base64'); }
+}
+
+// ─── 5×7 BITMAP FONT ─────────────────────────────────────────────────────────
+// Each glyph is 7 rows of 5 bits (MSB = leftmost pixel)
+
+const FONT5X7 = {
+  ' ': [0b00000,0b00000,0b00000,0b00000,0b00000,0b00000,0b00000],
+  '!': [0b00100,0b00100,0b00100,0b00100,0b00000,0b00000,0b00100],
+  '"': [0b01010,0b01010,0b00000,0b00000,0b00000,0b00000,0b00000],
+  '#': [0b01010,0b11111,0b01010,0b01010,0b11111,0b01010,0b00000],
+  '$': [0b00100,0b01111,0b10100,0b01110,0b00101,0b11110,0b00100],
+  '%': [0b11000,0b11001,0b00010,0b00100,0b01001,0b00011,0b00000],
+  '&': [0b01100,0b10010,0b10100,0b01000,0b10101,0b10010,0b01101],
+  "'": [0b00100,0b00100,0b00000,0b00000,0b00000,0b00000,0b00000],
+  '(': [0b00010,0b00100,0b01000,0b01000,0b01000,0b00100,0b00010],
+  ')': [0b01000,0b00100,0b00010,0b00010,0b00010,0b00100,0b01000],
+  '*': [0b00000,0b00100,0b10101,0b01110,0b10101,0b00100,0b00000],
+  '+': [0b00000,0b00100,0b00100,0b11111,0b00100,0b00100,0b00000],
+  ',': [0b00000,0b00000,0b00000,0b00000,0b00110,0b00100,0b01000],
+  '-': [0b00000,0b00000,0b00000,0b11111,0b00000,0b00000,0b00000],
+  '.': [0b00000,0b00000,0b00000,0b00000,0b00000,0b00110,0b00110],
+  '/': [0b00001,0b00010,0b00100,0b01000,0b10000,0b00000,0b00000],
+  '0': [0b01110,0b10001,0b10011,0b10101,0b11001,0b10001,0b01110],
+  '1': [0b00100,0b01100,0b00100,0b00100,0b00100,0b00100,0b01110],
+  '2': [0b01110,0b10001,0b00001,0b00110,0b01000,0b10000,0b11111],
+  '3': [0b11111,0b00010,0b00100,0b00010,0b00001,0b10001,0b01110],
+  '4': [0b00010,0b00110,0b01010,0b10010,0b11111,0b00010,0b00010],
+  '5': [0b11111,0b10000,0b11110,0b00001,0b00001,0b10001,0b01110],
+  '6': [0b00110,0b01000,0b10000,0b11110,0b10001,0b10001,0b01110],
+  '7': [0b11111,0b00001,0b00010,0b00100,0b01000,0b01000,0b01000],
+  '8': [0b01110,0b10001,0b10001,0b01110,0b10001,0b10001,0b01110],
+  '9': [0b01110,0b10001,0b10001,0b01111,0b00001,0b00010,0b01100],
+  ':': [0b00000,0b00110,0b00110,0b00000,0b00110,0b00110,0b00000],
+  ';': [0b00000,0b00110,0b00110,0b00000,0b00110,0b00100,0b01000],
+  '<': [0b00010,0b00100,0b01000,0b10000,0b01000,0b00100,0b00010],
+  '=': [0b00000,0b00000,0b11111,0b00000,0b11111,0b00000,0b00000],
+  '>': [0b01000,0b00100,0b00010,0b00001,0b00010,0b00100,0b01000],
+  '?': [0b01110,0b10001,0b00001,0b00110,0b00100,0b00000,0b00100],
+  '@': [0b01110,0b10001,0b10101,0b10111,0b10110,0b10000,0b01110],
+  'A': [0b01110,0b10001,0b10001,0b11111,0b10001,0b10001,0b10001],
+  'B': [0b11110,0b10001,0b10001,0b11110,0b10001,0b10001,0b11110],
+  'C': [0b01110,0b10001,0b10000,0b10000,0b10000,0b10001,0b01110],
+  'D': [0b11100,0b10010,0b10001,0b10001,0b10001,0b10010,0b11100],
+  'E': [0b11111,0b10000,0b10000,0b11110,0b10000,0b10000,0b11111],
+  'F': [0b11111,0b10000,0b10000,0b11110,0b10000,0b10000,0b10000],
+  'G': [0b01110,0b10001,0b10000,0b10111,0b10001,0b10001,0b01111],
+  'H': [0b10001,0b10001,0b10001,0b11111,0b10001,0b10001,0b10001],
+  'I': [0b01110,0b00100,0b00100,0b00100,0b00100,0b00100,0b01110],
+  'J': [0b00111,0b00010,0b00010,0b00010,0b10010,0b10010,0b01100],
+  'K': [0b10001,0b10010,0b10100,0b11000,0b10100,0b10010,0b10001],
+  'L': [0b10000,0b10000,0b10000,0b10000,0b10000,0b10000,0b11111],
+  'M': [0b10001,0b11011,0b10101,0b10001,0b10001,0b10001,0b10001],
+  'N': [0b10001,0b11001,0b10101,0b10011,0b10001,0b10001,0b10001],
+  'O': [0b01110,0b10001,0b10001,0b10001,0b10001,0b10001,0b01110],
+  'P': [0b11110,0b10001,0b10001,0b11110,0b10000,0b10000,0b10000],
+  'Q': [0b01110,0b10001,0b10001,0b10001,0b10101,0b10010,0b01101],
+  'R': [0b11110,0b10001,0b10001,0b11110,0b10100,0b10010,0b10001],
+  'S': [0b01111,0b10000,0b10000,0b01110,0b00001,0b00001,0b11110],
+  'T': [0b11111,0b00100,0b00100,0b00100,0b00100,0b00100,0b00100],
+  'U': [0b10001,0b10001,0b10001,0b10001,0b10001,0b10001,0b01110],
+  'V': [0b10001,0b10001,0b10001,0b10001,0b10001,0b01010,0b00100],
+  'W': [0b10001,0b10001,0b10001,0b10101,0b10101,0b11011,0b10001],
+  'X': [0b10001,0b10001,0b01010,0b00100,0b01010,0b10001,0b10001],
+  'Y': [0b10001,0b10001,0b01010,0b00100,0b00100,0b00100,0b00100],
+  'Z': [0b11111,0b00001,0b00010,0b00100,0b01000,0b10000,0b11111],
+  '[': [0b01110,0b01000,0b01000,0b01000,0b01000,0b01000,0b01110],
+  ']': [0b01110,0b00010,0b00010,0b00010,0b00010,0b00010,0b01110],
+  '^': [0b00100,0b01010,0b10001,0b00000,0b00000,0b00000,0b00000],
+  '_': [0b00000,0b00000,0b00000,0b00000,0b00000,0b00000,0b11111],
+  'a': [0b00000,0b00000,0b01110,0b00001,0b01111,0b10001,0b01111],
+  'b': [0b10000,0b10000,0b11110,0b10001,0b10001,0b10001,0b11110],
+  'c': [0b00000,0b00000,0b01110,0b10000,0b10000,0b10001,0b01110],
+  'd': [0b00001,0b00001,0b01111,0b10001,0b10001,0b10001,0b01111],
+  'e': [0b00000,0b00000,0b01110,0b10001,0b11111,0b10000,0b01110],
+  'f': [0b00110,0b01001,0b01000,0b11100,0b01000,0b01000,0b01000],
+  'g': [0b00000,0b01111,0b10001,0b10001,0b01111,0b00001,0b01110],
+  'h': [0b10000,0b10000,0b11110,0b10001,0b10001,0b10001,0b10001],
+  'i': [0b00100,0b00000,0b01100,0b00100,0b00100,0b00100,0b01110],
+  'j': [0b00010,0b00000,0b00110,0b00010,0b00010,0b10010,0b01100],
+  'k': [0b10000,0b10010,0b10100,0b11000,0b10100,0b10010,0b10001],
+  'l': [0b01100,0b00100,0b00100,0b00100,0b00100,0b00100,0b01110],
+  'm': [0b00000,0b00000,0b11010,0b10101,0b10101,0b10001,0b10001],
+  'n': [0b00000,0b00000,0b11110,0b10001,0b10001,0b10001,0b10001],
+  'o': [0b00000,0b00000,0b01110,0b10001,0b10001,0b10001,0b01110],
+  'p': [0b00000,0b11110,0b10001,0b10001,0b11110,0b10000,0b10000],
+  'q': [0b00000,0b01111,0b10001,0b10001,0b01111,0b00001,0b00001],
+  'r': [0b00000,0b00000,0b10110,0b11001,0b10000,0b10000,0b10000],
+  's': [0b00000,0b00000,0b01110,0b10000,0b01110,0b00001,0b11110],
+  't': [0b01000,0b01000,0b11110,0b01000,0b01000,0b01001,0b00110],
+  'u': [0b00000,0b00000,0b10001,0b10001,0b10001,0b10011,0b01101],
+  'v': [0b00000,0b00000,0b10001,0b10001,0b10001,0b01010,0b00100],
+  'w': [0b00000,0b00000,0b10001,0b10001,0b10101,0b10101,0b01010],
+  'x': [0b00000,0b00000,0b10001,0b01010,0b00100,0b01010,0b10001],
+  'y': [0b00000,0b00000,0b10001,0b10001,0b01111,0b00001,0b01110],
+  'z': [0b00000,0b00000,0b11111,0b00010,0b00100,0b01000,0b11111],
+};
+
+// ─── EXPORTS ─────────────────────────────────────────────────────────────────
+
+module.exports = {
+  kitdef: {
+    Canvas,
+    // Built-in renderers
+    BufferRenderer,
+    TerminalRenderer,
+    SVGRenderer,
+    // Color utilities
+    parseColor,
+    colorToHex,
+    lerpColor,
+    NAMED_COLORS,
+  }
+};