pm-canvas-viewer 0.1.1 → 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

@@ -152,6 +152,14 @@ async function startServerForRoot(rootDir) {
     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