@slithy/prim-interface 0.2.6 → 0.2.7

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,18 +78,29 @@ 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
 
 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
 
+**`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`
 
 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.
@@ -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 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>;
 
-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,15 +102,15 @@ 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);
@@ -115,10 +120,10 @@ async function shareFromVector(svgString, width, height) {
   const canvas = await svgToCanvas(svgString, width, height);
   return share(canvas);
 }
-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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slithy/prim-interface",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Browser-facing API for primitive-based image reconstruction.",
   "type": "module",
   "exports": {