@weave-apps/sdk 0.1.6 → 0.1.8

package/README.md

@@ -11,6 +11,8 @@ Official SDK for building third-party applications for the Weave Platform.
 - ✅ **DOM API** - Secure parent page DOM manipulation
 - ✅ **Shadow DOM Isolation** - Scoped styles and encapsulation
 - ✅ **Background Services** - Run code without user interaction
+- ✅ **State Persistence** - Survive page reloads with auto-persist
+- ✅ **Multi-Page Flows** - Pending operations across navigations
 - ✅ **Form Integration** - Auto-fill forms with extracted data
 - ✅ **AI Integration** - Leverage AI for smart form filling
 - ✅ **Data Persistence** - Store app data with the Weave API
@@ -124,6 +126,8 @@ constructor(appInfo: WeaveAppInfo)
 - `description` (string) - Detailed description
 - `author` (string) - Author name
 - `tags` (string[])` - Optional tags
+- `persistState` (boolean) - Enable auto-persist across page reloads (default: false)
+- `persistDebounce` (number) - Debounce delay in ms for state saves (default: 100)
 
 #### Settings & State
 
@@ -223,12 +227,35 @@ this.renderHTML('<h1>Hello</h1>');
 ```
 
 ##### `setState(updates: object): void`
-Update app state (shallow merge).
+Update app state (shallow merge). If `persistState: true`, state is automatically saved to background service.
 
 ```typescript
 this.setState({ isLoading: true, count: 5 });
 ```
 
+##### `this.background` (Property)
+Access the background API for state persistence and pending operations.
+
+```typescript
+// Save state manually
+await this.background?.saveState({ count: 5 });
+
+// Load state manually
+const state = await this.background?.loadState();
+
+// Set pending operation before navigation
+await this.background?.setPendingOperation({
+  type: 'fill-form',
+  data: { content: '...' }
+});
+
+// Get pending operation after navigation
+const pending = await this.background?.getPendingOperation();
+
+// Clear pending operation
+await this.background?.clearPendingOperation();
+```
+
 ##### `query<T>(selector: string): T | null`
 Query a single element in shadow root.
 
@@ -376,21 +403,86 @@ const markdown = window.weaveAPI.utils.htmlToMarkdown(htmlString);
 const html = window.weaveAPI.utils.markdownToHtml(markdownString);
 ```
 
-## Real-World Example: Heidi to DCP
+## Advanced Topics
+
+### State Persistence (Survive Page Reloads)
 
-The included `DemoWeaveHeidiDcp` app demonstrates advanced features:
+Apps can persist state across page reloads using the background state service. There are two approaches:
 
-- **Background Services** - Injects button on Heidi scribe pages
-- **URL Monitoring** - Reacts to SPA navigation
-- **DOM Injection** - Adds UI elements to parent page
-- **Form Detection** - Captures form structure and data
-- **Data Persistence** - Stores consultation notes
-- **AI Integration** - Auto-fills forms using AI
-- **State Management** - Multi-stage workflow (idle → select-form → confirm → filling → success)
+#### Auto-Persist (Recommended)
 
-Check `src/app.ts` for the complete implementation.
+Simply set `persistState: true` in your app config. State is automatically saved on every `setState()` call and restored when the app initializes after a page reload.
 
-## Advanced Topics
+```typescript
+class MyApp extends WeaveBaseApp<Settings, State> {
+  constructor() {
+    super({
+      id: 'my-app',
+      name: 'My App',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'App with persistent state',
+      author: 'Your Name',
+      persistState: true,      // Enable auto-persist
+      persistDebounce: 100,    // Optional: debounce delay (default 100ms)
+    });
+    
+    this.state = { count: 0, items: [] };
+  }
+  
+  async onBackgroundService() {
+    // State is already restored automatically!
+    console.log('Restored count:', this.state.count);
+  }
+  
+  handleIncrement() {
+    // Automatically saved to background service
+    this.setState({ count: this.state.count + 1 });
+  }
+}
+```
+
+#### Multi-Page Flows (Pending Operations)
+
+For operations that span multiple pages (e.g., extract data on page A, fill form on page B), use pending operations:
+
+```typescript
+class DataTransferApp extends WeaveBaseApp {
+  async handleTransferClick() {
+    // Save pending operation BEFORE navigation
+    await this.background?.setPendingOperation({
+      type: 'fill-form',
+      data: {
+        content: this.state.extractedContent,
+        targetForm: 'patient-notes'
+      },
+      targetUrl: 'https://target-system.com/form'
+    });
+    
+    // Navigate to target page
+    window.open('https://target-system.com/form', '_self');
+  }
+  
+  async onBackgroundService() {
+    // Check for pending operation after page loads
+    const pending = await this.background?.getPendingOperation();
+    
+    if (pending?.type === 'fill-form') {
+      const pageUrl = await window.weaveDOM.getPageUrl();
+      
+      // Verify we're on the right page
+      if (pageUrl.includes('target-system.com/form')) {
+        await this.fillForm(pending.data);
+        await this.background?.clearPendingOperation();
+      }
+    }
+  }
+}
+```
+
+#### State TTL
+
+Persisted state expires after **5 minutes** by default. This prevents stale state from accumulating.
 
 ### Settings & Configuration
 
@@ -493,6 +585,9 @@ Check that selectors match the actual form structure. Use browser DevTools to in
 ### Button not injecting
 Verify the target selector exists before injection attempt. Check browser console for errors.
 
-### State not persisting
-Use `this.weaveAPI.appData.*` methods to persist data to backend. In-memory state is lost on refresh.
+### State not persisting across page reloads
+Enable `persistState: true` in your app config. State will automatically save on `setState()` and restore on page reload.
+
+### State not persisting long-term
+Use `this.weaveAPI.appData.*` methods to persist data to backend. Background state only lasts 5 minutes.
 

package/dist/WeaveBackgroundAPI.d.ts

@@ -0,0 +1,81 @@
+/**
+ * WeaveBackgroundAPI
+ *
+ * Client-side API for Weave apps to interact with the background state service.
+ * Allows apps to persist state across page reloads and manage multi-page operations.
+ *
+ * Usage:
+ * ```typescript
+ * // Save state (survives page reload)
+ * await weaveAPI.background.saveState({ count: 5, items: [...] });
+ *
+ * // Load state after page reload
+ * const state = await weaveAPI.background.loadState();
+ *
+ * // Set pending operation before navigation
+ * await weaveAPI.background.setPendingOperation({
+ *   type: 'fill-form',
+ *   data: { content: '...' },
+ *   targetUrl: 'https://example.com/form'
+ * });
+ *
+ * // Check for pending operation after navigation
+ * const pending = await weaveAPI.background.getPendingOperation();
+ * ```
+ */
+/**
+ * Pending operation for multi-page flows
+ */
+export interface PendingOperation {
+    type: string;
+    data: any;
+    targetUrl?: string;
+}
+/**
+ * WeaveBackgroundAPI class
+ *
+ * Provides methods for apps to interact with background state service.
+ * Each app instance gets its own API instance with its appId.
+ */
+export declare class WeaveBackgroundAPI {
+    private appId;
+    constructor(appId: string);
+    /**
+     * Save app state to background service
+     * State survives page reloads within the browser session
+     *
+     * @param state - The state object to save
+     */
+    saveState(state: any): Promise<void>;
+    /**
+     * Load app state from background service
+     * Returns null if no state exists or if it has expired
+     *
+     * @returns The saved state or null
+     */
+    loadState<T = any>(): Promise<T | null>;
+    /**
+     * Clear app state from background service
+     */
+    clearState(): Promise<void>;
+    /**
+     * Set a pending operation for multi-page flows
+     * Use this before triggering navigation to save context
+     *
+     * @param operation - The operation to save
+     */
+    setPendingOperation(operation: PendingOperation): Promise<void>;
+    /**
+     * Get pending operation after navigation
+     * Returns null if no pending operation exists
+     *
+     * @returns The pending operation or null
+     */
+    getPendingOperation(): Promise<PendingOperation | null>;
+    /**
+     * Clear pending operation
+     * Call this after successfully handling the pending operation
+     */
+    clearPendingOperation(): Promise<void>;
+}
+//# sourceMappingURL=WeaveBackgroundAPI.d.ts.map

package/dist/WeaveBackgroundAPI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WeaveBackgroundAPI.d.ts","sourceRoot":"","sources":["../src/WeaveBackgroundAPI.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAWH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,GAAG,CAAC;IACV,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4FD;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,KAAK,CAAS;gBAEV,KAAK,EAAE,MAAM;IAIzB;;;;;OAKG;IACG,SAAS,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C;;;;;OAKG;IACG,SAAS,CAAC,CAAC,GAAG,GAAG,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAO7C;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAMjC;;;;;OAKG;IACG,mBAAmB,CAAC,SAAS,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOrE;;;;;OAKG;IACG,mBAAmB,IAAI,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAO7D;;;OAGG;IACG,qBAAqB,IAAI,OAAO,CAAC,IAAI,CAAC;CAK7C"}

package/dist/WeaveBackgroundAPI.js

@@ -0,0 +1,165 @@
+/**
+ * WeaveBackgroundAPI
+ *
+ * Client-side API for Weave apps to interact with the background state service.
+ * Allows apps to persist state across page reloads and manage multi-page operations.
+ *
+ * Usage:
+ * ```typescript
+ * // Save state (survives page reload)
+ * await weaveAPI.background.saveState({ count: 5, items: [...] });
+ *
+ * // Load state after page reload
+ * const state = await weaveAPI.background.loadState();
+ *
+ * // Set pending operation before navigation
+ * await weaveAPI.background.setPendingOperation({
+ *   type: 'fill-form',
+ *   data: { content: '...' },
+ *   targetUrl: 'https://example.com/form'
+ * });
+ *
+ * // Check for pending operation after navigation
+ * const pending = await weaveAPI.background.getPendingOperation();
+ * ```
+ */
+// Request timeout in ms
+const REQUEST_TIMEOUT = 5000;
+// Counter for unique request IDs
+let requestIdCounter = 0;
+// Pending requests waiting for response
+const pendingRequests = new Map();
+// Flag to track if listener is set up
+let listenerInitialized = false;
+/**
+ * Initialize the response listener (called once)
+ */
+function initializeListener() {
+    if (listenerInitialized)
+        return;
+    listenerInitialized = true;
+    window.addEventListener('message', (event) => {
+        const message = event.data;
+        // Only handle background state responses
+        if (message?.type !== 'BG_STATE_RESPONSE')
+            return;
+        const pending = pendingRequests.get(message.requestId);
+        if (!pending)
+            return;
+        // Clear timeout and remove from pending
+        clearTimeout(pending.timeout);
+        pendingRequests.delete(message.requestId);
+        if (message.success) {
+            pending.resolve({
+                state: message.state,
+                operation: message.operation,
+            });
+        }
+        else {
+            pending.reject(new Error(message.error || 'Unknown error'));
+        }
+    });
+}
+/**
+ * Send a message to the background state service via content script
+ */
+async function sendMessage(type, payload) {
+    // Initialize listener on first use
+    initializeListener();
+    const requestId = `bg-${++requestIdCounter}-${Date.now()}`;
+    return new Promise((resolve, reject) => {
+        // Set up timeout
+        const timeout = setTimeout(() => {
+            pendingRequests.delete(requestId);
+            reject(new Error(`Background state request timed out: ${type}`));
+        }, REQUEST_TIMEOUT);
+        // Store pending request
+        pendingRequests.set(requestId, { resolve, reject, timeout });
+        // Send message to content script (which forwards to background)
+        window.parent.postMessage({
+            type,
+            requestId,
+            payload,
+        }, '*');
+    });
+}
+/**
+ * WeaveBackgroundAPI class
+ *
+ * Provides methods for apps to interact with background state service.
+ * Each app instance gets its own API instance with its appId.
+ */
+export class WeaveBackgroundAPI {
+    constructor(appId) {
+        this.appId = appId;
+    }
+    /**
+     * Save app state to background service
+     * State survives page reloads within the browser session
+     *
+     * @param state - The state object to save
+     */
+    async saveState(state) {
+        await sendMessage('BG_SAVE_STATE', {
+            appId: this.appId,
+            state,
+        });
+    }
+    /**
+     * Load app state from background service
+     * Returns null if no state exists or if it has expired
+     *
+     * @returns The saved state or null
+     */
+    async loadState() {
+        const response = await sendMessage('BG_LOAD_STATE', {
+            appId: this.appId,
+        });
+        return response.state;
+    }
+    /**
+     * Clear app state from background service
+     */
+    async clearState() {
+        await sendMessage('BG_CLEAR_STATE', {
+            appId: this.appId,
+        });
+    }
+    /**
+     * Set a pending operation for multi-page flows
+     * Use this before triggering navigation to save context
+     *
+     * @param operation - The operation to save
+     */
+    async setPendingOperation(operation) {
+        await sendMessage('BG_SET_PENDING_OP', {
+            appId: this.appId,
+            operation,
+        });
+    }
+    /**
+     * Get pending operation after navigation
+     * Returns null if no pending operation exists
+     *
+     * @returns The pending operation or null
+     */
+    async getPendingOperation() {
+        const response = await sendMessage('BG_GET_PENDING_OP', {
+            appId: this.appId,
+        });
+        return response.operation;
+    }
+    /**
+     * Clear pending operation
+     * Call this after successfully handling the pending operation
+     */
+    async clearPendingOperation() {
+        await sendMessage('BG_CLEAR_PENDING_OP', {
+            appId: this.appId,
+        });
+    }
+}
+// Export for global usage
+if (typeof window !== 'undefined') {
+    window.WeaveBackgroundAPI = WeaveBackgroundAPI;
+}

package/dist/WeaveBaseApp.d.ts

@@ -10,7 +10,6 @@
  * interface MyAppSettings {
  *   apiKey: string;
  *   endpoint: string;
- *   autoSave?: boolean;
  * }
  *
  * interface MyAppState {
@@ -28,7 +27,9 @@
  *       category: 'utility',
  *       description: 'My custom app',
  *       author: 'Your Name',
- *       tags: ['custom']
+ *       tags: ['custom'],
+ *       // Enable auto-persist to survive page reloads
+ *       persistState: true,
  *     });
  *
  *     // Settings are now type-safe!
@@ -47,7 +48,7 @@
  *   }
  *
  *   setupEventListeners() {
- *     // setState is also type-safe
+ *     // setState is also type-safe and auto-persists if enabled
  *     this.setState({ count: this.state.count + 1 }); // ✅ Type-safe
  *   }
  * }
@@ -55,6 +56,8 @@
  * customElements.define('my-app', MyApp);
  * ```
  */
+import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+export type { PendingOperation } from './WeaveBackgroundAPI';
 /**
  * App metadata configuration
  */
@@ -73,6 +76,19 @@ export interface WeaveAppInfo {
     author: string;
     /** Additional tags for search and categorization */
     tags?: string[];
+    /**
+     * Enable automatic state persistence across page reloads.
+     * When true, state is automatically saved to background service on each setState() call.
+     * State is restored when the app initializes after a page reload.
+     * @default false
+     */
+    persistState?: boolean;
+    /**
+     * Debounce delay for state persistence in milliseconds.
+     * Prevents excessive saves when state changes rapidly.
+     * @default 100
+     */
+    persistDebounce?: number;
 }
 /**
  * Base class for Weave apps
@@ -90,11 +106,24 @@ export declare abstract class WeaveBaseApp<TSettings = Record<string, any>, TSta
     private _shadowRoot;
     /** App-specific API client instance (prevents app ID conflicts) */
     protected weaveAPI: any;
+    /** Background API for state persistence */
+    private _backgroundAPI;
+    /** Debounced persist function */
+    private _debouncedPersist;
+    /** Flag to track if state has been restored */
+    private _stateRestored;
+    /** App UUID from registry */
+    private _appUuid;
     /**
      * Creates a new Weave app
      * @param appInfo - App metadata configuration
      */
     constructor(appInfo: WeaveAppInfo);
+    /**
+     * Get the background API for state persistence and pending operations
+     * Use this for manual state management or multi-page flows
+     */
+    protected get background(): WeaveBackgroundAPI | null;
     /**
      * Get shadow root (override native property)
      */
@@ -159,8 +188,19 @@ export declare abstract class WeaveBaseApp<TSettings = Record<string, any>, TSta
     setAppConfig(_config: Record<string, any>): void;
     /**
      * Helper: Update app state
+     * If persistState is enabled, state is automatically saved to background service
      */
     protected setState(updates: Partial<TState>): void;
+    /**
+     * Persist current state to background service
+     * Called automatically when persistState is enabled
+     */
+    private _persistState;
+    /**
+     * Restore state from background service
+     * Called by BackgroundAppManager during initialization
+     */
+    restoreState(): Promise<boolean>;
     /**
      * Helper: Render HTML into shadow root
      */

package/dist/WeaveBaseApp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WeaveBaseApp.d.ts","sourceRoot":"","sources":["../src/WeaveBaseApp.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAEH;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;GAIG;AACH,8BAAsB,YAAY,CAChC,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAC/B,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAC5B,SAAQ,WAAW;IACnB,mBAAmB;IACnB,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC;IAEhC,2CAA2C;IAC3C,SAAS,CAAC,WAAW,CAAC,EAAE,SAAS,CAAC;IAElC,gDAAgD;IAChD,SAAS,CAAC,KAAK,EAAE,MAAM,CAAgB;IAEvC,sCAAsC;IACtC,OAAO,CAAC,WAAW,CAAa;IAEhC,mEAAmE;IACnE,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC;IAExB;;;OAGG;gBACS,OAAO,EAAE,YAAY;IAyCjC;;OAEG;IACH,IAAI,UAAU,IAAI,UAAU,CAE3B;IAED;;;;OAIG;IACH,SAAS,CAAC,mBAAmB,CAAC,IAAI,IAAI;IAEtC;;;;OAIG;IACH,SAAS,CAAC,WAAW,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAEzC;;;OAGG;IACH,SAAS,CAAC,MAAM,IAAI,IAAI;IAIxB;;OAEG;IACH,SAAS,CAAC,mBAAmB,IAAI,IAAI;IAIrC;;;OAGG;IACI,2BAA2B,IAAI,IAAI;IAO1C;;;OAGG;IACI,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAMzC;;;OAGG;IACH,iBAAiB,IAAI,IAAI;IAoBzB;;OAEG;IACH,oBAAoB,IAAI,IAAI;IAI5B;;;OAGG;IACH,SAAS,CAAC,OAAO,IAAI,IAAI;IAIzB;;OAEG;IACI,UAAU,IAAI,YAAY;IAIjC;;OAEG;IACI,WAAW,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC;IAOzC;;;OAGG;IAEI,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI;IAIvD;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI;IAIlD;;OAEG;IACH,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQxC;;OAEG;IACH,SAAS,CAAC,KAAK,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI;IAIxE;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC;CAGjF"}
+{"version":3,"file":"WeaveBaseApp.d.ts","sourceRoot":"","sources":["../src/WeaveBaseApp.ts"],"names":[],"mappings":"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"}

package/dist/WeaveBaseApp.js

@@ -10,7 +10,6 @@
  * interface MyAppSettings {
  *   apiKey: string;
  *   endpoint: string;
- *   autoSave?: boolean;
  * }
  *
  * interface MyAppState {
@@ -28,7 +27,9 @@
  *       category: 'utility',
  *       description: 'My custom app',
  *       author: 'Your Name',
- *       tags: ['custom']
+ *       tags: ['custom'],
+ *       // Enable auto-persist to survive page reloads
+ *       persistState: true,
  *     });
  *
  *     // Settings are now type-safe!
@@ -47,7 +48,7 @@
  *   }
  *
  *   setupEventListeners() {
- *     // setState is also type-safe
+ *     // setState is also type-safe and auto-persists if enabled
  *     this.setState({ count: this.state.count + 1 }); // ✅ Type-safe
  *   }
  * }
@@ -55,6 +56,22 @@
  * customElements.define('my-app', MyApp);
  * ```
  */
+import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
+/**
+ * Simple debounce utility
+ */
+function debounce(fn, delay) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        timeoutId = setTimeout(() => {
+            fn(...args);
+            timeoutId = null;
+        }, delay);
+    };
+}
 /**
  * Base class for Weave apps
  * @template TSettings - Type for app settings, defaults to an empty object
@@ -69,6 +86,14 @@ export class WeaveBaseApp extends HTMLElement {
         super();
         /** App-specific state (override in subclass) */
         this.state = {};
+        /** Background API for state persistence */
+        this._backgroundAPI = null;
+        /** Debounced persist function */
+        this._debouncedPersist = null;
+        /** Flag to track if state has been restored */
+        this._stateRestored = false;
+        /** App UUID from registry */
+        this._appUuid = null;
         // Validate required fields
         if (!appInfo.id || !appInfo.name || !appInfo.version) {
             throw new Error('WeaveBaseApp: id, name, and version are required');
@@ -85,14 +110,24 @@ export class WeaveBaseApp extends HTMLElement {
         if (registryData?.settings) {
             this.appSettings = registryData.settings;
         }
+        // Store app UUID for background API
+        this._appUuid = registryData?.uuid || null;
         // Set app UUID on the global API client so it's included in all requests
         // This allows background services to make API calls without the app being open
         if (window.weaveAPI) {
-            const appUuid = registryData?.uuid;
-            if (appUuid) {
+            if (this._appUuid) {
                 // Create a new API client instance for THIS app
                 this.weaveAPI = new window.WeaveAPIClient();
-                this.weaveAPI.setAppId(appUuid);
+                this.weaveAPI.setAppId(this._appUuid);
+                // Create background API instance for state persistence
+                this._backgroundAPI = new WeaveBackgroundAPI(this._appUuid);
+                // Set up debounced persist if enabled
+                if (appInfo.persistState) {
+                    const delay = appInfo.persistDebounce ?? 100;
+                    this._debouncedPersist = debounce(() => {
+                        this._persistState();
+                    }, delay);
+                }
             }
             else {
                 console.warn('⚠️ App UUID not found in registry - API calls may fail. App:', appInfo.id);
@@ -101,6 +136,13 @@ export class WeaveBaseApp extends HTMLElement {
             }
         }
     }
+    /**
+     * Get the background API for state persistence and pending operations
+     * Use this for manual state management or multi-page flows
+     */
+    get background() {
+        return this._backgroundAPI;
+    }
     /**
      * Get shadow root (override native property)
      */
@@ -195,9 +237,53 @@ export class WeaveBaseApp extends HTMLElement {
     }
     /**
      * Helper: Update app state
+     * If persistState is enabled, state is automatically saved to background service
      */
     setState(updates) {
         this.state = { ...this.state, ...updates };
+        // Auto-persist if enabled
+        if (this.appInfo.persistState && this._debouncedPersist) {
+            this._debouncedPersist();
+        }
+    }
+    /**
+     * Persist current state to background service
+     * Called automatically when persistState is enabled
+     */
+    async _persistState() {
+        if (!this._backgroundAPI)
+            return;
+        try {
+            await this._backgroundAPI.saveState(this.state);
+        }
+        catch (error) {
+            console.error('❌ Failed to persist state:', error);
+        }
+    }
+    /**
+     * Restore state from background service
+     * Called by BackgroundAppManager during initialization
+     */
+    async restoreState() {
+        if (!this._backgroundAPI || !this.appInfo.persistState) {
+            return false;
+        }
+        if (this._stateRestored) {
+            return true; // Already restored
+        }
+        try {
+            const savedState = await this._backgroundAPI.loadState();
+            if (savedState) {
+                this.state = { ...this.state, ...savedState };
+                this._stateRestored = true;
+                console.log('✅ State restored for app:', this.appInfo.id);
+                return true;
+            }
+        }
+        catch (error) {
+            console.error('❌ Failed to restore state:', error);
+        }
+        return false;
     }
     /**
      * Helper: Render HTML into shadow root

package/dist/global.d.ts

@@ -7,6 +7,7 @@
 import { WeaveBaseApp } from './WeaveBaseApp';
 import { WeaveDOMAPI } from './WeaveDOMAPI';
 import { WeaveAPIClient } from './WeaveAPIClient';
+import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
 declare global {
     interface Window {
         WeaveBaseApp: typeof WeaveBaseApp;
@@ -14,6 +15,7 @@ declare global {
         weaveDOM: WeaveDOMAPI;
         WeaveAPIClient: typeof WeaveAPIClient;
         weaveAPI: WeaveAPIClient;
+        WeaveBackgroundAPI: typeof WeaveBackgroundAPI;
     }
 }
 //# sourceMappingURL=global.d.ts.map

package/dist/global.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIlD,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,YAAY,EAAE,OAAO,YAAY,CAAC;QAClC,WAAW,EAAE,OAAO,WAAW,CAAC;QAChC,QAAQ,EAAE,WAAW,CAAC;QACtB,cAAc,EAAE,OAAO,cAAc,CAAC;QACtC,QAAQ,EAAE,cAAc,CAAC;KAAG;CAC/B"}
+{"version":3,"file":"global.d.ts","sourceRoot":"","sources":["../src/global.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAG1D,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,YAAY,EAAE,OAAO,YAAY,CAAC;QAClC,WAAW,EAAE,OAAO,WAAW,CAAC;QAChC,QAAQ,EAAE,WAAW,CAAC;QACtB,cAAc,EAAE,OAAO,cAAc,CAAC;QACtC,QAAQ,EAAE,cAAc,CAAC;QACzB,kBAAkB,EAAE,OAAO,kBAAkB,CAAC;KAAG;CACpD"}

package/dist/global.js

@@ -9,9 +9,11 @@ import { WeaveDOMAPI } from './WeaveDOMAPI';
 import weavekDOM from './WeaveDOMAPI';
 import { WeaveAPIClient } from './WeaveAPIClient';
 import weaveAPI from './WeaveAPIClient';
+import { WeaveBackgroundAPI } from './WeaveBackgroundAPI';
 // Make SDK available globally
 window.WeaveBaseApp = WeaveBaseApp;
 window.WeaveDOMAPI = WeaveDOMAPI;
 window.weaveDOM = weavekDOM;
 window.WeaveAPIClient = WeaveAPIClient;
 window.weaveAPI = weaveAPI;
+window.WeaveBackgroundAPI = WeaveBackgroundAPI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weave-apps/sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "SDK for building Weave Micro Apps",
   "publishConfig": {
     "access": "public"

package/scripts/copy-sdk-files.js

@@ -16,6 +16,7 @@ const filesToCopy = [
   'WeaveBaseApp.ts',
   'WeaveDOMAPI.ts',
   'WeaveAPIClient.ts',
+  'WeaveBackgroundAPI.ts',
   'global.ts',
   'app-template.js',
   'README.md',

package/templates/WEAVE_SPEC.md

@@ -1083,12 +1083,14 @@ customElements.define('smart-form-assistant', SmartFormAssistant);
 ### Key Takeaways
 
 1. **Single Instance Architecture**: One app instance serves both background and foreground
-2. **Persistent State**: `this.state` persists across open/close cycles
-3. **Background Service**: `onBackgroundService()` runs immediately, before DOM attachment
-4. **URL Monitoring**: `onUrlChange()` detects SPA navigation automatically
-5. **Shared Context**: Background and foreground share the same instance and state
-6. **DOM Check**: Use `this.isConnected` to check if app is attached to DOM
-7. **No User Interaction Required**: Apps can run and inject UI automatically
+2. **Persistent State**: `this.state` persists across open/close cycles (within session)
+3. **Page Reload Survival**: Enable `persistState: true` to survive page reloads
+4. **Multi-Page Flows**: Use `this.background?.setPendingOperation()` for cross-page operations
+5. **Background Service**: `onBackgroundService()` runs immediately, before DOM attachment
+6. **URL Monitoring**: `onUrlChange()` detects SPA navigation automatically
+7. **Shared Context**: Background and foreground share the same instance and state
+8. **DOM Check**: Use `this.isConnected` to check if app is attached to DOM
+9. **No User Interaction Required**: Apps can run and inject UI automatically
 
 ### Helper Methods (Available in `this`)
 
@@ -1102,7 +1104,7 @@ this.query<T>(selector: string): T | null
 // Query all elements in shadow root
 this.queryAll<T>(selector: string): NodeListOf<T>
 
-// Update app state
+// Update app state (auto-persists if persistState: true)
 this.setState(updates: object): void
 
 // Access current state
@@ -1113,8 +1115,263 @@ this.appInfo: WeaveAppInfo
 
 // Access shadow root
 this.shadowRoot: ShadowRoot
+
+// Access background API for state persistence
+this.background: WeaveBackgroundAPI | null
 ```
 
+## State Persistence (Survive Page Reloads)
+
+### Overview
+
+Apps can persist state across **page reloads** using the background state service. This is different from `weaveAPI.appData` which persists to the backend database - background state is stored in the browser extension's memory and survives page navigations within the same browser session.
+
+**Use Cases:**
+- 🔄 **Survive page reloads** - State persists when user refreshes the page
+- 📋 **Multi-page flows** - Extract data on page A, fill form on page B
+- 🔀 **Handle redirects** - Continue operation after OAuth redirect or form submission
+- 💾 **Temporary state** - Store data that doesn't need long-term persistence
+
+### Auto-Persist (Recommended)
+
+The simplest approach is to enable `persistState: true` in your app config. State is automatically:
+- **Saved** on every `setState()` call (debounced)
+- **Restored** when the app initializes after a page reload
+
+```typescript
+class PersistentCounterApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'persistent-counter',
+      name: 'Persistent Counter',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Counter that survives page reloads',
+      author: 'Your Name',
+      
+      // ✅ Enable auto-persist
+      persistState: true,
+      
+      // Optional: debounce delay in ms (default: 100)
+      persistDebounce: 100,
+    });
+    
+    this.state = {
+      count: 0,
+      lastUpdated: null
+    };
+  }
+  
+  async onBackgroundService() {
+    // ✅ State is already restored automatically!
+    console.log('Restored count:', this.state.count);
+    console.log('Last updated:', this.state.lastUpdated);
+  }
+  
+  handleIncrement() {
+    // ✅ Automatically saved to background service
+    this.setState({ 
+      count: this.state.count + 1,
+      lastUpdated: new Date().toISOString()
+    });
+    
+    if (this.isConnected) {
+      this.render();
+    }
+  }
+  
+  render() {
+    this.renderHTML(`
+      <div class="p-4">
+        <p>Count: <strong>${this.state.count}</strong></p>
+        <p>Last updated: ${this.state.lastUpdated || 'Never'}</p>
+        <button id="increment" class="bg-blue-500 text-white px-4 py-2 rounded">
+          Increment
+        </button>
+        <p class="text-gray-500 text-sm mt-4">
+          Refresh the page - count will persist!
+        </p>
+      </div>
+    `);
+  }
+  
+  setupEventListeners() {
+    this.query('#increment')?.addEventListener('click', () => {
+      this.handleIncrement();
+    });
+  }
+}
+
+customElements.define('persistent-counter', PersistentCounterApp);
+```
+
+### Manual State Management
+
+For more control, use the `this.background` API directly:
+
+```typescript
+class ManualStateApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'manual-state-app',
+      name: 'Manual State App',
+      version: '1.0.0',
+      category: 'utility',
+      description: 'Manual state management',
+      author: 'Your Name',
+      // Note: persistState is false (default)
+    });
+    
+    this.state = { data: null };
+  }
+  
+  async saveImportantData(data: any) {
+    // Manually save state
+    await this.background?.saveState({ importantData: data });
+  }
+  
+  async loadSavedData() {
+    // Manually load state
+    const saved = await this.background?.loadState();
+    if (saved?.importantData) {
+      this.state.data = saved.importantData;
+    }
+  }
+  
+  async clearSavedData() {
+    // Clear saved state
+    await this.background?.clearState();
+  }
+}
+```
+
+### Multi-Page Flows (Pending Operations)
+
+For operations that span multiple pages, use **pending operations**. This is perfect for:
+- Extract data on page A → Fill form on page B
+- Click button → Handle redirect → Continue operation
+- OAuth flows → Return and continue
+
+```typescript
+class DataTransferApp extends WeaveBaseApp {
+  constructor() {
+    super({
+      id: 'data-transfer-app',
+      name: 'Data Transfer App',
+      version: '1.0.0',
+      category: 'integration',
+      description: 'Transfer data between pages',
+      author: 'Your Name',
+    });
+    
+    this.state = {
+      extractedContent: null,
+      transferInProgress: false
+    };
+  }
+  
+  async onBackgroundService() {
+    // Check for pending operation after page loads
+    const pending = await this.background?.getPendingOperation();
+    
+    if (pending?.type === 'fill-form') {
+      const pageUrl = await window.weaveDOM.getPageUrl();
+      
+      // Verify we're on the target page
+      if (pageUrl.includes(pending.targetUrl || '')) {
+        console.log('✅ On target page, filling form...');
+        await this.fillFormWithData(pending.data);
+        await this.background?.clearPendingOperation();
+      }
+    }
+  }
+  
+  async handleTransferClick() {
+    if (!this.state.extractedContent) {
+      console.error('No content to transfer');
+      return;
+    }
+    
+    // Save pending operation BEFORE navigation
+    await this.background?.setPendingOperation({
+      type: 'fill-form',
+      data: {
+        content: this.state.extractedContent,
+        timestamp: Date.now()
+      },
+      targetUrl: 'target-system.com/form'
+    });
+    
+    // Navigate to target page
+    window.open('https://target-system.com/form', '_self');
+    // Page will reload, but pending operation is saved!
+  }
+  
+  async fillFormWithData(data: any) {
+    // Fill form fields with transferred data
+    await window.weaveDOM.setFormFieldValue('#notes', data.content);
+    console.log('✅ Form filled with transferred data');
+  }
+}
+
+customElements.define('data-transfer-app', DataTransferApp);
+```
+
+### Pending Operation Structure
+
+```typescript
+interface PendingOperation {
+  type: string;       // Operation type (e.g., 'fill-form', 'continue-auth')
+  data: any;          // Operation-specific data
+  targetUrl?: string; // Optional: URL where operation should resume
+}
+```
+
+### Background API Reference
+
+```typescript
+// Available via this.background
+
+// Save state (survives page reload)
+await this.background?.saveState(state: any): Promise<void>
+
+// Load state
+await this.background?.loadState<T>(): Promise<T | null>
+
+// Clear state
+await this.background?.clearState(): Promise<void>
+
+// Set pending operation (for multi-page flows)
+await this.background?.setPendingOperation(op: PendingOperation): Promise<void>
+
+// Get pending operation
+await this.background?.getPendingOperation(): Promise<PendingOperation | null>
+
+// Clear pending operation
+await this.background?.clearPendingOperation(): Promise<void>
+```
+
+### State TTL (Time To Live)
+
+Persisted state expires after **5 minutes** by default. This prevents stale state from accumulating.
+
+For long-term persistence, use `this.weaveAPI.appData.*` methods instead.
+
+### Best Practices
+
+#### ✅ DO:
+- Use `persistState: true` for simple state persistence
+- Use pending operations for multi-page flows
+- Clear pending operations after handling them
+- Check `this.background` exists before calling methods
+- Use background state for temporary/session data
+
+#### ❌ DON'T:
+- Don't use background state for long-term data (use `weaveAPI.appData`)
+- Don't store sensitive data in background state
+- Don't forget to clear pending operations
+- Don't assume state will persist forever (5 min TTL)
+
 ## Weave Backend API
 
 ### ⚠️ CRITICAL: API Access Restrictions