cajonzero 0.1.2 → 0.2.0

package/dist/{providers-BX7e4pNW.d.ts → providers-Bu0-iMVs.d.ts}

@@ -1,4 +1,5 @@
 import { Storage, StorageValue, Driver } from 'unstorage';
+import { M as MapEntry } from './catalog-BRO-mQoP.js';
 import * as gl_matrix from 'gl-matrix';
 import { vec3, mat3 } from 'gl-matrix';
 import { z } from 'zod';
@@ -131,6 +132,10 @@ interface R2Bucket {
     delete(key: string): Promise<void>;
     list(options?: unknown): Promise<unknown>;
 }
+/** Structural stand-in for workerd's static-assets `Fetcher` binding. */
+interface AssetsBinding {
+    fetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
 /**
  * Runtime bindings + secrets injected by the Cloudflare Workers runtime.
  *
@@ -140,8 +145,20 @@ interface R2Bucket {
 interface Env {
     /** KV namespace: map code/asset KV and player data (unstorage KV adapter). */
     readonly CAJONZERO_KV: KVNamespace;
+    /**
+     * Optional private KV namespace for server-only map scripts.
+     *
+     * Public seed packs strip `scripts`; this binding is the non-public half
+     * (`scripts:<slug>` → `cajonzero-scripts` JSON). Never served over HTTP.
+     */
+    readonly CAJONZERO_SCRIPTS?: KVNamespace;
     /** Durable Object namespace for per-room actors (`Room`). */
     readonly ROOMS: DurableObjectNamespace;
+    /**
+     * Static-assets binding (`assets.binding`). Optional: older deployments
+     * without it still work, they just cannot read the worker-bundled seed packs.
+     */
+    readonly ASSETS?: AssetsBinding;
     /** Optional R2 bucket for large map assets; absent in minimal deployments. */
     readonly CAJONZERO_R2?: R2Bucket;
     /** Admin bearer token guarding the management/ban API. Secret. */
@@ -501,59 +518,6 @@ interface SessionRegistry {
     current(accountId: string): Promise<SessionSlotRecord | undefined>;
 }
 
-/**
- * cajonzero — the map catalog (`cajonzero/maps.json`).
- *
- * Maps are **not** stored by cajonzero. A `.boxplay` is unpacked by the operator
- * and uploaded to object storage (OSS/CDN); `maps.json` only records where each
- * map's unpacked root lives.
- *
- * Expected layout under `entry.root` (exactly the archive layout):
- *
- * ```text
- * <root>/bundle.json
- * <root>/worlds/<worldId>/manifest.json
- * <root>/worlds/<worldId>/data/project-state.json
- * <root>/worlds/<worldId>/data/blobs/<cid>
- * ```
- *
- * Worker path: URL handling + validation only, no Node globals.
- */
-/** The only catalog version this build understands. */
-declare const MAP_CATALOG_VERSION = 1;
-/** One map in the catalog. */
-interface MapEntry {
-    /** Stable room/catalog id (`omega`, `drift`, …). */
-    readonly slug: string;
-    /** Unpacked map root, absolute `http(s)://…/` URL. */
-    readonly root: string;
-    /** `worlds/<worldId>` directory name; derived from `bundle.json` when absent. */
-    readonly worldId?: string;
-    /** Display name (falls back to the map's own manifest). */
-    readonly name?: string;
-    readonly author?: string;
-    readonly version?: string;
-    /** Cover image URL for the lobby. */
-    readonly cover?: string;
-    /** Optional CDN root for browser assets; defaults to {@link root}. */
-    readonly assetRoot?: string;
-}
-/** The `maps.json` document. */
-interface MapCatalog {
-    readonly version: typeof MAP_CATALOG_VERSION;
-    readonly maps: readonly MapEntry[];
-}
-/** No maps configured (the scaffold default). */
-declare const EMPTY_MAP_CATALOG: MapCatalog;
-/**
- * Validate a parsed `maps.json`.
- *
- * @throws {MapCatalogError} for a malformed document, entry, or duplicate slug.
- */
-declare function parseMapCatalog(input: unknown): MapCatalog;
-/** Look up a map by slug. */
-declare function findMap(catalog: MapCatalog, slug: string): MapEntry | undefined;
-
 declare class MuBuffer {
     buffer: ArrayBuffer;
     dataView: DataView;
@@ -2414,6 +2378,8 @@ interface SeedMesh {
         duration: number;
     }[];
     renderBoxOffset?: [number, number, number];
+    /** `voxelModel` | `gltfModel` (client model loader dispatch). */
+    hashType?: string;
 }
 /** A map entity that should render a mesh (static scenery / vehicles). */
 interface SeedRenderEntity {
@@ -2434,6 +2400,36 @@ interface SeedRender {
     entities: SeedRenderEntity[];
     warnings: string[];
 }
+/** One server-side script module resolved from `scriptAssets`. */
+interface SeedScriptModule {
+    /** Content hash (`data/blobs/<hash>`). */
+    hash: string;
+    /** UTF-8 module source. */
+    source: string;
+    /** Editor ordering hint (diagnostics only). */
+    order: number;
+    /** Logical name from `scriptAssets` (usually the file id). */
+    name?: string;
+}
+/** Resolved server-side map scripts (`scriptIndex` + modules). */
+interface SeedScripts {
+    /** Entry module key, e.g. `index.js` (empty when the map has no scripts). */
+    index: string;
+    modules: Record<string, SeedScriptModule>;
+    /** Map catalog version/etag at pack time (private-pack cache key). */
+    revision?: string;
+}
+/** Per-entity seed metadata used by the map-script runtime (name + tags). */
+interface SeedEntitySeedInfo {
+    id: number;
+    name: string;
+    tags: string[];
+}
+/** One audio asset (path → content hash) for `world.sound` / `resources`. */
+interface SeedAudioAsset {
+    path: string;
+    hash: string;
+}
 /** The resolved, pure world seed. */
 interface WorldSeed {
     version: number;
@@ -2452,6 +2448,12 @@ interface WorldSeed {
     voxels: SeedVoxels | null;
     /** Mesh/entity render projection (empty when the map has no models). */
     render?: SeedRender;
+    /** Server-side map scripts. Never include this in a public seed pack. */
+    scripts?: SeedScripts;
+    /** Entity names/tags used to seed the map-script entity table. */
+    seedInfo?: SeedEntitySeedInfo[];
+    /** Audio assets for `resources` / `world.sound`. */
+    audioAssets?: SeedAudioAsset[];
     /** Number of entities present in the map's `entitiesTree`. */
     entityCount: number;
     /** Human-readable record of anything skipped (never silently dropped). */
@@ -2644,6 +2646,32 @@ interface SettingsService {
 /** Construct a {@link SettingsService} over a T4 `SettingsRepo`. */
 declare function createSettingsService(options: CreateSettingsServiceOptions): SettingsService;
 
+type ProtocolMessageHandler = (sessionId: string, data: unknown, unreliable: boolean) => void;
+interface ProtocolBusOptions {
+    /** Send reliable bytes on the player's game socket. */
+    send(sessionId: string, bytes: Uint8Array, unreliable: boolean): void;
+}
+declare class ProtocolBus {
+    private readonly options;
+    private readonly inbound;
+    private readonly outbound;
+    private readonly inboundByBase;
+    private readonly handlers;
+    constructor(options: ProtocolBusOptions);
+    /** Register a handler for one inbound protocol message. */
+    on(protocol: string, message: string, handler: ProtocolMessageHandler): void;
+    /**
+     * Try to decode a post-game-net frame. Returns `true` when the id belongs to
+     * this bus (even if no handler is registered), so `NetCodec` never logs it as
+     * unknown. Returns `false` for game-net frames.
+     */
+    tryDecode(sessionId: string, data: Uint8Array | string, unreliable: boolean): boolean;
+    /** Encode one server→client message for `protocol`. */
+    encode(protocol: string, message: string, payload: unknown): Uint8Array | null;
+    /** Encode and send one server→client message. */
+    send(sessionId: string, protocol: string, message: string, payload: unknown, unreliable?: boolean): boolean;
+}
+
 /**
  * cajonzero — mudb `MuSocketServer`-compatible adapter for Cloudflare workerd (T8).
  *
@@ -4930,6 +4958,8 @@ interface ScriptHost {
     clearEvents(): void;
     suspend(): void;
     resume(): void;
+    /** Optional teardown (QuickJS VM, timers). Called when the room is replaced. */
+    dispose?(): void;
 }
 /** The Durable Object storage surface the room uses (structural). */
 interface RoomStorage {
@@ -4965,6 +4995,14 @@ interface RoomOptions {
      */
     emptyGraceMs?: number;
     heartbeatIntervalMs?: number;
+    /**
+     * Drop a connection that has sent no frame for this long (ms). Defaults to
+     * {@link DEFAULT_PLAYER_IDLE_TIMEOUT_MS}. This is the room's own liveness
+     * check — a client that never sends a close frame must still be removed.
+     */
+    playerIdleTimeoutMs?: number;
+    /** How often to look for silent connections (ms). Defaults to 60 s. */
+    idleSweepIntervalMs?: number;
     maxStepsPerFrame?: number;
     /** Simulation engine. Defaults to the registered factory or a null engine. */
     engine?: RoomEngine;
@@ -5027,11 +5065,21 @@ declare class Room {
     /** Tracks the async settings read that arms the grace timer at drain. */
     private graceOps;
     private readonly heartbeatIntervalMs;
+    private readonly playerIdleTimeoutMs;
+    private readonly idleSweepIntervalMs;
+    /** Wall-clock of the last sweep for silent connections. */
+    private lastIdleSweepAt;
+    /** Last time an inbound frame was seen per session (liveness). */
+    private readonly lastSeenAt;
     private readonly maxStepsPerFrame;
     private readonly manualClock;
     private readonly createPair;
     private readonly logger;
     private readonly secret;
+    /** Worker static-assets binding, used to read seed packs bundled at deploy. */
+    private readonly assets;
+    private readonly scriptsKv;
+    private readonly store;
     private engine;
     private script;
     private readonly explicitScriptHost;
@@ -5039,6 +5087,7 @@ declare class Room {
     private readonly sockets;
     /** mudb wire codec: protocol envelope + netcode frames. */
     private readonly codec;
+    private readonly protocolBus;
     private readonly modelCodec;
     private readonly messageHandlers;
     private readonly banChecker;
@@ -5094,6 +5143,10 @@ declare class Room {
     private pendingEngineMap;
     /** Identity of the map the current engine was seeded from. */
     private seededMap;
+    /** Non-fatal seed warnings (missing blobs, skipped entities, …). */
+    private seedWarnings;
+    /** Last map-load failure; cleared on a successful seed. */
+    private mapLoadError;
     private heartbeatBeats;
     private ticksRun;
     private lastTickError;
@@ -5142,6 +5195,14 @@ declare class Room {
     private applyPendingEngineSnapshot;
     private loadWorld;
     private loadSeed;
+    /**
+     * Merge the private scripts pack (`CAJONZERO_SCRIPTS`) into a public seed.
+     *
+     * Public seed packs deliberately strip `scripts`; this binding is the
+     * server-only half and is never served over HTTP. Missing/broken packs keep
+     * the room playable without scripts.
+     */
+    private attachPrivateScripts;
     /**
      * Run the full connect path and return a structured outcome (no `Response`,
      * so tests can drive it without a workerd runtime). Steps: resolve the sid →
@@ -5160,7 +5221,6 @@ declare class Room {
     private admitConnectionOnce;
     private startSockets;
     private registerSocket;
-    /** Build the per-connection codec callback table (allocated once per socket). */
     private createHandlers;
     /**
      * Decode one inbound frame. A protocol violation closes the socket exactly like
@@ -5258,6 +5318,17 @@ declare class Room {
      * secret diff → pings → clear events.
      */
     tickOnce(): void;
+    /**
+     * Drop connections the client never told us about.
+     *
+     * A player is normally removed by `removeClient` when the socket closes, but
+     * a browser cannot be trusted to send that close frame: an SPA that tears the
+     * engine down half-way, a sleeping laptop, a dropped mobile link or a killed
+     * tab all leave the socket open from the room's point of view. Without this
+     * sweep the player stays in the world for everyone else and keeps the
+     * account's session slot.
+     */
+    private sweepIdleConnections;
     private buildContext;
     private buildSecret;
     private startTickLoop;
@@ -5295,6 +5366,8 @@ declare class Room {
     get phase(): RoomPhase;
     /** Current simulation tick. */
     get tick(): number;
+    /** Extra game-socket protocols (dialog/chat/gui/...) after `game-net`. */
+    getProtocolBus(): ProtocolBus;
     /** `true` once the empty-grace window has elapsed (heartbeat released). */
     get isEvictable(): boolean;
     /** `true` while the draining heartbeat is armed (the DO is pinned). */
@@ -5361,5 +5434,5 @@ declare function resolveEnvironment(env: Env): string | undefined;
 declare function resolveRooms(env: Env): DurableObjectNamespace | undefined;
 declare function resolveSettingDefaults(env: Env): SettingDefaults | undefined;
 
-export { parseMapCatalog as A, resolveAdminToken as B, resolveEnvironment as C, resolveRooms as F, resolveSessionSecret as G, resolveSettingDefaults as H, resolveStore as I, setRuntimeProviders as J, setStorageFactory as K, Room as R, EMPTY_MAP_CATALOG as c, SETTINGS as h, SETTING_KEYS as i, SettingsError as l, configureDefaultKV as r, createMemoryStore as s, createRepos as t, createSettingsService as u, createStore as v, findMap as w, getRuntimeProviders as x, isSettingKey as y, memoryDriver as z };
-export type { DurableObjectNamespace as D, EnvProvider as E, SessionsRepo as L, MapEntry as M, NetPublic as N, NetSecret as O, StorageSource as S, TimestampedClientInput as T, WorldSeed as W, SettingDefaults as a, Env as b, MapCatalog as d, Repos as e, RoomOptions as f, RuntimeProviders as g, SettingDefinition as j, Settings as k, SettingsErrorCode as m, SettingsService as n, StorageFactory as o, Store as p, WorldSeedReader as q };
+export { resolveSessionSecret as A, resolveSettingDefaults as B, resolveStore as C, setRuntimeProviders as F, setStorageFactory as G, Room as R, SETTINGS as f, SETTING_KEYS as g, SettingsError as j, configureDefaultKV as p, createMemoryStore as q, createRepos as r, createSettingsService as s, createStore as t, getRuntimeProviders as u, isSettingKey as v, memoryDriver as w, resolveAdminToken as x, resolveEnvironment as y, resolveRooms as z };
+export type { DurableObjectNamespace as D, EnvProvider as E, SessionsRepo as H, NetSecret as I, NetPublic as N, StorageSource as S, TimestampedClientInput as T, WorldSeed as W, SettingDefaults as a, Env as b, Repos as c, RoomOptions as d, RuntimeProviders as e, SettingDefinition as h, Settings as i, SettingsErrorCode as k, SettingsService as l, StorageFactory as m, Store as n, WorldSeedReader as o };

package/dist/scaffold.d.ts

@@ -10,8 +10,8 @@
  * ## Where configuration lives
  *
  * - `cajonzero/config.json` — cajonzero runtime config (room policy, map fetch policy).
- * - `cajonzero/maps.json`   — the map catalog; entries point at unpacked map roots
- *   hosted on OSS/CDN. Maps are never stored in the project.
+ * - `cajonzero/maps.json`   — the map catalog; `cj0 add` writes `/maps/<slug>/` roots
+ *   (static assets) and the operator may switch a root to an external CDN URL.
  * - `wrangler.jsonc`      — Cloudflare bindings (KV, Durable Object, assets).
  *
  * `buildScaffoldFiles()` is imported by BOTH the scaffolder (`createProject`)
@@ -62,7 +62,7 @@ declare const SCAFFOLD_KV_PLACEHOLDER_ID = "PLACEHOLDER_KV_ID";
 declare const SCAFFOLD_ENTRY_CONTENT: string;
 /** `cajonzero/config.json` — runtime policy; secrets stay in `wrangler secret`. */
 declare const SCAFFOLD_CONFIG_CONTENT: string;
-/** `cajonzero/maps.json` — empty by default; see the README for an entry. */
+/** `cajonzero/maps.json` — empty by default; `cj0 add` fills it. */
 declare const SCAFFOLD_MAPS_CONTENT: string;
 /**
  * Render the complete, deterministically ordered set of files for a created
@@ -147,7 +147,7 @@ declare function toPackageName(folder: string): string;
 declare function createProject(folder: string, options?: CreateProjectOptions): ScaffoldResult;
 
 /** Where one setup value is written. */
-type SetupKind = "var" | "secret";
+type SetupKind = "var" | "secret" | "kv";
 /** One configurable value. */
 interface SetupField {
     readonly name: string;
@@ -171,6 +171,8 @@ interface SetupResult {
     readonly vars: Record<string, string>;
     /** Secrets written to `.dev.vars`. */
     readonly secrets: Record<string, string>;
+    /** KV namespace id written to `wrangler.jsonc` (when provided). */
+    readonly kvId?: string;
 }
 interface SetupOptions {
     readonly cwd?: string;
@@ -189,6 +191,19 @@ declare function suggestedValue(field: SetupField): string | undefined;
 declare function parseDevVars(text: string): Record<string, string>;
 /** Serialize `.dev.vars` (stable order, trailing newline). */
 declare function serializeDevVars(values: Record<string, string>): string;
+/** Strip `//` / block comments and trailing commas so a JSONC object can be parsed. */
+declare function parseJsoncObject(text: string): Record<string, unknown>;
+/**
+ * Read the KV namespace id bound to `binding` from a wrangler config.
+ * Returns `undefined` when the binding is absent or the id is the placeholder.
+ */
+declare function readWranglerKvNamespaceId(raw: string, binding?: string): string | undefined;
+/**
+ * Set the `id` of the `kv_namespaces` entry bound to `binding`, preserving
+ * comments and unrelated JSONC formatting. Adds the entry (or the whole
+ * `kv_namespaces` array) when missing.
+ */
+declare function setWranglerKvNamespaceId(raw: string, binding: string, id: string): string;
 /**
  * Merge `vars` into the `wrangler.jsonc` `"vars"` object.
  *
@@ -204,5 +219,57 @@ declare function readSetupValues(cwd: string, configPath: string, devVarsPath: s
  */
 declare function applySetup(options: SetupOptions): SetupResult;
 
-export { SCAFFOLD_COMPATIBILITY_DATE, SCAFFOLD_CONFIG_CONTENT, SCAFFOLD_ENTRY_CONTENT, SCAFFOLD_ENTRY_PATH, SCAFFOLD_KV_PLACEHOLDER_ID, SCAFFOLD_MAPS_CONTENT, SETUP_FIELDS, ScaffoldError, applySetup, buildScaffoldFiles, createProject, generateAdminToken, generateSecret, parseDevVars, readCajonzeroPackage, readSetupValues, serializeDevVars, setWranglerVars, suggestedValue, toPackageName };
-export type { CajonzeroPackageInfo, CreateProjectOptions, ScaffoldErrorCode, ScaffoldFile, ScaffoldResult, ScaffoldTemplateOptions, SetupField, SetupKind, SetupOptions, SetupResult };
+/** Marker written inside the target dir; excluded from the copy and the hash. */
+declare const ASSETS_STAMP_FILE = ".cajonzero-assets.json";
+/**
+ * Subdirectory of the assets directory that holds `cj0 add` map imports.
+ * {@link syncPublicAssets} preserves it when re-syncing the packaged UI.
+ */
+declare const ASSETS_MAPS_DIR = "maps";
+/** Preserved file (keeps an otherwise empty `public/` in git). */
+declare const ASSETS_KEEP_FILE = ".gitkeep";
+/** Options for {@link syncPublicAssets}. */
+interface SyncPublicAssetsOptions {
+    /** Project directory (default: `process.cwd()`). */
+    readonly cwd?: string;
+    /** Wrangler config, relative to `cwd` (default: `wrangler.jsonc`). */
+    readonly configPath?: string;
+    /**
+     * Target directory, relative to the config's directory. Overrides
+     * `assets.directory` from the config.
+     */
+    readonly assetsDir?: string;
+    /** Source tree override (tests). Defaults to the installed package's `dist/ui`. */
+    readonly sourceDir?: string;
+    /** Copy even when the fingerprint already matches. */
+    readonly force?: boolean;
+}
+/** Result of a successful sync. */
+interface SyncPublicAssetsResult {
+    /** Absolute source directory (the packaged UI). */
+    readonly sourceDir: string;
+    /** Absolute target directory (the project's `assets.directory`). */
+    readonly targetDir: string;
+    /** Content fingerprint of the source tree. */
+    readonly fingerprint: string;
+    /** `false` when the target was already up to date. */
+    readonly copied: boolean;
+    /** Number of files in the source tree. */
+    readonly files: number;
+    /** Total uncompressed bytes in the source tree. */
+    readonly bytes: number;
+}
+/** Throw when `configPath` is missing or has no `assets.directory`. */
+declare function readWranglerAssetsDirectory(configPath: string): string | undefined;
+/**
+ * Copy cajonzero's packaged UI into the project's static-asset directory.
+ * Idempotent: a matching fingerprint is a no-op. Imported maps under
+ * `<target>/maps/` and a `.gitkeep` are preserved across the wipe.
+ *
+ * @throws when the packaged UI is missing, the config has no `assets.directory`
+ *   and no override was given, or the target would overlap the project/source.
+ */
+declare function syncPublicAssets(options?: SyncPublicAssetsOptions): Promise<SyncPublicAssetsResult>;
+
+export { ASSETS_KEEP_FILE, ASSETS_MAPS_DIR, ASSETS_STAMP_FILE, SCAFFOLD_COMPATIBILITY_DATE, SCAFFOLD_CONFIG_CONTENT, SCAFFOLD_ENTRY_CONTENT, SCAFFOLD_ENTRY_PATH, SCAFFOLD_KV_PLACEHOLDER_ID, SCAFFOLD_MAPS_CONTENT, SETUP_FIELDS, ScaffoldError, applySetup, buildScaffoldFiles, createProject, generateAdminToken, generateSecret, parseDevVars, parseJsoncObject, readCajonzeroPackage, readSetupValues, readWranglerAssetsDirectory, readWranglerKvNamespaceId, serializeDevVars, setWranglerKvNamespaceId, setWranglerVars, suggestedValue, syncPublicAssets, toPackageName };
+export type { CajonzeroPackageInfo, CreateProjectOptions, ScaffoldErrorCode, ScaffoldFile, ScaffoldResult, ScaffoldTemplateOptions, SetupField, SetupKind, SetupOptions, SetupResult, SyncPublicAssetsOptions, SyncPublicAssetsResult };