@threenative/core 0.3.0 → 0.3.1

package/capabilities.json

@@ -1,9 +1,335 @@
 {
   "entries": [
     {
+      "aliases": [],
+      "constraints": [
+        "a clip declared a loop has its seam measured on the decoded output bytes and fails the build when it exceeds the threshold; the assertion cannot be declared away",
+        "which clips loop, which are positional, and what a clip is for are declared per glob and never inferred from a filename",
+        "sources must be RIFF/WAVE or Ogg Vorbis, which is exactly what every native target decodes; an MP3 fails the bake"
+      ],
+      "example": "const pass = audioPass({ overrides: [{ glob: \"audio/*-bed.ogg\", loop: true }] });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function audioPass(options: IAudioPassOptions = { … }",
+      "situations": [
+        "make an ambience bed loop without an audible click",
+        "halve what a positional sound effect costs a device's memory",
+        "stop an audio asset shipping silent on desktop, Android and iOS"
+      ],
+      "summary": "Conditions a game's audio and proves the conditioning did not destroy it.",
+      "supersedes": [],
+      "symbol": "audioPass"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "source and output directories must be disjoint; a pass failure stops the build with the asset path"
+      ],
+      "example": "const result = await compileAssets({ source: \"assets\", output: \"public\" });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export async function compileAssets( options: IAssetCompileOptions = { … }",
+      "situations": [
+        "compile game assets before a web or native build",
+        "optimize textures for the GPU",
+        "produce a manifest for runtime asset loading"
+      ],
+      "summary": "Compiles a project's source assets into content-addressed runtime files and a manifest.",
+      "supersedes": [],
+      "symbol": "compileAssets"
+    },
+    {
+      "aliases": [],
+      "constraints": ["an empty row list produces no report lines"],
+      "example": "const lines = formatAudioSizes(audioRows);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function formatAudioSizes(rows: readonly IAudioRow[]): readonly string[] { … }",
+      "situations": [
+        "see what audio conditioning did to a clip's wire and decoded size",
+        "read the loop seam and cross-fade a build measured"
+      ],
+      "summary": "Formats audio conditioning measurements for a build report.",
+      "supersedes": [],
+      "symbol": "formatAudioSizes"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the returned lines describe findings; target enforcement happens in runHealthReport"
+      ],
+      "example": "const lines = formatHealthReport(report);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function formatHealthReport(report: IAssetHealthReport): readonly string[] { … }",
+      "situations": [
+        "print asset size, license, and target findings after compilation",
+        "show why an asset health check is warning or failing"
+      ],
+      "summary": "Formats asset health findings and their summary for human-readable output.",
+      "supersedes": [],
+      "symbol": "formatHealthReport"
+    },
+    {
+      "aliases": [],
+      "constraints": ["rows must use bytes before and after from the same compiled input"],
+      "example": "const lines = formatModelSizes(modelRows);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function formatModelSizes(rows: readonly IModelSizeRow[]): readonly string[] { … }",
+      "situations": [
+        "inspect how model optimization changed file and GPU sizes",
+        "print model compression results after an asset build"
+      ],
+      "summary": "Formats model byte, geometry, and embedded-texture measurements for a build report.",
+      "supersedes": [],
+      "symbol": "formatModelSizes"
+    },
+    {
+      "aliases": [],
+      "constraints": ["one row per pass in registry order, per-asset rows sorted by logical path"],
+      "example": "const lines = formatPassCosts(result.passCosts);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function formatPassCosts(rows: readonly IPassCostRow[]): readonly string[] { … }",
+      "situations": [
+        "see which asset pass owns the wall clock after a bake",
+        "compare pass costs between two builds before optimizing the pipeline"
+      ],
+      "summary": "Formats per-pass wall-clock costs for a build report.",
+      "supersedes": [],
+      "symbol": "formatPassCosts"
+    },
+    {
+      "aliases": [],
+      "constraints": ["an empty row list produces no report lines"],
+      "example": "const lines = formatTextureSizes(textureRows);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function formatTextureSizes(rows: readonly ITextureSizeRow[]): readonly string[] { … }",
+      "situations": [
+        "inspect texture compression savings",
+        "print which codec a compiled texture uses"
+      ],
+      "summary": "Formats standalone texture byte measurements for a build report.",
+      "supersedes": [],
+      "symbol": "formatTextureSizes"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the input must be a static self-contained GLB with at least one punctual light"
+      ],
+      "example": "const pass = lightmapPass({ atlasSize: 1024, padding: 2 });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function lightmapPass(options: ILightmapPassOptions): IAssetPass { … }",
+      "situations": [
+        "add baked static lighting to a model",
+        "generate TEXCOORD_1 data for a lightmapped scene"
+      ],
+      "summary": "Generates lightmap UVs and bakes a static GLB's lightmap atlas.",
+      "supersedes": [],
+      "symbol": "lightmapPass"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the pass self-verifies reachable geometry, animation, bounds, and embedded texture bindings before returning output"
+      ],
+      "example": "const pass = modelPass({ simplify: { ratio: 0.5 } });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function modelPass(options: IModelPassOptions = { … }",
+      "situations": [
+        "reduce a model's download and GPU footprint",
+        "optimize a GLB before shipping it with a game"
+      ],
+      "summary": "Optimizes self-contained GLB models through the configured geometry and embedded-texture passes.",
+      "supersedes": [],
+      "symbol": "modelPass"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "returns undefined for `\"none\"`, which drops the audio pass; an absent block returns the defaults",
+        "throws TN_ASSETS_CONFIG_INVALID or TN_ASSETS_CONFIG_UNKNOWN_KEY rather than dropping a key it does not know"
+      ],
+      "example": "const options = parseAudioConfig({ overrides: [{ glob: \"audio/*.ogg\", conditioning: \"none\" }] });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function parseAudioConfig(raw: unknown): IAudioPassOptions | undefined { … }",
+      "situations": [
+        "validate a threenative.config.ts audio block before compiling assets",
+        "ship audio exactly as committed without conditioning it"
+      ],
+      "summary": "Validates a game's declared `assets.audio` block, the one place its keys and ranges are checked.",
+      "supersedes": [],
+      "symbol": "parseAudioConfig"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "non-PNG or truncated bytes return undefined instead of being treated as a valid image"
+      ],
+      "example": "const png = parsePng(bytes); if (png !== undefined) console.log(png.width, png.height);",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function parsePng(value: Buffer): IPngInfo | undefined { … }",
+      "situations": [
+        "inspect a PNG before choosing a texture codec",
+        "read source texture dimensions in an asset health check"
+      ],
+      "summary": "Reads dimensions and alpha metadata from a PNG signature and IHDR header.",
+      "supersedes": [],
+      "symbol": "parsePng"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the supplied working directory must resolve both basis_transcoder.js and basis_transcoder.wasm from its Three.js installation"
+      ],
+      "example": "const transcoder = resolveBasisTranscoder(process.cwd());",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function resolveBasisTranscoder(cwd: string): IBasisTranscoder { … }",
+      "situations": [
+        "prepare compressed textures for runtime loading",
+        "copy the Basis transcoder into a compiled asset output"
+      ],
+      "summary": "Finds Three.js's Basis Universal transcoder files for the runtime KTX2 loader.",
+      "supersedes": [],
+      "symbol": "resolveBasisTranscoder"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "a finding is fail-grade only when the corresponding project target was declared"
+      ],
+      "example": "const report = await runHealthReport(inputs, { maxTextureDimension: 2048 });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export async function runHealthReport( inputs: readonly IAssetHealthInput[], targets: IAssetTargets = { … }",
+      "situations": [
+        "check asset dimensions, triangles, materials, and licenses",
+        "enforce asset budgets during a build"
+      ],
+      "summary": "Measures compiled assets and grades them against declared project targets.",
+      "supersedes": [],
+      "symbol": "runHealthReport"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "compressed source width and height must each be divisible by 4; automatic cooking retains an unaligned source unchanged and reports block-size, while an explicit compression codec override fails",
+        "every compressed source width and height must be divisible by 4 because BC7, BC1, ETC2, and ASTC 4x4 use 4x4 blocks; WebGPU rejects an unaligned texture at draw time",
+        "automatic cooking retains an unaligned source unchanged and reports block-size; an explicit compression codec override fails, while codec \"none\" remains available"
+      ],
+      "example": "const pass = texturePass({ quality: 150 });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function texturePass(options: ITexturePassOptions = { … }",
+      "situations": [
+        "optimize textures for the GPU",
+        "compress PNG or JPEG files before runtime loading"
+      ],
+      "summary": "Encodes standalone textures as mipmapped KTX2/Basis assets for GPU storage.",
+      "supersedes": [],
+      "symbol": "texturePass"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "call close on the returned handle; initial and burst failures are reported without stopping the dev server"
+      ],
+      "example": "const watcher = watchAssets({ cwd: process.cwd() });",
+      "importPath": "@threenative/assets",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/assets",
+      "signature": "export function watchAssets(options: IAssetWatchOptions = { … }",
+      "situations": [
+        "recompile a changed texture without restarting the dev server",
+        "see asset pipeline failures as files are saved"
+      ],
+      "summary": "Watches an asset source directory and recompiles settled changes during development.",
+      "supersedes": [],
+      "symbol": "watchAssets"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the objects, and where each one goes, stay the game's; this decides only when each joins the graph",
+        "input order is the attach order and cannot be changed",
+        "a false `while` stops the run and is reported as `stopped`, never thrown"
+      ],
+      "example": "const report = await addInSlices(objects, (object) => ctx.add(object), {\n  onProgress: ({ added, total }) => setProgress(added / total),\n  while: () => generation.live,\n});",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [
+        "sliceSize defaults to 256; `marker: false` silences the TN_ADD_SLICES line, not the report"
+      ],
+      "package": "@threenative/core",
+      "signature": "export async function addInSlices<T>( objects: Iterable<T>, add: (object: T, index: number) => void, options: IAddInSlicesOptions = { … }",
+      "situations": [
+        "add hundreds of built objects to the scene without one multi-second frame",
+        "stream a detail tier in behind a loading curtain without the page looking hung"
+      ],
+      "summary": "Attach hundreds of built objects to the scene in slices, presenting a frame between each.",
+      "supersedes": [],
+      "symbol": "addInSlices"
+    },
+    {
+      "aliases": [],
+      "constraints": ["register from a scene context; callbacks are cleared when that scene exits"],
+      "example": "afterPhysics(ctx, (dt) => camera.position.copy(player.mesh.position));",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function afterPhysics( context: IAfterPhysicsContext, callback: AfterPhysicsCallback, ): () => void { … }",
+      "situations": [
+        "read a body after physics has moved it",
+        "place a camera or aim from the solved character transform"
+      ],
+      "summary": "Register work that reads a body or camera after physics has moved it and before this frame draws. The engine owns the phase ordering; a callback cannot be misplaced by plugin-array order.",
+      "supersedes": [],
+      "symbol": "afterPhysics"
+    },
+    {
+      "aliases": [],
       "constraints": [
         "name the body a game moves as strideRoot when the animated rig is a child of it",
-        "a one-shot clip always plays at its authored rate; the matched rate re-times loops only"
+        "a one-shot clip always plays at its authored rate; the matched rate re-times loops only",
+        "the matched rate is held inside 0.15x-3x; a speed outside what the clip's own stride supports is clamped, and `stride.rate` says so"
       ],
       "example": "const player = new AnimationPlayer({ clips, root: rig, strideRoot: body });",
       "importPath": "@threenative/core",
@@ -17,13 +343,16 @@
         "play an animation on a character",
         "switch a character between idle and attack clips",
         "stop a walking character's feet from sliding or spinning",
-        "match a walk or run cycle to how fast a character is moving"
+        "match a walk or run cycle to how fast a character is moving",
+        "match an in-place walk cycle with no root motion to the body's speed",
+        "find out what speed an animation clip was authored for"
       ],
-      "summary": "Play a skinned or sprite animation from game code. A travelling clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it.",
+      "summary": "Play a skinned or sprite animation from game code. A locomotion clip's playback rate is matched to the ground the body actually covers, so feet do not skate or spin — on by default, `strideSync: false` to keep the authored rate, and `player.stride` reports the measurement either way. Name the body a game moves as `strideRoot` when the rig is a child of it. Clips authored **in place** — every ActorX and Unreal export, every Mixamo \"in place\" clip, every stock animal pack — are matched too: their stride is read off the ground a planted foot sweeps, and `stride.inPlace` says so.",
       "supersedes": [],
       "symbol": "AnimationPlayer"
     },
     {
+      "aliases": ["bright sky saturated green platforms"],
       "constraints": [
         "supply rayleigh, mie, ozone, planetRadius, and atmosphereRadius; there is no Earth fallback",
         "the game creates the sky object, surface, and sun from the returned nodes"
@@ -43,6 +372,7 @@
       "symbol": "Atmosphere"
     },
     {
+      "aliases": [],
       "constraints": ["supply all physical parameters; this class creates no scene appearance"],
       "example": "const luts = new AtmosphereLuts({ rayleigh, mie, ozone, planetRadius, atmosphereRadius });",
       "importPath": "@threenative/core",
@@ -56,6 +386,7 @@
       "symbol": "AtmosphereLuts"
     },
     {
+      "aliases": [],
       "constraints": [
         "when a request is to hold or attach a weapon to a hand, import and call `attachToBone` from `@threenative/core`; do not manually parent, position, or rotate the rifle",
         "if a stock visual has no skeleton, add a portable Three.js Bone named `RightHand` under the character, then call `attachToBone`; do not replace the helper with manual parenting"
@@ -79,6 +410,7 @@
       "symbol": "attachToBone"
     },
     {
+      "aliases": [],
       "constraints": [
         "create buses before playing clips and dispose them with the game",
         "refDistance and rolloffFactor tune positional falloff and apply to playAt only"
@@ -100,6 +432,7 @@
       "symbol": "AudioBus"
     },
     {
+      "aliases": [],
       "constraints": [
         "call update from the owning scene; no global scene scan is installed",
         "orthographic cameras use their forward direction, and lockAxis restricts world rotation"
@@ -119,6 +452,67 @@
       "symbol": "Billboard3D"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "this walks the target's vertices; call it on a check or a debug sample, not every frame"
+      ],
+      "example": "import { boneContact } from \"@threenative/core\";\nconst contact = boneContact(worker, \"hand_r\", keyboard);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function boneContact( root: Object3D, boneName: string, target: Object3D, ): IBoneContactReport { … }",
+      "situations": [
+        "check that a seated character's hands reach the keyboard",
+        "check that a character's hips meet the chair it is sitting on",
+        "turn \"the character is not touching the prop\" into a number a scenario can assert"
+      ],
+      "summary": "Measure whether a named bone reaches the object it is supposed to be touching, in metres.",
+      "supersedes": [],
+      "symbol": "boneContact"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "a rigid skeleton preserves every parent→child distance under any pose; a named bone is a defect with an address",
+        "this is a diagnostic — it reports numbers and names; it moves nothing and decides no appearance"
+      ],
+      "example": "import { boneLengths, boneLengthDeviations } from \"@threenative/core\";\nconst report = boneLengthDeviations(character, boneLengths(character));\nif (!report.rigid && report.worst !== null) console.log(report.worst.bone, report.worst.ratio);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function boneLengthDeviations( root: Object3D, bind: IBoneLengthSnapshot, options: IBoneLengthDeviationsOptions = { … }",
+      "situations": [
+        "find out why a skinned character renders deformed",
+        "check that an animated pose keeps the skeleton rigid",
+        "name the bone that breaks a posed skeleton without taking a screenshot"
+      ],
+      "summary": "Compare a rig's bone distances now against a captured snapshot and name every bone that moved.",
+      "supersedes": [],
+      "symbol": "boneLengthDeviations"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the baseline and the later comparison must come from the same rig under the same ancestor transform, so a uniform scale cancels"
+      ],
+      "example": "import { boneLengths } from \"@threenative/core\";\nconst baseline = boneLengths(character);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function boneLengths(root: Object3D): IBoneLengthSnapshot { … }",
+      "situations": [
+        "capture a rig's bind-pose bone lengths before any clip plays",
+        "measure a skeleton for the bone-length invariance check"
+      ],
+      "summary": "Measure a rig's parent→child bone distances, in world space, as it stands right now.",
+      "supersedes": [],
+      "symbol": "boneLengths"
+    },
+    {
+      "aliases": [],
       "constraints": [
         "amplitude, rotationAmplitude, frequency, decay, and curve are required game choices",
         "update returns an offset and never writes to a camera"
@@ -138,8 +532,9 @@
       "symbol": "CameraShake"
     },
     {
+      "aliases": [],
       "constraints": [],
-      "example": "const hud = new CanvasLayer({ camera });",
+      "example": "const hud = new CanvasLayer(ctx.viewport);",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
@@ -154,6 +549,66 @@
       "symbol": "CanvasLayer"
     },
     {
+      "aliases": [],
+      "constraints": ["a track that binds nothing counts as driving nothing"],
+      "example": "import { clipBoneCoverage } from \"@threenative/core\";\nconst coverage = clipBoneCoverage(character, clip);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function clipBoneCoverage(root: Object3D, clip: AnimationClip): IClipCoverageReport { … }",
+      "situations": [
+        "find out why a character keeps the previous animation's hand shape",
+        "check how much of a rig a clip covers before shipping it"
+      ],
+      "summary": "Report which bones of a character a clip does not drive.",
+      "supersedes": [],
+      "symbol": "clipBoneCoverage"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "each bone is compared as a whole quaternion relative to its own rig's bind pose, so the two rigs never have to share a bind convention; a bone-direction check reports zero on the roll this catches",
+        "both rigs must face the same way in world space, and both are driven and then restored to the transforms they arrived with"
+      ],
+      "example": "import { clipPoseError } from \"@threenative/core\";\nconst report = clipPoseError({ root: rig, clip: retargeted }, { root: source, clip: original });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [
+        "bones maps one rig's bone names onto the other's when they differ; samples sets how many poses are compared"
+      ],
+      "package": "@threenative/core",
+      "signature": "export function clipPoseError( subject: IClipPoseSubject, reference: IClipPoseSubject, options: IClipPoseErrorOptions = { … }",
+      "situations": [
+        "find out why a retargeted animation looks wrong on a character",
+        "tell a fixed retarget from one that merely moved",
+        "catch a retarget that rolled every limb about its own axis"
+      ],
+      "summary": "Score a retargeted clip against the source it came from, per bone, in degrees.",
+      "supersedes": [],
+      "symbol": "clipPoseError"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the reason is Three.js's own, captured off its console hook so a scenario's console assertions stay clean"
+      ],
+      "example": "import { clipTrackBindings } from \"@threenative/core\";\nconst bindings = clipTrackBindings(character, clip);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function clipTrackBindings(root: Object3D, clip: AnimationClip): IClipBindingReport { … }",
+      "situations": [
+        "find out why a character plays its bind pose instead of the animation",
+        "check that a loaded clip actually drives the model it was written for"
+      ],
+      "summary": "Report which of a clip's tracks bind to nothing on a character.",
+      "supersedes": [],
+      "symbol": "clipTrackBindings"
+    },
+    {
+      "aliases": [],
       "constraints": [
         "the body's geometry must carry a cluster table from `assets.models.virtual`",
         "every copy is placed before build(); place() after build() throws"
@@ -176,6 +631,7 @@
       "symbol": "ClusteredBatch"
     },
     {
+      "aliases": [],
       "constraints": [
         "the bake happens in the asset pipeline, never at run time — there is no runtime flag",
         "the payload costs about 3-4x a baked primitive's bytes; `assets.models.virtual: \"none\"` opts out and `minSourceTriangles` moves the 65,536 line",
@@ -201,10 +657,11 @@
       "symbol": "ClusteredMesh"
     },
     {
+      "aliases": [],
       "constraints": [
         "add the object through ctx.add so it attaches, dispatches, and releases with its scene"
       ],
-      "example": "class Cloth extends Mesh implements IComputeDriven { ... }",
+      "example": "const registry = new ComputeDrivenRegistry(); registry.add(cloth, ctx.renderer.raw);",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
@@ -220,6 +677,7 @@
       "symbol": "ComputeDrivenRegistry"
     },
     {
+      "aliases": ["different props in each area", "first playable screen external assets"],
       "constraints": [
         "reuse the loader handed to scenes as `ctx.assets` instead of building parallel caches"
       ],
@@ -238,6 +696,26 @@
       "symbol": "createAssetLoader"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "the capture is bounded and incomplete when the backend cannot expose an observation"
+      ],
+      "example": "const capture = game.runtime.pipelineCensus?.();\n// The game normally reaches this through `runtime.pipelineCensus`; direct construction exists\n// for renderer adapters and contract tests, not for gameplay.",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function createPipelineCensus(options: IPipelineCensusOptions): PipelineCensus { … }",
+      "situations": [
+        "inspect shader and pipeline creation work during a real launch",
+        "correlate pipeline creation with material, object, pass, and shader identities"
+      ],
+      "summary": "Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.",
+      "supersedes": [],
+      "symbol": "createPipelineCensus"
+    },
+    {
+      "aliases": [],
       "constraints": ["use the returned source instead of Math.random for replayable behavior"],
       "example": "const random = createRandom(42);",
       "importPath": "@threenative/core",
@@ -254,10 +732,11 @@
       "symbol": "createRandom"
     },
     {
+      "aliases": ["fixed seed fixed-step simulation"],
       "constraints": [
         "use a seeded random source and fixed-step simulation for meaningful replays"
       ],
-      "example": "const driver = createReplayDriver({ recording });",
+      "example": "const driver = createReplayDriver(recording, ctx.renderer.domElement);",
       "importPath": "@threenative/core",
       "kind": "function",
       "overrides": [],
@@ -272,12 +751,18 @@
       "symbol": "createReplayDriver"
     },
     {
+      "aliases": [
+        "firing line nearest target crosshair",
+        "third-person camera",
+        "restart the run without a page reload",
+        "field of view while aiming"
+      ],
       "constraints": [
         "keep DOM and React mounting in src/main.ts",
         "bind scroll or pinch and read the intent with ctx.input.axis(name); do not add a window wheel listener",
         "scroll: true uses the DOM wheel sign on browser and native: negative deltaY toward the user is positive intent"
       ],
-      "example": "const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play } });",
+      "example": "const game = defineGame({ input: { zoom: { scroll: true, pinch: true } }, scenes: { Play }, start: \"Play\" });",
       "importPath": "@threenative/core",
       "kind": "function",
       "overrides": [],
@@ -286,13 +771,15 @@
       "situations": [
         "start a ThreeNative game from src/game.ts",
         "register physics and gameplay plugins",
-        "let the player zoom the camera with a wheel, pinch, or gamepad axis"
+        "let the player zoom the camera with a wheel, pinch, or gamepad axis",
+        "frame a camera behind the player"
       ],
       "summary": "Define the portable game entry shared by web and native.",
       "supersedes": [],
       "symbol": "defineGame"
     },
     {
+      "aliases": [],
       "constraints": ["pass a non-zero direction; coefficients and radii come from the game"],
       "example": "const transmittance = directionalTransmittance(parameters, sunDirection);",
       "importPath": "@threenative/core",
@@ -306,6 +793,7 @@
       "symbol": "directionalTransmittance"
     },
     {
+      "aliases": [],
       "constraints": ["elevation and azimuth must be finite degrees"],
       "example": "const direction = directionFromSolarPosition(sun.elevation, sun.azimuth);",
       "importPath": "@threenative/core",
@@ -319,6 +807,7 @@
       "symbol": "directionFromSolarPosition"
     },
     {
+      "aliases": [],
       "constraints": [
         "call `VelocityTracker.update()` before the render and `commit()` after it",
         "a pass is only given a velocity target when a temporal stage consumes it",
@@ -340,6 +829,7 @@
       "symbol": "ensureVelocityOutput"
     },
     {
+      "aliases": [],
       "constraints": [
         "add the field through `ctx.add` so renderer attachment, fixed-step dispatch, and release are automatic",
         "`dye` and `velocity` are numeric samplers; appearance stays in the game's `src/render/` code",
@@ -365,6 +855,7 @@
       "symbol": "FluidField2D"
     },
     {
+      "aliases": [],
       "constraints": [
         "on by default and printed as TN_FRAME_BUDGET; defineGame({ frameBudget: false }) silences the marker, not the measurement"
       ],
@@ -383,6 +874,7 @@
       "symbol": "FrameBudget"
     },
     {
+      "aliases": [],
       "constraints": [
         "only use the returned platform facts; native globals are host-owned",
         "ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result"
@@ -403,6 +895,7 @@
       "symbol": "getPlatform"
     },
     {
+      "aliases": [],
       "constraints": ["geometry, color, and timing remain supplied by the game"],
       "example": "const particles = new GPUParticles3D(particleOptions);",
       "importPath": "@threenative/core",
@@ -413,6 +906,7 @@
       "situations": [
         "emit sparks, smoke, or other transient effects",
         "update many small visual particles",
+        "trail dust, exhaust, or spray behind a moving object",
         "emit cannon smoke and muzzle flash particles",
         "fire a cannonball projectile with cannon smoke particles"
       ],
@@ -421,6 +915,7 @@
       "symbol": "GPUParticles3D"
     },
     {
+      "aliases": [],
       "constraints": [
         "the copy is asynchronous, so every sample carries staleFrames and is never this frame",
         "WebGPU only; the seam throws on a WebGL2 renderer rather than returning nothing",
@@ -443,6 +938,7 @@
       "symbol": "GPUReadback"
     },
     {
+      "aliases": [],
       "constraints": [
         "call rebuild() after a scene transform or geometry change; the snapshot is static by default",
         "rebuild() is an explicit CPU SAH build proportional to selected triangles; process() is a no-op, and the game pays upstream traversal per shader ray"
@@ -462,6 +958,7 @@
       "symbol": "GPUSceneBVH"
     },
     {
+      "aliases": [],
       "constraints": [
         "import from `@threenative/core`; this moves the rendered model, not its physics collider"
       ],
@@ -482,6 +979,7 @@
       "symbol": "GroundSnap"
     },
     {
+      "aliases": ["landmarks points of interest", "obstacles collectibles increasing pace"],
       "constraints": [
         "geometry and material are required and come from the game; the batch chooses neither",
         "span stretches along +Y, so its geometry must be unit-height and centred on the origin",
@@ -497,6 +995,7 @@
       "signature": "export class InstancedBatch { … }",
       "situations": [
         "draw hundreds of repeated props without hundreds of draw calls",
+        "draw thousands of identical instanced blocks or obstacles in one mesh",
         "place repeated props when the count is not known until the layout has been walked",
         "build a chain, railing, cable, or tie rod out of point-to-point segments"
       ],
@@ -505,6 +1004,7 @@
       "symbol": "InstancedBatch"
     },
     {
+      "aliases": [],
       "constraints": [
         "only use the returned platform facts; native globals are host-owned",
         "ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result"
@@ -525,6 +1025,7 @@
       "symbol": "isMobile"
     },
     {
+      "aliases": [],
       "constraints": [
         "only use the returned platform facts; native globals are host-owned",
         "ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result"
@@ -545,6 +1046,7 @@
       "symbol": "isNative"
     },
     {
+      "aliases": [],
       "constraints": [
         "only use the returned platform facts; native globals are host-owned",
         "ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result"
@@ -565,6 +1067,7 @@
       "symbol": "isTouchscreenAvailable"
     },
     {
+      "aliases": [],
       "constraints": [
         "only use the returned platform facts; native globals are host-owned",
         "ray tracing is unavailable on native until buffer-to-texture copy-out interop exists; `mystralRT.traceRays` refuses instead of resolving success without a readable result"
@@ -585,6 +1088,29 @@
       "symbol": "isWeb"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "results are written to each item's own index and never appended, so a positional lookup finds the same asset on every load",
+        "the first rejection rejects the call and no lane starts a load it had not begun"
+      ],
+      "example": "const species = await loadAll(names, (name) => ctx.assets.model(`flora/${name}.glb`));",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [
+        "concurrency defaults to 6; `marker: false` silences the TN_LOAD_ALL line, not onProgress"
+      ],
+      "package": "@threenative/core",
+      "signature": "export async function loadAll<TIn, TOut>( items: readonly TIn[], load: (item: TIn, index: number) => Promise<TOut>, options: ILoadAllOptions = { … }",
+      "situations": [
+        "load many models or textures in parallel instead of one at a time",
+        "keep a loading screen moving while a list of assets downloads"
+      ],
+      "summary": "Load a list with bounded concurrency, returning results in the input's order.",
+      "supersedes": [],
+      "symbol": "loadAll"
+    },
+    {
+      "aliases": [],
       "constraints": ["precise per-vertex measurement is opt-in and not for frame loops"],
       "example": "const measurement = measureThreePose(model);",
       "importPath": "@threenative/core",
@@ -598,6 +1124,31 @@
       "symbol": "measureThreePose"
     },
     {
+      "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",
+        "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\" });",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [
+        "color is per part and optional; without it no colour attribute is written and the surface alone decides"
+      ],
+      "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 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.",
+      "supersedes": [],
+      "symbol": "mergeParts"
+    },
+    {
+      "aliases": [],
       "constraints": [
         "skinned height uses a crown bone; game-specific asset expectations stay in render code"
       ],
@@ -616,6 +1167,7 @@
       "symbol": "normaliseToMetres"
     },
     {
+      "aliases": [],
       "constraints": ["recordings are version 1; the parser fails closed with TN_REPLAY_* codes"],
       "example": "const recording = parseReplayRecording(rawRecording);",
       "importPath": "@threenative/core",
@@ -629,8 +1181,9 @@
       "symbol": "parseReplayRecording"
     },
     {
+      "aliases": [],
       "constraints": [],
-      "example": "const follower = new PathFollow3D(curve, { loop: true });",
+      "example": "const follower = new PathFollow3D({ points: patrolPoints, loop: true, speed: 3 });",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
@@ -645,26 +1198,48 @@
       "symbol": "PathFollow3D"
     },
     {
+      "aliases": [],
       "constraints": [
-        "listeners are side-table registrations; Three.js prototypes are never patched",
-        "one raycast serves each active pointer and no raycast runs when nothing is registered"
+        "the capture is bounded and incomplete when the backend cannot expose an observation"
       ],
-      "example": "ctx.pointer.on(tile, \"tapped\", (event) => place(event.point));",
+      "example": "const capture = game.runtime.pipelineCensus?.();\n// The game normally reaches this through `runtime.pipelineCensus`; direct construction exists\n// for renderer adapters and contract tests, not for gameplay.",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
       "package": "@threenative/core",
-      "signature": "export class PointerEvents3D implements IPointerEvents3D { … }",
+      "signature": "export class PipelineCensus { … }",
       "situations": [
-        "let the player click on a thing in the world",
-        "show a 3D object while a pointer hovers over it",
-        "handle touch and mouse taps on a loaded model without naming its child meshes"
+        "inspect shader and pipeline creation work during a real launch",
+        "correlate pipeline creation with material, object, pass, and shader identities"
       ],
-      "summary": "Dispatch portable pointer events from the game surface to registered Three.js objects.",
+      "summary": "Read the renderer's bounded, versioned pipeline capture in a diagnostic or playtest tool.",
+      "supersedes": [],
+      "symbol": "PipelineCensus"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "listeners are side-table registrations; Three.js prototypes are never patched",
+        "one raycast serves each active pointer and no raycast runs when nothing is registered"
+      ],
+      "example": "ctx.pointer.on(tile, \"tapped\", (event) => place(event.point));",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export class PointerEvents3D implements IPointerEvents3D { … }",
+      "situations": [
+        "let the player click on a thing in the world",
+        "show a 3D object while a pointer hovers over it",
+        "handle touch and mouse taps on a loaded model without naming its child meshes",
+        "drag a crate or prop with the mouse or a finger"
+      ],
+      "summary": "Dispatch portable pointer events from the game surface to registered Three.js objects.",
       "supersedes": [],
       "symbol": "PointerEvents3D"
     },
     {
+      "aliases": [],
       "constraints": ["precise per-vertex measurement is opt-in and not for frame loops"],
       "example": "const measurement = measureThreePose(model);",
       "importPath": "@threenative/core",
@@ -678,6 +1253,7 @@
       "symbol": "posedBounds"
     },
     {
+      "aliases": [],
       "constraints": [
         "keep the surface visible with zero opacity; do not hide it with `visible = false`"
       ],
@@ -696,6 +1272,7 @@
       "symbol": "prewarm"
     },
     {
+      "aliases": ["readable world lighting"],
       "constraints": [
         "request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting",
         "add the volume with ctx.add() so its incremental work is measured in the render phase",
@@ -716,27 +1293,27 @@
       "symbol": "ProbeVolume"
     },
     {
+      "aliases": [],
       "constraints": [
-        "request a bake after static geometry and lights are authored; this is static-lighting-first, not fully dynamic relighting",
-        "add the volume with ctx.add() so its incremental work is measured in the render phase",
-        "call sample() or sampleNode() from a game-owned material before screen-space GI; the volume owns no light, material, or colour"
+        "the returned observation is a measurement; it does not own lighting or materials"
       ],
-      "example": "const probes = new ProbeVolume({ bounds, density: 0.5 }); ctx.add(probes); void probes.requestBake(scene);",
+      "example": "const observation = readProbeVolumeObservation(probes);",
       "importPath": "@threenative/core",
       "kind": "function",
-      "overrides": ["density, bounds, bakeBudgetMs, and bounces are game-owned choices"],
+      "overrides": [],
       "package": "@threenative/core",
       "signature": "export function readProbeVolumeObservation(value: unknown): IProbeVolumeObservation | undefined { … }",
-      "situations": [
-        "light bouncing from a room I cannot see",
-        "light a wall with an off-screen emitter"
-      ],
-      "summary": "Bake static diffuse irradiance that reaches surfaces from outside the camera view.",
+      "situations": ["inspect the latest probe bake observation"],
+      "summary": "Read the most recent observation from a probe volume.",
       "supersedes": [],
       "symbol": "readProbeVolumeObservation"
     },
     {
-      "constraints": ["stage factories own colour, strength, and all other appearance choices"],
+      "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\" } });",
       "importPath": "@threenative/core",
       "kind": "function",
@@ -745,15 +1322,18 @@
       "signature": "export function readRenderChainObservation( renderer: unknown, ): IRenderChainMarker[\"applied\"] | undefined { … }",
       "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.",
+      "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": "readRenderChainObservation"
     },
     {
+      "aliases": [],
       "constraints": [
         "stage factories own colour, strength, and all other appearance choices",
+        "authored stages declare exactly one before or after anchor",
         "an absent value means no chain was installed and must fail a chain assertion"
       ],
       "example": "const chain = new RenderChain(renderer, { input: colour, stages, request: { stages: [\"bloom\"], tier: \"auto\" } });",
@@ -764,15 +1344,17 @@
       "signature": "export function readRenderChainReport(renderer: unknown): IRenderChainMarker | undefined { … }",
       "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",
         "expose the render tier and dropped-stage reasons to a playtest",
         "inspect whether a temporal pass received velocity"
       ],
-      "summary": "Compose game-provided render nodes in a measured, fail-closed chain.",
+      "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": "readRenderChainReport"
     },
     {
+      "aliases": [],
       "constraints": [
         "call `VelocityTracker.update()` before the render and `commit()` after it",
         "a pass is only given a velocity target when a temporal stage consumes it"
@@ -793,6 +1375,7 @@
       "symbol": "readVelocityPreviousBoneMatrices"
     },
     {
+      "aliases": [],
       "constraints": [
         "call `VelocityTracker.update()` before the render and `commit()` after it",
         "a pass is only given a velocity target when a temporal stage consumes it"
@@ -813,6 +1396,7 @@
       "symbol": "readVelocityPreviousMatrices"
     },
     {
+      "aliases": [],
       "constraints": [
         "call `VelocityTracker.update()` before the render and `commit()` after it",
         "a pass is only given a velocity target when a temporal stage consumes it"
@@ -833,7 +1417,48 @@
       "symbol": "readVelocityPreviousWorldMatrix"
     },
     {
-      "constraints": ["stage factories own colour, strength, and all other appearance choices"],
+      "aliases": [],
+      "constraints": [
+        "non-marker lines and markers with incomplete or non-numeric stats return `undefined`"
+      ],
+      "example": "const stats = readVirtualShadowMarker(line);\nif (stats !== undefined) console.log(stats.reuseRatio);",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function readVirtualShadowMarker(line: string): IVirtualShadowStats | undefined { … }",
+      "situations": ["inspect virtual shadow cache and mover counters from a renderer log"],
+      "summary": "Parse a `TN_VIRTUAL_SHADOW` console line back into its complete stats, or `undefined`.",
+      "supersedes": [],
+      "symbol": "readVirtualShadowMarker"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the model loader already applies this automatically; only a game loading GLBs around it needs the call",
+        "detection votes per tracked bone and converts only on an overwhelming signature; a file that does not carry it is left byte-identical"
+      ],
+      "example": "import { reconcileMirroredClips } from \"@threenative/core\";\nif (reconcileMirroredClips(gltf.scene, gltf.animations)) console.info(\"clips were z-mirrored; repaired\");",
+      "importPath": "@threenative/core",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export function reconcileMirroredClips(root: Object3D, clips: readonly AnimationClip[]): boolean { … }",
+      "situations": [
+        "find out why a skinned character renders deformed",
+        "repair an imported character that walks backwards with its spine folded",
+        "load a rigged GLB through a custom loader and keep the framework's repair"
+      ],
+      "summary": "Repair an exported rig whose animation clips are z-mirrored against its own bind pose.",
+      "supersedes": [],
+      "symbol": "reconcileMirroredClips"
+    },
+    {
+      "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\" } });",
       "importPath": "@threenative/core",
       "kind": "class",
@@ -842,17 +1467,19 @@
       "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.",
+      "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": ["fixed seed fixed-step simulation"],
       "constraints": [
         "use a seeded random source and fixed-step simulation for meaningful replays"
       ],
-      "example": "const driver = createReplayDriver({ recording });",
+      "example": "const driver = createReplayDriver(recording, ctx.renderer.domElement);",
       "importPath": "@threenative/core",
       "kind": "function",
       "overrides": [],
@@ -867,6 +1494,7 @@
       "symbol": "replay"
     },
     {
+      "aliases": [],
       "constraints": [
         "every width and height must be a positive integer; the dimensions are not a named fidelity tier"
       ],
@@ -882,6 +1510,7 @@
       "symbol": "resolveAtmosphereLutResolutions"
     },
     {
+      "aliases": [],
       "constraints": [
         "provide all three coefficient vectors and both radii; omitted fields are errors"
       ],
@@ -897,6 +1526,7 @@
       "symbol": "resolveAtmosphereParameters"
     },
     {
+      "aliases": [],
       "constraints": ["scene code must stay portable across web and native"],
       "example": "class Play extends Scene { update(ctx, dt) {} }",
       "importPath": "@threenative/core",
@@ -913,8 +1543,9 @@
       "symbol": "Scene"
     },
     {
+      "aliases": [],
       "constraints": [],
-      "example": "const picker = new ScenePicker({ camera, scene });",
+      "example": "const picker = new ScenePicker({ camera: ctx.camera, scene: ctx.scene, pointer: () => ctx.input.raw.pointer, viewport: ctx.viewport });",
       "importPath": "@threenative/core",
       "kind": "class",
       "overrides": [],
@@ -929,6 +1560,7 @@
       "symbol": "ScenePicker"
     },
     {
+      "aliases": ["tower defense game", "spawn waves"],
       "constraints": [
         "dispose returned handles when the owning scene exits",
         "ease receives progress in the range 0 to 1 and its return value is the interpolation factor"
@@ -949,6 +1581,33 @@
       "symbol": "Scheduler"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "use strideRoot to name the body moved by game code when the rig is parented under it",
+        "requiredClips fails closed at load time if any requested clip is missing or binds 0 tracks"
+      ],
+      "example": "import { SkeletalMesh3D } from \"@threenative/core\";\nconst character = new SkeletalMesh3D({\n  source: gltf.scene, clips: gltf.animations, requiredClips: [\"idle\", \"walk\"],\n  size: { metres: 1.8, axis: \"height\" }, strideRoot: body,\n});\nbody.add(character.root); character.play(\"idle\");\nfunction update(dt: number): void { character.update(dt); }",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [
+        "strideSync controls whether locomotion playback rate matches ground covered",
+        "size normalises the instance to real-world metres with skin-aware measurement"
+      ],
+      "package": "@threenative/core",
+      "signature": "export class SkeletalMesh3D extends AnimationPlayer { … }",
+      "situations": [
+        "put an animated character in the scene",
+        "my imported character renders deformed",
+        "instance an imported rigged character",
+        "validate animation clips on a character rig at load time",
+        "prepare a skinned character with safe skeleton cloning and stride sync"
+      ],
+      "summary": "Shared preparation for an imported rigged character. Instances the rig with a skeleton-safe clone, normalises size with skin-aware measurement, validates requested clips against the file and rig at load time, and sets up AnimationPlayer with honest stride-root accounting.",
+      "supersedes": [],
+      "symbol": "SkeletalMesh3D"
+    },
+    {
+      "aliases": [],
       "constraints": [],
       "example": "import { skeletonBones } from \"@threenative/core\";\nconst bones = skeletonBones(character);",
       "importPath": "@threenative/core",
@@ -965,6 +1624,7 @@
       "symbol": "skeletonBones"
     },
     {
+      "aliases": [],
       "constraints": [
         "the mesh must use one Three.js node material and contain complete triangles",
         "pinned, stiffness, damping, gravity, and wind are required game-owned inputs",
@@ -990,6 +1650,7 @@
       "symbol": "SoftBody3D"
     },
     {
+      "aliases": [],
       "constraints": [
         "canvas-painted images sample black under WebGPURenderer; write sprites as pixel data there"
       ],
@@ -1008,6 +1669,7 @@
       "symbol": "softCircleDataTexture"
     },
     {
+      "aliases": [],
       "constraints": [
         "dates are interpreted as UTC unless utcOffset is supplied; no fixed sun direction is assumed",
         "pass a mutable { azimuth, elevation } target to reuse the result object in a steady frame loop"
@@ -1018,12 +1680,16 @@
       "overrides": [],
       "package": "@threenative/core",
       "signature": "export function solarPosition(input: ISolarPositionInput, target?: ISolarPosition): ISolarPosition;",
-      "situations": ["move a sun across a real day at a game's latitude and longitude"],
+      "situations": [
+        "move a sun across a real day at a game's latitude and longitude",
+        "run a day and night cycle over the game's sky"
+      ],
       "summary": "Calculate solar elevation and azimuth from time, latitude, and longitude.",
       "supersedes": [],
       "symbol": "solarPosition"
     },
     {
+      "aliases": [],
       "constraints": [
         "dates are interpreted as UTC; use solarPosition for an explicit local offset"
       ],
@@ -1039,6 +1705,7 @@
       "symbol": "solarPositionAt"
     },
     {
+      "aliases": [],
       "constraints": [
         "it draws nothing; the game supplies the mesh, the material and every colour",
         "CPU height is a throttled copy carrying staleFrames, never this frame and never exact",
@@ -1062,6 +1729,7 @@
       "symbol": "SpectralOcean"
     },
     {
+      "aliases": [],
       "constraints": [
         "the game supplies the atlas texture, surface, filtering, layout, and every frame duration",
         "update is driven by the scene fixed step; no wall clock or default frame rate is used"
@@ -1081,6 +1749,7 @@
       "symbol": "SpriteAnimator3D"
     },
     {
+      "aliases": [],
       "constraints": [
         "the surface comes from the game; pooling, travel, and fading belong to the engine",
         "update once per frame and dispose with the owning scene"
@@ -1100,6 +1769,7 @@
       "symbol": "TracerPool3D"
     },
     {
+      "aliases": [],
       "constraints": ["patches cannot introduce omitted, negative, or non-finite physical values"],
       "example": "atmosphere.setAtmosphere({ rayleigh: [0.008, 0.016, 0.04] });",
       "importPath": "@threenative/core",
@@ -1113,6 +1783,7 @@
       "symbol": "updateAtmosphereParameters"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "updateClusteredMeshes(stagedRoot, myCamera, ctx.renderer.domElement.height);",
       "importPath": "@threenative/core",
@@ -1126,6 +1797,7 @@
       "symbol": "updateClusteredMeshes"
     },
     {
+      "aliases": [],
       "constraints": [
         "call `VelocityTracker.update()` before the render and `commit()` after it",
         "a pass is only given a velocity target when a temporal stage consumes it"
@@ -1146,6 +1818,7 @@
       "symbol": "velocityTexture"
     },
     {
+      "aliases": [],
       "constraints": [
         "call `VelocityTracker.update()` before the render and `commit()` after it",
         "a pass is only given a velocity target when a temporal stage consumes it",
@@ -1167,6 +1840,33 @@
       "symbol": "VelocityTracker"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "the light must be a DirectionalLight with `castShadow` and a target in the scene",
+        "clipExtents are half-widths in world units, finest first, strictly increasing",
+        "call `trackCaster(object)` for movers; it enables layer `VIRTUAL_SHADOW_MOVER_LAYER` on the object and its descendants, tracking or untracking refreshes cached levels once, and subsequent mover movement refreshes only when a window moves"
+      ],
+      "example": "const sun = new DirectionalLight(0xffffff, 3);\nsun.castShadow = true;\nsun.shadow.shadowNode = new VirtualShadowNode(sun, { clipExtents: [12, 40, 120] });",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [
+        "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults, and `marker: false` silences the TN_VIRTUAL_SHADOW line, not the measurement",
+        "bias, biasNode, normalBias, intensity, radius, blurSamples, mapType and filterNode stay on `light.shadow`; mapSize and the other options here have defaults"
+      ],
+      "package": "@threenative/core",
+      "signature": "export class VirtualShadowNode extends ShadowBaseNode { … }",
+      "situations": [
+        "crisp shadows close to the player across a large outdoor level",
+        "shadow map too coarse over a big terrain",
+        "one directional light shadow for a whole open world",
+        "shadows shimmer when the camera moves"
+      ],
+      "summary": "One directional shadow for a whole open world: camera-centred clip levels, each snapped to its own texel grid and re-rendered only when its window moves. Tracked casters draw into a per-level mover map every frame, so animated casters do not invalidate the cached levels after the one refresh caused by tracking or untracking them. Plugs into three's own `light.shadow.shadowNode` slot, so every material receives it.",
+      "supersedes": [],
+      "symbol": "VirtualShadowNode"
+    },
+    {
+      "aliases": [],
       "constraints": [],
       "example": "await warmUpScene(renderer, scene, camera, { onProgress: (p) => setLoading(p) });",
       "importPath": "@threenative/core",
@@ -1183,6 +1883,32 @@
       "symbol": "warmUpScene"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "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",
+        "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);",
+      "importPath": "@threenative/core",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/core",
+      "signature": "export class WaterSurface3D { … }",
+      "situations": [
+        "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"
+      ],
+      "summary": "Give a horizontal water surface the world mirrored in it, the world beneath it, and the metres of water between them.",
+      "supersedes": [],
+      "symbol": "WaterSurface3D"
+    },
+    {
+      "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"
@@ -1203,6 +1929,7 @@
       "symbol": "WaveField"
     },
     {
+      "aliases": [],
       "constraints": [
         "call `VelocityTracker.update()` before the render and `commit()` after it",
         "a pass is only given a velocity target when a temporal stage consumes it"
@@ -1223,6 +1950,7 @@
       "symbol": "withVelocityContext"
     },
     {
+      "aliases": [],
       "constraints": [
         "use the returned value as a validation oracle; the rendered path samples the LUT"
       ],
@@ -1238,6 +1966,7 @@
       "symbol": "zenithTransmittance"
     },
     {
+      "aliases": [],
       "constraints": ["use only in the web development entry"],
       "example": "acceptHotUpdate(game, import.meta.hot);",
       "importPath": "@threenative/core/hot",
@@ -1254,6 +1983,7 @@
       "symbol": "acceptHotUpdate"
     },
     {
+      "aliases": [],
       "constraints": ["state must contain finite numbers and plain objects only"],
       "example": "assertPortableState(game.state.getState());",
       "importPath": "@threenative/core/hot",
@@ -1270,6 +2000,31 @@
       "symbol": "assertPortableState"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "the URL must use HTTPS and the credential is supplied by the game's identity flow; this API never issues credentials",
+        "channels, message sizes, and queues are validated before WebTransport opens, and reliable overflow returns false",
+        "native qualification depends on the installed host WebTransport bridge; iOS remains unverified"
+      ],
+      "example": "const connection = await connect(\"https://game.example/game\", { applicationProtocol: \"my-game/1\", credential, channels: [{ id: 1, delivery: \"unreliable\" }] });",
+      "importPath": "@threenative/core/net",
+      "kind": "function",
+      "overrides": [
+        "connectTimeoutMs, maxReliableMessageBytes, maxQueuedReliableBytes, and maxQueuedDatagrams are named per-connection limits"
+      ],
+      "package": "@threenative/core",
+      "signature": "export function connect(url: string, options: INetworkOptions): Promise<INetworkConnection> { … }",
+      "situations": [
+        "connect two game clients over the portable WebTransport seam",
+        "send ordered actions and bounded unreliable state messages between game clients",
+        "exchange multiplayer messages without putting replication or gameplay in the engine"
+      ],
+      "summary": "Open a bounded, authenticated WebTransport message channel shared by browser and native games.",
+      "supersedes": [],
+      "symbol": "connect"
+    },
+    {
+      "aliases": [],
       "constraints": ["install once in the game's plugin list"],
       "example": "const game = defineGame({ plugins: [playtest()] });",
       "importPath": "@threenative/core/playtest",
@@ -1286,6 +2041,7 @@
       "symbol": "playtest"
     },
     {
+      "aliases": [],
       "constraints": [
         "styling is the `style` prop; Tailwind class names are CSS and cannot cross",
         "import `react`, never `react-dom`, from the portable native entry",
@@ -1308,6 +2064,7 @@
       "symbol": "createReactOverlay"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "const scoreWidth = measureText(\"SCORE 10\", 24)",
       "importPath": "@threenative/core/react",
@@ -1321,6 +2078,7 @@
       "symbol": "measureText"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "supportedGlyphs().includes(\"A\")",
       "importPath": "@threenative/core/react",
@@ -1334,6 +2092,7 @@
       "symbol": "supportedGlyphs"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "supportedStyleKeys().includes(\"centerX\")",
       "importPath": "@threenative/core/react",
@@ -1347,6 +2106,7 @@
       "symbol": "supportedStyleKeys"
     },
     {
+      "aliases": ["objective panel journal"],
       "constraints": [],
       "example": "<Text style={{ color: \"#ffffff\", fontSize: 24 }}>SCORE 10</Text>",
       "importPath": "@threenative/core/react",
@@ -1360,8 +2120,9 @@
       "symbol": "Text"
     },
     {
+      "aliases": [],
       "constraints": [],
-      "example": "<View style={{ centerX: 0, top: 24 }}><Text>READY</Text></View>",
+      "example": "<View style={{ centerX: true, top: 24 }}><Text>READY</Text></View>",
       "importPath": "@threenative/core/react",
       "kind": "function",
       "overrides": [],
@@ -1373,6 +2134,7 @@
       "symbol": "View"
     },
     {
+      "aliases": [],
       "constraints": ["the transport is discovered, never configured; no game names the web view"],
       "example": "const bridge = connectUiBridge({ end: \"ui\" });",
       "importPath": "@threenative/core/ui-layer",
@@ -1391,6 +2153,7 @@
       "symbol": "connectUiBridge"
     },
     {
+      "aliases": [],
       "constraints": ["prefer game.ui.onIntent, which connects the bridge for you"],
       "example": "onUiIntent(bridge, (intent) => { if (intent === \"restart\") game.goto(\"Play\"); });",
       "importPath": "@threenative/core/ui-layer",
@@ -1408,6 +2171,7 @@
       "symbol": "onUiIntent"
     },
     {
+      "aliases": [],
       "constraints": [
         "mark controls with data-tn-interactive; pointer-events is not the mechanism"
       ],
@@ -1428,6 +2192,7 @@
       "symbol": "publishHitRegions"
     },
     {
+      "aliases": ["journal objective panel", "readable HUD"],
       "constraints": [
         "publishes at the store's throttled cadence, and not at all with no UI listening"
       ],
@@ -1448,6 +2213,7 @@
       "symbol": "publishUiState"
     },
     {
+      "aliases": [],
       "constraints": ["one-way; the game decides what each name means and may ignore one"],
       "example": "sendUiIntent(bridge, \"restart\");",
       "importPath": "@threenative/core/ui-layer",
@@ -1466,6 +2232,7 @@
       "symbol": "sendUiIntent"
     },
     {
+      "aliases": [],
       "constraints": ["returns undefined until the game publishes its first state"],
       "example": "const mirror = subscribeUiState(bridge);",
       "importPath": "@threenative/core/ui-layer",
@@ -1483,6 +2250,28 @@
       "symbol": "subscribeUiState"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "unsupported is returned when compute limits are unknown or below the requirement; callers must not silently continue"
+      ],
+      "example": "const capabilities = getWorldCapabilities({ limits: adapter.limits, cpuFallbackIterations: 8 });",
+      "importPath": "@threenative/core/world",
+      "kind": "function",
+      "overrides": [
+        "minimumWorkgroupsPerDimension, minimumStorageBufferBindingSize, and cpuFallbackIterations"
+      ],
+      "package": "@threenative/core",
+      "signature": "export function getWorldCapabilities(options: IWorldCapabilitiesOptions = { … }",
+      "situations": [
+        "decide whether generated terrain can use GPU compute",
+        "report why terrain generation is using a reduced CPU fallback"
+      ],
+      "summary": "Resolve the active world-generation path from host capability facts. The function accepts the adapter facts instead of reaching through a renderer-specific global, so browser and native hosts can report the same object. Missing limits are not treated as infinite: a host must either provide a valid GPU limit report or explicitly choose CPU fallback. GPU generation remains unavailable until a GPU readback can own the canonical field; a host adapter report therefore never upgrades a CPU fallback into a GPU generation claim.",
+      "supersedes": [],
+      "symbol": "getWorldCapabilities"
+    },
+    {
+      "aliases": [],
       "constraints": [
         "sampleHeight owns the terrain shape and stays in game source; the framework stores and interpolates its output",
         "rows and columns are vertex counts; geometry is row-major z-then-x and collider export transposes once into Rapier's column-major matrix order"
@@ -1494,10 +2283,12 @@
         "rows, columns, width, depth, origin, and sampleHeight are explicit on every field"
       ],
       "package": "@threenative/core",
-      "signature": "export class Heightfield { … }",
+      "signature": "export class Heightfield extends Group implements IComputeDriven { … }",
       "situations": [
         "build terrain geometry and collision from one game-authored height function",
+        "generate a terrain a player can walk across",
         "query the same ground height or normal that a player sees and collides with",
+        "ask how high the ground is here",
         "build islands and coastlines from terrain"
       ],
       "summary": "One height buffer shared by world queries, rendered geometry, and a physics heightfield. The game supplies every value, so changing the terrain's shape never requires a package edit. `fromSampler` evaluates that game function exactly once at each vertex and retains only the resulting numbers. Queries interpolate those same numbers instead of evaluating the function again.",
@@ -1505,8 +2296,32 @@
       "symbol": "Heightfield"
     },
     {
+      "aliases": ["stream terrain across chunks"],
+      "constraints": [
+        "sampleHeight and surface are required game choices; no landform or surface preset is installed",
+        "residentTileBudget and residentByteBudget are hard caps; a tile that cannot fit throws"
+      ],
+      "example": "const tiles = new TerrainTiles({ sampleHeight, surface: gameSurface(), tileSize: 256, tileResolution: 129, residentTileBudget: 25, residentByteBudget: 32_000_000 });",
+      "importPath": "@threenative/core/world",
+      "kind": "class",
+      "overrides": [
+        "tileSize, tileResolution, lodFactors, lodDistances, skirtDepth, streamRadius, and budgets"
+      ],
+      "package": "@threenative/core",
+      "signature": "export class TerrainTiles extends Object3D implements IComputeDriven { … }",
+      "situations": [
+        "stream terrain without cracks",
+        "keep generated terrain resident around a moving player",
+        "put a generated terrain tile into a game-owned physics world"
+      ],
+      "summary": "Stream a bounded square of game-authored heightfields and keep their render and physics units together. The class composes ordinary THREE.LOD objects and leaves frustum/projection culling to the renderer's existing scene path.",
+      "supersedes": [],
+      "symbol": "TerrainTiles"
+    },
+    {
+      "aliases": ["pick up item"],
       "constraints": ["add the area to the physics context before stepping the world"],
-      "example": "const area = new Area3D({ context, shape });",
+      "example": "const goal = new Area3D({ physics: ctx.physics, shape: CollisionShape3D.sphere(1.2), position: { x: 0, y: 0.5, z: -8 } });",
       "importPath": "@threenative/physics",
       "kind": "class",
       "overrides": [],
@@ -1521,6 +2336,27 @@
       "symbol": "Area3D"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "supply the game-owned predicate for decorative meshes; the helper throws when it selects nothing",
+        "generated bodies use trimesh geometry and world-space instance transforms"
+      ],
+      "example": "const colliders = buildStaticColliders(ctx, level, { predicate: (object) => object.name.startsWith(\"wall\") });",
+      "importPath": "@threenative/physics",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/physics",
+      "signature": "export function buildStaticColliders( context: IStaticColliderContext, root: Object3D, filter?: StaticColliderFilter, ): readonly RigidBody3D[] { … }",
+      "situations": [
+        "make the level I built stop the player",
+        "turn a cathedral or map scene into static collision"
+      ],
+      "summary": "Build fixed trimesh bodies from the meshes a game authored in a scene root.",
+      "supersedes": [],
+      "symbol": "buildStaticColliders"
+    },
+    {
+      "aliases": [],
       "constraints": ["supply hull points, density, drag, and the height source"],
       "example": "new Buoyancy3D({ body, surface: field, hullPoints, density: 1_000, drag: 4 });",
       "importPath": "@threenative/physics",
@@ -1534,8 +2370,15 @@
       "symbol": "Buoyancy3D"
     },
     {
+      "aliases": [
+        "raised platform gap hazard restart",
+        "enemy targets cooldown reload win condition",
+        "platformer double jump",
+        "first person",
+        "run jump coins goal"
+      ],
       "constraints": ["use moveAndSlide inside the physics update"],
-      "example": "const body = new CharacterBody3D({ context, object });",
+      "example": "const body = new CharacterBody3D({ object: hero, physics: ctx.physics, shape: CollisionShape3D.capsule(0.5, 0.35) });",
       "importPath": "@threenative/physics",
       "kind": "class",
       "overrides": [],
@@ -1550,8 +2393,9 @@
       "symbol": "CharacterBody3D"
     },
     {
+      "aliases": ["passes through body", "arena walls pickups"],
       "constraints": ["create shapes through the owning physics context"],
-      "example": "const shape = new CollisionShape3D({ context, shape: \"capsule\" });",
+      "example": "const shape = CollisionShape3D.capsule(0.5, 0.35);",
       "importPath": "@threenative/physics",
       "kind": "class",
       "overrides": [],
@@ -1566,6 +2410,7 @@
       "symbol": "CollisionShape3D"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "const groups = interactionGroups(1, 3);",
       "importPath": "@threenative/physics",
@@ -1582,19 +2427,25 @@
       "symbol": "interactionGroups"
     },
     {
+      "aliases": [],
       "constraints": ["both bodies must belong to the same physics context"],
-      "example": "const joint = new Joint3D({ context, kind: \"hinge\" });",
+      "example": "const hinge = Joint3D.hinge({ physics: ctx.physics, bodyA: beam, bodyB: bob, anchorA: { x: 0, y: 0, z: 0 }, anchorB: { x: 0, y: 2.4, z: 0 }, axis: { x: 1, y: 0, z: 0 } });",
       "importPath": "@threenative/physics",
       "kind": "class",
       "overrides": [],
       "package": "@threenative/physics",
       "signature": "export class Joint3D { … }",
-      "situations": ["constrain a rigid body to another body", "build a hinge or pin mechanism"],
+      "situations": [
+        "constrain a rigid body to another body",
+        "build a hinge or pin mechanism",
+        "swing a pendulum, wrecking ball, or hinged door on a joint"
+      ],
       "summary": "Connect two physics bodies with a Godot-style joint.",
       "supersedes": [],
       "symbol": "Joint3D"
     },
     {
+      "aliases": ["hitscan camera"],
       "constraints": ["query results are bounded by the configured result limit"],
       "example": "const space = new PhysicsDirectSpaceState3D(context);",
       "importPath": "@threenative/physics",
@@ -1611,6 +2462,7 @@
       "symbol": "PhysicsDirectSpaceState3D"
     },
     {
+      "aliases": [],
       "constraints": ["place rapier() before recast() in the plugin list"],
       "example": "const game = defineGame({ plugins: [rapier()] });",
       "importPath": "@threenative/physics",
@@ -1627,24 +2479,29 @@
       "symbol": "rapier"
     },
     {
+      "aliases": [],
       "constraints": ["register rapier() in the game plugin list before using bodies"],
-      "example": "const crate = new RigidBody3D({ context, object, mode: \"dynamic\" });",
+      "example": "const crate = new RigidBody3D({ object, physics: ctx.physics, shape: CollisionShape3D.box(1, 1, 1), mass: 8 });",
       "importPath": "@threenative/physics",
       "kind": "class",
-      "overrides": [],
+      "overrides": [
+        "continuousCollision: false opts one body out while body.continuousCollision still reports the effective setting"
+      ],
       "package": "@threenative/physics",
       "signature": "export class RigidBody3D { … }",
       "situations": [
         "give a crate or prop physical motion",
         "create a body that collides with a character",
         "fire physical cannonballs that collide with ships or scenery",
-        "fire a cannonball projectile with cannon smoke particles"
+        "fire a cannonball projectile with cannon smoke particles",
+        "a bullet passes through a wall"
       ],
       "summary": "Simulate a dynamic or static rigid body.",
       "supersedes": [],
       "symbol": "RigidBody3D"
     },
     {
+      "aliases": [],
       "constraints": [
         "every body must use CollisionShape3D.box and retain its Three.js object transform",
         "rotated boxes become conservative cloth-local axis-aligned bounds"
@@ -1664,6 +2521,7 @@
       "symbol": "softBodyCollision"
     },
     {
+      "aliases": ["close engagement range"],
       "constraints": [
         "import NavigationAgent3D from exactly `@threenative/physics/navigation`; `@threenative/physics` is not a valid import for this symbol; use this capability instead of hand-written A*; requires recast() after rapier(), plus a baked NavigationRegion3D"
       ],
@@ -1687,6 +2545,7 @@
       "symbol": "NavigationAgent3D"
     },
     {
+      "aliases": [],
       "constraints": ["create it after recast() and dispose it with the scene"],
       "example": "const obstacle = new NavigationObstacle3D({ navigation, object });",
       "importPath": "@threenative/physics/navigation",
@@ -1703,6 +2562,7 @@
       "symbol": "NavigationObstacle3D"
     },
     {
+      "aliases": [],
       "constraints": ["bake before creating agents or obstacles"],
       "example": "const region = new NavigationRegion3D({ navigation, meshes: [floor] });",
       "importPath": "@threenative/physics/navigation",
@@ -1719,6 +2579,7 @@
       "symbol": "NavigationRegion3D"
     },
     {
+      "aliases": [],
       "constraints": ["requires rapier() earlier in the plugins array"],
       "example": "const game = defineGame({ plugins: [rapier(), recast()] });",
       "importPath": "@threenative/physics/navigation",
@@ -1732,6 +2593,7 @@
       "symbol": "recast"
     },
     {
+      "aliases": [],
       "constraints": [
         "bridge values must be JSON-shaped",
         "throws instead of silently dropping the offending field"
@@ -1752,6 +2614,7 @@
       "symbol": "assertJsonSafe"
     },
     {
+      "aliases": [],
       "constraints": [
         "a reading the device does not expose reports unavailable, never zero",
         "a run that started hot or whose thermal status rose is flagged as confounded"
@@ -1771,6 +2634,7 @@
       "symbol": "DeviceMetricsError"
     },
     {
+      "aliases": [],
       "constraints": [
         "a reading the device does not expose reports unavailable, never zero",
         "a run that started hot or whose thermal status rose is flagged as confounded"
@@ -1790,6 +2654,7 @@
       "symbol": "DeviceMetricsRecorder"
     },
     {
+      "aliases": [],
       "constraints": ["malformed or empty assertions fail closed"],
       "example": "const result = evaluateRichPlaytestAssertions(input);",
       "importPath": "@threenative/playtest",
@@ -1806,6 +2671,7 @@
       "symbol": "evaluateRichPlaytestAssertions"
     },
     {
+      "aliases": [],
       "constraints": ["unknown scenario keys fail closed"],
       "example": "const scenario = await loadPlaytestScenario(project, file);",
       "importPath": "@threenative/playtest",
@@ -1822,6 +2688,7 @@
       "symbol": "invalidScenario"
     },
     {
+      "aliases": [],
       "constraints": ["bridge values must be JSON-shaped"],
       "example": "assertJsonSafe({ score: 10 });",
       "importPath": "@threenative/playtest",
@@ -1839,6 +2706,7 @@
       "symbol": "jsonByteLength"
     },
     {
+      "aliases": [],
       "constraints": ["unknown scenario keys fail closed"],
       "example": "const scenario = await loadPlaytestScenario(project, file);",
       "importPath": "@threenative/playtest",
@@ -1855,6 +2723,7 @@
       "symbol": "loadPlaytestScenario"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "const missing = missingPlaytestCapabilities(required, available);",
       "importPath": "@threenative/playtest",
@@ -1871,6 +2740,7 @@
       "symbol": "missingPlaytestCapabilities"
     },
     {
+      "aliases": [],
       "constraints": [
         "a reading the device does not expose reports unavailable, never zero",
         "a run that started hot or whose thermal status rose is flagged as confounded"
@@ -1890,6 +2760,7 @@
       "symbol": "parseDeviceBattery"
     },
     {
+      "aliases": [],
       "constraints": [
         "a reading the device does not expose reports unavailable, never zero",
         "a run that started hot or whose thermal status rose is flagged as confounded"
@@ -1909,6 +2780,7 @@
       "symbol": "parseDeviceCurrent"
     },
     {
+      "aliases": [],
       "constraints": [
         "a reading the device does not expose reports unavailable, never zero",
         "a run that started hot or whose thermal status rose is flagged as confounded"
@@ -1928,6 +2800,7 @@
       "symbol": "parseDevicePowerRails"
     },
     {
+      "aliases": [],
       "constraints": [
         "a reading the device does not expose reports unavailable, never zero",
         "a run that started hot or whose thermal status rose is flagged as confounded"
@@ -1947,8 +2820,9 @@
       "symbol": "parseDeviceThermal"
     },
     {
+      "aliases": [],
       "constraints": [],
-      "example": "playtestDiagnostic(\"physics\", \"body missing\");",
+      "example": "playtestDiagnostic(\"TN_PLAYTEST_CAPABILITY_MISSING\", \"body missing\", \"register rapier() before adding bodies\");",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
@@ -1963,6 +2837,7 @@
       "symbol": "playtestDiagnostic"
     },
     {
+      "aliases": [],
       "constraints": ["unknown scenario keys fail closed"],
       "example": "const scenario = await loadPlaytestScenario(project, file);",
       "importPath": "@threenative/playtest",
@@ -1979,6 +2854,7 @@
       "symbol": "PlaytestScenarioError"
     },
     {
+      "aliases": [],
       "constraints": ["unknown scenario keys fail closed"],
       "example": "const scenario = await loadPlaytestScenario(project, file);",
       "importPath": "@threenative/playtest",
@@ -1995,6 +2871,7 @@
       "symbol": "playtestStepHoldTicks"
     },
     {
+      "aliases": [],
       "constraints": ["unknown scenario keys fail closed"],
       "example": "const scenario = await loadPlaytestScenario(project, file);",
       "importPath": "@threenative/playtest",
@@ -2011,6 +2888,7 @@
       "symbol": "playtestStepWaitTicks"
     },
     {
+      "aliases": [],
       "constraints": ["unknown scenario keys fail closed"],
       "example": "const scenario = await loadPlaytestScenario(project, file);",
       "importPath": "@threenative/playtest",
@@ -2027,13 +2905,14 @@
       "symbol": "rejectUnknownKeys"
     },
     {
+      "aliases": [],
       "constraints": ["malformed or empty assertions fail closed"],
       "example": "const result = evaluateRichPlaytestAssertions(input);",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
-      "signature": "export function requiredPlaytestCapabilities(scenario: IPlaytestScenario): PlaytestCapability[] { … }",
+      "signature": "export function requiredPlaytestCapabilities( scenario: IPlaytestScenario, target?: string, ): PlaytestCapability[] { … }",
       "situations": [
         "assert movement, visibility, or diagnostics in a playtest",
         "turn a scenario observation into a pass or failure"
@@ -2043,19 +2922,21 @@
       "symbol": "requiredPlaytestCapabilities"
     },
     {
+      "aliases": [],
       "constraints": ["absent policy fields default to rejecting errors"],
       "example": "const policy = resolveDiagnosticsPolicy(scenario.assert?.diagnostics);",
       "importPath": "@threenative/playtest",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
-      "signature": "export function resolveDiagnosticsPolicy( policy: IPlaytestDiagnosticsAssertion | undefined, ): IPlaytestDiagnosticsPolicy { … }",
+      "signature": "export function resolveDiagnosticsPolicy( policy: IPlaytestDiagnosticsAssertion | undefined, target?: string, ): IPlaytestDiagnosticsPolicy { … }",
       "situations": ["judge captured console, network, or runtime diagnostics for a playtest"],
       "summary": "Resolve the effective diagnostics policy for a run, with fail-closed defaults applied.",
       "supersedes": [],
       "symbol": "resolveDiagnosticsPolicy"
     },
     {
+      "aliases": [],
       "constraints": [
         "a reading the device does not expose reports unavailable, never zero",
         "a run that started hot or whose thermal status rose is flagged as confounded"
@@ -2075,6 +2956,7 @@
       "symbol": "summarizeDeviceMetrics"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "const missing = missingPlaytestCapabilities(required, available);",
       "importPath": "@threenative/playtest",
@@ -2091,6 +2973,7 @@
       "symbol": "unknownPlaytestCapabilities"
     },
     {
+      "aliases": [],
       "constraints": ["the assertion throws instead of returning a false pass"],
       "example": "assertCaptureNotBlank(png, \"first frame\");",
       "importPath": "@threenative/playtest/capture",
@@ -2107,6 +2990,7 @@
       "symbol": "assertCaptureNotBlank"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "throw new CaptureGuardError(\"menu\", \"no bright pixels\");",
       "importPath": "@threenative/playtest/capture",
@@ -2123,6 +3007,7 @@
       "symbol": "CaptureGuardError"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "const stats = inspectFrame(png);",
       "importPath": "@threenative/playtest/capture",
@@ -2139,6 +3024,7 @@
       "symbol": "inspectFrame"
     },
     {
+      "aliases": [],
       "constraints": ["throws instead of silently dropping the offending field"],
       "example": "assertJsonSafe(snapshot, \"$.components\");",
       "importPath": "@threenative/playtest/protocol",
@@ -2154,6 +3040,7 @@
       "symbol": "assertJsonSafe"
     },
     {
+      "aliases": [],
       "constraints": [],
       "example": "const bytes = jsonByteLength(observation);",
       "importPath": "@threenative/playtest/protocol",
@@ -2169,6 +3056,7 @@
       "symbol": "jsonByteLength"
     },
     {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -2185,6 +3073,7 @@
       "symbol": "AdbAndroidDriver"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2201,8 +3090,9 @@
       "symbol": "advanceFixedStep"
     },
     {
+      "aliases": [],
       "constraints": ["the bridge must answer the handshake or the run fails"],
-      "example": "const bridge = await connectPlaytestBridge(page);",
+      "example": "const bridge = await connectPlaytestBridge(page, scenario);",
       "importPath": "@threenative/playtest/runner",
       "kind": "function",
       "overrides": [],
@@ -2217,6 +3107,7 @@
       "symbol": "advanceTimeoutMs"
     },
     {
+      "aliases": [],
       "constraints": ["paths stay inside the managed artifact directory"],
       "example": "const paths = deviceMailboxPaths(projectRoot);",
       "importPath": "@threenative/playtest/runner",
@@ -2233,6 +3124,7 @@
       "symbol": "androidMailboxPaths"
     },
     {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -2249,6 +3141,7 @@
       "symbol": "androidTouchBatches"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2265,6 +3158,7 @@
       "symbol": "batchArtifactDirectory"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2281,8 +3175,9 @@
       "symbol": "boundedTeardownStep"
     },
     {
+      "aliases": [],
       "constraints": ["the bridge must answer the handshake or the run fails"],
-      "example": "const bridge = await connectPlaytestBridge(page);",
+      "example": "const bridge = await connectPlaytestBridge(page, scenario);",
       "importPath": "@threenative/playtest/runner",
       "kind": "function",
       "overrides": [],
@@ -2297,6 +3192,7 @@
       "symbol": "bridgeWaitTimeoutMs"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2313,6 +3209,7 @@
       "symbol": "buildReport"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2329,8 +3226,9 @@
       "symbol": "captureVisualSurface"
     },
     {
+      "aliases": [],
       "constraints": ["the bridge must answer the handshake or the run fails"],
-      "example": "const bridge = await connectPlaytestBridge(page);",
+      "example": "const bridge = await connectPlaytestBridge(page, scenario);",
       "importPath": "@threenative/playtest/runner",
       "kind": "function",
       "overrides": [],
@@ -2345,13 +3243,14 @@
       "symbol": "connectPlaytestBridge"
     },
     {
+      "aliases": [],
       "constraints": ["the bridge must answer the handshake or the run fails"],
-      "example": "const bridge = await connectPlaytestBridge(page);",
+      "example": "const bridge = await connectPlaytestBridge(page, scenario);",
       "importPath": "@threenative/playtest/runner",
       "kind": "function",
       "overrides": [],
       "package": "@threenative/playtest",
-      "signature": "export async function connectPlaytestBridgeTransport( transport: IBridgeTransport, scenario: IPlaytestScenario, timeoutMs: number = bridgeWaitTimeoutMs(), ): Promise<IPlaytestBridgeClient | undefined> { … }",
+      "signature": "export async function connectPlaytestBridgeTransport( transport: IBridgeTransport, scenario: IPlaytestScenario, timeoutMs: number = bridgeWaitTimeoutMs(), target?: string, ): Promise<IPlaytestBridgeClient | undefined> { … }",
       "situations": [
         "run a browser scenario against a game",
         "inspect bridge diagnostics from a runner"
@@ -2361,6 +3260,7 @@
       "symbol": "connectPlaytestBridgeTransport"
     },
     {
+      "aliases": [],
       "constraints": ["the mailbox lifecycle must be disposed after the run"],
       "example": "const driver = new DesktopPlaytestDriver(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2377,6 +3277,7 @@
       "symbol": "DesktopPlaytestDriver"
     },
     {
+      "aliases": [],
       "constraints": ["paths stay inside the managed artifact directory"],
       "example": "const paths = deviceMailboxPaths(projectRoot);",
       "importPath": "@threenative/playtest/runner",
@@ -2393,6 +3294,7 @@
       "symbol": "DeviceBridgeTransport"
     },
     {
+      "aliases": [],
       "constraints": ["paths stay inside the managed artifact directory"],
       "example": "const paths = deviceMailboxPaths(projectRoot);",
       "importPath": "@threenative/playtest/runner",
@@ -2409,6 +3311,7 @@
       "symbol": "deviceMailboxPaths"
     },
     {
+      "aliases": [],
       "constraints": ["paths stay inside the managed artifact directory"],
       "example": "const paths = deviceMailboxPaths(projectRoot);",
       "importPath": "@threenative/playtest/runner",
@@ -2425,6 +3328,7 @@
       "symbol": "DeviceMailboxTransport"
     },
     {
+      "aliases": [],
       "constraints": ["paths stay inside the managed artifact directory"],
       "example": "const paths = deviceMailboxPaths(projectRoot);",
       "importPath": "@threenative/playtest/runner",
@@ -2441,6 +3345,7 @@
       "symbol": "deviceTimeoutDiagnostic"
     },
     {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -2457,6 +3362,7 @@
       "symbol": "discoverAdb"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2473,6 +3379,24 @@
       "symbol": "failedDiagnosticsAssertion"
     },
     {
+      "aliases": [],
+      "constraints": ["incomplete or malformed captures never become a successful empty report"],
+      "example": "summarizePipelineCapture(parsePipelineCapture(captureText));",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function formatPipelineSummary(summary: IPipelineSummary): string { … }",
+      "situations": [
+        "diagnose a slow shader-heavy launch from one browser or native capture",
+        "reconcile pipeline creation counts and compile timing"
+      ],
+      "summary": "Parse and explain bounded shader-compilation captures.",
+      "supersedes": [],
+      "symbol": "formatPipelineSummary"
+    },
+    {
+      "aliases": [],
       "constraints": ["invalid flags throw a named usage error"],
       "example": "const config = parseStandalonePlaytestArgs(argv);",
       "importPath": "@threenative/playtest/runner",
@@ -2489,6 +3413,7 @@
       "symbol": "formatUsage"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2505,6 +3430,7 @@
       "symbol": "handlePlaytestSignal"
     },
     {
+      "aliases": [],
       "constraints": ["generated scenarios must contain real assertions"],
       "example": "await initStandalonePlaytest(projectPath);",
       "importPath": "@threenative/playtest/runner",
@@ -2518,6 +3444,7 @@
       "symbol": "initStandalonePlaytest"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2534,6 +3461,7 @@
       "symbol": "isRuntimeReadout"
     },
     {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -2550,6 +3478,7 @@
       "symbol": "keyboardIsShown"
     },
     {
+      "aliases": [],
       "constraints": ["the mailbox lifecycle must be disposed after the run"],
       "example": "const driver = new DesktopPlaytestDriver(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2566,6 +3495,7 @@
       "symbol": "LocalDeviceMailbox"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2582,6 +3512,7 @@
       "symbol": "ManagedServerError"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2598,6 +3529,7 @@
       "symbol": "openPageAndConnectBridge"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2614,6 +3546,7 @@
       "symbol": "pageLifecycleDiagnostic"
     },
     {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -2630,6 +3563,24 @@
       "symbol": "parseAndroidConsole"
     },
     {
+      "aliases": [],
+      "constraints": ["Android evidence must name its target and transport"],
+      "example": "const adb = discoverAdb(process.env);",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function parseAndroidTouchViewport(output: string): IAndroidTouchViewport { … }",
+      "situations": [
+        "run a scenario on an Android emulator or device",
+        "parse Android console diagnostics"
+      ],
+      "summary": "Drive and inspect Android playtest transport.",
+      "supersedes": [],
+      "symbol": "parseAndroidTouchViewport"
+    },
+    {
+      "aliases": [],
       "constraints": ["simulator evidence does not claim physical-device proof"],
       "example": "const driver = new XcrunIosDriver(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2646,6 +3597,41 @@
       "symbol": "parseLaunchedPid"
     },
     {
+      "aliases": [],
+      "constraints": ["incomplete or malformed captures never become a successful empty report"],
+      "example": "summarizePipelineCapture(parsePipelineCapture(captureText));",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function parsePipelineCapture(input: string | unknown): IPipelineCapture { … }",
+      "situations": [
+        "diagnose a slow shader-heavy launch from one browser or native capture",
+        "reconcile pipeline creation counts and compile timing"
+      ],
+      "summary": "Parse and explain bounded shader-compilation captures.",
+      "supersedes": [],
+      "symbol": "parsePipelineCapture"
+    },
+    {
+      "aliases": [],
+      "constraints": ["incomplete or malformed captures never become a successful empty report"],
+      "example": "summarizePipelineCapture(parsePipelineCapture(captureText));",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function parsePipelineEventMarkers(text: string): IPipelineCaptureEvent[] { … }",
+      "situations": [
+        "diagnose a slow shader-heavy launch from one browser or native capture",
+        "reconcile pipeline creation counts and compile timing"
+      ],
+      "summary": "Parse and explain bounded shader-compilation captures.",
+      "supersedes": [],
+      "symbol": "parsePipelineEventMarkers"
+    },
+    {
+      "aliases": [],
       "constraints": ["invalid flags throw a named usage error"],
       "example": "const config = parseStandalonePlaytestArgs(argv);",
       "importPath": "@threenative/playtest/runner",
@@ -2662,8 +3648,9 @@
       "symbol": "parseStandalonePlaytestArgs"
     },
     {
+      "aliases": [],
       "constraints": ["the bridge must answer the handshake or the run fails"],
-      "example": "const bridge = await connectPlaytestBridge(page);",
+      "example": "const bridge = await connectPlaytestBridge(page, scenario);",
       "importPath": "@threenative/playtest/runner",
       "kind": "class",
       "overrides": [],
@@ -2678,6 +3665,7 @@
       "symbol": "PlaytestBridgeError"
     },
     {
+      "aliases": [],
       "constraints": ["invalid flags throw a named usage error"],
       "example": "const config = parseStandalonePlaytestArgs(argv);",
       "importPath": "@threenative/playtest/runner",
@@ -2694,6 +3682,7 @@
       "symbol": "PlaytestCliUsageError"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2710,8 +3699,9 @@
       "symbol": "playtestStepDrivesMovement"
     },
     {
+      "aliases": [],
       "constraints": ["the bridge must answer the handshake or the run fails"],
-      "example": "const bridge = await connectPlaytestBridge(page);",
+      "example": "const bridge = await connectPlaytestBridge(page, scenario);",
       "importPath": "@threenative/playtest/runner",
       "kind": "class",
       "overrides": [],
@@ -2726,6 +3716,7 @@
       "symbol": "PlaywrightTransport"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2742,6 +3733,7 @@
       "symbol": "preflightDisplay"
     },
     {
+      "aliases": [],
       "constraints": ["inspect the adapter name before claiming GPU proof"],
       "example": "const args = resolveBrowserArguments(undefined);",
       "importPath": "@threenative/playtest/runner",
@@ -2758,6 +3750,7 @@
       "symbol": "reconcileBrowserPointers"
     },
     {
+      "aliases": [],
       "constraints": ["an empty assertion set is a failure"],
       "example": "const scenario = recordToScenario(recording);",
       "importPath": "@threenative/playtest/runner",
@@ -2774,6 +3767,7 @@
       "symbol": "recordToScenario"
     },
     {
+      "aliases": [],
       "constraints": ["an empty assertion set is a failure"],
       "example": "const scenario = recordToScenario(recording);",
       "importPath": "@threenative/playtest/runner",
@@ -2790,6 +3784,7 @@
       "symbol": "requireAssertions"
     },
     {
+      "aliases": [],
       "constraints": ["inspect the adapter name before claiming GPU proof"],
       "example": "const args = resolveBrowserArguments(undefined);",
       "importPath": "@threenative/playtest/runner",
@@ -2806,6 +3801,7 @@
       "symbol": "resolveBrowserArguments"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2822,6 +3818,7 @@
       "symbol": "resolveManagedServerCommand"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2838,6 +3835,7 @@
       "symbol": "resolveManagedServerConfig"
     },
     {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -2854,6 +3852,7 @@
       "symbol": "rotatedTouchPosition"
     },
     {
+      "aliases": [],
       "constraints": ["the app bundle and device transport must be prepared"],
       "example": "await runAndroidPlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2870,6 +3869,7 @@
       "symbol": "runAndroidPlaytest"
     },
     {
+      "aliases": [],
       "constraints": ["the desktop host must be built before launching"],
       "example": "await runDesktopPlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2886,6 +3886,7 @@
       "symbol": "runDesktopPlaytest"
     },
     {
+      "aliases": [],
       "constraints": ["the app bundle and device transport must be prepared"],
       "example": "await runAndroidPlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2902,6 +3903,7 @@
       "symbol": "runDevicePlaytest"
     },
     {
+      "aliases": [],
       "constraints": ["identify simulator versus physical transport in evidence"],
       "example": "await runIosPlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2915,6 +3917,7 @@
       "symbol": "runIosPlaytest"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2931,6 +3934,7 @@
       "symbol": "runStandalonePlaytest"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2947,6 +3951,7 @@
       "symbol": "runStandalonePlaytests"
     },
     {
+      "aliases": [],
       "constraints": ["inspect the adapter name before claiming GPU proof"],
       "example": "const args = resolveBrowserArguments(undefined);",
       "importPath": "@threenative/playtest/runner",
@@ -2963,6 +3968,7 @@
       "symbol": "softwareAdapterName"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -2979,6 +3985,24 @@
       "symbol": "substituteManagedPort"
     },
     {
+      "aliases": [],
+      "constraints": ["incomplete or malformed captures never become a successful empty report"],
+      "example": "summarizePipelineCapture(parsePipelineCapture(captureText));",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function summarizePipelineCapture(capture: IPipelineCapture): IPipelineSummary { … }",
+      "situations": [
+        "diagnose a slow shader-heavy launch from one browser or native capture",
+        "reconcile pipeline creation counts and compile timing"
+      ],
+      "summary": "Parse and explain bounded shader-compilation captures.",
+      "supersedes": [],
+      "symbol": "summarizePipelineCapture"
+    },
+    {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -2995,6 +4019,24 @@
       "symbol": "tapCommand"
     },
     {
+      "aliases": [],
+      "constraints": ["Android evidence must name its target and transport"],
+      "example": "const adb = discoverAdb(process.env);",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function touchPositionForViewport( x: number, y: number, viewport: IAndroidTouchViewport, rotationOverride?: number, ): [number, number] { … }",
+      "situations": [
+        "run a scenario on an Android emulator or device",
+        "parse Android console diagnostics"
+      ],
+      "summary": "Drive and inspect Android playtest transport.",
+      "supersedes": [],
+      "symbol": "touchPositionForViewport"
+    },
+    {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -3011,6 +4053,7 @@
       "symbol": "touchRotationFromWindowDump"
     },
     {
+      "aliases": [],
       "constraints": ["paths stay inside the managed artifact directory"],
       "example": "const paths = deviceMailboxPaths(projectRoot);",
       "importPath": "@threenative/playtest/runner",
@@ -3027,6 +4070,7 @@
       "symbol": "validateDeviceEndpoint"
     },
     {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -3043,6 +4087,26 @@
       "symbol": "viewportPresentationCommands"
     },
     {
+      "aliases": [],
+      "constraints": ["Android evidence must name its target and transport"],
+      "example": "const adb = discoverAdb(process.env);",
+      "importPath": "@threenative/playtest/runner",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function viewportPresentationObserved( override: string | undefined, expected: string | undefined, physical: { … }",
+      "situations": [
+        "run a scenario on an Android emulator or device",
+        "parse Android console diagnostics",
+        "verify that an Android device presented the requested viewport",
+        "accept the physical panel size when `wm size` omits its override line"
+      ],
+      "summary": "Drive and inspect Android playtest transport.",
+      "supersedes": [],
+      "symbol": "viewportPresentationObserved"
+    },
+    {
+      "aliases": [],
       "constraints": ["Android evidence must name its target and transport"],
       "example": "const adb = discoverAdb(process.env);",
       "importPath": "@threenative/playtest/runner",
@@ -3059,6 +4123,7 @@
       "symbol": "viewportRestoreCommands"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -3075,6 +4140,7 @@
       "symbol": "writeCaptureProvenance"
     },
     {
+      "aliases": [],
       "constraints": ["missing observations and malformed assertions fail closed"],
       "example": "const report = await runStandalonePlaytest(options);",
       "importPath": "@threenative/playtest/runner",
@@ -3091,6 +4157,7 @@
       "symbol": "writeObservationArtifacts"
     },
     {
+      "aliases": [],
       "constraints": ["simulator evidence does not claim physical-device proof"],
       "example": "const driver = new XcrunIosDriver(options);",
       "importPath": "@threenative/playtest/runner",
@@ -3107,6 +4174,7 @@
       "symbol": "XcrunIosDriver"
     },
     {
+      "aliases": [],
       "constraints": ["use measured input rather than visual guesses"],
       "example": "const advice = adviseThreeRenderWorkload(input);",
       "importPath": "@threenative/playtest/three",
@@ -3123,8 +4191,9 @@
       "symbol": "adviseThreeRenderWorkload"
     },
     {
+      "aliases": [],
       "constraints": ["use the device transport selected by the runner"],
-      "example": "const connection = await connectDevicePlaytestBridge();",
+      "example": "const connection = connectDevicePlaytestBridge(bridge, endpoint);",
       "importPath": "@threenative/playtest/three",
       "kind": "function",
       "overrides": [],
@@ -3139,6 +4208,7 @@
       "symbol": "connectDevicePlaytestBridge"
     },
     {
+      "aliases": [],
       "constraints": ["install once before the runner connects"],
       "example": "const bridge = installThreePlaytestBridge(options);",
       "importPath": "@threenative/playtest/three",
@@ -3155,8 +4225,30 @@
       "symbol": "installThreePlaytestBridge"
     },
     {
+      "aliases": [],
+      "constraints": [
+        "reports counts and names only; it decides nothing about how the game looks",
+        "reports counts and names only; nothing here decides how the game looks",
+        "a walk that hits {@link SCENE_WALK_OBJECT_CAP} reports `truncated: true`"
+      ],
+      "example": "const room = observeSceneResources(scene, camera);",
+      "importPath": "@threenative/playtest/three",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/playtest",
+      "signature": "export function observeSceneResources(scene: Scene, camera: Camera): IPlaytestSceneObservation { … }",
+      "situations": [
+        "ask why a frame is black or washed out without opening a screenshot",
+        "ask what lights, materials and framing a running game actually has"
+      ],
+      "summary": "Observe the room a game is played in — lights, materials, fog, background and camera framing.",
+      "supersedes": [],
+      "symbol": "observeSceneResources"
+    },
+    {
+      "aliases": [],
       "constraints": ["use the device transport selected by the runner"],
-      "example": "const connection = await connectDevicePlaytestBridge();",
+      "example": "const connection = connectDevicePlaytestBridge(bridge, endpoint);",
       "importPath": "@threenative/playtest/three",
       "kind": "function",
       "overrides": [],
@@ -3171,8 +4263,9 @@
       "symbol": "readPlaytestEndpoint"
     },
     {
+      "aliases": [],
       "constraints": ["keep recorder limits within the documented caps"],
-      "example": "const physics = new ThreePlaytestPhysicsRecorder();",
+      "example": "const physics = new ThreePlaytestPhysicsRecorder(worldPhysics);",
       "importPath": "@threenative/playtest/three",
       "kind": "class",
       "overrides": [],
@@ -3187,53 +4280,581 @@
       "symbol": "ThreePlaytestPhysicsRecorder"
     },
     {
+      "aliases": [],
       "constraints": [
-        "Use the running WebGPU renderer and keep appearance choices in template render source."
+        "materials are never chosen here; the geometry carries groups, the game carries materials"
       ],
-      "example": "gradualBackground(...)",
-      "importPath": "@threenative/template/starter/src/render/effects/gradualBackground",
+      "example": "const geometry = createThreeGeometry(parseUAssetStaticMesh(buffer));",
+      "importPath": "@threenative/raw-unreal",
       "kind": "function",
       "overrides": [],
-      "package": "template:starter",
-      "signature": "function gradualBackground",
-      "situations": ["grade a background by distance"],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function createThreeGeometry(decoded: IDecodedUAssetStaticMesh): BufferGeometry { … }",
+      "situations": [
+        "build custom scene objects from Unreal mesh data instead of a whole mesh",
+        "hand a decoded Unreal mesh to a framework pipeline that owns materials itself"
+      ],
+      "summary": "Converts a decoded `.uasset` static mesh into a `THREE.BufferGeometry`, with one draw group per material section.",
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects gradualBackground.",
-      "symbol": "gradualBackground"
+      "symbol": "createThreeGeometry"
     },
     {
+      "aliases": [],
       "constraints": [
-        "Use the running WebGPU renderer and keep appearance choices in template render source."
+        "the fallback is three.js's own plain MeshStandardMaterial; every real material comes from the game"
       ],
-      "example": "lensDistortion(...)",
-      "importPath": "@threenative/template/starter/src/render/effects/lensDistortion",
+      "example": "const mesh = createThreeObject(decoded, { materialFactory: (d) => d.sections.map(() => barkMaterial) });",
+      "importPath": "@threenative/raw-unreal",
       "kind": "function",
       "overrides": [],
-      "package": "template:starter",
-      "signature": "function lensDistortion",
-      "situations": ["warp the image with radial lens distortion"],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function createThreeObject( decoded: IDecodedUAssetStaticMesh, options: IThreeAdapterOptions = { … }",
+      "situations": [
+        "put a raw .uasset mesh on screen without converting it to glTF first",
+        "key materials to a package's own sections by name or section index"
+      ],
+      "summary": "Converts a decoded `.uasset` static mesh into a renderable `THREE.Mesh` with provenance in `userData.unreal` and material selection left to the game's `materialFactory`.",
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects lensDistortion.",
-      "symbol": "lensDistortion"
+      "symbol": "createThreeObject"
     },
     {
+      "aliases": [],
       "constraints": [
-        "Use the running WebGPU renderer and keep appearance choices in template render source."
+        "zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing",
+        "a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry"
       ],
-      "example": "sparkle(...)",
-      "importPath": "@threenative/template/starter/src/render/effects/sparkle",
+      "example": "const payload = resolveBulkDataPayload(bytes, header, { zlib });",
+      "importPath": "@threenative/raw-unreal",
       "kind": "function",
       "overrides": [],
-      "package": "template:starter",
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function decompressBulkData( container: Uint8Array, codecs: { … }",
+      "situations": [
+        "read a UE4 editor static mesh whose source model lives in bulk data rather than inline",
+        "decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in"
+      ],
+      "summary": "Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.",
+      "supersedes": [],
+      "symbol": "decompressBulkData"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing"
+      ],
+      "example": "const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function decompressCompressedBuffer( buffer: ICompressedBuffer, codecs: IUAssetCodecs, ): Uint8Array { … }",
+      "situations": ["decompress the package-trailer payload that carries a UE5 MeshDescription"],
+      "summary": "Parses one UE5 `FCompressedBuffer` and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.",
+      "supersedes": [],
+      "symbol": "decompressCompressedBuffer"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing",
+        "a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry"
+      ],
+      "example": "const payload = resolveBulkDataPayload(bytes, header, { zlib });",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function findBulkDataHeaders( bytes: Uint8Array, layout: IPackageLayout, files: IUAssetBulkDataFiles = { … }",
+      "situations": [
+        "read a UE4 editor static mesh whose source model lives in bulk data rather than inline",
+        "decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in"
+      ],
+      "summary": "Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.",
+      "supersedes": [],
+      "symbol": "findBulkDataHeaders"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing"
+      ],
+      "example": "const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function findCompressedBufferOffsets(bytes: Uint8Array): number[] { … }",
+      "situations": ["decompress the package-trailer payload that carries a UE5 MeshDescription"],
+      "summary": "Parses one UE5 `FCompressedBuffer` and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.",
+      "supersedes": [],
+      "symbol": "findCompressedBufferOffsets"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every count is validated against its neighbors before any geometry is built"
+      ],
+      "example": "const description = parseMeshDescription(payload, offset);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function findMeshDescriptionOffsets(bytes: Uint8Array): number[] { … }",
+      "situations": [
+        "inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription"
+      ],
+      "summary": "Parses a serialized `FMeshDescription` — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.",
+      "supersedes": [],
+      "symbol": "findMeshDescriptionOffsets"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "only inline uncompressed blobs are found; compressed or external bulk data throws rather than guessing"
+      ],
+      "example": "const blob = parseRawMesh(bytes, offset);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function findRawMeshBlobs(bytes: Uint8Array): IRawMeshBlob[] { … }",
+      "situations": [
+        "read the source geometry of a Fab pack saved by UE 4.18 straight from its .uasset"
+      ],
+      "summary": "Parses one `FRawMesh` blob — the UE4.18-era source-model layout — validating that the fixed eighteen-array walk consumes the blob exactly and every count agrees with the wedge totals.",
+      "supersedes": [],
+      "symbol": "findRawMeshBlobs"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every count is validated against its neighbors before any geometry is built"
+      ],
+      "example": "const description = parseMeshDescription(payload, offset);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function looksLikeMeshDescription(bytes: Uint8Array, offset = 0): boolean { … }",
+      "situations": [
+        "inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription"
+      ],
+      "summary": "Parses a serialized `FMeshDescription` — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.",
+      "supersedes": [],
+      "symbol": "looksLikeMeshDescription"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the walk must consume the payload exactly; a short walk throws rather than returning the geometry it managed to read"
+      ],
+      "example": "const description = parseMeshDescriptionUe4(payload);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function looksLikeMeshDescriptionUe4(bytes: Uint8Array, offset = 0): boolean { … }",
+      "situations": ["decode the MeshDescription a UE 4.23-4.27 editor package keeps in bulk data"],
+      "summary": "Parses the UE4.2x serialization of `FMeshDescription` — fixed-order element containers, and a triangle container that trails the attribute sets rather than sitting with its siblings.",
+      "supersedes": [],
+      "symbol": "looksLikeMeshDescriptionUe4"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing",
+        "a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry"
+      ],
+      "example": "const payload = resolveBulkDataPayload(bytes, header, { zlib });",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function parseBulkDataHeader( bytes: Uint8Array, offset: number, layout: IPackageLayout, ): IBulkDataHeader { … }",
+      "situations": [
+        "read a UE4 editor static mesh whose source model lives in bulk data rather than inline",
+        "decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in"
+      ],
+      "summary": "Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.",
+      "supersedes": [],
+      "symbol": "parseBulkDataHeader"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "Oodle and LZ4 payloads require an injected codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing"
+      ],
+      "example": "const payload = decompressCompressedBuffer(parseCompressedBuffer(bytes, offset), { oodle });",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function parseCompressedBuffer(bytes: Uint8Array, offset = 0): ICompressedBuffer { … }",
+      "situations": ["decompress the package-trailer payload that carries a UE5 MeshDescription"],
+      "summary": "Parses one UE5 `FCompressedBuffer` and decompresses it block-by-block with the codecs the caller injected — uncompressed payloads are handled natively.",
+      "supersedes": [],
+      "symbol": "parseCompressedBuffer"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every count is validated against its neighbors before any geometry is built"
+      ],
+      "example": "const description = parseMeshDescription(payload, offset);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function parseMeshDescription(input: Uint8Array, offset = 0): IMeshDescription { … }",
+      "situations": [
+        "inspect the vertex, triangle, and polygon-group structure of a UE5 MeshDescription"
+      ],
+      "summary": "Parses a serialized `FMeshDescription` — element containers, allocation bit arrays, and attribute sets — into validated typed arrays, exactly consuming its byte range.",
+      "supersedes": [],
+      "symbol": "parseMeshDescription"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the walk must consume the payload exactly; a short walk throws rather than returning the geometry it managed to read"
+      ],
+      "example": "const description = parseMeshDescriptionUe4(payload);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function parseMeshDescriptionUe4(input: Uint8Array, offset = 0): IUe4MeshDescription { … }",
+      "situations": ["decode the MeshDescription a UE 4.23-4.27 editor package keeps in bulk data"],
+      "summary": "Parses the UE4.2x serialization of `FMeshDescription` — fixed-order element containers, and a triangle container that trails the attribute sets rather than sitting with its siblings.",
+      "supersedes": [],
+      "symbol": "parseMeshDescriptionUe4"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "only inline uncompressed blobs are found; compressed or external bulk data throws rather than guessing"
+      ],
+      "example": "const blob = parseRawMesh(bytes, offset);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function parseRawMesh(bytes: Uint8Array, offset = 0): IRawMeshBlob { … }",
+      "situations": [
+        "read the source geometry of a Fab pack saved by UE 4.18 straight from its .uasset"
+      ],
+      "summary": "Parses one `FRawMesh` blob — the UE4.18-era source-model layout — validating that the fixed eighteen-array walk consumes the blob exactly and every count agrees with the wedge totals.",
+      "supersedes": [],
+      "symbol": "parseRawMesh"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "only legacy-tag uncooked editor packages are read; IoStore (.utoc/.ucas), PAK archives, cooked render buffers, Nanite, and skeletal data throw UAssetError",
+        "the format layer never invents fallback geometry; every malformed or unsupported layout surfaces as UAssetError with its byte offset or counts"
+      ],
+      "example": "const decoded = parseUAssetStaticMesh(await file.arrayBuffer(), { oodle });",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function parseUAssetStaticMesh( input: ArrayBuffer | ArrayBufferView, options: IUAssetParseOptions = { … }",
+      "situations": [
+        "load a raw Unreal editor .uasset mesh in the browser without conversion",
+        "decode a Fab pack's UE4.18 static meshes straight from their .uasset files"
+      ],
+      "summary": "Parses a raw Unreal editor `.uasset` static mesh into validated, plain typed arrays — UE5 `FMeshDescription` payloads (including the Oodle-compressed package-trailer form) and the UE4.18-era `FRawMesh` source-model layout, with no interchange conversion at any step.",
+      "supersedes": [],
+      "symbol": "parseUAssetStaticMesh"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "returns undefined rather than guessing when the summary does not end on its own name table, or when the package uses a LegacyFileVersion this walk does not model"
+      ],
+      "example": "const layout = readPackageLayout(bytes); if (layout) readBulk(layout.bulkDataStartOffset);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function readPackageLayout(bytes: Uint8Array): IPackageLayout | undefined { … }",
+      "situations": ["find where a .uasset's export data and bulk-data region begin"],
+      "summary": "Walks the whole `FPackageFileSummary` for the offsets bulk data is addressed against — `TotalHeaderSize` and `BulkDataStartOffset` — and returns `undefined` when the walk cannot be trusted.",
+      "supersedes": [],
+      "symbol": "readPackageLayout"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "only the summary prefix is read; locating payload data is the payload readers' self-validating signature scans"
+      ],
+      "example": "const summary = readPackageSummary(bytes);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function readPackageSummary(bytes: Uint8Array): IPackageSummary { … }",
+      "situations": [
+        "report which engine generation a .uasset was written by before decoding it",
+        "reject a non-Unreal file with the stable INVALID_PACKAGE_TAG error"
+      ],
+      "summary": "Reads the fixed prefix of `FPackageFileSummary` — the legacy tag, engine versions, and the custom-version list — without walking the name map, export map, or dependency graph.",
+      "supersedes": [],
+      "symbol": "readPackageSummary"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "zlib payloads require an injected `zlib` codec; the package never bundles one, and a missing codec throws MISSING_CODEC instead of guessing",
+        "a payload written to a sibling file throws MISSING_BULK_DATA_FILE naming that file, rather than inventing geometry"
+      ],
+      "example": "const payload = resolveBulkDataPayload(bytes, header, { zlib });",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export function resolveBulkDataPayload( bytes: Uint8Array, header: IBulkDataHeader, options: { … }",
+      "situations": [
+        "read a UE4 editor static mesh whose source model lives in bulk data rather than inline",
+        "decompress the zlib-chunked bulk payload a UE4.2x package stores its MeshDescription in"
+      ],
+      "summary": "Reads the `FByteBulkData` headers an editor package serializes into its export data, and resolves each payload — inline, at the end of the package, or in a sibling `.ubulk`/`.uptnl` file whose bytes the caller supplies — decompressing `FArchive::SerializeCompressed` blocks.",
+      "supersedes": [],
+      "symbol": "resolveBulkDataPayload"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every parse, decompression, and geometry failure surfaces as this error; the loader never invents fallback geometry"
+      ],
+      "example": "catch (error) { if (error instanceof UAssetError) log(error.code, error.details); }",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export class UAssetError extends Error { … }",
+      "situations": [
+        "tell why a raw .uasset failed to load, by code, before any geometry is shown",
+        "branch on an unsupported Unreal layout instead of shipping broken geometry"
+      ],
+      "summary": "The error thrown for every malformed, truncated, or unsupported `.uasset` input, carrying a stable `code` and structured details instead of invented fallback geometry.",
+      "supersedes": [],
+      "symbol": "UAssetError"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "UE5 Oodle payloads require an `oodle` codec in the parse options; see README licensing"
+      ],
+      "example": "const mesh = new UAssetLoader(manager, { parse: { oodle } }).parse(data);",
+      "importPath": "@threenative/raw-unreal",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/raw-unreal",
+      "requires": ["npm i @threenative/raw-unreal"],
+      "signature": "export class UAssetLoader extends Loader { … }",
+      "situations": [
+        "load a .uasset asset in the browser with the standard three.js loader protocol",
+        "hand raw Fab-pack meshes to the framework's asset loading without a conversion step"
+      ],
+      "summary": "Loads a raw Unreal `.uasset` static mesh as a three.js loader — `load(url)` for the browser, `parse(data)` for bytes you already hold — with parse and adapter options passed through.",
+      "supersedes": [],
+      "symbol": "UAssetLoader"
+    },
+    {
+      "constraints": [
+        "Use the running WebGPU renderer and keep appearance choices in template render source."
+      ],
+      "example": "gradualBackground(...)",
+      "importPath": "@threenative/template/starter/src/render/effects/gradualBackground",
+      "kind": "function",
+      "overrides": [],
+      "package": "template:starter",
+      "signature": "function gradualBackground",
+      "situations": ["grade a background by distance"],
+      "supersedes": [],
+      "summary": "ThreeNative equivalent for realism-effects gradualBackground.",
+      "symbol": "gradualBackground",
+      "aliases": []
+    },
+    {
+      "constraints": [
+        "Use the running WebGPU renderer and keep appearance choices in template render source."
+      ],
+      "example": "lensDistortion(...)",
+      "importPath": "@threenative/template/starter/src/render/effects/lensDistortion",
+      "kind": "function",
+      "overrides": [],
+      "package": "template:starter",
+      "signature": "function lensDistortion",
+      "situations": ["warp the image with radial lens distortion"],
+      "supersedes": [],
+      "summary": "ThreeNative equivalent for realism-effects lensDistortion.",
+      "symbol": "lensDistortion",
+      "aliases": []
+    },
+    {
+      "constraints": [
+        "Use the running WebGPU renderer and keep appearance choices in template render source."
+      ],
+      "example": "sparkle(...)",
+      "importPath": "@threenative/template/starter/src/render/effects/sparkle",
+      "kind": "function",
+      "overrides": [],
+      "package": "template:starter",
       "signature": "function sparkle",
       "situations": ["add glints to bright highlights"],
       "supersedes": [],
       "summary": "ThreeNative equivalent for realism-effects sparkle.",
-      "symbol": "sparkle"
+      "symbol": "sparkle",
+      "aliases": []
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "rejects indices, channels, or material sections that disagree with the vertex count before any geometry is constructed"
+      ],
+      "example": "const geometry = createThreeGeometry(model.lods[0]);",
+      "importPath": "@threenative/ueformat",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/ueformat",
+      "requires": ["npm i @threenative/ueformat"],
+      "signature": "export function createThreeGeometry( lod: IUEModelLOD, adapterOptions: IThreeAdapterOptions = { … }",
+      "situations": [
+        "convert one Unreal mesh LOD into a three.js BufferGeometry by hand",
+        "build custom scene objects from Unreal mesh data instead of a whole model"
+      ],
+      "summary": "Converts one parsed Unreal mesh LOD into a `THREE.BufferGeometry` — coordinates, scale, winding, normals, tangents, UVs, vertex colours, morphs, skin weights, and material groups.",
+      "supersedes": [],
+      "symbol": "createThreeGeometry"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every material comes from the game through `materialFactory`; the fallback is three.js's own GLTFLoader default, a plain MeshStandardMaterial",
+        "parsed bones are exposed on `userData` but never bound into a THREE.SkinnedMesh — skeletal rendering is the game's job"
+      ],
+      "example": "const hero = createThreeObject(parseUEModel(buffer), { lodDistances: [0, 25, 50] });",
+      "importPath": "@threenative/ueformat",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/ueformat",
+      "requires": ["npm i @threenative/ueformat"],
+      "signature": "export function createThreeObject( model: IUEModelData, adapterOptions: IThreeAdapterOptions = { … }",
+      "situations": [
+        "put a mesh exported from an Unreal package on screen",
+        "load an Unreal static or skeletal mesh with LODs, sockets, and collision geometry"
+      ],
+      "summary": "Builds a renderable Three.js object — a `Group` for single-LOD models, a `THREE.LOD` for multi-LOD ones — from parsed `.uemodel` data, with collision geometry on `userData`.",
+      "supersedes": [],
+      "symbol": "createThreeObject"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "only UEFormat v10 UEMODEL files are accepted; anything else throws UEFormatError with the byte offset",
+        "ZSTD-compressed bodies require an injected `zstdDecoder`; the package never bundles a ZSTD implementation"
+      ],
+      "example": "const model = parseUEModel(await file.arrayBuffer());",
+      "importPath": "@threenative/ueformat",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/ueformat",
+      "requires": ["npm i @threenative/ueformat"],
+      "signature": "export function parseUEModel( input: ArrayBuffer | ArrayBufferView, options: IParseUEModelOptions = { … }",
+      "situations": [
+        "parse a mesh exported from an Unreal package without Unreal installed",
+        "inspect the LODs, skeleton, sockets, and collision inside a .uemodel file"
+      ],
+      "summary": "Parses a UEFormat v10 `.uemodel` body — the interchange format CUE4Parse and FModel export from Unreal packages — into validated, plain mesh data without building any Three.js objects.",
+      "supersedes": [],
+      "symbol": "parseUEModel"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "the summary reflects one already-parsed model; it does not read files itself"
+      ],
+      "example": "const summary = summarizeUEModel(parseUEModel(buffer));",
+      "importPath": "@threenative/ueformat",
+      "kind": "function",
+      "overrides": [],
+      "package": "@threenative/ueformat",
+      "requires": ["npm i @threenative/ueformat"],
+      "signature": "export function summarizeUEModel(model: IUEModelData): IUEModelSummary { … }",
+      "situations": [
+        "report what a UEFormat model contains without dumping its vertex data",
+        "validate a .uemodel file before building geometry from it"
+      ],
+      "summary": "Summarizes a parsed `.uemodel` — LOD, material, skeleton, collision, and unknown-attribute counts — without dumping vertex arrays, for logs, validation, and build reports.",
+      "supersedes": [],
+      "symbol": "summarizeUEModel"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "every parse and geometry failure surfaces as this error; nothing malformed is silently skipped"
+      ],
+      "example": "catch (error) { if (error instanceof UEFormatError) log(error.code, error.offset); }",
+      "importPath": "@threenative/ueformat",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/ueformat",
+      "requires": ["npm i @threenative/ueformat"],
+      "signature": "export class UEFormatError extends Error { … }",
+      "situations": [
+        "tell why a .uemodel file failed to load",
+        "report a malformed Unreal export with its byte offset instead of a generic error"
+      ],
+      "summary": "The error thrown for every malformed, truncated, or unsupported `.uemodel` input, carrying a stable `code` and the byte offset where validation stopped.",
+      "supersedes": [],
+      "symbol": "UEFormatError"
+    },
+    {
+      "aliases": [],
+      "constraints": [
+        "ZSTD-compressed bodies require an injected `zstdDecoder` in the parse options"
+      ],
+      "example": "const model = new UEFormatLoader(manager).parse(data);",
+      "importPath": "@threenative/ueformat",
+      "kind": "class",
+      "overrides": [],
+      "package": "@threenative/ueformat",
+      "requires": ["npm i @threenative/ueformat"],
+      "signature": "export class UEFormatLoader extends Loader { … }",
+      "situations": [
+        "load a .uemodel asset in the browser with the standard three.js loader protocol",
+        "hand a game's Unreal-exported meshes to the framework's asset loading"
+      ],
+      "summary": "Loads a `.uemodel` file as a Three.js loader — `load(url)` for the browser, `parse(data)` for bytes you already hold — with the parser and three-adapter options passed straight through.",
+      "supersedes": [],
+      "symbol": "UEFormatLoader"
     },
     {
+      "aliases": [],
       "constraints": [],
-      "example": "<DebugOverlay game={game} />",
+      "example": "<DebugOverlay />",
       "importPath": "@threenative/ui",
       "kind": "function",
       "overrides": [],
@@ -3248,6 +4869,7 @@
       "symbol": "DebugOverlay"
     },
     {
+      "aliases": [],
       "constraints": ["keep the portable game entry free of React DOM code"],
       "example": "<GameCanvas game={game} />",
       "importPath": "@threenative/ui",
@@ -3264,6 +4886,7 @@
       "symbol": "GameCanvas"
     },
     {
+      "aliases": [],
       "constraints": ["mark every control the player touches with data-tn-interactive"],
       "example": "<UiLayer><Hud /></UiLayer>",
       "importPath": "@threenative/ui",
@@ -3280,6 +4903,7 @@
       "symbol": "UiLayer"
     },
     {
+      "aliases": [],
       "constraints": ["use this hook only from the web UI entry"],
       "example": "const score = useGameState(game, (state) => state.score);",
       "importPath": "@threenative/ui",
@@ -3296,6 +4920,7 @@
       "symbol": "useGameState"
     },
     {
+      "aliases": [],
       "constraints": ["the game decides what each intent name means; it may ignore one"],
       "example": "const send = useUiIntent(); send(\"restart\");",
       "importPath": "@threenative/ui",
@@ -3312,8 +4937,9 @@
       "symbol": "useUiIntent"
     },
     {
+      "aliases": [],
       "constraints": ["returns undefined until the game publishes its first state"],
-      "example": "const score = useUiState((state) => state.score);",
+      "example": "const score = useUiState<GameState, number>((state) => state.score);",
       "importPath": "@threenative/ui",
       "kind": "function",
       "overrides": [],
@@ -3327,20 +4953,105 @@
       "supersedes": [],
       "symbol": "useUiState"
     },
+    {
+      "symbol": "WorldEnvironment",
+      "package": "three",
+      "importPath": "src/render/worldEnvironment.ts",
+      "kind": "class",
+      "signature": "class WorldEnvironment",
+      "summary": "The generated file that composes every lighting stage and prints TN_RENDER_CHAIN naming each one as applied or refused with a reason. It is the game's source, not the framework's — edit it.",
+      "situations": [
+        "turn a lighting or post-processing effect on or off",
+        "find out why an effect you enabled is not visible",
+        "change how the scene is lit, graded, or tonemapped",
+        "match a reference image's lighting"
+      ],
+      "example": "src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment",
+      "constraints": [
+        "Read the TN_RENDER_CHAIN line before assuming a stage ran: it names every stage as applied or dropped, with the reason it was dropped.",
+        "A stage reported `applied` can still be invisible if its own inputs are wrong — the chain reports whether it built, not whether you can see it.",
+        "Appearance belongs here, in generated game source. Nothing in packages/ decides how the scene looks."
+      ],
+      "overrides": [],
+      "supersedes": [],
+      "aliases": []
+    },
+    {
+      "symbol": "bloom",
+      "package": "three",
+      "importPath": "three/addons/tsl/display/BloomNode.js",
+      "kind": "function",
+      "signature": "bloom(node, strength, radius, threshold)",
+      "summary": "Glow around bright pixels. Already wired as the `bloom` stage.",
+      "situations": ["make a bright opening or a lamp glow", "bloom, glare, light spill"],
+      "example": "src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment",
+      "constraints": [
+        "Strength above ~0.3 on an interior washes the mid-tones; the reference-matching band is lower than it looks."
+      ],
+      "overrides": [],
+      "supersedes": [],
+      "aliases": []
+    },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "DenoiseNode(...)",
+      "example": "denoise(...)",
       "importPath": "three/addons/tsl/display/DenoiseNode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class DenoiseNode",
+      "signature": "function denoise",
       "situations": ["denoise a noisy screen-space pass"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects DenoiseNode.",
-      "symbol": "DenoiseNode"
+      "summary": "ThreeNative equivalent for realism-effects denoise.",
+      "symbol": "denoise",
+      "aliases": []
+    },
+    {
+      "symbol": "godrays",
+      "package": "three",
+      "importPath": "three/addons/tsl/display/GodraysNode.js",
+      "kind": "function",
+      "signature": "godrays(textureNode, light, shadowMap, params)",
+      "summary": "Raymarched shafts of light. Already wired as the `godRays` stage of the render chain; turn it on with `godraysEnabled` in src/render/postprocessing.ts.",
+      "situations": [
+        "draw a visible shaft of light through a window or a hole in a roof",
+        "god rays, sun shafts, light beams, crepuscular rays",
+        "make sunlight visible in dusty or misty air indoors",
+        "light a cave or a hall through an opening above",
+        "volumetric lighting without adding cone geometry"
+      ],
+      "example": "src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment",
+      "constraints": [
+        "Needs a shadow-casting DirectionalLight passed as `godraysLight`, and `renderer.shadowMap.enabled = true` — without the shadow map the stage refuses and the whole chain reports it dropped.",
+        "`godraysFloor` is what separates beams from fog: it subtracts out-of-beam scatter before `godraysIntensity` multiplies. Raising intensity with a floor near zero brightens the haze over the whole room instead of the beams.",
+        "Do not author cone geometry for beams. A hand-built additive cone draws its own silhouette and reads as a plastic tube; this stage is the supported route.",
+        "Measured band on an interior scene: density 0.7, floor 0.08, intensity 3.0, maxDensity 0.6. Above ~0.8 density the haze stops being confined to the beams and the room fogs."
+      ],
+      "overrides": [],
+      "supersedes": [],
+      "aliases": []
+    },
+    {
+      "symbol": "ao",
+      "package": "three",
+      "importPath": "three/addons/tsl/display/GTAONode.js",
+      "kind": "function",
+      "signature": "ao(scene, camera, resolution, radius, intensity)",
+      "summary": "Ground-truth ambient occlusion. Already wired as the `ambientOcclusion` stage; turn it on with `gtaoEnabled`.",
+      "situations": [
+        "darken the contact where an object meets the floor",
+        "stop props looking like they float",
+        "ambient occlusion, contact shadows, crevice darkening"
+      ],
+      "example": "src/render/postprocessing.ts — edit the preset it passes to WorldEnvironment",
+      "constraints": [
+        "Radius is in metres; a radius sized for a room reads as a smudge on a prop."
+      ],
+      "overrides": [],
+      "supersedes": [],
+      "aliases": []
     },
     {
       "constraints": [
@@ -3355,112 +5066,120 @@
       "situations": ["blur motion using a velocity buffer"],
       "supersedes": [],
       "summary": "ThreeNative equivalent for realism-effects motionBlur.",
-      "symbol": "motionBlur"
+      "symbol": "motionBlur",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "RecurrentDenoiseNode(...)",
+      "example": "recurrentDenoise(...)",
       "importPath": "three/addons/tsl/display/RecurrentDenoiseNode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class RecurrentDenoiseNode",
+      "signature": "function recurrentDenoise",
       "situations": ["denoise a noisy screen-space pass"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects RecurrentDenoiseNode.",
-      "symbol": "RecurrentDenoiseNode"
+      "summary": "ThreeNative equivalent for realism-effects recurrentDenoise.",
+      "symbol": "recurrentDenoise",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "SharpenNode(...)",
+      "example": "sharpen(...)",
       "importPath": "three/addons/tsl/display/SharpenNode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class SharpenNode",
+      "signature": "function sharpen",
       "situations": ["make the image sharper"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects SharpenNode.",
-      "symbol": "SharpenNode"
+      "summary": "ThreeNative equivalent for realism-effects sharpen.",
+      "symbol": "sharpen",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "SSAAPassNode(...)",
+      "example": "ssaaPass(...)",
       "importPath": "three/addons/tsl/display/SSAAPassNode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class SSAAPassNode",
+      "signature": "function ssaaPass",
       "situations": ["anti-alias still and moving scenes"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects SSAAPassNode.",
-      "symbol": "SSAAPassNode"
+      "summary": "ThreeNative equivalent for realism-effects ssaaPass.",
+      "symbol": "ssaaPass",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "SSGINode(...)",
+      "example": "ssgi(...)",
       "importPath": "three/addons/tsl/display/SSGINode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class SSGINode",
+      "signature": "function ssgi",
       "situations": ["add screen-space global illumination"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects SSGINode.",
-      "symbol": "SSGINode"
+      "summary": "ThreeNative equivalent for realism-effects ssgi.",
+      "symbol": "ssgi",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "SSRNode(...)",
+      "example": "ssr(...)",
       "importPath": "three/addons/tsl/display/SSRNode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class SSRNode",
+      "signature": "function ssr",
       "situations": ["add screen-space reflections"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects SSRNode.",
-      "symbol": "SSRNode"
+      "summary": "ThreeNative equivalent for realism-effects ssr.",
+      "symbol": "ssr",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "TemporalReprojectNode(...)",
+      "example": "temporalReproject(...)",
       "importPath": "three/addons/tsl/display/TemporalReprojectNode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class TemporalReprojectNode",
+      "signature": "function temporalReproject",
       "situations": ["reproject a temporal history"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects TemporalReprojectNode.",
-      "symbol": "TemporalReprojectNode"
+      "summary": "ThreeNative equivalent for realism-effects temporalReproject.",
+      "symbol": "temporalReproject",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "TRAANode(...)",
+      "example": "traa(...)",
       "importPath": "three/addons/tsl/display/TRAANode.js",
-      "kind": "class",
+      "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "class TRAANode",
+      "signature": "function traa",
       "situations": ["temporally resolve a moving image"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects TRAANode.",
-      "symbol": "TRAANode"
+      "summary": "ThreeNative equivalent for realism-effects traa.",
+      "symbol": "traa",
+      "aliases": []
     },
     {
       "constraints": [
@@ -3475,7 +5194,8 @@
       "situations": ["provide depth to screen-space effects"],
       "supersedes": [],
       "summary": "ThreeNative equivalent for realism-effects depth.",
-      "symbol": "depth"
+      "symbol": "depth",
+      "aliases": []
     },
     {
       "constraints": [
@@ -3490,22 +5210,24 @@
       "situations": ["provision velocity, normal, and depth render targets"],
       "supersedes": [],
       "summary": "ThreeNative equivalent for realism-effects mrt.",
-      "symbol": "mrt"
+      "symbol": "mrt",
+      "aliases": []
     },
     {
       "constraints": [
         "Use the running WebGPU renderer and keep appearance choices in template render source."
       ],
-      "example": "normal(...)",
+      "example": "normalView(...)",
       "importPath": "three/tsl",
       "kind": "function",
       "overrides": [],
       "package": "three",
-      "signature": "function normal",
+      "signature": "function normalView",
       "situations": ["provide normals to screen-space effects"],
       "supersedes": [],
-      "summary": "ThreeNative equivalent for realism-effects normal.",
-      "symbol": "normal"
+      "summary": "ThreeNative equivalent for realism-effects normalView.",
+      "symbol": "normalView",
+      "aliases": []
     },
     {
       "constraints": [
@@ -3520,7 +5242,8 @@
       "situations": ["provide motion vectors to temporal effects"],
       "supersedes": [],
       "summary": "ThreeNative equivalent for realism-effects velocity.",
-      "symbol": "velocity"
+      "symbol": "velocity",
+      "aliases": []
     },
     {
       "constraints": [
@@ -3535,8 +5258,35 @@
       "situations": ["provide motion vectors to temporal effects"],
       "supersedes": [],
       "summary": "ThreeNative equivalent for realism-effects VelocityNode.",
-      "symbol": "VelocityNode"
+      "symbol": "VelocityNode",
+      "aliases": []
+    }
+  ],
+  "notOwned": [
+    {
+      "guidance": "The framework owns no save/load system. Write a save module in your project's src/ using your own plain state shape (for example, ctx.state), and read agent-docs/gameplay-recipes.md for the template recipe.",
+      "id": "save-load",
+      "situations": [
+        "persist a player's progress between sessions",
+        "save player progress between sessions",
+        "load a saved game state"
+      ]
+    },
+    {
+      "guidance": "The framework owns no inventory system. Write inventory state in your project's src/ with plain objects under ctx.state, and read agent-docs/gameplay-recipes.md for the template recipe.",
+      "id": "inventory",
+      "situations": ["inventory system", "manage inventory contents"]
+    },
+    {
+      "guidance": "The framework owns no dialogue system. Write the conversation data and state in your project's src/; render it with the template UI (starter uses src/ui/), and read agent-docs/gameplay-recipes.md.",
+      "id": "dialogue",
+      "situations": ["NPC dialogue system", "write conversation choices for an NPC"]
+    },
+    {
+      "guidance": "The framework owns the optional authenticated transport seam at @threenative/core/net. Import connect with an HTTPS endpoint and a game-issued credential; it validates channels, message sizes, and bounded queues, but reliable overflow returns false and native qualification depends on the installed bridge (iOS remains unverified). Write authoritative replication, snapshots, prediction, interpolation, and rejoin policy in your project's src/ and server code.",
+      "id": "networked-multiplayer",
+      "situations": ["authoritative replication", "client prediction"]
     }
   ],
-  "version": 1
+  "version": 2
 }