@slithy/prim-lib 0.8.2 → 0.9.1

package/LICENSE-COMMERCIAL.md

@@ -4,11 +4,11 @@ Copyright Matthew Campagna
 
 1. Grant
 
-Matthew Campagna grants Matthew Campagna a personal, non-transferable, non-sublicensable license to use, reproduce, modify, distribute, and commercially exploit `@slithy/prim-lib` as part of software products and related internal development activities.
+The individual copyright owner of `@slithy/prim-lib`, currently Matthew Campagna, is granted a personal, non-transferable, non-sublicensable license to use, reproduce, modify, distribute, and commercially exploit `@slithy/prim-lib` as part of software products and related internal development activities.
 
 2. Scope
 
-This commercial license applies only to Matthew Campagna in his personal capacity. It does not extend to any employer, client, contractor, affiliate, assignee, or other third party.
+This commercial license applies only to the natural person who is the individual copyright owner of `@slithy/prim-lib` at the time of use, in that person's personal capacity. It does not extend to any employer, client, contractor, affiliate, assignee, or other third party.
 
 3. Public License Unchanged
 

package/dist/index.d.ts

@@ -30,8 +30,7 @@ interface ShapeInterface {
     hueCenter?: number;
     hueTolerance?: number;
     invertHue?: boolean;
-    /** cfg is rarely used by implementations; accepts Partial to keep call sites flexible. */
-    mutate(cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
     toSVG(): SVGElement | undefined;
     toData(alpha: number, color: RGB): StepData;
     rasterize(alpha: number): {
@@ -46,10 +45,14 @@ interface Cfg {
     mutateAlpha: boolean;
     shapeTypes: Array<new (w: number, h: number) => ShapeInterface>;
     shapeWeights?: number[];
+    /** Number of candidate shapes to generate and score per step. Also reused as the
+     *  rejection-streak retry limit in Optimizer._addShape() — how many consecutive
+     *  fully-rejected candidates (e.g. from tonal/hue/saturation constraints) to
+     *  tolerate before consuming a step from the budget anyway. */
     shapes: number;
     mutations: number;
     steps: number;
-    fill: 'auto' | string;
+    fill: 'auto' | (string & {});
     outputFill?: string;
     computeSize: number;
     viewSize: number;
@@ -119,6 +122,7 @@ type StepData = {
     cy: number;
     fs: number;
     text: string;
+    fontFamily?: string;
 } | {
     t: 'rc';
     a: number;
@@ -141,9 +145,7 @@ interface SerializedOutput {
 interface DrawableStep {
     alpha: number;
     color: string;
-    shape: {
-        render(ctx: Ctx2D): void;
-    };
+    shape: Pick<ShapeInterface, 'bbox' | 'rasterize' | 'render'>;
 }
 declare class Canvas {
     node: HTMLCanvasElement | OffscreenCanvas;
@@ -161,6 +163,7 @@ declare class Canvas {
     getImageData(): ImageDataLike;
     difference(otherCanvas: Canvas): number;
     distance(otherCanvas: Canvas): number;
+    private patchImageData;
     drawStep(step: DrawableStep): this;
 }
 
@@ -196,6 +199,7 @@ declare class Optimizer {
     cfg: Cfg;
     state: State;
     onStep: (step: Step | null) => void;
+    onError: (error: unknown) => void;
     _steps: number;
     _stopped: boolean;
     _paused: boolean;
@@ -218,21 +222,22 @@ declare class Shape implements ShapeInterface {
     static randomPoint(width: number, height: number): Point;
     static create(cfg: Cfg): ShapeInterface;
     constructor(_w: number, _h: number);
-    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
     toSVG(): SVGElement | undefined;
     toData(_alpha: number, _color: RGB): StepData;
     rasterize(alpha: number): {
         getImageData(): ImageDataLike;
     };
+    protected setBbox(tight: Bbox): this;
     render(_ctx: Ctx2D): void;
 }
 declare class Polygon extends Shape {
     points: Point[];
     constructor(w: number, h: number, count?: number);
     protected _cloneEmpty(): Polygon;
-    render(ctx: CanvasRenderingContext2D): void;
+    render(ctx: Ctx2D): void;
     toSVG(): SVGElement;
-    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
     computeBbox(): this;
     _createPoints(w: number, h: number, count: number): Point[];
 }
@@ -245,7 +250,7 @@ declare class Rectangle extends Polygon {
     constructor(w: number, h: number);
     protected _cloneEmpty(): Rectangle;
     toData(a: number, c: RGB): StepData;
-    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
     _createPoints(w: number, h: number, _count: number): Point[];
 }
 declare class Ellipse extends Shape {
@@ -253,10 +258,10 @@ declare class Ellipse extends Shape {
     rx: number;
     ry: number;
     constructor(w: number, h: number);
-    render(ctx: CanvasRenderingContext2D): void;
+    render(ctx: Ctx2D): void;
     toSVG(): SVGElement;
     toData(a: number, c: RGB): StepData;
-    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
     computeBbox(): this;
 }
 declare class Circle extends Shape {
@@ -264,10 +269,10 @@ declare class Circle extends Shape {
     r: number;
     constructor(w: number, h: number);
     computeBbox(): this;
-    render(ctx: CanvasRenderingContext2D): void;
+    render(ctx: Ctx2D): void;
     toSVG(): SVGElement;
     toData(a: number, c: RGB): StepData;
-    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
 }
 declare class Glyph extends Shape {
     center: Point;
@@ -275,8 +280,8 @@ declare class Glyph extends Shape {
     fontSize: number;
     constructor(w: number, h: number, text?: string);
     computeBbox(): this;
-    render(ctx: CanvasRenderingContext2D): void;
-    mutate(_cfg?: Partial<Cfg>): Glyph;
+    render(ctx: Ctx2D): void;
+    mutate(): Glyph;
     toSVG(): SVGElement;
     toData(a: number, c: RGB): StepData;
 }
@@ -285,10 +290,10 @@ declare class Square extends Shape {
     r: number;
     constructor(w: number, h: number);
     computeBbox(): this;
-    render(ctx: CanvasRenderingContext2D): void;
+    render(ctx: Ctx2D): void;
     toSVG(): SVGElement;
     toData(a: number, c: RGB): StepData;
-    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
 }
 declare class Hexagon extends Shape {
     center: Point;
@@ -298,10 +303,10 @@ declare class Hexagon extends Shape {
     constructor(w: number, h: number);
     _points(): Point[];
     computeBbox(): this;
-    render(ctx: CanvasRenderingContext2D): void;
+    render(ctx: Ctx2D): void;
     toSVG(): SVGElement;
     toData(a: number, c: RGB): StepData;
-    mutate(_cfg?: Partial<Cfg>): ShapeInterface;
+    mutate(): ShapeInterface;
 }
 interface NGonOptions {
     sides: number;
@@ -378,7 +383,7 @@ interface GlyphOptions {
 declare function makeGlyph(opts?: Partial<GlyphOptions>): new (w: number, h: number) => ShapeInterface;
 declare class Debug extends Shape {
     constructor(w: number, h: number);
-    render(ctx: CanvasRenderingContext2D): void;
+    render(ctx: Ctx2D): void;
 }
 
 declare const SVGNS = "http://www.w3.org/2000/svg";
@@ -386,6 +391,20 @@ declare function rgbToHsl(r: number, g: number, b: number): [number, number, num
 declare function parseColor(color: string): [number, number, number];
 
 declare function clamp(x: number, min: number, max: number): number;
+/** The four corners of a rotated rectangle centred at (cx, cy) with half-extents
+ *  (hw, hh) rotated by `angle` radians. Raw floats — no truncation. */
+declare function rectCorners(cx: number, cy: number, hw: number, hh: number, angle: number): [Point, Point, Point, Point];
+/** The `sides` vertices of a regular polygon centred at (cx, cy), the first at
+ *  `angle`. `radius` may be a constant or a per-index function (for noise).
+ *  Raw floats — no truncation. */
+declare function regularPolygonPoints(cx: number, cy: number, sides: number, angle: number, radius: number | ((i: number) => number)): Point[];
+/** Axis-aligned bounding box of a set of points. Degenerate zero-extent
+ *  width/height fall back to 1 (matching the per-shape computeBbox behaviour). */
+declare function bboxOfPoints(points: Point[]): Bbox;
+/** A random offset within a disc of radius `scale`, truncated to integers.
+ *  Used by shape mutations to nudge a point by a random angle + magnitude.
+ *  The `~~` truncation is intentional and behaviour-defining — do not remove. */
+declare function randomPolarOffset(scale: number): [number, number];
 declare function clampColor(x: number): number;
 declare function distanceToDifference(distance: number, pixels: number): number;
 declare function differenceToDistance(difference: number, pixels: number): number;
@@ -405,4 +424,4 @@ interface ReplayResult {
 }
 declare function replayOutput(data: SerializedOutput): ReplayResult;
 
-export { type Bbox, Canvas, type Cfg, Circle, type CircleOptions, type Ctx2D, Debug, Ellipse, type EllipseOptions, Glyph, type GlyphOptions, Hexagon, type ImageDataLike, type NGonOptions, Optimizer, type Point, type PreCfg, type RGB, type RectOptions, Rectangle, type ReplayResult, SVGNS, type SerializedOutput, Shape, type ShapeImageData, type ShapeInterface, Square, State, Step, type StepData, Triangle, clamp, clampColor, computeColorAndDifferenceChange, difference, differenceToDistance, distanceToDifference, getFill, makeCircle, makeEllipse, makeGlyph, makeNGon, makeRect, parseColor, renderStepToCtx, replayOutput, rgbToHsl, stepDataToSVGElement, stepPerf };
+export { type Bbox, Canvas, type Cfg, Circle, type CircleOptions, type Ctx2D, Debug, Ellipse, type EllipseOptions, Glyph, type GlyphOptions, Hexagon, type ImageDataLike, type NGonOptions, Optimizer, type Point, type PreCfg, type RGB, type RectOptions, Rectangle, type ReplayResult, SVGNS, type SerializedOutput, Shape, type ShapeImageData, type ShapeInterface, Square, State, Step, type StepData, Triangle, bboxOfPoints, clamp, clampColor, computeColorAndDifferenceChange, difference, differenceToDistance, distanceToDifference, getFill, makeCircle, makeEllipse, makeGlyph, makeNGon, makeRect, parseColor, randomPolarOffset, rectCorners, regularPolygonPoints, renderStepToCtx, replayOutput, rgbToHsl, stepDataToSVGElement, stepPerf };