@chromatic-coherence/generative-engine 1.0.0

package/dist/world.js

@@ -0,0 +1,764 @@
+// generative-engine — world.ts: THE THIRD ENGINE's core. The charts-3d API rides on top
+// unchanged (face/line/glow/grow/draw*/fade/project/pick), and underneath it is a
+// WebGL2 renderer: HDR scene target + post chain (bloom, SSAO, composite, FXAA),
+// hardware-PCF depth-texture shadows, per-group transforms + morph targets in the
+// vertex stage, mesh + ribbon primitives. Zero third-party imports, on purpose.
+import { v3, add, sub, scale, cross, norm, clamp, hsl, mIdent, mPerspective, mLookAt, mMul, mCompose, normalMat3, } from "./math.js";
+import { FACE_VS, FACE_FS, DEPTH_VS, DEPTH_FS, LINE_VS, LINE_FS, PT_VS, PT_FS, RIBBON_VS, RIBBON_FS, } from "./shaders.js";
+import { PInfo, PostChain } from "./post.js";
+const FACE_STRIDE = 18; // pos3 norm3 rgb3 gloss1 blood1 grp1 pos2:3 norm2:3
+const LINE_STRIDE = 8; // pos3 col4 grp1
+const PT_STRIDE = 9; // pos3 size1 col4 grp1
+const RIB_STRIDE = 16; // pos3 prev3 next3 side1 width1 col4 grp1
+export class World {
+    idxFor(name) {
+        const n = name ?? "default";
+        let i = this.groupIdx.get(n);
+        if (i == null) {
+            i = Math.min(7, this.groupIdx.size);
+            this.groupIdx.set(n, i);
+        }
+        return i;
+    }
+    /** Fade a named group toward a target alpha — eased per frame. */
+    fade(name, target) { this.groupTarget[this.idxFor(name)] = clamp(target, 0, 1); }
+    /** Blend a named group toward its morph target (meshMorph geometry) — eased per frame. */
+    morph(name, target) { this.groupMorphT[this.idxFor(name)] = clamp(target, 0, 1); }
+    /** Set a named group's model transform — a mat4 or a {translate, rotateY, scale...} spec.
+     *  Geometry in the group moves rigidly with NO CPU re-tessellation. */
+    setTransform(name, m) {
+        const i = this.idxFor(name);
+        const mat = m instanceof Float32Array ? m : mCompose(m);
+        this.groupMat.set(mat, i * 16);
+        this.groupNM.set(normalMat3(mat), i * 9);
+    }
+    constructor(o) {
+        this.ink = false;
+        this.bg = [0.024, 0.016, 0.055];
+        this.transparent = false;
+        this.shadowSize = 2048;
+        this.shadowSoft = 1.6;
+        this.shadowBias = 0.0035;
+        this.shadowFBO = null;
+        this.shadowTex = null;
+        this.svp = mIdent();
+        // static stores (rebuilt on staticDirty) + per-frame dynamic stores
+        this.sFace = [];
+        this.sLine = [];
+        this.sPt = [];
+        this.sRib = [];
+        this.dFaceA = [];
+        this.dLineA = [];
+        this.dPtA = [];
+        this.dRibA = [];
+        this.labels = [];
+        this.staticDirty = true;
+        this.hooks = [];
+        this.raf = 0;
+        this.t0 = 0;
+        this.tPrev = 0;
+        this.disposed = false;
+        this.lastT = -1; // last rendered time — lets a paused world repaint after resize
+        this.cleanup = [];
+        this.fLight = [];
+        this.fRib = [];
+        this.cam = { target: v3(0, 0, 0), dist: 700, pitch: 0.5, yawBase: 0, yawUser: 0, pitchUser: 0, distT: 700, fov: 1.15 };
+        this.light = { dir: v3(0, 1, 0), ambient: 0.55, diffuse: 0.45, signed: false };
+        /** up to 8 point lights; lights[0] casts the shadow map (when shadows are on) */
+        this.lights = [];
+        /** per-pixel specular strength (0 = matte); skin catches the light around 0.5 */
+        this.specular = 0;
+        this.ambientSky = v3(1, 1, 1);
+        this.ambientGround = v3(1, 1, 1);
+        /** filmic tone map (ACES-ish) — runs in the composite pass now */
+        this.filmic = false;
+        /** the colour grade: violet-cool shadows, warm highlights — composite pass */
+        this.grade = false;
+        /** cinematic vignette 0..1 — composite pass (overlay fallback when post is off) */
+        this.vignette = 0;
+        /** the global heartbeat 0..1 — rides the per-face blood */
+        this.bloodPulse = 0;
+        /** HDR bloom — the light-on-dark aesthetic's native glow. Art-directable. */
+        this.bloom = { on: true, threshold: 0.82, knee: 0.35, strength: 0.65 };
+        /** depth-based SSAO — contact shading where surfaces meet */
+        this.ssao = { on: true, strength: 0.55, radius: 22 };
+        /** FXAA on the final composite */
+        this.fxaa = true;
+        // groups: fade alpha + morph weight + transform, resolved in the vertex stage
+        this.groupIdx = new Map([["default", 0]]);
+        this.groupAlpha = new Float32Array(8).fill(1);
+        this.groupTarget = new Float32Array(8).fill(1);
+        this.groupMorph = new Float32Array(8);
+        this.groupMorphT = new Float32Array(8);
+        this.groupMat = new Float32Array(8 * 16);
+        this.groupNM = new Float32Array(8 * 9);
+        this.W = 0;
+        this.H = 0;
+        this.mx = 0;
+        this.my = 0;
+        this.mxT = 0;
+        this.myT = 0;
+        this.yawUserT = 0;
+        this.pitchUserT = 0;
+        this.cx = v3();
+        this.rt = v3();
+        this.up = v3();
+        this.fw = v3();
+        this.focal = 0;
+        this.vp = mIdent();
+        this.zNear = 24;
+        this.zFar = 6000;
+        this.inkCss = new Map();
+        this.canvas = o.canvas;
+        const gl = o.canvas.getContext("webgl2", { alpha: true, antialias: false, premultipliedAlpha: true });
+        if (!gl)
+            throw new Error("generative-engine: no webgl2 context"); // callers fall back — never take the page down
+        this.gl = gl;
+        this.ink = o.theme === "light";
+        this.transparent = o.background === "transparent";
+        if (this.transparent) {
+            this.bg = [0, 0, 0];
+        }
+        else if (o.background && o.background !== "transparent") {
+            this.bg = hsl(o.background.hue, o.background.sat ?? 45, o.background.light ?? 5);
+        }
+        else {
+            this.bg = this.ink ? [0.90, 0.92, 0.95] : hsl(258, 48, 4);
+        }
+        this.opts = {
+            maxDpr: o.maxDpr ?? 2,
+            drift: o.drift ?? 0.045,
+            parallax: o.parallax ?? 0.3,
+            controls: o.controls ?? false,
+        };
+        if (o.camera) {
+            if (o.camera.target)
+                this.cam.target = o.camera.target;
+            if (o.camera.dist != null) {
+                this.cam.dist = o.camera.dist;
+                this.cam.distT = o.camera.dist;
+            }
+            if (o.camera.pitch != null)
+                this.cam.pitch = o.camera.pitch;
+            if (o.camera.yaw != null)
+                this.cam.yawBase = o.camera.yaw;
+            if (o.camera.fov != null)
+                this.cam.fov = o.camera.fov;
+        }
+        for (let i = 0; i < 8; i++) {
+            this.groupMat.set(mIdent(), i * 16);
+            this.groupNM.set([1, 0, 0, 0, 1, 0, 0, 0, 1], i * 9);
+        }
+        this.pFace = new PInfo(gl, FACE_VS, FACE_FS);
+        this.pLine = new PInfo(gl, LINE_VS, LINE_FS);
+        this.pPt = new PInfo(gl, PT_VS, PT_FS);
+        this.pRib = new PInfo(gl, RIBBON_VS, RIBBON_FS);
+        this.pDepth = new PInfo(gl, DEPTH_VS, DEPTH_FS);
+        this.post = (o.post ?? true) && !this.transparent ? new PostChain(gl) : null;
+        this.shadowsOn = !!o.shadows;
+        if (o.shadows && typeof o.shadows === "object") {
+            this.shadowSize = o.shadows.size ?? 2048;
+            this.shadowSoft = o.shadows.softness ?? 1.6;
+            this.shadowBias = o.shadows.bias ?? 0.0035;
+        }
+        if (this.shadowsOn) {
+            // a REAL depth texture with hardware comparison — LINEAR gives free 2x2 PCF per tap
+            this.shadowTex = gl.createTexture();
+            gl.bindTexture(gl.TEXTURE_2D, this.shadowTex);
+            gl.texImage2D(gl.TEXTURE_2D, 0, gl.DEPTH_COMPONENT24, this.shadowSize, this.shadowSize, 0, gl.DEPTH_COMPONENT, gl.UNSIGNED_INT, null);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_MODE, gl.COMPARE_REF_TO_TEXTURE);
+            gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_COMPARE_FUNC, gl.LEQUAL);
+            this.shadowFBO = gl.createFramebuffer();
+            gl.bindFramebuffer(gl.FRAMEBUFFER, this.shadowFBO);
+            gl.framebufferTexture2D(gl.FRAMEBUFFER, gl.DEPTH_ATTACHMENT, gl.TEXTURE_2D, this.shadowTex, 0);
+            gl.drawBuffers([gl.NONE]);
+            gl.readBuffer(gl.NONE);
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        }
+        this.bFace = gl.createBuffer();
+        this.bLine = gl.createBuffer();
+        this.bPt = gl.createBuffer();
+        this.bRib = gl.createBuffer();
+        this.bFaceD = gl.createBuffer();
+        this.bLineD = gl.createBuffer();
+        this.bPtD = gl.createBuffer();
+        this.bRibD = gl.createBuffer();
+        // the label overlay — a synced 2D canvas floated over the GL surface
+        this.overlay = document.createElement("canvas");
+        this.overlay.style.cssText = "position:absolute;inset:0;width:100%;height:100%;pointer-events:none;";
+        const parent = this.canvas.parentElement;
+        if (parent) {
+            if (getComputedStyle(parent).position === "static")
+                parent.style.position = "relative";
+            parent.appendChild(this.overlay);
+        }
+        this.og = this.overlay.getContext("2d");
+        this.resize();
+        const ro = new ResizeObserver(() => this.resize());
+        ro.observe(this.canvas);
+        this.cleanup.push(() => ro.disconnect());
+        const onMouse = (e) => {
+            this.mxT = (e.clientX / window.innerWidth - 0.5) * 2;
+            this.myT = (e.clientY / window.innerHeight - 0.5) * 2;
+        };
+        window.addEventListener("mousemove", onMouse);
+        this.cleanup.push(() => window.removeEventListener("mousemove", onMouse));
+        if (this.opts.controls)
+            this.wireControls();
+    }
+    wireControls() {
+        const cv = this.canvas;
+        cv.style.touchAction = "pan-y";
+        cv.style.cursor = "grab";
+        let dragging = false, lx = 0, ly = 0;
+        const down = (e) => { dragging = true; lx = e.clientX; ly = e.clientY; cv.style.cursor = "grabbing"; cv.setPointerCapture(e.pointerId); };
+        const move = (e) => {
+            if (!dragging)
+                return;
+            this.yawUserT -= (e.clientX - lx) * 0.0045;
+            this.pitchUserT = clamp(this.pitchUserT + (e.clientY - ly) * 0.003, -0.3, 0.4);
+            lx = e.clientX;
+            ly = e.clientY;
+        };
+        const upFn = () => { dragging = false; cv.style.cursor = "grab"; };
+        const wheel = (e) => {
+            if (!e.ctrlKey && !e.metaKey)
+                return;
+            e.preventDefault();
+            this.cam.distT = clamp(this.cam.distT + e.deltaY * 0.6, 120, 2200);
+        };
+        cv.addEventListener("pointerdown", down);
+        cv.addEventListener("pointermove", move);
+        cv.addEventListener("pointerup", upFn);
+        cv.addEventListener("pointercancel", upFn);
+        cv.addEventListener("wheel", wheel, { passive: false });
+        this.cleanup.push(() => {
+            cv.removeEventListener("pointerdown", down);
+            cv.removeEventListener("pointermove", move);
+            cv.removeEventListener("pointerup", upFn);
+            cv.removeEventListener("pointercancel", upFn);
+            cv.removeEventListener("wheel", wheel);
+        });
+    }
+    resize() {
+        const dpr = Math.min(window.devicePixelRatio || 1, this.opts.maxDpr);
+        const W = this.canvas.clientWidth, H = this.canvas.clientHeight;
+        const pw = Math.max(1, Math.round(W * dpr)), ph = Math.max(1, Math.round(H * dpr));
+        // no-op when nothing changed: ANY canvas.width assignment clears the drawing
+        // buffer, so the ResizeObserver's initial fire would wipe a settle()d still
+        if (W === this.W && H === this.H && this.canvas.width === pw && this.canvas.height === ph)
+            return;
+        this.W = W;
+        this.H = H;
+        this.canvas.width = pw;
+        this.canvas.height = ph;
+        this.overlay.width = this.canvas.width;
+        this.overlay.height = this.canvas.height;
+        this.og.setTransform(dpr, 0, 0, dpr, 0, 0);
+        this.gl.viewport(0, 0, this.canvas.width, this.canvas.height);
+        this.post?.resize(this.canvas.width, this.canvas.height);
+        // a resize clears the drawing buffer — a PAUSED world (settle() stills) repaints
+        // its last frame here so a late ResizeObserver fire never leaves a blank canvas
+        if (!this.raf && this.lastT >= 0 && !this.disposed)
+            this.renderFrame(this.lastT, 0);
+    }
+    // ── theme: the ink edition inverts lightness; recipes pass through unchanged when dark ──
+    col(h, s, l) {
+        return hsl(h, s, this.ink ? 100 - l : l);
+    }
+    parseCol(c) {
+        const m = /hsl\(\s*([\d.]+)[deg\s]*[, ]\s*([\d.]+)%[, ]\s*([\d.]+)%/.exec(c);
+        return m ? this.col(+m[1], +m[2], +m[3]) : (this.ink ? [0.18, 0.18, 0.28] : [0.9, 0.9, 1]);
+    }
+    themedCss(color) {
+        if (!this.ink)
+            return color;
+        let c = this.inkCss.get(color);
+        if (!c) {
+            const m = /hsl\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%\s*\)/.exec(color);
+            c = m ? `hsl(${m[1]} ${m[2]}% ${clamp(100 - +m[3], 0, 100)}%)` : color;
+            this.inkCss.set(color, c);
+        }
+        return c;
+    }
+    // ── building the static world ──
+    pushFace(store, a, b, c, o, na, nb, nc, a2, b2, c2, na2, nb2, nc2) {
+        const n = na ? undefined : norm(cross(sub(b, a), sub(c, a)));
+        const [r, g, bl] = this.col(o.hue, o.sat ?? 45, o.light ?? 30);
+        const gi = this.idxFor(o.group);
+        const gloss = clamp(o.gloss ?? 0.3, 0, 1);
+        const blood = clamp(o.blood ?? 0, 0, 1);
+        const verts = [
+            [a, na ?? n, a2 ?? a, na2 ?? na ?? n],
+            [b, nb ?? n, b2 ?? b, nb2 ?? nb ?? n],
+            [c, nc ?? n, c2 ?? c, nc2 ?? nc ?? n],
+        ];
+        for (const [p, nn, p2, nn2] of verts)
+            store.push(p.x, p.y, p.z, nn.x, nn.y, nn.z, r, g, bl, gloss, blood, gi, p2.x, p2.y, p2.z, nn2.x, nn2.y, nn2.z);
+    }
+    /** One static triangle. Pass per-vertex normals for smooth shading; omit for flat. */
+    face(a, b, c, o, na, nb, nc) {
+        this.pushFace(this.sFace, a, b, c, o, na, nb, nc);
+        this.staticDirty = true;
+    }
+    /** Upload a whole Mesh (geometry.ts builders) as static faces in one call. */
+    mesh(geo, o) {
+        const P = geo.pos, N = geo.nrm;
+        for (let i = 0; i < P.length; i += 9) {
+            this.pushFace(this.sFace, v3(P[i], P[i + 1], P[i + 2]), v3(P[i + 3], P[i + 4], P[i + 5]), v3(P[i + 6], P[i + 7], P[i + 8]), o, v3(N[i], N[i + 1], N[i + 2]), v3(N[i + 3], N[i + 4], N[i + 5]), v3(N[i + 6], N[i + 7], N[i + 8]));
+        }
+        this.staticDirty = true;
+    }
+    /** Upload a morph pair: the group's morph weight blends A -> B in the vertex shader.
+     *  The two meshes MUST have identical vertex counts (build them from the same recipe). */
+    meshMorph(geoA, geoB, o) {
+        if (geoA.pos.length !== geoB.pos.length)
+            throw new Error(`generative-engine meshMorph: vertex counts differ (${geoA.pos.length / 3} vs ${geoB.pos.length / 3})`);
+        const P = geoA.pos, N = geoA.nrm, Q = geoB.pos, M = geoB.nrm;
+        for (let i = 0; i < P.length; i += 9) {
+            this.pushFace(this.sFace, v3(P[i], P[i + 1], P[i + 2]), v3(P[i + 3], P[i + 4], P[i + 5]), v3(P[i + 6], P[i + 7], P[i + 8]), o, v3(N[i], N[i + 1], N[i + 2]), v3(N[i + 3], N[i + 4], N[i + 5]), v3(N[i + 6], N[i + 7], N[i + 8]), v3(Q[i], Q[i + 1], Q[i + 2]), v3(Q[i + 3], Q[i + 4], Q[i + 5]), v3(Q[i + 6], Q[i + 7], Q[i + 8]), v3(M[i], M[i + 1], M[i + 2]), v3(M[i + 3], M[i + 4], M[i + 5]), v3(M[i + 6], M[i + 7], M[i + 8]));
+        }
+        this.staticDirty = true;
+    }
+    line(a, b, o) {
+        const [r, g, bl] = this.col(o.hue, o.sat ?? 80, o.light ?? 55);
+        const al = clamp(o.alpha, 0, 1), gi = this.idxFor(o.group);
+        this.sLine.push(a.x, a.y, a.z, r, g, bl, al, gi, b.x, b.y, b.z, r, g, bl, al, gi);
+        this.staticDirty = true;
+    }
+    glow(p, o) {
+        const [r, g, bl] = o.white ? (this.ink ? [0.16, 0.15, 0.24] : [1, 1, 1]) : this.col(o.hue ?? 0, 85, 62);
+        this.sPt.push(p.x, p.y, p.z, o.size, r, g, bl, clamp(o.alpha, 0, 1), this.idxFor(o.group));
+        this.staticDirty = true;
+    }
+    dust(p, alpha) {
+        if (this.ink)
+            this.sPt.push(p.x, p.y, p.z, 1.6, 0.29, 0.31, 0.45, clamp(alpha * 0.6, 0, 1), 0);
+        else
+            this.sPt.push(p.x, p.y, p.z, 1.6, 0.87, 0.89, 1, clamp(alpha * 0.6, 0, 1), 0);
+        this.staticDirty = true;
+    }
+    pushRibbon(store, pts, o) {
+        const n = pts.length;
+        if (n < 2)
+            return;
+        const [r, g, bl] = this.col(o.hue, o.sat ?? 80, o.light ?? 55);
+        const al = clamp(o.alpha, 0, 1), gi = this.idxFor(o.group), w = o.width;
+        const vert = (i, side) => {
+            const p = pts[i], q = pts[Math.max(0, i - 1)], s = pts[Math.min(n - 1, i + 1)];
+            store.push(p.x, p.y, p.z, q.x, q.y, q.z, s.x, s.y, s.z, side, w, r, g, bl, al, gi);
+        };
+        for (let i = 0; i < n - 1; i++) {
+            vert(i, -1);
+            vert(i, 1);
+            vert(i + 1, -1);
+            vert(i, 1);
+            vert(i + 1, 1);
+            vert(i + 1, -1);
+        }
+    }
+    /** A static ribbon stroke — real pixel width, feathered edges, depth-tested. */
+    ribbon(pts, o) { this.pushRibbon(this.sRib, pts, o); this.staticDirty = true; }
+    grow(fn) { this.hooks.push(fn); }
+    // ── the living verbs (gathered per frame) ──
+    drawLine(a, b, color, alpha, width = 1) {
+        this.fLight.push({ k: "line", a, b, color, alpha, width });
+    }
+    drawPath(pts, color, alpha, width = 1) {
+        this.fLight.push({ k: "poly", pts, color, alpha, width });
+    }
+    drawGlow(p, hue, size, alpha) {
+        this.fLight.push({ k: "glow", p, hue, size, alpha });
+    }
+    drawLabel(p, text, color, alpha, dy = 0) {
+        this.fLight.push({ k: "label", p, text, color, alpha, dy });
+    }
+    drawFace(a, b, c, o, na, nb, nc) {
+        this.pushFace(this.dFaceA, a, b, c, o, na, nb, nc);
+    }
+    /** A per-frame ribbon stroke — the animated counterpart of ribbon(). */
+    drawRibbon(pts, o) { this.fRib.push({ pts, o }); }
+    /** Screen-space overlay (the 2D label canvas — never occluded). */
+    overlay2d(cb) { cb(this.og, this); }
+    // ── camera + CPU projection for pick/labels ──
+    setupCamera(t, dt) {
+        this.mx += (this.mxT - this.mx) * Math.min(1, dt * 3);
+        this.my += (this.myT - this.my) * Math.min(1, dt * 3);
+        this.cam.yawUser += (this.yawUserT - this.cam.yawUser) * Math.min(1, dt * 5);
+        this.cam.pitchUser += (this.pitchUserT - this.cam.pitchUser) * Math.min(1, dt * 5);
+        this.cam.dist += (this.cam.distT - this.cam.dist) * Math.min(1, dt * 4);
+        const yaw = this.cam.yawBase + t * this.opts.drift + this.cam.yawUser + this.mx * this.opts.parallax;
+        const pitch = clamp(this.cam.pitch + this.cam.pitchUser + this.my * this.opts.parallax * 0.5, 0.18, 0.95);
+        const cp = Math.cos(pitch), sp = Math.sin(pitch);
+        this.cx = add(this.cam.target, scale(v3(cp * Math.cos(yaw), sp, cp * Math.sin(yaw)), this.cam.dist));
+        this.fw = norm(sub(this.cam.target, this.cx));
+        this.rt = norm(cross(this.fw, v3(0, 1, 0)));
+        this.up = cross(this.rt, this.fw);
+        this.focal = Math.min(this.W, this.H) * this.cam.fov;
+        const fovy = 2 * Math.atan(this.H / (2 * this.focal));
+        this.vp = mMul(mPerspective(fovy, this.W / this.H, this.zNear, this.zFar), mLookAt(this.cx, this.cam.target, v3(0, 1, 0)));
+    }
+    project(p) {
+        const dx = p.x - this.cx.x, dy = p.y - this.cx.y, dz = p.z - this.cx.z;
+        const z = dx * this.fw.x + dy * this.fw.y + dz * this.fw.z;
+        if (z < this.zNear)
+            return null;
+        const f = this.focal / z;
+        return {
+            x: this.W / 2 + (dx * this.rt.x + dy * this.rt.y + dz * this.rt.z) * f,
+            y: this.H / 2 - (dx * this.up.x + dy * this.up.y + dz * this.up.z) * f,
+            s: f, z,
+        };
+    }
+    fog(z) { return Math.min(1, Math.max(0.08, (this.cam.dist * 0.9) / z)); }
+    pick(sx, sy, planeY = 0) {
+        const rx = (sx - this.W / 2) / this.focal, ry = -(sy - this.H / 2) / this.focal;
+        const dir = norm(add(add(this.fw, scale(this.rt, rx)), scale(this.up, ry)));
+        if (Math.abs(dir.y) < 1e-5)
+            return null;
+        const s = (planeY - this.cx.y) / dir.y;
+        if (s < this.zNear)
+            return null;
+        return add(this.cx, scale(dir, s));
+    }
+    get surface() { return this.canvas; }
+    // ── uniform helpers ──
+    setGroups(p) {
+        const gl = this.gl;
+        gl.uniformMatrix4fv(p.u("uGM[0]"), false, this.groupMat);
+        gl.uniformMatrix3fv(p.u("uNM[0]"), false, this.groupNM);
+        gl.uniform1fv(p.u("uMW[0]"), this.groupMorph);
+        gl.uniform1fv(p.u("uGA[0]"), this.groupAlpha);
+    }
+    setVP(p) {
+        this.gl.uniformMatrix4fv(p.u("uVP"), false, this.vp);
+        this.setGroups(p);
+    }
+    setFog(p, fogK) {
+        this.gl.uniform1f(p.u("uFogK"), fogK);
+        this.gl.uniform1f(p.u("uInk"), this.ink ? 1 : 0);
+    }
+    setLights(p, fogK) {
+        const gl = this.gl, L = norm(this.light.dir);
+        gl.uniform3f(p.u("uLdir"), L.x, L.y, L.z);
+        gl.uniform1f(p.u("uAmb"), this.ink ? Math.min(1, this.light.ambient + 0.22) : this.light.ambient);
+        gl.uniform1f(p.u("uDif"), this.ink ? this.light.diffuse * 0.55 : this.light.diffuse);
+        gl.uniform1f(p.u("uSigned"), this.light.signed ? 1 : 0);
+        gl.uniform3f(p.u("uCam"), this.cx.x, this.cx.y, this.cx.z);
+        gl.uniform1f(p.u("uSpec"), this.specular);
+        gl.uniform1f(p.u("uPulse"), this.bloodPulse);
+        gl.uniform3f(p.u("uBg"), this.bg[0], this.bg[1], this.bg[2]);
+        gl.uniform3f(p.u("uSkyC"), this.ambientSky.x, this.ambientSky.y, this.ambientSky.z);
+        gl.uniform3f(p.u("uGroundC"), this.ambientGround.x, this.ambientGround.y, this.ambientGround.z);
+        gl.uniformMatrix4fv(p.u("uSVP"), false, this.svp);
+        const shOn = this.shadowsOn && this.shadowTex && this.lights.length > 0;
+        gl.uniform1f(p.u("uShadowOn"), shOn ? 1 : 0);
+        gl.uniform1f(p.u("uShadowSoft"), this.shadowSoft);
+        gl.uniform1f(p.u("uShadowBias"), this.shadowBias);
+        gl.uniform1f(p.u("uShadowPx"), 1 / this.shadowSize);
+        if (this.shadowTex) {
+            gl.activeTexture(gl.TEXTURE0);
+            gl.bindTexture(gl.TEXTURE_2D, this.shadowTex);
+            gl.uniform1i(p.u("uShadow"), 0);
+        }
+        gl.uniform1f(p.u("uFogK"), fogK);
+        const n = Math.min(8, this.lights.length);
+        gl.uniform1i(p.u("uLn"), n);
+        const lp = new Float32Array(24), li = new Float32Array(8), lf = new Float32Array(8);
+        for (let i = 0; i < n; i++) {
+            lp[i * 3] = this.lights[i].p.x;
+            lp[i * 3 + 1] = this.lights[i].p.y;
+            lp[i * 3 + 2] = this.lights[i].p.z;
+            li[i] = this.lights[i].intensity;
+            lf[i] = this.lights[i].falloff;
+        }
+        gl.uniform3fv(p.u("uLp[0]"), lp);
+        gl.uniform1fv(p.u("uLi[0]"), li);
+        gl.uniform1fv(p.u("uLf[0]"), lf);
+    }
+    attrib(p, name, size, stride, off) {
+        const gl = this.gl, loc = gl.getAttribLocation(p.prog, name);
+        if (loc < 0)
+            return;
+        gl.enableVertexAttribArray(loc);
+        gl.vertexAttribPointer(loc, size, gl.FLOAT, false, stride * 4, off * 4);
+    }
+    // ── draw helpers ──
+    depthDraw(buf, verts) {
+        if (!verts)
+            return;
+        const gl = this.gl;
+        gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+        this.attrib(this.pDepth, "aPos", 3, FACE_STRIDE, 0);
+        this.attrib(this.pDepth, "aGrp", 1, FACE_STRIDE, 11);
+        this.attrib(this.pDepth, "aPos2", 3, FACE_STRIDE, 12);
+        gl.drawArrays(gl.TRIANGLES, 0, verts);
+    }
+    drawFaces(buf, verts, dyn) {
+        if (!verts)
+            return;
+        const gl = this.gl;
+        gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+        if (dyn)
+            gl.bufferData(gl.ARRAY_BUFFER, dyn, gl.DYNAMIC_DRAW);
+        this.attrib(this.pFace, "aPos", 3, FACE_STRIDE, 0);
+        this.attrib(this.pFace, "aNorm", 3, FACE_STRIDE, 3);
+        this.attrib(this.pFace, "aCol", 4, FACE_STRIDE, 6);
+        this.attrib(this.pFace, "aBlood", 1, FACE_STRIDE, 10);
+        this.attrib(this.pFace, "aGrp", 1, FACE_STRIDE, 11);
+        this.attrib(this.pFace, "aPos2", 3, FACE_STRIDE, 12);
+        this.attrib(this.pFace, "aNorm2", 3, FACE_STRIDE, 15);
+        gl.drawArrays(gl.TRIANGLES, 0, verts);
+    }
+    drawLines(buf, verts, dyn) {
+        if (!verts)
+            return;
+        const gl = this.gl;
+        gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+        if (dyn)
+            gl.bufferData(gl.ARRAY_BUFFER, dyn, gl.DYNAMIC_DRAW);
+        this.attrib(this.pLine, "aPos", 3, LINE_STRIDE, 0);
+        this.attrib(this.pLine, "aCol", 4, LINE_STRIDE, 3);
+        this.attrib(this.pLine, "aGrp", 1, LINE_STRIDE, 7);
+        gl.drawArrays(gl.LINES, 0, verts);
+    }
+    drawPts(buf, verts, dyn) {
+        if (!verts)
+            return;
+        const gl = this.gl;
+        gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+        if (dyn)
+            gl.bufferData(gl.ARRAY_BUFFER, dyn, gl.DYNAMIC_DRAW);
+        this.attrib(this.pPt, "aPos", 3, PT_STRIDE, 0);
+        this.attrib(this.pPt, "aSize", 1, PT_STRIDE, 3);
+        this.attrib(this.pPt, "aCol", 4, PT_STRIDE, 4);
+        this.attrib(this.pPt, "aGrp", 1, PT_STRIDE, 8);
+        gl.drawArrays(gl.POINTS, 0, verts);
+    }
+    drawRibbons(buf, verts, dyn) {
+        if (!verts)
+            return;
+        const gl = this.gl;
+        gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+        if (dyn)
+            gl.bufferData(gl.ARRAY_BUFFER, dyn, gl.DYNAMIC_DRAW);
+        this.attrib(this.pRib, "aPos", 3, RIB_STRIDE, 0);
+        this.attrib(this.pRib, "aPrev", 3, RIB_STRIDE, 3);
+        this.attrib(this.pRib, "aNext", 3, RIB_STRIDE, 6);
+        this.attrib(this.pRib, "aSide", 1, RIB_STRIDE, 9);
+        this.attrib(this.pRib, "aWidth", 1, RIB_STRIDE, 10);
+        this.attrib(this.pRib, "aCol", 4, RIB_STRIDE, 11);
+        this.attrib(this.pRib, "aGrp", 1, RIB_STRIDE, 15);
+        gl.drawArrays(gl.TRIANGLES, 0, verts);
+    }
+    // ── the frame ──
+    renderFrame(t, dt) {
+        const gl = this.gl;
+        this.lastT = t;
+        this.setupCamera(t, dt);
+        this.fLight.length = 0;
+        this.fRib.length = 0;
+        this.dFaceA.length = 0;
+        this.dLineA.length = 0;
+        this.dPtA.length = 0;
+        this.dRibA.length = 0;
+        for (const fn of this.hooks)
+            fn(t, dt, this);
+        this.labels.length = 0;
+        for (const rec of this.fLight) {
+            if (rec.k === "label") {
+                this.labels.push(rec);
+                continue;
+            }
+            if (rec.k === "glow") {
+                const [r, g, b] = rec.hue == null ? (this.ink ? [0.16, 0.15, 0.24] : [1, 1, 1]) : this.col(rec.hue, 85, 62);
+                this.dPtA.push(rec.p.x, rec.p.y, rec.p.z, rec.size, r, g, b, clamp(rec.alpha, 0, 1), 0);
+            }
+            else if (rec.k === "line") {
+                const [r, g, b] = this.parseCol(rec.color);
+                this.dLineA.push(rec.a.x, rec.a.y, rec.a.z, r, g, b, rec.alpha, 0, rec.b.x, rec.b.y, rec.b.z, r, g, b, rec.alpha, 0);
+            }
+            else if (rec.k === "poly") {
+                const [r, g, b] = this.parseCol(rec.color);
+                for (let i = 1; i < rec.pts.length; i++) {
+                    const a = rec.pts[i - 1].p, q = rec.pts[i].p;
+                    this.dLineA.push(a.x, a.y, a.z, r, g, b, rec.alpha, 0, q.x, q.y, q.z, r, g, b, rec.alpha, 0);
+                }
+            }
+        }
+        for (const rb of this.fRib)
+            this.pushRibbon(this.dRibA, rb.pts, rb.o);
+        const fogK = this.cam.dist * 0.9;
+        for (let i = 0; i < 8; i++) { // eased group alphas + morph weights
+            this.groupAlpha[i] += (this.groupTarget[i] - this.groupAlpha[i]) * Math.min(1, dt * 6);
+            this.groupMorph[i] += (this.groupMorphT[i] - this.groupMorph[i]) * Math.min(1, dt * 6);
+        }
+        if (this.staticDirty) {
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.bFace);
+            gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(this.sFace), gl.STATIC_DRAW);
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.bLine);
+            gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(this.sLine), gl.STATIC_DRAW);
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.bPt);
+            gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(this.sPt), gl.STATIC_DRAW);
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.bRib);
+            gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(this.sRib), gl.STATIC_DRAW);
+            this.staticDirty = false;
+        }
+        if (this.dFaceA.length) {
+            gl.bindBuffer(gl.ARRAY_BUFFER, this.bFaceD);
+            gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(this.dFaceA), gl.DYNAMIC_DRAW);
+        }
+        // the shadow pass: the world as lights[0] sees it, into a REAL depth texture
+        if (this.shadowsOn && this.shadowFBO && this.lights.length) {
+            const lp = this.lights[0].p;
+            const dir = norm(sub(this.cam.target, lp));
+            const up = Math.abs(dir.y) > 0.95 ? v3(1, 0, 0) : v3(0, 1, 0);
+            this.svp = mMul(mPerspective(1.15, 1, 40, 3500), mLookAt(lp, this.cam.target, up));
+            gl.bindFramebuffer(gl.FRAMEBUFFER, this.shadowFBO);
+            gl.viewport(0, 0, this.shadowSize, this.shadowSize);
+            gl.enable(gl.DEPTH_TEST);
+            gl.depthMask(true);
+            gl.disable(gl.BLEND);
+            gl.clear(gl.DEPTH_BUFFER_BIT);
+            this.pDepth.use();
+            gl.uniformMatrix4fv(this.pDepth.u("uVP"), false, this.svp);
+            this.setGroups(this.pDepth);
+            this.depthDraw(this.bFace, this.sFace.length / FACE_STRIDE);
+            if (this.dFaceA.length) {
+                gl.bindBuffer(gl.ARRAY_BUFFER, this.bFaceD);
+                this.depthDraw(this.bFaceD, this.dFaceA.length / FACE_STRIDE);
+            }
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+        }
+        // the scene pass — into the HDR target when the post chain is on
+        if (this.post)
+            this.post.begin();
+        else {
+            gl.bindFramebuffer(gl.FRAMEBUFFER, null);
+            gl.viewport(0, 0, this.canvas.width, this.canvas.height);
+        }
+        if (this.transparent)
+            gl.clearColor(0, 0, 0, 0);
+        else
+            gl.clearColor(this.bg[0], this.bg[1], this.bg[2], 1);
+        gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);
+        // solids — depth-written, per-pixel lit, shadowed
+        gl.enable(gl.DEPTH_TEST);
+        gl.depthMask(true);
+        gl.disable(gl.BLEND);
+        this.pFace.use();
+        this.setVP(this.pFace);
+        this.setLights(this.pFace, fogK);
+        this.drawFaces(this.bFace, this.sFace.length / FACE_STRIDE, null);
+        if (this.dFaceA.length)
+            this.drawFaces(this.bFaceD, this.dFaceA.length / FACE_STRIDE, new Float32Array(this.dFaceA));
+        // the light — additive, depth-TESTED but not written (ink: normal alpha blend)
+        gl.depthMask(false);
+        gl.enable(gl.BLEND);
+        if (this.ink)
+            gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA);
+        else
+            gl.blendFunc(gl.ONE, gl.ONE);
+        this.pLine.use();
+        this.setVP(this.pLine);
+        this.setFog(this.pLine, fogK);
+        this.drawLines(this.bLine, this.sLine.length / LINE_STRIDE, null);
+        if (this.dLineA.length)
+            this.drawLines(this.bLineD, this.dLineA.length / LINE_STRIDE, new Float32Array(this.dLineA));
+        this.pRib.use();
+        this.setVP(this.pRib);
+        this.setFog(this.pRib, fogK);
+        this.gl.uniform2f(this.pRib.u("uRes"), this.W, this.H);
+        this.drawRibbons(this.bRib, this.sRib.length / RIB_STRIDE, null);
+        if (this.dRibA.length)
+            this.drawRibbons(this.bRibD, this.dRibA.length / RIB_STRIDE, new Float32Array(this.dRibA));
+        this.pPt.use();
+        this.setVP(this.pPt);
+        this.setFog(this.pPt, fogK);
+        gl.uniform1f(this.pPt.u("uFocal"), this.focal * (this.canvas.width / Math.max(1, this.W)));
+        this.drawPts(this.bPt, this.sPt.length / PT_STRIDE, null);
+        if (this.dPtA.length)
+            this.drawPts(this.bPtD, this.dPtA.length / PT_STRIDE, new Float32Array(this.dPtA));
+        gl.depthMask(true);
+        // the post chain: bloom + SSAO + composite (+ FXAA) to the canvas
+        if (this.post) {
+            gl.disable(gl.BLEND);
+            this.post.end({
+                bloomOn: this.bloom.on && !this.ink, // bloom is light-on-dark; paper does not glow
+                bloomThreshold: this.bloom.threshold, bloomKnee: this.bloom.knee, bloomStrength: this.bloom.strength,
+                ssaoOn: this.ssao.on, ssaoStrength: this.ssao.strength, ssaoRadius: this.ssao.radius,
+                filmic: this.filmic && !this.ink, grade: this.grade, vignette: this.vignette, ink: this.ink,
+                fxaa: this.fxaa, near: this.zNear, far: this.zFar,
+            });
+        }
+        // labels — 2D overlay, never occluded (the honest exception)
+        this.og.clearRect(0, 0, this.W, this.H);
+        this.og.font = "600 11px ui-monospace, Menlo, monospace";
+        this.og.textAlign = "center";
+        this.og.textBaseline = "middle";
+        for (const l of this.labels) {
+            const q = this.project(l.p);
+            if (!q)
+                continue;
+            this.og.globalAlpha = clamp(l.alpha, 0, 1);
+            this.og.fillStyle = this.themedCss(l.color);
+            this.og.fillText(l.text, q.x, q.y + l.dy);
+        }
+        this.og.globalAlpha = 1;
+        if (this.vignette > 0 && !this.post) { // overlay fallback when the chain is off
+            const g = this.og, W = this.W, H = this.H;
+            const grd = g.createRadialGradient(W / 2, H * 0.46, Math.min(W, H) * 0.28, W / 2, H / 2, Math.max(W, H) * 0.72);
+            grd.addColorStop(0, "rgba(0,0,0,0)");
+            grd.addColorStop(1, this.ink ? `rgba(52,48,76,${this.vignette * 0.3})` : `rgba(6,4,14,${this.vignette})`);
+            g.fillStyle = grd;
+            g.fillRect(0, 0, W, H);
+        }
+    }
+    start() {
+        const frame = (ts) => {
+            if (this.disposed)
+                return;
+            if (!this.t0) {
+                this.t0 = ts;
+                this.tPrev = ts;
+            }
+            const t = (ts - this.t0) / 1000;
+            const dt = Math.min(0.05, (ts - this.tPrev) / 1000);
+            this.tPrev = ts;
+            this.renderFrame(t, dt);
+            this.raf = !document.hidden ? requestAnimationFrame(frame) : 0;
+        };
+        this.raf = requestAnimationFrame(frame);
+        const onVis = () => {
+            if (!document.hidden && !this.raf && !this.disposed) {
+                this.tPrev = performance.now();
+                this.raf = requestAnimationFrame(frame);
+            }
+        };
+        document.addEventListener("visibilitychange", onVis);
+        this.cleanup.push(() => document.removeEventListener("visibilitychange", onVis));
+    }
+    /** Render one deterministic frame at time t (no loop) — stills, tests, screenshots. */
+    settle(t) { this.renderFrame(t, 0); }
+    /** Stop the world. `releaseContext: true` also LOSES the GL context immediately —
+     *  browsers cap live contexts per page and reclaim them only at GC, so many-canvas
+     *  pages must release on teardown. A lost context is permanently dead on its canvas:
+     *  a releasing caller must mount a FRESH canvas to build again (React: key it). */
+    dispose(releaseContext = false) {
+        this.disposed = true;
+        cancelAnimationFrame(this.raf);
+        this.raf = 0;
+        for (const c of this.cleanup)
+            c();
+        this.cleanup = [];
+        this.overlay.remove();
+        this.post?.dispose();
+        if (releaseContext)
+            this.gl.getExtension("WEBGL_lose_context")?.loseContext();
+    }
+}
+export function createWorld(o) { return new World(o); }