@jgengine/core 0.9.0 → 0.11.0

package/dist/format/speed.d.ts

@@ -0,0 +1,17 @@
+/** Target unit for {@link formatSpeed}: km/h, mph, knots, or raw m/s. */
+export type SpeedUnit = "kmh" | "mph" | "knots" | "ms";
+/** Options for {@link formatSpeed}. */
+export interface SpeedFormat {
+    /** Target unit to convert into from the m/s input. Defaults to `"kmh"`. */
+    unit?: SpeedUnit;
+    /** Fractional digits to show. Defaults to 0. */
+    decimals?: 0 | 1 | 2;
+    /** Append the unit label. Defaults to true; set false to compose custom unit styling. */
+    showUnit?: boolean;
+}
+/**
+ * Format a speed given in meters/second as a HUD-ready string in km/h, mph, knots, or m/s — the one conversion table every speedometer and telemetry readout should share.
+ *
+ * @capability speed-format render a m/s speed as km/h, mph, knots, or m/s for speedometers and telemetry HUDs
+ */
+export declare function formatSpeed(metersPerSecond: number, options?: SpeedFormat): string;

package/dist/format/speed.js

@@ -0,0 +1,25 @@
+const SPEED_UNIT_FACTOR = {
+    kmh: 3.6,
+    mph: 2.2369362920544025,
+    knots: 1.9438444924406046,
+    ms: 1,
+};
+const SPEED_UNIT_LABEL = {
+    kmh: "km/h",
+    mph: "mph",
+    knots: "kn",
+    ms: "m/s",
+};
+/**
+ * Format a speed given in meters/second as a HUD-ready string in km/h, mph, knots, or m/s — the one conversion table every speedometer and telemetry readout should share.
+ *
+ * @capability speed-format render a m/s speed as km/h, mph, knots, or m/s for speedometers and telemetry HUDs
+ */
+export function formatSpeed(metersPerSecond, options = {}) {
+    const unit = options.unit ?? "kmh";
+    const decimals = options.decimals ?? 0;
+    const showUnit = options.showUnit ?? true;
+    const converted = Math.max(0, metersPerSecond) * SPEED_UNIT_FACTOR[unit];
+    const text = converted.toFixed(decimals);
+    return showUnit ? `${text} ${SPEED_UNIT_LABEL[unit]}` : text;
+}

package/dist/game/connectedPlayers.d.ts

@@ -0,0 +1,30 @@
+import type { InputFrame } from "../runtime/inputSnapshot.js";
+/** A player currently joined to a hosted world — the unit a shared-world loop iterates instead of `ctx.player`. Frozen by the registry (see {@link ConnectedPlayers.get}); fields are `readonly` so a caller can't edit its own copy and assume the change stuck. */
+export interface ConnectedPlayer {
+    readonly userId: string;
+    readonly isNew: boolean;
+    /** This player's latest {@link InputFrame}, written by the host each time the client sends input; `null` until the first frame arrives. The per-player movement seam reads it in `onTick`. */
+    readonly input: InputFrame | null;
+}
+/**
+ * The set of players connected to one hosted world. A single-player game uses `ctx.player`; a shared-world loop
+ * reads `ctx.game.players` so `onTick` can advance every connected hero, not just the one local player. The host
+ * (`HostedGameRunner`) drives `join`/`leave`/`setInput`; game code reads `list`/`ids`/`has`/`count`/`input`.
+ */
+export interface ConnectedPlayers {
+    join(userId: string, isNew: boolean): void;
+    leave(userId: string): boolean;
+    has(userId: string): boolean;
+    /** Returns a frozen `ConnectedPlayer` — mutating it (or reassigning `.input`) throws instead of corrupting the registry. */
+    get(userId: string): ConnectedPlayer | null;
+    /** Frozen `ConnectedPlayer` entries, same immutability contract as {@link get}. */
+    list(): readonly ConnectedPlayer[];
+    ids(): readonly string[];
+    count(): number;
+    /** Record a player's latest input frame (host-driven); a no-op for a player that hasn't joined. */
+    setInput(userId: string, frame: InputFrame): void;
+    /** This player's latest input frame, or `null` if they haven't joined or no frame has arrived yet. */
+    input(userId: string): InputFrame | null;
+}
+/** Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them. */
+export declare function createConnectedPlayers(): ConnectedPlayers;

package/dist/game/connectedPlayers.js

@@ -0,0 +1,21 @@
+/** Build an empty {@link ConnectedPlayers} registry — the host joins/leaves players; the game loop reads them. */
+export function createConnectedPlayers() {
+    const players = new Map();
+    return {
+        join(userId, isNew) {
+            players.set(userId, Object.freeze({ userId, isNew, input: null }));
+        },
+        leave: (userId) => players.delete(userId),
+        has: (userId) => players.has(userId),
+        get: (userId) => players.get(userId) ?? null,
+        list: () => Array.from(players.values()),
+        ids: () => Array.from(players.keys()),
+        count: () => players.size,
+        setInput(userId, frame) {
+            const player = players.get(userId);
+            if (player !== undefined)
+                players.set(userId, Object.freeze({ ...player, input: frame }));
+        },
+        input: (userId) => players.get(userId)?.input ?? null,
+    };
+}

package/dist/game/cosmetics.d.ts

@@ -21,5 +21,14 @@ export interface Cosmetics {
     get(userId: string): Readonly<Record<string, string>>;
     snapshot(userId: string): Record<string, string>;
     hydrate(userId: string, state: Record<string, string>): void;
+    /** Snapshot every user's equipped slots for a whole-world save. */
+    snapshotAll(): Record<string, Record<string, string>>;
+    /** Restore every user's equipped slots from a {@link snapshotAll} payload. */
+    hydrateAll(state: Record<string, Record<string, string>>): void;
 }
+/**
+ * Equip cosmetic skins and customizations by slot, independent of gameplay stats.
+ *
+ * @capability cosmetics equip cosmetic skins and customizations by slot
+ */
 export declare function createCosmetics(deps?: CosmeticsDeps): Cosmetics;

package/dist/game/cosmetics.js

@@ -1,4 +1,9 @@
 const EMPTY_SLOTS = Object.freeze({});
+/**
+ * Equip cosmetic skins and customizations by slot, independent of gameplay stats.
+ *
+ * @capability cosmetics equip cosmetic skins and customizations by slot
+ */
 export function createCosmetics(deps = {}) {
     const definitions = new Map();
     const equipped = new Map();
@@ -47,5 +52,16 @@ export function createCosmetics(deps = {}) {
         hydrate(userId, state) {
             equipped.set(userId, { ...state });
         },
+        snapshotAll() {
+            const out = {};
+            for (const [userId, slots] of equipped)
+                out[userId] = { ...slots };
+            return out;
+        },
+        hydrateAll(state) {
+            equipped.clear();
+            for (const [userId, slots] of Object.entries(state))
+                equipped.set(userId, { ...slots });
+        },
     };
 }

package/dist/game/defineGame.d.ts

@@ -1,18 +1,37 @@
 import type { ActionCodesMap } from "../input/actionBindings.js";
 import type { GameFeedOptions } from "./feed.js";
+import type { GamePhase } from "./gamePhase.js";
+import type { SystemDefinition } from "./defineSystem.js";
 import type { ItemTraits } from "../inventory/inventoryModel.js";
 import type { StorageTier } from "../inventory/storageTier.js";
+import type { GameContext } from "../runtime/gameContext.js";
+import type { ReplicationPolicy } from "../runtime/worldProjection.js";
+import type { RuntimeSaveMode } from "../runtime/runtimeSave.js";
 import type { SaveConfig } from "../runtime/save.js";
 import { type AssetCatalog, type ModelAssetRef } from "../scene/assetCatalog.js";
 import { type EntityStore } from "../scene/entityStore.js";
+import type { StoreHandle } from "../store/defineStore.js";
 import type { TimeConfig } from "../time/simClock.js";
 import type { WorldFeature } from "../world/features.js";
+/** Tunes offline whole-world save (`defineGame({ persist })`). Defaults: continuous `autosave` to `localStorage`, one slot, no version. */
+export interface PersistConfig {
+    /** `"autosave"` (default) writes on a debounce after any change; `"manual"` writes only on `ctx.game.save.checkpoint()` (save points / quest triggers). */
+    mode?: RuntimeSaveMode;
+    /** `"local"` (default) persists to `localStorage`; `"memory"` keeps saves in-session only (tests, "no persistence" mode). */
+    storage?: "local" | "memory";
+    /** Save-format version; bump when the world shape changes in a save-breaking way. */
+    version?: number;
+    /** Autosave debounce in ms (autosave mode). Default 3000. */
+    autosaveMs?: number;
+}
+/** World gravity and jump tuning, plus scene-object collision opt-ins, for the game's physics step. */
 export interface PhysicsConfig {
     gravity?: number;
     jumpVelocity?: number;
     /** Opt placed scene objects into projectile raycasts as blocking cover AABBs. Default false — enabling changes where shots land. */
     projectileObstacles?: boolean;
 }
+/** Shape of one named inventory a game declares — slot count, accepted item types, HUD binding. */
 export interface InventoryDeclaration {
     slots: number;
     hud?: string;
@@ -21,20 +40,122 @@ export interface InventoryDeclaration {
     applyModifiers?: boolean;
     tier?: StorageTier;
 }
+/** Hosting mode for a game's multiplayer server: `"persistent"`, or a custom mode with its own options. */
 export type GameServerConfig = "persistent" | {
     mode: string;
     [key: string]: unknown;
 };
+/** Identity of a player joining or leaving a hosted world — passed to the multiplayer loop hooks. */
+export interface LoopPlayer {
+    userId: string;
+    isNew: boolean;
+}
+/** Lifecycle hooks a game implements to drive init, per-tick simulation, and player join/leave. */
 export interface GameLoop<TContext = unknown> {
     onInit?(ctx: TContext): void;
-    onNewPlayer?(ctx: TContext): void;
+    /** Once per join. `player` identifies the joiner in a hosted world; single-player callers may omit it. */
+    onNewPlayer?(ctx: TContext, player?: LoopPlayer): void;
     onTick?(ctx: TContext, dt: number): void;
+    /** Once per leave in a hosted world (never fired single-player). Despawn the player's entities / release their slots here. */
+    onPlayerLeave?(ctx: TContext, player: LoopPlayer): void;
+    /** Scenario/run reset — clear run-scoped state. Composed system `reset` hooks run here too. */
+    onReset?(ctx: TContext): void;
+    /** World teardown (mode switch, unmount). Composed system `dispose` hooks run here too. */
+    onDispose?(ctx: TContext): void;
+}
+/**
+ * A scope cleanups register onto, run in LIFO order exactly once — the shared shape behind every
+ * teardown path in this codebase (a looping audio handle's source/gain nodes, a GPU texture swap on
+ * entity/scene replacement). Registering after `dispose()` has already run invokes the cleanup
+ * immediately instead of dropping it, so a resource created by a still-in-flight async step (e.g. a
+ * decoded audio buffer) never leaks past a `stop()`/unmount that raced ahead of it.
+ * @internal
+ */
+export interface DisposerScope {
+    onDispose(cleanup: () => void): void;
+}
+/** @internal */
+export interface Disposer extends DisposerScope {
+    dispose(): void;
+}
+/** @internal */
+export declare function createDisposer(): Disposer;
+/**
+ * Opt-in `ctx.game.*` subsystems. Absent = off: the game doesn't carry (or expose) it, and `ctx.game.<name>`
+ * is `undefined`. Present (`true`) builds it. The universal base — `commands`, `events`, `store`, `feed` — is
+ * always on and not listed here. This is what keeps core genre-agnostic: a puzzle game isn't handed an MMO's
+ * leaderboard/roster/turn plumbing it never asked for.
+ */
+export interface GameFeatures {
+    /** Quest/mission journal (`ctx.game.quest`) — quest-driven games. */
+    quest?: boolean;
+    /** Shop/vendor barter (`ctx.game.trade`) — games with buy/sell economies. */
+    trade?: boolean;
+    /** Earned unlockable content (`ctx.game.unlocks`) — progression-gated games. */
+    unlocks?: boolean;
+    /** Cosmetic skins/customization (`ctx.player.cosmetics`) — appearance-customization games. */
+    cosmetics?: boolean;
+    /** Owned/captured entity roster (`ctx.game.roster`) — pet/monster collection games. */
+    roster?: boolean;
+    /** Card pile zones (`ctx.game.cards`) — deckbuilders, card games. */
+    cards?: boolean;
+    /** Turn/phase loop (`ctx.game.turn`) — turn-based games. */
+    turn?: boolean;
+    /** Talkable-NPC dialogue bridge (`ctx.game.dialogue`) — auto-registers `dialogue.open`/`dialogue.close`; dialogue-driven games. */
+    dialogue?: boolean;
+    /** Lap/checkpoint race state (`ctx.game.race`) — racers. */
+    race?: boolean;
+    /** Competitive score tracking (`ctx.game.leaderboard`) — ranked/arcade games. */
+    leaderboard?: boolean;
+    /** Friends/party/presence/emotes/world-invites (`ctx.game.social`) — social/MMO games. */
+    social?: boolean;
+    /** Channels + messages (`ctx.game.chat`) — implies `social`; multiplayer/social games. */
+    chat?: boolean;
+    /** Connected-player set (`ctx.game.players`) — shared-world hosts whose loop ticks every player, not just `ctx.player`. */
+    players?: boolean;
+}
+/**
+ * Declarative start/restart run lifecycle: the state transitions a game's run phase every genre repeats
+ * (title screen → live run → live run → title screen again), expressed as pure functions over one typed
+ * {@link StoreHandle} slot instead of hand-rolled `commands.define("start"/"restart")` glue that re-derives
+ * phase after every mutation. `start`/`restart` receive the store's own value type — the store's `TState`,
+ * never `ctx.game.store.get(key) as T` — and return the next value; the runtime writes it back and derives
+ * {@link GamePhase} from it via `phaseOf` in one place, so every adopting game gets identical, correct
+ * phase-sync for free.
+ *
+ * @capability lifecycle declarative start/restart run flow — the engine owns the command glue and phase sync, the game supplies pure state transitions
+ */
+export interface LifecycleConfig<TState = unknown> {
+    /** The store slot holding this game's run state; `start`/`restart` transform its current value. */
+    store: StoreHandle<TState>;
+    /** Pure transition into a live run. `input` is whatever the `start` command was invoked with (e.g. a chosen difficulty/tier). */
+    start(state: TState, ctx: GameContext, input?: unknown): TState;
+    /** Pure transition back into a fresh live run — same shape as `start` but never re-shows the menu first. */
+    restart(state: TState, ctx: GameContext): TState;
+    /** Derive the canonical {@link GamePhase} from the run state. The runtime calls this after every loop hook (`onInit`/`onNewPlayer`/`onTick`) as well as after `start`/`restart`, publishing the result only when it changed — so a game never hand-writes a per-tick `setGamePhase` ternary or its own previous-phase diff. */
+    phaseOf(state: TState): GamePhase;
+    /** Override the registered command names — default `"start"`/`"restart"` — for games whose input bindings already name them differently. */
+    commands?: {
+        start?: string;
+        restart?: string;
+    };
 }
+/** Fully-resolved game description produced by {@link defineGame} — assets, scene, and opted-in subsystems. */
 export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> {
     name: string;
     assets: AssetCatalog<TAssetRef>;
     multiplayer: TMultiplayer;
+    /** @deprecated No longer the runtime store — `createGameContext` mints a fresh per-context `EntityStore` so one host can serve many worlds without state bleed (#632). Retained only for API compatibility; read `ctx.scene.entity` instead. */
     scene: EntityStore;
+    /** Opt-in `ctx.game.*` subsystems beyond the always-on base; omitted systems are `undefined` on `ctx.game`. */
+    features?: GameFeatures;
+    /**
+     * Composable game capabilities — the preferred authoring path for runtime behavior.
+     * Each system owns timing, events, and optional save/replication/reset/disposal.
+     * Installing a system with `feature` enables that `ctx.game.*` capability without a redundant flag.
+     * Classic `loop` hooks still run for incremental migration (systems tick first, then `loop.onTick`).
+     */
+    systems?: readonly SystemDefinition[];
     world?: WorldFeature;
     physics?: PhysicsConfig;
     /** Simulation clock: real→game time scale, selectable speeds, calendar. Exposed as `ctx.time`; the shell feeds its scaled dt to `loop.onTick`. */
@@ -45,10 +166,28 @@ export interface GameDefinition<TAssetRef extends ModelAssetRef = ModelAssetRef,
     input?: ActionCodesMap;
     server?: GameServerConfig;
     save?: SaveConfig;
+    /** Offline/single-player whole-world save. `true` autosaves the entire game to `localStorage`; a config object tunes the mode/cadence/target. Binds `ctx.game.save` — the game drives save points and restore. Ignored for multiplayer worlds (the host persists). */
+    persist?: boolean | PersistConfig;
     ui?: unknown;
-    loop?: GameLoop<any>;
+    loop?: GameLoop<GameContext>;
+    /** Declarative start/restart run lifecycle — see {@link LifecycleConfig}. Omitted games keep hand-rolling their own commands. */
+    lifecycle?: LifecycleConfig;
+    /**
+     * Host-side per-viewer replication policy — private-state and area-of-interest projection over the
+     * wire. Applied on every authoritative host (ws, Convex, loopback); clients need not set it. Unset
+     * replicates the whole world to every client (today's behavior). Changes only what each client sees,
+     * never the simulation, so the game plays identically with or without it.
+     */
+    replication?: ReplicationPolicy;
 }
+/** Input to {@link defineGame} — a `GameDefinition` with `scene` derived and `assets` optional. */
 export type GameDefinitionConfig<TAssetRef extends ModelAssetRef = ModelAssetRef, TMultiplayer = unknown> = Omit<GameDefinition<TAssetRef, TMultiplayer>, "scene" | "assets"> & {
     assets?: AssetCatalog<TAssetRef>;
 };
+/**
+ * Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`,
+ * OR-merges `features` from installed systems, and composes `loop` from `systems` + any classic hooks.
+ *
+ * @capability define-game single public game-authoring path — compose systems, world, and loop in one definition
+ */
 export declare function defineGame<TAssetRef extends ModelAssetRef, TMultiplayer>(config: GameDefinitionConfig<TAssetRef, TMultiplayer>): GameDefinition<TAssetRef, TMultiplayer>;

package/dist/game/defineGame.js

@@ -1,8 +1,46 @@
+import { mergeSystemFeatures } from "./defineSystem.js";
+import { composeGameLoop } from "./systemRuntime.js";
 import { createAssetCatalog } from "../scene/assetCatalog.js";
 import { createEntityStore } from "../scene/entityStore.js";
+/** @internal */
+export function createDisposer() {
+    const cleanups = [];
+    let disposed = false;
+    return {
+        onDispose(cleanup) {
+            if (disposed) {
+                cleanup();
+                return;
+            }
+            cleanups.push(cleanup);
+        },
+        dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            while (cleanups.length > 0) {
+                cleanups.pop()();
+            }
+        },
+    };
+}
+/**
+ * Task-first entry point for authoring a game: fills in `scene` and default `assets`, validates `name`,
+ * OR-merges `features` from installed systems, and composes `loop` from `systems` + any classic hooks.
+ *
+ * @capability define-game single public game-authoring path — compose systems, world, and loop in one definition
+ */
 export function defineGame(config) {
     if (config.name.trim().length === 0) {
         throw new Error("defineGame: name must be non-empty");
     }
-    return { ...config, scene: createEntityStore(), assets: config.assets ?? createAssetCatalog() };
+    const features = mergeSystemFeatures(config.features, config.systems);
+    const loop = composeGameLoop(config.systems, config.loop);
+    return {
+        ...config,
+        features,
+        loop,
+        scene: createEntityStore(),
+        assets: config.assets ?? createAssetCatalog(),
+    };
 }

package/dist/game/defineSystem.d.ts

@@ -0,0 +1,88 @@
+import type { GameFeatures } from "./defineGame.js";
+import type { GameContext } from "../runtime/gameContext.js";
+import type { SnapshotModule } from "../runtime/worldSnapshot.js";
+/**
+ * How a system is scheduled. Omit `tick` (or use only `events`) for event-driven systems.
+ * Multiple systems may share the same channel; order within a channel is deterministic by stage
+ * then optional `before`/`after` constraints — never import order.
+ */
+export type SystemTick = {
+    type: "fixed";
+    /** Steps per game-second. Default 60. */
+    rate?: number;
+    stage?: string;
+    after?: string | readonly string[];
+    before?: string | readonly string[];
+} | {
+    type: "frame";
+    stage?: string;
+    after?: string | readonly string[];
+    before?: string | readonly string[];
+} | {
+    type: "interval";
+    /** Period in game-seconds between runs. */
+    every: number;
+    stage?: string;
+    after?: string | readonly string[];
+    before?: string | readonly string[];
+} | {
+    type: "manual";
+};
+/** Event name → handler. Payload is the engine event shape for that name. */
+export type SystemEventHandlers = {
+    readonly [eventName: string]: (ctx: GameContext, event: unknown) => void;
+};
+/**
+ * A reusable game capability — lifecycle, timing, events, and optional save / replication /
+ * reset / disposal. Pass instances via `defineGame({ systems })`. Prefer one system per meaningful
+ * capability (`combat`, `quests`), not per micro-tick.
+ *
+ * @capability game-system declare a composable capability with its own schedule and lifecycle
+ */
+export interface SystemDefinition {
+    readonly id: string;
+    /**
+     * Timing channel. Omit for event-only systems (handlers in {@link events} still run).
+     * `manual` systems install but never auto-tick — call them yourself or leave as infrastructure.
+     */
+    tick?: SystemTick;
+    /** Other system ids that must also be installed; validated when the schedule compiles. */
+    dependsOn?: readonly string[];
+    /**
+     * Opt-in `ctx.game.*` feature(s) this system needs. Installing the system enables them — no
+     * separate `features: { quest: true }` flag required (you may still set flags for systems-free games).
+     */
+    feature?: keyof GameFeatures | readonly (keyof GameFeatures)[];
+    /** Once per world boot, before {@link start}. */
+    create?(ctx: GameContext): void;
+    /** Once per world boot, after every system's `create`. */
+    start?(ctx: GameContext): void;
+    /** Per schedule fire — `dt` is game-seconds for the step (fixed/frame/interval). */
+    update?(ctx: GameContext, dt: number): void;
+    events?: SystemEventHandlers;
+    /**
+     * Whole-world save contribution. A factory form runs after `create` so closures can close over
+     * system state. Registered into `ctx.game.save` coverage.
+     */
+    save?: SnapshotModule | ((ctx: GameContext) => SnapshotModule | undefined);
+    /**
+     * Host→client replication contribution. Same factory form as {@link save}; registered into
+     * `ctx.snapshot` / `ctx.hydrate`.
+     */
+    replicate?: SnapshotModule | ((ctx: GameContext) => SnapshotModule | undefined);
+    /** Run on scenario/run reset — clear run-scoped state while meta may survive. */
+    reset?(ctx: GameContext): void;
+    /** Run when the world is torn down (mode switch, unmount). */
+    dispose?(ctx: GameContext): void;
+}
+/**
+ * Declare a composable game system. Pure data + hooks — the engine compiles the schedule and
+ * installs lifecycle when the game boots.
+ */
+export declare function defineSystem(definition: SystemDefinition): SystemDefinition;
+/** Collect feature flags implied by a system list (OR-merge; installing a system activates its capability).
+ * @internal */
+export declare function featuresFromSystems(systems: readonly SystemDefinition[] | undefined): GameFeatures;
+/** OR-merge explicit `features` with flags implied by installed systems.
+ * @internal */
+export declare function mergeSystemFeatures(explicit: GameFeatures | undefined, systems: readonly SystemDefinition[] | undefined): GameFeatures | undefined;

package/dist/game/defineSystem.js

@@ -0,0 +1,45 @@
+/**
+ * Declare a composable game system. Pure data + hooks — the engine compiles the schedule and
+ * installs lifecycle when the game boots.
+ */
+export function defineSystem(definition) {
+    if (definition.id.trim().length === 0) {
+        throw new Error("defineSystem: id must be non-empty");
+    }
+    if (definition.tick?.type === "interval" && !(definition.tick.every > 0)) {
+        throw new Error(`defineSystem "${definition.id}": interval.every must be > 0`);
+    }
+    if (definition.tick?.type === "fixed" && definition.tick.rate !== undefined && !(definition.tick.rate > 0)) {
+        throw new Error(`defineSystem "${definition.id}": fixed.rate must be > 0`);
+    }
+    return definition;
+}
+/** Collect feature flags implied by a system list (OR-merge; installing a system activates its capability).
+ * @internal */
+export function featuresFromSystems(systems) {
+    const out = {};
+    if (systems === undefined)
+        return out;
+    for (const system of systems) {
+        if (system.feature === undefined)
+            continue;
+        const keys = typeof system.feature === "string" ? [system.feature] : system.feature;
+        for (const key of keys)
+            out[key] = true;
+    }
+    return out;
+}
+/** OR-merge explicit `features` with flags implied by installed systems.
+ * @internal */
+export function mergeSystemFeatures(explicit, systems) {
+    const fromSystems = featuresFromSystems(systems);
+    if (explicit === undefined) {
+        return Object.keys(fromSystems).length === 0 ? undefined : fromSystems;
+    }
+    const merged = { ...explicit };
+    for (const key of Object.keys(fromSystems)) {
+        if (fromSystems[key] === true)
+            merged[key] = true;
+    }
+    return merged;
+}

package/dist/game/dialogue.d.ts

@@ -0,0 +1,33 @@
+import { type StoreHandle } from "../store/defineStore.js";
+/** Store slot holding the id of the dialogue currently open, or absent when none is showing. */
+export declare const DIALOGUE_STORE_KEY = "jg.dialogue";
+/** Typed handle onto the open-dialogue slot — React reads it via `useOpenDialogueId`; game code uses `ctx.game.dialogue`. */
+export declare const dialogueSlot: StoreHandle<string | undefined>;
+/** The minimal keyed-store surface {@link createGameDialogue} writes through — satisfied by `ctx.game.store`. */
+interface DialogueStore {
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    delete(key: string): void;
+}
+/**
+ * `ctx.game.dialogue` — the blessed open/close bridge for the `talkable`/`dialogue.open` prompt flow. A game
+ * opts in with `features.dialogue`, and the runtime both builds this surface and auto-registers the
+ * `dialogue.open`/`dialogue.close` commands a `talkable(id)` prompt dispatches, so no game re-implements the
+ * store, the command pair, or the open/close bookkeeping. React reads the open id via `useOpenDialogueId`.
+ */
+export interface GameDialogue {
+    /** Show the dialogue with this catalog id (what a `talkable(id)` prompt / `dialogue.open` command carries). */
+    open(id: string): void;
+    /** Close whatever dialogue is open — the no-op when nothing is showing. */
+    close(): void;
+    /** The open dialogue id, or `null` when none is showing. */
+    openId(): string | null;
+}
+/**
+ * Build a {@link GameDialogue} over one keyed-store slot. Writes flow through the reactive store, so opening
+ * or closing bumps `ctx.version()` and a `useOpenDialogueId` selector re-renders.
+ *
+ * @capability dialogue-bridge open/close the talkable→DialogueBox flow with no per-game store or command glue
+ */
+export declare function createGameDialogue(store: DialogueStore): GameDialogue;
+export {};

package/dist/game/dialogue.js

@@ -0,0 +1,21 @@
+import { defineStore } from "../store/defineStore.js";
+/** Store slot holding the id of the dialogue currently open, or absent when none is showing. */
+export const DIALOGUE_STORE_KEY = "jg.dialogue";
+/** Typed handle onto the open-dialogue slot — React reads it via `useOpenDialogueId`; game code uses `ctx.game.dialogue`. */
+export const dialogueSlot = defineStore(DIALOGUE_STORE_KEY, undefined);
+/**
+ * Build a {@link GameDialogue} over one keyed-store slot. Writes flow through the reactive store, so opening
+ * or closing bumps `ctx.version()` and a `useOpenDialogueId` selector re-renders.
+ *
+ * @capability dialogue-bridge open/close the talkable→DialogueBox flow with no per-game store or command glue
+ */
+export function createGameDialogue(store) {
+    return {
+        open: (id) => store.set(DIALOGUE_STORE_KEY, id),
+        close: () => store.delete(DIALOGUE_STORE_KEY),
+        openId: () => {
+            const value = store.get(DIALOGUE_STORE_KEY);
+            return typeof value === "string" ? value : null;
+        },
+    };
+}