contactsheet 0.1.2 → 0.1.4

package/README.md

@@ -60,7 +60,10 @@ flags：`--port`（外壳端口，默认 5199）、`--target`（你的 dev serve
 - 5199 被**别的进程**占着：自动顺延到下一个空闲端口（最多 +20）并醒目提示。注意顺延 = 换浏览器源，
   画板位置这些本机记忆按源隔离，`.mcp.json`/hook 也仍指向原端口——想固定就改 config 的 port 再跑一次 `init`；
 - 5199 上跑的是**本项目的另一个 contactsheet**（最常见：忘了已经起过）：直接提示地址退出，不再起第二个；
-- 显式传了 `--port` 时不猜你的意图：被占就报错，附排查命令。
+- 显式传了 `--port` 时不猜你的意图：被占就报错，附排查命令；
+- **判定「被占」看的是双栈**：外壳同时绑 `127.0.0.1` 和 `::1`（浏览器解析 localhost 普遍优先 IPv6——
+  只绑 v4 的话，v6 侧被别的进程占着时 curl 一切正常、浏览器却拿到别人的空响应，Docker 的端口转发就常年蹲在
+  IPv6 通配上）。任何一侧绑不上都算冲突，照常顺延。
 
 **只监听 127.0.0.1。** 画布没有登录，而 `p` 推送能以你的名义往 Claude Code 会话里说话 ——
 所以默认只有本机能连。非 GET 请求还会校验 Origin，推送另外要一枚每次启动随机生成的 token
@@ -117,7 +120,7 @@ export 名可以用中文。布局见下面「左侧列表与布局」一节。
 | 操作 | 进入 | 干什么 |
 |---|---|---|
 | **浏览**（默认） | `Esc` 随时回来 | 鼠标划过高亮元素，点一下 = 指着它（生成 CSS selector 发给外壳）。组件画板上 `html`/`body`/注入的 wrapper 不参与反查——组件比画板视口小时，空白处什么都不高亮，**指着空白 = 没指任何东西**（页面画板不过滤，body 就是页面本身） |
-| **交互** | 双击画板 | 这块画板可以点、可以填、可以展开菜单，其余压暗 |
+| **交互** | 双击画板 | 这块画板可以点、可以填、可以展开菜单，其余压暗。压暗的画板点不动是**故意的**（误触不打断你正在交互的板）——点了会提示，**双击那块**即可切换交互目标 |
 | **走查** | 选中画板后 `Enter` | 这块画板放大居中（最多 2 倍——不改画板声明的宽度，媒体查询保持真实），`Esc` 退出 |
 
 其他键：
@@ -153,6 +156,7 @@ open(橙) ──标记完成──▶ resolved(绿·待核验) ──核验通
 - `1` 全景（一屏看完整面墙）· `2` 聚焦当前画板 · `0` 回到 100% · `+` / `-` 步进缩放
 - 点一个 pin 选中它，然后 `Enter` 编辑（编辑中再按 `Enter` 保存，`Shift+Enter` 换行）、
   `Backspace` 删除、`Esc` 取消选中
+- 浏览模式下没选 pin 时，对着画板按 `Backspace` = **收起这块画板**（不是删除，左侧列表随时点回来）
 - **pin 上的数字是批注的永久序号**：按创建顺序分配，全墙唯一，核验/打回都不改号——
   推送给 Claude 的文本里每条批注也带同一个 `#序号`，所以你说「批注 3」，
   你、墙、Claude 指的是同一条。（唯一例外：「删除」误钉的 pin 后，最大号可能被下一条重用）
@@ -160,6 +164,11 @@ open(橙) ──标记完成──▶ resolved(绿·待核验) ──核验通
 ## 左侧列表与布局
 
 左侧是图层列表：**上半是页面**（显示各自的真实路由，点一下聚焦过去），**下半是组件**（按文件分组）。
+
+**页面画板默认全部收起**，从列表按需打开。一块页面画板 = 一个完整 app 实例的 iframe
+（React、provider、realtime 全套），二十几块同时挂载会把 dev server 和浏览器一起拖垮。
+收起的画板完全不发请求，打开那一刻才挂载；你开过/关过谁会被记住，新出现的页面画板才默认收起。
+组件画板轻得多，默认全部显示。
 顶部搜索框按名字/文件/路由过滤；每行右边的圆点是显隐开关——隐藏只是从墙上撤下，随时点回来。
 分区标题（「页面」「组件」）和每个文件组都能**折叠**；标题行右侧的三态圆点是**整组一键显隐**
 （`●` 全显示 / `◐` 部分 / `◌` 全隐藏，点一下在「全显示」和「全隐藏」之间切）。折叠状态按项目记住。
@@ -223,10 +232,36 @@ iframe 的画布永远是不透明的，所以组件画板必然有一层底。
 - **token 存在 localStorage / sessionStorage 里的项目要多登一次**：storage 按源隔离，`:5199` 是另一个源。
   在 `:5199` 下把你的登录流程走一遍（页面画板正好可以直接开 `/login`），之后就一直有了。
 
+## 接入方式：已有项目 / 新项目
+
+**已有项目**（先把看得见的上墙，再逐步补数据）：
+
+1. `npx contactsheet init` —— 组件骨架画板自动铺出来；
+2. 公开页面（登录页、文档页）直接写进 `design/screens.artboard.ts`，立即可看；
+3. 受登录保护的页面：在 dev server 的端口登一次测试账号即可（cookie 不分端口，画布共享登录态）；
+4. 有**服务端权限守卫**的页面（管理后台这类）：mock 救不了它——守卫跑在服务端，
+   唯一正解是给测试账号相应权限（dev seed 提权）。这是项目侧的一次性工作；
+5. 带参数的路由（`/t/[teamId]`、`/projects/[id]`）：让项目提供一组**重置后不变的 demo id**
+   （固定 slug 的种子数据），画板 url 里直接写死。
+
+页面多了按区拆文件：`screens-public.artboard.ts` / `screens-admin.artboard.ts` / `screens-team.artboard.ts`，
+侧栏会按文件分组。`design/` 整个提交进 git——画板即文档，团队共享。
+
+**新项目**（design-first，从第一天就把回路建起来）：
+
+1. 写组件前先写 artboard —— 画板就是组件的规格（要哪些状态，一个 export 一个）；
+2. 每建一条路由，顺手在 screens 文件里加一行，路由和画板同步生长；
+3. seed 脚本第一天就准备**两个账号**：一个永远空（审空态），一个数据丰富（审满态）——
+   这比任何 mock 层都便宜，而且看到的就是真实渲染路径。
+
+**为什么没有 mock 模式**：页面画板渲染的是你 dev server 的真实输出。服务端组件在服务端取数、
+守卫在服务端判权，浏览器侧的 mock 层拦不到它们；拦到了，你看的也不再是用户会看到的东西。
+数据问题在数据侧解决（种子、测试账号、demo id），画布只负责让你同时看见。
+
 ## 边界（先说清楚，省得你试）
 
-- **没有 mock 层**。画板拿到的数据就是你 dev 环境里的真数据。「空态 / 错误态 / 加载中」这类需要拦网络的场景，
-  v1 只能靠你自己在组件层传 props 摆出来；内置 mocks 排在 v1.1。
+- **没有 mock 层，也不打算做**（理由见上一节）。组件的「空态 / 错误态 / 加载中」在组件层传 props 摆出来；
+  页面的空态/满态用两个种子账号解决。
 - **走查模式很勉强**。它就是把一块画板放大居中，方便盯细节；要走完整流程（多页跳转、真实滚动、devtools），
   请照常开浏览器访问 `:3000`。
 - **它不是开发环境，是一扇窗**。构建、测试、调试照旧在你原来的地方做。contactsheet 只负责「同时看见很多状态」