@jgengine/core 0.10.0 → 0.12.0

package/dist/stats/spawnLevelStats.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Per-stat growth definition for one species. `base` is the level-1 value of the stat; `growth`
+ * is how much a single distributed point adds, expressed as a fraction of `base` — so a point on a
+ * `growth: 0.1` stat is worth +10% of base. The resolved value is `base * (1 + points * growth)`.
+ */
+export interface SpawnStatDef {
+    base: number;
+    growth: number;
+}
+/**
+ * A species' stat table: every stat the creature owns keyed to its {@link SpawnStatDef}. The key
+ * order is the deterministic order random points are distributed over, so a serialized species
+ * definition reproduces the same rolls under the same rng sequence.
+ */
+export type SpawnSpeciesDef<TStat extends string> = Record<TStat, SpawnStatDef>;
+/**
+ * A single creature's serializable stat record — a reference to its species (`speciesId`), the
+ * current `level`, the per-stat count of distributed points, and how many post-capture domestic
+ * levels have been spent. Plain data: round-trips through JSON, save/load, and multiplayer sync.
+ * Resolve display values with {@link resolveSpawnStats}.
+ */
+export interface CreatureStatInstance<TStat extends string> {
+    speciesId: string;
+    level: number;
+    points: Record<TStat, number>;
+    domesticLevels: number;
+}
+/**
+ * Outcome of {@link applyCaptureEffectiveness}: the granted `bonusLevels`, the `tamedLevel`
+ * (wild level plus bonus levels), and the post-capture {@link CreatureStatInstance}.
+ * @internal
+ */
+export interface CaptureResult<TStat extends string> {
+    bonusLevels: number;
+    tamedLevel: number;
+    instance: CreatureStatInstance<TStat>;
+}
+/**
+ * Options for {@link spendDomesticLevel}. `maxDomesticLevels` caps how many post-capture levels a
+ * creature may spend; once reached, further spends are refused.
+ * @internal
+ */
+export interface SpendLevelOptions {
+    maxDomesticLevels?: number;
+}
+/**
+ * Result of {@link spendDomesticLevel}: the resulting instance and whether the level was applied
+ * (`spent: false` when the domestic-level cap blocked it, leaving the instance untouched).
+ * @internal
+ */
+export interface SpendLevelResult<TStat extends string> {
+    instance: CreatureStatInstance<TStat>;
+    spent: boolean;
+}
+/**
+ * Roll a fresh wild creature at `level`: distribute `(level - 1)` points randomly across the
+ * species' stats using the injected rng and return a serializable {@link CreatureStatInstance}.
+ * Deterministic — the same rng sequence yields the same point spread. Levels below 1 clamp to 1
+ * (no points). Use `seededRng` from `../random/rng` for a persisted, reproducible stream.
+ *
+ * @capability spawn-level-roll distribute a wild creature's spawn level into random per-stat points
+ */
+export declare function rollSpawnInstance<TStat extends string>(speciesId: string, species: SpawnSpeciesDef<TStat>, level: number, rng: () => number): CreatureStatInstance<TStat>;
+/**
+ * Resolve an instance's live stat values from its distributed points:
+ * `value = base * (1 + points * growth)` per stat. Stats with zero points return their base.
+ *
+ * @capability spawn-stat-values resolve a creature's per-stat values from its distributed points
+ */
+export declare function resolveSpawnStats<TStat extends string>(species: SpawnSpeciesDef<TStat>, instance: CreatureStatInstance<TStat>): Record<TStat, number>;
+/**
+ * Bonus levels granted by a capture at the given effectiveness:
+ * `floor(level * clamp01(effectiveness) / 2)`. A perfect (1.0) capture grants half the wild
+ * level; a botched (0) capture grants none. Effectiveness outside `[0,1]` clamps.
+ *
+ * @capability capture-bonus-levels convert wild level and capture effectiveness into bonus levels
+ */
+export declare function captureBonusLevels(level: number, effectiveness: number): number;
+/**
+ * Apply a capture at the given effectiveness: compute bonus levels via {@link captureBonusLevels},
+ * distribute those extra points randomly with the injected rng, and return the post-capture
+ * instance (level raised to the tamed total) alongside the granted bonus levels and tamed level.
+ * The input instance is not mutated.
+ *
+ * @capability capture-effectiveness-tame apply capture effectiveness to grant and distribute bonus levels
+ */
+export declare function applyCaptureEffectiveness<TStat extends string>(species: SpawnSpeciesDef<TStat>, instance: CreatureStatInstance<TStat>, effectiveness: number, rng: () => number): CaptureResult<TStat>;
+/**
+ * Spend one earned post-capture level into `stat`, adding a single growth increment (one point)
+ * and raising both `level` and `domesticLevels`. When `maxDomesticLevels` is set and already
+ * reached, the spend is refused (`spent: false`) and the instance is returned untouched. Pure:
+ * returns a new instance rather than mutating the input.
+ *
+ * @capability domestic-level-spend spend an earned post-capture level into a chosen stat under a cap
+ */
+export declare function spendDomesticLevel<TStat extends string>(instance: CreatureStatInstance<TStat>, stat: TStat, options?: SpendLevelOptions): SpendLevelResult<TStat>;
+/**
+ * Deep-copy an instance into a detached, serializable record — the transport/save counterpart of
+ * {@link restoreSpawnInstance}. Copies the points map so later edits don't leak into the snapshot.
+ *
+ * @capability spawn-instance-snapshot deep-copy a creature stat instance into a serializable record
+ */
+export declare function snapshotSpawnInstance<TStat extends string>(instance: CreatureStatInstance<TStat>): CreatureStatInstance<TStat>;
+/**
+ * Rehydrate a creature stat instance from decoded data (e.g. `JSON.parse` output), returning a
+ * fresh deep copy the caller owns. Inverse of {@link snapshotSpawnInstance}.
+ *
+ * @capability spawn-instance-restore rehydrate a creature stat instance from decoded snapshot data
+ */
+export declare function restoreSpawnInstance<TStat extends string>(data: CreatureStatInstance<TStat>): CreatureStatInstance<TStat>;

package/dist/stats/spawnLevelStats.js

@@ -0,0 +1,140 @@
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function normalizeLevel(level) {
+    const floored = Math.floor(level);
+    return floored < 1 ? 1 : floored;
+}
+/**
+ * Scatter `count` points one at a time across `statIds`, choosing each target uniformly from the
+ * injected rng. Mutates `into` in place; bounded by `count`. The rng draws the sole source of
+ * randomness, so an identical rng sequence reproduces an identical distribution.
+ */
+function distributePoints(statIds, count, rng, into) {
+    const n = statIds.length;
+    if (n === 0 || count <= 0)
+        return;
+    for (let i = 0; i < count; i++) {
+        let index = Math.floor(rng() * n);
+        if (index >= n)
+            index = n - 1;
+        if (index < 0)
+            index = 0;
+        const stat = statIds[index];
+        into[stat] = (into[stat] ?? 0) + 1;
+    }
+}
+function zeroedPoints(statIds) {
+    const points = {};
+    for (const stat of statIds)
+        points[stat] = 0;
+    return points;
+}
+/**
+ * Roll a fresh wild creature at `level`: distribute `(level - 1)` points randomly across the
+ * species' stats using the injected rng and return a serializable {@link CreatureStatInstance}.
+ * Deterministic — the same rng sequence yields the same point spread. Levels below 1 clamp to 1
+ * (no points). Use `seededRng` from `../random/rng` for a persisted, reproducible stream.
+ *
+ * @capability spawn-level-roll distribute a wild creature's spawn level into random per-stat points
+ */
+export function rollSpawnInstance(speciesId, species, level, rng) {
+    const statIds = Object.keys(species);
+    const points = zeroedPoints(statIds);
+    const normalized = normalizeLevel(level);
+    distributePoints(statIds, normalized - 1, rng, points);
+    return { speciesId, level: normalized, points, domesticLevels: 0 };
+}
+/**
+ * Resolve an instance's live stat values from its distributed points:
+ * `value = base * (1 + points * growth)` per stat. Stats with zero points return their base.
+ *
+ * @capability spawn-stat-values resolve a creature's per-stat values from its distributed points
+ */
+export function resolveSpawnStats(species, instance) {
+    const out = {};
+    for (const stat of Object.keys(species)) {
+        const def = species[stat];
+        const pts = instance.points[stat] ?? 0;
+        out[stat] = def.base * (1 + pts * def.growth);
+    }
+    return out;
+}
+/**
+ * Bonus levels granted by a capture at the given effectiveness:
+ * `floor(level * clamp01(effectiveness) / 2)`. A perfect (1.0) capture grants half the wild
+ * level; a botched (0) capture grants none. Effectiveness outside `[0,1]` clamps.
+ *
+ * @capability capture-bonus-levels convert wild level and capture effectiveness into bonus levels
+ */
+export function captureBonusLevels(level, effectiveness) {
+    return Math.floor((normalizeLevel(level) * clamp01(effectiveness)) / 2);
+}
+/**
+ * Apply a capture at the given effectiveness: compute bonus levels via {@link captureBonusLevels},
+ * distribute those extra points randomly with the injected rng, and return the post-capture
+ * instance (level raised to the tamed total) alongside the granted bonus levels and tamed level.
+ * The input instance is not mutated.
+ *
+ * @capability capture-effectiveness-tame apply capture effectiveness to grant and distribute bonus levels
+ */
+export function applyCaptureEffectiveness(species, instance, effectiveness, rng) {
+    const bonusLevels = captureBonusLevels(instance.level, effectiveness);
+    const statIds = Object.keys(species);
+    const points = { ...instance.points };
+    distributePoints(statIds, bonusLevels, rng, points);
+    const tamedLevel = instance.level + bonusLevels;
+    return {
+        bonusLevels,
+        tamedLevel,
+        instance: { ...instance, level: tamedLevel, points },
+    };
+}
+/**
+ * Spend one earned post-capture level into `stat`, adding a single growth increment (one point)
+ * and raising both `level` and `domesticLevels`. When `maxDomesticLevels` is set and already
+ * reached, the spend is refused (`spent: false`) and the instance is returned untouched. Pure:
+ * returns a new instance rather than mutating the input.
+ *
+ * @capability domestic-level-spend spend an earned post-capture level into a chosen stat under a cap
+ */
+export function spendDomesticLevel(instance, stat, options) {
+    const cap = options?.maxDomesticLevels;
+    if (cap !== undefined && instance.domesticLevels >= cap) {
+        return { instance, spent: false };
+    }
+    const points = { ...instance.points };
+    points[stat] = (points[stat] ?? 0) + 1;
+    return {
+        instance: {
+            ...instance,
+            points,
+            level: instance.level + 1,
+            domesticLevels: instance.domesticLevels + 1,
+        },
+        spent: true,
+    };
+}
+/**
+ * Deep-copy an instance into a detached, serializable record — the transport/save counterpart of
+ * {@link restoreSpawnInstance}. Copies the points map so later edits don't leak into the snapshot.
+ *
+ * @capability spawn-instance-snapshot deep-copy a creature stat instance into a serializable record
+ */
+export function snapshotSpawnInstance(instance) {
+    return {
+        speciesId: instance.speciesId,
+        level: instance.level,
+        domesticLevels: instance.domesticLevels,
+        points: { ...instance.points },
+    };
+}
+/**
+ * Rehydrate a creature stat instance from decoded data (e.g. `JSON.parse` output), returning a
+ * fresh deep copy the caller owns. Inverse of {@link snapshotSpawnInstance}.
+ *
+ * @capability spawn-instance-restore rehydrate a creature stat instance from decoded snapshot data
+ */
+export function restoreSpawnInstance(data) {
+    return snapshotSpawnInstance(data);
+}

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/stats/statPool.d.ts

@@ -0,0 +1,70 @@
+/** Serializable state for any bounded named resource. The caller defines what the resource means. */
+export interface StatPool {
+    current: number;
+    max: number;
+    min: number;
+}
+/** Input used to create a normalized pool. `current` defaults to `max`; `min` defaults to zero. */
+export interface StatPoolInput {
+    current?: number;
+    max: number;
+    min?: number;
+}
+/** Partial update applied without mutating the previous pool. */
+export interface StatPoolPatch {
+    current?: number;
+    max?: number;
+    min?: number;
+}
+/**
+ * Structural bridge to caller-owned resource state. Implement it over an ECS,
+ * Redux/Zustand store, plain object, database-backed model, or JGengine's native
+ * entity stats without moving ownership into the SDK.
+ */
+export interface StatPoolAccess<TOwnerId extends string = string, TStatId extends string = string> {
+    get(ownerId: TOwnerId, statId: TStatId): StatPool | null;
+    set(ownerId: TOwnerId, statId: TStatId, next: StatPool): unknown;
+}
+/** Inspectable result of a bounded pool change. */
+export interface StatPoolChange {
+    previous: StatPool;
+    pool: StatPool;
+    /** Actual applied amount after clamping. */
+    applied: number;
+    hitMin: boolean;
+    hitMax: boolean;
+}
+/** Outcome of changing a pool through {@link StatPoolAccess}. */
+export type StatPoolAccessResult = ({
+    status: "ok";
+} & StatPoolChange) | {
+    status: "rejected";
+    reason: string;
+};
+/**
+ * Normalize caller data into a complete plain-data pool.
+ *
+ * @capability stat-pool create a serializable current/min/max pool for any caller-named resource
+ */
+export declare function createStatPool(input: StatPoolInput): StatPool;
+/**
+ * Apply new bounds/current to a pool, clamping the result and leaving the input untouched.
+ *
+ * @capability stat-pool-patch immutably retune a bounded resource's current value or bounds
+ */
+export declare function patchStatPool(pool: StatPool, patch: StatPoolPatch): StatPool;
+/**
+ * Pure bounded delta transition with the exact applied amount and boundary flags.
+ *
+ * @capability stat-pool-change immutably increase or decrease any named bounded resource with clamp evidence
+ */
+export declare function changeStatPool(pool: StatPool, amount: number): StatPoolChange;
+/**
+ * Read, transition, and write a caller-owned pool through the structural
+ * adapter. Positive amounts increase the resource; negative amounts decrease
+ * it. The adapter receives a complete replacement value, never a hidden
+ * mutation.
+ *
+ * @capability portable-stat-pool apply deterministic bounded resource changes through a caller-owned stat adapter
+ */
+export declare function applyStatPoolDelta<TOwnerId extends string, TStatId extends string>(access: StatPoolAccess<TOwnerId, TStatId>, ownerId: TOwnerId, statId: TStatId, amount: number): StatPoolAccessResult;

package/dist/stats/statPool.js

@@ -0,0 +1,59 @@
+import { clamp } from "../math/scalar.js";
+/**
+ * Normalize caller data into a complete plain-data pool.
+ *
+ * @capability stat-pool create a serializable current/min/max pool for any caller-named resource
+ */
+export function createStatPool(input) {
+    const min = input.min ?? 0;
+    return {
+        current: clamp(input.current ?? input.max, min, input.max),
+        max: input.max,
+        min,
+    };
+}
+/**
+ * Apply new bounds/current to a pool, clamping the result and leaving the input untouched.
+ *
+ * @capability stat-pool-patch immutably retune a bounded resource's current value or bounds
+ */
+export function patchStatPool(pool, patch) {
+    const max = patch.max ?? pool.max;
+    const min = patch.min ?? pool.min;
+    return {
+        current: clamp(patch.current ?? pool.current, min, max),
+        max,
+        min,
+    };
+}
+/**
+ * Pure bounded delta transition with the exact applied amount and boundary flags.
+ *
+ * @capability stat-pool-change immutably increase or decrease any named bounded resource with clamp evidence
+ */
+export function changeStatPool(pool, amount) {
+    const next = patchStatPool(pool, { current: pool.current + amount });
+    return {
+        previous: pool,
+        pool: next,
+        applied: next.current - pool.current,
+        hitMin: next.current === next.min,
+        hitMax: next.current === next.max,
+    };
+}
+/**
+ * Read, transition, and write a caller-owned pool through the structural
+ * adapter. Positive amounts increase the resource; negative amounts decrease
+ * it. The adapter receives a complete replacement value, never a hidden
+ * mutation.
+ *
+ * @capability portable-stat-pool apply deterministic bounded resource changes through a caller-owned stat adapter
+ */
+export function applyStatPoolDelta(access, ownerId, statId, amount) {
+    const pool = access.get(ownerId, statId);
+    if (pool === null)
+        return { status: "rejected", reason: `unknown stat "${statId}"` };
+    const change = changeStatPool(pool, amount);
+    access.set(ownerId, statId, change.pool);
+    return { status: "ok", ...change };
+}

package/dist/store/changeSignal.d.ts

@@ -1,7 +1,10 @@
+/** @internal */
 export interface ChangeSignal {
     subscribe(listener: () => void): () => void;
     notify(): void;
     version(): number;
 }
+/** @internal */
 export declare function createChangeSignal(): ChangeSignal;
+/** @internal */
 export declare function notifyAfter<T extends object, K extends keyof T>(target: T, methods: readonly K[], notify: () => void): T;

package/dist/store/changeSignal.js

@@ -1,3 +1,4 @@
+/** @internal */
 export function createChangeSignal() {
     const listeners = new Set();
     let version = 0;
@@ -18,6 +19,7 @@ export function createChangeSignal() {
         },
     };
 }
+/** @internal */
 export function notifyAfter(target, methods, notify) {
     const wrapped = { ...target };
     for (const method of methods) {

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

@@ -1,14 +1,21 @@
+/** @internal */
 export interface ObservableKeyedStore<T> {
     set(key: string, value: T): void;
     delete(key: string): void;
     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;
 }
+/** @internal */
 export declare function createObservableKeyedStore<T>(areEqual?: (previous: T, next: T) => boolean): ObservableKeyedStore<T>;