@lokvis/ui-react 0.1.1-beta.0 → 0.2.0

package/src/components/AssetPanel.tsx

@@ -1,11 +1,12 @@
 /**
  * AssetPanel - 左侧资产面板
  *
- * 紧凑布局：section header + 上传按钮 + 资产列表。
- * 支持拖拽导入、点击选择、缩略图预览。
+ * 紧凑布局：section header + 上传按钮 + 筛选 + 资产列表。
+ * 支持拖拽导入、点击选择、缩略图预览、按类型/关键词筛选、删除(W6.5)。
  */
 
 import * as React from 'react';
+import type { AssetType } from '@lokvis/schema';
 import { Icon } from '@lokvis/ui-core';
 import { useWorkspaceStore } from '../store/index.js';
 
@@ -13,6 +14,17 @@ export interface AssetPanelProps {
   className?: string;
 }
 
+/** 类型筛选 chip 显示名 */
+const TYPE_LABEL: Record<AssetType, string> = {
+  image: 'Image',
+  video: 'Video',
+  audio: 'Audio',
+  pdf: 'PDF',
+  text: 'Text',
+  data: 'Data',
+  unknown: 'Other',
+};
+
 export function AssetPanel({ className = '' }: AssetPanelProps) {
   const assets = useWorkspaceStore((s) => s.assets);
   const selectedAssetId = useWorkspaceStore((s) => s.selectedAssetId);
@@ -24,6 +36,11 @@ export function AssetPanel({ className = '' }: AssetPanelProps) {
   const runtime = useWorkspaceStore((s) => s.runtime);
 
   const [dragging, setDragging] = React.useState(false);
+  // W6.5 筛选:类型 + 关键词(纯 UI 状态,不入 store)
+  const [filterType, setFilterType] = React.useState<'all' | AssetType>('all');
+  const [searchQuery, setSearchQuery] = React.useState('');
+  // B2 修复:跟踪 in-flight exportAsset,避免同一 asset 跨 effect 重跑并发发起
+  const inflightRef = React.useRef<Set<string>>(new Set());
 
   async function handleFiles(files: FileList | File[] | null) {
     if (!files) return;
@@ -32,24 +49,69 @@ export function AssetPanel({ className = '' }: AssetPanelProps) {
   }
 
   // 自动生成缩略图
+  // B2 修复:
+  // - cancelled flag:effect 重跑/卸载时,await 完成的 exportAsset 不再创建
+  //   ObjectURL 也不 setThumbnail,避免覆盖更新值与孤儿 URL
+  // - inflightRef:同一 asset 在上一轮 effect 还在 await 时,新一轮 effect
+  //   不再重复发起(批量导入 assets 频繁变化场景)
   React.useEffect(() => {
     if (!runtime) return;
+    let cancelled = false;
+    const inflight = inflightRef.current;
     for (const asset of assets) {
       if (thumbnails[asset.id]) continue;
       if (asset.type !== 'image') continue;
+      if (inflight.has(asset.id)) continue;
+      inflight.add(asset.id);
       (async () => {
         try {
           const blob = await runtime.exportAsset(asset.id);
+          // effect 已过期或资产已删除:不创建 ObjectURL(零泄漏)
+          if (cancelled) return;
           const url = URL.createObjectURL(blob);
+          if (cancelled) {
+            // 双重检查:await 与 createObjectURL 之间可能被取消
+            URL.revokeObjectURL(url);
+            return;
+          }
           setThumbnail(asset.id, url);
         } catch {
-          // ignore
+          // ignore export 失败
+        } finally {
+          inflight.delete(asset.id);
         }
       })();
     }
+    return () => {
+      cancelled = true;
+    };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [assets, runtime]);
 
+  // 资产中实际存在的类型(仅展示有意义的 chip,避免空类型噪音)
+  const availableTypes = React.useMemo(() => {
+    const set = new Set<AssetType>();
+    for (const a of assets) set.add(a.type);
+    return Array.from(set);
+  }, [assets]);
+
+  // 筛选后的资产列表
+  const filteredAssets = React.useMemo(() => {
+    let result = assets;
+    if (filterType !== 'all') {
+      result = result.filter((a) => a.type === filterType);
+    }
+    const q = searchQuery.trim().toLowerCase();
+    if (q) {
+      result = result.filter(
+        (a) =>
+          a.metadata.format.toLowerCase().includes(q) ||
+          a.metadata.mimeType.toLowerCase().includes(q)
+      );
+    }
+    return result;
+  }, [assets, filterType, searchQuery]);
+
   return (
     <aside
       className={`flex w-56 shrink-0 flex-col border-r border-zinc-200 dark:border-zinc-800 ${className}`}
@@ -69,7 +131,11 @@ export function AssetPanel({ className = '' }: AssetPanelProps) {
         <span className="text-[11px] font-semibold uppercase tracking-wider text-zinc-400">
           Assets
         </span>
-        <span className="text-[11px] tabular-nums text-zinc-400">{assets.length}</span>
+        <span className="text-[11px] tabular-nums text-zinc-400">
+          {filterType === 'all' && !searchQuery
+            ? assets.length
+            : `${filteredAssets.length}/${assets.length}`}
+        </span>
       </div>
 
       {/* Upload zone */}
@@ -94,22 +160,97 @@ export function AssetPanel({ className = '' }: AssetPanelProps) {
         </span>
       </label>
 
+      {/* W6.5 筛选栏:仅当有资产时显示 */}
+      {assets.length > 0 && (
+        <div className="px-2 pb-2 space-y-1.5">
+          {/* 类型 chips:m10 radiogroup 语义,屏幕阅读器识别为单选组 */}
+          <div
+            role="radiogroup"
+            aria-label="Filter by type"
+            className="flex flex-wrap gap-1"
+          >
+            <button
+              type="button"
+              role="radio"
+              aria-checked={filterType === 'all'}
+              onClick={() => setFilterType('all')}
+              className={`rounded px-1.5 py-0.5 text-[10px] font-medium transition-colors ${
+                filterType === 'all'
+                  ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-950/50 dark:text-indigo-300'
+                  : 'bg-zinc-100 text-zinc-500 hover:bg-zinc-200 dark:bg-zinc-800 dark:text-zinc-400 dark:hover:bg-zinc-700'
+              }`}
+            >
+              All
+            </button>
+            {availableTypes.map((t) => (
+              <button
+                key={t}
+                type="button"
+                role="radio"
+                aria-checked={filterType === t}
+                onClick={() => setFilterType(t)}
+                className={`rounded px-1.5 py-0.5 text-[10px] font-medium transition-colors ${
+                  filterType === t
+                    ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-950/50 dark:text-indigo-300'
+                    : 'bg-zinc-100 text-zinc-500 hover:bg-zinc-200 dark:bg-zinc-800 dark:text-zinc-400 dark:hover:bg-zinc-700'
+                }`}
+              >
+                {TYPE_LABEL[t]}
+              </button>
+            ))}
+          </div>
+          {/* 搜索框:m4 文案改为与实际过滤行为一致(按 format/mimeType) */}
+          <div className="relative">
+            <Icon
+              size={11}
+              className="absolute left-1.5 top-1/2 -translate-y-1/2 text-zinc-400 pointer-events-none"
+            >
+              <circle cx="10" cy="10" r="6" />
+              <path d="m20 20-5-5" />
+            </Icon>
+            <input
+              type="text"
+              value={searchQuery}
+              onChange={(e) => setSearchQuery(e.target.value)}
+              placeholder="Filter by type..."
+              aria-label="Filter assets by format"
+              className="w-full rounded bg-zinc-100 py-1 pl-6 pr-1.5 text-[10px] text-zinc-700 placeholder:text-zinc-400 focus:outline-none focus:ring-1 focus:ring-indigo-300 dark:bg-zinc-800 dark:text-zinc-200 dark:placeholder:text-zinc-500"
+            />
+          </div>
+        </div>
+      )}
+
       {/* Asset list */}
       <div className="flex-1 overflow-y-auto px-2 pb-2">
         {assets.length === 0 ? (
           <p className="px-1 py-4 text-center text-[10px] text-zinc-400">
             No assets imported
           </p>
+        ) : filteredAssets.length === 0 ? (
+          <p className="px-1 py-4 text-center text-[10px] text-zinc-400">
+            No assets match filter
+          </p>
         ) : (
           <ul className="space-y-1">
-            {assets.map((asset) => {
+            {filteredAssets.map((asset) => {
               const selected = asset.id === selectedAssetId;
               const thumb = thumbnails[asset.id];
               return (
                 <li
                   key={asset.id}
+                  // M3: 键盘可达 —— tabIndex + role + onKeyDown(Enter/Space 选中)
+                  tabIndex={0}
+                  role="button"
+                  aria-pressed={selected}
+                  aria-label={`Select asset ${asset.metadata.format}`}
                   onClick={() => selectAsset(asset.id)}
-                  className={`group flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-xs transition-all ${
+                  onKeyDown={(e) => {
+                    if (e.key === 'Enter' || e.key === ' ') {
+                      e.preventDefault();
+                      selectAsset(asset.id);
+                    }
+                  }}
+                  className={`group flex cursor-pointer items-center gap-2 rounded-md px-2 py-1.5 text-xs transition-all focus:outline-none focus:ring-2 focus:ring-indigo-300 ${
                     selected
                       ? 'bg-indigo-50 ring-1 ring-indigo-200 dark:bg-indigo-950/30 dark:ring-indigo-800'
                       : 'hover:bg-zinc-50 dark:hover:bg-zinc-800'
@@ -136,8 +277,8 @@ export function AssetPanel({ className = '' }: AssetPanelProps) {
                       e.stopPropagation();
                       void removeAsset(asset.id);
                     }}
-                    className="shrink-0 rounded p-0.5 text-zinc-300 opacity-0 transition-all hover:bg-red-50 hover:text-red-500 group-hover:opacity-100 dark:text-zinc-600 dark:hover:bg-red-950/30"
-                    aria-label="Remove asset"
+                    className="shrink-0 rounded p-0.5 text-zinc-300 opacity-0 transition-all hover:bg-red-50 hover:text-red-500 focus:opacity-100 group-hover:opacity-100 dark:text-zinc-600 dark:hover:bg-red-950/30"
+                    aria-label={`Remove asset ${asset.metadata.format}`}
                   >
                     <Icon size={12}><path d="M6 18L18 6M6 6l12 12" /></Icon>
                   </button>

package/src/components/Canvas.tsx

@@ -3,25 +3,64 @@
  *
  * 只负责展示当前选中资产的预览，以及空状态引导。
  * 工作流节点链已移至独立的 PipelineBar 组件。
+ *
+ * W9.4: 当存在 lastOutputIds 时,可切换到 CompareSlider 模式,
+ *       并排展示 before/after。
  */
 
 import * as React from 'react';
 import { Icon } from '@lokvis/ui-core';
 import { useWorkspaceStore } from '../store/index.js';
+import { CompareSlider } from './CompareSlider.js';
 
 export interface CanvasProps {
   className?: string;
+  /**
+   * 是否启用 before/after 对比模式(W9.4)。
+   * 默认 true;关闭后即使有 outputs 也只显示单图预览。
+   */
+  enableCompare?: boolean;
 }
 
-export function Canvas({ className = '' }: CanvasProps) {
+export function Canvas({ className = '', enableCompare = true }: CanvasProps) {
   const selectedAssetId = useWorkspaceStore((s) => s.selectedAssetId);
   const assets = useWorkspaceStore((s) => s.assets);
   const thumbnails = useWorkspaceStore((s) => s.thumbnails);
   const importFiles = useWorkspaceStore((s) => s.importFiles);
+  const lastOutputIds = useWorkspaceStore((s) => s.lastOutputIds);
+  const selectedOutputId = useWorkspaceStore((s) => s.selectedOutputId);
 
   const selected = assets.find((a) => a.id === selectedAssetId);
   const preview = selected ? thumbnails[selected.id] : undefined;
 
+  // W9.4 是否有可对比的输出
+  const outputId = selectedOutputId ?? lastOutputIds[0] ?? null;
+  const outputThumbnail = outputId ? thumbnails[outputId] : undefined;
+  const canCompare = enableCompare && !!(preview && outputThumbnail);
+
+  // W9.4 默认开启 compare 模式:当 outputs 生成后,用户首次希望对比
+  // 切换状态由用户控制,直到下次 outputs 重新生成时再默认开启
+  const [compareMode, setCompareMode] = React.useState(false);
+  // 记录上次已自动切到 compare 模式的 outputId。
+  // 修复 review:原 effect 依赖 [lastOutputIds, preview, outputThumbnail],
+  // 当用户手动切到 Single 后再切换选中资产,preview 变化会触发 effect
+  // 把 compareMode 强制重置为 true,覆盖用户选择。
+  // 现在仅在 outputId 真正变化(新 run 完成 / 切换输出)且 preview/outputThumbnail
+  // 都就绪时才自动切换;同一 outputId 下 preview / outputThumbnail 的异步变化
+  // 不会覆盖用户已选择的 Single 模式。
+  const lastAutoSwitchedOutputId = React.useRef<string | null>(null);
+  React.useEffect(() => {
+    if (
+      outputId !== null &&
+      outputId !== lastAutoSwitchedOutputId.current &&
+      preview &&
+      outputThumbnail
+    ) {
+      lastAutoSwitchedOutputId.current = outputId;
+      setCompareMode(true);
+    }
+  }, [outputId, preview, outputThumbnail]);
+
   // 全局拖拽支持（直接拖到画布区）
   const [dragOver, setDragOver] = React.useState(false);
 
@@ -32,6 +71,9 @@ export function Canvas({ className = '' }: CanvasProps) {
       onDragLeave={() => setDragOver(false)}
       onDrop={(e) => {
         e.preventDefault();
+        // stopPropagation 防止事件冒泡到 window 的 GlobalDropzone 监听,
+        // 否则文件会被导入两次(Canvas 处理一次 + GlobalDropzone 再处理一次)
+        e.stopPropagation();
         setDragOver(false);
         if (e.dataTransfer.files.length > 0) {
           void importFiles(Array.from(e.dataTransfer.files));
@@ -49,6 +91,36 @@ export function Canvas({ className = '' }: CanvasProps) {
           }}
         />
 
+        {/* W9.4 Compare 模式切换按钮(右上) */}
+        {canCompare && (
+          <div className="absolute top-2 right-2 z-20 flex items-center gap-1 rounded-md bg-white/90 p-0.5 shadow-sm backdrop-blur-sm dark:bg-zinc-900/90">
+            <button
+              type="button"
+              onClick={() => setCompareMode(false)}
+              aria-pressed={!compareMode}
+              className={`rounded px-2 py-1 text-[10px] font-medium transition-colors ${
+                !compareMode
+                  ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-950/50 dark:text-indigo-300'
+                  : 'text-zinc-500 hover:bg-zinc-100 dark:hover:bg-zinc-800'
+              }`}
+            >
+              Single
+            </button>
+            <button
+              type="button"
+              onClick={() => setCompareMode(true)}
+              aria-pressed={compareMode}
+              className={`rounded px-2 py-1 text-[10px] font-medium transition-colors ${
+                compareMode
+                  ? 'bg-indigo-100 text-indigo-700 dark:bg-indigo-950/50 dark:text-indigo-300'
+                  : 'text-zinc-500 hover:bg-zinc-100 dark:hover:bg-zinc-800'
+              }`}
+            >
+              Compare
+            </button>
+          </div>
+        )}
+
         {dragOver && (
           <div className="absolute inset-4 z-10 rounded-xl border-2 border-dashed border-indigo-400 bg-indigo-50/80 flex items-center justify-center dark:border-indigo-600 dark:bg-indigo-950/60">
             <div className="text-center">
@@ -58,7 +130,12 @@ export function Canvas({ className = '' }: CanvasProps) {
           </div>
         )}
 
-        {selected ? (
+        {/* W9.4 Compare 模式:展示 before/after 滑块 */}
+        {compareMode && canCompare ? (
+          <div className="relative flex max-h-[calc(100%-4rem)] max-w-[calc(100%-4rem)] items-center justify-center">
+            <CompareSlider className="max-h-[calc(100vh-12rem)] max-w-full" />
+          </div>
+        ) : selected ? (
           preview ? (
             <div className="relative">
               <img

package/src/components/CommandPalette.tsx

@@ -0,0 +1,300 @@
+/**
+ * CommandPalette - ⌘K 工具选择器(W9.2)
+ *
+ * Command Palette 风格的快捷工具入口:
+ *   - ⌘K / Ctrl+K 打开
+ *   - ESC 关闭
+ *   - 输入关键词过滤能力列表
+ *   - ↑↓ 选择,Enter 添加到工作流,or 鼠标点击
+ *
+ * 数据源:`store.capabilities`,与 Inspector 右侧能力列表同源。
+ * 选中后调用 `store.addNode(cap.name)` 添加到工作流,并关闭面板。
+ *
+ * 实现:基于 ui-core 的 Dialog 组件提供模态基底 + 焦点 trap。
+ */
+
+import * as React from 'react';
+import { Dialog, Icon } from '@lokvis/ui-core';
+import type { Capability } from '@lokvis/schema';
+import { useWorkspaceStore } from '../store/index.js';
+
+export interface CommandPaletteProps {
+  /** 是否打开(受控) */
+  open: boolean;
+  /** 关闭回调 */
+  onClose: () => void;
+  className?: string;
+}
+
+export function CommandPalette({ open, onClose, className = '' }: CommandPaletteProps) {
+  const capabilities = useWorkspaceStore((s) => s.capabilities);
+  const addNode = useWorkspaceStore((s) => s.addNode);
+  const undo = useWorkspaceStore((s) => s.undo);
+  const redo = useWorkspaceStore((s) => s.redo);
+  const clearWorkflow = useWorkspaceStore((s) => s.clearWorkflow);
+  const running = useWorkspaceStore((s) => s.running);
+
+  const [query, setQuery] = React.useState('');
+  const [activeIndex, setActiveIndex] = React.useState(0);
+  const inputRef = React.useRef<HTMLInputElement>(null);
+  const listRef = React.useRef<HTMLUListElement>(null);
+
+  // 命令项:capability 添加 + 工作流操作
+  type Command =
+    | { kind: 'capability'; cap: Capability }
+    | { kind: 'action'; id: string; label: string; description: string; run: () => void; disabled?: boolean };
+
+  const commands: Command[] = React.useMemo(() => {
+    const caps = capabilities.map((cap) => ({ kind: 'capability' as const, cap }));
+    const actions: Command[] = [
+      {
+        kind: 'action',
+        id: 'undo',
+        label: 'Undo',
+        description: '回退到上一步历史',
+        run: () => void undo(),
+        disabled: false,
+      },
+      {
+        kind: 'action',
+        id: 'redo',
+        label: 'Redo',
+        description: '重做一步',
+        run: () => void redo(),
+        disabled: false,
+      },
+      {
+        kind: 'action',
+        id: 'clear',
+        label: 'Clear Workflow',
+        description: '清空当前工作流节点',
+        run: () => clearWorkflow(),
+        disabled: running,
+      },
+    ];
+    return [...caps, ...actions];
+  }, [capabilities, undo, redo, clearWorkflow, running]);
+
+  const filtered = React.useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return commands;
+    return commands.filter((cmd) => {
+      if (cmd.kind === 'capability') {
+        return (
+          cmd.cap.name.toLowerCase().includes(q) ||
+          cmd.cap.description.toLowerCase().includes(q)
+        );
+      }
+      return cmd.label.toLowerCase().includes(q) || cmd.description.toLowerCase().includes(q);
+    });
+  }, [commands, query]);
+
+  // 打开时重置 query + activeIndex + 聚焦输入
+  React.useEffect(() => {
+    if (!open) return;
+    setQuery('');
+    setActiveIndex(0);
+    // Dialog 聚焦首个可聚焦元素(input)后,input ref 才有值
+    // 用 timer 句柄 + cleanup 避免卸载后 setState 警告
+    const t = setTimeout(() => inputRef.current?.focus(), 0);
+    return () => clearTimeout(t);
+  }, [open]);
+
+  // filtered 变化时校正 activeIndex 越界
+  React.useEffect(() => {
+    if (activeIndex >= filtered.length) {
+      setActiveIndex(filtered.length === 0 ? 0 : filtered.length - 1);
+    }
+  }, [filtered.length, activeIndex]);
+
+  // 滚动 active 项进入视区
+  React.useEffect(() => {
+    if (!open || !listRef.current) return;
+    const active = listRef.current.querySelector<HTMLElement>(`[data-index="${activeIndex}"]`);
+    active?.scrollIntoView({ block: 'nearest' });
+  }, [activeIndex, open]);
+
+  function handleSelect(cmd: Command) {
+    if (cmd.kind === 'capability') {
+      addNode(cmd.cap.name);
+    } else {
+      if (cmd.disabled) return;
+      cmd.run();
+    }
+    onClose();
+  }
+
+  function handleKeyDown(e: React.KeyboardEvent) {
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setActiveIndex((i) => (i + 1) % Math.max(1, filtered.length));
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setActiveIndex((i) => (i - 1 + filtered.length) % Math.max(1, filtered.length));
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      const cmd = filtered[activeIndex];
+      if (cmd) handleSelect(cmd);
+    }
+  }
+
+  return (
+    <Dialog open={open} onClose={onClose} size="md" closeOnOverlay>
+      <div className={`-mx-5 -my-5 ${className}`}>
+        {/* 搜索输入 */}
+        <div className="flex items-center gap-2 border-b border-zinc-200 px-4 py-3 dark:border-zinc-800">
+          <Icon size={16} className="text-zinc-400">
+            <circle cx="11" cy="11" r="8" />
+            <path d="m21 21-4.3-4.3" />
+          </Icon>
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder="Search commands or capabilities..."
+            aria-label="Search commands"
+            className="flex-1 bg-transparent text-sm text-zinc-900 placeholder:text-zinc-400 focus:outline-none dark:text-zinc-100"
+            autoComplete="off"
+            spellCheck={false}
+          />
+          <kbd className="rounded border border-zinc-200 px-1.5 py-0.5 text-[9px] font-medium text-zinc-400 dark:border-zinc-700 dark:text-zinc-500">
+            ESC
+          </kbd>
+        </div>
+
+        {/* 命令列表 */}
+        <ul
+          ref={listRef}
+          className="max-h-80 overflow-y-auto py-1"
+          role="listbox"
+          aria-label="Available commands"
+        >
+          {filtered.length === 0 ? (
+            <li className="px-4 py-6 text-center text-xs text-zinc-400">
+              No matching commands
+            </li>
+          ) : (
+            filtered.map((cmd, i) => {
+              const isActive = i === activeIndex;
+              const isCap = cmd.kind === 'capability';
+              const primary = isCap ? cmd.cap.name : cmd.label;
+              const secondary = isCap ? cmd.cap.description : cmd.description;
+              const disabled = !isCap && cmd.disabled;
+              return (
+                <li
+                  key={isCap ? `cap:${cmd.cap.name}` : `act:${cmd.id}`}
+                  data-index={i}
+                  role="option"
+                  aria-selected={isActive}
+                  aria-disabled={disabled}
+                >
+                  <button
+                    type="button"
+                    onMouseEnter={() => setActiveIndex(i)}
+                    onClick={() => !disabled && handleSelect(cmd)}
+                    disabled={disabled}
+                    className={`flex w-full items-center gap-3 px-4 py-2 text-left transition-colors ${
+                      isActive && !disabled
+                        ? 'bg-indigo-50 dark:bg-indigo-950/30'
+                        : ''
+                    } ${disabled ? 'cursor-not-allowed opacity-40' : 'hover:bg-zinc-50 dark:hover:bg-zinc-800/50'}`}
+                  >
+                    <span
+                      className={`flex h-6 w-6 shrink-0 items-center justify-center rounded ${
+                        isCap
+                          ? 'bg-zinc-100 text-zinc-500 dark:bg-zinc-800 dark:text-zinc-400'
+                          : 'bg-indigo-100 text-indigo-600 dark:bg-indigo-950/50 dark:text-indigo-400'
+                      }`}
+                    >
+                      <Icon size={12} strokeWidth={2}>
+                        {isCap ? (
+                          <path d="M12 4.5v15m7.5-7.5h-15" />
+                        ) : (
+                          <path d="M13 2L3 14h7l-1 8 10-12h-7l1-8z" />
+                        )}
+                      </Icon>
+                    </span>
+                    <div className="min-w-0 flex-1">
+                      <div className="flex items-center justify-between gap-2">
+                        <span className="truncate text-xs font-medium text-zinc-900 dark:text-zinc-100">
+                          {primary}
+                        </span>
+                        {isCap && (
+                          <span className="shrink-0 rounded px-1 py-0.5 text-[9px] font-medium uppercase bg-zinc-100 text-zinc-500 dark:bg-zinc-800 dark:text-zinc-400">
+                            {cmd.cap.performance}
+                          </span>
+                        )}
+                      </div>
+                      <p className="truncate text-[10px] text-zinc-500 dark:text-zinc-400">
+                        {secondary}
+                      </p>
+                    </div>
+                  </button>
+                </li>
+              );
+            })
+          )}
+        </ul>
+
+        {/* 底部提示 */}
+        <div className="flex items-center justify-between border-t border-zinc-200 px-4 py-2 text-[10px] text-zinc-400 dark:border-zinc-800">
+          <span className="flex items-center gap-1">
+            <kbd className="rounded border border-zinc-200 px-1 dark:border-zinc-700">↑↓</kbd>
+            <span>navigate</span>
+            <kbd className="ml-2 rounded border border-zinc-200 px-1 dark:border-zinc-700">↵</kbd>
+            <span>select</span>
+          </span>
+          <span>{filtered.length} command{filtered.length !== 1 ? 's' : ''}</span>
+        </div>
+      </div>
+    </Dialog>
+  );
+}
+
+/**
+ * useCommandPalette - 在组件中注册 ⌘K / Ctrl+K 全局快捷键打开面板。
+ *
+ * 返回 [open, setOpen]。在 useEffect 中绑定 keydown 监听。
+ * 兼容 macOS(⌘K)与 Windows/Linux(Ctrl+K)。Shift+⌘K / Ctrl+Shift+K 也触发,
+ * 方便用户在 ⌘K 被浏览器拦截时使用。
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = useCommandPalette();
+ * // 或禁用快捷键(仍可受控使用 open/setOpen):
+ * const [open, setOpen] = useCommandPalette({ enabled: false });
+ * return (
+ *   <>
+ *     <CommandPalette open={open} onClose={() => setOpen(false)} />
+ *   </>
+ * );
+ * ```
+ */
+export interface UseCommandPaletteOptions {
+  /** 是否注册 ⌘K 全局快捷键(默认 true)。设为 false 时仍可受控使用 open/setOpen */
+  enabled?: boolean;
+}
+
+export function useCommandPalette(
+  options: UseCommandPaletteOptions = {}
+): [boolean, React.Dispatch<React.SetStateAction<boolean>>] {
+  const { enabled = true } = options;
+  const [open, setOpen] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!enabled) return;
+    const onKey = (e: KeyboardEvent) => {
+      // ⌘K (mac) / Ctrl+K (win/linux),忽略纯 K(避免拦截输入)
+      if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+        e.preventDefault();
+        setOpen((v) => !v);
+      }
+    };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [enabled]);
+
+  return [open, setOpen];
+}