castle-web-sdk 0.4.25 → 0.4.27

package/dist/transport.js

@@ -7,7 +7,7 @@
 //   - web     → window.parent.postMessage; responses via 'message' events
 //   - local   → the castle-web serve dev server, over runtime.ts's websocket
 // Error reconstruction is uniform here so callers always get a CastleError.
-import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, } from "./commands";
+import { CASTLE_SDK_PROTOCOL, isResponseEnvelope, unloadRequestId, } from "./commands";
 import { getCastleEmbed } from "./context";
 import { CastleError } from "./errors";
 import { sendLocalCommand } from "./runtime";
@@ -22,6 +22,7 @@ const INTERACTIVE_COMMANDS = new Set([
 let nextRequestId = 1;
 const pending = new Map();
 let listenersInstalled = false;
+let unloadHandler = null;
 export async function hostRequest(command, params) {
     try {
         const channel = resolveChannel();
@@ -67,6 +68,26 @@ export function hostNotify(event) {
     };
     sendEnvelope(channel, envelope);
 }
+// Reply to a host unload request. One-way like hostNotify, but it carries the
+// handshake's whole point, so it posts even with no state: the host is holding
+// its teardown open until this arrives or its cap runs out.
+export function postUnloadDone(unloadId, state) {
+    if (typeof window === "undefined")
+        return;
+    const channel = resolveChannel();
+    if (channel === "local")
+        return;
+    const envelope = {
+        castleSdk: CASTLE_SDK_PROTOCOL,
+        unloadDone: state === undefined ? { unloadId } : { unloadId, state },
+    };
+    sendEnvelope(channel, envelope);
+}
+// Registered by unloadHandshake.ts rather than imported from it, so this module
+// keeps no dependency on the one that depends on it.
+export function setUnloadHandler(handler) {
+    unloadHandler = handler;
+}
 function resolveChannel() {
     if (typeof window === "undefined")
         return "local";
@@ -82,7 +103,7 @@ function resolveChannel() {
     return window.parent && window.parent !== window ? "web" : "local";
 }
 function postCommand(channel, command, params) {
-    installResponseListener();
+    installHostListener();
     const requestId = `csdk_${nextRequestId++}`;
     return new Promise((resolve, reject) => {
         const timeout = INTERACTIVE_COMMANDS.has(command)
@@ -106,15 +127,28 @@ function sendEnvelope(channel, envelope) {
 }
 // The mobile host can't dispatch a DOM 'message' event, so it calls this global
 // directly with the parsed envelope. The web host posts a 'message' event.
-function installResponseListener() {
+//
+// Exported because a deck that only registers an unload subscriber never posts a
+// command, and without this the global would never exist — the host's inject
+// would land on nothing and its handshake would run out its cap in silence.
+export function installHostListener() {
     if (listenersInstalled || typeof window === "undefined")
         return;
     listenersInstalled = true;
-    window.__castleSdkHost = { receive: (message) => settle(message) };
+    window.__castleSdkHost = { receive: (message) => receive(message) };
     window.addEventListener("message", (event) => {
-        settle(event.data);
+        receive(event.data);
     });
 }
+function receive(message) {
+    if (isResponseEnvelope(message)) {
+        settle(message);
+        return;
+    }
+    const unloadId = unloadRequestId(message);
+    if (unloadId !== null)
+        unloadHandler?.(unloadId);
+}
 function settle(message) {
     if (!isResponseEnvelope(message))
         return;

package/dist/unloadFlush.d.ts

@@ -0,0 +1,3 @@
+type FlushHandler = () => void;
+export declare function onUnloadFlush(handler: FlushHandler): void;
+export {};

package/dist/unloadFlush.js

@@ -0,0 +1,30 @@
+// Somewhere to hang "flush before the page goes away".
+//
+// Writes batch on a timer, so leaving the page inside that window would lose
+// them, and a deck saving progress as someone quits is exactly when it matters.
+// `pagehide` is the reliable signal on iOS, where unload often never fires, and
+// visibilitychange covers backgrounding without a navigation.
+//
+// Listeners are registered on the first write, so a deck that never stores
+// anything hooks nothing.
+//
+// Handlers are held in a Set, so registering on every write is fine as long as
+// the caller passes a STABLE function reference. A fresh closure per call would
+// accumulate, and every one of them would run at unload.
+const handlers = new Set();
+let hooked = false;
+export function onUnloadFlush(handler) {
+    handlers.add(handler);
+    if (hooked || typeof window === "undefined")
+        return;
+    hooked = true;
+    const flushAll = () => {
+        for (const flush of handlers)
+            flush();
+    };
+    window.addEventListener("pagehide", flushAll);
+    document.addEventListener("visibilitychange", () => {
+        if (document.visibilityState === "hidden")
+            flushAll();
+    });
+}

package/dist/unloadHandshake.d.ts

@@ -0,0 +1,6 @@
+export interface UnloadContext {
+    state?: string;
+}
+export type UnloadSubscriber = (ctx: UnloadContext) => void;
+export declare function onHostUnload(subscriber: UnloadSubscriber): () => void;
+export declare function notifyUnloadInterest(): void;

package/dist/unloadHandshake.js

@@ -0,0 +1,47 @@
+// The host-driven half of "this page is about to go away".
+//
+// `unloadFlush.ts` is the browser-event half — pagehide / visibilitychange,
+// which a deck's own document raises. This one is the host's: an RN WebView
+// being torn down on a feed swipe never raises those reliably, so the mobile
+// host sends an explicit unload request first and holds its teardown open,
+// briefly, for the reply.
+//
+// Subscribers run synchronously and the reply goes out in the same tick. That
+// is the contract that makes the host's wait short: it is waiting on one
+// postMessage, not on whatever work a subscriber might want to do. A subscriber
+// with host-bound work of its own must post it BEFORE returning — deck→host
+// messages are FIFO per WebView, so anything posted first arrives first.
+import { hostNotify, installHostListener, postUnloadDone, setUnloadHandler } from "./transport";
+const subscribers = new Set();
+let installed = false;
+let interestSent = false;
+export function onHostUnload(subscriber) {
+    subscribers.add(subscriber);
+    if (!installed) {
+        installed = true;
+        installHostListener();
+        setUnloadHandler(runHandshake);
+    }
+    return () => subscribers.delete(subscriber);
+}
+// Tells the host this deck has something to hand over, so it runs the handshake
+// (and pays its bounded wait) for this deck instead of skipping it. Sent once;
+// the host doesn't care which subscriber prompted it.
+export function notifyUnloadInterest() {
+    if (interestSent)
+        return;
+    interestSent = true;
+    hostNotify("unloadInterest");
+}
+function runHandshake(unloadId) {
+    const ctx = {};
+    for (const subscriber of subscribers) {
+        try {
+            subscriber(ctx);
+        }
+        catch (error) {
+            console.warn("Castle unload subscriber threw.", error);
+        }
+    }
+    postUnloadDone(unloadId, ctx.state);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-sdk",
-  "version": "0.4.25",
+  "version": "0.4.27",
   "type": "module",
   "main": "dist/castle.js",
   "types": "dist/castle.d.ts",