@slithy/prim-lib 0.1.0

package/LICENSE

@@ -0,0 +1,91 @@
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+Required Notice: Copyright Matthew Campagna
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+---
+
+## Third-party attributions
+
+This software is derived from the following MIT-licensed works:
+
+**primitive** by Michael Fogleman
+https://github.com/fogleman/primitive
+Copyright (c) 2016 Michael Fogleman — MIT License
+
+**primitive.js** by Ondřej Žára
+https://github.com/ondras/primitive.js
+Copyright (c) Ondřej Žára — MIT License
+
+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 notices 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,68 @@
+# @slithy/prim-lib
+
+Core engine for primitive-based image reconstruction. Consumed by `@slithy/prim-interface`.
+
+## What it does
+
+Reconstructs an image by iteratively placing geometric shapes. Each step evaluates candidate shapes, mutates them, picks the one that most reduces the difference from the target, and draws it onto the working canvas.
+
+## Exports
+
+### Classes
+
+- **`Canvas`** — wraps `HTMLCanvasElement`; handles image loading, pixel reads, drawing steps, and SVG output
+- **`Optimizer`** — runs the rAF loop; calls `onStep` after each shape is placed
+- **`State`** — holds the current canvas and its distance from the target
+- **`Step`** — a single candidate shape placement; computes best color and difference change
+
+### Shapes
+
+- **`Shape`** — abstract base
+- **`Triangle`**, **`Rectangle`**, **`Ellipse`**, **`Hexagon`**, **`Smiley`**, **`Debug`**
+
+### Types
+
+**`Cfg`** — runtime config (all fields required):
+
+```ts
+interface Cfg {
+  width: number        // image width for computation (set by Canvas.original)
+  height: number       // image height for computation (set by Canvas.original)
+  steps: number        // total shapes to place
+  shapes: number       // candidate shapes evaluated per step
+  mutations: number    // hill-climb attempts per candidate
+  alpha: number        // starting shape opacity
+  mutateAlpha: boolean // whether opacity is mutated per candidate
+  computeSize: number  // max image dimension for pixel distance calculations
+  viewSize: number     // max image dimension for display canvas
+  scale?: number       // viewSize / computeSize ratio (set by Canvas.original)
+  shapeTypes: Array<new (w: number, h: number) => ShapeInterface>
+  fill: 'auto' | string
+}
+```
+
+- **`PreCfg`** — `Cfg` with optional `width`/`height`; used before image dimensions are known
+- **`ShapeInterface`** — structural interface for shapes
+- **`Bbox`**, **`Point`**, **`ImageDataLike`**, **`ShapeImageData`**
+
+### Utilities
+
+- **`stepPerf`** — accumulator for profiling rasterize vs pixel math time per step
+
+## Differences from primitive.js
+
+`prim-lib` is derived from [primitive.js](https://github.com/ondras/primitive.js), a JavaScript port of the Go [primitive](https://github.com/fogleman/primitive) library by Michael Fogleman. The core algorithm — iterative shape placement via hill-climbing — is unchanged. What's different:
+
+- **TypeScript, strict mode** — fully typed throughout; `strict: true` on both packages
+- **ESM only** — no CommonJS; no `importScripts()`
+- **Canvas reuse** — the original creates a new `<canvas>` element for every shape rasterization call (~58,000 per run at default settings). `prim-lib` reuses a single module-level canvas, growing it only when a larger bbox is seen. This delivered a ~27× speedup (37 s → ~0.8 s rasterize time per run)
+- **`willReadFrequently: true`** — canvas contexts used for `getImageData` are created with this flag, keeping pixel data in CPU memory and suppressing browser warnings
+- **Workers removed** — the original included worker stubs (`importScripts()`-based, not ESM-compatible). Workers were investigated and benchmarked; after the canvas reuse optimization, a batched worker implementation matched single-threaded performance. Workers are not used
+- **Architecture split** — the original is a single-layer library. Here, `prim-lib` is the pure algorithm (no knowledge of how images arrive or where results go), and `prim-interface` is the adapter that wires it to the browser
+- **`PreCfg` / `Cfg` distinction** — `Canvas.original()` accepts `PreCfg` (optional `width`/`height`) and resolves to a fully-populated `Cfg`, making the config lifecycle explicit in the types
+
+## Architecture notes
+
+- `Shape.rasterize()` reuses a single module-level canvas (`_rasterCanvas`) grown to the max shape size seen; avoids per-call `createElement('canvas')` which was the dominant cost (27x speedup)
+- `Cfg.shapeTypes` holds shape constructors; shapes are chosen randomly each step
+- `PreCfg` exists to bridge the gap between call time (dimensions unknown) and runtime (dimensions set by `Canvas.original()`)

package/dist/index.d.ts

@@ -0,0 +1,206 @@
+type Point = [number, number];
+interface Bbox {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** Structural subset of ImageData used by pixel-walking functions. Avoids requiring
+ *  the `colorSpace` field that DOM ImageData has but hand-crafted test objects lack. */
+interface ImageDataLike {
+    data: Uint8ClampedArray;
+    width: number;
+    height: number;
+}
+interface ShapeImageData {
+    shape: ImageDataLike;
+    current: ImageDataLike;
+    target: ImageDataLike;
+}
+/**
+ * Structural interface for shapes. Defined here (rather than in shape.ts)
+ * so Cfg.shapeTypes can reference it without creating a circular import.
+ */
+interface ShapeInterface {
+    bbox: Bbox;
+    /** cfg is rarely used by implementations; accepts Partial to keep call sites flexible. */
+    mutate(cfg?: Partial<Cfg>): ShapeInterface;
+    toSVG(): SVGElement | undefined;
+    rasterize(alpha: number): {
+        getImageData(): ImageDataLike;
+    };
+    render(ctx: CanvasRenderingContext2D): void;
+}
+interface Cfg {
+    width: number;
+    height: number;
+    alpha: number;
+    mutateAlpha: boolean;
+    shapeTypes: Array<new (w: number, h: number) => ShapeInterface>;
+    shapes: number;
+    mutations: number;
+    steps: number;
+    fill: 'auto' | string;
+    computeSize: number;
+    viewSize: number;
+    scale?: number;
+}
+/**
+ * Config as provided by the caller before Canvas.original() runs.
+ * width/height/scale are absent until Canvas.original sets them.
+ */
+type PreCfg = Omit<Cfg, 'width' | 'height'> & {
+    width?: number;
+    height?: number;
+};
+
+interface DrawableStep {
+    alpha: number;
+    color: string;
+    shape: {
+        render(ctx: CanvasRenderingContext2D): void;
+    };
+}
+declare class Canvas {
+    node: HTMLCanvasElement;
+    ctx: CanvasRenderingContext2D;
+    _imageData: ImageData | null;
+    static empty(cfg: Cfg, svg: true): SVGSVGElement;
+    static empty(cfg: Cfg, svg?: false): Canvas;
+    static original(url: string, cfg: PreCfg): Promise<Canvas>;
+    static test(cfg: PreCfg): Canvas;
+    constructor(width: number, height: number, willReadFrequently?: boolean);
+    clone(): Canvas;
+    fill(color: string): this;
+    getImageData(): ImageDataLike;
+    difference(otherCanvas: Canvas): number;
+    distance(otherCanvas: Canvas): number;
+    drawStep(step: DrawableStep): this;
+}
+
+declare class State {
+    target: Canvas;
+    canvas: Canvas;
+    distance: number;
+    constructor(target: Canvas, canvas: Canvas, distance?: number);
+}
+
+declare const stepPerf: {
+    rasterizeMs: number;
+    pixelMs: number;
+    calls: number;
+    reset(): void;
+};
+declare class Step {
+    shape: ShapeInterface;
+    cfg: Cfg;
+    alpha: number;
+    color: string;
+    distance: number;
+    constructor(shape: ShapeInterface, cfg: Cfg);
+    toSVG(): SVGElement;
+    apply(state: State): State;
+    compute(state: State): Promise<Step>;
+    mutate(): Step;
+}
+
+declare class Optimizer {
+    cfg: Cfg;
+    state: State;
+    onStep: (step: Step | null) => void;
+    _steps: number;
+    _stopped: boolean;
+    _paused: boolean;
+    constructor(original: Canvas, cfg: Cfg);
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    _addShape(): void;
+    _continue(): void;
+    _findBestStep(): Promise<Step | null>;
+    _optimizeStep(step: Step): Promise<Step>;
+}
+
+declare class Shape implements ShapeInterface {
+    bbox: Bbox;
+    static randomPoint(width: number, height: number): Point;
+    static create(cfg: Cfg): ShapeInterface;
+    constructor(_w: number, _h: number);
+    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    toSVG(): SVGElement | undefined;
+    rasterize(alpha: number): {
+        getImageData(): ImageDataLike;
+    };
+    render(_ctx: CanvasRenderingContext2D): void;
+}
+declare class Polygon extends Shape {
+    points: Point[];
+    constructor(w: number, h: number, count?: number);
+    protected _cloneEmpty(): Polygon;
+    render(ctx: CanvasRenderingContext2D): void;
+    toSVG(): SVGElement;
+    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    computeBbox(): this;
+    _createPoints(w: number, h: number, count: number): Point[];
+}
+declare class Triangle extends Polygon {
+    constructor(w: number, h: number);
+    protected _cloneEmpty(): Triangle;
+}
+declare class Rectangle extends Polygon {
+    constructor(w: number, h: number);
+    protected _cloneEmpty(): Rectangle;
+    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    _createPoints(w: number, h: number, _count: number): Point[];
+}
+declare class Ellipse extends Shape {
+    center: Point;
+    rx: number;
+    ry: number;
+    constructor(w: number, h: number);
+    render(ctx: CanvasRenderingContext2D): void;
+    toSVG(): SVGElement;
+    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    computeBbox(): this;
+}
+declare class Smiley extends Shape {
+    center: Point;
+    text: string;
+    fontSize: number;
+    constructor(w: number, h: number, text?: string);
+    computeBbox(): this;
+    render(ctx: CanvasRenderingContext2D): void;
+    mutate(_cfg?: Partial<Cfg>): Smiley;
+    toSVG(): SVGElement;
+}
+declare class Hexagon extends Shape {
+    center: Point;
+    r: number;
+    angle: number;
+    _cachedPoints: Point[] | null;
+    constructor(w: number, h: number);
+    _points(): Point[];
+    computeBbox(): this;
+    render(ctx: CanvasRenderingContext2D): void;
+    toSVG(): SVGElement;
+    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+}
+declare class Debug extends Shape {
+    constructor(w: number, h: number);
+    render(ctx: CanvasRenderingContext2D): void;
+}
+
+declare const SVGNS = "http://www.w3.org/2000/svg";
+
+declare function clamp(x: number, min: number, max: number): number;
+declare function clampColor(x: number): number;
+declare function distanceToDifference(distance: number, pixels: number): number;
+declare function differenceToDistance(difference: number, pixels: number): number;
+declare function difference(data: ImageDataLike, dataOther: ImageDataLike): number;
+declare function computeColorAndDifferenceChange(offset: Bbox, imageData: ShapeImageData, alpha: number): {
+    color: string;
+    differenceChange: number;
+};
+
+export { type Bbox, Canvas, type Cfg, Debug, Ellipse, Hexagon, type ImageDataLike, Optimizer, type Point, type PreCfg, Rectangle, SVGNS, Shape, type ShapeImageData, type ShapeInterface, Smiley, State, Step, Triangle, clamp, clampColor, computeColorAndDifferenceChange, difference, differenceToDistance, distanceToDifference, stepPerf };

package/dist/index.js

@@ -0,0 +1,823 @@
+// src/util.ts
+var SVGNS = "http://www.w3.org/2000/svg";
+function clamp(x, min, max) {
+  return Math.max(min, Math.min(max, x));
+}
+function clampColor(x) {
+  return clamp(x, 0, 255);
+}
+function distanceToDifference(distance, pixels) {
+  return Math.pow(distance * 255, 2) * (3 * pixels);
+}
+function differenceToDistance(difference2, pixels) {
+  return Math.sqrt(difference2 / (3 * pixels)) / 255;
+}
+function difference(data, dataOther) {
+  let sum = 0, dr = 0, dg = 0, db = 0;
+  for (let i = 0; i < data.data.length; i += 4) {
+    dr = dataOther.data[i] - data.data[i];
+    dg = dataOther.data[i + 1] - data.data[i + 1];
+    db = dataOther.data[i + 2] - data.data[i + 2];
+    sum += dr * dr + dg * dg + db * db;
+  }
+  return sum;
+}
+function computeColorAndDifferenceChange(offset, imageData, alpha) {
+  const { shape, current, target } = imageData;
+  const shapeData = shape.data;
+  const currentData = current.data;
+  const targetData = target.data;
+  let si = 0, sx = 0, sy = 0, fi = 0, fx = 0, fy = 0;
+  const sw = shape.width;
+  const sh = shape.height;
+  const fw = current.width;
+  const fh = current.height;
+  let r = 0, g = 0, b = 0, count = 0;
+  for (sy = 0; sy < sh; sy++) {
+    fy = sy + offset.top;
+    if (fy < 0 || fy >= fh) {
+      continue;
+    }
+    for (sx = 0; sx < sw; sx++) {
+      fx = offset.left + sx;
+      if (fx < 0 || fx >= fw) {
+        continue;
+      }
+      si = 4 * (sx + sy * sw);
+      if (shapeData[si + 3] == 0) {
+        continue;
+      }
+      fi = 4 * (fx + fy * fw);
+      r += (targetData[fi] - currentData[fi]) / alpha + currentData[fi];
+      g += (targetData[fi + 1] - currentData[fi + 1]) / alpha + currentData[fi + 1];
+      b += (targetData[fi + 2] - currentData[fi + 2]) / alpha + currentData[fi + 2];
+      count++;
+    }
+  }
+  const cr = clampColor(~~(r / count));
+  const cg = clampColor(~~(g / count));
+  const cb = clampColor(~~(b / count));
+  let sum = 0;
+  let a = 0, blend = 0, d1r = 0, d1g = 0, d1b = 0, d2r = 0, d2g = 0, d2b = 0;
+  for (sy = 0; sy < sh; sy++) {
+    fy = sy + offset.top;
+    if (fy < 0 || fy >= fh) {
+      continue;
+    }
+    for (sx = 0; sx < sw; sx++) {
+      fx = offset.left + sx;
+      if (fx < 0 || fx >= fw) {
+        continue;
+      }
+      si = 4 * (sx + sy * sw);
+      a = shapeData[si + 3];
+      if (a == 0) {
+        continue;
+      }
+      fi = 4 * (fx + fy * fw);
+      a = a / 255;
+      blend = 1 - a;
+      d1r = targetData[fi] - currentData[fi];
+      d1g = targetData[fi + 1] - currentData[fi + 1];
+      d1b = targetData[fi + 2] - currentData[fi + 2];
+      d2r = targetData[fi] - (cr * a + currentData[fi] * blend);
+      d2g = targetData[fi + 1] - (cg * a + currentData[fi + 1] * blend);
+      d2b = targetData[fi + 2] - (cb * a + currentData[fi + 2] * blend);
+      sum -= d1r * d1r + d1g * d1g + d1b * d1b;
+      sum += d2r * d2r + d2g * d2g + d2b * d2b;
+    }
+  }
+  return { color: `rgb(${cr}, ${cg}, ${cb})`, differenceChange: sum };
+}
+
+// src/canvas.ts
+function getScale(width, height, limit) {
+  return Math.max(width / limit, height / limit, 1);
+}
+function getFill(canvas) {
+  const data = canvas.getImageData();
+  const w = data.width;
+  const h = data.height;
+  const d = data.data;
+  let rgb = [0, 0, 0];
+  let count = 0;
+  let i = 0;
+  for (let x = 0; x < w; x++) {
+    for (let y = 0; y < h; y++) {
+      if (x > 0 && y > 0 && x < w - 1 && y < h - 1) {
+        continue;
+      }
+      count++;
+      i = 4 * (x + y * w);
+      rgb[0] += d[i];
+      rgb[1] += d[i + 1];
+      rgb[2] += d[i + 2];
+    }
+  }
+  rgb = rgb.map((x) => ~~(x / count)).map(clampColor);
+  return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`;
+}
+function svgRect(w, h) {
+  const node = document.createElementNS(SVGNS, "rect");
+  node.setAttribute("x", "0");
+  node.setAttribute("y", "0");
+  node.setAttribute("width", String(w));
+  node.setAttribute("height", String(h));
+  return node;
+}
+var Canvas = class _Canvas {
+  node;
+  ctx;
+  _imageData;
+  static empty(cfg, svg) {
+    if (svg) {
+      const node = document.createElementNS(SVGNS, "svg");
+      node.setAttribute("viewBox", `0 0 ${cfg.width} ${cfg.height}`);
+      node.setAttribute("clip-path", "url(#clip)");
+      const defs = document.createElementNS(SVGNS, "defs");
+      node.appendChild(defs);
+      const cp = document.createElementNS(SVGNS, "clipPath");
+      defs.appendChild(cp);
+      cp.setAttribute("id", "clip");
+      cp.setAttribute("clipPathUnits", "objectBoundingBox");
+      let rect = svgRect(cfg.width, cfg.height);
+      cp.appendChild(rect);
+      rect = svgRect(cfg.width, cfg.height);
+      rect.setAttribute("fill", cfg.fill);
+      node.appendChild(rect);
+      return node;
+    } else {
+      return new this(cfg.width, cfg.height).fill(cfg.fill);
+    }
+  }
+  static original(url, cfg) {
+    if (url == "test") {
+      return Promise.resolve(this.test(cfg));
+    }
+    return new Promise((resolve) => {
+      const img = new Image();
+      img.crossOrigin = "anonymous";
+      img.src = url;
+      img.onload = () => {
+        const w = img.naturalWidth;
+        const h = img.naturalHeight;
+        const computeScale = getScale(w, h, cfg.computeSize);
+        cfg.width = w / computeScale;
+        cfg.height = h / computeScale;
+        const viewScale = getScale(w, h, cfg.viewSize);
+        cfg.scale = computeScale / viewScale;
+        const fullCfg = { ...cfg, width: cfg.width, height: cfg.height };
+        const canvas = this.empty(fullCfg);
+        canvas.ctx.drawImage(img, 0, 0, fullCfg.width, fullCfg.height);
+        if (cfg.fill == "auto") {
+          cfg.fill = getFill(canvas);
+        }
+        resolve(canvas);
+      };
+      img.onerror = (e) => {
+        console.error(e);
+        alert("The image URL cannot be loaded. Does the server support CORS?");
+      };
+    });
+  }
+  static test(cfg) {
+    cfg.width = cfg.computeSize;
+    cfg.height = cfg.computeSize;
+    cfg.scale = 1;
+    const [w, h] = [cfg.computeSize, cfg.computeSize];
+    const canvas = new this(w, h);
+    canvas.fill("#fff");
+    const ctx = canvas.ctx;
+    ctx.fillStyle = "#f00";
+    ctx.beginPath();
+    ctx.arc(w / 4, h / 2, w / 7, 0, 2 * Math.PI, true);
+    ctx.fill();
+    ctx.fillStyle = "#0f0";
+    ctx.beginPath();
+    ctx.arc(w / 2, h / 2, w / 7, 0, 2 * Math.PI, true);
+    ctx.fill();
+    ctx.fillStyle = "#00f";
+    ctx.beginPath();
+    ctx.arc(w * 3 / 4, h / 2, w / 7, 0, 2 * Math.PI, true);
+    ctx.fill();
+    if (cfg.fill == "auto") {
+      cfg.fill = getFill(canvas);
+    }
+    return canvas;
+  }
+  constructor(width, height, willReadFrequently = false) {
+    this.node = document.createElement("canvas");
+    this.node.width = width;
+    this.node.height = height;
+    this.ctx = this.node.getContext("2d", { willReadFrequently });
+    this._imageData = null;
+  }
+  clone() {
+    const other = new _Canvas(this.node.width, this.node.height);
+    other.ctx.drawImage(this.node, 0, 0);
+    return other;
+  }
+  fill(color) {
+    this.ctx.fillStyle = color;
+    this.ctx.fillRect(0, 0, this.node.width, this.node.height);
+    return this;
+  }
+  getImageData() {
+    if (!this._imageData) {
+      this._imageData = this.ctx.getImageData(0, 0, this.node.width, this.node.height);
+    }
+    return this._imageData;
+  }
+  difference(otherCanvas) {
+    const data = this.getImageData();
+    const dataOther = otherCanvas.getImageData();
+    return difference(data, dataOther);
+  }
+  distance(otherCanvas) {
+    const difference2 = this.difference(otherCanvas);
+    return differenceToDistance(difference2, this.node.width * this.node.height);
+  }
+  drawStep(step) {
+    this.ctx.globalAlpha = step.alpha;
+    this.ctx.fillStyle = step.color;
+    step.shape.render(this.ctx);
+    return this;
+  }
+};
+
+// src/state.ts
+var State = class {
+  target;
+  canvas;
+  distance;
+  constructor(target, canvas, distance = Infinity) {
+    this.target = target;
+    this.canvas = canvas;
+    this.distance = distance == Infinity ? target.distance(canvas) : distance;
+  }
+};
+
+// src/step.ts
+var stepPerf = {
+  rasterizeMs: 0,
+  pixelMs: 0,
+  calls: 0,
+  reset() {
+    this.rasterizeMs = 0;
+    this.pixelMs = 0;
+    this.calls = 0;
+  }
+};
+var Step = class _Step {
+  shape;
+  cfg;
+  alpha;
+  color;
+  distance;
+  constructor(shape, cfg) {
+    this.shape = shape;
+    this.cfg = cfg;
+    this.alpha = cfg.alpha;
+    this.color = "#000";
+    this.distance = Infinity;
+  }
+  toSVG() {
+    const node = this.shape.toSVG();
+    if (!node) throw new Error("Shape does not support SVG export");
+    node.setAttribute("fill", this.color);
+    node.setAttribute("fill-opacity", this.alpha.toFixed(2));
+    return node;
+  }
+  /* apply this step to a state to get a new state. call only after .compute */
+  apply(state) {
+    const newCanvas = state.canvas.clone().drawStep(this);
+    return new State(state.target, newCanvas, this.distance);
+  }
+  /* find optimal color and compute the resulting distance */
+  compute(state) {
+    const pixels = state.canvas.node.width * state.canvas.node.height;
+    const offset = this.shape.bbox;
+    const t0 = performance.now();
+    const shapeImageData = this.shape.rasterize(this.alpha).getImageData();
+    const t1 = performance.now();
+    const imageData = {
+      shape: shapeImageData,
+      current: state.canvas.getImageData(),
+      target: state.target.getImageData()
+    };
+    const { color, differenceChange } = computeColorAndDifferenceChange(offset, imageData, this.alpha);
+    const t2 = performance.now();
+    stepPerf.rasterizeMs += t1 - t0;
+    stepPerf.pixelMs += t2 - t1;
+    stepPerf.calls++;
+    this.color = color;
+    const currentDifference = distanceToDifference(state.distance, pixels);
+    this.distance = differenceToDistance(currentDifference + differenceChange, pixels);
+    return Promise.resolve(this);
+  }
+  /* return a slightly mutated step */
+  mutate() {
+    const newShape = this.shape.mutate(this.cfg);
+    const mutated = new _Step(newShape, this.cfg);
+    if (this.cfg.mutateAlpha) {
+      const mutatedAlpha = this.alpha + (Math.random() - 0.5) * 0.08;
+      mutated.alpha = clamp(mutatedAlpha, 0.1, 1);
+    }
+    return mutated;
+  }
+};
+
+// src/shape.ts
+var _rasterCanvas = null;
+var Shape = class {
+  bbox;
+  static randomPoint(width, height) {
+    return [~~(Math.random() * width), ~~(Math.random() * height)];
+  }
+  static create(cfg) {
+    const ctors = cfg.shapeTypes;
+    const index = Math.floor(Math.random() * ctors.length);
+    const ctor = ctors[index];
+    return new ctor(cfg.width, cfg.height);
+  }
+  constructor(_w, _h) {
+    this.bbox = { left: 0, top: 0, width: 0, height: 0 };
+  }
+  mutate(_cfg) {
+    return this;
+  }
+  toSVG() {
+    return void 0;
+  }
+  /* get a new smaller canvas with this shape */
+  rasterize(alpha) {
+    const w = this.bbox.width;
+    const h = this.bbox.height;
+    if (!_rasterCanvas || _rasterCanvas.node.width < w || _rasterCanvas.node.height < h) {
+      _rasterCanvas = new Canvas(
+        Math.max(w, _rasterCanvas?.node.width ?? 0),
+        Math.max(h, _rasterCanvas?.node.height ?? 0),
+        true
+      );
+    }
+    const ctx = _rasterCanvas.ctx;
+    ctx.setTransform(1, 0, 0, 1, 0, 0);
+    ctx.clearRect(0, 0, w, h);
+    ctx.fillStyle = "#000";
+    ctx.globalAlpha = alpha;
+    ctx.translate(-this.bbox.left, -this.bbox.top);
+    this.render(ctx);
+    const data = ctx.getImageData(0, 0, w, h);
+    return { getImageData: () => data };
+  }
+  render(_ctx) {
+  }
+};
+var Polygon = class _Polygon extends Shape {
+  points;
+  constructor(w, h, count) {
+    super(w, h);
+    this.points = this._createPoints(w, h, count ?? 3);
+    this.computeBbox();
+  }
+  _cloneEmpty() {
+    return new _Polygon(0, 0);
+  }
+  render(ctx) {
+    ctx.beginPath();
+    this.points.forEach(([x, y], index) => {
+      if (index) {
+        ctx.lineTo(x, y);
+      } else {
+        ctx.moveTo(x, y);
+      }
+    });
+    ctx.closePath();
+    ctx.fill();
+  }
+  toSVG() {
+    const path = document.createElementNS(SVGNS, "path");
+    const d = this.points.map((point, index) => {
+      const cmd = index ? "L" : "M";
+      return `${cmd}${point.join(",")}`;
+    }).join("");
+    path.setAttribute("d", `${d}Z`);
+    return path;
+  }
+  mutate(_cfg) {
+    const clone = this._cloneEmpty();
+    clone.points = this.points.map(([x, y]) => [x, y]);
+    const index = Math.floor(Math.random() * this.points.length);
+    const point = clone.points[index];
+    const angle = Math.random() * 2 * Math.PI;
+    const radius = Math.random() * 20;
+    point[0] += ~~(radius * Math.cos(angle));
+    point[1] += ~~(radius * Math.sin(angle));
+    return clone.computeBbox();
+  }
+  computeBbox() {
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const [x, y] of this.points) {
+      if (x < minX) minX = x;
+      if (y < minY) minY = y;
+      if (x > maxX) maxX = x;
+      if (y > maxY) maxY = y;
+    }
+    this.bbox = {
+      left: minX,
+      top: minY,
+      width: maxX - minX || 1,
+      /* fallback for deformed shapes */
+      height: maxY - minY || 1
+    };
+    return this;
+  }
+  _createPoints(w, h, count) {
+    const first = Shape.randomPoint(w, h);
+    const points = [first];
+    for (let i = 1; i < count; i++) {
+      const angle = Math.random() * 2 * Math.PI;
+      const radius = Math.random() * 20;
+      points.push([
+        first[0] + ~~(radius * Math.cos(angle)),
+        first[1] + ~~(radius * Math.sin(angle))
+      ]);
+    }
+    return points;
+  }
+};
+var Triangle = class _Triangle extends Polygon {
+  constructor(w, h) {
+    super(w, h, 3);
+  }
+  _cloneEmpty() {
+    return new _Triangle(0, 0);
+  }
+};
+var Rectangle = class _Rectangle extends Polygon {
+  constructor(w, h) {
+    super(w, h, 4);
+  }
+  _cloneEmpty() {
+    return new _Rectangle(0, 0);
+  }
+  mutate(_cfg) {
+    const clone = this._cloneEmpty();
+    clone.points = this.points.map(([x, y]) => [x, y]);
+    const amount = ~~((Math.random() - 0.5) * 20);
+    switch (Math.floor(Math.random() * 4)) {
+      case 0:
+        clone.points[0][0] += amount;
+        clone.points[3][0] += amount;
+        break;
+      case 1:
+        clone.points[0][1] += amount;
+        clone.points[1][1] += amount;
+        break;
+      case 2:
+        clone.points[1][0] += amount;
+        clone.points[2][0] += amount;
+        break;
+      case 3:
+        clone.points[2][1] += amount;
+        clone.points[3][1] += amount;
+        break;
+    }
+    return clone.computeBbox();
+  }
+  _createPoints(w, h, _count) {
+    const p1 = Shape.randomPoint(w, h);
+    const p2 = Shape.randomPoint(w, h);
+    const left = Math.min(p1[0], p2[0]);
+    const right = Math.max(p1[0], p2[0]);
+    const top = Math.min(p1[1], p2[1]);
+    const bottom = Math.max(p1[1], p2[1]);
+    return [
+      [left, top],
+      [right, top],
+      [right, bottom],
+      [left, bottom]
+    ];
+  }
+};
+var Ellipse = class _Ellipse extends Shape {
+  center;
+  rx;
+  ry;
+  constructor(w, h) {
+    super(w, h);
+    this.center = Shape.randomPoint(w, h);
+    this.rx = 1 + ~~(Math.random() * 20);
+    this.ry = 1 + ~~(Math.random() * 20);
+    this.computeBbox();
+  }
+  render(ctx) {
+    ctx.beginPath();
+    ctx.ellipse(this.center[0], this.center[1], this.rx, this.ry, 0, 0, 2 * Math.PI, false);
+    ctx.fill();
+  }
+  toSVG() {
+    const node = document.createElementNS(SVGNS, "ellipse");
+    node.setAttribute("cx", String(this.center[0]));
+    node.setAttribute("cy", String(this.center[1]));
+    node.setAttribute("rx", String(this.rx));
+    node.setAttribute("ry", String(this.ry));
+    return node;
+  }
+  mutate(_cfg) {
+    const clone = new _Ellipse(0, 0);
+    clone.center = [this.center[0], this.center[1]];
+    clone.rx = this.rx;
+    clone.ry = this.ry;
+    switch (Math.floor(Math.random() * 3)) {
+      case 0: {
+        const angle = Math.random() * 2 * Math.PI;
+        const radius = Math.random() * 20;
+        clone.center[0] += ~~(radius * Math.cos(angle));
+        clone.center[1] += ~~(radius * Math.sin(angle));
+        break;
+      }
+      case 1:
+        clone.rx += (Math.random() - 0.5) * 20;
+        clone.rx = Math.max(1, ~~clone.rx);
+        break;
+      case 2:
+        clone.ry += (Math.random() - 0.5) * 20;
+        clone.ry = Math.max(1, ~~clone.ry);
+        break;
+    }
+    return clone.computeBbox();
+  }
+  computeBbox() {
+    this.bbox = {
+      left: this.center[0] - this.rx,
+      top: this.center[1] - this.ry,
+      width: 2 * this.rx,
+      height: 2 * this.ry
+    };
+    return this;
+  }
+};
+var Smiley = class _Smiley extends Shape {
+  center;
+  text;
+  fontSize;
+  constructor(w, h, text = "\u263A") {
+    super(w, h);
+    this.center = Shape.randomPoint(w, h);
+    this.text = text;
+    this.fontSize = 16;
+    this.computeBbox();
+  }
+  computeBbox() {
+    const tmp = new Canvas(1, 1);
+    tmp.ctx.font = `${this.fontSize}px sans-serif`;
+    const w = ~~tmp.ctx.measureText(this.text).width;
+    this.bbox = {
+      left: ~~(this.center[0] - w / 2),
+      top: ~~(this.center[1] - this.fontSize / 2),
+      width: w,
+      height: this.fontSize
+    };
+    return this;
+  }
+  render(ctx) {
+    ctx.textAlign = "center";
+    ctx.textBaseline = "middle";
+    ctx.font = `${this.fontSize}px sans-serif`;
+    ctx.fillText(this.text, this.center[0], this.center[1]);
+  }
+  mutate(_cfg) {
+    const clone = new _Smiley(0, 0, this.text);
+    clone.center = [this.center[0], this.center[1]];
+    clone.fontSize = this.fontSize;
+    switch (Math.floor(Math.random() * 2)) {
+      case 0: {
+        const angle = Math.random() * 2 * Math.PI;
+        const radius = Math.random() * 20;
+        clone.center[0] += ~~(radius * Math.cos(angle));
+        clone.center[1] += ~~(radius * Math.sin(angle));
+        break;
+      }
+      case 1:
+        clone.fontSize += Math.random() > 0.5 ? 1 : -1;
+        clone.fontSize = Math.max(10, clone.fontSize);
+        break;
+    }
+    return clone.computeBbox();
+  }
+  toSVG() {
+    const text = document.createElementNS(SVGNS, "text");
+    text.appendChild(document.createTextNode(this.text));
+    text.setAttribute("text-anchor", "middle");
+    text.setAttribute("dominant-baseline", "central");
+    text.setAttribute("font-size", String(this.fontSize));
+    text.setAttribute("font-family", "sans-serif");
+    text.setAttribute("x", String(this.center[0]));
+    text.setAttribute("y", String(this.center[1]));
+    return text;
+  }
+};
+var Hexagon = class _Hexagon extends Shape {
+  center;
+  r;
+  angle;
+  _cachedPoints;
+  constructor(w, h) {
+    super(w, h);
+    this.center = Shape.randomPoint(w, h);
+    this.r = 1 + ~~(Math.random() * 20);
+    this.angle = Math.random() * Math.PI / 3;
+    this._cachedPoints = null;
+    this.computeBbox();
+  }
+  _points() {
+    if (!this._cachedPoints) {
+      this._cachedPoints = Array.from({ length: 6 }, (_, i) => {
+        const a = this.angle + i * Math.PI / 3;
+        return [
+          ~~(this.center[0] + this.r * Math.cos(a)),
+          ~~(this.center[1] + this.r * Math.sin(a))
+        ];
+      });
+    }
+    return this._cachedPoints;
+  }
+  computeBbox() {
+    this._cachedPoints = null;
+    const pts = this._points();
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+    for (const [x, y] of pts) {
+      if (x < minX) minX = x;
+      if (y < minY) minY = y;
+      if (x > maxX) maxX = x;
+      if (y > maxY) maxY = y;
+    }
+    this.bbox = {
+      left: minX,
+      top: minY,
+      width: maxX - minX || 1,
+      height: maxY - minY || 1
+    };
+    return this;
+  }
+  render(ctx) {
+    const pts = this._points();
+    ctx.beginPath();
+    pts.forEach(([x, y], i) => i ? ctx.lineTo(x, y) : ctx.moveTo(x, y));
+    ctx.closePath();
+    ctx.fill();
+  }
+  toSVG() {
+    const node = document.createElementNS(SVGNS, "polygon");
+    node.setAttribute("points", this._points().map((p) => p.join(",")).join(" "));
+    return node;
+  }
+  mutate(_cfg) {
+    const clone = new _Hexagon(0, 0);
+    clone.center = [this.center[0], this.center[1]];
+    clone.r = this.r;
+    clone.angle = this.angle;
+    switch (Math.floor(Math.random() * 3)) {
+      case 0: {
+        const a = Math.random() * 2 * Math.PI;
+        const d = Math.random() * 20;
+        clone.center[0] += ~~(d * Math.cos(a));
+        clone.center[1] += ~~(d * Math.sin(a));
+        break;
+      }
+      case 1:
+        clone.r += (Math.random() - 0.5) * 20;
+        clone.r = Math.max(1, ~~clone.r);
+        break;
+      case 2:
+        clone.angle += (Math.random() - 0.5) * Math.PI / 3;
+        break;
+    }
+    return clone.computeBbox();
+  }
+};
+var Debug = class extends Shape {
+  constructor(w, h) {
+    super(w, h);
+    this.bbox = { left: 0, top: 0, width: w, height: h };
+  }
+  render(ctx) {
+    ctx.fillRect(0, 0, 1.5, 1.5);
+  }
+};
+
+// src/optimizer.ts
+var Optimizer = class {
+  cfg;
+  state;
+  onStep;
+  _steps;
+  _stopped;
+  _paused;
+  constructor(original, cfg) {
+    this.cfg = cfg;
+    this.state = new State(original, Canvas.empty(cfg));
+    this._steps = 0;
+    this._stopped = false;
+    this._paused = false;
+    this.onStep = () => {
+    };
+  }
+  start() {
+    this._stopped = false;
+    this._paused = false;
+    this._addShape();
+  }
+  stop() {
+    this._stopped = true;
+  }
+  pause() {
+    this._paused = true;
+  }
+  resume() {
+    if (this._paused && !this._stopped) {
+      this._paused = false;
+      this._addShape();
+    }
+  }
+  _addShape() {
+    this._findBestStep().then((step) => step ? this._optimizeStep(step) : null).then((step) => {
+      this._steps++;
+      if (step && step.distance < this.state.distance) {
+        this.state = step.apply(this.state);
+        this.onStep(step);
+      } else {
+        this.onStep(null);
+      }
+      this._continue();
+    }).catch(() => this._continue());
+  }
+  _continue() {
+    if (this._stopped || this._paused) {
+      return;
+    }
+    if (this._steps < this.cfg.steps) {
+      requestAnimationFrame(() => this._addShape());
+    }
+  }
+  _findBestStep() {
+    const LIMIT = this.cfg.shapes;
+    let bestStep = null;
+    const promises = [];
+    for (let i = 0; i < LIMIT; i++) {
+      const shape = Shape.create(this.cfg);
+      const promise = new Step(shape, this.cfg).compute(this.state).then((step) => {
+        if (!bestStep || step.distance < bestStep.distance) {
+          bestStep = step;
+        }
+      });
+      promises.push(promise);
+    }
+    return Promise.all(promises).then(() => bestStep);
+  }
+  _optimizeStep(step) {
+    const LIMIT = this.cfg.mutations;
+    let failedAttempts = 0;
+    let resolve;
+    let bestStep = step;
+    const promise = new Promise((r) => resolve = r);
+    const tryMutation = () => {
+      if (failedAttempts >= LIMIT) {
+        return resolve(bestStep);
+      }
+      bestStep.mutate().compute(this.state).then((mutatedStep) => {
+        if (mutatedStep.distance < bestStep.distance) {
+          failedAttempts = 0;
+          bestStep = mutatedStep;
+        } else {
+          failedAttempts++;
+        }
+        tryMutation();
+      });
+    };
+    tryMutation();
+    return promise;
+  }
+};
+export {
+  Canvas,
+  Debug,
+  Ellipse,
+  Hexagon,
+  Optimizer,
+  Rectangle,
+  SVGNS,
+  Shape,
+  Smiley,
+  State,
+  Step,
+  Triangle,
+  clamp,
+  clampColor,
+  computeColorAndDifferenceChange,
+  difference,
+  differenceToDistance,
+  distanceToDifference,
+  stepPerf
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@slithy/prim-lib",
+  "version": "0.1.0",
+  "description": "Core engine for primitive-based image reconstruction.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.0",
+    "jsdom": "^28",
+    "tsup": "^8",
+    "typescript": "^5",
+    "vitest": "^4",
+    "@slithy/eslint-config": "0.0.0",
+    "@slithy/tsconfig": "0.0.0"
+  },
+  "author": {
+    "name": "Matthew Campagna",
+    "url": "https://github.com/mjcampagna"
+  },
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "keywords": [
+    "image",
+    "reconstruction",
+    "primitive",
+    "shapes",
+    "canvas"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mjcampagna/slithy.git",
+    "directory": "packages/prim-lib"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "rm -rf dist && tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}