("checking");
const [detected, setDetected] = useState("");
const [busy, setBusy] = useState(false);
+ /** WebView2 运行时缺失(UI-4 Stage B2);仅在权威判定为 false 时置位 */
+ const [wv2Missing, setWv2Missing] = useState(false);
const check = useCallback(async () => {
setBusy(true);
try {
- if (!(await probePort())) {
+ // 端口探测与 WebView2 检测同轮发起;后者失败按「不可知」处理,不误报
+ const [hubUp, wv2Present] = await Promise.all([probePort(), probeWebview2()]);
+ setWv2Missing(!wv2Present);
+ if (!hubUp) {
setPhase("guide");
return;
}
@@ -87,6 +99,23 @@ export default function HubLauncher({ onReady }: HubLauncherProps) {
未检测到 tts-hub
+ {wv2Missing && (
+
+
+ ⚠
+
+
+ 缺少 WebView2 运行时:本应用界面可能无法渲染。请先安装并重启应用。
+
+
+
+ )}
桌面应用经 hub({HUB_BASE_URL.replace(/^http:\/\//, "")})与
Tabletop Simulator 通信。请在终端先启动:
@@ -146,6 +175,29 @@ async function probePort(): Promise {
}
}
+/**
+ * WebView2 运行时探测(UI-4 Stage B2):Rust 侧 is_webview2_present(查注册表)。
+ * 非 Tauri 环境(纯浏览器 dev)与命令缺失(旧壳 / 调用异常)一律按 true 返回——
+ * 只有拿到权威的 false 才提示,避免误报。
+ */
+async function probeWebview2(): Promise {
+ if (!isTauri()) return true;
+ try {
+ return await invoke("is_webview2_present");
+ } catch {
+ return true;
+ }
+}
+
+/** 打开微软官方 WebView2 引导安装链接;非 Tauri 环境退化为新标签页 */
+async function openWebview2Download(): Promise {
+ try {
+ await openUrl(WEBVIEW2_URL);
+ } catch {
+ window.open(WEBVIEW2_URL, "_blank", "noopener,noreferrer");
+ }
+}
+
async function probeHttp(): Promise {
const ctrl = new AbortController();
const timer = setTimeout(() => ctrl.abort(), PROBE_TIMEOUT_MS);
diff --git a/src/components/LayerTiles.css b/src/components/LayerTiles.css
new file mode 100644
index 0000000..ae95021
--- /dev/null
+++ b/src/components/LayerTiles.css
@@ -0,0 +1,76 @@
+/* 四面状态磁贴 — UI-4 Stage A1(a-deep.html .ov-side h4 + .ftile)
+ * 标题:仿宋小字 + 3px 字距 + 1px --w 实线下划线(§2.4 分版面);行间
+ * 1px dashed --wfaint 虚线分组(分组用虚线)。
+ * 字族:面名仿宋(标注层)/ 取值等宽(数据层),不混用(§2.2)。
+ * 状态色:取值色由 data-tone 决定(bad=--red 差异/死链、blue=--blue 代理、
+ * ok=--ok 一致、dim=--wdim 中性计数),全部引用 tokens.css 变量。 */
+
+.layertiles {
+ display: flex;
+ flex-direction: column;
+}
+
+.layertiles-head {
+ padding-bottom: var(--sp-2);
+ margin-bottom: var(--sp-2);
+ border-bottom: var(--border-w) solid var(--w);
+ font-family: var(--fs);
+ font-size: var(--fs-note);
+ letter-spacing: 3px;
+ color: var(--wdim);
+}
+
+.layertiles-tile {
+ display: flex;
+ align-items: baseline;
+ justify-content: space-between;
+ gap: var(--sp-3);
+ padding: var(--sp-2) var(--sp-1);
+ border-bottom: var(--border-w) dashed var(--wfaint);
+ font-family: var(--fs);
+ font-size: var(--fs-panel);
+ cursor: pointer;
+ transition: background var(--dur-fast) var(--ease-out);
+}
+
+.layertiles-tile:last-child {
+ border-bottom: none;
+}
+
+.layertiles-tile:hover {
+ background: var(--bp-d);
+}
+
+.layertiles-tile:focus-visible {
+ outline: var(--border-w) solid var(--blue);
+ outline-offset: calc(var(--border-w) * -1);
+}
+
+.layertiles-k {
+ color: var(--w);
+}
+
+/* 取值:等宽小字(数据层)+ 数字表格化(§2.2) */
+.layertiles-v {
+ font-family: var(--mono);
+ font-size: var(--fs-note);
+ line-height: var(--lh-data);
+ color: var(--wdim);
+}
+
+.layertiles-tile[data-tone="bad"] .layertiles-v {
+ color: var(--red);
+}
+
+.layertiles-tile[data-tone="blue"] .layertiles-v {
+ color: var(--blue);
+}
+
+.layertiles-tile[data-tone="ok"] .layertiles-v {
+ color: var(--ok);
+}
+
+/* ④ 素材行内的死链计数:红字(同一行内独立着色,--red = 死链) */
+.layertiles-bad {
+ color: var(--red);
+}
diff --git a/src/components/LayerTiles.tsx b/src/components/LayerTiles.tsx
new file mode 100644
index 0000000..7b3f081
--- /dev/null
+++ b/src/components/LayerTiles.tsx
@@ -0,0 +1,99 @@
+/**
+ * 四面状态磁贴 — UI-4 Stage A1(⓪总览右栏,a-deep.html .ftile)
+ *
+ * 职责:标题「四面状态」+ 四行磁贴(① 代码 / ② 代理 / ③ 卡牌 / ④ 素材),
+ * 每行「面名(仿宋)+ 取值(等宽)」,点击 → onNavigate(对应面)。
+ * 纯受控展示:全部取值从 OverviewData 派生(本组件不自查、不调 hub)。
+ *
+ * 四行取值规则(契约 §3,逐条落地):
+ * ① 代码:diffCount>0 → 红字「N ⇄」(与游戏内不同,--red 唯一语义);否则「✓ 一致」青
+ * ② 代理:蓝字「● 流水 N」(--blue = 代理活动)
+ * ③ 卡牌:cardCount,未知(null)→「—」
+ * ④ 素材:「N 行」(未知 →「—」)+ deadCount>0 时红字「N✗」(--red = 死链)
+ * 符号:⇄ M ✗ ✓ ● 均为已注册字符(§2.4 / 图例条),不引图标库。
+ */
+import type { KeyboardEvent, ReactElement, ReactNode } from "react";
+import type { LayerId, OverviewData } from "../state/processStamps";
+import "./LayerTiles.css";
+
+export interface LayerTilesProps {
+ /** 总览聚合数据(A3 经 useOverviewData 供给) */
+ data: OverviewData;
+ /** 行点击 → 跳转对应工作面 */
+ onNavigate(layer: LayerId): void;
+}
+
+/** 取值色调:默认弱色(--wdim)/ 红(差异·死链)/ 蓝(代理活动)/ 青(一致) */
+type TileTone = "dim" | "bad" | "blue" | "ok";
+
+interface Tile {
+ layer: LayerId;
+ label: string;
+ tone: TileTone;
+ value: ReactNode;
+}
+
+/** OverviewData → 四行磁贴(顺序固定 ① 代码 → ④ 素材) */
+function buildTiles(data: OverviewData): Tile[] {
+ return [
+ {
+ layer: "code",
+ label: "① 代码",
+ tone: data.diffCount > 0 ? "bad" : "ok",
+ value: data.diffCount > 0 ? `${data.diffCount} ⇄` : "✓ 一致",
+ },
+ {
+ layer: "agent",
+ label: "② 代理",
+ tone: "blue",
+ value: `● 流水 ${data.jobCount}`,
+ },
+ {
+ layer: "cards",
+ label: "③ 卡牌",
+ tone: "dim",
+ value: data.cardCount === null ? "—" : String(data.cardCount),
+ },
+ {
+ layer: "assets",
+ label: "④ 素材",
+ tone: "dim",
+ value: (
+ <>
+ {data.assetCount === null ? "—" : `${data.assetCount} 行`}
+ {data.deadCount > 0 && {data.deadCount}✗}
+ >
+ ),
+ },
+ ];
+}
+
+export default function LayerTiles(props: LayerTilesProps): ReactElement {
+ const { data, onNavigate } = props;
+ const tiles = buildTiles(data);
+
+ return (
+
+ 四面状态
+ {tiles.map((tile) => (
+ onNavigate(tile.layer)}
+ onKeyDown={(event: KeyboardEvent): void => {
+ if (event.key === "Enter" || event.key === " ") {
+ event.preventDefault();
+ onNavigate(tile.layer);
+ }
+ }}
+ >
+ {tile.label}
+ {tile.value}
+
+ ))}
+
+ );
+}
diff --git a/src/components/MiniFileTree.css b/src/components/MiniFileTree.css
new file mode 100644
index 0000000..a54985c
--- /dev/null
+++ b/src/components/MiniFileTree.css
@@ -0,0 +1,42 @@
+/* 工作区迷你文件树 — UI-4 Stage A1(a-deep.html .ov-blk + .ftree/.ftn)
+ * 块:1px --wdim 外框 + 底 --bp(总览面板底,与 待办 同款);
+ * 标题行:仿宋小字 + 3px 字距,右小注等宽弱色(数据层)。
+ * 复用 :覆盖其底色(bp-dd → 面板底 --bp)与高度(100% → 自然高度),
+ * 行高/字族/状态符号色一律沿用 CodeFileTree.css(单一事实源,不复制样式)。 */
+
+.miniftree {
+ border: var(--border-w) solid var(--wdim);
+ background: var(--bp);
+}
+
+.miniftree-head {
+ display: flex;
+ align-items: baseline;
+ justify-content: space-between;
+ gap: var(--sp-2);
+ padding: var(--sp-2) var(--sp-4);
+ border-bottom: var(--border-w) solid var(--wdim);
+}
+
+.miniftree-title {
+ font-family: var(--fs);
+ font-size: var(--fs-note);
+ letter-spacing: 3px;
+ color: var(--w);
+}
+
+/* 右上角小注:差异 N / 未注册图包(等宽弱色,数字表格化) */
+.miniftree-note {
+ font-family: var(--mono);
+ font-size: var(--fs-note);
+ line-height: var(--lh-data);
+ letter-spacing: 1px;
+ color: var(--wdim);
+ white-space: nowrap;
+}
+
+/* 复用件的底与高度适配:面板底、自然高度(外层若给高度上限则由 .codetree 自身滚动) */
+.miniftree-body .codetree {
+ height: auto;
+ background: var(--bp);
+}
diff --git a/src/components/MiniFileTree.tsx b/src/components/MiniFileTree.tsx
new file mode 100644
index 0000000..239493d
--- /dev/null
+++ b/src/components/MiniFileTree.tsx
@@ -0,0 +1,43 @@
+/**
+ * 工作区迷你文件树 — UI-4 Stage A1(⓪总览左下块,a-deep.html .ftree)
+ *
+ * 职责:块标题「工作区」+ 右上角小注(「差异 N」/「未注册图包」)+ 差异文件列表;
+ * 行点击 → onNavigate("code")(跳 ①代码面看 diff,不在此做编辑)。
+ * 复用泛化后的 (groups 单组渲染),故行样式/状态符号/键盘可达性
+ * 与①代码面对象区同源,不另造第二套文件树。
+ *
+ * 数据来源(契约 §5 修订版,逐字):nodes / note 由 A3 从 useOverviewData 派生后
+ * 传入——本组件不调 hub、不读模块级缓存、不依赖 hook 调用时序(纯受控展示)。
+ * nodes 为空时由 CodeFileTree 的分组空态渲染「— 无对象」(未注册图包 / 无差异
+ * 两种情况都不留空块)。
+ */
+import type { ReactElement } from "react";
+import CodeFileTree, { type TreeNode } from "./CodeFileTree";
+import type { LayerId } from "../state/processStamps";
+import "./MiniFileTree.css";
+
+export interface MiniFileTreeProps {
+ /** 差异文件节点(A3 由 useOverviewData 缓存派生;kind 按扩展名,status 按 added/modified/deleted) */
+ nodes: TreeNode[];
+ /** 右上角小注:「差异 N」或「未注册图包」 */
+ note: string;
+ /** 行点击 → 跳转工作面(本组件固定跳 "code") */
+ onNavigate(layer: LayerId): void;
+}
+
+export default function MiniFileTree(props: MiniFileTreeProps): ReactElement {
+ const { nodes, note, onNavigate } = props;
+
+ return (
+
+
+ 工作区
+ {note}
+
+
+ {/* 组标题留空:块标题已在上方,树内不重复标题也不留空标题占位 */}
+ onNavigate("code")} />
+
+
+ );
+}
diff --git a/src/components/ProcessStamps.css b/src/components/ProcessStamps.css
new file mode 100644
index 0000000..997b484
--- /dev/null
+++ b/src/components/ProcessStamps.css
@@ -0,0 +1,87 @@
+/* 工序章 — UI-4 Stage A1(round-03 §4.3 + a-deep.html .stamps/.stamp)
+ * 五等分章:边框 1px --w,章间 1px --wdim,直角无线框;底 --bp(图纸底)。
+ * 三层字族:.no / .st 等宽(数据层),.nm 仿宋(标注层),不用黑体(§2.2)。
+ * 状态色纪律(§2.5):done=--ok 青 / doing=--blue 蓝(进行中)/ alert=--red
+ * 红 / todo=--wdim 灰 + 半透明。颜色全部引用 tokens.css 变量,不写死色值。 */
+
+.processstamps {
+ display: flex;
+ border: var(--border-w) solid var(--w);
+ background: var(--bp);
+}
+
+.processstamps-stamp {
+ flex: 1;
+ min-width: 0;
+ position: relative;
+ padding: var(--sp-4) 0 var(--sp-3);
+ text-align: center;
+ background: var(--bp);
+ border-right: var(--border-w) solid var(--wdim);
+}
+
+.processstamps-stamp:last-child {
+ border-right: none;
+}
+
+/* 序号:等宽小字(数据层) */
+.processstamps-no {
+ font-family: var(--mono);
+ font-size: var(--fs-note);
+ line-height: var(--lh-data);
+ color: var(--wdim);
+ letter-spacing: 2px;
+}
+
+/* 工序名:仿宋大字(标注层),字距放开成章面 */
+.processstamps-nm {
+ margin: var(--sp-1) 0;
+ font-family: var(--fs);
+ font-size: calc(var(--fs-body) + var(--sp-1));
+ line-height: var(--lh-data);
+ letter-spacing: 5px;
+}
+
+/* 状态小字:等宽(数据层) */
+.processstamps-st {
+ font-family: var(--mono);
+ font-size: var(--fs-note);
+ line-height: var(--lh-data);
+}
+
+/* ---- done:已完成 → 状态小字青(--ok 唯一语义=成功/已完成) ---- */
+.processstamps-stamp[data-status="done"] .processstamps-st {
+ color: var(--ok);
+}
+
+/* ---- doing:进行中 → 底部 inset 蓝条 + 淡蓝底 + 名白字 + 状态蓝字 ----
+ * 淡蓝底 = a-deep .doing 的 rgba(143,192,230,.06):此处以 color-mix 由令牌
+ * 混出(不写死色值);不支持 color-mix 的环境落回面板底 --bp-d,蓝条仍在。 */
+.processstamps-stamp[data-status="doing"] {
+ background: var(--bp-d);
+ background: color-mix(in srgb, var(--blue) 6%, var(--bp));
+ box-shadow: inset 0 calc(var(--border-w) * -3) 0 var(--blue);
+}
+
+.processstamps-stamp[data-status="doing"] .processstamps-nm {
+ color: var(--w);
+}
+
+.processstamps-stamp[data-status="doing"] .processstamps-st {
+ color: var(--blue);
+}
+
+/* ---- alert:有问题 → 名与状态小字红(--red 唯一语义=错误/死链/差异) ---- */
+.processstamps-stamp[data-status="alert"] .processstamps-nm,
+.processstamps-stamp[data-status="alert"] .processstamps-st {
+ color: var(--red);
+}
+
+/* ---- todo:未开始 → 整章半透明 + 状态小字弱色 ---- */
+.processstamps-stamp[data-status="todo"] {
+ opacity: 0.5;
+}
+
+.processstamps-stamp[data-status="todo"] .processstamps-st {
+ color: var(--wdim);
+}
diff --git a/src/components/ProcessStamps.tsx b/src/components/ProcessStamps.tsx
new file mode 100644
index 0000000..0a758e3
--- /dev/null
+++ b/src/components/ProcessStamps.tsx
@@ -0,0 +1,48 @@
+/**
+ * 工序章 — UI-4 Stage A1(⓪总览顶部主角,§4.3)
+ *
+ * 职责:拉取→切片→拼版→校样→出厂 五章横排,等分;每章「序号(等宽小字)+
+ * 名(仿宋大字)+ 状态(等宽小字 note)」。差异化的图纸语言,总览唯一主角。
+ * 纯受控展示:不调 hub、不持状态——五章数据由 A3 经 useOverviewData 派生后传入,
+ * 本组件只做渲染 + 状态四态的视觉映射(§2.5 状态色纪律):
+ * done → .st 青(--ok = 已完成)
+ * doing → 章底 inset 蓝条 + 淡蓝底 + .nm 白字 + .st 蓝(--blue = 进行中)
+ * alert → .nm / .st 红(--red = 错误 / 死链 / 差异)
+ * todo → 整章半透明 + .st 灰(--wdim)
+ * 数据形状:StampState(state/processStamps.ts,契约 §1)——steps 恒 5 项,
+ * 顺序 拉取→切片→拼版→校样→出厂,序号 01…05 由数组下标派生(不写死)。
+ * 动效(§6,A2 实现到 CSS / A3 在 Overview.tsx 施加 .ov-enter→.ov-enter-done):
+ * 本章内每项即 .processstamps-stamp(.processstamps 的直接子元素,恰 5 项),
+ * 阶梯 transition-delay 由 :nth-child 命中;本组件不加动画类、不接管时序。
+ */
+import type { ReactElement } from "react";
+import type { StampState } from "../state/processStamps";
+import "./ProcessStamps.css";
+
+export interface ProcessStampsProps {
+ /** 五道工序(恒 5 项,顺序 拉取→切片→拼版→校样→出厂) */
+ steps: StampState[];
+}
+
+export default function ProcessStamps(props: ProcessStampsProps): ReactElement {
+ const { steps } = props;
+
+ return (
+
+ {steps.map((step, i) => (
+
+ {/* 序号:等宽·数字表格化(§2.2),01…05 由下标派生 */}
+
{String(i + 1).padStart(2, "0")}
+
{step.name}
+
{step.note}
+
+ ))}
+
+ );
+}
diff --git a/src/components/RouteSlide.tsx b/src/components/RouteSlide.tsx
new file mode 100644
index 0000000..09139ce
--- /dev/null
+++ b/src/components/RouteSlide.tsx
@@ -0,0 +1,32 @@
+/**
+ * — 工作面滑入包装(round-03 §2.6 第二件套:状态切换来路)
+ *
+ * 机制:挂载时根 div 带 .route-slide-pre(translateX(var(--dist-move)) + opacity 0),
+ * 双 rAF 后移除该类 → .route-slide 上的 transition(--dur-move / --ease-out)驱动
+ * transform + opacity 归位。用 transition 而非 keyframes 是为了让截图工具能抓到
+ * 过渡帧(§2.6 明示);样式表在 src/routes/routes.css(与其余路由壳样式同处)。
+ *
+ * 用法(五面路由根元素,替代原 ):
+ *
+ * …
+ *
+ *
+ * 受控性:本组件不持有业务状态,唯一的内部状态是"是否已入场"的动效开关
+ * (由 useFirstEnter 提供,挂载即启动,父组件无需干预)。
+ * prefers-reduced-motion 由 tokens.css 全局兜底,本组件无需分支。
+ */
+import { type ReactNode, type JSX } from "react";
+import { useFirstEnter } from "../hub/useFirstEnter";
+import "../routes/routes.css";
+
+export function RouteSlide(props: { children: ReactNode }): JSX.Element {
+ const entered = useFirstEnter();
+
+ return (
+
+ {props.children}
+
+ );
+}
+
+export default RouteSlide;
diff --git a/src/components/TodoList.css b/src/components/TodoList.css
new file mode 100644
index 0000000..7260bb1
--- /dev/null
+++ b/src/components/TodoList.css
@@ -0,0 +1,89 @@
+/*
待办清单 — UI-4 Stage A1(a-deep.html .ov-blk + .todo-line)
+ * 块:1px --wdim 外框 + 底 --bp(总览面板底);标题行 1px --wdim 实线分块;
+ * 行间 1px dashed --wfaint 虚线分组(§2.4 分隔三级)。
+ * 字族:标题与行文本仿宋(标注层,照 a-deep),符号等宽(数据层)。
+ * 颜色全部引用 tokens.css 变量,不写死色值。 */
+
+.todolist {
+ border: var(--border-w) solid var(--wdim);
+ background: var(--bp);
+}
+
+.todolist-head {
+ padding: var(--sp-2) var(--sp-4);
+ border-bottom: var(--border-w) solid var(--wdim);
+}
+
+.todolist-title {
+ font-family: var(--fs);
+ font-size: var(--fs-note);
+ letter-spacing: 3px;
+ color: var(--w);
+}
+
+.todolist-line {
+ display: flex;
+ align-items: center;
+ gap: var(--sp-3);
+ padding: var(--sp-2) var(--sp-4);
+ border-bottom: var(--border-w) dashed var(--wfaint);
+ font-family: var(--fs);
+ font-size: var(--fs-panel);
+ line-height: var(--lh-body);
+ cursor: pointer;
+ transition: background var(--dur-fast) var(--ease-out);
+}
+
+.todolist-line:last-child,
+.todolist-empty:last-child {
+ border-bottom: none;
+}
+
+.todolist-line:hover {
+ background: var(--bp-d);
+}
+
+.todolist-line:focus-visible {
+ outline: var(--border-w) solid var(--blue);
+ outline-offset: calc(var(--border-w) * -1);
+}
+
+/* 行首符号:固定槽宽(对齐),等宽字符;颜色由数据侧语义决定(§2.5) */
+.todolist-mk {
+ flex: none;
+ width: var(--sp-4);
+ text-align: center;
+ font-family: var(--mono);
+ font-size: var(--fs-note);
+}
+
+.todolist-line[data-color="red"] .todolist-mk {
+ color: var(--red);
+}
+
+.todolist-line[data-color="blue"] .todolist-mk {
+ color: var(--blue);
+}
+
+.todolist-line[data-color="amber"] .todolist-mk {
+ color: var(--amber);
+}
+
+.todolist-line[data-color="ok"] .todolist-mk {
+ color: var(--ok);
+}
+
+.todolist-text {
+ min-width: 0;
+ overflow: hidden;
+ white-space: nowrap;
+ text-overflow: ellipsis;
+}
+
+/* 空态:一行灰字,不留空白块 */
+.todolist-empty {
+ padding: var(--sp-3) var(--sp-4);
+ font-family: var(--fs);
+ font-size: var(--fs-panel);
+ color: var(--wdim);
+}
diff --git a/src/components/TodoList.tsx b/src/components/TodoList.tsx
new file mode 100644
index 0000000..c3e02dc
--- /dev/null
+++ b/src/components/TodoList.tsx
@@ -0,0 +1,76 @@
+/**
+ * 待办清单 — UI-4 Stage A1(⓪总览左下块,a-deep.html .todo-line)
+ *
+ * 职责:块标题「待 办」+ 若干行「mark 字符符号(自带颜色)+ 文本」;行点击
+ * → onNavigate(target),跳去该行所属工作面(①代码 / ③卡牌 / ④素材…)。
+ * 纯受控展示:todos 与跳转回调由 A3(useOverviewData + 图层切换)供给,
+ * 本组件不持状态、不调 hub。
+ * 符号与状态色(§2.4 符号即图标 / §2.5 纪律):mark 用字符符号(✗ ⇄ ✂ ⬆ ✓…),
+ * 颜色由 item.color 决定 —— 数据侧已按语义定色(红=错误·死链·差异、
+ * 蓝=进行中·代理、琥珀=待人审、青=成功·完成),本组件只做映射不做判断。
+ * 空态:一行灰字「✓ 无待办」(诚实空态,不留空白块)。
+ */
+import type { KeyboardEvent, ReactElement } from "react";
+import type { LayerId, TodoItem } from "../state/processStamps";
+import "./TodoList.css";
+
+export interface TodoListProps {
+ /** 待办行(来自 OverviewData.todos) */
+ todos: TodoItem[];
+ /** 行点击 → 跳转对应工作面 */
+ onNavigate(layer: LayerId): void;
+}
+
+function TodoLine(props: {
+ item: TodoItem;
+ onNavigate: TodoListProps["onNavigate"];
+}): ReactElement {
+ const { item, onNavigate } = props;
+
+ const activate = (): void => {
+ onNavigate(item.target);
+ };
+
+ const handleKeyDown = (event: KeyboardEvent): void => {
+ if (event.key === "Enter" || event.key === " ") {
+ event.preventDefault();
+ activate();
+ }
+ };
+
+ return (
+
+
+ {item.mark}
+
+ {item.text}
+
+ );
+}
+
+export default function TodoList(props: TodoListProps): ReactElement {
+ const { todos, onNavigate } = props;
+
+ return (
+
+
+ 待 办
+
+ {todos.length > 0 ? (
+ todos.map((item, i) => (
+
+ ))
+ ) : (
+ ✓ 无待办
+ )}
+
+ );
+}
diff --git a/src/hub/useFirstEnter.ts b/src/hub/useFirstEnter.ts
new file mode 100644
index 0000000..04bba6e
--- /dev/null
+++ b/src/hub/useFirstEnter.ts
@@ -0,0 +1,38 @@
+/**
+ * useFirstEnter — 首次进入钩子(round-03 §2.6 第三件套 / UI-4 Stage A 契约 §6)
+ *
+ * 语义:挂载后先返回 false(= 元素处于 pre 出场态),双 rAF 之后返回 true
+ * (= pre 态被移除,transition 归位)。仅首次挂载触发一次,之后不再回退。
+ *
+ * 双 rAF 的理由:第一帧让浏览器完成带 pre 类的首帧布局/绘制(否则"挂载即翻态"
+ * 会被合并进同一次样式计算,transition 不产生过渡帧);第二帧再翻态,过渡必被观测。
+ *
+ * 用法(装配方:总览面):
+ * const entered = useFirstEnter();
+ * …
+ * 类名语义见 src/routes/Overview.css(.ov-enter = pre 态,.ov-enter-done = 移除 pre)。
+ *
+ * 无副作用:不做订阅、不请求 hub;prefers-reduced-motion 由 tokens.css 全局
+ * transition:none 兜底(本 hook 照常翻态,元素直接落到终态)。
+ */
+import { useEffect, useState } from "react";
+
+export function useFirstEnter(): boolean {
+ const [entered, setEntered] = useState(false);
+
+ useEffect(() => {
+ let raf1 = 0;
+ let raf2 = 0;
+ raf1 = window.requestAnimationFrame(() => {
+ raf2 = window.requestAnimationFrame(() => setEntered(true));
+ });
+ return () => {
+ window.cancelAnimationFrame(raf1);
+ window.cancelAnimationFrame(raf2);
+ };
+ }, []);
+
+ return entered;
+}
+
+export default useFirstEnter;
diff --git a/src/routes/Agent.tsx b/src/routes/Agent.tsx
index a0f3141..22f0b45 100644
--- a/src/routes/Agent.tsx
+++ b/src/routes/Agent.tsx
@@ -23,6 +23,7 @@ import type { ReactElement } from "react";
import JobSheet from "../components/JobSheet";
import LuaExecPanel from "../components/LuaExecPanel";
import EventFlow from "../components/EventFlow";
+import { RouteSlide } from "../components/RouteSlide";
import { useSseEvents } from "../hub/useSseEvents";
import { useJobTracker } from "../hub/useJobTracker";
import { useHub } from "../hub/HubContext";
@@ -74,7 +75,7 @@ export default function Agent(): ReactElement {
};
return (
-
+
{/* 工作区:作业流水 */}
@@ -94,6 +95,6 @@ export default function Agent(): ReactElement {
-
+
);
}
diff --git a/src/routes/Assets.tsx b/src/routes/Assets.tsx
index 8029338..37e59eb 100644
--- a/src/routes/Assets.tsx
+++ b/src/routes/Assets.tsx
@@ -55,6 +55,7 @@ import type { AssetGroupCount } from "../components/AssetsGroupNav";
import AssetsTable from "../components/AssetsTable";
import type { AssetRow } from "../components/AssetsTable";
import ImportPreviewDialog from "../components/ImportPreviewDialog";
+import { RouteSlide } from "../components/RouteSlide";
import { useConfirmGate, useHub, type ConfirmRequest } from "../hub/HubContext";
import { useSseEvents } from "../hub/useSseEvents";
@@ -637,7 +638,7 @@ function AssetsInner(): ReactElement {
const rootBase = root === null ? "—" : root.split(/[\\/]/).filter(Boolean).pop() ?? root;
return (
-
+
{/* 对象区:类型分组导航 */}
+
);
}
diff --git a/src/routes/Cards.tsx b/src/routes/Cards.tsx
index ab08fcd..4f4b0ad 100644
--- a/src/routes/Cards.tsx
+++ b/src/routes/Cards.tsx
@@ -43,6 +43,7 @@ import CardBackPreview from "../components/CardBackPreview";
import SliceGrid from "../components/SliceGrid";
import type { SheetMeta, SliceCard } from "../components/SliceGrid";
import CardFacePreview from "../components/CardFacePreview";
+import { RouteSlide } from "../components/RouteSlide";
import { useConfirmGate, useHub } from "../hub/HubContext";
import { useSseEvents } from "../hub/useSseEvents";
@@ -749,7 +750,7 @@ function CardsInner(): ReactElement {
};
return (
-
+
{/* 对象区:牌堆列表(上) + 卡背预览(下) */}
-
+
);
}
diff --git a/src/routes/Code.tsx b/src/routes/Code.tsx
index 37f4fca..be483ad 100644
--- a/src/routes/Code.tsx
+++ b/src/routes/Code.tsx
@@ -27,10 +27,12 @@ import type { TreeNode } from "../components/CodeFileTree";
import CodeDiffView from "../components/CodeDiffView";
import type { DiffEntry } from "../components/CodeDiffView";
import CodeEditor from "../components/CodeEditor";
+import { RouteSlide } from "../components/RouteSlide";
import { useConfirmGate, useHub, type ConfirmRequest } from "../hub/HubContext";
import { useSseEvents } from "../hub/useSseEvents";
import { useJobTracker } from "../hub/useJobTracker";
+import { useDirty } from "../state/DirtyContext";
import { sha256Hex } from "../hub/sha256";
import { isHubError } from "../hub/errors";
@@ -107,6 +109,9 @@ function CodeInner(): ReactElement {
const { events: sseEvents } = useSseEvents();
const { track } = useJobTracker();
const { ask } = useConfirmGate();
+ // 脏通道(UI-4 Stage B1 最小接入):编辑器缓冲的未提交改动上报给全站 store,
+ // App.tsx ① 代码 dot(蓝)与会签栏版本行的未提交数同源;本面照旧只管自己的编辑态
+ const { markDirty, markClean } = useDirty();
// ---- 数据状态 ----
const [root, setRoot] = useState(null);
@@ -232,6 +237,9 @@ function CodeInner(): ReactElement {
const handleSelect = useCallback(
async (guid: string, kind: EntryKind): Promise => {
if (root === null || loading) return;
+ // 脏通道:切换 / 重载都会丢弃编辑器缓冲(本面既有行为),上一个对象的未提交
+ // 标记随之清除;重新加载当前对象即「还原」→ 同样在这条路径上标干净
+ if (activeGuid !== null) markClean(activeGuid);
const entry = diffEntries.find((e) => e.guid === guid && e.kind === kind) ?? null;
setTab("edit");
setActiveGuid(guid);
@@ -260,7 +268,7 @@ function CodeInner(): ReactElement {
setError(e instanceof Error ? e.message : String(e));
}
},
- [root, loading, diffEntries, caps.canReadFiles, client, track],
+ [root, loading, diffEntries, caps.canReadFiles, client, track, activeGuid, markClean],
);
const openEntryInEditor = useCallback(
@@ -270,10 +278,15 @@ function CodeInner(): ReactElement {
[handleSelect],
);
- const handleEditorChange = useCallback((next: string): void => {
- setEditedContent(next);
- setDirty(true);
- }, []);
+ const handleEditorChange = useCallback(
+ (next: string): void => {
+ setEditedContent(next);
+ setDirty(true);
+ // 脏通道:编辑器里有改动(保存 / 还原前)→ 上报当前对象,① 代码 dot 转蓝
+ if (activeGuid !== null) markDirty(activeGuid);
+ },
+ [activeGuid, markDirty],
+ );
// ---- 保存:filesWrite(乐观锁);409 → 冲突条 ----
const handleSave = useCallback(async (): Promise => {
@@ -289,6 +302,8 @@ function CodeInner(): ReactElement {
setOriginalSha256(res.sha256);
setDirty(false);
setConflict(false);
+ // 脏通道:落盘成功 → 该对象的未提交改动清除
+ if (activeGuid !== null) markClean(activeGuid);
await refreshDiff(root);
} catch (e) {
if (isHubError(e) && e.code === "HUB_CONFLICT") {
@@ -299,7 +314,17 @@ function CodeInner(): ReactElement {
} finally {
setBusy(false);
}
- }, [root, activeEntry, originalSha256, editedContent, client, track, refreshDiff]);
+ }, [
+ root,
+ activeEntry,
+ originalSha256,
+ editedContent,
+ client,
+ track,
+ refreshDiff,
+ activeGuid,
+ markClean,
+ ]);
/** 冲突条「强制覆盖」:不带 baseSha256 绕过乐观锁(用户显式选择) */
const handleForceOverwrite = useCallback(async (): Promise => {
@@ -314,13 +339,15 @@ function CodeInner(): ReactElement {
setOriginalSha256(res.sha256);
setDirty(false);
setConflict(false);
+ // 脏通道:强制覆盖同样已落盘 → 清除该对象的未提交改动
+ if (activeGuid !== null) markClean(activeGuid);
await refreshDiff(root);
} catch (e) {
setError(e instanceof Error ? e.message : String(e));
} finally {
setBusy(false);
}
- }, [root, activeEntry, editedContent, client, track, refreshDiff]);
+ }, [root, activeEntry, editedContent, client, track, refreshDiff, activeGuid, markClean]);
// ---- 重新拉取:游戏内 → 工作区,再重 diff ----
const handlePull = useCallback(async (): Promise => {
@@ -426,7 +453,7 @@ function CodeInner(): ReactElement {
};
return (
-
+
{/* 对象区:差异文件树 */}
-
+
);
}
diff --git a/src/routes/Overview.css b/src/routes/Overview.css
new file mode 100644
index 0000000..1a1ba8d
--- /dev/null
+++ b/src/routes/Overview.css
@@ -0,0 +1,164 @@
+/* ============================================================================
+ * ⓪ 总览面样式 — UI-4 Stage A2(首进阶梯)+ Stage B1(路由骨架布局)
+ *
+ * 本文件两块:下半「布局」段 = Stage B1 补的路由骨架(a-deep.html 48-49/68-70/94 行);
+ * 其余是 Stage A2 的「首次进入阶梯」(round-03 §2.6 动效三件套之三,
+ * 参考 ui-design/round-03/candidates/a-deep.html 301-307 行):
+ * 工序章五枚 + 内容块两项,按阅读顺序 translateY(10px) + opacity 0 → 归位,
+ * 延迟阶梯 02/07/12/17/22/26/32。
+ * 内容块的外框/标题(a-deep .ov-blk 的边框与 .bh 头)由各块组件自己负责
+ * (TodoList / MiniFileTree / LayerTiles … 均自带块级外框),本文件的 .ov-blk
+ * 只作动效钩子,不重复画框,避免与组件样式叠成双线。
+ *
+ * ── 类名语义(契约 §6,装配方在 Overview.tsx 施加)──────────────────────────
+ * .ov-enter pre 出场态(translateY(10px) + opacity 0)
+ * .ov-enter-done 移除 pre 态 → 元素的 transition 归位
+ * 装配方用法(推荐:整面一个容器 + useFirstEnter):
+ * const entered = useFirstEnter(); // src/hub/useFirstEnter.ts
+ *
+ *
← .processstamps-stamp 自动错落
+ *
+ *
…
← delay .26s
+ *
…
← delay .32s
+ *
+ *
+ * 元素级用法等价:把 .ov-enter / .ov-enter-done 直接加在 .ov-blk 上即可。
+ * pre 态只落在「工序章 + 内容块」上,不落在容器本身——避免与 的
+ * translateX 滑入叠成两段位移。
+ *
+ * ── 取巧说明 ───────────────────────────────────────────────────────────────
+ * 1) 时长 .4s ease 按 §2.6 第三件套原文取字面量:该套动的时长未令牌化
+ * (§2.6 的 --dur-* 只覆盖遮罩淡入 / 工作面滑入 / 确认门生长),
+ * 阶梯延迟 .02–.32s 同样是字面量;若后续把 .4s 收进令牌(--dur-enter),
+ * 只改本文件这一处。
+ * 2) transition 写在元素本体(不在 .ov-enter 上):若写在 .ov-enter 里,
+ * 换类那一帧 transition 声明会随类一起消失,过渡不产生。
+ * 3) prefers-reduced-motion 由 tokens.css 全局 transition:none 兜底,
+ * 本文件不重复写 media query;此时类切换照常发生,元素直接落终态。
+ * ==========================================================================*/
+
+/* ── 出场元素白名单:工序章五枚 + 内容块两项 ─────────────────────────────────
+ * 类名有变时只改这一组选择器(.processstamps-stamp 见 components/ProcessStamps.tsx,
+ * .ov-blk 为总览面块容器约定名)。 */
+.processstamps-stamp,
+.ov-blk {
+ transition:
+ transform .4s ease,
+ opacity .4s ease;
+}
+
+/* ── 阶梯延迟:阅读顺序,与 round-03 逐字一致 ────────────────────────────── */
+.processstamps-stamp:nth-child(1) {
+ transition-delay: 0.02s;
+}
+.processstamps-stamp:nth-child(2) {
+ transition-delay: 0.07s;
+}
+.processstamps-stamp:nth-child(3) {
+ transition-delay: 0.12s;
+}
+.processstamps-stamp:nth-child(4) {
+ transition-delay: 0.17s;
+}
+.processstamps-stamp:nth-child(5) {
+ transition-delay: 0.22s;
+}
+
+/* 内容块两项:.26 / .32s(嵌套在列容器里时各为其父的第一子 → 同为 .26s,
+ * 与 a-deep 的 .ov-blk:nth-child(1)/(2)写法一致) */
+.ov-blk:nth-child(1) {
+ transition-delay: 0.26s;
+}
+.ov-blk:nth-child(2) {
+ transition-delay: 0.32s;
+}
+
+/* ── pre 态(translateY(10px) + opacity 0)────────────────────────────────
+ * 容器式:祖先带 .ov-enter 且尚未标 done;
+ * 元素式:元素自身带 .ov-enter 且尚未标 done(此时元素必是白名单成员)。 */
+.ov-enter:not(.ov-enter-done) .processstamps-stamp,
+.ov-enter:not(.ov-enter-done) .ov-blk,
+.processstamps-stamp.ov-enter:not(.ov-enter-done),
+.ov-blk.ov-enter:not(.ov-enter-done) {
+ transform: translateY(10px);
+ opacity: 0;
+}
+
+/* ============================================================================
+ * 布局 — UI-4 Stage B1 路由骨架(a-deep.html 48-49 / 68-70 / 94 行)
+ *
+ * 结构(Overview.tsx 组装):
+ * .overview(横排)├ .ov-main(flex:1)= .ov-stamps + .ov-grid 双列
+ * └ .ov-side(290px 定宽)
+ * 线框分隔:右栏左缘 1px dashed --wdim(分栏用虚线,§2.4);块外框由各展示组件自管
+ * (TodoList / MiniFileTree / LayerTiles 自带 1px --wdim 框),.ov-blk 只作动效钩子,
+ * .ov-ev 只给「事件流」这一块补同款框(EventFlow 自带头部,无自有外框)。
+ * 全引用 tokens.css 变量;290px 栏宽与 a-deep 逐字一致(同 Agent.css 的 320px 列宽)。
+ * ==========================================================================*/
+
+.overview {
+ display: flex;
+ width: 100%;
+ height: 100%;
+ overflow: hidden;
+}
+
+.ov-main {
+ flex: 1;
+ min-width: 0;
+ padding: var(--sp-5) var(--sp-6); /* a-deep:20px 24px */
+ display: flex;
+ flex-direction: column;
+}
+
+/* 工序章容器:只作阶梯动效钩子 + 章面与下部的间距(a-deep .stamps margin 0 0 18px);
+ * flex:none —— 主轴(纵向)压缩不得压扁章面,余量归 .ov-grid */
+.ov-stamps {
+ flex: none;
+ margin-bottom: var(--sp-4);
+}
+
+/* 下部两栏填实:左工作区 / 右事件流(1fr 1fr) */
+.ov-grid {
+ flex: 1;
+ display: grid;
+ grid-template-columns: 1fr 1fr;
+ gap: var(--sp-4);
+ min-height: 0;
+}
+
+.ov-col {
+ display: flex;
+ flex-direction: column;
+ min-height: 0;
+}
+
+/* 同列两块之间的间距(a-deep 左列第二块 margin-top:14px → 取最近的间距令牌) */
+.ov-col > .ov-blk + .ov-blk {
+ margin-top: var(--sp-3);
+}
+
+/* 事件流块:吃满右列高度(.eventflow 自带 height:100% + 内部滚动),框同左列两块 */
+.ov-ev {
+ flex: 1;
+ min-height: 0;
+ display: flex;
+ flex-direction: column;
+ border: var(--border-w) solid var(--wdim);
+ background: var(--bp);
+ overflow: hidden;
+}
+
+/* 右栏:290px 定宽(a-deep 290px,不随窗口伸缩),左缘虚线分栏 */
+.ov-side {
+ width: 290px;
+ flex: none;
+ padding: var(--sp-4);
+ border-left: var(--border-w) dashed var(--wdim);
+ background: var(--bp); /* 盖住 canvas 的 42px 网格底纹(a-deep .ov-side 同) */
+ display: flex;
+ flex-direction: column;
+ gap: var(--sp-4);
+ overflow-y: auto;
+}
+
diff --git a/src/routes/Overview.tsx b/src/routes/Overview.tsx
index bbb0282..584bc58 100644
--- a/src/routes/Overview.tsx
+++ b/src/routes/Overview.tsx
@@ -1,16 +1,102 @@
/**
- * ⓪ 总览面 — 占位(UI-4 填充:工序章 + 待办 + 迷你文件树 + 四面状态磁贴)
+ * ⓪ 总览面 — UI-4 Stage B1 路由组装(round-03 §3.1 三区骨架 + a-deep.html 368-425)
+ *
+ * 职责:把 Stage A 展示组件组装为完整总览面——
+ * 左主区(.ov-main): 工序章 横贯顶部
+ * + .ov-grid 双列:左列 / ,右列
+ * 右栏(.ov-side,290px): 四面状态磁贴
+ * 动效(§2.6 三件套之二/之三):
+ * - 工作面滑入:根元素由 包装(替掉原 );
+ * - 首次进入阶梯:useFirstEnter() 翻转 .ov-enter → .ov-enter-done(delay 阶梯在
+ * ./Overview.css,pre 态只落在「工序章容器 + .ov-grid」两个块上,不落在容器本体,
+ * 免与 RouteSlide 的 translateX 叠成两段位移)。
+ *
+ * 数据来源(受控):OverviewData 由 AppInner 的 useOverviewData 单点派生后经 props 传入。
+ * 本面不自己调 useOverviewData——该 hook 有模块级结果缓存但无在途去重,App 与路由同时
+ * 调用会在冷启动并发发两次 pullScripts(覆盖工作区)+ 两次 testRun(在真实游戏内跑测试),
+ * 详见 src/App.tsx 文件头「单点」说明。本面只读:SSE 事件流经 useSseEvents()(Context 订阅,
+ * 无副作用),迷你文件树经 Stage A 的 deriveMiniTree(root)(与 ①代码面同一份差异缓存)。
+ * 视图内跳转:待办行 / 四面磁贴 / 迷你文件树行 → onNavigate(layer)(App.tsx 的 setActiveLayer)。
*/
+import type { ReactElement } from "react";
+
+import ProcessStamps from "../components/ProcessStamps";
+import TodoList from "../components/TodoList";
+import MiniFileTree from "../components/MiniFileTree";
+import LayerTiles from "../components/LayerTiles";
+import EventFlow from "../components/EventFlow";
+import { RouteSlide } from "../components/RouteSlide";
+
+import { useSseEvents } from "../hub/useSseEvents";
+import { useFirstEnter } from "../hub/useFirstEnter";
+import { deriveMiniTree, type LayerId, type OverviewData } from "../state/processStamps";
+
import "./routes.css";
+import "./Overview.css";
+
+export interface OverviewProps {
+ /** ⓪总览聚合数据(AppInner 的 useOverviewData 单点派生;本面纯渲染) */
+ data: OverviewData;
+ /** 已注册图包 root(迷你文件树数据源;null = 未注册图包,deriveMiniTree 给空态 note) */
+ root: string | null;
+ /** 块内跳转(待办行 / 四面磁贴 / 迷你文件树)→ 切换工作面 */
+ onNavigate(layer: LayerId): void;
+}
+
+export default function Overview(props: OverviewProps): ReactElement {
+ const { data, root, onNavigate } = props;
+
+ // SSE 事件流(②代理面同一订阅:App.tsx 顶层 SseProvider,本面只消费)
+ const { events, state, clear } = useSseEvents();
+ // 首进阶梯开关:false = 出场态(.ov-enter),双 rAF 后 true(.ov-enter-done)
+ const entered = useFirstEnter();
+ // 迷你文件树:与 ①代码面同源(Stage A 差异缓存派生,组件不调 hub)
+ const tree = deriveMiniTree(root);
+
+ const ladder = entered ? "ov-enter-done" : "ov-enter";
-export default function Overview() {
return (
-
-
-
⓪
-
总览
-
本面内容于 UI-4 窗口填充(工序章 / 待办 / 迷你文件树)
+
+
+
+ {/* 工序章:总览唯一主角,横贯顶部(容器只作阶梯动效钩子) */}
+
+
+ {/* 下部填实:左工作区(待办 + 文件树) / 右事件流 */}
+
+
+
+ {/* .ov-ev 只补块框与剩余高度:.eventflow 自带头部(标题 + ● 存活点 + 清空)
+ 与内部滚动,不另造第二套外壳 */}
+
+
+
+
+
+
+
+ {/* 右栏:四面状态磁贴(290px 定宽,虚线分栏) */}
+
-
+
);
}
diff --git a/src/routes/routes.css b/src/routes/routes.css
index 462dad8..28739c1 100644
--- a/src/routes/routes.css
+++ b/src/routes/routes.css
@@ -28,19 +28,18 @@
font-family: var(--sans);
}
-/* 工作面切换动画:translateX(56px) + opacity 滑入(§2.6) */
+/* 工作面切换动画:translateX(var(--dist-move)) + opacity 滑入(§2.6 第二件套)
+ * transition 驱动(不用 keyframes)以便截图工具抓到过渡帧;
+ * 初始 pre 态 .route-slide-pre 由
挂载时带上,双 rAF 后移除并触发过渡。
+ * 位移由 .frame-canvas{overflow:hidden} 兜住,不产生横向滚动。 */
.route-slide {
height: 100%;
- animation: route-slide-in var(--dur-move) var(--ease-out) both;
+ transition:
+ transform var(--dur-move) var(--ease-out),
+ opacity var(--dur-move) var(--ease-out);
}
-@keyframes route-slide-in {
- from {
- transform: translateX(var(--dist-move));
- opacity: 0;
- }
- to {
- transform: translateX(0);
- opacity: 1;
- }
+.route-slide-pre {
+ transform: translateX(var(--dist-move));
+ opacity: 0;
}
diff --git a/src/state/DirtyContext.tsx b/src/state/DirtyContext.tsx
new file mode 100644
index 0000000..e355ab1
--- /dev/null
+++ b/src/state/DirtyContext.tsx
@@ -0,0 +1,123 @@
+/**
+ * DirtyContext — UI-4 Stage A3「状态引擎 + 脏通道」的脏通道半边
+ *
+ * 职责:全站「未提交改动」GUID 集合 store(React Context + useReducer,仿
+ * ./DeadLinkContext.tsx + ./deadLinkReducer.ts 范式)。①代码面在编辑器里改动 /
+ * 保存后把对应对象 guid 上报进来,App.tsx 读 dirtyGuids.size 驱动 ① 代码面
+ * LayerNav 圆点(>0 = red「有未提交改动」),后续要更多消费方也只是读同一集合。
+ *
+ * 关键设计(与 DeadLinkContext 对齐的约定):
+ * - 唯一实例挂 App.tsx 顶层(HubContext.Provider → ConfirmGateProvider → SseProvider
+ * → DeadLinkProvider → DirtyProvider → AppInner;路由不自行挂 Provider);
+ * - 状态机在本文件内(dirtyReducer / DirtyState / DirtyAction 均导出),状态不可变:
+ * Set 只在变更时新建,未变更(重复 markDirty / markClean 不存在的 guid)返回原引用,
+ * 消费方按引用即可判断「有没有变化」,也不会被空操作触发多余重渲染;
+ * - dirtyGuids 对外类型 ReadonlySet:只读视图,变更只能经 reducer,
+ * 杜绝旁路写;
+ * - markDirty / markClean / clearDirty 经 useCallback 稳定引用:消费方
+ * memo / effect 依赖安全;
+ * - 空字符串 guid 静默忽略(全局脚本/UI 的合法 guid 是 "-1",不是 "");
+ * - useDirty 在 Provider 外使用即 throw(useHub / useConfirmGate / useDeadLinks 同款防御)。
+ *
+ * 说明:任务清单只允许写本文件,故 reducer 不像 deadLinkReducer 那样单列一个文件,
+ * 但导出形状(reducer + 初始态 + State/Action 类型)与 DeadLinkContext 一致。
+ */
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useMemo,
+ useReducer,
+ type JSX,
+ type ReactNode,
+} from "react";
+
+/** 脏文件 store 状态 */
+export interface DirtyState {
+ /** 已改动未提交的对象 GUID 集合(只读;变更经 reducer) */
+ dirtyGuids: ReadonlySet;
+}
+
+/** 脏文件 store 动作 */
+export type DirtyAction =
+ | { type: "dirty"; guid: string }
+ | { type: "clean"; guid: string }
+ | { type: "clear" };
+
+/** 初始状态:无脏文件 */
+export const initialDirtyState: DirtyState = {
+ dirtyGuids: new Set(),
+};
+
+/**
+ * 脏文件 store reducer(纯函数)。
+ * 未产生变化的动作返回原 state 引用(不新建 Set、不触发重渲染)。
+ */
+export function dirtyReducer(state: DirtyState, action: DirtyAction): DirtyState {
+ switch (action.type) {
+ case "dirty": {
+ if (action.guid === "" || state.dirtyGuids.has(action.guid)) return state;
+ const next = new Set(state.dirtyGuids);
+ next.add(action.guid);
+ return { dirtyGuids: next };
+ }
+ case "clean": {
+ if (!state.dirtyGuids.has(action.guid)) return state;
+ const next = new Set(state.dirtyGuids);
+ next.delete(action.guid);
+ return { dirtyGuids: next };
+ }
+ case "clear":
+ return state.dirtyGuids.size === 0 ? state : { dirtyGuids: new Set() };
+ }
+}
+
+/** DirtyContext 消费值(契约 §2) */
+export interface DirtyContextValue {
+ /** 已改动未提交的对象 GUID 集合(只读) */
+ dirtyGuids: ReadonlySet;
+ /** 上报某对象有未提交改动 */
+ markDirty(guid: string): void;
+ /** 上报某对象已回到干净状态(保存 / 写回 / 重新拉取后) */
+ markClean(guid: string): void;
+ /** 清空(重新拉取 / 切换图包) */
+ clearDirty(): void;
+}
+
+const DirtyContext = createContext(null);
+
+/** 全站唯一脏文件 Provider(App.tsx 顶层挂载一次) */
+export function DirtyProvider(props: { children: ReactNode }): JSX.Element {
+ const { children } = props;
+
+ const [state, dispatch] = useReducer(dirtyReducer, initialDirtyState);
+
+ // 动作引用稳定(useCallback []):消费方 memo / effect 依赖安全
+ const markDirty = useCallback((guid: string): void => {
+ dispatch({ type: "dirty", guid });
+ }, []);
+ const markClean = useCallback((guid: string): void => {
+ dispatch({ type: "clean", guid });
+ }, []);
+ const clearDirty = useCallback((): void => {
+ dispatch({ type: "clear" });
+ }, []);
+
+ const value = useMemo(
+ () => ({ dirtyGuids: state.dirtyGuids, markDirty, markClean, clearDirty }),
+ [state.dirtyGuids, markDirty, markClean, clearDirty],
+ );
+
+ return {children};
+}
+
+/** 消费脏文件 store;必须在 内使用(App.tsx 顶层挂载一次) */
+export function useDirty(): DirtyContextValue {
+ const v = useContext(DirtyContext);
+ if (v === null) {
+ throw new Error(
+ "useDirty() 必须在 内使用(App.tsx 顶层挂载一次)",
+ );
+ }
+ return v;
+}
diff --git a/src/state/processStamps.ts b/src/state/processStamps.ts
new file mode 100644
index 0000000..736fb50
--- /dev/null
+++ b/src/state/processStamps.ts
@@ -0,0 +1,826 @@
+/**
+ * processStamps — UI-4 Stage A3「状态引擎 + 脏通道」的状态引擎半边
+ *
+ * 唯一事实源:ui-design/round-03/UI施工方案.md §4.3(工序章)/ §4.4(会签栏)/
+ * §3.1(⓪总览工作面)+ UI-4 锁定决策 2「出厂章与 SignBlock checks 同源」。
+ *
+ * 本模块三块职责:
+ * 1. `useOverviewData(src)`:把 hub(GET /v1/packs、POST /v1/scripts/pull + /v1/diff、
+ * POST /v1/test/run)+ 全站死链 store(消费方经 src.deadUrls 传入)+ SSE 事件数组
+ * (src.sseEvents 传入)折算成 ⓪总览需要的 OverviewData(五章状态 / 待办行 / 四面磁贴)。
+ * 2. `deriveMiniTree(root)`:⓪总览「工作区」迷你文件树的数据源(A1 版 MiniFileTreeProps
+ * 的 nodes + note),与 ①代码面的 diff 同源(同一份条目的模块级缓存)。
+ * 3. `deriveSignBlock(data)`:§4.4 会签栏交付清单数据源(出厂行与出厂章同源)。
+ *
+ * 五章状态推导(契约 §1 语义表,优先级 alert > doing > done > todo):
+ * 拉取 pull:root=null → todo「未注册」|请求中 → doing「拉取中…」|失败 → alert「拉取失败」
+ * |成功且有差异 → doing「N 件待写回」|成功且无差异 → done「✓ 已同步」
+ * 切片 slice:有切片活动 → doing「进行中」|否则 → todo「未开始」
+ * 拼版 compose:拉取未成功 → todo「待拉取」|死链 > 0 → alert「N 死链」|否则 → done「✓ 无死链」
+ * 校样 proof:root=null → todo「未注册」|请求中 → doing「校样中…」|通过 → done「N/N ✓」
+ * |有用例未过 / 请求失败 → alert
+ * 出厂 ship:root=null → todo「未注册」|拉取未成功 → todo「待拉取」
+ * |有件待签 → todo「N 件待签」|全部签出 → done「✓ 已会签」
+ *
+ * 实测偏差与工程选择(逐条与任务书/契约对齐后的判断,供下游与验收窗口核对):
+ * - HubEvent 的导入路径:契约写「类型从 ../hub/useSseEvents 导入」,但 useSseEvents.ts
+ * 只是 `import type { HubEvent } from "./sse"`(src/hub/useSseEvents.ts:24),并未 re-export,
+ * 故此处从真正的定义处 `../hub/sse` 导入(同一类型身份,消费方传 useSseEvents().events 无需改动)。
+ * - 切片活动的检测:hub 的 POST /v1/deck/slice 是纯本地文件操作(tts-toolkit
+ * src/hub/control.ts:1276-1289 → sliceAtlas),不发任何 SSE 帧;SSE 只转发 TTS 入站
+ * messageID 1/2/3/4/6/7(src/hub/sse.ts:14-20)。因此契约的「SSE 会话期有 slice 活动」
+ * 没有直接信号:本模块实现为 (a) 可选入参 src.sliceActive(消费方可显式上报,
+ * 追加字段,非契约必需)(b) SSE 文案线索尽力检测(见 hasSliceActivity),
+ * 两者都无 → todo「未开始」(诚实简化)。
+ * - cardCount / assetCount 恒 null:注册表(.registry.yaml)实际带 PackStats
+ * (tts-toolkit src/pack/registry.ts:103-115)与卡牌数,但按任务书本窗口不接③④面数据源,
+ * 保持 null(LayerTiles 渲染为「—」);素材行数无任何查询路由,确实不可得。
+ * - packVersion:.registry.yaml(PackEntry)与 pack.yaml 都没有 version 字段
+ * (src/pack/registry.ts:110-126、src/pack/packyaml.ts:105-135),故恒为 NO_VERSION「—」;
+ * 此处保留对注册表条目可选 version 字段的前瞻探测,未来加字段即自动生效。
+ * - 「写回游戏成功」在 OverviewSource 里没有直接信号:出厂章以「拉取成功且 diff=0
+ * (工作区 == 游戏内)」等价于「全部签出」;SSE 的 saved(GameSaved)事件为潜在线索,
+ * 刻意不用于避免误判(用户手动存档也会发)。
+ * - 失败不写结果缓存,但记 30s 节流窗(pullErrorAt / proofErrorAt):pull 会覆盖工作区、
+ * testRun 会在真实游戏内跑测试,反复切换 ⓪ 面不应反复触发。
+ * - 拉取与校样串行执行:两条路由都经 hub 已绑定的编辑器端口 39998
+ * (tts-toolkit src/hub/control.ts:1342-1465 注入 daemon.server),并发交错风险不值当。
+ *
+ * 受控:本模块只读 hub 与入参,不写任何组件状态;root 为 null 时不发任何 hub 请求。
+ */
+import { useEffect, useMemo, useState } from "react";
+import { useHub } from "../hub/HubContext";
+import type { HubEvent } from "../hub/sse";
+import type { TreeNode } from "../components/CodeFileTree";
+import type { SignCheck } from "../components/SignBlock";
+
+// ───────────────────────────── 契约类型(逐字) ─────────────────────────────
+
+export type StampId = "pull" | "slice" | "compose" | "proof" | "ship";
+export type StampStatus = "done" | "doing" | "alert" | "todo";
+
+export interface StampState {
+ id: StampId;
+ name: string;
+ status: StampStatus;
+ note: string;
+}
+
+export type LayerId = "overview" | "code" | "agent" | "cards" | "assets";
+
+export interface TodoItem {
+ mark: string;
+ color: "red" | "blue" | "amber" | "ok";
+ text: string;
+ target: LayerId;
+}
+
+export interface OverviewData {
+ /** 恒 5 个,顺序 拉取→切片→拼版→校样→出厂 */
+ stamps: StampState[];
+ todos: TodoItem[];
+ /** 与游戏内不同/未提交的文件数(①代码;拉取未知/失败时为 0) */
+ diffCount: number;
+ /** 死链总数(deadUrls.size,③④同源) */
+ deadCount: number;
+ /** 待会签件数(≈ diffCount) */
+ pendingSign: number;
+ /** SSE 事件数(②代理流水) */
+ jobCount: number;
+ /** 卡牌总数(③,未知为 null——见文件头) */
+ cardCount: number | null;
+ /** 素材行数(④,未知为 null——见文件头) */
+ assetCount: number | null;
+ /** 已注册图包名(无则 "(未注册图包)") */
+ packName: string;
+ /** 图包版本(无则 "—") */
+ packVersion: string;
+}
+
+export interface OverviewSource {
+ deadUrls: ReadonlySet;
+ sseEvents: HubEvent[];
+ /** 图包根路径;null 表示无已注册图包(降级模式,不发起 hub 调用)。 */
+ root: string | null;
+ /**
+ * 可选:切片活动显式上报(追加字段,非契约必需)。
+ * hub 的 /v1/deck/slice 不发 SSE(见文件头),消费方(如③卡牌面切片进行中)可置 true
+ * 让「切片」章进入 doing;缺省走 SSE 文案线索。
+ */
+ sliceActive?: boolean;
+}
+
+/** 无已注册图包时的图包名(契约「无则」值) */
+export const NO_PACK_NAME = "(未注册图包)";
+/** 无版本来源时的版本占位(契约「无则」值) */
+export const NO_VERSION = "—";
+
+// ───────────────────────────── 内部状态与缓存 ─────────────────────────────
+
+/** 拉取结果:成功带差异条目数;失败(含 pull/diff 任一步失败)无数据 */
+type PullOutcome = { ok: true; diffEntries: number } | { ok: false };
+
+/** 校样结果:ok=用例全过;notPassed=未通过数(failed+errored+bailed);notPassed=null 表示请求/解析失败 */
+type ProofOutcome = { ok: true; passed: number; notPassed: number } | { ok: false; notPassed: number | null };
+
+/** 契约 §1 的模块级结果缓存(仅内存) */
+export interface StampCacheEntry {
+ pull?: { diffEntries: number };
+ proof?: { passed: number; failed: number };
+ /** 追加:上次拉取失败的补充标记(供 30s 节流 + 重挂载后仍显示 alert),非契约字段 */
+ pullErrorAt?: number;
+ /** 追加:上次校样请求失败的补充标记(同上) */
+ proofErrorAt?: number;
+}
+
+/** 结果缓存:root → 拉取/校样结果(免重复请求) */
+const cache = new Map();
+/** 迷你文件树缓存:root → diff 条目派生的 TreeNode[](与 ①代码面同源) */
+const treeCache = new Map();
+/** 图包元信息缓存:metaKey(root) → {name, version}(会话级) */
+const packMetaCache = new Map();
+
+/** 失败节流窗(ms):窗口内重挂载不重发 hub 请求,直接从缓存的失败标记推导 alert */
+const RETRY_AFTER_MS = 30_000;
+
+/** 迷你文件树最多渲染行数(⓪总览块高有限;note 仍报总差异数) */
+const MINI_TREE_MAX = 12;
+
+interface EngineState {
+ root: string | null;
+ pull: PullOutcome | null;
+ proof: ProofOutcome | null;
+ packName: string;
+ packVersion: string;
+}
+
+interface PackMeta {
+ /** 注册表条目 dir(一级子目录名,hub 路由直接接受,与 ①代码面同口径) */
+ dir: string;
+ name: string;
+ version: string;
+}
+
+// ───────────────────────────── 纯工具 ─────────────────────────────
+
+/** 路径归一:斜杠统一 + 小写(Windows 比较用;只做展示级匹配,不做真实路径解析) */
+function normalizePath(p: string): string {
+ return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+
+/** 注册表条目在缓存里的 key */
+function metaKey(rootish: string): string {
+ return normalizePath(rootish);
+}
+
+/** root 兜底显示名:路径最后一段(注册表查不到时的诚实兜底,避免谎报「未注册」) */
+function packNameFallback(root: string): string {
+ const parts = root.split(/[\\/]+/).filter((s) => s !== "");
+ const last = parts[parts.length - 1];
+ return last !== undefined && last !== "" ? last : root;
+}
+
+/** 失败节流判断:窗口内不重发 */
+function isThrottled(root: string, kind: "pull" | "proof"): boolean {
+ const entry = cache.get(root);
+ const at = kind === "pull" ? entry?.pullErrorAt : entry?.proofErrorAt;
+ return at !== undefined && Date.now() - at < RETRY_AFTER_MS;
+}
+
+/** 合并式写缓存(成功清除失败标记:显式 undefined 覆盖) */
+function patchCache(root: string, patch: Partial): void {
+ cache.set(root, { ...(cache.get(root) ?? {}), ...patch });
+}
+
+/** 由缓存/空态推导引擎基线(root 变更首帧同步渲染,避免闪上一图包的旧值) */
+function seedState(root: string | null): EngineState {
+ if (root === null) {
+ return {
+ root: null,
+ pull: null,
+ proof: null,
+ packName: NO_PACK_NAME,
+ packVersion: NO_VERSION,
+ };
+ }
+ const entry = cache.get(root);
+ const meta = packMetaCache.get(metaKey(root));
+ const pull: PullOutcome | null =
+ entry?.pull !== undefined
+ ? { ok: true, diffEntries: entry.pull.diffEntries }
+ : isThrottled(root, "pull")
+ ? { ok: false }
+ : null;
+ const proof: ProofOutcome | null =
+ entry?.proof !== undefined
+ ? { ok: entry.proof.failed === 0, passed: entry.proof.passed, notPassed: entry.proof.failed }
+ : isThrottled(root, "proof")
+ ? { ok: false, notPassed: null }
+ : null;
+ return {
+ root,
+ pull,
+ proof,
+ packName: meta?.name ?? packNameFallback(root),
+ packVersion: meta?.version ?? NO_VERSION,
+ };
+}
+
+/** 5 章名称(id → 仿宋大字) */
+const STAMP_NAMES: Record = {
+ pull: "拉取",
+ slice: "切片",
+ compose: "拼版",
+ proof: "校样",
+ ship: "出厂",
+};
+
+/** 工序章顺序:拉取 → 切片 → 拼版 → 校样 → 出厂 */
+const STAMP_ORDER: StampId[] = ["pull", "slice", "compose", "proof", "ship"];
+
+/**
+ * 由四组标量推导五章(纯函数,见文件头语义表)。导出供验收窗口离线核对语义表;
+ * 组件侧只经 useOverviewData 消费。
+ */
+export function deriveStamps(args: {
+ root: string | null;
+ pull: PullOutcome | null;
+ proof: ProofOutcome | null;
+ deadCount: number;
+ sliceActive: boolean;
+ pendingSign: number;
+}): StampState[] {
+ const { root, pull, proof, deadCount, sliceActive, pendingSign } = args;
+
+ // 拉取
+ let pullStatus: StampStatus;
+ let pullNote: string;
+ if (root === null) {
+ pullStatus = "todo";
+ pullNote = "未注册";
+ } else if (pull === null) {
+ pullStatus = "doing";
+ pullNote = "拉取中…";
+ } else if (!pull.ok) {
+ pullStatus = "alert";
+ pullNote = "拉取失败";
+ } else if (pull.diffEntries > 0) {
+ pullStatus = "doing";
+ pullNote = `${pull.diffEntries} 件待写回`;
+ } else {
+ pullStatus = "done";
+ pullNote = "✓ 已同步";
+ }
+ const pullDone = pull !== null && pull.ok;
+
+ // 切片(见文件头:无历史查询路由,只认会话内活动)
+ const sliceStatus: StampStatus = sliceActive ? "doing" : "todo";
+ const sliceNote = sliceActive ? "进行中" : "未开始";
+
+ // 拼版(死链来自全站死链 store,与 ③④ 面同源)
+ let composeStatus: StampStatus;
+ let composeNote: string;
+ if (!pullDone) {
+ composeStatus = "todo";
+ composeNote = "待拉取";
+ } else if (deadCount > 0) {
+ composeStatus = "alert";
+ composeNote = `${deadCount} 死链`;
+ } else {
+ composeStatus = "done";
+ composeNote = "✓ 无死链";
+ }
+
+ // 校样
+ let proofStatus: StampStatus;
+ let proofNote: string;
+ if (root === null) {
+ proofStatus = "todo";
+ proofNote = "未注册";
+ } else if (proof === null) {
+ proofStatus = "doing";
+ proofNote = "校样中…";
+ } else if (proof.ok) {
+ proofStatus = "done";
+ proofNote = `${proof.passed}/${proof.passed + proof.notPassed} ✓`;
+ } else if (proof.notPassed !== null && proof.notPassed > 0) {
+ proofStatus = "alert";
+ proofNote = `${proof.notPassed} 未过`;
+ } else {
+ proofStatus = "alert";
+ proofNote = "校样失败";
+ }
+
+ // 出厂(待签件数 ≈ diffCount;「全部签出」= 拉取成功且无差异)
+ let shipStatus: StampStatus;
+ let shipNote: string;
+ if (root === null) {
+ shipStatus = "todo";
+ shipNote = "未注册";
+ } else if (!pullDone) {
+ shipStatus = "todo";
+ shipNote = "待拉取";
+ } else if (pendingSign > 0) {
+ shipStatus = "todo";
+ shipNote = `${pendingSign} 件待签`;
+ } else {
+ shipStatus = "done";
+ shipNote = "✓ 已会签";
+ }
+
+ const byId: Record = {
+ pull: { status: pullStatus, note: pullNote },
+ slice: { status: sliceStatus, note: sliceNote },
+ compose: { status: composeStatus, note: composeNote },
+ proof: { status: proofStatus, note: proofNote },
+ ship: { status: shipStatus, note: shipNote },
+ };
+
+ return STAMP_ORDER.map((id) => ({
+ id,
+ name: STAMP_NAMES[id],
+ status: byId[id].status,
+ note: byId[id].note,
+ }));
+}
+
+/**
+ * 待办行(符号 + 色彩纪律:✗ 红=错误/死链 ⇄ 红=与游戏内不同 ✂ 蓝=进行中 ⬆ 琥珀=待会签)。
+ * 导出供验收窗口离线核对;组件侧只经 useOverviewData 消费。
+ */
+export function deriveTodos(args: {
+ pull: PullOutcome | null;
+ deadCount: number;
+ sliceActive: boolean;
+ pendingSign: number;
+}): TodoItem[] {
+ const { pull, deadCount, sliceActive, pendingSign } = args;
+ const todos: TodoItem[] = [];
+
+ if (deadCount > 0) {
+ todos.push({
+ mark: "✗",
+ color: "red",
+ text: `${deadCount} 个素材死链待替换`,
+ target: "assets",
+ });
+ }
+ if (pull !== null && !pull.ok) {
+ todos.push({
+ mark: "✗",
+ color: "red",
+ text: "拉取失败,去 ① 代码重试",
+ target: "code",
+ });
+ }
+ const diff = pull !== null && pull.ok ? pull.diffEntries : 0;
+ if (diff > 0) {
+ todos.push({
+ mark: "⇄",
+ color: "red",
+ text: `${diff} 个对象与游戏内不同`,
+ target: "code",
+ });
+ }
+ if (sliceActive) {
+ todos.push({
+ mark: "✂",
+ color: "blue",
+ text: "切片进行中",
+ target: "cards",
+ });
+ }
+ if (pendingSign > 0) {
+ // 会签动作在右下常驻会签栏(不是某个工作面)→ target 取 ⓪ 总览为最近落点
+ todos.push({
+ mark: "⬆",
+ color: "amber",
+ text: `${pendingSign} 件待会签(右下会签栏)`,
+ target: "overview",
+ });
+ }
+ return todos;
+}
+
+// ───────────────────────────── hub 响应解析(容错) ─────────────────────────────
+
+interface DiffEntryLite {
+ guid: string;
+ name: string;
+ kind: "script" | "ui";
+ status: "added" | "modified" | "deleted";
+}
+
+/** 扩展名 → 对象类别(契约 §5:.lua→script / .xml→ui) */
+function kindFromName(name: string): "script" | "ui" {
+ return name.toLowerCase().endsWith(".xml") ? "ui" : "script";
+}
+
+/** POST /v1/diff 响应 → 条目数组(hub 返回 { entries, added, modified, deleted }) */
+function readDiffEntries(res: unknown): DiffEntryLite[] {
+ const entries = (res as { entries?: unknown }).entries;
+ if (!Array.isArray(entries)) return [];
+ const out: DiffEntryLite[] = [];
+ for (const raw of entries) {
+ if (typeof raw !== "object" || raw === null) continue;
+ const guid = (raw as { guid?: unknown }).guid;
+ const name = (raw as { name?: unknown }).name;
+ const kind = (raw as { kind?: unknown }).kind;
+ const status = (raw as { status?: unknown }).status;
+ if (typeof guid !== "string" || typeof name !== "string") continue;
+ out.push({
+ guid,
+ name,
+ // hub 的分类为准;缺失时按契约 §5 的扩展名规则兜底
+ kind: kind === "script" || kind === "ui" ? kind : kindFromName(name),
+ status:
+ status === "added" || status === "modified" || status === "deleted"
+ ? status
+ : "modified",
+ });
+ }
+ return out;
+}
+
+/** diff 条目 → 迷你文件树节点(①代码面同一份条目形状) */
+function toTreeNodes(entries: DiffEntryLite[]): TreeNode[] {
+ return entries.map(
+ (e): TreeNode => ({
+ name: e.name,
+ guid: e.guid,
+ kind: e.kind,
+ status: e.status,
+ }),
+ );
+}
+
+/** POST /v1/test/run 响应(RunReport)→ { passed, notPassed };非 RunReport 形状返回 null */
+function readRunReport(res: unknown): { passed: number; notPassed: number } | null {
+ if (typeof res !== "object" || res === null) return null;
+ const r = res as {
+ passed?: unknown;
+ failed?: unknown;
+ errored?: unknown;
+ bailed?: unknown;
+ };
+ if (r.passed === undefined && r.failed === undefined && r.errored === undefined) {
+ return null; // 缺 results/total 之外的三个计数即认为不是 RunReport
+ }
+ const num = (v: unknown): number =>
+ typeof v === "number" && Number.isFinite(v) ? v : 0;
+ // 未通过数 = 断言失败 + 执行错误 + 提前中止(任一非 0 都不算「校样通过」)
+ return {
+ passed: num(r.passed),
+ notPassed: num(r.failed) + num(r.errored) + num(r.bailed),
+ };
+}
+
+/** GET /v1/packs 响应(.registry.yaml)→ 条目数组 */
+function readPackMetas(res: unknown): PackMeta[] {
+ const packs = (res as { packs?: unknown }).packs;
+ if (!Array.isArray(packs)) return [];
+ const out: PackMeta[] = [];
+ for (const p of packs) {
+ if (typeof p !== "object" || p === null) continue;
+ const dir = (p as { dir?: unknown }).dir;
+ if (typeof dir !== "string" || dir === "") continue;
+ const name = (p as { name?: unknown }).name;
+ // 前瞻探测:当前 .registry.yaml 的 PackEntry 无 version 字段(严格 schema),
+ // 未来若加入即自动生效,否则恒 NO_VERSION
+ const version = (p as { version?: unknown }).version;
+ out.push({
+ dir,
+ name: typeof name === "string" && name !== "" ? name : packNameFallback(dir),
+ version:
+ typeof version === "string" && version !== "" ? version : NO_VERSION,
+ });
+ }
+ return out;
+}
+
+/** 注册表条目匹配 root:dir 是一级子目录名,root 可能是其完整路径 */
+function findPackMeta(metas: PackMeta[], root: string): PackMeta | null {
+ const target = normalizePath(root);
+ for (const meta of metas) {
+ const dir = normalizePath(meta.dir);
+ if (target === dir || (dir !== "" && target.endsWith(`/${dir}`))) return meta;
+ }
+ return null;
+}
+
+/** SSE 文案线索(尽力而为,见文件头):切片活动检测 */
+function hasSliceActivity(events: HubEvent[]): boolean {
+ for (const e of events) {
+ const msg = e.msg.toLowerCase();
+ if (msg.includes("切片") || msg.includes("deck/slice") || msg.includes("slice")) {
+ return true;
+ }
+ }
+ return false;
+}
+
+// ───────────────────────────── 主 hook ─────────────────────────────
+
+/**
+ * ⓪总览数据源。只在 root 非 null 时访问 hub(降级模式零请求);拉取/校样结果按 root
+ * 走模块级缓存,同会话内 ⓪ 面反复切换不重复请求。
+ */
+export function useOverviewData(src: OverviewSource): OverviewData {
+ const { client } = useHub();
+ const { root, deadUrls, sseEvents } = src;
+
+ const [state, setState] = useState(() => seedState(src.root));
+ // root 变更首帧:直接以缓存/空态渲染(effect 随后补请求),不闪上一图包的旧值
+ const view = state.root === root ? state : seedState(root);
+
+ const deadCount = deadUrls.size;
+ const jobCount = sseEvents.length;
+ const sliceActive = src.sliceActive === true || hasSliceActivity(sseEvents);
+
+ useEffect(() => {
+ let cancelled = false;
+
+ // 幂等基线同步:仅当组件内状态与本轮 root 不一致时重置
+ setState((prev) => (prev.root === root ? prev : seedState(root)));
+
+ // 降级模式(无已注册图包):不发任何 hub 请求
+ if (root === null) {
+ return () => {
+ cancelled = true;
+ };
+ }
+ const packRoot = root;
+
+ void (async () => {
+ const apply = (updater: (prev: EngineState) => EngineState): void => {
+ if (!cancelled) {
+ setState((prev) => (prev.root === packRoot ? updater(prev) : prev));
+ }
+ };
+
+ // ① 图包元信息(GET /v1/packs 只读本地注册表;会话级缓存,同 root 只查一次)
+ if (!packMetaCache.has(metaKey(packRoot))) {
+ try {
+ const hit = findPackMeta(readPackMetas(await client.packs()), packRoot);
+ if (hit !== null) {
+ packMetaCache.set(metaKey(packRoot), hit);
+ apply((prev) => ({
+ ...prev,
+ packName: hit.name,
+ packVersion: hit.version,
+ }));
+ } else if (!cancelled) {
+ // 查不到条目:保留 basename 兜底名与 "—" 版本(不谎报「未注册」)
+ packMetaCache.set(metaKey(packRoot), {
+ dir: packRoot,
+ name: packNameFallback(packRoot),
+ version: NO_VERSION,
+ });
+ }
+ } catch {
+ // 静默降级:保留 basename(packRoot) + "—"
+ }
+ }
+
+ // ② 拉取:POST /v1/scripts/pull + POST /v1/diff 合并为一次「拉取」语义
+ // (与 ①代码面挂载同序:先拉后 diff,diff 反映拉取后的工作区状态)
+ if (cache.get(packRoot)?.pull === undefined && !isThrottled(packRoot, "pull")) {
+ try {
+ await client.pullScripts(packRoot);
+ const entries = readDiffEntries(await client.diff(packRoot));
+ // 先写缓存再 setState:同一帧内 deriveMiniTree 已能取到新节点
+ patchCache(packRoot, {
+ pull: { diffEntries: entries.length },
+ pullErrorAt: undefined,
+ });
+ treeCache.set(packRoot, toTreeNodes(entries));
+ apply((prev) => ({
+ ...prev,
+ pull: { ok: true, diffEntries: entries.length },
+ }));
+ } catch {
+ // 静默降级:拉取章 alert,失败标记进节流窗(30s 内重挂载不重发)
+ patchCache(packRoot, { pullErrorAt: Date.now() });
+ apply((prev) => ({ ...prev, pull: { ok: false } }));
+ }
+ }
+
+ // ③ 校样:POST /v1/test/run(在真实游戏内跑 tests/**);跑完即缓存(断言失败也算跑完)
+ if (
+ cache.get(packRoot)?.proof === undefined &&
+ !isThrottled(packRoot, "proof")
+ ) {
+ try {
+ const report = readRunReport(await client.testRun({ root: packRoot }));
+ if (report === null) {
+ patchCache(packRoot, { proofErrorAt: Date.now() });
+ apply((prev) => ({ ...prev, proof: { ok: false, notPassed: null } }));
+ } else {
+ patchCache(packRoot, {
+ proof: { passed: report.passed, failed: report.notPassed },
+ proofErrorAt: undefined,
+ });
+ apply((prev) => ({
+ ...prev,
+ proof: {
+ ok: report.notPassed === 0,
+ passed: report.passed,
+ notPassed: report.notPassed,
+ },
+ }));
+ }
+ } catch {
+ patchCache(packRoot, { proofErrorAt: Date.now() });
+ apply((prev) => ({ ...prev, proof: { ok: false, notPassed: null } }));
+ }
+ }
+ })();
+
+ return () => {
+ cancelled = true;
+ };
+ }, [client, root]);
+
+ const pull = view.pull;
+ const proof = view.proof;
+
+ const diffCount = pull !== null && pull.ok ? pull.diffEntries : 0;
+ const pendingSign = diffCount;
+
+ const stamps = useMemo(
+ () =>
+ deriveStamps({
+ root,
+ pull,
+ proof,
+ deadCount,
+ sliceActive,
+ pendingSign,
+ }),
+ [root, pull, proof, deadCount, sliceActive, pendingSign],
+ );
+
+ const todos = useMemo(
+ () => deriveTodos({ pull, deadCount, sliceActive, pendingSign }),
+ [pull, deadCount, sliceActive, pendingSign],
+ );
+
+ return useMemo(
+ () => ({
+ stamps,
+ todos,
+ diffCount,
+ deadCount,
+ pendingSign,
+ jobCount,
+ // 见文件头:本窗口不接 ③④ 面数据源(LayerTiles 渲染为 "—")
+ cardCount: null,
+ assetCount: null,
+ packName: view.packName,
+ packVersion: view.packVersion,
+ }),
+ [
+ stamps,
+ todos,
+ diffCount,
+ deadCount,
+ pendingSign,
+ jobCount,
+ view.packName,
+ view.packVersion,
+ ],
+ );
+}
+
+// ───────────────────────────── 派生数据源(迷你文件树 / 会签栏) ─────────────────────────────
+
+export interface MiniTreeData {
+ nodes: TreeNode[];
+ /** 块右上角小注(契约 §5:「差异 N」/ 空态「未注册图包」) */
+ note: string;
+}
+
+/**
+ * ⓪总览「工作区」迷你文件树数据源:读 useOverviewData 同一份缓存(同源),
+ * 在渲染期调用即可(拉取成功后本模块已先写 treeCache 再 setState,同一帧能取到新节点)。
+ * 最多 MINI_TREE_MAX 行,note 报总差异数。
+ */
+export function deriveMiniTree(root: string | null): MiniTreeData {
+ if (root === null) {
+ return { nodes: [], note: "未注册图包" };
+ }
+ const nodes = treeCache.get(root);
+ if (nodes === undefined) {
+ return { nodes: [], note: "差异 —" };
+ }
+ return { nodes: nodes.slice(0, MINI_TREE_MAX), note: `差异 ${nodes.length}` };
+}
+
+export interface SignBlockData {
+ version: string;
+ checks: SignCheck[];
+}
+
+/**
+ * §4.4 会签栏交付清单数据源(锁定决策 2:出厂行与出厂章同源)。
+ * 行序 版本 → 校样 → 打样 → 出厂;`next` 落在第一行 bad 上(当前下一步)。
+ *
+ * 注意:SignCheck.tone 只有 ok | bad(SignBlock 现有类型),故非 done 行一律 bad
+ * (与 App.tsx 既有占位「待/未 → bad」一致);若后续把 tone 扩到 amber(待签=待人审,
+ * §2.5 更准确),此处可相应细化。打样(POST /v1/pack/build)产物不在 OverviewSource 内
+ * 且无查询路由,恒「未打样」。
+ */
+export function deriveSignBlock(data: OverviewData): SignBlockData {
+ const note = (id: StampId): string =>
+ data.stamps.find((s) => s.id === id)?.note ?? NO_VERSION;
+ const status = (id: StampId): StampStatus =>
+ data.stamps.find((s) => s.id === id)?.status ?? "todo";
+ const toneOf = (id: StampId): "ok" | "bad" =>
+ status(id) === "done" ? "ok" : "bad";
+
+ const checks: SignCheck[] = [
+ {
+ k: "版本",
+ v: data.packVersion === NO_VERSION ? "未标注" : data.packVersion,
+ tone: data.packVersion === NO_VERSION ? "bad" : "ok",
+ },
+ { k: "校样", v: note("proof"), tone: toneOf("proof") },
+ { k: "打样", v: "未打样", tone: "bad" },
+ { k: "出厂", v: note("ship"), tone: toneOf("ship") },
+ ];
+
+ const nextIdx = checks.findIndex((c) => c.tone === "bad");
+ const nextRow = checks[nextIdx];
+ if (nextRow !== undefined) checks[nextIdx] = { ...nextRow, next: true };
+
+ return { version: data.packVersion, checks };
+}
+
+/** 图包根信息(供 Stage B 解一次注册表,同时喂 useOverviewData 与 MiniFileTree 的 root) */
+export interface PackRootInfo {
+ /** 已注册图包根(注册表条目 dir,hub 路由直接接受;无图包为 null) */
+ root: string | null;
+ packName: string;
+ packVersion: string;
+}
+
+/**
+ * 解析已注册图包根(GET /v1/packs 取第一个条目,与 ①代码面「第一个注册图包」口径一致)。
+ * root 为 null 时不写任何数据;consumers 可把 root 转交 useOverviewData / deriveMiniTree。
+ */
+export function usePackRoot(): PackRootInfo {
+ const { client } = useHub();
+ const [info, setInfo] = useState(() => ({
+ root: null,
+ packName: NO_PACK_NAME,
+ packVersion: NO_VERSION,
+ }));
+
+ useEffect(() => {
+ let cancelled = false;
+ void (async () => {
+ try {
+ const metas = readPackMetas(await client.packs());
+ if (cancelled) return;
+ for (const meta of metas) packMetaCache.set(metaKey(meta.dir), meta);
+ const first = metas[0];
+ setInfo(
+ first === undefined
+ ? { root: null, packName: NO_PACK_NAME, packVersion: NO_VERSION }
+ : {
+ root: first.dir,
+ packName: first.name,
+ packVersion: first.version,
+ },
+ );
+ } catch {
+ if (!cancelled) {
+ setInfo({ root: null, packName: NO_PACK_NAME, packVersion: NO_VERSION });
+ }
+ }
+ })();
+ return () => {
+ cancelled = true;
+ };
+ }, [client]);
+
+ return info;
+}
+
+// ───────────────────────────── 缓存维护(供 Stage B / 验收窗口) ─────────────────────────────
+
+/** 读缓存(只读视图;调试 / 二次派生用) */
+export function readStampCache(root: string): StampCacheEntry | undefined {
+ return cache.get(root);
+}
+
+/**
+ * 清空全部结果缓存(拉取 / 校样 / 迷你文件树 / 图包元信息)。
+ * 用途:写回游戏成功(push)后主动失效,让 ⓪ 面重算五章与差异计数。
+ * 注意:清空后下次进入 ⓪ 会重新 pull(会覆盖工作区)+ 重跑测试,请在明确时机调用。
+ */
+export function clearStampCache(): void {
+ cache.clear();
+ treeCache.clear();
+ packMetaCache.clear();
+}