@immediately-run/sandpack-client 2.21.0 → 2.22.0

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

@@ -1,6 +1,6 @@
 {
   "name": "sandpack-client",
-  "version": "2.21.0",
-  "srcHash": "afbc7e1f72ab14999158254aba8d870baf59194b341b07fe89ea866277efaf8d",
-  "builtAt": "2026-07-31T18:21:27.125Z"
+  "version": "2.22.0",
+  "srcHash": "0ad007879d4260ed144b1aef82d68bc2332a9b291d777aed95b8320499351fac",
+  "builtAt": "2026-08-26T22:56:07.275Z"
 }

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

@@ -17,8 +17,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 +44,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;
     /**

package/dist/clients/runtime/index.js

@@ -364,6 +364,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++) {
@@ -530,14 +623,25 @@ function getExtension(filepath) {
 
 var _a;
 var SUFFIX_PLACEHOLDER = "-{{suffix}}";
-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 BUNDLER_URL = "https://".concat((_a = "2.22.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) {
         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 +696,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 +959,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();

package/dist/clients/runtime/index.mjs

@@ -362,6 +362,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,14 +621,25 @@ function getExtension(filepath) {
 
 var _a;
 var SUFFIX_PLACEHOLDER = "-{{suffix}}";
-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 BUNDLER_URL = "https://".concat((_a = "2.22.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) {
         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) {
@@ -590,6 +694,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 __awaiter(_this, void 0, void 0, function () {
@@ -833,9 +957,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();

package/dist/clients/runtime/initialization-guard.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+export declare class InitializationGuard {
+    private expected;
+    private detached;
+    /** Record that the host has navigated the frame, so ONE boot is now expected. */
+    arm(): void;
+    /**
+     * 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.
+     */
+    consume(): boolean;
+    /** True once an unexpected boot has been refused. Terminal. */
+    get isDetached(): boolean;
+    /** How many host-initiated boots are still outstanding (diagnostics/tests). */
+    get pending(): number;
+}

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

@@ -28,6 +28,11 @@ export type SandpackRuntimeMessage = BaseSandpackMessage & ({
     url: string;
     back: boolean;
     forward: boolean;
+    /** R3-268: the tri-state viewed-document declaration — ABSENT means
+     *  "derive from the URL's `files/` suffix convention", `null` means
+     *  "this view shows no file" (clears the explorer highlight), a string
+     *  is a working-tree repo-relative path the destination renders. */
+    viewedDocument?: string | null;
 } | {
     type: "resize";
     height: number;

package/dist/types.d.ts

@@ -37,6 +37,18 @@ export interface ClientOptions {
      * `allow-same-origin`). Required for the runtime client to transpile.
      */
     babelWorkerURL?: string;
+    /**
+     * Called when the client REFUSES to register a frame because it booted from a
+     * navigation the client did not perform (R3-353 — a sandboxed frame may always
+     * navigate itself, and the browsing context survives, so a page the app chose
+     * could otherwise post `initialized` and be handed this frame's grants).
+     *
+     * By the time this fires the frame has been blanked and the client destroyed:
+     * nothing was connected and no fs port was minted. The host's job is to surface
+     * it (and/or re-create the frame from a clean state), not to decide whether to
+     * allow it — that decision has already been made, fail-closed.
+     */
+    onUnexpectedNavigation?: () => void;
     /**
      * Level of logging to do in the bundler
      */

package/package.json

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