@openchamber/sdk 2.0.4 → 2.1.1

package/dist/host.js

@@ -1,5 +1,7 @@
 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";
 // Structural, not `instanceof KeyboardEvent`: the frame's own realm owns that
@@ -18,6 +20,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 +48,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();
@@ -49,6 +63,9 @@ export const connectHost = (options = {}) => {
     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;
@@ -146,6 +163,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 +299,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.`);
@@ -317,11 +382,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;
@@ -357,14 +437,34 @@ export const connectHost = (options = {}) => {
             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 +526,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 () => {
@@ -735,6 +865,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 +883,8 @@ export const connectHost = (options = {}) => {
             connectionListeners.clear();
             settingsListeners.clear();
             itemListeners.clear();
+            statusControlListeners.clear();
+            popoverClosedListeners.clear();
         },
     };
 };

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 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 { 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 +13,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, 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, 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,13 @@
 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_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;

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,6 +40,8 @@ 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<{
             sessions: "sessions";
@@ -184,10 +186,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,6 +214,8 @@ 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<{
                 sessions: "sessions";

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();

package/dist/popover.d.ts

@@ -0,0 +1,37 @@
+import type { JsonValue } from './contract.ts';
+export declare const GUEST_POPOVER_ID: RegExp;
+export declare const GUEST_POPOVER_COORDINATE_MAX = 100000;
+export declare const GUEST_POPOVER_WIDTH_MIN = 160;
+export declare const GUEST_POPOVER_WIDTH_MAX = 640;
+export declare const GUEST_POPOVER_HEIGHT_MIN = 48;
+export declare const GUEST_POPOVER_HEIGHT_MAX = 480;
+export declare const GUEST_POPOVER_DATA_MAX = 16000;
+export declare const GUEST_POPOVER_DATA_DEPTH_MAX = 32;
+export declare const GUEST_POPOVER_SIDES: readonly ["left", "right", "top", "bottom"];
+export type GuestPopoverSide = (typeof GUEST_POPOVER_SIDES)[number];
+export type GuestPopoverAnchor = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type GuestPopoverRequest = {
+    id: string;
+    anchor: GuestPopoverAnchor;
+    width: number;
+    height: number;
+    side?: GuestPopoverSide;
+    focus?: boolean;
+    data: JsonValue;
+};
+export type GuestPopoverContext = {
+    id: string;
+    data: JsonValue;
+};
+export declare const GUEST_POPOVER_CLOSE_REASONS: readonly ["escape", "outside", "anchor", "owner", "closed", "replaced"];
+export type GuestPopoverClosedEvent = {
+    id: string;
+    reason: (typeof GUEST_POPOVER_CLOSE_REASONS)[number];
+};
+/** Guest-side fast-fail guard. The host schema remains authoritative for untyped callers. */
+export declare const isGuestPopoverRequest: (request: GuestPopoverRequest) => boolean;

package/dist/popover.js

@@ -0,0 +1,57 @@
+export const GUEST_POPOVER_ID = /^[A-Za-z0-9_-]{1,80}$/;
+export const GUEST_POPOVER_COORDINATE_MAX = 100_000;
+export const GUEST_POPOVER_WIDTH_MIN = 160;
+export const GUEST_POPOVER_WIDTH_MAX = 640;
+export const GUEST_POPOVER_HEIGHT_MIN = 48;
+export const GUEST_POPOVER_HEIGHT_MAX = 480;
+export const GUEST_POPOVER_DATA_MAX = 16_000;
+export const GUEST_POPOVER_DATA_DEPTH_MAX = 32;
+export const GUEST_POPOVER_SIDES = ['left', 'right', 'top', 'bottom'];
+export const GUEST_POPOVER_CLOSE_REASONS = ['escape', 'outside', 'anchor', 'owner', 'closed', 'replaced'];
+const hasBoundedJsonTree = (value, depth = 0, budget = { remaining: GUEST_POPOVER_DATA_MAX }) => {
+    if (--budget.remaining < 0 || depth >= GUEST_POPOVER_DATA_DEPTH_MAX)
+        return false;
+    if (value === null)
+        return true;
+    const children = Array.isArray(value) ? value : Object(value) === value ? Object.values(value) : [];
+    for (const item of children) {
+        if (!hasBoundedJsonTree(item, depth + 1, budget))
+            return false;
+    }
+    return true;
+};
+// Used only after the depth bound above, including for JavaScript consumers
+// whose values need not satisfy the public JsonValue type.
+const isFiniteJson = (value) => {
+    if (value === null || value === true || value === false)
+        return true;
+    if (Array.isArray(value))
+        return Object.keys(value).every((key) => /^(0|[1-9]\d*)$/.test(key) && Number(key) < value.length)
+            && value.every(isFiniteJson);
+    if (Object(value) === value) {
+        const prototype = Object.getPrototypeOf(value);
+        return (prototype === null || prototype === Object.prototype) && Object.values(value).every(isFiniteJson);
+    }
+    return String(value) === value || Number.isFinite(value);
+};
+/** Guest-side fast-fail guard. The host schema remains authoritative for untyped callers. */
+export const isGuestPopoverRequest = (request) => {
+    try {
+        if (String(request.id) !== request.id || !GUEST_POPOVER_ID.test(request.id)
+            || !Number.isFinite(request.anchor.x) || Math.abs(request.anchor.x) > GUEST_POPOVER_COORDINATE_MAX
+            || !Number.isFinite(request.anchor.y) || Math.abs(request.anchor.y) > GUEST_POPOVER_COORDINATE_MAX
+            || !Number.isFinite(request.anchor.width) || !Number.isFinite(request.anchor.height)
+            || request.anchor.width <= 0 || request.anchor.height <= 0
+            || request.anchor.width > GUEST_POPOVER_COORDINATE_MAX || request.anchor.height > GUEST_POPOVER_COORDINATE_MAX
+            || !Number.isInteger(request.width) || request.width < GUEST_POPOVER_WIDTH_MIN || request.width > GUEST_POPOVER_WIDTH_MAX
+            || !Number.isInteger(request.height) || request.height < GUEST_POPOVER_HEIGHT_MIN || request.height > GUEST_POPOVER_HEIGHT_MAX
+            || (request.side !== undefined && !GUEST_POPOVER_SIDES.includes(request.side))
+            || (request.focus !== undefined && request.focus !== true && request.focus !== false)
+            || !hasBoundedJsonTree(request.data) || !isFiniteJson(request.data))
+            return false;
+        return JSON.stringify(request.data).length <= GUEST_POPOVER_DATA_MAX;
+    }
+    catch {
+        return false;
+    }
+};