@jgengine/shell 0.24.0 → 0.26.0

package/dist/render/stableTextureSet.js

@@ -0,0 +1,24 @@
+import { useRef } from "react";
+/** Whether two texture sets hold the same roles and texture instances. @internal */
+export function sameTextureSet(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+        return false;
+    const keys = Object.keys(a);
+    if (keys.length !== Object.keys(b).length)
+        return false;
+    return keys.every((key) => a[key] === b[key]);
+}
+/**
+ * Keep one texture-set identity while its roles and texture instances are unchanged. The drei
+ * loader hands back a fresh keyed object per render, and materials built from it rebuilt and
+ * recompiled their shaders every frame.
+ * @internal
+ */
+export function useStableTextureSet(textures) {
+    const stable = useRef(textures);
+    if (!sameTextureSet(stable.current, textures))
+        stable.current = textures;
+    return stable.current;
+}

package/dist/render/triplanarMaterial.d.ts

@@ -0,0 +1,52 @@
+import type { MaterialAsset } from "@jgengine/core/material/materialAsset";
+import * as THREE from "three";
+/** Inputs for {@link applyTriplanarProjection}. */
+export interface TriplanarProjectionOptions {
+    /** Metres one texture tile covers in world space. Must be finite and positive. */
+    tileMetres: number;
+    /** Blend sharpness between the three projections; 4 keeps corners soft, 8 is decisive. */
+    sharpness?: number;
+    /** Normal strength applied to each projection's tangent-space perturbation. */
+    normalScale?: number;
+}
+/**
+ * The GLSL the triplanar path injects, split by chunk. Exposed so a test can prove the patch
+ * samples by world position instead of `vMapUv`, and so a reader can audit the projection.
+ * @internal
+ */
+export declare function triplanarChunks(): {
+    vertexPars: string;
+    vertexNormal: string;
+    vertexPosition: string;
+    fragmentPars: string;
+    color: string;
+    roughness: string;
+    normal: string;
+    ao: string;
+};
+/**
+ * Projects a standard material's maps from world position instead of mesh UVs, so world geometry
+ * without a `uv` attribute still renders a textured PBR surface. Instanced meshes project in their
+ * instanced world space. Skinned meshes keep the bind-pose normal for the blend weights, which is
+ * close enough for the static world surfaces this path exists for.
+ */
+export declare function applyTriplanarProjection(material: THREE.MeshStandardMaterial, options: TriplanarProjectionOptions): THREE.MeshStandardMaterial;
+/**
+ * Render a serializable material asset — one built by `libraryMaterialAsset`, or authored in the
+ * editor — with world-space triplanar projection, so world geometry needs no UVs. Tile size
+ * defaults to the asset's own `physicalSize`, which the shared library sets per surface.
+ * @capability material-triplanar render a material asset on world geometry without UVs
+ */
+export declare function useTriplanarAssetMaterial(asset: MaterialAsset, options?: {
+    tileMetres?: number;
+    sharpness?: number;
+    normalScale?: number;
+}): THREE.MeshStandardMaterial;
+/** Mounts {@link useTriplanarAssetMaterial} on a mesh; the R3F renderer owns disposal. */
+export declare function TriplanarAssetMaterial({ asset, ...options }: {
+    asset: MaterialAsset;
+} & {
+    tileMetres?: number;
+    sharpness?: number;
+    normalScale?: number;
+}): import("react").JSX.Element;

package/dist/render/triplanarMaterial.js

@@ -0,0 +1,169 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import * as THREE from "three";
+import { useMaterialAssetMaterial } from "./materialAsset.js";
+const VERTEX_PARS = `varying vec3 vJgTriPos;
+varying vec3 vJgTriNormal;`;
+const VERTEX_WORLD_NORMAL = `vJgTriNormal = normalize(mat3(modelMatrix) * objectNormal);`;
+const VERTEX_WORLD_POSITION = `vec4 jgTriWorld = vec4(transformed, 1.0);
+#ifdef USE_INSTANCING
+jgTriWorld = instanceMatrix * jgTriWorld;
+#endif
+vJgTriPos = (modelMatrix * jgTriWorld).xyz;`;
+const FRAGMENT_PARS = `varying vec3 vJgTriPos;
+varying vec3 vJgTriNormal;
+uniform float uJgTriTile;
+uniform float uJgTriSharp;
+uniform float uJgTriNormalScale;
+vec3 jgTriWeights() {
+  vec3 w = pow(abs(normalize(vJgTriNormal)), vec3(uJgTriSharp));
+  return w / max(dot(w, vec3(1.0)), 1e-4);
+}
+vec3 jgTriSample(sampler2D tex, vec3 w) {
+  vec3 p = vJgTriPos / uJgTriTile;
+  return texture2D(tex, p.zy).rgb * w.x + texture2D(tex, p.xz).rgb * w.y + texture2D(tex, p.xy).rgb * w.z;
+}`;
+const FRAGMENT_COLOR = `#ifdef USE_MAP
+{
+  vec3 jgW = jgTriWeights();
+  vec3 jgP = vJgTriPos / uJgTriTile;
+  diffuseColor *= texture2D(map, jgP.zy) * jgW.x + texture2D(map, jgP.xz) * jgW.y + texture2D(map, jgP.xy) * jgW.z;
+}
+#endif`;
+const FRAGMENT_ROUGHNESS = `float roughnessFactor = roughness;
+#ifdef USE_ROUGHNESSMAP
+roughnessFactor *= jgTriSample(roughnessMap, jgTriWeights()).g;
+#endif`;
+// Each projection perturbs the world normal along its own tangent frame: an X-facing projection
+// uses +Z as U and +Y as V, a Y-facing one +X/+Z, a Z-facing one +X/+Y.
+const FRAGMENT_NORMAL = `#ifdef USE_NORMALMAP
+{
+  vec3 jgW = jgTriWeights();
+  vec3 jgP = vJgTriPos / uJgTriTile;
+  vec3 jgNx = texture2D(normalMap, jgP.zy).xyz * 2.0 - 1.0;
+  vec3 jgNy = texture2D(normalMap, jgP.xz).xyz * 2.0 - 1.0;
+  vec3 jgNz = texture2D(normalMap, jgP.xy).xyz * 2.0 - 1.0;
+  jgNx.xy *= uJgTriNormalScale;
+  jgNy.xy *= uJgTriNormalScale;
+  jgNz.xy *= uJgTriNormalScale;
+  vec3 jgPerturb = vec3(jgNx.z, jgNx.y, jgNx.x) * jgW.x
+    + vec3(jgNy.x, jgNy.z, jgNy.y) * jgW.y
+    + vec3(jgNz.x, jgNz.y, jgNz.z) * jgW.z;
+  normal = normalize((viewMatrix * vec4(normalize(vJgTriNormal + jgPerturb), 0.0)).xyz);
+}
+#endif`;
+const FRAGMENT_AO = `#ifdef USE_AOMAP
+{
+  float jgAo = jgTriSample(aoMap, jgTriWeights()).r;
+  float ambientOcclusion = ( jgAo - 1.0 ) * aoMapIntensity + 1.0;
+  reflectedLight.indirectDiffuse *= ambientOcclusion;
+  #if defined( USE_CLEARCOAT )
+    clearcoatSpecularIndirect *= ambientOcclusion;
+  #endif
+  #if defined( USE_SHEEN )
+    sheenSpecularIndirect *= ambientOcclusion;
+  #endif
+  #if defined( USE_ENVMAP ) && defined( STANDARD )
+    float dotNV = saturate( dot( geometryNormal, geometryViewDir ) );
+    reflectedLight.indirectSpecular *= computeSpecularOcclusion( dotNV, ambientOcclusion, material.roughness );
+  #endif
+}
+#endif`;
+/**
+ * The GLSL the triplanar path injects, split by chunk. Exposed so a test can prove the patch
+ * samples by world position instead of `vMapUv`, and so a reader can audit the projection.
+ * @internal
+ */
+export function triplanarChunks() {
+    return {
+        vertexPars: VERTEX_PARS,
+        vertexNormal: VERTEX_WORLD_NORMAL,
+        vertexPosition: VERTEX_WORLD_POSITION,
+        fragmentPars: FRAGMENT_PARS,
+        color: FRAGMENT_COLOR,
+        roughness: FRAGMENT_ROUGHNESS,
+        normal: FRAGMENT_NORMAL,
+        ao: FRAGMENT_AO,
+    };
+}
+function assertPatchable(material) {
+    const vertex = THREE.ShaderLib.physical.vertexShader;
+    const fragment = THREE.ShaderLib.physical.fragmentShader;
+    const required = [
+        [vertex, "#include <beginnormal_vertex>"],
+        [vertex, "#include <worldpos_vertex>"],
+        [fragment, "#include <map_fragment>"],
+        [fragment, "#include <roughnessmap_fragment>"],
+        [fragment, "#include <normal_fragment_maps>"],
+        [fragment, "#include <aomap_fragment>"],
+    ];
+    for (const [source, marker] of required) {
+        if (!source.includes(marker))
+            throw new Error(`Three.js r${THREE.REVISION} physical shader lacks ${marker} for the triplanar world projection`);
+    }
+    if (!material.isMeshStandardMaterial)
+        throw new Error("Triplanar projection requires a standard or physical material");
+}
+/**
+ * Projects a standard material's maps from world position instead of mesh UVs, so world geometry
+ * without a `uv` attribute still renders a textured PBR surface. Instanced meshes project in their
+ * instanced world space. Skinned meshes keep the bind-pose normal for the blend weights, which is
+ * close enough for the static world surfaces this path exists for.
+ */
+export function applyTriplanarProjection(material, options) {
+    const tile = options.tileMetres;
+    if (!Number.isFinite(tile) || tile <= 0)
+        throw new Error("Triplanar tileMetres must be finite and positive");
+    const sharpness = options.sharpness ?? 8;
+    const normalScale = options.normalScale ?? 1;
+    if (!Number.isFinite(sharpness) || sharpness <= 0)
+        throw new Error("Triplanar sharpness must be finite and positive");
+    if (!Number.isFinite(normalScale) || normalScale < 0)
+        throw new Error("Triplanar normalScale must be finite and non-negative");
+    if (material.userData["jgTriplanar"] !== undefined)
+        return material;
+    assertPatchable(material);
+    const uniforms = {
+        uJgTriTile: { value: tile },
+        uJgTriSharp: { value: sharpness },
+        uJgTriNormalScale: { value: normalScale },
+    };
+    material.userData["jgTriplanar"] = uniforms;
+    const previousCompile = material.onBeforeCompile;
+    const previousKey = material.customProgramCacheKey;
+    material.onBeforeCompile = (shader, renderer) => {
+        previousCompile.call(material, shader, renderer);
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `#include <common>\n${VERTEX_PARS}`)
+            .replace("#include <beginnormal_vertex>", `#include <beginnormal_vertex>\n${VERTEX_WORLD_NORMAL}`)
+            .replace("#include <worldpos_vertex>", `#include <worldpos_vertex>\n${VERTEX_WORLD_POSITION}`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `#include <common>\n${FRAGMENT_PARS}`)
+            .replace("#include <map_fragment>", FRAGMENT_COLOR)
+            .replace("#include <roughnessmap_fragment>", FRAGMENT_ROUGHNESS)
+            .replace("#include <normal_fragment_maps>", FRAGMENT_NORMAL)
+            .replace("#include <aomap_fragment>", FRAGMENT_AO);
+    };
+    material.customProgramCacheKey = () => `${previousKey.call(material)}|jg-triplanar:v1`;
+    material.needsUpdate = true;
+    return material;
+}
+/**
+ * Render a serializable material asset — one built by `libraryMaterialAsset`, or authored in the
+ * editor — with world-space triplanar projection, so world geometry needs no UVs. Tile size
+ * defaults to the asset's own `physicalSize`, which the shared library sets per surface.
+ * @capability material-triplanar render a material asset on world geometry without UVs
+ */
+export function useTriplanarAssetMaterial(asset, options = {}) {
+    const material = useMaterialAssetMaterial(asset);
+    const tile = options.tileMetres ?? asset.textures?.color?.physicalSize?.[0] ?? asset.textures?.normal?.physicalSize?.[0] ?? 1;
+    const sharpness = options.sharpness ?? 8;
+    const normalScale = options.normalScale ?? 1;
+    return useMemo(() => applyTriplanarProjection(material, { tileMetres: tile, sharpness, normalScale }), [material, tile, sharpness, normalScale]);
+}
+/** Mounts {@link useTriplanarAssetMaterial} on a mesh; the R3F renderer owns disposal. */
+export function TriplanarAssetMaterial({ asset, ...options }) {
+    const material = useTriplanarAssetMaterial(asset, options);
+    return _jsx("primitive", { object: material, attach: "material" });
+}

package/dist/settings/appliedSettings.js

@@ -1,4 +1,4 @@
-import { useCallback, useEffect, useRef, useSyncExternalStore } from "react";
+import { useCallback, useEffect, useMemo, useRef, useSyncExternalStore } from "react";
 import { busVolumeSettingId, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
 import { readGraphicsSettings } from "@jgengine/core/settings/graphicsSettings";
 import { readFrameRateLimit } from "@jgengine/core/settings/frameRateLimit";
@@ -29,18 +29,21 @@ export function useSettingsRevision(store) {
     return useSyncExternalStore(subscribe, getVersion, getVersion);
 }
 export function useGraphicsSettings(store, shadowsDefault, overrides) {
-    useSettingsRevision(store);
-    const { quality, profile } = readGraphicsSettings(store, overrides);
-    const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
-    return {
-        shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
-        dpr: profile.renderScale,
-        uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
-        quality,
-        profile,
-        frameRateLimit: readFrameRateLimit(store),
-        showFps: store.get(SETTING_IDS.graphicsShowFps, false),
-    };
+    const rev = useSettingsRevision(store);
+    // Effects rebuild on identity change; a fresh object each render recompiled the post chain every frame.
+    return useMemo(() => {
+        const { quality, profile } = readGraphicsSettings(store, overrides);
+        const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
+        return {
+            shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
+            dpr: profile.renderScale,
+            uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
+            quality,
+            profile,
+            frameRateLimit: readFrameRateLimit(store),
+            showFps: store.get(SETTING_IDS.graphicsShowFps, false),
+        };
+    }, [store, rev, shadowsDefault, overrides]);
 }
 export function AudioSettingsBridge({ store, engine, buses, }) {
     const rev = useSettingsRevision(store);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.24.0",
+  "version": "0.26.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.24.0",
-    "@jgengine/react": "^0.24.0",
-    "@jgengine/ws": "^0.24.0"
+    "@jgengine/core": "^0.26.0",
+    "@jgengine/react": "^0.26.0",
+    "@jgengine/ws": "^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.24.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.24.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-ui/SKILL.md

@@ -32,8 +32,8 @@ Existing React games keep their entity store and use the focused
 - **Settings is game-owned and reachable from a sensible place.** Every game ships settings as *its* settings — skinned and placed inline with its UI (main menu and pause), never the engine's stock face floated into a corner. Credits are a reachable in-game screen, not attribution buried in a build artifact.
 - **Route the front-end with `useMenuRouter`, and generate the credits.** `useMenuRouter(root)` is the screen stack behind title → save select → settings → credits: `open`/`back`/`replace`/`reset`, `path` for depth, and Escape-to-back bound by default (`escapeToBack: false` when the game owns Escape). `menuStackReducer` is the same transition as a pure function. For credits, `creditsForSourceIds(ids)` (`@jgengine/assets/credits`) turns the pack ids a game declares to `buildCatalog` into licensed, attributed sections, `mergeCredits` folds them into hand-authored lines, and `CreditsScreen` renders the result HudTheme-skinned.
 - **Skin the shared chrome with one `HudTheme` token object.** `hudThemeVars(theme)` emits the whole `--jg-*` vocabulary — bar fills and troughs, `HudFrame variation="themed"`, painted slots, the minimap ring, plus surfaces, edges, text, status colors, fonts, and rarity — so one theme spread on any HUD ancestor reskins the `@jgengine/react` primitives and the `registry/jgengine` blocks together. Author your own with `deriveHudTheme({ accent, surface })` or `hudTheme({ ... })`; `HUD_THEME_PRESETS` / `resolveHudTheme("<preset>")` are demo/scaffold starting points, never a game's identity. A component that needs a token no theme emits fails `check-hud-tokens` — add it to `HudTheme` rather than inventing a second vocabulary. Caller `style`/`renderItem` overrides still win.
-- **The shell applies `defaultHudTheme` at the GameUI root.** `HudThemeRoot` wraps every `GameUI` in a `display: contents` `[data-jg-hud]` element carrying the theme vars and injects the engine stylesheet (`jg-*` keyframes, `[data-jg-*]` interaction states, reduced motion). Set `defineGame({ hudTheme })` to swap the root theme, `hudTheme: false` to opt out; a theme spread inside `GameUI` still wins. Games outside the shell add `@import "@jgengine/react/styles.css";` to `src/index.css` (the `jgengine create` template does). The theme also carries a type scale with a 12px floor, spacing, motion, elevation, and hover/press/focus/disabled tokens; read them in inline styles through `hudType`, `hudSpace`, `hudTransition`, `hudElevation`, and `HUD_FOCUS_RING` (`@jgengine/react/hudTokens`) — never hardcode text under 12px.
-- **Build interactive chrome from `HudButton`, `HudPanel`, and `TweenNumber`.** `HudButton` gives hover lift, press scale, focus ring, and disabled from tokens; `HudPanel` gives elevation, header slots, and an `open` enter/exit transition; `TweenNumber` / `useTweenedValue` roll counters with an up/down delta flash. Each takes `cue` (`data-jg-cue`) and `onInteract`; `HudInteractProvider` routes every primitive's hover/press/activate/open/close to one listener; the shell mounts one that plays the matching UI cue, so engine primitives sound with no wiring (`cue="confirm"` picks the activate sound).
+- **The shell applies `defaultHudTheme` at the GameUI root.** `HudThemeRoot` wraps every `GameUI` in a `display: contents` `[data-jg-hud]` element carrying the theme vars and injects the engine stylesheet (`jg-*` keyframes, `[data-jg-*]` interaction states, reduced motion). Set `defineGame({ hudTheme })` to swap the root theme, `hudTheme: false` to opt out; a theme spread inside `GameUI` still wins. Games outside the shell add `@import "@jgengine/react/styles.css";` to `src/index.css` (the `jgengine create` template does). Every engine rule sits in the `components.jgengine` cascade layer, so plain game CSS and Tailwind utilities override engine buttons and panels without `!important`. The theme also carries a type scale with a 12px floor, spacing, motion, elevation, and hover/press/focus/disabled tokens; read them in inline styles through `hudType`, `hudSpace`, `hudTransition`, `hudElevation`, and `HUD_FOCUS_RING` (`@jgengine/react/hudTokens`) — never hardcode text under 12px.
+- **Build interactive chrome from `HudButton`, `HudSurface`, and `TweenNumber`.** `HudButton` gives hover lift, press scale, focus ring, and disabled from tokens, and wraps long labels; `HudSurface` (`@jgengine/react/hudSurface`; `HudPanel` from `@jgengine/react/hudPanel` is its deprecated old name, not the `HudCanvas` slot) gives elevation, header slots, an `as` landmark element, padding from `--jg-panel-padding`, and an `open` enter/exit transition; `TweenNumber` / `useTweenedValue` roll counters with an up/down delta flash. Each takes `cue` (`data-jg-cue`) and `onInteract`; `HudInteractProvider` routes every primitive's hover/press/activate/open/close to one listener; the shell mounts one that plays the matching UI cue, so engine primitives sound with no wiring (`cue="confirm"` picks the activate sound). `audio.hudCues: false` silences those control sounds; notice sounds are separate (`notices.cues`).
 - **Paint slot icons with `IconTreatment`, never render raw `itemId` strings.** It draws a `GameIcon` glyph over a school/element-keyed gradient with gloss, vignette, and optional count/keycap badges, reading the `--jg-slot-*` / `--jg-accent` tokens. `treatedItemIcon(itemId)` / `treatedActionIcon(action)` are ready adapters for hotbars and ability bars.
 - **Player death gets a visible screen and respawn feedback — never a silent teleport.** Build the moment `game-design` requires: an authored death/downed overlay that reads the lethal event, communicates the consequence, and surfaces the way back (respawn/revive/restart). Drive it from `createDownedState` (`@jgengine/core/combat`) rather than a hand-rolled flag, and mount it inside `HudCanvas`.
 - **Browser interruption listeners are shared.** Use `useBrowserSuspension` from `@jgengine/react/browserLifecycle` for blur, hidden-page and pointer-lock loss. Keep the decision to pause, release controls or preserve multiplayer simulation in the callback; use options to disable unwanted triggers.
@@ -43,7 +43,7 @@ Existing React games keep their entity store and use the focused
 
 ## Shared-world interaction rules
 
-- **Refusals and notices are engine feedback, not per-game toasts.** Return `{ reason: "insufficient-gold", message: "Needs 40 more gold" }` from a command's `validate`: the shell shows `message` in the shared notice feed with the deny cue and stacks repeats. Push other player messages with `ctx.game.notices.push({ text, tone })` (info/success/warn/deny) from game logic instead of a hand-built toast list. Tune or hide the stock feed with `notices: { placement, hidden }` (`hidden` keeps cues and lets the game render `useNoticeList(ctx.game.notices)` itself).
+- **Refusals and notices are engine feedback, not per-game toasts.** Return `{ reason: "insufficient-gold", message: "Needs 40 more gold" }` from a command's `validate`: the shell shows `message` in the shared notice feed with the deny cue and stacks repeats. Push other player messages with `ctx.game.notices.push({ text, tone })` (info/success/warn/deny) from game logic instead of a hand-built toast list. The stack renders inside the HUD theme root, so it takes the game's `hudTheme` colours and font; a top or bottom stack moves clear of `HudCanvas` panels and touch controls in its column and sits above `ModalHost` (z 85). Tune or hide it with `notices: { placement, offset, avoidHud, zIndex, cues, hidden }` (`hidden` keeps cues and lets the game render `useNoticeList(ctx.game.notices)` itself); `push({ text, silent: true })` skips one notice's sound.
 - **UI sounds come from `useUiCue()`.** Engine primitives already sound through the shell; for game-owned markup call `cue("click" | "hover" | "open" | "close" | "confirm" | "deny" | "notify")` from buttons and panels; replace a default by declaring `audio.sounds["ui.click"]`, or silence with `audio.uiCues: { hover: false }` / `false`.
 - Every rejected verb displays its reason on the triggering surface. Use `useServerSession(transport, gameId)` for join lifecycle. Join failure blocks play with `JoinGate` and retry; returning `{ ok: false }` without feedback is incomplete.
 - Placement previews display claim cost and affordability inline with `TerritoryOverlay`.