@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/projection.js

@@ -0,0 +1,87 @@
+import { mat4 } from "@aethervtt/shard-core";
+import { Cameras } from "./view.js";
+const scratchInv = mat4.create();
+const scratchKey = mat4.create();
+let invValid = false;
+function inverse(viewProj) {
+  let same = invValid;
+  for (let i = 0; same && i < 16; i++) if (scratchKey[i] !== viewProj[i]) same = false;
+  if (!same) {
+    mat4.copy(scratchKey, viewProj);
+    invValid = mat4.invert(scratchInv, viewProj) !== null;
+  }
+  return scratchInv;
+}
+function worldToScreen(world, camera, point, out) {
+  const cam = world.tryResource(Cameras)?.get(camera);
+  if (!cam) return false;
+  const m = cam.viewProjNoJitter;
+  const x = point[0];
+  const y = point[1];
+  const z = point[2];
+  const cx = m[0] * x + m[4] * y + m[8] * z + m[12];
+  const cy = m[1] * x + m[5] * y + m[9] * z + m[13];
+  const cw = m[3] * x + m[7] * y + m[11] * z + m[15];
+  if (cw <= 1e-9) return false;
+  const width = cam.displayWidth / cam.pixelRatio;
+  const height = cam.displayHeight / cam.pixelRatio;
+  out[0] = (cx / cw * 0.5 + 0.5) * width;
+  out[1] = (0.5 - cy / cw * 0.5) * height;
+  return true;
+}
+function screenToRay(world, camera, x, y, outOrigin, outDir) {
+  const cam = world.tryResource(Cameras)?.get(camera);
+  if (!cam) {
+    outOrigin[0] = outOrigin[1] = outOrigin[2] = 0;
+    outDir[0] = outDir[1] = 0;
+    outDir[2] = -1;
+    return;
+  }
+  const inv = inverse(cam.viewProjNoJitter);
+  const nx = x / (cam.displayWidth / cam.pixelRatio) * 2 - 1;
+  const ny = 1 - y / (cam.displayHeight / cam.pixelRatio) * 2;
+  let px = 0;
+  let py = 0;
+  let pz = 0;
+  for (let k = 0; k < 2; k++) {
+    const d = k === 0 ? 1 : 0.5;
+    const wx = inv[0] * nx + inv[4] * ny + inv[8] * d + inv[12];
+    const wy = inv[1] * nx + inv[5] * ny + inv[9] * d + inv[13];
+    const wz = inv[2] * nx + inv[6] * ny + inv[10] * d + inv[14];
+    const ww = inv[3] * nx + inv[7] * ny + inv[11] * d + inv[15];
+    if (k === 0) {
+      px = wx / ww;
+      py = wy / ww;
+      pz = wz / ww;
+    } else {
+      const dx = wx / ww - px;
+      const dy = wy / ww - py;
+      const dz = wz / ww - pz;
+      const len = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1;
+      outDir[0] = dx / len;
+      outDir[1] = dy / len;
+      outDir[2] = dz / len;
+    }
+  }
+  outOrigin[0] = px;
+  outOrigin[1] = py;
+  outOrigin[2] = pz;
+}
+const rayOrigin = new Float64Array(3);
+const rayDir = new Float64Array(3);
+function screenToPlane(world, camera, x, y, planeY, out) {
+  screenToRay(world, camera, x, y, rayOrigin, rayDir);
+  const dy = rayDir[1];
+  if (Math.abs(dy) < 1e-9) return false;
+  const t = (planeY - rayOrigin[1]) / dy;
+  if (t < 0) return false;
+  out[0] = rayOrigin[0] + rayDir[0] * t;
+  out[1] = planeY;
+  out[2] = rayOrigin[2] + rayDir[2] * t;
+  return true;
+}
+export {
+  screenToPlane,
+  screenToRay,
+  worldToScreen
+};

package/dist/readback.d.ts

@@ -1,4 +1,5 @@
 /** Readback helpers: bytes per texel and conversion of any readable format to floats. */
 export declare const BYTES_PER_TEXEL: Partial<Record<GPUTextureFormat, number>>;
+export declare function halfToFloat(h: number): number;
 /** Unpacks a readback row of any supported format into 4 floats per pixel. */
 export declare function toFloats(src: ArrayBuffer, format: GPUTextureFormat, count: number, out: Float32Array, o: number): void;

package/dist/readback.js

@@ -91,5 +91,6 @@ function small(v, mantissaBits) {
 }
 export {
   BYTES_PER_TEXEL,
+  halfToFloat,
   toFloats
 };

package/dist/render-scale.js

@@ -2,6 +2,7 @@ import { defineResource } from "@aethervtt/shard-core";
 import { DisplayRate } from "@aethervtt/shard-runtime";
 import { Views } from "./plugin.js";
 const RenderScale = defineResource("render/RenderScale", {
+  hostWritable: true,
   description: "Render resolution of window cameras (0051): the scene renders at scale \xD7 the window size and is upscaled, UI stays native. auto moves the scale between min and max to hold the frame budget: targetMs, or one display refresh (DisplayRate) when it is 0.",
   init: () => ({
     mode: "auto",

package/dist/ribbons-plugin.d.ts

@@ -0,0 +1,5 @@
+import { VfxRenderer } from './vfx-draw.js';
+export declare const RibbonGpu: import("@aethervtt/shard-core").ResourceDef<{
+    renderer?: VfxRenderer;
+}>;
+export declare const ribbonsPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/ribbons-plugin.js

@@ -0,0 +1,59 @@
+import { defineResource, defineSystem, Last, PostUpdate } from "@aethervtt/shard-core";
+import { definePlugin, FrameDemand } from "@aethervtt/shard-runtime";
+import { OriginShift, TransformSystems } from "@aethervtt/shard-transform";
+import { addRenderFeatures } from "./features.js";
+import { Graph, RenderDescribers, RenderSet, Shaders } from "./plugin.js";
+import { describeRibbons, Ribbons, shiftRibbons, updateRibbons } from "./ribbons.js";
+import { registerShaders } from "./shaders.js";
+import { RibbonsPath } from "./vfx.js";
+import { VFX_SHADERS, VfxRenderer } from "./vfx-draw.js";
+import { computeVisibility } from "./visibility.js";
+const RibbonGpu = defineResource("render/RibbonGpu", {
+  init: () => ({})
+});
+const prune = defineSystem({
+  name: "render/ribbons-prune",
+  run: (_, world) => world.resource(RibbonGpu).renderer?.prune(world)
+});
+const ribbonsPlugin = definePlugin({
+  name: "render/ribbons",
+  dependencies: ["render/forward"],
+  provides: [Ribbons, RibbonGpu, updateRibbons],
+  build(app) {
+    const w = app.world;
+    w.initResource(RibbonsPath);
+    w.initResource(Ribbons);
+    w.initResource(RibbonGpu);
+    w.observe(
+      OriginShift,
+      ({ data }) => shiftRibbons(w, data.offset[0], data.offset[1], data.offset[2])
+    );
+    app.addSystems(PostUpdate, updateRibbons.after(TransformSystems, computeVisibility));
+    app.addSystems(Last, prune.inSet(RenderSet.Prepare));
+  },
+  ready(app) {
+    const w = app.world, renderer = new VfxRenderer(w.resource(Ribbons).records, false);
+    w.resource(RibbonGpu).renderer = renderer;
+    registerShaders(w.resource(Shaders), VFX_SHADERS);
+    addRenderFeatures(w, {
+      name: "render/ribbons",
+      description: "Bounded trails and beams.",
+      nodes: ["ribbons"],
+      baseline: { strategy: "The same vertex attributes, uniform buffers and fragment passes" }
+    });
+    w.resource(Graph).addNode("ribbons", renderer.node());
+    w.initResource(RenderDescribers).set("ribbons", describeRibbons);
+  },
+  dispose(app) {
+    app.world.resource(RibbonGpu).renderer?.dispose();
+    const s = app.world.resource(Ribbons);
+    s.records.length = 0;
+    s.trails.clear();
+    s.beams.clear();
+    app.world.tryResource(FrameDemand)?.set("render/ribbons", false);
+  }
+});
+export {
+  RibbonGpu,
+  ribbonsPlugin
+};

package/dist/ribbons.d.ts

@@ -0,0 +1,44 @@
+import { type World } from '@aethervtt/shard-core';
+import { type VfxRecord } from './vfx-state.js';
+export interface RibbonRecord extends VfxRecord {
+    points: Float64Array;
+    capacity: number;
+    head: number;
+    pointsCount: number;
+    distance: number;
+    targetMatrix: Float64Array;
+    scratch: Float64Array;
+}
+export declare const Ribbons: import("@aethervtt/shard-core").ResourceDef<{
+    records: RibbonRecord[];
+    trails: Map<number, RibbonRecord>;
+    beams: Map<number, RibbonRecord>;
+    frame: number;
+    rejected: number;
+}>;
+/** Geometry is camera-independent; the vertex shader extrudes shared point tangents per view. */
+export declare function ribbonGeometry(r: RibbonRecord): void;
+export declare const updateRibbons: import("@aethervtt/shard-core").SystemDef<{
+    trails: import("@aethervtt/shard-core").Query;
+    beams: import("@aethervtt/shard-core").Query;
+}>;
+export declare function shiftRibbons(world: World, x: number, y: number, z: number): void;
+export declare function describeRibbons(world: World): {
+    rejected: number;
+    error: string | null;
+    records: {
+        entity: number;
+        kind: "beam" | "decal" | "trail";
+        vertices: number;
+        age: number;
+        opacity: number;
+        error: string | null;
+        visible: boolean;
+        texture: string;
+        playing: boolean;
+        paused: boolean;
+        cpuBytes: number;
+        points: number;
+        capacity: number;
+    }[];
+};

package/dist/ribbons.js

@@ -0,0 +1,288 @@
+import { defineResource, defineSystem } from "@aethervtt/shard-core";
+import { FrameDemand, Time } from "@aethervtt/shard-runtime";
+import { GlobalTransform } from "@aethervtt/shard-transform";
+import { Beam, Trail } from "./vfx.js";
+import {
+  createRecord,
+  matrixChanged,
+  number,
+  point,
+  recordDescription,
+  refreshRecord,
+  VFX_STRIDE
+} from "./vfx-state.js";
+const Ribbons = defineResource("render/Ribbons", {
+  init: () => ({
+    records: [],
+    trails: /* @__PURE__ */ new Map(),
+    beams: /* @__PURE__ */ new Map(),
+    frame: 0,
+    rejected: 0
+  })
+});
+function create(world, entity, beam2) {
+  const capacity = beam2 ? 256 : world.get(entity, Trail).capacity;
+  return {
+    ...createRecord(
+      world,
+      entity,
+      beam2 ? Beam : Trail,
+      beam2 ? "beam" : "trail",
+      (capacity - 1) * 6
+    ),
+    points: new Float64Array(capacity * 5),
+    capacity,
+    head: 0,
+    pointsCount: 0,
+    distance: 0,
+    targetMatrix: new Float64Array(12),
+    scratch: new Float64Array(6)
+  };
+}
+function noise(seed, index) {
+  let x = (seed ^ Math.imul(index + 1, 2654435769)) >>> 0;
+  x = Math.imul(x ^ x >>> 16, 569420461);
+  x = Math.imul(x ^ x >>> 15, 1935289751);
+  return ((x ^ x >>> 15) >>> 0) / 4294967295 * 2 - 1;
+}
+function trail(r, playing, paused) {
+  const life = number(r, "lifetime"), p = r.points;
+  while (r.pointsCount && r.age - p[r.head * 5 + 3] >= life) {
+    r.head = (r.head + 1) % r.capacity;
+    r.pointsCount--;
+  }
+  if (!playing || paused) return;
+  const offset = r.columns.offset, o = r.row * 3;
+  point(r.scratch, 0, r.matrix, offset[o], offset[o + 1], offset[o + 2]);
+  let distance = 0;
+  if (r.pointsCount) {
+    const last = (r.head + r.pointsCount - 1) % r.capacity * 5;
+    const dx = r.scratch[0] - p[last], dy = r.scratch[1] - p[last + 1], dz = r.scratch[2] - p[last + 2];
+    distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+    if (distance < number(r, "minDistance")) return;
+    if (distance > number(r, "breakDistance")) {
+      r.head = 0;
+      r.pointsCount = 0;
+      r.distance = 0;
+      distance = 0;
+    }
+  }
+  if (r.pointsCount === r.capacity) {
+    r.head = (r.head + 1) % r.capacity;
+    r.pointsCount--;
+  }
+  const at = (r.head + r.pointsCount++) % r.capacity * 5;
+  p[at] = r.scratch[0];
+  p[at + 1] = r.scratch[1];
+  p[at + 2] = r.scratch[2];
+  p[at + 3] = r.age;
+  p[at + 4] = r.distance += distance;
+}
+function beam(world, r) {
+  const authored = r.columns.points[r.row];
+  if (authored.length > 256 || authored.length === 1) {
+    r.error = "render/beam-points";
+    r.pointsCount = 0;
+    return;
+  }
+  const p = r.points;
+  r.head = 0;
+  if (authored.length) {
+    r.pointsCount = authored.length;
+    for (let i = 0; i < authored.length; i++) {
+      const v = authored[i];
+      point(p, i * 5, r.matrix, v[0], v[1], v[2]);
+    }
+  } else {
+    const target = number(r, "target"), start = r.columns.start, end = r.columns.end, o = r.row * 3;
+    if (target >= 0 && (!world.isAlive(target) || !world.has(target, GlobalTransform))) {
+      r.error = "render/beam-target";
+      r.pointsCount = 0;
+      return;
+    }
+    const m = target >= 0 ? r.targetMatrix : r.matrix;
+    if (target >= 0) matrixChanged(world, target, m);
+    point(r.scratch, 0, r.matrix, start[o], start[o + 1], start[o + 2]);
+    point(r.scratch, 3, m, end[o], end[o + 1], end[o + 2]);
+    const segments = number(r, "segments"), strength = number(r, "noise"), seed = number(r, "seed");
+    r.pointsCount = segments + 1;
+    for (let i = 0; i <= segments; i++) {
+      const f = i / segments, amplitude = i === 0 || i === segments ? 0 : strength;
+      for (let k = 0; k < 3; k++)
+        p[i * 5 + k] = r.scratch[k] + (r.scratch[k + 3] - r.scratch[k]) * f + noise(seed, i * 3 + k) * amplitude;
+    }
+  }
+  let distance = 0;
+  for (let i = 0; i < r.pointsCount; i++) {
+    if (i) {
+      const dx = p[i * 5] - p[(i - 1) * 5], dy = p[i * 5 + 1] - p[(i - 1) * 5 + 1], dz = p[i * 5 + 2] - p[(i - 1) * 5 + 2];
+      distance += Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    p[i * 5 + 4] = distance;
+  }
+  r.distance = distance;
+}
+function ribbonGeometry(r) {
+  r.count = 0;
+  const curve = r.columns.widthCurve[r.row];
+  if (curve.length > 16) {
+    r.error = "render/ribbon-curve";
+    return;
+  }
+  for (let i = 0; i < curve.length; i++)
+    if (!Number.isFinite(curve[i].at) || !Number.isFinite(curve[i].value) || curve[i].at < 0 || curve[i].at > 1 || curve[i].value < 0 || curve[i].value > 16 || i > 0 && curve[i].at <= curve[i - 1].at) {
+      r.error = "render/ribbon-curve";
+      return;
+    }
+  const p = r.points, out = r.vertices, c = r.columns.color, e = r.columns.endColor;
+  const width = number(r, "width"), repeat = number(r, "repeat"), scroll = number(r, "scroll") * r.age;
+  const life = r.kind === "trail" ? number(r, "lifetime") : 1;
+  for (let segment = 0; segment < r.pointsCount - 1; segment++) {
+    const a = (r.head + segment) % r.capacity * 5, b = (r.head + segment + 1) % r.capacity * 5;
+    const dx = p[b] - p[a], dy = p[b + 1] - p[a + 1], dz = p[b + 2] - p[a + 2];
+    if (dx * dx + dy * dy + dz * dz < 1e-16) continue;
+    for (let v = 0; v < 6; v++) {
+      const next = v === 1 || v === 2 || v === 4, side = v === 2 || v === 4 || v === 5 ? 1 : -1;
+      const index = segment + (next ? 1 : 0), at = next ? b : a;
+      const prev = (r.head + Math.max(0, index - 1)) % r.capacity * 5, after = (r.head + Math.min(r.pointsCount - 1, index + 1)) % r.capacity * 5;
+      const f = Math.min(
+        1,
+        Math.max(
+          0,
+          r.kind === "trail" ? (r.age - p[at + 3]) / life : p[at + 4] / Math.max(r.distance, 1e-9)
+        )
+      );
+      let scale = 1;
+      if (curve.length) {
+        scale = curve[0].value;
+        for (let k = 1; k < curve.length; k++) {
+          const x = curve[k - 1], y = curve[k];
+          if (f >= y.at) scale = y.value;
+          else if (f > x.at) {
+            scale = x.value + (y.value - x.value) * (f - x.at) / (y.at - x.at);
+            break;
+          } else break;
+        }
+      }
+      const o = r.count++ * VFX_STRIDE;
+      out[o] = p[at];
+      out[o + 1] = p[at + 1];
+      out[o + 2] = p[at + 2];
+      out[o + 3] = p[after] - p[prev];
+      out[o + 4] = p[after + 1] - p[prev + 1];
+      out[o + 5] = p[after + 2] - p[prev + 2];
+      out[o + 6] = p[at + 4] / repeat + scroll;
+      out[o + 7] = (side + 1) * 0.5;
+      for (let k = 0; k < 4; k++)
+        out[o + 8 + k] = c[r.row * 4 + k] + (e[r.row * 4 + k] - c[r.row * 4 + k]) * f;
+      out[o + 12] = width * scale * 0.5;
+      out[o + 13] = side;
+    }
+  }
+  r.version++;
+}
+const updateRibbons = defineSystem({
+  name: "render/ribbons-update",
+  setup: (world) => ({
+    trails: world.query({ with: [Trail, GlobalTransform] }),
+    beams: world.query({ with: [Beam, GlobalTransform] })
+  }),
+  run({ trails, beams }, world) {
+    const state = world.resource(Ribbons), delta = world.resource(Time).delta;
+    state.frame++;
+    state.rejected = 0;
+    let demand = false;
+    for (let kind = 0; kind < 2; kind++) {
+      const q = kind ? beams : trails;
+      for (let t = 0; t < q.tables.length; t++) {
+        const table = q.tables[t];
+        for (let row = 0; row < table.count; row++) {
+          const entity = table.entities[row];
+          const limit = kind ? table.column(Beam, "segments")[row] : table.column(Trail, "capacity")[row];
+          if (limit < (kind ? 1 : 2) || limit > (kind ? 255 : 256)) {
+            state.rejected++;
+            continue;
+          }
+          const lookup = kind ? state.beams : state.trails;
+          let r = lookup.get(entity);
+          if (!r) {
+            if (state.records.length >= 256) {
+              state.rejected++;
+              continue;
+            }
+            r = create(world, entity, kind === 1);
+            state.records.push(r);
+            lookup.set(entity, r);
+          }
+          refreshRecord(world, r);
+          matrixChanged(world, entity, r.matrix);
+          r.seen = state.frame;
+          r.error = null;
+          const playing = !!number(r, "playing"), paused = !!number(r, "paused");
+          if (r.kind === "trail" && r.capacity !== number(r, "capacity")) {
+            r.capacity = number(r, "capacity");
+            r.points = new Float64Array(r.capacity * 5);
+            r.vertices = new Float32Array((r.capacity - 1) * 6 * VFX_STRIDE);
+            r.head = 0;
+            r.pointsCount = 0;
+          }
+          if (playing && !r.wasPlaying && r.kind === "beam") r.age = 0;
+          r.wasPlaying = playing;
+          if (!paused) r.age += delta;
+          if (kind) {
+            if (playing && (!paused || r.pointsCount === 0)) beam(world, r);
+            else if (!playing) r.pointsCount = 0;
+            else if (r.columns.points[r.row].length === 0) {
+              const target = number(r, "target");
+              if (target >= 0 && (!world.isAlive(target) || !world.has(target, GlobalTransform))) {
+                r.error = "render/beam-target";
+                r.pointsCount = 0;
+              }
+            }
+          } else trail(r, playing, paused);
+          ribbonGeometry(r);
+          if (!paused && (playing || r.pointsCount > 0)) demand = true;
+        }
+      }
+    }
+    for (let i = state.records.length - 1; i >= 0; i--)
+      if (state.records[i].seen !== state.frame) {
+        const r = state.records[i];
+        (r.kind === "beam" ? state.beams : state.trails).delete(r.entity);
+        state.records.splice(i, 1);
+      }
+    world.tryResource(FrameDemand)?.set("render/ribbons", demand);
+  }
+});
+function shiftRibbons(world, x, y, z) {
+  const records = world.resource(Ribbons).records;
+  for (let i = 0; i < records.length; i++) {
+    const r = records[i];
+    for (let j = 0; j < r.pointsCount; j++) {
+      const at = (r.head + j) % r.capacity * 5;
+      r.points[at] = r.points[at] + x;
+      r.points[at + 1] = r.points[at + 1] + y;
+      r.points[at + 2] = r.points[at + 2] + z;
+    }
+  }
+}
+function describeRibbons(world) {
+  const s = world.resource(Ribbons);
+  return {
+    rejected: s.rejected,
+    error: s.rejected ? "render/ribbon-limit" : null,
+    records: s.records.map((r) => ({
+      ...recordDescription(r),
+      cpuBytes: r.vertices.byteLength + r.points.byteLength + r.matrix.byteLength + r.targetMatrix.byteLength + r.scratch.byteLength,
+      points: r.pointsCount,
+      capacity: r.capacity
+    }))
+  };
+}
+export {
+  Ribbons,
+  describeRibbons,
+  ribbonGeometry,
+  shiftRibbons,
+  updateRibbons
+};

package/dist/scenario.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Scenario tests (0075), a test helper exported from `@aethervtt/shard-render/testing`: a fixture's
+ * camera path runs through a 0074 capture, and each slice of the scenario (`bench/perf/budgets.json`)
+ * is read from it with the covers rule (`Capture.spanTime`), so tests, `shard profile` and the
+ * `perf` overlay measure the same thing. On a machine whose GPU passes overlap (machines.json's
+ * `passTiming: "ablation"`), GPU slices are measured by ablation under `pnpm bench` instead.
+ */
+import { type World } from '@aethervtt/shard-core';
+import type { Capture, CaptureSummary } from '@aethervtt/shard-core/capture';
+import { type Track } from '@aethervtt/shard-core/test-env';
+import type { expect as vitestExpect } from 'vitest';
+export interface ScenarioSlice {
+    key: string;
+    track: Track;
+    /** Spans that ran in the capture and that the key covers. */
+    covers: string[];
+    /** Time the key covered in each captured frame (ms). */
+    perFrame: Float64Array;
+    /** The p95 of it: frames whose GPU timings landed, for a GPU slice. Ablation's cost instead. */
+    p95: number;
+    measuredBy: 'capture' | 'ablation';
+    /**
+     * Ablation only: half the range of the cost over rounds, in ms. A pass's cost is the difference
+     * of two frame times that vary by milliseconds, so a sub-millisecond pass can't be resolved
+     * below this; the budget check allows it.
+     */
+    noise?: number;
+}
+export interface ScenarioRun {
+    name: string;
+    summary: CaptureSummary;
+    capture: Capture;
+    /** Every span that ran during the capture, by name. */
+    spans: string[];
+    /** Each frame's CPU time (`frame`) and GPU time (`gpu:frame`; 0 where none landed). */
+    frame: {
+        cpu: Float64Array;
+        gpu: Float64Array;
+        cpuP95: number;
+        gpuP95: number;
+    };
+    /** Whether GPU passes were timed (the device has `timestamp-query`). */
+    gpuTimed: boolean;
+    slices: ScenarioSlice[];
+}
+export interface ScenarioOptions {
+    /** Frames along the camera path, each run through the capture. */
+    frames: number;
+    /** Puts the camera at path frame `i`, runs one app frame, and waits for the GPU. */
+    step: (i: number) => void | Promise<void>;
+    /** Ablation under `pnpm bench` on a machine that needs it: frames per measurement, rounds. */
+    ablation?: {
+        frames?: number;
+        rounds?: number; /** Ablate whatever the machine (tests of this helper). */
+        force?: boolean;
+    };
+}
+/**
+ * Runs a scenario's camera path through a capture and measures its frame and slices (0075). The
+ * slices are the scenario's keys in budgets.json, `headroom` aside.
+ */
+export declare function measureScenario(world: World, name: string, options: ScenarioOptions): Promise<ScenarioRun>;
+/**
+ * The checks of a scenario test. In `pnpm test`: the capture ran every frame, and every slice key
+ * covers at least one span that ran (GPU ones where the device times passes). Under `pnpm bench`:
+ * p95 of the frame and of each slice against the scenario's budgets, soft, so every one is
+ * recorded for `bench/perf/report.json`. A slice measured by ablation fails only when it's over by
+ * more than its noise: what's checked (and reported) is its cost minus the noise.
+ */
+export declare function expectScenario(run: ScenarioRun, expect: typeof vitestExpect): void;