@tokenoftrust/storefront-runner 4.7.3 → 4.7.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.7.3",
+  "version": "4.7.4",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -5,7 +5,8 @@
  * the renderer-published boot descriptor global, guarantees ONE lifecycle per document
  * with a window-level singleton (so a nested layout that re-runs the boot island cannot
  * double-init), wires same-document navigations to the reserved completed-navigation
- * event, disposes on document teardown, and is a guarded no-op off the browser.
+ * event, disposes on every `pagehide`, boots a fresh lifecycle when the back-forward
+ * cache restores the page, and is a guarded no-op off the browser.
  *
  * The entry module for each integration is the same-origin, exact-version asset the
  * boot descriptor carries (`integration.entry.url`): the default loader dynamically
@@ -440,20 +441,38 @@ function deferFetchCapability(
     })) as typeof fetch;
 }
 
+/** The window property marking that this window's event wiring is installed (once per window). */
+const LIFECYCLE_WIRED_GLOBAL = "__TOT_INTEGRATION_LIFECYCLE_WIRED__";
+
 /**
- * Boot the lifecycle for `win` exactly once. A second call returns the same instance
- * (nested-layout safety). Returns `null` when there is no boot descriptor to act on.
+ * Boot the lifecycle for `win`. While a live lifecycle exists a second call returns it
+ * (nested-layout safety). A disposed one — the page was hidden into the back-forward
+ * cache — is replaced by a fresh lifecycle. Returns `null` when there is no boot
+ * descriptor to act on.
  */
 export function bootIntegrationLifecycle(
   win: LifecycleWindow,
   options: BootLifecycleOptions = {},
 ): IntegrationLifecycle | null {
   const existing = win[LIFECYCLE_SINGLETON_GLOBAL];
-  if (existing instanceof IntegrationLifecycle) return existing;
+  if (existing instanceof IntegrationLifecycle && !existing.isDisposed) return existing;
 
   const descriptor = readDescriptor(win);
   if (!descriptor) return null;
 
+  const lifecycle = createDocumentLifecycle(win, descriptor, options);
+  win[LIFECYCLE_SINGLETON_GLOBAL] = lifecycle;
+  wireWindow(win, options);
+  void lifecycle.init();
+  return lifecycle;
+}
+
+function createDocumentLifecycle(
+  win: LifecycleWindow,
+  descriptor: IntegrationBootDescriptor,
+  options: BootLifecycleOptions,
+): IntegrationLifecycle {
+
   const hostFetch = options.fetchCapability ??
     (typeof win.fetch === "function" ? win.fetch.bind(win) : undefined);
   const schedulePlatformAdapterStart =
@@ -508,7 +527,7 @@ export function bootIntegrationLifecycle(
   // The managed-analytics bridge over the SAME broker the adapters subscribe to — the
   // only seam that emits this document's governed page view. The lifecycle owns when it
   // fires (after every adapter has subscribed, and re-attempted on a consent grant).
-  const lifecycle = new IntegrationLifecycle({
+  return new IntegrationLifecycle({
     descriptor,
     loadModule,
     isEligible,
@@ -536,39 +555,48 @@ export function bootIntegrationLifecycle(
       pageView: () => documentPageView(win, descriptor, options.now ?? Date.now),
     },
   });
-  win[LIFECYCLE_SINGLETON_GLOBAL] = lifecycle;
+}
 
-  wireNavigation(win, lifecycle);
-  wireTeardown(win, lifecycle);
-  void lifecycle.init();
-  return lifecycle;
+/** The window's current live lifecycle, if any. */
+function liveLifecycle(win: LifecycleWindow): IntegrationLifecycle | undefined {
+  const current = win[LIFECYCLE_SINGLETON_GLOBAL];
+  return current instanceof IntegrationLifecycle && !current.isDisposed ? current : undefined;
 }
 
 /**
- * Wire same-document navigations to the reserved completed-navigation event. In a
- * traditional MPA a real document load re-inits by construction, so only the two
- * navigations that DON'T reload the document — hash changes and history back/forward —
- * need a completed-navigation signal, and neither re-initializes integrations.
+ * Install this window's event wiring once; every listener acts on the CURRENT lifecycle.
+ *
+ * Same-document navigations — hash changes and history back/forward — emit the reserved
+ * completed-navigation event and never re-initialize integrations; a real document load
+ * re-inits by construction.
+ *
+ * Every `pagehide` disposes the lifecycle, so integrations clean up and abandon any
+ * deferred work (a held navigation never resumes after the shopper left). A
+ * `pageshow` from the back-forward cache boots a fresh lifecycle, so the restored page
+ * has live integrations again.
  */
-function wireNavigation(win: LifecycleWindow, lifecycle: IntegrationLifecycle): void {
+function wireWindow(win: LifecycleWindow, options: BootLifecycleOptions): void {
+  if (win[LIFECYCLE_WIRED_GLOBAL] === true) return;
+  win[LIFECYCLE_WIRED_GLOBAL] = true;
   let lastPath = win.location.pathname + win.location.hash;
   win.addEventListener("hashchange", () => {
     const to = win.location.pathname + win.location.hash;
-    lifecycle.notifyNavigationCompleted({ from: lastPath, to, kind: "hash" });
+    liveLifecycle(win)?.notifyNavigationCompleted({ from: lastPath, to, kind: "hash" });
     lastPath = to;
   });
   win.addEventListener("popstate", () => {
     const to = win.location.pathname + win.location.hash;
     const kind: NavigationKind = "back-forward";
-    lifecycle.notifyNavigationCompleted({ from: lastPath, to, kind });
+    liveLifecycle(win)?.notifyNavigationCompleted({ from: lastPath, to, kind });
     lastPath = to;
   });
-}
-
-/** Dispose the lifecycle when the document is torn down, so integrations clean up once. */
-function wireTeardown(win: LifecycleWindow, lifecycle: IntegrationLifecycle): void {
   win.addEventListener("pagehide", () => {
-    void lifecycle.dispose();
+    const current = win[LIFECYCLE_SINGLETON_GLOBAL];
+    if (current instanceof IntegrationLifecycle) void current.dispose();
+  });
+  win.addEventListener("pageshow", (event) => {
+    if ((event as { persisted?: unknown } | null)?.persisted !== true) return;
+    bootIntegrationLifecycle(win, options);
   });
 }
 

package/packages/public-runtime/src/integration/lifecycle-runtime.ts

@@ -224,6 +224,11 @@ export class IntegrationLifecycle {
     return this.state === "initialized";
   }
 
+  /** True once dispose has started; a disposed lifecycle never runs again. */
+  get isDisposed(): boolean {
+    return this.isTerminal();
+  }
+
   /**
    * Initialize every integration EXACTLY ONCE per document, in the plan's resolved order.
    * A second call — including one from a nested layout that re-runs the boot island — is a