nx-kv 0.1.1

package/src/runtime/registry.js

@@ -0,0 +1,56 @@
+// 模块注册表：所有功能域的 action 在此汇合。
+//
+// CLI 命令表、HTTP 路由表、help 文本三者全部由此派生 —— 这是
+// 「Web 上每个操作都有等价 CLI 命令」得以成为**结构性保证**而非口头约定的原因：
+// 一条 action 同时声明 cli 与 http，二者写在同一处，不可能分叉。
+//
+// 新增功能域：
+//   1. 写 src/modules/<name>/（index.js 声明 actions，service.js 写业务，view.jsx 写面板）
+//   2. 在下面 import 并加进 MODULES；再到 web/frontend/registry.js 登记视图
+// tests/unit/registry.test.mjs 会断言两侧对齐，漏登记直接测试失败。
+import { cliPathsOf } from './spec.js';
+import system from '../modules/system/index.js';
+import auth from '../modules/auth/index.js';
+import group from '../modules/group/index.js';
+import todo from '../modules/todo/index.js';
+import bundled from '../modules/bundled/index.js';
+
+export const MODULES = [system, auth, group, todo, bundled].sort(
+  (a, b) => (a.order ?? 100) - (b.order ?? 100)
+);
+
+export const ACTIONS = MODULES.flatMap((m) =>
+  (m.actions || []).map((a) => ({ ...a, module: m.id }))
+);
+
+// 装载期自检：把「两个模块声明了同名命令」这类问题暴露在启动瞬间，
+// 而不是等某个用户敲到那条命令时才发现。
+//
+// 方向性约定（刻意的不对称）：
+//   - 每条 action 都必须有 cli —— 保证「Web 上能做的，CLI 都能做」
+//   - http 允许为 null（纯 CLI 命令），但**不允许**声明 http 却没有 cli
+const seenIds = new Set();
+const seenCli = new Set();
+const seenHttp = new Set();
+for (const a of ACTIONS) {
+  if (seenIds.has(a.id)) throw new Error('action id 重复: ' + a.id);
+  seenIds.add(a.id);
+
+  const paths = cliPathsOf(a);
+  if (!paths.length) throw new Error(`action 没有声明 CLI 命令（Web 操作必须有 CLI 等价）: ${a.id}`);
+  for (const path of paths) {
+    const key = path.join(' ');
+    if (seenCli.has(key)) throw new Error(`CLI 命令重复: ${key}（action ${a.id}）`);
+    seenCli.add(key);
+  }
+
+  if (a.http) {
+    const httpKey = a.http[0] + ' ' + a.http[1];
+    if (seenHttp.has(httpKey)) throw new Error(`HTTP 路由重复: ${httpKey}（action ${a.id}）`);
+    seenHttp.add(httpKey);
+  } else if (a.http !== null) {
+    throw new Error(`action 的 http 必须是路由数组或显式 null: ${a.id}`);
+  }
+
+  if (!a.run) throw new Error(`action 缺少 run: ${a.id}`);
+}

package/src/runtime/server.js

@@ -0,0 +1,74 @@
+// Web 服务器：node:http 零依赖。
+// 职责只有两件事：发静态面板文件 + 把 /api/* 交给路由层（见 api.js）。
+import http from 'node:http';
+import { extname, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import fsp from 'node:fs/promises';
+import { handleApi, sendJson } from './api.js';
+import { DEFAULT_PORT } from '../core/paths.js';
+
+// vite 的 outDir：src/web/public（构建产物，gitignore）
+const PUBLIC_DIR = resolve(fileURLToPath(new URL('../web/public/', import.meta.url)));
+
+const MIME = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff2': 'font/woff2',
+  '.map': 'application/json; charset=utf-8',
+};
+
+async function serveStatic(pathname, res) {
+  const rel = pathname === '/' ? 'index.html' : decodeURIComponent(pathname).replace(/^\/+/, '');
+  const file = resolve(PUBLIC_DIR, rel);
+
+  // 越界校验：解析成绝对路径后必须仍落在 PUBLIC_DIR 内。
+  // 比对解析结果，而不是剥离 '..' 字面量——后者挡不住编码变形。
+  if (file !== PUBLIC_DIR && !file.startsWith(PUBLIC_DIR + sep)) {
+    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('Forbidden');
+    return;
+  }
+
+  try {
+    const buf = await fsp.readFile(file);
+    res.writeHead(200, {
+      'content-type': MIME[extname(file).toLowerCase()] || 'application/octet-stream',
+      'cache-control': 'no-store',
+    });
+    res.end(buf);
+  } catch {
+    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+    res.end('Not Found');
+  }
+}
+
+export function startServer({ port = DEFAULT_PORT, host = '127.0.0.1' } = {}) {
+  const server = http.createServer(async (req, res) => {
+    try {
+      const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`);
+      if (url.pathname.startsWith('/api/')) {
+        await handleApi(req, res, url);
+        return;
+      }
+      await serveStatic(url.pathname, res);
+    } catch (err) {
+      sendJson(res, 500, {
+        ok: false,
+        error: String((err && err.message) || err),
+        code: 'INTERNAL',
+      });
+    }
+  });
+  return new Promise((resolve_, reject) => {
+    server.once('error', reject);
+    server.listen(port, host, () => resolve_(server));
+  });
+}

package/src/runtime/spec.js

@@ -0,0 +1,147 @@
+// action 规格的解析、校验与文本生成。
+//
+// 一处声明，两端生效：CLI 的 `--flag` 与 HTTP 的 query/body 都走同一套强转与校验。
+// 这正是历史上 `parseInt(flags.depth, 10) || 3` 散落在各处的根源——两端各写一遍解析，
+// 迟早分叉。现在 depth 只在 action 声明里写一次 `{ type: 'number', default: 3 }`。
+import { badInput } from '../core/errors.js';
+
+const TYPES = new Set(['string', 'number', 'boolean', 'array']);
+
+// 取 action 的 CLI 路径列表。支持两种写法：
+//   单路径   cli: ['repo', 'list']
+//   多路径   cli: [['bundled','list'], ['skill','install','--list']]   ← 别名
+export function cliPathsOf(action) {
+  const cli = action.cli;
+  if (!cli || !cli.length) return [];
+  return Array.isArray(cli[0]) ? cli : [cli];
+}
+
+// 位置参数规格：字符串表示必填，对象可声明 optional / rest（收集剩余全部）
+export function argSpecsOf(action) {
+  return (action.args || []).map((a) =>
+    typeof a === 'string'
+      ? { name: a, required: true }
+      : { ...a, required: a.required !== false }
+  );
+}
+
+export function flagSpecsOf(action) {
+  return Object.entries(action.flags || {}).map(([name, spec]) => ({ name, ...spec }));
+}
+
+// 该 action 里哪些 flag 是布尔型——CLI 解析据此决定要不要吃掉下一个 token 当值。
+// 少了这份信息，`skill install --force demo` 会把 force 解析成字符串 'demo'。
+export function booleanFlagNames(action) {
+  return new Set(flagSpecsOf(action).filter((f) => (f.type || 'string') === 'boolean').map((f) => f.name));
+}
+
+function coerceOne(name, spec, raw) {
+  const type = spec.type || 'string';
+  if (!TYPES.has(type)) throw new Error(`action 声明有误：flag "${name}" 的 type 非法 (${type})`);
+  if (raw === undefined || raw === null) return undefined;
+
+  // 需要值的 flag 写在末尾时（`--depth` 后面没跟东西），解析器只能记成 true。
+  // 放任下去：Number(true) === 1 会静默变成「深度 1」这种另一个合法值，
+  // String(true) 则会让路径变成 'true'。宁可报错，也不要把笔误变成别的语义。
+  if (raw === true && type !== 'boolean') {
+    throw badInput(`参数 --${name} 需要提供值`);
+  }
+
+  if (type === 'boolean') {
+    if (typeof raw === 'boolean') return raw;
+    const s = String(raw).toLowerCase();
+    return !(s === 'false' || s === '0' || s === 'no' || s === '');
+  }
+  if (type === 'number') {
+    const n = Number(raw);
+    if (!Number.isFinite(n)) throw badInput(`参数 ${name} 必须是数字，收到: ${raw}`);
+    return n;
+  }
+  if (type === 'array') {
+    if (Array.isArray(raw)) return raw.map((x) => String(x).trim()).filter(Boolean);
+    return String(raw).split(',').map((x) => x.trim()).filter(Boolean);
+  }
+  return String(raw);
+}
+
+// 参数缺失/非法时的统一报错。
+//
+// 「用法:」前缀是**对外契约**：assets/repo-hub/references/agent-workflow.md 明确
+// 教 agent 用错误文本里的「用法:」判定为参数错误，并据此决定「停下来问人」。
+// 所以这里不能只写「缺少参数 X」，必须带上完整用法串。
+function inputError(action, detail) {
+  return badInput(`用法: ${usageOf(action)} —— ${detail}`);
+}
+
+// 按声明校验并强转输入。未声明的键原样透传（HTTP body 可能带界面用的额外字段）。
+export function applySpec(action, raw) {
+  const out = { ...raw };
+
+  for (const spec of flagSpecsOf(action)) {
+    const v = coerceOne(spec.name, spec, raw[spec.name]);
+    if (v === undefined) {
+      if (spec.default !== undefined) out[spec.name] = spec.default;
+      else if (spec.required) throw inputError(action, `缺少参数 --${spec.name}`);
+      continue;
+    }
+    if (spec.enum && !spec.enum.includes(v)) {
+      throw inputError(action, `参数 --${spec.name} 只能是 ${spec.enum.join(' | ')}，收到: ${v}`);
+    }
+    out[spec.name] = v;
+  }
+
+  for (const spec of argSpecsOf(action)) {
+    const v = out[spec.name];
+    const empty = v === undefined || v === '' || (Array.isArray(v) && !v.length);
+    if (empty && spec.required) throw inputError(action, `缺少参数 <${spec.name}>`);
+  }
+  return out;
+}
+
+// ---- HTTP 路由模式编译：'/api/repos/:id' → 正则 + 键名 ----
+
+const ROUTE_CACHE = new WeakMap();
+
+export function compileRoute(action) {
+  const cached = ROUTE_CACHE.get(action);
+  if (cached) return cached;
+  const [method, pattern] = action.http;
+  const keys = [];
+  const body = pattern
+    .split('/')
+    .map((seg) => {
+      if (!seg.startsWith(':')) return seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      keys.push(seg.slice(1));
+      return '([^/]+)';
+    })
+    .join('/');
+  const compiled = { method, keys, regex: new RegExp('^' + body + '$') };
+  ROUTE_CACHE.set(action, compiled);
+  return compiled;
+}
+
+// ---- 用法串生成：从声明反推，help 因此不可能与实际命令脱节 ----
+
+export function usageOf(action) {
+  const [path] = cliPathsOf(action);
+  const parts = ['nx-kv', ...path];
+
+  for (const a of argSpecsOf(action)) {
+    const label = a.rest ? `${a.name}...` : a.name;
+    parts.push(a.required ? `<${label}>` : `[${label}]`);
+  }
+
+  for (const f of flagSpecsOf(action)) {
+    let token;
+    if (f.type === 'boolean') {
+      token = `--${f.name}`;
+    } else {
+      // 值的占位符优先用 enum 展开（--side <ours|theirs>），其次显式 hint，
+      // 最后才退回 flag 名——`--http <http>` 这种读起来没有信息量。
+      const hint = f.enum ? f.enum.join('|') : f.hint || f.name;
+      token = `--${f.name} <${hint}>`;
+    }
+    parts.push(f.required ? token : `[${token}]`);
+  }
+  return parts.join(' ');
+}

package/src/web/frontend/App.jsx

@@ -0,0 +1,74 @@
+// 应用壳：顶栏 + tab 导航（注册表驱动）+ hash 路由。
+// 路由即持久化：当前视图写进 location.hash 与 store，刷新/分享链接都停在原页面。
+import { Suspense, useEffect } from 'react';
+import { useStore } from './store.jsx';
+import { ErrorBoundary } from './components/ui.jsx';
+import { VIEWS } from './registry.js';
+
+function viewFromHash() {
+  const h = (location.hash || '').replace(/^#\/?/, '');
+  return VIEWS.some((v) => v.id === h) ? h : '';
+}
+
+export default function App() {
+  const { boot, ui, patchUi } = useStore();
+
+  // 初始进入：hash 优先，否则用持久化的上次视图
+  useEffect(() => {
+    const fromHash = viewFromHash();
+    if (fromHash && fromHash !== ui.view) patchUi({ view: fromHash });
+    else if (!location.hash) location.hash = '#/' + ui.view;
+    // 只在挂载时对齐一次：后续 hash 变化由下面的 hashchange 监听接管
+  }, []);
+
+  // hash 变化（浏览器前进后退）→ 同步 store
+  useEffect(() => {
+    const onHash = () => {
+      const v = viewFromHash();
+      if (v) patchUi({ view: v });
+    };
+    window.addEventListener('hashchange', onHash);
+    return () => window.removeEventListener('hashchange', onHash);
+  }, [patchUi]);
+
+  const current = VIEWS.find((v) => v.id === ui.view) || VIEWS[0];
+
+  const switchTo = (id) => {
+    patchUi({ view: id });
+    location.hash = '#/' + id;
+  };
+
+  return (
+    <>
+      <header>
+        <div className="brand">nx-kv<span className="sub">nx-kv</span></div>
+        <nav>
+          {VIEWS.map((v) => (
+            <button
+              key={v.id}
+              className={'tab' + (v.id === current.id ? ' active' : '')}
+              onClick={() => switchTo(v.id)}
+            >
+              {v.title}
+            </button>
+          ))}
+        </nav>
+        <div className="meta">{boot?.storePath || ''}</div>
+      </header>
+
+      <main>
+        {/* 边界放在 Suspense 外层：懒加载 chunk 拉取失败也由它接管，
+            否则一个视图崩掉就是整页白屏 */}
+        <ErrorBoundary key={current.id}>
+          <Suspense fallback={<div className="muted" style={{ padding: 24 }}>加载中…</div>}>
+            <section className="panel active"><current.component /></section>
+          </Suspense>
+        </ErrorBoundary>
+      </main>
+
+      <footer>
+        面板上每个按钮都有同构 CLI 命令（见各页底部提示）· <code>nx-kv help</code> · agent 可加 <code>--json</code> 获取机器可读输出
+      </footer>
+    </>
+  );
+}

package/src/web/frontend/api/client.js

@@ -0,0 +1,39 @@
+// API 客户端：全部面板操作走 /api，与 CLI 共享同一份 action 声明。
+//
+// 响应包约定 { ok: true, data } / { ok: false, error, code }。
+// 失败时抛 Error 并带上 .code —— 调用方可据此区分「业务冲突」与「参数错误」，
+// 而不是像改造前那样只能对错误文案做字符串匹配。
+const DEFAULT_TIMEOUT_MS = 30000;
+
+export async function api(path, opts = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), opts.timeoutMs || DEFAULT_TIMEOUT_MS);
+
+  try {
+    const res = await fetch(path, {
+      method: opts.method || 'GET',
+      headers: opts.body ? { 'content-type': 'application/json' } : undefined,
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+      signal: ctrl.signal,
+    });
+    let json;
+    try {
+      json = await res.json();
+    } catch {
+      throw new Error(`HTTP ${res.status}`);
+    }
+    if (!json.ok) {
+      const err = new Error(json.error || '请求失败');
+      err.code = json.code;
+      err.details = json.details;
+      throw err;
+    }
+    return json.data;
+  } catch (e) {
+    // AbortError 的原生文案是「The operation was aborted」，对用户没有意义
+    if (e && e.name === 'AbortError') throw new Error('请求超时（本地服务无响应）');
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/web/frontend/components/CliHints.jsx

@@ -0,0 +1,25 @@
+// CLI 等价提示：列出当前模块的全部同构命令。
+//
+// 为什么由数据派生而不是手写：这行提示是用户核对「面板上这个按钮到底有没有 CLI 等价」
+// 的唯一依据。改造前它是三个视图各自维护的字符串（reposView / skillsView / githubView
+// 各写一行），命令一改就悄悄过期——提示说「有」，实际没有，比没有提示更糟。
+// 现在它来自 bootstrap 下发的命令表，与 CLI 实际注册的命令同源。
+import { useStore } from '../store.jsx';
+import { Copyable } from './ui.jsx';
+
+export function CliHints({ module: moduleId }) {
+  const { boot } = useStore();
+  const cmds = (boot?.commands || []).filter((c) => c.module === moduleId);
+  if (!cmds.length) return null;
+
+  return (
+    <div className="cli-hint">
+      <span className="cli-hint-label">CLI 等价（同构命令，加 --json 得机器可读输出）：</span>
+      {cmds.map((c) => (
+        <Copyable key={c.id} className="cli-cmd" text={c.command} title={`点击复制：${c.usage}`}>
+          {c.command}
+        </Copyable>
+      ))}
+    </div>
+  );
+}

package/src/web/frontend/components/ui.jsx

@@ -0,0 +1,197 @@
+// 通用 UI 件：toast、对话框、弹窗、错误边界、diff 渲染。
+// 约定延续自 vanilla 版：无 emoji、不用浏览器原生弹窗（alert/confirm/prompt 一律页内实现）。
+import { Component, createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+
+// ---- toast：页内轻提示（自动消失） ----
+
+const ToastCtx = createContext(null);
+
+export function ToastProvider({ children }) {
+  const [msgs, setMsgs] = useState([]);
+  const idRef = useRef(0);
+
+  const toast = useCallback((msg) => {
+    const id = ++idRef.current;
+    setMsgs((m) => [...m, { id, msg }]);
+    setTimeout(() => setMsgs((m) => m.filter((x) => x.id !== id)), 2800);
+  }, []);
+
+  return (
+    <ToastCtx.Provider value={toast}>
+      {children}
+      <div className="toast-stack">
+        {msgs.map((m) => <div key={m.id} className="toast show">{m.msg}</div>)}
+      </div>
+    </ToastCtx.Provider>
+  );
+}
+
+export function useToast() {
+  return useContext(ToastCtx) || ((m) => console.log(m));
+}
+
+// 操作守卫：包一层，失败自动 toast 错误信息（对应 vanilla 版的 guard()）
+export function useGuard() {
+  const toast = useToast();
+  return useCallback(async (fn) => {
+    try { return await fn(); } catch (e) { toast(String((e && e.message) || e)); }
+  }, [toast]);
+}
+
+// ---- 点击即复制：所有路径/长标识的展示标准 ----
+// 点一下复制全文；hover 显示「点击复制」提示；复制成功 toast 确认。
+export function Copyable({ text, className = '', title, children }) {
+  const toast = useToast();
+  const copy = async () => {
+    const v = String(text ?? '');
+    try {
+      await navigator.clipboard.writeText(v);
+      toast('已复制: ' + (v.length > 60 ? v.slice(0, 57) + '...' : v));
+    } catch {
+      // 剪贴板 API 不可用（非安全上下文等）：退回 execCommand
+      try {
+        const ta = document.createElement('textarea');
+        ta.value = v;
+        ta.style.cssText = 'position:fixed;opacity:0';
+        document.body.appendChild(ta);
+        ta.select();
+        document.execCommand('copy');
+        ta.remove();
+        toast('已复制: ' + (v.length > 60 ? v.slice(0, 57) + '...' : v));
+      } catch {
+        toast('复制失败（剪贴板不可用）');
+      }
+    }
+  };
+  return (
+    <span
+      className={'copyable' + (className ? ' ' + className : '')}
+      title={title || '点击复制'}
+      onClick={copy}
+    >{children !== undefined ? children : text}</span>
+  );
+}
+
+// ---- 对话框：确认 / 输入（Promise 风格，对应 vanilla 版 dialog()） ----
+
+export function useDialog() {
+  const [state, setState] = useState(null); // {resolve, ...opts}
+  // 用 ref 读输入框，而不是 document.querySelector('.dlg-input')——
+  // 后者绕开 React 直接摸 DOM，页面上有第二个同名类名时就会读错。
+  const inputRef = useRef(null);
+
+  const close = useCallback((val) => {
+    setState((s) => { if (s && s.resolve) s.resolve(val); return null; });
+  }, []);
+
+  const dialog = useCallback((opts = {}) => new Promise((resolve) => {
+    setState({ ...opts, resolve });
+  }), []);
+
+  const node = state ? (
+    <div className="dlg" onMouseDown={(e) => { if (e.target === e.currentTarget) close(null); }}>
+      <div className="dlg-box">
+        {state.title ? <div className="dlg-title">{state.title}</div> : null}
+        {state.message ? <div className="dlg-msg">{state.message}</div> : null}
+        {state.input ? (
+          <input
+            ref={inputRef}
+            className="dlg-input"
+            autoFocus
+            spellCheck="false"
+            placeholder={state.placeholder || ''}
+            defaultValue={state.value || ''}
+            onKeyDown={(e) => {
+              if (e.key === 'Enter') close(e.currentTarget.value.trim());
+              if (e.key === 'Escape') close(null);
+            }}
+          />
+        ) : null}
+        <div className="dlg-acts">
+          <button className="btn ghost" onClick={() => close(null)}>取消</button>
+          <button
+            className={'btn' + (state.danger ? ' danger' : '')}
+            onClick={() => close(state.input ? (inputRef.current?.value.trim() ?? null) : true)}
+          >
+            {state.okText || '确定'}
+          </button>
+        </div>
+      </div>
+    </div>
+  ) : null;
+
+  return { dialog, node };
+}
+
+// ---- 错误边界：把崩溃限制在单个视图内 ----
+// 视图都是 lazy() 加载的，没有这层兜底时，任何一个视图抛错（或 chunk 加载失败）
+// 都会让整个面板白屏，用户连切到别的 tab 自救都做不到。
+
+export class ErrorBoundary extends Component {
+  constructor(props) {
+    super(props);
+    this.state = { error: null };
+  }
+
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+
+  componentDidCatch(error, info) {
+    console.error('[nx-kv] 视图渲染失败:', error, info);
+  }
+
+  render() {
+    if (!this.state.error) return this.props.children;
+    return (
+      <div className="card" style={{ padding: 16 }}>
+        <div className="colhead"><h3>这个面板出错了</h3></div>
+        <div className="dlg-msg">{String(this.state.error?.message || this.state.error)}</div>
+        <div className="muted" style={{ marginBottom: 10 }}>
+          其他面板不受影响，可以切到别的 tab 继续操作；控制台有完整堆栈。
+        </div>
+        <button className="btn" onClick={() => this.setState({ error: null })}>重试</button>
+      </div>
+    );
+  }
+}
+
+// ---- 弹窗：大块内容（diff / 冲突详情 / 命令输出） ----
+
+export function Modal({ title, onClose, children }) {
+  useEffect(() => {
+    const onKey = (e) => { if (e.key === 'Escape') onClose(); };
+    document.addEventListener('keydown', onKey);
+    return () => document.removeEventListener('keydown', onKey);
+  }, [onClose]);
+
+  return (
+    <div className="modal" onMouseDown={(e) => { if (e.target === e.currentTarget) onClose(); }}>
+      <div className="modal-box">
+        <div className="modal-title">
+          <span>{title}</span>
+          <button className="btn small ghost" onClick={onClose}>关闭</button>
+        </div>
+        <div className="modal-body">{children}</div>
+      </div>
+    </div>
+  );
+}
+
+// ---- diff 文本渲染（+/- 行着色） ----
+
+export function DiffPre({ text }) {
+  const lines = String(text ?? '').split('\n');
+  return (
+    <pre>
+      {lines.map((line, i) => (
+        <span key={i} className={
+          line.startsWith('+') && !line.startsWith('+++') ? 'd-add'
+            : line.startsWith('-') && !line.startsWith('---') ? 'd-del' : ''
+        }>
+          {line}{i < lines.length - 1 ? '\n' : ''}
+        </span>
+      ))}
+    </pre>
+  );
+}

package/src/web/frontend/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>nx-kv · nx-kv</title>
+<link rel="stylesheet" href="/style.css">
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="/main.jsx"></script>
+</body>
+</html>

package/src/web/frontend/main.jsx

@@ -0,0 +1,17 @@
+// 面板入口：Provider 组装（store → toast → dialog → App）。
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import App from './App.jsx';
+import { StoreProvider } from './store.jsx';
+import { ToastProvider } from './components/ui.jsx';
+import './style.css';
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <StoreProvider>
+      <ToastProvider>
+        <App />
+      </ToastProvider>
+    </StoreProvider>
+  </StrictMode>
+);

package/src/web/frontend/registry.js

@@ -0,0 +1,12 @@
+// 视图注册表：新增面板 = 在模块里写 view.jsx + 在这里登记一行。
+// App 的 tab 导航、hash 路由、懒加载全部由这张表驱动，改面板不用动壳。
+//
+// 与后端 src/runtime/registry.js 的模块表一一对应；tests/unit/registry.test.mjs
+// 会断言两侧对齐——漏登记（或登记了不存在的视图）都会直接测试失败。
+import { lazy } from 'react';
+
+export const VIEWS = [
+  { id: 'todo', title: '清单', component: lazy(() => import('../../modules/todo/view.jsx')) },
+  { id: 'group', title: '工作空间', component: lazy(() => import('../../modules/group/view.jsx')) },
+  { id: 'auth', title: '登录', component: lazy(() => import('../../modules/auth/view.jsx')) },
+];