@slithy/prim-interface 0.1.1 → 0.2.1

package/README.md

@@ -15,8 +15,8 @@ Starts a reconstruction job. Returns a `JobHandle` for stopping, pausing, and re
 ```ts
 const job = run(imageUrl, config, {
   onStart(raster, svg) {},
-  onStep({ raster, svg, svgString, progress }) {},
-  onComplete() {},
+  onStep({ raster, svg, svgString, stepData, progress }) {},
+  onComplete(serialized) {},
   onStop() {},
 });
 
@@ -29,13 +29,15 @@ job.resume();
 
 ```ts
 interface Config {
-  steps: number        // shapes in the final image
-  shapes: number       // candidate shapes evaluated per step
-  mutations: number    // random mutations tried per candidate
-  alpha: number        // shape opacity
-  mutateAlpha: boolean // whether opacity is mutated per candidate
-  computeSize: number  // internal render resolution (px)
-  viewSize: number     // display resolution (px)
+  steps: number          // shapes in the final image
+  shapes: number         // candidate shapes evaluated per step
+  mutations: number      // random mutations tried per candidate
+  alpha: number          // shape opacity
+  mutateAlpha: boolean   // whether opacity is mutated per candidate
+  computeSize: number    // internal render resolution (px, longest edge)
+  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)
   shapeTypes: ShapeConstructor[]
   fill: 'auto' | string
 }
@@ -43,14 +45,56 @@ interface Config {
 
 `width`, `height`, and `scale` are set automatically by `run()` after loading the source image.
 
+**`allowUpscale`** — by default, output is capped at source image dimensions. Set to `true` to allow `viewSize` and `computeSize` to exceed the source, upscaling the output.
+
+**`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.
+
+### Callbacks
+
+**`onStart(raster, svg)`** — called once after the source image loads. `raster` is the display canvas; `svg` is the live SVG element. Both update in place as shapes are added.
+
+**`onStep(result)`** — called after each accepted shape:
+
+```ts
+interface StepResult {
+  raster: HTMLCanvasElement
+  svg: SVGSVGElement
+  svgString: string       // serialized SVG markup
+  stepData: StepData      // structured data for this shape
+  progress: {
+    current: number       // shapes placed so far
+    total: number         // cfg.steps
+    similarity: number    // % similarity to source (0–100)
+  }
+}
+```
+
+**`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()`.
+
 ### Exit helpers
 
-- **`saveRaster(canvas, format?, quality?)`** — downloads PNG or JPEG
+Higher-level (rasterize SVG at save time for crisp output):
+
+- **`saveRasterFromVector(svgString, width, height, format?, quality?)`** — downloads PNG or JPEG rasterized from the SVG
+- **`copyRasterFromVector(svgString, width, height)`** — copies a PNG rasterized from the SVG to the clipboard
+- **`shareFromVector(svgString, width, height)`** — shares a PNG rasterized from the SVG via the Web Share API
+
+Lower-level (operate directly on a canvas or SVG string):
+
+- **`saveRaster(canvas, format?, quality?)`** — downloads PNG or JPEG from a canvas
 - **`saveVector(svgString)`** — downloads SVG
 - **`copyRaster(canvas)`** — copies PNG to clipboard
 - **`copyVector(svgString)`** — copies SVG markup to clipboard
-- **`share(canvas)`** — uses Web Share API if available
+- **`share(canvas)`** — shares via Web Share API if available
+
+### `replayOutput(data: SerializedOutput): ReplayResult`
+
+Reconstructs a raster canvas and SVG from a `SerializedOutput` without re-running the optimizer. Use this to restore saved results from localStorage or a database.
+
+```ts
+const { raster, svg, svgString } = replayOutput(serializedData);
+```
 
 ### Re-exports from prim-lib
 
-`Triangle`, `Rectangle`, `Ellipse`, `Hexagon`, `Smiley`, `stepPerf`
+`Triangle`, `Rectangle`, `Ellipse`, `Square`, `Hexagon`, `Glyph`, `stepPerf`, `replayOutput`, `RGB`, `SerializedOutput`, `StepData`, `ReplayResult`

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { ShapeInterface } from '@slithy/prim-lib';
-export { Bbox, Ellipse, Hexagon, Rectangle, ShapeInterface, Smiley, Square, Triangle, stepPerf } from '@slithy/prim-lib';
+import { ShapeInterface, StepData, SerializedOutput } from '@slithy/prim-lib';
+export { Bbox, Ellipse, Glyph, Hexagon, RGB, Rectangle, ReplayResult, SerializedOutput, ShapeInterface, Square, StepData, Triangle, replayOutput, stepPerf } from '@slithy/prim-lib';
 
 interface Config {
     steps: number;
@@ -9,6 +9,8 @@ interface Config {
     mutateAlpha: boolean;
     computeSize: number;
     viewSize: number;
+    allowUpscale?: boolean;
+    pixelRatio?: number;
     shapeTypes: Array<new (w: number, h: number) => ShapeInterface>;
     fill: 'auto' | string;
     width?: number;
@@ -19,6 +21,7 @@ interface StepResult {
     raster: HTMLCanvasElement;
     svg: SVGSVGElement;
     svgString: string;
+    stepData: StepData;
     progress: {
         current: number;
         total: number;
@@ -28,7 +31,7 @@ interface StepResult {
 interface RunCallbacks {
     onStart?: (raster: HTMLCanvasElement, svg: SVGSVGElement) => void;
     onStep?: (result: StepResult) => void;
-    onComplete?: () => void;
+    onComplete?: (serialized: SerializedOutput) => void;
     onStop?: () => void;
 }
 interface JobHandle {
@@ -40,9 +43,12 @@ interface JobHandle {
 declare function run(source: string | File, cfg: Config, callbacks?: RunCallbacks): JobHandle;
 
 declare function saveRaster(canvas: HTMLCanvasElement, format?: 'png' | 'jpeg', quality?: number): void;
+declare function saveRasterFromVector(svgString: string, width: number, height: number, format?: 'png' | 'jpeg', quality?: number): Promise<void>;
+declare function copyRasterFromVector(svgString: string, width: number, height: number): Promise<void>;
+declare function shareFromVector(svgString: string, width: number, height: number): Promise<void>;
 declare function saveVector(svgString: string): void;
 declare function copyVector(svgString: string): Promise<void>;
 declare function copyRaster(canvas: HTMLCanvasElement): Promise<void>;
 declare function share(canvas: HTMLCanvasElement): Promise<void>;
 
-export { type Config, type JobHandle, type RunCallbacks, type StepResult, copyRaster, copyVector, run, saveRaster, saveVector, share };
+export { type Config, type JobHandle, type RunCallbacks, type StepResult, copyRaster, copyRasterFromVector, copyVector, run, saveRaster, saveRasterFromVector, saveVector, share, shareFromVector };

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/run.ts
-import { Canvas, Optimizer } from "@slithy/prim-lib";
+import { Canvas, Optimizer, parseColor } from "@slithy/prim-lib";
 function run(source, cfg, callbacks = {}) {
   const url = source instanceof File ? URL.createObjectURL(source) : source;
   let optimizer = null;
@@ -11,14 +11,17 @@ function run(source, cfg, callbacks = {}) {
     }
     if (source instanceof File) URL.revokeObjectURL(url);
     const 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 result = Canvas.empty(viewCfg);
-    result.ctx.scale(computeCfg.scale, computeCfg.scale);
+    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);
     const svg = Canvas.empty(computeCfg, true);
     svg.setAttribute("width", String(viewCfg.width));
     svg.setAttribute("height", String(viewCfg.height));
     callbacks.onStart?.(result.node, svg);
     const serializer = new XMLSerializer();
+    const accumulatedSteps = [];
     optimizer = new Optimizer(original, computeCfg);
     let stepCount = 0;
     optimizer.onStep = (step) => {
@@ -26,10 +29,13 @@ function run(source, cfg, callbacks = {}) {
       if (step) {
         result.drawStep(step);
         svg.appendChild(step.toSVG());
+        const stepData = step.serialize();
+        accumulatedSteps.push(stepData);
         callbacks.onStep?.({
           raster: result.node,
           svg,
           svgString: serializer.serializeToString(svg),
+          stepData,
           progress: {
             current: stepCount,
             total: cfg.steps,
@@ -38,7 +44,14 @@ function run(source, cfg, callbacks = {}) {
         });
       }
       if (stepCount >= cfg.steps) {
-        callbacks.onComplete?.();
+        callbacks.onComplete?.({
+          v: 1,
+          w: computeCfg.width,
+          h: computeCfg.height,
+          scale: computeCfg.scale,
+          fill: parseColor(cfg.fill),
+          steps: accumulatedSteps
+        });
       }
     };
     optimizer.start();
@@ -63,12 +76,45 @@ function triggerDownload(url, filename) {
   a.download = filename;
   a.click();
 }
+function svgToCanvas(svgString, width, height) {
+  return new Promise((resolve, reject) => {
+    const sized = svgString.replace(/(<svg[^>]*\s)width="[^"]*"/, `$1width="${width}"`).replace(/(<svg[^>]*\s)height="[^"]*"/, `$1height="${height}"`);
+    const blob = new Blob([sized], { type: "image/svg+xml" });
+    const url = URL.createObjectURL(blob);
+    const img = new Image();
+    img.onload = () => {
+      const canvas = document.createElement("canvas");
+      canvas.width = width;
+      canvas.height = height;
+      canvas.getContext("2d").drawImage(img, 0, 0, width, height);
+      URL.revokeObjectURL(url);
+      resolve(canvas);
+    };
+    img.onerror = () => {
+      URL.revokeObjectURL(url);
+      reject(new Error("Failed to rasterize SVG"));
+    };
+    img.src = url;
+  });
+}
 function saveRaster(canvas, format = "png", quality = 0.92) {
   const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
   const ext = format === "jpeg" ? "jpg" : "png";
   const dataUrl = canvas.toDataURL(mimeType, quality);
   triggerDownload(dataUrl, `output.${ext}`);
 }
+async function saveRasterFromVector(svgString, width, height, format = "png", quality = 0.92) {
+  const canvas = await svgToCanvas(svgString, width, height);
+  saveRaster(canvas, format, quality);
+}
+async function copyRasterFromVector(svgString, width, height) {
+  const canvas = await svgToCanvas(svgString, width, height);
+  return copyRaster(canvas);
+}
+async function shareFromVector(svgString, width, height) {
+  const canvas = await svgToCanvas(svgString, width, height);
+  return share(canvas);
+}
 function saveVector(svgString) {
   const blob = new Blob([svgString], { type: "image/svg+xml" });
   const url = URL.createObjectURL(blob);
@@ -91,19 +137,23 @@ async function share(canvas) {
 }
 
 // src/index.ts
-import { Triangle, Rectangle, Ellipse, Square, Hexagon, Smiley, stepPerf } from "@slithy/prim-lib";
+import { Triangle, Rectangle, Ellipse, Square, Hexagon, Glyph, stepPerf, replayOutput } from "@slithy/prim-lib";
 export {
   Ellipse,
+  Glyph,
   Hexagon,
   Rectangle,
-  Smiley,
   Square,
   Triangle,
   copyRaster,
+  copyRasterFromVector,
   copyVector,
+  replayOutput,
   run,
   saveRaster,
+  saveRasterFromVector,
   saveVector,
   share,
+  shareFromVector,
   stepPerf
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slithy/prim-interface",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Browser-facing API for primitive-based image reconstruction.",
   "type": "module",
   "exports": {
@@ -14,7 +14,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@slithy/prim-lib": "0.1.1"
+    "@slithy/prim-lib": "0.2.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0",
@@ -22,8 +22,8 @@
     "tsup": "^8",
     "typescript": "^5",
     "vitest": "^4",
-    "@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",