@lokvis/ui-react 0.1.0

package/src/components/Workspace.tsx

@@ -0,0 +1,90 @@
+/**
+ * Workspace - 完整工作台组件
+ *
+ * 标准三栏布局：Toolbar → [AssetPanel | Canvas | Inspector] → PipelineBar → StatusBar
+ * 通过 useLokvis 自动初始化 Runtime 与插件。
+ *
+ * @example
+ * ```tsx
+ * import { Workspace } from '@lokvis/ui-react';
+ * import imageToolsPlugin from '@lokvis/plugin-image';
+ *
+ * <Workspace plugins={[imageToolsPlugin()]} />
+ * ```
+ */
+
+import { useLokvis, type UseLokvisOptions } from '../hooks/useLokvis.js';
+import { Toolbar } from './Toolbar.js';
+import { AssetPanel } from './AssetPanel.js';
+import { Canvas } from './Canvas.js';
+import { Inspector } from './Inspector.js';
+import { PipelineBar } from './PipelineBar.js';
+import { StatusBar } from './StatusBar.js';
+
+export interface WorkspaceProps extends UseLokvisOptions {
+  /** 顶部标题 */
+  title?: string;
+  /** 是否显示状态栏（默认 true） */
+  showStatusBar?: boolean;
+  className?: string;
+}
+
+export function Workspace({
+  title,
+  showStatusBar = true,
+  className = '',
+  ...lokvisOptions
+}: WorkspaceProps) {
+  const { status, error } = useLokvis(lokvisOptions);
+
+  if (status === 'initializing') {
+    return (
+      <div className="flex h-full items-center justify-center">
+        <div className="flex flex-col items-center gap-4">
+          <div className="relative flex h-12 w-12 items-center justify-center">
+            <div className="absolute inset-0 rounded-full border-2 border-indigo-200 dark:border-indigo-800" />
+            <div className="h-8 w-8 animate-spin rounded-full border-2 border-transparent border-t-indigo-500" />
+          </div>
+          <div className="text-center">
+            <p className="text-sm font-medium text-zinc-700 dark:text-zinc-300">Initializing Runtime</p>
+            <p className="mt-1 text-xs text-zinc-400">Loading plugins and capabilities...</p>
+          </div>
+        </div>
+      </div>
+    );
+  }
+
+  if (status === 'error') {
+    return (
+      <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>
+          </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>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className={`flex h-full flex-col bg-white dark:bg-zinc-900 ${className}`}>
+      {/* Top: Toolbar */}
+      <Toolbar title={title} />
+
+      {/* Middle: Three-panel area */}
+      <div className="flex flex-1 overflow-hidden">
+        <AssetPanel />
+        <Canvas />
+        <Inspector />
+      </div>
+
+      {/* Pipeline bar */}
+      <PipelineBar />
+
+      {/* Bottom: StatusBar */}
+      {showStatusBar && <StatusBar />}
+    </div>
+  );
+}

package/src/hooks/useLokvis.ts

@@ -0,0 +1,78 @@
+/**
+ * useLokvis - 在 React 中初始化 Lokvis Runtime 并加载插件
+ *
+ * @example
+ * ```tsx
+ * import { useLokvis } from '@lokvis/ui-react';
+ * import imageToolsPlugin from '@lokvis/plugin-image';
+ *
+ * function App() {
+ *   const { runtime, status, error } = useLokvis({
+ *     plugins: [imageToolsPlugin()],
+ *   });
+ *   if (!runtime) return <p>Loading...</p>;
+ *   return <Workspace />;
+ * }
+ * ```
+ */
+
+import { useEffect, useRef, useState } from 'react';
+import { createLokvis } from '@lokvis/sdk';
+import type { LokvisRuntime, RuntimeConfig } from '@lokvis/runtime';
+import type { PluginLoadEntry } from '@lokvis/sdk';
+import { useWorkspaceStore } from '../store/index.js';
+
+export interface UseLokvisOptions extends RuntimeConfig {
+  /** 预加载的插件列表 */
+  plugins?: PluginLoadEntry[];
+  /** 是否在挂载时自动初始化（默认 true） */
+  autoInit?: boolean;
+}
+
+export interface UseLokvisResult {
+  runtime: LokvisRuntime | null;
+  status: 'idle' | 'initializing' | 'ready' | 'error';
+  error: string | null;
+}
+
+export function useLokvis(options: UseLokvisOptions = {}): UseLokvisResult {
+  const { plugins = [], autoInit = true, ...runtimeConfig } = options;
+  const [runtime, setRuntime] = useState<LokvisRuntime | null>(null);
+  const [status, setStatus] = useState<UseLokvisResult['status']>('idle');
+  const [error, setError] = useState<string | null>(null);
+  const initRef = useRef(false);
+
+  const storeInit = useWorkspaceStore((s) => s.init);
+
+  useEffect(() => {
+    if (!autoInit || initRef.current) return;
+    initRef.current = true;
+
+    let cancelled = false;
+    (async () => {
+      try {
+        setStatus('initializing');
+        const rt = await createLokvis({
+          ...runtimeConfig,
+          plugins,
+        });
+        if (cancelled) return;
+        setRuntime(rt);
+        await storeInit(rt);
+        if (cancelled) return;
+        setStatus('ready');
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : String(err));
+        setStatus('error');
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return { runtime, status, error };
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * @lokvis/ui-react
+ *
+ * Lokvis Workspace UI - React workspace component library.
+ *
+ * Provides:
+ * - `<Workspace />` - Ready-to-use local-first workspace
+ * - `<AssetPanel />` - Asset panel (import / select / preview)
+ * - `<Canvas />` - Canvas preview area
+ * - `<Inspector />` - Right panel for capability configuration
+ * - `<PipelineBar />` - Workflow pipeline step bar
+ * - `<Toolbar />` - Top toolbar
+ * - `<StatusBar />` - Bottom status bar
+ * - `useLokvis()` - React hook for initializing Runtime + plugins
+ */
+
+export { useLokvis, type UseLokvisOptions, type UseLokvisResult } from './hooks/useLokvis.js';
+export { useWorkspaceStore, type WorkspaceState, type WorkspaceActions } from './store/index.js';
+
+export { Workspace, type WorkspaceProps } from './components/Workspace.js';
+export { AssetPanel } from './components/AssetPanel.js';
+export { Canvas } from './components/Canvas.js';
+export { Inspector } from './components/Inspector.js';
+export { PipelineBar } from './components/PipelineBar.js';
+export { Toolbar } from './components/Toolbar.js';
+export { StatusBar } from './components/StatusBar.js';
+export { ParamForm, type ParamFormProps } from './components/ParamForm.js';
+
+export type {
+  WorkspaceEvent,
+  NodeStatus,
+} from './types.js';

package/src/store/assets-slice.ts

@@ -0,0 +1,57 @@
+/**
+ * Assets slice —— 资产导入 / 选择 / 删除 / 缩略图
+ */
+import type { StateCreator } from 'zustand';
+import type { WorkspaceStore, WorkspaceState, WorkspaceActions } from './types.js';
+
+export interface AssetsSlice
+  extends Pick<WorkspaceState, 'assets' | 'selectedAssetId' | 'thumbnails'>,
+    Pick<
+      WorkspaceActions,
+      'refreshAssets' | 'importFiles' | 'selectAsset' | 'setThumbnail' | 'removeAsset'
+    > {}
+
+export const createAssetsSlice: StateCreator<
+  WorkspaceStore,
+  [],
+  [],
+  AssetsSlice
+> = (set, get) => ({
+  assets: [],
+  selectedAssetId: null,
+  thumbnails: {},
+
+  async refreshAssets() {
+    const { runtime } = get();
+    if (!runtime) return;
+    const assets = await runtime.listAssets();
+    set({ assets });
+  },
+
+  async importFiles(files) {
+    const { runtime } = get();
+    if (!runtime) return;
+    set({ statusMessage: `Importing ${files.length} file(s)...` });
+    for (const file of files) {
+      await runtime.importAsset({ kind: 'file', file });
+    }
+    await get().refreshAssets();
+    set({ statusMessage: `Imported ${files.length} file(s)` });
+  },
+
+  selectAsset(id) {
+    set({ selectedAssetId: id });
+  },
+
+  setThumbnail(id, url) {
+    set((state) => ({ thumbnails: { ...state.thumbnails, [id]: url } }));
+  },
+
+  async removeAsset(id) {
+    const { runtime } = get();
+    if (!runtime) return;
+    await runtime.removeAsset(id);
+    await get().refreshAssets();
+    if (get().selectedAssetId === id) set({ selectedAssetId: null });
+  },
+});

package/src/store/capabilities-slice.ts

@@ -0,0 +1,29 @@
+/**
+ * Capabilities slice —— 能力列表与映射
+ */
+import type { StateCreator } from 'zustand';
+import type { CapabilityMap } from '../types.js';
+import type { WorkspaceStore, WorkspaceState, WorkspaceActions } from './types.js';
+
+export interface CapabilitiesSlice
+  extends Pick<WorkspaceState, 'capabilities' | 'capabilityMap'>,
+    Pick<WorkspaceActions, 'refreshCapabilities'> {}
+
+export const createCapabilitiesSlice: StateCreator<
+  WorkspaceStore,
+  [],
+  [],
+  CapabilitiesSlice
+> = (set, get) => ({
+  capabilities: [],
+  capabilityMap: {},
+
+  async refreshCapabilities() {
+    const { runtime } = get();
+    if (!runtime) return;
+    const capabilities = await runtime.capabilities();
+    const capabilityMap: CapabilityMap = {};
+    for (const cap of capabilities) capabilityMap[cap.name] = cap;
+    set({ capabilities, capabilityMap });
+  },
+});

package/src/store/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Workspace UI 状态管理(Zustand)
+ *
+ * 按域拆分为 4 个 slice:
+ * - runtime-slice:      Runtime 初始化、全局状态消息、错误
+ * - assets-slice:       资产导入 / 选择 / 删除 / 缩略图
+ * - capabilities-slice: 能力列表与映射
+ * - workflow-slice:     工作流节点编排与执行
+ *
+ * 各 slice 独立演进,W6/W7/W9 扩展时按 slice 添加 action 即可。
+ * Runtime 永远不知道 React,但 UI 层负责把 Runtime 事件桥接到 store。
+ */
+import { create } from 'zustand';
+import type { WorkspaceStore } from './types.js';
+import { createRuntimeSlice } from './runtime-slice.js';
+import { createAssetsSlice } from './assets-slice.js';
+import { createCapabilitiesSlice } from './capabilities-slice.js';
+import { createWorkflowSlice } from './workflow-slice.js';
+
+export const useWorkspaceStore = create<WorkspaceStore>()((...a) => ({
+  ...createRuntimeSlice(...a),
+  ...createAssetsSlice(...a),
+  ...createCapabilitiesSlice(...a),
+  ...createWorkflowSlice(...a),
+}));
+
+export type { WorkspaceState, WorkspaceActions, WorkspaceStore } from './types.js';

package/src/store/runtime-slice.ts

@@ -0,0 +1,53 @@
+/**
+ * Runtime slice —— Runtime 初始化与状态消息
+ *
+ * 负责 runtime 实例注入、初始化、全局状态消息与错误。
+ */
+import type { StateCreator } from 'zustand';
+import type { WorkspaceStore, WorkspaceState, WorkspaceActions } from './types.js';
+
+export interface RuntimeSlice
+  extends Pick<
+    WorkspaceState,
+    'runtime' | 'initializing' | 'initError' | 'running' | 'statusMessage' | 'error'
+  >,
+    Pick<
+      WorkspaceActions,
+      'init' | 'setStatus' | 'setError'
+    > {}
+
+export const createRuntimeSlice: StateCreator<
+  WorkspaceStore,
+  [],
+  [],
+  RuntimeSlice
+> = (set, get) => ({
+  runtime: null,
+  initializing: false,
+  initError: null,
+  running: false,
+  statusMessage: 'Idle',
+  error: null,
+
+  async init(runtime) {
+    set({ runtime, initializing: true, initError: null });
+    try {
+      await get().refreshAssets();
+      await get().refreshCapabilities();
+      set({ initializing: false, statusMessage: 'Ready' });
+    } catch (err) {
+      set({
+        initializing: false,
+        initError: err instanceof Error ? err.message : String(err),
+      });
+    }
+  },
+
+  setStatus(message) {
+    set({ statusMessage: message });
+  },
+
+  setError(error) {
+    set({ error });
+  },
+});

package/src/store/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Workspace Store 类型定义
+ *
+ * 把原 store.ts 顶部的 WorkspaceState / WorkspaceActions 抽出,
+ * 供各 slice 引用,避免循环依赖。
+ */
+import type { Asset, Capability } from '@lokvis/schema';
+import type { LokvisRuntime } from '@lokvis/runtime';
+import type { CapabilityMap, NodeStatus, WorkspaceNode } from '../types.js';
+
+/** 工作台完整状态 */
+export interface WorkspaceState {
+  /** Runtime 实例 */
+  runtime: LokvisRuntime | null;
+  /** 是否正在初始化 Runtime */
+  initializing: boolean;
+  /** 初始化错误 */
+  initError: string | null;
+
+  /** 所有已导入资产 */
+  assets: Asset[];
+  /** 当前选中的资产 ID */
+  selectedAssetId: string | null;
+  /** 资产缩略图（AssetId → ObjectURL） */
+  thumbnails: Record<string, string>;
+
+  /** 所有已注册能力 */
+  capabilities: Capability[];
+  /** 能力映射表（name → Capability） */
+  capabilityMap: CapabilityMap;
+
+  /** 工作流节点序列（线性链） */
+  nodes: WorkspaceNode[];
+  /** 当前选中的节点 ID */
+  selectedNodeId: string | null;
+
+  /** 是否正在执行工作流 */
+  running: boolean;
+  /** 全局状态消息 */
+  statusMessage: string;
+  /** 错误信息 */
+  error: string | null;
+}
+
+/** 工作台操作 */
+export interface WorkspaceActions {
+  /** 初始化 Runtime */
+  init(runtime: LokvisRuntime): Promise<void>;
+  /** 刷新资产列表 */
+  refreshAssets(): Promise<void>;
+  /** 刷新能力列表 */
+  refreshCapabilities(): Promise<void>;
+  /** 导入文件 */
+  importFiles(files: File[]): Promise<void>;
+  /** 选择资产 */
+  selectAsset(id: string | null): void;
+  /** 设置缩略图 */
+  setThumbnail(id: string, url: string): void;
+  /** 删除资产 */
+  removeAsset(id: string): Promise<void>;
+
+  /** 添加工作流节点 */
+  addNode(capability: string): void;
+  /** 更新节点参数 */
+  updateNodeParams(id: string, params: Record<string, unknown>): void;
+  /** 删除节点 */
+  removeNode(id: string): void;
+  /** 选择节点 */
+  selectNode(id: string | null): void;
+  /** 设置节点状态 */
+  setNodeStatus(id: string, status: NodeStatus, error?: string, duration?: number): void;
+
+  /** 执行工作流 */
+  run(): Promise<Asset[]>;
+  /** 设置状态消息 */
+  setStatus(message: string): void;
+  /** 设置错误 */
+  setError(error: string | null): void;
+  /** 清空工作流 */
+  clearWorkflow(): void;
+}
+
+export type WorkspaceStore = WorkspaceState & WorkspaceActions;
+
+/** 生成节点 ID */
+export function genNodeId(): string {
+  return `node_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
+}

package/src/store/workflow-slice.ts

@@ -0,0 +1,178 @@
+/**
+ * Workflow slice —— 工作流节点编排与执行
+ *
+ * 负责:
+ * - 节点 CRUD(add / remove / updateParams / select / setNodeStatus)
+ * - 工作流执行(run):构建线性 Workflow → 调用 runtime.run → 更新节点状态
+ * - 清空(clearWorkflow)
+ *
+ * run() 内部依赖 buildLinearWorkflow(本地工具)把节点序列构建为 Workflow 定义。
+ */
+import type { StateCreator } from 'zustand';
+import type { Asset, Workflow, WorkflowEdge, WorkflowNode } from '@lokvis/schema';
+import type { WorkspaceNode } from '../types.js';
+import type { WorkspaceStore, WorkspaceState, WorkspaceActions } from './types.js';
+import { genNodeId } from './types.js';
+
+export interface WorkflowSlice
+  extends Pick<WorkspaceState, 'nodes' | 'selectedNodeId'>,
+    Pick<
+      WorkspaceActions,
+      | 'addNode'
+      | 'updateNodeParams'
+      | 'removeNode'
+      | 'selectNode'
+      | 'setNodeStatus'
+      | 'run'
+      | 'clearWorkflow'
+    > {}
+
+export const createWorkflowSlice: StateCreator<
+  WorkspaceStore,
+  [],
+  [],
+  WorkflowSlice
+> = (set, get) => ({
+  nodes: [],
+  selectedNodeId: null,
+
+  addNode(capability) {
+    const node: WorkspaceNode = {
+      id: genNodeId(),
+      capability,
+      params: {},
+      status: 'idle',
+    };
+    set((state) => ({
+      nodes: [...state.nodes, node],
+      selectedNodeId: node.id,
+    }));
+  },
+
+  updateNodeParams(id, params) {
+    set((state) => ({
+      nodes: state.nodes.map((n) => (n.id === id ? { ...n, params } : n)),
+    }));
+  },
+
+  removeNode(id) {
+    set((state) => ({
+      nodes: state.nodes.filter((n) => n.id !== id),
+      selectedNodeId: state.selectedNodeId === id ? null : state.selectedNodeId,
+    }));
+  },
+
+  selectNode(id) {
+    set({ selectedNodeId: id });
+  },
+
+  setNodeStatus(id, status, error, duration) {
+    set((state) => ({
+      nodes: state.nodes.map((n) =>
+        n.id === id ? { ...n, status, error, duration } : n
+      ),
+    }));
+  },
+
+  async run() {
+    const { runtime, nodes, selectedAssetId } = get();
+    if (!runtime) throw new Error('Runtime not initialized');
+    if (nodes.length === 0) throw new Error('Workflow is empty');
+    if (!selectedAssetId) throw new Error('No asset selected');
+
+    set({ running: true, error: null, statusMessage: 'Running...' });
+
+    // 重置所有节点状态
+    set((state) => ({
+      nodes: state.nodes.map((n) => ({ ...n, status: 'pending', error: undefined })),
+    }));
+
+    try {
+      // 构建 Workflow
+      const workflow = buildLinearWorkflow(nodes);
+      const input = await runtime.getAsset(selectedAssetId);
+
+      set({ statusMessage: 'Running workflow...' });
+      const result = await runtime.run(workflow, [input]);
+
+      // 更新节点状态
+      if (result.status === 'completed') {
+        for (const node of nodes) {
+          get().setNodeStatus(node.id, 'success', undefined, undefined);
+        }
+      } else if (result.status === 'failed') {
+        for (const node of nodes) {
+          if (get().nodes.find((n) => n.id === node.id)?.status === 'pending') {
+            get().setNodeStatus(node.id, 'failed', result.error);
+          }
+        }
+      }
+
+      // 加载输出资产
+      const outputs: Asset[] = [];
+      for (const id of result.outputs) {
+        try {
+          outputs.push(await runtime.getAsset(id));
+        } catch {
+          // skip
+        }
+      }
+
+      set({
+        running: false,
+        statusMessage: `Workflow ${result.status} in ${result.duration}ms`,
+      });
+
+      if (result.status === 'failed') {
+        set({ error: result.error ?? 'Workflow failed' });
+      }
+
+      await get().refreshAssets();
+      return outputs;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      set({
+        running: false,
+        error: message,
+        statusMessage: 'Failed',
+      });
+      throw err;
+    }
+  },
+
+  clearWorkflow() {
+    set({ nodes: [], selectedNodeId: null });
+  },
+});
+
+/** 把工作台节点序列构建为线性 Workflow */
+function buildLinearWorkflow(nodes: WorkspaceNode[]): Workflow {
+  if (nodes.length === 0) {
+    throw new Error('Workflow is empty');
+  }
+  const workflowNodes: WorkflowNode[] = nodes.map((n) => ({
+    id: n.id,
+    type: 'transform' as const,
+    capability: n.capability,
+    params: n.params,
+  }));
+  const edges: WorkflowEdge[] = [];
+  for (let i = 0; i < workflowNodes.length - 1; i++) {
+    edges.push({ from: workflowNodes[i]!.id, to: workflowNodes[i + 1]!.id });
+  }
+  return {
+    id: `wf_${Date.now().toString(36)}`,
+    name: 'Workspace Workflow',
+    version: '1',
+    description: 'Workspace linear workflow',
+    author: { id: 'local', name: 'Local User' },
+    category: 'image',
+    tags: [],
+    nodes: workflowNodes,
+    edges,
+    inputs: { type: 'image', multiple: true },
+    outputs: { type: 'image' },
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+  };
+}

package/src/types.ts

@@ -0,0 +1,46 @@
+/**
+ * Workspace UI 类型定义
+ */
+
+import type { Asset, Capability, WorkflowResult } from '@lokvis/schema';
+
+/** 工作台事件（用于事件回调） */
+export interface WorkspaceEvent {
+  type:
+    | 'asset:imported'
+    | 'asset:selected'
+    | 'asset:removed'
+    | 'capability:added'
+    | 'workflow:started'
+    | 'workflow:completed'
+    | 'workflow:failed';
+  payload?: unknown;
+}
+
+/** 节点状态 */
+export type NodeStatus = 'idle' | 'pending' | 'running' | 'success' | 'failed' | 'cancelled';
+
+/** 已添加到工作台的工作流节点 */
+export interface WorkspaceNode {
+  id: string;
+  capability: string;
+  params: Record<string, unknown>;
+  status: NodeStatus;
+  /** 上次执行的耗时（毫秒） */
+  duration?: number;
+  /** 错误信息 */
+  error?: string;
+}
+
+/** 工作台运行结果摘要 */
+export interface RunSummary {
+  result?: WorkflowResult;
+  outputs: Asset[];
+  duration: number;
+}
+
+/** 资产缩略图缓存 */
+export type ThumbnailMap = Record<string, string>;
+
+/** 能力映射表（按能力名索引） */
+export type CapabilityMap = Record<string, Capability>;