@jgengine/core 0.9.0 → 0.11.0

package/dist/sensor/recordingBuffer.d.ts

@@ -31,5 +31,6 @@ export interface RecordingBuffer<T> {
  * then seek/scrub the recording independent of the live sim. Frames are
  * expected in non-decreasing `t` order (one push per tick); `seek`/`range`
  * binary-search on that assumption.
- */
+  * @internal
+  */
 export declare function createRecordingBuffer<T>(options?: RecordingBufferOptions): RecordingBuffer<T>;

package/dist/sensor/recordingBuffer.js

@@ -17,7 +17,8 @@ function evict(frames, options) {
  * then seek/scrub the recording independent of the live sim. Frames are
  * expected in non-decreasing `t` order (one push per tick); `seek`/`range`
  * binary-search on that assumption.
- */
+  * @internal
+  */
 export function createRecordingBuffer(options = {}) {
     const frames = [];
     function floorIndex(t) {

package/dist/sensor/replayLoop.d.ts

@@ -14,6 +14,7 @@ export interface ReplayLoop<T> {
     duration(): number;
     sample(t: number): T | null;
 }
+/** @internal */
 export declare function createReplayLoop<T>(buffer: RecordingBuffer<T>, options?: ReplayLoopOptions<T>): ReplayLoop<T>;
 export interface ReplayEntityDeps {
     has(id: string): boolean;
@@ -29,11 +30,14 @@ export interface RecordedPoseLike {
     position: readonly [number, number, number];
     rotationY?: number;
 }
-/** Linear pose blend for `ReplayLoopOptions.interpolate` — position lerp plus shortest-arc yaw. */
+/** Linear pose blend for `ReplayLoopOptions.interpolate` — position lerp plus shortest-arc yaw.
+ * @internal
+ */
 export declare function interpolateRecordedPose<T extends RecordedPoseLike>(before: T, after: T, alpha: number): T;
 /**
  * Reconcile a replayed pose against an entity store: spawns the ghost on the first non-null sample,
  * poses it while samples flow, despawns it through grace gaps or after the recording empties.
  * `deps` matches `ctx.scene.entity` structurally — pass `{ has: (id) => ctx.scene.entity.get(id) !== null, spawn, setPose, despawn }`.
- */
+  * @internal
+  */
 export declare function syncReplayEntity(deps: ReplayEntityDeps, id: string, pose: RecordedPoseLike | null, dt?: number): void;

package/dist/sensor/replayLoop.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createReplayLoop(buffer, options = {}) {
     const grace = Math.max(0, options.spawnGraceSeconds ?? 0);
     const interpolate = options.interpolate;
@@ -26,7 +27,9 @@ export function createReplayLoop(buffer, options = {}) {
         },
     };
 }
-/** Linear pose blend for `ReplayLoopOptions.interpolate` — position lerp plus shortest-arc yaw. */
+/** Linear pose blend for `ReplayLoopOptions.interpolate` — position lerp plus shortest-arc yaw.
+ * @internal
+ */
 export function interpolateRecordedPose(before, after, alpha) {
     let yawDelta = (after.rotationY ?? 0) - (before.rotationY ?? 0);
     while (yawDelta > Math.PI)
@@ -47,7 +50,8 @@ export function interpolateRecordedPose(before, after, alpha) {
  * Reconcile a replayed pose against an entity store: spawns the ghost on the first non-null sample,
  * poses it while samples flow, despawns it through grace gaps or after the recording empties.
  * `deps` matches `ctx.scene.entity` structurally — pass `{ has: (id) => ctx.scene.entity.get(id) !== null, spawn, setPose, despawn }`.
- */
+  * @internal
+  */
 export function syncReplayEntity(deps, id, pose, dt) {
     if (pose === null) {
         if (deps.has(id))

package/dist/sensor/revealQuery.d.ts

@@ -18,5 +18,6 @@ export interface RevealQuery {
  * the same unfiltered radius query, scoped to catalog-declared tags and shaped
  * for a vision readout (Dark Sight / detective-vision reveal) instead of damage
  * resolution — it never consults an occluder, by design.
- */
+  * @internal
+  */
 export declare function createRevealQuery(options: RevealQueryOptions): RevealQuery;

package/dist/sensor/revealQuery.js

@@ -5,7 +5,8 @@ import { distanceBetween } from "../scene/spatial.js";
  * the same unfiltered radius query, scoped to catalog-declared tags and shaped
  * for a vision readout (Dark Sight / detective-vision reveal) instead of damage
  * resolution — it never consults an occluder, by design.
- */
+  * @internal
+  */
 export function createRevealQuery(options) {
     const { resolvePosition, resolveTags, candidates } = options;
     return {

package/dist/sensor/visionCone.d.ts

@@ -9,11 +9,17 @@ export interface VisionConeConfig {
     /** Full cone opening angle in radians (matches `TelegraphShape`'s cone `angle`). */
     angle: number;
 }
-/** 2D segment intersection on the XZ plane (collinear overlaps count) — the LoS building block `revealQuery`/`frustumSensor` never shipped (#286.5). */
+/** 2D segment intersection on the XZ plane (collinear overlaps count) — the LoS building block `revealQuery`/`frustumSensor` never shipped (#286.5).
+ * @internal
+ */
 export declare function segmentsIntersect(a1: VisionPoint, a2: VisionPoint, b1: VisionPoint, b2: VisionPoint): boolean;
-/** True when no wall segment crosses the sight line. */
+/** True when no wall segment crosses the sight line.
+ * @internal
+ */
 export declare function hasWallLineOfSight(from: VisionPoint, to: VisionPoint, walls: readonly VisionWall[]): boolean;
-/** Angle + range test only — no occlusion. `heading` is engine yaw (radians, `atan2(dx, dz)`). */
+/** Angle + range test only — no occlusion. `heading` is engine yaw (radians, `atan2(dx, dz)`).
+ * @internal
+ */
 export declare function pointInCone(origin: VisionPoint, heading: number, config: VisionConeConfig, point: VisionPoint): boolean;
 export interface VisionTarget<TId extends string = string> {
     id: TId;
@@ -28,4 +34,5 @@ export interface VisionCone {
     canSee(origin: VisionPoint, heading: number, target: VisionPoint): boolean;
     visibleTargets<TId extends string>(origin: VisionPoint, heading: number, targets: readonly VisionTarget<TId>[]): TId[];
 }
+/** @internal */
 export declare function createVisionCone(config: VisionConeConfig, walls?: readonly VisionWall[]): VisionCone;

package/dist/sensor/visionCone.js

@@ -12,7 +12,9 @@ function onSegment(ax, az, bx, bz, cx, cz) {
         Math.min(az, bz) - 1e-9 <= cz &&
         cz <= Math.max(az, bz) + 1e-9);
 }
-/** 2D segment intersection on the XZ plane (collinear overlaps count) — the LoS building block `revealQuery`/`frustumSensor` never shipped (#286.5). */
+/** 2D segment intersection on the XZ plane (collinear overlaps count) — the LoS building block `revealQuery`/`frustumSensor` never shipped (#286.5).
+ * @internal
+ */
 export function segmentsIntersect(a1, a2, b1, b2) {
     const o1 = orientation(a1[0], a1[1], a2[0], a2[1], b1[0], b1[1]);
     const o2 = orientation(a1[0], a1[1], a2[0], a2[1], b2[0], b2[1]);
@@ -30,7 +32,9 @@ export function segmentsIntersect(a1, a2, b1, b2) {
         return true;
     return false;
 }
-/** True when no wall segment crosses the sight line. */
+/** True when no wall segment crosses the sight line.
+ * @internal
+ */
 export function hasWallLineOfSight(from, to, walls) {
     for (const wall of walls) {
         if (segmentsIntersect(from, to, wall.from, wall.to))
@@ -38,7 +42,9 @@ export function hasWallLineOfSight(from, to, walls) {
     }
     return true;
 }
-/** Angle + range test only — no occlusion. `heading` is engine yaw (radians, `atan2(dx, dz)`). */
+/** Angle + range test only — no occlusion. `heading` is engine yaw (radians, `atan2(dx, dz)`).
+ * @internal
+ */
 export function pointInCone(origin, heading, config, point) {
     const dx = point[0] - origin[0];
     const dz = point[1] - origin[1];
@@ -54,6 +60,7 @@ export function pointInCone(origin, heading, config, point) {
         delta += Math.PI * 2;
     return Math.abs(delta) <= config.angle / 2;
 }
+/** @internal */
 export function createVisionCone(config, walls = []) {
     function canSee(origin, heading, target) {
         return pointInCone(origin, heading, config, target) && hasWallLineOfSight(origin, target, walls);

package/dist/session/contestedChannel.d.ts

@@ -33,4 +33,5 @@ export interface ContestedChannel {
     remaining(): number;
     snapshot(): ContestedSnapshot;
 }
+/** @internal */
 export declare function createContestedChannel(config: ContestedChannelConfig): ContestedChannel;

package/dist/session/contestedChannel.js

@@ -10,6 +10,7 @@ function anyContester(occupants, owner) {
     }
     return false;
 }
+/** @internal */
 export function createContestedChannel(config) {
     const duration = config.duration > 0 ? config.duration : Number.EPSILON;
     const interruptOnDamage = config.interruptOnDamage ?? true;

package/dist/session/extraction.d.ts

@@ -51,4 +51,5 @@ export interface RaidSession {
     status(userId: string): RaidStatus;
     playerSnapshot(userId: string): RaidPlayerSnapshot;
 }
+/** @internal */
 export declare function createRaidSession(config: RaidSessionConfig): RaidSession;

package/dist/session/extraction.js

@@ -18,6 +18,7 @@ function mergeAll(containers) {
             out.push({ itemId, count });
     return out;
 }
+/** @internal */
 export function createRaidSession(config) {
     const points = new Map();
     for (const point of config.extracts)

package/dist/session/roles.d.ts

@@ -3,4 +3,10 @@ export interface RoleSpec {
     count?: number;
     ratio?: number;
 }
+/**
+ * Assign hidden or team roles across players by ratio — social-deduction and team-shuffle setups.
+ *
+ * @capability role-assign assign hidden or team roles to players by ratio
+  * @internal
+  */
 export declare function assignRoles(userIds: readonly string[], roles: readonly RoleSpec[], rng?: () => number): Record<string, string>;

package/dist/session/roles.js

@@ -1,4 +1,10 @@
 import { shuffleWithRng } from "../cards/cardPile.js";
+/**
+ * Assign hidden or team roles across players by ratio — social-deduction and team-shuffle setups.
+ *
+ * @capability role-assign assign hidden or team roles to players by ratio
+  * @internal
+  */
 export function assignRoles(userIds, roles, rng = Math.random) {
     if (roles.length === 0)
         throw new Error("assignRoles needs at least one role");

package/dist/session/roundState.d.ts

@@ -72,8 +72,16 @@ export interface RoundState<TPhase extends string = RoundPhase> {
     roleOf(team: string): string | undefined;
     snapshot(): RoundSnapshot<TPhase>;
 }
+/** @internal */
 export declare function lossBonusFor(rule: LossBonusRule | undefined, streak: number): number;
+/**
+ * Run a match as repeating buy/action/end round phases with per-round win rewards and loss-streak economy.
+ *
+ * @capability match-rounds run buy/action/end round phases with per-round economy
+  * @internal
+  */
 export declare function createRoundState(config: RoundConfig<RoundPhase>): RoundState<RoundPhase>;
+/** @internal */
 export declare function createRoundState<TPhase extends string>(config: RoundConfig<TPhase> & {
     phaseOrder: readonly TPhase[];
 }): RoundState<TPhase>;

package/dist/session/roundState.js

@@ -1,4 +1,5 @@
 const DEFAULT_PHASE_ORDER = ["buy", "live", "end"];
+/** @internal */
 export function lossBonusFor(rule, streak) {
     if (rule === undefined)
         return 0;
@@ -17,6 +18,7 @@ function isConcludable(order, phase) {
     const idx = order.indexOf(phase);
     return idx > 0 && idx < order.length - 1;
 }
+/** @internal */
 export function createRoundState(config) {
     const order = config.phaseOrder ?? DEFAULT_PHASE_ORDER;
     const durations = config.phases;

package/dist/settings/settingsModel.d.ts

@@ -67,6 +67,7 @@ export declare const SETTING_IDS: {
     readonly graphicsQuality: "graphics.quality";
     readonly graphicsShadows: "graphics.shadows";
     readonly graphicsUiScale: "graphics.uiScale";
+    readonly touchStyle: "controls.touchStyle";
 };
 export type GraphicsQuality = "low" | "medium" | "high";
 export declare const GRAPHICS_QUALITY_OPTIONS: readonly SettingOption[];

package/dist/settings/settingsModel.js

@@ -11,6 +11,7 @@ export const SETTING_IDS = {
     graphicsQuality: "graphics.quality",
     graphicsShadows: "graphics.shadows",
     graphicsUiScale: "graphics.uiScale",
+    touchStyle: "controls.touchStyle",
 };
 export const GRAPHICS_QUALITY_OPTIONS = [
     { value: "low", label: "Low" },

package/dist/stats/accumulatorMeter.d.ts

@@ -27,5 +27,11 @@ export interface AccumulatorMeter {
     reset(): void;
     tick(dtSeconds: number): void;
 }
+/** The highest tier id whose `at` threshold `value` has reached, or `null` below every tier — the pure lookup `createAccumulatorMeter`/`createEventMeter` call on every `add`/`tick`. */
 export declare function tierAt(value: number, tiers: readonly MeterTier[]): string | null;
+/**
+ * A raw accumulating gauge that crosses named tier thresholds as a value builds, with optional decay — the primitive under charge, rage, and combo meters.
+ *
+ * @capability charge-meter fill a gauge toward named tier thresholds as a value accumulates
+ */
 export declare function createAccumulatorMeter(config: AccumulatorMeterConfig): AccumulatorMeter;

package/dist/stats/accumulatorMeter.js

@@ -3,6 +3,7 @@ function sortedTiers(tiers) {
         return [];
     return [...tiers].sort((a, b) => a.at - b.at);
 }
+/** The highest tier id whose `at` threshold `value` has reached, or `null` below every tier — the pure lookup `createAccumulatorMeter`/`createEventMeter` call on every `add`/`tick`. */
 export function tierAt(value, tiers) {
     let current = null;
     for (const tier of tiers) {
@@ -13,6 +14,11 @@ export function tierAt(value, tiers) {
     }
     return current;
 }
+/**
+ * A raw accumulating gauge that crosses named tier thresholds as a value builds, with optional decay — the primitive under charge, rage, and combo meters.
+ *
+ * @capability charge-meter fill a gauge toward named tier thresholds as a value accumulates
+ */
 export function createAccumulatorMeter(config) {
     const mode = config.mode ?? "hold";
     const tiers = sortedTiers(config.tiers);

package/dist/stats/eventMeter.d.ts

@@ -31,4 +31,9 @@ export interface EventMeter {
     reset(): void;
     tick(dtSeconds: number): void;
 }
+/**
+ * A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shooters and fighters hand-roll.
+ *
+ * @capability event-meter a heat/streak gauge that builds from repeated hits and cools down over time
+ */
 export declare function createEventMeter(config: EventMeterConfig): EventMeter;

package/dist/stats/eventMeter.js

@@ -2,6 +2,11 @@ import { createAccumulatorMeter, } from "./accumulatorMeter.js";
 function readyOf(meter, mode) {
     return mode === "hold" ? meter.broke() : meter.value() >= 0 && meter.fraction() >= 1;
 }
+/**
+ * A heat/hype gauge that rises as tagged events land and cools between them, firing when it fills or breaks — the streak/overdrive meter shooters and fighters hand-roll.
+ *
+ * @capability event-meter a heat/streak gauge that builds from repeated hits and cools down over time
+ */
 export function createEventMeter(config) {
     const mode = config.mode ?? "hold";
     const resets = new Set(config.resets ?? []);

package/dist/stats/rollCheck.d.ts

@@ -12,4 +12,9 @@ export interface CheckResult {
     success: boolean;
     critical: "success" | "failure" | null;
 }
+/**
+ * Resolve a tabletop-style pass/fail roll against a target number with modifiers and crit/fumble bands.
+ *
+ * @capability dice-check resolve a pass/fail roll against a target number with modifiers and crits
+ */
 export declare function rollCheck(input: CheckInput, rng?: () => number): CheckResult;

package/dist/stats/rollCheck.js

@@ -1,3 +1,8 @@
+/**
+ * Resolve a tabletop-style pass/fail roll against a target number with modifiers and crit/fumble bands.
+ *
+ * @capability dice-check resolve a pass/fail roll against a target number with modifiers and crits
+ */
 export function rollCheck(input, rng = Math.random) {
     const sides = input.diceSides ?? 20;
     const advantage = input.advantage ?? "normal";

package/dist/stats/statModifiers.d.ts

@@ -18,4 +18,9 @@ export interface Stats<TStat extends string> {
     pruneExpired(nowMs: number): string[];
     sources(): string[];
 }
+/**
+ * A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
+ *
+ * @capability stat-block base stats with stacking, expiring buffs and debuffs applied on read
+ */
 export declare function createStats<TStat extends string>(base: Record<TStat, number>, options?: CreateStatsOptions): Stats<TStat>;

package/dist/stats/statModifiers.js

@@ -1,3 +1,8 @@
+/**
+ * A stat block whose base values take stacking, timed buffs and debuffs, resolving the modified value on read.
+ *
+ * @capability stat-block base stats with stacking, expiring buffs and debuffs applied on read
+ */
 export function createStats(base, options) {
     const baseValues = { ...base };
     const sourceEntries = new Map();

package/dist/store/defineKeyedStore.d.ts

@@ -0,0 +1,38 @@
+import type { GameContext } from "../runtime/gameContext.js";
+/**
+ * A typed, cast-free handle onto a per-owner keyed family of slots on the reactive game store
+ * (`ctx.game.store`) — the {@link StoreHandle} shape widened with an `id` (userId, instanceId, …)
+ * so one definition covers every owner instead of one `defineStore` call per key. `keyFor` composes
+ * the underlying store key from the id; call sites never see it. Writes flow through the engine
+ * store, so they bump `ctx.version()`, serialize into a {@link WorldSnapshot}, and replay under host
+ * authority — the same guarantees a hand-rolled `` `prefix:${id}` `` string plus `store.get(key) as T`
+ * gives up.
+ */
+export interface KeyedStoreHandle<T> {
+    /** Compose the underlying store key for one owner. Exposed for snapshot/debug tooling; call sites use {@link read}/{@link write}. */
+    keyFor(id: string): string;
+    /** The current value for `id`, or the definition's initial when that slot has never been written. */
+    read(ctx: GameContext, id: string): T;
+    /** The raw stored value for `id`, or `undefined` when unset — distinguishes "never written" from the initial. */
+    peek(ctx: GameContext, id: string): T | undefined;
+    /** Overwrite `id`'s slot; bumps `ctx.version()` and notifies `ctx.subscribe`. */
+    write(ctx: GameContext, id: string, value: T): void;
+    /** Read-modify-write `id`'s slot in one step, returning the next value. `mutate` receives the current value (or initial when unset). */
+    update(ctx: GameContext, id: string, mutate: (previous: T) => T): T;
+    /** Delete `id`'s slot, so the next {@link read} for that id returns the initial again. */
+    clear(ctx: GameContext, id: string): void;
+}
+/**
+ * Define a typed per-owner keyed family on the game store: game code expresses
+ * `read(ctx, userId)`/`write(ctx, userId, v)`/`update(...)` with the value type it means, and both the
+ * `` `prefix:${id}` `` key composition and the `unknown → T` cast live once, here, behind the boundary.
+ * Reach for this over N separate `defineStore` calls whenever the owning id varies at runtime (per-user
+ * class, per-instance auras) — `defineStore` stays the right call for a single fixed slot.
+ *
+ * Pass a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most
+ * once **per id** and its result is reused, so an unwritten id's slot keeps a stable identity across
+ * reads (no per-read churn for a React selector, no allocation on a hot path).
+ *
+ * @capability typed-keyed-store a cast-free typed handle onto a per-owner keyed family of reactive game-store slots, replayable and host-authoritative
+ */
+export declare function defineKeyedStore<T>(keyFor: (id: string) => string, initial: T | (() => T)): KeyedStoreHandle<T>;

package/dist/store/defineKeyedStore.js

@@ -0,0 +1,42 @@
+/**
+ * Define a typed per-owner keyed family on the game store: game code expresses
+ * `read(ctx, userId)`/`write(ctx, userId, v)`/`update(...)` with the value type it means, and both the
+ * `` `prefix:${id}` `` key composition and the `unknown → T` cast live once, here, behind the boundary.
+ * Reach for this over N separate `defineStore` calls whenever the owning id varies at runtime (per-user
+ * class, per-instance auras) — `defineStore` stays the right call for a single fixed slot.
+ *
+ * Pass a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most
+ * once **per id** and its result is reused, so an unwritten id's slot keeps a stable identity across
+ * reads (no per-read churn for a React selector, no allocation on a hot path).
+ *
+ * @capability typed-keyed-store a cast-free typed handle onto a per-owner keyed family of reactive game-store slots, replayable and host-authoritative
+ */
+export function defineKeyedStore(keyFor, initial) {
+    const resolved = new Map();
+    const initialValue = (id) => {
+        if (typeof initial !== "function")
+            return initial;
+        let entry = resolved.get(id);
+        if (entry === undefined) {
+            entry = { value: initial() };
+            resolved.set(id, entry);
+        }
+        return entry.value;
+    };
+    const read = (ctx, id) => {
+        const value = ctx.game.store.get(keyFor(id));
+        return value === undefined ? initialValue(id) : value;
+    };
+    return {
+        keyFor,
+        read,
+        peek: (ctx, id) => ctx.game.store.get(keyFor(id)),
+        write: (ctx, id, value) => ctx.game.store.set(keyFor(id), value),
+        update: (ctx, id, mutate) => {
+            const next = mutate(read(ctx, id));
+            ctx.game.store.set(keyFor(id), next);
+            return next;
+        },
+        clear: (ctx, id) => ctx.game.store.delete(keyFor(id)),
+    };
+}

package/dist/store/defineStore.d.ts

@@ -0,0 +1,33 @@
+import type { GameContext } from "../runtime/gameContext.js";
+/**
+ * A typed, cast-free handle onto one slot of the reactive game store (`ctx.game.store`). The single
+ * type parameter is fixed at definition; `read`/`write`/`update` never widen to `unknown`, so no call
+ * site repeats `store.get(key) as T`. Writes flow through the engine store, so they bump
+ * `ctx.version()`, serialize into a {@link WorldSnapshot}, and replay under host authority — the same
+ * guarantees a hand-rolled `store.get`/`store.set` pair gives up the moment it forks run state into a
+ * module-level singleton.
+ */
+export interface StoreHandle<T> {
+    /** The underlying store key. Exposed for snapshot/debug tooling; call sites use {@link read}/{@link write}. */
+    readonly key: string;
+    /** The current value, or the definition's initial when the slot has never been written. */
+    read(ctx: GameContext): T;
+    /** The raw stored value, or `undefined` when unset — for callers that need to distinguish "never written" from the initial. */
+    peek(ctx: GameContext): T | undefined;
+    /** Overwrite the slot; bumps `ctx.version()` and notifies `ctx.subscribe`. */
+    write(ctx: GameContext, value: T): void;
+    /** Read-modify-write in one step, returning the next value. `mutate` receives the current value (or initial when unset). */
+    update(ctx: GameContext, mutate: (previous: T) => T): T;
+    /** Delete the slot, so the next {@link read} returns the initial again. */
+    clear(ctx: GameContext): void;
+}
+/**
+ * Define a typed slot on the game store: game code expresses `read(ctx)`/`write(ctx, v)`/`update(...)`
+ * with the value type it means, and the `unknown → T` cast lives once, here, behind the boundary. Pass
+ * a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most once and
+ * its result is reused, so an unwritten slot keeps a stable identity across reads (no per-read churn for
+ * a React selector, no allocation on a hot path).
+ *
+ * @capability typed-store a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
+ */
+export declare function defineStore<T>(key: string, initial: T | (() => T)): StoreHandle<T>;

package/dist/store/defineStore.js

@@ -0,0 +1,35 @@
+/**
+ * Define a typed slot on the game store: game code expresses `read(ctx)`/`write(ctx, v)`/`update(...)`
+ * with the value type it means, and the `unknown → T` cast lives once, here, behind the boundary. Pass
+ * a factory for `initial` when the fallback is a fresh mutable object; the factory runs at most once and
+ * its result is reused, so an unwritten slot keeps a stable identity across reads (no per-read churn for
+ * a React selector, no allocation on a hot path).
+ *
+ * @capability typed-store a cast-free typed handle onto one reactive game-store slot, replayable and host-authoritative
+ */
+export function defineStore(key, initial) {
+    let resolved = null;
+    const initialValue = () => {
+        if (typeof initial !== "function")
+            return initial;
+        if (resolved === null)
+            resolved = { value: initial() };
+        return resolved.value;
+    };
+    const read = (ctx) => {
+        const value = ctx.game.store.get(key);
+        return value === undefined ? initialValue() : value;
+    };
+    return {
+        key,
+        read,
+        peek: (ctx) => ctx.game.store.get(key),
+        write: (ctx, value) => ctx.game.store.set(key, value),
+        update: (ctx, mutate) => {
+            const next = mutate(read(ctx));
+            ctx.game.store.set(key, next);
+            return next;
+        },
+        clear: (ctx) => ctx.game.store.delete(key),
+    };
+}

package/dist/store/observableKeyedStore.d.ts

@@ -4,7 +4,16 @@ export interface ObservableKeyedStore<T> {
     get(key: string): T | undefined;
     has(key: string): boolean;
     subscribe(listener: () => void): () => void;
+    /** Notified only when membership changes (a key is added, deleted, or hydrated) — value updates on an existing key do not fire. Pair with {@link keysSnapshot}. */
+    subscribeMembership(listener: () => void): () => void;
+    /** An owned copy of the store's entries — mutating the returned map never reaches the store. Stable identity until the next write, like {@link arraySnapshot}. */
     mapSnapshot(): ReadonlyMap<string, T>;
     arraySnapshot(): readonly T[];
+    /** Stable-identity list of keys; identity changes only when membership changes, so a per-frame `set` on an existing key does not churn it. */
+    keysSnapshot(): readonly string[];
+    /** Serializable `[key, value]` entries — the transport counterpart of {@link hydrate} for host→client mirroring. */
+    snapshot(): readonly (readonly [string, T])[];
+    /** Replace all entries with `data` (clears keys absent from it), emitting once. */
+    hydrate(data: readonly (readonly [string, T])[]): void;
 }
 export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>;

package/dist/store/observableKeyedStore.js

@@ -1,28 +1,44 @@
 export function createObservableKeyedStore(areEqual) {
     const store = new Map();
     const listeners = new Set();
+    const membershipListeners = new Set();
     const EMPTY = [];
+    const EMPTY_KEYS = [];
     let arrayCache = EMPTY;
     let arrayDirty = false;
+    let keysCache = EMPTY_KEYS;
+    let keysDirty = false;
+    let mapCache = new Map();
+    let mapDirty = false;
     function emit() {
         arrayDirty = true;
+        mapDirty = true;
         for (const listener of listeners)
             listener();
     }
+    function emitMembership() {
+        keysDirty = true;
+        for (const listener of membershipListeners)
+            listener();
+    }
     return {
         set(key, value) {
+            const had = store.has(key);
             const previous = store.get(key);
-            if (previous !== undefined && areEqual?.(previous, value))
+            if (had && areEqual?.(previous, value))
                 return;
             if (previous !== value)
                 store.set(key, value);
             emit();
+            if (!had)
+                emitMembership();
         },
         delete(key) {
             if (!store.has(key))
                 return;
             store.delete(key);
             emit();
+            emitMembership();
         },
         get(key) {
             return store.get(key);
@@ -34,8 +50,16 @@ export function createObservableKeyedStore(areEqual) {
             listeners.add(listener);
             return () => listeners.delete(listener);
         },
+        subscribeMembership(listener) {
+            membershipListeners.add(listener);
+            return () => membershipListeners.delete(listener);
+        },
         mapSnapshot() {
-            return store;
+            if (mapDirty) {
+                mapCache = new Map(store);
+                mapDirty = false;
+            }
+            return mapCache;
         },
         arraySnapshot() {
             if (arrayDirty) {
@@ -44,5 +68,22 @@ export function createObservableKeyedStore(areEqual) {
             }
             return arrayCache;
         },
+        keysSnapshot() {
+            if (keysDirty) {
+                keysCache = store.size === 0 ? EMPTY_KEYS : Array.from(store.keys());
+                keysDirty = false;
+            }
+            return keysCache;
+        },
+        snapshot() {
+            return Array.from(store.entries());
+        },
+        hydrate(data) {
+            store.clear();
+            for (const [key, value] of data)
+                store.set(key, value);
+            emit();
+            emitMembership();
+        },
     };
 }