@jgengine/core 0.25.0 → 0.26.0

package/dist/combat.d.ts

@@ -6,9 +6,12 @@ export { createCastRunner } from "./combat/castRunner.js";
 export { createComboMeter, type ComboMeter, type ComboMeterConfig, type ComboMeterSnapshot, type ComboMeterView, type ComboTier, } from "./combat/comboMeter.js";
 export { createComboPoints } from "./combat/comboPoints.js";
 export { advanceCombo, createComboRunner, type ComboStep } from "./combat/comboString.js";
+export { coverPointsFromSolids, coverPointsNear, createCoverField, scoreCoverPoint, selectCover, type CoverChoice, type CoverField, type CoverFieldOptions, type CoverFieldSnapshot, type CoverPoint, type CoverPointOptions, type CoverQuery, type CoverSolid, type CoverSource, type CoverThreat, type CoverWeights, } from "./combat/cover.js";
 export { MAX_INTERCEPT_STEPS, createAntiOneShotPolicy, createDamageClamp, createDamagePipeline, createImmunityWindow, resolveDamage, type AntiOneShotConfig, type AntiOneShotPolicy, type DamageClampConfig, type DamageInterceptor, type DamagePipeline, type DamageResolution, type ImmunityWindow, type InterceptContext, type InterceptDecision, type InterceptRecord, type PendingDamage, } from "./combat/damageInterceptors.js";
 export { resolveMatchup, type DamageChannelId, type DamageMatchup, type MatchupOutputs, type ResolvedMatchup, type TargetTraitId, } from "./combat/damageMatchup.js";
 export { resolveDamageHit, type DamageHitInput, type DamageHitResolution } from "./combat/damageResolution.js";
+export { UnknownTargetProfileError, createDamageRuntime, type DamageRuntimeConfig, type DamageRuntimeHitInput, type DamageRuntimeResolution, type DamageRuntimeRetune, type DamageRuntimeState, type DamageStatusRequest, type TargetProfile, type TimeToKill, } from "./combat/damageRuntime.js";
+export { DEFAULT_ARMOR_HALF_VALUE, DEFAULT_MAX_MITIGATION, DuplicateDamageTypeError, UnknownDamageTypeError, armorMitigation, assertDamageTable, formatDamageTable, readDamageTable, resolveTableDamage, typeBypassesArmor, typeMultiplier, type ArmorConfig, type DamageTableDef, type DamageTableRow, type DamageTypeDef, } from "./combat/damageTable.js";
 export { createDeathSystem, type OnDeathSpec } from "./combat/death.js";
 export { type DeathReason } from "./combat/deathReason.js";
 export { createDefensiveWindow, resolveDefense, type DefenseResolution } from "./combat/defensiveWindow.js";
@@ -17,6 +20,7 @@ export { createDownedState } from "./combat/downed.js";
 export { createEffectSystem, type ReceiveMap } from "./combat/effects.js";
 export { BUILTIN_COMPLETION_PREDICATES, BUILTIN_SPAWN_PROVIDERS, activePhaseId, createEncounterState, encounterProgress, forceCompletePhase, injectPhase, phaseStatus, startEncounter, updateEncounter, type CompletionPredicate, type EncounterConfig, type EncounterContext, type EncounterEvent, type EncounterPhase, type EncounterSignals, type EncounterSpawnRequest, type EncounterState, type EncounterStep, type PhaseCompletionRef, type PhaseInjectAt, type PhaseRuntime, type PhaseSpawnRef, type PhaseStatus, type PredicateContext, type SpawnProvider, type SpawnProviderContext, } from "./combat/encounterSequence.js";
 export { impactPresets, resolveHitReaction, type HitReactionConfig } from "./combat/hitReaction.js";
+export { DEFAULT_CRIT_MULTIPLIER, UnknownHitZoneError, assertHitZoneTable, hitZoneMultiplier, resolveHitZone, type HitZoneDef, type HitZoneResolution, type HitZoneTable, } from "./combat/hitZones.js";
 export { createMagazine, type Magazine, type MagazineConfig, type MagazineReserve, type MagazineSnapshot, } from "./combat/magazine.js";
 export { createProjectileSystem, type ObjectRaycastHit, type ProjectileSystemDeps, type RaycastHit, } from "./combat/projectiles.js";
 export { resolveReceivedDamage, type DamageContext, type DamagePredicate, type ReceivedDamageResult, type ReceivedModifier, type ReceivedPolicy, } from "./combat/receivedDamage.js";
@@ -26,12 +30,17 @@ export { resistanceScale, resolveResistance } from "./combat/resistance.js";
 export { createResourcePool, type ResourcePool } from "./combat/resourcePool.js";
 export { allocateRewards, filterOutcomeFor, resolveClaim, type AllocationOutcome, type AllocationRequest, type ClaimOutcome, type ClaimablePool, type RewardClaimSpec, type RewardGrant, type RewardPolicyKind, type RewardRecipient, type RewardResult, type RewardShare, } from "./combat/rewardAllocation.js";
 export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot, type ResolvedShot, type ShotOriginPolicy, } from "./combat/shotOrigin.js";
+export { createSquadCombat, type SquadCombat, type SquadCombatOptions, type SquadCombatSnapshot, type SquadCombatStats, type SquadCombatTunables, type SquadMemberSpec, type SquadMemberView, type SquadMode, } from "./combat/squadCombat.js";
+export { assignSquadRoles, threatsFromMemory, type FireDiscipline, type SquadComposition, type SquadRole, type ThreatReadOptions, type ThreatReading, } from "./combat/squadTactics.js";
 export { resolveStatusApplication, type StatusApplicationOutcome, type StatusApplicationSpec, type StatusImmunity, type StatusInstance, type StatusStackPolicy, } from "./combat/statusApplication.js";
 export { statusEffectRemainingFraction, toStatusEffectView, toStatusEffectViews, type StatusEffectView, type StatusEffectViewOptions, } from "./combat/statusEffectView.js";
+export { UnknownStatusError, createStatusRuntime, type StatusApplyOptions, type StatusDamageTick, type StatusDef, type StatusEffect, type StatusExpiredTick, type StatusRuntime, type StatusRuntimeEntry, type StatusRuntimeOptions, type StatusRuntimeState, type StatusStatTick, type StatusTickEvent, } from "./combat/statusRuntime.js";
 export { type TelegraphConfig, type TelegraphShape } from "./combat/telegraph.js";
 export { createThresholdTracker, type CrossingDirection, type CrossingPolicy, type CrossingTrigger, type ThresholdCrossing, type ThresholdCrossingConfig, type ThresholdMark, type ThresholdTracker, type ThresholdTrackerSnapshot, } from "./combat/thresholdCrossings.js";
 export { DEFAULT_VFX_PRESET, resolveVfxPreset, vfxPresets, type VfxPreset, type VfxPresetName, } from "./combat/vfxPresets.js";
+export { DEFAULT_WEAPON_PELLETS_IN_FLIGHT, MAX_WEAPON_BURST_COUNT, MAX_WEAPON_PELLETS_IN_FLIGHT, MAX_WEAPON_PELLETS_PER_SHOT, assertWeaponDefinition, weaponDamageAt, weaponIntervalMs, weaponMaxInFlight, type WeaponBurstDef, type WeaponDamageDef, type WeaponDefinition, type WeaponFalloffDef, type WeaponFireMode, type WeaponHitscanDef, type WeaponMagazineDef, type WeaponProjectileDef, type WeaponVec3, } from "./combat/weaponDefinition.js";
 export { createFireCadence, createWeaponRuntime, type FireCadence, type FireCadenceConfig, type WeaponFireResult, type WeaponFireStatus, type WeaponRuntime, type WeaponRuntimeConfig, } from "./combat/weaponFire.js";
+export { createWeaponSystem, type WeaponAim, type WeaponAmmo, type WeaponContact, type WeaponImpact, type WeaponImpactContext, type WeaponProjectileView, type WeaponReloadState, type WeaponShotRecord, type WeaponStats, type WeaponSystem, type WeaponSystemDeps, type WeaponSystemState, type WeaponTickResult, } from "./combat/weaponSystem.js";
 export { createAccumulatorMeter, tierAt, type MeterAddResult } from "./stats/accumulatorMeter.js";
 export { createEventMeter, type EventMeter, type EventMeterFeedResult } from "./stats/eventMeter.js";
 export { rollCheck, type CheckAdvantage, type CheckResult } from "./stats/rollCheck.js";

package/dist/combat.js

@@ -6,9 +6,12 @@ export { createCastRunner } from "./combat/castRunner.js";
 export { createComboMeter, } from "./combat/comboMeter.js";
 export { createComboPoints } from "./combat/comboPoints.js";
 export { advanceCombo, createComboRunner } from "./combat/comboString.js";
+export { coverPointsFromSolids, coverPointsNear, createCoverField, scoreCoverPoint, selectCover, } from "./combat/cover.js";
 export { MAX_INTERCEPT_STEPS, createAntiOneShotPolicy, createDamageClamp, createDamagePipeline, createImmunityWindow, resolveDamage, } from "./combat/damageInterceptors.js";
 export { resolveMatchup, } from "./combat/damageMatchup.js";
 export { resolveDamageHit } from "./combat/damageResolution.js";
+export { UnknownTargetProfileError, createDamageRuntime, } from "./combat/damageRuntime.js";
+export { DEFAULT_ARMOR_HALF_VALUE, DEFAULT_MAX_MITIGATION, DuplicateDamageTypeError, UnknownDamageTypeError, armorMitigation, assertDamageTable, formatDamageTable, readDamageTable, resolveTableDamage, typeBypassesArmor, typeMultiplier, } from "./combat/damageTable.js";
 export { createDeathSystem } from "./combat/death.js";
 export {} from "./combat/deathReason.js";
 export { createDefensiveWindow, resolveDefense } from "./combat/defensiveWindow.js";
@@ -17,6 +20,7 @@ export { createDownedState } from "./combat/downed.js";
 export { createEffectSystem } from "./combat/effects.js";
 export { BUILTIN_COMPLETION_PREDICATES, BUILTIN_SPAWN_PROVIDERS, activePhaseId, createEncounterState, encounterProgress, forceCompletePhase, injectPhase, phaseStatus, startEncounter, updateEncounter, } from "./combat/encounterSequence.js";
 export { impactPresets, resolveHitReaction } from "./combat/hitReaction.js";
+export { DEFAULT_CRIT_MULTIPLIER, UnknownHitZoneError, assertHitZoneTable, hitZoneMultiplier, resolveHitZone, } from "./combat/hitZones.js";
 export { createMagazine, } from "./combat/magazine.js";
 export { createProjectileSystem, } from "./combat/projectiles.js";
 export { resolveReceivedDamage, } from "./combat/receivedDamage.js";
@@ -26,12 +30,17 @@ export { resistanceScale, resolveResistance } from "./combat/resistance.js";
 export { createResourcePool } from "./combat/resourcePool.js";
 export { allocateRewards, filterOutcomeFor, resolveClaim, } from "./combat/rewardAllocation.js";
 export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot, } from "./combat/shotOrigin.js";
+export { createSquadCombat, } from "./combat/squadCombat.js";
+export { assignSquadRoles, threatsFromMemory, } from "./combat/squadTactics.js";
 export { resolveStatusApplication, } from "./combat/statusApplication.js";
 export { statusEffectRemainingFraction, toStatusEffectView, toStatusEffectViews, } from "./combat/statusEffectView.js";
+export { UnknownStatusError, createStatusRuntime, } from "./combat/statusRuntime.js";
 export {} from "./combat/telegraph.js";
 export { createThresholdTracker, } from "./combat/thresholdCrossings.js";
 export { DEFAULT_VFX_PRESET, resolveVfxPreset, vfxPresets, } from "./combat/vfxPresets.js";
+export { DEFAULT_WEAPON_PELLETS_IN_FLIGHT, MAX_WEAPON_BURST_COUNT, MAX_WEAPON_PELLETS_IN_FLIGHT, MAX_WEAPON_PELLETS_PER_SHOT, assertWeaponDefinition, weaponDamageAt, weaponIntervalMs, weaponMaxInFlight, } from "./combat/weaponDefinition.js";
 export { createFireCadence, createWeaponRuntime, } from "./combat/weaponFire.js";
+export { createWeaponSystem, } from "./combat/weaponSystem.js";
 export { createAccumulatorMeter, tierAt } from "./stats/accumulatorMeter.js";
 export { createEventMeter } from "./stats/eventMeter.js";
 export { rollCheck } from "./stats/rollCheck.js";

package/dist/devtools/devtools.d.ts

@@ -2,9 +2,11 @@ import type { TunableOptions } from "./tunableSchema.js";
 import type { Devtools, DevtoolsSnapshot, Tunable } from "./types.js";
 export type { AngleUnit, DevtoolsControlKind, DevtoolsOverrides, DiscoverySkip, OverrideApplyDiagnostic, TunableChoice, TunableInterval, TunableOptions, TunableVec2, TunableVec3, TunableVec4, ScanMeta, ScanFieldMeta, NormalizedColor, } from "./tunableSchema.js";
 export { CONTROL_SCHEMA_VERSION, OVERRIDES_FORMAT_VERSION, convertAngle, escapePathSegment, formatColor, joinTunablePath, normalizeAngle, normalizeColorValue, parseColor, parseOverridesPayload, splitTunablePath, unescapePathSegment, validateControlValue, } from "./tunableSchema.js";
-export type { Devtools, DevtoolsControl, DevtoolsLogEntry, DevtoolsLogLevel, DevtoolsSnapshot, DiscoveredEntry, FrameRecordSample, FrameStats, LatencyStats, LongFrameEvent, OverrideApplyResult, PhaseStats, RenderSample, Tunable, TunableAccessor, } from "./types.js";
-export { LONG_FRAME_MS } from "./frame.js";
+export type { Devtools, DevtoolsControl, DevtoolsLogEntry, DevtoolsLogLevel, DevtoolsLogs, DevtoolsSnapshot, DiscoveredEntry, FrameRecordSample, FrameStats, LatencyStats, LongFrameEvent, OverrideApplyResult, PhaseStats, RenderSample, SystemProbe, SystemProbeReading, Tunable, TunableAccessor, } from "./types.js";
+export { LONG_FRAME_MS } from "./report.js";
 export { formatLogMessage } from "./logs.js";
+export type { FrameWindow, GlReport, PerfQuality, PerfReport, ProfileEntry, ProfileReport, RenderReport, ReportLogLine, ReportLogs, ReportTelemetry, SceneNodeSource, } from "./report.js";
+export type { LogBusCounts, LogBusEntry, LogBusSnapshot } from "./logBus.js";
 export declare function createDevtools(): Devtools;
 export declare const devtools: Devtools;
 export declare function tunable<T>(name: string, initial: T, options?: TunableOptions<T>): Tunable<T>;

package/dist/devtools/devtools.js

@@ -5,7 +5,7 @@ import { createControlsModule } from "./controls.js";
 import { createDiscoverModule } from "./discover.js";
 import { createOverridesModule } from "./overrides.js";
 export { CONTROL_SCHEMA_VERSION, OVERRIDES_FORMAT_VERSION, convertAngle, escapePathSegment, formatColor, joinTunablePath, normalizeAngle, normalizeColorValue, parseColor, parseOverridesPayload, splitTunablePath, unescapePathSegment, validateControlValue, } from "./tunableSchema.js";
-export { LONG_FRAME_MS } from "./frame.js";
+export { LONG_FRAME_MS } from "./report.js";
 export { formatLogMessage } from "./logs.js";
 export function createDevtools() {
     const signal = createChangeSignal();
@@ -44,6 +44,7 @@ export function createDevtools() {
                 longFrames: [...frame.frame.longFrames()],
                 logs: [...logs.logs.list()],
                 probes: discover.readProbes(),
+                systems: discover.readSystems(),
                 controls: [...controls.controlRecords.values()].map((record) => ({
                     name: record.name,
                     kind: record.kind,

package/dist/devtools/discover.d.ts

@@ -1,7 +1,7 @@
 import type { ChangeSignal } from "../store/changeSignal.js";
 import { type DevtoolsControlKind, type DiscoverySkip, type TunableOptions } from "./tunableSchema.js";
 import type { ControlRecord } from "./controls.js";
-import type { Devtools, Tunable } from "./types.js";
+import type { Devtools, SystemProbeReading, Tunable } from "./types.js";
 /** Internal record for an auto-discovered field: identity, kind, initial value, source object, and get/set accessors. */
 export interface DiscoveredRecord {
     id: string;
@@ -20,6 +20,7 @@ export interface DiscoverModule {
     discover: Devtools["discover"];
     probes: Devtools["probes"];
     readProbes: () => Record<string, unknown>;
+    readSystems: () => Record<string, SystemProbeReading>;
     enableDiscovered: (id: string) => void;
     discoveredRecords: Map<string, DiscoveredRecord>;
     getDiscoverySkips: () => readonly DiscoverySkip[];

package/dist/devtools/discover.js

@@ -72,6 +72,7 @@ export const createDiscoverModule = (deps) => {
     const { signal, register, controlRecords } = deps;
     const discoveredRecords = new Map();
     const probeReaders = new Map();
+    const systemProbes = new Map();
     let boundProps = new WeakMap();
     let discoverySkips = [];
     const readProbes = () => {
@@ -86,6 +87,30 @@ export const createDiscoverModule = (deps) => {
         }
         return values;
     };
+    const finiteOnly = (values) => {
+        const out = {};
+        for (const [key, value] of Object.entries(values ?? {})) {
+            if (typeof value === "number" && Number.isFinite(value))
+                out[key] = value;
+        }
+        return out;
+    };
+    const readSystems = () => {
+        const out = {};
+        for (const [id, probe] of systemProbes) {
+            try {
+                out[id] = {
+                    counters: finiteOnly(probe.counters?.()),
+                    timers: finiteOnly(probe.timers?.()),
+                    state: probe.state?.() ?? "",
+                };
+            }
+            catch (error) {
+                out[id] = { counters: {}, timers: {}, state: `probe failed: ${formatLogArg(error)}` };
+            }
+        }
+        return out;
+    };
     const bindDiscovered = (table, key, kind, accessor, source, options) => {
         const id = `${table}/${key}`;
         const existing = discoveredRecords.get(id);
@@ -215,6 +240,7 @@ export const createDiscoverModule = (deps) => {
                         controlRecords.delete(record.id);
                     }
                 }
+                // A clear drops discovered bindings; system probes belong to their systems, not to discovery.
                 discoveredRecords.clear();
                 discoverySkips = [];
                 boundProps = new WeakMap();
@@ -231,8 +257,20 @@ export const createDiscoverModule = (deps) => {
                 };
             },
             read: readProbes,
+            registerSystem(id, probe) {
+                systemProbes.set(id, probe);
+                signal.notify();
+                return () => {
+                    if (systemProbes.get(id) !== probe)
+                        return;
+                    systemProbes.delete(id);
+                    signal.notify();
+                };
+            },
+            systems: readSystems,
         },
         readProbes,
+        readSystems,
         enableDiscovered,
         discoveredRecords,
         getDiscoverySkips: () => discoverySkips,

package/dist/devtools/frame.d.ts

@@ -1,6 +1,4 @@
 import type { Devtools } from "./types.js";
-/** Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget). */
-export declare const LONG_FRAME_MS = 33.4;
 /** @internal */
 export declare function nowMs(): number;
 /** Frame subsystem exposing the frame-timing, profiling, and render-sample facades. */

package/dist/devtools/frame.js

@@ -1,7 +1,6 @@
+import { LONG_FRAME_MS } from "./report.js";
 const FRAME_CAPACITY = 240;
 const RECENT_FRAMES = 60;
-/** Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget). */
-export const LONG_FRAME_MS = 33.4;
 const LONG_FRAME_CAPACITY = 40;
 const MAX_PHASES_PER_FRAME = 24;
 const MAX_LONG_FRAME_PHASES = 8;

package/dist/devtools/logBus.d.ts

@@ -0,0 +1,58 @@
+import type { DevtoolsLogLevel } from "./types.js";
+/** Default measured window for the log ring; older lines are evicted, never grown. */
+export declare const LOG_BUS_CAPACITY = 200;
+/** Warnings and errors also land in their own ring, so an error is never pushed out by info traffic. */
+export declare const LOG_BUS_SEVERE_CAPACITY = 64;
+/** Longest kept message; a longer one is cut once, at write time. */
+export declare const LOG_BUS_MESSAGE_MAX = 400;
+/** One captured line: when, how bad, which system said it, and what it said. */
+export interface LogBusEntry {
+    at: number;
+    level: DevtoolsLogLevel;
+    /** Owning system tag, e.g. `needs`, `nav`, `render/culling`, `console`. */
+    system: string;
+    message: string;
+}
+/** Lifetime totals per level, plus how many lines the ring dropped. */
+export interface LogBusCounts {
+    log: number;
+    info: number;
+    warn: number;
+    error: number;
+}
+/** Read-out of the log bus: newest-window entries, the warning/error ring, totals, and evictions. */
+export interface LogBusSnapshot {
+    entries: readonly LogBusEntry[];
+    severe: readonly LogBusEntry[];
+    counts: LogBusCounts;
+    dropped: number;
+    capacity: number;
+}
+/** Tunables for the log ring: capacity, the severity ring's capacity, and the clock. */
+export interface LogBusOptions {
+    capacity?: number;
+    severeCapacity?: number;
+    now?: () => number;
+}
+/**
+ * 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.
+ *
+ * @capability devtools-log-bus a bounded, per-system-tagged log ring a system writes to and a report reads
+ */
+export interface LogBus {
+    write(level: DevtoolsLogLevel, system: string, message: string): void;
+    /** Oldest-to-newest entries currently held. Allocates once per read. */
+    list(): readonly LogBusEntry[];
+    /** Warnings and errors only, oldest first. */
+    severe(): readonly LogBusEntry[];
+    counts(): LogBusCounts;
+    dropped(): number;
+    snapshot(): LogBusSnapshot;
+    /** Empty every ring and counter, keeping the allocation. */
+    reset(): void;
+}
+/** Create the bounded log bus the devtools log facade writes through. */
+export declare function createLogBus(options?: LogBusOptions): LogBus;

package/dist/devtools/logBus.js

@@ -0,0 +1,79 @@
+/** Default measured window for the log ring; older lines are evicted, never grown. */
+export const LOG_BUS_CAPACITY = 200;
+/** Warnings and errors also land in their own ring, so an error is never pushed out by info traffic. */
+export const LOG_BUS_SEVERE_CAPACITY = 64;
+/** Longest kept message; a longer one is cut once, at write time. */
+export const LOG_BUS_MESSAGE_MAX = 400;
+function blankEntry() {
+    return { at: 0, level: "log", system: "", message: "" };
+}
+function createRing(capacity) {
+    const slots = new Array(capacity);
+    for (let index = 0; index < capacity; index += 1)
+        slots[index] = blankEntry();
+    return { slots, head: 0, size: 0, total: 0 };
+}
+function ringPush(ring, at, level, system, message) {
+    const slot = ring.slots[ring.head];
+    slot.at = at;
+    slot.level = level;
+    slot.system = system;
+    slot.message = message.length > LOG_BUS_MESSAGE_MAX ? `${message.slice(0, LOG_BUS_MESSAGE_MAX)}…` : message;
+    ring.head = (ring.head + 1) % ring.slots.length;
+    if (ring.size < ring.slots.length)
+        ring.size += 1;
+    ring.total += 1;
+}
+function ringRead(ring) {
+    const out = new Array(ring.size);
+    const start = (ring.head - ring.size + ring.slots.length) % ring.slots.length;
+    for (let offset = 0; offset < ring.size; offset += 1) {
+        const slot = ring.slots[(start + offset) % ring.slots.length];
+        out[offset] = { at: slot.at, level: slot.level, system: slot.system, message: slot.message };
+    }
+    return out;
+}
+/** Create the bounded log bus the devtools log facade writes through. */
+export function createLogBus(options = {}) {
+    const capacity = Math.max(1, Math.floor(options.capacity ?? LOG_BUS_CAPACITY));
+    const severeCapacity = Math.max(1, Math.floor(options.severeCapacity ?? LOG_BUS_SEVERE_CAPACITY));
+    const now = options.now ?? Date.now;
+    const ring = createRing(capacity);
+    const severeRing = createRing(Math.min(severeCapacity, capacity));
+    const totals = { log: 0, info: 0, warn: 0, error: 0 };
+    return {
+        write(level, system, message) {
+            const at = now();
+            const text = message.length > LOG_BUS_MESSAGE_MAX ? `${message.slice(0, LOG_BUS_MESSAGE_MAX)}…` : message;
+            ringPush(ring, at, level, system, text);
+            totals[level] += 1;
+            if (level === "warn" || level === "error")
+                ringPush(severeRing, at, level, system, text);
+        },
+        list: () => ringRead(ring),
+        severe: () => ringRead(severeRing),
+        counts: () => ({ ...totals }),
+        dropped: () => Math.max(0, ring.total - ring.size),
+        snapshot() {
+            return {
+                entries: ringRead(ring),
+                severe: ringRead(severeRing),
+                counts: { ...totals },
+                dropped: Math.max(0, ring.total - ring.size),
+                capacity: ring.slots.length,
+            };
+        },
+        reset() {
+            ring.head = 0;
+            ring.size = 0;
+            ring.total = 0;
+            severeRing.head = 0;
+            severeRing.size = 0;
+            severeRing.total = 0;
+            totals.log = 0;
+            totals.info = 0;
+            totals.warn = 0;
+            totals.error = 0;
+        },
+    };
+}

package/dist/devtools/logs.d.ts

@@ -1,13 +1,16 @@
 import type { ChangeSignal } from "../store/changeSignal.js";
-import type { Devtools } from "./types.js";
+import type { DevtoolsLogs, DevtoolsLatency } from "./types.js";
+import { type LogBus } from "./logBus.js";
 /** @internal */
 export declare function formatLogArg(arg: unknown): string;
 /** Format an array of console arguments into a single truncated log message string. */
 export declare function formatLogMessage(args: readonly unknown[]): string;
 /** Logs subsystem exposing the log-capture and latency-tracking facades. */
 export interface LogsModule {
-    logs: Devtools["logs"];
-    latency: Devtools["latency"];
+    logs: DevtoolsLogs;
+    latency: DevtoolsLatency;
+    /** The ring the facade writes through, for a reporter that needs the whole window at once. */
+    bus: LogBus;
 }
 /** Create the logs subsystem that buffers captured console output and records latency samples. */
 export declare const createLogsModule: (deps: {

package/dist/devtools/logs.js

@@ -1,6 +1,5 @@
+import { createLogBus, LOG_BUS_MESSAGE_MAX } from "./logBus.js";
 const LATENCY_CAPACITY = 120;
-const LOG_CAPACITY = 200;
-const LOG_MESSAGE_MAX = 400;
 /** @internal */
 export function formatLogArg(arg) {
     if (typeof arg === "string")
@@ -17,19 +16,14 @@ export function formatLogArg(arg) {
 /** Format an array of console arguments into a single truncated log message string. */
 export function formatLogMessage(args) {
     const message = args.map(formatLogArg).join(" ");
-    return message.length > LOG_MESSAGE_MAX ? `${message.slice(0, LOG_MESSAGE_MAX)}…` : message;
+    return message.length > LOG_BUS_MESSAGE_MAX ? `${message.slice(0, LOG_BUS_MESSAGE_MAX)}…` : message;
 }
 /** Create the logs subsystem that buffers captured console output and records latency samples. */
 export const createLogsModule = (deps) => {
     const { signal } = deps;
-    const logEntries = [];
+    const bus = createLogBus();
     let consoleCaptured = false;
     const latencySamples = [];
-    const pushLog = (level, message) => {
-        logEntries.push({ at: Date.now(), level, message });
-        if (logEntries.length > LOG_CAPACITY)
-            logEntries.splice(0, logEntries.length - LOG_CAPACITY);
-    };
     const latencyStats = () => {
         if (latencySamples.length === 0)
             return null;
@@ -51,7 +45,12 @@ export const createLogsModule = (deps) => {
     };
     return {
         logs: {
-            push: pushLog,
+            write(level, system, message) {
+                bus.write(level, system, message);
+            },
+            push(level, message, system = "console") {
+                bus.write(level, system, message);
+            },
             captureConsole() {
                 if (consoleCaptured)
                     return;
@@ -63,14 +62,18 @@ export const createLogsModule = (deps) => {
                 for (const level of levels) {
                     const original = globalConsole[level].bind(globalConsole);
                     globalConsole[level] = (...args) => {
-                        pushLog(level, formatLogMessage(args));
+                        bus.write(level, "console", formatLogMessage(args));
                         original(...args);
                     };
                 }
             },
-            list: () => logEntries,
+            list: () => bus.list(),
+            severe: () => bus.severe(),
+            counts: () => bus.counts(),
+            dropped: () => bus.dropped(),
+            snapshot: () => bus.snapshot(),
             clear() {
-                logEntries.length = 0;
+                bus.reset();
                 signal.notify();
             },
         },
@@ -82,5 +85,6 @@ export const createLogsModule = (deps) => {
             },
             stats: latencyStats,
         },
+        bus,
     };
 };

package/dist/devtools/report.d.ts

@@ -0,0 +1,120 @@
+import type { LogBusCounts, LogBusSnapshot } from "./logBus.js";
+import type { DevtoolsLogLevel, SystemProbeReading } from "./types.js";
+/**
+ * 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.
+ */
+/** Frame duration above which a frame counts as a spike (~30 fps). */
+export declare const LONG_FRAME_MS = 33.4;
+/** Graphics tier the record was measured at. */
+export type PerfQuality = "full" | "draft";
+/** Where the scene-node count came from: the live scene graph, a heap walk, or nowhere. */
+export type SceneNodeSource = "scene-graph" | "heap-object3d" | "unavailable";
+/** Frame timings over the measured window, as the player sees them. */
+export interface FrameWindow {
+    fps: number;
+    avgMs: number;
+    p95Ms: number;
+    maxMs: number;
+    samples: number;
+    longFrames: number;
+}
+/** Renderer-side counts for the measured window; `null` where the source could not read them. */
+export interface RenderReport {
+    draws: number | null;
+    triangles: number | null;
+    geometries: number | null;
+    textures: number | null;
+    nodes: number | null;
+    nodesSource: SceneNodeSource;
+    scenes: number;
+}
+/** GPU-object creation counts. `total` is since the page loaded, the named fields since warmup. */
+export interface GlReport {
+    programsLinked: number;
+    framebuffers: number;
+    buffers: number;
+    textures: number;
+    vertexArrays: number;
+    allocations: number;
+    residentPrograms: number | null;
+    total: Record<string, number>;
+    /** True once the counters provably wrapped the WebGL calls; false means a zero is not evidence. */
+    attached: boolean;
+}
+/** One sampled stack frame reduced to a readable key and its self time. */
+export interface ProfileEntry {
+    fn: string;
+    at: string;
+    selfMs: number;
+    selfPct: number;
+}
+/** CPU profile summary; only the CDP harness can produce one. */
+export interface ProfileReport {
+    samplingUs: number;
+    seconds: number;
+    top: readonly ProfileEntry[];
+}
+/** One log line as it appears in the report. */
+export interface ReportLogLine {
+    at: number;
+    level: DevtoolsLogLevel;
+    system: string;
+    message: string;
+}
+/** Bounded log read-out carried by the report: warn/error lines survive even a flood of info logs. */
+export interface ReportLogs {
+    counts: LogBusCounts;
+    dropped: number;
+    severe: readonly ReportLogLine[];
+}
+/** Who produced the report, and how much producing it cost. */
+export interface ReportTelemetry {
+    source: "in-page" | "cdp";
+    /** True once the counters have a post-warmup baseline, which the link/framebuffer fields need. */
+    warmedUp: boolean;
+    /** Milliseconds since the sampler started. */
+    ageMs: number;
+    /** Milliseconds the report itself took to gather. */
+    buildMs: number;
+    heapBytes: number | null;
+}
+/** One measured window of one game: the record `bun run perf`, `window.__JG.report()` and `bun run debug` print. */
+export interface PerfReport {
+    game: string;
+    gpu: string;
+    quality: PerfQuality;
+    viewport: string;
+    /** Length of the measured frame window in seconds. */
+    seconds: number;
+    /** Wall-clock timestamp when the record was taken. */
+    at: number;
+    frame: FrameWindow;
+    render: RenderReport;
+    gl: GlReport;
+    sim: {
+        avgMs: number;
+        outsideMs: number;
+    } | null;
+    profile: ProfileReport | null;
+    /** Per-system probe readings, keyed by system id (`render/culling`, `needs`, …). */
+    systems: Record<string, SystemProbeReading>;
+    logs: ReportLogs | null;
+    telemetry: ReportTelemetry | null;
+}
+/** Round to `digits` decimals so two runs of different lengths print comparably. @internal */
+export declare function roundReport(value: number, digits?: number): number;
+/**
+ * Reduce raw frame deltas to {@link FrameWindow}. One implementation, so the CDP
+ * harness and the in-page sampler cannot disagree about fps or p95.
+ * @internal
+ */
+export declare function summarizeFrameWindow(samples: ArrayLike<number>): FrameWindow;
+/**
+ * Project a log-bus read-out onto the report's compact shape: totals plus the last
+ * twelve warning/error lines. A thrown error or a lost GL context therefore survives
+ * in the report even when hundreds of info lines followed it.
+ * @internal
+ */
+export declare function toReportLogs(snapshot: LogBusSnapshot, severeLimit?: number): ReportLogs;

package/dist/devtools/report.js

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+/** Frame duration above which a frame counts as a spike (~30 fps). */
+export const LONG_FRAME_MS = 33.4;
+/** Round to `digits` decimals so two runs of different lengths print comparably. @internal */
+export function roundReport(value, digits = 2) {
+    const scale = 10 ** digits;
+    return Math.round(value * scale) / scale;
+}
+/**
+ * Reduce raw frame deltas to {@link FrameWindow}. One implementation, so the CDP
+ * harness and the in-page sampler cannot disagree about fps or p95.
+ * @internal
+ */
+export function summarizeFrameWindow(samples) {
+    const kept = [];
+    for (let index = 0; index < samples.length; index += 1) {
+        const ms = samples[index];
+        if (Number.isFinite(ms) && ms > 0)
+            kept.push(ms);
+    }
+    if (kept.length === 0)
+        return { fps: 0, avgMs: 0, p95Ms: 0, maxMs: 0, samples: 0, longFrames: 0 };
+    const sorted = [...kept].sort((a, b) => a - b);
+    const avgMs = kept.reduce((sum, ms) => sum + ms, 0) / kept.length;
+    return {
+        fps: roundReport(1000 / avgMs, 1),
+        avgMs: roundReport(avgMs),
+        p95Ms: roundReport(sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))]),
+        maxMs: roundReport(sorted[sorted.length - 1]),
+        samples: kept.length,
+        longFrames: kept.filter((ms) => ms > LONG_FRAME_MS).length,
+    };
+}
+/**
+ * Project a log-bus read-out onto the report's compact shape: totals plus the last
+ * twelve warning/error lines. A thrown error or a lost GL context therefore survives
+ * in the report even when hundreds of info lines followed it.
+ * @internal
+ */
+export function toReportLogs(snapshot, severeLimit = 12) {
+    const severe = snapshot.severe
+        .slice(-severeLimit)
+        .map((entry) => ({ at: entry.at, level: entry.level, system: entry.system, message: entry.message }));
+    return { counts: snapshot.counts, dropped: snapshot.dropped, severe };
+}

package/dist/devtools/reportEndpoint.d.ts

@@ -0,0 +1,17 @@
+import type { PerfReport } from "./report.js";
+/**
+ * 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"`.
+ */
+export declare const REPORT_ENDPOINT_PATH = "/__jgengine/report";
+/** Body the page POSTs: the game it measured and the record itself. */
+export interface ReportPushBody {
+    gameId: string;
+    report: PerfReport;
+}
+/** Body sent when there is nothing to return yet. */
+export interface ReportRouteError {
+    error: string;
+}

package/dist/devtools/reportEndpoint.js

@@ -0,0 +1,7 @@
+/**
+ * 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"`.
+ */
+export const REPORT_ENDPOINT_PATH = "/__jgengine/report";