contactsheet 0.1.2 → 0.1.3

package/README.md

@@ -160,6 +160,11 @@ open(橙) ──标记完成──▶ resolved(绿·待核验) ──核验通
 ## 左侧列表与布局
 
 左侧是图层列表：**上半是页面**（显示各自的真实路由，点一下聚焦过去），**下半是组件**（按文件分组）。
+
+**页面画板默认全部收起**，从列表按需打开。一块页面画板 = 一个完整 app 实例的 iframe
+（React、provider、realtime 全套），二十几块同时挂载会把 dev server 和浏览器一起拖垮。
+收起的画板完全不发请求，打开那一刻才挂载；你开过/关过谁会被记住，新出现的页面画板才默认收起。
+组件画板轻得多，默认全部显示。
 顶部搜索框按名字/文件/路由过滤；每行右边的圆点是显隐开关——隐藏只是从墙上撤下，随时点回来。
 分区标题（「页面」「组件」）和每个文件组都能**折叠**；标题行右侧的三态圆点是**整组一键显隐**
 （`●` 全显示 / `◐` 部分 / `◌` 全隐藏，点一下在「全显示」和「全隐藏」之间切）。折叠状态按项目记住。
@@ -223,10 +228,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 只负责「同时看见很多状态」

package/dist/canvas/app.js

@@ -1539,6 +1539,7 @@ ${board.entry.kind} \xB7 ${board.entry.id}`);
           if (state.scale < MOUNT_MIN_SCALE) continue;
           const id = r.target.dataset.id;
           const board = id ? state.boards.get(id) : null;
+          if (board?.el.hidden) continue;
           if (board) requestMount(board);
           io.unobserve(r.target);
         }
@@ -1568,6 +1569,7 @@ ${board.entry.kind} \xB7 ${board.entry.id}`);
       heightWatchers.get(id)?.disconnect();
       heightWatchers.delete(id);
     }
+    const defaultHid = markSeenAndDefaultHide(entries);
     for (const [file, list] of byFile) {
       const ids = list.map((e) => e.id);
       const kept = (state.order.get(file) ?? []).filter((id) => ids.includes(id));
@@ -1587,6 +1589,7 @@ ${board.entry.kind} \xB7 ${board.entry.id}`);
       applyPositions();
       if (n && !firstSync) toast(`\u65B0\u753B\u677F ${n} \u5757 \xB7 \u5DF2\u653E\u5230\u5899\u5E95\u90E8`, "info");
     }
+    if (defaultHid) toast("\u9875\u9762\u753B\u677F\u9ED8\u8BA4\u6536\u8D77(\u6574\u9875 iframe \u592A\u91CD),\u5728\u5DE6\u4FA7\u300C\u9875\u9762\u300D\u5206\u533A\u6309\u9700\u6253\u5F00", "info");
     if (state.boards.size) firstSync = false;
     renderSidebar();
   }
@@ -1647,6 +1650,7 @@ ${board.entry.kind} \xB7 ${board.entry.id}`);
     }
     attachResizeHandles(board);
     attachBoardDrag(board);
+    el.hidden = isHidden(entry.id);
     applySize(board);
     updateBoard(board, entry);
     io.observe(el);
@@ -1729,6 +1733,34 @@ ${board.entry.kind} \xB7 ${board.entry.id}`);
   function hiddenKey() {
     return `cs-hidden:${state.info?.projectRoot ?? "unknown"}`;
   }
+  function seenKey() {
+    return `cs-seen:${state.info?.projectRoot ?? "unknown"}`;
+  }
+  function markSeenAndDefaultHide(entries) {
+    let seen;
+    try {
+      seen = new Set(JSON.parse(localStorage.getItem(seenKey()) ?? "[]"));
+    } catch {
+      seen = /* @__PURE__ */ new Set();
+    }
+    const fresh = entries.filter((e) => !seen.has(e.id));
+    if (fresh.length === 0) return false;
+    const hid = hiddenSet();
+    let hidSomething = false;
+    for (const e of fresh) {
+      seen.add(e.id);
+      if (e.kind === "screen") {
+        hid.add(e.id);
+        hidSomething = true;
+      }
+    }
+    try {
+      localStorage.setItem(seenKey(), JSON.stringify([...seen]));
+      if (hidSomething) localStorage.setItem(hiddenKey(), JSON.stringify([...hid]));
+    } catch {
+    }
+    return hidSomething;
+  }
   function hiddenSet() {
     try {
       return new Set(JSON.parse(localStorage.getItem(hiddenKey()) ?? "[]"));
@@ -1979,6 +2011,7 @@ ${board.entry.kind} \xB7 ${board.entry.id}`);
     }
   }
   function requestMount(board) {
+    if (board.el.hidden) return;
     if (board.iframe || mountQueue.includes(board)) return;
     if (loadingCount >= MAX_LOADING) {
       mountQueue.push(board);