@panda-agent/panda-app-sdk 0.1.0 → 0.4.0

package/dist/browser/index.d.ts

@@ -1,9 +1,11 @@
 export { PANDA_APP_BRIDGE_EVENT, PANDA_APP_BRIDGE_INVOKE, PANDA_APP_BRIDGE_INVOKE_RESULT, } from './protocol.js';
 export { createAppSdk } from './create-app-sdk.js';
 export { createIframeBridgeTransport } from './transport/iframe.js';
+export { newRequestId } from './request-id.browser.js';
 export type * from './types.js';
 export declare const PandaApp: {
-    connectIframe(): {
+    connect: () => {
+        ready: () => Promise<void>;
         auth: {
             getCurrentUser: () => Promise<import("./types.js").AppUser | null>;
         };
@@ -17,6 +19,7 @@ export declare const PandaApp: {
                 scene?: string;
                 preferredModelId?: string;
             }) => Promise<import("./types.js").ModelListItem | null>;
+            chat: (request: import("./types.js").ModelChatRequest) => Promise<import("./types.js").ModelChatResult>;
         };
         workspace: {
             list: (request: {
@@ -28,9 +31,32 @@ export declare const PandaApp: {
                 touch?: boolean;
             }) => Promise<import("./types.js").WorkspaceListItem>;
         };
+        artifacts: {
+            list: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsListResult>;
+            snapshot: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsSnapshotResult>;
+            readText: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadTextResult>;
+            readDataUrl: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadDataUrlResult>;
+        };
+        conversationData: {
+            readActivity: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationActivityQuery) => Promise<import("./types.js").ConversationActivity>;
+            listConversations: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            readRecords: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationRecordsQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataRecord>>;
+            readRecord: (ref: import("./types.js").ConversationRef, recordId: string, query?: import("./types.js").ConversationRecordQuery) => Promise<import("./types.js").ConversationDataRecord>;
+            getRuntime: (ref: import("./types.js").ConversationRef, options?: {
+                streamingPreview?: boolean;
+            }) => Promise<import("./types.js").ConversationRuntimeObservation>;
+            listRuntime: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            getLocations: (ref: import("./types.js").ConversationRef) => Promise<import("./types.js").ConversationRecordLocation[]>;
+        };
         conversation: {
+            create: (options?: import("./types.js").CreateConversationOptions) => Promise<import("./types.js").CreateConversationResult>;
             createForApp: (options?: import("./types.js").CreateForAppOptions) => Promise<import("./types.js").CreateForAppResult>;
             disposeForApp: (conversationId: string) => Promise<unknown>;
+            listForApp: (workspaceId?: string) => Promise<unknown>;
+            attach: (conversationId: string) => Promise<{
+                conversationId: string;
+            }>;
+            detach: (conversationId: string) => Promise<unknown>;
             submitMessage: (conversationId: string, prompt: string) => Promise<unknown>;
             getMessages: (conversationId: string) => Promise<unknown>;
             subscribe: (options: import("./types.js").ConversationSubscribeOptions & {
@@ -46,9 +72,16 @@ export declare const PandaApp: {
             }) => Promise<unknown>;
         };
         session: {
-            mount: (conversationId: string, appId: string, replaceConfirmed?: boolean) => Promise<unknown>;
-            unmount: (conversationId: string) => Promise<unknown>;
-            getMount: (conversationId: string) => Promise<unknown>;
+            getContext: () => Promise<import("./types.js").SessionContext>;
+            mount: (conversationId: string, appId: string) => Promise<unknown>;
+            unmount: (conversationId: string, appId: string) => Promise<unknown>;
+            listMounts: (conversationId: string) => Promise<unknown>;
+        };
+        todo: {
+            get: (conversationId: string) => Promise<import("./types.js").TodoSnapshot>;
+        };
+        memory: {
+            listSessionEntries: (conversationId: string) => Promise<import("./types.js").MemorySessionEntries>;
         };
         ingress: {
             submit: (conversationId: string, prompt: string) => Promise<{
@@ -56,6 +89,37 @@ export declare const PandaApp: {
                 status: string;
             }>;
         };
+        agent: {
+            invokeSkill: (request: import("./types.js").InvokeSkillRequest) => Promise<import("./types.js").InvokeSkillResult>;
+            invokeSubagent: (request: import("./types.js").InvokeSubagentRequest) => Promise<import("./types.js").InvokeSubagentResult>;
+            cancelSubagent: (invocationId: string) => Promise<import("./types.js").CancelSubagentResult>;
+        };
+        ui: {
+            theme: () => Promise<import("./types.js").AppUiThemeResult>;
+            openExternal: (url: string) => Promise<void>;
+            sessionSurface: {
+                getState: () => Promise<import("./types.js").SessionSurfaceState>;
+                show: (options?: {
+                    activate?: boolean;
+                    reason?: string;
+                }) => Promise<unknown>;
+                collapse: () => Promise<unknown>;
+            };
+        };
+        storage: {
+            global: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+            session: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+        };
         tools: {
             list: (request: {
                 workspace?: import("./types.js").WorkspaceRef;
@@ -100,7 +164,190 @@ export declare const PandaApp: {
                 homeDir: string;
                 pandaVersion: string;
                 appSdkVersion: string;
+                capabilities?: {
+                    invocationToolPolicy?: boolean;
+                    appPrivateMcp?: boolean;
+                };
+            }>;
+            supports: (requiredVersion: string) => Promise<boolean>;
+        };
+        dialog: {
+            showOpen: (request?: import("./types.js").DialogShowOpenRequest) => Promise<import("./types.js").DialogShowOpenResult>;
+            readPickedFile: (request: import("./types.js").DialogReadPickedFileRequest) => Promise<import("./types.js").DialogReadPickedFileResult>;
+            releasePick: (pickToken: string) => Promise<unknown>;
+            showSave: (request?: import("./types.js").DialogShowSaveRequest) => Promise<import("./types.js").DialogShowSaveResult>;
+            writeSaveFile: (request: import("./types.js").DialogWriteSaveFileRequest) => Promise<import("./types.js").DialogWriteSaveFileResult>;
+            pickAndReadFile: (options?: import("./types.js").DialogPickAndReadFileOptions) => Promise<import("./types.js").DialogReadPickedFileResult | null>;
+            saveFile: (options: import("./types.js").DialogSaveFileOptions) => Promise<string | null>;
+        };
+    };
+    /** @deprecated Use PandaApp.connect() instead. */
+    connectIframe: () => {
+        ready: () => Promise<void>;
+        auth: {
+            getCurrentUser: () => Promise<import("./types.js").AppUser | null>;
+        };
+        model: {
+            list: (options?: {
+                enabledOnly?: boolean;
+                visibleOnly?: boolean;
+                scene?: string;
+            }) => Promise<import("./types.js").ModelListItem[]>;
+            resolveForScene: (request?: {
+                scene?: string;
+                preferredModelId?: string;
+            }) => Promise<import("./types.js").ModelListItem | null>;
+            chat: (request: import("./types.js").ModelChatRequest) => Promise<import("./types.js").ModelChatResult>;
+        };
+        workspace: {
+            list: (request: {
+                limit: number;
+                includeEphemeral?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem[]>;
+            ensureLocal: (request: {
+                path: string;
+                touch?: boolean;
+            }) => Promise<import("./types.js").WorkspaceListItem>;
+        };
+        artifacts: {
+            list: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsListResult>;
+            snapshot: (request: import("./types.js").ArtifactsListRequest) => Promise<import("./types.js").ArtifactsSnapshotResult>;
+            readText: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadTextResult>;
+            readDataUrl: (request: import("./types.js").ArtifactsReadRequest) => Promise<import("./types.js").ArtifactReadDataUrlResult>;
+        };
+        conversationData: {
+            readActivity: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationActivityQuery) => Promise<import("./types.js").ConversationActivity>;
+            listConversations: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            readRecords: (ref: import("./types.js").ConversationRef, query: import("./types.js").ConversationRecordsQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataRecord>>;
+            readRecord: (ref: import("./types.js").ConversationRef, recordId: string, query?: import("./types.js").ConversationRecordQuery) => Promise<import("./types.js").ConversationDataRecord>;
+            getRuntime: (ref: import("./types.js").ConversationRef, options?: {
+                streamingPreview?: boolean;
+            }) => Promise<import("./types.js").ConversationRuntimeObservation>;
+            listRuntime: (query?: import("./types.js").ConversationListQuery) => Promise<import("./types.js").ConversationDataPage<import("./types.js").ConversationDataListItem>>;
+            getLocations: (ref: import("./types.js").ConversationRef) => Promise<import("./types.js").ConversationRecordLocation[]>;
+        };
+        conversation: {
+            create: (options?: import("./types.js").CreateConversationOptions) => Promise<import("./types.js").CreateConversationResult>;
+            createForApp: (options?: import("./types.js").CreateForAppOptions) => Promise<import("./types.js").CreateForAppResult>;
+            disposeForApp: (conversationId: string) => Promise<unknown>;
+            listForApp: (workspaceId?: string) => Promise<unknown>;
+            attach: (conversationId: string) => Promise<{
+                conversationId: string;
+            }>;
+            detach: (conversationId: string) => Promise<unknown>;
+            submitMessage: (conversationId: string, prompt: string) => Promise<unknown>;
+            getMessages: (conversationId: string) => Promise<unknown>;
+            subscribe: (options: import("./types.js").ConversationSubscribeOptions & {
+                onEvent?: import("./types.js").AppEventHandler;
+            }) => Promise<{
+                subscriptionId: string;
+                unsubscribe: () => Promise<void>;
+            }>;
+            awaitTurn: (options: {
+                conversationId: string;
+                turnId?: string;
+                timeoutMs?: number;
+            }) => Promise<unknown>;
+        };
+        session: {
+            getContext: () => Promise<import("./types.js").SessionContext>;
+            mount: (conversationId: string, appId: string) => Promise<unknown>;
+            unmount: (conversationId: string, appId: string) => Promise<unknown>;
+            listMounts: (conversationId: string) => Promise<unknown>;
+        };
+        todo: {
+            get: (conversationId: string) => Promise<import("./types.js").TodoSnapshot>;
+        };
+        memory: {
+            listSessionEntries: (conversationId: string) => Promise<import("./types.js").MemorySessionEntries>;
+        };
+        ingress: {
+            submit: (conversationId: string, prompt: string) => Promise<{
+                conversationId: string;
+                status: string;
+            }>;
+        };
+        agent: {
+            invokeSkill: (request: import("./types.js").InvokeSkillRequest) => Promise<import("./types.js").InvokeSkillResult>;
+            invokeSubagent: (request: import("./types.js").InvokeSubagentRequest) => Promise<import("./types.js").InvokeSubagentResult>;
+            cancelSubagent: (invocationId: string) => Promise<import("./types.js").CancelSubagentResult>;
+        };
+        ui: {
+            theme: () => Promise<import("./types.js").AppUiThemeResult>;
+            openExternal: (url: string) => Promise<void>;
+            sessionSurface: {
+                getState: () => Promise<import("./types.js").SessionSurfaceState>;
+                show: (options?: {
+                    activate?: boolean;
+                    reason?: string;
+                }) => Promise<unknown>;
+                collapse: () => Promise<unknown>;
+            };
+        };
+        storage: {
+            global: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+            session: {
+                get: (key: string) => Promise<import("./types.js").AppJsonValue | undefined>;
+                set: (key: string, value: import("./types.js").AppJsonValue) => Promise<unknown>;
+                delete: (key: string) => Promise<unknown>;
+                list: (prefix?: string) => Promise<import("./types.js").AppStorageListItem[]>;
+            };
+        };
+        tools: {
+            list: (request: {
+                workspace?: import("./types.js").WorkspaceRef;
+                workspaceId?: string;
+            }) => Promise<Array<{
+                name: string;
+                displayName: string;
+                description: string;
+                kind: string;
+            }>>;
+            execute: (request: {
+                toolName: string;
+                args?: Record<string, unknown>;
+                workspace?: import("./types.js").WorkspaceRef;
+                workspaceId?: string;
+            }) => Promise<{
+                toolName: string;
+                workspaceId: string;
+                ok: boolean;
+                llmContent?: string;
+                error?: {
+                    message: string;
+                    type?: string;
+                };
+                displayData?: unknown;
+            }>;
+        };
+        runtime: {
+            now: () => Promise<{
+                timestamp: number;
+                iso: string;
+                timeZone: string;
+                utcOffsetMinutes: number;
+            }>;
+            getHost: () => Promise<{
+                platform: string;
+                arch: string;
+                osName: string;
+                hostProduct: string;
+                shell: string;
+                shellKind: string;
+                homeDir: string;
+                pandaVersion: string;
+                appSdkVersion: string;
+                capabilities?: {
+                    invocationToolPolicy?: boolean;
+                    appPrivateMcp?: boolean;
+                };
             }>;
+            supports: (requiredVersion: string) => Promise<boolean>;
         };
         dialog: {
             showOpen: (request?: import("./types.js").DialogShowOpenRequest) => Promise<import("./types.js").DialogShowOpenResult>;

package/dist/browser/index.js

@@ -3,30 +3,75 @@ var PANDA_APP_BRIDGE_INVOKE = "panda-app-bridge:invoke";
 var PANDA_APP_BRIDGE_INVOKE_RESULT = "panda-app-bridge:invoke-result";
 var PANDA_APP_BRIDGE_EVENT = "panda-app-bridge:event";
 
+// src/semver.ts
+function compareSemver(v1, v2) {
+  const parse = (v) => {
+    const parts = v.split(".");
+    const nums = [];
+    for (let i = 0; i < 3; i++) {
+      const n = parseInt(parts[i] ?? "0", 10);
+      nums.push(Number.isFinite(n) ? n : 0);
+    }
+    return nums;
+  };
+  const a = parse(v1);
+  const b = parse(v2);
+  for (let i = 0; i < 3; i++) {
+    if (a[i] > b[i]) return 1;
+    if (a[i] < b[i]) return -1;
+  }
+  return 0;
+}
+
 // src/create-app-sdk.ts
 function createAppSdk(transport) {
+  const policyPreflights = /* @__PURE__ */ new Map();
+  let ready;
   return {
+    /** Report this side ready. Initialization and the first usable render must finish before calling. */
+    ready: () => ready ??= transport.ready ? transport.ready() : Promise.reject(new Error("This Panda host does not support App readiness")),
     auth: {
       getCurrentUser: () => transport.invoke("auth.getCurrentUser", [])
     },
     model: {
       list: (options) => transport.invoke("model.list", [options ?? {}]),
-      resolveForScene: (request) => transport.invoke("model.resolveForScene", [request ?? {}])
+      resolveForScene: (request) => transport.invoke("model.resolveForScene", [request ?? {}]),
+      chat: (request) => transport.invoke("model.chat", [request])
     },
     workspace: {
       list: (request) => transport.invoke("workspace.list", [request]),
       ensureLocal: (request) => transport.invoke("workspace.ensureLocal", [request])
     },
+    artifacts: {
+      list: (request) => transport.invoke("artifacts.list", [request]),
+      snapshot: (request) => transport.invoke("artifacts.snapshot", [request]),
+      readText: (request) => transport.invoke("artifacts.readText", [request]),
+      readDataUrl: (request) => transport.invoke("artifacts.readDataUrl", [request])
+    },
+    conversationData: {
+      readActivity: (ref, query) => transport.invoke("conversationData.readActivity", [ref, query]),
+      listConversations: (query) => transport.invoke("conversationData.listConversations", [query ?? {}]),
+      readRecords: (ref, query) => transport.invoke("conversationData.readRecords", [ref, query]),
+      readRecord: (ref, recordId, query) => transport.invoke("conversationData.readRecord", [ref, recordId, query ?? {}]),
+      getRuntime: (ref, options) => transport.invoke("conversationData.getRuntime", [ref, options ?? {}]),
+      listRuntime: (query) => transport.invoke("conversationData.listRuntime", [query ?? {}]),
+      getLocations: (ref) => transport.invoke("conversationData.getLocations", [ref])
+    },
     conversation: {
+      create: (options) => transport.invoke("conversation.create", [options ?? {}]),
       createForApp: (options) => transport.invoke("conversation.createForApp", [options ?? {}]),
       disposeForApp: (conversationId) => transport.invoke("conversation.disposeForApp", [conversationId]),
+      listForApp: (workspaceId) => transport.invoke("conversation.listForApp", workspaceId === void 0 ? [] : [workspaceId]),
+      attach: (conversationId) => transport.invoke("conversation.attach", [conversationId]),
+      detach: (conversationId) => transport.invoke("conversation.detach", [conversationId]),
       submitMessage: (conversationId, prompt) => transport.invoke("conversation.submitMessage", [conversationId, prompt]),
       getMessages: (conversationId) => transport.invoke("conversation.getMessages", [conversationId]),
       subscribe: async (options) => {
-        const result = await transport.invoke("conversation.subscribe", [options]);
+        const { onEvent, ...request } = options;
+        const result = await transport.invoke("conversation.subscribe", [request]);
         let offEvent;
-        if (options.onEvent) {
-          offEvent = transport.subscribe(result.subscriptionId, options.onEvent);
+        if (onEvent) {
+          offEvent = transport.subscribe(result.subscriptionId, onEvent);
         }
         return {
           subscriptionId: result.subscriptionId,
@@ -39,20 +84,85 @@ function createAppSdk(transport) {
       awaitTurn: (options) => transport.invoke("conversation.awaitTurn", [options])
     },
     session: {
-      mount: (conversationId, appId, replaceConfirmed) => transport.invoke("mountSession", [conversationId, appId, replaceConfirmed === true]),
-      unmount: (conversationId) => transport.invoke("unmountSession", [conversationId]),
-      getMount: (conversationId) => transport.invoke("getSessionMount", [conversationId])
+      getContext: () => transport.invoke("session.getContext", []),
+      mount: (conversationId, appId) => transport.invoke("mountSession", [conversationId, appId]),
+      unmount: (conversationId, appId) => transport.invoke("unmountSession", [conversationId, appId]),
+      listMounts: (conversationId) => transport.invoke("listSessionMounts", [conversationId])
+    },
+    todo: {
+      get: (conversationId) => transport.invoke("todo.get", [conversationId])
+    },
+    memory: {
+      listSessionEntries: (conversationId) => transport.invoke("memory.listSessionEntries", [conversationId])
     },
     ingress: {
       submit: (conversationId, prompt) => transport.invoke("ingress.submit", [conversationId, prompt])
     },
+    agent: {
+      invokeSkill: (request) => transport.invoke("agent.invokeSkill", [request]),
+      invokeSubagent: async (request) => {
+        const restricted = request.allowedTools !== void 0 || request.readableFiles !== void 0;
+        const id = restricted ? request.invocationId?.trim() : void 0;
+        if (id && policyPreflights.has(id)) throw new Error("Duplicate subagent invocationId");
+        const pending = { cancelled: false };
+        if (id) policyPreflights.set(id, pending);
+        try {
+          if (restricted) {
+            const host = await transport.invoke("runtime.getHost", []);
+            if (pending.cancelled) throw new Error("Subagent cancelled before dispatch");
+            if (host?.capabilities?.invocationToolPolicy !== true) {
+              throw Object.assign(new Error("Host does not support invocation tool policies; refusing an unrestricted fallback"), { code: "APP_HOST_CAPABILITY_REQUIRED" });
+            }
+          }
+          if (id) policyPreflights.delete(id);
+          return await transport.invoke("agent.invokeSubagent", [request]);
+        } finally {
+          if (id && policyPreflights.get(id) === pending) policyPreflights.delete(id);
+        }
+      },
+      cancelSubagent: async (invocationId) => {
+        const pending = policyPreflights.get(invocationId.trim());
+        if (pending) {
+          pending.cancelled = true;
+          return { cancelled: true };
+        }
+        return transport.invoke("agent.cancelSubagent", [{ invocationId }]);
+      }
+    },
+    ui: {
+      theme: () => transport.invoke("ui.theme", []),
+      openExternal: (url) => transport.invoke("ui.openExternal", [{ url }]),
+      sessionSurface: {
+        getState: () => transport.invoke("ui.sessionSurface.getState", []),
+        show: (options) => transport.invoke("ui.sessionSurface.show", [options ?? {}]),
+        collapse: () => transport.invoke("ui.sessionSurface.collapse", [])
+      }
+    },
+    storage: {
+      global: {
+        get: (key) => transport.invoke("storage.global.get", [key]),
+        set: (key, value) => transport.invoke("storage.global.set", [key, value]),
+        delete: (key) => transport.invoke("storage.global.delete", [key]),
+        list: (prefix) => transport.invoke("storage.global.list", prefix === void 0 ? [] : [prefix])
+      },
+      session: {
+        get: (key) => transport.invoke("storage.session.get", [key]),
+        set: (key, value) => transport.invoke("storage.session.set", [key, value]),
+        delete: (key) => transport.invoke("storage.session.delete", [key]),
+        list: (prefix) => transport.invoke("storage.session.list", prefix === void 0 ? [] : [prefix])
+      }
+    },
     tools: {
       list: (request) => transport.invoke("tools.list", [request]),
       execute: (request) => transport.invoke("tools.execute", [request])
     },
     runtime: {
       now: () => transport.invoke("runtime.now", []),
-      getHost: () => transport.invoke("runtime.getHost", [])
+      getHost: () => transport.invoke("runtime.getHost", []),
+      supports: async (requiredVersion) => {
+        const host = await transport.invoke("runtime.getHost", []);
+        return compareSemver(host.appSdkVersion, requiredVersion) >= 0;
+      }
     },
     dialog: {
       showOpen: (request) => transport.invoke("dialog.showOpen", [request ?? {}]),
@@ -96,18 +206,42 @@ function createAppSdk(transport) {
 }
 
 // src/request-id.browser.ts
+function randomByte() {
+  return Math.floor(Math.random() * 256);
+}
+function uuidFromBytes(bytes) {
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
+  return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10, 16).join("")}`;
+}
 function newRequestId() {
-  return crypto.randomUUID();
+  const webCrypto = globalThis.crypto;
+  if (typeof webCrypto?.randomUUID === "function") return webCrypto.randomUUID();
+  const bytes = new Uint8Array(16);
+  if (typeof webCrypto?.getRandomValues === "function") webCrypto.getRandomValues(bytes);
+  else bytes.set(Array.from({ length: bytes.length }, randomByte));
+  return uuidFromBytes(bytes);
 }
 
 // src/transport/shared/pending-invoke.ts
 function createPendingInvoke(newRequestId2) {
   const pending = /* @__PURE__ */ new Map();
-  function invoke(postMessage, invokeType, path, args) {
+  function invoke(postMessage, invokeType, path, args, timeoutMs) {
     const requestId = newRequestId2();
     return new Promise((resolve, reject) => {
-      pending.set(requestId, { resolve, reject });
-      postMessage({ type: invokeType, requestId, path, args });
+      const timer = timeoutMs ? setTimeout(() => {
+        pending.delete(requestId);
+        reject(new Error("App ready acknowledgement timed out; update or reopen the Panda host"));
+      }, timeoutMs) : void 0;
+      pending.set(requestId, { resolve, reject, timer });
+      try {
+        postMessage({ type: invokeType, requestId, path, args });
+      } catch (error) {
+        pending.delete(requestId);
+        clearTimeout(timer);
+        reject(error);
+      }
     });
   }
   function handleInvokeResult(message) {
@@ -119,6 +253,7 @@ function createPendingInvoke(newRequestId2) {
       return;
     }
     pending.delete(message.requestId);
+    clearTimeout(entry.timer);
     if (message.ok) {
       entry.resolve(message.result);
     } else {
@@ -162,15 +297,33 @@ function createSubscriptionEvents() {
 }
 
 // src/transport/iframe.ts
+var documentIds = /* @__PURE__ */ new WeakMap();
 function createIframeBridgeTransport() {
   if (typeof window === "undefined") {
     throw new Error("[app-sdk] iframe bridge requires browser context");
   }
   const { invoke: createInvoke, handleInvokeResult } = createPendingInvoke(newRequestId);
   const subscriptions = createSubscriptionEvents();
+  const document = window.document ?? window;
+  let documentId = documentIds.get(document);
+  if (!documentId) {
+    documentId = newRequestId();
+    documentIds.set(document, documentId);
+  }
+  const bootId = new URL(window.location.href).searchParams.get("pandaAppBoot");
   window.addEventListener("message", (event) => {
     const data = event.data;
-    if (!data || typeof data !== "object" || !data.type) {
+    if (event.source !== window.parent || !data || typeof data !== "object" || !data.type) {
+      return;
+    }
+    if (data.type === "panda-app-bridge:document-probe") {
+      const probe = data;
+      if (probe.bootId === bootId && typeof probe.challenge === "string") window.parent.postMessage({
+        type: "panda-app-bridge:document-identity",
+        bootId,
+        documentId,
+        challenge: probe.challenge
+      }, "*");
       return;
     }
     if (data.type === PANDA_APP_BRIDGE_EVENT && data.subscriptionId && data.event) {
@@ -181,7 +334,34 @@ function createIframeBridgeTransport() {
       handleInvokeResult(data);
     }
   });
+  const connected = bootId ? createInvoke(
+    (message) => window.parent.postMessage(message, "*"),
+    PANDA_APP_BRIDGE_INVOKE,
+    "app.frontend.connect",
+    [{ bootId, documentId }],
+    3e4
+  ) : void 0;
+  void connected?.catch(() => void 0);
+  window.addEventListener("pagehide", () => {
+    if (bootId) window.parent.postMessage({
+      type: PANDA_APP_BRIDGE_INVOKE,
+      requestId: newRequestId(),
+      path: "app.frontend.unloading",
+      args: [{ bootId, documentId }]
+    }, "*");
+  });
   return {
+    ready: async () => {
+      if (!connected) throw new Error("App readiness requires a current Panda frontend host");
+      await connected;
+      await createInvoke(
+        (message) => window.parent.postMessage(message, "*"),
+        PANDA_APP_BRIDGE_INVOKE,
+        "app.ready",
+        [{ bootId, documentId }],
+        3e4
+      );
+    },
     invoke(path, args) {
       return createInvoke(
         (message) => {
@@ -197,10 +377,11 @@ function createIframeBridgeTransport() {
 }
 
 // src/browser.ts
+var connect = () => createAppSdk(createIframeBridgeTransport());
 var PandaApp = {
-  connectIframe() {
-    return createAppSdk(createIframeBridgeTransport());
-  }
+  connect,
+  /** @deprecated Use PandaApp.connect() instead. */
+  connectIframe: connect
 };
 export {
   PANDA_APP_BRIDGE_EVENT,
@@ -208,5 +389,6 @@ export {
   PANDA_APP_BRIDGE_INVOKE_RESULT,
   PandaApp,
   createAppSdk,
-  createIframeBridgeTransport
+  createIframeBridgeTransport,
+  newRequestId
 };