@crowdedkingdoms/crowdyjs 8.2.0 → 8.4.0

package/dist/stores/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * World Stores — opt-in, SDK-managed game state for CrowdyJS
+ * (`@crowdedkingdoms/crowdyjs/stores`).
+ *
+ * The core client is a thin transport; this layer adds the source-of-truth
+ * data structures every game otherwise hand-writes: typed codecs, actor
+ * registries, chunk/voxel caches, error attribution, message inboxes, host
+ * tracking, and durable-state wrappers. Import only what you use — the core
+ * bundle never includes this module, and unused stores tree-shake away
+ * (`"sideEffects": false`).
+ *
+ * Entry point: {@link createWorldSession}.
+ */
+export { bool8, bytes, f32, f64, i8, i16, i32, jsonCodec, rawCodec, reserved, structCodec, textCodec, u8, u16, u32, type StateCodec, type StructCodec, type StructField, type StructSpec, type StructValue, } from './codec.js';
+export { CHUNK_SIZE, CHUNK_VOLUME, chunkDistance, chunkKey, chunksAround, fromChunkInput, parseChunkKey, toChunkInput, voxelCoordFromIndex, voxelIndex, worldToChunk, worldToLocalVoxel, type ChunkCoord, } from './keys.js';
+export { intervalTicker, manualTicker, workerTicker, type ManualTicker, type Ticker, } from './ticker.js';
+export { WorldSessionCore, type BusKey, type SentPacketKind, type SentPacketRecord, type WorldSessionBaseConfig, type WorldSessionContext, type WorldStoresClient, } from './session.js';
+export { LocalActorStore, RemoteActorLane, RemoteActorStore, attachLocalActor, attachRemoteActors, localStorageUuidStore, memoryUuidStore, type AckedActorUpdate, type ActorSendError, type ActorUpdateEcho, type GenericErrorEcho, type LocalActorConfig, type LocalActorStatus, type RemoteActor, type RemoteActorSample, type RemoteActorsConfig, type SendReason, type SentActorUpdate, type UuidStore, } from './actors.js';
+export { ErrorStore, attachErrorStore, type AttributedError, type ErrorStoreConfig, } from './errors.js';
+export { ChunkStore, attachChunkStore, type CachedChunk, type ChunkLoadState, type ChunkStoreConfig, type SetVoxelInput, } from './chunks.js';
+export { ActorInbox, ChannelInbox, EventRouter, attachActorInbox, attachChannelInbox, attachEventRouter, type ActorInboxConfig, type ChannelInboxConfig, type EventRouterConfig, type InboxMessage, type TypedEvent, } from './inbox.js';
+export { ContainerMirror, attachContainerMirror, type ContainerMirrorConfig, type MirroredContainer, } from './model.js';
+export { AvatarStateStore, HostTracker, SaveStateStore, attachAvatarState, attachHostTracker, attachSaveState, type AvatarStateConfig, type HostTrackerConfig, type SaveStateConfig, } from './durable.js';
+import { LocalActorStore, RemoteActorStore, type LocalActorConfig, type RemoteActorsConfig } from './actors.js';
+import type { StateCodec } from './codec.js';
+import { ChunkStore, type ChunkStoreConfig } from './chunks.js';
+import { AvatarStateStore, HostTracker, SaveStateStore, type AvatarStateConfig, type HostTrackerConfig, type SaveStateConfig } from './durable.js';
+import { ContainerMirror, type ContainerMirrorConfig } from './model.js';
+import { ErrorStore, type ErrorStoreConfig } from './errors.js';
+import { ActorInbox, ChannelInbox, EventRouter, type ActorInboxConfig, type ChannelInboxConfig, type EventRouterConfig } from './inbox.js';
+import { WorldSessionCore, type WorldSessionBaseConfig, type WorldStoresClient } from './session.js';
+/**
+ * Configuration for {@link createWorldSession}: one optional key per store.
+ * Only configured stores are constructed — and, via {@link WorldSession}'s
+ * conditional typing, only configured stores exist on the returned session's
+ * TYPE, so touching an unconfigured store is a compile error, not a runtime
+ * surprise. Keys documented on each store's config type; `true` selects a
+ * store's defaults.
+ */
+export interface WorldSessionConfig extends WorldSessionBaseConfig {
+    /** Your own actor: identity, typed state, 5 Hz send loop ({@link LocalActorStore}). */
+    self?: LocalActorConfig<any>;
+    /**
+     * Remote actors: typed registry with lanes, history, staleness
+     * ({@link RemoteActorStore}). The self-echo filter is wired from `self`
+     * automatically; set `selfUuid` yourself otherwise.
+     */
+    actors?: RemoteActorsConfig<any>;
+    /**
+     * Send-error log: attributes `GenericErrorResponse`s to the sends that
+     * caused them ({@link ErrorStore}).
+     */
+    errors?: ErrorStoreConfig | true;
+    /**
+     * Chunk/voxel cache: bulk loading, typed states, realtime merge,
+     * optimistic edits, worldgen write-back ({@link ChunkStore}). The outbound
+     * sender uuid is wired from `self` automatically.
+     */
+    chunks?: ChunkStoreConfig<any, any> | true;
+    /** Channel message inbox: per-channel typed history + send ({@link ChannelInbox}). */
+    channelInbox?: ChannelInboxConfig<any> | true;
+    /** Direct actor-to-actor message inbox ({@link ActorInbox}). */
+    actorInbox?: ActorInboxConfig<any> | true;
+    /**
+     * App-defined event router: per-eventType codecs + handlers, lastEvent
+     * cache ({@link EventRouter}).
+     */
+    events?: EventRouterConfig | true;
+    /** Host election tracking: heartbeat loop + isHost ({@link HostTracker}). */
+    host?: HostTrackerConfig | true;
+    /** Typed per-user app save blob with debounced autosave ({@link SaveStateStore}). */
+    save?: SaveStateConfig<any> | true;
+    /** Typed avatar public/private/app state ({@link AvatarStateStore}). */
+    avatar?: AvatarStateConfig<any, any, any> | true;
+    /**
+     * Game-model mirror: typed cached container snapshots with coalesced
+     * refresh + notify-to-pull channel binding ({@link ContainerMirror}).
+     */
+    model?: ContainerMirrorConfig | true;
+}
+/** Infer the payload type of a `codec` config field (else the default `D`). */
+type CodecType<CC, D> = CC extends {
+    codec: StateCodec<infer T>;
+} ? T : D;
+type VoxelStateType<CC> = CC extends {
+    voxelStateCodec: StateCodec<infer T>;
+} ? T : string;
+type ChunkStateType<CC> = CC extends {
+    chunkStateCodec: StateCodec<infer T>;
+} ? T : string;
+type AvatarPublicType<CC> = CC extends {
+    publicCodec: StateCodec<infer T>;
+} ? T : unknown;
+type AvatarPrivateType<CC> = CC extends {
+    privateCodec: StateCodec<infer T>;
+} ? T : unknown;
+type AvatarAppType<CC> = CC extends {
+    appCodec: StateCodec<infer T>;
+} ? T : unknown;
+/** The parts of a {@link WorldSession} that exist regardless of config. */
+export interface WorldSessionBase {
+    /** The app this session is scoped to. */
+    readonly appId: string;
+    /** Close the shared subscription, cancel timers, and release the stores. */
+    dispose(): void;
+    /** The wiring context (for custom store implementations). */
+    readonly context: WorldSessionCore;
+}
+/**
+ * The session returned by {@link createWorldSession}: the base surface plus
+ * exactly the stores your config declared, with every store's value types
+ * inferred from the codecs you passed. Annotate variables as
+ * `WorldSession<typeof config>` when you need a name for it.
+ */
+export type WorldSession<C extends WorldSessionConfig = WorldSessionConfig> = WorldSessionBase & (C extends {
+    self: LocalActorConfig<infer T>;
+} ? {
+    readonly self: LocalActorStore<T>;
+} : unknown) & (C extends {
+    actors: RemoteActorsConfig<infer T>;
+} ? {
+    readonly actors: RemoteActorStore<T>;
+} : unknown) & (C extends {
+    errors: ErrorStoreConfig | true;
+} ? {
+    readonly errors: ErrorStore;
+} : unknown) & (C extends {
+    chunks: infer CC;
+} ? {
+    readonly chunks: ChunkStore<VoxelStateType<CC>, ChunkStateType<CC>>;
+} : unknown) & (C extends {
+    channelInbox: infer CC;
+} ? {
+    readonly channelInbox: ChannelInbox<CodecType<CC, string>>;
+} : unknown) & (C extends {
+    actorInbox: infer CC;
+} ? {
+    readonly actorInbox: ActorInbox<CodecType<CC, string>>;
+} : unknown) & (C extends {
+    events: EventRouterConfig | true;
+} ? {
+    readonly events: EventRouter;
+} : unknown) & (C extends {
+    host: HostTrackerConfig | true;
+} ? {
+    readonly host: HostTracker;
+} : unknown) & (C extends {
+    save: infer CC;
+} ? {
+    readonly save: SaveStateStore<CodecType<CC, unknown>>;
+} : unknown) & (C extends {
+    avatar: infer CC;
+} ? {
+    readonly avatar: AvatarStateStore<AvatarPublicType<CC>, AvatarPrivateType<CC>, AvatarAppType<CC>>;
+} : unknown) & (C extends {
+    model: ContainerMirrorConfig | true;
+} ? {
+    readonly model: ContainerMirror;
+} : unknown);
+/**
+ * Create a **world session**: one shared `udpNotifications` subscription
+ * fanned out to the stores you configure, one shared {@link Ticker}, and a
+ * single `dispose()`. Pass your `CrowdyClient` (it satisfies
+ * {@link WorldStoresClient} structurally) and the app id.
+ *
+ * ```ts
+ * import { createWorldSession, structCodec, f32, u8, jsonCodec, workerTicker } from '@crowdedkingdoms/crowdyjs/stores';
+ *
+ * const poseCodec = structCodec({ x: f32(), y: f32(), z: f32(), flags: u8() });
+ * const session = createWorldSession(client, appId, {
+ *   ticker: workerTicker(), // hold 5 Hz in backgrounded tabs
+ *   self: { codec: poseCodec, initialState: { x: 0, y: 0, z: 0, flags: 0 } },
+ *   actors: { codec: poseCodec },
+ *   errors: true,
+ *   save: { codec: jsonCodec<{ level: number }>(), autosaveMs: 5000 },
+ * });
+ * await session.self.join({ x: '0', y: '0', z: '0' });
+ * session.self.patchState({ x: 12.5 });          // next tick replicates it
+ * for (const other of session.actors.list()) {}  // typed poses, self filtered
+ * session.save.set({ level: 2 });                // autosaves, typed
+ * // session.chunks — compile error: not configured.
+ * session.dispose();
+ * ```
+ */
+export declare function createWorldSession<const C extends WorldSessionConfig = Record<never, never>>(client: WorldStoresClient, appId: string, config?: C): WorldSession<C>;
+//# sourceMappingURL=index.d.ts.map

package/dist/stores/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/stores/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,KAAK,EACL,KAAK,EACL,GAAG,EACH,GAAG,EACH,EAAE,EACF,GAAG,EACH,GAAG,EACH,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,SAAS,EACT,EAAE,EACF,GAAG,EACH,GAAG,EACH,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,aAAa,EACb,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,MAAM,GACZ,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gBAAgB,EAChB,KAAK,MAAM,EACX,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,eAAe,EACf,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,eAAe,EACf,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,SAAS,GACf,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACrB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,GACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,EAAE,UAAU,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EACL,UAAU,EACV,YAAY,EACZ,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,gBAAgB,EAChB,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACvB,MAAM,cAAc,CAAC;AAEtB;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAmB,SAAQ,sBAAsB;IAChE,uFAAuF;IACvF,IAAI,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAC7B;;;;OAIG;IACH,MAAM,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC3C,sFAAsF;IACtF,YAAY,CAAC,EAAE,kBAAkB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAC9C,gEAAgE;IAChE,UAAU,CAAC,EAAE,gBAAgB,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IAC1C;;;OAGG;IACH,MAAM,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClC,6EAA6E;IAC7E,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAChC,qFAAqF;IACrF,IAAI,CAAC,EAAE,eAAe,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC;IACnC,wEAAwE;IACxE,MAAM,CAAC,EAAE,iBAAiB,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IACjD;;;OAGG;IACH,KAAK,CAAC,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACtC;AAED,+EAA+E;AAC/E,KAAK,SAAS,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,SAAS;IAAE,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,CAAC,CAAC;AAC1E,KAAK,cAAc,CAAC,EAAE,IAAI,EAAE,SAAS;IAAE,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,MAAM,CAAC;AAC3F,KAAK,cAAc,CAAC,EAAE,IAAI,EAAE,SAAS;IAAE,eAAe,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,MAAM,CAAC;AAC3F,KAAK,gBAAgB,CAAC,EAAE,IAAI,EAAE,SAAS;IAAE,WAAW,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,OAAO,CAAC;AAC1F,KAAK,iBAAiB,CAAC,EAAE,IAAI,EAAE,SAAS;IAAE,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,OAAO,CAAC;AAC5F,KAAK,aAAa,CAAC,EAAE,IAAI,EAAE,SAAS;IAAE,QAAQ,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAAG,CAAC,GAAG,OAAO,CAAC;AAEpF,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,OAAO,IAAI,IAAI,CAAC;IAChB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;CACpC;AAED;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,kBAAkB,GAAG,kBAAkB,IACxE,gBAAgB,GACd,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC,CAAC,CAAC,CAAA;CAAE,GACrC,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAA;CAAE,GACxC,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAAE,GAC1C;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC/B,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,cAAc,CAAC,EAAE,CAAC,CAAC,CAAA;CAAE,GACvE,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GACjC;IAAE,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GAC9D,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,GAC1D,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAAE,GAC3C;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAAE,GAChC,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAAA;CAAE,GACzC;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAA;CAAE,GACzD,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAC3B;IACE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAC/B,gBAAgB,CAAC,EAAE,CAAC,EACpB,iBAAiB,CAAC,EAAE,CAAC,EACrB,aAAa,CAAC,EAAE,CAAC,CAClB,CAAC;CACH,GACD,OAAO,CAAC,GACZ,CAAC,CAAC,SAAS;IAAE,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAA;CAAE,GAC9C;IAAE,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAA;CAAE,GACnC,OAAO,CAAC,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,kBAAkB,GAAG,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,EAC1F,MAAM,EAAE,iBAAiB,EACzB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,CAAC,GACT,YAAY,CAAC,CAAC,CAAC,CAwDjB"}

package/dist/stores/index.js

@@ -0,0 +1,109 @@
+/**
+ * World Stores — opt-in, SDK-managed game state for CrowdyJS
+ * (`@crowdedkingdoms/crowdyjs/stores`).
+ *
+ * The core client is a thin transport; this layer adds the source-of-truth
+ * data structures every game otherwise hand-writes: typed codecs, actor
+ * registries, chunk/voxel caches, error attribution, message inboxes, host
+ * tracking, and durable-state wrappers. Import only what you use — the core
+ * bundle never includes this module, and unused stores tree-shake away
+ * (`"sideEffects": false`).
+ *
+ * Entry point: {@link createWorldSession}.
+ */
+export { bool8, bytes, f32, f64, i8, i16, i32, jsonCodec, rawCodec, reserved, structCodec, textCodec, u8, u16, u32, } from './codec.js';
+export { CHUNK_SIZE, CHUNK_VOLUME, chunkDistance, chunkKey, chunksAround, fromChunkInput, parseChunkKey, toChunkInput, voxelCoordFromIndex, voxelIndex, worldToChunk, worldToLocalVoxel, } from './keys.js';
+export { intervalTicker, manualTicker, workerTicker, } from './ticker.js';
+export { WorldSessionCore, } from './session.js';
+export { LocalActorStore, RemoteActorLane, RemoteActorStore, attachLocalActor, attachRemoteActors, localStorageUuidStore, memoryUuidStore, } from './actors.js';
+export { ErrorStore, attachErrorStore, } from './errors.js';
+export { ChunkStore, attachChunkStore, } from './chunks.js';
+export { ActorInbox, ChannelInbox, EventRouter, attachActorInbox, attachChannelInbox, attachEventRouter, } from './inbox.js';
+export { ContainerMirror, attachContainerMirror, } from './model.js';
+export { AvatarStateStore, HostTracker, SaveStateStore, attachAvatarState, attachHostTracker, attachSaveState, } from './durable.js';
+import { LocalActorStore, RemoteActorStore, } from './actors.js';
+import { ChunkStore } from './chunks.js';
+import { AvatarStateStore, HostTracker, SaveStateStore, } from './durable.js';
+import { ContainerMirror } from './model.js';
+import { ErrorStore } from './errors.js';
+import { ActorInbox, ChannelInbox, EventRouter, } from './inbox.js';
+import { WorldSessionCore, } from './session.js';
+/**
+ * Create a **world session**: one shared `udpNotifications` subscription
+ * fanned out to the stores you configure, one shared {@link Ticker}, and a
+ * single `dispose()`. Pass your `CrowdyClient` (it satisfies
+ * {@link WorldStoresClient} structurally) and the app id.
+ *
+ * ```ts
+ * import { createWorldSession, structCodec, f32, u8, jsonCodec, workerTicker } from '@crowdedkingdoms/crowdyjs/stores';
+ *
+ * const poseCodec = structCodec({ x: f32(), y: f32(), z: f32(), flags: u8() });
+ * const session = createWorldSession(client, appId, {
+ *   ticker: workerTicker(), // hold 5 Hz in backgrounded tabs
+ *   self: { codec: poseCodec, initialState: { x: 0, y: 0, z: 0, flags: 0 } },
+ *   actors: { codec: poseCodec },
+ *   errors: true,
+ *   save: { codec: jsonCodec<{ level: number }>(), autosaveMs: 5000 },
+ * });
+ * await session.self.join({ x: '0', y: '0', z: '0' });
+ * session.self.patchState({ x: 12.5 });          // next tick replicates it
+ * for (const other of session.actors.list()) {}  // typed poses, self filtered
+ * session.save.set({ level: 2 });                // autosaves, typed
+ * // session.chunks — compile error: not configured.
+ * session.dispose();
+ * ```
+ */
+export function createWorldSession(client, appId, config) {
+    const cfg = config ?? {};
+    const opt = (value) => value === true ? {} : value;
+    const core = new WorldSessionCore(client, appId, cfg.ticker);
+    // The error store registers the send-tracking sink — construct it first so
+    // the very first actor/chunk sends are already attributable.
+    const errors = cfg.errors ? new ErrorStore(core, opt(cfg.errors)) : undefined;
+    const self = cfg.self ? new LocalActorStore(core, cfg.self) : undefined;
+    const selfUuid = self ? () => self.uuid : undefined;
+    const actors = cfg.actors
+        ? new RemoteActorStore(core, {
+            // Filter the local echo automatically when a self store exists.
+            selfUuid,
+            ...cfg.actors,
+        })
+        : undefined;
+    const chunks = cfg.chunks
+        ? new ChunkStore(core, {
+            // Stamp outbound voxel edits with the local actor's uuid.
+            actorUuid: selfUuid,
+            ...opt(cfg.chunks),
+        })
+        : undefined;
+    const channelInbox = cfg.channelInbox
+        ? new ChannelInbox(core, { senderUuid: selfUuid, ...opt(cfg.channelInbox) })
+        : undefined;
+    const actorInbox = cfg.actorInbox
+        ? new ActorInbox(core, opt(cfg.actorInbox))
+        : undefined;
+    const events = cfg.events
+        ? new EventRouter(core, { senderUuid: selfUuid, ...opt(cfg.events) })
+        : undefined;
+    const host = cfg.host ? new HostTracker(core, opt(cfg.host)) : undefined;
+    const save = cfg.save ? new SaveStateStore(core, opt(cfg.save)) : undefined;
+    const avatar = cfg.avatar ? new AvatarStateStore(core, opt(cfg.avatar)) : undefined;
+    const model = cfg.model ? new ContainerMirror(core, opt(cfg.model)) : undefined;
+    const session = {
+        appId,
+        context: core,
+        ...(self ? { self } : {}),
+        ...(actors ? { actors } : {}),
+        ...(errors ? { errors } : {}),
+        ...(chunks ? { chunks } : {}),
+        ...(channelInbox ? { channelInbox } : {}),
+        ...(actorInbox ? { actorInbox } : {}),
+        ...(events ? { events } : {}),
+        ...(host ? { host } : {}),
+        ...(save ? { save } : {}),
+        ...(avatar ? { avatar } : {}),
+        ...(model ? { model } : {}),
+        dispose: () => core.dispose(),
+    };
+    return session;
+}

package/dist/stores/keys.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Chunk/voxel coordinate math shared by the World Stores — the helpers every
+ * voxel game re-derives (chunk keys, world→chunk mapping, the 4096-slot voxel
+ * index). A chunk is a 16×16×16 voxel cube addressed by signed-int64 chunk
+ * coordinates (decimal strings on the wire).
+ */
+import type { ChunkCoordinatesInput } from '../generated/graphql.js';
+/** Voxels per chunk axis. */
+export declare const CHUNK_SIZE = 16;
+/** Voxels per chunk (16³) — the length of a dense voxel array. */
+export declare const CHUNK_VOLUME: number;
+/** A chunk coordinate with numeric axes (convenient client-side form). */
+export interface ChunkCoord {
+    x: number;
+    y: number;
+    z: number;
+}
+/** The stable string key a chunk is cached under: `"x:y:z"`. */
+export declare function chunkKey(coord: ChunkCoord | ChunkCoordinatesInput): string;
+/** Parse a {@link chunkKey} back into numeric coordinates. */
+export declare function parseChunkKey(key: string): ChunkCoord;
+/** Convert a numeric chunk coordinate to the wire form (decimal strings). */
+export declare function toChunkInput(coord: ChunkCoord): ChunkCoordinatesInput;
+/** Convert a wire chunk coordinate (decimal strings) to numeric form. */
+export declare function fromChunkInput(coord: ChunkCoordinatesInput): ChunkCoord;
+/** The chunk containing a world-space position. */
+export declare function worldToChunk(x: number, y: number, z: number): ChunkCoord;
+/** The within-chunk voxel coordinate (0-15 per axis) of a world position. */
+export declare function worldToLocalVoxel(x: number, y: number, z: number): {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * The dense-array index of a within-chunk voxel coordinate:
+ * `x + y*16 + z*256` (the platform's chunk `voxels` layout).
+ */
+export declare function voxelIndex(x: number, y: number, z: number): number;
+/** Invert {@link voxelIndex} back to within-chunk coordinates. */
+export declare function voxelCoordFromIndex(index: number): {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * Every chunk coordinate within a Chebyshev radius of `center` (the cube
+ * `(2r+1)³`, matching `chunks.byDistance` semantics), center first.
+ */
+export declare function chunksAround(center: ChunkCoord, radius: number): ChunkCoord[];
+/** Chebyshev (chunk-grid) distance between two chunk coordinates. */
+export declare function chunkDistance(a: ChunkCoord, b: ChunkCoord): number;
+//# sourceMappingURL=keys.d.ts.map

package/dist/stores/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/stores/keys.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAErE,6BAA6B;AAC7B,eAAO,MAAM,UAAU,KAAK,CAAC;AAC7B,kEAAkE;AAClE,eAAO,MAAM,YAAY,QAAuC,CAAC;AAEjE,0EAA0E;AAC1E,MAAM,WAAW,UAAU;IACzB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;CACX;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,qBAAqB,GAAG,MAAM,CAE1E;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAGrD;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,qBAAqB,CAErE;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,UAAU,CAEvE;AAED,mDAAmD;AACnD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,UAAU,CAMxE;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,GACR;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAGrC;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,CAMtF;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,UAAU,EAAE,CAW7E;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,UAAU,GAAG,MAAM,CAElE"}

package/dist/stores/keys.js

@@ -0,0 +1,76 @@
+/**
+ * Chunk/voxel coordinate math shared by the World Stores — the helpers every
+ * voxel game re-derives (chunk keys, world→chunk mapping, the 4096-slot voxel
+ * index). A chunk is a 16×16×16 voxel cube addressed by signed-int64 chunk
+ * coordinates (decimal strings on the wire).
+ */
+/** Voxels per chunk axis. */
+export const CHUNK_SIZE = 16;
+/** Voxels per chunk (16³) — the length of a dense voxel array. */
+export const CHUNK_VOLUME = CHUNK_SIZE * CHUNK_SIZE * CHUNK_SIZE;
+/** The stable string key a chunk is cached under: `"x:y:z"`. */
+export function chunkKey(coord) {
+    return `${coord.x}:${coord.y}:${coord.z}`;
+}
+/** Parse a {@link chunkKey} back into numeric coordinates. */
+export function parseChunkKey(key) {
+    const [x, y, z] = key.split(':').map(Number);
+    return { x, y, z };
+}
+/** Convert a numeric chunk coordinate to the wire form (decimal strings). */
+export function toChunkInput(coord) {
+    return { x: String(coord.x), y: String(coord.y), z: String(coord.z) };
+}
+/** Convert a wire chunk coordinate (decimal strings) to numeric form. */
+export function fromChunkInput(coord) {
+    return { x: Number(coord.x), y: Number(coord.y), z: Number(coord.z) };
+}
+/** The chunk containing a world-space position. */
+export function worldToChunk(x, y, z) {
+    return {
+        x: Math.floor(x / CHUNK_SIZE),
+        y: Math.floor(y / CHUNK_SIZE),
+        z: Math.floor(z / CHUNK_SIZE),
+    };
+}
+/** The within-chunk voxel coordinate (0-15 per axis) of a world position. */
+export function worldToLocalVoxel(x, y, z) {
+    const mod = (n) => ((Math.floor(n) % CHUNK_SIZE) + CHUNK_SIZE) % CHUNK_SIZE;
+    return { x: mod(x), y: mod(y), z: mod(z) };
+}
+/**
+ * The dense-array index of a within-chunk voxel coordinate:
+ * `x + y*16 + z*256` (the platform's chunk `voxels` layout).
+ */
+export function voxelIndex(x, y, z) {
+    return x + y * CHUNK_SIZE + z * CHUNK_SIZE * CHUNK_SIZE;
+}
+/** Invert {@link voxelIndex} back to within-chunk coordinates. */
+export function voxelCoordFromIndex(index) {
+    return {
+        x: index % CHUNK_SIZE,
+        y: Math.floor(index / CHUNK_SIZE) % CHUNK_SIZE,
+        z: Math.floor(index / (CHUNK_SIZE * CHUNK_SIZE)),
+    };
+}
+/**
+ * Every chunk coordinate within a Chebyshev radius of `center` (the cube
+ * `(2r+1)³`, matching `chunks.byDistance` semantics), center first.
+ */
+export function chunksAround(center, radius) {
+    const out = [center];
+    for (let dx = -radius; dx <= radius; dx++) {
+        for (let dy = -radius; dy <= radius; dy++) {
+            for (let dz = -radius; dz <= radius; dz++) {
+                if (dx === 0 && dy === 0 && dz === 0)
+                    continue;
+                out.push({ x: center.x + dx, y: center.y + dy, z: center.z + dz });
+            }
+        }
+    }
+    return out;
+}
+/** Chebyshev (chunk-grid) distance between two chunk coordinates. */
+export function chunkDistance(a, b) {
+    return Math.max(Math.abs(a.x - b.x), Math.abs(a.y - b.y), Math.abs(a.z - b.z));
+}

package/dist/stores/model.d.ts

@@ -0,0 +1,81 @@
+/**
+ * ContainerMirror — the client half of the platform's **notify-to-pull**
+ * pattern for game-model state: keep typed snapshots of the containers you
+ * care about, re-pull them on demand or whenever a bound channel pings
+ * ("state changed"), and render straight from the cache.
+ *
+ * Model changes are pull-based on this platform (there is no model
+ * subscription); functions declare channel/spatial notifications and clients
+ * re-read. The Game Kit's match layer pings a per-match channel — bind the
+ * mirror to that channel and every watched container refreshes itself.
+ */
+import type { WorldSessionContext } from './session.js';
+/** A typed snapshot of one watched container. */
+export interface MirroredContainer<T = Record<string, unknown>> {
+    readonly containerId: string;
+    typeName: string;
+    displayName: string;
+    ownerUserId: string | null;
+    /** The parsed, caller-visible properties. */
+    value: T;
+    /** Bumped on every refresh that changed the snapshot. */
+    revision: number;
+    /** Local time of the last refresh. */
+    refreshedAt: number;
+}
+/** Options for {@link attachContainerMirror}. */
+export interface ContainerMirrorConfig {
+    /** Clock override for tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * The SDK-managed **model mirror**: typed, cached snapshots of watched
+ * game-model containers with coalesced refresh and channel-ping binding.
+ * Reads are synchronous ({@link get}); {@link onChange} fires only when a
+ * refresh actually changed the visible state.
+ */
+export declare class ContainerMirror {
+    private readonly ctx;
+    private readonly watches;
+    private readonly listeners;
+    private readonly boundChannels;
+    private readonly now;
+    private refreshing;
+    private refreshQueued;
+    constructor(ctx: WorldSessionContext, config?: ContainerMirrorConfig);
+    /**
+     * Watch a container: fetches the initial snapshot and keeps it refreshable.
+     * `parse` maps the visible properties object to your type (defaults to the
+     * raw object).
+     */
+    watch<T = Record<string, unknown>>(containerId: string, parse?: (properties: Record<string, unknown>) => T): Promise<MirroredContainer<T>>;
+    /** Stop watching a container (its snapshot is dropped). */
+    unwatch(containerId: string): void;
+    /** The current snapshot of a watched container (undefined before watch resolves). */
+    get<T = Record<string, unknown>>(containerId: string): MirroredContainer<T> | undefined;
+    /** Every watched snapshot. */
+    list(): Array<MirroredContainer<unknown>>;
+    /**
+     * Subscribe to snapshot changes — every watched container, or one
+     * `containerId`. Fires only when a refresh changed the visible state.
+     * @returns off.
+     */
+    onChange(handler: (container: MirroredContainer<unknown>) => void, containerId?: string): () => void;
+    /**
+     * Bind a channel: any message on it triggers a coalesced {@link refreshAll}
+     * — pair with model functions that declare channel notifications (e.g. the
+     * Game Kit's `match_changed` pings).
+     */
+    bindToChannel(channelId: string): () => void;
+    /** Re-pull one watched container now. */
+    refresh(containerId: string): Promise<void>;
+    /**
+     * Re-pull every watched container. Concurrent calls coalesce: a refresh
+     * requested while one is running queues exactly one follow-up pass (pings
+     * can burst; state converges without stampeding the API).
+     */
+    refreshAll(): Promise<void>;
+}
+/** Attach a {@link ContainerMirror}. Prefer the `model` config key. */
+export declare function attachContainerMirror(ctx: WorldSessionContext, config?: ContainerMirrorConfig): ContainerMirror;
+//# sourceMappingURL=model.d.ts.map

package/dist/stores/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/stores/model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,iDAAiD;AACjD,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC5D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,6CAA6C;IAC7C,KAAK,EAAE,CAAC,CAAC;IACT,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,qBAAqB;IACpC,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AASD;;;;;GAKG;AACH,qBAAa,eAAe;IAYxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAXtB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiC;IACzD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAGrB;IACL,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAS;gBAGX,GAAG,EAAE,mBAAmB,EACzC,MAAM,GAAE,qBAA0B;IAcpC;;;;OAIG;IACG,KAAK,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACrC,WAAW,EAAE,MAAM,EACnB,KAAK,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GACjD,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC;IAWhC,2DAA2D;IAC3D,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIlC,qFAAqF;IACrF,GAAG,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAAC,CAAC,CAAC,GAAG,SAAS;IAMvF,8BAA8B;IAC9B,IAAI,IAAI,KAAK,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAQzC;;;;OAIG;IACH,QAAQ,CACN,OAAO,EAAE,CAAC,SAAS,EAAE,iBAAiB,CAAC,OAAO,CAAC,KAAK,IAAI,EACxD,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,IAAI;IAMb;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,IAAI;IAK5C,yCAAyC;IACnC,OAAO,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiDjD;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAqBlC;AAED,uEAAuE;AACvE,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,mBAAmB,EACxB,MAAM,GAAE,qBAA0B,GACjC,eAAe,CAEjB"}