@immediately-run/sandpack-client 2.22.0 → 2.22.1

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

@@ -1,6 +1,6 @@
 {
   "name": "sandpack-client",
-  "version": "2.22.0",
-  "srcHash": "0ad007879d4260ed144b1aef82d68bc2332a9b291d777aed95b8320499351fac",
-  "builtAt": "2026-08-26T22:56:07.275Z"
+  "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;
@@ -81,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();
@@ -621,9 +685,44 @@ 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.22.0") === 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) {
@@ -1122,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) {
@@ -1209,3 +1326,5 @@ function snapshotFS(fs) {
 }
 
 exports.SandpackRuntime = SandpackRuntime;
+exports.codeSandboxExportAllowed = codeSandboxExportAllowed$1;
+exports.notifyCodeSandboxExportRefused = notifyCodeSandboxExportRefused$1;

package/dist/clients/runtime/index.mjs

@@ -1,6 +1,6 @@
 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-BgalzxpH.mjs';
+import { a as SandpackLogLevel } from '../../types-DRg992RB.mjs';
 import { S as SandpackClient } from '../../base-DBh7xJX9.mjs';
 import { c as createSandboxedIframe, e as ensureSandboxed } from '../../iframe-factory-C8M0b9uf.mjs';
 import mimeDB from 'mime-db';
@@ -64,6 +64,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
@@ -72,8 +87,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 = [];
@@ -99,8 +115,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).
@@ -151,7 +168,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;
         }
@@ -188,24 +209,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 __awaiter(void 0, void 0, void 0, function () {
     var _a;
@@ -297,14 +344,22 @@ var matchesIntegrity = function (body, integrity) { return __awaiter(void 0, voi
  */
 function handleImmutableFetch(url, integrity) {
     return __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 __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:
@@ -328,12 +383,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();
@@ -619,9 +683,44 @@ 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.22.0") === 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) {
     __extends(SandpackRuntime, _super);
     function SandpackRuntime(selector, sandboxSetup, options) {
@@ -1120,14 +1219,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 __awaiter(this, void 0, void 0, function () {
             var snapshot, paramFiles, res, sandboxId;
             return __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) {
@@ -1206,4 +1323,4 @@ function snapshotFS(fs) {
     });
 }
 
-export { SandpackRuntime };
+export { SandpackRuntime, codeSandboxExportAllowed$1 as codeSandboxExportAllowed, notifyCodeSandboxExportRefused$1 as notifyCodeSandboxExportRefused };

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

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

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

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

package/dist/{index-CetxPB1x.mjs → index-CSAGdFtt.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-BYuGaxe8.mjs';
+import { E as EventEmitter, g as generateRandomId, c as consoleHook } from './consoleHook-DT9Wd42J.mjs';
 import { S as SandpackClient } from './base-DBh7xJX9.mjs';
 import { c as createSandboxedIframe, e as ensureSandboxed } from './iframe-factory-C8M0b9uf.mjs';
 import 'outvariant';
-import './types-BgalzxpH.mjs';
+import './types-DRg992RB.mjs';
 import '@zenfs/core';
 import 'dequal';
 

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

@@ -2,11 +2,11 @@
 
 var utils = require('./utils-BiVyytui.js');
 var staticBrowserServer = require('static-browser-server');
-var consoleHook = require('./consoleHook-BRSVCdB0.js');
+var consoleHook = require('./consoleHook-vrsBdedj.js');
 var base = require('./base-DelKLlDk.js');
 var iframeFactory = require('./iframe-factory-Bc7tcyQZ.js');
 require('outvariant');
-require('./types-KEkDKvIe.js');
+require('./types-B3g_70H8.js');
 require('@zenfs/core');
 require('dequal');
 

package/dist/index.js

@@ -1,7 +1,7 @@
 'use strict';
 
 var utils = require('./utils-BiVyytui.js');
-var types = require('./types-KEkDKvIe.js');
+var types = require('./types-B3g_70H8.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-dX5nvjo5.js'); }).then(function (m) { return m.SandpackStatic; })];
+                case 3: return [4 /*yield*/, Promise.resolve().then(function () { return require('./index-Dnq1i5aM.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-BgalzxpH.mjs';
+export { M as META_PATH, S as SandpackFS, a as SandpackLogLevel } from './types-DRg992RB.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-CetxPB1x.mjs').then(function (m) { return m.SandpackStatic; })];
+                case 3: return [4 /*yield*/, import('./index-CSAGdFtt.mjs').then(function (m) { return m.SandpackStatic; })];
                 case 4:
                     Client = _c.sent();
                     return [3 /*break*/, 7];

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

@@ -45,7 +45,7 @@ var GUARDED_WRITE_METHODS = [
  * (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
+ * is behind the `if (IS_DEV)` branch in {@link ensureGuard} — 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.
  */
@@ -73,6 +73,35 @@ function installOutOfBandGuard(fsContext) {
         _loop_1(method);
     }
 }
+/**
+ * The true raw write methods per bound context, captured once and shared by every
+ * SandpackFS instance that adopts that context. Without this, a second instance's
+ * constructor captures the first instance's wrapper as its "raw" method — because the
+ * guard has already replaced `fsContext.fs.promises` entries — so SandpackFS's own
+ * writes trip the guard once per prior adoption (the R3-614 stacking bug).
+ */
+var RAW = new WeakMap();
+/**
+ * Return the context's raw write methods, capturing them and installing the out-of-band
+ * guard exactly once per context (see {@link installOutOfBandGuard}). Reads `RAW` first,
+ * so adopting the same context any number of times never re-wraps, never re-captures a
+ * wrapper as raw, and never disarms a sibling instance.
+ */
+function ensureGuard(fsContext) {
+    var existing = RAW.get(fsContext);
+    if (existing)
+        return existing;
+    var p = fsContext.fs.promises;
+    var raw = {
+        writeFile: p.writeFile.bind(p),
+        unlink: p.unlink.bind(p),
+        mkdir: p.mkdir.bind(p),
+    };
+    RAW.set(fsContext, raw);
+    if (IS_DEV)
+        installOutOfBandGuard(fsContext);
+    return raw;
+}
 var mountCounter = 0;
 var normalize = function (path) {
     return path.startsWith("/") ? path : "/".concat(path);
@@ -119,12 +148,10 @@ var SandpackFS = /** @class */ (function () {
          *  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);
+        var raw = ensureGuard(fsContext);
+        this.rawWriteFile = raw.writeFile;
+        this.rawUnlink = raw.unlink;
+        this.rawMkdir = raw.mkdir;
     }
     /**
      * Create the `MessagePort` shared with the child iframe, wiring the iframe's

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

@@ -43,7 +43,7 @@ var GUARDED_WRITE_METHODS = [
  * (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
+ * is behind the `if (IS_DEV)` branch in {@link ensureGuard} — 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.
  */
@@ -71,6 +71,35 @@ function installOutOfBandGuard(fsContext) {
         _loop_1(method);
     }
 }
+/**
+ * The true raw write methods per bound context, captured once and shared by every
+ * SandpackFS instance that adopts that context. Without this, a second instance's
+ * constructor captures the first instance's wrapper as its "raw" method — because the
+ * guard has already replaced `fsContext.fs.promises` entries — so SandpackFS's own
+ * writes trip the guard once per prior adoption (the R3-614 stacking bug).
+ */
+var RAW = new WeakMap();
+/**
+ * Return the context's raw write methods, capturing them and installing the out-of-band
+ * guard exactly once per context (see {@link installOutOfBandGuard}). Reads `RAW` first,
+ * so adopting the same context any number of times never re-wraps, never re-captures a
+ * wrapper as raw, and never disarms a sibling instance.
+ */
+function ensureGuard(fsContext) {
+    var existing = RAW.get(fsContext);
+    if (existing)
+        return existing;
+    var p = fsContext.fs.promises;
+    var raw = {
+        writeFile: p.writeFile.bind(p),
+        unlink: p.unlink.bind(p),
+        mkdir: p.mkdir.bind(p),
+    };
+    RAW.set(fsContext, raw);
+    if (IS_DEV)
+        installOutOfBandGuard(fsContext);
+    return raw;
+}
 var mountCounter = 0;
 var normalize = function (path) {
     return path.startsWith("/") ? path : "/".concat(path);
@@ -117,12 +146,10 @@ var SandpackFS = /** @class */ (function () {
          *  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);
+        var raw = ensureGuard(fsContext);
+        this.rawWriteFile = raw.writeFile;
+        this.rawUnlink = raw.unlink;
+        this.rawMkdir = raw.mkdir;
     }
     /**
      * Create the `MessagePort` shared with the child iframe, wiring the iframe's

package/dist/types.d.ts

@@ -251,7 +251,13 @@ export type ClientStatus = "initializing" | "installing-dependencies" | "transpi
 export type SandpackMessageConsoleMethods = "log" | "debug" | "info" | "warn" | "error" | "table" | "clear" | "time" | "timeEnd" | "count" | "assert";
 export interface BaseSandpackMessage {
     type: string;
-    $id?: number;
+    /**
+     * The sender's channel id. Newer peers mint it as a crypto-random hex STRING
+     * (R3-367 — 64 bits); ids older peers minted as numbers still flow, because
+     * each side compares the value it itself sent. Correlation only — never an
+     * authenticator (the evt.source check in IFrameProtocol is).
+     */
+    $id?: string | number;
     codesandbox?: boolean;
     /**
      * Transferable objects (e.g. a `MessagePort`) to hand to the iframe alongside

package/package.json

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