@jgengine/core 0.28.0 → 0.30.0

package/dist/ai/director/sound.js

@@ -0,0 +1,113 @@
+const DEFAULTS = {
+    maxInvestigators: 3,
+    giveUpConfidence: 0.15,
+    maxSeconds: 20,
+    maxNoises: 16,
+};
+function flatDistance(a, b) {
+    return Math.hypot(a[0] - b[0], a[2] - b[2]);
+}
+/**
+ * Make enemies investigate a noise, reusing the hearing owner.
+ *
+ * The noise goes into `PerceptionService.pushStimulus` as a `sound` stimulus, so the same range,
+ * loudness and linear memory decay that every other hearing consumer gets apply here; this layer
+ * adds only the two things a squad needs: a *bound* on how many enemies chase one noise, and a
+ * *give-up* rule, both read back from that memory instead of a second copy of it. A sighting of the
+ * source during the hunt raises the same memory's confidence, so an investigation escalates into a
+ * pursuit without any bookkeeping here.
+ *
+ * @capability sound-hunting send a bounded set of nearby enemies to investigate a noise with decaying memory
+ */
+export function createSoundHunt(config) {
+    const maxInvestigators = Math.max(0, Math.floor(config.maxInvestigators ?? DEFAULTS.maxInvestigators));
+    const giveUp = Math.max(0, config.giveUpConfidence ?? DEFAULTS.giveUpConfidence);
+    const maxSeconds = Math.max(0, config.maxSeconds ?? DEFAULTS.maxSeconds);
+    const maxNoises = Math.max(1, Math.floor(config.maxNoises ?? DEFAULTS.maxNoises));
+    let entries = [];
+    return {
+        noise(event) {
+            if (!Number.isFinite(event.at))
+                throw new Error("noise.at must be finite.");
+            const loudness = Math.max(0, event.loudness ?? 1);
+            const audible = config.hearingRange * loudness;
+            const ranked = [];
+            if (audible > 0) {
+                for (const hunter of config.hunters(event.position, audible)) {
+                    if (hunter.id === event.sourceId)
+                        continue;
+                    if (flatDistance(hunter.position, event.position) >= audible)
+                        continue;
+                    ranked.push(hunter);
+                }
+            }
+            ranked.sort((a, b) => {
+                const distance = flatDistance(a.position, event.position) - flatDistance(b.position, event.position);
+                if (Math.abs(distance) > 0.0001)
+                    return distance;
+                return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+            });
+            const admitted = ranked.slice(0, maxInvestigators).map((hunter) => hunter.id);
+            config.perception.pushStimulus({
+                kind: "sound",
+                sourceId: event.sourceId,
+                position: [...event.position],
+                loudness,
+                at: event.at,
+            });
+            const admittedSet = new Set(admitted);
+            entries = entries
+                .filter((entry) => entry.noise.sourceId !== event.sourceId)
+                .map((entry) => ({ noise: entry.noise, hunters: entry.hunters.filter((id) => !admittedSet.has(id)) }))
+                .filter((entry) => entry.hunters.length > 0);
+            entries.push({
+                noise: { ...event, position: [...event.position], loudness },
+                hunters: admitted,
+            });
+            while (entries.length > maxNoises)
+                entries.shift();
+            return admitted;
+        },
+        investigations(nowMs) {
+            const results = [];
+            const kept = [];
+            for (const entry of entries) {
+                const ageSeconds = Math.max(0, nowMs - entry.noise.at) / 1000;
+                if (ageSeconds > maxSeconds)
+                    continue;
+                const alive = [];
+                for (const hunterId of entry.hunters) {
+                    const memory = config.perception.memoryOf(hunterId, entry.noise.sourceId);
+                    if (memory === null || memory.confidence <= giveUp)
+                        continue;
+                    alive.push(hunterId);
+                    results.push({
+                        hunterId,
+                        sourceId: entry.noise.sourceId,
+                        position: [...memory.lastKnownPos],
+                        confidence: memory.confidence,
+                        ageSeconds,
+                    });
+                }
+                if (alive.length > 0)
+                    kept.push({ noise: entry.noise, hunters: alive });
+            }
+            entries = kept;
+            return results;
+        },
+        snapshot() {
+            return {
+                entries: entries.map((entry) => ({
+                    noise: { ...entry.noise, position: [...entry.noise.position] },
+                    hunters: [...entry.hunters],
+                })),
+            };
+        },
+        restore(snapshot) {
+            entries = snapshot.entries.map((entry) => ({
+                noise: { ...entry.noise, position: [...entry.noise.position] },
+                hunters: [...entry.hunters],
+            }));
+        },
+    };
+}

package/dist/game/playableGame.d.ts

@@ -729,7 +729,7 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
     platforms?: readonly HudPlatform[];
     /** HUD design resolution + scale clamps (default 1600×900, scale 0.4–1). `mobile` overrides tune the phone fit separately — the same resolution system drives desktop UI-scale and phone shrink. */
     hudFit?: HudViewportConfig;
-    /** Opt in to world-space health bars floating over non-local entities that carry the stat. `roles` restricts bars to entities whose catalog entry declares one of the given roles; `maxDistance` hides bars beyond this many world units from the render camera (default 60). */
+    /** Opt in to world-space health bars floating over non-local entities that carry the stat. `roles` restricts bars to entities whose catalog entry declares one of the given roles; `maxDistance` hides bars beyond this many world units from the render camera, and unset derives the range from the camera and the target height (an overhead camera reaches the units it looks at). */
     worldHealthBars?: boolean | {
         statId?: string;
         roles?: readonly CatalogEntityRole[];
@@ -745,7 +745,7 @@ export interface PlayableGame<TUi = unknown, TWorldOverlay = unknown, TRenderEnt
      * Opt in to billboarded nameplates (name + optional HP bar) floating over non-local entities — the
      * MMO "who's this and how hurt are they" readout. `roles` restricts to entities whose catalog entry
      * declares one of the given roles (default: all); `maxDistance` hides nameplates beyond this many
-     * world units from the render camera (default 40). Headless: skin every part via `className`/`data-*` hooks
+     * world units from the render camera, and unset derives the range the same way the bars do. Headless: skin every part via `className`/`data-*` hooks
      * on `WorldNameplates` (`@jgengine/shell/world/WorldHud`) — this flag only turns the readout on and
      * scopes which entities it covers. Set `showHealth: false` for a name-only plate when a game already
      * draws the HP bar itself (its own HUD, or `worldHealthBars`) — otherwise the nameplate's built-in bar

package/dist/meta/changelog.d.ts

@@ -1,5 +1,5 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export declare const VERSION = "0.28.0";
+export declare const VERSION = "0.30.0";
 /** One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md). */
 export interface ChangelogEntry {
     migrate: readonly string[];

package/dist/meta/changelog.js

@@ -1,7 +1,36 @@
 /** Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating. */
-export const VERSION = "0.28.0";
+export const VERSION = "0.30.0";
 /** Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`). */
 export const CHANGELOG = {
+    "0.30.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.30.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.27.0`; `@jgengine/github` is `0.17.0`.",
+        ],
+        added: [
+            "`ColorblindFrame` (`@jgengine/react/accessibility`) wraps the 3D canvas and applies the player's colour-vision mode to that box alone, so HUD, menu and caption text keep their own contrast. `colorblindFrameFilter` (`@jgengine/core/ui/accessibility`) resolves a mode to the CSS filter, and `useColorblindMode` reads the mode from the settings store the settings rows write; the 3D shell does both for the mounted game.",
+            "`SettingsSection` (`@jgengine/react/settingsBlocks`) is one `useMenuNav` menu: a d-pad or left stick moves between rows and left/right steps the focused value — slider by its step, toggle flipped, select to the next option, confirm arms a keybind — through the same `onAdjust` path the arrow keys use. `onAdjust` (`@jgengine/react/menuNav`) is the option that makes left/right adjust instead of move.",
+            "`createStanding` (`@jgengine/core/progression/standing`) holds per-faction or per-district standing over authored tracks and moves it from named outcomes, so an outcome that resolves to nothing throws at the call instead of silently moving nothing.",
+            "`createGateSet` (`@jgengine/core/progression/gates`) evaluates authored milestones against standing and money, and refuses to load when a gate's unlock id resolves to nothing.",
+            "`createCareerBank` (`@jgengine/core/progression/careerBank`) keeps persistent career money apart from a run's haul, so a failed run loses the haul and keeps the bank.",
+            "`createUpgradeTree` (`@jgengine/core/progression/upgrades`) prices each rank from the shared curve primitive and gates purchases on prerequisites and standing.",
+        ],
+        changed: [
+            "`AccessibilityProvider` (`@jgengine/react/accessibility`) sets its data attributes and text-scale var without filtering its own subtree. A colour matrix over the HUD and menu root recoloured the text the rest of the UI assumes, so wrap the game canvas in `ColorblindFrame` instead; a custom root can still offset it with its own `ColorblindFilters` and `filter: url(#jg-cb-<mode>)`.",
+            "World health bars and nameplates derive their range from the render camera and the target height when a game sets no `maxDistance`: an overhead camera reaches the units it looks down at, and a bar is kept while the target it annotates still covers 18 px, instead of hiding every target past a fixed 60 units.",
+            "A configured `worldHealthBars.maxDistance` or `nameplates.maxDistance` that hides every target in view now warns once with the nearest measured distance and the prop to raise, instead of rendering nothing.",
+        ],
+        removed: [],
+    },
+    "0.29.0": {
+        migrate: [
+            "Bump lockstep SDK packages to `^0.29.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.26.0`; `@jgengine/github` is `0.16.0`.",
+        ],
+        added: [],
+        changed: [
+            "`MissionView.remaining` (`@jgengine/core/gameplay`) now counts down from a `survive` objective's own `duration`, not only from a `timeout`. A defend or hold objective reports the seconds it still has to run, which is the one number its HUD needs; a completed run still reports null.",
+        ],
+        removed: [],
+    },
     "0.28.0": {
         migrate: [
             "Bump lockstep SDK packages to `^0.28.0`: `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.25.0`; `@jgengine/github` is `0.15.0`.",

package/dist/mission/mission.d.ts

@@ -281,7 +281,7 @@ export interface MissionView {
     objectiveId: string | null;
     label: string;
     objectiveElapsed: number;
-    /** Seconds left on the current objective's timer, or null when it has none. */
+    /** Seconds left on the current objective's timer (a `timeout` or a `survive` duration), or null when it has none. */
     remaining: number | null;
     /** Counter fraction 0..1 for the current objective, or 0 when it is not a counter. */
     progress: number;

package/dist/mission/mission.js

@@ -561,7 +561,10 @@ export function createMissionRuntime(config) {
             readout.objectiveId = state.objective;
             readout.label = objective === null ? "" : objectiveLabel(objective);
             readout.objectiveElapsed = state.objectiveElapsed;
-            readout.remaining = objective?.timeout === undefined ? null : Math.max(0, objective.timeout - state.objectiveElapsed);
+            const timer = objective === null
+                ? undefined
+                : objective.timeout ?? (objective.kind === "survive" ? objective.duration : undefined);
+            readout.remaining = timer === undefined ? null : Math.max(0, timer - state.objectiveElapsed);
             const counted = objective === null || !isCounterObjective(objective.kind)
                 ? 0
                 : (state.progress[counterKey(objective)] ?? 0);

package/dist/progression/careerBank.d.ts

@@ -0,0 +1,63 @@
+import { type CurrencyDefinition } from "../economy/currency.js";
+/**
+ * Everything a career bank stores, as plain JSON. `banked` is the persistent balance; `haul` is
+ * the run in progress and is the part a failed run loses. `deposited`, `lost`, `bestHaul` and
+ * `runs` are lifetime counters a results screen reads.
+ */
+export interface CareerBankState {
+    banked: number;
+    haul: number;
+    deposited: number;
+    lost: number;
+    bestHaul: number;
+    runs: number;
+}
+/** Configuration for {@link createCareerBank}. */
+export interface CareerBankConfig {
+    currency: CurrencyDefinition;
+    /** Persistent money before any run (default `0`). */
+    start?: number;
+    /** Most a single run's haul can carry; omitted means no cap. */
+    haulCap?: number;
+    /** Rehydrate from a prior {@link CareerBank.snapshot}. */
+    state?: CareerBankState;
+}
+/** Persistent career money plus the run in progress, which a failed run loses. */
+export interface CareerBank {
+    currency(): CurrencyDefinition;
+    /** Money kept between runs. */
+    banked(): number;
+    /** Money earned this run and not yet banked or lost. */
+    haul(): number;
+    /** Add to the run's haul (capped by `haulCap`); negative or non-finite is ignored. Returns the haul. */
+    earn(amount: number): number;
+    /** Bank the haul: it becomes persistent and the run's haul resets. */
+    cashOut(): {
+        deposited: number;
+        banked: number;
+    };
+    /** The run failed: the haul is gone, persistent money is untouched. */
+    loseHaul(): {
+        lost: number;
+        banked: number;
+    };
+    /** Pay from persistent money; `false` when it cannot cover the amount. */
+    spend(amount: number): boolean;
+    afford(amount: number): boolean;
+    counters(): {
+        deposited: number;
+        lost: number;
+        bestHaul: number;
+        runs: number;
+    };
+    snapshot(): CareerBankState;
+    restore(next: CareerBankState): void;
+}
+/**
+ * Money that means something between runs: a persistent balance plus a run's haul that is banked on
+ * a cash-out and lost on a failure. Amounts are snapped to the currency's minor units, so a save
+ * round-trip and a display never drift. Pair it with `economy/upgrades` for a career upgrade tree.
+ *
+ * @capability career-bank persistent career money with a run haul that can be banked or lost
+ */
+export declare function createCareerBank(config: CareerBankConfig): CareerBank;

package/dist/progression/careerBank.js

@@ -0,0 +1,83 @@
+import { fromMinorUnits, toMinorUnits } from "../economy/currency.js";
+import { charge, createEmptyWallet, grant } from "../economy/wallet.js";
+function sanitizeAmount(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * Money that means something between runs: a persistent balance plus a run's haul that is banked on
+ * a cash-out and lost on a failure. Amounts are snapped to the currency's minor units, so a save
+ * round-trip and a display never drift. Pair it with `economy/upgrades` for a career upgrade tree.
+ *
+ * @capability career-bank persistent career money with a run haul that can be banked or lost
+ */
+export function createCareerBank(config) {
+    const currency = config.currency;
+    const snap = (amount) => fromMinorUnits(currency, toMinorUnits(currency, sanitizeAmount(amount)));
+    const haulCap = config.haulCap === undefined ? Number.POSITIVE_INFINITY : snap(config.haulCap);
+    const walletOf = (bankedAmount) => bankedAmount > 0 ? grant(createEmptyWallet(), currency, bankedAmount) : createEmptyWallet();
+    let wallet = walletOf(snap(config.start ?? 0));
+    let haul = 0;
+    let deposited = 0;
+    let lost = 0;
+    let bestHaul = 0;
+    let runs = 0;
+    const banked = () => wallet.balances[currency.id] ?? 0;
+    if (config.state !== undefined) {
+        wallet = walletOf(snap(config.state.banked));
+        haul = snap(config.state.haul);
+        deposited = snap(config.state.deposited);
+        lost = snap(config.state.lost);
+        bestHaul = snap(config.state.bestHaul);
+        runs = Number.isInteger(config.state.runs) && config.state.runs > 0 ? config.state.runs : 0;
+    }
+    return {
+        currency: () => currency,
+        banked,
+        haul: () => haul,
+        earn(amount) {
+            const added = snap(amount);
+            if (added > 0)
+                haul = snap(Math.min(haul + added, haulCap));
+            return haul;
+        },
+        cashOut() {
+            const held = haul;
+            if (held > 0) {
+                wallet = grant(wallet, currency, held);
+                deposited = snap(deposited + held);
+                bestHaul = Math.max(bestHaul, held);
+            }
+            haul = 0;
+            runs += 1;
+            return { deposited: held, banked: banked() };
+        },
+        loseHaul() {
+            const gone = haul;
+            haul = 0;
+            lost = snap(lost + gone);
+            runs += 1;
+            return { lost: gone, banked: banked() };
+        },
+        spend(amount) {
+            const cost = snap(amount);
+            if (cost <= 0)
+                return false;
+            const paid = charge(wallet, currency, cost);
+            if (paid.status !== "ok")
+                return false;
+            wallet = paid.state;
+            return true;
+        },
+        afford: (amount) => banked() >= snap(amount),
+        counters: () => ({ deposited, lost, bestHaul, runs }),
+        snapshot: () => ({ banked: banked(), haul, deposited, lost, bestHaul, runs }),
+        restore(next) {
+            wallet = walletOf(snap(next.banked));
+            haul = snap(next.haul);
+            deposited = snap(next.deposited);
+            lost = snap(next.lost);
+            bestHaul = snap(next.bestHaul);
+            runs = Number.isInteger(next.runs) && next.runs > 0 ? next.runs : 0;
+        },
+    };
+}

package/dist/progression/gates.d.ts

@@ -0,0 +1,66 @@
+import type { UnlockCatalog } from "../game/unlocks.js";
+import type { Standing, StandingRequirement } from "./standing.js";
+/** What a gate is evaluated against: standing by track and money by currency. */
+export interface GateFacts {
+    standing(trackId: string): number;
+    balance(currency: string): number;
+}
+/** Every condition a gate can require; all named conditions must hold. */
+export interface GateRequirement {
+    standing?: StandingRequirement;
+    /** Smallest balance of `currency` that passes. */
+    balance?: {
+        currency: string;
+        min: number;
+    };
+}
+/**
+ * A milestone: content that opens exactly when its requirements hold and names the unlock it
+ * grants. `unlock` must resolve in the catalog the set is built with, or the set refuses to load.
+ */
+export interface GateDef {
+    id: string;
+    unlock: string;
+    label?: string;
+    category?: string;
+    requires?: GateRequirement;
+}
+/** Which named condition a closed gate still needs. */
+export type GateMiss = "standing" | "balance";
+/** One gate against live facts. */
+export interface GateStatus {
+    gate: GateDef;
+    open: boolean;
+    missing: readonly GateMiss[];
+}
+/** Evaluated gate content: the table, its status against facts, and the grants a caller applies. */
+export interface GateSet {
+    gates(): readonly GateDef[];
+    gate(gateId: string): GateDef | null;
+    status(facts: GateFacts): readonly GateStatus[];
+    isOpen(gateId: string, facts: GateFacts): boolean;
+    open(facts: GateFacts): readonly GateDef[];
+    /** Gates met now whose `unlock` is not in `granted` — the unlocks to grant this pass. */
+    claim(facts: GateFacts, granted: readonly string[]): readonly GateDef[];
+}
+/** Content and the resolvers a {@link GateSet} is built from. */
+export interface GateSetConfig {
+    gates: readonly GateDef[];
+    /** The ids an unlock may resolve to; normally the game's content catalog. */
+    catalog: Pick<UnlockCatalog, "has">;
+    /** The standing a requirement reads; also validates every requirement's track at load. */
+    standing?: Pick<Standing, "hasTrack">;
+}
+/** Read a {@link Standing} and a balance record as {@link GateFacts}. */
+export declare function gateFacts(standing: Pick<Standing, "standing">, actorId: string, balances?: Readonly<Record<string, number>>): GateFacts;
+/** Check an authored gate table against the content it grants; throws `RangeError` naming the gate. */
+export declare function assertGates(config: GateSetConfig): void;
+/**
+ * Authored unlock gates: each one names the unlock it grants and the standing or balance it reads.
+ * Evaluated against caller-supplied facts, so one table serves a single-player save, a server actor
+ * or a probe. Load refuses a gate whose unlock id resolves to nothing (the D3.8 class), so a dead
+ * milestone fails at startup instead of in play. A gate with no requirements is open from the start.
+ *
+ * @capability unlock-gates milestones gated by standing or money, validated against the content they grant
+ */
+export declare function createGateSet(config: GateSetConfig): GateSet;

package/dist/progression/gates.js

@@ -0,0 +1,88 @@
+/** Read a {@link Standing} and a balance record as {@link GateFacts}. */
+export function gateFacts(standing, actorId, balances = {}) {
+    return {
+        standing: (trackId) => standing.standing(actorId, trackId),
+        balance: (currency) => balances[currency] ?? 0,
+    };
+}
+function check(condition, message) {
+    if (!condition)
+        throw new RangeError(message);
+}
+/** Check an authored gate table against the content it grants; throws `RangeError` naming the gate. */
+export function assertGates(config) {
+    const ids = new Set();
+    for (const gate of config.gates) {
+        const id = gate.id.trim();
+        check(id !== "", "Gate id must not be empty");
+        check(!ids.has(id), `Gate "${id}" is declared twice`);
+        ids.add(id);
+        check(gate.unlock.trim() !== "", `Gate "${id}" names an empty unlock`);
+        check(config.catalog.has(gate.unlock), `Gate "${id}" unlocks unknown id "${gate.unlock}" - the reward resolves to nothing`);
+        const standing = gate.requires?.standing;
+        if (standing !== undefined) {
+            check(standing.trackId.trim() !== "", `Gate "${id}" names an empty standing track`);
+            check(config.standing === undefined || config.standing.hasTrack(standing.trackId), `Gate "${id}" reads unknown standing track "${standing.trackId}"`);
+            if (standing.min !== undefined)
+                check(Number.isFinite(standing.min), `Gate "${id}" standing min must be finite`);
+            if (standing.max !== undefined)
+                check(Number.isFinite(standing.max), `Gate "${id}" standing max must be finite`);
+            check(standing.min === undefined || standing.max === undefined || standing.min <= standing.max, `Gate "${id}" needs standing min <= max`);
+        }
+        const balance = gate.requires?.balance;
+        if (balance !== undefined) {
+            check(balance.currency.trim() !== "", `Gate "${id}" names an empty currency`);
+            check(Number.isFinite(balance.min) && balance.min >= 0, `Gate "${id}" balance min must be finite and >= 0`);
+        }
+    }
+}
+function missingFor(gate, facts) {
+    const missing = [];
+    const standing = gate.requires?.standing;
+    if (standing !== undefined) {
+        const value = facts.standing(standing.trackId);
+        if ((standing.min !== undefined && value < standing.min) || (standing.max !== undefined && value > standing.max)) {
+            missing.push("standing");
+        }
+    }
+    const balance = gate.requires?.balance;
+    if (balance !== undefined && facts.balance(balance.currency) < balance.min)
+        missing.push("balance");
+    return missing;
+}
+/**
+ * Authored unlock gates: each one names the unlock it grants and the standing or balance it reads.
+ * Evaluated against caller-supplied facts, so one table serves a single-player save, a server actor
+ * or a probe. Load refuses a gate whose unlock id resolves to nothing (the D3.8 class), so a dead
+ * milestone fails at startup instead of in play. A gate with no requirements is open from the start.
+ *
+ * @capability unlock-gates milestones gated by standing or money, validated against the content they grant
+ */
+export function createGateSet(config) {
+    assertGates(config);
+    const definitions = config.gates.slice();
+    function statusOf(gate, facts) {
+        const missing = missingFor(gate, facts);
+        return { gate, open: missing.length === 0, missing };
+    }
+    return {
+        gates: () => definitions.slice(),
+        gate: (gateId) => definitions.find((gate) => gate.id === gateId) ?? null,
+        status: (facts) => definitions.map((gate) => statusOf(gate, facts)),
+        isOpen(gateId, facts) {
+            const gate = definitions.find((entry) => entry.id === gateId);
+            return gate === undefined ? false : missingFor(gate, facts).length === 0;
+        },
+        open: (facts) => definitions.filter((gate) => missingFor(gate, facts).length === 0),
+        claim(facts, granted) {
+            const out = [];
+            for (const gate of definitions) {
+                if (granted.includes(gate.unlock))
+                    continue;
+                if (missingFor(gate, facts).length === 0)
+                    out.push(gate);
+            }
+            return out;
+        },
+    };
+}

package/dist/progression/standing.d.ts

@@ -0,0 +1,77 @@
+import { type ReputationTier } from "../faction/reputation.js";
+/** One standing track: a faction, a district, a licence board — whatever an authored outcome moves. */
+export interface StandingTrackDef {
+    id: string;
+    label?: string;
+    /** Tiers this track crosses, ascending by `min`; defaults to the shared reputation ladder. */
+    tiers?: readonly ReputationTier[];
+    /** Standing every actor starts at (default `0`). */
+    initial?: number;
+    /** Floor and ceiling; omitted means unbounded. */
+    min?: number;
+    max?: number;
+}
+/** One outcome a game can report, and the standing it moves on each track. */
+export interface StandingOutcomeDef {
+    id: string;
+    label?: string;
+    /** Track id → signed standing. A negative number is the fall. */
+    impacts: Readonly<Record<string, number>>;
+}
+/** Authored standing content: the tracks an actor stands with, and the outcomes that move them. */
+export interface StandingConfig {
+    tracks: readonly StandingTrackDef[];
+    outcomes?: readonly StandingOutcomeDef[];
+}
+/** One track's movement, with the tier on both sides so a caller can announce a crossing. */
+export interface StandingChange {
+    trackId: string;
+    before: number;
+    after: number;
+    delta: number;
+    previousTier: string;
+    tier: string;
+}
+/** A threshold on one track, as an unlock or an upgrade reads it. */
+export interface StandingRequirement {
+    trackId: string;
+    /** Smallest standing that passes; omitted means no floor. */
+    min?: number;
+    /** Largest standing that passes; omitted means no ceiling. */
+    max?: number;
+}
+/** Plain JSON state of a {@link Standing}; tracks left at their authored `initial` are absent. */
+export interface StandingState {
+    records: Record<string, Record<string, number>>;
+}
+/**
+ * Live standing over authored tracks, moved by named outcomes or direct adjustments, with the
+ * tier on each track and a serializable snapshot.
+ */
+export interface Standing {
+    tracks(): readonly StandingTrackDef[];
+    hasTrack(trackId: string): boolean;
+    hasOutcome(outcomeId: string): boolean;
+    standing(actorId: string, trackId: string): number;
+    tier(actorId: string, trackId: string): ReputationTier;
+    /** Every track's standing for one actor, authored tracks included at their initial value. */
+    standings(actorId: string): Record<string, number>;
+    /** Apply an authored outcome; returns each track it moved. Throws on an unknown outcome id. */
+    apply(actorId: string, outcomeId: string): readonly StandingChange[];
+    /** Move one track directly; returns the change. Throws on an unknown track id. */
+    adjust(actorId: string, trackId: string, delta: number): StandingChange;
+    meets(actorId: string, requirement: StandingRequirement): boolean;
+    snapshot(): StandingState;
+    restore(next: StandingState): void;
+}
+/** Check authored standing content before use; throws `RangeError` naming the offending field. */
+export declare function assertStandingConfig(config: StandingConfig): void;
+/**
+ * Per-faction or per-district standing that rises and falls from named outcomes, over authored
+ * tracks. Numbers live in the shared reputation ledger (`faction/reputation`); this adds the
+ * authored outcome table, tier-per-track and the one snapshot a save stores. An outcome id or
+ * track id that resolves to nothing throws at the call, so authored content fails loudly.
+ *
+ * @capability standing per-track standing moved by authored outcomes, with tiers and one snapshot
+ */
+export declare function createStanding(config: StandingConfig): Standing;