@jgengine/core 0.10.0 → 0.11.0

package/dist/game/social.js

@@ -1,5 +1,10 @@
 export const DEFAULT_EMOTE_RADIUS = 20;
 const DEFAULT_INVITE_TTL_MS = 60_000;
+/**
+ * Emotes and lightweight social interactions between nearby players.
+ *
+ * @capability social-emotes emotes and social interactions between nearby players
+ */
 export function createSocial(deps) {
     const now = deps.now ?? Date.now;
     const events = deps.events;
@@ -351,6 +356,70 @@ export function createSocial(deps) {
             return result;
         },
     };
+    function snapshot() {
+        const friendshipsOut = {};
+        for (const [userId, set] of friendships)
+            friendshipsOut[userId] = Array.from(set);
+        const blockedOut = {};
+        for (const [userId, set] of blocked)
+            blockedOut[userId] = Array.from(set);
+        const friendRequestsOut = {};
+        for (const [id, request] of friendRequests)
+            friendRequestsOut[id] = { from: request.from, to: request.to };
+        const partyInvitesOut = {};
+        for (const [id, invite] of partyInvites) {
+            partyInvitesOut[id] = { from: invite.from, to: invite.to, createdAt: invite.createdAt };
+        }
+        return {
+            friendships: friendshipsOut,
+            blocked: blockedOut,
+            friendRequests: friendRequestsOut,
+            requestCounter,
+            partyConfig,
+            parties: Array.from(parties.values(), (state) => ({
+                id: state.id,
+                leader: state.leader,
+                members: state.members.slice(),
+            })),
+            partyInvites: partyInvitesOut,
+            partyCounter,
+            inviteCounter,
+            worldInvites: Array.from(worldInviteEntries.values(), (entry) => ({ ...entry })),
+            worldInviteCounter,
+        };
+    }
+    function hydrate(data) {
+        friendships.clear();
+        for (const [userId, list] of Object.entries(data.friendships))
+            friendships.set(userId, new Set(list));
+        blocked.clear();
+        for (const [userId, list] of Object.entries(data.blocked))
+            blocked.set(userId, new Set(list));
+        friendRequests.clear();
+        for (const [id, request] of Object.entries(data.friendRequests)) {
+            friendRequests.set(id, { from: request.from, to: request.to });
+        }
+        requestCounter = data.requestCounter;
+        partyConfig = data.partyConfig;
+        parties.clear();
+        memberToParty.clear();
+        for (const state of data.parties) {
+            const restored = { id: state.id, leader: state.leader, members: state.members.slice() };
+            parties.set(restored.id, restored);
+            for (const member of restored.members)
+                memberToParty.set(member, restored.id);
+        }
+        partyInvites.clear();
+        for (const [id, invite] of Object.entries(data.partyInvites)) {
+            partyInvites.set(id, { from: invite.from, to: invite.to, createdAt: invite.createdAt });
+        }
+        partyCounter = data.partyCounter;
+        inviteCounter = data.inviteCounter;
+        worldInviteEntries.clear();
+        for (const entry of data.worldInvites)
+            worldInviteEntries.set(entry.id, { ...entry });
+        worldInviteCounter = data.worldInviteCounter;
+    }
     return {
         friends,
         party,
@@ -361,5 +430,7 @@ export function createSocial(deps) {
         },
         emotes,
         worldInvites,
+        snapshot,
+        hydrate,
     };
 }

package/dist/game/spawnPoints.d.ts

@@ -16,4 +16,9 @@ export interface SpawnPoints {
     })[];
     respawn(entities: RespawnTarget, entityId: string, spawnId: string): boolean;
 }
+/**
+ * Register spawn locations and choose where entities spawn or respawn.
+ *
+ * @capability spawn-points register spawn locations and pick where entities respawn
+ */
 export declare function createSpawnPoints(): SpawnPoints;

package/dist/game/spawnPoints.js

@@ -1,3 +1,8 @@
+/**
+ * Register spawn locations and choose where entities spawn or respawn.
+ *
+ * @capability spawn-points register spawn locations and pick where entities respawn
+ */
 export function createSpawnPoints() {
     const points = new Map();
     return {

package/dist/game/systemRuntime.d.ts

@@ -0,0 +1,50 @@
+import type { GameLoop } from "./defineGame.js";
+import type { SystemDefinition } from "./defineSystem.js";
+import { type CompiledSystemSchedule, type CompileSystemScheduleOptions } from "./systemSchedule.js";
+import type { GameContext } from "../runtime/gameContext.js";
+import type { SnapshotModule } from "../runtime/worldSnapshot.js";
+/** @internal */
+export interface SystemModuleRegistration {
+    registerSave(module: SnapshotModule): void;
+    registerReplicate(module: SnapshotModule): void;
+}
+/** @internal */
+export interface InstalledSystems {
+    readonly schedule: CompiledSystemSchedule;
+    /** Advance fixed/frame/interval systems for one game-time step of `dt` seconds. */
+    tick(ctx: GameContext, dt: number): void;
+    /** Invoke every system's `reset` (scenario/run wipe). */
+    reset(ctx: GameContext): void;
+    /** Invoke every system's `dispose` in reverse install order. */
+    dispose(ctx: GameContext): void;
+    /** Run one manual system by id (no-op if missing or not manual). */
+    runManual(ctx: GameContext, id: string, dt?: number): void;
+}
+/**
+ * Install systems on a live context: `create` → bind events → register save/replicate → `start`.
+ * Call once per world boot (from the composed loop's `onInit`).
+ * @internal
+ */
+export declare function installSystems(ctx: GameContext, systems: readonly SystemDefinition[], options?: CompileSystemScheduleOptions & {
+    modules?: SystemModuleRegistration;
+}): InstalledSystems;
+/**
+ * Look up systems installed on `ctx` (if any). Used by hosts that need `reset`/`dispose` after boot.
+ * @internal
+ */
+export declare function systemsOf(ctx: GameContext): InstalledSystems | undefined;
+/** @internal */
+export interface ComposeGameLoopOptions extends CompileSystemScheduleOptions {
+    /**
+     * When true, the user loop's `onTick` runs before system ticks (default: systems first, then
+     * residual loop work — the incremental-migration path).
+     */
+    loopBeforeSystems?: boolean;
+}
+/**
+ * Merge a system list with an optional classic `GameLoop` into one loop the shell/runners drive.
+ * Systems install on first `onInit`; classic hooks still run for incremental migration.
+ *
+ * @capability compose-game-loop fold composable systems into the game loop without a manual tick fan-out
+ */
+export declare function composeGameLoop(systems: readonly SystemDefinition[] | undefined, loop: GameLoop<GameContext> | undefined, options?: ComposeGameLoopOptions): GameLoop<GameContext>;

package/dist/game/systemRuntime.js

@@ -0,0 +1,157 @@
+import { compileSystemSchedule, } from "./systemSchedule.js";
+function resolveModule(spec, ctx) {
+    if (spec === undefined)
+        return undefined;
+    return typeof spec === "function" ? spec(ctx) : spec;
+}
+/**
+ * Install systems on a live context: `create` → bind events → register save/replicate → `start`.
+ * Call once per world boot (from the composed loop's `onInit`).
+ * @internal
+ */
+export function installSystems(ctx, systems, options) {
+    const schedule = compileSystemSchedule(systems, options);
+    const list = systems;
+    const unsubs = [];
+    const intervalAcc = new Map();
+    const fixedAcc = new Map();
+    for (const system of list) {
+        system.create?.(ctx);
+    }
+    for (const system of list) {
+        if (system.events !== undefined) {
+            for (const [name, handler] of Object.entries(system.events)) {
+                if (handler === undefined)
+                    continue;
+                const off = ctx.game.events.on(name, ((event) => {
+                    handler(ctx, event);
+                }));
+                unsubs.push(off);
+            }
+        }
+        const save = resolveModule(system.save, ctx);
+        if (save !== undefined)
+            options?.modules?.registerSave(save);
+        const replicate = resolveModule(system.replicate, ctx);
+        if (replicate !== undefined)
+            options?.modules?.registerReplicate(replicate);
+    }
+    for (const system of list) {
+        system.start?.(ctx);
+    }
+    for (const group of schedule.fixed) {
+        fixedAcc.set(group.rate, 0);
+    }
+    for (const interval of schedule.intervals) {
+        intervalAcc.set(interval.id, 0);
+    }
+    function runIds(ctx, ids, dt) {
+        for (const id of ids) {
+            schedule.systemsById.get(id)?.update?.(ctx, dt);
+        }
+    }
+    function tick(ctx, dt) {
+        if (!(dt > 0))
+            return;
+        for (const group of schedule.fixed) {
+            const step = 1 / group.rate;
+            let acc = (fixedAcc.get(group.rate) ?? 0) + dt;
+            while (acc >= step) {
+                runIds(ctx, group.order, step);
+                acc -= step;
+            }
+            fixedAcc.set(group.rate, acc);
+        }
+        runIds(ctx, schedule.frameOrder, dt);
+        for (const interval of schedule.intervals) {
+            const every = interval.every ?? 1;
+            let acc = (intervalAcc.get(interval.id) ?? 0) + dt;
+            while (acc >= every) {
+                schedule.systemsById.get(interval.id)?.update?.(ctx, every);
+                acc -= every;
+            }
+            intervalAcc.set(interval.id, acc);
+        }
+    }
+    function reset(ctx) {
+        for (const system of list)
+            system.reset?.(ctx);
+        for (const group of schedule.fixed)
+            fixedAcc.set(group.rate, 0);
+        for (const interval of schedule.intervals)
+            intervalAcc.set(interval.id, 0);
+    }
+    function dispose(ctx) {
+        for (const off of unsubs)
+            off();
+        unsubs.length = 0;
+        for (let i = list.length - 1; i >= 0; i -= 1) {
+            list[i]?.dispose?.(ctx);
+        }
+    }
+    function runManual(ctx, id, dt = 0) {
+        if (!schedule.manual.includes(id))
+            return;
+        schedule.systemsById.get(id)?.update?.(ctx, dt);
+    }
+    return { schedule, tick, reset, dispose, runManual };
+}
+const installedByCtx = new WeakMap();
+/**
+ * Look up systems installed on `ctx` (if any). Used by hosts that need `reset`/`dispose` after boot.
+ * @internal
+ */
+export function systemsOf(ctx) {
+    return installedByCtx.get(ctx);
+}
+/**
+ * Merge a system list with an optional classic `GameLoop` into one loop the shell/runners drive.
+ * Systems install on first `onInit`; classic hooks still run for incremental migration.
+ *
+ * @capability compose-game-loop fold composable systems into the game loop without a manual tick fan-out
+ */
+export function composeGameLoop(systems, loop, options) {
+    if (systems === undefined || systems.length === 0) {
+        return loop ?? {};
+    }
+    let installed;
+    const loopBefore = options?.loopBeforeSystems === true;
+    return {
+        onInit(ctx) {
+            const modules = ctx.game.registerSave !== undefined && ctx.game.registerReplicate !== undefined
+                ? {
+                    registerSave: (m) => ctx.game.registerSave(m),
+                    registerReplicate: (m) => ctx.game.registerReplicate(m),
+                }
+                : undefined;
+            installed = installSystems(ctx, systems, { ...options, modules });
+            installedByCtx.set(ctx, installed);
+            loop?.onInit?.(ctx);
+        },
+        onNewPlayer(ctx, player) {
+            loop?.onNewPlayer?.(ctx, player);
+        },
+        onTick(ctx, dt) {
+            if (loopBefore) {
+                loop?.onTick?.(ctx, dt);
+                installed?.tick(ctx, dt);
+            }
+            else {
+                installed?.tick(ctx, dt);
+                loop?.onTick?.(ctx, dt);
+            }
+        },
+        onPlayerLeave(ctx, player) {
+            loop?.onPlayerLeave?.(ctx, player);
+        },
+        onReset(ctx) {
+            installed?.reset(ctx);
+            loop?.onReset?.(ctx);
+        },
+        onDispose(ctx) {
+            installed?.dispose(ctx);
+            installedByCtx.delete(ctx);
+            loop?.onDispose?.(ctx);
+        },
+    };
+}

package/dist/game/systemSchedule.d.ts

@@ -0,0 +1,72 @@
+import type { SystemDefinition } from "./defineSystem.js";
+/** Default fixed-sim stage order — systems pick a stage; most need only this. */
+export declare const DEFAULT_FIXED_STAGES: readonly ["input", "movement", "combat", "ai", "activities", "cleanup"];
+/**
+ * Default frame stage order. Gameplay stages mirror the fixed table so once-per-frame systems
+ * (`type: "frame"`) can pick `combat`/`ai`/… without falling into the unknown-stage bucket;
+ * presentation stages follow.
+ */
+export declare const DEFAULT_FRAME_STAGES: readonly ["input", "movement", "combat", "ai", "activities", "cleanup", "animation", "camera", "effects"];
+/** @internal */
+export type TimingChannel = "fixed" | "frame" | "interval" | "manual" | "event";
+/** @internal */
+export interface ScheduledSystem {
+    readonly id: string;
+    readonly channel: TimingChannel;
+    readonly stage: string;
+    readonly rate?: number;
+    readonly every?: number;
+    readonly after: readonly string[];
+    readonly before: readonly string[];
+    readonly dependsOn: readonly string[];
+}
+/** @internal */
+export interface StageBucket {
+    readonly stage: string;
+    /** System ids in deterministic order within this stage. */
+    readonly systems: readonly string[];
+}
+/** @internal */
+export interface FixedRateGroup {
+    readonly rate: number;
+    readonly stages: readonly StageBucket[];
+    /** Flat ordered ids for this rate (all stages). */
+    readonly order: readonly string[];
+}
+/**
+ * Deterministic compiled schedule: stage buckets, multi-subscribe channels, dependency validation.
+ * Order never depends on import order — only stage tables + explicit before/after constraints.
+ */
+export interface CompiledSystemSchedule {
+    readonly systemsById: ReadonlyMap<string, SystemDefinition>;
+    readonly scheduled: readonly ScheduledSystem[];
+    /** Fixed-sim groups keyed by rate (Hz); multiple systems may share a rate. */
+    readonly fixed: readonly FixedRateGroup[];
+    readonly frame: readonly StageBucket[];
+    readonly frameOrder: readonly string[];
+    /** Interval systems — each keeps its own period; multi-subscribe is per-system. */
+    readonly intervals: readonly ScheduledSystem[];
+    readonly manual: readonly string[];
+    readonly eventOnly: readonly string[];
+    /** All auto-ticking systems in a diagnostic flat order (fixed rates → frame → intervals). */
+    readonly tickOrder: readonly string[];
+}
+/** @internal */
+export interface CompileSystemScheduleOptions {
+    fixedStages?: readonly string[];
+    frameStages?: readonly string[];
+    defaultFixedRate?: number;
+}
+/**
+ * Topological sort with a stable tie-break on original declaration index, then id.
+ * Edges: `after: "x"` means this runs after x (x → this); `before: "y"` means this → y.
+ * @internal
+ */
+export declare function orderWithConstraints(ids: readonly string[], after: ReadonlyMap<string, readonly string[]>, before: ReadonlyMap<string, readonly string[]>, indexOf: ReadonlyMap<string, number>): string[];
+/**
+ * Compile system definitions into a deterministic schedule.
+ * Validates unique ids, `dependsOn`, and before/after cycles.
+ *
+ * @capability system-schedule compile fixed/frame/interval system ticks into deterministic ordered stages
+ */
+export declare function compileSystemSchedule(systems: readonly SystemDefinition[], options?: CompileSystemScheduleOptions): CompiledSystemSchedule;

package/dist/game/systemSchedule.js

@@ -0,0 +1,242 @@
+/** Default fixed-sim stage order — systems pick a stage; most need only this. */
+export const DEFAULT_FIXED_STAGES = [
+    "input",
+    "movement",
+    "combat",
+    "ai",
+    "activities",
+    "cleanup",
+];
+/**
+ * Default frame stage order. Gameplay stages mirror the fixed table so once-per-frame systems
+ * (`type: "frame"`) can pick `combat`/`ai`/… without falling into the unknown-stage bucket;
+ * presentation stages follow.
+ */
+export const DEFAULT_FRAME_STAGES = [
+    "input",
+    "movement",
+    "combat",
+    "ai",
+    "activities",
+    "cleanup",
+    "animation",
+    "camera",
+    "effects",
+];
+const DEFAULT_FIXED_RATE = 60;
+function asList(value) {
+    if (value === undefined)
+        return [];
+    return typeof value === "string" ? [value] : value;
+}
+function channelOf(tick) {
+    if (tick === undefined)
+        return "event";
+    return tick.type;
+}
+function stageOf(tick, channel) {
+    if (tick === undefined || tick.type === "manual")
+        return "";
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return tick.stage ?? defaultStage(channel);
+    }
+    return "";
+}
+function defaultStage(channel) {
+    if (channel === "fixed")
+        return "combat";
+    if (channel === "frame")
+        return "effects";
+    if (channel === "interval")
+        return "activities";
+    return "";
+}
+function rateOf(tick, defaultFixedRate) {
+    if (tick?.type === "fixed")
+        return tick.rate ?? defaultFixedRate;
+    return undefined;
+}
+function everyOf(tick) {
+    if (tick?.type === "interval")
+        return tick.every;
+    return undefined;
+}
+function afterOf(tick) {
+    if (tick === undefined || tick.type === "manual")
+        return [];
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return asList(tick.after);
+    }
+    return [];
+}
+function beforeOf(tick) {
+    if (tick === undefined || tick.type === "manual")
+        return [];
+    if (tick.type === "fixed" || tick.type === "frame" || tick.type === "interval") {
+        return asList(tick.before);
+    }
+    return [];
+}
+/**
+ * Topological sort with a stable tie-break on original declaration index, then id.
+ * Edges: `after: "x"` means this runs after x (x → this); `before: "y"` means this → y.
+ * @internal
+ */
+export function orderWithConstraints(ids, after, before, indexOf) {
+    const idSet = new Set(ids);
+    const preds = new Map();
+    const succs = new Map();
+    for (const id of ids) {
+        preds.set(id, new Set());
+        succs.set(id, new Set());
+    }
+    const addEdge = (from, to) => {
+        if (!idSet.has(from) || !idSet.has(to) || from === to)
+            return;
+        succs.get(from).add(to);
+        preds.get(to).add(from);
+    };
+    for (const id of ids) {
+        for (const a of after.get(id) ?? [])
+            addEdge(a, id);
+        for (const b of before.get(id) ?? [])
+            addEdge(id, b);
+    }
+    const ready = ids
+        .filter((id) => preds.get(id).size === 0)
+        .sort((a, b) => {
+        const ia = indexOf.get(a) ?? 0;
+        const ib = indexOf.get(b) ?? 0;
+        if (ia !== ib)
+            return ia - ib;
+        return a < b ? -1 : a > b ? 1 : 0;
+    });
+    const ordered = [];
+    while (ready.length > 0) {
+        const next = ready.shift();
+        ordered.push(next);
+        for (const succ of succs.get(next) ?? []) {
+            const set = preds.get(succ);
+            set.delete(next);
+            if (set.size === 0) {
+                ready.push(succ);
+                ready.sort((a, b) => {
+                    const ia = indexOf.get(a) ?? 0;
+                    const ib = indexOf.get(b) ?? 0;
+                    if (ia !== ib)
+                        return ia - ib;
+                    return a < b ? -1 : a > b ? 1 : 0;
+                });
+            }
+        }
+    }
+    if (ordered.length !== ids.length) {
+        const leftover = ids.filter((id) => !ordered.includes(id));
+        throw new Error(`system schedule: cyclic before/after constraints among: ${leftover.join(", ")}`);
+    }
+    return ordered;
+}
+function bucketByStage(items, stageOrder, indexOf) {
+    const stageIndex = new Map();
+    stageOrder.forEach((s, i) => stageIndex.set(s, i));
+    const unknownStages = new Set();
+    for (const item of items) {
+        if (item.stage !== "" && !stageIndex.has(item.stage))
+            unknownStages.add(item.stage);
+    }
+    const stages = [...stageOrder, ...[...unknownStages].sort()];
+    const buckets = [];
+    for (const stage of stages) {
+        const inStage = items.filter((s) => s.stage === stage);
+        if (inStage.length === 0)
+            continue;
+        const after = new Map();
+        const before = new Map();
+        for (const s of inStage) {
+            after.set(s.id, s.after);
+            before.set(s.id, s.before);
+        }
+        const order = orderWithConstraints(inStage.map((s) => s.id), after, before, indexOf);
+        buckets.push({ stage, systems: order });
+    }
+    return buckets;
+}
+/**
+ * Compile system definitions into a deterministic schedule.
+ * Validates unique ids, `dependsOn`, and before/after cycles.
+ *
+ * @capability system-schedule compile fixed/frame/interval system ticks into deterministic ordered stages
+ */
+export function compileSystemSchedule(systems, options) {
+    const fixedStages = options?.fixedStages ?? DEFAULT_FIXED_STAGES;
+    const frameStages = options?.frameStages ?? DEFAULT_FRAME_STAGES;
+    const defaultFixedRate = options?.defaultFixedRate ?? DEFAULT_FIXED_RATE;
+    const systemsById = new Map();
+    const indexOf = new Map();
+    systems.forEach((system, index) => {
+        if (systemsById.has(system.id)) {
+            throw new Error(`system schedule: duplicate system id "${system.id}"`);
+        }
+        systemsById.set(system.id, system);
+        indexOf.set(system.id, index);
+    });
+    for (const system of systems) {
+        for (const dep of system.dependsOn ?? []) {
+            if (!systemsById.has(dep)) {
+                throw new Error(`system schedule: "${system.id}" dependsOn unknown system "${dep}"`);
+            }
+        }
+    }
+    const scheduled = systems.map((system) => {
+        const channel = channelOf(system.tick);
+        return {
+            id: system.id,
+            channel,
+            stage: stageOf(system.tick, channel),
+            rate: rateOf(system.tick, defaultFixedRate),
+            every: everyOf(system.tick),
+            after: afterOf(system.tick),
+            before: beforeOf(system.tick),
+            dependsOn: system.dependsOn ?? [],
+        };
+    });
+    const fixedItems = scheduled.filter((s) => s.channel === "fixed");
+    const rates = [...new Set(fixedItems.map((s) => s.rate ?? defaultFixedRate))].sort((a, b) => b - a);
+    const fixed = rates.map((rate) => {
+        const group = fixedItems.filter((s) => (s.rate ?? defaultFixedRate) === rate);
+        const stages = bucketByStage(group, fixedStages, indexOf);
+        return {
+            rate,
+            stages,
+            order: stages.flatMap((b) => b.systems),
+        };
+    });
+    const frameItems = scheduled.filter((s) => s.channel === "frame");
+    const frame = bucketByStage(frameItems, frameStages, indexOf);
+    const frameOrder = frame.flatMap((b) => b.systems);
+    const intervals = scheduled.filter((s) => s.channel === "interval");
+    // Stable order for intervals: stage buckets then constraints across all interval systems
+    const intervalBuckets = bucketByStage(intervals, fixedStages, indexOf);
+    const intervalOrder = intervalBuckets.flatMap((b) => b.systems);
+    const intervalsOrdered = intervalOrder.map((id) => intervals.find((s) => s.id === id));
+    const manual = scheduled.filter((s) => s.channel === "manual").map((s) => s.id);
+    const eventOnly = scheduled
+        .filter((s) => s.channel === "event")
+        .map((s) => s.id);
+    const tickOrder = [
+        ...fixed.flatMap((g) => g.order),
+        ...frameOrder,
+        ...intervalOrder,
+    ];
+    return {
+        systemsById,
+        scheduled,
+        fixed,
+        frame,
+        frameOrder,
+        intervals: intervalsOrdered,
+        manual,
+        eventOnly,
+        tickOrder,
+    };
+}

package/dist/game/toasts.d.ts

@@ -0,0 +1,43 @@
+/** A transient HUD message that expires on its own — banner, pickup note, alert. */
+export interface Toast<T = string> {
+    /** Stable id for keying in a UI list. */
+    id: string;
+    /** Message payload (a string, or any structured content the HUD renders). */
+    body: T;
+    /** Wall-clock time (seconds) after which the toast should be dropped. */
+    expiresAt: number;
+}
+/**
+ * Append `toast`, keeping only the newest `cap` entries.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export declare function appendToast<T>(toasts: readonly Toast<T>[], toast: Toast<T>, cap: number): readonly Toast<T>[];
+/** Drop every toast whose `expiresAt` is at or before `now`. Returns the same array when nothing expired. */
+export declare function pruneToasts<T>(toasts: readonly Toast<T>[], now: number): readonly Toast<T>[];
+/** Stateful transient-toast list with a size cap and time-to-live eviction. */
+export interface ToastQueue<T = string> {
+    /** Raise a toast at `now` living `ttlSeconds` (falling back to the queue default); returns it. */
+    push(body: T, now: number, ttlSeconds?: number): Toast<T>;
+    /** Evict toasts that have expired as of `now`. */
+    prune(now: number): void;
+    /** Current live toasts, oldest first. */
+    list(): readonly Toast<T>[];
+    /** Remove all toasts. */
+    clear(): void;
+}
+/** Options for {@link createToastQueue}. */
+export interface ToastQueueOptions {
+    /** Maximum toasts retained; older ones fall off. Defaults to 4. */
+    cap?: number;
+    /** Default lifetime in seconds when `push` is not given one. Defaults to 3. */
+    ttlSeconds?: number;
+}
+/**
+ * A capped, self-expiring toast queue — the append-with-limit plus TTL-prune list every HUD hand-rolled
+ * on top of a plain array. Feed it game time: `push` raises a message, `prune(now)` drops expired ones,
+ * `list()` is what the HUD renders. Unlike the append-only event feed, toasts evict themselves.
+ *
+ * @capability toast-feed queue of transient self-expiring on-screen messages (toasts, announcer, kill-feed)
+ */
+export declare function createToastQueue<T = string>(options?: ToastQueueOptions): ToastQueue<T>;