@threenative/core 0.3.1 → 0.3.3

package/capabilities.json

@@ -1,5 +1,26 @@
 {
   "entries": [
+    {
+      "aliases": [],
+      "constraints": [
+        "deterministic by construction: the packing order is derived from the sources, never from directory order, so a rebuild places every source at the same pixel",
+        "a source the scene samples outside [0, 1] is excluded and reported, never clamped onto a shared page",
+        "page bounds hold regardless of input order; padding keeps a mip tap from reaching the next source"
+      ],
+      "example": "const { pages, transforms, excluded } = packAtlas(sources, { pageSize: 4096, padding: 4 });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function atlasManifest(result: IAtlasResult): string { … }",
+      "situations": [
+        "a merge found nothing to collapse because each imported part owns its own texture",
+        "cut the material count of an imported model pack at build time"
+      ],
+      "summary": "Pack texture sources into deterministic atlas pages and answer each source's UV transform, so a build can stop giving every material a private texture.",
+      "supersedes": [],
+      "symbol": "atlasManifest"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -22,6 +43,27 @@
       "supersedes": [],
       "symbol": "audioPass"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "reads geometry and materials only: no GPU, no runtime, no game",
+        "a texture whose size the document does not state is reported excluded, never assumed square",
+        "a model the reader cannot open is named, never skipped silently"
+      ],
+      "example": "pnpm census:content public/assets",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function censusDocument( model: string, document: Document, pageSize = 4_096, ): IContentCensus { … }",
+      "situations": [
+        "find out whether \"fewer objects\" is available in this content before promising it",
+        "explain why a per-material merge collapsed nothing"
+      ],
+      "summary": "Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.",
+      "supersedes": [],
+      "symbol": "censusDocument"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -42,6 +84,26 @@
       "supersedes": [],
       "symbol": "compileAssets"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand",
+        "the census reads geometry and materials only: no GPU, no runtime, no game"
+      ],
+      "example": "pnpm census:content public/assets",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function dedupeMaterials(materials: readonly IMaterialState[]): { … }",
+      "situations": [
+        "decide whether fewer objects is actually available in this content",
+        "report why a per-material merge collapsed nothing"
+      ],
+      "summary": "Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.",
+      "supersedes": [],
+      "symbol": "dedupeMaterials"
+    },
     {
       "aliases": [],
       "constraints": ["an empty row list produces no report lines"],
@@ -148,6 +210,47 @@
       "supersedes": [],
       "symbol": "lightmapPass"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand",
+        "the census reads geometry and materials only: no GPU, no runtime, no game"
+      ],
+      "example": "pnpm census:content public/assets",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function materialSignature(material: IMaterialState): string { … }",
+      "situations": [
+        "decide whether fewer objects is actually available in this content",
+        "report why a per-material merge collapsed nothing"
+      ],
+      "summary": "Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.",
+      "supersedes": [],
+      "symbol": "materialSignature"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "reads geometry and materials only: no GPU, no runtime, no game",
+        "a texture whose size the document does not state is reported excluded, never assumed square",
+        "a model the reader cannot open is named, never skipped silently"
+      ],
+      "example": "pnpm census:content public/assets",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function materialStateOf(material: Material): IMaterialState { … }",
+      "situations": [
+        "find out whether \"fewer objects\" is available in this content before promising it",
+        "explain why a per-material merge collapsed nothing"
+      ],
+      "summary": "Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.",
+      "supersedes": [],
+      "symbol": "materialStateOf"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -167,6 +270,27 @@
       "supersedes": [],
       "symbol": "modelPass"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "deterministic by construction: the packing order is derived from the sources, never from directory order, so a rebuild places every source at the same pixel",
+        "a source the scene samples outside [0, 1] is excluded and reported, never clamped onto a shared page",
+        "page bounds hold regardless of input order; padding keeps a mip tap from reaching the next source"
+      ],
+      "example": "const { pages, transforms, excluded } = packAtlas(sources, { pageSize: 4096, padding: 4 });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function packAtlas( sources: readonly IAtlasSource[], options: IAtlasOptions = { … }",
+      "situations": [
+        "a merge found nothing to collapse because each imported part owns its own texture",
+        "cut the material count of an imported model pack at build time"
+      ],
+      "summary": "Pack texture sources into deterministic atlas pages and answer each source's UV transform, so a build can stop giving every material a private texture.",
+      "supersedes": [],
+      "symbol": "packAtlas"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -225,6 +349,48 @@
       "supersedes": [],
       "symbol": "resolveBasisTranscoder"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test",
+        "the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate",
+        "`resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself"
+      ],
+      "example": "if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function resolveSourceTexel( atlasUv: readonly [number, number], transform: IAtlasTransform, source: { … }",
+      "situations": [
+        "rewrite a model's texture coordinates after packing its images into an atlas",
+        "tell a surface that tiles from one that merely has a repeating sampler"
+      ],
+      "summary": "Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.",
+      "supersedes": [],
+      "symbol": "resolveSourceTexel"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test",
+        "the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate",
+        "`resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself"
+      ],
+      "example": "if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function rewriteUvs(uv: Float32Array, transform: IAtlasTransform): Float32Array { … }",
+      "situations": [
+        "rewrite a model's texture coordinates after packing its images into an atlas",
+        "tell a surface that tiles from one that merely has a repeating sampler"
+      ],
+      "summary": "Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.",
+      "supersedes": [],
+      "symbol": "rewriteUvs"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -265,6 +431,48 @@
       "supersedes": [],
       "symbol": "texturePass"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "reads geometry and materials only: no GPU, no runtime, no game",
+        "a texture whose size the document does not state is reported excluded, never assumed square",
+        "a model the reader cannot open is named, never skipped silently"
+      ],
+      "example": "pnpm census:content public/assets",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function totalCensus(entries: readonly IContentCensus[]): Omit<IContentCensus, \"model\"> { … }",
+      "situations": [
+        "find out whether \"fewer objects\" is available in this content before promising it",
+        "explain why a per-material merge collapsed nothing"
+      ],
+      "summary": "Census one glTF document, or a directory of them: the merge buckets a scene has now, and the buckets it would have once its atlasable textures shared pages.",
+      "supersedes": [],
+      "symbol": "totalCensus"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test",
+        "the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate",
+        "`resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself"
+      ],
+      "example": "if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function uvsTile(uv: ArrayLike<number>): boolean { … }",
+      "situations": [
+        "rewrite a model's texture coordinates after packing its images into an atlas",
+        "tell a surface that tiles from one that merely has a repeating sampler"
+      ],
+      "summary": "Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.",
+      "supersedes": [],
+      "symbol": "uvsTile"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -284,6 +492,47 @@
       "supersedes": [],
       "symbol": "watchAssets"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "the signature ignores the material name, which is what made every imported part a singleton, and keeps materials apart on any field it does not understand",
+        "the census reads geometry and materials only: no GPU, no runtime, no game"
+      ],
+      "example": "pnpm census:content public/assets",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function withAtlasTextures( materials: readonly IMaterialState[], pageOf: (texture: string) => string | undefined, ): IMaterialState[] { … }",
+      "situations": [
+        "decide whether fewer objects is actually available in this content",
+        "report why a per-material merge collapsed nothing"
+      ],
+      "summary": "Collapse materials that became identical once their textures shared an atlas page, and count the buckets a merge would find — before and after — so the promise can be checked rather than made.",
+      "supersedes": [],
+      "symbol": "withAtlasTextures"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "a surface is tiling when its own UVs leave [0, 1]; glTF's default wrap is REPEAT, so the sampler alone excludes almost everything and is the wrong test",
+        "the rewrite is in place, and a buffer that does not hold pairs throws rather than rewriting half a coordinate",
+        "`resolveSourceTexel` is the inverse, so a build can round-trip a texel instead of asserting the arithmetic against itself"
+      ],
+      "example": "if (!uvsTile(uv)) rewriteUvs(uv, transforms.get(source)!);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function wrapTiles(wrapS: number | undefined, wrapT: number | undefined): boolean { … }",
+      "situations": [
+        "rewrite a model's texture coordinates after packing its images into an atlas",
+        "tell a surface that tiles from one that merely has a repeating sampler"
+      ],
+      "summary": "Move a mesh's UVs onto its atlas page, and decide from the geometry which meshes may not go.",
+      "supersedes": [],
+      "symbol": "wrapTiles"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -307,6 +556,49 @@
       "supersedes": [],
       "symbol": "addInSlices"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function addSpan(id: SpanId, ms: number): void { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "addSpan"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every mass, area, power and inertia value comes from the game's airframe",
+        "damage, stores and configuration arrive as the game's own modifier sample"
+      ],
+      "example": "const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });\nmodel.step(1 / 60, { turn: -1, pitch: 0.4 });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function aerodynamicCoefficients( alpha: number, flaps = 0, gear = 0, brakes = 0, ): { … }",
+      "situations": [
+        "fly an airplane with lift, drag, stall and control authority",
+        "launch an aircraft off a moving carrier deck",
+        "apply component damage or a loadout to an aircraft's performance"
+      ],
+      "summary": "Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.",
+      "supersedes": [],
+      "symbol": "aerodynamicCoefficients"
+    },
     {
       "aliases": [],
       "constraints": ["register from a scene context; callbacks are cleared when that scene exits"],
@@ -324,6 +616,74 @@
       "supersedes": [],
       "symbol": "afterPhysics"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "every mass, area, power and inertia value comes from the game's airframe",
+        "damage, stores and configuration arrive as the game's own modifier sample"
+      ],
+      "example": "const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });\nmodel.step(1 / 60, { turn: -1, pitch: 0.4 });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function aircraftMass(state: IFlightState, airframe: IAircraftAirframe): number { … }",
+      "situations": [
+        "fly an airplane with lift, drag, stall and control authority",
+        "launch an aircraft off a moving carrier deck",
+        "apply component damage or a loadout to an aircraft's performance"
+      ],
+      "summary": "Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.",
+      "supersedes": [],
+      "symbol": "aircraftMass"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every mass, area, power and inertia value comes from the game's airframe",
+        "damage, stores and configuration arrive as the game's own modifier sample"
+      ],
+      "example": "const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });\nmodel.step(1 / 60, { turn: -1, pitch: 0.4 });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function airDensity(y: number): number { … }",
+      "situations": [
+        "fly an airplane with lift, drag, stall and control authority",
+        "launch an aircraft off a moving carrier deck",
+        "apply component damage or a loadout to an aircraft's performance"
+      ],
+      "summary": "Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.",
+      "supersedes": [],
+      "symbol": "airDensity"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the marker is per object and is reported as `exemptMarked` in the projection window",
+        "`renderer.minimumProjectedPixels: false` leaves the scene drawn and keeps the measurement on",
+        "the marker is per object and survives scene rebuilds only as long as the object does",
+        "disabling the gate (`renderer.minimumProjectedPixels: false`) keeps its measurement on"
+      ],
+      "example": "import { alwaysRender } from \"@threenative/core\";\nalwaysRender(ctx.camera.children[0]); // a camera-attached cockpit stays drawn",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [
+        "renderer.minimumProjectedPixels sets the projected-pixel threshold, default 0.5"
+      ],
+      "package": "@threenative/core",
+      "signature": "export function alwaysRender(object: Object3D, enabled = true): void { … }",
+      "situations": [
+        "keep a small object drawn when the engine would skip it as too far to resolve",
+        "stop my cockpit, marker or player model popping out at distance",
+        "a tiny object disappeared at range and I need it always visible",
+        "widen or narrow the projected-size cull with a named threshold"
+      ],
+      "summary": "Keep an object drawn even when the render camera cannot resolve it. The engine's projected-size gate is on by default: an object whose world bounding sphere projects to fewer than 0.5 raster pixels in the camera about to render it is not submitted, per camera. Mark the player's own cockpit, a nameplate, a quest marker, or anything a game never wants to pop out of the frame. `alwaysRender(object, false)` removes the marker. Camera-attached objects and shadow casters are already kept, and the number of marked objects is reported beside the cull in the `TN_PROJECTION` window rather than hidden. The threshold itself is `renderer.minimumProjectedPixels` — a larger number cuts more aggressively, `false` leaves every object drawn while still measuring.",
+      "supersedes": [],
+      "symbol": "alwaysRender"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -409,6 +769,27 @@
       "supersedes": [],
       "symbol": "attachToBone"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "every mass, area, power and inertia value comes from the game's airframe",
+        "damage, stores and configuration arrive as the game's own modifier sample"
+      ],
+      "example": "const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });\nmodel.step(1 / 60, { turn: -1, pitch: 0.4 });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function attitudeAxes(state: IFlightState): IFlightAxes { … }",
+      "situations": [
+        "fly an airplane with lift, drag, stall and control authority",
+        "launch an aircraft off a moving carrier deck",
+        "apply component damage or a loadout to an aircraft's performance"
+      ],
+      "summary": "Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.",
+      "supersedes": [],
+      "symbol": "attitudeAxes"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -431,6 +812,44 @@
       "supersedes": ["new Audio("],
       "symbol": "AudioBus"
     },
+    {
+      "aliases": [],
+      "constraints": [],
+      "example": "const geometry = baseGeometryOf(mesh);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function baseGeometryOf(mesh: Mesh): BufferGeometry { … }",
+      "situations": [
+        "collide or ray-test the authored geometry of a mesh whose render detail changes with distance"
+      ],
+      "summary": "The full-detail geometry of a mesh the loader gave an automatic LOD chain. Selection swaps `mesh.geometry`, so a ray test or a collision body built from the current geometry would change with the camera. Framework picking and gameplay collide against this instead: the authored LOD0, which never changes as the camera moves.",
+      "supersedes": [],
+      "symbol": "baseGeometryOf"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function beginSpan(id: SpanId): void { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "beginSpan"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -676,6 +1095,27 @@
       "supersedes": [],
       "symbol": "ComputeDrivenRegistry"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in",
+        "`gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included",
+        "`jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it"
+      ],
+      "example": "const counters = FrameCounters.install(counterDeviceOf(renderer.raw));",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function counterDeviceOf(raw: unknown): unknown { … }",
+      "situations": [
+        "decide whether a CPU-bound frame is paying for the V8-to-host boundary",
+        "measure how many bytes a frame writes into GPU buffers, and how many commands it issues"
+      ],
+      "summary": "Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing count and a millisecond split describe the same frames.",
+      "supersedes": [],
+      "symbol": "counterDeviceOf"
+    },
     {
       "aliases": ["different props in each area", "first playable screen external assets"],
       "constraints": [
@@ -778,6 +1218,48 @@
       "supersedes": [],
       "symbol": "defineGame"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant",
+        "no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence",
+        "the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking"
+      ],
+      "example": "defineGame({ display: { maxFps: 60 }, scenes: { Play } });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function describeSceneShape( window: IFrameBudgetWindow, cull: IRenderCameraCullReport | undefined, ): ISceneShape | undefined { … }",
+      "situations": [
+        "find out whether a slow frame is the scene's shape or the device",
+        "tell an authoring agent what to reduce before it promises a merge"
+      ],
+      "summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
+      "supersedes": [],
+      "symbol": "describeSceneShape"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant",
+        "no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence",
+        "the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking"
+      ],
+      "example": "defineGame({ display: { maxFps: 60 }, scenes: { Play } });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function describeSceneWarning(warning: ISceneWarning): string { … }",
+      "situations": [
+        "find out whether a slow frame is the scene's shape or the device",
+        "tell an authoring agent what to reduce before it promises a merge"
+      ],
+      "summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
+      "supersedes": [],
+      "symbol": "describeSceneWarning"
+    },
     {
       "aliases": [],
       "constraints": ["pass a non-zero direction; coefficients and radii come from the game"],
@@ -806,6 +1288,49 @@
       "supersedes": [],
       "symbol": "directionFromSolarPosition"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant",
+        "no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence",
+        "the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking"
+      ],
+      "example": "defineGame({ display: { maxFps: 60 }, scenes: { Play } });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function displayPeriodMs( declaredTargetFps: number | undefined, ): { … }",
+      "situations": [
+        "find out whether a slow frame is the scene's shape or the device",
+        "tell an authoring agent what to reduce before it promises a merge"
+      ],
+      "summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
+      "supersedes": [],
+      "symbol": "displayPeriodMs"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function endSpan(id: SpanId): void { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "endSpan"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -828,6 +1353,27 @@
       "supersedes": [],
       "symbol": "ensureVelocityOutput"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "every mass, area, power and inertia value comes from the game's airframe",
+        "damage, stores and configuration arrive as the game's own modifier sample"
+      ],
+      "example": "const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });\nmodel.step(1 / 60, { turn: -1, pitch: 0.4 });",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export class FlightModel<TState extends IFlightState = IFlightState> { … }",
+      "situations": [
+        "fly an airplane with lift, drag, stall and control authority",
+        "launch an aircraft off a moving carrier deck",
+        "apply component damage or a loadout to an aircraft's performance"
+      ],
+      "summary": "Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.",
+      "supersedes": [],
+      "symbol": "FlightModel"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -857,7 +1403,73 @@
     {
       "aliases": [],
       "constraints": [
-        "on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement"
+        "the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant",
+        "no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence",
+        "the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking"
+      ],
+      "example": "defineGame({ display: { maxFps: 60 }, scenes: { Play } });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function formatSceneWarning(warning: ISceneWarning): string { … }",
+      "situations": [
+        "find out whether a slow frame is the scene's shape or the device",
+        "tell an authoring agent what to reduce before it promises a merge"
+      ],
+      "summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
+      "supersedes": [],
+      "symbol": "formatSceneWarning"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function formatSpansWindow(window: ISpanWindow): string { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "formatSpansWindow"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and expensive by construction — it does the work it is checking, twice",
+        "it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads",
+        "it proves the frames it ran on and nothing else"
+      ],
+      "example": "if (renderListValidationRequested()) console.log(formatValidationReport(report));",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function formatValidationReport(report: IValidationReport): string { … }",
+      "situations": [
+        "prove a static freeze did not leave a stale transform on screen",
+        "gate a scene in CI against silent transform divergence"
+      ],
+      "summary": "Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.",
+      "supersedes": [],
+      "symbol": "formatValidationReport"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement",
+        "per-pass numbers are attributed to the innermost active render call, so nested shadow and reflection passes do not read as main",
+        "GPU is a mean/p50/p95/max series over resolved frames (`gpu`) with `gpuStale` counting frames that had no fresh reading; absent means no timestamps, never zero"
       ],
       "example": "defineGame({ frameBudget: { reportEvery: 120 }, scenes: { Play } });",
       "importPath": "@threenative/core",
@@ -867,12 +1479,57 @@
       "signature": "export class FrameBudget { … }",
       "situations": [
         "find out why a game runs slowly on a phone",
-        "attribute a frame to present wait, simulation, three.js render, or overlay"
+        "attribute a frame to present wait, simulation, three.js render, or overlay",
+        "tell whether the GPU is the frame's constraint from a per-frame series, not one lagged timestamp",
+        "split a frame's draw calls and triangles per render pass (main, shadow, reflection)",
+        "tell a shadow or reflection pass's cost from the main colour pass"
       ],
-      "summary": "Read where the frame's milliseconds went, per presented frame, on any platform.",
+      "summary": "Read where the frame's milliseconds went, per presented frame, on any platform; each `TN_FRAME_BUDGET` window also carries the GPU time per resolved frame and the draw calls and triangles each render pass submitted.",
       "supersedes": [],
       "symbol": "FrameBudget"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "counts command-encoder and queue methods only; `mapAsync` and the presentation path are named, not folded in",
+        "`gpuBytes` is `queue.writeBuffer` exactly, so it reconciles against a driver; texture uploads are not included",
+        "`jsAllocBytes` needs `performance.memory` and stays absent where the platform lacks it"
+      ],
+      "example": "const counters = FrameCounters.install(counterDeviceOf(renderer.raw));",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export class FrameCounters { … }",
+      "situations": [
+        "decide whether a CPU-bound frame is paying for the V8-to-host boundary",
+        "measure how many bytes a frame writes into GPU buffers, and how many commands it issues"
+      ],
+      "summary": "Count the frame's host-boundary crossings and the bytes it writes into GPU buffers, off unless `TN_FRAME_SPANS` asks for them. On the frame budget's own window as `counters`, so a crossing count and a millisecond split describe the same frames.",
+      "supersedes": [],
+      "symbol": "FrameCounters"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every mass, area, power and inertia value comes from the game's airframe",
+        "damage, stores and configuration arrive as the game's own modifier sample"
+      ],
+      "example": "const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });\nmodel.step(1 / 60, { turn: -1, pitch: 0.4 });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function gearClearance(state: IFlightState): number { … }",
+      "situations": [
+        "fly an airplane with lift, drag, stall and control authority",
+        "launch an aircraft off a moving carrier deck",
+        "apply component damage or a loadout to an aircraft's performance"
+      ],
+      "summary": "Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.",
+      "supersedes": [],
+      "symbol": "gearClearance"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -978,6 +1635,27 @@
       "supersedes": [],
       "symbol": "GroundSnap"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "returns an uninstall that restores every wrapper, asserted by test",
+        "a renderer whose internals have moved loses that span rather than throwing, and it is absent from the report rather than zero",
+        "only the outermost `_projectObject` opens a span, because three's recurses per child"
+      ],
+      "example": "const uninstall = installSpanProbes(renderer.raw, scene);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function installSpanProbes(target: ISpanProbeTarget, root: Object3D): () => void { … }",
+      "situations": [
+        "measure which part of three's render path costs the frame",
+        "attach the span tree to a renderer a test or a tool constructed itself"
+      ],
+      "summary": "Attach the span probes to a renderer: three's `render`, `_projectObject`, the render list's `sort`, the per-draw submission, and the scene-graph walk. Installed for you when `TN_FRAME_SPANS` asks; exported so a harness can wrap a renderer it owns.",
+      "supersedes": [],
+      "symbol": "installSpanProbes"
+    },
     {
       "aliases": ["landmarks points of interest", "obstacles collectibles increasing pace"],
       "constraints": [
@@ -1003,6 +1681,27 @@
       "supersedes": [],
       "symbol": "InstancedBatch"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
+        "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
+        "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
+      ],
+      "example": "markStatic(island); invalidateStatic(drawbridge);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function invalidateStatic(object: Object3D): number | undefined { … }",
+      "situations": [
+        "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
+        "keep a frozen subtree correct when the game does move it after all"
+      ],
+      "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
+      "supersedes": [],
+      "symbol": "invalidateStatic"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -1045,6 +1744,27 @@
       "supersedes": [],
       "symbol": "isNative"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
+        "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
+        "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
+      ],
+      "example": "markStatic(island); invalidateStatic(drawbridge);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function isStatic(root: Object3D): boolean { … }",
+      "situations": [
+        "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
+        "keep a frozen subtree correct when the game does move it after all"
+      ],
+      "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
+      "supersedes": [],
+      "symbol": "isStatic"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -1109,6 +1829,50 @@
       "supersedes": [],
       "symbol": "loadAll"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
+        "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
+        "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
+      ],
+      "example": "markStatic(island); invalidateStatic(drawbridge);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function markStatic(root: Object3D): number { … }",
+      "situations": [
+        "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
+        "keep a frozen subtree correct when the game does move it after all"
+      ],
+      "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
+      "supersedes": [],
+      "symbol": "markStatic"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "a game that reads a hidden object's matrixWorld directly must use getWorldPosition or updateWorldMatrix(true, false) first",
+        "`renderer.matrixWorld: \"all\"` visits every node; `TN_PROJECTION` reports the visited count either way"
+      ],
+      "example": "import { MatrixWorldPass } from \"@threenative/core\";\nconst pass = new MatrixWorldPass(); // renderer.matrixWorld defaults to \"visible\"",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [
+        "renderer.matrixWorld: \"all\" runs three's full walk instead of the visible-only default"
+      ],
+      "package": "@threenative/core",
+      "signature": "export class MatrixWorldPass { … }",
+      "situations": [
+        "the per-frame world matrix walk is hot in a profile",
+        "stop multiplying matrices for hidden models, LOD levels and merged stand-ins",
+        "a game needs every node walked, exactly as three's own updateMatrixWorld does"
+      ],
+      "summary": "Walk the scene graph's world matrices each frame without recursing into a hidden subtree. On by default as `renderer.matrixWorld: \"visible\"`. three's `updateMatrixWorld` recurses into every child whatever its `visible` flag, so a hidden LOD body, a merged stand-in and a parked model cost a world-matrix multiply each while nothing under them can draw. This pass mirrors three exactly for every visible node and defers a hidden node's subtree until the frame it shows again. A class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a hidden node that holds bones is walked, so no skeleton or view matrix goes stale.",
+      "supersedes": [],
+      "symbol": "MatrixWorldPass"
+    },
     {
       "aliases": [],
       "constraints": ["precise per-vertex measurement is opt-in and not for frame loops"],
@@ -1126,24 +1890,30 @@
     {
       "aliases": [],
       "constraints": [
-        "every part is de-indexed and stripped to position, so UVs and authored normals do not survive; normals are recomputed from the merged buffer",
+        "every part is de-indexed; without preserve it is stripped to position and normals are recomputed from the merged buffer",
+        "preserve keeps the listed channels, transforming position and normal by the part's placement matrix while UV values are retained unchanged",
+        "a part that does not carry a listed preserve channel throws naming the label, the part and the channel",
         "either every part names a color or none does, and a mix throws",
         "an empty part list throws, and a merge three.js refuses throws naming the label"
       ],
-      "example": "const wall = new Mesh(mergeParts(pieces, { label: \"gatehouse\" }), stone);\n// pieces are meshes, or { geometry, matrix, color } when the colour is per piece:\nconst banner = mergeParts([{ color: 0x8b2f1a, geometry: cloth, matrix: placement }], { label: \"banner\" });",
+      "example": "const wall = new Mesh(mergeParts(pieces, { label: \"gatehouse\" }), stone);\n// pieces are meshes, or { geometry, matrix, color } when the colour is per piece:\nconst banner = mergeParts([{ color: 0x8b2f1a, geometry: cloth, matrix: placement }], { label: \"banner\" });\n// keep a model's texture UVs and authored normals while baking its transforms:\nconst hull = mergeParts(hullParts, { label: \"hull\", preserve: [\"uv\", \"normal\"] });",
       "importPath": "@threenative/core",
       "kind": "function",
       "overrides": [
-        "color is per part and optional; without it no colour attribute is written and the surface alone decides"
+        "color is per part and optional; without it no colour attribute is written and the surface alone decides",
+        "preserve is optional and empty by default: position-only merge with recomputed normals, exactly as before"
       ],
       "package": "@threenative/core",
       "signature": "export function mergeParts( parts: Iterable<IMergePart>, options: IMergePartsOptions, ): BufferGeometry { … }",
       "situations": [
         "bake a building, ship or character authored out of primitives into one draw call",
+        "merge multiple static Three.js meshes into one mesh per material",
+        "consolidate the static parts of an imported glTF model into one buffer",
+        "preserve texture UV coordinates and authored normals while baking object transforms",
         "merge many small geometries and keep each piece's own colour",
         "stop mergeGeometries from silently returning null on an extruded shape"
       ],
-      "summary": "Merge pieces a game authored out of primitives into one buffer, keeping each piece's own colour. `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that never move relative to each other — a building, a ship, a character built from boxes. Two things go wrong every time and neither is about how any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing, and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other primitive is indexed, so the merge fails at the first piece and the scene never loads. And a merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a flat `color` attribute written before the merge. Both are mechanical. Geometry, placement, colour and the surface it draws with all stay the game's.",
+      "summary": "Merge pieces a game authored out of primitives into one buffer, keeping each piece's own look. `InstancedBatch` collapses many copies of one shape; this collapses many *different* shapes that never move relative to each other — a building, a ship, a character built from boxes, or the static parts of an imported glTF model. Two things go wrong every time and neither is about how any of it looks. `mergeGeometries` hands back `null` on mismatched inputs instead of throwing, and the usual mismatch is invisible: one `ExtrudeGeometry` is non-indexed while every other primitive is indexed, so the merge fails at the first piece and the scene never loads. And a merged buffer draws with one surface, so per-piece colour is gone unless every piece carries a flat `color` attribute written before the merge. Both are mechanical. By default every part is stripped to position and the normals are recomputed from the merged buffer; pass `preserve` to keep authored normals and texture UVs while baking each part's object transform. Geometry, placement, colour and the surface it draws with all stay the game's.",
       "supersedes": [],
       "symbol": "mergeParts"
     },
@@ -1166,6 +1936,23 @@
       "supersedes": ["new Box3().setFromObject("],
       "symbol": "normaliseToMetres"
     },
+    {
+      "aliases": [],
+      "constraints": [],
+      "example": "const off = onLaunchFailure((failure) => shell.loading({ failure: failure.message }));",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function onLaunchFailure(listener: (failure: ILaunchFailure) => void): () => void { … }",
+      "situations": [
+        "show the player why the game stopped loading instead of leaving the loading screen up",
+        "report a stalled launch or a lost GPU device in the game's own UI"
+      ],
+      "summary": "Called for every launch failure the engine notices, with the message to show the player.",
+      "supersedes": [],
+      "symbol": "onLaunchFailure"
+    },
     {
       "aliases": [],
       "constraints": ["recordings are version 1; the parser fails closed with TN_REPLAY_* codes"],
@@ -1453,26 +2240,89 @@
       "supersedes": [],
       "symbol": "reconcileMirroredClips"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
+        "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
+        "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
+      ],
+      "example": "markStatic(island); invalidateStatic(drawbridge);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function refreshStaticTransforms(): void { … }",
+      "situations": [
+        "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
+        "keep a frozen subtree correct when the game does move it after all"
+      ],
+      "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
+      "supersedes": [],
+      "symbol": "refreshStaticTransforms"
+    },
     {
       "aliases": [],
       "constraints": [
         "stage factories own colour, strength, and all other appearance choices",
         "authored stages declare exactly one before or after anchor"
       ],
-      "example": "const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: [\"bloom\"], tier: \"auto\" } });",
+      "example": "const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: [\"bloom\"], tier: \"auto\" } });",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export class RenderChain { … }",
+      "situations": [
+        "compose screen-space effects in a canonical order",
+        "insert a game-authored post stage into the measured render chain",
+        "report which render tier and velocity route actually ran"
+      ],
+      "summary": "Compose game-provided render nodes in a measured, fail-closed chain. Authored stages use an opaque id and anchor before or after a built-in or another supplied stage; the engine does not need to know the effect's visual vocabulary.",
+      "supersedes": [],
+      "symbol": "RenderChain"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and expensive by construction — it does the work it is checking, twice",
+        "it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads",
+        "it proves the frames it ran on and nothing else"
+      ],
+      "example": "if (renderListValidationRequested()) console.log(formatValidationReport(report));",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function renderListValidationRequested(): boolean { … }",
+      "situations": [
+        "prove a static freeze did not leave a stale transform on screen",
+        "gate a scene in CI against silent transform divergence"
+      ],
+      "summary": "Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.",
+      "supersedes": [],
+      "symbol": "renderListValidationRequested"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and expensive by construction — it does the work it is checking, twice",
+        "it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads",
+        "it proves the frames it ran on and nothing else"
+      ],
+      "example": "if (renderListValidationRequested()) console.log(formatValidationReport(report));",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
       "package": "@threenative/core",
-      "signature": "export class RenderChain { … }",
+      "signature": "export class RenderListValidator { … }",
       "situations": [
-        "compose screen-space effects in a canonical order",
-        "insert a game-authored post stage into the measured render chain",
-        "report which render tier and velocity route actually ran"
+        "prove a static freeze did not leave a stale transform on screen",
+        "gate a scene in CI against silent transform divergence"
       ],
-      "summary": "Compose game-provided render nodes in a measured, fail-closed chain. Authored stages use an opaque id and anchor before or after a built-in or another supplied stage; the engine does not need to know the effect's visual vocabulary.",
+      "summary": "Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.",
       "supersedes": [],
-      "symbol": "RenderChain"
+      "symbol": "RenderListValidator"
     },
     {
       "aliases": ["fixed seed fixed-step simulation"],
@@ -1493,6 +2343,43 @@
       "supersedes": [],
       "symbol": "replay"
     },
+    {
+      "aliases": [],
+      "constraints": [],
+      "example": "resetAudioCueLedger();",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function resetAudioCueLedger(): void { … }",
+      "situations": [
+        "clear the recorded audio cue counts between tests so one test cannot read another's plays"
+      ],
+      "summary": "Forgets every recorded cue.",
+      "supersedes": [],
+      "symbol": "resetAudioCueLedger"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
+        "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
+        "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
+      ],
+      "example": "markStatic(island); invalidateStatic(drawbridge);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function resetStaticTransforms(): void { … }",
+      "situations": [
+        "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
+        "keep a frozen subtree correct when the game does move it after all"
+      ],
+      "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
+      "supersedes": [],
+      "symbol": "resetStaticTransforms"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -1525,10 +2412,37 @@
       "supersedes": [],
       "symbol": "resolveAtmosphereParameters"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "it draws nothing; the game supplies the mesh, the material and every colour",
+        "add its height to an analytic swell, never in place of one",
+        "the patch is finite and its rim absorbs; call recenter to keep it over the action",
+        "there is no obstacle mask, because a mask is only correct for a body that never moves"
+      ],
+      "example": "const ripples = new RippleField({ resolution: 128, size: 400 });\nripples.impulse(hit.x, hit.z, 6, -40, 0.5);\nripples.advance(dt);\nconst lift = ripples.heightAt(boat.x, boat.z);",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [
+        "speed, damping, foamHalfLife, current, step and maxSteps tune the solve; the default"
+      ],
+      "package": "@threenative/core",
+      "signature": "export class RippleField { … }",
+      "situations": [
+        "make a splash or explosion ripple outward across water",
+        "show the sea reacting to a bomb, shell, or torpedo hitting it",
+        "leave a foam trail behind something moving through water",
+        "disturb a water surface the player can see respond",
+        "spread and drift foam on a water surface over time"
+      ],
+      "summary": "Propagate a disturbance across a patch of water surface and let it fade. step is 1/60s or the CFL stability limit for the given resolution and speed, whichever is smaller",
+      "supersedes": [],
+      "symbol": "RippleField"
+    },
     {
       "aliases": [],
       "constraints": ["scene code must stay portable across web and native"],
-      "example": "class Play extends Scene { update(ctx, dt) {} }",
+      "example": "class Play extends Scene { update(ctx, dt) {} }\nctx.beforeRender(() => packBatches()); // cleared on scene change and stop, like ctx.afterPhysics",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
@@ -1536,7 +2450,8 @@
       "signature": "export abstract class Scene< TState extends Record<string, unknown> = Record<string, unknown>, TPhysics = undefined, > { … }",
       "situations": [
         "add a playable level or menu scene",
-        "move scene setup and per-frame gameplay out of the entry point"
+        "move scene setup and per-frame gameplay out of the entry point",
+        "run scene work once per actual world draw, after the frame's last fixed update and before the projection packs"
       ],
       "summary": "Implement a portable Godot-shaped game scene lifecycle.",
       "supersedes": [],
@@ -1559,6 +2474,27 @@
       "supersedes": ["new Raycaster("],
       "symbol": "ScenePicker"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "the rule is derived from the frame's own numbers; the display period comes from the host's presentation cap or the game's declared target, never a constant",
+        "no verdict without a measured GPU reading and a pass census — an absent measurement is not evidence",
+        "the record carries objects considered, draws per pass, triangles per draw and shadow-exempt casters, so the reader is not dependent on the ranking"
+      ],
+      "example": "defineGame({ display: { maxFps: 60 }, scenes: { Play } });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function sceneWarning( window: IFrameBudgetWindow, shape: ISceneShape | undefined, declaredTargetFps: number | undefined, ): ISceneWarning | undefined { … }",
+      "situations": [
+        "find out whether a slow frame is the scene's shape or the device",
+        "tell an authoring agent what to reduce before it promises a merge"
+      ],
+      "summary": "Warn the agent that built the scene before a human plays it: a frame whose GPU is idle while its JS render phase is longer than the display's own period is a scene-shape problem, and the engine already has the shape. On by default, printed at most once per reported window as `TN_SCENE_WARNING`, and silent on a scene that is honestly GPU-bound.",
+      "supersedes": [],
+      "symbol": "sceneWarning"
+    },
     {
       "aliases": ["tower defense game", "spawn waves"],
       "constraints": [
@@ -1580,6 +2516,49 @@
       "supersedes": [],
       "symbol": "Scheduler"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "every mass, area, power and inertia value comes from the game's airframe",
+        "damage, stores and configuration arrive as the game's own modifier sample"
+      ],
+      "example": "const model = new FlightModel({ airframe: sbd, state: aircraft, wind: seaWind });\nmodel.step(1 / 60, { turn: -1, pitch: 0.4 });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function setAttitude( state: IFlightState, heading = 0, pitch = 0, roll = 0, ): IFlightQuaternion { … }",
+      "situations": [
+        "fly an airplane with lift, drag, stall and control authority",
+        "launch an aircraft off a moving carrier deck",
+        "apply component damage or a loadout to an aircraft's performance"
+      ],
+      "summary": "Fly a fixed-wing aircraft with a real force balance instead of a steered velocity.",
+      "supersedes": [],
+      "symbol": "setAttitude"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function setSpanRecorder(next: SpanRecorder | undefined): void { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "setSpanRecorder"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -1704,6 +2683,94 @@
       "supersedes": [],
       "symbol": "solarPositionAt"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function spanNow(): number { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "spanNow"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function spanRecorder(): SpanRecorder | undefined { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "spanRecorder"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export class SpanRecorder { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "SpanRecorder"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and installed by `TN_FRAME_SPANS=1`; unset, every call site is one guarded return",
+        "the tree is closed against the frame budget's own render phase, so `TN_FRAME_SPANS` and `TN_FRAME_BUDGET` describe the same frames",
+        "measurement only: no span changes what is drawn, in what order, or with which renderer"
+      ],
+      "example": "if (spansRequested()) setSpanRecorder(new SpanRecorder());",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function spansRequested(): boolean { … }",
+      "situations": [
+        "find out what inside the render phase is actually costing the frame",
+        "tell a shadow pass's traversal from the main pass's, with the residual computed",
+        "price an optimisation against a measured part of the phase rather than the whole of it"
+      ],
+      "summary": "Attribute the render phase to 100% with a nested span tree, off unless `TN_FRAME_SPANS` asks. Every non-leaf reports its own time minus the spans inside it, so an unmeasured part shows up as a residual instead of being filed under \"other\"; a child that outlives its parent reports a negative residual rather than a clamped zero.",
+      "supersedes": [],
+      "symbol": "spansRequested"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -1748,6 +2815,27 @@
       "supersedes": [],
       "symbol": "SpriteAnimator3D"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
+        "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
+        "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
+      ],
+      "example": "markStatic(island); invalidateStatic(drawbridge);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function staticTransformCensus(): IStaticTransformCensus { … }",
+      "situations": [
+        "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
+        "keep a frozen subtree correct when the game does move it after all"
+      ],
+      "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
+      "supersedes": [],
+      "symbol": "staticTransformCensus"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -1768,6 +2856,27 @@
       "supersedes": [],
       "symbol": "TracerPool3D"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "staticness is authored, never guessed; no heuristic watches gameplay and decides for you",
+        "it deletes the local and world matrix composes, not the walk itself — three 0.185 recurses into every child regardless",
+        "a write deeper inside a frozen subtree must call `invalidateStatic`; `TN_RENDERLIST_VALIDATE=1` is what proves it happened"
+      ],
+      "example": "markStatic(island); invalidateStatic(drawbridge);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function unmarkStatic(root: Object3D): void { … }",
+      "situations": [
+        "cut the per-frame matrix work of terrain, buildings, props and other scenery that never moves",
+        "keep a frozen subtree correct when the game does move it after all"
+      ],
+      "summary": "Stop recomposing the transforms of a subtree nobody moves. `markStatic(root)` composes the subtree once and freezes it; the engine re-arms a root whose own transform the game changes, and `invalidateStatic(object)` announces a write deeper inside one.",
+      "supersedes": [],
+      "symbol": "unmarkStatic"
+    },
     {
       "aliases": [],
       "constraints": ["patches cannot introduce omitted, negative, or non-finite physical values"],
@@ -1796,6 +2905,52 @@
       "supersedes": [],
       "symbol": "updateClusteredMeshes"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "the chain is baked by the asset cook; there is no runtime generation and no runtime flag",
+        "`assets.lod: false` opts out globally and `assets.lod.overrides` per asset, with no runtime controller installed",
+        "only static indexed triangles are eligible; skinned, morphed, alpha-blended or authored-LOD meshes keep full detail",
+        "the real gate is measured benefit: a level must save at least `minSaving` (20% default) of its predecessor, and a mesh that cannot is skipped, not forced"
+      ],
+      "example": "// Nothing to call: the loader returns a mesh with the chain and the engine selects every frame.\nconst hull = await ctx.assets.model(\"hull.glb\");\nctx.scene.add(hull.scene);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [
+        "`assets.lod.generation.maxLevels`, `.minTriangles`, `.minTrianglesScope`, `.minSaving` and `.errorTargets` move the bake's ceiling, pre-filter, its scope, its saving rule and its error ladder; `assets.lod.runtime.maxPixelError` and `.hysteresis` move the runtime budget and coarsen band; all by project, preset or asset"
+      ],
+      "package": "@threenative/core",
+      "signature": "export function updateModelLods( root: { … }",
+      "situations": [
+        "draw a vehicle or hull built from many small meshes at distance without its full triangles",
+        "stop a distant model from costing its authored mesh count and triangle count",
+        "one source model, right detail by default, no hand-authored LOD files"
+      ],
+      "summary": "Draw a model at the detail its projected geometric error earns, from a chain the asset cook baked. **This is engine-owned, and a game does not call it.** `assets.lod: {}` opts in — the default-on front door opens after qualification — the `model` pass bakes `TN_discrete_lod` into eligible models, the loader registers the reader, and the engine runs the selection every frame before it renders. Each frame the mesh picks the cheapest baked level whose measured error projects to fewer than the resolved pixel budget, taking the camera's own projection, zoom, viewport and a conservative nearest depth into account. Refinement is immediate; coarsening waits for the resolved hysteresis. A mesh with no baked chain draws its full geometry.",
+      "supersedes": [],
+      "symbol": "updateModelLods"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "off by default and expensive by construction — it does the work it is checking, twice",
+        "it throws on the first divergence rather than logging; a validation mode that continues is one nobody reads",
+        "it proves the frames it ran on and nothing else"
+      ],
+      "example": "if (renderListValidationRequested()) console.log(formatValidationReport(report));",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function validateWorldMatrices(root: Object3D): { … }",
+      "situations": [
+        "prove a static freeze did not leave a stale transform on screen",
+        "gate a scene in CI against silent transform divergence"
+      ],
+      "summary": "Prove that nothing a cache skipped changed the picture: `TN_RENDERLIST_VALIDATE=1` recomputes every world matrix the long way, every frame, and throws on the first element that disagrees with what the frame is about to draw.",
+      "supersedes": [],
+      "symbol": "validateWorldMatrices"
+    },
     {
       "aliases": [],
       "constraints": [
@@ -1888,10 +3043,12 @@
         "it draws nothing; the game supplies the mesh, the material and every colour",
         "the material must be transparent so the frame beneath it is already drawn",
         "thickness is metres, saturating at maxThickness; sky behind the surface reads deep",
-        "one reflection is a second draw of the world, so resolutionScale is the whole cost",
+        "one reflection is a second draw of the world; resolutionScale is its pixels only",
+        "on a crowded scene the mirrored pass is draw-bound: name reflection.layers or pay twice",
+        "reflection.refreshInterval is in presented frames; 1 is every frame, and the default",
         "the mirror plane is level, from level alone; do not parent target to a scaled mesh"
       ],
-      "example": "const surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5 } });\nmaterial.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);",
+      "example": "const REFLECTED = 1; // the layer the big silhouettes sit on\nconst surface = new WaterSurface3D({ level: 0, maxThickness: 3, reflection: { resolutionScale: 0.5, layers: (1 << 0) | (1 << REFLECTED) } });\nmaterial.colorNode = mix(surface.refractionAt(offset), surface.reflectionAt(offset), fresnel);",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
@@ -1901,7 +3058,9 @@
         "reflect the sky and the shoreline in a lake, pond or river",
         "see the bed through the water and have the shallows fade at the shore",
         "know how deep the water is under a pixel without a second render pass",
-        "stop a water surface repeating in visible bands or stripes"
+        "stop a water surface repeating in visible bands or stripes",
+        "keep a crowd of small actors out of the water's reflection so the frame can afford it",
+        "stop the water reflection redrawing the whole world every frame"
       ],
       "summary": "Give a horizontal water surface the world mirrored in it, the world beneath it, and the metres of water between them.",
       "supersedes": [],
@@ -1911,9 +3070,10 @@
       "aliases": [],
       "constraints": [
         "supply every wave amplitude, wavelength, direction, speed and warp value",
-        "call setTime for the default graph clock when the game advances its own time"
+        "call setTime for the default graph clock when the game advances its own time",
+        "sample allocates a result and a normal vector; ask heightAt when only the height is"
       ],
-      "example": "const field = new WaveField({ waves });\nconst { height, normal } = field.sample(x, z, elapsed);",
+      "example": "const field = new WaveField({ waves });\nconst { height, normal } = field.sample(x, z, elapsed);\nconst lift = field.heightAt(x, z, elapsed);",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
@@ -1924,7 +3084,7 @@
         "make water move",
         "find the water surface height at a point"
       ],
-      "summary": "Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph.",
+      "summary": "Evaluate analytic waves on CPU and displace game-owned vertices with the matching TSL graph. wanted, and the warp jacobian, every slope and both allocations are skipped",
       "supersedes": [],
       "symbol": "WaveField"
     },
@@ -2194,7 +3354,7 @@
     {
       "aliases": ["journal objective panel", "readable HUD"],
       "constraints": [
-        "publishes at the store's throttled cadence, and not at all with no UI listening"
+        "publishes once per rendered frame unless stateFlushMs selects a slower interval, and not at all with no UI listening"
       ],
       "example": "publishUiState(bridge, game.state);",
       "importPath": "@threenative/core/ui-layer",
@@ -2206,7 +3366,7 @@
         "show score or health in a UI rendered over the game surface",
         "keep a HUD in step with the game without re-rendering on the loop",
         "publish game state to a HUD in another realm",
-        "keep a web and native UI mirror on the same throttled state stream"
+        "keep a web and native UI mirror on the same coalesced state stream"
       ],
       "summary": "Publish the game's state so a UI in another process can mirror it.",
       "supersedes": [],
@@ -2672,18 +3832,15 @@
     },
     {
       "aliases": [],
-      "constraints": ["unknown scenario keys fail closed"],
-      "example": "const scenario = await loadPlaytestScenario(project, file);",
+      "constraints": ["returns an error; the caller must throw it"],
+      "example": "import { invalidScenario } from \"@threenative/playtest\";\nthrow invalidScenario(\"smoke.playtest.json\", \"Expected a non-empty assertion set\");",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export function invalidScenario(scenarioPath: string, message: string): PlaytestScenarioError { … }",
-      "situations": [
-        "create a browser or device playtest scenario",
-        "wait or hold a game for a deterministic number of ticks"
-      ],
-      "summary": "Load and validate a scenario, then control its tick steps.",
+      "situations": ["construct a validation error for malformed scenario input"],
+      "summary": "Construct a named invalid-scenario error without loading or executing a scenario.",
       "supersedes": [],
       "symbol": "invalidScenario"
     },
@@ -2707,8 +3864,11 @@
     },
     {
       "aliases": [],
-      "constraints": ["unknown scenario keys fail closed"],
-      "example": "const scenario = await loadPlaytestScenario(project, file);",
+      "constraints": [
+        "unknown scenario keys and missing referenced evidence fail closed",
+        "loading validates the fixture; use the runner to execute it"
+      ],
+      "example": "import { loadPlaytestScenario } from \"@threenative/playtest\";\nconst scenario = await loadPlaytestScenario(process.cwd(), \"playtests/smoke.playtest.json\");",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
@@ -2716,9 +3876,9 @@
       "signature": "export async function loadPlaytestScenario(projectPath: string, scenarioPath: string): Promise<IPlaytestScenario> { … }",
       "situations": [
         "create a browser or device playtest scenario",
-        "wait or hold a game for a deterministic number of ticks"
+        "load a deterministic tick-based playtest scenario"
       ],
-      "summary": "Load and validate a scenario, then control its tick steps.",
+      "summary": "Load and validate a scenario and its referenced evidence before running it.",
       "supersedes": [],
       "symbol": "loadPlaytestScenario"
     },
@@ -2838,69 +3998,59 @@
     },
     {
       "aliases": [],
-      "constraints": ["unknown scenario keys fail closed"],
-      "example": "const scenario = await loadPlaytestScenario(project, file);",
+      "constraints": [
+        "the diagnostic describes a failed load, not a successfully executed scenario"
+      ],
+      "example": "import { PlaytestScenarioError } from \"@threenative/playtest\";\nconst error = new PlaytestScenarioError({ code: \"TN_PLAYTEST_SCENARIO_INVALID\", message: \"Invalid fixture\", severity: \"error\", suggestion: \"Fix the fixture\" });",
       "importPath": "@threenative/playtest",
       "kind": "class",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export class PlaytestScenarioError extends Error { … }",
-      "situations": [
-        "create a browser or device playtest scenario",
-        "wait or hold a game for a deterministic number of ticks"
-      ],
-      "summary": "Load and validate a scenario, then control its tick steps.",
+      "situations": ["catch a structured playtest scenario validation error"],
+      "summary": "Carry a structured scenario validation diagnostic as an error.",
       "supersedes": [],
       "symbol": "PlaytestScenarioError"
     },
     {
       "aliases": [],
-      "constraints": ["unknown scenario keys fail closed"],
-      "example": "const scenario = await loadPlaytestScenario(project, file);",
+      "constraints": ["reads the duration only; the runner advances the simulation"],
+      "example": "import { playtestStepHoldTicks } from \"@threenative/playtest\";\nconst ticks = playtestStepHoldTicks({ kind: \"input\", press: \"KeyW\", holdTicks: 30, release: true });",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export function playtestStepHoldTicks(step: IPlaytestStep, fallback = 1): number { … }",
-      "situations": [
-        "create a browser or device playtest scenario",
-        "wait or hold a game for a deterministic number of ticks"
-      ],
-      "summary": "Load and validate a scenario, then control its tick steps.",
+      "situations": ["read the deterministic number of ticks to hold a playtest input"],
+      "summary": "Read a validated step's input-hold duration in simulation ticks.",
       "supersedes": [],
       "symbol": "playtestStepHoldTicks"
     },
     {
       "aliases": [],
-      "constraints": ["unknown scenario keys fail closed"],
-      "example": "const scenario = await loadPlaytestScenario(project, file);",
+      "constraints": ["reads the wait duration only; the runner advances the simulation"],
+      "example": "import { playtestStepWaitTicks } from \"@threenative/playtest\";\nconst ticks = playtestStepWaitTicks({ kind: \"wait\", waitTicks: 30, release: true });",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export function playtestStepWaitTicks(step: IPlaytestStep): number { … }",
-      "situations": [
-        "create a browser or device playtest scenario",
-        "wait or hold a game for a deterministic number of ticks"
-      ],
-      "summary": "Load and validate a scenario, then control its tick steps.",
+      "situations": ["wait or hold a game for a deterministic number of ticks"],
+      "summary": "Read a validated step's no-input duration in simulation ticks.",
       "supersedes": [],
       "symbol": "playtestStepWaitTicks"
     },
     {
       "aliases": [],
-      "constraints": ["unknown scenario keys fail closed"],
-      "example": "const scenario = await loadPlaytestScenario(project, file);",
+      "constraints": ["throws an invalid-scenario error on the first unknown key"],
+      "example": "import { rejectUnknownKeys } from \"@threenative/playtest\";\nrejectUnknownKeys({ name: \"smoke\" }, [\"name\"], \"smoke.playtest.json\", \"scenario\");",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export function rejectUnknownKeys( value: Record<string, unknown>, allowedKeys: readonly string[], scenarioPath: string, objectPath: string, ): void { … }",
-      "situations": [
-        "create a browser or device playtest scenario",
-        "wait or hold a game for a deterministic number of ticks"
-      ],
-      "summary": "Load and validate a scenario, then control its tick steps.",
+      "situations": ["reject an unknown field while validating a scenario object"],
+      "summary": "Reject object keys outside the explicitly allowed scenario fields.",
       "supersedes": [],
       "symbol": "rejectUnknownKeys"
     },
@@ -3734,18 +4884,17 @@
     },
     {
       "aliases": [],
-      "constraints": ["inspect the adapter name before claiming GPU proof"],
-      "example": "const args = resolveBrowserArguments(undefined);",
+      "constraints": [
+        "returns changes only; the caller dispatches them and retains the next snapshot"
+      ],
+      "example": "import { reconcileBrowserPointers } from \"@threenative/playtest/runner\";\nconst changes = reconcileBrowserPointers(new Map(), [{ id: 1, x: 20, y: 30 }]);",
       "importPath": "@threenative/playtest/runner",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export function reconcileBrowserPointers( previous: ReadonlyMap<number, Required<IPlaytestPointer>>, next: readonly IPlaytestPointer[], ): IBrowserPointerChange[] { … }",
-      "situations": [
-        "run a browser playtest with Vulkan WebGPU",
-        "reject a SwiftShader adapter as evidence"
-      ],
-      "summary": "Select safe Chromium arguments for WebGPU playtests.",
+      "situations": ["reconcile pointer contacts into down move and up events"],
+      "summary": "Compare pointer snapshots and produce down, move, and up transitions.",
       "supersedes": [],
       "symbol": "reconcileBrowserPointers"
     },
@@ -3785,18 +4934,18 @@
     },
     {
       "aliases": [],
-      "constraints": ["inspect the adapter name before claiming GPU proof"],
-      "example": "const args = resolveBrowserArguments(undefined);",
+      "constraints": [
+        "pass WEBGPU_BROWSER_ARGS explicitly; undefined selects no additional arguments",
+        "inspect the observed adapter before claiming hardware GPU evidence"
+      ],
+      "example": "import { resolveBrowserArguments, WEBGPU_BROWSER_ARGS } from \"@threenative/playtest/runner\";\nconst args = resolveBrowserArguments(WEBGPU_BROWSER_ARGS);",
       "importPath": "@threenative/playtest/runner",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export function resolveBrowserArguments(browserArgs: readonly string[] | undefined): string[] { … }",
-      "situations": [
-        "run a browser playtest with Vulkan WebGPU",
-        "reject a SwiftShader adapter as evidence"
-      ],
-      "summary": "Select safe Chromium arguments for WebGPU playtests.",
+      "situations": ["run a browser playtest with Vulkan WebGPU"],
+      "summary": "Copy the selected Chromium arguments without silently enabling a rendering recipe.",
       "supersedes": [],
       "symbol": "resolveBrowserArguments"
     },
@@ -3952,18 +5101,17 @@
     },
     {
       "aliases": [],
-      "constraints": ["inspect the adapter name before claiming GPU proof"],
-      "example": "const args = resolveBrowserArguments(undefined);",
+      "constraints": [
+        "undefined means no software name was found, not proof of a hardware adapter"
+      ],
+      "example": "import { softwareAdapterName } from \"@threenative/playtest/runner\";\nconst software = softwareAdapterName({ architecture: \"swiftshader\" });",
       "importPath": "@threenative/playtest/runner",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
       "signature": "export function softwareAdapterName(adapter: Readonly<Record<string, string>> | undefined): string | undefined { … }",
-      "situations": [
-        "run a browser playtest with Vulkan WebGPU",
-        "reject a SwiftShader adapter as evidence"
-      ],
-      "summary": "Select safe Chromium arguments for WebGPU playtests.",
+      "situations": ["reject a SwiftShader adapter as evidence"],
+      "summary": "Identify a software renderer in the fields reported by adapter.info.",
       "supersedes": [],
       "symbol": "softwareAdapterName"
     },
@@ -4122,6 +5270,25 @@
       "supersedes": [],
       "symbol": "viewportRestoreCommands"
     },
+    {
+      "aliases": [],
+      "constraints": [
+        "browser only; requires a scenario and runtime.startup; does not execute scenario steps or assertions",
+        "cancellation is checked between resource acquisitions; lock waiting retains its own bounded queue policy",
+        "use session.screenshot for nonblank PNGs; private-display captures are not FPS evidence",
+        "use threenative-playtest trace --url <url> for slow-frame attribution instead of creating another profiler"
+      ],
+      "example": "import { parseStandalonePlaytestArgs, withBrowserCapture } from \"@threenative/playtest/runner\";\nconst config = parseStandalonePlaytestArgs([\"--scenario\", \"playtests/smoke.playtest.json\", \"--url\", \"http://127.0.0.1:5173\"]);\nawait withBrowserCapture(config, async (session) => session.screenshot(\"ready\"));",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export async function withBrowserCapture<T>( config: IStandalonePlaytestConfig, capture: (session: IBrowserCaptureSession) => Promise<T>, signal?: AbortSignal, ): Promise<T> { … }",
+      "situations": ["write a custom browser capture without owning Xvfb or Chromium cleanup"],
+      "summary": "Capture a ready ThreeNative game with the runner's display, lock, server and browser ownership.",
+      "supersedes": [],
+      "symbol": "withBrowserCapture"
+    },
     {
       "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
@@ -4853,7 +6020,10 @@
     },
     {
       "aliases": [],
-      "constraints": [],
+      "constraints": [
+        "the Geometry tab captures only on an explicit press; nothing is collected while idle",
+        "per-object numbers are measured submissions reconciled against the frame's own pass totals, and the remainder is reported rather than hidden"
+      ],
       "example": "<DebugOverlay />",
       "importPath": "@threenative/ui",
       "kind": "function",
@@ -4862,9 +6032,11 @@
       "signature": "export function DebugOverlay() { … }",
       "situations": [
         "display runtime and playtest diagnostics in a React HUD",
-        "inspect a game without changing its scene"
+        "inspect a game without changing its scene",
+        "find out which scene object is submitting the frame's triangles",
+        "tell a cheap foreground character from an expensive distant prop"
       ],
-      "summary": "Show framework diagnostics while developing a game.",
+      "summary": "Show framework diagnostics while developing a game. Backtick opens it; the Entities tab lists registered entity fields, and the Geometry tab captures one frame and ranks the objects that submitted its triangles beside their projected size on screen.",
       "supersedes": [],
       "symbol": "DebugOverlay"
     },
@@ -4915,7 +6087,7 @@
         "bind a HUD component to game state",
         "select a slice of state for a React panel"
       ],
-      "summary": "Read throttled game state from React.",
+      "summary": "Read the game's coalesced frame snapshot from React.",
       "supersedes": [],
       "symbol": "useGameState"
     },
@@ -4953,6 +6125,90 @@
       "supersedes": [],
       "symbol": "useUiState"
     },
+    {
+      "symbol": "renderer.matrixWorld",
+      "package": "@threenative/core",
+      "importPath": "src/game.ts",
+      "kind": "function",
+      "signature": "renderer.matrixWorld?: \"visible\" | \"all\"",
+      "summary": "The per-frame world-matrix walk, on by default as `\"visible\"`: a hidden subtree — a full-detail body behind a merged stand-in, a hidden LOD level, a parked or hangared model — is not recursed into, so nothing that cannot draw pays a world-matrix multiply. Every visible node is composed exactly as three does, a class that overrides `updateMatrixWorld` (`SkinnedMesh`, `Camera`) runs its own, and a hidden node that holds bones is still walked. `\"all\"` restores three's every-node walk.",
+      "situations": [
+        "updateMatrixWorld and multiplyMatrices are hot in a profile",
+        "the per-frame matrix walk is slow with many hidden LOD bodies or paired full/hull models",
+        "stop paying for matrices of models nothing can draw",
+        "a skinned mesh or camera goes stale because its world matrix was not refreshed",
+        "restore three's own full updateMatrixWorld walk",
+        "compare how many scene nodes the engine walks per frame"
+      ],
+      "example": "renderer: { matrixWorld: \"all\" } // in threenative.config.ts; omit for the visible-only default",
+      "constraints": [
+        "Unset is the shipping behaviour: `\"visible\"`, which does not recurse into a hidden subtree. `\"all\"` visits every node exactly as three's own `updateMatrixWorld` does.",
+        "A game that reads a hidden object's `matrixWorld` directly must not rely on the walk reaching it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` or call `object.updateWorldMatrix(true, false)` first.",
+        "The walk is the engine's either way, so three's renderer never walks the scene a second time; the count of nodes visited is reported as `matrixWorld` in every `TN_PROJECTION` window.",
+        "Bones are never skipped: a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its skeleton's matrices wherever the armature sits."
+      ],
+      "overrides": [
+        "renderer.matrixWorld: \"all\" restores three's every-node walk; the visited count still reports"
+      ],
+      "supersedes": [],
+      "aliases": []
+    },
+    {
+      "symbol": "renderer.minimumProjectedPixels",
+      "package": "@threenative/core",
+      "importPath": "src/game.ts",
+      "kind": "function",
+      "signature": "renderer.minimumProjectedPixels?: number | false",
+      "summary": "Do not submit what the render camera cannot resolve. On by default at a conservative 0.5 projected pixel; an object below it is skipped per render camera. Raise the number to cull more, set `false` to leave every object drawn — the count of what was skipped still reports in `TN_PROJECTION`.",
+      "situations": [
+        "my frame is slow with many distant objects",
+        "draw count is high but the screen is mostly empty",
+        "far away models, aircraft, boats or props cost draw calls but are specks",
+        "a large roster or fleet drops the frame rate while barely visible",
+        "stop submitting objects smaller than a pixel to the camera",
+        "cull by how big something looks to the camera rather than how far it is from the player",
+        "tune how aggressively distant objects are skipped",
+        "a small object I need disappeared at range"
+      ],
+      "example": "renderer: { minimumProjectedPixels: 2 } // in threenative.config.ts",
+      "constraints": [
+        "Unset is the shipping behaviour: the gate runs at 0.5 px. A game that wants the cut a shipped title tuned names 2; `false` leaves every object drawn.",
+        "The decision reads the render camera's projection and viewport, not the player's distance — a camera far from the player still culls its own specks.",
+        "It writes only `object.visible`, which the projection's batch key ignores; `castShadow`, `layers` and `frustumCulled` are never flipped, because that churns batch grouping.",
+        "Shadow casters and objects attached to the render camera are never dropped on the main view alone. Exempt any other object with `alwaysRender`.",
+        "Turning the gate off with `false` does not turn its measurement off: `TN_PROJECTION` still reports considered and skipped counts as `cull`."
+      ],
+      "overrides": [
+        "alwaysRender(object) keeps one object drawn whatever the render camera resolves",
+        "renderer.minimumProjectedPixels: false leaves the scene drawn and keeps the measurement on"
+      ],
+      "supersedes": [],
+      "aliases": []
+    },
+    {
+      "symbol": "renderer.projection",
+      "package": "@threenative/core",
+      "importPath": "src/game.ts",
+      "kind": "function",
+      "signature": "renderer.projection?: boolean",
+      "summary": "The engine's scene-render projection — an internal mirror that collapses repeated draws — on by default. Set `renderer.projection: false` to decline it.",
+      "situations": [
+        "the game got slower after the projection engaged",
+        "turn off the render projection, batching, or the instanced mirror",
+        "draw count fell but frame time did not",
+        "a multi-second freeze when the mirror first engages",
+        "opt out of an engine render optimizer"
+      ],
+      "example": "renderer: { projection: false } // in threenative.config.ts",
+      "constraints": [
+        "Unset is the shipping behaviour: the projection runs. Only an explicit `false` declines it.",
+        "An opted-out game builds no mirror and runs no eligibility scan; the authored scene is what renders, so declining costs nothing rather than being re-judged each frame.",
+        "TN_RENDER_PROJECTION still reports the verdict, with reasonCode `disabled` rather than one of the measured declines."
+      ],
+      "overrides": [],
+      "supersedes": [],
+      "aliases": []
+    },
     {
       "symbol": "WorldEnvironment",
       "package": "three",