blob-creator 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Blob Creator Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,3 +1,136 @@
1
- # Temporary Holding Version
1
+ # Blob Creator
2
+
3
+ Deterministic, zero-dependency procedural SVG generator for modern websites — featuring **15 pure-math generators**, **OKLCH color harmonies**, **cohesive multi-shape sets**, optional **React components**, and a built-in **`npx` interactive Studio**.
4
+
5
+ ## Highlights
6
+
7
+ - **Zero runtime dependencies** — pure ESM & CJS TypeScript core that runs in Node, Bun, Deno, browsers, and edge workers.
8
+ - **100% deterministic seeding** — powered by `FNV-1a` + `Mulberry32`; identical inputs always produce byte-identical SVGs with collision-free `<defs>` IDs.
9
+ - **15 procedural generators** across 6 categories:
10
+ - **Organic:** `blob`, `waves`, `ribbon`
11
+ - **Atmosphere:** `aurora`, `rings`
12
+ - **Editorial:** `topo`, `squiggle`
13
+ - **Geometric:** `bauhaus` (incl. graph-traced Truchet ribbons with weave crossings & trailing ends), `lowpoly`, `burst`
14
+ - **Dimensional:** `isometric`, `dotfield`, `mesh`
15
+ - **UI & Utility:** `mask`, `pattern`
16
+ - **Built-in `npx` Studio & CLI** — launch the full interactive visual studio locally or generate SVGs directly in build scripts.
17
+
18
+ ---
19
+
20
+ ## Quick Start
21
+
22
+ ### Launch the Interactive Studio via `npx`
23
+
24
+ ```bash
25
+ npx blob-creator
26
+ # or with custom port:
27
+ npx blob-creator studio --port 3030
28
+ ```
29
+
30
+ ### Install as a Library
31
+
32
+ ```bash
33
+ npm install blob-creator
34
+ ```
35
+
36
+ ### JavaScript / TypeScript (Zero Dependencies)
37
+
38
+ ```ts
39
+ import {
40
+ createSvg,
41
+ createDataUri,
42
+ createClipPath,
43
+ createSet,
44
+ } from 'blob-creator';
45
+
46
+ // Generate a deterministic SVG string
47
+ const svg = createSvg({
48
+ type: 'bauhaus',
49
+ seed: 'hero-01',
50
+ palette: 'midnight-aurora',
51
+ width: 1280,
52
+ height: 720,
53
+ params: { style: 'truchet', trailingEnds: true },
54
+ polish: { transparentBg: true, grain: 0.02 },
55
+ });
56
+
57
+ // Generate a CSS background-image data URI
58
+ const backgroundImage = createDataUri({
59
+ type: 'pattern',
60
+ seed: 'grid-01',
61
+ palette: 'minimal-ink',
62
+ });
63
+
64
+ // Generate a responsive CSS clip-path for masks or blobs
65
+ const clip = createClipPath({
66
+ type: 'mask',
67
+ seed: 'badge-01',
68
+ params: { shape: 'scallop', lobes: 12 },
69
+ });
70
+
71
+ // Generate a cohesive set of 6 matching shapes
72
+ const set = createSet({
73
+ type: 'blob',
74
+ seed: 'team-avatars',
75
+ count: 6,
76
+ cohesion: 'balanced',
77
+ palette: 'sunset-coral',
78
+ });
79
+ ```
80
+
81
+ ### React (`blob-creator/react`)
82
+
83
+ ```tsx
84
+ import { ProceduralSvg } from 'blob-creator/react';
85
+
86
+ export function HeroAccent() {
87
+ return (
88
+ <ProceduralSvg
89
+ type="bauhaus"
90
+ seed="hero-01"
91
+ palette="midnight-aurora"
92
+ width={1200}
93
+ height={630}
94
+ params={{ style: 'truchet', subdivide: 0.25 }}
95
+ polish={{ transparentBg: true }}
96
+ className="w-full h-auto"
97
+ />
98
+ );
99
+ }
100
+ ```
101
+
102
+ ### CLI Generation
103
+
104
+ ```bash
105
+ # List all 15 generators and 14 curated palettes
106
+ npx blob-creator list
107
+
108
+ # Generate a single SVG to a file (or stdout if --out is omitted)
109
+ npx blob-creator generate bauhaus \
110
+ --seed hero-01 \
111
+ --palette midnight-aurora \
112
+ --width 1280 --height 720 \
113
+ --param style=truchet \
114
+ --param trailingEnds=true \
115
+ --transparent \
116
+ --out ./public/hero-truchet.svg
117
+
118
+ # Generate a cohesive set of 6 blobs into a directory
119
+ npx blob-creator generate blob --seed team --set 6 --palette sunset-coral --out ./public/blobs
120
+ ```
121
+
122
+ ---
123
+
124
+ ## Development
125
+
126
+ ```bash
127
+ npm install
128
+ npm run dev # Start local Studio dev server
129
+ npm test # Run Vitest suite
130
+ npm run build # Typecheck + build library, CLI, and Studio bundle
131
+ ```
132
+
133
+ ## License
134
+
135
+ MIT
2
136
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
@@ -0,0 +1,274 @@
1
+ interface Rng {
2
+ /** Uniform float in [0, 1). */
3
+ next(): number;
4
+ /** Uniform float in [min, max). */
5
+ range(min: number, max: number): number;
6
+ /** Uniform integer in [min, max] inclusive. */
7
+ int(min: number, max: number): number;
8
+ /** Returns true with probability p in [0, 1]. */
9
+ chance(probability: number): boolean;
10
+ /** Picks a deterministic item from a non-empty array. */
11
+ pick<T>(items: readonly T[]): T;
12
+ /** Returns a deterministically shuffled shallow copy. */
13
+ shuffle<T>(items: readonly T[]): T[];
14
+ /** Creates an isolated child PRNG stream under a namespace. */
15
+ fork(namespace: string): Rng;
16
+ }
17
+ /** 32-bit FNV-1a hash returning an unsigned 32-bit integer. */
18
+ declare function hashSeed(input: string): number;
19
+ /** Short 6-char deterministic hex hash suitable for SVG <defs> ID prefixes. */
20
+ declare function hashHex(input: string): string;
21
+ /** Deterministic Mulberry32 PRNG seeded via FNV-1a. */
22
+ declare function createRng(seed: string): Rng;
23
+
24
+ type SvgAttrValue = string | number | boolean | undefined;
25
+ interface SvgNode {
26
+ tag: string;
27
+ attrs?: Record<string, SvgAttrValue>;
28
+ children?: SvgNode[];
29
+ text?: string;
30
+ }
31
+ interface SvgSceneMeta {
32
+ generatorId: string;
33
+ seed: string;
34
+ /** Set when generator renders its own full-bleed backdrop. */
35
+ ownsBackground?: boolean;
36
+ /** Disable drop-shadow polish for full-bleed dividers/backgrounds/patterns. */
37
+ disableShadow?: boolean;
38
+ /** Exact edge color of divider/wave elements for seamless section transitions. */
39
+ edgeColor?: string;
40
+ /** Whether wave divider is anchored to top edge instead of bottom. */
41
+ flippedEdge?: boolean;
42
+ /** Primary SVG path data in scene coordinates (for clip-path export). */
43
+ clipPathD?: string;
44
+ /** Normalized [0..1] objectBoundingBox path data for responsive CSS clip-path. */
45
+ normalizedClipPathD?: string;
46
+ /** Deterministic clipPath ID for CSS url(#...) export. */
47
+ clipPathId?: string;
48
+ }
49
+ interface SvgScene {
50
+ width: number;
51
+ height: number;
52
+ viewBox?: string;
53
+ preserveAspectRatio?: string;
54
+ idPrefix: string;
55
+ defs: SvgNode[];
56
+ nodes: SvgNode[];
57
+ meta: SvgSceneMeta;
58
+ }
59
+ declare function el(tag: string, attrs?: Record<string, SvgAttrValue>, children?: SvgNode[]): SvgNode;
60
+ declare function group(attrs: Record<string, SvgAttrValue> | undefined, children: SvgNode[]): SvgNode;
61
+ declare function pathNode(d: string, attrs?: Record<string, SvgAttrValue>): SvgNode;
62
+ declare function rectNode(x: number | string, y: number | string, width: number | string, height: number | string, attrs?: Record<string, SvgAttrValue>): SvgNode;
63
+ declare function circleNode(cx: number, cy: number, r: number, attrs?: Record<string, SvgAttrValue>): SvgNode;
64
+ declare function ellipseNode(cx: number, cy: number, rx: number, ry: number, attrs?: Record<string, SvgAttrValue>): SvgNode;
65
+ declare function polygonNode(points: readonly {
66
+ x: number;
67
+ y: number;
68
+ }[], attrs?: Record<string, SvgAttrValue>): SvgNode;
69
+
70
+ type ElementCategory = 'organic' | 'atmosphere' | 'editorial' | 'geometric' | 'dimensional' | 'ui-utility';
71
+ type SurfaceTheme = 'light' | 'dark' | 'both';
72
+ type HarmonyMode = 'analogous' | 'complementary' | 'split' | 'triadic' | 'monochrome';
73
+ type SetCohesion = 'tight' | 'balanced' | 'playful';
74
+ type MotionPreset = 'none' | 'float' | 'breathe' | 'spin' | 'drift';
75
+ type MotionSpeed = 'slow' | 'medium' | 'brisk';
76
+ type PreviewContextId = 'element' | 'grid' | 'hero' | 'features' | 'bento' | 'divider' | 'mask';
77
+ interface Palette {
78
+ id: string;
79
+ name: string;
80
+ theme: SurfaceTheme;
81
+ background: string;
82
+ colors: string[];
83
+ }
84
+ interface PolishOptions {
85
+ /** Film grain overlay opacity in [0, 0.09]. 0 disables grain. */
86
+ grain: number;
87
+ /** Subtle drop shadow for standalone shapes. */
88
+ shadow: boolean;
89
+ /** Omit canvas background fill when true. */
90
+ transparentBg: boolean;
91
+ /** Optional declarative CSS @keyframes motion embedded inside the SVG. */
92
+ motion: MotionPreset;
93
+ /** Animation duration cadence when motion !== 'none'. */
94
+ motionSpeed: MotionSpeed;
95
+ }
96
+ declare const DEFAULT_POLISH: PolishOptions;
97
+ type ControlGroup = 'shape' | 'style' | 'layout';
98
+ type ControlDef<P> = {
99
+ key: keyof P & string;
100
+ label: string;
101
+ type: 'slider';
102
+ min: number;
103
+ max: number;
104
+ step: number;
105
+ unit?: string;
106
+ group?: ControlGroup;
107
+ /** Progressive disclosure predicate: control is shown only when this returns true. */
108
+ when?: (params: P) => boolean;
109
+ } | {
110
+ key: keyof P & string;
111
+ label: string;
112
+ type: 'toggle';
113
+ group?: ControlGroup;
114
+ when?: (params: P) => boolean;
115
+ } | {
116
+ key: keyof P & string;
117
+ label: string;
118
+ type: 'select';
119
+ options: readonly {
120
+ value: string;
121
+ label: string;
122
+ }[];
123
+ group?: ControlGroup;
124
+ when?: (params: P) => boolean;
125
+ };
126
+ interface Preset<P> {
127
+ id: string;
128
+ name: string;
129
+ theme: SurfaceTheme;
130
+ seed: string;
131
+ paletteId: string;
132
+ params: Partial<P>;
133
+ polish?: Partial<PolishOptions>;
134
+ }
135
+ interface GenerateContext<P> {
136
+ rng: Rng;
137
+ seed: string;
138
+ idPrefix: string;
139
+ width: number;
140
+ height: number;
141
+ params: P;
142
+ palette: Palette;
143
+ }
144
+ interface ElementGenerator<P extends Record<string, unknown> = Record<string, unknown>> {
145
+ id: string;
146
+ name: string;
147
+ shortName: string;
148
+ description: string;
149
+ category: ElementCategory;
150
+ defaultSize: {
151
+ width: number;
152
+ height: number;
153
+ };
154
+ /** Preferred website context preview mode for this element. */
155
+ defaultContext: PreviewContextId;
156
+ /** Whether standalone transparent background is preferred by default. */
157
+ defaultTransparentBg: boolean;
158
+ defaults: P;
159
+ controls: readonly ControlDef<P>[];
160
+ presets: readonly Preset<P>[];
161
+ generate(ctx: GenerateContext<P>): SvgScene;
162
+ }
163
+ interface RenderRequest<P extends Record<string, unknown> = Record<string, unknown>> {
164
+ generatorId: string;
165
+ seed: string;
166
+ params?: Partial<P>;
167
+ palette: Palette;
168
+ width?: number;
169
+ height?: number;
170
+ polish?: Partial<PolishOptions>;
171
+ }
172
+
173
+ interface SvgExportOptions {
174
+ minify?: boolean;
175
+ includeDimensions?: boolean;
176
+ }
177
+ /** Serializes an SvgScene AST into clean, valid SVG XML. */
178
+ declare function exportSvg(scene: SvgScene, options?: SvgExportOptions): string;
179
+
180
+ interface ClipPathExportResult {
181
+ supported: boolean;
182
+ clipPathId: string;
183
+ /** Responsive SVG <clipPath clipPathUnits="objectBoundingBox"> + CSS usage snippet. */
184
+ snippet: string;
185
+ /** Raw pixel-coordinate CSS clip-path: path('...') fallback. */
186
+ cssPathRule: string;
187
+ }
188
+ /**
189
+ * Generates responsive objectBoundingBox clip-path markup for mask/blob scenes.
190
+ */
191
+ declare function exportCssClipPath(scene: SvgScene): ClipPathExportResult;
192
+
193
+ interface SetRenderRequest {
194
+ generatorId: string;
195
+ seed: string;
196
+ count: number;
197
+ cohesion: SetCohesion;
198
+ params?: Record<string, unknown>;
199
+ palette: Palette;
200
+ width?: number;
201
+ height?: number;
202
+ polish?: Partial<PolishOptions>;
203
+ /** Optional per-slot seed overrides so users can reroll single tiles in a set. */
204
+ slotSeeds?: Record<number, string>;
205
+ }
206
+ interface SetItem {
207
+ index: number;
208
+ seed: string;
209
+ label: string;
210
+ palette: Palette;
211
+ params: Record<string, unknown>;
212
+ scene: SvgScene;
213
+ }
214
+ /**
215
+ * Generates 1 to 20 cohesive, deterministically seeded variations of the same
216
+ * element family that visually fit together across cards, grids, or avatars.
217
+ */
218
+ declare function generateSet(request: SetRenderRequest): SetItem[];
219
+ /**
220
+ * Combines a set of 1..20 scenes into a single clean vector contact-sheet SvgScene.
221
+ * Because every item carries its own collision-free idPrefix, <defs> merge safely.
222
+ */
223
+ declare function buildSetContactSheetScene(items: readonly SetItem[], options?: {
224
+ cols?: number;
225
+ gap?: number;
226
+ }): SvgScene;
227
+ /**
228
+ * Exports all 1..20 cohesive set shapes as a single drop-in React/TSX module
229
+ * exporting named components (`Shape01`..`ShapeN`) plus a typed `SHAPE_SET` array.
230
+ */
231
+ declare function exportSetReactModule(items: readonly SetItem[], generatorId: string): string;
232
+
233
+ type GeneratorId = 'blob' | 'waves' | 'ribbon' | 'aurora' | 'rings' | 'topo' | 'squiggle' | 'bauhaus' | 'lowpoly' | 'burst' | 'isometric' | 'dotfield' | 'mesh' | 'mask' | 'pattern';
234
+ interface CreateElementOptions {
235
+ /** Procedural generator ID (e.g. 'blob', 'bauhaus', 'waves', 'topo'). */
236
+ type: GeneratorId | (string & {});
237
+ /** Deterministic seed string. Identical inputs produce byte-identical SVGs. */
238
+ seed?: string;
239
+ /** Curated palette ID (e.g. 'midnight-aurora') or custom Palette object. */
240
+ palette?: string | Palette;
241
+ /** Generator-specific parameters (validated and clamped automatically). */
242
+ params?: Record<string, unknown>;
243
+ /** Canvas width in viewBox units. Defaults to the generator's defaultSize.width. */
244
+ width?: number;
245
+ /** Canvas height in viewBox units. Defaults to the generator's defaultSize.height. */
246
+ height?: number;
247
+ /** Optional polish & motion overrides (grain, shadow, transparentBg, motion). */
248
+ polish?: Partial<PolishOptions>;
249
+ }
250
+ interface CreateSetOptions extends CreateElementOptions {
251
+ /** Number of cohesive shapes to generate (1..20). Defaults to 6. */
252
+ count?: number;
253
+ /** Variation tightness across the set. Defaults to 'balanced'. */
254
+ cohesion?: SetCohesion;
255
+ /** Optional per-slot seed overrides. */
256
+ slotSeeds?: Record<number, string>;
257
+ }
258
+ interface GeneratedSetItem extends SetItem {
259
+ /** Ready-to-use minified SVG string for this set item. */
260
+ svg: string;
261
+ }
262
+ /** Generates a pure SvgScene AST from high-level options. */
263
+ declare function createScene(options: CreateElementOptions): SvgScene;
264
+ /** Generates a clean, deterministic SVG string in one call. */
265
+ declare function createSvg(options: CreateElementOptions, exportOptions?: SvgExportOptions): string;
266
+ /** Generates a CSS `url("data:image/svg+xml,...")` background value. */
267
+ declare function createDataUri(options: CreateElementOptions): string;
268
+ /** Generates responsive CSS `clip-path` and `<clipPath>` markup for standalone shapes. */
269
+ declare function createClipPath(options: CreateElementOptions): ClipPathExportResult;
270
+ /** Generates a cohesive set of 1–20 related procedural SVGs. */
271
+ declare function createSet(options: CreateSetOptions): GeneratedSetItem[];
272
+
273
+ export { createSet as A, createSvg as B, DEFAULT_POLISH as D, el as F, ellipseNode as I, exportCssClipPath as J, exportSetReactModule as K, exportSvg as L, generateSet as N, group as O, hashHex as Q, hashSeed as T, pathNode as U, polygonNode as V, rectNode as W, buildSetContactSheetScene as u, circleNode as v, createClipPath as w, createDataUri as x, createRng as y, createScene as z };
274
+ export type { ClipPathExportResult as C, ElementGenerator as E, GenerateContext as G, HarmonyMode as H, MotionPreset as M, Palette as P, Rng as R, SvgScene as S, MotionSpeed as a, PolishOptions as b, RenderRequest as c, ControlDef as d, ControlGroup as e, CreateElementOptions as f, CreateSetOptions as g, ElementCategory as h, GeneratedSetItem as i, GeneratorId as j, Preset as k, PreviewContextId as l, SetCohesion as m, SetItem as n, SetRenderRequest as o, SurfaceTheme as p, SvgAttrValue as q, SvgExportOptions as r, SvgNode as s, SvgSceneMeta as t };