pm-canvas-viewer 0.1.0 → 0.7.0

package/README.md

@@ -1,8 +1,8 @@
 # pm-canvas-viewer
 
-本地画板查看器 + 文档编辑工具。一键启动，浏览器操作。
+本地 **HTML 原型 + 配套文档** 查看编辑器。一键启动，浏览器操作。
 
-配合 [pm-canvas skill](../skill/) 使用：Agent 生成画板文件，人用 viewer 预览画板并编辑关联文档。
+打开任意"含 HTML 文件 + 可选 docs/ 文档"的目录，左侧选项 / 切页，中间预览，右侧 Markdown / Excalidraw / draw.io 三种文档编辑器。完整兼容 [pm-canvas skill](../skill/) 生成的画板（含锚点系统）。
 
 ## 安装
 
@@ -14,70 +14,156 @@ npm i -g pm-canvas-viewer
 
 ## 使用
 
+打开一个**文件夹**（viewer 不接受单文件路径——它的定位是"HTML + 配套文档"组合）：
+
 ```bash
-canvas open ./我的画板/
+canvas open ./我的原型/
+canvas open                # 等价于 canvas open .
+canvas                     # 从历史记录里检索
+canvas list                # 查看运行中的实例
+canvas stop                # 停止实例
 ```
 
-浏览器自动打开，左侧画板预览，右侧文档编辑面板。
+浏览器自动打开。viewer 会扫目录识别"展示项"，然后按情况渲染界面。
+
+### viewer 识别哪些目录
+
+每个目录独立判断：
+
+| 类型 | 判定 | viewer 内表现 |
+|---|---|---|
+| **画板项** | 含 `canvas.json` 且 `rows[]` 是数组 | 完整画板能力 + 锚点系统 |
+| **html 项** | 直接含 ≥1 个 `.html` 且无 canvas.json | 普通预览 + iframe 跳转拦截 |
+| **容器目录** | 自身非项，子孙含项 | 在左栏作为分组节点展开 |
+| 其他 | 无 html 无 canvas.json | 完全忽略 |
 
-### 画板目录结构
+过滤名单：`node_modules` / `.git` / `dist` / `docs` / `.DS_Store` / `assets`。深度上限 8 层。
+
+### 界面布局
 
 ```
-我的画板/
-├── index.html          ← 画板 shell（Agent 生成）
-├── canvas.json         ← 画板元数据（Agent 生成）
-├── rows/               ← 画板行文件（Agent 生成）
-│   ├── 01-home.html
-│   └── 02-profile.html
-└── docs/               ← 关联文档（人维护，viewer 读写）
-    ├── 需求规格.md
-    └── 业务流程.excalidraw
+┌────────────┬──────────────────┬────────────┐
+│ 左栏       │ 中间画框          │ 右栏       │
+│            │ （iframe）        │            │
+│ 项列表 ▾   │                  │ 文档面板   │
+│ ────────  │                  │ + 编辑器   │
+│ 页列表     │                  │            │
+└────────────┴──────────────────┴────────────┘
 ```
 
-### 命令参数
+- **左栏自适应显隐**：项数 ≥2 显示项列表（树状）；当前 html 项 ≥2 页时显示页列表；两者都无显示时左栏整体隐藏（沉浸预览）
+- **页序**：`index.html > home.html > A-Z`，支持拖动调整并按项记忆
+- **html 项的跳转策略**：同源同项放行 + 同步页列表选中态；外链或跨项拦截 + toast 提示
+
+### 几种典型场景
 
 ```bash
-canvas open [目录] [选项]
+# 1. 标准画板（向后兼容，体验和老版本完全一致）
+canvas open ./画板目录/
+
+# 2. 多版本画板管理
+canvas open ./我的产品/
+# ↑ 目录里有 v1/canvas.json、v2/canvas.json，左栏显示项树
 
-# 选项
--p, --port <端口>    指定端口（默认 4800）
--V, --version        查看版本
--h, --help           查看帮助
+# 3. 多页 HTML 原型
+canvas open ./用户中心原型/
+# ↑ 目录直接含 home.html / profile.html / settings.html，左下显示页列表
+
+# 4. 混合（画板 + 普通 HTML 共存）
+canvas open ./prototypes/
+# ↑ 含画板子目录 + 散户 html 目录，左栏按物理目录树状展开
 ```
 
 ## 功能
 
-### 画板预览（左侧）
-- iframe 加载画板 index.html，所有 row 平铺展示
+### 中间画框
+
+- **画板项**：保留 pm-canvas shell 的无限画布、缩放、平移；可挂载锚点
+- **html 项**：iframe 加载选中页，`sandbox="allow-scripts allow-same-origin"`，onload 注入跳转拦截脚本（同源放行 + URL 变化同步左下页列表；外链拦截 toast）
 
-### 文档面板（右侧，可收起）
+### 右栏：文档面板
+
+支持三种文档（都按"当前选中项的 `docs/`"动态绑定）：
 
 **Markdown 编辑器**
-- Tiptap 3 所见即所得编辑器（WYSIWYG，`@tiptap/markdown` 读写 MD）
-- 工具栏：标题、加粗、斜体、列表、代码、表格可视化编辑
-- `⌘B` 加粗、`⌘I` 斜体
-- `⌘S` 保存到本地文件
+- Tiptap 3 WYSIWYG，工具栏：标题、加粗、斜体、列表、代码、表格
+- `⌘B` 加粗、`⌘I` 斜体、`⌘S` 保存
 
 **Excalidraw 编辑器**
-- 完整 Excalidraw 编辑器（画流程图、架构图等）
-- `⌘S` 保存为 .excalidraw 文件
+- 完整 Excalidraw（流程图、架构图等）
+- `⌘S` 保存为 .excalidraw
+
+**draw.io 编辑器**
+- 集成 diagrams.net iframe，`⌘S` 保存为 .drawio
 
 **文件管理**
-- 标签页切换不同文档
-- `+` 按钮新建 Markdown 或 Excalidraw 文件
-- 文件保存在画板目录的 `docs/` 下
+- 标签页切换、拖动排序（按项独立记忆）
+- 空状态点 + 新建文件，触发 `docs/` 按需创建（不会无 docs 文件就生成空 `docs/` 目录）
+
+### 锚点系统（仅画板项）
+
+- 双击画板创建锚点 pin（自定义颜色 + 标签）
+- 锚点可关联到文档文件、或文档内的标题（marker）
+- pin ↔ Tiptap chip 双向跳转
+- 数据存 `docs/anchors.json`，按项隔离
+- 切到 html 项时**彻底卸载**（无 iframe DOM 监听残留）
+
+### 文案就地编辑（v0.5+）
+
+无需翻代码即可改原型/画板里的可见文字，写回源 HTML/JS 文件。
+
+**5 类可编辑范围**：
+
+| 类别 | 例 | 引入 |
+|------|---|------|
+| HTML 静态文本 | `<p>文字</p>` 里的"文字" | v1.0 |
+| HTML mixed content | `<div>市值<b>14.5万</b>仓位</div>` 里的"市值"或"仓位"（每段独立可改） | v1.5 |
+| HTML 属性白名单 | `<input placeholder=>`、`<img alt=>`、`title` / `aria-label` / `aria-description` | v1.5 |
+| JS 字符串字面量 | `const STOCK = 'AI芯片';` 里的 `'AI芯片'`（含单/双引号 + 纯反引号字符串） | v1.5 |
+| 模板字符串静态片段 | `` `hello ${name}` `` 里的 `hello ` | v1.5 |
+
+**入口**（任一）：按 `E` 键 / canvas 项 iframe toolbar 「开启文案编辑」 / html 项右上角浮层 toggle。
+
+**不可编辑提示**：灰色高亮 + hover 200ms tooltip，10 类原因（`no-locator` / `pm-id-not-found` / `text-mismatch` / `no-text-child` / `whitespace-only` / `computed-text` / `template-expression` / `attribute-not-editable` / `script-or-style-internal` / `source-position-ambiguous`）。
+
+**实现要点**：
+- 后端 Patcher Strategy（HtmlText / HtmlAttr / JsLiteral），用 parse5 + acorn 解析定位 + 字符 offset 切片重写
+- JS 字面量首次保存自动插 sentinel 注释（`/*pm-js-id:lit-xxx*/`）便于下次精确反查；多处同字面量返 `source-position-ambiguous`
+- 保存走 fileHash 校验 + 冲突弹窗（覆盖 / 取消）
+- 详见 [`ai/specs/2026-06-03-inline-text-editing-v1.5-design.md`](../ai/specs/2026-06-03-inline-text-editing-v1.5-design.md)
+
+**已知限制**（v1.5 → 后续）：
+- JS 字面量改完后 DOM 不自动重算（DOM 是 JS innerHTML 拼出）→ toast 提示「刷新页面看效果」；根治需 skill 模板侧为动态节点注入 `data-pm-id`
+- 模板字符串 quasi 不插 sentinel（会破坏模板字符串）→ 同 stringValue quasi 多处时 `source-position-ambiguous`
+- 见 `ai/ROADMAP.md` 技术债清单
+
+### 命令行
+
+```bash
+canvas open [目录]  -p <端口>     # 默认 4800
+canvas                            # 历史检索
+canvas list                       # 列运行实例
+canvas stop [port|--all]          # 停止实例
+canvas --version / --help
+```
 
 ## 技术栈
 
 | 层 | 技术 |
 |---|---|
 | CLI | Commander.js |
-| 服务端 | Express（静态文件 + 文件读写 API） |
+| 服务端 | Express（ItemRegistry + routeId 协议 + 路径穿越防御） |
 | 前端框架 | React 18 + Vite |
 | MD 编辑器 | Tiptap 3 WYSIWYG（@tiptap/markdown） |
-| 流程图编辑 | @excalidraw/excalidraw |
+| 流程图编辑 | @excalidraw/excalidraw + diagrams.net embed |
 | 构建 | Vite 5 |
 
+## 安全
+
+- 服务端只接受 scanner 产出的 routeId（sha1 前 8 位），不接受任意路径
+- 路径穿越二段防御：filename 层拒绝 `\0` / `/` / `..` / `.` 开头；resolve 后强制落在项目录内
+- iframe sandbox（html 项）+ 跳转拦截脚本（拦 `<a>` / `<form>` / `window.open` / `history.pushState` / 越界 location）
+
 ## 开发
 
 ```bash
@@ -88,25 +174,38 @@ npm run dev
 npm run build
 
 # 用开发版直接测试
-node bin/cli.js open /path/to/canvas --port 4800
+node bin/cli.js open /path/to/dir --port 4800
 ```
 
 ### 项目结构
 
 ```
 pm-canvas-viewer/
-├── bin/cli.js                  ← CLI 入口
+├── bin/cli.js                         ← CLI 入口
 ├── server/
-│   ├── index.js                ← Express 服务器
-│   └── api/files.js            ← 文件 CRUD API（限定 docs/ 目录）
-├── frontend/
-│   ├── src/
-│   │   ├── App.jsx             ← 主布局
-│   │   ├── CanvasView/         ← 画板 iframe
-│   │   ├── DocPanel/           ← 右侧面板 + 标签页 + 新建
-│   │   ├── MdEditor/           ← Tiptap MD 编辑器
-│   │   └── ExcalidrawEditor/   ← Excalidraw 编辑器
-│   └── vite.config.js
-├── dist/                       ← 前端构建产物（gitignored）
-└── ai/                         ← AI 协作产物
+│   ├── index.js                       ← Express 服务器 + /item/:routeId/* 静态路由
+│   ├── itemRegistry.js                ← 单例 routeId → Item 映射
+│   └── api/
+│       ├── files.js                   ← docs/ CRUD（routeId 协议 + 按需 mkdir）
+│       └── anchors.js                 ← anchors.json CRUD（仅画板项）
+├── lib/
+│   ├── scanner.js                     ← 展示项扫描（画板 / html / 容器 / 过滤）
+│   ├── history.js                     ← 启动过的根目录历史
+│   ├── port.js                        ← 端口管理
+│   └── prompts.js                     ← 终端 TUI（fuzzy 选择）
+├── frontend/src/
+│   ├── App.jsx                        ← 主布局 + 导航状态机 + 切项清理
+│   ├── apiClient.js                   ← 统一注入 routeId 的 fetch 封装
+│   ├── Sidebar/                       ← 左栏（项树 + 页列表）
+│   ├── CanvasView/
+│   │   ├── index.jsx                  ← iframe 双模式渲染
+│   │   └── iframeInterceptor.js       ← html 项跳转拦截脚本生成器
+│   ├── DocPanel/                      ← 右栏 + 新建文件
+│   ├── MdEditor/                      ← Tiptap MD
+│   ├── ExcalidrawEditor/              ← Excalidraw
+│   ├── DrawioEditor/                  ← draw.io iframe
+│   ├── AnchorSystem/                  ← 锚点 overlay + store + dialog
+│   └── Toast.jsx                      ← 拦截反馈
+├── dist/                              ← 前端构建产物（gitignored，发包时打入）
+└── package.json
 ```

package/bin/cli.js

@@ -1,84 +1,65 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import { resolve } from 'path';
-import { existsSync } from 'fs';
+import { resolve, basename } from 'path';
+import { existsSync, statSync } from 'fs';
 import open from 'open';
 import { createServer } from '../server/index.js';
-import { scanForCanvases, tryReadCanvasMeta } from '../lib/scanner.js';
-import { recordOpen, getRecentCanvases } from '../lib/history.js';
-import { findAvailablePort, isPortFree, getPortOccupant, killPort, listRunningInstances, registerInstance } from '../lib/port.js';
-import { fuzzySelectCanvas, fuzzySelectFromHistory, handlePortConflict } from '../lib/prompts.js';
+import { scanForItems } from '../lib/scanner.js';
+import { recordOpenRoot, getRecentRoots } from '../lib/history.js';
+import {
+  findAvailablePort, isPortFree, getPortOccupant, killPort,
+  listRunningInstances, registerInstance,
+} from '../lib/port.js';
+import { fuzzySelectFromHistory, handlePortConflict } from '../lib/prompts.js';
+import registry from '../server/itemRegistry.js';
 
 const program = new Command();
 
 program
   .name('canvas')
-  .description('Local canvas viewer + doc editor')
+  .description('Local viewer + doc editor for HTML prototypes & pm-canvas boards')
   .version('0.1.0');
 
-// Default command: canvas — interactive fuzzy search over history
+// canvas — 从历史里挑一个根目录打开
 program
   .action(async () => {
-    const entries = await getRecentCanvases();
+    const entries = await getRecentRoots();
     const selected = await fuzzySelectFromHistory(entries);
     if (!selected) process.exit(0);
 
-    const meta = await tryReadCanvasMeta(selected.path);
-    if (!meta) {
-      console.error(`  Canvas no longer exists: ${selected.path}`);
+    if (!existsSync(selected.rootPath)) {
+      console.error(`  Root no longer exists: ${selected.rootPath}`);
       process.exit(1);
     }
 
-    await startServer(selected.path, meta);
+    await startServerForRoot(selected.rootPath);
   });
 
-// canvas open [path] — scan current directory or open a direct path
+// canvas open [path] — 打开指定文件夹（或当前目录）
 program
   .command('open [path]')
-  .description('Scan current directory for canvases, or open a path directly')
+  .description('Open a directory as viewer root (scans for items)')
   .option('-p, --port <port>', 'Server port', '4800')
   .action(async (targetPath, opts) => {
     portOverride = opts.port ? parseInt(opts.port) : null;
 
-    if (targetPath) {
-      const fullPath = resolve(targetPath);
+    const target = targetPath ? resolve(targetPath) : process.cwd();
 
-      if (!existsSync(fullPath)) {
-        console.error(`  Directory not found: ${fullPath}`);
-        process.exit(1);
-      }
-
-      // Direct canvas path
-      const meta = await tryReadCanvasMeta(fullPath);
-      if (meta) {
-        await startServer(meta.path, meta);
-        return;
-      }
-
-      // Not a canvas — scan it
-      console.log('  Scanning for canvases...');
-      const found = await scanForCanvases(fullPath, 4);
-      const history = await getRecentCanvases();
-      const selected = await fuzzySelectCanvas(found, history);
-      if (!selected) process.exit(0);
-      await startServer(selected.path, selected);
-    } else {
-      // No path — scan current directory
-      const cwd = process.cwd();
-      const cwdMeta = await tryReadCanvasMeta(cwd);
-
-      if (cwdMeta) {
-        await startServer(cwdMeta.path, cwdMeta);
-        return;
-      }
+    if (!existsSync(target)) {
+      console.error(`  Path not found: ${target}`);
+      process.exit(1);
+    }
 
-      console.log('  Scanning for canvases...');
-      const found = await scanForCanvases(cwd, 4);
-      const history = await getRecentCanvases();
-      const selected = await fuzzySelectCanvas(found, history);
-      if (!selected) process.exit(0);
-      await startServer(selected.path, selected);
+    // 拒绝单文件路径 — viewer 定位是"HTML + docs/"组合，必须是文件夹
+    const st = statSync(target);
+    if (!st.isDirectory()) {
+      console.error(`  viewer 必须打开文件夹，不接受单文件路径`);
+      console.error(`  Got: ${target}`);
+      console.error(`  Hint: 用浏览器直接打开 HTML 文件即可，viewer 用于"HTML + docs 文档"组合查看`);
+      process.exit(1);
     }
+
+    await startServerForRoot(target);
   });
 
 program
@@ -90,7 +71,6 @@ program
       console.log('  No running canvas instances.');
       return;
     }
-
     console.log(`\n  Running instances:\n`);
     for (const inst of instances) {
       console.log(`  Port ${inst.port}  PID ${inst.pid}`);
@@ -147,52 +127,81 @@ program
 
 let portOverride = null;
 
-async function startServer(canvasDir, meta) {
-  const preferredPort = portOverride || 4800;
-  let port;
-
-  if (await isPortFree(preferredPort)) {
-    port = preferredPort;
-  } else {
-    const occupant = getPortOccupant(preferredPort);
-
-    if (occupant?.isPmCanvas) {
-      const action = await handlePortConflict(preferredPort, occupant);
-      if (!action) process.exit(0);
-
-      switch (action) {
-        case 'reuse':
-          const url = `http://localhost:${preferredPort}`;
-          console.log(`\n  Opening ${url}`);
-          await open(url);
-          process.exit(0);
-        case 'kill':
-          killPort(preferredPort);
-          await new Promise(r => setTimeout(r, 500));
-          port = preferredPort;
-          break;
-        case 'next':
-          port = await findAvailablePort(preferredPort + 1);
-          break;
-      }
-    } else {
-      port = await findAvailablePort(preferredPort);
-    }
+async function startServerForRoot(rootDir) {
+  console.log('  Scanning for items...');
+  let scanResult;
+  try {
+    scanResult = await scanForItems(rootDir);
+  } catch (err) {
+    console.error(`  Scan failed: ${err.message}`);
+    process.exit(1);
   }
 
-  const server = createServer(canvasDir);
-  const title = meta?.title || canvasDir.split('/').pop();
+  if (scanResult.items.length === 0) {
+    console.error(`  No HTML prototypes or canvas boards found under ${rootDir}`);
+    console.error(`  Hint: 目录里需要至少 1 个 .html 文件，或含 canvas.json 的子目录`);
+    process.exit(1);
+  }
+
+  const rootName = basename(rootDir);
+  registry.setRoot({
+    rootDir,
+    rootName,
+    items: scanResult.items,
+    tree: scanResult.tree,
+    stats: scanResult.stats,
+  });
+
+  // v0.5: 编辑文案功能需要每个元素有稳定 data-pm-id，启动时自动注入（幂等）
+  const { injectAllCanvasItems } = await import('../lib/scan-and-inject.js');
+  const injectResults = await injectAllCanvasItems(scanResult.items);
+  const changed = injectResults.filter(r => r.changed).length;
+  if (changed > 0) {
+    console.log(`  ✓ 已给 ${changed} 个 HTML 文件注入 data-pm-id（首次迁移）`);
+  }
+
+  const port = await resolvePort(portOverride || 4800);
+  if (port === null) process.exit(0); // 用户在端口冲突 prompt 中选了 reuse
+
+  const server = createServer();
   server.listen(port, async () => {
     const url = `http://localhost:${port}`;
+    const { itemCount, canvasCount, htmlCount } = scanResult.stats;
     console.log(`\n  canvas-viewer`);
-    console.log(`  Canvas: ${title}`);
-    console.log(`  Path:   ${canvasDir}`);
+    console.log(`  Root:   ${rootDir}`);
+    console.log(`  Items:  ${itemCount} (${canvasCount} canvas · ${htmlCount} html)`);
     console.log(`  URL:    ${url}\n`);
     open(url);
 
-    await registerInstance(port, canvasDir, title).catch(() => {});
-    await recordOpen(canvasDir, meta?.title).catch(() => {});
+    await registerInstance(port, rootDir, rootName).catch(() => {});
+    await recordOpenRoot(rootDir, { title: rootName, itemCount }).catch(() => {});
   });
 }
 
+async function resolvePort(preferredPort) {
+  if (await isPortFree(preferredPort)) return preferredPort;
+
+  const occupant = getPortOccupant(preferredPort);
+  if (occupant?.isPmCanvas) {
+    const action = await handlePortConflict(preferredPort, occupant);
+    if (!action) return null;
+
+    switch (action) {
+      case 'reuse': {
+        const url = `http://localhost:${preferredPort}`;
+        console.log(`\n  Opening ${url}`);
+        await open(url);
+        return null;
+      }
+      case 'kill':
+        killPort(preferredPort);
+        await new Promise(r => setTimeout(r, 500));
+        return preferredPort;
+      case 'next':
+        return await findAvailablePort(preferredPort + 1);
+    }
+  }
+  return await findAvailablePort(preferredPort);
+}
+
 program.parse();