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

npm install foster-ts-shapes

Quick Start

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

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:

{
  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:

{
  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:

{
  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:

{
  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:

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:

// 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

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 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.

import type { GeneratorInput, Shape, GeneratorOutput } from "foster-ts-shapes";

███████╗ ██████╗ ███████╗████████╗███████╗██████╗
██╔════╝██╔═══██╗██╔════╝╚══██╔══╝██╔════╝██╔══██╗
█████╗  ██║   ██║███████╗   ██║   █████╗  ██████╔╝
██╔══╝  ██║   ██║╚════██║   ██║   ██╔══╝  ██╔══██╗
██║     ╚██████╔╝███████║   ██║   ███████╗██║  ██║
╚═╝      ╚═════╝ ╚══════╝   ╚═╝   ╚══════╝╚═╝  ╚═╝

License

MIT © 2026 VisualFinesse