@openchamber/sdk 2.1.0 → 2.2.0

package/dist/host.js

@@ -1,7 +1,10 @@
 import { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL } from "./api-version.js";
 import { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_VALUE_BYTES } from "./workspace.js";
+import { isGuestStatusControls } from "./status-controls.js";
+import { isGuestPopoverRequest } from "./popover.js";
 import { GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITOR_VERSION_MAX, fileEditorPayloadSize, sameFileEditorDocument, } from "./file-editor.js";
 import { GUEST_FILE_CONTENT_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_TOAST_MAX, GUEST_FILE_PATH_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TIMEOUT_MS, GUEST_REQUEST_TIMEOUT_MS, GUEST_RESOLVE_ERROR_MAX, isGuestFilePath, isGuestRequestPath, clampAttachRequest, clampBadgeCount, clampFrameHeight, isGuestCommitSha, clampPromptRequest, clampStartSessionRequest, readHostMessage, isGenerateResult, isFileListResult, isFileReadResult, isFileStatResult, isJsonValue, isFileWriteResult, isServiceStatusResult, isGuestRequestResult, isPromptResult, isStartSessionResult, } from "./contract.js";
+import { GUEST_SHELL_ID_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX } from "./shells.js";
 // Structural, not `instanceof KeyboardEvent`: the frame's own realm owns that
 // constructor, and non-browser runtimes have none.
 const isKeyEvent = (event) => 'key' in event && 'metaKey' in event && 'ctrlKey' in event;
@@ -18,6 +21,16 @@ export class HostRequestError extends Error {
 // path would otherwise surface only as HOST_TIMEOUT twenty seconds later.
 const rejectBadPath = () => Promise.reject(new HostRequestError('BAD_PATH', 'Request path must start with "/" and stay on the declared origin.'));
 const rejectBadFilePath = () => Promise.reject(new HostRequestError('BAD_PATH', `File path must be 1 to ${GUEST_FILE_PATH_MAX} characters without NUL or backslash.`));
+const deviceStorageScope = (options) => {
+    // Typed callers supply GuestStorageOptions, but extensions may call this JavaScript API without TypeScript.
+    if (options === undefined)
+        return undefined;
+    if (Object(options) !== options || Array.isArray(options)
+        || (options.scope !== undefined && options.scope !== 'instance' && options.scope !== 'device')) {
+        throw new HostRequestError('HOST_REJECTED', 'Storage scope must be "instance" or "device".');
+    }
+    return options.scope === 'device' ? 'device' : undefined;
+};
 const nextId = (n) => {
     n.value += 1;
     return `oc-${n.value}`;
@@ -36,6 +49,8 @@ export const connectHost = (options = {}) => {
     const connectionListeners = new Set();
     const settingsListeners = new Set();
     const itemListeners = new Set();
+    const statusControlListeners = new Set();
+    const popoverClosedListeners = new Set();
     let resolveHandler = null;
     let actionHandler = null;
     const fileOpenListeners = new Set();
@@ -45,10 +60,14 @@ export const connectHost = (options = {}) => {
     let saveShortcutInstalled = false;
     const pending = new Map();
     const workspaceListeners = new Map();
+    const shellsListeners = new Map();
     let disposed = false;
     const ids = { value: 0 };
     let lastReady = null;
     let lastLifecycle = null;
+    let popoverPointerActive = false;
+    let popoverFocusActive = false;
+    let popoverActivityReported = null;
     const lifecycleFromSession = (session) => {
         if (!session)
             return null;
@@ -86,6 +105,12 @@ export const connectHost = (options = {}) => {
                 emit([listener], message.payload.snapshot);
             return;
         }
+        if (message.type === 'shells') {
+            const listener = shellsListeners.get(message.payload.subscriptionId);
+            if (listener)
+                emit([listener], message.payload.snapshot);
+            return;
+        }
         if (message.type === 'ready') {
             lastReady = message.payload;
             lastLifecycle = lifecycleFromSession(message.payload.session);
@@ -146,6 +171,14 @@ export const connectHost = (options = {}) => {
             emit(itemListeners, message.payload.item);
             return;
         }
+        if (message.type === 'status-control-event') {
+            emit(statusControlListeners, message.payload);
+            return;
+        }
+        if (message.type === 'popover-closed') {
+            emit(popoverClosedListeners, message.payload);
+            return;
+        }
         if (message.type === 'action') {
             const answer = (payload) => {
                 if (!disposed)
@@ -274,6 +307,46 @@ export const connectHost = (options = {}) => {
         event.preventDefault();
         requestFileSave();
     };
+    const onPopoverEscape = (event) => {
+        if (!isKeyEvent(event) || event.key !== 'Escape' || lastReady?.surface !== 'popover' || !lastReady.popover)
+            return;
+        event.preventDefault();
+        void closePopover(lastReady.popover.id, 'escape').catch(() => undefined);
+    };
+    const reportPopoverActivity = () => {
+        const popover = lastReady?.surface === 'popover' ? lastReady.popover : undefined;
+        if (!popover)
+            return;
+        const active = popoverPointerActive || popoverFocusActive;
+        if (popoverActivityReported === active)
+            return;
+        popoverActivityReported = active;
+        void setPopoverAnchorActive(popover.id, active).catch(() => undefined);
+    };
+    const onPopoverPointerOver = () => {
+        if (lastReady?.surface !== 'popover' || popoverPointerActive)
+            return;
+        popoverPointerActive = true;
+        reportPopoverActivity();
+    };
+    const onPopoverPointerOut = (event) => {
+        if (lastReady?.surface !== 'popover' || event.relatedTarget !== null || !popoverPointerActive)
+            return;
+        popoverPointerActive = false;
+        reportPopoverActivity();
+    };
+    const onPopoverFocus = () => {
+        if (lastReady?.surface !== 'popover' || popoverFocusActive)
+            return;
+        popoverFocusActive = true;
+        reportPopoverActivity();
+    };
+    const onPopoverBlur = () => {
+        if (lastReady?.surface !== 'popover' || !popoverFocusActive)
+            return;
+        popoverFocusActive = false;
+        reportPopoverActivity();
+    };
     const requireIdentity = (value, maximum = 1024) => {
         if (!value.trim() || value.length > maximum)
             throw new HostRequestError('HOST_REJECTED', `Identity must contain 1 to ${maximum} characters.`);
@@ -307,6 +380,28 @@ export const connectHost = (options = {}) => {
             post({ ...envelope, type: 'workspace-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
         };
     };
+    const subscribeShells = async (scope, listener) => {
+        if (scope.kind === 'session')
+            requireIdentity(scope.sessionId);
+        if (scope.kind === 'project')
+            requireIdentity(scope.projectId);
+        const subscriptionId = nextId(ids);
+        shellsListeners.set(subscriptionId, listener);
+        try {
+            await request({ ...envelope, type: 'shells-subscribe', id: nextId(ids), payload: { subscriptionId, scope } });
+        }
+        catch (error) {
+            shellsListeners.delete(subscriptionId);
+            if (!disposed)
+                post({ ...envelope, type: 'shells-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
+            throw error;
+        }
+        return () => {
+            if (!shellsListeners.delete(subscriptionId) || disposed)
+                return;
+            post({ ...envelope, type: 'shells-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
+        };
+    };
     const storage = async (payload) => {
         if ('key' in payload && (payload.key.length === 0 || payload.key.length > GUEST_STORAGE_KEY_MAX)) {
             throw new HostRequestError('HOST_REJECTED', 'Storage key must contain 1 to 128 characters.');
@@ -317,11 +412,26 @@ export const connectHost = (options = {}) => {
         if (payload.op === 'set' && new TextEncoder().encode(JSON.stringify(payload.value)).length > GUEST_STORAGE_VALUE_BYTES) {
             throw new HostRequestError('HOST_REJECTED', 'Storage value exceeds 64 KiB.');
         }
+        if (payload.scope === 'device' && lastReady?.features?.deviceStorage !== true) {
+            throw new HostRequestError('UNSUPPORTED', 'This host does not support device storage.');
+        }
         const result = await send({ ...envelope, type: 'storage', id: nextId(ids), payload });
         if (!result || !('storage' in result) || result.op !== payload.op)
             throw new HostRequestError('HOST_REJECTED', 'Host did not return storage data.');
         return result;
     };
+    const closePopover = (id, reason) => (lastReady?.features?.popovers !== true && !(lastReady?.surface === 'popover' && lastReady.popover?.id === id)
+        ? Promise.reject(new HostRequestError('UNSUPPORTED', 'This host does not support popovers.'))
+        : request({ ...envelope, type: 'popover-close', id: nextId(ids), payload: reason ? { id, reason } : { id } }));
+    const setPopoverAnchorActive = (id, active) => (lastReady?.features?.popovers !== true && !(lastReady?.surface === 'popover' && lastReady.popover?.id === id)
+        ? Promise.reject(new HostRequestError('UNSUPPORTED', 'This host does not support popovers.'))
+        : request({ ...envelope, type: 'popover-anchor', id: nextId(ids), payload: { id, active } }));
+    target.addEventListener('keydown', onPopoverEscape, true);
+    target.addEventListener('pointerover', onPopoverPointerOver);
+    target.addEventListener('pointermove', onPopoverPointerOver);
+    target.addEventListener('pointerout', onPopoverPointerOut);
+    target.addEventListener('focus', onPopoverFocus);
+    target.addEventListener('blur', onPopoverBlur);
     return {
         onAction: (handler) => {
             actionHandler = handler;
@@ -352,19 +462,64 @@ export const connectHost = (options = {}) => {
             listener(snapshot); }),
         onSessions: (projectId, listener) => subscribeWorkspace({ kind: 'sessions', projectId }, (snapshot) => { if (snapshot.kind === 'sessions')
             listener(snapshot); }),
+        onRunningShells: (scope, listener) => subscribeShells(scope, listener),
+        readShellOutput: async (shellId, options) => {
+            requireIdentity(shellId, GUEST_SHELL_ID_MAX);
+            const cursor = options?.cursor;
+            if (cursor !== undefined && (!Number.isInteger(cursor) || cursor < 0)) {
+                throw new HostRequestError('HOST_REJECTED', 'Shell output cursor must be a non-negative integer.');
+            }
+            const tailBytes = options?.tailBytes;
+            if (tailBytes !== undefined && (!Number.isInteger(tailBytes) || tailBytes < 1 || tailBytes > GUEST_SHELL_OUTPUT_TAIL_MAX)) {
+                throw new HostRequestError('HOST_REJECTED', `Shell output tailBytes must be an integer between 1 and ${GUEST_SHELL_OUTPUT_TAIL_MAX}.`);
+            }
+            const result = await send({ ...envelope, type: 'shell-output', id: nextId(ids), payload: { shellId, cursor, tailBytes } });
+            const output = result;
+            if (!output || typeof output.output !== 'string' || !Number.isFinite(output.cursor)) {
+                throw new HostRequestError('HOST_REJECTED', 'Host did not return shell output.');
+            }
+            return output;
+        },
+        stopShell: async (shellId) => {
+            requireIdentity(shellId, GUEST_SHELL_ID_MAX);
+            const result = (await send({ ...envelope, type: 'shell-stop', id: nextId(ids), payload: { shellId } }));
+            if (result?.stopped !== true)
+                throw new HostRequestError('HOST_REJECTED', 'Host did not stop the shell.');
+            return { stopped: true };
+        },
         openSession: async (sessionId) => {
             requireIdentity(sessionId);
             await request({ ...envelope, type: 'open-session', id: nextId(ids), payload: { sessionId } });
         },
         storage: {
-            get: async (key) => {
-                const result = await storage({ op: 'get', key });
+            get: async (key, options) => {
+                const scope = deviceStorageScope(options);
+                const payload = { op: 'get', key };
+                if (scope)
+                    payload.scope = scope;
+                const result = await storage(payload);
                 return result.op === 'get' && result.found ? result.value : undefined;
             },
-            set: async (key, value) => { await storage({ op: 'set', key, value }); },
-            delete: async (key) => { await storage({ op: 'delete', key }); },
-            keys: async () => {
-                const result = await storage({ op: 'keys' });
+            set: async (key, value, options) => {
+                const scope = deviceStorageScope(options);
+                const payload = { op: 'set', key, value };
+                if (scope)
+                    payload.scope = scope;
+                await storage(payload);
+            },
+            delete: async (key, options) => {
+                const scope = deviceStorageScope(options);
+                const payload = { op: 'delete', key };
+                if (scope)
+                    payload.scope = scope;
+                await storage(payload);
+            },
+            keys: async (options) => {
+                const scope = deviceStorageScope(options);
+                const payload = { op: 'keys' };
+                if (scope)
+                    payload.scope = scope;
+                const result = await storage(payload);
                 if (result.op !== 'keys')
                     throw new HostRequestError('HOST_REJECTED', 'Expected storage keys.');
                 return result.keys;
@@ -426,6 +581,36 @@ export const connectHost = (options = {}) => {
                 itemListeners.delete(listener);
             };
         },
+        onStatusControl: (listener) => {
+            statusControlListeners.add(listener);
+            return () => {
+                statusControlListeners.delete(listener);
+            };
+        },
+        onPopoverClosed: (listener) => {
+            popoverClosedListeners.add(listener);
+            return () => { popoverClosedListeners.delete(listener); };
+        },
+        setStatusControls: (controls) => {
+            if (lastReady?.features?.statusControls !== true) {
+                return Promise.reject(new HostRequestError('UNSUPPORTED', 'This host does not support status controls.'));
+            }
+            if (!isGuestStatusControls(controls)) {
+                return Promise.reject(new HostRequestError('HOST_REJECTED', 'Status controls must have unique bounded ids and valid selected options.'));
+            }
+            return request({ ...envelope, type: 'status-controls', id: nextId(ids), payload: { controls } });
+        },
+        openPopover: (payload) => {
+            if (lastReady?.features?.popovers !== true) {
+                return Promise.reject(new HostRequestError('UNSUPPORTED', 'This host does not support popovers.'));
+            }
+            if (!isGuestPopoverRequest(payload)) {
+                return Promise.reject(new HostRequestError('HOST_REJECTED', 'Popover requests need bounded geometry and JSON data.'));
+            }
+            return request({ ...envelope, type: 'popover-open', id: nextId(ids), payload });
+        },
+        closePopover,
+        setPopoverAnchorActive,
         onResolve: (handler) => {
             resolveHandler = handler;
             return () => {
@@ -726,6 +911,10 @@ export const connectHost = (options = {}) => {
                 post({ ...envelope, type: 'workspace-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
             }
             workspaceListeners.clear();
+            for (const subscriptionId of shellsListeners.keys()) {
+                post({ ...envelope, type: 'shells-unsubscribe', id: nextId(ids), payload: { subscriptionId } });
+            }
+            shellsListeners.clear();
             disposed = true;
             resolveHandler = null;
             actionHandler = null;
@@ -735,6 +924,12 @@ export const connectHost = (options = {}) => {
             if (saveShortcutInstalled)
                 target.removeEventListener('keydown', onSaveShortcut, true);
             target.removeEventListener('message', onMessage);
+            target.removeEventListener('keydown', onPopoverEscape, true);
+            target.removeEventListener('pointerover', onPopoverPointerOver);
+            target.removeEventListener('pointermove', onPopoverPointerOver);
+            target.removeEventListener('pointerout', onPopoverPointerOut);
+            target.removeEventListener('focus', onPopoverFocus);
+            target.removeEventListener('blur', onPopoverBlur);
             for (const waiter of pending.values()) {
                 clearTimeout(waiter.timer);
                 waiter.reject(new HostRequestError('HOST_UNAVAILABLE', 'Host client was disposed.'));
@@ -747,6 +942,8 @@ export const connectHost = (options = {}) => {
             connectionListeners.clear();
             settingsListeners.clear();
             itemListeners.clear();
+            statusControlListeners.clear();
+            popoverClosedListeners.clear();
         },
     };
 };

package/dist/index.d.ts

@@ -1,8 +1,12 @@
 export { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL, OPENCHAMBER_SDK_MANIFEST_API_VERSIONS } from './api-version.ts';
 export { GUEST_SCROLLBAR_CSS, GUEST_SCROLLBAR_SCRIPT } from './scrollbar-style.ts';
 export { guestFramePolicy } from './frame-policy.ts';
-export type { GuestLoadState, GuestProject, GuestWorktree, GuestSessionActivity, GuestSessionRecord, GuestDirectoryCoverage, GuestProjectsSnapshot, GuestWorktreesSnapshot, GuestSessionsSnapshot, GuestWorkspaceSnapshot, GuestWorkspaceQuery, GuestWorkspaceSubscription, GuestWorkspaceUpdate, GuestStorageRequest, GuestStorageResult, GuestSessionWorktree } from './workspace.ts';
-export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES } from './workspace.ts';
+export type { GuestLoadState, GuestProject, GuestWorktree, GuestSessionActivity, GuestSessionRecord, GuestDirectoryCoverage, GuestProjectsSnapshot, GuestWorktreesSnapshot, GuestSessionsSnapshot, GuestWorkspaceSnapshot, GuestWorkspaceQuery, GuestWorkspaceSubscription, GuestWorkspaceUpdate, GuestStorageRequest, GuestStorageResult, GuestStorageOptions, GuestStorageScope, GuestSessionWorktree } from './workspace.ts';
+export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES, GUEST_DEVICE_STORAGE_TOTAL_BYTES } from './workspace.ts';
+export type { GuestRunningShell, GuestEndedShell, GuestShellEndStatus, GuestRunningShellsSnapshot, GuestShellsScope, GuestShellsSubscription, GuestShellOutputRequest, GuestShellOutputResult, GuestShellStopResult, } from './shells.ts';
+export { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX, } from './shells.ts';
+export { GUEST_STATUS_CONTROLS_MAX, GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX } from './status-controls.ts';
+export type { GuestStatusControl, GuestStatusControlEvent, GuestStatusControlOption } from './status-controls.ts';
 export type { OpenChamberManifestApiVersion } from './api-version.ts';
 export { compareOpenChamberVersions, hostMeetsOpenChamberEngine, openChamberEngineMinimum, OPENCHAMBER_ENGINE_PATTERN, parseOpenChamberVersion, } from './host-version.ts';
 export { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_CAPABILITIES, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_TOOLS_MAX, GUEST_TOOL_COLUMNS_MAX, GUEST_TOOL_COLUMN_MAX, GUEST_TOOL_LANGUAGE_MAX, GUEST_TOOL_MATCH, GUEST_TOOL_MATCH_MAX, GUEST_TOOL_NAME_MAX, GUEST_TOOL_OUTPUTS, GUEST_TOOL_TEMPLATE_MAX, GUEST_TOOL_TEMPLATE_VALUE_MAX, guestActionsNeedConversation, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_ORIGINS_MAX, GUEST_SERVICE_PROVIDES, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_DEFAULT, GUEST_SURFACE_DOCK_SIZE_DEFAULT, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_DEFAULT, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, clampStatusSectionHeight, HOST_LINEAR_API_ORIGIN, isGuestFilesystemPattern, hasGuestCapability, hasGuestPage, isGuestApproved, isGuestPackageSvgIcon, requestedGuestCapabilities, resolveAttachEntry, resolvePageEntry, resolveStatusSectionEntry, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, serviceProvides, toPublicService, toPublicIntegration, } from './manifest.ts';
@@ -11,8 +15,10 @@ export { GUEST_FILE_EDITORS_MAX, GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITO
 export type { FileEditorChange, FileEditorContentKind, FileEditorContribution, FileEditorDocument, FileEditorSnapshot, FileSnapshotPurpose, FileSnapshotRequest, FileSnapshotResultPayload, } from './file-editor.ts';
 export { connectHost, HostRequestError } from './host.ts';
 export type { HostClient, HostClientOptions, HostFrame } from './host.ts';
+export { GUEST_POPOVER_COORDINATE_MAX, GUEST_POPOVER_DATA_DEPTH_MAX, GUEST_POPOVER_DATA_MAX, GUEST_POPOVER_HEIGHT_MAX, GUEST_POPOVER_HEIGHT_MIN, GUEST_POPOVER_ID, GUEST_POPOVER_SIDES, GUEST_POPOVER_WIDTH_MAX, GUEST_POPOVER_WIDTH_MIN, GUEST_POPOVER_CLOSE_REASONS, isGuestPopoverRequest, } from './popover.ts';
+export type { GuestPopoverAnchor, GuestPopoverClosedEvent, GuestPopoverContext, GuestPopoverRequest, GuestPopoverSide } from './popover.ts';
 export { clampAttachRequest, clampBadgeCount, clampFrameHeight, isGuestCommitSha, GUEST_COMMIT_SHA, clampPromptRequest, clampStartSessionRequest, guestFileScope, isAttachData, isJsonValue, isFileListResult, isFileReadResult, isFileStatResult, isGenerateResult, isFileWriteResult, isGuestFilePath, isGuestAttachItem, isGuestMessageItem, isGuestSessionItem, isServiceStatusResult, isGuestRequestPath, isGuestRequestResult, isHostRequestErrorCode, isPromptResult, isStartSessionResult, readHostMessage, resolveHostRequestErrorCode, } from './contract.ts';
-export type { BadgeRequest, ActionResultPayload, GuestActionItem, GuestActionResultMessage, HostActionMessage, HostFileOpenMessage, HostFileSnapshotMessage, HostFileSavedMessage, GuestFileSnapshotResultMessage, GuestFileChangeMessage, GuestFileSaveMessage, GuestFileUnsupportedMessage, GuestBadgeMessage, GuestResizeMessage, GuestOpenCommitMessage, OpenCommitRequest, ResizeRequest, GuestItem, GuestItemRole, GuestMessageItem, GuestResolveResultMessage, GuestSessionItem, GuestSessionItemMessage, HostResolveMessage, ResolveRequest, ResolveResultPayload, FileListEntry, FileListRequest, FileListResult, FileReadRequest, FileReadResult, FileStatRequest, FileStatResult, FileWriteRequest, FileWriteResult, GenerateRequest, GenerateResult, GuestFileEntryKind, GuestFileListMessage, GuestFileReadMessage, GuestFileScope, GuestFileStatKind, GuestFileStatMessage, GuestGenerateMessage, GuestFileWriteMessage, ServiceStatus, ServiceStatusResult, HostRequestErrorCode, AttachBranches, AttachIssueRequest, AttachThreadKind, JsonValue, HostResultPayload, PromptRequest, PromptResult, SessionLifecycleEvent, SessionLifecyclePhase, StartSessionRequest, StartSessionResult, StartSessionSent, ComposeRequest, GuestServiceRequestMessage, GuestServiceStatusMessage, GuestAttachMessage, GuestClipboardWriteMessage, GuestCloseMessage, GuestComposeMessage, GuestConnection, GuestHelloMessage, GuestMessage, GuestOauthDisconnectMessage, GuestOauthStartMessage, GuestOpenSurfaceMessage, GuestOpenUrlMessage, GuestRequest, GuestRequestMessage, GuestRequestMethod, GuestPromptMessage, GuestSessionLinkMessage, GuestStartSessionMessage, GuestRequestResult, GuestSettings, GuestToastMessage, GuestHostSurface, HostConnectionMessage, HostDirectoryMessage, HostItemMessage, HostMessage, HostReadyContext, HostReadyMessage, HostResultMessage, HostSessionLifecycleMessage, HostSessionMessage, HostSettingsMessage, HostTheme, HostThemeMode, HostThemeTokens, SessionSnapshot, ToastKind, ToastRequest, } from './contract.ts';
+export type { BadgeRequest, ActionResultPayload, GuestActionItem, GuestActionResultMessage, HostActionMessage, HostFileOpenMessage, HostFileSnapshotMessage, HostFileSavedMessage, GuestFileSnapshotResultMessage, GuestFileChangeMessage, GuestFileSaveMessage, GuestFileUnsupportedMessage, GuestBadgeMessage, GuestResizeMessage, GuestOpenCommitMessage, GuestStatusControlsMessage, GuestPopoverAnchorMessage, GuestPopoverCloseMessage, GuestPopoverOpenMessage, OpenCommitRequest, ResizeRequest, GuestItem, GuestItemRole, GuestMessageItem, GuestResolveResultMessage, GuestSessionItem, GuestSessionItemMessage, HostResolveMessage, ResolveRequest, ResolveResultPayload, FileListEntry, FileListRequest, FileListResult, FileReadRequest, FileReadResult, FileStatRequest, FileStatResult, FileWriteRequest, FileWriteResult, GenerateRequest, GenerateResult, GuestFileEntryKind, GuestFileListMessage, GuestFileReadMessage, GuestFileScope, GuestFileStatKind, GuestFileStatMessage, GuestGenerateMessage, GuestFileWriteMessage, ServiceStatus, ServiceStatusResult, HostRequestErrorCode, AttachBranches, AttachIssueRequest, AttachThreadKind, JsonValue, HostResultPayload, PromptRequest, PromptResult, SessionLifecycleEvent, SessionLifecyclePhase, StartSessionRequest, StartSessionResult, StartSessionSent, ComposeRequest, GuestServiceRequestMessage, GuestServiceStatusMessage, GuestShellOutputMessage, GuestShellsSubscribeMessage, GuestShellsUnsubscribeMessage, GuestShellStopMessage, GuestAttachMessage, GuestClipboardWriteMessage, GuestCloseMessage, GuestComposeMessage, GuestConnection, GuestHelloMessage, GuestMessage, GuestOauthDisconnectMessage, GuestOauthStartMessage, GuestOpenSurfaceMessage, GuestOpenUrlMessage, GuestRequest, GuestRequestMessage, GuestRequestMethod, GuestPromptMessage, GuestSessionLinkMessage, GuestStartSessionMessage, GuestRequestResult, GuestSettings, GuestToastMessage, GuestHostSurface, HostConnectionMessage, HostDirectoryMessage, HostItemMessage, HostStatusControlEventMessage, HostPopoverClosedMessage, HostMessage, HostReadyContext, HostReadyMessage, HostResultMessage, HostSessionLifecycleMessage, HostSessionMessage, HostSettingsMessage, HostShellsMessage, HostTheme, HostThemeMode, HostThemeTokens, SessionSnapshot, ToastKind, ToastRequest, } from './contract.ts';
 export { EMPTY_GUEST_CONNECTION, GUEST_BADGE_MAX, GUEST_FRAME_HEIGHT_MAX, GUEST_ITEM_MESSAGE_TEXT_MAX, GUEST_ITEM_SESSION_MAX, GUEST_RESOLVE_ERROR_MAX, GUEST_FILE_CONTENT_MAX, GUEST_FILE_ENTRY_KINDS, GUEST_FILE_LIST_MAX, GUEST_FILE_PATH_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TEXT_MAX, GUEST_GENERATE_TIMEOUT_MS, GUEST_FILE_STAT_KINDS, SERVICE_STATUS_VALUES, HOST_REQUEST_ERROR_CODES, SESSION_LIFECYCLE_PHASES, START_SESSION_SENT, GUEST_ACCOUNT_MAX, GUEST_SESSION_AGENT_MAX, GUEST_SESSION_MODEL_MAX, GUEST_ATTACH_AUTHOR_MAX, GUEST_ATTACH_BRANCH_MAX, GUEST_ATTACH_DATA_MAX, GUEST_ATTACH_ID_MAX, GUEST_ATTACH_TEXT_MAX, GUEST_ATTACH_TITLE_MAX, GUEST_ATTACH_URL_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_TOAST_MAX, GUEST_COMPOSE_TEXT_MAX, GUEST_REQUEST_BODY_MAX, GUEST_REQUEST_PATH_MAX, GUEST_REQUEST_RESPONSE_MAX, GUEST_REQUEST_TIMEOUT_MS, GUEST_SETTING_VALUE_MAX, } from './contract.ts';
 export { BROWSER_CONTROL_ACTIONS, BROWSER_PROVIDER_ACTION_TIMEOUT_MS, BROWSER_PROVIDER_IDLE_MS, BROWSER_PROVIDER_OPEN_TIMEOUT_MS, BROWSER_PROVIDER_PATH, BROWSER_PROVIDER_RESPONSE_MAX, BROWSER_SCROLL_DIRECTIONS, BROWSER_VIEWPORT_MODES, isBrowserControlAction, readBrowserProviderRequest, } from './service-providers.ts';
 export type { BrowserCaptureData, BrowserCaptureParameters, BrowserClickData, BrowserClickParameters, BrowserConsoleProblem, BrowserControlAction, BrowserElementBounds, BrowserInspectData, BrowserInspectParameters, BrowserNavigationData, BrowserOpenData, BrowserOpenParameters, BrowserProviderContext, BrowserProviderData, BrowserProviderRequest, BrowserProviderResult, BrowserResizeData, BrowserResizeParameters, BrowserScrollData, BrowserScrollDirection, BrowserScrollParameters, BrowserSnapshotData, BrowserSnapshotElement, BrowserSnapshotParameters, BrowserTab, BrowserTabTarget, BrowserTypeData, BrowserTypeParameters, BrowserViewportMode, BrowserViewportSummary, } from './service-providers.ts';

package/dist/index.js

@@ -1,11 +1,14 @@
 export { OPENCHAMBER_SDK_API_VERSION, OPENCHAMBER_SDK_CHANNEL, OPENCHAMBER_SDK_MANIFEST_API_VERSIONS } from "./api-version.js";
 export { GUEST_SCROLLBAR_CSS, GUEST_SCROLLBAR_SCRIPT } from "./scrollbar-style.js";
 export { guestFramePolicy } from "./frame-policy.js";
-export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES } from "./workspace.js";
+export { GUEST_STORAGE_KEY_MAX, GUEST_STORAGE_KEYS_MAX, GUEST_STORAGE_VALUE_BYTES, GUEST_STORAGE_TOTAL_BYTES, GUEST_DEVICE_STORAGE_TOTAL_BYTES } from "./workspace.js";
+export { GUEST_SHELL_END_STATUSES, GUEST_SHELL_ID_MAX, GUEST_SHELLS_MAX, GUEST_SHELL_OUTPUT_TAIL_MAX, } from "./shells.js";
+export { GUEST_STATUS_CONTROLS_MAX, GUEST_STATUS_CONTROL_ID, GUEST_STATUS_CONTROL_LABEL_MAX, GUEST_STATUS_CONTROL_OPTIONS_MAX, GUEST_STATUS_CONTROL_VALUE_MAX } from "./status-controls.js";
 export { compareOpenChamberVersions, hostMeetsOpenChamberEngine, openChamberEngineMinimum, OPENCHAMBER_ENGINE_PATTERN, parseOpenChamberVersion, } from "./host-version.js";
 export { DECLARED_GUEST_CAPABILITIES, GUEST_ACTIONS_MAX, GUEST_ACTION_LABEL_MAX, GUEST_CAPABILITIES, GUEST_COMMANDS_MAX, GUEST_COMMAND_DESCRIPTION_MAX, GUEST_COMMAND_NAME, GUEST_TOOLS_MAX, GUEST_TOOL_COLUMNS_MAX, GUEST_TOOL_COLUMN_MAX, GUEST_TOOL_LANGUAGE_MAX, GUEST_TOOL_MATCH, GUEST_TOOL_MATCH_MAX, GUEST_TOOL_NAME_MAX, GUEST_TOOL_OUTPUTS, GUEST_TOOL_TEMPLATE_MAX, GUEST_TOOL_TEMPLATE_VALUE_MAX, guestActionsNeedConversation, GUEST_FILESYSTEM_PATTERN_MAX, GUEST_FILESYSTEM_PATTERNS_MAX, GUEST_ORIGINS_MAX, GUEST_SERVICE_PROVIDES, GUEST_SURFACE_DOCKS, GUEST_SURFACE_DOCK_DEFAULT, GUEST_SURFACE_DOCK_SIZE_DEFAULT, GUEST_SURFACE_DOCK_SIZE_MAX, GUEST_SURFACE_DOCK_SIZE_MIN, GUEST_STATUS_SECTION_HEIGHT_DEFAULT, GUEST_STATUS_SECTION_HEIGHT_MAX, GUEST_STATUS_SECTION_HEIGHT_MIN, GUEST_STATUS_SECTION_TITLE_MAX, clampStatusSectionHeight, HOST_LINEAR_API_ORIGIN, isGuestFilesystemPattern, hasGuestCapability, hasGuestPage, isGuestApproved, isGuestPackageSvgIcon, requestedGuestCapabilities, resolveAttachEntry, resolvePageEntry, resolveStatusSectionEntry, resolveAttachMode, resolveIntegrationApi, resolveIntegrationAuth, serviceProvides, toPublicService, toPublicIntegration, } from "./manifest.js";
 export { GUEST_FILE_EDITORS_MAX, GUEST_FILE_EDITOR_CONTENT_MAX, GUEST_FILE_EDITOR_PATTERNS_MAX, GUEST_FILE_EDITOR_PATTERN_MAX, GUEST_FILE_EDITOR_TITLE_MAX, GUEST_FILE_EDITOR_VERSION_MAX, createFileSaveTracker, fileEditorPayloadSize, isFileEditorPattern, matchesFileEditorPattern, } from "./file-editor.js";
 export { connectHost, HostRequestError } from "./host.js";
+export { GUEST_POPOVER_COORDINATE_MAX, GUEST_POPOVER_DATA_DEPTH_MAX, GUEST_POPOVER_DATA_MAX, GUEST_POPOVER_HEIGHT_MAX, GUEST_POPOVER_HEIGHT_MIN, GUEST_POPOVER_ID, GUEST_POPOVER_SIDES, GUEST_POPOVER_WIDTH_MAX, GUEST_POPOVER_WIDTH_MIN, GUEST_POPOVER_CLOSE_REASONS, isGuestPopoverRequest, } from "./popover.js";
 export { clampAttachRequest, clampBadgeCount, clampFrameHeight, isGuestCommitSha, GUEST_COMMIT_SHA, clampPromptRequest, clampStartSessionRequest, guestFileScope, isAttachData, isJsonValue, isFileListResult, isFileReadResult, isFileStatResult, isGenerateResult, isFileWriteResult, isGuestFilePath, isGuestAttachItem, isGuestMessageItem, isGuestSessionItem, isServiceStatusResult, isGuestRequestPath, isGuestRequestResult, isHostRequestErrorCode, isPromptResult, isStartSessionResult, readHostMessage, resolveHostRequestErrorCode, } from "./contract.js";
 export { EMPTY_GUEST_CONNECTION, GUEST_BADGE_MAX, GUEST_FRAME_HEIGHT_MAX, GUEST_ITEM_MESSAGE_TEXT_MAX, GUEST_ITEM_SESSION_MAX, GUEST_RESOLVE_ERROR_MAX, GUEST_FILE_CONTENT_MAX, GUEST_FILE_ENTRY_KINDS, GUEST_FILE_LIST_MAX, GUEST_FILE_PATH_MAX, GUEST_GENERATE_OUTPUT_TOKENS_MAX, GUEST_GENERATE_PROMPT_MAX, GUEST_GENERATE_SYSTEM_MAX, GUEST_GENERATE_TEXT_MAX, GUEST_GENERATE_TIMEOUT_MS, GUEST_FILE_STAT_KINDS, SERVICE_STATUS_VALUES, HOST_REQUEST_ERROR_CODES, SESSION_LIFECYCLE_PHASES, START_SESSION_SENT, GUEST_ACCOUNT_MAX, GUEST_SESSION_AGENT_MAX, GUEST_SESSION_MODEL_MAX, GUEST_ATTACH_AUTHOR_MAX, GUEST_ATTACH_BRANCH_MAX, GUEST_ATTACH_DATA_MAX, GUEST_ATTACH_ID_MAX, GUEST_ATTACH_TEXT_MAX, GUEST_ATTACH_TITLE_MAX, GUEST_ATTACH_URL_MAX, GUEST_CLIPBOARD_TEXT_MAX, GUEST_TOAST_MAX, GUEST_COMPOSE_TEXT_MAX, GUEST_REQUEST_BODY_MAX, GUEST_REQUEST_PATH_MAX, GUEST_REQUEST_RESPONSE_MAX, GUEST_REQUEST_TIMEOUT_MS, GUEST_SETTING_VALUE_MAX, } from "./contract.js";
 export { BROWSER_CONTROL_ACTIONS, BROWSER_PROVIDER_ACTION_TIMEOUT_MS, BROWSER_PROVIDER_IDLE_MS, BROWSER_PROVIDER_OPEN_TIMEOUT_MS, BROWSER_PROVIDER_PATH, BROWSER_PROVIDER_RESPONSE_MAX, BROWSER_SCROLL_DIRECTIONS, BROWSER_VIEWPORT_MODES, isBrowserControlAction, readBrowserProviderRequest, } from "./service-providers.js";

package/dist/manifest.d.ts

@@ -60,6 +60,8 @@ export type StatusSectionContribution = true | {
     entry: string;
     title?: string;
     height?: number;
+    defaultExpanded?: boolean;
+    requiresProject?: boolean;
 };
 /** Characters in a status section title. */
 export declare const GUEST_STATUS_SECTION_TITLE_MAX = 60;
@@ -271,15 +273,15 @@ export declare const serviceProvides: (service: Pick<ServiceContribution, "provi
 /**
  * What a guest may do beyond drawing its own panel. The user approves the
  * full list once, when the package is installed; a later package that asks
- * for more is re-approved. `prompt`, `sessions`, `files`, and `model` are
- * declared under `contributes.capabilities`; `service`, `network`,
+ * for more is re-approved. `prompt`, `sessions`, `files`, `model`, and
+ * `shells` are declared under `contributes.capabilities`; `service`, `network`,
  * `filesystem` and `origins` follow from `contributes.service`,
  * `contributes.integration`, `contributes.filesystem` and `contributes.origins`. `model` is one-off text generation with the
  * user's Small Model (`host.generate`), outside any session.
  */
-export declare const GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model", "conversation", "service", "network", "filesystem", "origins"];
+export declare const GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model", "shells", "conversation", "service", "network", "filesystem", "origins"];
 export type GuestCapability = (typeof GUEST_CAPABILITIES)[number];
-export declare const DECLARED_GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model"];
+export declare const DECLARED_GUEST_CAPABILITIES: readonly ["prompt", "sessions", "files", "model", "shells"];
 /** The capabilities a manifest may ask for directly. */
 export type DeclaredGuestCapability = (typeof DECLARED_GUEST_CAPABILITIES)[number];
 /** How many `contributes.origins` a package may declare. */

package/dist/manifest.js

@@ -96,14 +96,14 @@ export const serviceProvides = (service, role) => Boolean(service?.provides?.inc
 /**
  * What a guest may do beyond drawing its own panel. The user approves the
  * full list once, when the package is installed; a later package that asks
- * for more is re-approved. `prompt`, `sessions`, `files`, and `model` are
- * declared under `contributes.capabilities`; `service`, `network`,
+ * for more is re-approved. `prompt`, `sessions`, `files`, `model`, and
+ * `shells` are declared under `contributes.capabilities`; `service`, `network`,
  * `filesystem` and `origins` follow from `contributes.service`,
  * `contributes.integration`, `contributes.filesystem` and `contributes.origins`. `model` is one-off text generation with the
  * user's Small Model (`host.generate`), outside any session.
  */
-export const GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model', 'conversation', 'service', 'network', 'filesystem', 'origins'];
-export const DECLARED_GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model'];
+export const GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model', 'shells', 'conversation', 'service', 'network', 'filesystem', 'origins'];
+export const DECLARED_GUEST_CAPABILITIES = ['prompt', 'sessions', 'files', 'model', 'shells'];
 /** How many `contributes.origins` a package may declare. */
 export const GUEST_ORIGINS_MAX = 8;
 /** How many `contributes.filesystem` patterns a package may declare. */

package/dist/parse.d.ts

@@ -12,10 +12,10 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             icon: z.ZodString;
             entry: z.ZodOptional<z.ZodString>;
             dock: z.ZodOptional<z.ZodEnum<{
-                top: "top";
-                bottom: "bottom";
                 left: "left";
                 right: "right";
+                top: "top";
+                bottom: "bottom";
             }>>;
             size: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strip>;
@@ -40,8 +40,11 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             entry: z.ZodString;
             title: z.ZodOptional<z.ZodString>;
             height: z.ZodOptional<z.ZodNumber>;
+            defaultExpanded: z.ZodOptional<z.ZodBoolean>;
+            requiresProject: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>]>>;
         capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            shells: "shells";
             sessions: "sessions";
             prompt: "prompt";
             files: "files";
@@ -121,8 +124,8 @@ export declare const openChamberManifestSchema: z.ZodObject<{
             label: z.ZodString;
             icon: z.ZodOptional<z.ZodString>;
             where: z.ZodEnum<{
-                message: "message";
                 session: "session";
+                message: "message";
             }>;
             mode: z.ZodOptional<z.ZodEnum<{
                 background: "background";
@@ -184,10 +187,10 @@ export declare const packageManifestSchema: z.ZodObject<{
                 icon: z.ZodString;
                 entry: z.ZodOptional<z.ZodString>;
                 dock: z.ZodOptional<z.ZodEnum<{
-                    top: "top";
-                    bottom: "bottom";
                     left: "left";
                     right: "right";
+                    top: "top";
+                    bottom: "bottom";
                 }>>;
                 size: z.ZodOptional<z.ZodNumber>;
             }, z.core.$strip>;
@@ -212,8 +215,11 @@ export declare const packageManifestSchema: z.ZodObject<{
                 entry: z.ZodString;
                 title: z.ZodOptional<z.ZodString>;
                 height: z.ZodOptional<z.ZodNumber>;
+                defaultExpanded: z.ZodOptional<z.ZodBoolean>;
+                requiresProject: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>]>>;
             capabilities: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                shells: "shells";
                 sessions: "sessions";
                 prompt: "prompt";
                 files: "files";
@@ -293,8 +299,8 @@ export declare const packageManifestSchema: z.ZodObject<{
                 label: z.ZodString;
                 icon: z.ZodOptional<z.ZodString>;
                 where: z.ZodEnum<{
-                    message: "message";
                     session: "session";
+                    message: "message";
                 }>;
                 mode: z.ZodOptional<z.ZodEnum<{
                     background: "background";

package/dist/parse.js

@@ -215,6 +215,8 @@ const contributesSchema = z.object({
             entry: z.string().trim().refine((value) => isSafeAssetPath(value) && value.toLowerCase().endsWith('.html')),
             title: z.string().trim().min(1).max(GUEST_STATUS_SECTION_TITLE_MAX).optional(),
             height: z.number().int().min(GUEST_STATUS_SECTION_HEIGHT_MIN).max(GUEST_STATUS_SECTION_HEIGHT_MAX).optional(),
+            defaultExpanded: z.boolean().optional(),
+            requiresProject: z.boolean().optional(),
         })]).optional(),
     capabilities: z.array(z.enum(DECLARED_GUEST_CAPABILITIES)).max(8).optional(),
     integration: integrationSchema.optional(),

package/dist/popover-schemas.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { JsonValue } from './contract.ts';
+export declare const guestPopoverDataSchema: z.ZodCustom<JsonValue, JsonValue>;
+export declare const guestPopoverRequestSchema: z.ZodObject<{
+    id: z.ZodString;
+    anchor: z.ZodObject<{
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        width: z.ZodNumber;
+        height: z.ZodNumber;
+    }, z.core.$strict>;
+    width: z.ZodNumber;
+    height: z.ZodNumber;
+    side: z.ZodOptional<z.ZodEnum<{
+        left: "left";
+        right: "right";
+        top: "top";
+        bottom: "bottom";
+    }>>;
+    focus: z.ZodOptional<z.ZodBoolean>;
+    data: z.ZodCustom<JsonValue, JsonValue>;
+}, z.core.$strict>;
+export declare const guestPopoverClosedEventSchema: z.ZodObject<{
+    id: z.ZodString;
+    reason: z.ZodEnum<{
+        escape: "escape";
+        outside: "outside";
+        anchor: "anchor";
+        owner: "owner";
+        closed: "closed";
+        replaced: "replaced";
+    }>;
+}, z.core.$strict>;

package/dist/popover-schemas.js

@@ -0,0 +1,74 @@
+import { z } from 'zod';
+import { GUEST_POPOVER_CLOSE_REASONS, GUEST_POPOVER_COORDINATE_MAX, GUEST_POPOVER_DATA_MAX, GUEST_POPOVER_DATA_DEPTH_MAX, GUEST_POPOVER_HEIGHT_MAX, GUEST_POPOVER_HEIGHT_MIN, GUEST_POPOVER_ID, GUEST_POPOVER_SIDES, GUEST_POPOVER_WIDTH_MAX, GUEST_POPOVER_WIDTH_MIN, } from "./popover.js";
+const jsonPrimitive = z.union([z.string().max(GUEST_POPOVER_DATA_MAX), z.number(), z.boolean(), z.null()]);
+const jsonRecord = z.record(z.string().max(GUEST_POPOVER_DATA_MAX), z.unknown());
+// Parse one level at a time: recursive z.json() would traverse a hostile cycle
+// or deeply nested structured-clone payload before its size/depth refinement.
+export const guestPopoverDataSchema = z.custom((value) => {
+    const pending = [{ value, depth: 0 }];
+    let size = 0;
+    while (pending.length > 0) {
+        const current = pending.pop();
+        if (!current)
+            break;
+        const item = current.value;
+        if (current.depth >= GUEST_POPOVER_DATA_DEPTH_MAX)
+            return false;
+        if (Array.isArray(item)) {
+            if (item.length > GUEST_POPOVER_DATA_MAX)
+                return false;
+            if (Object.keys(item).some((key) => !/^(0|[1-9]\d*)$/.test(key) || Number(key) >= item.length))
+                return false;
+            size += 2 + Math.max(0, item.length - 1);
+            for (const child of item)
+                pending.push({ value: child, depth: current.depth + 1 });
+        }
+        else {
+            const primitive = jsonPrimitive.safeParse(item);
+            if (primitive.success) {
+                size += JSON.stringify(primitive.data).length;
+            }
+            else {
+                const record = jsonRecord.safeParse(item);
+                if (!record.success)
+                    return false;
+                const prototype = Object.getPrototypeOf(item);
+                if (prototype !== null && prototype !== Object.prototype)
+                    return false;
+                // z.record normalizes prototype-named keys. Validate the original
+                // structured-clone values so those keys cannot escape the budget.
+                const entries = Object.entries(Object.getOwnPropertyDescriptors(item)).filter(([, descriptor]) => descriptor.enumerable);
+                size += 2 + Math.max(0, entries.length - 1);
+                for (const [key, descriptor] of entries) {
+                    if (!('value' in descriptor))
+                        return false;
+                    size += JSON.stringify(key).length + 1;
+                    if (size > GUEST_POPOVER_DATA_MAX)
+                        return false;
+                    pending.push({ value: descriptor.value, depth: current.depth + 1 });
+                }
+            }
+        }
+        if (size > GUEST_POPOVER_DATA_MAX)
+            return false;
+    }
+    return true;
+}, 'Popover data must be finite JSON within its size and depth limits.');
+export const guestPopoverRequestSchema = z.object({
+    id: z.string().regex(GUEST_POPOVER_ID),
+    anchor: z.object({
+        x: z.number().finite().min(-GUEST_POPOVER_COORDINATE_MAX).max(GUEST_POPOVER_COORDINATE_MAX),
+        y: z.number().finite().min(-GUEST_POPOVER_COORDINATE_MAX).max(GUEST_POPOVER_COORDINATE_MAX),
+        width: z.number().finite().positive().max(GUEST_POPOVER_COORDINATE_MAX),
+        height: z.number().finite().positive().max(GUEST_POPOVER_COORDINATE_MAX),
+    }).strict(),
+    width: z.number().int().min(GUEST_POPOVER_WIDTH_MIN).max(GUEST_POPOVER_WIDTH_MAX),
+    height: z.number().int().min(GUEST_POPOVER_HEIGHT_MIN).max(GUEST_POPOVER_HEIGHT_MAX),
+    side: z.enum(GUEST_POPOVER_SIDES).optional(),
+    focus: z.boolean().optional(),
+    data: guestPopoverDataSchema,
+}).strict();
+export const guestPopoverClosedEventSchema = z.object({
+    id: z.string().regex(GUEST_POPOVER_ID),
+    reason: z.enum(GUEST_POPOVER_CLOSE_REASONS),
+}).strict();