@immediately-run/sandpack-client 2.19.8

package/dist/types-BIIEoWr6.js

@@ -0,0 +1,534 @@
+'use strict';
+
+var utils = require('./utils-BiVyytui.js');
+var core = require('@zenfs/core');
+
+/**
+ * Path (within the SandpackFS) of the sidecar metadata file. Anything below
+ * `/.sandpack/` is treated as internal and excluded from {@link SandpackFS.list}.
+ */
+var META_PATH = "/.sandpack/meta.json";
+var META_DIR = "/.sandpack";
+var mountCounter = 0;
+var normalize = function (path) {
+    return path.startsWith("/") ? path : "/".concat(path);
+};
+/**
+ * A filesystem-shaped handle over the files Sandpack renders. It wraps a
+ * ZenFS @see FileSystem mounted at a unique path prefix so multiple
+ * `SandpackProvider` instances stay isolated.
+ *
+ * All reads / writes are async. Changes emit a single coalesced notification
+ * (watcher or explicit helper calls) so React can subscribe via
+ * `useSyncExternalStore`.
+ */
+var SandpackFS = /** @class */ (function () {
+    function SandpackFS(fsContext, remotePortFactory, 
+    // Invoked after a LOCAL editor write (writeFile) lands in the backing fs,
+    // with the normalized repo-relative path. The host uses it to record overlay
+    // provenance (COW_OVERLAY_PROVENANCE_SPEC §5 — the writer declares intent);
+    // iframe writes go through `remotePortFactory`/`handleRemoteChange` instead.
+    onWrite) {
+        this.fsContext = fsContext;
+        this.remotePortFactory = remotePortFactory;
+        this.onWrite = onWrite;
+        this.listeners = new Set();
+        this.metaCache = {};
+        this.sidecarEnvironment = undefined;
+        this.sidecarMode = undefined;
+        this.disposed = false;
+    }
+    /**
+     * Create the `MessagePort` shared with the child iframe, wiring the iframe's
+     * write notifications back into this instance. The host's factory forwards
+     * `onRemoteChange` to `exportZenFS`, which calls it whenever the iframe writes
+     * a file over the Port — surfaced here as an `external` change.
+     */
+    SandpackFS.prototype.connectRemote = function () {
+        var _this = this;
+        return this.remotePortFactory(function (path) { return _this.handleRemoteChange(path); });
+    };
+    /**
+     * Create a new filesystem backed by an InMemory store and seed it with the
+     * given files.
+     */
+    SandpackFS.fromFiles = function () {
+        return utils.__awaiter(this, arguments, void 0, function (files, options, remotePortFactory, onWrite) {
+            var id, prefix, backend, ctxt, instance;
+            if (files === void 0) { files = {}; }
+            if (options === void 0) { options = {}; }
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        id = ++mountCounter;
+                        prefix = "/__sandpack_".concat(id);
+                        return [4 /*yield*/, core.resolveMountConfig({ backend: core.InMemory })];
+                    case 1:
+                        backend = _a.sent();
+                        core.mount(prefix, backend);
+                        ctxt = core.bindContext({ root: prefix });
+                        instance = new SandpackFS(ctxt, remotePortFactory, onWrite);
+                        if (options.environment !== undefined) {
+                            instance.sidecarEnvironment = options.environment;
+                        }
+                        if (options.mode !== undefined) {
+                            instance.sidecarMode = options.mode;
+                        }
+                        return [4 /*yield*/, instance.writeInitial(files)];
+                    case 2:
+                        _a.sent();
+                        return [2 /*return*/, instance];
+                }
+            });
+        });
+    };
+    /**
+     * Adopt an existing ZenFS filesystem. The caller is responsible for its
+     * lifecycle - {@link dispose} will unmount but not destroy the underlying
+     * store.
+     */
+    SandpackFS.fromFileSystemContext = function (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    fsContext, remotePortFactory, onWrite) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var instance;
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        instance = new SandpackFS(fsContext, remotePortFactory, onWrite);
+                        return [4 /*yield*/, instance.ensureMetaDir()];
+                    case 1:
+                        _a.sent();
+                        return [4 /*yield*/, instance.refreshMetaCache()];
+                    case 2:
+                        _a.sent();
+                        return [2 /*return*/, instance];
+                }
+            });
+        });
+    };
+    // ------------------------------------------------------------------
+    // Core file ops
+    // ------------------------------------------------------------------
+    /**
+     * Return every visible file path (leading `/`). Metadata sidecar and
+     * everything under `/.sandpack/` is excluded.
+     */
+    SandpackFS.prototype.list = function () {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var paths;
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        paths = [];
+                        return [4 /*yield*/, this.walk("/", paths)];
+                    case 1:
+                        _a.sent();
+                        paths.sort();
+                        return [2 /*return*/, paths];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.readFile = function (path) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.fsContext.fs.promises.readFile(this.toAbs(path), "utf8")];
+                    case 1: return [2 /*return*/, (_a.sent())];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.writeFile = function (path, content) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var abs, normalized;
+            var _a;
+            return utils.__generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        abs = this.toAbs(path);
+                        return [4 /*yield*/, this.ensureParent(abs)];
+                    case 1:
+                        _b.sent();
+                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(abs, content)];
+                    case 2:
+                        _b.sent();
+                        normalized = normalize(path);
+                        this.notify({ path: normalized, external: false });
+                        // A local editor write — declare it to the host's provenance recorder.
+                        (_a = this.onWrite) === null || _a === void 0 ? void 0 : _a.call(this, normalized);
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.unlink = function (path) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var normalized;
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.fsContext.fs.promises.unlink(this.toAbs(path))];
+                    case 1:
+                        _a.sent();
+                        normalized = normalize(path);
+                        if (!(normalized in this.metaCache)) return [3 /*break*/, 3];
+                        delete this.metaCache[normalized];
+                        return [4 /*yield*/, this.persistMeta()];
+                    case 2:
+                        _a.sent();
+                        _a.label = 3;
+                    case 3:
+                        this.notify({ path: normalized, external: false });
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.exists = function (path) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            return utils.__generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 2, , 3]);
+                        return [4 /*yield*/, this.fsContext.fs.promises.stat(this.toAbs(path))];
+                    case 1:
+                        _b.sent();
+                        return [2 /*return*/, true];
+                    case 2:
+                        _b.sent();
+                        return [2 /*return*/, false];
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    // ------------------------------------------------------------------
+    // Metadata
+    // ------------------------------------------------------------------
+    SandpackFS.prototype.getAllMetadata = function () {
+        return utils.__assign({}, this.metaCache);
+    };
+    SandpackFS.prototype.getMetadata = function (path) {
+        var _a;
+        return utils.__assign({}, ((_a = this.metaCache[normalize(path)]) !== null && _a !== void 0 ? _a : {}));
+    };
+    SandpackFS.prototype.setMetadata = function (path, patch) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var key, next;
+            var _a;
+            return utils.__generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        key = normalize(path);
+                        next = utils.__assign(utils.__assign({}, ((_a = this.metaCache[key]) !== null && _a !== void 0 ? _a : {})), patch);
+                        Object.keys(next).forEach(function (k) {
+                            if (next[k] === undefined) {
+                                delete next[k];
+                            }
+                        });
+                        if (Object.keys(next).length === 0) {
+                            delete this.metaCache[key];
+                        }
+                        else {
+                            this.metaCache[key] = next;
+                        }
+                        return [4 /*yield*/, this.persistMeta()];
+                    case 1:
+                        _b.sent();
+                        this.notify({ path: key, external: false });
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.getEnvironment = function () {
+        return this.sidecarEnvironment;
+    };
+    SandpackFS.prototype.setEnvironment = function (environment) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.sidecarEnvironment = environment;
+                        return [4 /*yield*/, this.persistMeta()];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.getMode = function () {
+        return this.sidecarMode;
+    };
+    SandpackFS.prototype.setMode = function (mode) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0:
+                        this.sidecarMode = mode;
+                        return [4 /*yield*/, this.persistMeta()];
+                    case 1:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    // ------------------------------------------------------------------
+    // Change detection
+    // ------------------------------------------------------------------
+    /**
+     * Subscribe to any mutation. Each change carries its `path` and an `external`
+     * flag (`true` = written by the child iframe, `false` = a local edit). See
+     * {@link SandpackFSChange}.
+     */
+    SandpackFS.prototype.onChange = function (cb) {
+        var _this = this;
+        this.listeners.add(cb);
+        return function () {
+            _this.listeners.delete(cb);
+        };
+    };
+    /**
+     * Record a write made by the child iframe (relayed from the `attachFS`
+     * boundary in the host). Surfaces as an `external` change so the editor can
+     * reflect it — distinct from local edits, which never reach here.
+     */
+    SandpackFS.prototype.handleRemoteChange = function (path) {
+        if (this.disposed)
+            return;
+        this.notify({ path: normalize(path), external: true });
+    };
+    // ------------------------------------------------------------------
+    // Internals
+    // ------------------------------------------------------------------
+    SandpackFS.prototype.toAbs = function (path) {
+        return normalize(path);
+    };
+    SandpackFS.prototype.notify = function (change) {
+        this.listeners.forEach(function (listener) {
+            try {
+                listener(change);
+            }
+            catch (err) {
+                console.error("[sandpack-client]: SandpackFS listener threw", err);
+            }
+        });
+    };
+    SandpackFS.prototype.ensureMetaDir = function () {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            return utils.__generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 2, , 3]);
+                        return [4 /*yield*/, this.fsContext.fs.promises.mkdir(META_DIR, {
+                                recursive: true,
+                            })];
+                    case 1:
+                        _b.sent();
+                        return [3 /*break*/, 3];
+                    case 2:
+                        _b.sent();
+                        return [3 /*break*/, 3];
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.ensureParent = function (absPath) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var lastSlash, dir;
+            return utils.__generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        lastSlash = absPath.lastIndexOf("/");
+                        if (lastSlash <= 0)
+                            return [2 /*return*/];
+                        dir = absPath.slice(0, lastSlash);
+                        if (!dir || dir === "/")
+                            return [2 /*return*/];
+                        _b.label = 1;
+                    case 1:
+                        _b.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.fsContext.fs.promises.mkdir(dir, { recursive: true })];
+                    case 2:
+                        _b.sent();
+                        return [3 /*break*/, 4];
+                    case 3:
+                        _b.sent();
+                        return [3 /*break*/, 4];
+                    case 4: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.walk = function (relDir, out) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var absDir, entries, _i, entries_1, entry, relPath, absEntry, isDir, stat;
+            return utils.__generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0:
+                        absDir = this.toAbs(relDir);
+                        _c.label = 1;
+                    case 1:
+                        _c.trys.push([1, 3, , 4]);
+                        return [4 /*yield*/, this.fsContext.fs.promises.readdir(absDir)];
+                    case 2:
+                        entries = (_c.sent());
+                        return [3 /*break*/, 4];
+                    case 3:
+                        _c.sent();
+                        return [2 /*return*/];
+                    case 4:
+                        _i = 0, entries_1 = entries;
+                        _c.label = 5;
+                    case 5:
+                        if (!(_i < entries_1.length)) return [3 /*break*/, 13];
+                        entry = entries_1[_i];
+                        relPath = (relDir === "/" ? "" : relDir) + "/" + entry;
+                        if (relPath.startsWith(META_DIR))
+                            return [3 /*break*/, 12];
+                        absEntry = this.toAbs(relPath);
+                        isDir = false;
+                        _c.label = 6;
+                    case 6:
+                        _c.trys.push([6, 8, , 9]);
+                        return [4 /*yield*/, this.fsContext.fs.promises.stat(absEntry)];
+                    case 7:
+                        stat = _c.sent();
+                        isDir = stat.isDirectory();
+                        return [3 /*break*/, 9];
+                    case 8:
+                        _c.sent();
+                        return [3 /*break*/, 12];
+                    case 9:
+                        if (!isDir) return [3 /*break*/, 11];
+                        return [4 /*yield*/, this.walk(relPath, out)];
+                    case 10:
+                        _c.sent();
+                        return [3 /*break*/, 12];
+                    case 11:
+                        out.push(relPath);
+                        _c.label = 12;
+                    case 12:
+                        _i++;
+                        return [3 /*break*/, 5];
+                    case 13: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.writeInitial = function (files) {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var meta, _i, _a, _b, rawPath, entry, path, abs, fileMeta;
+            return utils.__generator(this, function (_c) {
+                switch (_c.label) {
+                    case 0: return [4 /*yield*/, this.ensureMetaDir()];
+                    case 1:
+                        _c.sent();
+                        meta = {};
+                        _i = 0, _a = Object.entries(files);
+                        _c.label = 2;
+                    case 2:
+                        if (!(_i < _a.length)) return [3 /*break*/, 6];
+                        _b = _a[_i], rawPath = _b[0], entry = _b[1];
+                        path = normalize(rawPath);
+                        abs = this.toAbs(path);
+                        return [4 /*yield*/, this.ensureParent(abs)];
+                    case 3:
+                        _c.sent();
+                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(abs, entry.code)];
+                    case 4:
+                        _c.sent();
+                        fileMeta = {};
+                        if (entry.hidden !== undefined)
+                            fileMeta.hidden = entry.hidden;
+                        if (entry.active !== undefined)
+                            fileMeta.active = entry.active;
+                        if (entry.readOnly !== undefined)
+                            fileMeta.readOnly = entry.readOnly;
+                        if (Object.keys(fileMeta).length > 0)
+                            meta[path] = fileMeta;
+                        _c.label = 5;
+                    case 5:
+                        _i++;
+                        return [3 /*break*/, 2];
+                    case 6:
+                        this.metaCache = meta;
+                        return [4 /*yield*/, this.persistMeta()];
+                    case 7:
+                        _c.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.persistMeta = function () {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var sidecar;
+            return utils.__generator(this, function (_a) {
+                switch (_a.label) {
+                    case 0: return [4 /*yield*/, this.ensureMetaDir()];
+                    case 1:
+                        _a.sent();
+                        sidecar = { files: this.metaCache };
+                        if (this.sidecarEnvironment !== undefined) {
+                            sidecar.environment = this.sidecarEnvironment;
+                        }
+                        if (this.sidecarMode !== undefined) {
+                            sidecar.mode = this.sidecarMode;
+                        }
+                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(this.toAbs(META_PATH), JSON.stringify(sidecar))];
+                    case 2:
+                        _a.sent();
+                        return [2 /*return*/];
+                }
+            });
+        });
+    };
+    SandpackFS.prototype.refreshMetaCache = function () {
+        return utils.__awaiter(this, void 0, void 0, function () {
+            var raw, parsed;
+            return utils.__generator(this, function (_b) {
+                switch (_b.label) {
+                    case 0:
+                        _b.trys.push([0, 2, , 3]);
+                        return [4 /*yield*/, this.fsContext.fs.promises.readFile(this.toAbs(META_PATH), "utf8")];
+                    case 1:
+                        raw = (_b.sent());
+                        parsed = JSON.parse(raw);
+                        if ("files" in parsed && typeof parsed.files === "object") {
+                            this.metaCache = parsed.files;
+                            this.sidecarEnvironment = parsed.environment;
+                            this.sidecarMode = parsed.mode;
+                        }
+                        else {
+                            // Legacy format: plain FileMetaMap
+                            this.metaCache = parsed;
+                        }
+                        return [3 /*break*/, 3];
+                    case 2:
+                        _b.sent();
+                        this.metaCache = {};
+                        return [3 /*break*/, 3];
+                    case 3: return [2 /*return*/];
+                }
+            });
+        });
+    };
+    return SandpackFS;
+}());
+
+exports.SandpackLogLevel = void 0;
+(function (SandpackLogLevel) {
+    SandpackLogLevel[SandpackLogLevel["None"] = 0] = "None";
+    SandpackLogLevel[SandpackLogLevel["Error"] = 10] = "Error";
+    SandpackLogLevel[SandpackLogLevel["Warning"] = 20] = "Warning";
+    SandpackLogLevel[SandpackLogLevel["Info"] = 30] = "Info";
+    SandpackLogLevel[SandpackLogLevel["Debug"] = 40] = "Debug";
+})(exports.SandpackLogLevel || (exports.SandpackLogLevel = {}));
+
+exports.META_PATH = META_PATH;
+exports.SandpackFS = SandpackFS;