@jgengine/editor 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -26,6 +26,71 @@ 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.26.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.26.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.23.0`; `@jgengine/github` is `0.13.0`.
+
+### Added
+
+- `createLogBus` (`@jgengine/core/devtools/logBus`): a fixed-capacity ring of log lines tagged by owning system, with a separate ring for warnings and errors so a crash line is never pushed out by info traffic. `devtools.logs` now writes through it (`write(level, system, message)`, `snapshot()`, `counts()`, `dropped()`); `DevtoolsLogEntry` gained `system`.
+- `devtools.probes.registerSystem(id, { counters, timers, state })`: a system reports its own counters, named timings and one state line in a few lines, with no shell wiring. Readings surface as `systems` in `devtools.snapshot()`, in `debug_snapshot`, and in every perf record.
+- `PerfReport` (`@jgengine/core/devtools/report`): the one perf record shape shared by `bun run perf` and the in-page report.
+- The shell samples frame telemetry in-page in dev builds: `window.__JG.report()` returns that record, and the page pushes it about once a second to the dev server's `GET/POST /__jgengine/report` route. `bun run debug <game>` prints the record of a game already open and exits non-zero on a budget breach in `scripts/perf-budget.json`.
+- `createNeedSet` (`@jgengine/core/gameplay`) drains named needs on game time and reads them by index — decaying hunger, energy, fun with snapshot/restore and per-need rate retuning.
+- `createUtilityBrain` (`@jgengine/core/world`) picks an action from decaying-need appeal: linear, quadratic, logistic, exponential and threshold response curves, candidate cost (travel, queues, price), a switch margin plus minimum hold (hysteresis), declared interrupts, optional seeded jitter, and a devtools probe string.
+- `createNavRuntime` (`@jgengine/core/world`) consumes an editor-baked nav mesh: reads the `nav` bake off a scene document (`navMeshFromBake`), routes with the mesh query, resolves authored doors, ladders and jumps (`AuthoredNavLink`, priced by kind) onto the current surface, and swaps in a new bake after an edit while matching polygon identity by geometry — `applyMesh` returns a `remap` so only routes over changed polygons need re-planning.
+- `createNavCrowd` (`@jgengine/core/world`) moves many agents across that mesh: plans a corridor, follows the funnel-smoothed waypoints, keeps agents apart with reciprocal velocity obstacle avoidance, bounds path searches per tick by count and milliseconds, fans converging agents out with `spread`, and round-trips through `snapshot`/`restore`.
+- `createRvoCrowd` (`@jgengine/core/world`) is the avoidance solver on its own: RVO/ORCA half-plane solve over a uniform-grid neighbour search capped at `maxNeighbors`, deterministic tie-breaking, overlap relief, retunable `timeHorizon`/`neighborDist`/`maxNeighbors`/`sideBias`/`overlapRelief`, and `snapshot`/`restore` for saves and replays.
+- `resolveRoutine` (`@jgengine/core/gameplay`) resolves an authored day into real arrival and departure times against the world clock. Travel time is injected per stop or as a callback, so a stop departs early enough to walk to the next one and an arrival that runs late slips instead of teleporting; `phaseAt(time)` returns the held place, the walking leg and its progress, and `nextChangeAfter(time)` drives a scheduler. A day whose walks cannot fit its cycle throws at construction.
+- `createOffScreenWorld` (`@jgengine/core/gameplay`) keeps a whole population without simulating it: residents beyond the injected radius are cheap state (position, routine phase, needs) that only moves when the clock crosses a routine boundary, and they spawn into the game's own near simulation through a `NearAgents` interface when they come close. The radius, an optional per-agent cost model, a near budget and a per-tick switch budget are all injected; `snapshot`/`restore` round-trip the whole population, and crossing the boundary preserves identity, schedule progress, need values and position.
+- `createNearAgents` (`@jgengine/core/gameplay`) is the default near half of that seam: a nav crowd with a need set and utility brain per agent, goal-tracking as routines move residents between places, and a decision counter for tests and probes.
+- `createPerception` shares squad knowledge: `squadMates(observerId)` names an observer's roster, and a sighting one member makes is written into every mate's memory with `sourceId` (who saw it) and `sourceTick` (the observe pass it was recorded on). A mate's own sighting at the same instant replaces the hand-off. `maxSharesPerTick` (default 64, per observer pass) bounds a large roster and reports elided shares.
+- Perception memory is auditable without guessing: `memoryOf(observerId, targetId)` returns the one remembered target with its confidence right now or `null` once it has faded, and `stats()` counts pair checks, range prunes, cone tests, line-of-sight calls, sightings, heard stimuli, shares and dropped shares. The check order is range → cone → line of sight, so occlusion work only sees the pruned set. `resetStats()` opens a measurement window; `memories` are pruned per observer so a 200-observer pass does not rescan every memory.
+- `devtoolsName` registers a probe showing observers, remembered targets and the work counters, and `dispose()` removes it.
+- `createCoverField` and `coverPointsFromSolids` (`@jgengine/core/combat`) derive stand-able cover from authored solid boxes instead of a coordinate list: one row of points per vertical face, clear of the corners, filtered by an injected `walkable` test, rebuilt when the world is edited, and queried through a bounded `near(position, radius, limit)`. `CoverSource` is the seam, so a game with its own spatial index can supply cover without the box generator.
+- `selectCover` / `scoreCoverPoint` choose cover by threat: `hidden` is the confidence-weighted share of remembered threats whose line of sight the point (and a body-sized footprint at it) blocks, scored against the role's preferred fighting range, flank angle around the threat, distance, a squadmate's claim on the point, and whether the walk to it is a detour. Fading memories stop steering at `minConfidence`, and a point that hides from only one of two shooters is not cover.
+- `createSquadCombat` (`@jgengine/core/combat`) drives a squad over existing seams: role-driven cover selection, fire discipline (hold, lean out, shoot), suppression from `underFire()`, retreat below a role's health threshold, and relocation under sustained fire. Threat comes only from `threatsFromMemory`, i.e. the perception memory the game already keeps; movement goes through `NavCrowd` with a tighter arrival tolerance so a body actually reaches the stand point. Serializable through `snapshot()`/`restore()` (member decisions, crowd, tuning), retunable, and a `devtoolsName` probe reports pins, peeks, shots and the worst exposure.
+- `assignSquadRoles` and `threatsFromMemory` (`@jgengine/core/combat`): deterministic role assignment over a caller-authored `SquadComposition` (role ids, counts, ranges, flank angles, retreat thresholds and cover weights are all content), and a bounded, confidence-ranked threat list from one observer's memory.
+- A 2v4 arena soak proves the behavior: 90 simulated seconds, 2700 ticks, 4 squad members against 2 scripted raiders, worst exposure 2.33 s (bar 3 s), 0 of 38 exposure spells over 3 s, per-tick cost p50 0.05 ms / p95 0.19 ms.
+- `createDamageRuntime` (`@jgengine/core/combat`) composes a damage table, hit zones, the armor curve and carried statuses into one stateful model: `hit()` returns every stage of the number (`base × zone multiplier × type multiplier × (1 − armor mitigation)`), `tick()` runs status effects through the same table and armor, `timeToKill()` quotes a fight, and `table()` reads the whole chart. `snapshot()`/`restore()` carry registered targets and carried statuses; `retune()` swaps table, zones or status definitions without dropping either; a `devtoolsName` probe reports hits, crits, ticks and the last hit.
+- A damage table (`combat/damageTable`) of damage type × resistance class, with `armor / (armor + halfValue)` mitigation — armor equal to the half value halves the hit — a per-type `bypassArmor`, and `readDamageTable` / `formatDamageTable` to read every row at given armor values. An unknown damage type throws instead of silently dealing 1×.
+- Hit zones and crits (`combat/hitZones`): a zone carries a normal multiplier and an optional crit multiplier, `resolveHitZone` rolls once and returns one multiplier, and a crit replaces the zone multiplier rather than compounding with it. `hitZoneMultiplier` quotes the same number without a roll.
+- `createStatusRuntime` (`combat/statusRuntime`): data-defined statuses with the existing `StatusStackPolicy` (`refresh`, stack to `max`, `replace`, `ignore`) as the only thing that changes stacks, per-tick effects of `{ kind: "damage", channel }` or `{ kind: "stat", stat }`, damage routed through an injected `applyDamage` so resistances and armor still apply, bounded ticks per call, and plain-data state out and back.
+- Numbers from the tests: 25 base kinetic against a 150 HP target, 0.15 s between shots — 8 shots / 1.05 s unarmored, 20 shots / 2.85 s at 60 armor, 36 shots / 5.25 s at 200 armor; two stacked burns of 4 per tick deal 8, not 16; a 1.5× head zone with a 2.5× crit multiplier deals 2.5×, not 3.75×.
+- `createWeaponSystem` (`@jgengine/core/combat`) runs one `WeaponDefinition`: single, automatic or burst fire, hitscan or ballistic projectiles, recoil that moves the aim the shot flies down, spread bloom, interrupted/resumed reloads, a readable ammo economy (`ammo()`, `stats()`), `snapshot()`/`restore()` and a devtools probe. Every hit, hitscan or projectile, resolves through `createDamageRuntime`. Pellet work is bounded per tick (`maxShotsPerTick`, default 4) and per weapon (`maxInFlight`, default 32).
+- `WeaponDefinition` (`@jgengine/core/combat/weaponDefinition`) as plain JSON — rate, fire mode, delivery, magazine, handling, damage, falloff — with `assertWeaponDefinition`, `weaponIntervalMs`, `weaponDamageAt` and `weaponMaxInFlight`. A generated gun is the same shape.
+- `Magazine.pauseReload()` / `resumeReload()` / `isPaused()` suspend a reload and keep its progress; a paused reload is not `isReloading()`, does not advance in `tick`, and round-trips through `snapshot()`/`restore()`.
+- `environment.grading` on the scene document authors a per-game colour grade: shadow/midtone/highlight swatches plus tint, saturation and contrast bake into a small display-space LUT (`lutCubeFromGrading`, `colorGradeFromDocument` in `@jgengine/core/editor/environment`), edited in the Lighting workspace. The shell applies it from `editorLayers`, and a graded game needs no LUT asset or hardcoded pass.
+- Clamped auto-exposure: `postProcessing.autoExposure: { min, max, adaptationSeconds } | false` meters the pre-tone-map frame every four frames toward 18% grey and stays inside the authored range. `WHITE_POINT` and `MID_GREY` in `@jgengine/core/render/colorPipeline` are the single documented calibration the pipeline uses.
+- `GradeConfig.lut` also accepts a baked `{ cube: { size, data } }` LUT, sampled trilinearly after the numeric grade.
+- `MATERIAL_LIBRARY` (`@jgengine/assets/catalogs/materialLibrary`) names 56 PBR surfaces — wet asphalt, painted metal, stucco, brick, wood, foliage with cut-out coverage and sheen, glass, water, sand, concrete and more — each mapping a name to an ambientCG source, a world tile size in metres and a physical response. `libraryMaterialAsset("asphalt/wet")` returns the editable `MaterialAsset` those names resolve to, and `filterLibraryMaterials` backs pickers. `assets pull library` pulls every pinned map set.
+- `TriplanarAssetMaterial` / `useTriplanarAssetMaterial` / `applyTriplanarProjection` (`@jgengine/shell/render/triplanarMaterial`) render a material asset from world position, so world geometry without a `uv` attribute still gets colour, normal, roughness and AO maps. Tile size is world metres; instanced meshes project in instanced space.
+- The editor's Materials workspace browses the library by name and writes the chosen entry into the document's material assets.
+
+### Changed
+
+- `createPerception` (`@jgengine/core/world`, also `@jgengine/core/sensor/perception`) takes `isSegmentClear` instead of `occluded`: the game supplies collision as a "nothing blocks this segment" test, and it is only called for pairs already inside range and cone. **Migration:** flip the predicate — a `occluded: (from, to) => blocked(from, to)` becomes `isSegmentClear: (from, to) => !blocked(from, to)`.
+- `MagazineSnapshot` gains an optional `paused: true` field, present only while a reload is suspended, so existing snapshots and idle shapes are unchanged.
+- AgX is the pipeline's tone map: `postProcessing.toneMapping` defaults to `"agx"`, and the `cinematic`, `photoreal`, `comic`, `retro` and `STUDIO_STAGE_POST` configs now pick it too. `"toon"` keeps `"linear"` on purpose. Games that authored `"aces"` explicitly are unchanged.
+- The grade pass samples LUT tiles at texel centres and blends the blue axis by hand, so a supplied strip LUT no longer bleeds across slices.
+
+### Fixed
+
+- `bun run debug <game>` now finds the server `bun dev` started. The website dev server publishes the same checkout marker the runner does (`scripts/devServerMarker.ts`, written at listen, removed on shutdown, dev builds only), and the marker records the host that answers, since Vite's default `localhost` can be IPv6-only where `127.0.0.1` hangs.
+- The website dev server serves `GET/POST /__jgengine/report` too, so a game opened at `/games/<id>` reports from the `/play` runner it embeds.
+- The in-page sampler installs when the dev report route answers, not on a build-time `PROD` check: the `/play` runner is a production build, so the old check silently disabled the report on `bun dev`.
+- A report taken inside the sampler's warmup is no longer judged on link/framebuffer counts, which only mean something after the warmup baseline exists.
+- `extractMaterialMaps` and `buildMaterialCatalog` now recognise ambientCG's `_Opacity` map, so cut-out foliage and decal scans keep their coverage instead of rendering as solid cards.
+- Capture runs no longer leak a ~150 MB temp Chrome profile each. `shoot`, `drive` and `perf` delete their profile on every exit path — success, throw, watchdog and SIGINT — `bun run shoot` reclaims profiles a killed run left untouched for three hours, the capture guard sweeps the profile of a run it force-kills, and the generated `browser.mjs` harness for game repos removes its own. A capture also refuses to start when the temp drive has less free space than it needs.
+- The post-processing chain, graphics settings and textured terrain material keep a stable identity across renders. Before, every render rebuilt the effect composer and recompiled shaders, which dropped games to single-digit FPS.
+
+### Numbers
+
+- Test fixture at 600 rpm, 30-round magazine: 2.9 s to empty; 17.0° pitch and 3.1° yaw climb over the magazine; back to half climb in 0.37 s and within 5% in 0.6 s; bloom 2.0 → 8.0 → 12.0 mrad (cap) by the tenth shot, settling to base 0.63 s after the last shot.
+- A hitscan and a projectile contact at the same distance return the same damage (20 body, 30 on a 1.5x head zone) through one damage model; a 60 m/s projectile crosses 20 m in 0.33 s and drops 2.45 m in 0.5 s at 9.81 m/s².
+
 ## 0.25.0
 
 ### Migrate

package/dist/LightingPanel.d.ts

@@ -1,8 +1,9 @@
 import type { EditorSession } from "@jgengine/core/editor/index";
 /**
  * Lighting workspace panel — edits `document.environment` (sky preset, time-of-day, intensities,
- * fog, optional horizon/zenith colors) through the session undo stack. No fabricated runtime data:
- * empty document shows defaults as display placeholders; the first edit writes a real bag.
+ * fog, optional horizon/zenith colors, local lights and baked light-probe volumes) through the
+ * session undo stack. No fabricated runtime data: empty document shows defaults as display
+ * placeholders; the first edit writes a real bag.
  *
  * @internal
  */

package/dist/LightingPanel.js

@@ -1,5 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useSyncExternalStore } from "react";
+import { bakeLightProbe } from "@jgengine/core/editor/environment";
+import { editorDocumentBounds } from "@jgengine/core/editor/document";
 import { SliderRow } from "./chromeFields.js";
 import { BORDER, CONTROL, CONTROL_ACTIVE, FOCUS_RING, INPUT_CLS, MICRO_LABEL, PANEL_BG } from "./shell/theme.js";
 const PRESETS = [
@@ -36,10 +38,28 @@ function readDisplay(env) {
         zenithColor: env?.zenithColor ?? DISPLAY_DEFAULTS.zenithColor,
     };
 }
+/**
+ * A new irradiance volume sized to the scene's authored extent: one grid over the whole play space,
+ * so the first bake already covers it. The author shrinks it to a room when it should be enclosed.
+ */
+function newProbe(doc, index) {
+    const bounds = editorDocumentBounds(doc);
+    const halfX = bounds === null ? 30 : Math.max(30, (bounds.max.x - bounds.min.x) / 2 + 12);
+    const halfZ = bounds === null ? 30 : Math.max(30, (bounds.max.z - bounds.min.z) / 2 + 12);
+    return {
+        id: `probes-${index + 1}`,
+        label: `Volume ${index + 1}`,
+        center: [0, 4, 0],
+        size: [Math.round(halfX * 2), 12, Math.round(halfZ * 2)],
+        resolution: [4, 2, 4],
+        bake: { skyVisibility: 0.4, ceilingColor: "#b8b2a4", floorColor: "#494339", fillIntensity: 0.6 },
+    };
+}
 /**
  * Lighting workspace panel — edits `document.environment` (sky preset, time-of-day, intensities,
- * fog, optional horizon/zenith colors) through the session undo stack. No fabricated runtime data:
- * empty document shows defaults as display placeholders; the first edit writes a real bag.
+ * fog, optional horizon/zenith colors, local lights and baked light-probe volumes) through the
+ * session undo stack. No fabricated runtime data: empty document shows defaults as display
+ * placeholders; the first edit writes a real bag.
  *
  * @internal
  */
@@ -50,6 +70,25 @@ export function LightingPanel({ session }) {
     const authored = env !== undefined;
     const source = env?.source;
     const pointLights = env?.pointLights ?? [];
+    const probes = env?.probes ?? [];
+    const grading = env?.grading;
+    const exposure = grading?.autoExposure;
+    const setGrading = (next) => {
+        const base = { ...(env ?? {}) };
+        if (next === undefined || Object.keys(next).length === 0)
+            delete base.grading;
+        else
+            base.grading = next;
+        commit(Object.keys(base).length === 0 ? undefined : base, "env:grading");
+    };
+    const patchGrading = (partial) => {
+        const next = { ...(grading ?? {}), ...partial };
+        for (const key of Object.keys(next)) {
+            if (next[key] === undefined)
+                delete next[key];
+        }
+        setGrading(next);
+    };
     const commit = (next, coalesce) => {
         session.dispatch({ type: "setEnvironment", environment: next }, coalesce === undefined ? undefined : { coalesce });
     };
@@ -74,7 +113,15 @@ export function LightingPanel({ session }) {
                                 ? { kind, sky: "#87b5e0", ground: "#3d4a38" }
                                 : kind === "hdri" ? { kind, url: "" } : { kind, urls: ["", "", "", "", "", ""] };
                             patch({ source: nextSource }, "env:source");
-                        }, children: [_jsx("option", { value: "gradient", children: "Gradient" }), _jsx("option", { value: "hdri", children: "HDRI / EXR" }), _jsx("option", { value: "cube", children: "Cube map" })] }), source?.kind === "hdri" ? (_jsx("input", { className: `w-full px-2 py-1 ${INPUT_CLS}`, placeholder: "https://\u2026/environment.hdr", value: source.url, onChange: (event) => patch({ source: { ...source, url: event.target.value } }, "env:sourceUrl") })) : null, source?.kind === "cube" ? (_jsx("input", { className: `w-full px-2 py-1 ${INPUT_CLS}`, placeholder: " six face URLs, comma-separated", value: source.urls.join(","), onChange: (event) => patch({ source: { ...source, urls: event.target.value.split(",").slice(0, 6) } }, "env:sourceCube") })) : null] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsx("span", { className: MICRO_LABEL, children: "Sun & ambient" }), _jsx(SliderRow, { label: "sun", value: display.sunIntensity, min: 0, max: 3, step: 0.05, onChange: (value) => patch({ sunIntensity: value }, "env:sun"), format: (v) => v.toFixed(2) }), _jsx(SliderRow, { label: "ambient", value: display.ambientIntensity, min: 0, max: 2, step: 0.05, onChange: (value) => patch({ ambientIntensity: value }, "env:ambient"), format: (v) => v.toFixed(2) }), _jsx(SliderRow, { label: "bearing", value: display.sunAzimuth, min: 0, max: 360, step: 1, onChange: (value) => patch({ sunAzimuth: value }, "env:sunAzimuth"), format: (v) => `${Math.round(v)}°` }), _jsx(SliderRow, { label: "height", value: display.sunElevation, min: 0, max: 90, step: 1, onChange: (value) => patch({ sunElevation: value }, "env:sunElevation"), format: (v) => `${Math.round(v)}°` })] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsx("span", { className: MICRO_LABEL, children: "Fog" }), _jsx(SliderRow, { label: "near", value: display.fogNear, min: 0, max: 500, step: 1, onChange: (value) => patch({ fog: { near: value } }, "env:fogNear"), format: (v) => `${Math.round(v)}m` }), _jsx(SliderRow, { label: "far", value: display.fogFar, min: 10, max: 2000, step: 5, onChange: (value) => patch({ fog: { far: value } }, "env:fogFar"), format: (v) => `${Math.round(v)}m` }), _jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "color" }), _jsx("input", { type: "text", className: `w-36 px-2 py-1 ${INPUT_CLS}`, placeholder: "#a8c4d8", value: display.fogColor, onChange: (event) => {
+                        }, children: [_jsx("option", { value: "gradient", children: "Gradient" }), _jsx("option", { value: "hdri", children: "HDRI / EXR" }), _jsx("option", { value: "cube", children: "Cube map" })] }), source?.kind === "hdri" ? (_jsx("input", { className: `w-full px-2 py-1 ${INPUT_CLS}`, placeholder: "https://\u2026/environment.hdr", value: source.url, onChange: (event) => patch({ source: { ...source, url: event.target.value } }, "env:sourceUrl") })) : null, source?.kind === "cube" ? (_jsx("input", { className: `w-full px-2 py-1 ${INPUT_CLS}`, placeholder: " six face URLs, comma-separated", value: source.urls.join(","), onChange: (event) => patch({ source: { ...source, urls: event.target.value.split(",").slice(0, 6) } }, "env:sourceCube") })) : null] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("span", { className: MICRO_LABEL, children: "Light probes" }), _jsxs("div", { className: "flex gap-1", children: [_jsx("button", { type: "button", className: `${CONTROL} px-2 py-1 text-[10px]`, title: "Add an irradiance volume around the scene centre, then bake it", onClick: () => patch({ probes: [...probes, newProbe(state.document, probes.length)] }, "env:probes"), children: "Add" }), _jsx("button", { type: "button", className: `${CONTROL} px-2 py-1 text-[10px]`, disabled: probes.length === 0, title: "Re-bake every volume from the document's lamps and its authored fill", onClick: () => commit({ ...(env ?? {}), probes: probes.map((probe) => bakeLightProbe(probe, state.document)) }, "env:probes"), children: "Bake" })] })] }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Ambient baked per volume: interiors take their own fill instead of the sky's." }), probes.map((probe, index) => (_jsxs("div", { className: "rounded border border-white/[0.06] p-1.5", children: [_jsxs("div", { className: "mb-1 flex items-center justify-between text-[10px] text-neutral-400", children: [_jsx("span", { children: probe.label ?? probe.id }), _jsxs("div", { className: "flex gap-1", children: [_jsx("button", { type: "button", className: `${CONTROL} px-1.5 py-0.5 text-[9px]`, title: "Bake this volume from the document's lamps", onClick: () => {
+                                                    const next = [...probes];
+                                                    next[index] = bakeLightProbe(probe, state.document);
+                                                    patch({ probes: next }, "env:probes");
+                                                }, children: "Bake" }), _jsx("button", { type: "button", className: `${CONTROL} px-1.5 py-0.5 text-[9px]`, onClick: () => patch({ probes: probes.filter((_, i) => i !== index) }, "env:probes"), children: "Remove" })] })] }), _jsx(SliderRow, { label: "sky reach", value: probe.bake?.skyVisibility ?? 0.4, min: 0, max: 1, step: 0.05, format: (v) => (v <= 0.001 ? "enclosed" : v.toFixed(2)), onChange: (value) => {
+                                    const next = [...probes];
+                                    next[index] = { ...probe, bake: { ...(probe.bake ?? {}), skyVisibility: value } };
+                                    patch({ probes: next }, "env:probes");
+                                } }), _jsxs("div", { className: "text-[9px] text-neutral-500", children: [probe.samples === undefined ? "not baked" : `${probe.resolution.join("×")} probes baked`, " \u00B7 ", probe.size.map((extent) => Math.round(extent)).join("×"), " m"] })] }, probe.id)))] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsx("span", { className: MICRO_LABEL, children: "Sun & ambient" }), _jsx(SliderRow, { label: "sun", value: display.sunIntensity, min: 0, max: 3, step: 0.05, onChange: (value) => patch({ sunIntensity: value }, "env:sun"), format: (v) => v.toFixed(2) }), _jsx(SliderRow, { label: "ambient", value: display.ambientIntensity, min: 0, max: 2, step: 0.05, onChange: (value) => patch({ ambientIntensity: value }, "env:ambient"), format: (v) => v.toFixed(2) }), _jsx(SliderRow, { label: "bearing", value: display.sunAzimuth, min: 0, max: 360, step: 1, onChange: (value) => patch({ sunAzimuth: value }, "env:sunAzimuth"), format: (v) => `${Math.round(v)}°` }), _jsx(SliderRow, { label: "height", value: display.sunElevation, min: 0, max: 90, step: 1, onChange: (value) => patch({ sunElevation: value }, "env:sunElevation"), format: (v) => `${Math.round(v)}°` })] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsx("span", { className: MICRO_LABEL, children: "Fog" }), _jsx(SliderRow, { label: "near", value: display.fogNear, min: 0, max: 500, step: 1, onChange: (value) => patch({ fog: { near: value } }, "env:fogNear"), format: (v) => `${Math.round(v)}m` }), _jsx(SliderRow, { label: "far", value: display.fogFar, min: 10, max: 2000, step: 5, onChange: (value) => patch({ fog: { far: value } }, "env:fogFar"), format: (v) => `${Math.round(v)}m` }), _jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "color" }), _jsx("input", { type: "text", className: `w-36 px-2 py-1 ${INPUT_CLS}`, placeholder: "#a8c4d8", value: display.fogColor, onChange: (event) => {
                                     const color = event.target.value.trim();
                                     const fog = { ...(env?.fog ?? {}) };
                                     if (color.length === 0)
@@ -87,7 +134,7 @@ export function LightingPanel({ session }) {
                                     else
                                         next.fog = fog;
                                     commit(Object.keys(next).length === 0 ? undefined : next, "env:fogColor");
-                                } })] })] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsx("span", { className: MICRO_LABEL, children: "Sky colors (optional)" }), _jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "horizon" }), _jsx("input", { type: "text", className: `w-36 px-2 py-1 ${INPUT_CLS}`, placeholder: "#87ceeb", value: display.horizonColor, onChange: (event) => {
+                                } })] })] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsxs("div", { className: "flex items-center justify-between", children: [_jsx("span", { className: MICRO_LABEL, children: "Colour grade" }), grading === undefined ? null : (_jsx("button", { type: "button", className: `${CONTROL} px-2 py-1 text-[10px]`, title: "Remove the authored grade; the game's own post chain applies unchanged", onClick: () => setGrading(undefined), children: "Clear" }))] }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Baked into a small LUT applied after tone mapping. Swatches tint their band; white leaves it alone." }), _jsx("div", { className: "grid grid-cols-3 gap-1", children: [["shadows", "shadows", "#2a3a52"], ["midtones", "mid", "#e8e2d6"], ["highlights", "high", "#ffe9c4"]].map(([key, label, placeholder]) => (_jsxs("label", { className: "flex flex-col gap-1 rounded border border-white/[0.06] p-1", children: [_jsx("span", { className: "text-[9px] uppercase tracking-wider text-neutral-500", children: label }), _jsxs("div", { className: "flex items-center gap-1", children: [_jsx("input", { type: "color", "aria-label": `Grade ${label} tint`, value: grading?.[key] ?? placeholder, onChange: (event) => patchGrading({ [key]: event.target.value }) }), grading?.[key] === undefined ? null : (_jsx("button", { type: "button", "aria-label": `Clear ${label} tint`, className: `${CONTROL} px-1 py-0.5 text-[9px]`, onClick: () => patchGrading({ [key]: undefined }), children: "\u00D7" }))] })] }, key))) }), _jsx(SliderRow, { label: "tint", value: grading?.tint ?? 0.45, min: 0, max: 1, step: 0.01, onChange: (value) => patchGrading({ tint: value }), format: (v) => v.toFixed(2) }), _jsx(SliderRow, { label: "saturation", value: grading?.saturation ?? 1, min: 0, max: 2, step: 0.01, onChange: (value) => patchGrading({ saturation: value }), format: (v) => v.toFixed(2) }), _jsx(SliderRow, { label: "contrast", value: grading?.contrast ?? 1, min: 0.5, max: 1.6, step: 0.01, onChange: (value) => patchGrading({ contrast: value }), format: (v) => v.toFixed(2) }), _jsx(SliderRow, { label: "min exposure", value: exposure?.min ?? 0.5, min: 0.1, max: 1, step: 0.05, onChange: (value) => patchGrading({ autoExposure: { ...(exposure ?? {}), min: value } }), format: (v) => `${v.toFixed(2)}×` }), _jsx(SliderRow, { label: "max exposure", value: exposure?.max ?? 2.5, min: 1, max: 6, step: 0.05, onChange: (value) => patchGrading({ autoExposure: { ...(exposure ?? {}), max: value } }), format: (v) => `${v.toFixed(2)}×` }), _jsx("div", { className: "text-[10px] text-neutral-500", children: "Auto-exposure meters the frame toward 18% grey and stays inside this range, so a dark room lifts instead of crushing." })] }), _jsxs("section", { className: "space-y-1.5 border-t border-white/[0.05] pt-2", children: [_jsx("span", { className: MICRO_LABEL, children: "Sky colors (optional)" }), _jsxs("label", { className: "flex items-center justify-between gap-2", children: [_jsx("span", { className: "text-[9px] font-semibold uppercase tracking-wider text-neutral-500", children: "horizon" }), _jsx("input", { type: "text", className: `w-36 px-2 py-1 ${INPUT_CLS}`, placeholder: "#87ceeb", value: display.horizonColor, onChange: (event) => {
                                     const horizonColor = event.target.value.trim();
                                     if (horizonColor.length === 0) {
                                         const next = { ...(env ?? {}) };

package/dist/MaterialLibraryBrowser.d.ts

@@ -0,0 +1,17 @@
+import type { MaterialAsset } from "@jgengine/core/material/materialAsset";
+/** Adopting a library name writes a real, editable material asset into the scene document. */
+export interface MaterialLibraryBrowserProps {
+    /** URL prefix the pulled maps resolve under; matches `assets pull library --dir <public>`. */
+    basePath?: string;
+    /** Called with the asset the author should now assign to a mesh or slot. */
+    onAdopt(asset: MaterialAsset): void;
+    /** Reports a name that could not be built, so a broken library entry is visible instead of silent. */
+    onError(message: string): void;
+}
+/**
+ * Browses the shared ambientCG material library by name and adds one entry to the document's
+ * material assets. Names, response parameters and CC0 attribution come from `@jgengine/assets`;
+ * this panel owns presentation only.
+ * @internal Mounted by the materials workspace.
+ */
+export declare function MaterialLibraryBrowser({ basePath, onAdopt, onError }: MaterialLibraryBrowserProps): import("react").JSX.Element;

package/dist/MaterialLibraryBrowser.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { filterLibraryMaterials, libraryMaterialAsset } from "@jgengine/assets/catalogs/materialLibrary";
+import { useMemo, useState } from "react";
+import { FOCUS_RING, INPUT_CLS, MICRO_LABEL } from "./shell/theme.js";
+/**
+ * Browses the shared ambientCG material library by name and adds one entry to the document's
+ * material assets. Names, response parameters and CC0 attribution come from `@jgengine/assets`;
+ * this panel owns presentation only.
+ * @internal Mounted by the materials workspace.
+ */
+export function MaterialLibraryBrowser({ basePath = "/materials", onAdopt, onError }) {
+    const [query, setQuery] = useState("");
+    const rows = useMemo(() => filterLibraryMaterials(query), [query]);
+    const adopt = (name) => {
+        try {
+            onAdopt(libraryMaterialAsset(name, { basePath }));
+        }
+        catch (error) {
+            onError(error instanceof Error ? error.message : String(error));
+        }
+    };
+    return _jsxs("details", { className: "rounded-[6px] border border-white/[0.07] bg-white/[0.02]", children: [_jsxs("summary", { className: `cursor-pointer p-2 text-[11px] text-neutral-300 ${FOCUS_RING}`, children: ["Material library (", rows.length, ")"] }), _jsxs("div", { className: "space-y-2 px-2 pb-2", children: [_jsx("input", { type: "search", value: query, onChange: (event) => setQuery(event.target.value), placeholder: "Filter by name, group or source\u2026", "aria-label": "Filter material library", className: `h-7 w-full px-2 ${INPUT_CLS}` }), _jsxs("p", { className: "text-[10px] leading-snug text-neutral-500", children: ["ambientCG PBR surfaces, pulled per source with ", _jsx("code", { children: "assets pull library" }), ". Adding one creates a reusable asset; assign it to a mesh slot or world surface."] }), _jsxs("div", { className: "max-h-64 space-y-0.5 overflow-auto", role: "list", "aria-label": "Material library", children: [rows.map((entry) => _jsxs("button", { type: "button", role: "listitem", onClick: () => adopt(entry.name), title: `${entry.name}${entry.source === undefined ? " (shader surface)" : ` · ${entry.source}`}`, className: `block w-full rounded-[5px] px-1.5 py-1 text-left hover:bg-white/[0.04] ${FOCUS_RING}`, children: [_jsx("span", { className: "block truncate text-[11px] text-neutral-200", children: entry.title }), _jsxs("span", { className: "block truncate text-[9px] text-neutral-600", children: [entry.name, " \u00B7 ", entry.group, " \u00B7 ", entry.surface, " \u00B7 ", entry.tileMetres, " m tile"] })] }, entry.name)), rows.length === 0 ? _jsxs("p", { className: "px-1.5 py-1 text-[10px] text-neutral-500", children: ["No library material matches \u201C", query, "\u201D."] }) : null] }), _jsxs("div", { className: MICRO_LABEL, children: [rows.length, " of ", filterLibraryMaterials("").length, " materials"] })] })] });
+}

package/dist/MaterialsWorkspacePanel.js

@@ -3,6 +3,7 @@ import { useEffect, useMemo, useState } from "react";
 import { createMaterialTemplate, parseMaterialAssignments } from "@jgengine/core/material/materialAsset";
 import { clearMaterialAssignmentPatch } from "./authoredComponentMeta.js";
 import { MaterialAssetEditor } from "./MaterialAssetEditor.js";
+import { MaterialLibraryBrowser } from "./MaterialLibraryBrowser.js";
 import { filterMaterialAssignments, listMaterialAssignments, summarizeMaterialUsage, } from "./materialAssignments.js";
 import { TERRAIN_MATERIALS } from "./uiStore.js";
 import { FOCUS_RING, INPUT_CLS, MICRO_LABEL } from "./shell/theme.js";
@@ -115,7 +116,12 @@ export function MaterialsWorkspacePanel({ session, api, preview, onSave, materia
     };
     const tabs = _jsx("div", { className: "flex shrink-0 gap-1 border-b border-white/[0.06] p-2", role: "tablist", "aria-label": "Material workspace views", children: ["assets", "assignments"].map((view) => _jsx("button", { type: "button", role: "tab", "aria-selected": tab === view, className: `${CHIP} flex-1 ${tab === view ? CHIP_ACTIVE : CHIP_IDLE}`, onClick: () => setTab(view), children: view === "assets" ? "Surface assets" : "Legacy assignments" }, view)) });
     if (tab === "assets")
-        return _jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [tabs, _jsxs("div", { className: "min-h-0 flex-1 overflow-auto", children: [_jsxs("div", { className: "space-y-2 border-b border-white/[0.06] p-2", children: [_jsxs("label", { className: "block space-y-1", children: [_jsx("span", { className: MICRO_LABEL, children: "Reusable material asset" }), _jsx("select", { "aria-label": "Choose material asset", value: activeAsset?.id ?? "", className: `w-full px-2 py-1 ${INPUT_CLS}`, onChange: (event) => setActiveAssetId(event.target.value), children: assets.length ? assets.map((asset) => _jsx("option", { value: asset.id, children: asset.name }, asset.id)) : _jsx("option", { value: "", children: "No authored materials" }) })] }), activeAsset ? _jsx("button", { type: "button", className: `${CHIP} border-rose-400/25 text-rose-200`, onClick: () => { const result = api.handle({ method: "remove_material_asset", id: activeAsset.id }); setError(result.ok ? null : result.error ?? "Material operation failed."); }, children: "Remove unused asset" }) : null, _jsxs("details", { children: [_jsx("summary", { className: `cursor-pointer text-[11px] text-neutral-400 ${FOCUS_RING}`, children: "Create from an editable starting point" }), _jsxs("div", { className: "mt-2 space-y-2", children: [_jsx("select", { "aria-label": "Material starting point", className: `w-full px-2 py-1 ${INPUT_CLS}`, value: template, onChange: (event) => setTemplate(event.target.value), children: ["wool", "cotton", "silk", "brushed-metal", "glass", "coated-plastic", "stone", "hair-cards"].map((entry) => _jsx("option", { value: entry, children: entry }, entry)) }), _jsx("input", { "aria-label": "New material stable ID", value: newId, onChange: (event) => setNewId(event.target.value), placeholder: "game/my-original-surface", className: `w-full px-2 py-1 ${INPUT_CLS}` }), _jsx("button", { type: "button", disabled: !newId.trim() || assets.some((asset) => asset.id === newId.trim()), className: `${CHIP} ${CHIP_IDLE}`, onClick: () => { const asset = createMaterialTemplate(template, newId.trim()); const result = api.handle({ method: "upsert_material_asset", asset }); if (!result.ok)
+        return _jsxs("div", { className: "flex min-h-0 flex-1 flex-col", children: [tabs, _jsxs("div", { className: "min-h-0 flex-1 overflow-auto", children: [_jsxs("div", { className: "space-y-2 border-b border-white/[0.06] p-2", children: [_jsxs("label", { className: "block space-y-1", children: [_jsx("span", { className: MICRO_LABEL, children: "Reusable material asset" }), _jsx("select", { "aria-label": "Choose material asset", value: activeAsset?.id ?? "", className: `w-full px-2 py-1 ${INPUT_CLS}`, onChange: (event) => setActiveAssetId(event.target.value), children: assets.length ? assets.map((asset) => _jsx("option", { value: asset.id, children: asset.name }, asset.id)) : _jsx("option", { value: "", children: "No authored materials" }) })] }), activeAsset ? _jsx("button", { type: "button", className: `${CHIP} border-rose-400/25 text-rose-200`, onClick: () => { const result = api.handle({ method: "remove_material_asset", id: activeAsset.id }); setError(result.ok ? null : result.error ?? "Material operation failed."); }, children: "Remove unused asset" }) : null, _jsx(MaterialLibraryBrowser, { onAdopt: (asset) => { const result = api.handle({ method: "upsert_material_asset", asset }); if (result.ok) {
+                                        setActiveAssetId(asset.id);
+                                        setError(null);
+                                    }
+                                    else
+                                        setError(result.error ?? "Material operation failed."); }, onError: setError }), _jsxs("details", { children: [_jsx("summary", { className: `cursor-pointer text-[11px] text-neutral-400 ${FOCUS_RING}`, children: "Create from an editable starting point" }), _jsxs("div", { className: "mt-2 space-y-2", children: [_jsx("select", { "aria-label": "Material starting point", className: `w-full px-2 py-1 ${INPUT_CLS}`, value: template, onChange: (event) => setTemplate(event.target.value), children: ["wool", "cotton", "silk", "brushed-metal", "glass", "coated-plastic", "stone", "hair-cards"].map((entry) => _jsx("option", { value: entry, children: entry }, entry)) }), _jsx("input", { "aria-label": "New material stable ID", value: newId, onChange: (event) => setNewId(event.target.value), placeholder: "game/my-original-surface", className: `w-full px-2 py-1 ${INPUT_CLS}` }), _jsx("button", { type: "button", disabled: !newId.trim() || assets.some((asset) => asset.id === newId.trim()), className: `${CHIP} ${CHIP_IDLE}`, onClick: () => { const asset = createMaterialTemplate(template, newId.trim()); const result = api.handle({ method: "upsert_material_asset", asset }); if (!result.ok)
                                                         setError(result.error ?? "Material operation failed.");
                                                     else {
                                                         setActiveAssetId(asset.id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/editor",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Scene/world/asset editor for JGengine — loaded lazily by the runner; never import from game entrypoints.",
   "license": "Apache-2.0",
   "type": "module",
@@ -31,10 +31,11 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.25.0",
-    "@jgengine/navbake": "^0.25.0",
-    "@jgengine/react": "^0.25.0",
-    "@jgengine/shell": "^0.25.0"
+    "@jgengine/assets": "^0.26.0",
+    "@jgengine/core": "^0.26.0",
+    "@jgengine/navbake": "^0.26.0",
+    "@jgengine/react": "^0.26.0",
+    "@jgengine/shell": "^0.26.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.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -82,25 +82,42 @@
 - `Devtools` (interface): interface Devtools — Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes.
 - `DevtoolsControl` (interface): interface DevtoolsControl — Registered tunable control with its resolved schema metadata and read/write/reset accessors.
 - `DevtoolsControlKind` (type): type DevtoolsControlKind = | "slider" | "toggle" | "color" | "select" | "text" | "vec2" | "vec3" | "vec4" | "interval" | "angle" | "enum" — ⚠ undocumented
-- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, and formatted message.
+- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, owning system tag, and formatted message.
 - `DevtoolsLogLevel` (type): type DevtoolsLogLevel = "log" | "info" | "warn" | "error" — Severity level for a captured devtools log entry.
+- `DevtoolsLogs` (interface): interface DevtoolsLogs — Bounded log ring with per-system tags, a warning/error ring, and lifetime counts.
 - `DevtoolsOverrides` (interface): interface DevtoolsOverrides { version: number; enabled: string[]; values: Record<string, unknown>; schemas?: Record<string, {kind: DevtoolsControlKind; schemaVersion?: number}> } — ⚠ undocumented
 - `DevtoolsSnapshot` (interface): interface DevtoolsSnapshot — Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields.
 - `DiscoveredEntry` (interface): interface DiscoveredEntry — A control auto-discovered by scanning an object/table, with its binding metadata and current reader.
 - `DiscoverySkip` (interface): interface DiscoverySkip { readonly path: string; readonly reason: string } — ⚠ undocumented
 - `FrameRecordSample` (interface): interface FrameRecordSample — Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations.
 - `FrameStats` (interface): interface FrameStats — Aggregated frame-timing statistics over the recent sampling window, including per-phase breakdown.
-- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget).
+- `FrameWindow` (interface): interface FrameWindow — Frame timings over the measured window, as the player sees them.
+- `GlReport` (interface): interface GlReport — GPU-object creation counts. `total` is since the page loaded, the named fields since warmup.
+- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — The one perf record shape. `bun run perf` (CDP, out of process) and the in-page telemetry report (`window.__JG.report()`, the dev-server route, `bun run debug`) both produce exactly this object, so a budget check and a diff read either one.
 - `LatencyStats` (interface): interface LatencyStats — Aggregated latency statistics (last/avg/min/max) over recorded latency samples.
+- `LogBusCounts` (interface): interface LogBusCounts — Lifetime totals per level, plus how many lines the ring dropped.
+- `LogBusEntry` (interface): interface LogBusEntry — One captured line: when, how bad, which system said it, and what it said.
+- `LogBusSnapshot` (interface): interface LogBusSnapshot — Read-out of the log bus: newest-window entries, the warning/error ring, totals, and evictions.
 - `LongFrameEvent` (interface): interface LongFrameEvent — Recorded spike event for a frame that exceeded the long-frame threshold, with culprit attribution.
 - `NormalizedColor` (interface): interface NormalizedColor { readonly hex: string; readonly rgb: string; readonly alpha: number; readonly hasAlpha: boolean } — ⚠ undocumented
 - `OVERRIDES_FORMAT_VERSION` (const): const OVERRIDES_FORMAT_VERSION: 1 — ⚠ undocumented
 - `OverrideApplyDiagnostic` (interface): interface OverrideApplyDiagnostic { readonly id: string; readonly reason: string } — ⚠ undocumented
 - `OverrideApplyResult` (interface): interface OverrideApplyResult — Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics.
+- `PerfQuality` (type): type PerfQuality = "full" | "draft" — Graphics tier the record was measured at.
+- `PerfReport` (interface): interface PerfReport — One measured window of one game: the record `bun run perf`, `window.__JG.report()` and `bun run debug` print.
 - `PhaseStats` (interface): interface PhaseStats — Timing summary for a single named profiling phase across the sampling window.
+- `ProfileEntry` (interface): interface ProfileEntry — One sampled stack frame reduced to a readable key and its self time.
+- `ProfileReport` (interface): interface ProfileReport — CPU profile summary; only the CDP harness can produce one.
+- `RenderReport` (interface): interface RenderReport — Renderer-side counts for the measured window; `null` where the source could not read them.
 - `RenderSample` (interface): interface RenderSample — Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame.
+- `ReportLogLine` (interface): interface ReportLogLine — One log line as it appears in the report.
+- `ReportLogs` (interface): interface ReportLogs — Bounded log read-out carried by the report: warn/error lines survive even a flood of info logs.
+- `ReportTelemetry` (interface): interface ReportTelemetry — Who produced the report, and how much producing it cost.
 - `ScanFieldMeta` (interface): interface ScanFieldMeta extends TunableOptions { kind?: DevtoolsControlKind } — ⚠ undocumented
 - `ScanMeta` (type): type ScanMeta = Readonly<Record<string, ScanFieldMeta>> — ⚠ undocumented
+- `SceneNodeSource` (type): type SceneNodeSource = "scene-graph" | "heap-object3d" | "unavailable" — Where the scene-node count came from: the live scene graph, a heap walk, or nowhere.
+- `SystemProbe` (interface): interface SystemProbe — What one system reports about itself: totals it keeps anyway, named timings, and one state line.
+- `SystemProbeReading` (interface): interface SystemProbeReading — One system's probe read out on demand; missing sections stay empty rather than absent.
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 - `TunableChoice` (interface): interface TunableChoice<T = unknown> { readonly value: T; readonly label?: string } — ⚠ undocumented
@@ -139,9 +156,20 @@
 ## @jgengine/core/devtools/frame
 
 - `FrameModule` (interface): interface FrameModule — Frame subsystem exposing the frame-timing, profiling, and render-sample facades.
-- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget).
 - `createFrameModule` (const): const createFrameModule: (deps: { readProbes: () => Record<string, unknown>; }) => FrameModule — Create the frame subsystem that records frame/sim/phase timings, computes stats, and captures long-frame events.
 
+## @jgengine/core/devtools/logBus
+
+- `LOG_BUS_CAPACITY` (const): const LOG_BUS_CAPACITY: 200 — Default measured window for the log ring; older lines are evicted, never grown.
+- `LOG_BUS_MESSAGE_MAX` (const): const LOG_BUS_MESSAGE_MAX: 400 — Longest kept message; a longer one is cut once, at write time.
+- `LOG_BUS_SEVERE_CAPACITY` (const): const LOG_BUS_SEVERE_CAPACITY: 64 — Warnings and errors also land in their own ring, so an error is never pushed out by info traffic.
+- `LogBus` (interface): interface LogBus — A fixed-capacity ring of log lines tagged by owning system. `write` reuses a preallocated slot — no array growth, no splice, no per-write object — so a hot path can call it and only the message string (already built by the caller) costs an allocation.
+- `LogBusCounts` (interface): interface LogBusCounts — Lifetime totals per level, plus how many lines the ring dropped.
+- `LogBusEntry` (interface): interface LogBusEntry — One captured line: when, how bad, which system said it, and what it said.
+- `LogBusOptions` (interface): interface LogBusOptions — Tunables for the log ring: capacity, the severity ring's capacity, and the clock.
+- `LogBusSnapshot` (interface): interface LogBusSnapshot — Read-out of the log bus: newest-window entries, the warning/error ring, totals, and evictions.
+- `createLogBus` (function): function createLogBus(options: LogBusOptions = {}): LogBus — Create the bounded log bus the devtools log facade writes through.
+
 ## @jgengine/core/devtools/logs
 
 - `LogsModule` (interface): interface LogsModule — Logs subsystem exposing the log-capture and latency-tracking facades.
@@ -153,6 +181,27 @@
 - `OverridesModule` (interface): interface OverridesModule — Overrides subsystem exposing the export/apply facade for persisting and restoring control values.
 - `createOverridesModule` (const): const createOverridesModule: (deps: { signal: ChangeSignal; controlRecords: Map<string, ControlRecord>; writeControl: (record: ControlRecord, raw: unknown) => boolean; discoveredRecords: Map<string, DiscoveredRecord>; enableDiscovered: (id: string) => void; }) => OverridesModule — Create the overrides subsystem that serializes changed control values and re-applies a saved overrides payload.
 
+## @jgengine/core/devtools/report
+
+- `FrameWindow` (interface): interface FrameWindow — Frame timings over the measured window, as the player sees them.
+- `GlReport` (interface): interface GlReport — GPU-object creation counts. `total` is since the page loaded, the named fields since warmup.
+- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — The one perf record shape. `bun run perf` (CDP, out of process) and the in-page telemetry report (`window.__JG.report()`, the dev-server route, `bun run debug`) both produce exactly this object, so a budget check and a diff read either one.
+- `PerfQuality` (type): type PerfQuality = "full" | "draft" — Graphics tier the record was measured at.
+- `PerfReport` (interface): interface PerfReport — One measured window of one game: the record `bun run perf`, `window.__JG.report()` and `bun run debug` print.
+- `ProfileEntry` (interface): interface ProfileEntry — One sampled stack frame reduced to a readable key and its self time.
+- `ProfileReport` (interface): interface ProfileReport — CPU profile summary; only the CDP harness can produce one.
+- `RenderReport` (interface): interface RenderReport — Renderer-side counts for the measured window; `null` where the source could not read them.
+- `ReportLogLine` (interface): interface ReportLogLine — One log line as it appears in the report.
+- `ReportLogs` (interface): interface ReportLogs — Bounded log read-out carried by the report: warn/error lines survive even a flood of info logs.
+- `ReportTelemetry` (interface): interface ReportTelemetry — Who produced the report, and how much producing it cost.
+- `SceneNodeSource` (type): type SceneNodeSource = "scene-graph" | "heap-object3d" | "unavailable" — Where the scene-node count came from: the live scene graph, a heap walk, or nowhere.
+
+## @jgengine/core/devtools/reportEndpoint
+
+- `REPORT_ENDPOINT_PATH` (const): const REPORT_ENDPOINT_PATH: "/__jgengine/report" — The dev-only route a running game pushes its in-page report to, and that `bun run debug <game>` reads back. One process: the page gathers, the dev server holds the newest record per game, the CLI fetches it. Nothing here ships in a production build — the Vite plugin mounts it under `apply: "serve"`.
+- `ReportPushBody` (interface): interface ReportPushBody — Body the page POSTs: the game it measured and the record itself.
+- `ReportRouteError` (interface): interface ReportRouteError — Body sent when there is nothing to return yet.
+
 ## @jgengine/core/devtools/rewriteTunables
 
 - `TunableDelta` (interface): interface TunableDelta — One changed tunable to write back into game source: which table, key path, and new value.
@@ -203,8 +252,10 @@
 
 - `Devtools` (interface): interface Devtools — Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes.
 - `DevtoolsControl` (interface): interface DevtoolsControl — Registered tunable control with its resolved schema metadata and read/write/reset accessors.
-- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, and formatted message.
+- `DevtoolsLatency` (interface): interface DevtoolsLatency — Latency samples recorded by instrumented transport methods.
+- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, owning system tag, and formatted message.
 - `DevtoolsLogLevel` (type): type DevtoolsLogLevel = "log" | "info" | "warn" | "error" — Severity level for a captured devtools log entry.
+- `DevtoolsLogs` (interface): interface DevtoolsLogs — Bounded log ring with per-system tags, a warning/error ring, and lifetime counts.
 - `DevtoolsSnapshot` (interface): interface DevtoolsSnapshot — Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields.
 - `DiscoveredEntry` (interface): interface DiscoveredEntry — A control auto-discovered by scanning an object/table, with its binding metadata and current reader.
 - `FrameRecordSample` (interface): interface FrameRecordSample — Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations.
@@ -214,6 +265,8 @@
 - `OverrideApplyResult` (interface): interface OverrideApplyResult — Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics.
 - `PhaseStats` (interface): interface PhaseStats — Timing summary for a single named profiling phase across the sampling window.
 - `RenderSample` (interface): interface RenderSample — Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame.
+- `SystemProbe` (interface): interface SystemProbe — What one system reports about itself: totals it keeps anyway, named timings, and one state line.
+- `SystemProbeReading` (interface): interface SystemProbeReading — One system's probe read out on demand; missing sections stay empty rather than absent.
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
@@ -232,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.25.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine/capabilities.md

@@ -48,6 +48,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineSystem` (function) · `import { defineSystem } from "@jgengine/shell/gameKit"`
 
+## devtools-log-bus — a bounded, per-system-tagged log ring a system writes to and a report reads
+
+- `LogBus` (interface) · `import { LogBus } from "@jgengine/core/devtools/logBus"`
+
 ## editor-catalogs — Export typed gameplay catalogs for in-editor tuning.
 
 - `EditorCatalogDefinition` (interface) · `import { EditorCatalogDefinition } from "@jgengine/shell/gameKit"`

package/skills/jgengine-editor/api.md

@@ -15,15 +15,18 @@
 - `DirectiveFootprint` (interface): interface DirectiveFootprint — A resolved directive footprint: the XZ bounds to scatter within, plus an optional clip polygon.
 - `DirectiveInstancePatch` (interface): interface DirectiveInstancePatch — A per-instance hand-tweak over a materialized directive, keyed by the minted instance id.
 - `DocumentBakeOptions` (interface): interface DocumentBakeOptions extends MinimapBakeOptions — Options for {@link bakeMinimapFromDocument}.
+- `DocumentColorGrade` (interface): interface DocumentColorGrade — The renderer-facing result of a document's authored grade.
 - `DocumentLiveEvent` (interface): interface DocumentLiveEvent — Event emitted when the authoritative document changes on a {@link DocumentLiveSync}.
 - `DocumentLiveSync` (interface): interface DocumentLiveSync — Two-way live-sync bus: document patches out, runtime state deltas back.
 - `DocumentPatch` (type): type DocumentPatch = | { type: "snapshot"; revision?: number; baseRevision: number; document: EditorDocument; } | { type: "commands"; revision?: number; baseRevision: number; commands: readonly EditorCommand[]; } — One versioned document mutation on the live-sync stream. `snapshot` replaces the whole document; `commands` replays structural editor commands onto the current document. `baseRevision` must match the receiver's current revision unless `force` is set (document authority from the editor). `revision` preserves the authority cursor when replaying: snapshots may jump forward for reconnect recovery; commands must be the next revision.
 - `ENTITY_CATALOG_ID` (const): const ENTITY_CATALOG_ID: "entities" — Well-known catalog id for authored entity definitions. A `mob`/`boss` marker's `catalogId` references an entry (row) in this catalog, and {@link entityEntryFromCatalog} turns that row into the runtime {@link GameContextEntityEntry} a spawn consumes — so an entity's stats and speed are authored in the editor Data tab, not hardcoded in game TS.
+- `EditorAutoExposure` (interface): interface EditorAutoExposure — Authored clamped auto-exposure range: how far the meter may pull a dark room or a bright street.
 - `EditorCatalogData` (interface): interface EditorCatalogData — Persisted values for one gameplay data catalog (weapons, waves, economy, …). Schemas are not stored here — they come from the game's `editorCatalogs` export and drive SchemaInspector.
 - `EditorCatalogDefinition` (interface): interface EditorCatalogDefinition — Game-exported catalog definition: a `ParamSchema` plus default entries. Schemas stay in code; entry values merge into `document.catalogs` and are what the editor/RPC edits and saves.
 - `EditorCatalogEntry` (interface): interface EditorCatalogEntry — One row in a gameplay data catalog — id + optional label + a meta bag matching the catalog's `ParamSchema`. Values persist on the scene document; the schema lives in the game export.
 - `EditorCatalogsInput` (type): type EditorCatalogsInput = | readonly EditorCatalogDefinition[] | (() => readonly EditorCatalogDefinition[]) — Accepted shape for a game's `editorCatalogs` export: definitions, or a factory.
 - `EditorCollection` (interface): interface EditorCollection — A named, persisted list of object ids — a selection bookmark (restore, add-to) that can also double as a production group: `locked` blocks `translate`/`setTransform`/`remove`/`removeMany` on its members, `color`/`visible` are UI-only hints for the collections panel.
+- `EditorColorGrading` (interface): interface EditorColorGrading — Authored colour grading for the scene document's final image. The editor bakes a small display-space LUT from these controls and the shell applies it after tone mapping, so a game's grade is authored data like its sky, not a hardcoded pass in the game's config.
 - `EditorCommand` (type): type EditorCommand = | { type: "select"; ids: readonly string[] } | { type: "clearSelection" } | { type: "setTransform"; id: string; position?: EditorVec3; rotationY?: number } | { type: "translate"; ids: readonly string[]; delta: EditorVec3 } | { type: "setParent"; ids: readonly string[]; parentId:… — A single editor mutation — select, move, add, remove, undo/redo — dispatched to a session.
 - `EditorDirective` (type): type EditorDirective = EditorScatterDirective | EditorPopulationDirective — A procedural directive on the scene document: scatter props or a mob population.
 - `EditorDirectiveArea` (interface): interface EditorDirectiveArea — XZ world-space bounds, `[minX, minZ]`..`[maxX, maxZ]`, for a directive that names no region.
@@ -41,6 +44,7 @@
 - `EditorGridPaletteEntry` (interface): interface EditorGridPaletteEntry — One selectable value in a grid layer's palette: the cell value id plus how it reads (label, color) and how ASCII import/export maps it (`glyph`). Games register these so the editor and the import adapters share one legend. `meta` carries the typed payload (cost, damage, tags, …) a runtime attaches to every cell holding this value.
 - `EditorKindVisibility` (interface): interface EditorKindVisibility — Per-kind show/hide flags for the editor's layer panel.
 - `EditorLayersInput` (type): type EditorLayersInput = | EditorDocument | Partial<Omit<EditorDocument, "version">> | (() => EditorDocument | Partial<Omit<EditorDocument, "version">>) — Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory.
+- `EditorLightProbe` (interface): interface EditorLightProbe extends IrradianceVolume — An irradiance volume authored on the scene document: a grid of baked SH probes over a box, plus the bake settings that produced them so a scene can re-bake without the editor session.
 - `EditorMarker` (interface): interface EditorMarker — A placeable point object in the scene — spawn, mob, chest, POI, etc.
 - `EditorMinimapBake` (interface): interface EditorMinimapBake — A baked top-down minimap stored on the scene document (#1036): the PNG the editor rasterized from the authored terrain (a `data:image/png;base64,…` URI) plus the world bounds it spans. Runtime feeds these straight into the `Minimap`/`WorldMap` `background`/`mapBounds` props — no re-raster.
 - `EditorNote` (interface): interface EditorNote — A free-text annotation pinned to a world position for designers.
@@ -99,8 +103,11 @@
 - `applyDirectiveOverlay` (function): function applyDirectiveOverlay(instances: readonly MaterializedInstance[], overlay: EditorDirectiveOverlay): MaterializedInstance[] — Applies a directive overlay to its materialized instances: patched fields override, `deleted` drops the instance. Instances with no patch pass through untouched.
 - `applyDocumentPatch` (function): function applyDocumentPatch(document: EditorDocument, revision: number, patch: DocumentPatch, options?: { force?: boolean }): ApplyDocumentPatchResult — Applies a versioned document patch. Rejects base-revision mismatches unless `force` (document is authoritative — the editor forces when publishing its own session state).
 - `applyRuntimeStateDelta` (function): function applyRuntimeStateDelta(snapshot: RuntimeStateSnapshot, delta: Omit<RuntimeStateDelta, "seq"> & { seq?: number }): { snapshot: RuntimeStateSnapshot; delta: RuntimeStateDelta } — Merges a runtime delta into a snapshot without touching the scene document — runtime overrides stay ephemeral until an explicit write-back produces a document patch.
+- `authoredLightsFromDocument` (function): function authoredLightsFromDocument(doc: EditorDocument): readonly { position: readonly [number, number, number]; color?: string; intensity?: number; distance?: number }[] — The lamps a bake should include: authored light markers plus the environment's point lights.
+- `bakeLightProbe` (function): function bakeLightProbe(probe: EditorLightProbe, doc: EditorDocument): EditorLightProbe — Bakes one authored irradiance volume from its own settings and the document's lamps: sky where the region is open, an authored ceiling/floor fill where it is enclosed, and the authored lamps on top. Pure and deterministic, so the editor's Bake button and a script produce the same samples.
 - `bakeMinimapFromDocument` (function): function bakeMinimapFromDocument(doc: EditorDocument, sampleHeight: (x: number, z: number) => number, options: DocumentBakeOptions = {}): { background: string; mapBounds: MinimapBakeBounds } — Bakes a minimap image from a scene document plus a terrain height sampler: sizes the footprint to the authored objects (or an explicit `bounds`), tints biome-colored volumes, and rasterizes the terrain top-down. Returns `{ background, mapBounds }` for the `Minimap` props. The editor runs this as its bake action and stores the result on the document.
 - `cloneGridLayer` (function): function cloneGridLayer(layer: EditorGridLayer): EditorGridLayer — Deep-clones a grid layer so authoring edits and history snapshots never alias source cells.
+- `colorGradeFromDocument` (function): function colorGradeFromDocument(doc: EditorDocument): DocumentColorGrade | undefined — The colour grade a scene document authored, baked for the renderer. `undefined` when the document authored no grade at all, so an ungraded game keeps its own post chain untouched. The shell folds this into the post config the same way {@link lightProbesFromDocument} feeds the irradiance volumes, so a game's grade is authored data rather than a pass wired in its config.
 - `consumeRuntimePlayStep` (function): function consumeRuntimePlayStep(play: RuntimePlayControl): { runFrame: boolean; next: RuntimePlayControl; } — Advances the play-control step counter: when paused with pending steps, consumes one and reports whether the sim should run this frame. When not paused, always runs.
 - `createDocumentLiveSync` (function): function createDocumentLiveSync(initial: EditorDocument): DocumentLiveSync — Creates an in-memory two-way live-sync bus seeded from an initial document. Document is authoritative; runtime overrides are ephemeral until {@link DocumentLiveSync.writeBackOverride}.
 - `createGridLayer` (function): function createGridLayer(init: CreateGridLayerInit): EditorGridLayer — Creates a grid layer from a partial init, defaulting cell size to `1`, origin to the world origin, and axes to `"xz"`. Runs the result through {@link migrateGridLayer} so it is normalized and bounds-clean.
@@ -136,8 +143,10 @@
 - `importCsvGrid` (function): function importCsvGrid(text: string, options: CsvGridImportOptions): EditorGridLayer — Parses a CSV grid — one row per line, one value id per comma-separated field — into a grid layer. Blank fields become the empty value. Unlike ASCII this carries multi-character value ids directly, so it suits grids whose cell values are names rather than single glyphs.
 - `inGridBounds` (function): function inGridBounds(layer: EditorGridLayer, col: number, row: number): boolean — True when `col,row` falls inside the layer's declared bounds.
 - `installDocumentLiveSync` (function): function installDocumentLiveSync(sync: DocumentLiveSync): () => void — Publishes a live-sync bus globally so AuthoredScene / games can subscribe without prop drilling.
+- `lightProbesFromDocument` (function): function lightProbesFromDocument(doc: EditorDocument): readonly IrradianceVolume[] — The baked irradiance volumes a scene document authored, flattened for the renderer.
 - `lightingFromDocument` (function): function lightingFromDocument(doc: EditorDocument): LightingConfig | undefined — Converts authored `light` markers into the runtime lighting contract.
 - `loadWorldDocument` (function): function loadWorldDocument(manifest: WorldManifest, resolve: WorldShardResolver, query?: WorldQuery): EditorDocument — Loads the live neighborhood document for a query: reads each selected shard through `resolve`, applies its overlay (if any) on top, then merges them into one {@link EditorDocument} downstream consumers (`placeAuthoredObjects`, `collectAuthoredTriggers`, scatter, …) read unchanged. The monolith becomes an internal detail of the loader; a one-shard world yields exactly that shard.
+- `lutCubeFromGrading` (function): function lutCubeFromGrading(grading: EditorColorGrading): LutCube — Bakes an authored grade into a display-space LUT cube. Contrast and saturation work around luma, then each band pulls its share of the frame toward the authored swatch, scaled to the pixel's own brightness so a swatch tints a band instead of painting over it. Pure and deterministic, so the editor's preview and the runtime produce the same bytes.
 - `materializeDirective` (function): function materializeDirective(doc: EditorDocument, directive: EditorDirective): MaterializedInstance[] — Materializes one directive against a document, resolving its footprint first. Returns an empty list when the region does not resolve.
 - `materializeDirectives` (function): function materializeDirectives(doc: EditorDocument, overlays?: readonly EditorDirectiveOverlay[]): MaterializedInstance[] — Materializes every directive on a document into one flat instance list, applying each directive's overlay (matched by `over` === directive id) as it goes. The bulk-content counterpart to `resolveAuthoredObjects` / `resolveScatter`: games and headless tests read the same list.
 - `materializePopulationDirective` (function): function materializePopulationDirective(directive: EditorPopulationDirective, footprint: DirectiveFootprint): MaterializedInstance[] — Materializes a population directive into deterministic mob spawn placements: at most `cap` of each weighted species, distributed across the footprint. Each placement carries a stable id and its species id in `asset`, ready to feed `ctx.scene.entity.spawn` / `ai/populationDirector`.
@@ -212,11 +221,17 @@
 
 ## @jgengine/core/editor/environment
 
+- `DocumentColorGrade` (interface): interface DocumentColorGrade — The renderer-facing result of a document's authored grade.
 - `EnvironmentContent` (interface): interface EnvironmentContent — The coordinate/placement content of a world, derived from its scene document.
 - `EnvironmentContentOptions` (interface): interface EnvironmentContentOptions extends ClearanceOptions — World-authoring convergence (#1018, epic #1006 Phase 4): derive the **coordinate/placement** content of an `environment()` world from the scene document, so a game with an authored document needs no coordinate arrays in `world.ts` — the remaining `world.ts` surface is engine tuning (noise, materials, sky preset, physics). Terrain footprint follows the authored objects, ground clearings come from authored spawns/POIs (`clearanceZonesFrom`), and the sculpt snapshot is the document's own terrain overlay. Pure and serializable; consumers pass the result straight to `environment({ terrain: terrain({ bounds }), clearings, sculpt })`.
+- `authoredLightsFromDocument` (function): function authoredLightsFromDocument(doc: EditorDocument): readonly { position: readonly [number, number, number]; color?: string; intensity?: number; distance?: number }[] — The lamps a bake should include: authored light markers plus the environment's point lights.
+- `bakeLightProbe` (function): function bakeLightProbe(probe: EditorLightProbe, doc: EditorDocument): EditorLightProbe — Bakes one authored irradiance volume from its own settings and the document's lamps: sky where the region is open, an authored ceiling/floor fill where it is enclosed, and the authored lamps on top. Pure and deterministic, so the editor's Bake button and a script produce the same samples.
+- `colorGradeFromDocument` (function): function colorGradeFromDocument(doc: EditorDocument): DocumentColorGrade | undefined — The colour grade a scene document authored, baked for the renderer. `undefined` when the document authored no grade at all, so an ungraded game keeps its own post chain untouched. The shell folds this into the post config the same way {@link lightProbesFromDocument} feeds the irradiance volumes, so a game's grade is authored data rather than a pass wired in its config.
 - `environmentContentFromDocument` (function): function environmentContentFromDocument(doc: EditorDocument, options: EnvironmentContentOptions = {}): EnvironmentContent — Derives the coordinate/placement content of an `environment()` world from its scene document: terrain footprint (via {@link terrainBoundsFromDocument}), ground clearings under authored spawns/POIs (via `clearanceZonesFrom`), and the document's sculpt snapshot. This is the seam that lets a game author its world footprint and flatten regions in the editor instead of hardcoding them — the `world.ts` that consumes it carries only engine tuning.
 - `lakebedFromWaterVolumes` (function): function lakebedFromWaterVolumes(doc: EditorDocument): TerraformSnapshot | undefined — Derives a terrain-depression sculpt snapshot from the document's authored `water` volumes: each water box carves a lake bed that ramps from the shoreline down to below the box's bottom face, so an editor-authored pond/lake sits *in* the ground instead of floating as a sheet on top of it (and ground-sampled vegetation sinks below the surface rather than growing through it). Returns `undefined` when the document has no water volumes.
+- `lightProbesFromDocument` (function): function lightProbesFromDocument(doc: EditorDocument): readonly IrradianceVolume[] — The baked irradiance volumes a scene document authored, flattened for the renderer.
 - `lightingFromDocument` (function): function lightingFromDocument(doc: EditorDocument): LightingConfig | undefined — Converts authored `light` markers into the runtime lighting contract.
+- `lutCubeFromGrading` (function): function lutCubeFromGrading(grading: EditorColorGrading): LutCube — Bakes an authored grade into a display-space LUT cube. Contrast and saturation work around luma, then each band pulls its share of the frame toward the authored swatch, scaled to the pixel's own brightness so a swatch tints a band instead of painting over it. Pure and deterministic, so the editor's preview and the runtime produce the same bytes.
 - `skyFromDocument` (function): function skyFromDocument(doc: EditorDocument): SkyEnvironmentConfig | undefined — Maps the scene document's serializable environment bag onto the runtime sky config consumed by `sky()` / `environment({ sky })`. Returns `undefined` when the document has no environment field so callers can fall back to a world.ts default without inventing values.
 - `terrainBoundsFromDocument` (function): function terrainBoundsFromDocument(doc: EditorDocument, options: EnvironmentContentOptions = {}): WorldBounds — The origin-centered terrain footprint that covers every authored object in a document, padded and floored to `minBounds`. An empty document yields exactly `minBounds`. Because `environment()` terrain is centered on the origin, the footprint is sized symmetrically to the farthest object on each axis, so no authored object falls off the ground.
 
@@ -357,12 +372,14 @@
 
 ## @jgengine/core/editor/types
 
+- `EditorAutoExposure` (interface): interface EditorAutoExposure — Authored clamped auto-exposure range: how far the meter may pull a dark room or a bright street.
 - `EditorBake` (interface): interface EditorBake — A named baked artifact produced by an editor or build tool.
 - `EditorCatalogData` (interface): interface EditorCatalogData — Persisted values for one gameplay data catalog (weapons, waves, economy, …). Schemas are not stored here — they come from the game's `editorCatalogs` export and drive SchemaInspector.
 - `EditorCatalogDefinition` (interface): interface EditorCatalogDefinition — Game-exported catalog definition: a `ParamSchema` plus default entries. Schemas stay in code; entry values merge into `document.catalogs` and are what the editor/RPC edits and saves.
 - `EditorCatalogEntry` (interface): interface EditorCatalogEntry — One row in a gameplay data catalog — id + optional label + a meta bag matching the catalog's `ParamSchema`. Values persist on the scene document; the schema lives in the game export.
 - `EditorCatalogsInput` (type): type EditorCatalogsInput = | readonly EditorCatalogDefinition[] | (() => readonly EditorCatalogDefinition[]) — Accepted shape for a game's `editorCatalogs` export: definitions, or a factory.
 - `EditorCollection` (interface): interface EditorCollection — A named, persisted list of object ids — a selection bookmark (restore, add-to) that can also double as a production group: `locked` blocks `translate`/`setTransform`/`remove`/`removeMany` on its members, `color`/`visible` are UI-only hints for the collections panel.
+- `EditorColorGrading` (interface): interface EditorColorGrading — Authored colour grading for the scene document's final image. The editor bakes a small display-space LUT from these controls and the shell applies it after tone mapping, so a game's grade is authored data like its sky, not a hardcoded pass in the game's config.
 - `EditorDirective` (type): type EditorDirective = EditorScatterDirective | EditorPopulationDirective — A procedural directive on the scene document: scatter props or a mob population.
 - `EditorDirectiveArea` (interface): interface EditorDirectiveArea — XZ world-space bounds, `[minX, minZ]`..`[maxX, maxZ]`, for a directive that names no region.
 - `EditorDirectiveKind` (type): type EditorDirectiveKind = EditorDirective["kind"] — The distinct directive kinds a materializer expands.
@@ -372,6 +389,7 @@
 - `EditorFragmentContent` (interface): interface EditorFragmentContent — The four placeable-object collections a prefab fragment or clipboard fragment carries.
 - `EditorKindVisibility` (interface): interface EditorKindVisibility — Per-kind show/hide flags for the editor's layer panel.
 - `EditorLayersInput` (type): type EditorLayersInput = | EditorDocument | Partial<Omit<EditorDocument, "version">> | (() => EditorDocument | Partial<Omit<EditorDocument, "version">>) — Accepted shape for a game's `editorLayers` export: a document, partial data, or a factory.
+- `EditorLightProbe` (interface): interface EditorLightProbe extends IrradianceVolume — An irradiance volume authored on the scene document: a grid of baked SH probes over a box, plus the bake settings that produced them so a scene can re-bake without the editor session.
 - `EditorMarker` (interface): interface EditorMarker — A placeable point object in the scene — spawn, mob, chest, POI, etc.
 - `EditorMinimapBake` (interface): interface EditorMinimapBake — A baked top-down minimap stored on the scene document (#1036): the PNG the editor rasterized from the authored terrain (a `data:image/png;base64,…` URI) plus the world bounds it spans. Runtime feeds these straight into the `Minimap`/`WorldMap` `background`/`mapBounds` props — no re-raster.
 - `EditorNote` (interface): interface EditorNote — A free-text annotation pinned to a world position for designers.
@@ -564,6 +582,10 @@
 
 - `MaterialAssetEditorProps` (interface): interface MaterialAssetEditorProps — A callback-driven physical material editor; the host owns persistence, undo and preview rendering.
 
+## @jgengine/editor/MaterialLibraryBrowser
+
+- `MaterialLibraryBrowserProps` (interface): interface MaterialLibraryBrowserProps — Adopting a library name writes a real, editable material asset into the scene document.
+
 ## @jgengine/editor/PerfProbe
 
 - `PerfProbe` (const): const PerfProbe: React.MemoExoticComponent<({ api }: { api: EditorHostApi; }) => null> — In-canvas frame counter: publishes fps/draw-call samples to the editor host every 500ms.

package/skills/jgengine-editor/capabilities.md

@@ -8,6 +8,11 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `authoredMaterialAssignments` (function) · `import { authoredMaterialAssignments } from "@jgengine/core/editor/materialAuthoring"`
 
+## color-grading — read the scene document's authored grade at runtime
+
+- `colorGradeFromDocument` (function) · `import { colorGradeFromDocument } from "@jgengine/core/editor"`
+- `lutCubeFromGrading` (function) · `import { lutCubeFromGrading } from "@jgengine/core/editor"`
+
 ## creator-export — export validated player scenes with approved catalogs and finite budgets
 
 - `exportCreatorDocument` (function) · `import { exportCreatorDocument } from "@jgengine/core/editor/creatorStorage"`
@@ -100,6 +105,13 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 - `runtimeEntityMetaWriteBackCommand` (function) · `import { runtimeEntityMetaWriteBackCommand } from "@jgengine/core/editor"`
 - `summarizeRuntimeInspector` (function) · `import { summarizeRuntimeInspector } from "@jgengine/core/editor"`
 
+## light-probes — author a baked irradiance volume on the scene document
+
+- `EditorLightProbe` (interface) · `import { EditorLightProbe } from "@jgengine/core/editor"`
+- `authoredLightsFromDocument` (function) · `import { authoredLightsFromDocument } from "@jgengine/core/editor"`
+- `bakeLightProbe` (function) · `import { bakeLightProbe } from "@jgengine/core/editor"`
+- `lightProbesFromDocument` (function) · `import { lightProbesFromDocument } from "@jgengine/core/editor"`
+
 ## minimap-bake — persist a baked minimap PNG + bounds on the scene document
 
 - `EditorMinimapBake` (interface) · `import { EditorMinimapBake } from "@jgengine/core/editor"`

package/skills/jgengine-editor/reference.md

@@ -14,6 +14,23 @@ Scene and catalog modules are optional. A present module with a broken dependenc
 
 `dispatch` with `setEnvironment` validates only the candidate environment before changing the session, undo history, or live document revision. Supported presets are `day`, `dusk`, and `night`; custom palette, sun, intensity, and fog fields remain explicit authored values. Invalid inputs report `$.environment` paths. Validated nested fields are copied, so mutating the command afterward cannot change the document. Passing `environment: undefined` removes the bag and remains undoable. Repair unsupported authored values through an explicit editor command; preserve the author's palette and fog rather than substituting a default.
 
+`environment.grading` is the colour pipeline's authored face, edited in the Lighting workspace's Colour grade section:
+
+```json
+"grading": {
+  "size": 8,
+  "shadows": "#25304a",
+  "midtones": "#e6dcc8",
+  "highlights": "#fff0d2",
+  "tint": 0.42,
+  "saturation": 1.12,
+  "contrast": 1.08,
+  "autoExposure": { "min": 0.5, "max": 2.6 }
+}
+```
+
+Each band swatch is a display colour the pixels of that band are pulled toward by `tint` (absent band = untouched); saturation and contrast work around luma first. The runtime bakes the block into one `size³` cube LUT (`lutCubeFromGrading`, `@jgengine/core/editor/environment`, size 2..16, default 8 — a few hundred bytes of JSON, no texture asset to ship) and applies it after tone mapping; `autoExposure` is the clamped range the meter may use. The shell reads it from `editorLayers` with `colorGradeFromDocument`, so a game carries its own grade by authoring this block — never by hardcoding a LUT URL or grade in its config. Swatches must be hex colours and cube sizes outside 2..16 are rejected with their `$.environment.grading` path.
+
 ## Atomic authoring batches
 
 Use `document_revision` to inspect the current revision, then send one `push_document_patch` for a complete placement operation. Commands use the `EditorCommand` shapes from `@jgengine/core/editor/commands`, rather than RPC verb shapes. Earlier commands' ids are available to later commands in the same batch: