@jgengine/core 0.10.0 → 0.11.0

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;

package/dist/combat/breakMeters.d.ts

@@ -11,6 +11,11 @@ export interface StaggerMeter {
     recover(): void;
     tick(dtSeconds: number): void;
 }
+/**
+ * Build a stagger/poise gauge from landed hits toward a break threshold that staggers the target.
+ *
+ * @capability stagger-meter build toward a stagger/poise-break threshold from landed hits
+ */
 export declare function createStaggerMeter(config: StaggerMeterConfig): StaggerMeter;
 export interface BuildupMeterConfig {
     status: string;
@@ -29,4 +34,9 @@ export interface BuildupMeter {
     fraction(): number;
     tick(dtSeconds: number): void;
 }
+/**
+ * Accumulate an ailment buildup — bleed, freeze, poison — that procs a status once it fills, then decays.
+ *
+ * @capability stagger-meter accumulate an ailment buildup (bleed, freeze) until it procs
+ */
 export declare function createBuildupMeter(config: BuildupMeterConfig): BuildupMeter;

package/dist/combat/breakMeters.js

@@ -1,4 +1,9 @@
 import { createAccumulatorMeter } from "../stats/accumulatorMeter.js";
+/**
+ * Build a stagger/poise gauge from landed hits toward a break threshold that staggers the target.
+ *
+ * @capability stagger-meter build toward a stagger/poise-break threshold from landed hits
+ */
 export function createStaggerMeter(config) {
     const meter = createAccumulatorMeter({
         max: config.max,
@@ -27,6 +32,11 @@ export function createStaggerMeter(config) {
         },
     };
 }
+/**
+ * Accumulate an ailment buildup — bleed, freeze, poison — that procs a status once it fills, then decays.
+ *
+ * @capability stagger-meter accumulate an ailment buildup (bleed, freeze) until it procs
+ */
 export function createBuildupMeter(config) {
     const meter = createAccumulatorMeter({
         max: config.max,

package/dist/combat/castRunner.d.ts

@@ -37,4 +37,9 @@ export interface CastRunner {
     /** Advance by `dtSeconds`; `movedDistance` accumulates toward the config's `moveTolerance`. */
     tick(dtSeconds: number, movedDistance?: number): CastEvent | null;
 }
+/**
+ * Run a channeled cast/charge timer that movement or damage can interrupt — the spell cast bar.
+ *
+ * @capability cast-bar run a channeled cast timer that movement or damage can interrupt
+ */
 export declare function createCastRunner(): CastRunner;

package/dist/combat/castRunner.js

@@ -1,4 +1,9 @@
 const DEFAULT_MOVE_TOLERANCE = 0.04;
+/**
+ * Run a channeled cast/charge timer that movement or damage can interrupt — the spell cast bar.
+ *
+ * @capability cast-bar run a channeled cast timer that movement or damage can interrupt
+ */
 export function createCastRunner() {
     let active = null;
     function snapshot() {

package/dist/combat/comboPoints.d.ts

@@ -11,4 +11,9 @@ export interface ComboPoints {
     expiresIn(): number | null;
     clear(): void;
 }
+/**
+ * Build and spend finisher points — the combo-point economy behind rogue-style builders and spenders.
+ *
+ * @capability combo-points build up and spend finisher/combo points
+ */
 export declare function createComboPoints(config: ComboPointsConfig): ComboPoints;

package/dist/combat/comboPoints.js

@@ -1,3 +1,8 @@
+/**
+ * Build and spend finisher points — the combo-point economy behind rogue-style builders and spenders.
+ *
+ * @capability combo-points build up and spend finisher/combo points
+ */
 export function createComboPoints(config) {
     const max = config.max;
     const expireAfterSeconds = config.expireAfterSeconds;

package/dist/combat/comboString.d.ts

@@ -32,4 +32,9 @@ export interface ComboRunner {
     request(stepId: string, stance?: string): AdvanceComboResult;
     reset(): void;
 }
+/**
+ * Advance a chained melee string from timed inputs, tracking the current step and its cancel/continue windows.
+ *
+ * @capability combo-chain advance a chained melee string from timed button inputs
+ */
 export declare function createComboRunner(combo: ComboString, anim: AnimationState): ComboRunner;

package/dist/combat/comboString.js

@@ -32,6 +32,11 @@ export function advanceCombo(input) {
     }
     return { accepted: true, step: requested };
 }
+/**
+ * Advance a chained melee string from timed inputs, tracking the current step and its cancel/continue windows.
+ *
+ * @capability combo-chain advance a chained melee string from timed button inputs
+ */
 export function createComboRunner(combo, anim) {
     let current = null;
     return {

package/dist/combat/damageInterceptors.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Ordered, inspectable damage-resolution interception (#931).
+ *
+ * A pending damage application flows through an ordered list of interceptors
+ * BEFORE lethality is resolved. Each interceptor may pass, transform, clamp,
+ * redirect, split, defer, or reject the application, and every decision is
+ * recorded as provenance so combat resolution stays auditable — no hidden
+ * callbacks. Invulnerability, i-frames, and anti-one-shot clamps are ordinary
+ * interceptors installed and removed by state transitions, not a boss branch.
+ *
+ * All state is serializable (`Record<string, number>` maps), all randomness is
+ * absent (pure), and work is bounded by `MAX_INTERCEPT_STEPS` so split/redirect
+ * can never recurse without limit.
+ */
+/** A damage application queued for resolution against a target. `amount` is always non-negative; healing is a separate concern. */
+export interface PendingDamage {
+    /** Instance receiving the damage. */
+    target: string;
+    /** Instance dealing the damage. */
+    source: string;
+    /** Damage magnitude, non-negative. */
+    amount: number;
+    /** Optional caller tag (weapon id, effect id, channel) carried through for provenance and downstream routing. */
+    tag?: string;
+}
+/**
+ * What an interceptor decides to do with the pending application it was handed.
+ * `split` parts continue at the NEXT interceptor (never re-entering the splitter),
+ * which is what keeps the pipeline bounded and recursion-free.
+ */
+export type InterceptDecision = {
+    kind: "pass";
+} | {
+    kind: "transform";
+    amount: number;
+    note?: string;
+} | {
+    kind: "clamp";
+    max: number;
+    note?: string;
+} | {
+    kind: "redirect";
+    target: string;
+    note?: string;
+} | {
+    kind: "split";
+    parts: readonly PendingDamage[];
+    note?: string;
+} | {
+    kind: "defer";
+    note?: string;
+} | {
+    kind: "reject";
+    note?: string;
+};
+/** Read-only context an interceptor may consult — deterministic clock and optional health lookup for HP-relative policies. */
+export interface InterceptContext {
+    /** Deterministic current time in milliseconds; interceptors never read a wall clock. */
+    nowMs: number;
+    /** Optional current/max pool lookup for the target, enabling HP-relative clamps like anti-one-shot. */
+    healthOf?(target: string): {
+        current: number;
+        max: number;
+    } | undefined;
+}
+/** A named stage in the interception pipeline. The `id` is stable so it can be installed, removed, and cited in provenance. */
+export interface DamageInterceptor {
+    /** Stable identifier used for install/remove and provenance. */
+    id: string;
+    /** Decide what happens to `pending`; must be deterministic given `ctx`. */
+    intercept(pending: PendingDamage, ctx: InterceptContext): InterceptDecision;
+}
+/** One row of provenance: which interceptor acted, what it decided, and the amount before/after it acted. */
+export interface InterceptRecord {
+    interceptor: string;
+    kind: InterceptDecision["kind"];
+    target: string;
+    before: number;
+    after: number;
+    note?: string;
+}
+/** The outcome of running a pending application through the pipeline: what to apply, what was deferred, and why each value changed. */
+export interface DamageResolution {
+    /** Final applications to commit (0..n after splits/rejections). */
+    applications: PendingDamage[];
+    /** Applications held back by a `defer` decision for the caller to resubmit later. */
+    deferred: PendingDamage[];
+    /** Ordered record of every interceptor decision. */
+    provenance: InterceptRecord[];
+}
+/** Upper bound on interceptor evaluations for a single resolution; guards against runaway `split`/`redirect` loops. */
+export declare const MAX_INTERCEPT_STEPS = 256;
+/**
+ * Run one pending damage application through an ordered interceptor list before
+ * lethality resolves, returning the final applications, any deferred ones, and
+ * full provenance. Pure and deterministic; bounded by `MAX_INTERCEPT_STEPS`.
+ *
+ * @capability damage-interception intercept a pending damage application before lethal resolution with ordered, inspectable stages
+ */
+export declare function resolveDamage(interceptors: readonly DamageInterceptor[], pending: PendingDamage, ctx: InterceptContext): DamageResolution;
+/** A mutable ordered interceptor chain that transitions can install into and remove from at runtime. */
+export interface DamagePipeline {
+    /** Append an interceptor, or replace an existing one with the same `id` in place. */
+    install(interceptor: DamageInterceptor): void;
+    /** Remove the interceptor with `id`; returns whether one was removed. */
+    remove(id: string): boolean;
+    /** Whether an interceptor with `id` is currently installed. */
+    has(id: string): boolean;
+    /** Installed interceptor ids in evaluation order (serializable install record). */
+    interceptorIds(): string[];
+    /** Resolve one pending application through the current chain. */
+    resolve(pending: PendingDamage, ctx: InterceptContext): DamageResolution;
+}
+/**
+ * Create a mutable damage interception chain that state transitions install into
+ * and remove from — e.g. add an invulnerability interceptor on phase enter and
+ * drop it on phase exit. Evaluation order is install order.
+ *
+ * @capability damage-pipeline install and remove ordered damage interceptors that transitions toggle at runtime
+ */
+export declare function createDamagePipeline(initial?: readonly DamageInterceptor[]): DamagePipeline;
+/** Caller data for a flat per-hit damage cap. */
+export interface DamageClampConfig {
+    /** Interceptor id; defaults to `"damage-clamp"`. */
+    id?: string;
+    /** Maximum damage a single application may carry. */
+    maxPerHit: number;
+}
+/**
+ * A stateless interceptor that caps any single application at `maxPerHit`.
+ *
+ * @capability damage-clamp cap incoming damage per hit at a configured maximum
+ */
+export declare function createDamageClamp(config: DamageClampConfig): DamageInterceptor;
+/** A per-target timed immunity policy: an interceptor plus grant/query/serialize controls, toggled by transitions. */
+export interface ImmunityWindow {
+    /** The interceptor to install; rejects damage to any target whose immunity has not expired. */
+    interceptor: DamageInterceptor;
+    /** Make `target` immune until `untilMs` (extends, never shortens, an existing window). */
+    grant(target: string, untilMs: number): void;
+    /** Make `target` immune for `durationMs` starting at `nowMs`. */
+    grantFor(target: string, nowMs: number, durationMs: number): void;
+    /** Whether `target` is immune at `nowMs`. */
+    active(target: string, nowMs: number): boolean;
+    /** Drop `target`'s immunity immediately. */
+    clear(target: string): void;
+    /** Drop every window that has expired at `nowMs` (bounded housekeeping for save size). */
+    clearExpired(nowMs: number): void;
+    /** Serializable snapshot: target → expiry ms. */
+    snapshot(): Record<string, number>;
+    /** Restore from a snapshot. */
+    restore(snap: Record<string, number>): void;
+}
+/**
+ * A per-target immunity/invulnerability window as an ordinary damage policy —
+ * granted and cleared by state transitions (i-frames, phase invuln), rejecting
+ * damage while active. Deterministic (time is passed in) and serializable.
+ *
+ * @capability immunity-window reject damage during a per-target invulnerability window installed by transitions
+ */
+export declare function createImmunityWindow(id?: string): ImmunityWindow;
+/** Caller data for the anti-one-shot composition: "cannot cross lethal while above X, leave Y, then recover for Z". */
+export interface AntiOneShotConfig {
+    /** Interceptor id; defaults to `"anti-one-shot"`. */
+    id?: string;
+    /** Only intervene when the target's HP fraction is strictly above this (X). Below it, lethal hits pass. */
+    guardAboveFraction: number;
+    /** HP fraction to leave the target at after an intercepted near-lethal hit (Y). */
+    leaveFraction: number;
+    /** Immunity granted after an intercepted hit, in milliseconds (Z). */
+    recoverMs: number;
+}
+/** The anti-one-shot policy: an interceptor plus its serializable recovery-immunity state. */
+export interface AntiOneShotPolicy {
+    /** The interceptor to install ahead of lethal resolution. */
+    interceptor: DamageInterceptor;
+    /** Whether `target` is in the post-hit recovery i-frame at `nowMs`. */
+    immune(target: string, nowMs: number): boolean;
+    /** Serializable snapshot: target → recovery expiry ms. */
+    snapshot(): Record<string, number>;
+    /** Restore from a snapshot. */
+    restore(snap: Record<string, number>): void;
+}
+/**
+ * Compose a reusable anti-one-shot / chip-guard clamp from caller data:
+ * while above `guardAboveFraction` a hit cannot drop the target below
+ * `leaveFraction`, and after such a save the target gets `recoverMs` of
+ * immunity. Below the guard fraction, lethal hits pass unchanged.
+ *
+ * @capability anti-one-shot clamp a near-lethal hit to leave a health floor then grant recovery immunity
+ */
+export declare function createAntiOneShotPolicy(config: AntiOneShotConfig): AntiOneShotPolicy;

package/dist/combat/damageInterceptors.js

@@ -0,0 +1,251 @@
+/**
+ * Ordered, inspectable damage-resolution interception (#931).
+ *
+ * A pending damage application flows through an ordered list of interceptors
+ * BEFORE lethality is resolved. Each interceptor may pass, transform, clamp,
+ * redirect, split, defer, or reject the application, and every decision is
+ * recorded as provenance so combat resolution stays auditable — no hidden
+ * callbacks. Invulnerability, i-frames, and anti-one-shot clamps are ordinary
+ * interceptors installed and removed by state transitions, not a boss branch.
+ *
+ * All state is serializable (`Record<string, number>` maps), all randomness is
+ * absent (pure), and work is bounded by `MAX_INTERCEPT_STEPS` so split/redirect
+ * can never recurse without limit.
+ */
+/** Upper bound on interceptor evaluations for a single resolution; guards against runaway `split`/`redirect` loops. */
+export const MAX_INTERCEPT_STEPS = 256;
+/**
+ * Run one pending damage application through an ordered interceptor list before
+ * lethality resolves, returning the final applications, any deferred ones, and
+ * full provenance. Pure and deterministic; bounded by `MAX_INTERCEPT_STEPS`.
+ *
+ * @capability damage-interception intercept a pending damage application before lethal resolution with ordered, inspectable stages
+ */
+export function resolveDamage(interceptors, pending, ctx) {
+    const applications = [];
+    const deferred = [];
+    const provenance = [];
+    const queue = [{ pending: normalize(pending), next: 0 }];
+    let steps = 0;
+    while (queue.length > 0) {
+        if (++steps > MAX_INTERCEPT_STEPS)
+            break;
+        const item = queue.shift();
+        if (item === undefined)
+            break;
+        if (item.next >= interceptors.length) {
+            applications.push(item.pending);
+            continue;
+        }
+        const interceptor = interceptors[item.next];
+        if (interceptor === undefined) {
+            applications.push(item.pending);
+            continue;
+        }
+        const current = item.pending;
+        const interceptorId = interceptor.id;
+        const decision = interceptor.intercept(current, ctx);
+        const before = current.amount;
+        function record(after, note) {
+            const row = {
+                interceptor: interceptorId,
+                kind: decision.kind,
+                target: current.target,
+                before,
+                after,
+            };
+            if (note !== undefined)
+                row.note = note;
+            provenance.push(row);
+        }
+        const nextIndex = item.next + 1;
+        switch (decision.kind) {
+            case "pass":
+                record(before);
+                queue.push({ pending: current, next: nextIndex });
+                break;
+            case "transform": {
+                const amount = Math.max(0, decision.amount);
+                record(amount, decision.note);
+                queue.push({ pending: { ...current, amount }, next: nextIndex });
+                break;
+            }
+            case "clamp": {
+                const amount = Math.min(current.amount, Math.max(0, decision.max));
+                record(amount, decision.note);
+                queue.push({ pending: { ...current, amount }, next: nextIndex });
+                break;
+            }
+            case "redirect":
+                record(before, decision.note);
+                queue.push({ pending: { ...current, target: decision.target }, next: nextIndex });
+                break;
+            case "split":
+                record(before, decision.note);
+                for (const part of decision.parts)
+                    queue.push({ pending: normalize(part), next: nextIndex });
+                break;
+            case "defer":
+                record(before, decision.note);
+                deferred.push(current);
+                break;
+            case "reject":
+                record(0, decision.note);
+                break;
+        }
+    }
+    return { applications, deferred, provenance };
+}
+function normalize(pending) {
+    return pending.amount >= 0 ? pending : { ...pending, amount: 0 };
+}
+/**
+ * Create a mutable damage interception chain that state transitions install into
+ * and remove from — e.g. add an invulnerability interceptor on phase enter and
+ * drop it on phase exit. Evaluation order is install order.
+ *
+ * @capability damage-pipeline install and remove ordered damage interceptors that transitions toggle at runtime
+ */
+export function createDamagePipeline(initial) {
+    const interceptors = initial === undefined ? [] : [...initial];
+    function indexOf(id) {
+        return interceptors.findIndex((entry) => entry.id === id);
+    }
+    return {
+        install(interceptor) {
+            const idx = indexOf(interceptor.id);
+            if (idx >= 0)
+                interceptors[idx] = interceptor;
+            else
+                interceptors.push(interceptor);
+        },
+        remove(id) {
+            const idx = indexOf(id);
+            if (idx < 0)
+                return false;
+            interceptors.splice(idx, 1);
+            return true;
+        },
+        has(id) {
+            return indexOf(id) >= 0;
+        },
+        interceptorIds() {
+            return interceptors.map((entry) => entry.id);
+        },
+        resolve(pending, ctx) {
+            return resolveDamage(interceptors, pending, ctx);
+        },
+    };
+}
+/**
+ * A stateless interceptor that caps any single application at `maxPerHit`.
+ *
+ * @capability damage-clamp cap incoming damage per hit at a configured maximum
+ */
+export function createDamageClamp(config) {
+    const id = config.id ?? "damage-clamp";
+    return {
+        id,
+        intercept(pending) {
+            if (pending.amount <= config.maxPerHit)
+                return { kind: "pass" };
+            return { kind: "clamp", max: config.maxPerHit, note: `capped at ${config.maxPerHit}` };
+        },
+    };
+}
+/**
+ * A per-target immunity/invulnerability window as an ordinary damage policy —
+ * granted and cleared by state transitions (i-frames, phase invuln), rejecting
+ * damage while active. Deterministic (time is passed in) and serializable.
+ *
+ * @capability immunity-window reject damage during a per-target invulnerability window installed by transitions
+ */
+export function createImmunityWindow(id = "immunity") {
+    const until = new Map();
+    const window = {
+        interceptor: {
+            id,
+            intercept(pending, ctx) {
+                const expiry = until.get(pending.target);
+                if (expiry !== undefined && ctx.nowMs < expiry)
+                    return { kind: "reject", note: `immune until ${expiry}` };
+                return { kind: "pass" };
+            },
+        },
+        grant(target, untilMs) {
+            const prev = until.get(target);
+            until.set(target, prev === undefined ? untilMs : Math.max(prev, untilMs));
+        },
+        grantFor(target, nowMs, durationMs) {
+            window.grant(target, nowMs + durationMs);
+        },
+        active(target, nowMs) {
+            const expiry = until.get(target);
+            return expiry !== undefined && nowMs < expiry;
+        },
+        clear(target) {
+            until.delete(target);
+        },
+        clearExpired(nowMs) {
+            for (const [target, expiry] of [...until])
+                if (nowMs >= expiry)
+                    until.delete(target);
+        },
+        snapshot() {
+            return Object.fromEntries(until);
+        },
+        restore(snap) {
+            until.clear();
+            for (const [target, expiry] of Object.entries(snap))
+                until.set(target, expiry);
+        },
+    };
+    return window;
+}
+/**
+ * Compose a reusable anti-one-shot / chip-guard clamp from caller data:
+ * while above `guardAboveFraction` a hit cannot drop the target below
+ * `leaveFraction`, and after such a save the target gets `recoverMs` of
+ * immunity. Below the guard fraction, lethal hits pass unchanged.
+ *
+ * @capability anti-one-shot clamp a near-lethal hit to leave a health floor then grant recovery immunity
+ */
+export function createAntiOneShotPolicy(config) {
+    const id = config.id ?? "anti-one-shot";
+    const immuneUntil = new Map();
+    const policy = {
+        interceptor: {
+            id,
+            intercept(pending, ctx) {
+                const expiry = immuneUntil.get(pending.target);
+                if (expiry !== undefined && ctx.nowMs < expiry)
+                    return { kind: "reject", note: "anti-one-shot i-frame" };
+                const hp = ctx.healthOf?.(pending.target);
+                if (hp === undefined || hp.max <= 0)
+                    return { kind: "pass" };
+                const fraction = hp.current / hp.max;
+                if (fraction <= config.guardAboveFraction)
+                    return { kind: "pass" };
+                const floor = config.leaveFraction * hp.max;
+                if (hp.current - pending.amount >= floor)
+                    return { kind: "pass" };
+                const clamped = Math.max(0, hp.current - floor);
+                immuneUntil.set(pending.target, ctx.nowMs + config.recoverMs);
+                return { kind: "clamp", max: clamped, note: `anti-one-shot: leave ${floor}, recover ${config.recoverMs}ms` };
+            },
+        },
+        immune(target, nowMs) {
+            const expiry = immuneUntil.get(target);
+            return expiry !== undefined && nowMs < expiry;
+        },
+        snapshot() {
+            return Object.fromEntries(immuneUntil);
+        },
+        restore(snap) {
+            immuneUntil.clear();
+            for (const [target, expiry] of Object.entries(snap))
+                immuneUntil.set(target, expiry);
+        },
+    };
+    return policy;
+}