cajonzero 0.1.3 → 0.2.0

package/dist/maps.d.ts

@@ -0,0 +1,182 @@
+import { MapEntry, MapCatalog } from './core.js';
+
+interface BoxplayFile {
+    path: string;
+    data: Uint8Array;
+    size: number;
+}
+interface BoxplayBundleMember {
+    id: string;
+    permanentMapId?: string;
+    publicId?: string;
+    name?: string;
+    mapRole?: string;
+    mainProjectId?: string;
+}
+interface BoxplayBundle {
+    formatVersion: number;
+    type: string;
+    mapGroupId: string;
+    permanentMapGroupId?: string;
+    mainProjectId?: string;
+    version: string;
+    createdAt?: string;
+    members: BoxplayBundleMember[];
+    [key: string]: unknown;
+}
+interface BoxplayWorld {
+    worldId: string;
+    manifest: Record<string, unknown>;
+    dataFiles: string[];
+}
+interface BoxplayArchive {
+    bundle: BoxplayBundle;
+    worlds: BoxplayWorld[];
+    files: BoxplayFile[];
+    expandedBytes: number;
+}
+
+/**
+ * cajonzero — precomputed world-seed packs.
+ *
+ * Resolving a map graph over HTTP takes one request per blob (a real map can be
+ * 100+ requests and a large amount of parsing). That is fine on a Node machine
+ * but expensive against Worker quotas, so `cj0 add` / `cj0 update` resolve the
+ * graph once on the operator's machine and write a single `seed.json[.gz]`
+ * next to the map root.
+ *
+ * The room then performs **one** fetch, `JSON.parse`s the seed, and decodes the
+ * embedded block palette — no graph traversal, no per-blob requests.
+ *
+ * Format (JSON):
+ *
+ *   {
+ *     "format": "cajonzero-seed",
+ *     "version": 1,
+ *     "mapId": "worlds/<id> directory name",
+ *     "seed": { ...WorldSeed, "voxels": { ..., "chunkBlobs": ["<base64>"] } },
+ *     "blockInfo": "<base64 raw BlockInfo blob>"   // optional
+ *   }
+ *
+ * `blockInfo` is the *raw* palette blob (not the decoded schema object, which
+ * is not JSON-safe); the loader decodes it with the same schema the graph path
+ * uses. Binary fields are base64 (`atob`/`btoa`, available in workerd and Node).
+ *
+ * Worker-safe: no Node globals.
+ */
+
+/** Marker for the private (server-only) scripts pack. */
+declare const SCRIPT_PACK_FORMAT = "cajonzero-scripts";
+
+/** Default catalog path, relative to the project root. */
+declare const DEFAULT_MAPS_FILE = "cajonzero/maps.json";
+/** Default static-asset directory, relative to the project root. */
+declare const DEFAULT_PUBLIC_DIR = "public";
+/** Default private script-pack directory, relative to the project root. */
+declare const DEFAULT_SCRIPTS_DIR: string;
+/** Stable error codes so callers never string-match messages. */
+type MapImportErrorCode = "ARCHIVE_NOT_FOUND" | "MAP_NOT_FOUND" | "SLUG_EXISTS" | "INVALID_SLUG" | "INVALID_ARCHIVE" | "INVALID_CATALOG" | "INVALID_ROOT";
+/** Typed failure thrown by the map-import helpers. */
+declare class MapImportError extends Error {
+    readonly code: MapImportErrorCode;
+    constructor(code: MapImportErrorCode, message: string);
+}
+/** Options shared by {@link addMap} and {@link updateMap}. */
+interface MapImportOptions {
+    /** Project directory (default: `process.cwd()`). */
+    readonly cwd?: string;
+    /** Catalog path, relative to `cwd` (default `cajonzero/maps.json`). */
+    readonly maps?: string;
+    /** Static-asset directory, relative to `cwd` (default `public`). */
+    readonly publicDir?: string;
+    /** Private script-pack directory, relative to `cwd`. */
+    readonly scriptsDir?: string;
+    /** Override the derived slug (`add` only; `update` uses its argument). */
+    readonly slug?: string;
+    /** Write gzip packs (default `true`; `false` writes plain JSON). */
+    readonly gzip?: boolean;
+    /**
+     * `update` only: reset a manually changed `root`/`assetRoot` back to
+     * `/maps/<slug>/`. Ignored by `add`.
+     */
+    readonly resetRoot?: boolean;
+}
+/** One imported map, as returned to the CLI. */
+interface MapImportResult {
+    readonly action: "add" | "update";
+    readonly slug: string;
+    readonly root: string;
+    readonly worldId: string;
+    readonly mapId: string;
+    readonly name?: string;
+    readonly version?: string;
+    /** Absolute path of the written map directory. */
+    readonly publicDir: string;
+    /** Absolute path of the public seed pack. */
+    readonly seedPack: string;
+    /** Absolute path of the private script pack (`undefined` when no scripts). */
+    readonly scriptsPack?: string;
+    /** Project-relative private script file recorded in `maps.json`. */
+    readonly scriptsFile?: string;
+    /** Public files written, including the seed pack. */
+    readonly files: number;
+    /** Public bytes written, including the seed pack. */
+    readonly bytes: number;
+    readonly seedPackBytes: number;
+    readonly scriptModules: number;
+    readonly warnings: readonly string[];
+}
+/** One catalog row for `cj0 list`. */
+interface MapListEntry {
+    readonly slug: string;
+    readonly root: string;
+    readonly worldId?: string;
+    readonly name?: string;
+    readonly version?: string;
+    /** `true` when `public/maps/<slug>/` exists locally. */
+    readonly imported: boolean;
+    /** `true` when the public seed pack is present. */
+    readonly seeded: boolean;
+    /** `true` when a private script pack exists. */
+    readonly hasScripts: boolean;
+}
+/** Result of {@link removeMap}. */
+interface MapRemoveResult {
+    readonly slug: string;
+    readonly removedDir?: string;
+    readonly removedScripts: readonly string[];
+}
+/** Read a catalog file (BOM-tolerant) or the empty catalog when absent. */
+declare function readMapCatalogFile(mapsPath: string): MapCatalog;
+/** Derive a catalog slug from the archive's own metadata. */
+declare function deriveMapSlug(archive: BoxplayArchive, override?: string): string;
+/** Lowercase + sanitize arbitrary archive metadata into the slug grammar. */
+declare function toMapSlug(raw: string): string;
+/** Public directory for a slug. */
+declare function mapPublicDir(publicDir: string, slug: string): string;
+/** Seed pack file name for the configured compression. */
+declare function seedPackName(gzip: boolean): string;
+/** Private script pack path (with extension) for the configured compression. */
+declare function scriptsPackPath(scriptsDir: string, slug: string, gzip: boolean): string;
+/** Resolve a catalog entry's private script pack file. */
+declare function mapScriptsFile(entry: MapEntry, options?: MapImportOptions): string;
+/** All catalog entries that have a local private script pack. */
+declare function listScriptPackLocations(options?: MapImportOptions): {
+    slug: string;
+    file: string;
+}[];
+/** Import a new map (`cj0 add`). Fails when the slug already exists. */
+declare function addMap(archivePath: string, options?: MapImportOptions): Promise<MapImportResult>;
+/** Replace an existing map (`cj0 update`). */
+declare function updateMap(slug: string, archivePath: string, options?: MapImportOptions): Promise<MapImportResult>;
+/** List catalog entries and their local import state (`cj0 list`). */
+declare function listMaps(options?: MapImportOptions): MapListEntry[];
+/** Remove a map from `public/`, the private scripts dir and the catalog. */
+declare function removeMap(slug: string, options?: MapImportOptions): MapRemoveResult;
+/** Read a private script pack as JSON text (used by `cj0 deploy`). */
+declare function readScriptsPackText(file: string): string | undefined;
+/** All slugs with a local script pack. */
+declare function listScriptPacks(scriptsDir: string): string[];
+
+export { DEFAULT_MAPS_FILE, DEFAULT_PUBLIC_DIR, DEFAULT_SCRIPTS_DIR, MapImportError, SCRIPT_PACK_FORMAT, addMap, deriveMapSlug, listMaps, listScriptPackLocations, listScriptPacks, mapPublicDir, mapScriptsFile, readMapCatalogFile, readScriptsPackText, removeMap, scriptsPackPath, seedPackName, toMapSlug, updateMap };
+export type { MapImportErrorCode, MapImportOptions, MapImportResult, MapListEntry, MapRemoveResult };