@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/outline.js

@@ -0,0 +1,42 @@
+import { defineComponent, defineResource, onAdd, t } from "@aethervtt/shard-core";
+import { warnFeatureMissing } from "./features.js";
+const OUTLINE_OCCLUSION = ["hide", "show", "dim"];
+const Outline = defineComponent(
+  "render/Outline",
+  {
+    color: t.color({
+      default: [1, 0.78, 0.2, 1],
+      description: "Outline color (linear), with alpha."
+    }),
+    width: t.f32({
+      default: 2,
+      min: 0,
+      max: 32,
+      unit: "px",
+      description: "Width in CSS pixels, outside the silhouette, at any zoom and display density."
+    }),
+    occluded: t.enum(OUTLINE_OCCLUSION, {
+      description: "Where something hides the outlined object: hide the outline there, show it anyway, or dim it."
+    })
+  },
+  {
+    description: "Outlines a renderable, or every renderable under this entity. Selection and hover are two Outlines with different colors; the host sets and clears them."
+  }
+);
+const OutlinePath = defineResource("render/OutlinePath", {
+  description: "Present when the outline pass is installed."
+});
+const MAX_OUTLINE_STYLES = 16;
+function observeOutlinesWithoutPass(world) {
+  world.observe(onAdd(Outline), ({ world: w }) => {
+    if (!w.hasResource(OutlinePath))
+      warnFeatureMissing(w, "An entity has Outline", "outlinePlugin", "it draws no outline");
+  });
+}
+export {
+  MAX_OUTLINE_STYLES,
+  OUTLINE_OCCLUSION,
+  Outline,
+  OutlinePath,
+  observeOutlinesWithoutPass
+};

package/dist/overlays.js

@@ -34,6 +34,7 @@ function scenePath(world, entity) {
   return v?.path || void 0;
 }
 const DebugOverlays = defineResource("render/DebugOverlays", {
+  hostWritable: true,
   description: "Built-in debug drawings, each drawn through Gizmos: bounds, light volumes, camera frustums, shadow cascades, normals, transform axes, and entity labels.",
   init: () => ({
     bounds: false,

package/dist/picking.d.ts

@@ -12,7 +12,22 @@ export interface PickHit {
     normal: [number, number, number];
     /** Meters from the camera (from the ray origin, for raycasts). */
     distance: number;
+    /**
+     * What within the entity was hit, when something knows (0059): a tilemap gives
+     * `{ kind: 'tile', layer, x, y, tile }`, the tile named as its palette names it.
+     */
+    detail?: PickDetail;
 }
+/** Detail of a pick within an entity: `kind` says what the rest means. */
+export interface PickDetail {
+    kind: string;
+    [key: string]: unknown;
+}
+/**
+ * Turns a hit into detail about what within the entity it hit (a tile of a tilemap), or
+ * undefined when the hit isn't its kind. Runs for GPU picks and raycasts alike.
+ */
+export type PickDetailer = (world: World, hit: PickHit) => PickDetail | undefined;
 interface PickRequest {
     x: number;
     y: number;
@@ -35,6 +50,8 @@ export interface PickingState {
     pending: Map<string, PickRequest[]>;
     drawers: Map<string, PickDrawer>;
     blockers: Map<string, PickBlocker>;
+    /** Detail for hits, by who adds it (tilemaps). */
+    detailers: Map<string, PickDetailer>;
     /** Views whose pick pass skipped a draw (a pipeline still compiling): their picks wait a frame. */
     incomplete: Set<string>;
 }

package/dist/picking.js

@@ -1,9 +1,10 @@
 import { defineResource, mat4, ShardError } from "@aethervtt/shard-core";
 import { GlobalTransform } from "@aethervtt/shard-transform";
-import { Meshes } from "./assets.js";
-import { drawMaterials, ForwardStateResource, PASS_PICK } from "./forward.js";
+import { Materials, Meshes } from "./assets.js";
+import { addRenderFeatures } from "./features.js";
+import { drawMaterials, ForwardStateResource, PASS_PICK, PASS_PICK_GROUND } from "./forward.js";
 import { RenderPhase } from "./graph.js";
-import { Lod, Mesh3d } from "./instances.js";
+import { Lod, Mesh3d, MeshMaterial } from "./instances.js";
 import { DebugOverlays } from "./overlays.js";
 import { Graph, Views } from "./plugin.js";
 import { cameraOf } from "./view.js";
@@ -14,6 +15,7 @@ const Picking = defineResource("render/Picking", {
     pending: /* @__PURE__ */ new Map(),
     drawers: /* @__PURE__ */ new Map(),
     blockers: /* @__PURE__ */ new Map(),
+    detailers: /* @__PURE__ */ new Map(),
     incomplete: /* @__PURE__ */ new Set()
   })
 });
@@ -69,6 +71,8 @@ function pickNode(world) {
       drawMaterials(ctx, state, pv, cam, cam.draws, PASS_PICK);
       if (cam.deferred) drawMaterials(ctx, state, pv, cam, cam.forwardOnly, PASS_PICK);
       drawMaterials(ctx, state, pv, cam, cam.transparent, PASS_PICK);
+      drawMaterials(ctx, state, pv, cam, cam.ground, PASS_PICK_GROUND);
+      drawMaterials(ctx, state, pv, cam, cam.overlay, PASS_PICK_GROUND);
       for (const draw of picking.drawers.values()) draw(ctx, cam);
       if (ctx.gpu.pipelines.skipped > skipped) picking.incomplete.add(ctx.view.name);
     }
@@ -147,13 +151,15 @@ function pickReadbackNode(world) {
               const dx = position[0] - eye[0];
               const dy = position[1] - eye[1];
               const dz = position[2] - eye[2];
-              r.resolve({
-                entity,
-                path: w.isAlive(entity) ? name(w, entity) : void 0,
-                position,
-                normal: [n[0], n[1], n[2]],
-                distance: Math.sqrt(dx * dx + dy * dy + dz * dz)
-              });
+              r.resolve(
+                withDetail(w, {
+                  entity,
+                  path: w.isAlive(entity) ? name(w, entity) : void 0,
+                  position,
+                  normal: [n[0], n[1], n[2]],
+                  distance: Math.sqrt(dx * dx + dy * dy + dz * dz)
+                })
+              );
             });
             buffer.unmap();
             buffer.destroy();
@@ -173,6 +179,12 @@ function addPickNodes(world) {
   graph.declare({ name: "pick-id", format: "r32uint", usage });
   graph.declare({ name: "pick-normal", format: "rgba32float", usage });
   graph.declare({ name: "pick-depth", format: "depth32float" });
+  addRenderFeatures(world, {
+    name: "render/picking",
+    description: "Entity picking from id and normal targets, read back per request.",
+    nodes: ["picking", "picking/readback"],
+    baseline: { strategy: "The same targets, read back with copies" }
+  });
   graph.addNode("picking", pickNode(world));
   graph.addNode("picking/readback", pickReadbackNode(world));
 }
@@ -235,11 +247,14 @@ function worldBox(bb, m, out) {
 }
 function buildBvh(world, tick, tables) {
   const items = [];
+  const materials = world.tryResource(Materials);
   for (const table of world.query({ with: [Mesh3d, GlobalTransform, ComputedVisibility] }).tables) {
     const g = table.column(GlobalTransform, "matrix");
     const vis = table.column(ComputedVisibility, "visible");
+    const refs = table.has(MeshMaterial) ? table.column(MeshMaterial, "material") : void 0;
     for (let i = 0; i < table.count; i++) {
       if (!vis[i]) continue;
+      if (refs && materials?.get(refs[i])?.type.pickable === false) continue;
       const entity = table.entities[i];
       const mesh = meshOf(world, entity);
       if (!mesh) continue;
@@ -442,7 +457,21 @@ function raycast(world, origin, direction, options = {}) {
     }
   }
   hits.sort((a, b) => a.distance - b.distance);
-  return options.all ? hits : hits.slice(0, 1);
+  const out = options.all ? hits : hits.slice(0, 1);
+  for (const hit of out) withDetail(world, hit);
+  return out;
+}
+function withDetail(world, hit) {
+  const detailers = world.tryResource(Picking)?.detailers;
+  if (!detailers || detailers.size === 0 || !world.isAlive(hit.entity)) return hit;
+  for (const detailer of detailers.values()) {
+    const detail = detailer(world, hit);
+    if (detail) {
+      hit.detail = detail;
+      break;
+    }
+  }
+  return hit;
 }
 export {
   BvhResource,

package/dist/pixel-perfect-plugin.js

@@ -1,4 +1,5 @@
 import { definePlugin } from "@aethervtt/shard-runtime";
+import { addRenderFeatures } from "./features.js";
 import { RenderPhase } from "./graph.js";
 import { PixelPerfectPath } from "./pixel-perfect.js";
 import { Graph, Shaders } from "./plugin.js";
@@ -6,7 +7,7 @@ import { registerShaders } from "./shaders.js";
 const PIXEL_PERFECT_SHADERS = {
   "shard::post::pixel_upscale": `
 struct Upscale {
-  /** offset (xy), scale, 0. */
+  /** offset (xy), scale, the bars' alpha (0 for a camera clearing to alpha, 0052). */
   params: vec4f,
 }
 
@@ -17,7 +18,7 @@ struct Upscale {
 @fragment fn fs(@builtin(position) frag: vec4f) -> @location(0) vec4f {
   let p = (frag.xy - upscale.params.xy) / upscale.params.z;
   let size = vec2f(textureDimensions(source));
-  if (any(p < vec2f(0.0)) || any(p >= size)) { return vec4f(0.0, 0.0, 0.0, 1.0); }
+  if (any(p < vec2f(0.0)) || any(p >= size)) { return vec4f(0.0, 0.0, 0.0, upscale.params.w); }
   return textureLoad(source, vec2i(floor(p)), 0);
 }`
 };
@@ -92,6 +93,7 @@ function pixelUpscaleNode() {
       params[0] = layout.offsetX;
       params[1] = layout.offsetY;
       params[2] = layout.scale;
+      params[3] = ctx.view.data.alphaOutput === true ? 0 : 1;
       gpu.device.queue.writeBuffer(buffer, 0, params);
       const source = layout.target.texture();
       let cached = groups.get(ctx.view.name);
@@ -125,6 +127,12 @@ const pixelPerfectPlugin = definePlugin({
   },
   ready(app) {
     registerShaders(app.world.resource(Shaders), PIXEL_PERFECT_SHADERS);
+    addRenderFeatures(app.world, {
+      name: "render/pixel-perfect",
+      description: "Pixel-art cameras: low-resolution render, integer upscale.",
+      nodes: ["pixel-upscale"],
+      baseline: { strategy: "The same fragment pass" }
+    });
     app.world.resource(Graph).addNode("pixel-upscale", pixelUpscaleNode());
   }
 });

package/dist/plugin.d.ts

@@ -1,9 +1,9 @@
 import { type World } from '@aethervtt/shard-core';
-import { type GpuContext } from '@aethervtt/shard-gpu';
+import { type GpuBackendChoice, type GpuContext, type Surface, type SurfaceAlpha, type Webgl2ContextOptions } from '@aethervtt/shard-gpu';
 import { type Plugin } from '@aethervtt/shard-runtime';
 import { type ShaderBake, ShaderLibrary } from '@aethervtt/shard-shader';
 import { type CapturedBuffer, type CapturedImage, RenderGraph, type RenderView } from './graph.js';
-import { type RenderTarget } from './target.js';
+import type { RenderTarget } from './target.js';
 export declare const Gpu: import("@aethervtt/shard-core").ResourceDef<GpuContext>;
 export declare const Graph: import("@aethervtt/shard-core").ResourceDef<RenderGraph>;
 export declare const Shaders: import("@aethervtt/shard-core").ResourceDef<ShaderLibrary>;
@@ -29,16 +29,43 @@ export declare const RenderSet: {
     readonly Graph: import("@aethervtt/shard-core").SystemSetDef;
 };
 export interface RenderPluginOptions {
-    /** Render into this canvas. Omit for headless (views use offscreen targets). */
+    /**
+     * Render into this canvas: the plugin adds it as a surface of `gpu` (or of a device it makes).
+     * Omit for headless (views use offscreen targets).
+     */
     canvas?: HTMLCanvasElement | OffscreenCanvas;
-    /** An existing GPU context (e.g. Dawn in Node). Otherwise one is created in `ready`. */
+    /**
+     * With `canvas`: 'premultiplied' composites the canvas over the page, where cameras clearing to
+     * alpha 0 show what's under it (0052). Default 'opaque'.
+     */
+    alpha?: SurfaceAlpha;
+    /** Render into a surface already on `gpu` (`gpu.addSurface`). Disposing the app removes it. */
+    surface?: Surface;
+    /**
+     * An existing GPU context (e.g. Dawn in Node, or one shared with other apps). Otherwise one is
+     * created in `ready` and destroyed with the app.
+     */
     gpu?: GpuContext;
+    /** The name this app's GPU objects count under in `gpu.stats(owner)`. Default `render:<n>`. */
+    owner?: string;
     /**
      * Headless stand-in for the window: cameras without a target render here. Used by the CLI for
-     * screenshots. Ignored when there's a canvas.
+     * screenshots. Ignored when there's a canvas or surface.
      */
     target?: RenderTarget;
     features?: GPUFeatureName[];
+    /**
+     * The graphics API, when the plugin makes the device (0064). 'auto' (default): WebGPU where it
+     * works, else WebGL2 on the baseline tier. 'webgpu' or 'webgl2' insist on one.
+     */
+    backend?: GpuBackendChoice;
+    /** WebGL2 settings, for tests and tools (the 'minimum' profile, GL error checks). */
+    webgl2?: Webgl2ContextOptions;
+    /**
+     * 'baseline' runs the baseline tier even where the full one would (on WebGPU, a
+     * compatibility-mode device), when the plugin makes the device.
+     */
+    tier?: 'baseline';
     /** An existing shader library to share (e.g. a preview rendering the game's own shaders). */
     shaders?: ShaderLibrary;
     /**
@@ -57,8 +84,15 @@ export interface RenderPluginOptions {
  * so the renderer's description grows with what's installed.
  */
 export declare const RenderDescribers: import("@aethervtt/shard-core").ResourceDef<Map<string, (world: World) => unknown>>;
-export declare const RenderOptions: import("@aethervtt/shard-core").ResourceDef<Required<Pick<RenderPluginOptions, "windowView">>>;
+export interface RenderOptionsValue {
+    windowView: boolean;
+    /** What this app's GPU objects count under in `gpu.stats` (0052). */
+    owner: string;
+}
+export declare const RenderOptions: import("@aethervtt/shard-core").ResourceDef<RenderOptionsValue>;
 export declare function renderPlugin(options?: RenderPluginOptions): Plugin;
+/** The name this app's GPU objects count under in `gpu.stats` (0052). */
+export declare function renderOwner(world: World): string;
 /** A screenshot of a view (default: the window) after the next frame renders it. */
 export declare function captureView(world: World, view?: string): Promise<CapturedImage>;
 /**
@@ -108,4 +142,22 @@ export declare function describeRender(world: World): {
         path?: string;
         details?: unknown[];
     }[];
+    features: {
+        name: string;
+        nodes: string[];
+        baseline: string;
+    }[];
+    health: import("./health.js").RenderHealthValue;
+    backend: import("@aethervtt/shard-gpu").GpuBackendName;
+    tier: import("@aethervtt/shard-gpu").GpuTier;
+    capabilities: import("@aethervtt/shard-gpu").GpuCapabilities;
+    shaderCache: import("@aethervtt/shard-gpu").ShaderCacheStats | undefined;
+    limits: {
+        maxTextureDimension2D: number;
+        maxColorAttachments: number;
+        maxSampledTexturesPerShaderStage: number;
+        maxInterStageShaderVariables: number;
+        maxUniformBufferBindingSize: number;
+    };
+    reasons: readonly import("@aethervtt/shard-gpu").GraphicsReason[];
 } & Record<string, unknown>;

package/dist/plugin.js

@@ -1,3 +1,4 @@
+import { AssetServerResource } from "@aethervtt/shard-assets";
 import {
   defineEvent,
   defineResource,
@@ -6,15 +7,30 @@ import {
   Last,
   ShardError
 } from "@aethervtt/shard-core";
-import { createGpuContext } from "@aethervtt/shard-gpu";
-import { definePlugin, LogResource } from "@aethervtt/shard-runtime";
+import {
+  createGpuContext
+} from "@aethervtt/shard-gpu";
+import {
+  definePlugin,
+  FrameDemand,
+  LOADING_DEMAND,
+  LogResource
+} from "@aethervtt/shard-runtime";
 import { ShaderLibrary } from "@aethervtt/shard-shader";
+import { loadDataTextures, releaseDataStores } from "./data-store.js";
+import { checkUnsupportedFeatures, describeFeatures, RenderFeatures } from "./features.js";
 import { RenderGraph } from "./graph.js";
+import {
+  healthSystem,
+  RenderHealth,
+  RenderHealthChanged,
+  RenderHealthReports,
+  raiseHealthIssue
+} from "./health.js";
 import { registerEngineShaders } from "./shaders.js";
 import { GpuMemory, RenderCounters, RenderStats } from "./stats.js";
-import { WindowTarget } from "./target.js";
 const Gpu = defineResource("render/Gpu", {
-  description: "The GPU device, caches, and canvas."
+  description: "The GPU device, its surfaces (canvases), and caches. Apps can share one."
 });
 const Graph = defineResource("render/Graph", {
   description: "Render graph nodes, run for every view each frame."
@@ -26,7 +42,7 @@ const Views = defineResource("render/Views", {
   description: "Views to render this frame. Rebuilt every frame by extract systems."
 });
 const Window = defineResource("render/Window", {
-  description: "Where cameras without a target render: the canvas swapchain, or an offscreen target when headless."
+  description: "Where cameras without a target render: the app's surface (canvas), or an offscreen target when headless."
 });
 const GpuDeviceLost = defineEvent(
   "render/GpuDeviceLost",
@@ -51,12 +67,37 @@ const begin = defineSystem({
     world.resource(Gpu).pipelines.skipped = 0;
   }
 });
+const markMissing = defineSystem({
+  name: "render/mark-missing",
+  description: "Puts MissingAsset on entities that reference an asset showing a fallback.",
+  run: (_, world) => world.tryResource(AssetServerResource)?.markMissing()
+});
+const checkUnsupported = defineSystem({
+  name: "render/check-unsupported",
+  description: "On the baseline tier: reports render features the scene uses that it can't run (render/feature-unsupported), and WebGL2 shaders translated at load (render/shader-cache-miss).",
+  setup: () => ({ misses: 0 }),
+  run: (state, world) => {
+    const gpu = world.tryResource(Gpu);
+    if (gpu?.tier !== "baseline") return;
+    checkUnsupportedFeatures(world);
+    const cache = gpu.shaderCache();
+    if (!cache || cache.misses.length === state.misses) return;
+    state.misses = cache.misses.length;
+    let ms = 0;
+    for (const m of cache.misses) ms += m.ms;
+    const load = cache.nagaLoadMs === void 0 ? "" : `, ${cache.nagaLoadMs.toFixed(0)} ms to load it`;
+    raiseHealthIssue(world, {
+      code: "render/shader-cache-miss",
+      severity: "info",
+      message: `${state.misses} shader stage${state.misses === 1 ? "" : "s"} translated to GLSL at load (${ms.toFixed(0)} ms in naga${load}): \`shard shaders bake\` ships them translated`
+    });
+  }
+});
 const execute = defineSystem({
   name: "render/execute-graph",
   description: "Runs the render graph for every view and submits.",
-  setup: () => ({ recovering: { value: false } }),
-  run: ({ recovering }, world) => {
-    if (recovering.value) return;
+  run: (_, world) => {
+    if (world.resource(Gpu).status !== "ok") return;
     const views = world.resource(Views).list;
     const window = world.tryResource(Window);
     const options = world.resource(RenderOptions);
@@ -65,13 +106,35 @@ const execute = defineSystem({
     }
     if (views.length === 0) return;
     world.resource(Graph).execute(world, views);
+    world.tryResource(RenderStats)?.endFrame(world.resource(Gpu).uploads(options.owner));
+    const gpu = world.resource(Gpu);
+    anyPending = gpu.pipelines.skipped > 0 || gpu.pipelines.pending > 0;
+    if (!anyPending) world.tryResource(RenderStats)?.forEach(notePending);
+    world.tryResource(FrameDemand)?.set(LOADING_DEMAND, anyPending);
   }
 });
+let anyPending = false;
+function notePending(stats) {
+  if (stats.pending > 0) anyPending = true;
+}
 const RenderDescribers = defineResource(
   "render/Describers",
   { description: "Sections plugins add to render.describe.", init: () => /* @__PURE__ */ new Map() }
 );
-const RenderOptions = defineResource("render/Options");
+const RenderOptions = defineResource("render/Options", {
+  description: "The render plugin's settings: the fallback window view, and the app's GPU owner."
+});
+const renderApps = /* @__PURE__ */ new WeakMap();
+let nextOwner = 1;
+function nextRefresh() {
+  return new Promise((resolve) => requestAnimationFrame(resolve));
+}
+function presentOn(state) {
+  return () => {
+    const done = state.gpu.device.queue.onSubmittedWorkDone();
+    return typeof requestAnimationFrame === "function" ? done.then(nextRefresh) : done.then(() => void 0);
+  };
+}
 function renderPlugin(options = {}) {
   return definePlugin({
     name: "render",
@@ -81,6 +144,10 @@ function renderPlugin(options = {}) {
       GpuDeviceLost,
       Graph,
       RenderDescribers,
+      RenderFeatures,
+      RenderHealth,
+      RenderHealthChanged,
+      RenderHealthReports,
       RenderOptions,
       Shaders,
       Views,
@@ -88,40 +155,123 @@ function renderPlugin(options = {}) {
     ],
     dependencies: ["core/time"],
     build(app) {
-      app.insertResource(Views, { list: [] }).insertResource(RenderOptions, { windowView: options.windowView ?? true }).configureSets(
+      const state = {
+        owner: options.owner ?? `render:${nextOwner++}`,
+        gpu: void 0,
+        ownsDevice: false,
+        surface: void 0,
+        saved: [],
+        unsubscribe: []
+      };
+      renderApps.set(app, state);
+      app.addScope({
+        enter() {
+          const gpu = state.gpu;
+          state.saved.push(gpu?.owner);
+          if (gpu) gpu.owner = state.owner;
+        },
+        exit() {
+          const previous = state.saved.pop();
+          if (state.gpu && previous !== void 0) state.gpu.owner = previous;
+        }
+      });
+      app.insertResource(Views, { list: [] }).insertResource(RenderOptions, {
+        windowView: options.windowView ?? true,
+        owner: state.owner
+      }).configureSets(
         Last,
         RenderSet.Extract.after(RenderSet.Begin),
         RenderSet.Prepare.after(RenderSet.Extract),
         RenderSet.Queue.after(RenderSet.Prepare),
         RenderSet.Upload.after(RenderSet.Queue),
         RenderSet.Graph.after(RenderSet.Upload)
-      ).addSystems(Last, begin.inSet(RenderSet.Begin), execute.inSet(RenderSet.Graph));
+      ).addSystems(
+        Last,
+        begin.inSet(RenderSet.Begin),
+        markMissing.inSet(RenderSet.Begin).after(begin),
+        checkUnsupported.inSet(RenderSet.Begin).after(begin),
+        execute.inSet(RenderSet.Graph),
+        healthSystem({ status: () => state.gpu?.status ?? "ok" }).inSet(RenderSet.Graph).after(execute)
+      );
     },
     async ready(app) {
-      const gpu = options.gpu ?? await createGpuContext({ canvas: options.canvas, features: options.features });
-      app.insertResource(Gpu, gpu);
-      app.insertResource(Graph, new RenderGraph(gpu));
+      const state = renderApps.get(app);
+      const given = options.gpu ?? options.surface?.gpu;
+      if (options.surface && options.gpu && options.surface.gpu !== options.gpu) {
+        throw new ShardError("render/surface-device", "The surface belongs to another GpuContext", {
+          hint: "Pass the GpuContext the surface was added to (surface.gpu), or omit gpu."
+        });
+      }
+      const gpu = given ?? await createGpuContext({
+        features: options.features,
+        backend: options.backend,
+        webgl2: options.webgl2,
+        tier: options.tier,
+        canvas: options.canvas,
+        alpha: options.alpha
+      });
+      state.gpu = gpu;
+      state.ownsDevice = !given;
+      if (gpu.tier === "baseline") await loadDataTextures();
+      gpu.withOwner(state.owner, () => {
+        app.insertResource(Gpu, gpu);
+        app.insertResource(Graph, new RenderGraph(gpu));
+      });
+      app.setPresenter(presentOn(state));
       const shaders = options.shaders ?? new ShaderLibrary();
       if (!options.shaders) registerEngineShaders(shaders);
       if (options.shaderBake) shaders.preload(options.shaderBake);
       app.insertResource(Shaders, shaders);
-      if (gpu.context) app.insertResource(Window, new WindowTarget(gpu));
-      else if (options.target) app.insertResource(Window, options.target);
+      const surface = options.surface ?? (options.canvas ? gpu.surfaces.find((s) => s.canvas === options.canvas) ?? gpu.addSurface(options.canvas, { alpha: options.alpha }) : void 0);
+      state.surface = surface;
+      if (surface) {
+        app.insertResource(Window, surface);
+        state.unsubscribe.push(surface.onResize(() => app.disposed || app.requestFrame()));
+      } else if (options.target) app.insertResource(Window, options.target);
       const log = app.world.tryResource(LogResource);
-      if (log) gpu.onError((error) => log.error(error));
-      gpu.onDeviceLost((info) => {
-        app.world.send(GpuDeviceLost, info);
-        void gpu.recreate();
-      });
+      if (log) state.unsubscribe.push(gpu.onError((error) => log.error(error)));
+      state.unsubscribe.push(
+        gpu.onDeviceLost((info) => {
+          app.world.send(GpuDeviceLost, info);
+          gpu.recreate().then(
+            () => app.disposed || app.requestFrame(),
+            () => app.disposed || app.requestFrame()
+          );
+        })
+      );
+    },
+    beforeDispose(app) {
+      const gpu = renderApps.get(app)?.gpu;
+      if (gpu?.status === "ok") return gpu.device.queue.onSubmittedWorkDone();
+    },
+    dispose(app) {
+      const state = renderApps.get(app);
+      if (!state) return;
+      renderApps.delete(app);
+      for (const off of state.unsubscribe.splice(0)) off();
+      app.world.tryResource(Graph)?.dispose();
+      state.surface?.remove();
+      const gpu = state.gpu;
+      if (!gpu) return;
+      releaseDataStores(gpu, state.owner);
+      gpu.release(state.owner);
+      if (state.ownsDevice) gpu.destroy();
     }
   });
 }
+function renderOwner(world) {
+  return world.resource(RenderOptions).owner;
+}
 function captureView(world, view = WINDOW_VIEW) {
-  return world.resource(Graph).capture(view);
+  const shot = world.resource(Graph).capture(view);
+  world.wake();
+  return shot;
 }
 async function captureBuffer(world, view, buffer) {
   const graph = world.resource(Graph);
-  const result = await graph.capture(view, buffer);
+  const pending = graph.capture(view, buffer);
+  world.wake();
+  const result = await pending;
   if (!("format" in result)) {
     const data = new Float32Array(result.data.length);
     for (let i = 0; i < data.length; i++) data[i] = result.data[i] / 255;
@@ -159,7 +309,23 @@ function describeRender(world) {
     stats: Object.fromEntries(world.tryResource(RenderStats) ?? []),
     counters: { ...world.tryResource(RenderCounters) ?? { taaResets: 0, originShifts: 0 } },
     memory: world.tryResource(GpuMemory) ?? { textures: 0, textureBytes: 0 },
-    recentErrors: gpu.errors.slice(-5).map((e) => e.toJSON())
+    recentErrors: gpu.errors.slice(-5).map((e) => e.toJSON()),
+    features: describeFeatures(world),
+    health: world.tryResource(RenderHealth) ?? { state: "ok", issues: [] },
+    // The API and tier the device runs (0064), what it can do, and why a better option was skipped.
+    backend: gpu.backend,
+    tier: gpu.tier,
+    capabilities: gpu.capabilities,
+    // WebGL2: where shader translations came from, and what naga translated this session.
+    shaderCache: gpu.shaderCache(),
+    limits: {
+      maxTextureDimension2D: gpu.device.limits.maxTextureDimension2D,
+      maxColorAttachments: gpu.device.limits.maxColorAttachments,
+      maxSampledTexturesPerShaderStage: gpu.device.limits.maxSampledTexturesPerShaderStage,
+      maxInterStageShaderVariables: gpu.device.limits.maxInterStageShaderVariables,
+      maxUniformBufferBindingSize: gpu.device.limits.maxUniformBufferBindingSize
+    },
+    reasons: gpu.reasons
   };
   const sections = {};
   for (const [name, fn] of world.tryResource(RenderDescribers) ?? []) sections[name] = fn(world);
@@ -178,5 +344,6 @@ export {
   captureBuffer,
   captureView,
   describeRender,
+  renderOwner,
   renderPlugin
 };

package/dist/post-common.d.ts

@@ -11,6 +11,8 @@ export declare const tex: (binding: number, sampleType?: GPUTextureSampleType) =
         sampleType: GPUTextureSampleType;
     };
 };
+/** Depth read without comparison, in the fragment stage (a float texture on baseline, 0064). */
+export declare const depthTex: (gpu: GpuContext, binding: number) => GPUBindGroupLayoutEntry;
 export declare const uniform: (binding: number, visibility?: number) => {
     binding: number;
     visibility: number;

package/dist/post-common.js

@@ -1,6 +1,7 @@
 import { GpuBuffer } from "@aethervtt/shard-gpu";
 import { ForwardStateResource } from "./forward.js";
 import { Shaders } from "./plugin.js";
+import { depthReadEntry } from "./tier.js";
 import { cameraOf } from "./view.js";
 const textureIds = /* @__PURE__ */ new WeakMap();
 let nextId = 1;
@@ -18,6 +19,7 @@ const tex = (binding, sampleType = "float") => ({
   visibility: F(),
   texture: { sampleType }
 });
+const depthTex = (gpu, binding) => depthReadEntry(gpu, binding, F());
 const uniform = (binding, visibility = F()) => ({
   binding,
   visibility,
@@ -139,6 +141,7 @@ export {
   HDR,
   PostCache,
   beginPass,
+  depthTex,
   forwardView,
   idOf,
   sampler,