@threenative/core 0.3.1 → 0.3.3

package/dist/playtest.d.ts

@@ -1,10 +1,10 @@
 import { JsonValue, JsonPrimitive } from '@threenative/playtest/protocol';
-import { b as IGamePluginHooks } from './game-XGrTzapq.js';
-import './assets-kyoF7JlJ.js';
+import { b as IGamePluginHooks } from './game-D_6r-k4Y.js';
+import './assets-CYKk2WTu.js';
 import 'three';
-import './renderer-C6hqZpoG.js';
+import './renderer-Cy4qeBOA.js';
 import 'three/webgpu';
-import './canvas-layer-BLVijiUJ.js';
+import './canvas-layer-C1SnMoJ-.js';
 import 'zustand/vanilla';
 
 /**

package/dist/playtest.js

@@ -1,27 +1,48 @@
 import { assertJsonSafe, PLAYTEST_PROTOCOL_LIMITS } from '@threenative/playtest/protocol';
 import { installThreePlaytestBridge } from '@threenative/playtest/three';
-import { Object3D } from 'three';
+import { Sphere, Vector3, Object3D } from 'three';
 
 // src/playtest.ts
-var buses = /* @__PURE__ */ new Set();
+var AUDIO_STATE = /* @__PURE__ */ Symbol.for("threenative.audio.runtime");
+function audioState() {
+  const host = globalThis;
+  const existing = host[AUDIO_STATE];
+  if (existing !== void 0) return existing;
+  const created = { buses: /* @__PURE__ */ new Set(), cueCounts: /* @__PURE__ */ new Map(), cueLog: [] };
+  host[AUDIO_STATE] = created;
+  return created;
+}
 function audioRuntimeSnapshot() {
   let queued = 0;
   let voices = 0;
   let pooled = 0;
   let paused = 0;
   const unsupported = /* @__PURE__ */ new Set();
-  for (const bus of buses) {
+  const state = audioState();
+  for (const bus of state.buses) {
     queued += bus.queued;
     voices += bus.voices;
     pooled += bus.pooled;
     paused += bus.pausedVoices;
     for (const option of bus.unsupported) unsupported.add(option);
   }
-  return { paused, pooled, queued, unsupported: [...unsupported].sort(), voices };
+  return {
+    cues: Object.fromEntries(state.cueCounts),
+    paused,
+    pooled,
+    queued,
+    recentCues: state.cueLog.map((entry) => ({ ...entry })),
+    unsupported: [...unsupported].sort(),
+    voices
+  };
 }
+var GEOMETRY_CAPTURE_CAPABILITY = "runtime.geometry";
+new Sphere();
+new Vector3();
+new Vector3();
 
 // src/version.ts
-var CORE_VERSION = "0.3.1";
+var CORE_VERSION = "0.3.3";
 
 // src/pipeline-census.ts
 var PIPELINE_CENSUS_CAPABILITY = "runtime.pipelineCensus";
@@ -53,6 +74,7 @@ function playtest(options = {}) {
   let attached;
   let startSceneEntered;
   let disposePipelineCensus;
+  let disposeGeometryCapture;
   let contactHistory = [];
   const watcher = createTransitionWatcher();
   let readTick;
@@ -122,14 +144,24 @@ function playtest(options = {}) {
           sample: () => ({ pipelineCensus: pipelineCensus() })
         });
       }
+      const geometryCapture = runtime?.geometryCapture;
+      if (runtime !== void 0 && geometryCapture !== void 0) {
+        disposeGeometryCapture = runtime.observations.contribute({
+          capabilities: [GEOMETRY_CAPTURE_CAPABILITY],
+          // Nothing is armed, walked or hooked unless this request asked for a capture: the
+          // capability says the runtime can answer, not that every sample pays for one.
+          sample: async (request) => request.geometry === void 0 ? {} : { geometry: await geometryCapture(request.geometry) }
+        });
+      }
       installRuntimeChannels(installation.bridge, runtime);
-      if (globalThis[PLAYTEST_RUNNER_EXPECTED_GLOBAL] === true)
-        runtime?.enableRuntimeDiagnostics?.();
+      if (runnerAnnounced()) runtime?.enableRuntimeDiagnostics?.();
       dispose = installation.dispose;
       attached = holdUntilAttached(installation.bridge, options, () => startSceneEntered);
       const cleanup = () => {
         disposePipelineCensus?.();
         disposePipelineCensus = void 0;
+        disposeGeometryCapture?.();
+        disposeGeometryCapture = void 0;
         dispose?.();
         dispose = void 0;
         attached = void 0;
@@ -157,6 +189,9 @@ var PLAYTEST_ATTACH_TIMEOUT_MS = 3e4;
 var PLAYTEST_RUNNER_EXPECTED_GLOBAL = "__THREENATIVE_PLAYTEST_RUNNER_EXPECTED__";
 function shouldHoldUntilAttached(options) {
   if (options.holdUntilAttached !== void 0) return options.holdUntilAttached;
+  return runnerAnnounced();
+}
+function runnerAnnounced() {
   const host = globalThis;
   return host[PLAYTEST_RUNNER_EXPECTED_GLOBAL] === true || host.TN_PLAYTEST_ENDPOINT !== void 0;
 }
@@ -227,10 +262,10 @@ function addRuntimeCapabilities(description, contributions) {
   }
   return { ...description, capabilities };
 }
-function addRuntimeObservations(snapshot, request, contributions) {
+async function addRuntimeObservations(snapshot, request, contributions) {
   const result = { ...snapshot };
   for (const contribution of contributions) {
-    const slice = contribution.sample(request);
+    const slice = await contribution.sample(request);
     if (typeof slice !== "object" || slice === null || Array.isArray(slice)) {
       throw new TypeError("A runtime observation contribution must return a top-level object.");
     }

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import { ReactNode } from 'react';
-import { C as CanvasLayer } from './canvas-layer-BLVijiUJ.js';
+import { C as CanvasLayer } from './canvas-layer-C1SnMoJ-.js';
 import 'three';
-import './renderer-C6hqZpoG.js';
+import './renderer-Cy4qeBOA.js';
 import 'three/webgpu';
 
 /**

package/dist/{renderer-C6hqZpoG.d.ts → renderer-Cy4qeBOA.d.ts}

@@ -1,6 +1,90 @@
 import { Object3D, Matrix4, Camera } from 'three';
 import { MRTNode, Node } from 'three/webgpu';
 
+/**
+ * Host-boundary counters, default-off, on the frame budget's own record.
+ *
+ * Two of the three hypotheses about the render phase's unattributed time are about crossings and
+ * bytes — "the V8↔host boundary dominates" and "a buffer write per object per pass dominates" —
+ * and neither can be answered by a JS CPU profile, because the time is spent on the other side of a
+ * call the profiler attributes to a single frame. This counts the calls instead.
+ *
+ * What it counts, precisely, because a counter that overstates itself is worse than none:
+ *
+ *  - `hostCalls` — every WebGPU method invoked on the device's command encoders and on its queue.
+ *    On a native host each of those is one crossing; in a browser it is one API call. It is not
+ *    every crossing a frame makes: `mapAsync`, `getCurrentTexture` and the presentation path are
+ *    issued by three and by the host outside these objects, and they are named here rather than
+ *    folded in so the number can be checked against a host that counts its own.
+ *  - `gpuBytes` — the byte count handed to `queue.writeBuffer`, exactly. Texture uploads are not
+ *    included: a `writeTexture` size is a function of the destination's format, and estimating it
+ *    from `data.byteLength` would be a number nobody could reconcile.
+ *  - `jsAllocBytes` — the change in `performance.memory.usedJSHeapSize`, where the platform has it.
+ *    Absent on a host without `performance.memory`, never zero: an unmeasurable allocation rate and
+ *    a frame that allocated nothing are different facts.
+ *
+ * Wrapping every method of a command encoder is not free — it is one extra JS call per command, and
+ * this is why the counters ride the same opt-in flag as the spans rather than being always on.
+ */
+/** One frame's boundary counts. Every field is absent when the platform cannot report it. */
+interface IFrameCounters {
+    readonly gpuBytes?: number;
+    readonly hostCalls?: number;
+    readonly jsAllocBytes?: number;
+}
+/** The slice of a WebGPU device this reads. Structural, so a test can stand in a fake. */
+interface ICounterDevice {
+    createCommandEncoder?(): unknown;
+    createRenderBundleEncoder?(): unknown;
+    queue?: unknown;
+}
+/** The WebGPU device behind a raw three renderer, when the backend exposes one. */
+declare function counterDeviceOf(raw: unknown): unknown;
+/**
+ * Counts the frame's boundary crossings and bytes, and reads what the platform will say about
+ * allocation. Install once per renderer; `read` returns the counts since the previous `read`.
+ */
+declare class FrameCounters {
+    #private;
+    private constructor();
+    /** Installs the counters on a device, or answers `undefined` when it has nothing to count. */
+    static install(device: unknown): FrameCounters | undefined;
+    /** The counts since the previous read. */
+    read(): IFrameCounters;
+    /** Removes every wrapper. A game that disposes its renderer must not leave the counters behind. */
+    uninstall(): void;
+}
+
+/**
+ * Per-pass draw and triangle attribution, on by default, for every platform.
+ *
+ * The frame budget already owned the milliseconds; this owns the submissions. Three's
+ * `renderer.info.reset()` runs once per frame before the world render, and a nested shadow or
+ * reflection `renderer.render(...)` shares that same `info`, so `info.render` reports main plus
+ * every nested pass combined. The aggregate cannot tell a 316-draw shadow lane from a 1,418-draw
+ * colour pass, and every optimisation attempt had to hand-roll the split. This is the split: each
+ * `render()` is one entry on a stack, and its own submissions are the counter delta across its
+ * call minus the deltas of the nested calls it made, so the innermost active render call owns
+ * exactly what it submitted.
+ *
+ * Three names its own shadow pass by temporarily renaming the scene to `Shadow Map [ ... ]`
+ * (`renderShadow`), and a reflection pass names its scene with `Reflector` in it. Those are
+ * borrowed, not invented: the classifier reads three's vocabulary and falls back to `nested`.
+ *
+ * Measurement, not policy: installing this alters no draw. `install` answers `undefined` on a
+ * renderer whose `info.render` cannot be read, and a consumer must then report the pass split as
+ * absent rather than zero.
+ */
+/** The named kinds of a render pass. Closed on purpose: a consumer bounds a known kind. */
+declare const FRAME_PASS_KINDS: readonly ["main", "shadow", "reflection", "nested"];
+type FramePassKind = (typeof FRAME_PASS_KINDS)[number];
+/** One render call's own submissions, attributed to its innermost active render call. */
+interface IRenderPassSample {
+    readonly draws: number;
+    readonly kind: FramePassKind;
+    readonly triangles: number;
+}
+
 /**
  * Per-presented-frame cost attribution, on by default, for every platform.
  *
@@ -23,6 +107,7 @@ import { MRTNode, Node } from 'three/webgpu';
  * and a phase that was never measured reports zero samples so a consumer asserting on it fails
  * instead of skipping.
  */
+
 /** Marker printed once per report window. */
 declare const FRAME_BUDGET_MARKER = "TN_FRAME_BUDGET";
 /** Marker printed the moment a gap between presented frames exceeds `hitchMs`. */
@@ -30,9 +115,14 @@ declare const FRAME_HITCH_MARKER = "TN_FRAME_HITCH";
 /**
  * The named parts of one presented frame. They partition the frame: `hostGap` is the time before
  * the callback (present wait plus whatever the host did between callbacks), and `update`,
- * `render`, `overlay` and `residual` sum to the callback's own duration.
+ * `render`, `overlay`, `ui` and `residual` sum to the callback's own duration.
+ *
+ * `overlay` and `ui` are two different draws that happen to sit next to each other. `overlay` is
+ * the three.js HUD pass; `ui` is the native UI layer's composite of the page's pixels into the
+ * game's own frame — one upload and one quad — which is why it is a phase of its own and not part
+ * of `overlay`.
  */
-declare const FRAME_BUDGET_PHASES: readonly ["hostGap", "update", "render", "overlay", "residual"];
+declare const FRAME_BUDGET_PHASES: readonly ["hostGap", "update", "render", "overlay", "ui", "residual"];
 type FrameBudgetPhase = (typeof FRAME_BUDGET_PHASES)[number];
 /** One frame's cost, split by phase. Every field is milliseconds. */
 interface IFramePhaseSample {
@@ -40,6 +130,7 @@ interface IFramePhaseSample {
     readonly update: number;
     readonly render: number;
     readonly overlay: number;
+    readonly ui: number;
     readonly residual: number;
 }
 /**
@@ -82,16 +173,58 @@ interface IFrameBudgetSummary {
     readonly p99: number;
     readonly max: number;
 }
+/**
+ * One render-pass kind's submissions across a window, so a change that trades triangles for CPU is
+ * visible in the same report as the milliseconds it traded for.
+ */
+interface IFrameBudgetPassSummary {
+    readonly draws: IFrameBudgetSummary;
+    /** Frames in the window that submitted a pass of this kind. */
+    readonly frames: number;
+    readonly triangles: IFrameBudgetSummary;
+}
+/**
+ * One reported window of the frame meter.
+ *
+ * **The cadence here is the loop's, not necessarily the display's.** `endFrame` is called once per
+ * frame the game's loop runs, and on the web that is one `requestAnimationFrame` per vblank, so the
+ * interval is a presented frame's. On a native host the loop's dispatch is what drives it — the host
+ * says so itself: "the JavaScript budget reads the same interval as presentedDelta"
+ * (`runtime-native/src/runtime.cpp`, `executeAnimationFrameCallbacks`). Its presentation cap paces
+ * the **present**, never the loop, so a loop that outruns 60 Hz iterates many times per present and
+ * this window's `fps` is inflated by exactly that ratio. Measured on midway's native launch:
+ * `fps 2631.58` beside the host's own `TN_PRESENTS_TICK:{"frames":1740,"presents":133,"capHz":60}`.
+ * The display's rate is the host's series; a reader that has both must not print this one as though
+ * it were a player's — `threenative-playtest perf` refuses to (`TN_PERF_VIRTUAL_DISPLAY`).
+ */
 interface IFrameBudgetWindow {
     /** 1 for the first reported window, incrementing thereafter. */
     readonly window: number;
-    /** Presented frames counted in this window, hitches excluded. */
+    /** Loop frames counted in this window, hitches excluded — one per present on the web. */
     readonly frames: number;
     /** Frames excluded from the window because their present gap exceeded `hitchMs`. */
     readonly hitches: number;
-    /** Derived from the mean presented interval: the number a player would read off a counter. */
+    /**
+     * Derived from the mean interval between loop frames. The number a player would read off a
+     * counter only where the loop's cadence is the display's, as it is on the web via rAF.
+     */
     readonly fps: number;
-    /** Interval between presented frames — the honest frame period. */
+    /**
+     * Frames that reached the display in this window, when the host reports them.
+     *
+     * Absent on the web, where rAF *is* the display's cadence and a second number would be the same
+     * one. On a native host the presentation cap lets the loop dispatch many times per present, so
+     * this is the count a player saw and `fps` is not. **Zero is a reading**: a window of loop frames
+     * can be shorter than one present period, and the display genuinely showed nothing in it.
+     */
+    readonly presents?: number;
+    /**
+     * Presents per second over this window's own duration. Absent when the window counted none —
+     * a rate needs at least one present, and a window too short to contain one carries no rate to
+     * assess rather than a zero.
+     */
+    readonly presentedFps?: number;
+    /** Interval between loop frames — the honest frame period where the loop presents every frame. */
     readonly presented: IFrameBudgetSummary;
     /** Duration of the frame callback itself, entry to exit. */
     readonly frame: IFrameBudgetSummary;
@@ -100,6 +233,14 @@ interface IFrameBudgetWindow {
     readonly phases: Readonly<Record<FrameBudgetPhase, IFrameBudgetSummary>>;
     /** Each phase's mean as a fraction of the mean presented interval. */
     readonly shares: Readonly<Record<FrameBudgetPhase, number>>;
+    /**
+     * Draw calls and triangles submitted per render pass, when a pass recorder was installed.
+     *
+     * Absent rather than defaulted: a renderer whose submissions nothing measured and a frame that
+     * submitted nothing are different facts, and a zero would merge them. A kind no frame submitted
+     * is absent; `frames` says how many frames did.
+     */
+    readonly passes?: Readonly<Partial<Record<FramePassKind, IFrameBudgetPassSummary>>>;
     /**
      * The resolution and sampling this window's frames were drawn at, when the loop reported one.
      * Absent rather than defaulted: a consumer asserting on it must fail loudly instead of reading
@@ -107,14 +248,44 @@ interface IFrameBudgetWindow {
      */
     readonly surface?: IFrameSurfaceState;
     /**
-     * GPU milliseconds for a frame in this window, from `timestamp-query`, when the adapter has it.
+     * GPU milliseconds per resolved frame in this window, from `timestamp-query`, summarised like a
+     * phase — mean/p50/p95/p99/max over the frames the device actually reported.
+     *
+     * A single instantaneous `info.render.timestamp` read is lagged by up to `gpuAgeFrames` and
+     * spread 3.5x between consecutive reads of one steady frame, so it is not the frame's GPU cost
+     * and is not what this reports. Absent rather than zero when no frame resolved a reading: an
+     * adapter without timestamps and a frame that genuinely cost no GPU time are different facts,
+     * and a zero would merge them.
+     */
+    readonly gpu?: IFrameBudgetSummary;
+    /**
+     * Frames in the window whose GPU reading had not advanced since the previous frame, or was
+     * absent. `gpu.samples + gpuStale` is the frames the device was asked about; a window where
+     * every frame is stale reports `gpu` absent rather than the last reading looking current.
+     */
+    readonly gpuStale: number;
+    /**
+     * The window mean of `gpu`, when present. The scalar the resolution scaler reads.
      *
-     * Absent rather than zero when there is nothing to report: an adapter without timestamps and a
-     * frame that genuinely cost no GPU time are different facts, and a zero would merge them.
+     * It is the same number as `gpu.mean`; a single field keeps the scaler and the perf report on
+     * one series rather than a second instantaneous read.
      */
     readonly gpuMs?: number;
-    /** Age of the resolved GPU timestamp in Three.js frame IDs; absent means unobservable. */
+    /** Age of the most recent resolved GPU timestamp in Three.js frame IDs; absent means unobservable. */
     readonly gpuAgeFrames?: number;
+    /**
+     * The frame's boundary counts, when something counted them.
+     *
+     * Each series is absent when nothing measured it, and a series present with zero samples is not
+     * possible: an uncounted frame and a frame that crossed the boundary zero times are different
+     * facts, and a fabricated zero merges them. `hostCalls` and `gpuBytes` come from
+     * `FrameCounters`; `jsAllocBytes` needs a platform that publishes `performance.memory`.
+     */
+    readonly counters?: {
+        readonly hostCalls?: IFrameBudgetSummary;
+        readonly gpuBytes?: IFrameBudgetSummary;
+        readonly jsAllocBytes?: IFrameBudgetSummary;
+    };
 }
 interface IFrameBudgetOptions {
     /** Presented frames per report window. Default 300. */
@@ -138,8 +309,14 @@ interface IFrameBudgetOptions {
      * loop, which is the only place that knows both the renderer and the window boundary.
      */
     readonly readSurface?: () => IFrameSurfaceState;
-    /** Reads the last resolved GPU frame time, called once per reported window. */
-    readonly readGpuMs?: () => number | undefined;
+    /**
+     * Frames the display has presented so far, when the platform can say.
+     *
+     * Defaults to the native host's `__tnPresentedCount`, whose presence is the whole signal: the
+     * web has no such seam and needs none. A counter that goes backwards or non-finite is ignored
+     * for the window rather than reported as a negative rate.
+     */
+    readonly readPresentCount?: () => number | undefined;
     /** Reads the successful GPU query frame age, not the age of the last resolve attempt. */
     readonly readGpuAgeFrames?: () => number | undefined;
 }
@@ -147,7 +324,7 @@ interface IFrameBudgetOptions {
  * Accumulates one frame at a time and reports windowed attribution.
  *
  * The caller is the frame loop; the sequence per frame is
- * `beginFrame` → `markSimulationEnd` → (`addRender` / `addOverlay`) → `endFrame`.
+ * `beginFrame` → `markSimulationEnd` → (`addRender` / `addOverlay` / `addUi`) → `endFrame`.
  * Calling them out of order throws rather than producing a plausible-looking split.
  */
 declare class FrameBudget {
@@ -165,6 +342,34 @@ declare class FrameBudget {
     markSimulationEnd(nowMs: number, substeps: number): void;
     addRender(ms: number): void;
     addOverlay(ms: number): void;
+    addUi(ms: number): void;
+    /**
+     * Records one presented frame's GPU duration, from a resolved `timestamp-query`.
+     *
+     * `ms` is `undefined` when the device reported no reading for the frame. `frame` is the
+     * Three.js frame id the duration belongs to — `gpuFrameSample`/`gpuFrameAge` on the renderer.
+     * A reading whose `frame` has not advanced since the previous frame is the previous frame's
+     * resolve still in flight, so it is counted as stale and not pushed again; that repetition was
+     * what made one lagged sample read as the current frame's cost. Without a `frame` a reading is
+     * always taken as fresh, since there is nothing to tell repeats from a genuine re-measurement.
+     *
+     * Once per frame. A window with no reading at all reports `gpu` absent, never a zero.
+     */
+    addGpuMs(ms: number | undefined, frame?: number): void;
+    /**
+     * Records the frame's host-boundary counts, from `FrameCounters` or any other source.
+     *
+     * At most one call per frame; a second replaces the first rather than summing, because the
+     * counter's own reader already returns the frame's totals and summing two reads of one frame
+     * would double it. A field the platform cannot report is left out of the series entirely.
+     */
+    addCounters(counters: IFrameCounters): void;
+    /**
+     * Records the frame's per-pass submissions, from `RenderPassBudget` or any other source. At most
+     * one entry per kind per frame is meaningful; a second of the same kind is summed by the caller.
+     * An unknown kind throws rather than being dropped, the same fail-closed rule as a phase.
+     */
+    addRenderPasses(passes: readonly IRenderPassSample[]): void;
     /**
      * Closes the frame and returns its phase split, or `undefined` when the frame was a hitch and
      * therefore excluded — a 27-second startup stall is not a frame time and must not enter a
@@ -179,6 +384,16 @@ declare class FrameBudget {
     endFrame(nowMs: number, wantSample?: boolean): IFramePhaseSample | undefined;
     /** Reads the window in progress without disturbing it. */
     window(): IFrameBudgetWindow;
+    /**
+     * The render phase of the frame that just closed, or `undefined` when that frame was a hitch and
+     * therefore not counted.
+     *
+     * It exists because the phase split object is optional — `endFrame` builds one only when a
+     * consumer asked for per-frame samples, which shipping games do not — and a reader that needs
+     * the number must not be forced to turn that allocation on to get it. Reading a measurement and
+     * collecting a sample are different requests.
+     */
+    get lastRenderMs(): number | undefined;
 }
 
 /**
@@ -704,6 +919,19 @@ interface IRendererLike {
     gpuFrameMs(): number | undefined;
     /** Age in Three.js frame IDs of the resolved render timestamp; absent when unobservable. */
     gpuFrameAge?(): number | undefined;
+    /**
+     * The last resolved GPU frame's duration and the Three.js frame id it belongs to, or
+     * `undefined` when no resolved reading is available.
+     *
+     * `gpuFrameMs` is that duration alone; the frame id is what tells a reading still in flight
+     * from the current frame's cost, so a caller building a per-frame series never measures one
+     * resolve twice. Optional like `gpuFrameAge`, for stubs that implement only the drawing
+     * contract. `createRenderer` always provides it.
+     */
+    gpuFrameSample?(): {
+        readonly frame: number;
+        readonly ms: number;
+    } | undefined;
     /** Starts a resolve of the GPU timestamps for the frames drawn since the last call. */
     resolveGpuFrame(): void;
     /**
@@ -717,6 +945,11 @@ interface IRendererLike {
      * session because nothing in the measurement could say which one produced it.
      */
     surface(): IFrameSurfaceState;
+    /**
+     * The drawing buffer height on its own, for a caller that wants one number every frame and no
+     * record. Optional so a platform or test double can keep exposing only `surface()`.
+     */
+    surfaceDrawingBufferHeight?(): number;
     dispose(): void;
 }
 interface IRendererPlatformSource {
@@ -736,6 +969,7 @@ interface IRendererOptions {
     /** Requests multisample antialiasing from the renderer. Defaults to true. */
     antialias?: boolean;
     canvas?: HTMLCanvasElement;
+    gpuTimestampFrameInterval?: number;
     preferWebGPU?: boolean;
     /** CSS-pixel multiplier for the drawing buffer. The default is intentional DPR 1. */
     resolutionScale?: number;
@@ -767,4 +1001,4 @@ interface IRendererOptions {
     }>) => unknown;
 }
 
-export { readRenderChainObservation as $, type IVelocityRenderPass as A, PIPELINE_CENSUS_VERSION as B, PipelineCensus as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type PipelineCensusMode as E, FRAME_BUDGET_MARKER as F, type PipelineCensusStatus as G, RENDER_CHAIN_STAGE_ORDER as H, type IRendererLike as I, RENDER_CHAIN_TIERS as J, RenderChain as K, type RenderChainSource as L, type RenderChainStageId as M, type RenderChainStageName as N, type RenderChainTier as O, PIPELINE_CENSUS_CAPABILITY as P, type RenderChainTierRequest as Q, RENDER_CHAIN_MARKER as R, type RenderChainVelocitySource as S, VELOCITY_PREVIOUS_BONE_MATRICES as T, VELOCITY_PREVIOUS_INSTANCE_MATRICES as U, VELOCITY_OUTPUT_NAME as V, VELOCITY_PREVIOUS_WORLD_MATRIX as W, VelocityTracker as X, createPipelineCensus as Y, ensureVelocityOutput as Z, prewarm as _, FRAME_BUDGET_PHASES as a, readRenderChainReport as a0, readVelocityPreviousBoneMatrices as a1, readVelocityPreviousMatrices as a2, readVelocityPreviousWorldMatrix as a3, velocityTexture as a4, withVelocityContext as a5, type IRendererOptions as a6, FRAME_HITCH_MARKER as b, FrameBudget as c, type FrameBudgetPhase as d, type IFrameBudgetOptions as e, type IFrameBudgetSummary as f, type IFrameBudgetWindow as g, type IFramePhaseSample as h, type IPipelineCensus as i, type IPipelineCensusCounts as j, type IPipelineCensusEvent as k, type IPipelineCensusOptions as l, type IPipelineProvenance as m, type IPipelineShaderObservation as n, type IRenderChainApplied as o, type IRenderChainBudgetWindow as p, type IRenderChainDroppedStage as q, type IRenderChainOptions as r, type IRenderChainRenderer as s, type IRenderChainRequest as t, type IRenderChainStage as u, type IRenderChainStageContext as v, type IRenderChainVelocityMeasurement as w, type IRenderChainVelocityReport as x, type IRenderChainVelocityRequest as y, type IRenderChainVelocityResult as z };
+export { VELOCITY_PREVIOUS_INSTANCE_MATRICES as $, type IRenderChainStageContext as A, type IRenderChainVelocityMeasurement as B, type IRenderChainVelocityReport as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type IRenderChainVelocityRequest as E, type FramePassKind as F, type IRenderChainVelocityResult as G, type IRenderPassSample as H, type IRendererLike as I, type IVelocityRenderPass as J, PIPELINE_CENSUS_VERSION as K, PipelineCensus as L, type PipelineCensusMode as M, type PipelineCensusStatus as N, RENDER_CHAIN_STAGE_ORDER as O, PIPELINE_CENSUS_CAPABILITY as P, RENDER_CHAIN_TIERS as Q, RENDER_CHAIN_MARKER as R, RenderChain as S, type RenderChainSource as T, type RenderChainStageId as U, type RenderChainStageName as V, type RenderChainTier as W, type RenderChainTierRequest as X, type RenderChainVelocitySource as Y, VELOCITY_OUTPUT_NAME as Z, VELOCITY_PREVIOUS_BONE_MATRICES as _, type IFrameBudgetWindow as a, VELOCITY_PREVIOUS_WORLD_MATRIX as a0, VelocityTracker as a1, counterDeviceOf as a2, createPipelineCensus as a3, ensureVelocityOutput as a4, prewarm as a5, readRenderChainObservation as a6, readRenderChainReport as a7, readVelocityPreviousBoneMatrices as a8, readVelocityPreviousMatrices as a9, readVelocityPreviousWorldMatrix as aa, velocityTexture as ab, withVelocityContext as ac, type IRendererOptions as ad, FRAME_BUDGET_MARKER as b, FRAME_BUDGET_PHASES as c, FRAME_HITCH_MARKER as d, FrameBudget as e, type FrameBudgetPhase as f, FrameCounters as g, type ICounterDevice as h, type IFrameBudgetOptions as i, type IFrameBudgetPassSummary as j, type IFrameBudgetSummary as k, type IFrameCounters as l, type IFramePhaseSample as m, type IPipelineCensus as n, type IPipelineCensusCounts as o, type IPipelineCensusEvent as p, type IPipelineCensusOptions as q, type IPipelineProvenance as r, type IPipelineShaderObservation as s, type IRenderChainApplied as t, type IRenderChainBudgetWindow as u, type IRenderChainDroppedStage as v, type IRenderChainOptions as w, type IRenderChainRenderer as x, type IRenderChainRequest as y, type IRenderChainStage as z };

package/dist/ui-layer.d.ts

@@ -57,6 +57,13 @@ declare const HIT_REGIONS_MESSAGE = "tn:hit-regions";
 declare const GAME_STATE_MESSAGE = "tn:state";
 /** The message the UI end sends when the player acts on a control. */
 declare const UI_INTENT_MESSAGE = "tn:intent";
+/**
+ * The frame rate the game end publishes when it was launched in dev mode.
+ *
+ * Separate from the state stream because it is not game state: a HUD that showed it would be
+ * showing the engine's own measurement, and a game that never asked for dev mode never sends it.
+ */
+declare const UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
 /**
  * The intent the UI layer sends once, when its tree has rendered and its rectangles are published.
  *
@@ -118,16 +125,15 @@ declare function connectUiBridge(options: IConnectOptions): IUiBridge;
  * the mirror behaves identically on both, because on web the mirror is fed by the same
  * publication through an in-process channel.
  *
- * Publications are **coalesced**: many store writes inside one turn produce one frame. React
- * must never re-render on the game loop, and neither may the bridge carry a frame per tick.
+ * Publications are **coalesced**: many simulation writes produce one state message per rendered
+ * frame. React consumes that snapshot in the UI realm, independently of the game's render work.
  */
 /**
  * The minimum a store must offer to be published.
  *
  * `getPublishedState` is optional and preferred when present: ThreeNative's game store keeps a
- * live `getState()` that moves every tick and a `getPublishedState()` that moves at most ten
- * times a second. The UI wants the throttled one — the live one would put a bridge frame on
- * every tick, which is the thing React must never do.
+ * live `getState()` that moves every tick and a stable `getPublishedState()` snapshot published
+ * once per rendered frame, unless the game selected a slower `stateFlushMs` interval.
  */
 interface IPublishableStore<T> {
     getState(): T;
@@ -162,7 +168,7 @@ interface IPublishOptions {
  * directly would be a second source of truth that only diverges on the platform where the two
  * are actually separate processes.
  * @situation publish game state to a HUD in another realm
- * @situation keep a web and native UI mirror on the same throttled state stream
+ * @situation keep a web and native UI mirror on the same coalesced state stream
  * @example const publisher = publishUiState(bridge, store);
  */
 declare function publishUiState<T>(bridge: IUiBridge, store: IPublishableStore<T>, options?: IPublishOptions): IUiStatePublisher;
@@ -303,4 +309,4 @@ interface IScopeLike extends IEventTargetLike {
  */
 declare function publishHitRegions(options: IRegistryOptions): IHitRegionRegistry;
 
-export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, type IHitRegion, type IHitRegionRegistry, INTERACTIVE_ATTRIBUTE, type IPublishableStore, type IUiBridge, type IUiMessage, type IUiStateMirror, type IUiStatePublisher, UI_BRIDGE_GLOBALS, UI_INTENT_MESSAGE, UI_READY_INTENT, type UiBridgeEnd, type UiBridgeTransport, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
+export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, type IHitRegion, type IHitRegionRegistry, INTERACTIVE_ATTRIBUTE, type IPublishableStore, type IUiBridge, type IUiMessage, type IUiStateMirror, type IUiStatePublisher, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, type UiBridgeEnd, type UiBridgeTransport, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };

package/dist/ui-layer.js

@@ -2,6 +2,7 @@
 var HIT_REGIONS_MESSAGE = "tn:hit-regions";
 var GAME_STATE_MESSAGE = "tn:state";
 var UI_INTENT_MESSAGE = "tn:intent";
+var UI_DEV_METRICS_MESSAGE = "tn:dev-metrics";
 var UI_READY_INTENT = "tn:ready";
 var UI_BRIDGE_GLOBALS = {
   /** UI end, inbound: the host calls this with one JSON string. */
@@ -422,4 +423,4 @@ function isDevelopment() {
   return import.meta.env?.DEV === true;
 }
 
-export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, INTERACTIVE_ATTRIBUTE, UI_BRIDGE_GLOBALS, UI_INTENT_MESSAGE, UI_READY_INTENT, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };
+export { GAME_STATE_MESSAGE, HIT_REGIONS_MESSAGE, INTERACTIVE_ATTRIBUTE, UI_BRIDGE_GLOBALS, UI_DEV_METRICS_MESSAGE, UI_INTENT_MESSAGE, UI_READY_INTENT, connectUiBridge, onUiIntent, publishHitRegions, publishUiState, sendUiIntent, subscribeUiState };

package/dist/world.d.ts

@@ -1,7 +1,7 @@
 import { Object3D, Mesh, LOD, Vector3, Group, BufferGeometry } from 'three';
-import { I as IComputeDriven, a as IGPUReadbackSample } from './gpu-readback-D2iRvoe9.js';
-import { I as IRendererLike } from './renderer-C6hqZpoG.js';
-import { I as IAssetLoader } from './assets-kyoF7JlJ.js';
+import { I as IComputeDriven, a as IGPUReadbackSample } from './gpu-readback-CMklJs6r.js';
+import { I as IRendererLike } from './renderer-Cy4qeBOA.js';
+import { I as IAssetLoader } from './assets-CYKk2WTu.js';
 import 'three/webgpu';
 
 interface IWorldErosionOptions {

package/mcp/blender-server.mjs

@@ -424,7 +424,7 @@ async function runRecipe(name, request, options = {}) {
 
 // src/index.ts
 var SERVER_NAME = "threenative-blender-mcp";
-var SERVER_VERSION = "0.1.1";
+var SERVER_VERSION = "0.1.3";
 var AUTHORING_INSTRUCTIONS = "Call blender_status before anything else: it answers whether this machine can convert models at all, and when it cannot it names the install command rather than failing. Blender is never installed for the user \u2014 ask first, then let them run the command. An .fbx, .blend, .obj or .dae placed in a game's assets directory is converted by the build itself; these tools are for inspecting a source before committing it and for operations the build does not perform. For anything no named tool covers, read a shipped recipe with blender_recipes and adapt it, then run it with blender_run_python.";
 var TOOL_DEFINITIONS = [
   {