@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/safety/json.js

@@ -0,0 +1,70 @@
+/**
+ * Keys that are blocked to prevent prototype pollution.
+ */
+const BLOCKED_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+/**
+ * Recursively sanitizes a parsed JSON object:
+ * - Resets any prototype that was set via `__proto__` pollution
+ * - Removes own properties named `__proto__`, `constructor`, `prototype`
+ * - Recurses into nested objects and arrays
+ */
+function deepSanitize(obj) {
+    if (typeof obj !== "object" || obj === null)
+        return obj;
+    if (Array.isArray(obj)) {
+        const arr = obj;
+        for (let i = 0; i < arr.length; i++) {
+            arr[i] = deepSanitize(arr[i]);
+        }
+        return obj;
+    }
+    // Reset prototype in case __proto__ pollution occurred during JSON.parse
+    const proto = Object.getPrototypeOf(obj);
+    if (proto !== null && proto !== Object.prototype) {
+        Object.setPrototypeOf(obj, Object.prototype);
+    }
+    const record = obj;
+    // Check for own properties named with blocked keys (including non-enumerable)
+    for (const key of Object.getOwnPropertyNames(record)) {
+        if (BLOCKED_KEYS.has(key)) {
+            delete record[key];
+        }
+    }
+    // Recurse into remaining enumerable keys
+    for (const key of Object.keys(record)) {
+        record[key] = deepSanitize(record[key]);
+    }
+    return obj;
+}
+/**
+ * Parses JSON safely, preventing prototype pollution (`__proto__`,
+ * `constructor`, `prototype` keys are stripped).
+ *
+ * Throws on invalid JSON (same as `JSON.parse`).
+ */
+export function safeJsonParse(text) {
+    const parsed = JSON.parse(text);
+    return deepSanitize(parsed);
+}
+/**
+ * Parses JSON safely and validates the result with a type guard.
+ * Returns `null` if parsing fails or validation rejects the result.
+ */
+export function safeJsonParseWithSchema(text, validate) {
+    try {
+        const parsed = safeJsonParse(text);
+        if (validate(parsed))
+            return parsed;
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Recursively removes prototype-polluting keys from an already-parsed object.
+ * Useful for sanitizing objects received from untrusted sources.
+ */
+export function sanitizeObject(obj) {
+    return deepSanitize(obj);
+}

package/dist/core/src/safety/path.js

@@ -0,0 +1,151 @@
+/**
+ * Path validation utilities — browser-safe (no `node:path` dependency).
+ *
+ * These functions work with POSIX-style paths (`/` separator) which is
+ * sufficient for URI validation and path traversal prevention in both
+ * browser and Node.js contexts.
+ */
+/** Returns true if the path starts with `/` (POSIX absolute) or a Windows drive letter. */
+function isAbsolutePath(p) {
+    if (p.startsWith("/"))
+        return true;
+    // Windows drive: C:\ or C:/
+    return /^[A-Za-z]:[\\/]/.test(p);
+}
+/**
+ * Normalizes a path by resolving `.` and `..` segments.
+ * Does NOT resolve symlinks or check filesystem existence.
+ * Works on POSIX-style paths (forward slashes).
+ */
+function normalizePath(p) {
+    const isAbs = isAbsolutePath(p);
+    const parts = p.replace(/\\/g, "/").split("/");
+    const result = [];
+    for (let _i = 0, _it = parts, _n = _it.length; _i < _n; _i++) {
+        const part = _it[_i];
+        if (part === "" || part === ".")
+            continue;
+        if (part === "..") {
+            if (result.length > 0 && result[result.length - 1] !== "..") {
+                result.pop();
+            }
+            else if (!isAbs) {
+                result.push("..");
+            }
+            // For absolute paths, .. at root stays at root (pop nothing)
+        }
+        else {
+            result.push(part);
+        }
+    }
+    let normalized = result.join("/");
+    if (isAbs)
+        normalized = "/" + normalized;
+    return normalized || (isAbs ? "/" : ".");
+}
+/**
+ * Joins `base` and `target` into a single normalized path.
+ * If `target` is absolute, `base` is ignored.
+ */
+function joinPath(base, target) {
+    if (isAbsolutePath(target))
+        return normalizePath(target);
+    const sep = base.endsWith("/") ? "" : "/";
+    return normalizePath(base + sep + target);
+}
+/**
+ * Computes the relative path from `from` to `to`.
+ * If `to` is not under `from`, the result starts with `..`.
+ */
+function relativePath(from, to) {
+    const fromNorm = normalizePath(from);
+    const toNorm = normalizePath(to);
+    const fromParts = fromNorm.split("/").filter(Boolean);
+    const toParts = toNorm.split("/").filter(Boolean);
+    // Find common prefix
+    let commonLen = 0;
+    while (commonLen < fromParts.length &&
+        commonLen < toParts.length &&
+        fromParts[commonLen] === toParts[commonLen]) {
+        commonLen++;
+    }
+    const upCount = fromParts.length - commonLen;
+    const downParts = toParts.slice(commonLen);
+    const result = [
+        ...Array(upCount).fill(".."),
+        ...downParts,
+    ];
+    if (result.length === 0)
+        return ".";
+    return result.join("/");
+}
+/**
+ * Resolves `targetPath` relative to `baseDir` and ensures the result does not
+ * escape `baseDir` via `..` segments or absolute paths.
+ *
+ * Throws if the resolved path would be outside `baseDir`.
+ * Returns the resolved absolute path on success.
+ */
+export function confinePath(baseDir, targetPath) {
+    const base = normalizePath(baseDir);
+    let target;
+    if (isAbsolutePath(targetPath)) {
+        target = normalizePath(targetPath);
+    }
+    else {
+        target = joinPath(base, targetPath);
+    }
+    const rel = relativePath(base, target);
+    // If the relative path starts with `..` or is an absolute path (different drive on Windows),
+    // the target escapes the base directory.
+    if (rel.startsWith("..") || isAbsolutePath(rel)) {
+        throw new Error(`Path "${targetPath}" escapes base directory "${baseDir}"`);
+    }
+    return target;
+}
+/**
+ * Boolean variant of {@link confinePath}. Returns `true` if `targetPath` is
+ * confined within `baseDir`, `false` otherwise.
+ */
+export function isPathSafe(baseDir, targetPath) {
+    try {
+        confinePath(baseDir, targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates a URI string (e.g. from glTF texture references). Only allows:
+ * - Relative paths without `..` segments
+ * - `data:` URIs
+ *
+ * Rejects: absolute paths, `file://`, `..` traversal, `http://`/`https://` to
+ * arbitrary hosts (unless `allowRemote` is true).
+ */
+export function sanitizeUri(uri, opts = {}) {
+    if (uri.startsWith("data:"))
+        return uri;
+    if (uri.startsWith("file://")) {
+        throw new Error(`file:// URIs are not allowed: "${uri}"`);
+    }
+    if (uri.startsWith("http://") || uri.startsWith("https://")) {
+        if (!opts.allowRemote) {
+            throw new Error(`Remote URIs are not allowed: "${uri}"`);
+        }
+        return uri;
+    }
+    // Relative path — reject `..` segments
+    if (uri.includes("..")) {
+        throw new Error(`Path traversal detected in URI: "${uri}"`);
+    }
+    if (isAbsolutePath(uri)) {
+        throw new Error(`Absolute paths are not allowed: "${uri}"`);
+    }
+    // If baseDir provided, verify confinement
+    if (opts.baseDir) {
+        return confinePath(opts.baseDir, uri);
+    }
+    return uri;
+}

package/dist/core/src/save/binary-format.js

@@ -0,0 +1,95 @@
+// ============================================================================
+// Binary Save Format — uncompressed header + zstd-compressed body
+// ============================================================================
+//
+// Header layout (46 bytes, little-endian):
+//   Offset  Size  Field
+//   0       4     Magic: 0xDD5A0001
+//   4       2     Format version (header structure version)
+//   6       4     Engine version hash (packed semver: major<<22 | minor<<12 | patch)
+//   10      8     Timestamp (f64, Unix epoch seconds)
+//   18      4     Entity count
+//   22      4     Player count
+//   26      16    XXH128 hash of uncompressed body
+//   42      4     Uncompressed body length
+//   46      ...   Zstd-compressed body (JSON)
+export const SAVE_MAGIC = 0xdd5a0001;
+export const SAVE_FORMAT_VERSION = 1;
+export const HEADER_SIZE = 46;
+export const XXH128_SIZE = 16;
+// --- Engine version packing ---
+export function packEngineVersion(major, minor, patch) {
+    return ((major & 0x3ff) << 22) | ((minor & 0x3ff) << 12) | (patch & 0xfff);
+}
+export function unpackEngineVersion(packed) {
+    return {
+        major: (packed >>> 22) & 0x3ff,
+        minor: (packed >>> 12) & 0x3ff,
+        patch: packed & 0xfff,
+    };
+}
+export function engineVersionString(packed) {
+    const v = unpackEngineVersion(packed);
+    return `${v.major}.${v.minor}.${v.patch}`;
+}
+export function encodeHeader(header) {
+    const buf = new ArrayBuffer(HEADER_SIZE);
+    const view = new DataView(buf);
+    const u8 = new Uint8Array(buf);
+    view.setUint32(0, header.magic, true);
+    view.setUint16(4, header.formatVersion, true);
+    view.setUint32(6, header.engineVersionPacked, true);
+    view.setFloat64(10, header.timestamp, true);
+    view.setUint32(18, header.entityCount, true);
+    view.setUint32(22, header.playerCount, true);
+    // XXH128 hash (16 bytes at offset 26)
+    u8.set(header.bodyHash.subarray(0, XXH128_SIZE), 26);
+    view.setUint32(42, header.uncompressedBodyLength, true);
+    return buf;
+}
+export function decodeHeader(buf) {
+    if (buf.byteLength < HEADER_SIZE)
+        return null;
+    const view = new DataView(buf);
+    const magic = view.getUint32(0, true);
+    if (magic !== SAVE_MAGIC)
+        return null;
+    const formatVersion = view.getUint16(4, true);
+    if (formatVersion !== SAVE_FORMAT_VERSION)
+        return null;
+    if (6 + 4 > buf.byteLength)
+        return null;
+    const engineVersionPacked = view.getUint32(6, true);
+    if (10 + 8 > buf.byteLength)
+        return null;
+    const timestamp = view.getFloat64(10, true);
+    if (18 + 4 > buf.byteLength)
+        return null;
+    const entityCount = view.getUint32(18, true);
+    if (22 + 4 > buf.byteLength)
+        return null;
+    const playerCount = view.getUint32(22, true);
+    const u8 = new Uint8Array(buf);
+    if (26 + XXH128_SIZE > buf.byteLength)
+        return null;
+    const bodyHash = u8.slice(26, 26 + XXH128_SIZE);
+    if (42 + 4 > buf.byteLength)
+        return null;
+    const uncompressedBodyLength = view.getUint32(42, true);
+    return {
+        magic,
+        formatVersion,
+        engineVersionPacked,
+        timestamp,
+        entityCount,
+        playerCount,
+        bodyHash,
+        uncompressedBodyLength,
+    };
+}
+// --- Read header only from a file buffer (for listSaves without decompression) ---
+export function readHeaderFromFile(fileBuffer) {
+    if (fileBuffer.byteLength < HEADER_SIZE)
+        return null;
+    return decodeHeader(fileBuffer.slice(0, HEADER_SIZE));
+}

package/dist/core/src/save/game-save-system.js

@@ -0,0 +1,101 @@
+// ============================================================================
+// createGameSaveSystem — batteries-included save lifecycle facade.
+//
+// createGridSaveSystem covers the store CRUD; games still hand-rolled the
+// same lifecycle on top in main.tsx:
+//   - module-scope `let autosaveInterval` + setInterval(autosave, 3000)
+//   - loadAutosave()-on-start → renderer.loadSave(...) with try/catch
+//   - cleanup in onDispose
+//   - save/load/delete/list wrappers that snapshot via the renderer
+//
+// This facade ties the grid system + autosave interval + snapshot/restore
+// contract into one object. Games keep their schema mapping (buildState /
+// buildBlobs / parseEntry) — everything else is engine-owned.
+//
+// Usage:
+//   const saves = createGameSaveSystem({
+//     createStore: () => createDefaultSaveStore(ENGINE_VERSION),
+//     autosaveSlot: "autosave",
+//     buildState, buildBlobs, parseEntry, extractListMeta,
+//     snapshot: () => renderer.snapshotGrids(),
+//     restore: (e) => renderer.loadSave(e.grids, e.fields, e.gridW, e.gridH),
+//     deterministic: ctx.deterministic,
+//   });
+//   // in onReady:
+//   await saves.start();      // restores autosave, starts the interval
+//   // on hot-reload:
+//   saves.stop();
+// ============================================================================
+import { createLogger } from "../util/logger.js";
+import { createGridSaveSystem } from "./grid-save-system.js";
+const log = createLogger();
+export function createGameSaveSystem(opts) {
+    const system = createGridSaveSystem(opts);
+    const intervalMs = opts.intervalMs ?? 3000;
+    const onError = opts.onError ?? ((e) => log.warn("save", `autosave failed: ${e}`));
+    let interval = null;
+    const maybeEnrich = async (id, entry) => {
+        if (entry === null || !opts.enrichEntry)
+            return entry;
+        const store = await system.getStore();
+        const [thumbBuf, props] = await Promise.all([
+            store.getThumbnail(id),
+            store.getProperties(id),
+        ]);
+        const meta = {
+            id,
+            props,
+            thumbnail: thumbBuf ? new Blob([thumbBuf], { type: "image/jpeg" }) : null,
+        };
+        return (await opts.enrichEntry(entry, meta)) ?? entry;
+    };
+    const tick = async () => {
+        try {
+            const meta = await opts.snapshot?.();
+            if (meta !== null && meta !== undefined)
+                await system.autosave(meta);
+        }
+        catch (e) {
+            onError(e);
+        }
+    };
+    return {
+        ...system,
+        async start() {
+            let restored = null;
+            if (!opts.deterministic) {
+                try {
+                    restored = await system.loadAutosave();
+                    if (restored !== null)
+                        await opts.restore?.(restored);
+                }
+                catch (e) {
+                    // No autosave / corrupt autosave is normal on first run.
+                    onError(e);
+                }
+                if (opts.snapshot && !interval) {
+                    interval = setInterval(() => { void tick(); }, intervalMs);
+                }
+            }
+            return restored;
+        },
+        stop() {
+            if (interval) {
+                clearInterval(interval);
+                interval = null;
+            }
+        },
+        get running() {
+            return interval !== null;
+        },
+        async loadGame(id) {
+            return maybeEnrich(id, await system.loadGame(id));
+        },
+        async loadAndRestore(id) {
+            const entry = await maybeEnrich(id, await system.loadGame(id));
+            if (entry !== null)
+                await opts.restore?.(entry);
+            return entry;
+        },
+    };
+}

package/dist/core/src/save/grid-save-system.js

@@ -0,0 +1,102 @@
+// ============================================================================
+// createGridSaveSystem — generic save-system factory for grid-based games.
+//
+// Eliminates the duplicated getStore() singleton + save/load/list/delete/
+// autosave/loadAutosave boilerplate that was copy-pasted across grid-based games.
+//
+// The factory owns:
+//   - Lazy ISaveStore singleton (via the game-provided createStore function)
+//   - saveGame: named slot + thumbnail + properties
+//   - loadGame: parse state + blobs into game-specific entry
+//   - listSaves: list all slots except autosave, with thumbnails
+//   - deleteSave: delete a named slot
+//   - autosave: save to the autosave slot
+//   - loadAutosave: load from the autosave slot
+//
+// Games provide:
+//   - createStore: () => Promise<ISaveStore> (typically createDefaultSaveStore)
+//   - autosaveSlot: string ("autosave", "world", etc.)
+//   - buildState: (meta) => SaveState
+//   - buildBlobs: (meta) => Record<string, ArrayBuffer>
+//   - parseEntry: (state, blobs) => Entry | null
+//   - extractListMeta?: (state) => Record<string, unknown> (for listSaves extra fields)
+// ============================================================================
+export function createGridSaveSystem(opts) {
+    let storePromise = null;
+    function getStore() {
+        if (!storePromise) {
+            storePromise = opts.createStore();
+        }
+        return storePromise;
+    }
+    return {
+        async saveGame(name, thumbnail, meta) {
+            const store = await getStore();
+            const id = `save-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+            const state = opts.buildState(meta);
+            await store.save(id, state, {
+                thumbnail: thumbnail ? new Uint8Array(thumbnail) : undefined,
+                properties: { name, savedAt: Date.now() },
+                blobs: opts.buildBlobs(meta),
+            });
+            return { id, timestamp: Date.now() };
+        },
+        async loadGame(id) {
+            const store = await getStore();
+            const result = await store.load(id);
+            if (!result.state)
+                return null;
+            return opts.parseEntry(result.state, result.blobs ?? null);
+        },
+        async listSaves() {
+            const store = await getStore();
+            const slots = await store.listSaves();
+            return Promise.all(slots
+                .filter((s) => s.slot !== opts.autosaveSlot)
+                .map(async (s) => {
+                const thumbBuf = await store.getThumbnail(s.slot);
+                const thumbnailUrl = thumbBuf
+                    ? URL.createObjectURL(new Blob([thumbBuf], { type: "image/jpeg" }))
+                    : "";
+                const props = await store.getProperties(s.slot);
+                const base = {
+                    id: s.slot,
+                    name: props.name ?? "Save",
+                    timestamp: props.savedAt ?? s.timestamp * 1000,
+                    thumbnailUrl,
+                };
+                // Merge game-specific list metadata if the game provided the callback.
+                if (opts.extractListMeta) {
+                    // Load the state to extract list metadata (e.g. gridW, gridH).
+                    // This is a lightweight load — the state header is small.
+                    const result = await store.load(s.slot, { includeBlobs: false });
+                    if (result.state) {
+                        const extra = opts.extractListMeta(result.state);
+                        Object.assign(base, extra);
+                    }
+                }
+                return base;
+            }));
+        },
+        async deleteSave(id) {
+            const store = await getStore();
+            await store.deleteSave(id);
+        },
+        async autosave(meta) {
+            const store = await getStore();
+            const state = opts.buildState(meta);
+            await store.save(opts.autosaveSlot, state, {
+                properties: { name: "Autosave", savedAt: Date.now() },
+                blobs: opts.buildBlobs(meta),
+            });
+        },
+        async loadAutosave() {
+            const store = await getStore();
+            const result = await store.load(opts.autosaveSlot);
+            if (!result.state)
+                return null;
+            return opts.parseEntry(result.state, result.blobs ?? null);
+        },
+        getStore,
+    };
+}

package/dist/core/src/save/migrate.js

@@ -0,0 +1,35 @@
+import { SchemaRegistry } from "./schema.js";
+import { Serializer } from "./serializer.js";
+export class SaveSystem {
+    serializer;
+    schemaRegistry;
+    constructor() {
+        this.serializer = new Serializer();
+        this.schemaRegistry = new SchemaRegistry();
+    }
+    getSchemaRegistry() {
+        return this.schemaRegistry;
+    }
+    save(world, sceneName) {
+        return this.serializer.serialize(world, sceneName);
+    }
+    load(data, world) {
+        this.serializer.deserialize(data, world, this.schemaRegistry);
+    }
+    async saveToFile(world, sceneName, path) {
+        const data = this.save(world, sceneName);
+        const json = this.serializer.toJSON(data);
+        // Lazy node:fs import — this module is reachable from the browser-side
+        // barrel, so node builtins must not be evaluated at import time.
+        await (await import("node:fs")).promises.writeFile(path, json);
+        return json.length;
+    }
+    async loadFromFile(path, world) {
+        const json = await (await import("node:fs")).promises.readFile(path, "utf-8");
+        const data = this.serializer.fromJSON(json);
+        this.load(data, world);
+    }
+    registerMigration(fromVersion, fn) {
+        this.schemaRegistry.registerMigration(fromVersion, fn);
+    }
+}

package/dist/core/src/save/migration-registry.js

@@ -0,0 +1,66 @@
+// ============================================================================
+// Migration Registry — per-component schema versioning with chain walking
+// ============================================================================
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+export class MigrationRegistryImpl {
+    components = new Map();
+    setCurrentVersion(component, version) {
+        let entry = this.components.get(component);
+        if (!entry) {
+            entry = { currentVersion: version, migrations: new Map() };
+            this.components.set(component, entry);
+        }
+        else {
+            entry.currentVersion = version;
+        }
+    }
+    getLatestVersion(component) {
+        return this.components.get(component)?.currentVersion ?? 1;
+    }
+    register(component, migration) {
+        let entry = this.components.get(component);
+        if (!entry) {
+            entry = { currentVersion: migration.toVersion, migrations: new Map() };
+            this.components.set(component, entry);
+        }
+        if (migration.toVersion > entry.currentVersion) {
+            entry.currentVersion = migration.toVersion;
+        }
+        entry.migrations.set(migration.fromVersion, migration);
+    }
+    migrate(component, data, fromVersion) {
+        const entry = this.components.get(component);
+        if (!entry) {
+            if (fromVersion === 1)
+                return { data, version: 1 };
+            log.warn("migration-registry", `Unknown component "${component}" with version ${fromVersion}`);
+            return null;
+        }
+        if (fromVersion === entry.currentVersion) {
+            return { data, version: entry.currentVersion };
+        }
+        if (fromVersion > entry.currentVersion) {
+            log.warn("migration-registry", `Component "${component}" save version ${fromVersion} > current ${entry.currentVersion} — forward incompatible`);
+            return null;
+        }
+        let current = data;
+        let version = fromVersion;
+        while (version < entry.currentVersion) {
+            const step = entry.migrations.get(version);
+            if (!step) {
+                log.warn("migration-registry", `Missing migration for "${component}" v${version}→v${version + 1} — marking as abandoned`);
+                return null;
+            }
+            try {
+                current = step.migrate(current);
+                version = step.toVersion;
+            }
+            catch (e) {
+                log.warn("migration-registry", `Migration failed for "${component}" v${version}→v${step.toVersion}: ${e}`);
+                return null;
+            }
+        }
+        return { data: current, version: entry.currentVersion };
+    }
+}

package/dist/core/src/save/persist-types.js

@@ -0,0 +1,4 @@
+// ============================================================================
+// Persistence Types — interfaces for the versioned save/load system
+// ============================================================================
+export {};

package/dist/core/src/save/schema.js

@@ -0,0 +1,36 @@
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+export const CURRENT_SCHEMA_VERSION = 1;
+export class SchemaRegistry {
+    migrations = new Map();
+    currentVersion = CURRENT_SCHEMA_VERSION;
+    registerMigration(fromVersion, fn) {
+        this.migrations.set(fromVersion, fn);
+    }
+    getCurrentVersion() {
+        return this.currentVersion;
+    }
+    migrate(data, fromVersion, targetVersion = this.currentVersion) {
+        let current = data;
+        let version = fromVersion;
+        while (version < targetVersion) {
+            const fn = this.migrations.get(version);
+            if (!fn) {
+                version++;
+                continue;
+            }
+            try {
+                current = fn(current);
+            }
+            catch (e) {
+                log.warn("schema-registry", `Migration v${version}→v${version + 1} failed: ${e} — returning data at v${version}`);
+                return current;
+            }
+            version++;
+        }
+        return current;
+    }
+    hasMigration(fromVersion) {
+        return this.migrations.has(fromVersion);
+    }
+}