@jgengine/core 0.10.0 → 0.12.0

package/dist/area/areaEffectField.js

@@ -0,0 +1,175 @@
+/**
+ * Continuous area-effect membership: moving sources emit an area that follows them each tick,
+ * receivers that move in and out get enter / refresh / leave edges, and membership is cleaned up
+ * when a source is removed, disabled, or the field is cleared. A pure lifecycle machine — it never
+ * applies damage, heals, or stat changes itself; the caller routes each edge through its own
+ * effect pipeline (see `combat/effects`, `combat/dotField`, `stats/statModifiers`). This is the
+ * dynamic, source-following counterpart to `scene/authoredTriggers` (static document volumes).
+ *
+ * Bounded by design: the caller supplies a broad-phase `candidates(shape)` query (e.g.
+ * `visibility/spatialIndex`'s `querySphere`) plus a `positionOf` lookup, so a step visits only
+ * receivers near each source — never the whole world. Serializable: `serialize()` captures the
+ * membership set and each member's refresh phase so cadence and enter/leave edges survive save/load.
+ */
+const SENTINEL_SHAPE = { kind: "sphere", center: [0, 0, 0], radius: 0 };
+function shapeContains(shape, point) {
+    if (shape.kind === "custom")
+        return shape.contains(point);
+    const dx = point[0] - shape.center[0];
+    const dy = point[1] - shape.center[1];
+    const dz = point[2] - shape.center[2];
+    return dx * dx + dy * dy + dz * dz <= shape.radius * shape.radius;
+}
+/**
+ * Build a continuous area-effect field. Drive it with `setSource` (once per live source per tick, so
+ * shapes follow their emitters) and `step` (to reconcile membership and drain enter/refresh/leave edges).
+ * Optionally restore prior membership by passing a `serialize()` snapshot; re-`setSource` live shapes
+ * before the first `step` after restore, since shapes are transient.
+ *
+ * @capability area-effect-field source-following area membership with enter/refresh/leave edges, stacking, and cleanup
+ */
+export function createAreaEffectField(state) {
+    const sources = new Map();
+    if (state !== undefined) {
+        for (const source of state.sources) {
+            sources.set(source.id, {
+                shape: SENTINEL_SHAPE,
+                payload: source.payload,
+                refreshMs: source.refreshMs,
+                stackKey: source.stackKey,
+                enabled: source.enabled,
+                members: new Map(),
+            });
+        }
+        for (const membership of state.memberships) {
+            sources.get(membership.sourceId)?.members.set(membership.receiverId, {
+                sinceRefreshMs: membership.sinceRefreshMs,
+            });
+        }
+    }
+    function leaveAll(rec, sourceId, reason) {
+        const events = [];
+        for (const receiverId of rec.members.keys()) {
+            events.push({ kind: "leave", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload, reason });
+        }
+        rec.members.clear();
+        return events;
+    }
+    return {
+        setSource(spec) {
+            const stackKey = spec.stackKey ?? spec.id;
+            const enabled = spec.enabled ?? true;
+            const existing = sources.get(spec.id);
+            if (existing !== undefined) {
+                existing.shape = spec.shape;
+                existing.payload = spec.payload;
+                existing.refreshMs = spec.refreshMs;
+                existing.stackKey = stackKey;
+                existing.enabled = enabled;
+                return;
+            }
+            sources.set(spec.id, {
+                shape: spec.shape,
+                payload: spec.payload,
+                refreshMs: spec.refreshMs,
+                stackKey,
+                enabled,
+                members: new Map(),
+            });
+        },
+        removeSource(id) {
+            const rec = sources.get(id);
+            if (rec === undefined)
+                return [];
+            const events = leaveAll(rec, id, "source-removed");
+            sources.delete(id);
+            return events;
+        },
+        hasSource: (id) => sources.has(id),
+        sourceIds: () => [...sources.keys()],
+        step(input) {
+            const dtMs = Math.max(0, input.dtMs);
+            const events = [];
+            for (const [sourceId, rec] of sources) {
+                if (!rec.enabled) {
+                    events.push(...leaveAll(rec, sourceId, "disabled"));
+                    continue;
+                }
+                const seen = new Set();
+                for (const receiverId of input.candidates(rec.shape)) {
+                    if (seen.has(receiverId))
+                        continue;
+                    const position = input.positionOf(receiverId);
+                    if (position === undefined)
+                        continue;
+                    if (!shapeContains(rec.shape, position))
+                        continue;
+                    if (input.eligible !== undefined && !input.eligible(sourceId, receiverId, rec.payload))
+                        continue;
+                    seen.add(receiverId);
+                    const member = rec.members.get(receiverId);
+                    if (member === undefined) {
+                        rec.members.set(receiverId, { sinceRefreshMs: 0 });
+                        events.push({ kind: "enter", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload });
+                        continue;
+                    }
+                    if (rec.refreshMs !== undefined && rec.refreshMs > 0) {
+                        member.sinceRefreshMs += dtMs;
+                        let ticks = 0;
+                        while (member.sinceRefreshMs >= rec.refreshMs) {
+                            member.sinceRefreshMs -= rec.refreshMs;
+                            ticks += 1;
+                        }
+                        if (ticks > 0) {
+                            events.push({ kind: "refresh", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload, ticks });
+                        }
+                    }
+                }
+                for (const receiverId of [...rec.members.keys()]) {
+                    if (seen.has(receiverId))
+                        continue;
+                    rec.members.delete(receiverId);
+                    events.push({ kind: "leave", sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload, reason: "exit" });
+                }
+            }
+            return events;
+        },
+        members: (sourceId) => [...(sources.get(sourceId)?.members.keys() ?? [])],
+        isMember: (sourceId, receiverId) => sources.get(sourceId)?.members.has(receiverId) ?? false,
+        memberships() {
+            const out = [];
+            for (const [sourceId, rec] of sources) {
+                for (const receiverId of rec.members.keys()) {
+                    out.push({ sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload });
+                }
+            }
+            return out;
+        },
+        membershipsOf(receiverId) {
+            const out = [];
+            for (const [sourceId, rec] of sources) {
+                if (rec.members.has(receiverId)) {
+                    out.push({ sourceId, receiverId, stackKey: rec.stackKey, payload: rec.payload });
+                }
+            }
+            return out;
+        },
+        clear() {
+            const events = [];
+            for (const [sourceId, rec] of sources)
+                events.push(...leaveAll(rec, sourceId, "cleared"));
+            sources.clear();
+            return events;
+        },
+        serialize() {
+            const out = { sources: [], memberships: [] };
+            for (const [id, rec] of sources) {
+                out.sources.push({ id, payload: rec.payload, refreshMs: rec.refreshMs, stackKey: rec.stackKey, enabled: rec.enabled });
+                for (const [receiverId, member] of rec.members) {
+                    out.memberships.push({ sourceId: id, receiverId, sinceRefreshMs: member.sinceRefreshMs });
+                }
+            }
+            return out;
+        },
+    };
+}

package/dist/area/stackPolicy.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Overlap aggregation for {@link AreaMembership} lists: when several area sources cover the same
+ * receiver, a policy decides which memberships actually apply. Genre-agnostic and pure — policies
+ * are `(memberships) => memberships` reducers over one receiver's memberships, so the caller stays
+ * in control of magnitude and meaning. Pair with `createAreaEffectField().membershipsOf(receiverId)`.
+ */
+import type { AreaMembership } from "./areaEffectField.js";
+/** Reduce one receiver's overlapping memberships to the subset that applies under a stacking rule. */
+export type AreaStackPolicy<P> = (memberships: readonly AreaMembership<P>[]) => AreaMembership<P>[];
+/** Read a comparable magnitude from a membership (e.g. buff strength, damage per tick). */
+export type MagnitudeOf<P> = (membership: AreaMembership<P>) => number;
+/**
+ * Every overlapping membership applies independently (no deduplication) — the default for hazards,
+ * fields, and lights where two sources genuinely stack.
+ *
+ * @capability area-stack-independent apply every overlapping area membership independently
+ */
+export declare function independentStacks<P>(): AreaStackPolicy<P>;
+/**
+ * Keep at most one membership per `stackKey`. With `magnitudeOf` the strongest per key wins (ties
+ * broken by `sourceId` for determinism); without it the first-seen per key wins. Use for
+ * unique-by-key buffs where reapplying the same aura should not stack.
+ *
+ * @capability area-stack-unique keep one area membership per stack key, strongest wins
+ */
+export declare function uniqueByStackKey<P>(magnitudeOf?: MagnitudeOf<P>): AreaStackPolicy<P>;
+/**
+ * Keep at most `limit` memberships per `stackKey` (the highest-magnitude ones when `magnitudeOf` is
+ * given, else the first-seen). Models capped stacks — e.g. a poison that stacks up to 5 times.
+ *
+ * @capability area-stack-capped cap area memberships per stack key at a maximum count
+ */
+export declare function cappedStacks<P>(limit: number, magnitudeOf?: MagnitudeOf<P>): AreaStackPolicy<P>;
+/**
+ * Reduce to the single strongest membership overall (`weakest = false` picks the weakest); ties broken
+ * by `sourceId`. Use when only the best or worst overlapping source should apply.
+ *
+ * @capability area-stack-extremum keep only the strongest or weakest overlapping area membership
+ */
+export declare function extremumStack<P>(magnitudeOf: MagnitudeOf<P>, weakest?: boolean): AreaStackPolicy<P>;
+/**
+ * Sum a numeric magnitude across memberships — additive aggregation for a total field strength
+ * (total damage per tick, total slow). A terminal reducer, not a filter, so it returns the number.
+ *
+ * @capability area-stack-additive sum a magnitude across overlapping area memberships
+ */
+export declare function sumMagnitude<P>(memberships: readonly AreaMembership<P>[], magnitudeOf: MagnitudeOf<P>): number;

package/dist/area/stackPolicy.js

@@ -0,0 +1,99 @@
+/**
+ * Overlap aggregation for {@link AreaMembership} lists: when several area sources cover the same
+ * receiver, a policy decides which memberships actually apply. Genre-agnostic and pure — policies
+ * are `(memberships) => memberships` reducers over one receiver's memberships, so the caller stays
+ * in control of magnitude and meaning. Pair with `createAreaEffectField().membershipsOf(receiverId)`.
+ */
+function byMagnitudeDesc(magnitudeOf) {
+    return (a, b) => {
+        const diff = magnitudeOf(b) - magnitudeOf(a);
+        if (diff !== 0)
+            return diff;
+        return a.sourceId < b.sourceId ? -1 : a.sourceId > b.sourceId ? 1 : 0;
+    };
+}
+function groupByStackKey(memberships) {
+    const groups = new Map();
+    for (const membership of memberships) {
+        const list = groups.get(membership.stackKey);
+        if (list === undefined)
+            groups.set(membership.stackKey, [membership]);
+        else
+            list.push(membership);
+    }
+    return groups;
+}
+/**
+ * Every overlapping membership applies independently (no deduplication) — the default for hazards,
+ * fields, and lights where two sources genuinely stack.
+ *
+ * @capability area-stack-independent apply every overlapping area membership independently
+ */
+export function independentStacks() {
+    return (memberships) => [...memberships];
+}
+/**
+ * Keep at most one membership per `stackKey`. With `magnitudeOf` the strongest per key wins (ties
+ * broken by `sourceId` for determinism); without it the first-seen per key wins. Use for
+ * unique-by-key buffs where reapplying the same aura should not stack.
+ *
+ * @capability area-stack-unique keep one area membership per stack key, strongest wins
+ */
+export function uniqueByStackKey(magnitudeOf) {
+    return (memberships) => {
+        const out = [];
+        for (const group of groupByStackKey(memberships).values()) {
+            if (magnitudeOf === undefined) {
+                out.push(group[0]);
+            }
+            else {
+                out.push([...group].sort(byMagnitudeDesc(magnitudeOf))[0]);
+            }
+        }
+        return out;
+    };
+}
+/**
+ * Keep at most `limit` memberships per `stackKey` (the highest-magnitude ones when `magnitudeOf` is
+ * given, else the first-seen). Models capped stacks — e.g. a poison that stacks up to 5 times.
+ *
+ * @capability area-stack-capped cap area memberships per stack key at a maximum count
+ */
+export function cappedStacks(limit, magnitudeOf) {
+    const cap = Math.max(0, Math.floor(limit));
+    return (memberships) => {
+        const out = [];
+        for (const group of groupByStackKey(memberships).values()) {
+            const ordered = magnitudeOf === undefined ? group : [...group].sort(byMagnitudeDesc(magnitudeOf));
+            for (const membership of ordered.slice(0, cap))
+                out.push(membership);
+        }
+        return out;
+    };
+}
+/**
+ * Reduce to the single strongest membership overall (`weakest = false` picks the weakest); ties broken
+ * by `sourceId`. Use when only the best or worst overlapping source should apply.
+ *
+ * @capability area-stack-extremum keep only the strongest or weakest overlapping area membership
+ */
+export function extremumStack(magnitudeOf, weakest = false) {
+    return (memberships) => {
+        if (memberships.length === 0)
+            return [];
+        const ordered = [...memberships].sort(byMagnitudeDesc(magnitudeOf));
+        return [weakest ? ordered[ordered.length - 1] : ordered[0]];
+    };
+}
+/**
+ * Sum a numeric magnitude across memberships — additive aggregation for a total field strength
+ * (total damage per tick, total slow). A terminal reducer, not a filter, so it returns the number.
+ *
+ * @capability area-stack-additive sum a magnitude across overlapping area memberships
+ */
+export function sumMagnitude(memberships, magnitudeOf) {
+    let total = 0;
+    for (const membership of memberships)
+        total += magnitudeOf(membership);
+    return total;
+}

package/dist/authoring.d.ts

@@ -5,10 +5,11 @@
  * advanced composition, but this module intentionally exposes common authored
  * concepts without requiring callers to understand the repository layout.
  */
-export { defineGame, type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
+export { type GameDefinition, type GameDefinitionConfig, type GameLoop, type InventoryDeclaration, type PhysicsConfig, type GameServerConfig, } from "./game/defineGame.js";
 export { lootTable, type LootTableDef, type LootEntry, type Drop, } from "./game/lootTable.js";
 export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, type WorldFeature, } from "./world/features.js";
 export { seededRng, seededStreams } from "./random/rng.js";
 export { selectSpawnPoint, type SpawnPointSelectionOptions, type SpawnPointDistanceBias, } from "./ai/spawnPoint.js";
 export { contextVerb } from "./interaction/contextMenu.js";
 export { type ActionCodesMap } from "./input/actionBindings.js";
+export { classifyOwnership, collectOwnershipDiagnostics, auditManifest, ownershipKey, isSceneOwnershipManifest, SCENE_OWNERSHIP_MANIFEST_VERSION, type SceneProvenance, type SceneProvenanceKind, type AuthoredProvenance, type GeneratedProvenance, type RuntimeProvenance, type TransientProvenance, type ProviderCapabilities, type SceneOwnershipDeclaration, type OwnershipDecision, type OwnershipVerdict, type OwnershipDiagnostic, type SceneOwnershipManifest, } from "./scene/sceneOwnership.js";

package/dist/authoring.js

@@ -5,10 +5,11 @@
  * advanced composition, but this module intentionally exposes common authored
  * concepts without requiring callers to understand the repository layout.
  */
-export { defineGame, } from "./game/defineGame.js";
+export {} from "./game/defineGame.js";
 export { lootTable, } from "./game/lootTable.js";
 export { biomes, voxel, plots, tilemap, flat, environment, terrain, rain, snow, grass, ocean, building, road, } from "./world/features.js";
 export { seededRng, seededStreams } from "./random/rng.js";
 export { selectSpawnPoint, } from "./ai/spawnPoint.js";
 export { contextVerb } from "./interaction/contextMenu.js";
 export {} from "./input/actionBindings.js";
+export { classifyOwnership, collectOwnershipDiagnostics, auditManifest, ownershipKey, isSceneOwnershipManifest, SCENE_OWNERSHIP_MANIFEST_VERSION, } from "./scene/sceneOwnership.js";

package/dist/board/laneBoard.d.ts

@@ -43,12 +43,19 @@ export interface LanePlaceRejected {
     reason: LaneRejection;
 }
 export type LaneResult<C> = LanePlaceResult<C> | LanePlaceRejected;
+/** @internal */
 export declare function createLaneBoardState<C>(config: LaneBoardConfig<C>): LaneBoardState<C>;
+/** @internal */
 export declare function placeCard<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number, side: Side, card: C): LaneResult<C>;
+/** @internal */
 export declare function removeCard<C>(state: LaneBoardState<C>, lane: number, side: Side, predicate: (card: C, index: number) => boolean): LaneResult<C>;
+/** @internal */
 export declare function laneAggregate<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number, side: Side): LaneAggregate;
+/** @internal */
 export declare function laneOutcome<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>, lane: number): LaneOutcome;
+/** @internal */
 export declare function boardTotals<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>): Readonly<Record<Side, number>>;
+/** @internal */
 export declare function lanesWon<C>(state: LaneBoardState<C>, config: LaneBoardConfig<C>): Readonly<Record<Side, number>>;
 export interface LaneBoard<C> {
     state(): LaneBoardState<C>;
@@ -60,4 +67,10 @@ export interface LaneBoard<C> {
     lanesWon(): Readonly<Record<Side, number>>;
     reset(next?: LaneBoardState<C>): void;
 }
+/**
+ * A lane-based board where cards resolve per lane — the lane card-battler layout.
+ *
+ * @capability lane-board a lane-based card-battler board with per-lane outcomes
+  * @internal
+  */
 export declare function createLaneBoard<C>(config: LaneBoardConfig<C>): LaneBoard<C>;

package/dist/board/laneBoard.js

@@ -4,6 +4,7 @@ function emptyLane(sides) {
         cells[side] = [];
     return cells;
 }
+/** @internal */
 export function createLaneBoardState(config) {
     if (config.laneCount <= 0)
         throw new Error("laneBoard needs at least one lane");
@@ -17,6 +18,7 @@ export function createLaneBoardState(config) {
 function validLane(state, lane) {
     return Number.isInteger(lane) && lane >= 0 && lane < state.lanes.length;
 }
+/** @internal */
 export function placeCard(state, config, lane, side, card) {
     if (!validLane(state, lane))
         return { status: "rejected", reason: "invalid-lane" };
@@ -27,6 +29,7 @@ export function placeCard(state, config, lane, side, card) {
     lanes[lane] = { ...cell, [side]: [...cell[side], card] };
     return { status: "ok", state: { lanes } };
 }
+/** @internal */
 export function removeCard(state, lane, side, predicate) {
     if (!validLane(state, lane))
         return { status: "rejected", reason: "invalid-lane" };
@@ -37,6 +40,7 @@ export function removeCard(state, lane, side, predicate) {
     lanes[lane] = { ...cell, [side]: cell[side].filter((card, index) => !predicate(card, index)) };
     return { status: "ok", state: { lanes } };
 }
+/** @internal */
 export function laneAggregate(state, config, lane, side) {
     const cards = state.lanes[lane]?.[side] ?? [];
     let subtotal = 0;
@@ -46,6 +50,7 @@ export function laneAggregate(state, config, lane, side) {
     const total = rule ? rule.apply({ lane, side, cards, subtotal }) : subtotal;
     return { lane, side, subtotal, total, count: cards.length };
 }
+/** @internal */
 export function laneOutcome(state, config, lane) {
     const totals = {};
     let winner = null;
@@ -65,6 +70,7 @@ export function laneOutcome(state, config, lane) {
     }
     return { lane, totals, winner: tie ? null : winner };
 }
+/** @internal */
 export function boardTotals(state, config) {
     const totals = {};
     for (const side of config.sides)
@@ -76,6 +82,7 @@ export function boardTotals(state, config) {
     }
     return totals;
 }
+/** @internal */
 export function lanesWon(state, config) {
     const won = {};
     for (const side of config.sides)
@@ -87,6 +94,12 @@ export function lanesWon(state, config) {
     }
     return won;
 }
+/**
+ * A lane-based board where cards resolve per lane — the lane card-battler layout.
+ *
+ * @capability lane-board a lane-based card-battler board with per-lane outcomes
+  * @internal
+  */
 export function createLaneBoard(config) {
     let state = createLaneBoardState(config);
     return {

package/dist/board/timelineBoard.d.ts

@@ -23,9 +23,13 @@ export interface TimelineTickResult {
     state: TimelineBoardState;
     fires: readonly TimelineFire[];
 }
+/** @internal */
 export declare function createTimelineBoardState(slots: readonly TimelineSlotConfig[]): TimelineBoardState;
+/** @internal */
 export declare function tickTimeline(state: TimelineBoardState, dtMs: number): TimelineTickResult;
+/** @internal */
 export declare function setSlotEnabled(state: TimelineBoardState, slotId: string, enabled: boolean): TimelineBoardState;
+/** @internal */
 export declare function resetSlot(state: TimelineBoardState, slotId: string, remainingMs?: number): TimelineBoardState;
 export interface TimelineBoard {
     state(): TimelineBoardState;
@@ -33,4 +37,10 @@ export interface TimelineBoard {
     setEnabled(slotId: string, enabled: boolean): void;
     reset(slotId?: string, remainingMs?: number): void;
 }
+/**
+ * A step-sequencer timeline board of timed, toggleable slots.
+ *
+ * @capability timeline-board a step-sequencer timeline board of timed slots
+  * @internal
+  */
 export declare function createTimelineBoard(slots: readonly TimelineSlotConfig[]): TimelineBoard;

package/dist/board/timelineBoard.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createTimelineBoardState(slots) {
     const seen = new Set();
     const built = [];
@@ -16,6 +17,7 @@ export function createTimelineBoardState(slots) {
     }
     return { slots: built, elapsedMs: 0 };
 }
+/** @internal */
 export function tickTimeline(state, dtMs) {
     if (dtMs <= 0)
         return { state, fires: [] };
@@ -38,18 +40,26 @@ export function tickTimeline(state, dtMs) {
         fires,
     };
 }
+/** @internal */
 export function setSlotEnabled(state, slotId, enabled) {
     return {
         ...state,
         slots: state.slots.map((slot) => (slot.id === slotId ? { ...slot, enabled } : slot)),
     };
 }
+/** @internal */
 export function resetSlot(state, slotId, remainingMs) {
     return {
         ...state,
         slots: state.slots.map((slot) => slot.id === slotId ? { ...slot, remainingMs: remainingMs ?? slot.cooldownMs } : slot),
     };
 }
+/**
+ * A step-sequencer timeline board of timed, toggleable slots.
+ *
+ * @capability timeline-board a step-sequencer timeline board of timed slots
+  * @internal
+  */
 export function createTimelineBoard(slots) {
     const initial = slots;
     let state = createTimelineBoardState(slots);

package/dist/combat/abilityKit.d.ts

@@ -15,8 +15,21 @@ export interface AbilityCooldownGroup {
     id: string;
     cooldownMs: number;
 }
+/**
+ * A spendable resource pool (mana, energy, rage) bound to an ability kit. When bound, `cast` deducts a
+ * slot's `resourceCost` on success and `state`/`snapshot`/`canCast` reflect affordability without a
+ * per-call `resourceAvailable` argument — the cast path actually spends instead of only gating (#357).
+ */
+export interface AbilityResource {
+    /** Current spendable amount, read fresh on each cast/snapshot. */
+    available(): number;
+    /** Deduct `cost` from the pool after a successful cast. */
+    spend(cost: number): void;
+}
 export interface AbilityKitOptions {
     groups?: readonly AbilityCooldownGroup[];
+    /** Bind a resource pool so casting charges `resourceCost` and snapshots reflect affordability automatically. Passing an explicit `resourceAvailable` to a method overrides the bound pool for that call and never auto-spends. */
+    resource?: AbilityResource;
 }
 export interface AbilitySlotSnapshot {
     id: string;
@@ -59,4 +72,9 @@ export interface AbilityKit {
     reset(slotId?: string): void;
     retuneSlot(slotId: string, patch: AbilitySlotRetune): boolean;
 }
+/**
+ * A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
+ *
+ * @capability ability-bar a bar of cooldown-gated abilities the player triggers by slot
+ */
 export declare function createAbilityKit(configs: readonly AbilitySlotConfig[], options?: AbilityKitOptions): AbilityKit;

package/dist/combat/abilityKit.js

@@ -39,7 +39,18 @@ function snapshotOf(runtime, resourceAvailable, group) {
         ready: runtime.charges > 0 && group.remainingMs <= 0 && resourceAvailable >= config.resourceCost,
     };
 }
+/**
+ * A bar of cooldown-gated abilities the player fires by slot, tracking readiness and cooldown per ability.
+ *
+ * @capability ability-bar a bar of cooldown-gated abilities the player triggers by slot
+ */
 export function createAbilityKit(configs, options = {}) {
+    const boundResource = options.resource;
+    function currentResource(explicit) {
+        if (explicit !== undefined)
+            return explicit;
+        return boundResource === undefined ? Number.POSITIVE_INFINITY : boundResource.available();
+    }
     const groupCooldowns = new Map();
     const groupRemaining = new Map();
     for (const group of options.groups ?? []) {
@@ -103,21 +114,22 @@ export function createAbilityKit(configs, options = {}) {
         config(slotId) {
             return runtimes.get(slotId)?.config ?? null;
         },
-        state(slotId, resourceAvailable = Number.POSITIVE_INFINITY) {
+        state(slotId, resourceAvailable) {
             const runtime = runtimes.get(slotId);
-            return runtime === undefined ? null : snapshotOf(runtime, resourceAvailable, groupBlockOf(runtime));
+            return runtime === undefined ? null : snapshotOf(runtime, currentResource(resourceAvailable), groupBlockOf(runtime));
         },
-        snapshot(resourceAvailable = Number.POSITIVE_INFINITY) {
+        snapshot(resourceAvailable) {
+            const available = currentResource(resourceAvailable);
             return order.map((slotId) => {
                 const runtime = runtimes.get(slotId);
-                return snapshotOf(runtime, resourceAvailable, groupBlockOf(runtime));
+                return snapshotOf(runtime, available, groupBlockOf(runtime));
             });
         },
-        canCast(slotId, resourceAvailable = Number.POSITIVE_INFINITY) {
-            return evaluate(slotId, resourceAvailable);
+        canCast(slotId, resourceAvailable) {
+            return evaluate(slotId, currentResource(resourceAvailable));
         },
-        cast(slotId, resourceAvailable = Number.POSITIVE_INFINITY) {
-            const result = evaluate(slotId, resourceAvailable);
+        cast(slotId, resourceAvailable) {
+            const result = evaluate(slotId, currentResource(resourceAvailable));
             if (!result.ok)
                 return result;
             const runtime = runtimes.get(slotId);
@@ -128,7 +140,10 @@ export function createAbilityKit(configs, options = {}) {
             for (const groupId of runtime.config.groups) {
                 groupRemaining.set(groupId, groupCooldowns.get(groupId) ?? 0);
             }
-            return { ok: true, slot: snapshotOf(runtime, resourceAvailable, groupBlockOf(runtime)) };
+            if (resourceAvailable === undefined && boundResource !== undefined && runtime.config.resourceCost > 0) {
+                boundResource.spend(runtime.config.resourceCost);
+            }
+            return { ok: true, slot: snapshotOf(runtime, currentResource(resourceAvailable), groupBlockOf(runtime)) };
         },
         tick(dtSeconds) {
             if (dtSeconds <= 0)

package/dist/combat/animationState.d.ts

@@ -23,9 +23,13 @@ export interface AnimationTickResult {
     exited: readonly FramePhase[];
     completed: boolean;
 }
+/** @internal */
 export declare function clipDurationMs(clip: AnimationClip): number;
+/** @internal */
 export declare function frameAtMs(clip: AnimationClip, elapsedMs: number): number;
+/** @internal */
 export declare function phasesAtFrame(clip: AnimationClip, frame: number): FramePhase[];
+/** @internal */
 export declare function activeRangeAtFrame(clip: AnimationClip, frame: number): FrameRange | null;
 export interface AnimationState {
     play(clipId: string): void;
@@ -44,4 +48,5 @@ export interface AnimationState {
 export interface AnimationStateConfig {
     clips: readonly AnimationClip[];
 }
+/** @internal */
 export declare function createAnimationState(config: AnimationStateConfig): AnimationState;

package/dist/combat/animationState.js

@@ -1,6 +1,8 @@
+/** @internal */
 export function clipDurationMs(clip) {
     return (clip.frames / clip.fps) * 1000;
 }
+/** @internal */
 export function frameAtMs(clip, elapsedMs) {
     const raw = (elapsedMs / 1000) * clip.fps;
     if (clip.loop === true) {
@@ -9,6 +11,7 @@ export function frameAtMs(clip, elapsedMs) {
     }
     return Math.min(raw, clip.frames);
 }
+/** @internal */
 export function phasesAtFrame(clip, frame) {
     const phases = [];
     for (const range of clip.ranges) {
@@ -18,6 +21,7 @@ export function phasesAtFrame(clip, frame) {
     }
     return phases;
 }
+/** @internal */
 export function activeRangeAtFrame(clip, frame) {
     for (const range of clip.ranges) {
         if (range.phase === "active" && frame >= range.from && frame < range.to)
@@ -25,6 +29,7 @@ export function activeRangeAtFrame(clip, frame) {
     }
     return null;
 }
+/** @internal */
 export function createAnimationState(config) {
     const clips = new Map(config.clips.map((clip) => [clip.id, clip]));
     let activeClip = null;