@developerz.ai/ts23d 0.0.0-stage → 0.1.0

package/docs/plans/roadmap.md

@@ -0,0 +1,127 @@
+# Roadmap
+
+**Each milestone ships something an agent can use end to end, gated by `bun run verify`. Scope ends at the GLB, textures and manifest; engines and game code are out of scope.** Ticked = on `main` with a test and, where it makes geometry, a recipe. Order within a milestone is a suggestion; order between milestones is a dependency. No dates promised.
+
+Status as of 2026-11-07: **M0 done, M1 done but for recipes, M2 under way.** Every exported entry point that isn't ticked throws `T3D_NOT_IMPLEMENTED` with a pointer here.
+
+## M0: Scaffold (0.x)
+
+- [x] Mesh IR, `MeshBuilder`, seeded forkable RNG, vector math
+- [x] `defineAsset` / `compile` / `ctx.part` / `ctx.group` / `ctx.use`, LODs by re-run
+- [x] `real` dimensions + `sources` on `defineAsset`
+- [x] Mesh transforms: `place`, `affine`, `frame`, `applyAffine`
+- [x] `Ts23dError` with code + cause + fix
+- [x] Split grammar (`split`, `parseSplit`, `layoutSplit`), Whyte notation
+- [x] Trim-sheet layout, palettes, `hex()`
+- [x] Primitives: `box`, `lathe`, `cylinder`
+- [x] Kinds: `facade`, `setbacks`, `axle`, `trackRun`, `whyteAxles`, `propeller`
+- [x] `grime` pass
+- [x] QA: `triangle-budget`, `floating-parts` (surface contact), `clashes` (swept motion, `clearOf`), `part-names`, `proportions`, `measures` (`real.measures`)
+- [x] GLB writer: one material, baked spin/slide clip, Z-up → Y-up root
+- [x] `defineFamily`: variants and derived families
+- [x] `ctx.emitter`: particle sources as named nodes
+- [x] `sway` motion; `run` clip baked by `t3d build`, opt-in in `toGlb`
+- [x] Recipe `checks` (`clear`, `noOverlap`, `touches`, `symmetric`) and `inspect`
+- [x] `ctx.socket`; surfaces (opaque / cutout / glass / translucent, ≤ 4 materials)
+- [x] CLI output: `out/<asset>/` with GLBs, sheet, manifest; `out/index.json`
+- [x] `heightfield` terrain
+- [x] GLB production pass: front axis +Z, seamless loops, `rest` + `run` clips, u16 indices, u16 colours, shared time accessors, glTF-Validator in tests ([glb-production.md](../architecture/glb-production.md) G1, G2, G4, G5, G10)
+- [x] `mergeToPivots`: static geometry batched into its nearest pivot (default in `toGlb`; `keepParts` opts out)
+- [x] CPU contact sheet: six views, metre grid, header dims
+- [x] CLI: `t3d build | shot | list`, `--out`, `--json`
+- [x] Repo gates: lint, typecheck, boundaries, determinism, filesize, tests, recipes (QA + double-build hash), build
+- [x] Release flow: stamp → PR → tag → OIDC publish
+- [x] Recipes: `tiger_1`, `t34` + `t34_1941` (family), `loco_440` (family; the Jupiter, drivers 1.626 m sourced), `material_swatches`
+- [x] Asset gallery site (every recipe, compiled in the browser)
+- [ ] First npm publish (bootstrap, [PUBLISHING.md](../../PUBLISHING.md))
+
+## M1: Architecture primitives
+
+- [x] `prism`: extrude a 2D profile in the `xy` / `xz` / `yz` plane
+- [x] `beam`: member between two points, square or round
+- [x] `planar`: flat polygon in 3D
+- [x] `triangulate`: ear clipping
+- [x] `tiled`: quad tiling a strip at true scale
+- [x] `cell`: quad mapped to a decal cell (with `inset` reveals)
+- [x] `roof`: hip, gable, pyramid, mansard, gambrel, shed; `opening` window/door kit, `mass` true-scale masonry
+- [ ] Opt-out for genuinely floating parts (aircraft in flight, hanging signs)
+- [ ] Cross-machine determinism check; a `t3d build` flag for users' recipes
+- [x] Recipe: `eiffel_tower` (188,016 / 21,860 / 1,062 triangles, 1 draw call; profile from Weidman & Pinelis 2004 and Eiffel's 1887 drawing)
+- [x] `lattice` truss primitive (Warren / Pratt / Howe / X)
+- [ ] Recipes: a terrace street, a station, an Art Deco tower, townhouse, gas lamp (landing)
+
+## Recipe-agent backlog (unscheduled)
+
+- [ ] `orbit` motion + `phase` for side rods and quartering
+- [x] Sector sweep for `sway` clashes; `oneWay` slide / sway
+- [ ] `recipes/_lib/` shared helpers: `trackLoop`, `roadWheel`, decal font with Cyrillic
+- [ ] `subdivide(mesh, maxEdge)` pass for vertex-colour camo
+- [ ] Exact-match option for measure `parts` (today: prefix match)
+- [ ] TriangleGrid filling only the cells a triangle crosses
+
+## M2: High definition, cheap to draw
+
+Materials:
+- [x] `paintTrimSheet`: procedural albedo / normal / ORM; strips bond, planks, plates, noise, flat, slate, concrete, glass; 6 decal + 11 foliage cells
+- [x] Sheet in the GLB: embedded or shared external PNGs (`--sheet`, `--sheet-size`)
+- [ ] KTX2 profile; fix mip bleed between strips; per-face V mapping on `box`
+- [ ] Image-stamped cells (decals from any `ImageSource`)
+
+Optimisation and GLB production (gap ids from [glb-production.md](../architecture/glb-production.md)):
+- [x] `optimize(mesh)`: vertex weld + vertex-cache reorder, reports ACMR (default in export)
+- [ ] Gate: ACMR ceiling
+- [ ] Opt-in `web` profile: `KHR_mesh_quantization` + `EXT_meshopt_compression` (G14). Default stays core glTF: Godot refuses required extensions
+- [ ] `MSFT_lod` single-file LOD set + screen-coverage switch hints (G11)
+- [ ] Placeholder pivots at LOD2 so engine-bound names exist in every LOD (G3)
+- [ ] `engine-names` gate against Godot suffix hints like `_wheel`, `-col` (G6)
+- [ ] Clip naming Godot loops (`*_loop`) (G7)
+- [x] Asset metadata: generator version, copyright, XMP provenance (G8)
+- [ ] Mesh dedupe: identical geometry shares one mesh (G9)
+- [x] Emissive surface (`KHR_materials_emissive_strength`) for lit windows (G13 remainder)
+
+Shape:
+- [x] `sweep`: parallel-transport frames, taper, twist
+- [x] `loft` over `rings`, `ringXY` with wobble
+- [x] `hull` (vessel kind) from length / beam / draft / freeboard
+- [ ] Lofted vehicle bodies, fuselages, wings
+
+Checking:
+- [ ] `photoMatch(asset, { photo, camera })`: photo · model · overlay in one PNG + silhouette IoU
+- [ ] `silhouetteIoU` gate on top of it
+- [ ] Gates: manifold + outward normals, texel density
+
+Exit bar: a 4-4-0 with tender matching [`docs/reference/loco-photo-match.png`](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/reference/loco-photo-match.png) (predecessor output: ~16k triangles, 17 named nodes, one embedded trim-sheet material, baked `run`). Recipes: that loco, a harbour tug, a biplane.
+
+## M3: Vegetation and engine import adapters
+
+- [x] `tree`: Weber–Penn skeleton, leaf cards; presets oak / pine / palm / birch / willow; `trees` family; `treeReal`
+- [x] Recipes: `oak`, `pine`, `palm`
+- [ ] Per-vertex wind weights (crown `sway` today)
+- [ ] LOD2 impostors as crossed billboards from the foliage cells
+- [ ] Species presets as data
+- [x] `threeMaterialSource` (TSL) and `godotShaderSource`: wind, window glow, wear
+- [ ] Engine import adapters as data, not runtime: import settings for Unity (glTFast), Godot, Unreal; mapping extras + shader hints onto each engine's material
+- [ ] Engine collision naming: `ctx.collider` → Godot `-convcolonly`, Unreal `UCX_`, generic extras (G12)
+- [ ] Motion baked into vertex attributes (pivot + spin axis per vertex): a shader animates every wheel in one draw call
+- [ ] Recipes: a park, an orchard
+
+## M4: Creatures
+
+- [x] `sdf`: surface nets or marching cubes over a signed-distance field; `sculpt` edit lists (Dreams-style)
+- [ ] `creature`: SDF flesh over biped / quadruped / bird skeletons, bones as named parts
+- [ ] Recipes: stylised critters, rocks
+
+## M5: Neural adapters and import
+
+- [ ] `localGenerator`: HTTP adapter for a local TRELLIS.2 / Hunyuan3D 2.1 / SF3D server
+- [ ] Content-hash cache under `.ts23d/neural/`; a CI cache miss is an error naming the regenerate command
+- [ ] `importGlb`: any GLB as a part, fitted and recoloured onto the trim sheet
+- [ ] `kubeezImages`: kubeez.com image source for references, decals, texture sources
+- [ ] Recipe: a code-built cart drawn by a generated horse
+
+## M6: Reverse direction and reach
+
+- [ ] Camera solve for `photoMatch` from ≥ 4 marked correspondences
+- [ ] Reverse direction: a VLM proposes recipe params from photos, scored by silhouette IoU, best kept
+- [ ] MCP server: `build`, `shot`, `list` as tools, PNG inline
+- [ ] Playground: edit a recipe in the browser, see GLB + contact sheet live

package/examples/build-with-bun.ts

@@ -0,0 +1,41 @@
+// Build assets without the CLI: the library is plain TypeScript, so a script is all you need.
+// Run: bun examples/build-with-bun.ts [out-dir]   (Node ≥ 22 works too, against the built dist/)
+// Pick exactly what you want — which LODs, textures or not, QA or not, sheets or not.
+
+import {
+  compile,
+  contactSheet,
+  DEFAULT_SHEET,
+  type Lod,
+  paintTrimSheet,
+  runQa,
+  toGlb,
+} from '@developerz.ai/ts23d';
+import { tiger_1 } from '../recipes/tiger_1/tiger_1.ts';
+
+const out = process.argv[2] ?? 'out/example';
+const asset = tiger_1;
+const lods: Lod[] = [0, 2]; // near + far only — your call
+
+// Textures are optional: paint once, embed (or pass { external: true } and ship the PNGs).
+const sheet = paintTrimSheet({ ...DEFAULT_SHEET, size: 512 });
+
+for (const lod of lods) {
+  const compiled = compile(asset, { lod });
+
+  // QA is a function too: gate however your pipeline wants.
+  const findings = runQa(compiled);
+  if (findings.length > 0) {
+    for (const f of findings) console.error(`LOD${lod} ${f.gate}: ${f.message}\n  fix: ${f.fix}`);
+    process.exit(1);
+  }
+
+  await Bun.write(
+    `${out}/${asset.name}.lod${lod}.glb`,
+    toGlb(compiled, { sheet, animations: true }),
+  );
+}
+
+// The six-view contact sheet, for you or your agent to look at.
+await Bun.write(`${out}/${asset.name}.png`, contactSheet(compile(asset, { lod: 0 })));
+console.log(`✔ ${asset.name}: LOD ${lods.join(', ')} + contact sheet → ${out}/`);

package/llms.txt

@@ -0,0 +1,47 @@
+# ts23d
+
+> @developerz.ai/ts23d — a free, deterministic 3D asset generator driven by coding agents. Assets are TypeScript modules (never JSON) built with a DSL: `defineAsset({ name, kind, real, sources, budget, build(ctx) })`, where `build` adds named, pivoted, animatable parts from primitives (`box`, `lathe`, `cylinder`, `prism`, `beam`, `planar`), places detail with `place`/`merge`, composes other assets with `ctx.use`, and gates detail on `ctx.lod`. It compiles to glTF/GLB for any engine (Unity, Unreal, Godot, three.js, Babylon) — ts23d generates assets only, the engine is yours — (3 LODs, one shared trim-sheet material, baked motion), fails a QA gate on floating parts, budget overruns and wrong real-world proportions, and renders a zero-GPU six-view contact-sheet PNG so a vision-capable agent can check its own work. Bun only, zero runtime dependencies, MIT. Status 0.x: stubs throw T3D_NOT_IMPLEMENTED with the roadmap slice that builds them.
+
+## Offline (inside your project)
+The npm package ships every doc, skill and example, versioned with the code — read them without internet:
+- `node_modules/@developerz.ai/ts23d/AGENTS.md` — rules and the loop
+- `node_modules/@developerz.ai/ts23d/docs/` — DSL, IR, materials, agent loop, QA, kinds, decisions, roadmap
+- `node_modules/@developerz.ai/ts23d/recipes/<name>/` — idiomatic recipes, each with its research dossier (`README.md`) and committed hero + contact sheet (`out/`)
+- `node_modules/@developerz.ai/ts23d/.claude/skills/author-recipe/SKILL.md` — copy into your `.claude/skills/`
+
+## The workflow
+The human names a thing ("Tiger I, mid-production 1943"). The agent researches specs and real photos into `recipes/<name>/README.md` (every number sourced), writes `recipes/<name>.ts` with `sources` + `real.measures` from that dossier, compiles until QA PASS (budget, surface contact, clashes, proportions ±5%, measures ±2%), renders the six-view contact sheet, looks at it, adds LOD-gated detail, and iterates.
+
+## Programmatic (no CLI)
+`t3d` is optional: `compile` → `runQa` → `toGlb` / `contactSheet` / `paintTrimSheet` are plain functions returning bytes. Runnable script: `examples/build-with-bun.ts` (also in the npm package).
+
+## Start
+- [README](https://raw.githubusercontent.com/developerz-ai/ts23d/main/README.md): what it is, quickstart, the agent loop
+- [AGENTS.md](https://raw.githubusercontent.com/developerz-ai/ts23d/main/AGENTS.md): rules for agents using or changing the library
+- [CLAUDE.md](https://raw.githubusercontent.com/developerz-ai/ts23d/main/CLAUDE.md): commands, axioms, module tiers, CI
+- [Author-recipe skill](https://raw.githubusercontent.com/developerz-ai/ts23d/main/.claude/skills/author-recipe/SKILL.md): the closed loop, step by step, with a skeleton
+
+## DSL and concepts
+- [The DSL](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/02-dsl.md): defineAsset, ctx API, composition, determinism
+- [IR, units, axes](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/03-ir.md)
+- [Materials](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/04-materials.md): trim sheet, palettes, generator, image sources (kubeez.com)
+- [Agent loop](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/05-agent-loop.md): contact sheet layout, iteration
+- [QA gates](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/06-qa.md)
+- [What fits](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/07-what-fits.md): hard-surface vs organic; sculpted stylised characters and terrain today; realistic creatures via local-GPU adapters
+- [Kinds](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/idea/09-kinds.md): buildings, vehicles, vessels, vegetation, scenes
+
+## Reference
+- [Public API barrel](https://raw.githubusercontent.com/developerz-ai/ts23d/main/src/index.ts)
+- [Error codes](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/architecture/errors.md): every T3D_* with cause and fix
+- [Module tiers](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/architecture/README.md)
+- [glTF capabilities](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/architecture/gltf-capabilities.md): every extension, skins, physics drafts; what ts23d writes
+- [Roadmap](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/plans/roadmap.md): shipped vs planned
+- [Decisions](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/decisions/): why TS not JSON, why one material, why CPU renders
+- [Example recipe: Tiger I](https://raw.githubusercontent.com/developerz-ai/ts23d/main/recipes/tiger_1/tiger_1.ts)
+- [Reference dossier template](https://raw.githubusercontent.com/developerz-ai/ts23d/main/recipes/README.md)
+
+## Optional
+- [Landscape](https://raw.githubusercontent.com/developerz-ai/ts23d/main/docs/landscape.md): neutral overview of AI 3D generators and where each approach fits
+- [Gallery](https://developerz-ai.github.io/ts23d/): every asset compiled live in the browser — orbit, LODs, textures, download GLB
+- kubeez.com — recommended for reference/concept images and texture sources
+- developerz.ai — 100% AI-managed software engineering; builds and maintains this project

package/package.json

@@ -1,6 +1,101 @@
 {
   "name": "@developerz.ai/ts23d",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Free, deterministic 3D asset generation in TypeScript — a DSL your coding agent writes, compiled to game-ready glTF.",
+  "type": "module",
+  "license": "MIT",
+  "author": "developerz.ai",
+  "homepage": "https://developerz-ai.github.io/ts23d/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/developerz-ai/ts23d.git"
+  },
+  "bugs": "https://github.com/developerz-ai/ts23d/issues",
+  "keywords": [
+    "3d",
+    "procedural",
+    "gltf",
+    "glb",
+    "dsl",
+    "game-assets",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "three"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*": {
+      "types": "./dist/*/index.d.ts",
+      "bun": "./src/*/index.ts",
+      "default": "./dist/*/index.js"
+    }
+  },
+  "bin": {
+    "t3d": "./dist/cli/bin.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "docs",
+    "!docs/reference/*.png",
+    "recipes",
+    "!recipes/*/out",
+    "!docs/media",
+    "examples",
+    "README.md",
+    "CLAUDE.md",
+    "llms.txt",
+    "CHANGELOG.md",
+    "LICENSE",
+    ".claude/skills",
+    ".claude/agents",
+    ".claude/commands",
+    "!examples/**/*.test.ts"
+  ],
+  "workspaces": [
+    "apps/*"
+  ],
+  "scripts": {
+    "setup": "bun run scripts/setup.ts",
+    "verify": "bun run scripts/verify.ts",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test src scripts examples",
+    "build": "bun run scripts/build.ts",
+    "boundaries": "bun run scripts/boundaries.ts",
+    "determinism": "bun run scripts/determinism.ts",
+    "filesize": "bun run scripts/filesize.ts",
+    "recipes": "bun run scripts/recipes.ts",
+    "shots": "bun run scripts/shots.ts",
+    "release": "bun run scripts/release.ts",
+    "t3d": "bun run src/cli/bin.ts",
+    "site:dev": "bun run --filter @ts23d/site dev",
+    "site:build": "bun run --filter @ts23d/site build",
+    "site:shots": "bun run scripts/site-shots.ts",
+    "bench": "bun run scripts/bench.ts"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.6.3",
+    "@types/bun": "1.4.4",
+    "gltf-validator": "2.0.0-dev.3.10",
+    "lefthook": "2.2.2",
+    "typescript": "7.0.2"
+  },
+  "trustedDependencies": [],
+  "engines": {
+    "bun": ">=1.4.4",
+    "node": ">=22"
+  }
+}

package/recipes/README.md

@@ -0,0 +1,38 @@
+# recipes/ — one folder per asset
+
+Each asset is a folder: `recipes/<name>/<name>.ts` (the recipe), `recipes/<name>/README.md` (this dossier)
+and `recipes/<name>/out/<asset>/` (hero.png, sheet.png, manifest.json — committed, refreshed by
+`bun run shots`, checked by the recipes gate). The dossier is `recipes/<name>/README.md`. The agent writes it BEFORE the recipe; the recipe's
+`sources` and `real.measures` are copied from it, and the `measures` gate proves the model matches.
+Photos are linked, never committed (licences); downloads go to `tmp/refs/<name>/` (gitignored).
+
+## Template
+
+```md
+# <Name> — <variant / year>
+
+## Identity
+Variant chosen and why (one line). What makes it THIS object: the 3–5 signature features.
+
+## Specs
+| Dimension | Value (m) | Source |
+|---|---|---|
+| overall length | 6.316 | <url> |
+| width | 3.56 | <url> |
+| height | 3.00 | <url> |
+| road wheel diameter | 0.80 | <url> |
+
+## Photos (by view)
+| View | URL | Notes |
+|---|---|---|
+| side elevation | <url> | scale reference: wheel diameter |
+| front 3/4 | <url> | |
+| top | <url> | |
+| detail: <thing> | <url> | |
+
+## Parts the engine needs
+`turret` (yaw), `gun` (pitch), `road_wheel_*` (spin) …
+
+## Open questions
+What the sources disagree on, and which value was chosen.
+```

package/recipes/asteroid/README.md

@@ -0,0 +1,46 @@
+# Mineable asteroid (`asteroid`, `asteroid_b`, `asteroid_c`)
+
+## Identity
+A ~10 m rubble-pile asteroid for a mining game, in three seeded variants: `asteroid` (seed 1,
+5.0 × 3.8 × 3.0 m radii), `asteroid_b` (seed 2, rounder) and `asteroid_c` (seed 3, an elongated
+shard). The rocks are original and procedural.
+
+Signature features: a lumpy mass chipped by flat fracture planes; impact craters with raised rims
+and dark floors; very dark carbonaceous rock with lighter dust on up-facing slopes; thin metallic
+ore veins; glowing teal crystal clusters at the mining points.
+
+## References
+| Fact | Value | Source |
+|---|---|---|
+| C-type (carbonaceous) albedo | 0.03–0.09, ~75 % of asteroids, very dark | https://starlust.org/what-are-the-different-types-of-asteroids |
+| S-type (silicate) albedo | 0.10–0.22 | same |
+| M-type (metallic, nickel-iron) | bright, metallic, the mining target | https://www.esa.int/Science_Exploration/Space_Science/Rosetta/Debris_of_the_Solar_System_Asteroids |
+
+The base rock (`#3b3632`/`#4f4841`) is C-type dark. The ore veins (`#b78a45`) stand in for
+M-type metal. The glowing crystals (`#3fe0d0`) are a game convention, not science.
+
+## How it is built
+`sdf({ field, resolution: ctx.pick([0.17, 0.38, 0.95]) })` over one field:
+1. An ellipsoid core plus three smooth-unioned ellipsoid lobes.
+2. `valueNoise` displacement: 0.65 m at a 2.8 m feature size, plus 0.12 m pitting at 0.8 m.
+3. Twelve fracture half-spaces, smooth-max'd (k = 0.12 m), which give the angular facets.
+4. Nine craters. Each is a radial rim bump that displaces the surface, then a smooth-subtracted
+   bowl sphere. All shape draws come from `ctx.rng.fork('shape')`, so the shape is identical at
+   every LOD.
+5. Colour per vertex: blended tone noise, dust where n·z > 0.55, ore veins where |noise| < 0.05
+   (teal near crystals), dark crater floors.
+6. `bakeAo` (16 / 8 rays at LOD0 / LOD1) for crevice darkening.
+
+The bottom is clipped flat at z = 0 by the SDF bounds, so the rock rests on the ground (or in a
+field). The core sits below every variant's z radius, so the clip always happens.
+
+## Parts the engine needs
+`rock` (the mass; also usable as a collider at LOD2), `ore_crystals` (glow), interact sockets
+`mine_point_0…3` (at each cluster, facing into the rock, `data: { resource, yield }`), emitter
+`dust` (`event`, for mining debris).
+
+## Open questions
+- `real` is not declared: the size of a procedural rock is a design choice, not a spec, and the
+  noise moves its extents by ±10 %. The budget is measured per seed instead.
+- No in-library "surface point along a ray" helper exists, so the recipe bisects its own field to
+  seat the crystals. A `sdfSurface(field, from, dir)` helper would make this reusable.