@slithy/prim-lib 0.7.0 → 0.8.1

package/README.md

@@ -2,6 +2,15 @@
 
 Core engine for primitive-based image reconstruction. Consumed by `@slithy/prim-interface`.
 
+## License
+
+This package is dual-licensed.
+
+- Public use is licensed under `PolyForm-Noncommercial-1.0.0` in [LICENSE](./LICENSE).
+- Separate commercial use rights, if any, are granted only by a separate written commercial license. The current repo-tracked commercial grant is in [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md).
+
+This package also includes upstream MIT attributions for `primitive` and `primitive.js` in its `LICENSE` file.
+
 ## What it does
 
 Reconstructs an image by iteratively placing geometric shapes. Each step evaluates candidate shapes, mutates them, picks the one that most reduces the difference from the target, and draws it onto the working canvas.
@@ -24,10 +33,13 @@ Fixed shapes (class constructors, pass directly in `shapeTypes`):
 Configurable shapes (factory functions that return a constructor):
 
 - **`makeNGon(opts)`** — N-sided polygon; supports regular and irregular modes
-- **`makeRect(opts)`** — axis-aligned or rotatable rectangle with independent width/height control
+- **`makeRect(opts?)`** — axis-aligned or rotatable rectangle with independent width/height control
+- **`makeCircle(opts?)`** — circle with configurable size range and pixel-area constraints
+- **`makeEllipse(opts?)`** — ellipse with independent rx/ry ranges and optional aspect ratio lock
+- **`makeGlyph(opts?)`** — Unicode character shape; measures glyph bounds at render time and serializes as SVG `<text>`
 
 ```ts
-shapeTypes: [Triangle, makeNGon({ sides: 6, regular: true }), makeRect({ aspectRatio: 1.78 })]
+shapeTypes: [Triangle, makeNGon({ sides: 6, regular: true }), makeCircle({ sizeRange: [5, 20] })]
 ```
 
 ### Factory options
@@ -46,6 +58,14 @@ interface NGonOptions {
   sizeRange?: [number, number] // vertex radius range in compute-space px (default: [1, 20])
                                // regular: radius from center; irregular: scatter radius from first point
   mutationScale?: number      // max mutation step size in px (default: 20)
+  // pixel-area constraints (see Pixel-area constraints)
+  tonalRange?: [number, number]
+  invertTonal?: boolean
+  saturationRange?: [number, number]
+  invertSaturation?: boolean
+  hueCenter?: number
+  hueTolerance?: number
+  invertHue?: boolean
 }
 ```
 
@@ -60,9 +80,91 @@ interface RectOptions {
                                   // e.g. 1.78 for 16:9, 1.33 for 4:3, 1.0 for square
   rotatable?: boolean             // random rotation per instance (default: false)
   mutationScale?: number          // max mutation step size in px (default: 20)
+  // pixel-area constraints (see Pixel-area constraints)
+  tonalRange?: [number, number]
+  invertTonal?: boolean
+  saturationRange?: [number, number]
+  invertSaturation?: boolean
+  hueCenter?: number
+  hueTolerance?: number
+  invertHue?: boolean
+}
+```
+
+**`CircleOptions`**
+
+```ts
+interface CircleOptions {
+  sizeRange?: [number, number]    // radius range in compute-space px (default: [1, 20])
+  mutationScale?: number          // max mutation step size in px (default: 20)
+  // pixel-area constraints (see Pixel-area constraints)
+  tonalRange?: [number, number]
+  invertTonal?: boolean
+  saturationRange?: [number, number]
+  invertSaturation?: boolean
+  hueCenter?: number
+  hueTolerance?: number
+  invertHue?: boolean
 }
 ```
 
+**`EllipseOptions`**
+
+```ts
+interface EllipseOptions {
+  rxRange?: [number, number]      // x-radius range in compute-space px (default: [1, 20])
+  ryRange?: [number, number]      // y-radius range in compute-space px (default: [1, 20])
+                                  // ignored when aspectRatio is set
+  aspectRatio?: number            // rx ÷ ry; locks proportions, derives ry from rx
+  mutationScale?: number          // max mutation step size in px (default: 20)
+  // pixel-area constraints (see Pixel-area constraints)
+  tonalRange?: [number, number]
+  invertTonal?: boolean
+  saturationRange?: [number, number]
+  invertSaturation?: boolean
+  hueCenter?: number
+  hueTolerance?: number
+  invertHue?: boolean
+}
+```
+
+**`GlyphOptions`**
+
+```ts
+interface GlyphOptions {
+  char?: string                   // Unicode character (default: '☺')
+  fontFamily?: string             // CSS font-family string (default: 'sans-serif')
+  sizeRange?: [number, number]    // font-size range in compute-space px (default: [10, 30])
+  mutationScale?: number          // max mutation step size in px (default: 20)
+  // pixel-area constraints (see Pixel-area constraints)
+  tonalRange?: [number, number]
+  invertTonal?: boolean
+  saturationRange?: [number, number]
+  invertSaturation?: boolean
+  hueCenter?: number
+  hueTolerance?: number
+  invertHue?: boolean
+}
+```
+
+### Pixel-area constraints
+
+All factory shapes (`makeNGon`, `makeRect`, `makeCircle`, `makeEllipse`, `makeGlyph`) accept optional pixel-area constraint fields. Before rasterizing, the optimizer samples the pixels the shape would cover in the target image. If the area fails any active check, the shape is discarded without consuming the step budget. Shapes placed entirely outside the image bounds skip all checks.
+
+**`tonalRange: [min, max]`** — BT.601 luma (0–255). Discard if the covered area's average luminance falls outside `[min, max]`. Set `invertTonal: true` to keep shapes *outside* the range instead.
+
+**`saturationRange: [min, max]`** — HSL saturation (0–100). Discard if average saturation falls outside `[min, max]`. Set `invertSaturation: true` to invert.
+
+**`hueCenter` / `hueTolerance`** — center hue (0–360°) and allowed angular deviation in degrees. Discard if the covered area's average hue differs from `hueCenter` by more than `hueTolerance`. Set `invertHue: true` to invert. Both fields must be set together to activate the hue check.
+
+```ts
+// circles only in bright areas; glyphs only in desaturated areas
+shapeTypes: [
+  makeCircle({ sizeRange: [5, 20], tonalRange: [180, 255] }),
+  makeGlyph({ char: '·', saturationRange: [0, 20] }),
+]
+```
+
 ### Types
 
 **`Cfg`** — runtime config (all fields required):
@@ -167,4 +269,4 @@ interface ReplayResult {
 - When `shapeWeights` is provided (same length as `shapeTypes`), `Optimizer` builds a step plan at construction time: each shape type is allocated an exact number of slots proportional to its weight (using largest-remainder rounding), then the plan is Fisher-Yates shuffled. This guarantees the final shape distribution matches the weights, rather than just biasing random selection
 - `PreCfg` exists to bridge the gap between call time (dimensions unknown) and runtime (dimensions set by `Canvas.original()` or `Canvas.fromBitmap()`)
 - `Canvas.svgRoot()` is a static helper shared by `Canvas.empty()` and `replayOutput()` to create the SVG root with clip path and background fill; it uses DOM APIs and is main-thread only
-- Factory shapes (`makeNGon`, `makeRect`) capture their options in a closure and return an inner class. The class carries a static `_shapeSpec` property (`{ f: string, o: opts }`) used by `runWorker` to serialize and reconstruct the factory call inside the worker
+- Factory shapes (`makeNGon`, `makeRect`, `makeCircle`, `makeEllipse`, `makeGlyph`) capture their options in a closure and return an inner class. The class carries a static `_shapeSpec` property (`{ f: string, o: opts }`) used by `runWorker` to serialize and reconstruct the factory call inside the worker

package/dist/index.d.ts

@@ -24,9 +24,12 @@ interface ShapeImageData {
 interface ShapeInterface {
     bbox: Bbox;
     tonalRange?: [number, number];
+    invertTonal?: boolean;
     saturationRange?: [number, number];
+    invertSaturation?: boolean;
     hueCenter?: number;
     hueTolerance?: number;
+    invertHue?: boolean;
     /** cfg is rarely used by implementations; accepts Partial to keep call sites flexible. */
     mutate(cfg?: Partial<Cfg>): ShapeInterface;
     toSVG(): SVGElement | undefined;
@@ -310,9 +313,12 @@ interface NGonOptions {
     sizeRange?: [number, number];
     mutationScale?: number;
     tonalRange?: [number, number];
+    invertTonal?: boolean;
     saturationRange?: [number, number];
+    invertSaturation?: boolean;
     hueCenter?: number;
     hueTolerance?: number;
+    invertHue?: boolean;
 }
 declare function makeNGon(opts: NGonOptions): new (w: number, h: number) => ShapeInterface;
 interface RectOptions {
@@ -322,18 +328,24 @@ interface RectOptions {
     rotatable?: boolean;
     mutationScale?: number;
     tonalRange?: [number, number];
+    invertTonal?: boolean;
     saturationRange?: [number, number];
+    invertSaturation?: boolean;
     hueCenter?: number;
     hueTolerance?: number;
+    invertHue?: boolean;
 }
 declare function makeRect(opts?: Partial<RectOptions>): new (w: number, h: number) => ShapeInterface;
 interface CircleOptions {
     sizeRange?: [number, number];
     mutationScale?: number;
     tonalRange?: [number, number];
+    invertTonal?: boolean;
     saturationRange?: [number, number];
+    invertSaturation?: boolean;
     hueCenter?: number;
     hueTolerance?: number;
+    invertHue?: boolean;
 }
 declare function makeCircle(opts?: Partial<CircleOptions>): new (w: number, h: number) => ShapeInterface;
 interface EllipseOptions {
@@ -342,9 +354,12 @@ interface EllipseOptions {
     aspectRatio?: number;
     mutationScale?: number;
     tonalRange?: [number, number];
+    invertTonal?: boolean;
     saturationRange?: [number, number];
+    invertSaturation?: boolean;
     hueCenter?: number;
     hueTolerance?: number;
+    invertHue?: boolean;
 }
 declare function makeEllipse(opts?: Partial<EllipseOptions>): new (w: number, h: number) => ShapeInterface;
 interface GlyphOptions {
@@ -353,9 +368,12 @@ interface GlyphOptions {
     sizeRange?: [number, number];
     mutationScale?: number;
     tonalRange?: [number, number];
+    invertTonal?: boolean;
     saturationRange?: [number, number];
+    invertSaturation?: boolean;
     hueCenter?: number;
     hueTolerance?: number;
+    invertHue?: boolean;
 }
 declare function makeGlyph(opts?: Partial<GlyphOptions>): new (w: number, h: number) => ShapeInterface;
 declare class Debug extends Shape {

package/dist/index.js

@@ -382,7 +382,7 @@ var Step = class _Step {
   compute(state) {
     const pixels = state.canvas.node.width * state.canvas.node.height;
     const offset = this.shape.bbox;
-    const { tonalRange, saturationRange, hueCenter, hueTolerance } = this.shape;
+    const { tonalRange, invertTonal, saturationRange, invertSaturation, hueCenter, hueTolerance, invertHue } = this.shape;
     if (tonalRange || saturationRange || hueCenter !== void 0 && hueTolerance !== void 0) {
       const { left, top, width, height } = offset;
       const targetData = state.target.getImageData();
@@ -405,20 +405,25 @@ var Step = class _Step {
       if (count > 0) {
         if (tonalRange) {
           const luma = (0.299 * rSum + 0.587 * gSum + 0.114 * bSum) / count;
-          if (luma < tonalRange[0] || luma > tonalRange[1]) {
+          const inRange = luma >= tonalRange[0] && luma <= tonalRange[1];
+          if (invertTonal ? inRange : !inRange) {
             this.distance = Infinity;
             return Promise.resolve(this);
           }
         }
         if (saturationRange || hueCenter !== void 0 && hueTolerance !== void 0) {
           const [h, s] = rgbToHsl(rSum / count, gSum / count, bSum / count);
-          if (saturationRange && (s < saturationRange[0] || s > saturationRange[1])) {
-            this.distance = Infinity;
-            return Promise.resolve(this);
+          if (saturationRange) {
+            const inRange = s >= saturationRange[0] && s <= saturationRange[1];
+            if (invertSaturation ? inRange : !inRange) {
+              this.distance = Infinity;
+              return Promise.resolve(this);
+            }
           }
           if (hueCenter !== void 0 && hueTolerance !== void 0) {
             const diff = Math.abs((h - hueCenter + 180 + 360) % 360 - 180);
-            if (diff > hueTolerance) {
+            const inRange = diff <= hueTolerance;
+            if (invertHue ? inRange : !inRange) {
               this.distance = Infinity;
               return Promise.resolve(this);
             }
@@ -1026,12 +1031,15 @@ function makeNGon(opts) {
       static {
         __name(this, "NGonRegular");
       }
-      static _ngonOpts = { sides, regular: true, rotatable, noise, sizeRange, mutationScale, startAngle, tonalRange: opts.tonalRange, saturationRange: opts.saturationRange, hueCenter: opts.hueCenter, hueTolerance: opts.hueTolerance };
+      static _ngonOpts = { sides, regular: true, rotatable, noise, sizeRange, mutationScale, startAngle, tonalRange: opts.tonalRange, invertTonal: opts.invertTonal, saturationRange: opts.saturationRange, invertSaturation: opts.invertSaturation, hueCenter: opts.hueCenter, hueTolerance: opts.hueTolerance, invertHue: opts.invertHue };
       static _shapeSpec = { f: "ngon", o: NGonRegular._ngonOpts };
       tonalRange;
+      invertTonal;
       saturationRange;
+      invertSaturation;
       hueCenter;
       hueTolerance;
+      invertHue;
       center;
       r;
       angle;
@@ -1040,9 +1048,12 @@ function makeNGon(opts) {
       constructor(w, h) {
         super(w, h);
         this.tonalRange = opts.tonalRange;
+        this.invertTonal = opts.invertTonal;
         this.saturationRange = opts.saturationRange;
+        this.invertSaturation = opts.invertSaturation;
         this.hueCenter = opts.hueCenter;
         this.hueTolerance = opts.hueTolerance;
+        this.invertHue = opts.invertHue;
         this.center = Shape.randomPoint(w, h);
         this.r = Math.max(1, sizeRange[0] + ~~(Math.random() * (sizeRange[1] - sizeRange[0])));
         this.angle = rotatable ? Math.random() * (2 * Math.PI / sides) : startAngle;
@@ -1138,19 +1149,25 @@ function makeNGon(opts) {
       static {
         __name(this, "NGonIrregular");
       }
-      static _ngonOpts = { sides, regular: false, convex, sizeRange, mutationScale, tonalRange: opts.tonalRange, saturationRange: opts.saturationRange, hueCenter: opts.hueCenter, hueTolerance: opts.hueTolerance };
+      static _ngonOpts = { sides, regular: false, convex, sizeRange, mutationScale, tonalRange: opts.tonalRange, invertTonal: opts.invertTonal, saturationRange: opts.saturationRange, invertSaturation: opts.invertSaturation, hueCenter: opts.hueCenter, hueTolerance: opts.hueTolerance, invertHue: opts.invertHue };
       static _shapeSpec = { f: "ngon", o: NGonIrregular._ngonOpts };
       tonalRange;
+      invertTonal;
       saturationRange;
+      invertSaturation;
       hueCenter;
       hueTolerance;
+      invertHue;
       points;
       constructor(w, h) {
         super(w, h);
         this.tonalRange = opts.tonalRange;
+        this.invertTonal = opts.invertTonal;
         this.saturationRange = opts.saturationRange;
+        this.invertSaturation = opts.invertSaturation;
         this.hueCenter = opts.hueCenter;
         this.hueTolerance = opts.hueTolerance;
+        this.invertHue = opts.invertHue;
         const first = Shape.randomPoint(w, h);
         this.points = [first];
         for (let i = 1; i < sides; i++) {
@@ -1222,12 +1239,15 @@ function makeRect(opts) {
     static {
       __name(this, "Rect");
     }
-    static _rectOpts = { widthRange, heightRange, aspectRatio, rotatable, mutationScale, tonalRange: opts?.tonalRange, saturationRange: opts?.saturationRange, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance };
+    static _rectOpts = { widthRange, heightRange, aspectRatio, rotatable, mutationScale, tonalRange: opts?.tonalRange, invertTonal: opts?.invertTonal, saturationRange: opts?.saturationRange, invertSaturation: opts?.invertSaturation, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance, invertHue: opts?.invertHue };
     static _shapeSpec = { f: "rect", o: Rect._rectOpts };
     tonalRange;
+    invertTonal;
     saturationRange;
+    invertSaturation;
     hueCenter;
     hueTolerance;
+    invertHue;
     center;
     hw;
     hh;
@@ -1235,9 +1255,12 @@ function makeRect(opts) {
     constructor(w, h) {
       super(w, h);
       this.tonalRange = opts?.tonalRange;
+      this.invertTonal = opts?.invertTonal;
       this.saturationRange = opts?.saturationRange;
+      this.invertSaturation = opts?.invertSaturation;
       this.hueCenter = opts?.hueCenter;
       this.hueTolerance = opts?.hueTolerance;
+      this.invertHue = opts?.invertHue;
       this.center = Shape.randomPoint(w, h);
       this.hw = widthRange[0] + ~~(Math.random() * (widthRange[1] - widthRange[0]));
       if (aspectRatio !== void 0) {
@@ -1350,20 +1373,26 @@ function makeCircle(opts) {
     static {
       __name(this, "MadeCircle");
     }
-    static _circleOpts = { sizeRange, mutationScale, tonalRange: opts?.tonalRange, saturationRange: opts?.saturationRange, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance };
+    static _circleOpts = { sizeRange, mutationScale, tonalRange: opts?.tonalRange, invertTonal: opts?.invertTonal, saturationRange: opts?.saturationRange, invertSaturation: opts?.invertSaturation, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance, invertHue: opts?.invertHue };
     static _shapeSpec = { f: "circle", o: MadeCircle._circleOpts };
     tonalRange;
+    invertTonal;
     saturationRange;
+    invertSaturation;
     hueCenter;
     hueTolerance;
+    invertHue;
     center;
     r;
     constructor(w, h) {
       super(w, h);
       this.tonalRange = opts?.tonalRange;
+      this.invertTonal = opts?.invertTonal;
       this.saturationRange = opts?.saturationRange;
+      this.invertSaturation = opts?.invertSaturation;
       this.hueCenter = opts?.hueCenter;
       this.hueTolerance = opts?.hueTolerance;
+      this.invertHue = opts?.invertHue;
       this.center = Shape.randomPoint(w, h);
       this.r = Math.max(1, sizeRange[0] + ~~(Math.random() * (sizeRange[1] - sizeRange[0])));
       this.computeBbox();
@@ -1424,21 +1453,27 @@ function makeEllipse(opts) {
     static {
       __name(this, "MadeEllipse");
     }
-    static _ellipseOpts = { rxRange, ryRange, aspectRatio, mutationScale, tonalRange: opts?.tonalRange, saturationRange: opts?.saturationRange, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance };
+    static _ellipseOpts = { rxRange, ryRange, aspectRatio, mutationScale, tonalRange: opts?.tonalRange, invertTonal: opts?.invertTonal, saturationRange: opts?.saturationRange, invertSaturation: opts?.invertSaturation, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance, invertHue: opts?.invertHue };
     static _shapeSpec = { f: "ellipse", o: MadeEllipse._ellipseOpts };
     tonalRange;
+    invertTonal;
     saturationRange;
+    invertSaturation;
     hueCenter;
     hueTolerance;
+    invertHue;
     center;
     rx;
     ry;
     constructor(w, h) {
       super(w, h);
       this.tonalRange = opts?.tonalRange;
+      this.invertTonal = opts?.invertTonal;
       this.saturationRange = opts?.saturationRange;
+      this.invertSaturation = opts?.invertSaturation;
       this.hueCenter = opts?.hueCenter;
       this.hueTolerance = opts?.hueTolerance;
+      this.invertHue = opts?.invertHue;
       this.center = Shape.randomPoint(w, h);
       this.rx = Math.max(1, rxRange[0] + ~~(Math.random() * (rxRange[1] - rxRange[0])));
       this.ry = aspectRatio !== void 0 ? Math.max(1, Math.round(this.rx / aspectRatio)) : Math.max(1, ryRange[0] + ~~(Math.random() * (ryRange[1] - ryRange[0])));
@@ -1510,20 +1545,26 @@ function makeGlyph(opts) {
     static {
       __name(this, "MadeGlyph");
     }
-    static _glyphOpts = { char, fontFamily, sizeRange, mutationScale, tonalRange: opts?.tonalRange, saturationRange: opts?.saturationRange, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance };
+    static _glyphOpts = { char, fontFamily, sizeRange, mutationScale, tonalRange: opts?.tonalRange, invertTonal: opts?.invertTonal, saturationRange: opts?.saturationRange, invertSaturation: opts?.invertSaturation, hueCenter: opts?.hueCenter, hueTolerance: opts?.hueTolerance, invertHue: opts?.invertHue };
     static _shapeSpec = { f: "glyph", o: MadeGlyph._glyphOpts };
     tonalRange;
+    invertTonal;
     saturationRange;
+    invertSaturation;
     hueCenter;
     hueTolerance;
+    invertHue;
     center;
     fontSize;
     constructor(w, h) {
       super(w, h);
       this.tonalRange = opts?.tonalRange;
+      this.invertTonal = opts?.invertTonal;
       this.saturationRange = opts?.saturationRange;
+      this.invertSaturation = opts?.invertSaturation;
       this.hueCenter = opts?.hueCenter;
       this.hueTolerance = opts?.hueTolerance;
+      this.invertHue = opts?.invertHue;
       this.center = Shape.randomPoint(w, h);
       this.fontSize = Math.max(sizeRange[0], sizeRange[0] + ~~(Math.random() * (sizeRange[1] - sizeRange[0])));
       this.computeBbox();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slithy/prim-lib",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Core engine for primitive-based image reconstruction.",
   "type": "module",
   "exports": {
@@ -14,11 +14,11 @@
   ],
   "sideEffects": false,
   "devDependencies": {
-    "@vitest/coverage-v8": "^4.1.2",
-    "jsdom": "^29.0.1",
+    "@vitest/coverage-v8": "^4.1.7",
+    "jsdom": "^29.1.1",
     "tsup": "^8",
     "typescript": "^5",
-    "vitest": "^4.1.2",
+    "vitest": "^4.1.7",
     "@slithy/eslint-config": "0.0.0",
     "@slithy/tsconfig": "0.0.0"
   },