@wonderwhy-er/desktop-commander 0.2.36 → 0.2.38

package/dist/ui/file-preview/styles.css

@@ -3,28 +3,36 @@
  */
 :root {
   color-scheme: light dark;
+
+  /* Spec variables with light-dark() fallbacks (following customer-segmentation pattern).
+     When a host provides --color-* via applyHostStyleVariables, the var() picks it up;
+     otherwise the light-dark() fallback keeps the UI legible. */
   --bg: transparent;
-  --panel: var(--color-background-primary, Canvas);
-  --panel-subtle: var(--color-background-tertiary, ButtonFace);
-  --panel-muted: var(--color-background-muted, ButtonFace);
-  --text: var(--color-text-primary, CanvasText);
-  --text-secondary: var(--color-text-secondary, CanvasText);
-  --muted: var(--color-text-tertiary, GrayText);
-  --border: var(--color-border-default, GrayText);
-  --accent: var(--color-accent-primary, LinkText);
-  --accent-hover: var(--color-accent-primary-hover, var(--accent));
-  --accent-soft: var(--color-accent-subtle, var(--panel-subtle));
-  --focus-ring: var(--color-border-focused, var(--accent));
+  --panel: var(--color-background-primary, light-dark(#ffffff, #1e1e2e));
+  --panel-subtle: var(--color-background-tertiary, light-dark(#f5f5f5, #2a2a3c));
+  --panel-muted: var(--color-background-tertiary, light-dark(#f5f5f5, #2a2a3c));
+  --text: var(--color-text-primary, light-dark(#1a1a2e, #e4e4ef));
+  --text-secondary: var(--color-text-secondary, light-dark(#4a4a5a, #a0a0b8));
+  --muted: var(--color-text-tertiary, light-dark(#94a3b8, #64748b));
+  --border: var(--color-border-primary, light-dark(#e2e8f0, #334155));
+  --accent: var(--color-text-info, light-dark(#2563eb, #60a5fa));
+  --accent-hover: var(--color-text-info, var(--accent));
+  --accent-soft: var(--color-background-info, var(--panel-subtle));
+  --focus-ring: var(--color-border-primary, var(--accent));
   --shadow-sm: var(--shadow-sm, none);
   --success-bg: var(--color-background-success, var(--panel-subtle));
   --success-border: var(--color-border-success, var(--border));
-  --success-text: var(--color-text-success, var(--text));
+  --success-text: var(--color-text-success, light-dark(#059669, #34d399));
   --error-bg: var(--color-background-danger, var(--panel-subtle));
   --error-border: var(--color-border-danger, var(--border));
-  --error-text: var(--color-text-danger, var(--text));
+  --error-text: var(--color-text-danger, light-dark(#dc2626, #f87171));
   --warning-bg: var(--color-background-warning, var(--panel-subtle));
   --warning-border: var(--color-border-warning, var(--border));
-  --warning-text: var(--color-text-warning, var(--text));
+  --warning-text: var(--color-text-warning, light-dark(#d97706, #fbbf24));
+}
+
+html {
+  background: var(--bg);
 }
 
 * {
@@ -64,6 +72,73 @@ body.dc-ready {
 }
 
 
+.compact-row {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 2px;
+  font-size: 13px;
+  color: var(--muted);
+  line-height: 1;
+  user-select: none;
+}
+
+.compact-row--ready {
+  cursor: pointer;
+  border-radius: 8px;
+  transition: color 150ms ease;
+}
+
+.compact-row--ready:hover {
+  color: var(--text-secondary);
+}
+
+.compact-row--ready:hover .compact-chevron {
+  color: var(--text-secondary);
+}
+
+.compact-chevron {
+  width: 14px;
+  height: 14px;
+  fill: currentColor;
+  color: var(--muted);
+  flex-shrink: 0;
+  transition: transform 200ms ease, color 150ms ease;
+}
+
+.tool-shell.expanded .compact-chevron {
+  transform: rotate(90deg);
+}
+
+.compact-label {
+  color: inherit;
+}
+
+.compact-filename {
+  color: var(--text);
+  font-weight: 600;
+}
+
+.compact-row--ready .compact-label::after {
+  content: ' · ';
+}
+
+.compact-row--loading {
+  animation: fade-pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes fade-pulse {
+  0%,
+  100% {
+    opacity: 0.5;
+  }
+
+  50% {
+    opacity: 1;
+  }
+}
+
+
 /*
  * Reusable styles for the shared tool header component. It provides consistent spacing, alignment, and action presentation across apps.
  */
@@ -276,69 +351,23 @@ body.dc-ready {
 :root {
   --code-bg: var(--panel);
   --code-text: var(--color-text-primary, var(--text));
-  --hljs-keyword: var(--color-text-accent, #8b5cf6);
-  --hljs-string: var(--color-text-success, #059669);
-  --hljs-comment: var(--color-text-tertiary, #94a3b8);
-  --hljs-type: var(--color-text-info, #0f766e);
-  --hljs-number: var(--color-text-warning, #b45309);
-  --hljs-attr: var(--color-text-info, #2563eb);
-  --hljs-built-in: var(--color-text-accent, #6366f1);
-  --hljs-tag: var(--color-text-info, #0ea5a8);
+  --hljs-keyword: light-dark(#8b5cf6, #a78bfa);
+  --hljs-string: var(--color-text-success, light-dark(#059669, #34d399));
+  --hljs-comment: var(--color-text-tertiary, light-dark(#94a3b8, #64748b));
+  --hljs-type: var(--color-text-info, light-dark(#0f766e, #5eead4));
+  --hljs-number: var(--color-text-warning, light-dark(#b45309, #fbbf24));
+  --hljs-attr: var(--color-text-info, light-dark(#2563eb, #60a5fa));
+  --hljs-built-in: light-dark(#6366f1, #818cf8);
+  --hljs-tag: var(--color-text-info, light-dark(#0ea5a8, #67e8f9));
   --content-height: min(82vh, 920px);
   --markdown-text: var(--text);
   --markdown-muted: var(--text-secondary);
   --inline-code-bg: var(--panel-subtle);
   --inline-code-border: var(--border);
   --inline-code-text: var(--text);
-  --notice-bg: var(--warning-bg);
-  --notice-border: var(--warning-border);
-  --notice-text: var(--warning-text);
-}
-
-/* ── Compact row ── */
-
-.compact-row {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 6px 2px;
-  font-size: 13px;
-  color: var(--muted);
-  line-height: 1;
-  user-select: none;
-}
-
-.compact-row--ready {
-  cursor: pointer;
-  border-radius: 8px;
-  transition: color 150ms ease;
-}
-
-.compact-row--ready:hover { color: var(--text-secondary); }
-.compact-row--ready:hover .compact-chevron { color: var(--text-secondary); }
-
-.compact-chevron {
-  width: 14px;
-  height: 14px;
-  fill: currentColor;
-  color: var(--muted);
-  flex-shrink: 0;
-  transition: transform 200ms ease, color 150ms ease;
-}
-
-.tool-shell.expanded .compact-chevron { transform: rotate(90deg); }
-
-.compact-label { color: inherit; }
-.compact-filename { color: var(--text-secondary); font-weight: 500; }
-.compact-row--ready .compact-label::after { content: ' · '; }
-
-.compact-row--loading {
-  animation: fade-pulse 1.5s ease-in-out infinite;
-}
-
-@keyframes fade-pulse {
-  0%, 100% { opacity: 0.5; }
-  50% { opacity: 1; }
+  --notice-bg: var(--panel-subtle);
+  --notice-border: var(--border);
+  --notice-text: var(--text-secondary);
 }
 
 /* ── Panel (Claude-style card) ── */
@@ -351,18 +380,25 @@ body.dc-ready {
   overflow: hidden;
 }
 
-@media (prefers-color-scheme: dark) {
-  .panel {
-    background: color-mix(in srgb, var(--panel), white 6%);
-  }
-}
-
-[data-theme="dark"] .panel {
-  background: color-mix(in srgb, var(--panel), white 6%);
-}
+/* Panel background comes directly from host --color-background-primary.
+   No dark-mode adjustment — the host provides the correct color. */
 
 .tool-shell.collapsed .panel { display: none; }
 
+/* When the host hides the summary row (hideSummaryRow: true), it means the host
+   provides its own outer frame/card. Strip inner chrome so only content remains. */
+.tool-shell.host-framed .compact-row { display: none; }
+.tool-shell.host-framed .panel {
+  margin-top: 0;
+  border: none;
+  border-radius: 0;
+  background: transparent;
+}
+.tool-shell.host-framed .panel-topbar { display: none; }
+.tool-shell.host-framed .panel-footer { display: none; }
+.tool-shell.host-framed .panel-content-wrapper { max-height: none; overflow: hidden; }
+.tool-shell.host-framed .image-content { background: transparent; }
+
 /* ── Top bar ── */
 
 .panel-topbar {
@@ -495,9 +531,7 @@ body.dc-ready {
 
 .image-preview {
   width: 100%;
-  height: var(--content-height);
   max-width: 920px;
-  max-height: 100%;
   display: flex;
   align-items: center;
   justify-content: center;
@@ -505,7 +539,7 @@ body.dc-ready {
 
 .image-preview img {
   max-width: 100%;
-  max-height: 100%;
+  max-height: var(--content-height);
   object-fit: contain;
   border-radius: 8px;
   border: 1px solid var(--border);

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/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/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/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 {};