@jgengine/core 0.10.0 → 0.11.0

package/dist/game/quest.js

@@ -1,6 +1,11 @@
 function clamp(value, min, max) {
     return Math.min(max, Math.max(min, value));
 }
+/**
+ * Track accepted quests and their per-objective progress, granting rewards on completion.
+ *
+ * @capability quest-log track accepted quests and their per-objective progress
+ */
 export function createQuestJournal(deps) {
     const catalog = new Map();
     const users = new Map();
@@ -230,6 +235,30 @@ export function createQuestJournal(deps) {
             }
             users.set(userId, quests);
         },
+        snapshotAll() {
+            const out = {};
+            for (const [userId, quests] of users) {
+                out[userId] = Array.from(quests, ([questId, state]) => ({
+                    questId,
+                    status: state.status,
+                    progress: Object.fromEntries(state.progress),
+                }));
+            }
+            return out;
+        },
+        hydrateAll(data) {
+            users.clear();
+            for (const [userId, entries] of Object.entries(data)) {
+                const quests = new Map();
+                for (const entry of entries) {
+                    quests.set(entry.questId, {
+                        status: entry.status,
+                        progress: new Map(Object.entries(entry.progress)),
+                    });
+                }
+                users.set(userId, quests);
+            }
+        },
     };
 }
 export function applyQuestRewards(rewards, appliers) {

package/dist/game/race.d.ts

@@ -135,4 +135,145 @@ export declare class RaceState {
     private compare;
     update(now: number, positions: Record<string, readonly [number, number, number]> | Map<string, readonly [number, number, number]>): readonly RaceEvent[];
 }
+/**
+ * A checkpoint race state machine — laps, forks, live standings, splits, and pluggable win conditions.
+ *
+ * @capability race-track a checkpoint race with laps, standings, splits, and win conditions
+ */
 export declare function createRaceState(config: RaceStateConfig): RaceState;
+/** Wall-clock lap timing: the current/last/best/total split-book every racing HUD reads. */
+export interface LapTimerSnapshot {
+    /** Seconds elapsed in the lap now underway. */
+    currentLap: number;
+    /** Duration of the lap just completed, or `null` before the first lap closes. */
+    lastLap: number | null;
+    /** Fastest completed lap so far, or `null` before the first lap closes. */
+    bestLap: number | null;
+    /** Total time across every lap, including the current one. */
+    total: number;
+    /** Number of laps completed. */
+    lapCount: number;
+    /** Completed lap durations in order — the split book for a results screen. */
+    splits: readonly number[];
+}
+/**
+ * Wall-clock lap timer complementing {@link RaceState}: feed it `tick(dt)` each frame and call
+ * `completeLap()` when the race emits a player `lap.completed` event. It accumulates the current lap,
+ * carries best/last, banks splits, and `penalize()` folds a time penalty into the running lap — the
+ * timing bookkeeping every racer reimplemented on top of the position-only race state.
+ */
+export interface LapTimer {
+    /** Advance the current lap and total by `dt` seconds. */
+    tick(dt: number): void;
+    /** Close the current lap: bank its split, update last/best, reset the current lap to 0, and return its time. */
+    completeLap(): number;
+    /** Add a time penalty (seconds) to the lap currently underway. */
+    penalize(seconds: number): void;
+    /** Clear all timing back to the start line. */
+    reset(): void;
+    /** Immutable view of the current timing state. */
+    snapshot(): LapTimerSnapshot;
+}
+/**
+ * Create a {@link LapTimer} starting at lap 0 with no splits, best, or last time recorded.
+ *
+ * @capability lap-timer wall-clock current/last/best lap timing with splits
+ */
+export declare function createLapTimer(): LapTimer;
+/**
+ * The lifecycle every race runs through before, during, and after the clock: `idle` on the grid,
+ * `countdown` on the lights, `racing` once they go green, `finished` at the flag. A pure value driven
+ * by the transition functions below — it carries no track, racer, or lap data, so it composes with
+ * {@link RaceState} (position/laps) and {@link LapTimer} (wall-clock) rather than duplicating them.
+ */
+export type RacePhase = "idle" | "countdown" | "racing" | "finished";
+/** Immutable lifecycle snapshot: the current {@link RacePhase} plus the two clocks it owns. */
+export interface RaceSessionState {
+    /** Where the session sits in the start→countdown→race→finish lifecycle. */
+    readonly phase: RacePhase;
+    /** Seconds left on the countdown, or 0 outside the `countdown` phase. */
+    readonly countdown: number;
+    /** Seconds of green-flag racing accumulated so far. */
+    readonly elapsed: number;
+}
+/** Options for {@link startRaceCountdown}. */
+export interface RaceCountdownOptions {
+    /** Countdown length in seconds before the race goes green (default 3). A value ≤ 0 starts racing immediately. */
+    readonly seconds?: number;
+}
+/**
+ * The pre-race session on the grid: `idle`, both clocks at zero. Call {@link startRaceCountdown} to
+ * light the lights, or hold here until the field is ready.
+ *
+ * @capability race-session pure idle→countdown→racing→finished clock every racer wraps around its state
+ */
+export declare function idleRaceSession(): RaceSessionState;
+/**
+ * Drop the lights: return a fresh `countdown` session of `seconds` (default 3). A non-positive length
+ * skips straight to `racing` for a standing start with no countdown.
+ */
+export declare function startRaceCountdown(options?: RaceCountdownOptions): RaceSessionState;
+/**
+ * Advance the session by `dt` seconds: bleed the countdown down and flip to `racing` when it reaches
+ * zero, or accumulate `elapsed` while `racing`. `idle` and `finished` are inert. Overshoot past the
+ * countdown is dropped rather than banked into `elapsed`, so the race clock always starts from zero.
+ */
+export declare function tickRaceSession(session: RaceSessionState, dt: number): RaceSessionState;
+/** Cross the flag: move a `racing` session to `finished`, freezing its `elapsed`. A no-op in any other phase. */
+export declare function finishRaceSession(session: RaceSessionState): RaceSessionState;
+/** Whether a racer won or lost, derived from where they placed against the winning-places cutoff. */
+export type RaceOutcome = "win" | "lose";
+/** A racer's finishing position (`place`, 1-based) in a finish order, and the {@link RaceOutcome} it earns. */
+export interface RacePlacement {
+    readonly racerId: string;
+    /** 1-based finishing position: `1` is the winner. */
+    readonly place: number;
+    readonly outcome: RaceOutcome;
+}
+/** Options for {@link racePlacements} / {@link placementOf} / {@link raceOutcomeOf}. */
+export interface PlacementOptions {
+    /** How many top places count as a win (default 1). A podium finish would pass `3`. */
+    readonly winningPlaces?: number;
+}
+/**
+ * Turn a finish-order ranking (index 0 = winner, e.g. the `ranking` of a `race.finished` event) into
+ * per-racer {@link RacePlacement}s — the `1st/2nd/3rd` + win/lose every results screen shows.
+ *
+ * @capability race-placements finish order into per-racer place + win/lose for a results screen
+ */
+export declare function racePlacements(finishOrder: readonly string[], options?: PlacementOptions): readonly RacePlacement[];
+/**
+ * One racer's {@link RacePlacement} within a finish order, or `null` if they never crossed the line.
+ *
+ * @capability race-placements look up one racer's place + win/lose within a finish order
+ */
+export declare function placementOf(finishOrder: readonly string[], racerId: string, options?: PlacementOptions): RacePlacement | null;
+/**
+ * The win/lose verdict for one racer in a finish order — `ranking[0] === player ? "win" : "lose"`, the
+ * check every racing game hand-rolls, generalized to a `winningPlaces` cutoff. A racer absent from the
+ * order counts as a `lose`.
+ */
+export declare function raceOutcomeOf(finishOrder: readonly string[], racerId: string, options?: PlacementOptions): RaceOutcome;
+/**
+ * Per-segment durations from a cumulative split book (`splits[i]` = elapsed time at checkpoint `i`):
+ * `segments[i] = splits[i] − splits[i−1]`, the first measured from `start` (default 0). Turns the
+ * cumulative splits {@link RacerProgress} records into the individual leg times a results screen shows.
+ *
+ * @capability lap-splits turn cumulative split times into per-segment leg times
+ */
+export declare function splitSegments(splits: readonly number[], start?: number): number[];
+/**
+ * Per-lap durations from a cumulative split book with `gatesPerLap` checkpoints per lap — each lap's time
+ * is its finish-gate split minus the previous lap's finish. Only complete laps are returned.
+ *
+ * @capability lap-splits per-lap durations from a cumulative split book
+ */
+export declare function lapDurations(splits: readonly number[], gatesPerLap: number): number[];
+/**
+ * Elementwise delta of a cumulative split book against a `reference` book (a personal best or par lap):
+ * positive means behind the reference at that checkpoint. Compared up to the shorter length — the
+ * `+0.3s` / `−1.2s` gap every racing HUD shows against its ghost.
+ *
+ * @capability lap-splits delta of splits against a personal-best or par reference
+ */
+export declare function parDelta(splits: readonly number[], reference: readonly number[]): number[];

package/dist/game/race.js

@@ -316,6 +316,175 @@ export class RaceState {
         return events;
     }
 }
+/**
+ * A checkpoint race state machine — laps, forks, live standings, splits, and pluggable win conditions.
+ *
+ * @capability race-track a checkpoint race with laps, standings, splits, and win conditions
+ */
 export function createRaceState(config) {
     return new RaceState(config);
 }
+/**
+ * Create a {@link LapTimer} starting at lap 0 with no splits, best, or last time recorded.
+ *
+ * @capability lap-timer wall-clock current/last/best lap timing with splits
+ */
+export function createLapTimer() {
+    let currentLap = 0;
+    let lastLap = null;
+    let bestLap = null;
+    let total = 0;
+    const splits = [];
+    return {
+        tick(dt) {
+            if (dt <= 0)
+                return;
+            currentLap += dt;
+            total += dt;
+        },
+        completeLap() {
+            const lapTime = currentLap;
+            lastLap = lapTime;
+            bestLap = bestLap === null || lapTime < bestLap ? lapTime : bestLap;
+            splits.push(lapTime);
+            currentLap = 0;
+            return lapTime;
+        },
+        penalize(seconds) {
+            if (seconds <= 0)
+                return;
+            currentLap += seconds;
+            total += seconds;
+        },
+        reset() {
+            currentLap = 0;
+            lastLap = null;
+            bestLap = null;
+            total = 0;
+            splits.length = 0;
+        },
+        snapshot() {
+            return { currentLap, lastLap, bestLap, total, lapCount: splits.length, splits: [...splits] };
+        },
+    };
+}
+const DEFAULT_COUNTDOWN_SECONDS = 3;
+/**
+ * The pre-race session on the grid: `idle`, both clocks at zero. Call {@link startRaceCountdown} to
+ * light the lights, or hold here until the field is ready.
+ *
+ * @capability race-session pure idle→countdown→racing→finished clock every racer wraps around its state
+ */
+export function idleRaceSession() {
+    return { phase: "idle", countdown: 0, elapsed: 0 };
+}
+/**
+ * Drop the lights: return a fresh `countdown` session of `seconds` (default 3). A non-positive length
+ * skips straight to `racing` for a standing start with no countdown.
+ */
+export function startRaceCountdown(options) {
+    const seconds = Math.max(0, options?.seconds ?? DEFAULT_COUNTDOWN_SECONDS);
+    return seconds === 0 ? { phase: "racing", countdown: 0, elapsed: 0 } : { phase: "countdown", countdown: seconds, elapsed: 0 };
+}
+/**
+ * Advance the session by `dt` seconds: bleed the countdown down and flip to `racing` when it reaches
+ * zero, or accumulate `elapsed` while `racing`. `idle` and `finished` are inert. Overshoot past the
+ * countdown is dropped rather than banked into `elapsed`, so the race clock always starts from zero.
+ */
+export function tickRaceSession(session, dt) {
+    if (dt <= 0)
+        return session;
+    if (session.phase === "countdown") {
+        const countdown = session.countdown - dt;
+        return countdown <= 0 ? { phase: "racing", countdown: 0, elapsed: 0 } : { phase: "countdown", countdown, elapsed: session.elapsed };
+    }
+    if (session.phase === "racing")
+        return { phase: "racing", countdown: 0, elapsed: session.elapsed + dt };
+    return session;
+}
+/** Cross the flag: move a `racing` session to `finished`, freezing its `elapsed`. A no-op in any other phase. */
+export function finishRaceSession(session) {
+    return session.phase === "racing" ? { phase: "finished", countdown: 0, elapsed: session.elapsed } : session;
+}
+function outcomeForPlace(place, winningPlaces) {
+    return place <= winningPlaces ? "win" : "lose";
+}
+/**
+ * Turn a finish-order ranking (index 0 = winner, e.g. the `ranking` of a `race.finished` event) into
+ * per-racer {@link RacePlacement}s — the `1st/2nd/3rd` + win/lose every results screen shows.
+ *
+ * @capability race-placements finish order into per-racer place + win/lose for a results screen
+ */
+export function racePlacements(finishOrder, options) {
+    const winningPlaces = Math.max(0, Math.floor(options?.winningPlaces ?? 1));
+    return finishOrder.map((racerId, index) => ({ racerId, place: index + 1, outcome: outcomeForPlace(index + 1, winningPlaces) }));
+}
+/**
+ * One racer's {@link RacePlacement} within a finish order, or `null` if they never crossed the line.
+ *
+ * @capability race-placements look up one racer's place + win/lose within a finish order
+ */
+export function placementOf(finishOrder, racerId, options) {
+    const index = finishOrder.indexOf(racerId);
+    if (index < 0)
+        return null;
+    const winningPlaces = Math.max(0, Math.floor(options?.winningPlaces ?? 1));
+    return { racerId, place: index + 1, outcome: outcomeForPlace(index + 1, winningPlaces) };
+}
+/**
+ * The win/lose verdict for one racer in a finish order — `ranking[0] === player ? "win" : "lose"`, the
+ * check every racing game hand-rolls, generalized to a `winningPlaces` cutoff. A racer absent from the
+ * order counts as a `lose`.
+ */
+export function raceOutcomeOf(finishOrder, racerId, options) {
+    return placementOf(finishOrder, racerId, options)?.outcome ?? "lose";
+}
+/**
+ * Per-segment durations from a cumulative split book (`splits[i]` = elapsed time at checkpoint `i`):
+ * `segments[i] = splits[i] − splits[i−1]`, the first measured from `start` (default 0). Turns the
+ * cumulative splits {@link RacerProgress} records into the individual leg times a results screen shows.
+ *
+ * @capability lap-splits turn cumulative split times into per-segment leg times
+ */
+export function splitSegments(splits, start = 0) {
+    const segments = [];
+    let previous = start;
+    for (const split of splits) {
+        segments.push(split - previous);
+        previous = split;
+    }
+    return segments;
+}
+/**
+ * Per-lap durations from a cumulative split book with `gatesPerLap` checkpoints per lap — each lap's time
+ * is its finish-gate split minus the previous lap's finish. Only complete laps are returned.
+ *
+ * @capability lap-splits per-lap durations from a cumulative split book
+ */
+export function lapDurations(splits, gatesPerLap) {
+    if (gatesPerLap <= 0)
+        return [];
+    const laps = [];
+    for (let lap = 0;; lap += 1) {
+        const finish = lap * gatesPerLap + (gatesPerLap - 1);
+        if (finish >= splits.length)
+            break;
+        const previousFinish = lap === 0 ? 0 : (splits[lap * gatesPerLap - 1] ?? 0);
+        laps.push(splits[finish] - previousFinish);
+    }
+    return laps;
+}
+/**
+ * Elementwise delta of a cumulative split book against a `reference` book (a personal best or par lap):
+ * positive means behind the reference at that checkpoint. Compared up to the shorter length — the
+ * `+0.3s` / `−1.2s` gap every racing HUD shows against its ghost.
+ *
+ * @capability lap-splits delta of splits against a personal-best or par reference
+ */
+export function parDelta(splits, reference) {
+    const count = Math.min(splits.length, reference.length);
+    const deltas = [];
+    for (let i = 0; i < count; i += 1)
+        deltas.push(splits[i] - reference[i]);
+    return deltas;
+}

package/dist/game/recordBook.d.ts

@@ -1,4 +1,4 @@
-import type { KeyValueStorage } from "./keyValueStore.js";
+import { type KeyValueStorage } from "./keyValueStore.js";
 /** The structural storage backend a record book persists through — an alias of the shared {@link KeyValueStorage} seam (browser `localStorage`, a test stub, or `null`). */
 export type RecordStorage = KeyValueStorage;
 export type RecordDirection = "lower" | "higher";
@@ -23,5 +23,7 @@ export interface RecordBook<K extends string> {
  * key-value storage (pass `localStorage` in a browser, a stub in tests, or
  * `null` for in-memory only). Corrupt or unavailable storage degrades to an
  * empty book — a record write never throws into a game tick.
+ *
+ * @capability best-record persist personal-best times/scores with safe storage fallback
  */
 export declare function createRecordBook<K extends string>(config: RecordBookConfig<K>): RecordBook<K>;

package/dist/game/recordBook.js

@@ -1,3 +1,4 @@
+import { defaultKeyValueStorage } from "./keyValueStore.js";
 function loadStored(config, storage) {
     if (storage === null)
         return {};
@@ -33,9 +34,11 @@ function loadStored(config, storage) {
  * key-value storage (pass `localStorage` in a browser, a stub in tests, or
  * `null` for in-memory only). Corrupt or unavailable storage degrades to an
  * empty book — a record write never throws into a game tick.
+ *
+ * @capability best-record persist personal-best times/scores with safe storage fallback
  */
 export function createRecordBook(config) {
-    const storage = config.storage ?? null;
+    const storage = config.storage === undefined ? defaultKeyValueStorage() : config.storage;
     let best = loadStored(config, storage);
     function persist() {
         if (storage === null)

package/dist/game/ruleSelection.d.ts

@@ -0,0 +1,75 @@
+import { type ParamLayer, type LayerSelection } from "./paramLayers.js";
+/**
+ * A selectable rule over a tagged pool. `tags` classify it for include/exclude filtering and for
+ * `requires`/`conflicts` matching (which match either another rule's id or one of its tags). `layers`
+ * are the parameter layers this rule contributes when active; `payload` is opaque caller data.
+ */
+export interface RuleDef<TPayload = unknown> {
+    readonly id: string;
+    readonly tags?: readonly string[];
+    /** Relative pick weight; non-positive or omitted is treated as `1`. */
+    readonly weight?: number;
+    /** Ids/tags that must already be selected for this rule to become eligible. */
+    readonly requires?: readonly string[];
+    /** Ids/tags that, if already selected (either direction), make this rule ineligible. */
+    readonly conflicts?: readonly string[];
+    /** Parameter layers contributed when this rule is active, read back via {@link RuleRegistry.layersFor}. */
+    readonly layers?: readonly ParamLayer[];
+    readonly payload?: TPayload;
+}
+/** Deterministic selection inputs — plain serializable data a host can persist and replay. */
+export interface RuleSelectionConfig {
+    readonly count: number;
+    readonly seed: string | number;
+    /** If set, only rules carrying at least one of these tags are eligible. */
+    readonly includeTags?: readonly string[];
+    /** Rules carrying any of these tags are excluded outright. */
+    readonly excludeTags?: readonly string[];
+    /** Rule ids force-selected first, in order; counts toward `count`. Unknown ids are ignored. */
+    readonly locked?: readonly string[];
+}
+/** The result of a selection — the chosen rules and their ids (a serializable {@link LayerSelection}-style list). */
+export interface RuleSelection<TPayload = unknown> {
+    readonly rules: readonly RuleDef<TPayload>[];
+    readonly ids: readonly string[];
+}
+/**
+ * Select up to `count` rules from `pool` deterministically from `config.seed`. Locked ids are placed
+ * first (in order), then remaining slots are filled by weighted draw from tag-filtered, still-eligible
+ * candidates, honoring `requires`/`conflicts` after each pick. Each slot draws from an independent
+ * seed stream keyed by slot index, so a later slot's outcome never shifts an earlier one. Selection
+ * stops early when no compatible candidate remains. Pure given `pool` + `config`.
+ *
+ * @capability rule-selection deterministically select rules from a tagged pool under compatibility/exclusion constraints
+ */
+export declare function selectRules<TPayload = unknown>(pool: readonly RuleDef<TPayload>[], config: RuleSelectionConfig): RuleSelection<TPayload>;
+/**
+ * Reroll a prior selection: keep `keepIds` (the locked slots) and re-draw the rest under a fresh,
+ * still-deterministic stream derived from `config.seed` and `salt`. The same seed + salt + keep set
+ * reproduce the same reroll, so reroll history stays replayable.
+ *
+ * @capability rule-selection reroll unlocked slots of a selection deterministically from seed and salt
+ */
+export declare function rerollRules<TPayload = unknown>(pool: readonly RuleDef<TPayload>[], config: RuleSelectionConfig, keepIds: readonly string[], salt?: string | number): RuleSelection<TPayload>;
+/** Registered pool of {@link RuleDef}s — the install seam games register mutators/modes/events into. */
+export interface RuleRegistry<TPayload = unknown> {
+    register(rule: RuleDef<TPayload>): void;
+    has(id: string): boolean;
+    get(id: string): RuleDef<TPayload> | undefined;
+    all(): readonly RuleDef<TPayload>[];
+    /** Run {@link selectRules} over the registered pool. */
+    select(config: RuleSelectionConfig): RuleSelection<TPayload>;
+    /**
+     * Collect the parameter layers contributed by the given selected rule ids, in id order. Unknown ids
+     * are skipped so stale/migrated selections resolve without throwing. This is the bridge from a
+     * rule selection to a {@link ParamLayer} stack — core reads `.layers`, never a rule's name.
+     */
+    layersFor(ids: LayerSelection): readonly ParamLayer[];
+}
+/**
+ * Create a {@link RuleRegistry}. Rules install through `register` (duplicate ids throw); selection and
+ * `layersFor` are data-driven, so the core never branches on which mutators exist.
+ *
+ * @capability rule-selection register rules and bridge a selection to its contributed parameter layers
+ */
+export declare function createRuleRegistry<TPayload = unknown>(initial?: readonly RuleDef<TPayload>[]): RuleRegistry<TPayload>;

package/dist/game/ruleSelection.js

@@ -0,0 +1,127 @@
+/**
+ * Seeded rule selection over a tagged pool.
+ *
+ * A {@link RuleDef} is a caller-owned selectable — a mutator, game mode, event, or challenge modifier
+ * — carrying tags, an optional weight, compatibility (`requires`) and exclusion (`conflicts`)
+ * constraints, and any {@link ParamLayer}s it contributes when active. {@link selectRules} draws a
+ * requested count from the eligible pool using injected, deterministic randomness: the same seed and
+ * pool always yield the same rules, so a host can reproduce a session from `{ seed, count }` alone and
+ * every peer agrees without replicating the roll.
+ *
+ * Core never branches on known rule names — selection is driven entirely by tags and the caller's
+ * constraint data, and a selected rule's behavior is read back through its `layers`/`payload`. That
+ * keeps the seam genre-agnostic and lets games install rules through {@link createRuleRegistry}
+ * without the primitive knowing what any mutator "means".
+ */
+import { pickWeighted } from "../random/pick.js";
+import { seededStreams } from "../random/rng.js";
+import {} from "./paramLayers.js";
+function tokensOf(rule) {
+    return [rule.id, ...(rule.tags ?? [])];
+}
+function passesTagFilter(rule, config) {
+    const tags = rule.tags ?? [];
+    if (config.excludeTags?.some((tag) => tags.includes(tag)))
+        return false;
+    if (config.includeTags && config.includeTags.length > 0) {
+        return config.includeTags.some((tag) => tags.includes(tag));
+    }
+    return true;
+}
+function isCompatible(rule, selected) {
+    const selectedTokens = new Set(selected.flatMap(tokensOf));
+    if (rule.requires && !rule.requires.every((token) => selectedTokens.has(token)))
+        return false;
+    if (rule.conflicts?.some((token) => selectedTokens.has(token)))
+        return false;
+    const ruleTokens = new Set(tokensOf(rule));
+    for (const other of selected) {
+        if (other.conflicts?.some((token) => ruleTokens.has(token)))
+            return false;
+    }
+    return true;
+}
+/**
+ * Select up to `count` rules from `pool` deterministically from `config.seed`. Locked ids are placed
+ * first (in order), then remaining slots are filled by weighted draw from tag-filtered, still-eligible
+ * candidates, honoring `requires`/`conflicts` after each pick. Each slot draws from an independent
+ * seed stream keyed by slot index, so a later slot's outcome never shifts an earlier one. Selection
+ * stops early when no compatible candidate remains. Pure given `pool` + `config`.
+ *
+ * @capability rule-selection deterministically select rules from a tagged pool under compatibility/exclusion constraints
+ */
+export function selectRules(pool, config) {
+    const byId = new Map(pool.map((rule) => [rule.id, rule]));
+    const chosen = [];
+    const chosenIds = new Set();
+    for (const id of config.locked ?? []) {
+        const rule = byId.get(id);
+        if (rule && !chosenIds.has(id)) {
+            chosen.push(rule);
+            chosenIds.add(id);
+        }
+        if (chosen.length >= config.count)
+            return { rules: chosen, ids: chosen.map((r) => r.id) };
+    }
+    const streams = seededStreams(config.seed);
+    let slot = chosen.length;
+    while (chosen.length < config.count) {
+        const candidates = pool.filter((rule) => !chosenIds.has(rule.id) && passesTagFilter(rule, config) && isCompatible(rule, chosen));
+        if (candidates.length === 0)
+            break;
+        const picked = pickWeighted(streams(`slot:${slot}`), candidates, (rule) => rule.weight !== undefined && rule.weight > 0 ? rule.weight : 1);
+        if (!picked)
+            break;
+        chosen.push(picked);
+        chosenIds.add(picked.id);
+        slot += 1;
+    }
+    return { rules: chosen, ids: chosen.map((r) => r.id) };
+}
+/**
+ * Reroll a prior selection: keep `keepIds` (the locked slots) and re-draw the rest under a fresh,
+ * still-deterministic stream derived from `config.seed` and `salt`. The same seed + salt + keep set
+ * reproduce the same reroll, so reroll history stays replayable.
+ *
+ * @capability rule-selection reroll unlocked slots of a selection deterministically from seed and salt
+ */
+export function rerollRules(pool, config, keepIds, salt = 0) {
+    return selectRules(pool, {
+        ...config,
+        locked: keepIds,
+        seed: `${config.seed}:reroll:${salt}`,
+    });
+}
+/**
+ * Create a {@link RuleRegistry}. Rules install through `register` (duplicate ids throw); selection and
+ * `layersFor` are data-driven, so the core never branches on which mutators exist.
+ *
+ * @capability rule-selection register rules and bridge a selection to its contributed parameter layers
+ */
+export function createRuleRegistry(initial) {
+    const rules = new Map();
+    const register = (rule) => {
+        if (rules.has(rule.id))
+            throw new Error(`rule "${rule.id}" is already registered`);
+        rules.set(rule.id, rule);
+    };
+    if (initial)
+        for (const rule of initial)
+            register(rule);
+    return {
+        register,
+        has: (id) => rules.has(id),
+        get: (id) => rules.get(id),
+        all: () => [...rules.values()],
+        select: (config) => selectRules([...rules.values()], config),
+        layersFor(ids) {
+            const layers = [];
+            for (const id of ids) {
+                const rule = rules.get(id);
+                if (rule?.layers)
+                    layers.push(...rule.layers);
+            }
+            return layers;
+        },
+    };
+}

package/dist/game/runDraft.d.ts

@@ -31,4 +31,9 @@ export interface RunDraft<TStat extends string = string, TData = unknown> {
     choose(offerId: string): boolean;
     stack(): RunModifierStack<TStat, TData>;
 }
+/**
+ * A roguelike run built from stacking drafted modifier picks that reshape the run.
+ *
+ * @capability run-modifiers a roguelike run built from stacking drafted modifier picks
+ */
 export declare function createRunDraft<TStat extends string = string, TData = unknown>(config: RunDraftConfig<TStat, TData>): RunDraft<TStat, TData>;

package/dist/game/runDraft.js

@@ -68,6 +68,11 @@ export function createRunModifierStack(offers) {
         },
     };
 }
+/**
+ * A roguelike run built from stacking drafted modifier picks that reshape the run.
+ *
+ * @capability run-modifiers a roguelike run built from stacking drafted modifier picks
+ */
 export function createRunDraft(config) {
     const stack = createRunModifierStack(config.offers);
     const defaultRng = config.rng ?? Math.random;