@vgai/engine 0.5.7 → 0.5.9

package/dist/dev/render-census.js

@@ -0,0 +1,257 @@
+/**
+ * THE ADDRESS BOOK behind the render vitals (`dev/render-vitals.ts`): which
+ * subtree owns the draw calls, and which meshes are identical enough to
+ * instance. A draw-call count with no address is a symptom you cannot act on.
+ *
+ * Pure functions over a live `THREE.Object3D` — no renderer, no profiler, no
+ * game. They are what the `render.census` / `render.families` debug commands
+ * run; keeping them here (rather than inline in the adapter) is what lets a
+ * headless test build a scene by hand and check the arithmetic.
+ *
+ * ── WHAT "VISIBLE" MEANS HERE, AND WHY IT IS A WALK ─────────────────────────
+ * Visibility in three is HIERARCHICAL: a hidden parent hides its whole
+ * subtree, and `Object3D.traverse` cannot prune. So these walk manually and
+ * stop descending at an invisible node. That is not a detail — `render.toggle`
+ * works by hiding a PARENT, and a census that kept counting the children under
+ * it would report that nothing changed.
+ *
+ * ── TWO FAMILY SCANS, AND WHY BOTH ──────────────────────────────────────────
+ * {@link meshFamilies} keys on object IDENTITY: meshes sharing one geometry
+ * instance and one material instance (`uuid`) — exactly the precondition for
+ * collapsing them into a bare `InstancedMesh` as they stand. It deliberately
+ * does not compare material PARAMETERS.
+ *
+ * {@link structuralBatchScan} keys on STRUCTURE (`render/structural-
+ * signature.ts`): meshes that are the same DRAW, however many distinct
+ * material objects describe it. A project that writes a material per mesh —
+ * which is what inline `<meshStandardMaterial>` in a TSX world does, i.e. what
+ * every fresh scaffold does — reads as all families-of-one under the first
+ * scan and as one big collapsible family under the second. Both readings are
+ * true; they answer different questions, and only the second one routes an
+ * author to the fix (`dev/static-batch-advisor.ts`).
+ *
+ * Nothing here assumes a project interns its materials or that its world is
+ * static — the STATIC half is a claim only the author can make, which is why
+ * the advisory asks rather than acts.
+ */
+import { materialMergeSignature, staticBatchSkipReason } from '../render/structural-signature';
+/** How many rows a census/family report carries. A shortlist is actionable;
+ *  a full dump through a JSON relay is a wall of text nobody reads. */
+export const CENSUS_ROW_LIMIT = 40;
+export const FAMILY_ROW_LIMIT = 30;
+function asMesh(node) {
+    const mesh = node;
+    return mesh.isMesh || mesh.isSkinnedMesh ? mesh : null;
+}
+/** Triangles one mesh submits: its geometry's own count times its instance
+ *  count. Non-indexed geometry falls back to the position attribute; a
+ *  geometry with neither contributes 0 rather than a guess. */
+function triangleCount(mesh) {
+    const geometry = mesh.geometry;
+    if (!geometry)
+        return 0;
+    const index = geometry.getIndex?.() ?? null;
+    const position = geometry.getAttribute?.('position') ?? null;
+    const vertices = index ? index.count : (position?.count ?? 0);
+    const instances = mesh.isInstancedMesh ? (mesh.count ?? 1) : 1;
+    return Math.round(vertices / 3) * instances;
+}
+/** Walk `node` and its visible descendants, calling `visit` for every visible
+ *  mesh. Stops at an invisible node — see the module note. */
+function walkVisibleMeshes(node, visit) {
+    if (!node.visible)
+        return;
+    const mesh = asMesh(node);
+    if (mesh)
+        visit(mesh);
+    for (const child of node.children)
+        walkVisibleMeshes(child, visit);
+}
+const UNNAMED = '(unnamed)';
+/**
+ * Tally visible meshes and triangles per direct child of `root`. Pure.
+ *
+ * One level, deliberately: the report is a set of addresses to drill into
+ * with the same command, and a recursive dump is not something you can act on
+ * one step at a time. `root` itself contributes its own meshes under its own
+ * name when it has any.
+ */
+export function sceneCensus(root, rootLabel = '(scene)') {
+    const rows = new Map();
+    let totalMeshes = 0;
+    let totalTriangles = 0;
+    if (!root.visible) {
+        return { root: rootLabel, totalMeshes: 0, totalTriangles: 0, subtreeCount: 0, subtrees: [] };
+    }
+    const tally = (key, node) => {
+        walkVisibleMeshes(node, (mesh) => {
+            const triangles = triangleCount(mesh);
+            const row = rows.get(key) ?? { meshes: 0, triangles: 0 };
+            row.meshes += 1;
+            row.triangles += triangles;
+            rows.set(key, row);
+            totalMeshes += 1;
+            totalTriangles += triangles;
+        });
+    };
+    // `root`'s own mesh, if it is one, is charged to `root` — not silently
+    // dropped because the grouping key is "direct child".
+    const selfMesh = asMesh(root);
+    if (selfMesh) {
+        const triangles = triangleCount(selfMesh);
+        rows.set(root.name || rootLabel, { meshes: 1, triangles });
+        totalMeshes += 1;
+        totalTriangles += triangles;
+    }
+    for (const child of root.children)
+        tally(child.name || UNNAMED, child);
+    const sorted = [...rows.entries()]
+        .map(([name, row]) => ({ name, meshes: row.meshes, triangles: row.triangles }))
+        .sort((a, b) => b.triangles - a.triangles || b.meshes - a.meshes);
+    return {
+        root: rootLabel,
+        totalMeshes,
+        totalTriangles,
+        subtreeCount: sorted.length,
+        subtrees: sorted.slice(0, CENSUS_ROW_LIMIT),
+    };
+}
+/** First node named `name` in `root`'s subtree, or `null`. Depth-first, so the
+ *  shallowest match under an ordinary hierarchy wins. */
+export function findByName(root, name) {
+    if (root.name === name)
+        return root;
+    for (const child of root.children) {
+        const hit = findByName(child, name);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
+/** Group visible non-instanced meshes by (geometry, material) identity. Pure.
+ *  See the module note for what identity does and does not assume. */
+export function meshFamilies(root) {
+    const families = new Map();
+    let plainMeshes = 0;
+    walkVisibleMeshes(root, (mesh) => {
+        if (mesh.isInstancedMesh)
+            return;
+        const geometry = mesh.geometry;
+        if (!geometry)
+            return;
+        const material = mesh.material;
+        const materialKey = Array.isArray(material)
+            ? material.map((entry) => entry.uuid).join('+')
+            : (material?.uuid ?? 'none');
+        const key = `${geometry.uuid}/${materialKey}`;
+        plainMeshes += 1;
+        const existing = families.get(key);
+        if (existing) {
+            existing.meshes += 1;
+            return;
+        }
+        families.set(key, {
+            meshes: 1,
+            triangles: triangleCount(mesh),
+            example: `${mesh.parent?.name || UNNAMED}/${mesh.name || UNNAMED}`,
+        });
+    });
+    const sorted = [...families.values()].sort((a, b) => b.meshes - a.meshes);
+    const top = sorted.slice(0, FAMILY_ROW_LIMIT);
+    return {
+        plainMeshes,
+        familyCount: sorted.length,
+        top,
+        meshesInTop: top.reduce((total, row) => total + row.meshes, 0),
+    };
+}
+/**
+ * Group visible meshes by STRUCTURAL identity — the same key the batchers use
+ * (`render/structural-signature.ts`), so this measures what `<Frozen>` would
+ * actually do rather than what a uuid comparison can see.
+ *
+ * This is the companion to {@link meshFamilies}, not a replacement, and the
+ * difference between the two is the finding: `meshFamilies` asks "which meshes
+ * SHARE a geometry and material object", which is what a bare `InstancedMesh`
+ * needs; this asks "which meshes are the same draw", which is what a merging
+ * batcher needs. On a freshly scaffolded world writing inline materials the
+ * first reports families of one and the second reports the win — see the uuid
+ * trap in `render/structural-signature.ts`.
+ *
+ * Pure. One walk, plus a tally.
+ */
+export function structuralBatchScan(root) {
+    const families = new Map();
+    const skipped = {};
+    // Which subtree each candidate sits under, kept per mesh so attribution can
+    // wait until the families are known (a family of one is not collapsible, and
+    // charging its member to a subtree would inflate that subtree's row).
+    const members = [];
+    let plainMeshes = 0;
+    /** One node, no recursion. Answers `false` when its subtree must be pruned. */
+    const visit = (node, subtree) => {
+        if (!node.visible)
+            return false;
+        const reason = staticBatchSkipReason(node);
+        if (reason === 'opted-out') {
+            skipped['opted-out'] = (skipped['opted-out'] ?? 0) + 1;
+            return false; // an opt-out covers its whole subtree
+        }
+        if (reason === null) {
+            const mesh = node;
+            const material = mesh.material;
+            const key = `${materialMergeSignature(material)}|${node.castShadow ? 1 : 0}${node.receiveShadow ? 1 : 0}`;
+            plainMeshes += 1;
+            members.push({ key, subtree });
+            const existing = families.get(key);
+            if (existing)
+                existing.meshes += 1;
+            else {
+                families.set(key, {
+                    meshes: 1,
+                    triangles: triangleCount(mesh),
+                    example: `${node.parent?.name || UNNAMED}/${node.name || UNNAMED}`,
+                });
+            }
+        }
+        else if (reason !== 'not-a-mesh') {
+            skipped[reason] = (skipped[reason] ?? 0) + 1;
+        }
+        return true;
+    };
+    const scan = (node, subtree) => {
+        if (!visit(node, subtree))
+            return;
+        for (const child of node.children)
+            scan(child, subtree);
+    };
+    // `root`'s own mesh, if it is one, is charged to `root` — the same rule
+    // `sceneCensus` uses, so the two reports address the same graph.
+    if (visit(root, root.name || UNNAMED)) {
+        for (const child of root.children)
+            scan(child, child.name || UNNAMED);
+    }
+    const collapsibleKeys = new Set([...families.entries()].filter(([, family]) => family.meshes >= 2).map(([key]) => key));
+    const perSubtree = new Map();
+    let collapsible = 0;
+    for (const member of members) {
+        if (!collapsibleKeys.has(member.key))
+            continue;
+        collapsible += 1;
+        perSubtree.set(member.subtree, (perSubtree.get(member.subtree) ?? 0) + 1);
+    }
+    const sorted = [...families.values()].sort((a, b) => b.meshes - a.meshes);
+    const top = sorted.slice(0, FAMILY_ROW_LIMIT);
+    return {
+        plainMeshes,
+        familyCount: sorted.length,
+        top,
+        meshesInTop: top.reduce((total, row) => total + row.meshes, 0),
+        collapsible,
+        skipped,
+        bySubtree: [...perSubtree.entries()]
+            .map(([name, count]) => ({ name, collapsible: count }))
+            .sort((a, b) => b.collapsible - a.collapsible)
+            .slice(0, CENSUS_ROW_LIMIT),
+    };
+}

package/dist/dev/render-vitals.d.ts

@@ -0,0 +1,181 @@
+/**
+ * LIVE RENDER VITALS — the frame explaining its own cost, derived ENTIRELY
+ * from `PerformanceProfiler` frames (`dev/performance-profiler.ts`).
+ *
+ * Nothing in a viewport tells you why it is slow, and a frame-time number on
+ * its own tells you only THAT it is. These readings answer the next question:
+ * where did the milliseconds go, and which subtree owns them
+ * (`dev/render-census.ts` is the address book half).
+ *
+ * ── THE MEASUREMENT SOURCE, STATED ONCE ─────────────────────────────────────
+ * There is no side ledger here. Every number below is folded out of profiler
+ * frames — the timing from phase spans, the counters from `reportRender`. The
+ * CPU submission cost is the profiler phase {@link RENDER_SUBMIT_PHASE}, which
+ * the three adapter brackets around its actual draw; the profiler's phase
+ * bookkeeping is a stack precisely so that bracket can sit INSIDE the frame's
+ * enclosing `render` phase without truncating it.
+ *
+ * ── TWO FRAME FLAVOURS, ONE FOLD ────────────────────────────────────────────
+ * The real runtime runs sim and presentation on different callbacks
+ * (`create-runtime.ts`: `update` → `runFrame({skipRenderPhases})` per fixed
+ * substep, `render` → `runRenderFrame` once per display frame), so a profiler
+ * "frame" is EITHER a sim substep OR a presentation pass. A capture/offline
+ * host drives one `runFrame` that is both. {@link foldProfilerFrame} handles
+ * all three the same way, and never has to know which host it is under:
+ *
+ *  - a frame carrying a {@link RENDER_SUBMIT_PHASE} span IS a presentation —
+ *    that phase only exists when a draw actually happened;
+ *  - sim CPU accumulates across every frame since the last presentation, so
+ *    the substeps a display frame consumed are attributed to it;
+ *  - renderer COUNTERS ride whichever frame `reportRender` landed on (the
+ *    adapter reports from its `endFrame` hook, which the substep pass drives),
+ *    so the latest report wins and the counters describe the last completed
+ *    draw. That is the same one-frame-warm reading `renderer.info` gives any
+ *    caller — three resets it when the next draw starts.
+ *
+ * ── WHY THE WORST FRAME IS NOT AN EMA ───────────────────────────────────────
+ * A decaying average keeps a restart spike on the readout for ~30 s, long
+ * after it stopped being true. The rolling two-window max
+ * ({@link WORST_WINDOW_FRAMES}) holds a hitch for one to two windows and then
+ * genuinely forgets it, so the number always describes recent history.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: the caller of {@link createRenderVitals}, which allocates one state
+ * object and one `profiler.subscribe` registration. SHARER: none — the state
+ * is private to that call. TEARDOWN: the returned `dispose()`, the ONE path
+ * that ends the subscription (`setup-three-root-adapter.ts` calls it from
+ * `disposeGame`).
+ */
+import type { PerformanceFrame, PerformanceProfiler } from './performance-profiler';
+/**
+ * The profiler phase name the three adapter brackets its CPU render
+ * submission with — spelled HERE and nowhere else, so the producer
+ * (`setup-three-root-adapter.ts`) and the consumer ({@link foldProfilerFrame})
+ * cannot drift apart. Dotted, so it reads as a decomposition of the enclosing
+ * `render` phase rather than a ninth peer of `SystemPhase`.
+ */
+export declare const RENDER_SUBMIT_PHASE = "render.submit";
+/**
+ * The phases whose cost is SIMULATION. Deliberately not "everything that is
+ * not render": `preRender` (LOD selection, particle stepping, culling prep) is
+ * neither the simulation nor the submission, so it lands in the hitch's
+ * `other` bucket where an investigation can see it. `render` itself is
+ * excluded because {@link RENDER_SUBMIT_PHASE} nests inside it — summing both
+ * would double-count the draw.
+ */
+export declare const SIM_PHASES: readonly string[];
+/** Display frames per worst-frame window — ~5 s at 60 Hz, so the reported
+ *  worst (the max of the current and previous window) survives 5–10 s. */
+export declare const WORST_WINDOW_FRAMES = 300;
+/** A display frame at or above this is worth decomposing. ~3 dropped frames at
+ *  60 Hz: below it, ordinary jitter would rewrite the reading constantly. */
+export declare const HITCH_THRESHOLD_MS = 50;
+/** Smoothing for the frame-time reading — a readable number, not a blur. */
+export declare const FRAME_TIME_EMA_ALPHA = 0.05;
+/** Smoothing for the render-CPU reading. Faster than frame time: submission
+ *  cost is what a draw-call diet moves, and it should visibly move. */
+export declare const RENDER_CPU_EMA_ALPHA = 0.1;
+/**
+ * A hitch, split into the three buckets that route an investigation. `other`
+ * is the diagnostic payload, not a rounding remainder: when it dominates, the
+ * thief is neither the renderer nor the simulation — it is GC, asset decode,
+ * a layout-thrashing DOM overlay, or the browser itself — and every minute
+ * spent on draw calls would have been wasted.
+ */
+export interface HitchDecomposition {
+    /** The display frame's wall-clock cost. */
+    readonly totalMs: number;
+    /** CPU spent submitting draws ({@link RENDER_SUBMIT_PHASE}). */
+    readonly renderMs: number;
+    /** CPU spent in {@link SIM_PHASES}, summed over the substeps this frame
+     *  consumed. */
+    readonly simMs: number;
+    /** Everything else in the wall clock — see this interface's own note. May be
+     *  negative if a measurement straddles the frame boundary; reported as
+     *  measured rather than clamped to a tidier lie. */
+    readonly otherMs: number;
+    /** The one-line reading: `"NNms = render X + sim Y + other Z"`. */
+    readonly text: string;
+}
+/** Split one display frame's wall clock into render / sim / other. Pure. */
+export declare function decomposeHitch(totalMs: number, renderMs: number, simMs: number): HitchDecomposition;
+/** What `render.vitals` reads. Every field is `null` until the fold has
+ *  actually measured it — a stopped, headless or never-drawn game reports
+ *  emptiness rather than a fabricated `0 ms / 0 draws`. */
+export interface RenderVitalsReading {
+    /** Smoothed wall-clock ms per display frame. */
+    readonly frameTimeMs: number | null;
+    /** Frames per second implied by {@link frameTimeMs}. */
+    readonly fps: number | null;
+    /** Draw calls in the last reported draw. */
+    readonly drawCalls: number | null;
+    /** Triangles in the last reported draw. */
+    readonly triangles: number | null;
+    /** Smoothed CPU ms spent submitting draws — invisible in frame time once
+     *  vsync caps the loop, and exactly what fewer draw calls would improve. */
+    readonly renderCpuMs: number | null;
+    /** Top-level `renderer.render()` submissions the last presentation took. */
+    readonly renderPasses: number | null;
+    /** Worst display frame in the last one-to-two windows. */
+    readonly worstFrameMs: number | null;
+    /** The most recent frame over {@link HITCH_THRESHOLD_MS}, decomposed. */
+    readonly lastHitch: HitchDecomposition | null;
+    /** How many display frames the fold has seen. `0` reads as "nothing has
+     *  presented yet", which is why every reading above is `null`. */
+    readonly presentedFrames: number;
+}
+/** The fold's accumulator. Mutable by design (one allocation for the life of a
+ *  mount, written once per profiler frame); read through
+ *  {@link readRenderVitals}. */
+export interface RenderVitalsState {
+    /** Highest profiler frame id already folded — the dedupe that makes the fold
+     *  safe to drive from `profiler.subscribe`, which also fires for
+     *  enabled/recording changes that publish no new frame. */
+    lastFrameId: number;
+    /** `timestamp` of the last presentation, or `null` before the first (there
+     *  is no interval to measure from one sample). */
+    lastPresentAt: number | null;
+    /** Sim CPU accumulated since the last presentation. */
+    pendingSimMs: number;
+    frameTimeMs: number | null;
+    renderCpuMs: number | null;
+    drawCalls: number | null;
+    triangles: number | null;
+    renderPasses: number | null;
+    /** Running max of the CURRENT worst-frame window. */
+    worstCurrentMs: number;
+    /** The PREVIOUS window's max, kept so the reading does not drop to zero the
+     *  instant a window rolls over. */
+    worstPreviousMs: number;
+    /** Display frames counted into the current window. */
+    worstWindowFrames: number;
+    lastHitch: HitchDecomposition | null;
+    presentedFrames: number;
+}
+export declare function createRenderVitalsState(): RenderVitalsState;
+/**
+ * Fold ONE profiler frame into the accumulator. Pure with respect to time and
+ * randomness — every input is on the frame — which is what makes the whole
+ * derivation testable from synthetic frames with no renderer, no clock and no
+ * game.
+ *
+ * Returns `true` when the frame was a presentation (the readings moved).
+ */
+export declare function foldProfilerFrame(state: RenderVitalsState, frame: PerformanceFrame): boolean;
+/** The provider body — pure over the accumulator. */
+export declare function readRenderVitals(state: RenderVitalsState): RenderVitalsReading;
+/** What {@link createRenderVitals} hands back. */
+export interface RenderVitals {
+    /** The `render.vitals` provider body. */
+    read(): RenderVitalsReading;
+    /** See the module's ownership note — the ONE path that ends the
+     *  subscription. Idempotent. */
+    dispose(): void;
+}
+/**
+ * Attach a fold to a live profiler. `subscribe` fires once per published
+ * frame (and on enabled/recording changes, which the id dedupe absorbs), so
+ * nothing here polls and nothing here owns a timer.
+ */
+export declare function createRenderVitals(profiler: PerformanceProfiler): RenderVitals;
+//# sourceMappingURL=render-vitals.d.ts.map

package/dist/dev/render-vitals.d.ts.map

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

package/dist/dev/render-vitals.js

@@ -0,0 +1,232 @@
+/**
+ * LIVE RENDER VITALS — the frame explaining its own cost, derived ENTIRELY
+ * from `PerformanceProfiler` frames (`dev/performance-profiler.ts`).
+ *
+ * Nothing in a viewport tells you why it is slow, and a frame-time number on
+ * its own tells you only THAT it is. These readings answer the next question:
+ * where did the milliseconds go, and which subtree owns them
+ * (`dev/render-census.ts` is the address book half).
+ *
+ * ── THE MEASUREMENT SOURCE, STATED ONCE ─────────────────────────────────────
+ * There is no side ledger here. Every number below is folded out of profiler
+ * frames — the timing from phase spans, the counters from `reportRender`. The
+ * CPU submission cost is the profiler phase {@link RENDER_SUBMIT_PHASE}, which
+ * the three adapter brackets around its actual draw; the profiler's phase
+ * bookkeeping is a stack precisely so that bracket can sit INSIDE the frame's
+ * enclosing `render` phase without truncating it.
+ *
+ * ── TWO FRAME FLAVOURS, ONE FOLD ────────────────────────────────────────────
+ * The real runtime runs sim and presentation on different callbacks
+ * (`create-runtime.ts`: `update` → `runFrame({skipRenderPhases})` per fixed
+ * substep, `render` → `runRenderFrame` once per display frame), so a profiler
+ * "frame" is EITHER a sim substep OR a presentation pass. A capture/offline
+ * host drives one `runFrame` that is both. {@link foldProfilerFrame} handles
+ * all three the same way, and never has to know which host it is under:
+ *
+ *  - a frame carrying a {@link RENDER_SUBMIT_PHASE} span IS a presentation —
+ *    that phase only exists when a draw actually happened;
+ *  - sim CPU accumulates across every frame since the last presentation, so
+ *    the substeps a display frame consumed are attributed to it;
+ *  - renderer COUNTERS ride whichever frame `reportRender` landed on (the
+ *    adapter reports from its `endFrame` hook, which the substep pass drives),
+ *    so the latest report wins and the counters describe the last completed
+ *    draw. That is the same one-frame-warm reading `renderer.info` gives any
+ *    caller — three resets it when the next draw starts.
+ *
+ * ── WHY THE WORST FRAME IS NOT AN EMA ───────────────────────────────────────
+ * A decaying average keeps a restart spike on the readout for ~30 s, long
+ * after it stopped being true. The rolling two-window max
+ * ({@link WORST_WINDOW_FRAMES}) holds a hitch for one to two windows and then
+ * genuinely forgets it, so the number always describes recent history.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: the caller of {@link createRenderVitals}, which allocates one state
+ * object and one `profiler.subscribe` registration. SHARER: none — the state
+ * is private to that call. TEARDOWN: the returned `dispose()`, the ONE path
+ * that ends the subscription (`setup-three-root-adapter.ts` calls it from
+ * `disposeGame`).
+ */
+/**
+ * The profiler phase name the three adapter brackets its CPU render
+ * submission with — spelled HERE and nowhere else, so the producer
+ * (`setup-three-root-adapter.ts`) and the consumer ({@link foldProfilerFrame})
+ * cannot drift apart. Dotted, so it reads as a decomposition of the enclosing
+ * `render` phase rather than a ninth peer of `SystemPhase`.
+ */
+export const RENDER_SUBMIT_PHASE = 'render.submit';
+/**
+ * The phases whose cost is SIMULATION. Deliberately not "everything that is
+ * not render": `preRender` (LOD selection, particle stepping, culling prep) is
+ * neither the simulation nor the submission, so it lands in the hitch's
+ * `other` bucket where an investigation can see it. `render` itself is
+ * excluded because {@link RENDER_SUBMIT_PHASE} nests inside it — summing both
+ * would double-count the draw.
+ */
+export const SIM_PHASES = [
+    'input',
+    'prePhysics',
+    'physics',
+    'postPhysics',
+    'gameLogic',
+    'animation',
+];
+/** Display frames per worst-frame window — ~5 s at 60 Hz, so the reported
+ *  worst (the max of the current and previous window) survives 5–10 s. */
+export const WORST_WINDOW_FRAMES = 300;
+/** A display frame at or above this is worth decomposing. ~3 dropped frames at
+ *  60 Hz: below it, ordinary jitter would rewrite the reading constantly. */
+export const HITCH_THRESHOLD_MS = 50;
+/** Smoothing for the frame-time reading — a readable number, not a blur. */
+export const FRAME_TIME_EMA_ALPHA = 0.05;
+/** Smoothing for the render-CPU reading. Faster than frame time: submission
+ *  cost is what a draw-call diet moves, and it should visibly move. */
+export const RENDER_CPU_EMA_ALPHA = 0.1;
+/** Split one display frame's wall clock into render / sim / other. Pure. */
+export function decomposeHitch(totalMs, renderMs, simMs) {
+    const otherMs = totalMs - renderMs - simMs;
+    return {
+        totalMs,
+        renderMs,
+        simMs,
+        otherMs,
+        text: `${totalMs.toFixed(0)}ms = render ${renderMs.toFixed(0)} + ` +
+            `sim ${simMs.toFixed(0)} + other ${otherMs.toFixed(0)}`,
+    };
+}
+export function createRenderVitalsState() {
+    return {
+        lastFrameId: 0,
+        lastPresentAt: null,
+        pendingSimMs: 0,
+        frameTimeMs: null,
+        renderCpuMs: null,
+        drawCalls: null,
+        triangles: null,
+        renderPasses: null,
+        worstCurrentMs: 0,
+        worstPreviousMs: 0,
+        worstWindowFrames: 0,
+        lastHitch: null,
+        presentedFrames: 0,
+    };
+}
+/** Sum of one frame's phase timings whose names are in `names`. */
+function sumPhases(frame, names) {
+    let total = 0;
+    for (const timing of frame.phases)
+        if (names.includes(timing.name))
+            total += timing.ms;
+    return total;
+}
+/** This frame's CPU render submission, or `null` when it was not a
+ *  presentation (no draw happened, so no bracket was recorded). */
+function submissionMs(frame) {
+    for (const timing of frame.phases)
+        if (timing.name === RENDER_SUBMIT_PHASE)
+            return timing.ms;
+    return null;
+}
+function ema(previous, sample, alpha) {
+    return previous === null ? sample : previous * (1 - alpha) + sample * alpha;
+}
+/**
+ * Fold ONE profiler frame into the accumulator. Pure with respect to time and
+ * randomness — every input is on the frame — which is what makes the whole
+ * derivation testable from synthetic frames with no renderer, no clock and no
+ * game.
+ *
+ * Returns `true` when the frame was a presentation (the readings moved).
+ */
+export function foldProfilerFrame(state, frame) {
+    // Re-publishes and the ring's own re-reads must not double-count. Frame ids
+    // are monotonic for the profiler's whole life, including across `clear()`.
+    if (frame.id <= state.lastFrameId)
+        return false;
+    state.lastFrameId = frame.id;
+    // Counters ride whichever frame `reportRender` landed on — see the module
+    // note. `renderPasses !== null` is the marker that a reporter spoke at all;
+    // a frame nobody reported on leaves the previous reading standing rather
+    // than blanking it to a zero that would read as "nothing is drawn".
+    if (frame.render.renderPasses !== null) {
+        state.drawCalls = frame.render.drawCalls;
+        state.triangles = frame.render.triangles;
+        state.renderPasses = frame.render.renderPasses;
+    }
+    state.pendingSimMs += sumPhases(frame, SIM_PHASES);
+    const renderMs = submissionMs(frame);
+    if (renderMs === null)
+        return false; // a sim substep: its cost is now pending
+    const simMs = state.pendingSimMs;
+    state.pendingSimMs = 0;
+    state.presentedFrames += 1;
+    state.renderCpuMs = ema(state.renderCpuMs, renderMs, RENDER_CPU_EMA_ALPHA);
+    const previousAt = state.lastPresentAt;
+    state.lastPresentAt = frame.timestamp;
+    // The FIRST presentation has no interval behind it. Everything that needs a
+    // dt (frame time, worst frame, the hitch) waits for the second one; the
+    // alternative is to invent an interval from the profiler's own start, which
+    // would report the mount cost as a frame time forever.
+    if (previousAt === null)
+        return true;
+    const dt = frame.timestamp - previousAt;
+    state.frameTimeMs = ema(state.frameTimeMs, dt, FRAME_TIME_EMA_ALPHA);
+    if (dt > state.worstCurrentMs)
+        state.worstCurrentMs = dt;
+    state.worstWindowFrames += 1;
+    if (state.worstWindowFrames >= WORST_WINDOW_FRAMES) {
+        state.worstPreviousMs = state.worstCurrentMs;
+        state.worstCurrentMs = 0;
+        state.worstWindowFrames = 0;
+    }
+    // Blame the hitch with THIS frame's own measurements: `dt` spans the work
+    // between the two presentations, which is exactly the submission just
+    // measured plus the substeps that ran in between.
+    if (dt >= HITCH_THRESHOLD_MS)
+        state.lastHitch = decomposeHitch(dt, renderMs, simMs);
+    return true;
+}
+function round(value, places) {
+    if (value === null)
+        return null;
+    const factor = 10 ** places;
+    return Math.round(value * factor) / factor;
+}
+/** The provider body — pure over the accumulator. */
+export function readRenderVitals(state) {
+    const frameTimeMs = round(state.frameTimeMs, 2);
+    const worst = Math.max(state.worstCurrentMs, state.worstPreviousMs);
+    return {
+        frameTimeMs,
+        fps: frameTimeMs !== null && frameTimeMs > 0 ? round(1000 / frameTimeMs, 1) : null,
+        drawCalls: state.drawCalls,
+        triangles: state.triangles,
+        renderCpuMs: round(state.renderCpuMs, 2),
+        renderPasses: state.renderPasses,
+        worstFrameMs: state.frameTimeMs === null ? null : round(worst, 2),
+        lastHitch: state.lastHitch,
+        presentedFrames: state.presentedFrames,
+    };
+}
+/**
+ * Attach a fold to a live profiler. `subscribe` fires once per published
+ * frame (and on enabled/recording changes, which the id dedupe absorbs), so
+ * nothing here polls and nothing here owns a timer.
+ */
+export function createRenderVitals(profiler) {
+    const state = createRenderVitalsState();
+    const unsubscribe = profiler.subscribe(() => {
+        const frame = profiler.getSnapshot().frames.at(-1);
+        if (frame)
+            foldProfilerFrame(state, frame);
+    });
+    let disposed = false;
+    return {
+        read: () => readRenderVitals(state),
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            unsubscribe();
+        },
+    };
+}