@chromatic-coherence/generative-engine 1.0.3 → 1.2.0

package/README.md

@@ -49,6 +49,46 @@ w.start();
 **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.
 
+## Objectives — scenes that know where they're going
+
+A scene gets a **goal** and the engine drives motion toward it; a live **movement meter**
+tells you whether the scene is moving or settled — and names what is moving.
+
+```ts
+import { createWorld, attachObjectives } from "@chromatic-coherence/generative-engine";
+
+const w = createWorld({ canvas });
+const obj = attachObjectives(w);
+
+obj.define("reveal", {
+  morph:  { group: "terrain", to: 1 },     // blend the terrain to its B shape
+  camera: { dist: 420, pitch: 0.62 },      // settle the camera in close
+  fade:   { group: "veil", to: 0 },        // dissolve the veil
+  pace: 3,                                 // seconds to ~95% of the way there
+});
+
+obj.onReading(r => {
+  // { name, progress, level, floor, moving, settled, driving: ["morph:terrain","camera",...] }
+  if (r.settled) console.log(`${r.name}: settled`);
+});
+
+// later — the goal itself moves; motion continues from the current state, no snap,
+// and the meter lights up again:
+obj.retarget("reveal", { camera: { dist: 300 } });
+```
+
+Channels: `transform` (group rigid-body spec) · `morph` · `fade` · `camera` · `custom`
+(an `apply(progress, dt)` escape hatch). `readings()` is the pull form of `onReading`.
+
+**The meter's semantics** come from the objective-movement measurement work this engine's
+org ran first as science: movement is a **level sustained above a settled floor**, not a
+discrete event. `driving` names the elevated channels — movement you can name; `settled`
+is the sustained fall to the floor. Options: `attachObjectives(w, { floor, settleAfter })`.
+
+The layer rides the frame loop as a `grow()` hook and drives the World through its public
+verbs only — the renderer is untouched, and everything composes with hand-written `grow()`
+animation.
+
 ## Demo
 
 `demo/index.html` — serve the package folder (`python -m http.server`) and open
@@ -62,9 +102,19 @@ engine → charts-3d → charts-2d is three imports of the same code. Browsers c
 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).
 
+## Instancing, depth of field, motion blur (v1.2)
+
+- **`w.meshInstanced(geo, transforms, opts)`** — upload a mesh once, draw it at every
+  transform in a single instanced call, shadow pass included. A forest is one draw.
+  Instances ride their group's fade / morph / transform like any other geometry.
+- **`w.dof = { on, focus, range, maxBlur }`** — depth of field: blur grows with distance
+  from the focus plane (world units), sharp subjects protected per-tap.
+- **`w.motionBlur = { on, strength }`** — camera motion blur by depth reprojection into
+  the previous frame; streaks clamp to 4 % of the screen.
+
 ## Roadmap
 
-Planar mirrors · instancing · depth of field · motion blur. The chart editions stay lean.
+Planar mirrors. The chart editions stay lean.
 
 ## Licence
 

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/objectives.d.ts

@@ -0,0 +1,96 @@
+import { V3, TransformSpec } from "./math.js";
+import type { World } from "./world.js";
+export type ObjectiveCamera = {
+    target?: V3;
+    dist?: number;
+    pitch?: number;
+    yaw?: number;
+};
+export type ObjectiveSpec = {
+    /** rigid-body goal for a named group — interpolated spec, applied via setTransform */
+    transform?: {
+        group: string;
+        to: TransformSpec;
+        from?: TransformSpec;
+    };
+    /** morph-weight goal for a named group (meshMorph geometry). Default from: 0. */
+    morph?: {
+        group: string;
+        to: number;
+        from?: number;
+    };
+    /** fade goal for a named group. Default from: 1. */
+    fade?: {
+        group: string;
+        to: number;
+        from?: number;
+    };
+    /** camera goal — absent fields keep the camera's current value */
+    camera?: ObjectiveCamera;
+    /** escape hatch — called every tick with eased progress 0..1 */
+    custom?: (progress: number, dt: number) => void;
+    /** seconds to ~95 % of the way there. Default 3. */
+    pace?: number;
+};
+/** One tick's reading for one objective — the movement meter's voice. */
+export type MovementReading = {
+    name: string;
+    /** eased approach to the goal, 0..1 */
+    progress: number;
+    /** movement level this tick (≈ 1 at a fresh goal, decaying toward 0) */
+    level: number;
+    /** the settled floor the level is read against */
+    floor: number;
+    /** level is above the floor */
+    moving: boolean;
+    /** level has stayed at/below the floor for settleAfter seconds */
+    settled: boolean;
+    /** the channels currently elevated — the movement you can name */
+    driving: string[];
+};
+export type ObjectivesOpts = {
+    /** the settled floor (movement level units). Default 0.02. */
+    floor?: number;
+    /** seconds the level must hold at/below the floor to read settled. Default 0.6. */
+    settleAfter?: number;
+};
+/** Channel writes, injected — a World in production, plain recorders in tests. */
+export type ChannelAppliers = {
+    transform(group: string, spec: TransformSpec): void;
+    morph(group: string, weight: number): void;
+    fade(group: string, alpha: number): void;
+    camera(c: ObjectiveCamera): void;
+};
+export declare class ObjectivesCore {
+    private apply;
+    private objs;
+    private listeners;
+    private floor;
+    private settleAfter;
+    constructor(apply: ChannelAppliers, opts?: ObjectivesOpts);
+    /** Define (or wholly replace) a named objective. The drive starts on the next tick. */
+    define(name: string, spec: ObjectiveSpec, camNow?: ObjectiveCamera): void;
+    /** Move a live objective's goal — progress restarts FROM THE CURRENT STATE (no snap)
+     *  and the meter lights up again. Channels absent from the patch keep their goal. */
+    retarget(name: string, patch: Partial<ObjectiveSpec>, camNow?: ObjectiveCamera): void;
+    /** Forget an objective — its channels stay wherever they were last driven to. */
+    remove(name: string): void;
+    /** Subscribe to per-tick readings (one call per live objective per tick). */
+    onReading(cb: (r: MovementReading) => void): () => void;
+    /** Pull the latest readings — the same objects the callbacks saw. */
+    readings(): MovementReading[];
+    /** Advance every objective by dt seconds and apply the driven values.
+     *  dt <= 0 (settle() stills) re-applies values without advancing the meter. */
+    tick(dt: number): void;
+}
+/** The user-facing facade returned by attachObjectives(). */
+export type Objectives = {
+    define(name: string, spec: ObjectiveSpec): void;
+    retarget(name: string, patch: Partial<ObjectiveSpec>): void;
+    remove(name: string): void;
+    onReading(cb: (r: MovementReading) => void): () => void;
+    readings(): MovementReading[];
+};
+/** 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. */
+export declare function attachObjectives(world: World, opts?: ObjectivesOpts): Objectives;

package/dist/objectives.js

@@ -0,0 +1,174 @@
+// generative-engine — objectives.ts: THE OBJECTIVES LAYER. A scene gets a goal and the
+// engine drives motion toward it; a live movement meter reads whether the scene is
+// moving or settled, and names what is moving.
+//
+// Two layers, deliberately split:
+//   ObjectivesCore  — pure logic, no GL, no DOM. Channel writes go through injected
+//                     appliers, so the core runs (and is tested) under bare node.
+//   attachObjectives(world) — the binder: wires the core to a World through its PUBLIC
+//                     verbs only (grow / setTransform / morph / fade / cam). world.ts
+//                     is untouched by this layer.
+//
+// The meter's lineage (documented, not mystified): it is the regime measure from the
+// objective-movement work (science/walk/station-23) carried into engineering — movement
+// is a LEVEL sustained above a settled FLOOR, not a discrete event. `driving` names the
+// elevated channels — the movement you can name; `settled` is the sustained fall to the
+// floor: the turn you cannot name is the stop.
+import { v3, clamp } from "./math.js";
+const lerp = (a, b, t) => a + (b - a) * t;
+const lerpV3 = (a, b, t) => v3(lerp(a.x, b.x, t), lerp(a.y, b.y, t), lerp(a.z, b.z, t));
+const asV3 = (s, d) => s == null ? v3(d, d, d) : typeof s === "number" ? v3(s, s, s) : s;
+function lerpSpec(a, b, t) {
+    return {
+        translate: lerpV3(a.translate ?? v3(), b.translate ?? v3(), t),
+        rotateX: lerp(a.rotateX ?? 0, b.rotateX ?? 0, t),
+        rotateY: lerp(a.rotateY ?? 0, b.rotateY ?? 0, t),
+        rotateZ: lerp(a.rotateZ ?? 0, b.rotateZ ?? 0, t),
+        scale: lerpV3(asV3(a.scale, 1), asV3(b.scale, 1), t),
+    };
+}
+export class ObjectivesCore {
+    constructor(apply, opts = {}) {
+        this.apply = apply;
+        this.objs = new Map();
+        this.listeners = [];
+        this.floor = opts.floor ?? 0.02;
+        this.settleAfter = opts.settleAfter ?? 0.6;
+    }
+    /** Define (or wholly replace) a named objective. The drive starts on the next tick. */
+    define(name, spec, camNow) {
+        this.objs.set(name, {
+            name, spec,
+            k: 3 / Math.max(0.05, spec.pace ?? 3),
+            progress: 0, level: 1, atFloorFor: 0,
+            camFrom: spec.camera ? (camNow ?? {}) : null,
+            reading: { name, progress: 0, level: 1, floor: this.floor, moving: true, settled: false, driving: [] },
+        });
+    }
+    /** Move a live objective's goal — progress restarts FROM THE CURRENT STATE (no snap)
+     *  and the meter lights up again. Channels absent from the patch keep their goal. */
+    retarget(name, patch, camNow) {
+        const o = this.objs.get(name);
+        if (!o)
+            throw new Error(`generative-engine objectives: retarget of unknown objective "${name}"`);
+        const s = o.spec, p = o.progress;
+        const next = { ...s, ...patch };
+        // continuity: each patched channel's new `from` is the value currently applied
+        if (patch.transform && s.transform)
+            next.transform = { ...patch.transform, from: lerpSpec(s.transform.from ?? {}, s.transform.to, p) };
+        if (patch.morph && s.morph)
+            next.morph = { ...patch.morph, from: lerp(s.morph.from ?? 0, s.morph.to, p) };
+        if (patch.fade && s.fade)
+            next.fade = { ...patch.fade, from: lerp(s.fade.from ?? 1, s.fade.to, p) };
+        const camFrom = patch.camera ? (camNow ?? o.camFrom ?? {}) : o.camFrom;
+        this.objs.set(name, {
+            name, spec: next,
+            k: 3 / Math.max(0.05, next.pace ?? 3),
+            progress: 0, level: 1, atFloorFor: 0,
+            camFrom,
+            reading: o.reading,
+        });
+    }
+    /** Forget an objective — its channels stay wherever they were last driven to. */
+    remove(name) { this.objs.delete(name); }
+    /** Subscribe to per-tick readings (one call per live objective per tick). */
+    onReading(cb) {
+        this.listeners.push(cb);
+        return () => { const i = this.listeners.indexOf(cb); if (i >= 0)
+            this.listeners.splice(i, 1); };
+    }
+    /** Pull the latest readings — the same objects the callbacks saw. */
+    readings() {
+        return [...this.objs.values()].map(o => o.reading);
+    }
+    /** Advance every objective by dt seconds and apply the driven values.
+     *  dt <= 0 (settle() stills) re-applies values without advancing the meter. */
+    tick(dt) {
+        for (const o of this.objs.values()) {
+            if (dt > 0) {
+                o.progress += (1 - o.progress) * Math.min(1, dt * o.k);
+                // the level is the drive still outstanding — ≈1 at a fresh goal, easing to 0.
+                // A retarget resets progress, so the level re-elevates: movement is a REGIME.
+                o.level = 1 - o.progress;
+                if (o.level <= this.floor)
+                    o.atFloorFor += dt;
+                else
+                    o.atFloorFor = 0;
+            }
+            const p = o.progress, s = o.spec;
+            const driving = [];
+            const moving = o.level > this.floor;
+            if (s.transform) {
+                this.apply.transform(s.transform.group, lerpSpec(s.transform.from ?? {}, s.transform.to, p));
+                if (moving)
+                    driving.push(`transform:${s.transform.group}`);
+            }
+            if (s.morph) {
+                this.apply.morph(s.morph.group, clamp(lerp(s.morph.from ?? 0, s.morph.to, p), 0, 1));
+                if (moving)
+                    driving.push(`morph:${s.morph.group}`);
+            }
+            if (s.fade) {
+                this.apply.fade(s.fade.group, clamp(lerp(s.fade.from ?? 1, s.fade.to, p), 0, 1));
+                if (moving)
+                    driving.push(`fade:${s.fade.group}`);
+            }
+            if (s.camera && o.camFrom) {
+                const c = s.camera, f = o.camFrom, out = {};
+                if (c.target)
+                    out.target = lerpV3(f.target ?? c.target, c.target, p);
+                if (c.dist != null)
+                    out.dist = lerp(f.dist ?? c.dist, c.dist, p);
+                if (c.pitch != null)
+                    out.pitch = lerp(f.pitch ?? c.pitch, c.pitch, p);
+                if (c.yaw != null)
+                    out.yaw = lerp(f.yaw ?? c.yaw, c.yaw, p);
+                this.apply.camera(out);
+                if (moving)
+                    driving.push("camera");
+            }
+            if (s.custom) {
+                s.custom(p, Math.max(0, dt));
+                if (moving)
+                    driving.push("custom");
+            }
+            o.reading = {
+                name: o.name, progress: p, level: o.level, floor: this.floor,
+                moving, settled: !moving && o.atFloorFor >= this.settleAfter, driving,
+            };
+            for (const cb of this.listeners)
+                cb(o.reading);
+        }
+    }
+}
+/** 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. */
+export function attachObjectives(world, opts = {}) {
+    const core = new ObjectivesCore({
+        transform: (g, spec) => world.setTransform(g, spec),
+        morph: (g, w) => world.morph(g, w),
+        fade: (g, a) => world.fade(g, a),
+        camera: (c) => {
+            if (c.target)
+                world.cam.target = c.target;
+            if (c.dist != null)
+                world.cam.distT = c.dist;
+            if (c.pitch != null)
+                world.cam.pitch = c.pitch;
+            if (c.yaw != null)
+                world.cam.yawBase = c.yaw;
+        },
+    }, opts);
+    const camNow = () => ({
+        target: world.cam.target, dist: world.cam.distT,
+        pitch: world.cam.pitch, yaw: world.cam.yawBase,
+    });
+    world.grow((_t, dt) => core.tick(dt));
+    return {
+        define: (name, spec) => core.define(name, spec, camNow()),
+        retarget: (name, patch) => core.retarget(name, patch, camNow()),
+        remove: (name) => core.remove(name),
+        onReading: (cb) => core.onReading(cb),
+        readings: () => core.readings(),
+    };
+}

package/dist/post.d.ts

@@ -23,6 +23,16 @@ export type PostParams = {
     fxaa: boolean;
     near: number;
     far: number;
+    /** depth of field (W8): blur scaled by distance from the focus plane */
+    dofOn?: boolean;
+    dofFocus?: number;
+    dofRange?: number;
+    dofMaxBlur?: number;
+    /** camera motion blur (W8): depth reprojection into the previous frame */
+    moOn?: boolean;
+    moStrength?: number;
+    invVP?: Float32Array;
+    prevVP?: Float32Array;
 };
 export declare class PostChain {
     readonly hdr: boolean;
@@ -33,6 +43,8 @@ export declare class PostChain {
     private pAoBlur;
     private pComposite;
     private pFxaa;
+    private pDof;
+    private pMoblur;
     private scene;
     sceneDepth: WebGLTexture | null;
     private bloomA;
@@ -40,6 +52,7 @@ export declare class PostChain {
     private aoA;
     private aoB;
     private ldr;
+    private ldrB;
     private W;
     private H;
     constructor(gl: WebGL2RenderingContext);

package/dist/post.js

@@ -4,7 +4,7 @@
 // texture; then bright-pass -> half-res separable gaussian (ping-pong) for
 // bloom, depth-based half-res SSAO + blur, one composite pass (bloom add,
 // ACES filmic, grade, vignette), and an optional FXAA pass last.
-import { FST_VS, BRIGHT_FS, BLUR_FS, SSAO_FS, AOBLUR_FS, COMPOSITE_FS, FXAA_FS, } from "./shaders.js";
+import { FST_VS, BRIGHT_FS, BLUR_FS, SSAO_FS, AOBLUR_FS, COMPOSITE_FS, FXAA_FS, DOF_FS, MOBLUR_FS, } from "./shaders.js";
 export function makeProg(gl, vs, fs) {
     const sh = (type, src) => {
         const s = gl.createShader(type);
@@ -48,6 +48,7 @@ export class PostChain {
         this.aoA = null;
         this.aoB = null;
         this.ldr = null;
+        this.ldrB = null;
         this.W = 0;
         this.H = 0;
         this.gl = gl;
@@ -58,6 +59,8 @@ export class PostChain {
         this.pAoBlur = new PInfo(gl, FST_VS, AOBLUR_FS);
         this.pComposite = new PInfo(gl, FST_VS, COMPOSITE_FS);
         this.pFxaa = new PInfo(gl, FST_VS, FXAA_FS);
+        this.pDof = new PInfo(gl, FST_VS, DOF_FS);
+        this.pMoblur = new PInfo(gl, FST_VS, MOBLUR_FS);
     }
     makeTarget(w, h, hdrFmt, filter) {
         const gl = this.gl;
@@ -114,6 +117,7 @@ export class PostChain {
         this.aoA = this.makeTarget(hw, hh, false, gl.LINEAR);
         this.aoB = this.makeTarget(hw, hh, false, gl.LINEAR);
         this.ldr = this.makeTarget(w, h, false, gl.LINEAR);
+        this.ldrB = this.makeTarget(w, h, false, gl.LINEAR);
         gl.bindFramebuffer(gl.FRAMEBUFFER, null);
     }
     /** Bind the scene target — the world's render pass draws into this. */
@@ -173,6 +177,9 @@ export class PostChain {
             gl.uniform2f(this.pAoBlur.u("uPx"), 1 / this.aoA.w, 1 / this.aoA.h);
             this.fst(this.pAoBlur, this.aoB);
         }
+        // remaining LDR passes after composite — each renders src -> dst (null = the canvas)
+        const dofOn = !!o.dofOn, moOn = !!(o.moOn && o.invVP && o.prevVP);
+        const tail = (dofOn ? 1 : 0) + (moOn ? 1 : 0) + (o.fxaa ? 1 : 0);
         this.pComposite.use();
         this.bindTex(0, this.scene.tex);
         this.bindTex(1, o.bloomOn ? this.bloomA.tex : null);
@@ -186,10 +193,42 @@ export class PostChain {
         gl.uniform1f(this.pComposite.u("uGrade"), o.grade ? 1 : 0);
         gl.uniform1f(this.pComposite.u("uVig"), o.vignette);
         gl.uniform1f(this.pComposite.u("uInk"), o.ink ? 1 : 0);
-        this.fst(this.pComposite, o.fxaa ? this.ldr : null);
+        let src = tail > 0 ? this.ldr : null;
+        this.fst(this.pComposite, src);
+        let left = tail;
+        const next = () => (--left > 0 ? (src === this.ldr ? this.ldrB : this.ldr) : null);
+        if (dofOn) {
+            const dst = next();
+            this.pDof.use();
+            this.bindTex(0, src.tex);
+            this.bindTex(1, this.sceneDepth);
+            gl.uniform1i(this.pDof.u("uTex"), 0);
+            gl.uniform1i(this.pDof.u("uDepth"), 1);
+            gl.uniform1f(this.pDof.u("uNear"), o.near);
+            gl.uniform1f(this.pDof.u("uFar"), o.far);
+            gl.uniform1f(this.pDof.u("uFocus"), o.dofFocus ?? 700);
+            gl.uniform1f(this.pDof.u("uRange"), o.dofRange ?? 420);
+            gl.uniform1f(this.pDof.u("uMaxBlur"), o.dofMaxBlur ?? 10);
+            gl.uniform2f(this.pDof.u("uPx"), 1 / this.W, 1 / this.H);
+            this.fst(this.pDof, dst);
+            src = dst;
+        }
+        if (moOn) {
+            const dst = next();
+            this.pMoblur.use();
+            this.bindTex(0, src.tex);
+            this.bindTex(1, this.sceneDepth);
+            gl.uniform1i(this.pMoblur.u("uTex"), 0);
+            gl.uniform1i(this.pMoblur.u("uDepth"), 1);
+            gl.uniformMatrix4fv(this.pMoblur.u("uInvVP"), false, o.invVP);
+            gl.uniformMatrix4fv(this.pMoblur.u("uPrevVP"), false, o.prevVP);
+            gl.uniform1f(this.pMoblur.u("uStrength"), o.moStrength ?? 0.6);
+            this.fst(this.pMoblur, dst);
+            src = dst;
+        }
         if (o.fxaa) {
             this.pFxaa.use();
-            this.bindTex(0, this.ldr.tex);
+            this.bindTex(0, src.tex);
             gl.uniform1i(this.pFxaa.u("uTex"), 0);
             gl.uniform2f(this.pFxaa.u("uPx"), 1 / this.W, 1 / this.H);
             this.fst(this.pFxaa, null);
@@ -205,9 +244,10 @@ export class PostChain {
         this.drop(this.aoA);
         this.drop(this.aoB);
         this.drop(this.ldr);
+        this.drop(this.ldrB);
         if (this.sceneDepth)
             this.gl.deleteTexture(this.sceneDepth);
-        this.scene = this.bloomA = this.bloomB = this.aoA = this.aoB = this.ldr = null;
+        this.scene = this.bloomA = this.bloomB = this.aoA = this.aoB = this.ldr = this.ldrB = null;
         this.sceneDepth = null;
     }
 }

package/dist/shaders.d.ts

@@ -1,5 +1,7 @@
 export declare const FACE_VS = "#version 300 es\nin vec3 aPos; in vec3 aNorm; in vec4 aCol; in float aBlood; in float aGrp;\nin vec3 aPos2; in vec3 aNorm2;\nuniform mat4 uVP; uniform mat4 uSVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nout vec3 vPos; out vec3 vNorm; out vec4 vCol; out float vZ; out vec4 vSh;\nout float vGA; out float vBlood;\nvoid main(){\n  int g = int(aGrp + 0.5);\n  float w = uMW[g];\n  vec3 p = mix(aPos, aPos2, w), n = mix(aNorm, aNorm2, w);\n  vec4 wp = uGM[g] * vec4(p, 1.0);\n  vPos = wp.xyz; vNorm = uNM[g] * n; vCol = aCol; vGA = uGA[g]; vBlood = aBlood;\n  vec4 cp = uVP * wp; vZ = cp.w; vSh = uSVP * wp; gl_Position = cp;\n}";
 export declare const FACE_FS = "#version 300 es\nprecision highp float;\nin vec3 vPos; in vec3 vNorm; in vec4 vCol; in float vZ; in vec4 vSh;\nin float vGA; in float vBlood;\nuniform vec3 uLdir; uniform float uAmb; uniform float uDif; uniform float uSigned;\nuniform vec3 uLp[8]; uniform float uLi[8]; uniform float uLf[8]; uniform int uLn;\nuniform vec3 uCam; uniform float uFogK; uniform float uSpec; uniform vec3 uBg;\nuniform vec3 uSkyC; uniform vec3 uGroundC; uniform float uPulse;\nuniform float uShadowOn; uniform float uShadowSoft; uniform float uShadowBias;\nuniform lowp sampler2DShadow uShadow; uniform float uShadowPx;\nout vec4 fragColor;\nfloat h3(vec3 p){ return fract(sin(dot(p, vec3(12.9898, 78.233, 37.719))) * 43758.5453); }\nfloat vnoise(vec3 p){ vec3 i = floor(p), f = fract(p); f = f * f * (3.0 - 2.0 * f);\n  return mix(mix(mix(h3(i), h3(i + vec3(1,0,0)), f.x), mix(h3(i + vec3(0,1,0)), h3(i + vec3(1,1,0)), f.x), f.y),\n             mix(mix(h3(i + vec3(0,0,1)), h3(i + vec3(1,0,1)), f.x), mix(h3(i + vec3(0,1,1)), h3(i + vec3(1,1,1)), f.x), f.y), f.z); }\nfloat shadowFactor(){\n  vec3 pr = vSh.xyz / vSh.w * 0.5 + 0.5;\n  if (pr.x < 0.0 || pr.x > 1.0 || pr.y < 0.0 || pr.y > 1.0 || pr.z > 1.0) return 1.0;\n  float ref = pr.z - uShadowBias;\n  // 3x3 taps over a hardware-compared (LINEAR sampler2DShadow => free 2x2 PCF each) map\n  float s = 0.0;\n  for (int sy = -1; sy <= 1; sy++)\n    for (int sx = -1; sx <= 1; sx++)\n      s += texture(uShadow, vec3(pr.xy + vec2(float(sx), float(sy)) * uShadowPx * uShadowSoft, ref));\n  s /= 9.0;\n  return 0.35 + 0.65 * s;\n}\nvoid main(){\n  vec3 n = normalize(vNorm);\n  vec3 V = normalize(uCam - vPos);\n  float skin = clamp(vBlood * 5.0, 0.0, 1.0);\n  { // procedural micro-relief: perturb the shading normal by a fine noise gradient\n    float bs = 5.5, e = 0.12, n0 = vnoise(vPos * bs);\n    vec3 g = vec3(vnoise(vPos * bs + vec3(e, 0.0, 0.0)) - n0,\n                  vnoise(vPos * bs + vec3(0.0, e, 0.0)) - n0,\n                  vnoise(vPos * bs + vec3(0.0, 0.0, e)) - n0) / e;\n    n = normalize(n - g * (0.10 + 0.30 * skin));\n  }\n  float d = dot(n, normalize(uLdir));\n  float shade = uAmb + uDif * mix(abs(d), max(d, 0.0), uSigned);\n  float spec = 0.0;\n  float sh = uShadowOn > 0.5 ? shadowFactor() : 1.0;\n  for (int i = 0; i < 8; i++) { if (i >= uLn) break;\n    vec3 v = uLp[i] - vPos; float d2 = dot(v, v); vec3 L = v * inversesqrt(d2 + 1e-4);\n    float lam = dot(n, L); lam = mix(abs(lam), max(lam, 0.0), uSigned);\n    float fall = 1.0 / (1.0 + d2 / (uLf[i] * uLf[i]));\n    float k = (i == 0) ? sh : 1.0;\n    shade += uLi[i] * lam * fall * k;\n    // GGX microfacet + Fresnel \u2014 roughness from the face's gloss (colour alpha slot)\n    vec3 H = normalize(L + V);\n    float nh = max(dot(n, H), 0.0);\n    float rough = clamp(1.0 - vCol.a, 0.08, 1.0), a2 = rough * rough; a2 = a2 * a2;\n    float dnm = nh * nh * (a2 - 1.0) + 1.0;\n    float ggx = a2 / (3.14159 * dnm * dnm);\n    float fres = 0.04 + 0.96 * pow(1.0 - max(dot(H, V), 0.0), 5.0);\n    spec += uLi[i] * min(ggx, 6.0) * fres * fall * k * 0.16;\n  }\n  // coloured hemispheric ambient: cool from above, warm from below\n  vec3 tint = mix(uGroundC, uSkyC, n.y * 0.5 + 0.5);\n  vec3 lit = vCol.rgb * (uAmb * tint + vec3(shade - uAmb));\n  // the perfusion term: blood near the surface changes how it meets the light\n  float b = clamp(vBlood + uPulse * vBlood * 6.0, 0.0, 1.0);\n  lit *= mix(vec3(1.0), vec3(1.07, 0.95, 0.94), b);\n  lit += vec3(0.62, 0.06, 0.08) * (b * 0.20 * (1.0 - abs(d)));\n  // pore noise, only where there is blood (skin, not cloth)\n  float pore = vnoise(vPos * 2.4) * 0.6 + vnoise(vPos * 6.0) * 0.4;\n  lit *= 1.0 + (pore - 0.5) * 0.09 * skin;\n  // subsurface rim: grazing light bleeds through thin tissue, warm\n  float fres = pow(1.0 - clamp(dot(n, V), 0.0, 1.0), 3.0);\n  lit += vec3(0.55, 0.09, 0.10) * fres * skin * (0.28 + 0.5 * b);\n  float fog = clamp(uFogK / vZ, 0.08, 1.0);\n  vec3 outC = lit + vec3(1.0) * spec * uSpec * vCol.a;\n  // fog and fades resolve toward the REAL background colour (the engine owns its ground)\n  fragColor = vec4(mix(uBg, outC, fog * vGA), 1.0);\n}";
+export declare const FACE_INST_VS = "#version 300 es\nin vec3 aPos; in vec3 aNorm; in vec4 aCol; in float aBlood; in float aGrp;\nin vec3 aPos2; in vec3 aNorm2;\nin vec4 aI0; in vec4 aI1; in vec4 aI2; in vec4 aI3;\nuniform mat4 uVP; uniform mat4 uSVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nout vec3 vPos; out vec3 vNorm; out vec4 vCol; out float vZ; out vec4 vSh;\nout float vGA; out float vBlood;\nvoid main(){\n  int g = int(aGrp + 0.5);\n  float w = uMW[g];\n  mat4 inst = mat4(aI0, aI1, aI2, aI3);\n  vec3 p = mix(aPos, aPos2, w), n = mix(aNorm, aNorm2, w);\n  vec4 wp = uGM[g] * (inst * vec4(p, 1.0));\n  vPos = wp.xyz; vNorm = uNM[g] * (mat3(inst) * n); vCol = aCol; vGA = uGA[g]; vBlood = aBlood;\n  vec4 cp = uVP * wp; vZ = cp.w; vSh = uSVP * wp; gl_Position = cp;\n}";
+export declare const DEPTH_INST_VS = "#version 300 es\nin vec3 aPos; in float aGrp; in vec3 aPos2;\nin vec4 aI0; in vec4 aI1; in vec4 aI2; in vec4 aI3;\nuniform mat4 uVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nvoid main(){\n  int g = int(aGrp + 0.5);\n  vec3 p = mix(aPos, aPos2, uMW[g]);\n  gl_Position = uVP * (uGM[g] * (mat4(aI0, aI1, aI2, aI3) * vec4(p, 1.0)));\n}";
 export declare const DEPTH_VS = "#version 300 es\nin vec3 aPos; in float aGrp; in vec3 aPos2;\nuniform mat4 uVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nvoid main(){\n  int g = int(aGrp + 0.5);\n  vec3 p = mix(aPos, aPos2, uMW[g]);\n  gl_Position = uVP * (uGM[g] * vec4(p, 1.0));\n}";
 export declare const DEPTH_FS = "#version 300 es\nprecision mediump float;\nvoid main(){}";
 export declare const LINE_VS = "#version 300 es\nin vec3 aPos; in vec4 aCol; in float aGrp;\nuniform mat4 uVP;\nuniform mat4 uGM[8]; uniform mat3 uNM[8]; uniform float uMW[8]; uniform float uGA[8];\nout vec4 vCol; out float vZ; out float vGA;\nvoid main(){\n  int g = int(aGrp + 0.5);\n  vCol = aCol; vGA = uGA[g];\n  vec4 p = uVP * (uGM[g] * vec4(aPos, 1.0)); vZ = p.w; gl_Position = p;\n}";
@@ -14,4 +16,6 @@ export declare const BLUR_FS = "#version 300 es\nprecision mediump float;\nin ve
 export declare const SSAO_FS = "#version 300 es\nprecision highp float;\nin vec2 vUv; uniform sampler2D uDepth;\nuniform float uNear; uniform float uFar; uniform float uRadius; uniform vec2 uRes;\nout vec4 fragColor;\nfloat viewZ(vec2 uv){\n  float d = texture(uDepth, uv).r * 2.0 - 1.0;\n  return 2.0 * uNear * uFar / (uFar + uNear - d * (uFar - uNear));\n}\nfloat hash(vec2 p){ return fract(sin(dot(p, vec2(12.9898, 78.233))) * 43758.5453); }\nvoid main(){\n  float z0 = viewZ(vUv);\n  // screen-space sample radius shrinks with distance (a world-ish radius)\n  float rad = uRadius / z0;\n  float ang = hash(vUv * uRes) * 6.2831853;\n  float occ = 0.0;\n  for (int i = 0; i < 12; i++) {\n    float fi = float(i);\n    float a = ang + fi * 2.3999632;           // golden-angle spiral\n    float r = rad * (0.25 + 0.75 * fract(fi * 0.618034));\n    vec2 uv = vUv + vec2(cos(a), sin(a)) * r;\n    float dz = z0 - viewZ(uv);                // positive => sample nearer camera => occluder\n    occ += smoothstep(z0 * 0.002, z0 * 0.02, dz) * smoothstep(z0 * 0.35, 0.0, dz);\n  }\n  float ao = 1.0 - occ / 12.0;\n  fragColor = vec4(vec3(ao), 1.0);\n}";
 export declare const AOBLUR_FS = "#version 300 es\nprecision mediump float;\nin vec2 vUv; uniform sampler2D uTex; uniform vec2 uPx;\nout vec4 fragColor;\nvoid main(){\n  float s = 0.0;\n  for (int y = -1; y <= 2; y++)\n    for (int x = -1; x <= 2; x++)\n      s += texture(uTex, vUv + vec2(float(x) - 0.5, float(y) - 0.5) * uPx).r;\n  fragColor = vec4(vec3(s / 16.0), 1.0);\n}";
 export declare const COMPOSITE_FS = "#version 300 es\nprecision mediump float;\nin vec2 vUv;\nuniform sampler2D uScene; uniform sampler2D uBloom; uniform sampler2D uAO;\nuniform float uBloomStr; uniform float uAOStr;\nuniform float uFilm; uniform float uGrade; uniform float uVig; uniform float uInk;\nout vec4 fragColor;\nvoid main(){\n  vec3 c = texture(uScene, vUv).rgb;\n  c *= mix(1.0, texture(uAO, vUv).r, uAOStr);\n  c += texture(uBloom, vUv).rgb * uBloomStr;\n  if (uFilm > 0.5) { // ACES-ish filmic: highlights roll off instead of clipping\n    c = (c * (2.51 * c + 0.03)) / (c * (2.43 * c + 0.59) + 0.14);\n  }\n  c = clamp(c, 0.0, 1.0);\n  if (uGrade > 0.5) { // violet-cool shadows, warm highlights\n    float luma = dot(c, vec3(0.299, 0.587, 0.114));\n    c *= mix(vec3(0.85, 0.83, 1.07), vec3(1.07, 0.99, 0.92), smoothstep(0.12, 0.72, luma));\n    c = clamp(c, 0.0, 1.0);\n  }\n  if (uVig > 0.0) { // cinematic vignette, in the composite now (off the overlay)\n    vec2 q = vUv - vec2(0.5, 0.54);\n    float r = smoothstep(0.35, 0.9, length(q * vec2(1.15, 1.0)));\n    vec3 dk = uInk > 0.5 ? vec3(0.20, 0.19, 0.30) : vec3(0.024, 0.016, 0.055);\n    c = mix(c, dk, uVig * r * (uInk > 0.5 ? 0.3 : 1.0));\n  }\n  fragColor = vec4(c, 1.0);\n}";
+export declare const DOF_FS = "#version 300 es\nprecision highp float;\nin vec2 vUv; uniform sampler2D uTex; uniform sampler2D uDepth;\nuniform float uNear; uniform float uFar; uniform float uFocus; uniform float uRange;\nuniform float uMaxBlur; uniform vec2 uPx;\nout vec4 fragColor;\nfloat lin(float d){ return uNear * uFar / (uFar - d * (uFar - uNear)); }\nconst vec2 DISC[12] = vec2[](\n  vec2(-0.326, -0.406), vec2(-0.840, -0.074), vec2(-0.696, 0.457), vec2(-0.203, 0.621),\n  vec2(0.962, -0.195), vec2(0.473, -0.480), vec2(0.519, 0.767), vec2(0.185, -0.893),\n  vec2(0.507, 0.064), vec2(0.896, 0.412), vec2(-0.322, -0.933), vec2(-0.792, -0.598));\nvoid main(){\n  float z = lin(texture(uDepth, vUv).r);\n  float coc = clamp(abs(z - uFocus) / max(1.0, uRange), 0.0, 1.0) * uMaxBlur;\n  vec3 acc = texture(uTex, vUv).rgb;\n  float wsum = 1.0;\n  for (int i = 0; i < 12; i++) {\n    vec2 off = DISC[i] * coc * uPx;\n    // a sharp (in-focus) neighbour must not bleed into a blurred one: weight each tap\n    // by ITS OWN CoC so foreground focus stays crisp against a soft background\n    float zt = lin(texture(uDepth, vUv + off).r);\n    float ct = clamp(abs(zt - uFocus) / max(1.0, uRange), 0.0, 1.0);\n    float w = 0.25 + 0.75 * ct;\n    acc += texture(uTex, vUv + off).rgb * w;\n    wsum += w;\n  }\n  fragColor = vec4(acc / wsum, 1.0);\n}";
+export declare const MOBLUR_FS = "#version 300 es\nprecision highp float;\nin vec2 vUv; uniform sampler2D uTex; uniform sampler2D uDepth;\nuniform mat4 uInvVP; uniform mat4 uPrevVP; uniform float uStrength;\nout vec4 fragColor;\nvoid main(){\n  float d = texture(uDepth, vUv).r;\n  vec4 ndc = vec4(vUv * 2.0 - 1.0, d * 2.0 - 1.0, 1.0);\n  vec4 wp = uInvVP * ndc; wp /= wp.w;\n  vec4 pc = uPrevVP * wp;\n  vec2 prevUv = (pc.xy / pc.w) * 0.5 + 0.5;\n  vec2 vel = (vUv - prevUv) * uStrength;\n  float vlen = length(vel);\n  if (vlen < 1e-5 || pc.w <= 0.0) { fragColor = vec4(texture(uTex, vUv).rgb, 1.0); return; }\n  vel = vlen > 0.04 ? vel * (0.04 / vlen) : vel;  // clamp the streak to 4% of the screen\n  vec3 acc = vec3(0.0);\n  for (int i = 0; i < 8; i++) {\n    float t = (float(i) / 7.0) - 0.5;\n    acc += texture(uTex, clamp(vUv + vel * t, vec2(0.001), vec2(0.999))).rgb;\n  }\n  fragColor = vec4(acc / 8.0, 1.0);\n}";
 export declare const FXAA_FS = "#version 300 es\nprecision mediump float;\nin vec2 vUv; uniform sampler2D uTex; uniform vec2 uPx;\nout vec4 fragColor;\nfloat luma(vec3 c){ return dot(c, vec3(0.299, 0.587, 0.114)); }\nvoid main(){\n  vec3 cM = texture(uTex, vUv).rgb;\n  float lM = luma(cM);\n  float lN = luma(texture(uTex, vUv + vec2(0.0, -uPx.y)).rgb);\n  float lS = luma(texture(uTex, vUv + vec2(0.0, uPx.y)).rgb);\n  float lW = luma(texture(uTex, vUv + vec2(-uPx.x, 0.0)).rgb);\n  float lE = luma(texture(uTex, vUv + vec2(uPx.x, 0.0)).rgb);\n  float lMin = min(lM, min(min(lN, lS), min(lW, lE)));\n  float lMax = max(lM, max(max(lN, lS), max(lW, lE)));\n  float range = lMax - lMin;\n  if (range < max(0.0312, lMax * 0.125)) { fragColor = vec4(cM, 1.0); return; }\n  vec2 dir = normalize(vec2((lE + lS) - (lW + lN), (lN + lE) - (lS + lW)) + 1e-6);\n  vec3 a = texture(uTex, vUv + dir * uPx * 0.5).rgb;\n  vec3 b = texture(uTex, vUv - dir * uPx * 0.5).rgb;\n  fragColor = vec4(mix(cM, (a + b) * 0.5, 0.75), 1.0);\n}";

package/dist/shaders.js

@@ -97,6 +97,35 @@ void main(){
   fragColor = vec4(mix(uBg, outC, fog * vGA), 1.0);
 }`;
 // depth-only pass (shadow map) — same morph + group transforms, no colour output
+// instanced face VS (W8): the per-instance model matrix arrives as 4 vec4 attributes
+// (divisor 1) and composes INSIDE the group transform — instances ride their group's
+// fade / morph / transform like any other geometry. Normals use mat3(instance); with
+// rotation + uniform scale that is exact (the normalize() in the FS absorbs scale).
+export const FACE_INST_VS = `#version 300 es
+in vec3 aPos; in vec3 aNorm; in vec4 aCol; in float aBlood; in float aGrp;
+in vec3 aPos2; in vec3 aNorm2;
+in vec4 aI0; in vec4 aI1; in vec4 aI2; in vec4 aI3;
+uniform mat4 uVP; uniform mat4 uSVP;${GROUPS}
+out vec3 vPos; out vec3 vNorm; out vec4 vCol; out float vZ; out vec4 vSh;
+out float vGA; out float vBlood;
+void main(){
+  int g = int(aGrp + 0.5);
+  float w = uMW[g];
+  mat4 inst = mat4(aI0, aI1, aI2, aI3);
+  vec3 p = mix(aPos, aPos2, w), n = mix(aNorm, aNorm2, w);
+  vec4 wp = uGM[g] * (inst * vec4(p, 1.0));
+  vPos = wp.xyz; vNorm = uNM[g] * (mat3(inst) * n); vCol = aCol; vGA = uGA[g]; vBlood = aBlood;
+  vec4 cp = uVP * wp; vZ = cp.w; vSh = uSVP * wp; gl_Position = cp;
+}`;
+export const DEPTH_INST_VS = `#version 300 es
+in vec3 aPos; in float aGrp; in vec3 aPos2;
+in vec4 aI0; in vec4 aI1; in vec4 aI2; in vec4 aI3;
+uniform mat4 uVP;${GROUPS}
+void main(){
+  int g = int(aGrp + 0.5);
+  vec3 p = mix(aPos, aPos2, uMW[g]);
+  gl_Position = uVP * (uGM[g] * (mat4(aI0, aI1, aI2, aI3) * vec4(p, 1.0)));
+}`;
 export const DEPTH_VS = `#version 300 es
 in vec3 aPos; in float aGrp; in vec3 aPos2;
 uniform mat4 uVP;${GROUPS}
@@ -283,6 +312,59 @@ void main(){
   }
   fragColor = vec4(c, 1.0);
 }`;
+// depth of field — CoC from linearized depth, 12-tap poisson disc gather on the LDR
+export const DOF_FS = `#version 300 es
+precision highp float;
+in vec2 vUv; uniform sampler2D uTex; uniform sampler2D uDepth;
+uniform float uNear; uniform float uFar; uniform float uFocus; uniform float uRange;
+uniform float uMaxBlur; uniform vec2 uPx;
+out vec4 fragColor;
+float lin(float d){ return uNear * uFar / (uFar - d * (uFar - uNear)); }
+const vec2 DISC[12] = vec2[](
+  vec2(-0.326, -0.406), vec2(-0.840, -0.074), vec2(-0.696, 0.457), vec2(-0.203, 0.621),
+  vec2(0.962, -0.195), vec2(0.473, -0.480), vec2(0.519, 0.767), vec2(0.185, -0.893),
+  vec2(0.507, 0.064), vec2(0.896, 0.412), vec2(-0.322, -0.933), vec2(-0.792, -0.598));
+void main(){
+  float z = lin(texture(uDepth, vUv).r);
+  float coc = clamp(abs(z - uFocus) / max(1.0, uRange), 0.0, 1.0) * uMaxBlur;
+  vec3 acc = texture(uTex, vUv).rgb;
+  float wsum = 1.0;
+  for (int i = 0; i < 12; i++) {
+    vec2 off = DISC[i] * coc * uPx;
+    // a sharp (in-focus) neighbour must not bleed into a blurred one: weight each tap
+    // by ITS OWN CoC so foreground focus stays crisp against a soft background
+    float zt = lin(texture(uDepth, vUv + off).r);
+    float ct = clamp(abs(zt - uFocus) / max(1.0, uRange), 0.0, 1.0);
+    float w = 0.25 + 0.75 * ct;
+    acc += texture(uTex, vUv + off).rgb * w;
+    wsum += w;
+  }
+  fragColor = vec4(acc / wsum, 1.0);
+}`;
+// camera motion blur — reconstruct world position from depth, reproject into the
+// previous frame's clip space, sample along the screen-space velocity
+export const MOBLUR_FS = `#version 300 es
+precision highp float;
+in vec2 vUv; uniform sampler2D uTex; uniform sampler2D uDepth;
+uniform mat4 uInvVP; uniform mat4 uPrevVP; uniform float uStrength;
+out vec4 fragColor;
+void main(){
+  float d = texture(uDepth, vUv).r;
+  vec4 ndc = vec4(vUv * 2.0 - 1.0, d * 2.0 - 1.0, 1.0);
+  vec4 wp = uInvVP * ndc; wp /= wp.w;
+  vec4 pc = uPrevVP * wp;
+  vec2 prevUv = (pc.xy / pc.w) * 0.5 + 0.5;
+  vec2 vel = (vUv - prevUv) * uStrength;
+  float vlen = length(vel);
+  if (vlen < 1e-5 || pc.w <= 0.0) { fragColor = vec4(texture(uTex, vUv).rgb, 1.0); return; }
+  vel = vlen > 0.04 ? vel * (0.04 / vlen) : vel;  // clamp the streak to 4% of the screen
+  vec3 acc = vec3(0.0);
+  for (int i = 0; i < 8; i++) {
+    float t = (float(i) / 7.0) - 0.5;
+    acc += texture(uTex, clamp(vUv + vel * t, vec2(0.001), vec2(0.999))).rgb;
+  }
+  fragColor = vec4(acc / 8.0, 1.0);
+}`;
 // compact FXAA (luma-based, 5-tap edge blend) — runs last, on the LDR composite
 export const FXAA_FS = `#version 300 es
 precision mediump float;

package/dist/world.d.ts

@@ -88,6 +88,9 @@ export declare class World {
     private pPt;
     private pRib;
     private pDepth;
+    private pFaceI;
+    private pDepthI;
+    private instanced;
     private post;
     private ink;
     private bg;
@@ -171,6 +174,20 @@ export declare class World {
     };
     /** FXAA on the final composite */
     fxaa: boolean;
+    /** depth of field (W8) — blur grows with distance from the focus plane (world units) */
+    dof: {
+        on: boolean;
+        focus: number;
+        range: number;
+        maxBlur: number;
+    };
+    /** camera motion blur (W8) — depth reprojection into the previous frame's view */
+    motionBlur: {
+        on: boolean;
+        strength: number;
+    };
+    private prevVP;
+    private prevVPValid;
     private groupIdx;
     private groupAlpha;
     private groupTarget;
@@ -223,6 +240,10 @@ export declare class World {
     private pushRibbon;
     /** A static ribbon stroke — real pixel width, feathered edges, depth-tested. */
     ribbon(pts: V3[], o: RibbonOpts): void;
+    /** W8 — GPU instancing: upload a Mesh ONCE and draw it at every given transform in a
+     *  single instanced call (scene + shadow pass alike). A forest is one draw. Instances
+     *  ride their group's fade / morph / transform like any other geometry. */
+    meshInstanced(geo: Mesh, instances: (M4 | TransformSpec)[], o: FaceOpts): void;
     grow(fn: GrowFn): void;
     drawLine(a: V3, b: V3, color: string, alpha: number, width?: number): void;
     drawPath(pts: {
@@ -250,6 +271,10 @@ export declare class World {
     private drawLines;
     private drawPts;
     private drawRibbons;
+    /** Instanced records under a given program (scene or depth pass). Divisors are reset
+     *  after each draw — attribute divisor is global-per-index state and would otherwise
+     *  poison the non-instanced draws that share those indices. */
+    private drawInstancedAll;
     private renderFrame;
     private frameFn;
     private pausedByUser;

package/dist/world.js

@@ -3,8 +3,8 @@
 // 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 { v3, add, sub, scale, cross, norm, clamp, hsl, mIdent, mPerspective, mLookAt, mMul, mCompose, mInvert, 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, FACE_INST_VS, DEPTH_INST_VS, } 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
@@ -33,6 +33,7 @@ export class World {
         this.groupNM.set(normalMat3(mat), i * 9);
     }
     constructor(o) {
+        this.instanced = [];
         this.ink = false;
         this.bg = [0.024, 0.016, 0.055];
         this.transparent = false;
@@ -84,6 +85,12 @@ export class World {
         this.ssao = { on: true, strength: 0.55, radius: 22 };
         /** FXAA on the final composite */
         this.fxaa = true;
+        /** depth of field (W8) — blur grows with distance from the focus plane (world units) */
+        this.dof = { on: false, focus: 700, range: 420, maxBlur: 10 };
+        /** camera motion blur (W8) — depth reprojection into the previous frame's view */
+        this.motionBlur = { on: false, strength: 0.6 };
+        this.prevVP = mIdent();
+        this.prevVPValid = false;
         // groups: fade alpha + morph weight + transform, resolved in the vertex stage
         this.groupIdx = new Map([["default", 0]]);
         this.groupAlpha = new Float32Array(8).fill(1);
@@ -156,6 +163,8 @@ export class World {
         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.pFaceI = new PInfo(gl, FACE_INST_VS, FACE_FS);
+        this.pDepthI = new PInfo(gl, DEPTH_INST_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") {
@@ -371,6 +380,28 @@ export class World {
     }
     /** A static ribbon stroke — real pixel width, feathered edges, depth-tested. */
     ribbon(pts, o) { this.pushRibbon(this.sRib, pts, o); this.staticDirty = true; }
+    /** W8 — GPU instancing: upload a Mesh ONCE and draw it at every given transform in a
+     *  single instanced call (scene + shadow pass alike). A forest is one draw. Instances
+     *  ride their group's fade / morph / transform like any other geometry. */
+    meshInstanced(geo, instances, o) {
+        if (!instances.length)
+            return;
+        const gl = this.gl;
+        const store = [];
+        const P = geo.pos, N = geo.nrm;
+        for (let i = 0; i < P.length; i += 9) {
+            this.pushFace(store, 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]));
+        }
+        const mats = new Float32Array(instances.length * 16);
+        instances.forEach((m, i) => mats.set(m instanceof Float32Array ? m : mCompose(m), i * 16));
+        const vbuf = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, vbuf);
+        gl.bufferData(gl.ARRAY_BUFFER, new Float32Array(store), gl.STATIC_DRAW);
+        const ibuf = gl.createBuffer();
+        gl.bindBuffer(gl.ARRAY_BUFFER, ibuf);
+        gl.bufferData(gl.ARRAY_BUFFER, mats, gl.STATIC_DRAW);
+        this.instanced.push({ vbuf, ibuf, verts: store.length / FACE_STRIDE, count: instances.length });
+    }
     grow(fn) { this.hooks.push(fn); }
     // ── the living verbs (gathered per frame) ──
     drawLine(a, b, color, alpha, width = 1) {
@@ -563,11 +594,53 @@ export class World {
         this.attrib(this.pRib, "aGrp", 1, RIB_STRIDE, 15);
         gl.drawArrays(gl.TRIANGLES, 0, verts);
     }
+    /** Instanced records under a given program (scene or depth pass). Divisors are reset
+     *  after each draw — attribute divisor is global-per-index state and would otherwise
+     *  poison the non-instanced draws that share those indices. */
+    drawInstancedAll(p, depthOnly) {
+        if (!this.instanced.length)
+            return;
+        const gl = this.gl;
+        for (const rec of this.instanced) {
+            gl.bindBuffer(gl.ARRAY_BUFFER, rec.vbuf);
+            this.attrib(p, "aPos", 3, FACE_STRIDE, 0);
+            if (!depthOnly) {
+                this.attrib(p, "aNorm", 3, FACE_STRIDE, 3);
+                this.attrib(p, "aCol", 4, FACE_STRIDE, 6);
+                this.attrib(p, "aBlood", 1, FACE_STRIDE, 10);
+            }
+            this.attrib(p, "aGrp", 1, FACE_STRIDE, 11);
+            this.attrib(p, "aPos2", 3, FACE_STRIDE, 12);
+            if (!depthOnly)
+                this.attrib(p, "aNorm2", 3, FACE_STRIDE, 15);
+            gl.bindBuffer(gl.ARRAY_BUFFER, rec.ibuf);
+            const locs = [];
+            for (let k = 0; k < 4; k++) {
+                const loc = gl.getAttribLocation(p.prog, "aI" + k);
+                if (loc < 0)
+                    continue;
+                gl.enableVertexAttribArray(loc);
+                gl.vertexAttribPointer(loc, 4, gl.FLOAT, false, 64, k * 16);
+                gl.vertexAttribDivisor(loc, 1);
+                locs.push(loc);
+            }
+            gl.drawArraysInstanced(gl.TRIANGLES, 0, rec.verts, rec.count);
+            for (const loc of locs)
+                gl.vertexAttribDivisor(loc, 0);
+        }
+    }
     // ── the frame ──
     renderFrame(t, dt) {
         const gl = this.gl;
         this.lastT = t;
+        if (this.motionBlur.on && this.prevVPValid)
+            this.prevVP = new Float32Array(this.vp);
         this.setupCamera(t, dt);
+        if (this.motionBlur.on && !this.prevVPValid) {
+            // first blurred frame: previous = current, so velocity is zero (no identity streak)
+            this.prevVP = new Float32Array(this.vp);
+            this.prevVPValid = true;
+        }
         this.fLight.length = 0;
         this.fRib.length = 0;
         this.dFaceA.length = 0;
@@ -640,6 +713,12 @@ export class World {
                 gl.bindBuffer(gl.ARRAY_BUFFER, this.bFaceD);
                 this.depthDraw(this.bFaceD, this.dFaceA.length / FACE_STRIDE);
             }
+            if (this.instanced.length) {
+                this.pDepthI.use();
+                gl.uniformMatrix4fv(this.pDepthI.u("uVP"), false, this.svp);
+                this.setGroups(this.pDepthI);
+                this.drawInstancedAll(this.pDepthI, true);
+            }
             gl.bindFramebuffer(gl.FRAMEBUFFER, null);
         }
         // the scene pass — into the HDR target when the post chain is on
@@ -664,6 +743,12 @@ export class World {
         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));
+        if (this.instanced.length) {
+            this.pFaceI.use();
+            this.setVP(this.pFaceI);
+            this.setLights(this.pFaceI, fogK);
+            this.drawInstancedAll(this.pFaceI, false);
+        }
         // the light — additive, depth-TESTED but not written (ink: normal alpha blend)
         gl.depthMask(false);
         gl.enable(gl.BLEND);
@@ -701,6 +786,9 @@ export class World {
                 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,
+                dofOn: this.dof.on, dofFocus: this.dof.focus, dofRange: this.dof.range, dofMaxBlur: this.dof.maxBlur,
+                moOn: this.motionBlur.on, moStrength: this.motionBlur.strength,
+                invVP: this.motionBlur.on ? mInvert(this.vp) : undefined, prevVP: this.prevVP,
             });
         }
         // labels — 2D overlay, never occluded (the honest exception)
@@ -784,6 +872,11 @@ export class World {
             c();
         this.cleanup = [];
         this.overlay.remove();
+        for (const rec of this.instanced) {
+            this.gl.deleteBuffer(rec.vbuf);
+            this.gl.deleteBuffer(rec.ibuf);
+        }
+        this.instanced = [];
         this.post?.dispose();
         if (releaseContext)
             this.gl.getExtension("WEBGL_lose_context")?.loseContext();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromatic-coherence/generative-engine",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "THE THIRD ENGINE — a zero-dependency WebGL2 graphics engine grown from generative-charts-3d: HDR + bloom + SSAO post chain, hardware-PCF shadow maps, a geometry stdlib, ribbon strokes, group transforms and morph targets. The charts API rides on top unchanged.",
   "type": "module",
   "main": "./dist/index.js",