@slithy/prim-interface

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.

Exports

run(source, config, callbacks)

Starts a reconstruction job. Returns a JobHandle for stopping, pausing, and resuming.

const job = run(imageUrl, config, {
  onStart(raster, svg) {},
  onStep({ raster, svg, svgString, stepData, progress }) {},
  onComplete(serialized) {},
  onStop() {},
});

job.stop();
job.pause();
job.resume();

Config

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, 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[]
  shapeWeights?: number[]  // per-shape selection weights (same length as shapeTypes)
  fill: 'auto' | string
}

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.

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.

onStep(result) — called after each accepted shape:

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

Higher-level (rasterize SVG at save time for crisp output):

• 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, 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?, 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, options?) — shares via Web Share API if available

SaveOptions controls download filenames, formatted as ${filename}--${suffix}.${ext}:

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.

const { raster, svg, svgString } = replayOutput(serializedData);

Re-exports from prim-lib

Triangle, Rectangle, Ellipse, Circle, Square, Hexagon, Glyph, stepPerf, replayOutput, RGB, SerializedOutput, StepData, ReplayResult