@jgengine/core 0.10.0 → 0.11.0

package/dist/area/areaEffectField.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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.
+ */
+import type { EntityPosition } from "../scene/entityStore.js";
+/**
+ * The area a source occupies this tick. `sphere` is first-class; `custom` leaves a seam for authored
+ * volumes and other shapes while still exposing a bounding sphere (`center`/`radius`) for the caller's
+ * broad-phase candidate query.
+ */
+export type AreaShape = {
+    readonly kind: "sphere";
+    readonly center: EntityPosition;
+    readonly radius: number;
+} | {
+    readonly kind: "custom";
+    /** Bounding-sphere center the caller's broad-phase `candidates` query is built from. */
+    readonly center: EntityPosition;
+    /** Bounding-sphere radius the caller's broad-phase `candidates` query is built from. */
+    readonly radius: number;
+    /** Authoritative containment test applied to each broad-phase candidate. */
+    readonly contains: (point: EntityPosition) => boolean;
+};
+/** Descriptor for one continuous area source; re-supplied each tick so its shape follows the emitter. */
+export interface AreaSourceSpec<P> {
+    /** Stable source id (the emitter). Re-using an id updates the descriptor and preserves membership. */
+    readonly id: string;
+    /** The source's area this tick — pass the emitter's live position so membership follows it. */
+    readonly shape: AreaShape;
+    /** Caller data describing what this source does (damage amount, heal, buff key, capture rate…). */
+    readonly payload: P;
+    /** Milliseconds between `refresh` edges emitted for each member; omit for enter/leave only. */
+    readonly refreshMs?: number;
+    /** Aggregation group key for stacking policies; defaults to the source id. */
+    readonly stackKey?: string;
+    /** When false the source keeps its descriptor but holds no members (current members `leave`). Default true. */
+    readonly enabled?: boolean;
+}
+/** Why a `leave` edge fired. */
+export type AreaLeaveReason = "exit" | "source-removed" | "disabled" | "cleared";
+/** The three membership edges a step can emit. */
+export type AreaEventKind = "enter" | "refresh" | "leave";
+/** One membership edge emitted by `step`, `removeSource`, or `clear`. */
+export interface AreaEffectEvent<P> {
+    readonly kind: AreaEventKind;
+    readonly sourceId: string;
+    readonly receiverId: string;
+    readonly stackKey: string;
+    readonly payload: P;
+    /** Number of refresh cadences crossed this step (>= 1 on `refresh`; a large dt can cross several). */
+    readonly ticks?: number;
+    /** Present only on `leave`. */
+    readonly reason?: AreaLeaveReason;
+}
+/** One active (source, receiver) membership — feed a receiver's list to a stacking policy. */
+export interface AreaMembership<P> {
+    readonly sourceId: string;
+    readonly receiverId: string;
+    readonly stackKey: string;
+    readonly payload: P;
+}
+/** Per-tick inputs the field needs to reconcile membership without scanning the world. */
+export interface AreaStepInput {
+    /** Milliseconds since the previous step; negative values are clamped to 0. */
+    readonly dtMs: number;
+    /** Bounded broad-phase: receiver ids possibly inside `shape` (e.g. `spatialIndex.querySphere`). */
+    readonly candidates: (shape: AreaShape) => Iterable<string>;
+    /** Precise receiver position; `undefined` means the receiver is gone (removed/dead) and is dropped. */
+    readonly positionOf: (receiverId: string) => EntityPosition | undefined;
+    /** Optional per-pair gate (team filter, immunity, line-of-sight already resolved by the caller). */
+    readonly eligible?: (sourceId: string, receiverId: string, payload: unknown) => boolean;
+}
+/** Serialized field state: source descriptors (minus their transient shape) and per-member refresh phase. */
+export interface AreaFieldState<P> {
+    readonly sources: {
+        readonly id: string;
+        readonly payload: P;
+        readonly refreshMs?: number;
+        readonly stackKey: string;
+        readonly enabled: boolean;
+    }[];
+    readonly memberships: {
+        readonly sourceId: string;
+        readonly receiverId: string;
+        readonly sinceRefreshMs: number;
+    }[];
+}
+/** Runtime handle tracking continuous area membership across ticks. */
+export interface AreaEffectField<P> {
+    /** Register or update a source (upsert by id); an update preserves existing membership and refresh phase. */
+    setSource(spec: AreaSourceSpec<P>): void;
+    /** Remove a source and return a `leave` (reason `source-removed`) for each of its members. */
+    removeSource(id: string): AreaEffectEvent<P>[];
+    hasSource(id: string): boolean;
+    sourceIds(): string[];
+    /** Reconcile every source against the receivers its `candidates` query returns; emit enter/refresh/leave. */
+    step(input: AreaStepInput): AreaEffectEvent<P>[];
+    /** Receiver ids currently inside `sourceId`. */
+    members(sourceId: string): string[];
+    isMember(sourceId: string, receiverId: string): boolean;
+    /** Every active membership across all sources. */
+    memberships(): AreaMembership<P>[];
+    /** Active memberships affecting a single receiver — the input to a stacking policy. */
+    membershipsOf(receiverId: string): AreaMembership<P>[];
+    /** Drop all sources and members; returns a `leave` (reason `cleared`) for each member. */
+    clear(): AreaEffectEvent<P>[];
+    /** Snapshot the persistent membership lifecycle for save/load; shapes are transient and re-supplied via `setSource`. */
+    serialize(): AreaFieldState<P>;
+}
+/**
+ * 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 declare function createAreaEffectField<P = unknown>(state?: AreaFieldState<P>): AreaEffectField<P>;

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

@@ -12,3 +12,4 @@ 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

@@ -12,3 +12,4 @@ 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;