@slithy/prim-interface 0.2.6 → 0.2.8

package/README.md

@@ -39,6 +39,7 @@ interface Config {
   allowUpscale?: boolean // allow output larger than source image (default: false)
   pixelRatio?: number    // device pixel ratio for the raster canvas (default: 1)
   shapeTypes: ShapeConstructor[]
+  shapeWeights?: number[]  // per-shape selection weights (same length as shapeTypes)
   fill: 'auto' | string
 }
 ```
@@ -49,6 +50,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.
 
+**`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
 
 **`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.
@@ -75,17 +78,28 @@ interface StepResult {
 
 Higher-level (rasterize SVG at save time for crisp output):
 
-- **`saveRasterFromVector(svgString, width, height, format?, quality?)`** — downloads PNG or JPEG rasterized from the SVG
+- **`saveRasterFromVector(svgString, width, height, format?, quality?, options?)`** — 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
+- **`shareFromVector(svgString, width, height, options?)`** — 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
+- **`saveRaster(canvas, format?, quality?, options?)`** — downloads PNG or JPEG from a canvas
+- **`saveVector(svgString, options?)`** — downloads SVG
 - **`copyRaster(canvas)`** — copies PNG to clipboard
 - **`copyVector(svgString)`** — copies SVG markup to clipboard
-- **`share(canvas)`** — shares via Web Share API if available
+- **`share(canvas, options?)`** — shares via Web Share API if available
+
+**`SaveOptions`** controls download filenames, formatted as `${filename}--${suffix}.${ext}`:
+
+```ts
+interface SaveOptions {
+  suffix?: string    // default: 'prim'
+  filename?: string  // stem without extension, default: 'output'
+}
+```
+
+Example: `saveRaster(canvas, 'png', 0.92, { filename: 'mountains', suffix: 'v2' })` → `mountains--v2.png`
 
 ### `replayOutput(data: SerializedOutput): ReplayResult`
 
@@ -97,4 +111,4 @@ const { raster, svg, svgString } = replayOutput(serializedData);
 
 ### Re-exports from prim-lib
 
-`Triangle`, `Rectangle`, `Ellipse`, `Square`, `Hexagon`, `Glyph`, `stepPerf`, `replayOutput`, `RGB`, `SerializedOutput`, `StepData`, `ReplayResult`
+`Triangle`, `Rectangle`, `Ellipse`, `Circle`, `Square`, `Hexagon`, `Glyph`, `stepPerf`, `replayOutput`, `RGB`, `SerializedOutput`, `StepData`, `ReplayResult`

package/dist/index.d.ts

@@ -43,13 +43,17 @@ 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>;
+interface SaveOptions {
+    suffix?: string;
+    filename?: string;
+}
+declare function saveRaster(canvas: HTMLCanvasElement, format?: 'png' | 'jpeg', quality?: number, options?: SaveOptions): void;
+declare function saveRasterFromVector(svgString: string, width: number, height: number, format?: 'png' | 'jpeg', quality?: number, options?: SaveOptions): 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 shareFromVector(svgString: string, width: number, height: number, options?: SaveOptions): Promise<void>;
+declare function saveVector(svgString: string, options?: SaveOptions): void;
 declare function copyVector(svgString: string): Promise<void>;
 declare function copyRaster(canvas: HTMLCanvasElement): Promise<void>;
-declare function share(canvas: HTMLCanvasElement): Promise<void>;
+declare function share(canvas: HTMLCanvasElement, options?: SaveOptions): Promise<void>;
 
-export { type Config, type JobHandle, type RunCallbacks, 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, saveRaster, saveRasterFromVector, saveVector, share, shareFromVector };

package/dist/index.js

@@ -70,6 +70,11 @@ function run(source, cfg, callbacks = {}) {
 }
 
 // src/exit.ts
+function buildFilename(ext, options) {
+  const suffix = options?.suffix ?? "prim";
+  const name = options?.filename ?? "output";
+  return `${name}--${suffix}.${ext}`;
+}
 function triggerDownload(url, filename) {
   const a = document.createElement("a");
   a.href = url;
@@ -97,28 +102,28 @@ function svgToCanvas(svgString, width, height) {
     img.src = url;
   });
 }
-function saveRaster(canvas, format = "png", quality = 0.92) {
+function saveRaster(canvas, format = "png", quality = 0.92, options) {
   const mimeType = format === "jpeg" ? "image/jpeg" : "image/png";
   const ext = format === "jpeg" ? "jpg" : "png";
   const dataUrl = canvas.toDataURL(mimeType, quality);
-  triggerDownload(dataUrl, `output.${ext}`);
+  triggerDownload(dataUrl, buildFilename(ext, options));
 }
-async function saveRasterFromVector(svgString, width, height, format = "png", quality = 0.92) {
+async function saveRasterFromVector(svgString, width, height, format = "png", quality = 0.92, options) {
   const canvas = await svgToCanvas(svgString, width, height);
-  saveRaster(canvas, format, quality);
+  saveRaster(canvas, format, quality, options);
 }
 async function copyRasterFromVector(svgString, width, height) {
   const canvas = await svgToCanvas(svgString, width, height);
   return copyRaster(canvas);
 }
-async function shareFromVector(svgString, width, height) {
+async function shareFromVector(svgString, width, height, options) {
   const canvas = await svgToCanvas(svgString, width, height);
-  return share(canvas);
+  return share(canvas, options);
 }
-function saveVector(svgString) {
+function saveVector(svgString, options) {
   const blob = new Blob([svgString], { type: "image/svg+xml" });
   const url = URL.createObjectURL(blob);
-  triggerDownload(url, "output.svg");
+  triggerDownload(url, buildFilename("svg", options));
   URL.revokeObjectURL(url);
 }
 async function copyVector(svgString) {
@@ -128,9 +133,9 @@ async function copyRaster(canvas) {
   const blob = await new Promise((resolve, reject) => canvas.toBlob((b) => b ? resolve(b) : reject(new Error("toBlob failed"))));
   await navigator.clipboard.write([new ClipboardItem({ "image/png": blob })]);
 }
-async function share(canvas) {
+async function share(canvas, options) {
   const blob = await new Promise((resolve, reject) => canvas.toBlob((b) => b ? resolve(b) : reject(new Error("toBlob failed"))));
-  const file = new File([blob], "output.png", { type: "image/png" });
+  const file = new File([blob], buildFilename("png", options), { type: "image/png" });
   if (navigator.canShare({ files: [file] })) {
     await navigator.share({ files: [file] });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slithy/prim-interface",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Browser-facing API for primitive-based image reconstruction.",
   "type": "module",
   "exports": {
@@ -22,8 +22,8 @@
     "tsup": "^8",
     "typescript": "^5",
     "vitest": "^4",
-    "@slithy/eslint-config": "0.0.0",
-    "@slithy/tsconfig": "0.0.0"
+    "@slithy/tsconfig": "0.0.0",
+    "@slithy/eslint-config": "0.0.0"
   },
   "author": {
     "name": "Matthew Campagna",