Whole living worlds, grown from code.

THE FRONT DOOR — build a `World` on a canvas. Everything else in this package is reached through the object it returns.

THE RENDERER AND THE SCENE GRAPH IN ONE OBJECT — build it with {@link createWorld}, never with `new` (the factory is the published surface and keeps the constructor free to change).

Everything `createWorld` accepts. Only `canvas` is required; every other field has a stated default and the per-field docs below carry it. Passed once at build time — a world does not re-read these, so a scene that must change one rebuilds.

Render a recipe's poster frame OFF-SCREEN and return it as a PNG data URL — the placeholder-image pattern: paint it into the window (an <img> beneath the live canvas) at page load, and build the live world only when the window scrolls into view. The scratch world renders on a hidden staged canvas (sizing reads clientWidth, so it must be in the DOM) and its GL context is released before returning — a page can poster every window it owns without spending its live-context budget. Overlay labels (drawLabel) are not part of a poster. Returns null when WebGL is unavailable — callers keep their CSS fallback.

An axis-aligned box centred on the origin (flat-shaded faces).

A flat XZ plane centred on the origin, normal +Y.

An icosphere — geodesic subdivision of the icosahedron; normals are exact (radial), so it shades perfectly smooth at any subdivision level.

Sweep a circular cross-section along a polyline path using parallel-transport frames (no twist). `radius` may be a constant or a per-station function of u in 0..1 — taper for free.

Revolve a 2D profile (x = radius, y = height; x >= 0) around the Y axis.

Extrude a 2D polygon (CCW, on XZ) straight up by `height` — walls + fan caps.

A heightfield surface: y = f(x, z) sampled on an (nx x nz) grid over [-sizeX/2, sizeX/2] x [-sizeZ/2, sizeZ/2], smooth normals.

Grid helper: builds (nx*nz) quads from a parametric surface, smooth normals from central differences. Used by plane, heightfield and lathe alike.

A box of the given FULL extents. `radius` rounds every edge and corner — the cheapest realism there is, because a razor-perfect edge is the thing eyes read as fake.

A torus in the XZ plane: `ring` is the centreline radius, `tube` the thickness.

A capsule (a segment swept by a sphere) — the honest primitive for a limb or a branch.

A cone standing on the XZ plane, apex at +height.

A Y-axis cylinder of the given full height, optionally round-edged.

`a` with `b` cut out of it.

The one-liner: field in, Mesh out, ready for `world.mesh()`.

Mesh a field. Synchronous: it runs to completion before returning, and at a few tens of thousands of triangles that is a visible pause on the main thread. `marchSDFAsync` is the same algorithm with the pause broken up — see it for when that matters.

The bounding sphere of a mesh — vertex centroid + max distance. Not the minimal sphere, but stable and cheap; grown once at registration.

The Y-axis capsule of a mesh — radial extent in XZ, segment along Y inset by that radius (so the capsule's round ends stay inside the mesh's own top and bottom). The right auto-collider for anything grown upright: a trunk, a mast, a stem.

Ray vs sphere: nearest hit distance t ≥ 0 along a UNIT dir, or null. Pass `r` to sweep a moving sphere of that radius instead of a point; a ray starting inside reports the exit hit.

Ray vs capsule: nearest hit distance t ≥ 0 along a UNIT dir, or null. Pass `r` to sweep a moving sphere of that radius. A ray starting inside reports the exit hit — the same contract as `raySphere`, kept deliberately so a walker embedded in a trunk can find its way OUT instead of reporting nothing. Cylinder band + two end-sphere caps.

Overlap between two spheres — null when apart; otherwise the contact: `n` points from b to a (the push-out direction for a), `depth` the overlap.

Sphere vs capsule — the sphere/sphere contact against the capsule's closest point. `n` points from the capsule to the probe (the push-out direction for the probe), exactly `sphereHit`'s contract.

THE STEERING BRIDGE: obstacles, expressed as a field an agent can be steered by.

Attach the objectives layer to a World. Rides the frame loop as a grow() hook and drives the World through its public verbs — the renderer is untouched.

The user-facing facade returned by attachObjectives().

Classify a renderer string. PURE and testable — no GL, no DOM — so the table below can be argued with, extended, and checked against real strings in a unit test rather than discovered on someone's laptop.

What the engine thinks this GPU is. `detail` is the number a SCENE spends.

⚠ A World satisfies `Scale` structurally, so `growQuadruped(FOX, world)` reads correctly and needs no import in either direction — the same trick `FieldSampler` uses between flock and field. Nothing in this file knows what a World is.

What a caller passes instead of a size: "here is how big a metre is in this world."

A colour is born with its identity fixed, fully certain, and entirely unseen.

One observation's visibility. `L <- L + (1 - L) * weight` — fills toward the ceiling, never past.

Disagreement drains certainty. `S <- S * (1 - weight)`. Never rises; never below 0.

OBSERVE — shade a substrate colour by an amount of light, under the law.

⛔ **PARTICIPATION AT THE FLOAT32 CROSSING — the CPU sibling of the shader's `participate()` (bug #107, completing #104).** Identity below the knee, so every value the old wall did not touch is byte-identical; above it, strictly increasing forever, approaching 1 and reaching it for no finite input. The knee is `LIGHT_CEILING` — the SAME constant the old `Math.min` walls used, re-pointed from wall to curve exactly as the shader's `L_CEIL` was, so the correction is provably confined to the band the walls were destroying. Use it where `toRgb()` uses it: at the READ-OUT, where a held value becomes a colour a 32-bit pipeline will carry — never on the accumulator, whose bound is `FLOAT64_LAST_BELOW_ONE` above.

The held colour as linear RGB, 0..1. Standard HSL geometry — the LAW is upstream of this, in what may reach the three channels, so the conversion itself has nothing to enforce and does not try.

One concept's held state. `hue` is degrees; `saturation` and `lightness` are 0..1.

⚠ **KEPT AS AN ALIAS SO EXISTING CALLERS AND THE SHADER CONSTANT STILL RESOLVE**, and renamed in meaning rather than deleted: this corpus corrects by append. It no longer names a ceiling because there is not one — see above.