@jgengine/core 0.10.0 → 0.12.0

package/dist/game/tribe.js

@@ -0,0 +1,432 @@
+const DEFAULT_LOG_CAP = 128;
+function assetKey(kind, id) {
+    // Length-prefix the kind so the key is collision-free even when `kind` or `id`
+    // contains the delimiter (e.g. kind "ab"+id "c" must not collide with "a"+"bc").
+    return `${kind.length}:${kind}:${id}`;
+}
+function toRankRuntime(def) {
+    return {
+        id: def.id,
+        name: def.name,
+        level: def.level,
+        permissions: new Set(def.permissions ?? []),
+        bypass: def.bypass === true,
+    };
+}
+function rankToDef(rank) {
+    return {
+        id: rank.id,
+        name: rank.name,
+        level: rank.level,
+        ...(rank.permissions.size > 0 ? { permissions: [...rank.permissions] } : {}),
+        ...(rank.bypass ? { bypass: true } : {}),
+    };
+}
+/**
+ * Create a shared-ownership group aggregate (tribe / guild / clan / company). Members hold a
+ * {@link TribeRankDef rank} whose configurable permission slugs gate management actions and access
+ * to group-owned assets, while personally-owned assets stay with their member — and follow them out
+ * when they leave. Group↔group {@link Tribe.addAlly alliances} resolve allied tribes as friendly, and
+ * every membership / ownership / alliance change lands in a bounded ring-buffer {@link Tribe.events log}.
+ * All state is plain JSON via {@link Tribe.snapshot}/{@link Tribe.hydrate}; timestamps come from an
+ * injected clock for determinism. Compose many tribes with {@link createTribeRegistry} for mutual
+ * alliances and cross-member relation lookups.
+ *
+ * @capability tribe-group shared-ownership group (tribe/guild/clan) with ranked permissions, group vs personal assets, alliances, and a bounded event log
+ */
+export function createTribe(config) {
+    const now = config.now ?? Date.now;
+    if (config.ranks.length === 0)
+        throw new Error("tribe requires at least one rank");
+    const ranks = new Map();
+    let lowest;
+    let highest;
+    for (const def of config.ranks) {
+        if (ranks.has(def.id))
+            throw new Error(`duplicate rank id "${def.id}"`);
+        const rank = toRankRuntime(def);
+        ranks.set(rank.id, rank);
+        if (lowest === undefined || rank.level < lowest.level)
+            lowest = rank;
+        if (highest === undefined || rank.level > highest.level)
+            highest = rank;
+    }
+    const resolveRankId = (id, fallback) => {
+        if (id === undefined)
+            return fallback.id;
+        if (!ranks.has(id))
+            throw new Error(`unknown rank id "${id}"`);
+        return id;
+    };
+    let defaultRankId = resolveRankId(config.defaultRankId, lowest);
+    let founderRankId = resolveRankId(config.founderRankId, highest);
+    let logCap = Math.max(1, Math.floor(config.logCap ?? DEFAULT_LOG_CAP));
+    let founderId = config.founderId;
+    const members = new Map();
+    const assets = new Map();
+    const allies = new Set();
+    const eventLog = [];
+    let eventSeq = 0;
+    members.set(founderId, { id: founderId, rankId: founderRankId, joinedAt: now() });
+    function rankRuntimeOf(memberId) {
+        const member = members.get(memberId);
+        if (member === undefined)
+            return null;
+        return ranks.get(member.rankId) ?? null;
+    }
+    function isAdmin(memberId) {
+        if (memberId === founderId && members.has(memberId))
+            return true;
+        return rankRuntimeOf(memberId)?.bypass ?? false;
+    }
+    function can(memberId, permission) {
+        if (!members.has(memberId))
+            return false;
+        if (isAdmin(memberId))
+            return true;
+        return rankRuntimeOf(memberId)?.permissions.has(permission) ?? false;
+    }
+    function levelOf(memberId) {
+        if (isAdmin(memberId))
+            return Number.POSITIVE_INFINITY;
+        return rankRuntimeOf(memberId)?.level ?? Number.NEGATIVE_INFINITY;
+    }
+    function log(type, fields) {
+        eventSeq += 1;
+        const event = {
+            seq: eventSeq,
+            type,
+            at: now(),
+            ...(fields.actor === undefined ? {} : { actor: fields.actor }),
+            ...(fields.subject === undefined ? {} : { subject: fields.subject }),
+            ...(fields.tribeId === undefined ? {} : { tribeId: fields.tribeId }),
+            ...(fields.rankId === undefined ? {} : { rankId: fields.rankId }),
+            ...(fields.assetKind === undefined ? {} : { assetKind: fields.assetKind }),
+            ...(fields.assetId === undefined ? {} : { assetId: fields.assetId }),
+        };
+        eventLog.push(event);
+        if (eventLog.length > logCap)
+            eventLog.shift();
+    }
+    function dropPersonalAssets(memberId) {
+        for (const [key, asset] of assets) {
+            if (asset.ownerId === memberId)
+                assets.delete(key);
+        }
+    }
+    return {
+        id: config.id,
+        founderId: () => founderId,
+        hasMember: (memberId) => members.has(memberId),
+        memberIds: () => [...members.keys()],
+        rankOf(memberId) {
+            const rank = rankRuntimeOf(memberId);
+            return rank === null ? null : rankToDef(rank);
+        },
+        can,
+        isAdmin,
+        addMember(actorId, memberId, rankId) {
+            if (!members.has(actorId))
+                return { reason: "actor is not a member" };
+            if (!can(actorId, "invite"))
+                return { reason: "missing invite permission" };
+            if (members.has(memberId))
+                return { reason: "already a member" };
+            const targetRankId = rankId ?? defaultRankId;
+            const targetRank = ranks.get(targetRankId);
+            if (targetRank === undefined)
+                return { reason: `unknown rank id "${targetRankId}"` };
+            if (!isAdmin(actorId) && targetRank.level >= levelOf(actorId)) {
+                return { reason: "cannot invite at or above your own rank" };
+            }
+            members.set(memberId, { id: memberId, rankId: targetRankId, joinedAt: now() });
+            log("member-added", { actor: actorId, subject: memberId, rankId: targetRankId });
+            return null;
+        },
+        removeMember(actorId, memberId) {
+            if (!members.has(actorId))
+                return { reason: "actor is not a member" };
+            if (actorId === memberId)
+                return { reason: "use leave to remove yourself" };
+            if (!members.has(memberId))
+                return { reason: "not a member" };
+            if (memberId === founderId)
+                return { reason: "cannot remove the founder" };
+            if (!can(actorId, "kick"))
+                return { reason: "missing kick permission" };
+            if (levelOf(actorId) <= levelOf(memberId))
+                return { reason: "cannot manage an equal or higher rank" };
+            members.delete(memberId);
+            dropPersonalAssets(memberId);
+            log("member-removed", { actor: actorId, subject: memberId });
+            return null;
+        },
+        leave(memberId) {
+            if (!members.has(memberId))
+                return { reason: "not a member" };
+            if (memberId === founderId)
+                return { reason: "founder must transfer leadership first" };
+            members.delete(memberId);
+            dropPersonalAssets(memberId);
+            log("member-left", { subject: memberId });
+            return null;
+        },
+        setMemberRank(actorId, memberId, rankId) {
+            if (!members.has(actorId))
+                return { reason: "actor is not a member" };
+            if (!members.has(memberId))
+                return { reason: "not a member" };
+            if (memberId === founderId)
+                return { reason: "cannot re-rank the founder" };
+            if (!can(actorId, "manage-ranks"))
+                return { reason: "missing manage-ranks permission" };
+            const nextRank = ranks.get(rankId);
+            if (nextRank === undefined)
+                return { reason: `unknown rank id "${rankId}"` };
+            if (!isAdmin(actorId)) {
+                if (levelOf(actorId) <= levelOf(memberId))
+                    return { reason: "cannot manage an equal or higher rank" };
+                if (nextRank.level >= levelOf(actorId))
+                    return { reason: "cannot assign a rank at or above your own" };
+            }
+            members.get(memberId).rankId = rankId;
+            log("rank-changed", { actor: actorId, subject: memberId, rankId });
+            return null;
+        },
+        transferFounder(actorId, memberId) {
+            if (actorId !== founderId)
+                return { reason: "only the founder can transfer leadership" };
+            if (!members.has(memberId))
+                return { reason: "not a member" };
+            if (memberId === founderId)
+                return { reason: "already the founder" };
+            members.get(memberId).rankId = founderRankId;
+            founderId = memberId;
+            log("founder-transferred", { actor: actorId, subject: memberId });
+            return null;
+        },
+        registerAsset(actorId, ref, ownership) {
+            if (!members.has(actorId))
+                return { reason: "actor is not a member" };
+            const key = assetKey(ref.kind, ref.id);
+            if (assets.has(key))
+                return { reason: "asset already registered" };
+            let ownerId;
+            if (ownership.scope === "group") {
+                if (!can(actorId, "build"))
+                    return { reason: "missing build permission" };
+                ownerId = null;
+            }
+            else {
+                if (!members.has(ownership.memberId))
+                    return { reason: "owner is not a member" };
+                if (ownership.memberId !== actorId && !isAdmin(actorId)) {
+                    return { reason: "cannot register assets for another member" };
+                }
+                ownerId = ownership.memberId;
+            }
+            assets.set(key, { kind: ref.kind, id: ref.id, ownerId });
+            log("asset-registered", { actor: actorId, assetKind: ref.kind, assetId: ref.id });
+            return null;
+        },
+        unregisterAsset(actorId, ref) {
+            if (!members.has(actorId))
+                return { reason: "actor is not a member" };
+            const key = assetKey(ref.kind, ref.id);
+            const asset = assets.get(key);
+            if (asset === undefined)
+                return { reason: "unknown asset" };
+            if (asset.ownerId === null) {
+                if (!can(actorId, "demolish"))
+                    return { reason: "missing demolish permission" };
+            }
+            else if (asset.ownerId !== actorId && !isAdmin(actorId)) {
+                return { reason: "not the asset owner" };
+            }
+            assets.delete(key);
+            log("asset-unregistered", { actor: actorId, assetKind: ref.kind, assetId: ref.id });
+            return null;
+        },
+        ownerOfAsset(ref) {
+            const asset = assets.get(assetKey(ref.kind, ref.id));
+            if (asset === undefined)
+                return null;
+            return asset.ownerId === null ? { scope: "group" } : { scope: "personal", memberId: asset.ownerId };
+        },
+        assetsOf(memberId) {
+            const out = [];
+            for (const asset of assets.values()) {
+                if (asset.ownerId === memberId)
+                    out.push({ kind: asset.kind, id: asset.id });
+            }
+            return out;
+        },
+        canAccess(memberId, ref, action) {
+            if (!members.has(memberId))
+                return false;
+            if (isAdmin(memberId))
+                return true;
+            const asset = assets.get(assetKey(ref.kind, ref.id));
+            if (asset === undefined)
+                return false;
+            if (asset.ownerId !== null)
+                return asset.ownerId === memberId;
+            return can(memberId, action);
+        },
+        addAlly(tribeId) {
+            if (tribeId === config.id || allies.has(tribeId))
+                return;
+            allies.add(tribeId);
+            log("alliance-formed", { tribeId });
+        },
+        removeAlly(tribeId) {
+            if (!allies.delete(tribeId))
+                return;
+            log("alliance-broken", { tribeId });
+        },
+        isAllied: (tribeId) => allies.has(tribeId),
+        allyIds: () => [...allies],
+        relationTo(tribeId) {
+            if (tribeId === config.id || allies.has(tribeId))
+                return "friendly";
+            return "neutral";
+        },
+        events: () => eventLog.slice(),
+        snapshot() {
+            return {
+                id: config.id,
+                founderId,
+                ranks: [...ranks.values()].map(rankToDef),
+                defaultRankId,
+                founderRankId,
+                logCap,
+                members: [...members.values()].map((m) => ({ ...m })),
+                assets: [...assets.values()].map((a) => ({ kind: a.kind, id: a.id, ownerId: a.ownerId })),
+                allies: [...allies],
+                events: eventLog.map((e) => ({ ...e })),
+                eventSeq,
+            };
+        },
+        hydrate(snapshot) {
+            ranks.clear();
+            for (const def of snapshot.ranks)
+                ranks.set(def.id, toRankRuntime(def));
+            defaultRankId = snapshot.defaultRankId;
+            founderRankId = snapshot.founderRankId;
+            logCap = Math.max(1, Math.floor(snapshot.logCap));
+            founderId = snapshot.founderId;
+            members.clear();
+            for (const m of snapshot.members)
+                members.set(m.id, { ...m });
+            assets.clear();
+            for (const a of snapshot.assets)
+                assets.set(assetKey(a.kind, a.id), { kind: a.kind, id: a.id, ownerId: a.ownerId });
+            allies.clear();
+            for (const t of snapshot.allies)
+                allies.add(t);
+            eventLog.length = 0;
+            for (const e of snapshot.events)
+                eventLog.push({ ...e });
+            eventSeq = snapshot.eventSeq;
+        },
+    };
+}
+/**
+ * Create a registry that owns many tribes, keeps alliances mutual, and resolves member relations.
+ *
+ * @capability tribe-registry registry of tribes with mutual alliances and cross-tribe relation lookup
+ */
+export function createTribeRegistry(deps = {}) {
+    const tribes = new Map();
+    const build = (config) => {
+        const merged = {
+            ...config,
+            ...(config.now === undefined && deps.now !== undefined ? { now: deps.now } : {}),
+            ...(config.logCap === undefined && deps.defaultLogCap !== undefined ? { logCap: deps.defaultLogCap } : {}),
+        };
+        return createTribe(merged);
+    };
+    function relationBetweenTribes(tribeA, tribeB) {
+        if (tribeA === tribeB)
+            return "friendly";
+        const a = tribes.get(tribeA);
+        if (a === undefined || !tribes.has(tribeB))
+            return "neutral";
+        return a.isAllied(tribeB) ? "friendly" : "neutral";
+    }
+    function tribeOfMember(memberId) {
+        for (const tribe of tribes.values()) {
+            if (tribe.hasMember(memberId))
+                return tribe;
+        }
+        return null;
+    }
+    function relationBetweenMembers(memberA, memberB) {
+        const a = tribeOfMember(memberA);
+        const b = tribeOfMember(memberB);
+        if (a === null || b === null)
+            return "neutral";
+        if (a.id === b.id)
+            return "friendly";
+        return relationBetweenTribes(a.id, b.id);
+    }
+    return {
+        create(config) {
+            if (tribes.has(config.id))
+                throw new Error(`duplicate tribe id "${config.id}"`);
+            const tribe = build(config);
+            tribes.set(config.id, tribe);
+            return tribe;
+        },
+        get: (id) => tribes.get(id) ?? null,
+        all: () => [...tribes.values()],
+        remove(id) {
+            if (!tribes.delete(id))
+                return;
+            for (const tribe of tribes.values())
+                tribe.removeAlly(id);
+        },
+        formAlliance(tribeA, tribeB) {
+            if (tribeA === tribeB)
+                return { reason: "a tribe cannot ally with itself" };
+            const a = tribes.get(tribeA);
+            const b = tribes.get(tribeB);
+            if (a === undefined || b === undefined)
+                return { reason: "unknown tribe" };
+            a.addAlly(tribeB);
+            b.addAlly(tribeA);
+            return null;
+        },
+        breakAlliance(tribeA, tribeB) {
+            tribes.get(tribeA)?.removeAlly(tribeB);
+            tribes.get(tribeB)?.removeAlly(tribeA);
+        },
+        areAllied(tribeA, tribeB) {
+            const a = tribes.get(tribeA);
+            const b = tribes.get(tribeB);
+            return a !== undefined && b !== undefined && a.isAllied(tribeB) && b.isAllied(tribeA);
+        },
+        relationBetweenTribes,
+        tribeOfMember,
+        relationBetweenMembers,
+        isFriendly: (memberA, memberB) => relationBetweenMembers(memberA, memberB) === "friendly",
+        snapshot: () => ({ tribes: [...tribes.values()].map((tribe) => tribe.snapshot()) }),
+        hydrate(snapshot) {
+            tribes.clear();
+            for (const tribeSnap of snapshot.tribes) {
+                const config = {
+                    id: tribeSnap.id,
+                    founderId: tribeSnap.founderId,
+                    ranks: tribeSnap.ranks,
+                    defaultRankId: tribeSnap.defaultRankId,
+                    founderRankId: tribeSnap.founderRankId,
+                    logCap: tribeSnap.logCap,
+                    ...(deps.now === undefined ? {} : { now: deps.now }),
+                };
+                const tribe = createTribe(config);
+                tribe.hydrate(tribeSnap);
+                tribes.set(tribe.id, tribe);
+            }
+        },
+    };
+}

package/dist/game/unlocks.d.ts

@@ -10,6 +10,11 @@ export interface UnlockCatalog {
     has(unlockId: string): boolean;
     tree(categoryId: string): UnlockDef[];
 }
+/**
+ * A catalog of unlockable content gated behind conditions the player earns, tracking what is unlocked.
+ *
+ * @capability unlockables gate content behind unlock conditions the player earns
+ */
 export declare function createUnlockCatalog(defs?: readonly UnlockDef[]): UnlockCatalog;
 export interface Unlocks {
     has(userId: string, unlockId: string): boolean;
@@ -18,5 +23,8 @@ export interface Unlocks {
     tree(categoryId: string): UnlockDef[];
     snapshot(userId: string): string[];
     hydrate(userId: string, ids: string[]): void;
+    /** Whole-store capture across every user — the world-save/replication seam (per-user `snapshot` can't enumerate users). */
+    snapshotAll(): Record<string, string[]>;
+    hydrateAll(data: Record<string, string[]>): void;
 }
 export declare function createUnlocks(defs?: UnlockDef[]): Unlocks;

package/dist/game/unlocks.js

@@ -7,6 +7,11 @@ export function grantUnlock(granted, unlockId) {
 export function unlockTree(defs, categoryId) {
     return defs.filter((def) => def.category === categoryId);
 }
+/**
+ * A catalog of unlockable content gated behind conditions the player earns, tracking what is unlocked.
+ *
+ * @capability unlockables gate content behind unlock conditions the player earns
+ */
 export function createUnlockCatalog(defs = []) {
     const byId = new Map();
     for (const def of defs)
@@ -48,5 +53,16 @@ export function createUnlocks(defs = []) {
         hydrate(userId, ids) {
             granted.set(userId, new Set(ids));
         },
+        snapshotAll() {
+            const out = {};
+            for (const [userId, ids] of granted)
+                out[userId] = Array.from(ids);
+            return out;
+        },
+        hydrateAll(data) {
+            granted.clear();
+            for (const [userId, ids] of Object.entries(data))
+                granted.set(userId, new Set(ids));
+        },
     };
 }

package/dist/game/vfxInstance.d.ts

@@ -0,0 +1,138 @@
+import type { RetainedVfxKind, VfxRef } from "./events.js";
+/**
+ * The serializable specification for creating (or replacing) a retained VFX instance. Unlike a one-shot
+ * `combat.vfx` burst this describes a long-lived effect whose endpoints and parameters are updated over
+ * time. `id` is caller-stable so repeated `upsert` calls address the same effect; omit it to mint one.
+ * `from`/`to` are {@link VfxRef}s (an entity instance id or a world point) that a renderer resolves each
+ * frame, so an endpoint bound to a moving entity follows it without any per-frame command traffic.
+ */
+export interface VfxInstanceSpec {
+    /** Caller-stable handle. Repeated `upsert` with the same id replaces the instance; omitted mints a fresh id. */
+    id?: string;
+    /** Open effect archetype (e.g. `"beam"`). Renderers register kinds, so new visuals need no central branch. */
+    kind: RetainedVfxKind;
+    /** `0xRRGGBB` tint. */
+    color: number;
+    /** Origin endpoint: an entity instance id (followed live) or a fixed world point. */
+    from?: VfxRef;
+    /** Target endpoint: an entity instance id (followed live) or a fixed world point. */
+    to?: VfxRef;
+    /** Effect radius/thickness in world units, interpreted per kind. */
+    radius?: number;
+    /** Extra numeric knobs a renderer reads by name (intensity, spin, width, ...), kept a flat serializable bag. */
+    params?: Readonly<Record<string, number>>;
+    /** Optional time-to-live in ms: the instance auto-stops if `tick` runs past `ttlMs` since its last touch (heartbeat). */
+    ttlMs?: number;
+}
+/**
+ * The stored, fully-resolved form of a retained VFX instance. It is a plain serializable record so hosts can
+ * replicate it and debug tooling can inspect it; renderers receive it verbatim and never merge partial state
+ * themselves. `updatedAtMs` is the last create/update time and drives TTL heartbeat eviction.
+ */
+export interface VfxInstanceState {
+    /** Stable instance id. */
+    readonly id: string;
+    /** Effect archetype. */
+    readonly kind: RetainedVfxKind;
+    /** `0xRRGGBB` tint. */
+    readonly color: number;
+    /** Origin endpoint, if any. */
+    readonly from?: VfxRef;
+    /** Target endpoint, if any. */
+    readonly to?: VfxRef;
+    /** Effect radius/thickness. */
+    readonly radius?: number;
+    /** Renderer knobs. */
+    readonly params?: Readonly<Record<string, number>>;
+    /** TTL in ms, if the instance heartbeats. */
+    readonly ttlMs?: number;
+    /** Clock time (ms) of the last create/update; the TTL heartbeat measures staleness from here. */
+    readonly updatedAtMs: number;
+}
+/**
+ * A partial update to a live retained VFX instance. Only the provided fields change; `params` is shallow-merged
+ * so a caller can nudge one knob without resending the whole bag. Setting a field to `undefined` clears it.
+ * Applying a patch refreshes the instance heartbeat.
+ */
+export interface VfxInstancePatch {
+    /** New tint. */
+    color?: number;
+    /** New origin endpoint. */
+    from?: VfxRef;
+    /** New target endpoint. */
+    to?: VfxRef;
+    /** New radius/thickness. */
+    radius?: number;
+    /** Knobs shallow-merged into the current `params`. */
+    params?: Readonly<Record<string, number>>;
+}
+/** Options for {@link VfxInstanceStore.stop}. */
+export interface VfxInstanceStopOptions {
+    /** Fade-out duration in ms handed to the renderer; `0` (default) disposes immediately. */
+    fadeMs?: number;
+}
+/**
+ * The lifecycle op a {@link VfxInstanceStore} emits to its renderer sink. `upsert`/`update` carry the full merged
+ * {@link VfxInstanceState} (the renderer applies it directly, no merge); `stop` carries the id plus a fade duration.
+ * This is the payload of the `combat.vfxInstance` game event when the store is wired to the event bus.
+ */
+export interface CombatVfxInstanceEvent {
+    /** `upsert` creates/replaces, `update` mutates dynamic params, `stop` disposes (with optional fade). */
+    readonly op: "upsert" | "update" | "stop";
+    /** The affected instance id. */
+    readonly id: string;
+    /** The full merged state, present for `upsert` and `update`. */
+    readonly instance?: VfxInstanceState;
+    /** Fade-out duration in ms, present for `stop`. */
+    readonly fadeMs?: number;
+}
+/**
+ * A headless registry of retained VFX instances: create/replace, partially update, and stop long-lived effects
+ * addressed by stable id, independent of any renderer. It owns the authoritative serializable state and exposes
+ * inspection counts; wire {@link VfxInstanceStoreOptions.onOp} to a renderer (via the `combat.vfxInstance` event)
+ * to drive visuals.
+ */
+export interface VfxInstanceStore {
+    /**
+     * Create the instance, or replace it in place when its id already exists (idempotent by id). Returns the id
+     * (minted when the spec omits one). Refreshes the heartbeat.
+     */
+    upsert(spec: VfxInstanceSpec): string;
+    /**
+     * Merge `patch` into the live instance and refresh its heartbeat. Returns `false` for an unknown id (a missing
+     * update is a no-op, never a throw), `true` otherwise.
+     */
+    update(id: string, patch: VfxInstancePatch): boolean;
+    /** Dispose the instance, emitting a `stop` op with the resolved fade. Returns `false` for an unknown id. */
+    stop(id: string, options?: VfxInstanceStopOptions): boolean;
+    /** The current state of `id`, or `null` if absent. */
+    get(id: string): VfxInstanceState | null;
+    /** Every live instance, insertion-ordered. */
+    list(): readonly VfxInstanceState[];
+    /** Live instance count, for debug/inspection HUDs. */
+    count(): number;
+    /** Auto-stop instances whose TTL has elapsed as of `nowMs` (defaults to the store clock). Returns the number stopped. */
+    tick(nowMs?: number): number;
+    /** Dispose every instance (scene change / reset), emitting a `stop` op for each. */
+    clear(): void;
+}
+/** Options for {@link createVfxInstanceStore}. */
+export interface VfxInstanceStoreOptions {
+    /** Sink for lifecycle ops; wire to `events.emit("combat.vfxInstance", op)` so the shell renders them. */
+    onOp?: (op: CombatVfxInstanceEvent) => void;
+    /** Injected clock (ms) for heartbeat timestamps and TTL; defaults to `Date.now`. Pass a sim clock for determinism. */
+    now?: () => number;
+    /** Prefix for minted instance ids. Defaults to `"vfx"`. */
+    idPrefix?: string;
+}
+/**
+ * Build a headless retained-VFX registry. The store is the serializable source of truth for long-lived effects
+ * (beams, tethers, zones, target lines, looping emitters) that must move and mutate without one-shot re-emit
+ * flicker: `upsert` creates or replaces by stable id, `update` nudges dynamic params, `stop` disposes with an
+ * optional fade, and `tick` enforces TTL heartbeats. It stays independent of renderer availability, so simulation
+ * and tests run without a shell; a wired `onOp` sink turns each op into a `combat.vfxInstance` event the shell
+ * binds to render resources.
+ *
+ * @capability retained-vfx create/update/stop long-lived dynamic visual effects (beam, tether, zone, target line) by stable id
+ */
+export declare function createVfxInstanceStore(options?: VfxInstanceStoreOptions): VfxInstanceStore;