@jgengine/shell 0.25.0 → 0.27.0

package/dist/terrain/terrainDetailMaterial.d.ts

@@ -34,9 +34,21 @@ export interface TerrainDetailMaterialOptions {
     classMask?: number;
     /** Initial editor relief-contour strength. Default 0. */
     contour?: number;
+    /**
+     * Per-painted-slot scanned color maps (slot 1 first), each with its own world tile metres. Layers
+     * without a map (or beyond {@link MAX_TERRAIN_LAYER_MAPS}) keep the procedural surface response.
+     */
+    layerMaps?: readonly (TerrainLayerMap | undefined)[];
 }
 /** Compile every surface response, for an editor viewport whose paint can change to any surface. */
 export declare const ALL_TERRAIN_SURFACE_CLASSES = 511;
+/** One painted layer's scanned color map plus the world metres one tile covers. */
+export interface TerrainLayerMap {
+    color: THREE.Texture;
+    tileMetres: number;
+}
+/** At most this many painted layers sample their own scanned map; extra layers keep procedural shading. */
+export declare const MAX_TERRAIN_LAYER_MAPS = 4;
 /**
  * A `MeshStandardMaterial` that renders terrain as ground rather than flat colour. Each painted
  * layer draws its surface type's procedural response (grass clumps and blades, dirt clods and

package/dist/terrain/terrainDetailMaterial.js

@@ -1,10 +1,38 @@
 import * as THREE from "three";
 import { NOISE_GLSL, PAINT_PARS_GLSL, SURFACE_BUMP_NORMAL_GLSL, SURFACE_FUNCTIONS_GLSL } from "./terrainSurfaceShader.js";
+let placeholder;
+function placeholderTexture() {
+    if (placeholder !== undefined)
+        return placeholder;
+    placeholder = new THREE.DataTexture(new Uint8Array([255, 255, 255, 255]), 1, 1, THREE.RGBAFormat);
+    placeholder.needsUpdate = true;
+    return placeholder;
+}
 const ROCK_CLASS_BIT = 1 << 4;
 /** Compile every surface response, for an editor viewport whose paint can change to any surface. */
 export const ALL_TERRAIN_SURFACE_CLASSES = 0x1ff;
+/** At most this many painted layers sample their own scanned map; extra layers keep procedural shading. */
+export const MAX_TERRAIN_LAYER_MAPS = 4;
 // Slot 0 is the unpainted base, 1–8 the paint layers, 9 slope rock.
 const SLOT_GLSL = /* glsl */ `
+#ifdef JG_TERRAIN_LAYER_MAPS
+uniform sampler2D uLayerMap1;
+uniform sampler2D uLayerMap2;
+uniform sampler2D uLayerMap3;
+uniform sampler2D uLayerMap4;
+uniform float uLayerTile1;
+uniform float uLayerTile2;
+uniform float uLayerTile3;
+uniform float uLayerTile4;
+vec3 jgLayerMap(int slot, vec3 wp, out bool has) {
+  has = false;
+  if (slot == 1) { if (uLayerTile1 > 0.0) { has = true; return texture2D(uLayerMap1, wp.xz / uLayerTile1).rgb; } }
+  else if (slot == 2) { if (uLayerTile2 > 0.0) { has = true; return texture2D(uLayerMap2, wp.xz / uLayerTile2).rgb; } }
+  else if (slot == 3) { if (uLayerTile3 > 0.0) { has = true; return texture2D(uLayerMap3, wp.xz / uLayerTile3).rgb; } }
+  else if (slot == 4) { if (uLayerTile4 > 0.0) { has = true; return texture2D(uLayerMap4, wp.xz / uLayerTile4).rgb; } }
+  return vec3(0.0);
+}
+#endif
 JgSurf jgSlot(int slot, vec3 baseTone, vec3 wp){
   vec3 jgFlatC = baseTone;
   JgSurf s;
@@ -22,6 +50,15 @@ JgSurf jgSlot(int slot, vec3 baseTone, vec3 wp){
   else {
     s = jgSurface(0, baseTone, roughness, 1.0, wp);
   }
+#ifdef JG_TERRAIN_LAYER_MAPS
+  if (slot > 0 && slot <= 4) {
+    bool jgHasMap;
+    vec3 jgMapped = jgLayerMap(slot, wp, jgHasMap);
+    // The layer owns its own scan: grain, colour and all, tiled at its authored metres, and the
+    // mask weights decide how much of it shows against the neighbour layer.
+    if (jgHasMap) s.albedo = mix(s.albedo, jgMapped, 0.92);
+  }
+#endif
   s.albedo = mix(jgFlatC, s.albedo, uSurface);
   s.height *= uSurface;
   s.bump *= uSurface;
@@ -48,6 +85,20 @@ export function createTerrainDetailMaterial(detail, textures, options = {}) {
     const strength = detail.material?.strength ?? 1;
     const tint = detail.material?.tint ?? 1;
     const paint = options.paint;
+    const layerMaps = (options.layerMaps ?? []).slice(0, MAX_TERRAIN_LAYER_MAPS);
+    const hasLayerMaps = layerMaps.some((entry) => entry !== undefined);
+    const layerMapUniforms = hasLayerMaps
+        ? {
+            uLayerMap1: { value: layerMaps[0]?.color ?? placeholderTexture() },
+            uLayerMap2: { value: layerMaps[1]?.color ?? placeholderTexture() },
+            uLayerMap3: { value: layerMaps[2]?.color ?? placeholderTexture() },
+            uLayerMap4: { value: layerMaps[3]?.color ?? placeholderTexture() },
+            uLayerTile1: { value: layerMaps[0]?.tileMetres ?? 0 },
+            uLayerTile2: { value: layerMaps[1]?.tileMetres ?? 0 },
+            uLayerTile3: { value: layerMaps[2]?.tileMetres ?? 0 },
+            uLayerTile4: { value: layerMaps[3]?.tileMetres ?? 0 },
+        }
+        : {};
     const low = options.quality === "low";
     const contour = { value: options.contour ?? 0 };
     // Rock is always compiled for slope rock; each extra class costs shader time even where unused on
@@ -68,6 +119,7 @@ export function createTerrainDetailMaterial(detail, textures, options = {}) {
         uSurface: { value: detail.surfaceStrength },
         uContour: contour,
         ...(paint === undefined ? {} : paint.uniforms),
+        ...layerMapUniforms,
         ...(hasTexture
             ? {
                 uMatColor: { value: textures.color },
@@ -88,6 +140,7 @@ export function createTerrainDetailMaterial(detail, textures, options = {}) {
     });
     material.defines = {
         ...(paint === undefined ? {} : { JG_TERRAIN_PAINT: "" }),
+        ...(hasLayerMaps ? { JG_TERRAIN_LAYER_MAPS: "" } : {}),
         ...(low ? { JG_SURFACE_LOW: "" } : {}),
         JG_SURFACE_CLASSES: String(classMask),
     };
@@ -264,6 +317,6 @@ ${materialNormalGlsl}`)
             .replace("#include <aomap_fragment>", `#include <aomap_fragment>
 ${materialAoGlsl}`);
     };
-    material.customProgramCacheKey = () => `jgengine-terrain-detail-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}-${paint === undefined ? "bare" : "paint"}-${low ? "low" : "full"}-${classMask}`;
+    material.customProgramCacheKey = () => `jgengine-terrain-detail-${hasTexture ? "tex" : "flat"}-${hasTexture && textures.roughness !== undefined ? "rough" : "scalar"}-${hasTexture && textures.ao !== undefined ? "ao" : "unoccluded"}-${paint === undefined ? "bare" : "paint"}-${hasLayerMaps ? "layers" : "procedural"}-${low ? "low" : "full"}-${classMask}`;
     return { material, contour };
 }

package/dist/terrain/terrainSurfaces.d.ts

@@ -21,6 +21,10 @@ export interface TerrainPaintSlot {
     roughness: number;
     /** Pattern frequency multiplier from the layer's authored `tiling`. */
     scale: number;
+    /** World metres per texture repeat for this layer's scanned color map; 0 when the layer has no map. */
+    tileMetres: number;
+    /** Resolved color-map URL the slot's scanned texture comes from, if any. */
+    materialUrl?: string;
 }
 /** Per-cell paint coverage packed for the shader: two RGBA8 planes holding up to eight layer weights. */
 export interface TerrainPaintWeights {
@@ -50,6 +54,8 @@ export interface TerrainPaintTextures {
     readonly classMask: number;
     /** Re-upload coverage and layer slots; reallocates only when the cell grid size changes. */
     update(weights: TerrainPaintWeights): void;
+    /** The slot table the current coverage was packed from (layer materials, tile metres, classes). */
+    readonly slots: readonly TerrainPaintSlot[];
     dispose(): void;
 }
 /**

package/dist/terrain/terrainSurfaces.js

@@ -53,6 +53,8 @@ function slotFor(surface, layer) {
         classIndex: CLASS_INDEX[surfaceClass],
         roughness: layer?.roughness ?? CLASS_ROUGHNESS[surfaceClass],
         scale: tiling === undefined || tiling <= 0 ? 1 : Math.min(2, Math.max(0.5, CLASS_TILING[surfaceClass] / tiling)),
+        tileMetres: layer?.materialUrl === undefined ? 0 : tiling !== undefined && tiling > 0 ? tiling : 6,
+        ...(layer?.materialUrl === undefined ? {} : { materialUrl: layer.materialUrl }),
     };
 }
 /**
@@ -145,6 +147,7 @@ export function createTerrainPaintTextures(weights) {
     const classes = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
     const roughness = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
     const scales = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
+    const tiles = new Float32Array(MAX_TERRAIN_PAINT_LAYERS);
     const uniforms = {
         uPaintA: { value: coverageTexture(weights.planes[0], weights.cols, weights.rows) },
         uPaintB: { value: coverageTexture(weights.planes[1], weights.cols, weights.rows) },
@@ -156,9 +159,12 @@ export function createTerrainPaintTextures(weights) {
         uLayerClass: { value: classes },
         uLayerRough: { value: roughness },
         uLayerScale: { value: scales },
+        uLayerTile: { value: tiles },
     };
     let classMask = 0;
+    let slots = weights.slots;
     const update = (next) => {
+        slots = next.slots;
         classMask = next.slots.reduce((mask, slot) => mask | (1 << slot.classIndex), 0);
         for (const [key, plane] of [["uPaintA", next.planes[0]], ["uPaintB", next.planes[1]]]) {
             const current = uniforms[key].value;
@@ -182,6 +188,7 @@ export function createTerrainPaintTextures(weights) {
             classes[i] = slot?.classIndex ?? 0;
             roughness[i] = slot?.roughness ?? 0.9;
             scales[i] = slot?.scale ?? 1;
+            tiles[i] = slot?.tileMetres ?? 0;
         }
     };
     update(weights);
@@ -190,6 +197,9 @@ export function createTerrainPaintTextures(weights) {
         get classMask() {
             return classMask;
         },
+        get slots() {
+            return slots;
+        },
         update,
         dispose: () => {
             uniforms.uPaintA.value.dispose();

package/dist/world/WorldScene.js

@@ -17,6 +17,7 @@ import { useSceneEntityIds, useSceneObjectIds, useGameStore, usePlayer, useTarge
 import { colorFromId } from "../worldSky.js";
 import { DefaultSurface, detailMaps } from "../render/defaultSurface.js";
 import { useDisposable } from "../render/useDisposable.js";
+import { WindClock } from "../render/modelWind.js";
 import { MeasuredBoundsGroup } from "../render/measureBounds.js";
 import { EntitySprite, IsolatedEntityModel } from "../render/SceneModels.js";
 import { resolveEntityModel, resolveObjectModel } from "../render/resolveModel.js";
@@ -202,7 +203,7 @@ function WorldActors({ entitySprites, entityModels, objectModels, objectStyles,
             }), grouped.singles.map((candidate) => renderSingle(candidate.object)), grouped.batches.map((batch) => _jsx(StaticObjectModels, { batch: batch, single: renderSingle }, batch.key))] }));
 }
 export function WorldView({ entitySprites, entityModels, objectModels, objectStyles, environment, assets, renderEntity, renderObject, selectedIds, hideLocalActor, editorLayers, }) {
-    return (_jsxs(_Fragment, { children: [_jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor, editorLayers: editorLayers })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(WindClock, {}), _jsx(WorldEnvironment, { environment: environment }), _jsx(WorldActors, { entitySprites: entitySprites, entityModels: entityModels, objectModels: objectModels, objectStyles: objectStyles, assets: assets, renderEntity: renderEntity, renderObject: renderObject, selectedIds: selectedIds, hideLocalActor: hideLocalActor, editorLayers: editorLayers })] }));
 }
 export function RemotePlayers({ rows, presenceInterpolationMs = 100 }) {
     const groups = useRef(new Map());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.25.0",
+  "version": "0.27.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",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.25.0",
-    "@jgengine/react": "^0.25.0",
-    "@jgengine/ws": "^0.25.0"
+    "@jgengine/core": "^0.27.0",
+    "@jgengine/react": "^0.27.0",
+    "@jgengine/ws": "^0.27.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.27.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.27.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"`