@immediately-run/sandpack-client 2.21.1 → 2.22.1

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

@@ -1,6 +1,6 @@
 {
   "name": "sandpack-client",
-  "version": "2.21.1",
-  "srcHash": "89d50cca03a74c4165b1fc5bdb8b0056beb6c7922b7938dc996456632b144338",
-  "builtAt": "2026-08-16T19:29:38.984Z"
+  "version": "2.22.1",
+  "srcHash": "10bae547420c39b69868a88e4aa7810abbbd8490309a16a6154ca3fdc16e7b4f",
+  "builtAt": "2026-09-13T05:42:11.272Z"
 }

package/dist/clients/node/index.js

@@ -2,9 +2,9 @@
 
 var utils = require('../../utils-BiVyytui.js');
 var nodebox = require('@codesandbox/nodebox');
-require('../../types-KEkDKvIe.js');
+require('../../types-B3g_70H8.js');
 var base = require('../../base-DelKLlDk.js');
-var consoleHook = require('../../consoleHook-BRSVCdB0.js');
+var consoleHook = require('../../consoleHook-vrsBdedj.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-BgalzxpH.mjs';
+import '../../types-DRg992RB.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-BYuGaxe8.mjs';
+import { c as consoleHook, g as generateRandomId, E as EventEmitter, a as getMessageFromError, f as findStartScriptPackageJson } from '../../consoleHook-DT9Wd42J.mjs';
 import 'outvariant';
 import '@zenfs/core';
 import 'dequal';

package/dist/clients/runtime/gestureGate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * R3-367 — the getCodeSandboxURL gesture gate, extracted so it is testable
+ * without standing the whole runtime graph up (and so the fork's node-env
+ * suites can import it too).
+ */
+/**
+ * Whether a codesandbox.io export may run: the user has been ACTIVE on this
+ * page (sticky activation — the fs snapshot can outlive a transient window).
+ * False ⇒ app/script-initiated context ⇒ the export must refuse before
+ * reading the filesystem.
+ */
+export declare const codeSandboxExportAllowed: () => boolean;
+/**
+ * Make a gesture-gate refusal observable: a `sandpack-security-violation`
+ * CustomEvent the host (site-main) can listen for and journal into its
+ * security-events stream. Never throws — observability must not become a
+ * second failure mode on the refusal path.
+ */
+export declare const notifyCodeSandboxExportRefused: () => void;

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

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

package/dist/clients/runtime/index.d.ts

@@ -4,6 +4,7 @@ import { SandpackClient } from "../base";
 import Protocol from "./file-resolver-protocol";
 import { IFrameProtocol } from "./iframe-protocol";
 import { type SandpackRuntimeMessage } from "./types";
+export { codeSandboxExportAllowed, notifyCodeSandboxExportRefused, } from "./gestureGate";
 export declare class SandpackRuntime extends SandpackClient {
     fileResolverProtocol?: Protocol;
     immutableFetchProtocol?: Protocol;
@@ -17,8 +18,19 @@ export declare class SandpackRuntime extends SandpackClient {
     unsubscribeFsWatcher?: () => void;
     iframeProtocol: IFrameProtocol;
     fs: SandpackFS;
+    /** Set once the teardown below has run, so a rogue document posting in a loop
+     *  cannot re-run `destroy()` or re-fire the host callback. */
+    private refusedBoot;
     /** Parent-owned Babel transpiler worker, connected to the iframe by port. */
     private babelWorker;
+    /**
+     * Which `initialized` messages this client will honour (R3-353). Armed by
+     * {@link setLocationURLIntoIFrame} — i.e. by every navigation THIS CLIENT
+     * causes — and spent when a boot arrives. A boot the host did not cause finds
+     * nothing armed, which is the whole check. See `initialization-guard.ts` for
+     * why the parent asks "did I put you there?" rather than "where are you?".
+     */
+    private readonly initGuard;
     constructor(selector: string | HTMLIFrameElement, sandboxSetup: SandboxSetup, options?: ClientOptions);
     private createBundlerURL;
     /**
@@ -33,6 +45,16 @@ export declare class SandpackRuntime extends SandpackClient {
     private serviceWorkerHandshake;
     private handleWorkerRequest;
     setLocationURLIntoIFrame(): void;
+    /**
+     * Spend one armed `initialized`, or refuse this boot (R3-353).
+     *
+     * Refusing is terminal for this client: the frame is blanked so the rogue
+     * document — which still holds whatever it scraped before navigating — stops
+     * executing, the client detaches, and the host is told through
+     * `onUnexpectedNavigation` so it can surface or re-create the frame. Nothing is
+     * connected and nothing is registered, so no fs port is ever minted for it.
+     */
+    private consumeExpectedInitialization;
     destroy(): void;
     updateOptions(options: ClientOptions): void;
     /**
@@ -60,7 +82,17 @@ export declare class SandpackRuntime extends SandpackClient {
     dispatch(message: SandpackRuntimeMessage): void;
     listen(listener: ListenerFunction): UnsubscribeFunction;
     /**
-     * Get the URL of the contents of the current sandbox
+     * Get the URL of the contents of the current sandbox.
+     *
+     * R3-367 — GESTURE-GATED. This POSTs the ENTIRE app filesystem to
+     * codesandbox.io from the parent page; the fs may contain the user's data
+     * (spaces, mounts), so the export is reachable only when the user has been
+     * active on the page (`navigator.userActivation.hasBeenActive` — the sticky
+     * flag, because the fs snapshot can outlive a transient-activation window).
+     * Without any user activation this refuses BEFORE reading the filesystem:
+     * nothing is posted, and a `sandpack-security-violation` CustomEvent is
+     * dispatched on the window for the host to journal (site-main wires the
+     * listener into its security-events seam).
      */
     getCodeSandboxURL(): Promise<{
         sandboxId: string;

package/dist/clients/runtime/index.js

@@ -2,7 +2,7 @@
 
 var utils = require('../../utils-BiVyytui.js');
 var dequal = require('dequal');
-var types = require('../../types-KEkDKvIe.js');
+var types = require('../../types-B3g_70H8.js');
 var base = require('../../base-DelKLlDk.js');
 var iframeFactory = require('../../iframe-factory-Bc7tcyQZ.js');
 var mimeDB = require('mime-db');
@@ -66,6 +66,21 @@ var Protocol = /** @class */ (function () {
     return Protocol;
 }());
 
+// R3-367: crypto-random, 64-bit channel id (16 hex chars from 8 random bytes).
+// This used to be Math.floor(Math.random()*1e6) — guessable, and the id was
+// console.logged at registration. SECURITY INVARIANT (do not weaken): the id is
+// a CORRELATION key only — every incoming message is authenticated by the
+// `event.source === this.frameWindow` check in eventListener() below, NEVER by
+// the id alone. The crypto entropy is defense-in-depth on top of that check
+// (the frame-side twin comment lives in the sandbox bundler's protocol layer,
+// R3-352 C1). `string | number` on the wire stays compatible with ids older
+// peers minted as numbers: both sides compare the echoed value they themselves
+// sent, so the type never has to agree across versions.
+var randomChannelId = function () {
+    var bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, function (b) { return b.toString(16).padStart(2, "0"); }).join("");
+};
 var IFrameProtocol = /** @class */ (function () {
     function IFrameProtocol(iframe, _origin) {
         // React to messages from any iframe
@@ -74,8 +89,9 @@ var IFrameProtocol = /** @class */ (function () {
         // React to messages from the iframe owned by this instance
         this.channelListeners = {};
         this.channelListenersCount = 0;
-        // Random number to identify this instance of the client when messages are coming from multiple iframes
-        this.channelId = Math.floor(Math.random() * 1000000);
+        // Random id to identify this instance of the client when messages are coming
+        // from multiple iframes — crypto-random (see randomChannelId above).
+        this.channelId = randomChannelId();
         this.frameWindow = iframe.contentWindow;
         this.origin = "*"; //origin;
         this.globalListeners = [];
@@ -101,8 +117,9 @@ 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);
+        // R3-367: no channelId log — the id is not secret-critical, but logging it
+        // at registration handed an observer the correlation key for free (the
+        // evt.source check below is the actual authentication).
         // 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
         // is always present (it is, in normal operation).
@@ -153,7 +170,11 @@ var IFrameProtocol = /** @class */ (function () {
     };
     // Handles message windows coming from iframes
     IFrameProtocol.prototype.eventListener = function (evt) {
-        // skip events originating from different iframes
+        // SECURITY INVARIANT (R3-367, twin of the randomChannelId comment): this
+        // source check — not the channelId — is what authenticates an incoming
+        // message. The id below only routes a message ALREADY accepted here to the
+        // owning instance. Weakening or reordering this check would let any iframe
+        // on the page speak on the bundler channel.
         if (evt.source !== this.frameWindow) {
             return;
         }
@@ -190,24 +211,50 @@ var IFrameProtocol = /** @class */ (function () {
  * registers via `registerImmutableUrlPrefix` (see sandpack-bundler
  * `src/utils/fetch.ts`) — keep the two in sync.
  */
-/**
- * URL prefixes whose responses never change for a given URL (the URL encodes
- * the exact content version). Only these may be fetched on the iframe's
- * behalf, and they are safe to cache forever.
- */
 var IMMUTABLE_URL_ALLOWLIST = [
     // Module CDN, exact-versioned package bundles. (NOT /dep_tree/, which
     // resolves semver ranges and changes as new versions publish.)
-    "https://sandpack-cdn-staging.blazingly.io/package/",
+    {
+        origin: "https://sandpack-cdn-staging.blazingly.io",
+        pathPrefix: "/package/",
+    },
     // unpkg files, requested by the bundler at registry-resolved exact versions.
-    "https://unpkg.com/",
+    { origin: "https://unpkg.com", pathPrefix: "/" },
     // Self-hosted, versioned @immediately-run/sdk builds (SDK_PACKAGING_SPEC
     // §5/§11, Option A). The /v/<version>/ path encodes the exact version, so
     // responses are immutable; the bundler fetches these when an app opts the SDK
     // into immediately.run.resolveFromRegistry. Keep in sync with the prefix the
     // bundler registers via registerImmutableUrlPrefix (sandbox bundler.ts).
-    "https://immediately-run.github.io/immediately-run-sdk/v/",
+    {
+        origin: "https://immediately-run.github.io",
+        pathPrefix: "/immediately-run-sdk/v/",
+    },
 ];
+/**
+ * Is a PARSED URL inside the allowlist? Origin is compared exactly (a userinfo
+ * or lookalike host cannot match) and the path prefix against the URL parser's
+ * NORMALIZED pathname; additionally, any dot segment — literal or
+ * percent-encoded, in any hex case — is refused, so no spelling of `..` can
+ * cross the prefix boundary after a server-side decode.
+ */
+var inPolicy = function (u) {
+    var segments = u.pathname.split("/").map(function (segment) {
+        try {
+            return decodeURIComponent(segment).toLowerCase();
+        }
+        catch (_a) {
+            return segment.toLowerCase();
+        }
+    });
+    if (segments.some(function (s) { return s === ".." || s === "."; }))
+        return false;
+    if (/%2e/.test(u.pathname.toLowerCase()))
+        return false;
+    return IMMUTABLE_URL_ALLOWLIST.some(function (_a) {
+        var origin = _a.origin, pathPrefix = _a.pathPrefix;
+        return u.origin === origin && u.pathname.startsWith(pathPrefix);
+    });
+};
 var IMMUTABLE_CACHE_NAME = "sandpack-immutable-fetch-v1";
 var serializeResponse = function (res) { return utils.__awaiter(void 0, void 0, void 0, function () {
     var _a;
@@ -299,14 +346,22 @@ var matchesIntegrity = function (body, integrity) { return utils.__awaiter(void
  */
 function handleImmutableFetch(url, integrity) {
     return utils.__awaiter(this, void 0, void 0, function () {
-        var expected, cache, hit, body, res, result, _a;
+        var parsed, expected, cache, hit, body, res, result, _a;
         return utils.__generator(this, function (_b) {
             switch (_b.label) {
                 case 0:
-                    if (typeof url !== "string" ||
-                        !IMMUTABLE_URL_ALLOWLIST.some(function (prefix) { return url.startsWith(prefix); })) {
+                    if (typeof url !== "string") {
                         throw new Error("URL not allowed for immutable fetch: ".concat(String(url)));
                     }
+                    try {
+                        parsed = new URL(url);
+                    }
+                    catch (_c) {
+                        throw new Error("URL not allowed for immutable fetch: ".concat(url));
+                    }
+                    if (!inPolicy(parsed)) {
+                        throw new Error("URL not allowed for immutable fetch: ".concat(url));
+                    }
                     expected = typeof integrity === "string" ? integrity : undefined;
                     return [4 /*yield*/, openCache()];
                 case 1:
@@ -330,12 +385,21 @@ function handleImmutableFetch(url, integrity) {
                     // Stale/poisoned entry: drop it and fall through to a fresh fetch.
                     _b.sent();
                     _b.label = 6;
-                case 6: return [4 /*yield*/, fetch(url)];
+                case 6: return [4 /*yield*/, fetch(parsed)];
                 case 7:
                     res = _b.sent();
                     if (!res.ok) {
                         throw new Error("Immutable fetch failed with status ".concat(res.status, ": ").concat(url));
                     }
+                    // R3-364: the prefix hosts are exact-version content hosts; a redirect that
+                    // leaves the allowlist means the bytes did NOT come from an in-policy origin —
+                    // refuse rather than serve (and never cache) them. The browser follows
+                    // redirects itself (cross-origin `redirect: 'manual'` responses are opaque),
+                    // so this is the final-URL check: `res.url` is where the bytes actually came
+                    // from. A response that reports no URL (test doubles) skips the check.
+                    if (res.redirected && res.url !== "" && !inPolicy(new URL(res.url))) {
+                        throw new Error("Immutable fetch redirected outside the allowlist: ".concat(res.url));
+                    }
                     return [4 /*yield*/, serializeResponse(res)];
                 case 8:
                     result = _b.sent();
@@ -364,6 +428,99 @@ function handleImmutableFetch(url, integrity) {
     });
 }
 
+/**
+ * The re-register guard (R3-353; `TRUST_MODES_SPEC` §6, `UI_AS_APPS_SPEC` §G1a).
+ *
+ * ## What it defends
+ *
+ * A sandboxed frame may always navigate **itself** — no sandbox flag governs
+ * that, and `navigate-to` was dropped from CSP3, so neither half of the M3
+ * containment can prevent it. The finding that led here reads that as an egress
+ * problem (the M3 CSP travels with the birth document, so a frame that
+ * re-births itself at the policy-free baseline document gets unrestricted
+ * `connect-src` back). The bigger half is that **the host relationship travels
+ * with the document too, and the browsing context does not change**:
+ *
+ * - `iframe.contentWindow` returns the SAME `WindowProxy` across a navigation,
+ *   so `IFrameProtocol`'s `evt.source !== this.frameWindow` intake check — which
+ *   is correct, and is the only identity the parent has — still passes;
+ * - the client's `initialized` handler is a plain listener with no notion of how
+ *   many boots it has seen, so it re-runs `fs.connectRemote()` and `register(…)`;
+ * - whatever document is in the frame now — the baseline bundler document, or a
+ *   page on an origin the app chose — is therefore handed a **fresh fs port** and
+ *   a fresh registration, inheriting the frame's grants.
+ *
+ * So the escalation is not "a one-shot GET carrying a small secret" (the residual
+ * `TRUST_MODES_SPEC` §6 books); it is a persistent execution context, possibly at
+ * an attacker's own origin, still attached to the host with the victim frame's
+ * authority.
+ *
+ * ## Why it is shaped as a counter
+ *
+ * The parent cannot read a cross-origin frame's `location`, so it cannot ask
+ * *"where are you?"*. It can ask *"did I put you there?"* — the same question,
+ * and one it can answer without reading anything: every legitimate boot follows a
+ * navigation the CLIENT performed (its constructor, and its `refresh` dispatch,
+ * both through `setLocationURLIntoIFrame`). Arm on navigate, spend on boot; a
+ * boot with nothing armed was not ours.
+ *
+ * A counter rather than a boolean because a rapid navigate–navigate–boot–boot
+ * sequence is legitimate and must not eat its own credit. A latch rather than
+ * decrement-below-zero because a refusal is terminal: once a rogue document has
+ * been refused, nothing it posts may re-arm anything.
+ *
+ * Kept framework-free and separate from `SandpackRuntime` so the decision can be
+ * driven directly by tests — the client itself needs a real `SandpackFS`, a Babel
+ * worker and a live iframe to construct.
+ */
+var InitializationGuard = /** @class */ (function () {
+    function InitializationGuard() {
+        this.expected = 0;
+        this.detached = false;
+    }
+    /** Record that the host has navigated the frame, so ONE boot is now expected. */
+    InitializationGuard.prototype.arm = function () {
+        if (this.detached)
+            return;
+        this.expected++;
+    };
+    /**
+     * Spend one armed boot. Returns `false` when this boot was not caused by the
+     * host — the caller must then refuse to connect or register anything.
+     *
+     * The first `false` **detaches** the guard permanently: every later call
+     * returns `false` too, including after an `arm()`, so a refused frame cannot be
+     * brought back by any sequence of messages.
+     */
+    InitializationGuard.prototype.consume = function () {
+        if (this.detached)
+            return false;
+        if (this.expected > 0) {
+            this.expected--;
+            return true;
+        }
+        this.detached = true;
+        return false;
+    };
+    Object.defineProperty(InitializationGuard.prototype, "isDetached", {
+        /** True once an unexpected boot has been refused. Terminal. */
+        get: function () {
+            return this.detached;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(InitializationGuard.prototype, "pending", {
+        /** How many host-initiated boots are still outstanding (diagnostics/tests). */
+        get: function () {
+            return this.expected;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return InitializationGuard;
+}());
+
 var extensionMap = new Map();
 var entries = Object.entries(mimeDB);
 for (var _i = 0, entries_1 = entries; _i < entries_1.length; _i++) {
@@ -528,16 +685,62 @@ function getExtension(filepath) {
     }
 }
 
+/**
+ * R3-367 — the getCodeSandboxURL gesture gate, extracted so it is testable
+ * without standing the whole runtime graph up (and so the fork's node-env
+ * suites can import it too).
+ */
+/**
+ * Whether a codesandbox.io export may run: the user has been ACTIVE on this
+ * page (sticky activation — the fs snapshot can outlive a transient window).
+ * False ⇒ app/script-initiated context ⇒ the export must refuse before
+ * reading the filesystem.
+ */
+var codeSandboxExportAllowed$1 = function () {
+    var _a;
+    return ((_a = navigator.userActivation) === null || _a === void 0 ? void 0 : _a.hasBeenActive) === true;
+};
+/**
+ * Make a gesture-gate refusal observable: a `sandpack-security-violation`
+ * CustomEvent the host (site-main) can listen for and journal into its
+ * security-events stream. Never throws — observability must not become a
+ * second failure mode on the refusal path.
+ */
+var notifyCodeSandboxExportRefused$1 = function () {
+    try {
+        window.dispatchEvent(new CustomEvent("sandpack-security-violation", {
+            detail: {
+                kind: "gesture-gate.getCodeSandboxURL",
+                reason: "no user activation",
+            },
+        }));
+    }
+    catch (_a) {
+        /* no window / dispatch unavailable */
+    }
+};
+
 var _a;
 var SUFFIX_PLACEHOLDER = "-{{suffix}}";
-var BUNDLER_URL = "https://".concat((_a = "2.21.1") === null || _a === void 0 ? void 0 : _a.replace(/\./g, "-")).concat(SUFFIX_PLACEHOLDER, "-sandpack.codesandbox.io/");
+var BUNDLER_URL = "https://".concat((_a = "2.22.1") === 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) {
         if (options === void 0) { options = {}; }
         var _this = _super.call(this, selector, sandboxSetup, options) || this;
+        /** Set once the teardown below has run, so a rogue document posting in a loop
+         *  cannot re-run `destroy()` or re-fire the host callback. */
+        _this.refusedBoot = false;
         /** Parent-owned Babel transpiler worker, connected to the iframe by port. */
         _this.babelWorker = null;
+        /**
+         * Which `initialized` messages this client will honour (R3-353). Armed by
+         * {@link setLocationURLIntoIFrame} — i.e. by every navigation THIS CLIENT
+         * causes — and spent when a boot arrives. A boot the host did not cause finds
+         * nothing armed, which is the whole check. See `initialization-guard.ts` for
+         * why the parent asks "did I put you there?" rather than "where are you?".
+         */
+        _this.initGuard = new InitializationGuard();
         _this.getTranspilerContext = function () {
             return new Promise(function (resolve) {
                 var unsubscribe = _this.listen(function (message) {
@@ -592,6 +795,26 @@ var SandpackRuntime = /** @class */ (function (_super) {
             if (mes.type !== "initialized" || !_this.iframe.contentWindow) {
                 return;
             }
+            // R3-353 — the re-register guard. A sandboxed frame may always navigate
+            // ITSELF (no sandbox flag governs that), and after it does, the browsing
+            // context is the same one: `iframe.contentWindow` returns the same
+            // WindowProxy, so `IFrameProtocol`'s `evt.source !== this.frameWindow`
+            // check still passes. Whatever document is in the frame now — the
+            // policy-free baseline bundler document, or a page on an origin the app
+            // chose — can therefore post `initialized` and be handed a FRESH fs port
+            // and a fresh registration, inheriting this frame's grants.
+            //
+            // That is the escalation, and it is bigger than the CSP loss the finding
+            // leads with: the CSP travels with the document, but so does the host
+            // RELATIONSHIP, and the relationship is worth more.
+            //
+            // The host cannot read a cross-origin frame's location, so it cannot ask
+            // "where are you?". It can ask "did I put you there?" — which is the same
+            // question and one it can answer: every legitimate (re)boot follows a
+            // navigation THIS CLIENT performed (the constructor, and the `refresh`
+            // dispatch), both of which go through `setLocationURLIntoIFrame`.
+            if (!_this.consumeExpectedInitialization())
+                return;
             // this may not work with a boundedcontext, it may require an actual FS instance
             var remotePortPromise = _this.fs.connectRemote();
             remotePortPromise.then(function (remotePort) { return utils.__awaiter(_this, void 0, void 0, function () {
@@ -835,9 +1058,42 @@ var SandpackRuntime = /** @class */ (function (_super) {
         var urlSource = this.options.startRoute
             ? new URL(this.options.startRoute, this.bundlerURL).toString()
             : this.bundlerURL;
+        // Arm one expected `initialized` (R3-353): this navigation is host-initiated,
+        // so the boot that follows it is legitimate. Every legitimate (re)boot in the
+        // system passes through here — the constructor and the `refresh` dispatch —
+        // which is exactly what makes "nothing armed" mean "not ours".
+        this.initGuard.arm();
         (_a = this.iframe.contentWindow) === null || _a === void 0 ? void 0 : _a.location.replace(urlSource);
         this.iframe.src = urlSource;
     };
+    /**
+     * Spend one armed `initialized`, or refuse this boot (R3-353).
+     *
+     * Refusing is terminal for this client: the frame is blanked so the rogue
+     * document — which still holds whatever it scraped before navigating — stops
+     * executing, the client detaches, and the host is told through
+     * `onUnexpectedNavigation` so it can surface or re-create the frame. Nothing is
+     * connected and nothing is registered, so no fs port is ever minted for it.
+     */
+    SandpackRuntime.prototype.consumeExpectedInitialization = function () {
+        var _a, _b;
+        if (this.initGuard.consume())
+            return true;
+        if (this.refusedBoot)
+            return false; // already torn down; stay quiet
+        this.refusedBoot = true;
+        console.error("[Sandpack] Refusing to register a frame that booted from a navigation " +
+            "this client did not perform (R3-353). The frame is being torn down.");
+        try {
+            this.iframe.src = "about:blank";
+        }
+        catch (_c) {
+            /* the element may already be gone */
+        }
+        this.destroy();
+        (_b = (_a = this.options).onUnexpectedNavigation) === null || _b === void 0 ? void 0 : _b.call(_a);
+        return false;
+    };
     SandpackRuntime.prototype.destroy = function () {
         var _a, _b, _c, _d;
         this.unsubscribeChannelListener();
@@ -965,14 +1221,32 @@ var SandpackRuntime = /** @class */ (function (_super) {
         return this.iframeProtocol.channelListen(listener);
     };
     /**
-     * Get the URL of the contents of the current sandbox
+     * Get the URL of the contents of the current sandbox.
+     *
+     * R3-367 — GESTURE-GATED. This POSTs the ENTIRE app filesystem to
+     * codesandbox.io from the parent page; the fs may contain the user's data
+     * (spaces, mounts), so the export is reachable only when the user has been
+     * active on the page (`navigator.userActivation.hasBeenActive` — the sticky
+     * flag, because the fs snapshot can outlive a transient-activation window).
+     * Without any user activation this refuses BEFORE reading the filesystem:
+     * nothing is posted, and a `sandpack-security-violation` CustomEvent is
+     * dispatched on the window for the host to journal (site-main wires the
+     * listener into its security-events seam).
      */
     SandpackRuntime.prototype.getCodeSandboxURL = function () {
         return utils.__awaiter(this, void 0, void 0, function () {
             var snapshot, paramFiles, res, sandboxId;
             return utils.__generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0: return [4 /*yield*/, snapshotFS(this.sandboxSetup.fs)];
+                    case 0:
+                        if (!codeSandboxExportAllowed()) {
+                            // No user has ever interacted with this page: an export initiated here
+                            // would be app- or script-initiated, not user-initiated. Refuse and make
+                            // the refusal observable — BEFORE reading the filesystem.
+                            notifyCodeSandboxExportRefused();
+                            throw new Error("getCodeSandboxURL requires user activation (R3-367 gesture gate)");
+                        }
+                        return [4 /*yield*/, snapshotFS(this.sandboxSetup.fs)];
                     case 1:
                         snapshot = _a.sent();
                         paramFiles = Object.keys(snapshot).reduce(function (prev, next) {
@@ -1052,3 +1326,5 @@ function snapshotFS(fs) {
 }
 
 exports.SandpackRuntime = SandpackRuntime;
+exports.codeSandboxExportAllowed = codeSandboxExportAllowed$1;
+exports.notifyCodeSandboxExportRefused = notifyCodeSandboxExportRefused$1;