@slithy/prim-interface 0.2.10 → 0.3.0

package/README.md

@@ -4,16 +4,23 @@ Browser-facing API for `@slithy/prim-lib`. Consumed by `apps/prim-demo`.
 
 ## What it does
 
-Wraps `prim-lib` in a simple `run()` API and provides save/copy/share helpers for exporting results.
+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.
 
 ## Exports
 
-### `run(source, config, callbacks)`
+### `run(source, config, callbacks)` / `runWorker(source, config, callbacks)`
 
-Starts a reconstruction job. Returns a `JobHandle` for stopping, pausing, and resuming.
+Start a reconstruction job. Both return a `JobHandle` for stopping, pausing, and resuming, and accept identical arguments.
 
 ```ts
-const job = run(imageUrl, config, {
+const job = run(imageUrl, config, {       // main-thread
+  onStart(raster, svg) {},
+  onStep({ raster, svg, svgString, stepData, progress }) {},
+  onComplete(serialized) {},
+  onStop() {},
+});
+
+const job = runWorker(imageUrl, config, { // off-thread
   onStart(raster, svg) {},
   onStep({ raster, svg, svgString, stepData, progress }) {},
   onComplete(serialized) {},
@@ -25,6 +32,10 @@ job.pause();
 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.
+
 ### Config
 
 ```ts

package/dist/index.d.ts

@@ -43,6 +43,8 @@ interface JobHandle {
 
 declare function run(source: string | File, cfg: Config, callbacks?: RunCallbacks): JobHandle;
 
+declare function runWorker(source: string | File, cfg: Config, callbacks?: RunCallbacks): JobHandle;
+
 interface SaveOptions {
     suffix?: string;
     filename?: string;
@@ -56,4 +58,4 @@ declare function copyVector(svgString: string): Promise<void>;
 declare function copyRaster(canvas: HTMLCanvasElement): Promise<void>;
 declare function share(canvas: HTMLCanvasElement, options?: SaveOptions): Promise<void>;
 
-export { type Config, type JobHandle, type RunCallbacks, type SaveOptions, type StepResult, copyRaster, copyRasterFromVector, copyVector, run, saveRaster, saveRasterFromVector, saveVector, share, shareFromVector };
+export { type Config, type JobHandle, type RunCallbacks, type SaveOptions, type StepResult, copyRaster, copyRasterFromVector, copyVector, run, runWorker, saveRaster, saveRasterFromVector, saveVector, share, shareFromVector };

package/dist/index.js

@@ -16,10 +16,12 @@ function run(source, cfg, callbacks = {}) {
     const deviceViewCfg = { ...viewCfg, width: viewCfg.width * pixelRatio, height: viewCfg.height * pixelRatio };
     const result = Canvas.empty(deviceViewCfg);
     result.ctx.scale(computeCfg.scale * pixelRatio, computeCfg.scale * pixelRatio);
+    if (!(result.node instanceof HTMLCanvasElement)) throw new Error("[prim] Expected HTMLCanvasElement");
+    const rasterNode = result.node;
     const svg = Canvas.empty(computeCfg, true);
     svg.setAttribute("width", String(viewCfg.width));
     svg.setAttribute("height", String(viewCfg.height));
-    callbacks.onStart?.(result.node, svg);
+    callbacks.onStart?.(rasterNode, svg);
     const serializer = new XMLSerializer();
     const accumulatedSteps = [];
     optimizer = new Optimizer(original, computeCfg);
@@ -32,7 +34,7 @@ function run(source, cfg, callbacks = {}) {
         const stepData = step.serialize();
         accumulatedSteps.push(stepData);
         callbacks.onStep?.({
-          raster: result.node,
+          raster: rasterNode,
           svg,
           svgString: serializer.serializeToString(svg),
           stepData,
@@ -69,6 +71,80 @@ function run(source, cfg, callbacks = {}) {
   };
 }
 
+// src/runWorker.ts
+import { Canvas as Canvas2, renderStepToCtx, stepDataToSVGElement } from "@slithy/prim-lib";
+function runWorker(source, cfg, callbacks = {}) {
+  const url = source instanceof File ? URL.createObjectURL(source) : source;
+  const isBlob = source instanceof File;
+  let stopped = false;
+  let result = null;
+  let svgEl = null;
+  const serializer = new XMLSerializer();
+  const worker = new Worker(new URL("./worker-entry.js", import.meta.url), { type: "module" });
+  worker.onmessage = (e) => {
+    const msg = e.data;
+    if (msg.type === "ready") {
+      const { width, height, scale, fill } = msg;
+      const pixelRatio = cfg.pixelRatio ?? 1;
+      const computeCfg = { ...cfg, width, height, scale, fill };
+      const viewCfg = {
+        ...computeCfg,
+        width: scale * width,
+        height: scale * height
+      };
+      const deviceViewCfg = {
+        ...viewCfg,
+        width: viewCfg.width * pixelRatio,
+        height: viewCfg.height * pixelRatio
+      };
+      result = Canvas2.empty(deviceViewCfg);
+      const displayCanvas = result.node;
+      displayCanvas.style.width = `${viewCfg.width}px`;
+      result.ctx.scale(scale * pixelRatio, scale * pixelRatio);
+      svgEl = Canvas2.empty(computeCfg, true);
+      svgEl.setAttribute("width", String(viewCfg.width));
+      svgEl.setAttribute("height", String(viewCfg.height));
+      callbacks.onStart?.(displayCanvas, svgEl);
+    } else if (msg.type === "step") {
+      if (!result || !svgEl) return;
+      const { stepData, progress } = msg;
+      renderStepToCtx(stepData, result.ctx);
+      svgEl.appendChild(stepDataToSVGElement(stepData));
+      callbacks.onStep?.({
+        raster: result.node,
+        svg: svgEl,
+        svgString: serializer.serializeToString(svgEl),
+        stepData,
+        progress
+      });
+    } else if (msg.type === "complete") {
+      if (isBlob) URL.revokeObjectURL(url);
+      callbacks.onComplete?.(msg.serialized);
+    } else if (msg.type === "stopped") {
+      if (isBlob) URL.revokeObjectURL(url);
+      callbacks.onStop?.();
+    }
+  };
+  worker.onerror = (e) => {
+    console.error("[prim worker]", e);
+  };
+  const { shapeTypes, pixelRatio: _pr, width: _w, height: _h, scale: _s, ...rest } = cfg;
+  const workerCfg = {
+    ...rest,
+    shapeTypeNames: shapeTypes.map((ctor) => ctor.name)
+  };
+  worker.postMessage({ type: "start", url, cfg: workerCfg });
+  return {
+    stop: () => {
+      if (stopped) return;
+      stopped = true;
+      worker.postMessage({ type: "stop" });
+    },
+    pause: () => worker.postMessage({ type: "pause" }),
+    resume: () => worker.postMessage({ type: "resume" })
+  };
+}
+
 // src/exit.ts
 function buildFilename(ext, options) {
   const suffix = options?.suffix ?? "prim";
@@ -164,6 +240,7 @@ export {
   copyVector,
   replayOutput,
   run,
+  runWorker,
   saveRaster,
   saveRasterFromVector,
   saveVector,

package/dist/worker-entry.d.ts

@@ -0,0 +1,38 @@
+import { PreCfg, StepData, SerializedOutput } from '@slithy/prim-lib';
+
+type WorkerCfg = Omit<PreCfg, 'shapeTypes'> & {
+    shapeTypeNames: string[];
+};
+type WorkerInbound = {
+    type: 'start';
+    url: string;
+    cfg: WorkerCfg;
+} | {
+    type: 'pause';
+} | {
+    type: 'resume';
+} | {
+    type: 'stop';
+};
+type WorkerOutbound = {
+    type: 'ready';
+    width: number;
+    height: number;
+    scale: number;
+    fill: string;
+} | {
+    type: 'step';
+    stepData: StepData;
+    progress: {
+        current: number;
+        total: number;
+        similarity: number;
+    };
+} | {
+    type: 'complete';
+    serialized: SerializedOutput;
+} | {
+    type: 'stopped';
+};
+
+export type { WorkerCfg, WorkerInbound, WorkerOutbound };

package/dist/worker-entry.js

@@ -0,0 +1,83 @@
+// src/worker-entry.ts
+import { Canvas, Optimizer, parseColor } from "@slithy/prim-lib";
+import { Triangle, Rectangle, Ellipse, Circle, Square, Hexagon, Glyph } from "@slithy/prim-lib";
+var SHAPES = {
+  Triangle,
+  Rectangle,
+  Ellipse,
+  Circle,
+  Square,
+  Hexagon,
+  Glyph
+};
+var optimizer = null;
+self.onmessage = async (e) => {
+  const msg = e.data;
+  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}`);
+        return ctor;
+      });
+      const preCfg = { ...rest, shapeTypes };
+      const blob = await fetch(url).then((r) => r.blob());
+      const bitmap = await createImageBitmap(blob);
+      const original = Canvas.fromBitmap(bitmap, preCfg);
+      bitmap.close();
+      const computeCfg = { ...preCfg, width: preCfg.width, height: preCfg.height };
+      self.postMessage({
+        type: "ready",
+        width: computeCfg.width,
+        height: computeCfg.height,
+        scale: computeCfg.scale,
+        fill: computeCfg.fill
+      });
+      const accumulatedSteps = [];
+      let stepCount = 0;
+      optimizer = new Optimizer(original, computeCfg, (fn) => setTimeout(fn, 0));
+      optimizer.onStep = (step) => {
+        stepCount++;
+        if (step) {
+          const stepData = step.serialize();
+          accumulatedSteps.push(stepData);
+          const outbound = {
+            type: "step",
+            stepData,
+            progress: {
+              current: stepCount,
+              total: computeCfg.steps,
+              similarity: parseFloat((100 * (1 - step.distance)).toFixed(2))
+            }
+          };
+          self.postMessage(outbound);
+        }
+        if (stepCount >= computeCfg.steps) {
+          const serialized = {
+            v: 1,
+            w: computeCfg.width,
+            h: computeCfg.height,
+            scale: computeCfg.scale,
+            fill: parseColor(computeCfg.fill),
+            steps: accumulatedSteps
+          };
+          self.postMessage({ type: "complete", serialized });
+        }
+      };
+      optimizer.start();
+      break;
+    }
+    case "pause":
+      optimizer?.pause();
+      break;
+    case "resume":
+      optimizer?.resume();
+      break;
+    case "stop":
+      optimizer?.stop();
+      self.postMessage({ type: "stopped" });
+      break;
+  }
+};

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@slithy/prim-interface",
-  "version": "0.2.10",
+  "version": "0.3.0",
   "description": "Browser-facing API for primitive-based image reconstruction.",
   "type": "module",
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./worker-entry": {
+      "import": "./dist/worker-entry.js",
+      "types": "./dist/worker-entry.d.ts"
     }
   },
   "files": [
@@ -14,16 +18,16 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@slithy/prim-lib": "0.3.2"
+    "@slithy/prim-lib": "0.4.0"
   },
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.0",
-    "jsdom": "^28",
+    "@vitest/coverage-v8": "^4.1.2",
+    "jsdom": "^29.0.1",
     "tsup": "^8",
     "typescript": "^5",
-    "vitest": "^4",
-    "@slithy/eslint-config": "0.0.0",
-    "@slithy/tsconfig": "0.0.0"
+    "vitest": "^4.1.2",
+    "@slithy/tsconfig": "0.0.0",
+    "@slithy/eslint-config": "0.0.0"
   },
   "author": {
     "name": "Matthew Campagna",
@@ -47,8 +51,8 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "build": "rm -rf dist && tsup src/index.ts --format esm --dts",
-    "dev": "tsup src/index.ts --format esm --watch",
+    "build": "rm -rf dist && tsup src/index.ts src/worker-entry.ts --format esm --dts",
+    "dev": "tsup src/index.ts src/worker-entry.ts --format esm --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "test": "vitest run",