Recover sandbox reloads instead of dying on the stripped contract URL (#10)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: shawntabrizi

apps/sandbox/src/main.ts

@@ -85,6 +85,26 @@ function stripContractParamsFromUrl(): void {
   history.replaceState(null, "", cleaned.toString());
 }
 
+/**
+ * Ask the host shell to rebuild this iframe with a fresh contract URL.
+ *
+ * `stripContractParamsFromUrl` removes the contract params once boot
+ * succeeds, so a later reload of this window (a dApp calling
+ * `location.reload()`, a browser restoring a crashed frame) boots with no
+ * `?cid=`. The host still tracks the rendered label and resolved CID and
+ * can re-render the iframe with the exact params it last threaded. If the
+ * host does not tear this iframe down within the timeout (it no longer
+ * tracks a product, or its rate guard tripped) fall back to the hard
+ * contract error this path showed before recovery existed.
+ */
+function requestHostRerender(reason: string): void {
+  showStatus("Restoring app...");
+  window.parent.postMessage({ type: "dotli:sandbox-recover" }, "*");
+  window.setTimeout(() => {
+    failLoading("Invalid sandbox URL", reason);
+  }, TIMEOUTS.SANDBOX_RECOVER);
+}
+
 /**
  * Render the sandbox-local error page AND tell the host shell its loading
  * overlay is finished. Without the parent notify, the host's `.loading`
@@ -594,7 +614,11 @@ async function main(): Promise<void> {
   const urlParams = new URL(window.location.href).searchParams;
   const parsed = validateSandboxParams(urlParams);
   if (!parsed.ok) {
-    failLoading("Invalid sandbox URL", parsed.reason);
+    if (parsed.recoverable === true) {
+      requestHostRerender(parsed.reason);
+    } else {
+      failLoading("Invalid sandbox URL", parsed.reason);
+    }
     stopApp();
     return;
   }

packages/config/src/host-sandbox-contract.ts

@@ -78,13 +78,21 @@ export interface SandboxParams {
 
 export type SandboxParamsResult =
   | { ok: true; params: SandboxParams }
-  | { ok: false; reason: string };
+  | { ok: false; reason: string; recoverable?: boolean };
 
 /**
  * Validate a sandbox URL against the host-to-sandbox contract.
  *
  * Returns a discriminated result. The caller is expected to render the
  * failure reason in the UI and stop. Never substitute defaults silently.
+ *
+ * `recoverable: true` marks failures where a required param is absent
+ * entirely. The sandbox strips contract params from its URL after a
+ * successful boot, so an absent param is the signature of a reload of an
+ * already-booted sandbox window, and the host can recover by re-rendering
+ * the iframe with a fresh contract URL. A param that is present but
+ * invalid means the host build itself is broken. Re-rendering would
+ * produce the same bad value, so those stay fatal.
  */
 export function validateSandboxParams(
   search: URLSearchParams,
@@ -108,6 +116,7 @@ export function validateSandboxParams(
   if (cid === null || cid === "") {
     return {
       ok: false,
+      recoverable: cid === null,
       reason:
         "Missing required URL param `cid`. The host did not propagate the resolved content id. Reload from dot.li.",
     };
@@ -123,6 +132,7 @@ export function validateSandboxParams(
   if (chainBackend === null) {
     return {
       ok: false,
+      recoverable: true,
       reason:
         "Missing required URL param `chainBackend`. The host did not specify a backend — reload from dot.li.",
     };
@@ -138,6 +148,7 @@ export function validateSandboxParams(
   if (network === null) {
     return {
       ok: false,
+      recoverable: true,
       reason:
         "Missing required URL param `network`. The host did not propagate the active network — reload from dot.li.",
     };

packages/config/src/timeouts.ts

@@ -5,6 +5,10 @@
 export const TIMEOUTS = {
   /** SW cache lookup before falling through */
   SW_CACHE_LOOKUP: 3_000,
+  /** Host recover-request grace before the sandbox falls back to the
+   * contract error. Must exceed the host's recover rate-limit window so
+   * a rate-limited request fails visibly instead of hanging. */
+  SANDBOX_RECOVER: 6_000,
   /** Waiting for SW controllerchange after registration */
   SW_READY: 10_000,
   /** P2P fetch abort (per attempt) */

packages/config/tests/host-sandbox-contract.test.ts

@@ -44,27 +44,36 @@ describe("validateSandboxParams: v3 cid contract", () => {
     }
   });
 
-  it("As the sandbox, I reject a contract that omits the cid", () => {
-    // Given a contract with no cid param.
+  it("As the sandbox, I reject a contract that omits the cid, but flag it recoverable so the host can re-render me", () => {
+    // Given a contract with no cid param (the post-boot strip leaves
+    // exactly this shape behind, so a reload of a booted sandbox lands here).
     const params = search({ [SANDBOX_CONTRACT_PARAMS.cid]: null });
 
     // When the sandbox validates it.
     const result = validateSandboxParams(params);
 
-    // Then it fails with a reason that names the missing key.
+    // Then it fails with a reason that names the missing key, and marks
+    // the failure recoverable so the boot path asks the host for a fresh
+    // contract URL instead of dying on a dead-end error page.
     expect(result.ok).toBe(false);
-    if (!result.ok) expect(result.reason).toMatch(/cid/i);
+    if (!result.ok) {
+      expect(result.reason).toMatch(/cid/i);
+      expect(result.recoverable).toBe(true);
+    }
   });
 
-  it("As the sandbox, I reject a contract whose cid is the empty string", () => {
+  it("As the sandbox, I reject a contract whose cid is the empty string as fatal, since the host explicitly sent a broken value", () => {
     // Given a contract with an empty cid.
     const params = search({ [SANDBOX_CONTRACT_PARAMS.cid]: "" });
 
     // When the sandbox validates it.
     const result = validateSandboxParams(params);
 
-    // Then it fails (an empty cid is treated the same as a missing one).
+    // Then it fails, and is NOT recoverable: an empty value cannot come
+    // from the post-boot param strip, so re-rendering from the same host
+    // would produce the same empty cid again.
     expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.recoverable).not.toBe(true);
   });
 
   it("As the sandbox, I reject a contract whose cid contains non-alphanumeric characters", () => {
@@ -128,4 +137,20 @@ describe("validateSandboxParams: v3 cid contract", () => {
     // Then it fails (network is still required after the v3 bump).
     expect(result.ok).toBe(false);
   });
+
+  it("As a user whose dApp reloads itself after the param strip, the contract failure is recoverable so the host can restore my session", () => {
+    // Given a URL with no contract params at all, which is what a booted
+    // sandbox window looks like after stripContractParamsFromUrl: a dApp
+    // calling location.reload() re-enters the boot with this exact shape.
+    const params = new URLSearchParams({ theme: "dark" });
+
+    // When the sandbox validates it.
+    const result = validateSandboxParams(params);
+
+    // Then the failure is recoverable: the host still tracks the rendered
+    // label and CID, so it can rebuild the iframe instead of stranding the
+    // user on a full-viewport "Invalid sandbox URL" error.
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.recoverable).toBe(true);
+  });
 });

packages/ui/src/bridge.ts

@@ -67,6 +67,42 @@ window.addEventListener("dotli:device-permission-changed", () => {
   }
 });
 
+// The sandbox strips its contract params after a successful boot, so a
+// reload of the sandbox window (a dApp calling `location.reload()`, a
+// browser restoring a crashed frame) boots without `?cid=` and cannot
+// recover on its own. It posts a recover request and the host rebuilds
+// the iframe from the tracked product state. The origin gate restricts
+// the request to the product currently rendered. The interval guard stops
+// a reload-looping product from pinning the host in endless re-renders.
+// A rate-limited sandbox shows its own contract error once its
+// `TIMEOUTS.SANDBOX_RECOVER` grace expires.
+const RECOVER_MIN_INTERVAL_MS = 5_000;
+let lastRecoverAt = 0;
+window.addEventListener("message", (event: MessageEvent) => {
+  const data = event.data as Record<string, unknown> | null;
+  if (
+    data === null ||
+    typeof data !== "object" ||
+    data.type !== "dotli:sandbox-recover"
+  ) {
+    return;
+  }
+  if (
+    currentRenderMode !== "subdomain" ||
+    currentCid === null ||
+    currentLabel === null ||
+    event.origin !== getAppOrigin(currentLabel)
+  ) {
+    return;
+  }
+  const now = Date.now();
+  if (now - lastRecoverAt < RECOVER_MIN_INTERVAL_MS) {
+    return;
+  }
+  lastRecoverAt = now;
+  void renderAppSubdomain(currentCid, currentLabel);
+});
+
 /**
  * Capture deep link path (pathname + search + hash) to forward into the iframe.
  */