pneuma-skills 1.4.1 → 1.6.2

package/README.md

@@ -12,7 +12,7 @@ ModeManifest(skill + viewer + agent_config) × AgentBackend × RuntimeShell
 
 ## Demo
 
-Ships with **Doc Mode** (markdown editing) and **Slide Mode** (presentation editing). Here's Doc Mode — Claude Code edits `.md` files and you see the rendered result in real-time:
+Ships with **Doc Mode** (markdown editing), **Slide Mode** (presentation editing), and **Draw Mode** (Excalidraw whiteboard). Here's Doc Mode — Claude Code edits `.md` files and you see the rendered result in real-time:
 
 ```
 ┌─────────────────────────────┬──────────────────────────┐
@@ -69,8 +69,12 @@ This will:
 pneuma-skills <mode> [options]
 
 Modes:
-  doc    Markdown document editing mode
-  slide  Presentation editing mode (HTML slides with iframe preview)
+  doc                          Markdown document editing mode
+  slide                        Presentation editing mode (HTML slides with iframe preview)
+  draw                         Excalidraw whiteboard drawing mode
+  /path/to/mode                Load mode from a local directory
+  github:user/repo             Load mode from a GitHub repository
+  github:user/repo#branch      Load mode from a specific branch/tag
 
 Options:
   --workspace <path>   Target workspace directory (default: current directory)
@@ -78,6 +82,29 @@ Options:
   --no-open            Don't auto-open the browser
 ```
 
+### Remote / External Modes
+
+Pneuma supports loading modes from outside the built-in `modes/` directory:
+
+```bash
+# Load from a local directory (must contain manifest.ts and pneuma-mode.ts)
+bunx pneuma-skills /path/to/my-custom-mode --workspace ~/project
+
+# Load from a GitHub repository
+bunx pneuma-skills github:pandazki/pneuma-mode-canvas --workspace ~/project
+
+# Load from a specific branch or tag
+bunx pneuma-skills github:pandazki/pneuma-mode-canvas#develop --workspace ~/project
+```
+
+GitHub repositories are cloned to `~/.pneuma/modes/` and cached locally. Subsequent runs will fetch the latest changes.
+
+A mode package must contain:
+- `manifest.ts` — default export of `ModeManifest`
+- `pneuma-mode.ts` — default export of `ModeDefinition`
+- `viewer/` — React preview components
+- `skill/` — Skill files (optional)
+
 ## Architecture
 
 Pneuma is organized in four layers, each with a clear contract boundary:
@@ -90,7 +117,7 @@ Pneuma is organized in four layers, each with a clear contract boundary:
 ├─────────────────────────────────────────────────────────┤
 │  Layer 3: Content Viewer                                │
 │  ViewerContract — "how to render, select, update"       │
-│  modes/doc/components/DocPreview.tsx                     │
+│  modes/doc/viewer/DocPreview.tsx                         │
 ├─────────────────────────────────────────────────────────┤
 │  Layer 2: Agent Bridge                                  │
 │  AgentBackend — "how to launch, communicate, lifecycle" │
@@ -112,11 +139,11 @@ When Claude Code edits files, chokidar detects the changes and pushes updated co
 
 | Contract | Responsibility | Extend to... |
 |----------|---------------|-------------|
-| **ModeManifest** | Declares skill, viewer config, agent preferences, init seeds | Add new modes (slide, mindmap, canvas) |
+| **ModeManifest** | Declares skill, viewer config, agent preferences, init seeds | Add new modes (mindmap, canvas, etc.) |
 | **ViewerContract** | Preview component, context extraction, update strategy | Custom renderers (iframe, D3, Monaco) |
 | **AgentBackend** | Launch, resume, kill, capability declaration | Other agents (Codex, Aider) |
 
-Contracts are defined in `core/types/` with 42 tests in `core/__tests__/`.
+Contracts are defined in `core/types/` with 81 tests in `core/__tests__/`.
 
 ## Project Structure
 
@@ -130,19 +157,25 @@ pneuma-skills/
 │   │   ├── agent-backend.ts   #   AgentBackend, AgentCapabilities
 │   │   ├── mode-definition.ts #   ModeDefinition (manifest + viewer)
 │   │   └── index.ts           #   Re-exports
-│   ├── mode-loader.ts         # Dynamic mode discovery and loading
-│   └── __tests__/             # 42 contract tests
+│   ├── mode-loader.ts         # Dynamic mode discovery and loading (builtin + external)
+│   ├── mode-resolver.ts       # Mode source resolution (builtin/local/github)
+│   └── __tests__/             # 81 tests
 ├── modes/
 │   ├── doc/
 │   │   ├── pneuma-mode.ts     # Doc Mode definition (manifest + viewer)
 │   │   ├── skill/SKILL.md     # Skill prompt for Claude Code
-│   │   └── components/
+│   │   └── viewer/
 │   │       └── DocPreview.tsx  # Markdown preview with select/edit modes
-│   └── slide/
-│       ├── pneuma-mode.ts     # Slide Mode definition (manifest + viewer)
-│       ├── skill/             # Skill package (SKILL.md + design docs + scripts)
-│       └── components/
-│           └── SlidePreview.tsx # Slide carousel with iframe preview
+│   ├── slide/
+│   │   ├── pneuma-mode.ts     # Slide Mode definition (manifest + viewer)
+│   │   ├── skill/             # Skill package (SKILL.md + design docs + scripts)
+│   │   └── viewer/
+│   │       └── SlidePreview.tsx # Slide carousel with iframe preview
+│   └── draw/
+│       ├── pneuma-mode.ts     # Draw Mode definition (manifest + viewer)
+│       ├── skill/SKILL.md     # Skill prompt for Claude Code
+│       └── viewer/
+│           └── DrawPreview.tsx # Excalidraw editor
 ├── backends/
 │   └── claude-code/
 │       ├── index.ts           # ClaudeCodeBackend implements AgentBackend
@@ -167,6 +200,10 @@ pneuma-skills/
 │       ├── ToolBlock.tsx      # Expandable tool call cards
 │       ├── PermissionBanner.tsx # Tool permission approval UI
 │       └── TopBar.tsx         # Tabs (Chat/Context/Terminal) + status
+├── snapshot/                  # Snapshot push/pull via Cloudflare R2
+│   ├── push.ts                # Pack and upload workspace
+│   ├── pull.ts                # Download and extract workspace
+│   └── r2.ts                  # R2 storage client
 └── docs/
     ├── adr/                         # Architecture Decision Records (1-11)
     ├── design/                      # Active design documents
@@ -185,6 +222,7 @@ pneuma-skills/
 | Markdown | [react-markdown](https://github.com/remarkjs/react-markdown) + remark-gfm |
 | Terminal | [xterm.js](https://xtermjs.org) + Bun native PTY |
 | File Watching | [chokidar](https://github.com/paulmillr/chokidar) 4 |
+| Drawing | [Excalidraw](https://excalidraw.com) 0.18 |
 | Agent | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) via `--sdk-url` |
 
 ## Features
@@ -205,11 +243,12 @@ pneuma-skills/
 
 - [x] Doc Mode — Markdown WYSIWYG editing
 - [x] Slide Mode — Presentation editing with iframe preview, drag-reorder, AI image generation
+- [x] Draw Mode — Excalidraw whiteboard with `.excalidraw` file editing
 - [x] Element selection & inline editing
 - [x] Session persistence & resume
 - [x] Terminal, tasks, context panel
 - [x] v1.0 contract architecture (ModeManifest, ViewerContract, AgentBackend)
-- [ ] Remote mode loading — `pneuma --mode github:user/repo` (v1.x)
+- [x] Remote mode loading — `pneuma github:user/repo` or local path (v1.x)
 - [ ] Additional agent backends — Codex CLI, custom agents (v1.x)
 
 ## Acknowledgements

package/bin/pneuma.ts

@@ -15,9 +15,11 @@ import { startServer } from "../server/index.js";
 import { ClaudeCodeBackend } from "../backends/claude-code/index.js";
 import { installSkill } from "../server/skill-installer.js";
 import { startFileWatcher } from "../server/file-watcher.js";
-import { loadModeManifest, listModes } from "../core/mode-loader.js";
+import { loadModeManifest, listBuiltinModes, registerExternalMode } from "../core/mode-loader.js";
 import type { ModeManifest } from "../core/types/mode-manifest.js";
 import { applyTemplateParams } from "../server/skill-installer.js";
+import { resolveMode as resolveModeSource, isExternalMode } from "../core/mode-resolver.js";
+import type { ResolvedMode } from "../core/mode-resolver.js";
 
 const PROJECT_ROOT = resolve(dirname(import.meta.path), "..");
 
@@ -179,20 +181,40 @@ async function main() {
 
   const { mode, workspace, port, noOpen } = parseArgs(process.argv);
 
-  // Validate mode
-  const availableModes = listModes();
-  if (!mode || !availableModes.includes(mode)) {
-    const modeList = availableModes.join(" | ");
-    console.log(`Usage: pneuma <${modeList}> --workspace /path/to/project [--port 17996] [--no-open]`);
+  // Validate mode — support builtin names, local paths, and github: specifiers
+  if (!mode) {
+    const modeList = listBuiltinModes().join("|");
+    console.log(
+      `Usage: pneuma <${modeList}|/path/to/mode|github:user/repo> [--workspace <path>] [--port <number>] [--no-open]`,
+    );
+    process.exit(1);
+  }
+
+  // Resolve mode source (builtin, local path, or github clone)
+  let resolved: ResolvedMode;
+  try {
+    resolved = await resolveModeSource(mode, PROJECT_ROOT);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[pneuma] Failed to resolve mode "${mode}": ${msg}`);
     process.exit(1);
   }
 
+  // For external modes, register them in the mode-loader before loading
+  if (resolved.type !== "builtin") {
+    registerExternalMode(resolved.name, resolved.path);
+    console.log(`[pneuma] External mode "${resolved.name}" loaded from ${resolved.path}`);
+  }
+
   // Load mode manifest (no React deps — backend safe)
+  // Use resolved.name for lookup since external modes are registered under that name
+  const modeName = resolved.name;
   let manifest: ModeManifest;
   try {
-    manifest = await loadModeManifest(mode);
+    manifest = await loadModeManifest(modeName);
   } catch (err) {
-    console.error(`[pneuma] Failed to load mode "${mode}":`, err);
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[pneuma] Failed to load mode "${modeName}": ${msg}`);
     process.exit(1);
   }
 
@@ -206,7 +228,7 @@ async function main() {
     console.log(`[pneuma] Created workspace: ${workspace}`);
   }
 
-  console.log(`[pneuma] Mode: ${manifest.displayName} (${mode})`);
+  console.log(`[pneuma] Mode: ${manifest.displayName} (${modeName})`);
   console.log(`[pneuma] Workspace: ${workspace}`);
 
   // 0.5 Resolve init params (interactive on first run, then cached)
@@ -228,7 +250,8 @@ async function main() {
   }
 
   // 1. Install skill + inject CLAUDE.md (driven by manifest)
-  const modeSourceDir = resolve(PROJECT_ROOT, "modes", mode);
+  // Use resolved path for external modes, PROJECT_ROOT/modes/{name} for builtin
+  const modeSourceDir = resolved.path;
   const skillTarget = join(workspace, ".claude", "skills", manifest.skill.installName);
   let skipSkillInstall = false;
 
@@ -263,8 +286,11 @@ async function main() {
 
     if (!hasContent && manifest.init.seedFiles) {
       const hasParams = Object.keys(resolvedParams).length > 0;
+      // For builtin modes, seed paths are relative to PROJECT_ROOT
+      // For external modes, seed paths are relative to the mode package directory
+      const seedBase = resolved.type === "builtin" ? PROJECT_ROOT : resolved.path;
       for (const [src, dst] of Object.entries(manifest.init.seedFiles)) {
-        const srcPath = join(PROJECT_ROOT, src);
+        const srcPath = join(seedBase, src);
         if (existsSync(srcPath)) {
           const dstPath = join(workspace, dst);
           mkdirSync(dirname(dstPath), { recursive: true });
@@ -302,6 +328,10 @@ async function main() {
     watchPatterns: manifest.viewer.watchPatterns,
     ...(isDev ? {} : { distDir }),
     ...(Object.keys(resolvedParams).length > 0 ? { initParams: resolvedParams } : {}),
+    // Pass external mode info for the /api/mode-info endpoint
+    ...(resolved.type !== "builtin"
+      ? { externalMode: { name: resolved.name, path: resolved.path, type: resolved.type } }
+      : {}),
   });
 
   // 4. Launch Agent backend (driven by manifest)
@@ -343,7 +373,7 @@ async function main() {
   saveSession(workspace, {
     sessionId: session.sessionId,
     agentSessionId: existing?.agentSessionId,
-    mode,
+    mode: modeName,
     createdAt: existing?.createdAt || Date.now(),
   });
 
@@ -413,12 +443,23 @@ async function main() {
     // Dev mode: start Vite dev server
     const VITE_PORT = 17996;
     console.log(`[pneuma] Starting Vite dev server on port ${VITE_PORT}...`);
+
+    // Pass external mode path to Vite via env var (for server.fs.allow)
+    const viteEnv: Record<string, string> = {
+      ...process.env as Record<string, string>,
+    };
+    if (resolved.type !== "builtin") {
+      viteEnv.PNEUMA_EXTERNAL_MODE_PATH = resolved.path;
+      viteEnv.PNEUMA_EXTERNAL_MODE_NAME = resolved.name;
+    }
+
     viteProc = Bun.spawn(
       ["bunx", "vite", "--port", String(VITE_PORT), "--strictPort"],
       {
         cwd: PROJECT_ROOT,
         stdout: "pipe",
         stderr: "pipe",
+        env: viteEnv,
       }
     );
 
@@ -443,7 +484,7 @@ async function main() {
 
   // 7. Open browser (include mode in URL for frontend)
   if (!noOpen) {
-    const url = `http://localhost:${browserPort}?session=${session.sessionId}&mode=${mode}`;
+    const url = `http://localhost:${browserPort}?session=${session.sessionId}&mode=${modeName}`;
     console.log(`[pneuma] Opening browser: ${url}`);
     try {
       const opener = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";

package/core/__tests__/fixtures/test-mode/manifest.ts

@@ -0,0 +1,20 @@
+/**
+ * Test mode manifest — used by mode-resolver integration tests.
+ */
+const testManifest = {
+  name: "test-mode",
+  version: "0.1.0",
+  displayName: "Test Mode",
+  description: "A minimal mode for testing",
+  skill: {
+    sourceDir: "skill",
+    installName: "pneuma-test",
+    claudeMdSection: "## Test Mode",
+  },
+  viewer: {
+    watchPatterns: ["**/*.txt"],
+    ignorePatterns: ["node_modules/**"],
+  },
+};
+
+export default testManifest;

package/core/__tests__/mode-loader-external.test.ts

@@ -0,0 +1,36 @@
+/**
+ * Mode Loader — External mode registration tests
+ *
+ * 验证 registerExternalMode 和 loadModeManifest 对外部 mode 的支持。
+ */
+
+import { describe, test, expect } from "bun:test";
+import { resolve, dirname } from "node:path";
+import { registerExternalMode, loadModeManifest, listModes, listBuiltinModes } from "../mode-loader.js";
+
+const TEST_MODE_PATH = resolve(dirname(import.meta.path), "fixtures/test-mode");
+
+describe("registerExternalMode", () => {
+  test("registered external mode appears in listModes()", () => {
+    registerExternalMode("test-mode", TEST_MODE_PATH);
+    const modes = listModes();
+    expect(modes).toContain("test-mode");
+    expect(modes).toContain("doc");
+    expect(modes).toContain("slide");
+  });
+
+  test("listBuiltinModes() does not include external modes", () => {
+    const builtins = listBuiltinModes();
+    expect(builtins).toContain("doc");
+    expect(builtins).toContain("slide");
+    expect(builtins).not.toContain("test-mode");
+  });
+
+  test("loadModeManifest() works for registered external mode", async () => {
+    registerExternalMode("test-mode", TEST_MODE_PATH);
+    const manifest = await loadModeManifest("test-mode");
+    expect(manifest.name).toBe("test-mode");
+    expect(manifest.version).toBe("0.1.0");
+    expect(manifest.displayName).toBe("Test Mode");
+  });
+});

package/core/__tests__/mode-resolver.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Mode Resolver 测试
+ *
+ * 验证 mode 来源解析:
+ * - builtin mode 名称识别
+ * - local path 解析 (绝对路径、相对路径、~ 展开)
+ * - github 格式解析
+ * - 错误处理
+ */
+
+import { describe, test, expect } from "bun:test";
+import { parseModeSpecifier, isExternalMode, resolveMode } from "../mode-resolver.js";
+import { homedir } from "node:os";
+import { resolve, dirname, join } from "node:path";
+
+describe("parseModeSpecifier", () => {
+  // ── Builtin modes ──────────────────────────────────────────────────
+
+  test("recognizes builtin mode: doc", () => {
+    const result = parseModeSpecifier("doc");
+    expect(result.type).toBe("builtin");
+    expect(result.name).toBe("doc");
+  });
+
+  test("recognizes builtin mode: slide", () => {
+    const result = parseModeSpecifier("slide");
+    expect(result.type).toBe("builtin");
+    expect(result.name).toBe("slide");
+  });
+
+  test("unknown plain name falls back to builtin (let mode-loader handle it)", () => {
+    const result = parseModeSpecifier("mindmap");
+    expect(result.type).toBe("builtin");
+    expect(result.name).toBe("mindmap");
+  });
+
+  // ── Local paths ────────────────────────────────────────────────────
+
+  test("parses absolute path as local mode", () => {
+    const result = parseModeSpecifier("/home/user/my-mode");
+    expect(result.type).toBe("local");
+    expect(result.name).toBe("my-mode");
+    expect(result.localPath).toBe("/home/user/my-mode");
+  });
+
+  test("parses relative path with ./ as local mode", () => {
+    const result = parseModeSpecifier("./modes/custom");
+    expect(result.type).toBe("local");
+    expect(result.name).toBe("custom");
+    expect(result.localPath).toBeTruthy();
+  });
+
+  test("parses relative path with ../ as local mode", () => {
+    const result = parseModeSpecifier("../other-project/my-mode");
+    expect(result.type).toBe("local");
+    expect(result.name).toBe("my-mode");
+    expect(result.localPath).toBeTruthy();
+  });
+
+  test("expands ~ to home directory", () => {
+    const result = parseModeSpecifier("~/my-modes/custom");
+    expect(result.type).toBe("local");
+    expect(result.name).toBe("custom");
+    expect(result.localPath).toStartWith(homedir());
+  });
+
+  // ── GitHub specifiers ──────────────────────────────────────────────
+
+  test("parses github:user/repo", () => {
+    const result = parseModeSpecifier("github:pandazki/pneuma-mode-canvas");
+    expect(result.type).toBe("github");
+    expect(result.name).toBe("pandazki-pneuma-mode-canvas");
+    expect(result.github).toEqual({
+      user: "pandazki",
+      repo: "pneuma-mode-canvas",
+      ref: "main",
+    });
+  });
+
+  test("parses github:user/repo#branch", () => {
+    const result = parseModeSpecifier("github:pandazki/my-mode#develop");
+    expect(result.type).toBe("github");
+    expect(result.name).toBe("pandazki-my-mode");
+    expect(result.github).toEqual({
+      user: "pandazki",
+      repo: "my-mode",
+      ref: "develop",
+    });
+  });
+
+  test("parses github:user/repo#tag", () => {
+    const result = parseModeSpecifier("github:user/repo#v1.0.0");
+    expect(result.type).toBe("github");
+    expect(result.github?.ref).toBe("v1.0.0");
+  });
+
+  test("throws for invalid github specifier (no repo)", () => {
+    expect(() => parseModeSpecifier("github:user")).toThrow("Invalid GitHub mode specifier");
+  });
+
+  test("throws for invalid github specifier (empty user)", () => {
+    expect(() => parseModeSpecifier("github:/repo")).toThrow("Invalid GitHub mode specifier");
+  });
+});
+
+// ── resolveMode integration tests ─────────────────────────────────────
+
+const PROJECT_ROOT = resolve(dirname(import.meta.path), "../..");
+
+describe("resolveMode", () => {
+  test("resolves builtin mode to modes/ directory", async () => {
+    const result = await resolveMode("doc", PROJECT_ROOT);
+    expect(result.type).toBe("builtin");
+    expect(result.name).toBe("doc");
+    expect(result.path).toBe(join(PROJECT_ROOT, "modes", "doc"));
+  });
+
+  test("resolves local path to absolute directory", async () => {
+    const testModePath = resolve(dirname(import.meta.path), "fixtures/test-mode");
+    const result = await resolveMode(testModePath, PROJECT_ROOT);
+    expect(result.type).toBe("local");
+    expect(result.name).toBe("test-mode");
+    expect(result.path).toBe(testModePath);
+  });
+
+  test("throws for non-existent local path", async () => {
+    await expect(resolveMode("/nonexistent/path/to/mode", PROJECT_ROOT)).rejects.toThrow(
+      "Local mode directory not found",
+    );
+  });
+
+  test("throws for local path without manifest", async () => {
+    // Use a directory that exists but has no manifest.ts
+    const tmpDir = resolve(dirname(import.meta.path), "fixtures");
+    await expect(resolveMode(tmpDir, PROJECT_ROOT)).rejects.toThrow(
+      "missing manifest.ts",
+    );
+  });
+});
+
+describe("isExternalMode", () => {
+  test("builtin modes are not external", () => {
+    expect(isExternalMode("doc")).toBe(false);
+    expect(isExternalMode("slide")).toBe(false);
+  });
+
+  test("local paths are external", () => {
+    expect(isExternalMode("/path/to/mode")).toBe(true);
+    expect(isExternalMode("./my-mode")).toBe(true);
+  });
+
+  test("github specifiers are external", () => {
+    expect(isExternalMode("github:user/repo")).toBe(true);
+  });
+});

package/core/mode-loader.ts

@@ -1,8 +1,10 @@
 /**
  * Mode Loader — 解析、安装、加载 Mode。
  *
- * v1.0: 只支持 builtin mode，通过动态 import 加载。
- * v1.x: 支持 local path 和 remote URL。
+ * 支持三种来源:
+ * - builtin: 内置 mode，从 modes/ 目录动态 import
+ * - local: 本地文件系统路径
+ * - github: GitHub 仓库 (通过 mode-resolver 克隆到本地缓存)
  *
  * 核心流程: resolveMode → ensureInstalled → loadFromSource
  */
@@ -13,15 +15,21 @@ import type { ModeDefinition } from "./types/mode-definition.js";
 /**
  * Mode 来源类型:
  * - "builtin" — 内置 mode，从 modes/ 目录动态 import
+ * - "external" — 外部 mode，从绝对路径动态 import (local path 或 github clone)
  */
-type ModeSource = {
-  type: "builtin";
-  manifestLoader: () => Promise<ModeManifest>;
-  definitionLoader: () => Promise<ModeDefinition>;
-};
-// v1.x:
-// | { type: "local"; path: string }
-// | { type: "remote"; url: string }
+type ModeSource =
+  | {
+      type: "builtin";
+      manifestLoader: () => Promise<ModeManifest>;
+      definitionLoader: () => Promise<ModeDefinition>;
+    }
+  | {
+      type: "external";
+      name: string;
+      path: string;
+      manifestLoader: () => Promise<ModeManifest>;
+      definitionLoader: () => Promise<ModeDefinition>;
+    };
 
 /** 内置 mode 注册表 — 全部使用动态 import */
 const builtinModes: Record<string, ModeSource> = {
@@ -39,8 +47,18 @@ const builtinModes: Record<string, ModeSource> = {
     definitionLoader: () =>
       import("../modes/slide/pneuma-mode.js").then((m) => m.default),
   },
+  draw: {
+    type: "builtin",
+    manifestLoader: () =>
+      import("../modes/draw/manifest.js").then((m) => m.default),
+    definitionLoader: () =>
+      import("../modes/draw/pneuma-mode.js").then((m) => m.default),
+  },
 };
 
+/** 外部 mode 注册表 — 由 CLI 在启动时通过 registerExternalMode 注册 */
+const externalModes: Record<string, ModeSource> = {};
+
 // ── Public API ───────────────────────────────────────────────────────────────
 
 /**
@@ -64,35 +82,84 @@ export async function loadModeManifest(name: string): Promise<ModeManifest> {
 }
 
 /**
- * 列出所有已注册的 mode 名称。
+ * 列出所有已注册的 mode 名称 (包括 builtin 和已注册的 external)。
  */
 export function listModes(): string[] {
+  return [...Object.keys(builtinModes), ...Object.keys(externalModes)];
+}
+
+/**
+ * 列出内置 mode 名称。
+ */
+export function listBuiltinModes(): string[] {
   return Object.keys(builtinModes);
 }
 
+/**
+ * 注册外部 mode (由 CLI 在启动时调用)。
+ *
+ * Backend context (Bun): 直接用 import() 加载绝对路径。
+ * Frontend context (browser/Vite): 用 /@fs/ URL 加载。
+ *
+ * @param name — Mode 名称 (用于注册和查找)
+ * @param absPath — Mode 包的绝对路径
+ */
+export function registerExternalMode(name: string, absPath: string): void {
+  const isBrowser = typeof window !== "undefined";
+
+  if (isBrowser) {
+    // Frontend: use Vite's /@fs/ URL scheme for dev mode
+    externalModes[name] = {
+      type: "external",
+      name,
+      path: absPath,
+      manifestLoader: () =>
+        import(/* @vite-ignore */ `/@fs${absPath}/manifest.ts`).then(
+          (m) => m.default,
+        ),
+      definitionLoader: () =>
+        import(/* @vite-ignore */ `/@fs${absPath}/pneuma-mode.ts`).then(
+          (m) => m.default,
+        ),
+    };
+  } else {
+    // Backend (Bun): use direct absolute path import
+    externalModes[name] = {
+      type: "external",
+      name,
+      path: absPath,
+      manifestLoader: () =>
+        import(/* @vite-ignore */ absPath + "/manifest.ts").then((m) => m.default),
+      definitionLoader: () =>
+        import(/* @vite-ignore */ absPath + "/pneuma-mode.ts").then((m) => m.default),
+    };
+  }
+}
+
 // ── Internal ─────────────────────────────────────────────────────────────────
 
-/** 解析 mode 来源 (v1.0: 只查 builtin 注册表) */
+/** 解析 mode 来源 (查 builtin 和 external 注册表) */
 function resolveMode(name: string): ModeSource {
-  const source = builtinModes[name];
-  if (!source) {
-    const available = Object.keys(builtinModes).join(", ");
-    throw new Error(`Unknown mode: "${name}". Available: ${available}`);
-  }
-  return source;
+  // Check external modes first (allows overriding builtin names)
+  const external = externalModes[name];
+  if (external) return external;
+
+  const builtin = builtinModes[name];
+  if (builtin) return builtin;
+
+  const available = listModes();
+  throw new Error(
+    `Unknown mode: "${name}". Available: ${available.join(", ")}`,
+  );
 }
 
-/** 确保 mode 已安装 (v1.0: builtin 直接跳过) */
+/** 确保 mode 已安装 (builtin 直接跳过，external 已由 mode-resolver 处理) */
 async function ensureInstalled(_source: ModeSource): Promise<void> {
-  if (_source.type === "builtin") return;
-  // v1.x: 检查 .pneuma/modes/{name}/ 是否存在
-  //        不存在 → 从 source.url 拉取/安装
-  //        非信任来源 → 用户确认
+  // Both builtin and external modes are already resolved to local paths
+  return;
 }
 
 /** 从已安装的 source 加载完整 ModeDefinition */
 async function loadDefinition(source: ModeSource): Promise<ModeDefinition> {
-  if (source.type === "builtin") return source.definitionLoader();
-  // v1.x: dynamic import from .pneuma/modes/{name}/pneuma-mode.js
-  throw new Error("Non-builtin mode loading not yet implemented");
+  return source.definitionLoader();
 }