@slithy/prim-interface 0.3.2 → 0.4.0

package/README.md

@@ -6,6 +6,21 @@ Browser-facing API for `@slithy/prim-lib`. Consumed by `apps/prim-demo`.
 
 Wraps `prim-lib` in a `run()` / `runWorker()` API and provides save/copy/share helpers for exporting results. `run()` runs the optimizer on the main thread; `runWorker()` moves computation into a Web Worker, keeping the main thread responsive during long jobs. Both share the same callback API.
 
+## Vite setup
+
+This package ships a Web Worker and is incompatible with Vite's dependency optimizer. Add it to `optimizeDeps.exclude` in your Vite config:
+
+```ts
+// vite.config.ts
+optimizeDeps: {
+  exclude: ['@slithy/prim-interface']
+}
+```
+
+The same applies to `electron-vite` projects — the exclusion goes under `renderer.optimizeDeps.exclude`.
+
+---
+
 ## Exports
 
 ### `run(source, config, callbacks)` / `runWorker(source, config, callbacks)`
@@ -18,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
@@ -25,6 +41,7 @@ const job = runWorker(imageUrl, config, { // off-thread
   onStep({ raster, svg, svgString, stepData, progress }) {},
   onComplete(serialized) {},
   onStop() {},
+  onError(message) {},
 });
 
 job.stop();
@@ -34,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 automatically. 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
 
@@ -49,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
@@ -61,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
@@ -85,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):
@@ -122,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;
@@ -11,6 +11,7 @@ interface Config {
     viewSize: number;
     allowUpscale?: boolean;
     pixelRatio?: number;
+    glyphChar?: string;
     shapeTypes: Array<new (w: number, h: number) => ShapeInterface>;
     shapeWeights?: number[];
     fill: 'auto' | string;
@@ -34,6 +35,7 @@ interface RunCallbacks {
     onStep?: (result: StepResult) => void;
     onComplete?: (serialized: SerializedOutput) => void;
     onStop?: () => void;
+    onError?: (message: string) => void;
 }
 interface JobHandle {
     stop(): void;

package/dist/index.js

@@ -58,7 +58,8 @@ 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: () => {
@@ -123,15 +124,21 @@ function runWorker(source, cfg, callbacks = {}) {
     } else if (msg.type === "stopped") {
       if (isBlob) URL.revokeObjectURL(url);
       callbacks.onStop?.();
+    } 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 +233,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 +245,8 @@ export {
   copyRaster,
   copyRasterFromVector,
   copyVector,
+  makeNGon,
+  makeRect,
   replayOutput,
   run,
   runWorker,

package/dist/worker-entry.d.ts

@@ -1,7 +1,15 @@
-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 = {
     type: 'start';
@@ -33,6 +41,9 @@ type WorkerOutbound = {
     serialized: SerializedOutput;
 } | {
     type: 'stopped';
+} | {
+    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,
@@ -16,15 +16,38 @@ self.onmessage = async (e) => {
   switch (msg.type) {
     case "start": {
       const { url, cfg: workerCfg } = msg;
-      const { shapeTypeNames, ...rest } = workerCfg;
-      const shapeTypes = shapeTypeNames.map((name) => {
-        const ctor = SHAPES[name];
-        if (!ctor) throw new Error(`[prim worker] Unknown shape type: ${name}`);
+      const { shapeTypeNames, glyphChar, ...rest } = workerCfg;
+      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) {
+              super(w, h, char);
+            }
+          };
+        }
         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 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slithy/prim-interface",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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",