@wonderwhy-er/desktop-commander 0.2.37 → 0.2.39

package/dist/ui/file-preview/types.d.ts

@@ -0,0 +1 @@
+export type HtmlPreviewMode = 'rendered' | 'source';

package/dist/ui/file-preview/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/resources.d.ts

@@ -4,7 +4,14 @@ export declare const FILE_PREVIEW_RESOURCE: {
     description: string;
     mimeType: string;
 };
+export declare const CONFIG_EDITOR_RESOURCE: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+};
 export declare function getFilePreviewResourceText(): Promise<string>;
+export declare function getConfigEditorResourceText(): Promise<string>;
 export declare function listUiResources(): {
     uri: string;
     name: string;

package/dist/ui/resources.js

@@ -4,7 +4,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { FILE_PREVIEW_RESOURCE_URI } from './contracts.js';
+import { CONFIG_EDITOR_RESOURCE_URI, FILE_PREVIEW_RESOURCE_URI } from './contracts.js';
 const UI_RESOURCE_MIME_TYPE = 'text/html;profile=mcp-app';
 export const FILE_PREVIEW_RESOURCE = {
     uri: FILE_PREVIEW_RESOURCE_URI,
@@ -12,9 +12,16 @@ export const FILE_PREVIEW_RESOURCE = {
     description: 'Markdown-first preview surface for read_file structured content.',
     mimeType: UI_RESOURCE_MIME_TYPE
 };
+export const CONFIG_EDITOR_RESOURCE = {
+    uri: CONFIG_EDITOR_RESOURCE_URI,
+    name: 'Desktop Commander Config Editor',
+    description: 'Interactive editor for Desktop Commander configuration values.',
+    mimeType: UI_RESOURCE_MIME_TYPE
+};
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const DIST_FILE_PREVIEW_DIR = path.resolve(__dirname, 'file-preview');
+const DIST_CONFIG_EDITOR_DIR = path.resolve(__dirname, 'config-editor');
 function replaceOrThrow(source, pattern, replacement, context) {
     if (!pattern.test(source)) {
         throw new Error(`UI template is missing expected ${context}`);
@@ -43,14 +50,21 @@ async function readInlinedResourceHtml(distDir, runtimeFileName) {
 export async function getFilePreviewResourceText() {
     return readInlinedResourceHtml(DIST_FILE_PREVIEW_DIR, 'preview-runtime.js');
 }
+export async function getConfigEditorResourceText() {
+    return readInlinedResourceHtml(DIST_CONFIG_EDITOR_DIR, 'config-editor-runtime.js');
+}
 const READABLE_UI_RESOURCES = {
     [FILE_PREVIEW_RESOURCE_URI]: {
         mimeType: FILE_PREVIEW_RESOURCE.mimeType,
         getText: getFilePreviewResourceText
+    },
+    [CONFIG_EDITOR_RESOURCE_URI]: {
+        mimeType: CONFIG_EDITOR_RESOURCE.mimeType,
+        getText: getConfigEditorResourceText
     }
 };
 export function listUiResources() {
-    return [FILE_PREVIEW_RESOURCE];
+    return [FILE_PREVIEW_RESOURCE, CONFIG_EDITOR_RESOURCE];
 }
 export async function readUiResource(uri) {
     const resource = READABLE_UI_RESOURCES[uri];

package/dist/ui/server-integration.d.ts

@@ -0,0 +1,13 @@
+export declare function listUiResources(): {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}[];
+export declare function readUiResource(uri: string): Promise<{
+    contents: {
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+} | null>;

package/dist/ui/server-integration.js

@@ -0,0 +1,31 @@
+import { CONFIG_EDITOR_RESOURCE, FILE_PREVIEW_RESOURCE, getConfigEditorResourceText, getFilePreviewResourceText, } from './resources.js';
+import { CONFIG_EDITOR_RESOURCE_URI, FILE_PREVIEW_RESOURCE_URI } from './contracts.js';
+const READABLE_UI_RESOURCES = {
+    [FILE_PREVIEW_RESOURCE_URI]: {
+        mimeType: FILE_PREVIEW_RESOURCE.mimeType,
+        getText: getFilePreviewResourceText,
+    },
+    [CONFIG_EDITOR_RESOURCE_URI]: {
+        mimeType: CONFIG_EDITOR_RESOURCE.mimeType,
+        getText: getConfigEditorResourceText,
+    },
+};
+export function listUiResources() {
+    return [FILE_PREVIEW_RESOURCE, CONFIG_EDITOR_RESOURCE];
+}
+export async function readUiResource(uri) {
+    const resource = READABLE_UI_RESOURCES[uri];
+    if (!resource) {
+        return null;
+    }
+    const resourceText = await resource.getText();
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: resource.mimeType,
+                text: resourceText,
+            },
+        ],
+    };
+}

package/dist/ui/shared/ToolHeader.d.ts

@@ -0,0 +1,9 @@
+export interface ToolHeaderConfig {
+    pillLabel: string;
+    pillClassName?: string;
+    title: string;
+    subtitle: string;
+    badges: string[];
+    actionsHtml: string;
+}
+export declare function renderToolHeader(config: ToolHeaderConfig): string;

package/dist/ui/shared/ToolHeader.js

@@ -0,0 +1,29 @@
+function escapeHtml(value) {
+    return value
+        .split('&').join('&')
+        .split('<').join('&lt;')
+        .split('>').join('&gt;')
+        .split('"').join('&quot;')
+        .split("'").join('&#39;');
+}
+export function renderToolHeader(config) {
+    return `
+    <header class="toolbar">
+      <div class="meta">
+        <div class="meta-main">
+          <span class="file-pill ${escapeHtml(config.pillClassName ?? '')}">${escapeHtml(config.pillLabel)}</span>
+          <div class="meta-text">
+            <span class="filename" title="${escapeHtml(config.title)}">${escapeHtml(config.title)}</span>
+            <span class="filepath" title="${escapeHtml(config.subtitle)}">${escapeHtml(config.subtitle)}</span>
+          </div>
+        </div>
+        <div class="meta-badges">
+          ${config.badges.map((badge) => `<span class="badge">${escapeHtml(badge)}</span>`).join('')}
+        </div>
+      </div>
+      <div class="actions">
+        ${config.actionsHtml}
+      </div>
+    </header>
+  `;
+}

package/dist/ui/shared/app-bootstrap.d.ts

@@ -0,0 +1,9 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+import { type UiChromeState } from './host-context.js';
+export interface ConnectWithSharedHostContextOptions {
+    app: App;
+    chrome: UiChromeState;
+    onContextApplied?: () => void;
+    onConnected?: () => void | Promise<void>;
+}
+export declare function connectWithSharedHostContext(options: ConnectWithSharedHostContextOptions): Promise<void>;

package/dist/ui/shared/app-bootstrap.js

@@ -0,0 +1,15 @@
+import { applySharedHostContext } from './host-context.js';
+export async function connectWithSharedHostContext(options) {
+    const { app, chrome, onContextApplied, onConnected } = options;
+    app.onhostcontextchanged = (context) => {
+        applySharedHostContext(context, chrome);
+        onContextApplied?.();
+    };
+    await app.connect();
+    const hostContext = app.getHostContext();
+    if (hostContext) {
+        applySharedHostContext(hostContext, chrome);
+        onContextApplied?.();
+    }
+    await onConnected?.();
+}

package/dist/ui/shared/compact-row.d.ts

@@ -0,0 +1,11 @@
+interface RenderCompactRowOptions {
+    id?: string;
+    label: string;
+    filename?: string;
+    variant?: 'ready' | 'loading' | 'status';
+    expandable?: boolean;
+    expanded?: boolean;
+    interactive?: boolean;
+}
+export declare function renderCompactRow(options: RenderCompactRowOptions): string;
+export {};

package/dist/ui/shared/compact-row.js

@@ -0,0 +1,18 @@
+import { escapeHtml } from './escape-html.js';
+export function renderCompactRow(options) {
+    const variant = options.variant ?? 'ready';
+    const classNames = `compact-row compact-row--${variant}`;
+    const id = options.id ? ` id="${escapeHtml(options.id)}"` : '';
+    const interactive = options.interactive ?? variant === 'ready';
+    const role = interactive ? ' role="button" tabindex="0"' : '';
+    const ariaExpanded = typeof options.expanded === 'boolean'
+        ? ` aria-expanded="${String(options.expanded)}"`
+        : '';
+    const chevron = options.expandable
+        ? '<svg class="compact-chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 6l6 6-6 6z"/></svg>'
+        : '';
+    const filename = options.filename
+        ? `<span class="compact-filename">${escapeHtml(options.filename)}</span>`
+        : '';
+    return `<div class="${classNames}"${id}${role}${ariaExpanded}>${chevron}<span class="compact-label">${escapeHtml(options.label)}</span>${filename}</div>`;
+}

package/dist/ui/shared/guards.d.ts

@@ -0,0 +1 @@
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;

package/dist/ui/shared/guards.js

@@ -0,0 +1,3 @@
+export function isObjectRecord(value) {
+    return typeof value === 'object' && value !== null;
+}

package/dist/ui/shared/host-context.d.ts

@@ -0,0 +1,15 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+export interface UiChromeState {
+    expanded: boolean;
+    hideSummaryRow: boolean;
+    compact?: boolean;
+}
+export interface ConnectWithSharedHostContextOptions {
+    app: App;
+    chrome: UiChromeState;
+    onContextApplied?: () => void;
+    onConnected?: () => void | Promise<void>;
+}
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;
+export declare function applySharedHostContext(context: unknown, chrome: UiChromeState): void;
+export declare function connectWithSharedHostContext(options: ConnectWithSharedHostContextOptions): Promise<void>;

package/dist/ui/shared/host-context.js

@@ -0,0 +1,51 @@
+import { applyDocumentTheme, applyHostFonts, applyHostStyleVariables } from '@modelcontextprotocol/ext-apps';
+export function isObjectRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function applySharedHostContext(context, chrome) {
+    if (!isObjectRecord(context)) {
+        return;
+    }
+    if (context.theme === 'light' || context.theme === 'dark') {
+        applyDocumentTheme(context.theme);
+    }
+    const styles = isObjectRecord(context.styles) ? context.styles : null;
+    const variables = isObjectRecord(styles?.variables) ? styles.variables : null;
+    const css = isObjectRecord(styles?.css) ? styles.css : null;
+    const fonts = typeof css?.fonts === 'string' ? css.fonts : null;
+    if (variables) {
+        applyHostStyleVariables(variables);
+    }
+    if (fonts) {
+        applyHostFonts(fonts);
+    }
+    if (typeof context.initiallyExpanded === 'boolean') {
+        chrome.expanded = context.initiallyExpanded;
+    }
+    if (typeof context.compact === 'boolean' && typeof chrome.compact === 'boolean') {
+        chrome.compact = context.compact;
+    }
+    if (typeof context.hideSummaryRow === 'boolean') {
+        chrome.hideSummaryRow = context.hideSummaryRow;
+        if (context.hideSummaryRow) {
+            chrome.expanded = true;
+            if (typeof chrome.compact === 'boolean') {
+                chrome.compact = true;
+            }
+        }
+    }
+}
+export async function connectWithSharedHostContext(options) {
+    const { app, chrome, onContextApplied, onConnected } = options;
+    app.onhostcontextchanged = (context) => {
+        applySharedHostContext(context, chrome);
+        onContextApplied?.();
+    };
+    await app.connect();
+    const hostContext = app.getHostContext();
+    if (hostContext) {
+        applySharedHostContext(hostContext, chrome);
+        onContextApplied?.();
+    }
+    await onConnected?.();
+}

package/dist/ui/shared/host-lifecycle.d.ts

@@ -6,6 +6,7 @@ interface UiHostLifecycleOptions {
     appName: string;
     appVersion?: string;
     getRootElement?: () => Element | null;
+    onHostContext?: (hostContext: Record<string, unknown>) => void;
 }
 export interface UiHostLifecycle {
     notifyRender: () => void;

package/dist/ui/shared/host-lifecycle.js

@@ -1,5 +1,5 @@
 export function createUiHostLifecycle(rpcClient, options) {
-    const { appName, appVersion = '1.0.0', getRootElement } = options;
+    const { appName, appVersion = '1.0.0', getRootElement, onHostContext } = options;
     const resolveRootElement = () => getRootElement?.() ?? (document.getElementById('app')?.firstElementChild ?? document.getElementById('app'));
     const notifySizeChanged = () => {
         const node = resolveRootElement();
@@ -23,7 +23,13 @@ export function createUiHostLifecycle(rpcClient, options) {
                 appInfo: { name: appName, version: appVersion },
                 appCapabilities: {},
                 protocolVersion: '2026-01-26',
-            }).then(() => {
+            }).then((response) => {
+                if (onHostContext && response !== null && typeof response === 'object') {
+                    const hostContext = response.hostContext;
+                    if (hostContext !== null && typeof hostContext === 'object') {
+                        onHostContext(hostContext);
+                    }
+                }
                 rpcClient.notify('ui/notifications/initialized', {});
             }).catch(() => {
                 // Initialization handshake failure should not break rendering.

package/dist/ui/shared/tool-bridge.d.ts

@@ -0,0 +1,30 @@
+type ToolArgs = Record<string, unknown>;
+type ToolHelper = {
+    callTool: (name: string, args: ToolArgs) => Promise<unknown> | unknown;
+};
+type MessageEventLike = {
+    data: unknown;
+    origin?: string;
+    source?: unknown;
+};
+type MessageListener = (event: MessageEventLike) => void;
+type MessageTarget = {
+    postMessage: (message: unknown, targetOrigin?: string) => void;
+};
+type BridgeHost = {
+    openai?: ToolHelper;
+    mcp?: ToolHelper;
+    parent?: MessageTarget;
+    addEventListener?: (type: 'message', listener: MessageListener) => void;
+    removeEventListener?: (type: 'message', listener: MessageListener) => void;
+};
+export interface ToolBridgeOptions {
+    host?: BridgeHost;
+    requestTimeoutMs?: number;
+    targetOrigin?: string;
+    idPrefix?: string;
+}
+export declare function createToolBridge(options?: ToolBridgeOptions): {
+    callTool: (name: string, args?: ToolArgs) => Promise<unknown>;
+};
+export {};

package/dist/ui/shared/tool-bridge.js

@@ -0,0 +1,137 @@
+const DEFAULT_TIMEOUT_MS = 5000;
+function getDefaultTargetOrigin() {
+    if (typeof document === 'undefined') {
+        return '*';
+    }
+    const referrer = document.referrer;
+    if (typeof referrer !== 'string' || referrer.trim().length === 0) {
+        return '*';
+    }
+    try {
+        return new URL(referrer).origin;
+    }
+    catch {
+        return '*';
+    }
+}
+function normalizeTargetOrigin(value) {
+    if (value === '*') {
+        return value;
+    }
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        throw new Error(`Invalid targetOrigin: ${value}`);
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function normalizeToolArgs(args) {
+    return args ?? {};
+}
+function extractErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+function isHelperUnavailableError(error) {
+    if (!isObject(error)) {
+        return false;
+    }
+    const code = typeof error.code === 'string' ? error.code.toLowerCase() : '';
+    if (code === 'not_implemented' || code === 'not_supported' || code === 'unavailable') {
+        return true;
+    }
+    const message = extractErrorMessage(error).toLowerCase();
+    return message.includes('not implemented')
+        || message.includes('not supported')
+        || message.includes('unavailable')
+        || message.includes('not available');
+}
+export function createToolBridge(options = {}) {
+    const host = options.host ?? globalThis;
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const targetOrigin = normalizeTargetOrigin(options.targetOrigin ?? getDefaultTargetOrigin());
+    const idPrefix = options.idPrefix ?? 'tool-bridge';
+    let requestCounter = 0;
+    async function callViaFallback(name, args) {
+        if (!host.parent || !host.addEventListener || !host.removeEventListener) {
+            throw new Error('JSON-RPC fallback is unavailable in this host environment.');
+        }
+        const parent = host.parent;
+        const addListener = (type, listener) => {
+            host.addEventListener?.(type, listener);
+        };
+        const removeListener = (type, listener) => {
+            host.removeEventListener?.(type, listener);
+        };
+        requestCounter += 1;
+        const requestId = `${idPrefix}:${requestCounter}`;
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                removeListener('message', onMessage);
+                reject(new Error(`Tool call fallback timed out after ${timeoutMs}ms (request: ${requestId})`));
+            }, timeoutMs);
+            const onMessage = (event) => {
+                const payload = event.data;
+                if (event.source !== parent) {
+                    return;
+                }
+                if (targetOrigin !== '*' && event.origin !== targetOrigin) {
+                    return;
+                }
+                if (!isObject(payload) || payload.id !== requestId) {
+                    return;
+                }
+                clearTimeout(timeoutHandle);
+                removeListener('message', onMessage);
+                if (isObject(payload.error)) {
+                    const rawMessage = payload.error.message;
+                    const message = typeof rawMessage === 'string'
+                        ? rawMessage
+                        : 'Unknown tools/call fallback error';
+                    reject(new Error(`Tool call fallback failed: ${message}`));
+                    return;
+                }
+                resolve(payload.result);
+            };
+            addListener('message', onMessage);
+            parent.postMessage({
+                jsonrpc: '2.0',
+                id: requestId,
+                method: 'tools/call',
+                params: {
+                    name,
+                    arguments: args,
+                },
+            }, targetOrigin);
+        });
+    }
+    async function callTool(name, args) {
+        const normalizedArgs = normalizeToolArgs(args);
+        const helperCandidates = [host.openai, host.mcp].filter((candidate) => Boolean(candidate?.callTool));
+        for (const helper of helperCandidates) {
+            try {
+                return await helper.callTool(name, normalizedArgs);
+            }
+            catch (error) {
+                if (isHelperUnavailableError(error)) {
+                    continue;
+                }
+                throw new Error(`Tool helper call failed: ${extractErrorMessage(error)}`);
+            }
+        }
+        try {
+            return await callViaFallback(name, normalizedArgs);
+        }
+        catch (fallbackError) {
+            throw fallbackError;
+        }
+    }
+    return {
+        callTool,
+    };
+}

package/dist/ui/shared/tool-shell.d.ts

@@ -12,5 +12,14 @@ interface CreateToolShellControllerOptions {
     onScrollAfterExpand?: () => void;
     onRender?: () => void;
 }
+interface CreateCompactRowShellControllerOptions {
+    shell: HTMLElement | null;
+    compactRow: HTMLElement | null;
+    initialExpanded: boolean;
+    onToggle?: (expanded: boolean) => void;
+    onScrollAfterExpand?: () => void;
+    onRender?: () => void;
+}
 export declare function createToolShellController(options: CreateToolShellControllerOptions): ToolShellController;
+export declare function createCompactRowShellController(options: CreateCompactRowShellControllerOptions): ToolShellController;
 export {};

package/dist/ui/shared/tool-shell.js

@@ -23,6 +23,7 @@ export function createToolShellController(options) {
     const { shell, toggleButton, initialExpanded, onToggle, onScrollAfterExpand, onRender } = options;
     let isExpanded = initialExpanded;
     let scrollTrackedForCurrentExpand = false;
+    const shouldTrackScroll = typeof onScrollAfterExpand === 'function';
     const applyExpandedState = (nextExpanded) => {
         const wasExpanded = isExpanded;
         isExpanded = nextExpanded;
@@ -50,16 +51,57 @@ export function createToolShellController(options) {
     };
     applyExpandedState(isExpanded);
     toggleButton?.addEventListener('click', toggle);
-    shell?.addEventListener('scroll', handleScroll, { passive: true });
-    document.addEventListener('scroll', handleScroll, { passive: true, capture: true });
+    if (shouldTrackScroll) {
+        shell?.addEventListener('scroll', handleScroll, { passive: true });
+        document.addEventListener('scroll', handleScroll, { passive: true, capture: true });
+    }
     return {
         getExpanded: () => isExpanded,
         setExpanded: applyExpandedState,
         toggle,
         dispose: () => {
             toggleButton?.removeEventListener('click', toggle);
-            shell?.removeEventListener('scroll', handleScroll);
-            document.removeEventListener('scroll', handleScroll, true);
+            if (shouldTrackScroll) {
+                shell?.removeEventListener('scroll', handleScroll);
+                document.removeEventListener('scroll', handleScroll, true);
+            }
+        },
+    };
+}
+export function createCompactRowShellController(options) {
+    const { shell, compactRow, initialExpanded, onToggle, onScrollAfterExpand, onRender } = options;
+    const controller = createToolShellController({
+        shell,
+        toggleButton: null,
+        initialExpanded,
+        onToggle: (expanded) => {
+            compactRow?.setAttribute('aria-expanded', String(expanded));
+            onToggle?.(expanded);
+        },
+        onScrollAfterExpand,
+        onRender,
+    });
+    compactRow?.setAttribute('aria-expanded', String(initialExpanded));
+    const handleCompactClick = () => {
+        controller.toggle();
+    };
+    const handleCompactKeydown = (event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') {
+            return;
+        }
+        event.preventDefault();
+        controller.toggle();
+    };
+    compactRow?.addEventListener('click', handleCompactClick);
+    compactRow?.addEventListener('keydown', handleCompactKeydown);
+    return {
+        getExpanded: controller.getExpanded,
+        setExpanded: controller.setExpanded,
+        toggle: controller.toggle,
+        dispose: () => {
+            compactRow?.removeEventListener('click', handleCompactClick);
+            compactRow?.removeEventListener('keydown', handleCompactKeydown);
+            controller.dispose();
         },
     };
 }

package/dist/ui/shared/ui-event-tracker.d.ts

@@ -0,0 +1,9 @@
+type UiEventParamValue = string | number | boolean | null;
+export type UiEventParams = Record<string, UiEventParamValue>;
+type ToolCaller = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+export interface UiEventTrackerOptions {
+    component: string;
+    baseParams?: UiEventParams;
+}
+export declare function createUiEventTracker(callTool: ToolCaller, options: UiEventTrackerOptions): (event: string, params?: Record<string, unknown>) => void;
+export {};

package/dist/ui/shared/ui-event-tracker.js

@@ -0,0 +1,27 @@
+function normalizeUiEventParams(params) {
+    const normalized = {};
+    if (!params) {
+        return normalized;
+    }
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+export function createUiEventTracker(callTool, options) {
+    const baseParams = options.baseParams ?? {};
+    return (event, params = {}) => {
+        void callTool('track_ui_event', {
+            event,
+            component: options.component,
+            params: {
+                ...baseParams,
+                ...normalizeUiEventParams(params),
+            },
+        }).catch(() => {
+            // UI analytics should never block UI interactions.
+        });
+    };
+}

package/dist/ui/shared/widget-state.d.ts

@@ -23,6 +23,11 @@ export declare function isChatGPT(): boolean;
  * Create a widget state storage adapter.
  *
  * On ChatGPT: Uses window.openai.widgetState for persistence
- * On other hosts: Returns no-op adapter (state comes from ui/notifications/tool-result)
+ * On other hosts: Uses sessionStorage as a fallback so the preview can survive
+ *   transient interruptions (page refresh on hosts that don't re-send tool_result,
+ *   visibility/focus loss, etc.).
+ *   The fallback cache key is scoped by app pathname and a per-frame widget id
+ *   persisted in window.name, so different widgets in the same origin/session
+ *   do not overwrite one another's cached state.
  */
 export declare function createWidgetStateStorage<T>(validator?: (state: unknown) => boolean): WidgetStateStorage<T>;