@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/fxaa.js

@@ -1,10 +1,12 @@
 import { definePlugin } from "@aethervtt/shard-runtime";
+import { addRenderFeatures } from "./features.js";
 import { RenderPhase } from "./graph.js";
 import { Graph, Shaders } from "./plugin.js";
 import { hasEffect, PostEffect, PostFeatures } from "./post.js";
 import { idOf, PostCache, sampler, tex } from "./post-common.js";
 import { FXAA_SHADERS } from "./post-shaders.js";
 import { registerShaders } from "./shaders.js";
+import { cameraOf } from "./view.js";
 function fxaaNode() {
   const cache = new PostCache();
   let layout;
@@ -24,15 +26,17 @@ function fxaaNode() {
       }
       const input = ctx.texture("ldr");
       const format = ctx.texture("display").format;
+      const alpha = cameraOf(ctx.view)?.alphaOutput === true;
       const pipeline = cache.render(
         ctx,
-        `fxaa/${format}`,
+        `fxaa/${format}${alpha ? "/alpha" : ""}`,
         "shard::post::fxaa",
         "fs",
         [layout],
         [{ format }],
         {
-          SRGB_TARGET: format.endsWith("-srgb")
+          SRGB_TARGET: format.endsWith("-srgb"),
+          TRANSPARENT: alpha
         }
       );
       if (!pipeline) return;
@@ -57,6 +61,12 @@ const fxaaPlugin = definePlugin({
     registerShaders(app.world.resource(Shaders), FXAA_SHADERS);
     const graph = app.world.resource(Graph);
     graph.declare({ name: "fxaa-in", format: "view" });
+    addRenderFeatures(app.world, {
+      name: "render/fxaa",
+      description: "Fast approximate anti-aliasing.",
+      nodes: ["post/fxaa"],
+      baseline: { strategy: "The same fragment pass" }
+    });
     graph.addNode("post/fxaa", fxaaNode());
   }
 });

package/dist/gizmos-plugin.js

@@ -2,6 +2,7 @@ import { First, Last } from "@aethervtt/shard-core";
 import { definePlugin } from "@aethervtt/shard-runtime";
 import { OriginShift } from "@aethervtt/shard-transform";
 import { GIZMO_SHADERS } from "./debug-shaders.js";
+import { addRenderFeatures } from "./features.js";
 import { upload } from "./forward.js";
 import { beginGizmos, GizmoGpuResource, Gizmos, gizmoNode, uploadGizmos } from "./gizmos.js";
 import { DebugOverlays, drawOverlays, gridsOverlay } from "./overlays.js";
@@ -26,6 +27,12 @@ const gizmosPlugin = definePlugin({
   },
   ready(app) {
     registerShaders(app.world.resource(Shaders), GIZMO_SHADERS);
+    addRenderFeatures(app.world, {
+      name: "render/gizmos",
+      description: "Debug lines, shapes and labels.",
+      nodes: ["gizmos"],
+      baseline: { strategy: "Line and glyph records in data textures" }
+    });
     app.world.resource(Graph).addNode("gizmos", gizmoNode(app.world));
   }
 });

package/dist/gizmos.d.ts

@@ -1,5 +1,5 @@
 import { type World } from '@aethervtt/shard-core';
-import { GpuBuffer } from '@aethervtt/shard-gpu';
+import { DataStore } from './data-store.js';
 import { type NodeDescriptor } from './graph.js';
 /**
  * Immediate-mode debug drawing. Any system calls `world.resource(Gizmos).line(…)` and the line
@@ -127,8 +127,8 @@ export declare const Gizmos: import("@aethervtt/shard-core").ResourceDef<GizmoSt
 export declare const beginGizmos: import("@aethervtt/shard-core").SystemDef<undefined>;
 interface GizmoGpu {
     generation: number;
-    lines: GpuBuffer;
-    glyphs: GpuBuffer;
+    lines: DataStore;
+    glyphs: DataStore;
     atlas: GPUTexture;
     layouts: {
         view: GPUBindGroupLayout;

package/dist/gizmos.js

@@ -1,10 +1,11 @@
 import { defineResource, defineSystem, mat4 } from "@aethervtt/shard-core";
-import { GpuBuffer } from "@aethervtt/shard-gpu";
 import { Time } from "@aethervtt/shard-runtime";
+import { DataStore, dataEntry } from "./data-store.js";
 import { ForwardStateResource } from "./forward.js";
 import { LABEL_FONT, labelAtlas, labelWidth } from "./gizmo-font.js";
 import { RenderPhase } from "./graph.js";
 import { Gpu, Shaders } from "./plugin.js";
+import { depthReadEntry } from "./tier.js";
 import { cameraOf } from "./view.js";
 const GIZMO_LINE_FLOATS = 8;
 const GLYPH_FLOATS = 12;
@@ -537,12 +538,9 @@ function gizmoGpu(world, gpu) {
   const glyphData = new Float32Array(GLYPH_FLOATS * 256);
   r.gpu = {
     generation: gpu.generation,
-    lines: new GpuBuffer(gpu, { label: "gizmos/lines", usage: GPUBufferUsage.STORAGE, size: 4096 }),
-    glyphs: new GpuBuffer(gpu, {
-      label: "gizmos/glyphs",
-      usage: GPUBufferUsage.STORAGE,
-      size: 4096
-    }),
+    // Read by the vertex stage: data textures on baseline (0064).
+    lines: new DataStore(gpu, { label: "gizmos/lines", size: 4096 }),
+    glyphs: new DataStore(gpu, { label: "gizmos/glyphs", size: 4096 }),
     atlas,
     layouts: {
       view: gpu.layouts.bindGroupLayout({
@@ -552,9 +550,9 @@ function gizmoGpu(world, gpu) {
       data: gpu.layouts.bindGroupLayout({
         label: "gizmos/data",
         entries: [
-          { binding: 0, visibility: V, buffer: { type: "read-only-storage" } },
-          { binding: 1, visibility: V, buffer: { type: "read-only-storage" } },
-          { binding: 2, visibility: F, texture: { sampleType: "depth" } },
+          dataEntry(gpu, 0, V),
+          dataEntry(gpu, 1, V),
+          depthReadEntry(gpu, 2, F),
           { binding: 3, visibility: F, texture: { sampleType: "float" } }
         ]
       })
@@ -733,11 +731,11 @@ function gizmoNode(world) {
           gpu,
           r,
           `data/${ctx.view.name}`,
-          `${idOf(r.lines.buffer)}/${idOf(r.glyphs.buffer)}/${idOf(depth)}/${idOf(r.atlas)}`,
+          `${r.lines.version}/${r.glyphs.version}/${idOf(depth)}/${idOf(r.atlas)}`,
           r.layouts.data,
           () => [
-            { binding: 0, resource: { buffer: r.lines.buffer } },
-            { binding: 1, resource: { buffer: r.glyphs.buffer } },
+            { binding: 0, resource: r.lines.resource() },
+            { binding: 1, resource: r.glyphs.resource() },
             { binding: 2, resource: depth.createView() },
             { binding: 3, resource: r.atlas.createView() }
           ]

package/dist/gpu-assets.d.ts

@@ -1,10 +1,11 @@
+import { type AssetServer } from '@aethervtt/shard-assets';
 import { type World } from '@aethervtt/shard-core';
 import type { GpuContext } from '@aethervtt/shard-gpu';
-import type { Mesh } from '@aethervtt/shard-mesh';
-import { type Texture } from '@aethervtt/shard-texture';
-import { type MaterialAsset } from './assets.js';
+import { Mesh } from '@aethervtt/shard-mesh';
+import { Texture } from '@aethervtt/shard-texture';
+import { MaterialAsset } from './assets.js';
 import type { MaterialType } from './materials.js';
-import type { GpuMemoryData } from './stats.js';
+import type { FrameCounts, GpuMemoryData } from './stats.js';
 export interface GpuMesh {
     version: number;
     generation: number;
@@ -48,6 +49,8 @@ export interface GpuTexture {
     version: number;
     generation: number;
     bytes: number;
+    /** Frees the texture and anything made from it (baseline twins); else `texture.destroy()`. */
+    destroy?(): void;
 }
 /**
  * GPU copies of meshes, textures, and materials, shared by every pass that draws them (forward,
@@ -56,6 +59,8 @@ export interface GpuTexture {
  */
 export declare class GpuAssets {
     readonly meshes: Map<Mesh, GpuMesh>;
+    /** Where mesh uploads are counted (`RenderStats.current.meshesRebuilt`), when set. */
+    counts: FrameCounts | undefined;
     readonly materials: Map<MaterialAsset, GpuMaterial>;
     readonly textures: Map<Texture, GpuTexture>;
     private defaults;
@@ -75,10 +80,25 @@ export declare class GpuAssets {
     readonly gpu: GpuContext;
     readonly memory: GpuMemoryData;
     materialLayout: GPUBindGroupLayout;
+    /**
+     * The baseline tier's texture strategy (0064), set on a baseline device: one format and one
+     * binding dimension per texture, and twins for slots that read it otherwise.
+     */
+    baseline: typeof import('./baseline/textures.js') | undefined;
+    /** Uploaded this frame on baseline: their bytes go at the next frame (twins take them first). */
+    private readonly releaseLater;
+    /** Asset guids of textures, for reloading one a twin needs. */
+    private readonly guids;
+    private world;
     constructor(gpu: GpuContext, memory: GpuMemoryData);
     /** Call once per frame before drawing: rebuilds after device loss and resets readiness. */
     beginFrame(): void;
     mesh(mesh: Mesh): GpuMesh;
+    /**
+     * Writes a CPU mesh's new data into the buffers of its previous version, when each fits and the
+     * mesh is still indexed the same way. Returns false when it needs new buffers.
+     */
+    private rewrite;
     private destroyMesh;
     /** Index buffers shared by GPU meshes, per index array. */
     private readonly sharedIndexBuffers;
@@ -87,8 +107,23 @@ export declare class GpuAssets {
      * normals, uvs, uvs1, tangents; f32), and the index buffer every mesh with the same array shares.
      */
     private gpuMesh;
+    /**
+     * Frees GPU copies of assets as the asset server drops them: unloaded (an owner released, 0061),
+     * or a fallback replaced by the real asset. Returns the unsubscribe.
+     */
+    watch(server: AssetServer): () => void;
+    /** The GPU objects made for one asset object (a texture, mesh or material): owners.describe (0061). */
+    objectsOf(item: unknown): {
+        buffers: number;
+        textures: number;
+        bytes: number;
+    };
     /** Frees a mesh's GPU buffers now (they're made again if it's drawn later). */
     releaseMesh(mesh: Mesh): void;
+    /** Frees a texture's GPU copy now (it's uploaded again if it's used later). */
+    releaseTexture(texture: Texture): void;
+    /** Frees a material's uniform buffers now (they're made again if it's drawn later). */
+    releaseMaterial(material: MaterialAsset): void;
     /** Uploads a texture (all levels) on first use and when its version changes. */
     texture(texture: Texture): GpuTexture | undefined;
     /** 1x1 white and flat-normal textures for empty slots. */
@@ -105,6 +140,25 @@ export declare class GpuAssets {
     private resolveSlots;
     /** Whether a texture can be uploaded; if its pixels are gone (device loss), reloads it. */
     private available;
+    private twins;
+    /** What baseline textures ask of this asset layer: reloads, fallbacks, and twin accounting. */
+    private twinHost;
+    /**
+     * Baseline (0064), `render.describe → twins`: the twins waiting for their bytes and how long
+     * they've waited, and the last ones made with their waits (0 when made from kept bytes).
+     */
+    describeTwins(): {
+        pending: {
+            texture: string;
+            kind: string;
+            waitedMs: number;
+        }[];
+        recent: {
+            texture: string;
+            kind: string;
+            waitedMs: number;
+        }[];
+    };
     /** The group-1 layout of a material type on this device. */
     layoutOf(type: MaterialType): GPUBindGroupLayout;
     /** The material's uniforms and bind group, uploaded when its version or textures change. */

package/dist/gpu-assets.js

@@ -1,11 +1,14 @@
-import { assetServer } from "@aethervtt/shard-assets";
+import { AssetServerResource, assetServer } from "@aethervtt/shard-assets";
 import { defineResource } from "@aethervtt/shard-core";
-import { FORMAT_INFO, Textures } from "@aethervtt/shard-texture";
-import { STANDARD_TYPE, TEXTURE_SLOTS } from "./assets.js";
+import { Mesh } from "@aethervtt/shard-mesh";
+import { FORMAT_INFO, Texture, Textures } from "@aethervtt/shard-texture";
+import { MaterialAsset, STANDARD_TYPE, TEXTURE_SLOTS } from "./assets.js";
 import { materialLayout } from "./shaders.js";
 const SRGB_SLOT = [true, false, false, false, true];
 class GpuAssets {
   meshes = /* @__PURE__ */ new Map();
+  /** Where mesh uploads are counted (`RenderStats.current.meshesRebuilt`), when set. */
+  counts;
   materials = /* @__PURE__ */ new Map();
   textures = /* @__PURE__ */ new Map();
   defaults;
@@ -31,6 +34,16 @@ class GpuAssets {
   gpu;
   memory;
   materialLayout;
+  /**
+   * The baseline tier's texture strategy (0064), set on a baseline device: one format and one
+   * binding dimension per texture, and twins for slots that read it otherwise.
+   */
+  baseline;
+  /** Uploaded this frame on baseline: their bytes go at the next frame (twins take them first). */
+  releaseLater = [];
+  /** Asset guids of textures, for reloading one a twin needs. */
+  guids = /* @__PURE__ */ new WeakMap();
+  world;
   constructor(gpu, memory) {
     this.gpu = gpu;
     this.memory = memory;
@@ -40,6 +53,11 @@ class GpuAssets {
   /** Call once per frame before drawing: rebuilds after device loss and resets readiness. */
   beginFrame() {
     this.ready.clear();
+    for (let i = 0; i < this.releaseLater.length; i++) {
+      const t = this.releaseLater[i];
+      if (!t.keepCpu) t.levels = void 0;
+    }
+    this.releaseLater.length = 0;
     if (this.generation === this.gpu.generation) return;
     this.generation = this.gpu.generation;
     this.materialLayout = createMaterialLayout(this.gpu);
@@ -56,7 +74,11 @@ class GpuAssets {
       if (mesh.gpu) gm.count = mesh.drawCount;
       return gm;
     }
-    if (gm && gm.generation === gpu.generation) this.destroyMesh(gm);
+    if (this.counts) this.counts.meshesRebuilt++;
+    if (gm && gm.generation === gpu.generation) {
+      if (!mesh.gpu && this.rewrite(mesh, gm)) return gm;
+      this.destroyMesh(gm);
+    }
     if (mesh.gpu) return this.gpuMesh(mesh);
     const device = gpu.device;
     const n = mesh.vertexCount;
@@ -97,6 +119,42 @@ class GpuAssets {
     this.meshes.set(mesh, gm);
     return gm;
   }
+  /**
+   * Writes a CPU mesh's new data into the buffers of its previous version, when each fits and the
+   * mesh is still indexed the same way. Returns false when it needs new buffers.
+   */
+  rewrite(mesh, gm) {
+    if (gm.sharedVertices || gm.sharedIndices) return false;
+    const indices = mesh.indices;
+    if (indices === void 0 !== (gm.indices === void 0)) return false;
+    const n = mesh.vertexCount;
+    const fits = (buffer, bytes) => buffer.size >= bytes;
+    if (!fits(gm.positions, n * 12) || !fits(gm.normals, n * 12) || !fits(gm.uvs, n * 8) || !fits(gm.uvs1, n * 8) || !fits(gm.tangents, n * 16) || indices !== void 0 && !fits(gm.indices, indices.byteLength + 3 & ~3))
+      return false;
+    const queue = this.gpu.device.queue;
+    const write = (buffer, data) => {
+      if (data.length > 0) queue.writeBuffer(buffer, 0, data, 0, data.length);
+    };
+    write(gm.positions, mesh.positions);
+    write(gm.normals, mesh.normals ?? new Float32Array(n * 3).map((_, i) => i % 3 === 1 ? 1 : 0));
+    const uvs = mesh.uvs ?? new Float32Array(n * 2);
+    write(gm.uvs, uvs);
+    write(gm.uvs1, mesh.uvs1 ?? uvs);
+    write(gm.tangents, mesh.tangents ?? new Float32Array(n * 4));
+    if (indices) {
+      let data = indices;
+      if (data instanceof Uint16Array && data.length % 2 === 1) {
+        const padded = new Uint16Array(data.length + 1);
+        padded.set(data);
+        data = padded;
+      }
+      write(gm.indices, data);
+      gm.indexFormat = indices instanceof Uint32Array ? "uint32" : "uint16";
+    }
+    gm.version = mesh.version;
+    gm.count = mesh.drawCount;
+    return true;
+  }
   destroyMesh(gm) {
     if (gm.sharedVertices) return;
     gm.positions.destroy();
@@ -155,6 +213,46 @@ class GpuAssets {
     this.meshes.set(mesh, gm);
     return gm;
   }
+  /**
+   * Frees GPU copies of assets as the asset server drops them: unloaded (an owner released, 0061),
+   * or a fallback replaced by the real asset. Returns the unsubscribe.
+   */
+  watch(server) {
+    return server.onUnload((_, item) => {
+      if (item instanceof Texture) this.releaseTexture(item);
+      else if (item instanceof Mesh) this.releaseMesh(item);
+      else if (item instanceof MaterialAsset) this.releaseMaterial(item);
+    });
+  }
+  /** The GPU objects made for one asset object (a texture, mesh or material): owners.describe (0061). */
+  objectsOf(item) {
+    const out = { buffers: 0, textures: 0, bytes: 0 };
+    const gpu = this.gpu;
+    if (item instanceof Texture) {
+      const gt = this.textures.get(item);
+      if (gt && gt.generation === gpu.generation) {
+        out.textures = 1;
+        out.bytes = gt.bytes;
+      }
+    } else if (item instanceof Mesh) {
+      const gm = this.meshes.get(item);
+      if (gm && gm.generation === gpu.generation && !gm.sharedVertices) {
+        const buffers = [gm.positions, gm.normals, gm.uvs, gm.uvs1, gm.tangents];
+        if (gm.indices && !gm.sharedIndices) buffers.push(gm.indices);
+        out.buffers = buffers.length;
+        for (const b of buffers) out.bytes += b.size;
+      }
+    } else if (item instanceof MaterialAsset) {
+      const gm = this.materials.get(item);
+      if (gm && gm.generation === gpu.generation) {
+        const buffers = [gm.buffer, gm.textureBuffer];
+        if (gm.ownBuffer) buffers.push(gm.ownBuffer);
+        out.buffers = buffers.length;
+        for (const b of buffers) out.bytes += b.size;
+      }
+    }
+    return out;
+  }
   /** Frees a mesh's GPU buffers now (they're made again if it's drawn later). */
   releaseMesh(mesh) {
     const gm = this.meshes.get(mesh);
@@ -162,6 +260,30 @@ class GpuAssets {
     if (gm.generation === this.gpu.generation) this.destroyMesh(gm);
     this.meshes.delete(mesh);
   }
+  /** Frees a texture's GPU copy now (it's uploaded again if it's used later). */
+  releaseTexture(texture) {
+    const gt = this.textures.get(texture);
+    if (!gt) return;
+    if (gt.generation === this.gpu.generation) {
+      if (gt.destroy) gt.destroy();
+      else gt.texture.destroy();
+      this.memory.textures--;
+      this.memory.textureBytes -= gt.bytes;
+    }
+    this.textures.delete(texture);
+  }
+  /** Frees a material's uniform buffers now (they're made again if it's drawn later). */
+  releaseMaterial(material) {
+    const gm = this.materials.get(material);
+    if (!gm) return;
+    if (gm.generation === this.gpu.generation) {
+      gm.buffer.destroy();
+      gm.textureBuffer.destroy();
+      gm.ownBuffer?.destroy();
+    }
+    this.materials.delete(material);
+    this.ready.delete(material);
+  }
   /** Uploads a texture (all levels) on first use and when its version changes. */
   texture(texture) {
     const gpu = this.gpu;
@@ -174,7 +296,16 @@ class GpuAssets {
       this.memory.textures--;
       this.memory.textureBytes -= existing.bytes;
     }
-    existing?.texture.destroy();
+    if (existing?.destroy) existing.destroy();
+    else existing?.texture.destroy();
+    if (this.baseline) {
+      const out2 = new this.baseline.BaselineTexture(this.twinHost(), texture);
+      this.textures.set(texture, out2);
+      this.memory.textures++;
+      this.memory.textureBytes += out2.bytes;
+      if (!texture.keepCpu) this.releaseLater.push(texture);
+      return out2;
+    }
     const info = FORMAT_INFO[texture.format];
     const srgbView = texture.gpuOnly ? void 0 : info.srgbView;
     const layers = texture.faces * texture.layers;
@@ -229,6 +360,14 @@ class GpuAssets {
   defaultTextures() {
     const gpu = this.gpu;
     if (this.defaults && this.defaults.white.generation === gpu.generation) return this.defaults;
+    if (this.baseline) {
+      this.defaults = {
+        white: this.baseline.solidTexture(this.twinHost(), [255, 255, 255, 255]),
+        normal: this.baseline.solidTexture(this.twinHost(), [128, 128, 255, 255])
+      };
+      this.samplers.clear();
+      return this.defaults;
+    }
     const solid = (label, rgba) => {
       const texture = gpu.device.createTexture({
         label,
@@ -289,6 +428,7 @@ class GpuAssets {
     return ready;
   }
   resolveSlots(world, material) {
+    this.world = world;
     const store = world.tryResource(Textures);
     material.sync();
     const type = material.type;
@@ -300,7 +440,7 @@ class GpuAssets {
         this.ownTextures[i] = void 0;
         continue;
       }
-      const texture = store?.get(ref);
+      const texture = store?.get(ref) ?? missingTexture(world, ref);
       if (!texture || !this.available(world, texture, ref)) return false;
       this.ownTextures[i] = texture;
     }
@@ -312,14 +452,22 @@ class GpuAssets {
         this.slotTextures[i] = void 0;
         continue;
       }
-      const texture = store?.get(ref);
+      const texture = store?.get(ref) ?? missingTexture(world, ref);
       if (!texture || !this.available(world, texture, ref)) return false;
       this.slotTextures[i] = texture;
     }
+    if (this.baseline && material.value.deferUntilReady) {
+      for (let i = 0; i < 5; i++) {
+        const texture = this.slotTextures[i];
+        const g = texture ? this.texture(texture) : void 0;
+        if (g && g.waiting(SRGB_SLOT[i], false)) return false;
+      }
+    }
     return true;
   }
   /** Whether a texture can be uploaded; if its pixels are gone (device loss), reloads it. */
   available(world, texture, ref) {
+    if (ref.guid) this.guids.set(texture, ref.guid);
     if (texture.levels || this.textures.has(texture)) return true;
     if (ref.guid && !this.reloading.has(ref.guid)) {
       this.reloading.add(ref.guid);
@@ -328,6 +476,34 @@ class GpuAssets {
     }
     return false;
   }
+  twins;
+  /** What baseline textures ask of this asset layer: reloads, fallbacks, and twin accounting. */
+  twinHost() {
+    const assets = this;
+    this.twins ??= new this.baseline.Twins({
+      gpu: this.gpu,
+      get world() {
+        return assets.world;
+      },
+      guidOf: (texture) => this.guids.get(texture),
+      reload: (texture) => {
+        const guid = this.guids.get(texture);
+        const world = this.world;
+        if (!guid || !world || this.reloading.has(guid)) return;
+        this.reloading.add(guid);
+        void assetServer(world).reload(guid).finally(() => this.reloading.delete(guid));
+      },
+      white: () => this.defaultTextures().white
+    });
+    return this.twins;
+  }
+  /**
+   * Baseline (0064), `render.describe → twins`: the twins waiting for their bytes and how long
+   * they've waited, and the last ones made with their waits (0 when made from kept bytes).
+   */
+  describeTwins() {
+    return this.twins?.describe() ?? { pending: [], recent: [] };
+  }
   /** The group-1 layout of a material type on this device. */
   layoutOf(type) {
     return type.bindGroupLayout(this.gpu, standardEntries());
@@ -451,7 +627,7 @@ class GpuAssets {
           });
         } else {
           const g = gm.ownBound[i] ?? defaults.white;
-          entries.push({ binding: binding++, resource: g.linear });
+          entries.push({ binding: binding++, resource: type.colors.has(name) ? g.srgb : g.linear });
         }
         entries.push({ binding: binding++, resource: this.sampler("repeat", "linear") });
       }
@@ -484,6 +660,13 @@ function standardEntries() {
 function createMaterialLayout(gpu) {
   return STANDARD_TYPE.bindGroupLayout(gpu, standardEntries());
 }
+function missingTexture(world, ref) {
+  if (ref.guid === void 0) return void 0;
+  const server = world.tryResource(AssetServerResource);
+  if (!server || server.entry(ref.guid)) return void 0;
+  server.missing(ref, "Texture");
+  return world.tryResource(Textures)?.byGuid(ref.guid);
+}
 const GpuAssetsResource = defineResource("render/GpuAssets", {
   description: "GPU copies of meshes, textures, and materials."
 });

package/dist/graph.d.ts

@@ -67,6 +67,11 @@ export interface NodeContext {
     /** Set for compute nodes. */
     readonly computePass: GPUComputePassEncoder | undefined;
     texture(name: string): GPUTexture;
+    /**
+     * Hands later nodes `texture` as resource `name` for the rest of this view's frame, instead of a
+     * pooled one: a node that keeps its output across frames (TAA's history) writes it once.
+     */
+    provide(name: string, texture: GPUTexture): void;
     /** Timestamp writes for a pass the node begins itself (raw nodes), labeled `name`. */
     timestamps(name: string): GPURenderPassTimestampWrites | undefined;
     /** Runs after the frame's commands are submitted (e.g. to map a readback buffer). */
@@ -85,6 +90,11 @@ export interface NodeDescriptor {
     phase?: number;
     /** Runs even if nothing reads its outputs. */
     sideEffects?: boolean;
+    /**
+     * Render nodes: always a render pass of its own, never shared with the nodes around it (see
+     * `continues`), so its GPU time is its own: what reads it (FoliageBudget's `gpu:foliage/*`) needs it.
+     */
+    ownPass?: boolean;
     /**
      * Whether the node runs for a view (e.g. only when the camera has the effect's component).
      * Disabled nodes are removed before resolving, so what they fed is culled too.
@@ -103,8 +113,14 @@ export declare const RenderPhase: {
     readonly Opaque: 300;
     readonly Lighting: 350;
     readonly Sky: 400;
+    /** Coplanar ground bands (0057): after the sky, which draws where no depth was written. */
+    readonly Ground: 420;
     readonly Sprites: 450;
     readonly Transparent: 500;
+    /** Projected fog's composite (0058): after transparent objects, before the overlay band. */
+    readonly Fog: 520;
+    /** Ground bands from the overlay band up, over fog (0058). */
+    readonly Overlay3d: 530;
     readonly Effects3d: 550;
     readonly Resolve: 600;
     readonly Post: 700;
@@ -163,17 +179,46 @@ export declare class RenderGraph {
     /** Views rendered in the last frame, in order. */
     private lastViews;
     private readonly viewData;
+    /** Each node's `render/<node>` span and its CPU time this frame, summed over views (0074). */
+    private readonly nodeSlots;
+    private readonly nodeSpans;
+    private nodeMs;
+    private nodeRan;
+    /** Nodes disabled for measurement (0075): see `ablate`. */
+    private readonly ablatedNodes;
     constructor(gpu: GpuContext);
+    /** Rejects pending captures and destroys the timer's query set (the app is being disposed). */
+    dispose(): void;
     addNode(name: string, node: NodeDescriptor): void;
     removeNode(name: string): void;
     hasNode(name: string): boolean;
+    /** Every node's name, in the order they were added. */
+    nodeNames(): string[];
+    /**
+     * Disables nodes for measurement (0075's ablation), replacing the previous set; `[]` restores
+     * them. A disabled render or compute node still begins and ends its pass, with its attachments'
+     * clears, so the textures it writes stay valid for what reads them; only its `run` (its draws and
+     * dispatches) is skipped. A raw node, which begins its own passes, is skipped whole. The graph
+     * resolves as before: what the node fed still runs, on whatever its textures hold. The image is
+     * wrong while nodes are disabled. Throws `render/unknown-node` for a name the graph lacks.
+     */
+    ablate(names: Iterable<string>): void;
+    /** The nodes `ablate` disabled. */
+    ablated(): string[];
     /** The data of a view rendered in the last frame. */
     lastViewData(view: string): Record<string, unknown> | undefined;
     /** Declares a transient texture any node can write, read, or attach by name. */
     declare(texture: TransientTexture): void;
     /** The resolution with every node enabled and no aliases. */
     resolve(): ResolvedGraph;
+    /** `off`: nodes that don't run on this device (features the baseline tier doesn't support). */
     private resolveFor;
+    /**
+     * Whether render node `order[k]` can draw in the pass `order[from]` began: the same color
+     * attachments, loaded rather than cleared, the same depth (written only if the pass writes it),
+     * and nothing it samples bound as an attachment.
+     */
+    private continues;
     /** Whether a node after `k` loads or reads `resource` (so its contents must be stored). */
     private loadedLater;
     /**