@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/libraries/persistence/src/opfs-save-store.js

@@ -0,0 +1,584 @@
+// ============================================================================
+// OpfsSaveStore — OPFS-backed ISaveStore with generation history, blobs,
+// thumbnails, and properties. Runs in Web Workers (sync access handles) or
+// on the main thread (async writable streams).
+// ============================================================================
+//
+// Directory layout in OPFS:
+//   <root>/saves/
+//     <slot>/
+//       meta.json              — slot metadata (currentGen, generations[], properties)
+//       thumbnail.png          — optional thumbnail image
+//       gen/
+//         0001/
+//           body.zst           — zstd-compressed component JSON
+//           body.hash          — 16-byte XXH128 hash of uncompressed body
+//           blobs/
+//             <blobKey>        — raw binary blobs
+//         0002/
+//           ...
+//
+// On save: write body + blobs first, then update meta.json (commit point).
+// On load: read meta.json, load current gen (or specified), fall back to
+// previous gen on hash mismatch / corruption.
+//
+// Forward incompatibility: saves from a newer engine version are refused.
+import { safeJsonParse } from "@downdraft/engine";
+import { packEngineVersion } from "@downdraft/engine/save/binary-format";
+import { MigrationRegistryImpl } from "@downdraft/engine/save/migration-registry";
+import { createLogger } from "@downdraft/engine/util/logger";
+const log = createLogger("info");
+const DEFAULT_MAX_GENERATIONS = 3;
+const SAVES_DIR_NAME = "saves";
+const META_FILE = "meta.json";
+const THUMBNAIL_FILE = "thumbnail.png";
+const GEN_DIR = "gen";
+const BODY_FILE = "body.zst";
+const HASH_FILE = "body.hash";
+const BLOBS_DIR = "blobs";
+const META_FORMAT_VERSION = 1;
+// ── OpfsSaveStore ──────────────────────────────────────────────────────────
+export class OpfsSaveStore {
+    savesDir = null;
+    engineVersionPacked;
+    defaultMaxGenerations;
+    migrations;
+    warningCallbacks = [];
+    zstdReady = null;
+    _compress = null;
+    _decompress = null;
+    _hash128 = null;
+    _skipMigrations = false;
+    _rootDir;
+    _savesDirName;
+    constructor(opts) {
+        this._rootDir = opts.rootDir ?? null;
+        this._savesDirName = opts.savesDirName ?? SAVES_DIR_NAME;
+        const parts = opts.engineVersion.split(".").map(Number);
+        this.engineVersionPacked = packEngineVersion(parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0);
+        this.defaultMaxGenerations = opts.maxGenerations ?? DEFAULT_MAX_GENERATIONS;
+        this.migrations = opts.migrationRegistry ?? new MigrationRegistryImpl();
+        this._compress = opts.compress ?? null;
+        this._decompress = opts.decompress ?? null;
+        this._hash128 = opts.hash128 ?? null;
+        this._skipMigrations = opts.skipMigrations ?? false;
+    }
+    getMigrationRegistry() {
+        return this.migrations;
+    }
+    // ── Initialization ──────────────────────────────────────────────────────
+    /**
+     * Initialize the saves directory. Must be called before any save/load.
+     * If `rootDir` was provided in options, uses it; otherwise calls
+     * `navigator.storage.getDirectory()`.
+     */
+    async init() {
+        if (this.savesDir)
+            return;
+        let root = this._rootDir;
+        if (!root) {
+            const nav = globalThis;
+            if (!nav.navigator?.storage?.getDirectory) {
+                throw new Error("OPFS is not available in this environment");
+            }
+            root = await nav.navigator.storage.getDirectory();
+        }
+        // Create downdraft/ subdirectory, then saves/ under it
+        const ddDir = await root.getDirectoryHandle("downdraft", { create: true });
+        this.savesDir = await ddDir.getDirectoryHandle(this._savesDirName, { create: true });
+    }
+    /**
+     * Initialize from a pre-resolved saves directory handle (e.g. from a worker
+     * that already has the directory). Bypasses `navigator.storage.getDirectory()`.
+     */
+    initWithSavesDir(savesDir) {
+        this.savesDir = savesDir;
+    }
+    ensureInit() {
+        if (!this.savesDir) {
+            throw new Error("OpfsSaveStore not initialized — call init() first");
+        }
+        return this.savesDir;
+    }
+    // ── Warning system ──────────────────────────────────────────────────────
+    onWarning(cb) {
+        this.warningCallbacks.push(cb);
+        return () => {
+            const idx = this.warningCallbacks.indexOf(cb);
+            if (idx >= 0)
+                this.warningCallbacks.splice(idx, 1);
+        };
+    }
+    warn(warning) {
+        this.warningCallbacks.forEach((cb) => {
+            try {
+                cb(warning);
+            }
+            catch { /* ignore callback errors */ }
+        });
+    }
+    // ── Compression / hashing (lazy init, same as FileSaveStore) ────────────
+    async ensureZstd() {
+        if (this.zstdReady)
+            return this.zstdReady;
+        this.zstdReady = (async () => {
+            const { init } = await import("@bokuweb/zstd-wasm");
+            await init();
+        })();
+        // Don't cache a rejection forever — a transient failure (missing wasm
+        // asset, fs hiccup) would otherwise permanently break all saves.
+        this.zstdReady.catch(() => { this.zstdReady = null; });
+        return this.zstdReady;
+    }
+    async computeHash(data) {
+        // True XXH3-128 hash (16 bytes) — no longer padded h64.
+        const { xxh3_128 } = await import("./hash-utils.js");
+        return xxh3_128(data);
+    }
+    async compressBytes(data) {
+        await this.ensureZstd();
+        const { compress } = await import("@bokuweb/zstd-wasm");
+        return compress(data);
+    }
+    async decompressBytes(data, _originalSize) {
+        await this.ensureZstd();
+        const { decompress } = await import("@bokuweb/zstd-wasm");
+        return decompress(data);
+    }
+    // ── Path helpers ────────────────────────────────────────────────────────
+    sanitizeSlot(slot) {
+        return slot.replace(/[^a-zA-Z0-9_\-]/g, "_");
+    }
+    genDirName(gen) {
+        return String(gen).padStart(4, "0");
+    }
+    async getSlotDir(slot, create) {
+        const saves = this.ensureInit();
+        return saves.getDirectoryHandle(this.sanitizeSlot(slot), { create });
+    }
+    async getGenDir(slotDir, gen, create) {
+        const genRoot = await slotDir.getDirectoryHandle(GEN_DIR, { create });
+        return genRoot.getDirectoryHandle(this.genDirName(gen), { create });
+    }
+    async getBlobsDir(genDir, create) {
+        return genDir.getDirectoryHandle(BLOBS_DIR, { create });
+    }
+    // ── Meta file read/write ────────────────────────────────────────────────
+    async readMeta(slotDir) {
+        try {
+            const fileHandle = await slotDir.getFileHandle(META_FILE);
+            const file = await fileHandle.getFile();
+            const text = await file.text();
+            return safeJsonParse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    async writeMeta(slotDir, meta) {
+        const fileHandle = await slotDir.getFileHandle(META_FILE, { create: true });
+        const writable = await fileHandle.createWritable();
+        await writable.write(JSON.stringify(meta, null, 2));
+        await writable.close();
+    }
+    // ── File I/O helpers ────────────────────────────────────────────────────
+    async writeBinaryFile(dir, name, data) {
+        const fileHandle = await dir.getFileHandle(name, { create: true });
+        const writable = await fileHandle.createWritable();
+        await writable.write(data);
+        await writable.close();
+    }
+    async readBinaryFile(dir, name) {
+        try {
+            const fileHandle = await dir.getFileHandle(name);
+            const file = await fileHandle.getFile();
+            const buf = await file.arrayBuffer();
+            return new Uint8Array(buf);
+        }
+        catch {
+            return null;
+        }
+    }
+    async removeRecursive(dir, name) {
+        try {
+            await dir.removeEntry(name, { recursive: true });
+        }
+        catch {
+            // Already gone — fine
+        }
+    }
+    // ── ISaveStore: save ────────────────────────────────────────────────────
+    /** Serializes concurrent save() calls so they don't overlap.
+     *  Concurrent OPFS writes to the same files (body.zst, meta.json, blobs)
+     *  can corrupt save data or hang on file locks. The chain resolves even
+     *  when a save rejects so subsequent saves aren't permanently blocked. */
+    saveChain = Promise.resolve();
+    async save(slot, state, opts) {
+        const result = this.saveChain.then(() => this.doSave(slot, state, opts));
+        this.saveChain = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    async doSave(slot, state, opts) {
+        try {
+            this.ensureInit();
+            const slotDir = await this.getSlotDir(slot, true);
+            // Read existing meta or create new
+            const existingMeta = await this.readMeta(slotDir);
+            const maxGens = opts?.maxGenerations ?? existingMeta?.maxGenerations ?? this.defaultMaxGenerations;
+            const currentGen = (existingMeta?.currentGen ?? 0) + 1;
+            const genDir = await this.getGenDir(slotDir, currentGen, true);
+            // 1. Write body (compressed component JSON)
+            const bodyJson = JSON.stringify(state.components);
+            const bodyBytes = new TextEncoder().encode(bodyJson);
+            const hashBytes = this._hash128 ? this._hash128(bodyBytes) : await this.computeHash(bodyBytes);
+            const compressed = this._compress ? this._compress(bodyBytes) : await this.compressBytes(bodyBytes);
+            await this.writeBinaryFile(genDir, BODY_FILE, compressed);
+            await this.writeBinaryFile(genDir, HASH_FILE, hashBytes);
+            // 2. Write blobs
+            let blobCount = 0;
+            if (opts?.blobs && Object.keys(opts.blobs).length > 0) {
+                const blobsDir = await this.getBlobsDir(genDir, true);
+                for (const [key, buf] of Object.entries(opts.blobs)) {
+                    const safeKey = key.replace(/[^a-zA-Z0-9_\-]/g, "_");
+                    await this.writeBinaryFile(blobsDir, safeKey, new Uint8Array(buf));
+                    blobCount++;
+                }
+            }
+            // 3. Write thumbnail if provided
+            let hasThumbnail = existingMeta?.hasThumbnail ?? false;
+            if (opts?.thumbnail) {
+                const thumbData = opts.thumbnail instanceof Uint8Array ? opts.thumbnail : new Uint8Array(opts.thumbnail);
+                await this.writeBinaryFile(slotDir, THUMBNAIL_FILE, thumbData);
+                hasThumbnail = true;
+            }
+            // 4. Build new meta (commit point — written last)
+            const genMeta = {
+                gen: currentGen,
+                timestamp: state.meta.timestamp,
+                engineVersion: state.meta.engineVersion,
+                entityCount: state.meta.entityCount,
+                playerCount: state.meta.playerCount,
+                bodySize: compressed.length,
+                blobCount,
+            };
+            const generations = [...(existingMeta?.generations ?? []), genMeta];
+            // Prune old generations
+            while (generations.length > maxGens) {
+                const oldest = generations.shift();
+                await this.removeGenDir(slotDir, oldest.gen);
+            }
+            const properties = opts?.properties ?? existingMeta?.properties ?? {};
+            const newMeta = {
+                formatVersion: META_FORMAT_VERSION,
+                currentGen,
+                maxGenerations: maxGens,
+                generations,
+                properties,
+                hasThumbnail,
+            };
+            await this.writeMeta(slotDir, newMeta);
+            const totalBytes = compressed.length + hashBytes.length + (opts?.blobs ? Object.values(opts.blobs).reduce((s, b) => s + b.byteLength, 0) : 0);
+            return { success: true, bytes: totalBytes, gen: currentGen };
+        }
+        catch (err) {
+            log.error("opfs-save-store", `Save failed for slot '${slot}': ${err}`);
+            return { success: false, bytes: 0 };
+        }
+    }
+    async removeGenDir(slotDir, gen) {
+        try {
+            const genRoot = await slotDir.getDirectoryHandle(GEN_DIR);
+            await this.removeRecursive(genRoot, this.genDirName(gen));
+        }
+        catch {
+            // Already gone
+        }
+    }
+    // ── ISaveStore: load ────────────────────────────────────────────────────
+    async load(slot, opts) {
+        let slotDir;
+        try {
+            slotDir = await this.getSlotDir(slot, false);
+        }
+        catch (err) {
+            // Slot directory doesn't exist (first run / no save yet) — expected,
+            // not an error. Real OPFS throws a DOMException with name "NotFoundError";
+            // the mock OPFS throws a plain Error with "not found" in the message.
+            const name = err?.name;
+            const msg = err?.message ?? "";
+            const isNotFound = name === "NotFoundError" || name === "TypeMismatchError" ||
+                /not found/i.test(msg);
+            if (isNotFound) {
+                this.warn({ kind: "no_saves_found", slot, message: `No save slot '${slot}' found` });
+                return { state: null };
+            }
+            log.error("opfs-save-store", `Failed to access slot '${slot}': ${err}`);
+            return { state: null };
+        }
+        try {
+            const meta = await this.readMeta(slotDir);
+            if (!meta) {
+                this.warn({ kind: "no_saves_found", slot, message: `No save meta found for slot '${slot}'` });
+                return { state: null };
+            }
+            const targetGen = opts?.gen ?? meta.currentGen;
+            const includeBlobs = opts?.includeBlobs ?? true;
+            // Try target gen, then fall back to previous generations
+            const gensToTry = meta.generations
+                .filter(g => g.gen <= targetGen)
+                .sort((a, b) => b.gen - a.gen);
+            for (let _i = 0, _it = gensToTry, _n = _it.length; _i < _n; _i++) {
+                const genMeta = _it[_i];
+                const result = await this.loadFromGen(slotDir, slot, genMeta, includeBlobs);
+                if (result.state) {
+                    if (genMeta.gen !== targetGen) {
+                        this.warn({
+                            kind: "backup_loaded",
+                            slot,
+                            message: `Primary gen ${targetGen} failed, loaded gen ${genMeta.gen} for slot '${slot}'`,
+                        });
+                        return { ...result, gen: genMeta.gen };
+                    }
+                    return { ...result, gen: genMeta.gen };
+                }
+            }
+            this.warn({ kind: "no_saves_found", slot, message: `No valid save found for slot '${slot}'` });
+            return { state: null };
+        }
+        catch (err) {
+            log.error("opfs-save-store", `Load failed for slot '${slot}': ${err}`);
+            return { state: null };
+        }
+    }
+    async loadFromGen(slotDir, slot, genMeta, includeBlobs) {
+        try {
+            const genDir = await this.getGenDir(slotDir, genMeta.gen, false);
+            // Read and decompress body
+            const compressed = await this.readBinaryFile(genDir, BODY_FILE);
+            if (!compressed)
+                return { state: null };
+            const decompressed = this._decompress
+                ? this._decompress(compressed, 0)
+                : await this.decompressBytes(compressed, 0);
+            // Verify hash
+            const storedHash = await this.readBinaryFile(genDir, HASH_FILE);
+            if (storedHash) {
+                const computedHash = this._hash128 ? this._hash128(decompressed) : await this.computeHash(decompressed);
+                if (!this.hashEqual(computedHash, storedHash)) {
+                    this.warn({ kind: "corruption", slot, message: `Hash mismatch in gen ${genMeta.gen}` });
+                    return { state: null };
+                }
+            }
+            const bodyJson = new TextDecoder().decode(decompressed);
+            const components = safeJsonParse(bodyJson);
+            // Run migrations per component
+            const migrated = {};
+            for (const [name, section] of Object.entries(components)) {
+                if (this._skipMigrations) {
+                    migrated[name] = { v: section.v, data: section.data };
+                    continue;
+                }
+                const result = this.migrations.migrate(name, section.data, section.v);
+                if (result) {
+                    migrated[name] = { v: result.version, data: result.data };
+                }
+                else {
+                    this.warn({
+                        kind: "abandoned_data",
+                        slot,
+                        component: name,
+                        message: `Component '${name}' could not be migrated from v${section.v}`,
+                        abandonedData: section.data,
+                    });
+                }
+            }
+            // Read blobs if requested
+            let blobs;
+            if (includeBlobs) {
+                try {
+                    const blobsDir = await this.getBlobsDir(genDir, false);
+                    const entries = [];
+                    for await (const handle of blobsDir.values()) {
+                        if (handle.kind === "file") {
+                            const file = await handle.getFile();
+                            const buf = await file.arrayBuffer();
+                            entries.push([handle.name, buf]);
+                        }
+                    }
+                    if (entries.length > 0) {
+                        blobs = Object.fromEntries(entries);
+                    }
+                }
+                catch {
+                    // No blobs dir — fine
+                }
+            }
+            const state = {
+                components: migrated,
+                meta: {
+                    engineVersion: genMeta.engineVersion,
+                    timestamp: genMeta.timestamp,
+                    entityCount: genMeta.entityCount,
+                    playerCount: genMeta.playerCount,
+                },
+            };
+            return { state, blobs };
+        }
+        catch (err) {
+            log.warn("opfs-save-store", `loadFromGen ${genMeta.gen} failed: ${err}`);
+            return { state: null };
+        }
+    }
+    // ── ISaveStore: listSaves ───────────────────────────────────────────────
+    async listSaves() {
+        try {
+            const saves = this.ensureInit();
+            const slots = [];
+            for await (const handle of saves.values()) {
+                if (handle.kind !== "directory")
+                    continue;
+                const slotDir = handle;
+                const meta = await this.readMeta(slotDir);
+                if (!meta)
+                    continue;
+                const latest = meta.generations[meta.generations.length - 1] ?? meta.generations[0];
+                if (!latest)
+                    continue;
+                // Compute total file size across all generations
+                let totalSize = 0;
+                meta.generations.forEach((g) => {
+                    totalSize += g.bodySize;
+                });
+                slots.push({
+                    slot: handle.name,
+                    timestamp: latest.timestamp,
+                    entityCount: latest.entityCount,
+                    playerCount: latest.playerCount,
+                    engineVersion: latest.engineVersion,
+                    fileSize: totalSize,
+                    currentGen: meta.currentGen,
+                    generationCount: meta.generations.length,
+                    hasThumbnail: meta.hasThumbnail,
+                    properties: meta.properties,
+                });
+            }
+            slots.sort((a, b) => b.timestamp - a.timestamp);
+            return slots;
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── ISaveStore: listGenerations ─────────────────────────────────────────
+    async listGenerations(slot) {
+        try {
+            const slotDir = await this.getSlotDir(slot, false);
+            const meta = await this.readMeta(slotDir);
+            if (!meta)
+                return [];
+            return [...meta.generations].sort((a, b) => b.gen - a.gen);
+        }
+        catch {
+            return [];
+        }
+    }
+    // ── ISaveStore: deleteSave ──────────────────────────────────────────────
+    async deleteSave(slot) {
+        try {
+            const saves = this.ensureInit();
+            const safeSlot = this.sanitizeSlot(slot);
+            await this.removeRecursive(saves, safeSlot);
+            log.info("opfs-save-store", `Deleted slot '${slot}'`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── ISaveStore: deleteGeneration ────────────────────────────────────────
+    async deleteGeneration(slot, gen) {
+        try {
+            const slotDir = await this.getSlotDir(slot, false);
+            const meta = await this.readMeta(slotDir);
+            if (!meta)
+                return false;
+            // Remove gen directory
+            await this.removeGenDir(slotDir, gen);
+            // Update meta
+            meta.generations = meta.generations.filter(g => g.gen !== gen);
+            if (meta.currentGen === gen) {
+                meta.currentGen = meta.generations.length > 0
+                    ? Math.max(...meta.generations.map(g => g.gen))
+                    : 0;
+            }
+            await this.writeMeta(slotDir, meta);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── ISaveStore: thumbnail ───────────────────────────────────────────────
+    async setThumbnail(slot, data) {
+        const slotDir = await this.getSlotDir(slot, true);
+        const thumbData = data instanceof Uint8Array ? data : new Uint8Array(data);
+        await this.writeBinaryFile(slotDir, THUMBNAIL_FILE, thumbData);
+        // Update meta
+        const meta = await this.readMeta(slotDir);
+        if (meta) {
+            meta.hasThumbnail = true;
+            await this.writeMeta(slotDir, meta);
+        }
+    }
+    async getThumbnail(slot) {
+        try {
+            const slotDir = await this.getSlotDir(slot, false);
+            const data = await this.readBinaryFile(slotDir, THUMBNAIL_FILE);
+            return data ? data.buffer : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── ISaveStore: properties ──────────────────────────────────────────────
+    async setProperties(slot, props) {
+        const slotDir = await this.getSlotDir(slot, true);
+        const meta = await this.readMeta(slotDir);
+        if (meta) {
+            meta.properties = { ...meta.properties, ...props };
+            await this.writeMeta(slotDir, meta);
+        }
+        else {
+            // Create a minimal meta if none exists
+            const newMeta = {
+                formatVersion: META_FORMAT_VERSION,
+                currentGen: 0,
+                maxGenerations: this.defaultMaxGenerations,
+                generations: [],
+                properties: props,
+                hasThumbnail: false,
+            };
+            await this.writeMeta(slotDir, newMeta);
+        }
+    }
+    async getProperties(slot) {
+        try {
+            const slotDir = await this.getSlotDir(slot, false);
+            const meta = await this.readMeta(slotDir);
+            return meta?.properties ?? {};
+        }
+        catch {
+            return {};
+        }
+    }
+    // ── Utils ───────────────────────────────────────────────────────────────
+    hashEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    }
+}

package/dist/libraries/persistence/src/save-worker-proxy.js

@@ -0,0 +1,96 @@
+// ============================================================================
+// SaveWorkerProxy — ISaveStore implementation that delegates to a dedicated
+// save Web Worker via the engine's RPC layer.
+// ============================================================================
+//
+// The renderer creates this proxy when "worker" mode is selected. The proxy
+// spawns the save worker, calls init(), and forwards all ISaveStore methods
+// via postMessage (with ArrayBuffer transfer for zero-copy blob/thumbnail
+// transfer).
+import { wrap } from "@downdraft/engine/worker/rpc";
+export class SaveWorkerProxy {
+    opts;
+    wp = null;
+    warningCallbacks = [];
+    initialized = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /**
+     * Spawn the worker and initialize the OpfsSaveStore inside it.
+     * Must be called before any save/load operation.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        // NOTE: `new URL(...)` must be inlined directly inside `new Worker()` —
+        // Vite only bundles worker modules when it sees this exact pattern.
+        // Assigning the URL to a variable first causes Vite to emit the worker
+        // as a raw unbundled asset (bare imports unresolved), breaking prod.
+        const worker = this.opts.workerUrl
+            ? new Worker(this.opts.workerUrl, { type: "module" })
+            : new Worker(new URL("./save-worker.js", import.meta.url), { type: "module" });
+        this.wp = wrap(worker);
+        await this.wp.proxy.init(this.opts.storeOptions);
+        this.initialized = true;
+    }
+    ensureInit() {
+        if (!this.wp || !this.initialized) {
+            throw new Error("SaveWorkerProxy not initialized — call init() first");
+        }
+        return this.wp;
+    }
+    async save(slot, state, opts) {
+        return this.ensureInit().proxy.save(slot, state, opts);
+    }
+    async load(slot, opts) {
+        return this.ensureInit().proxy.load(slot, opts);
+    }
+    async listSaves() {
+        return this.ensureInit().proxy.listSaves();
+    }
+    async listGenerations(slot) {
+        return this.ensureInit().proxy.listGenerations(slot);
+    }
+    async deleteSave(slot) {
+        return this.ensureInit().proxy.deleteSave(slot);
+    }
+    async deleteGeneration(slot, gen) {
+        return this.ensureInit().proxy.deleteGeneration(slot, gen);
+    }
+    async setThumbnail(slot, data) {
+        return this.ensureInit().proxy.setThumbnail(slot, data);
+    }
+    async getThumbnail(slot) {
+        return this.ensureInit().proxy.getThumbnail(slot);
+    }
+    async setProperties(slot, props) {
+        return this.ensureInit().proxy.setProperties(slot, props);
+    }
+    async getProperties(slot) {
+        return this.ensureInit().proxy.getProperties(slot);
+    }
+    onWarning(cb) {
+        this.warningCallbacks.push(cb);
+        // Note: the worker forwards warnings via events; the proxy would need
+        // to subscribe to events and forward. For now, warnings are logged in
+        // the worker. A future improvement can wire up event forwarding.
+        return () => {
+            const idx = this.warningCallbacks.indexOf(cb);
+            if (idx >= 0)
+                this.warningCallbacks.splice(idx, 1);
+        };
+    }
+    /** Terminate the worker and clean up. */
+    async shutdown() {
+        if (this.wp) {
+            try {
+                await this.wp.proxy.shutdown();
+            }
+            catch { }
+            this.wp.terminate();
+            this.wp = null;
+        }
+        this.initialized = false;
+    }
+}