@yali-engine/render 0.0.0-stage → 0.4.0

package/dist/frame-graph.js

@@ -0,0 +1,226 @@
+import { YaliError } from '@yali-engine/core';
+/**
+ * The declarative frame graph (DESIGN.md §12, after O'Donnell, *FrameGraph*, GDC 2017).
+ * Plugins add passes with what they read and write; `compile` orders them, culls passes
+ * nothing downstream needs, and pools transient textures. `execute` records one frame.
+ *
+ * @example
+ * const graph = new FrameGraph(device);
+ * graph.importTexture('backbuffer', () => context.getCurrentTexture().createView());
+ * graph.transientTexture('depth', { format: 'depth32float', usage: GPUTextureUsage.RENDER_ATTACHMENT });
+ * graph.addPass(cullPass);
+ * graph.addPass(drawPass);
+ * graph.setOutput('backbuffer');
+ */
+/** Bytes per texel of the formats the renderer's transients use (4 for anything else listed as RGBA8-sized). */
+const TEXEL_BYTES = { rgba16float: 8, rgba32float: 16, rg16float: 4, r32float: 4, rgba8unorm: 4, 'rgba8unorm-srgb': 4, bgra8unorm: 4, depth32float: 4, depth24plus: 4, 'depth24plus-stencil8': 4, r32uint: 4, r16float: 2, r8unorm: 1 };
+export class FrameGraph {
+    device;
+    #passes = [];
+    #imports = new Map();
+    #transients = new Map();
+    #allocated = new Map();
+    #output = '';
+    #compiled = [];
+    #culled = [];
+    #dirty = true;
+    /** Names of the compiled passes in execution order; pass `i` uses timestamp slot `i`.
+     *  Replaced (not mutated) on each compile, so a holder can detect a recompile by identity. */
+    passNames = [];
+    #width = 0;
+    #height = 0;
+    #outWidth = 0;
+    #outHeight = 0;
+    #ctx;
+    timer = null;
+    constructor(device) {
+        this.device = device;
+        this.#ctx = { device, width: 0, height: 0, outputWidth: 0, outputHeight: 0, generation: 0, view: (name) => this.#view(name), texture: (name) => this.#texture(name) };
+    }
+    /** A texture owned outside the graph (the swapchain), fetched once per frame. */
+    importTexture(name, view) {
+        this.#imports.set(name, view);
+        this.#dirty = true;
+    }
+    /** A texture the graph allocates for the current size. */
+    transientTexture(name, desc) {
+        this.#transients.set(name, desc);
+        this.#dirty = true;
+    }
+    /** Adds a pass. Names are unique. */
+    addPass(def) {
+        if (this.#passes.some((p) => p.name === def.name)) {
+            throw new YaliError('DUPLICATE_PASS', `A pass named ${def.name} already exists.`, 'Give each pass a unique name.');
+        }
+        this.#passes.push(def);
+        this.#dirty = true;
+    }
+    /** The resource the frame exists to produce (usually `backbuffer`). */
+    setOutput(name) {
+        this.#output = name;
+        this.#dirty = true;
+    }
+    /** Resizes transients (on the next `execute`); the output size defaults to the render size. */
+    resize(width, height, outputWidth = width, outputHeight = height) {
+        if (width === this.#width && height === this.#height && outputWidth === this.#outWidth && outputHeight === this.#outHeight)
+            return;
+        this.#width = width;
+        this.#height = height;
+        this.#outWidth = outputWidth;
+        this.#outHeight = outputHeight;
+        this.#ctx.width = width;
+        this.#ctx.height = height;
+        this.#ctx.outputWidth = outputWidth;
+        this.#ctx.outputHeight = outputHeight;
+        for (const t of this.#allocated.values())
+            t.texture.destroy();
+        this.#allocated.clear();
+        this.#dirty = true;
+    }
+    static #targets(p) {
+        const out = [...(p.writes ?? [])];
+        if (p.kind === 'render') {
+            if (p.color)
+                out.push(p.color.target);
+            if (p.depth)
+                out.push(p.depth.target);
+        }
+        return out;
+    }
+    /**
+     * Orders passes (a pass runs after every earlier-declared pass that writes what it
+     * reads), culls passes that don't contribute to the output, and allocates transients.
+     */
+    compile() {
+        if (!this.#output) {
+            throw new YaliError('NO_OUTPUT', 'The frame graph has no output.', 'Call graph.setOutput("backbuffer").');
+        }
+        // Walk back from the output: a pass is needed if it writes something a needed pass
+        // (or the output) consumes.
+        const needed = new Set([this.#output]);
+        const keep = new Array(this.#passes.length).fill(false);
+        for (let i = this.#passes.length - 1; i >= 0; i--) {
+            const p = this.#passes[i];
+            if (FrameGraph.#targets(p).some((t) => needed.has(t))) {
+                keep[i] = true;
+                for (const r of p.reads ?? [])
+                    needed.add(r);
+                if (p.kind === 'render' && p.depth)
+                    needed.add(p.depth.target);
+            }
+        }
+        this.#culled = this.#passes.filter((_, i) => !keep[i]).map((p) => p.name);
+        const used = new Set();
+        this.#compiled = this.#passes
+            .filter((_, i) => keep[i])
+            .map((def, index) => {
+            for (const t of FrameGraph.#targets(def))
+                used.add(t);
+            for (const r of def.reads ?? [])
+                used.add(r);
+            if (def.kind === 'encoder')
+                return { def };
+            if (def.kind === 'compute') {
+                const tw = this.timer?.timestampWrites(index);
+                return { def, computeDesc: tw ? { label: def.name, timestampWrites: tw } : { label: def.name } };
+            }
+            const tw = this.timer?.timestampWrites(index);
+            const desc = {
+                label: def.name,
+                colorAttachments: def.color ? [{ view: undefined, clearValue: def.color.clear, loadOp: def.color.load ? 'load' : 'clear', storeOp: 'store' }] : [],
+                ...(def.depth
+                    ? { depthStencilAttachment: { view: undefined, depthClearValue: def.depth.clear, depthLoadOp: def.depth.load ? 'load' : 'clear', depthStoreOp: def.depth.store ? 'store' : 'discard' } }
+                    : {}),
+                ...(tw ? { timestampWrites: tw } : {}),
+            };
+            return { def, renderDesc: desc };
+        });
+        this.passNames = this.#compiled.map((c) => c.def.name);
+        for (const [name, t] of this.#transients) {
+            if (!used.has(name) || this.#allocated.has(name))
+                continue;
+            const scale = t.scale ?? 1;
+            const [w, h] = t.output ? [this.#outWidth || this.#width, this.#outHeight || this.#height] : [this.#width, this.#height];
+            const texture = this.device.createTexture({
+                label: `transient:${name}`,
+                size: [Math.max(1, Math.round(w * scale)), Math.max(1, Math.round(h * scale))],
+                format: t.format,
+                usage: t.usage,
+            });
+            this.#allocated.set(name, { texture, view: texture.createView() });
+            this.#ctx.generation++;
+        }
+        this.#dirty = false;
+    }
+    /** Bytes the allocated transient textures hold (M2's render-target budget, `budgets.json`). */
+    get transientBytes() {
+        let sum = 0;
+        for (const { texture } of this.#allocated.values())
+            sum += texture.width * texture.height * (TEXEL_BYTES[texture.format] ?? 4);
+        return sum;
+    }
+    #texture(name) {
+        const t = this.#allocated.get(name);
+        if (!t)
+            throw new YaliError('UNKNOWN_RESOURCE', `Frame graph texture ${name} is not a transient.`, 'Copy from a transient texture.');
+        return t.texture;
+    }
+    #view(name) {
+        const imported = this.#imports.get(name);
+        if (imported)
+            return imported();
+        const t = this.#allocated.get(name);
+        if (!t)
+            throw new YaliError('UNKNOWN_RESOURCE', `Frame graph texture ${name} does not exist.`, 'Import it or declare it as a transient.');
+        return t.view;
+    }
+    /** Records every compiled pass into `encoder`. */
+    execute(encoder) {
+        if (this.#dirty)
+            this.compile();
+        for (const c of this.#compiled) {
+            const def = c.def;
+            if (def.kind === 'encoder') {
+                def.execute(encoder, this.#ctx);
+                continue;
+            }
+            if (def.kind === 'compute') {
+                const pass = encoder.beginComputePass(c.computeDesc);
+                def.execute(pass, this.#ctx);
+                pass.end();
+            }
+            else {
+                const desc = c.renderDesc;
+                if (def.color)
+                    desc.colorAttachments[0].view = this.#view(def.color.target);
+                if (def.depth && desc.depthStencilAttachment)
+                    desc.depthStencilAttachment.view = this.#view(def.depth.target);
+                const pass = encoder.beginRenderPass(desc);
+                def.execute(pass, this.#ctx);
+                pass.end();
+            }
+        }
+    }
+    /** Transient textures currently allocated (for the dispose leak check). */
+    get liveTextures() {
+        return this.#allocated.size;
+    }
+    /** Forces transients to be rebuilt on the next frame (the attachment-mismatch heal). */
+    invalidate() {
+        for (const t of this.#allocated.values())
+            t.texture.destroy();
+        this.#allocated.clear();
+        this.#dirty = true;
+    }
+    /** Destroys every transient texture. */
+    destroy() {
+        this.invalidate();
+    }
+    /** The compiled graph, for inspection (CLI, MCP, overlay). */
+    describe() {
+        if (this.#dirty)
+            this.compile();
+        return { passes: this.#compiled.map((c) => c.def.name), culled: [...this.#culled], transients: [...this.#allocated.keys()] };
+    }
+}
+//# sourceMappingURL=frame-graph.js.map

package/dist/frame-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-graph.js","sourceRoot":"","sources":["../src/frame-graph.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AA+E9C;;;;;;;;;;;;GAYG;AACH,gHAAgH;AAChH,MAAM,WAAW,GAAwD,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,iBAAiB,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,sBAAsB,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;AAE7R,MAAM,OAAO,UAAU;IACZ,MAAM,CAAY;IAC3B,OAAO,GAAc,EAAE,CAAC;IACxB,QAAQ,GAAG,IAAI,GAAG,EAAgC,CAAC;IACnD,WAAW,GAAG,IAAI,GAAG,EAA4B,CAAC;IAClD,UAAU,GAAG,IAAI,GAAG,EAAyD,CAAC;IAC9E,OAAO,GAAG,EAAE,CAAC;IACb,SAAS,GAAe,EAAE,CAAC;IAC3B,OAAO,GAAa,EAAE,CAAC;IACvB,MAAM,GAAG,IAAI,CAAC;IACd;kGAC8F;IAC9F,SAAS,GAAsB,EAAE,CAAC;IAClC,MAAM,GAAG,CAAC,CAAC;IACX,OAAO,GAAG,CAAC,CAAC;IACZ,SAAS,GAAG,CAAC,CAAC;IACd,UAAU,GAAG,CAAC,CAAC;IACf,IAAI,CAA6L;IACjM,KAAK,GAAqB,IAAI,CAAC;IAE/B,YAAY,MAAiB;QAC3B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IACxK,CAAC;IAED,iFAAiF;IACjF,aAAa,CAAC,IAAY,EAAE,IAA0B;QACpD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,0DAA0D;IAC1D,gBAAgB,CAAC,IAAY,EAAE,IAAsB;QACnD,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,qCAAqC;IACrC,OAAO,CAAC,GAAY;QAClB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,SAAS,CAAC,gBAAgB,EAAE,gBAAgB,GAAG,CAAC,IAAI,kBAAkB,EAAE,+BAA+B,CAAC,CAAC;QACrH,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,uEAAuE;IACvE,SAAS,CAAC,IAAY;QACpB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,+FAA+F;IAC/F,MAAM,CAAC,KAAa,EAAE,MAAc,EAAE,WAAW,GAAG,KAAK,EAAE,YAAY,GAAG,MAAM;QAC9E,IAAI,KAAK,KAAK,IAAI,CAAC,MAAM,IAAI,MAAM,KAAK,IAAI,CAAC,OAAO,IAAI,WAAW,KAAK,IAAI,CAAC,SAAS,IAAI,YAAY,KAAK,IAAI,CAAC,UAAU;YAAE,OAAO;QACnI,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;QACtB,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC;QAC7B,IAAI,CAAC,UAAU,GAAG,YAAY,CAAC;QAC/B,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACxB,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAC1B,IAAI,CAAC,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QACpC,IAAI,CAAC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACtC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE;YAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC9D,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,MAAM,CAAC,QAAQ,CAAC,CAAU;QACxB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,CAAC;QAClC,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACxB,IAAI,CAAC,CAAC,KAAK;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACtC,IAAI,CAAC,CAAC,KAAK;gBAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QACxC,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;OAGG;IACH,OAAO;QACL,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,MAAM,IAAI,SAAS,CAAC,WAAW,EAAE,gCAAgC,EAAE,qCAAqC,CAAC,CAAC;QAC5G,CAAC;QACD,mFAAmF;QACnF,4BAA4B;QAC5B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;QAC/C,MAAM,IAAI,GAAG,IAAI,KAAK,CAAU,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACjE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBACtD,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;gBACf,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE;oBAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAC7C,IAAI,CAAC,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK;oBAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACjE,CAAC;QACH,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1E,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO;aAC1B,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;aACzB,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;YAClB,KAAK,MAAM,CAAC,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YACtD,KAAK,MAAM,CAAC,IAAI,GAAG,CAAC,KAAK,IAAI,EAAE;gBAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAC7C,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS;gBAAE,OAAO,EAAE,GAAG,EAAE,CAAC;YAC3C,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;gBAC9C,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;YACnG,CAAC;YACD,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,eAAe,CAAC,KAAK,CAAC,CAAC;YAC9C,MAAM,IAAI,GAA2B;gBACnC,KAAK,EAAE,GAAG,CAAC,IAAI;gBACf,gBAAgB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAsC,EAAE,UAAU,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE;gBAC/K,GAAG,CAAC,GAAG,CAAC,KAAK;oBACX,CAAC,CAAC,EAAE,sBAAsB,EAAE,EAAE,IAAI,EAAE,SAAsC,EAAE,eAAe,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE;oBACrN,CAAC,CAAC,EAAE,CAAC;gBACP,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACvC,CAAC;YACF,OAAO,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QACnC,CAAC,CAAC,CAAC;QACL,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvD,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACzC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YAC3D,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC;YAC3B,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACzH,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC;gBACxC,KAAK,EAAE,aAAa,IAAI,EAAE;gBAC1B,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;gBAC9E,MAAM,EAAE,CAAC,CAAC,MAAM;gBAChB,KAAK,EAAE,CAAC,CAAC,KAAK;aACf,CAAC,CAAC;YACH,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YACnE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;IACtB,CAAC;IAED,+FAA+F;IAC/F,IAAI,cAAc;QAChB,IAAI,GAAG,GAAG,CAAC,CAAC;QACZ,KAAK,MAAM,EAAE,OAAO,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE;YAAE,GAAG,IAAI,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QAC/H,OAAO,GAAG,CAAC;IACb,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,uBAAuB,IAAI,sBAAsB,EAAE,gCAAgC,CAAC,CAAC;QACrI,OAAO,CAAC,CAAC,OAAO,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,IAAY;QAChB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,QAAQ;YAAE,OAAO,QAAQ,EAAE,CAAC;QAChC,MAAM,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,kBAAkB,EAAE,uBAAuB,IAAI,kBAAkB,EAAE,yCAAyC,CAAC,CAAC;QAC1I,OAAO,CAAC,CAAC,IAAI,CAAC;IAChB,CAAC;IAED,kDAAkD;IAClD,OAAO,CAAC,OAA0B;QAChC,IAAI,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAChC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC;YAClB,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC3B,GAAG,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,IAAI,GAAG,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;gBACrD,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC7B,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,GAAG,CAAC,CAAC,UAAW,CAAC;gBAC3B,IAAI,GAAG,CAAC,KAAK;oBAAE,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC5E,IAAI,GAAG,CAAC,KAAK,IAAI,IAAI,CAAC,sBAAsB;oBAAE,IAAI,CAAC,sBAAsB,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;gBAC9G,MAAM,IAAI,GAAG,OAAO,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;gBAC3C,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;gBAC7B,IAAI,CAAC,GAAG,EAAE,CAAC;YACb,CAAC;QACH,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;IAC9B,CAAC;IAED,wFAAwF;IACxF,UAAU;QACR,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE;YAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC9D,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,wCAAwC;IACxC,OAAO;QACL,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;IAED,8DAA8D;IAC9D,QAAQ;QACN,IAAI,IAAI,CAAC,MAAM;YAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;IAC/H,CAAC;CACF"}

package/dist/gpu-health.d.ts

@@ -0,0 +1,74 @@
+/**
+ * GPU health: is the device alive, and if not, why (ADR-0010: ported from Character XYZ
+ * `mesh/viewport/gpu-health.ts`, per instance instead of module-global).
+ *
+ * A lost `GPUDevice` fails silently: every later command is ignored, with no exception,
+ * and the canvas just stops presenting. This class listens for `device.lost` and
+ * `uncapturederror`, so a loss arrives with its reason. It counts uncaptured errors even
+ * while the device is healthy, keeping the FIRST one (the error that started a cascade)
+ * as well as the last. It keeps a bounded diagnostic ring that survives until the page
+ * reloads, which is the one action that destroys every other trace.
+ */
+/** Health of one device. */
+export interface GpuHealthState {
+    status: 'ok' | 'lost';
+    /** The API's own reason (`destroyed` | `unknown`), null while healthy. */
+    reason: string | null;
+    /** The API's own message; often empty even when lost. Never invented. */
+    message: string | null;
+    /** `performance.now()` at the loss. */
+    at: number | null;
+    uncaptured: {
+        count: number;
+        first: string | null;
+        last: string | null;
+    };
+}
+/** One recorded moment in the device's life. */
+export interface GpuDiagEvent {
+    t: number;
+    kind: 'uncaptured' | 'device-lost' | 'heal' | 'note';
+    text: string;
+}
+/**
+ * The recoverable attachment-size mismatch: a depth attachment allocated at one pixel ratio
+ * still bound after the ratio changed. Captured live in Character XYZ (2026-08-19); a
+ * resize rebuilds the attachments and fixes it.
+ */
+export declare function isRecoverableAttachmentMismatch(text: string): boolean;
+/**
+ * Tracks one device.
+ *
+ * @example
+ * const health = new GpuHealth();
+ * const detach = health.attach(device, { onLost: (info) => app.deviceLost(info), onHeal: () => graph.forceResize() });
+ */
+export declare class GpuHealth {
+    #private;
+    readonly state: GpuHealthState;
+    readonly events: GpuDiagEvent[];
+    heals: number;
+    /** Records a note beside the GPU events (a heal, a mode change). */
+    note(text: string): void;
+    /**
+     * Listens to `device`. `onLost` gets the API's reason; `onHeal` runs when a known
+     * recoverable error arrives (rate-limited). Returns a detach function.
+     */
+    attach(device: GPUDevice, hooks?: {
+        onLost?: (info: {
+            reason: string;
+            message: string;
+        }) => void;
+        onHeal?: (why: string) => void;
+    }): () => void;
+    /** Marks a fresh device after recovery, keeping the history. */
+    reset(): void;
+    /** Everything needed to diagnose a black canvas, as one JSON-able object. */
+    diagnostics(): {
+        at: string;
+        userAgent: string;
+        health: GpuHealthState;
+        heals: number;
+        events: GpuDiagEvent[];
+    };
+}

package/dist/gpu-health.js

@@ -0,0 +1,106 @@
+/**
+ * GPU health: is the device alive, and if not, why (ADR-0010: ported from Character XYZ
+ * `mesh/viewport/gpu-health.ts`, per instance instead of module-global).
+ *
+ * A lost `GPUDevice` fails silently: every later command is ignored, with no exception,
+ * and the canvas just stops presenting. This class listens for `device.lost` and
+ * `uncapturederror`, so a loss arrives with its reason. It counts uncaptured errors even
+ * while the device is healthy, keeping the FIRST one (the error that started a cascade)
+ * as well as the last. It keeps a bounded diagnostic ring that survives until the page
+ * reloads, which is the one action that destroys every other trace.
+ */
+/** Bounded: a validation storm is thousands of errors per second. */
+const MAX_EVENTS = 60;
+/** Heals repeat every frame until fixed; at most one per second. */
+const HEAL_COOLDOWN_MS = 1000;
+/**
+ * The recoverable attachment-size mismatch: a depth attachment allocated at one pixel ratio
+ * still bound after the ratio changed. Captured live in Character XYZ (2026-08-19); a
+ * resize rebuilds the attachments and fixes it.
+ */
+export function isRecoverableAttachmentMismatch(text) {
+    return /does not match the size/i.test(text) && /attachment/i.test(text);
+}
+/**
+ * Tracks one device.
+ *
+ * @example
+ * const health = new GpuHealth();
+ * const detach = health.attach(device, { onLost: (info) => app.deviceLost(info), onHeal: () => graph.forceResize() });
+ */
+export class GpuHealth {
+    state = { status: 'ok', reason: null, message: null, at: null, uncaptured: { count: 0, first: null, last: null } };
+    events = [];
+    heals = 0;
+    #lastHeal = -Infinity;
+    #record(kind, text) {
+        this.events.push({ t: performance.now(), kind, text: text.length > 400 ? `${text.slice(0, 400)}…` : text });
+        // Keep the first few (the cascade's start) and the tail (what happened last).
+        if (this.events.length > MAX_EVENTS)
+            this.events.splice(MAX_EVENTS / 2, 1);
+    }
+    /** Records a note beside the GPU events (a heal, a mode change). */
+    note(text) {
+        this.#record('note', text);
+    }
+    /**
+     * Listens to `device`. `onLost` gets the API's reason; `onHeal` runs when a known
+     * recoverable error arrives (rate-limited). Returns a detach function.
+     */
+    attach(device, hooks = {}) {
+        let attached = true;
+        const onError = (e) => {
+            const text = e.error?.message ?? String(e);
+            const u = this.state.uncaptured;
+            u.count++;
+            if (u.first === null)
+                u.first = text;
+            u.last = text;
+            if (u.count <= 8)
+                this.#record('uncaptured', text);
+            if (hooks.onHeal && isRecoverableAttachmentMismatch(text)) {
+                const now = performance.now();
+                if (now - this.#lastHeal >= HEAL_COOLDOWN_MS) {
+                    this.#lastHeal = now;
+                    this.heals++;
+                    this.#record('heal', `attachment-size mismatch → forcing a resize (attempt ${this.heals})`);
+                    hooks.onHeal('attachment-size-mismatch');
+                }
+            }
+        };
+        device.addEventListener('uncapturederror', onError);
+        void device.lost.then((info) => {
+            if (!attached)
+                return;
+            this.state.status = 'lost';
+            this.state.reason = info.reason || 'unknown';
+            this.state.message = info.message || null;
+            this.state.at = performance.now();
+            this.#record('device-lost', `reason=${this.state.reason} message=${info.message || '(none)'}`);
+            hooks.onLost?.({ reason: this.state.reason, message: info.message ?? '' });
+        });
+        return () => {
+            attached = false;
+            device.removeEventListener('uncapturederror', onError);
+        };
+    }
+    /** Marks a fresh device after recovery, keeping the history. */
+    reset() {
+        this.state.status = 'ok';
+        this.state.reason = null;
+        this.state.message = null;
+        this.state.at = null;
+        this.note('device recovered');
+    }
+    /** Everything needed to diagnose a black canvas, as one JSON-able object. */
+    diagnostics() {
+        return {
+            at: new Date().toISOString(),
+            userAgent: typeof navigator === 'undefined' ? '' : navigator.userAgent,
+            health: structuredClone(this.state),
+            heals: this.heals,
+            events: this.events.slice(),
+        };
+    }
+}
+//# sourceMappingURL=gpu-health.js.map

package/dist/gpu-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-health.js","sourceRoot":"","sources":["../src/gpu-health.ts"],"names":[],"mappings":"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"}

package/dist/gpu-timer.d.ts

@@ -0,0 +1,26 @@
+import type { PassTimer } from './frame-graph.ts';
+/**
+ * Per-pass GPU timings from `timestamp-query` (DESIGN.md §12, §19). Results arrive a few
+ * frames late through a ring of readback buffers, so the frame never waits on the GPU.
+ *
+ * Browsers quantize timestamps (on the order of 100 µs, DESIGN.md §22), so read these as
+ * budgets averaged over frames, not precise single-frame measurements.
+ */
+export declare class GpuTimer implements PassTimer {
+    #private;
+    readonly enabled: boolean;
+    /** Latest duration per pass slot, in milliseconds (NaN until the first result). */
+    readonly ms: Float64Array;
+    /** Readbacks completed so far; it changes when `ms` holds a new frame's results. */
+    results: number;
+    constructor(device: GPUDevice, enabled: boolean, maxPasses?: number);
+    /** GPU objects this timer owns (for the dispose leak check). */
+    get liveResources(): number;
+    /** Destroys the query set and buffers. */
+    destroy(): void;
+    timestampWrites(index: number): GPUComputePassTimestampWrites | undefined;
+    /** Call after recording the frame's passes, before `finish()`. */
+    resolve(encoder: GPUCommandEncoder): GPUBuffer | null;
+    /** Call after `queue.submit` with what `resolve` returned. */
+    collect(buffer: GPUBuffer | null): void;
+}

package/dist/gpu-timer.js

@@ -0,0 +1,93 @@
+const RING = 3;
+/**
+ * Per-pass GPU timings from `timestamp-query` (DESIGN.md §12, §19). Results arrive a few
+ * frames late through a ring of readback buffers, so the frame never waits on the GPU.
+ *
+ * Browsers quantize timestamps (on the order of 100 µs, DESIGN.md §22), so read these as
+ * budgets averaged over frames, not precise single-frame measurements.
+ */
+export class GpuTimer {
+    enabled;
+    /** Latest duration per pass slot, in milliseconds (NaN until the first result). */
+    ms;
+    /** Readbacks completed so far; it changes when `ms` holds a new frame's results. */
+    results = 0;
+    #device;
+    #set = null;
+    #resolve = null;
+    #ring = [];
+    #slots;
+    #writes = [];
+    #destroyed = false;
+    constructor(device, enabled, maxPasses = 32) {
+        this.#device = device;
+        this.enabled = enabled;
+        this.#slots = maxPasses;
+        this.ms = new Float64Array(maxPasses).fill(Number.NaN);
+        if (!enabled)
+            return;
+        const count = maxPasses * 2;
+        this.#set = device.createQuerySet({ label: 'yali:timestamps', type: 'timestamp', count });
+        this.#resolve = device.createBuffer({ label: 'yali:timestamps:resolve', size: count * 8, usage: GPUBufferUsage.QUERY_RESOLVE | GPUBufferUsage.COPY_SRC });
+        for (let i = 0; i < RING; i++) {
+            this.#ring.push({
+                buffer: device.createBuffer({ label: `yali:timestamps:read${i}`, size: count * 8, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST }),
+                busy: false,
+            });
+        }
+        for (let i = 0; i < maxPasses; i++) {
+            this.#writes.push({ querySet: this.#set, beginningOfPassWriteIndex: i * 2, endOfPassWriteIndex: i * 2 + 1 });
+        }
+    }
+    /** GPU objects this timer owns (for the dispose leak check). */
+    get liveResources() {
+        return this.#destroyed || !this.enabled ? 0 : 2 + this.#ring.length;
+    }
+    /** Destroys the query set and buffers. */
+    destroy() {
+        if (this.#destroyed)
+            return;
+        this.#destroyed = true;
+        this.#set?.destroy();
+        this.#resolve?.destroy();
+        for (const r of this.#ring)
+            r.buffer.destroy();
+    }
+    timestampWrites(index) {
+        return this.enabled && index < this.#slots ? this.#writes[index] : undefined;
+    }
+    /** Call after recording the frame's passes, before `finish()`. */
+    resolve(encoder) {
+        if (!this.#set || !this.#resolve)
+            return null;
+        const free = this.#ring.find((r) => !r.busy);
+        if (!free)
+            return null; // every readback still in flight: skip this frame's sample
+        encoder.resolveQuerySet(this.#set, 0, this.#slots * 2, this.#resolve, 0);
+        encoder.copyBufferToBuffer(this.#resolve, 0, free.buffer, 0, this.#slots * 16);
+        free.busy = true;
+        return free.buffer;
+    }
+    /** Call after `queue.submit` with what `resolve` returned. */
+    collect(buffer) {
+        if (!buffer)
+            return;
+        const slot = this.#ring.find((r) => r.buffer === buffer);
+        void buffer.mapAsync(GPUMapMode.READ).then(() => {
+            const t = new BigInt64Array(buffer.getMappedRange());
+            for (let i = 0; i < this.#slots; i++) {
+                const d = Number(t[i * 2 + 1] - t[i * 2]);
+                if (d > 0)
+                    this.ms[i] = d / 1e6;
+            }
+            buffer.unmap();
+            this.results++;
+            if (slot)
+                slot.busy = false;
+        }, () => {
+            if (slot)
+                slot.busy = false;
+        });
+    }
+}
+//# sourceMappingURL=gpu-timer.js.map

package/dist/gpu-timer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-timer.js","sourceRoot":"","sources":["../src/gpu-timer.ts"],"names":[],"mappings":"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"}

package/dist/headless.d.ts

@@ -0,0 +1,28 @@
+import { type YaliPlugin } from '@yali-engine/core';
+/** What `headlessRenderPlugin` records of the instances it extracts. */
+export interface HeadlessFrameStats {
+    /** Frames that reached Submit. */
+    frames: number;
+    /** Instances extracted in the last frame. */
+    instances: number;
+    /** An order-sensitive checksum of the last frame's extracted instance records (FNV-1a). */
+    checksum: number;
+}
+/**
+ * The render plugin for a run without a GPU (DESIGN.md §19 headless mode; ADR-0041): it
+ * registers as `@yali-engine/render`, so game plugins that depend on it build unchanged, and
+ * provides a `render` resource with what game code uses: the camera (updated each frame,
+ * as the real plugin does), the mesh and material stores, `render.Mesh`, and the counters.
+ * It runs the same extract as the real plugin and checksums the records instead of
+ * drawing them. GPU members (`gpu`, `scene`, `graph`, `timer`, `pipelines`, `health`,
+ * `profile`, `viewport`) are absent; `capture()` rejects with `NO_GPU`.
+ *
+ * @example
+ * const app = App.create({ core, seed: 1, frames: manual, clock: fixed, plugins: [headlessRenderPlugin(), game] });
+ * await app.init();
+ * for (let i = 0; i < 120; i++) app.step(1 / 60);
+ * app.resource<RenderContext & { stats: HeadlessFrameStats }>('render').stats.checksum;
+ */
+export declare function headlessRenderPlugin(options?: {
+    aspect?: number;
+}): YaliPlugin;