@slithy/prim-interface 0.3.3 → 0.4.1

package/README.md

@@ -33,6 +33,7 @@ const job = run(imageUrl, config, {       // main-thread
   onStep({ raster, svg, svgString, stepData, progress }) {},
   onComplete(serialized) {},
   onStop() {},
+  onError(message) {},
 });
 
 const job = runWorker(imageUrl, config, { // off-thread
@@ -40,6 +41,7 @@ const job = runWorker(imageUrl, config, { // off-thread
   onStep({ raster, svg, svgString, stepData, progress }) {},
   onComplete(serialized) {},
   onStop() {},
+  onError(message) {},
 });
 
 job.stop();
@@ -49,7 +51,7 @@ job.resume();
 
 **`run()`** — runs the optimizer on the main thread via `requestAnimationFrame`. Simpler; no worker overhead. UI may feel sluggish during compute-heavy steps at high `shapes` / `mutations` settings.
 
-**`runWorker()`** — moves all computation into a Web Worker using `OffscreenCanvas`. The main thread only handles DOM updates (appending the canvas/SVG, calling callbacks). Requires a bundler that understands `new Worker(new URL(..., import.meta.url))` — Vite handles this, but see the Vite setup section above for a required config change. Shape constructors in `config.shapeTypes` are mapped to names internally; only the built-in shapes (`Triangle`, `Rectangle`, `Ellipse`, `Circle`, `Square`, `Hexagon`, `Glyph`) are supported.
+**`runWorker()`** — moves all computation into a Web Worker using `OffscreenCanvas`. The main thread only handles DOM updates (appending the canvas/SVG, calling callbacks). Requires a bundler that understands `new Worker(new URL(..., import.meta.url))` — Vite handles this, but see the Vite setup section above for a required config change. Both fixed shapes (`Triangle`, `Rectangle`, etc.) and factory shapes (`makeNGon`, `makeRect`) are supported in `config.shapeTypes`.
 
 ### Config
 
@@ -64,6 +66,7 @@ interface Config {
   viewSize: number       // display/output resolution (px, longest edge)
   allowUpscale?: boolean // allow output larger than source image (default: false)
   pixelRatio?: number    // device pixel ratio for the raster canvas (default: 1)
+  glyphChar?: string     // Unicode character for the Glyph shape (default: '☺')
   shapeTypes: ShapeConstructor[]
   shapeWeights?: number[]  // per-shape selection weights (same length as shapeTypes)
   fill: 'auto' | string
@@ -76,6 +79,8 @@ interface Config {
 
 **`pixelRatio`** — pass `window.devicePixelRatio` to produce a HiDPI raster canvas. The canvas pixel dimensions are `viewSize × pixelRatio`; set its CSS size to `viewSize` for a 1:1 device pixel mapping. Does not affect the SVG output or the optimizer; only the raster display canvas.
 
+**`glyphChar`** — Unicode character used by the `Glyph` shape when running via `runWorker()`. Defaults to `'☺'` when omitted. Has no effect with `run()`, since the main-thread path accepts shape constructors directly (subclass `Glyph` with a custom character if needed).
+
 **`shapeWeights`** — optional array of weights, one per entry in `shapeTypes`, controlling how often each shape type is used. Weights are relative (e.g. `[3, 1]` means 75% / 25%). When provided, the optimizer pre-allocates an exact number of slots per shape type (proportional to the weights) and shuffles them, guaranteeing the final distribution matches — rather than just biasing random selection.
 
 ### Callbacks
@@ -100,6 +105,10 @@ interface StepResult {
 
 **`onComplete(serialized)`** — called when all steps finish. Receives a `SerializedOutput` — a compact, storage-ready representation of the full run that can be replayed via `replayOutput()`.
 
+**`onStop()`** — called when the job is stopped via `job.stop()`.
+
+**`onError(message)`** — called if the job fails (e.g. image failed to load or decode). The job is considered stopped after this; no further callbacks will fire.
+
 ### Exit helpers
 
 Higher-level (rasterize SVG at save time for crisp output):
@@ -137,4 +146,12 @@ const { raster, svg, svgString } = replayOutput(serializedData);
 
 ### Re-exports from prim-lib
 
-`Triangle`, `Rectangle`, `Ellipse`, `Circle`, `Square`, `Hexagon`, `Glyph`, `stepPerf`, `replayOutput`, `RGB`, `SerializedOutput`, `StepData`, `ReplayResult`
+**Shapes:** `Triangle`, `Rectangle`, `Ellipse`, `Circle`, `Square`, `Hexagon`, `Glyph`
+
+**Factories:** `makeNGon`, `makeRect`
+
+**Factory option types:** `NGonOptions`, `RectOptions`
+
+**Functions:** `stepPerf`, `replayOutput`
+
+**Types:** `RGB`, `SerializedOutput`, `StepData`, `ReplayResult`, `ShapeInterface`, `Bbox`

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ShapeInterface, StepData, SerializedOutput } from '@slithy/prim-lib';
-export { Bbox, Circle, Ellipse, Glyph, Hexagon, RGB, Rectangle, ReplayResult, SerializedOutput, ShapeInterface, Square, StepData, Triangle, replayOutput, stepPerf } from '@slithy/prim-lib';
+export { Bbox, Circle, Ellipse, Glyph, Hexagon, NGonOptions, RGB, RectOptions, Rectangle, ReplayResult, SerializedOutput, ShapeInterface, Square, StepData, Triangle, makeNGon, makeRect, replayOutput, stepPerf } from '@slithy/prim-lib';
 
 interface Config {
     steps: number;
@@ -34,7 +34,8 @@ interface RunCallbacks {
     onStart?: (raster: HTMLCanvasElement, svg: SVGSVGElement) => void;
     onStep?: (result: StepResult) => void;
     onComplete?: (serialized: SerializedOutput) => void;
-    onStop?: () => void;
+    onStop?: (serialized: SerializedOutput | null) => void;
+    onError?: (message: string) => void;
 }
 interface JobHandle {
     stop(): void;

package/dist/index.js

@@ -4,13 +4,15 @@ function run(source, cfg, callbacks = {}) {
   const url = source instanceof File ? URL.createObjectURL(source) : source;
   let optimizer = null;
   let stopped = false;
+  let computeCfg = null;
+  let accumulatedSteps = [];
   Canvas.original(url, cfg).then((original) => {
     if (stopped) {
       if (source instanceof File) URL.revokeObjectURL(url);
       return;
     }
     if (source instanceof File) URL.revokeObjectURL(url);
-    const computeCfg = { ...cfg, width: cfg.width, height: cfg.height };
+    computeCfg = { ...cfg, width: cfg.width, height: cfg.height };
     const pixelRatio = cfg.pixelRatio ?? 1;
     const viewCfg = { ...computeCfg, width: computeCfg.scale * computeCfg.width, height: computeCfg.scale * computeCfg.height };
     const deviceViewCfg = { ...viewCfg, width: viewCfg.width * pixelRatio, height: viewCfg.height * pixelRatio };
@@ -23,7 +25,6 @@ function run(source, cfg, callbacks = {}) {
     svg.setAttribute("height", String(viewCfg.height));
     callbacks.onStart?.(rasterNode, svg);
     const serializer = new XMLSerializer();
-    const accumulatedSteps = [];
     optimizer = new Optimizer(original, computeCfg);
     let stepCount = 0;
     optimizer.onStep = (step) => {
@@ -58,13 +59,21 @@ function run(source, cfg, callbacks = {}) {
     };
     optimizer.start();
   }).catch((err) => {
-    console.error("[prim] run failed:", err);
+    if (source instanceof File) URL.revokeObjectURL(url);
+    callbacks.onError?.(err instanceof Error ? err.message : String(err));
   });
   return {
     stop: () => {
       stopped = true;
       optimizer?.stop();
-      callbacks.onStop?.();
+      callbacks.onStop?.(computeCfg ? {
+        v: 1,
+        w: computeCfg.width,
+        h: computeCfg.height,
+        scale: computeCfg.scale,
+        fill: parseColor(cfg.fill),
+        steps: accumulatedSteps
+      } : null);
     },
     pause: () => optimizer?.pause(),
     resume: () => optimizer?.resume()
@@ -122,16 +131,22 @@ function runWorker(source, cfg, callbacks = {}) {
       callbacks.onComplete?.(msg.serialized);
     } else if (msg.type === "stopped") {
       if (isBlob) URL.revokeObjectURL(url);
-      callbacks.onStop?.();
+      callbacks.onStop?.(msg.serialized);
+    } else if (msg.type === "error") {
+      if (isBlob) URL.revokeObjectURL(url);
+      callbacks.onError?.(msg.message);
     }
   };
   worker.onerror = (e) => {
-    console.error("[prim worker]", e);
+    if (isBlob) URL.revokeObjectURL(url);
+    callbacks.onError?.(e.message ?? "Unknown worker error");
   };
   const { shapeTypes, pixelRatio: _pr, width: _w, height: _h, scale: _s, ...rest } = cfg;
   const workerCfg = {
     ...rest,
-    shapeTypeNames: shapeTypes.map((ctor) => ctor.name)
+    shapeTypeNames: shapeTypes.map(
+      (ctor) => "_shapeSpec" in ctor ? ctor._shapeSpec : ctor.name
+    )
   };
   worker.postMessage({ type: "start", url, cfg: workerCfg });
   return {
@@ -226,7 +241,7 @@ async function share(canvas, options) {
 }
 
 // src/index.ts
-import { Triangle, Rectangle, Ellipse, Circle, Square, Hexagon, Glyph, stepPerf, replayOutput } from "@slithy/prim-lib";
+import { Triangle, Rectangle, Ellipse, Circle, Square, Hexagon, Glyph, stepPerf, replayOutput, makeNGon, makeRect } from "@slithy/prim-lib";
 export {
   Circle,
   Ellipse,
@@ -238,6 +253,8 @@ export {
   copyRaster,
   copyRasterFromVector,
   copyVector,
+  makeNGon,
+  makeRect,
   replayOutput,
   run,
   runWorker,

package/dist/worker-entry.d.ts

@@ -1,7 +1,14 @@
-import { PreCfg, StepData, SerializedOutput } from '@slithy/prim-lib';
+import { NGonOptions, RectOptions, PreCfg, StepData, SerializedOutput } from '@slithy/prim-lib';
 
+type ShapeTypeSpec = string | {
+    f: 'ngon';
+    o: NGonOptions;
+} | {
+    f: 'rect';
+    o: RectOptions;
+};
 type WorkerCfg = Omit<PreCfg, 'shapeTypes'> & {
-    shapeTypeNames: string[];
+    shapeTypeNames: ShapeTypeSpec[];
     glyphChar?: string;
 };
 type WorkerInbound = {
@@ -34,6 +41,10 @@ type WorkerOutbound = {
     serialized: SerializedOutput;
 } | {
     type: 'stopped';
+    serialized: SerializedOutput | null;
+} | {
+    type: 'error';
+    message: string;
 };
 
-export type { WorkerCfg, WorkerInbound, WorkerOutbound };
+export type { ShapeTypeSpec, WorkerCfg, WorkerInbound, WorkerOutbound };

package/dist/worker-entry.js

@@ -1,5 +1,5 @@
 // src/worker-entry.ts
-import { Canvas, Optimizer, parseColor } from "@slithy/prim-lib";
+import { Canvas, Optimizer, parseColor, makeNGon, makeRect } from "@slithy/prim-lib";
 import { Triangle, Rectangle, Ellipse, Circle, Square, Hexagon, Glyph } from "@slithy/prim-lib";
 var SHAPES = {
   Triangle,
@@ -11,16 +11,26 @@ var SHAPES = {
   Glyph
 };
 var optimizer = null;
+var computeCfg = null;
+var accumulatedSteps = [];
 self.onmessage = async (e) => {
   const msg = e.data;
   switch (msg.type) {
     case "start": {
       const { url, cfg: workerCfg } = msg;
       const { shapeTypeNames, glyphChar, ...rest } = workerCfg;
-      const shapeTypes = shapeTypeNames.map((name) => {
-        const ctor = SHAPES[name];
-        if (!ctor) throw new Error(`[prim worker] Unknown shape type: ${name}`);
-        if (name === "Glyph" && glyphChar) {
+      const shapeTypes = shapeTypeNames.map((spec) => {
+        if (typeof spec === "object") {
+          switch (spec.f) {
+            case "ngon":
+              return makeNGon(spec.o);
+            case "rect":
+              return makeRect(spec.o);
+          }
+        }
+        const ctor = SHAPES[spec];
+        if (!ctor) throw new Error(`[prim worker] Unknown shape type: ${spec}`);
+        if (spec === "Glyph" && glyphChar) {
           const char = glyphChar;
           return class GlyphWithChar extends Glyph {
             constructor(w, h) {
@@ -31,11 +41,19 @@ self.onmessage = async (e) => {
         return ctor;
       });
       const preCfg = { ...rest, shapeTypes };
-      const blob = await fetch(url).then((r) => r.blob());
-      const bitmap = await createImageBitmap(blob);
+      let blob;
+      let bitmap;
+      try {
+        blob = await fetch(url).then((r) => r.blob());
+        bitmap = await createImageBitmap(blob);
+      } catch (err) {
+        self.postMessage({ type: "error", message: err instanceof Error ? err.message : String(err) });
+        break;
+      }
       const original = Canvas.fromBitmap(bitmap, preCfg);
       bitmap.close();
-      const computeCfg = { ...preCfg, width: preCfg.width, height: preCfg.height };
+      computeCfg = { ...preCfg, width: preCfg.width, height: preCfg.height };
+      accumulatedSteps = [];
       self.postMessage({
         type: "ready",
         width: computeCfg.width,
@@ -43,9 +61,9 @@ self.onmessage = async (e) => {
         scale: computeCfg.scale,
         fill: computeCfg.fill
       });
-      const accumulatedSteps = [];
       let stepCount = 0;
-      optimizer = new Optimizer(original, computeCfg, (fn) => setTimeout(fn, 0));
+      const cc = computeCfg;
+      optimizer = new Optimizer(original, cc, (fn) => setTimeout(fn, 0));
       optimizer.onStep = (step) => {
         stepCount++;
         if (step) {
@@ -56,19 +74,19 @@ self.onmessage = async (e) => {
             stepData,
             progress: {
               current: stepCount,
-              total: computeCfg.steps,
+              total: cc.steps,
               similarity: parseFloat((100 * (1 - step.distance)).toFixed(2))
             }
           };
           self.postMessage(outbound);
         }
-        if (stepCount >= computeCfg.steps) {
+        if (stepCount >= cc.steps) {
           const serialized = {
             v: 1,
-            w: computeCfg.width,
-            h: computeCfg.height,
-            scale: computeCfg.scale,
-            fill: parseColor(computeCfg.fill),
+            w: cc.width,
+            h: cc.height,
+            scale: cc.scale,
+            fill: parseColor(cc.fill),
             steps: accumulatedSteps
           };
           self.postMessage({ type: "complete", serialized });
@@ -85,7 +103,14 @@ self.onmessage = async (e) => {
       break;
     case "stop":
       optimizer?.stop();
-      self.postMessage({ type: "stopped" });
+      self.postMessage({ type: "stopped", serialized: computeCfg ? {
+        v: 1,
+        w: computeCfg.width,
+        h: computeCfg.height,
+        scale: computeCfg.scale,
+        fill: parseColor(computeCfg.fill),
+        steps: accumulatedSteps
+      } : null });
       break;
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slithy/prim-interface",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Browser-facing API for primitive-based image reconstruction.",
   "type": "module",
   "exports": {
@@ -18,7 +18,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@slithy/prim-lib": "0.4.1"
+    "@slithy/prim-lib": "0.5.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.2",
@@ -26,8 +26,8 @@
     "tsup": "^8",
     "typescript": "^5",
     "vitest": "^4.1.2",
-    "@slithy/tsconfig": "0.0.0",
-    "@slithy/eslint-config": "0.0.0"
+    "@slithy/eslint-config": "0.0.0",
+    "@slithy/tsconfig": "0.0.0"
   },
   "author": {
     "name": "Matthew Campagna",