contactsheet 0.1.3 → 0.1.5

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 后，最大号可能被下一条重用）
@@ -267,6 +271,19 @@ iframe 的画布永远是不透明的，所以组件画板必然有一层底。
 - 画板路由在生产环境不可访问：`next build` 的路由清单里它仍然在，但运行时一律 404（`notFound()` 守卫）。
   想连清单都不进，`next build` 前跑一次 `contactsheet clean`。
 
+## dev server 出问题时（画布会替你归因）
+
+画布长开时，被代理的 `next dev` 自己可能出问题。外壳每 20 秒探测一次它的 SSR 路径，
+连挂两次就在画布顶部拉**红色横幅**——看到横幅，坏的是 dev server，不是画布。两种实测指纹：
+
+1. **所有路由秒回 500、连请求日志都不打**：`.next` 开发缓存被硬杀打坏（next/font 会进入
+   失败重试死循环，`.next` 疯狂膨胀）。重启救不回来，`rm -rf .next` 后再起即愈。
+2. **静态资源 200、SSR 报错、API 挂死、worker 数暴涨**：dev server 僵死，重启 `next dev` 即愈。
+
+外壳侧的配合：客户端中途放弃的请求（僵死期浏览器的重试洪水就是这样）会**向上游同步中断**——
+否则每次放弃都在 dev server 里留一个永远"渲染中"的挂起请求，把它压得更死（这同时也是外壳自身的
+fd 泄漏源，实测 300 次中断泄 300 个 fd，已修）。
+
 ## 卸载
 
 ```bash