foster-ts-shapes 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VisualFinesse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+# foster-ts-shapes
+
+> Deterministic SVG shape generation — zero dependencies, fully typed, endlessly composable.
+
+Drop in a seed and a shape list, get back a pixel-perfect SVG every time. No canvas, no DOM, no runtime deps — just TypeScript and math.
+
+---
+
+## Install
+
+```bash
+npm install foster-ts-shapes
+```
+
+---
+
+## Quick Start
+
+```ts
+import { generate } from "foster-ts-shapes";
+
+const result = generate({
+  seed: 42,
+  canvas: { width: 400, height: 400 },
+  shapes: [{ type: "circle", x: 200, y: 200, size: 100, fill: "steelblue" }],
+});
+
+console.log(result.svg); // <svg ...>...</svg>
+```
+
+Same seed → same SVG. Every time. On any machine.
+
+---
+
+## Examples
+
+![AnimatedShapes](./AnimatedShapes.gif) ![AnimatedShapes2](./AnimatedShapes2.gif)
+
+> **Note:** These animations are external visualizations created to showcase the PRNG-driven variation system — cycling through different seeds to demonstrate deterministic shape generation. `foster-ts-shapes` outputs static SVG strings only. It does not animate shapes or produce GIFs.
+
+---
+
+## Shapes
+
+Nine primitives, all sharing a common base interface:
+
+| Type        | Required fields                       |
+| ----------- | ------------------------------------- |
+| `square`    | `x, y, size`                          |
+| `rectangle` | `x, y, width, height`                 |
+| `circle`    | `x, y, size`                          |
+| `triangle`  | `x, y, size`                          |
+| `trapezoid` | `x, y, topWidth, bottomWidth, height` |
+| `octagon`   | `x, y, size`                          |
+| `polygon`   | `x, y, sides, size`                   |
+| `oval`      | `x, y, width, height`                 |
+| `blob`      | `x, y, size, points?`                 |
+
+Every shape also accepts `rotation?` (degrees).
+
+---
+
+## Features
+
+### Styling
+
+Every shape accepts fill, stroke, and opacity fields:
+
+```ts
+{
+  type: "square",
+  x: 100, y: 100, size: 80,
+  fill: "tomato",
+  stroke: "darkred",
+  strokeWidth: 3,
+  opacity: 0.85,
+}
+```
+
+### Gradients
+
+Linear and radial gradients on fill and/or stroke:
+
+```ts
+{
+  type: "circle",
+  x: 150, y: 150, size: 100,
+  fillGradient: {
+    type: "linear",
+    x1: 0, y1: 0, x2: 1, y2: 1,
+    stops: [
+      { offset: 0, color: "royalblue" },
+      { offset: 1, color: "mediumpurple" },
+    ],
+  },
+}
+```
+
+### Bezier Rounding
+
+Smooth out any shape's corners with a single field:
+
+```ts
+{
+  type: "polygon",
+  x: 200, y: 200, sides: 6, size: 100,
+  bezier: 0.4,             // 0–1: rounding amount
+  bezierDirection: "in",   // "out" (convex, default) | "in" (concave)
+}
+```
+
+### Variation / Distortion
+
+Seeded randomness that distorts vertices — great for organic, hand-drawn aesthetics:
+
+```ts
+{
+  type: "blob",
+  x: 150, y: 150, size: 100, points: 8,
+  fill: "goldenrod",
+  distort: 0.3,          // 0–1: per-vertex displacement
+  sizeVariance: 0.2,     // 0–1: overall scale jitter
+  clamp: { width: 200, height: 200 }, // keep shape within bounds
+}
+```
+
+### Layers
+
+Control z-order with `layer` — lower values render behind higher ones:
+
+```ts
+shapes: [
+  {
+    type: "circle",
+    x: 200,
+    y: 200,
+    size: 150,
+    fill: "cornflowerblue",
+    layer: 0,
+  },
+  {
+    type: "oval",
+    x: 200,
+    y: 200,
+    width: 80,
+    height: 40,
+    fill: "white",
+    layer: 1,
+  },
+];
+```
+
+### Masks
+
+Clip any shape using one or more mask shapes. Masks accept the full variation and bezier API:
+
+```ts
+// Circle clipped to a triangle window
+{
+  type: "circle",
+  x: 150, y: 150, size: 100,
+  fill: "steelblue",
+  mask: { type: "triangle", x: 150, y: 150, size: 90 },
+}
+
+// Polygon revealed through two circular windows
+{
+  type: "polygon",
+  x: 200, y: 150, sides: 8, size: 130,
+  fill: "mediumseagreen",
+  mask: [
+    { type: "circle", x: 140, y: 130, size: 60 },
+    { type: "circle", x: 260, y: 170, size: 60 },
+  ],
+}
+
+// Donut: punch a hole in a shape by compositing black into the mask
+{
+  type: "square",
+  x: 150, y: 150, size: 160,
+  fill: "steelblue",
+  mask: [
+    { type: "square", x: 150, y: 150, size: 160, fill: "white" }, // reveal
+    { type: "square", x: 150, y: 150, size: 80,  fill: "black" }, // punch hole
+  ],
+}
+```
+
+---
+
+## API
+
+### `generate(input: GeneratorInput): GeneratorOutput`
+
+```ts
+interface GeneratorInput {
+  seed: number; // any integer — determines all randomness
+  canvas: { width: number; height: number };
+  shapes: Shape[];
+  outputMode?: "semantic" | "path"; // default: "semantic"
+}
+
+interface GeneratorOutput {
+  svg: string;
+  metadata: { shapeCount: number };
+}
+```
+
+`outputMode: "semantic"` emits native SVG primitives (`<rect>`, `<circle>`, etc.) where possible.
+`outputMode: "path"` forces all shapes to `<path>` elements — useful when distortion or masking is applied.
+
+---
+
+## Determinism
+
+The seed drives a [mulberry32](https://gist.github.com/tommyettinger/46a874533244883189143505d203312c) PRNG. Given the same seed and input, `generate()` returns byte-for-byte identical SVG output across environments and versions. This makes the library suitable as a stable foundation for generative art pipelines, procedural asset systems, or any context where reproducibility matters.
+
+---
+
+## TypeScript
+
+Full strict-mode types are included. No `@types/` package needed.
+
+```ts
+import type { GeneratorInput, Shape, GeneratorOutput } from "foster-ts-shapes";
+```
+
+```
+
+███████╗ ██████╗ ███████╗████████╗███████╗██████╗
+██╔════╝██╔═══██╗██╔════╝╚══██╔══╝██╔════╝██╔══██╗
+█████╗  ██║   ██║███████╗   ██║   █████╗  ██████╔╝
+██╔══╝  ██║   ██║╚════██║   ██║   ██╔══╝  ██╔══██╗
+██║     ╚██████╔╝███████║   ██║   ███████╗██║  ██║
+╚═╝      ╚═════╝ ╚══════╝   ╚═╝   ╚══════╝╚═╝  ╚═╝
+```
+
+---
+
+## License
+
+MIT © 2026 VisualFinesse

package/dist/canonicalize.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratorInput } from "./types.js";
+export declare function canonicalize(input: GeneratorInput): GeneratorInput;

package/dist/canonicalize.js

@@ -0,0 +1,125 @@
+function canonicalizeCanvas(canvas) {
+    return {
+        width: canvas.width,
+        height: canvas.height,
+    };
+}
+// isMaskShape = true when canonicalizing a shape inside a <mask> element:
+//   mask and layer fields on nested shapes are silently dropped (no nesting).
+function canonicalizeShape(shape, isMaskShape = false) {
+    // Canonicalize mask shapes (only for top-level shapes; mask nesting not supported)
+    const canonicalMask = [];
+    if (!isMaskShape && shape.mask !== undefined) {
+        const rawArr = Array.isArray(shape.mask) ? shape.mask : [shape.mask];
+        for (const ms of rawArr) {
+            canonicalMask.push(canonicalizeShape(ms, true));
+        }
+    }
+    const base = {
+        x: shape.x,
+        y: shape.y,
+        ...(shape.rotation !== undefined ? { rotation: shape.rotation } : {}),
+        ...(shape.distort !== undefined ? { distort: shape.distort } : {}),
+        ...(shape.sizeVariance !== undefined ? { sizeVariance: shape.sizeVariance } : {}),
+        ...(shape.clamp !== undefined ? { clamp: shape.clamp } : {}),
+        ...(shape.fill !== undefined ? { fill: shape.fill } : {}),
+        ...(shape.stroke !== undefined ? { stroke: shape.stroke } : {}),
+        ...(shape.strokeWidth !== undefined ? { strokeWidth: shape.strokeWidth } : {}),
+        ...(shape.opacity !== undefined ? { opacity: shape.opacity } : {}),
+        ...(shape.fillGradient !== undefined ? { fillGradient: shape.fillGradient } : {}),
+        ...(shape.strokeGradient !== undefined ? { strokeGradient: shape.strokeGradient } : {}),
+        ...(shape.bezier !== undefined ? { bezier: shape.bezier } : {}),
+        ...(shape.bezierDirection !== undefined ? { bezierDirection: shape.bezierDirection } : {}),
+        ...(!isMaskShape && shape.layer !== undefined ? { layer: shape.layer } : {}),
+        ...(canonicalMask.length > 0 ? { mask: canonicalMask } : {}),
+    };
+    switch (shape.type) {
+        case "square": {
+            const s = shape;
+            const result = { type: "square", ...base, size: s.size };
+            return result;
+        }
+        case "rectangle": {
+            const s = shape;
+            const result = {
+                type: "rectangle",
+                ...base,
+                width: s.width,
+                height: s.height,
+            };
+            return result;
+        }
+        case "circle": {
+            const s = shape;
+            const result = { type: "circle", ...base, size: s.size };
+            return result;
+        }
+        case "triangle": {
+            const s = shape;
+            const result = {
+                type: "triangle",
+                ...base,
+                size: s.size,
+            };
+            return result;
+        }
+        case "trapezoid": {
+            const s = shape;
+            const result = {
+                type: "trapezoid",
+                ...base,
+                topWidth: s.topWidth,
+                bottomWidth: s.bottomWidth,
+                height: s.height,
+            };
+            return result;
+        }
+        case "octagon": {
+            const s = shape;
+            const result = { type: "octagon", ...base, size: s.size };
+            return result;
+        }
+        case "polygon": {
+            const s = shape;
+            const result = {
+                type: "polygon",
+                ...base,
+                sides: s.sides,
+                size: s.size,
+            };
+            return result;
+        }
+        case "oval": {
+            const s = shape;
+            const result = {
+                type: "oval",
+                ...base,
+                width: s.width,
+                height: s.height,
+            };
+            return result;
+        }
+        case "blob": {
+            const s = shape;
+            const result = {
+                type: "blob",
+                ...base,
+                size: s.size,
+                ...(s.points !== undefined ? { points: s.points } : {}),
+            };
+            return result;
+        }
+        default:
+            // Unknown type — pass through with only base fields; validate() will catch it
+            return { type: shape.type, ...base };
+    }
+}
+export function canonicalize(input) {
+    const result = {
+        seed: input.seed,
+        canvas: canonicalizeCanvas(input.canvas),
+        shapes: input.shapes.map((s) => canonicalizeShape(s)),
+        ...(input.outputMode !== undefined ? { outputMode: input.outputMode } : {}),
+    };
+    return result;
+}

package/dist/fmt.d.ts

@@ -0,0 +1 @@
+export declare function fmt(n: number): string;

package/dist/fmt.js

@@ -0,0 +1,3 @@
+export function fmt(n) {
+    return parseFloat(n.toFixed(6)).toString();
+}

package/dist/generate.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratorInput, GeneratorOutput } from "./types.js";
+export declare function generate(input: GeneratorInput): GeneratorOutput;

package/dist/generate.js

@@ -0,0 +1,140 @@
+import { shapeId } from "./id.js";
+import { assembleSvg } from "./svg.js";
+import { renderSquare } from "./shapes/square.js";
+import { renderRectangle } from "./shapes/rectangle.js";
+import { renderCircle } from "./shapes/circle.js";
+import { renderTriangle } from "./shapes/triangle.js";
+import { renderTrapezoid } from "./shapes/trapezoid.js";
+import { renderOctagon } from "./shapes/octagon.js";
+import { renderPolygon } from "./shapes/polygon.js";
+import { renderOval } from "./shapes/oval.js";
+import { renderBlob } from "./shapes/blob.js";
+import { canonicalize } from "./canonicalize.js";
+import { validate } from "./validate.js";
+import { createPrng, varSeed } from "./prng.js";
+import { applySizeVariance, renderVaried, extractVertices, verticesToPath } from "./variation.js";
+import { buildGradientDef, buildStylingAttrs } from "./styling.js";
+import { buildMaskDef } from "./mask.js";
+export function generate(input) {
+    const canonical = canonicalize(input);
+    validate(canonical);
+    const mode = canonical.outputMode ?? "semantic";
+    const defs = [];
+    // Stage 4: stable sort by layer (lower = rendered first = further back)
+    // Capture original index before sort so shapeId / varSeed remain deterministic
+    const indexed = canonical.shapes.map((shape, i) => ({ shape, i }));
+    indexed.sort((a, b) => (a.shape.layer ?? 0) - (b.shape.layer ?? 0));
+    const elements = indexed.map(({ shape, i }) => {
+        const sv = shape.sizeVariance ?? 0;
+        const dt = shape.distort ?? 0;
+        const bz = shape.bezier ?? 0;
+        // Create variation PRNG only when needed for sizeVariance or distort
+        const varPrng = (sv > 0 || dt > 0) ? createPrng(varSeed(canonical.seed, i)) : null;
+        // 1. Apply sizeVariance (scale size dims, consumes one prng draw)
+        const workShape = (sv > 0 && varPrng) ? applySizeVariance(shape, varPrng) : shape;
+        let tag;
+        let attrs;
+        if (dt > 0 || bz > 0) {
+            // Path pipeline: distort and/or bezier corner rounding
+            if (dt > 0 && varPrng) {
+                // Distortion (with optional bezier rounding passed through)
+                const r = renderVaried(workShape, varPrng, canonical.seed, i, bz, workShape.bezierDirection ?? "out");
+                tag = r.tag;
+                attrs = r.attrs;
+            }
+            else {
+                // Bezier only — extract vertices and apply corner rounding
+                const verts = extractVertices(workShape, canonical.seed, i);
+                const d = verticesToPath(verts, bz, workShape.bezierDirection ?? "out");
+                tag = "path";
+                attrs = { d };
+            }
+        }
+        else {
+            // Normal render pipeline
+            switch (workShape.type) {
+                case "square": {
+                    const r = renderSquare(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "rectangle": {
+                    const r = renderRectangle(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "circle": {
+                    const r = renderCircle(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "triangle": {
+                    const r = renderTriangle(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "trapezoid": {
+                    const r = renderTrapezoid(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "octagon": {
+                    const r = renderOctagon(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "polygon": {
+                    const r = renderPolygon(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "oval": {
+                    const r = renderOval(workShape, mode);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                case "blob": {
+                    const r = renderBlob(workShape, mode, canonical.seed, i);
+                    tag = r.tag;
+                    attrs = r.attrs;
+                    break;
+                }
+                default: throw new Error(`Unsupported shape type: ${workShape.type}`);
+            }
+        }
+        // Compute shape ID (needed for gradient IDs)
+        const id = shapeId(canonical.seed, shape.type, i);
+        // Gradient defs accumulation
+        let fillGradId;
+        if (shape.fillGradient) {
+            fillGradId = `grad-${id}-fill`;
+            defs.push(buildGradientDef(fillGradId, shape.fillGradient));
+        }
+        let strokeGradId;
+        if (shape.strokeGradient) {
+            strokeGradId = `grad-${id}-stroke`;
+            defs.push(buildGradientDef(strokeGradId, shape.strokeGradient));
+        }
+        // Apply all styling attrs (fill, stroke, stroke-width, opacity)
+        Object.assign(attrs, buildStylingAttrs(shape, fillGradId, strokeGradId));
+        // Stage 4: mask processing — build <mask> def and reference it on the shape
+        if (shape.mask !== undefined) {
+            const maskShapes = Array.isArray(shape.mask) ? shape.mask : [shape.mask];
+            if (maskShapes.length > 0) {
+                const maskId = `mask-${id}`;
+                defs.push(buildMaskDef(maskId, maskShapes, mode, canonical.seed, i, defs));
+                attrs["mask"] = `url(#${maskId})`;
+            }
+        }
+        return { tag, attrs, id, rotation: shape.rotation, cx: shape.x, cy: shape.y };
+    });
+    return { svg: assembleSvg(canonical.canvas, elements, defs), metadata: { shapeCount: canonical.shapes.length } };
+}

package/dist/id.d.ts

@@ -0,0 +1 @@
+export declare function shapeId(seed: number, type: string, index: number): string;

package/dist/id.js

@@ -0,0 +1,4 @@
+export function shapeId(seed, type, index) {
+    const seedPart = seed < 0 ? `sn${Math.abs(seed)}` : `s${seed}`;
+    return `${seedPart}-${type}-${index}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { generate } from "./generate.js";
+export type { GeneratorInput, Canvas, Shape, ShapeBase, SquareShape, RectangleShape, CircleShape, TriangleShape, TrapezoidShape, OctagonShape, PolygonShape, OvalShape, BlobShape, MaskShape, VariationFields, StylingFields, BezierFields, LayerFields, MaskFields, Gradient, LinearGradient, RadialGradient, ColorStop, GeneratorOutput, } from "./types.js";

package/dist/index.js

@@ -0,0 +1 @@
+export { generate } from "./generate.js";

package/dist/mask.d.ts

@@ -0,0 +1,2 @@
+import type { MaskShape } from "./types.js";
+export declare function buildMaskDef(maskId: string, maskShapes: MaskShape[], mode: "semantic" | "path", generatorSeed: number, parentIndex: number, gradientDefs: string[]): string;