@jgengine/core 0.30.0 → 0.32.0

package/CHANGELOG.md

@@ -26,6 +26,57 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.32.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.32.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.29.0`; `@jgengine/github` is `0.19.0`.
+
+### Added
+
+- Audio mixing grew a mute that composes with gain: `AudioEngine.setBusMute` / `setMasterMute` keep the player's volume while silencing a bus, `masterLevel()` / `busLevel()` report the composed value, and Settings carries a mute row per bus plus "Mute all" (`sound.muted`, `sound.bus.<id>.muted`). `AudioEngine.play` and `playOneShot` hold cues in a bounded 16-slot queue while the browser keeps the context suspended and play them on the first gesture instead of dropping them; `installGestureResume` wires that gesture for both presentation paths.
+- `AudioEngine.measure()` reads master RMS and peak from a lazily built analyser, and `installAudioProbe` publishes `window.__jgengineAudio` so a headless capture can prove sound with a measured level rather than a screenshot.
+- `@jgengine/core/audio/feedbackCues` ships seven procedural reactions - `hit`, `hurt`, `kill`, `pickup`, `objective`, `wave`, `deny` - on an `sfx` bus, merged into every game's catalog as `feel.<cue>`. A game sound with that id replaces one; `audio.feedbackCues` replaces or silences them.
+- `@jgengine/shell/audio/eventFeedback` maps the events the engine already announces to those reactions: `combat.damage` (local player reads as hurt, anything else as a hit), `entity.died`, `worldItem.picked_up`, `quest.completed`, `stat.levelUp` and `command.refused`. Each row carries a sound, a gamepad pulse, camera trauma and a caption; the mapping and reactions are data (`DEFAULT_FEEDBACK_BINDINGS`, `DEFAULT_FEEDBACK_REACTIONS`) a game can replace, cooldowns fold a burst into one impact, reduced motion keeps sound and rumble but drops the camera kick, and the resolved reaction is pooled so handling an event allocates nothing per frame. `attachWaveFeedback(runner, ctx.game.feedback)` announces each new wave.
+- `ctx.game.feedback.cue(cue, caption?)` announces a moment no engine event covers and emits `feedback.cue`.
+- `@jgengine/shell/audio/captions` and `CaptionOverlay` render a bounded, deduping, self-expiring caption line under the accessibility captions setting; `FeedbackHost` mounts the whole layer - feedback mapping, gesture resume, audio probe and captions - for both the 3D and HUD presentation paths.
+
+### Changed
+
+- The CI gate runs nine test shards instead of ten, and a `types` job whose stages overlap, so a docs-only pull request fits the account's 20-job runner cap with room for another run beside it. `scripts/test-shard.ts` owns which files each shard runs and what it prepares first; `bun scripts/type-shard.ts` runs the `check-types` plan two stages at a time and then the tsc fan-out alone.
+
+## 0.31.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.31.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.28.0`; `@jgengine/github` is `0.18.0`.
+
+### Added
+
+- `createAgent` (`@jgengine/core/agents/agent`) runs one resident's whole loop on the world clock: needs decay through `sim/needs`, a utility brain picks among the targets the game offers, an authored day plan says where the agent belongs, and the agent falls back to a declared target when its pick disappears. Mood, action and the far flag snapshot and restore with the needs.
+- `createMoodReader` / `readMood` (`@jgengine/core/agents/mood`) derive a 0-100 mood and a caller-labelled tier from weighted need satisfaction, plus named sources a queue, a litter patch or a cold snap raises and clears.
+- `createAgentSchedule` (`@jgengine/core/agents/schedule`) resolves an authored day plan through `sim/routine` and adds a work beat: a stop names the places it patrols, so a janitor is an agent with a route rather than a special case. Off-hours behaviour is a stop without a beat.
+- `createRelationshipBook` (`@jgengine/core/agents/relationships`) keeps undirected familiarity and opinion per pair. A social action moves both and reports the milestones crossed, friends prefer each other's company, and a bonded pair refuses to split. Pair keys come from `relation/keyedValues` and crossings from `relation/thresholds`.
+- `GameSave.deleteSlot(slot)` and `SaveStore.deleteSlot(slot)` remove one slot's payload and drop it from the slot index; they resolve `true` when a document was removed and `false` for an unknown slot. Deleting the active slot resets the live state to the initial document. `load()` no longer lists a slot that holds nothing, so a deleted slot cannot return.
+- `HudPanel` takes `lane` (`@jgengine/react`): blocks naming the same anchor and lane stack without overlap, lanes in one anchor sit side by side, and `resolveHudLanes` resolves the rectangles. A moved panel leaves its lane and keeps its authored placement.
+- `hudBlockOverlaps` and `formatHudOverlapReport` (`@jgengine/react`) name every pair of rendered HUD blocks whose rectangles intersect, with both ids and the viewport; `HudCanvas` warns with that report in a dev build.
+- `rollDrop` (`@jgengine/core/loot/drop`) rolls one deterministic item from a seed and `compareToEquipped` turns it into per-stat deltas against worn gear with a weighted verdict a HUD can render.
+- `createRunHaul` (`@jgengine/core/loot/haul`) gates carried loot by weight through the shared encumbrance rules, banks what the persistent stash fits, and discards the run's haul when the game calls `fail`.
+- `salvageItem` and `createItemLedger` (`@jgengine/core/loot/salvage`) break an item down for the currency its level and rarity say and claim the instance, so a salvaged item cannot be salvaged, equipped or sold again.
+- `stockVendor` and `createVendorRotation` (`@jgengine/core/loot/vendor`) fill a `ShopStock` with rolled items priced through the economy wallet, with a run-count restock rule the game authors.
+- `markerProximity` on `createMissionRuntime` picks the plane a marker proximity test compares in: `"horizontal"` (default) measures ground distance and allows the actor a `tolerance` (default 8 m) above or below the marker, `"spatial"` is the straight 3D check for worlds with stacked platforms. `MissionMarkerPlane`, `MissionMarkerProximity` and `DEFAULT_MARKER_TOLERANCE` are exported with it.
+
+### Changed
+
+- `evaluatePressure` (`@jgengine/core/ai/director/pressure`) reads pressure as player control: a healthy player further into a run is leaned on harder, a hurt player is eased off, and every effect stays inside the rule's `maxTier`.
+- Loot bases and affixes take `minLevel`, so `rollLoot` only draws from entries at or below the item level. Loot bases take `mass`; rolled items carry it for carry checks.
+
+### Fixed
+
+- `HudCanvas` resolved its host with `canvas.parentElement`, which is `HudThemeRoot`'s `display: contents` element and measures 0x0 — the boundary overlay, the HUD-fit measurement and the new overlap report never ran under the standard HUD root. It now uses the nearest ancestor with a real box.
+- The HUD boundary check returned early whenever nothing overflowed, so a later report in the same pass could never run.
+- `reach`, `interact` and the `left-area` fail condition compared a marker in 3D, so a marker authored at `y=0` under rising ground was unreachable. They now read the same plane.
+
 ## 0.30.0
 
 ### Migrate

package/dist/ai/director/pressure.d.ts

@@ -5,18 +5,18 @@
  */
 /** What the director reads about the player before it chooses a tier. */
 export interface PressureReading {
-    /** Player health fraction `0..1`. Lower leans harder. */
+    /** Player health fraction `0..1`. A healthier player is leaned on harder. */
     health: number;
-    /** Encounter progress `0..1` — waves cleared over waves authored. Lower leans harder. */
+    /** Encounter progress `0..1` — waves cleared over waves authored. Further in leans harder. */
     progress: number;
     /** Seconds the encounter has run. Longer leans harder, up to the window. */
     elapsed: number;
 }
 /** The weights and window that turn a reading into an index, plus the hard cap. */
 export interface PressureRule {
-    /** Weight of low player health. Default `1`. */
+    /** Weight of the player staying in control (health). Default `0.5`. */
     healthWeight?: number;
-    /** Weight of the encounter not being finished. Default `1`. */
+    /** Weight of how far through the encounter the player is. Default `1`. */
     progressWeight?: number;
     /** Weight of time spent past `timeFloorSeconds`. Default `0.5`. */
     timeWeight?: number;
@@ -47,11 +47,12 @@ export interface PressurePlan {
 /**
  * Turn one reading into a bounded pressure plan.
  *
- * The index is the weighted mean of three terms — how hurt the player is (`1 - health`), how far
- * from finished the encounter is (`1 - progress`), and how long it has run — each clamped to
- * `0..1`, then split into `maxTier + 1` bands. Because every term and every derived effect is a
- * clamp of an authored cap, the rule cannot climb: a dead player on a stalled timer for an hour
- * lands on `tier === maxTier` with `countBonus === maxTier`, never above it.
+ * The index is the weighted mean of three terms — the player's health (staying in control), how far
+ * through the encounter they are, and how long it has run — each clamped to `0..1`, then split into
+ * `maxTier + 1` bands. A hurt player is leaned on *less*, so a director that reads this plan never
+ * piles on someone already losing. Because every term and every derived effect is a clamp of an
+ * authored cap, the rule cannot climb: a full-health player on a long run lands on
+ * `tier === maxTier` with `countBonus === maxTier`, never above it.
  *
  * @capability encounter-pressure bounded difficulty tier read from player health, encounter progress and time
  */

package/dist/ai/director/pressure.js

@@ -4,7 +4,7 @@
  * a callback, so a test can sweep it and a probe can print it.
  */
 const RULE_DEFAULTS = {
-    healthWeight: 1,
+    healthWeight: 0.5,
     progressWeight: 1,
     timeWeight: 0.5,
     timeFloorSeconds: 90,
@@ -35,11 +35,12 @@ function timeTerm(elapsed, rule) {
 /**
  * Turn one reading into a bounded pressure plan.
  *
- * The index is the weighted mean of three terms — how hurt the player is (`1 - health`), how far
- * from finished the encounter is (`1 - progress`), and how long it has run — each clamped to
- * `0..1`, then split into `maxTier + 1` bands. Because every term and every derived effect is a
- * clamp of an authored cap, the rule cannot climb: a dead player on a stalled timer for an hour
- * lands on `tier === maxTier` with `countBonus === maxTier`, never above it.
+ * The index is the weighted mean of three terms — the player's health (staying in control), how far
+ * through the encounter they are, and how long it has run — each clamped to `0..1`, then split into
+ * `maxTier + 1` bands. A hurt player is leaned on *less*, so a director that reads this plan never
+ * piles on someone already losing. Because every term and every derived effect is a clamp of an
+ * authored cap, the rule cannot climb: a full-health player on a long run lands on
+ * `tier === maxTier` with `countBonus === maxTier`, never above it.
  *
  * @capability encounter-pressure bounded difficulty tier read from player health, encounter progress and time
  */
@@ -52,8 +53,8 @@ export function evaluatePressure(reading, rule = {}) {
     const totalWeight = resolved.healthWeight + resolved.progressWeight + resolved.timeWeight;
     const index = totalWeight <= 0
         ? 0
-        : clamp01((resolved.healthWeight * (1 - health) +
-            resolved.progressWeight * (1 - progress) +
+        : clamp01((resolved.healthWeight * health +
+            resolved.progressWeight * progress +
             resolved.timeWeight * time) /
             totalWeight);
     const tier = Math.min(resolved.maxTier, Math.max(0, Math.floor(index * (resolved.maxTier + 1))));

package/dist/audio/feedbackCues.d.ts

@@ -0,0 +1,30 @@
+import type { AudioBusDef, SoundDef } from "./audioFalloff.js";
+/**
+ * A gameplay moment the engine reacts to: taking or dealing a hit, a kill, a pickup, an objective,
+ * a wave starting, or a refused action. The game names the moment; the engine owns the reaction.
+ */
+export type FeedbackCue = "hit" | "hurt" | "kill" | "pickup" | "objective" | "wave" | "deny";
+/** Every {@link FeedbackCue}, in a stable order. */
+export declare const FEEDBACK_CUES: readonly FeedbackCue[];
+/** Bus the default feedback cues mix through; the settings menu shows its volume and mute. */
+export declare const FEEDBACK_CUE_BUS = "sfx";
+/** Catalog id a cue plays under: `feel.hit`, `feel.kill`, ... A game sound with that id replaces the default. */
+export declare function feedbackCueSoundId(cue: FeedbackCue): string;
+/**
+ * Short procedural reactions - no samples to load, so every game has impact feedback without
+ * authoring audio. Loud enough to read, quiet enough to sit under a weapon's own sound.
+ */
+export declare const DEFAULT_FEEDBACK_CUE_SOUNDS: Readonly<Record<FeedbackCue, SoundDef>>;
+/** Per-cue override: a replacement sound, or `false` to silence that cue. `false` for the whole map silences all. */
+export type FeedbackCueOverrides = false | Partial<Record<FeedbackCue, SoundDef | false>>;
+/**
+ * Merge the default feedback reactions into a game's sound catalog. A game sound already named
+ * `feel.<cue>` wins, then `overrides`, then the default. Adds the `sfx` bus (gain 0.9) when the game
+ * did not declare one, so the impact layer has its own volume and mute row.
+ *
+ * @capability feedback-cue-sounds default procedural hit/hurt/kill/pickup/objective/wave/deny reactions on an "sfx" bus, overridable per game
+ */
+export declare function withFeedbackCueSounds(sounds: Readonly<Record<string, SoundDef>> | undefined, buses: Readonly<Record<string, AudioBusDef>> | undefined, overrides?: FeedbackCueOverrides): {
+    sounds: Record<string, SoundDef>;
+    buses: Record<string, AudioBusDef> | undefined;
+};

package/dist/audio/feedbackCues.js

@@ -0,0 +1,119 @@
+/** Every {@link FeedbackCue}, in a stable order. */
+export const FEEDBACK_CUES = ["hit", "hurt", "kill", "pickup", "objective", "wave", "deny"];
+/** Bus the default feedback cues mix through; the settings menu shows its volume and mute. */
+export const FEEDBACK_CUE_BUS = "sfx";
+/** Catalog id a cue plays under: `feel.hit`, `feel.kill`, ... A game sound with that id replaces the default. */
+export function feedbackCueSoundId(cue) {
+    return `feel.${cue}`;
+}
+function feelSound(cue, def) {
+    return { id: feedbackCueSoundId(cue), bus: FEEDBACK_CUE_BUS, positional: false, priority: 5, ...def };
+}
+/**
+ * Short procedural reactions - no samples to load, so every game has impact feedback without
+ * authoring audio. Loud enough to read, quiet enough to sit under a weapon's own sound.
+ */
+export const DEFAULT_FEEDBACK_CUE_SOUNDS = {
+    hit: feelSound("hit", {
+        gain: 0.55,
+        maxVoices: 4,
+        synth: {
+            voices: [
+                { kind: "noise", filterType: "bandpass", filterFreq: 1800, duration: 0.05, gain: 0.3 },
+                { kind: "tone", wave: "triangle", freq: 210, slideTo: 150, duration: 0.07, gain: 0.24, attack: 0.002 },
+            ],
+        },
+    }),
+    hurt: feelSound("hurt", {
+        gain: 0.65,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 165, slideTo: 110, duration: 0.16, gain: 0.32, attack: 0.003 },
+                { kind: "noise", filterType: "lowpass", filterFreq: 900, duration: 0.1, gain: 0.14 },
+            ],
+        },
+    }),
+    kill: feelSound("kill", {
+        gain: 0.6,
+        maxVoices: 2,
+        synth: {
+            voices: [
+                { kind: "noise", filterType: "lowpass", filterFreq: 1400, duration: 0.12, gain: 0.24 },
+                { kind: "tone", wave: "sawtooth", freq: 330, slideTo: 220, duration: 0.14, gain: 0.18 },
+                { kind: "tone", wave: "sine", freq: 110, slideTo: 78, duration: 0.2, gain: 0.22, delay: 0.03 },
+            ],
+        },
+    }),
+    pickup: feelSound("pickup", {
+        gain: 0.5,
+        maxVoices: 3,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "sine", freq: 880, duration: 0.09, gain: 0.2, attack: 0.003 },
+                { kind: "tone", wave: "sine", freq: 1320, duration: 0.11, gain: 0.16, delay: 0.05, attack: 0.003 },
+            ],
+        },
+    }),
+    objective: feelSound("objective", {
+        gain: 0.55,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "triangle", freq: 523, duration: 0.14, gain: 0.22 },
+                { kind: "tone", wave: "triangle", freq: 659, duration: 0.14, gain: 0.2, delay: 0.08 },
+                { kind: "tone", wave: "triangle", freq: 784, duration: 0.26, gain: 0.2, delay: 0.16 },
+            ],
+        },
+    }),
+    wave: feelSound("wave", {
+        gain: 0.6,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "sawtooth", freq: 98, duration: 0.5, gain: 0.16, attack: 0.04, sustain: 0.24 },
+                { kind: "tone", wave: "sawtooth", freq: 147, duration: 0.5, gain: 0.12, attack: 0.05, sustain: 0.24 },
+                { kind: "noise", filterType: "lowpass", filterFreq: 600, duration: 0.45, gain: 0.12, decay: 1 },
+            ],
+        },
+    }),
+    deny: feelSound("deny", {
+        gain: 0.5,
+        maxVoices: 1,
+        synth: {
+            voices: [
+                { kind: "tone", wave: "square", freq: 196, slideTo: 170, duration: 0.07, gain: 0.16, attack: 0.002 },
+                { kind: "tone", wave: "square", freq: 155, slideTo: 130, duration: 0.1, gain: 0.16, delay: 0.07, attack: 0.002 },
+            ],
+        },
+    }),
+};
+/**
+ * Merge the default feedback reactions into a game's sound catalog. A game sound already named
+ * `feel.<cue>` wins, then `overrides`, then the default. Adds the `sfx` bus (gain 0.9) when the game
+ * did not declare one, so the impact layer has its own volume and mute row.
+ *
+ * @capability feedback-cue-sounds default procedural hit/hurt/kill/pickup/objective/wave/deny reactions on an "sfx" bus, overridable per game
+ */
+export function withFeedbackCueSounds(sounds, buses, overrides) {
+    if (overrides === false)
+        return { sounds: { ...sounds }, buses: buses === undefined ? undefined : { ...buses } };
+    const merged = {};
+    let usesBus = false;
+    for (const cue of FEEDBACK_CUES) {
+        const id = feedbackCueSoundId(cue);
+        if (sounds?.[id] !== undefined)
+            continue;
+        const override = overrides?.[cue];
+        if (override === false)
+            continue;
+        const def = override ?? DEFAULT_FEEDBACK_CUE_SOUNDS[cue];
+        merged[id] = { ...def, id };
+        if (def.bus === FEEDBACK_CUE_BUS)
+            usesBus = true;
+    }
+    const nextBuses = usesBus && buses?.[FEEDBACK_CUE_BUS] === undefined
+        ? { ...buses, [FEEDBACK_CUE_BUS]: { id: FEEDBACK_CUE_BUS, gain: 0.9 } }
+        : buses;
+    return { sounds: { ...merged, ...sounds }, buses: nextBuses };
+}

package/dist/game/events.d.ts

@@ -2,6 +2,7 @@ import type { EffectResult } from "../combat/effects.js";
 import type { DeathReason } from "../combat/deathReason.js";
 import type { TelegraphShape } from "../combat/telegraph.js";
 import type { CameraShake } from "../combat/hitReaction.js";
+import type { FeedbackCue } from "../audio/feedbackCues.js";
 import type { CombatVfxInstanceEvent } from "./vfxInstance.js";
 export type { DeathReason };
 export interface EntityDiedEvent {
@@ -242,6 +243,15 @@ export interface AudioPlayEvent {
 }
 /** Request that the shell's audio engine resume its (browser-gesture-suspended) context; carries no payload. */
 export type AudioResumeEvent = Record<string, never>;
+/**
+ * A gameplay moment the game announces itself, for the moments no engine event covers (a wave
+ * starting, a scripted beat). The shell reacts with the cue's sound, rumble, camera kick and caption.
+ */
+export interface FeedbackCueEvent {
+    cue: FeedbackCue;
+    /** Caption text that replaces the cue's default label ("WAVE 3"). */
+    caption?: string;
+}
 /** Crossfade the procedural soundtrack to `theme` (null fades out), optionally transposing the incoming theme by `transpose` semitones. */
 export interface AudioMusicEvent {
     theme: string | null;
@@ -325,6 +335,7 @@ export interface GameEventMap {
     "audio.loopStop": AudioLoopStopEvent;
     "entity.animation": EntityAnimationEvent;
     "animation.event": AnimationClipEvent;
+    "feedback.cue": FeedbackCueEvent;
     "command.refused": CommandRefusedEvent;
 }
 export type GameEventHandler<TPayload> = (payload: TPayload) => void;

package/dist/game/gameSave.d.ts

@@ -111,6 +111,12 @@ export interface GameSave {
     peek(slot: string): Promise<GameSaveDocument | null>;
     /** Slots this save has written. */
     slots(): Promise<string[]>;
+    /**
+     * Delete one slot's document and drop it from the slot index, so `slots()` and `peek()` stop
+     * seeing it. Resolves `true` when a document was removed and `false` when the slot held nothing.
+     * Deleting the active slot resets the registered systems to a fresh document.
+     */
+    deleteSlot(slot: string): Promise<boolean>;
     slot(): string;
     status(): SaveStatus;
     /** Monotonic change counter — bumps on any value or status change. */

package/dist/game/gameSave.js

@@ -150,6 +150,12 @@ export function createGameSave(config) {
             return stored.value;
         },
         slots: () => store.slots(),
+        async deleteSlot(slot) {
+            const deleted = await store.deleteSlot(slot);
+            if (deleted && slot === store.slot())
+                apply(store.value());
+            return deleted;
+        },
         slot: () => store.slot(),
         status: () => store.status(),
         revision: () => store.revision(),

package/dist/game/playableGame.d.ts

@@ -2,6 +2,7 @@ import type { AnimGraph } from "../anim/animGraph.js";
 import type { AudioBusDef, SoundDef } from "../audio/audioFalloff.js";
 import type { MusicTheme } from "../audio/music.js";
 import type { UiCueOverrides } from "../audio/uiCues.js";
+import type { FeedbackCueOverrides } from "../audio/feedbackCues.js";
 import type { NoticeFeedConfig } from "./notices.js";
 import type { MaterialAsset, MaterialAssignment, MaterialSurfaceParameters, MaterialTextureRole } from "../material/materialAsset.js";
 import type { EditorCatalogDefinition, EditorDocument } from "../editor/types.js";
@@ -786,6 +787,8 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
         hudCues?: boolean;
         /** Default UI cues (`ui.click`, `ui.deny`, ...) on a "ui" bus. A sound named `ui.<cue>` in `sounds` replaces one; a map entry replaces or (`false`) silences one; `false` silences all. */
         uiCues?: UiCueOverrides;
+        /** Default gameplay reactions (`feel.hit`, `feel.kill`, `feel.pickup`, ...) on an "sfx" bus, played by the shell from the events the engine announces. A sound named `feel.<cue>` in `sounds` replaces one; a map entry replaces or (`false`) silences one; `false` silences all. */
+        feedbackCues?: FeedbackCueOverrides;
     };
     /** Continuous positional emitter keyed by entity kind name: while a matching entity exists, the shell plays and repositions the mapped `audio.sounds` id (looping engine hum, campfire crackle, footstep loop) with listener-distance falloff. */
     entitySounds?: Record<string, string>;

package/dist/game/saveStore.d.ts

@@ -92,6 +92,13 @@ export interface SaveStore<T> {
     save(): Promise<void>;
     /** Delete the active slot and reset `value()` to `initial`. */
     clear(): Promise<void>;
+    /**
+     * Delete any slot: remove its stored payload and drop it from the slot index, so `slots()` and
+     * `peek()` stop seeing it. Resolves `true` when a payload was removed and `false` when the slot
+     * held nothing (an unknown slot is a no-op). Deleting the active slot resets `value()` to
+     * `initial`; other slots leave the live value alone.
+     */
+    deleteSlot(slot: string): Promise<boolean>;
     /**
      * Read a stored slot without touching the live value, active slot or status — what a save-select
      * menu shows. Returns `null` when the slot holds nothing.

package/dist/game/saveStore.js

@@ -231,6 +231,10 @@ export function createSaveStore(config) {
             firstDirtyAt = null;
             setStatus("idle");
             emit();
+            // Only a slot that holds a payload belongs in the index — loading an empty
+            // slot must not resurrect an id a deleteSlot removed.
+            if (raw === null)
+                return current;
             void rememberSlot(currentSlot).catch((error) => {
                 setStatus("error");
                 reportError(error);
@@ -279,6 +283,37 @@ export function createSaveStore(config) {
                 reportError(error);
             }
         },
+        async deleteSlot(slot) {
+            const wasActive = slot === currentSlot;
+            if (wasActive) {
+                clearTimer();
+                dirty = false;
+                firstDirtyAt = null;
+            }
+            const run = saveChain.then(async () => {
+                if (wasActive)
+                    setStatus("saving");
+                try {
+                    const existing = await backend.read(dataKey(slot));
+                    if (existing !== null)
+                        await backend.remove(dataKey(slot));
+                    await forgetSlot(slot);
+                    if (existing !== null && wasActive)
+                        current = initial;
+                    if (wasActive)
+                        setStatus("idle");
+                    emit();
+                    return existing !== null;
+                }
+                catch (error) {
+                    setStatus("error");
+                    reportError(error);
+                    return false;
+                }
+            });
+            saveChain = run.then(() => undefined, () => undefined);
+            return run;
+        },
         async switchSlot(slot) {
             if (dirty)
                 await save();

package/dist/gameplay.d.ts

@@ -88,7 +88,7 @@ export { createWeaponStats } from "./item/weapon.js";
 export { MAX_LOOT_AFFIXES, assertLootCatalog, compareLootItems, createLootRoller, lootLevelScale, lootStatContributions, rollLoot, scoreLootStats, validateLootItem, type LootBaseDef, type LootCatalog, type LootComparison, type LootComparisonOptions, type LootInstalledPart, type LootIssueCode, type LootItem, type LootManufacturerDef, type LootPartDef, type LootRollOptions, type LootRoller, type LootRollerOptions, type LootRollerState, type LootStatDelta, type LootValidationIssue, } from "./loot/lootGen.js";
 export { lootWeaponDefinition, type LootWeaponProjection, type LootWeaponStatMap } from "./loot/lootWeapon.js";
 export { chaseMission, defendMission, escortMission, type ChaseMissionOptions, type ComposedMissionOptions, type DefendMissionOptions, type EscortMissionOptions, } from "./mission/compositions.js";
-export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, type MissionActorFact, type MissionBranch, type MissionDef, type MissionEvent, type MissionEventFilter, type MissionFactCondition, type MissionFailCondition, type MissionFailDef, type MissionIssue, type MissionObjectiveDef, type MissionObjectiveKind, type MissionRewardAppliers, type MissionRewards, type MissionRuntime, type MissionRuntimeConfig, type MissionRuntimeSnapshot, type MissionState, type MissionStats, type MissionStatus, type MissionTickInput, type MissionValidationOptions, type MissionView, type MissionWorldEvent, type MissionWorldEventKind, } from "./mission/mission.js";
+export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_MARKER_TOLERANCE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, type MissionActorFact, type MissionBranch, type MissionDef, type MissionEvent, type MissionEventFilter, type MissionFactCondition, type MissionFailCondition, type MissionFailDef, type MissionIssue, type MissionMarkerPlane, type MissionMarkerProximity, type MissionObjectiveDef, type MissionObjectiveKind, type MissionRewardAppliers, type MissionRewards, type MissionRuntime, type MissionRuntimeConfig, type MissionRuntimeSnapshot, type MissionState, type MissionStats, type MissionStatus, type MissionTickInput, type MissionValidationOptions, type MissionView, type MissionWorldEvent, type MissionWorldEventKind, } from "./mission/mission.js";
 export { MISSION_TRIGGER_ACTIONS, createMissionTriggerBridge, missionMarkers, registerMissionTriggerActions, type MissionTriggerBridge, } from "./mission/triggers.js";
 export { compareGearSets, gearScore, type GearScore, type GearScoreOptions, type GearSlotItem, } from "./progression/gearScore.js";
 export { assertSkillTreeConfig, createSkillTree, type SkillActiveDef, type SkillNodeDef, type SkillRequirement, type SkillResolution, type SkillSpendReason, type SkillSpendResult, type SkillSynergyDef, type SkillTree, type SkillTreeConfig, type SkillTreeState, } from "./progression/skillTree.js";

package/dist/gameplay.js

@@ -88,7 +88,7 @@ export { createWeaponStats } from "./item/weapon.js";
 export { MAX_LOOT_AFFIXES, assertLootCatalog, compareLootItems, createLootRoller, lootLevelScale, lootStatContributions, rollLoot, scoreLootStats, validateLootItem, } from "./loot/lootGen.js";
 export { lootWeaponDefinition } from "./loot/lootWeapon.js";
 export { chaseMission, defendMission, escortMission, } from "./mission/compositions.js";
-export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, } from "./mission/mission.js";
+export { DEFAULT_ESCAPE_MULTIPLE, DEFAULT_MARKER_TOLERANCE, DEFAULT_PURSUE_DISTANCE, DEFAULT_REACH_RADIUS, MISSION_COUNTER_KINDS, applyMissionRewards, createMissionRuntime, isCounterObjective, validateMissionCatalog, } from "./mission/mission.js";
 export { MISSION_TRIGGER_ACTIONS, createMissionTriggerBridge, missionMarkers, registerMissionTriggerActions, } from "./mission/triggers.js";
 export { compareGearSets, gearScore, } from "./progression/gearScore.js";
 export { assertSkillTreeConfig, createSkillTree, } from "./progression/skillTree.js";

package/dist/item/affix.d.ts

@@ -5,6 +5,8 @@ export interface AffixDef {
     op?: AffixOp;
     roll: number | [number, number];
     weight: number;
+    /** Lowest item level whose roll pool includes this affix; omitted means every level. */
+    minLevel?: number;
     namePart?: {
         position: "prefix" | "suffix";
         text: string;

package/dist/loot/drop.d.ts

@@ -0,0 +1,47 @@
+import { type LootCatalog, type LootComparisonOptions, type LootItem, type LootRollOptions, type LootStatDelta } from "./lootGen.js";
+/** A rolled item with a stable instance id, so a stash, ledger and vendor stock can name it. */
+export interface ItemDrop extends LootItem {
+    id: string;
+}
+/** {@link rollDrop} options: the loot roll plus the instance id (defaults to `drop:<seed>`). */
+export interface RollDropOptions extends LootRollOptions {
+    id?: string;
+}
+/**
+ * Roll one item from a seed. Same seed, catalog and options produce the same id, name, affixes,
+ * stats and mass on every run; level gates which bases and affixes are in the pool.
+ *
+ * @capability item-roll roll one deterministic, level-gated item from a seed
+ */
+export declare function rollDrop(catalog: LootCatalog, seed: string | number, options?: RollDropOptions): ItemDrop;
+/** A per-stat delta from the equipped item to the candidate; positive `delta` means the candidate is larger. */
+export interface EquippedStatDelta extends LootStatDelta {
+    /** Whether this stat reads better on the candidate, following `lowerIsBetter`. */
+    better: "candidate" | "equipped" | "equal";
+}
+/** What a HUD renders when a drop lands: per-stat deltas against the worn item and one verdict. */
+export interface EquippedComparison {
+    candidateId: string;
+    equippedId: string | null;
+    deltas: readonly EquippedStatDelta[];
+    scoreCandidate: number;
+    scoreEquipped: number;
+    /** `scoreCandidate - scoreEquipped`. */
+    scoreDelta: number;
+    better: "candidate" | "equipped" | "equal";
+}
+/**
+ * Compare a dropped item against what is equipped, with one delta per stat and a weighted verdict.
+ * The delta is `candidate - equipped`; `better` flips for stats the caller lists in
+ * `lowerIsBetter`, so reload time improving does not read as worse. A missing equipped item
+ * compares against zeros.
+ *
+ * @capability item-comparison show per-stat deltas and a weighted verdict for a drop against equipped gear
+ */
+export declare function compareToEquipped(candidate: ItemDrop, equipped: ItemDrop | null, options?: LootComparisonOptions): EquippedComparison;
+/**
+ * Carried mass of a rolled item. Older saves may predate `mass`; those default to `1`.
+ *
+ * @capability item-weight read a rolled item's mass for a carry check
+ */
+export declare function itemMass(item: Pick<LootItem, "mass">): number;

package/dist/loot/drop.js

@@ -0,0 +1,57 @@
+import { compareLootItems, rollLoot, } from "./lootGen.js";
+import { seededRng } from "../random/rng.js";
+/**
+ * Roll one item from a seed. Same seed, catalog and options produce the same id, name, affixes,
+ * stats and mass on every run; level gates which bases and affixes are in the pool.
+ *
+ * @capability item-roll roll one deterministic, level-gated item from a seed
+ */
+export function rollDrop(catalog, seed, options = {}) {
+    const item = rollLoot(catalog, seededRng(seed), options);
+    return { ...item, id: options.id ?? `drop:${String(seed)}` };
+}
+const NO_ITEM = {
+    baseId: "none",
+    manufacturer: "none",
+    rarity: "none",
+    level: 0,
+    name: "",
+    parts: [],
+    affixes: [],
+    stats: {},
+    mass: 0,
+};
+/**
+ * Compare a dropped item against what is equipped, with one delta per stat and a weighted verdict.
+ * The delta is `candidate - equipped`; `better` flips for stats the caller lists in
+ * `lowerIsBetter`, so reload time improving does not read as worse. A missing equipped item
+ * compares against zeros.
+ *
+ * @capability item-comparison show per-stat deltas and a weighted verdict for a drop against equipped gear
+ */
+export function compareToEquipped(candidate, equipped, options = {}) {
+    const base = equipped ?? NO_ITEM;
+    const comparison = compareLootItems(base, candidate, options);
+    const lower = new Set(options.lowerIsBetter ?? []);
+    const deltas = comparison.deltas.map((entry) => ({
+        ...entry,
+        better: entry.delta === 0 ? "equal" : (entry.delta > 0) !== lower.has(entry.stat) ? "candidate" : "equipped",
+    }));
+    return {
+        candidateId: candidate.id,
+        equippedId: equipped?.id ?? null,
+        deltas,
+        scoreCandidate: comparison.scoreB,
+        scoreEquipped: comparison.scoreA,
+        scoreDelta: comparison.scoreDelta,
+        better: comparison.better === "b" ? "candidate" : comparison.better === "a" ? "equipped" : "equal",
+    };
+}
+/**
+ * Carried mass of a rolled item. Older saves may predate `mass`; those default to `1`.
+ *
+ * @capability item-weight read a rolled item's mass for a carry check
+ */
+export function itemMass(item) {
+    return item.mass !== undefined && Number.isFinite(item.mass) && item.mass > 0 ? item.mass : 1;
+}