@chromatic-coherence/generative-engine 1.0.0

package/LICENSE

@@ -0,0 +1,36 @@
+Chromatic Coherence — generative-engine Licence (2026)
+
+Copyright (c) 2026 Chromatic Coherence. All rights reserved.
+
+This software ("the Software") is source-available but is NOT open source.
+It is licensed, not sold. Downloading or installing it (for example from npm)
+grants no rights beyond those written below, and does not transfer ownership.
+
+1. FREE LICENCE — no cost, perpetual — granted to:
+     * individuals, for personal or non-commercial use;
+     * registered charities and non-profit organisations;
+     * small businesses — an organisation with fewer than 25 people AND under
+       £1,000,000 in annual gross revenue.
+   A Free Licence lets you install the Software and use it AS-IS, embedded
+   inside your own application, and distribute it only as an inseparable part
+   of that application.
+
+2. COMMERCIAL LICENCE — required by any organisation not covered by clause 1
+   (an "SME or Enterprise"). A one-off fee of £100 per organisation grants a
+   perpetual Commercial Licence covering all of that organisation's products.
+   Contact hello@chromaticcoherence.ai.
+
+3. In no case, and under no licence, may you:
+     * modify, adapt, translate, or create derivative works of the Software;
+     * reverse-engineer, decompile, or disassemble it, except to the extent
+       that right cannot lawfully be excluded;
+     * resell, relicense, sublicense, rent, or redistribute the Software on its
+       own — as a package, fork, component, or competing library;
+     * remove or alter this licence or any copyright or authorship notice.
+
+4. NO WARRANTY. The Software is provided "AS IS", without warranty of any kind,
+   express or implied. To the fullest extent permitted by law, Chromatic
+   Coherence accepts no liability for any claim, damage, or loss arising from
+   the Software or its use.
+
+For commercial licensing, contact hello@chromaticcoherence.ai.

package/README.md

@@ -0,0 +1,80 @@
+<div align="center">
+
+# generative-engine
+
+### **THE THIRD ENGINE** — the [Generative Charts](https://chromaticcoherence.ai/generative-charts) family grows into a full **WebGL2 graphics engine**.
+
+[![licence: source-available](https://img.shields.io/badge/licence-source--available-1e88e5)](./LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-success)](#)
+
+**[2D · CPU edition →](https://www.npmjs.com/package/@chromatic-coherence/generative-charts-2d)** · **[3D · GPU charts edition →](https://www.npmjs.com/package/@chromatic-coherence/generative-charts-3d)**
+
+</div>
+
+---
+
+The two chart editions stay what they are — small, stable, chart-first. **generative-engine** is where
+the family expands: the same API (`createWorld` · `face` · `line` · `glow` · `grow` · `draw*` ·
+`fade`), so chart recipes port forward by changing one import — and underneath it, a real
+graphics engine. Zero dependencies; the browser is the only runtime.
+
+```bash
+npm install @chromatic-coherence/generative-engine
+```
+
+```js
+import { createWorld, v3, icosphere, heightfield } from "@chromatic-coherence/generative-engine";
+
+const w = createWorld({ canvas, controls: true, shadows: true });
+w.lights.push({ p: v3(-160, 320, 120), intensity: 1.2, falloff: 500 });
+w.mesh(heightfield((x, z) => Math.sin(x * 0.01) * 20, 800, 800), { hue: 262, sat: 38, light: 26 });
+w.meshMorph(icosphere(70, 3), myBlob, { hue: 350, sat: 30, light: 42, gloss: 0.5, group: "blob" });
+w.grow((t) => { w.morph("blob", 0.5 + 0.5 * Math.sin(t)); w.setTransform("blob", { rotateY: t * 0.4 }); });
+w.start();
+```
+
+## What the engine adds over the chart editions
+
+| | |
+|---|---|
+| **WebGL2 + HDR post chain** | The scene renders to a floating-point target, then: **bloom** (soft-knee bright pass, half-res gaussian), **SSAO** (depth-based contact shading), one composite pass (ACES filmic, colour grade, vignette), and **FXAA**. All art-directable (`w.bloom`, `w.ssao`, `w.fxaa`), all on by default. `post: false` opts out. |
+| **Real shadow maps** | A depth **texture** with hardware-comparison PCF (`sampler2DShadow`) — soft, exact, 2048px by default. `shadows: { size, softness, bias }`. |
+| **Geometry stdlib** | `plane` · `box` · `icosphere` · `tube` (parallel-transport sweep, taperable) · `lathe` · `extrude` · `heightfield` · `transformMesh` · `mergeMesh` — all pure math, all unit-tested, uploaded in one `w.mesh(geo, opts)` call with smooth normals. |
+| **Ribbons** | `w.ribbon(points, { width })` / `w.drawRibbon(...)` — screen-space-expanded strokes with **real pixel width**, feathered edges, depth-tested. The stroke aesthetic `gl.LINES` never allowed. |
+| **Group transforms** | `w.setTransform(group, { translate, rotateY, scale })` — geometry moves rigidly in the vertex stage, zero CPU re-tessellation, shadow pass included. |
+| **Morph targets** | `w.meshMorph(geoA, geoB, opts)` + `w.morph(group, t)` — blend between two vertex sets in the shader (breathing, becoming). Eased like `fade`. |
+| **8 point lights** | Up from 4; `lights[0]` casts the shadows. HDR intensities welcome — bloom catches what exceeds 1.0. |
+| **The carried light model** | Everything the chart edition learned rides along: GGX + Fresnel specular, procedural micro-relief, the perfusion term (`blood`, `bloodPulse`), pore noise, subsurface rim, coloured hemispheric ambient, fog — now resolving toward a real background colour the engine owns. |
+
+**The ink edition** (`theme: "light"`) still renders any recipe on paper instead of night —
+lightness inverts, strokes blend normally, SSAO becomes pencil shading. Bloom stays dark-only.
+
+## Demo
+
+`demo/index.html` — serve the package folder (`python -m http.server`) and open
+`/demo/`. Drag to orbit, ctrl+wheel to zoom; `?theme=light`, `?post=0`, `?still`.
+
+## Falling back
+
+`createWorld` **throws** (never a blank page) when WebGL2 is missing. Catch it and build the
+same recipe through the chart editions — the API is a subset, so the fallback chain
+engine → charts-3d → charts-2d is three imports of the same code. Browsers cap live GL
+contexts per page: on teardown call `dispose(true)` to release the context immediately, and
+mount a **fresh** canvas if you rebuild (a lost context is dead on its canvas).
+
+## Roadmap
+
+Planar mirrors · instancing · depth of field · motion blur. The chart editions stay lean.
+
+## Licence
+
+**Source-available, not open source.** Free for individuals, charities and small businesses
+(fewer than 25 people and under £1M annual revenue); a one-off **£100** covers any larger
+organisation. Full terms in [LICENSE](./LICENSE); commercial licensing:
+[hello@chromaticcoherence.ai](mailto:hello@chromaticcoherence.ai).
+
+---
+
+<div align="center">
+<sub>© 2026 Chromatic Coherence. All rights reserved.</sub>
+</div>

package/dist/geometry.d.ts

@@ -0,0 +1,40 @@
+import { V3, M4 } from "./math.js";
+/** Triangle soup: positions/normals are 3 floats per vertex, 3 vertices per triangle. */
+export type Mesh = {
+    pos: number[];
+    nrm: number[];
+};
+export declare const meshVertCount: (m: Mesh) => number;
+/** Grid helper: builds (nx*nz) quads from a parametric surface, smooth normals from
+ *  central differences. Used by plane, heightfield and lathe alike. */
+export declare function parametric(f: (u: number, v: number) => V3, nu: number, nv: number, opts?: {
+    wrapU?: boolean;
+}): Mesh;
+/** A flat XZ plane centred on the origin, normal +Y. */
+export declare function plane(sizeX: number, sizeZ: number, nx?: number, nz?: number): Mesh;
+/** An axis-aligned box centred on the origin (flat-shaded faces). */
+export declare function box(sx: number, sy: number, sz: number): Mesh;
+/** An icosphere — geodesic subdivision of the icosahedron; normals are exact
+ *  (radial), so it shades perfectly smooth at any subdivision level. */
+export declare function icosphere(radius: number, subdiv?: number): Mesh;
+/** 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. */
+export declare function tube(path: V3[], radius: number | ((u: number) => number), segments?: number, closed?: boolean): Mesh;
+/** Revolve a 2D profile (x = radius, y = height; x >= 0) around the Y axis. */
+export declare function lathe(profile: {
+    x: number;
+    y: number;
+}[], segments?: number): Mesh;
+/** Extrude a 2D polygon (CCW, on XZ) straight up by `height` — walls + fan caps. */
+export declare function extrude(shape: {
+    x: number;
+    z: number;
+}[], height: number): Mesh;
+/** 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. */
+export declare function heightfield(f: (x: number, z: number) => number, sizeX: number, sizeZ: number, nx?: number, nz?: number): Mesh;
+/** Transform a mesh in place by a mat4 (normals via the inverse-transpose). */
+export declare function transformMesh(m: Mesh, mat: M4): Mesh;
+/** Concatenate meshes into one (they must be pre-transformed into a shared space). */
+export declare function mergeMesh(...parts: Mesh[]): Mesh;

package/dist/geometry.js

@@ -0,0 +1,203 @@
+// generative-engine — geometry.ts: the mesh stdlib. Every builder returns a Mesh —
+// flat triangle soup with per-vertex smooth normals — that World.mesh() uploads
+// in one call. Pure math, no GL here: everything in this file runs under node
+// and is covered by test/run.mjs.
+import { v3, add, sub, scale, cross, norm, dot, len, applyM4, normalMat3, TAU } from "./math.js";
+export const meshVertCount = (m) => m.pos.length / 3;
+function pushTri(m, a, b, c, na, nb, nc) {
+    m.pos.push(a.x, a.y, a.z, b.x, b.y, b.z, c.x, c.y, c.z);
+    m.nrm.push(na.x, na.y, na.z, nb.x, nb.y, nb.z, nc.x, nc.y, nc.z);
+}
+function flatTri(m, a, b, c) {
+    const n = norm(cross(sub(b, a), sub(c, a)));
+    pushTri(m, a, b, c, n, n, n);
+}
+/** Grid helper: builds (nx*nz) quads from a parametric surface, smooth normals from
+ *  central differences. Used by plane, heightfield and lathe alike. */
+export function parametric(f, nu, nv, opts) {
+    const m = { pos: [], nrm: [] };
+    const P = [], N = [];
+    const eps = 1e-3;
+    for (let i = 0; i <= nu; i++) {
+        P.push([]);
+        N.push([]);
+        const u = i / nu;
+        for (let j = 0; j <= nv; j++) {
+            const v = j / nv;
+            const p = f(u, v);
+            const du = sub(f(Math.min(1, u + eps), v), f(Math.max(0, u - eps), v));
+            const dv = sub(f(u, Math.min(1, v + eps)), f(u, Math.max(0, v - eps)));
+            const n = norm(cross(dv, du)); // dv x du: +Y on an XZ field, outward on a lathe
+            P[i].push(p);
+            N[i].push(n);
+        }
+    }
+    if (opts?.wrapU)
+        for (let j = 0; j <= nv; j++) {
+            P[nu][j] = P[0][j];
+            N[nu][j] = N[0][j];
+        }
+    for (let i = 0; i < nu; i++)
+        for (let j = 0; j < nv; j++) {
+            pushTri(m, P[i][j], P[i + 1][j], P[i + 1][j + 1], N[i][j], N[i + 1][j], N[i + 1][j + 1]);
+            pushTri(m, P[i][j], P[i + 1][j + 1], P[i][j + 1], N[i][j], N[i + 1][j + 1], N[i][j + 1]);
+        }
+    return m;
+}
+/** A flat XZ plane centred on the origin, normal +Y. */
+export function plane(sizeX, sizeZ, nx = 1, nz = 1) {
+    return parametric((u, v) => v3((u - 0.5) * sizeX, 0, (v - 0.5) * sizeZ), nx, nz);
+}
+/** An axis-aligned box centred on the origin (flat-shaded faces). */
+export function box(sx, sy, sz) {
+    const m = { pos: [], nrm: [] };
+    const x = sx / 2, y = sy / 2, z = sz / 2;
+    const q = (a, b, c, d) => { flatTri(m, a, b, c); flatTri(m, a, c, d); };
+    q(v3(-x, -y, z), v3(x, -y, z), v3(x, y, z), v3(-x, y, z)); // +Z
+    q(v3(x, -y, -z), v3(-x, -y, -z), v3(-x, y, -z), v3(x, y, -z)); // -Z
+    q(v3(x, -y, z), v3(x, -y, -z), v3(x, y, -z), v3(x, y, z)); // +X
+    q(v3(-x, -y, -z), v3(-x, -y, z), v3(-x, y, z), v3(-x, y, -z)); // -X
+    q(v3(-x, y, z), v3(x, y, z), v3(x, y, -z), v3(-x, y, -z)); // +Y
+    q(v3(-x, -y, -z), v3(x, -y, -z), v3(x, -y, z), v3(-x, -y, z)); // -Y
+    return m;
+}
+/** An icosphere — geodesic subdivision of the icosahedron; normals are exact
+ *  (radial), so it shades perfectly smooth at any subdivision level. */
+export function icosphere(radius, subdiv = 2) {
+    const t = (1 + Math.sqrt(5)) / 2;
+    const V = [
+        v3(-1, t, 0), v3(1, t, 0), v3(-1, -t, 0), v3(1, -t, 0),
+        v3(0, -1, t), v3(0, 1, t), v3(0, -1, -t), v3(0, 1, -t),
+        v3(t, 0, -1), v3(t, 0, 1), v3(-t, 0, -1), v3(-t, 0, 1),
+    ].map(norm);
+    let tris = [
+        [V[0], V[11], V[5]], [V[0], V[5], V[1]], [V[0], V[1], V[7]], [V[0], V[7], V[10]], [V[0], V[10], V[11]],
+        [V[1], V[5], V[9]], [V[5], V[11], V[4]], [V[11], V[10], V[2]], [V[10], V[7], V[6]], [V[7], V[1], V[8]],
+        [V[3], V[9], V[4]], [V[3], V[4], V[2]], [V[3], V[2], V[6]], [V[3], V[6], V[8]], [V[3], V[8], V[9]],
+        [V[4], V[9], V[5]], [V[2], V[4], V[11]], [V[6], V[2], V[10]], [V[8], V[6], V[7]], [V[9], V[8], V[1]],
+    ];
+    for (let s = 0; s < subdiv; s++) {
+        const next = [];
+        for (const [a, b, c] of tris) {
+            const ab = norm(scale(add(a, b), 0.5)), bc = norm(scale(add(b, c), 0.5)), ca = norm(scale(add(c, a), 0.5));
+            next.push([a, ab, ca], [ab, b, bc], [ca, bc, c], [ab, bc, ca]);
+        }
+        tris = next;
+    }
+    const m = { pos: [], nrm: [] };
+    for (const [a, b, c] of tris)
+        pushTri(m, scale(a, radius), scale(b, radius), scale(c, radius), a, b, c);
+    return m;
+}
+/** 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. */
+export function tube(path, radius, segments = 12, closed = false) {
+    const m = { pos: [], nrm: [] };
+    const n = path.length;
+    if (n < 2)
+        return m;
+    const rad = typeof radius === "number" ? () => radius : radius;
+    // tangents by central difference
+    const T = [];
+    for (let i = 0; i < n; i++) {
+        const a = path[Math.max(0, i - 1)], b = path[Math.min(n - 1, i + 1)];
+        T.push(norm(sub(b, a)));
+    }
+    // parallel transport: seed a normal, rotate minimally between stations
+    let N0 = cross(T[0], Math.abs(T[0].y) < 0.95 ? v3(0, 1, 0) : v3(1, 0, 0));
+    N0 = norm(N0);
+    const rings = [], ringN = [];
+    let N = N0;
+    for (let i = 0; i < n; i++) {
+        if (i > 0) {
+            // rotate N so it stays perpendicular to the new tangent (Gram-Schmidt re-project)
+            N = norm(sub(N, scale(T[i], dot(N, T[i]))));
+            if (!isFinite(N.x) || len(N) < 1e-6)
+                N = norm(cross(T[i], v3(0, 1, 0)));
+        }
+        const B = cross(T[i], N);
+        const r = rad(i / (n - 1));
+        const ring = [], rn = [];
+        for (let s = 0; s < segments; s++) {
+            const a = (s / segments) * TAU;
+            const dir = add(scale(N, Math.cos(a)), scale(B, Math.sin(a)));
+            ring.push(add(path[i], scale(dir, r)));
+            rn.push(dir);
+        }
+        rings.push(ring);
+        ringN.push(rn);
+    }
+    const last = closed ? n : n - 1;
+    for (let i = 0; i < last; i++) {
+        const j = (i + 1) % n;
+        for (let s = 0; s < segments; s++) {
+            const s2 = (s + 1) % segments;
+            pushTri(m, rings[i][s], rings[j][s], rings[j][s2], ringN[i][s], ringN[j][s], ringN[j][s2]);
+            pushTri(m, rings[i][s], rings[j][s2], rings[i][s2], ringN[i][s], ringN[j][s2], ringN[i][s2]);
+        }
+    }
+    return m;
+}
+/** Revolve a 2D profile (x = radius, y = height; x >= 0) around the Y axis. */
+export function lathe(profile, segments = 24) {
+    const np = profile.length;
+    return parametric((u, v) => {
+        const a = u * TAU;
+        const i = Math.min(np - 1.001, v * (np - 1));
+        const i0 = Math.floor(i), fr = i - i0;
+        const x = profile[i0].x + (profile[Math.min(np - 1, i0 + 1)].x - profile[i0].x) * fr;
+        const y = profile[i0].y + (profile[Math.min(np - 1, i0 + 1)].y - profile[i0].y) * fr;
+        return v3(Math.cos(a) * x, y, Math.sin(a) * x);
+    }, segments, (np - 1) * 2, { wrapU: true });
+}
+/** Extrude a 2D polygon (CCW, on XZ) straight up by `height` — walls + fan caps. */
+export function extrude(shape, height) {
+    const m = { pos: [], nrm: [] };
+    const n = shape.length;
+    const lo = (p) => v3(p.x, 0, p.z);
+    const hi = (p) => v3(p.x, height, p.z);
+    for (let i = 0; i < n; i++) {
+        const a = shape[i], b = shape[(i + 1) % n];
+        flatTri(m, lo(a), lo(b), hi(b));
+        flatTri(m, lo(a), hi(b), hi(a));
+    }
+    for (let i = 1; i < n - 1; i++) { // caps (convex fan)
+        flatTri(m, hi(shape[0]), hi(shape[i]), hi(shape[i + 1]));
+        flatTri(m, lo(shape[0]), lo(shape[i + 1]), lo(shape[i]));
+    }
+    return m;
+}
+/** 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. */
+export function heightfield(f, sizeX, sizeZ, nx = 48, nz = 48) {
+    return parametric((u, v) => {
+        const x = (u - 0.5) * sizeX, z = (v - 0.5) * sizeZ;
+        return v3(x, f(x, z), z);
+    }, nx, nz);
+}
+/** Transform a mesh in place by a mat4 (normals via the inverse-transpose). */
+export function transformMesh(m, mat) {
+    const nm = normalMat3(mat);
+    for (let i = 0; i < m.pos.length; i += 3) {
+        const p = applyM4(mat, v3(m.pos[i], m.pos[i + 1], m.pos[i + 2]));
+        m.pos[i] = p.x;
+        m.pos[i + 1] = p.y;
+        m.pos[i + 2] = p.z;
+        const x = m.nrm[i], y = m.nrm[i + 1], z = m.nrm[i + 2];
+        const n = norm(v3(nm[0] * x + nm[3] * y + nm[6] * z, nm[1] * x + nm[4] * y + nm[7] * z, nm[2] * x + nm[5] * y + nm[8] * z));
+        m.nrm[i] = n.x;
+        m.nrm[i + 1] = n.y;
+        m.nrm[i + 2] = n.z;
+    }
+    return m;
+}
+/** Concatenate meshes into one (they must be pre-transformed into a shared space). */
+export function mergeMesh(...parts) {
+    const m = { pos: [], nrm: [] };
+    for (const p of parts) {
+        m.pos.push(...p.pos);
+        m.nrm.push(...p.nrm);
+    }
+    return m;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./math.js";
+export * from "./geometry.js";
+export * from "./world.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+// generative-engine — THE THIRD ENGINE. Public surface: the whole math kit, the geometry
+// stdlib, and the World. The chart editions' API is a strict subset — recipes port
+// forward by changing only the import.
+export * from "./math.js";
+export * from "./geometry.js";
+export * from "./world.js";

package/dist/math.d.ts

@@ -0,0 +1,45 @@
+export type V3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare const v3: (x?: number, y?: number, z?: number) => V3;
+export declare const add: (a: V3, b: V3) => V3;
+export declare const sub: (a: V3, b: V3) => V3;
+export declare const scale: (a: V3, s: number) => V3;
+export declare const dot: (a: V3, b: V3) => number;
+export declare const cross: (a: V3, b: V3) => V3;
+export declare const len: (a: V3) => number;
+export declare const norm: (a: V3) => V3;
+export declare const mix3: (a: V3, b: V3, u: number) => V3;
+export declare const TAU: number;
+export declare const clamp: (v: number, lo: number, hi: number) => number;
+export declare const lerp: (a: number, b: number, u: number) => number;
+export declare const easeInOut: (u: number) => number;
+/** Deterministic hash noise — identical to the chart editions, so recipes port. */
+export declare function rnd(i: number, k: number): number;
+export type M4 = Float32Array;
+export declare const mIdent: () => M4;
+export declare function mPerspective(fovy: number, aspect: number, near: number, far: number): M4;
+export declare function mLookAt(eye: V3, at: V3, up: V3): M4;
+export declare function mMul(a: M4, b: M4): M4;
+export declare const mTranslate: (t: V3) => M4;
+export declare const mScale: (s: V3) => M4;
+export declare function mRotX(a: number): M4;
+export declare function mRotY(a: number): M4;
+export declare function mRotZ(a: number): M4;
+/** Compose T*Ry*Rx*Rz*S from a plain-english spec — the group-transform helper. */
+export type TransformSpec = {
+    translate?: V3;
+    rotateX?: number;
+    rotateY?: number;
+    rotateZ?: number;
+    scale?: number | V3;
+};
+export declare function mCompose(spec: TransformSpec): M4;
+export declare function mInvert(m: M4): M4;
+export declare function mTranspose(m: M4): M4;
+/** Upper-3x3 inverse-transpose of a mat4 — the normal matrix (handles non-uniform scale). */
+export declare function normalMat3(m: M4): Float32Array;
+export declare function applyM4(m: M4, p: V3): V3;
+export declare function hsl(h: number, s: number, l: number): [number, number, number];

package/dist/math.js

@@ -0,0 +1,151 @@
+// generative-engine — THE THIRD ENGINE. math.ts: vectors, matrices, easing, colour.
+// Grown from dark-math-3d's maths, extended with the mat4 compose/invert set the
+// group-transform and post pipelines need. Zero third-party imports, on purpose.
+export const v3 = (x = 0, y = 0, z = 0) => ({ x, y, z });
+export const add = (a, b) => v3(a.x + b.x, a.y + b.y, a.z + b.z);
+export const sub = (a, b) => v3(a.x - b.x, a.y - b.y, a.z - b.z);
+export const scale = (a, s) => v3(a.x * s, a.y * s, a.z * s);
+export const dot = (a, b) => a.x * b.x + a.y * b.y + a.z * b.z;
+export const cross = (a, b) => v3(a.y * b.z - a.z * b.y, a.z * b.x - a.x * b.z, a.x * b.y - a.y * b.x);
+export const len = (a) => Math.hypot(a.x, a.y, a.z);
+export const norm = (a) => { const l = len(a) || 1; return v3(a.x / l, a.y / l, a.z / l); };
+export const mix3 = (a, b, u) => v3(a.x + (b.x - a.x) * u, a.y + (b.y - a.y) * u, a.z + (b.z - a.z) * u);
+export const TAU = Math.PI * 2;
+export const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v));
+export const lerp = (a, b, u) => a + (b - a) * u;
+export const easeInOut = (u) => (u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2);
+/** Deterministic hash noise — identical to the chart editions, so recipes port. */
+export function rnd(i, k) {
+    const x = Math.sin(i * 12.9898 + k * 78.233) * 43758.5453;
+    return x - Math.floor(x);
+}
+export const mIdent = () => new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+export function mPerspective(fovy, aspect, near, far) {
+    const f = 1 / Math.tan(fovy / 2), nf = 1 / (near - far);
+    const m = new Float32Array(16);
+    m[0] = f / aspect;
+    m[5] = f;
+    m[10] = (far + near) * nf;
+    m[11] = -1;
+    m[14] = 2 * far * near * nf;
+    return m;
+}
+export function mLookAt(eye, at, up) {
+    const zc = norm(sub(eye, at)), xc = norm(cross(up, zc)), yc = cross(zc, xc);
+    const m = new Float32Array(16);
+    m[0] = xc.x;
+    m[1] = yc.x;
+    m[2] = zc.x;
+    m[4] = xc.y;
+    m[5] = yc.y;
+    m[6] = zc.y;
+    m[8] = xc.z;
+    m[9] = yc.z;
+    m[10] = zc.z;
+    m[12] = -dot(xc, eye);
+    m[13] = -dot(yc, eye);
+    m[14] = -dot(zc, eye);
+    m[15] = 1;
+    return m;
+}
+export function mMul(a, b) {
+    const o = new Float32Array(16);
+    for (let c = 0; c < 4; c++)
+        for (let r = 0; r < 4; r++)
+            o[c * 4 + r] = a[r] * b[c * 4] + a[4 + r] * b[c * 4 + 1] + a[8 + r] * b[c * 4 + 2] + a[12 + r] * b[c * 4 + 3];
+    return o;
+}
+export const mTranslate = (t) => new Float32Array([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, t.x, t.y, t.z, 1]);
+export const mScale = (s) => new Float32Array([s.x, 0, 0, 0, 0, s.y, 0, 0, 0, 0, s.z, 0, 0, 0, 0, 1]);
+export function mRotX(a) {
+    const c = Math.cos(a), s = Math.sin(a);
+    return new Float32Array([1, 0, 0, 0, 0, c, s, 0, 0, -s, c, 0, 0, 0, 0, 1]);
+}
+export function mRotY(a) {
+    const c = Math.cos(a), s = Math.sin(a);
+    return new Float32Array([c, 0, -s, 0, 0, 1, 0, 0, s, 0, c, 0, 0, 0, 0, 1]);
+}
+export function mRotZ(a) {
+    const c = Math.cos(a), s = Math.sin(a);
+    return new Float32Array([c, s, 0, 0, -s, c, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
+}
+export function mCompose(spec) {
+    let m = mIdent();
+    if (spec.scale != null) {
+        const s = typeof spec.scale === "number" ? v3(spec.scale, spec.scale, spec.scale) : spec.scale;
+        m = mMul(mScale(s), m);
+    }
+    if (spec.rotateZ)
+        m = mMul(mRotZ(spec.rotateZ), m);
+    if (spec.rotateX)
+        m = mMul(mRotX(spec.rotateX), m);
+    if (spec.rotateY)
+        m = mMul(mRotY(spec.rotateY), m);
+    if (spec.translate)
+        m = mMul(mTranslate(spec.translate), m);
+    return m;
+}
+export function mInvert(m) {
+    // general 4x4 inverse (cofactors) — the post chain needs inverse-projection,
+    // the normal matrix needs inverse-transpose. Falls back to identity if singular.
+    const inv = new Float32Array(16);
+    inv[0] = m[5] * m[10] * m[15] - m[5] * m[11] * m[14] - m[9] * m[6] * m[15] + m[9] * m[7] * m[14] + m[13] * m[6] * m[11] - m[13] * m[7] * m[10];
+    inv[4] = -m[4] * m[10] * m[15] + m[4] * m[11] * m[14] + m[8] * m[6] * m[15] - m[8] * m[7] * m[14] - m[12] * m[6] * m[11] + m[12] * m[7] * m[10];
+    inv[8] = m[4] * m[9] * m[15] - m[4] * m[11] * m[13] - m[8] * m[5] * m[15] + m[8] * m[7] * m[13] + m[12] * m[5] * m[11] - m[12] * m[7] * m[9];
+    inv[12] = -m[4] * m[9] * m[14] + m[4] * m[10] * m[13] + m[8] * m[5] * m[14] - m[8] * m[6] * m[13] - m[12] * m[5] * m[10] + m[12] * m[6] * m[9];
+    inv[1] = -m[1] * m[10] * m[15] + m[1] * m[11] * m[14] + m[9] * m[2] * m[15] - m[9] * m[3] * m[14] - m[13] * m[2] * m[11] + m[13] * m[3] * m[10];
+    inv[5] = m[0] * m[10] * m[15] - m[0] * m[11] * m[14] - m[8] * m[2] * m[15] + m[8] * m[3] * m[14] + m[12] * m[2] * m[11] - m[12] * m[3] * m[10];
+    inv[9] = -m[0] * m[9] * m[15] + m[0] * m[11] * m[13] + m[8] * m[1] * m[15] - m[8] * m[3] * m[13] - m[12] * m[1] * m[11] + m[12] * m[3] * m[9];
+    inv[13] = m[0] * m[9] * m[14] - m[0] * m[10] * m[13] - m[8] * m[1] * m[14] + m[8] * m[2] * m[13] + m[12] * m[1] * m[10] - m[12] * m[2] * m[9];
+    inv[2] = m[1] * m[6] * m[15] - m[1] * m[7] * m[14] - m[5] * m[2] * m[15] + m[5] * m[3] * m[14] + m[13] * m[2] * m[7] - m[13] * m[3] * m[6];
+    inv[6] = -m[0] * m[6] * m[15] + m[0] * m[7] * m[14] + m[4] * m[2] * m[15] - m[4] * m[3] * m[14] - m[12] * m[2] * m[7] + m[12] * m[3] * m[6];
+    inv[10] = m[0] * m[5] * m[15] - m[0] * m[7] * m[13] - m[4] * m[1] * m[15] + m[4] * m[3] * m[13] + m[12] * m[1] * m[7] - m[12] * m[3] * m[5];
+    inv[14] = -m[0] * m[5] * m[14] + m[0] * m[6] * m[13] + m[4] * m[1] * m[14] - m[4] * m[2] * m[13] - m[12] * m[1] * m[6] + m[12] * m[2] * m[5];
+    inv[3] = -m[1] * m[6] * m[11] + m[1] * m[7] * m[10] + m[5] * m[2] * m[11] - m[5] * m[3] * m[10] - m[9] * m[2] * m[7] + m[9] * m[3] * m[6];
+    inv[7] = m[0] * m[6] * m[11] - m[0] * m[7] * m[10] - m[4] * m[2] * m[11] + m[4] * m[3] * m[10] + m[8] * m[2] * m[7] - m[8] * m[3] * m[6];
+    inv[11] = -m[0] * m[5] * m[11] + m[0] * m[7] * m[9] + m[4] * m[1] * m[11] - m[4] * m[3] * m[9] - m[8] * m[1] * m[7] + m[8] * m[3] * m[5];
+    inv[15] = m[0] * m[5] * m[10] - m[0] * m[6] * m[9] - m[4] * m[1] * m[10] + m[4] * m[2] * m[9] + m[8] * m[1] * m[6] - m[8] * m[2] * m[5];
+    const det = m[0] * inv[0] + m[1] * inv[4] + m[2] * inv[8] + m[3] * inv[12];
+    if (!det)
+        return mIdent();
+    const d = 1 / det;
+    for (let i = 0; i < 16; i++)
+        inv[i] *= d;
+    return inv;
+}
+export function mTranspose(m) {
+    const o = new Float32Array(16);
+    for (let c = 0; c < 4; c++)
+        for (let r = 0; r < 4; r++)
+            o[c * 4 + r] = m[r * 4 + c];
+    return o;
+}
+/** Upper-3x3 inverse-transpose of a mat4 — the normal matrix (handles non-uniform scale). */
+export function normalMat3(m) {
+    const it = mTranspose(mInvert(m));
+    return new Float32Array([it[0], it[1], it[2], it[4], it[5], it[6], it[8], it[9], it[10]]);
+}
+export function applyM4(m, p) {
+    const w = m[3] * p.x + m[7] * p.y + m[11] * p.z + m[15] || 1;
+    return v3((m[0] * p.x + m[4] * p.y + m[8] * p.z + m[12]) / w, (m[1] * p.x + m[5] * p.y + m[9] * p.z + m[13]) / w, (m[2] * p.x + m[6] * p.y + m[10] * p.z + m[14]) / w);
+}
+// ── colour: hsl -> rgb (0..1), CPU-side — colours ride the vertex buffers ──
+export function hsl(h, s, l) {
+    h = (((h % 360) + 360) % 360) / 360;
+    s = clamp(s, 0, 100) / 100;
+    l = clamp(l, 0, 100) / 100;
+    if (s === 0)
+        return [l, l, l];
+    const q = l < 0.5 ? l * (1 + s) : l + s - l * s, p = 2 * l - q;
+    const f = (t) => {
+        t = ((t % 1) + 1) % 1;
+        if (t < 1 / 6)
+            return p + (q - p) * 6 * t;
+        if (t < 1 / 2)
+            return q;
+        if (t < 2 / 3)
+            return p + (q - p) * (2 / 3 - t) * 6;
+        return p;
+    };
+    return [f(h + 1 / 3), f(h), f(h - 1 / 3)];
+}

package/dist/post.d.ts

@@ -0,0 +1,57 @@
+export declare function makeProg(gl: WebGL2RenderingContext, vs: string, fs: string): WebGLProgram;
+/** A program plus a uniform-location cache — getUniformLocation once, ever. */
+export declare class PInfo {
+    private gl;
+    prog: WebGLProgram;
+    private locs;
+    constructor(gl: WebGL2RenderingContext, vs: string, fs: string);
+    u(name: string): WebGLUniformLocation | null;
+    use(): void;
+}
+export type PostParams = {
+    bloomOn: boolean;
+    bloomThreshold: number;
+    bloomKnee: number;
+    bloomStrength: number;
+    ssaoOn: boolean;
+    ssaoStrength: number;
+    ssaoRadius: number;
+    filmic: boolean;
+    grade: boolean;
+    vignette: number;
+    ink: boolean;
+    fxaa: boolean;
+    near: number;
+    far: number;
+};
+export declare class PostChain {
+    readonly hdr: boolean;
+    private gl;
+    private pBright;
+    private pBlur;
+    private pSsao;
+    private pAoBlur;
+    private pComposite;
+    private pFxaa;
+    private scene;
+    sceneDepth: WebGLTexture | null;
+    private bloomA;
+    private bloomB;
+    private aoA;
+    private aoB;
+    private ldr;
+    private W;
+    private H;
+    constructor(gl: WebGL2RenderingContext);
+    private makeTarget;
+    private drop;
+    /** (Re)allocate every target at the given DEVICE-pixel size. */
+    resize(w: number, h: number): void;
+    /** Bind the scene target — the world's render pass draws into this. */
+    begin(): void;
+    private fst;
+    private bindTex;
+    /** Run the chain: bloom + ssao + composite (+ fxaa) to the canvas. */
+    end(o: PostParams): void;
+    dispose(): void;
+}