@jgengine/core 0.14.0 → 0.15.0

package/dist/combat/regenShield.js

@@ -4,46 +4,94 @@
  * @capability regen-shield a rechargeable overshield that absorbs damage and refills after a lull
  */
 export function createRegenShield(config) {
-    let max = Math.max(0, config.max);
+    const pool = config.pool;
     const regenPerSecond = Math.max(0, config.regenPerSecond);
     const regenDelayMs = Math.max(0, config.regenDelayMs);
     function clamp(value, ceiling) {
         return Math.max(0, Math.min(ceiling, value));
     }
-    let current = clamp(config.current ?? max, max);
+    let ownMax = Math.max(0, config.max);
+    let ownCurrent = clamp(config.current ?? ownMax, ownMax);
     let sinceDamageMs = regenDelayMs;
+    /** Grace period currently in force — the configured one until a `tick` overrides it. */
+    let activeDelayMs = regenDelayMs;
+    const readMax = () => (pool === undefined ? ownMax : Math.max(0, pool.max()));
+    const readCurrent = () => (pool === undefined ? ownCurrent : clamp(pool.current(), readMax()));
+    function write(value) {
+        const next = clamp(value, readMax());
+        if (pool === undefined)
+            ownCurrent = next;
+        else
+            pool.set(next);
+    }
+    /**
+     * Last value this shield knows about, so a pool-backed shield can tell its own writes apart from
+     * damage applied elsewhere. `null` until the first observation, so the first tick never reads a
+     * cold start as a hit.
+     */
+    let observed = pool === undefined ? null : readCurrent();
+    /** Detect an external decrease in a pool-backed value and restart the grace period if one happened. */
+    function syncExternal() {
+        if (pool === undefined)
+            return;
+        const live = readCurrent();
+        if (observed !== null && live < observed)
+            sinceDamageMs = 0;
+        observed = live;
+    }
     return {
-        current: () => current,
-        max: () => max,
+        current: readCurrent,
+        max: readMax,
         setMax(value) {
-            max = Math.max(0, value);
-            current = clamp(current, max);
+            // A pool owns its own bounds (an entity stat's max, a save record's cap); resizing it here
+            // would silently disagree with whatever else writes that storage.
+            if (pool !== undefined)
+                return;
+            ownMax = Math.max(0, value);
+            ownCurrent = clamp(ownCurrent, ownMax);
         },
-        fraction: () => (max <= 0 ? 0 : current / max),
-        isFull: () => current >= max,
-        isBroken: () => current <= 0,
-        suppressed: () => sinceDamageMs < regenDelayMs,
+        fraction: () => (readMax() <= 0 ? 0 : readCurrent() / readMax()),
+        isFull: () => readCurrent() >= readMax(),
+        isBroken: () => readCurrent() <= 0,
+        suppressed: () => sinceDamageMs < activeDelayMs,
         damage(amount) {
             if (amount <= 0)
                 return 0;
+            syncExternal();
             sinceDamageMs = 0;
-            const overflow = Math.max(0, amount - current);
-            current = clamp(current - amount, max);
+            const live = readCurrent();
+            const overflow = Math.max(0, amount - live);
+            write(live - amount);
+            observed = pool === undefined ? observed : readCurrent();
             return overflow;
         },
         restore(amount) {
-            if (amount > 0)
-                current = clamp(current + amount, max);
+            if (amount <= 0)
+                return;
+            syncExternal();
+            write(readCurrent() + amount);
+            observed = pool === undefined ? observed : readCurrent();
         },
         set(value) {
-            current = clamp(value, max);
+            write(value);
+            observed = pool === undefined ? observed : readCurrent();
+        },
+        noteDamage() {
+            syncExternal();
+            sinceDamageMs = 0;
         },
-        tick(dtSeconds) {
+        tick(dtSeconds, rates) {
+            activeDelayMs = Math.max(0, rates?.regenDelayMs ?? regenDelayMs);
             if (dtSeconds <= 0)
                 return;
+            // Advance time first, THEN observe: damage that landed since the last tick resets the timer to
+            // zero for this tick, so the tick that sees a hit never also regenerates over it.
             sinceDamageMs += dtSeconds * 1000;
-            if (sinceDamageMs >= regenDelayMs)
-                current = clamp(current + regenPerSecond * dtSeconds, max);
+            syncExternal();
+            if (sinceDamageMs < activeDelayMs)
+                return;
+            write(readCurrent() + Math.max(0, rates?.regenPerSecond ?? regenPerSecond) * dtSeconds);
+            observed = pool === undefined ? observed : readCurrent();
         },
     };
 }

package/dist/combat/resourcePool.d.ts

@@ -4,6 +4,19 @@ export interface ResourcePoolConfig {
     regenPerSecond?: number;
     decayPerSecond?: number;
 }
+/** Complete serializable state for a {@link ResourcePool}. */
+export interface ResourcePoolSnapshot {
+    current: number;
+    max: number;
+    regenPerSecond: number;
+    decayPerSecond: number;
+}
+/** Runtime tuning patch for {@link ResourcePool.retune} — omitted fields keep their current value. */
+export interface ResourcePoolRetune {
+    max?: number;
+    regenPerSecond?: number;
+    decayPerSecond?: number;
+}
 export interface ResourcePool {
     current(): number;
     max(): number;
@@ -16,6 +29,12 @@ export interface ResourcePool {
     tick(dtSeconds: number): void;
     isFull(): boolean;
     isEmpty(): boolean;
+    /** The whole pool as plain data — save it, ship it to a host, diff it in a test. */
+    snapshot(): ResourcePoolSnapshot;
+    /** Adopt a snapshot, replacing current value and tuning. */
+    restore(state: ResourcePoolSnapshot): void;
+    /** Change regen/decay/max mid-run (a buff, a difficulty change) without rebuilding the pool. */
+    retune(patch: ResourcePoolRetune): void;
 }
 /**
  * A regenerating resource pool — mana, stamina, energy — that actions spend from and that refills over time.

package/dist/combat/resourcePool.js

@@ -5,8 +5,8 @@
  */
 export function createResourcePool(config) {
     let max = Math.max(0, config.max);
-    const regenPerSecond = Math.max(0, config.regenPerSecond ?? 0);
-    const decayPerSecond = Math.max(0, config.decayPerSecond ?? 0);
+    let regenPerSecond = Math.max(0, config.regenPerSecond ?? 0);
+    let decayPerSecond = Math.max(0, config.decayPerSecond ?? 0);
     let current = clamp(config.initial ?? max, max);
     function clamp(value, ceiling) {
         return Math.max(0, Math.min(ceiling, value));
@@ -56,5 +56,23 @@ export function createResourcePool(config) {
         isEmpty() {
             return current <= 0;
         },
+        snapshot() {
+            return { current, max, regenPerSecond, decayPerSecond };
+        },
+        restore(state) {
+            max = Math.max(0, state.max);
+            regenPerSecond = Math.max(0, state.regenPerSecond);
+            decayPerSecond = Math.max(0, state.decayPerSecond);
+            current = clamp(state.current, max);
+        },
+        retune(patch) {
+            if (patch.max !== undefined)
+                max = Math.max(0, patch.max);
+            if (patch.regenPerSecond !== undefined)
+                regenPerSecond = Math.max(0, patch.regenPerSecond);
+            if (patch.decayPerSecond !== undefined)
+                decayPerSecond = Math.max(0, patch.decayPerSecond);
+            current = clamp(current, max);
+        },
     };
 }

package/dist/combat/shotOrigin.d.ts

@@ -43,6 +43,11 @@ export type ShotOriginPolicy = {
     origin: EntityPosition;
     direction?: EntityPosition;
 };
+/**
+ * A shot's resolved firing geometry in world space: `origin` is the point the projectile/ray starts
+ * from and `direction` is its normalized aim vector, both computed by {@link resolveShot} from the
+ * shooter's position, facing, and the chosen origin policy.
+ */
 export interface ResolvedShot {
     origin: EntityPosition;
     direction: EntityPosition;

package/dist/combat/statusApplication.d.ts

@@ -70,7 +70,7 @@ export interface StatusApplicationInput {
     immunity?: StatusImmunity | null;
     /** Attribution written onto the resulting instance. */
     source?: string;
-    /** Deterministic RNG returning `[0,1)`; defaults to `Math.random`. Pass a seeded stream for reproducibility. */
+    /** Deterministic RNG returning `[0,1)`. Omitting it falls back to `Math.random` and warns once — pass `ctx.rng` or a seeded stream. */
     rng?: () => number;
 }
 /** Why an application did or did not take, plus the roll for provenance. */

package/dist/combat/statusApplication.js

@@ -1,3 +1,4 @@
+import { resolveRng } from "../random/resolveRng.js";
 function clamp01(value) {
     if (value < 0)
         return 0;
@@ -15,7 +16,7 @@ function clamp01(value) {
  */
 export function resolveStatusApplication(input) {
     const { spec, scale, current, immunity, source } = input;
-    const rng = input.rng ?? Math.random;
+    const rng = resolveRng(input.rng, "applyStatus");
     if (immunity?.statuses?.includes(spec.status) === true) {
         return { kind: "immune", instance: current ?? null, chance: 0, roll: null };
     }

package/dist/combat/statusEffectView.d.ts

@@ -0,0 +1,56 @@
+import type { StatusInstance } from "./statusApplication.js";
+/**
+ * A serializable, presentation-ready snapshot of one active status for a timeline HUD row:
+ * a stable list `id`, the free-string `kind` the game styles (color / label / icon), the
+ * countdown-ring inputs `remainingMs` / `durationMs`, the `stacks` badge count, and the optional
+ * `magnitude` in force. Derived from a live {@link StatusInstance} via {@link toStatusEffectView}.
+ * The engine never interprets `kind` — it is a reference the game skins, not a built-in condition.
+ */
+export interface StatusEffectView {
+    /** Stable list key. Defaults to the status id; override when several instances share a status. */
+    id: string;
+    /** The free-string status id (`"poison"`, `"haste"`, `"shield"`) — the game styles it. */
+    kind: string;
+    /** Milliseconds of life remaining (the numerator of the ring fraction). */
+    remainingMs: number;
+    /** The status's full (unelapsed) duration in ms (the ring denominator). */
+    durationMs: number;
+    /** Current stack count (>= 1 while active). */
+    stacks: number;
+    /** Per-application magnitude in force, when the source status tracks one. */
+    magnitude?: number;
+}
+/** Options for {@link toStatusEffectView} / {@link toStatusEffectViews}. */
+export interface StatusEffectViewOptions {
+    /**
+     * The status's full (unelapsed) duration in ms — the countdown-ring denominator. A fixed number,
+     * or a resolver keyed off the instance (base durations usually live in the game's spec table, not
+     * on the live {@link StatusInstance}, which only carries `remainingMs`). When omitted or
+     * non-positive for an instance, the view reports `durationMs === remainingMs` so the ring shows
+     * full — the elapsed fraction is simply unknown, never negative.
+     */
+    durationMs?: number | ((instance: StatusInstance) => number);
+    /** Derive the stable list key; defaults to the status id. */
+    id?: (instance: StatusInstance) => string;
+}
+/**
+ * Map one live {@link StatusInstance} to a serializable {@link StatusEffectView} for a HUD row.
+ * Pure: no clock, no allocation beyond the returned view. The `durationMs` option supplies the ring
+ * denominator the instance does not carry; without it the ring reads full.
+ *
+ * @capability status-effect-view adapt one live status instance into a serializable timeline-HUD view (id, kind, remaining/duration, stacks)
+ */
+export declare function toStatusEffectView(instance: StatusInstance, options?: StatusEffectViewOptions): StatusEffectView;
+/**
+ * Map a list of live statuses (a target's carried {@link StatusInstance}s) to ordered HUD views.
+ * Pure and allocation-bounded — one pass, one view per input — so a status bar can render straight
+ * off the existing status model's snapshot without re-deriving ring math or timers.
+ *
+ * @capability status-effect-timeline adapt live status instances into serializable timeline-HUD views (id, kind, remaining/duration, stacks) for a countdown-ring effect bar
+ */
+export declare function toStatusEffectViews(instances: readonly StatusInstance[], options?: StatusEffectViewOptions): StatusEffectView[];
+/**
+ * Fraction of the countdown still remaining, clamped to `[0,1]` — the value a countdown ring fills
+ * to. Returns `0` when the duration is non-positive. Pure; safe to call every frame.
+ */
+export declare function statusEffectRemainingFraction(view: StatusEffectView): number;

package/dist/combat/statusEffectView.js

@@ -0,0 +1,52 @@
+function resolveDurationMs(instance, options) {
+    const raw = typeof options?.durationMs === "function" ? options.durationMs(instance) : options?.durationMs;
+    if (raw === undefined || !Number.isFinite(raw) || raw <= 0)
+        return instance.remainingMs;
+    return Math.max(raw, instance.remainingMs);
+}
+/**
+ * Map one live {@link StatusInstance} to a serializable {@link StatusEffectView} for a HUD row.
+ * Pure: no clock, no allocation beyond the returned view. The `durationMs` option supplies the ring
+ * denominator the instance does not carry; without it the ring reads full.
+ *
+ * @capability status-effect-view adapt one live status instance into a serializable timeline-HUD view (id, kind, remaining/duration, stacks)
+ */
+export function toStatusEffectView(instance, options) {
+    const view = {
+        id: options?.id?.(instance) ?? instance.status,
+        kind: instance.status,
+        remainingMs: Math.max(0, instance.remainingMs),
+        durationMs: resolveDurationMs(instance, options),
+        stacks: instance.stacks,
+    };
+    if (instance.magnitude !== 0)
+        view.magnitude = instance.magnitude;
+    return view;
+}
+/**
+ * Map a list of live statuses (a target's carried {@link StatusInstance}s) to ordered HUD views.
+ * Pure and allocation-bounded — one pass, one view per input — so a status bar can render straight
+ * off the existing status model's snapshot without re-deriving ring math or timers.
+ *
+ * @capability status-effect-timeline adapt live status instances into serializable timeline-HUD views (id, kind, remaining/duration, stacks) for a countdown-ring effect bar
+ */
+export function toStatusEffectViews(instances, options) {
+    const views = [];
+    for (const instance of instances)
+        views.push(toStatusEffectView(instance, options));
+    return views;
+}
+/**
+ * Fraction of the countdown still remaining, clamped to `[0,1]` — the value a countdown ring fills
+ * to. Returns `0` when the duration is non-positive. Pure; safe to call every frame.
+ */
+export function statusEffectRemainingFraction(view) {
+    if (view.durationMs <= 0)
+        return 0;
+    const fraction = view.remainingMs / view.durationMs;
+    if (fraction < 0)
+        return 0;
+    if (fraction > 1)
+        return 1;
+    return fraction;
+}

package/dist/combat.d.ts

@@ -3,6 +3,7 @@ export { type AnimationClip, type FrameRange } from "./combat/animationState.js"
 export { attackMeta, counters, isBlockable, isDodgeable, isParryable } from "./combat/attackTags.js";
 export { createBuildupMeter, createStaggerMeter, type BuildupProc } from "./combat/breakMeters.js";
 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 { 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";
@@ -10,7 +11,7 @@ export { resolveMatchup, type DamageChannelId, type DamageMatchup, type MatchupO
 export { resolveDamageHit, type DamageHitInput, type DamageHitResolution } from "./combat/damageResolution.js";
 export { createDeathSystem, type OnDeathSpec } from "./combat/death.js";
 export { type DeathReason } from "./combat/deathReason.js";
-export { createDefensiveWindow, resolveDefense } from "./combat/defensiveWindow.js";
+export { createDefensiveWindow, resolveDefense, type DefenseResolution } from "./combat/defensiveWindow.js";
 export { createDotField } from "./combat/dotField.js";
 export { createDownedState } from "./combat/downed.js";
 export { createEffectSystem, type ReceiveMap } from "./combat/effects.js";
@@ -24,8 +25,9 @@ export { DEFAULT_FIRE_PULSE_SECONDS, DEFAULT_HIT_PULSE_SECONDS, DEFAULT_RENDER_C
 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 ShotOriginPolicy, } from "./combat/shotOrigin.js";
+export { DEFAULT_EYE_HEIGHT, convergeShot, eyeHeightFromColliders, resolveShot, type ResolvedShot, type ShotOriginPolicy, } from "./combat/shotOrigin.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 { 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";

package/dist/combat.js

@@ -3,6 +3,7 @@ export {} from "./combat/animationState.js";
 export { attackMeta, counters, isBlockable, isDodgeable, isParryable } from "./combat/attackTags.js";
 export { createBuildupMeter, createStaggerMeter } from "./combat/breakMeters.js";
 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 { MAX_INTERCEPT_STEPS, createAntiOneShotPolicy, createDamageClamp, createDamagePipeline, createImmunityWindow, resolveDamage, } from "./combat/damageInterceptors.js";
@@ -26,6 +27,7 @@ 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 { resolveStatusApplication, } from "./combat/statusApplication.js";
+export { statusEffectRemainingFraction, toStatusEffectView, toStatusEffectViews, } from "./combat/statusEffectView.js";
 export {} from "./combat/telegraph.js";
 export { createThresholdTracker, } from "./combat/thresholdCrossings.js";
 export { DEFAULT_VFX_PRESET, resolveVfxPreset, vfxPresets, } from "./combat/vfxPresets.js";

package/dist/devtools/fallbackSeams.d.ts

@@ -7,9 +7,10 @@ export type FallbackSeam = "ground" | "entity" | "object" | "scatter";
 /**
  * Why a seam fell back: `omittedMapping` (no mapping supplied — often intended),
  * `unpulledPack` (a mapping was supplied but its asset pack is not pulled/indexed),
- * `noScene` (nothing authored — e.g. no environment component).
+ * `noScene` (nothing authored — e.g. no environment component),
+ * `renderError` (authored content was found but threw while rendering — always a defect).
  */
-export type FallbackCause = "omittedMapping" | "unpulledPack" | "noScene";
+export type FallbackCause = "omittedMapping" | "unpulledPack" | "noScene" | "renderError";
 /** A per-seam, per-cause count table. Serializable, allocation-stable (keys never change). */
 export type FallbackSeamCounts = Record<FallbackSeam, Record<FallbackCause, number>>;
 /** Non-zero-only view of {@link FallbackSeamCounts} returned by {@link fallbackSeamsSnapshot}. */

package/dist/devtools/fallbackSeams.js

@@ -1,6 +1,6 @@
 import { devtools } from "./devtools.js";
 const SEAMS = ["ground", "entity", "object", "scatter"];
-const CAUSES = ["omittedMapping", "unpulledPack", "noScene"];
+const CAUSES = ["omittedMapping", "unpulledPack", "noScene", "renderError"];
 function freshCounts() {
     const out = {};
     for (const seam of SEAMS) {

package/dist/devtools/textureErrors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * One texture (or other GLB sub-resource) that failed to load, plus how many times
+ * a load for that URL errored. Serializable so it flows through the `debug_snapshot`
+ * RPC exactly like {@link import("./fallbackSeams.js").FallbackSeamsReport}.
+ */
+export interface TextureLoadError {
+    /** The URL the loader tried and failed to fetch (e.g. a `THREE.GLTFLoader` texture image). */
+    url: string;
+    /** How many load attempts for this URL have errored since the probe was armed. */
+    count: number;
+}
+/**
+ * Arm or disarm the texture-load-error diagnostic. Off by default; the shell arms it only when devtools
+ * is enabled (dev builds), so production is a pure no-op. Toggling clears the tally so a fresh observation
+ * starts empty and the opt-out path reports nothing.
+ * @capability render-fallback-diagnostics Enable/disable the dev-only texture-load-error probe.
+ */
+export declare function armTextureErrors(on: boolean): void;
+/**
+ * Clear the texture-error tally without changing the armed state. Used to bracket a fresh observation
+ * (e.g. between scenes or in tests). No-op when disarmed.
+ * @capability render-fallback-diagnostics Reset the texture-load-error tally.
+ */
+export declare function resetTextureErrors(): void;
+/**
+ * Record that a sub-resource load ERRORED for `url` (called from the shared GLB loading manager's
+ * `onError`, which fires for GLTF textures/images whose fetch 404s or otherwise fails — the failure the
+ * whole-model fallback probe never sees because the model itself still resolves). A pure, allocation-free
+ * no-op when disarmed. On the armed path it also emits ONE deduped devtools warn line per newly-seen
+ * failure set so a texture-404'd scene is loud, not silent.
+ * @capability render-fallback-diagnostics Report a texture/sub-resource load failure.
+ */
+export declare function reportTextureLoadError(url: string): void;
+/**
+ * Snapshot the current texture-load-error tally as a compact, serializable list (empty when nothing
+ * failed). Flows into the devtools `textureErrors` probe and the `debug_snapshot` RPC so `jgengine-verify`
+ * can treat a non-empty set exactly like a model fallback: content that resolved but is visibly broken.
+ * @capability render-fallback-diagnostics Read per-URL texture/sub-resource load-failure counts.
+ */
+export declare function textureErrorsSnapshot(): TextureLoadError[];

package/dist/devtools/textureErrors.js

@@ -0,0 +1,68 @@
+import { devtools } from "./devtools.js";
+// Module-private state. `enabled` gates every mutation so production (devtools off) is a pure no-op;
+// `counts` is the authoritative per-URL error tally. A Map keeps report O(1) and allocation-free on
+// repeat errors (only a first-seen URL allocates a key), matching the allocation-aware fallback probe.
+let enabled = false;
+const counts = new Map();
+let lastSignature = "";
+/**
+ * Arm or disarm the texture-load-error diagnostic. Off by default; the shell arms it only when devtools
+ * is enabled (dev builds), so production is a pure no-op. Toggling clears the tally so a fresh observation
+ * starts empty and the opt-out path reports nothing.
+ * @capability render-fallback-diagnostics Enable/disable the dev-only texture-load-error probe.
+ */
+export function armTextureErrors(on) {
+    enabled = on;
+    counts.clear();
+    lastSignature = "";
+}
+/**
+ * Clear the texture-error tally without changing the armed state. Used to bracket a fresh observation
+ * (e.g. between scenes or in tests). No-op when disarmed.
+ * @capability render-fallback-diagnostics Reset the texture-load-error tally.
+ */
+export function resetTextureErrors() {
+    if (!enabled)
+        return;
+    counts.clear();
+    lastSignature = "";
+}
+/**
+ * Record that a sub-resource load ERRORED for `url` (called from the shared GLB loading manager's
+ * `onError`, which fires for GLTF textures/images whose fetch 404s or otherwise fails — the failure the
+ * whole-model fallback probe never sees because the model itself still resolves). A pure, allocation-free
+ * no-op when disarmed. On the armed path it also emits ONE deduped devtools warn line per newly-seen
+ * failure set so a texture-404'd scene is loud, not silent.
+ * @capability render-fallback-diagnostics Report a texture/sub-resource load failure.
+ */
+export function reportTextureLoadError(url) {
+    if (!enabled)
+        return;
+    counts.set(url, (counts.get(url) ?? 0) + 1);
+    const sig = signature();
+    if (sig === lastSignature)
+        return;
+    lastSignature = sig;
+    devtools.logs.push("warn", `[jgengine] texture/sub-resource loads failed — ${sig.replaceAll("|", ", ")}. ` +
+        `The model resolved but its textures 404'd; fix the asset path/pack or the scene renders untextured.`);
+}
+// Keys on the SET of failed URLs, not their counts, so re-erroring the same texture (counts keep
+// growing as the loader retries) does not re-warn — only a newly-seen failing URL widens the line.
+function signature() {
+    let sig = "";
+    for (const url of counts.keys())
+        sig += `${url}|`;
+    return sig.replace(/\|$/, "");
+}
+/**
+ * Snapshot the current texture-load-error tally as a compact, serializable list (empty when nothing
+ * failed). Flows into the devtools `textureErrors` probe and the `debug_snapshot` RPC so `jgengine-verify`
+ * can treat a non-empty set exactly like a model fallback: content that resolved but is visibly broken.
+ * @capability render-fallback-diagnostics Read per-URL texture/sub-resource load-failure counts.
+ */
+export function textureErrorsSnapshot() {
+    const out = [];
+    for (const [url, count] of counts)
+        out.push({ url, count });
+    return out;
+}

package/dist/economy/shopStock.d.ts

@@ -0,0 +1,110 @@
+import { type WalletState } from "./wallet.js";
+/**
+ * A price tag: how much of a free-string `currency` an entry costs (buy) or returns (sell).
+ * `amount` is a non-negative finite number; `0` means free (no wallet charge/grant happens).
+ */
+export interface ShopPrice {
+    /** Free-string currency key the game owns — matches a {@link WalletState} balance key. Never interpreted. */
+    currency: string;
+    /** Non-negative finite quantity of `currency`. */
+    amount: number;
+}
+/** One item a vendor stocks. Fully serializable; `kind` and `currency` are free strings the model never branches on. */
+export interface ShopStockEntry {
+    /** Stable unique id within the shop. */
+    id: string;
+    /** Free-string label the game owns and styles ("potion", "blade", "charm", …). The model never interprets it. */
+    kind: string;
+    /** What it costs to buy one. */
+    price: ShopPrice;
+    /** Units on hand: a non-negative integer, or `null` for unlimited (never decrements, never sells out). */
+    qty: number | null;
+    /** Optional buy-back price paid to the wallet on {@link ShopStock.sell}. Omitted means the item is not sellable. */
+    sellPrice?: ShopPrice;
+}
+/** Config for {@link createShopStock}: the initial set of entries. */
+export interface ShopStockConfig {
+    /** Initial stock. Ids must be unique; a duplicate id throws. */
+    entries?: readonly ShopStockEntry[];
+}
+/** Why a {@link ShopStock.buy} was refused. */
+export type ShopBuyRejection = "unknown-item" | "out-of-stock" | "insufficient-funds";
+/** Why a {@link ShopStock.sell} was refused. */
+export type ShopSellRejection = "unknown-item" | "not-sellable";
+/**
+ * Result of {@link ShopStock.buy}: on success the caller receives the debited `wallet` to adopt and a
+ * snapshot of the purchased `entry` (post-decrement); on failure a `reason` and the wallet is untouched.
+ */
+export type ShopBuyResult = {
+    ok: true;
+    wallet: WalletState;
+    entry: ShopStockEntry;
+} | {
+    ok: false;
+    reason: ShopBuyRejection;
+};
+/**
+ * Result of {@link ShopStock.sell}: on success the caller receives the credited `wallet` and a snapshot
+ * of the sold `entry` (post-restock); on failure a `reason` and the wallet is untouched.
+ */
+export type ShopSellResult = {
+    ok: true;
+    wallet: WalletState;
+    entry: ShopStockEntry;
+} | {
+    ok: false;
+    reason: ShopSellRejection;
+};
+/** Serializable state of a shop's stock, for save/restore. */
+export interface ShopStockSnapshot {
+    entries: readonly ShopStockEntry[];
+}
+/** A live, observable vendor/shop stock operating over a caller-owned wallet. */
+export interface ShopStock {
+    /**
+     * Buy one unit of `id` against `wallet` (the shop never owns the wallet). Debits the entry's `price`
+     * via {@link charge}, decrements a finite `qty`, and returns the new wallet to adopt plus the entry
+     * snapshot. Rejects `"unknown-item"`, `"out-of-stock"` (finite qty at 0), or `"insufficient-funds"`
+     * — the passed wallet is never mutated.
+     */
+    buy(id: string, wallet: WalletState): ShopBuyResult;
+    /**
+     * Sell one unit of `id` back to the vendor, crediting the entry's `sellPrice` to `wallet` via
+     * {@link grant} and incrementing a finite `qty`. Rejects `"unknown-item"` or `"not-sellable"`
+     * (no `sellPrice`). The passed wallet is never mutated.
+     */
+    sell(id: string, wallet: WalletState): ShopSellResult;
+    /** Whether `wallet` can currently afford one unit of `id` (false for unknown or sold-out items). */
+    canAfford(id: string, wallet: WalletState): boolean;
+    /** Add `n` units to a finite-`qty` entry (no-op for unlimited stock). Notifies subscribers. */
+    restock(id: string, n: number): void;
+    /** Replace an entry's buy `price`. Notifies subscribers. */
+    setPrice(id: string, price: ShopPrice): void;
+    /** Insert a new entry. Throws if its id already exists. Notifies subscribers. */
+    add(entry: ShopStockEntry): void;
+    /** Remove an entry by id (no-op if absent). Notifies subscribers. */
+    remove(id: string): void;
+    /** A snapshot array of every entry, in insertion order (safe to retain — copies, not live records). */
+    list(): ShopStockEntry[];
+    /** A snapshot of one entry, or `null` if unknown (safe to retain). */
+    get(id: string): ShopStockEntry | null;
+    /** Observe changes (buy, sell, restock, setPrice, add, remove, restore). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ShopStockSnapshot;
+    /** Restore from a {@link ShopStockSnapshot}, replacing all entries. Notifies subscribers. */
+    restore(snapshot: ShopStockSnapshot): void;
+}
+/**
+ * A serializable, observable vendor/shop stock. Each entry carries a game-owned free-string `kind`, a
+ * `price` in a free-string `currency`, a finite or unlimited (`qty: null`) count, and an optional
+ * `sellPrice` buy-back. All currency math is delegated to the existing pure `wallet` model — `buy`
+ * charges and `sell` grants a **caller-owned** {@link WalletState} (the shop never holds the wallet, it
+ * returns the new wallet for the caller to adopt), so the same stock composes with any wallet the game
+ * owns. Nothing here is genre-specific: `kind` and `currency` are free labels the game styles and the
+ * model never branches on. `restock`/`setPrice`/`add`/`remove` mutate the catalog, `subscribe` observes
+ * every change, and `snapshot`/`restore` round-trips the whole stock through a save.
+ *
+ * @capability shop-grid serializable vendor/shop stock with buy/sell over a caller-owned wallet — finite/unlimited qty, sell-back, restock/setPrice, snapshot/restore
+ */
+export declare function createShopStock(config?: ShopStockConfig): ShopStock;