@threenative/core 0.3.2 → 0.3.4

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

@@ -1,6 +1,162 @@
-import { Object3D, Matrix4, Camera } from 'three';
+import { Object3D, Matrix4, Camera, BufferGeometry } 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;
+}
+
+type PlatformRuntime = "web" | "native";
+type PlatformOS = "android" | "ios" | "linux" | "macos" | "windows" | "unknown";
+type PlatformFormFactor = "mobile" | "desktop" | "unknown";
+interface IPlatformInfo {
+    readonly runtime: PlatformRuntime;
+    readonly os: PlatformOS;
+    readonly formFactor: PlatformFormFactor;
+    readonly maxTouchPoints: number;
+}
+declare function getPlatform(): Readonly<IPlatformInfo>;
+declare function isWeb(): boolean;
+declare function isNative(): boolean;
+declare function isMobile(): boolean;
+declare function isTouchscreenAvailable(): boolean;
+
+/**
+ * One rule for what `display.maxFps` means when a game does not say.
+ *
+ * A template that shipped `maxFps: 60` taught every agent to copy the line, and every 120 Hz
+ * desktop then ran its game at half the panel it was sitting on — a default that is a constant the
+ * author is told to revisit later is a bug, not an option. So the default follows the display,
+ * capped at 120 on desktop and web, and stays 60 on mobile where the ceiling is power and heat
+ * rather than pixels. An explicit number still wins and `0` still removes the ceiling.
+ *
+ * **A browser has no refresh-rate API**, so "follows the display" is a measurement: the median
+ * interval between presented frames over the frame budget's first window is the panel's period,
+ * because on the web one rAF callback is one vblank. A native host says its own rate through the
+ * present counter, which is the only series there that counts displays rather than loop
+ * iterations. Both arrive as `measuredRefreshHz`; until one does, the answer is 60 and says so.
+ */
+
+/** What a game gets before anything has been measured, and all a mobile gets. */
+declare const DEFAULT_TARGET_FPS = 60;
+/** The desktop and web ceiling, whatever the panel runs at. */
+declare const MAX_TARGET_FPS = 120;
+/**
+ * Where a resolved target came from, so a harness can assert the *rule* and not just the number:
+ * `"config"` is the game naming it, `"display"` a measured panel rate, `"mobile-default"` the
+ * mobile power ceiling, and `"fallback"` the 60 held until a measurement exists. An unmeasured 60
+ * is not the display's rate and does not report as one.
+ */
+type TargetFpsSource = "config" | "display" | "fallback" | "mobile-default";
+/** A resolved frame budget: the rate the loop holds, and what decided it. */
+interface ITargetFps {
+    readonly targetFps: number;
+    readonly source: TargetFpsSource;
+}
+/** Whatever holds `display.maxFps` — `IGameConfig`, `IThreeNativeConfig`, or a bare object. */
+interface ITargetFpsConfig {
+    readonly display?: {
+        readonly maxFps?: number | undefined;
+    } | undefined;
+}
+/** Only the one field the rule reads, so a caller need not hold a whole `IPlatformInfo`. */
+type ITargetFpsPlatform = Pick<IPlatformInfo, "formFactor">;
+/**
+ * The nearest common refresh rate, never above `MAX_TARGET_FPS`.
+ *
+ * A measured 59.94 Hz panel and a measured 60 Hz one are the same panel, and a value the engine
+ * invents rather than reads is a value no display can be asked to hold.
+ */
+declare function snapRefreshRate(refreshHz: number): number;
+/**
+ * The single reader of `display.maxFps`, used by the loop, the resolution scaler, the scene-shape
+ * warning, the frame-budget marker and the templates.
+ *
+ * `measuredRefreshHz` is the display's own rate when the platform can say it, and is what turns
+ * `"fallback"` into `"display"`. A negative or non-finite configured rate throws rather than
+ * quietly falling back: a config the engine ignored is worse than a config it rejected.
+ */
+declare function resolveTargetFps(config: ITargetFpsConfig | undefined, platform: ITargetFpsPlatform | undefined, measuredRefreshHz?: number): ITargetFps;
+
 /**
  * Per-presented-frame cost attribution, on by default, for every platform.
  *
@@ -23,6 +179,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 +187,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 +202,7 @@ interface IFramePhaseSample {
     readonly update: number;
     readonly render: number;
     readonly overlay: number;
+    readonly ui: number;
     readonly residual: number;
 }
 /**
@@ -82,16 +245,63 @@ interface IFrameBudgetSummary {
     readonly p99: number;
     readonly max: number;
 }
+/** Where one resolved frame's GPU milliseconds went. Closed on purpose, like the phases. */
+declare const FRAME_GPU_BUCKETS: readonly ["main", "shadow", "other", "compute"];
+type FrameGpuBucket = (typeof FRAME_GPU_BUCKETS)[number];
+/** One frame's GPU milliseconds per bucket; a bucket the device did not resolve is absent. */
+type IFrameGpuBucketSample = Partial<Record<FrameGpuBucket, 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 +310,26 @@ 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>>>;
+    /**
+     * Instances and triangles the GPU actually selected in the main pass, from the streamed world's
+     * own indirect-args tally when it has one.
+     *
+     * These are the honest counterpart of `passes.main`: three's `renderer.info.render.triangles`
+     * counts a mesh's CPU window/capacity for an indirect draw, so `passes.main.triangles` is an upper
+     * bound over what the GPU could draw, while `mainGpuTriangles` is the sum over the indirect
+     * records of `instanceCount x indexCount / 3` — what the kernel selected. Main pass only: shadow
+     * passes are not tallied. Absent, never zero, before the first sample lands.
+     */
+    readonly mainGpuInstances?: number;
+    readonly mainGpuTriangles?: number;
     /**
      * 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 +337,66 @@ interface IFrameBudgetWindow {
      */
     readonly surface?: IFrameSurfaceState;
     /**
-     * GPU milliseconds for a frame in this window, from `timestamp-query`, when the adapter has it.
+     * The rate the loop is holding, and what decided it, when the engine resolved one.
      *
-     * 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.
+     * Two fields rather than an object, and a harness reads them without unwrapping anything: a
+     * number nobody can place (`targetSource: "fallback"`) is the difference between a game holding
+     * its panel and a game settling for 60, and only this line says which one happened.
+     */
+    readonly targetFps?: number;
+    readonly targetSource?: TargetFpsSource;
+    /**
+     * 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.
+     *
+     * 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;
+    /**
+     * GPU milliseconds per resolved frame, split by where the device spent them: the main scene
+     * pass, every shadow pass, everything else in the render pool (post chain, reflections, HUD) and
+     * the compute pool. Each is the window's p50 over the frames that resolved it, one decimal.
+     *
+     * `gpu` is their sum's series; these say which pass owns it. Absent rather than zero when that
+     * bucket never resolved — an unmeasured pass and a free one are different facts — so
+     * `gpuMain + gpuShadow + gpuOther` reconciles with `gpuMs` only when all three are present.
+     */
+    readonly gpuMain?: number;
+    readonly gpuShadow?: number;
+    readonly gpuOther?: number;
+    readonly gpuCompute?: 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,16 +420,39 @@ 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;
+    /**
+     * The engine's resolved frame budget, read once per reported window.
+     *
+     * Wired by the game, which owns the rule and the panel measurement behind it. A window with no
+     * resolver reports no target rather than a default that looks measured.
+     */
+    readonly readTarget?: () => ITargetFps | 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;
+    /**
+     * The GPU-selected main-pass instance and triangle count, read once per reported window.
+     *
+     * Wired by the game from the streamed world's own tally; `undefined` until its first sample lands
+     * or when the world has none, so a window reports absent rather than a fabricated zero.
+     */
+    readonly readGpuTally?: () => {
+        readonly instances: number;
+        readonly triangles: number;
+    } | undefined;
 }
 /**
  * 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 +470,43 @@ 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 where one resolved frame's GPU time went, from the per-pass timestamp split.
+     *
+     * Alongside `addGpuMs`, once per frame. A bucket the producer could not attribute is left out
+     * rather than passed as zero: an unmeasured pass and a free one are different facts, and the
+     * p50 of a bucket that was never measured is absent from the window. An unknown bucket name
+     * throws rather than being dropped, the same fail-closed rule as a phase.
+     */
+    addGpuBucketMs(sample: IFrameGpuBucketSample): 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 +521,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;
 }
 
 /**
@@ -663,7 +1015,33 @@ interface IRendererLike {
      * the `TN_ALPHA_ANTIALIASING` marker is printed either way, so nothing is only readable here.
      */
     alphaAntialiasing?: () => IAlphaAntialiasingReport;
+    /**
+     * The `adapter.info` field value that identifies a CPU rasteriser — `swiftshader`, `llvmpipe`,
+     * a `Microsoft Basic Render Driver` — when the adapter named one, else absent.
+     *
+     * Reading it needs `navigator.gpu`, so it is read here rather than in a game's render source.
+     * It is a fact about the machine, not a look: which tier a game runs on a software adapter is
+     * that game's own decision, and every tier name it might pick is already in its own
+     * `src/render/quality.ts`. What this removes is the reason it could not make that decision
+     * before its first expensive frame — a CPU rasteriser running a desktop render chain can lose
+     * the device on the very first frame, which no adaptation after it survives.
+     *
+     * Absent means no software name was found, never that the adapter is hardware. The native host
+     * exposes the same four `adapter.info` fields, so the same read works on every target.
+     */
+    readonly softwareAdapter?: string;
     compute(node: unknown): void;
+    /**
+     * Creates the GPU buffers these geometries draw from, through the backend's own attribute path,
+     * and reports how many it created.
+     *
+     * `compileAsync` builds pipelines, not buffers: a streamed mesh's first draw is where its
+     * attributes reach the device, and one chunk's first draw measured 230 ms of a frame for it. This
+     * moves that to admission, one chunk at a time. WebGPU only — the WebGL fallback has no seam
+     * this can call without inventing a GL enum — and absent or throwing answers 0, so the first
+     * draw uploads exactly as it did before.
+     */
+    uploadAttributes?(geometries: Iterable<BufferGeometry>): number;
     /**
      * Copies one GPU storage attribute back to the CPU, asynchronously.
      *
@@ -704,6 +1082,44 @@ 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;
+    /**
+     * GPU milliseconds of the last resolved compute frame, when the adapter reports one.
+     *
+     * The compute pool is a separate series from the render pool and `resolveGpuFrame` resolves it,
+     * so a GPU simulation's cost is measurable instead of being charged to whatever render frame
+     * happened to overlap. `undefined` for a WebGL2 fallback, an adapter without timestamps, or a
+     * frame that ran no compute.
+     */
+    gpuComputeMs?(): number | undefined;
+    /**
+     * The main render pass's GPU milliseconds, smoothed over fresh resolved samples, or `undefined`
+     * while no reading is fresh.
+     *
+     * `gpuFrameMs` is the whole render pool, main plus every shadow, reflection, post and HUD pass;
+     * the adaptive LOD control loop needs the main-pass share alone. `game.ts` splits the resolved
+     * frame through the pass recorder and feeds the sample here with {@link noteGpuMainMs}. A
+     * repeated frame id is a resolve still in flight and not a new reading, and with no fresh sample
+     * for too long the value reads absent, so a caller never adapts on a stale number.
+     */
+    gpuMainMs?(): number | undefined;
+    /**
+     * Records one resolved frame's main-pass GPU milliseconds into {@link gpuMainMs}. Called once a
+     * frame by `game.ts`; `ms` is `undefined` when the frame attributed no main-pass reading.
+     */
+    noteGpuMainMs?(ms: number | undefined, frame?: number): void;
     /** Starts a resolve of the GPU timestamps for the frames drawn since the last call. */
     resolveGpuFrame(): void;
     /**
@@ -717,6 +1133,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 +1157,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 +1189,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 { type RenderChainStageId as $, type IRenderChainRequest as A, type IRenderChainStage as B, type IRenderChainStageContext as C, DEFAULT_PIPELINE_CENSUS_LIMIT as D, type IRenderChainVelocityMeasurement as E, type FramePassKind as F, type IRenderChainVelocityReport as G, type IRenderChainVelocityRequest as H, type IRendererLike as I, type IRenderChainVelocityResult as J, type IRenderPassSample as K, type ITargetFps as L, type IVelocityRenderPass as M, MAX_TARGET_FPS as N, PIPELINE_CENSUS_VERSION as O, PIPELINE_CENSUS_CAPABILITY as P, PipelineCensus as Q, type PipelineCensusMode as R, type PipelineCensusStatus as S, type PlatformFormFactor as T, type PlatformOS as U, type PlatformRuntime as V, RENDER_CHAIN_MARKER as W, RENDER_CHAIN_STAGE_ORDER as X, RENDER_CHAIN_TIERS as Y, RenderChain as Z, type RenderChainSource as _, type IFrameBudgetWindow as a, type RenderChainStageName as a0, type RenderChainTier as a1, type RenderChainTierRequest as a2, type RenderChainVelocitySource as a3, type TargetFpsSource as a4, VELOCITY_OUTPUT_NAME as a5, VELOCITY_PREVIOUS_BONE_MATRICES as a6, VELOCITY_PREVIOUS_INSTANCE_MATRICES as a7, VELOCITY_PREVIOUS_WORLD_MATRIX as a8, VelocityTracker as a9, counterDeviceOf as aa, createPipelineCensus as ab, ensureVelocityOutput as ac, getPlatform as ad, isMobile as ae, isNative as af, isTouchscreenAvailable as ag, isWeb as ah, prewarm as ai, readRenderChainObservation as aj, readRenderChainReport as ak, readVelocityPreviousBoneMatrices as al, readVelocityPreviousMatrices as am, readVelocityPreviousWorldMatrix as an, resolveTargetFps as ao, snapRefreshRate as ap, velocityTexture as aq, withVelocityContext as ar, type IRendererOptions as as, DEFAULT_TARGET_FPS as b, FRAME_BUDGET_MARKER as c, FRAME_BUDGET_PHASES as d, FRAME_HITCH_MARKER as e, FrameBudget as f, type FrameBudgetPhase as g, FrameCounters as h, type ICounterDevice as i, type IFrameBudgetOptions as j, type IFrameBudgetPassSummary as k, type IFrameBudgetSummary as l, type IFrameCounters as m, type IFramePhaseSample as n, type IPipelineCensus as o, type IPipelineCensusCounts as p, type IPipelineCensusEvent as q, type IPipelineCensusOptions as r, type IPipelineProvenance as s, type IPipelineShaderObservation as t, type IPlatformInfo as u, type IRenderChainApplied as v, type IRenderChainBudgetWindow as w, type IRenderChainDroppedStage as x, type IRenderChainOptions as y, type IRenderChainRenderer as z };

package/dist/ui-layer.d.ts

@@ -57,6 +57,15 @@ 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 scene-shape verdict the game end publishes when it was launched in dev mode.
+ *
+ * Separate from the state stream because it is not game state: it is the engine's own measurement
+ * of the scene, and a game that never asked for dev mode never sends it. No frame rate rides it —
+ * the loop's rAF rate reads throttled under a compositor or a virtual display, so a number drawn
+ * from it lies in exactly the sessions where somebody is trying to measure.
+ */
+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 +127,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 +170,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 +311,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 };