@jgengine/shell 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -26,6 +26,122 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.37.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.37.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.34.0`; `@jgengine/github` is `0.24.0`.
+
+### Added
+
+- `bun run check:script-help` walks every `package.json` script that points into `scripts/`, runs each with `--help`, and fails when one errors, hangs over its own timeout, prints nothing, or when a script names a file the repo does not have. Script files that predate `--help` are listed in `scripts/script-help-baseline.json` and reported, so a new one cannot arrive undocumented.
+- `land`, `lane:close`, `lane:audit`, `ci-status` and `verify:fast` answer `--help` with their purpose, the flags they actually accept, one example and their exit codes, through one shared `scripts/script-help.ts`. No install, network or browser needed.
+- `RunLoop.present(count)` and `RunLoop.choose(id)` (`@jgengine/core/run/runLoop`) draw several next-run changes for a choice screen and adopt the pick, so a game that offers three relics does not compose `game/runDraft` beside the loop. `present` honours the same `after` gates and weights as the single draw and never repeats the change just played while alternatives remain; `choose` opens the next run around the pick and refuses an id the loop's table does not carry.
+- `installRunProbe` (`@jgengine/core/run/runLoop`) publishes `window.__jgengineRun` with the run in progress, what it carries, what it banked or lost, its best bank and the change it offers, so a capture or devtools read proves the loop is live instead of only imported.
+- `bun run find <pattern> [--in <dir>] [--kind ts,tsx] [--files]` answers a repository-wide search in about a second: ripgrep reads the tree once, honours `.gitignore` and never enters `node_modules`, `.git`, `.claude/worktrees` or build output. `--files` lists names by `--glob`, which is what a tree listing was for. Eight of the ten hard timeouts in three hours of lane transcripts were a recursive directory listing over this checkout (160 s, 3.0M files) against a 120 s limit, while every other call's p90 was 10.5 s.
+- `bun run check-recursive-walk` fails a `scripts/**` file or a lane document (`AGENTS.md`, `README.md`, every skill under `.claude/skills`) that ships a recursive directory listing, a `find` walk from a root, or `git ls-files` piped into per-file work; a required one carries `// walk-ok: <reason>`. It runs in CI through the scripts test shard.
+- `ModelConfig.variants` (`levels: [{ url, maxDistance? }]`, `hysteresis?`) declares ordered mesh detail levels for a model. The instanced prop path switches level per instance by distance to the camera, so near and far placements of one species keep their own mesh inside one batch cell. A model without `variants` draws exactly as before.
+- `createModelVariantSelector` (`@jgengine/core/world/modelLod`) returns the level index for an id at a distance, carrying hysteresis across each boundary (`DEFAULT_VARIANT_HYSTERESIS`, 6 m). `lodBandIndex` is now exported from `@jgengine/core/world/lod` and both the LOD scheduler and the selector read distances through it, so simulation throttling and mesh detail cannot disagree.
+- `syncStaticObjectSource` takes an optional `accept` predicate so one batch can split its instances between two instanced draws.
+- `InstancedScatter` now honours `ModelConfig.variants`: each species-chunk batch asks the same `createModelVariantSelector` the static prop path uses for every placement's level, and each level draws its own instanced meshes claiming only its placements. A chunk that holds near and far palms of one species draws both levels from the one batch; a model without `variants` draws exactly as before.
+- `writeScatterVariantLevel` (`@jgengine/shell` internal, `scatter/scatterVariants`) is the per-frame pass: it writes one level's composed matrices into a reserved slot array and returns `count`, allocating nothing per frame, and takes an optional `keep` predicate so a tier-distance or occlusion cull composes with level selection in one loop.
+- `terrain({ cellSize })` states ground density as world units per quad instead of a segment count, and derives the per-axis grid from `bounds` — the same `cellSize` on a bigger world spends more cells rather than stretching one count across it. `segments` still works and also takes `[x, z]` for a non-square grid. Setting both fails naming `cellSize`; a cell size over the 1,000,000-vertex ceiling fails with the cell/vertex numbers and the smallest `cellSize` that fits.
+- `shoot`, `drive` and `perf` take `--quality <low|medium|high|ultra>` and pin that graphics tier on the game page (`?quality=<tier>`). Each run reads the tier back from the shell (`data-jg-quality`) and fails when it is missing or different, so a capture or perf record always names the tier it measured. Every capture summary prints `tier <tier>`; `perf` echoes `perf: tier <tier>` and records it in `quality`.
+- The old `--quality draft|full` iteration mode is now the `--draft` switch (low tier, half viewport, `-draft` file names), on `shoot`, `drive` and `perf`; `perf:gate` takes `--draft` too. An unknown `--quality` value fails naming all four tiers.
+- `attributeTriangles` (`@jgengine/shell/render/triangleAttribution`) sums a scene's triangles by model and geometry with instance counts, and the devtools render probe publishes it as `probes["render/triangles"]` and the `render/triangles` system probe, so `debug_snapshot` names the object behind a heavy frame instead of only counting it. Harbor Heat read 1,021,671 triangles from 840 objects: the 640 m terrain at 300 segments (180,000), the `TwistedTree_2` foliage species (137,010 over 15 trees) and 93 instances of a 1,280-triangle NPC model.
+- `ShotSpec` and `resolveShotSpec` (`@jgengine/core/combat/shotSpec`) describe how a shot travels and what it does on contact as plain data: an instant trace or a travelling body with speed, gravity, drag, fuse, lifetime, radius and homing, plus contact damage, falloff, penetration, splash, ricochet and statuses. Every field but `delivery.kind` is optional with a documented default, so a plain gun is three lines and a grenade, mortar, arrow or hitscan explosive is the same shape with different numbers. `shotArc`, `shotFalloffAt` and `shotHitOutcome` are the one place trajectory, falloff and penetration are solved; `shotSpecFromStats` and `shotSpecFromWeapon` adapt existing item stats and weapon definitions once, and a splash radius or damage number never decides that a shot travels.
+- `ProjectileShotInput.spec` lets a caller state the spec directly; the projectile and weapon systems read the resolved spec at spawn, fuse, hitscan settle and damage application instead of classifying a shot.
+- A trace that carries splash now resolves its area damage at the contact point on the same tick, which is the #2272 hitscan-explosive configuration.
+- `bun run check:path-portability` fails a test that asserts one platform's path separator: a `\\` literal under `toContain`/`toEqual`/`toBe`/`includes`/`endsWith`, a bare `toContain("/")`, a POSIX root handed to `join`/`resolve`, or a literal compared with an OS path result. It reports the file, the line and the `join(...)` that replaces it. A genuinely single-platform assertion is named in `scripts/path-portability-allow.json` with a reason, printed on every run. This is the class behind #2301 (`toContain("proofs\\flows")`) and the `agent-worktree.test.ts` assertions that only pass on one OS.
+
+Verification:
+- `bun test scripts/check-path-portability.test.ts` - pass, including the pre-fix `proofs\\flows` line failing through the gate and the fixed one passing
+- `bun run check:path-portability` - ok, 3 allowlisted with reasons
+- `bun test scripts/agent-worktree.test.ts scripts/shot-metrics.test.ts scripts/lane-audit.test.ts` - pass
+
+### Changed
+
+- Merge pull request #2309 from Noisemaker111/agent/lane-path-portability
+- `bun run land` hands the PR over instead of waiting for it: it pushes, opens or updates the PR, runs `--verify`, arms auto-merge and exits in seconds, printing the PR URL and `bun run ci:status --pr <n>`. A trivial change spent 5m09s inside `land`'s own poll loop, and one night's lanes spent 449 minutes watching CI. `--watch` still lands the old way and says it is deprecated.
+- `bun run land:queue` is the only process that waits for CI. It lands ready PRs into `beta` in readiness order (auto-merge armed, else the `land:queue` label), rebases a branch whose base moved in a throwaway worktree so a moved base costs one CI run instead of two, waits once per PR and prints one line per PR with its wait time and run id. A lane hands off by running `bun run land`; it never rebases, labels or waits.
+- `bun run lane:close` ends a lane in one command. It stages the worktree's tracked and new files (ignored ones such as `.scratch/` stay out), takes the commit message from the branch's own `changes/` fragment, writes that fragment from the commit summary when the diff has none, pushes, opens or updates the PR with the fragment as the body, arms auto-merge, and prints the PR URL and `bun run ci:status --pr <n>`. One lane's last 20 calls were 13 of commit, push, rebase and PR choreography; this replaces them with one. `bun run land --commit` does the same for a lane that skips `lane:close`, and a clean tree lands as it did before.
+- `bun run bg:run -- <cmd>` starts a long command and returns its id at once; `bun run bg:await <id>` blocks on that task's exit file as an event, then prints its whole output and its exit code. It replaces waiting out a `.out` file with guessed intervals — one lane spent 10 minutes of `Start-Sleep` calls watching a capture it had already started. A runner that dies is answered rather than waited on forever.
+- `--commit` prints every path it will commit before committing, and refuses the ones a lane did not author: a scratch artifact, a path git ignores, a lockfile staged without its `package.json` manifest, and a new `changes/` fragment whose name is not part of the branch's name. `--allow <path>` keeps one refused file on purpose. The first replay committed a test-written `changes/agent-lane-x.md` and this checkout's shared-install `bun.lock` drift; both are refused now, with the file list printed either way.
+- A capture at a non-default tier writes its tier into the file name (`-low`, `-medium`, `-ultra`), so an ultra shot cannot overwrite the high one it was compared against.
+
+Root cause: `--quality` carried the iteration preset, not the graphics tier, so a culling lane that asked for ultra got the game's default `high` on both sides of its comparison and could not prove a tier claim.
+
+### Fixed
+
+- `verify:fast`, `land` and `lane:close` refuse a checkout with no `node_modules` up front: they print the missing marker, the exact fix (`bun install` in this checkout, or `bun run agent:bootstrap`) and exit 78, instead of a `command not found` or a module error from a test file. A genuine failure still exits on its own code.
+- `lane:audit --cwd` finds the lane whose own tool calls name that worktree, and prints `attributed ses_… (N references to …)`. Ambiguous ties name their candidates and pick the worst-waiting one; no candidate at all exits non-zero naming the path it searched, so `--fail-on-waiting` has a lane to judge instead of an empty table.
+- `land` builds the PR body only from `changes/` fragments its own `git diff origin/beta...HEAD` adds, prints a line for every fragment it ignores, and falls back to the branch's commit subjects.
+
+Root cause: a subagent session stores the directory of the agent that spawned it, so a lane was invisible to its own audit; `changes/` is shared by every lane on the branch, so "newest fragment" was free to be a stranger's note.
+
+Before: `lane:audit --cwd …\lane-wait-audit` exited 1 with "no child sessions", and a body built from a stray `changes/` fragment claimed work the diff did not contain.
+After: `lane:audit: attributed ses_e94f3aeedffe2CCMsTlrzgvez5 (136 references to …\lane-wait-audit)`, and `land: ignoring changes/scratch-leftover.md: this branch's diff against origin/beta does not add it`.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts scripts/land.test.ts` — pass
+- `bun run verify:fast` — pass
+- `bun run lane:audit --cwd <the real lane worktree> --hours 6` — attributed that lane by 136 references
+- `lane:audit` classifies a call by what it runs, not by the text inside its arguments: `rg`, `grep`, `Select-String`, `findstr`, `Get-Content`, `cat`, `echo`, `Write-Output` and `git` (any subcommand) never count as a sleep or a CI watch, and quoted arguments are stripped before matching. A lane that greps for `Start-Sleep` or writes a PR body about `gh run watch` no longer records waiting it never did.
+- Catches the waits it used to miss: `Start-Sleep` under `powershell -Command`/`pwsh -c`/`bash -lc`, `cmd /c "timeout /t"`, `Thread.sleep`, `Atomics.wait`, `Bun.sleep`, and `gh pr checks` inside a `for`/`while` loop.
+
+Over the last 40 hours (209 lanes): sleep 1066.6 -> 1068.7 minutes, CI watch 421.8 -> 421.3 minutes. 15 calls stopped counting as waits, one real `Start-Sleep -Seconds 150` started counting.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts scripts/land.test.ts` — pass
+- `bun run lane:audit --json --hours 40` before and after, compared per command
+- `lane:close` reads `calls` as the count it is, takes waits from a new `waits` list in `lane:audit --json`, and refuses an unfamiliar audit shape with `the audit output shape changed: <field> is <type>, expected <type> (keys seen: …)` instead of a TypeError. Exit codes unchanged: a sleep or CI watch is 2, `--waive` records the reason, no percentage thresholds.
+
+Root cause: `lane:audit --json` had always reported `calls` as a number, while `lane:close` held it as a list of call objects; nothing read the real document until lane attribution started returning a lane, so the gate that judges a finishing lane crashed on the first lane that had one.
+
+Before: `lane:close` landed the PR, then died with `source.filter is not a function` at `waitingGate`.
+After: the same captured output is judged, the waits are listed, and the lane gets exit 2 with a report skeleton.
+
+Verification:
+- `bun test scripts/lane-audit.test.ts scripts/lane-close.test.ts` — pass, including the captured-output fixture
+- `bun run verify:fast` — pass
+- `shoot --url ... --look` now sends the aim to the page it captures, so a lane can measure a branch on a dev runner it started itself. The read-back stays: a page that reports no applied aim still fails the capture instead of returning a plausible wrong view, and a page that applies `--param look=` itself can report it on `data-jg-look` or `window.__jgLook`. `--site --look` is refused at the command line, naming the `--url` form that works.
+- `check:no-blocking-wait` judges code that waits, not prose that describes waiting. In `packages/<pkg>/src/meta` (the changelog mirror and its neighbours) single- and double-quoted text and comments are masked before matching, so a release note reading "one lane spent 10 minutes of `Start-Sleep`" no longer fails the gate; a command in a template literal still fails, and every other `scripts/**` path keeps the strict rule where a quoted command is a real finding. The 0.37.0 release cut failed `types` on `packages/core/src/meta/changelog.ts:46,55,56` with exactly that false positive.
+- `@jgengine/rapier` now accumulates `step(dt)` into its fixed substeps instead of stepping once per call with `fixedDt` as the timestep. A 1 s move covered 0.5 s of simulated time at 30 fps and 2.4 s at 144 fps; it now covers 1 s at either rate, matching `PhysicsWorld` and the `PhysicsBackend` contract.
+- `PhysicsWorld` bounds-floor friction is Coulomb (`friction × g × dt`) like contact friction, not a 60 Hz multiplicative brake: a crate sliding at 4 m/s travelled 0.165 m on the world floor and 0.970 m on a floor collider, and now travels 0.967 m on both.
+- Player and character-controller gravity integrate trapezoidally, so a jump reaches `v²/2g` at any frame rate: the default jump peaked at 0.933 m at 30 fps and 1.026 m at 144 fps, and now at 1.050 m for both.
+
+## 0.36.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.36.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.33.0`; `@jgengine/github` is `0.23.0`.
+
+### Added
+
+- `createAgentSystem` (`@jgengine/core/agents/system`) takes a game's needs, options, mood weights, members and
+  schedules once and returns a running cast: one `tick(dt)` for everyone, one target selector for the whole system,
+  a fallback declared once, and a plain-JSON `save()`/`load()` that rides the game's own save.
+- `--quick` on `bun run shoot` and `bun run drive` is the 960x540 iteration preset: one settled frame (a 2s settle window in drive), no video, no perf pass, written as `<name>-quick.png` and timed on its own line. It refuses a 1600x900 pixel claim, a frame-time claim, a non-desktop device and a recording flag by name instead of producing weaker evidence; full stays the default for PR shots. On a warm daemon a two-shot `drive` of ember-command went 9.3s to 8.2s and 4316KB to 1383KB of PNG.
+- `createPlayScript` / `runPlayScript` (`@jgengine/shell/play`) play a real `PlayableGame` headlessly from a tick-based script: `move`, `aim`, `fire`, `use`, `wait` and `command` steps plus `setup`/`onTick` hooks, `expect` assertions read after setup and on their own tick, a tick timeline, and an FNV digest for replay comparison. It replays the shell's own frame pipeline — held movement through the walk controller, a bound action resolving to its command on press and repeat, interact prompts, hotbar — so a script proves the same code path a player's hands do. No browser, no wall clock, fixed `dt`.
+- `bun run simulate <game> <script>` runs a committed `<game>/scripts/*.play.ts` against a game under `./Games`, prints the timeline, names a failed assertion and exits 1. It merges the game's own tsconfig `paths` with this checkout's source packages, so the game imports and the engine under test are one module graph.
+- `HeadlessRunner.aim()` steers the walk controller mid-run; `HeadlessRunnerOptions` gains `seed` (deterministic `ctx.rng`) and `collision` (the shell's voxel config, previously dropped on the headless path).
+
+Play scripts prove play in seconds instead of minutes of browser play, and the three proofs land beside their games: Scrap Signal (an enemy takes damage and closes in), Beacon Bastion (a composed wave is reached, its bounty scales, a boss phase flips) and Harbor Heat (heat is witness-gated, the search area is set, a courier is swept).
+
+### Changed
+
+- The graphics quality tier now costs what it claims on the render path. A tier's post chain renders at its own resolution scale (`low` 0.7, `medium` 0.85, `high`/`ultra` native) instead of always at the canvas size, and a game's authored `shadowMapSize` and `cascades` are a ceiling the tier caps rather than a value it ignored — every reference game authored 3 cascades and 1024/2048, so no tier changed a shadow before this. `low` and `medium` also stretch the far cascades' refresh interval, and the smallest caster worth a depth draw grows as the map shrinks. `high` and `ultra` keep native resolution, the authored shadow sizes and the measured cadence, so their frames are unchanged.
+- Measured uncapped at 1600x900: whole-frame draws at `low` fell 53% in harbor-heat (515 → 242) and 63% in drift-foundry (1,098 → 408), with the shadow pass there down from 911 ms to 344 ms over a 6 s window; `high` and `ultra` held their draw counts.
+
+### Fixed
+
+- Terrain build no longer scans every road and path segment for every vertex. A baked path corridor, a draped road and a painted polyline region each answer "how far is this point?" from a precomputed segment grid, so Scrap Signal's world build drops from 16.6 s to 0.51 s on the same machine and its longest boot stall from 11.6–18.4 s to 1.2 s. Sampled heights and palettes are bit-identical to the previous full scan, and `withPathProfiles` still composes profiles in order.
+- Load-time shader warmup compiles against the render state the first frame actually draws with. A scene whose post chain renders into its own buffer was linking two programs per material, one linear untone-mapped set the frame draws and one canvas set nothing ever drew; the cover no longer waits for the second set. Harbor Heat links 84 programs to 58 and Scrap Signal 124 to 83 before the cover lifts, with no visual change.
+
+### Performance
+
+- `createTerrainPaletteSampler` (`@jgengine/core/world/terrain`) tests only the material regions whose painted core or blend ring covers a sample, so a world with hundreds of authored regions no longer pays for all of them at every vertex.
+
 ## 0.35.0
 
 ### Migrate

package/dist/GamePlayerShell.js

@@ -242,6 +242,15 @@ export function GamePlayerShell({ playable, multiplayer: rawMultiplayer = null,
             delete document.documentElement.dataset.jgPresentation;
         };
     }, [playable]);
+    // The tier the shell actually resolved, so a capture can prove which one it measured.
+    useEffect(() => {
+        if (typeof document === "undefined")
+            return;
+        document.documentElement.dataset.jgQuality = graphics.quality;
+        return () => {
+            delete document.documentElement.dataset.jgQuality;
+        };
+    }, [graphics.quality]);
     useEffect(() => {
         if (ctx === null || typeof document === "undefined")
             return;

package/dist/devtools/DevtoolsOverlay.js

@@ -3,6 +3,7 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { devtools, } from "@jgengine/core/devtools/devtools";
 import { heavyModels } from "../render/modelLoad.js";
+import { triangleProbe } from "../render/triangleAttribution.js";
 import { buildLeanReport } from "./devtoolsReports.js";
 import { PerfPanel } from "./PerfPanel.js";
 import { LogsPanel } from "./LogsPanel.js";
@@ -19,8 +20,41 @@ const RENDER_PROBE_FRAME_PRIORITY = -10;
 export function DevtoolsRendererProbe() {
     useEffect(() => devtools.probes.register("heavyModels", () => heavyModels()), []);
     const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
     const lastSampleAt = useRef(0);
     useEffect(() => devtools.probes.register("shaderPrograms", () => gl.info.programs?.length ?? 0), [gl]);
+    useEffect(() => {
+        // One walk serves the counters, the state line and the probe: a snapshot reads the same frame.
+        const probe = triangleProbe(scene);
+        let cachedAt = 0;
+        let cached = probe.table();
+        const read = () => {
+            const now = performance.now();
+            if (now - cachedAt > 500) {
+                cachedAt = now;
+                cached = probe.table();
+            }
+            return cached;
+        };
+        const disposeProbe = devtools.probes.register("render/triangles", () => read());
+        const disposeSystem = devtools.probes.registerSystem("render/triangles", {
+            counters: () => {
+                const { triangles, casters, lines } = read();
+                return { triangles, casters, lines: lines.length };
+            },
+            state: () => {
+                const { triangles, casters, lines } = read();
+                const top = lines[0];
+                return top === undefined
+                    ? `${triangles} triangles`
+                    : `${triangles} triangles · casters ${casters} · top ${top.label} ${top.triangles}`;
+            },
+        });
+        return () => {
+            disposeProbe();
+            disposeSystem();
+        };
+    }, [scene]);
     useEffect(() => {
         // three resets gl.info after every render() call, so with a multi-pass
         // composer the counters only ever hold the last fullscreen pass. Own the

package/dist/render/CascadedShadows.d.ts

@@ -21,21 +21,40 @@ export declare const SHADOW_DISTANCE_BY_MAP_SIZE: Readonly<Record<number, number
  */
 export declare function resolveShadowDistance(profile?: GraphicsProfile, authored?: number): number;
 /**
- * Frames between shadow-map refreshes for the cascade at `index`, nearest first. The nearest
- * cascades move several texels per frame and refresh every frame; the far ones cover ground a
- * slow camera barely crosses, so they pay the depth pass a half or a quarter as often.
+ * Frames between shadow-map refreshes for the cascade at `index`, nearest first.
+ * @deprecated Cascades refresh on a texel step; see {@link refreshCascadesOnTexelStep}.
  * @internal
  */
 export declare function cascadeShadowCadence(index: number, cascades: number): number;
+/** Depth-axis steps worth of a texel the snapped light may drift before it re-anchors. */
+export declare const CASCADE_DEPTH_STEP_TEXELS = 8;
+/** World size of one texel on a cascade's own shadow map. @internal */
+export declare function cascadeTexelSize(light: THREE.DirectionalLight): number;
 /**
- * Set each cascade's shadow refresh policy for `frame`. A cascade that is not due keeps both
- * its matrix and its map from the last refresh, so the pair stays consistent with itself.
- * `refreshScale` stretches the far cascades' interval further on a tier whose maps are cheap
- * enough to lag; `1` is the cadence the cascade rig was measured with. The nearest cascade always
- * refreshes every frame: it is the one a moving camera crosses fastest.
+ * The cascade centre rounded to whole texels of its own shadow map, in the light's orientation.
+ * Lateral texels are what the eye sees move; the depth axis is coarser because it only shifts the
+ * ortho depth window. @internal
+ */
+export declare function snapCascadeCenter(center: THREE.Vector3, lightDirection: THREE.Vector3, texelSize: number, depthTexels?: number): THREE.Vector3;
+/** Per-frame cascade refresh bookkeeping: the centre each map was last rendered with. */
+export interface CascadeRefreshState {
+    centres: THREE.Vector3[];
+    /** Depth passes requested since the state was created. */
+    refreshes: number;
+    /** Leading cascades that refresh every frame whatever the snap says: a moving caster must not freeze. */
+    floor: number;
+}
+/** @internal */
+export declare function createCascadeRefreshState(floor?: number): CascadeRefreshState;
+/**
+ * Pin each cascade's light to its texel grid and request a depth pass where that grid step moved
+ * the light, plus every frame for the `floor` nearest cascades. `floor: 1` keeps the cascade holding
+ * the player live so a walking actor's shadow follows it while the camera stands still; the far
+ * cascades skip until the camera crosses a texel. An unmoved light keeps `autoUpdate` off, so the
+ * map and the sampling matrix always stay the pair they were rendered as.
  * @internal
  */
-export declare function scheduleCascadeRefresh(lights: readonly THREE.DirectionalLight[], frame: number, refreshScale?: number): void;
+export declare function refreshCascadesOnTexelStep(lights: readonly THREE.DirectionalLight[], lightDirection: THREE.Vector3, state: CascadeRefreshState): number;
 /**
  * Cascaded shadow maps for one directional light — outdoor scenes keep shadows past a
  * single 40-unit ortho frustum. Uses three.js `CSM` (shader injection on standard materials).

package/dist/render/CascadedShadows.js

@@ -2,7 +2,7 @@ import { useFrame, useThree } from "@react-three/fiber";
 import { useEffect, useRef } from "react";
 import * as THREE from "three";
 import { CSM } from "three/examples/jsm/csm/CSM.js";
-import { resolveCascadeCount, resolveShadowMapSize, shadowRefreshScale } from "./shadowTiers.js";
+import { resolveCascadeCount, resolveShadowMapSize } from "./shadowTiers.js";
 /** @internal Default PCF penumbra in shadow-map texels for configured directional lights. */
 export const DEFAULT_SHADOW_RADIUS = 1.25;
 /** @internal Reach in metres used when neither the game nor a graphics profile sets one. */
@@ -33,9 +33,8 @@ export function resolveShadowDistance(profile, authored) {
     return Math.min(profile.drawDistance, reach);
 }
 /**
- * Frames between shadow-map refreshes for the cascade at `index`, nearest first. The nearest
- * cascades move several texels per frame and refresh every frame; the far ones cover ground a
- * slow camera barely crosses, so they pay the depth pass a half or a quarter as often.
+ * Frames between shadow-map refreshes for the cascade at `index`, nearest first.
+ * @deprecated Cascades refresh on a texel step; see {@link refreshCascadesOnTexelStep}.
  * @internal
  */
 export function cascadeShadowCadence(index, cascades) {
@@ -45,24 +44,70 @@ export function cascadeShadowCadence(index, cascades) {
         return index === 0 ? 1 : 2;
     return 2 ** (index - (cascades - 3));
 }
+/** Depth-axis steps worth of a texel the snapped light may drift before it re-anchors. */
+export const CASCADE_DEPTH_STEP_TEXELS = 8;
+const UP = new THREE.Vector3(0, 1, 0);
+const orientMatrix = new THREE.Matrix4();
+const inverseOrient = new THREE.Matrix4();
+const localCentre = new THREE.Vector3();
+/** World size of one texel on a cascade's own shadow map. @internal */
+export function cascadeTexelSize(light) {
+    const shadowCamera = light.shadow.camera;
+    const span = Math.max(shadowCamera.right - shadowCamera.left, shadowCamera.top - shadowCamera.bottom);
+    return span / Math.max(1, light.shadow.mapSize.x);
+}
 /**
- * Set each cascade's shadow refresh policy for `frame`. A cascade that is not due keeps both
- * its matrix and its map from the last refresh, so the pair stays consistent with itself.
- * `refreshScale` stretches the far cascades' interval further on a tier whose maps are cheap
- * enough to lag; `1` is the cadence the cascade rig was measured with. The nearest cascade always
- * refreshes every frame: it is the one a moving camera crosses fastest.
+ * The cascade centre rounded to whole texels of its own shadow map, in the light's orientation.
+ * Lateral texels are what the eye sees move; the depth axis is coarser because it only shifts the
+ * ortho depth window. @internal
+ */
+export function snapCascadeCenter(center, lightDirection, texelSize, depthTexels = CASCADE_DEPTH_STEP_TEXELS) {
+    const texel = texelSize > 0 ? texelSize : 1;
+    orientMatrix.lookAt(new THREE.Vector3(), lightDirection, UP);
+    inverseOrient.copy(orientMatrix).invert();
+    localCentre.copy(center).applyMatrix4(inverseOrient);
+    localCentre.x = Math.round(localCentre.x / texel) * texel;
+    localCentre.y = Math.round(localCentre.y / texel) * texel;
+    const depth = texel * Math.max(1, Math.floor(depthTexels));
+    localCentre.z = Math.round(localCentre.z / depth) * depth;
+    return localCentre.applyMatrix4(orientMatrix);
+}
+/** @internal */
+export function createCascadeRefreshState(floor = 1) {
+    return { centres: [], refreshes: 0, floor };
+}
+/**
+ * Pin each cascade's light to its texel grid and request a depth pass where that grid step moved
+ * the light, plus every frame for the `floor` nearest cascades. `floor: 1` keeps the cascade holding
+ * the player live so a walking actor's shadow follows it while the camera stands still; the far
+ * cascades skip until the camera crosses a texel. An unmoved light keeps `autoUpdate` off, so the
+ * map and the sampling matrix always stay the pair they were rendered as.
  * @internal
  */
-export function scheduleCascadeRefresh(lights, frame, refreshScale = 1) {
-    const stretch = Math.max(1, Math.floor(refreshScale));
+export function refreshCascadesOnTexelStep(lights, lightDirection, state) {
+    let refreshed = 0;
     for (let index = 0; index < lights.length; index += 1) {
-        const shadow = lights[index].shadow;
-        const base = cascadeShadowCadence(index, lights.length);
-        const cadence = base === 1 ? 1 : base * stretch;
-        shadow.autoUpdate = cadence === 1;
-        if (cadence > 1)
-            shadow.needsUpdate = frame % cadence === 0;
+        const light = lights[index];
+        const snapped = snapCascadeCenter(light.position, lightDirection, cascadeTexelSize(light));
+        const known = state.centres[index];
+        const moved = known === undefined || known.distanceToSquared(snapped) > 1e-12;
+        const refresh = moved || index < state.floor;
+        light.position.copy(snapped);
+        light.target.position.copy(snapped).add(lightDirection);
+        light.shadow.autoUpdate = refresh;
+        light.shadow.needsUpdate = false;
+        if (moved) {
+            if (known === undefined)
+                state.centres[index] = snapped.clone();
+            else
+                known.copy(snapped);
+        }
+        if (refresh) {
+            refreshed += 1;
+            state.refreshes += 1;
+        }
     }
+    return refreshed;
 }
 function isStandardMaterial(mat) {
     return mat instanceof THREE.MeshStandardMaterial || mat instanceof THREE.MeshPhysicalMaterial;
@@ -80,12 +125,12 @@ export function CascadedShadows({ entry, profile, modulation, }) {
     const camera = useThree((s) => s.camera);
     const scene = useThree((s) => s.scene);
     const csmRef = useRef(null);
-    const frameRef = useRef(0);
+    const lightDirectionRef = useRef(new THREE.Vector3());
+    const refreshRef = useRef(createCascadeRefreshState());
     const baseIntensity = entry.intensity ?? 1.3;
     const maxFar = resolveShadowDistance(profile, entry.shadowMaxFar);
     const shadowMapSize = resolveShadowMapSize(profile, entry.shadowMapSize);
     const cascades = Math.max(2, Math.min(4, Math.floor(resolveCascadeCount(profile, entry.cascades))));
-    const refreshScale = shadowRefreshScale(shadowMapSize);
     useEffect(() => {
         const lightDirection = new THREE.Vector3(-entry.position[0], -entry.position[1], -entry.position[2]);
         if (lightDirection.lengthSq() < 1e-8)
@@ -112,6 +157,8 @@ export function CascadedShadows({ entry, profile, modulation, }) {
         }
         const unbind = bindCsmMaterials(scene, csm);
         csmRef.current = csm;
+        lightDirectionRef.current.copy(lightDirection);
+        refreshRef.current = createCascadeRefreshState();
         return () => {
             unbind();
             releaseCascadedShadows(csm);
@@ -145,7 +192,7 @@ export function CascadedShadows({ entry, profile, modulation, }) {
         }
         csm.camera = camera;
         csm.update();
-        scheduleCascadeRefresh(csm.lights, frameRef.current++, refreshScale);
+        refreshCascadesOnTexelStep(csm.lights, lightDirectionRef.current, refreshRef.current);
     });
     return null;
 }

package/dist/render/shadowTiers.d.ts

@@ -15,16 +15,6 @@ export declare function resolveShadowMapSize(profile?: GraphicsProfile, authored
  * @internal
  */
 export declare function resolveCascadeCount(profile?: GraphicsProfile, authored?: number): number;
-/**
- * Multiplier on the far cascades' refresh interval, by shadow map size. A tier that halves its map
- * also accepts a far cascade lagging a frame or two longer: at 1024 and below the depth pass is
- * cheap per cascade but there are several of them, and a half-res silhouette moving is harder to
- * see than a full-res one. `high` and `ultra` keep the cadence they had.
- * @internal
- */
-export declare const SHADOW_REFRESH_SCALE_BY_MAP_SIZE: Readonly<Record<number, number>>;
-/** Refresh-interval multiplier for a shadow map of `mapSize`. @internal */
-export declare function shadowRefreshScale(mapSize: number): number;
 /**
  * Map size at which a caster's silhouette is still a few texels wide, the reference
  * {@link MIN_SHADOW_CASTER_RADIUS} was measured at. A smaller map resolves less, so the smallest

package/dist/render/shadowTiers.js

@@ -20,23 +20,6 @@ export function resolveCascadeCount(profile, authored) {
     const wanted = authored ?? profile?.cascades ?? DEFAULT_CASCADES;
     return profile === undefined ? wanted : Math.min(wanted, profile.cascades);
 }
-/**
- * Multiplier on the far cascades' refresh interval, by shadow map size. A tier that halves its map
- * also accepts a far cascade lagging a frame or two longer: at 1024 and below the depth pass is
- * cheap per cascade but there are several of them, and a half-res silhouette moving is harder to
- * see than a full-res one. `high` and `ultra` keep the cadence they had.
- * @internal
- */
-export const SHADOW_REFRESH_SCALE_BY_MAP_SIZE = {
-    512: 2,
-    1024: 2,
-    2048: 1,
-    4096: 1,
-};
-/** Refresh-interval multiplier for a shadow map of `mapSize`. @internal */
-export function shadowRefreshScale(mapSize) {
-    return SHADOW_REFRESH_SCALE_BY_MAP_SIZE[mapSize] ?? 1;
-}
 /**
  * Map size at which a caster's silhouette is still a few texels wide, the reference
  * {@link MIN_SHADOW_CASTER_RADIUS} was measured at. A smaller map resolves less, so the smallest

package/dist/render/triangleAttribution.d.ts

@@ -0,0 +1,40 @@
+import * as THREE from "three";
+/** One line of the triangle table: the draws sharing one geometry inside one named model. */
+export interface TriangleLine {
+    /** Model ancestor names plus the mesh name, or the material name when nothing is named. */
+    label: string;
+    /** Triangles one instance submits. */
+    perInstance: number;
+    /** Instances drawn from this geometry. */
+    instances: number;
+    /** Draw calls this line costs. */
+    draws: number;
+    /** `perInstance * instances` - the triangles this line puts in the frame. */
+    triangles: number;
+}
+/** Where one scene's triangles are, biggest line first. */
+export interface TriangleAttribution {
+    /** Every triangle the scene graph would submit for one camera pass, instances included. */
+    triangles: number;
+    /** How many of those belong to meshes that cast shadows, so the shadow pass pays them again. */
+    casters: number;
+    lines: readonly TriangleLine[];
+}
+/**
+ * Sum a scene's triangles by model and geometry, which is the attribution a triangle budget needs:
+ * a total says a frame is heavy, a table says which authored object made it heavy. Walks the graph
+ * once; call it on demand, never per frame.
+ * @capability triangle-attribution per-model triangle table with instance counts, for perf probes
+ */
+export declare function attributeTriangles(root: THREE.Object3D, limit?: number): TriangleAttribution;
+/**
+ * The `render/triangles` probe for one scene: the table, its two headline numbers, and the one-line
+ * summary a report prints. Reads the graph on every call, so wrap it in a short cache when a
+ * snapshot reads counters and state together.
+ * @internal
+ */
+export declare function triangleProbe(root: THREE.Object3D): {
+    table(): TriangleAttribution;
+    counters(): Record<string, number>;
+    state(): string;
+};

package/dist/render/triangleAttribution.js

@@ -0,0 +1,88 @@
+import * as THREE from "three";
+function triangleCount(mesh) {
+    if (mesh.isPoints === true)
+        return 0;
+    if (mesh.isLine === true)
+        return 0;
+    const geometry = mesh.geometry;
+    if (geometry === undefined || geometry === null)
+        return 0;
+    const index = geometry.getIndex();
+    const position = geometry.getAttribute("position");
+    const vertices = index !== null ? index.count : position?.count ?? 0;
+    return Math.round(vertices / 3);
+}
+const MAX_LABEL_DEPTH = 3;
+function labelOf(mesh) {
+    const names = [];
+    let node = mesh;
+    for (let depth = 0; node !== null && node !== undefined && depth < MAX_LABEL_DEPTH + 1; depth += 1) {
+        if (typeof node.name === "string" && node.name.length > 0)
+            names.push(node.name);
+        node = node.parent;
+    }
+    if (names.length > 0)
+        return names.reverse().join("/");
+    const material = mesh.material;
+    const first = Array.isArray(material) ? material[0] : material;
+    return first?.name || first?.type || mesh.type;
+}
+/**
+ * Sum a scene's triangles by model and geometry, which is the attribution a triangle budget needs:
+ * a total says a frame is heavy, a table says which authored object made it heavy. Walks the graph
+ * once; call it on demand, never per frame.
+ * @capability triangle-attribution per-model triangle table with instance counts, for perf probes
+ */
+export function attributeTriangles(root, limit = 12) {
+    const lines = new Map();
+    let triangles = 0;
+    let casters = 0;
+    root.traverse((node) => {
+        const mesh = node;
+        const per = triangleCount(mesh);
+        if (per === 0)
+            return;
+        const instances = mesh.isInstancedMesh === true
+            ? Math.max(0, mesh.count)
+            : 1;
+        const total = per * instances;
+        triangles += total;
+        if (mesh.castShadow === true)
+            casters += total;
+        const label = labelOf(mesh);
+        const key = `${label}#${mesh.geometry.uuid}`;
+        const line = lines.get(key);
+        if (line === undefined)
+            lines.set(key, { label, perInstance: per, instances, draws: 1, triangles: total });
+        else {
+            line.instances += instances;
+            line.draws += 1;
+            line.triangles += total;
+        }
+    });
+    const sorted = [...lines.values()].sort((a, b) => b.triangles - a.triangles);
+    return { triangles, casters, lines: limit > 0 ? sorted.slice(0, limit) : sorted };
+}
+/**
+ * The `render/triangles` probe for one scene: the table, its two headline numbers, and the one-line
+ * summary a report prints. Reads the graph on every call, so wrap it in a short cache when a
+ * snapshot reads counters and state together.
+ * @internal
+ */
+export function triangleProbe(root) {
+    const table = () => attributeTriangles(root);
+    return {
+        table,
+        counters: () => {
+            const { triangles, casters, lines } = table();
+            return { triangles, casters, lines: lines.length };
+        },
+        state: () => {
+            const { triangles, casters, lines } = table();
+            const top = lines[0];
+            return top === undefined
+                ? `${triangles} triangles`
+                : `${triangles} triangles · casters ${casters} · top ${top.label} ${top.triangles}`;
+        },
+    };
+}

package/dist/scatter/InstancedScatter.d.ts

@@ -1,5 +1,17 @@
+import * as THREE from "three";
 import type { ModelConfig } from "@jgengine/core/game/playableGame";
 import { type ScatterInstance } from "@jgengine/core/world/scatterRegion";
+/** One instanced draw unit - a single species within a single spatial chunk. @internal */
+export interface ScatterBatch {
+    key: string;
+    item: string;
+    /** Per-instance transforms, parallel to `instances`. */
+    matrices: THREE.Matrix4[];
+    /** The placements themselves, so the level pass can read a stable id and a world position. */
+    instances: ScatterInstance[];
+}
+/** Groups resolved instances by spatial chunk then species so each batch is one cullable draw. @internal */
+export declare function scatterBatchInstances(instances: readonly ScatterInstance[], chunkSize: number): ScatterBatch[];
 /** Props for {@link InstancedScatter}: the resolved instances plus chunking/instance-cap knobs. */
 export interface InstancedScatterProps {
     instances: readonly ScatterInstance[];

package/dist/scatter/InstancedScatter.js

@@ -1,18 +1,21 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Suspense, useEffect, useMemo, useRef } from "react";
-import { useLoader } from "@react-three/fiber";
+import { Suspense, useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { useFrame, useLoader, useThree } from "@react-three/fiber";
 import * as THREE from "three";
 import { GLTFLoader } from "three/examples/jsm/loaders/GLTFLoader.js";
 import { MeshoptDecoder } from "three/examples/jsm/libs/meshopt_decoder.module.js";
 import { chunkScatterInstances } from "@jgengine/core/world/scatterRegion";
 import { beginFallbackSeam, reportFallbackSeam } from "@jgengine/core/devtools/fallbackSeams";
+import { createModelVariantSelector } from "@jgengine/core/world/modelLod";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
 import { buildScatterProxy } from "./scatterProxies.js";
 import { buildScatterModelSources, disposeScatterModelSources } from "./scatterModels.js";
+import { writeScatterVariantLevel } from "./scatterVariants.js";
 /** Chunk edge (m): dense fields split into this-sized buckets, each frustum-culled independently. */
 const DEFAULT_CHUNK_SIZE = 24;
 const DEFAULT_MAX_INSTANCES = 20000;
-/** Groups resolved instances by spatial chunk then species so each batch is one cullable draw. */
-function batchInstances(instances, chunkSize) {
+/** Groups resolved instances by spatial chunk then species so each batch is one cullable draw. @internal */
+export function scatterBatchInstances(instances, chunkSize) {
     const batches = [];
     const matrix = new THREE.Matrix4();
     const position = new THREE.Vector3();
@@ -29,12 +32,15 @@ function batchInstances(instances, chunkSize) {
             matrix.compose(position, quaternion, scale);
             const bucket = byItem.get(instance.item);
             if (bucket === undefined)
-                byItem.set(instance.item, [matrix.clone()]);
-            else
-                bucket.push(matrix.clone());
+                byItem.set(instance.item, { matrices: [matrix.clone()], instances: [instance] });
+            else {
+                bucket.matrices.push(matrix.clone());
+                bucket.instances.push(instance);
+            }
+        }
+        for (const [item, bucket] of byItem) {
+            batches.push({ key: `${chunk.key}:${item}`, item, matrices: bucket.matrices, instances: bucket.instances });
         }
-        for (const [item, matrices] of byItem)
-            batches.push({ key: `${chunk.key}:${item}`, item, matrices });
     }
     return batches;
 }
@@ -71,8 +77,68 @@ function ScatterModelSourceInstances({ source, matrices }) {
     }, [matrices, source]);
     return _jsx("instancedMesh", { ref: meshRef, args: [source.geometry, source.material, matrices.length], castShadow: true, receiveShadow: true });
 }
+/**
+ * One detail level's draw source, instanced across every chunk of one species. Each frame it asks the
+ * shared variant selector for each placement's level and draws only the ones it owns, composing into
+ * a reserved matrix slot so the far level's instances cost a second instanced draw, not per-frame
+ * allocation. A cell that holds near and far placements feeds both levels from the same batch.
+ */
+function ScatterVariantSourceInstances({ source, batch, level, selector }) {
+    const meshRef = useRef(null);
+    const camera = useThree((state) => state.camera);
+    const slots = useMemo(() => batch.matrices.map(() => new THREE.Matrix4()), [batch]);
+    const cameraPosition = useMemo(() => new THREE.Vector3(), []);
+    const lastCamera = useRef(new THREE.Vector3(Number.POSITIVE_INFINITY, 0, 0));
+    const writeLevel = useCallback((from) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        const count = writeScatterVariantLevel(level, selector, from, batch.instances, batch.matrices, source.localMatrix, slots);
+        mesh.count = count;
+        mesh.visible = count > 0;
+        mesh.instanceMatrix.needsUpdate = true;
+        if (count > 0)
+            mesh.computeBoundingSphere();
+    }, [level, selector, batch, source, slots]);
+    useLayoutEffect(() => {
+        camera.getWorldPosition(cameraPosition);
+        lastCamera.current.copy(cameraPosition);
+        writeLevel(cameraPosition);
+    }, [camera, writeLevel, cameraPosition]);
+    useFrame((state) => {
+        state.camera.getWorldPosition(cameraPosition);
+        if (cameraPosition.distanceToSquared(lastCamera.current) < 0.25)
+            return;
+        lastCamera.current.copy(cameraPosition);
+        writeLevel(cameraPosition);
+    }, CAMERA_POST_FRAME_PRIORITY + 0.1);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [source.geometry, source.material, batch.matrices.length], castShadow: source.castShadow ?? true, receiveShadow: source.receiveShadow ?? true }));
+}
+/** Renders one level of a variant model: the level's own GLB harvested into instanced draws. */
+function ScatterVariantLevel({ model, url, level, selector, batches }) {
+    const gltf = useLoader(GLTFLoader, url, (loader) => {
+        loader.setMeshoptDecoder(MeshoptDecoder);
+    });
+    const { sources, root } = useMemo(() => {
+        const levelModel = { ...model, url, variants: undefined };
+        return buildScatterModelSources(gltf.scene, levelModel);
+    }, [gltf, model, url]);
+    useEffect(() => () => disposeScatterModelSources(root), [root]);
+    return (_jsx(_Fragment, { children: sources.map((source, sourceIndex) => batches.map((batch) => (_jsx(ScatterVariantSourceInstances, { source: source, batch: batch, level: level, selector: selector }, `${batch.key}:${sourceIndex}`)))) }));
+}
+/**
+ * A species whose model declares detail levels: one GLB per level, each level's instanced draws
+ * claiming only the placements the one shared selector put on it. The selector lives here so a
+ * placement keeps its hysteresis across every level component instead of each level deciding alone.
+ */
+function ScatterVariantSpecies({ model, batches }) {
+    const variants = model.variants;
+    const selector = useMemo(() => createModelVariantSelector(variants), [variants]);
+    useEffect(() => () => selector.clear(), [selector]);
+    return (_jsx(_Fragment, { children: variants.levels.map((level, index) => (_jsx(Suspense, { fallback: null, children: _jsx(ScatterVariantLevel, { model: model, url: level.url, level: index, selector: selector, batches: batches }) }, `${level.url}:${index}`))) }));
+}
 /** Loads one species' real catalog GLB once, harvests its instanceable draw sources, then GPU-instances them across every chunk that species appears in. */
-function ScatterModelSpecies({ model, batches }) {
+function ScatterSingleSpecies({ model, batches }) {
     const gltf = useLoader(GLTFLoader, model.url, (loader) => {
         loader.setMeshoptDecoder(MeshoptDecoder);
     });
@@ -80,6 +146,12 @@ function ScatterModelSpecies({ model, batches }) {
     useEffect(() => () => disposeScatterModelSources(root), [root]);
     return (_jsx(_Fragment, { children: sources.map((source, sourceIndex) => batches.map((batch) => (_jsx(ScatterModelSourceInstances, { source: source, matrices: batch.matrices }, `${batch.key}:${sourceIndex}`)))) }));
 }
+/** One species draw: the level switch for a model with `variants`, the single GLB otherwise. */
+function ScatterModelSpecies({ model, batches }) {
+    return model.variants === undefined
+        ? _jsx(ScatterSingleSpecies, { model: model, batches: batches })
+        : _jsx(ScatterVariantSpecies, { model: model, batches: batches });
+}
 /**
  * Renders resolved {@link ScatterInstance}s grouped into per-chunk, per-species GPU-instanced draws
  * that frustum-cull independently. Species with no `resolveItem` mapping (or a `null` result) render
@@ -89,7 +161,7 @@ function ScatterModelSpecies({ model, batches }) {
  * `resolveScatter` — never one node per placement.
  */
 export function InstancedScatter({ instances, chunkSize = DEFAULT_CHUNK_SIZE, maxInstances = DEFAULT_MAX_INSTANCES, resolveItem, }) {
-    const batches = useMemo(() => batchInstances(instances.length > maxInstances ? instances.slice(0, maxInstances) : instances, chunkSize), [instances, chunkSize, maxInstances]);
+    const batches = useMemo(() => scatterBatchInstances(instances.length > maxInstances ? instances.slice(0, maxInstances) : instances, chunkSize), [instances, chunkSize, maxInstances]);
     const { proxyBatches, modelSpecies } = useMemo(() => {
         // Dev diagnostic (no-op unless armed): re-zero the scatter seam before re-tallying which species
         // fall to a stylized proxy (no resolveItem mapping / a null result). Reported once per species.

package/dist/scatter/scatterVariants.d.ts

@@ -0,0 +1,30 @@
+import type * as THREE from "three";
+import type { ModelVariantSelector } from "@jgengine/core/world/modelLod";
+/** A scatter placement as the level pass reads it: a stable id and a world position. */
+export interface ScatterVariantMember {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/** A camera position the level pass measures from. */
+export interface ScatterVariantCamera {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * Writes the matrices of the members the shared variant selector put on `level` into `out`, in source
+ * order, and returns how many were written. `out` is the level mesh's reserved capacity (one matrix
+ * per member), so a frame writes matrices and `count` without allocating.
+ *
+ * Every member is asked for its level through the same {@link ModelVariantSelector} the static prop
+ * path uses, so hysteresis and the `lodBandIndex` boundary are identical, and a chunk cell holding
+ * near and far members of one species splits between this level's draw and the other levels'.
+ *
+ * `keep` lets an orthogonal instance cull (tier distance, occlusion) drop a member without changing
+ * the level answer, so culling and level selection compose in one pass over the batch.
+ */
+export declare function writeScatterVariantLevel(level: number, selector: ModelVariantSelector, camera: ScatterVariantCamera, members: readonly ScatterVariantMember[], transforms: readonly THREE.Matrix4[], localMatrix: THREE.Matrix4, out: THREE.Matrix4[], keep?: (index: number) => boolean): number;
+/** Triangle total for per-level instance counts, so a fixture reports real geometry, not instance counts. */
+export declare function scatterVariantTriangles(counts: readonly number[], triangles: readonly number[]): number;

package/dist/scatter/scatterVariants.js

@@ -0,0 +1,36 @@
+/**
+ * Writes the matrices of the members the shared variant selector put on `level` into `out`, in source
+ * order, and returns how many were written. `out` is the level mesh's reserved capacity (one matrix
+ * per member), so a frame writes matrices and `count` without allocating.
+ *
+ * Every member is asked for its level through the same {@link ModelVariantSelector} the static prop
+ * path uses, so hysteresis and the `lodBandIndex` boundary are identical, and a chunk cell holding
+ * near and far members of one species splits between this level's draw and the other levels'.
+ *
+ * `keep` lets an orthogonal instance cull (tier distance, occlusion) drop a member without changing
+ * the level answer, so culling and level selection compose in one pass over the batch.
+ */
+export function writeScatterVariantLevel(level, selector, camera, members, transforms, localMatrix, out, keep) {
+    let count = 0;
+    for (let index = 0; index < members.length; index += 1) {
+        const member = members[index];
+        const dx = member.x - camera.x;
+        const dy = member.y - camera.y;
+        const dz = member.z - camera.z;
+        const distance = Math.sqrt(dx * dx + dy * dy + dz * dz);
+        if (selector.level(member.id, distance) !== level)
+            continue;
+        if (keep !== undefined && !keep(index))
+            continue;
+        out[count].multiplyMatrices(transforms[index], localMatrix);
+        count += 1;
+    }
+    return count;
+}
+/** Triangle total for per-level instance counts, so a fixture reports real geometry, not instance counts. */
+export function scatterVariantTriangles(counts, triangles) {
+    let total = 0;
+    for (let index = 0; index < counts.length; index += 1)
+        total += (counts[index] ?? 0) * (triangles[index] ?? 0);
+    return total;
+}

package/dist/world/StaticObjectModels.d.ts

@@ -1,6 +1,7 @@
 import { type ReactNode } from "react";
 import * as THREE from "three";
 import type { SceneObject } from "@jgengine/core/scene/objectStore";
+import { type ModelVariantSelector } from "@jgengine/core/world/modelLod";
 import { type StaticObjectBatch } from "./staticObjectBatches.js";
 /**
  * Report what static object batching is doing to `debug_snapshot().systems`: the grouped batches, the
@@ -14,6 +15,23 @@ export declare function useStaticObjectBatchProbe(scene: THREE.Object3D, stats:
     instances: number;
     singles: number;
 }): void;
+/** Members of one level drawn through the individual renderer, for a level whose asset cannot be instanced. @internal */
+export declare function LevelSingles({ objects, level, selector, single }: {
+    objects: readonly SceneObject[];
+    level: number;
+    selector: ModelVariantSelector;
+    single: (object: SceneObject) => ReactNode;
+}): import("react").JSX.Element;
+/**
+ * A batch whose model declares detail levels: every level draws its own instanced meshes and claims
+ * only the instances the shared distance switch put on it, so near and far trees of one species keep
+ * their own mesh inside one batch cell.
+ * @internal
+ */
+export declare function VariantStaticObjects({ batch, single }: {
+    batch: StaticObjectBatch;
+    single: (object: SceneObject) => ReactNode;
+}): import("react").JSX.Element;
 /** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export declare function StaticObjectModels({ batch, single }: {
     batch: StaticObjectBatch;

package/dist/world/StaticObjectModels.js

@@ -2,6 +2,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { useFrame, useLoader } from "@react-three/fiber";
 import { useEffect, useMemo, useRef, useState, useCallback } from "react";
 import * as THREE from "three";
+import { createModelVariantSelector } from "@jgengine/core/world/modelLod";
 import { devtools } from "@jgengine/core/devtools/devtools";
 import { useGameContext } from "@jgengine/react/provider";
 import { sharedGltfLoader } from "../render/modelLoad.js";
@@ -31,11 +32,26 @@ export function useStaticObjectBatchProbe(scene, stats) {
         },
     }), [scene]);
 }
-function ObjectSource({ source, objects, batch }) {
+/** Live members of one batch after the per-frame compatibility gate removed any that changed at runtime. */
+function useBatchMembers(batch) {
+    const ctx = useGameContext();
+    const [excluded, setExcluded] = useState([]);
+    const fallbackObjects = useRef(new Map());
+    useFrame(() => {
+        const next = incompatibleStaticObjectIds(batch, ctx.scene.object.get, ctx.scene.object.catalog, excluded, fallbackObjects.current);
+        if (next !== excluded)
+            setExcluded(next);
+    });
+    const objects = useMemo(() => batch.objects.filter((object) => !excluded.includes(object.instanceId)), [batch, excluded]);
+    return { objects, excluded };
+}
+function ObjectSource({ source, objects, batch, selector, level }) {
     const ctx = useGameContext();
     const visibility = useRenderVisibility();
     const ref = useRef(null);
     const scratch = useMemo(() => new THREE.Object3D(), []);
+    const cameraPosition = useRef(new THREE.Vector3());
+    const probe = useMemo(() => new THREE.Vector3(), []);
     const attach = useCallback((mesh) => {
         ref.current = mesh;
         if (mesh !== null)
@@ -45,26 +61,26 @@ function ObjectSource({ source, objects, batch }) {
         const mesh = ref.current;
         return () => { mesh?.dispose(); };
     }, [objects.length, source]);
-    useFrame(() => {
-        if (ref.current !== null)
-            syncStaticObjectSource(ref.current, source, objects, (id) => {
-                const object = ctx.scene.object.get(id);
-                return object !== null && object.catalogId === batch.objects[0].catalogId &&
-                    isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
-            }, visibility.current, scratch);
+    useFrame((state) => {
+        if (ref.current === null)
+            return;
+        let accept;
+        if (selector !== undefined && level !== undefined) {
+            const camera = cameraPosition.current;
+            state.camera.getWorldPosition(camera);
+            accept = (live) => selector.level(live.instanceId, camera.distanceTo(probe.set(live.position[0], live.position[1], live.position[2]))) === level;
+        }
+        syncStaticObjectSource(ref.current, source, objects, (id) => {
+            const object = ctx.scene.object.get(id);
+            return object !== null && object.catalogId === batch.objects[0].catalogId &&
+                isCompatibleStaticObject(object, batch.model, ctx.scene.object.catalog(id)) ? object : null;
+        }, visibility.current, scratch, accept);
     }, CAMERA_POST_FRAME_PRIORITY + 0.1);
     return _jsx("instancedMesh", { ref: attach, args: [source.geometry, source.material, objects.length], userData: { [STATIC_BATCH_MESH_KEY]: true }, castShadow: source.castShadow, receiveShadow: source.receiveShadow, dispose: null });
 }
 function LoadedStaticObjects({ batch, single }) {
     const ctx = useGameContext();
-    const [excluded, setExcluded] = useState([]);
-    const fallbackObjects = useRef(new Map());
-    useFrame(() => {
-        const next = incompatibleStaticObjectIds(batch, ctx.scene.object.get, ctx.scene.object.catalog, excluded, fallbackObjects.current);
-        if (next !== excluded)
-            setExcluded(next);
-    });
-    const objects = useMemo(() => batch.objects.filter((object) => !excluded.includes(object.instanceId)), [batch, excluded]);
+    const { objects, excluded } = useBatchMembers(batch);
     const gltf = useLoader(sharedGltfLoader, batch.model.url);
     const supported = useMemo(() => canInstanceStaticScene(gltf.scene, gltf.animations), [gltf]);
     const harvested = useMemo(() => supported ? buildScatterModelSources(gltf.scene, batch.model) : null, [supported, gltf, batch.model]);
@@ -94,7 +110,75 @@ function LoadedStaticObjects({ batch, single }) {
         return _jsx(_Fragment, { children: batch.objects.map(single) });
     return _jsxs(_Fragment, { children: [harvested.sources.map((source, index) => objects.length === 0 ? null : _jsx(ObjectSource, { source: source, objects: objects, batch: batch }, index)), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
 }
+/** One detail level's GLB, harvested into instanced draws that only claim the instances the selector put on this level. */
+function VariantLevel({ url, model, batch, objects, level, selector, measure, single }) {
+    const ctx = useGameContext();
+    const gltf = useLoader(sharedGltfLoader, url);
+    const supported = useMemo(() => canInstanceStaticScene(gltf.scene, gltf.animations), [gltf]);
+    const harvested = useMemo(() => supported ? buildScatterModelSources(gltf.scene, model) : null, [supported, gltf, model]);
+    useEffect(() => () => { if (harvested !== null)
+        disposeScatterModelSources(harvested.root); }, [harvested]);
+    useEffect(() => {
+        if (harvested === null || !measure)
+            return;
+        const root = new THREE.Group();
+        for (const source of harvested.sources) {
+            const mesh = new THREE.Mesh(source.geometry, source.material);
+            mesh.matrixAutoUpdate = false;
+            mesh.matrix.copy(source.localMatrix);
+            root.add(mesh);
+        }
+        const key = batch.objects[0].catalogId;
+        if (batch.model.dims?.maxY === undefined) {
+            const bounds = measureLocalBounds(root);
+            if (bounds !== null)
+                reportMeasuredBounds(ctx, "object", key, bounds);
+        }
+        const triangles = measureLocalCollisionTriangles(root);
+        if (triangles !== null)
+            reportMeasuredCollisionMesh(ctx, "object", key, triangles);
+    }, [ctx, harvested, batch, measure]);
+    if (harvested === null)
+        return _jsx(LevelSingles, { objects: objects, level: level, selector: selector, single: single });
+    return _jsx(_Fragment, { children: harvested.sources.map((source, index) => _jsx(ObjectSource, { source: source, objects: objects, batch: batch, selector: selector, level: level }, index)) });
+}
+/** Members of one level drawn through the individual renderer, for a level whose asset cannot be instanced. @internal */
+export function LevelSingles({ objects, level, selector, single }) {
+    const ctx = useGameContext();
+    const visibility = useRenderVisibility();
+    const camera = useMemo(() => new THREE.Vector3(), []);
+    const probe = useMemo(() => new THREE.Vector3(), []);
+    const [members, setMembers] = useState(objects);
+    useFrame((state) => {
+        state.camera.getWorldPosition(camera);
+        const next = objects.flatMap((object) => {
+            const live = ctx.scene.object.get(object.instanceId);
+            if (live === null || !visibility.current(live.instanceId))
+                return [];
+            probe.set(live.position[0], live.position[1], live.position[2]);
+            return selector.level(live.instanceId, camera.distanceTo(probe)) === level ? [live] : [];
+        });
+        if (next.length !== members.length || next.some((member, index) => member !== members[index]))
+            setMembers(next);
+    });
+    return _jsx(_Fragment, { children: members.map(single) });
+}
+/**
+ * A batch whose model declares detail levels: every level draws its own instanced meshes and claims
+ * only the instances the shared distance switch put on it, so near and far trees of one species keep
+ * their own mesh inside one batch cell.
+ * @internal
+ */
+export function VariantStaticObjects({ batch, single }) {
+    const ctx = useGameContext();
+    const { objects, excluded } = useBatchMembers(batch);
+    const levels = batch.model.variants.levels;
+    const selector = useMemo(() => createModelVariantSelector(batch.model.variants), [batch.model]);
+    return _jsxs(_Fragment, { children: [levels.map((level, index) => (_jsx(VariantLevel, { url: level.url, model: { ...batch.model, url: level.url, variants: undefined }, batch: batch, objects: objects, level: index, selector: selector, measure: index === 0, single: single }, `${level.url}:${index}`))), excluded.map((id) => { const live = ctx.scene.object.get(id); return live === null ? null : single(live); })] });
+}
 /** Render compatible authored or `scenery` props as shared model draws, preserving unsupported models. @internal */
 export function StaticObjectModels({ batch, single }) {
-    return _jsx(IsolatedModelPart, { model: batch.model, seam: "object", children: _jsx(LoadedStaticObjects, { batch: batch, single: single }) });
+    return (_jsx(IsolatedModelPart, { model: batch.model, seam: "object", children: batch.model.variants === undefined
+            ? _jsx(LoadedStaticObjects, { batch: batch, single: single })
+            : _jsx(VariantStaticObjects, { batch: batch, single: single }) }));
 }

package/dist/world/staticObjectBatches.d.ts

@@ -63,5 +63,5 @@ export interface StaticBatchCounts {
 export declare function countStaticBatchDraws(scene: THREE.Object3D): StaticBatchCounts;
 /** Rejects loaded scenes whose behavior cannot be represented by static instanced draws. @internal */
 export declare function canInstanceStaticScene(scene: THREE.Object3D, clips: readonly THREE.AnimationClip[]): boolean;
-/** Compact visible placements and update picking identities without allocating per instance. @internal */
-export declare function syncStaticObjectSource(mesh: THREE.InstancedMesh, source: ScatterModelSource, objects: readonly SceneObject[], get: (id: string) => SceneObject | null, visible: (id: string) => boolean, scratch: THREE.Object3D): void;
+/** Compact visible placements and update picking identities without allocating per instance. `accept` narrows the range to one detail level of a variant model. @internal */
+export declare function syncStaticObjectSource(mesh: THREE.InstancedMesh, source: ScatterModelSource, objects: readonly SceneObject[], get: (id: string) => SceneObject | null, visible: (id: string) => boolean, scratch: THREE.Object3D, accept?: (live: SceneObject) => boolean): void;

package/dist/world/staticObjectBatches.js

@@ -155,8 +155,8 @@ export function canInstanceStaticScene(scene, clips) {
     });
     return supported;
 }
-/** Compact visible placements and update picking identities without allocating per instance. @internal */
-export function syncStaticObjectSource(mesh, source, objects, get, visible, scratch) {
+/** Compact visible placements and update picking identities without allocating per instance. `accept` narrows the range to one detail level of a variant model. @internal */
+export function syncStaticObjectSource(mesh, source, objects, get, visible, scratch, accept) {
     const ids = (mesh.userData[POINTER_OBJECT_INSTANCES_KEY] ??= []);
     const poses = (mesh.userData["jgStaticObjectPoses"] ??= []);
     if (mesh.userData["jgStaticObjectSource"] !== source) {
@@ -168,7 +168,7 @@ export function syncStaticObjectSource(mesh, source, objects, get, visible, scra
     const composed = scratch.matrixWorld;
     for (const object of objects) {
         const live = get(object.instanceId);
-        if (live === null || !visible(live.instanceId))
+        if (live === null || !visible(live.instanceId) || (accept !== undefined && !accept(live)))
             continue;
         if (poses[count] === live) {
             ids[count++] = live.instanceId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.35.0",
+  "version": "0.37.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,9 +39,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.35.0",
-    "@jgengine/react": "^0.35.0",
-    "@jgengine/ws": "^0.35.0"
+    "@jgengine/core": "^0.37.0",
+    "@jgengine/react": "^0.37.0",
+    "@jgengine/ws": "^0.37.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.37.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.35.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.37.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine-ui/api.md

@@ -2829,6 +2829,8 @@
 
 ## @jgengine/shell/render/CascadedShadows
 
+- `CASCADE_DEPTH_STEP_TEXELS` (const): const CASCADE_DEPTH_STEP_TEXELS: 8 — Depth-axis steps worth of a texel the snapped light may drift before it re-anchors.
+- `CascadeRefreshState` (interface): interface CascadeRefreshState — Per-frame cascade refresh bookkeeping: the centre each map was last rendered with.
 - `CsmMaterialSetup` (interface): interface CsmMaterialSetup — Structural slice of CSM so the patcher is testable without a renderer.
 - `patchSceneMaterials` (function): function patchSceneMaterials(scene: THREE.Scene, csm: CsmMaterialSetup, patched: WeakSet<THREE.Material>): void — Run CSM's `setupMaterial` over every unpatched standard material in the scene, chaining rather than clobbering a material's own `onBeforeCompile`.
 
@@ -3034,6 +3036,12 @@
 
 - `drawProceduralTileLayer` (function): function drawProceduralTileLayer(canvas: CanvasFixture): TilemapWorldConfig — Draw the deterministic tile atlas used by textured tile-layer captures and tests.
 
+## @jgengine/shell/render/triangleAttribution
+
+- `TriangleAttribution` (interface): interface TriangleAttribution — Where one scene's triangles are, biggest line first.
+- `TriangleLine` (interface): interface TriangleLine — One line of the triangle table: the draws sharing one geometry inside one named model.
+- `attributeTriangles` (function): function attributeTriangles(root: THREE.Object3D, limit = 12): TriangleAttribution — Sum a scene's triangles by model and geometry, which is the attribution a triangle budget needs: a total says a frame is heavy, a table says which authored object made it heavy. Walks the graph once; call it on demand, never per frame.
+
 ## @jgengine/shell/render/triplanarMaterial
 
 - `TriplanarAssetMaterial` (function): function TriplanarAssetMaterial({ asset, ...options }: { asset: MaterialAsset } & { tileMetres?: number; sharpness?: number; normalScale?: number }): React.JSX.Element — Mounts {@link useTriplanarAssetMaterial} on a mesh; the R3F renderer owns disposal.
@@ -3101,6 +3109,13 @@
 
 - `ScatterModelSource` (interface): interface ScatterModelSource — One instanceable draw source harvested from a resolved GLB — geometry stays shared with the loader cache, `localMatrix` bakes the model's own transform (from its scene root) plus scale/anchor normalization.
 
+## @jgengine/shell/scatter/scatterVariants
+
+- `ScatterVariantCamera` (interface): interface ScatterVariantCamera — A camera position the level pass measures from.
+- `ScatterVariantMember` (interface): interface ScatterVariantMember — A scatter placement as the level pass reads it: a stable id and a world position.
+- `scatterVariantTriangles` (function): function scatterVariantTriangles(counts: readonly number[], triangles: readonly number[]): number — Triangle total for per-level instance counts, so a fixture reports real geometry, not instance counts.
+- `writeScatterVariantLevel` (function): function writeScatterVariantLevel(level: number, selector: ModelVariantSelector, camera: ScatterVariantCamera, members: readonly ScatterVariantMember[], transforms: readonly THREE.Matrix4[], localMatrix: THREE.Matrix4, out: THREE.Matrix4[], keep?: (index: number) => boolean): number — Writes the matrices of the members the shared variant selector put on `level` into `out`, in source order, and returns how many were written. `out` is the level mesh's reserved capacity (one matrix per member), so a frame writes matrices and `count` without allocating.
+
 ## @jgengine/shell/scene
 
 - `AuthoredObjects` (function): function AuthoredObjects({ document, field, verticalOffset = 0, onExisting = "keep", synchronize = false, excludeKinds, }: AuthoredObjectsProps): null — Places every editor marker with a catalog id into `ctx.scene.object`, grounded on `field`. WorldScene renders them through the game's `objectModels` seam — no bespoke place loop. Pure headless twin: `resolveAuthoredObjects` / `placeAuthoredObjects`.

package/skills/jgengine-ui/capabilities.md

@@ -919,6 +919,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `TransformGizmo` (const) · `import { TransformGizmo } from "@jgengine/shell/structures"`
 
+## triangle-attribution — per-model triangle table with instance counts, for perf probes
+
+- `attributeTriangles` (function) · `import { attributeTriangles } from "@jgengine/shell/render/triangleAttribution"`
+
 ## tween-number — rolling number readout with an up/down delta flash
 
 - `TweenNumber` (function) · `import { TweenNumber } from "@jgengine/react/tweenNumber"`

package/skills/jgengine-world/api.md

@@ -2501,6 +2501,7 @@
 - `DEFAULT_POLICE_TIERS` (const): const DEFAULT_POLICE_TIERS: readonly PoliceTier[] — The starting tier table: patrol until heat arrives, then investigate, pursue and finally cordon.
 - `DEFAULT_POLICE_TUNING` (const): const DEFAULT_POLICE_TUNING: PoliceTuning — The starting policy: linear decay, a six-second escape and a search area that grows at 2 m/s.
 - `DEFAULT_REPUTATION_TIERS` (const): const DEFAULT_REPUTATION_TIERS: readonly ReputationTier[] — ⚠ undocumented
+- `DEFAULT_VARIANT_HYSTERESIS` (const): const DEFAULT_VARIANT_HYSTERESIS: 6 — Metres an instance must travel past a switch boundary before it changes level unless the model declares its own.
 - `DamageDirectionOptions` (interface): interface DamageDirectionOptions — Options for {@link createDamageDirectionTracker}.
 - `DamageDirectionSnapshot` (interface): interface DamageDirectionSnapshot — Serializable state for save/restore — the clock reading plus every live indicator.
 - `DamageDirectionTracker` (interface): interface DamageDirectionTracker — A serializable, allocation-aware brain that tracks where recent damage came from. Each registered hit becomes a directional indicator that fades over a fixed duration on the injected clock; {@link DamageDirectionTracker.active} reports the live ones with their eased current strength.
@@ -2654,6 +2655,10 @@
 - `ModelAssetRef` (interface): interface ModelAssetRef { url: string; anchor?: "center" | "origin"; dims?: ModelDims; collisionMesh?: CollisionMeshData; space?: AssetSpace; clips?: readonly string[] } — ⚠ undocumented · used by `createHostedWorldSessionAsync` (@jgengine/core/runtime/hostedWorldSession): Build a hosted session from an asynchronous persistence backend.
 - `ModelDims` (interface): interface ModelDims — Measured horizontal footprint, footprint center, and lowest Y of a model in model space.
 - `ModelNode` (interface): interface ModelNode — Generic named-socket reader for loaded 3D models. Walks a node tree (any object with `.name`, `.position`, and `.children` — structurally satisfied by `THREE.Object3D`) and collects the local offsets of nodes whose name marks an attachment point. Genre-agnostic: wire anchors on a pylon, muzzle/hand mounts on a character, hardpoints on a ship, seat/decal slots on furniture — anything an artist tags with an empty in the GLB. Pure data (no three.js import), so it lives in core.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
+- `ModelVariantSelector` (interface): interface ModelVariantSelector — Per-instance distance switch over a model's detail levels: one answer per id, held across a boundary until the instance clears it.
+- `ModelVariantSelectorState` (interface): interface ModelVariantSelectorState — Plain JSON state of a {@link ModelVariantSelector}: each id's current level index.
 - `MountController` (class): class MountController — Mount / rideable control-transfer (issue #83). Registers rideables (each with one or more seats — a control seat drives, the rest ride) and tracks who is on what. It owns no camera or physics: game code reads `cameraTarget(riderId)` to point the follow camera at the mount, and `driveTarget(riderId)` to route that rider's {@link import("../physics/vehicleBody").AxisInput}-driven input at the mount's movement kit — the same seam a horse, a truck, or a shared multi-seat ship all plug into.
 - `MoveOrderPayload` (interface): interface MoveOrderPayload — Payload for a move order: go to a point and complete on arrival.
 - `MovementPose` (type): type MovementPose = "standing" | "crouch" | "prone" | "running" — ⚠ undocumented
@@ -3109,6 +3114,7 @@
 - `createLodScheduler` (function): function createLodScheduler(config: LodSchedulerConfig): LodScheduler — ⚠ undocumented
 - `createMarkerSet` (function): function createMarkerSet<TMeta = unknown>(now: () => number = Date.now): MarkerSet<TMeta> — ⚠ undocumented
 - `createMarkerSource` (function): function createMarkerSource<TEntity, TMarker extends MarkerView = MarkerView>(options: MarkerSourceOptions<TEntity, TMarker>): MarkerSource<TMarker> — Adapt a caller-owned array/store to an observable marker source. Projection is cached between source changes, so React reads do not copy the collection per frame. The caller retains ownership of entities, updates, persistence, and subscription scheduling.
+- `createModelVariantSelector` (function): function createModelVariantSelector(config: ModelVariantLodConfig): ModelVariantSelector — Builds the per-instance distance switch for a model's variant levels.
 - `createMountController` (function): function createMountController(): MountController — ⚠ undocumented
 - `createNavCrowd` (function): function createNavCrowd(options: NavCrowdOptions & { nav: NavRuntime }): NavCrowd — Compose {@link createNavRuntime} and {@link createRvoCrowd} into a moving crowd: plan on the mesh, follow the smoothed corridor, avoid each other. Deterministic — agents advance in insertion order and the avoidance solve breaks ties by slot, not chance.
 - `createNavGrid` (function): function createNavGrid(config: NavGridConfig): NavGrid — ⚠ undocumented
@@ -3213,6 +3219,7 @@
 - `leaveVehicle` (function): function leaveVehicle(ctx: GameContext, seats: VehicleSeats, riderId: string, options: LeaveVehicleOptions = {}): ExitVehicleResult | { ok: false; reason: "unknown_rider" | "unknown_vehicle" } — Apply dismount placement, restore rider movement/visibility and the configured camera rig.
 - `lineFormation` (function): function lineFormation(options: LineFormationOptions): FormationSlotGenerator — A single rank abreast, centered on the destination and facing forward — a skirmish line or a chorus row. Slots run left→right along the group's right axis.
 - `listTriggerActions` (function): function listTriggerActions(target?: TriggerSourceKind): TriggerActionDefinition[] — Every registered action, optionally filtered by target collection.
+- `lodBandIndex` (function): function lodBandIndex(bands: readonly { maxDistance: number }[], distance: number): number — Index of the band `distance` falls in, `-1` past the last band. Bands must already be sorted near to far. The scheduler and `createModelVariantSelector` both read distances through this one function, so simulation throttling and mesh detail cannot disagree about what band an id is in.
 - `mapLayerColor` (function): function mapLayerColor(tone: MapLayerTone | undefined): string — ⚠ undocumented
 - `markerCatalogId` (function): function markerCatalogId(marker: AuthoredObjectMarkerLike): string | null — Catalog id for a marker: first-class `catalogId` field, else `meta.catalogId` migration alias. Returns null when the marker is not an authored catalog prop (spawn, mob, generator, …).
 - `markerKindStyle` (function): function markerKindStyle(kind: string | undefined, styles: Record<string, MarkerKindStyle> = DEFAULT_MARKER_KINDS): MarkerKindStyle — ⚠ undocumented
@@ -3942,6 +3949,7 @@
 - `LodSchedulerConfig` (interface): interface LodSchedulerConfig { bands: readonly LodBand[]; beyondInterval?: number | null; stagger?: boolean } — ⚠ undocumented
 - `LodSchedulerState` (interface): interface LodSchedulerState — Plain JSON state of a {@link LodScheduler}: each id's accumulated seconds.
 - `createLodScheduler` (function): function createLodScheduler(config: LodSchedulerConfig): LodScheduler — ⚠ undocumented
+- `lodBandIndex` (function): function lodBandIndex(bands: readonly { maxDistance: number }[], distance: number): number — Index of the band `distance` falls in, `-1` past the last band. Bands must already be sorted near to far. The scheduler and `createModelVariantSelector` both read distances through this one function, so simulation throttling and mesh detail cannot disagree about what band an id is in.
 
 ## @jgengine/core/world/mapAnnotations
 
@@ -4030,6 +4038,15 @@
 - `TrackAxis` (interface): interface TrackAxis — A world-space segment defining a linear "track" minimap — points are projected onto the `from`→`to` axis.
 - `trackFraction` (function): function trackFraction(point: WorldXZ | readonly [number, number, number], axis: TrackAxis): number — Project a world point onto the `from`→`to` segment of `axis` and return the clamped 0..1 fraction of how far along the track it lies (0 at `from`, 1 at `to`). The linear analogue of `projectToMinimap` — feeds a horizontal corridor/route progress rail. Accepts XZ (`[x, z]`) or XYZ (`[x, y, z]`) points (index 0 = x, index 2 when length 3 else index 1 = z). A zero-length axis returns 0.
 
+## @jgengine/core/world/modelLod
+
+- `DEFAULT_VARIANT_HYSTERESIS` (const): const DEFAULT_VARIANT_HYSTERESIS: 6 — Metres an instance must travel past a switch boundary before it changes level unless the model declares its own.
+- `ModelVariantConfig` (interface): interface ModelVariantConfig — One mesh level of a {@link ModelVariantLodConfig}: a full or decimated GLB and how far it draws.
+- `ModelVariantLodConfig` (interface): interface ModelVariantLodConfig — Ordered mesh detail levels for one model, switched per instance by camera distance. The first level is the full mesh the model's own `url` names; every later level is a cheaper asset. A tree line uses this so near trees keep their full mesh while far ones draw a decimated copy of the same species.
+- `ModelVariantSelector` (interface): interface ModelVariantSelector — Per-instance distance switch over a model's detail levels: one answer per id, held across a boundary until the instance clears it.
+- `ModelVariantSelectorState` (interface): interface ModelVariantSelectorState — Plain JSON state of a {@link ModelVariantSelector}: each id's current level index.
+- `createModelVariantSelector` (function): function createModelVariantSelector(config: ModelVariantLodConfig): ModelVariantSelector — Builds the per-instance distance switch for a model's variant levels.
+
 ## @jgengine/core/world/pathInstances
 
 - `PathInstance` (interface): interface PathInstance — One placed transform along a path: grounded position, facing yaw, and its ordinal + arc distance.