@jgengine/core 0.10.0 → 0.12.0

package/dist/ai/spawnDirector.js

@@ -1,12 +1,14 @@
+import { randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+const BIAS_STRENGTH_EXPONENT = {
+    subtle: 0.5,
+    moderate: 1,
+    strong: 2,
+};
+function biasStrengthFromMagnitude(magnitude) {
+    return magnitude <= 0.5 ? "subtle" : magnitude >= 1.5 ? "strong" : "moderate";
+}
 const DEFAULT_MAX_SPAWNS_PER_TICK = 64;
 const DEFAULT_ALERT_DECAY = 0.1;
-function nextRandom(seed) {
-    const next = (seed + 0x6d2b79f5) | 0;
-    let t = Math.imul(next ^ (next >>> 15), 1 | next);
-    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
-    const value = ((t ^ (t >>> 14)) >>> 0) / 4294967296;
-    return [value, next];
-}
 function clamp01(value) {
     return value < 0 ? 0 : value > 1 ? 1 : value;
 }
@@ -20,7 +22,7 @@ export function createSpawnDirectorState(config) {
         alert: 0,
         spawnedThisWave: 0,
         spawnedTotal: 0,
-        rng: (config.seed ?? 1) | 0,
+        rng: randomSeedFrom(config.seed ?? 1),
         done: config.waves.length === 0,
     };
 }
@@ -56,7 +58,7 @@ function pickEntry(entries, wave, budget, rng) {
     }
     if (affordable.length === 0 || total <= 0)
         return null;
-    const [roll, nextRng] = nextRandom(rng);
+    const [roll, nextRng] = stepRandomSeed(rng);
     let cursor = roll * total;
     for (const entry of affordable) {
         cursor -= entry.weight ?? 1;
@@ -116,7 +118,7 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
         budget -= picked.entry.cost;
         const spawn = { entryId: picked.entry.id, cost: picked.entry.cost, wave };
         if (spawnPoints !== undefined && spawnPoints.length > 0) {
-            const [roll, nextRng] = nextRandom(rng);
+            const [roll, nextRng] = stepRandomSeed(rng);
             rng = nextRng;
             const bias = config.spawnPointBias ?? 1;
             const point = pickSpawnPoint({
@@ -124,7 +126,7 @@ export function advanceSpawnDirector(config, state, dt, ctx) {
                 avoid: playerPositions,
                 random: () => roll,
                 distanceBias: bias < 0 ? "far" : bias > 0 ? "near" : "none",
-                biasStrength: Math.abs(bias),
+                biasStrength: biasStrengthFromMagnitude(Math.abs(bias)),
             });
             if (point !== null) {
                 spawn.point = point;
@@ -150,19 +152,20 @@ export function pickSpawnPoint(optionsOrPoints, legacyPlayers = [], legacyOption
             avoid: legacyPlayers,
             random: () => legacyOptions.roll,
             distanceBias: legacyBias < 0 ? "far" : legacyBias > 0 ? "near" : "none",
-            biasStrength: Math.abs(legacyBias),
+            biasStrength: biasStrengthFromMagnitude(Math.abs(legacyBias)),
         };
     }
     else {
         options = optionsOrPoints;
     }
-    const { candidates, avoid = [], random, distanceBias = "near", biasStrength = 1 } = options;
+    const { candidates, avoid = [], random, distanceBias = "near", biasStrength = "moderate" } = options;
     if (candidates.length === 0)
         return null;
-    if (distanceBias === "none" || avoid.length === 0 || biasStrength === 0) {
+    if (distanceBias === "none" || avoid.length === 0) {
         return candidates[Math.min(candidates.length - 1, Math.floor(clamp01(random()) * candidates.length))];
     }
-    const exponent = distanceBias === "far" ? biasStrength : -biasStrength;
+    const strength = BIAS_STRENGTH_EXPONENT[biasStrength];
+    const exponent = distanceBias === "far" ? strength : -strength;
     const weights = [];
     let total = 0;
     for (const point of candidates) {

package/dist/ai/spawnPoint.d.ts

@@ -1,5 +1,7 @@
 import type { NavPoint } from "../nav/navGrid.js";
 import { type SpawnPointDistanceBias, type SpawnPointSelectionOptions } from "./spawnDirector.js";
 export type { SpawnPointDistanceBias, SpawnPointSelectionOptions };
-/** Selects a spawn point by game intent while keeping weighting mechanics internal. */
+/** Selects a spawn point by game intent while keeping weighting mechanics internal.
+ * @internal
+ */
 export declare function selectSpawnPoint(options: SpawnPointSelectionOptions): NavPoint | null;

package/dist/ai/spawnPoint.js

@@ -1,5 +1,7 @@
 import { pickSpawnPoint, } from "./spawnDirector.js";
-/** Selects a spawn point by game intent while keeping weighting mechanics internal. */
+/** Selects a spawn point by game intent while keeping weighting mechanics internal.
+ * @internal
+ */
 export function selectSpawnPoint(options) {
     return pickSpawnPoint(options);
 }

package/dist/ai/targetAcquisition.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Composable target acquisition: the "which enemy do I lock onto?" decision split into the
+ * independent concerns every aggro system tangles together — a bounded candidate provider, an
+ * eligibility filter, a per-pair acquisition envelope (dynamic range), a perception/LOS gate,
+ * scoring, deterministic tie-break, and retention hysteresis. This owns *policy*; threat, brains,
+ * and movement stay separate. Feed `candidates` a spatial-index query, never a full-world scan.
+ */
+/** A per-pair acquisition range: a static radius, or a function that varies range by pair. */
+export type AcquisitionEnvelope = number | ((selfId: string, candidateId: string) => number);
+/** Retention hysteresis that keeps an already-held target from flickering under churn. */
+export interface AcquisitionRetention {
+    /**
+     * A challenger's score must beat the held target's by at least this additive margin to steal
+     * acquisition. Keeps the lock stable when scores are near-tied. Default `0` (any win switches).
+     */
+    readonly switchMargin?: number;
+    /**
+     * The held target keeps acquisition out to `range * dropRangeScale` before it is dropped, so a
+     * target does not un-acquire the instant it steps past the acquisition edge. Default `1`.
+     */
+    readonly dropRangeScale?: number;
+}
+/**
+ * A fully composed acquisition policy. Every concern is an independent, injectable seam; the only
+ * required pieces are the bounded `candidates` provider and the `distance` metric. Omit the rest to
+ * fall back to the thin default — a static/unbounded range, everything eligible and perceptible,
+ * nearest-wins scoring, id tie-break, no hysteresis — which matches a plain proximity aggro radius.
+ */
+export interface AcquisitionPolicy {
+    /** Bounded candidate ids for `selfId` — wire a spatial-index query here, not a whole-world list. */
+    readonly candidates: (selfId: string) => Iterable<string>;
+    /** Distance self→candidate; `null` rejects the candidate (despawned / unmeasurable). */
+    readonly distance: (selfId: string, candidateId: string) => number | null;
+    /** Per-pair acquisition range (the dynamic envelope). Default `Infinity` (range-unbounded). */
+    readonly range?: AcquisitionEnvelope;
+    /** Eligibility filter run first — faction, alive, targetable, stealth, ownership. Default: all pass. */
+    readonly eligible?: (selfId: string, candidateId: string) => boolean;
+    /** Perception / line-of-sight gate run last (after range) because it is the costly check. */
+    readonly perceptible?: (selfId: string, candidateId: string, distance: number) => boolean;
+    /** Score of an in-range candidate; the highest wins. Default: nearest (`-distance`). */
+    readonly score?: (selfId: string, candidateId: string, distance: number) => number;
+    /** Deterministic tie-break when scores are equal (return <0 to prefer `a`). Default: id order. */
+    readonly tieBreak?: (a: string, b: string) => number;
+    /** Retention/hysteresis for an already-held target. Omit for no stickiness. */
+    readonly retention?: AcquisitionRetention;
+}
+/** Outcome of one acquisition pass. */
+export interface AcquisitionResult {
+    /** The chosen target, or `null` when nothing qualifies. */
+    readonly targetId: string | null;
+    /** True when `targetId` differs from the `held` target passed in (a fresh acquire or a switch). */
+    readonly changed: boolean;
+    /** Candidates that passed eligibility + range + perception this pass — a cheap tuning/metric signal. */
+    readonly considered: number;
+}
+/**
+ * Run one acquisition pass and pick the best target under `policy`. Pass the currently `held` target
+ * so retention hysteresis (`switchMargin`, `dropRangeScale`) can keep the lock stable; pass `null`
+ * for a cold acquire. Pure and allocation-light — the caller owns the held-target state.
+ *
+ * @capability target-acquisition composable candidate/eligibility/range/perception/score/tie-break/retention target pick
+ */
+export declare function acquireTarget(policy: AcquisitionPolicy, selfId: string, held?: string | null): AcquisitionResult;
+/** A stateful acquirer that holds the current target across passes — sugar over {@link acquireTarget}. */
+export interface TargetAcquirer {
+    /** Re-run acquisition for `selfId`, update the held target, and return it. */
+    acquire(selfId: string): string | null;
+    /** The held target without re-running acquisition. */
+    target(): string | null;
+    /** Candidates considered on the last {@link acquire} pass. */
+    considered(): number;
+    /** Force the held target — external override for taunt, script, or ownership handoff. */
+    hold(targetId: string | null): void;
+    /** Drop back to unacquired. */
+    clear(): void;
+}
+/**
+ * Wrap an {@link AcquisitionPolicy} in a small object that remembers the held target between passes,
+ * so callers get retention hysteresis for free without threading the previous target by hand. The
+ * only state is the held id (a string) — trivially serializable; round-trip it with {@link TargetAcquirer.hold}.
+ *
+ * @capability target-acquirer stateful held-target wrapper over an acquisition policy with retention
+ */
+export declare function createTargetAcquirer(policy: AcquisitionPolicy): TargetAcquirer;

package/dist/ai/targetAcquisition.js

@@ -0,0 +1,92 @@
+/**
+ * Composable target acquisition: the "which enemy do I lock onto?" decision split into the
+ * independent concerns every aggro system tangles together — a bounded candidate provider, an
+ * eligibility filter, a per-pair acquisition envelope (dynamic range), a perception/LOS gate,
+ * scoring, deterministic tie-break, and retention hysteresis. This owns *policy*; threat, brains,
+ * and movement stay separate. Feed `candidates` a spatial-index query, never a full-world scan.
+ */
+function resolveRange(range, selfId, candidateId) {
+    if (range === undefined)
+        return Number.POSITIVE_INFINITY;
+    return typeof range === "number" ? range : range(selfId, candidateId);
+}
+function defaultTieBreak(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * Run one acquisition pass and pick the best target under `policy`. Pass the currently `held` target
+ * so retention hysteresis (`switchMargin`, `dropRangeScale`) can keep the lock stable; pass `null`
+ * for a cold acquire. Pure and allocation-light — the caller owns the held-target state.
+ *
+ * @capability target-acquisition composable candidate/eligibility/range/perception/score/tie-break/retention target pick
+ */
+export function acquireTarget(policy, selfId, held = null) {
+    const tieBreak = policy.tieBreak ?? defaultTieBreak;
+    const dropScale = Math.max(0, policy.retention?.dropRangeScale ?? 1);
+    const switchMargin = policy.retention?.switchMargin ?? 0;
+    let considered = 0;
+    let bestId = null;
+    let bestScore = Number.NEGATIVE_INFINITY;
+    let heldSeen = false;
+    let heldScore = Number.NEGATIVE_INFINITY;
+    for (const candidateId of policy.candidates(selfId)) {
+        if (candidateId === selfId)
+            continue;
+        if (policy.eligible !== undefined && !policy.eligible(selfId, candidateId))
+            continue;
+        const d = policy.distance(selfId, candidateId);
+        if (d === null)
+            continue;
+        const range = resolveRange(policy.range, selfId, candidateId);
+        const effectiveRange = candidateId === held ? range * dropScale : range;
+        if (d > effectiveRange)
+            continue;
+        if (policy.perceptible !== undefined && !policy.perceptible(selfId, candidateId, d))
+            continue;
+        considered += 1;
+        const score = policy.score === undefined ? -d : policy.score(selfId, candidateId, d);
+        if (candidateId === held) {
+            heldSeen = true;
+            heldScore = score;
+        }
+        if (bestId === null ||
+            score > bestScore ||
+            (score === bestScore && tieBreak(candidateId, bestId) < 0)) {
+            bestId = candidateId;
+            bestScore = score;
+        }
+    }
+    // Retention: an in-range held target keeps the lock unless a challenger clears the switch margin.
+    if (heldSeen && held !== null && bestId !== held && bestScore < heldScore + switchMargin) {
+        return { targetId: held, changed: false, considered };
+    }
+    return { targetId: bestId, changed: bestId !== held, considered };
+}
+/**
+ * Wrap an {@link AcquisitionPolicy} in a small object that remembers the held target between passes,
+ * so callers get retention hysteresis for free without threading the previous target by hand. The
+ * only state is the held id (a string) — trivially serializable; round-trip it with {@link TargetAcquirer.hold}.
+ *
+ * @capability target-acquirer stateful held-target wrapper over an acquisition policy with retention
+ */
+export function createTargetAcquirer(policy) {
+    let held = null;
+    let considered = 0;
+    return {
+        acquire(selfId) {
+            const result = acquireTarget(policy, selfId, held);
+            held = result.targetId;
+            considered = result.considered;
+            return held;
+        },
+        target: () => held,
+        considered: () => considered,
+        hold(targetId) {
+            held = targetId;
+        },
+        clear() {
+            held = null;
+            considered = 0;
+        },
+    };
+}

package/dist/anim/easing.d.ts

@@ -1,14 +1,33 @@
 export type Easing = (t: number) => number;
+/** Linearly interpolate from `from` to `to` by fraction `t` (unclamped).
+ * @internal
+ */
 export declare function lerp(from: number, to: number, t: number): number;
+/** Constrain `t` to the unit range `[0, 1]`.
+ * @internal
+ */
 export declare function clamp01(t: number): number;
+/** Smooth Hermite interpolation of `t` across `[0, 1]`, easing both ends.
+ * @internal
+ */
 export declare function smoothstep(t: number): number;
+/** @internal */
 export declare function easeInQuad(t: number): number;
+/** @internal */
 export declare function easeOutQuad(t: number): number;
+/** @internal */
 export declare function easeInOutQuad(t: number): number;
+/** @internal */
 export declare function easeInCubic(t: number): number;
+/** @internal */
 export declare function easeOutCubic(t: number): number;
+/** @internal */
 export declare function easeInOutCubic(t: number): number;
+/** @internal */
 export declare function easeOutBack(t: number): number;
+/** @internal */
 export declare function easeOutElastic(t: number): number;
+/** @internal */
 export declare function tween(from: number, to: number, t: number, easing?: Easing): number;
+/** @internal */
 export declare function timedProgress(startedAt: number, now: number, durationMs: number): number;

package/dist/anim/easing.js

@@ -1,53 +1,72 @@
+/** Linearly interpolate from `from` to `to` by fraction `t` (unclamped).
+ * @internal
+ */
 export function lerp(from, to, t) {
     return from + (to - from) * t;
 }
+/** Constrain `t` to the unit range `[0, 1]`.
+ * @internal
+ */
 export function clamp01(t) {
     return t < 0 ? 0 : t > 1 ? 1 : t;
 }
+/** Smooth Hermite interpolation of `t` across `[0, 1]`, easing both ends.
+ * @internal
+ */
 export function smoothstep(t) {
     const c = clamp01(t);
     return c * c * (3 - 2 * c);
 }
+/** @internal */
 export function easeInQuad(t) {
     const c = clamp01(t);
     return c * c;
 }
+/** @internal */
 export function easeOutQuad(t) {
     const c = clamp01(t);
     return 1 - (1 - c) * (1 - c);
 }
+/** @internal */
 export function easeInOutQuad(t) {
     const c = clamp01(t);
     return c < 0.5 ? 2 * c * c : 1 - ((-2 * c + 2) ** 2) / 2;
 }
+/** @internal */
 export function easeInCubic(t) {
     const c = clamp01(t);
     return c * c * c;
 }
+/** @internal */
 export function easeOutCubic(t) {
     const c = clamp01(t);
     return 1 - (1 - c) ** 3;
 }
+/** @internal */
 export function easeInOutCubic(t) {
     const c = clamp01(t);
     return c < 0.5 ? 4 * c * c * c : 1 - ((-2 * c + 2) ** 3) / 2;
 }
 const BACK_OVERSHOOT = 1.70158;
+/** @internal */
 export function easeOutBack(t) {
     const c = clamp01(t);
     const s = BACK_OVERSHOOT + 1;
     return 1 + s * (c - 1) ** 3 + BACK_OVERSHOOT * (c - 1) ** 2;
 }
 const ELASTIC_PERIOD = (2 * Math.PI) / 3;
+/** @internal */
 export function easeOutElastic(t) {
     const c = clamp01(t);
     if (c === 0 || c === 1)
         return c;
     return 2 ** (-10 * c) * Math.sin((c * 10 - 0.75) * ELASTIC_PERIOD) + 1;
 }
+/** @internal */
 export function tween(from, to, t, easing = smoothstep) {
     return lerp(from, to, easing(clamp01(t)));
 }
+/** @internal */
 export function timedProgress(startedAt, now, durationMs) {
     if (durationMs <= 0)
         return now >= startedAt ? 1 : 0;

package/dist/anim/oscillator.d.ts

@@ -0,0 +1,12 @@
+/** Sawtooth ramp: rises 0→1 over each `period` then resets, for looping sweeps and scrolls.
+ * @internal
+ */
+export declare function sawWave(time: number, period: number): number;
+/** Triangle wave: ramps 0→1→0 across each `period`, for patrols, searchlights, and pulsing glows.
+ * @internal
+ */
+export declare function triangleWave(time: number, period: number): number;
+/** Ping-pong a value across `[0, length]`, bouncing at each edge — the index/position analog of {@link triangleWave}.
+ * @internal
+ */
+export declare function pingPong(value: number, length: number): number;

package/dist/anim/oscillator.js

@@ -0,0 +1,25 @@
+/** Sawtooth ramp: rises 0→1 over each `period` then resets, for looping sweeps and scrolls.
+ * @internal
+ */
+export function sawWave(time, period) {
+    if (!(period > 0))
+        return 0;
+    const phase = ((time % period) + period) % period;
+    return phase / period;
+}
+/** Triangle wave: ramps 0→1→0 across each `period`, for patrols, searchlights, and pulsing glows.
+ * @internal
+ */
+export function triangleWave(time, period) {
+    const up = sawWave(time, period);
+    return up < 0.5 ? up * 2 : 2 - up * 2;
+}
+/** Ping-pong a value across `[0, length]`, bouncing at each edge — the index/position analog of {@link triangleWave}.
+ * @internal
+ */
+export function pingPong(value, length) {
+    if (!(length > 0))
+        return 0;
+    const t = ((value % (length * 2)) + length * 2) % (length * 2);
+    return t <= length ? t : length * 2 - t;
+}

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>;