cajonzero 0.1.2 → 0.1.3

package/dist/index.js

@@ -11,7 +11,7 @@ import 'unstorage/drivers/memory';
 
 // src/version.ts
 var NAME = "cajonzero";
-var VERSION = "0.1.1";
+var VERSION = "0.1.3";
 
 // src/core/config.ts
 var ConfigError = class extends Error {
@@ -213,6 +213,7 @@ function parseEntry(value, index) {
   const name = optionalString2(record.name, `maps[${index}].name`);
   const author = optionalString2(record.author, `maps[${index}].author`);
   const version = optionalString2(record.version, `maps[${index}].version`);
+  const etag = optionalString2(record.etag, `maps[${index}].etag`);
   const cover = optionalString2(record.cover, `maps[${index}].cover`);
   return {
     slug,
@@ -221,6 +222,7 @@ function parseEntry(value, index) {
     ...name !== void 0 ? { name } : {},
     ...author !== void 0 ? { author } : {},
     ...version !== void 0 ? { version } : {},
+    ...etag !== void 0 ? { etag } : {},
     ...cover !== void 0 ? { cover } : {},
     ...assetRoot !== void 0 ? { assetRoot: normalizeRootUrl(assetRoot) } : {}
   };
@@ -16155,16 +16157,125 @@ function decodeBlockInfo(bytes) {
     return null;
   }
 }
-async function loadBlockInfo(reader, worldId, hash = BLOCK_INFO_HASH) {
+async function readBlockInfoBytes(reader, worldId, hash = BLOCK_INFO_HASH) {
   try {
     const bytes = await reader.read(`worlds/${worldId}/data/blobs/${hash}`);
     if (bytes === null || bytes.length === 0) return null;
-    return decodeBlockInfo(bytes);
+    return bytes;
   } catch {
     return null;
   }
 }
 
+// src/core/maps/seed-pack.ts
+var SEED_PACK_VERSION = 1;
+var SEED_PACK_FORMAT = "cajonzero-seed";
+var SEED_PACK_FILES = ["seed.json.gz", "seed.json"];
+function isGzip(bytes) {
+  return bytes.length >= 2 && bytes[0] === 31 && bytes[1] === 139;
+}
+async function gunzipBytes(bytes) {
+  if (typeof DecompressionStream === "undefined") {
+    throw new Error("this runtime does not support gzip seed packs");
+  }
+  const buffer = bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength
+  );
+  const stream = new Blob([buffer]).stream().pipeThrough(new DecompressionStream("gzip"));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+async function decodeSeedPackAuto(bytes) {
+  return decodeSeedPack(isGzip(bytes) ? await gunzipBytes(bytes) : bytes);
+}
+async function loadSeedPackFromAssets(assets, slug, worldId) {
+  if (assets === void 0) return null;
+  for (const file of SEED_PACK_FILES) {
+    const suffix = file.slice("seed".length);
+    const path = `/seed/${encodeURIComponent(slug)}${suffix}`;
+    try {
+      const response = await assets.fetch(new Request(`https://cajonzero.internal${path}`));
+      if (!response.ok) continue;
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      const seed = await decodeSeedPackAuto(bytes);
+      if (worldId !== void 0 && worldId.length > 0 && seed.mapId !== worldId) continue;
+      return seed;
+    } catch {
+    }
+  }
+  return null;
+}
+function base64ToBytes(text) {
+  const binary = atob(text);
+  const out = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) out[i] = binary.charCodeAt(i);
+  return out;
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeSeedPack(bytes) {
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    throw new Error("seed pack is not valid JSON");
+  }
+  if (!isRecord2(parsed) || parsed["format"] !== SEED_PACK_FORMAT) {
+    throw new Error("not a cajonzero seed pack");
+  }
+  if (parsed["version"] !== SEED_PACK_VERSION) {
+    throw new Error(
+      `unsupported seed pack version ${String(parsed["version"])} (expected ${SEED_PACK_VERSION})`
+    );
+  }
+  if (typeof parsed["mapId"] !== "string" || parsed["mapId"].length === 0) {
+    throw new Error("seed pack is missing mapId");
+  }
+  if (!isRecord2(parsed["seed"])) {
+    throw new Error("seed pack is missing the seed payload");
+  }
+  const rawSeed = parsed["seed"];
+  if (rawSeed["version"] !== WORLD_SEED_VERSION) {
+    throw new Error(
+      `seed pack was built for world-seed v${String(rawSeed["version"])} (this runtime expects v${WORLD_SEED_VERSION}); re-run cj0 maps pack`
+    );
+  }
+  const rawVoxels = rawSeed["voxels"];
+  let voxels = null;
+  if (rawVoxels !== null) {
+    if (!isRecord2(rawVoxels)) throw new Error("seed pack voxels are malformed");
+    const blobs = rawVoxels["chunkBlobs"];
+    if (!Array.isArray(blobs)) throw new Error("seed pack voxels are malformed");
+    const rawShape = rawVoxels["shape"];
+    const shape = isRecord2(rawShape) ? {
+      x: Number(rawShape["x"]) || 0,
+      y: Number(rawShape["y"]) || 0,
+      z: Number(rawShape["z"]) || 0
+    } : { x: 0, y: 0, z: 0 };
+    const hashes = rawVoxels["chunkHashes"];
+    voxels = {
+      shape,
+      chunkCount: Number(rawVoxels["chunkCount"]) || blobs.length,
+      chunkBlobs: blobs.map(
+        (blob) => typeof blob === "string" ? base64ToBytes(blob) : new Uint8Array(0)
+      ),
+      chunkHashes: Array.isArray(hashes) ? hashes.map((hash) => typeof hash === "string" ? hash : "") : []
+    };
+  }
+  const { voxels: _ignored, ...rest } = rawSeed;
+  const seed = {
+    ...rest,
+    mapId: parsed["mapId"],
+    voxels
+  };
+  if (typeof parsed["blockInfo"] === "string" && parsed["blockInfo"].length > 0) {
+    const blockInfo = decodeBlockInfo(base64ToBytes(parsed["blockInfo"]));
+    if (blockInfo !== null) seed.blockInfo = blockInfo;
+  }
+  return seed;
+}
+
 // src/core/maps/http.ts
 var MapSourceError = class extends Error {
   code;
@@ -16267,14 +16378,14 @@ var HttpMapSource = class {
     return new Uint8Array(buffer);
   }
 };
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 async function resolveWorldId(source) {
   const bundle = await source.readJson("bundle.json");
   if (bundle === null) fail3("MAP_NO_WORLD", "bundle.json is missing or not JSON");
   const members = Array.isArray(bundle.members) ? bundle.members : [];
-  const records = members.filter(isRecord2);
+  const records = members.filter(isRecord3);
   const main = records.find((member) => member.mapRole === "main") ?? records[0];
   const candidate = (main !== void 0 && typeof main.id === "string" ? main.id : void 0) ?? (typeof bundle.mainProjectId === "string" ? bundle.mainProjectId : void 0);
   if (candidate === void 0) {
@@ -16283,6 +16394,13 @@ async function resolveWorldId(source) {
   return assertWorldId(candidate);
 }
 async function loadWorldSeedFromHttp(entry, options = {}) {
+  if (options.preferSeedPack !== false) {
+    const packed = await loadSeedPackFromHttp(entry, options);
+    if (packed !== null) return packed;
+  }
+  return (await loadWorldSeedGraphFromHttp(entry, options)).seed;
+}
+async function loadWorldSeedGraphFromHttp(entry, options = {}) {
   const source = new HttpMapSource(entry.root, options);
   const worldId = entry.worldId ?? await resolveWorldId(source);
   const manifest = await source.readJson(
@@ -16291,13 +16409,35 @@ async function loadWorldSeedFromHttp(entry, options = {}) {
   if (manifest === null) {
     fail3("MAP_NO_WORLD", `worlds/${worldId}/manifest.json is missing or not JSON`);
   }
-  return resolveWorldSeed(
+  const seed = await resolveWorldSeed(
     { worldId, manifest, reader: source },
     { concurrency: options.concurrency ?? DEFAULT_CONCURRENCY }
-  ).then(async (seed) => {
-    const blockInfo = await loadBlockInfo(source, worldId);
-    return blockInfo === null ? seed : { ...seed, blockInfo };
-  });
+  );
+  const blockInfoBytes = await readBlockInfoBytes(source, worldId) ?? void 0;
+  const blockInfo = blockInfoBytes === void 0 ? null : decodeBlockInfo(blockInfoBytes);
+  return {
+    seed: blockInfo === null ? seed : { ...seed, blockInfo },
+    ...blockInfoBytes !== void 0 ? { blockInfoBytes } : {}
+  };
+}
+async function loadSeedPackFromHttp(entry, options) {
+  const source = new HttpMapSource(entry.root, options);
+  for (const file of SEED_PACK_FILES) {
+    let bytes;
+    try {
+      bytes = await source.read(file);
+    } catch {
+      continue;
+    }
+    if (bytes === null) continue;
+    try {
+      const seed = await decodeSeedPackAuto(bytes);
+      if (entry.worldId !== void 0 && seed.mapId !== entry.worldId) continue;
+      return seed;
+    } catch {
+    }
+  }
+  return null;
 }
 
 // src/core/net/framing.ts
@@ -24521,6 +24661,8 @@ var Room = class {
   createPair;
   logger;
   secret;
+  /** Worker static-assets binding, used to read seed packs bundled at deploy. */
+  assets;
   engine;
   script;
   explicitScriptHost;
@@ -24583,6 +24725,10 @@ var Room = class {
   pendingEngineMap;
   /** Identity of the map the current engine was seeded from. */
   seededMap;
+  /** Non-fatal seed warnings (missing blobs, skipped entities, …). */
+  seedWarnings = [];
+  /** Last map-load failure; cleared on a successful seed. */
+  mapLoadError;
   heartbeatBeats = 0;
   ticksRun = 0;
   lastTickError;
@@ -24606,6 +24752,7 @@ var Room = class {
     this.createPair = options.createPair ?? defaultCreatePair;
     this.logger = options.logger ?? defaultLogger;
     this.secret = options.secret ?? resolveSessionSecret(env);
+    this.assets = env.ASSETS;
     this.engine = options.engine ?? getRoomEngineFactory()?.() ?? createNullEngine();
     this.explicitScriptHost = options.scriptHost !== void 0;
     this.script = options.scriptHost ?? this.engine;
@@ -24700,7 +24847,9 @@ var Room = class {
           ok: true,
           slug: this.mapBootstrap?.slug ?? null,
           seeded: this.worldReady,
-          entities: this.engine.getReplica().entities.length
+          entities: this.engine.getReplica().entities.length,
+          mapLoadError: this.mapLoadError ?? null,
+          warnings: this.seedWarnings
         }),
         { headers: { "content-type": "application/json", "cache-control": "no-store" } }
       );
@@ -24731,6 +24880,8 @@ var Room = class {
           secretPackets: this.secretPackets,
           clockPings: this.clockPings,
           inboundIds: Object.fromEntries(this.inboundIds),
+          mapLoadError: this.mapLoadError ?? null,
+          mapWarnings: this.seedWarnings,
           voxel: this.engine.voxelGeometry?.() ?? null,
           sampleEntity: (() => {
             const entity = this.engine.getReplica().entities[0];
@@ -24828,21 +24979,32 @@ var Room = class {
       this.engine = engine;
       if (!this.explicitScriptHost) this.script = engine;
       this.seededMap = { slug: bootstrap.slug, root: bootstrap.root, worldId: seed.mapId };
+      this.seedWarnings = seed.warnings;
+      this.mapLoadError = void 0;
+      for (const warning of seed.warnings) {
+        this.logger.log(`cajonzero: map "${bootstrap.slug}" warning: ${warning}`);
+      }
       this.applyPendingEngineSnapshot();
       this.worldReady = true;
       this.logger.log(`cajonzero: seeded room "${bootstrap.slug}" from "${seed.mapId}"`);
     } catch (error) {
+      this.mapLoadError = describeError2(error);
       this.logger.error(
-        `cajonzero: map load failed for "${bootstrap.slug}": ${describeError2(error)}`
+        `cajonzero: map load failed for "${bootstrap.slug}": ${this.mapLoadError}`
       );
     }
   }
   loadSeed(bootstrap) {
-    return loadWorldSeedFromHttp(bootstrap, {
-      ...bootstrap.maxDownloadBytes !== void 0 ? { maxDownloadBytes: bootstrap.maxDownloadBytes } : {},
-      ...bootstrap.concurrency !== void 0 ? { concurrency: bootstrap.concurrency } : {},
-      ...bootstrap.requestTimeoutMs !== void 0 ? { requestTimeoutMs: bootstrap.requestTimeoutMs } : {}
-    });
+    return loadSeedPackFromAssets(this.assets, bootstrap.slug, bootstrap.worldId).then(
+      (packed) => {
+        if (packed !== null) return packed;
+        return loadWorldSeedFromHttp(bootstrap, {
+          ...bootstrap.maxDownloadBytes !== void 0 ? { maxDownloadBytes: bootstrap.maxDownloadBytes } : {},
+          ...bootstrap.concurrency !== void 0 ? { concurrency: bootstrap.concurrency } : {},
+          ...bootstrap.requestTimeoutMs !== void 0 ? { requestTimeoutMs: bootstrap.requestTimeoutMs } : {}
+        });
+      }
+    );
   }
   /**
    * Run the full connect path and return a structured outcome (no `Response`,
@@ -26658,7 +26820,7 @@ function createPlayEngine(options = {}) {
   const spawnOnClientInput = options.spawnOnClientInput ?? true;
   const scriptHost = options.scriptHost;
   const physicsOverride = options.physics ? buildPhysicsOverride(options.physics) : null;
-  const playerConfig = isRecord3(options.worldSeed?.player) ? options.worldSeed.player : null;
+  const playerConfig = isRecord4(options.worldSeed?.player) ? options.worldSeed.player : null;
   let world = options.world ? NetStateSchema.clone(options.world) : options.worldSeed ? buildInitialWorld(options.worldSeed) : null;
   let currentTick = 0;
   let suspended = false;
@@ -26977,7 +27139,7 @@ function buildPhysicsOverride(override) {
   }
   return params;
 }
-function isRecord3(value) {
+function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function finite(value) {
@@ -27035,7 +27197,7 @@ function spawnPlayerBody(id, config) {
   body.friction = PLAYER_FRICTION;
   body.restitution = PLAYER_RESTITUTION;
   body.mass = PLAYER_MASS;
-  const spawn = isRecord3(config?.initialPosition) ? config.initialPosition : null;
+  const spawn = isRecord4(config?.initialPosition) ? config.initialPosition : null;
   body.px = finite(spawn?.x) ?? 0;
   body.py = finite(spawn?.y) ?? 0;
   body.pz = finite(spawn?.z) ?? 0;
@@ -27054,12 +27216,12 @@ function projectEnvironment(raw) {
   return environment;
 }
 function copyEnvironmentFields(target, source) {
-  if (!isRecord3(target)) return;
+  if (!isRecord4(target)) return;
   for (const key of Object.keys(target)) {
     const value = source[key];
     if (value === void 0) continue;
     const current = target[key];
-    if (isRecord3(current) && isRecord3(value)) {
+    if (isRecord4(current) && isRecord4(value)) {
       copyEnvironmentFields(current, value);
       continue;
     }

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

@@ -131,6 +131,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.
  *
@@ -142,6 +146,11 @@ interface Env {
     readonly CAJONZERO_KV: 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. */
@@ -533,6 +542,8 @@ interface MapEntry {
     readonly name?: string;
     readonly author?: string;
     readonly version?: string;
+    /** Optional content revision (e.g. `v1.0.4`); invalidates precomputed seeds. */
+    readonly etag?: string;
     /** Cover image URL for the lobby. */
     readonly cover?: string;
     /** Optional CDN root for browser assets; defaults to {@link root}. */
@@ -5032,6 +5043,8 @@ declare class Room {
     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 engine;
     private script;
     private readonly explicitScriptHost;
@@ -5094,6 +5107,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;

package/dist/scaffold.d.ts

@@ -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,54 @@ 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 `assets.directory` that holds `cj0 worker build-seed` packs.
+ * `worker prepare` preserves it when re-syncing the packaged UI.
+ */
+declare const ASSETS_SEED_DIR = "seed";
+/** Options for {@link prepareWorkerAssets}. */
+interface PrepareWorkerAssetsOptions {
+    /** 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 preparation. */
+interface PrepareWorkerAssetsResult {
+    /** 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;
+/**
+ * Materialise cajonzero's packaged UI into the project's static-assets
+ * directory. Idempotent: a matching fingerprint is a no-op.
+ *
+ * @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 prepareWorkerAssets(options?: PrepareWorkerAssetsOptions): Promise<PrepareWorkerAssetsResult>;
+
+export { ASSETS_SEED_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, prepareWorkerAssets, readCajonzeroPackage, readSetupValues, readWranglerAssetsDirectory, readWranglerKvNamespaceId, serializeDevVars, setWranglerKvNamespaceId, setWranglerVars, suggestedValue, toPackageName };
+export type { CajonzeroPackageInfo, CreateProjectOptions, PrepareWorkerAssetsOptions, PrepareWorkerAssetsResult, ScaffoldErrorCode, ScaffoldFile, ScaffoldResult, ScaffoldTemplateOptions, SetupField, SetupKind, SetupOptions, SetupResult };