@lokvis/ui-react 0.1.0 → 0.2.0

package/src/components/Workspace.tsx

@@ -1,7 +1,32 @@
 /**
  * Workspace - 完整工作台组件
  *
- * 标准三栏布局：Toolbar → [AssetPanel | Canvas | Inspector] → PipelineBar → StatusBar
+ * W9 布局:
+ *   ┌──────────────────────────────────────────────┐
+ *   │ Toolbar                                       │
+ *   ├──────┬──────────────┬───────────────────────┤
+ *   │Asset │   Canvas     │   Inspector           │
+ *   │Panel │   (center)   │   (right)             │
+ *   ├──────┴──────────────┴───────────────────────┤
+ *   │ PipelineBar                                  │
+ *   ├──────────────────────────────────────────────┤
+ *   │ HistoryPanel (horizontal, W9.1)              │
+ *   ├──────────────────────────────────────────────┤
+ *   │ DownloadPanel (W9.5,条件渲染)                │
+ *   ├──────────────────────────────────────────────┤
+ *   │ StatusBar                                    │
+ *   └──────────────────────────────────────────────┘
+ *
+ * W9 集成:
+ *   - 9.1 HistoryPanel 移到底部(horizontal variant)
+ *   - 9.2 CommandPalette(⌘K)挂载在 Workspace 内
+ *   - 9.3 GlobalDropzone 全屏拖拽 + MIME 校验
+ *   - 9.4 Canvas 内置 CompareSlider(before/after)
+ *   - 9.5 DownloadPanel 在 HistoryPanel 下方,有 outputs 时显示
+ *   - 9.6 StatusBar 已增强(当前工具/进度/在线)
+ *   - 9.7 ThemeToggle 通过 Toolbar rightExtra 挂载
+ *   - 9.8 响应式:移动端折叠为 drawer 模式
+ *
  * 通过 useLokvis 自动初始化 Runtime 与插件。
  *
  * @example
@@ -13,29 +38,107 @@
  * ```
  */
 
+import * as React from 'react';
+import { Icon } from '@lokvis/ui-core';
 import { useLokvis, type UseLokvisOptions } from '../hooks/useLokvis.js';
+import { useBreakpoints } from '../hooks/useMediaQuery.js';
 import { Toolbar } from './Toolbar.js';
 import { AssetPanel } from './AssetPanel.js';
+import { HistoryPanel } from './HistoryPanel.js';
 import { Canvas } from './Canvas.js';
 import { Inspector } from './Inspector.js';
 import { PipelineBar } from './PipelineBar.js';
+import { WorkflowEditor } from './WorkflowEditor.js';
+import { ProgressBar } from './ProgressBar.js';
+import { ErrorBanner } from './ErrorBanner.js';
 import { StatusBar } from './StatusBar.js';
+import { DownloadPanel } from './DownloadPanel.js';
+import { CommandPalette, useCommandPalette } from './CommandPalette.js';
+import { GlobalDropzone } from './GlobalDropzone.js';
+import { ThemeToggle } from './ThemeToggle.js';
+import { useShareLink } from '../hooks/useShareLink.js';
+import { useWorkspaceStore } from '../store/index.js';
 
 export interface WorkspaceProps extends UseLokvisOptions {
   /** 顶部标题 */
   title?: string;
   /** 是否显示状态栏（默认 true） */
   showStatusBar?: boolean;
+  /** 是否显示历史面板（默认 true,W7.1） */
+  showHistoryPanel?: boolean;
+  /** 是否启用全屏拖拽导入（默认 true,W9.3） */
+  enableGlobalDropzone?: boolean;
+  /** 是否启用 Command Palette ⌘K（默认 true,W9.2） */
+  enableCommandPalette?: boolean;
+  /** 是否启用 ThemeToggle（默认 true,W9.7） */
+  enableThemeToggle?: boolean;
+  /** 是否启用 CompareSlider（默认 true,W9.4） */
+  enableCompare?: boolean;
+  /** 是否启用 DownloadPanel（默认 true,W9.5） */
+  enableDownloadPanel?: boolean;
+  /** 是否启用拖拽式 WorkflowEditor（默认 false,W10.4;关闭则用只读 PipelineBar） */
+  enableWorkflowEditor?: boolean;
+  /** 是否启用 ProgressBar + Cancel 按钮（默认 true,W11.6） */
+  enableProgressBar?: boolean;
+  /** 是否启用 ErrorBanner 错误信息横幅（默认 true,W11.3） */
+  enableErrorBanner?: boolean;
+  /** 是否从 URL ?workflow= 参数加载分享工作流（默认 true,W11.5） */
+  enableShareLink?: boolean;
   className?: string;
 }
 
+/** W9.8 移动端抽屉切换状态 */
+type MobilePanel = 'asset' | 'inspector' | null;
+
 export function Workspace({
   title,
   showStatusBar = true,
+  showHistoryPanel = true,
+  enableGlobalDropzone = true,
+  enableCommandPalette = true,
+  enableThemeToggle = true,
+  enableCompare = true,
+  enableDownloadPanel = true,
+  enableWorkflowEditor = false,
+  enableProgressBar = true,
+  enableErrorBanner = true,
+  enableShareLink = true,
   className = '',
   ...lokvisOptions
 }: WorkspaceProps) {
   const { status, error } = useLokvis(lokvisOptions);
+  const { isMobile } = useBreakpoints();
+  const [paletteOpen, setPaletteOpen] = useCommandPalette({ enabled: enableCommandPalette });
+  // W9.8 移动端抽屉:Asset / Inspector 切换显示
+  const [mobilePanel, setMobilePanel] = React.useState<MobilePanel>(null);
+
+  // W11.5: 从 URL ?workflow= 参数加载分享工作流(runtime 就绪后执行一次)
+  // 保护:若用户已通过其它路径(如 localStorage 恢复或手动添加)有 nodes,
+  // 不静默替换 —— 用 confirm 让用户显式选择,避免丢失未保存工作。
+  // 注:不用 useWorkspaceStore 订阅 nodes.length 做 effect 依赖
+  //   (review 反馈:那样 nodesLength 变化会触发 effect 重跑,而 ref 已 true
+  //   时重跑无意义,且语义上 effect 只应在 status 切换时跑一次)。
+  //   改用 getState() 在体内读取最新值,既不订阅也不进 deps。
+  const { loadFromCurrentUrl } = useShareLink();
+  const shareLoadedRef = React.useRef(false);
+  React.useEffect(() => {
+    if (enableShareLink && !shareLoadedRef.current && status !== 'initializing' && status !== 'error') {
+      shareLoadedRef.current = true;
+      // 仅在 URL 含 ?workflow= 参数时才提示(避免无谓 confirm 弹窗)
+      const hasShareParam = typeof window !== 'undefined'
+        && new URLSearchParams(window.location.search).has('workflow');
+      if (!hasShareParam) return;
+      // 读取当前 nodes 长度(最新值,非订阅快照)
+      const currentNodesLength = useWorkspaceStore.getState().nodes.length;
+      if (currentNodesLength > 0) {
+        const ok = window.confirm(
+          `检测到分享工作流链接,但当前已有 ${currentNodesLength} 个节点。是否替换为分享的工作流?`
+        );
+        if (!ok) return;
+      }
+      loadFromCurrentUrl();
+    }
+  }, [enableShareLink, status, loadFromCurrentUrl]);
 
   if (status === 'initializing') {
     return (
@@ -59,7 +162,7 @@ export function Workspace({
       <div className="flex h-full items-center justify-center px-6">
         <div className="max-w-md rounded-xl border border-red-200 bg-red-50 p-6 text-center dark:border-red-800/50 dark:bg-red-950/20">
           <div className="mb-3 flex h-10 w-10 mx-auto items-center justify-center rounded-full bg-red-100 dark:bg-red-900/40">
-            <svg className="h-5 w-5 text-red-500" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12.01" y2="16"/></svg>
+            <Icon size={20} className="text-red-500"><circle cx="12" cy="12" r="10" /><line x1="12" y1="8" x2="12" y2="12" /><line x1="12" y1="16" x2="12.01" y2="16" /></Icon>
           </div>
           <p className="font-semibold text-red-700 dark:text-red-400">Failed to initialize</p>
           <p className="mt-1.5 text-sm text-red-600/80 dark:text-red-400/70">{error}</p>
@@ -68,20 +171,115 @@ export function Workspace({
     );
   }
 
+  // W9.7 Toolbar rightExtra: ThemeToggle + ⌘K hint
+  const toolbarRight = (
+    <>
+      {enableCommandPalette && (
+        <button
+          type="button"
+          onClick={() => setPaletteOpen(true)}
+          aria-label="Open command palette"
+          title="Command palette (⌘K)"
+          className="flex h-7 items-center gap-1 rounded-md border border-zinc-200 px-1.5 text-[10px] text-zinc-500 transition-colors hover:bg-zinc-100 hover:text-zinc-700 dark:border-zinc-700 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
+        >
+          <Icon size={11}><circle cx="11" cy="11" r="8" /><path d="m21 21-4.3-4.3" /></Icon>
+          <kbd className="font-sans">⌘K</kbd>
+        </button>
+      )}
+      {enableThemeToggle && <ThemeToggle />}
+      {/* W9.8 移动端面板切换按钮 */}
+      {isMobile && (
+        <>
+          <button
+            type="button"
+            onClick={() => setMobilePanel(mobilePanel === 'asset' ? null : 'asset')}
+            aria-label="Toggle asset panel"
+            aria-pressed={mobilePanel === 'asset'}
+            className="flex h-7 w-7 items-center justify-center rounded-md text-zinc-500 hover:bg-zinc-100 hover:text-zinc-700 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
+          >
+            <Icon size={14}><rect x="3" y="3" width="7" height="18" rx="1" /><path d="M14 3h7v18h-7z" opacity="0.3" /></Icon>
+          </button>
+          <button
+            type="button"
+            onClick={() => setMobilePanel(mobilePanel === 'inspector' ? null : 'inspector')}
+            aria-label="Toggle inspector panel"
+            aria-pressed={mobilePanel === 'inspector'}
+            className="flex h-7 w-7 items-center justify-center rounded-md text-zinc-500 hover:bg-zinc-100 hover:text-zinc-700 dark:hover:bg-zinc-800 dark:hover:text-zinc-200"
+          >
+            <Icon size={14}><path d="M3 3h7v18H3z" opacity="0.3" /><rect x="14" y="3" width="7" height="18" rx="1" /></Icon>
+          </button>
+        </>
+      )}
+    </>
+  );
+
   return (
     <div className={`flex h-full flex-col bg-white dark:bg-zinc-900 ${className}`}>
       {/* Top: Toolbar */}
-      <Toolbar title={title} />
+      <Toolbar title={title} rightExtra={toolbarRight} />
+
+      {/* W11.3 ErrorBanner (有 error 时显示) */}
+      {enableErrorBanner && <ErrorBanner />}
+
+      {/* W9.3 全屏拖拽 */}
+      {enableGlobalDropzone && <GlobalDropzone />}
+
+      {/* W9.2 Command Palette */}
+      {enableCommandPalette && (
+        <CommandPalette open={paletteOpen} onClose={() => setPaletteOpen(false)} />
+      )}
 
-      {/* Middle: Three-panel area */}
-      <div className="flex flex-1 overflow-hidden">
-        <AssetPanel />
-        <Canvas />
-        <Inspector />
+      {/* Middle: Panel area */}
+      <div className="flex flex-1 overflow-hidden relative">
+        {/* W9.8 桌面:三栏并列;移动:Canvas 单独,其他为 overlay drawer */}
+        <div
+          className={`${
+            isMobile
+              ? `absolute inset-y-0 left-0 z-20 w-64 max-w-[80vw] transition-transform duration-200 ${
+                  mobilePanel === 'asset' ? 'translate-x-0' : '-translate-x-full'
+                }`
+              : 'relative'
+          }`}
+        >
+          <AssetPanel className="h-full" />
+        </div>
+
+        <Canvas enableCompare={enableCompare} />
+
+        <div
+          className={`${
+            isMobile
+              ? `absolute inset-y-0 right-0 z-20 w-72 max-w-[80vw] transition-transform duration-200 ${
+                  mobilePanel === 'inspector' ? 'translate-x-0' : 'translate-x-full'
+                }`
+              : 'relative'
+          }`}
+        >
+          <Inspector className="h-full" />
+        </div>
+
+        {/* W9.8 移动端遮罩:点击关闭抽屉 */}
+        {isMobile && mobilePanel !== null && (
+          <button
+            type="button"
+            aria-label="Close panel"
+            onClick={() => setMobilePanel(null)}
+            className="absolute inset-0 z-10 bg-black/30"
+          />
+        )}
       </div>
 
       {/* Pipeline bar */}
-      <PipelineBar />
+      {enableWorkflowEditor ? <WorkflowEditor /> : <PipelineBar />}
+
+      {/* W11.6 ProgressBar + Cancel */}
+      {enableProgressBar && <ProgressBar />}
+
+      {/* W9.1 History panel (horizontal at bottom) */}
+      {showHistoryPanel && <HistoryPanel variant="horizontal" />}
+
+      {/* W9.5 Download panel (条件渲染:有 outputs 时显示) */}
+      {enableDownloadPanel && <DownloadPanel />}
 
       {/* Bottom: StatusBar */}
       {showStatusBar && <StatusBar />}

package/src/data/workflow-templates.ts

@@ -0,0 +1,137 @@
+/**
+ * 工作流模板数据(W11.4)
+ *
+ * 5 个内置模板,覆盖常见图片处理场景:
+ *   1. Web 优化 - resize + compress(webp),适用于网页素材
+ *   2. 社媒批量 - resize(1080) + watermark,适用于 Instagram/Twitter
+ *   3. 电商主图 - resize(800) + compress(jpeg) + watermark(店铺名)
+ *   4. 打印预处理 - resize(高分辨率) + convert(png),无损打印
+ *   5. 截图压缩 - resize(1280) + compress(png, 低质量),减小体积
+ *
+ * 每个模板仅含 capability + 默认 params,由 loadWorkflowTemplate() 应用到 store。
+ * 用户应用模板后仍可在 Inspector 调整参数。
+ *
+ * @module workflow-templates
+ */
+
+/** 单个模板节点定义 */
+export interface WorkflowTemplateNode {
+  /** 能力名,如 `image.resize` */
+  capability: string;
+  /** 默认参数(用户可修改) */
+  params: Record<string, unknown>;
+}
+
+/** 工作流模板 */
+export interface WorkflowTemplate {
+  /** 模板 ID(唯一) */
+  id: string;
+  /** 模板名称(中文) */
+  name: string;
+  /** 模板描述 */
+  description: string;
+  /** 图标 emoji(用于 UI 展示) */
+  icon: string;
+  /** 模板分类 */
+  category: 'web' | 'social' | 'ecommerce' | 'print' | 'utility';
+  /** 节点序列 */
+  nodes: WorkflowTemplateNode[];
+}
+
+/** 5 个内置工作流模板 */
+export const WORKFLOW_TEMPLATES: WorkflowTemplate[] = [
+  {
+    id: 'tpl-web-optimize',
+    name: 'Web 优化',
+    description: '调整尺寸并压缩为 WebP,适用于网页素材',
+    icon: '🌐',
+    category: 'web',
+    nodes: [
+      {
+        capability: 'image.resize',
+        params: { width: 1920, height: 1080, fit: 'inside' },
+      },
+      {
+        capability: 'image.compress',
+        params: { format: 'webp', quality: 80 },
+      },
+    ],
+  },
+  {
+    id: 'tpl-social-batch',
+    name: '社媒批量',
+    description: '统一为 1080px 并添加水印,适用于 Instagram/Twitter',
+    icon: '📱',
+    category: 'social',
+    nodes: [
+      {
+        capability: 'image.resize',
+        params: { width: 1080, height: 1080, fit: 'cover' },
+      },
+      {
+        capability: 'image.watermark',
+        params: { text: '@username', position: 'bottom-right', opacity: 0.7 },
+      },
+    ],
+  },
+  {
+    id: 'tpl-ecommerce-main',
+    name: '电商主图',
+    description: '800px 主图 + JPEG 压缩 + 店铺水印',
+    icon: '🛒',
+    category: 'ecommerce',
+    nodes: [
+      {
+        capability: 'image.resize',
+        params: { width: 800, height: 800, fit: 'contain' },
+      },
+      {
+        capability: 'image.compress',
+        params: { format: 'jpeg', quality: 90 },
+      },
+      {
+        capability: 'image.watermark',
+        params: { text: '店铺名', position: 'center', opacity: 0.3 },
+      },
+    ],
+  },
+  {
+    id: 'tpl-print-prep',
+    name: '打印预处理',
+    description: '高分辨率 resize + PNG 无损转换,适用于打印',
+    icon: '🖨️',
+    category: 'print',
+    nodes: [
+      {
+        capability: 'image.resize',
+        params: { width: 3508, height: 2480, fit: 'inside', dpi: 300 },
+      },
+      {
+        capability: 'image.convert',
+        params: { format: 'png' },
+      },
+    ],
+  },
+  {
+    id: 'tpl-screenshot-compress',
+    name: '截图压缩',
+    description: '缩小到 1280px 并压缩为低质量 PNG,减小体积',
+    icon: '📸',
+    category: 'utility',
+    nodes: [
+      {
+        capability: 'image.resize',
+        params: { width: 1280, height: 720, fit: 'inside' },
+      },
+      {
+        capability: 'image.compress',
+        params: { format: 'png', quality: 60 },
+      },
+    ],
+  },
+];
+
+/** 按 ID 查找模板 */
+export function findTemplate(id: string): WorkflowTemplate | undefined {
+  return WORKFLOW_TEMPLATES.find((t) => t.id === id);
+}

package/src/hooks/useDebouncedRun.ts

@@ -0,0 +1,151 @@
+/**
+ * useDebouncedRun - 修改参数后 debounced 自动重跑(W11.2)
+ *
+ * 监听当前工作流节点序列(含 params),变化后延迟 delay 毫秒自动调用
+ * store.run(),实现"修改参数即时预览"。
+ *
+ * 设计要点:
+ *   - 仅在 enabled=true 且 nodes.length>0 且 selectedAssetId 存在时触发
+ *   - debounce 避免连续修改(如拖滑块)触发过多执行
+ *   - 组件卸载时清除 timer,避免卸载后仍调用 store action
+ *   - running 期间不触发新的 run(避免并发执行同一工作流;run() 也有并发保护)
+ *   - 用户可手动触发 runNow() 立即执行(取消 pending debounce)
+ *
+ * 实现说明:
+ *   - 主 effect 依赖 [nodesKey, enabled, selectedAssetId, delay](用户输入)
+ *   - run / running / nodes.length 通过 ref 读取最新值,避免加入 deps:
+ *     - run / running:store action 引用每次 store 变化都变,加入 deps 触发循环重订阅
+ *     - nodes.length:节点数量变化必然使 nodesKey(JSON 序列化)变化,
+ *       加入 deps 是冗余触发源(节点增减会触发两次 effect 重新计时)
+ *   - 这是 React 社区标准模式(避免 effect 与 store action 循环 + 消除冗余触发),非 workaround
+ *
+ * 典型用法:
+ * ```tsx
+ * const { enabled, setEnabled, runNow } = useDebouncedRun({ delay: 400 });
+ * <Toggle checked={enabled} onChange={setEnabled} label="实时预览" />
+ * ```
+ *
+ * @module useDebouncedRun
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useWorkspaceStore } from '../store/index.js';
+
+export interface UseDebouncedRunOptions {
+  /** 防抖延迟毫秒(默认 400ms,平衡响应性与性能) */
+  delay?: number;
+  /** 初始是否启用(默认 false,需用户显式开启避免意外执行) */
+  initialEnabled?: boolean;
+}
+
+export interface UseDebouncedRunResult {
+  /** 当前是否启用自动运行 */
+  enabled: boolean;
+  /** 切换启用状态 */
+  setEnabled: (v: boolean) => void;
+  /** 立即触发运行(取消 pending debounce) */
+  runNow: () => void;
+  /** 取消 pending debounce(不取消正在运行的) */
+  cancelPending: () => void;
+  /** 是否有 pending 的执行(等待 debounce 触发) */
+  isPending: boolean;
+}
+
+/** 序列化节点序列用于变化检测(params 嵌套对象需稳定序列化) */
+function serializeNodes(
+  nodes: ReadonlyArray<{ capability: string; params: Record<string, unknown> }>
+): string {
+  return JSON.stringify(
+    nodes.map((n) => ({ c: n.capability, p: n.params }))
+  );
+}
+
+export function useDebouncedRun(
+  options: UseDebouncedRunOptions = {}
+): UseDebouncedRunResult {
+  const { delay = 400, initialEnabled = false } = options;
+  const [enabled, setEnabled] = useState(initialEnabled);
+  const [isPending, setIsPending] = useState(false);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const nodes = useWorkspaceStore((s) => s.nodes);
+  const selectedAssetId = useWorkspaceStore((s) => s.selectedAssetId);
+  const running = useWorkspaceStore((s) => s.running);
+  const run = useWorkspaceStore((s) => s.run);
+
+  // 用 ref 持有最新的 run / running / nodes.length 引用:
+  // 主 effect 依赖数组只跟踪用户输入(nodesKey / enabled / selectedAssetId / delay),
+  // 不包含 store action 引用(每次 store 变化都生成新函数引用,加入 deps 会
+  // 触发 effect 重订阅 → debounce timer 重置 → 无法稳定等待 delay)。
+  // nodes.length 同样用 ref 读取:节点数量变化必然导致 nodesKey(JSON 序列化)
+  // 变化,nodes.length 在主 effect deps 中是冗余触发源,改用 ref 在 body 中读取
+  // 最新值即可(与 run / running 同模式,非 workaround)。
+  const runRef = useRef(run);
+  const runningRef = useRef(running);
+  const nodesLengthRef = useRef(nodes.length);
+  useEffect(() => {
+    runRef.current = run;
+    runningRef.current = running;
+    nodesLengthRef.current = nodes.length;
+  }, [run, running, nodes.length]);
+
+  // 序列化节点,作为 debounce 触发依赖
+  const nodesKey = serializeNodes(nodes);
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+      timerRef.current = null;
+    }
+    setIsPending(false);
+  }, []);
+
+  const runNow = useCallback(() => {
+    clearTimer();
+    if (!selectedAssetId || nodesLengthRef.current === 0 || runningRef.current) return;
+    void runRef.current();
+  }, [clearTimer, selectedAssetId]);
+
+  // 监听节点序列变化。依赖数组为用户输入:
+  //   nodesKey(序列化节点) / enabled / selectedAssetId / delay
+  // run / running / nodes.length 通过 ref 读取最新值(见上):
+  //   - run / running:action 引用每次 store 变化都变,加入 deps 触发循环重订阅
+  //   - nodes.length:节点数量变化必然使 nodesKey 变化,加入 deps 是冗余触发源
+  useEffect(() => {
+    if (!enabled) return;
+    if (!selectedAssetId || nodesLengthRef.current === 0 || runningRef.current) return;
+
+    // 清除上一次 pending,重新计时
+    if (timerRef.current !== null) {
+      clearTimeout(timerRef.current);
+    }
+    setIsPending(true);
+    timerRef.current = setTimeout(() => {
+      timerRef.current = null;
+      setIsPending(false);
+      // 再次检查 running + 节点非空,避免 timer 排队期间状态已变化
+      // (用户手动触发 run / 清空节点)
+      if (!runningRef.current && nodesLengthRef.current > 0) {
+        void runRef.current();
+      }
+    }, delay);
+
+    return () => {
+      // cleanup:清 timer + 重置 isPending。React 18 卸载后调用 setState 不再 warn,
+      // 但 cleanup 仍是正确做法(避免卸载后 timer 触发仍调用 store action)。
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      setIsPending(false);
+    };
+  }, [nodesKey, enabled, selectedAssetId, delay]);
+
+  return {
+    enabled,
+    setEnabled,
+    runNow,
+    cancelPending: clearTimer,
+    isPending,
+  };
+}

package/src/hooks/useLokvis.ts

@@ -71,7 +71,7 @@ export function useLokvis(options: UseLokvisOptions = {}): UseLokvisResult {
     return () => {
       cancelled = true;
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
+    // oxlint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   return { runtime, status, error };

package/src/hooks/useMediaQuery.ts

@@ -0,0 +1,53 @@
+/**
+ * useMediaQuery - 响应式断点 hook(W9.8)
+ *
+ * 在 React 中订阅 `matchMedia` 查询,断点变化时触发组件重渲染。
+ * SSR 安全:`window` 不存在时返回初始值 `false`。
+ *
+ * @example
+ * ```tsx
+ * const isMobile = useMediaQuery('(max-width: 768px)');
+ * const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
+ * ```
+ *
+ * 内置断点常量(与 Tailwind v4 默认对齐):
+ *   - sm: 640px, md: 768px, lg: 1024px, xl: 1280px, 2xl: 1536px
+ */
+
+import { useEffect, useState } from 'react';
+
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState<boolean>(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return false;
+    return window.matchMedia(query).matches;
+  });
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+    const mq = window.matchMedia(query);
+    const onChange = () => setMatches(mq.matches);
+    // 初始同步(matchMedia 可能在 effect 跑前已变化)
+    setMatches(mq.matches);
+    mq.addEventListener('change', onChange);
+    return () => mq.removeEventListener('change', onChange);
+  }, [query]);
+
+  return matches;
+}
+
+/** W9.8 三档断点 helper */
+export interface Breakpoints {
+  /** 移动端 (< 768px) */
+  isMobile: boolean;
+  /** 平板 (768px - 1023px) */
+  isTablet: boolean;
+  /** 桌面 (>= 1024px) */
+  isDesktop: boolean;
+}
+
+export function useBreakpoints(): Breakpoints {
+  const isMobile = useMediaQuery('(max-width: 767px)');
+  const isTablet = useMediaQuery('(min-width: 768px) and (max-width: 1023px)');
+  const isDesktop = useMediaQuery('(min-width: 1024px)');
+  return { isMobile, isTablet, isDesktop };
+}