docs(workspace): explain host page and sidebar lifecycles

src/components/workspace/board-directory.tsx

@@ -1,3 +1,7 @@
+/**
+ * 侧栏画布树显示组件，使用业务目录库派生结构/搜索路径，只保存哪些目录项被用户折叠。
+ * 不重写board父子归属；活动路径和搜索可临时展开祖先，路由Link负责进入真实画布页面。
+ */
 "use client";
 import { useEffect, useMemo, useState } from "react";
 import Link from "next/link";
@@ -6,13 +10,16 @@ import { activeBoardAncestors, boardDirectory, filterBoardDirectory, type BoardB
 import { boardHref, matchesRef, type Board } from "@/lib/workspace";
 import styles from "./workspace.module.css";
 
+/** branches只随boards/query重算，closed是当前挂载视图局部状态，宿主切工作区可用key重建。 */
 export function BoardDirectory({ boards, workspace, active, query, demo }: { boards: Board[]; workspace: string; active?: string; query: string; demo: boolean }) {
   const [closed, setClosed] = useState(new Set<string>());
   const branches = useMemo(() => filterBoardDirectory(boardDirectory(boards), query), [boards, query]);
+  /** 活动画布或目录刷新时展开其祖先路径，防当前页藏在折叠树下。 */
   useEffect(() => {
     const path = activeBoardAncestors(boards, active);
     setClosed((previous) => { const next = new Set(previous); for (const id of path) next.delete(id); return next; });
   }, [active, boards]);
+  /** 递归渲染树，视觉缩进最多8层但不裁掉更深子项；搜索时强制展开匹配路径而不清空用户closed记录。 */
   function render(items: BoardBranch[], depth = 0) {
     return <ul className={styles.directoryList}>{items.map(({ board, children }) => {
       const expanded = !!query.trim() || !closed.has(board.id);
@@ -22,5 +29,6 @@ export function BoardDirectory({ boards, workspace, active, query, demo }: { boa
       </div>{expanded && children.length > 0 && render(children, depth + 1)}</li>;
     })}</ul>;
   }
+  // 有结果显示树；仅搜索无命中给提示，原始目录空时不伪造一条默认页面。
   return branches.length ? render(branches) : query ? <p className={styles.hint}>没有找到相关页面</p> : null;
 }