@mochabug/adapt-web 1.0.0-rc53 → 1.0.0-rc55

package/dist/esm/AdaptAutomationElement.js

@@ -13,6 +13,7 @@ const OBSERVED_ATTRIBUTES = [
     "dialog-resize-to-content",
     "dark-mode",
     "auto-resizing",
+    "persist",
 ];
 /**
  * `<adapt-automation>` custom element for embedding Adapt automations.
@@ -107,6 +108,25 @@ export class AdaptAutomationElement extends BaseElement {
             this.removeAttribute("dialog-resize-to-content");
         }
     }
+    get persist() {
+        return this.hasAttribute("persist");
+    }
+    set persist(v) {
+        if (v) {
+            this.setAttribute("persist", "");
+        }
+        else {
+            this.removeAttribute("persist");
+        }
+    }
+    /**
+     * Clear persisted state, stop current session, and reinitialize fresh.
+     */
+    async newSession() {
+        if (this._client) {
+            await this._client.newSession();
+        }
+    }
     // --- Lifecycle ---
     connectedCallback() {
         // Defer to next microtask to avoid TDZ issues from circular imports
@@ -119,7 +139,7 @@ export class AdaptAutomationElement extends BaseElement {
     attributeChangedCallback(name, oldValue, newValue) {
         if (oldValue === newValue)
             return;
-        if (name === "automation-id") {
+        if (name === "automation-id" || name === "persist") {
             this._destroyClient();
             queueMicrotask(() => this._tryInit());
             return;
@@ -229,6 +249,13 @@ export class AdaptAutomationElement extends BaseElement {
             options.classNames = this.classNames;
         if (this.styles !== undefined)
             options.styles = this.styles;
+        // Persist: object options take precedence, otherwise use boolean attribute
+        if (this.persistOptions !== undefined) {
+            options.persist = this.persistOptions;
+        }
+        else if (this.persist) {
+            options.persist = true;
+        }
         this._client = new AdaptWebClient(options);
     }
     _destroyClient() {
@@ -251,4 +278,3 @@ if (typeof customElements !== "undefined" &&
         document.head.appendChild(s);
     }
 }
-//# sourceMappingURL=AdaptAutomationElement.js.map

package/dist/esm/AdaptCapElement.js

@@ -145,4 +145,3 @@ if (typeof customElements !== "undefined" &&
         document.head.appendChild(s);
     }
 }
-//# sourceMappingURL=AdaptCapElement.js.map

package/dist/esm/AdaptCapWidget.js

@@ -287,4 +287,3 @@ export class AdaptCapWidget {
         this.widgetElement = null;
     }
 }
-//# sourceMappingURL=AdaptCapWidget.js.map

package/dist/esm/cap-adapter.js

@@ -144,4 +144,3 @@ export function cleanupCapAdapter() {
     currentClient = null;
     currentAutomationId = null;
 }
-//# sourceMappingURL=cap-adapter.js.map

package/dist/esm/elements.js

@@ -2,4 +2,3 @@
 // Usage: import "@mochabug/adapt-web/elements";
 import "./AdaptAutomationElement.js";
 import "./AdaptCapElement.js";
-//# sourceMappingURL=elements.js.map

package/dist/esm/iframe-url.js

@@ -22,4 +22,3 @@
 export function getIframeSrc(url, token) {
     return `${url}${token ? `#mb_token=${encodeURIComponent(token)}` : ""}`;
 }
-//# sourceMappingURL=iframe-url.js.map

package/dist/esm/index.js

@@ -19,6 +19,22 @@ export { configure, resetConfig };
 // Re-export custom elements
 export { AdaptAutomationElement } from "./AdaptAutomationElement.js";
 export { AdaptCapElement } from "./AdaptCapElement.js";
+/**
+ * Clear persisted session state for a given automation ID.
+ * Use this to force a fresh session on next page load.
+ *
+ * @param automationId - The automation ID whose state to clear
+ * @param storage - Which storage to clear: 'session' (default), 'local', or 'both'
+ */
+export function clearPersistedState(automationId, storage = "both") {
+    const key = `mb_adapt_${automationId}`;
+    if (storage === "session" || storage === "both") {
+        sessionStorage.removeItem(key);
+    }
+    if (storage === "local" || storage === "both") {
+        localStorage.removeItem(key);
+    }
+}
 /**
  * Default CSS styles with CSS Custom Properties for theming.
  */
@@ -1021,6 +1037,8 @@ export class AdaptWebClient {
             }
             // Reset for next drag
             unclampedSplit = this.splitPercentage;
+            // Persist the new split position
+            this.saveState();
         };
         this.mouseMoveHandler = handleMouseMove;
         this.mouseUpHandler = handleMouseUp;
@@ -1098,6 +1116,13 @@ export class AdaptWebClient {
                 if (sessionJson.status === "STATUS_COMPLETED" && !sessionJson.fork) {
                     this.handleSessionComplete();
                 }
+                // On any session-level terminal status, clear persisted state
+                if (!sessionJson.fork &&
+                    (sessionJson.status === "STATUS_COMPLETED" ||
+                        sessionJson.status === "STATUS_STOPPED" ||
+                        sessionJson.status === "STATUS_ERRORED")) {
+                    this.clearState();
+                }
                 if (this.options.onSession) {
                     this.options.onSession(sessionJson.status || "STATUS_UNSPECIFIED", sessionJson.fork);
                 }
@@ -1106,6 +1131,12 @@ export class AdaptWebClient {
         if (this.options.onOutput) {
             handlers.onOutput = this.options.onOutput;
         }
+        // Try to restore persisted session (skip when sessionToken is provided — server manages lifecycle)
+        if (!this.options.sessionToken && this.resolvePersistOptions()) {
+            const restored = await this.tryRestoreSession(handlers);
+            if (restored)
+                return;
+        }
         // Priority: sessionToken > challengeToken > inheritToken/inheritFrom > authToken
         if (this.options.sessionToken) {
             // Use pre-created session token directly (server-side scenario)
@@ -1154,6 +1185,8 @@ export class AdaptWebClient {
                 result = await this.client.run(runOptions);
             }
             this.sessionToken = result.sessionToken;
+            this.sessionExpiresAt = result.expiresAt;
+            this.saveState();
         }
     }
     /**
@@ -1198,12 +1231,223 @@ export class AdaptWebClient {
             this.capWidgetInstance = null;
         }
     }
+    // --- Persistence helpers ---
+    resolvePersistOptions() {
+        const p = this.options.persist;
+        if (!p)
+            return null;
+        if (p === true)
+            return { storage: "session", ttl: 3600 };
+        return { storage: p.storage ?? "session", ttl: p.ttl ?? 3600 };
+    }
+    getStorageKey() {
+        return `mb_adapt_${this.options.id}`;
+    }
+    getStorage() {
+        const opts = this.resolvePersistOptions();
+        if (!opts)
+            return null;
+        return opts.storage === "local" ? localStorage : sessionStorage;
+    }
+    saveState() {
+        const storage = this.getStorage();
+        if (!storage || !this.sessionToken)
+            return;
+        const opts = this.resolvePersistOptions();
+        const state = {
+            v: 1,
+            token: this.sessionToken,
+            expiresAt: this.sessionExpiresAt
+                ? this.sessionExpiresAt.toISOString()
+                : null,
+            savedAt: Date.now(),
+            ttl: opts.ttl,
+            mainUrl: this.mainUrl,
+            mainToken: this.mainToken,
+            currentFork: this.currentFork
+                ? {
+                    url: this.currentFork.url,
+                    token: this.currentFork.token,
+                    fork: this.currentFork.fork,
+                    depth: this.currentFork.depth,
+                    time: this.currentFork.time,
+                    completed: this.currentFork.completed,
+                }
+                : null,
+            forkQueue: this.forkQueue.map((f) => ({
+                url: f.url,
+                token: f.token,
+                fork: f.fork,
+                depth: f.depth,
+                time: f.time,
+                completed: f.completed,
+            })),
+            forkDisplayMode: this.forkDisplay.mode,
+            splitPercentage: this.splitPercentage,
+        };
+        storage.setItem(this.getStorageKey(), JSON.stringify(state));
+    }
+    loadState() {
+        const storage = this.getStorage();
+        if (!storage)
+            return null;
+        const raw = storage.getItem(this.getStorageKey());
+        if (!raw)
+            return null;
+        let state;
+        try {
+            state = JSON.parse(raw);
+        }
+        catch {
+            this.clearState();
+            return null;
+        }
+        // Version check
+        if (state.v !== 1) {
+            this.clearState();
+            return null;
+        }
+        const now = Date.now();
+        const leeway = 30000; // 30 seconds
+        // TTL check
+        if (now - state.savedAt > state.ttl * 1000 + leeway) {
+            this.clearState();
+            return null;
+        }
+        // Session expiresAt check
+        if (state.expiresAt) {
+            const expires = new Date(state.expiresAt).getTime();
+            if (now > expires + leeway) {
+                this.clearState();
+                return null;
+            }
+        }
+        return state;
+    }
+    clearState() {
+        const storage = this.getStorage();
+        if (!storage)
+            return;
+        storage.removeItem(this.getStorageKey());
+    }
+    async tryRestoreSession(handlers) {
+        const state = this.loadState();
+        if (!state)
+            return false;
+        // Restore state and show iframes IMMEDIATELY — don't wait for subscribe
+        this.sessionToken = state.token;
+        this.sessionExpiresAt = state.expiresAt
+            ? new Date(state.expiresAt)
+            : undefined;
+        this.mainUrl = state.mainUrl;
+        this.mainToken = state.mainToken;
+        this.forkQueue = state.forkQueue;
+        this.currentFork = state.currentFork;
+        // Restore UI state if fork display mode is consistent with current options
+        if (state.forkDisplayMode === this.forkDisplay.mode) {
+            if (this.forkDisplay.mode === "side-by-side") {
+                this.splitPercentage = state.splitPercentage;
+            }
+            // Dialog collapsed state is already captured by currentFork/forkQueue
+        }
+        if (this.mainUrl && this.mainIframe) {
+            const newSrc = getIframeSrc(this.mainUrl, this.mainToken);
+            if (this.mainIframe.src !== newSrc) {
+                this.mainIframe.src = newSrc;
+            }
+            this.showIframe(this.mainIframe);
+        }
+        if (this.currentFork && this.forkIframe) {
+            this.updateForkIframe();
+        }
+        // Update visibility for the current display mode — must run even when
+        // currentFork is null so that collapsed-state UI (expand buttons) renders
+        if (this.forkDisplay.mode === "dialog") {
+            this.updateDialogVisibility();
+        }
+        else {
+            this.updateSideBySideVisibility();
+        }
+        // Now reconnect the stream — if it fails, reset everything and fall through
+        try {
+            await this.client.subscribe(state.token, handlers);
+            // Fire synthetic STATUS_RUNNING so consumers don't need to distinguish
+            // hydration from a fresh start
+            handlers.onSession?.({ status: "STATUS_RUNNING" });
+        }
+        catch {
+            this.clearState();
+            this.sessionToken = null;
+            this.sessionExpiresAt = undefined;
+            this.mainUrl = null;
+            this.mainToken = undefined;
+            this.forkQueue = [];
+            this.currentFork = null;
+            if (this.mainIframe) {
+                this.mainIframe.src = "about:blank";
+                this.mainIframe.classList.remove("mb-adapt__iframe--visible");
+            }
+            if (this.forkIframe) {
+                this.forkIframe.src = "about:blank";
+                this.forkIframe.classList.remove("mb-adapt__iframe--visible");
+                this.forkIframe.classList.add("mb-adapt__iframe--hidden");
+            }
+            if (this.forkDisplay.mode === "side-by-side") {
+                this.updateSideBySideVisibility();
+            }
+            else {
+                this.updateDialogVisibility();
+            }
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Clear persisted state, stop current session, and reinitialize fresh.
+     */
+    async newSession() {
+        this.clearState();
+        // Stop current session best-effort
+        if (this.sessionToken) {
+            this.client.stop(this.sessionToken).catch(() => { });
+        }
+        await this.client.unsubscribe();
+        // Reset internal state
+        this.mainUrl = null;
+        this.mainToken = undefined;
+        this.forkQueue = [];
+        this.currentFork = null;
+        this.sessionToken = null;
+        this.sessionExpiresAt = undefined;
+        this.lastForkActive = null;
+        // Reset iframes
+        if (this.mainIframe) {
+            this.mainIframe.src = "about:blank";
+            this.mainIframe.classList.remove("mb-adapt__iframe--visible");
+        }
+        if (this.forkIframe) {
+            this.forkIframe.src = "about:blank";
+            this.forkIframe.classList.remove("mb-adapt__iframe--visible");
+            this.forkIframe.classList.add("mb-adapt__iframe--hidden");
+        }
+        // Reset visual state
+        this.removeStoppedPlaceholder();
+        if (this.forkDisplay.mode === "side-by-side") {
+            this.updateSideBySideVisibility();
+        }
+        else {
+            this.updateDialogVisibility();
+        }
+        // Reinitialize
+        await this.init();
+    }
     async destroy() {
         this.destroyed = true;
         // Clean up Cap.js widget if present
         this.destroyCapWidget();
-        // We stop best-effort. Sometimes you will get perm denied etc...
-        if (this.sessionToken) {
+        // Stop session on destroy — but NOT when persist has saved state (session survives page refresh).
+        // If persisted state was cleared (explicit stop, terminal status), stop() is still called.
+        if (this.sessionToken && !this.loadState()) {
             this.client.stop(this.sessionToken).catch(() => { });
         }
         await this.client.unsubscribe();
@@ -1255,10 +1499,12 @@ export class AdaptWebClient {
         const fork = msg.fork || "";
         if (msg.stopped) {
             this.handleStoppedMessage(fork);
+            this.saveState();
             return;
         }
         if (msg.done) {
             this.handleDoneMessage(fork);
+            this.saveState();
             return;
         }
         if (!msg.url)
@@ -1271,6 +1517,7 @@ export class AdaptWebClient {
             // Fork URL - should open dialog
             this.handleForkUrl(msg.url, msg.token, fork);
         }
+        this.saveState();
     }
     handleSessionComplete() {
         // Clear all forks and minimize to show only main frame
@@ -1400,6 +1647,7 @@ export class AdaptWebClient {
         else {
             this.updateSideBySideVisibility();
         }
+        this.saveState();
     }
     updateMainIframe() {
         if (!this.rootElement || !this.mainUrl || !this.mainIframe)
@@ -1510,6 +1758,7 @@ export class AdaptWebClient {
                 this.splitPercentage = 50;
             }
             this.updateSideBySideVisibility();
+            this.saveState();
         });
         this.wrapperElement.appendChild(this.mainFrameElement);
         this.wrapperElement.appendChild(this.forkFrameElement);
@@ -1682,6 +1931,7 @@ export class AdaptWebClient {
             this.currentFork = null;
             this.updateDialogVisibility();
         }
+        this.saveState();
     }
     handleForkExit() {
         if (!this.currentFork)
@@ -1711,6 +1961,7 @@ export class AdaptWebClient {
                 this.updateDialogVisibility();
             }
         }
+        this.saveState();
     }
     createDialogStructure() {
         if (this.mainContainer)
@@ -1849,4 +2100,3 @@ export class AdaptWebClient {
 AdaptWebClient.COLLAPSE_THRESHOLD = 15;
 AdaptWebClient.RESPONSIVE_BREAKPOINT = 900; // px - below this, auto-collapse to single view
 AdaptWebClient.DIALOG_FULLSCREEN_BREAKPOINT = 639; // px - at or below this, dialog is fullscreen
-//# sourceMappingURL=index.js.map

package/dist/esm/types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=types.js.map

package/dist/types/AdaptAutomationElement.d.ts

@@ -1,4 +1,4 @@
-import type { AdaptWebClientOptions, CapWidgetOptions, Output, SignalValue, StatusJson } from "./types.js";
+import type { AdaptWebClientOptions, CapWidgetOptions, Output, PersistOptions, SignalValue, StatusJson } from "./types.js";
 /**
  * `<adapt-automation>` custom element for embedding Adapt automations.
  *
@@ -33,6 +33,7 @@ export declare class AdaptAutomationElement extends BaseElement {
     } | undefined;
     classNames: AdaptWebClientOptions["classNames"];
     styles: Partial<CSSStyleDeclaration> | undefined;
+    persistOptions: PersistOptions | undefined;
     onSessionCallback: ((status: StatusJson, fork?: string) => void) | undefined;
     onOutputCallback: ((output: Output) => void) | undefined;
     onForkActiveCallback: ((active: boolean) => void) | undefined;
@@ -48,6 +49,12 @@ export declare class AdaptAutomationElement extends BaseElement {
     set dialogBackdropClose(v: boolean);
     get dialogResizeToContent(): boolean;
     set dialogResizeToContent(v: boolean);
+    get persist(): boolean;
+    set persist(v: boolean);
+    /**
+     * Clear persisted state, stop current session, and reinitialize fresh.
+     */
+    newSession(): Promise<void>;
     connectedCallback(): void;
     disconnectedCallback(): void;
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;

package/dist/types/index.d.ts

@@ -6,7 +6,7 @@ declare global {
 import { configure, resetConfig } from "@mochabug/adapt-core";
 import { createConnectClient } from "@mochabug/adapt-core/connect";
 import type { AdaptWebClientOptions } from "./types.js";
-export type { AdaptWebClientOptions, CapWidgetI18n, CapWidgetOptions, ChallengeInfo, ForkDisplay, Output, RedeemedChallenge, SignalValue, StatusJson, } from "./types.js";
+export type { AdaptWebClientOptions, CapWidgetI18n, CapWidgetOptions, ChallengeInfo, ForkDisplay, Output, PersistOptions, RedeemedChallenge, SignalValue, StatusJson, } from "./types.js";
 export { AdaptCapWidget, type AdaptCapWidgetOptions, } from "./AdaptCapWidget.js";
 export { createChallenge, redeemChallenge } from "./cap-adapter.js";
 export type { SignalData } from "@mochabug/adapt-core";
@@ -27,6 +27,14 @@ export interface AdaptAutoResizingMessage {
     type: "adapt-autoResizing";
     autoResizing: boolean;
 }
+/**
+ * Clear persisted session state for a given automation ID.
+ * Use this to force a fresh session on next page load.
+ *
+ * @param automationId - The automation ID whose state to clear
+ * @param storage - Which storage to clear: 'session' (default), 'local', or 'both'
+ */
+export declare function clearPersistedState(automationId: string, storage?: "session" | "local" | "both"): void;
 /**
  * Browser client for rendering Adapt automation sessions in iframes.
  *
@@ -73,6 +81,7 @@ export declare class AdaptWebClient {
     private forkDisplay;
     private destroyed;
     private lastForkActive;
+    private sessionExpiresAt;
     private stoppedPlaceholder;
     private capWidgetInstance;
     constructor(options: AdaptWebClientOptions);
@@ -126,6 +135,17 @@ export declare class AdaptWebClient {
      * Destroy the Cap.js widget instance if present.
      */
     private destroyCapWidget;
+    private resolvePersistOptions;
+    private getStorageKey;
+    private getStorage;
+    private saveState;
+    private loadState;
+    private clearState;
+    private tryRestoreSession;
+    /**
+     * Clear persisted state, stop current session, and reinitialize fresh.
+     */
+    newSession(): Promise<void>;
     destroy(): Promise<void>;
     private onUrl;
     private handleSessionComplete;

package/dist/types/types.d.ts

@@ -1,5 +1,14 @@
 import type { Output, SignalValue, StatusJson } from "@mochabug/adapt-core";
 export type { Output, SignalValue, StatusJson } from "@mochabug/adapt-core";
+/**
+ * Options for session persistence across page refreshes.
+ */
+export interface PersistOptions {
+    /** Storage type: 'session' (default) uses sessionStorage, 'local' uses localStorage. */
+    storage?: "session" | "local";
+    /** Max TTL in seconds (default: 3600). Capped by the session's own expiresAt. */
+    ttl?: number;
+}
 /**
  * Discriminated union for fork display configuration.
  *
@@ -374,4 +383,16 @@ export interface AdaptWebClientOptions {
      * ```
      */
     styles?: Partial<CSSStyleDeclaration>;
+    /**
+     * Enable session persistence across page refreshes.
+     *
+     * When enabled, the session token and URL state are stored in browser storage.
+     * On page load, the client reconnects to the existing session instead of creating a new one.
+     *
+     * - `true` — use sessionStorage with 3600s TTL
+     * - `PersistOptions` — customize storage type and TTL
+     *
+     * @default undefined (disabled)
+     */
+    persist?: boolean | PersistOptions;
 }