From 80cfaf8eaf6389f74c21e47d36042dc8c9ce2d7e Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 21:41:26 +0800
Subject: [PATCH 01/49] docs: add Windows desktop redesign spec

---
 ...6-06-19-windows-desktop-redesign-design.md | 243 ++++++++++++++++++
 1 file changed, 243 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-19-windows-desktop-redesign-design.md

diff --git a/docs/superpowers/specs/2026-06-19-windows-desktop-redesign-design.md b/docs/superpowers/specs/2026-06-19-windows-desktop-redesign-design.md
new file mode 100644
index 00000000..47ef4f30
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-19-windows-desktop-redesign-design.md
@@ -0,0 +1,243 @@
+# Merak Windows Desktop 客户端完善设计
+
+## 1. 背景与目标
+
+Merak Windows Desktop 当前由 Tauri 桌面壳层和 React WebUI 组成。现有实现已经具备会话、世界观数据、文件编辑、LLM 配置、SSE 运行状态和桌面 Runtime 管理能力，但主要界面仍围绕单一三栏工作台组织，无法完整承载设计稿中的十个独立工作区。
+
+本次改造以 2026-06-19 提供的十张 `1672 x 941` 设计稿和 `docs/api-reference.md` 为依据，在保留现有 Tauri、React、SSE 与业务能力的前提下，完成桌面端的信息架构、页面体系、API 接入和视觉系统升级。
+
+目标如下：
+
+- 建立统一的桌面应用壳层与十个一级工作区。
+- 已有和新增界面均使用真实 API 数据，不使用演示数据伪造功能。
+- 接入 API 文档中已实现但前端尚未使用的必要能力。
+- 保留现有会话、编辑器、审批、导出、配置和桌面诊断流程。
+- 在设计稿原始尺寸、默认桌面窗口和最小窗口下完成视觉与交互验收。
+
+## 2. 已确认的产品原则
+
+### 2.1 真实数据优先
+
+- API 已支持的数据直接从本机 Merak Runtime 获取。
+- 可由真实响应推导的统计在前端 selector 中计算，并记录明确口径。
+- API 未支持的分享、自动分析、虚构任务系统等功能不使用模拟数据。
+- 无后端支持的入口应隐藏；若入口对理解页面结构必要，则以不可用说明替代可点击控件。
+
+### 2.2 模块化改造现有 WebUI
+
+采用在现有 WebUI 内部重构的方案，不维护并行 V2 应用。保留 React、CSS Modules、AppState、SSE、Tauri 调用和已有业务组件，通过新应用壳层、页面路由和页面级数据模块逐步替换现有单一工作台结构。
+
+### 2.3 桌面优先
+
+主验收环境是 Windows Desktop。默认窗口为 `1280 x 820`，最小窗口为 `960 x 640`。设计稿原始尺寸 `1672 x 941` 用于高保真对照。窄窗口可以折叠次要栏，但主操作、正文和当前任务不可被裁切。
+
+## 3. 信息架构
+
+### 3.1 全局应用壳层
+
+应用壳层由以下区域组成：
+
+- 左侧全局导航：品牌、当前世界、搜索入口、十个工作区入口、世界进度摘要和用户/版本区域。
+- 顶部操作栏：世界选择器、当前页面上下文和与当前能力匹配的全局操作。
+- 页面内容区：由页面布局决定，可为总览、列表详情或创作布局。
+- 全局覆盖层：创建弹窗、审批、导出、帮助、连接状态、通知和桌面启动/恢复界面。
+
+左侧导航的一级页面为：
+
+1. 概览
+2. 会话
+3. 世界
+4. 角色
+5. 章节
+6. 场景
+7. 伏笔
+8. 秘密
+9. 文件
+10. 设置
+
+### 3.2 页面布局类型
+
+#### 总览型
+
+用于概览、世界和设置。主内容区展示核心资料或配置，右侧摘要栏展示统计、状态和相关提醒。
+
+#### 列表详情型
+
+用于角色、伏笔、秘密和文件。资源列表位于左侧，中间为选中资源详情，右侧为关联数据、检查结果或元数据。选中项由稳定 ID 驱动，列表刷新时尽量保留选择。
+
+#### 创作型
+
+用于会话、章节和场景。中心区域优先承载对话、规划表、场景结构或正文，右侧展示当前上下文、关联资源和实时状态。
+
+## 4. 页面设计
+
+### 4.1 概览
+
+展示当前世界的真实统计、最近会话、创作进度、可验证的提醒和快捷入口。统计来自 `/overview`、`/dashboard` 或资源列表响应。若 `/dashboard` 不可用，则只展示能够由已加载列表准确计算的项目。
+
+### 4.2 会话
+
+保留并重组现有会话列表、消息时间线、Composer、工具调用、审批、生成文件和运行状态。会话页处理 SSE 实时事件，并补齐 `ask_user_requested`、`creation_requested`、`creation_resolved` 及 `POST /v1/runs/:id/ask-response`。
+
+### 4.3 世界
+
+展示世界基础资料、世界时间、地点、势力、知识条目、时间线和知识图谱数据。世界页按区块延迟加载，避免进入页面时请求全部世界观端点。编辑操作遵循接口版本和错误约定。
+
+### 4.4 角色
+
+展示角色列表、角色卡片、图片、日记、关系、记忆摘要、声音分析和出场信息。复用现有角色卡片编辑、图片上传、关系图和创建流程，并补齐搜索、详情和删除等 API 客户端能力。
+
+### 4.5 章节
+
+展示章节列表、顺序、状态、场景规划和正文入口。支持章节重排、更新、删除、评审和导出。现有 ChapterEditor 迁入新页面流程，文件保存继续使用版本冲突保护。
+
+### 4.6 场景
+
+展示场景目标、参与角色、地点、关联伏笔、正文和结束场景结果。支持创建、更新、删除和结束场景。知识提取或一致性结果仅在对应 API 有真实响应时展示。
+
+### 4.7 伏笔
+
+展示伏笔列表、状态、首次出现、计划回收、关联角色和章节时间线。支持创建、更新和删除。提醒、逾期和冲突状态仅由已有字段和真实章节/场景关系推导。
+
+### 4.8 秘密
+
+展示秘密内容、公开版本、知情者范围、怀疑者、风险、揭示计划和关联资源。受保护内容默认隐藏，由用户主动揭示。支持创建、更新和删除。
+
+### 4.9 文件
+
+展示工作区目录、搜索、类型筛选、文件列表、内容预览和编辑。支持读取、版本化保存、在系统中打开和世界资源关联。正文和大型文件按需加载，不进入全局启动请求。
+
+### 4.10 设置
+
+整合 LLM Provider、API Key、Base URL、默认模型、偏好、权限模式、桌面 Runtime、数据库状态和诊断工具。不存在真实读写接口的配置不显示为可编辑字段。Tauri 继续负责 Runtime 重启、日志目录和诊断报告。
+
+## 5. 数据与状态架构
+
+### 5.1 启动流程
+
+启动时并行加载 Runtime 元数据、LLM 配置、能力开关、世界列表、会话列表和用户偏好。恢复上次选中的世界与页面；恢复失败时使用第一个可用世界。没有世界时进入世界创建流程，没有可用角色时显示世界概览和创建入口。
+
+### 5.2 页面查询
+
+页面数据以 `worldId + resource + filters` 作为查询身份。切换世界时清理世界级选中状态和过期缓存。每个页面独立管理加载、空状态、错误和重试，不将全部资源塞入单一启动请求。
+
+项目继续使用现有 React 状态模式，不为本次改造引入新的远程状态依赖。页面查询逻辑封装为按资源划分的 hooks 和 API 方法；跨页面共享的世界、会话、运行状态和用户偏好保留在 AppState。
+
+### 5.3 写操作
+
+- 创建成功后将新资源插入对应列表并选中。
+- 更新成功后局部合并响应，并使相关统计失效。
+- 删除成功后选择相邻资源或进入空状态。
+- 乐观锁冲突时保留用户输入，不覆盖服务端内容。
+- 删除、结束场景和覆盖保存等危险操作在服务器确认前不改变最终 UI 状态。
+
+### 5.4 SSE
+
+SSE 仅承载会话运行和实时事件。断线后从最后事件序号恢复，Reducer 使用事件 ID 和序号防止重复处理。新增提问与创建请求状态必须具备明确的打开、提交、解决和取消生命周期。
+
+### 5.5 Tauri 边界
+
+Tauri 只负责本地 Runtime 生命周期、端口和目录、系统打开行为与诊断。世界、会话、文件和配置等业务数据继续通过本机 HTTP API 访问，避免桌面命令与 Web API 形成两套业务契约。
+
+## 6. API 层设计
+
+API 客户端按资源域组织，同时保留统一的 `request`、错误解析和 API Base URL。需要补齐的能力至少包括：
+
+- Run 提问响应与相关 SSE 类型。
+- 角色删除、日记详情/搜索、记忆摘要、关系写操作和声音分析。
+- 叙事树、章节/场景详情与删除、章节重排。
+- 伏笔与秘密删除。
+- 完整导入导出。
+- 地点、知识条目和势力 CRUD。
+- Dashboard、世界文件关联、预览与创建流程。
+- Knowledge Graph 与 Timeline 查询/写入。
+- Pipeline retreat 和 clear-error。
+
+`GET /v1/runs/:id/audit` 在文档中标记为前端调用但后端未实现。新界面不依赖该端点；现有调用在迁移时移除或保持不可达，不把失败响应作为正常产品功能。
+
+错误解析必须兼容文档列出的非标准响应：字符串 `error`、对象 `error` 和 worldbuilding `{ ok: false, error }` 格式。
+
+## 7. 视觉系统
+
+视觉以提供的设计稿为主，现有 `PRODUCT.md` 和 `DESIGN.md` 作为品牌约束补充。
+
+- 背景使用纯白和轻微冷灰，不引入暖黄页面底色。
+- 主品牌色使用设计稿中的深海军蓝，语义色仅用于成功、警告、错误和状态。
+- 字体使用 Inter、Segoe UI 和系统中文无衬线回退。
+- 表面默认使用细边框，不使用大面积阴影或装饰性渐变。
+- 导航、按钮、输入、表格、状态标签和详情区使用统一 tokens 与组件变体。
+- 图标优先使用现有 Lucide 图标；图标含义、线宽、尺寸和选中态必须与设计稿一致。
+- 动效用于页面切换、选择反馈、状态变化和面板展开，并遵循 `prefers-reduced-motion`。
+
+不使用 Image Gen 重新生成视觉概念，因为用户提供的十张完整设计稿已经构成获批视觉规格。本次只对已有设计进行忠实实现。
+
+## 8. 错误、空状态与恢复
+
+- 页面级失败只影响对应区域，应用壳层和其他成功区域保持可用。
+- 多请求页面采用部分成功策略，不因单个接口失败清空已有数据。
+- `400`、`403`、`404`、`409`、`415` 和 `5xx` 映射为可操作的中文提示。
+- `409` 冲突提供重新载入和保留/复制修改内容的路径。
+- Runtime 断开时保留当前页面，显示桌面连接条并自动重连；持续失败后提供重启和诊断入口。
+- 空世界、空角色、空章节等状态提供对应创建入口。
+- 能力缺失与请求失败使用不同的界面文案，避免把未实现功能伪装成系统错误。
+
+## 9. 组件边界
+
+主要组件和模块边界如下：
+
+- `DesktopShell`：全局布局、导航、顶部栏和页面出口。
+- `PrimaryNavigation`：十个一级页面、当前世界摘要与响应式折叠。
+- `DesktopTopbar`：世界切换和当前页面允许的全局操作。
+- `PageState`：加载、空状态、错误和重试的统一容器。
+- `ResourceList`：列表筛选、选择、键盘导航与虚拟化扩展点。
+- `DetailPane`：详情页头、标签页、操作和内容滚动边界。
+- `InspectorRail`：页面相关摘要、关联资源和状态。
+- `api/*`：按 sessions、worlds、agents、narrative、files、config、pipeline、graph 和 timeline 划分。
+- `pages/*`：十个页面的组合层；复杂页面继续拆分为领域组件。
+
+现有 `App.tsx` 只负责 Provider、启动和高层路由组合，不承载页面内部业务。
+
+## 10. 测试与验收
+
+### 10.1 自动化测试
+
+- API 单元测试覆盖新增端点、查询参数、错误解析和版本冲突。
+- Reducer 测试覆盖页面/世界切换、SSE 提问与创建事件、断线恢复和去重。
+- 页面测试覆盖加载、空状态、部分失败、选择详情和主要写操作。
+- 用户流程覆盖世界创建、角色创建、会话运行、章节与场景操作、文件编辑、配置和诊断。
+- 可访问性检查覆盖键盘导航、焦点、语义标签和减少动画模式。
+
+当前基线为生产构建通过，自动化测试 `104/106` 通过。两个既有失败来自 Inspector 文案/标签与测试预期不一致，必须在实现过程中修复，不能作为允许保留的失败。
+
+### 10.2 视觉验收
+
+逐页在以下尺寸检查：
+
+- `1672 x 941`：与十张设计稿一一对照。
+- `1280 x 820`：Tauri 默认窗口。
+- `960 x 640`：Tauri 最小窗口。
+
+每页至少记录布局、可见文案、字体、颜色、间距、边框、图标、响应式行为和核心交互。最终对照必须使用浏览器截图与原始设计稿进行同轮 `view_image` 检查，并记录有意差异。
+
+### 10.3 构建验收
+
+- WebUI 测试全部通过。
+- TypeScript 与 Vite 生产构建通过。
+- 主要页面按需加载，避免当前约 `713 kB` 主包继续无界增长。
+- 浏览器完成桌面与最小窗口的核心工作流验证。
+- 原生 Tauri 检查和安装包构建在具备 Rust/Cargo 与 `merak.exe` 的环境中执行。
+
+当前开发机缺少 Rust/Cargo 和 `merak.exe`，因此原生安装包构建属于已知环境阻塞，不改变 WebUI、Tauri 源码和浏览器视觉验收范围。
+
+## 11. 完成标准
+
+本目标只有在以下条件全部满足时才完成：
+
+1. 十个一级工作区均存在并遵循确认的信息架构。
+2. 每个页面可用区域均接入真实 API 或真实推导数据。
+3. 无 API 支持的功能没有伪造数据或误导性可点击入口。
+4. 会话 SSE 提问与创建请求闭环完成。
+5. 原有编辑、审批、导出、配置和桌面诊断能力无回归。
+6. 自动化测试与生产构建通过。
+7. 十张设计稿完成逐页视觉对照，默认与最小窗口无主内容裁切。
+8. 所有剩余差异均为有依据、已记录的有意差异。

From b540abade9b617b796a9179ec0d7b6bba014f7ea Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 21:51:06 +0800
Subject: [PATCH 02/49] docs: add Windows desktop implementation plan

---
 .../2026-06-19-windows-desktop-redesign.md    | 719 ++++++++++++++++++
 1 file changed, 719 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md

diff --git a/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
new file mode 100644
index 00000000..4956785f
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
@@ -0,0 +1,719 @@
+# Merak Windows Desktop Redesign Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build the ten-page Merak Windows Desktop workbench from the approved screenshots, backed only by real API responses or explicitly derived data.
+
+**Architecture:** Keep the existing React, AppState, SSE, CSS Modules, and Tauri boundaries. Add a lazy-loaded desktop shell and page modules, split API access by resource domain, and migrate existing working components into page-specific layouts without creating a parallel application.
+
+**Tech Stack:** React 19, TypeScript 5.8, Vite 6, Vitest, Testing Library, CSS Modules, Lucide React, Tauri 2.
+
+## Global Constraints
+
+- Implement ten top-level pages: overview, sessions, world, characters, chapters, scenes, foreshadowing, secrets, files, settings.
+- Use real HTTP API data or deterministic selectors over real responses; never ship fabricated dashboard or task data.
+- Keep Tauri responsible only for local Runtime lifecycle, OS paths, and diagnostics.
+- Preserve existing editor, approval, export, configuration, and desktop recovery workflows.
+- Match the supplied `1672 x 941` screenshots and verify `1280 x 820` and `960 x 640` viewports.
+- Keep React 19, TypeScript 5.8, Vite 6, CSS Modules, and Lucide React; add no remote-state or component-library dependency.
+- Respect `prefers-reduced-motion` and keep all primary workflows keyboard reachable.
+- Treat the two existing Inspector test failures as regressions to fix, not accepted baseline failures.
+- Do not require `GET /v1/runs/:id/audit`; the backend does not implement it.
+
+---
+
+## File Structure
+
+Create these focused modules:
+
+- `webui/src/api/http.ts`: base URL, request helpers, API error normalization.
+- `webui/src/api/runtime.ts`: runtime, session, run, approval, SSE URL operations.
+- `webui/src/api/worldbuilding.ts`: world, dashboard, agent, narrative, location, faction, knowledge, graph, timeline operations.
+- `webui/src/api/files.ts`: workspace file and world file-link operations.
+- `webui/src/api/config.ts`: LLM and preference operations.
+- `webui/src/api/index.ts`: compatibility `api` facade used during migration.
+- `webui/src/hooks/useResource.ts`: cancellable page-level GET lifecycle.
+- `webui/src/shell/DesktopShell.tsx`: global navigation, top bar, page outlet, responsive rails.
+- `webui/src/shell/DesktopShell.module.css`: shell grid and viewport breakpoints.
+- `webui/src/shell/navigation.ts`: page metadata and icon mapping.
+- `webui/src/components/layout/PageState.tsx`: loading, partial error, empty, retry states.
+- `webui/src/components/layout/ResourceList.tsx`: selectable keyboard list primitive.
+- `webui/src/components/layout/DetailPane.tsx`: detail content and optional inspector rail.
+- `webui/src/pages/*.tsx`: one composition module for each top-level page.
+- `webui/src/pages/*.module.css`: page-specific layout only; shared tokens remain global.
+- `webui/src/pages/selectors.ts`: deterministic overview and progress calculations.
+- `webui/src/__tests__/shell.test.tsx`: shell navigation and responsive behavior.
+- `webui/src/__tests__/pages.test.tsx`: page loading, empty, partial failure, and interactions.
+- `webui/src/__tests__/sse-workflows.test.tsx`: ask-user and creation-request workflows.
+
+Modify these existing modules:
+
+- `webui/src/App.tsx`: providers, bootstrap, lazy page outlet, global overlays.
+- `webui/src/AppState.tsx`: top-level page IDs, selection state, ask/creation SSE state.
+- `webui/src/api/types.ts`: API resource and SSE payload types.
+- `webui/src/api/client.ts`: temporary re-export during migration, then compatibility-only facade.
+- `webui/src/hooks/useSSE.ts`: exported parser, reconnect timer cleanup, duplicate sequence guard.
+- `webui/src/styles/global.css`: approved navy/cool-gray tokens and shared control states.
+- `webui/src/i18n.tsx`: visible Chinese and English shell/page copy.
+- Existing components under `webui/src/components/`: migrate into pages without duplicating working business behavior.
+
+---
+
+### Task 1: Normalize HTTP Errors and Split the API Foundation
+
+**Files:**
+- Create: `webui/src/api/http.ts`
+- Create: `webui/src/api/runtime.ts`
+- Create: `webui/src/api/index.ts`
+- Modify: `webui/src/api/client.ts`
+- Modify: `webui/src/__tests__/api.test.ts`
+
+**Interfaces:**
+- Produces: `request<T>(method, path, body?)`, `requestForm<T>(path, form)`, `ApiError`, `formatApiError`, `setApiBase`, `getApiBase`, `apiUrl`, and `runtimeApi`.
+- Preserves: `import { api } from './api/client'` until all call sites migrate.
+
+- [ ] **Step 1: Write failing normalization tests**
+
+```ts
+it.each([
+  [{ error: { code: 'world_not_found', message: 'World not found', retryable: false } }, 'world_not_found'],
+  [{ ok: false, error: { code: 'file_conflict', message: 'Conflict', retryable: true } }, 'file_conflict'],
+  [{ error: 'session not found' }, undefined],
+])('normalizes documented error shapes', async (payload, code) => {
+  fetchMock.mockResolvedValueOnce(new Response(JSON.stringify(payload), { status: 409 }));
+  await expect(request('GET', '/failure')).rejects.toMatchObject({ status: 409, code });
+});
+```
+
+- [ ] **Step 2: Run the focused tests and confirm failure**
+
+Run: `npm test -- --run src/__tests__/api.test.ts`
+
+Expected: FAIL because `request` is not exported from `api/http.ts`.
+
+- [ ] **Step 3: Implement the shared HTTP module**
+
+```ts
+export class ApiError extends Error {
+  constructor(message: string, public status: number, public code?: string, public retryable = false) {
+    super(message);
+  }
+}
+
+export async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const response = await fetch(apiUrl(path), {
+    method,
+    headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const payload = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const raw = payload?.error;
+    const detail = typeof raw === 'object' && raw ? raw : {};
+    throw new ApiError(
+      detail.message ?? (typeof raw === 'string' ? raw : `Request failed (${response.status})`),
+      response.status,
+      detail.code,
+      Boolean(detail.retryable),
+    );
+  }
+  return payload as T;
+}
+```
+
+Move the existing base URL, form/blob helpers, and `formatApiError` unchanged in behavior. Move runtime metadata, sessions, runs, delegations, approvals, creation resolution, and SSE URL methods into `runtimeApi` in `api/runtime.ts`. Re-export a compatibility `api` object from `api/index.ts` and `api/client.ts` by spreading `runtimeApi` so existing call sites retain their method names.
+
+- [ ] **Step 4: Run API tests and production build**
+
+Run: `npm test -- --run src/__tests__/api.test.ts && npm run build`
+
+Expected: API tests PASS; TypeScript and Vite build PASS.
+
+- [ ] **Step 5: Commit the API foundation**
+
+```powershell
+git add webui/src/api/http.ts webui/src/api/runtime.ts webui/src/api/index.ts webui/src/api/client.ts webui/src/__tests__/api.test.ts
+git commit -m "refactor(webui): split shared API transport"
+```
+
+### Task 2: Add Typed Worldbuilding and File Endpoints
+
+**Files:**
+- Create: `webui/src/api/worldbuilding.ts`
+- Create: `webui/src/api/files.ts`
+- Create: `webui/src/api/config.ts`
+- Modify: `webui/src/api/types.ts`
+- Modify: `webui/src/api/index.ts`
+- Test: `webui/src/__tests__/api.test.ts`
+
+**Interfaces:**
+- Produces: `worldbuildingApi`, `filesApi`, `configApi`.
+- Core signatures: `getDashboard(worldId)`, `listLocations(worldId)`, `listKnowledge(worldId)`, `listFactions(worldId)`, `getTimeline(worldId)`, `listGraphEntities(worldId)`, `reorderChapters(worldId, chapterIds)`, resource delete functions, `listWorldFiles(worldId)`, `linkWorldFile(worldId, link)`.
+
+- [ ] **Step 1: Add failing URL and body tests**
+
+```ts
+it('reorders chapters with the documented body', async () => {
+  fetchMock.mockResolvedValueOnce(json({ ok: true }));
+  await worldbuildingApi.reorderChapters('w 1', ['c1', 'c2']);
+  expect(fetchMock).toHaveBeenCalledWith(
+    expect.stringContaining('/api/worldbuilding/w%201/chapters/reorder'),
+    expect.objectContaining({ method: 'POST', body: JSON.stringify({ chapter_ids: ['c1', 'c2'] }) }),
+  );
+});
+
+it('encodes a linked file path when deleting it', async () => {
+  fetchMock.mockResolvedValueOnce(json({ ok: true }));
+  await filesApi.unlinkWorldFile('w1', '章节/第一章.md');
+  expect(fetchMock.mock.calls[0][0]).toContain(encodeURIComponent('章节/第一章.md'));
+});
+```
+
+- [ ] **Step 2: Run tests and confirm missing modules**
+
+Run: `npm test -- --run src/__tests__/api.test.ts`
+
+Expected: FAIL on imports for `worldbuildingApi` and `filesApi`.
+
+- [ ] **Step 3: Define exact shared resource types**
+
+```ts
+export interface ResourceListResponse<T> { ok?: boolean; items?: T[]; }
+export interface LocationItem { id: string; name: string; description?: string; version?: number; }
+export interface KnowledgeItem { id: string; title: string; content?: string; tags?: string[]; version?: number; }
+export interface FactionItem { id: string; name: string; description?: string; version?: number; }
+export interface TimelineEvent { id: string; title: string; world_time?: string; description?: string; }
+export interface GraphEntity { id: string; type: string; name: string; }
+export interface WorldFileLink { file_path: string; entity_type?: string; entity_id?: string; }
+```
+
+Implement every method with `encodeURIComponent` for path IDs and documented request bodies. Use response adapters that accept documented named arrays and `items` without manufacturing records.
+
+- [ ] **Step 4: Run API tests, formatter, and build**
+
+Run: `npm test -- --run src/__tests__/api.test.ts && npm run format:check && npm run build`
+
+Expected: all commands PASS.
+
+- [ ] **Step 5: Commit typed API domains**
+
+```powershell
+git add webui/src/api webui/src/__tests__/api.test.ts
+git commit -m "feat(webui): add typed worldbuilding APIs"
+```
+
+### Task 3: Complete Ask-User and Creation SSE Workflows
+
+**Files:**
+- Modify: `webui/src/api/types.ts`
+- Modify: `webui/src/api/runtime.ts`
+- Modify: `webui/src/AppState.tsx`
+- Modify: `webui/src/hooks/useSSE.ts`
+- Create: `webui/src/components/AskUserPrompt.tsx`
+- Create: `webui/src/components/AskUserPrompt.module.css`
+- Create: `webui/src/components/CreationRequestDialog.tsx`
+- Test: `webui/src/__tests__/AppState.test.ts`
+- Test: `webui/src/__tests__/sse-workflows.test.tsx`
+
+**Interfaces:**
+- Produces: `runtimeApi.respondToAsk(runId: string, response: string)`, `pendingAsk`, `pendingCreation`, `RESOLVE_ASK`, `RESOLVE_CREATION` actions.
+- Consumes: existing `resolveCreation(id, decision, modifications?)` behavior.
+
+- [ ] **Step 1: Add reducer tests for SSE lifecycle and deduplication**
+
+```ts
+const askFrame = { seq: 10, type: 'ask_user_requested', payload: { run_id: 'r1', question: 'Choose POV' } };
+expect(reducer(initialState, { type: 'APPLY_SSE', frame: askFrame }).pendingAsk)
+  .toEqual({ runId: 'r1', question: 'Choose POV' });
+expect(reducer({ ...initialState, lastSeq: 10 }, { type: 'APPLY_SSE', frame: askFrame }))
+  .toEqual({ ...initialState, lastSeq: 10 });
+```
+
+- [ ] **Step 2: Run focused tests and confirm failure**
+
+Run: `npm test -- --run src/__tests__/AppState.test.ts src/__tests__/sse-workflows.test.tsx`
+
+Expected: FAIL because pending workflow state and dialogs do not exist.
+
+- [ ] **Step 3: Implement typed SSE state and dialogs**
+
+```ts
+export interface PendingAsk { runId: string; question: string; choices?: string[]; }
+export interface PendingCreation { id: string; toolName: string; preview?: Record<string, unknown>; }
+```
+
+Reject frames whose `seq` is nonzero and `seq <= state.lastSeq`. On submit, disable the dialog, call the real endpoint, clear state only on success, and show `formatApiError` on failure. Clear creation state on both `creation_resolved` and successful local resolution.
+
+- [ ] **Step 4: Verify workflow tests and all reducer tests**
+
+Run: `npm test -- --run src/__tests__/AppState.test.ts src/__tests__/sse-workflows.test.tsx`
+
+Expected: PASS with one network call per submission and no duplicate frame effects.
+
+- [ ] **Step 5: Commit SSE workflow completion**
+
+```powershell
+git add webui/src/api webui/src/AppState.tsx webui/src/hooks/useSSE.ts webui/src/components/AskUserPrompt* webui/src/components/CreationRequestDialog.tsx webui/src/__tests__
+git commit -m "feat(webui): complete interactive SSE requests"
+```
+
+### Task 4: Build Shared Page State and Resource Layout Primitives
+
+**Files:**
+- Create: `webui/src/hooks/useResource.ts`
+- Create: `webui/src/components/layout/PageState.tsx`
+- Create: `webui/src/components/layout/PageState.module.css`
+- Create: `webui/src/components/layout/ResourceList.tsx`
+- Create: `webui/src/components/layout/ResourceList.module.css`
+- Create: `webui/src/components/layout/DetailPane.tsx`
+- Create: `webui/src/components/layout/DetailPane.module.css`
+- Test: `webui/src/__tests__/pages.test.tsx`
+
+**Interfaces:**
+- Produces: `useResource<T>(key, loader)`, `PageState`, `ResourceList<T>`, `DetailPane`.
+
+- [ ] **Step 1: Write failing partial-error and keyboard selection tests**
+
+```tsx
+render(<ResourceList items={[{ id: 'a', name: 'A' }, { id: 'b', name: 'B' }]} selectedId="a" getId={x => x.id} renderItem={x => x.name} onSelect={onSelect} />);
+fireEvent.keyDown(screen.getByRole('listbox'), { key: 'ArrowDown' });
+expect(onSelect).toHaveBeenCalledWith('b');
+```
+
+- [ ] **Step 2: Run the focused page tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx`
+
+Expected: FAIL because layout primitives are missing.
+
+- [ ] **Step 3: Implement cancellable resource lifecycle**
+
+```ts
+export type ResourceState<T> = { status: 'loading' | 'ready' | 'error'; data: T | null; error: Error | null; retry(): void };
+export function useResource<T>(key: string, loader: (signal: AbortSignal) => Promise<T>): ResourceState<T>;
+```
+
+The hook must abort the previous request on key change, retain successful data during retry, and ignore aborted rejections. `PageState` renders skeleton, retained-data warning, full error, or empty state based on explicit props.
+
+- [ ] **Step 4: Run tests and accessibility assertions**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx`
+
+Expected: PASS; listbox exposes selected option and keyboard navigation.
+
+- [ ] **Step 5: Commit layout primitives**
+
+```powershell
+git add webui/src/hooks/useResource.ts webui/src/components/layout webui/src/__tests__/pages.test.tsx
+git commit -m "feat(webui): add resource page primitives"
+```
+
+### Task 5: Add the Ten-Page Desktop Shell
+
+**Files:**
+- Create: `webui/src/shell/navigation.ts`
+- Create: `webui/src/shell/DesktopShell.tsx`
+- Create: `webui/src/shell/DesktopShell.module.css`
+- Modify: `webui/src/AppState.tsx`
+- Modify: `webui/src/App.tsx`
+- Modify: `webui/src/i18n.tsx`
+- Test: `webui/src/__tests__/shell.test.tsx`
+
+**Interfaces:**
+- Produces: `AppPage = 'overview' | 'sessions' | 'world' | 'characters' | 'chapters' | 'scenes' | 'foreshadowing' | 'secrets' | 'files' | 'settings' | 'editor'`.
+- Produces: `DesktopShell({ page, onNavigate, children })`.
+
+- [ ] **Step 1: Add failing navigation tests**
+
+```tsx
+const navigation = screen.getByRole('navigation', { name: '主导航' });
+expect(within(navigation).getAllByRole('button')).toHaveLength(10);
+fireEvent.click(within(navigation).getByRole('button', { name: /角色/ }));
+expect(dispatch).toHaveBeenCalledWith({ type: 'SET_PAGE', page: 'characters' });
+```
+
+- [ ] **Step 2: Run shell tests and confirm failure**
+
+Run: `npm test -- --run src/__tests__/shell.test.tsx`
+
+Expected: FAIL because the desktop shell is missing.
+
+- [ ] **Step 3: Implement navigation metadata and lazy outlet**
+
+```ts
+export const desktopPages = [
+  ['overview', '概览', LayoutDashboard], ['sessions', 'Sessions 会话', MessagesSquare],
+  ['world', 'World 世界设定', Globe2], ['characters', 'Characters 角色', Users],
+  ['chapters', 'Chapters 章节', BookOpen], ['scenes', 'Scenes 场景', PanelsTopLeft],
+  ['foreshadowing', 'Foreshadowing 伏笔线索', Sparkles], ['secrets', 'Secrets 秘密', KeyRound],
+  ['files', 'Files 资料库', Files], ['settings', 'Settings 设置', Settings],
+] as const;
+```
+
+Use `<button>` navigation with `aria-current="page"` rather than fake URLs. Persist the selected page in `localStorage` only after validating it against `desktopPages`. Lazy-load every page component in `App.tsx`.
+
+- [ ] **Step 4: Run shell, reducer, and build checks**
+
+Run: `npm test -- --run src/__tests__/shell.test.tsx src/__tests__/AppState.test.ts && npm run build`
+
+Expected: PASS; build output contains separate page chunks.
+
+- [ ] **Step 5: Commit the desktop shell**
+
+```powershell
+git add webui/src/shell webui/src/App.tsx webui/src/AppState.tsx webui/src/i18n.tsx webui/src/__tests__
+git commit -m "feat(webui): add ten-page desktop shell"
+```
+
+### Task 6: Implement Overview Page with Deterministic Selectors
+
+**Files:**
+- Create: `webui/src/pages/selectors.ts`
+- Create: `webui/src/pages/OverviewPage.tsx`
+- Create: `webui/src/pages/OverviewPage.module.css`
+- Modify: `webui/src/App.tsx`
+- Test: `webui/src/__tests__/pages.test.tsx`
+
+**Interfaces:**
+- Produces: `selectWorldMetrics({ agents, chapters, scenes, files, overview, dashboard })`.
+
+- [ ] **Step 1: Write failing selector tests with real response-shaped fixtures**
+
+```ts
+expect(selectWorldMetrics({ agents: [{ id: 'a' }], chapters: [{ id: 'c', status: 'completed' }], scenes: [], files: [], overview: null, dashboard: null }))
+  .toMatchObject({ characterCount: 1, chapterCount: 1, completedChapterCount: 1 });
+```
+
+- [ ] **Step 2: Run selector and page tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx`
+
+Expected: FAIL because the selector and Overview page are absent.
+
+- [ ] **Step 3: Implement real-data sections**
+
+Render metric strip, recent sessions, current progress, reminders derived from incomplete resources, and quick links. Omit recent activity and task widgets when no endpoint proves their content. Every metric label includes a tooltip or adjacent copy describing its source.
+
+- [ ] **Step 4: Verify empty, partial, and populated states**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx -t "Overview"`
+
+Expected: PASS for dashboard success, dashboard failure with derived counts, and empty world.
+
+- [ ] **Step 5: Commit Overview page**
+
+```powershell
+git add webui/src/pages/OverviewPage* webui/src/pages/selectors.ts webui/src/App.tsx webui/src/__tests__/pages.test.tsx
+git commit -m "feat(webui): add real-data world overview"
+```
+
+### Task 7: Migrate the Sessions Workbench
+
+**Files:**
+- Create: `webui/src/pages/SessionsPage.tsx`
+- Create: `webui/src/pages/SessionsPage.module.css`
+- Modify: `webui/src/components/MainPanel.tsx`
+- Modify: `webui/src/components/InspectorPanel.tsx`
+- Modify: `webui/src/App.tsx`
+- Test: `webui/src/__tests__/UserFlow.test.tsx`
+- Test: `webui/src/__tests__/components.test.tsx`
+
+**Interfaces:**
+- Consumes: existing `SessionList`, `ChatTimeline`, `Composer`, `InspectorPanel`, SSE state.
+- Produces: sessions-page three-column layout matching screenshot 9.
+
+- [ ] **Step 1: Update failing workflow expectations to the approved page structure**
+
+Assert session history, conversation title, Story/Files/Agents/Run tabs, composer, and current execution state are visible in one page.
+
+- [ ] **Step 2: Run session tests and preserve the two known Inspector failures**
+
+Run: `npm test -- --run src/__tests__/UserFlow.test.tsx src/__tests__/components.test.tsx`
+
+Expected: new Sessions assertions FAIL; existing Inspector text assertions still identify the baseline mismatch.
+
+- [ ] **Step 3: Compose the Sessions page and repair Inspector copy contracts**
+
+Move layout ownership out of `MainPanel`; keep message, send, cancel, approval, file, and inspector behaviors unchanged. Update stale tests to assert accessible Chinese labels actually rendered by the approved UI, including `世界时间` and `Create` rather than removed English sub-tabs.
+
+- [ ] **Step 4: Run session and component suites**
+
+Run: `npm test -- --run src/__tests__/UserFlow.test.tsx src/__tests__/components.test.tsx`
+
+Expected: all tests PASS, including the two baseline failures.
+
+- [ ] **Step 5: Commit Sessions migration**
+
+```powershell
+git add webui/src/pages/SessionsPage* webui/src/components/MainPanel.tsx webui/src/components/InspectorPanel.tsx webui/src/App.tsx webui/src/__tests__
+git commit -m "feat(webui): migrate sessions into desktop workspace"
+```
+
+### Task 8: Implement World and Characters Pages
+
+**Files:**
+- Create: `webui/src/pages/WorldPage.tsx`
+- Create: `webui/src/pages/WorldPage.module.css`
+- Create: `webui/src/pages/CharactersPage.tsx`
+- Create: `webui/src/pages/CharactersPage.module.css`
+- Modify: existing components under `webui/src/components/Inspector/Agent*`
+- Test: `webui/src/__tests__/pages.test.tsx`
+
+**Interfaces:**
+- World consumes: world detail, locations, factions, knowledge, timeline, graph APIs.
+- Characters consumes: agents, detail, images, diaries, relations, memory summaries, voice APIs.
+
+- [ ] **Step 1: Add failing resource selection and partial-failure tests**
+
+Verify the World page still displays world detail when graph loading fails. Verify selecting a character loads detail once and keeps the selection after list refresh.
+
+- [ ] **Step 2: Run World and Characters tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx -t "World|Characters"`
+
+Expected: FAIL because page modules are absent.
+
+- [ ] **Step 3: Implement both pages with existing editors**
+
+World uses independent `useResource` calls per section and renders only endpoint-backed sections. Characters uses `ResourceList` + `AgentCardView`/`AgentCardEdit` + an inspector rail for chapters, relations, and memories. Create, update, image upload, and delete refresh only affected resources.
+
+- [ ] **Step 4: Verify API calls, empty states, and mutation refresh**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx -t "World|Characters"`
+
+Expected: PASS; failed secondary requests show inline retry and retain primary data.
+
+- [ ] **Step 5: Commit World and Characters pages**
+
+```powershell
+git add webui/src/pages/WorldPage* webui/src/pages/CharactersPage* webui/src/components/Inspector/Agent* webui/src/__tests__/pages.test.tsx
+git commit -m "feat(webui): add world and character workspaces"
+```
+
+### Task 9: Implement Chapters and Scenes Pages
+
+**Files:**
+- Create: `webui/src/pages/ChaptersPage.tsx`
+- Create: `webui/src/pages/ChaptersPage.module.css`
+- Create: `webui/src/pages/ScenesPage.tsx`
+- Create: `webui/src/pages/ScenesPage.module.css`
+- Modify: `webui/src/components/ChapterEditor.tsx`
+- Modify: `webui/src/components/Inspector/EndSceneModal.tsx`
+- Test: `webui/src/__tests__/pages.test.tsx`
+- Test: `webui/src/__tests__/UserFlow.test.tsx`
+
+**Interfaces:**
+- Chapters produces reorder body `{ chapter_ids: string[] }` and editor navigation.
+- Scenes produces selected scene detail and real `endScene` result rendering.
+
+- [ ] **Step 1: Add failing chapter reorder and scene end tests**
+
+Assert drag-independent keyboard reorder sends exact IDs. Assert ending a scene does not mark it completed until the endpoint resolves and renders returned extraction counts.
+
+- [ ] **Step 2: Run narrative page tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx src/__tests__/UserFlow.test.tsx -t "Chapter|Scene"`
+
+Expected: FAIL because pages are missing.
+
+- [ ] **Step 3: Implement chapter grid/table and scene detail composition**
+
+Use button-based Move Previous/Next controls in addition to pointer reordering. Reuse ChapterEditor and EndSceneModal. Show consistency or extraction panels only when the scene response supplies them; otherwise omit the panel.
+
+- [ ] **Step 4: Verify tests and editor save regression suite**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx src/__tests__/UserFlow.test.tsx`
+
+Expected: PASS; editor dirty/saving/ conflict behavior remains covered.
+
+- [ ] **Step 5: Commit narrative planning pages**
+
+```powershell
+git add webui/src/pages/ChaptersPage* webui/src/pages/ScenesPage* webui/src/components/ChapterEditor.tsx webui/src/components/Inspector/EndSceneModal.tsx webui/src/__tests__
+git commit -m "feat(webui): add chapter and scene workspaces"
+```
+
+### Task 10: Implement Foreshadowing and Secrets Pages
+
+**Files:**
+- Create: `webui/src/pages/ForeshadowingPage.tsx`
+- Create: `webui/src/pages/ForeshadowingPage.module.css`
+- Create: `webui/src/pages/SecretsPage.tsx`
+- Create: `webui/src/pages/SecretsPage.module.css`
+- Modify: `webui/src/components/Inspector/CreateForeshadowingModal.tsx`
+- Modify: `webui/src/components/Inspector/CreateSecretModal.tsx`
+- Test: `webui/src/__tests__/pages.test.tsx`
+
+**Interfaces:**
+- Consumes real foreshadowing, secret, chapter, scene, and agent data.
+- Produces derived status helpers that return `null` when required fields are absent.
+
+- [ ] **Step 1: Add failing privacy and derived-status tests**
+
+Verify secret truth is absent from the DOM until Reveal is pressed. Verify overdue status appears only when both planned and current chapter positions are known.
+
+- [ ] **Step 2: Run focused tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx -t "Foreshadowing|Secrets"`
+
+Expected: FAIL because pages are missing.
+
+- [ ] **Step 3: Implement list-detail-inspector layouts**
+
+Use existing create modals. Add update/delete actions with confirmation. Build relation chips from real agent and narrative IDs; omit missing relations rather than inventing labels. Keep secret content in component state only after explicit reveal.
+
+- [ ] **Step 4: Verify privacy, filtering, and mutation tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx -t "Foreshadowing|Secrets"`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit thread and secret workspaces**
+
+```powershell
+git add webui/src/pages/ForeshadowingPage* webui/src/pages/SecretsPage* webui/src/components/Inspector/CreateForeshadowingModal.tsx webui/src/components/Inspector/CreateSecretModal.tsx webui/src/__tests__/pages.test.tsx
+git commit -m "feat(webui): add foreshadowing and secret workspaces"
+```
+
+### Task 11: Implement Files and Settings Pages
+
+**Files:**
+- Create: `webui/src/pages/FilesPage.tsx`
+- Create: `webui/src/pages/FilesPage.module.css`
+- Create: `webui/src/pages/SettingsPage.tsx`
+- Create: `webui/src/pages/SettingsPage.module.css`
+- Modify: `webui/src/components/SettingsPage.tsx`
+- Modify: `webui/src/components/Inspector/FilesInspector.tsx`
+- Test: `webui/src/__tests__/pages.test.tsx`
+- Test: `webui/src/__tests__/SettingsPanel.test.tsx`
+
+**Interfaces:**
+- Files consumes workspace file, content, save, open, and world-file-link APIs.
+- Settings consumes config, preferences, Runtime status, restart, logs, open/export diagnostics.
+
+- [ ] **Step 1: Add failing file conflict and settings capability tests**
+
+Verify a `409 file_conflict` preserves edited content and offers Reload/Copy. Verify settings fields without a write endpoint are not rendered as enabled controls.
+
+- [ ] **Step 2: Run focused tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx src/__tests__/SettingsPanel.test.tsx -t "Files|Settings|desktop"`
+
+Expected: FAIL on new page contracts.
+
+- [ ] **Step 3: Compose full-page file library and consolidated settings**
+
+Reuse file editor and desktop diagnostic behavior. Fetch content only after selection. Keep API keys masked. Display PostgreSQL/Neo4j status only if Runtime/config responses provide it; otherwise show the existing Runtime health status without invented database versions.
+
+- [ ] **Step 4: Verify file, config, and desktop tests**
+
+Run: `npm test -- --run src/__tests__/pages.test.tsx src/__tests__/SettingsPanel.test.tsx src/__tests__/DesktopBoot.test.tsx`
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit Files and Settings pages**
+
+```powershell
+git add webui/src/pages/FilesPage* webui/src/pages/SettingsPage* webui/src/components/SettingsPage.tsx webui/src/components/Inspector/FilesInspector.tsx webui/src/__tests__
+git commit -m "feat(webui): add file library and desktop settings"
+```
+
+### Task 12: Apply the Approved Visual System and Responsive Layout
+
+**Files:**
+- Modify: `webui/src/styles/global.css`
+- Modify: `webui/src/shell/DesktopShell.module.css`
+- Modify: all `webui/src/pages/*.module.css`
+- Modify: affected existing component CSS Modules.
+- Test: `webui/src/__tests__/shell.test.tsx`
+
+**Interfaces:**
+- Produces shared tokens: navy brand, cool gray surfaces, borders, typography, focus ring, semantic colors, motion durations.
+
+- [ ] **Step 1: Add source-level token and responsive contract tests**
+
+```ts
+expect(globalCss).toContain('--brand: #06266f');
+expect(shellCss).toMatch(/@media \(max-width: 1180px\)/);
+expect(shellCss).toMatch(/@media \(max-width: 980px\)/);
+```
+
+- [ ] **Step 2: Run shell visual-contract tests**
+
+Run: `npm test -- --run src/__tests__/shell.test.tsx`
+
+Expected: FAIL until approved tokens and breakpoints are present.
+
+- [ ] **Step 3: Implement exact shared tokens and layout behavior**
+
+Use `#06266f` as the deep navy starting token, then sample screenshots during browser comparison and adjust tokens once globally. At `<=1180px`, collapse inspector rails behind explicit buttons. At `<=980px`, reduce sidebar width and collapse secondary resource lists into drawers; never hide the central editor or primary action. Preserve visible focus and reduced motion.
+
+- [ ] **Step 4: Run formatting, lint, tests, and build**
+
+Run: `npm run format:check && npm run lint && npm test -- --run && npm run build`
+
+Expected: all commands PASS; Vite emits page chunks and no TypeScript errors.
+
+- [ ] **Step 5: Commit visual system**
+
+```powershell
+git add webui/src/styles webui/src/shell webui/src/pages webui/src/components webui/src/__tests__/shell.test.tsx
+git commit -m "style(webui): match approved desktop design system"
+```
+
+### Task 13: Browser Fidelity and Core Workflow Verification
+
+**Files:**
+- Create: `docs/qa/2026-06-19-windows-desktop-fidelity.md`
+- Create: `webui/src/__tests__/DesktopNavigation.test.tsx`
+- Modify: files identified by visual comparison.
+
+**Interfaces:**
+- Produces a ten-page fidelity ledger and reproducible screenshots.
+
+- [ ] **Step 1: Start the WebUI with a controlled real or fixture API**
+
+Run: `npm run dev -- --host 127.0.0.1`
+
+Expected: Vite reports `http://127.0.0.1:5173`; if the local Runtime is unavailable, use test interception that returns response-shaped fixtures already used by automated tests, clearly labeling screenshots as fixture-backed rather than runtime-backed.
+
+- [ ] **Step 2: Capture and compare every page at native design size**
+
+Use Browser/IAB at `1672 x 941`. Capture each page, then inspect the implementation screenshot and its corresponding supplied design image with `view_image` in the same QA pass. Record copy, layout, typography, palette, icon, spacing, and interaction differences in the fidelity ledger.
+
+- [ ] **Step 3: Fix every material mismatch and repeat comparison**
+
+For each page, repair clipped content, wrong container model, added copy, missing controls, icon mismatch, typography drift, and spacing drift. Record only API-caused intentional deviations, with the endpoint evidence explaining each deviation.
+
+- [ ] **Step 4: Verify default and minimum desktop windows**
+
+Check `1280 x 820` and `960 x 640`. Navigate all ten pages, switch worlds, open a list detail, send a session message, respond to an ask, resolve a creation request, edit/save a file, open settings, and invoke a non-destructive diagnostic action. Confirm no primary content is clipped and the browser console has no errors.
+
+- [ ] **Step 5: Run the complete verification suite**
+
+Run: `npm run format:check && npm run lint && npm test -- --run && npm run build && npm --prefix ../apps/desktop run check`
+
+Expected: WebUI formatting, lint, 106+ tests, and build PASS. Desktop preflight may report only the already documented missing Rust/Cargo and `merak.exe`; any source/config error fails this task.
+
+- [ ] **Step 6: Commit final QA fixes and ledger**
+
+```powershell
+git add webui docs/qa/2026-06-19-windows-desktop-fidelity.md
+git commit -m "test(webui): verify Windows desktop redesign"
+```
+
+---
+
+## Completion Audit
+
+Before claiming the goal complete, verify each requirement against authoritative evidence:
+
+1. `desktopPages` contains exactly ten top-level workspaces and every page is reachable through keyboard navigation.
+2. Search page code for hard-coded resource arrays; only navigation metadata and empty UI labels are allowed.
+3. Map every visible statistic and relationship in the fidelity ledger to an API field or named selector.
+4. Exercise `ask_user_requested`, ask response, `creation_requested`, and creation resolution end to end.
+5. Exercise editor save/conflict, approval, export, config save/test, Runtime restart, and diagnostics.
+6. Confirm the full Vitest suite, lint, formatting, and Vite build pass from fresh commands.
+7. Compare all ten page screenshots at `1672 x 941`, then verify `1280 x 820` and `960 x 640`.
+8. Confirm remaining deviations are listed with API or environment evidence.
+9. Confirm the only native build blocker is the externally missing Rust/Cargo and `merak.exe`; do not mark the goal complete while any source-level desktop failure remains.

From 7f252a2350722ec239a561488b72f41cd39f27a0 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 21:58:28 +0800
Subject: [PATCH 03/49] chore: ignore local worktrees

---
 .gitignore | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.gitignore b/.gitignore
index 9f120d1f..57a013a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,3 +8,4 @@ CMakeUserPresets.json
 .claude/
 /docs/
 .superpowers/
+.worktrees/

From 055a551cf53b4b350d9fe0a4cd4c62f859dc6237 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 22:20:01 +0800
Subject: [PATCH 04/49] refactor(webui): split shared API transport

---
 webui/src/__tests__/api.test.ts |  16 ++
 webui/src/api/client.ts         | 294 ++------------------------------
 webui/src/api/http.ts           | 194 +++++++++++++++++++++
 webui/src/api/index.ts          |   3 +
 webui/src/api/runtime.ts        |  84 +++++++++
 5 files changed, 307 insertions(+), 284 deletions(-)
 create mode 100644 webui/src/api/http.ts
 create mode 100644 webui/src/api/index.ts
 create mode 100644 webui/src/api/runtime.ts

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index 5f3fc566..c62e1084 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { request } from '../api/http';
 
 describe('api client', () => {
   beforeEach(() => {
@@ -9,6 +10,21 @@ describe('api client', () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([
+    [
+      { error: { code: 'world_not_found', message: 'World not found', retryable: false } },
+      'world_not_found',
+    ],
+    [
+      { ok: false, error: { code: 'file_conflict', message: 'Conflict', retryable: true } },
+      'file_conflict',
+    ],
+    [{ error: 'session not found' }, undefined],
+  ])('normalizes documented error shapes', async (payload, code) => {
+    vi.mocked(fetch).mockResolvedValueOnce(new Response(JSON.stringify(payload), { status: 409 }));
+    await expect(request('GET', '/failure')).rejects.toMatchObject({ status: 409, code });
+  });
+
   it('metadata() calls GET /v1/runtime', async () => {
     vi.mocked(fetch).mockResolvedValue({
       status: 200,
diff --git a/webui/src/api/client.ts b/webui/src/api/client.ts
index b9beedf4..4d7e7661 100644
--- a/webui/src/api/client.ts
+++ b/webui/src/api/client.ts
@@ -1,3 +1,5 @@
+import { ApiError, apiUrl, fallbackRequest, request, requestBlob, requestForm } from './http';
+import { runtimeApi } from './runtime';
 import type {
   AdvanceWorldTimeResponse,
   AgentDetailResponse,
@@ -55,209 +57,7 @@ import type {
   WorldTimeResponse,
 } from './types';
 
-let apiBase = import.meta.env.VITE_API_BASE ?? '';
-
-export function setApiBase(base: string) {
-  apiBase = base.replace(/\/$/, '');
-}
-
-export function getApiBase() {
-  return apiBase;
-}
-
-export function apiUrl(path: string) {
-  if (/^https?:\/\//i.test(path)) return path;
-  return `${apiBase}${path.startsWith('/') ? path : `/${path}`}`;
-}
-
-export class ApiError extends Error {
-  status: number;
-  code?: string;
-  constructor(message: string, status: number, code?: string) {
-    super(message);
-    this.name = 'ApiError';
-    this.status = status;
-    this.code = code;
-  }
-}
-
-export function formatApiError(
-  error: unknown,
-  fallback = '操作失败，请稍后重试。',
-  t?: (key: string) => string,
-) {
-  if (error instanceof ApiError) {
-    if (t && error.code) {
-      const key = `error.${error.code}`;
-      const translated = t(key);
-      if (translated !== key) return translated;
-    }
-    switch (error.code) {
-      case 'version_conflict':
-        return '内容已在后端更新，请刷新后再保存。';
-      case 'file_conflict':
-        return '文件已被其他操作修改，请刷新后再保存。';
-      case 'session_not_found':
-        return '会话不存在，可能已被删除或归档。';
-      case 'session_busy':
-        return '会话正在进行中，请等待当前操作完成后再发送消息。';
-      case 'run_not_found':
-        return '运行记录不存在。';
-      case 'approval_not_found':
-        return '审批请求不存在或已过期。';
-      case 'invalid_request':
-        return error.message || '请求格式有误，请检查输入。';
-      case 'invalid_path':
-        return '文件路径不在允许的范围内。';
-      case 'file_not_found':
-        return '文件不存在或已被删除。';
-      case 'unsupported_file_type':
-        return '不支持该文件类型。';
-
-      // World
-      case 'world_not_found':
-        return '世界不存在或已被删除。';
-      case 'world_create_failed':
-        return '创建世界失败，请检查名称是否重复。';
-      case 'world_name_required':
-        return '世界名称不能为空。';
-
-      // Agent
-      case 'agent_not_found':
-        return '角色不存在或已被删除。';
-      case 'agent_create_failed':
-        return '创建角色失败，请检查必填字段。';
-      case 'agent_version_conflict':
-        return '角色信息已被其他操作更新，请刷新后再试。';
-
-      // Scene
-      case 'scene_not_found':
-        return '场景不存在或已被删除。';
-      case 'scene_create_failed':
-        return '创建场景失败，请确认章节存在。';
-      case 'scene_end_failed':
-        return '结束场景失败，场景可能已经结束。';
-      case 'scene_status_invalid':
-        return '场景当前状态不支持此操作。';
-
-      // Chapter
-      case 'chapter_not_found':
-        return '章节不存在或已被删除。';
-      case 'chapter_update_failed':
-        return '章节更新失败，请刷新后再试。';
-
-      // Diary
-      case 'information_boundary_leak':
-        return '日记内容包含角色不应知晓的信息，已被信息边界过滤。';
-      case 'diary_write_failed':
-        return '日记写入失败，请稍后重试。';
-
-      // Foreshadowing / Secret
-      case 'foreshadow_not_found':
-        return '伏笔不存在，可能已被删除。';
-      case 'foreshadowing_not_found':
-        return '伏笔不存在或已被删除。';
-      case 'secret_not_found':
-        return '秘密不存在或已被删除。';
-      case 'secret_status_invalid':
-        return '秘密当前状态不支持此操作。';
-
-      // Pipeline
-      case 'pipeline_not_available':
-        return '创作流水线暂不可用，请确认后端已启用 worldbuilding pipeline。';
-      case 'pipeline_advance_blocked':
-        return '阶段推进被阻止：当前阶段条件未全部满足。请先完成当前阶段的所有要求。';
-      case 'pipeline_phase_invalid':
-        return '目标阶段无效，请确认阶段名称正确。';
-      case 'workflow_not_found':
-        return '指定的 Pipeline 工作流不存在。';
-
-      // Image service
-      case 'image_service_not_available':
-        return '图片服务未启用，请确认后端 Image Service 已初始化。';
-      case 'image_upload_failed':
-        return '图片上传失败，请确认文件格式和大小符合要求。';
-      case 'invalid_image_type':
-        return '图片类型必须是头像或人设图。';
-      case 'image_not_found':
-        return '图片不存在或已被删除。';
-
-      // Config
-      case 'config_load_failed':
-        return '配置加载失败，请检查后端服务状态。';
-      case 'config_save_failed':
-        return '配置保存失败，请稍后重试。';
-      case 'title_generation_failed':
-        return '标题生成失败，请稍后重试。';
-      case 'test_failed':
-        return `连接测试失败：${error.message}`;
-      case 'test_unavailable':
-        return '连接测试暂不可用，请检查后端配置。';
-
-      // General
-      case 'missing_param':
-        return error.message || '缺少必要参数，请检查输入。';
-      case 'database_error':
-        return '数据库操作失败，请稍后重试。';
-
-      default:
-        return error.message || (t ? t('error.unknown') : fallback);
-    }
-  }
-  return error instanceof Error ? error.message : (t ? t('error.unknown') : fallback);
-}
-
-async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
-  const opts: RequestInit = {
-    method,
-    headers: { 'Content-Type': 'application/json' },
-  };
-  if (body !== undefined) {
-    opts.body = JSON.stringify(body);
-  }
-  const res = await fetch(apiUrl(path), opts);
-  return parseJsonResponse<T>(res);
-}
-
-async function parseJsonResponse<T>(res: Response): Promise<T> {
-  let json: unknown;
-  try {
-    json = await res.json();
-  } catch {
-    const text = await res.text().catch(() => '<unreadable>');
-    throw new Error(`Non-JSON response (${res.status}): ${text.slice(0, 200)}`);
-  }
-  if (res.status >= 400) {
-    const error = (
-      json as { error?: { message?: string; code?: string } | string; message?: string }
-    ).error;
-    const message =
-      typeof error === 'string'
-        ? error
-        : (error?.message ?? (json as { message?: string }).message ?? `HTTP ${res.status}`);
-    const code = typeof error === 'object' && error !== null ? error.code : undefined;
-    throw new ApiError(message, res.status, code);
-  }
-  return json as T;
-}
-
-async function requestForm<T>(path: string, body: FormData): Promise<T> {
-  const res = await fetch(apiUrl(path), { method: 'POST', body });
-  return parseJsonResponse<T>(res);
-}
-
-async function requestBlob<T>(method: string, path: string, body?: Blob): Promise<T> {
-  const res = await fetch(apiUrl(path), { method, body });
-  return parseJsonResponse<T>(res);
-}
-
-async function fallbackRequest<T>(path: string, fallback: T): Promise<T> {
-  try {
-    return await request<T>('GET', path);
-  } catch {
-    return fallback;
-  }
-}
+export { ApiError, apiUrl, formatApiError, getApiBase, setApiBase } from './http';
 
 const fallbackCapabilities: CapabilitiesResponse = {
   ok: true,
@@ -272,74 +72,11 @@ const fallbackCapabilities: CapabilitiesResponse = {
 };
 
 export const api = {
-  metadata: () => request<RuntimeMetadata>('GET', '/v1/runtime'),
+  ...runtimeApi,
 
   capabilities: () =>
     fallbackRequest<CapabilitiesResponse>('/api/webui/capabilities', fallbackCapabilities),
 
-  createSession: (title = '', worldId?: string, agentId?: string) => {
-    const body: Record<string, string> = { title };
-    if (worldId) body.world_id = worldId;
-    if (agentId) body.agent_id = agentId;
-    return request<CreateSessionResponse>('POST', '/v1/sessions', body);
-  },
-
-  archiveSession: (session: SessionSummary, archived: boolean) =>
-    request<ArchiveSessionResponse>('POST', `/v1/sessions/${session.id}/archive`, { archived }),
-
-  updateSession: (id: string, title: string) =>
-    request<UpdateSessionResponse>('PATCH', `/v1/sessions/${id}`, { title }),
-
-  generateTitle: (id: string) =>
-    request<GenerateTitleResponse>('POST', `/v1/sessions/${id}/generate-title`),
-
-  listSessions: (worldId?: string) => {
-    const query = worldId ? `?world_id=${encodeURIComponent(worldId)}` : '';
-    return request<SessionListResponse>('GET', `/v1/sessions${query}`);
-  },
-
-  getOrCreateAgentSession: (worldId: string, agentId: string) =>
-    request<{ session: SessionSummary; created: boolean }>(
-      'GET',
-      `/v1/worlds/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}/session`,
-    ),
-
-  getSession: (id: string) => request<SessionSummary>('GET', `/v1/sessions/${id}`),
-
-  getRun: (runId: string) => request<RunDetailResponse>('GET', `/v1/runs/${runId}`),
-
-  events: (id: string, after = 0) =>
-    request<{ events: unknown[] }>('GET', `/v1/sessions/${id}/events?after=${after}`),
-
-  memory: (id: string) =>
-    request<{ session_id: string; items: unknown[] }>('GET', `/v1/sessions/${id}/memory`),
-
-  startRun: (id: string, message: string, model = '') =>
-    request<StartRunResponse>('POST', `/v1/sessions/${id}/runs`, {
-      message,
-      ...(model ? { model } : {}),
-    }),
-
-  startDelegation: (
-    id: string,
-    pattern: string,
-    agents: string[],
-    task: string,
-    aggregation = 'all_results',
-  ) =>
-    request<{ delegation_id: string; parent_run_id: string; session_id: string }>(
-      'POST',
-      `/v1/sessions/${id}/delegations`,
-      { pattern, agents, task, aggregation },
-    ),
-
-  resolveApproval: (id: string, allow: boolean) =>
-    request<ApprovalResponse>('POST', `/v1/approvals/${id}`, {
-      decision: allow ? 'allow' : 'deny',
-    }),
-
-  cancelRun: (id: string) => request<CancelRunResponse>('POST', `/v1/runs/${id}/cancel`),
-
   listWorlds: () => request<WorldListResponse>('GET', '/api/worldbuilding/worlds'),
 
   createWorld: (name: string, description = '') =>
@@ -425,13 +162,11 @@ export const api = {
     ),
 
   saveWorkspaceFile: (path: string, content: string, version?: string) =>
-    request<SaveWorkspaceFileResponse>(
-      'PUT',
-      '/api/workspace/files/content',
-      { path, content, version },
-    ),
-
-  sseUrl: (id: string) => `${apiBase}/v1/sessions/${id}/events/stream`,
+    request<SaveWorkspaceFileResponse>('PUT', '/api/workspace/files/content', {
+      path,
+      content,
+      version,
+    }),
 
   getConfig: () => request<LlmConfigFull>('GET', '/api/config/llm'),
 
@@ -449,8 +184,7 @@ export const api = {
   testConfig: () => request<OkResponse>('POST', '/api/config/llm/test'),
 
   // Preferences
-  getPreferences: () =>
-    request<PreferencesResponse>('GET', '/api/config/preferences'),
+  getPreferences: () => request<PreferencesResponse>('GET', '/api/config/preferences'),
 
   savePreferences: (prefs: {
     default_genre?: string;
@@ -699,14 +433,6 @@ export const api = {
   // World detail
   getWorldDetail: (worldId: string) =>
     request<WorldDetailResponse>('GET', `/api/worldbuilding/worlds/${worldId}`),
-
-  // Creation resolution — wired for future SSE-driven creation approval flow
-  // The backend emits creation requests via SSE; the UI will call this to allow/deny with optional modifications.
-  resolveCreation: (id: string, decision: string, modifications?: Record<string, unknown>) =>
-    request<ResolveCreationResponse>('POST', `/v1/creations/${id}/resolve`, {
-      decision,
-      modifications,
-    }),
 };
 
 export async function getPipelineState(worldId: string): Promise<PipelineViewData> {
diff --git a/webui/src/api/http.ts b/webui/src/api/http.ts
new file mode 100644
index 00000000..15d4b620
--- /dev/null
+++ b/webui/src/api/http.ts
@@ -0,0 +1,194 @@
+let apiBase = import.meta.env.VITE_API_BASE ?? '';
+
+export function setApiBase(base: string) {
+  apiBase = base.replace(/\/$/, '');
+}
+
+export function getApiBase() {
+  return apiBase;
+}
+
+export function apiUrl(path: string) {
+  if (/^https?:\/\//i.test(path)) return path;
+  return `${apiBase}${path.startsWith('/') ? path : `/${path}`}`;
+}
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public status: number,
+    public code?: string,
+    public retryable = false,
+  ) {
+    super(message);
+    this.name = 'ApiError';
+  }
+}
+
+async function parseJsonResponse<T>(response: Response): Promise<T> {
+  const payload = await response.json().catch(() => ({}));
+  if (response.status >= 400) {
+    const raw = payload?.error;
+    const detail = typeof raw === 'object' && raw ? raw : {};
+    throw new ApiError(
+      detail.message ?? (typeof raw === 'string' ? raw : `Request failed (${response.status})`),
+      response.status,
+      detail.code,
+      Boolean(detail.retryable),
+    );
+  }
+  return payload as T;
+}
+
+export async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
+  const response = await fetch(apiUrl(path), {
+    method,
+    headers: body === undefined ? undefined : { 'Content-Type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return parseJsonResponse<T>(response);
+}
+
+export async function requestForm<T>(path: string, form: FormData): Promise<T> {
+  const response = await fetch(apiUrl(path), { method: 'POST', body: form });
+  return parseJsonResponse<T>(response);
+}
+
+export async function requestBlob<T>(method: string, path: string, body?: Blob): Promise<T> {
+  const response = await fetch(apiUrl(path), { method, body });
+  return parseJsonResponse<T>(response);
+}
+
+export async function fallbackRequest<T>(path: string, fallback: T): Promise<T> {
+  try {
+    return await request<T>('GET', path);
+  } catch {
+    return fallback;
+  }
+}
+
+export function formatApiError(
+  error: unknown,
+  fallback = '操作失败，请稍后重试。',
+  t?: (key: string) => string,
+) {
+  if (error instanceof ApiError) {
+    if (t && error.code) {
+      const key = `error.${error.code}`;
+      const translated = t(key);
+      if (translated !== key) return translated;
+    }
+    switch (error.code) {
+      case 'version_conflict':
+        return '内容已在后端更新，请刷新后再保存。';
+      case 'file_conflict':
+        return '文件已被其他操作修改，请刷新后再保存。';
+      case 'session_not_found':
+        return '会话不存在，可能已被删除或归档。';
+      case 'session_busy':
+        return '会话正在进行中，请等待当前操作完成后再发送消息。';
+      case 'run_not_found':
+        return '运行记录不存在。';
+      case 'approval_not_found':
+        return '审批请求不存在或已过期。';
+      case 'invalid_request':
+        return error.message || '请求格式有误，请检查输入。';
+      case 'invalid_path':
+        return '文件路径不在允许的范围内。';
+      case 'file_not_found':
+        return '文件不存在或已被删除。';
+      case 'unsupported_file_type':
+        return '不支持该文件类型。';
+
+      // World
+      case 'world_not_found':
+        return '世界不存在或已被删除。';
+      case 'world_create_failed':
+        return '创建世界失败，请检查名称是否重复。';
+      case 'world_name_required':
+        return '世界名称不能为空。';
+
+      // Agent
+      case 'agent_not_found':
+        return '角色不存在或已被删除。';
+      case 'agent_create_failed':
+        return '创建角色失败，请检查必填字段。';
+      case 'agent_version_conflict':
+        return '角色信息已被其他操作更新，请刷新后再试。';
+
+      // Scene
+      case 'scene_not_found':
+        return '场景不存在或已被删除。';
+      case 'scene_create_failed':
+        return '创建场景失败，请确认章节存在。';
+      case 'scene_end_failed':
+        return '结束场景失败，场景可能已经结束。';
+      case 'scene_status_invalid':
+        return '场景当前状态不支持此操作。';
+
+      // Chapter
+      case 'chapter_not_found':
+        return '章节不存在或已被删除。';
+      case 'chapter_update_failed':
+        return '章节更新失败，请刷新后再试。';
+
+      // Diary
+      case 'information_boundary_leak':
+        return '日记内容包含角色不应知晓的信息，已被信息边界过滤。';
+      case 'diary_write_failed':
+        return '日记写入失败，请稍后重试。';
+
+      // Foreshadowing / Secret
+      case 'foreshadow_not_found':
+        return '伏笔不存在，可能已被删除。';
+      case 'foreshadowing_not_found':
+        return '伏笔不存在或已被删除。';
+      case 'secret_not_found':
+        return '秘密不存在或已被删除。';
+      case 'secret_status_invalid':
+        return '秘密当前状态不支持此操作。';
+
+      // Pipeline
+      case 'pipeline_not_available':
+        return '创作流水线暂不可用，请确认后端已启用 worldbuilding pipeline。';
+      case 'pipeline_advance_blocked':
+        return '阶段推进被阻止：当前阶段条件未全部满足。请先完成当前阶段的所有要求。';
+      case 'pipeline_phase_invalid':
+        return '目标阶段无效，请确认阶段名称正确。';
+      case 'workflow_not_found':
+        return '指定的 Pipeline 工作流不存在。';
+
+      // Image service
+      case 'image_service_not_available':
+        return '图片服务未启用，请确认后端 Image Service 已初始化。';
+      case 'image_upload_failed':
+        return '图片上传失败，请确认文件格式和大小符合要求。';
+      case 'invalid_image_type':
+        return '图片类型必须是头像或人设图。';
+      case 'image_not_found':
+        return '图片不存在或已被删除。';
+
+      // Config
+      case 'config_load_failed':
+        return '配置加载失败，请检查后端服务状态。';
+      case 'config_save_failed':
+        return '配置保存失败，请稍后重试。';
+      case 'title_generation_failed':
+        return '标题生成失败，请稍后重试。';
+      case 'test_failed':
+        return `连接测试失败：${error.message}`;
+      case 'test_unavailable':
+        return '连接测试暂不可用，请检查后端配置。';
+
+      // General
+      case 'missing_param':
+        return error.message || '缺少必要参数，请检查输入。';
+      case 'database_error':
+        return '数据库操作失败，请稍后重试。';
+
+      default:
+        return error.message || (t ? t('error.unknown') : fallback);
+    }
+  }
+  return error instanceof Error ? error.message : t ? t('error.unknown') : fallback;
+}
diff --git a/webui/src/api/index.ts b/webui/src/api/index.ts
new file mode 100644
index 00000000..347a593e
--- /dev/null
+++ b/webui/src/api/index.ts
@@ -0,0 +1,3 @@
+export * from './http';
+export { runtimeApi } from './runtime';
+export { api } from './client';
diff --git a/webui/src/api/runtime.ts b/webui/src/api/runtime.ts
new file mode 100644
index 00000000..6e804cf5
--- /dev/null
+++ b/webui/src/api/runtime.ts
@@ -0,0 +1,84 @@
+import { getApiBase, request } from './http';
+import type {
+  ApprovalResponse,
+  ArchiveSessionResponse,
+  CancelRunResponse,
+  CreateSessionResponse,
+  GenerateTitleResponse,
+  ResolveCreationResponse,
+  RunDetailResponse,
+  RuntimeMetadata,
+  SessionListResponse,
+  SessionSummary,
+  StartRunResponse,
+  UpdateSessionResponse,
+} from './types';
+
+export const runtimeApi = {
+  metadata: () => request<RuntimeMetadata>('GET', '/v1/runtime'),
+
+  createSession: (title = '', worldId?: string, agentId?: string) => {
+    const body: Record<string, string> = { title };
+    if (worldId) body.world_id = worldId;
+    if (agentId) body.agent_id = agentId;
+    return request<CreateSessionResponse>('POST', '/v1/sessions', body);
+  },
+
+  archiveSession: (session: SessionSummary, archived: boolean) =>
+    request<ArchiveSessionResponse>('POST', `/v1/sessions/${session.id}/archive`, { archived }),
+
+  updateSession: (id: string, title: string) =>
+    request<UpdateSessionResponse>('PATCH', `/v1/sessions/${id}`, { title }),
+
+  generateTitle: (id: string) =>
+    request<GenerateTitleResponse>('POST', `/v1/sessions/${id}/generate-title`),
+
+  listSessions: (worldId?: string) => {
+    const query = worldId ? `?world_id=${encodeURIComponent(worldId)}` : '';
+    return request<SessionListResponse>('GET', `/v1/sessions${query}`);
+  },
+
+  getOrCreateAgentSession: (worldId: string, agentId: string) =>
+    request<{ session: SessionSummary; created: boolean }>(
+      'GET',
+      `/v1/worlds/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}/session`,
+    ),
+
+  getSession: (id: string) => request<SessionSummary>('GET', `/v1/sessions/${id}`),
+  getRun: (runId: string) => request<RunDetailResponse>('GET', `/v1/runs/${runId}`),
+  events: (id: string, after = 0) =>
+    request<{ events: unknown[] }>('GET', `/v1/sessions/${id}/events?after=${after}`),
+  memory: (id: string) =>
+    request<{ session_id: string; items: unknown[] }>('GET', `/v1/sessions/${id}/memory`),
+
+  startRun: (id: string, message: string, model = '') =>
+    request<StartRunResponse>('POST', `/v1/sessions/${id}/runs`, {
+      message,
+      ...(model ? { model } : {}),
+    }),
+
+  startDelegation: (
+    id: string,
+    pattern: string,
+    agents: string[],
+    task: string,
+    aggregation = 'all_results',
+  ) =>
+    request<{ delegation_id: string; parent_run_id: string; session_id: string }>(
+      'POST',
+      `/v1/sessions/${id}/delegations`,
+      { pattern, agents, task, aggregation },
+    ),
+
+  resolveApproval: (id: string, allow: boolean) =>
+    request<ApprovalResponse>('POST', `/v1/approvals/${id}`, {
+      decision: allow ? 'allow' : 'deny',
+    }),
+  cancelRun: (id: string) => request<CancelRunResponse>('POST', `/v1/runs/${id}/cancel`),
+  resolveCreation: (id: string, decision: string, modifications?: Record<string, unknown>) =>
+    request<ResolveCreationResponse>('POST', `/v1/creations/${id}/resolve`, {
+      decision,
+      modifications,
+    }),
+  sseUrl: (id: string) => `${getApiBase()}/v1/sessions/${id}/events/stream`,
+};

From cf75e80445452bc73fe7415a824c321bda3c0882 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 22:33:21 +0800
Subject: [PATCH 05/49] fix(webui): reject non-success HTTP responses

---
 webui/src/__tests__/api.test.ts | 15 +++++++++++++++
 webui/src/api/http.ts           |  2 +-
 2 files changed, 16 insertions(+), 1 deletion(-)

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index c62e1084..250a5dba 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -25,8 +25,18 @@ describe('api client', () => {
     await expect(request('GET', '/failure')).rejects.toMatchObject({ status: 409, code });
   });
 
+  it('rejects non-success 3xx responses with ApiError', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(new Response(null, { status: 304 }));
+
+    await expect(request('GET', '/not-modified')).rejects.toMatchObject({
+      name: 'ApiError',
+      status: 304,
+    });
+  });
+
   it('metadata() calls GET /v1/runtime', async () => {
     vi.mocked(fetch).mockResolvedValue({
+      ok: true,
       status: 200,
       json: async () => ({ model: 'gpt-4o' }),
     } as Response);
@@ -42,6 +52,7 @@ describe('api client', () => {
 
   it('createSession() calls POST /v1/sessions', async () => {
     vi.mocked(fetch).mockResolvedValue({
+      ok: true,
       status: 201,
       json: async () => ({ session_id: 's1' }),
     } as Response);
@@ -98,6 +109,7 @@ describe('api client', () => {
 
   it('worldbuilding readers call the selected world endpoints', async () => {
     vi.mocked(fetch).mockResolvedValue({
+      ok: true,
       status: 200,
       json: async () => ({ ok: true, agents: [] }),
     } as Response);
@@ -132,6 +144,7 @@ describe('api client', () => {
 
   it('saveConfig() sends max_output_tokens to the backend', async () => {
     vi.mocked(fetch).mockResolvedValue({
+      ok: true,
       status: 200,
       json: async () => ({ ok: true }),
     } as Response);
@@ -162,6 +175,7 @@ describe('api client', () => {
 
   it('deleteWorld() calls DELETE /api/worldbuilding/worlds/:id', async () => {
     vi.mocked(fetch).mockResolvedValue({
+      ok: true,
       status: 200,
       json: async () => ({ ok: true, deleted: 'world_1' }),
     } as Response);
@@ -177,6 +191,7 @@ describe('api client', () => {
 
   it('advanceWorldTime() calls POST /api/worldbuilding/:worldId/time/advance', async () => {
     vi.mocked(fetch).mockResolvedValue({
+      ok: true,
       status: 200,
       json: async () => ({ ok: true, world_time: 'Day 2 Dawn' }),
     } as Response);
diff --git a/webui/src/api/http.ts b/webui/src/api/http.ts
index 15d4b620..923d73cd 100644
--- a/webui/src/api/http.ts
+++ b/webui/src/api/http.ts
@@ -27,7 +27,7 @@ export class ApiError extends Error {
 
 async function parseJsonResponse<T>(response: Response): Promise<T> {
   const payload = await response.json().catch(() => ({}));
-  if (response.status >= 400) {
+  if (!response.ok) {
     const raw = payload?.error;
     const detail = typeof raw === 'object' && raw ? raw : {};
     throw new ApiError(

From 592dd5da0a9251c5e9ba84ec7c62d03feaa9fe80 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 22:48:04 +0800
Subject: [PATCH 06/49] feat(webui): add typed worldbuilding APIs

---
 webui/src/__tests__/api.test.ts | 27 +++++++++++
 webui/src/api/config.ts         | 22 +++++++++
 webui/src/api/files.ts          | 37 +++++++++++++++
 webui/src/api/index.ts          |  4 ++
 webui/src/api/types.ts          | 46 +++++++++++++++++++
 webui/src/api/worldbuilding.ts  | 79 +++++++++++++++++++++++++++++++++
 6 files changed, 215 insertions(+)
 create mode 100644 webui/src/api/config.ts
 create mode 100644 webui/src/api/files.ts
 create mode 100644 webui/src/api/worldbuilding.ts

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index 250a5dba..f538f727 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { filesApi, worldbuildingApi } from '../api';
 import { request } from '../api/http';
 
 describe('api client', () => {
@@ -207,4 +208,30 @@ describe('api client', () => {
       }),
     );
   });
+
+  it('reorders chapters with the documented body', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ ok: true }), { status: 200 }),
+    );
+
+    await worldbuildingApi.reorderChapters('w 1', ['c1', 'c2']);
+
+    expect(vi.mocked(fetch)).toHaveBeenCalledWith(
+      expect.stringContaining('/api/worldbuilding/w%201/chapters/reorder'),
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ chapter_ids: ['c1', 'c2'] }),
+      }),
+    );
+  });
+
+  it('encodes a linked file path when deleting it', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ ok: true }), { status: 200 }),
+    );
+
+    await filesApi.unlinkWorldFile('w1', '章节/第一章.md');
+
+    expect(vi.mocked(fetch).mock.calls[0][0]).toContain(encodeURIComponent('章节/第一章.md'));
+  });
 });
diff --git a/webui/src/api/config.ts b/webui/src/api/config.ts
new file mode 100644
index 00000000..886196e5
--- /dev/null
+++ b/webui/src/api/config.ts
@@ -0,0 +1,22 @@
+import { request } from './http';
+import type { LlmConfigFull, OkResponse, PreferencesResponse, UserPreferences } from './types';
+
+export interface SaveLlmConfig {
+  provider?: string;
+  api_key?: string;
+  api_base_url?: string;
+  default_model?: string;
+  max_output_tokens?: number;
+  temperature?: number;
+  context_memory_length?: 'short' | 'medium' | 'long';
+  writer_model?: string;
+}
+
+export const configApi = {
+  getConfig: () => request<LlmConfigFull>('GET', '/api/config/llm'),
+  saveConfig: (config: SaveLlmConfig) => request<OkResponse>('POST', '/api/config/llm', config),
+  testConfig: () => request<OkResponse>('POST', '/api/config/llm/test'),
+  getPreferences: () => request<PreferencesResponse>('GET', '/api/config/preferences'),
+  savePreferences: (preferences: Partial<UserPreferences>) =>
+    request<OkResponse>('PUT', '/api/config/preferences', preferences),
+};
diff --git a/webui/src/api/files.ts b/webui/src/api/files.ts
new file mode 100644
index 00000000..10dbe160
--- /dev/null
+++ b/webui/src/api/files.ts
@@ -0,0 +1,37 @@
+import { request } from './http';
+import type { OkResponse, ResourceListResponse, WorldFileLink } from './types';
+
+type FileListResponse = ResourceListResponse<WorldFileLink> & {
+  files?: WorldFileLink[];
+};
+
+const filesPath = (worldId: string) => `/api/worldbuilding/${encodeURIComponent(worldId)}/files`;
+
+function fileTarget(link?: Pick<WorldFileLink, 'entity_type' | 'entity_id'>) {
+  if (!link?.entity_type || !link.entity_id) return undefined;
+  return { target_type: link.entity_type, target_id: link.entity_id };
+}
+
+export const filesApi = {
+  listWorldFiles: async (worldId: string): Promise<ResourceListResponse<WorldFileLink>> => {
+    const response = await request<FileListResponse>('GET', filesPath(worldId));
+    return { ...response, items: response.items ?? response.files };
+  },
+
+  linkWorldFile: (worldId: string, link: WorldFileLink) =>
+    request<OkResponse>('POST', filesPath(worldId), {
+      file_path: link.file_path,
+      ...fileTarget(link),
+    }),
+
+  unlinkWorldFile: (
+    worldId: string,
+    filePath: string,
+    link?: Pick<WorldFileLink, 'entity_type' | 'entity_id'>,
+  ) =>
+    request<OkResponse>(
+      'DELETE',
+      `${filesPath(worldId)}/${encodeURIComponent(filePath)}`,
+      fileTarget(link),
+    ),
+};
diff --git a/webui/src/api/index.ts b/webui/src/api/index.ts
index 347a593e..5f26a32c 100644
--- a/webui/src/api/index.ts
+++ b/webui/src/api/index.ts
@@ -1,3 +1,7 @@
+export { configApi } from './config';
+export { filesApi } from './files';
 export * from './http';
 export { runtimeApi } from './runtime';
+export * from './types';
+export { worldbuildingApi } from './worldbuilding';
 export { api } from './client';
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 8047c44d..83620479 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -682,3 +682,49 @@ export interface ExportResult {
   file_path: string;
   total_chars: number;
 }
+
+export interface ResourceListResponse<T> {
+  ok?: boolean;
+  items?: T[];
+}
+
+export interface LocationItem {
+  id: string;
+  name: string;
+  description?: string;
+  version?: number;
+}
+
+export interface KnowledgeItem {
+  id: string;
+  title: string;
+  content?: string;
+  tags?: string[];
+  version?: number;
+}
+
+export interface FactionItem {
+  id: string;
+  name: string;
+  description?: string;
+  version?: number;
+}
+
+export interface TimelineEvent {
+  id: string;
+  title: string;
+  world_time?: string;
+  description?: string;
+}
+
+export interface GraphEntity {
+  id: string;
+  type: string;
+  name: string;
+}
+
+export interface WorldFileLink {
+  file_path: string;
+  entity_type?: string;
+  entity_id?: string;
+}
diff --git a/webui/src/api/worldbuilding.ts b/webui/src/api/worldbuilding.ts
new file mode 100644
index 00000000..719f8166
--- /dev/null
+++ b/webui/src/api/worldbuilding.ts
@@ -0,0 +1,79 @@
+import { request } from './http';
+import type {
+  FactionItem,
+  GraphEntity,
+  KnowledgeItem,
+  LocationItem,
+  OkResponse,
+  ResourceListResponse,
+  TimelineEvent,
+} from './types';
+
+type NamedListResponse<T> = ResourceListResponse<T> & Record<string, unknown>;
+
+function adaptList<T>(response: NamedListResponse<T>, key: string): ResourceListResponse<T> {
+  const namedItems = response[key];
+  return {
+    ...response,
+    items: response.items ?? (Array.isArray(namedItems) ? (namedItems as T[]) : undefined),
+  };
+}
+
+const worldPath = (worldId: string) => `/api/worldbuilding/${encodeURIComponent(worldId)}`;
+const resourcePath = (worldId: string, resource: string, resourceId?: string) =>
+  `${worldPath(worldId)}/${resource}${resourceId ? `/${encodeURIComponent(resourceId)}` : ''}`;
+
+export const worldbuildingApi = {
+  getDashboard: (worldId: string) =>
+    request<{ ok?: boolean; dashboard?: Record<string, unknown> }>(
+      'POST',
+      `${worldPath(worldId)}/dashboard`,
+    ),
+
+  listLocations: async (worldId: string) =>
+    adaptList<LocationItem>(
+      await request<NamedListResponse<LocationItem>>('GET', resourcePath(worldId, 'locations')),
+      'locations',
+    ),
+
+  listKnowledge: async (worldId: string) =>
+    adaptList<KnowledgeItem>(
+      await request<NamedListResponse<KnowledgeItem>>('GET', resourcePath(worldId, 'knowledge')),
+      'knowledge',
+    ),
+
+  listFactions: async (worldId: string) =>
+    adaptList<FactionItem>(
+      await request<NamedListResponse<FactionItem>>('GET', resourcePath(worldId, 'factions')),
+      'factions',
+    ),
+
+  getTimeline: async (worldId: string) =>
+    adaptList<TimelineEvent>(
+      await request<NamedListResponse<TimelineEvent>>('GET', resourcePath(worldId, 'timeline')),
+      'events',
+    ),
+
+  listGraphEntities: async (worldId: string) =>
+    adaptList<GraphEntity>(
+      await request<NamedListResponse<GraphEntity>>(
+        'GET',
+        resourcePath(worldId, 'knowledge-graph/entities'),
+      ),
+      'entities',
+    ),
+
+  reorderChapters: (worldId: string, chapterIds: string[]) =>
+    request<OkResponse>('POST', resourcePath(worldId, 'chapters/reorder'), {
+      chapter_ids: chapterIds,
+    }),
+
+  deleteLocation: (worldId: string, locationId: string) =>
+    request<OkResponse>('DELETE', resourcePath(worldId, 'locations', locationId)),
+
+  deleteKnowledge: (worldId: string, knowledgeId: string) =>
+    request<OkResponse>('DELETE', resourcePath(worldId, 'knowledge', knowledgeId)),
+
+  deleteFaction: (worldId: string, factionId: string) =>
+    request<OkResponse>('DELETE', resourcePath(worldId, 'factions', factionId)),
+};

From c18bb2bfb760cf5016a2d374b21c8a70f629b33c Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 22:51:06 +0800
Subject: [PATCH 07/49] docs: align desktop plan with API contract

---
 .../plans/2026-06-19-windows-desktop-redesign.md     | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
index 4956785f..ca63c914 100644
--- a/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
+++ b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
@@ -148,7 +148,7 @@ git commit -m "refactor(webui): split shared API transport"
 
 **Interfaces:**
 - Produces: `worldbuildingApi`, `filesApi`, `configApi`.
-- Core signatures: `getDashboard(worldId)`, `listLocations(worldId)`, `listKnowledge(worldId)`, `listFactions(worldId)`, `getTimeline(worldId)`, `listGraphEntities(worldId)`, `reorderChapters(worldId, chapterIds)`, resource delete functions, `listWorldFiles(worldId)`, `linkWorldFile(worldId, link)`.
+- Core signatures: `getDashboard(worldId)`, `listLocations(worldId)`, `listKnowledge(worldId)`, `listFactions(worldId)`, `getTimeline(worldId)`, `listGraphEntities(worldId)`, `reorderChapters(worldId, chapterIds)`, resource delete functions, `listWorldFiles(worldId)`, `linkWorldFile(worldId, link)`, `unlinkWorldFile(worldId, filePath, target)`.
 
 - [ ] **Step 1: Add failing URL and body tests**
 
@@ -158,14 +158,18 @@ it('reorders chapters with the documented body', async () => {
   await worldbuildingApi.reorderChapters('w 1', ['c1', 'c2']);
   expect(fetchMock).toHaveBeenCalledWith(
     expect.stringContaining('/api/worldbuilding/w%201/chapters/reorder'),
-    expect.objectContaining({ method: 'POST', body: JSON.stringify({ chapter_ids: ['c1', 'c2'] }) }),
+    expect.objectContaining({ method: 'POST', body: JSON.stringify({ order: ['c1', 'c2'] }) }),
   );
 });
 
 it('encodes a linked file path when deleting it', async () => {
   fetchMock.mockResolvedValueOnce(json({ ok: true }));
-  await filesApi.unlinkWorldFile('w1', '章节/第一章.md');
+  await filesApi.unlinkWorldFile('w1', '章节/第一章.md', { entity_type: 'chapter', entity_id: 'c1' });
   expect(fetchMock.mock.calls[0][0]).toContain(encodeURIComponent('章节/第一章.md'));
+  expect(fetchMock.mock.calls[0][1]).toMatchObject({
+    method: 'DELETE',
+    body: JSON.stringify({ target_type: 'chapter', target_id: 'c1' }),
+  });
 });
 ```
 
@@ -503,7 +507,7 @@ git commit -m "feat(webui): add world and character workspaces"
 - Test: `webui/src/__tests__/UserFlow.test.tsx`
 
 **Interfaces:**
-- Chapters produces reorder body `{ chapter_ids: string[] }` and editor navigation.
+- Chapters produces reorder body `{ order: string[] }` and editor navigation.
 - Scenes produces selected scene detail and real `endScene` result rendering.
 
 - [ ] **Step 1: Add failing chapter reorder and scene end tests**

From 52fd4bfe37095c8509bee7c92d39294c3b7026a3 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 22:56:32 +0800
Subject: [PATCH 08/49] fix(webui): align typed APIs with backend contract

---
 webui/src/__tests__/api.test.ts | 28 +++++++++++++++++++++++++---
 webui/src/api/files.ts          | 13 ++++++-------
 webui/src/api/worldbuilding.ts  |  2 +-
 3 files changed, 32 insertions(+), 11 deletions(-)

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index f538f727..dc1a6690 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -220,18 +220,40 @@ describe('api client', () => {
       expect.stringContaining('/api/worldbuilding/w%201/chapters/reorder'),
       expect.objectContaining({
         method: 'POST',
-        body: JSON.stringify({ chapter_ids: ['c1', 'c2'] }),
+        body: JSON.stringify({ order: ['c1', 'c2'] }),
       }),
     );
   });
 
-  it('encodes a linked file path when deleting it', async () => {
+  it('requires target metadata when deleting a linked file', async () => {
     vi.mocked(fetch).mockResolvedValueOnce(
       new Response(JSON.stringify({ ok: true }), { status: 200 }),
     );
 
-    await filesApi.unlinkWorldFile('w1', '章节/第一章.md');
+    const unlinkWithoutTarget = filesApi.unlinkWorldFile as (
+      worldId: string,
+      filePath: string,
+    ) => Promise<unknown>;
+
+    await expect(unlinkWithoutTarget('w1', '章节/第一章.md')).rejects.toThrow(
+      'File link target is required',
+    );
+  });
+
+  it('encodes a linked file path and target when deleting it', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(JSON.stringify({ ok: true }), { status: 200 }),
+    );
+
+    await filesApi.unlinkWorldFile('w1', '章节/第一章.md', {
+      entity_type: 'chapter',
+      entity_id: 'c1',
+    });
 
     expect(vi.mocked(fetch).mock.calls[0][0]).toContain(encodeURIComponent('章节/第一章.md'));
+    expect(vi.mocked(fetch).mock.calls[0][1]).toMatchObject({
+      method: 'DELETE',
+      body: JSON.stringify({ target_type: 'chapter', target_id: 'c1' }),
+    });
   });
 });
diff --git a/webui/src/api/files.ts b/webui/src/api/files.ts
index 10dbe160..c84709f0 100644
--- a/webui/src/api/files.ts
+++ b/webui/src/api/files.ts
@@ -4,11 +4,14 @@ import type { OkResponse, ResourceListResponse, WorldFileLink } from './types';
 type FileListResponse = ResourceListResponse<WorldFileLink> & {
   files?: WorldFileLink[];
 };
+type WorldFileTarget = Required<Pick<WorldFileLink, 'entity_type' | 'entity_id'>>;
 
 const filesPath = (worldId: string) => `/api/worldbuilding/${encodeURIComponent(worldId)}/files`;
 
 function fileTarget(link?: Pick<WorldFileLink, 'entity_type' | 'entity_id'>) {
-  if (!link?.entity_type || !link.entity_id) return undefined;
+  if (!link?.entity_type || !link.entity_id) {
+    throw new Error('File link target is required');
+  }
   return { target_type: link.entity_type, target_id: link.entity_id };
 }
 
@@ -24,14 +27,10 @@ export const filesApi = {
       ...fileTarget(link),
     }),
 
-  unlinkWorldFile: (
-    worldId: string,
-    filePath: string,
-    link?: Pick<WorldFileLink, 'entity_type' | 'entity_id'>,
-  ) =>
+  unlinkWorldFile: async (worldId: string, filePath: string, target: WorldFileTarget) =>
     request<OkResponse>(
       'DELETE',
       `${filesPath(worldId)}/${encodeURIComponent(filePath)}`,
-      fileTarget(link),
+      fileTarget(target),
     ),
 };
diff --git a/webui/src/api/worldbuilding.ts b/webui/src/api/worldbuilding.ts
index 719f8166..2652475b 100644
--- a/webui/src/api/worldbuilding.ts
+++ b/webui/src/api/worldbuilding.ts
@@ -65,7 +65,7 @@ export const worldbuildingApi = {
 
   reorderChapters: (worldId: string, chapterIds: string[]) =>
     request<OkResponse>('POST', resourcePath(worldId, 'chapters/reorder'), {
-      chapter_ids: chapterIds,
+      order: chapterIds,
     }),
 
   deleteLocation: (worldId: string, locationId: string) =>

From 2f6dee2acfed8b36954601de4dd8b71afcc15882 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 23:12:55 +0800
Subject: [PATCH 09/49] fix(webui): preserve typed API response metadata

---
 webui/src/__tests__/api.test.ts | 62 +++++++++++++++++++++++++++++++++
 webui/src/api/files.ts          | 15 ++++----
 webui/src/api/types.ts          | 61 +++++++++++++++++++++++++++++++-
 webui/src/api/worldbuilding.ts  | 46 +++++++++++-------------
 4 files changed, 148 insertions(+), 36 deletions(-)

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index dc1a6690..2f3c38f3 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -256,4 +256,66 @@ describe('api client', () => {
       body: JSON.stringify({ target_type: 'chapter', target_id: 'c1' }),
     });
   });
+
+  it('preserves named resource arrays and truthful knowledge fields', async () => {
+    vi.mocked(fetch)
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ ok: true, locations: [{ id: 'l1', name: 'Harbor' }] }), {
+          status: 200,
+        }),
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            ok: true,
+            knowledge: [{ id: 'k1', category: 'history', content: 'Founded at dawn' }],
+          }),
+          { status: 200 },
+        ),
+      );
+
+    const locations = await worldbuildingApi.listLocations('w1');
+    const knowledge = await worldbuildingApi.listKnowledge('w1');
+
+    expect(locations.locations?.[0].name).toBe('Harbor');
+    expect(locations.items).toEqual(locations.locations);
+    expect(knowledge.knowledge?.[0].category).toBe('history');
+    expect(knowledge.items).toEqual(knowledge.knowledge);
+  });
+
+  it('preserves timeline metadata with truthful event fields', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          current_time: { day: 2, period: 1, label: 'Day 2' },
+          events: [{ id: 'e1', world_time: 'Day 2', description: 'The gates opened' }],
+        }),
+        { status: 200 },
+      ),
+    );
+
+    const timeline = await worldbuildingApi.getTimeline('w1');
+
+    expect(timeline.current_time.label).toBe('Day 2');
+    expect(timeline.events?.[0].description).toBe('The gates opened');
+    expect(timeline.items).toEqual(timeline.events);
+  });
+
+  it('preserves documented file-link target fields', async () => {
+    vi.mocked(fetch).mockResolvedValueOnce(
+      new Response(
+        JSON.stringify({
+          ok: true,
+          files: [{ file_path: 'chapter.md', target_type: 'chapter', target_id: 'c1' }],
+        }),
+        { status: 200 },
+      ),
+    );
+
+    const files = await filesApi.listWorldFiles('w1');
+
+    expect(files.files?.[0].target_type).toBe('chapter');
+    expect(files.items?.[0].target_id).toBe('c1');
+  });
 });
diff --git a/webui/src/api/files.ts b/webui/src/api/files.ts
index c84709f0..1c4b5366 100644
--- a/webui/src/api/files.ts
+++ b/webui/src/api/files.ts
@@ -1,14 +1,11 @@
 import { request } from './http';
-import type { OkResponse, ResourceListResponse, WorldFileLink } from './types';
+import type { OkResponse, WorldFileLinkInput, WorldFileListResponse } from './types';
 
-type FileListResponse = ResourceListResponse<WorldFileLink> & {
-  files?: WorldFileLink[];
-};
-type WorldFileTarget = Required<Pick<WorldFileLink, 'entity_type' | 'entity_id'>>;
+type WorldFileTarget = Required<Pick<WorldFileLinkInput, 'entity_type' | 'entity_id'>>;
 
 const filesPath = (worldId: string) => `/api/worldbuilding/${encodeURIComponent(worldId)}/files`;
 
-function fileTarget(link?: Pick<WorldFileLink, 'entity_type' | 'entity_id'>) {
+function fileTarget(link?: Pick<WorldFileLinkInput, 'entity_type' | 'entity_id'>) {
   if (!link?.entity_type || !link.entity_id) {
     throw new Error('File link target is required');
   }
@@ -16,12 +13,12 @@ function fileTarget(link?: Pick<WorldFileLink, 'entity_type' | 'entity_id'>) {
 }
 
 export const filesApi = {
-  listWorldFiles: async (worldId: string): Promise<ResourceListResponse<WorldFileLink>> => {
-    const response = await request<FileListResponse>('GET', filesPath(worldId));
+  listWorldFiles: async (worldId: string): Promise<WorldFileListResponse> => {
+    const response = await request<WorldFileListResponse>('GET', filesPath(worldId));
     return { ...response, items: response.items ?? response.files };
   },
 
-  linkWorldFile: (worldId: string, link: WorldFileLink) =>
+  linkWorldFile: (worldId: string, link: WorldFileLinkInput) =>
     request<OkResponse>('POST', filesPath(worldId), {
       file_path: link.file_path,
       ...fileTarget(link),
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 83620479..f2e6f42a 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -723,8 +723,67 @@ export interface GraphEntity {
   name: string;
 }
 
-export interface WorldFileLink {
+export interface WorldFileLinkInput {
   file_path: string;
   entity_type?: string;
   entity_id?: string;
 }
+
+export type WorldFileLink = WorldFileLinkInput;
+
+export interface KnowledgeRecord {
+  id: string;
+  category: string;
+  content: string;
+  tags?: string[];
+  aliases?: string[];
+  related_ids?: string[];
+  created_at?: string;
+}
+
+export interface TimelineEventRecord {
+  id: string;
+  world_time: string;
+  description: string;
+  recorded_by?: string;
+  affected_character_ids?: string[];
+  related_scene_ids?: string[];
+}
+
+export interface WorldFileLinkRecord {
+  file_path: string;
+  target_type: string;
+  target_id: string;
+  created_at?: string;
+}
+
+export type LocationListResponse = ResourceListResponse<LocationItem> & {
+  locations?: LocationItem[];
+};
+
+export type KnowledgeListResponse = ResourceListResponse<KnowledgeRecord> & {
+  knowledge?: KnowledgeRecord[];
+};
+
+export type FactionListResponse = ResourceListResponse<FactionItem> & {
+  factions?: FactionItem[];
+};
+
+export interface TimelineCurrentTime {
+  day: number;
+  period: number;
+  label: string;
+}
+
+export type TimelineResponse = ResourceListResponse<TimelineEventRecord> & {
+  current_time: TimelineCurrentTime;
+  events?: TimelineEventRecord[];
+};
+
+export type GraphEntityListResponse = ResourceListResponse<GraphEntity> & {
+  entities?: GraphEntity[];
+};
+
+export type WorldFileListResponse = ResourceListResponse<WorldFileLinkRecord> & {
+  files?: WorldFileLinkRecord[];
+};
diff --git a/webui/src/api/worldbuilding.ts b/webui/src/api/worldbuilding.ts
index 2652475b..0b1f985f 100644
--- a/webui/src/api/worldbuilding.ts
+++ b/webui/src/api/worldbuilding.ts
@@ -1,21 +1,23 @@
 import { request } from './http';
 import type {
   FactionItem,
+  FactionListResponse,
   GraphEntity,
-  KnowledgeItem,
-  LocationItem,
+  GraphEntityListResponse,
+  KnowledgeListResponse,
+  LocationListResponse,
   OkResponse,
   ResourceListResponse,
-  TimelineEvent,
+  TimelineResponse,
 } from './types';
 
-type NamedListResponse<T> = ResourceListResponse<T> & Record<string, unknown>;
-
-function adaptList<T>(response: NamedListResponse<T>, key: string): ResourceListResponse<T> {
-  const namedItems = response[key];
+function adaptList<T, TResponse extends ResourceListResponse<T>>(
+  response: TResponse,
+  namedItems?: T[],
+): TResponse {
   return {
     ...response,
-    items: response.items ?? (Array.isArray(namedItems) ? (namedItems as T[]) : undefined),
+    items: response.items ?? namedItems,
   };
 }
 
@@ -31,36 +33,28 @@ export const worldbuildingApi = {
     ),
 
   listLocations: async (worldId: string) =>
-    adaptList<LocationItem>(
-      await request<NamedListResponse<LocationItem>>('GET', resourcePath(worldId, 'locations')),
-      'locations',
+    request<LocationListResponse>('GET', resourcePath(worldId, 'locations')).then((response) =>
+      adaptList(response, response.locations),
     ),
 
   listKnowledge: async (worldId: string) =>
-    adaptList<KnowledgeItem>(
-      await request<NamedListResponse<KnowledgeItem>>('GET', resourcePath(worldId, 'knowledge')),
-      'knowledge',
+    request<KnowledgeListResponse>('GET', resourcePath(worldId, 'knowledge')).then((response) =>
+      adaptList(response, response.knowledge),
     ),
 
   listFactions: async (worldId: string) =>
-    adaptList<FactionItem>(
-      await request<NamedListResponse<FactionItem>>('GET', resourcePath(worldId, 'factions')),
-      'factions',
+    request<FactionListResponse>('GET', resourcePath(worldId, 'factions')).then((response) =>
+      adaptList<FactionItem, FactionListResponse>(response, response.factions),
     ),
 
   getTimeline: async (worldId: string) =>
-    adaptList<TimelineEvent>(
-      await request<NamedListResponse<TimelineEvent>>('GET', resourcePath(worldId, 'timeline')),
-      'events',
+    request<TimelineResponse>('GET', resourcePath(worldId, 'timeline')).then((response) =>
+      adaptList(response, response.events),
     ),
 
   listGraphEntities: async (worldId: string) =>
-    adaptList<GraphEntity>(
-      await request<NamedListResponse<GraphEntity>>(
-        'GET',
-        resourcePath(worldId, 'knowledge-graph/entities'),
-      ),
-      'entities',
+    request<GraphEntityListResponse>('GET', resourcePath(worldId, 'knowledge-graph/entities')).then(
+      (response) => adaptList<GraphEntity, GraphEntityListResponse>(response, response.entities),
     ),
 
   reorderChapters: (worldId: string, chapterIds: string[]) =>

From 5d1e925de5baea378d4dcbe2123f540cceaced61 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Fri, 19 Jun 2026 23:25:00 +0800
Subject: [PATCH 10/49] feat(webui): complete interactive SSE requests

---
 webui/src/App.tsx                             |  59 ++++++----
 webui/src/AppState.tsx                        |  55 ++++++++-
 webui/src/__tests__/AppState.test.ts          |  81 ++++++++++++-
 webui/src/__tests__/sse-workflows.test.tsx    | 109 ++++++++++++++++++
 webui/src/api/runtime.ts                      |   6 +
 webui/src/api/types.ts                        |  20 ++++
 webui/src/components/AskUserPrompt.module.css |  75 ++++++++++++
 webui/src/components/AskUserPrompt.tsx        |  81 +++++++++++++
 .../src/components/CreationRequestDialog.tsx  |  92 +++++++++++++++
 webui/src/hooks/useSSE.ts                     |   1 -
 10 files changed, 555 insertions(+), 24 deletions(-)
 create mode 100644 webui/src/__tests__/sse-workflows.test.tsx
 create mode 100644 webui/src/components/AskUserPrompt.module.css
 create mode 100644 webui/src/components/AskUserPrompt.tsx
 create mode 100644 webui/src/components/CreationRequestDialog.tsx

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index ce2f1bb5..d52b837c 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -3,17 +3,19 @@ import { ArrowLeft } from 'lucide-react';
 import { api } from './api/client';
 import styles from './App.module.css';
 import { AppStateProvider, useAppState, type AppState } from './AppState';
+import AskUserPrompt from './components/AskUserPrompt';
+import ChapterEditor from './components/ChapterEditor';
 import ConnectionBanner from './components/ConnectionBanner';
+import CreationRequestDialog from './components/CreationRequestDialog';
 import ErrorBoundary from './components/ErrorBoundary';
 import InspectorPanel from './components/InspectorPanel';
 import MainPanel from './components/MainPanel';
+import SettingsPage from './components/SettingsPage';
 import Skeleton from './components/Skeleton';
 import { ToastProvider } from './components/Toast';
 import WorldDashboard from './components/WorldDashboard';
 import WorldOnboarding from './components/WorldOnboarding';
 import WorldSidebar from './components/WorldSidebar';
-import SettingsPage from './components/SettingsPage';
-import ChapterEditor from './components/ChapterEditor';
 import DesktopBoot from './DesktopBoot';
 import { useSSE } from './hooks/useSSE';
 import { I18nProvider } from './i18n';
@@ -56,13 +58,14 @@ function AppInner() {
         dispatch({ type: 'SHOW_SETUP_WIZARD', show: true });
       }
 
-      const [metadataRes, worldsRes, sessionsRes, capabilitiesRes, prefsRes] = await Promise.allSettled([
-        api.metadata(),
-        api.listWorlds(),
-        api.listSessions(),
-        api.capabilities(),
-        api.getPreferences(),
-      ]);
+      const [metadataRes, worldsRes, sessionsRes, capabilitiesRes, prefsRes] =
+        await Promise.allSettled([
+          api.metadata(),
+          api.listWorlds(),
+          api.listSessions(),
+          api.capabilities(),
+          api.getPreferences(),
+        ]);
 
       if (metadataRes.status === 'fulfilled') {
         dispatch({ type: 'SET_METADATA', metadata: metadataRes.value });
@@ -172,10 +175,7 @@ function AppInner() {
         fallback: overviewRes.status === 'fulfilled' ? overviewRes.value.fallback : false,
       });
       if (
-        shouldReportWorldbuildingPartialFailure(
-          overviewRes.status === 'fulfilled',
-          secondaryFailed,
-        )
+        shouldReportWorldbuildingPartialFailure(overviewRes.status === 'fulfilled', secondaryFailed)
       ) {
         dispatch({
           type: 'SET_WORLDBUILDING_STATUS',
@@ -235,9 +235,7 @@ function AppInner() {
             <ArrowLeft size={15} aria-hidden="true" strokeWidth={2.3} />
             返回工作台
           </button>
-          <h1 className={styles.editorTitle}>
-            {state.activeEditorChapterTitle || '章节编辑'}
-          </h1>
+          <h1 className={styles.editorTitle}>{state.activeEditorChapterTitle || '章节编辑'}</h1>
         </div>
         <div className={styles.editorBody}>
           <ChapterEditor chapterId={state.activeEditorChapterId} worldId={state.worldId} />
@@ -255,7 +253,9 @@ function AppInner() {
     return (
       <ToastProvider>
         <WorldOnboarding onOpenGuide={() => setHelpOpen(true)} />
-        <Suspense>{helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}</Suspense>
+        <Suspense>
+          {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
+        </Suspense>
       </ToastProvider>
     );
   }
@@ -264,7 +264,9 @@ function AppInner() {
     return (
       <ToastProvider>
         <WorldDashboard onOpenGuide={() => setHelpOpen(true)} />
-        <Suspense>{helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}</Suspense>
+        <Suspense>
+          {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
+        </Suspense>
       </ToastProvider>
     );
   }
@@ -289,7 +291,9 @@ function AppInner() {
             />
           </div>
         </ErrorBoundary>
-        <Suspense><HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} /></Suspense>
+        <Suspense>
+          <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />
+        </Suspense>
         <ErrorBoundary>
           <InspectorPanel open={inspectorOpen} onClose={() => setInspectorOpen(false)} />
         </ErrorBoundary>
@@ -298,7 +302,9 @@ function AppInner() {
       {/* Setup Wizard — shown when LLM is not configured */}
       <Suspense>
         {state.showSetupWizard && (
-          <SetupWizard onComplete={() => dispatch({ type: 'SET_LLM_CONFIGURED', configured: true })} />
+          <SetupWizard
+            onComplete={() => dispatch({ type: 'SET_LLM_CONFIGURED', configured: true })}
+          />
         )}
       </Suspense>
 
@@ -324,6 +330,19 @@ function AppInner() {
         )}
       </Suspense>
 
+      {state.pendingAsk && (
+        <AskUserPrompt
+          request={state.pendingAsk}
+          onResolved={() => dispatch({ type: 'RESOLVE_ASK' })}
+        />
+      )}
+      {state.pendingCreation && (
+        <CreationRequestDialog
+          request={state.pendingCreation}
+          onResolved={() => dispatch({ type: 'RESOLVE_CREATION' })}
+        />
+      )}
+
       {/* Export Dialog */}
       <Suspense>
         {state.showExportDialog && state.worldId && (
diff --git a/webui/src/AppState.tsx b/webui/src/AppState.tsx
index 73964498..96494b04 100644
--- a/webui/src/AppState.tsx
+++ b/webui/src/AppState.tsx
@@ -4,6 +4,8 @@ import type {
   ConditionState,
   ForeshadowingItem,
   Message,
+  PendingAsk,
+  PendingCreation,
   PhaseTransition,
   PipelineViewData,
   RuntimeMetadata,
@@ -48,6 +50,8 @@ export interface AppState {
   sessionId: string;
   lastSeq: number;
   currentRun: string | null;
+  pendingAsk: PendingAsk | null;
+  pendingCreation: PendingCreation | null;
   lastRunId: string | null;
   messages: Message[];
   status: StatusLabel;
@@ -116,6 +120,8 @@ export const initialState: AppState = {
   sessionId: '',
   lastSeq: 0,
   currentRun: null,
+  pendingAsk: null,
+  pendingCreation: null,
   lastRunId: null,
   messages: [],
   status: 'idle',
@@ -308,6 +314,8 @@ export type Action =
   | { type: 'COMMIT_ACTIVE' }
   | { type: 'SET_STORY_VERSION' }
   | { type: 'APPLY_SSE'; frame: SseFrame }
+  | { type: 'RESOLVE_ASK' }
+  | { type: 'RESOLVE_CREATION' }
   | { type: 'SET_PIPELINE_CONDITIONS'; conditions: ConditionState[] }
   | { type: 'SET_PIPELINE_VIEW'; view: Partial<PipelineViewData> }
   | { type: 'DISMISS_PHASE_PROMPT' }
@@ -339,6 +347,8 @@ export function reducer(state: AppState, action: Action): AppState {
         lastSeq: 0,
         currentRun: null,
         lastRunId: null,
+        pendingAsk: null,
+        pendingCreation: null,
         status: 'idle',
       };
 
@@ -351,6 +361,8 @@ export function reducer(state: AppState, action: Action): AppState {
         lastSeq: 0,
         currentRun: null,
         lastRunId: null,
+        pendingAsk: null,
+        pendingCreation: null,
         status: 'idle',
       };
 
@@ -485,7 +497,8 @@ export function reducer(state: AppState, action: Action): AppState {
         ...state,
         editorBuffers: {
           ...state.editorBuffers,
-          [action.fileId]: state.editorOriginals[action.fileId] ?? state.editorBuffers[action.fileId] ?? '',
+          [action.fileId]:
+            state.editorOriginals[action.fileId] ?? state.editorBuffers[action.fileId] ?? '',
         },
         workspaceFiles: state.workspaceFiles.map((file) =>
           file.id === action.fileId ? { ...file, dirty: false } : file,
@@ -678,10 +691,17 @@ export function reducer(state: AppState, action: Action): AppState {
 
     case 'APPLY_SSE': {
       const { frame } = action;
+      if (frame.seq > 0 && frame.seq <= state.lastSeq) return state;
       if (frame.seq > 0) state = { ...state, lastSeq: Math.max(state.lastSeq, frame.seq) };
       return applySseFrame(state, frame);
     }
 
+    case 'RESOLVE_ASK':
+      return { ...state, pendingAsk: null };
+
+    case 'RESOLVE_CREATION':
+      return { ...state, pendingCreation: null };
+
     case 'SET_PIPELINE_CONDITIONS':
       return { ...state, pipelineConditions: action.conditions };
 
@@ -868,6 +888,39 @@ function applySseFrame(state: AppState, frame: SseFrame): AppState {
     case 'approval_resolved':
       return reducer(state, { type: 'CLEAR_APPROVAL' });
 
+    case 'ask_user_requested': {
+      const choices = Array.isArray(p.options)
+        ? p.options.filter((choice): choice is string => typeof choice === 'string')
+        : undefined;
+      return {
+        ...state,
+        pendingAsk: {
+          runId: (p.run_id as string) || state.currentRun || '',
+          ...(typeof p.call_id === 'string' && p.call_id ? { callId: p.call_id } : {}),
+          question: (p.question as string) ?? '',
+          ...(choices?.length ? { choices } : {}),
+          ...(typeof p.multi_select === 'boolean' ? { multiSelect: p.multi_select } : {}),
+        },
+      };
+    }
+
+    case 'creation_requested':
+      return {
+        ...state,
+        pendingCreation: {
+          id: (p.creation_id as string) ?? '',
+          toolName: (p.tool as string) ?? '',
+          ...(p.preview && typeof p.preview === 'object'
+            ? { preview: p.preview as Record<string, unknown> }
+            : {}),
+        },
+      };
+
+    case 'creation_resolved':
+      return state.pendingCreation?.id === p.creation_id || !p.creation_id
+        ? reducer(state, { type: 'RESOLVE_CREATION' })
+        : state;
+
     case 'usage_updated':
       return reducer(state, {
         type: 'SET_USAGE',
diff --git a/webui/src/__tests__/AppState.test.ts b/webui/src/__tests__/AppState.test.ts
index 31ade23a..d188f9c4 100644
--- a/webui/src/__tests__/AppState.test.ts
+++ b/webui/src/__tests__/AppState.test.ts
@@ -8,13 +8,20 @@ function state(overrides: Partial<AppState> = {}): AppState {
 
 describe('AppState reducer', () => {
   it('SET_SESSION resets messages and sets sessionId', () => {
-    const prev = state({ messages: [{ id: 'm1', kind: 'user', text: 'hi' }], lastSeq: 5 });
+    const prev = state({
+      messages: [{ id: 'm1', kind: 'user', text: 'hi' }],
+      lastSeq: 5,
+      pendingAsk: { runId: 'old-run', question: 'Old question' },
+      pendingCreation: { id: 'old-creation', toolName: 'create_scene' },
+    });
     const next = reducer(prev, { type: 'SET_SESSION', sessionId: 'new-id' });
     expect(next.sessionId).toBe('new-id');
     expect(next.messages).toHaveLength(0);
     expect(next.lastSeq).toBe(0);
     expect(next.currentRun).toBeNull();
     expect(next.status).toBe('idle');
+    expect(next.pendingAsk).toBeNull();
+    expect(next.pendingCreation).toBeNull();
   });
 
   it('SET_METADATA stores metadata and sets selectedModel', () => {
@@ -42,7 +49,16 @@ describe('AppState reducer', () => {
     const next = reducer(prev, {
       type: 'SET_SESSIONS',
       sessions: [
-        { id: 's1', title: 'Test', world_id: null, agent_id: null, last_seq: 0, created_at: '', updated_at: '', archived_at: null },
+        {
+          id: 's1',
+          title: 'Test',
+          world_id: null,
+          agent_id: null,
+          last_seq: 0,
+          created_at: '',
+          updated_at: '',
+          archived_at: null,
+        },
       ],
     });
     expect(next.sessions).toHaveLength(1);
@@ -200,6 +216,67 @@ describe('AppState reducer', () => {
     expect(next2.lastSeq).toBe(7);
   });
 
+  it('tracks and resolves interactive SSE requests', () => {
+    const askFrame = {
+      seq: 10,
+      type: 'ask_user_requested',
+      payload: {
+        run_id: 'r1',
+        call_id: 'call_1',
+        question: 'Choose POV',
+        options: ['First person', 'Third person'],
+      },
+    };
+    const asked = reducer(state(), { type: 'APPLY_SSE', frame: askFrame });
+    expect(asked.pendingAsk).toEqual({
+      runId: 'r1',
+      callId: 'call_1',
+      question: 'Choose POV',
+      choices: ['First person', 'Third person'],
+    });
+    expect(reducer(asked, { type: 'RESOLVE_ASK' }).pendingAsk).toBeNull();
+
+    const creationFrame = {
+      seq: 11,
+      type: 'creation_requested',
+      payload: { creation_id: 'creation_1', tool: 'create_scene', preview: { title: 'Arrival' } },
+    };
+    const requested = reducer(asked, { type: 'APPLY_SSE', frame: creationFrame });
+    expect(requested.pendingCreation).toEqual({
+      id: 'creation_1',
+      toolName: 'create_scene',
+      preview: { title: 'Arrival' },
+    });
+    expect(
+      reducer(requested, {
+        type: 'APPLY_SSE',
+        frame: {
+          seq: 12,
+          type: 'creation_resolved',
+          payload: { creation_id: 'creation_1', decision: 'allow' },
+        },
+      }).pendingCreation,
+    ).toBeNull();
+    expect(reducer(requested, { type: 'RESOLVE_CREATION' }).pendingCreation).toBeNull();
+  });
+
+  it('ignores duplicate and stale nonzero SSE frames before applying their effects', () => {
+    const askFrame = {
+      seq: 10,
+      type: 'ask_user_requested',
+      payload: { run_id: 'r1', question: 'Choose POV' },
+    };
+    const prev = state({ lastSeq: 10 });
+    expect(reducer(prev, { type: 'APPLY_SSE', frame: askFrame })).toEqual(prev);
+
+    const zeroSeq = reducer(prev, {
+      type: 'APPLY_SSE',
+      frame: { ...askFrame, seq: 0 },
+    });
+    expect(zeroSeq.pendingAsk).toEqual({ runId: 'r1', question: 'Choose POV' });
+    expect(zeroSeq.lastSeq).toBe(10);
+  });
+
   describe('SSE frame: run_started', () => {
     it('creates user message from payload.message', () => {
       const prev = state();
diff --git a/webui/src/__tests__/sse-workflows.test.tsx b/webui/src/__tests__/sse-workflows.test.tsx
new file mode 100644
index 00000000..3d1e3612
--- /dev/null
+++ b/webui/src/__tests__/sse-workflows.test.tsx
@@ -0,0 +1,109 @@
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { runtimeApi } from '../api/runtime';
+import AskUserPrompt from '../components/AskUserPrompt';
+import CreationRequestDialog from '../components/CreationRequestDialog';
+
+const apiMocks = vi.hoisted(() => ({
+  respondToAsk: vi.fn(),
+  resolveCreation: vi.fn(),
+}));
+
+vi.mock('../api/client', () => ({
+  api: apiMocks,
+  formatApiError: (error: unknown, fallback = 'Request failed') =>
+    error instanceof Error ? error.message : fallback,
+}));
+
+describe('interactive SSE workflows', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('exposes the ask-user response endpoint', () => {
+    expect(runtimeApi.respondToAsk).toBeTypeOf('function');
+  });
+
+  it('submits an ask response once and resolves only after success', async () => {
+    let complete!: () => void;
+    apiMocks.respondToAsk.mockReturnValue(
+      new Promise<void>((resolve) => {
+        complete = resolve;
+      }),
+    );
+    const onResolved = vi.fn();
+    render(
+      <AskUserPrompt
+        request={{
+          runId: 'run_1',
+          callId: 'call_1',
+          question: 'Choose POV',
+          choices: ['First person'],
+        }}
+        onResolved={onResolved}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'First person' }));
+    const submit = screen.getByRole('button', { name: 'Send response' });
+    fireEvent.click(submit);
+    fireEvent.click(submit);
+
+    expect(apiMocks.respondToAsk).toHaveBeenCalledOnce();
+    expect(apiMocks.respondToAsk).toHaveBeenCalledWith('run_1', 'First person', 'call_1');
+    expect(onResolved).not.toHaveBeenCalled();
+    expect(screen.getByRole('button', { name: 'Sending...' })).toBeDisabled();
+
+    complete();
+    await waitFor(() => expect(onResolved).toHaveBeenCalledOnce());
+  });
+
+  it('keeps the ask dialog open and formats request errors', async () => {
+    apiMocks.respondToAsk.mockRejectedValue(new Error('Run is no longer waiting'));
+    const onResolved = vi.fn();
+    render(
+      <AskUserPrompt request={{ runId: 'run_1', question: 'Continue?' }} onResolved={onResolved} />,
+    );
+    fireEvent.change(screen.getByLabelText('Your response'), { target: { value: 'Yes' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Send response' }));
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Run is no longer waiting');
+    expect(onResolved).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['Allow', 'allow'],
+    ['Deny', 'deny'],
+  ] as const)('resolves a creation request once via %s', async (button, decision) => {
+    apiMocks.resolveCreation.mockResolvedValue({ ok: true });
+    const onResolved = vi.fn();
+    render(
+      <CreationRequestDialog
+        request={{ id: 'creation_1', toolName: 'create_scene', preview: { title: 'Arrival' } }}
+        onResolved={onResolved}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: button }));
+
+    await waitFor(() => expect(onResolved).toHaveBeenCalledOnce());
+    expect(apiMocks.resolveCreation).toHaveBeenCalledOnce();
+    expect(apiMocks.resolveCreation).toHaveBeenCalledWith(
+      'creation_1',
+      decision,
+      decision === 'allow' ? { title: 'Arrival' } : undefined,
+    );
+  });
+
+  it('keeps the creation dialog open when resolution fails', async () => {
+    apiMocks.resolveCreation.mockRejectedValue(new Error('Creation expired'));
+    const onResolved = vi.fn();
+    render(
+      <CreationRequestDialog
+        request={{ id: 'creation_1', toolName: 'create_scene' }}
+        onResolved={onResolved}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Allow' }));
+
+    expect(await screen.findByRole('alert')).toHaveTextContent('Creation expired');
+    expect(onResolved).not.toHaveBeenCalled();
+  });
+});
diff --git a/webui/src/api/runtime.ts b/webui/src/api/runtime.ts
index 6e804cf5..eea02ef8 100644
--- a/webui/src/api/runtime.ts
+++ b/webui/src/api/runtime.ts
@@ -2,6 +2,7 @@ import { getApiBase, request } from './http';
 import type {
   ApprovalResponse,
   ArchiveSessionResponse,
+  AskResponse,
   CancelRunResponse,
   CreateSessionResponse,
   GenerateTitleResponse,
@@ -75,6 +76,11 @@ export const runtimeApi = {
       decision: allow ? 'allow' : 'deny',
     }),
   cancelRun: (id: string) => request<CancelRunResponse>('POST', `/v1/runs/${id}/cancel`),
+  respondToAsk: (runId: string, response: string, callId = runId) =>
+    request<AskResponse>('POST', `/v1/runs/${runId}/ask-response`, {
+      call_id: callId,
+      response,
+    }),
   resolveCreation: (id: string, decision: string, modifications?: Record<string, unknown>) =>
     request<ResolveCreationResponse>('POST', `/v1/creations/${id}/resolve`, {
       decision,
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index f2e6f42a..4b2e6ff2 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -4,6 +4,26 @@ export interface SseFrame {
   payload: Record<string, unknown>;
 }
 
+export interface PendingAsk {
+  runId: string;
+  callId?: string;
+  question: string;
+  choices?: string[];
+  multiSelect?: boolean;
+}
+
+export interface PendingCreation {
+  id: string;
+  toolName: string;
+  preview?: Record<string, unknown>;
+}
+
+export interface AskResponse {
+  ok: boolean;
+  run_id: string;
+  call_id: string;
+}
+
 export type MessageKind = 'user' | 'assistant' | 'tool' | 'system' | 'approval' | 'status_pill';
 
 export type StatusLabel =
diff --git a/webui/src/components/AskUserPrompt.module.css b/webui/src/components/AskUserPrompt.module.css
new file mode 100644
index 00000000..1fd9cfca
--- /dev/null
+++ b/webui/src/components/AskUserPrompt.module.css
@@ -0,0 +1,75 @@
+.overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 1100;
+  display: grid;
+  place-items: center;
+  padding: 24px;
+  background: rgba(0, 0, 0, 0.55);
+}
+
+.card {
+  width: min(520px, 100%);
+  padding: 24px;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: var(--surface);
+  color: var(--text);
+}
+
+.question {
+  white-space: pre-wrap;
+}
+.choices {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin: 16px 0;
+}
+.choice,
+.selected,
+.submit {
+  padding: 8px 14px;
+  border: 1px solid var(--border);
+  border-radius: 7px;
+  cursor: pointer;
+}
+.choice {
+  background: var(--bg-secondary);
+  color: var(--text);
+}
+.selected,
+.submit {
+  background: var(--accent);
+  color: white;
+}
+.label {
+  display: block;
+  margin: 16px 0 6px;
+  font-size: 0.9rem;
+}
+.input {
+  box-sizing: border-box;
+  width: 100%;
+  min-height: 88px;
+  padding: 10px;
+  border: 1px solid var(--border);
+  border-radius: 7px;
+  background: var(--input-bg);
+  color: var(--text);
+  resize: vertical;
+}
+.actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: 16px;
+}
+.error {
+  color: var(--ruby);
+}
+.submit:disabled,
+.choice:disabled,
+.selected:disabled {
+  cursor: not-allowed;
+  opacity: 0.6;
+}
diff --git a/webui/src/components/AskUserPrompt.tsx b/webui/src/components/AskUserPrompt.tsx
new file mode 100644
index 00000000..cd115e52
--- /dev/null
+++ b/webui/src/components/AskUserPrompt.tsx
@@ -0,0 +1,81 @@
+import { FormEvent, useState } from 'react';
+import { api, formatApiError } from '../api/client';
+import type { PendingAsk } from '../api/types';
+import styles from './AskUserPrompt.module.css';
+
+interface Props {
+  request: PendingAsk;
+  onResolved: () => void;
+}
+
+export default function AskUserPrompt({ request, onResolved }: Props) {
+  const [response, setResponse] = useState('');
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(event: FormEvent) {
+    event.preventDefault();
+    const answer = response.trim();
+    if (!answer || submitting) return;
+    setSubmitting(true);
+    setError(null);
+    try {
+      await api.respondToAsk(request.runId, answer, request.callId);
+      onResolved();
+    } catch (cause) {
+      setError(formatApiError(cause, 'Could not send your response.'));
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <div
+      className={styles.overlay}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="ask-user-title"
+    >
+      <form className={styles.card} onSubmit={submit}>
+        <h2 id="ask-user-title">Agent question</h2>
+        <p className={styles.question}>{request.question}</p>
+        {request.choices?.length ? (
+          <div className={styles.choices}>
+            {request.choices.map((choice) => (
+              <button
+                key={choice}
+                type="button"
+                className={response === choice ? styles.selected : styles.choice}
+                onClick={() => setResponse(choice)}
+                disabled={submitting}
+              >
+                {choice}
+              </button>
+            ))}
+          </div>
+        ) : null}
+        <label className={styles.label} htmlFor="ask-user-response">
+          Your response
+        </label>
+        <textarea
+          id="ask-user-response"
+          className={styles.input}
+          value={response}
+          onChange={(event) => setResponse(event.target.value)}
+          disabled={submitting}
+          autoFocus
+        />
+        {error && (
+          <p className={styles.error} role="alert">
+            {error}
+          </p>
+        )}
+        <div className={styles.actions}>
+          <button className={styles.submit} type="submit" disabled={submitting || !response.trim()}>
+            {submitting ? 'Sending...' : 'Send response'}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
diff --git a/webui/src/components/CreationRequestDialog.tsx b/webui/src/components/CreationRequestDialog.tsx
new file mode 100644
index 00000000..3ca9fe5d
--- /dev/null
+++ b/webui/src/components/CreationRequestDialog.tsx
@@ -0,0 +1,92 @@
+import { useState } from 'react';
+import { api, formatApiError } from '../api/client';
+import type { PendingCreation } from '../api/types';
+import styles from './AskUserPrompt.module.css';
+
+interface Props {
+  request: PendingCreation;
+  onResolved: () => void;
+}
+
+export default function CreationRequestDialog({ request, onResolved }: Props) {
+  const [submitting, setSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [modifications, setModifications] = useState(
+    request.preview ? JSON.stringify(request.preview, null, 2) : '',
+  );
+
+  async function resolve(decision: 'allow' | 'deny') {
+    if (submitting) return;
+    setSubmitting(true);
+    setError(null);
+    try {
+      let parsedModifications: Record<string, unknown> | undefined;
+      if (decision === 'allow' && modifications.trim()) {
+        const parsed = JSON.parse(modifications) as unknown;
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+          throw new Error('Modifications must be a JSON object.');
+        }
+        parsedModifications = parsed as Record<string, unknown>;
+      }
+      await api.resolveCreation(request.id, decision, parsedModifications);
+      onResolved();
+    } catch (cause) {
+      setError(formatApiError(cause, 'Could not resolve the creation request.'));
+    } finally {
+      setSubmitting(false);
+    }
+  }
+
+  return (
+    <div
+      className={styles.overlay}
+      role="dialog"
+      aria-modal="true"
+      aria-labelledby="creation-title"
+    >
+      <div className={styles.card}>
+        <h2 id="creation-title">Creation request</h2>
+        <p>
+          The agent wants to run <strong>{request.toolName}</strong>.
+        </p>
+        {request.preview && (
+          <>
+            <label className={styles.label} htmlFor="creation-modifications">
+              Proposed values
+            </label>
+            <textarea
+              id="creation-modifications"
+              className={styles.input}
+              value={modifications}
+              onChange={(event) => setModifications(event.target.value)}
+              disabled={submitting}
+            />
+          </>
+        )}
+        {error && (
+          <p className={styles.error} role="alert">
+            {error}
+          </p>
+        )}
+        <div className={styles.actions}>
+          <button
+            className={styles.choice}
+            type="button"
+            disabled={submitting}
+            onClick={() => resolve('deny')}
+          >
+            Deny
+          </button>
+          <button
+            className={styles.submit}
+            type="button"
+            disabled={submitting}
+            onClick={() => resolve('allow')}
+          >
+            {submitting ? 'Submitting...' : 'Allow'}
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/webui/src/hooks/useSSE.ts b/webui/src/hooks/useSSE.ts
index 38e5ddca..4c890d26 100644
--- a/webui/src/hooks/useSSE.ts
+++ b/webui/src/hooks/useSSE.ts
@@ -71,7 +71,6 @@ export function useSSE(url: string | null, dispatch: Dispatch<Action>, lastSeq:
             const frame = parseSseFrame(part);
             if (frame) {
               dispatchRef.current({ type: 'APPLY_SSE', frame });
-              dispatchRef.current({ type: 'SET_LAST_SEQ', seq: frame.seq });
             }
           }
         }

From 8f79d1317582b9467fc7a02cd2939273f7da1aeb Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 02:24:19 +0800
Subject: [PATCH 11/49] docs: align SSE workflow plan with runtime

---
 .../plans/2026-06-19-windows-desktop-redesign.md            | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
index ca63c914..0054ac00 100644
--- a/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
+++ b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
@@ -220,7 +220,7 @@ git commit -m "feat(webui): add typed worldbuilding APIs"
 - Test: `webui/src/__tests__/sse-workflows.test.tsx`
 
 **Interfaces:**
-- Produces: `runtimeApi.respondToAsk(runId: string, response: string)`, `pendingAsk`, `pendingCreation`, `RESOLVE_ASK`, `RESOLVE_CREATION` actions.
+- Produces: `runtimeApi.respondToAsk(runId: string, callId: string, response: string)`, `pendingAsk`, `pendingCreation`, and identifier-bearing `RESOLVE_ASK` / `RESOLVE_CREATION` actions.
 - Consumes: existing `resolveCreation(id, decision, modifications?)` behavior.
 
 - [ ] **Step 1: Add reducer tests for SSE lifecycle and deduplication**
@@ -242,11 +242,11 @@ Expected: FAIL because pending workflow state and dialogs do not exist.
 - [ ] **Step 3: Implement typed SSE state and dialogs**
 
 ```ts
-export interface PendingAsk { runId: string; question: string; choices?: string[]; }
+export interface PendingAsk { runId: string; callId: string; question: string; choices?: string[]; multiSelect: boolean; }
 export interface PendingCreation { id: string; toolName: string; preview?: Record<string, unknown>; }
 ```
 
-Reject frames whose `seq` is nonzero and `seq <= state.lastSeq`. On submit, disable the dialog, call the real endpoint, clear state only on success, and show `formatApiError` on failure. Clear creation state on both `creation_resolved` and successful local resolution.
+Reject frames whose `seq` is nonzero and `seq <= state.lastSeq`. On submit, disable the dialog, call the real endpoint with the SSE `call_id`, clear only the same request identifier on success, and show `formatApiError` on failure. A `creation_resolved` frame clears state only when its matching `result.ok` is not false. Terminal run events clear matching pending ask/creation state. Multi-select requests support toggling multiple options and expose `aria-pressed`; dialogs trap focus while open and restore focus when closed.
 
 - [ ] **Step 4: Verify workflow tests and all reducer tests**
 

From 1f2a17fa5e07dc3186d5f8a0150d59638448357a Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 02:30:09 +0800
Subject: [PATCH 12/49] fix(webui): harden interactive SSE workflows

---
 webui/src/App.tsx                             |   4 +-
 webui/src/AppState.tsx                        |  38 ++++--
 webui/src/__tests__/AppState.test.ts          |  96 +++++++++++++-
 webui/src/__tests__/sse-workflows.test.tsx    | 123 +++++++++++++++++-
 webui/src/api/runtime.ts                      |   2 +-
 webui/src/api/types.ts                        |   4 +-
 webui/src/components/AskUserPrompt.tsx        |  82 ++++++++++--
 .../src/components/CreationRequestDialog.tsx  |  16 ++-
 8 files changed, 331 insertions(+), 34 deletions(-)

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index d52b837c..e02fbe1f 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -333,13 +333,13 @@ function AppInner() {
       {state.pendingAsk && (
         <AskUserPrompt
           request={state.pendingAsk}
-          onResolved={() => dispatch({ type: 'RESOLVE_ASK' })}
+          onResolved={(callId) => dispatch({ type: 'RESOLVE_ASK', callId })}
         />
       )}
       {state.pendingCreation && (
         <CreationRequestDialog
           request={state.pendingCreation}
-          onResolved={() => dispatch({ type: 'RESOLVE_CREATION' })}
+          onResolved={(creationId) => dispatch({ type: 'RESOLVE_CREATION', creationId })}
         />
       )}
 
diff --git a/webui/src/AppState.tsx b/webui/src/AppState.tsx
index 96494b04..aabe9af7 100644
--- a/webui/src/AppState.tsx
+++ b/webui/src/AppState.tsx
@@ -314,8 +314,8 @@ export type Action =
   | { type: 'COMMIT_ACTIVE' }
   | { type: 'SET_STORY_VERSION' }
   | { type: 'APPLY_SSE'; frame: SseFrame }
-  | { type: 'RESOLVE_ASK' }
-  | { type: 'RESOLVE_CREATION' }
+  | { type: 'RESOLVE_ASK'; callId: string }
+  | { type: 'RESOLVE_CREATION'; creationId: string }
   | { type: 'SET_PIPELINE_CONDITIONS'; conditions: ConditionState[] }
   | { type: 'SET_PIPELINE_VIEW'; view: Partial<PipelineViewData> }
   | { type: 'DISMISS_PHASE_PROMPT' }
@@ -697,10 +697,12 @@ export function reducer(state: AppState, action: Action): AppState {
     }
 
     case 'RESOLVE_ASK':
-      return { ...state, pendingAsk: null };
+      return state.pendingAsk?.callId === action.callId ? { ...state, pendingAsk: null } : state;
 
     case 'RESOLVE_CREATION':
-      return { ...state, pendingCreation: null };
+      return state.pendingCreation?.id === action.creationId
+        ? { ...state, pendingCreation: null }
+        : state;
 
     case 'SET_PIPELINE_CONDITIONS':
       return { ...state, pipelineConditions: action.conditions };
@@ -896,10 +898,10 @@ function applySseFrame(state: AppState, frame: SseFrame): AppState {
         ...state,
         pendingAsk: {
           runId: (p.run_id as string) || state.currentRun || '',
-          ...(typeof p.call_id === 'string' && p.call_id ? { callId: p.call_id } : {}),
+          callId: (p.call_id as string) ?? '',
           question: (p.question as string) ?? '',
           ...(choices?.length ? { choices } : {}),
-          ...(typeof p.multi_select === 'boolean' ? { multiSelect: p.multi_select } : {}),
+          multiSelect: p.multi_select === true,
         },
       };
     }
@@ -916,10 +918,12 @@ function applySseFrame(state: AppState, frame: SseFrame): AppState {
         },
       };
 
-    case 'creation_resolved':
-      return state.pendingCreation?.id === p.creation_id || !p.creation_id
-        ? reducer(state, { type: 'RESOLVE_CREATION' })
-        : state;
+    case 'creation_resolved': {
+      const result = p.result as Record<string, unknown> | undefined;
+      if (result?.ok === false) return state;
+      const creationId = (p.creation_id as string) ?? '';
+      return reducer(state, { type: 'RESOLVE_CREATION', creationId });
+    }
 
     case 'usage_updated':
       return reducer(state, {
@@ -937,7 +941,8 @@ function applySseFrame(state: AppState, frame: SseFrame): AppState {
         message: { id: msgId(), kind: 'system', text: `${type} — ${JSON.stringify(p)}` },
       });
 
-    case 'run_completed':
+    case 'run_completed': {
+      state = clearPendingForTerminalRun(state, (p.run_id as string) || state.currentRun || '');
       return reducer(
         reducer(reducer(state, { type: 'COMMIT_ACTIVE' }), {
           type: 'SET_CURRENT_RUN',
@@ -945,10 +950,12 @@ function applySseFrame(state: AppState, frame: SseFrame): AppState {
         }),
         { type: 'SET_STATUS', status: 'idle' },
       );
+    }
 
     case 'run_failed':
     case 'run_cancelled':
     case 'run_interrupted':
+      state = clearPendingForTerminalRun(state, (p.run_id as string) || state.currentRun || '');
       state = reducer(reducer(state, { type: 'COMMIT_ACTIVE' }), {
         type: 'SET_CURRENT_RUN',
         runId: null,
@@ -1130,6 +1137,15 @@ function applySseFrame(state: AppState, frame: SseFrame): AppState {
   }
 }
 
+function clearPendingForTerminalRun(state: AppState, runId: string): AppState {
+  if (!runId) return state;
+  return {
+    ...state,
+    pendingAsk: state.pendingAsk?.runId === runId ? null : state.pendingAsk,
+    pendingCreation: state.currentRun === runId ? null : state.pendingCreation,
+  };
+}
+
 function generatedFilesFromText(text: string): GeneratedFileEntry[] {
   const paths = new Set<string>();
   const filePattern =
diff --git a/webui/src/__tests__/AppState.test.ts b/webui/src/__tests__/AppState.test.ts
index d188f9c4..50d86d1c 100644
--- a/webui/src/__tests__/AppState.test.ts
+++ b/webui/src/__tests__/AppState.test.ts
@@ -11,7 +11,12 @@ describe('AppState reducer', () => {
     const prev = state({
       messages: [{ id: 'm1', kind: 'user', text: 'hi' }],
       lastSeq: 5,
-      pendingAsk: { runId: 'old-run', question: 'Old question' },
+      pendingAsk: {
+        runId: 'old-run',
+        callId: 'old-call',
+        question: 'Old question',
+        multiSelect: false,
+      },
       pendingCreation: { id: 'old-creation', toolName: 'create_scene' },
     });
     const next = reducer(prev, { type: 'SET_SESSION', sessionId: 'new-id' });
@@ -233,8 +238,9 @@ describe('AppState reducer', () => {
       callId: 'call_1',
       question: 'Choose POV',
       choices: ['First person', 'Third person'],
+      multiSelect: false,
     });
-    expect(reducer(asked, { type: 'RESOLVE_ASK' }).pendingAsk).toBeNull();
+    expect(reducer(asked, { type: 'RESOLVE_ASK', callId: 'call_1' }).pendingAsk).toBeNull();
 
     const creationFrame = {
       seq: 11,
@@ -257,7 +263,84 @@ describe('AppState reducer', () => {
         },
       }).pendingCreation,
     ).toBeNull();
-    expect(reducer(requested, { type: 'RESOLVE_CREATION' }).pendingCreation).toBeNull();
+    expect(
+      reducer(requested, { type: 'RESOLVE_CREATION', creationId: 'creation_1' }).pendingCreation,
+    ).toBeNull();
+  });
+
+  it('retains a creation request when its resolving SSE result fails', () => {
+    const prev = state({
+      pendingCreation: { id: 'creation_1', toolName: 'create_scene' },
+      lastSeq: 4,
+    });
+    const next = reducer(prev, {
+      type: 'APPLY_SSE',
+      frame: {
+        seq: 5,
+        type: 'creation_resolved',
+        payload: { creation_id: 'creation_1', result: { ok: false } },
+      },
+    });
+    expect(next.pendingCreation).toEqual(prev.pendingCreation);
+  });
+
+  it('does not let stale local resolutions clear newer requests', () => {
+    const prev = state({
+      pendingAsk: {
+        runId: 'run_2',
+        callId: 'call_2',
+        question: 'New question',
+        multiSelect: false,
+      },
+      pendingCreation: { id: 'creation_2', toolName: 'create_scene' },
+    });
+    expect(reducer(prev, { type: 'RESOLVE_ASK', callId: 'call_1' }).pendingAsk).toEqual(
+      prev.pendingAsk,
+    );
+    expect(
+      reducer(prev, { type: 'RESOLVE_CREATION', creationId: 'creation_1' }).pendingCreation,
+    ).toEqual(prev.pendingCreation);
+  });
+
+  it.each(['run_completed', 'run_failed', 'run_cancelled', 'run_interrupted'])(
+    'clears matching pending requests on %s',
+    (type) => {
+      const prev = state({
+        currentRun: 'run_1',
+        pendingAsk: {
+          runId: 'run_1',
+          callId: 'call_1',
+          question: 'Question',
+          multiSelect: false,
+        },
+        pendingCreation: { id: 'creation_1', toolName: 'create_scene' },
+      });
+      const next = reducer(prev, {
+        type: 'APPLY_SSE',
+        frame: { seq: 8, type, payload: { run_id: 'run_1' } },
+      });
+      expect(next.pendingAsk).toBeNull();
+      expect(next.pendingCreation).toBeNull();
+    },
+  );
+
+  it('keeps newer pending requests when an older run terminates', () => {
+    const prev = state({
+      currentRun: 'run_2',
+      pendingAsk: {
+        runId: 'run_2',
+        callId: 'call_2',
+        question: 'Question',
+        multiSelect: false,
+      },
+      pendingCreation: { id: 'creation_2', toolName: 'create_scene' },
+    });
+    const next = reducer(prev, {
+      type: 'APPLY_SSE',
+      frame: { seq: 8, type: 'run_completed', payload: { run_id: 'run_1' } },
+    });
+    expect(next.pendingAsk).toEqual(prev.pendingAsk);
+    expect(next.pendingCreation).toEqual(prev.pendingCreation);
   });
 
   it('ignores duplicate and stale nonzero SSE frames before applying their effects', () => {
@@ -273,7 +356,12 @@ describe('AppState reducer', () => {
       type: 'APPLY_SSE',
       frame: { ...askFrame, seq: 0 },
     });
-    expect(zeroSeq.pendingAsk).toEqual({ runId: 'r1', question: 'Choose POV' });
+    expect(zeroSeq.pendingAsk).toEqual({
+      runId: 'r1',
+      callId: '',
+      question: 'Choose POV',
+      multiSelect: false,
+    });
     expect(zeroSeq.lastSeq).toBe(10);
   });
 
diff --git a/webui/src/__tests__/sse-workflows.test.tsx b/webui/src/__tests__/sse-workflows.test.tsx
index 3d1e3612..a9c8fd2a 100644
--- a/webui/src/__tests__/sse-workflows.test.tsx
+++ b/webui/src/__tests__/sse-workflows.test.tsx
@@ -48,19 +48,23 @@ describe('interactive SSE workflows', () => {
     fireEvent.click(submit);
 
     expect(apiMocks.respondToAsk).toHaveBeenCalledOnce();
-    expect(apiMocks.respondToAsk).toHaveBeenCalledWith('run_1', 'First person', 'call_1');
+    expect(apiMocks.respondToAsk).toHaveBeenCalledWith('run_1', 'call_1', 'First person');
     expect(onResolved).not.toHaveBeenCalled();
     expect(screen.getByRole('button', { name: 'Sending...' })).toBeDisabled();
 
     complete();
     await waitFor(() => expect(onResolved).toHaveBeenCalledOnce());
+    expect(onResolved).toHaveBeenCalledWith('call_1');
   });
 
   it('keeps the ask dialog open and formats request errors', async () => {
     apiMocks.respondToAsk.mockRejectedValue(new Error('Run is no longer waiting'));
     const onResolved = vi.fn();
     render(
-      <AskUserPrompt request={{ runId: 'run_1', question: 'Continue?' }} onResolved={onResolved} />,
+      <AskUserPrompt
+        request={{ runId: 'run_1', callId: 'call_1', question: 'Continue?', multiSelect: false }}
+        onResolved={onResolved}
+      />,
     );
     fireEvent.change(screen.getByLabelText('Your response'), { target: { value: 'Yes' } });
     fireEvent.click(screen.getByRole('button', { name: 'Send response' }));
@@ -69,6 +73,56 @@ describe('interactive SSE workflows', () => {
     expect(onResolved).not.toHaveBeenCalled();
   });
 
+  it('toggles multiple ask options and exposes their selected state', async () => {
+    apiMocks.respondToAsk.mockResolvedValue({ ok: true });
+    render(
+      <AskUserPrompt
+        request={{
+          runId: 'run_1',
+          callId: 'call_1',
+          question: 'Choose themes',
+          choices: ['Hope', 'Loss', 'Memory'],
+          multiSelect: true,
+        }}
+        onResolved={vi.fn()}
+      />,
+    );
+    const hope = screen.getByRole('button', { name: 'Hope' });
+    const loss = screen.getByRole('button', { name: 'Loss' });
+    fireEvent.click(hope);
+    fireEvent.click(loss);
+    expect(hope).toHaveAttribute('aria-pressed', 'true');
+    expect(loss).toHaveAttribute('aria-pressed', 'true');
+    fireEvent.click(hope);
+    expect(hope).toHaveAttribute('aria-pressed', 'false');
+    fireEvent.click(screen.getByRole('button', { name: 'Send response' }));
+    await waitFor(() =>
+      expect(apiMocks.respondToAsk).toHaveBeenCalledWith('run_1', 'call_1', 'Loss'),
+    );
+  });
+
+  it('resets ask input and errors when request identity changes', async () => {
+    apiMocks.respondToAsk.mockRejectedValueOnce(new Error('Old failure'));
+    const { rerender } = render(
+      <AskUserPrompt
+        request={{ runId: 'run_1', callId: 'call_1', question: 'Old?', multiSelect: false }}
+        onResolved={vi.fn()}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText('Your response'), { target: { value: 'Old answer' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Send response' }));
+    expect(await screen.findByRole('alert')).toHaveTextContent('Old failure');
+
+    rerender(
+      <AskUserPrompt
+        request={{ runId: 'run_2', callId: 'call_2', question: 'New?', multiSelect: false }}
+        onResolved={vi.fn()}
+      />,
+    );
+    expect(screen.getByLabelText('Your response')).toHaveValue('');
+    expect(screen.queryByRole('alert')).toBeNull();
+  });
+
   it.each([
     ['Allow', 'allow'],
     ['Deny', 'deny'],
@@ -84,6 +138,7 @@ describe('interactive SSE workflows', () => {
     fireEvent.click(screen.getByRole('button', { name: button }));
 
     await waitFor(() => expect(onResolved).toHaveBeenCalledOnce());
+    expect(onResolved).toHaveBeenCalledWith('creation_1');
     expect(apiMocks.resolveCreation).toHaveBeenCalledOnce();
     expect(apiMocks.resolveCreation).toHaveBeenCalledWith(
       'creation_1',
@@ -92,6 +147,70 @@ describe('interactive SSE workflows', () => {
     );
   });
 
+  it('resets creation edits and errors when request identity changes', async () => {
+    apiMocks.resolveCreation.mockRejectedValueOnce(new Error('Old failure'));
+    const { rerender } = render(
+      <CreationRequestDialog
+        request={{ id: 'creation_1', toolName: 'create_scene', preview: { title: 'Old' } }}
+        onResolved={vi.fn()}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Allow' }));
+    expect(await screen.findByRole('alert')).toHaveTextContent('Old failure');
+    rerender(
+      <CreationRequestDialog
+        request={{ id: 'creation_2', toolName: 'create_scene', preview: { title: 'New' } }}
+        onResolved={vi.fn()}
+      />,
+    );
+    expect(screen.getByLabelText('Proposed values')).toHaveValue('{\n  "title": "New"\n}');
+    expect(screen.queryByRole('alert')).toBeNull();
+  });
+
+  it.each([
+    ['ask', 'Agent question'],
+    ['creation', 'Creation request'],
+  ] as const)('traps and restores focus for the %s dialog', (_kind, title) => {
+    const opener = document.createElement('button');
+    document.body.append(opener);
+    opener.focus();
+    const view =
+      title === 'Agent question'
+        ? render(
+            <AskUserPrompt
+              request={{
+                runId: 'run_1',
+                callId: 'call_1',
+                question: 'Choose',
+                choices: ['One'],
+                multiSelect: false,
+              }}
+              onResolved={vi.fn()}
+            />,
+          )
+        : render(
+            <CreationRequestDialog
+              request={{ id: 'creation_1', toolName: 'create_scene', preview: { title: 'One' } }}
+              onResolved={vi.fn()}
+            />,
+          );
+    const dialog = screen.getByRole('dialog', { name: title });
+    const focusable = dialog.querySelectorAll<HTMLElement>(
+      'button:not([disabled]), textarea:not([disabled])',
+    );
+    const first = focusable[0];
+    const last = focusable[focusable.length - 1];
+    last.focus();
+    fireEvent.keyDown(dialog, { key: 'Tab' });
+    expect(document.activeElement).toBe(first);
+    first.focus();
+    fireEvent.keyDown(dialog, { key: 'Tab', shiftKey: true });
+    expect(document.activeElement).toBe(last);
+    view.unmount();
+    expect(document.activeElement).toBe(opener);
+    opener.remove();
+  });
+
   it('keeps the creation dialog open when resolution fails', async () => {
     apiMocks.resolveCreation.mockRejectedValue(new Error('Creation expired'));
     const onResolved = vi.fn();
diff --git a/webui/src/api/runtime.ts b/webui/src/api/runtime.ts
index eea02ef8..c66f727e 100644
--- a/webui/src/api/runtime.ts
+++ b/webui/src/api/runtime.ts
@@ -76,7 +76,7 @@ export const runtimeApi = {
       decision: allow ? 'allow' : 'deny',
     }),
   cancelRun: (id: string) => request<CancelRunResponse>('POST', `/v1/runs/${id}/cancel`),
-  respondToAsk: (runId: string, response: string, callId = runId) =>
+  respondToAsk: (runId: string, callId: string, response: string) =>
     request<AskResponse>('POST', `/v1/runs/${runId}/ask-response`, {
       call_id: callId,
       response,
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 4b2e6ff2..49ba0136 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -6,10 +6,10 @@ export interface SseFrame {
 
 export interface PendingAsk {
   runId: string;
-  callId?: string;
+  callId: string;
   question: string;
   choices?: string[];
-  multiSelect?: boolean;
+  multiSelect: boolean;
 }
 
 export interface PendingCreation {
diff --git a/webui/src/components/AskUserPrompt.tsx b/webui/src/components/AskUserPrompt.tsx
index cd115e52..2f570586 100644
--- a/webui/src/components/AskUserPrompt.tsx
+++ b/webui/src/components/AskUserPrompt.tsx
@@ -1,27 +1,90 @@
-import { FormEvent, useState } from 'react';
+import { FormEvent, RefObject, useEffect, useRef, useState } from 'react';
 import { api, formatApiError } from '../api/client';
 import type { PendingAsk } from '../api/types';
 import styles from './AskUserPrompt.module.css';
 
 interface Props {
   request: PendingAsk;
-  onResolved: () => void;
+  onResolved: (callId: string) => void;
+}
+
+const focusableSelector =
+  'button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export function useDialogFocus(dialogRef: RefObject<HTMLElement | null>) {
+  useEffect(() => {
+    const previousFocus =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    const dialog = dialogRef.current;
+    const focusables = () =>
+      Array.from(dialog?.querySelectorAll<HTMLElement>(focusableSelector) ?? []);
+    if (dialog && !dialog.contains(document.activeElement)) focusables()[0]?.focus();
+
+    function trapFocus(event: KeyboardEvent) {
+      if (event.key !== 'Tab' || !dialog) return;
+      const elements = focusables();
+      if (!elements.length) return;
+      const first = elements[0];
+      const last = elements[elements.length - 1];
+      if (
+        event.shiftKey &&
+        (document.activeElement === first || !dialog.contains(document.activeElement))
+      ) {
+        event.preventDefault();
+        last.focus();
+      } else if (
+        !event.shiftKey &&
+        (document.activeElement === last || !dialog.contains(document.activeElement))
+      ) {
+        event.preventDefault();
+        first.focus();
+      }
+    }
+
+    dialog?.addEventListener('keydown', trapFocus);
+    return () => {
+      dialog?.removeEventListener('keydown', trapFocus);
+      previousFocus?.focus();
+    };
+  }, [dialogRef]);
 }
 
 export default function AskUserPrompt({ request, onResolved }: Props) {
   const [response, setResponse] = useState('');
+  const [selectedChoices, setSelectedChoices] = useState<string[]>([]);
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const dialogRef = useRef<HTMLDivElement>(null);
+  useDialogFocus(dialogRef);
+
+  useEffect(() => {
+    setResponse('');
+    setSelectedChoices([]);
+    setSubmitting(false);
+    setError(null);
+  }, [request.callId]);
+
+  const answer = response.trim() || selectedChoices.join(', ');
+
+  function toggleChoice(choice: string) {
+    if (request.multiSelect) {
+      setSelectedChoices((current) =>
+        current.includes(choice) ? current.filter((item) => item !== choice) : [...current, choice],
+      );
+      return;
+    }
+    setSelectedChoices([choice]);
+    setResponse(choice);
+  }
 
   async function submit(event: FormEvent) {
     event.preventDefault();
-    const answer = response.trim();
     if (!answer || submitting) return;
     setSubmitting(true);
     setError(null);
     try {
-      await api.respondToAsk(request.runId, answer, request.callId);
-      onResolved();
+      await api.respondToAsk(request.runId, request.callId, answer);
+      onResolved(request.callId);
     } catch (cause) {
       setError(formatApiError(cause, 'Could not send your response.'));
     } finally {
@@ -32,6 +95,7 @@ export default function AskUserPrompt({ request, onResolved }: Props) {
   return (
     <div
       className={styles.overlay}
+      ref={dialogRef}
       role="dialog"
       aria-modal="true"
       aria-labelledby="ask-user-title"
@@ -45,8 +109,9 @@ export default function AskUserPrompt({ request, onResolved }: Props) {
               <button
                 key={choice}
                 type="button"
-                className={response === choice ? styles.selected : styles.choice}
-                onClick={() => setResponse(choice)}
+                className={selectedChoices.includes(choice) ? styles.selected : styles.choice}
+                onClick={() => toggleChoice(choice)}
+                aria-pressed={selectedChoices.includes(choice)}
                 disabled={submitting}
               >
                 {choice}
@@ -63,7 +128,6 @@ export default function AskUserPrompt({ request, onResolved }: Props) {
           value={response}
           onChange={(event) => setResponse(event.target.value)}
           disabled={submitting}
-          autoFocus
         />
         {error && (
           <p className={styles.error} role="alert">
@@ -71,7 +135,7 @@ export default function AskUserPrompt({ request, onResolved }: Props) {
           </p>
         )}
         <div className={styles.actions}>
-          <button className={styles.submit} type="submit" disabled={submitting || !response.trim()}>
+          <button className={styles.submit} type="submit" disabled={submitting || !answer}>
             {submitting ? 'Sending...' : 'Send response'}
           </button>
         </div>
diff --git a/webui/src/components/CreationRequestDialog.tsx b/webui/src/components/CreationRequestDialog.tsx
index 3ca9fe5d..21c67e2f 100644
--- a/webui/src/components/CreationRequestDialog.tsx
+++ b/webui/src/components/CreationRequestDialog.tsx
@@ -1,11 +1,12 @@
-import { useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { api, formatApiError } from '../api/client';
 import type { PendingCreation } from '../api/types';
+import { useDialogFocus } from './AskUserPrompt';
 import styles from './AskUserPrompt.module.css';
 
 interface Props {
   request: PendingCreation;
-  onResolved: () => void;
+  onResolved: (creationId: string) => void;
 }
 
 export default function CreationRequestDialog({ request, onResolved }: Props) {
@@ -14,6 +15,14 @@ export default function CreationRequestDialog({ request, onResolved }: Props) {
   const [modifications, setModifications] = useState(
     request.preview ? JSON.stringify(request.preview, null, 2) : '',
   );
+  const dialogRef = useRef<HTMLDivElement>(null);
+  useDialogFocus(dialogRef);
+
+  useEffect(() => {
+    setSubmitting(false);
+    setError(null);
+    setModifications(request.preview ? JSON.stringify(request.preview, null, 2) : '');
+  }, [request.id]);
 
   async function resolve(decision: 'allow' | 'deny') {
     if (submitting) return;
@@ -29,7 +38,7 @@ export default function CreationRequestDialog({ request, onResolved }: Props) {
         parsedModifications = parsed as Record<string, unknown>;
       }
       await api.resolveCreation(request.id, decision, parsedModifications);
-      onResolved();
+      onResolved(request.id);
     } catch (cause) {
       setError(formatApiError(cause, 'Could not resolve the creation request.'));
     } finally {
@@ -40,6 +49,7 @@ export default function CreationRequestDialog({ request, onResolved }: Props) {
   return (
     <div
       className={styles.overlay}
+      ref={dialogRef}
       role="dialog"
       aria-modal="true"
       aria-labelledby="creation-title"

From 98437b36e08e4cf549e476e939623ce78a082e45 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 02:35:44 +0800
Subject: [PATCH 13/49] fix(webui): isolate interactive request lifecycles

---
 webui/src/AppState.tsx                        |   3 +-
 webui/src/__tests__/AppState.test.ts          |  41 ++++++-
 webui/src/__tests__/sse-workflows.test.tsx    | 110 +++++++++++++++++-
 webui/src/api/types.ts                        |   1 +
 webui/src/components/AskUserPrompt.tsx        |   9 +-
 .../src/components/CreationRequestDialog.tsx  |   9 +-
 6 files changed, 157 insertions(+), 16 deletions(-)

diff --git a/webui/src/AppState.tsx b/webui/src/AppState.tsx
index aabe9af7..b5f12d5a 100644
--- a/webui/src/AppState.tsx
+++ b/webui/src/AppState.tsx
@@ -911,6 +911,7 @@ function applySseFrame(state: AppState, frame: SseFrame): AppState {
         ...state,
         pendingCreation: {
           id: (p.creation_id as string) ?? '',
+          runId: (p.run_id as string) || state.currentRun || '',
           toolName: (p.tool as string) ?? '',
           ...(p.preview && typeof p.preview === 'object'
             ? { preview: p.preview as Record<string, unknown> }
@@ -1142,7 +1143,7 @@ function clearPendingForTerminalRun(state: AppState, runId: string): AppState {
   return {
     ...state,
     pendingAsk: state.pendingAsk?.runId === runId ? null : state.pendingAsk,
-    pendingCreation: state.currentRun === runId ? null : state.pendingCreation,
+    pendingCreation: state.pendingCreation?.runId === runId ? null : state.pendingCreation,
   };
 }
 
diff --git a/webui/src/__tests__/AppState.test.ts b/webui/src/__tests__/AppState.test.ts
index 50d86d1c..7849dfc1 100644
--- a/webui/src/__tests__/AppState.test.ts
+++ b/webui/src/__tests__/AppState.test.ts
@@ -17,7 +17,7 @@ describe('AppState reducer', () => {
         question: 'Old question',
         multiSelect: false,
       },
-      pendingCreation: { id: 'old-creation', toolName: 'create_scene' },
+      pendingCreation: { id: 'old-creation', runId: 'old-run', toolName: 'create_scene' },
     });
     const next = reducer(prev, { type: 'SET_SESSION', sessionId: 'new-id' });
     expect(next.sessionId).toBe('new-id');
@@ -245,11 +245,17 @@ describe('AppState reducer', () => {
     const creationFrame = {
       seq: 11,
       type: 'creation_requested',
-      payload: { creation_id: 'creation_1', tool: 'create_scene', preview: { title: 'Arrival' } },
+      payload: {
+        run_id: 'r1',
+        creation_id: 'creation_1',
+        tool: 'create_scene',
+        preview: { title: 'Arrival' },
+      },
     };
     const requested = reducer(asked, { type: 'APPLY_SSE', frame: creationFrame });
     expect(requested.pendingCreation).toEqual({
       id: 'creation_1',
+      runId: 'r1',
       toolName: 'create_scene',
       preview: { title: 'Arrival' },
     });
@@ -270,7 +276,7 @@ describe('AppState reducer', () => {
 
   it('retains a creation request when its resolving SSE result fails', () => {
     const prev = state({
-      pendingCreation: { id: 'creation_1', toolName: 'create_scene' },
+      pendingCreation: { id: 'creation_1', runId: 'run_1', toolName: 'create_scene' },
       lastSeq: 4,
     });
     const next = reducer(prev, {
@@ -292,7 +298,7 @@ describe('AppState reducer', () => {
         question: 'New question',
         multiSelect: false,
       },
-      pendingCreation: { id: 'creation_2', toolName: 'create_scene' },
+      pendingCreation: { id: 'creation_2', runId: 'run_2', toolName: 'create_scene' },
     });
     expect(reducer(prev, { type: 'RESOLVE_ASK', callId: 'call_1' }).pendingAsk).toEqual(
       prev.pendingAsk,
@@ -313,7 +319,7 @@ describe('AppState reducer', () => {
           question: 'Question',
           multiSelect: false,
         },
-        pendingCreation: { id: 'creation_1', toolName: 'create_scene' },
+        pendingCreation: { id: 'creation_1', runId: 'run_1', toolName: 'create_scene' },
       });
       const next = reducer(prev, {
         type: 'APPLY_SSE',
@@ -333,7 +339,7 @@ describe('AppState reducer', () => {
         question: 'Question',
         multiSelect: false,
       },
-      pendingCreation: { id: 'creation_2', toolName: 'create_scene' },
+      pendingCreation: { id: 'creation_2', runId: 'run_2', toolName: 'create_scene' },
     });
     const next = reducer(prev, {
       type: 'APPLY_SSE',
@@ -343,6 +349,29 @@ describe('AppState reducer', () => {
     expect(next.pendingCreation).toEqual(prev.pendingCreation);
   });
 
+  it('retains a creation from another run even when currentRun matches the terminal event', () => {
+    const pendingCreation = { id: 'creation_2', runId: 'run_2', toolName: 'create_scene' };
+    const next = reducer(state({ currentRun: 'run_1', pendingCreation }), {
+      type: 'APPLY_SSE',
+      frame: { seq: 8, type: 'run_completed', payload: { run_id: 'run_1' } },
+    });
+    expect(next.pendingCreation).toEqual(pendingCreation);
+  });
+
+  it('clears a creation matching the terminal run even when currentRun has moved on', () => {
+    const next = reducer(
+      state({
+        currentRun: 'run_3',
+        pendingCreation: { id: 'creation_2', runId: 'run_2', toolName: 'create_scene' },
+      }),
+      {
+        type: 'APPLY_SSE',
+        frame: { seq: 8, type: 'run_failed', payload: { run_id: 'run_2', error: 'stopped' } },
+      },
+    );
+    expect(next.pendingCreation).toBeNull();
+  });
+
   it('ignores duplicate and stale nonzero SSE frames before applying their effects', () => {
     const askFrame = {
       seq: 10,
diff --git a/webui/src/__tests__/sse-workflows.test.tsx b/webui/src/__tests__/sse-workflows.test.tsx
index a9c8fd2a..9d88470a 100644
--- a/webui/src/__tests__/sse-workflows.test.tsx
+++ b/webui/src/__tests__/sse-workflows.test.tsx
@@ -123,6 +123,47 @@ describe('interactive SSE workflows', () => {
     expect(screen.queryByRole('alert')).toBeNull();
   });
 
+  it('ignores completion from a replaced ask while the new request is submitting', async () => {
+    let rejectOld!: (error: Error) => void;
+    let resolveNew!: () => void;
+    apiMocks.respondToAsk
+      .mockReturnValueOnce(
+        new Promise<void>((_resolve, reject) => {
+          rejectOld = reject;
+        }),
+      )
+      .mockReturnValueOnce(
+        new Promise<void>((resolve) => {
+          resolveNew = resolve;
+        }),
+      );
+    const onResolved = vi.fn();
+    const { rerender } = render(
+      <AskUserPrompt
+        request={{ runId: 'run_1', callId: 'call_1', question: 'Old?', multiSelect: false }}
+        onResolved={onResolved}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText('Your response'), { target: { value: 'Old answer' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Send response' }));
+    rerender(
+      <AskUserPrompt
+        request={{ runId: 'run_2', callId: 'call_2', question: 'New?', multiSelect: false }}
+        onResolved={onResolved}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText('Your response'), { target: { value: 'New answer' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Send response' }));
+
+    rejectOld(new Error('Old failure'));
+    await waitFor(() => expect(apiMocks.respondToAsk).toHaveBeenCalledTimes(2));
+    expect(screen.queryByRole('alert')).toBeNull();
+    expect(screen.getByRole('button', { name: 'Sending...' })).toBeDisabled();
+
+    resolveNew();
+    await waitFor(() => expect(onResolved).toHaveBeenCalledWith('call_2'));
+  });
+
   it.each([
     ['Allow', 'allow'],
     ['Deny', 'deny'],
@@ -131,7 +172,12 @@ describe('interactive SSE workflows', () => {
     const onResolved = vi.fn();
     render(
       <CreationRequestDialog
-        request={{ id: 'creation_1', toolName: 'create_scene', preview: { title: 'Arrival' } }}
+        request={{
+          id: 'creation_1',
+          runId: 'run_1',
+          toolName: 'create_scene',
+          preview: { title: 'Arrival' },
+        }}
         onResolved={onResolved}
       />,
     );
@@ -151,7 +197,12 @@ describe('interactive SSE workflows', () => {
     apiMocks.resolveCreation.mockRejectedValueOnce(new Error('Old failure'));
     const { rerender } = render(
       <CreationRequestDialog
-        request={{ id: 'creation_1', toolName: 'create_scene', preview: { title: 'Old' } }}
+        request={{
+          id: 'creation_1',
+          runId: 'run_1',
+          toolName: 'create_scene',
+          preview: { title: 'Old' },
+        }}
         onResolved={vi.fn()}
       />,
     );
@@ -159,7 +210,12 @@ describe('interactive SSE workflows', () => {
     expect(await screen.findByRole('alert')).toHaveTextContent('Old failure');
     rerender(
       <CreationRequestDialog
-        request={{ id: 'creation_2', toolName: 'create_scene', preview: { title: 'New' } }}
+        request={{
+          id: 'creation_2',
+          runId: 'run_2',
+          toolName: 'create_scene',
+          preview: { title: 'New' },
+        }}
         onResolved={vi.fn()}
       />,
     );
@@ -167,6 +223,45 @@ describe('interactive SSE workflows', () => {
     expect(screen.queryByRole('alert')).toBeNull();
   });
 
+  it('ignores completion from a replaced creation while the new request is submitting', async () => {
+    let rejectOld!: (error: Error) => void;
+    let resolveNew!: () => void;
+    apiMocks.resolveCreation
+      .mockReturnValueOnce(
+        new Promise<void>((_resolve, reject) => {
+          rejectOld = reject;
+        }),
+      )
+      .mockReturnValueOnce(
+        new Promise<void>((resolve) => {
+          resolveNew = resolve;
+        }),
+      );
+    const onResolved = vi.fn();
+    const { rerender } = render(
+      <CreationRequestDialog
+        request={{ id: 'creation_1', runId: 'run_1', toolName: 'create_scene' }}
+        onResolved={onResolved}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Allow' }));
+    rerender(
+      <CreationRequestDialog
+        request={{ id: 'creation_2', runId: 'run_2', toolName: 'create_scene' }}
+        onResolved={onResolved}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Allow' }));
+
+    rejectOld(new Error('Old failure'));
+    await waitFor(() => expect(apiMocks.resolveCreation).toHaveBeenCalledTimes(2));
+    expect(screen.queryByRole('alert')).toBeNull();
+    expect(screen.getByRole('button', { name: 'Submitting...' })).toBeDisabled();
+
+    resolveNew();
+    await waitFor(() => expect(onResolved).toHaveBeenCalledWith('creation_2'));
+  });
+
   it.each([
     ['ask', 'Agent question'],
     ['creation', 'Creation request'],
@@ -190,7 +285,12 @@ describe('interactive SSE workflows', () => {
           )
         : render(
             <CreationRequestDialog
-              request={{ id: 'creation_1', toolName: 'create_scene', preview: { title: 'One' } }}
+              request={{
+                id: 'creation_1',
+                runId: 'run_1',
+                toolName: 'create_scene',
+                preview: { title: 'One' },
+              }}
               onResolved={vi.fn()}
             />,
           );
@@ -216,7 +316,7 @@ describe('interactive SSE workflows', () => {
     const onResolved = vi.fn();
     render(
       <CreationRequestDialog
-        request={{ id: 'creation_1', toolName: 'create_scene' }}
+        request={{ id: 'creation_1', runId: 'run_1', toolName: 'create_scene' }}
         onResolved={onResolved}
       />,
     );
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 49ba0136..5888959e 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -14,6 +14,7 @@ export interface PendingAsk {
 
 export interface PendingCreation {
   id: string;
+  runId: string;
   toolName: string;
   preview?: Record<string, unknown>;
 }
diff --git a/webui/src/components/AskUserPrompt.tsx b/webui/src/components/AskUserPrompt.tsx
index 2f570586..2a5f5908 100644
--- a/webui/src/components/AskUserPrompt.tsx
+++ b/webui/src/components/AskUserPrompt.tsx
@@ -55,6 +55,8 @@ export default function AskUserPrompt({ request, onResolved }: Props) {
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const dialogRef = useRef<HTMLDivElement>(null);
+  const requestIdRef = useRef(request.callId);
+  requestIdRef.current = request.callId;
   useDialogFocus(dialogRef);
 
   useEffect(() => {
@@ -82,13 +84,16 @@ export default function AskUserPrompt({ request, onResolved }: Props) {
     if (!answer || submitting) return;
     setSubmitting(true);
     setError(null);
+    const submittedCallId = request.callId;
     try {
       await api.respondToAsk(request.runId, request.callId, answer);
       onResolved(request.callId);
     } catch (cause) {
-      setError(formatApiError(cause, 'Could not send your response.'));
+      if (requestIdRef.current === submittedCallId) {
+        setError(formatApiError(cause, 'Could not send your response.'));
+      }
     } finally {
-      setSubmitting(false);
+      if (requestIdRef.current === submittedCallId) setSubmitting(false);
     }
   }
 
diff --git a/webui/src/components/CreationRequestDialog.tsx b/webui/src/components/CreationRequestDialog.tsx
index 21c67e2f..4c6ac871 100644
--- a/webui/src/components/CreationRequestDialog.tsx
+++ b/webui/src/components/CreationRequestDialog.tsx
@@ -16,6 +16,8 @@ export default function CreationRequestDialog({ request, onResolved }: Props) {
     request.preview ? JSON.stringify(request.preview, null, 2) : '',
   );
   const dialogRef = useRef<HTMLDivElement>(null);
+  const requestIdRef = useRef(request.id);
+  requestIdRef.current = request.id;
   useDialogFocus(dialogRef);
 
   useEffect(() => {
@@ -28,6 +30,7 @@ export default function CreationRequestDialog({ request, onResolved }: Props) {
     if (submitting) return;
     setSubmitting(true);
     setError(null);
+    const submittedCreationId = request.id;
     try {
       let parsedModifications: Record<string, unknown> | undefined;
       if (decision === 'allow' && modifications.trim()) {
@@ -40,9 +43,11 @@ export default function CreationRequestDialog({ request, onResolved }: Props) {
       await api.resolveCreation(request.id, decision, parsedModifications);
       onResolved(request.id);
     } catch (cause) {
-      setError(formatApiError(cause, 'Could not resolve the creation request.'));
+      if (requestIdRef.current === submittedCreationId) {
+        setError(formatApiError(cause, 'Could not resolve the creation request.'));
+      }
     } finally {
-      setSubmitting(false);
+      if (requestIdRef.current === submittedCreationId) setSubmitting(false);
     }
   }
 

From 40647532d77d7d78f2d3409135d286b80f21da96 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 02:46:36 +0800
Subject: [PATCH 14/49] feat(webui): add resource page primitives

---
 webui/src/__tests__/pages.test.tsx            | 189 ++++++++++++++++++
 .../components/layout/DetailPane.module.css   |  80 ++++++++
 webui/src/components/layout/DetailPane.tsx    |  47 +++++
 .../components/layout/PageState.module.css    |  91 +++++++++
 webui/src/components/layout/PageState.tsx     |  83 ++++++++
 .../components/layout/ResourceList.module.css |  34 ++++
 webui/src/components/layout/ResourceList.tsx  |  79 ++++++++
 webui/src/hooks/useResource.ts                |  69 +++++++
 8 files changed, 672 insertions(+)
 create mode 100644 webui/src/__tests__/pages.test.tsx
 create mode 100644 webui/src/components/layout/DetailPane.module.css
 create mode 100644 webui/src/components/layout/DetailPane.tsx
 create mode 100644 webui/src/components/layout/PageState.module.css
 create mode 100644 webui/src/components/layout/PageState.tsx
 create mode 100644 webui/src/components/layout/ResourceList.module.css
 create mode 100644 webui/src/components/layout/ResourceList.tsx
 create mode 100644 webui/src/hooks/useResource.ts

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
new file mode 100644
index 00000000..5d08beec
--- /dev/null
+++ b/webui/src/__tests__/pages.test.tsx
@@ -0,0 +1,189 @@
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import DetailPane from '../components/layout/DetailPane';
+import PageState from '../components/layout/PageState';
+import ResourceList from '../components/layout/ResourceList';
+import { useResource } from '../hooks/useResource';
+
+type Deferred<T> = {
+  promise: Promise<T>;
+  resolve(value: T): void;
+  reject(error: unknown): void;
+};
+
+function deferred<T>(): Deferred<T> {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((resolvePromise, rejectPromise) => {
+    resolve = resolvePromise;
+    reject = rejectPromise;
+  });
+  return { promise, resolve, reject };
+}
+
+function ResourceHarness({
+  resourceKey,
+  loader,
+}: {
+  resourceKey: string;
+  loader: (signal: AbortSignal) => Promise<string>;
+}) {
+  const resource = useResource(resourceKey, loader);
+  return (
+    <div>
+      <output aria-label="status">{resource.status}</output>
+      <output aria-label="data">{resource.data ?? 'none'}</output>
+      <output aria-label="error">{resource.error?.message ?? 'none'}</output>
+      <button type="button" onClick={resource.retry}>
+        Retry resource
+      </button>
+    </div>
+  );
+}
+
+describe('useResource', () => {
+  it('aborts the previous request when the resource key changes', async () => {
+    const first = deferred<string>();
+    const second = deferred<string>();
+    const signals: AbortSignal[] = [];
+    const loader = vi.fn((signal: AbortSignal) => {
+      signals.push(signal);
+      return signals.length === 1 ? first.promise : second.promise;
+    });
+    const view = render(<ResourceHarness resourceKey="first" loader={loader} />);
+
+    await waitFor(() => expect(loader).toHaveBeenCalledTimes(1));
+    view.rerender(<ResourceHarness resourceKey="second" loader={loader} />);
+
+    await waitFor(() => expect(loader).toHaveBeenCalledTimes(2));
+    expect(signals[0].aborted).toBe(true);
+    expect(screen.getByLabelText('data')).toHaveTextContent('none');
+
+    await act(async () => second.resolve('second data'));
+    expect(screen.getByLabelText('data')).toHaveTextContent('second data');
+  });
+
+  it('retains successful data when a retry fails', async () => {
+    const retryRequest = deferred<string>();
+    const loader = vi
+      .fn<(signal: AbortSignal) => Promise<string>>()
+      .mockResolvedValueOnce('retained data')
+      .mockImplementationOnce(() => retryRequest.promise);
+
+    render(<ResourceHarness resourceKey="resource" loader={loader} />);
+    await waitFor(() => expect(screen.getByLabelText('status')).toHaveTextContent('ready'));
+
+    fireEvent.click(screen.getByRole('button', { name: 'Retry resource' }));
+    expect(screen.getByLabelText('status')).toHaveTextContent('loading');
+    expect(screen.getByLabelText('data')).toHaveTextContent('retained data');
+
+    await act(async () => retryRequest.reject(new Error('Refresh failed')));
+    expect(screen.getByLabelText('status')).toHaveTextContent('error');
+    expect(screen.getByLabelText('data')).toHaveTextContent('retained data');
+    expect(screen.getByLabelText('error')).toHaveTextContent('Refresh failed');
+  });
+
+  it('ignores an aborted request rejection', async () => {
+    const request = deferred<string>();
+    render(<ResourceHarness resourceKey="resource" loader={() => request.promise} />);
+
+    await act(async () => request.reject(new DOMException('Aborted', 'AbortError')));
+
+    expect(screen.getByLabelText('status')).toHaveTextContent('loading');
+    expect(screen.getByLabelText('error')).toHaveTextContent('none');
+  });
+});
+
+describe('PageState', () => {
+  it('shows a non-blocking warning while retaining stale content after refresh failure', () => {
+    const retry = vi.fn();
+    render(
+      <PageState error={new Error('Refresh failed')} hasData onRetry={retry}>
+        <p>Retained content</p>
+      </PageState>,
+    );
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Refresh failed');
+    expect(screen.getByText('Retained content')).toBeDefined();
+    fireEvent.click(screen.getByRole('button', { name: 'Retry' }));
+    expect(retry).toHaveBeenCalledOnce();
+  });
+
+  it('renders loading, full error, and empty states without page-specific copy', () => {
+    const { rerender } = render(<PageState loading loadingLabel="Loading worlds" />);
+    expect(screen.getByRole('status')).toHaveAccessibleName('Loading worlds');
+
+    rerender(<PageState error={new Error('Worlds unavailable')} onRetry={() => {}} />);
+    expect(screen.getByRole('alert')).toHaveTextContent('Worlds unavailable');
+
+    rerender(<PageState isEmpty emptyTitle="No worlds" emptyDescription="Create one to begin." />);
+    expect(screen.getByRole('heading', { name: 'No worlds' })).toBeDefined();
+    expect(screen.getByText('Create one to begin.')).toBeDefined();
+  });
+});
+
+describe('ResourceList', () => {
+  const items = [
+    { id: 'a', name: 'A' },
+    { id: 'b', name: 'B' },
+  ];
+
+  it('selects the next item with the keyboard and exposes the selected option', () => {
+    const onSelect = vi.fn();
+    render(
+      <ResourceList
+        ariaLabel="Characters"
+        items={items}
+        selectedId="a"
+        getId={(item) => item.id}
+        renderItem={(item) => item.name}
+        onSelect={onSelect}
+      />,
+    );
+
+    const listbox = screen.getByRole('listbox', { name: 'Characters' });
+    expect(screen.getByRole('option', { name: 'A' })).toHaveAttribute('aria-selected', 'true');
+    fireEvent.keyDown(listbox, { key: 'ArrowDown' });
+    expect(onSelect).toHaveBeenCalledWith('b');
+  });
+
+  it('supports boundary navigation and mouse selection', () => {
+    const onSelect = vi.fn();
+    render(
+      <ResourceList
+        items={items}
+        selectedId="b"
+        getId={(item) => item.id}
+        renderItem={(item) => item.name}
+        onSelect={onSelect}
+      />,
+    );
+
+    const listbox = screen.getByRole('listbox');
+    fireEvent.keyDown(listbox, { key: 'ArrowDown' });
+    expect(onSelect).toHaveBeenLastCalledWith('b');
+    fireEvent.keyDown(listbox, { key: 'Home' });
+    expect(onSelect).toHaveBeenLastCalledWith('a');
+    fireEvent.click(screen.getByRole('option', { name: 'B' }));
+    expect(onSelect).toHaveBeenLastCalledWith('b');
+  });
+});
+
+describe('DetailPane', () => {
+  it('provides a labeled detail region with actions and an optional inspector', () => {
+    render(
+      <DetailPane
+        title="Lian"
+        description="Archivist"
+        actions={<button type="button">Edit</button>}
+        inspector={<p>Related chapters</p>}
+      >
+        <p>Character details</p>
+      </DetailPane>,
+    );
+
+    expect(screen.getByRole('region', { name: 'Lian' })).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Edit' })).toBeDefined();
+    expect(screen.getByRole('complementary')).toHaveTextContent('Related chapters');
+  });
+});
diff --git a/webui/src/components/layout/DetailPane.module.css b/webui/src/components/layout/DetailPane.module.css
new file mode 100644
index 00000000..8154b809
--- /dev/null
+++ b/webui/src/components/layout/DetailPane.module.css
@@ -0,0 +1,80 @@
+.pane {
+  min-width: 0;
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  border: 1px solid var(--border);
+  border-radius: var(--rounded-lg);
+  background: var(--surface);
+}
+
+.header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-lg);
+  padding: var(--space-lg);
+  border-bottom: 1px solid var(--border);
+}
+
+.heading {
+  min-width: 0;
+}
+
+.heading h1 {
+  color: var(--ink);
+  font-size: 18px;
+  line-height: 1.25;
+}
+
+.description {
+  margin-top: var(--space-xs);
+  color: var(--muted);
+  line-height: 1.45;
+}
+
+.actions {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: var(--space-sm);
+}
+
+.body {
+  min-height: 0;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) auto;
+  flex: 1;
+}
+
+.content {
+  min-width: 0;
+  overflow: auto;
+  padding: var(--space-lg);
+}
+
+.inspector {
+  width: min(300px, 30vw);
+  overflow: auto;
+  padding: var(--space-lg);
+  border-left: 1px solid var(--border);
+  background: var(--surface-strong);
+}
+
+@media (max-width: 767px) {
+  .header {
+    flex-direction: column;
+  }
+
+  .body {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .inspector {
+    width: auto;
+    border-top: 1px solid var(--border);
+    border-left: 0;
+  }
+}
diff --git a/webui/src/components/layout/DetailPane.tsx b/webui/src/components/layout/DetailPane.tsx
new file mode 100644
index 00000000..915f5979
--- /dev/null
+++ b/webui/src/components/layout/DetailPane.tsx
@@ -0,0 +1,47 @@
+import { useId, type ReactNode } from 'react';
+import styles from './DetailPane.module.css';
+
+export type DetailPaneProps = {
+  title: ReactNode;
+  description?: ReactNode;
+  actions?: ReactNode;
+  inspector?: ReactNode;
+  inspectorLabel?: string;
+  children: ReactNode;
+  className?: string;
+};
+
+export default function DetailPane({
+  title,
+  description,
+  actions,
+  inspector,
+  inspectorLabel = 'Related details',
+  children,
+  className,
+}: DetailPaneProps) {
+  const titleId = useId();
+
+  return (
+    <section
+      className={[styles.pane, className].filter(Boolean).join(' ')}
+      aria-labelledby={titleId}
+    >
+      <header className={styles.header}>
+        <div className={styles.heading}>
+          <h1 id={titleId}>{title}</h1>
+          {description ? <div className={styles.description}>{description}</div> : null}
+        </div>
+        {actions ? <div className={styles.actions}>{actions}</div> : null}
+      </header>
+      <div className={styles.body}>
+        <div className={styles.content}>{children}</div>
+        {inspector ? (
+          <aside className={styles.inspector} aria-label={inspectorLabel}>
+            {inspector}
+          </aside>
+        ) : null}
+      </div>
+    </section>
+  );
+}
diff --git a/webui/src/components/layout/PageState.module.css b/webui/src/components/layout/PageState.module.css
new file mode 100644
index 00000000..e301b462
--- /dev/null
+++ b/webui/src/components/layout/PageState.module.css
@@ -0,0 +1,91 @@
+.content {
+  min-width: 0;
+  min-height: 0;
+}
+
+.state,
+.loading {
+  min-height: 220px;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-sm);
+  padding: var(--space-xl);
+  text-align: center;
+  color: var(--muted-strong);
+}
+
+.state h2 {
+  color: var(--ink);
+  font-size: 16px;
+}
+
+.state p {
+  max-width: 480px;
+  line-height: 1.5;
+}
+
+.state button,
+.warning button {
+  padding: 7px 12px;
+  border: 1px solid var(--border-strong);
+  border-radius: var(--rounded-md);
+  background: var(--surface);
+  color: var(--ink);
+  cursor: pointer;
+  font-weight: 700;
+}
+
+.error {
+  color: var(--ruby);
+}
+
+.warning {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-md);
+  margin-bottom: var(--space-md);
+  padding: 9px 12px;
+  border: 1px solid #f5c2c7;
+  border-radius: var(--rounded-md);
+  background: var(--ruby-soft);
+  color: var(--ruby);
+}
+
+.refreshing {
+  padding: 6px 10px;
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.skeleton,
+.skeletonShort {
+  width: min(520px, 100%);
+  height: 18px;
+  border-radius: var(--rounded-md);
+  background: linear-gradient(90deg, var(--surface-muted), var(--surface), var(--surface-muted));
+  background-size: 200% 100%;
+  animation: shimmer 1.5s ease-in-out infinite;
+}
+
+.skeletonShort {
+  width: min(340px, 70%);
+}
+
+@keyframes shimmer {
+  from {
+    background-position: 200% 0;
+  }
+  to {
+    background-position: -200% 0;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .skeleton,
+  .skeletonShort {
+    animation: none;
+  }
+}
diff --git a/webui/src/components/layout/PageState.tsx b/webui/src/components/layout/PageState.tsx
new file mode 100644
index 00000000..9edc14ec
--- /dev/null
+++ b/webui/src/components/layout/PageState.tsx
@@ -0,0 +1,83 @@
+import type { ReactNode } from 'react';
+import styles from './PageState.module.css';
+
+export type PageStateProps = {
+  loading?: boolean;
+  loadingLabel?: string;
+  error?: Error | null;
+  hasData?: boolean;
+  isEmpty?: boolean;
+  emptyTitle?: string;
+  emptyDescription?: string;
+  emptyAction?: ReactNode;
+  onRetry?: () => void;
+  children?: ReactNode;
+};
+
+export default function PageState({
+  loading = false,
+  loadingLabel = 'Loading',
+  error = null,
+  hasData = false,
+  isEmpty = false,
+  emptyTitle = 'Nothing here yet',
+  emptyDescription,
+  emptyAction,
+  onRetry,
+  children,
+}: PageStateProps) {
+  if (loading && !hasData) {
+    return (
+      <div className={styles.loading} role="status" aria-label={loadingLabel}>
+        <span className={styles.skeleton} />
+        <span className={styles.skeleton} />
+        <span className={styles.skeletonShort} />
+      </div>
+    );
+  }
+
+  if (error && !hasData) {
+    return (
+      <div className={`${styles.state} ${styles.error}`} role="alert">
+        <h2>Unable to load this content</h2>
+        <p>{error.message}</p>
+        {onRetry ? (
+          <button type="button" onClick={onRetry}>
+            Retry
+          </button>
+        ) : null}
+      </div>
+    );
+  }
+
+  if (isEmpty && !hasData) {
+    return (
+      <div className={styles.state}>
+        <h2>{emptyTitle}</h2>
+        {emptyDescription ? <p>{emptyDescription}</p> : null}
+        {emptyAction}
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.content}>
+      {error ? (
+        <div className={styles.warning} role="alert">
+          <span>{error.message}</span>
+          {onRetry ? (
+            <button type="button" onClick={onRetry}>
+              Retry
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+      {loading ? (
+        <div className={styles.refreshing} role="status">
+          {loadingLabel}
+        </div>
+      ) : null}
+      {children}
+    </div>
+  );
+}
diff --git a/webui/src/components/layout/ResourceList.module.css b/webui/src/components/layout/ResourceList.module.css
new file mode 100644
index 00000000..a6522b12
--- /dev/null
+++ b/webui/src/components/layout/ResourceList.module.css
@@ -0,0 +1,34 @@
+.list {
+  min-width: 0;
+  overflow: auto;
+  padding: var(--space-xs);
+  border: 1px solid var(--border);
+  border-radius: var(--rounded-lg);
+  background: var(--surface);
+}
+
+.list:focus-visible {
+  outline: none;
+  box-shadow: var(--ring);
+}
+
+.option {
+  padding: 10px 12px;
+  border-radius: var(--rounded-md);
+  color: var(--ink-soft);
+  cursor: pointer;
+  transition:
+    color var(--duration-fast) var(--ease),
+    background var(--duration-fast) var(--ease);
+}
+
+.option:hover {
+  background: var(--hover);
+  color: var(--ink);
+}
+
+.selected {
+  background: var(--surface-muted);
+  color: var(--ink);
+  box-shadow: inset 2px 0 0 var(--ink);
+}
diff --git a/webui/src/components/layout/ResourceList.tsx b/webui/src/components/layout/ResourceList.tsx
new file mode 100644
index 00000000..64b0c9ef
--- /dev/null
+++ b/webui/src/components/layout/ResourceList.tsx
@@ -0,0 +1,79 @@
+import { useId, type KeyboardEvent, type ReactNode } from 'react';
+import styles from './ResourceList.module.css';
+
+export type ResourceListProps<T> = {
+  items: readonly T[];
+  selectedId: string | null;
+  getId: (item: T) => string;
+  renderItem: (item: T) => ReactNode;
+  onSelect: (id: string) => void;
+  ariaLabel?: string;
+  className?: string;
+};
+
+export default function ResourceList<T>({
+  items,
+  selectedId,
+  getId,
+  renderItem,
+  onSelect,
+  ariaLabel = 'Resources',
+  className,
+}: ResourceListProps<T>) {
+  const listId = useId();
+  const selectedIndex = items.findIndex((item) => getId(item) === selectedId);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (items.length === 0) return;
+
+    let nextIndex: number | null = null;
+
+    switch (event.key) {
+      case 'ArrowDown':
+        nextIndex = selectedIndex < 0 ? 0 : Math.min(selectedIndex + 1, items.length - 1);
+        break;
+      case 'ArrowUp':
+        nextIndex = selectedIndex < 0 ? items.length - 1 : Math.max(selectedIndex - 1, 0);
+        break;
+      case 'Home':
+        nextIndex = 0;
+        break;
+      case 'End':
+        nextIndex = items.length - 1;
+        break;
+      default:
+        return;
+    }
+
+    event.preventDefault();
+    onSelect(getId(items[nextIndex]));
+  };
+
+  return (
+    <div
+      className={[styles.list, className].filter(Boolean).join(' ')}
+      role="listbox"
+      aria-label={ariaLabel}
+      aria-activedescendant={selectedIndex >= 0 ? `${listId}-option-${selectedIndex}` : undefined}
+      tabIndex={0}
+      onKeyDown={handleKeyDown}
+    >
+      {items.map((item, index) => {
+        const id = getId(item);
+        const selected = id === selectedId;
+        return (
+          <div
+            className={`${styles.option} ${selected ? styles.selected : ''}`}
+            id={`${listId}-option-${index}`}
+            key={id}
+            role="option"
+            aria-selected={selected}
+            onClick={() => onSelect(id)}
+          >
+            {renderItem(item)}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/webui/src/hooks/useResource.ts b/webui/src/hooks/useResource.ts
new file mode 100644
index 00000000..4c171d88
--- /dev/null
+++ b/webui/src/hooks/useResource.ts
@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useReducer, useRef, useState } from 'react';
+
+export type ResourceState<T> = {
+  status: 'loading' | 'ready' | 'error';
+  data: T | null;
+  error: Error | null;
+  retry(): void;
+};
+
+type ResourceSnapshot<T> = Omit<ResourceState<T>, 'retry'>;
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException
+    ? error.name === 'AbortError'
+    : error instanceof Error && error.name === 'AbortError';
+}
+
+export function useResource<T>(
+  key: string,
+  loader: (signal: AbortSignal) => Promise<T>,
+): ResourceState<T> {
+  const [snapshot, setSnapshot] = useState<ResourceSnapshot<T>>({
+    status: 'loading',
+    data: null,
+    error: null,
+  });
+  const [retryVersion, retry] = useReducer((version: number) => version + 1, 0);
+  const loaderRef = useRef(loader);
+  const previousKeyRef = useRef(key);
+  loaderRef.current = loader;
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const keyChanged = previousKeyRef.current !== key;
+    previousKeyRef.current = key;
+
+    setSnapshot((previous) => ({
+      status: 'loading',
+      data: keyChanged ? null : previous.data,
+      error: null,
+    }));
+
+    void (async () => {
+      try {
+        const data = await loaderRef.current(controller.signal);
+        if (!controller.signal.aborted) {
+          setSnapshot({ status: 'ready', data, error: null });
+        }
+      } catch (error) {
+        if (!controller.signal.aborted && !isAbortError(error)) {
+          setSnapshot((previous) => ({
+            status: 'error',
+            data: previous.data,
+            error: toError(error),
+          }));
+        }
+      }
+    })();
+
+    return () => controller.abort();
+  }, [key, retryVersion]);
+
+  const retryResource = useCallback(() => retry(), []);
+  return { ...snapshot, retry: retryResource };
+}

From 0e85b04dd16e09ab3be5b07c33c8feb01c5747f7 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 02:54:33 +0800
Subject: [PATCH 15/49] fix(webui): harden resource page primitives

---
 webui/src/__tests__/pages.test.tsx           | 73 ++++++++++++++++++++
 webui/src/components/layout/ResourceList.tsx | 19 ++++-
 webui/src/hooks/useResource.ts               | 18 ++++-
 3 files changed, 105 insertions(+), 5 deletions(-)

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 5d08beec..3776987a 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -1,3 +1,4 @@
+import { useState } from 'react';
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import DetailPane from '../components/layout/DetailPane';
@@ -24,11 +25,14 @@ function deferred<T>(): Deferred<T> {
 function ResourceHarness({
   resourceKey,
   loader,
+  onRender,
 }: {
   resourceKey: string;
   loader: (signal: AbortSignal) => Promise<string>;
+  onRender?: (key: string, data: string | null) => void;
 }) {
   const resource = useResource(resourceKey, loader);
+  onRender?.(resourceKey, resource.data);
   return (
     <div>
       <output aria-label="status">{resource.status}</output>
@@ -42,6 +46,24 @@ function ResourceHarness({
 }
 
 describe('useResource', () => {
+  it('does not expose data from the previous key during the new key render', async () => {
+    const renders: Array<{ key: string; data: string | null }> = [];
+    const loader = vi
+      .fn()
+      .mockResolvedValueOnce('first data')
+      .mockReturnValue(new Promise(() => {}));
+    const onRender = (key: string, data: string | null) => renders.push({ key, data });
+    const view = render(
+      <ResourceHarness resourceKey="first" loader={loader} onRender={onRender} />,
+    );
+
+    await waitFor(() => expect(screen.getByLabelText('data')).toHaveTextContent('first data'));
+    const renderCountBeforeKeyChange = renders.length;
+    view.rerender(<ResourceHarness resourceKey="second" loader={loader} onRender={onRender} />);
+
+    expect(renders[renderCountBeforeKeyChange]).toEqual({ key: 'second', data: null });
+  });
+
   it('aborts the previous request when the resource key changes', async () => {
     const first = deferred<string>();
     const second = deferred<string>();
@@ -128,6 +150,57 @@ describe('ResourceList', () => {
     { id: 'b', name: 'B' },
   ];
 
+  function SelectableList({ initialId = 'a' }: { initialId?: string }) {
+    const [selectedId, setSelectedId] = useState(initialId);
+    return (
+      <ResourceList
+        items={items}
+        selectedId={selectedId}
+        getId={(item) => item.id}
+        renderItem={(item) => item.name}
+        onSelect={setSelectedId}
+      />
+    );
+  }
+
+  it('scrolls keyboard-selected options into view', () => {
+    const scrollIntoView = vi.fn();
+    Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {
+      configurable: true,
+      value: scrollIntoView,
+    });
+
+    render(<SelectableList />);
+    scrollIntoView.mockClear();
+    fireEvent.keyDown(screen.getByRole('listbox'), { key: 'End' });
+
+    expect(screen.getByRole('option', { name: 'B' })).toHaveAttribute('aria-selected', 'true');
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: 'nearest' });
+
+    scrollIntoView.mockClear();
+    fireEvent.keyDown(screen.getByRole('listbox'), { key: 'Home' });
+    expect(screen.getByRole('option', { name: 'A' })).toHaveAttribute('aria-selected', 'true');
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: 'nearest' });
+
+    scrollIntoView.mockClear();
+    fireEvent.keyDown(screen.getByRole('listbox'), { key: 'ArrowDown' });
+    expect(screen.getByRole('option', { name: 'B' })).toHaveAttribute('aria-selected', 'true');
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: 'nearest' });
+
+    delete HTMLElement.prototype.scrollIntoView;
+  });
+
+  it('focuses the listbox when an option is clicked', () => {
+    render(<SelectableList />);
+
+    fireEvent.click(screen.getByRole('option', { name: 'B' }));
+
+    const listbox = screen.getByRole('listbox');
+    expect(listbox).toHaveFocus();
+    fireEvent.keyDown(listbox, { key: 'ArrowUp' });
+    expect(screen.getByRole('option', { name: 'A' })).toHaveAttribute('aria-selected', 'true');
+  });
+
   it('selects the next item with the keyboard and exposes the selected option', () => {
     const onSelect = vi.fn();
     render(
diff --git a/webui/src/components/layout/ResourceList.tsx b/webui/src/components/layout/ResourceList.tsx
index 64b0c9ef..be2a2c18 100644
--- a/webui/src/components/layout/ResourceList.tsx
+++ b/webui/src/components/layout/ResourceList.tsx
@@ -1,4 +1,4 @@
-import { useId, type KeyboardEvent, type ReactNode } from 'react';
+import { useEffect, useId, useRef, type KeyboardEvent, type ReactNode } from 'react';
 import styles from './ResourceList.module.css';
 
 export type ResourceListProps<T> = {
@@ -21,8 +21,16 @@ export default function ResourceList<T>({
   className,
 }: ResourceListProps<T>) {
   const listId = useId();
+  const listRef = useRef<HTMLDivElement>(null);
+  const optionRefs = useRef<Array<HTMLDivElement | null>>([]);
   const selectedIndex = items.findIndex((item) => getId(item) === selectedId);
 
+  useEffect(() => {
+    if (selectedIndex >= 0) {
+      optionRefs.current[selectedIndex]?.scrollIntoView?.({ block: 'nearest' });
+    }
+  }, [selectedIndex]);
+
   const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
     if (items.length === 0) return;
 
@@ -51,6 +59,7 @@ export default function ResourceList<T>({
 
   return (
     <div
+      ref={listRef}
       className={[styles.list, className].filter(Boolean).join(' ')}
       role="listbox"
       aria-label={ariaLabel}
@@ -63,12 +72,18 @@ export default function ResourceList<T>({
         const selected = id === selectedId;
         return (
           <div
+            ref={(node) => {
+              optionRefs.current[index] = node;
+            }}
             className={`${styles.option} ${selected ? styles.selected : ''}`}
             id={`${listId}-option-${index}`}
             key={id}
             role="option"
             aria-selected={selected}
-            onClick={() => onSelect(id)}
+            onClick={() => {
+              listRef.current?.focus();
+              onSelect(id);
+            }}
           >
             {renderItem(item)}
           </div>
diff --git a/webui/src/hooks/useResource.ts b/webui/src/hooks/useResource.ts
index 4c171d88..945b6620 100644
--- a/webui/src/hooks/useResource.ts
+++ b/webui/src/hooks/useResource.ts
@@ -7,7 +7,7 @@ export type ResourceState<T> = {
   retry(): void;
 };
 
-type ResourceSnapshot<T> = Omit<ResourceState<T>, 'retry'>;
+type ResourceSnapshot<T> = Omit<ResourceState<T>, 'retry'> & { key: string };
 
 function toError(error: unknown): Error {
   return error instanceof Error ? error : new Error(String(error));
@@ -24,6 +24,7 @@ export function useResource<T>(
   loader: (signal: AbortSignal) => Promise<T>,
 ): ResourceState<T> {
   const [snapshot, setSnapshot] = useState<ResourceSnapshot<T>>({
+    key,
     status: 'loading',
     data: null,
     error: null,
@@ -39,6 +40,7 @@ export function useResource<T>(
     previousKeyRef.current = key;
 
     setSnapshot((previous) => ({
+      key,
       status: 'loading',
       data: keyChanged ? null : previous.data,
       error: null,
@@ -48,11 +50,12 @@ export function useResource<T>(
       try {
         const data = await loaderRef.current(controller.signal);
         if (!controller.signal.aborted) {
-          setSnapshot({ status: 'ready', data, error: null });
+          setSnapshot({ key, status: 'ready', data, error: null });
         }
       } catch (error) {
         if (!controller.signal.aborted && !isAbortError(error)) {
           setSnapshot((previous) => ({
+            key,
             status: 'error',
             data: previous.data,
             error: toError(error),
@@ -65,5 +68,14 @@ export function useResource<T>(
   }, [key, retryVersion]);
 
   const retryResource = useCallback(() => retry(), []);
-  return { ...snapshot, retry: retryResource };
+  if (snapshot.key !== key) {
+    return { status: 'loading', data: null, error: null, retry: retryResource };
+  }
+
+  return {
+    status: snapshot.status,
+    data: snapshot.data,
+    error: snapshot.error,
+    retry: retryResource,
+  };
 }

From 836f9f3f40d001020ac01f565415e5ff39addd5e Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 02:59:09 +0800
Subject: [PATCH 16/49] docs: sequence desktop shell before pages

---
 .../plans/2026-06-19-windows-desktop-redesign.md            | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
index 0054ac00..38b40cce 100644
--- a/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
+++ b/docs/superpowers/plans/2026-06-19-windows-desktop-redesign.md
@@ -342,7 +342,7 @@ Run: `npm test -- --run src/__tests__/shell.test.tsx`
 
 Expected: FAIL because the desktop shell is missing.
 
-- [ ] **Step 3: Implement navigation metadata and lazy outlet**
+- [ ] **Step 3: Implement navigation metadata and shell composition**
 
 ```ts
 export const desktopPages = [
@@ -354,13 +354,13 @@ export const desktopPages = [
 ] as const;
 ```
 
-Use `<button>` navigation with `aria-current="page"` rather than fake URLs. Persist the selected page in `localStorage` only after validating it against `desktopPages`. Lazy-load every page component in `App.tsx`.
+Use `<button>` navigation with `aria-current="page"` rather than fake URLs. Persist the selected page in `localStorage` only after validating it against `desktopPages`. `DesktopShell` receives the existing phase content through `children`; Tasks 6-11 register each page component with `lazy()` when that real page is introduced, so this task never imports nonexistent modules or adds placeholder pages.
 
 - [ ] **Step 4: Run shell, reducer, and build checks**
 
 Run: `npm test -- --run src/__tests__/shell.test.tsx src/__tests__/AppState.test.ts && npm run build`
 
-Expected: PASS; build output contains separate page chunks.
+Expected: PASS; App renders the existing workbench inside the shell without importing nonexistent page modules.
 
 - [ ] **Step 5: Commit the desktop shell**
 

From 967164d7857256dce8ef5dbadc0ea149a0fcc357 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 03:08:47 +0800
Subject: [PATCH 17/49] feat(webui): add ten-page desktop shell

---
 webui/src/App.tsx                       |  30 ++--
 webui/src/AppState.tsx                  |  21 ++-
 webui/src/__tests__/shell.test.tsx      |  66 +++++++++
 webui/src/components/SettingsPage.tsx   |   2 +-
 webui/src/i18n.tsx                      |   8 +
 webui/src/shell/DesktopShell.module.css | 188 ++++++++++++++++++++++++
 webui/src/shell/DesktopShell.tsx        |  88 +++++++++++
 webui/src/shell/navigation.ts           |  47 ++++++
 8 files changed, 436 insertions(+), 14 deletions(-)
 create mode 100644 webui/src/__tests__/shell.test.tsx
 create mode 100644 webui/src/shell/DesktopShell.module.css
 create mode 100644 webui/src/shell/DesktopShell.tsx
 create mode 100644 webui/src/shell/navigation.ts

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index e02fbe1f..6717ef00 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useEffect, useState } from 'react';
+import { lazy, Suspense, useEffect, useState, type ReactNode } from 'react';
 import { ArrowLeft } from 'lucide-react';
 import { api } from './api/client';
 import styles from './App.module.css';
@@ -19,6 +19,7 @@ import WorldSidebar from './components/WorldSidebar';
 import DesktopBoot from './DesktopBoot';
 import { useSSE } from './hooks/useSSE';
 import { I18nProvider } from './i18n';
+import DesktopShell from './shell/DesktopShell';
 
 const HelpDrawer = lazy(() => import('./components/HelpDrawer'));
 const SetupWizard = lazy(() => import('./components/SetupWizard'));
@@ -219,9 +220,18 @@ function AppInner() {
 
   const connState = useSSE(sseUrl, dispatch, state.lastSeq);
 
+  const inDesktopShell = (children: ReactNode) => (
+    <DesktopShell
+      page={state.currentPage}
+      onNavigate={(page) => dispatch({ type: 'SET_PAGE', page })}
+    >
+      {children}
+    </DesktopShell>
+  );
+
   // Page-based rendering (overrides phase when navigating away from workbench)
   if (state.currentPage === 'settings') {
-    return <SettingsPage />;
+    return inDesktopShell(<SettingsPage />);
   }
 
   if (state.currentPage === 'editor' && state.activeEditorChapterId && state.worldId) {
@@ -230,7 +240,7 @@ function AppInner() {
         <div className={styles.editorHeader}>
           <button
             className={styles.editorBackBtn}
-            onClick={() => dispatch({ type: 'SET_PAGE', page: 'workbench' })}
+            onClick={() => dispatch({ type: 'SET_PAGE', page: 'overview' })}
           >
             <ArrowLeft size={15} aria-hidden="true" strokeWidth={2.3} />
             返回工作台
@@ -246,33 +256,33 @@ function AppInner() {
 
   // Phase-based rendering (workbench page)
   if (!bootstrapped || state.appPhase === 'loading') {
-    return <Skeleton />;
+    return inDesktopShell(<Skeleton />);
   }
 
   if (state.appPhase === 'no_world') {
-    return (
+    return inDesktopShell(
       <ToastProvider>
         <WorldOnboarding onOpenGuide={() => setHelpOpen(true)} />
         <Suspense>
           {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
         </Suspense>
-      </ToastProvider>
+      </ToastProvider>,
     );
   }
 
   if (state.appPhase === 'no_agent') {
-    return (
+    return inDesktopShell(
       <ToastProvider>
         <WorldDashboard onOpenGuide={() => setHelpOpen(true)} />
         <Suspense>
           {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
         </Suspense>
-      </ToastProvider>
+      </ToastProvider>,
     );
   }
 
   // appPhase === 'ready': three-column Workbench
-  return (
+  return inDesktopShell(
     <ToastProvider>
       <div className={styles.layout}>
         <ErrorBoundary>
@@ -353,7 +363,7 @@ function AppInner() {
           />
         )}
       </Suspense>
-    </ToastProvider>
+    </ToastProvider>,
   );
 }
 
diff --git a/webui/src/AppState.tsx b/webui/src/AppState.tsx
index b5f12d5a..e52ddf46 100644
--- a/webui/src/AppState.tsx
+++ b/webui/src/AppState.tsx
@@ -20,9 +20,21 @@ import type {
   WorldAgent,
   WorldSummary,
 } from './api/types';
+import { readStoredDesktopPage } from './shell/navigation';
 
 export type InspectorTab = 'story' | 'files' | 'agents' | 'run' | 'creation';
-export type AppPage = 'workbench' | 'settings' | 'editor';
+export type AppPage =
+  | 'overview'
+  | 'sessions'
+  | 'world'
+  | 'characters'
+  | 'chapters'
+  | 'scenes'
+  | 'foreshadowing'
+  | 'secrets'
+  | 'files'
+  | 'settings'
+  | 'editor';
 export type WorldbuildingStatus = 'idle' | 'loading' | 'ready' | 'error';
 
 export interface GeneratedFileEntry {
@@ -113,7 +125,7 @@ export interface AppState {
 
 export const initialState: AppState = {
   appPhase: 'loading',
-  currentPage: 'workbench',
+  currentPage: 'overview',
   activeEditorChapterId: null,
   activeEditorChapterTitle: '',
   agentId: null,
@@ -1203,7 +1215,10 @@ const AppContext = createContext<{
 } | null>(null);
 
 export function AppStateProvider({ children }: { children: ReactNode }) {
-  const [state, dispatch] = useReducer(reducer, initialState);
+  const [state, dispatch] = useReducer(reducer, initialState, (baseState) => ({
+    ...baseState,
+    currentPage: readStoredDesktopPage(),
+  }));
   return <AppContext.Provider value={{ state, dispatch }}>{children}</AppContext.Provider>;
 }
 
diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
new file mode 100644
index 00000000..5d1dee72
--- /dev/null
+++ b/webui/src/__tests__/shell.test.tsx
@@ -0,0 +1,66 @@
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { AppStateProvider } from '../AppState';
+import { I18nProvider } from '../i18n';
+import DesktopShell from '../shell/DesktopShell';
+import { desktopPages, readStoredDesktopPage, writeStoredDesktopPage } from '../shell/navigation';
+
+describe('desktop shell', () => {
+  beforeEach(() => window.localStorage.clear());
+
+  function renderShell(page: 'overview' | 'sessions', onNavigate = vi.fn()) {
+    return render(
+      <I18nProvider defaultLocale="zh">
+        <AppStateProvider>
+          <DesktopShell page={page} onNavigate={onNavigate}>
+            <div>Existing workbench</div>
+          </DesktopShell>
+        </AppStateProvider>
+      </I18nProvider>,
+    );
+  }
+
+  it('renders exactly ten bilingual navigation buttons and dispatches navigation', () => {
+    const dispatch = vi.fn();
+    renderShell('overview', (page) => dispatch({ type: 'SET_PAGE', page }));
+
+    const navigation = screen.getByRole('navigation', { name: '主导航' });
+    expect(within(navigation).getAllByRole('button')).toHaveLength(10);
+    expect(within(navigation).getByRole('button', { name: '概览' })).toBeInTheDocument();
+    expect(within(navigation).getByRole('button', { name: 'Sessions 会话' })).toBeInTheDocument();
+    expect(within(navigation).getByRole('button', { name: 'World 世界设定' })).toBeInTheDocument();
+
+    fireEvent.click(within(navigation).getByRole('button', { name: /角色/ }));
+    expect(dispatch).toHaveBeenCalledWith({ type: 'SET_PAGE', page: 'characters' });
+  });
+
+  it('marks the active page and preserves the existing workbench children', () => {
+    renderShell('sessions');
+
+    expect(screen.getByRole('button', { name: 'Sessions 会话' })).toHaveAttribute(
+      'aria-current',
+      'page',
+    );
+    expect(screen.getByText('Existing workbench')).toBeInTheDocument();
+  });
+
+  it('restores only persisted top-level pages', () => {
+    window.localStorage.setItem('merak.desktop.page', 'characters');
+    expect(readStoredDesktopPage()).toBe('characters');
+
+    window.localStorage.setItem('merak.desktop.page', 'editor');
+    expect(readStoredDesktopPage()).toBe('overview');
+
+    window.localStorage.setItem('merak.desktop.page', 'not-a-page');
+    expect(readStoredDesktopPage()).toBe('overview');
+  });
+
+  it('persists only validated top-level pages', () => {
+    writeStoredDesktopPage('files');
+    expect(window.localStorage.getItem('merak.desktop.page')).toBe('files');
+
+    writeStoredDesktopPage('editor');
+    expect(window.localStorage.getItem('merak.desktop.page')).toBe('files');
+    expect(desktopPages).toHaveLength(10);
+  });
+});
diff --git a/webui/src/components/SettingsPage.tsx b/webui/src/components/SettingsPage.tsx
index cf3b36c3..b77b65d3 100644
--- a/webui/src/components/SettingsPage.tsx
+++ b/webui/src/components/SettingsPage.tsx
@@ -185,7 +185,7 @@ export default function SettingsPage() {
       <div className={styles.header}>
         <button
           className={styles.backBtn}
-          onClick={() => dispatch({ type: 'SET_PAGE', page: 'workbench' })}
+          onClick={() => dispatch({ type: 'SET_PAGE', page: 'overview' })}
         >
           <ArrowLeft size={15} aria-hidden="true" strokeWidth={2.3} />
           返回工作台
diff --git a/webui/src/i18n.tsx b/webui/src/i18n.tsx
index 58cf3def..13e83035 100644
--- a/webui/src/i18n.tsx
+++ b/webui/src/i18n.tsx
@@ -6,6 +6,10 @@ export type Locale = 'zh' | 'en';
 type Dictionary = Record<string, string>;
 
 const zh: Dictionary = {
+  'shell.primaryNavigation': '主导航',
+  'shell.worldSelector': '选择世界',
+  'shell.noWorld': '未选择世界',
+  'shell.search': '搜索',
   'app.workbench': '创作工作台',
   'app.runtimeReady': '本地服务已连接',
   'app.connecting': '连接中',
@@ -251,6 +255,10 @@ const zh: Dictionary = {
 }
 
 const en: Dictionary = {
+  'shell.primaryNavigation': 'Primary navigation',
+  'shell.worldSelector': 'Select world',
+  'shell.noWorld': 'No world selected',
+  'shell.search': 'Search',
   'app.workbench': 'Workbench',
   'app.runtimeReady': 'Local service connected',
   'app.connecting': 'Connecting',
diff --git a/webui/src/shell/DesktopShell.module.css b/webui/src/shell/DesktopShell.module.css
new file mode 100644
index 00000000..0c8287ca
--- /dev/null
+++ b/webui/src/shell/DesktopShell.module.css
@@ -0,0 +1,188 @@
+.shell {
+  --shell-navy: #082a78;
+  display: grid;
+  grid-template-columns: 244px minmax(0, 1fr);
+  width: 100%;
+  height: 100vh;
+  overflow: hidden;
+  background: #f7f9fc;
+  color: #101828;
+}
+
+.sidebar {
+  display: flex;
+  min-height: 0;
+  flex-direction: column;
+  gap: 10px;
+  padding: 14px 14px 18px;
+  border-right: 1px solid #e2e8f0;
+  background: #fff;
+}
+
+.brand {
+  height: 54px;
+  display: flex;
+  align-items: center;
+  padding: 0 8px;
+}
+
+.brand img {
+  width: 122px;
+  height: auto;
+}
+
+.worldCard,
+.search,
+.worldSelector {
+  display: flex;
+  align-items: center;
+  gap: 9px;
+  border: 1px solid #dce3ed;
+  border-radius: 7px;
+  background: #fff;
+  color: #17213b;
+}
+
+.worldCard {
+  min-height: 48px;
+  padding: 0 12px;
+  font-weight: 700;
+}
+
+.worldCard span {
+  flex: 1;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.search {
+  min-height: 36px;
+  padding: 0 10px;
+  color: #667085;
+  font-size: 12px;
+}
+
+.search span {
+  flex: 1;
+}
+
+.search kbd {
+  padding: 2px 5px;
+  border: 1px solid #e3e8ef;
+  border-radius: 4px;
+  background: #f8fafc;
+  font: inherit;
+}
+
+.navigation {
+  display: flex;
+  min-height: 0;
+  flex: 1;
+  flex-direction: column;
+  gap: 3px;
+  padding-top: 1px;
+}
+
+.navButton {
+  display: flex;
+  width: 100%;
+  min-height: 34px;
+  align-items: center;
+  gap: 10px;
+  padding: 0 11px;
+  border: 0;
+  border-radius: 6px;
+  background: transparent;
+  color: #263653;
+  cursor: pointer;
+  text-align: left;
+  transition:
+    color 120ms ease,
+    background 120ms ease;
+}
+
+.navButton:hover {
+  background: #f1f5fb;
+}
+
+.navButton[aria-current='page'] {
+  background: var(--shell-navy);
+  color: #fff;
+  font-weight: 700;
+}
+
+.stage {
+  display: grid;
+  min-width: 0;
+  min-height: 0;
+  grid-template-rows: 66px minmax(0, 1fr);
+}
+
+.topbar {
+  display: flex;
+  align-items: center;
+  padding: 0 20px;
+  border-bottom: 1px solid #e2e8f0;
+  background: rgba(255, 255, 255, 0.96);
+}
+
+.worldSelector {
+  min-width: 190px;
+  height: 38px;
+  padding: 0 11px;
+}
+
+.worldSelector select {
+  min-width: 0;
+  flex: 1;
+  appearance: none;
+  border: 0;
+  outline: 0;
+  background: transparent;
+  color: inherit;
+  font: inherit;
+  font-weight: 650;
+}
+
+.content {
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+
+/* Legacy phase views previously owned the viewport; the shell now owns it. */
+.content.content > * {
+  position: relative;
+  inset: auto;
+  z-index: auto;
+  width: 100%;
+  height: 100%;
+  min-height: 0;
+}
+
+.srOnly {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+@media (max-width: 960px) {
+  .shell {
+    grid-template-columns: 202px minmax(0, 1fr);
+  }
+
+  .sidebar {
+    padding-inline: 10px;
+  }
+
+  .navButton {
+    font-size: 12px;
+  }
+}
diff --git a/webui/src/shell/DesktopShell.tsx b/webui/src/shell/DesktopShell.tsx
new file mode 100644
index 00000000..be742173
--- /dev/null
+++ b/webui/src/shell/DesktopShell.tsx
@@ -0,0 +1,88 @@
+import type { ReactNode } from 'react';
+import { ChevronDown, Globe2, Search } from 'lucide-react';
+import type { AppPage } from '../AppState';
+import { useAppState } from '../AppState';
+import merakLogo from '../assets/merak-logo.svg';
+import { useI18n } from '../i18n';
+import styles from './DesktopShell.module.css';
+import { desktopPages, writeStoredDesktopPage } from './navigation';
+
+interface DesktopShellProps {
+  page: AppPage;
+  onNavigate: (page: AppPage) => void;
+  children: ReactNode;
+}
+
+export default function DesktopShell({ page, onNavigate, children }: DesktopShellProps) {
+  const { state, dispatch } = useAppState();
+  const { t } = useI18n();
+  const selectedWorld = state.worlds.find((world) => world.id === state.worldId);
+  const worldName = selectedWorld?.name || t('shell.noWorld');
+
+  function navigate(nextPage: AppPage) {
+    writeStoredDesktopPage(nextPage);
+    onNavigate(nextPage);
+  }
+
+  return (
+    <div className={styles.shell}>
+      <aside className={styles.sidebar}>
+        <div className={styles.brand}>
+          <img src={merakLogo} alt="Merak" />
+        </div>
+
+        <div className={styles.worldCard}>
+          <Globe2 size={18} aria-hidden="true" />
+          <span>{worldName}</span>
+          <ChevronDown size={14} aria-hidden="true" />
+        </div>
+
+        <div className={styles.search} aria-hidden="true">
+          <Search size={15} />
+          <span>{t('shell.search')}</span>
+          <kbd>Ctrl K</kbd>
+        </div>
+
+        <nav className={styles.navigation} aria-label={t('shell.primaryNavigation')}>
+          {desktopPages.map(([pageId, label, Icon]) => (
+            <button
+              key={pageId}
+              type="button"
+              className={styles.navButton}
+              aria-current={page === pageId ? 'page' : undefined}
+              onClick={() => navigate(pageId)}
+            >
+              <Icon size={16} aria-hidden="true" strokeWidth={2} />
+              <span>{label}</span>
+            </button>
+          ))}
+        </nav>
+      </aside>
+
+      <div className={styles.stage}>
+        <header className={styles.topbar}>
+          <label className={styles.worldSelector}>
+            <Globe2 size={16} aria-hidden="true" />
+            <span className={styles.srOnly}>{t('shell.worldSelector')}</span>
+            <select
+              aria-label={t('shell.worldSelector')}
+              value={state.worldId ?? ''}
+              onChange={(event) =>
+                dispatch({ type: 'SET_WORLD', worldId: event.target.value || null })
+              }
+            >
+              <option value="">{t('shell.noWorld')}</option>
+              {state.worlds.map((world) => (
+                <option key={world.id} value={world.id}>
+                  {world.name || world.id}
+                </option>
+              ))}
+            </select>
+            <ChevronDown size={14} aria-hidden="true" />
+          </label>
+        </header>
+        <main className={styles.content}>{children}</main>
+      </div>
+    </div>
+  );
+}
diff --git a/webui/src/shell/navigation.ts b/webui/src/shell/navigation.ts
new file mode 100644
index 00000000..3f07b5f1
--- /dev/null
+++ b/webui/src/shell/navigation.ts
@@ -0,0 +1,47 @@
+import {
+  BookOpen,
+  Files,
+  Globe2,
+  KeyRound,
+  LayoutDashboard,
+  MessagesSquare,
+  PanelsTopLeft,
+  Settings,
+  Sparkles,
+  Users,
+} from 'lucide-react';
+import type { AppPage } from '../AppState';
+
+export const desktopPages = [
+  ['overview', '概览', LayoutDashboard],
+  ['sessions', 'Sessions 会话', MessagesSquare],
+  ['world', 'World 世界设定', Globe2],
+  ['characters', 'Characters 角色', Users],
+  ['chapters', 'Chapters 章节', BookOpen],
+  ['scenes', 'Scenes 场景', PanelsTopLeft],
+  ['foreshadowing', 'Foreshadowing 伏笔线索', Sparkles],
+  ['secrets', 'Secrets 秘密', KeyRound],
+  ['files', 'Files 资料库', Files],
+  ['settings', 'Settings 设置', Settings],
+] as const;
+
+export type DesktopPage = (typeof desktopPages)[number][0];
+
+const storageKey = 'merak.desktop.page';
+const desktopPageIds = new Set<string>(desktopPages.map(([page]) => page));
+
+export function isDesktopPage(page: unknown): page is DesktopPage {
+  return typeof page === 'string' && desktopPageIds.has(page);
+}
+
+export function readStoredDesktopPage(): DesktopPage {
+  if (typeof window === 'undefined') return 'overview';
+  const storedPage = window.localStorage.getItem(storageKey);
+  return isDesktopPage(storedPage) ? storedPage : 'overview';
+}
+
+export function writeStoredDesktopPage(page: AppPage) {
+  if (typeof window !== 'undefined' && isDesktopPage(page)) {
+    window.localStorage.setItem(storageKey, page);
+  }
+}

From aec7441982a358f88645d86543e6603c8e74654d Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 03:22:20 +0800
Subject: [PATCH 18/49] fix(webui): preserve shell overlays and page state

---
 webui/src/App.module.css                      |  16 +-
 webui/src/App.tsx                             | 195 +++++++++---------
 webui/src/AppState.tsx                        |  17 +-
 webui/src/__tests__/shell.test.tsx            | 114 +++++++++-
 webui/src/components/SettingsPage.module.css  |  32 ++-
 .../src/components/WorldDashboard.module.css  |  12 +-
 .../src/components/WorldOnboarding.module.css |  15 +-
 webui/src/shell/DesktopShell.module.css       |   9 +-
 webui/src/shell/DesktopShell.tsx              |  17 +-
 9 files changed, 293 insertions(+), 134 deletions(-)

diff --git a/webui/src/App.module.css b/webui/src/App.module.css
index 8fe2eb9c..dbbe064b 100644
--- a/webui/src/App.module.css
+++ b/webui/src/App.module.css
@@ -1,7 +1,7 @@
 .layout {
   position: relative;
   display: flex;
-  height: 100vh;
+  height: 100%;
   overflow: hidden;
   padding: 10px;
   gap: 10px;
@@ -154,7 +154,9 @@
   font-size: 13px;
   font-weight: 600;
   cursor: pointer;
-  transition: background 120ms ease, transform 120ms ease;
+  transition:
+    background 120ms ease,
+    transform 120ms ease;
 }
 
 .editorBackBtn:hover {
@@ -175,6 +177,12 @@
 }
 
 @keyframes pageIn {
-  from { opacity: 0; transform: translateY(8px); }
-  to { opacity: 1; transform: translateY(0); }
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
 }
diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index 6717ef00..f4069e34 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -220,10 +220,11 @@ function AppInner() {
 
   const connState = useSSE(sseUrl, dispatch, state.lastSeq);
 
-  const inDesktopShell = (children: ReactNode) => (
+  const inDesktopShell = (children: ReactNode, overlays?: ReactNode) => (
     <DesktopShell
       page={state.currentPage}
       onNavigate={(page) => dispatch({ type: 'SET_PAGE', page })}
+      overlays={overlays}
     >
       {children}
     </DesktopShell>
@@ -260,110 +261,120 @@ function AppInner() {
   }
 
   if (state.appPhase === 'no_world') {
-    return inDesktopShell(
+    return (
       <ToastProvider>
-        <WorldOnboarding onOpenGuide={() => setHelpOpen(true)} />
-        <Suspense>
-          {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
-        </Suspense>
-      </ToastProvider>,
+        {inDesktopShell(
+          <WorldOnboarding onOpenGuide={() => setHelpOpen(true)} />,
+          <Suspense>
+            {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
+          </Suspense>,
+        )}
+      </ToastProvider>
     );
   }
 
   if (state.appPhase === 'no_agent') {
-    return inDesktopShell(
+    return (
       <ToastProvider>
-        <WorldDashboard onOpenGuide={() => setHelpOpen(true)} />
-        <Suspense>
-          {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
-        </Suspense>
-      </ToastProvider>,
+        {inDesktopShell(
+          <WorldDashboard onOpenGuide={() => setHelpOpen(true)} />,
+          <Suspense>
+            {helpOpen && <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />}
+          </Suspense>,
+        )}
+      </ToastProvider>
     );
   }
 
   // appPhase === 'ready': three-column Workbench
-  return inDesktopShell(
+  return (
     <ToastProvider>
-      <div className={styles.layout}>
-        <ErrorBoundary>
-          <WorldSidebar open={sidebarOpen} onClose={() => setSidebarOpen(false)} />
-        </ErrorBoundary>
-        <ErrorBoundary>
-          <div className={styles.workspace}>
-            <ConnectionBanner state={connState} />
-            <MainPanel
-              onToggleSidebar={() => setSidebarOpen((prev) => !prev)}
-              onToggleInspector={() => setInspectorOpen((prev) => !prev)}
-              onOpenGuide={() => setHelpOpen(true)}
-              sidebarOpen={sidebarOpen}
-              inspectorOpen={inspectorOpen}
-              connectionState={connState}
+      {inDesktopShell(
+        <div className={styles.layout}>
+          <ErrorBoundary>
+            <WorldSidebar open={sidebarOpen} onClose={() => setSidebarOpen(false)} />
+          </ErrorBoundary>
+          <ErrorBoundary>
+            <div className={styles.workspace}>
+              <ConnectionBanner state={connState} />
+              <MainPanel
+                onToggleSidebar={() => setSidebarOpen((prev) => !prev)}
+                onToggleInspector={() => setInspectorOpen((prev) => !prev)}
+                onOpenGuide={() => setHelpOpen(true)}
+                sidebarOpen={sidebarOpen}
+                inspectorOpen={inspectorOpen}
+                connectionState={connState}
+              />
+            </div>
+          </ErrorBoundary>
+          <ErrorBoundary>
+            <InspectorPanel open={inspectorOpen} onClose={() => setInspectorOpen(false)} />
+          </ErrorBoundary>
+        </div>,
+        <>
+          <Suspense>
+            <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />
+          </Suspense>
+
+          {/* Setup Wizard — shown when LLM is not configured */}
+          <Suspense>
+            {state.showSetupWizard && (
+              <SetupWizard
+                onComplete={() => dispatch({ type: 'SET_LLM_CONFIGURED', configured: true })}
+              />
+            )}
+          </Suspense>
+
+          {/* Chapter Review Banner — shown after chapter completion */}
+          <Suspense>
+            {state.chapterReview && state.worldId && (
+              <ChapterReviewBanner
+                worldId={state.worldId}
+                chapterId={state.chapterReview.chapter_id}
+                chapterTitle={state.chapterReview.title}
+                onNewChapter={() => {
+                  dispatch({ type: 'SET_CHAPTER_REVIEW', review: null });
+                  if (state.sessionId) {
+                    api
+                      .startRun(state.sessionId, '开始写下一章', state.selectedModel)
+                      .catch(() => {});
+                  }
+                }}
+                onRevise={() => {
+                  dispatch({ type: 'SET_CHAPTER_REVIEW', review: null });
+                }}
+                onExport={() => dispatch({ type: 'SET_SHOW_EXPORT_DIALOG', show: true })}
+                onClose={() => dispatch({ type: 'SET_CHAPTER_REVIEW', review: null })}
+              />
+            )}
+          </Suspense>
+
+          {state.pendingAsk && (
+            <AskUserPrompt
+              request={state.pendingAsk}
+              onResolved={(callId) => dispatch({ type: 'RESOLVE_ASK', callId })}
             />
-          </div>
-        </ErrorBoundary>
-        <Suspense>
-          <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />
-        </Suspense>
-        <ErrorBoundary>
-          <InspectorPanel open={inspectorOpen} onClose={() => setInspectorOpen(false)} />
-        </ErrorBoundary>
-      </div>
-
-      {/* Setup Wizard — shown when LLM is not configured */}
-      <Suspense>
-        {state.showSetupWizard && (
-          <SetupWizard
-            onComplete={() => dispatch({ type: 'SET_LLM_CONFIGURED', configured: true })}
-          />
-        )}
-      </Suspense>
-
-      {/* Chapter Review Banner — shown after chapter completion */}
-      <Suspense>
-        {state.chapterReview && state.worldId && (
-          <ChapterReviewBanner
-            worldId={state.worldId}
-            chapterId={state.chapterReview.chapter_id}
-            chapterTitle={state.chapterReview.title}
-            onNewChapter={() => {
-              dispatch({ type: 'SET_CHAPTER_REVIEW', review: null });
-              if (state.sessionId) {
-                api.startRun(state.sessionId, '开始写下一章', state.selectedModel).catch(() => {});
-              }
-            }}
-            onRevise={() => {
-              dispatch({ type: 'SET_CHAPTER_REVIEW', review: null });
-            }}
-            onExport={() => dispatch({ type: 'SET_SHOW_EXPORT_DIALOG', show: true })}
-            onClose={() => dispatch({ type: 'SET_CHAPTER_REVIEW', review: null })}
-          />
-        )}
-      </Suspense>
-
-      {state.pendingAsk && (
-        <AskUserPrompt
-          request={state.pendingAsk}
-          onResolved={(callId) => dispatch({ type: 'RESOLVE_ASK', callId })}
-        />
-      )}
-      {state.pendingCreation && (
-        <CreationRequestDialog
-          request={state.pendingCreation}
-          onResolved={(creationId) => dispatch({ type: 'RESOLVE_CREATION', creationId })}
-        />
+          )}
+          {state.pendingCreation && (
+            <CreationRequestDialog
+              request={state.pendingCreation}
+              onResolved={(creationId) => dispatch({ type: 'RESOLVE_CREATION', creationId })}
+            />
+          )}
+
+          {/* Export Dialog */}
+          <Suspense>
+            {state.showExportDialog && state.worldId && (
+              <ExportDialog
+                worldId={state.worldId}
+                chapters={[] /* TODO: populate from full chapter list when available in state */}
+                onClose={() => dispatch({ type: 'SET_SHOW_EXPORT_DIALOG', show: false })}
+              />
+            )}
+          </Suspense>
+        </>,
       )}
-
-      {/* Export Dialog */}
-      <Suspense>
-        {state.showExportDialog && state.worldId && (
-          <ExportDialog
-            worldId={state.worldId}
-            chapters={[] /* TODO: populate from full chapter list when available in state */}
-            onClose={() => dispatch({ type: 'SET_SHOW_EXPORT_DIALOG', show: false })}
-          />
-        )}
-      </Suspense>
-    </ToastProvider>,
+    </ToastProvider>
   );
 }
 
diff --git a/webui/src/AppState.tsx b/webui/src/AppState.tsx
index e52ddf46..01eba17c 100644
--- a/webui/src/AppState.tsx
+++ b/webui/src/AppState.tsx
@@ -1,4 +1,11 @@
-import { createContext, useContext, useReducer, type Dispatch, type ReactNode } from 'react';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useReducer,
+  type Dispatch,
+  type ReactNode,
+} from 'react';
 import type {
   ChapterReviewItem,
   ConditionState,
@@ -20,7 +27,7 @@ import type {
   WorldAgent,
   WorldSummary,
 } from './api/types';
-import { readStoredDesktopPage } from './shell/navigation';
+import { readStoredDesktopPage, writeStoredDesktopPage } from './shell/navigation';
 
 export type InspectorTab = 'story' | 'files' | 'agents' | 'run' | 'creation';
 export type AppPage =
@@ -1215,10 +1222,14 @@ const AppContext = createContext<{
 } | null>(null);
 
 export function AppStateProvider({ children }: { children: ReactNode }) {
-  const [state, dispatch] = useReducer(reducer, initialState, (baseState) => ({
+  const [state, baseDispatch] = useReducer(reducer, initialState, (baseState) => ({
     ...baseState,
     currentPage: readStoredDesktopPage(),
   }));
+  const dispatch = useCallback<Dispatch<Action>>((action) => {
+    if (action.type === 'SET_PAGE') writeStoredDesktopPage(action.page);
+    baseDispatch(action);
+  }, []);
   return <AppContext.Provider value={{ state, dispatch }}>{children}</AppContext.Provider>;
 }
 
diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index 5d1dee72..2feba83b 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -1,10 +1,61 @@
+import { readFileSync } from 'node:fs';
+import type { ReactNode } from 'react';
 import { fireEvent, render, screen, within } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { AppStateProvider } from '../AppState';
+import { AppStateProvider, useAppState } from '../AppState';
 import { I18nProvider } from '../i18n';
 import DesktopShell from '../shell/DesktopShell';
 import { desktopPages, readStoredDesktopPage, writeStoredDesktopPage } from '../shell/navigation';
 
+vi.mock('../DesktopBoot', () => ({
+  default: ({ children }: { children: ReactNode }) => children,
+}));
+vi.mock('../hooks/useSSE', () => ({ useSSE: () => 'connected' }));
+vi.mock('../components/WorldSidebar', () => ({ default: () => <aside>Workbench sidebar</aside> }));
+vi.mock('../components/MainPanel', () => ({ default: () => <div>Workbench main</div> }));
+vi.mock('../components/InspectorPanel', () => ({ default: () => <aside>Inspector</aside> }));
+vi.mock('../api/client', () => ({
+  api: {
+    getConfig: vi.fn().mockResolvedValue({ api_key_masked: '' }),
+    metadata: vi.fn().mockResolvedValue({
+      provider: 'openai',
+      model: 'gpt-4o',
+      models: [],
+      permission_mode: 'default',
+      memory: { enabled: false },
+      tools: [],
+      mcp_servers: [],
+      agents: [],
+      delegation_patterns: [],
+    }),
+    listWorlds: vi.fn().mockResolvedValue({
+      worlds: [{ id: 'world-1', name: 'Test World', description: '', created_at: '' }],
+    }),
+    listSessions: vi.fn().mockResolvedValue({
+      sessions: [
+        {
+          id: 'session-1',
+          title: 'Test',
+          world_id: 'world-1',
+          agent_id: 'agent-1',
+          last_seq: 0,
+          created_at: '',
+          updated_at: '',
+          archived_at: null,
+        },
+      ],
+    }),
+    capabilities: vi.fn().mockResolvedValue({ capabilities: {}, fallback: false }),
+    getPreferences: vi.fn().mockResolvedValue(null),
+    getStoryOverview: vi.fn().mockResolvedValue({ overview: null, fallback: false }),
+    listAgents: vi.fn().mockResolvedValue({ agents: [] }),
+    listForeshadowing: vi.fn().mockResolvedValue({ items: [] }),
+    listSecrets: vi.fn().mockResolvedValue({ items: [] }),
+    getWorldTime: vi.fn().mockResolvedValue({}),
+    sseUrl: vi.fn().mockReturnValue(null),
+  },
+}));
+
 describe('desktop shell', () => {
   beforeEach(() => window.localStorage.clear());
 
@@ -63,4 +114,65 @@ describe('desktop shell', () => {
     expect(window.localStorage.getItem('merak.desktop.page')).toBe('files');
     expect(desktopPages).toHaveLength(10);
   });
+
+  it('keeps global overlays outside the constrained page-content outlet', () => {
+    render(
+      <I18nProvider defaultLocale="zh">
+        <AppStateProvider>
+          <DesktopShell
+            page="overview"
+            onNavigate={vi.fn()}
+            overlays={<div data-testid="global-overlay">Overlay</div>}
+          >
+            <div data-testid="page-content">Workbench</div>
+          </DesktopShell>
+        </AppStateProvider>
+      </I18nProvider>,
+    );
+
+    const main = screen.getByRole('main');
+    expect(within(main).getByTestId('page-content')).toBeInTheDocument();
+    expect(within(main).queryByTestId('global-overlay')).toBeNull();
+    expect(screen.getByTestId('global-overlay')).toBeInTheDocument();
+  });
+
+  it('persists programmatic settings and overview transitions but never editor', () => {
+    function PageDispatchHarness() {
+      const { dispatch } = useAppState();
+      return (
+        <>
+          <button onClick={() => dispatch({ type: 'SET_PAGE', page: 'settings' })}>Settings</button>
+          <button onClick={() => dispatch({ type: 'SET_PAGE', page: 'overview' })}>Overview</button>
+          <button onClick={() => dispatch({ type: 'SET_PAGE', page: 'editor' })}>Editor</button>
+        </>
+      );
+    }
+
+    render(
+      <AppStateProvider>
+        <PageDispatchHarness />
+      </AppStateProvider>,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: 'Settings' }));
+    expect(window.localStorage.getItem('merak.desktop.page')).toBe('settings');
+    fireEvent.click(screen.getByRole('button', { name: 'Overview' }));
+    expect(window.localStorage.getItem('merak.desktop.page')).toBe('overview');
+    fireEvent.click(screen.getByRole('button', { name: 'Editor' }));
+    expect(window.localStorage.getItem('merak.desktop.page')).toBe('overview');
+  });
+
+  it('keeps all navigation buttons reachable in short windows', () => {
+    const css = readFileSync('src/shell/DesktopShell.module.css', 'utf8');
+    expect(css).toMatch(/\.navigation\s*\{[^}]*overflow-y:\s*auto/s);
+  });
+
+  it('mounts App global dialogs outside the constrained page outlet', async () => {
+    const { default: App } = await import('../App');
+    render(<App />);
+
+    const dialog = await screen.findByRole('dialog', { name: '初始化设置' });
+    expect(within(screen.getByRole('main')).queryByRole('dialog')).toBeNull();
+    expect(dialog).toBeInTheDocument();
+  });
 });
diff --git a/webui/src/components/SettingsPage.module.css b/webui/src/components/SettingsPage.module.css
index db1b3aae..6e93b6af 100644
--- a/webui/src/components/SettingsPage.module.css
+++ b/webui/src/components/SettingsPage.module.css
@@ -1,7 +1,7 @@
 .page {
-  position: fixed;
-  inset: 0;
-  z-index: 100;
+  position: relative;
+  width: 100%;
+  height: 100%;
   background: var(--page);
   display: flex;
   flex-direction: column;
@@ -9,8 +9,14 @@
 }
 
 @keyframes pageIn {
-  from { opacity: 0; transform: translateY(8px); }
-  to { opacity: 1; transform: translateY(0); }
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
 }
 
 .header {
@@ -34,7 +40,9 @@
   font-size: 13px;
   font-weight: 600;
   cursor: pointer;
-  transition: background 120ms ease, transform 120ms ease;
+  transition:
+    background 120ms ease,
+    transform 120ms ease;
 }
 
 .backBtn:hover {
@@ -93,7 +101,9 @@
   color: var(--ink);
   width: 100%;
   box-sizing: border-box;
-  transition: border-color 120ms ease, box-shadow 120ms ease;
+  transition:
+    border-color 120ms ease,
+    box-shadow 120ms ease;
 }
 
 .input:focus,
@@ -147,7 +157,7 @@
   flex-shrink: 0;
 }
 
-.toggleSwitch[aria-checked="true"] {
+.toggleSwitch[aria-checked='true'] {
   background: var(--ink);
 }
 
@@ -162,7 +172,7 @@
   transition: transform 150ms var(--ease-spring);
 }
 
-.toggleSwitch[aria-checked="true"] .toggleKnob {
+.toggleSwitch[aria-checked='true'] .toggleKnob {
   transform: translateX(18px);
 }
 
@@ -186,7 +196,9 @@
   font-size: 13px;
   font-weight: 600;
   cursor: pointer;
-  transition: background 120ms ease, transform 120ms ease;
+  transition:
+    background 120ms ease,
+    transform 120ms ease;
 }
 
 .btn:hover:not(:disabled) {
diff --git a/webui/src/components/WorldDashboard.module.css b/webui/src/components/WorldDashboard.module.css
index 95678ded..ccc39959 100644
--- a/webui/src/components/WorldDashboard.module.css
+++ b/webui/src/components/WorldDashboard.module.css
@@ -1,9 +1,8 @@
 .dashboard {
-  min-height: 100vh;
+  min-height: 100%;
   padding: 28px;
   background:
-    linear-gradient(180deg, rgba(255, 255, 255, 0.72), rgba(247, 247, 245, 0.95)),
-    var(--color-bg);
+    linear-gradient(180deg, rgba(255, 255, 255, 0.72), rgba(247, 247, 245, 0.95)), var(--color-bg);
   overflow: auto;
 }
 
@@ -279,7 +278,12 @@
   content: '';
   position: absolute;
   inset: 0;
-  background: linear-gradient(105deg, transparent 14%, rgba(255, 255, 255, 0.72) 44%, transparent 68%);
+  background: linear-gradient(
+    105deg,
+    transparent 14%,
+    rgba(255, 255, 255, 0.72) 44%,
+    transparent 68%
+  );
   opacity: 0;
   transform: translateX(-42%);
   transition:
diff --git a/webui/src/components/WorldOnboarding.module.css b/webui/src/components/WorldOnboarding.module.css
index ffadcf01..731cc028 100644
--- a/webui/src/components/WorldOnboarding.module.css
+++ b/webui/src/components/WorldOnboarding.module.css
@@ -1,5 +1,5 @@
 .onboarding {
-  min-height: 100vh;
+  min-height: 100%;
   display: grid;
   place-items: center;
   padding: 42px;
@@ -8,8 +8,7 @@
   background:
     linear-gradient(135deg, rgba(255, 255, 255, 0.92), rgba(247, 247, 245, 0.94)),
     radial-gradient(circle at 18% 18%, rgba(15, 118, 110, 0.09), transparent 26%),
-    radial-gradient(circle at 82% 76%, rgba(183, 121, 31, 0.1), transparent 24%),
-    var(--color-bg);
+    radial-gradient(circle at 82% 76%, rgba(183, 121, 31, 0.1), transparent 24%), var(--color-bg);
 }
 
 .ambient {
@@ -197,8 +196,7 @@
   border: 1px solid var(--color-border);
   border-radius: 8px;
   background:
-    linear-gradient(135deg, rgba(255, 255, 255, 0.96), rgba(248, 249, 247, 0.96)),
-    var(--surface);
+    linear-gradient(135deg, rgba(255, 255, 255, 0.96), rgba(248, 249, 247, 0.96)), var(--surface);
   color: var(--color-text-primary);
   cursor: pointer;
   padding: 12px;
@@ -224,7 +222,12 @@
   content: '';
   position: absolute;
   inset: 0;
-  background: linear-gradient(110deg, transparent 20%, rgba(255, 255, 255, 0.62) 46%, transparent 68%);
+  background: linear-gradient(
+    110deg,
+    transparent 20%,
+    rgba(255, 255, 255, 0.62) 46%,
+    transparent 68%
+  );
   opacity: 0;
   transform: translateX(-38%);
   transition:
diff --git a/webui/src/shell/DesktopShell.module.css b/webui/src/shell/DesktopShell.module.css
index 0c8287ca..aa7884ee 100644
--- a/webui/src/shell/DesktopShell.module.css
+++ b/webui/src/shell/DesktopShell.module.css
@@ -82,6 +82,8 @@
   flex-direction: column;
   gap: 3px;
   padding-top: 1px;
+  overflow-y: auto;
+  overscroll-behavior: contain;
 }
 
 .navButton {
@@ -151,14 +153,11 @@
   overflow: hidden;
 }
 
-/* Legacy phase views previously owned the viewport; the shell now owns it. */
-.content.content > * {
-  position: relative;
-  inset: auto;
-  z-index: auto;
+.pageContent {
   width: 100%;
   height: 100%;
   min-height: 0;
+  overflow: hidden;
 }
 
 .srOnly {
diff --git a/webui/src/shell/DesktopShell.tsx b/webui/src/shell/DesktopShell.tsx
index be742173..6cf364ec 100644
--- a/webui/src/shell/DesktopShell.tsx
+++ b/webui/src/shell/DesktopShell.tsx
@@ -5,25 +5,21 @@ import { useAppState } from '../AppState';
 import merakLogo from '../assets/merak-logo.svg';
 import { useI18n } from '../i18n';
 import styles from './DesktopShell.module.css';
-import { desktopPages, writeStoredDesktopPage } from './navigation';
+import { desktopPages } from './navigation';
 
 interface DesktopShellProps {
   page: AppPage;
   onNavigate: (page: AppPage) => void;
   children: ReactNode;
+  overlays?: ReactNode;
 }
 
-export default function DesktopShell({ page, onNavigate, children }: DesktopShellProps) {
+export default function DesktopShell({ page, onNavigate, children, overlays }: DesktopShellProps) {
   const { state, dispatch } = useAppState();
   const { t } = useI18n();
   const selectedWorld = state.worlds.find((world) => world.id === state.worldId);
   const worldName = selectedWorld?.name || t('shell.noWorld');
 
-  function navigate(nextPage: AppPage) {
-    writeStoredDesktopPage(nextPage);
-    onNavigate(nextPage);
-  }
-
   return (
     <div className={styles.shell}>
       <aside className={styles.sidebar}>
@@ -50,7 +46,7 @@ export default function DesktopShell({ page, onNavigate, children }: DesktopShel
               type="button"
               className={styles.navButton}
               aria-current={page === pageId ? 'page' : undefined}
-              onClick={() => navigate(pageId)}
+              onClick={() => onNavigate(pageId)}
             >
               <Icon size={16} aria-hidden="true" strokeWidth={2} />
               <span>{label}</span>
@@ -81,8 +77,11 @@ export default function DesktopShell({ page, onNavigate, children }: DesktopShel
             <ChevronDown size={14} aria-hidden="true" />
           </label>
         </header>
-        <main className={styles.content}>{children}</main>
+        <main className={styles.content}>
+          <div className={styles.pageContent}>{children}</div>
+        </main>
       </div>
+      {overlays}
     </div>
   );
 }

From f6f51fd4b80a16385c530c89a6807e0cb7be83b5 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 03:26:49 +0800
Subject: [PATCH 19/49] fix(webui): keep world dashboard scrollable

---
 webui/src/__tests__/shell.test.tsx             | 9 +++++++++
 webui/src/components/WorldDashboard.module.css | 3 ++-
 2 files changed, 11 insertions(+), 1 deletion(-)

diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index 2feba83b..cd127326 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -167,6 +167,15 @@ describe('desktop shell', () => {
     expect(css).toMatch(/\.navigation\s*\{[^}]*overflow-y:\s*auto/s);
   });
 
+  it('gives the world dashboard a definite scroll-container height', () => {
+    const css = readFileSync('src/components/WorldDashboard.module.css', 'utf8');
+    const dashboardRule = css.match(/\.dashboard\s*\{([^}]*)\}/s)?.[1] ?? '';
+
+    expect(dashboardRule).toMatch(/^\s*height:\s*100%/m);
+    expect(dashboardRule).toMatch(/^\s*min-height:\s*0/m);
+    expect(dashboardRule).toMatch(/^\s*overflow:\s*auto/m);
+  });
+
   it('mounts App global dialogs outside the constrained page outlet', async () => {
     const { default: App } = await import('../App');
     render(<App />);
diff --git a/webui/src/components/WorldDashboard.module.css b/webui/src/components/WorldDashboard.module.css
index ccc39959..8e07fffc 100644
--- a/webui/src/components/WorldDashboard.module.css
+++ b/webui/src/components/WorldDashboard.module.css
@@ -1,5 +1,6 @@
 .dashboard {
-  min-height: 100%;
+  height: 100%;
+  min-height: 0;
   padding: 28px;
   background:
     linear-gradient(180deg, rgba(255, 255, 255, 0.72), rgba(247, 247, 245, 0.95)), var(--color-bg);

From 25f3499e8c60ffefcdba37a7f88f95077aaf0ceb Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 03:37:04 +0800
Subject: [PATCH 20/49] feat(webui): add real-data world overview

---
 webui/src/App.tsx                       |  13 ++
 webui/src/__tests__/pages.test.tsx      | 145 +++++++++++++
 webui/src/pages/OverviewPage.module.css | 236 ++++++++++++++++++++
 webui/src/pages/OverviewPage.tsx        | 275 ++++++++++++++++++++++++
 webui/src/pages/selectors.ts            |  65 ++++++
 5 files changed, 734 insertions(+)
 create mode 100644 webui/src/pages/OverviewPage.module.css
 create mode 100644 webui/src/pages/OverviewPage.tsx
 create mode 100644 webui/src/pages/selectors.ts

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index f4069e34..3d253933 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -25,6 +25,7 @@ const HelpDrawer = lazy(() => import('./components/HelpDrawer'));
 const SetupWizard = lazy(() => import('./components/SetupWizard'));
 const ChapterReviewBanner = lazy(() => import('./components/ChapterReviewBanner'));
 const ExportDialog = lazy(() => import('./components/ExportDialog'));
+const OverviewPage = lazy(() => import('./pages/OverviewPage'));
 
 export function shouldReportWorldbuildingPartialFailure(
   overviewLoaded: boolean,
@@ -273,6 +274,18 @@ function AppInner() {
     );
   }
 
+  if (state.currentPage === 'overview' && state.worldId) {
+    return inDesktopShell(
+      <Suspense fallback={<Skeleton />}>
+        <OverviewPage
+          worldId={state.worldId}
+          sessions={state.sessions}
+          onNavigate={(page) => dispatch({ type: 'SET_PAGE', page })}
+        />
+      </Suspense>,
+    );
+  }
+
   if (state.appPhase === 'no_agent') {
     return (
       <ToastProvider>
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 3776987a..bac69f81 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -1,10 +1,28 @@
 import { useState } from 'react';
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
+import { api } from '../api/client';
+import { worldbuildingApi } from '../api/worldbuilding';
 import DetailPane from '../components/layout/DetailPane';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
 import { useResource } from '../hooks/useResource';
+import OverviewPage from '../pages/OverviewPage';
+import { selectWorldMetrics } from '../pages/selectors';
+
+vi.mock('../api/client', () => ({
+  api: {
+    listAgents: vi.fn(),
+    listChapters: vi.fn(),
+    listScenes: vi.fn(),
+    listWorkspaceFiles: vi.fn(),
+    getStoryOverview: vi.fn(),
+  },
+}));
+
+vi.mock('../api/worldbuilding', () => ({
+  worldbuildingApi: { getDashboard: vi.fn() },
+}));
 
 type Deferred<T> = {
   promise: Promise<T>;
@@ -260,3 +278,130 @@ describe('DetailPane', () => {
     expect(screen.getByRole('complementary')).toHaveTextContent('Related chapters');
   });
 });
+
+describe('Overview selectors', () => {
+  it('derives counts from real response-shaped resource fixtures', () => {
+    expect(
+      selectWorldMetrics({
+        agents: [{ id: 'a' }],
+        chapters: [{ id: 'c', status: 'completed' }],
+        scenes: [],
+        files: [],
+        overview: null,
+        dashboard: null,
+      }),
+    ).toMatchObject({ characterCount: 1, chapterCount: 1, completedChapterCount: 1 });
+  });
+
+  it('uses dashboard aggregates when available and derives missing values', () => {
+    expect(
+      selectWorldMetrics({
+        agents: [{ id: 'a' }],
+        chapters: [{ id: 'c', status: 'drafting' }],
+        scenes: [{ id: 's', status: 'completed' }],
+        files: [{ id: 'f' }],
+        overview: null,
+        dashboard: {
+          agents: { total: 4 },
+          chapters: { total: 3, completed: 2 },
+          progress: { chapter_completion_pct: 67 },
+        },
+      }),
+    ).toMatchObject({
+      characterCount: 4,
+      chapterCount: 3,
+      completedChapterCount: 2,
+      sceneCount: 1,
+      fileCount: 1,
+      chapterCompletionPercent: 67,
+    });
+  });
+});
+
+describe('Overview page', () => {
+  const navigate = vi.fn();
+
+  function mockResources({ dashboardFails = false, empty = false } = {}) {
+    vi.mocked(api.listAgents).mockResolvedValue({
+      ok: true,
+      agents: empty ? [] : [{ id: 'a', name: 'Lin', display_name: 'Lin', kind: 'character' }],
+    });
+    vi.mocked(api.listChapters).mockResolvedValue({
+      ok: true,
+      chapters: empty
+        ? []
+        : [
+            {
+              id: 'c',
+              title: 'The First Light',
+              number: 1,
+              status: 'drafting',
+              scene_count: 1,
+              updated_at: '2026-06-18T12:00:00Z',
+            },
+          ],
+    });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({ ok: true, root: '', files: [] });
+    vi.mocked(api.getStoryOverview).mockResolvedValue({
+      ok: true,
+      overview: { agents: [], foreshadowing: [], secrets: [], world_time: null },
+    });
+    const dashboard = {
+      agents: { total: 1 },
+      chapters: { total: 1, completed: 0 },
+      progress: { chapter_completion_pct: 0 },
+    };
+    vi.mocked(worldbuildingApi.getDashboard).mockImplementation(() =>
+      dashboardFails
+        ? Promise.reject(new Error('Dashboard unavailable'))
+        : Promise.resolve({ ok: true, dashboard: empty ? {} : dashboard }),
+    );
+  }
+
+  it('Overview renders API-backed metrics, sessions, reminders, and quick links', async () => {
+    mockResources();
+    render(
+      <OverviewPage
+        worldId="world-1"
+        sessions={[
+          {
+            id: 'session-1',
+            title: 'Night planning',
+            world_id: 'world-1',
+            agent_id: null,
+            last_seq: 3,
+            created_at: '2026-06-17T10:00:00Z',
+            updated_at: '2026-06-19T10:00:00Z',
+            archived_at: null,
+          },
+        ]}
+        onNavigate={navigate}
+      />,
+    );
+
+    expect(await screen.findByText('Night planning')).toBeDefined();
+    expect(screen.getByText('The First Light')).toBeDefined();
+    expect(screen.getByRole('button', { name: 'View characters' })).toBeDefined();
+    expect(screen.getByTitle('Counted from the world character list.')).toHaveTextContent('1');
+  });
+
+  it('Overview falls back to derived resource counts when dashboard fails', async () => {
+    mockResources({ dashboardFails: true });
+    render(<OverviewPage worldId="world-1" sessions={[]} onNavigate={navigate} />);
+
+    expect(await screen.findByText(/Dashboard summary is unavailable\./)).toBeDefined();
+    expect(screen.getByTitle('Counted from the world character list.')).toHaveTextContent('1');
+    expect(screen.getByText('The First Light')).toBeDefined();
+  });
+
+  it('Overview shows an honest empty state for an empty world', async () => {
+    mockResources({ empty: true });
+    render(<OverviewPage worldId="world-1" sessions={[]} onNavigate={navigate} />);
+
+    expect(
+      await screen.findByRole('heading', { name: 'Your world is ready for its first details' }),
+    ).toBeDefined();
+    expect(screen.queryByText('Recent activity')).toBeNull();
+  });
+});
diff --git a/webui/src/pages/OverviewPage.module.css b/webui/src/pages/OverviewPage.module.css
new file mode 100644
index 00000000..bfe463c1
--- /dev/null
+++ b/webui/src/pages/OverviewPage.module.css
@@ -0,0 +1,236 @@
+.page {
+  height: 100%;
+  min-height: 0;
+  overflow: auto;
+  padding: 20px;
+  background: #f7f9fc;
+}
+
+.notice {
+  margin-bottom: 12px;
+  padding: 9px 12px;
+  border: 1px solid #f0d7a6;
+  border-radius: 7px;
+  background: #fff9eb;
+  color: #7a4d0b;
+}
+
+.metrics {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  gap: 12px;
+  margin-bottom: 16px;
+}
+
+.metricCard,
+.panel,
+.empty {
+  border: 1px solid #dfe6ef;
+  border-radius: 9px;
+  background: #fff;
+  box-shadow: 0 1px 2px rgba(16, 24, 40, 0.025);
+}
+
+.metricCard {
+  display: flex;
+  min-height: 132px;
+  align-items: flex-start;
+  justify-content: space-between;
+  padding: 18px;
+  color: #0b2d80;
+}
+
+.metricCard div {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+}
+.metricCard span {
+  color: #344054;
+  font-weight: 650;
+}
+.metricCard strong {
+  margin: 8px 0 4px;
+  color: #102f7c;
+  font-size: 28px;
+  line-height: 1;
+}
+.metricCard small {
+  color: #7a8699;
+  font-size: 10px;
+  line-height: 1.35;
+}
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 16px;
+}
+
+.panel {
+  min-height: 238px;
+  padding: 17px;
+}
+.panel header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 14px;
+}
+.panel h2 {
+  color: #17213b;
+  font-size: 15px;
+}
+.panel header button {
+  border: 0;
+  background: transparent;
+  color: #0b3b96;
+  cursor: pointer;
+  font-weight: 650;
+}
+
+.sessionList {
+  display: grid;
+  gap: 8px;
+}
+.session {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 12px;
+  border: 1px solid #e4e9f1;
+  border-radius: 7px;
+  color: #14398b;
+}
+.session div {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+  gap: 4px;
+}
+.session strong {
+  overflow: hidden;
+  color: #1d2939;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.session span,
+.muted {
+  color: #7a8699;
+}
+
+.progressRow {
+  margin: 20px 0;
+}
+.progressRow > div:first-child {
+  display: flex;
+  justify-content: space-between;
+  color: #263653;
+}
+.progressRow small {
+  color: #7a8699;
+}
+.track {
+  height: 6px;
+  margin: 8px 0 6px;
+  overflow: hidden;
+  border-radius: 999px;
+  background: #e8edf5;
+}
+.track span {
+  display: block;
+  height: 100%;
+  border-radius: inherit;
+  background: #0b3287;
+}
+
+.reminder {
+  display: flex;
+  width: 100%;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 11px 4px;
+  border: 0;
+  border-bottom: 1px solid #edf0f4;
+  background: transparent;
+  color: #a46b08;
+  cursor: pointer;
+  text-align: left;
+}
+.reminder span {
+  display: flex;
+  flex-direction: column;
+  gap: 3px;
+}
+.reminder strong {
+  color: #263653;
+}
+.reminder small {
+  color: #7a8699;
+}
+
+.quickLinks {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 10px;
+}
+.quickLinks button {
+  display: flex;
+  min-height: 72px;
+  align-items: center;
+  justify-content: center;
+  gap: 9px;
+  border: 1px solid #dfe6ef;
+  border-radius: 7px;
+  background: #fff;
+  color: #153981;
+  cursor: pointer;
+  font-weight: 700;
+}
+.quickLinks svg {
+  width: 20px;
+}
+
+.empty {
+  max-width: 560px;
+  margin: 12vh auto 0;
+  padding: 48px;
+  text-align: center;
+  color: #153981;
+}
+.empty h1 {
+  margin: 14px 0 8px;
+  color: #17213b;
+  font-size: 22px;
+}
+.empty p {
+  color: #667085;
+}
+.emptyActions {
+  display: flex;
+  justify-content: center;
+  gap: 10px;
+  margin-top: 24px;
+}
+.emptyActions button {
+  padding: 9px 14px;
+  border: 1px solid #cfd8e6;
+  border-radius: 6px;
+  background: #fff;
+  color: #14398b;
+  cursor: pointer;
+  font-weight: 700;
+}
+
+@media (max-width: 1050px) {
+  .metrics {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+}
+
+@media (max-width: 760px) {
+  .grid,
+  .metrics {
+    grid-template-columns: 1fr;
+  }
+}
diff --git a/webui/src/pages/OverviewPage.tsx b/webui/src/pages/OverviewPage.tsx
new file mode 100644
index 00000000..d88bc26e
--- /dev/null
+++ b/webui/src/pages/OverviewPage.tsx
@@ -0,0 +1,275 @@
+import { BookOpen, Clock3, Files, MessageSquarePlus, PanelsTopLeft, Users } from 'lucide-react';
+import { api } from '../api/client';
+import type {
+  SessionSummary,
+  StoryChapter,
+  StoryOverview,
+  StoryScene,
+  WorkspaceFile,
+  WorldAgent,
+} from '../api/types';
+import { worldbuildingApi } from '../api/worldbuilding';
+import type { AppPage } from '../AppState';
+import PageState from '../components/layout/PageState';
+import { useResource } from '../hooks/useResource';
+import styles from './OverviewPage.module.css';
+import { selectWorldMetrics, type DashboardData } from './selectors';
+
+interface OverviewPageProps {
+  worldId: string;
+  sessions: SessionSummary[];
+  onNavigate(page: AppPage): void;
+}
+
+interface OverviewData {
+  agents: WorldAgent[];
+  chapters: StoryChapter[];
+  scenes: StoryScene[];
+  files: WorkspaceFile[];
+  overview: StoryOverview | null;
+  dashboard: DashboardData | null;
+  dashboardFailed: boolean;
+}
+
+async function loadOverview(worldId: string): Promise<OverviewData> {
+  const [agents, chapters, scenes, files, overview, dashboard] = await Promise.allSettled([
+    api.listAgents(worldId),
+    api.listChapters(worldId),
+    api.listScenes(worldId),
+    api.listWorkspaceFiles({ world_id: worldId }),
+    api.getStoryOverview(worldId),
+    worldbuildingApi.getDashboard(worldId),
+  ]);
+
+  const required = [agents, chapters, scenes, files, overview];
+  if (required.every((result) => result.status === 'rejected')) {
+    throw new Error('Overview data could not be loaded.');
+  }
+
+  return {
+    agents: agents.status === 'fulfilled' ? (agents.value.agents ?? []) : [],
+    chapters: chapters.status === 'fulfilled' ? (chapters.value.chapters ?? []) : [],
+    scenes: scenes.status === 'fulfilled' ? (scenes.value.scenes ?? []) : [],
+    files: files.status === 'fulfilled' ? (files.value.files ?? []) : [],
+    overview: overview.status === 'fulfilled' ? overview.value.overview : null,
+    dashboard:
+      dashboard.status === 'fulfilled'
+        ? ((dashboard.value.dashboard as DashboardData | undefined) ?? null)
+        : null,
+    dashboardFailed: dashboard.status === 'rejected',
+  };
+}
+
+function formatUpdatedAt(value: string) {
+  const date = new Date(value);
+  return Number.isNaN(date.getTime())
+    ? value
+    : new Intl.DateTimeFormat(undefined, { month: 'short', day: 'numeric' }).format(date);
+}
+
+export default function OverviewPage({ worldId, sessions, onNavigate }: OverviewPageProps) {
+  const resource = useResource(`overview:${worldId}`, () => loadOverview(worldId));
+  const data = resource.data;
+
+  if (!data) {
+    return (
+      <PageState
+        loading={resource.status === 'loading'}
+        loadingLabel="Loading overview"
+        error={resource.error}
+        onRetry={resource.retry}
+      />
+    );
+  }
+
+  const metrics = selectWorldMetrics(data);
+  const activeSessions = sessions
+    .filter((session) => session.world_id === worldId && !session.archived_at)
+    .sort((a, b) => b.updated_at.localeCompare(a.updated_at))
+    .slice(0, 3);
+  const incompleteChapters = data.chapters.filter(
+    (chapter) => !['completed', 'revised'].includes(chapter.status),
+  );
+  const incompleteScenes = data.scenes.filter((scene) => scene.status !== 'completed');
+  const isEmpty =
+    metrics.characterCount + metrics.chapterCount + metrics.sceneCount + metrics.fileCount === 0 &&
+    activeSessions.length === 0;
+
+  if (isEmpty) {
+    return (
+      <div className={styles.page}>
+        <section className={styles.empty}>
+          <BookOpen size={30} aria-hidden="true" />
+          <h1>Your world is ready for its first details</h1>
+          <p>Add a character or chapter to begin shaping this world.</p>
+          <div className={styles.emptyActions}>
+            <button type="button" onClick={() => onNavigate('characters')}>
+              View characters
+            </button>
+            <button type="button" onClick={() => onNavigate('chapters')}>
+              View chapters
+            </button>
+          </div>
+        </section>
+      </div>
+    );
+  }
+
+  const metricCards = [
+    ['Characters', metrics.characterCount, 'Counted from the world character list.', Users],
+    [
+      'Chapters',
+      metrics.chapterCount,
+      'Counted from the chapter list or dashboard aggregate.',
+      BookOpen,
+    ],
+    [
+      'Scenes',
+      metrics.sceneCount,
+      'Counted from the scene list or dashboard aggregate.',
+      PanelsTopLeft,
+    ],
+    ['Files', metrics.fileCount, 'Counted from workspace files linked to this world.', Files],
+  ] as const;
+
+  return (
+    <main className={styles.page}>
+      {data.dashboardFailed && (
+        <div className={styles.notice} role="status">
+          Dashboard summary is unavailable. Showing derived resource counts.
+        </div>
+      )}
+
+      <section className={styles.metrics} aria-label="World metrics">
+        {metricCards.map(([label, value, source, Icon]) => (
+          <article className={styles.metricCard} key={label} title={source}>
+            <div>
+              <span>{label}</span>
+              <strong>{value}</strong>
+              <small>{source}</small>
+            </div>
+            <Icon size={24} aria-hidden="true" />
+          </article>
+        ))}
+      </section>
+
+      <div className={styles.grid}>
+        <section className={styles.panel}>
+          <header>
+            <h2>Recent sessions</h2>
+            <button onClick={() => onNavigate('sessions')}>View all</button>
+          </header>
+          {activeSessions.length ? (
+            <div className={styles.sessionList}>
+              {activeSessions.map((session) => (
+                <article className={styles.session} key={session.id}>
+                  <MessageSquarePlus size={18} aria-hidden="true" />
+                  <div>
+                    <strong>{session.title || 'Untitled session'}</strong>
+                    <span>Updated {formatUpdatedAt(session.updated_at)}</span>
+                  </div>
+                </article>
+              ))}
+            </div>
+          ) : (
+            <p className={styles.muted}>No sessions are linked to this world yet.</p>
+          )}
+        </section>
+
+        <section className={styles.panel}>
+          <header>
+            <h2>Current progress</h2>
+          </header>
+          <ProgressRow
+            label="Chapter completion"
+            value={metrics.chapterCompletionPercent}
+            detail={`${metrics.completedChapterCount} of ${metrics.chapterCount} chapters`}
+          />
+          <ProgressRow
+            label="Scene completion"
+            value={metrics.sceneCompletionPercent}
+            detail={`${metrics.completedSceneCount} of ${metrics.sceneCount} scenes`}
+          />
+        </section>
+
+        <section className={styles.panel}>
+          <header>
+            <h2>Reminders</h2>
+          </header>
+          {incompleteChapters.slice(0, 3).map((chapter) => (
+            <button
+              className={styles.reminder}
+              key={chapter.id}
+              onClick={() => onNavigate('chapters')}
+            >
+              <Clock3 size={17} aria-hidden="true" />
+              <span>
+                <strong>{chapter.title}</strong>
+                <small>Chapter status: {chapter.status}</small>
+              </span>
+            </button>
+          ))}
+          {incompleteScenes.slice(0, 3).map((scene) => (
+            <button className={styles.reminder} key={scene.id} onClick={() => onNavigate('scenes')}>
+              <Clock3 size={17} aria-hidden="true" />
+              <span>
+                <strong>{scene.title}</strong>
+                <small>Scene status: {scene.status}</small>
+              </span>
+            </button>
+          ))}
+          {!incompleteChapters.length && !incompleteScenes.length && (
+            <p className={styles.muted}>No incomplete chapters or scenes.</p>
+          )}
+        </section>
+
+        <section className={styles.panel}>
+          <header>
+            <h2>Quick links</h2>
+          </header>
+          <div className={styles.quickLinks}>
+            <button onClick={() => onNavigate('sessions')}>
+              <MessageSquarePlus aria-hidden="true" />
+              Sessions
+            </button>
+            <button aria-label="View characters" onClick={() => onNavigate('characters')}>
+              <Users aria-hidden="true" />
+              Characters
+            </button>
+            <button onClick={() => onNavigate('chapters')}>
+              <BookOpen aria-hidden="true" />
+              Chapters
+            </button>
+            <button onClick={() => onNavigate('files')}>
+              <Files aria-hidden="true" />
+              Files
+            </button>
+          </div>
+        </section>
+      </div>
+    </main>
+  );
+}
+
+function ProgressRow({ label, value, detail }: { label: string; value: number; detail: string }) {
+  const boundedValue = Math.max(0, Math.min(100, Math.round(value)));
+  return (
+    <div className={styles.progressRow}>
+      <div>
+        <strong>{label}</strong>
+        <span>{boundedValue}%</span>
+      </div>
+      <div
+        className={styles.track}
+        role="progressbar"
+        aria-label={label}
+        aria-valuemin={0}
+        aria-valuemax={100}
+        aria-valuenow={boundedValue}
+      >
+        <span style={{ width: `${boundedValue}%` }} />
+      </div>
+      <small>{detail}</small>
+    </div>
+  );
+}
diff --git a/webui/src/pages/selectors.ts b/webui/src/pages/selectors.ts
new file mode 100644
index 00000000..42cef7d0
--- /dev/null
+++ b/webui/src/pages/selectors.ts
@@ -0,0 +1,65 @@
+type Countable = { id: string };
+type StatusItem = Countable & { status?: string };
+
+export type DashboardData = Record<string, unknown>;
+
+export interface WorldMetricInput {
+  agents: Countable[];
+  chapters: StatusItem[];
+  scenes: StatusItem[];
+  files: Countable[];
+  overview: { agents?: Countable[] } | null;
+  dashboard: DashboardData | null;
+}
+
+export interface WorldMetrics {
+  characterCount: number;
+  chapterCount: number;
+  completedChapterCount: number;
+  sceneCount: number;
+  completedSceneCount: number;
+  fileCount: number;
+  chapterCompletionPercent: number;
+  sceneCompletionPercent: number;
+}
+
+function nestedNumber(source: DashboardData | null, group: string, key: string) {
+  const value = source?.[group];
+  if (!value || typeof value !== 'object') return null;
+  const candidate = (value as Record<string, unknown>)[key];
+  return typeof candidate === 'number' && Number.isFinite(candidate) ? candidate : null;
+}
+
+function percentage(completed: number, total: number) {
+  return total === 0 ? 0 : Math.round((completed / total) * 100);
+}
+
+export function selectWorldMetrics(input: WorldMetricInput): WorldMetrics {
+  const derivedAgents = input.agents.length || input.overview?.agents?.length || 0;
+  const derivedCompletedChapters = input.chapters.filter((item) =>
+    ['completed', 'revised'].includes(item.status ?? ''),
+  ).length;
+  const derivedCompletedScenes = input.scenes.filter((item) => item.status === 'completed').length;
+  const characterCount = nestedNumber(input.dashboard, 'agents', 'total') ?? derivedAgents;
+  const chapterCount = nestedNumber(input.dashboard, 'chapters', 'total') ?? input.chapters.length;
+  const completedChapterCount =
+    nestedNumber(input.dashboard, 'chapters', 'completed') ?? derivedCompletedChapters;
+  const sceneCount = nestedNumber(input.dashboard, 'scenes', 'total') ?? input.scenes.length;
+  const completedSceneCount =
+    nestedNumber(input.dashboard, 'scenes', 'completed') ?? derivedCompletedScenes;
+
+  return {
+    characterCount,
+    chapterCount,
+    completedChapterCount,
+    sceneCount,
+    completedSceneCount,
+    fileCount: input.files.length,
+    chapterCompletionPercent:
+      nestedNumber(input.dashboard, 'progress', 'chapter_completion_pct') ??
+      percentage(completedChapterCount, chapterCount),
+    sceneCompletionPercent:
+      nestedNumber(input.dashboard, 'progress', 'scene_completion_pct') ??
+      percentage(completedSceneCount, sceneCount),
+  };
+}

From 3e296fc43a5663ea104d9aeb2057a4d47a3d06e5 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 03:46:36 +0800
Subject: [PATCH 21/49] fix(webui): preserve overview data availability

---
 webui/src/__tests__/pages.test.tsx |  86 +++++++++++++++-
 webui/src/pages/OverviewPage.tsx   | 154 ++++++++++++++++++-----------
 webui/src/pages/selectors.ts       |  81 ++++++++++-----
 3 files changed, 232 insertions(+), 89 deletions(-)

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index bac69f81..f0341c59 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -316,12 +316,40 @@ describe('Overview selectors', () => {
       chapterCompletionPercent: 67,
     });
   });
+
+  it('counts revised dashboard chapters as completed progress', () => {
+    expect(
+      selectWorldMetrics({
+        agents: [],
+        chapters: null,
+        scenes: [],
+        files: [],
+        overview: null,
+        dashboard: {
+          chapters: { total: 1, completed: 0, revised: 1 },
+          progress: { chapter_completion_pct: 100 },
+        },
+      }),
+    ).toMatchObject({
+      chapterCount: 1,
+      completedChapterCount: 1,
+      chapterCompletionPercent: 100,
+    });
+  });
 });
 
 describe('Overview page', () => {
   const navigate = vi.fn();
 
-  function mockResources({ dashboardFails = false, empty = false } = {}) {
+  function mockResources({
+    dashboardFails = false,
+    empty = false,
+    failedLists = [],
+  }: {
+    dashboardFails?: boolean;
+    empty?: boolean;
+    failedLists?: Array<'agents' | 'chapters' | 'scenes' | 'files'>;
+  } = {}) {
     vi.mocked(api.listAgents).mockResolvedValue({
       ok: true,
       agents: empty ? [] : [{ id: 'a', name: 'Lin', display_name: 'Lin', kind: 'character' }],
@@ -357,6 +385,18 @@ describe('Overview page', () => {
         ? Promise.reject(new Error('Dashboard unavailable'))
         : Promise.resolve({ ok: true, dashboard: empty ? {} : dashboard }),
     );
+    if (failedLists.includes('agents')) {
+      vi.mocked(api.listAgents).mockRejectedValue(new Error('Agents unavailable'));
+    }
+    if (failedLists.includes('chapters')) {
+      vi.mocked(api.listChapters).mockRejectedValue(new Error('Chapters unavailable'));
+    }
+    if (failedLists.includes('scenes')) {
+      vi.mocked(api.listScenes).mockRejectedValue(new Error('Scenes unavailable'));
+    }
+    if (failedLists.includes('files')) {
+      vi.mocked(api.listWorkspaceFiles).mockRejectedValue(new Error('Files unavailable'));
+    }
   }
 
   it('Overview renders API-backed metrics, sessions, reminders, and quick links', async () => {
@@ -382,8 +422,16 @@ describe('Overview page', () => {
 
     expect(await screen.findByText('Night planning')).toBeDefined();
     expect(screen.getByText('The First Light')).toBeDefined();
-    expect(screen.getByRole('button', { name: 'View characters' })).toBeDefined();
-    expect(screen.getByTitle('Counted from the world character list.')).toHaveTextContent('1');
+    expect(screen.getByRole('button', { name: 'Sessions' })).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Settings' })).toBeDefined();
+    expect(screen.queryByRole('button', { name: 'View characters' })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Chapters' })).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Files' })).toBeNull();
+    expect(screen.getByText('Characters').closest('article')).toHaveAttribute(
+      'title',
+      'Counted from the worldbuilding dashboard.',
+    );
+    expect(screen.getByText('Characters').closest('article')).toHaveTextContent('1');
   });
 
   it('Overview falls back to derived resource counts when dashboard fails', async () => {
@@ -395,6 +443,38 @@ describe('Overview page', () => {
     expect(screen.getByText('The First Light')).toBeDefined();
   });
 
+  it('Overview does not turn failed lists into an empty world when dashboard also fails', async () => {
+    mockResources({
+      dashboardFails: true,
+      empty: true,
+      failedLists: ['agents', 'chapters', 'scenes', 'files'],
+    });
+    render(<OverviewPage worldId="world-1" sessions={[]} onNavigate={navigate} />);
+
+    expect(await screen.findByText(/Some overview data is unavailable\./)).toBeDefined();
+    expect(
+      screen.queryByRole('heading', { name: 'Your world is ready for its first details' }),
+    ).toBeNull();
+    expect(screen.getByText('Characters')).toBeDefined();
+    expect(screen.queryByText('Chapters')).toBeNull();
+    expect(screen.queryByText('Scenes')).toBeNull();
+    expect(screen.queryByText('Files')).toBeNull();
+    expect(screen.getByText('Reminder sources are unavailable.')).toBeDefined();
+  });
+
+  it('Overview omits only a failed metric and shows a partial warning', async () => {
+    mockResources({ failedLists: ['files'] });
+    render(<OverviewPage worldId="world-1" sessions={[]} onNavigate={navigate} />);
+
+    expect(await screen.findByText(/Some overview data is unavailable\./)).toBeDefined();
+    expect(screen.getByText('Characters')).toBeDefined();
+    expect(screen.getByText('Chapters')).toBeDefined();
+    expect(screen.queryByText('Files')).toBeNull();
+    expect(
+      screen.queryByRole('heading', { name: 'Your world is ready for its first details' }),
+    ).toBeNull();
+  });
+
   it('Overview shows an honest empty state for an empty world', async () => {
     mockResources({ empty: true });
     render(<OverviewPage worldId="world-1" sessions={[]} onNavigate={navigate} />);
diff --git a/webui/src/pages/OverviewPage.tsx b/webui/src/pages/OverviewPage.tsx
index d88bc26e..a2294411 100644
--- a/webui/src/pages/OverviewPage.tsx
+++ b/webui/src/pages/OverviewPage.tsx
@@ -1,4 +1,12 @@
-import { BookOpen, Clock3, Files, MessageSquarePlus, PanelsTopLeft, Users } from 'lucide-react';
+import {
+  BookOpen,
+  Clock3,
+  Files,
+  MessageSquarePlus,
+  PanelsTopLeft,
+  Settings,
+  Users,
+} from 'lucide-react';
 import { api } from '../api/client';
 import type {
   SessionSummary,
@@ -22,13 +30,14 @@ interface OverviewPageProps {
 }
 
 interface OverviewData {
-  agents: WorldAgent[];
-  chapters: StoryChapter[];
-  scenes: StoryScene[];
-  files: WorkspaceFile[];
+  agents: WorldAgent[] | null;
+  chapters: StoryChapter[] | null;
+  scenes: StoryScene[] | null;
+  files: WorkspaceFile[] | null;
   overview: StoryOverview | null;
   dashboard: DashboardData | null;
   dashboardFailed: boolean;
+  failedLists: Array<'agents' | 'chapters' | 'scenes' | 'files'>;
 }
 
 async function loadOverview(worldId: string): Promise<OverviewData> {
@@ -47,16 +56,22 @@ async function loadOverview(worldId: string): Promise<OverviewData> {
   }
 
   return {
-    agents: agents.status === 'fulfilled' ? (agents.value.agents ?? []) : [],
-    chapters: chapters.status === 'fulfilled' ? (chapters.value.chapters ?? []) : [],
-    scenes: scenes.status === 'fulfilled' ? (scenes.value.scenes ?? []) : [],
-    files: files.status === 'fulfilled' ? (files.value.files ?? []) : [],
+    agents: agents.status === 'fulfilled' ? (agents.value.agents ?? []) : null,
+    chapters: chapters.status === 'fulfilled' ? (chapters.value.chapters ?? []) : null,
+    scenes: scenes.status === 'fulfilled' ? (scenes.value.scenes ?? []) : null,
+    files: files.status === 'fulfilled' ? (files.value.files ?? []) : null,
     overview: overview.status === 'fulfilled' ? overview.value.overview : null,
     dashboard:
       dashboard.status === 'fulfilled'
         ? ((dashboard.value.dashboard as DashboardData | undefined) ?? null)
         : null,
     dashboardFailed: dashboard.status === 'rejected',
+    failedLists: [
+      ...(agents.status === 'rejected' ? (['agents'] as const) : []),
+      ...(chapters.status === 'rejected' ? (['chapters'] as const) : []),
+      ...(scenes.status === 'rejected' ? (['scenes'] as const) : []),
+      ...(files.status === 'rejected' ? (['files'] as const) : []),
+    ],
   };
 }
 
@@ -87,13 +102,16 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
     .filter((session) => session.world_id === worldId && !session.archived_at)
     .sort((a, b) => b.updated_at.localeCompare(a.updated_at))
     .slice(0, 3);
-  const incompleteChapters = data.chapters.filter(
-    (chapter) => !['completed', 'revised'].includes(chapter.status),
-  );
-  const incompleteScenes = data.scenes.filter((scene) => scene.status !== 'completed');
-  const isEmpty =
-    metrics.characterCount + metrics.chapterCount + metrics.sceneCount + metrics.fileCount === 0 &&
-    activeSessions.length === 0;
+  const incompleteChapters =
+    data.chapters?.filter((chapter) => !['completed', 'revised'].includes(chapter.status)) ?? null;
+  const incompleteScenes = data.scenes?.filter((scene) => scene.status !== 'completed') ?? null;
+  const metricValues = [
+    metrics.characterCount,
+    metrics.chapterCount,
+    metrics.sceneCount,
+    metrics.fileCount,
+  ];
+  const isEmpty = metricValues.every((value) => value === 0) && activeSessions.length === 0;
 
   if (isEmpty) {
     return (
@@ -103,11 +121,11 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
           <h1>Your world is ready for its first details</h1>
           <p>Add a character or chapter to begin shaping this world.</p>
           <div className={styles.emptyActions}>
-            <button type="button" onClick={() => onNavigate('characters')}>
-              View characters
+            <button type="button" onClick={() => onNavigate('sessions')}>
+              Open sessions
             </button>
-            <button type="button" onClick={() => onNavigate('chapters')}>
-              View chapters
+            <button type="button" onClick={() => onNavigate('settings')}>
+              Settings
             </button>
           </div>
         </section>
@@ -115,28 +133,32 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
     );
   }
 
+  const sourceCopy = (source: 'dashboard' | 'list' | 'overview' | null, listLabel: string) =>
+    source === 'dashboard'
+      ? 'Counted from the worldbuilding dashboard.'
+      : source === 'overview'
+        ? 'Counted from the story overview.'
+        : `Counted from the ${listLabel}.`;
   const metricCards = [
-    ['Characters', metrics.characterCount, 'Counted from the world character list.', Users],
-    [
-      'Chapters',
-      metrics.chapterCount,
-      'Counted from the chapter list or dashboard aggregate.',
-      BookOpen,
-    ],
     [
-      'Scenes',
-      metrics.sceneCount,
-      'Counted from the scene list or dashboard aggregate.',
-      PanelsTopLeft,
+      'Characters',
+      metrics.characterCount,
+      sourceCopy(metrics.characterSource, 'world character list'),
+      Users,
     ],
-    ['Files', metrics.fileCount, 'Counted from workspace files linked to this world.', Files],
-  ] as const;
+    ['Chapters', metrics.chapterCount, sourceCopy(metrics.chapterSource, 'chapter list'), BookOpen],
+    ['Scenes', metrics.sceneCount, sourceCopy(metrics.sceneSource, 'scene list'), PanelsTopLeft],
+    ['Files', metrics.fileCount, sourceCopy(metrics.fileSource, 'workspace file list'), Files],
+  ].filter((card): card is [string, number, string, typeof Users] => card[1] !== null);
 
   return (
     <main className={styles.page}>
-      {data.dashboardFailed && (
+      {(data.dashboardFailed || data.failedLists.length > 0) && (
         <div className={styles.notice} role="status">
-          Dashboard summary is unavailable. Showing derived resource counts.
+          {data.dashboardFailed && 'Dashboard summary is unavailable. '}
+          {data.failedLists.length > 0
+            ? 'Some overview data is unavailable. Available sections use verified sources.'
+            : 'Showing derived resource counts.'}
         </div>
       )}
 
@@ -180,23 +202,34 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
           <header>
             <h2>Current progress</h2>
           </header>
-          <ProgressRow
-            label="Chapter completion"
-            value={metrics.chapterCompletionPercent}
-            detail={`${metrics.completedChapterCount} of ${metrics.chapterCount} chapters`}
-          />
-          <ProgressRow
-            label="Scene completion"
-            value={metrics.sceneCompletionPercent}
-            detail={`${metrics.completedSceneCount} of ${metrics.sceneCount} scenes`}
-          />
+          {metrics.chapterCompletionPercent !== null &&
+            metrics.completedChapterCount !== null &&
+            metrics.chapterCount !== null && (
+              <ProgressRow
+                label="Chapter completion"
+                value={metrics.chapterCompletionPercent}
+                detail={`${metrics.completedChapterCount} of ${metrics.chapterCount} chapters`}
+              />
+            )}
+          {metrics.sceneCompletionPercent !== null &&
+            metrics.completedSceneCount !== null &&
+            metrics.sceneCount !== null && (
+              <ProgressRow
+                label="Scene completion"
+                value={metrics.sceneCompletionPercent}
+                detail={`${metrics.completedSceneCount} of ${metrics.sceneCount} scenes`}
+              />
+            )}
+          {metrics.chapterCompletionPercent === null && metrics.sceneCompletionPercent === null && (
+            <p className={styles.muted}>Progress sources are unavailable.</p>
+          )}
         </section>
 
         <section className={styles.panel}>
           <header>
             <h2>Reminders</h2>
           </header>
-          {incompleteChapters.slice(0, 3).map((chapter) => (
+          {incompleteChapters?.slice(0, 3).map((chapter) => (
             <button
               className={styles.reminder}
               key={chapter.id}
@@ -209,7 +242,7 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
               </span>
             </button>
           ))}
-          {incompleteScenes.slice(0, 3).map((scene) => (
+          {incompleteScenes?.slice(0, 3).map((scene) => (
             <button className={styles.reminder} key={scene.id} onClick={() => onNavigate('scenes')}>
               <Clock3 size={17} aria-hidden="true" />
               <span>
@@ -218,9 +251,18 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
               </span>
             </button>
           ))}
-          {!incompleteChapters.length && !incompleteScenes.length && (
-            <p className={styles.muted}>No incomplete chapters or scenes.</p>
+          {incompleteChapters === null && incompleteScenes === null && (
+            <p className={styles.muted}>Reminder sources are unavailable.</p>
+          )}
+          {(incompleteChapters === null) !== (incompleteScenes === null) && (
+            <p className={styles.muted}>Some reminder sources are unavailable.</p>
           )}
+          {incompleteChapters !== null &&
+            incompleteScenes !== null &&
+            !incompleteChapters.length &&
+            !incompleteScenes.length && (
+              <p className={styles.muted}>No incomplete chapters or scenes.</p>
+            )}
         </section>
 
         <section className={styles.panel}>
@@ -232,17 +274,9 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
               <MessageSquarePlus aria-hidden="true" />
               Sessions
             </button>
-            <button aria-label="View characters" onClick={() => onNavigate('characters')}>
-              <Users aria-hidden="true" />
-              Characters
-            </button>
-            <button onClick={() => onNavigate('chapters')}>
-              <BookOpen aria-hidden="true" />
-              Chapters
-            </button>
-            <button onClick={() => onNavigate('files')}>
-              <Files aria-hidden="true" />
-              Files
+            <button onClick={() => onNavigate('settings')}>
+              <Settings aria-hidden="true" />
+              Settings
             </button>
           </div>
         </section>
diff --git a/webui/src/pages/selectors.ts b/webui/src/pages/selectors.ts
index 42cef7d0..77d04257 100644
--- a/webui/src/pages/selectors.ts
+++ b/webui/src/pages/selectors.ts
@@ -4,23 +4,27 @@ type StatusItem = Countable & { status?: string };
 export type DashboardData = Record<string, unknown>;
 
 export interface WorldMetricInput {
-  agents: Countable[];
-  chapters: StatusItem[];
-  scenes: StatusItem[];
-  files: Countable[];
+  agents: Countable[] | null;
+  chapters: StatusItem[] | null;
+  scenes: StatusItem[] | null;
+  files: Countable[] | null;
   overview: { agents?: Countable[] } | null;
   dashboard: DashboardData | null;
 }
 
 export interface WorldMetrics {
-  characterCount: number;
-  chapterCount: number;
-  completedChapterCount: number;
-  sceneCount: number;
-  completedSceneCount: number;
-  fileCount: number;
-  chapterCompletionPercent: number;
-  sceneCompletionPercent: number;
+  characterCount: number | null;
+  chapterCount: number | null;
+  completedChapterCount: number | null;
+  sceneCount: number | null;
+  completedSceneCount: number | null;
+  fileCount: number | null;
+  chapterCompletionPercent: number | null;
+  sceneCompletionPercent: number | null;
+  characterSource: 'dashboard' | 'list' | 'overview' | null;
+  chapterSource: 'dashboard' | 'list' | null;
+  sceneSource: 'dashboard' | 'list' | null;
+  fileSource: 'dashboard' | 'list' | null;
 }
 
 function nestedNumber(source: DashboardData | null, group: string, key: string) {
@@ -35,18 +39,28 @@ function percentage(completed: number, total: number) {
 }
 
 export function selectWorldMetrics(input: WorldMetricInput): WorldMetrics {
-  const derivedAgents = input.agents.length || input.overview?.agents?.length || 0;
-  const derivedCompletedChapters = input.chapters.filter((item) =>
+  const dashboardCharacters = nestedNumber(input.dashboard, 'agents', 'total');
+  const dashboardChapters = nestedNumber(input.dashboard, 'chapters', 'total');
+  const dashboardCompletedChapters = nestedNumber(input.dashboard, 'chapters', 'completed');
+  const dashboardRevisedChapters = nestedNumber(input.dashboard, 'chapters', 'revised');
+  const dashboardScenes = nestedNumber(input.dashboard, 'scenes', 'total');
+  const dashboardCompletedScenes = nestedNumber(input.dashboard, 'scenes', 'completed');
+  const dashboardFiles = nestedNumber(input.dashboard, 'file_links', 'total');
+  const derivedCompletedChapters = input.chapters?.filter((item) =>
     ['completed', 'revised'].includes(item.status ?? ''),
   ).length;
-  const derivedCompletedScenes = input.scenes.filter((item) => item.status === 'completed').length;
-  const characterCount = nestedNumber(input.dashboard, 'agents', 'total') ?? derivedAgents;
-  const chapterCount = nestedNumber(input.dashboard, 'chapters', 'total') ?? input.chapters.length;
+  const derivedCompletedScenes = input.scenes?.filter((item) => item.status === 'completed').length;
+  const characterCount =
+    dashboardCharacters ?? input.agents?.length ?? input.overview?.agents?.length ?? null;
+  const chapterCount = dashboardChapters ?? input.chapters?.length ?? null;
   const completedChapterCount =
-    nestedNumber(input.dashboard, 'chapters', 'completed') ?? derivedCompletedChapters;
-  const sceneCount = nestedNumber(input.dashboard, 'scenes', 'total') ?? input.scenes.length;
-  const completedSceneCount =
-    nestedNumber(input.dashboard, 'scenes', 'completed') ?? derivedCompletedScenes;
+    dashboardCompletedChapters !== null
+      ? dashboardCompletedChapters + (dashboardRevisedChapters ?? 0)
+      : (derivedCompletedChapters ?? null);
+  const sceneCount = dashboardScenes ?? input.scenes?.length ?? null;
+  const completedSceneCount = dashboardCompletedScenes ?? derivedCompletedScenes ?? null;
+  const chapterPercent = nestedNumber(input.dashboard, 'progress', 'chapter_completion_pct');
+  const scenePercent = nestedNumber(input.dashboard, 'progress', 'scene_completion_pct');
 
   return {
     characterCount,
@@ -54,12 +68,27 @@ export function selectWorldMetrics(input: WorldMetricInput): WorldMetrics {
     completedChapterCount,
     sceneCount,
     completedSceneCount,
-    fileCount: input.files.length,
+    fileCount: dashboardFiles ?? input.files?.length ?? null,
     chapterCompletionPercent:
-      nestedNumber(input.dashboard, 'progress', 'chapter_completion_pct') ??
-      percentage(completedChapterCount, chapterCount),
+      chapterPercent ??
+      (completedChapterCount !== null && chapterCount !== null
+        ? percentage(completedChapterCount, chapterCount)
+        : null),
     sceneCompletionPercent:
-      nestedNumber(input.dashboard, 'progress', 'scene_completion_pct') ??
-      percentage(completedSceneCount, sceneCount),
+      scenePercent ??
+      (completedSceneCount !== null && sceneCount !== null
+        ? percentage(completedSceneCount, sceneCount)
+        : null),
+    characterSource:
+      dashboardCharacters !== null
+        ? 'dashboard'
+        : input.agents !== null
+          ? 'list'
+          : input.overview?.agents
+            ? 'overview'
+            : null,
+    chapterSource: dashboardChapters !== null ? 'dashboard' : input.chapters ? 'list' : null,
+    sceneSource: dashboardScenes !== null ? 'dashboard' : input.scenes ? 'list' : null,
+    fileSource: dashboardFiles !== null ? 'dashboard' : input.files ? 'list' : null,
   };
 }

From 1377c6459c80c5f08ac17b63066a5c8be83b249b Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 11:31:35 +0800
Subject: [PATCH 22/49] fix(webui): clarify overview metric provenance

---
 webui/src/__tests__/pages.test.tsx | 34 ++++++++++++++++++++++++++++++
 webui/src/pages/OverviewPage.tsx   | 23 +++++++++++++++++++-
 webui/src/pages/selectors.ts       | 21 ++++++++++++++----
 3 files changed, 73 insertions(+), 5 deletions(-)

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index f0341c59..8c11c847 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -336,6 +336,19 @@ describe('Overview selectors', () => {
       chapterCompletionPercent: 100,
     });
   });
+
+  it('does not substitute dashboard file-link associations for workspace files', () => {
+    expect(
+      selectWorldMetrics({
+        agents: [],
+        chapters: [],
+        scenes: [],
+        files: null,
+        overview: null,
+        dashboard: { file_links: { total: 9 } },
+      }),
+    ).toMatchObject({ fileCount: null, fileSource: null });
+  });
 });
 
 describe('Overview page', () => {
@@ -432,6 +445,14 @@ describe('Overview page', () => {
       'Counted from the worldbuilding dashboard.',
     );
     expect(screen.getByText('Characters').closest('article')).toHaveTextContent('1');
+    expect(screen.getByRole('progressbar', { name: 'Chapter completion' })).toHaveAttribute(
+      'title',
+      'Calculated from the worldbuilding dashboard.',
+    );
+    expect(screen.getByRole('progressbar', { name: 'Scene completion' })).toHaveAttribute(
+      'title',
+      'Calculated from scene statuses in the scene list.',
+    );
   });
 
   it('Overview falls back to derived resource counts when dashboard fails', async () => {
@@ -441,6 +462,10 @@ describe('Overview page', () => {
     expect(await screen.findByText(/Dashboard summary is unavailable\./)).toBeDefined();
     expect(screen.getByTitle('Counted from the world character list.')).toHaveTextContent('1');
     expect(screen.getByText('The First Light')).toBeDefined();
+    expect(screen.getByRole('progressbar', { name: 'Chapter completion' })).toHaveAttribute(
+      'title',
+      'Calculated from chapter statuses in the chapter list.',
+    );
   });
 
   it('Overview does not turn failed lists into an empty world when dashboard also fails', async () => {
@@ -464,6 +489,15 @@ describe('Overview page', () => {
 
   it('Overview omits only a failed metric and shows a partial warning', async () => {
     mockResources({ failedLists: ['files'] });
+    vi.mocked(worldbuildingApi.getDashboard).mockResolvedValue({
+      ok: true,
+      dashboard: {
+        agents: { total: 1 },
+        chapters: { total: 1, completed: 0 },
+        file_links: { total: 7 },
+        progress: { chapter_completion_pct: 0 },
+      },
+    });
     render(<OverviewPage worldId="world-1" sessions={[]} onNavigate={navigate} />);
 
     expect(await screen.findByText(/Some overview data is unavailable\./)).toBeDefined();
diff --git a/webui/src/pages/OverviewPage.tsx b/webui/src/pages/OverviewPage.tsx
index a2294411..25f82d36 100644
--- a/webui/src/pages/OverviewPage.tsx
+++ b/webui/src/pages/OverviewPage.tsx
@@ -209,6 +209,11 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
                 label="Chapter completion"
                 value={metrics.chapterCompletionPercent}
                 detail={`${metrics.completedChapterCount} of ${metrics.chapterCount} chapters`}
+                source={
+                  metrics.chapterProgressSource === 'dashboard'
+                    ? 'Calculated from the worldbuilding dashboard.'
+                    : 'Calculated from chapter statuses in the chapter list.'
+                }
               />
             )}
           {metrics.sceneCompletionPercent !== null &&
@@ -218,6 +223,11 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
                 label="Scene completion"
                 value={metrics.sceneCompletionPercent}
                 detail={`${metrics.completedSceneCount} of ${metrics.sceneCount} scenes`}
+                source={
+                  metrics.sceneProgressSource === 'dashboard'
+                    ? 'Calculated from the worldbuilding dashboard.'
+                    : 'Calculated from scene statuses in the scene list.'
+                }
               />
             )}
           {metrics.chapterCompletionPercent === null && metrics.sceneCompletionPercent === null && (
@@ -285,7 +295,17 @@ export default function OverviewPage({ worldId, sessions, onNavigate }: Overview
   );
 }
 
-function ProgressRow({ label, value, detail }: { label: string; value: number; detail: string }) {
+function ProgressRow({
+  label,
+  value,
+  detail,
+  source,
+}: {
+  label: string;
+  value: number;
+  detail: string;
+  source: string;
+}) {
   const boundedValue = Math.max(0, Math.min(100, Math.round(value)));
   return (
     <div className={styles.progressRow}>
@@ -300,6 +320,7 @@ function ProgressRow({ label, value, detail }: { label: string; value: number; d
         aria-valuemin={0}
         aria-valuemax={100}
         aria-valuenow={boundedValue}
+        title={source}
       >
         <span style={{ width: `${boundedValue}%` }} />
       </div>
diff --git a/webui/src/pages/selectors.ts b/webui/src/pages/selectors.ts
index 77d04257..45c80078 100644
--- a/webui/src/pages/selectors.ts
+++ b/webui/src/pages/selectors.ts
@@ -24,7 +24,9 @@ export interface WorldMetrics {
   characterSource: 'dashboard' | 'list' | 'overview' | null;
   chapterSource: 'dashboard' | 'list' | null;
   sceneSource: 'dashboard' | 'list' | null;
-  fileSource: 'dashboard' | 'list' | null;
+  fileSource: 'list' | null;
+  chapterProgressSource: 'dashboard' | 'list' | null;
+  sceneProgressSource: 'dashboard' | 'list' | null;
 }
 
 function nestedNumber(source: DashboardData | null, group: string, key: string) {
@@ -45,7 +47,6 @@ export function selectWorldMetrics(input: WorldMetricInput): WorldMetrics {
   const dashboardRevisedChapters = nestedNumber(input.dashboard, 'chapters', 'revised');
   const dashboardScenes = nestedNumber(input.dashboard, 'scenes', 'total');
   const dashboardCompletedScenes = nestedNumber(input.dashboard, 'scenes', 'completed');
-  const dashboardFiles = nestedNumber(input.dashboard, 'file_links', 'total');
   const derivedCompletedChapters = input.chapters?.filter((item) =>
     ['completed', 'revised'].includes(item.status ?? ''),
   ).length;
@@ -68,7 +69,7 @@ export function selectWorldMetrics(input: WorldMetricInput): WorldMetrics {
     completedChapterCount,
     sceneCount,
     completedSceneCount,
-    fileCount: dashboardFiles ?? input.files?.length ?? null,
+    fileCount: input.files?.length ?? null,
     chapterCompletionPercent:
       chapterPercent ??
       (completedChapterCount !== null && chapterCount !== null
@@ -89,6 +90,18 @@ export function selectWorldMetrics(input: WorldMetricInput): WorldMetrics {
             : null,
     chapterSource: dashboardChapters !== null ? 'dashboard' : input.chapters ? 'list' : null,
     sceneSource: dashboardScenes !== null ? 'dashboard' : input.scenes ? 'list' : null,
-    fileSource: dashboardFiles !== null ? 'dashboard' : input.files ? 'list' : null,
+    fileSource: input.files ? 'list' : null,
+    chapterProgressSource:
+      chapterPercent !== null || (dashboardChapters !== null && dashboardCompletedChapters !== null)
+        ? 'dashboard'
+        : input.chapters
+          ? 'list'
+          : null,
+    sceneProgressSource:
+      scenePercent !== null || (dashboardScenes !== null && dashboardCompletedScenes !== null)
+        ? 'dashboard'
+        : input.scenes
+          ? 'list'
+          : null,
   };
 }

From cf7df9019f68831b0abaf7bf550079a39e7351c7 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 11:43:40 +0800
Subject: [PATCH 23/49] feat(webui): migrate sessions into desktop workspace

---
 .superpowers/sdd/task-7-report.md       | 50 +++++++++++++++
 webui/src/App.tsx                       | 49 ++++++++-------
 webui/src/__tests__/UserFlow.test.tsx   | 75 ++++++++++++++++++++++-
 webui/src/__tests__/components.test.tsx | 14 +++--
 webui/src/components/MainPanel.tsx      | 38 +++++++++---
 webui/src/i18n.tsx                      |  4 +-
 webui/src/pages/SessionsPage.module.css | 81 +++++++++++++++++++++++++
 webui/src/pages/SessionsPage.tsx        | 56 +++++++++++++++++
 8 files changed, 325 insertions(+), 42 deletions(-)
 create mode 100644 .superpowers/sdd/task-7-report.md
 create mode 100644 webui/src/pages/SessionsPage.module.css
 create mode 100644 webui/src/pages/SessionsPage.tsx

diff --git a/.superpowers/sdd/task-7-report.md b/.superpowers/sdd/task-7-report.md
new file mode 100644
index 00000000..d5ede431
--- /dev/null
+++ b/.superpowers/sdd/task-7-report.md
@@ -0,0 +1,50 @@
+# Task 7 Report: Sessions Workbench
+
+## Status
+
+Implemented the lazy `sessions` route as a three-column sessions workbench using the existing session history, conversation, composer, SSE, and inspector components.
+
+## RED
+
+1. Baseline command:
+   `npm test -- --run src/__tests__/UserFlow.test.tsx src/__tests__/components.test.tsx`
+2. Baseline result: 48 passed, 2 failed.
+3. Preserved baseline failures:
+   - `World time control` / `Current: Day 4, dusk` did not match the approved rendered labels `世界时间` / `当前：Day 4, dusk`.
+   - The removed `Foreshadowing` sub-tab did not exist; `Create` is the approved accessible top-level tab.
+4. New page test RED:
+   `npm test -- --run src/__tests__/UserFlow.test.tsx`
+5. New page test result: failed because `../pages/SessionsPage` did not exist.
+
+## GREEN
+
+1. Focused command:
+   `npm test -- --run src/__tests__/UserFlow.test.tsx src/__tests__/components.test.tsx`
+2. Result: 51 passed, 0 failed across 2 test files.
+3. Build command: `npm run build`
+4. Result: TypeScript and Vite production build passed; Vite emitted a pre-existing large main-chunk advisory.
+5. Lint command: `npm run lint`
+6. Result: 0 errors and 12 pre-existing unused-type warnings in `src/api/client.ts`.
+
+## Preserved Workflows
+
+- `SessionList` remains the sole owner of create, select, rename, generated-title, archive, and restore behavior.
+- `ChatTimeline` and `Composer` remain mounted once through `MainPanel`, preserving messages, send, cancel, approvals, SSE status, and tool/run rendering.
+- `InspectorPanel` remains the sole owner of Story, Files, Agents, Create, and Run content, preserving generated files, editor entry points, creation dialogs, run replay, and audit behavior.
+- `App` still owns SSE setup and keeps help, setup, chapter review, ask, creation request, and export overlays outside the page route.
+- Editor routing and close protection remain unchanged.
+
+## Structure
+
+- Left: current-world session history using real `state.sessions` data.
+- Center: selected session title, connection status, chat timeline, and composer.
+- Right: existing inspector with approved `Story`, `Files`, `Agents`, `Create`, and `Run` labels.
+- Responsive behavior retains the history and inspector toggles without duplicating stateful workbench components.
+
+## Self-review
+
+- Confirmed `SessionsPage` is emitted as a separate lazy build chunk.
+- Confirmed the legacy workbench remains available for routes not migrated in this task.
+- Confirmed overlays remain siblings of the lazy page and were not moved or duplicated.
+- Confirmed no fixture content was added to production UI.
+- No task-specific lint errors remain.
diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index 3d253933..92f78c26 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -26,6 +26,7 @@ const SetupWizard = lazy(() => import('./components/SetupWizard'));
 const ChapterReviewBanner = lazy(() => import('./components/ChapterReviewBanner'));
 const ExportDialog = lazy(() => import('./components/ExportDialog'));
 const OverviewPage = lazy(() => import('./pages/OverviewPage'));
+const SessionsPage = lazy(() => import('./pages/SessionsPage'));
 
 export function shouldReportWorldbuildingPartialFailure(
   overviewLoaded: boolean,
@@ -303,27 +304,33 @@ function AppInner() {
   return (
     <ToastProvider>
       {inDesktopShell(
-        <div className={styles.layout}>
-          <ErrorBoundary>
-            <WorldSidebar open={sidebarOpen} onClose={() => setSidebarOpen(false)} />
-          </ErrorBoundary>
-          <ErrorBoundary>
-            <div className={styles.workspace}>
-              <ConnectionBanner state={connState} />
-              <MainPanel
-                onToggleSidebar={() => setSidebarOpen((prev) => !prev)}
-                onToggleInspector={() => setInspectorOpen((prev) => !prev)}
-                onOpenGuide={() => setHelpOpen(true)}
-                sidebarOpen={sidebarOpen}
-                inspectorOpen={inspectorOpen}
-                connectionState={connState}
-              />
-            </div>
-          </ErrorBoundary>
-          <ErrorBoundary>
-            <InspectorPanel open={inspectorOpen} onClose={() => setInspectorOpen(false)} />
-          </ErrorBoundary>
-        </div>,
+        state.currentPage === 'sessions' ? (
+          <Suspense fallback={<Skeleton />}>
+            <SessionsPage connectionState={connState} onOpenGuide={() => setHelpOpen(true)} />
+          </Suspense>
+        ) : (
+          <div className={styles.layout}>
+            <ErrorBoundary>
+              <WorldSidebar open={sidebarOpen} onClose={() => setSidebarOpen(false)} />
+            </ErrorBoundary>
+            <ErrorBoundary>
+              <div className={styles.workspace}>
+                <ConnectionBanner state={connState} />
+                <MainPanel
+                  onToggleSidebar={() => setSidebarOpen((prev) => !prev)}
+                  onToggleInspector={() => setInspectorOpen((prev) => !prev)}
+                  onOpenGuide={() => setHelpOpen(true)}
+                  sidebarOpen={sidebarOpen}
+                  inspectorOpen={inspectorOpen}
+                  connectionState={connState}
+                />
+              </div>
+            </ErrorBoundary>
+            <ErrorBoundary>
+              <InspectorPanel open={inspectorOpen} onClose={() => setInspectorOpen(false)} />
+            </ErrorBoundary>
+          </div>
+        ),
         <>
           <Suspense>
             <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />
diff --git a/webui/src/__tests__/UserFlow.test.tsx b/webui/src/__tests__/UserFlow.test.tsx
index 49ed4f7e..fb0b88a7 100644
--- a/webui/src/__tests__/UserFlow.test.tsx
+++ b/webui/src/__tests__/UserFlow.test.tsx
@@ -1,10 +1,79 @@
-import { render, screen, fireEvent } from '@testing-library/react';
+import { useEffect } from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
-import { AppStateProvider } from '../AppState';
+import { AppStateProvider, useAppState } from '../AppState';
 import Composer from '../components/Composer';
 import ExportDialog from '../components/ExportDialog';
-import { ToastProvider } from '../components/Toast';
 import SetupWizard from '../components/SetupWizard';
+import { ToastProvider } from '../components/Toast';
+import SessionsPage from '../pages/SessionsPage';
+
+function SessionsPageHarness() {
+  const { dispatch } = useAppState();
+
+  useEffect(() => {
+    dispatch({ type: 'SET_WORLD', worldId: 'world_1' });
+    dispatch({ type: 'SET_SESSION', sessionId: 'session_1' });
+    dispatch({ type: 'SET_CURRENT_RUN', runId: 'run_1' });
+    dispatch({ type: 'SET_STATUS', status: 'thinking' });
+    dispatch({
+      type: 'SET_WORLDBUILDING_DATA',
+      worlds: [
+        {
+          id: 'world_1',
+          name: 'Northreach',
+          description: 'Snowbound border city',
+          created_at: '2026-06-06T10:00:00Z',
+        },
+      ],
+      agents: [],
+      foreshadowing: [],
+      secrets: [],
+      worldTime: 'Day 4, dusk',
+    });
+    dispatch({
+      type: 'SET_SESSIONS',
+      sessions: [
+        {
+          id: 'session_1',
+          title: 'Plan the rain invasion',
+          world_id: 'world_1',
+          agent_id: null,
+          last_seq: 6,
+          created_at: '2026-06-06T10:30:00Z',
+          updated_at: '2026-06-06T10:35:00Z',
+          archived_at: null,
+        },
+      ],
+    });
+    dispatch({ type: 'SET_INSPECTOR_TAB', tab: 'run' });
+  }, [dispatch]);
+
+  return <SessionsPage connectionState="connected" />;
+}
+
+describe('Sessions workbench', () => {
+  it('keeps session history, conversation, context, composer, and execution state together', async () => {
+    render(
+      <AppStateProvider>
+        <ToastProvider>
+          <SessionsPageHarness />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+
+    expect(await screen.findByRole('region', { name: 'Session history' })).toBeDefined();
+    expect(screen.getByRole('main', { name: 'Conversation' })).toBeDefined();
+    expect(screen.getByRole('complementary', { name: 'Story inspector' })).toBeDefined();
+    expect(screen.getByRole('heading', { name: 'Plan the rain invasion' })).toBeDefined();
+    expect(screen.getByTestId('composer-input')).toBeDefined();
+    for (const tab of ['Story', 'Files', 'Agents', 'Create', 'Run']) {
+      expect(screen.getByRole('tab', { name: tab })).toBeDefined();
+    }
+    expect(screen.getAllByText('Thinking').length).toBeGreaterThan(0);
+    expect(await screen.findByText('Creation in progress')).toBeDefined();
+  });
+});
 
 describe('SetupWizard', () => {
   it('renders the provider selection step initially', () => {
diff --git a/webui/src/__tests__/components.test.tsx b/webui/src/__tests__/components.test.tsx
index fafc7aaa..afa56900 100644
--- a/webui/src/__tests__/components.test.tsx
+++ b/webui/src/__tests__/components.test.tsx
@@ -194,12 +194,14 @@ describe('Cell components', () => {
     render(
       <AppStateProvider>
         <ToastProvider>
-          <MainPanel connectionState="connected" />
+          <MainPanel connectionState="connected" onToggleHistory={() => {}} />
         </ToastProvider>
       </AppStateProvider>,
     );
 
-    expect(screen.getByRole('button', { name: 'Open sidebar' }).querySelector('svg')).toBeDefined();
+    expect(
+      screen.getByRole('button', { name: 'Open session history' }).querySelector('svg'),
+    ).toBeDefined();
     expect(
       screen.getByRole('button', { name: 'Open inspector' }).querySelector('svg'),
     ).toBeDefined();
@@ -728,8 +730,8 @@ describe('InspectorPanel', () => {
     expect(screen.getByText('Lian')).toBeDefined();
     expect(screen.getByText('The bell tower never rings at noon')).toBeDefined();
     expect(screen.getByText('Lian knows the passphrase')).toBeDefined();
-    expect(screen.getByText('World time control')).toBeDefined();
-    expect(screen.getByText('Current: Day 4, dusk')).toBeDefined();
+    expect(screen.getByText('世界时间')).toBeDefined();
+    expect(screen.getByText('当前：Day 4, dusk')).toBeDefined();
     expect(screen.queryByText(/[�鈥鈫鈭]/)).toBeNull();
   });
 
@@ -853,8 +855,8 @@ describe('InspectorPanel', () => {
     );
 
     expect(await screen.findByRole('heading', { name: 'Creation Panel' })).toBeDefined();
-    expect(screen.getByRole('tab', { name: /Foreshadowing/ })).toBeDefined();
-    expect(screen.getByText('Plant and track narrative threads.')).toBeDefined();
+    expect(screen.getByRole('tab', { name: 'Create' })).toBeDefined();
+    expect(await screen.findByText('Plant and track narrative threads.')).toBeDefined();
     expect(screen.getByText('Open Threads')).toBeDefined();
     expect(screen.getByText('The old bell never rings at noon.')).toBeDefined();
     expect(screen.queryByText(/[�鈥鈫鈭]/)).toBeNull();
diff --git a/webui/src/components/MainPanel.tsx b/webui/src/components/MainPanel.tsx
index 82ff3356..a24123d0 100644
--- a/webui/src/components/MainPanel.tsx
+++ b/webui/src/components/MainPanel.tsx
@@ -1,25 +1,31 @@
-import { CircleHelp, Menu, PanelRight, X } from 'lucide-react';
 import { useState } from 'react';
-import type { ConnectionState } from '../hooks/useSSE';
+import { CircleHelp, Menu, PanelRight, X } from 'lucide-react';
 import { useAppState } from '../AppState';
+import type { ConnectionState } from '../hooks/useSSE';
 import BrandMark from './BrandMark';
 import ChatTimeline from './ChatTimeline';
 import Composer from './Composer';
 import styles from './MainPanel.module.css';
 
 interface MainPanelProps {
+  title?: string;
+  onToggleHistory?: () => void;
   onToggleSidebar?: () => void;
   onToggleInspector?: () => void;
   onOpenGuide?: () => void;
+  historyOpen?: boolean;
   sidebarOpen?: boolean;
   inspectorOpen?: boolean;
   connectionState?: ConnectionState;
 }
 
 export default function MainPanel({
+  title,
+  onToggleHistory,
   onToggleSidebar,
   onToggleInspector,
   onOpenGuide,
+  historyOpen,
   sidebarOpen,
   inspectorOpen,
   connectionState = 'connecting',
@@ -30,9 +36,11 @@ export default function MainPanel({
   const currentAgent = state.agents.find((a) => a.id === state.agentId);
   const currentWorld = state.worlds.find((w) => w.id === state.worldId);
 
-  const headerTitle = currentAgent
-    ? `${currentAgent.display_name || currentAgent.name} / ${currentWorld?.name ?? ''}`
-    : 'Merak Workbench';
+  const headerTitle =
+    title ||
+    (currentAgent
+      ? `${currentAgent.display_name || currentAgent.name} / ${currentWorld?.name ?? ''}`
+      : 'Merak Workbench');
 
   const headerSubtitle = currentAgent
     ? (() => {
@@ -48,12 +56,20 @@ export default function MainPanel({
   const activeScene = state.storyOverview?.current_scene ?? null;
 
   return (
-    <main className={styles.main} role="main" aria-label="Chat">
+    <main className={styles.main} role="main" aria-label="Conversation">
       <header className={styles.header}>
         <button
           className={styles.iconBtn}
-          onClick={onToggleSidebar}
-          aria-label={sidebarOpen ? 'Close sidebar' : 'Open sidebar'}
+          onClick={onToggleHistory ?? onToggleSidebar}
+          aria-label={
+            onToggleHistory
+              ? historyOpen
+                ? 'Close session history'
+                : 'Open session history'
+              : sidebarOpen
+                ? 'Close sidebar'
+                : 'Open sidebar'
+          }
           data-testid="menu-btn"
         >
           <Menu size={18} aria-hidden="true" strokeWidth={2.2} />
@@ -62,7 +78,7 @@ export default function MainPanel({
           <BrandMark compact />
         </div>
         <div>
-          <div className={styles.title}>{headerTitle}</div>
+          <h1 className={styles.title}>{headerTitle}</h1>
           <div className={styles.subtitle}>
             {headerSubtitle}
             {activeScene && (
@@ -137,7 +153,9 @@ export default function MainPanel({
               </article>
               <article>
                 <strong>Close safely</strong>
-                <span>Active runs and unsaved editor changes are protected before window close.</span>
+                <span>
+                  Active runs and unsaved editor changes are protected before window close.
+                </span>
               </article>
             </div>
           </section>
diff --git a/webui/src/i18n.tsx b/webui/src/i18n.tsx
index 13e83035..4f10e1fa 100644
--- a/webui/src/i18n.tsx
+++ b/webui/src/i18n.tsx
@@ -358,8 +358,8 @@ const en: Dictionary = {
   'composer.hint': 'Enter to send · Shift+Enter for a new line',
   'inspector.kicker': 'Inspector',
   'inspector.story': 'Story',
-  'inspector.files': 'Drafts',
-  'inspector.agents': 'Characters',
+  'inspector.files': 'Files',
+  'inspector.agents': 'Agents',
   'inspector.creation': 'Create',
   'inspector.run': 'Run',
   'inspector.storyTitle': 'Story Context',
diff --git a/webui/src/pages/SessionsPage.module.css b/webui/src/pages/SessionsPage.module.css
new file mode 100644
index 00000000..729e7876
--- /dev/null
+++ b/webui/src/pages/SessionsPage.module.css
@@ -0,0 +1,81 @@
+.page {
+  display: grid;
+  grid-template-columns: 270px minmax(420px, 1fr) 360px;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+  background: #f7f9fc;
+}
+
+.history {
+  min-width: 0;
+  min-height: 0;
+  overflow-y: auto;
+  border-right: 1px solid #e2e8f0;
+  background: #fff;
+}
+
+.historyHeader {
+  display: flex;
+  min-height: 68px;
+  align-items: center;
+  padding: 0 16px;
+  border-bottom: 1px solid #e2e8f0;
+}
+
+.historyHeader span {
+  color: #667085;
+  font-size: 10px;
+  font-weight: 750;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+
+.historyHeader h2 {
+  margin-top: 3px;
+  color: #17213b;
+  font-size: 15px;
+  font-weight: 780;
+}
+
+.conversation {
+  display: flex;
+  min-width: 0;
+  min-height: 0;
+  flex-direction: column;
+  overflow: hidden;
+  background: #fff;
+}
+
+@media (max-width: 1179px) {
+  .page {
+    grid-template-columns: 250px minmax(0, 1fr);
+  }
+}
+
+@media (max-width: 767px) {
+  .page {
+    display: block;
+    position: relative;
+  }
+
+  .history {
+    position: absolute;
+    inset: 0 auto 0 0;
+    z-index: 30;
+    width: min(300px, 88vw);
+    transform: translateX(-100%);
+    transition: transform 220ms ease;
+  }
+
+  .historyOpen {
+    transform: translateX(0);
+    box-shadow: 18px 0 36px rgba(16, 24, 40, 0.14);
+  }
+
+  .conversation {
+    height: 100%;
+  }
+}
diff --git a/webui/src/pages/SessionsPage.tsx b/webui/src/pages/SessionsPage.tsx
new file mode 100644
index 00000000..f19ad129
--- /dev/null
+++ b/webui/src/pages/SessionsPage.tsx
@@ -0,0 +1,56 @@
+import { useState } from 'react';
+import { useAppState } from '../AppState';
+import ConnectionBanner from '../components/ConnectionBanner';
+import InspectorPanel from '../components/InspectorPanel';
+import MainPanel from '../components/MainPanel';
+import SessionList from '../components/Sidebar/SessionList';
+import type { ConnectionState } from '../hooks/useSSE';
+import styles from './SessionsPage.module.css';
+
+interface SessionsPageProps {
+  connectionState?: ConnectionState;
+  onOpenGuide?: () => void;
+}
+
+export default function SessionsPage({
+  connectionState = 'connecting',
+  onOpenGuide,
+}: SessionsPageProps) {
+  const { state } = useAppState();
+  const [historyOpen, setHistoryOpen] = useState(() => window.innerWidth >= 768);
+  const [inspectorOpen, setInspectorOpen] = useState(() => window.innerWidth >= 1180);
+  const selectedSession = state.sessions.find((session) => session.id === state.sessionId);
+  const conversationTitle = selectedSession?.title || 'New conversation';
+
+  return (
+    <div className={styles.page} aria-label="Sessions workbench">
+      <section
+        className={`${styles.history} ${historyOpen ? styles.historyOpen : ''}`}
+        aria-label="Session history"
+      >
+        <header className={styles.historyHeader}>
+          <div>
+            <span>Workspace</span>
+            <h2>Conversation history</h2>
+          </div>
+        </header>
+        <SessionList worldId={state.worldId ?? undefined} />
+      </section>
+
+      <section className={styles.conversation} aria-label="Conversation workspace">
+        <ConnectionBanner state={connectionState} />
+        <MainPanel
+          title={conversationTitle}
+          connectionState={connectionState}
+          historyOpen={historyOpen}
+          inspectorOpen={inspectorOpen}
+          onToggleHistory={() => setHistoryOpen((open) => !open)}
+          onToggleInspector={() => setInspectorOpen((open) => !open)}
+          onOpenGuide={onOpenGuide}
+        />
+      </section>
+
+      <InspectorPanel open={inspectorOpen} onClose={() => setInspectorOpen(false)} />
+    </div>
+  );
+}

From 2206b82f51aa03ddee3624739791991d13996de5 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 12:00:49 +0800
Subject: [PATCH 24/49] fix(webui): preserve sessions workbench state

---
 .superpowers/sdd/task-7-report.md             | 37 ++++++++++
 webui/src/App.tsx                             | 11 ++-
 webui/src/AppState.tsx                        |  3 +-
 webui/src/__tests__/AppState.test.ts          | 32 ++++++++-
 webui/src/__tests__/UserFlow.test.tsx         | 67 +++++++++++++++++++
 webui/src/__tests__/components.test.tsx       | 56 ++++++++++++++++
 webui/src/components/Composer.tsx             |  2 +-
 .../src/components/InspectorPanel.module.css  |  6 +-
 webui/src/components/InspectorPanel.tsx       |  2 +
 webui/src/components/MainPanel.tsx            |  4 ++
 webui/src/components/Sidebar/SessionList.tsx  | 27 +++++---
 webui/src/pages/SessionsPage.module.css       | 29 +++++++-
 webui/src/pages/SessionsPage.tsx              |  9 ++-
 13 files changed, 268 insertions(+), 17 deletions(-)

diff --git a/.superpowers/sdd/task-7-report.md b/.superpowers/sdd/task-7-report.md
index d5ede431..c230a3a7 100644
--- a/.superpowers/sdd/task-7-report.md
+++ b/.superpowers/sdd/task-7-report.md
@@ -48,3 +48,40 @@ Implemented the lazy `sessions` route as a three-column sessions workbench using
 - Confirmed overlays remain siblings of the lazy page and were not moved or duplicated.
 - Confirmed no fixture content was added to production UI.
 - No task-specific lint errors remain.
+
+## Review Fixes
+
+### RED
+
+Command:
+`npm test -- --run src/__tests__/UserFlow.test.tsx src/__tests__/components.test.tsx src/__tests__/AppState.test.ts`
+
+The new regressions demonstrated that:
+
+- `SET_SESSION` retained the previous agent when the selected session had no `agent_id`.
+- The sessions page exposed no `aria-hidden` state and desktop/tablet toggles did not control panel visibility.
+- A typed composer prompt could enable the send button without a selected session.
+- The App phase policy did not admit `sessions` during `no_agent`.
+
+### GREEN
+
+Focused command:
+`npm test -- --run src/__tests__/UserFlow.test.tsx src/__tests__/components.test.tsx src/__tests__/AppState.test.ts`
+
+Result: 98 passed, 0 failed across 3 test files.
+
+Build command: `npm run build`
+
+Result: TypeScript and Vite production build passed. The existing main-chunk size advisory remains; `SessionsPage` remains a separate lazy chunk.
+
+Lint command: `npm run lint`
+
+Result: 0 errors and the same 12 pre-existing unused-type warnings in `src/api/client.ts`.
+
+### Preserved constraints
+
+- `no_world` still renders onboarding before any sessions route can mount.
+- `no_agent` permits the sessions route so a user can select or create a session.
+- Selecting or creating a session atomically sets its agent, clears a missing agent, and moves the app to ready.
+- The composer send action stays disabled until both prompt text and a session ID exist; its handler guard remains intact.
+- Desktop and tablet toggles now collapse grid columns, remove hidden panels from interaction, and expose matching `aria-hidden` / `aria-expanded` state.
diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index 92f78c26..c4a103b0 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -2,7 +2,7 @@ import { lazy, Suspense, useEffect, useState, type ReactNode } from 'react';
 import { ArrowLeft } from 'lucide-react';
 import { api } from './api/client';
 import styles from './App.module.css';
-import { AppStateProvider, useAppState, type AppState } from './AppState';
+import { AppStateProvider, useAppState, type AppPage, type AppState } from './AppState';
 import AskUserPrompt from './components/AskUserPrompt';
 import ChapterEditor from './components/ChapterEditor';
 import ConnectionBanner from './components/ConnectionBanner';
@@ -41,6 +41,10 @@ export function shouldWarnBeforeClose(state: AppState) {
   return runActive || editorUnsafe;
 }
 
+export function shouldRenderSessionsPage(page: AppPage, phase: AppState['appPhase']) {
+  return page === 'sessions' && phase !== 'loading' && phase !== 'no_world';
+}
+
 function AppInner() {
   const { state, dispatch } = useAppState();
   const [sidebarOpen, setSidebarOpen] = useState(window.innerWidth >= 768);
@@ -287,7 +291,10 @@ function AppInner() {
     );
   }
 
-  if (state.appPhase === 'no_agent') {
+  if (
+    state.appPhase === 'no_agent' &&
+    !shouldRenderSessionsPage(state.currentPage, state.appPhase)
+  ) {
     return (
       <ToastProvider>
         {inDesktopShell(
diff --git a/webui/src/AppState.tsx b/webui/src/AppState.tsx
index 01eba17c..f770c739 100644
--- a/webui/src/AppState.tsx
+++ b/webui/src/AppState.tsx
@@ -375,7 +375,8 @@ export function reducer(state: AppState, action: Action): AppState {
       return {
         ...state,
         sessionId: action.sessionId,
-        agentId: action.agentId ?? state.agentId,
+        agentId: action.agentId ?? null,
+        appPhase: action.sessionId ? 'ready' : state.worldId ? 'no_agent' : state.appPhase,
         messages: [],
         lastSeq: 0,
         currentRun: null,
diff --git a/webui/src/__tests__/AppState.test.ts b/webui/src/__tests__/AppState.test.ts
index 7849dfc1..ff9358f2 100644
--- a/webui/src/__tests__/AppState.test.ts
+++ b/webui/src/__tests__/AppState.test.ts
@@ -1,5 +1,9 @@
 import { describe, expect, it } from 'vitest';
-import { shouldReportWorldbuildingPartialFailure, shouldWarnBeforeClose } from '../App';
+import {
+  shouldRenderSessionsPage,
+  shouldReportWorldbuildingPartialFailure,
+  shouldWarnBeforeClose,
+} from '../App';
 import { initialState, reducer, type AppState } from '../AppState';
 
 function state(overrides: Partial<AppState> = {}): AppState {
@@ -29,6 +33,21 @@ describe('AppState reducer', () => {
     expect(next.pendingCreation).toBeNull();
   });
 
+  it('SET_SESSION replaces the previous agent and clears it when the session has none', () => {
+    const withAgent = reducer(state({ agentId: 'old-agent' }), {
+      type: 'SET_SESSION',
+      sessionId: 'agent-session',
+      agentId: 'new-agent',
+    });
+    expect(withAgent.agentId).toBe('new-agent');
+
+    const withoutAgent = reducer(withAgent, {
+      type: 'SET_SESSION',
+      sessionId: 'world-session',
+    });
+    expect(withoutAgent.agentId).toBeNull();
+  });
+
   it('SET_METADATA stores metadata and sets selectedModel', () => {
     const prev = state();
     const next = reducer(prev, {
@@ -543,6 +562,17 @@ describe('worldbuilding bootstrap error policy', () => {
   });
 });
 
+describe('sessions route policy', () => {
+  it('allows the sessions page while a world has no active agent session', () => {
+    expect(shouldRenderSessionsPage('sessions', 'no_agent')).toBe(true);
+  });
+
+  it('keeps loading and no-world phases on their truthful boundary pages', () => {
+    expect(shouldRenderSessionsPage('sessions', 'loading')).toBe(false);
+    expect(shouldRenderSessionsPage('sessions', 'no_world')).toBe(false);
+  });
+});
+
 describe('close protection policy', () => {
   it('warns before closing while a run is active', () => {
     expect(shouldWarnBeforeClose(state({ currentRun: 'run_1', status: 'thinking' }))).toBe(true);
diff --git a/webui/src/__tests__/UserFlow.test.tsx b/webui/src/__tests__/UserFlow.test.tsx
index fb0b88a7..6a1cb907 100644
--- a/webui/src/__tests__/UserFlow.test.tsx
+++ b/webui/src/__tests__/UserFlow.test.tsx
@@ -1,6 +1,7 @@
 import { useEffect } from 'react';
 import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
+import { api } from '../api/client';
 import { AppStateProvider, useAppState } from '../AppState';
 import Composer from '../components/Composer';
 import ExportDialog from '../components/ExportDialog';
@@ -54,6 +55,7 @@ function SessionsPageHarness() {
 
 describe('Sessions workbench', () => {
   it('keeps session history, conversation, context, composer, and execution state together', async () => {
+    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 1440 });
     render(
       <AppStateProvider>
         <ToastProvider>
@@ -73,6 +75,55 @@ describe('Sessions workbench', () => {
     expect(screen.getAllByText('Thinking').length).toBeGreaterThan(0);
     expect(await screen.findByText('Creation in progress')).toBeDefined();
   });
+
+  it('hides and restores history and inspector panels with truthful toggle state', async () => {
+    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 1440 });
+    render(
+      <AppStateProvider>
+        <ToastProvider>
+          <SessionsPageHarness />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+
+    const history = await screen.findByRole('region', { name: 'Session history' });
+    const inspector = screen.getByRole('complementary', { name: 'Story inspector' });
+    expect(history).toHaveAttribute('aria-hidden', 'false');
+    expect(inspector).toHaveAttribute('aria-hidden', 'false');
+
+    fireEvent.click(screen.getByTestId('menu-btn'));
+    expect(history).toHaveAttribute('aria-hidden', 'true');
+    expect(history.className).not.toContain('historyOpen');
+    expect(screen.getByRole('button', { name: 'Open session history' })).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+
+    fireEvent.click(screen.getByTestId('inspector-btn'));
+    expect(inspector).toHaveAttribute('aria-hidden', 'true');
+    expect(inspector.className).not.toContain('panelOpen');
+    expect(screen.getByRole('button', { name: 'Open inspector' })).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+  });
+
+  it('opens the inspector from its tablet default without exposing a hidden-state mismatch', async () => {
+    Object.defineProperty(window, 'innerWidth', { configurable: true, value: 1024 });
+    render(
+      <AppStateProvider>
+        <ToastProvider>
+          <SessionsPageHarness />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+
+    const inspector = await screen.findByTestId('inspector-panel');
+    expect(inspector).toHaveAttribute('aria-hidden', 'true');
+    fireEvent.click(screen.getByRole('button', { name: 'Open inspector' }));
+    expect(inspector).toHaveAttribute('aria-hidden', 'false');
+    expect(inspector.className).toContain('panelOpen');
+  });
 });
 
 describe('SetupWizard', () => {
@@ -292,4 +343,20 @@ describe('Composer', () => {
     // Send button is disabled when text is empty
     expect((sendBtn as HTMLButtonElement).disabled).toBe(true);
   });
+
+  it('cannot start a run without a selected session', () => {
+    const startRun = vi.spyOn(api, 'startRun');
+    render(
+      <AppStateProvider>
+        <ToastProvider>
+          <Composer />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+
+    fireEvent.change(screen.getByTestId('composer-input'), { target: { value: 'Draft a scene' } });
+    expect(screen.getByTestId('send-btn')).toBeDisabled();
+    fireEvent.click(screen.getByTestId('send-btn'));
+    expect(startRun).not.toHaveBeenCalled();
+  });
 });
diff --git a/webui/src/__tests__/components.test.tsx b/webui/src/__tests__/components.test.tsx
index afa56900..fe59b9cb 100644
--- a/webui/src/__tests__/components.test.tsx
+++ b/webui/src/__tests__/components.test.tsx
@@ -121,6 +121,47 @@ function SessionLifecycleHarness() {
   return <SessionList />;
 }
 
+function SessionSelectionHarness() {
+  const { state, dispatch } = useAppState();
+
+  useEffect(() => {
+    dispatch({ type: 'SET_AGENT_SESSION', sessionId: 'agent_session', agentId: 'agent_old' });
+    dispatch({
+      type: 'SET_SESSIONS',
+      sessions: [
+        {
+          id: 'agent_session',
+          title: 'Agent draft',
+          world_id: 'world_1',
+          agent_id: 'agent_old',
+          last_seq: 1,
+          created_at: '2026-06-06T10:30:00Z',
+          updated_at: '2026-06-06T10:30:00Z',
+          archived_at: null,
+        },
+        {
+          id: 'world_session',
+          title: 'World notes',
+          world_id: 'world_1',
+          agent_id: null,
+          last_seq: 2,
+          created_at: '2026-06-06T11:00:00Z',
+          updated_at: '2026-06-06T11:00:00Z',
+          archived_at: null,
+        },
+      ],
+    });
+  }, [dispatch]);
+
+  return (
+    <>
+      <SessionList worldId="world_1" />
+      <output aria-label="selected-session">{state.sessionId}</output>
+      <output aria-label="selected-agent">{state.agentId ?? 'none'}</output>
+    </>
+  );
+}
+
 function WorldIconHarness() {
   const { dispatch } = useAppState();
 
@@ -266,6 +307,21 @@ describe('Cell components', () => {
     expect(screen.getByLabelText('Session Old outline, archived, 8 turns')).toBeDefined();
   });
 
+  it('SessionList selects the session agent and clears a stale agent when absent', () => {
+    render(
+      <AppStateProvider>
+        <ToastProvider>
+          <SessionSelectionHarness />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+
+    fireEvent.click(screen.getByLabelText('Session World notes, 2 turns'));
+
+    expect(screen.getByLabelText('selected-session')).toHaveTextContent('world_session');
+    expect(screen.getByLabelText('selected-agent')).toHaveTextContent('none');
+  });
+
   it('UserCell renders text', () => {
     render(<UserCell text="Hello world" />);
     expect(screen.getByText('Hello world')).toBeDefined();
diff --git a/webui/src/components/Composer.tsx b/webui/src/components/Composer.tsx
index a5106e02..1a73d9bd 100644
--- a/webui/src/components/Composer.tsx
+++ b/webui/src/components/Composer.tsx
@@ -294,7 +294,7 @@ export default function Composer() {
           <button
             className={styles.sendBtn}
             onClick={send}
-            disabled={sending || !text.trim()}
+            disabled={sending || !text.trim() || !state.sessionId}
             data-testid="send-btn"
             aria-label="Send message"
           >
diff --git a/webui/src/components/InspectorPanel.module.css b/webui/src/components/InspectorPanel.module.css
index f9c984a3..49be486d 100644
--- a/webui/src/components/InspectorPanel.module.css
+++ b/webui/src/components/InspectorPanel.module.css
@@ -6,13 +6,17 @@
   background:
     linear-gradient(180deg, rgba(255, 255, 255, 0.84), rgba(242, 242, 240, 0.82)),
     var(--surface-muted);
-  display: flex;
+  display: none;
   position: relative;
   z-index: 20;
   box-shadow: var(--shadow-md);
   animation: inspectorEnter 620ms var(--ease-spring) 80ms both;
 }
 
+.panelOpen {
+  display: flex;
+}
+
 .surface {
   width: 100%;
   display: flex;
diff --git a/webui/src/components/InspectorPanel.tsx b/webui/src/components/InspectorPanel.tsx
index a5821dbd..8195cc32 100644
--- a/webui/src/components/InspectorPanel.tsx
+++ b/webui/src/components/InspectorPanel.tsx
@@ -49,8 +49,10 @@ export default function InspectorPanel({ open = true, onClose }: InspectorPanelP
 
   return (
     <aside
+      id="session-inspector-panel"
       className={`${styles.panel} ${open ? styles.panelOpen : ''}`}
       aria-label="Story inspector"
+      aria-hidden={!open}
       data-testid="inspector-panel"
     >
       <div className={styles.mobileScrim} onClick={onClose} />
diff --git a/webui/src/components/MainPanel.tsx b/webui/src/components/MainPanel.tsx
index a24123d0..de191415 100644
--- a/webui/src/components/MainPanel.tsx
+++ b/webui/src/components/MainPanel.tsx
@@ -70,6 +70,8 @@ export default function MainPanel({
                 ? 'Close sidebar'
                 : 'Open sidebar'
           }
+          aria-controls="session-history-panel"
+          aria-expanded={onToggleHistory ? historyOpen : sidebarOpen}
           data-testid="menu-btn"
         >
           <Menu size={18} aria-hidden="true" strokeWidth={2.2} />
@@ -110,6 +112,8 @@ export default function MainPanel({
           className={styles.iconBtn}
           onClick={onToggleInspector}
           aria-label={inspectorOpen ? 'Close inspector' : 'Open inspector'}
+          aria-controls="session-inspector-panel"
+          aria-expanded={inspectorOpen}
           data-testid="inspector-btn"
         >
           <PanelRight size={18} aria-hidden="true" strokeWidth={2.2} />
diff --git a/webui/src/components/Sidebar/SessionList.tsx b/webui/src/components/Sidebar/SessionList.tsx
index fce76f4d..ebf35a9e 100644
--- a/webui/src/components/Sidebar/SessionList.tsx
+++ b/webui/src/components/Sidebar/SessionList.tsx
@@ -37,21 +37,32 @@ export default function SessionList({ worldId, agentId }: SessionListProps) {
     try {
       const data = await api.createSession('', worldId, agentId);
       const id = data.session_id;
+      const session: SessionSummary = {
+        id,
+        title: '',
+        world_id: worldId ?? null,
+        agent_id: agentId ?? null,
+        last_seq: 0,
+        created_at: '',
+        updated_at: '',
+        archived_at: null,
+      };
       dispatch({
         type: 'SET_SESSIONS',
-        sessions: [
-          ...state.sessions,
-          { id, title: '', world_id: worldId ?? null, agent_id: agentId ?? null, last_seq: 0, created_at: '', updated_at: '', archived_at: null },
-        ],
+        sessions: [...state.sessions, session],
       });
-      select(id);
+      select(session);
     } catch {
       showToast('Failed to create session', 'error');
     }
   }
 
-  function select(id: string) {
-    dispatch({ type: 'SET_SESSION', sessionId: id });
+  function select(session: SessionSummary) {
+    dispatch({
+      type: 'SET_SESSION',
+      sessionId: session.id,
+      agentId: session.agent_id ?? undefined,
+    });
   }
 
   function startRename(session: { id: string; title: string }) {
@@ -139,7 +150,7 @@ export default function SessionList({ worldId, agentId }: SessionListProps) {
         className={`${styles.item} ${session.id === state.sessionId ? styles.itemActive : ''} ${
           session.archived_at ? styles.itemArchived : ''
         }`}
-        onClick={() => select(session.id)}
+        onClick={() => select(session)}
         onContextMenu={(e) => {
           e.preventDefault();
           startRename(session);
diff --git a/webui/src/pages/SessionsPage.module.css b/webui/src/pages/SessionsPage.module.css
index 729e7876..3b9f7530 100644
--- a/webui/src/pages/SessionsPage.module.css
+++ b/webui/src/pages/SessionsPage.module.css
@@ -1,6 +1,8 @@
 .page {
+  --history-width: 270px;
+  --inspector-width: 360px;
   display: grid;
-  grid-template-columns: 270px minmax(420px, 1fr) 360px;
+  grid-template-columns: var(--history-width) minmax(420px, 1fr) var(--inspector-width);
   width: 100%;
   height: 100%;
   min-width: 0;
@@ -9,12 +11,29 @@
   background: #f7f9fc;
 }
 
+.historyClosed {
+  --history-width: 0px;
+}
+
+.inspectorClosed {
+  --inspector-width: 0px;
+}
+
 .history {
   min-width: 0;
   min-height: 0;
   overflow-y: auto;
   border-right: 1px solid #e2e8f0;
   background: #fff;
+  opacity: 0;
+  pointer-events: none;
+  visibility: hidden;
+}
+
+.historyOpen {
+  opacity: 1;
+  pointer-events: auto;
+  visibility: visible;
 }
 
 .historyHeader {
@@ -51,7 +70,13 @@
 
 @media (max-width: 1179px) {
   .page {
-    grid-template-columns: 250px minmax(0, 1fr);
+    --history-width: 250px;
+    --inspector-width: 0px;
+    grid-template-columns: var(--history-width) minmax(0, 1fr) var(--inspector-width);
+  }
+
+  .historyClosed {
+    --history-width: 0px;
   }
 }
 
diff --git a/webui/src/pages/SessionsPage.tsx b/webui/src/pages/SessionsPage.tsx
index f19ad129..aae6f83c 100644
--- a/webui/src/pages/SessionsPage.tsx
+++ b/webui/src/pages/SessionsPage.tsx
@@ -23,10 +23,17 @@ export default function SessionsPage({
   const conversationTitle = selectedSession?.title || 'New conversation';
 
   return (
-    <div className={styles.page} aria-label="Sessions workbench">
+    <div
+      className={`${styles.page} ${historyOpen ? '' : styles.historyClosed} ${
+        inspectorOpen ? '' : styles.inspectorClosed
+      }`}
+      aria-label="Sessions workbench"
+    >
       <section
+        id="session-history-panel"
         className={`${styles.history} ${historyOpen ? styles.historyOpen : ''}`}
         aria-label="Session history"
+        aria-hidden={!historyOpen}
       >
         <header className={styles.historyHeader}>
           <div>

From e133d3e156a3e8d46ded5f63d09fc2e8105dd945 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 12:07:09 +0800
Subject: [PATCH 25/49] fix(webui): keep sessions inspector reachable

---
 .superpowers/sdd/task-7-report.md       | 26 +++++++++++++++++
 webui/src/__tests__/components.test.tsx | 37 +++++++++++++++++++++++++
 webui/src/components/MainPanel.tsx      |  2 +-
 webui/src/pages/SessionsPage.module.css |  2 +-
 4 files changed, 65 insertions(+), 2 deletions(-)

diff --git a/.superpowers/sdd/task-7-report.md b/.superpowers/sdd/task-7-report.md
index c230a3a7..c16228df 100644
--- a/.superpowers/sdd/task-7-report.md
+++ b/.superpowers/sdd/task-7-report.md
@@ -85,3 +85,29 @@ Result: 0 errors and the same 12 pre-existing unused-type warnings in `src/api/c
 - Selecting or creating a session atomically sets its agent, clears a missing agent, and moves the app to ready.
 - The composer send action stays disabled until both prompt text and a session ID exist; its handler guard remains intact.
 - Desktop and tablet toggles now collapse grid columns, remove hidden panels from interaction, and expose matching `aria-hidden` / `aria-expanded` state.
+
+## Final Review Fixes
+
+### RED
+
+Command:
+`npm test -- --run src/__tests__/components.test.tsx src/__tests__/UserFlow.test.tsx`
+
+Result: 2 new failures, confirming that the base sessions grid required a 420px center track and legacy `MainPanel` sidebar mode referenced the sessions-only `session-history-panel` ID.
+
+### GREEN
+
+Command:
+`npm test -- --run src/__tests__/components.test.tsx src/__tests__/UserFlow.test.tsx`
+
+Result: 57 passed, 0 failed across 2 test files.
+
+Build command: `npm run build`
+
+Result: TypeScript and Vite production build passed. The existing main-chunk size advisory remains.
+
+### Preserved constraints
+
+- The base three-column grid now uses `minmax(0, 1fr)`, so a 1180-1293px viewport can retain the inspector without exceeding the shell content width.
+- The existing `1179px` inspector-overlay breakpoint remains, preserving the 960px minimum-window layout.
+- Sessions mode retains `aria-controls="session-history-panel"`; legacy sidebar mode emits no reference to that sessions-only ID.
diff --git a/webui/src/__tests__/components.test.tsx b/webui/src/__tests__/components.test.tsx
index fe59b9cb..eaddd266 100644
--- a/webui/src/__tests__/components.test.tsx
+++ b/webui/src/__tests__/components.test.tsx
@@ -250,6 +250,43 @@ describe('Cell components', () => {
     expect(screen.queryByText('◫')).toBeNull();
   });
 
+  it('MainPanel only references session history controls in sessions mode', () => {
+    const { rerender } = render(
+      <AppStateProvider>
+        <ToastProvider>
+          <MainPanel connectionState="connected" onToggleSidebar={() => {}} />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+
+    expect(screen.getByRole('button', { name: 'Open sidebar' })).not.toHaveAttribute(
+      'aria-controls',
+    );
+
+    rerender(
+      <AppStateProvider>
+        <ToastProvider>
+          <MainPanel connectionState="connected" onToggleHistory={() => {}} />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+
+    expect(screen.getByRole('button', { name: 'Open session history' })).toHaveAttribute(
+      'aria-controls',
+      'session-history-panel',
+    );
+  });
+
+  it('keeps the sessions center column shrinkable before inspector overlay mode', () => {
+    const css = readFileSync(join(process.cwd(), 'src/pages/SessionsPage.module.css'), 'utf8');
+    const basePageRule = css.match(/^\.page\s*\{([^}]*)\}/m)?.[1] ?? '';
+
+    expect(basePageRule).toMatch(
+      /grid-template-columns:\s*var\(--history-width\)\s+minmax\(0,\s*1fr\)\s+var\(--inspector-width\)/,
+    );
+    expect(css).toMatch(/@media\s*\(max-width:\s*1179px\)/);
+  });
+
   it('MainPanel opens an in-workbench guide from the help control', () => {
     render(
       <AppStateProvider>
diff --git a/webui/src/components/MainPanel.tsx b/webui/src/components/MainPanel.tsx
index de191415..f83645c4 100644
--- a/webui/src/components/MainPanel.tsx
+++ b/webui/src/components/MainPanel.tsx
@@ -70,7 +70,7 @@ export default function MainPanel({
                 ? 'Close sidebar'
                 : 'Open sidebar'
           }
-          aria-controls="session-history-panel"
+          aria-controls={onToggleHistory ? 'session-history-panel' : undefined}
           aria-expanded={onToggleHistory ? historyOpen : sidebarOpen}
           data-testid="menu-btn"
         >
diff --git a/webui/src/pages/SessionsPage.module.css b/webui/src/pages/SessionsPage.module.css
index 3b9f7530..50144cc2 100644
--- a/webui/src/pages/SessionsPage.module.css
+++ b/webui/src/pages/SessionsPage.module.css
@@ -2,7 +2,7 @@
   --history-width: 270px;
   --inspector-width: 360px;
   display: grid;
-  grid-template-columns: var(--history-width) minmax(420px, 1fr) var(--inspector-width);
+  grid-template-columns: var(--history-width) minmax(0, 1fr) var(--inspector-width);
   width: 100%;
   height: 100%;
   min-width: 0;

From 9b7597ee064b3b8197cba79c2e6536e8b19ff011 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 12:23:23 +0800
Subject: [PATCH 26/49] feat(webui): add world and character workspaces

---
 webui/src/App.tsx                             |  18 ++
 webui/src/__tests__/pages.test.tsx            | 174 +++++++++++++-
 .../components/Inspector/AgentCardView.tsx    | 139 ++++++-----
 .../components/Inspector/AgentsInspector.tsx  |   7 +-
 webui/src/pages/CharactersPage.module.css     | 196 +++++++++++++++
 webui/src/pages/CharactersPage.tsx            | 212 ++++++++++++++++
 webui/src/pages/WorldPage.module.css          | 179 ++++++++++++++
 webui/src/pages/WorldPage.tsx                 | 226 ++++++++++++++++++
 8 files changed, 1077 insertions(+), 74 deletions(-)
 create mode 100644 webui/src/pages/CharactersPage.module.css
 create mode 100644 webui/src/pages/CharactersPage.tsx
 create mode 100644 webui/src/pages/WorldPage.module.css
 create mode 100644 webui/src/pages/WorldPage.tsx

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index c4a103b0..7a9a75c1 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -27,6 +27,8 @@ const ChapterReviewBanner = lazy(() => import('./components/ChapterReviewBanner'
 const ExportDialog = lazy(() => import('./components/ExportDialog'));
 const OverviewPage = lazy(() => import('./pages/OverviewPage'));
 const SessionsPage = lazy(() => import('./pages/SessionsPage'));
+const WorldPage = lazy(() => import('./pages/WorldPage'));
+const CharactersPage = lazy(() => import('./pages/CharactersPage'));
 
 export function shouldReportWorldbuildingPartialFailure(
   overviewLoaded: boolean,
@@ -291,6 +293,22 @@ function AppInner() {
     );
   }
 
+  if (state.currentPage === 'world' && state.worldId) {
+    return inDesktopShell(
+      <Suspense fallback={<Skeleton />}>
+        <WorldPage worldId={state.worldId} />
+      </Suspense>,
+    );
+  }
+
+  if (state.currentPage === 'characters' && state.worldId) {
+    return inDesktopShell(
+      <Suspense fallback={<Skeleton />}>
+        <CharactersPage worldId={state.worldId} />
+      </Suspense>,
+    );
+  }
+
   if (
     state.appPhase === 'no_agent' &&
     !shouldRenderSessionsPage(state.currentPage, state.appPhase)
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 8c11c847..25fe5bad 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -1,14 +1,17 @@
 import { useState } from 'react';
-import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
 import { worldbuildingApi } from '../api/worldbuilding';
+import { AppStateProvider } from '../AppState';
 import DetailPane from '../components/layout/DetailPane';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
 import { useResource } from '../hooks/useResource';
+import CharactersPage from '../pages/CharactersPage';
 import OverviewPage from '../pages/OverviewPage';
 import { selectWorldMetrics } from '../pages/selectors';
+import WorldPage from '../pages/WorldPage';
 
 vi.mock('../api/client', () => ({
   api: {
@@ -17,11 +20,23 @@ vi.mock('../api/client', () => ({
     listScenes: vi.fn(),
     listWorkspaceFiles: vi.fn(),
     getStoryOverview: vi.fn(),
+    getWorldDetail: vi.fn(),
+    fetchAgentDetail: vi.fn(),
+    fetchDiaries: vi.fn(),
+    fetchRelations: vi.fn(),
+    createAgent: vi.fn(),
   },
 }));
 
 vi.mock('../api/worldbuilding', () => ({
-  worldbuildingApi: { getDashboard: vi.fn() },
+  worldbuildingApi: {
+    getDashboard: vi.fn(),
+    listLocations: vi.fn(),
+    listKnowledge: vi.fn(),
+    listFactions: vi.fn(),
+    getTimeline: vi.fn(),
+    listGraphEntities: vi.fn(),
+  },
 }));
 
 type Deferred<T> = {
@@ -519,3 +534,158 @@ describe('Overview page', () => {
     expect(screen.queryByText('Recent activity')).toBeNull();
   });
 });
+
+describe('World page', () => {
+  it('keeps world detail visible when the graph request fails', async () => {
+    vi.mocked(api.getWorldDetail).mockResolvedValue({
+      ok: true,
+      world: {
+        id: 'world-1',
+        name: 'Starfall City',
+        description: 'A city rebuilt after the long night.',
+        created_at: '2026-06-01T00:00:00Z',
+        stats: { agents: 2, chapters: 1, scenes: 3, open_foreshadowing: 0, active_secrets: 0 },
+      },
+    });
+    vi.mocked(worldbuildingApi.listLocations).mockResolvedValue({
+      ok: true,
+      locations: [],
+      items: [],
+    });
+    vi.mocked(worldbuildingApi.listFactions).mockResolvedValue({
+      ok: true,
+      factions: [],
+      items: [],
+    });
+    vi.mocked(worldbuildingApi.listKnowledge).mockResolvedValue({
+      ok: true,
+      knowledge: [],
+      items: [],
+    });
+    vi.mocked(worldbuildingApi.getTimeline).mockResolvedValue({
+      ok: true,
+      current_time: { day: 1, period: 1, label: 'First dawn' },
+      events: [],
+      items: [],
+    });
+    vi.mocked(worldbuildingApi.listGraphEntities).mockRejectedValue(new Error('Graph unavailable'));
+
+    render(<WorldPage worldId="world-1" />);
+
+    expect(await screen.findByRole('heading', { name: 'Starfall City' })).toBeDefined();
+    expect(screen.getByText('A city rebuilt after the long night.')).toBeDefined();
+    expect(await screen.findByText('Graph unavailable')).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Retry graph' })).toBeDefined();
+  });
+
+  it('shows honest empty states for endpoint-backed world sections', async () => {
+    vi.mocked(api.getWorldDetail).mockResolvedValue({
+      ok: true,
+      world: {
+        id: 'world-1',
+        name: 'Blank World',
+        description: '',
+        created_at: '2026-06-01T00:00:00Z',
+        stats: { agents: 0, chapters: 0, scenes: 0, open_foreshadowing: 0, active_secrets: 0 },
+      },
+    });
+    vi.mocked(worldbuildingApi.listLocations).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(worldbuildingApi.listFactions).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(worldbuildingApi.listKnowledge).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(worldbuildingApi.getTimeline).mockResolvedValue({
+      ok: true,
+      current_time: { day: 1, period: 1, label: 'Day 1' },
+      items: [],
+    });
+    vi.mocked(worldbuildingApi.listGraphEntities).mockResolvedValue({ ok: true, items: [] });
+
+    render(<WorldPage worldId="world-1" />);
+
+    expect(await screen.findByText('No locations yet.')).toBeDefined();
+    expect(screen.getByText('No factions yet.')).toBeDefined();
+    expect(screen.getByText('No knowledge records yet.')).toBeDefined();
+    expect(screen.getByText('No timeline events yet.')).toBeDefined();
+    expect(screen.getByText('No graph entities yet.')).toBeDefined();
+  });
+});
+
+describe('Characters page', () => {
+  const lin = { id: 'lin', name: 'Lin', display_name: 'Lin', kind: 'character' };
+  const sora = { id: 'sora', name: 'Sora', display_name: 'Sora', kind: 'character' };
+
+  function detail(id: string, name: string) {
+    return {
+      ok: true as const,
+      agent: {
+        id,
+        world_id: 'world-1',
+        name,
+        display_name: name,
+        kind: 'character',
+        created_at: '2026-06-01T00:00:00Z',
+        updated_at: '2026-06-01T00:00:00Z',
+        character_card: { version: 1, core_traits: [], identity: `${name} identity` },
+      },
+    };
+  }
+
+  it('loads selected detail once and retains selection after list refresh', async () => {
+    vi.mocked(api.listAgents).mockClear();
+    vi.mocked(api.fetchAgentDetail).mockClear();
+    vi.mocked(api.fetchDiaries).mockClear();
+    vi.mocked(api.fetchRelations).mockClear();
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [lin, sora] });
+    vi.mocked(api.fetchAgentDetail).mockImplementation((_worldId, agentId) =>
+      Promise.resolve(detail(agentId, agentId === 'lin' ? 'Lin' : 'Sora')),
+    );
+    vi.mocked(api.fetchDiaries).mockResolvedValue({ ok: true, diaries: [] });
+    vi.mocked(api.fetchRelations).mockResolvedValue({ ok: true, relations: [] });
+
+    render(<CharactersPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Sora/ }));
+    expect(await screen.findByRole('heading', { name: 'Sora' })).toBeDefined();
+    expect(screen.queryByText('Not set')).toBeNull();
+    expect(api.fetchAgentDetail).toHaveBeenCalledTimes(1);
+
+    fireEvent.click(screen.getByRole('button', { name: 'Refresh characters' }));
+
+    await waitFor(() => expect(api.listAgents).toHaveBeenCalledTimes(2));
+    expect(screen.getByRole('option', { name: /Sora/ })).toHaveAttribute('aria-selected', 'true');
+    expect(api.fetchAgentDetail).toHaveBeenCalledTimes(1);
+  });
+
+  it('shows an honest empty state without loading character detail', async () => {
+    vi.mocked(api.fetchAgentDetail).mockClear();
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    render(<CharactersPage worldId="world-1" />);
+
+    expect(await screen.findByRole('heading', { name: 'No characters yet' })).toBeDefined();
+    expect(api.fetchAgentDetail).not.toHaveBeenCalled();
+  });
+
+  it('refreshes only the character list after creation', async () => {
+    vi.mocked(api.listAgents).mockClear();
+    vi.mocked(api.fetchAgentDetail).mockClear();
+    vi.mocked(api.fetchDiaries).mockClear();
+    vi.mocked(api.fetchRelations).mockClear();
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [lin] });
+    vi.mocked(api.createAgent).mockResolvedValue({ ok: true, agent_id: 'new-agent', name: 'Mira' });
+
+    render(
+      <AppStateProvider>
+        <CharactersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Create character' }));
+    const dialog = screen.getByRole('dialog', { name: 'Create character' });
+    fireEvent.change(within(dialog).getByLabelText('Character name'), {
+      target: { value: 'Mira' },
+    });
+    fireEvent.click(within(dialog).getByRole('button', { name: 'Create character' }));
+
+    await waitFor(() => expect(api.listAgents).toHaveBeenCalledTimes(2));
+    expect(api.fetchAgentDetail).not.toHaveBeenCalled();
+    expect(api.fetchDiaries).not.toHaveBeenCalled();
+    expect(api.fetchRelations).not.toHaveBeenCalled();
+  });
+});
diff --git a/webui/src/components/Inspector/AgentCardView.tsx b/webui/src/components/Inspector/AgentCardView.tsx
index fd5d3938..e0e30f83 100644
--- a/webui/src/components/Inspector/AgentCardView.tsx
+++ b/webui/src/components/Inspector/AgentCardView.tsx
@@ -2,24 +2,19 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import { ArrowLeft, Pencil } from 'lucide-react';
 import { api } from '../../api/client';
 import type { AgentDetail } from '../../api/types';
-import { useAppState } from '../../AppState';
 import AgentAvatar from '../AgentAvatar';
 import AgentCardEdit from './AgentCardEdit';
 import styles from './AgentCardView.module.css';
 import AgentImageGallery from './AgentImageGallery';
 
 interface Props {
+  worldId: string;
   agentId: string;
   onClose: () => void;
   onViewPrompt?: () => void;
 }
 
-function fallback(value: string | number | null | undefined) {
-  return value || 'Not set';
-}
-
-export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props) {
-  const { state } = useAppState();
+export default function AgentCardView({ worldId, agentId, onClose, onViewPrompt }: Props) {
   const [detail, setDetail] = useState<AgentDetail | null>(null);
   const [editMode, setEditMode] = useState(false);
   const [loading, setLoading] = useState(true);
@@ -27,14 +22,13 @@ export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props)
   const abortRef = useRef<AbortController | undefined>(undefined);
 
   const load = useCallback(async () => {
-    if (!state.worldId) return;
     abortRef.current?.abort();
     const controller = new AbortController();
     abortRef.current = controller;
     setLoading(true);
     setError(null);
     try {
-      const res = await api.fetchAgentDetail(state.worldId, agentId);
+      const res = await api.fetchAgentDetail(worldId, agentId);
       if (!controller.signal.aborted) {
         setDetail(res.agent);
         setLoading(false);
@@ -45,7 +39,7 @@ export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props)
         setLoading(false);
       }
     }
-  }, [agentId, state.worldId]);
+  }, [agentId, worldId]);
 
   useEffect(() => {
     load();
@@ -68,10 +62,9 @@ export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props)
   if (!detail) return <div className={styles.container}>Agent not found</div>;
 
   if (editMode) {
-    if (!state.worldId) return <div className={styles.container}>No world selected</div>;
     return (
       <AgentCardEdit
-        worldId={state.worldId}
+        worldId={worldId}
         agentId={agentId}
         detail={detail}
         onSave={(updated) => {
@@ -112,47 +105,45 @@ export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props)
         <div className={styles.profileText}>
           <h3>{displayName}</h3>
           <span>{detail.kind}</span>
-          <p>{cc.identity || cc.appearance || 'Character profile ready for worldbuilding context.'}</p>
+          {cc.identity || cc.appearance ? <p>{cc.identity || cc.appearance}</p> : null}
         </div>
       </section>
 
-      {state.worldId && (
-        <section className={styles.section}>
-          <AgentImageGallery
-            worldId={state.worldId}
-            agentId={agentId}
-            imageType="avatar"
-            images={images.avatar}
-            onChanged={load}
-          />
-        </section>
-      )}
-
-      {state.worldId && (
-        <section className={styles.section}>
-          <AgentImageGallery
-            worldId={state.worldId}
-            agentId={agentId}
-            imageType="design"
-            images={images.design}
-            onChanged={load}
-          />
-        </section>
-      )}
-
       <section className={styles.section}>
-        <h4>Basics</h4>
-        <div className={styles.fieldRow}>
-          <span>Age: {fallback(cc.age)}</span>
-          <span>Gender: {fallback(cc.gender)}</span>
-          <span>Race: {fallback(cc.race)}</span>
-          <span>Identity: {fallback(cc.identity)}</span>
-        </div>
+        <AgentImageGallery
+          worldId={worldId}
+          agentId={agentId}
+          imageType="avatar"
+          images={images.avatar}
+          onChanged={load}
+        />
       </section>
 
       <section className={styles.section}>
-        <h4>Core Traits</h4>
-        {cc.core_traits?.length ? (
+        <AgentImageGallery
+          worldId={worldId}
+          agentId={agentId}
+          imageType="design"
+          images={images.design}
+          onChanged={load}
+        />
+      </section>
+
+      {cc.age !== undefined || cc.gender || cc.race || cc.identity ? (
+        <section className={styles.section}>
+          <h4>Basics</h4>
+          <div className={styles.fieldRow}>
+            {cc.age !== undefined ? <span>Age: {cc.age}</span> : null}
+            {cc.gender ? <span>Gender: {cc.gender}</span> : null}
+            {cc.race ? <span>Race: {cc.race}</span> : null}
+            {cc.identity ? <span>Identity: {cc.identity}</span> : null}
+          </div>
+        </section>
+      ) : null}
+
+      {cc.core_traits?.length ? (
+        <section className={styles.section}>
+          <h4>Core Traits</h4>
           <div className={styles.tags}>
             {cc.core_traits.map((trait) => (
               <span key={trait} className={styles.tag}>
@@ -160,10 +151,8 @@ export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props)
               </span>
             ))}
           </div>
-        ) : (
-          <p>Not set</p>
-        )}
-      </section>
+        </section>
+      ) : null}
 
       {cc.emotional_tendency && (
         <section className={styles.section}>
@@ -172,25 +161,33 @@ export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props)
         </section>
       )}
 
-      <section className={styles.section}>
-        <h4>Speaking Style</h4>
-        <p>{fallback(cc.speaking_style)}</p>
-      </section>
+      {cc.speaking_style ? (
+        <section className={styles.section}>
+          <h4>Speaking Style</h4>
+          <p>{cc.speaking_style}</p>
+        </section>
+      ) : null}
 
-      <section className={styles.section}>
-        <h4>Core Desire</h4>
-        <p>{fallback(cc.core_desire)}</p>
-      </section>
+      {cc.core_desire ? (
+        <section className={styles.section}>
+          <h4>Core Desire</h4>
+          <p>{cc.core_desire}</p>
+        </section>
+      ) : null}
 
-      <section className={styles.section}>
-        <h4>Deep Fear</h4>
-        <p>{fallback(cc.deep_fear)}</p>
-      </section>
+      {cc.deep_fear ? (
+        <section className={styles.section}>
+          <h4>Deep Fear</h4>
+          <p>{cc.deep_fear}</p>
+        </section>
+      ) : null}
 
-      <section className={styles.section}>
-        <h4>Daily Goal</h4>
-        <p>{fallback(cc.daily_goal)}</p>
-      </section>
+      {cc.daily_goal ? (
+        <section className={styles.section}>
+          <h4>Daily Goal</h4>
+          <p>{cc.daily_goal}</p>
+        </section>
+      ) : null}
 
       {cc.background && (
         <section className={styles.section}>
@@ -199,10 +196,12 @@ export default function AgentCardView({ agentId, onClose, onViewPrompt }: Props)
         </section>
       )}
 
-      <section className={styles.section}>
-        <h4>Knowledge Scope</h4>
-        <p>{fallback(cc.knowledge_scope)}</p>
-      </section>
+      {cc.knowledge_scope ? (
+        <section className={styles.section}>
+          <h4>Knowledge Scope</h4>
+          <p>{cc.knowledge_scope}</p>
+        </section>
+      ) : null}
 
       {cc.appearance && (
         <section className={styles.section}>
diff --git a/webui/src/components/Inspector/AgentsInspector.tsx b/webui/src/components/Inspector/AgentsInspector.tsx
index 9d0c7a35..106f4d03 100644
--- a/webui/src/components/Inspector/AgentsInspector.tsx
+++ b/webui/src/components/Inspector/AgentsInspector.tsx
@@ -30,9 +30,10 @@ export default function AgentsInspector() {
   const [showCreateAgent, setShowCreateAgent] = useState(false);
   const [promptAgentId, setPromptAgentId] = useState<string | null>(null);
 
-  if (selectedAgentId) {
+  if (selectedAgentId && state.worldId) {
     return (
       <AgentCardView
+        worldId={state.worldId}
         agentId={selectedAgentId}
         onClose={() => setSelectedAgentId(null)}
         onViewPrompt={() => setPromptAgentId(selectedAgentId)}
@@ -45,7 +46,9 @@ export default function AgentsInspector() {
       <>
         <section className={styles.section}>
           <div className={styles.sectionTitle}>角色声音</div>
-          <p className={styles.muted}>当前世界还没有角色。创建第一个角色后，工作台会用真实后端数据展示声音、提示词和知识边界。</p>
+          <p className={styles.muted}>
+            当前世界还没有角色。创建第一个角色后，工作台会用真实后端数据展示声音、提示词和知识边界。
+          </p>
           {state.worldId && (
             <button
               className={styles.entryButton}
diff --git a/webui/src/pages/CharactersPage.module.css b/webui/src/pages/CharactersPage.module.css
new file mode 100644
index 00000000..59de3019
--- /dev/null
+++ b/webui/src/pages/CharactersPage.module.css
@@ -0,0 +1,196 @@
+.workspace {
+  display: grid;
+  grid-template-columns: 260px minmax(420px, 1fr) 280px;
+  height: 100%;
+  min-height: 0;
+  background: #f7f9fc;
+  color: #17213b;
+}
+.listPane,
+.contextPane {
+  min-height: 0;
+  overflow: auto;
+  background: #fff;
+}
+.listPane {
+  display: flex;
+  flex-direction: column;
+  border-right: 1px solid #dfe6ef;
+}
+.contextPane {
+  padding: 16px;
+  border-left: 1px solid #dfe6ef;
+}
+.detailPane {
+  min-width: 0;
+  overflow: auto;
+}
+.listPane > header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 16px;
+}
+.listPane header span {
+  color: #667085;
+  font-size: 11px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+.listPane h1 {
+  margin-top: 2px;
+  font-size: 19px;
+}
+.listPane header button {
+  display: grid;
+  width: 32px;
+  height: 32px;
+  place-items: center;
+  border: 1px solid #d7dfeb;
+  border-radius: 6px;
+  background: #fff;
+  color: #153981;
+  cursor: pointer;
+}
+.refresh {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  margin: 0 16px 10px;
+  padding: 7px 9px;
+  border: 1px solid #dfe6ef;
+  border-radius: 6px;
+  background: #fff;
+  color: #536178;
+  cursor: pointer;
+  font-size: 12px;
+}
+.refresh svg {
+  width: 13px;
+}
+.listItem {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+}
+.listItem div {
+  display: flex;
+  min-width: 0;
+  flex-direction: column;
+}
+.listItem strong {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.listItem span {
+  color: #7a8699;
+  font-size: 11px;
+}
+.listPane footer {
+  margin-top: auto;
+  padding: 12px 16px;
+  border-top: 1px solid #edf0f4;
+  color: #7a8699;
+  font-size: 12px;
+}
+.pick,
+.empty {
+  display: grid;
+  max-width: 520px;
+  margin: 15vh auto 0;
+  justify-items: center;
+  padding: 40px;
+  text-align: center;
+}
+.pick svg,
+.empty svg {
+  width: 34px;
+  height: 34px;
+  color: #153981;
+}
+.pick h2,
+.empty h1 {
+  margin: 12px 0 6px;
+  font-size: 20px;
+}
+.pick p,
+.empty p,
+.muted {
+  color: #7a8699;
+}
+.empty button {
+  display: flex;
+  align-items: center;
+  gap: 7px;
+  margin-top: 16px;
+  padding: 9px 13px;
+  border: 0;
+  border-radius: 6px;
+  background: #103687;
+  color: #fff;
+  cursor: pointer;
+}
+.page {
+  height: 100%;
+  overflow: auto;
+  background: #f7f9fc;
+}
+.contextStack {
+  display: grid;
+  gap: 14px;
+}
+.contextSection {
+  padding: 14px;
+  border: 1px solid #dfe6ef;
+  border-radius: 8px;
+}
+.contextSection h2 {
+  margin-bottom: 10px;
+  font-size: 14px;
+}
+.contextSection article {
+  padding: 9px 0;
+  border-bottom: 1px solid #edf0f4;
+}
+.contextSection article:last-child {
+  border-bottom: 0;
+}
+.contextSection p {
+  margin: 0;
+  line-height: 1.45;
+}
+.contextSection small {
+  color: #7a8699;
+}
+.contextError {
+  display: grid;
+  gap: 8px;
+  color: #9b3a25;
+}
+.contextError button {
+  width: max-content;
+  border: 0;
+  background: transparent;
+  color: #153981;
+  cursor: pointer;
+  font-weight: 700;
+}
+@media (max-width: 1050px) {
+  .workspace {
+    grid-template-columns: 230px 1fr;
+  }
+  .contextPane {
+    display: none;
+  }
+}
+@media (max-width: 700px) {
+  .workspace {
+    grid-template-columns: 1fr;
+  }
+  .listPane {
+    max-height: 42%;
+    border-right: 0;
+    border-bottom: 1px solid #dfe6ef;
+  }
+}
diff --git a/webui/src/pages/CharactersPage.tsx b/webui/src/pages/CharactersPage.tsx
new file mode 100644
index 00000000..d8efeefb
--- /dev/null
+++ b/webui/src/pages/CharactersPage.tsx
@@ -0,0 +1,212 @@
+import { useState } from 'react';
+import { Plus, RefreshCw, Users } from 'lucide-react';
+import { api } from '../api/client';
+import type { DiaryEntry, RelationEntry, WorldAgent } from '../api/types';
+import AgentAvatar from '../components/AgentAvatar';
+import AgentCardView from '../components/Inspector/AgentCardView';
+import CreateAgentModal from '../components/Inspector/CreateAgentModal';
+import PageState from '../components/layout/PageState';
+import ResourceList from '../components/layout/ResourceList';
+import { useResource } from '../hooks/useResource';
+import styles from './CharactersPage.module.css';
+
+interface CharactersPageProps {
+  worldId: string;
+}
+
+export default function CharactersPage({ worldId }: CharactersPageProps) {
+  const agents = useResource(`characters:${worldId}`, () => api.listAgents(worldId));
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [showCreate, setShowCreate] = useState(false);
+  const items = agents.data?.agents ?? [];
+  const selected = selectedId && items.some((item) => item.id === selectedId) ? selectedId : null;
+
+  if (!agents.data) {
+    return (
+      <PageState
+        loading={agents.status === 'loading'}
+        loadingLabel="Loading characters"
+        error={agents.error}
+        onRetry={agents.retry}
+      />
+    );
+  }
+
+  if (items.length === 0) {
+    return (
+      <main className={styles.page}>
+        <section className={styles.empty}>
+          <Users aria-hidden="true" />
+          <h1>No characters yet</h1>
+          <p>Create a character to begin defining a voice and identity.</p>
+          <button type="button" onClick={() => setShowCreate(true)}>
+            <Plus aria-hidden="true" />
+            Create character
+          </button>
+        </section>
+        {showCreate ? (
+          <CreateAgentModal
+            worldId={worldId}
+            onClose={() => setShowCreate(false)}
+            onCreated={agents.retry}
+          />
+        ) : null}
+      </main>
+    );
+  }
+
+  return (
+    <main className={styles.workspace}>
+      <aside className={styles.listPane}>
+        <header>
+          <div>
+            <span>World cast</span>
+            <h1>Characters</h1>
+          </div>
+          <button type="button" onClick={() => setShowCreate(true)} aria-label="Create character">
+            <Plus aria-hidden="true" />
+          </button>
+        </header>
+        <button
+          className={styles.refresh}
+          type="button"
+          onClick={agents.retry}
+          aria-label="Refresh characters"
+        >
+          <RefreshCw aria-hidden="true" />
+          Refresh
+        </button>
+        <ResourceList
+          items={items}
+          selectedId={selected}
+          getId={(item) => item.id}
+          onSelect={setSelectedId}
+          ariaLabel="Characters"
+          renderItem={(item) => <CharacterListItem agent={item} />}
+        />
+        <footer>
+          {items.length} {items.length === 1 ? 'character' : 'characters'}
+        </footer>
+      </aside>
+
+      <section className={styles.detailPane}>
+        {selected ? (
+          <AgentCardView worldId={worldId} agentId={selected} onClose={() => setSelectedId(null)} />
+        ) : (
+          <div className={styles.pick}>
+            <Users aria-hidden="true" />
+            <h2>Select a character</h2>
+            <p>Choose a character to inspect its endpoint-backed profile and images.</p>
+          </div>
+        )}
+      </section>
+
+      <aside className={styles.contextPane}>
+        {selected ? (
+          <CharacterContext worldId={worldId} agentId={selected} />
+        ) : (
+          <p className={styles.muted}>Character diaries and explicit relationships appear here.</p>
+        )}
+      </aside>
+      {showCreate ? (
+        <CreateAgentModal
+          worldId={worldId}
+          onClose={() => setShowCreate(false)}
+          onCreated={agents.retry}
+        />
+      ) : null}
+    </main>
+  );
+}
+
+function CharacterListItem({ agent }: { agent: WorldAgent }) {
+  const name = agent.display_name || agent.name;
+  return (
+    <div className={styles.listItem}>
+      <AgentAvatar name={name} src={agent.avatar_url} size="sm" />
+      <div>
+        <strong>{name}</strong>
+        {agent.kind ? <span>{agent.kind}</span> : null}
+      </div>
+    </div>
+  );
+}
+
+function CharacterContext({ worldId, agentId }: { worldId: string; agentId: string }) {
+  const diaries = useResource(`character:${worldId}:${agentId}:diaries`, () =>
+    api.fetchDiaries(worldId, agentId),
+  );
+  const relations = useResource(`character:${worldId}:${agentId}:relations`, () =>
+    api.fetchRelations(worldId, agentId),
+  );
+  return (
+    <div className={styles.contextStack}>
+      <ContextSection
+        title="Recent diaries"
+        resource={diaries}
+        retryLabel="Retry diaries"
+        items={(data) => data.diaries}
+        render={(item: DiaryEntry) => (
+          <article key={item.id}>
+            <p>{item.content}</p>
+            {item.world_time ? <small>{item.world_time}</small> : null}
+          </article>
+        )}
+        empty="No diary entries yet."
+      />
+      <ContextSection
+        title="Relationships"
+        resource={relations}
+        retryLabel="Retry relationships"
+        items={(data) => data.relations}
+        render={(item: RelationEntry) => (
+          <article key={`${item.agent_id}:${item.target_id}`}>
+            <strong>{item.relation_type}</strong>
+            {item.description ? <p>{item.description}</p> : null}
+          </article>
+        )}
+        empty="No explicit relationships yet."
+      />
+    </div>
+  );
+}
+
+function ContextSection<TData, TItem>({
+  title,
+  resource,
+  retryLabel,
+  items,
+  render,
+  empty,
+}: {
+  title: string;
+  resource: ReturnType<typeof useResource<TData>>;
+  retryLabel: string;
+  items(data: TData): TItem[];
+  render(item: TItem): React.ReactNode;
+  empty: string;
+}) {
+  return (
+    <section className={styles.contextSection}>
+      <h2>{title}</h2>
+      {resource.status === 'loading' && !resource.data ? (
+        <p className={styles.muted}>Loading...</p>
+      ) : null}
+      {resource.error && !resource.data ? (
+        <div className={styles.contextError} role="alert">
+          <span>{resource.error.message}</span>
+          <button type="button" onClick={resource.retry} aria-label={retryLabel}>
+            Retry
+          </button>
+        </div>
+      ) : null}
+      {resource.data ? (
+        items(resource.data).length ? (
+          items(resource.data).slice(0, 8).map(render)
+        ) : (
+          <p className={styles.muted}>{empty}</p>
+        )
+      ) : null}
+    </section>
+  );
+}
diff --git a/webui/src/pages/WorldPage.module.css b/webui/src/pages/WorldPage.module.css
new file mode 100644
index 00000000..403b9338
--- /dev/null
+++ b/webui/src/pages/WorldPage.module.css
@@ -0,0 +1,179 @@
+.page {
+  height: 100%;
+  overflow: auto;
+  padding: 20px;
+  background: #f7f9fc;
+  color: #17213b;
+}
+.heading {
+  display: flex;
+  gap: 14px;
+  padding: 20px;
+  border: 1px solid #dfe6ef;
+  border-radius: 10px;
+  background: #fff;
+}
+.heading span {
+  color: #667085;
+  font-size: 12px;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+.heading h1 {
+  margin: 3px 0 6px;
+  font-size: 24px;
+}
+.heading p {
+  margin: 0;
+  color: #59667c;
+  line-height: 1.55;
+}
+.titleIcon {
+  display: grid;
+  width: 42px;
+  height: 42px;
+  flex: 0 0 auto;
+  place-items: center;
+  border-radius: 9px;
+  background: #eaf0ff;
+  color: #123b91;
+}
+.stats {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  margin: 14px 0;
+}
+.stats article {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 14px 16px;
+  border: 1px solid #dfe6ef;
+  border-radius: 9px;
+  background: #fff;
+  color: #153981;
+}
+.stats article div {
+  display: flex;
+  flex-direction: column;
+}
+.stats strong {
+  font-size: 20px;
+}
+.stats span {
+  color: #667085;
+  font-size: 12px;
+}
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 14px;
+}
+.panel {
+  min-height: 220px;
+  padding: 16px;
+  border: 1px solid #dfe6ef;
+  border-radius: 9px;
+  background: #fff;
+}
+.wide {
+  grid-column: 1 / -1;
+  min-height: 140px;
+}
+.panel > header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  margin-bottom: 14px;
+  color: #153981;
+}
+.panel h2 {
+  font-size: 15px;
+  color: #17213b;
+}
+.cards {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 9px;
+}
+.cards article {
+  padding: 12px;
+  border: 1px solid #e3e8f0;
+  border-radius: 7px;
+}
+.cards p,
+.rows p,
+.timeline p {
+  margin: 5px 0 0;
+  color: #667085;
+  line-height: 1.45;
+}
+.rows article,
+.timeline article {
+  padding: 10px 4px;
+  border-bottom: 1px solid #edf0f4;
+}
+.rows small {
+  color: #7b86a0;
+}
+.currentTime {
+  margin-bottom: 6px;
+  color: #153981;
+  font-size: 12px;
+  font-weight: 700;
+}
+.timeline strong {
+  color: #153981;
+  font-size: 12px;
+}
+.entityList {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+.entityList span {
+  display: flex;
+  gap: 7px;
+  align-items: center;
+  padding: 8px 10px;
+  border: 1px solid #dfe6ef;
+  border-radius: 7px;
+}
+.entityList small {
+  color: #667085;
+  text-transform: uppercase;
+}
+.empty,
+.loading {
+  margin: 34px 0;
+  color: #7a8699;
+  text-align: center;
+}
+.inlineError {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+  padding: 10px;
+  border: 1px solid #f0d7a6;
+  border-radius: 7px;
+  background: #fff9eb;
+  color: #7a4d0b;
+}
+.inlineError button {
+  border: 0;
+  background: transparent;
+  color: #153981;
+  font-weight: 700;
+  cursor: pointer;
+}
+@media (max-width: 800px) {
+  .grid,
+  .stats {
+    grid-template-columns: 1fr;
+  }
+  .wide {
+    grid-column: auto;
+  }
+}
diff --git a/webui/src/pages/WorldPage.tsx b/webui/src/pages/WorldPage.tsx
new file mode 100644
index 00000000..7bf64cc5
--- /dev/null
+++ b/webui/src/pages/WorldPage.tsx
@@ -0,0 +1,226 @@
+import { BookOpen, Building2, Clock3, Globe2, Network, Users } from 'lucide-react';
+import { api } from '../api/client';
+import type { GraphEntity, KnowledgeRecord, TimelineEventRecord } from '../api/types';
+import { worldbuildingApi } from '../api/worldbuilding';
+import PageState from '../components/layout/PageState';
+import { useResource, type ResourceState } from '../hooks/useResource';
+import styles from './WorldPage.module.css';
+
+interface WorldPageProps {
+  worldId: string;
+}
+
+function SectionState<T>({
+  resource,
+  retryLabel,
+  children,
+}: {
+  resource: ResourceState<T>;
+  retryLabel: string;
+  children: (data: T) => React.ReactNode;
+}) {
+  if (resource.data) return <>{children(resource.data)}</>;
+  if (resource.status === 'error') {
+    return (
+      <div className={styles.inlineError} role="alert">
+        <span>{resource.error?.message}</span>
+        <button type="button" onClick={resource.retry} aria-label={retryLabel}>
+          Retry
+        </button>
+      </div>
+    );
+  }
+  return <div className={styles.loading}>Loading...</div>;
+}
+
+export default function WorldPage({ worldId }: WorldPageProps) {
+  const detail = useResource(`world:${worldId}`, () => api.getWorldDetail(worldId));
+  const locations = useResource(`world:${worldId}:locations`, () =>
+    worldbuildingApi.listLocations(worldId),
+  );
+  const factions = useResource(`world:${worldId}:factions`, () =>
+    worldbuildingApi.listFactions(worldId),
+  );
+  const knowledge = useResource(`world:${worldId}:knowledge`, () =>
+    worldbuildingApi.listKnowledge(worldId),
+  );
+  const timeline = useResource(`world:${worldId}:timeline`, () =>
+    worldbuildingApi.getTimeline(worldId),
+  );
+  const graph = useResource(`world:${worldId}:graph`, () =>
+    worldbuildingApi.listGraphEntities(worldId),
+  );
+
+  if (!detail.data) {
+    return (
+      <PageState
+        loading={detail.status === 'loading'}
+        loadingLabel="Loading world"
+        error={detail.error}
+        onRetry={detail.retry}
+      />
+    );
+  }
+
+  const world = detail.data.world;
+  return (
+    <main className={styles.page}>
+      <header className={styles.heading}>
+        <div className={styles.titleIcon}>
+          <Globe2 aria-hidden="true" />
+        </div>
+        <div>
+          <span>World setting</span>
+          <h1>{world.name}</h1>
+          {world.description ? <p>{world.description}</p> : null}
+        </div>
+      </header>
+
+      <section className={styles.stats} aria-label="World totals">
+        <Stat label="Characters" value={world.stats.agents} icon={Users} />
+        <Stat label="Chapters" value={world.stats.chapters} icon={BookOpen} />
+        <Stat label="Scenes" value={world.stats.scenes} icon={Clock3} />
+      </section>
+
+      <div className={styles.grid}>
+        <Panel title="Locations" icon={Building2}>
+          <SectionState resource={locations} retryLabel="Retry locations">
+            {(data) => {
+              const items = data.items ?? [];
+              return items.length ? (
+                <div className={styles.cards}>
+                  {items.map((item) => (
+                    <article key={item.id}>
+                      <strong>{item.name}</strong>
+                      {item.description ? <p>{item.description}</p> : null}
+                    </article>
+                  ))}
+                </div>
+              ) : (
+                <Empty text="No locations yet." />
+              );
+            }}
+          </SectionState>
+        </Panel>
+        <Panel title="Factions" icon={Users}>
+          <SectionState resource={factions} retryLabel="Retry factions">
+            {(data) => {
+              const items = data.items ?? [];
+              return items.length ? (
+                <div className={styles.cards}>
+                  {items.map((item) => (
+                    <article key={item.id}>
+                      <strong>{item.name}</strong>
+                      {item.description ? <p>{item.description}</p> : null}
+                    </article>
+                  ))}
+                </div>
+              ) : (
+                <Empty text="No factions yet." />
+              );
+            }}
+          </SectionState>
+        </Panel>
+        <Panel title="Knowledge" icon={BookOpen}>
+          <SectionState resource={knowledge} retryLabel="Retry knowledge">
+            {(data) => <KnowledgeList items={data.items ?? []} />}
+          </SectionState>
+        </Panel>
+        <Panel title="Timeline" icon={Clock3}>
+          <SectionState resource={timeline} retryLabel="Retry timeline">
+            {(data) => <Timeline items={data.items ?? []} currentTime={data.current_time?.label} />}
+          </SectionState>
+        </Panel>
+        <Panel title="Knowledge graph" icon={Network} wide>
+          <SectionState resource={graph} retryLabel="Retry graph">
+            {(data) => <GraphList items={data.items ?? []} />}
+          </SectionState>
+        </Panel>
+      </div>
+    </main>
+  );
+}
+
+function Stat({ label, value, icon: Icon }: { label: string; value: number; icon: typeof Users }) {
+  return (
+    <article>
+      <Icon aria-hidden="true" />
+      <div>
+        <strong>{value}</strong>
+        <span>{label}</span>
+      </div>
+    </article>
+  );
+}
+function Panel({
+  title,
+  icon: Icon,
+  wide = false,
+  children,
+}: {
+  title: string;
+  icon: typeof Users;
+  wide?: boolean;
+  children: React.ReactNode;
+}) {
+  return (
+    <section className={`${styles.panel} ${wide ? styles.wide : ''}`}>
+      <header>
+        <Icon aria-hidden="true" />
+        <h2>{title}</h2>
+      </header>
+      {children}
+    </section>
+  );
+}
+function Empty({ text }: { text: string }) {
+  return <p className={styles.empty}>{text}</p>;
+}
+function KnowledgeList({ items }: { items: KnowledgeRecord[] }) {
+  return items.length ? (
+    <div className={styles.rows}>
+      {items.map((item) => (
+        <article key={item.id}>
+          <strong>{item.category}</strong>
+          <p>{item.content}</p>
+          {item.tags?.length ? <small>{item.tags.join(' · ')}</small> : null}
+        </article>
+      ))}
+    </div>
+  ) : (
+    <Empty text="No knowledge records yet." />
+  );
+}
+function Timeline({ items, currentTime }: { items: TimelineEventRecord[]; currentTime?: string }) {
+  return (
+    <>
+      {currentTime ? <div className={styles.currentTime}>{currentTime}</div> : null}
+      {items.length ? (
+        <div className={styles.timeline}>
+          {items.map((item) => (
+            <article key={item.id}>
+              <strong>{item.world_time}</strong>
+              <p>{item.description}</p>
+            </article>
+          ))}
+        </div>
+      ) : (
+        <Empty text="No timeline events yet." />
+      )}
+    </>
+  );
+}
+function GraphList({ items }: { items: GraphEntity[] }) {
+  return items.length ? (
+    <div className={styles.entityList}>
+      {items.map((item) => (
+        <span key={item.id}>
+          <small>{item.type}</small>
+          {item.name}
+        </span>
+      ))}
+    </div>
+  ) : (
+    <Empty text="No graph entities yet." />
+  );
+}

From c38a5b7bb8335c5700845a01dcc6b4aa22dbae0b Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 12:36:07 +0800
Subject: [PATCH 27/49] fix(webui): complete character resource workspace

---
 webui/src/__tests__/api.test.ts               |  53 ++++++++
 webui/src/__tests__/pages.test.tsx            | 106 ++++++++++++++++
 webui/src/api/client.ts                       |  20 +++
 webui/src/api/types.ts                        |  16 ++-
 .../Inspector/AgentCardView.module.css        |  10 ++
 .../components/Inspector/AgentCardView.tsx    |  14 ++-
 webui/src/pages/CharactersPage.module.css     |  42 ++++++-
 webui/src/pages/CharactersPage.tsx            | 116 +++++++++++++++++-
 8 files changed, 370 insertions(+), 7 deletions(-)

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index 2f3c38f3..ba33626f 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -302,6 +302,59 @@ describe('api client', () => {
     expect(timeline.items).toEqual(timeline.events);
   });
 
+  it('uses the implemented agent memory, voice, and delete endpoints', async () => {
+    vi.mocked(fetch)
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            ok: true,
+            summaries: [
+              {
+                id: 'm1',
+                period_start: 'Day 1',
+                period_end: 'Day 2',
+                summary: 'Kept watch.',
+                source_diary_ids: ['d1'],
+                created_at: '2026-06-20',
+              },
+            ],
+          }),
+          { status: 200 },
+        ),
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({
+            ok: true,
+            voice: {
+              avg_sentence_length: 8.5,
+              sentence_variance: 1.2,
+              question_frequency: 0.1,
+              modifier_ratio: 0.2,
+              sample_count: 4,
+              signature_words: ['steady'],
+              tone_profile: { question_ratio: 0.1 },
+            },
+          }),
+          { status: 200 },
+        ),
+      )
+      .mockResolvedValueOnce(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+    const { api } = await import('../api/client');
+
+    const memory = await api.fetchMemorySummaries('world one', 'agent/two');
+    const voice = await api.fetchAgentVoice('world one', 'agent/two');
+    await api.deleteAgent('world one', 'agent/two');
+
+    expect(memory.summaries[0].summary).toBe('Kept watch.');
+    expect(voice.voice.signature_words).toEqual(['steady']);
+    expect(vi.mocked(fetch).mock.calls.map(([url, init]) => [url, init?.method])).toEqual([
+      ['/api/worldbuilding/world%20one/agents/agent%2Ftwo/memory-summaries', 'GET'],
+      ['/api/worldbuilding/world%20one/agents/agent%2Ftwo/voice', 'GET'],
+      ['/api/worldbuilding/world%20one/agents/agent%2Ftwo', 'DELETE'],
+    ]);
+  });
+
   it('preserves documented file-link target fields', async () => {
     vi.mocked(fetch).mockResolvedValueOnce(
       new Response(
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 25fe5bad..e1f1ffeb 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -1,3 +1,5 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { useState } from 'react';
 import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
@@ -25,6 +27,9 @@ vi.mock('../api/client', () => ({
     fetchDiaries: vi.fn(),
     fetchRelations: vi.fn(),
     createAgent: vi.fn(),
+    fetchMemorySummaries: vi.fn(),
+    fetchAgentVoice: vi.fn(),
+    deleteAgent: vi.fn(),
   },
 }));
 
@@ -640,6 +645,19 @@ describe('Characters page', () => {
     );
     vi.mocked(api.fetchDiaries).mockResolvedValue({ ok: true, diaries: [] });
     vi.mocked(api.fetchRelations).mockResolvedValue({ ok: true, relations: [] });
+    vi.mocked(api.fetchMemorySummaries).mockResolvedValue({ ok: true, summaries: [] });
+    vi.mocked(api.fetchAgentVoice).mockResolvedValue({
+      ok: true,
+      voice: {
+        avg_sentence_length: 8,
+        sentence_variance: 1,
+        question_frequency: 0,
+        modifier_ratio: 0,
+        sample_count: 2,
+        signature_words: [],
+        tone_profile: {},
+      },
+    });
 
     render(<CharactersPage worldId="world-1" />);
     fireEvent.click(await screen.findByRole('option', { name: /Sora/ }));
@@ -663,6 +681,94 @@ describe('Characters page', () => {
     expect(api.fetchAgentDetail).not.toHaveBeenCalled();
   });
 
+  it('renders memory, voice, and real relationship targets independently', async () => {
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [lin, sora] });
+    vi.mocked(api.fetchAgentDetail).mockResolvedValue(detail('lin', 'Lin'));
+    vi.mocked(api.fetchDiaries).mockResolvedValue({ ok: true, diaries: [] });
+    vi.mocked(api.fetchRelations).mockResolvedValue({
+      ok: true,
+      relations: [
+        { agent_id: 'lin', target_id: 'sora', relation_type: 'ally', updated_at: '2026-06-20' },
+        {
+          agent_id: 'lin',
+          target_id: 'missing-agent',
+          relation_type: 'rival',
+          updated_at: '2026-06-20',
+        },
+      ],
+    });
+    vi.mocked(api.fetchMemorySummaries).mockResolvedValue({
+      ok: true,
+      summaries: [
+        {
+          id: 'm1',
+          period_start: 'Day 1',
+          period_end: 'Day 2',
+          summary: 'Guarded the gate.',
+          source_diary_ids: ['d1'],
+          created_at: '2026-06-20',
+        },
+      ],
+    });
+    vi.mocked(api.fetchAgentVoice).mockResolvedValue({
+      ok: true,
+      voice: {
+        avg_sentence_length: 9,
+        sentence_variance: 2,
+        question_frequency: 0.1,
+        modifier_ratio: 0.2,
+        sample_count: 5,
+        signature_words: ['steady'],
+        tone_profile: { question_ratio: 0.1 },
+      },
+    });
+
+    render(<CharactersPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Lin/ }));
+
+    expect(await screen.findByText('Guarded the gate.')).toBeDefined();
+    const relationships = screen.getByRole('heading', { name: 'Relationships' }).closest('section');
+    expect(relationships).not.toBeNull();
+    expect(within(relationships!).getByText('Sora')).toBeDefined();
+    expect(within(relationships!).getByText('missing-agent')).toBeDefined();
+    expect(screen.getByText('steady')).toBeDefined();
+  });
+
+  it('deletes with confirmation, refreshes the list, and selects a surviving neighbor', async () => {
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listAgents)
+      .mockResolvedValueOnce({ ok: true, agents: [lin, sora] })
+      .mockResolvedValueOnce({ ok: true, agents: [lin] });
+    vi.mocked(api.fetchAgentDetail).mockImplementation((_worldId, id) =>
+      Promise.resolve(detail(id, id === 'lin' ? 'Lin' : 'Sora')),
+    );
+    vi.mocked(api.fetchDiaries).mockResolvedValue({ ok: true, diaries: [] });
+    vi.mocked(api.fetchRelations).mockResolvedValue({ ok: true, relations: [] });
+    vi.mocked(api.fetchMemorySummaries).mockResolvedValue({ ok: true, summaries: [] });
+    vi.mocked(api.fetchAgentVoice).mockRejectedValue(new Error('Voice fingerprint not found'));
+    vi.mocked(api.deleteAgent).mockResolvedValue({ ok: true });
+
+    render(<CharactersPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Sora/ }));
+    await screen.findByRole('heading', { name: 'Sora' });
+    fireEvent.click(screen.getByRole('button', { name: 'Delete character' }));
+
+    await waitFor(() => expect(api.deleteAgent).toHaveBeenCalledWith('world-1', 'sora'));
+    await waitFor(() =>
+      expect(screen.getByRole('option', { name: /Lin/ })).toHaveAttribute('aria-selected', 'true'),
+    );
+  });
+
+  it('keeps character context accessible below 1050px', () => {
+    const css = readFileSync(join(process.cwd(), 'src/pages/CharactersPage.module.css'), 'utf8');
+    const responsiveBlock = css.slice(
+      css.indexOf('@media (max-width: 1050px)'),
+      css.indexOf('@media (max-width: 700px)'),
+    );
+    expect(responsiveBlock).not.toMatch(/\.contextPane\s*\{[^}]*display:\s*none/s);
+    expect(responsiveBlock).toMatch(/\.contextPane\s*\{[^}]*grid-column:\s*1\s*\/\s*-1/s);
+  });
+
   it('refreshes only the character list after creation', async () => {
     vi.mocked(api.listAgents).mockClear();
     vi.mocked(api.fetchAgentDetail).mockClear();
diff --git a/webui/src/api/client.ts b/webui/src/api/client.ts
index 4d7e7661..6308b4e7 100644
--- a/webui/src/api/client.ts
+++ b/webui/src/api/client.ts
@@ -29,6 +29,7 @@ import type {
   ForeshadowingListResponse,
   GenerateTitleResponse,
   LlmConfigFull,
+  MemorySummaryListResponse,
   OkResponse,
   OpenWorkspacePathResponse,
   PatchAgentCardResponse,
@@ -49,6 +50,7 @@ import type {
   StoryOverviewResponse,
   UpdateSessionResponse,
   UpdateWorldResponse,
+  VoiceFingerprintResponse,
   WorkflowSummary,
   WorkspaceFileContentResponse,
   WorkspaceFileListResponse,
@@ -329,6 +331,24 @@ export const api = {
       `/api/worldbuilding/${worldId}/agents/${agentId}/relations`,
     ),
 
+  fetchMemorySummaries: (worldId: string, agentId: string) =>
+    request<MemorySummaryListResponse>(
+      'GET',
+      `/api/worldbuilding/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}/memory-summaries`,
+    ),
+
+  fetchAgentVoice: (worldId: string, agentId: string) =>
+    request<VoiceFingerprintResponse>(
+      'GET',
+      `/api/worldbuilding/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}/voice`,
+    ),
+
+  deleteAgent: (worldId: string, agentId: string) =>
+    request<OkResponse>(
+      'DELETE',
+      `/api/worldbuilding/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}`,
+    ),
+
   // Patch other cards
   patchForeshadow: (worldId: string, id: string, fields: Record<string, unknown>) =>
     request<OkResponse>('PATCH', `/api/worldbuilding/${worldId}/foreshadowing/${id}`, { fields }),
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 5888959e..e474da36 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -516,7 +516,6 @@ export interface DiaryListResponse {
 
 export interface MemorySummary {
   id: string;
-  agent_id: string;
   period_start: string;
   period_end: string;
   summary: string;
@@ -524,6 +523,21 @@ export interface MemorySummary {
   created_at: string;
 }
 
+export interface VoiceFingerprint {
+  avg_sentence_length: number;
+  sentence_variance: number;
+  question_frequency: number;
+  modifier_ratio: number;
+  sample_count: number;
+  signature_words: string[];
+  tone_profile: Record<string, number>;
+}
+
+export interface VoiceFingerprintResponse {
+  ok: boolean;
+  voice: VoiceFingerprint;
+}
+
 export interface MemorySummaryListResponse {
   ok: boolean;
   summaries: MemorySummary[];
diff --git a/webui/src/components/Inspector/AgentCardView.module.css b/webui/src/components/Inspector/AgentCardView.module.css
index 6e342ee4..c1402ccc 100644
--- a/webui/src/components/Inspector/AgentCardView.module.css
+++ b/webui/src/components/Inspector/AgentCardView.module.css
@@ -22,6 +22,16 @@
   font-size: 12px;
   font-weight: 800;
 }
+.deleteBtn {
+  padding: 6px 10px;
+  border: 1px solid #efc8c2;
+  border-radius: 5px;
+  background: #fff;
+  color: #a63225;
+  cursor: pointer;
+  font-size: 11px;
+  font-weight: 700;
+}
 
 .backBtn:hover,
 .editBtn:hover {
diff --git a/webui/src/components/Inspector/AgentCardView.tsx b/webui/src/components/Inspector/AgentCardView.tsx
index e0e30f83..1524c87c 100644
--- a/webui/src/components/Inspector/AgentCardView.tsx
+++ b/webui/src/components/Inspector/AgentCardView.tsx
@@ -12,9 +12,16 @@ interface Props {
   agentId: string;
   onClose: () => void;
   onViewPrompt?: () => void;
+  onDelete?: () => Promise<void> | void;
 }
 
-export default function AgentCardView({ worldId, agentId, onClose, onViewPrompt }: Props) {
+export default function AgentCardView({
+  worldId,
+  agentId,
+  onClose,
+  onViewPrompt,
+  onDelete,
+}: Props) {
   const [detail, setDetail] = useState<AgentDetail | null>(null);
   const [editMode, setEditMode] = useState(false);
   const [loading, setLoading] = useState(true);
@@ -93,6 +100,11 @@ export default function AgentCardView({ worldId, agentId, onClose, onViewPrompt
               Prompt
             </button>
           )}
+          {onDelete ? (
+            <button onClick={() => void onDelete()} className={styles.deleteBtn}>
+              Delete character
+            </button>
+          ) : null}
           <button onClick={() => setEditMode(true)} className={styles.editBtn}>
             <Pencil size={13} aria-hidden="true" />
             Edit
diff --git a/webui/src/pages/CharactersPage.module.css b/webui/src/pages/CharactersPage.module.css
index 59de3019..72d09680 100644
--- a/webui/src/pages/CharactersPage.module.css
+++ b/webui/src/pages/CharactersPage.module.css
@@ -176,12 +176,52 @@
   cursor: pointer;
   font-weight: 700;
 }
+.deleteError {
+  margin: 12px;
+  padding: 10px;
+  border: 1px solid #efc8c2;
+  border-radius: 6px;
+  background: #fff3f1;
+  color: #923a2d;
+}
+.voiceMetrics {
+  display: grid;
+  gap: 7px;
+  margin: 0;
+}
+.voiceMetrics div {
+  display: flex;
+  justify-content: space-between;
+}
+.voiceMetrics dt {
+  color: #667085;
+}
+.voiceMetrics dd {
+  margin: 0;
+  font-weight: 700;
+}
+.voiceWords {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 5px;
+  margin-top: 10px;
+}
+.voiceWords span {
+  padding: 3px 6px;
+  border-radius: 4px;
+  background: #edf2ff;
+  color: #153981;
+}
 @media (max-width: 1050px) {
   .workspace {
     grid-template-columns: 230px 1fr;
+    overflow: auto;
   }
   .contextPane {
-    display: none;
+    grid-column: 1 / -1;
+    overflow: visible;
+    border-top: 1px solid #dfe6ef;
+    border-left: 0;
   }
 }
 @media (max-width: 700px) {
diff --git a/webui/src/pages/CharactersPage.tsx b/webui/src/pages/CharactersPage.tsx
index d8efeefb..45b15ade 100644
--- a/webui/src/pages/CharactersPage.tsx
+++ b/webui/src/pages/CharactersPage.tsx
@@ -1,7 +1,13 @@
 import { useState } from 'react';
 import { Plus, RefreshCw, Users } from 'lucide-react';
 import { api } from '../api/client';
-import type { DiaryEntry, RelationEntry, WorldAgent } from '../api/types';
+import type {
+  DiaryEntry,
+  MemorySummary,
+  RelationEntry,
+  VoiceFingerprint,
+  WorldAgent,
+} from '../api/types';
 import AgentAvatar from '../components/AgentAvatar';
 import AgentCardView from '../components/Inspector/AgentCardView';
 import CreateAgentModal from '../components/Inspector/CreateAgentModal';
@@ -18,9 +24,26 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
   const agents = useResource(`characters:${worldId}`, () => api.listAgents(worldId));
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [showCreate, setShowCreate] = useState(false);
+  const [deleteError, setDeleteError] = useState<string | null>(null);
   const items = agents.data?.agents ?? [];
   const selected = selectedId && items.some((item) => item.id === selectedId) ? selectedId : null;
 
+  async function deleteSelected() {
+    if (!selected) return;
+    const index = items.findIndex((item) => item.id === selected);
+    const agent = items[index];
+    const name = agent?.display_name || agent?.name || selected;
+    if (!window.confirm(`Delete ${name}? This cannot be undone.`)) return;
+    setDeleteError(null);
+    try {
+      await api.deleteAgent(worldId, selected);
+      setSelectedId(items[index + 1]?.id ?? items[index - 1]?.id ?? null);
+      agents.retry();
+    } catch (error) {
+      setDeleteError(error instanceof Error ? error.message : 'Unable to delete character.');
+    }
+  }
+
   if (!agents.data) {
     return (
       <PageState
@@ -90,8 +113,18 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
       </aside>
 
       <section className={styles.detailPane}>
+        {deleteError ? (
+          <div className={styles.deleteError} role="alert">
+            {deleteError}
+          </div>
+        ) : null}
         {selected ? (
-          <AgentCardView worldId={worldId} agentId={selected} onClose={() => setSelectedId(null)} />
+          <AgentCardView
+            worldId={worldId}
+            agentId={selected}
+            onClose={() => setSelectedId(null)}
+            onDelete={deleteSelected}
+          />
         ) : (
           <div className={styles.pick}>
             <Users aria-hidden="true" />
@@ -103,7 +136,7 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
 
       <aside className={styles.contextPane}>
         {selected ? (
-          <CharacterContext worldId={worldId} agentId={selected} />
+          <CharacterContext worldId={worldId} agentId={selected} agents={items} />
         ) : (
           <p className={styles.muted}>Character diaries and explicit relationships appear here.</p>
         )}
@@ -132,13 +165,28 @@ function CharacterListItem({ agent }: { agent: WorldAgent }) {
   );
 }
 
-function CharacterContext({ worldId, agentId }: { worldId: string; agentId: string }) {
+function CharacterContext({
+  worldId,
+  agentId,
+  agents,
+}: {
+  worldId: string;
+  agentId: string;
+  agents: WorldAgent[];
+}) {
   const diaries = useResource(`character:${worldId}:${agentId}:diaries`, () =>
     api.fetchDiaries(worldId, agentId),
   );
   const relations = useResource(`character:${worldId}:${agentId}:relations`, () =>
     api.fetchRelations(worldId, agentId),
   );
+  const memories = useResource(`character:${worldId}:${agentId}:memories`, () =>
+    api.fetchMemorySummaries(worldId, agentId),
+  );
+  const voice = useResource(`character:${worldId}:${agentId}:voice`, () =>
+    api.fetchAgentVoice(worldId, agentId),
+  );
+  const names = new Map(agents.map((agent) => [agent.id, agent.display_name || agent.name]));
   return (
     <div className={styles.contextStack}>
       <ContextSection
@@ -162,15 +210,75 @@ function CharacterContext({ worldId, agentId }: { worldId: string; agentId: stri
         render={(item: RelationEntry) => (
           <article key={`${item.agent_id}:${item.target_id}`}>
             <strong>{item.relation_type}</strong>
+            <small>{names.get(item.target_id) ?? item.target_id}</small>
             {item.description ? <p>{item.description}</p> : null}
           </article>
         )}
         empty="No explicit relationships yet."
       />
+      <ContextSection
+        title="Memory summaries"
+        resource={memories}
+        retryLabel="Retry memory summaries"
+        items={(data) => data.summaries}
+        render={(item: MemorySummary) => (
+          <article key={item.id}>
+            <p>{item.summary}</p>
+            <small>
+              {item.period_start} - {item.period_end}
+            </small>
+          </article>
+        )}
+        empty="No memory summaries yet."
+      />
+      <VoiceSection resource={voice} />
     </div>
   );
 }
 
+function VoiceSection({
+  resource,
+}: {
+  resource: ReturnType<typeof useResource<{ ok: boolean; voice: VoiceFingerprint }>>;
+}) {
+  const voice = resource.data?.voice;
+  return (
+    <section className={styles.contextSection}>
+      <h2>Voice fingerprint</h2>
+      {resource.status === 'loading' && !voice ? <p className={styles.muted}>Loading...</p> : null}
+      {resource.error && !voice ? (
+        <div className={styles.contextError} role="alert">
+          <span>{resource.error.message}</span>
+          <button type="button" onClick={resource.retry} aria-label="Retry voice fingerprint">
+            Retry
+          </button>
+        </div>
+      ) : null}
+      {voice ? (
+        <article>
+          <dl className={styles.voiceMetrics}>
+            <div>
+              <dt>Samples</dt>
+              <dd>{voice.sample_count}</dd>
+            </div>
+            <div>
+              <dt>Average sentence length</dt>
+              <dd>{voice.avg_sentence_length}</dd>
+            </div>
+          </dl>
+          {voice.signature_words.length ? (
+            <div className={styles.voiceWords}>
+              {voice.signature_words.map((word) => (
+                <span key={word}>{word}</span>
+              ))}
+            </div>
+          ) : null}
+        </article>
+      ) : null}
+    </section>
+  );
+}
+
 function ContextSection<TData, TItem>({
   title,
   resource,

From 1929f8ef6c3e98cc44c5005345082d19d02323d0 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 12:42:23 +0800
Subject: [PATCH 28/49] fix(webui): retain character deletion state

---
 webui/src/__tests__/api.test.ts           | 23 +++++++++++
 webui/src/__tests__/pages.test.tsx        | 49 +++++++++++++++++++++++
 webui/src/api/client.ts                   | 16 +++++---
 webui/src/api/types.ts                    |  2 +-
 webui/src/pages/CharactersPage.module.css | 20 +++++++++
 webui/src/pages/CharactersPage.tsx        | 24 ++++++++++-
 6 files changed, 126 insertions(+), 8 deletions(-)

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index ba33626f..f32aed75 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -355,6 +355,29 @@ describe('api client', () => {
     ]);
   });
 
+  it('normalizes only voice endpoint 404 to an empty fingerprint', async () => {
+    vi.mocked(fetch)
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({ error: { code: 'not_found', message: 'Voice fingerprint not found' } }),
+          { status: 404 },
+        ),
+      )
+      .mockResolvedValueOnce(
+        new Response(
+          JSON.stringify({ error: { code: 'database_error', message: 'Voice store failed' } }),
+          { status: 500 },
+        ),
+      );
+    const { api } = await import('../api/client');
+
+    await expect(api.fetchAgentVoice('w1', 'a1')).resolves.toEqual({ ok: true, voice: null });
+    await expect(api.fetchAgentVoice('w1', 'a1')).rejects.toMatchObject({
+      status: 500,
+      message: 'Voice store failed',
+    });
+  });
+
   it('preserves documented file-link target fields', async () => {
     vi.mocked(fetch).mockResolvedValueOnce(
       new Response(
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index e1f1ffeb..23e30d14 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -759,6 +759,55 @@ describe('Characters page', () => {
     );
   });
 
+  it('filters a confirmed deletion when retained list refresh fails', async () => {
+    const deletion = deferred<{ ok: boolean }>();
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listAgents)
+      .mockResolvedValueOnce({ ok: true, agents: [lin, sora] })
+      .mockRejectedValueOnce(new Error('List refresh failed'));
+    vi.mocked(api.fetchAgentDetail).mockImplementation((_worldId, id) =>
+      Promise.resolve(detail(id, id === 'lin' ? 'Lin' : 'Sora')),
+    );
+    vi.mocked(api.fetchDiaries).mockResolvedValue({ ok: true, diaries: [] });
+    vi.mocked(api.fetchRelations).mockResolvedValue({ ok: true, relations: [] });
+    vi.mocked(api.fetchMemorySummaries).mockResolvedValue({ ok: true, summaries: [] });
+    vi.mocked(api.fetchAgentVoice).mockResolvedValue({ ok: true, voice: null });
+    vi.mocked(api.deleteAgent).mockReturnValue(deletion.promise);
+
+    render(<CharactersPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Sora/ }));
+    await screen.findByRole('heading', { name: 'Sora' });
+    fireEvent.click(screen.getByRole('button', { name: 'Delete character' }));
+    expect(screen.getByRole('option', { name: /Sora/ })).toBeDefined();
+
+    await act(async () => deletion.resolve({ ok: true }));
+
+    await waitFor(() => expect(screen.queryByRole('option', { name: /Sora/ })).toBeNull());
+    expect(await screen.findByRole('alert')).toHaveTextContent('List refresh failed');
+    expect(screen.getByRole('button', { name: 'Retry character list' })).toBeDefined();
+    expect(screen.getByRole('option', { name: /Lin/ })).toHaveAttribute('aria-selected', 'true');
+  });
+
+  it('renders voice 404 as empty and voice 500 as retryable error', async () => {
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [lin, sora] });
+    vi.mocked(api.fetchAgentDetail).mockImplementation((_worldId, id) =>
+      Promise.resolve(detail(id, id === 'lin' ? 'Lin' : 'Sora')),
+    );
+    vi.mocked(api.fetchDiaries).mockResolvedValue({ ok: true, diaries: [] });
+    vi.mocked(api.fetchRelations).mockResolvedValue({ ok: true, relations: [] });
+    vi.mocked(api.fetchMemorySummaries).mockResolvedValue({ ok: true, summaries: [] });
+    vi.mocked(api.fetchAgentVoice)
+      .mockResolvedValueOnce({ ok: true, voice: null })
+      .mockRejectedValueOnce(new Error('Voice store failed'));
+
+    render(<CharactersPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Lin/ }));
+    expect(await screen.findByText('No voice fingerprint yet.')).toBeDefined();
+    fireEvent.click(screen.getByRole('option', { name: /Sora/ }));
+    expect(await screen.findByText('Voice store failed')).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Retry voice fingerprint' })).toBeDefined();
+  });
+
   it('keeps character context accessible below 1050px', () => {
     const css = readFileSync(join(process.cwd(), 'src/pages/CharactersPage.module.css'), 'utf8');
     const responsiveBlock = css.slice(
diff --git a/webui/src/api/client.ts b/webui/src/api/client.ts
index 6308b4e7..4f7723a8 100644
--- a/webui/src/api/client.ts
+++ b/webui/src/api/client.ts
@@ -337,11 +337,17 @@ export const api = {
       `/api/worldbuilding/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}/memory-summaries`,
     ),
 
-  fetchAgentVoice: (worldId: string, agentId: string) =>
-    request<VoiceFingerprintResponse>(
-      'GET',
-      `/api/worldbuilding/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}/voice`,
-    ),
+  fetchAgentVoice: async (worldId: string, agentId: string) => {
+    try {
+      return await request<VoiceFingerprintResponse>(
+        'GET',
+        `/api/worldbuilding/${encodeURIComponent(worldId)}/agents/${encodeURIComponent(agentId)}/voice`,
+      );
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404) return { ok: true, voice: null };
+      throw error;
+    }
+  },
 
   deleteAgent: (worldId: string, agentId: string) =>
     request<OkResponse>(
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index e474da36..3abedab8 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -535,7 +535,7 @@ export interface VoiceFingerprint {
 
 export interface VoiceFingerprintResponse {
   ok: boolean;
-  voice: VoiceFingerprint;
+  voice: VoiceFingerprint | null;
 }
 
 export interface MemorySummaryListResponse {
diff --git a/webui/src/pages/CharactersPage.module.css b/webui/src/pages/CharactersPage.module.css
index 72d09680..6bfc66b0 100644
--- a/webui/src/pages/CharactersPage.module.css
+++ b/webui/src/pages/CharactersPage.module.css
@@ -68,6 +68,26 @@
 .refresh svg {
   width: 13px;
 }
+.listWarning {
+  display: grid;
+  gap: 6px;
+  margin: 0 16px 10px;
+  padding: 9px;
+  border: 1px solid #f0d7a6;
+  border-radius: 6px;
+  background: #fff9eb;
+  color: #7a4d0b;
+  font-size: 12px;
+}
+.listWarning button {
+  width: max-content;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: #153981;
+  cursor: pointer;
+  font-weight: 700;
+}
 .listItem {
   display: flex;
   align-items: center;
diff --git a/webui/src/pages/CharactersPage.tsx b/webui/src/pages/CharactersPage.tsx
index 45b15ade..85caff23 100644
--- a/webui/src/pages/CharactersPage.tsx
+++ b/webui/src/pages/CharactersPage.tsx
@@ -25,7 +25,13 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [showCreate, setShowCreate] = useState(false);
   const [deleteError, setDeleteError] = useState<string | null>(null);
-  const items = agents.data?.agents ?? [];
+  const [confirmedDeleted, setConfirmedDeleted] = useState<{
+    worldId: string;
+    ids: Set<string>;
+  }>(() => ({ worldId, ids: new Set() }));
+  const deletedIds =
+    confirmedDeleted.worldId === worldId ? confirmedDeleted.ids : new Set<string>();
+  const items = (agents.data?.agents ?? []).filter((agent) => !deletedIds.has(agent.id));
   const selected = selectedId && items.some((item) => item.id === selectedId) ? selectedId : null;
 
   async function deleteSelected() {
@@ -37,6 +43,11 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
     setDeleteError(null);
     try {
       await api.deleteAgent(worldId, selected);
+      setConfirmedDeleted((previous) => {
+        const ids = previous.worldId === worldId ? new Set(previous.ids) : new Set<string>();
+        ids.add(selected);
+        return { worldId, ids };
+      });
       setSelectedId(items[index + 1]?.id ?? items[index - 1]?.id ?? null);
       agents.retry();
     } catch (error) {
@@ -99,6 +110,14 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
           <RefreshCw aria-hidden="true" />
           Refresh
         </button>
+        {agents.error && agents.data ? (
+          <div className={styles.listWarning} role="alert">
+            <span>{agents.error.message}</span>
+            <button type="button" onClick={agents.retry} aria-label="Retry character list">
+              Retry
+            </button>
+          </div>
+        ) : null}
         <ResourceList
           items={items}
           selectedId={selected}
@@ -239,7 +258,7 @@ function CharacterContext({
 function VoiceSection({
   resource,
 }: {
-  resource: ReturnType<typeof useResource<{ ok: boolean; voice: VoiceFingerprint }>>;
+  resource: ReturnType<typeof useResource<{ ok: boolean; voice: VoiceFingerprint | null }>>;
 }) {
   const voice = resource.data?.voice;
   return (
@@ -254,6 +273,7 @@ function VoiceSection({
           </button>
         </div>
       ) : null}
+      {resource.data && !voice ? <p className={styles.muted}>No voice fingerprint yet.</p> : null}
       {voice ? (
         <article>
           <dl className={styles.voiceMetrics}>

From 9e38231338272a417f3e3d330e6ce38fb6c054bb Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 12:49:52 +0800
Subject: [PATCH 29/49] fix(webui): preserve empty character refresh warning

---
 webui/src/__tests__/pages.test.tsx | 23 +++++++++++++++++++++++
 webui/src/pages/CharactersPage.tsx | 19 +++++++++++--------
 2 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 23e30d14..c6a9bb06 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -788,6 +788,29 @@ describe('Characters page', () => {
     expect(screen.getByRole('option', { name: /Lin/ })).toHaveAttribute('aria-selected', 'true');
   });
 
+  it('shows retained refresh failure beside empty state after deleting the only character', async () => {
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listAgents)
+      .mockResolvedValueOnce({ ok: true, agents: [lin] })
+      .mockRejectedValueOnce(new Error('List refresh failed'));
+    vi.mocked(api.fetchAgentDetail).mockResolvedValue(detail('lin', 'Lin'));
+    vi.mocked(api.fetchDiaries).mockResolvedValue({ ok: true, diaries: [] });
+    vi.mocked(api.fetchRelations).mockResolvedValue({ ok: true, relations: [] });
+    vi.mocked(api.fetchMemorySummaries).mockResolvedValue({ ok: true, summaries: [] });
+    vi.mocked(api.fetchAgentVoice).mockResolvedValue({ ok: true, voice: null });
+    vi.mocked(api.deleteAgent).mockResolvedValue({ ok: true });
+
+    render(<CharactersPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Lin/ }));
+    await screen.findByRole('heading', { name: 'Lin' });
+    fireEvent.click(screen.getByRole('button', { name: 'Delete character' }));
+
+    expect(await screen.findByRole('heading', { name: 'No characters yet' })).toBeDefined();
+    expect(screen.queryByRole('option', { name: /Lin/ })).toBeNull();
+    expect(await screen.findByRole('alert')).toHaveTextContent('List refresh failed');
+    expect(screen.getByRole('button', { name: 'Retry character list' })).toBeDefined();
+  });
+
   it('renders voice 404 as empty and voice 500 as retryable error', async () => {
     vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [lin, sora] });
     vi.mocked(api.fetchAgentDetail).mockImplementation((_worldId, id) =>
diff --git a/webui/src/pages/CharactersPage.tsx b/webui/src/pages/CharactersPage.tsx
index 85caff23..e4eac437 100644
--- a/webui/src/pages/CharactersPage.tsx
+++ b/webui/src/pages/CharactersPage.tsx
@@ -66,9 +66,19 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
     );
   }
 
+  const listWarning = agents.error ? (
+    <div className={styles.listWarning} role="alert">
+      <span>{agents.error.message}</span>
+      <button type="button" onClick={agents.retry} aria-label="Retry character list">
+        Retry
+      </button>
+    </div>
+  ) : null;
+
   if (items.length === 0) {
     return (
       <main className={styles.page}>
+        {listWarning}
         <section className={styles.empty}>
           <Users aria-hidden="true" />
           <h1>No characters yet</h1>
@@ -110,14 +120,7 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
           <RefreshCw aria-hidden="true" />
           Refresh
         </button>
-        {agents.error && agents.data ? (
-          <div className={styles.listWarning} role="alert">
-            <span>{agents.error.message}</span>
-            <button type="button" onClick={agents.retry} aria-label="Retry character list">
-              Retry
-            </button>
-          </div>
-        ) : null}
+        {listWarning}
         <ResourceList
           items={items}
           selectedId={selected}

From 1f23612ab7cccf6718e0587c024b5c685d9760d7 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 13:02:17 +0800
Subject: [PATCH 30/49] feat(webui): add chapter and scene workspaces

---
 webui/src/App.tsx                             |  84 ++++++++
 webui/src/__tests__/UserFlow.test.tsx         |  78 ++++++--
 webui/src/__tests__/pages.test.tsx            | 157 +++++++++++++++
 webui/src/components/ChapterEditor.module.css |  33 ++-
 webui/src/components/ChapterEditor.tsx        |  68 +++++--
 .../components/Inspector/EndSceneModal.tsx    |  25 ++-
 webui/src/pages/ChaptersPage.module.css       | 147 ++++++++++++++
 webui/src/pages/ChaptersPage.tsx              | 154 ++++++++++++++
 webui/src/pages/ScenesPage.module.css         | 188 ++++++++++++++++++
 webui/src/pages/ScenesPage.tsx                | 162 +++++++++++++++
 10 files changed, 1057 insertions(+), 39 deletions(-)
 create mode 100644 webui/src/pages/ChaptersPage.module.css
 create mode 100644 webui/src/pages/ChaptersPage.tsx
 create mode 100644 webui/src/pages/ScenesPage.module.css
 create mode 100644 webui/src/pages/ScenesPage.tsx

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index 7a9a75c1..f73ce1c4 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -29,6 +29,8 @@ const OverviewPage = lazy(() => import('./pages/OverviewPage'));
 const SessionsPage = lazy(() => import('./pages/SessionsPage'));
 const WorldPage = lazy(() => import('./pages/WorldPage'));
 const CharactersPage = lazy(() => import('./pages/CharactersPage'));
+const ChaptersPage = lazy(() => import('./pages/ChaptersPage'));
+const ScenesPage = lazy(() => import('./pages/ScenesPage'));
 
 export function shouldReportWorldbuildingPartialFailure(
   overviewLoaded: boolean,
@@ -238,6 +240,62 @@ function AppInner() {
     </DesktopShell>
   );
 
+  const narrativePageOverlays = (
+    <>
+      <Suspense>
+        <HelpDrawer open={helpOpen} onClose={() => setHelpOpen(false)} />
+      </Suspense>
+      <Suspense>
+        {state.showSetupWizard ? (
+          <SetupWizard
+            onComplete={() => dispatch({ type: 'SET_LLM_CONFIGURED', configured: true })}
+          />
+        ) : null}
+      </Suspense>
+      <Suspense>
+        {state.chapterReview && state.worldId ? (
+          <ChapterReviewBanner
+            worldId={state.worldId}
+            chapterId={state.chapterReview.chapter_id}
+            chapterTitle={state.chapterReview.title}
+            onNewChapter={() => {
+              dispatch({ type: 'SET_CHAPTER_REVIEW', review: null });
+              if (state.sessionId) {
+                api
+                  .startRun(state.sessionId, 'Start the next chapter', state.selectedModel)
+                  .catch(() => {});
+              }
+            }}
+            onRevise={() => dispatch({ type: 'SET_CHAPTER_REVIEW', review: null })}
+            onExport={() => dispatch({ type: 'SET_SHOW_EXPORT_DIALOG', show: true })}
+            onClose={() => dispatch({ type: 'SET_CHAPTER_REVIEW', review: null })}
+          />
+        ) : null}
+      </Suspense>
+      {state.pendingAsk ? (
+        <AskUserPrompt
+          request={state.pendingAsk}
+          onResolved={(callId) => dispatch({ type: 'RESOLVE_ASK', callId })}
+        />
+      ) : null}
+      {state.pendingCreation ? (
+        <CreationRequestDialog
+          request={state.pendingCreation}
+          onResolved={(creationId) => dispatch({ type: 'RESOLVE_CREATION', creationId })}
+        />
+      ) : null}
+      <Suspense>
+        {state.showExportDialog && state.worldId ? (
+          <ExportDialog
+            worldId={state.worldId}
+            chapters={[]}
+            onClose={() => dispatch({ type: 'SET_SHOW_EXPORT_DIALOG', show: false })}
+          />
+        ) : null}
+      </Suspense>
+    </>
+  );
+
   // Page-based rendering (overrides phase when navigating away from workbench)
   if (state.currentPage === 'settings') {
     return inDesktopShell(<SettingsPage />);
@@ -309,6 +367,32 @@ function AppInner() {
     );
   }
 
+  if (state.currentPage === 'chapters' && state.worldId) {
+    return (
+      <ToastProvider>
+        {inDesktopShell(
+          <Suspense fallback={<Skeleton />}>
+            <ChaptersPage worldId={state.worldId} />
+          </Suspense>,
+          narrativePageOverlays,
+        )}
+      </ToastProvider>
+    );
+  }
+
+  if (state.currentPage === 'scenes' && state.worldId) {
+    return (
+      <ToastProvider>
+        {inDesktopShell(
+          <Suspense fallback={<Skeleton />}>
+            <ScenesPage worldId={state.worldId} />
+          </Suspense>,
+          narrativePageOverlays,
+        )}
+      </ToastProvider>
+    );
+  }
+
   if (
     state.appPhase === 'no_agent' &&
     !shouldRenderSessionsPage(state.currentPage, state.appPhase)
diff --git a/webui/src/__tests__/UserFlow.test.tsx b/webui/src/__tests__/UserFlow.test.tsx
index 6a1cb907..ab6e1f54 100644
--- a/webui/src/__tests__/UserFlow.test.tsx
+++ b/webui/src/__tests__/UserFlow.test.tsx
@@ -1,5 +1,5 @@
 import { useEffect } from 'react';
-import { fireEvent, render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
 import { AppStateProvider, useAppState } from '../AppState';
@@ -7,8 +7,17 @@ import Composer from '../components/Composer';
 import ExportDialog from '../components/ExportDialog';
 import SetupWizard from '../components/SetupWizard';
 import { ToastProvider } from '../components/Toast';
+import ScenesPage from '../pages/ScenesPage';
 import SessionsPage from '../pages/SessionsPage';
 
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((resolvePromise) => {
+    resolve = resolvePromise;
+  });
+  return { promise, resolve };
+}
+
 function SessionsPageHarness() {
   const { dispatch } = useAppState();
 
@@ -126,6 +135,57 @@ describe('Sessions workbench', () => {
   });
 });
 
+describe('Scene completion flow', () => {
+  it('marks a scene complete only after endScene resolves and renders returned extraction counts', async () => {
+    const ending = deferred<Awaited<ReturnType<typeof api.endScene>>>();
+    vi.spyOn(api, 'listScenes').mockResolvedValue({
+      ok: true,
+      scenes: [
+        {
+          id: 'scene-1',
+          title: 'Crossing the flooded stacks',
+          chapter_id: 'chapter-2',
+          world_time: 'Day 4, dusk',
+          status: 'writing',
+          participant_ids: ['lin'],
+          updated_at: '2026-06-19T09:00:00Z',
+        },
+      ],
+    });
+    vi.spyOn(api, 'endScene').mockReturnValue(ending.promise);
+
+    render(
+      <AppStateProvider>
+        <ScenesPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('option', { name: /Crossing the flooded stacks/ }));
+    expect(screen.getByText('writing')).toBeDefined();
+    fireEvent.click(screen.getByRole('button', { name: 'End scene' }));
+    const dialog = screen.getByRole('dialog', { name: 'End scene' });
+    fireEvent.click(within(dialog).getByRole('button', { name: 'End Scene' }));
+
+    expect(screen.getByText('writing')).toBeDefined();
+    expect(screen.queryByText('completed')).toBeNull();
+
+    await act(async () =>
+      ending.resolve({
+        ok: true,
+        diaries_written: [{ id: 'diary-1', agent_id: 'lin', scene_id: 'scene-1' }],
+        diary_count: 1,
+        relations_updated: 2,
+        proposed_foreshadowing: [{ id: 'thread-1', content: 'The archive glass remembers.' }],
+        leak_risks: 0,
+      }),
+    );
+
+    await waitFor(() => expect(screen.getByText('completed')).toBeDefined());
+    expect(screen.getByText('diaries written').parentElement).toHaveTextContent('1');
+    expect(screen.getByText('relations updated').parentElement).toHaveTextContent('2');
+    expect(screen.getByText('The archive glass remembers.')).toBeDefined();
+  });
+});
+
 describe('SetupWizard', () => {
   it('renders the provider selection step initially', () => {
     const onComplete = vi.fn();
@@ -194,9 +254,7 @@ describe('ExportDialog', () => {
 
   it('renders the export dialog with chapter checkboxes', () => {
     const onClose = vi.fn();
-    render(
-      <ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />,
-    );
+    render(<ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />);
 
     // Dialog title
     expect(screen.getByText('导出 TXT')).toBeDefined();
@@ -221,9 +279,7 @@ describe('ExportDialog', () => {
 
   it('all checking and unchecking of chapters via select-all and deselect-all', () => {
     const onClose = vi.fn();
-    render(
-      <ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />,
-    );
+    render(<ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />);
 
     // All checkboxes should be checked by default
     const checkbox1 = screen.getByLabelText(/第1章 The Beginning/) as HTMLInputElement;
@@ -248,9 +304,7 @@ describe('ExportDialog', () => {
 
   it('export button is disabled until title is entered and at least one chapter is selected', () => {
     const onClose = vi.fn();
-    render(
-      <ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />,
-    );
+    render(<ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />);
 
     const exportBtn = screen.getByRole('button', { name: '导出' });
 
@@ -272,9 +326,7 @@ describe('ExportDialog', () => {
 
   it('calls onClose when cancel button is clicked', () => {
     const onClose = vi.fn();
-    render(
-      <ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />,
-    );
+    render(<ExportDialog worldId="world_1" chapters={chapters} onClose={onClose} />);
 
     fireEvent.click(screen.getByRole('button', { name: '取消' }));
     expect(onClose).toHaveBeenCalledTimes(1);
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index c6a9bb06..20dfdc2f 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -10,8 +10,10 @@ import DetailPane from '../components/layout/DetailPane';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
 import { useResource } from '../hooks/useResource';
+import ChaptersPage from '../pages/ChaptersPage';
 import CharactersPage from '../pages/CharactersPage';
 import OverviewPage from '../pages/OverviewPage';
+import ScenesPage from '../pages/ScenesPage';
 import { selectWorldMetrics } from '../pages/selectors';
 import WorldPage from '../pages/WorldPage';
 
@@ -30,6 +32,10 @@ vi.mock('../api/client', () => ({
     fetchMemorySummaries: vi.fn(),
     fetchAgentVoice: vi.fn(),
     deleteAgent: vi.fn(),
+    endScene: vi.fn(),
+    readWorkspaceFile: vi.fn(),
+    saveWorkspaceFile: vi.fn(),
+    patchChapter: vi.fn(),
   },
 }));
 
@@ -41,6 +47,7 @@ vi.mock('../api/worldbuilding', () => ({
     listFactions: vi.fn(),
     getTimeline: vi.fn(),
     listGraphEntities: vi.fn(),
+    reorderChapters: vi.fn(),
   },
 }));
 
@@ -182,6 +189,156 @@ describe('PageState', () => {
   });
 });
 
+const chapterFixtures = [
+  {
+    id: 'chapter-1',
+    title: 'Ashes at Dawn',
+    number: 1,
+    status: 'completed',
+    scene_count: 2,
+    updated_at: '2026-06-18T08:00:00Z',
+  },
+  {
+    id: 'chapter-2',
+    title: 'The Rain Archive',
+    number: 2,
+    status: 'draft',
+    scene_count: 1,
+    updated_at: '2026-06-19T08:00:00Z',
+  },
+];
+
+const sceneFixtures = [
+  {
+    id: 'scene-1',
+    title: 'Crossing the flooded stacks',
+    chapter_id: 'chapter-2',
+    world_time: 'Day 4, dusk',
+    status: 'writing',
+    participant_ids: ['lin', 'sora'],
+    updated_at: '2026-06-19T09:00:00Z',
+  },
+];
+
+describe('Chapter and scene pages', () => {
+  it('moves chapters with keyboard-accessible controls and sends the exact ordered IDs', async () => {
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
+    vi.mocked(worldbuildingApi.reorderChapters).mockResolvedValue({ ok: true });
+
+    render(<ChaptersPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('button', { name: 'Move The Rain Archive previous' }));
+
+    await waitFor(() =>
+      expect(worldbuildingApi.reorderChapters).toHaveBeenCalledWith('world-1', [
+        'chapter-2',
+        'chapter-1',
+      ]),
+    );
+    expect(
+      screen.getAllByRole('heading', { level: 2 }).map((heading) => heading.textContent),
+    ).toEqual(['The Rain Archive', 'Ashes at Dawn']);
+  });
+
+  it.each([
+    ['Chapters', ChaptersPage, 'Loading chapters', 'No chapters yet', 'Chapter list unavailable'],
+    ['Scenes', ScenesPage, 'Loading scenes', 'No scenes yet', 'Scene list unavailable'],
+  ] as const)(
+    'renders %s loading, empty, and error states',
+    async (_name, Page, loading, empty, error) => {
+      const list = _name === 'Chapters' ? api.listChapters : api.listScenes;
+      const pending = deferred<never>();
+      vi.mocked(list as typeof api.listChapters).mockReturnValueOnce(pending.promise);
+      const { unmount } = render(<Page worldId="world-1" />);
+      expect(screen.getByRole('status', { name: loading })).toBeDefined();
+      unmount();
+
+      if (_name === 'Chapters') {
+        vi.mocked(api.listChapters).mockResolvedValueOnce({ ok: true, chapters: [] });
+      } else {
+        vi.mocked(api.listScenes).mockResolvedValueOnce({ ok: true, scenes: [] });
+      }
+      const emptyRender = render(<Page worldId="world-1" />);
+      expect(await screen.findByRole('heading', { name: empty })).toBeDefined();
+      emptyRender.unmount();
+
+      vi.mocked(list as typeof api.listChapters).mockRejectedValueOnce(new Error(error));
+      render(<Page worldId="world-1" />);
+      expect(await screen.findByRole('alert')).toHaveTextContent(error);
+    },
+  );
+
+  it('opens the selected chapter in the reusable editor', async () => {
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: 'chapters/world-1/chapter-2.md',
+        content: 'Rain pressed against the archive glass.',
+        encoding: 'utf-8',
+        updated_at: '2026-06-19T09:00:00Z',
+        version: 'v1',
+      },
+    });
+
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Edit The Rain Archive' }));
+
+    expect(await screen.findByRole('textbox', { name: 'Chapter content' })).toHaveValue(
+      'Rain pressed against the archive glass.',
+    );
+  });
+
+  it('keeps chapter editor dirty state and sends the loaded version when saving', async () => {
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: 'chapters/world-1/chapter-2.md',
+        content: 'Original draft.',
+        encoding: 'utf-8',
+        updated_at: '2026-06-19T09:00:00Z',
+        version: 'v7',
+      },
+    });
+    vi.mocked(api.saveWorkspaceFile).mockRejectedValue(new Error('Conflict: file changed on disk'));
+
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Edit The Rain Archive' }));
+    const editor = await screen.findByRole('textbox', { name: 'Chapter content' });
+    fireEvent.change(editor, { target: { value: 'Revised draft.' } });
+    expect(screen.getByText('Unsaved changes')).toBeDefined();
+    fireEvent.click(screen.getByRole('button', { name: 'Save chapter' }));
+
+    await waitFor(() =>
+      expect(api.saveWorkspaceFile).toHaveBeenCalledWith(
+        'chapters/world-1/chapter-2.md',
+        'Revised draft.',
+        'v7',
+      ),
+    );
+    expect(await screen.findByRole('alert')).toHaveTextContent('Conflict: file changed on disk');
+    expect(screen.getByText('Unsaved changes')).toBeDefined();
+  });
+
+  it('renders only actual scene fields and omits unsupported consistency content', async () => {
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: sceneFixtures });
+    render(<ScenesPage worldId="world-1" />);
+
+    fireEvent.click(await screen.findByRole('option', { name: /Crossing the flooded stacks/ }));
+    expect(screen.getByText('Day 4, dusk')).toBeDefined();
+    expect(screen.getByText('lin, sora')).toBeDefined();
+    expect(screen.queryByText(/consistency/i)).toBeNull();
+  });
+});
+
 describe('ResourceList', () => {
   const items = [
     { id: 'a', name: 'A' },
diff --git a/webui/src/components/ChapterEditor.module.css b/webui/src/components/ChapterEditor.module.css
index fcda0d54..06f808d4 100644
--- a/webui/src/components/ChapterEditor.module.css
+++ b/webui/src/components/ChapterEditor.module.css
@@ -52,7 +52,8 @@
   cursor: pointer;
   font-size: 12px;
   white-space: nowrap;
-  transition: background var(--duration-fast) var(--ease),
+  transition:
+    background var(--duration-fast) var(--ease),
     border-color var(--duration-fast) var(--ease),
     transform var(--duration-fast) var(--ease);
 }
@@ -74,7 +75,8 @@
   font-size: 12px;
   font-weight: 650;
   white-space: nowrap;
-  transition: background var(--duration-fast) var(--ease),
+  transition:
+    background var(--duration-fast) var(--ease),
     transform var(--duration-fast) var(--ease);
 }
 
@@ -98,6 +100,22 @@
   overflow: hidden;
 }
 
+.dirty {
+  padding: 6px 14px;
+  border-bottom: 1px solid var(--border);
+  background: var(--amber-soft);
+  color: var(--brand-strong);
+  font-size: 11px;
+  font-weight: 700;
+}
+.saveError {
+  padding: 8px 14px;
+  border-bottom: 1px solid rgba(183, 60, 31, 0.25);
+  background: #fff1ee;
+  color: #9b2c1f;
+  font-size: 12px;
+}
+
 .textarea {
   flex: 1;
   padding: 16px 20px;
@@ -106,7 +124,13 @@
   color: var(--ink);
   font-size: 15px;
   line-height: 1.8;
-  font-family: Inter, ui-sans-serif, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  font-family:
+    Inter,
+    ui-sans-serif,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    sans-serif;
   font-feature-settings: 'ss01', 'ss03';
   resize: none;
   outline: none;
@@ -169,7 +193,8 @@
   cursor: pointer;
   font-size: 11px;
   font-weight: 680;
-  transition: background var(--duration-fast) var(--ease),
+  transition:
+    background var(--duration-fast) var(--ease),
     border-color var(--duration-fast) var(--ease),
     transform var(--duration-fast) var(--ease);
 }
diff --git a/webui/src/components/ChapterEditor.tsx b/webui/src/components/ChapterEditor.tsx
index c51dd114..ceb08a80 100644
--- a/webui/src/components/ChapterEditor.tsx
+++ b/webui/src/components/ChapterEditor.tsx
@@ -1,5 +1,6 @@
 import { useCallback, useEffect, useState, type KeyboardEvent } from 'react';
 import { api } from '../api/client';
+import type { StoryChapter } from '../api/types';
 import { useAppState } from '../AppState';
 import styles from './ChapterEditor.module.css';
 
@@ -10,6 +11,7 @@ function chapterFilePath(worldId: string, chapterId: string) {
 interface Props {
   chapterId: string;
   worldId: string;
+  chapter?: StoryChapter;
 }
 
 interface ContextEntity {
@@ -19,17 +21,21 @@ interface ContextEntity {
   detail?: string;
 }
 
-export default function ChapterEditor({ chapterId, worldId }: Props) {
-  const { state } = useAppState();
-  const chapter = state.storyOverview?.current_chapter;
+export default function ChapterEditor({ chapterId, worldId, chapter: chapterProp }: Props) {
+  const { state, dispatch } = useAppState();
+  const chapter = chapterProp ?? state.storyOverview?.current_chapter;
   const scene = state.storyOverview?.current_scene;
 
   const [title, setTitle] = useState(chapter?.title ?? '');
+  const [originalTitle, setOriginalTitle] = useState(chapter?.title ?? '');
   const [content, setContent] = useState('');
   const [contentLoaded, setContentLoaded] = useState(false);
+  const [originalContent, setOriginalContent] = useState('');
+  const [version, setVersion] = useState<string | undefined>();
   const [saveStatus, setSaveStatus] = useState<'idle' | 'saving' | 'saved'>('idle');
   const [showContext, setShowContext] = useState(false);
   const [entities, setEntities] = useState<ContextEntity[]>([]);
+  const [saveError, setSaveError] = useState<string | null>(null);
 
   useEffect(() => {
     const items: ContextEntity[] = [];
@@ -62,6 +68,7 @@ export default function ChapterEditor({ chapterId, worldId }: Props) {
 
   useEffect(() => {
     setTitle(chapter?.title ?? '');
+    setOriginalTitle(chapter?.title ?? '');
   }, [chapter?.title]);
 
   useEffect(() => {
@@ -74,19 +81,27 @@ export default function ChapterEditor({ chapterId, worldId }: Props) {
       .then((data) => {
         if (!cancelled) {
           setContent(data.file.content);
+          setOriginalContent(data.file.content);
+          setVersion(data.file.version);
           setContentLoaded(true);
+          setSaveError(null);
+          dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'idle' });
         }
       })
       .catch(() => {
         if (!cancelled) {
           setContent('');
+          setOriginalContent('');
+          setVersion(undefined);
           setContentLoaded(true);
         }
       });
     return () => {
       cancelled = true;
     };
-  }, [chapterId, worldId]);
+  }, [chapterId, dispatch, worldId]);
+
+  const dirty = content !== originalContent || title !== originalTitle;
 
   const trimmed = content.trim();
   const cjkChars = (trimmed.match(/[一-鿿]/g) || []).length;
@@ -108,16 +123,25 @@ export default function ChapterEditor({ chapterId, worldId }: Props) {
 
   const handleSave = async () => {
     setSaveStatus('saving');
+    setSaveError(null);
+    dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saving' });
     try {
       const path = chapterFilePath(worldId, chapterId);
-      await api.saveWorkspaceFile(path, content);
-      if (title !== (chapter?.title ?? '')) {
-        await api.patchChapter(worldId, chapterId, { title }).catch(() => {});
+      const response = await api.saveWorkspaceFile(path, content, version);
+      if (title !== originalTitle) {
+        await api.patchChapter(worldId, chapterId, { title });
       }
+      setOriginalContent(content);
+      setOriginalTitle(title);
+      setVersion(response.file.version);
       setSaveStatus('saved');
+      dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saved' });
       setTimeout(() => setSaveStatus('idle'), 2000);
-    } catch {
+    } catch (error) {
+      const message = error instanceof Error ? error.message : 'Unable to save chapter.';
+      setSaveError(message);
       setSaveStatus('idle');
+      dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'error', error: message });
     }
   };
 
@@ -134,8 +158,12 @@ export default function ChapterEditor({ chapterId, worldId }: Props) {
         <input
           className={styles.titleInput}
           value={title}
-          onChange={(event) => setTitle(event.target.value)}
+          onChange={(event) => {
+            setTitle(event.target.value);
+            dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'dirty' });
+          }}
           placeholder="Chapter title"
+          aria-label="Chapter title"
         />
         <div className={styles.toolbarRight}>
           <span className={styles.stats}>
@@ -154,19 +182,30 @@ export default function ChapterEditor({ chapterId, worldId }: Props) {
           <button
             className={styles.saveBtn}
             onClick={handleSave}
-            disabled={saveStatus === 'saving' || !contentLoaded}
+            disabled={saveStatus === 'saving' || !contentLoaded || !dirty}
             type="button"
+            aria-label="Save chapter"
           >
             {saveStatus === 'saving' ? 'Saving...' : saveStatus === 'saved' ? 'Saved' : 'Save'}
           </button>
         </div>
       </div>
 
+      {dirty ? <div className={styles.dirty}>Unsaved changes</div> : null}
+      {saveError ? (
+        <div className={styles.saveError} role="alert">
+          {saveError}
+        </div>
+      ) : null}
+
       <div className={styles.editorBody}>
         <textarea
           className={styles.textarea}
           value={content}
-          onChange={(event) => setContent(event.target.value)}
+          onChange={(event) => {
+            setContent(event.target.value);
+            dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'dirty' });
+          }}
           onKeyDown={handleKeyDown}
           placeholder={[
             'Write here...',
@@ -176,6 +215,7 @@ export default function ChapterEditor({ chapterId, worldId }: Props) {
             'Use @secret{id=secret_id} to reference a secret',
           ].join('\n')}
           spellCheck={false}
+          aria-label="Chapter content"
         />
 
         {showContext && (
@@ -221,11 +261,7 @@ export default function ChapterEditor({ chapterId, worldId }: Props) {
                     title={entity.detail}
                     type="button"
                   >
-                    {entity.kind === 'agent'
-                      ? '@'
-                      : entity.kind === 'foreshadow'
-                        ? '#'
-                        : 'key'}{' '}
+                    {entity.kind === 'agent' ? '@' : entity.kind === 'foreshadow' ? '#' : 'key'}{' '}
                     {entity.label}
                   </button>
                 ))}
diff --git a/webui/src/components/Inspector/EndSceneModal.tsx b/webui/src/components/Inspector/EndSceneModal.tsx
index 323d8cf6..d008c369 100644
--- a/webui/src/components/Inspector/EndSceneModal.tsx
+++ b/webui/src/components/Inspector/EndSceneModal.tsx
@@ -1,5 +1,5 @@
-import { BookOpen, CheckCircle2, Loader2, ScrollText, Users, X } from 'lucide-react';
 import { useEffect, useState } from 'react';
+import { BookOpen, CheckCircle2, Loader2, ScrollText, Users, X } from 'lucide-react';
 import { api } from '../../api/client';
 import type { EndSceneResponse } from '../../api/types';
 import { useAppState } from '../../AppState';
@@ -10,9 +10,10 @@ interface Props {
   sceneId: string;
   sceneTitle: string;
   onClose: () => void;
+  onEnded?: (result: EndSceneResponse) => void;
 }
 
-export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose }: Props) {
+export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose, onEnded }: Props) {
   const { state, dispatch } = useAppState();
   const [finalMarkdown, setFinalMarkdown] = useState('');
   const [submitting, setSubmitting] = useState(false);
@@ -36,6 +37,7 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose }:
         session_id: state.sessionId,
       });
       setResult(res);
+      onEnded?.(res);
       dispatch({ type: 'SET_STORY_VERSION' });
     } catch (e) {
       setError((e as Error).message);
@@ -79,14 +81,17 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose }:
             <div className={styles.foreshadowList}>
               <div className={styles.listTitle}>Suggested Foreshadowing</div>
               {result.proposed_foreshadowing.map((f) => (
-                <div key={f.id} className={styles.foreshadowItem}>{f.content}</div>
+                <div key={f.id} className={styles.foreshadowItem}>
+                  {f.content}
+                </div>
               ))}
             </div>
           )}
 
           {result.leak_risks > 0 && (
             <div className={styles.leakNotice}>
-              {result.leak_risks} secret leak risk{result.leak_risks > 1 ? 's' : ''} detected. Review knowledge boundaries.
+              {result.leak_risks} secret leak risk{result.leak_risks > 1 ? 's' : ''} detected.
+              Review knowledge boundaries.
             </div>
           )}
 
@@ -101,7 +106,12 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose }:
   return (
     <div className={styles.scrim} role="presentation">
       <section className={styles.modal} role="dialog" aria-modal="true" aria-label="End scene">
-        <button className={styles.closeBtn} onClick={onClose} aria-label="Cancel" disabled={submitting}>
+        <button
+          className={styles.closeBtn}
+          onClick={onClose}
+          aria-label="Cancel"
+          disabled={submitting}
+        >
           <X size={17} aria-hidden="true" strokeWidth={2.4} />
         </button>
         <div className={styles.iconWrap}>
@@ -109,7 +119,10 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose }:
         </div>
         <div className={styles.kicker}>End Scene</div>
         <h2>{sceneTitle}</h2>
-        <p>Ending this scene will write character diaries, update relationships, and suggest new foreshadowing threads.</p>
+        <p>
+          Ending this scene will write character diaries, update relationships, and suggest new
+          foreshadowing threads.
+        </p>
 
         <label className={styles.field}>
           <span>Final text (optional)</span>
diff --git a/webui/src/pages/ChaptersPage.module.css b/webui/src/pages/ChaptersPage.module.css
new file mode 100644
index 00000000..1b5cff03
--- /dev/null
+++ b/webui/src/pages/ChaptersPage.module.css
@@ -0,0 +1,147 @@
+.page {
+  min-height: 100%;
+  padding: 28px;
+  background: var(--surface-muted);
+  color: var(--ink);
+}
+.header {
+  display: flex;
+  justify-content: space-between;
+  gap: 24px;
+  align-items: flex-start;
+  margin-bottom: 20px;
+}
+.header h1 {
+  margin: 3px 0 5px;
+  font-size: 28px;
+}
+.header p {
+  margin: 0;
+  color: var(--muted);
+}
+.eyebrow {
+  color: var(--brand);
+  font-size: 11px;
+  font-weight: 800;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+.refresh,
+.actions button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: var(--surface-strong);
+  color: var(--ink);
+  min-height: 36px;
+  padding: 0 11px;
+  cursor: pointer;
+}
+.refresh svg,
+.actions svg {
+  width: 15px;
+  height: 15px;
+}
+.warning {
+  margin-bottom: 12px;
+  padding: 10px 12px;
+  border: 1px solid rgba(183, 121, 31, 0.25);
+  border-radius: 8px;
+  background: var(--amber-soft);
+}
+.summary {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 12px;
+  margin-bottom: 20px;
+}
+.summary div {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 2px 10px;
+  padding: 16px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: var(--surface-strong);
+}
+.summary svg {
+  grid-row: 1 / 3;
+  width: 20px;
+  color: var(--brand);
+}
+.summary strong {
+  font-size: 21px;
+}
+.summary span {
+  color: var(--muted);
+  font-size: 12px;
+}
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(230px, 1fr));
+  gap: 12px;
+}
+.card,
+.selectedCard {
+  padding: 16px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: var(--surface-strong);
+}
+.selectedCard {
+  border-color: var(--brand);
+  box-shadow: var(--ring);
+}
+.cardTop {
+  display: flex;
+  justify-content: space-between;
+  color: var(--muted);
+  font-size: 12px;
+}
+.status {
+  text-transform: capitalize;
+}
+.card h2,
+.selectedCard h2 {
+  margin: 15px 0 7px;
+  font-size: 16px;
+}
+.card p,
+.selectedCard p {
+  margin: 0 0 15px;
+  color: var(--muted);
+  font-size: 12px;
+}
+.actions {
+  display: flex;
+  gap: 7px;
+}
+.actions button:first-child {
+  margin-right: auto;
+}
+.actions button:disabled {
+  opacity: 0.35;
+  cursor: default;
+}
+.editor {
+  height: 520px;
+  margin-top: 22px;
+  overflow: hidden;
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  background: var(--surface-strong);
+}
+@media (max-width: 700px) {
+  .page {
+    padding: 18px;
+  }
+  .header {
+    flex-direction: column;
+  }
+  .summary {
+    grid-template-columns: 1fr;
+  }
+}
diff --git a/webui/src/pages/ChaptersPage.tsx b/webui/src/pages/ChaptersPage.tsx
new file mode 100644
index 00000000..ee2e6776
--- /dev/null
+++ b/webui/src/pages/ChaptersPage.tsx
@@ -0,0 +1,154 @@
+import { useState } from 'react';
+import { ArrowDown, ArrowUp, BookOpen, Edit3, RefreshCw } from 'lucide-react';
+import { api } from '../api/client';
+import type { StoryChapter } from '../api/types';
+import { worldbuildingApi } from '../api/worldbuilding';
+import ChapterEditor from '../components/ChapterEditor';
+import PageState from '../components/layout/PageState';
+import { useResource } from '../hooks/useResource';
+import styles from './ChaptersPage.module.css';
+
+export default function ChaptersPage({ worldId }: { worldId: string }) {
+  const resource = useResource(`chapters:${worldId}`, () => api.listChapters(worldId));
+  const [localOrder, setLocalOrder] = useState<{ worldId: string; items: StoryChapter[] } | null>(
+    null,
+  );
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [reorderError, setReorderError] = useState<string | null>(null);
+  const chapters =
+    localOrder?.worldId === worldId ? localOrder.items : (resource.data?.chapters ?? []);
+  const selected = chapters.find((chapter) => chapter.id === selectedId) ?? null;
+
+  async function moveChapter(index: number, offset: -1 | 1) {
+    const target = index + offset;
+    if (target < 0 || target >= chapters.length) return;
+    const previous = chapters;
+    const next = [...chapters];
+    [next[index], next[target]] = [next[target], next[index]];
+    setLocalOrder({ worldId, items: next });
+    setReorderError(null);
+    try {
+      await worldbuildingApi.reorderChapters(
+        worldId,
+        next.map((chapter) => chapter.id),
+      );
+    } catch (error) {
+      setLocalOrder({ worldId, items: previous });
+      setReorderError(error instanceof Error ? error.message : 'Unable to reorder chapters.');
+    }
+  }
+
+  if (!resource.data) {
+    return (
+      <PageState
+        loading={resource.status === 'loading'}
+        loadingLabel="Loading chapters"
+        error={resource.error}
+        onRetry={resource.retry}
+      />
+    );
+  }
+
+  if (!chapters.length) {
+    return (
+      <main className={styles.page}>
+        <PageState
+          isEmpty
+          emptyTitle="No chapters yet"
+          emptyDescription="Chapters will appear here after they are created for this world."
+        />
+      </main>
+    );
+  }
+
+  return (
+    <main className={styles.page}>
+      <header className={styles.header}>
+        <div>
+          <span className={styles.eyebrow}>Narrative plan</span>
+          <h1>Chapters</h1>
+          <p>Arrange the manuscript and open a chapter without leaving the planning workspace.</p>
+        </div>
+        <button type="button" className={styles.refresh} onClick={resource.retry}>
+          <RefreshCw aria-hidden="true" /> Refresh
+        </button>
+      </header>
+
+      {resource.error ? (
+        <div role="alert" className={styles.warning}>
+          {resource.error.message}
+        </div>
+      ) : null}
+      {reorderError ? (
+        <div role="alert" className={styles.warning}>
+          {reorderError}
+        </div>
+      ) : null}
+
+      <section className={styles.summary} aria-label="Chapter summary">
+        <div>
+          <BookOpen aria-hidden="true" />
+          <strong>{chapters.length}</strong>
+          <span>Total chapters</span>
+        </div>
+        <div>
+          <strong>{chapters.filter((chapter) => chapter.status === 'completed').length}</strong>
+          <span>Completed</span>
+        </div>
+        <div>
+          <strong>{chapters.reduce((sum, chapter) => sum + chapter.scene_count, 0)}</strong>
+          <span>Scenes</span>
+        </div>
+      </section>
+
+      <section className={styles.grid} aria-label="Chapter order">
+        {chapters.map((chapter, index) => (
+          <article
+            className={selectedId === chapter.id ? styles.selectedCard : styles.card}
+            key={chapter.id}
+          >
+            <div className={styles.cardTop}>
+              <span>Chapter {chapter.number}</span>
+              <span className={styles.status}>{chapter.status}</span>
+            </div>
+            <h2>{chapter.title}</h2>
+            <p>
+              {chapter.scene_count} {chapter.scene_count === 1 ? 'scene' : 'scenes'}
+            </p>
+            <div className={styles.actions}>
+              <button
+                type="button"
+                onClick={() => setSelectedId(chapter.id)}
+                aria-label={`Edit ${chapter.title}`}
+              >
+                <Edit3 aria-hidden="true" /> Edit
+              </button>
+              <button
+                type="button"
+                onClick={() => moveChapter(index, -1)}
+                disabled={index === 0}
+                aria-label={`Move ${chapter.title} previous`}
+              >
+                <ArrowUp aria-hidden="true" />
+              </button>
+              <button
+                type="button"
+                onClick={() => moveChapter(index, 1)}
+                disabled={index === chapters.length - 1}
+                aria-label={`Move ${chapter.title} next`}
+              >
+                <ArrowDown aria-hidden="true" />
+              </button>
+            </div>
+          </article>
+        ))}
+      </section>
+
+      {selected ? (
+        <section className={styles.editor} aria-label={`Editing ${selected.title}`}>
+          <ChapterEditor chapterId={selected.id} worldId={worldId} chapter={selected} />
+        </section>
+      ) : null}
+    </main>
+  );
+}
diff --git a/webui/src/pages/ScenesPage.module.css b/webui/src/pages/ScenesPage.module.css
new file mode 100644
index 00000000..1bfa1953
--- /dev/null
+++ b/webui/src/pages/ScenesPage.module.css
@@ -0,0 +1,188 @@
+.page {
+  min-height: 100%;
+  padding: 28px;
+  background: var(--surface-muted);
+}
+.workspace {
+  display: grid;
+  grid-template-columns: minmax(260px, 340px) minmax(0, 1fr);
+  min-height: 100%;
+  background: var(--surface-muted);
+}
+.listPane {
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+  padding: 22px 16px 14px;
+  border-right: 1px solid var(--border);
+  background: var(--surface-strong);
+}
+.listPane header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: 14px;
+}
+.listPane header span {
+  color: var(--brand);
+  font-size: 11px;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+.listPane h1 {
+  margin: 3px 0 0;
+  font-size: 25px;
+}
+.listPane header button {
+  display: grid;
+  place-items: center;
+  width: 36px;
+  height: 36px;
+  border: 1px solid var(--border);
+  border-radius: 8px;
+  background: transparent;
+  cursor: pointer;
+}
+.listPane header svg {
+  width: 16px;
+}
+.listPane footer {
+  padding-top: 12px;
+  color: var(--muted);
+  font-size: 12px;
+}
+.warning {
+  margin-bottom: 10px;
+  padding: 9px;
+  border-radius: 8px;
+  background: var(--amber-soft);
+  font-size: 12px;
+}
+.listItem {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 3px;
+}
+.listItem div {
+  display: grid;
+  gap: 5px;
+  min-width: 0;
+}
+.listItem strong {
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+.listItem span {
+  color: var(--muted);
+  font-size: 11px;
+}
+.dot {
+  flex: 0 0 auto;
+  width: 8px;
+  height: 8px;
+  margin-top: 5px;
+  border-radius: 50%;
+  background: var(--brand);
+}
+.detail {
+  padding: 28px;
+}
+.detailHeader {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 20px;
+  padding-bottom: 20px;
+  border-bottom: 1px solid var(--border);
+}
+.detailHeader span {
+  color: var(--brand);
+  font-size: 11px;
+  font-weight: 800;
+  text-transform: uppercase;
+}
+.detailHeader h2 {
+  margin: 6px 0 0;
+  font-size: 27px;
+}
+.detailHeader button {
+  min-height: 38px;
+  padding: 0 16px;
+  border: 0;
+  border-radius: 8px;
+  background: var(--brand-strong);
+  color: white;
+  font-weight: 700;
+  cursor: pointer;
+}
+.facts {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+  margin-top: 20px;
+}
+.fact {
+  display: grid;
+  grid-template-columns: auto 1fr;
+  gap: 5px 10px;
+  padding: 17px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: var(--surface-strong);
+}
+.fact svg {
+  grid-row: 1 / 3;
+  width: 18px;
+  color: var(--brand);
+}
+.fact span,
+.updated span {
+  color: var(--muted);
+  font-size: 11px;
+  text-transform: uppercase;
+}
+.fact strong {
+  font-size: 14px;
+  overflow-wrap: anywhere;
+}
+.updated {
+  display: grid;
+  gap: 5px;
+  margin-top: 12px;
+  padding: 17px;
+  border: 1px solid var(--border);
+  border-radius: 10px;
+  background: var(--surface-strong);
+}
+.pick {
+  display: grid;
+  place-items: center;
+  align-content: center;
+  min-height: 420px;
+  text-align: center;
+  color: var(--muted);
+}
+.pick svg {
+  width: 34px;
+  height: 34px;
+}
+.pick h2 {
+  margin: 14px 0 5px;
+  color: var(--ink);
+}
+.pick p {
+  margin: 0;
+}
+@media (max-width: 800px) {
+  .workspace {
+    grid-template-columns: 1fr;
+  }
+  .listPane {
+    border-right: 0;
+    border-bottom: 1px solid var(--border);
+  }
+  .facts {
+    grid-template-columns: 1fr;
+  }
+}
diff --git a/webui/src/pages/ScenesPage.tsx b/webui/src/pages/ScenesPage.tsx
new file mode 100644
index 00000000..bfe90130
--- /dev/null
+++ b/webui/src/pages/ScenesPage.tsx
@@ -0,0 +1,162 @@
+import { useState } from 'react';
+import { CheckCircle2, Clock3, PanelsTopLeft, RefreshCw, Users } from 'lucide-react';
+import { api } from '../api/client';
+import type { EndSceneResponse, StoryScene } from '../api/types';
+import EndSceneModal from '../components/Inspector/EndSceneModal';
+import PageState from '../components/layout/PageState';
+import ResourceList from '../components/layout/ResourceList';
+import { useResource } from '../hooks/useResource';
+import styles from './ScenesPage.module.css';
+
+export default function ScenesPage({ worldId }: { worldId: string }) {
+  const resource = useResource(`scenes:${worldId}`, () => api.listScenes(worldId));
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [completed, setCompleted] = useState<Record<string, EndSceneResponse>>({});
+  const [showEnd, setShowEnd] = useState(false);
+  const scenes = resource.data?.scenes ?? [];
+  const selectedBase = scenes.find((scene) => scene.id === selectedId) ?? null;
+  const selected =
+    selectedBase && completed[selectedBase.id]
+      ? { ...selectedBase, status: 'completed' }
+      : selectedBase;
+
+  if (!resource.data) {
+    return (
+      <PageState
+        loading={resource.status === 'loading'}
+        loadingLabel="Loading scenes"
+        error={resource.error}
+        onRetry={resource.retry}
+      />
+    );
+  }
+  if (!scenes.length) {
+    return (
+      <main className={styles.page}>
+        <PageState
+          isEmpty
+          emptyTitle="No scenes yet"
+          emptyDescription="Scenes will appear here after they are added to a chapter."
+        />
+      </main>
+    );
+  }
+
+  return (
+    <main className={styles.workspace}>
+      <aside className={styles.listPane}>
+        <header>
+          <div>
+            <span>Narrative plan</span>
+            <h1>Scenes</h1>
+          </div>
+          <button type="button" onClick={resource.retry} aria-label="Refresh scenes">
+            <RefreshCw aria-hidden="true" />
+          </button>
+        </header>
+        {resource.error ? (
+          <div role="alert" className={styles.warning}>
+            {resource.error.message}
+          </div>
+        ) : null}
+        <ResourceList
+          items={scenes}
+          selectedId={selectedId}
+          getId={(scene) => scene.id}
+          onSelect={setSelectedId}
+          ariaLabel="Scenes"
+          renderItem={(scene) => (
+            <SceneListItem scene={scene} completed={Boolean(completed[scene.id])} />
+          )}
+        />
+        <footer>
+          {scenes.length} {scenes.length === 1 ? 'scene' : 'scenes'}
+        </footer>
+      </aside>
+      <section className={styles.detail} aria-label="Scene detail">
+        {selected ? (
+          <>
+            <header className={styles.detailHeader}>
+              <div>
+                <span>Scene detail</span>
+                <h2>{selected.title}</h2>
+              </div>
+              {selected.status !== 'completed' ? (
+                <button type="button" onClick={() => setShowEnd(true)}>
+                  End scene
+                </button>
+              ) : null}
+            </header>
+            <div className={styles.facts}>
+              <Fact
+                icon={<CheckCircle2 aria-hidden="true" />}
+                label="Status"
+                value={selected.status}
+              />
+              <Fact
+                icon={<PanelsTopLeft aria-hidden="true" />}
+                label="Chapter ID"
+                value={selected.chapter_id}
+              />
+              <Fact
+                icon={<Clock3 aria-hidden="true" />}
+                label="World time"
+                value={selected.world_time || 'Not set'}
+              />
+              <Fact
+                icon={<Users aria-hidden="true" />}
+                label="Participants"
+                value={
+                  selected.participant_ids.length ? selected.participant_ids.join(', ') : 'None'
+                }
+              />
+            </div>
+            <section className={styles.updated}>
+              <span>Last updated</span>
+              <strong>{selected.updated_at}</strong>
+            </section>
+          </>
+        ) : (
+          <div className={styles.pick}>
+            <PanelsTopLeft aria-hidden="true" />
+            <h2>Select a scene</h2>
+            <p>Choose a scene to inspect its current API-backed details.</p>
+          </div>
+        )}
+      </section>
+      {showEnd && selected ? (
+        <EndSceneModal
+          worldId={worldId}
+          sceneId={selected.id}
+          sceneTitle={selected.title}
+          onClose={() => setShowEnd(false)}
+          onEnded={(result) => setCompleted((previous) => ({ ...previous, [selected.id]: result }))}
+        />
+      ) : null}
+    </main>
+  );
+}
+
+function SceneListItem({ scene, completed }: { scene: StoryScene; completed: boolean }) {
+  return (
+    <div className={styles.listItem}>
+      <span className={styles.dot} />
+      <div>
+        <strong>{scene.title}</strong>
+        <span>
+          {completed ? 'completed' : scene.status} · {scene.world_time || 'No world time'}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+function Fact({ icon, label, value }: { icon: React.ReactNode; label: string; value: string }) {
+  return (
+    <div className={styles.fact}>
+      {icon}
+      <span>{label}</span>
+      <strong>{value}</strong>
+    </div>
+  );
+}

From 39fea59b3bb8f77e271d81c446c60aeca161043f Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 13:17:57 +0800
Subject: [PATCH 31/49] fix(webui): harden chapter and scene workflows

---
 webui/src/__tests__/UserFlow.test.tsx         |  93 ++++++++++
 webui/src/__tests__/pages.test.tsx            | 172 +++++++++++++++++-
 webui/src/components/ChapterEditor.module.css |   6 +
 webui/src/components/ChapterEditor.tsx        |  15 +-
 .../components/Inspector/EndSceneModal.tsx    |  55 +++++-
 webui/src/pages/ChaptersPage.tsx              |  34 +++-
 webui/src/pages/ScenesPage.tsx                |  29 ++-
 7 files changed, 378 insertions(+), 26 deletions(-)

diff --git a/webui/src/__tests__/UserFlow.test.tsx b/webui/src/__tests__/UserFlow.test.tsx
index ab6e1f54..1d2a05c9 100644
--- a/webui/src/__tests__/UserFlow.test.tsx
+++ b/webui/src/__tests__/UserFlow.test.tsx
@@ -184,6 +184,99 @@ describe('Scene completion flow', () => {
     expect(screen.getByText('relations updated').parentElement).toHaveTextContent('2');
     expect(screen.getByText('The archive glass remembers.')).toBeDefined();
   });
+
+  it('keeps the end-scene target fixed when the live scene selection changes', async () => {
+    vi.spyOn(api, 'listScenes').mockResolvedValue({
+      ok: true,
+      scenes: [
+        {
+          id: 'scene-1',
+          title: 'First scene',
+          chapter_id: 'chapter-1',
+          world_time: 'Dawn',
+          status: 'writing',
+          participant_ids: [],
+          updated_at: '2026-06-19T09:00:00Z',
+        },
+        {
+          id: 'scene-2',
+          title: 'Second scene',
+          chapter_id: 'chapter-1',
+          world_time: 'Noon',
+          status: 'writing',
+          participant_ids: [],
+          updated_at: '2026-06-19T10:00:00Z',
+        },
+      ],
+    });
+    vi.spyOn(api, 'endScene').mockResolvedValue({
+      ok: true,
+      diaries_written: [],
+      diary_count: 0,
+      relations_updated: 0,
+      proposed_foreshadowing: [],
+      leak_risks: 0,
+    });
+    render(
+      <AppStateProvider>
+        <ScenesPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('option', { name: /First scene/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'End scene' }));
+    fireEvent.click(screen.getAllByRole('option', { hidden: true })[1]);
+    fireEvent.click(
+      within(screen.getByRole('dialog', { name: 'End scene' })).getByRole('button', {
+        name: 'End Scene',
+      }),
+    );
+
+    await waitFor(() => expect(api.endScene).toHaveBeenCalled());
+    expect(api.endScene).toHaveBeenCalledWith('world-1', 'scene-1', expect.any(Object));
+  });
+
+  it('traps focus in the end-scene modal and restores focus to its opener', async () => {
+    vi.spyOn(api, 'listScenes').mockResolvedValue({
+      ok: true,
+      scenes: [
+        {
+          id: 'scene-1',
+          title: 'First scene',
+          chapter_id: 'chapter-1',
+          world_time: 'Dawn',
+          status: 'writing',
+          participant_ids: [],
+          updated_at: '2026-06-19T09:00:00Z',
+        },
+      ],
+    });
+    render(
+      <AppStateProvider>
+        <ScenesPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('option', { name: /First scene/ }));
+    const opener = screen.getByRole('button', { name: 'End scene' });
+    opener.focus();
+    fireEvent.click(opener);
+    const dialog = screen.getByRole('dialog', { name: 'End scene' });
+
+    expect(
+      screen.getByRole('listbox', { name: 'Scenes', hidden: true }).closest('aside'),
+    ).toHaveAttribute('inert');
+    expect(screen.getByRole('region', { hidden: true })).toHaveAttribute('aria-hidden', 'true');
+    await waitFor(() => expect(within(dialog).getByRole('textbox')).toHaveFocus());
+    const [close, cancel] = within(dialog).getAllByRole('button', { name: 'Cancel' });
+    const end = within(dialog).getByRole('button', { name: 'End Scene' });
+    close.focus();
+    fireEvent.keyDown(dialog, { key: 'Tab', shiftKey: true });
+    expect(end).toHaveFocus();
+    end.focus();
+    fireEvent.keyDown(dialog, { key: 'Tab' });
+    expect(close).toHaveFocus();
+    fireEvent.click(cancel);
+    expect(opener).toHaveFocus();
+  });
 });
 
 describe('SetupWizard', () => {
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 20dfdc2f..6cde7026 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -225,7 +225,11 @@ describe('Chapter and scene pages', () => {
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
     vi.mocked(worldbuildingApi.reorderChapters).mockResolvedValue({ ok: true });
 
-    render(<ChaptersPage worldId="world-1" />);
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
     fireEvent.click(await screen.findByRole('button', { name: 'Move The Rain Archive previous' }));
 
     await waitFor(() =>
@@ -239,6 +243,63 @@ describe('Chapter and scene pages', () => {
     ).toEqual(['The Rain Archive', 'Ashes at Dawn']);
   });
 
+  it('disables chapter moves while a reorder request is pending', async () => {
+    const reorder = deferred<{ ok: boolean }>();
+    vi.mocked(worldbuildingApi.reorderChapters).mockClear();
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
+    vi.mocked(worldbuildingApi.reorderChapters).mockReturnValue(reorder.promise);
+
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    const movePrevious = await screen.findByRole('button', {
+      name: 'Move The Rain Archive previous',
+    });
+    fireEvent.click(movePrevious);
+
+    const moveNext = screen.getByRole('button', { name: 'Move The Rain Archive next' });
+    expect(moveNext).toBeDisabled();
+    fireEvent.click(moveNext);
+    expect(worldbuildingApi.reorderChapters).toHaveBeenCalledTimes(1);
+
+    await act(async () => reorder.resolve({ ok: true }));
+    await waitFor(() => expect(moveNext).not.toBeDisabled());
+  });
+
+  it('reconciles local chapter order with a fresh server response', async () => {
+    vi.mocked(api.listChapters)
+      .mockResolvedValueOnce({ ok: true, chapters: chapterFixtures })
+      .mockResolvedValueOnce({
+        ok: true,
+        chapters: [
+          { ...chapterFixtures[1], title: 'Rain Archive Revised', status: 'completed' },
+          {
+            id: 'chapter-3',
+            title: 'A New Signal',
+            number: 3,
+            status: 'draft',
+            scene_count: 0,
+            updated_at: '2026-06-20T08:00:00Z',
+          },
+        ],
+      });
+    vi.mocked(worldbuildingApi.reorderChapters).mockResolvedValue({ ok: true });
+
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Move The Rain Archive previous' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Refresh' }));
+
+    expect(await screen.findByRole('heading', { name: 'Rain Archive Revised' })).toBeDefined();
+    expect(screen.getByRole('heading', { name: 'A New Signal' })).toBeDefined();
+    expect(screen.queryByRole('heading', { name: 'Ashes at Dawn' })).toBeNull();
+  });
+
   it.each([
     ['Chapters', ChaptersPage, 'Loading chapters', 'No chapters yet', 'Chapter list unavailable'],
     ['Scenes', ScenesPage, 'Loading scenes', 'No scenes yet', 'Scene list unavailable'],
@@ -248,7 +309,11 @@ describe('Chapter and scene pages', () => {
       const list = _name === 'Chapters' ? api.listChapters : api.listScenes;
       const pending = deferred<never>();
       vi.mocked(list as typeof api.listChapters).mockReturnValueOnce(pending.promise);
-      const { unmount } = render(<Page worldId="world-1" />);
+      const { unmount } = render(
+        <AppStateProvider>
+          <Page worldId="world-1" />
+        </AppStateProvider>,
+      );
       expect(screen.getByRole('status', { name: loading })).toBeDefined();
       unmount();
 
@@ -257,12 +322,20 @@ describe('Chapter and scene pages', () => {
       } else {
         vi.mocked(api.listScenes).mockResolvedValueOnce({ ok: true, scenes: [] });
       }
-      const emptyRender = render(<Page worldId="world-1" />);
+      const emptyRender = render(
+        <AppStateProvider>
+          <Page worldId="world-1" />
+        </AppStateProvider>,
+      );
       expect(await screen.findByRole('heading', { name: empty })).toBeDefined();
       emptyRender.unmount();
 
       vi.mocked(list as typeof api.listChapters).mockRejectedValueOnce(new Error(error));
-      render(<Page worldId="world-1" />);
+      render(
+        <AppStateProvider>
+          <Page worldId="world-1" />
+        </AppStateProvider>,
+      );
       expect(await screen.findByRole('alert')).toHaveTextContent(error);
     },
   );
@@ -328,6 +401,87 @@ describe('Chapter and scene pages', () => {
     expect(screen.getByText('Unsaved changes')).toBeDefined();
   });
 
+  it('keeps the dirty chapter selected when switching is cancelled', async () => {
+    vi.spyOn(window, 'confirm').mockReturnValue(false);
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: 'chapters/world-1/chapter-2.md',
+        content: 'Original draft.',
+        encoding: 'utf-8',
+        updated_at: '2026-06-19T09:00:00Z',
+        version: 'v7',
+      },
+    });
+
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Edit The Rain Archive' }));
+    const editor = await screen.findByRole('textbox', { name: 'Chapter content' });
+    fireEvent.change(editor, { target: { value: 'Unsaved rain.' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Edit Ashes at Dawn' }));
+
+    expect(window.confirm).toHaveBeenCalledTimes(1);
+    expect(screen.getByRole('region', { name: 'Editing The Rain Archive' })).toBeDefined();
+    expect(editor).toHaveValue('Unsaved rain.');
+  });
+
+  it('commits a successful file version before reporting a title metadata failure', async () => {
+    vi.mocked(api.saveWorkspaceFile).mockClear();
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: 'chapters/world-1/chapter-2.md',
+        content: 'Original draft.',
+        encoding: 'utf-8',
+        updated_at: '2026-06-19T09:00:00Z',
+        version: 'v7',
+      },
+    });
+    vi.mocked(api.saveWorkspaceFile)
+      .mockResolvedValueOnce({
+        ok: true,
+        file: { path: 'chapters/world-1/chapter-2.md', updated_at: 'now', version: 'v8' },
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        file: { path: 'chapters/world-1/chapter-2.md', updated_at: 'later', version: 'v9' },
+      });
+    vi.mocked(api.patchChapter)
+      .mockRejectedValueOnce(new Error('Title service unavailable'))
+      .mockResolvedValueOnce({ ok: true });
+
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Edit The Rain Archive' }));
+    fireEvent.change(await screen.findByRole('textbox', { name: 'Chapter content' }), {
+      target: { value: 'Saved prose.' },
+    });
+    fireEvent.change(screen.getByRole('textbox', { name: 'Chapter title' }), {
+      target: { value: 'New title' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Save chapter' }));
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(
+      'Chapter text saved, but title update failed: Title service unavailable',
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Save chapter' }));
+    await waitFor(() => expect(api.saveWorkspaceFile).toHaveBeenCalledTimes(2));
+    expect(api.saveWorkspaceFile).toHaveBeenLastCalledWith(
+      'chapters/world-1/chapter-2.md',
+      'Saved prose.',
+      'v8',
+    );
+  });
+
   it('renders only actual scene fields and omits unsupported consistency content', async () => {
     vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: sceneFixtures });
     render(<ScenesPage worldId="world-1" />);
@@ -337,6 +491,16 @@ describe('Chapter and scene pages', () => {
     expect(screen.getByText('lin, sora')).toBeDefined();
     expect(screen.queryByText(/consistency/i)).toBeNull();
   });
+
+  it('lets the chapter editor toolbar wrap at narrow widths without clipping actions', () => {
+    const css = readFileSync(
+      join(process.cwd(), 'src/components/ChapterEditor.module.css'),
+      'utf8',
+    );
+    expect(css).toMatch(/\.container\s*\{[^}]*min-width:\s*0/s);
+    expect(css).toMatch(/\.toolbar\s*\{[^}]*flex-wrap:\s*wrap/s);
+    expect(css).toMatch(/\.toolbarRight\s*\{[^}]*overflow-x:\s*auto/s);
+  });
 });
 
 describe('ResourceList', () => {
diff --git a/webui/src/components/ChapterEditor.module.css b/webui/src/components/ChapterEditor.module.css
index 06f808d4..d8280ed9 100644
--- a/webui/src/components/ChapterEditor.module.css
+++ b/webui/src/components/ChapterEditor.module.css
@@ -2,11 +2,13 @@
   display: flex;
   flex-direction: column;
   height: 100%;
+  min-width: 0;
 }
 
 .toolbar {
   display: flex;
   align-items: center;
+  flex-wrap: wrap;
   gap: 12px;
   padding: 10px 14px;
   border-bottom: 1px solid var(--border);
@@ -15,6 +17,7 @@
 
 .titleInput {
   flex: 1;
+  min-width: 180px;
   padding: 6px 10px;
   border: 1px solid var(--border);
   border-radius: 6px;
@@ -34,6 +37,9 @@
   display: flex;
   align-items: center;
   gap: 8px;
+  max-width: 100%;
+  overflow-x: auto;
+  padding-bottom: 2px;
 }
 
 .stats {
diff --git a/webui/src/components/ChapterEditor.tsx b/webui/src/components/ChapterEditor.tsx
index ceb08a80..fd5d57b1 100644
--- a/webui/src/components/ChapterEditor.tsx
+++ b/webui/src/components/ChapterEditor.tsx
@@ -128,12 +128,21 @@ export default function ChapterEditor({ chapterId, worldId, chapter: chapterProp
     try {
       const path = chapterFilePath(worldId, chapterId);
       const response = await api.saveWorkspaceFile(path, content, version);
+      setOriginalContent(content);
+      setVersion(response.file.version);
       if (title !== originalTitle) {
-        await api.patchChapter(worldId, chapterId, { title });
+        try {
+          await api.patchChapter(worldId, chapterId, { title });
+        } catch (error) {
+          const detail = error instanceof Error ? error.message : 'Unable to update title.';
+          const message = `Chapter text saved, but title update failed: ${detail}`;
+          setSaveError(message);
+          setSaveStatus('idle');
+          dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'error', error: message });
+          return;
+        }
       }
-      setOriginalContent(content);
       setOriginalTitle(title);
-      setVersion(response.file.version);
       setSaveStatus('saved');
       dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saved' });
       setTimeout(() => setSaveStatus('idle'), 2000);
diff --git a/webui/src/components/Inspector/EndSceneModal.tsx b/webui/src/components/Inspector/EndSceneModal.tsx
index d008c369..42bf84be 100644
--- a/webui/src/components/Inspector/EndSceneModal.tsx
+++ b/webui/src/components/Inspector/EndSceneModal.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { BookOpen, CheckCircle2, Loader2, ScrollText, Users, X } from 'lucide-react';
 import { api } from '../../api/client';
 import type { EndSceneResponse } from '../../api/types';
@@ -19,14 +19,44 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose, o
   const [submitting, setSubmitting] = useState(false);
   const [result, setResult] = useState<EndSceneResponse | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const dialogRef = useRef<HTMLElement>(null);
+  const initialFocusRef = useRef<HTMLTextAreaElement>(null);
+  const openerRef = useRef<HTMLElement | null>(null);
+  const onCloseRef = useRef(onClose);
+  const submittingRef = useRef(submitting);
+  onCloseRef.current = onClose;
+  submittingRef.current = submitting;
 
   useEffect(() => {
+    openerRef.current =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    initialFocusRef.current?.focus();
+
     function onKey(e: KeyboardEvent) {
-      if (e.key === 'Escape' && !submitting) onClose();
+      if (e.key === 'Escape' && !submittingRef.current) onCloseRef.current();
+      if (e.key !== 'Tab') return;
+      const focusable = Array.from(
+        dialogRef.current?.querySelectorAll<HTMLElement>(
+          'button:not(:disabled), textarea:not(:disabled), input:not(:disabled), select:not(:disabled), [tabindex]:not([tabindex="-1"])',
+        ) ?? [],
+      );
+      if (!focusable.length) return;
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
     }
     window.addEventListener('keydown', onKey);
-    return () => window.removeEventListener('keydown', onKey);
-  }, [onClose, submitting]);
+    return () => {
+      window.removeEventListener('keydown', onKey);
+      openerRef.current?.focus();
+    };
+  }, []);
 
   async function handleEnd() {
     setSubmitting(true);
@@ -49,7 +79,13 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose, o
   if (result) {
     return (
       <div className={styles.scrim} role="presentation">
-        <section className={styles.modal} role="dialog" aria-modal="true" aria-label="Scene ended">
+        <section
+          ref={dialogRef}
+          className={styles.modal}
+          role="dialog"
+          aria-modal="true"
+          aria-label="Scene ended"
+        >
           <button className={styles.closeBtn} onClick={onClose} aria-label="Close">
             <X size={17} aria-hidden="true" strokeWidth={2.4} />
           </button>
@@ -105,7 +141,13 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose, o
 
   return (
     <div className={styles.scrim} role="presentation">
-      <section className={styles.modal} role="dialog" aria-modal="true" aria-label="End scene">
+      <section
+        ref={dialogRef}
+        className={styles.modal}
+        role="dialog"
+        aria-modal="true"
+        aria-label="End scene"
+      >
         <button
           className={styles.closeBtn}
           onClick={onClose}
@@ -127,6 +169,7 @@ export default function EndSceneModal({ worldId, sceneId, sceneTitle, onClose, o
         <label className={styles.field}>
           <span>Final text (optional)</span>
           <textarea
+            ref={initialFocusRef}
             className={styles.textarea}
             value={finalMarkdown}
             onChange={(e) => setFinalMarkdown(e.target.value)}
diff --git a/webui/src/pages/ChaptersPage.tsx b/webui/src/pages/ChaptersPage.tsx
index ee2e6776..b49a0bde 100644
--- a/webui/src/pages/ChaptersPage.tsx
+++ b/webui/src/pages/ChaptersPage.tsx
@@ -1,25 +1,46 @@
-import { useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { ArrowDown, ArrowUp, BookOpen, Edit3, RefreshCw } from 'lucide-react';
 import { api } from '../api/client';
 import type { StoryChapter } from '../api/types';
 import { worldbuildingApi } from '../api/worldbuilding';
+import { useAppState } from '../AppState';
 import ChapterEditor from '../components/ChapterEditor';
 import PageState from '../components/layout/PageState';
 import { useResource } from '../hooks/useResource';
 import styles from './ChaptersPage.module.css';
 
 export default function ChaptersPage({ worldId }: { worldId: string }) {
+  const { state } = useAppState();
   const resource = useResource(`chapters:${worldId}`, () => api.listChapters(worldId));
   const [localOrder, setLocalOrder] = useState<{ worldId: string; items: StoryChapter[] } | null>(
     null,
   );
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [reorderError, setReorderError] = useState<string | null>(null);
+  const [reordering, setReordering] = useState(false);
+  const reorderingRef = useRef(false);
   const chapters =
     localOrder?.worldId === worldId ? localOrder.items : (resource.data?.chapters ?? []);
   const selected = chapters.find((chapter) => chapter.id === selectedId) ?? null;
 
+  useEffect(() => {
+    setLocalOrder(null);
+  }, [resource.data]);
+
+  function selectChapter(chapter: StoryChapter) {
+    if (
+      selectedId &&
+      selectedId !== chapter.id &&
+      ['dirty', 'saving', 'error'].includes(state.editorSaveStatus) &&
+      !window.confirm('Discard unsaved chapter changes and switch chapters?')
+    ) {
+      return;
+    }
+    setSelectedId(chapter.id);
+  }
+
   async function moveChapter(index: number, offset: -1 | 1) {
+    if (reorderingRef.current) return;
     const target = index + offset;
     if (target < 0 || target >= chapters.length) return;
     const previous = chapters;
@@ -27,6 +48,8 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
     [next[index], next[target]] = [next[target], next[index]];
     setLocalOrder({ worldId, items: next });
     setReorderError(null);
+    reorderingRef.current = true;
+    setReordering(true);
     try {
       await worldbuildingApi.reorderChapters(
         worldId,
@@ -35,6 +58,9 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
     } catch (error) {
       setLocalOrder({ worldId, items: previous });
       setReorderError(error instanceof Error ? error.message : 'Unable to reorder chapters.');
+    } finally {
+      reorderingRef.current = false;
+      setReordering(false);
     }
   }
 
@@ -118,7 +144,7 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
             <div className={styles.actions}>
               <button
                 type="button"
-                onClick={() => setSelectedId(chapter.id)}
+                onClick={() => selectChapter(chapter)}
                 aria-label={`Edit ${chapter.title}`}
               >
                 <Edit3 aria-hidden="true" /> Edit
@@ -126,7 +152,7 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
               <button
                 type="button"
                 onClick={() => moveChapter(index, -1)}
-                disabled={index === 0}
+                disabled={reordering || index === 0}
                 aria-label={`Move ${chapter.title} previous`}
               >
                 <ArrowUp aria-hidden="true" />
@@ -134,7 +160,7 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
               <button
                 type="button"
                 onClick={() => moveChapter(index, 1)}
-                disabled={index === chapters.length - 1}
+                disabled={reordering || index === chapters.length - 1}
                 aria-label={`Move ${chapter.title} next`}
               >
                 <ArrowDown aria-hidden="true" />
diff --git a/webui/src/pages/ScenesPage.tsx b/webui/src/pages/ScenesPage.tsx
index bfe90130..b90e815c 100644
--- a/webui/src/pages/ScenesPage.tsx
+++ b/webui/src/pages/ScenesPage.tsx
@@ -12,7 +12,7 @@ export default function ScenesPage({ worldId }: { worldId: string }) {
   const resource = useResource(`scenes:${worldId}`, () => api.listScenes(worldId));
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [completed, setCompleted] = useState<Record<string, EndSceneResponse>>({});
-  const [showEnd, setShowEnd] = useState(false);
+  const [endTarget, setEndTarget] = useState<StoryScene | null>(null);
   const scenes = resource.data?.scenes ?? [];
   const selectedBase = scenes.find((scene) => scene.id === selectedId) ?? null;
   const selected =
@@ -44,7 +44,11 @@ export default function ScenesPage({ worldId }: { worldId: string }) {
 
   return (
     <main className={styles.workspace}>
-      <aside className={styles.listPane}>
+      <aside
+        className={styles.listPane}
+        aria-hidden={endTarget ? 'true' : undefined}
+        inert={endTarget ? true : undefined}
+      >
         <header>
           <div>
             <span>Narrative plan</span>
@@ -73,7 +77,12 @@ export default function ScenesPage({ worldId }: { worldId: string }) {
           {scenes.length} {scenes.length === 1 ? 'scene' : 'scenes'}
         </footer>
       </aside>
-      <section className={styles.detail} aria-label="Scene detail">
+      <section
+        className={styles.detail}
+        aria-label="Scene detail"
+        aria-hidden={endTarget ? 'true' : undefined}
+        inert={endTarget ? true : undefined}
+      >
         {selected ? (
           <>
             <header className={styles.detailHeader}>
@@ -82,7 +91,7 @@ export default function ScenesPage({ worldId }: { worldId: string }) {
                 <h2>{selected.title}</h2>
               </div>
               {selected.status !== 'completed' ? (
-                <button type="button" onClick={() => setShowEnd(true)}>
+                <button type="button" onClick={() => setEndTarget(selected)}>
                   End scene
                 </button>
               ) : null}
@@ -124,13 +133,15 @@ export default function ScenesPage({ worldId }: { worldId: string }) {
           </div>
         )}
       </section>
-      {showEnd && selected ? (
+      {endTarget ? (
         <EndSceneModal
           worldId={worldId}
-          sceneId={selected.id}
-          sceneTitle={selected.title}
-          onClose={() => setShowEnd(false)}
-          onEnded={(result) => setCompleted((previous) => ({ ...previous, [selected.id]: result }))}
+          sceneId={endTarget.id}
+          sceneTitle={endTarget.title}
+          onClose={() => setEndTarget(null)}
+          onEnded={(result) =>
+            setCompleted((previous) => ({ ...previous, [endTarget.id]: result }))
+          }
         />
       ) : null}
     </main>

From 6eb1f3647be6c36c18cb173119257fed54d63929 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 13:33:01 +0800
Subject: [PATCH 32/49] fix(webui): guard chapter workspace navigation

---
 webui/src/App.tsx                        |  24 ++---
 webui/src/__tests__/pages.test.tsx       |  54 ++++++++++-
 webui/src/__tests__/shell.test.tsx       |  73 ++++++++++++++
 webui/src/components/SettingsPage.tsx    | 116 +++++++++++++++++------
 webui/src/components/WorldSidebar.tsx    |  46 +++++----
 webui/src/hooks/useSafePageNavigation.ts |  25 +++++
 webui/src/pages/ChaptersPage.tsx         |  16 +++-
 7 files changed, 292 insertions(+), 62 deletions(-)
 create mode 100644 webui/src/hooks/useSafePageNavigation.ts

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index f73ce1c4..969ea435 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -17,6 +17,7 @@ import WorldDashboard from './components/WorldDashboard';
 import WorldOnboarding from './components/WorldOnboarding';
 import WorldSidebar from './components/WorldSidebar';
 import DesktopBoot from './DesktopBoot';
+import { useSafePageNavigation } from './hooks/useSafePageNavigation';
 import { useSSE } from './hooks/useSSE';
 import { I18nProvider } from './i18n';
 import DesktopShell from './shell/DesktopShell';
@@ -51,6 +52,7 @@ export function shouldRenderSessionsPage(page: AppPage, phase: AppState['appPhas
 
 function AppInner() {
   const { state, dispatch } = useAppState();
+  const safeNavigate = useSafePageNavigation();
   const [sidebarOpen, setSidebarOpen] = useState(window.innerWidth >= 768);
   const [inspectorOpen, setInspectorOpen] = useState(window.innerWidth >= 1180);
   const [helpOpen, setHelpOpen] = useState(false);
@@ -231,11 +233,7 @@ function AppInner() {
   const connState = useSSE(sseUrl, dispatch, state.lastSeq);
 
   const inDesktopShell = (children: ReactNode, overlays?: ReactNode) => (
-    <DesktopShell
-      page={state.currentPage}
-      onNavigate={(page) => dispatch({ type: 'SET_PAGE', page })}
-      overlays={overlays}
-    >
+    <DesktopShell page={state.currentPage} onNavigate={safeNavigate} overlays={overlays}>
       {children}
     </DesktopShell>
   );
@@ -298,17 +296,14 @@ function AppInner() {
 
   // Page-based rendering (overrides phase when navigating away from workbench)
   if (state.currentPage === 'settings') {
-    return inDesktopShell(<SettingsPage />);
+    return inDesktopShell(<SettingsPage />, narrativePageOverlays);
   }
 
   if (state.currentPage === 'editor' && state.activeEditorChapterId && state.worldId) {
     return (
       <div className={styles.editorOverlay}>
         <div className={styles.editorHeader}>
-          <button
-            className={styles.editorBackBtn}
-            onClick={() => dispatch({ type: 'SET_PAGE', page: 'overview' })}
-          >
+          <button className={styles.editorBackBtn} onClick={() => safeNavigate('overview')}>
             <ArrowLeft size={15} aria-hidden="true" strokeWidth={2.3} />
             返回工作台
           </button>
@@ -342,12 +337,9 @@ function AppInner() {
   if (state.currentPage === 'overview' && state.worldId) {
     return inDesktopShell(
       <Suspense fallback={<Skeleton />}>
-        <OverviewPage
-          worldId={state.worldId}
-          sessions={state.sessions}
-          onNavigate={(page) => dispatch({ type: 'SET_PAGE', page })}
-        />
+        <OverviewPage worldId={state.worldId} sessions={state.sessions} onNavigate={safeNavigate} />
       </Suspense>,
+      narrativePageOverlays,
     );
   }
 
@@ -356,6 +348,7 @@ function AppInner() {
       <Suspense fallback={<Skeleton />}>
         <WorldPage worldId={state.worldId} />
       </Suspense>,
+      narrativePageOverlays,
     );
   }
 
@@ -364,6 +357,7 @@ function AppInner() {
       <Suspense fallback={<Skeleton />}>
         <CharactersPage worldId={state.worldId} />
       </Suspense>,
+      narrativePageOverlays,
     );
   }
 
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 6cde7026..d5121999 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -246,6 +246,7 @@ describe('Chapter and scene pages', () => {
   it('disables chapter moves while a reorder request is pending', async () => {
     const reorder = deferred<{ ok: boolean }>();
     vi.mocked(worldbuildingApi.reorderChapters).mockClear();
+    vi.mocked(api.listChapters).mockClear();
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
     vi.mocked(worldbuildingApi.reorderChapters).mockReturnValue(reorder.promise);
 
@@ -260,12 +261,21 @@ describe('Chapter and scene pages', () => {
     fireEvent.click(movePrevious);
 
     const moveNext = screen.getByRole('button', { name: 'Move The Rain Archive next' });
+    const refresh = screen.getByRole('button', { name: 'Refresh' });
     expect(moveNext).toBeDisabled();
+    expect(refresh).toBeDisabled();
+    expect(screen.getAllByRole('heading', { level: 2 }).map((item) => item.textContent)).toEqual([
+      'The Rain Archive',
+      'Ashes at Dawn',
+    ]);
+    fireEvent.click(refresh);
     fireEvent.click(moveNext);
     expect(worldbuildingApi.reorderChapters).toHaveBeenCalledTimes(1);
+    expect(api.listChapters).toHaveBeenCalledTimes(1);
 
     await act(async () => reorder.resolve({ ok: true }));
     await waitFor(() => expect(moveNext).not.toBeDisabled());
+    expect(refresh).not.toBeDisabled();
   });
 
   it('reconciles local chapter order with a fresh server response', async () => {
@@ -293,7 +303,9 @@ describe('Chapter and scene pages', () => {
       </AppStateProvider>,
     );
     fireEvent.click(await screen.findByRole('button', { name: 'Move The Rain Archive previous' }));
-    fireEvent.click(screen.getByRole('button', { name: 'Refresh' }));
+    const refresh = screen.getByRole('button', { name: 'Refresh' });
+    await waitFor(() => expect(refresh).not.toBeDisabled());
+    fireEvent.click(refresh);
 
     expect(await screen.findByRole('heading', { name: 'Rain Archive Revised' })).toBeDefined();
     expect(screen.getByRole('heading', { name: 'A New Signal' })).toBeDefined();
@@ -430,6 +442,46 @@ describe('Chapter and scene pages', () => {
     expect(editor).toHaveValue('Unsaved rain.');
   });
 
+  it('blocks chapter switching without confirmation while a save is pending', async () => {
+    const saving = deferred<Awaited<ReturnType<typeof api.saveWorkspaceFile>>>();
+    const confirm = vi.spyOn(window, 'confirm');
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: 'chapters/world-1/chapter-2.md',
+        content: 'Original draft.',
+        encoding: 'utf-8',
+        updated_at: '2026-06-19T09:00:00Z',
+        version: 'v7',
+      },
+    });
+    vi.mocked(api.saveWorkspaceFile).mockReturnValue(saving.promise);
+
+    render(
+      <AppStateProvider>
+        <ChaptersPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Edit The Rain Archive' }));
+    const editor = await screen.findByRole('textbox', { name: 'Chapter content' });
+    fireEvent.change(editor, { target: { value: 'Saving rain.' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save chapter' }));
+    expect(screen.getByRole('button', { name: 'Save chapter' })).toHaveTextContent('Saving...');
+    fireEvent.click(screen.getByRole('button', { name: 'Edit Ashes at Dawn' }));
+
+    expect(confirm).not.toHaveBeenCalled();
+    expect(screen.getByRole('region', { name: 'Editing The Rain Archive' })).toBeDefined();
+    expect(editor).toHaveValue('Saving rain.');
+
+    await act(async () =>
+      saving.resolve({
+        ok: true,
+        file: { path: 'chapters/world-1/chapter-2.md', updated_at: 'now', version: 'v8' },
+      }),
+    );
+  });
+
   it('commits a successful file version before reporting a title metadata failure', async () => {
     vi.mocked(api.saveWorkspaceFile).mockClear();
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: chapterFixtures });
diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index cd127326..f19efba3 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -3,6 +3,7 @@ import type { ReactNode } from 'react';
 import { fireEvent, render, screen, within } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { AppStateProvider, useAppState } from '../AppState';
+import { useSafePageNavigation } from '../hooks/useSafePageNavigation';
 import { I18nProvider } from '../i18n';
 import DesktopShell from '../shell/DesktopShell';
 import { desktopPages, readStoredDesktopPage, writeStoredDesktopPage } from '../shell/navigation';
@@ -71,6 +72,78 @@ describe('desktop shell', () => {
     );
   }
 
+  function SafeNavigationHarness() {
+    const { state, dispatch } = useAppState();
+    const navigate = useSafePageNavigation();
+    return (
+      <>
+        <button onClick={() => dispatch({ type: 'SET_PAGE', page: 'chapters' })}>
+          Start chapters
+        </button>
+        <button onClick={() => dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'dirty' })}>
+          Make dirty
+        </button>
+        <button onClick={() => dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saving' })}>
+          Start saving
+        </button>
+        <output aria-label="Current page">{state.currentPage}</output>
+        <DesktopShell page={state.currentPage} onNavigate={navigate}>
+          Embedded chapter editor
+        </DesktopShell>
+      </>
+    );
+  }
+
+  function renderSafeNavigation() {
+    return render(
+      <I18nProvider defaultLocale="en">
+        <AppStateProvider>
+          <SafeNavigationHarness />
+        </AppStateProvider>
+      </I18nProvider>,
+    );
+  }
+
+  it('keeps dirty Chapters navigation on the page when Overview or Scenes is cancelled', () => {
+    vi.spyOn(window, 'confirm').mockReturnValue(false);
+    renderSafeNavigation();
+    fireEvent.click(screen.getByRole('button', { name: 'Start chapters' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Make dirty' }));
+    const navigation = screen.getByRole('navigation', { name: 'Primary navigation' });
+
+    fireEvent.click(within(navigation).getAllByRole('button')[0]);
+    fireEvent.click(within(navigation).getByRole('button', { name: 'Scenes 场景' }));
+
+    expect(screen.getByLabelText('Current page')).toHaveTextContent('chapters');
+    expect(window.confirm).toHaveBeenCalledTimes(2);
+  });
+
+  it('allows confirmed dirty navigation from Chapters to Scenes', () => {
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    renderSafeNavigation();
+    fireEvent.click(screen.getByRole('button', { name: 'Start chapters' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Make dirty' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Scenes 场景' }));
+
+    expect(screen.getByLabelText('Current page')).toHaveTextContent('scenes');
+    fireEvent.click(
+      screen.getByRole('navigation', { name: 'Primary navigation' }).querySelectorAll('button')[0],
+    );
+    expect(window.confirm).toHaveBeenCalledTimes(1);
+    expect(screen.getByLabelText('Current page')).toHaveTextContent('overview');
+  });
+
+  it('blocks navigation while a chapter save is pending without prompting', () => {
+    const confirm = vi.spyOn(window, 'confirm');
+    renderSafeNavigation();
+    fireEvent.click(screen.getByRole('button', { name: 'Start chapters' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Start saving' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Scenes 场景' }));
+
+    expect(screen.getByLabelText('Current page')).toHaveTextContent('chapters');
+    expect(confirm).not.toHaveBeenCalled();
+  });
+
   it('renders exactly ten bilingual navigation buttons and dispatches navigation', () => {
     const dispatch = vi.fn();
     renderShell('overview', (page) => dispatch({ type: 'SET_PAGE', page }));
diff --git a/webui/src/components/SettingsPage.tsx b/webui/src/components/SettingsPage.tsx
index b77b65d3..3ae38fb8 100644
--- a/webui/src/components/SettingsPage.tsx
+++ b/webui/src/components/SettingsPage.tsx
@@ -10,6 +10,7 @@ import {
   restartDesktopRuntime,
   type DesktopRuntimeStatus,
 } from '../desktop';
+import { useSafePageNavigation } from '../hooks/useSafePageNavigation';
 import styles from './SettingsPage.module.css';
 
 interface ConfigState {
@@ -39,6 +40,7 @@ const STYLE_OPTIONS = [
 
 export default function SettingsPage() {
   const { dispatch } = useAppState();
+  const safeNavigate = useSafePageNavigation();
 
   // LLM config
   const [config, setConfig] = useState<ConfigState | null>(null);
@@ -50,7 +52,9 @@ export default function SettingsPage() {
   const [showKey, setShowKey] = useState(false);
   const [saving, setSaving] = useState(false);
   const [testing, setTesting] = useState(false);
-  const [llmStatus, setLlmStatus] = useState<'idle' | 'saved' | 'test_ok' | 'test_fail' | 'error'>('idle');
+  const [llmStatus, setLlmStatus] = useState<'idle' | 'saved' | 'test_ok' | 'test_fail' | 'error'>(
+    'idle',
+  );
   const [llmError, setLlmError] = useState('');
 
   // User preferences
@@ -67,7 +71,8 @@ export default function SettingsPage() {
   const [diagnosticMsg, setDiagnosticMsg] = useState('');
 
   useEffect(() => {
-    api.getConfig()
+    api
+      .getConfig()
       .then((data) => {
         setConfig(data);
         setProvider(data.provider || 'anthropic');
@@ -82,7 +87,8 @@ export default function SettingsPage() {
   }, []);
 
   useEffect(() => {
-    api.getPreferences()
+    api
+      .getPreferences()
       .then((prefs) => {
         if (prefs.default_genre) setGenre(prefs.default_genre);
         if (prefs.preferred_style) setStyle(prefs.preferred_style);
@@ -146,7 +152,10 @@ export default function SettingsPage() {
         preferred_style: style,
         allow_usage_logs: allowUsageLogs,
       });
-      dispatch({ type: 'SET_USER_PREFERENCES', prefs: { default_genre: genre, preferred_style: style } });
+      dispatch({
+        type: 'SET_USER_PREFERENCES',
+        prefs: { default_genre: genre, preferred_style: style },
+      });
       setPrefSaved(true);
       setTimeout(() => setPrefSaved(false), 2000);
     } catch (error) {
@@ -166,11 +175,14 @@ export default function SettingsPage() {
     setRuntime(response?.status ?? null);
     setDiagnosticMsg(response?.ok ? 'Merak 已重新打开。' : 'Merak 没能完成重新打开。');
     if (response?.ok) {
-      api.getConfig().then((data) => {
-        setConfig(data);
-        setProvider(data.provider || 'anthropic');
-        setModel(data.default_model || '');
-      }).catch(() => {});
+      api
+        .getConfig()
+        .then((data) => {
+          setConfig(data);
+          setProvider(data.provider || 'anthropic');
+          setModel(data.default_model || '');
+        })
+        .catch(() => {});
     }
   };
 
@@ -183,10 +195,7 @@ export default function SettingsPage() {
   return (
     <div className={styles.page}>
       <div className={styles.header}>
-        <button
-          className={styles.backBtn}
-          onClick={() => dispatch({ type: 'SET_PAGE', page: 'overview' })}
-        >
+        <button className={styles.backBtn} onClick={() => safeNavigate('overview')}>
           <ArrowLeft size={15} aria-hidden="true" strokeWidth={2.3} />
           返回工作台
         </button>
@@ -199,13 +208,21 @@ export default function SettingsPage() {
           <h2 className={styles.sectionTitle}>大模型配置</h2>
 
           {!config ? (
-            llmStatus === 'error' ? <div className={styles.error}>{llmError}</div> : <p className={styles.hint}>正在加载配置...</p>
+            llmStatus === 'error' ? (
+              <div className={styles.error}>{llmError}</div>
+            ) : (
+              <p className={styles.hint}>正在加载配置...</p>
+            )
           ) : (
             <>
               <div className={styles.field}>
                 <label className={styles.label}>
                   服务类型
-                  <select value={provider} onChange={(e) => setProvider(e.target.value)} className={styles.select}>
+                  <select
+                    value={provider}
+                    onChange={(e) => setProvider(e.target.value)}
+                    className={styles.select}
+                  >
                     <option value="anthropic">Anthropic</option>
                     <option value="openai">OpenAI</option>
                     <option value="custom">Custom</option>
@@ -224,7 +241,11 @@ export default function SettingsPage() {
                       placeholder={config.api_key_masked || 'sk-...'}
                       className={styles.input}
                     />
-                    <button type="button" onClick={() => setShowKey(!showKey)} className={styles.toggleBtn}>
+                    <button
+                      type="button"
+                      onClick={() => setShowKey(!showKey)}
+                      className={styles.toggleBtn}
+                    >
                       {showKey ? '隐藏' : '显示'}
                     </button>
                   </div>
@@ -265,7 +286,9 @@ export default function SettingsPage() {
                     min={256}
                     step={256}
                     value={maxOutputTokens}
-                    onChange={(e) => setMaxOutputTokens(Math.max(256, Number(e.target.value) || 256))}
+                    onChange={(e) =>
+                      setMaxOutputTokens(Math.max(256, Number(e.target.value) || 256))
+                    }
                     placeholder={String(config.max_output_tokens || 4096)}
                     className={styles.input}
                   />
@@ -300,9 +323,19 @@ export default function SettingsPage() {
               <div className={styles.field}>
                 <label className={styles.label}>
                   默认题材
-                  <select value={genre} onChange={(e) => { setGenre(e.target.value); setPrefSaved(false); }} className={styles.select} disabled={prefSaving}>
+                  <select
+                    value={genre}
+                    onChange={(e) => {
+                      setGenre(e.target.value);
+                      setPrefSaved(false);
+                    }}
+                    className={styles.select}
+                    disabled={prefSaving}
+                  >
                     {GENRE_OPTIONS.map((g) => (
-                      <option key={g.value} value={g.value}>{g.label}</option>
+                      <option key={g.value} value={g.value}>
+                        {g.label}
+                      </option>
                     ))}
                   </select>
                 </label>
@@ -311,9 +344,19 @@ export default function SettingsPage() {
               <div className={styles.field}>
                 <label className={styles.label}>
                   偏好风格
-                  <select value={style} onChange={(e) => { setStyle(e.target.value); setPrefSaved(false); }} className={styles.select} disabled={prefSaving}>
+                  <select
+                    value={style}
+                    onChange={(e) => {
+                      setStyle(e.target.value);
+                      setPrefSaved(false);
+                    }}
+                    className={styles.select}
+                    disabled={prefSaving}
+                  >
                     {STYLE_OPTIONS.map((s) => (
-                      <option key={s.value} value={s.value}>{s.label}</option>
+                      <option key={s.value} value={s.value}>
+                        {s.label}
+                      </option>
                     ))}
                   </select>
                 </label>
@@ -328,7 +371,10 @@ export default function SettingsPage() {
                     role="switch"
                     aria-checked={allowUsageLogs}
                     aria-label="切换使用情况日志"
-                    onClick={() => { setAllowUsageLogs((prev) => !prev); setPrefSaved(false); }}
+                    onClick={() => {
+                      setAllowUsageLogs((prev) => !prev);
+                      setPrefSaved(false);
+                    }}
                     disabled={prefSaving}
                   >
                     <span className={styles.toggleKnob} />
@@ -338,7 +384,11 @@ export default function SettingsPage() {
               </div>
 
               <div className={styles.actions}>
-                <button onClick={handleSavePrefs} disabled={prefSaving} className={styles.btnPrimary}>
+                <button
+                  onClick={handleSavePrefs}
+                  disabled={prefSaving}
+                  className={styles.btnPrimary}
+                >
                   {prefSaving ? '保存中...' : '保存偏好'}
                 </button>
               </div>
@@ -370,10 +420,22 @@ export default function SettingsPage() {
               </div>
               {runtime?.error && <div className={styles.error}>{runtime.error}</div>}
               <div className={styles.actions}>
-                <button type="button" onClick={refreshRuntime} className={styles.btn}>刷新</button>
-                <button type="button" onClick={handleRestartRuntime} className={styles.btn}>重新打开 Merak</button>
-                <button type="button" onClick={() => openDiagnosticsFolder()} className={styles.btn}>打开报告文件夹</button>
-                <button type="button" onClick={handleExportDiagnostics} className={styles.btn}>导出故障报告</button>
+                <button type="button" onClick={refreshRuntime} className={styles.btn}>
+                  刷新
+                </button>
+                <button type="button" onClick={handleRestartRuntime} className={styles.btn}>
+                  重新打开 Merak
+                </button>
+                <button
+                  type="button"
+                  onClick={() => openDiagnosticsFolder()}
+                  className={styles.btn}
+                >
+                  打开报告文件夹
+                </button>
+                <button type="button" onClick={handleExportDiagnostics} className={styles.btn}>
+                  导出故障报告
+                </button>
               </div>
               {diagnosticMsg && <div className={styles.ok}>{diagnosticMsg}</div>}
             </div>
diff --git a/webui/src/components/WorldSidebar.tsx b/webui/src/components/WorldSidebar.tsx
index 9d6d2c6f..d89afaf0 100644
--- a/webui/src/components/WorldSidebar.tsx
+++ b/webui/src/components/WorldSidebar.tsx
@@ -15,12 +15,13 @@ import {
 } from 'lucide-react';
 import { api } from '../api/client';
 import { useAppState } from '../AppState';
+import { useSafePageNavigation } from '../hooks/useSafePageNavigation';
 import BrandMark from './BrandMark';
 import ContextMeter from './Sidebar/ContextMeter';
 import ModelSelector from './Sidebar/ModelSelector';
 import PipelineNavigator from './Sidebar/PipelineNavigator';
-import WorkflowMonitor from './Sidebar/WorkflowMonitor';
 import SessionList from './Sidebar/SessionList';
+import WorkflowMonitor from './Sidebar/WorkflowMonitor';
 import WorldSelector from './Sidebar/WorldSelector';
 import styles from './WorldSidebar.module.css';
 
@@ -33,15 +34,19 @@ function AgentIcon({ kind }: { kind: string }) {
   const common = { size: 15, 'aria-hidden': true as const, strokeWidth: 2.3 };
   if (kind === 'god' || kind === '0' || kind === 'ruler') return <Crown {...common} />;
   if (kind === 'map_manager' || kind === '1' || kind === 'cartographer') return <Map {...common} />;
-  if (kind === 'history_manager' || kind === '2' || kind === 'scribe') return <ScrollText {...common} />;
-  if (kind === 'magic_system_manager' || kind === '3' || kind === 'oracle') return <Sparkles {...common} />;
-  if (kind === 'faction_manager' || kind === '4' || kind === 'warrior') return <Swords {...common} />;
+  if (kind === 'history_manager' || kind === '2' || kind === 'scribe')
+    return <ScrollText {...common} />;
+  if (kind === 'magic_system_manager' || kind === '3' || kind === 'oracle')
+    return <Sparkles {...common} />;
+  if (kind === 'faction_manager' || kind === '4' || kind === 'warrior')
+    return <Swords {...common} />;
   if (kind === 'group' || kind === '6' || kind === 'collective') return <UsersRound {...common} />;
   return <UserRound {...common} />;
 }
 
 export default function WorldSidebar({ open = true, onClose }: WorldSidebarProps) {
   const { state, dispatch } = useAppState();
+  const safeNavigate = useSafePageNavigation();
 
   const currentWorld = state.worlds.find((w) => w.id === state.worldId);
 
@@ -63,12 +68,17 @@ export default function WorldSidebar({ open = true, onClose }: WorldSidebarProps
       </div>
 
       {/* World Header — click to go back to dashboard */}
-      <div className={styles.worldHeader} onClick={handleBackToDashboard} role="button" tabIndex={0}
-        onKeyDown={(e) => { if (e.key === 'Enter') handleBackToDashboard(); }}>
+      <div
+        className={styles.worldHeader}
+        onClick={handleBackToDashboard}
+        role="button"
+        tabIndex={0}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') handleBackToDashboard();
+        }}
+      >
         <ArrowLeft size={15} aria-hidden="true" strokeWidth={2.4} />
-        <span className={styles.worldHeaderName}>
-          {currentWorld?.name ?? 'Select World'}
-        </span>
+        <span className={styles.worldHeaderName}>{currentWorld?.name ?? 'Select World'}</span>
       </div>
 
       <WorldSelector />
@@ -139,16 +149,18 @@ export default function WorldSidebar({ open = true, onClose }: WorldSidebarProps
               <div
                 key={agent.id}
                 className={
-                  agent.id === state.agentId
-                    ? styles.agentListItemActive
-                    : styles.agentListItem
+                  agent.id === state.agentId ? styles.agentListItemActive : styles.agentListItem
                 }
                 onClick={handleAgentClick}
                 role="button"
                 tabIndex={0}
-                onKeyDown={(e) => { if (e.key === 'Enter') handleAgentClick(); }}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') handleAgentClick();
+                }}
               >
-                <span className={styles.agentIcon}><AgentIcon kind={kind} /></span>
+                <span className={styles.agentIcon}>
+                  <AgentIcon kind={kind} />
+                </span>
                 <span>{agent.name ?? agent.id}</span>
               </div>
             );
@@ -163,10 +175,12 @@ export default function WorldSidebar({ open = true, onClose }: WorldSidebarProps
 
       <div
         className={styles.settingsTrigger}
-        onClick={() => dispatch({ type: 'SET_PAGE', page: 'settings' })}
+        onClick={() => safeNavigate('settings')}
         role="button"
         tabIndex={0}
-        onKeyDown={(e) => { if (e.key === 'Enter') dispatch({ type: 'SET_PAGE', page: 'settings' }); }}
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') safeNavigate('settings');
+        }}
       >
         <Settings size={15} aria-hidden="true" strokeWidth={2.3} />
         Settings
diff --git a/webui/src/hooks/useSafePageNavigation.ts b/webui/src/hooks/useSafePageNavigation.ts
new file mode 100644
index 00000000..0e0b682d
--- /dev/null
+++ b/webui/src/hooks/useSafePageNavigation.ts
@@ -0,0 +1,25 @@
+import { useCallback } from 'react';
+import { useAppState, type AppPage } from '../AppState';
+
+export function useSafePageNavigation() {
+  const { state, dispatch } = useAppState();
+
+  return useCallback(
+    (page: AppPage) => {
+      if (page === state.currentPage) return true;
+      if (state.editorSaveStatus === 'saving') return false;
+      if (
+        ['dirty', 'error'].includes(state.editorSaveStatus) &&
+        !window.confirm('Discard unsaved chapter changes and leave this page?')
+      ) {
+        return false;
+      }
+      if (['dirty', 'error'].includes(state.editorSaveStatus)) {
+        dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'idle' });
+      }
+      dispatch({ type: 'SET_PAGE', page });
+      return true;
+    },
+    [dispatch, state.currentPage, state.editorSaveStatus],
+  );
+}
diff --git a/webui/src/pages/ChaptersPage.tsx b/webui/src/pages/ChaptersPage.tsx
index b49a0bde..495c2013 100644
--- a/webui/src/pages/ChaptersPage.tsx
+++ b/webui/src/pages/ChaptersPage.tsx
@@ -19,19 +19,22 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
   const [reorderError, setReorderError] = useState<string | null>(null);
   const [reordering, setReordering] = useState(false);
   const reorderingRef = useRef(false);
+  const resourceDataRef = useRef(resource.data);
+  resourceDataRef.current = resource.data;
   const chapters =
     localOrder?.worldId === worldId ? localOrder.items : (resource.data?.chapters ?? []);
   const selected = chapters.find((chapter) => chapter.id === selectedId) ?? null;
 
   useEffect(() => {
-    setLocalOrder(null);
+    if (!reorderingRef.current) setLocalOrder(null);
   }, [resource.data]);
 
   function selectChapter(chapter: StoryChapter) {
+    if (selectedId && selectedId !== chapter.id && state.editorSaveStatus === 'saving') return;
     if (
       selectedId &&
       selectedId !== chapter.id &&
-      ['dirty', 'saving', 'error'].includes(state.editorSaveStatus) &&
+      ['dirty', 'error'].includes(state.editorSaveStatus) &&
       !window.confirm('Discard unsaved chapter changes and switch chapters?')
     ) {
       return;
@@ -44,6 +47,7 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
     const target = index + offset;
     if (target < 0 || target >= chapters.length) return;
     const previous = chapters;
+    const resourceAtStart = resource.data;
     const next = [...chapters];
     [next[index], next[target]] = [next[target], next[index]];
     setLocalOrder({ worldId, items: next });
@@ -61,6 +65,7 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
     } finally {
       reorderingRef.current = false;
       setReordering(false);
+      if (resourceDataRef.current !== resourceAtStart) setLocalOrder(null);
     }
   }
 
@@ -95,7 +100,12 @@ export default function ChaptersPage({ worldId }: { worldId: string }) {
           <h1>Chapters</h1>
           <p>Arrange the manuscript and open a chapter without leaving the planning workspace.</p>
         </div>
-        <button type="button" className={styles.refresh} onClick={resource.retry}>
+        <button
+          type="button"
+          className={styles.refresh}
+          onClick={resource.retry}
+          disabled={reordering}
+        >
           <RefreshCw aria-hidden="true" /> Refresh
         </button>
       </header>

From f7a41dd629a8835623568e3acb70301c1cd607c4 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 13:45:03 +0800
Subject: [PATCH 33/49] fix(webui): guard world changes and revert drafts

---
 webui/src/__tests__/shell.test.tsx       | 114 ++++++++++++++++++++++-
 webui/src/hooks/useSafePageNavigation.ts |  49 +++++++---
 webui/src/shell/DesktopShell.tsx         |   8 +-
 3 files changed, 152 insertions(+), 19 deletions(-)

diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index f19efba3..cfa983ff 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -2,8 +2,9 @@ import { readFileSync } from 'node:fs';
 import type { ReactNode } from 'react';
 import { fireEvent, render, screen, within } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { shouldWarnBeforeClose } from '../App';
 import { AppStateProvider, useAppState } from '../AppState';
-import { useSafePageNavigation } from '../hooks/useSafePageNavigation';
+import { useSafeNavigation } from '../hooks/useSafePageNavigation';
 import { I18nProvider } from '../i18n';
 import DesktopShell from '../shell/DesktopShell';
 import { desktopPages, readStoredDesktopPage, writeStoredDesktopPage } from '../shell/navigation';
@@ -74,7 +75,8 @@ describe('desktop shell', () => {
 
   function SafeNavigationHarness() {
     const { state, dispatch } = useAppState();
-    const navigate = useSafePageNavigation();
+    const { requestPageChange } = useSafeNavigation();
+    const activeFile = state.workspaceFiles.find((file) => file.id === state.activeEditorFileId);
     return (
       <>
         <button onClick={() => dispatch({ type: 'SET_PAGE', page: 'chapters' })}>
@@ -86,8 +88,62 @@ describe('desktop shell', () => {
         <button onClick={() => dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saving' })}>
           Start saving
         </button>
+        <button
+          onClick={() => {
+            dispatch({
+              type: 'SET_WORLDS',
+              worlds: [
+                { id: 'world-1', name: 'World One', description: '', created_at: '' },
+                { id: 'world-2', name: 'World Two', description: '', created_at: '' },
+              ],
+            });
+            dispatch({ type: 'SET_WORLD', worldId: 'world-1' });
+          }}
+        >
+          Setup worlds
+        </button>
+        <button
+          onClick={() => {
+            dispatch({
+              type: 'SET_WORKSPACE_FILES',
+              files: [
+                {
+                  id: 'draft.md',
+                  path: 'draft.md',
+                  name: 'draft.md',
+                  ext: '.md',
+                  mime: 'text/markdown',
+                  size: 8,
+                  updated_at: '',
+                  dirty: false,
+                },
+              ],
+            });
+            dispatch({ type: 'OPEN_WORKSPACE_FILE', fileId: 'draft.md' });
+            dispatch({
+              type: 'SET_EDITOR_CONTENT',
+              fileId: 'draft.md',
+              content: {
+                path: 'draft.md',
+                content: 'Original',
+                encoding: 'utf-8',
+                updated_at: '',
+                version: 'v1',
+              },
+            });
+            dispatch({ type: 'UPDATE_EDITOR_BUFFER', fileId: 'draft.md', content: 'Unsaved draft' });
+          }}
+        >
+          Open workspace draft
+        </button>
         <output aria-label="Current page">{state.currentPage}</output>
-        <DesktopShell page={state.currentPage} onNavigate={navigate}>
+        <output aria-label="Editor buffer">
+          {state.activeEditorFileId ? state.editorBuffers[state.activeEditorFileId] : ''}
+        </output>
+        <output aria-label="Editor status">{state.editorSaveStatus}</output>
+        <output aria-label="File dirty">{String(activeFile?.dirty ?? false)}</output>
+        <output aria-label="Warn before close">{String(shouldWarnBeforeClose(state))}</output>
+        <DesktopShell page={state.currentPage} onNavigate={requestPageChange}>
           Embedded chapter editor
         </DesktopShell>
       </>
@@ -144,6 +200,58 @@ describe('desktop shell', () => {
     expect(confirm).not.toHaveBeenCalled();
   });
 
+  it('blocks world changes while saving without prompting', () => {
+    const confirm = vi.spyOn(window, 'confirm');
+    renderSafeNavigation();
+    fireEvent.click(screen.getByRole('button', { name: 'Setup worlds' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Start saving' }));
+
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'world-2' } });
+
+    expect(screen.getByRole('combobox')).toHaveValue('world-1');
+    expect(confirm).not.toHaveBeenCalled();
+  });
+
+  it('retains the current world on cancel and changes it after confirmed discard', () => {
+    const confirm = vi.spyOn(window, 'confirm').mockReturnValue(false);
+    renderSafeNavigation();
+    fireEvent.click(screen.getByRole('button', { name: 'Setup worlds' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Make dirty' }));
+
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'world-2' } });
+    expect(screen.getByRole('combobox')).toHaveValue('world-1');
+    expect(screen.getByLabelText('Editor status')).toHaveTextContent('dirty');
+
+    confirm.mockReturnValue(true);
+    fireEvent.change(screen.getByRole('combobox'), { target: { value: 'world-2' } });
+    expect(screen.getByRole('combobox')).toHaveValue('world-2');
+    expect(screen.getByLabelText('Editor status')).toHaveTextContent('idle');
+    expect(confirm).toHaveBeenCalledTimes(2);
+  });
+
+  it('preserves a cancelled workspace draft and reverts it after confirmed navigation', () => {
+    const confirm = vi.spyOn(window, 'confirm').mockReturnValue(false);
+    renderSafeNavigation();
+    fireEvent.click(screen.getByRole('button', { name: 'Open workspace draft' }));
+    const navigation = screen.getByRole('navigation', { name: 'Primary navigation' });
+
+    fireEvent.click(within(navigation).getAllByRole('button')[5]);
+    expect(screen.getByLabelText('Current page')).toHaveTextContent('overview');
+    expect(screen.getByLabelText('Editor buffer')).toHaveTextContent('Unsaved draft');
+    expect(screen.getByLabelText('File dirty')).toHaveTextContent('true');
+    expect(screen.getByLabelText('Warn before close')).toHaveTextContent('true');
+
+    confirm.mockReturnValue(true);
+    fireEvent.click(within(navigation).getAllByRole('button')[5]);
+    fireEvent.click(within(navigation).getAllByRole('button')[8]);
+
+    expect(screen.getByLabelText('Current page')).toHaveTextContent('files');
+    expect(screen.getByLabelText('Editor buffer')).toHaveTextContent('Original');
+    expect(screen.getByLabelText('File dirty')).toHaveTextContent('false');
+    expect(screen.getByLabelText('Editor status')).toHaveTextContent('idle');
+    expect(screen.getByLabelText('Warn before close')).toHaveTextContent('false');
+  });
+
   it('renders exactly ten bilingual navigation buttons and dispatches navigation', () => {
     const dispatch = vi.fn();
     renderShell('overview', (page) => dispatch({ type: 'SET_PAGE', page }));
diff --git a/webui/src/hooks/useSafePageNavigation.ts b/webui/src/hooks/useSafePageNavigation.ts
index 0e0b682d..184c2354 100644
--- a/webui/src/hooks/useSafePageNavigation.ts
+++ b/webui/src/hooks/useSafePageNavigation.ts
@@ -2,24 +2,49 @@ import { useCallback } from 'react';
 import { useAppState, type AppPage } from '../AppState';
 
 export function useSafePageNavigation() {
+  return useSafeNavigation().requestPageChange;
+}
+
+export function useSafeNavigation() {
   const { state, dispatch } = useAppState();
 
-  return useCallback(
-    (page: AppPage) => {
-      if (page === state.currentPage) return true;
-      if (state.editorSaveStatus === 'saving') return false;
-      if (
-        ['dirty', 'error'].includes(state.editorSaveStatus) &&
-        !window.confirm('Discard unsaved chapter changes and leave this page?')
-      ) {
-        return false;
-      }
-      if (['dirty', 'error'].includes(state.editorSaveStatus)) {
+  const confirmDiscard = useCallback(() => {
+    if (state.editorSaveStatus === 'saving') return false;
+    if (
+      ['dirty', 'error'].includes(state.editorSaveStatus) &&
+      !window.confirm('Discard unsaved chapter changes and leave this page?')
+    ) {
+      return false;
+    }
+    if (['dirty', 'error'].includes(state.editorSaveStatus)) {
+      if (state.activeEditorFileId) {
+        dispatch({ type: 'REVERT_EDITOR_BUFFER', fileId: state.activeEditorFileId });
+      } else {
         dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'idle' });
       }
+    }
+    return true;
+  }, [dispatch, state.activeEditorFileId, state.editorSaveStatus]);
+
+  const requestPageChange = useCallback(
+    (page: AppPage) => {
+      if (page === state.currentPage) return true;
+      if (!confirmDiscard()) return false;
       dispatch({ type: 'SET_PAGE', page });
       return true;
     },
-    [dispatch, state.currentPage, state.editorSaveStatus],
+    [confirmDiscard, dispatch, state.currentPage],
+  );
+
+  const requestWorldChange = useCallback(
+    (worldId: string | null) => {
+      if (worldId === state.worldId) return true;
+      if (!confirmDiscard()) return false;
+      dispatch({ type: 'SET_WORLD', worldId });
+      return true;
+    },
+    [confirmDiscard, dispatch, state.worldId],
   );
+
+  return { requestPageChange, requestWorldChange };
 }
diff --git a/webui/src/shell/DesktopShell.tsx b/webui/src/shell/DesktopShell.tsx
index 6cf364ec..a8d5b3be 100644
--- a/webui/src/shell/DesktopShell.tsx
+++ b/webui/src/shell/DesktopShell.tsx
@@ -3,6 +3,7 @@ import { ChevronDown, Globe2, Search } from 'lucide-react';
 import type { AppPage } from '../AppState';
 import { useAppState } from '../AppState';
 import merakLogo from '../assets/merak-logo.svg';
+import { useSafeNavigation } from '../hooks/useSafePageNavigation';
 import { useI18n } from '../i18n';
 import styles from './DesktopShell.module.css';
 import { desktopPages } from './navigation';
@@ -15,7 +16,8 @@ interface DesktopShellProps {
 }
 
 export default function DesktopShell({ page, onNavigate, children, overlays }: DesktopShellProps) {
-  const { state, dispatch } = useAppState();
+  const { state } = useAppState();
+  const { requestWorldChange } = useSafeNavigation();
   const { t } = useI18n();
   const selectedWorld = state.worlds.find((world) => world.id === state.worldId);
   const worldName = selectedWorld?.name || t('shell.noWorld');
@@ -63,9 +65,7 @@ export default function DesktopShell({ page, onNavigate, children, overlays }: D
             <select
               aria-label={t('shell.worldSelector')}
               value={state.worldId ?? ''}
-              onChange={(event) =>
-                dispatch({ type: 'SET_WORLD', worldId: event.target.value || null })
-              }
+              onChange={(event) => requestWorldChange(event.target.value || null)}
             >
               <option value="">{t('shell.noWorld')}</option>
               {state.worlds.map((world) => (

From c50946d1b6d68d182e29b7b17e4b649585afa884 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 14:02:52 +0800
Subject: [PATCH 34/49] feat(webui): add foreshadowing and secret workspaces

---
 webui/src/App.tsx                             |  28 +++++
 webui/src/__tests__/pages.test.tsx            |  95 +++++++++++++++
 webui/src/api/client.ts                       |   6 +
 webui/src/api/types.ts                        |   9 ++
 .../Inspector/CreateForeshadowingModal.tsx    |   4 +-
 .../Inspector/CreateSecretModal.tsx           |   4 +-
 webui/src/pages/ForeshadowingPage.module.css  |  59 ++++++++++
 webui/src/pages/ForeshadowingPage.tsx         | 109 ++++++++++++++++++
 webui/src/pages/SecretsPage.module.css        |  59 ++++++++++
 webui/src/pages/SecretsPage.tsx               |  72 ++++++++++++
 10 files changed, 441 insertions(+), 4 deletions(-)
 create mode 100644 webui/src/pages/ForeshadowingPage.module.css
 create mode 100644 webui/src/pages/ForeshadowingPage.tsx
 create mode 100644 webui/src/pages/SecretsPage.module.css
 create mode 100644 webui/src/pages/SecretsPage.tsx

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index 969ea435..fa81e7e1 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -32,6 +32,8 @@ const WorldPage = lazy(() => import('./pages/WorldPage'));
 const CharactersPage = lazy(() => import('./pages/CharactersPage'));
 const ChaptersPage = lazy(() => import('./pages/ChaptersPage'));
 const ScenesPage = lazy(() => import('./pages/ScenesPage'));
+const ForeshadowingPage = lazy(() => import('./pages/ForeshadowingPage'));
+const SecretsPage = lazy(() => import('./pages/SecretsPage'));
 
 export function shouldReportWorldbuildingPartialFailure(
   overviewLoaded: boolean,
@@ -387,6 +389,32 @@ function AppInner() {
     );
   }
 
+  if (state.currentPage === 'foreshadowing' && state.worldId) {
+    return (
+      <ToastProvider>
+        {inDesktopShell(
+          <Suspense fallback={<Skeleton />}>
+            <ForeshadowingPage worldId={state.worldId} />
+          </Suspense>,
+          narrativePageOverlays,
+        )}
+      </ToastProvider>
+    );
+  }
+
+  if (state.currentPage === 'secrets' && state.worldId) {
+    return (
+      <ToastProvider>
+        {inDesktopShell(
+          <Suspense fallback={<Skeleton />}>
+            <SecretsPage worldId={state.worldId} />
+          </Suspense>,
+          narrativePageOverlays,
+        )}
+      </ToastProvider>
+    );
+  }
+
   if (
     state.appPhase === 'no_agent' &&
     !shouldRenderSessionsPage(state.currentPage, state.appPhase)
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index d5121999..58949e11 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -14,6 +14,8 @@ import ChaptersPage from '../pages/ChaptersPage';
 import CharactersPage from '../pages/CharactersPage';
 import OverviewPage from '../pages/OverviewPage';
 import ScenesPage from '../pages/ScenesPage';
+import ForeshadowingPage, { deriveForeshadowingStatus } from '../pages/ForeshadowingPage';
+import SecretsPage from '../pages/SecretsPage';
 import { selectWorldMetrics } from '../pages/selectors';
 import WorldPage from '../pages/WorldPage';
 
@@ -36,9 +38,102 @@ vi.mock('../api/client', () => ({
     readWorkspaceFile: vi.fn(),
     saveWorkspaceFile: vi.fn(),
     patchChapter: vi.fn(),
+    listForeshadowing: vi.fn(),
+    listSecrets: vi.fn(),
+    patchForeshadow: vi.fn(),
+    patchSecret: vi.fn(),
+    deleteForeshadowing: vi.fn(),
+    deleteSecret: vi.fn(),
+    createForeshadowing: vi.fn(),
+    createSecret: vi.fn(),
   },
 }));
 
+describe('Foreshadowing page', () => {
+  it('derives overdue only when planned and current chapter positions both exist', () => {
+    expect(deriveForeshadowingStatus({ status: 'open', planned_chapter_position: 2 }, 4)).toBeNull();
+    expect(
+      deriveForeshadowingStatus(
+        { status: 'open', planned_chapter_position: 2, current_chapter_position: 4 },
+        null,
+      ),
+    ).toBe('overdue');
+    expect(
+      deriveForeshadowingStatus(
+        { status: 'open', planned_chapter_position: 5, current_chapter_position: 4 },
+        null,
+      ),
+    ).toBeNull();
+  });
+
+  it('filters real records and keeps selection safe after deletion', async () => {
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listForeshadowing)
+      .mockResolvedValueOnce({
+        ok: true,
+        items: [
+          { id: 'f1', content: 'Silver bell', status: 'open' },
+          { id: 'f2', content: 'Broken seal', status: 'paid' },
+        ],
+      })
+      .mockResolvedValueOnce({ ok: true, items: [{ id: 'f2', content: 'Broken seal', status: 'paid' }] });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    vi.mocked(api.deleteForeshadowing).mockResolvedValue({ ok: true });
+
+    render(<ForeshadowingPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Silver bell/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Delete foreshadowing' }));
+
+    await waitFor(() => expect(api.deleteForeshadowing).toHaveBeenCalledWith('world-1', 'f1'));
+    expect(screen.getByRole('option', { name: /Broken seal/ })).toHaveAttribute('aria-selected', 'true');
+  });
+});
+
+describe('Secrets page', () => {
+  const secrets = {
+    ok: true,
+    items: [
+      { id: 's1', title: 'The pact', truth: 'The crown is counterfeit', status: 'active', aware_character_ids: ['a1', 'missing'] },
+      { id: 's2', title: 'The oath', truth: 'The oath was staged', status: 'active' },
+    ],
+  };
+
+  it('keeps truth absent from the DOM until explicit reveal and hides it on selection and world changes', async () => {
+    vi.mocked(api.listSecrets).mockResolvedValue(secrets);
+    vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [{ id: 'a1', name: 'Mira', display_name: 'Mira', kind: 'character' }] });
+
+    const view = render(<SecretsPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /The pact/ }));
+    expect(screen.queryByText('The crown is counterfeit')).toBeNull();
+    expect(screen.queryByText('missing')).toBeNull();
+    fireEvent.click(screen.getByRole('button', { name: 'Reveal truth' }));
+    expect(screen.getByText('The crown is counterfeit')).toBeDefined();
+    fireEvent.click(screen.getByRole('option', { name: /The oath/ }));
+    expect(screen.queryByText('The crown is counterfeit')).toBeNull();
+    expect(screen.queryByText('The oath was staged')).toBeNull();
+    view.rerender(<SecretsPage worldId="world-2" />);
+    expect(screen.queryByText('The oath was staged')).toBeNull();
+  });
+
+  it('retains the secret list when relationship context is partially unavailable', async () => {
+    vi.mocked(api.listSecrets).mockResolvedValue(secrets);
+    vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listAgents).mockRejectedValue(new Error('Characters unavailable'));
+
+    render(<SecretsPage worldId="world-1" />);
+
+    expect(await screen.findByRole('option', { name: /The pact/ })).toBeDefined();
+    expect(screen.getByRole('alert')).toHaveTextContent('Characters unavailable');
+  });
+});
+
 vi.mock('../api/worldbuilding', () => ({
   worldbuildingApi: {
     getDashboard: vi.fn(),
diff --git a/webui/src/api/client.ts b/webui/src/api/client.ts
index 4f7723a8..fe98688e 100644
--- a/webui/src/api/client.ts
+++ b/webui/src/api/client.ts
@@ -368,6 +368,12 @@ export const api = {
   patchSecret: (worldId: string, id: string, fields: Record<string, unknown>) =>
     request<OkResponse>('PATCH', `/api/worldbuilding/${worldId}/secrets/${id}`, { fields }),
 
+  deleteForeshadowing: (worldId: string, id: string) =>
+    request<OkResponse>('DELETE', `/api/worldbuilding/${worldId}/foreshadowing/${id}`),
+
+  deleteSecret: (worldId: string, id: string) =>
+    request<OkResponse>('DELETE', `/api/worldbuilding/${worldId}/secrets/${id}`),
+
   // Run audit
   fetchRunAudit: (runId: string) => request<RunAuditResponse>('GET', `/v1/runs/${runId}/audit`),
 
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 3abedab8..ed10917a 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -185,6 +185,12 @@ export interface ForeshadowingItem {
   tags?: string[];
   planted_at?: string;
   paid_at?: string;
+  planned_chapter_position?: number;
+  current_chapter_position?: number;
+  chapter_id?: string;
+  scene_id?: string;
+  related_agent_ids?: string[];
+  related_secret_ids?: string[];
 }
 
 export interface ForeshadowingListResponse {
@@ -203,6 +209,9 @@ export interface SecretItem {
   status?: string;
   aware_character_ids?: string[];
   suspicious_character_ids?: string[];
+  related_foreshadowing_ids?: string[];
+  chapter_id?: string;
+  scene_id?: string;
 }
 
 export interface SecretListResponse {
diff --git a/webui/src/components/Inspector/CreateForeshadowingModal.tsx b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
index b2ba7d27..5a8566f4 100644
--- a/webui/src/components/Inspector/CreateForeshadowingModal.tsx
+++ b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
@@ -7,7 +7,7 @@ import styles from './CreateModal.module.css';
 interface Props {
   worldId: string;
   onClose: () => void;
-  onCreated?: () => void;
+  onCreated?: () => void | Promise<void>;
 }
 
 export default function CreateForeshadowingModal({ worldId, onClose, onCreated }: Props) {
@@ -37,7 +37,7 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
         tags: tags ? tags.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      onCreated?.();
+      await onCreated?.();
       onClose();
     } catch (e) {
       setError((e as Error).message);
diff --git a/webui/src/components/Inspector/CreateSecretModal.tsx b/webui/src/components/Inspector/CreateSecretModal.tsx
index 4d1078a1..f4827209 100644
--- a/webui/src/components/Inspector/CreateSecretModal.tsx
+++ b/webui/src/components/Inspector/CreateSecretModal.tsx
@@ -7,7 +7,7 @@ import styles from './CreateModal.module.css';
 interface Props {
   worldId: string;
   onClose: () => void;
-  onCreated?: () => void;
+  onCreated?: () => void | Promise<void>;
 }
 
 export default function CreateSecretModal({ worldId, onClose, onCreated }: Props) {
@@ -41,7 +41,7 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
         suspicious_character_ids: suspiciousIds ? suspiciousIds.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      onCreated?.();
+      await onCreated?.();
       onClose();
     } catch (e) {
       setError((e as Error).message);
diff --git a/webui/src/pages/ForeshadowingPage.module.css b/webui/src/pages/ForeshadowingPage.module.css
new file mode 100644
index 00000000..26d5b9db
--- /dev/null
+++ b/webui/src/pages/ForeshadowingPage.module.css
@@ -0,0 +1,59 @@
+.workspace {
+  display: grid;
+  grid-template-columns: minmax(240px, 310px) minmax(360px, 1fr) minmax(220px, 280px);
+  min-height: 100%;
+  background: var(--surface-muted);
+}
+.listPane, .contextPane { min-height: 0; padding: 20px 16px; background: var(--surface-strong); }
+.listPane { display: flex; flex-direction: column; border-right: 1px solid var(--border); }
+.contextPane { border-left: 1px solid var(--border); overflow: auto; }
+.listPane header, .detailHeader { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; }
+.listPane header > div > span, .detailHeader > div > span { color: var(--brand); font-size: 11px; font-weight: 800; text-transform: uppercase; }
+.listPane h1 { margin-top: 3px; font-size: 24px; }
+.tools, .actions { display: flex; gap: 7px; }
+.tools button, .actions button { display: inline-flex; align-items: center; justify-content: center; gap: 5px; min-height: 34px; padding: 0 10px; border: 1px solid var(--border); border-radius: 7px; background: var(--surface); cursor: pointer; }
+.tools button { width: 34px; padding: 0; }
+.tools svg, .actions svg { width: 15px; height: 15px; }
+.filter { display: grid; grid-template-columns: auto auto 1fr; align-items: center; gap: 7px; margin: 14px 0; color: var(--muted); font-size: 12px; }
+.filter svg { width: 14px; }
+.filter select { min-height: 32px; border: 1px solid var(--border); border-radius: 7px; background: var(--surface); }
+.listItem { display: flex; gap: 10px; padding: 3px; }
+.listItem > svg { flex: 0 0 auto; width: 15px; color: var(--brand); }
+.listItem div { display: grid; gap: 5px; min-width: 0; }
+.listItem strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.listItem span, .listPane footer, .empty { color: var(--muted); font-size: 11px; }
+.listPane footer { margin-top: auto; padding-top: 12px; }
+.empty { padding: 20px 5px; }
+.warning { margin-bottom: 10px; padding: 9px; border-radius: 7px; background: var(--amber-soft); font-size: 12px; }
+.detail { min-width: 0; padding: 24px; overflow: auto; }
+.detailHeader { padding-bottom: 18px; border-bottom: 1px solid var(--border); }
+.detailHeader h2 { margin-top: 6px; font-size: 24px; overflow-wrap: anywhere; }
+.cards { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; margin-top: 18px; }
+.fact, .block, .truth { padding: 15px; border: 1px solid var(--border); border-radius: 9px; background: var(--surface-strong); }
+.fact { display: grid; gap: 5px; }
+.fact span { color: var(--muted); font-size: 10px; text-transform: uppercase; }
+.fact strong { overflow-wrap: anywhere; }
+.block, .truth { margin-top: 12px; }
+.block h3, .truth h3, .contextPane h2, .context h3 { margin-bottom: 9px; font-size: 13px; }
+.block p, .truth p, .contextPane p { color: var(--muted-strong); line-height: 1.55; overflow-wrap: anywhere; }
+.block textarea { width: 100%; min-height: 90px; padding: 10px; border: 1px solid var(--border); border-radius: 7px; resize: vertical; }
+.primary, .truth button { display: inline-flex; align-items: center; gap: 6px; margin-top: 10px; min-height: 35px; padding: 0 13px; border: 0; border-radius: 7px; background: var(--brand-strong); color: white; cursor: pointer; }
+.truth > div { display: grid; place-items: center; min-height: 170px; text-align: center; }
+.truth > div > svg { width: 25px; color: var(--muted); }
+.truth button svg { width: 15px; }
+.chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.chips span { max-width: 100%; padding: 5px 8px; border-radius: 999px; background: var(--brand-soft); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.context { display: grid; gap: 12px; }
+.pick { display: grid; place-items: center; align-content: center; min-height: 420px; color: var(--muted); text-align: center; }
+.pick svg { width: 32px; height: 32px; }
+.pick h2 { margin: 12px 0 5px; color: var(--ink); }
+@media (max-width: 1100px) {
+  .workspace { grid-template-columns: minmax(230px, 290px) minmax(0, 1fr); }
+  .contextPane { grid-column: 1 / -1; border-top: 1px solid var(--border); border-left: 0; }
+}
+@media (max-width: 700px) {
+  .workspace { grid-template-columns: 1fr; overflow: auto; }
+  .listPane { border-right: 0; border-bottom: 1px solid var(--border); }
+  .detail { min-height: 480px; }
+  .cards { grid-template-columns: 1fr; }
+}
diff --git a/webui/src/pages/ForeshadowingPage.tsx b/webui/src/pages/ForeshadowingPage.tsx
new file mode 100644
index 00000000..4772de30
--- /dev/null
+++ b/webui/src/pages/ForeshadowingPage.tsx
@@ -0,0 +1,109 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Filter, Pencil, Plus, RefreshCw, Sparkles, Trash2 } from 'lucide-react';
+import { api } from '../api/client';
+import type { ForeshadowingItem, StoryChapter, StoryScene, WorldAgent } from '../api/types';
+import CreateForeshadowingModal from '../components/Inspector/CreateForeshadowingModal';
+import PageState from '../components/layout/PageState';
+import ResourceList from '../components/layout/ResourceList';
+import { useResource } from '../hooks/useResource';
+import styles from './ForeshadowingPage.module.css';
+
+type Data = {
+  items: ForeshadowingItem[];
+  chapters: StoryChapter[];
+  scenes: StoryScene[];
+  agents: WorldAgent[];
+  contextError: string | null;
+};
+
+export function deriveForeshadowingStatus(
+  item: Pick<ForeshadowingItem, 'status' | 'planned_chapter_position' | 'current_chapter_position'>,
+  _currentChapterPosition: number | null,
+): 'overdue' | null {
+  if (
+    item.status !== 'open' ||
+    item.planned_chapter_position == null ||
+    item.current_chapter_position == null
+  ) return null;
+  return item.current_chapter_position > item.planned_chapter_position ? 'overdue' : null;
+}
+
+export default function ForeshadowingPage({ worldId }: { worldId: string }) {
+  const resource = useResource(`foreshadowing:${worldId}`, async () => {
+    const [foreshadowing, chapters, scenes, agents] = await Promise.allSettled([
+      api.listForeshadowing(worldId), api.listChapters(worldId), api.listScenes(worldId), api.listAgents(worldId),
+    ]);
+    if (foreshadowing.status === 'rejected') throw foreshadowing.reason;
+    const failures = [chapters, scenes, agents].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
+    return {
+      items: foreshadowing.value.foreshadowing ?? foreshadowing.value.items ?? [],
+      chapters: chapters.status === 'fulfilled' ? chapters.value.chapters : [],
+      scenes: scenes.status === 'fulfilled' ? scenes.value.scenes : [],
+      agents: agents.status === 'fulfilled' ? agents.value.agents : [],
+      contextError: failures.length ? failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') : null,
+    };
+  });
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [filter, setFilter] = useState('all');
+  const [createOpen, setCreateOpen] = useState(false);
+  const [editing, setEditing] = useState(false);
+  const [payoff, setPayoff] = useState('');
+  const [removed, setRemoved] = useState<string[]>([]);
+  const [mutationError, setMutationError] = useState<string | null>(null);
+  const data: Data | null = resource.data;
+  const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
+  const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
+  const selected = items.find((item) => item.id === selectedId) ?? null;
+
+  useEffect(() => { setSelectedId(null); setRemoved([]); setEditing(false); }, [worldId]);
+  useEffect(() => {
+    if (selectedId && !items.some((item) => item.id === selectedId)) setSelectedId(items[0]?.id ?? null);
+  }, [items, selectedId]);
+  useEffect(() => { setPayoff(selected?.pay_off_idea ?? ''); setEditing(false); }, [selected?.id]);
+
+  async function save() {
+    if (!selected || !window.confirm('Update this foreshadowing item?')) return;
+    setMutationError(null);
+    try { await api.patchForeshadow(worldId, selected.id, { pay_off_idea: payoff }); setEditing(false); resource.retry(); }
+    catch (error) { setMutationError((error as Error).message); }
+  }
+
+  async function remove() {
+    if (!selected || !window.confirm('Delete this foreshadowing item?')) return;
+    setMutationError(null);
+    const id = selected.id;
+    try { await api.deleteForeshadowing(worldId, id); setRemoved((ids) => [...ids, id]); setSelectedId(items.find((item) => item.id !== id)?.id ?? null); resource.retry(); }
+    catch (error) { setMutationError((error as Error).message); }
+  }
+
+  if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading foreshadowing" error={resource.error} onRetry={resource.retry} />;
+  return (
+    <main className={styles.workspace}>
+      <aside className={styles.listPane}>
+        <header><div><span>Narrative threads</span><h1>Foreshadowing</h1></div><div className={styles.tools}><button aria-label="Refresh foreshadowing" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create foreshadowing" onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
+        <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => setFilter(event.target.value)}><option value="all">All</option><option value="open">Open</option><option value="paid">Paid</option><option value="abandoned">Abandoned</option></select></label>
+        {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
+        {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Foreshadowing" renderItem={(item) => <div className={styles.listItem}><Sparkles /><div><strong>{item.content}</strong><span>{item.status ?? 'No status'}{deriveForeshadowingStatus(item, null) ? ' · overdue' : ''}</span></div></div>} /> : <p className={styles.empty}>No foreshadowing matches this filter.</p>}
+        <footer>{filtered.length} {filtered.length === 1 ? 'thread' : 'threads'}</footer>
+      </aside>
+      <section className={styles.detail} aria-label="Foreshadowing detail">
+        {selected ? <><header className={styles.detailHeader}><div><span>Thread detail</span><h2>{selected.content}</h2></div><div className={styles.actions}><button aria-label="Edit foreshadowing" onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete foreshadowing" onClick={remove}><Trash2 /> Delete</button></div></header>
+          <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Hint level" value={selected.hint_level} /><Fact label="Planted at" value={selected.planted_at} /><Fact label="Paid at" value={selected.paid_at} /></div>
+          <section className={styles.block}><h3>Payoff idea</h3>{editing ? <><textarea aria-label="Payoff idea" value={payoff} onChange={(event) => setPayoff(event.target.value)} /><button className={styles.primary} onClick={save}>Save changes</button></> : <p>{selected.pay_off_idea || 'No payoff idea recorded.'}</p>}</section>
+          {selected.tags?.length ? <section className={styles.block}><h3>Tags</h3><div className={styles.chips}>{selected.tags.map((tag) => <span key={tag}>{tag}</span>)}</div></section> : null}
+        </> : <Pick icon={<Sparkles />} title="Select foreshadowing" text="Choose a thread to inspect its recorded details." />}
+      </section>
+      <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <Context item={selected} data={data} /> : <p>Select a thread to see resolved relationships.</p>}</aside>
+      {createOpen ? <CreateForeshadowingModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
+    </main>
+  );
+}
+
+function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
+function Pick({ icon, title, text }: { icon: React.ReactNode; title: string; text: string }) { return <div className={styles.pick}>{icon}<h2>{title}</h2><p>{text}</p></div>; }
+function Context({ item, data }: { item: ForeshadowingItem; data: Data }) {
+  const chapter = data.chapters.find((entry) => entry.id === item.chapter_id);
+  const scene = data.scenes.find((entry) => entry.id === item.scene_id);
+  const agents = (item.related_agent_ids ?? []).map((id) => data.agents.find((entry) => entry.id === id)).filter(Boolean) as WorldAgent[];
+  return <div className={styles.context}>{chapter && <Fact label="Chapter" value={chapter.title} />}{scene && <Fact label="Scene" value={scene.title} />}{agents.length ? <div><h3>Characters</h3><div className={styles.chips}>{agents.map((agent) => <span key={agent.id}>{agent.display_name || agent.name}</span>)}</div></div> : null}{!chapter && !scene && !agents.length ? <p>No resolvable relationships recorded.</p> : null}</div>;
+}
diff --git a/webui/src/pages/SecretsPage.module.css b/webui/src/pages/SecretsPage.module.css
new file mode 100644
index 00000000..26d5b9db
--- /dev/null
+++ b/webui/src/pages/SecretsPage.module.css
@@ -0,0 +1,59 @@
+.workspace {
+  display: grid;
+  grid-template-columns: minmax(240px, 310px) minmax(360px, 1fr) minmax(220px, 280px);
+  min-height: 100%;
+  background: var(--surface-muted);
+}
+.listPane, .contextPane { min-height: 0; padding: 20px 16px; background: var(--surface-strong); }
+.listPane { display: flex; flex-direction: column; border-right: 1px solid var(--border); }
+.contextPane { border-left: 1px solid var(--border); overflow: auto; }
+.listPane header, .detailHeader { display: flex; align-items: flex-start; justify-content: space-between; gap: 12px; }
+.listPane header > div > span, .detailHeader > div > span { color: var(--brand); font-size: 11px; font-weight: 800; text-transform: uppercase; }
+.listPane h1 { margin-top: 3px; font-size: 24px; }
+.tools, .actions { display: flex; gap: 7px; }
+.tools button, .actions button { display: inline-flex; align-items: center; justify-content: center; gap: 5px; min-height: 34px; padding: 0 10px; border: 1px solid var(--border); border-radius: 7px; background: var(--surface); cursor: pointer; }
+.tools button { width: 34px; padding: 0; }
+.tools svg, .actions svg { width: 15px; height: 15px; }
+.filter { display: grid; grid-template-columns: auto auto 1fr; align-items: center; gap: 7px; margin: 14px 0; color: var(--muted); font-size: 12px; }
+.filter svg { width: 14px; }
+.filter select { min-height: 32px; border: 1px solid var(--border); border-radius: 7px; background: var(--surface); }
+.listItem { display: flex; gap: 10px; padding: 3px; }
+.listItem > svg { flex: 0 0 auto; width: 15px; color: var(--brand); }
+.listItem div { display: grid; gap: 5px; min-width: 0; }
+.listItem strong { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.listItem span, .listPane footer, .empty { color: var(--muted); font-size: 11px; }
+.listPane footer { margin-top: auto; padding-top: 12px; }
+.empty { padding: 20px 5px; }
+.warning { margin-bottom: 10px; padding: 9px; border-radius: 7px; background: var(--amber-soft); font-size: 12px; }
+.detail { min-width: 0; padding: 24px; overflow: auto; }
+.detailHeader { padding-bottom: 18px; border-bottom: 1px solid var(--border); }
+.detailHeader h2 { margin-top: 6px; font-size: 24px; overflow-wrap: anywhere; }
+.cards { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; margin-top: 18px; }
+.fact, .block, .truth { padding: 15px; border: 1px solid var(--border); border-radius: 9px; background: var(--surface-strong); }
+.fact { display: grid; gap: 5px; }
+.fact span { color: var(--muted); font-size: 10px; text-transform: uppercase; }
+.fact strong { overflow-wrap: anywhere; }
+.block, .truth { margin-top: 12px; }
+.block h3, .truth h3, .contextPane h2, .context h3 { margin-bottom: 9px; font-size: 13px; }
+.block p, .truth p, .contextPane p { color: var(--muted-strong); line-height: 1.55; overflow-wrap: anywhere; }
+.block textarea { width: 100%; min-height: 90px; padding: 10px; border: 1px solid var(--border); border-radius: 7px; resize: vertical; }
+.primary, .truth button { display: inline-flex; align-items: center; gap: 6px; margin-top: 10px; min-height: 35px; padding: 0 13px; border: 0; border-radius: 7px; background: var(--brand-strong); color: white; cursor: pointer; }
+.truth > div { display: grid; place-items: center; min-height: 170px; text-align: center; }
+.truth > div > svg { width: 25px; color: var(--muted); }
+.truth button svg { width: 15px; }
+.chips { display: flex; flex-wrap: wrap; gap: 6px; }
+.chips span { max-width: 100%; padding: 5px 8px; border-radius: 999px; background: var(--brand-soft); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.context { display: grid; gap: 12px; }
+.pick { display: grid; place-items: center; align-content: center; min-height: 420px; color: var(--muted); text-align: center; }
+.pick svg { width: 32px; height: 32px; }
+.pick h2 { margin: 12px 0 5px; color: var(--ink); }
+@media (max-width: 1100px) {
+  .workspace { grid-template-columns: minmax(230px, 290px) minmax(0, 1fr); }
+  .contextPane { grid-column: 1 / -1; border-top: 1px solid var(--border); border-left: 0; }
+}
+@media (max-width: 700px) {
+  .workspace { grid-template-columns: 1fr; overflow: auto; }
+  .listPane { border-right: 0; border-bottom: 1px solid var(--border); }
+  .detail { min-height: 480px; }
+  .cards { grid-template-columns: 1fr; }
+}
diff --git a/webui/src/pages/SecretsPage.tsx b/webui/src/pages/SecretsPage.tsx
new file mode 100644
index 00000000..21db8d3f
--- /dev/null
+++ b/webui/src/pages/SecretsPage.tsx
@@ -0,0 +1,72 @@
+import { useEffect, useMemo, useState } from 'react';
+import { Eye, Filter, KeyRound, Pencil, Plus, RefreshCw, Trash2 } from 'lucide-react';
+import { api } from '../api/client';
+import type { ForeshadowingItem, SecretItem, StoryChapter, StoryScene, WorldAgent } from '../api/types';
+import CreateSecretModal from '../components/Inspector/CreateSecretModal';
+import PageState from '../components/layout/PageState';
+import ResourceList from '../components/layout/ResourceList';
+import { useResource } from '../hooks/useResource';
+import styles from './SecretsPage.module.css';
+
+type Data = { items: SecretItem[]; foreshadowing: ForeshadowingItem[]; chapters: StoryChapter[]; scenes: StoryScene[]; agents: WorldAgent[]; contextError: string | null };
+
+export default function SecretsPage({ worldId }: { worldId: string }) {
+  const resource = useResource(`secrets:${worldId}`, async () => {
+    const [secrets, foreshadowing, chapters, scenes, agents] = await Promise.allSettled([api.listSecrets(worldId), api.listForeshadowing(worldId), api.listChapters(worldId), api.listScenes(worldId), api.listAgents(worldId)]);
+    if (secrets.status === 'rejected') throw secrets.reason;
+    const failures = [foreshadowing, chapters, scenes, agents].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
+    return {
+      items: secrets.value.secrets ?? secrets.value.items ?? [],
+      foreshadowing: foreshadowing.status === 'fulfilled' ? foreshadowing.value.foreshadowing ?? foreshadowing.value.items ?? [] : [],
+      chapters: chapters.status === 'fulfilled' ? chapters.value.chapters : [],
+      scenes: scenes.status === 'fulfilled' ? scenes.value.scenes : [],
+      agents: agents.status === 'fulfilled' ? agents.value.agents : [],
+      contextError: failures.length ? failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') : null,
+    };
+  });
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [filter, setFilter] = useState('all');
+  const [revealedTruth, setRevealedTruth] = useState<string | null>(null);
+  const [createOpen, setCreateOpen] = useState(false);
+  const [editing, setEditing] = useState(false);
+  const [publicVersion, setPublicVersion] = useState('');
+  const [removed, setRemoved] = useState<string[]>([]);
+  const [mutationError, setMutationError] = useState<string | null>(null);
+  const data: Data | null = resource.data;
+  const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
+  const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
+  const selected = items.find((item) => item.id === selectedId) ?? null;
+
+  useEffect(() => { setSelectedId(null); setRemoved([]); setRevealedTruth(null); setEditing(false); }, [worldId]);
+  useEffect(() => { setRevealedTruth(null); setEditing(false); setPublicVersion(selected?.public_version ?? ''); }, [selected?.id]);
+  useEffect(() => { if (selectedId && !items.some((item) => item.id === selectedId)) setSelectedId(items[0]?.id ?? null); }, [items, selectedId]);
+
+  async function save() { if (!selected || !window.confirm('Update this secret?')) return; setMutationError(null); try { await api.patchSecret(worldId, selected.id, { public_version: publicVersion }); setEditing(false); resource.retry(); } catch (error) { setMutationError((error as Error).message); } }
+  async function remove() { if (!selected || !window.confirm('Delete this secret?')) return; setMutationError(null); const id = selected.id; try { await api.deleteSecret(worldId, id); setRemoved((ids) => [...ids, id]); setSelectedId(items.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } catch (error) { setMutationError((error as Error).message); } }
+
+  if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading secrets" error={resource.error} onRetry={resource.retry} />;
+  return <main className={styles.workspace}>
+    <aside className={styles.listPane}><header><div><span>Knowledge boundaries</span><h1>Secrets</h1></div><div className={styles.tools}><button aria-label="Refresh secrets" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create secret" onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
+      <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => setFilter(event.target.value)}><option value="all">All</option><option value="active">Active</option><option value="revealed">Revealed</option><option value="abandoned">Abandoned</option></select></label>
+      {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
+      {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Secrets" renderItem={(item) => <div className={styles.listItem}><KeyRound /><div><strong>{item.title || item.public_version || 'Untitled secret'}</strong><span>{item.status ?? 'No status'}</span></div></div>} /> : <p className={styles.empty}>No secrets match this filter.</p>}
+      <footer>{filtered.length} {filtered.length === 1 ? 'secret' : 'secrets'}</footer></aside>
+    <section className={styles.detail} aria-label="Secret detail">{selected ? <><header className={styles.detailHeader}><div><span>Secret detail</span><h2>{selected.title || selected.public_version || 'Untitled secret'}</h2></div><div className={styles.actions}><button aria-label="Edit secret" onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete secret" onClick={remove}><Trash2 /> Delete</button></div></header>
+      <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Stakes" value={selected.stakes} /></div>
+      <section className={styles.block}><h3>Public version</h3>{editing ? <><textarea aria-label="Public version" value={publicVersion} onChange={(event) => setPublicVersion(event.target.value)} /><button className={styles.primary} onClick={save}>Save changes</button></> : <p>{selected.public_version || 'No public version recorded.'}</p>}</section>
+      <section className={styles.truth}><h3>Truth</h3>{revealedTruth === null ? <div><KeyRound /><p>Hidden until you explicitly reveal it.</p><button aria-label="Reveal truth" onClick={() => setRevealedTruth(selected.truth ?? selected.content ?? '')}><Eye /> Reveal truth</button></div> : <p>{revealedTruth || 'No truth recorded.'}</p>}</section>
+    </> : <div className={styles.pick}><KeyRound /><h2>Select a secret</h2><p>Choose a secret to inspect its public details.</p></div>}</section>
+    <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <Context item={selected} data={data} /> : <p>Select a secret to see resolved relationships.</p>}</aside>
+    {createOpen ? <CreateSecretModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
+  </main>;
+}
+
+function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
+function Context({ item, data }: { item: SecretItem; data: Data }) {
+  const resolveAgents = (ids: string[] | undefined) => (ids ?? []).map((id) => data.agents.find((agent) => agent.id === id)).filter(Boolean) as WorldAgent[];
+  const aware = resolveAgents(item.aware_character_ids); const suspicious = resolveAgents(item.suspicious_character_ids);
+  const threads = (item.related_foreshadowing_ids ?? []).map((id) => data.foreshadowing.find((entry) => entry.id === id)).filter(Boolean) as ForeshadowingItem[];
+  const chapter = data.chapters.find((entry) => entry.id === item.chapter_id); const scene = data.scenes.find((entry) => entry.id === item.scene_id);
+  return <div className={styles.context}>{aware.length ? <ChipGroup title="Aware" values={aware.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{suspicious.length ? <ChipGroup title="Suspicious" values={suspicious.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{threads.length ? <ChipGroup title="Foreshadowing" values={threads.map((thread) => ({ id: thread.id, label: thread.content }))} /> : null}{chapter && <Fact label="Chapter" value={chapter.title} />}{scene && <Fact label="Scene" value={scene.title} />}{!aware.length && !suspicious.length && !threads.length && !chapter && !scene ? <p>No resolvable relationships recorded.</p> : null}</div>;
+}
+function ChipGroup({ title, values }: { title: string; values: { id: string; label: string }[] }) { return <div><h3>{title}</h3><div className={styles.chips}>{values.map((value) => <span key={value.id}>{value.label}</span>)}</div></div>; }

From 618240241020e899913c9d81127125e89cb29131 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 22:40:54 +0800
Subject: [PATCH 35/49] fix(webui): harden foreshadowing and secret workspaces

---
 webui/src/__tests__/api.test.ts               |   8 ++
 webui/src/__tests__/pages.test.tsx            | 131 +++++++++++++++++-
 webui/src/api/client.ts                       |   1 -
 webui/src/api/types.ts                        |   6 -
 .../Inspector/CreateForeshadowingModal.tsx    |  28 +++-
 .../Inspector/CreateSecretModal.tsx           |  28 +++-
 webui/src/pages/ForeshadowingPage.module.css  |   6 +-
 webui/src/pages/ForeshadowingPage.tsx         |  78 +++++------
 webui/src/pages/SecretsPage.module.css        |   6 +-
 webui/src/pages/SecretsPage.tsx               |  65 ++++++---
 10 files changed, 271 insertions(+), 86 deletions(-)

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index f32aed75..798a5a1e 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -1,8 +1,16 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { filesApi, worldbuildingApi } from '../api';
 import { request } from '../api/http';
 
 describe('api client', () => {
+  it('does not advertise unsupported narrative relationship fields', () => {
+    const client = readFileSync(join(process.cwd(), 'src/api/client.ts'), 'utf8');
+    const createSecret = client.slice(client.indexOf('createSecret:'), client.indexOf('// Prompt'));
+    expect(createSecret).not.toContain('related_foreshadowing_ids');
+  });
+
   beforeEach(() => {
     vi.stubGlobal('fetch', vi.fn());
   });
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 58949e11..73b6ab52 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -89,6 +89,72 @@ describe('Foreshadowing page', () => {
     await waitFor(() => expect(api.deleteForeshadowing).toHaveBeenCalledWith('world-1', 'f1'));
     expect(screen.getByRole('option', { name: /Broken seal/ })).toHaveAttribute('aria-selected', 'true');
   });
+
+  it('selects only visible records when the status filter changes', async () => {
+    vi.mocked(api.listForeshadowing).mockResolvedValue({
+      ok: true,
+      items: [
+        { id: 'f1', content: 'Silver bell', status: 'open' },
+        { id: 'f2', content: 'Broken seal', status: 'paid' },
+      ],
+    });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    render(<ForeshadowingPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Silver bell/ }));
+
+    fireEvent.change(screen.getByLabelText('Status'), { target: { value: 'paid' } });
+
+    expect(screen.getByRole('option', { name: /Broken seal/ })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('heading', { name: 'Broken seal' })).toBeDefined();
+  });
+
+  it('ignores a completed delete after switching worlds and disables duplicate mutation', async () => {
+    const deletion = deferred<{ ok: boolean }>();
+    vi.mocked(api.deleteForeshadowing).mockClear();
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listForeshadowing).mockImplementation((worldId) => Promise.resolve({
+      ok: true,
+      items: [{ id: 'shared', content: worldId === 'world-1' ? 'Old thread' : 'New thread', status: 'open' }],
+    }));
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    vi.mocked(api.deleteForeshadowing).mockReturnValue(deletion.promise);
+    const view = render(<ForeshadowingPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Old thread/ }));
+    const deleteButton = screen.getByRole('button', { name: 'Delete foreshadowing' });
+    fireEvent.click(deleteButton);
+    expect(deleteButton).toBeDisabled();
+    fireEvent.click(deleteButton);
+    expect(api.deleteForeshadowing).toHaveBeenCalledTimes(1);
+
+    view.rerender(<ForeshadowingPage worldId="world-2" />);
+    expect(await screen.findByRole('option', { name: /New thread/ })).toBeDefined();
+    await act(async () => deletion.resolve({ ok: true }));
+    expect(screen.getByRole('option', { name: /New thread/ })).toBeDefined();
+  });
+
+  it('closes the create mutation when the world changes', async () => {
+    vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
+    const view = render(
+      <AppStateProvider>
+        <ForeshadowingPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    await screen.findByText('No foreshadowing matches this filter.');
+    fireEvent.click(screen.getByRole('button', { name: 'Create foreshadowing' }));
+    expect(screen.getByRole('dialog')).toBeDefined();
+
+    view.rerender(
+      <AppStateProvider>
+        <ForeshadowingPage worldId="world-2" />
+      </AppStateProvider>,
+    );
+
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
 });
 
 describe('Secrets page', () => {
@@ -96,7 +162,7 @@ describe('Secrets page', () => {
     ok: true,
     items: [
       { id: 's1', title: 'The pact', truth: 'The crown is counterfeit', status: 'active', aware_character_ids: ['a1', 'missing'] },
-      { id: 's2', title: 'The oath', truth: 'The oath was staged', status: 'active' },
+      { id: 's2', title: 'The oath', truth: 'The oath was staged', status: 'exposed' },
     ],
   };
 
@@ -132,6 +198,69 @@ describe('Secrets page', () => {
     expect(await screen.findByRole('option', { name: /The pact/ })).toBeDefined();
     expect(screen.getByRole('alert')).toHaveTextContent('Characters unavailable');
   });
+
+  it('uses the exposed status and selects the first visible filtered secret', async () => {
+    vi.mocked(api.listSecrets).mockResolvedValue(secrets);
+    vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    render(<SecretsPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /The pact/ }));
+
+    fireEvent.change(screen.getByLabelText('Status'), { target: { value: 'exposed' } });
+
+    expect(screen.getByRole('option', { name: /The oath/ })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('heading', { name: 'The oath' })).toBeDefined();
+  });
+
+  it('keeps revealed truth scoped to its secret across rerenders', async () => {
+    vi.mocked(api.listSecrets).mockResolvedValue(secrets);
+    vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    const view = render(<SecretsPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /The pact/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Reveal truth' }));
+    expect(screen.getByText('The crown is counterfeit')).toBeDefined();
+
+    view.rerender(<SecretsPage worldId="world-2" />);
+
+    expect(screen.queryByText('The crown is counterfeit')).toBeNull();
+    expect(screen.queryByText('The oath was staged')).toBeNull();
+  });
+
+  it('closes the create mutation when the world changes', async () => {
+    vi.mocked(api.listSecrets).mockResolvedValue({ ok: true, items: [] });
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    const view = render(
+      <AppStateProvider>
+        <SecretsPage worldId="world-1" />
+      </AppStateProvider>,
+    );
+    await screen.findByText('No secrets match this filter.');
+    fireEvent.click(screen.getByRole('button', { name: 'Create secret' }));
+    expect(screen.getByRole('dialog')).toBeDefined();
+
+    view.rerender(
+      <AppStateProvider>
+        <SecretsPage worldId="world-2" />
+      </AppStateProvider>,
+    );
+
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+});
+
+describe('Foreshadowing and Secrets responsive layout', () => {
+  it.each(['ForeshadowingPage.module.css', 'SecretsPage.module.css'])('%s owns scrolling when context stacks', (file) => {
+    const css = readFileSync(join(process.cwd(), 'src/pages', file), 'utf8');
+    const responsive = css.slice(css.indexOf('@media (max-width: 1100px)'), css.indexOf('@media (max-width: 700px)'));
+    expect(css).toMatch(/\.workspace\s*\{[^}]*height:\s*100%[^}]*min-height:\s*0[^}]*overflow:\s*auto/s);
+    expect(responsive).toMatch(/\.workspace\s*\{[^}]*align-content:\s*start/s);
+    expect(responsive).not.toMatch(/\.contextPane\s*\{[^}]*display:\s*none/s);
+  });
 });
 
 vi.mock('../api/worldbuilding', () => ({
diff --git a/webui/src/api/client.ts b/webui/src/api/client.ts
index fe98688e..3bcaf381 100644
--- a/webui/src/api/client.ts
+++ b/webui/src/api/client.ts
@@ -453,7 +453,6 @@ export const api = {
       stakes?: string;
       aware_character_ids?: string[];
       suspicious_character_ids?: string[];
-      related_foreshadowing_ids?: string[];
       session_id?: string;
     },
   ) => request<CreateSecretResponse>('POST', `/api/worldbuilding/${worldId}/secrets`, data),
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index ed10917a..3c33f28d 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -187,9 +187,6 @@ export interface ForeshadowingItem {
   paid_at?: string;
   planned_chapter_position?: number;
   current_chapter_position?: number;
-  chapter_id?: string;
-  scene_id?: string;
-  related_agent_ids?: string[];
   related_secret_ids?: string[];
 }
 
@@ -209,9 +206,6 @@ export interface SecretItem {
   status?: string;
   aware_character_ids?: string[];
   suspicious_character_ids?: string[];
-  related_foreshadowing_ids?: string[];
-  chapter_id?: string;
-  scene_id?: string;
 }
 
 export interface SecretListResponse {
diff --git a/webui/src/components/Inspector/CreateForeshadowingModal.tsx b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
index 5a8566f4..580453ff 100644
--- a/webui/src/components/Inspector/CreateForeshadowingModal.tsx
+++ b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
@@ -1,5 +1,5 @@
 import { Eye, Lightbulb, Loader2, Tag, X } from 'lucide-react';
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { api } from '../../api/client';
 import { useAppState } from '../../AppState';
 import styles from './CreateModal.module.css';
@@ -18,6 +18,15 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
   const [tags, setTags] = useState('');
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const submittingRef = useRef(false);
+  const mountedRef = useRef(true);
+  const worldRef = useRef(worldId);
+  worldRef.current = worldId;
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => { mountedRef.current = false; };
+  }, []);
 
   useEffect(() => {
     function onKey(e: KeyboardEvent) { if (e.key === 'Escape' && !submitting) onClose(); }
@@ -26,7 +35,9 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
   }, [onClose, submitting]);
 
   async function handleSubmit() {
-    if (!content.trim()) return;
+    if (!content.trim() || submittingRef.current) return;
+    const operationWorld = worldId;
+    submittingRef.current = true;
     setSubmitting(true);
     setError(null);
     try {
@@ -37,12 +48,17 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
         tags: tags ? tags.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      await onCreated?.();
-      onClose();
+      if (mountedRef.current && worldRef.current === operationWorld) {
+        await onCreated?.();
+        if (mountedRef.current && worldRef.current === operationWorld) onClose();
+      }
     } catch (e) {
-      setError((e as Error).message);
+      if (mountedRef.current && worldRef.current === operationWorld) setError((e as Error).message);
     } finally {
-      setSubmitting(false);
+      if (mountedRef.current && worldRef.current === operationWorld) {
+        submittingRef.current = false;
+        setSubmitting(false);
+      }
     }
   }
 
diff --git a/webui/src/components/Inspector/CreateSecretModal.tsx b/webui/src/components/Inspector/CreateSecretModal.tsx
index f4827209..39084a05 100644
--- a/webui/src/components/Inspector/CreateSecretModal.tsx
+++ b/webui/src/components/Inspector/CreateSecretModal.tsx
@@ -1,5 +1,5 @@
 import { KeyRound, Loader2, ShieldAlert, Users, X } from 'lucide-react';
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { api } from '../../api/client';
 import { useAppState } from '../../AppState';
 import styles from './CreateModal.module.css';
@@ -20,6 +20,15 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
   const [suspiciousIds, setSuspiciousIds] = useState('');
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const submittingRef = useRef(false);
+  const mountedRef = useRef(true);
+  const worldRef = useRef(worldId);
+  worldRef.current = worldId;
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => { mountedRef.current = false; };
+  }, []);
 
   useEffect(() => {
     function onKey(e: KeyboardEvent) { if (e.key === 'Escape' && !submitting) onClose(); }
@@ -28,7 +37,9 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
   }, [onClose, submitting]);
 
   async function handleSubmit() {
-    if (!title.trim() && !truth.trim()) return;
+    if ((!title.trim() && !truth.trim()) || submittingRef.current) return;
+    const operationWorld = worldId;
+    submittingRef.current = true;
     setSubmitting(true);
     setError(null);
     try {
@@ -41,12 +52,17 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
         suspicious_character_ids: suspiciousIds ? suspiciousIds.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      await onCreated?.();
-      onClose();
+      if (mountedRef.current && worldRef.current === operationWorld) {
+        await onCreated?.();
+        if (mountedRef.current && worldRef.current === operationWorld) onClose();
+      }
     } catch (e) {
-      setError((e as Error).message);
+      if (mountedRef.current && worldRef.current === operationWorld) setError((e as Error).message);
     } finally {
-      setSubmitting(false);
+      if (mountedRef.current && worldRef.current === operationWorld) {
+        submittingRef.current = false;
+        setSubmitting(false);
+      }
     }
   }
 
diff --git a/webui/src/pages/ForeshadowingPage.module.css b/webui/src/pages/ForeshadowingPage.module.css
index 26d5b9db..0e0be0a4 100644
--- a/webui/src/pages/ForeshadowingPage.module.css
+++ b/webui/src/pages/ForeshadowingPage.module.css
@@ -1,7 +1,9 @@
 .workspace {
   display: grid;
   grid-template-columns: minmax(240px, 310px) minmax(360px, 1fr) minmax(220px, 280px);
-  min-height: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: auto;
   background: var(--surface-muted);
 }
 .listPane, .contextPane { min-height: 0; padding: 20px 16px; background: var(--surface-strong); }
@@ -48,7 +50,7 @@
 .pick svg { width: 32px; height: 32px; }
 .pick h2 { margin: 12px 0 5px; color: var(--ink); }
 @media (max-width: 1100px) {
-  .workspace { grid-template-columns: minmax(230px, 290px) minmax(0, 1fr); }
+  .workspace { grid-template-columns: minmax(230px, 290px) minmax(0, 1fr); align-content: start; }
   .contextPane { grid-column: 1 / -1; border-top: 1px solid var(--border); border-left: 0; }
 }
 @media (max-width: 700px) {
diff --git a/webui/src/pages/ForeshadowingPage.tsx b/webui/src/pages/ForeshadowingPage.tsx
index 4772de30..2c9fddf8 100644
--- a/webui/src/pages/ForeshadowingPage.tsx
+++ b/webui/src/pages/ForeshadowingPage.tsx
@@ -1,7 +1,7 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { Filter, Pencil, Plus, RefreshCw, Sparkles, Trash2 } from 'lucide-react';
 import { api } from '../api/client';
-import type { ForeshadowingItem, StoryChapter, StoryScene, WorldAgent } from '../api/types';
+import type { ForeshadowingItem } from '../api/types';
 import CreateForeshadowingModal from '../components/Inspector/CreateForeshadowingModal';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
@@ -10,10 +10,6 @@ import styles from './ForeshadowingPage.module.css';
 
 type Data = {
   items: ForeshadowingItem[];
-  chapters: StoryChapter[];
-  scenes: StoryScene[];
-  agents: WorldAgent[];
-  contextError: string | null;
 };
 
 export function deriveForeshadowingStatus(
@@ -30,18 +26,8 @@ export function deriveForeshadowingStatus(
 
 export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const resource = useResource(`foreshadowing:${worldId}`, async () => {
-    const [foreshadowing, chapters, scenes, agents] = await Promise.allSettled([
-      api.listForeshadowing(worldId), api.listChapters(worldId), api.listScenes(worldId), api.listAgents(worldId),
-    ]);
-    if (foreshadowing.status === 'rejected') throw foreshadowing.reason;
-    const failures = [chapters, scenes, agents].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
-    return {
-      items: foreshadowing.value.foreshadowing ?? foreshadowing.value.items ?? [],
-      chapters: chapters.status === 'fulfilled' ? chapters.value.chapters : [],
-      scenes: scenes.status === 'fulfilled' ? scenes.value.scenes : [],
-      agents: agents.status === 'fulfilled' ? agents.value.agents : [],
-      contextError: failures.length ? failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') : null,
-    };
+    const foreshadowing = await api.listForeshadowing(worldId);
+    return { items: foreshadowing.foreshadowing ?? foreshadowing.items ?? [] };
   });
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [filter, setFilter] = useState('all');
@@ -50,50 +36,68 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const [payoff, setPayoff] = useState('');
   const [removed, setRemoved] = useState<string[]>([]);
   const [mutationError, setMutationError] = useState<string | null>(null);
+  const [pendingMutation, setPendingMutation] = useState<string | null>(null);
+  const pendingMutationRef = useRef(false);
+  const worldRef = useRef(worldId);
+  worldRef.current = worldId;
   const data: Data | null = resource.data;
   const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
-  const selected = items.find((item) => item.id === selectedId) ?? null;
+  const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
-  useEffect(() => { setSelectedId(null); setRemoved([]); setEditing(false); }, [worldId]);
+  useEffect(() => { setSelectedId(null); setRemoved([]); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
   useEffect(() => {
-    if (selectedId && !items.some((item) => item.id === selectedId)) setSelectedId(items[0]?.id ?? null);
-  }, [items, selectedId]);
+    if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null);
+  }, [filtered, selectedId]);
   useEffect(() => { setPayoff(selected?.pay_off_idea ?? ''); setEditing(false); }, [selected?.id]);
 
   async function save() {
-    if (!selected || !window.confirm('Update this foreshadowing item?')) return;
+    if (!selected || pendingMutationRef.current || !window.confirm('Update this foreshadowing item?')) return;
+    const operationWorld = worldId;
+    pendingMutationRef.current = true;
+    setPendingMutation('update');
     setMutationError(null);
-    try { await api.patchForeshadow(worldId, selected.id, { pay_off_idea: payoff }); setEditing(false); resource.retry(); }
-    catch (error) { setMutationError((error as Error).message); }
+    try { await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff }); if (worldRef.current === operationWorld) { setEditing(false); resource.retry(); } }
+    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
+    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
 
   async function remove() {
-    if (!selected || !window.confirm('Delete this foreshadowing item?')) return;
+    if (!selected || pendingMutationRef.current || !window.confirm('Delete this foreshadowing item?')) return;
     setMutationError(null);
     const id = selected.id;
-    try { await api.deleteForeshadowing(worldId, id); setRemoved((ids) => [...ids, id]); setSelectedId(items.find((item) => item.id !== id)?.id ?? null); resource.retry(); }
-    catch (error) { setMutationError((error as Error).message); }
+    const operationWorld = worldId;
+    pendingMutationRef.current = true;
+    setPendingMutation('delete');
+    try { await api.deleteForeshadowing(operationWorld, id); if (worldRef.current === operationWorld) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); resource.retry(); } }
+    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
+    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
+  }
+
+  function changeFilter(nextFilter: string) {
+    setFilter(nextFilter);
+    const visible = nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
+    setSelectedId(visible[0]?.id ?? null);
   }
 
   if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading foreshadowing" error={resource.error} onRetry={resource.retry} />;
   return (
     <main className={styles.workspace}>
       <aside className={styles.listPane}>
-        <header><div><span>Narrative threads</span><h1>Foreshadowing</h1></div><div className={styles.tools}><button aria-label="Refresh foreshadowing" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create foreshadowing" onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
-        <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => setFilter(event.target.value)}><option value="all">All</option><option value="open">Open</option><option value="paid">Paid</option><option value="abandoned">Abandoned</option></select></label>
-        {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
+        <header><div><span>Narrative threads</span><h1>Foreshadowing</h1></div><div className={styles.tools}><button aria-label="Refresh foreshadowing" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create foreshadowing" disabled={Boolean(pendingMutation)} onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
+        <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => changeFilter(event.target.value)}><option value="all">All</option><option value="open">Open</option><option value="paid">Paid</option><option value="abandoned">Abandoned</option></select></label>
+        {(resource.error || mutationError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message}</div>}
         {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Foreshadowing" renderItem={(item) => <div className={styles.listItem}><Sparkles /><div><strong>{item.content}</strong><span>{item.status ?? 'No status'}{deriveForeshadowingStatus(item, null) ? ' · overdue' : ''}</span></div></div>} /> : <p className={styles.empty}>No foreshadowing matches this filter.</p>}
         <footer>{filtered.length} {filtered.length === 1 ? 'thread' : 'threads'}</footer>
       </aside>
       <section className={styles.detail} aria-label="Foreshadowing detail">
-        {selected ? <><header className={styles.detailHeader}><div><span>Thread detail</span><h2>{selected.content}</h2></div><div className={styles.actions}><button aria-label="Edit foreshadowing" onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete foreshadowing" onClick={remove}><Trash2 /> Delete</button></div></header>
+        {selected ? <><header className={styles.detailHeader}><div><span>Thread detail</span><h2>{selected.content}</h2></div><div className={styles.actions}><button aria-label="Edit foreshadowing" disabled={Boolean(pendingMutation)} onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete foreshadowing" disabled={Boolean(pendingMutation)} onClick={remove}><Trash2 /> Delete</button></div></header>
           <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Hint level" value={selected.hint_level} /><Fact label="Planted at" value={selected.planted_at} /><Fact label="Paid at" value={selected.paid_at} /></div>
-          <section className={styles.block}><h3>Payoff idea</h3>{editing ? <><textarea aria-label="Payoff idea" value={payoff} onChange={(event) => setPayoff(event.target.value)} /><button className={styles.primary} onClick={save}>Save changes</button></> : <p>{selected.pay_off_idea || 'No payoff idea recorded.'}</p>}</section>
+          <section className={styles.block}><h3>Payoff idea</h3>{editing ? <><textarea aria-label="Payoff idea" disabled={Boolean(pendingMutation)} value={payoff} onChange={(event) => setPayoff(event.target.value)} /><button className={styles.primary} disabled={Boolean(pendingMutation)} onClick={save}>Save changes</button></> : <p>{selected.pay_off_idea || 'No payoff idea recorded.'}</p>}</section>
           {selected.tags?.length ? <section className={styles.block}><h3>Tags</h3><div className={styles.chips}>{selected.tags.map((tag) => <span key={tag}>{tag}</span>)}</div></section> : null}
         </> : <Pick icon={<Sparkles />} title="Select foreshadowing" text="Choose a thread to inspect its recorded details." />}
       </section>
-      <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <Context item={selected} data={data} /> : <p>Select a thread to see resolved relationships.</p>}</aside>
+      <aside className={styles.contextPane}><h2>Real context</h2><p>The foreshadowing list API does not expose chapter, scene, or character relationships.</p></aside>
       {createOpen ? <CreateForeshadowingModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
     </main>
   );
@@ -101,9 +105,3 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
 
 function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
 function Pick({ icon, title, text }: { icon: React.ReactNode; title: string; text: string }) { return <div className={styles.pick}>{icon}<h2>{title}</h2><p>{text}</p></div>; }
-function Context({ item, data }: { item: ForeshadowingItem; data: Data }) {
-  const chapter = data.chapters.find((entry) => entry.id === item.chapter_id);
-  const scene = data.scenes.find((entry) => entry.id === item.scene_id);
-  const agents = (item.related_agent_ids ?? []).map((id) => data.agents.find((entry) => entry.id === id)).filter(Boolean) as WorldAgent[];
-  return <div className={styles.context}>{chapter && <Fact label="Chapter" value={chapter.title} />}{scene && <Fact label="Scene" value={scene.title} />}{agents.length ? <div><h3>Characters</h3><div className={styles.chips}>{agents.map((agent) => <span key={agent.id}>{agent.display_name || agent.name}</span>)}</div></div> : null}{!chapter && !scene && !agents.length ? <p>No resolvable relationships recorded.</p> : null}</div>;
-}
diff --git a/webui/src/pages/SecretsPage.module.css b/webui/src/pages/SecretsPage.module.css
index 26d5b9db..0e0be0a4 100644
--- a/webui/src/pages/SecretsPage.module.css
+++ b/webui/src/pages/SecretsPage.module.css
@@ -1,7 +1,9 @@
 .workspace {
   display: grid;
   grid-template-columns: minmax(240px, 310px) minmax(360px, 1fr) minmax(220px, 280px);
-  min-height: 100%;
+  height: 100%;
+  min-height: 0;
+  overflow: auto;
   background: var(--surface-muted);
 }
 .listPane, .contextPane { min-height: 0; padding: 20px 16px; background: var(--surface-strong); }
@@ -48,7 +50,7 @@
 .pick svg { width: 32px; height: 32px; }
 .pick h2 { margin: 12px 0 5px; color: var(--ink); }
 @media (max-width: 1100px) {
-  .workspace { grid-template-columns: minmax(230px, 290px) minmax(0, 1fr); }
+  .workspace { grid-template-columns: minmax(230px, 290px) minmax(0, 1fr); align-content: start; }
   .contextPane { grid-column: 1 / -1; border-top: 1px solid var(--border); border-left: 0; }
 }
 @media (max-width: 700px) {
diff --git a/webui/src/pages/SecretsPage.tsx b/webui/src/pages/SecretsPage.tsx
index 21db8d3f..606f2a1f 100644
--- a/webui/src/pages/SecretsPage.tsx
+++ b/webui/src/pages/SecretsPage.tsx
@@ -1,60 +1,83 @@
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { Eye, Filter, KeyRound, Pencil, Plus, RefreshCw, Trash2 } from 'lucide-react';
 import { api } from '../api/client';
-import type { ForeshadowingItem, SecretItem, StoryChapter, StoryScene, WorldAgent } from '../api/types';
+import type { SecretItem, WorldAgent } from '../api/types';
 import CreateSecretModal from '../components/Inspector/CreateSecretModal';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
 import { useResource } from '../hooks/useResource';
 import styles from './SecretsPage.module.css';
 
-type Data = { items: SecretItem[]; foreshadowing: ForeshadowingItem[]; chapters: StoryChapter[]; scenes: StoryScene[]; agents: WorldAgent[]; contextError: string | null };
+type Data = { items: SecretItem[]; agents: WorldAgent[]; contextError: string | null };
 
 export default function SecretsPage({ worldId }: { worldId: string }) {
   const resource = useResource(`secrets:${worldId}`, async () => {
-    const [secrets, foreshadowing, chapters, scenes, agents] = await Promise.allSettled([api.listSecrets(worldId), api.listForeshadowing(worldId), api.listChapters(worldId), api.listScenes(worldId), api.listAgents(worldId)]);
+    const [secrets, agents] = await Promise.allSettled([api.listSecrets(worldId), api.listAgents(worldId)]);
     if (secrets.status === 'rejected') throw secrets.reason;
-    const failures = [foreshadowing, chapters, scenes, agents].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
+    const failures = [agents].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
     return {
       items: secrets.value.secrets ?? secrets.value.items ?? [],
-      foreshadowing: foreshadowing.status === 'fulfilled' ? foreshadowing.value.foreshadowing ?? foreshadowing.value.items ?? [] : [],
-      chapters: chapters.status === 'fulfilled' ? chapters.value.chapters : [],
-      scenes: scenes.status === 'fulfilled' ? scenes.value.scenes : [],
       agents: agents.status === 'fulfilled' ? agents.value.agents : [],
       contextError: failures.length ? failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') : null,
     };
   });
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [filter, setFilter] = useState('all');
-  const [revealedTruth, setRevealedTruth] = useState<string | null>(null);
+  const [revealedTruth, setRevealedTruth] = useState<{ secretId: string; truth: string } | null>(null);
   const [createOpen, setCreateOpen] = useState(false);
   const [editing, setEditing] = useState(false);
   const [publicVersion, setPublicVersion] = useState('');
   const [removed, setRemoved] = useState<string[]>([]);
   const [mutationError, setMutationError] = useState<string | null>(null);
+  const [pendingMutation, setPendingMutation] = useState<string | null>(null);
+  const pendingMutationRef = useRef(false);
+  const worldRef = useRef(worldId);
+  worldRef.current = worldId;
   const data: Data | null = resource.data;
   const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
-  const selected = items.find((item) => item.id === selectedId) ?? null;
+  const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
-  useEffect(() => { setSelectedId(null); setRemoved([]); setRevealedTruth(null); setEditing(false); }, [worldId]);
+  useEffect(() => { setSelectedId(null); setRemoved([]); setRevealedTruth(null); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
   useEffect(() => { setRevealedTruth(null); setEditing(false); setPublicVersion(selected?.public_version ?? ''); }, [selected?.id]);
-  useEffect(() => { if (selectedId && !items.some((item) => item.id === selectedId)) setSelectedId(items[0]?.id ?? null); }, [items, selectedId]);
+  useEffect(() => { if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null); }, [filtered, selectedId]);
 
-  async function save() { if (!selected || !window.confirm('Update this secret?')) return; setMutationError(null); try { await api.patchSecret(worldId, selected.id, { public_version: publicVersion }); setEditing(false); resource.retry(); } catch (error) { setMutationError((error as Error).message); } }
-  async function remove() { if (!selected || !window.confirm('Delete this secret?')) return; setMutationError(null); const id = selected.id; try { await api.deleteSecret(worldId, id); setRemoved((ids) => [...ids, id]); setSelectedId(items.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } catch (error) { setMutationError((error as Error).message); } }
+  async function save() {
+    if (!selected || pendingMutationRef.current || !window.confirm('Update this secret?')) return;
+    const operationWorld = worldId;
+    pendingMutationRef.current = true;
+    setPendingMutation('update'); setMutationError(null);
+    try { await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion }); if (worldRef.current === operationWorld) { setEditing(false); resource.retry(); } }
+    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
+    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
+  }
+  async function remove() {
+    if (!selected || pendingMutationRef.current || !window.confirm('Delete this secret?')) return;
+    const operationWorld = worldId; const id = selected.id;
+    pendingMutationRef.current = true;
+    setPendingMutation('delete'); setMutationError(null);
+    try { await api.deleteSecret(operationWorld, id); if (worldRef.current === operationWorld) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } }
+    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
+    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
+  }
+  function changeFilter(nextFilter: string) {
+    setFilter(nextFilter);
+    const visible = nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
+    setSelectedId(visible[0]?.id ?? null);
+    setRevealedTruth(null);
+  }
 
   if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading secrets" error={resource.error} onRetry={resource.retry} />;
   return <main className={styles.workspace}>
-    <aside className={styles.listPane}><header><div><span>Knowledge boundaries</span><h1>Secrets</h1></div><div className={styles.tools}><button aria-label="Refresh secrets" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create secret" onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
-      <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => setFilter(event.target.value)}><option value="all">All</option><option value="active">Active</option><option value="revealed">Revealed</option><option value="abandoned">Abandoned</option></select></label>
+    <aside className={styles.listPane}><header><div><span>Knowledge boundaries</span><h1>Secrets</h1></div><div className={styles.tools}><button aria-label="Refresh secrets" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create secret" disabled={Boolean(pendingMutation)} onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
+      <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => changeFilter(event.target.value)}><option value="all">All</option><option value="active">Active</option><option value="exposed">Exposed</option><option value="abandoned">Abandoned</option></select></label>
       {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
       {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Secrets" renderItem={(item) => <div className={styles.listItem}><KeyRound /><div><strong>{item.title || item.public_version || 'Untitled secret'}</strong><span>{item.status ?? 'No status'}</span></div></div>} /> : <p className={styles.empty}>No secrets match this filter.</p>}
       <footer>{filtered.length} {filtered.length === 1 ? 'secret' : 'secrets'}</footer></aside>
-    <section className={styles.detail} aria-label="Secret detail">{selected ? <><header className={styles.detailHeader}><div><span>Secret detail</span><h2>{selected.title || selected.public_version || 'Untitled secret'}</h2></div><div className={styles.actions}><button aria-label="Edit secret" onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete secret" onClick={remove}><Trash2 /> Delete</button></div></header>
+    <section className={styles.detail} aria-label="Secret detail">{selected ? <><header className={styles.detailHeader}><div><span>Secret detail</span><h2>{selected.title || selected.public_version || 'Untitled secret'}</h2></div><div className={styles.actions}><button aria-label="Edit secret" disabled={Boolean(pendingMutation)} onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete secret" disabled={Boolean(pendingMutation)} onClick={remove}><Trash2 /> Delete</button></div></header>
       <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Stakes" value={selected.stakes} /></div>
-      <section className={styles.block}><h3>Public version</h3>{editing ? <><textarea aria-label="Public version" value={publicVersion} onChange={(event) => setPublicVersion(event.target.value)} /><button className={styles.primary} onClick={save}>Save changes</button></> : <p>{selected.public_version || 'No public version recorded.'}</p>}</section>
-      <section className={styles.truth}><h3>Truth</h3>{revealedTruth === null ? <div><KeyRound /><p>Hidden until you explicitly reveal it.</p><button aria-label="Reveal truth" onClick={() => setRevealedTruth(selected.truth ?? selected.content ?? '')}><Eye /> Reveal truth</button></div> : <p>{revealedTruth || 'No truth recorded.'}</p>}</section>
+      <section className={styles.block}><h3>Public version</h3>{editing ? <><textarea aria-label="Public version" disabled={Boolean(pendingMutation)} value={publicVersion} onChange={(event) => setPublicVersion(event.target.value)} /><button className={styles.primary} disabled={Boolean(pendingMutation)} onClick={save}>Save changes</button></> : <p>{selected.public_version || 'No public version recorded.'}</p>}</section>
+      <section className={styles.truth}><h3>Truth</h3>{revealedTruth?.secretId === selected.id ? <p>{revealedTruth.truth || 'No truth recorded.'}</p> : <div><KeyRound /><p>Hidden until you explicitly reveal it.</p><button aria-label="Reveal truth" onClick={() => setRevealedTruth({ secretId: selected.id, truth: selected.truth ?? selected.content ?? '' })}><Eye /> Reveal truth</button></div>}</section>
     </> : <div className={styles.pick}><KeyRound /><h2>Select a secret</h2><p>Choose a secret to inspect its public details.</p></div>}</section>
     <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <Context item={selected} data={data} /> : <p>Select a secret to see resolved relationships.</p>}</aside>
     {createOpen ? <CreateSecretModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
@@ -65,8 +88,6 @@ function Fact({ label, value }: { label: string; value?: string }) { return <div
 function Context({ item, data }: { item: SecretItem; data: Data }) {
   const resolveAgents = (ids: string[] | undefined) => (ids ?? []).map((id) => data.agents.find((agent) => agent.id === id)).filter(Boolean) as WorldAgent[];
   const aware = resolveAgents(item.aware_character_ids); const suspicious = resolveAgents(item.suspicious_character_ids);
-  const threads = (item.related_foreshadowing_ids ?? []).map((id) => data.foreshadowing.find((entry) => entry.id === id)).filter(Boolean) as ForeshadowingItem[];
-  const chapter = data.chapters.find((entry) => entry.id === item.chapter_id); const scene = data.scenes.find((entry) => entry.id === item.scene_id);
-  return <div className={styles.context}>{aware.length ? <ChipGroup title="Aware" values={aware.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{suspicious.length ? <ChipGroup title="Suspicious" values={suspicious.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{threads.length ? <ChipGroup title="Foreshadowing" values={threads.map((thread) => ({ id: thread.id, label: thread.content }))} /> : null}{chapter && <Fact label="Chapter" value={chapter.title} />}{scene && <Fact label="Scene" value={scene.title} />}{!aware.length && !suspicious.length && !threads.length && !chapter && !scene ? <p>No resolvable relationships recorded.</p> : null}</div>;
+  return <div className={styles.context}>{aware.length ? <ChipGroup title="Aware" values={aware.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{suspicious.length ? <ChipGroup title="Suspicious" values={suspicious.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{!aware.length && !suspicious.length ? <p>No resolvable character relationships recorded.</p> : null}</div>;
 }
 function ChipGroup({ title, values }: { title: string; values: { id: string; label: string }[] }) { return <div><h3>{title}</h3><div className={styles.chips}>{values.map((value) => <span key={value.id}>{value.label}</span>)}</div></div>; }

From 7c2d9ea4995f1c297a5e17515f683704ec8a1acb Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 22:59:16 +0800
Subject: [PATCH 36/49] fix(webui): align narrative workspaces with real
 context

---
 webui/src/__tests__/api.test.ts               |   8 --
 webui/src/__tests__/pages.test.tsx            | 132 ++++++++++++++++--
 webui/src/api/client.ts                       |   1 +
 webui/src/api/types.ts                        |   3 -
 .../Inspector/CreateForeshadowingModal.tsx    |  23 +--
 .../Inspector/CreateSecretModal.tsx           |  23 +--
 webui/src/pages/ForeshadowingPage.tsx         |  64 ++++++---
 webui/src/pages/SecretsPage.tsx               |  23 +--
 8 files changed, 201 insertions(+), 76 deletions(-)

diff --git a/webui/src/__tests__/api.test.ts b/webui/src/__tests__/api.test.ts
index 798a5a1e..f32aed75 100644
--- a/webui/src/__tests__/api.test.ts
+++ b/webui/src/__tests__/api.test.ts
@@ -1,16 +1,8 @@
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { filesApi, worldbuildingApi } from '../api';
 import { request } from '../api/http';
 
 describe('api client', () => {
-  it('does not advertise unsupported narrative relationship fields', () => {
-    const client = readFileSync(join(process.cwd(), 'src/api/client.ts'), 'utf8');
-    const createSecret = client.slice(client.indexOf('createSecret:'), client.indexOf('// Prompt'));
-    expect(createSecret).not.toContain('related_foreshadowing_ids');
-  });
-
   beforeEach(() => {
     vi.stubGlobal('fetch', vi.fn());
   });
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 73b6ab52..1053e80e 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -6,6 +6,8 @@ import { describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
 import { worldbuildingApi } from '../api/worldbuilding';
 import { AppStateProvider } from '../AppState';
+import CreateForeshadowingModal from '../components/Inspector/CreateForeshadowingModal';
+import CreateSecretModal from '../components/Inspector/CreateSecretModal';
 import DetailPane from '../components/layout/DetailPane';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
@@ -51,19 +53,9 @@ vi.mock('../api/client', () => ({
 
 describe('Foreshadowing page', () => {
   it('derives overdue only when planned and current chapter positions both exist', () => {
-    expect(deriveForeshadowingStatus({ status: 'open', planned_chapter_position: 2 }, 4)).toBeNull();
-    expect(
-      deriveForeshadowingStatus(
-        { status: 'open', planned_chapter_position: 2, current_chapter_position: 4 },
-        null,
-      ),
-    ).toBe('overdue');
-    expect(
-      deriveForeshadowingStatus(
-        { status: 'open', planned_chapter_position: 5, current_chapter_position: 4 },
-        null,
-      ),
-    ).toBeNull();
+    expect(deriveForeshadowingStatus({ status: 'open', plannedPosition: 2, currentPosition: null })).toBeNull();
+    expect(deriveForeshadowingStatus({ status: 'open', plannedPosition: 2, currentPosition: 4 })).toBe('overdue');
+    expect(deriveForeshadowingStatus({ status: 'open', plannedPosition: 5, currentPosition: 4 })).toBeNull();
   });
 
   it('filters real records and keeps selection safe after deletion', async () => {
@@ -110,6 +102,25 @@ describe('Foreshadowing page', () => {
     expect(screen.getByRole('heading', { name: 'Broken seal' })).toBeDefined();
   });
 
+  it('resolves real planted and paid narrative IDs and retains the list when context fails', async () => {
+    vi.mocked(api.listForeshadowing).mockResolvedValue({
+      ok: true,
+      items: [{ id: 'f1', content: 'Silver bell', status: 'paid', planted_at: 'scene-1', paid_at: 'chapter-2' }],
+    });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [{ id: 'chapter-2', title: 'Reckoning', status: 'draft' }] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [{ id: 'scene-1', title: 'The warning', status: 'planned', chapter_id: 'chapter-1' }] });
+    render(<ForeshadowingPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /Silver bell/ }));
+    expect(screen.getByText('The warning')).toBeDefined();
+    expect(screen.getByText('Reckoning')).toBeDefined();
+
+    vi.mocked(api.listChapters).mockRejectedValue(new Error('Chapters unavailable'));
+    vi.mocked(api.listScenes).mockRejectedValue(new Error('Scenes unavailable'));
+    fireEvent.click(screen.getByRole('button', { name: 'Refresh foreshadowing' }));
+    expect(await screen.findByRole('alert')).toHaveTextContent('Chapters unavailable');
+    expect(screen.getByRole('option', { name: /Silver bell/ })).toBeDefined();
+  });
+
   it('ignores a completed delete after switching worlds and disables duplicate mutation', async () => {
     const deletion = deferred<{ ok: boolean }>();
     vi.mocked(api.deleteForeshadowing).mockClear();
@@ -136,6 +147,33 @@ describe('Foreshadowing page', () => {
     expect(screen.getByRole('option', { name: /New thread/ })).toBeDefined();
   });
 
+  it('does not let an A-B-A delete completion clear the new world generation lock', async () => {
+    const oldDeletion = deferred<{ ok: boolean }>();
+    const newDeletion = deferred<{ ok: boolean }>();
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listForeshadowing).mockImplementation((worldId) => Promise.resolve({
+      ok: true,
+      items: [{ id: 'shared', content: worldId === 'world-a' ? 'A thread' : 'B thread', status: 'open' }],
+    }));
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.deleteForeshadowing).mockReset().mockReturnValueOnce(oldDeletion.promise).mockReturnValueOnce(newDeletion.promise);
+    const view = render(<ForeshadowingPage worldId="world-a" />);
+    fireEvent.click(await screen.findByRole('option', { name: /A thread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Delete foreshadowing' }));
+    view.rerender(<ForeshadowingPage worldId="world-b" />);
+    await screen.findByRole('option', { name: /B thread/ });
+    view.rerender(<ForeshadowingPage worldId="world-a" />);
+    fireEvent.click(await screen.findByRole('option', { name: /A thread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Delete foreshadowing' }));
+
+    await act(async () => oldDeletion.resolve({ ok: true }));
+
+    expect(screen.getByRole('button', { name: 'Delete foreshadowing' })).toBeDisabled();
+    expect(screen.getByRole('option', { name: /A thread/ })).toBeDefined();
+    await act(async () => newDeletion.resolve({ ok: true }));
+  });
+
   it('closes the create mutation when the world changes', async () => {
     vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
     const view = render(
@@ -155,6 +193,74 @@ describe('Foreshadowing page', () => {
 
     expect(screen.queryByRole('dialog')).toBeNull();
   });
+
+  it('does not let an A-B-A secret delete completion clear the new generation lock', async () => {
+    const oldDeletion = deferred<{ ok: boolean }>();
+    const newDeletion = deferred<{ ok: boolean }>();
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listSecrets).mockImplementation((worldId) => Promise.resolve({ ok: true, items: [{ id: 'shared', title: `${worldId} secret`, status: 'active' }] }));
+    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
+    vi.mocked(api.deleteSecret).mockReset().mockReturnValueOnce(oldDeletion.promise).mockReturnValueOnce(newDeletion.promise);
+    const view = render(<SecretsPage worldId="world-a" />);
+    fireEvent.click(await screen.findByRole('option', { name: /world-a secret/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Delete secret' }));
+    view.rerender(<SecretsPage worldId="world-b" />);
+    await screen.findByRole('option', { name: /world-b secret/ });
+    view.rerender(<SecretsPage worldId="world-a" />);
+    fireEvent.click(await screen.findByRole('option', { name: /world-a secret/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Delete secret' }));
+
+    await act(async () => oldDeletion.resolve({ ok: true }));
+
+    expect(screen.getByRole('button', { name: 'Delete secret' })).toBeDisabled();
+    expect(screen.getByRole('option', { name: /world-a secret/ })).toBeDefined();
+    await act(async () => newDeletion.resolve({ ok: true }));
+  });
+});
+
+describe('Task 10 create mutation lifetime', () => {
+  it.each([
+    ['foreshadowing', CreateForeshadowingModal, 'createForeshadowing'],
+    ['secret', CreateSecretModal, 'createSecret'],
+  ] as const)('ignores %s callbacks after unmount', async (_name, Modal, method) => {
+    const creation = deferred<{ ok: boolean }>();
+    const onCreated = vi.fn();
+    const onClose = vi.fn();
+    vi.mocked(api[method]).mockReturnValue(creation.promise as never);
+    const view = render(<AppStateProvider><Modal worldId="world-a" onCreated={onCreated} onClose={onClose} /></AppStateProvider>);
+    const field = view.container.querySelector('textarea, input') as HTMLInputElement | HTMLTextAreaElement;
+    fireEvent.change(field, { target: { value: 'Required value' } });
+    const submit = Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement;
+    fireEvent.click(submit);
+    view.unmount();
+
+    await act(async () => creation.resolve({ ok: true }));
+
+    expect(onCreated).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ['foreshadowing', CreateForeshadowingModal, 'createForeshadowing'],
+    ['secret', CreateSecretModal, 'createSecret'],
+  ] as const)('ignores stale %s callbacks after an A-B-A world change', async (_name, Modal, method) => {
+    const creation = deferred<{ ok: boolean }>();
+    const onCreated = vi.fn();
+    const onClose = vi.fn();
+    vi.mocked(api[method]).mockReturnValue(creation.promise as never);
+    const renderModal = (worldId: string) => <AppStateProvider><Modal worldId={worldId} onCreated={onCreated} onClose={onClose} /></AppStateProvider>;
+    const view = render(renderModal('world-a'));
+    const field = view.container.querySelector('textarea, input') as HTMLInputElement | HTMLTextAreaElement;
+    fireEvent.change(field, { target: { value: 'Required value' } });
+    fireEvent.click(Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement);
+    view.rerender(renderModal('world-b'));
+    view.rerender(renderModal('world-a'));
+
+    await act(async () => creation.resolve({ ok: true }));
+
+    expect(onCreated).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
 });
 
 describe('Secrets page', () => {
diff --git a/webui/src/api/client.ts b/webui/src/api/client.ts
index 3bcaf381..fe98688e 100644
--- a/webui/src/api/client.ts
+++ b/webui/src/api/client.ts
@@ -453,6 +453,7 @@ export const api = {
       stakes?: string;
       aware_character_ids?: string[];
       suspicious_character_ids?: string[];
+      related_foreshadowing_ids?: string[];
       session_id?: string;
     },
   ) => request<CreateSecretResponse>('POST', `/api/worldbuilding/${worldId}/secrets`, data),
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 3c33f28d..3abedab8 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -185,9 +185,6 @@ export interface ForeshadowingItem {
   tags?: string[];
   planted_at?: string;
   paid_at?: string;
-  planned_chapter_position?: number;
-  current_chapter_position?: number;
-  related_secret_ids?: string[];
 }
 
 export interface ForeshadowingListResponse {
diff --git a/webui/src/components/Inspector/CreateForeshadowingModal.tsx b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
index 580453ff..8b4e3fae 100644
--- a/webui/src/components/Inspector/CreateForeshadowingModal.tsx
+++ b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
@@ -19,14 +19,14 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const submittingRef = useRef(false);
-  const mountedRef = useRef(true);
-  const worldRef = useRef(worldId);
-  worldRef.current = worldId;
+  const generationRef = useRef(0);
+  const renderedWorldRef = useRef(worldId);
+  if (renderedWorldRef.current !== worldId) {
+    renderedWorldRef.current = worldId;
+    generationRef.current += 1;
+  }
 
-  useEffect(() => {
-    mountedRef.current = true;
-    return () => { mountedRef.current = false; };
-  }, []);
+  useEffect(() => () => { generationRef.current += 1; }, []);
 
   useEffect(() => {
     function onKey(e: KeyboardEvent) { if (e.key === 'Escape' && !submitting) onClose(); }
@@ -37,6 +37,7 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
   async function handleSubmit() {
     if (!content.trim() || submittingRef.current) return;
     const operationWorld = worldId;
+    const operationGeneration = generationRef.current;
     submittingRef.current = true;
     setSubmitting(true);
     setError(null);
@@ -48,14 +49,14 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
         tags: tags ? tags.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      if (mountedRef.current && worldRef.current === operationWorld) {
+      if (generationRef.current === operationGeneration) {
         await onCreated?.();
-        if (mountedRef.current && worldRef.current === operationWorld) onClose();
+        if (generationRef.current === operationGeneration) onClose();
       }
     } catch (e) {
-      if (mountedRef.current && worldRef.current === operationWorld) setError((e as Error).message);
+      if (generationRef.current === operationGeneration) setError((e as Error).message);
     } finally {
-      if (mountedRef.current && worldRef.current === operationWorld) {
+      if (generationRef.current === operationGeneration) {
         submittingRef.current = false;
         setSubmitting(false);
       }
diff --git a/webui/src/components/Inspector/CreateSecretModal.tsx b/webui/src/components/Inspector/CreateSecretModal.tsx
index 39084a05..d0044561 100644
--- a/webui/src/components/Inspector/CreateSecretModal.tsx
+++ b/webui/src/components/Inspector/CreateSecretModal.tsx
@@ -21,14 +21,14 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
   const [submitting, setSubmitting] = useState(false);
   const [error, setError] = useState<string | null>(null);
   const submittingRef = useRef(false);
-  const mountedRef = useRef(true);
-  const worldRef = useRef(worldId);
-  worldRef.current = worldId;
+  const generationRef = useRef(0);
+  const renderedWorldRef = useRef(worldId);
+  if (renderedWorldRef.current !== worldId) {
+    renderedWorldRef.current = worldId;
+    generationRef.current += 1;
+  }
 
-  useEffect(() => {
-    mountedRef.current = true;
-    return () => { mountedRef.current = false; };
-  }, []);
+  useEffect(() => () => { generationRef.current += 1; }, []);
 
   useEffect(() => {
     function onKey(e: KeyboardEvent) { if (e.key === 'Escape' && !submitting) onClose(); }
@@ -39,6 +39,7 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
   async function handleSubmit() {
     if ((!title.trim() && !truth.trim()) || submittingRef.current) return;
     const operationWorld = worldId;
+    const operationGeneration = generationRef.current;
     submittingRef.current = true;
     setSubmitting(true);
     setError(null);
@@ -52,14 +53,14 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
         suspicious_character_ids: suspiciousIds ? suspiciousIds.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      if (mountedRef.current && worldRef.current === operationWorld) {
+      if (generationRef.current === operationGeneration) {
         await onCreated?.();
-        if (mountedRef.current && worldRef.current === operationWorld) onClose();
+        if (generationRef.current === operationGeneration) onClose();
       }
     } catch (e) {
-      if (mountedRef.current && worldRef.current === operationWorld) setError((e as Error).message);
+      if (generationRef.current === operationGeneration) setError((e as Error).message);
     } finally {
-      if (mountedRef.current && worldRef.current === operationWorld) {
+      if (generationRef.current === operationGeneration) {
         submittingRef.current = false;
         setSubmitting(false);
       }
diff --git a/webui/src/pages/ForeshadowingPage.tsx b/webui/src/pages/ForeshadowingPage.tsx
index 2c9fddf8..3e5096d3 100644
--- a/webui/src/pages/ForeshadowingPage.tsx
+++ b/webui/src/pages/ForeshadowingPage.tsx
@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { Filter, Pencil, Plus, RefreshCw, Sparkles, Trash2 } from 'lucide-react';
 import { api } from '../api/client';
-import type { ForeshadowingItem } from '../api/types';
+import type { ForeshadowingItem, StoryChapter, StoryScene } from '../api/types';
 import CreateForeshadowingModal from '../components/Inspector/CreateForeshadowingModal';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
@@ -10,24 +10,31 @@ import styles from './ForeshadowingPage.module.css';
 
 type Data = {
   items: ForeshadowingItem[];
+  chapters: StoryChapter[];
+  scenes: StoryScene[];
+  contextError: string | null;
 };
 
 export function deriveForeshadowingStatus(
-  item: Pick<ForeshadowingItem, 'status' | 'planned_chapter_position' | 'current_chapter_position'>,
-  _currentChapterPosition: number | null,
+  positions: { status?: string; plannedPosition: number | null; currentPosition: number | null },
 ): 'overdue' | null {
-  if (
-    item.status !== 'open' ||
-    item.planned_chapter_position == null ||
-    item.current_chapter_position == null
-  ) return null;
-  return item.current_chapter_position > item.planned_chapter_position ? 'overdue' : null;
+  if (positions.status !== 'open' || positions.plannedPosition == null || positions.currentPosition == null) return null;
+  return positions.currentPosition > positions.plannedPosition ? 'overdue' : null;
 }
 
 export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const resource = useResource(`foreshadowing:${worldId}`, async () => {
-    const foreshadowing = await api.listForeshadowing(worldId);
-    return { items: foreshadowing.foreshadowing ?? foreshadowing.items ?? [] };
+    const [foreshadowing, chapters, scenes] = await Promise.allSettled([
+      api.listForeshadowing(worldId), api.listChapters(worldId), api.listScenes(worldId),
+    ]);
+    if (foreshadowing.status === 'rejected') throw foreshadowing.reason;
+    const failures = [chapters, scenes].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
+    return {
+      items: foreshadowing.value.foreshadowing ?? foreshadowing.value.items ?? [],
+      chapters: chapters.status === 'fulfilled' ? chapters.value.chapters : [],
+      scenes: scenes.status === 'fulfilled' ? scenes.value.scenes : [],
+      contextError: failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') || null,
+    };
   });
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [filter, setFilter] = useState('all');
@@ -38,14 +45,19 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const [mutationError, setMutationError] = useState<string | null>(null);
   const [pendingMutation, setPendingMutation] = useState<string | null>(null);
   const pendingMutationRef = useRef(false);
-  const worldRef = useRef(worldId);
-  worldRef.current = worldId;
+  const generationRef = useRef(0);
+  const renderedWorldRef = useRef(worldId);
+  if (renderedWorldRef.current !== worldId) {
+    renderedWorldRef.current = worldId;
+    generationRef.current += 1;
+  }
   const data: Data | null = resource.data;
   const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
   useEffect(() => { setSelectedId(null); setRemoved([]); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
+  useEffect(() => () => { generationRef.current += 1; }, []);
   useEffect(() => {
     if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null);
   }, [filtered, selectedId]);
@@ -54,12 +66,13 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   async function save() {
     if (!selected || pendingMutationRef.current || !window.confirm('Update this foreshadowing item?')) return;
     const operationWorld = worldId;
+    const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('update');
     setMutationError(null);
-    try { await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff }); if (worldRef.current === operationWorld) { setEditing(false); resource.retry(); } }
-    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
-    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff }); if (generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
+    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
 
   async function remove() {
@@ -67,11 +80,12 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
     setMutationError(null);
     const id = selected.id;
     const operationWorld = worldId;
+    const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('delete');
-    try { await api.deleteForeshadowing(operationWorld, id); if (worldRef.current === operationWorld) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); resource.retry(); } }
-    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
-    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.deleteForeshadowing(operationWorld, id); if (generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); resource.retry(); } }
+    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
 
   function changeFilter(nextFilter: string) {
@@ -86,8 +100,8 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
       <aside className={styles.listPane}>
         <header><div><span>Narrative threads</span><h1>Foreshadowing</h1></div><div className={styles.tools}><button aria-label="Refresh foreshadowing" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create foreshadowing" disabled={Boolean(pendingMutation)} onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
         <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => changeFilter(event.target.value)}><option value="all">All</option><option value="open">Open</option><option value="paid">Paid</option><option value="abandoned">Abandoned</option></select></label>
-        {(resource.error || mutationError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message}</div>}
-        {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Foreshadowing" renderItem={(item) => <div className={styles.listItem}><Sparkles /><div><strong>{item.content}</strong><span>{item.status ?? 'No status'}{deriveForeshadowingStatus(item, null) ? ' · overdue' : ''}</span></div></div>} /> : <p className={styles.empty}>No foreshadowing matches this filter.</p>}
+        {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
+        {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Foreshadowing" renderItem={(item) => <div className={styles.listItem}><Sparkles /><div><strong>{item.content}</strong><span>{item.status ?? 'No status'}</span></div></div>} /> : <p className={styles.empty}>No foreshadowing matches this filter.</p>}
         <footer>{filtered.length} {filtered.length === 1 ? 'thread' : 'threads'}</footer>
       </aside>
       <section className={styles.detail} aria-label="Foreshadowing detail">
@@ -97,7 +111,7 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
           {selected.tags?.length ? <section className={styles.block}><h3>Tags</h3><div className={styles.chips}>{selected.tags.map((tag) => <span key={tag}>{tag}</span>)}</div></section> : null}
         </> : <Pick icon={<Sparkles />} title="Select foreshadowing" text="Choose a thread to inspect its recorded details." />}
       </section>
-      <aside className={styles.contextPane}><h2>Real context</h2><p>The foreshadowing list API does not expose chapter, scene, or character relationships.</p></aside>
+      <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <ForeshadowingContext item={selected} data={data} /> : <p>Select a thread to see resolved narrative positions.</p>}</aside>
       {createOpen ? <CreateForeshadowingModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
     </main>
   );
@@ -105,3 +119,9 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
 
 function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
 function Pick({ icon, title, text }: { icon: React.ReactNode; title: string; text: string }) { return <div className={styles.pick}>{icon}<h2>{title}</h2><p>{text}</p></div>; }
+function ForeshadowingContext({ item, data }: { item: ForeshadowingItem; data: Data }) {
+  const resolve = (id?: string) => data.scenes.find((scene) => scene.id === id)?.title ?? data.chapters.find((chapter) => chapter.id === id)?.title;
+  const planted = resolve(item.planted_at);
+  const paid = resolve(item.paid_at);
+  return <div className={styles.context}>{planted ? <Fact label="Planted narrative position" value={planted} /> : null}{paid ? <Fact label="Paid narrative position" value={paid} /> : null}{!planted && !paid ? <p>No resolvable narrative positions recorded.</p> : null}</div>;
+}
diff --git a/webui/src/pages/SecretsPage.tsx b/webui/src/pages/SecretsPage.tsx
index 606f2a1f..7e0c3dc1 100644
--- a/webui/src/pages/SecretsPage.tsx
+++ b/webui/src/pages/SecretsPage.tsx
@@ -31,34 +31,41 @@ export default function SecretsPage({ worldId }: { worldId: string }) {
   const [mutationError, setMutationError] = useState<string | null>(null);
   const [pendingMutation, setPendingMutation] = useState<string | null>(null);
   const pendingMutationRef = useRef(false);
-  const worldRef = useRef(worldId);
-  worldRef.current = worldId;
+  const generationRef = useRef(0);
+  const renderedWorldRef = useRef(worldId);
+  if (renderedWorldRef.current !== worldId) {
+    renderedWorldRef.current = worldId;
+    generationRef.current += 1;
+  }
   const data: Data | null = resource.data;
   const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
   useEffect(() => { setSelectedId(null); setRemoved([]); setRevealedTruth(null); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
+  useEffect(() => () => { generationRef.current += 1; }, []);
   useEffect(() => { setRevealedTruth(null); setEditing(false); setPublicVersion(selected?.public_version ?? ''); }, [selected?.id]);
   useEffect(() => { if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null); }, [filtered, selectedId]);
 
   async function save() {
     if (!selected || pendingMutationRef.current || !window.confirm('Update this secret?')) return;
     const operationWorld = worldId;
+    const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('update'); setMutationError(null);
-    try { await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion }); if (worldRef.current === operationWorld) { setEditing(false); resource.retry(); } }
-    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
-    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion }); if (generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
+    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
   async function remove() {
     if (!selected || pendingMutationRef.current || !window.confirm('Delete this secret?')) return;
     const operationWorld = worldId; const id = selected.id;
+    const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('delete'); setMutationError(null);
-    try { await api.deleteSecret(operationWorld, id); if (worldRef.current === operationWorld) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } }
-    catch (error) { if (worldRef.current === operationWorld) setMutationError((error as Error).message); }
-    finally { if (worldRef.current === operationWorld) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.deleteSecret(operationWorld, id); if (generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } }
+    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
   function changeFilter(nextFilter: string) {
     setFilter(nextFilter);

From abb6ef8dbcf09a39de50e32439bfeb344c80939d Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 23:15:42 +0800
Subject: [PATCH 37/49] fix(webui): guard narrative mutations across committed
 worlds

---
 webui/src/__tests__/pages.test.tsx            | 49 +++++++++++++++++--
 .../Inspector/CreateForeshadowingModal.tsx    | 25 +++++-----
 .../Inspector/CreateSecretModal.tsx           | 25 +++++-----
 webui/src/pages/ForeshadowingPage.tsx         | 31 +++++++-----
 webui/src/pages/SecretsPage.tsx               | 28 ++++++-----
 5 files changed, 108 insertions(+), 50 deletions(-)

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 1053e80e..5bc05993 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { useState } from 'react';
+import { startTransition, Suspense, useState } from 'react';
 import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
@@ -111,8 +111,9 @@ describe('Foreshadowing page', () => {
     vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [{ id: 'scene-1', title: 'The warning', status: 'planned', chapter_id: 'chapter-1' }] });
     render(<ForeshadowingPage worldId="world-1" />);
     fireEvent.click(await screen.findByRole('option', { name: /Silver bell/ }));
-    expect(screen.getByText('The warning')).toBeDefined();
-    expect(screen.getByText('Reckoning')).toBeDefined();
+    const positions = screen.getByRole('heading', { name: 'Narrative positions' }).parentElement!;
+    expect(within(positions).getByText('The warning')).toBeDefined();
+    expect(within(positions).getByText('Reckoning')).toBeDefined();
 
     vi.mocked(api.listChapters).mockRejectedValue(new Error('Chapters unavailable'));
     vi.mocked(api.listScenes).mockRejectedValue(new Error('Scenes unavailable'));
@@ -174,6 +175,27 @@ describe('Foreshadowing page', () => {
     await act(async () => newDeletion.resolve({ ok: true }));
   });
 
+  it('keeps the committed world mutation valid when a different world render is suspended', async () => {
+    const deletion = deferred<{ ok: boolean }>();
+    const suspended = new Promise<never>(() => {});
+    vi.spyOn(window, 'confirm').mockReturnValue(true);
+    vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [{ id: 'f1', content: 'Committed thread', status: 'open' }] });
+    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
+    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
+    vi.mocked(api.deleteForeshadowing).mockReset().mockReturnValue(deletion.promise);
+    const SuspendRender = ({ active }: { active: boolean }) => { if (active) throw suspended; return null; };
+    const page = (worldId: string, suspend: boolean) => <Suspense fallback={<p>Suspended</p>}><ForeshadowingPage worldId={worldId} /><SuspendRender active={suspend} /></Suspense>;
+    const view = render(page('world-a', false));
+    fireEvent.click(await screen.findByRole('option', { name: /Committed thread/ }));
+    fireEvent.click(screen.getByRole('button', { name: 'Delete foreshadowing' }));
+
+    act(() => { startTransition(() => view.rerender(page('world-b', true))); });
+    await act(async () => deletion.reject(new Error('Delete failed')));
+
+    expect(screen.getByRole('alert')).toHaveTextContent('Delete failed');
+    expect(screen.getByRole('button', { name: 'Delete foreshadowing' })).not.toBeDisabled();
+  });
+
   it('closes the create mutation when the world changes', async () => {
     vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
     const view = render(
@@ -261,6 +283,27 @@ describe('Task 10 create mutation lifetime', () => {
     expect(onCreated).not.toHaveBeenCalled();
     expect(onClose).not.toHaveBeenCalled();
   });
+
+  it.each([
+    ['foreshadowing', CreateForeshadowingModal, 'createForeshadowing'],
+    ['secret', CreateSecretModal, 'createSecret'],
+  ] as const)('keeps the committed %s creation valid when another world render is suspended', async (_name, Modal, method) => {
+    const creation = deferred<{ ok: boolean }>();
+    const suspended = new Promise<never>(() => {});
+    vi.mocked(api[method]).mockReturnValue(creation.promise as never);
+    const SuspendRender = ({ active }: { active: boolean }) => { if (active) throw suspended; return null; };
+    const renderModal = (worldId: string, suspend: boolean) => <AppStateProvider><Suspense fallback={<p>Suspended</p>}><Modal worldId={worldId} onClose={vi.fn()} /><SuspendRender active={suspend} /></Suspense></AppStateProvider>;
+    const view = render(renderModal('world-a', false));
+    const field = view.container.querySelector('textarea, input') as HTMLInputElement | HTMLTextAreaElement;
+    fireEvent.change(field, { target: { value: 'Required value' } });
+    fireEvent.click(Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement);
+
+    act(() => { startTransition(() => view.rerender(renderModal('world-b', true))); });
+    await act(async () => creation.reject(new Error('Create failed')));
+
+    expect(screen.getByText('Create failed')).toBeDefined();
+    expect(Array.from(view.container.querySelectorAll('button')).at(-1)).not.toBeDisabled();
+  });
 });
 
 describe('Secrets page', () => {
diff --git a/webui/src/components/Inspector/CreateForeshadowingModal.tsx b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
index 8b4e3fae..045650e7 100644
--- a/webui/src/components/Inspector/CreateForeshadowingModal.tsx
+++ b/webui/src/components/Inspector/CreateForeshadowingModal.tsx
@@ -20,13 +20,17 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
   const [error, setError] = useState<string | null>(null);
   const submittingRef = useRef(false);
   const generationRef = useRef(0);
-  const renderedWorldRef = useRef(worldId);
-  if (renderedWorldRef.current !== worldId) {
-    renderedWorldRef.current = worldId;
-    generationRef.current += 1;
-  }
+  const committedWorldRef = useRef(worldId);
+  const mountedRef = useRef(false);
 
-  useEffect(() => () => { generationRef.current += 1; }, []);
+  useEffect(() => {
+    mountedRef.current = true;
+    if (committedWorldRef.current !== worldId) {
+      committedWorldRef.current = worldId;
+      generationRef.current += 1;
+    }
+    return () => { mountedRef.current = false; generationRef.current += 1; };
+  }, [worldId]);
 
   useEffect(() => {
     function onKey(e: KeyboardEvent) { if (e.key === 'Escape' && !submitting) onClose(); }
@@ -36,7 +40,6 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
 
   async function handleSubmit() {
     if (!content.trim() || submittingRef.current) return;
-    const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     submittingRef.current = true;
     setSubmitting(true);
@@ -49,14 +52,14 @@ export default function CreateForeshadowingModal({ worldId, onClose, onCreated }
         tags: tags ? tags.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      if (generationRef.current === operationGeneration) {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
         await onCreated?.();
-        if (generationRef.current === operationGeneration) onClose();
+        if (mountedRef.current && generationRef.current === operationGeneration) onClose();
       }
     } catch (e) {
-      if (generationRef.current === operationGeneration) setError((e as Error).message);
+      if (mountedRef.current && generationRef.current === operationGeneration) setError((e as Error).message);
     } finally {
-      if (generationRef.current === operationGeneration) {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
         submittingRef.current = false;
         setSubmitting(false);
       }
diff --git a/webui/src/components/Inspector/CreateSecretModal.tsx b/webui/src/components/Inspector/CreateSecretModal.tsx
index d0044561..def8f448 100644
--- a/webui/src/components/Inspector/CreateSecretModal.tsx
+++ b/webui/src/components/Inspector/CreateSecretModal.tsx
@@ -22,13 +22,17 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
   const [error, setError] = useState<string | null>(null);
   const submittingRef = useRef(false);
   const generationRef = useRef(0);
-  const renderedWorldRef = useRef(worldId);
-  if (renderedWorldRef.current !== worldId) {
-    renderedWorldRef.current = worldId;
-    generationRef.current += 1;
-  }
+  const committedWorldRef = useRef(worldId);
+  const mountedRef = useRef(false);
 
-  useEffect(() => () => { generationRef.current += 1; }, []);
+  useEffect(() => {
+    mountedRef.current = true;
+    if (committedWorldRef.current !== worldId) {
+      committedWorldRef.current = worldId;
+      generationRef.current += 1;
+    }
+    return () => { mountedRef.current = false; generationRef.current += 1; };
+  }, [worldId]);
 
   useEffect(() => {
     function onKey(e: KeyboardEvent) { if (e.key === 'Escape' && !submitting) onClose(); }
@@ -38,7 +42,6 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
 
   async function handleSubmit() {
     if ((!title.trim() && !truth.trim()) || submittingRef.current) return;
-    const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     submittingRef.current = true;
     setSubmitting(true);
@@ -53,14 +56,14 @@ export default function CreateSecretModal({ worldId, onClose, onCreated }: Props
         suspicious_character_ids: suspiciousIds ? suspiciousIds.split(',').map(t => t.trim()).filter(Boolean) : undefined,
         session_id: state.sessionId,
       });
-      if (generationRef.current === operationGeneration) {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
         await onCreated?.();
-        if (generationRef.current === operationGeneration) onClose();
+        if (mountedRef.current && generationRef.current === operationGeneration) onClose();
       }
     } catch (e) {
-      if (generationRef.current === operationGeneration) setError((e as Error).message);
+      if (mountedRef.current && generationRef.current === operationGeneration) setError((e as Error).message);
     } finally {
-      if (generationRef.current === operationGeneration) {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
         submittingRef.current = false;
         setSubmitting(false);
       }
diff --git a/webui/src/pages/ForeshadowingPage.tsx b/webui/src/pages/ForeshadowingPage.tsx
index 3e5096d3..6269d9c4 100644
--- a/webui/src/pages/ForeshadowingPage.tsx
+++ b/webui/src/pages/ForeshadowingPage.tsx
@@ -46,18 +46,22 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const [pendingMutation, setPendingMutation] = useState<string | null>(null);
   const pendingMutationRef = useRef(false);
   const generationRef = useRef(0);
-  const renderedWorldRef = useRef(worldId);
-  if (renderedWorldRef.current !== worldId) {
-    renderedWorldRef.current = worldId;
-    generationRef.current += 1;
-  }
+  const committedWorldRef = useRef(worldId);
+  const mountedRef = useRef(false);
   const data: Data | null = resource.data;
   const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
   useEffect(() => { setSelectedId(null); setRemoved([]); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
-  useEffect(() => () => { generationRef.current += 1; }, []);
+  useEffect(() => {
+    mountedRef.current = true;
+    if (committedWorldRef.current !== worldId) {
+      committedWorldRef.current = worldId;
+      generationRef.current += 1;
+    }
+    return () => { mountedRef.current = false; generationRef.current += 1; };
+  }, [worldId]);
   useEffect(() => {
     if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null);
   }, [filtered, selectedId]);
@@ -70,9 +74,9 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
     pendingMutationRef.current = true;
     setPendingMutation('update');
     setMutationError(null);
-    try { await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff }); if (generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
-    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff }); if (mountedRef.current && generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
 
   async function remove() {
@@ -83,9 +87,9 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('delete');
-    try { await api.deleteForeshadowing(operationWorld, id); if (generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); resource.retry(); } }
-    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.deleteForeshadowing(operationWorld, id); if (mountedRef.current && generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
 
   function changeFilter(nextFilter: string) {
@@ -123,5 +127,6 @@ function ForeshadowingContext({ item, data }: { item: ForeshadowingItem; data: D
   const resolve = (id?: string) => data.scenes.find((scene) => scene.id === id)?.title ?? data.chapters.find((chapter) => chapter.id === id)?.title;
   const planted = resolve(item.planted_at);
   const paid = resolve(item.paid_at);
-  return <div className={styles.context}>{planted ? <Fact label="Planted narrative position" value={planted} /> : null}{paid ? <Fact label="Paid narrative position" value={paid} /> : null}{!planted && !paid ? <p>No resolvable narrative positions recorded.</p> : null}</div>;
+  const positions = [planted, paid].filter(Boolean) as string[];
+  return <div className={styles.context}>{positions.length ? <div><h3>Narrative positions</h3><div className={styles.chips}>{positions.map((position) => <span key={position}>{position}</span>)}</div></div> : <p>No resolvable narrative positions recorded.</p>}</div>;
 }
diff --git a/webui/src/pages/SecretsPage.tsx b/webui/src/pages/SecretsPage.tsx
index 7e0c3dc1..493696d0 100644
--- a/webui/src/pages/SecretsPage.tsx
+++ b/webui/src/pages/SecretsPage.tsx
@@ -32,18 +32,22 @@ export default function SecretsPage({ worldId }: { worldId: string }) {
   const [pendingMutation, setPendingMutation] = useState<string | null>(null);
   const pendingMutationRef = useRef(false);
   const generationRef = useRef(0);
-  const renderedWorldRef = useRef(worldId);
-  if (renderedWorldRef.current !== worldId) {
-    renderedWorldRef.current = worldId;
-    generationRef.current += 1;
-  }
+  const committedWorldRef = useRef(worldId);
+  const mountedRef = useRef(false);
   const data: Data | null = resource.data;
   const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
   useEffect(() => { setSelectedId(null); setRemoved([]); setRevealedTruth(null); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
-  useEffect(() => () => { generationRef.current += 1; }, []);
+  useEffect(() => {
+    mountedRef.current = true;
+    if (committedWorldRef.current !== worldId) {
+      committedWorldRef.current = worldId;
+      generationRef.current += 1;
+    }
+    return () => { mountedRef.current = false; generationRef.current += 1; };
+  }, [worldId]);
   useEffect(() => { setRevealedTruth(null); setEditing(false); setPublicVersion(selected?.public_version ?? ''); }, [selected?.id]);
   useEffect(() => { if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null); }, [filtered, selectedId]);
 
@@ -53,9 +57,9 @@ export default function SecretsPage({ worldId }: { worldId: string }) {
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('update'); setMutationError(null);
-    try { await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion }); if (generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
-    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion }); if (mountedRef.current && generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
   async function remove() {
     if (!selected || pendingMutationRef.current || !window.confirm('Delete this secret?')) return;
@@ -63,9 +67,9 @@ export default function SecretsPage({ worldId }: { worldId: string }) {
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('delete'); setMutationError(null);
-    try { await api.deleteSecret(operationWorld, id); if (generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } }
-    catch (error) { if (generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try { await api.deleteSecret(operationWorld, id); if (mountedRef.current && generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
   function changeFilter(nextFilter: string) {
     setFilter(nextFilter);

From ffb0ff25c8573b018f3828d9d2529494595e96e8 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 23:30:01 +0800
Subject: [PATCH 38/49] feat(webui): add file library and desktop settings

---
 webui/src/App.tsx                             |  19 +-
 webui/src/__tests__/SettingsPanel.test.tsx    |  28 +-
 webui/src/__tests__/pages.test.tsx            | 399 ++++++++++---
 .../components/Inspector/FilesInspector.tsx   | 411 +++++++------
 webui/src/components/SettingsPage.module.css  | 304 ++--------
 webui/src/components/SettingsPage.tsx         | 561 ++++++------------
 webui/src/pages/FilesPage.module.css          |  76 +++
 webui/src/pages/FilesPage.tsx                 | 229 +++++++
 webui/src/pages/SettingsPage.module.css       |   1 +
 webui/src/pages/SettingsPage.tsx              |   1 +
 10 files changed, 1143 insertions(+), 886 deletions(-)
 create mode 100644 webui/src/pages/FilesPage.module.css
 create mode 100644 webui/src/pages/FilesPage.tsx
 create mode 100644 webui/src/pages/SettingsPage.module.css
 create mode 100644 webui/src/pages/SettingsPage.tsx

diff --git a/webui/src/App.tsx b/webui/src/App.tsx
index fa81e7e1..26b868da 100644
--- a/webui/src/App.tsx
+++ b/webui/src/App.tsx
@@ -10,7 +10,6 @@ import CreationRequestDialog from './components/CreationRequestDialog';
 import ErrorBoundary from './components/ErrorBoundary';
 import InspectorPanel from './components/InspectorPanel';
 import MainPanel from './components/MainPanel';
-import SettingsPage from './components/SettingsPage';
 import Skeleton from './components/Skeleton';
 import { ToastProvider } from './components/Toast';
 import WorldDashboard from './components/WorldDashboard';
@@ -34,6 +33,8 @@ const ChaptersPage = lazy(() => import('./pages/ChaptersPage'));
 const ScenesPage = lazy(() => import('./pages/ScenesPage'));
 const ForeshadowingPage = lazy(() => import('./pages/ForeshadowingPage'));
 const SecretsPage = lazy(() => import('./pages/SecretsPage'));
+const FilesPage = lazy(() => import('./pages/FilesPage'));
+const SettingsPage = lazy(() => import('./pages/SettingsPage'));
 
 export function shouldReportWorldbuildingPartialFailure(
   overviewLoaded: boolean,
@@ -298,7 +299,12 @@ function AppInner() {
 
   // Page-based rendering (overrides phase when navigating away from workbench)
   if (state.currentPage === 'settings') {
-    return inDesktopShell(<SettingsPage />, narrativePageOverlays);
+    return inDesktopShell(
+      <Suspense fallback={<Skeleton />}>
+        <SettingsPage />
+      </Suspense>,
+      narrativePageOverlays,
+    );
   }
 
   if (state.currentPage === 'editor' && state.activeEditorChapterId && state.worldId) {
@@ -415,6 +421,15 @@ function AppInner() {
     );
   }
 
+  if (state.currentPage === 'files' && state.worldId) {
+    return inDesktopShell(
+      <Suspense fallback={<Skeleton />}>
+        <FilesPage worldId={state.worldId} />
+      </Suspense>,
+      narrativePageOverlays,
+    );
+  }
+
   if (
     state.appPhase === 'no_agent' &&
     !shouldRenderSessionsPage(state.currentPage, state.appPhase)
diff --git a/webui/src/__tests__/SettingsPanel.test.tsx b/webui/src/__tests__/SettingsPanel.test.tsx
index c29c5b44..f75ca337 100644
--- a/webui/src/__tests__/SettingsPanel.test.tsx
+++ b/webui/src/__tests__/SettingsPanel.test.tsx
@@ -1,7 +1,9 @@
 import { render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
+import { AppStateProvider } from '../AppState';
 import SettingsPanel from '../components/Sidebar/SettingsPanel';
 import { I18nProvider } from '../i18n';
+import SettingsPage from '../pages/SettingsPage';
 
 vi.mock('../api/client', () => ({
   api: {
@@ -14,6 +16,12 @@ vi.mock('../api/client', () => ({
     }),
     saveConfig: vi.fn().mockResolvedValue({ ok: true }),
     testConfig: vi.fn().mockResolvedValue({ ok: true }),
+    getPreferences: vi.fn().mockResolvedValue({
+      default_genre: 'No preference',
+      preferred_style: 'concise',
+      allow_usage_logs: true,
+    }),
+    savePreferences: vi.fn().mockResolvedValue({ ok: true }),
   },
   formatApiError: vi.fn((error: unknown, fallback: string) =>
     error instanceof Error ? error.message : fallback,
@@ -50,6 +58,24 @@ describe('SettingsPanel polish', () => {
     expect(screen.getByLabelText('访问密钥')).toBeDefined();
     expect(screen.getByText('本地桌面状态')).toBeDefined();
     expect(screen.getByRole('button', { name: '导出故障报告' })).toBeDefined();
-    expect(document.body.textContent ?? '').not.toMatch(/API Key|API Base URL|Runtime|Database|Diagnostics/i);
+    expect(document.body.textContent ?? '').not.toMatch(
+      /API Key|API Base URL|Runtime|Database|Diagnostics/i,
+    );
+  });
+});
+
+describe('Settings page capabilities', () => {
+  it('keeps API credentials masked and does not enable unsupported settings', async () => {
+    render(
+      <AppStateProvider>
+        <SettingsPage />
+      </AppStateProvider>,
+    );
+
+    const key = await screen.findByLabelText('API key');
+    expect(key).toHaveAttribute('type', 'password');
+    expect(screen.queryByRole('switch', { name: /auto.?save/i })).toBeNull();
+    expect(screen.queryByRole('combobox', { name: /theme/i })).toBeNull();
+    expect(screen.queryByRole('textbox', { name: /database/i })).toBeNull();
   });
 });
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 5bc05993..f10c5c2f 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -14,9 +14,10 @@ import ResourceList from '../components/layout/ResourceList';
 import { useResource } from '../hooks/useResource';
 import ChaptersPage from '../pages/ChaptersPage';
 import CharactersPage from '../pages/CharactersPage';
+import FilesPage from '../pages/FilesPage';
+import ForeshadowingPage, { deriveForeshadowingStatus } from '../pages/ForeshadowingPage';
 import OverviewPage from '../pages/OverviewPage';
 import ScenesPage from '../pages/ScenesPage';
-import ForeshadowingPage, { deriveForeshadowingStatus } from '../pages/ForeshadowingPage';
 import SecretsPage from '../pages/SecretsPage';
 import { selectWorldMetrics } from '../pages/selectors';
 import WorldPage from '../pages/WorldPage';
@@ -49,13 +50,152 @@ vi.mock('../api/client', () => ({
     createForeshadowing: vi.fn(),
     createSecret: vi.fn(),
   },
+  formatApiError: vi.fn((error: unknown, fallback: string) =>
+    error instanceof Error ? error.message : fallback,
+  ),
 }));
 
+describe('Files page', () => {
+  const file = {
+    id: 'draft',
+    path: 'chapters/draft.md',
+    name: 'draft.md',
+    ext: 'md',
+    mime: 'text/markdown',
+    size: 14,
+    updated_at: '2026-06-20T00:00:00Z',
+    dirty: false,
+  };
+
+  it('loads file content only after selection', async () => {
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: file.path,
+        content: 'Original text',
+        encoding: 'utf-8',
+        updated_at: file.updated_at,
+        version: 'v1',
+      },
+    });
+
+    render(<FilesPage worldId="world-1" />);
+    await screen.findByRole('option', { name: /draft/i });
+    expect(api.readWorkspaceFile).not.toHaveBeenCalled();
+    fireEvent.click(screen.getByRole('option', { name: /draft/i }));
+    expect(await screen.findByRole('textbox', { name: 'File content' })).toHaveValue(
+      'Original text',
+    );
+  });
+
+  it('preserves the local draft and offers Reload and Copy after a file conflict', async () => {
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: file.path,
+        content: 'Original text',
+        encoding: 'utf-8',
+        updated_at: file.updated_at,
+        version: 'v1',
+      },
+    });
+    vi.mocked(api.saveWorkspaceFile).mockRejectedValue(
+      Object.assign(new Error('File changed on disk'), { status: 409, code: 'file_conflict' }),
+    );
+
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    const editor = await screen.findByRole('textbox', { name: 'File content' });
+    fireEvent.change(editor, { target: { value: 'My local draft' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save file' }));
+
+    expect(await screen.findByRole('alert')).toHaveTextContent(/changed on disk/i);
+    expect(editor).toHaveValue('My local draft');
+    expect(screen.getByRole('button', { name: 'Reload file' })).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Copy local draft' })).toBeDefined();
+  });
+
+  it('ignores stale file reads across an A-B-A selection sequence', async () => {
+    const secondA = deferred<Awaited<ReturnType<typeof api.readWorkspaceFile>>>();
+    const firstA = deferred<Awaited<ReturnType<typeof api.readWorkspaceFile>>>();
+    const b = deferred<Awaited<ReturnType<typeof api.readWorkspaceFile>>>();
+    const other = { ...file, id: 'notes', path: 'notes.md', name: 'notes.md' };
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file, other],
+    });
+    vi.mocked(api.readWorkspaceFile)
+      .mockReturnValueOnce(firstA.promise)
+      .mockReturnValueOnce(b.promise)
+      .mockReturnValueOnce(secondA.promise);
+
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    fireEvent.click(screen.getByRole('option', { name: /notes/i }));
+    fireEvent.click(screen.getByRole('option', { name: /draft/i }));
+    await act(async () =>
+      secondA.resolve({
+        ok: true,
+        file: {
+          path: file.path,
+          content: 'Newest A',
+          encoding: 'utf-8',
+          updated_at: file.updated_at,
+          version: 'v3',
+        },
+      }),
+    );
+    await act(async () =>
+      firstA.resolve({
+        ok: true,
+        file: {
+          path: file.path,
+          content: 'Old A',
+          encoding: 'utf-8',
+          updated_at: file.updated_at,
+          version: 'v1',
+        },
+      }),
+    );
+    await act(async () =>
+      b.resolve({
+        ok: true,
+        file: {
+          path: other.path,
+          content: 'Old B',
+          encoding: 'utf-8',
+          updated_at: other.updated_at,
+          version: 'v2',
+        },
+      }),
+    );
+
+    expect(screen.getByRole('textbox', { name: 'File content' })).toHaveValue('Newest A');
+  });
+});
+
 describe('Foreshadowing page', () => {
   it('derives overdue only when planned and current chapter positions both exist', () => {
-    expect(deriveForeshadowingStatus({ status: 'open', plannedPosition: 2, currentPosition: null })).toBeNull();
-    expect(deriveForeshadowingStatus({ status: 'open', plannedPosition: 2, currentPosition: 4 })).toBe('overdue');
-    expect(deriveForeshadowingStatus({ status: 'open', plannedPosition: 5, currentPosition: 4 })).toBeNull();
+    expect(
+      deriveForeshadowingStatus({ status: 'open', plannedPosition: 2, currentPosition: null }),
+    ).toBeNull();
+    expect(
+      deriveForeshadowingStatus({ status: 'open', plannedPosition: 2, currentPosition: 4 }),
+    ).toBe('overdue');
+    expect(
+      deriveForeshadowingStatus({ status: 'open', plannedPosition: 5, currentPosition: 4 }),
+    ).toBeNull();
   });
 
   it('filters real records and keeps selection safe after deletion', async () => {
@@ -68,7 +208,10 @@ describe('Foreshadowing page', () => {
           { id: 'f2', content: 'Broken seal', status: 'paid' },
         ],
       })
-      .mockResolvedValueOnce({ ok: true, items: [{ id: 'f2', content: 'Broken seal', status: 'paid' }] });
+      .mockResolvedValueOnce({
+        ok: true,
+        items: [{ id: 'f2', content: 'Broken seal', status: 'paid' }],
+      });
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
     vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
     vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
@@ -79,7 +222,10 @@ describe('Foreshadowing page', () => {
     fireEvent.click(screen.getByRole('button', { name: 'Delete foreshadowing' }));
 
     await waitFor(() => expect(api.deleteForeshadowing).toHaveBeenCalledWith('world-1', 'f1'));
-    expect(screen.getByRole('option', { name: /Broken seal/ })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('option', { name: /Broken seal/ })).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
   });
 
   it('selects only visible records when the status filter changes', async () => {
@@ -98,17 +244,34 @@ describe('Foreshadowing page', () => {
 
     fireEvent.change(screen.getByLabelText('Status'), { target: { value: 'paid' } });
 
-    expect(screen.getByRole('option', { name: /Broken seal/ })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('option', { name: /Broken seal/ })).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
     expect(screen.getByRole('heading', { name: 'Broken seal' })).toBeDefined();
   });
 
   it('resolves real planted and paid narrative IDs and retains the list when context fails', async () => {
     vi.mocked(api.listForeshadowing).mockResolvedValue({
       ok: true,
-      items: [{ id: 'f1', content: 'Silver bell', status: 'paid', planted_at: 'scene-1', paid_at: 'chapter-2' }],
+      items: [
+        {
+          id: 'f1',
+          content: 'Silver bell',
+          status: 'paid',
+          planted_at: 'scene-1',
+          paid_at: 'chapter-2',
+        },
+      ],
+    });
+    vi.mocked(api.listChapters).mockResolvedValue({
+      ok: true,
+      chapters: [{ id: 'chapter-2', title: 'Reckoning', status: 'draft' }],
+    });
+    vi.mocked(api.listScenes).mockResolvedValue({
+      ok: true,
+      scenes: [{ id: 'scene-1', title: 'The warning', status: 'planned', chapter_id: 'chapter-1' }],
     });
-    vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [{ id: 'chapter-2', title: 'Reckoning', status: 'draft' }] });
-    vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [{ id: 'scene-1', title: 'The warning', status: 'planned', chapter_id: 'chapter-1' }] });
     render(<ForeshadowingPage worldId="world-1" />);
     fireEvent.click(await screen.findByRole('option', { name: /Silver bell/ }));
     const positions = screen.getByRole('heading', { name: 'Narrative positions' }).parentElement!;
@@ -126,10 +289,18 @@ describe('Foreshadowing page', () => {
     const deletion = deferred<{ ok: boolean }>();
     vi.mocked(api.deleteForeshadowing).mockClear();
     vi.spyOn(window, 'confirm').mockReturnValue(true);
-    vi.mocked(api.listForeshadowing).mockImplementation((worldId) => Promise.resolve({
-      ok: true,
-      items: [{ id: 'shared', content: worldId === 'world-1' ? 'Old thread' : 'New thread', status: 'open' }],
-    }));
+    vi.mocked(api.listForeshadowing).mockImplementation((worldId) =>
+      Promise.resolve({
+        ok: true,
+        items: [
+          {
+            id: 'shared',
+            content: worldId === 'world-1' ? 'Old thread' : 'New thread',
+            status: 'open',
+          },
+        ],
+      }),
+    );
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
     vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
     vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
@@ -152,13 +323,24 @@ describe('Foreshadowing page', () => {
     const oldDeletion = deferred<{ ok: boolean }>();
     const newDeletion = deferred<{ ok: boolean }>();
     vi.spyOn(window, 'confirm').mockReturnValue(true);
-    vi.mocked(api.listForeshadowing).mockImplementation((worldId) => Promise.resolve({
-      ok: true,
-      items: [{ id: 'shared', content: worldId === 'world-a' ? 'A thread' : 'B thread', status: 'open' }],
-    }));
+    vi.mocked(api.listForeshadowing).mockImplementation((worldId) =>
+      Promise.resolve({
+        ok: true,
+        items: [
+          {
+            id: 'shared',
+            content: worldId === 'world-a' ? 'A thread' : 'B thread',
+            status: 'open',
+          },
+        ],
+      }),
+    );
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
     vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
-    vi.mocked(api.deleteForeshadowing).mockReset().mockReturnValueOnce(oldDeletion.promise).mockReturnValueOnce(newDeletion.promise);
+    vi.mocked(api.deleteForeshadowing)
+      .mockReset()
+      .mockReturnValueOnce(oldDeletion.promise)
+      .mockReturnValueOnce(newDeletion.promise);
     const view = render(<ForeshadowingPage worldId="world-a" />);
     fireEvent.click(await screen.findByRole('option', { name: /A thread/ }));
     fireEvent.click(screen.getByRole('button', { name: 'Delete foreshadowing' }));
@@ -179,17 +361,30 @@ describe('Foreshadowing page', () => {
     const deletion = deferred<{ ok: boolean }>();
     const suspended = new Promise<never>(() => {});
     vi.spyOn(window, 'confirm').mockReturnValue(true);
-    vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [{ id: 'f1', content: 'Committed thread', status: 'open' }] });
+    vi.mocked(api.listForeshadowing).mockResolvedValue({
+      ok: true,
+      items: [{ id: 'f1', content: 'Committed thread', status: 'open' }],
+    });
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
     vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
     vi.mocked(api.deleteForeshadowing).mockReset().mockReturnValue(deletion.promise);
-    const SuspendRender = ({ active }: { active: boolean }) => { if (active) throw suspended; return null; };
-    const page = (worldId: string, suspend: boolean) => <Suspense fallback={<p>Suspended</p>}><ForeshadowingPage worldId={worldId} /><SuspendRender active={suspend} /></Suspense>;
+    const SuspendRender = ({ active }: { active: boolean }) => {
+      if (active) throw suspended;
+      return null;
+    };
+    const page = (worldId: string, suspend: boolean) => (
+      <Suspense fallback={<p>Suspended</p>}>
+        <ForeshadowingPage worldId={worldId} />
+        <SuspendRender active={suspend} />
+      </Suspense>
+    );
     const view = render(page('world-a', false));
     fireEvent.click(await screen.findByRole('option', { name: /Committed thread/ }));
     fireEvent.click(screen.getByRole('button', { name: 'Delete foreshadowing' }));
 
-    act(() => { startTransition(() => view.rerender(page('world-b', true))); });
+    act(() => {
+      startTransition(() => view.rerender(page('world-b', true)));
+    });
     await act(async () => deletion.reject(new Error('Delete failed')));
 
     expect(screen.getByRole('alert')).toHaveTextContent('Delete failed');
@@ -220,9 +415,17 @@ describe('Foreshadowing page', () => {
     const oldDeletion = deferred<{ ok: boolean }>();
     const newDeletion = deferred<{ ok: boolean }>();
     vi.spyOn(window, 'confirm').mockReturnValue(true);
-    vi.mocked(api.listSecrets).mockImplementation((worldId) => Promise.resolve({ ok: true, items: [{ id: 'shared', title: `${worldId} secret`, status: 'active' }] }));
+    vi.mocked(api.listSecrets).mockImplementation((worldId) =>
+      Promise.resolve({
+        ok: true,
+        items: [{ id: 'shared', title: `${worldId} secret`, status: 'active' }],
+      }),
+    );
     vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [] });
-    vi.mocked(api.deleteSecret).mockReset().mockReturnValueOnce(oldDeletion.promise).mockReturnValueOnce(newDeletion.promise);
+    vi.mocked(api.deleteSecret)
+      .mockReset()
+      .mockReturnValueOnce(oldDeletion.promise)
+      .mockReturnValueOnce(newDeletion.promise);
     const view = render(<SecretsPage worldId="world-a" />);
     fireEvent.click(await screen.findByRole('option', { name: /world-a secret/ }));
     fireEvent.click(screen.getByRole('button', { name: 'Delete secret' }));
@@ -249,10 +452,18 @@ describe('Task 10 create mutation lifetime', () => {
     const onCreated = vi.fn();
     const onClose = vi.fn();
     vi.mocked(api[method]).mockReturnValue(creation.promise as never);
-    const view = render(<AppStateProvider><Modal worldId="world-a" onCreated={onCreated} onClose={onClose} /></AppStateProvider>);
-    const field = view.container.querySelector('textarea, input') as HTMLInputElement | HTMLTextAreaElement;
+    const view = render(
+      <AppStateProvider>
+        <Modal worldId="world-a" onCreated={onCreated} onClose={onClose} />
+      </AppStateProvider>,
+    );
+    const field = view.container.querySelector('textarea, input') as
+      | HTMLInputElement
+      | HTMLTextAreaElement;
     fireEvent.change(field, { target: { value: 'Required value' } });
-    const submit = Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement;
+    const submit = Array.from(view.container.querySelectorAll('button')).at(
+      -1,
+    ) as HTMLButtonElement;
     fireEvent.click(submit);
     view.unmount();
 
@@ -265,52 +476,88 @@ describe('Task 10 create mutation lifetime', () => {
   it.each([
     ['foreshadowing', CreateForeshadowingModal, 'createForeshadowing'],
     ['secret', CreateSecretModal, 'createSecret'],
-  ] as const)('ignores stale %s callbacks after an A-B-A world change', async (_name, Modal, method) => {
-    const creation = deferred<{ ok: boolean }>();
-    const onCreated = vi.fn();
-    const onClose = vi.fn();
-    vi.mocked(api[method]).mockReturnValue(creation.promise as never);
-    const renderModal = (worldId: string) => <AppStateProvider><Modal worldId={worldId} onCreated={onCreated} onClose={onClose} /></AppStateProvider>;
-    const view = render(renderModal('world-a'));
-    const field = view.container.querySelector('textarea, input') as HTMLInputElement | HTMLTextAreaElement;
-    fireEvent.change(field, { target: { value: 'Required value' } });
-    fireEvent.click(Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement);
-    view.rerender(renderModal('world-b'));
-    view.rerender(renderModal('world-a'));
+  ] as const)(
+    'ignores stale %s callbacks after an A-B-A world change',
+    async (_name, Modal, method) => {
+      const creation = deferred<{ ok: boolean }>();
+      const onCreated = vi.fn();
+      const onClose = vi.fn();
+      vi.mocked(api[method]).mockReturnValue(creation.promise as never);
+      const renderModal = (worldId: string) => (
+        <AppStateProvider>
+          <Modal worldId={worldId} onCreated={onCreated} onClose={onClose} />
+        </AppStateProvider>
+      );
+      const view = render(renderModal('world-a'));
+      const field = view.container.querySelector('textarea, input') as
+        | HTMLInputElement
+        | HTMLTextAreaElement;
+      fireEvent.change(field, { target: { value: 'Required value' } });
+      fireEvent.click(
+        Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement,
+      );
+      view.rerender(renderModal('world-b'));
+      view.rerender(renderModal('world-a'));
 
-    await act(async () => creation.resolve({ ok: true }));
+      await act(async () => creation.resolve({ ok: true }));
 
-    expect(onCreated).not.toHaveBeenCalled();
-    expect(onClose).not.toHaveBeenCalled();
-  });
+      expect(onCreated).not.toHaveBeenCalled();
+      expect(onClose).not.toHaveBeenCalled();
+    },
+  );
 
   it.each([
     ['foreshadowing', CreateForeshadowingModal, 'createForeshadowing'],
     ['secret', CreateSecretModal, 'createSecret'],
-  ] as const)('keeps the committed %s creation valid when another world render is suspended', async (_name, Modal, method) => {
-    const creation = deferred<{ ok: boolean }>();
-    const suspended = new Promise<never>(() => {});
-    vi.mocked(api[method]).mockReturnValue(creation.promise as never);
-    const SuspendRender = ({ active }: { active: boolean }) => { if (active) throw suspended; return null; };
-    const renderModal = (worldId: string, suspend: boolean) => <AppStateProvider><Suspense fallback={<p>Suspended</p>}><Modal worldId={worldId} onClose={vi.fn()} /><SuspendRender active={suspend} /></Suspense></AppStateProvider>;
-    const view = render(renderModal('world-a', false));
-    const field = view.container.querySelector('textarea, input') as HTMLInputElement | HTMLTextAreaElement;
-    fireEvent.change(field, { target: { value: 'Required value' } });
-    fireEvent.click(Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement);
+  ] as const)(
+    'keeps the committed %s creation valid when another world render is suspended',
+    async (_name, Modal, method) => {
+      const creation = deferred<{ ok: boolean }>();
+      const suspended = new Promise<never>(() => {});
+      vi.mocked(api[method]).mockReturnValue(creation.promise as never);
+      const SuspendRender = ({ active }: { active: boolean }) => {
+        if (active) throw suspended;
+        return null;
+      };
+      const renderModal = (worldId: string, suspend: boolean) => (
+        <AppStateProvider>
+          <Suspense fallback={<p>Suspended</p>}>
+            <Modal worldId={worldId} onClose={vi.fn()} />
+            <SuspendRender active={suspend} />
+          </Suspense>
+        </AppStateProvider>
+      );
+      const view = render(renderModal('world-a', false));
+      const field = view.container.querySelector('textarea, input') as
+        | HTMLInputElement
+        | HTMLTextAreaElement;
+      fireEvent.change(field, { target: { value: 'Required value' } });
+      fireEvent.click(
+        Array.from(view.container.querySelectorAll('button')).at(-1) as HTMLButtonElement,
+      );
 
-    act(() => { startTransition(() => view.rerender(renderModal('world-b', true))); });
-    await act(async () => creation.reject(new Error('Create failed')));
+      act(() => {
+        startTransition(() => view.rerender(renderModal('world-b', true)));
+      });
+      await act(async () => creation.reject(new Error('Create failed')));
 
-    expect(screen.getByText('Create failed')).toBeDefined();
-    expect(Array.from(view.container.querySelectorAll('button')).at(-1)).not.toBeDisabled();
-  });
+      expect(screen.getByText('Create failed')).toBeDefined();
+      expect(Array.from(view.container.querySelectorAll('button')).at(-1)).not.toBeDisabled();
+    },
+  );
 });
 
 describe('Secrets page', () => {
   const secrets = {
     ok: true,
     items: [
-      { id: 's1', title: 'The pact', truth: 'The crown is counterfeit', status: 'active', aware_character_ids: ['a1', 'missing'] },
+      {
+        id: 's1',
+        title: 'The pact',
+        truth: 'The crown is counterfeit',
+        status: 'active',
+        aware_character_ids: ['a1', 'missing'],
+      },
       { id: 's2', title: 'The oath', truth: 'The oath was staged', status: 'exposed' },
     ],
   };
@@ -320,7 +567,10 @@ describe('Secrets page', () => {
     vi.mocked(api.listForeshadowing).mockResolvedValue({ ok: true, items: [] });
     vi.mocked(api.listChapters).mockResolvedValue({ ok: true, chapters: [] });
     vi.mocked(api.listScenes).mockResolvedValue({ ok: true, scenes: [] });
-    vi.mocked(api.listAgents).mockResolvedValue({ ok: true, agents: [{ id: 'a1', name: 'Mira', display_name: 'Mira', kind: 'character' }] });
+    vi.mocked(api.listAgents).mockResolvedValue({
+      ok: true,
+      agents: [{ id: 'a1', name: 'Mira', display_name: 'Mira', kind: 'character' }],
+    });
 
     const view = render(<SecretsPage worldId="world-1" />);
     fireEvent.click(await screen.findByRole('option', { name: /The pact/ }));
@@ -359,7 +609,10 @@ describe('Secrets page', () => {
 
     fireEvent.change(screen.getByLabelText('Status'), { target: { value: 'exposed' } });
 
-    expect(screen.getByRole('option', { name: /The oath/ })).toHaveAttribute('aria-selected', 'true');
+    expect(screen.getByRole('option', { name: /The oath/ })).toHaveAttribute(
+      'aria-selected',
+      'true',
+    );
     expect(screen.getByRole('heading', { name: 'The oath' })).toBeDefined();
   });
 
@@ -403,13 +656,21 @@ describe('Secrets page', () => {
 });
 
 describe('Foreshadowing and Secrets responsive layout', () => {
-  it.each(['ForeshadowingPage.module.css', 'SecretsPage.module.css'])('%s owns scrolling when context stacks', (file) => {
-    const css = readFileSync(join(process.cwd(), 'src/pages', file), 'utf8');
-    const responsive = css.slice(css.indexOf('@media (max-width: 1100px)'), css.indexOf('@media (max-width: 700px)'));
-    expect(css).toMatch(/\.workspace\s*\{[^}]*height:\s*100%[^}]*min-height:\s*0[^}]*overflow:\s*auto/s);
-    expect(responsive).toMatch(/\.workspace\s*\{[^}]*align-content:\s*start/s);
-    expect(responsive).not.toMatch(/\.contextPane\s*\{[^}]*display:\s*none/s);
-  });
+  it.each(['ForeshadowingPage.module.css', 'SecretsPage.module.css'])(
+    '%s owns scrolling when context stacks',
+    (file) => {
+      const css = readFileSync(join(process.cwd(), 'src/pages', file), 'utf8');
+      const responsive = css.slice(
+        css.indexOf('@media (max-width: 1100px)'),
+        css.indexOf('@media (max-width: 700px)'),
+      );
+      expect(css).toMatch(
+        /\.workspace\s*\{[^}]*height:\s*100%[^}]*min-height:\s*0[^}]*overflow:\s*auto/s,
+      );
+      expect(responsive).toMatch(/\.workspace\s*\{[^}]*align-content:\s*start/s);
+      expect(responsive).not.toMatch(/\.contextPane\s*\{[^}]*display:\s*none/s);
+    },
+  );
 });
 
 vi.mock('../api/worldbuilding', () => ({
diff --git a/webui/src/components/Inspector/FilesInspector.tsx b/webui/src/components/Inspector/FilesInspector.tsx
index bdedbe6c..2a69d0ce 100644
--- a/webui/src/components/Inspector/FilesInspector.tsx
+++ b/webui/src/components/Inspector/FilesInspector.tsx
@@ -1,15 +1,23 @@
-import { AlertCircle, CheckCircle2, FileText, FolderOpen, RotateCcw, Save, Search } from 'lucide-react';
-import { useMemo, useState } from 'react';
+import { useMemo, useRef, useState } from 'react';
+import {
+  AlertCircle,
+  CheckCircle2,
+  FileText,
+  FolderOpen,
+  RotateCcw,
+  Save,
+  Search,
+} from 'lucide-react';
 import { api, formatApiError } from '../../api/client';
-import { useAppState } from '../../AppState';
-import styles from '../InspectorPanel.module.css';
-import { useToast } from '../Toast';
-
+import { useAppState } from '../../AppState';
+import styles from '../InspectorPanel.module.css';
+import { useToast } from '../Toast';
+
 function formatSize(size: number) {
   if (!size) return '0 B';
-  if (size > 1024 * 1024) return `${(size / 1024 / 1024).toFixed(1)} MB`;
-  if (size > 1024) return `${(size / 1024).toFixed(1)} KB`;
-  return `${size} B`;
+  if (size > 1024 * 1024) return `${(size / 1024 / 1024).toFixed(1)} MB`;
+  if (size > 1024) return `${(size / 1024).toFixed(1)} KB`;
+  return `${size} B`;
 }
 
 function displayFileName(name: string) {
@@ -29,10 +37,12 @@ function formatUpdated(value: string | undefined) {
 }
 
 export default function FilesInspector() {
-  const { state, dispatch } = useAppState();
-  const { showToast } = useToast();
-  const [openingPath, setOpeningPath] = useState<string | null>(null);
-  const [loadingFileId, setLoadingFileId] = useState<string | null>(null);
+  const { state, dispatch } = useAppState();
+  const { showToast } = useToast();
+  const [openingPath, setOpeningPath] = useState<string | null>(null);
+  const [loadingFileId, setLoadingFileId] = useState<string | null>(null);
+  const [conflictFileId, setConflictFileId] = useState<string | null>(null);
+  const requestGeneration = useRef(0);
   const activeFile =
     state.workspaceFiles.find((file) => file.id === state.activeEditorFileId) ?? null;
   const activeFileName = activeFile ? displayFileName(activeFile.name) : '';
@@ -54,73 +64,82 @@ export default function FilesInspector() {
     ) : state.editorSaveStatus === 'saved' ? (
       <CheckCircle2 size={13} aria-hidden="true" strokeWidth={2.3} />
     ) : null;
-
-  const fileTypes = useMemo(
-    () => ['all', ...Array.from(new Set(state.workspaceFiles.map((file) => file.ext).filter(Boolean)))],
-    [state.workspaceFiles],
-  );
-
-  const visibleFiles = state.workspaceFiles.filter((file) => {
-    const query = state.fileSearch.trim().toLowerCase();
-    const matchesQuery =
-      !query ||
-      file.name.toLowerCase().includes(query) ||
-      file.path.toLowerCase().includes(query);
-    const matchesType = state.fileTypeFilter === 'all' || file.ext === state.fileTypeFilter;
-    return matchesQuery && matchesType;
-  });
-
-  async function openWorkspacePath(path: string | null, reveal = false) {
-    if (!path) return;
-    setOpeningPath(path);
-    try {
-      await api.openWorkspacePath(path, reveal);
-      showToast(reveal ? 'File revealed in workspace.' : 'Workspace folder opened.', 'success');
+
+  const fileTypes = useMemo(
+    () => [
+      'all',
+      ...Array.from(new Set(state.workspaceFiles.map((file) => file.ext).filter(Boolean))),
+    ],
+    [state.workspaceFiles],
+  );
+
+  const visibleFiles = state.workspaceFiles.filter((file) => {
+    const query = state.fileSearch.trim().toLowerCase();
+    const matchesQuery =
+      !query || file.name.toLowerCase().includes(query) || file.path.toLowerCase().includes(query);
+    const matchesType = state.fileTypeFilter === 'all' || file.ext === state.fileTypeFilter;
+    return matchesQuery && matchesType;
+  });
+
+  async function openWorkspacePath(path: string | null, reveal = false) {
+    if (!path) return;
+    setOpeningPath(path);
+    try {
+      await api.openWorkspacePath(path, reveal);
+      showToast(reveal ? 'File revealed in workspace.' : 'Workspace folder opened.', 'success');
     } catch (error) {
       showToast(formatApiError(error, 'Could not open workspace path.'), 'error');
-    } finally {
-      setOpeningPath(null);
-    }
-  }
-
-  async function openFile(fileId: string) {
-    const file = state.workspaceFiles.find((item) => item.id === fileId);
-    if (!file) return;
-    dispatch({ type: 'OPEN_WORKSPACE_FILE', fileId });
-    setLoadingFileId(fileId);
-    try {
-      const res = await api.readWorkspaceFile(file.path);
-      dispatch({ type: 'SET_EDITOR_CONTENT', fileId, content: res.file });
+    } finally {
+      setOpeningPath(null);
+    }
+  }
+
+  async function openFile(fileId: string) {
+    const file = state.workspaceFiles.find((item) => item.id === fileId);
+    if (!file) return;
+    dispatch({ type: 'OPEN_WORKSPACE_FILE', fileId });
+    const token = ++requestGeneration.current;
+    setConflictFileId(null);
+    setLoadingFileId(fileId);
+    try {
+      const res = await api.readWorkspaceFile(file.path);
+      if (token === requestGeneration.current)
+        dispatch({ type: 'SET_EDITOR_CONTENT', fileId, content: res.file });
     } catch (error) {
       showToast(formatApiError(error, 'Could not read file.'), 'error');
-    } finally {
-      setLoadingFileId(null);
-    }
-  }
-
-  async function saveFile() {
-    if (!activeFile) return;
-    dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saving' });
-    try {
-      const res = await api.saveWorkspaceFile(
-        activeFile.path,
-        state.editorBuffers[activeFile.id] ?? '',
-        state.editorVersions[activeFile.id],
-      );
+    } finally {
+      setLoadingFileId(null);
+    }
+  }
+
+  async function saveFile() {
+    if (!activeFile) return;
+    const target = activeFile;
+    const token = requestGeneration.current;
+    dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saving' });
+    try {
+      const res = await api.saveWorkspaceFile(
+        target.path,
+        state.editorBuffers[target.id] ?? '',
+        state.editorVersions[target.id],
+      );
+      if (token !== requestGeneration.current) return;
       dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saved' });
-      dispatch({ type: 'COMMIT_EDITOR_BUFFER', fileId: activeFile.id, version: res.file.version });
+      dispatch({ type: 'COMMIT_EDITOR_BUFFER', fileId: target.id, version: res.file.version });
       dispatch({
         type: 'SET_WORKSPACE_FILES',
         files: state.workspaceFiles.map((file) =>
-          file.id === activeFile.id
-            ? { ...file, dirty: false, updated_at: res.file.updated_at }
-            : file,
-        ),
-        root: state.outputDirectory ?? undefined,
-        fallback: state.fallback.workspaceFiles,
-      });
+          file.id === target.id ? { ...file, dirty: false, updated_at: res.file.updated_at } : file,
+        ),
+        root: state.outputDirectory ?? undefined,
+        fallback: state.fallback.workspaceFiles,
+      });
       showToast('File saved.', 'success');
-    } catch (error) {
+    } catch (error) {
+      if (token !== requestGeneration.current) return;
+      const conflict = error as { status?: number; code?: string };
+      if (conflict.status === 409 || conflict.code === 'file_conflict')
+        setConflictFileId(target.id);
       dispatch({
         type: 'SET_EDITOR_SAVE_STATUS',
         status: 'error',
@@ -129,117 +148,121 @@ export default function FilesInspector() {
       showToast(formatApiError(error, 'Save failed.'), 'error');
     }
   }
-
-  return (
-    <>
-      <section className={styles.outputCard}>
-        <div>
-          <div className={styles.sectionTitle}>Output Directory</div>
-          {state.outputDirectory ? (
-            <code className={styles.pathLine}>{state.outputDirectory}</code>
-          ) : (
-            <p className={styles.muted}>Generated files will appear here after a run writes to disk.</p>
-          )}
-        </div>
-        <button
-          className={styles.entryButton}
-          type="button"
-          disabled={!state.outputDirectory}
-          aria-label="Open output folder"
-          onClick={() => openWorkspacePath(state.outputDirectory)}
-        >
-          <FolderOpen size={14} aria-hidden="true" strokeWidth={2.3} />
-          {openingPath === state.outputDirectory ? 'Opening...' : 'Open folder'}
-        </button>
-      </section>
-
-      <section className={styles.section}>
-        <div className={styles.sectionTitle}>Generated Files</div>
-        <div className={styles.fileToolbar}>
-          <label>
-            <Search size={14} aria-hidden="true" />
-            <input
-              value={state.fileSearch}
-              onChange={(event) => dispatch({ type: 'SET_FILE_SEARCH', value: event.target.value })}
-              placeholder="Search files"
-            />
-          </label>
-          <select
-            value={state.fileTypeFilter}
-            onChange={(event) =>
-              dispatch({ type: 'SET_FILE_TYPE_FILTER', value: event.target.value })
-            }
-            aria-label="Filter by file type"
-          >
-            {fileTypes.map((type) => (
-              <option key={type} value={type}>
-                {type === 'all' ? 'All' : `.${type}`}
-              </option>
-            ))}
-          </select>
-        </div>
-
-        {visibleFiles.length === 0 ? (
-          <p className={styles.muted}>No files match this view yet.</p>
-        ) : (
-          <div className={styles.fileList}>
-            {visibleFiles.map((file) => (
+
+  return (
+    <>
+      <section className={styles.outputCard}>
+        <div>
+          <div className={styles.sectionTitle}>Output Directory</div>
+          {state.outputDirectory ? (
+            <code className={styles.pathLine}>{state.outputDirectory}</code>
+          ) : (
+            <p className={styles.muted}>
+              Generated files will appear here after a run writes to disk.
+            </p>
+          )}
+        </div>
+        <button
+          className={styles.entryButton}
+          type="button"
+          disabled={!state.outputDirectory}
+          aria-label="Open output folder"
+          onClick={() => openWorkspacePath(state.outputDirectory)}
+        >
+          <FolderOpen size={14} aria-hidden="true" strokeWidth={2.3} />
+          {openingPath === state.outputDirectory ? 'Opening...' : 'Open folder'}
+        </button>
+      </section>
+
+      <section className={styles.section}>
+        <div className={styles.sectionTitle}>Generated Files</div>
+        <div className={styles.fileToolbar}>
+          <label>
+            <Search size={14} aria-hidden="true" />
+            <input
+              value={state.fileSearch}
+              onChange={(event) => dispatch({ type: 'SET_FILE_SEARCH', value: event.target.value })}
+              placeholder="Search files"
+            />
+          </label>
+          <select
+            value={state.fileTypeFilter}
+            onChange={(event) =>
+              dispatch({ type: 'SET_FILE_TYPE_FILTER', value: event.target.value })
+            }
+            aria-label="Filter by file type"
+          >
+            {fileTypes.map((type) => (
+              <option key={type} value={type}>
+                {type === 'all' ? 'All' : `.${type}`}
+              </option>
+            ))}
+          </select>
+        </div>
+
+        {visibleFiles.length === 0 ? (
+          <p className={styles.muted}>No files match this view yet.</p>
+        ) : (
+          <div className={styles.fileList}>
+            {visibleFiles.map((file) =>
               (() => {
                 const displayName = displayFileName(file.name);
                 return (
-              <article
-                className={`${styles.fileItem} ${
-                  activeFile?.id === file.id ? styles.fileItemActive : ''
-                }`}
-                key={file.id}
-                onDoubleClick={() => openFile(file.id)}
-              >
-                <div>
-                  <strong>{displayName}</strong>
-                  <code>{file.path}</code>
-                  <small>
-                    {file.ext || 'file'} / {formatSize(file.size)} / Updated {formatUpdated(file.updated_at)}
-                  </small>
-                  {file.dirty && <span className={styles.fileDirtyBadge}>Unsaved changes</span>}
-                </div>
-                <div className={styles.fileActions}>
-                  <button
-                    className={styles.entryButton}
-                    type="button"
-                    aria-label={`Open ${displayName} in editor`}
-                    onClick={() => openFile(file.id)}
+                  <article
+                    className={`${styles.fileItem} ${
+                      activeFile?.id === file.id ? styles.fileItemActive : ''
+                    }`}
+                    key={file.id}
+                    onDoubleClick={() => openFile(file.id)}
                   >
-                    <FileText size={14} aria-hidden="true" strokeWidth={2.3} />
-                    {loadingFileId === file.id ? 'Loading...' : 'Edit'}
-                  </button>
-                  <button
-                    className={styles.entryButton}
-                    type="button"
-                    aria-label={`Reveal ${displayName} in folder`}
-                    disabled={openingPath === file.path}
-                    onClick={() => openWorkspacePath(file.path, true)}
-                  >
-                    <FolderOpen size={14} aria-hidden="true" strokeWidth={2.3} />
-                    Reveal
-                  </button>
-                </div>
-              </article>
+                    <div>
+                      <strong>{displayName}</strong>
+                      <code>{file.path}</code>
+                      <small>
+                        {file.ext || 'file'} / {formatSize(file.size)} / Updated{' '}
+                        {formatUpdated(file.updated_at)}
+                      </small>
+                      {file.dirty && <span className={styles.fileDirtyBadge}>Unsaved changes</span>}
+                    </div>
+                    <div className={styles.fileActions}>
+                      <button
+                        className={styles.entryButton}
+                        type="button"
+                        aria-label={`Open ${displayName} in editor`}
+                        onClick={() => openFile(file.id)}
+                      >
+                        <FileText size={14} aria-hidden="true" strokeWidth={2.3} />
+                        {loadingFileId === file.id ? 'Loading...' : 'Edit'}
+                      </button>
+                      <button
+                        className={styles.entryButton}
+                        type="button"
+                        aria-label={`Reveal ${displayName} in folder`}
+                        disabled={openingPath === file.path}
+                        onClick={() => openWorkspacePath(file.path, true)}
+                      >
+                        <FolderOpen size={14} aria-hidden="true" strokeWidth={2.3} />
+                        Reveal
+                      </button>
+                    </div>
+                  </article>
                 );
-              })()
-            ))}
+              })(),
+            )}
           </div>
-        )}
-      </section>
-
-      {activeFile && (
-        <section className={styles.editorPanel}>
-          <div className={styles.editorHeader}>
-            <div>
+        )}
+      </section>
+
+      {activeFile && (
+        <section className={styles.editorPanel}>
+          <div className={styles.editorHeader}>
+            <div>
               <div className={styles.sectionTitle}>Text Editor</div>
               <strong>{activeFileName}</strong>
               <code>{activeFile.path}</code>
               <small className={styles.editorMeta}>
-                Last loaded {activeFileLoaded ? formatUpdated(activeFile.updated_at) : 'from preview buffer'}
+                Last loaded{' '}
+                {activeFileLoaded ? formatUpdated(activeFile.updated_at) : 'from preview buffer'}
               </small>
             </div>
             <span
@@ -262,13 +285,13 @@ export default function FilesInspector() {
             aria-label={`Edit ${activeFileName}`}
             value={state.editorBuffers[activeFile.id] ?? ''}
             onChange={(event) =>
-              dispatch({
-                type: 'UPDATE_EDITOR_BUFFER',
-                fileId: activeFile.id,
-                content: event.target.value,
-              })
-            }
-          />
+              dispatch({
+                type: 'UPDATE_EDITOR_BUFFER',
+                fileId: activeFile.id,
+                content: event.target.value,
+              })
+            }
+          />
           <div className={styles.editorActions}>
             <div className={styles.editorButtonGroup}>
               <button
@@ -293,11 +316,33 @@ export default function FilesInspector() {
               </button>
             </div>
             <span className={state.editorError ? styles.editorErrorText : ''}>
-              {state.editorError ?? (activeFileDirty ? 'Changes stay local until saved.' : 'Ready.')}
+              {state.editorError ??
+                (activeFileDirty ? 'Changes stay local until saved.' : 'Ready.')}
             </span>
           </div>
+          {conflictFileId === activeFile.id && (
+            <div className={styles.editorActions} role="alert">
+              <span>The file changed on disk. Your local draft and version are preserved.</span>
+              <button
+                type="button"
+                className={styles.secondaryButton}
+                onClick={() => openFile(activeFile.id)}
+              >
+                Reload
+              </button>
+              <button
+                type="button"
+                className={styles.secondaryButton}
+                onClick={() =>
+                  navigator.clipboard?.writeText(state.editorBuffers[activeFile.id] ?? '')
+                }
+              >
+                Copy
+              </button>
+            </div>
+          )}
         </section>
       )}
-    </>
-  );
-}
+    </>
+  );
+}
diff --git a/webui/src/components/SettingsPage.module.css b/webui/src/components/SettingsPage.module.css
index 6e93b6af..17272c05 100644
--- a/webui/src/components/SettingsPage.module.css
+++ b/webui/src/components/SettingsPage.module.css
@@ -1,267 +1,93 @@
 .page {
-  position: relative;
-  width: 100%;
   height: 100%;
-  background: var(--page);
-  display: flex;
-  flex-direction: column;
-  animation: pageIn 280ms var(--ease-spring);
-}
-
-@keyframes pageIn {
-  from {
-    opacity: 0;
-    transform: translateY(8px);
-  }
-  to {
-    opacity: 1;
-    transform: translateY(0);
-  }
-}
-
-.header {
-  display: flex;
-  align-items: center;
-  gap: 12px;
-  padding: 16px 20px;
-  border-bottom: 1px solid var(--border);
-  background: var(--surface);
-}
-
-.backBtn {
-  display: flex;
-  align-items: center;
-  gap: 6px;
-  padding: 6px 10px;
-  border: 1px solid var(--border);
-  border-radius: 6px;
-  background: var(--surface);
-  color: var(--muted-strong);
-  font-size: 13px;
-  font-weight: 600;
-  cursor: pointer;
-  transition:
-    background 120ms ease,
-    transform 120ms ease;
+  overflow: auto;
+  box-sizing: border-box;
+  padding: 32px clamp(20px, 4vw, 56px);
 }
-
-.backBtn:hover {
-  background: var(--surface-muted);
-  transform: translateX(-2px);
+.page > header {
+  max-width: 760px;
+  margin-bottom: 24px;
 }
-
-.headerTitle {
-  font-size: 16px;
-  font-weight: 780;
-  color: var(--ink);
+.page h1,
+.page h2,
+.page p {
+  margin-top: 0;
 }
-
-.body {
-  flex: 1;
-  overflow-y: auto;
-  padding: 24px 20px;
-  max-width: 640px;
+.eyebrow {
+  color: var(--accent);
+  font-size: 12px;
+  font-weight: 700;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
 }
-
-.section {
-  margin-bottom: 28px;
+.grid {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 18px;
+  align-items: start;
 }
-
-.sectionTitle {
-  font-size: 10px;
-  font-weight: 720;
-  letter-spacing: 0.04em;
-  text-transform: uppercase;
-  color: var(--muted);
-  margin-bottom: 14px;
-  padding-bottom: 6px;
-  border-bottom: 1px solid var(--border);
+.card {
+  min-width: 0;
+  padding: 22px;
+  border: 1px solid var(--border-subtle);
+  border-radius: 14px;
+  background: var(--surface-raised);
 }
-
-.field {
-  margin-bottom: 14px;
+.card:last-child {
+  grid-column: 1 / -1;
 }
-
-.label {
-  display: flex;
-  flex-direction: column;
-  gap: 4px;
-  font-size: 12px;
+.card label {
+  display: grid;
+  gap: 7px;
+  margin: 14px 0;
   font-weight: 600;
-  color: var(--muted-strong);
 }
-
-.input,
-.select {
-  padding: 9px 11px;
-  border: 1px solid var(--border);
-  border-radius: 6px;
-  font-size: 13px;
-  background: var(--surface-strong);
-  color: var(--ink);
+.card input,
+.card select {
+  min-width: 0;
   width: 100%;
   box-sizing: border-box;
-  transition:
-    border-color 120ms ease,
-    box-shadow 120ms ease;
-}
-
-.input:focus,
-.select:focus {
-  outline: none;
-  border-color: var(--ink);
-  box-shadow: var(--ring);
-}
-
-.keyRow {
-  display: flex;
-  gap: 6px;
 }
-
-.keyRow .input {
-  flex: 1;
-}
-
-.toggleBtn {
-  flex-shrink: 0;
-  padding: 9px 12px;
-  font-size: 12px;
-  border: 1px solid var(--border);
-  border-radius: 6px;
-  background: var(--surface);
-  color: var(--muted-strong);
-  cursor: pointer;
-  transition: background 120ms ease;
-}
-
-.toggleBtn:hover {
-  background: var(--surface-muted);
-}
-
-.toggle {
+.card .check {
   display: flex;
   align-items: center;
-  gap: 10px;
-}
-
-.toggleSwitch {
-  width: 40px;
-  height: 22px;
-  background: var(--border);
-  border-radius: 11px;
-  position: relative;
-  cursor: pointer;
-  transition: background 150ms ease;
-  border: none;
-  padding: 0;
-  flex-shrink: 0;
-}
-
-.toggleSwitch[aria-checked='true'] {
-  background: var(--ink);
-}
-
-.toggleKnob {
-  width: 18px;
-  height: 18px;
-  background: #fff;
-  border-radius: 50%;
-  position: absolute;
-  top: 2px;
-  left: 2px;
-  transition: transform 150ms var(--ease-spring);
 }
-
-.toggleSwitch[aria-checked='true'] .toggleKnob {
-  transform: translateX(18px);
+.card .check input {
+  width: auto;
 }
-
-.toggleLabel {
-  font-size: 13px;
-  color: var(--ink);
-}
-
 .actions {
   display: flex;
+  flex-wrap: wrap;
   gap: 8px;
-  margin-top: 8px;
-}
-
-.btn {
-  padding: 10px 18px;
-  border: 1px solid var(--border);
-  border-radius: 6px;
-  background: var(--surface);
-  color: var(--muted-strong);
-  font-size: 13px;
-  font-weight: 600;
-  cursor: pointer;
-  transition:
-    background 120ms ease,
-    transform 120ms ease;
-}
-
-.btn:hover:not(:disabled) {
-  background: var(--surface-muted);
-  transform: translateY(-1px);
-}
-
-.btn:disabled {
-  opacity: 0.5;
-  cursor: not-allowed;
-}
-
-.btnPrimary {
-  composes: btn;
-  background: var(--ink);
-  color: #fff;
-  border-color: var(--ink);
+  margin-top: 16px;
 }
-
-.btnPrimary:hover:not(:disabled) {
-  background: #303030;
+.hint,
+.message {
+  color: var(--text-muted);
 }
-
-.ok {
-  font-size: 13px;
-  color: var(--green);
-  margin-top: 8px;
+.message {
+  margin-bottom: 16px;
 }
-
-.error {
-  font-size: 13px;
-  color: var(--ruby);
-  margin-top: 8px;
-}
-
-.hint {
-  font-size: 12px;
-  color: var(--muted);
-  line-height: 1.5;
-  margin-bottom: 14px;
-}
-
-.runtimePanel {
-  border-top: 1px solid var(--border);
-  margin-top: 8px;
-  padding-top: 18px;
-}
-
-.runtimeGrid {
+.card dl {
   display: grid;
-  grid-template-columns: minmax(80px, max-content) minmax(0, 1fr);
-  gap: 7px 12px;
-  font-size: 12px;
-  margin-bottom: 14px;
-}
-
-.runtimeGrid span {
-  color: var(--muted);
+  grid-template-columns: max-content minmax(0, 1fr);
+  gap: 8px 18px;
 }
-
-.runtimeGrid strong {
-  min-width: 0;
+.card dd {
+  margin: 0;
   overflow-wrap: anywhere;
-  color: var(--ink);
-  font-weight: 600;
+}
+.logs {
+  max-height: 240px;
+  overflow: auto;
+  padding: 12px;
+  white-space: pre-wrap;
+}
+@media (max-width: 700px) {
+  .grid {
+    grid-template-columns: 1fr;
+  }
+  .card:last-child {
+    grid-column: auto;
+  }
 }
diff --git a/webui/src/components/SettingsPage.tsx b/webui/src/components/SettingsPage.tsx
index 3ae38fb8..4db71c11 100644
--- a/webui/src/components/SettingsPage.tsx
+++ b/webui/src/components/SettingsPage.tsx
@@ -1,447 +1,224 @@
 import { useEffect, useState } from 'react';
-import { ArrowLeft } from 'lucide-react';
 import { api, formatApiError } from '../api/client';
-import { useAppState } from '../AppState';
+import type { LlmConfigFull } from '../api/types';
 import {
   exportDiagnostics,
+  getDesktopRuntimeLogs,
   getDesktopRuntimeStatus,
   isDesktopApp,
   openDiagnosticsFolder,
   restartDesktopRuntime,
   type DesktopRuntimeStatus,
 } from '../desktop';
-import { useSafePageNavigation } from '../hooks/useSafePageNavigation';
 import styles from './SettingsPage.module.css';
 
-interface ConfigState {
-  provider: string;
-  api_key_masked: string;
-  api_base_url: string;
-  default_model: string;
-  max_output_tokens: number;
-}
-
-const GENRE_OPTIONS = [
-  { value: '无偏好', label: '无偏好' },
-  { value: '修仙', label: '修仙' },
-  { value: '都市', label: '都市' },
-  { value: '悬疑', label: '悬疑' },
-  { value: '科幻', label: '科幻' },
-  { value: '言情', label: '言情' },
-  { value: '历史', label: '历史' },
-];
-
-const STYLE_OPTIONS = [
-  { value: '轻松', label: '轻松' },
-  { value: '严肃', label: '严肃' },
-  { value: '诗意', label: '诗意' },
-  { value: '简洁', label: '简洁' },
-];
-
 export default function SettingsPage() {
-  const { dispatch } = useAppState();
-  const safeNavigate = useSafePageNavigation();
-
-  // LLM config
-  const [config, setConfig] = useState<ConfigState | null>(null);
-  const [apiKey, setApiKey] = useState('');
-  const [provider, setProvider] = useState('anthropic');
+  const [config, setConfig] = useState<LlmConfigFull | null>(null);
+  const [provider, setProvider] = useState('');
   const [model, setModel] = useState('');
-  const [baseUrl, setBaseUrl] = useState('');
-  const [maxOutputTokens, setMaxOutputTokens] = useState(4096);
-  const [showKey, setShowKey] = useState(false);
-  const [saving, setSaving] = useState(false);
-  const [testing, setTesting] = useState(false);
-  const [llmStatus, setLlmStatus] = useState<'idle' | 'saved' | 'test_ok' | 'test_fail' | 'error'>(
-    'idle',
-  );
-  const [llmError, setLlmError] = useState('');
-
-  // User preferences
-  const [genre, setGenre] = useState('无偏好');
-  const [style, setStyle] = useState('轻松');
-  const [allowUsageLogs, setAllowUsageLogs] = useState(true);
-  const [prefsLoaded, setPrefsLoaded] = useState(false);
-  const [prefSaving, setPrefSaving] = useState(false);
-  const [prefError, setPrefError] = useState<string | null>(null);
-  const [prefSaved, setPrefSaved] = useState(false);
-
-  // Desktop runtime
+  const [apiKey, setApiKey] = useState('');
+  const [genre, setGenre] = useState('');
+  const [style, setStyle] = useState('');
+  const [usageLogs, setUsageLogs] = useState(false);
   const [runtime, setRuntime] = useState<DesktopRuntimeStatus | null>(null);
-  const [diagnosticMsg, setDiagnosticMsg] = useState('');
+  const [logs, setLogs] = useState<string[]>([]);
+  const [message, setMessage] = useState('');
+  const desktop = isDesktopApp();
 
   useEffect(() => {
-    api
-      .getConfig()
-      .then((data) => {
-        setConfig(data);
-        setProvider(data.provider || 'anthropic');
-        setModel(data.default_model || '');
-        setBaseUrl(data.api_base_url || '');
-        setMaxOutputTokens(data.max_output_tokens || 4096);
+    let active = true;
+    Promise.all([api.getConfig(), api.getPreferences()])
+      .then(([next, prefs]) => {
+        if (!active) return;
+        setConfig(next);
+        setProvider(next.provider);
+        setModel(next.default_model);
+        setGenre(prefs.default_genre ?? '');
+        setStyle(prefs.preferred_style ?? '');
+        setUsageLogs(prefs.allow_usage_logs ?? false);
       })
-      .catch((error) => {
-        setLlmStatus('error');
-        setLlmError(formatApiError(error, '加载设置失败'));
-      });
-  }, []);
-
-  useEffect(() => {
-    api
-      .getPreferences()
-      .then((prefs) => {
-        if (prefs.default_genre) setGenre(prefs.default_genre);
-        if (prefs.preferred_style) setStyle(prefs.preferred_style);
-        if (prefs.allow_usage_logs !== undefined) setAllowUsageLogs(prefs.allow_usage_logs);
-        setPrefsLoaded(true);
-      })
-      .catch(() => setPrefsLoaded(true));
-  }, []);
-
-  useEffect(() => {
-    if (!isDesktopApp()) return;
-    getDesktopRuntimeStatus().then(setRuntime);
-  }, []);
-
-  const handleSaveLlm = async () => {
-    setSaving(true);
-    setLlmStatus('idle');
-    setLlmError('');
+      .catch((error) => active && setMessage(formatApiError(error, 'Could not load settings.')));
+    if (desktop) getDesktopRuntimeStatus().then((value) => active && setRuntime(value));
+    return () => {
+      active = false;
+    };
+  }, [desktop]);
+
+  async function saveModel() {
+    setMessage('');
     try {
-      await api.saveConfig({
-        provider,
-        api_key: apiKey || undefined,
-        default_model: model || undefined,
-        api_base_url: baseUrl || undefined,
-        max_output_tokens: maxOutputTokens,
-      });
-      const data = await api.getConfig();
-      setConfig(data);
-      setLlmStatus('saved');
+      await api.saveConfig({ provider, default_model: model, api_key: apiKey || undefined });
       setApiKey('');
+      setMessage('Model settings saved.');
     } catch (error) {
-      setLlmStatus('error');
-      setLlmError(formatApiError(error, '保存设置失败'));
-    } finally {
-      setSaving(false);
-    }
-  };
-
-  const handleTest = async () => {
-    setTesting(true);
-    setLlmStatus('idle');
-    setLlmError('');
-    try {
-      await api.testConfig();
-      setLlmStatus('test_ok');
-    } catch (error) {
-      setLlmStatus('test_fail');
-      setLlmError(formatApiError(error, '连接测试失败'));
-    } finally {
-      setTesting(false);
+      setMessage(formatApiError(error, 'Could not save model settings.'));
     }
-  };
+  }
 
-  const handleSavePrefs = async () => {
-    setPrefSaving(true);
-    setPrefError(null);
-    setPrefSaved(false);
+  async function savePreferences() {
+    setMessage('');
     try {
       await api.savePreferences({
         default_genre: genre,
         preferred_style: style,
-        allow_usage_logs: allowUsageLogs,
+        allow_usage_logs: usageLogs,
       });
-      dispatch({
-        type: 'SET_USER_PREFERENCES',
-        prefs: { default_genre: genre, preferred_style: style },
-      });
-      setPrefSaved(true);
-      setTimeout(() => setPrefSaved(false), 2000);
+      setMessage('Preferences saved.');
     } catch (error) {
-      setPrefError(formatApiError(error, '保存偏好设置失败'));
-    } finally {
-      setPrefSaving(false);
-    }
-  };
-
-  const refreshRuntime = async () => {
-    setRuntime(await getDesktopRuntimeStatus());
-  };
-
-  const handleRestartRuntime = async () => {
-    setDiagnosticMsg('');
-    const response = await restartDesktopRuntime();
-    setRuntime(response?.status ?? null);
-    setDiagnosticMsg(response?.ok ? 'Merak 已重新打开。' : 'Merak 没能完成重新打开。');
-    if (response?.ok) {
-      api
-        .getConfig()
-        .then((data) => {
-          setConfig(data);
-          setProvider(data.provider || 'anthropic');
-          setModel(data.default_model || '');
-        })
-        .catch(() => {});
+      setMessage(formatApiError(error, 'Could not save preferences.'));
     }
-  };
-
-  const handleExportDiagnostics = async () => {
-    const response = await exportDiagnostics();
-    if (response?.ok) setDiagnosticMsg(`故障报告已导出：${response.path}`);
-    else if (response) setDiagnosticMsg(response.path);
-  };
+  }
 
   return (
-    <div className={styles.page}>
-      <div className={styles.header}>
-        <button className={styles.backBtn} onClick={() => safeNavigate('overview')}>
-          <ArrowLeft size={15} aria-hidden="true" strokeWidth={2.3} />
-          返回工作台
-        </button>
-        <h1 className={styles.headerTitle}>设置</h1>
-      </div>
-
-      <div className={styles.body}>
-        {/* LLM Configuration */}
-        <div className={styles.section}>
-          <h2 className={styles.sectionTitle}>大模型配置</h2>
-
-          {!config ? (
-            llmStatus === 'error' ? (
-              <div className={styles.error}>{llmError}</div>
-            ) : (
-              <p className={styles.hint}>正在加载配置...</p>
-            )
-          ) : (
+    <main className={styles.page}>
+      <header>
+        <p className={styles.eyebrow}>Workspace</p>
+        <h1>Settings</h1>
+        <p>Configure only capabilities supported by the connected Merak Runtime.</p>
+      </header>
+      {message && (
+        <div role="status" className={styles.message}>
+          {message}
+        </div>
+      )}
+      <div className={styles.grid}>
+        <section className={styles.card}>
+          <h2>Model provider</h2>
+          {config ? (
             <>
-              <div className={styles.field}>
-                <label className={styles.label}>
-                  服务类型
-                  <select
-                    value={provider}
-                    onChange={(e) => setProvider(e.target.value)}
-                    className={styles.select}
-                  >
-                    <option value="anthropic">Anthropic</option>
-                    <option value="openai">OpenAI</option>
-                    <option value="custom">Custom</option>
-                  </select>
-                </label>
-              </div>
-
-              <div className={styles.field}>
-                <label className={styles.label}>
-                  访问密钥
-                  <div className={styles.keyRow}>
-                    <input
-                      type={showKey ? 'text' : 'password'}
-                      value={apiKey}
-                      onChange={(e) => setApiKey(e.target.value)}
-                      placeholder={config.api_key_masked || 'sk-...'}
-                      className={styles.input}
-                    />
-                    <button
-                      type="button"
-                      onClick={() => setShowKey(!showKey)}
-                      className={styles.toggleBtn}
-                    >
-                      {showKey ? '隐藏' : '显示'}
-                    </button>
-                  </div>
-                </label>
-              </div>
-
-              <div className={styles.field}>
-                <label className={styles.label}>
-                  创作助手模型
-                  <input
-                    type="text"
-                    value={model}
-                    onChange={(e) => setModel(e.target.value)}
-                    placeholder={config.default_model || 'claude-sonnet-4-6'}
-                    className={styles.input}
-                  />
-                </label>
-              </div>
-
-              <div className={styles.field}>
-                <label className={styles.label}>
-                  高级连接地址
-                  <input
-                    type="text"
-                    value={baseUrl}
-                    onChange={(e) => setBaseUrl(e.target.value)}
-                    placeholder={config.api_base_url || 'https://api.anthropic.com'}
-                    className={styles.input}
-                  />
-                </label>
-              </div>
-
-              <div className={styles.field}>
-                <label className={styles.label}>
-                  最大输出 Token
-                  <input
-                    type="number"
-                    min={256}
-                    step={256}
-                    value={maxOutputTokens}
-                    onChange={(e) =>
-                      setMaxOutputTokens(Math.max(256, Number(e.target.value) || 256))
-                    }
-                    placeholder={String(config.max_output_tokens || 4096)}
-                    className={styles.input}
-                  />
-                </label>
-              </div>
-
+              <label>
+                Provider
+                <select value={provider} onChange={(event) => setProvider(event.target.value)}>
+                  <option value="anthropic">Anthropic</option>
+                  <option value="openai">OpenAI</option>
+                  <option value="custom">Custom</option>
+                </select>
+              </label>
+              <label>
+                Default model
+                <input value={model} onChange={(event) => setModel(event.target.value)} />
+              </label>
+              <label>
+                API key
+                <input
+                  aria-label="API key"
+                  type="password"
+                  value={apiKey}
+                  placeholder={config.api_key_masked || 'Not configured'}
+                  onChange={(event) => setApiKey(event.target.value)}
+                  autoComplete="new-password"
+                />
+              </label>
+              <p className={styles.hint}>Stored credentials are always returned masked.</p>
               <div className={styles.actions}>
-                <button onClick={handleTest} disabled={testing} className={styles.btn}>
-                  {testing ? '测试中...' : '测试连接'}
+                <button
+                  type="button"
+                  onClick={() =>
+                    api
+                      .testConfig()
+                      .then(() => setMessage('Connection succeeded.'))
+                      .catch((error) => setMessage(formatApiError(error, 'Connection failed.')))
+                  }
+                >
+                  Test connection
                 </button>
-                <button onClick={handleSaveLlm} disabled={saving} className={styles.btnPrimary}>
-                  {saving ? '保存中...' : '保存配置'}
+                <button type="button" onClick={saveModel}>
+                  Save model settings
                 </button>
               </div>
-
-              {llmStatus === 'saved' && <div className={styles.ok}>配置已保存，重启后生效。</div>}
-              {llmStatus === 'test_ok' && <div className={styles.ok}>连接测试通过。</div>}
-              {llmStatus === 'test_fail' && <div className={styles.error}>{llmError}</div>}
-              {llmStatus === 'error' && <div className={styles.error}>{llmError}</div>}
             </>
+          ) : (
+            <p>Loading model settings...</p>
           )}
-        </div>
-
-        {/* User Preferences */}
-        <div className={styles.section}>
-          <h2 className={styles.sectionTitle}>创作偏好</h2>
+        </section>
+
+        <section className={styles.card}>
+          <h2>Writing preferences</h2>
+          <label>
+            Default genre
+            <input value={genre} onChange={(event) => setGenre(event.target.value)} />
+          </label>
+          <label>
+            Preferred style
+            <input value={style} onChange={(event) => setStyle(event.target.value)} />
+          </label>
+          <label className={styles.check}>
+            <input
+              type="checkbox"
+              checked={usageLogs}
+              onChange={(event) => setUsageLogs(event.target.checked)}
+            />
+            Allow usage logs
+          </label>
+          <div className={styles.actions}>
+            <button type="button" onClick={savePreferences}>
+              Save preferences
+            </button>
+          </div>
+        </section>
 
-          {!prefsLoaded ? (
-            <p className={styles.hint}>正在加载偏好...</p>
-          ) : (
+        <section className={styles.card}>
+          <h2>Runtime and diagnostics</h2>
+          {desktop ? (
             <>
-              <div className={styles.field}>
-                <label className={styles.label}>
-                  默认题材
-                  <select
-                    value={genre}
-                    onChange={(e) => {
-                      setGenre(e.target.value);
-                      setPrefSaved(false);
-                    }}
-                    className={styles.select}
-                    disabled={prefSaving}
-                  >
-                    {GENRE_OPTIONS.map((g) => (
-                      <option key={g.value} value={g.value}>
-                        {g.label}
-                      </option>
-                    ))}
-                  </select>
-                </label>
-              </div>
-
-              <div className={styles.field}>
-                <label className={styles.label}>
-                  偏好风格
-                  <select
-                    value={style}
-                    onChange={(e) => {
-                      setStyle(e.target.value);
-                      setPrefSaved(false);
-                    }}
-                    className={styles.select}
-                    disabled={prefSaving}
-                  >
-                    {STYLE_OPTIONS.map((s) => (
-                      <option key={s.value} value={s.value}>
-                        {s.label}
-                      </option>
-                    ))}
-                  </select>
-                </label>
-              </div>
-
-              <div className={styles.field}>
-                <label className={styles.label}>使用情况日志</label>
-                <div className={styles.toggle}>
-                  <button
-                    type="button"
-                    className={styles.toggleSwitch}
-                    role="switch"
-                    aria-checked={allowUsageLogs}
-                    aria-label="切换使用情况日志"
-                    onClick={() => {
-                      setAllowUsageLogs((prev) => !prev);
-                      setPrefSaved(false);
-                    }}
-                    disabled={prefSaving}
-                  >
-                    <span className={styles.toggleKnob} />
-                  </button>
-                  <span className={styles.toggleLabel}>{allowUsageLogs ? '已开启' : '已关闭'}</span>
-                </div>
-              </div>
-
+              <dl>
+                <dt>Health</dt>
+                <dd>{runtime?.phase ?? 'Unavailable'}</dd>
+                <dt>API</dt>
+                <dd>{runtime?.apiBaseUrl ?? 'Unavailable'}</dd>
+                {runtime?.pgStatus ? (
+                  <>
+                    <dt>PostgreSQL</dt>
+                    <dd>{runtime.pgStatus}</dd>
+                  </>
+                ) : null}
+              </dl>
+              {runtime?.error && <p role="alert">{runtime.error}</p>}
               <div className={styles.actions}>
+                <button type="button" onClick={() => getDesktopRuntimeStatus().then(setRuntime)}>
+                  Refresh
+                </button>
                 <button
-                  onClick={handleSavePrefs}
-                  disabled={prefSaving}
-                  className={styles.btnPrimary}
+                  type="button"
+                  onClick={() =>
+                    restartDesktopRuntime().then((result) => setRuntime(result?.status ?? null))
+                  }
                 >
-                  {prefSaving ? '保存中...' : '保存偏好'}
-                </button>
-              </div>
-
-              {prefError && <div className={styles.error}>{prefError}</div>}
-              {prefSaved && <div className={styles.ok}>偏好已保存</div>}
-            </>
-          )}
-        </div>
-
-        {/* Desktop Runtime Status */}
-        {isDesktopApp() && (
-          <div className={styles.section}>
-            <h2 className={styles.sectionTitle}>本地桌面状态</h2>
-            <div className={styles.runtimePanel}>
-              <div className={styles.runtimeGrid}>
-                <span>当前步骤</span>
-                <strong>{runtime?.phase ?? '未知'}</strong>
-                <span>本机连接</span>
-                <strong>{runtime?.apiBaseUrl ?? '未准备好'}</strong>
-                <span>本地进程</span>
-                <strong>{runtime?.pid ? `PID ${runtime.pid}` : '未运行'}</strong>
-                <span>本地资料库</span>
-                <strong>{runtime?.pgStatus ?? '未知'}</strong>
-                <span>设置文件</span>
-                <strong>{runtime?.configPath ?? '未知'}</strong>
-                <span>报告文件</span>
-                <strong>{runtime?.logPath ?? '未知'}</strong>
-              </div>
-              {runtime?.error && <div className={styles.error}>{runtime.error}</div>}
-              <div className={styles.actions}>
-                <button type="button" onClick={refreshRuntime} className={styles.btn}>
-                  刷新
+                  Restart Runtime
                 </button>
-                <button type="button" onClick={handleRestartRuntime} className={styles.btn}>
-                  重新打开 Merak
+                <button type="button" onClick={() => openDiagnosticsFolder()}>
+                  Open diagnostics
                 </button>
                 <button
                   type="button"
-                  onClick={() => openDiagnosticsFolder()}
-                  className={styles.btn}
+                  onClick={() =>
+                    exportDiagnostics().then(
+                      (result) =>
+                        result &&
+                        setMessage(
+                          result.ok ? `Diagnostics exported to ${result.path}` : result.path,
+                        ),
+                    )
+                  }
                 >
-                  打开报告文件夹
+                  Export diagnostics
                 </button>
-                <button type="button" onClick={handleExportDiagnostics} className={styles.btn}>
-                  导出故障报告
+                <button
+                  type="button"
+                  onClick={() =>
+                    getDesktopRuntimeLogs().then((result) => setLogs(result?.lines ?? []))
+                  }
+                >
+                  View logs
                 </button>
               </div>
-              {diagnosticMsg && <div className={styles.ok}>{diagnosticMsg}</div>}
-            </div>
-          </div>
-        )}
+              {logs.length > 0 && <pre className={styles.logs}>{logs.join('\n')}</pre>}
+            </>
+          ) : (
+            <p role="status">Desktop diagnostics are unavailable in the web app.</p>
+          )}
+        </section>
       </div>
-    </div>
+    </main>
   );
 }
diff --git a/webui/src/pages/FilesPage.module.css b/webui/src/pages/FilesPage.module.css
new file mode 100644
index 00000000..c688fd67
--- /dev/null
+++ b/webui/src/pages/FilesPage.module.css
@@ -0,0 +1,76 @@
+.page {
+  display: grid;
+  grid-template-columns: minmax(220px, 320px) minmax(0, 1fr);
+  min-height: 0;
+  height: 100%;
+  overflow: hidden;
+}
+.library {
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+  min-height: 0;
+  padding: 24px;
+  border-right: 1px solid var(--border-subtle);
+  overflow: auto;
+}
+.library header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 12px;
+}
+.library h1 {
+  margin: 0;
+}
+.library input {
+  width: 100%;
+  box-sizing: border-box;
+}
+.library strong,
+.library small {
+  display: block;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.library small {
+  margin-top: 4px;
+  color: var(--text-muted);
+}
+.page textarea {
+  width: 100%;
+  min-height: 420px;
+  box-sizing: border-box;
+  resize: vertical;
+  font:
+    14px/1.65 ui-monospace,
+    Consolas,
+    monospace;
+}
+.error {
+  margin-bottom: 12px;
+  color: var(--danger);
+}
+.conflict {
+  display: flex;
+  gap: 8px;
+  margin-bottom: 12px;
+}
+@media (max-width: 1050px) {
+  .page {
+    grid-template-columns: 260px minmax(0, 1fr);
+    overflow: auto;
+  }
+}
+@media (max-width: 700px) {
+  .page {
+    grid-template-columns: 1fr;
+    height: auto;
+  }
+  .library {
+    border-right: 0;
+    border-bottom: 1px solid var(--border-subtle);
+    max-height: 280px;
+  }
+}
diff --git a/webui/src/pages/FilesPage.tsx b/webui/src/pages/FilesPage.tsx
new file mode 100644
index 00000000..2bf1fb3a
--- /dev/null
+++ b/webui/src/pages/FilesPage.tsx
@@ -0,0 +1,229 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { api, formatApiError } from '../api/client';
+import { filesApi } from '../api/files';
+import type { WorkspaceFile, WorkspaceFileContent, WorldFileLinkRecord } from '../api/types';
+import DetailPane from '../components/layout/DetailPane';
+import PageState from '../components/layout/PageState';
+import ResourceList from '../components/layout/ResourceList';
+import styles from './FilesPage.module.css';
+
+type Props = { worldId: string };
+
+function isConflict(error: unknown) {
+  const value = error as { status?: number; code?: string };
+  return value?.status === 409 || value?.code === 'file_conflict';
+}
+
+export default function FilesPage({ worldId }: Props) {
+  const [files, setFiles] = useState<WorkspaceFile[]>([]);
+  const [links, setLinks] = useState<WorldFileLinkRecord[]>([]);
+  const [selectedPath, setSelectedPath] = useState<string | null>(null);
+  const [loaded, setLoaded] = useState<WorkspaceFileContent | null>(null);
+  const [draft, setDraft] = useState('');
+  const [query, setQuery] = useState('');
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [conflict, setConflict] = useState(false);
+  const generation = useRef(0);
+
+  const loadList = () => {
+    const token = ++generation.current;
+    setLoading(true);
+    setError(null);
+    setSelectedPath(null);
+    setLoaded(null);
+    Promise.all([
+      api.listWorkspaceFiles({ world_id: worldId }),
+      filesApi.listWorldFiles(worldId).catch(() => ({ ok: false, items: [] })),
+    ])
+      .then(([result, linked]) => {
+        if (token !== generation.current) return;
+        setFiles(result.files);
+        setLinks(linked.items ?? ('files' in linked ? (linked.files ?? []) : []));
+      })
+      .catch(
+        (reason) =>
+          token === generation.current && setError(formatApiError(reason, 'Could not load files.')),
+      )
+      .finally(() => token === generation.current && setLoading(false));
+  };
+
+  useEffect(() => {
+    setSaving(false);
+    setConflict(false);
+    loadList();
+    return () => {
+      generation.current += 1;
+    };
+  }, [worldId]);
+
+  const visible = useMemo(() => {
+    const needle = query.trim().toLowerCase();
+    return files.filter(
+      (file) =>
+        !needle ||
+        file.name.toLowerCase().includes(needle) ||
+        file.path.toLowerCase().includes(needle),
+    );
+  }, [files, query]);
+
+  async function selectFile(path: string) {
+    if (saving) return;
+    const token = ++generation.current;
+    setSelectedPath(path);
+    setLoaded(null);
+    setConflict(false);
+    setError(null);
+    try {
+      const result = await api.readWorkspaceFile(path);
+      if (token !== generation.current) return;
+      setLoaded(result.file);
+      setDraft(result.file.content);
+    } catch (reason) {
+      if (token === generation.current) setError(formatApiError(reason, 'Could not read file.'));
+    }
+  }
+
+  async function saveFile() {
+    if (!loaded || saving) return;
+    const target = loaded.path;
+    const token = generation.current;
+    setSaving(true);
+    setError(null);
+    setConflict(false);
+    try {
+      const result = await api.saveWorkspaceFile(target, draft, loaded.version);
+      if (token !== generation.current || selectedPath !== target) return;
+      setLoaded({
+        ...loaded,
+        content: draft,
+        version: result.file.version,
+        updated_at: result.file.updated_at,
+      });
+    } catch (reason) {
+      if (token !== generation.current || selectedPath !== target) return;
+      setConflict(isConflict(reason));
+      setError(formatApiError(reason, 'Save failed.'));
+    } finally {
+      if (token === generation.current) setSaving(false);
+    }
+  }
+
+  const selected = files.find((file) => file.path === selectedPath) ?? null;
+  const linked = selected ? links.filter((link) => link.file_path === selected.path) : [];
+
+  if (loading) return <PageState loading loadingLabel="Loading files" />;
+  if (error && files.length === 0) return <PageState error={new Error(error)} onRetry={loadList} />;
+  if (files.length === 0)
+    return (
+      <PageState
+        isEmpty
+        emptyTitle="No workspace files yet"
+        emptyDescription="Files created by Merak will appear here."
+      />
+    );
+
+  return (
+    <div className={styles.page}>
+      <aside className={styles.library} aria-label="File library">
+        <header>
+          <h1>Files</h1>
+          <button type="button" onClick={loadList}>
+            Refresh
+          </button>
+        </header>
+        <input
+          aria-label="Search files"
+          placeholder="Search files"
+          value={query}
+          onChange={(event) => setQuery(event.target.value)}
+        />
+        <ResourceList
+          items={visible}
+          selectedId={selectedPath}
+          getId={(file) => file.path}
+          onSelect={selectFile}
+          ariaLabel="Workspace files"
+          renderItem={(file) => (
+            <>
+              <strong>{file.name}</strong>
+              <small>{file.path}</small>
+            </>
+          )}
+        />
+      </aside>
+      {selected && loaded ? (
+        <DetailPane
+          title={selected.name}
+          description={selected.path}
+          actions={
+            <>
+              <button type="button" onClick={() => api.openWorkspacePath(selected.path, true)}>
+                Reveal
+              </button>
+              <button
+                type="button"
+                disabled={saving || draft === loaded.content}
+                aria-label="Save file"
+                onClick={saveFile}
+              >
+                {saving ? 'Saving...' : 'Save'}
+              </button>
+            </>
+          }
+          inspector={
+            <>
+              <h2>World links</h2>
+              {linked.length ? (
+                linked.map((link) => (
+                  <p key={`${link.target_type}:${link.target_id}`}>
+                    {link.target_type}: {link.target_id}
+                  </p>
+                ))
+              ) : (
+                <p>No world links.</p>
+              )}
+            </>
+          }
+          inspectorLabel="File details"
+        >
+          {error && (
+            <div role="alert" className={styles.error}>
+              {error}
+            </div>
+          )}
+          {conflict && (
+            <div className={styles.conflict}>
+              <button
+                type="button"
+                aria-label="Reload file"
+                onClick={() => selectFile(selected.path)}
+              >
+                Reload
+              </button>
+              <button
+                type="button"
+                aria-label="Copy local draft"
+                onClick={() => navigator.clipboard?.writeText(draft)}
+              >
+                Copy
+              </button>
+            </div>
+          )}
+          <textarea
+            aria-label="File content"
+            value={draft}
+            onChange={(event) => setDraft(event.target.value)}
+          />
+        </DetailPane>
+      ) : (
+        <PageState
+          isEmpty
+          emptyTitle={selected ? 'Loading file content' : 'Select a file'}
+          emptyDescription="File content is loaded only when you select it."
+        />
+      )}
+    </div>
+  );
+}
diff --git a/webui/src/pages/SettingsPage.module.css b/webui/src/pages/SettingsPage.module.css
new file mode 100644
index 00000000..365690c6
--- /dev/null
+++ b/webui/src/pages/SettingsPage.module.css
@@ -0,0 +1 @@
+/* The page reuses the established settings component styles. */
diff --git a/webui/src/pages/SettingsPage.tsx b/webui/src/pages/SettingsPage.tsx
new file mode 100644
index 00000000..59807587
--- /dev/null
+++ b/webui/src/pages/SettingsPage.tsx
@@ -0,0 +1 @@
+export { default } from '../components/SettingsPage';

From c0c0e5179de3daeb58773c48365cc50d27a18c4c Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sat, 20 Jun 2026 23:50:22 +0800
Subject: [PATCH 39/49] fix(webui): harden file and settings workflows

---
 webui/src/__tests__/SettingsPanel.test.tsx    |  33 ++-
 webui/src/__tests__/components.test.tsx       |  59 ++++-
 webui/src/__tests__/pages.test.tsx            | 171 ++++++++++++++-
 webui/src/api/client.ts                       |   2 +-
 .../components/Inspector/FilesInspector.tsx   |  25 ++-
 webui/src/components/SettingsPage.tsx         |  37 +++-
 webui/src/components/layout/ResourceList.tsx  |   7 +-
 webui/src/pages/FilesPage.module.css          |   9 +
 webui/src/pages/FilesPage.tsx                 | 203 +++++++++++++-----
 9 files changed, 472 insertions(+), 74 deletions(-)

diff --git a/webui/src/__tests__/SettingsPanel.test.tsx b/webui/src/__tests__/SettingsPanel.test.tsx
index f75ca337..0ce08c2d 100644
--- a/webui/src/__tests__/SettingsPanel.test.tsx
+++ b/webui/src/__tests__/SettingsPanel.test.tsx
@@ -1,5 +1,6 @@
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
+import { api } from '../api/client';
 import { AppStateProvider } from '../AppState';
 import SettingsPanel from '../components/Sidebar/SettingsPanel';
 import { I18nProvider } from '../i18n';
@@ -22,6 +23,17 @@ vi.mock('../api/client', () => ({
       allow_usage_logs: true,
     }),
     savePreferences: vi.fn().mockResolvedValue({ ok: true }),
+    metadata: vi.fn().mockResolvedValue({
+      provider: 'openai',
+      model: 'gpt-4o',
+      models: [],
+      permission_mode: 'approval',
+      memory: { enabled: true },
+      tools: [],
+      mcp_servers: [],
+      agents: [],
+      delegation_patterns: [],
+    }),
   },
   formatApiError: vi.fn((error: unknown, fallback: string) =>
     error instanceof Error ? error.message : fallback,
@@ -78,4 +90,23 @@ describe('Settings page capabilities', () => {
     expect(screen.queryByRole('combobox', { name: /theme/i })).toBeNull();
     expect(screen.queryByRole('textbox', { name: /database/i })).toBeNull();
   });
+
+  it('renders writable API base URL, read-only permission mode, and restart-required save result', async () => {
+    vi.mocked(api.saveConfig).mockResolvedValueOnce({ ok: true, restart_required: true } as never);
+    render(
+      <AppStateProvider>
+        <SettingsPage />
+      </AppStateProvider>,
+    );
+    expect(await screen.findByLabelText('API base URL')).toHaveValue('https://api.openai.com/v1');
+    expect(await screen.findByText('approval')).toBeDefined();
+    fireEvent.change(screen.getByLabelText('API base URL'), {
+      target: { value: 'http://localhost:11434/v1' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Save model settings' }));
+    expect(await screen.findByRole('status')).toHaveTextContent(/restart required/i);
+    expect(api.saveConfig).toHaveBeenCalledWith(
+      expect.objectContaining({ api_base_url: 'http://localhost:11434/v1' }),
+    );
+  });
 });
diff --git a/webui/src/__tests__/components.test.tsx b/webui/src/__tests__/components.test.tsx
index eaddd266..a5c6205d 100644
--- a/webui/src/__tests__/components.test.tsx
+++ b/webui/src/__tests__/components.test.tsx
@@ -1,11 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { useEffect } from 'react';
-import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
 import { AppStateProvider, useAppState } from '../AppState';
-import { getDesktopRuntimeSteps } from '../DesktopBoot';
 import BrandMark from '../components/BrandMark';
 import AssistantCell from '../components/cells/AssistantCell';
 import StatusPill from '../components/cells/StatusPill';
@@ -20,6 +19,7 @@ import WorldSelector from '../components/Sidebar/WorldSelector';
 import { ToastProvider } from '../components/Toast';
 import WorldDashboard from '../components/WorldDashboard';
 import WorldOnboarding from '../components/WorldOnboarding';
+import { getDesktopRuntimeSteps } from '../DesktopBoot';
 
 function TimelineHarness() {
   const { dispatch } = useAppState();
@@ -513,7 +513,9 @@ describe('World onboarding', () => {
       target: { value: 'Snowbound border city' },
     });
     fireEvent.click(screen.getByRole('button', { name: /创建第一个|Create first/ }));
-    fireEvent.change(screen.getByLabelText(/Character Name|人物姓名|角色姓名/), { target: { value: 'Lian' } });
+    fireEvent.change(screen.getByLabelText(/Character Name|人物姓名|角色姓名/), {
+      target: { value: 'Lian' },
+    });
     fireEvent.change(screen.getByLabelText(/Identity|身份/), {
       target: { value: 'Archivist of the old passes' },
     });
@@ -904,7 +906,9 @@ describe('InspectorPanel', () => {
 
     expect(screen.getAllByText('Unsaved changes').length).toBeGreaterThan(0);
 
-    fireEvent.click(screen.getByRole('button', { name: 'Revert chapter-12 to last loaded version' }));
+    fireEvent.click(
+      screen.getByRole('button', { name: 'Revert chapter-12 to last loaded version' }),
+    );
 
     expect((editor as HTMLTextAreaElement).value).toBe('Original draft.');
     expect(screen.queryByText('Unsaved changes')).toBeNull();
@@ -940,6 +944,53 @@ describe('InspectorPanel', () => {
     expect(await screen.findAllByText('Disk is locked')).toHaveLength(2);
   });
 
+  it('blocks file switching during save and commits the returned version', async () => {
+    let resolveSave!: (value: Awaited<ReturnType<typeof api.saveWorkspaceFile>>) => void;
+    const pending = new Promise<Awaited<ReturnType<typeof api.saveWorkspaceFile>>>((resolve) => {
+      resolveSave = resolve;
+    });
+    vi.spyOn(api, 'readWorkspaceFile').mockResolvedValue({
+      ok: true,
+      file: {
+        path: '/Users/me/novel/chapter-12.md',
+        content: 'Original',
+        encoding: 'utf-8',
+        updated_at: 'old',
+        version: 'v1',
+      },
+    });
+    const save = vi
+      .spyOn(api, 'saveWorkspaceFile')
+      .mockReturnValueOnce(pending)
+      .mockResolvedValueOnce({
+        ok: true,
+        file: { path: '/Users/me/novel/chapter-12.md', updated_at: 'newer', version: 'v3' },
+      });
+    render(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Open chapter-12 in editor' }));
+    const editor = await screen.findByLabelText('Edit chapter-12');
+    fireEvent.change(editor, { target: { value: 'First save' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save chapter-12' }));
+    expect(screen.getByRole('button', { name: 'Open chapter-12 in editor' })).toBeDisabled();
+    await act(async () =>
+      resolveSave({
+        ok: true,
+        file: { path: '/Users/me/novel/chapter-12.md', updated_at: 'new', version: 'v2' },
+      }),
+    );
+    fireEvent.change(editor, { target: { value: 'Second save' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save chapter-12' }));
+    await waitFor(() =>
+      expect(save).toHaveBeenLastCalledWith('/Users/me/novel/chapter-12.md', 'Second save', 'v2'),
+    );
+  });
+
   it('renders a readable creation dashboard without mojibake copy', async () => {
     render(
       <AppStateProvider>
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index f10c5c2f..19dec636 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -2,8 +2,9 @@ import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { startTransition, Suspense, useState } from 'react';
 import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
-import { describe, expect, it, vi } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
+import { filesApi } from '../api/files';
 import { worldbuildingApi } from '../api/worldbuilding';
 import { AppStateProvider } from '../AppState';
 import CreateForeshadowingModal from '../components/Inspector/CreateForeshadowingModal';
@@ -40,6 +41,7 @@ vi.mock('../api/client', () => ({
     endScene: vi.fn(),
     readWorkspaceFile: vi.fn(),
     saveWorkspaceFile: vi.fn(),
+    openWorkspacePath: vi.fn(),
     patchChapter: vi.fn(),
     listForeshadowing: vi.fn(),
     listSecrets: vi.fn(),
@@ -55,6 +57,8 @@ vi.mock('../api/client', () => ({
   ),
 }));
 
+vi.mock('../api/files', () => ({ filesApi: { listWorldFiles: vi.fn() } }));
+
 describe('Files page', () => {
   const file = {
     id: 'draft',
@@ -67,6 +71,10 @@ describe('Files page', () => {
     dirty: false,
   };
 
+  beforeEach(() => {
+    vi.mocked(filesApi.listWorldFiles).mockResolvedValue({ ok: true, items: [] });
+  });
+
   it('loads file content only after selection', async () => {
     vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
       ok: true,
@@ -183,6 +191,167 @@ describe('Files page', () => {
 
     expect(screen.getByRole('textbox', { name: 'File content' })).toHaveValue('Newest A');
   });
+
+  it('keeps save completion live while refresh and selection are blocked', async () => {
+    const saving = deferred<Awaited<ReturnType<typeof api.saveWorkspaceFile>>>();
+    const other = { ...file, id: 'notes', path: 'notes.md', name: 'notes.md' };
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file, other],
+    });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: file.path,
+        content: 'Old',
+        encoding: 'utf-8',
+        updated_at: file.updated_at,
+        version: 'v1',
+      },
+    });
+    vi.mocked(api.saveWorkspaceFile).mockReturnValue(saving.promise);
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    fireEvent.change(await screen.findByRole('textbox', { name: 'File content' }), {
+      target: { value: 'Saved' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Save file' }));
+    expect(screen.getByRole('button', { name: 'Refresh files' })).toBeDisabled();
+    expect(screen.getByRole('option', { name: /notes/i })).toHaveAttribute('aria-disabled', 'true');
+    await act(async () =>
+      saving.resolve({ ok: true, file: { path: file.path, updated_at: 'now', version: 'v2' } }),
+    );
+    expect(screen.getByRole('button', { name: 'Refresh files' })).not.toBeDisabled();
+    expect(screen.getByRole('option', { name: /notes/i })).toHaveAttribute(
+      'aria-disabled',
+      'false',
+    );
+  });
+
+  it('shows world-link request failure as unavailable rather than empty', async () => {
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    vi.mocked(filesApi.listWorldFiles).mockRejectedValue(new Error('Links offline'));
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: file.path,
+        content: 'Old',
+        encoding: 'utf-8',
+        updated_at: file.updated_at,
+        version: 'v1',
+      },
+    });
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    expect(await screen.findByText(/World links unavailable: Links offline/)).toBeDefined();
+    expect(screen.queryByText('No world links.')).toBeNull();
+  });
+
+  it('reloads the remote version and reports clipboard failures without losing the draft', async () => {
+    const writeText = vi.fn().mockRejectedValue(new Error('Clipboard denied'));
+    Object.assign(navigator, { clipboard: { writeText } });
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    vi.mocked(api.readWorkspaceFile)
+      .mockResolvedValueOnce({
+        ok: true,
+        file: {
+          path: file.path,
+          content: 'Old',
+          encoding: 'utf-8',
+          updated_at: file.updated_at,
+          version: 'v1',
+        },
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        file: {
+          path: file.path,
+          content: 'Remote',
+          encoding: 'utf-8',
+          updated_at: 'now',
+          version: 'v2',
+        },
+      });
+    vi.mocked(api.saveWorkspaceFile).mockRejectedValue(
+      Object.assign(new Error('Changed'), { status: 409, code: 'file_conflict' }),
+    );
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    const editor = await screen.findByRole('textbox', { name: 'File content' });
+    fireEvent.change(editor, { target: { value: 'Local' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Save file' }));
+    fireEvent.click(await screen.findByRole('button', { name: 'Copy local draft' }));
+    expect(writeText).toHaveBeenCalledWith('Local');
+    expect(await screen.findByText('Clipboard denied')).toBeDefined();
+    fireEvent.click(screen.getByRole('button', { name: 'Reload file' }));
+    expect(await screen.findByRole('textbox', { name: 'File content' })).toHaveValue('Remote');
+    fireEvent.change(screen.getByRole('textbox', { name: 'File content' }), {
+      target: { value: 'Next' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Save file' }));
+    await waitFor(() =>
+      expect(api.saveWorkspaceFile).toHaveBeenLastCalledWith(file.path, 'Next', 'v2'),
+    );
+  });
+
+  it('opens the real workspace root and sends the selected type to the list API', async () => {
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    render(<FilesPage worldId="world-1" />);
+    expect(await screen.findByText('C:/story')).toBeDefined();
+    fireEvent.click(screen.getByRole('button', { name: 'Open workspace' }));
+    expect(api.openWorkspacePath).toHaveBeenCalledWith('C:/story');
+    fireEvent.change(screen.getByLabelText('File type'), { target: { value: 'markdown' } });
+    await waitFor(() =>
+      expect(api.listWorkspaceFiles).toHaveBeenLastCalledWith({
+        world_id: 'world-1',
+        type: 'markdown',
+      }),
+    );
+  });
+
+  it('ignores a pending save completion after unmount', async () => {
+    const saving = deferred<Awaited<ReturnType<typeof api.saveWorkspaceFile>>>();
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: file.path,
+        content: 'Old',
+        encoding: 'utf-8',
+        updated_at: file.updated_at,
+        version: 'v1',
+      },
+    });
+    vi.mocked(api.saveWorkspaceFile).mockReturnValue(saving.promise);
+    const view = render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    fireEvent.change(await screen.findByRole('textbox', { name: 'File content' }), {
+      target: { value: 'Local' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Save file' }));
+    view.unmount();
+    await act(async () =>
+      saving.resolve({ ok: true, file: { path: file.path, updated_at: 'now', version: 'v2' } }),
+    );
+    expect(screen.queryByRole('textbox', { name: 'File content' })).toBeNull();
+  });
 });
 
 describe('Foreshadowing page', () => {
diff --git a/webui/src/api/client.ts b/webui/src/api/client.ts
index fe98688e..20d0358f 100644
--- a/webui/src/api/client.ts
+++ b/webui/src/api/client.ts
@@ -181,7 +181,7 @@ export const api = {
     temperature?: number;
     context_memory_length?: 'short' | 'medium' | 'long';
     writer_model?: string;
-  }) => request<OkResponse>('POST', '/api/config/llm', config),
+  }) => request<OkResponse & { restart_required?: boolean }>('POST', '/api/config/llm', config),
 
   testConfig: () => request<OkResponse>('POST', '/api/config/llm/test'),
 
diff --git a/webui/src/components/Inspector/FilesInspector.tsx b/webui/src/components/Inspector/FilesInspector.tsx
index 2a69d0ce..260cac89 100644
--- a/webui/src/components/Inspector/FilesInspector.tsx
+++ b/webui/src/components/Inspector/FilesInspector.tsx
@@ -1,4 +1,4 @@
-import { useMemo, useRef, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import {
   AlertCircle,
   CheckCircle2,
@@ -43,6 +43,14 @@ export default function FilesInspector() {
   const [loadingFileId, setLoadingFileId] = useState<string | null>(null);
   const [conflictFileId, setConflictFileId] = useState<string | null>(null);
   const requestGeneration = useRef(0);
+  const mounted = useRef(true);
+  useEffect(
+    () => () => {
+      mounted.current = false;
+      requestGeneration.current += 1;
+    },
+    [],
+  );
   const activeFile =
     state.workspaceFiles.find((file) => file.id === state.activeEditorFileId) ?? null;
   const activeFileName = activeFile ? displayFileName(activeFile.name) : '';
@@ -82,7 +90,7 @@ export default function FilesInspector() {
   });
 
   async function openWorkspacePath(path: string | null, reveal = false) {
-    if (!path) return;
+    if (!path || state.editorSaveStatus === 'saving') return;
     setOpeningPath(path);
     try {
       await api.openWorkspacePath(path, reveal);
@@ -95,6 +103,7 @@ export default function FilesInspector() {
   }
 
   async function openFile(fileId: string) {
+    if (state.editorSaveStatus === 'saving') return;
     const file = state.workspaceFiles.find((item) => item.id === fileId);
     if (!file) return;
     dispatch({ type: 'OPEN_WORKSPACE_FILE', fileId });
@@ -103,7 +112,7 @@ export default function FilesInspector() {
     setLoadingFileId(fileId);
     try {
       const res = await api.readWorkspaceFile(file.path);
-      if (token === requestGeneration.current)
+      if (mounted.current && token === requestGeneration.current)
         dispatch({ type: 'SET_EDITOR_CONTENT', fileId, content: res.file });
     } catch (error) {
       showToast(formatApiError(error, 'Could not read file.'), 'error');
@@ -123,7 +132,7 @@ export default function FilesInspector() {
         state.editorBuffers[target.id] ?? '',
         state.editorVersions[target.id],
       );
-      if (token !== requestGeneration.current) return;
+      if (!mounted.current || token !== requestGeneration.current) return;
       dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saved' });
       dispatch({ type: 'COMMIT_EDITOR_BUFFER', fileId: target.id, version: res.file.version });
       dispatch({
@@ -136,7 +145,7 @@ export default function FilesInspector() {
       });
       showToast('File saved.', 'success');
     } catch (error) {
-      if (token !== requestGeneration.current) return;
+      if (!mounted.current || token !== requestGeneration.current) return;
       const conflict = error as { status?: number; code?: string };
       if (conflict.status === 409 || conflict.code === 'file_conflict')
         setConflictFileId(target.id);
@@ -165,7 +174,7 @@ export default function FilesInspector() {
         <button
           className={styles.entryButton}
           type="button"
-          disabled={!state.outputDirectory}
+          disabled={!state.outputDirectory || state.editorSaveStatus === 'saving'}
           aria-label="Open output folder"
           onClick={() => openWorkspacePath(state.outputDirectory)}
         >
@@ -186,6 +195,7 @@ export default function FilesInspector() {
             />
           </label>
           <select
+            disabled={state.editorSaveStatus === 'saving'}
             value={state.fileTypeFilter}
             onChange={(event) =>
               dispatch({ type: 'SET_FILE_TYPE_FILTER', value: event.target.value })
@@ -229,6 +239,7 @@ export default function FilesInspector() {
                         className={styles.entryButton}
                         type="button"
                         aria-label={`Open ${displayName} in editor`}
+                        disabled={state.editorSaveStatus === 'saving'}
                         onClick={() => openFile(file.id)}
                       >
                         <FileText size={14} aria-hidden="true" strokeWidth={2.3} />
@@ -238,7 +249,7 @@ export default function FilesInspector() {
                         className={styles.entryButton}
                         type="button"
                         aria-label={`Reveal ${displayName} in folder`}
-                        disabled={openingPath === file.path}
+                        disabled={openingPath === file.path || state.editorSaveStatus === 'saving'}
                         onClick={() => openWorkspacePath(file.path, true)}
                       >
                         <FolderOpen size={14} aria-hidden="true" strokeWidth={2.3} />
diff --git a/webui/src/components/SettingsPage.tsx b/webui/src/components/SettingsPage.tsx
index 4db71c11..250c9e84 100644
--- a/webui/src/components/SettingsPage.tsx
+++ b/webui/src/components/SettingsPage.tsx
@@ -1,6 +1,6 @@
 import { useEffect, useState } from 'react';
 import { api, formatApiError } from '../api/client';
-import type { LlmConfigFull } from '../api/types';
+import type { LlmConfigFull, RuntimeMetadata } from '../api/types';
 import {
   exportDiagnostics,
   getDesktopRuntimeLogs,
@@ -17,22 +17,26 @@ export default function SettingsPage() {
   const [provider, setProvider] = useState('');
   const [model, setModel] = useState('');
   const [apiKey, setApiKey] = useState('');
+  const [baseUrl, setBaseUrl] = useState('');
   const [genre, setGenre] = useState('');
   const [style, setStyle] = useState('');
   const [usageLogs, setUsageLogs] = useState(false);
   const [runtime, setRuntime] = useState<DesktopRuntimeStatus | null>(null);
+  const [metadata, setMetadata] = useState<RuntimeMetadata | null>(null);
   const [logs, setLogs] = useState<string[]>([]);
   const [message, setMessage] = useState('');
   const desktop = isDesktopApp();
 
   useEffect(() => {
     let active = true;
-    Promise.all([api.getConfig(), api.getPreferences()])
-      .then(([next, prefs]) => {
+    Promise.all([api.getConfig(), api.getPreferences(), api.metadata()])
+      .then(([next, prefs, runtimeMetadata]) => {
         if (!active) return;
         setConfig(next);
         setProvider(next.provider);
         setModel(next.default_model);
+        setBaseUrl(next.api_base_url);
+        setMetadata(runtimeMetadata);
         setGenre(prefs.default_genre ?? '');
         setStyle(prefs.preferred_style ?? '');
         setUsageLogs(prefs.allow_usage_logs ?? false);
@@ -47,9 +51,18 @@ export default function SettingsPage() {
   async function saveModel() {
     setMessage('');
     try {
-      await api.saveConfig({ provider, default_model: model, api_key: apiKey || undefined });
+      const result = await api.saveConfig({
+        provider,
+        default_model: model,
+        api_base_url: baseUrl,
+        api_key: apiKey || undefined,
+      });
       setApiKey('');
-      setMessage('Model settings saved.');
+      setMessage(
+        result.restart_required
+          ? 'Model settings saved. Runtime restart required.'
+          : 'Model settings saved.',
+      );
     } catch (error) {
       setMessage(formatApiError(error, 'Could not save model settings.'));
     }
@@ -98,6 +111,14 @@ export default function SettingsPage() {
                 Default model
                 <input value={model} onChange={(event) => setModel(event.target.value)} />
               </label>
+              <label>
+                API base URL
+                <input
+                  aria-label="API base URL"
+                  value={baseUrl}
+                  onChange={(event) => setBaseUrl(event.target.value)}
+                />
+              </label>
               <label>
                 API key
                 <input
@@ -166,6 +187,12 @@ export default function SettingsPage() {
                 <dd>{runtime?.phase ?? 'Unavailable'}</dd>
                 <dt>API</dt>
                 <dd>{runtime?.apiBaseUrl ?? 'Unavailable'}</dd>
+                {metadata ? (
+                  <>
+                    <dt>Permission mode</dt>
+                    <dd>{metadata.permission_mode}</dd>
+                  </>
+                ) : null}
                 {runtime?.pgStatus ? (
                   <>
                     <dt>PostgreSQL</dt>
diff --git a/webui/src/components/layout/ResourceList.tsx b/webui/src/components/layout/ResourceList.tsx
index be2a2c18..41949195 100644
--- a/webui/src/components/layout/ResourceList.tsx
+++ b/webui/src/components/layout/ResourceList.tsx
@@ -9,6 +9,7 @@ export type ResourceListProps<T> = {
   onSelect: (id: string) => void;
   ariaLabel?: string;
   className?: string;
+  disabled?: boolean;
 };
 
 export default function ResourceList<T>({
@@ -19,6 +20,7 @@ export default function ResourceList<T>({
   onSelect,
   ariaLabel = 'Resources',
   className,
+  disabled = false,
 }: ResourceListProps<T>) {
   const listId = useId();
   const listRef = useRef<HTMLDivElement>(null);
@@ -32,7 +34,7 @@ export default function ResourceList<T>({
   }, [selectedIndex]);
 
   const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
-    if (items.length === 0) return;
+    if (items.length === 0 || disabled) return;
 
     let nextIndex: number | null = null;
 
@@ -65,6 +67,7 @@ export default function ResourceList<T>({
       aria-label={ariaLabel}
       aria-activedescendant={selectedIndex >= 0 ? `${listId}-option-${selectedIndex}` : undefined}
       tabIndex={0}
+      aria-disabled={disabled}
       onKeyDown={handleKeyDown}
     >
       {items.map((item, index) => {
@@ -80,7 +83,9 @@ export default function ResourceList<T>({
             key={id}
             role="option"
             aria-selected={selected}
+            aria-disabled={disabled}
             onClick={() => {
+              if (disabled) return;
               listRef.current?.focus();
               onSelect(id);
             }}
diff --git a/webui/src/pages/FilesPage.module.css b/webui/src/pages/FilesPage.module.css
index c688fd67..63015afd 100644
--- a/webui/src/pages/FilesPage.module.css
+++ b/webui/src/pages/FilesPage.module.css
@@ -27,6 +27,15 @@
   width: 100%;
   box-sizing: border-box;
 }
+.root {
+  display: grid;
+  gap: 8px;
+  min-width: 0;
+}
+.root code {
+  overflow-wrap: anywhere;
+  color: var(--text-muted);
+}
 .library strong,
 .library small {
   display: block;
diff --git a/webui/src/pages/FilesPage.tsx b/webui/src/pages/FilesPage.tsx
index 2bf1fb3a..de51f4fe 100644
--- a/webui/src/pages/FilesPage.tsx
+++ b/webui/src/pages/FilesPage.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { api, formatApiError } from '../api/client';
 import { filesApi } from '../api/files';
 import type { WorkspaceFile, WorkspaceFileContent, WorldFileLinkRecord } from '../api/types';
@@ -8,111 +8,177 @@ import ResourceList from '../components/layout/ResourceList';
 import styles from './FilesPage.module.css';
 
 type Props = { worldId: string };
+type FileType = 'all' | 'markdown' | 'text' | 'data';
+type LinksState = {
+  status: 'loading' | 'ready' | 'error';
+  items: WorldFileLinkRecord[];
+  error?: string;
+};
 
 function isConflict(error: unknown) {
   const value = error as { status?: number; code?: string };
   return value?.status === 409 || value?.code === 'file_conflict';
 }
 
+function matchesType(file: WorkspaceFile, type: FileType) {
+  if (type === 'all') return true;
+  const ext = file.ext.toLowerCase();
+  if (type === 'markdown') return ['md', 'markdown'].includes(ext);
+  if (type === 'text') return ['txt', 'text'].includes(ext);
+  return ['json', 'yaml', 'yml', 'csv', 'tsv'].includes(ext);
+}
+
 export default function FilesPage({ worldId }: Props) {
   const [files, setFiles] = useState<WorkspaceFile[]>([]);
-  const [links, setLinks] = useState<WorldFileLinkRecord[]>([]);
+  const [root, setRoot] = useState('');
+  const [links, setLinks] = useState<LinksState>({ status: 'loading', items: [] });
   const [selectedPath, setSelectedPath] = useState<string | null>(null);
   const [loaded, setLoaded] = useState<WorkspaceFileContent | null>(null);
   const [draft, setDraft] = useState('');
   const [query, setQuery] = useState('');
+  const [type, setType] = useState<FileType>('all');
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
+  const [clipboardError, setClipboardError] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
   const [conflict, setConflict] = useState(false);
-  const generation = useRef(0);
+  const lifecycle = useRef(0);
+  const listToken = useRef(0);
+  const readToken = useRef(0);
+  const saveToken = useRef(0);
+  const savingRef = useRef(false);
 
-  const loadList = () => {
-    const token = ++generation.current;
+  const loadList = useCallback(async () => {
+    if (savingRef.current) return;
+    const life = lifecycle.current;
+    const token = ++listToken.current;
     setLoading(true);
     setError(null);
-    setSelectedPath(null);
-    setLoaded(null);
-    Promise.all([
-      api.listWorkspaceFiles({ world_id: worldId }),
-      filesApi.listWorldFiles(worldId).catch(() => ({ ok: false, items: [] })),
-    ])
-      .then(([result, linked]) => {
-        if (token !== generation.current) return;
-        setFiles(result.files);
-        setLinks(linked.items ?? ('files' in linked ? (linked.files ?? []) : []));
-      })
-      .catch(
-        (reason) =>
-          token === generation.current && setError(formatApiError(reason, 'Could not load files.')),
-      )
-      .finally(() => token === generation.current && setLoading(false));
-  };
+    try {
+      const result = await api.listWorkspaceFiles({
+        world_id: worldId,
+        type: type === 'all' ? undefined : type,
+      });
+      if (life !== lifecycle.current || token !== listToken.current) return;
+      setFiles(result.files);
+      setRoot(result.root);
+      setSelectedPath(null);
+      setLoaded(null);
+    } catch (reason) {
+      if (life === lifecycle.current && token === listToken.current)
+        setError(formatApiError(reason, 'Could not load files.'));
+    } finally {
+      if (life === lifecycle.current && token === listToken.current) setLoading(false);
+    }
+  }, [type, worldId]);
 
   useEffect(() => {
+    lifecycle.current += 1;
+    savingRef.current = false;
     setSaving(false);
     setConflict(false);
+    setLinks({ status: 'loading', items: [] });
     loadList();
+    const life = lifecycle.current;
+    filesApi
+      .listWorldFiles(worldId)
+      .then((result) => {
+        if (life === lifecycle.current)
+          setLinks({ status: 'ready', items: result.items ?? result.files ?? [] });
+      })
+      .catch((reason) => {
+        if (life === lifecycle.current)
+          setLinks({
+            status: 'error',
+            items: [],
+            error: formatApiError(reason, 'Request failed.'),
+          });
+      });
     return () => {
-      generation.current += 1;
+      lifecycle.current += 1;
+      savingRef.current = false;
     };
-  }, [worldId]);
+  }, [loadList, worldId]);
 
   const visible = useMemo(() => {
     const needle = query.trim().toLowerCase();
     return files.filter(
       (file) =>
-        !needle ||
-        file.name.toLowerCase().includes(needle) ||
-        file.path.toLowerCase().includes(needle),
+        matchesType(file, type) &&
+        (!needle ||
+          file.name.toLowerCase().includes(needle) ||
+          file.path.toLowerCase().includes(needle)),
     );
-  }, [files, query]);
+  }, [files, query, type]);
 
   async function selectFile(path: string) {
-    if (saving) return;
-    const token = ++generation.current;
+    if (savingRef.current) return;
+    const life = lifecycle.current;
+    const token = ++readToken.current;
     setSelectedPath(path);
     setLoaded(null);
     setConflict(false);
     setError(null);
+    setClipboardError(null);
     try {
       const result = await api.readWorkspaceFile(path);
-      if (token !== generation.current) return;
+      if (life !== lifecycle.current || token !== readToken.current) return;
       setLoaded(result.file);
       setDraft(result.file.content);
     } catch (reason) {
-      if (token === generation.current) setError(formatApiError(reason, 'Could not read file.'));
+      if (life === lifecycle.current && token === readToken.current)
+        setError(formatApiError(reason, 'Could not read file.'));
     }
   }
 
   async function saveFile() {
-    if (!loaded || saving) return;
+    if (!loaded || savingRef.current) return;
+    const life = lifecycle.current;
+    const token = ++saveToken.current;
     const target = loaded.path;
-    const token = generation.current;
+    const content = draft;
+    const version = loaded.version;
+    savingRef.current = true;
     setSaving(true);
     setError(null);
     setConflict(false);
     try {
-      const result = await api.saveWorkspaceFile(target, draft, loaded.version);
-      if (token !== generation.current || selectedPath !== target) return;
-      setLoaded({
-        ...loaded,
-        content: draft,
-        version: result.file.version,
-        updated_at: result.file.updated_at,
-      });
+      const result = await api.saveWorkspaceFile(target, content, version);
+      if (life !== lifecycle.current || token !== saveToken.current) return;
+      setLoaded((current) =>
+        current?.path === target
+          ? {
+              ...current,
+              content,
+              version: result.file.version,
+              updated_at: result.file.updated_at,
+            }
+          : current,
+      );
     } catch (reason) {
-      if (token !== generation.current || selectedPath !== target) return;
+      if (life !== lifecycle.current || token !== saveToken.current) return;
       setConflict(isConflict(reason));
       setError(formatApiError(reason, 'Save failed.'));
     } finally {
-      if (token === generation.current) setSaving(false);
+      if (life === lifecycle.current && token === saveToken.current) {
+        savingRef.current = false;
+        setSaving(false);
+      }
     }
   }
 
-  const selected = files.find((file) => file.path === selectedPath) ?? null;
-  const linked = selected ? links.filter((link) => link.file_path === selected.path) : [];
+  async function copyDraft() {
+    setClipboardError(null);
+    try {
+      if (!navigator.clipboard?.writeText) throw new Error('Clipboard is unavailable.');
+      await navigator.clipboard.writeText(draft);
+    } catch (reason) {
+      setClipboardError(formatApiError(reason, 'Could not copy the local draft.'));
+    }
+  }
 
+  const selected = files.find((file) => file.path === selectedPath) ?? null;
+  const linked = selected ? links.items.filter((link) => link.file_path === selected.path) : [];
   if (loading) return <PageState loading loadingLabel="Loading files" />;
   if (error && files.length === 0) return <PageState error={new Error(error)} onRetry={loadList} />;
   if (files.length === 0)
@@ -129,17 +195,37 @@ export default function FilesPage({ worldId }: Props) {
       <aside className={styles.library} aria-label="File library">
         <header>
           <h1>Files</h1>
-          <button type="button" onClick={loadList}>
+          <button type="button" aria-label="Refresh files" disabled={saving} onClick={loadList}>
             Refresh
           </button>
         </header>
+        {root && (
+          <div className={styles.root}>
+            <code>{root}</code>
+            <button type="button" onClick={() => api.openWorkspacePath(root)}>
+              Open workspace
+            </button>
+          </div>
+        )}
         <input
           aria-label="Search files"
           placeholder="Search files"
           value={query}
           onChange={(event) => setQuery(event.target.value)}
         />
+        <select
+          aria-label="File type"
+          value={type}
+          disabled={saving}
+          onChange={(event) => setType(event.target.value as FileType)}
+        >
+          <option value="all">All</option>
+          <option value="markdown">Markdown</option>
+          <option value="text">Text</option>
+          <option value="data">Data</option>
+        </select>
         <ResourceList
+          disabled={saving}
           items={visible}
           selectedId={selectedPath}
           getId={(file) => file.path}
@@ -159,7 +245,11 @@ export default function FilesPage({ worldId }: Props) {
           description={selected.path}
           actions={
             <>
-              <button type="button" onClick={() => api.openWorkspacePath(selected.path, true)}>
+              <button
+                type="button"
+                disabled={saving}
+                onClick={() => api.openWorkspacePath(selected.path, true)}
+              >
                 Reveal
               </button>
               <button
@@ -175,7 +265,11 @@ export default function FilesPage({ worldId }: Props) {
           inspector={
             <>
               <h2>World links</h2>
-              {linked.length ? (
+              {links.status === 'loading' ? (
+                <p>Loading world links...</p>
+              ) : links.status === 'error' ? (
+                <p>World links unavailable: {links.error}</p>
+              ) : linked.length ? (
                 linked.map((link) => (
                   <p key={`${link.target_type}:${link.target_id}`}>
                     {link.target_type}: {link.target_id}
@@ -193,6 +287,11 @@ export default function FilesPage({ worldId }: Props) {
               {error}
             </div>
           )}
+          {clipboardError && (
+            <div role="alert" className={styles.error}>
+              {clipboardError}
+            </div>
+          )}
           {conflict && (
             <div className={styles.conflict}>
               <button
@@ -202,11 +301,7 @@ export default function FilesPage({ worldId }: Props) {
               >
                 Reload
               </button>
-              <button
-                type="button"
-                aria-label="Copy local draft"
-                onClick={() => navigator.clipboard?.writeText(draft)}
-              >
+              <button type="button" aria-label="Copy local draft" onClick={copyDraft}>
                 Copy
               </button>
             </div>

From 467a228cc164204708c3fb49d6abca7770ddd125 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sun, 21 Jun 2026 00:08:06 +0800
Subject: [PATCH 40/49] fix(webui): preserve partial file and settings states

---
 webui/src/__tests__/SettingsPanel.test.tsx    | 46 ++++++++-
 webui/src/__tests__/components.test.tsx       | 97 ++++++++++++++++---
 webui/src/__tests__/pages.test.tsx            | 29 ++++++
 .../components/Inspector/FilesInspector.tsx   | 46 ++++++---
 webui/src/components/SettingsPage.tsx         | 91 ++++++++++++++---
 webui/src/pages/FilesPage.tsx                 | 41 ++++----
 6 files changed, 283 insertions(+), 67 deletions(-)

diff --git a/webui/src/__tests__/SettingsPanel.test.tsx b/webui/src/__tests__/SettingsPanel.test.tsx
index 0ce08c2d..cb95dcfb 100644
--- a/webui/src/__tests__/SettingsPanel.test.tsx
+++ b/webui/src/__tests__/SettingsPanel.test.tsx
@@ -1,8 +1,9 @@
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, within } from '@testing-library/react';
 import { describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
 import { AppStateProvider } from '../AppState';
 import SettingsPanel from '../components/Sidebar/SettingsPanel';
+import { getDesktopRuntimeStatus } from '../desktop';
 import { I18nProvider } from '../i18n';
 import SettingsPage from '../pages/SettingsPage';
 
@@ -19,7 +20,7 @@ vi.mock('../api/client', () => ({
     testConfig: vi.fn().mockResolvedValue({ ok: true }),
     getPreferences: vi.fn().mockResolvedValue({
       default_genre: 'No preference',
-      preferred_style: 'concise',
+      preferred_style: '简洁',
       allow_usage_logs: true,
     }),
     savePreferences: vi.fn().mockResolvedValue({ ok: true }),
@@ -109,4 +110,45 @@ describe('Settings page capabilities', () => {
       expect.objectContaining({ api_base_url: 'http://localhost:11434/v1' }),
     );
   });
+
+  it('keeps model settings editable when preferences fail and reports a local warning', async () => {
+    vi.mocked(api.getPreferences).mockRejectedValueOnce(new Error('Preferences offline'));
+    render(
+      <AppStateProvider>
+        <SettingsPage />
+      </AppStateProvider>,
+    );
+    expect(await screen.findByLabelText('API key')).toBeDefined();
+    expect(screen.getByText(/Preferences unavailable: Preferences offline/)).toBeDefined();
+    expect(screen.queryByText('Loading model settings...')).toBeNull();
+  });
+
+  it('restricts preferred style to the backend enum', async () => {
+    render(
+      <AppStateProvider>
+        <SettingsPage />
+      </AppStateProvider>,
+    );
+    const style = await screen.findByLabelText('Preferred style');
+    expect(style.tagName).toBe('SELECT');
+    expect(
+      within(style)
+        .getAllByRole('option')
+        .map((option) => option.textContent),
+    ).toEqual(['轻松', '严肃', '诗意', '简洁']);
+  });
+
+  it('keeps config available when runtime sources fail', async () => {
+    vi.mocked(api.metadata).mockRejectedValueOnce(new Error('Metadata offline'));
+    vi.mocked(getDesktopRuntimeStatus).mockRejectedValueOnce(new Error('Desktop offline'));
+    render(
+      <AppStateProvider>
+        <SettingsPage />
+      </AppStateProvider>,
+    );
+    expect(await screen.findByLabelText('API key')).toBeDefined();
+    expect(screen.getByText(/Runtime metadata unavailable: Metadata offline/)).toBeDefined();
+    expect(screen.getByText(/Desktop Runtime unavailable: Desktop offline/)).toBeDefined();
+    expect(screen.getAllByText('Unavailable').length).toBeGreaterThan(0);
+  });
 });
diff --git a/webui/src/__tests__/components.test.tsx b/webui/src/__tests__/components.test.tsx
index a5c6205d..ca28caf0 100644
--- a/webui/src/__tests__/components.test.tsx
+++ b/webui/src/__tests__/components.test.tsx
@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { useEffect } from 'react';
+import { StrictMode, useEffect } from 'react';
 import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
@@ -785,7 +785,7 @@ function AgentsPanelHarness() {
   return <InspectorPanel open={true} onClose={() => {}} />;
 }
 
-function FilesHarness() {
+function FilesHarness({ twoFiles = false }: { twoFiles?: boolean }) {
   const { dispatch } = useAppState();
 
   useEffect(() => {
@@ -803,7 +803,13 @@ function FilesHarness() {
       },
     });
     dispatch({ type: 'SET_INSPECTOR_TAB', tab: 'files' });
-  }, [dispatch]);
+    if (twoFiles) {
+      dispatch({
+        type: 'REGISTER_GENERATED_FILE',
+        file: { id: 'file_2', title: 'notes', path: '/Users/me/novel/notes.txt', updatedAt: 2 },
+      });
+    }
+  }, [dispatch, twoFiles]);
 
   return <InspectorPanel open={true} onClose={() => {}} />;
 }
@@ -928,11 +934,13 @@ describe('InspectorPanel', () => {
     vi.spyOn(api, 'saveWorkspaceFile').mockRejectedValue(new Error('Disk is locked'));
 
     render(
-      <AppStateProvider>
-        <ToastProvider>
-          <FilesHarness />
-        </ToastProvider>
-      </AppStateProvider>,
+      <StrictMode>
+        <AppStateProvider>
+          <ToastProvider>
+            <FilesHarness />
+          </ToastProvider>
+        </AppStateProvider>
+      </StrictMode>,
     );
 
     fireEvent.click(await screen.findByRole('button', { name: 'Open chapter-12 in editor' }));
@@ -967,11 +975,13 @@ describe('InspectorPanel', () => {
         file: { path: '/Users/me/novel/chapter-12.md', updated_at: 'newer', version: 'v3' },
       });
     render(
-      <AppStateProvider>
-        <ToastProvider>
-          <FilesHarness />
-        </ToastProvider>
-      </AppStateProvider>,
+      <StrictMode>
+        <AppStateProvider>
+          <ToastProvider>
+            <FilesHarness />
+          </ToastProvider>
+        </AppStateProvider>
+      </StrictMode>,
     );
     fireEvent.click(await screen.findByRole('button', { name: 'Open chapter-12 in editor' }));
     const editor = await screen.findByLabelText('Edit chapter-12');
@@ -991,6 +1001,67 @@ describe('InspectorPanel', () => {
     );
   });
 
+  it('ignores stale read errors and finally callbacks across A-B-A overlap', async () => {
+    let rejectA!: (reason: Error) => void;
+    let resolveB!: (value: Awaited<ReturnType<typeof api.readWorkspaceFile>>) => void;
+    let resolveNewestA!: (value: Awaited<ReturnType<typeof api.readWorkspaceFile>>) => void;
+    const oldA = new Promise<never>((_, reject) => {
+      rejectA = reject;
+    });
+    const oldB = new Promise<Awaited<ReturnType<typeof api.readWorkspaceFile>>>((resolve) => {
+      resolveB = resolve;
+    });
+    const newestA = new Promise<Awaited<ReturnType<typeof api.readWorkspaceFile>>>((resolve) => {
+      resolveNewestA = resolve;
+    });
+    vi.spyOn(api, 'readWorkspaceFile')
+      .mockReturnValueOnce(oldA)
+      .mockReturnValueOnce(oldB)
+      .mockReturnValueOnce(newestA);
+    render(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness twoFiles />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    const a = await screen.findByRole('button', { name: 'Open chapter-12 in editor' });
+    const b = screen.getByRole('button', { name: 'Open notes in editor' });
+    fireEvent.click(a);
+    fireEvent.click(b);
+    fireEvent.click(a);
+    await act(async () => rejectA(new Error('Old A failed')));
+    await act(async () =>
+      resolveB({
+        ok: true,
+        file: {
+          path: '/Users/me/novel/notes.txt',
+          content: 'Old B',
+          encoding: 'utf-8',
+          updated_at: 'old',
+          version: 'b1',
+        },
+      }),
+    );
+    expect(screen.queryByText('Old A failed')).toBeNull();
+    expect(screen.getByRole('button', { name: 'Open chapter-12 in editor' })).toHaveTextContent(
+      'Loading...',
+    );
+    await act(async () =>
+      resolveNewestA({
+        ok: true,
+        file: {
+          path: '/Users/me/novel/chapter-12.md',
+          content: 'Newest A',
+          encoding: 'utf-8',
+          updated_at: 'new',
+          version: 'a2',
+        },
+      }),
+    );
+    expect(await screen.findByLabelText('Edit chapter-12')).toHaveValue('Newest A');
+  });
+
   it('renders a readable creation dashboard without mojibake copy', async () => {
     render(
       <AppStateProvider>
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 19dec636..706696fb 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -352,6 +352,35 @@ describe('Files page', () => {
     );
     expect(screen.queryByRole('textbox', { name: 'File content' })).toBeNull();
   });
+
+  it('keeps the file shell and workspace actions visible for a real empty list', async () => {
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/empty-story',
+      files: [],
+    });
+    render(<FilesPage worldId="world-1" />);
+    expect(await screen.findByRole('heading', { name: 'Files' })).toBeDefined();
+    expect(screen.getByText('C:/empty-story')).toBeDefined();
+    expect(screen.getByRole('button', { name: 'Refresh files' })).toBeDefined();
+    expect(screen.getByLabelText('File type')).toBeDefined();
+    expect(screen.getByLabelText('Search files')).toBeDefined();
+    expect(screen.getByText('No files in this view.')).toBeDefined();
+  });
+
+  it('keeps filters available when a type has no matching files', async () => {
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    render(<FilesPage worldId="world-1" />);
+    await screen.findByRole('option', { name: /draft/i });
+    fireEvent.change(screen.getByLabelText('File type'), { target: { value: 'text' } });
+    expect(await screen.findByText('No files in this view.')).toBeDefined();
+    fireEvent.change(screen.getByLabelText('File type'), { target: { value: 'all' } });
+    expect(await screen.findByRole('option', { name: /draft/i })).toBeDefined();
+  });
 });
 
 describe('Foreshadowing page', () => {
diff --git a/webui/src/components/Inspector/FilesInspector.tsx b/webui/src/components/Inspector/FilesInspector.tsx
index 260cac89..bc55eb78 100644
--- a/webui/src/components/Inspector/FilesInspector.tsx
+++ b/webui/src/components/Inspector/FilesInspector.tsx
@@ -42,15 +42,18 @@ export default function FilesInspector() {
   const [openingPath, setOpeningPath] = useState<string | null>(null);
   const [loadingFileId, setLoadingFileId] = useState<string | null>(null);
   const [conflictFileId, setConflictFileId] = useState<string | null>(null);
-  const requestGeneration = useRef(0);
+  const lifecycleGeneration = useRef(0);
+  const readGeneration = useRef(0);
   const mounted = useRef(true);
-  useEffect(
-    () => () => {
+  useEffect(() => {
+    mounted.current = true;
+    const lifecycle = ++lifecycleGeneration.current;
+    return () => {
       mounted.current = false;
-      requestGeneration.current += 1;
-    },
-    [],
-  );
+      if (lifecycleGeneration.current === lifecycle) lifecycleGeneration.current += 1;
+      readGeneration.current += 1;
+    };
+  }, []);
   const activeFile =
     state.workspaceFiles.find((file) => file.id === state.activeEditorFileId) ?? null;
   const activeFileName = activeFile ? displayFileName(activeFile.name) : '';
@@ -107,24 +110,39 @@ export default function FilesInspector() {
     const file = state.workspaceFiles.find((item) => item.id === fileId);
     if (!file) return;
     dispatch({ type: 'OPEN_WORKSPACE_FILE', fileId });
-    const token = ++requestGeneration.current;
+    const lifecycle = lifecycleGeneration.current;
+    const token = ++readGeneration.current;
     setConflictFileId(null);
     setLoadingFileId(fileId);
     try {
       const res = await api.readWorkspaceFile(file.path);
-      if (mounted.current && token === requestGeneration.current)
+      if (
+        mounted.current &&
+        lifecycle === lifecycleGeneration.current &&
+        token === readGeneration.current
+      )
         dispatch({ type: 'SET_EDITOR_CONTENT', fileId, content: res.file });
     } catch (error) {
-      showToast(formatApiError(error, 'Could not read file.'), 'error');
+      if (
+        mounted.current &&
+        lifecycle === lifecycleGeneration.current &&
+        token === readGeneration.current
+      )
+        showToast(formatApiError(error, 'Could not read file.'), 'error');
     } finally {
-      setLoadingFileId(null);
+      if (
+        mounted.current &&
+        lifecycle === lifecycleGeneration.current &&
+        token === readGeneration.current
+      )
+        setLoadingFileId(null);
     }
   }
 
   async function saveFile() {
     if (!activeFile) return;
     const target = activeFile;
-    const token = requestGeneration.current;
+    const lifecycle = lifecycleGeneration.current;
     dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saving' });
     try {
       const res = await api.saveWorkspaceFile(
@@ -132,7 +150,7 @@ export default function FilesInspector() {
         state.editorBuffers[target.id] ?? '',
         state.editorVersions[target.id],
       );
-      if (!mounted.current || token !== requestGeneration.current) return;
+      if (!mounted.current || lifecycle !== lifecycleGeneration.current) return;
       dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saved' });
       dispatch({ type: 'COMMIT_EDITOR_BUFFER', fileId: target.id, version: res.file.version });
       dispatch({
@@ -145,7 +163,7 @@ export default function FilesInspector() {
       });
       showToast('File saved.', 'success');
     } catch (error) {
-      if (!mounted.current || token !== requestGeneration.current) return;
+      if (!mounted.current || lifecycle !== lifecycleGeneration.current) return;
       const conflict = error as { status?: number; code?: string };
       if (conflict.status === 409 || conflict.code === 'file_conflict')
         setConflictFileId(target.id);
diff --git a/webui/src/components/SettingsPage.tsx b/webui/src/components/SettingsPage.tsx
index 250c9e84..2344fbef 100644
--- a/webui/src/components/SettingsPage.tsx
+++ b/webui/src/components/SettingsPage.tsx
@@ -12,6 +12,8 @@ import {
 } from '../desktop';
 import styles from './SettingsPage.module.css';
 
+const STYLE_OPTIONS = ['轻松', '严肃', '诗意', '简洁'] as const;
+
 export default function SettingsPage() {
   const [config, setConfig] = useState<LlmConfigFull | null>(null);
   const [provider, setProvider] = useState('');
@@ -25,24 +27,48 @@ export default function SettingsPage() {
   const [metadata, setMetadata] = useState<RuntimeMetadata | null>(null);
   const [logs, setLogs] = useState<string[]>([]);
   const [message, setMessage] = useState('');
+  const [configError, setConfigError] = useState('');
+  const [preferencesError, setPreferencesError] = useState('');
+  const [metadataError, setMetadataError] = useState('');
+  const [desktopError, setDesktopError] = useState('');
   const desktop = isDesktopApp();
 
   useEffect(() => {
     let active = true;
-    Promise.all([api.getConfig(), api.getPreferences(), api.metadata()])
-      .then(([next, prefs, runtimeMetadata]) => {
+    Promise.allSettled([api.getConfig(), api.getPreferences(), api.metadata()]).then(
+      ([configResult, preferencesResult, metadataResult]) => {
         if (!active) return;
-        setConfig(next);
-        setProvider(next.provider);
-        setModel(next.default_model);
-        setBaseUrl(next.api_base_url);
-        setMetadata(runtimeMetadata);
-        setGenre(prefs.default_genre ?? '');
-        setStyle(prefs.preferred_style ?? '');
-        setUsageLogs(prefs.allow_usage_logs ?? false);
-      })
-      .catch((error) => active && setMessage(formatApiError(error, 'Could not load settings.')));
-    if (desktop) getDesktopRuntimeStatus().then((value) => active && setRuntime(value));
+        if (configResult.status === 'fulfilled') {
+          const next = configResult.value;
+          setConfig(next);
+          setProvider(next.provider);
+          setModel(next.default_model);
+          setBaseUrl(next.api_base_url);
+        } else
+          setConfigError(formatApiError(configResult.reason, 'Could not load model settings.'));
+        if (preferencesResult.status === 'fulfilled') {
+          const prefs = preferencesResult.value;
+          setGenre(prefs.default_genre ?? '');
+          setStyle(prefs.preferred_style ?? '');
+          setUsageLogs(prefs.allow_usage_logs ?? false);
+        } else setPreferencesError(formatApiError(preferencesResult.reason, 'Request failed.'));
+        if (metadataResult.status === 'fulfilled') setMetadata(metadataResult.value);
+        else
+          setMetadataError(
+            `Runtime metadata unavailable: ${formatApiError(metadataResult.reason, 'Request failed.')}`,
+          );
+      },
+    );
+    if (desktop)
+      getDesktopRuntimeStatus()
+        .then((value) => active && setRuntime(value))
+        .catch(
+          (error) =>
+            active &&
+            setDesktopError(
+              `Desktop Runtime unavailable: ${formatApiError(error, 'Request failed.')}`,
+            ),
+        );
     return () => {
       active = false;
     };
@@ -70,6 +96,10 @@ export default function SettingsPage() {
 
   async function savePreferences() {
     setMessage('');
+    if (!STYLE_OPTIONS.includes(style as (typeof STYLE_OPTIONS)[number])) {
+      setMessage('Choose a supported preferred style before saving.');
+      return;
+    }
     try {
       await api.savePreferences({
         default_genre: genre,
@@ -94,6 +124,21 @@ export default function SettingsPage() {
           {message}
         </div>
       )}
+      {preferencesError && (
+        <div role="alert" className={styles.message}>
+          Preferences unavailable: {preferencesError}
+        </div>
+      )}
+      {metadataError && (
+        <div role="alert" className={styles.message}>
+          {metadataError}
+        </div>
+      )}
+      {desktopError && (
+        <div role="alert" className={styles.message}>
+          {desktopError}
+        </div>
+      )}
       <div className={styles.grid}>
         <section className={styles.card}>
           <h2>Model provider</h2>
@@ -148,6 +193,8 @@ export default function SettingsPage() {
                 </button>
               </div>
             </>
+          ) : configError ? (
+            <p role="alert">{configError}</p>
           ) : (
             <p>Loading model settings...</p>
           )}
@@ -161,7 +208,17 @@ export default function SettingsPage() {
           </label>
           <label>
             Preferred style
-            <input value={style} onChange={(event) => setStyle(event.target.value)} />
+            <select
+              aria-label="Preferred style"
+              value={style}
+              onChange={(event) => setStyle(event.target.value)}
+            >
+              {STYLE_OPTIONS.map((option) => (
+                <option key={option} value={option}>
+                  {option}
+                </option>
+              ))}
+            </select>
           </label>
           <label className={styles.check}>
             <input
@@ -172,7 +229,11 @@ export default function SettingsPage() {
             Allow usage logs
           </label>
           <div className={styles.actions}>
-            <button type="button" onClick={savePreferences}>
+            <button
+              type="button"
+              disabled={!STYLE_OPTIONS.includes(style as (typeof STYLE_OPTIONS)[number])}
+              onClick={savePreferences}
+            >
               Save preferences
             </button>
           </div>
diff --git a/webui/src/pages/FilesPage.tsx b/webui/src/pages/FilesPage.tsx
index de51f4fe..1d016d92 100644
--- a/webui/src/pages/FilesPage.tsx
+++ b/webui/src/pages/FilesPage.tsx
@@ -181,15 +181,6 @@ export default function FilesPage({ worldId }: Props) {
   const linked = selected ? links.items.filter((link) => link.file_path === selected.path) : [];
   if (loading) return <PageState loading loadingLabel="Loading files" />;
   if (error && files.length === 0) return <PageState error={new Error(error)} onRetry={loadList} />;
-  if (files.length === 0)
-    return (
-      <PageState
-        isEmpty
-        emptyTitle="No workspace files yet"
-        emptyDescription="Files created by Merak will appear here."
-      />
-    );
-
   return (
     <div className={styles.page}>
       <aside className={styles.library} aria-label="File library">
@@ -224,20 +215,24 @@ export default function FilesPage({ worldId }: Props) {
           <option value="text">Text</option>
           <option value="data">Data</option>
         </select>
-        <ResourceList
-          disabled={saving}
-          items={visible}
-          selectedId={selectedPath}
-          getId={(file) => file.path}
-          onSelect={selectFile}
-          ariaLabel="Workspace files"
-          renderItem={(file) => (
-            <>
-              <strong>{file.name}</strong>
-              <small>{file.path}</small>
-            </>
-          )}
-        />
+        {visible.length ? (
+          <ResourceList
+            disabled={saving}
+            items={visible}
+            selectedId={selectedPath}
+            getId={(file) => file.path}
+            onSelect={selectFile}
+            ariaLabel="Workspace files"
+            renderItem={(file) => (
+              <>
+                <strong>{file.name}</strong>
+                <small>{file.path}</small>
+              </>
+            )}
+          />
+        ) : (
+          <p>No files in this view.</p>
+        )}
       </aside>
       {selected && loaded ? (
         <DetailPane

From 824117f66b1d6f1aec41d83721c2c21226442a7a Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sun, 21 Jun 2026 12:15:23 +0800
Subject: [PATCH 41/49] fix(webui): isolate file inspector across worlds

---
 webui/src/__tests__/components.test.tsx       | 158 +++++++++++++++++-
 .../components/Inspector/FilesInspector.tsx   |  62 ++++++-
 2 files changed, 214 insertions(+), 6 deletions(-)

diff --git a/webui/src/__tests__/components.test.tsx b/webui/src/__tests__/components.test.tsx
index ca28caf0..5a78df97 100644
--- a/webui/src/__tests__/components.test.tsx
+++ b/webui/src/__tests__/components.test.tsx
@@ -785,10 +785,17 @@ function AgentsPanelHarness() {
   return <InspectorPanel open={true} onClose={() => {}} />;
 }
 
-function FilesHarness({ twoFiles = false }: { twoFiles?: boolean }) {
+function FilesHarness({
+  twoFiles = false,
+  worldId = 'world-a',
+}: {
+  twoFiles?: boolean;
+  worldId?: string;
+}) {
   const { dispatch } = useAppState();
 
   useEffect(() => {
+    dispatch({ type: 'SET_WORLD', worldId });
     dispatch({
       type: 'SET_OUTPUT_DIRECTORY',
       path: '/Users/me/novel',
@@ -809,7 +816,7 @@ function FilesHarness({ twoFiles = false }: { twoFiles?: boolean }) {
         file: { id: 'file_2', title: 'notes', path: '/Users/me/novel/notes.txt', updatedAt: 2 },
       });
     }
-  }, [dispatch, twoFiles]);
+  }, [dispatch, twoFiles, worldId]);
 
   return <InspectorPanel open={true} onClose={() => {}} />;
 }
@@ -1062,6 +1069,153 @@ describe('InspectorPanel', () => {
     expect(await screen.findByLabelText('Edit chapter-12')).toHaveValue('Newest A');
   });
 
+  it('invalidates a pending read and resets loading when the world changes', async () => {
+    let rejectRead!: (reason: Error) => void;
+    vi.spyOn(api, 'readWorkspaceFile').mockReturnValue(
+      new Promise<never>((_, reject) => {
+        rejectRead = reject;
+      }),
+    );
+    const view = render(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness worldId="world-a" />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Open chapter-12 in editor' }));
+    expect(screen.getByRole('button', { name: 'Open chapter-12 in editor' })).toHaveTextContent(
+      'Loading...',
+    );
+    view.rerender(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness worldId="world-b" />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    await waitFor(() =>
+      expect(screen.getByRole('button', { name: 'Open chapter-12 in editor' })).toHaveTextContent(
+        'Edit',
+      ),
+    );
+    await act(async () => rejectRead(new Error('Old world read failed')));
+    expect(screen.queryByText('Old world read failed')).toBeNull();
+  });
+
+  it('invalidates save completion after a world switch', async () => {
+    let resolveSave!: (value: Awaited<ReturnType<typeof api.saveWorkspaceFile>>) => void;
+    vi.spyOn(api, 'readWorkspaceFile').mockResolvedValue({
+      ok: true,
+      file: {
+        path: '/Users/me/novel/chapter-12.md',
+        content: 'Old',
+        encoding: 'utf-8',
+        updated_at: 'old',
+        version: 'v1',
+      },
+    });
+    vi.spyOn(api, 'saveWorkspaceFile').mockReturnValue(
+      new Promise((resolve) => {
+        resolveSave = resolve;
+      }),
+    );
+    const view = render(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness worldId="world-a" />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Open chapter-12 in editor' }));
+    fireEvent.change(await screen.findByLabelText('Edit chapter-12'), {
+      target: { value: 'Local A' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Save chapter-12' }));
+    view.rerender(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness worldId="world-b" />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    await act(async () =>
+      resolveSave({
+        ok: true,
+        file: { path: '/Users/me/novel/chapter-12.md', updated_at: 'new', version: 'v2' },
+      }),
+    );
+    expect(screen.queryByText('File saved.')).toBeNull();
+    expect(screen.queryByText('Saved')).toBeNull();
+  });
+
+  it('does not let an A-B-A open completion clear the newest open operation', async () => {
+    let resolveOld!: (value: { ok: boolean; path: string }) => void;
+    let resolveNew!: (value: { ok: boolean; path: string }) => void;
+    vi.spyOn(api, 'openWorkspacePath')
+      .mockReturnValueOnce(
+        new Promise((resolve) => {
+          resolveOld = resolve;
+        }),
+      )
+      .mockReturnValueOnce(
+        new Promise((resolve) => {
+          resolveNew = resolve;
+        }),
+      );
+    const view = render(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness worldId="world-a" />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Open output folder' }));
+    view.rerender(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness worldId="world-b" />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    view.rerender(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness worldId="world-a" />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Open output folder' }));
+    await act(async () => resolveOld({ ok: true, path: '/old' }));
+    expect(screen.getByRole('button', { name: 'Open output folder' })).toHaveTextContent(
+      'Opening...',
+    );
+    await act(async () => resolveNew({ ok: true, path: '/new' }));
+    expect(screen.getByRole('button', { name: 'Open output folder' })).toHaveTextContent(
+      'Open folder',
+    );
+  });
+
+  it('ignores pending Inspector callbacks after unmount', async () => {
+    let rejectRead!: (reason: Error) => void;
+    vi.spyOn(api, 'readWorkspaceFile').mockReturnValue(
+      new Promise<never>((_, reject) => {
+        rejectRead = reject;
+      }),
+    );
+    const view = render(
+      <AppStateProvider>
+        <ToastProvider>
+          <FilesHarness />
+        </ToastProvider>
+      </AppStateProvider>,
+    );
+    fireEvent.click(await screen.findByRole('button', { name: 'Open chapter-12 in editor' }));
+    view.unmount();
+    await act(async () => rejectRead(new Error('Unmounted read')));
+    expect(screen.queryByText('Unmounted read')).toBeNull();
+  });
+
   it('renders a readable creation dashboard without mojibake copy', async () => {
     render(
       <AppStateProvider>
diff --git a/webui/src/components/Inspector/FilesInspector.tsx b/webui/src/components/Inspector/FilesInspector.tsx
index bc55eb78..33c0dcaf 100644
--- a/webui/src/components/Inspector/FilesInspector.tsx
+++ b/webui/src/components/Inspector/FilesInspector.tsx
@@ -44,16 +44,29 @@ export default function FilesInspector() {
   const [conflictFileId, setConflictFileId] = useState<string | null>(null);
   const lifecycleGeneration = useRef(0);
   const readGeneration = useRef(0);
+  const saveGeneration = useRef(0);
+  const openGeneration = useRef(0);
+  const committedWorld = useRef<string | null>(null);
   const mounted = useRef(true);
   useEffect(() => {
     mounted.current = true;
+    committedWorld.current = state.worldId;
     const lifecycle = ++lifecycleGeneration.current;
+    readGeneration.current += 1;
+    saveGeneration.current += 1;
+    openGeneration.current += 1;
+    setLoadingFileId(null);
+    setOpeningPath(null);
+    setConflictFileId(null);
+    dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'idle' });
     return () => {
       mounted.current = false;
       if (lifecycleGeneration.current === lifecycle) lifecycleGeneration.current += 1;
       readGeneration.current += 1;
+      saveGeneration.current += 1;
+      openGeneration.current += 1;
     };
-  }, []);
+  }, [dispatch, state.worldId]);
   const activeFile =
     state.workspaceFiles.find((file) => file.id === state.activeEditorFileId) ?? null;
   const activeFileName = activeFile ? displayFileName(activeFile.name) : '';
@@ -94,14 +107,37 @@ export default function FilesInspector() {
 
   async function openWorkspacePath(path: string | null, reveal = false) {
     if (!path || state.editorSaveStatus === 'saving') return;
+    const lifecycle = lifecycleGeneration.current;
+    const worldId = state.worldId;
+    const token = ++openGeneration.current;
     setOpeningPath(path);
     try {
       await api.openWorkspacePath(path, reveal);
+      if (
+        !mounted.current ||
+        lifecycle !== lifecycleGeneration.current ||
+        worldId !== committedWorld.current ||
+        token !== openGeneration.current
+      )
+        return;
       showToast(reveal ? 'File revealed in workspace.' : 'Workspace folder opened.', 'success');
     } catch (error) {
+      if (
+        !mounted.current ||
+        lifecycle !== lifecycleGeneration.current ||
+        worldId !== committedWorld.current ||
+        token !== openGeneration.current
+      )
+        return;
       showToast(formatApiError(error, 'Could not open workspace path.'), 'error');
     } finally {
-      setOpeningPath(null);
+      if (
+        mounted.current &&
+        lifecycle === lifecycleGeneration.current &&
+        worldId === committedWorld.current &&
+        token === openGeneration.current
+      )
+        setOpeningPath(null);
     }
   }
 
@@ -111,6 +147,7 @@ export default function FilesInspector() {
     if (!file) return;
     dispatch({ type: 'OPEN_WORKSPACE_FILE', fileId });
     const lifecycle = lifecycleGeneration.current;
+    const worldId = state.worldId;
     const token = ++readGeneration.current;
     setConflictFileId(null);
     setLoadingFileId(fileId);
@@ -119,6 +156,7 @@ export default function FilesInspector() {
       if (
         mounted.current &&
         lifecycle === lifecycleGeneration.current &&
+        worldId === committedWorld.current &&
         token === readGeneration.current
       )
         dispatch({ type: 'SET_EDITOR_CONTENT', fileId, content: res.file });
@@ -126,6 +164,7 @@ export default function FilesInspector() {
       if (
         mounted.current &&
         lifecycle === lifecycleGeneration.current &&
+        worldId === committedWorld.current &&
         token === readGeneration.current
       )
         showToast(formatApiError(error, 'Could not read file.'), 'error');
@@ -133,6 +172,7 @@ export default function FilesInspector() {
       if (
         mounted.current &&
         lifecycle === lifecycleGeneration.current &&
+        worldId === committedWorld.current &&
         token === readGeneration.current
       )
         setLoadingFileId(null);
@@ -143,6 +183,8 @@ export default function FilesInspector() {
     if (!activeFile) return;
     const target = activeFile;
     const lifecycle = lifecycleGeneration.current;
+    const worldId = state.worldId;
+    const token = ++saveGeneration.current;
     dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saving' });
     try {
       const res = await api.saveWorkspaceFile(
@@ -150,7 +192,13 @@ export default function FilesInspector() {
         state.editorBuffers[target.id] ?? '',
         state.editorVersions[target.id],
       );
-      if (!mounted.current || lifecycle !== lifecycleGeneration.current) return;
+      if (
+        !mounted.current ||
+        lifecycle !== lifecycleGeneration.current ||
+        worldId !== committedWorld.current ||
+        token !== saveGeneration.current
+      )
+        return;
       dispatch({ type: 'SET_EDITOR_SAVE_STATUS', status: 'saved' });
       dispatch({ type: 'COMMIT_EDITOR_BUFFER', fileId: target.id, version: res.file.version });
       dispatch({
@@ -163,7 +211,13 @@ export default function FilesInspector() {
       });
       showToast('File saved.', 'success');
     } catch (error) {
-      if (!mounted.current || lifecycle !== lifecycleGeneration.current) return;
+      if (
+        !mounted.current ||
+        lifecycle !== lifecycleGeneration.current ||
+        worldId !== committedWorld.current ||
+        token !== saveGeneration.current
+      )
+        return;
       const conflict = error as { status?: number; code?: string };
       if (conflict.status === 409 || conflict.code === 'file_conflict')
         setConflictFileId(target.id);

From 9d70b2cd6b49ee8fbc012c7e671d9403c065633a Mon Sep 17 00:00:00 2001
From: ULookup <chbulookup@outlook.com>
Date: Sun, 21 Jun 2026 04:15:31 +0000
Subject: [PATCH 42/49] fix(loop): remove AgentLoop retry layer, rely on
 provider internal retry

Provider layer (openai_provider.cpp, anthropic_provider.cpp) already handles
all transient failures with 3 attempts and exponential backoff. The AgentLoop
retry was redundant and introduced two bugs:

1. Duplicate stream chunks: the failed attempt already emitted partial text
   via the on_chunk callback (flushed to UI). The retry re-emitted the same
   content from the start.
2. Response.text corruption: on final failure, response.text contained debris
   from the last failed attempt.
---
 libs/loop/src/agent_loop.cpp | 71 ++++--------------------------------
 1 file changed, 8 insertions(+), 63 deletions(-)

diff --git a/libs/loop/src/agent_loop.cpp b/libs/loop/src/agent_loop.cpp
index e9454cc9..4ce3a6f3 100644
--- a/libs/loop/src/agent_loop.cpp
+++ b/libs/loop/src/agent_loop.cpp
@@ -134,10 +134,9 @@ AgentResponse AgentLoop::run_loop(RunControl& control) {
 
         std::vector<ToolCall> accumulated_tool_calls;
 
-        // Snapshot: if LLM streaming fails mid-flight, chunks already emitted
-        // via the callback would be duplicated by the retry. Save and restore
-        // the pre-attempt text length so only the successful response is kept.
-        const auto text_len_before_attempt = response.text.size();
+        // Provider layer handles all retry internally (exponential backoff).
+        // AgentLoop only catches to handle context-window recovery.
+        AgentResponse llm_response;
 
         auto llm_future = llm_->chat(req,
             [&](StreamChunk chunk) {
@@ -150,65 +149,11 @@ AgentResponse AgentLoop::run_loop(RunControl& control) {
                 }
             }, control.cancellation_token());
 
-        AgentResponse llm_response;
-        int attempt = 0;
-        while (true) {
-            try {
-                llm_response = llm_future.get();
-                break;
-            } catch (const std::exception& e) {
-                // Restore text to pre-attempt state so retry doesn't duplicate
-                // partial chunks already emitted by the failed future.
-                response.text.resize(text_len_before_attempt);
-                attempt++;
-                int http_status = 0;
-                std::string msg = e.what();
-                auto pos = msg.rfind("(HTTP ");
-                if (pos != std::string::npos) {
-                    http_status = std::stoi(msg.substr(pos + 6));
-                }
-                auto error_class = turn_ingestor_.classify_error(http_status, msg);
-
-                if (attempt > config_.max_retries) {
-                    spdlog::error("Loop: max retries ({}) exceeded", config_.max_retries);
-                    throw;
-                }
-
-                switch (error_class) {
-                case LlmErrorClass::Auth:
-                case LlmErrorClass::Cancelled:
-                    throw; // never retry these
-                case LlmErrorClass::ContextWindow:
-                    spdlog::warn("Loop: context window error, triggering compaction");
-                    maybe_compact(control);
-                    break;
-                case LlmErrorClass::RateLimit:
-                case LlmErrorClass::StreamTransport:
-                case LlmErrorClass::StreamIdle:
-                case LlmErrorClass::Unknown:
-                default: {
-                    int delay_ms = std::min(2000 * (1 << (attempt - 1)), 30000);
-                    spdlog::warn("Loop: retry {}/{} after {}ms ({}: {})",
-                        attempt, config_.max_retries, delay_ms,
-                        (int)error_class, e.what());
-                    std::this_thread::sleep_for(std::chrono::milliseconds(delay_ms));
-                    break;
-                }
-                case LlmErrorClass::None:
-                    break;
-                }
-
-                llm_future = llm_->chat(req,
-                    [&](StreamChunk chunk) {
-                        auto token = control.cancellation_token();
-                        if (token && token->should_stop()) return;
-                        if (chunk.is_final) return;
-                        if (!chunk.is_tool_call) {
-                            control.emit_text_delta(chunk.text);
-                            response.text += chunk.text;
-                        }
-                    }, control.cancellation_token());
-            }
+        try {
+            llm_response = llm_future.get();
+        } catch (const std::exception& e) {
+            spdlog::error("Loop: LLM request failed after provider retries: {}", e.what());
+            throw;
         }
         response.total_input_tokens += llm_response.total_input_tokens;
         response.total_output_tokens += llm_response.total_output_tokens;

From 94cbbff462c7c37181d003534609dad0b5e74270 Mon Sep 17 00:00:00 2001
From: ULookup <chbulookup@outlook.com>
Date: Sun, 21 Jun 2026 04:19:25 +0000
Subject: [PATCH 43/49] fix(loop): keep context-window error recovery in
 AgentLoop retry logic

Provider layer handles transient errors (5xx, 429, curl). AgentLoop
catches one class of error the provider cannot handle internally:
context-window errors. When the LLM returns a 400-level error about
context length, AgentLoop triggers compaction (maybe_compact()) and
retries once.

Removed: general retry loop that re-invokes chat() on all error types
Kept: context-window specific recovery with single retry
---
 libs/loop/src/agent_loop.cpp | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/libs/loop/src/agent_loop.cpp b/libs/loop/src/agent_loop.cpp
index 4ce3a6f3..e7d1ae2d 100644
--- a/libs/loop/src/agent_loop.cpp
+++ b/libs/loop/src/agent_loop.cpp
@@ -135,7 +135,7 @@ AgentResponse AgentLoop::run_loop(RunControl& control) {
         std::vector<ToolCall> accumulated_tool_calls;
 
         // Provider layer handles all retry internally (exponential backoff).
-        // AgentLoop only catches to handle context-window recovery.
+        // AgentLoop only retries context-window errors: trim history and retry once.
         AgentResponse llm_response;
 
         auto llm_future = llm_->chat(req,
@@ -152,8 +152,33 @@ AgentResponse AgentLoop::run_loop(RunControl& control) {
         try {
             llm_response = llm_future.get();
         } catch (const std::exception& e) {
-            spdlog::error("Loop: LLM request failed after provider retries: {}", e.what());
-            throw;
+            // Context-window errors need trim + retry; all others are final.
+            int http_status = 0;
+            std::string msg = e.what();
+            auto pos = msg.rfind("(HTTP ");
+            if (pos != std::string::npos) {
+                http_status = std::stoi(msg.substr(pos + 6));
+            }
+            auto error_class = turn_ingestor_.classify_error(http_status, msg);
+
+            if (error_class == LlmErrorClass::ContextWindow) {
+                spdlog::warn("Loop: context window error, triggering compaction and retry");
+                maybe_compact(control);
+                llm_future = llm_->chat(req,
+                    [&](StreamChunk chunk) {
+                        auto token = control.cancellation_token();
+                        if (token && token->should_stop()) return;
+                        if (chunk.is_final) return;
+                        if (!chunk.is_tool_call) {
+                            control.emit_text_delta(chunk.text);
+                            response.text += chunk.text;
+                        }
+                    }, control.cancellation_token());
+                llm_response = llm_future.get();
+            } else {
+                spdlog::error("Loop: LLM request failed after provider retries: {}", e.what());
+                throw;
+            }
         }
         response.total_input_tokens += llm_response.total_input_tokens;
         response.total_output_tokens += llm_response.total_output_tokens;

From f09ec47289fedec1f8f61a8c01dd6a1134cd3200 Mon Sep 17 00:00:00 2001
From: ULookup <chbulookup@outlook.com>
Date: Sun, 21 Jun 2026 04:26:30 +0000
Subject: [PATCH 44/49] fix(loop): remove all AgentLoop retry logic, delegate
 entirely to provider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Provider layer handles all transient errors (5xx, 429, curl errors)
with 3 attempts and exponential backoff. AgentLoop now only catches
for logging before propagating the exception upstream.

Context-window retry was also removed: all callers (fork_skill_tool,
worldbuilding_tools) already catch exceptions from sub_loop.run()
and return errors as tool results. The heuristic-based compact+retry
was unreliable — if token counting underestimates, compaction won't
help either.
---
 libs/loop/src/agent_loop.cpp | 36 ++++--------------------------------
 1 file changed, 4 insertions(+), 32 deletions(-)

diff --git a/libs/loop/src/agent_loop.cpp b/libs/loop/src/agent_loop.cpp
index e7d1ae2d..4904eef0 100644
--- a/libs/loop/src/agent_loop.cpp
+++ b/libs/loop/src/agent_loop.cpp
@@ -134,10 +134,6 @@ AgentResponse AgentLoop::run_loop(RunControl& control) {
 
         std::vector<ToolCall> accumulated_tool_calls;
 
-        // Provider layer handles all retry internally (exponential backoff).
-        // AgentLoop only retries context-window errors: trim history and retry once.
-        AgentResponse llm_response;
-
         auto llm_future = llm_->chat(req,
             [&](StreamChunk chunk) {
                 auto token = control.cancellation_token();
@@ -149,36 +145,12 @@ AgentResponse AgentLoop::run_loop(RunControl& control) {
                 }
             }, control.cancellation_token());
 
+        AgentResponse llm_response;
         try {
             llm_response = llm_future.get();
-        } catch (const std::exception& e) {
-            // Context-window errors need trim + retry; all others are final.
-            int http_status = 0;
-            std::string msg = e.what();
-            auto pos = msg.rfind("(HTTP ");
-            if (pos != std::string::npos) {
-                http_status = std::stoi(msg.substr(pos + 6));
-            }
-            auto error_class = turn_ingestor_.classify_error(http_status, msg);
-
-            if (error_class == LlmErrorClass::ContextWindow) {
-                spdlog::warn("Loop: context window error, triggering compaction and retry");
-                maybe_compact(control);
-                llm_future = llm_->chat(req,
-                    [&](StreamChunk chunk) {
-                        auto token = control.cancellation_token();
-                        if (token && token->should_stop()) return;
-                        if (chunk.is_final) return;
-                        if (!chunk.is_tool_call) {
-                            control.emit_text_delta(chunk.text);
-                            response.text += chunk.text;
-                        }
-                    }, control.cancellation_token());
-                llm_response = llm_future.get();
-            } else {
-                spdlog::error("Loop: LLM request failed after provider retries: {}", e.what());
-                throw;
-            }
+        } catch (const std::exception&) {
+            spdlog::error("Loop: LLM request failed after provider retries");
+            throw;
         }
         response.total_input_tokens += llm_response.total_input_tokens;
         response.total_output_tokens += llm_response.total_output_tokens;

From dd864ad46bd95499153ad2bf762d1879ac478939 Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sun, 21 Jun 2026 12:33:11 +0800
Subject: [PATCH 45/49] fix(webui): surface file and desktop failures

---
 webui/src/__tests__/SettingsPanel.test.tsx |  57 ++++++-
 webui/src/__tests__/pages.test.tsx         |  61 +++++++
 webui/src/api/types.ts                     |   1 +
 webui/src/components/SettingsPage.tsx      | 176 +++++++++++++--------
 webui/src/desktop.ts                       |  19 ++-
 webui/src/pages/FilesPage.tsx              |  79 ++++++---
 6 files changed, 303 insertions(+), 90 deletions(-)

diff --git a/webui/src/__tests__/SettingsPanel.test.tsx b/webui/src/__tests__/SettingsPanel.test.tsx
index cb95dcfb..27b9152a 100644
--- a/webui/src/__tests__/SettingsPanel.test.tsx
+++ b/webui/src/__tests__/SettingsPanel.test.tsx
@@ -3,7 +3,13 @@ import { describe, expect, it, vi } from 'vitest';
 import { api } from '../api/client';
 import { AppStateProvider } from '../AppState';
 import SettingsPanel from '../components/Sidebar/SettingsPanel';
-import { getDesktopRuntimeStatus } from '../desktop';
+import {
+  exportDiagnostics,
+  getDesktopRuntimeLogs,
+  getDesktopRuntimeStatus,
+  openDiagnosticsFolder,
+  restartDesktopRuntime,
+} from '../desktop';
 import { I18nProvider } from '../i18n';
 import SettingsPage from '../pages/SettingsPage';
 
@@ -55,7 +61,8 @@ vi.mock('../desktop', () => ({
     error: null,
   }),
   isDesktopApp: vi.fn(() => true),
-  openDiagnosticsFolder: vi.fn(),
+  getDesktopRuntimeLogs: vi.fn().mockResolvedValue({ lines: ['runtime ready'] }),
+  openDiagnosticsFolder: vi.fn().mockResolvedValue({ ok: true, path: 'C:/Users/me/logs' }),
   restartDesktopRuntime: vi.fn().mockResolvedValue({ ok: true, status: null }),
 }));
 
@@ -120,9 +127,55 @@ describe('Settings page capabilities', () => {
     );
     expect(await screen.findByLabelText('API key')).toBeDefined();
     expect(screen.getByText(/Preferences unavailable: Preferences offline/)).toBeDefined();
+    expect(screen.queryByLabelText('Default genre')).toBeNull();
+    expect(screen.queryByLabelText('Preferred style')).toBeNull();
+    expect(screen.queryByRole('button', { name: 'Save preferences' })).toBeNull();
+    expect(api.savePreferences).not.toHaveBeenCalled();
     expect(screen.queryByText('Loading model settings...')).toBeNull();
   });
 
+  it('reports null and unsuccessful desktop action results without discarding runtime state', async () => {
+    vi.mocked(getDesktopRuntimeStatus)
+      .mockResolvedValueOnce({
+        phase: 'ready',
+        apiBaseUrl: 'http://127.0.0.1:3888',
+        port: 3888,
+        pid: 1234,
+        version: '0.1.0',
+        pgStatus: 'ready',
+        configPath: 'C:/config.json',
+        logPath: 'C:/desktop.log',
+        error: null,
+      })
+      .mockResolvedValueOnce(null);
+    vi.mocked(restartDesktopRuntime).mockResolvedValueOnce(null);
+    vi.mocked(openDiagnosticsFolder).mockResolvedValueOnce({
+      ok: false,
+      path: '',
+      error: 'Folder unavailable',
+    } as never);
+    vi.mocked(exportDiagnostics).mockResolvedValueOnce(null);
+    vi.mocked(getDesktopRuntimeLogs).mockResolvedValueOnce(null);
+    render(
+      <AppStateProvider>
+        <SettingsPage />
+      </AppStateProvider>,
+    );
+    expect(await screen.findByText('http://127.0.0.1:3888')).toBeDefined();
+
+    for (const [name, failure] of [
+      ['Refresh', /refresh runtime status failed/i],
+      ['Restart Runtime', /restart runtime failed/i],
+      ['Open diagnostics', /Folder unavailable/i],
+      ['Export diagnostics', /export diagnostics failed/i],
+      ['View logs', /view logs failed/i],
+    ] as const) {
+      fireEvent.click(screen.getByRole('button', { name }));
+      expect(await screen.findByRole('alert')).toHaveTextContent(failure);
+      expect(screen.getByText('http://127.0.0.1:3888')).toBeDefined();
+    }
+  });
+
   it('restricts preferred style to the backend enum', async () => {
     render(
       <AppStateProvider>
diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 706696fb..a05292ab 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -252,6 +252,20 @@ describe('Files page', () => {
     expect(screen.queryByText('No world links.')).toBeNull();
   });
 
+  it('shows content loading failures separately from list and link state', async () => {
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    vi.mocked(api.readWorkspaceFile).mockRejectedValue(new Error('Content offline'));
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    expect(await screen.findByRole('alert')).toHaveTextContent('Content offline');
+    expect(screen.getByRole('option', { name: /draft/i })).toBeDefined();
+    expect(screen.queryByText(/World links unavailable/)).toBeNull();
+  });
+
   it('reloads the remote version and reports clipboard failures without losing the draft', async () => {
     const writeText = vi.fn().mockRejectedValue(new Error('Clipboard denied'));
     Object.assign(navigator, { clipboard: { writeText } });
@@ -322,6 +336,53 @@ describe('Files page', () => {
     );
   });
 
+  it('keeps the previous list and shows a local warning when refresh or type loading fails', async () => {
+    vi.mocked(api.listWorkspaceFiles)
+      .mockResolvedValueOnce({ ok: true, root: 'C:/story', files: [file] })
+      .mockRejectedValueOnce(new Error('Refresh offline'))
+      .mockRejectedValueOnce(new Error('Type offline'));
+    render(<FilesPage worldId="world-1" />);
+    expect(await screen.findByRole('option', { name: /draft/i })).toBeDefined();
+
+    fireEvent.click(screen.getByRole('button', { name: 'Refresh files' }));
+    expect(await screen.findByRole('alert')).toHaveTextContent('Refresh offline');
+    expect(screen.getByRole('option', { name: /draft/i })).toBeDefined();
+
+    fireEvent.change(screen.getByLabelText('File type'), { target: { value: 'markdown' } });
+    expect(await screen.findByRole('alert')).toHaveTextContent('Type offline');
+    expect(screen.getByRole('option', { name: /draft/i })).toBeDefined();
+  });
+
+  it('locks root Open while pending and reports null, false, and rejected results', async () => {
+    const opening = deferred<Awaited<ReturnType<typeof api.openWorkspacePath>>>();
+    vi.mocked(api.openWorkspacePath).mockClear();
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [],
+    });
+    vi.mocked(api.openWorkspacePath)
+      .mockReturnValueOnce(opening.promise)
+      .mockResolvedValueOnce(null as never)
+      .mockResolvedValueOnce({ ok: false, path: '', error: 'Open denied' } as never)
+      .mockRejectedValueOnce(new Error('Open crashed'));
+    render(<FilesPage worldId="world-1" />);
+    const open = await screen.findByRole('button', { name: 'Open workspace' });
+
+    fireEvent.click(open);
+    expect(open).toBeDisabled();
+    fireEvent.click(open);
+    expect(api.openWorkspacePath).toHaveBeenCalledTimes(1);
+    await act(async () => opening.resolve({ ok: true, path: 'C:/story' } as never));
+    expect(open).not.toBeDisabled();
+
+    for (const failure of [/open workspace failed/i, /Open denied/i, /Open crashed/i]) {
+      fireEvent.click(open);
+      expect(await screen.findByRole('alert')).toHaveTextContent(failure);
+      expect(open).not.toBeDisabled();
+    }
+  });
+
   it('ignores a pending save completion after unmount', async () => {
     const saving = deferred<Awaited<ReturnType<typeof api.saveWorkspaceFile>>>();
     vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
diff --git a/webui/src/api/types.ts b/webui/src/api/types.ts
index 3abedab8..63287e68 100644
--- a/webui/src/api/types.ts
+++ b/webui/src/api/types.ts
@@ -244,6 +244,7 @@ export interface OkResponse {
 export interface OpenWorkspacePathResponse {
   ok: boolean;
   path: string;
+  error?: string;
 }
 
 export interface UiCapabilities {
diff --git a/webui/src/components/SettingsPage.tsx b/webui/src/components/SettingsPage.tsx
index 2344fbef..59555f96 100644
--- a/webui/src/components/SettingsPage.tsx
+++ b/webui/src/components/SettingsPage.tsx
@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { api, formatApiError } from '../api/client';
 import type { LlmConfigFull, RuntimeMetadata } from '../api/types';
 import {
@@ -29,11 +29,15 @@ export default function SettingsPage() {
   const [message, setMessage] = useState('');
   const [configError, setConfigError] = useState('');
   const [preferencesError, setPreferencesError] = useState('');
+  const [preferencesLoaded, setPreferencesLoaded] = useState(false);
   const [metadataError, setMetadataError] = useState('');
   const [desktopError, setDesktopError] = useState('');
+  const lifecycle = useRef(0);
+  const desktopToken = useRef(0);
   const desktop = isDesktopApp();
 
   useEffect(() => {
+    const life = ++lifecycle.current;
     let active = true;
     Promise.allSettled([api.getConfig(), api.getPreferences(), api.metadata()]).then(
       ([configResult, preferencesResult, metadataResult]) => {
@@ -51,6 +55,7 @@ export default function SettingsPage() {
           setGenre(prefs.default_genre ?? '');
           setStyle(prefs.preferred_style ?? '');
           setUsageLogs(prefs.allow_usage_logs ?? false);
+          setPreferencesLoaded(true);
         } else setPreferencesError(formatApiError(preferencesResult.reason, 'Request failed.'));
         if (metadataResult.status === 'fulfilled') setMetadata(metadataResult.value);
         else
@@ -61,7 +66,11 @@ export default function SettingsPage() {
     );
     if (desktop)
       getDesktopRuntimeStatus()
-        .then((value) => active && setRuntime(value))
+        .then((value) => {
+          if (!active || life !== lifecycle.current) return;
+          if (value) setRuntime(value);
+          else setDesktopError('Desktop Runtime unavailable: Request failed.');
+        })
         .catch(
           (error) =>
             active &&
@@ -71,6 +80,8 @@ export default function SettingsPage() {
         );
     return () => {
       active = false;
+      lifecycle.current += 1;
+      desktopToken.current += 1;
     };
   }, [desktop]);
 
@@ -96,6 +107,10 @@ export default function SettingsPage() {
 
   async function savePreferences() {
     setMessage('');
+    if (!preferencesLoaded) {
+      setMessage('Preferences are unavailable and cannot be saved.');
+      return;
+    }
     if (!STYLE_OPTIONS.includes(style as (typeof STYLE_OPTIONS)[number])) {
       setMessage('Choose a supported preferred style before saving.');
       return;
@@ -112,6 +127,56 @@ export default function SettingsPage() {
     }
   }
 
+  async function runDesktopAction(
+    operation: (isCurrent: () => boolean) => Promise<void>,
+    fallback: string,
+  ) {
+    const life = lifecycle.current;
+    const token = ++desktopToken.current;
+    setDesktopError('');
+    try {
+      await operation(() => life === lifecycle.current && token === desktopToken.current);
+    } catch (error) {
+      if (life === lifecycle.current && token === desktopToken.current)
+        setDesktopError(formatApiError(error, fallback));
+    }
+  }
+
+  const refreshRuntime = () =>
+    runDesktopAction(async (isCurrent) => {
+      const result = await getDesktopRuntimeStatus();
+      if (!result) throw new Error('Refresh runtime status failed.');
+      if (isCurrent()) setRuntime(result);
+    }, 'Refresh runtime status failed.');
+
+  const restartRuntime = () =>
+    runDesktopAction(async (isCurrent) => {
+      const result = await restartDesktopRuntime();
+      if (!result?.ok || !result.status)
+        throw new Error(result?.error || 'Restart runtime failed.');
+      if (isCurrent()) setRuntime(result.status);
+    }, 'Restart runtime failed.');
+
+  const openDiagnostics = () =>
+    runDesktopAction(async () => {
+      const result = await openDiagnosticsFolder();
+      if (!result?.ok) throw new Error(result?.error || 'Open diagnostics failed.');
+    }, 'Open diagnostics failed.');
+
+  const exportDiagnosticReport = () =>
+    runDesktopAction(async (isCurrent) => {
+      const result = await exportDiagnostics();
+      if (!result?.ok) throw new Error(result?.error || 'Export diagnostics failed.');
+      if (isCurrent()) setMessage(`Diagnostics exported to ${result.path}`);
+    }, 'Export diagnostics failed.');
+
+  const viewRuntimeLogs = () =>
+    runDesktopAction(async (isCurrent) => {
+      const result = await getDesktopRuntimeLogs();
+      if (!result || result.error) throw new Error(result?.error || 'View logs failed.');
+      if (isCurrent()) setLogs(result.lines);
+    }, 'View logs failed.');
+
   return (
     <main className={styles.page}>
       <header>
@@ -202,41 +267,47 @@ export default function SettingsPage() {
 
         <section className={styles.card}>
           <h2>Writing preferences</h2>
-          <label>
-            Default genre
-            <input value={genre} onChange={(event) => setGenre(event.target.value)} />
-          </label>
-          <label>
-            Preferred style
-            <select
-              aria-label="Preferred style"
-              value={style}
-              onChange={(event) => setStyle(event.target.value)}
-            >
-              {STYLE_OPTIONS.map((option) => (
-                <option key={option} value={option}>
-                  {option}
-                </option>
-              ))}
-            </select>
-          </label>
-          <label className={styles.check}>
-            <input
-              type="checkbox"
-              checked={usageLogs}
-              onChange={(event) => setUsageLogs(event.target.checked)}
-            />
-            Allow usage logs
-          </label>
-          <div className={styles.actions}>
-            <button
-              type="button"
-              disabled={!STYLE_OPTIONS.includes(style as (typeof STYLE_OPTIONS)[number])}
-              onClick={savePreferences}
-            >
-              Save preferences
-            </button>
-          </div>
+          {preferencesLoaded ? (
+            <>
+              <label>
+                Default genre
+                <input value={genre} onChange={(event) => setGenre(event.target.value)} />
+              </label>
+              <label>
+                Preferred style
+                <select
+                  aria-label="Preferred style"
+                  value={style}
+                  onChange={(event) => setStyle(event.target.value)}
+                >
+                  {STYLE_OPTIONS.map((option) => (
+                    <option key={option} value={option}>
+                      {option}
+                    </option>
+                  ))}
+                </select>
+              </label>
+              <label className={styles.check}>
+                <input
+                  type="checkbox"
+                  checked={usageLogs}
+                  onChange={(event) => setUsageLogs(event.target.checked)}
+                />
+                Allow usage logs
+              </label>
+              <div className={styles.actions}>
+                <button
+                  type="button"
+                  disabled={!STYLE_OPTIONS.includes(style as (typeof STYLE_OPTIONS)[number])}
+                  onClick={savePreferences}
+                >
+                  Save preferences
+                </button>
+              </div>
+            </>
+          ) : (
+            <p>{preferencesError ? 'Preferences are unavailable.' : 'Loading preferences...'}</p>
+          )}
         </section>
 
         <section className={styles.card}>
@@ -263,40 +334,19 @@ export default function SettingsPage() {
               </dl>
               {runtime?.error && <p role="alert">{runtime.error}</p>}
               <div className={styles.actions}>
-                <button type="button" onClick={() => getDesktopRuntimeStatus().then(setRuntime)}>
+                <button type="button" onClick={refreshRuntime}>
                   Refresh
                 </button>
-                <button
-                  type="button"
-                  onClick={() =>
-                    restartDesktopRuntime().then((result) => setRuntime(result?.status ?? null))
-                  }
-                >
+                <button type="button" onClick={restartRuntime}>
                   Restart Runtime
                 </button>
-                <button type="button" onClick={() => openDiagnosticsFolder()}>
+                <button type="button" onClick={openDiagnostics}>
                   Open diagnostics
                 </button>
-                <button
-                  type="button"
-                  onClick={() =>
-                    exportDiagnostics().then(
-                      (result) =>
-                        result &&
-                        setMessage(
-                          result.ok ? `Diagnostics exported to ${result.path}` : result.path,
-                        ),
-                    )
-                  }
-                >
+                <button type="button" onClick={exportDiagnosticReport}>
                   Export diagnostics
                 </button>
-                <button
-                  type="button"
-                  onClick={() =>
-                    getDesktopRuntimeLogs().then((result) => setLogs(result?.lines ?? []))
-                  }
-                >
+                <button type="button" onClick={viewRuntimeLogs}>
                   View logs
                 </button>
               </div>
diff --git a/webui/src/desktop.ts b/webui/src/desktop.ts
index ff42bff9..296892d7 100644
--- a/webui/src/desktop.ts
+++ b/webui/src/desktop.ts
@@ -21,15 +21,18 @@ export interface DesktopRuntimeStatus {
 export interface DesktopRuntimeRestartResponse {
   ok: boolean;
   status: DesktopRuntimeStatus;
+  error?: string;
 }
 
 export interface DesktopRuntimeLogsResponse {
   lines: string[];
+  error?: string;
 }
 
 export interface DesktopPathResponse {
   ok: boolean;
   path: string;
+  error?: string;
 }
 
 export function isDesktopApp() {
@@ -39,7 +42,7 @@ export function isDesktopApp() {
 export async function getDesktopAppInfo(): Promise<DesktopAppInfo | null> {
   if (!isDesktopApp()) return null;
   try {
-    return await invoke<DesktopAppInfo>('app_info');
+    return (await invoke<DesktopAppInfo>('app_info')) ?? null;
   } catch {
     return null;
   }
@@ -48,7 +51,7 @@ export async function getDesktopAppInfo(): Promise<DesktopAppInfo | null> {
 export async function getDesktopRuntimeStatus(): Promise<DesktopRuntimeStatus | null> {
   if (!isDesktopApp()) return null;
   try {
-    return await invoke<DesktopRuntimeStatus>('runtime_status');
+    return (await invoke<DesktopRuntimeStatus>('runtime_status')) ?? null;
   } catch {
     return null;
   }
@@ -57,16 +60,18 @@ export async function getDesktopRuntimeStatus(): Promise<DesktopRuntimeStatus |
 export async function restartDesktopRuntime(): Promise<DesktopRuntimeRestartResponse | null> {
   if (!isDesktopApp()) return null;
   try {
-    return await invoke<DesktopRuntimeRestartResponse>('runtime_restart');
+    return (await invoke<DesktopRuntimeRestartResponse>('runtime_restart')) ?? null;
   } catch {
     return null;
   }
 }
 
-export async function getDesktopRuntimeLogs(tail = 200): Promise<DesktopRuntimeLogsResponse | null> {
+export async function getDesktopRuntimeLogs(
+  tail = 200,
+): Promise<DesktopRuntimeLogsResponse | null> {
   if (!isDesktopApp()) return null;
   try {
-    return await invoke<DesktopRuntimeLogsResponse>('runtime_logs', { tail });
+    return (await invoke<DesktopRuntimeLogsResponse>('runtime_logs', { tail })) ?? null;
   } catch {
     return null;
   }
@@ -75,7 +80,7 @@ export async function getDesktopRuntimeLogs(tail = 200): Promise<DesktopRuntimeL
 export async function openDiagnosticsFolder(): Promise<DesktopPathResponse | null> {
   if (!isDesktopApp()) return null;
   try {
-    return await invoke<DesktopPathResponse>('open_diagnostics_folder');
+    return (await invoke<DesktopPathResponse>('open_diagnostics_folder')) ?? null;
   } catch {
     return null;
   }
@@ -84,7 +89,7 @@ export async function openDiagnosticsFolder(): Promise<DesktopPathResponse | nul
 export async function exportDiagnostics(): Promise<DesktopPathResponse | null> {
   if (!isDesktopApp()) return null;
   try {
-    return await invoke<DesktopPathResponse>('export_diagnostics');
+    return (await invoke<DesktopPathResponse>('export_diagnostics')) ?? null;
   } catch {
     return null;
   }
diff --git a/webui/src/pages/FilesPage.tsx b/webui/src/pages/FilesPage.tsx
index 1d016d92..ab15d6c3 100644
--- a/webui/src/pages/FilesPage.tsx
+++ b/webui/src/pages/FilesPage.tsx
@@ -30,6 +30,7 @@ function matchesType(file: WorkspaceFile, type: FileType) {
 
 export default function FilesPage({ worldId }: Props) {
   const [files, setFiles] = useState<WorkspaceFile[]>([]);
+  const [loadedWorld, setLoadedWorld] = useState<string | null>(null);
   const [root, setRoot] = useState('');
   const [links, setLinks] = useState<LinksState>({ status: 'loading', items: [] });
   const [selectedPath, setSelectedPath] = useState<string | null>(null);
@@ -38,22 +39,26 @@ export default function FilesPage({ worldId }: Props) {
   const [query, setQuery] = useState('');
   const [type, setType] = useState<FileType>('all');
   const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
+  const [listError, setListError] = useState<string | null>(null);
+  const [contentError, setContentError] = useState<string | null>(null);
   const [clipboardError, setClipboardError] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
+  const [openingRoot, setOpeningRoot] = useState(false);
   const [conflict, setConflict] = useState(false);
   const lifecycle = useRef(0);
   const listToken = useRef(0);
   const readToken = useRef(0);
   const saveToken = useRef(0);
   const savingRef = useRef(false);
+  const openingRootRef = useRef(false);
+  const openRootToken = useRef(0);
 
   const loadList = useCallback(async () => {
     if (savingRef.current) return;
     const life = lifecycle.current;
     const token = ++listToken.current;
     setLoading(true);
-    setError(null);
+    setListError(null);
     try {
       const result = await api.listWorkspaceFiles({
         world_id: worldId,
@@ -61,12 +66,13 @@ export default function FilesPage({ worldId }: Props) {
       });
       if (life !== lifecycle.current || token !== listToken.current) return;
       setFiles(result.files);
+      setLoadedWorld(worldId);
       setRoot(result.root);
       setSelectedPath(null);
       setLoaded(null);
     } catch (reason) {
       if (life === lifecycle.current && token === listToken.current)
-        setError(formatApiError(reason, 'Could not load files.'));
+        setListError(formatApiError(reason, 'Could not load files.'));
     } finally {
       if (life === lifecycle.current && token === listToken.current) setLoading(false);
     }
@@ -76,6 +82,8 @@ export default function FilesPage({ worldId }: Props) {
     lifecycle.current += 1;
     savingRef.current = false;
     setSaving(false);
+    openingRootRef.current = false;
+    setOpeningRoot(false);
     setConflict(false);
     setLinks({ status: 'loading', items: [] });
     loadList();
@@ -118,7 +126,7 @@ export default function FilesPage({ worldId }: Props) {
     setSelectedPath(path);
     setLoaded(null);
     setConflict(false);
-    setError(null);
+    setContentError(null);
     setClipboardError(null);
     try {
       const result = await api.readWorkspaceFile(path);
@@ -127,7 +135,7 @@ export default function FilesPage({ worldId }: Props) {
       setDraft(result.file.content);
     } catch (reason) {
       if (life === lifecycle.current && token === readToken.current)
-        setError(formatApiError(reason, 'Could not read file.'));
+        setContentError(formatApiError(reason, 'Could not read file.'));
     }
   }
 
@@ -140,7 +148,7 @@ export default function FilesPage({ worldId }: Props) {
     const version = loaded.version;
     savingRef.current = true;
     setSaving(true);
-    setError(null);
+    setContentError(null);
     setConflict(false);
     try {
       const result = await api.saveWorkspaceFile(target, content, version);
@@ -158,7 +166,7 @@ export default function FilesPage({ worldId }: Props) {
     } catch (reason) {
       if (life !== lifecycle.current || token !== saveToken.current) return;
       setConflict(isConflict(reason));
-      setError(formatApiError(reason, 'Save failed.'));
+      setContentError(formatApiError(reason, 'Save failed.'));
     } finally {
       if (life === lifecycle.current && token === saveToken.current) {
         savingRef.current = false;
@@ -167,6 +175,28 @@ export default function FilesPage({ worldId }: Props) {
     }
   }
 
+  async function openRoot() {
+    if (!root || savingRef.current || openingRootRef.current) return;
+    const life = lifecycle.current;
+    const token = ++openRootToken.current;
+    openingRootRef.current = true;
+    setOpeningRoot(true);
+    setListError(null);
+    try {
+      const result = await api.openWorkspacePath(root);
+      if (life !== lifecycle.current || token !== openRootToken.current) return;
+      if (!result?.ok) throw new Error(result?.error || 'Open workspace failed.');
+    } catch (reason) {
+      if (life === lifecycle.current && token === openRootToken.current)
+        setListError(formatApiError(reason, 'Open workspace failed.'));
+    } finally {
+      if (life === lifecycle.current && token === openRootToken.current) {
+        openingRootRef.current = false;
+        setOpeningRoot(false);
+      }
+    }
+  }
+
   async function copyDraft() {
     setClipboardError(null);
     try {
@@ -179,8 +209,9 @@ export default function FilesPage({ worldId }: Props) {
 
   const selected = files.find((file) => file.path === selectedPath) ?? null;
   const linked = selected ? links.items.filter((link) => link.file_path === selected.path) : [];
-  if (loading) return <PageState loading loadingLabel="Loading files" />;
-  if (error && files.length === 0) return <PageState error={new Error(error)} onRetry={loadList} />;
+  if (loading && loadedWorld !== worldId) return <PageState loading loadingLabel="Loading files" />;
+  if (listError && loadedWorld !== worldId)
+    return <PageState error={new Error(listError)} onRetry={loadList} />;
   return (
     <div className={styles.page}>
       <aside className={styles.library} aria-label="File library">
@@ -190,11 +221,16 @@ export default function FilesPage({ worldId }: Props) {
             Refresh
           </button>
         </header>
+        {listError && (
+          <div role="alert" className={styles.error}>
+            {listError}
+          </div>
+        )}
         {root && (
           <div className={styles.root}>
             <code>{root}</code>
-            <button type="button" onClick={() => api.openWorkspacePath(root)}>
-              Open workspace
+            <button type="button" disabled={saving || openingRoot} onClick={openRoot}>
+              {openingRoot ? 'Opening...' : 'Open workspace'}
             </button>
           </div>
         )}
@@ -277,9 +313,9 @@ export default function FilesPage({ worldId }: Props) {
           }
           inspectorLabel="File details"
         >
-          {error && (
+          {contentError && (
             <div role="alert" className={styles.error}>
-              {error}
+              {contentError}
             </div>
           )}
           {clipboardError && (
@@ -308,11 +344,18 @@ export default function FilesPage({ worldId }: Props) {
           />
         </DetailPane>
       ) : (
-        <PageState
-          isEmpty
-          emptyTitle={selected ? 'Loading file content' : 'Select a file'}
-          emptyDescription="File content is loaded only when you select it."
-        />
+        <div>
+          {contentError && (
+            <div role="alert" className={styles.error}>
+              {contentError}
+            </div>
+          )}
+          <PageState
+            isEmpty
+            emptyTitle={selected ? 'File content unavailable' : 'Select a file'}
+            emptyDescription="File content is loaded only when you select it."
+          />
+        </div>
       )}
     </div>
   );

From 42fc8e14bc41472cabc465fac6dbf0f3a4532ccf Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sun, 21 Jun 2026 12:57:50 +0800
Subject: [PATCH 46/49] style(webui): match approved desktop design system

---
 webui/src/__tests__/pages.test.tsx            |  62 ++++
 webui/src/__tests__/shell.test.tsx            |  18 +-
 .../components/layout/DetailPane.module.css   |  62 +++-
 webui/src/components/layout/DetailPane.tsx    |  49 ++-
 webui/src/pages/FilesPage.module.css          |   8 +
 webui/src/pages/FilesPage.tsx                 |  42 ++-
 webui/src/pages/ForeshadowingPage.tsx         | 325 +++++++++++++++---
 webui/src/shell/DesktopShell.module.css       |  43 ++-
 webui/src/styles/global.css                   |  49 ++-
 9 files changed, 569 insertions(+), 89 deletions(-)

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index a05292ab..223d48b0 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -383,6 +383,46 @@ describe('Files page', () => {
     }
   });
 
+  it('locks selected-file Reveal and reports null, false, and rejected results', async () => {
+    const revealing = deferred<Awaited<ReturnType<typeof api.openWorkspacePath>>>();
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file],
+    });
+    vi.mocked(api.readWorkspaceFile).mockResolvedValue({
+      ok: true,
+      file: {
+        path: file.path,
+        content: 'Original text',
+        encoding: 'utf-8',
+        updated_at: file.updated_at,
+        version: 'v1',
+      },
+    });
+    vi.mocked(api.openWorkspacePath)
+      .mockReturnValueOnce(revealing.promise)
+      .mockResolvedValueOnce(null as never)
+      .mockResolvedValueOnce({ ok: false, path: '', error: 'Reveal denied' } as never)
+      .mockRejectedValueOnce(new Error('Reveal crashed'));
+
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    const reveal = await screen.findByRole('button', { name: 'Reveal selected file' });
+
+    fireEvent.click(reveal);
+    expect(reveal).toBeDisabled();
+    expect(reveal).toHaveTextContent('Revealing...');
+    await act(async () => revealing.resolve({ ok: true, path: file.path } as never));
+    expect(await screen.findByRole('status')).toHaveTextContent('File revealed in workspace.');
+
+    for (const failure of [/reveal file failed/i, /Reveal denied/i, /Reveal crashed/i]) {
+      fireEvent.click(reveal);
+      expect(await screen.findByRole('alert')).toHaveTextContent(failure);
+      expect(reveal).not.toBeDisabled();
+    }
+  });
+
   it('ignores a pending save completion after unmount', async () => {
     const saving = deferred<Awaited<ReturnType<typeof api.saveWorkspaceFile>>>();
     vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
@@ -445,6 +485,10 @@ describe('Files page', () => {
 });
 
 describe('Foreshadowing page', () => {
+  it('keys relation chips by relation type and target id', () => {
+    const source = readFileSync(join(process.cwd(), 'src/pages/ForeshadowingPage.tsx'), 'utf8');
+    expect(source).toMatch(/key=\{`\$\{position\.type\}:\$\{position\.id\}`\}/);
+  });
   it('derives overdue only when planned and current chapter positions both exist', () => {
     expect(
       deriveForeshadowingStatus({ status: 'open', plannedPosition: 2, currentPosition: null }),
@@ -1563,6 +1607,24 @@ describe('DetailPane', () => {
     expect(screen.getByRole('button', { name: 'Edit' })).toBeDefined();
     expect(screen.getByRole('complementary')).toHaveTextContent('Related chapters');
   });
+
+  it('keeps a collapsed inspector reachable and restores trigger focus after Escape', () => {
+    render(
+      <DetailPane title="Lian" inspector={<p>Related chapters</p>} inspectorLabel="Relations">
+        <p>Character details</p>
+      </DetailPane>,
+    );
+
+    const toggle = screen.getByRole('button', { name: 'Hide Relations' });
+    fireEvent.click(toggle);
+    expect(screen.queryByRole('complementary', { name: 'Relations' })).toBeNull();
+    expect(toggle).toHaveAccessibleName('Show Relations');
+    fireEvent.click(toggle);
+    const inspector = screen.getByRole('complementary', { name: 'Relations' });
+    fireEvent.keyDown(inspector, { key: 'Escape' });
+    expect(screen.queryByRole('complementary', { name: 'Relations' })).toBeNull();
+    expect(toggle).toHaveFocus();
+  });
 });
 
 describe('Overview selectors', () => {
diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index cfa983ff..460e5e3d 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -131,7 +131,11 @@ describe('desktop shell', () => {
                 version: 'v1',
               },
             });
-            dispatch({ type: 'UPDATE_EDITOR_BUFFER', fileId: 'draft.md', content: 'Unsaved draft' });
+            dispatch({
+              type: 'UPDATE_EDITOR_BUFFER',
+              fileId: 'draft.md',
+              content: 'Unsaved draft',
+            });
           }}
         >
           Open workspace draft
@@ -348,6 +352,18 @@ describe('desktop shell', () => {
     expect(css).toMatch(/\.navigation\s*\{[^}]*overflow-y:\s*auto/s);
   });
 
+  it('defines the approved shared visual tokens and responsive shell contracts', () => {
+    const globalCss = readFileSync('src/styles/global.css', 'utf8');
+    const shellCss = readFileSync('src/shell/DesktopShell.module.css', 'utf8');
+
+    expect(globalCss).toContain('--brand: #06266f');
+    expect(globalCss).toContain('--page: #ffffff');
+    expect(globalCss).toMatch(/:focus-visible/);
+    expect(globalCss).toMatch(/prefers-reduced-motion:\s*reduce/);
+    expect(shellCss).toMatch(/@media \(max-width: 1180px\)/);
+    expect(shellCss).toMatch(/@media \(max-width: 980px\)/);
+  });
+
   it('gives the world dashboard a definite scroll-container height', () => {
     const css = readFileSync('src/components/WorldDashboard.module.css', 'utf8');
     const dashboardRule = css.match(/\.dashboard\s*\{([^}]*)\}/s)?.[1] ?? '';
diff --git a/webui/src/components/layout/DetailPane.module.css b/webui/src/components/layout/DetailPane.module.css
index 8154b809..beea0392 100644
--- a/webui/src/components/layout/DetailPane.module.css
+++ b/webui/src/components/layout/DetailPane.module.css
@@ -41,6 +41,27 @@
   gap: var(--space-sm);
 }
 
+.inspectorToggle,
+.inspectorClose {
+  min-height: 32px;
+  padding: 0 var(--space-md);
+  border: 1px solid var(--border);
+  border-radius: var(--rounded-md);
+  background: var(--surface);
+  color: var(--brand);
+  cursor: pointer;
+  font-weight: 700;
+}
+
+.inspectorToggle {
+  display: none;
+}
+
+.inspectorClose {
+  display: none;
+  margin: 0 0 var(--space-md) auto;
+}
+
 .body {
   min-height: 0;
   display: grid;
@@ -62,19 +83,44 @@
   background: var(--surface-strong);
 }
 
-@media (max-width: 767px) {
-  .header {
-    flex-direction: column;
-  }
+.inspector[aria-hidden='true'] {
+  display: none;
+}
 
+@media (max-width: 1180px) {
   .body {
-    display: flex;
+    position: relative;
+    display: block;
+  }
+
+  .content {
+    height: 100%;
+  }
+
+  .inspectorToggle,
+  .inspectorClose {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .inspector {
+    position: absolute;
+    z-index: 20;
+    inset: 0 0 0 auto;
+    width: min(340px, 82%);
+    border-left: 1px solid var(--border);
+    background: var(--surface);
+    box-shadow: var(--shadow-md);
+    overscroll-behavior: contain;
+  }
+}
+
+@media (max-width: 767px) {
+  .header {
     flex-direction: column;
   }
 
   .inspector {
-    width: auto;
-    border-top: 1px solid var(--border);
-    border-left: 0;
+    width: min(320px, 92%);
   }
 }
diff --git a/webui/src/components/layout/DetailPane.tsx b/webui/src/components/layout/DetailPane.tsx
index 915f5979..85914fa8 100644
--- a/webui/src/components/layout/DetailPane.tsx
+++ b/webui/src/components/layout/DetailPane.tsx
@@ -1,4 +1,4 @@
-import { useId, type ReactNode } from 'react';
+import { useId, useRef, useState, type ReactNode } from 'react';
 import styles from './DetailPane.module.css';
 
 export type DetailPaneProps = {
@@ -21,6 +21,14 @@ export default function DetailPane({
   className,
 }: DetailPaneProps) {
   const titleId = useId();
+  const inspectorId = useId();
+  const inspectorToggleRef = useRef<HTMLButtonElement>(null);
+  const [inspectorOpen, setInspectorOpen] = useState(true);
+
+  function closeInspector(restoreFocus = false) {
+    setInspectorOpen(false);
+    if (restoreFocus) inspectorToggleRef.current?.focus();
+  }
 
   return (
     <section
@@ -32,13 +40,46 @@ export default function DetailPane({
           <h1 id={titleId}>{title}</h1>
           {description ? <div className={styles.description}>{description}</div> : null}
         </div>
-        {actions ? <div className={styles.actions}>{actions}</div> : null}
+        {actions || inspector ? (
+          <div className={styles.actions}>
+            {inspector ? (
+              <button
+                ref={inspectorToggleRef}
+                type="button"
+                className={styles.inspectorToggle}
+                aria-controls={inspectorId}
+                aria-expanded={inspectorOpen}
+                aria-label={`${inspectorOpen ? 'Hide' : 'Show'} ${inspectorLabel}`}
+                onClick={() => setInspectorOpen((open) => !open)}
+              >
+                {inspectorOpen ? 'Hide details' : 'Show details'}
+              </button>
+            ) : null}
+            {actions}
+          </div>
+        ) : null}
       </header>
       <div className={styles.body}>
         <div className={styles.content}>{children}</div>
         {inspector ? (
-          <aside className={styles.inspector} aria-label={inspectorLabel}>
-            {inspector}
+          <aside
+            id={inspectorId}
+            className={styles.inspector}
+            aria-label={inspectorLabel}
+            aria-hidden={!inspectorOpen}
+            onKeyDown={(event) => {
+              if (event.key === 'Escape') closeInspector(true);
+            }}
+          >
+            <button
+              type="button"
+              className={styles.inspectorClose}
+              aria-label={`Close ${inspectorLabel}`}
+              onClick={() => closeInspector(true)}
+            >
+              Close
+            </button>
+            <div>{inspector}</div>
           </aside>
         ) : null}
       </div>
diff --git a/webui/src/pages/FilesPage.module.css b/webui/src/pages/FilesPage.module.css
index 63015afd..464fa393 100644
--- a/webui/src/pages/FilesPage.module.css
+++ b/webui/src/pages/FilesPage.module.css
@@ -61,6 +61,14 @@
   margin-bottom: 12px;
   color: var(--danger);
 }
+
+.success {
+  padding: 8px 10px;
+  border: 1px solid #bbf7d0;
+  border-radius: var(--rounded-md);
+  background: var(--green-soft);
+  color: #166534;
+}
 .conflict {
   display: flex;
   gap: 8px;
diff --git a/webui/src/pages/FilesPage.tsx b/webui/src/pages/FilesPage.tsx
index ab15d6c3..c5d46b2d 100644
--- a/webui/src/pages/FilesPage.tsx
+++ b/webui/src/pages/FilesPage.tsx
@@ -44,6 +44,11 @@ export default function FilesPage({ worldId }: Props) {
   const [clipboardError, setClipboardError] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
   const [openingRoot, setOpeningRoot] = useState(false);
+  const [revealingPath, setRevealingPath] = useState<string | null>(null);
+  const [revealMessage, setRevealMessage] = useState<{
+    type: 'success' | 'error';
+    text: string;
+  } | null>(null);
   const [conflict, setConflict] = useState(false);
   const lifecycle = useRef(0);
   const listToken = useRef(0);
@@ -52,6 +57,7 @@ export default function FilesPage({ worldId }: Props) {
   const savingRef = useRef(false);
   const openingRootRef = useRef(false);
   const openRootToken = useRef(0);
+  const revealToken = useRef(0);
 
   const loadList = useCallback(async () => {
     if (savingRef.current) return;
@@ -84,6 +90,8 @@ export default function FilesPage({ worldId }: Props) {
     setSaving(false);
     openingRootRef.current = false;
     setOpeningRoot(false);
+    setRevealingPath(null);
+    setRevealMessage(null);
     setConflict(false);
     setLinks({ status: 'loading', items: [] });
     loadList();
@@ -197,6 +205,25 @@ export default function FilesPage({ worldId }: Props) {
     }
   }
 
+  async function revealSelectedFile(path: string) {
+    if (savingRef.current || revealingPath) return;
+    const life = lifecycle.current;
+    const token = ++revealToken.current;
+    setRevealingPath(path);
+    setRevealMessage(null);
+    try {
+      const result = await api.openWorkspacePath(path, true);
+      if (life !== lifecycle.current || token !== revealToken.current) return;
+      if (!result?.ok) throw new Error(result?.error || 'Reveal file failed.');
+      setRevealMessage({ type: 'success', text: 'File revealed in workspace.' });
+    } catch (reason) {
+      if (life === lifecycle.current && token === revealToken.current)
+        setRevealMessage({ type: 'error', text: formatApiError(reason, 'Reveal file failed.') });
+    } finally {
+      if (life === lifecycle.current && token === revealToken.current) setRevealingPath(null);
+    }
+  }
+
   async function copyDraft() {
     setClipboardError(null);
     try {
@@ -278,10 +305,11 @@ export default function FilesPage({ worldId }: Props) {
             <>
               <button
                 type="button"
-                disabled={saving}
-                onClick={() => api.openWorkspacePath(selected.path, true)}
+                aria-label="Reveal selected file"
+                disabled={saving || revealingPath === selected.path}
+                onClick={() => revealSelectedFile(selected.path)}
               >
-                Reveal
+                {revealingPath === selected.path ? 'Revealing...' : 'Reveal'}
               </button>
               <button
                 type="button"
@@ -313,6 +341,14 @@ export default function FilesPage({ worldId }: Props) {
           }
           inspectorLabel="File details"
         >
+          {revealMessage ? (
+            <div
+              role={revealMessage.type === 'error' ? 'alert' : 'status'}
+              className={revealMessage.type === 'error' ? styles.error : styles.success}
+            >
+              {revealMessage.text}
+            </div>
+          ) : null}
           {contentError && (
             <div role="alert" className={styles.error}>
               {contentError}
diff --git a/webui/src/pages/ForeshadowingPage.tsx b/webui/src/pages/ForeshadowingPage.tsx
index 6269d9c4..a5fc7f4f 100644
--- a/webui/src/pages/ForeshadowingPage.tsx
+++ b/webui/src/pages/ForeshadowingPage.tsx
@@ -15,25 +15,41 @@ type Data = {
   contextError: string | null;
 };
 
-export function deriveForeshadowingStatus(
-  positions: { status?: string; plannedPosition: number | null; currentPosition: number | null },
-): 'overdue' | null {
-  if (positions.status !== 'open' || positions.plannedPosition == null || positions.currentPosition == null) return null;
+export function deriveForeshadowingStatus(positions: {
+  status?: string;
+  plannedPosition: number | null;
+  currentPosition: number | null;
+}): 'overdue' | null {
+  if (
+    positions.status !== 'open' ||
+    positions.plannedPosition === null ||
+    positions.currentPosition === null
+  )
+    return null;
   return positions.currentPosition > positions.plannedPosition ? 'overdue' : null;
 }
 
 export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const resource = useResource(`foreshadowing:${worldId}`, async () => {
     const [foreshadowing, chapters, scenes] = await Promise.allSettled([
-      api.listForeshadowing(worldId), api.listChapters(worldId), api.listScenes(worldId),
+      api.listForeshadowing(worldId),
+      api.listChapters(worldId),
+      api.listScenes(worldId),
     ]);
     if (foreshadowing.status === 'rejected') throw foreshadowing.reason;
-    const failures = [chapters, scenes].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
+    const failures = [chapters, scenes].filter(
+      (result) => result.status === 'rejected',
+    ) as PromiseRejectedResult[];
     return {
       items: foreshadowing.value.foreshadowing ?? foreshadowing.value.items ?? [],
       chapters: chapters.status === 'fulfilled' ? chapters.value.chapters : [],
       scenes: scenes.status === 'fulfilled' ? scenes.value.scenes : [],
-      contextError: failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') || null,
+      contextError:
+        failures
+          .map((result) =>
+            result.reason instanceof Error ? result.reason.message : String(result.reason),
+          )
+          .join(' ') || null,
     };
   });
   const [selectedId, setSelectedId] = useState<string | null>(null);
@@ -49,84 +65,311 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const committedWorldRef = useRef(worldId);
   const mountedRef = useRef(false);
   const data: Data | null = resource.data;
-  const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
+  const items = useMemo(
+    () => (data?.items ?? []).filter((item) => !removed.includes(item.id)),
+    [data, removed],
+  );
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
-  useEffect(() => { setSelectedId(null); setRemoved([]); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
+  useEffect(() => {
+    setSelectedId(null);
+    setRemoved([]);
+    setEditing(false);
+    setCreateOpen(false);
+    setPendingMutation(null);
+    pendingMutationRef.current = false;
+    setMutationError(null);
+  }, [worldId]);
   useEffect(() => {
     mountedRef.current = true;
     if (committedWorldRef.current !== worldId) {
       committedWorldRef.current = worldId;
       generationRef.current += 1;
     }
-    return () => { mountedRef.current = false; generationRef.current += 1; };
+    return () => {
+      mountedRef.current = false;
+      generationRef.current += 1;
+    };
   }, [worldId]);
   useEffect(() => {
-    if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null);
+    if (selectedId && !filtered.some((item) => item.id === selectedId))
+      setSelectedId(filtered[0]?.id ?? null);
   }, [filtered, selectedId]);
-  useEffect(() => { setPayoff(selected?.pay_off_idea ?? ''); setEditing(false); }, [selected?.id]);
+  useEffect(() => {
+    setPayoff(selected?.pay_off_idea ?? '');
+    setEditing(false);
+  }, [selected?.id]);
 
   async function save() {
-    if (!selected || pendingMutationRef.current || !window.confirm('Update this foreshadowing item?')) return;
+    if (
+      !selected ||
+      pendingMutationRef.current ||
+      !window.confirm('Update this foreshadowing item?')
+    )
+      return;
     const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('update');
     setMutationError(null);
-    try { await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff }); if (mountedRef.current && generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
-    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try {
+      await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff });
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        setEditing(false);
+        resource.retry();
+      }
+    } catch (error) {
+      if (mountedRef.current && generationRef.current === operationGeneration)
+        setMutationError((error as Error).message);
+    } finally {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        pendingMutationRef.current = false;
+        setPendingMutation(null);
+      }
+    }
   }
 
   async function remove() {
-    if (!selected || pendingMutationRef.current || !window.confirm('Delete this foreshadowing item?')) return;
+    if (
+      !selected ||
+      pendingMutationRef.current ||
+      !window.confirm('Delete this foreshadowing item?')
+    )
+      return;
     setMutationError(null);
     const id = selected.id;
     const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('delete');
-    try { await api.deleteForeshadowing(operationWorld, id); if (mountedRef.current && generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); resource.retry(); } }
-    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    try {
+      await api.deleteForeshadowing(operationWorld, id);
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        setRemoved((ids) => [...ids, id]);
+        setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null);
+        resource.retry();
+      }
+    } catch (error) {
+      if (mountedRef.current && generationRef.current === operationGeneration)
+        setMutationError((error as Error).message);
+    } finally {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        pendingMutationRef.current = false;
+        setPendingMutation(null);
+      }
+    }
   }
 
   function changeFilter(nextFilter: string) {
     setFilter(nextFilter);
-    const visible = nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
+    const visible =
+      nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
     setSelectedId(visible[0]?.id ?? null);
   }
 
-  if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading foreshadowing" error={resource.error} onRetry={resource.retry} />;
+  if (!data)
+    return (
+      <PageState
+        loading={resource.status === 'loading'}
+        loadingLabel="Loading foreshadowing"
+        error={resource.error}
+        onRetry={resource.retry}
+      />
+    );
   return (
     <main className={styles.workspace}>
       <aside className={styles.listPane}>
-        <header><div><span>Narrative threads</span><h1>Foreshadowing</h1></div><div className={styles.tools}><button aria-label="Refresh foreshadowing" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create foreshadowing" disabled={Boolean(pendingMutation)} onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
-        <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => changeFilter(event.target.value)}><option value="all">All</option><option value="open">Open</option><option value="paid">Paid</option><option value="abandoned">Abandoned</option></select></label>
-        {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
-        {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Foreshadowing" renderItem={(item) => <div className={styles.listItem}><Sparkles /><div><strong>{item.content}</strong><span>{item.status ?? 'No status'}</span></div></div>} /> : <p className={styles.empty}>No foreshadowing matches this filter.</p>}
-        <footer>{filtered.length} {filtered.length === 1 ? 'thread' : 'threads'}</footer>
+        <header>
+          <div>
+            <span>Narrative threads</span>
+            <h1>Foreshadowing</h1>
+          </div>
+          <div className={styles.tools}>
+            <button aria-label="Refresh foreshadowing" onClick={resource.retry}>
+              <RefreshCw />
+            </button>
+            <button
+              aria-label="Create foreshadowing"
+              disabled={Boolean(pendingMutation)}
+              onClick={() => setCreateOpen(true)}
+            >
+              <Plus />
+            </button>
+          </div>
+        </header>
+        <label className={styles.filter}>
+          <Filter />
+          <span>Status</span>
+          <select value={filter} onChange={(event) => changeFilter(event.target.value)}>
+            <option value="all">All</option>
+            <option value="open">Open</option>
+            <option value="paid">Paid</option>
+            <option value="abandoned">Abandoned</option>
+          </select>
+        </label>
+        {(resource.error || mutationError || data.contextError) && (
+          <div role="alert" className={styles.warning}>
+            {mutationError ?? resource.error?.message ?? data.contextError}
+          </div>
+        )}
+        {filtered.length ? (
+          <ResourceList
+            items={filtered}
+            selectedId={selectedId}
+            getId={(item) => item.id}
+            onSelect={setSelectedId}
+            ariaLabel="Foreshadowing"
+            renderItem={(item) => (
+              <div className={styles.listItem}>
+                <Sparkles />
+                <div>
+                  <strong>{item.content}</strong>
+                  <span>{item.status ?? 'No status'}</span>
+                </div>
+              </div>
+            )}
+          />
+        ) : (
+          <p className={styles.empty}>No foreshadowing matches this filter.</p>
+        )}
+        <footer>
+          {filtered.length} {filtered.length === 1 ? 'thread' : 'threads'}
+        </footer>
       </aside>
       <section className={styles.detail} aria-label="Foreshadowing detail">
-        {selected ? <><header className={styles.detailHeader}><div><span>Thread detail</span><h2>{selected.content}</h2></div><div className={styles.actions}><button aria-label="Edit foreshadowing" disabled={Boolean(pendingMutation)} onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete foreshadowing" disabled={Boolean(pendingMutation)} onClick={remove}><Trash2 /> Delete</button></div></header>
-          <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Hint level" value={selected.hint_level} /><Fact label="Planted at" value={selected.planted_at} /><Fact label="Paid at" value={selected.paid_at} /></div>
-          <section className={styles.block}><h3>Payoff idea</h3>{editing ? <><textarea aria-label="Payoff idea" disabled={Boolean(pendingMutation)} value={payoff} onChange={(event) => setPayoff(event.target.value)} /><button className={styles.primary} disabled={Boolean(pendingMutation)} onClick={save}>Save changes</button></> : <p>{selected.pay_off_idea || 'No payoff idea recorded.'}</p>}</section>
-          {selected.tags?.length ? <section className={styles.block}><h3>Tags</h3><div className={styles.chips}>{selected.tags.map((tag) => <span key={tag}>{tag}</span>)}</div></section> : null}
-        </> : <Pick icon={<Sparkles />} title="Select foreshadowing" text="Choose a thread to inspect its recorded details." />}
+        {selected ? (
+          <>
+            <header className={styles.detailHeader}>
+              <div>
+                <span>Thread detail</span>
+                <h2>{selected.content}</h2>
+              </div>
+              <div className={styles.actions}>
+                <button
+                  aria-label="Edit foreshadowing"
+                  disabled={Boolean(pendingMutation)}
+                  onClick={() => setEditing(true)}
+                >
+                  <Pencil /> Edit
+                </button>
+                <button
+                  aria-label="Delete foreshadowing"
+                  disabled={Boolean(pendingMutation)}
+                  onClick={remove}
+                >
+                  <Trash2 /> Delete
+                </button>
+              </div>
+            </header>
+            <div className={styles.cards}>
+              <Fact label="Status" value={selected.status} />
+              <Fact label="Hint level" value={selected.hint_level} />
+              <Fact label="Planted at" value={selected.planted_at} />
+              <Fact label="Paid at" value={selected.paid_at} />
+            </div>
+            <section className={styles.block}>
+              <h3>Payoff idea</h3>
+              {editing ? (
+                <>
+                  <textarea
+                    aria-label="Payoff idea"
+                    disabled={Boolean(pendingMutation)}
+                    value={payoff}
+                    onChange={(event) => setPayoff(event.target.value)}
+                  />
+                  <button
+                    className={styles.primary}
+                    disabled={Boolean(pendingMutation)}
+                    onClick={save}
+                  >
+                    Save changes
+                  </button>
+                </>
+              ) : (
+                <p>{selected.pay_off_idea || 'No payoff idea recorded.'}</p>
+              )}
+            </section>
+            {selected.tags?.length ? (
+              <section className={styles.block}>
+                <h3>Tags</h3>
+                <div className={styles.chips}>
+                  {selected.tags.map((tag) => (
+                    <span key={tag}>{tag}</span>
+                  ))}
+                </div>
+              </section>
+            ) : null}
+          </>
+        ) : (
+          <Pick
+            icon={<Sparkles />}
+            title="Select foreshadowing"
+            text="Choose a thread to inspect its recorded details."
+          />
+        )}
       </section>
-      <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <ForeshadowingContext item={selected} data={data} /> : <p>Select a thread to see resolved narrative positions.</p>}</aside>
-      {createOpen ? <CreateForeshadowingModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
+      <aside className={styles.contextPane}>
+        <h2>Real context</h2>
+        {selected ? (
+          <ForeshadowingContext item={selected} data={data} />
+        ) : (
+          <p>Select a thread to see resolved narrative positions.</p>
+        )}
+      </aside>
+      {createOpen ? (
+        <CreateForeshadowingModal
+          worldId={worldId}
+          onClose={() => setCreateOpen(false)}
+          onCreated={resource.retry}
+        />
+      ) : null}
     </main>
   );
 }
 
-function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
-function Pick({ icon, title, text }: { icon: React.ReactNode; title: string; text: string }) { return <div className={styles.pick}>{icon}<h2>{title}</h2><p>{text}</p></div>; }
+function Fact({ label, value }: { label: string; value?: string }) {
+  return (
+    <div className={styles.fact}>
+      <span>{label}</span>
+      <strong>{value || 'Not set'}</strong>
+    </div>
+  );
+}
+function Pick({ icon, title, text }: { icon: React.ReactNode; title: string; text: string }) {
+  return (
+    <div className={styles.pick}>
+      {icon}
+      <h2>{title}</h2>
+      <p>{text}</p>
+    </div>
+  );
+}
 function ForeshadowingContext({ item, data }: { item: ForeshadowingItem; data: Data }) {
-  const resolve = (id?: string) => data.scenes.find((scene) => scene.id === id)?.title ?? data.chapters.find((chapter) => chapter.id === id)?.title;
-  const planted = resolve(item.planted_at);
-  const paid = resolve(item.paid_at);
-  const positions = [planted, paid].filter(Boolean) as string[];
-  return <div className={styles.context}>{positions.length ? <div><h3>Narrative positions</h3><div className={styles.chips}>{positions.map((position) => <span key={position}>{position}</span>)}</div></div> : <p>No resolvable narrative positions recorded.</p>}</div>;
+  const resolve = (type: 'planted' | 'paid', id?: string) => {
+    if (!id) return null;
+    const label =
+      data.scenes.find((scene) => scene.id === id)?.title ??
+      data.chapters.find((chapter) => chapter.id === id)?.title;
+    return label ? { type, id, label } : null;
+  };
+  const positions = [resolve('planted', item.planted_at), resolve('paid', item.paid_at)].filter(
+    Boolean,
+  ) as { type: 'planted' | 'paid'; id: string; label: string }[];
+  return (
+    <div className={styles.context}>
+      {positions.length ? (
+        <div>
+          <h3>Narrative positions</h3>
+          <div className={styles.chips}>
+            {positions.map((position) => (
+              <span key={`${position.type}:${position.id}`}>{position.label}</span>
+            ))}
+          </div>
+        </div>
+      ) : (
+        <p>No resolvable narrative positions recorded.</p>
+      )}
+    </div>
+  );
 }
diff --git a/webui/src/shell/DesktopShell.module.css b/webui/src/shell/DesktopShell.module.css
index aa7884ee..79fb3454 100644
--- a/webui/src/shell/DesktopShell.module.css
+++ b/webui/src/shell/DesktopShell.module.css
@@ -1,5 +1,5 @@
 .shell {
-  --shell-navy: #082a78;
+  --shell-navy: var(--brand);
   display: grid;
   grid-template-columns: 244px minmax(0, 1fr);
   width: 100%;
@@ -172,9 +172,19 @@
   border: 0;
 }
 
-@media (max-width: 960px) {
+@media (max-width: 1180px) {
+  .stage {
+    grid-template-rows: 58px minmax(0, 1fr);
+  }
+
+  .topbar {
+    padding-inline: 16px;
+  }
+}
+
+@media (max-width: 980px) {
   .shell {
-    grid-template-columns: 202px minmax(0, 1fr);
+    grid-template-columns: 184px minmax(0, 1fr);
   }
 
   .sidebar {
@@ -184,4 +194,31 @@
   .navButton {
     font-size: 12px;
   }
+
+  .brand img {
+    width: 108px;
+  }
+
+  .worldSelector {
+    min-width: 164px;
+  }
+}
+
+@media (max-height: 640px) {
+  .brand {
+    height: 38px;
+  }
+
+  .sidebar {
+    gap: 6px;
+    padding-block: 8px;
+  }
+
+  .worldCard {
+    min-height: 40px;
+  }
+
+  .stage {
+    grid-template-rows: 52px minmax(0, 1fr);
+  }
 }
diff --git a/webui/src/styles/global.css b/webui/src/styles/global.css
index dcaaaf7b..8138bbba 100644
--- a/webui/src/styles/global.css
+++ b/webui/src/styles/global.css
@@ -7,28 +7,28 @@
 }
 
 :root {
-  --page: #f6f6f4;
-  --page-warm: #ededeb;
+  --page: #ffffff;
+  --page-warm: #f1f5f9;
   --surface: #ffffff;
-  --surface-muted: #f2f2f0;
-  --surface-strong: #fafafa;
+  --surface-muted: #f1f5f9;
+  --surface-strong: #f8fafc;
   --surface-raised: #ffffff;
   --glass: rgba(255, 255, 255, 0.74);
   --glass-strong: rgba(255, 255, 255, 0.9);
-  --ink: #171717;
-  --ink-soft: #333333;
-  --muted: #77756f;
-  --muted-strong: #55524c;
-  --border: #e0dfdc;
-  --border-strong: #c7c5bf;
+  --ink: #0f172a;
+  --ink-soft: #1e293b;
+  --muted: #64748b;
+  --muted-strong: #475569;
+  --border: #e2e8f0;
+  --border-strong: #cbd5e1;
   --teal: #171717;
   --teal-strong: #171717;
   --teal-soft: #ededeb;
   --teal-wash: #f7f7f5;
-  --brand: #343434;
-  --brand-strong: #171717;
-  --brand-soft: #e8e7e4;
-  --brand-wash: #f7f7f5;
+  --brand: #06266f;
+  --brand-strong: #041c55;
+  --brand-soft: #dbe7ff;
+  --brand-wash: #f3f7ff;
   --amber: #8a5a12;
   --amber-soft: #fbf2dc;
   --amber-wash: #fafafa;
@@ -42,11 +42,11 @@
   --purple-soft: #f0efed;
   --green: #16a34a;
   --green-soft: #dcfce7;
-  --hover: rgba(23, 23, 23, 0.055);
+  --hover: rgba(6, 38, 111, 0.06);
   --shadow-sm: 0 1px 2px rgba(23, 23, 23, 0.06);
   --shadow-md: 0 12px 28px rgba(23, 23, 23, 0.1);
   --shadow-lg: 0 18px 46px rgba(23, 23, 23, 0.12);
-  --ring: 0 0 0 3px rgba(23, 23, 23, 0.12);
+  --ring: 0 0 0 3px rgba(6, 38, 111, 0.2);
   --rounded-sm: 4px;
   --rounded-md: 6px;
   --rounded-lg: 8px;
@@ -71,7 +71,7 @@
   --color-text-primary: var(--ink);
   --color-text-secondary: var(--muted-strong);
   --color-text-tertiary: var(--muted);
-  --color-accent: var(--ink);
+  --color-accent: var(--brand);
   --color-error: var(--ruby);
   --color-error-bg: var(--ruby-soft);
   --color-error-border: #fecaca;
@@ -98,19 +98,8 @@ body {
   overflow: hidden;
 }
 
-body::before {
-  content: '';
-  position: fixed;
-  inset: 0;
-  pointer-events: none;
-  background-image:
-    linear-gradient(rgba(23, 23, 23, 0.035) 1px, transparent 1px),
-    linear-gradient(90deg, rgba(23, 23, 23, 0.03) 1px, transparent 1px);
-  background-size: 34px 34px;
-  mask-image: radial-gradient(circle at 50% 36%, #000 0%, transparent 68%);
-}
-
 button,
+input,
 select,
 textarea {
   font: inherit;
@@ -121,6 +110,8 @@ button {
 }
 
 button:focus-visible,
+input:focus-visible,
+a:focus-visible,
 select:focus-visible,
 textarea:focus-visible {
   outline: none;

From b7bffec0baf7d9b17b40af8287ac1deda58757ce Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sun, 21 Jun 2026 13:25:12 +0800
Subject: [PATCH 47/49] fix(webui): complete responsive desktop drawers

---
 webui/src/__tests__/pages.test.tsx            |  78 +++-
 webui/src/__tests__/shell.test.tsx            |  11 +
 .../components/layout/DetailPane.module.css   |  16 +
 webui/src/components/layout/DetailPane.tsx    |  42 ++-
 .../layout/ResponsivePane.module.css          |  79 ++++
 .../src/components/layout/ResponsivePane.tsx  | 124 +++++++
 webui/src/pages/CharactersPage.module.css     |  74 ++--
 webui/src/pages/CharactersPage.tsx            |   5 +-
 webui/src/pages/FilesPage.module.css          |   4 +-
 webui/src/pages/FilesPage.tsx                 |  16 +-
 webui/src/pages/ForeshadowingPage.tsx         | 328 +++--------------
 webui/src/pages/OverviewPage.module.css       |  66 ++--
 webui/src/pages/ScenesPage.tsx                |   7 +-
 webui/src/pages/SecretsPage.tsx               | 340 ++++++++++++++++--
 webui/src/pages/SessionsPage.module.css       |  14 +-
 webui/src/pages/WorldPage.module.css          |  58 +--
 webui/src/shell/DesktopShell.module.css       |  67 +++-
 webui/src/shell/DesktopShell.tsx              |  62 +++-
 18 files changed, 941 insertions(+), 450 deletions(-)
 create mode 100644 webui/src/components/layout/ResponsivePane.module.css
 create mode 100644 webui/src/components/layout/ResponsivePane.tsx

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 223d48b0..0025cd4a 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -1,4 +1,4 @@
-import { readFileSync } from 'node:fs';
+import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { startTransition, Suspense, useState } from 'react';
 import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
@@ -12,6 +12,7 @@ import CreateSecretModal from '../components/Inspector/CreateSecretModal';
 import DetailPane from '../components/layout/DetailPane';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
+import ResponsivePane from '../components/layout/ResponsivePane';
 import { useResource } from '../hooks/useResource';
 import ChaptersPage from '../pages/ChaptersPage';
 import CharactersPage from '../pages/CharactersPage';
@@ -423,6 +424,57 @@ describe('Files page', () => {
     }
   });
 
+  it('invalidates pending Reveal feedback when another file is selected', async () => {
+    const revealing = deferred<Awaited<ReturnType<typeof api.openWorkspacePath>>>();
+    const second = { ...file, path: 'C:/story/second.md', name: 'second.md' };
+    vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
+      ok: true,
+      root: 'C:/story',
+      files: [file, second],
+    });
+    vi.mocked(api.readWorkspaceFile).mockImplementation(async (path) => ({
+      ok: true,
+      file: { path, content: path, encoding: 'utf-8', updated_at: '', version: 'v1' },
+    }));
+    vi.mocked(api.openWorkspacePath).mockReturnValue(revealing.promise);
+    render(<FilesPage worldId="world-1" />);
+    fireEvent.click(await screen.findByRole('option', { name: /draft/i }));
+    fireEvent.click(await screen.findByRole('button', { name: 'Reveal selected file' }));
+    fireEvent.click(screen.getByRole('option', { name: /second/i }));
+    expect(await screen.findByRole('button', { name: 'Reveal selected file' })).not.toBeDisabled();
+    await act(async () => revealing.resolve({ ok: true, path: file.path } as never));
+    expect(screen.queryByText('File revealed in workspace.')).toBeNull();
+  });
+
+  it('uses one shared responsive resource pane across the five rail pages', () => {
+    for (const page of [
+      'CharactersPage',
+      'FilesPage',
+      'ScenesPage',
+      'ForeshadowingPage',
+      'SecretsPage',
+    ]) {
+      const source = readFileSync(join(process.cwd(), `src/pages/${page}.tsx`), 'utf8');
+      expect(source).toContain('ResponsivePane');
+    }
+  });
+
+  it('keeps all page styles on approved global palette tokens', () => {
+    const pagesDir = join(process.cwd(), 'src/pages');
+    const files = readdirSync(pagesDir).filter((name) => name.endsWith('.module.css'));
+    const allowed = new Set(['#06266f', '#ffffff']);
+    for (const name of files) {
+      const css = readFileSync(join(pagesDir, name), 'utf8');
+      const colors = css.match(/#[0-9a-f]{3,8}\b/gi) ?? [];
+      expect(
+        colors.filter((color) => !allowed.has(color.toLowerCase())),
+        name,
+      ).toEqual([]);
+      if (css.includes('{'))
+        expect(css, name).toMatch(/var\(--(?:brand|surface|border|ink|muted|ruby|green|amber)/);
+    }
+  });
+
   it('ignores a pending save completion after unmount', async () => {
     const saving = deferred<Awaited<ReturnType<typeof api.saveWorkspaceFile>>>();
     vi.mocked(api.listWorkspaceFiles).mockResolvedValue({
@@ -1627,6 +1679,30 @@ describe('DetailPane', () => {
   });
 });
 
+describe('ResponsivePane', () => {
+  it('opens as a compact dialog, moves focus, closes on Escape, and restores focus', () => {
+    vi.stubGlobal('matchMedia', () => ({
+      matches: true,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }));
+    render(
+      <ResponsivePane label="Story resources">
+        <button type="button">First resource</button>
+      </ResponsivePane>,
+    );
+    const trigger = screen.getByRole('button', { name: 'Open Story resources' });
+    fireEvent.click(trigger);
+    const dialog = screen.getByRole('dialog', { name: 'Story resources' });
+    expect(dialog).toBeInTheDocument();
+    expect(within(dialog).getByRole('button', { name: 'Close Story resources' })).toHaveFocus();
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(screen.queryByRole('dialog', { name: 'Story resources' })).toBeNull();
+    expect(trigger).toHaveFocus();
+    vi.unstubAllGlobals();
+  });
+});
+
 describe('Overview selectors', () => {
   it('derives counts from real response-shaped resource fixtures', () => {
     expect(
diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index 460e5e3d..6bc388de 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -352,6 +352,17 @@ describe('desktop shell', () => {
     expect(css).toMatch(/\.navigation\s*\{[^}]*overflow-y:\s*auto/s);
   });
 
+  it('opens and closes compact navigation with Escape and restores focus', () => {
+    renderShell('overview');
+    const trigger = screen.getByRole('button', { name: 'Open navigation' });
+    fireEvent.click(trigger);
+    expect(screen.getByRole('dialog', { name: /navigation|导航/i })).toBeInTheDocument();
+    expect(screen.getAllByRole('button', { name: 'Close navigation' })[1]).toHaveFocus();
+    fireEvent.keyDown(document, { key: 'Escape' });
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(trigger).toHaveFocus();
+  });
+
   it('defines the approved shared visual tokens and responsive shell contracts', () => {
     const globalCss = readFileSync('src/styles/global.css', 'utf8');
     const shellCss = readFileSync('src/shell/DesktopShell.module.css', 'utf8');
diff --git a/webui/src/components/layout/DetailPane.module.css b/webui/src/components/layout/DetailPane.module.css
index beea0392..3f4b4135 100644
--- a/webui/src/components/layout/DetailPane.module.css
+++ b/webui/src/components/layout/DetailPane.module.css
@@ -83,6 +83,9 @@
   background: var(--surface-strong);
 }
 
+.backdrop {
+  display: none;
+}
 .inspector[aria-hidden='true'] {
   display: none;
 }
@@ -104,6 +107,7 @@
   }
 
   .inspector {
+    display: none;
     position: absolute;
     z-index: 20;
     inset: 0 0 0 auto;
@@ -113,6 +117,18 @@
     box-shadow: var(--shadow-md);
     overscroll-behavior: contain;
   }
+  .inspector[data-open='true'] {
+    display: block;
+  }
+  .backdrop {
+    display: block;
+    position: absolute;
+    z-index: 19;
+    inset: 0;
+    width: 100%;
+    border: 0;
+    background: rgb(15 23 42 / 38%);
+  }
 }
 
 @media (max-width: 767px) {
diff --git a/webui/src/components/layout/DetailPane.tsx b/webui/src/components/layout/DetailPane.tsx
index 85914fa8..6704f3d9 100644
--- a/webui/src/components/layout/DetailPane.tsx
+++ b/webui/src/components/layout/DetailPane.tsx
@@ -1,4 +1,4 @@
-import { useId, useRef, useState, type ReactNode } from 'react';
+import { useEffect, useId, useRef, useState, type ReactNode } from 'react';
 import styles from './DetailPane.module.css';
 
 export type DetailPaneProps = {
@@ -23,6 +23,8 @@ export default function DetailPane({
   const titleId = useId();
   const inspectorId = useId();
   const inspectorToggleRef = useRef<HTMLButtonElement>(null);
+  const inspectorRef = useRef<HTMLElement>(null);
+  const [compact, setCompact] = useState(false);
   const [inspectorOpen, setInspectorOpen] = useState(true);
 
   function closeInspector(restoreFocus = false) {
@@ -30,6 +32,32 @@ export default function DetailPane({
     if (restoreFocus) inspectorToggleRef.current?.focus();
   }
 
+  useEffect(() => {
+    const query = window.matchMedia?.('(max-width: 1180px)');
+    if (!query) return;
+    const update = () => {
+      setCompact(query.matches);
+      setInspectorOpen(!query.matches);
+    };
+    update();
+    query.addEventListener?.('change', update);
+    return () => query.removeEventListener?.('change', update);
+  }, []);
+
+  useEffect(() => {
+    if (!compact || !inspectorOpen) return;
+    inspectorRef.current
+      ?.querySelector<HTMLElement>(
+        'button, input, select, textarea, [tabindex]:not([tabindex="-1"])',
+      )
+      ?.focus();
+    const escape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') closeInspector(true);
+    };
+    document.addEventListener('keydown', escape);
+    return () => document.removeEventListener('keydown', escape);
+  }, [compact, inspectorOpen]);
+
   return (
     <section
       className={[styles.pane, className].filter(Boolean).join(' ')}
@@ -61,12 +89,24 @@ export default function DetailPane({
       </header>
       <div className={styles.body}>
         <div className={styles.content}>{children}</div>
+        {inspectorOpen ? (
+          <button
+            type="button"
+            className={styles.backdrop}
+            aria-label={`Close ${inspectorLabel}`}
+            onClick={() => closeInspector(true)}
+          />
+        ) : null}
         {inspector ? (
           <aside
+            ref={inspectorRef}
             id={inspectorId}
             className={styles.inspector}
             aria-label={inspectorLabel}
+            data-open={inspectorOpen}
             aria-hidden={!inspectorOpen}
+            role={compact && inspectorOpen ? 'dialog' : undefined}
+            aria-modal={compact && inspectorOpen ? true : undefined}
             onKeyDown={(event) => {
               if (event.key === 'Escape') closeInspector(true);
             }}
diff --git a/webui/src/components/layout/ResponsivePane.module.css b/webui/src/components/layout/ResponsivePane.module.css
new file mode 100644
index 00000000..df5f3af9
--- /dev/null
+++ b/webui/src/components/layout/ResponsivePane.module.css
@@ -0,0 +1,79 @@
+.trigger,
+.close {
+  display: none;
+}
+.pane {
+  min-width: 0;
+  min-height: 0;
+  overflow: auto;
+  overscroll-behavior: contain;
+}
+.backdrop {
+  display: none;
+}
+
+@media (max-width: 1180px) {
+  .pane[data-open='true'] {
+    z-index: 42;
+  }
+}
+
+@media (max-width: 980px) {
+  .trigger {
+    display: inline-flex;
+    position: absolute;
+    z-index: 20;
+    top: var(--space-md);
+    left: var(--space-md);
+    min-height: 32px;
+    align-items: center;
+    padding: 0 var(--space-md);
+    border: 1px solid var(--border);
+    border-radius: var(--rounded-md);
+    background: var(--surface);
+    color: var(--brand);
+    font-weight: 700;
+    cursor: pointer;
+  }
+  .pane {
+    display: none;
+    position: absolute;
+    z-index: 42;
+    inset-block: 0;
+    width: min(340px, 88vw);
+    overflow: auto;
+    background: var(--surface);
+    box-shadow: var(--shadow-md);
+  }
+  .pane[data-open='true'] {
+    display: block;
+  }
+  .left {
+    left: 0;
+  }
+  .right {
+    right: 0;
+  }
+  .close {
+    display: flex;
+    min-height: 32px;
+    align-items: center;
+    margin: var(--space-md) var(--space-md) var(--space-sm) auto;
+    padding: 0 var(--space-md);
+    border: 1px solid var(--border);
+    border-radius: var(--rounded-md);
+    background: var(--surface);
+    color: var(--brand);
+    cursor: pointer;
+  }
+  .backdrop {
+    display: block;
+    position: absolute;
+    z-index: 41;
+    inset: 0;
+    width: 100%;
+    border: 0;
+    background: rgb(15 23 42 / 38%);
+    cursor: default;
+  }
+}
diff --git a/webui/src/components/layout/ResponsivePane.tsx b/webui/src/components/layout/ResponsivePane.tsx
new file mode 100644
index 00000000..c3cb58be
--- /dev/null
+++ b/webui/src/components/layout/ResponsivePane.tsx
@@ -0,0 +1,124 @@
+import { useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import styles from './ResponsivePane.module.css';
+
+type Props = {
+  label: string;
+  children: ReactNode;
+  className?: string;
+  side?: 'left' | 'right';
+  breakpoint?: 980 | 1180;
+  closeOnSelect?: boolean;
+  inert?: boolean;
+  'aria-hidden'?: boolean | 'true';
+};
+
+const focusable =
+  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export default function ResponsivePane({
+  label,
+  children,
+  className,
+  side = 'left',
+  breakpoint = 980,
+  closeOnSelect = false,
+  inert,
+  'aria-hidden': ariaHidden,
+}: Props) {
+  const id = useId();
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const paneRef = useRef<HTMLElement>(null);
+  const [compact, setCompact] = useState(false);
+  const [open, setOpen] = useState(false);
+
+  const close = (restoreFocus = true) => {
+    setOpen(false);
+    if (restoreFocus) triggerRef.current?.focus();
+  };
+
+  useEffect(() => {
+    const query = window.matchMedia?.(`(max-width: ${breakpoint}px)`);
+    if (!query) return;
+    const update = () => {
+      setCompact(query.matches);
+      if (!query.matches) setOpen(false);
+    };
+    update();
+    query.addEventListener?.('change', update);
+    return () => query.removeEventListener?.('change', update);
+  }, [breakpoint]);
+
+  useEffect(() => {
+    if (!compact || !open) return;
+    paneRef.current?.querySelector<HTMLElement>(focusable)?.focus();
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        close();
+        return;
+      }
+      if (event.key !== 'Tab') return;
+      const nodes = [...(paneRef.current?.querySelectorAll<HTMLElement>(focusable) ?? [])];
+      if (!nodes.length) return;
+      const first = nodes[0];
+      const last = nodes[nodes.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [compact, open]);
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        className={styles.trigger}
+        aria-controls={id}
+        aria-expanded={open}
+        onClick={() => setOpen(true)}
+      >
+        Open {label}
+      </button>
+      {open ? (
+        <button
+          type="button"
+          className={styles.backdrop}
+          aria-label={`Close ${label}`}
+          onClick={() => close()}
+        />
+      ) : null}
+      <aside
+        ref={paneRef}
+        id={id}
+        className={[styles.pane, styles[side], className].filter(Boolean).join(' ')}
+        data-open={open}
+        role={compact && open ? 'dialog' : undefined}
+        aria-modal={compact && open ? true : undefined}
+        aria-label={label}
+        aria-hidden={ariaHidden}
+        inert={inert}
+        onClickCapture={(event) => {
+          if (closeOnSelect && compact && (event.target as Element).closest('[role="option"]'))
+            close(false);
+        }}
+      >
+        <button
+          type="button"
+          className={styles.close}
+          aria-label={`Close ${label}`}
+          onClick={() => close()}
+        >
+          Close
+        </button>
+        {children}
+      </aside>
+    </>
+  );
+}
diff --git a/webui/src/pages/CharactersPage.module.css b/webui/src/pages/CharactersPage.module.css
index 6bfc66b0..f1156b82 100644
--- a/webui/src/pages/CharactersPage.module.css
+++ b/webui/src/pages/CharactersPage.module.css
@@ -3,23 +3,23 @@
   grid-template-columns: 260px minmax(420px, 1fr) 280px;
   height: 100%;
   min-height: 0;
-  background: #f7f9fc;
-  color: #17213b;
+  background: var(--surface-strong);
+  color: var(--ink);
 }
 .listPane,
 .contextPane {
   min-height: 0;
   overflow: auto;
-  background: #fff;
+  background: var(--surface);
 }
 .listPane {
   display: flex;
   flex-direction: column;
-  border-right: 1px solid #dfe6ef;
+  border-right: 1px solid var(--border);
 }
 .contextPane {
   padding: 16px;
-  border-left: 1px solid #dfe6ef;
+  border-left: 1px solid var(--border);
 }
 .detailPane {
   min-width: 0;
@@ -32,7 +32,7 @@
   padding: 16px;
 }
 .listPane header span {
-  color: #667085;
+  color: var(--muted);
   font-size: 11px;
   font-weight: 700;
   text-transform: uppercase;
@@ -46,10 +46,10 @@
   width: 32px;
   height: 32px;
   place-items: center;
-  border: 1px solid #d7dfeb;
+  border: 1px solid var(--border-strong);
   border-radius: 6px;
-  background: #fff;
-  color: #153981;
+  background: var(--surface);
+  color: var(--brand);
   cursor: pointer;
 }
 .refresh {
@@ -58,10 +58,10 @@
   gap: 6px;
   margin: 0 16px 10px;
   padding: 7px 9px;
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 6px;
-  background: #fff;
-  color: #536178;
+  background: var(--surface);
+  color: var(--muted-strong);
   cursor: pointer;
   font-size: 12px;
 }
@@ -73,10 +73,10 @@
   gap: 6px;
   margin: 0 16px 10px;
   padding: 9px;
-  border: 1px solid #f0d7a6;
+  border: 1px solid var(--amber-soft);
   border-radius: 6px;
-  background: #fff9eb;
-  color: #7a4d0b;
+  background: var(--amber-soft);
+  color: var(--amber);
   font-size: 12px;
 }
 .listWarning button {
@@ -84,7 +84,7 @@
   padding: 0;
   border: 0;
   background: transparent;
-  color: #153981;
+  color: var(--brand);
   cursor: pointer;
   font-weight: 700;
 }
@@ -104,14 +104,14 @@
   white-space: nowrap;
 }
 .listItem span {
-  color: #7a8699;
+  color: var(--muted);
   font-size: 11px;
 }
 .listPane footer {
   margin-top: auto;
   padding: 12px 16px;
-  border-top: 1px solid #edf0f4;
-  color: #7a8699;
+  border-top: 1px solid var(--surface-muted);
+  color: var(--muted);
   font-size: 12px;
 }
 .pick,
@@ -127,7 +127,7 @@
 .empty svg {
   width: 34px;
   height: 34px;
-  color: #153981;
+  color: var(--brand);
 }
 .pick h2,
 .empty h1 {
@@ -137,7 +137,7 @@
 .pick p,
 .empty p,
 .muted {
-  color: #7a8699;
+  color: var(--muted);
 }
 .empty button {
   display: flex;
@@ -147,14 +147,14 @@
   padding: 9px 13px;
   border: 0;
   border-radius: 6px;
-  background: #103687;
-  color: #fff;
+  background: var(--brand);
+  color: var(--surface);
   cursor: pointer;
 }
 .page {
   height: 100%;
   overflow: auto;
-  background: #f7f9fc;
+  background: var(--surface-strong);
 }
 .contextStack {
   display: grid;
@@ -162,7 +162,7 @@
 }
 .contextSection {
   padding: 14px;
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 8px;
 }
 .contextSection h2 {
@@ -171,7 +171,7 @@
 }
 .contextSection article {
   padding: 9px 0;
-  border-bottom: 1px solid #edf0f4;
+  border-bottom: 1px solid var(--surface-muted);
 }
 .contextSection article:last-child {
   border-bottom: 0;
@@ -181,28 +181,28 @@
   line-height: 1.45;
 }
 .contextSection small {
-  color: #7a8699;
+  color: var(--muted);
 }
 .contextError {
   display: grid;
   gap: 8px;
-  color: #9b3a25;
+  color: var(--ruby);
 }
 .contextError button {
   width: max-content;
   border: 0;
   background: transparent;
-  color: #153981;
+  color: var(--brand);
   cursor: pointer;
   font-weight: 700;
 }
 .deleteError {
   margin: 12px;
   padding: 10px;
-  border: 1px solid #efc8c2;
+  border: 1px solid var(--ruby-soft);
   border-radius: 6px;
-  background: #fff3f1;
-  color: #923a2d;
+  background: var(--ruby-soft);
+  color: var(--ruby);
 }
 .voiceMetrics {
   display: grid;
@@ -214,7 +214,7 @@
   justify-content: space-between;
 }
 .voiceMetrics dt {
-  color: #667085;
+  color: var(--muted);
 }
 .voiceMetrics dd {
   margin: 0;
@@ -229,8 +229,8 @@
 .voiceWords span {
   padding: 3px 6px;
   border-radius: 4px;
-  background: #edf2ff;
-  color: #153981;
+  background: var(--brand-wash);
+  color: var(--brand);
 }
 @media (max-width: 1050px) {
   .workspace {
@@ -240,7 +240,7 @@
   .contextPane {
     grid-column: 1 / -1;
     overflow: visible;
-    border-top: 1px solid #dfe6ef;
+    border-top: 1px solid var(--border);
     border-left: 0;
   }
 }
@@ -251,6 +251,6 @@
   .listPane {
     max-height: 42%;
     border-right: 0;
-    border-bottom: 1px solid #dfe6ef;
+    border-bottom: 1px solid var(--border);
   }
 }
diff --git a/webui/src/pages/CharactersPage.tsx b/webui/src/pages/CharactersPage.tsx
index e4eac437..8f0baa99 100644
--- a/webui/src/pages/CharactersPage.tsx
+++ b/webui/src/pages/CharactersPage.tsx
@@ -13,6 +13,7 @@ import AgentCardView from '../components/Inspector/AgentCardView';
 import CreateAgentModal from '../components/Inspector/CreateAgentModal';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
+import ResponsivePane from '../components/layout/ResponsivePane';
 import { useResource } from '../hooks/useResource';
 import styles from './CharactersPage.module.css';
 
@@ -101,7 +102,7 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
 
   return (
     <main className={styles.workspace}>
-      <aside className={styles.listPane}>
+      <ResponsivePane label="Characters" className={styles.listPane} closeOnSelect>
         <header>
           <div>
             <span>World cast</span>
@@ -132,7 +133,7 @@ export default function CharactersPage({ worldId }: CharactersPageProps) {
         <footer>
           {items.length} {items.length === 1 ? 'character' : 'characters'}
         </footer>
-      </aside>
+      </ResponsivePane>
 
       <section className={styles.detailPane}>
         {deleteError ? (
diff --git a/webui/src/pages/FilesPage.module.css b/webui/src/pages/FilesPage.module.css
index 464fa393..bac82cff 100644
--- a/webui/src/pages/FilesPage.module.css
+++ b/webui/src/pages/FilesPage.module.css
@@ -64,10 +64,10 @@
 
 .success {
   padding: 8px 10px;
-  border: 1px solid #bbf7d0;
+  border: 1px solid var(--green-soft);
   border-radius: var(--rounded-md);
   background: var(--green-soft);
-  color: #166534;
+  color: var(--green);
 }
 .conflict {
   display: flex;
diff --git a/webui/src/pages/FilesPage.tsx b/webui/src/pages/FilesPage.tsx
index c5d46b2d..b78a4fda 100644
--- a/webui/src/pages/FilesPage.tsx
+++ b/webui/src/pages/FilesPage.tsx
@@ -5,6 +5,7 @@ import type { WorkspaceFile, WorkspaceFileContent, WorldFileLinkRecord } from '.
 import DetailPane from '../components/layout/DetailPane';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
+import ResponsivePane from '../components/layout/ResponsivePane';
 import styles from './FilesPage.module.css';
 
 type Props = { worldId: string };
@@ -59,6 +60,12 @@ export default function FilesPage({ worldId }: Props) {
   const openRootToken = useRef(0);
   const revealToken = useRef(0);
 
+  function invalidateReveal() {
+    revealToken.current += 1;
+    setRevealingPath(null);
+    setRevealMessage(null);
+  }
+
   const loadList = useCallback(async () => {
     if (savingRef.current) return;
     const life = lifecycle.current;
@@ -90,8 +97,7 @@ export default function FilesPage({ worldId }: Props) {
     setSaving(false);
     openingRootRef.current = false;
     setOpeningRoot(false);
-    setRevealingPath(null);
-    setRevealMessage(null);
+    invalidateReveal();
     setConflict(false);
     setLinks({ status: 'loading', items: [] });
     loadList();
@@ -112,6 +118,7 @@ export default function FilesPage({ worldId }: Props) {
       });
     return () => {
       lifecycle.current += 1;
+      revealToken.current += 1;
       savingRef.current = false;
     };
   }, [loadList, worldId]);
@@ -129,6 +136,7 @@ export default function FilesPage({ worldId }: Props) {
 
   async function selectFile(path: string) {
     if (savingRef.current) return;
+    invalidateReveal();
     const life = lifecycle.current;
     const token = ++readToken.current;
     setSelectedPath(path);
@@ -241,7 +249,7 @@ export default function FilesPage({ worldId }: Props) {
     return <PageState error={new Error(listError)} onRetry={loadList} />;
   return (
     <div className={styles.page}>
-      <aside className={styles.library} aria-label="File library">
+      <ResponsivePane label="File library" className={styles.library} closeOnSelect>
         <header>
           <h1>Files</h1>
           <button type="button" aria-label="Refresh files" disabled={saving} onClick={loadList}>
@@ -296,7 +304,7 @@ export default function FilesPage({ worldId }: Props) {
         ) : (
           <p>No files in this view.</p>
         )}
-      </aside>
+      </ResponsivePane>
       {selected && loaded ? (
         <DetailPane
           title={selected.name}
diff --git a/webui/src/pages/ForeshadowingPage.tsx b/webui/src/pages/ForeshadowingPage.tsx
index a5fc7f4f..146a8c31 100644
--- a/webui/src/pages/ForeshadowingPage.tsx
+++ b/webui/src/pages/ForeshadowingPage.tsx
@@ -5,6 +5,7 @@ import type { ForeshadowingItem, StoryChapter, StoryScene } from '../api/types';
 import CreateForeshadowingModal from '../components/Inspector/CreateForeshadowingModal';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
+import ResponsivePane from '../components/layout/ResponsivePane';
 import { useResource } from '../hooks/useResource';
 import styles from './ForeshadowingPage.module.css';
 
@@ -15,41 +16,25 @@ type Data = {
   contextError: string | null;
 };
 
-export function deriveForeshadowingStatus(positions: {
-  status?: string;
-  plannedPosition: number | null;
-  currentPosition: number | null;
-}): 'overdue' | null {
-  if (
-    positions.status !== 'open' ||
-    positions.plannedPosition === null ||
-    positions.currentPosition === null
-  )
-    return null;
+export function deriveForeshadowingStatus(
+  positions: { status?: string; plannedPosition: number | null; currentPosition: number | null },
+): 'overdue' | null {
+  if (positions.status !== 'open' || positions.plannedPosition === null || positions.currentPosition === null) return null;
   return positions.currentPosition > positions.plannedPosition ? 'overdue' : null;
 }
 
 export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const resource = useResource(`foreshadowing:${worldId}`, async () => {
     const [foreshadowing, chapters, scenes] = await Promise.allSettled([
-      api.listForeshadowing(worldId),
-      api.listChapters(worldId),
-      api.listScenes(worldId),
+      api.listForeshadowing(worldId), api.listChapters(worldId), api.listScenes(worldId),
     ]);
     if (foreshadowing.status === 'rejected') throw foreshadowing.reason;
-    const failures = [chapters, scenes].filter(
-      (result) => result.status === 'rejected',
-    ) as PromiseRejectedResult[];
+    const failures = [chapters, scenes].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
     return {
       items: foreshadowing.value.foreshadowing ?? foreshadowing.value.items ?? [],
       chapters: chapters.status === 'fulfilled' ? chapters.value.chapters : [],
       scenes: scenes.status === 'fulfilled' ? scenes.value.scenes : [],
-      contextError:
-        failures
-          .map((result) =>
-            result.reason instanceof Error ? result.reason.message : String(result.reason),
-          )
-          .join(' ') || null,
+      contextError: failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') || null,
     };
   });
   const [selectedId, setSelectedId] = useState<string | null>(null);
@@ -65,311 +50,82 @@ export default function ForeshadowingPage({ worldId }: { worldId: string }) {
   const committedWorldRef = useRef(worldId);
   const mountedRef = useRef(false);
   const data: Data | null = resource.data;
-  const items = useMemo(
-    () => (data?.items ?? []).filter((item) => !removed.includes(item.id)),
-    [data, removed],
-  );
+  const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
-  useEffect(() => {
-    setSelectedId(null);
-    setRemoved([]);
-    setEditing(false);
-    setCreateOpen(false);
-    setPendingMutation(null);
-    pendingMutationRef.current = false;
-    setMutationError(null);
-  }, [worldId]);
+  useEffect(() => { setSelectedId(null); setRemoved([]); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
   useEffect(() => {
     mountedRef.current = true;
     if (committedWorldRef.current !== worldId) {
       committedWorldRef.current = worldId;
       generationRef.current += 1;
     }
-    return () => {
-      mountedRef.current = false;
-      generationRef.current += 1;
-    };
+    return () => { mountedRef.current = false; generationRef.current += 1; };
   }, [worldId]);
   useEffect(() => {
-    if (selectedId && !filtered.some((item) => item.id === selectedId))
-      setSelectedId(filtered[0]?.id ?? null);
+    if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null);
   }, [filtered, selectedId]);
-  useEffect(() => {
-    setPayoff(selected?.pay_off_idea ?? '');
-    setEditing(false);
-  }, [selected?.id]);
+  useEffect(() => { setPayoff(selected?.pay_off_idea ?? ''); setEditing(false); }, [selected?.id]);
 
   async function save() {
-    if (
-      !selected ||
-      pendingMutationRef.current ||
-      !window.confirm('Update this foreshadowing item?')
-    )
-      return;
+    if (!selected || pendingMutationRef.current || !window.confirm('Update this foreshadowing item?')) return;
     const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('update');
     setMutationError(null);
-    try {
-      await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff });
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        setEditing(false);
-        resource.retry();
-      }
-    } catch (error) {
-      if (mountedRef.current && generationRef.current === operationGeneration)
-        setMutationError((error as Error).message);
-    } finally {
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        pendingMutationRef.current = false;
-        setPendingMutation(null);
-      }
-    }
+    try { await api.patchForeshadow(operationWorld, selected.id, { pay_off_idea: payoff }); if (mountedRef.current && generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
 
   async function remove() {
-    if (
-      !selected ||
-      pendingMutationRef.current ||
-      !window.confirm('Delete this foreshadowing item?')
-    )
-      return;
+    if (!selected || pendingMutationRef.current || !window.confirm('Delete this foreshadowing item?')) return;
     setMutationError(null);
     const id = selected.id;
     const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
     setPendingMutation('delete');
-    try {
-      await api.deleteForeshadowing(operationWorld, id);
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        setRemoved((ids) => [...ids, id]);
-        setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null);
-        resource.retry();
-      }
-    } catch (error) {
-      if (mountedRef.current && generationRef.current === operationGeneration)
-        setMutationError((error as Error).message);
-    } finally {
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        pendingMutationRef.current = false;
-        setPendingMutation(null);
-      }
-    }
+    try { await api.deleteForeshadowing(operationWorld, id); if (mountedRef.current && generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
 
   function changeFilter(nextFilter: string) {
     setFilter(nextFilter);
-    const visible =
-      nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
+    const visible = nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
     setSelectedId(visible[0]?.id ?? null);
   }
 
-  if (!data)
-    return (
-      <PageState
-        loading={resource.status === 'loading'}
-        loadingLabel="Loading foreshadowing"
-        error={resource.error}
-        onRetry={resource.retry}
-      />
-    );
+  if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading foreshadowing" error={resource.error} onRetry={resource.retry} />;
   return (
     <main className={styles.workspace}>
-      <aside className={styles.listPane}>
-        <header>
-          <div>
-            <span>Narrative threads</span>
-            <h1>Foreshadowing</h1>
-          </div>
-          <div className={styles.tools}>
-            <button aria-label="Refresh foreshadowing" onClick={resource.retry}>
-              <RefreshCw />
-            </button>
-            <button
-              aria-label="Create foreshadowing"
-              disabled={Boolean(pendingMutation)}
-              onClick={() => setCreateOpen(true)}
-            >
-              <Plus />
-            </button>
-          </div>
-        </header>
-        <label className={styles.filter}>
-          <Filter />
-          <span>Status</span>
-          <select value={filter} onChange={(event) => changeFilter(event.target.value)}>
-            <option value="all">All</option>
-            <option value="open">Open</option>
-            <option value="paid">Paid</option>
-            <option value="abandoned">Abandoned</option>
-          </select>
-        </label>
-        {(resource.error || mutationError || data.contextError) && (
-          <div role="alert" className={styles.warning}>
-            {mutationError ?? resource.error?.message ?? data.contextError}
-          </div>
-        )}
-        {filtered.length ? (
-          <ResourceList
-            items={filtered}
-            selectedId={selectedId}
-            getId={(item) => item.id}
-            onSelect={setSelectedId}
-            ariaLabel="Foreshadowing"
-            renderItem={(item) => (
-              <div className={styles.listItem}>
-                <Sparkles />
-                <div>
-                  <strong>{item.content}</strong>
-                  <span>{item.status ?? 'No status'}</span>
-                </div>
-              </div>
-            )}
-          />
-        ) : (
-          <p className={styles.empty}>No foreshadowing matches this filter.</p>
-        )}
-        <footer>
-          {filtered.length} {filtered.length === 1 ? 'thread' : 'threads'}
-        </footer>
-      </aside>
+      <ResponsivePane label="Foreshadowing" className={styles.listPane} closeOnSelect>
+        <header><div><span>Narrative threads</span><h1>Foreshadowing</h1></div><div className={styles.tools}><button aria-label="Refresh foreshadowing" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create foreshadowing" disabled={Boolean(pendingMutation)} onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
+        <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => changeFilter(event.target.value)}><option value="all">All</option><option value="open">Open</option><option value="paid">Paid</option><option value="abandoned">Abandoned</option></select></label>
+        {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
+        {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Foreshadowing" renderItem={(item) => <div className={styles.listItem}><Sparkles /><div><strong>{item.content}</strong><span>{item.status ?? 'No status'}</span></div></div>} /> : <p className={styles.empty}>No foreshadowing matches this filter.</p>}
+        <footer>{filtered.length} {filtered.length === 1 ? 'thread' : 'threads'}</footer>
+      </ResponsivePane>
       <section className={styles.detail} aria-label="Foreshadowing detail">
-        {selected ? (
-          <>
-            <header className={styles.detailHeader}>
-              <div>
-                <span>Thread detail</span>
-                <h2>{selected.content}</h2>
-              </div>
-              <div className={styles.actions}>
-                <button
-                  aria-label="Edit foreshadowing"
-                  disabled={Boolean(pendingMutation)}
-                  onClick={() => setEditing(true)}
-                >
-                  <Pencil /> Edit
-                </button>
-                <button
-                  aria-label="Delete foreshadowing"
-                  disabled={Boolean(pendingMutation)}
-                  onClick={remove}
-                >
-                  <Trash2 /> Delete
-                </button>
-              </div>
-            </header>
-            <div className={styles.cards}>
-              <Fact label="Status" value={selected.status} />
-              <Fact label="Hint level" value={selected.hint_level} />
-              <Fact label="Planted at" value={selected.planted_at} />
-              <Fact label="Paid at" value={selected.paid_at} />
-            </div>
-            <section className={styles.block}>
-              <h3>Payoff idea</h3>
-              {editing ? (
-                <>
-                  <textarea
-                    aria-label="Payoff idea"
-                    disabled={Boolean(pendingMutation)}
-                    value={payoff}
-                    onChange={(event) => setPayoff(event.target.value)}
-                  />
-                  <button
-                    className={styles.primary}
-                    disabled={Boolean(pendingMutation)}
-                    onClick={save}
-                  >
-                    Save changes
-                  </button>
-                </>
-              ) : (
-                <p>{selected.pay_off_idea || 'No payoff idea recorded.'}</p>
-              )}
-            </section>
-            {selected.tags?.length ? (
-              <section className={styles.block}>
-                <h3>Tags</h3>
-                <div className={styles.chips}>
-                  {selected.tags.map((tag) => (
-                    <span key={tag}>{tag}</span>
-                  ))}
-                </div>
-              </section>
-            ) : null}
-          </>
-        ) : (
-          <Pick
-            icon={<Sparkles />}
-            title="Select foreshadowing"
-            text="Choose a thread to inspect its recorded details."
-          />
-        )}
+        {selected ? <><header className={styles.detailHeader}><div><span>Thread detail</span><h2>{selected.content}</h2></div><div className={styles.actions}><button aria-label="Edit foreshadowing" disabled={Boolean(pendingMutation)} onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete foreshadowing" disabled={Boolean(pendingMutation)} onClick={remove}><Trash2 /> Delete</button></div></header>
+          <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Hint level" value={selected.hint_level} /><Fact label="Planted at" value={selected.planted_at} /><Fact label="Paid at" value={selected.paid_at} /></div>
+          <section className={styles.block}><h3>Payoff idea</h3>{editing ? <><textarea aria-label="Payoff idea" disabled={Boolean(pendingMutation)} value={payoff} onChange={(event) => setPayoff(event.target.value)} /><button className={styles.primary} disabled={Boolean(pendingMutation)} onClick={save}>Save changes</button></> : <p>{selected.pay_off_idea || 'No payoff idea recorded.'}</p>}</section>
+          {selected.tags?.length ? <section className={styles.block}><h3>Tags</h3><div className={styles.chips}>{selected.tags.map((tag) => <span key={tag}>{tag}</span>)}</div></section> : null}
+        </> : <Pick icon={<Sparkles />} title="Select foreshadowing" text="Choose a thread to inspect its recorded details." />}
       </section>
-      <aside className={styles.contextPane}>
-        <h2>Real context</h2>
-        {selected ? (
-          <ForeshadowingContext item={selected} data={data} />
-        ) : (
-          <p>Select a thread to see resolved narrative positions.</p>
-        )}
-      </aside>
-      {createOpen ? (
-        <CreateForeshadowingModal
-          worldId={worldId}
-          onClose={() => setCreateOpen(false)}
-          onCreated={resource.retry}
-        />
-      ) : null}
+      <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <ForeshadowingContext item={selected} data={data} /> : <p>Select a thread to see resolved narrative positions.</p>}</aside>
+      {createOpen ? <CreateForeshadowingModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
     </main>
   );
 }
 
-function Fact({ label, value }: { label: string; value?: string }) {
-  return (
-    <div className={styles.fact}>
-      <span>{label}</span>
-      <strong>{value || 'Not set'}</strong>
-    </div>
-  );
-}
-function Pick({ icon, title, text }: { icon: React.ReactNode; title: string; text: string }) {
-  return (
-    <div className={styles.pick}>
-      {icon}
-      <h2>{title}</h2>
-      <p>{text}</p>
-    </div>
-  );
-}
+function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
+function Pick({ icon, title, text }: { icon: React.ReactNode; title: string; text: string }) { return <div className={styles.pick}>{icon}<h2>{title}</h2><p>{text}</p></div>; }
 function ForeshadowingContext({ item, data }: { item: ForeshadowingItem; data: Data }) {
-  const resolve = (type: 'planted' | 'paid', id?: string) => {
-    if (!id) return null;
-    const label =
-      data.scenes.find((scene) => scene.id === id)?.title ??
-      data.chapters.find((chapter) => chapter.id === id)?.title;
-    return label ? { type, id, label } : null;
-  };
-  const positions = [resolve('planted', item.planted_at), resolve('paid', item.paid_at)].filter(
-    Boolean,
-  ) as { type: 'planted' | 'paid'; id: string; label: string }[];
-  return (
-    <div className={styles.context}>
-      {positions.length ? (
-        <div>
-          <h3>Narrative positions</h3>
-          <div className={styles.chips}>
-            {positions.map((position) => (
-              <span key={`${position.type}:${position.id}`}>{position.label}</span>
-            ))}
-          </div>
-        </div>
-      ) : (
-        <p>No resolvable narrative positions recorded.</p>
-      )}
-    </div>
-  );
+  const resolve = (type: 'planted' | 'paid', id?: string) => ({ type, id: id ?? '', label: data.scenes.find((scene) => scene.id === id)?.title ?? data.chapters.find((chapter) => chapter.id === id)?.title });
+  const positions = [resolve('planted', item.planted_at), resolve('paid', item.paid_at)].filter((position) => position.id && position.label);
+  return <div className={styles.context}>{positions.length ? <div><h3>Narrative positions</h3><div className={styles.chips}>{positions.map((position) => <span key={`${position.type}:${position.id}`}>{position.label}</span>)}</div></div> : <p>No resolvable narrative positions recorded.</p>}</div>;
 }
diff --git a/webui/src/pages/OverviewPage.module.css b/webui/src/pages/OverviewPage.module.css
index bfe463c1..262bc954 100644
--- a/webui/src/pages/OverviewPage.module.css
+++ b/webui/src/pages/OverviewPage.module.css
@@ -3,16 +3,16 @@
   min-height: 0;
   overflow: auto;
   padding: 20px;
-  background: #f7f9fc;
+  background: var(--surface-strong);
 }
 
 .notice {
   margin-bottom: 12px;
   padding: 9px 12px;
-  border: 1px solid #f0d7a6;
+  border: 1px solid var(--amber-soft);
   border-radius: 7px;
-  background: #fff9eb;
-  color: #7a4d0b;
+  background: var(--amber-soft);
+  color: var(--amber);
 }
 
 .metrics {
@@ -25,9 +25,9 @@
 .metricCard,
 .panel,
 .empty {
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 9px;
-  background: #fff;
+  background: var(--surface);
   box-shadow: 0 1px 2px rgba(16, 24, 40, 0.025);
 }
 
@@ -37,7 +37,7 @@
   align-items: flex-start;
   justify-content: space-between;
   padding: 18px;
-  color: #0b2d80;
+  color: var(--brand);
 }
 
 .metricCard div {
@@ -46,17 +46,17 @@
   flex-direction: column;
 }
 .metricCard span {
-  color: #344054;
+  color: var(--ink-soft);
   font-weight: 650;
 }
 .metricCard strong {
   margin: 8px 0 4px;
-  color: #102f7c;
+  color: var(--brand);
   font-size: 28px;
   line-height: 1;
 }
 .metricCard small {
-  color: #7a8699;
+  color: var(--muted);
   font-size: 10px;
   line-height: 1.35;
 }
@@ -78,13 +78,13 @@
   margin-bottom: 14px;
 }
 .panel h2 {
-  color: #17213b;
+  color: var(--ink);
   font-size: 15px;
 }
 .panel header button {
   border: 0;
   background: transparent;
-  color: #0b3b96;
+  color: var(--brand);
   cursor: pointer;
   font-weight: 650;
 }
@@ -98,9 +98,9 @@
   align-items: center;
   gap: 12px;
   padding: 12px;
-  border: 1px solid #e4e9f1;
+  border: 1px solid var(--border);
   border-radius: 7px;
-  color: #14398b;
+  color: var(--brand);
 }
 .session div {
   display: flex;
@@ -110,13 +110,13 @@
 }
 .session strong {
   overflow: hidden;
-  color: #1d2939;
+  color: var(--ink);
   text-overflow: ellipsis;
   white-space: nowrap;
 }
 .session span,
 .muted {
-  color: #7a8699;
+  color: var(--muted);
 }
 
 .progressRow {
@@ -125,23 +125,23 @@
 .progressRow > div:first-child {
   display: flex;
   justify-content: space-between;
-  color: #263653;
+  color: var(--ink-soft);
 }
 .progressRow small {
-  color: #7a8699;
+  color: var(--muted);
 }
 .track {
   height: 6px;
   margin: 8px 0 6px;
   overflow: hidden;
   border-radius: 999px;
-  background: #e8edf5;
+  background: var(--surface-muted);
 }
 .track span {
   display: block;
   height: 100%;
   border-radius: inherit;
-  background: #0b3287;
+  background: var(--brand);
 }
 
 .reminder {
@@ -151,9 +151,9 @@
   gap: 10px;
   padding: 11px 4px;
   border: 0;
-  border-bottom: 1px solid #edf0f4;
+  border-bottom: 1px solid var(--surface-muted);
   background: transparent;
-  color: #a46b08;
+  color: var(--amber);
   cursor: pointer;
   text-align: left;
 }
@@ -163,10 +163,10 @@
   gap: 3px;
 }
 .reminder strong {
-  color: #263653;
+  color: var(--ink-soft);
 }
 .reminder small {
-  color: #7a8699;
+  color: var(--muted);
 }
 
 .quickLinks {
@@ -180,10 +180,10 @@
   align-items: center;
   justify-content: center;
   gap: 9px;
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 7px;
-  background: #fff;
-  color: #153981;
+  background: var(--surface);
+  color: var(--brand);
   cursor: pointer;
   font-weight: 700;
 }
@@ -196,15 +196,15 @@
   margin: 12vh auto 0;
   padding: 48px;
   text-align: center;
-  color: #153981;
+  color: var(--brand);
 }
 .empty h1 {
   margin: 14px 0 8px;
-  color: #17213b;
+  color: var(--ink);
   font-size: 22px;
 }
 .empty p {
-  color: #667085;
+  color: var(--muted);
 }
 .emptyActions {
   display: flex;
@@ -214,10 +214,10 @@
 }
 .emptyActions button {
   padding: 9px 14px;
-  border: 1px solid #cfd8e6;
+  border: 1px solid var(--border-strong);
   border-radius: 6px;
-  background: #fff;
-  color: #14398b;
+  background: var(--surface);
+  color: var(--brand);
   cursor: pointer;
   font-weight: 700;
 }
diff --git a/webui/src/pages/ScenesPage.tsx b/webui/src/pages/ScenesPage.tsx
index b90e815c..056570f9 100644
--- a/webui/src/pages/ScenesPage.tsx
+++ b/webui/src/pages/ScenesPage.tsx
@@ -5,6 +5,7 @@ import type { EndSceneResponse, StoryScene } from '../api/types';
 import EndSceneModal from '../components/Inspector/EndSceneModal';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
+import ResponsivePane from '../components/layout/ResponsivePane';
 import { useResource } from '../hooks/useResource';
 import styles from './ScenesPage.module.css';
 
@@ -44,7 +45,9 @@ export default function ScenesPage({ worldId }: { worldId: string }) {
 
   return (
     <main className={styles.workspace}>
-      <aside
+      <ResponsivePane
+        label="Scenes"
+        closeOnSelect
         className={styles.listPane}
         aria-hidden={endTarget ? 'true' : undefined}
         inert={endTarget ? true : undefined}
@@ -76,7 +79,7 @@ export default function ScenesPage({ worldId }: { worldId: string }) {
         <footer>
           {scenes.length} {scenes.length === 1 ? 'scene' : 'scenes'}
         </footer>
-      </aside>
+      </ResponsivePane>
       <section
         className={styles.detail}
         aria-label="Scene detail"
diff --git a/webui/src/pages/SecretsPage.tsx b/webui/src/pages/SecretsPage.tsx
index 493696d0..5c24e8d1 100644
--- a/webui/src/pages/SecretsPage.tsx
+++ b/webui/src/pages/SecretsPage.tsx
@@ -5,6 +5,7 @@ import type { SecretItem, WorldAgent } from '../api/types';
 import CreateSecretModal from '../components/Inspector/CreateSecretModal';
 import PageState from '../components/layout/PageState';
 import ResourceList from '../components/layout/ResourceList';
+import ResponsivePane from '../components/layout/ResponsivePane';
 import { useResource } from '../hooks/useResource';
 import styles from './SecretsPage.module.css';
 
@@ -12,18 +13,31 @@ type Data = { items: SecretItem[]; agents: WorldAgent[]; contextError: string |
 
 export default function SecretsPage({ worldId }: { worldId: string }) {
   const resource = useResource(`secrets:${worldId}`, async () => {
-    const [secrets, agents] = await Promise.allSettled([api.listSecrets(worldId), api.listAgents(worldId)]);
+    const [secrets, agents] = await Promise.allSettled([
+      api.listSecrets(worldId),
+      api.listAgents(worldId),
+    ]);
     if (secrets.status === 'rejected') throw secrets.reason;
-    const failures = [agents].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
+    const failures = [agents].filter(
+      (result) => result.status === 'rejected',
+    ) as PromiseRejectedResult[];
     return {
       items: secrets.value.secrets ?? secrets.value.items ?? [],
       agents: agents.status === 'fulfilled' ? agents.value.agents : [],
-      contextError: failures.length ? failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') : null,
+      contextError: failures.length
+        ? failures
+            .map((result) =>
+              result.reason instanceof Error ? result.reason.message : String(result.reason),
+            )
+            .join(' ')
+        : null,
     };
   });
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [filter, setFilter] = useState('all');
-  const [revealedTruth, setRevealedTruth] = useState<{ secretId: string; truth: string } | null>(null);
+  const [revealedTruth, setRevealedTruth] = useState<{ secretId: string; truth: string } | null>(
+    null,
+  );
   const [createOpen, setCreateOpen] = useState(false);
   const [editing, setEditing] = useState(false);
   const [publicVersion, setPublicVersion] = useState('');
@@ -35,70 +49,318 @@ export default function SecretsPage({ worldId }: { worldId: string }) {
   const committedWorldRef = useRef(worldId);
   const mountedRef = useRef(false);
   const data: Data | null = resource.data;
-  const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
+  const items = useMemo(
+    () => (data?.items ?? []).filter((item) => !removed.includes(item.id)),
+    [data, removed],
+  );
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
-  useEffect(() => { setSelectedId(null); setRemoved([]); setRevealedTruth(null); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
+  useEffect(() => {
+    setSelectedId(null);
+    setRemoved([]);
+    setRevealedTruth(null);
+    setEditing(false);
+    setCreateOpen(false);
+    setPendingMutation(null);
+    pendingMutationRef.current = false;
+    setMutationError(null);
+  }, [worldId]);
   useEffect(() => {
     mountedRef.current = true;
     if (committedWorldRef.current !== worldId) {
       committedWorldRef.current = worldId;
       generationRef.current += 1;
     }
-    return () => { mountedRef.current = false; generationRef.current += 1; };
+    return () => {
+      mountedRef.current = false;
+      generationRef.current += 1;
+    };
   }, [worldId]);
-  useEffect(() => { setRevealedTruth(null); setEditing(false); setPublicVersion(selected?.public_version ?? ''); }, [selected?.id]);
-  useEffect(() => { if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null); }, [filtered, selectedId]);
+  useEffect(() => {
+    setRevealedTruth(null);
+    setEditing(false);
+    setPublicVersion(selected?.public_version ?? '');
+  }, [selected?.id]);
+  useEffect(() => {
+    if (selectedId && !filtered.some((item) => item.id === selectedId))
+      setSelectedId(filtered[0]?.id ?? null);
+  }, [filtered, selectedId]);
 
   async function save() {
     if (!selected || pendingMutationRef.current || !window.confirm('Update this secret?')) return;
     const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
-    setPendingMutation('update'); setMutationError(null);
-    try { await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion }); if (mountedRef.current && generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
-    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    setPendingMutation('update');
+    setMutationError(null);
+    try {
+      await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion });
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        setEditing(false);
+        resource.retry();
+      }
+    } catch (error) {
+      if (mountedRef.current && generationRef.current === operationGeneration)
+        setMutationError((error as Error).message);
+    } finally {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        pendingMutationRef.current = false;
+        setPendingMutation(null);
+      }
+    }
   }
   async function remove() {
     if (!selected || pendingMutationRef.current || !window.confirm('Delete this secret?')) return;
-    const operationWorld = worldId; const id = selected.id;
+    const operationWorld = worldId;
+    const id = selected.id;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
-    setPendingMutation('delete'); setMutationError(null);
-    try { await api.deleteSecret(operationWorld, id); if (mountedRef.current && generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } }
-    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
-    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
+    setPendingMutation('delete');
+    setMutationError(null);
+    try {
+      await api.deleteSecret(operationWorld, id);
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        setRemoved((ids) => [...ids, id]);
+        setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null);
+        setRevealedTruth(null);
+        resource.retry();
+      }
+    } catch (error) {
+      if (mountedRef.current && generationRef.current === operationGeneration)
+        setMutationError((error as Error).message);
+    } finally {
+      if (mountedRef.current && generationRef.current === operationGeneration) {
+        pendingMutationRef.current = false;
+        setPendingMutation(null);
+      }
+    }
   }
   function changeFilter(nextFilter: string) {
     setFilter(nextFilter);
-    const visible = nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
+    const visible =
+      nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
     setSelectedId(visible[0]?.id ?? null);
     setRevealedTruth(null);
   }
 
-  if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading secrets" error={resource.error} onRetry={resource.retry} />;
-  return <main className={styles.workspace}>
-    <aside className={styles.listPane}><header><div><span>Knowledge boundaries</span><h1>Secrets</h1></div><div className={styles.tools}><button aria-label="Refresh secrets" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create secret" disabled={Boolean(pendingMutation)} onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
-      <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => changeFilter(event.target.value)}><option value="all">All</option><option value="active">Active</option><option value="exposed">Exposed</option><option value="abandoned">Abandoned</option></select></label>
-      {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
-      {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Secrets" renderItem={(item) => <div className={styles.listItem}><KeyRound /><div><strong>{item.title || item.public_version || 'Untitled secret'}</strong><span>{item.status ?? 'No status'}</span></div></div>} /> : <p className={styles.empty}>No secrets match this filter.</p>}
-      <footer>{filtered.length} {filtered.length === 1 ? 'secret' : 'secrets'}</footer></aside>
-    <section className={styles.detail} aria-label="Secret detail">{selected ? <><header className={styles.detailHeader}><div><span>Secret detail</span><h2>{selected.title || selected.public_version || 'Untitled secret'}</h2></div><div className={styles.actions}><button aria-label="Edit secret" disabled={Boolean(pendingMutation)} onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete secret" disabled={Boolean(pendingMutation)} onClick={remove}><Trash2 /> Delete</button></div></header>
-      <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Stakes" value={selected.stakes} /></div>
-      <section className={styles.block}><h3>Public version</h3>{editing ? <><textarea aria-label="Public version" disabled={Boolean(pendingMutation)} value={publicVersion} onChange={(event) => setPublicVersion(event.target.value)} /><button className={styles.primary} disabled={Boolean(pendingMutation)} onClick={save}>Save changes</button></> : <p>{selected.public_version || 'No public version recorded.'}</p>}</section>
-      <section className={styles.truth}><h3>Truth</h3>{revealedTruth?.secretId === selected.id ? <p>{revealedTruth.truth || 'No truth recorded.'}</p> : <div><KeyRound /><p>Hidden until you explicitly reveal it.</p><button aria-label="Reveal truth" onClick={() => setRevealedTruth({ secretId: selected.id, truth: selected.truth ?? selected.content ?? '' })}><Eye /> Reveal truth</button></div>}</section>
-    </> : <div className={styles.pick}><KeyRound /><h2>Select a secret</h2><p>Choose a secret to inspect its public details.</p></div>}</section>
-    <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <Context item={selected} data={data} /> : <p>Select a secret to see resolved relationships.</p>}</aside>
-    {createOpen ? <CreateSecretModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
-  </main>;
+  if (!data)
+    return (
+      <PageState
+        loading={resource.status === 'loading'}
+        loadingLabel="Loading secrets"
+        error={resource.error}
+        onRetry={resource.retry}
+      />
+    );
+  return (
+    <main className={styles.workspace}>
+      <ResponsivePane label="Secrets" className={styles.listPane} closeOnSelect>
+        <header>
+          <div>
+            <span>Knowledge boundaries</span>
+            <h1>Secrets</h1>
+          </div>
+          <div className={styles.tools}>
+            <button aria-label="Refresh secrets" onClick={resource.retry}>
+              <RefreshCw />
+            </button>
+            <button
+              aria-label="Create secret"
+              disabled={Boolean(pendingMutation)}
+              onClick={() => setCreateOpen(true)}
+            >
+              <Plus />
+            </button>
+          </div>
+        </header>
+        <label className={styles.filter}>
+          <Filter />
+          <span>Status</span>
+          <select value={filter} onChange={(event) => changeFilter(event.target.value)}>
+            <option value="all">All</option>
+            <option value="active">Active</option>
+            <option value="exposed">Exposed</option>
+            <option value="abandoned">Abandoned</option>
+          </select>
+        </label>
+        {(resource.error || mutationError || data.contextError) && (
+          <div role="alert" className={styles.warning}>
+            {mutationError ?? resource.error?.message ?? data.contextError}
+          </div>
+        )}
+        {filtered.length ? (
+          <ResourceList
+            items={filtered}
+            selectedId={selectedId}
+            getId={(item) => item.id}
+            onSelect={setSelectedId}
+            ariaLabel="Secrets"
+            renderItem={(item) => (
+              <div className={styles.listItem}>
+                <KeyRound />
+                <div>
+                  <strong>{item.title || item.public_version || 'Untitled secret'}</strong>
+                  <span>{item.status ?? 'No status'}</span>
+                </div>
+              </div>
+            )}
+          />
+        ) : (
+          <p className={styles.empty}>No secrets match this filter.</p>
+        )}
+        <footer>
+          {filtered.length} {filtered.length === 1 ? 'secret' : 'secrets'}
+        </footer>
+      </ResponsivePane>
+      <section className={styles.detail} aria-label="Secret detail">
+        {selected ? (
+          <>
+            <header className={styles.detailHeader}>
+              <div>
+                <span>Secret detail</span>
+                <h2>{selected.title || selected.public_version || 'Untitled secret'}</h2>
+              </div>
+              <div className={styles.actions}>
+                <button
+                  aria-label="Edit secret"
+                  disabled={Boolean(pendingMutation)}
+                  onClick={() => setEditing(true)}
+                >
+                  <Pencil /> Edit
+                </button>
+                <button
+                  aria-label="Delete secret"
+                  disabled={Boolean(pendingMutation)}
+                  onClick={remove}
+                >
+                  <Trash2 /> Delete
+                </button>
+              </div>
+            </header>
+            <div className={styles.cards}>
+              <Fact label="Status" value={selected.status} />
+              <Fact label="Stakes" value={selected.stakes} />
+            </div>
+            <section className={styles.block}>
+              <h3>Public version</h3>
+              {editing ? (
+                <>
+                  <textarea
+                    aria-label="Public version"
+                    disabled={Boolean(pendingMutation)}
+                    value={publicVersion}
+                    onChange={(event) => setPublicVersion(event.target.value)}
+                  />
+                  <button
+                    className={styles.primary}
+                    disabled={Boolean(pendingMutation)}
+                    onClick={save}
+                  >
+                    Save changes
+                  </button>
+                </>
+              ) : (
+                <p>{selected.public_version || 'No public version recorded.'}</p>
+              )}
+            </section>
+            <section className={styles.truth}>
+              <h3>Truth</h3>
+              {revealedTruth?.secretId === selected.id ? (
+                <p>{revealedTruth.truth || 'No truth recorded.'}</p>
+              ) : (
+                <div>
+                  <KeyRound />
+                  <p>Hidden until you explicitly reveal it.</p>
+                  <button
+                    aria-label="Reveal truth"
+                    onClick={() =>
+                      setRevealedTruth({
+                        secretId: selected.id,
+                        truth: selected.truth ?? selected.content ?? '',
+                      })
+                    }
+                  >
+                    <Eye /> Reveal truth
+                  </button>
+                </div>
+              )}
+            </section>
+          </>
+        ) : (
+          <div className={styles.pick}>
+            <KeyRound />
+            <h2>Select a secret</h2>
+            <p>Choose a secret to inspect its public details.</p>
+          </div>
+        )}
+      </section>
+      <aside className={styles.contextPane}>
+        <h2>Real context</h2>
+        {selected ? (
+          <Context item={selected} data={data} />
+        ) : (
+          <p>Select a secret to see resolved relationships.</p>
+        )}
+      </aside>
+      {createOpen ? (
+        <CreateSecretModal
+          worldId={worldId}
+          onClose={() => setCreateOpen(false)}
+          onCreated={resource.retry}
+        />
+      ) : null}
+    </main>
+  );
 }
 
-function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
+function Fact({ label, value }: { label: string; value?: string }) {
+  return (
+    <div className={styles.fact}>
+      <span>{label}</span>
+      <strong>{value || 'Not set'}</strong>
+    </div>
+  );
+}
 function Context({ item, data }: { item: SecretItem; data: Data }) {
-  const resolveAgents = (ids: string[] | undefined) => (ids ?? []).map((id) => data.agents.find((agent) => agent.id === id)).filter(Boolean) as WorldAgent[];
-  const aware = resolveAgents(item.aware_character_ids); const suspicious = resolveAgents(item.suspicious_character_ids);
-  return <div className={styles.context}>{aware.length ? <ChipGroup title="Aware" values={aware.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{suspicious.length ? <ChipGroup title="Suspicious" values={suspicious.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{!aware.length && !suspicious.length ? <p>No resolvable character relationships recorded.</p> : null}</div>;
+  const resolveAgents = (ids: string[] | undefined) =>
+    (ids ?? [])
+      .map((id) => data.agents.find((agent) => agent.id === id))
+      .filter(Boolean) as WorldAgent[];
+  const aware = resolveAgents(item.aware_character_ids);
+  const suspicious = resolveAgents(item.suspicious_character_ids);
+  return (
+    <div className={styles.context}>
+      {aware.length ? (
+        <ChipGroup
+          title="Aware"
+          values={aware.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))}
+        />
+      ) : null}
+      {suspicious.length ? (
+        <ChipGroup
+          title="Suspicious"
+          values={suspicious.map((agent) => ({
+            id: agent.id,
+            label: agent.display_name || agent.name,
+          }))}
+        />
+      ) : null}
+      {!aware.length && !suspicious.length ? (
+        <p>No resolvable character relationships recorded.</p>
+      ) : null}
+    </div>
+  );
+}
+function ChipGroup({ title, values }: { title: string; values: { id: string; label: string }[] }) {
+  return (
+    <div>
+      <h3>{title}</h3>
+      <div className={styles.chips}>
+        {values.map((value) => (
+          <span key={value.id}>{value.label}</span>
+        ))}
+      </div>
+    </div>
+  );
 }
-function ChipGroup({ title, values }: { title: string; values: { id: string; label: string }[] }) { return <div><h3>{title}</h3><div className={styles.chips}>{values.map((value) => <span key={value.id}>{value.label}</span>)}</div></div>; }
diff --git a/webui/src/pages/SessionsPage.module.css b/webui/src/pages/SessionsPage.module.css
index 50144cc2..f93a5382 100644
--- a/webui/src/pages/SessionsPage.module.css
+++ b/webui/src/pages/SessionsPage.module.css
@@ -8,7 +8,7 @@
   min-width: 0;
   min-height: 0;
   overflow: hidden;
-  background: #f7f9fc;
+  background: var(--surface-strong);
 }
 
 .historyClosed {
@@ -23,8 +23,8 @@
   min-width: 0;
   min-height: 0;
   overflow-y: auto;
-  border-right: 1px solid #e2e8f0;
-  background: #fff;
+  border-right: 1px solid var(--border);
+  background: var(--surface);
   opacity: 0;
   pointer-events: none;
   visibility: hidden;
@@ -41,11 +41,11 @@
   min-height: 68px;
   align-items: center;
   padding: 0 16px;
-  border-bottom: 1px solid #e2e8f0;
+  border-bottom: 1px solid var(--border);
 }
 
 .historyHeader span {
-  color: #667085;
+  color: var(--muted);
   font-size: 10px;
   font-weight: 750;
   letter-spacing: 0.08em;
@@ -54,7 +54,7 @@
 
 .historyHeader h2 {
   margin-top: 3px;
-  color: #17213b;
+  color: var(--ink);
   font-size: 15px;
   font-weight: 780;
 }
@@ -65,7 +65,7 @@
   min-height: 0;
   flex-direction: column;
   overflow: hidden;
-  background: #fff;
+  background: var(--surface);
 }
 
 @media (max-width: 1179px) {
diff --git a/webui/src/pages/WorldPage.module.css b/webui/src/pages/WorldPage.module.css
index 403b9338..a8ef3ec6 100644
--- a/webui/src/pages/WorldPage.module.css
+++ b/webui/src/pages/WorldPage.module.css
@@ -2,19 +2,19 @@
   height: 100%;
   overflow: auto;
   padding: 20px;
-  background: #f7f9fc;
-  color: #17213b;
+  background: var(--surface-strong);
+  color: var(--ink);
 }
 .heading {
   display: flex;
   gap: 14px;
   padding: 20px;
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 10px;
-  background: #fff;
+  background: var(--surface);
 }
 .heading span {
-  color: #667085;
+  color: var(--muted);
   font-size: 12px;
   font-weight: 700;
   text-transform: uppercase;
@@ -25,7 +25,7 @@
 }
 .heading p {
   margin: 0;
-  color: #59667c;
+  color: var(--muted-strong);
   line-height: 1.55;
 }
 .titleIcon {
@@ -35,8 +35,8 @@
   flex: 0 0 auto;
   place-items: center;
   border-radius: 9px;
-  background: #eaf0ff;
-  color: #123b91;
+  background: var(--brand-soft);
+  color: var(--brand);
 }
 .stats {
   display: grid;
@@ -49,10 +49,10 @@
   align-items: center;
   gap: 12px;
   padding: 14px 16px;
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 9px;
-  background: #fff;
-  color: #153981;
+  background: var(--surface);
+  color: var(--brand);
 }
 .stats article div {
   display: flex;
@@ -62,7 +62,7 @@
   font-size: 20px;
 }
 .stats span {
-  color: #667085;
+  color: var(--muted);
   font-size: 12px;
 }
 .grid {
@@ -73,9 +73,9 @@
 .panel {
   min-height: 220px;
   padding: 16px;
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 9px;
-  background: #fff;
+  background: var(--surface);
 }
 .wide {
   grid-column: 1 / -1;
@@ -86,11 +86,11 @@
   align-items: center;
   gap: 8px;
   margin-bottom: 14px;
-  color: #153981;
+  color: var(--brand);
 }
 .panel h2 {
   font-size: 15px;
-  color: #17213b;
+  color: var(--ink);
 }
 .cards {
   display: grid;
@@ -99,32 +99,32 @@
 }
 .cards article {
   padding: 12px;
-  border: 1px solid #e3e8f0;
+  border: 1px solid var(--border);
   border-radius: 7px;
 }
 .cards p,
 .rows p,
 .timeline p {
   margin: 5px 0 0;
-  color: #667085;
+  color: var(--muted);
   line-height: 1.45;
 }
 .rows article,
 .timeline article {
   padding: 10px 4px;
-  border-bottom: 1px solid #edf0f4;
+  border-bottom: 1px solid var(--surface-muted);
 }
 .rows small {
-  color: #7b86a0;
+  color: var(--muted);
 }
 .currentTime {
   margin-bottom: 6px;
-  color: #153981;
+  color: var(--brand);
   font-size: 12px;
   font-weight: 700;
 }
 .timeline strong {
-  color: #153981;
+  color: var(--brand);
   font-size: 12px;
 }
 .entityList {
@@ -137,17 +137,17 @@
   gap: 7px;
   align-items: center;
   padding: 8px 10px;
-  border: 1px solid #dfe6ef;
+  border: 1px solid var(--border);
   border-radius: 7px;
 }
 .entityList small {
-  color: #667085;
+  color: var(--muted);
   text-transform: uppercase;
 }
 .empty,
 .loading {
   margin: 34px 0;
-  color: #7a8699;
+  color: var(--muted);
   text-align: center;
 }
 .inlineError {
@@ -156,15 +156,15 @@
   justify-content: space-between;
   gap: 12px;
   padding: 10px;
-  border: 1px solid #f0d7a6;
+  border: 1px solid var(--amber-soft);
   border-radius: 7px;
-  background: #fff9eb;
-  color: #7a4d0b;
+  background: var(--amber-soft);
+  color: var(--amber);
 }
 .inlineError button {
   border: 0;
   background: transparent;
-  color: #153981;
+  color: var(--brand);
   font-weight: 700;
   cursor: pointer;
 }
diff --git a/webui/src/shell/DesktopShell.module.css b/webui/src/shell/DesktopShell.module.css
index 79fb3454..bbc51f3f 100644
--- a/webui/src/shell/DesktopShell.module.css
+++ b/webui/src/shell/DesktopShell.module.css
@@ -5,8 +5,13 @@
   width: 100%;
   height: 100vh;
   overflow: hidden;
-  background: #f7f9fc;
-  color: #101828;
+  background: var(--surface-strong);
+  color: var(--ink);
+}
+.menuButton,
+.navClose,
+.navBackdrop {
+  display: none;
 }
 
 .sidebar {
@@ -184,11 +189,67 @@
 
 @media (max-width: 980px) {
   .shell {
-    grid-template-columns: 184px minmax(0, 1fr);
+    position: relative;
+    display: block;
   }
 
+  .stage {
+    height: 100%;
+  }
+  .menuButton {
+    display: inline-flex;
+    position: absolute;
+    z-index: 31;
+    top: 13px;
+    left: 12px;
+    width: 34px;
+    height: 34px;
+    align-items: center;
+    justify-content: center;
+    border: 1px solid var(--border);
+    border-radius: var(--rounded-md);
+    background: var(--surface);
+    color: var(--brand);
+  }
+  .navBackdrop {
+    display: block;
+    position: absolute;
+    z-index: 39;
+    inset: 0;
+    width: 100%;
+    border: 0;
+    background: rgb(15 23 42 / 38%);
+  }
   .sidebar {
+    display: none;
+    position: absolute;
+    z-index: 40;
+    inset: 0 auto 0 0;
+    width: min(280px, 86vw);
     padding-inline: 10px;
+    overflow: hidden;
+    box-shadow: var(--shadow-md);
+  }
+  .sidebar[data-open='true'] {
+    display: flex;
+  }
+  .navClose {
+    display: inline-flex;
+    position: absolute;
+    z-index: 1;
+    top: 10px;
+    right: 10px;
+    width: 32px;
+    height: 32px;
+    align-items: center;
+    justify-content: center;
+    border: 1px solid var(--border);
+    border-radius: var(--rounded-md);
+    background: var(--surface);
+    color: var(--brand);
+  }
+  .topbar {
+    padding-left: 58px;
   }
 
   .navButton {
diff --git a/webui/src/shell/DesktopShell.tsx b/webui/src/shell/DesktopShell.tsx
index a8d5b3be..5e2ecdb0 100644
--- a/webui/src/shell/DesktopShell.tsx
+++ b/webui/src/shell/DesktopShell.tsx
@@ -1,5 +1,5 @@
-import type { ReactNode } from 'react';
-import { ChevronDown, Globe2, Search } from 'lucide-react';
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+import { ChevronDown, Globe2, Menu, Search, X } from 'lucide-react';
 import type { AppPage } from '../AppState';
 import { useAppState } from '../AppState';
 import merakLogo from '../assets/merak-logo.svg';
@@ -21,10 +21,61 @@ export default function DesktopShell({ page, onNavigate, children, overlays }: D
   const { t } = useI18n();
   const selectedWorld = state.worlds.find((world) => world.id === state.worldId);
   const worldName = selectedWorld?.name || t('shell.noWorld');
+  const [navigationOpen, setNavigationOpen] = useState(false);
+  const navigationTriggerRef = useRef<HTMLButtonElement>(null);
+  const navigationCloseRef = useRef<HTMLButtonElement>(null);
+  const closeNavigation = (restoreFocus = true) => {
+    setNavigationOpen(false);
+    if (restoreFocus) navigationTriggerRef.current?.focus();
+  };
+
+  useEffect(() => setNavigationOpen(false), [page]);
+  useEffect(() => {
+    if (!navigationOpen) return;
+    navigationCloseRef.current?.focus();
+    const escape = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') closeNavigation();
+    };
+    document.addEventListener('keydown', escape);
+    return () => document.removeEventListener('keydown', escape);
+  }, [navigationOpen]);
 
   return (
     <div className={styles.shell}>
-      <aside className={styles.sidebar}>
+      <button
+        ref={navigationTriggerRef}
+        type="button"
+        className={styles.menuButton}
+        aria-label="Open navigation"
+        aria-expanded={navigationOpen}
+        onClick={() => setNavigationOpen(true)}
+      >
+        <Menu aria-hidden="true" />
+      </button>
+      {navigationOpen ? (
+        <button
+          type="button"
+          className={styles.navBackdrop}
+          aria-label="Close navigation"
+          onClick={() => closeNavigation()}
+        />
+      ) : null}
+      <aside
+        className={styles.sidebar}
+        data-open={navigationOpen}
+        role={navigationOpen ? 'dialog' : undefined}
+        aria-modal={navigationOpen ? true : undefined}
+        aria-label={navigationOpen ? t('shell.primaryNavigation') : undefined}
+      >
+        <button
+          ref={navigationCloseRef}
+          type="button"
+          className={styles.navClose}
+          aria-label="Close navigation"
+          onClick={() => closeNavigation()}
+        >
+          <X aria-hidden="true" />
+        </button>
         <div className={styles.brand}>
           <img src={merakLogo} alt="Merak" />
         </div>
@@ -48,7 +99,10 @@ export default function DesktopShell({ page, onNavigate, children, overlays }: D
               type="button"
               className={styles.navButton}
               aria-current={page === pageId ? 'page' : undefined}
-              onClick={() => onNavigate(pageId)}
+              onClick={() => {
+                onNavigate(pageId);
+                closeNavigation(false);
+              }}
             >
               <Icon size={16} aria-hidden="true" strokeWidth={2} />
               <span>{label}</span>

From 077cf0727c366c9116c690792c69891b5c38343c Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sun, 21 Jun 2026 13:37:35 +0800
Subject: [PATCH 48/49] fix(webui): harden responsive drawer focus

---
 webui/src/__tests__/pages.test.tsx            |  66 ++++
 webui/src/__tests__/shell.test.tsx            |  13 +
 webui/src/components/layout/DetailPane.tsx    |  20 +-
 .../src/components/layout/ResponsivePane.tsx  |  32 +-
 webui/src/hooks/useModalFocusTrap.ts          |  41 +++
 webui/src/pages/CharactersPage.module.css     |   1 +
 webui/src/pages/FilesPage.module.css          |   1 +
 webui/src/pages/ForeshadowingPage.module.css  |   1 +
 webui/src/pages/ScenesPage.module.css         |   1 +
 webui/src/pages/SecretsPage.module.css        |   1 +
 webui/src/pages/SecretsPage.tsx               | 339 ++----------------
 webui/src/shell/DesktopShell.tsx              |  15 +-
 12 files changed, 177 insertions(+), 354 deletions(-)
 create mode 100644 webui/src/hooks/useModalFocusTrap.ts

diff --git a/webui/src/__tests__/pages.test.tsx b/webui/src/__tests__/pages.test.tsx
index 0025cd4a..40a1026f 100644
--- a/webui/src/__tests__/pages.test.tsx
+++ b/webui/src/__tests__/pages.test.tsx
@@ -459,6 +459,24 @@ describe('Files page', () => {
     }
   });
 
+  it('gives every responsive rail page an explicit positioning context', () => {
+    for (const page of [
+      'CharactersPage',
+      'FilesPage',
+      'ScenesPage',
+      'ForeshadowingPage',
+      'SecretsPage',
+    ]) {
+      const css = readFileSync(join(process.cwd(), `src/pages/${page}.module.css`), 'utf8');
+      expect(css, page).toMatch(/\.(?:workspace|page)\s*\{[^}]*position:\s*relative/s);
+    }
+    const paneCss = readFileSync(
+      join(process.cwd(), 'src/components/layout/ResponsivePane.module.css'),
+      'utf8',
+    );
+    expect(paneCss).toMatch(/\.pane\s*\{[^}]*overflow:\s*auto/s);
+  });
+
   it('keeps all page styles on approved global palette tokens', () => {
     const pagesDir = join(process.cwd(), 'src/pages');
     const files = readdirSync(pagesDir).filter((name) => name.endsWith('.module.css'));
@@ -1677,6 +1695,33 @@ describe('DetailPane', () => {
     expect(screen.queryByRole('complementary', { name: 'Relations' })).toBeNull();
     expect(toggle).toHaveFocus();
   });
+
+  it('traps Tab in a compact inspector', () => {
+    vi.stubGlobal('matchMedia', () => ({
+      matches: true,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }));
+    render(
+      <DetailPane
+        title="Lian"
+        inspector={<button type="button">Last control</button>}
+        inspectorLabel="Relations"
+      >
+        <p>Details</p>
+      </DetailPane>,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Show Relations' }));
+    const dialog = screen.getByRole('dialog', { name: 'Relations' });
+    const controls = within(dialog).getAllByRole('button');
+    controls.at(-1)?.focus();
+    fireEvent.keyDown(document, { key: 'Tab' });
+    expect(controls[0]).toHaveFocus();
+    controls[0].focus();
+    fireEvent.keyDown(document, { key: 'Tab', shiftKey: true });
+    expect(controls.at(-1)).toHaveFocus();
+    vi.unstubAllGlobals();
+  });
 });
 
 describe('ResponsivePane', () => {
@@ -1701,6 +1746,27 @@ describe('ResponsivePane', () => {
     expect(trigger).toHaveFocus();
     vi.unstubAllGlobals();
   });
+
+  it('returns focus to its trigger when selection closes the compact pane', () => {
+    vi.stubGlobal('matchMedia', () => ({
+      matches: true,
+      addEventListener: vi.fn(),
+      removeEventListener: vi.fn(),
+    }));
+    render(
+      <ResponsivePane label="Resources" closeOnSelect>
+        <div role="option" tabIndex={0}>
+          Selected resource
+        </div>
+      </ResponsivePane>,
+    );
+    const trigger = screen.getByRole('button', { name: 'Open Resources' });
+    fireEvent.click(trigger);
+    fireEvent.click(screen.getByRole('option'));
+    expect(screen.queryByRole('dialog', { name: 'Resources' })).toBeNull();
+    expect(trigger).toHaveFocus();
+    vi.unstubAllGlobals();
+  });
 });
 
 describe('Overview selectors', () => {
diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index 6bc388de..469d82f2 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -363,6 +363,19 @@ describe('desktop shell', () => {
     expect(trigger).toHaveFocus();
   });
 
+  it('traps forward and reverse Tab inside open navigation', () => {
+    renderShell('overview');
+    fireEvent.click(screen.getByRole('button', { name: 'Open navigation' }));
+    const dialog = screen.getByRole('dialog', { name: /navigation|导航/i });
+    const controls = within(dialog).getAllByRole('button');
+    controls.at(-1)?.focus();
+    fireEvent.keyDown(document, { key: 'Tab' });
+    expect(controls[0]).toHaveFocus();
+    controls[0].focus();
+    fireEvent.keyDown(document, { key: 'Tab', shiftKey: true });
+    expect(controls.at(-1)).toHaveFocus();
+  });
+
   it('defines the approved shared visual tokens and responsive shell contracts', () => {
     const globalCss = readFileSync('src/styles/global.css', 'utf8');
     const shellCss = readFileSync('src/shell/DesktopShell.module.css', 'utf8');
diff --git a/webui/src/components/layout/DetailPane.tsx b/webui/src/components/layout/DetailPane.tsx
index 6704f3d9..869714ad 100644
--- a/webui/src/components/layout/DetailPane.tsx
+++ b/webui/src/components/layout/DetailPane.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import { useModalFocusTrap } from '../../hooks/useModalFocusTrap';
 import styles from './DetailPane.module.css';
 
 export type DetailPaneProps = {
@@ -43,20 +44,7 @@ export default function DetailPane({
     query.addEventListener?.('change', update);
     return () => query.removeEventListener?.('change', update);
   }, []);
-
-  useEffect(() => {
-    if (!compact || !inspectorOpen) return;
-    inspectorRef.current
-      ?.querySelector<HTMLElement>(
-        'button, input, select, textarea, [tabindex]:not([tabindex="-1"])',
-      )
-      ?.focus();
-    const escape = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') closeInspector(true);
-    };
-    document.addEventListener('keydown', escape);
-    return () => document.removeEventListener('keydown', escape);
-  }, [compact, inspectorOpen]);
+  useModalFocusTrap(inspectorRef, compact && inspectorOpen, () => closeInspector(true));
 
   return (
     <section
@@ -88,7 +76,9 @@ export default function DetailPane({
         ) : null}
       </header>
       <div className={styles.body}>
-        <div className={styles.content}>{children}</div>
+        <div className={styles.content} inert={compact && inspectorOpen}>
+          {children}
+        </div>
         {inspectorOpen ? (
           <button
             type="button"
diff --git a/webui/src/components/layout/ResponsivePane.tsx b/webui/src/components/layout/ResponsivePane.tsx
index c3cb58be..ceeebe62 100644
--- a/webui/src/components/layout/ResponsivePane.tsx
+++ b/webui/src/components/layout/ResponsivePane.tsx
@@ -1,4 +1,5 @@
 import { useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import { useModalFocusTrap } from '../../hooks/useModalFocusTrap';
 import styles from './ResponsivePane.module.css';
 
 type Props = {
@@ -12,9 +13,6 @@ type Props = {
   'aria-hidden'?: boolean | 'true';
 };
 
-const focusable =
-  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
-
 export default function ResponsivePane({
   label,
   children,
@@ -48,31 +46,7 @@ export default function ResponsivePane({
     return () => query.removeEventListener?.('change', update);
   }, [breakpoint]);
 
-  useEffect(() => {
-    if (!compact || !open) return;
-    paneRef.current?.querySelector<HTMLElement>(focusable)?.focus();
-    const onKeyDown = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') {
-        event.preventDefault();
-        close();
-        return;
-      }
-      if (event.key !== 'Tab') return;
-      const nodes = [...(paneRef.current?.querySelectorAll<HTMLElement>(focusable) ?? [])];
-      if (!nodes.length) return;
-      const first = nodes[0];
-      const last = nodes[nodes.length - 1];
-      if (event.shiftKey && document.activeElement === first) {
-        event.preventDefault();
-        last.focus();
-      } else if (!event.shiftKey && document.activeElement === last) {
-        event.preventDefault();
-        first.focus();
-      }
-    };
-    document.addEventListener('keydown', onKeyDown);
-    return () => document.removeEventListener('keydown', onKeyDown);
-  }, [compact, open]);
+  useModalFocusTrap(paneRef, compact && open, close);
 
   return (
     <>
@@ -106,7 +80,7 @@ export default function ResponsivePane({
         inert={inert}
         onClickCapture={(event) => {
           if (closeOnSelect && compact && (event.target as Element).closest('[role="option"]'))
-            close(false);
+            close();
         }}
       >
         <button
diff --git a/webui/src/hooks/useModalFocusTrap.ts b/webui/src/hooks/useModalFocusTrap.ts
new file mode 100644
index 00000000..0453a044
--- /dev/null
+++ b/webui/src/hooks/useModalFocusTrap.ts
@@ -0,0 +1,41 @@
+import { useEffect, useRef, type RefObject } from 'react';
+
+const focusableSelector =
+  'button:not([disabled]), [href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+export function useModalFocusTrap(
+  containerRef: RefObject<HTMLElement | null>,
+  open: boolean,
+  onClose: () => void,
+) {
+  const closeRef = useRef(onClose);
+  closeRef.current = onClose;
+
+  useEffect(() => {
+    if (!open) return;
+    containerRef.current?.querySelector<HTMLElement>(focusableSelector)?.focus();
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') {
+        event.preventDefault();
+        closeRef.current();
+        return;
+      }
+      if (event.key !== 'Tab') return;
+      const controls = [
+        ...(containerRef.current?.querySelectorAll<HTMLElement>(focusableSelector) ?? []),
+      ];
+      if (!controls.length) return;
+      const first = controls[0];
+      const last = controls[controls.length - 1];
+      if (event.shiftKey && document.activeElement === first) {
+        event.preventDefault();
+        last.focus();
+      } else if (!event.shiftKey && document.activeElement === last) {
+        event.preventDefault();
+        first.focus();
+      }
+    };
+    document.addEventListener('keydown', onKeyDown);
+    return () => document.removeEventListener('keydown', onKeyDown);
+  }, [containerRef, open]);
+}
diff --git a/webui/src/pages/CharactersPage.module.css b/webui/src/pages/CharactersPage.module.css
index f1156b82..18f42349 100644
--- a/webui/src/pages/CharactersPage.module.css
+++ b/webui/src/pages/CharactersPage.module.css
@@ -1,4 +1,5 @@
 .workspace {
+  position: relative;
   display: grid;
   grid-template-columns: 260px minmax(420px, 1fr) 280px;
   height: 100%;
diff --git a/webui/src/pages/FilesPage.module.css b/webui/src/pages/FilesPage.module.css
index bac82cff..3f2c853f 100644
--- a/webui/src/pages/FilesPage.module.css
+++ b/webui/src/pages/FilesPage.module.css
@@ -1,4 +1,5 @@
 .page {
+  position: relative;
   display: grid;
   grid-template-columns: minmax(220px, 320px) minmax(0, 1fr);
   min-height: 0;
diff --git a/webui/src/pages/ForeshadowingPage.module.css b/webui/src/pages/ForeshadowingPage.module.css
index 0e0be0a4..861f31cc 100644
--- a/webui/src/pages/ForeshadowingPage.module.css
+++ b/webui/src/pages/ForeshadowingPage.module.css
@@ -1,4 +1,5 @@
 .workspace {
+  position: relative;
   display: grid;
   grid-template-columns: minmax(240px, 310px) minmax(360px, 1fr) minmax(220px, 280px);
   height: 100%;
diff --git a/webui/src/pages/ScenesPage.module.css b/webui/src/pages/ScenesPage.module.css
index 1bfa1953..6d87e771 100644
--- a/webui/src/pages/ScenesPage.module.css
+++ b/webui/src/pages/ScenesPage.module.css
@@ -4,6 +4,7 @@
   background: var(--surface-muted);
 }
 .workspace {
+  position: relative;
   display: grid;
   grid-template-columns: minmax(260px, 340px) minmax(0, 1fr);
   min-height: 100%;
diff --git a/webui/src/pages/SecretsPage.module.css b/webui/src/pages/SecretsPage.module.css
index 0e0be0a4..861f31cc 100644
--- a/webui/src/pages/SecretsPage.module.css
+++ b/webui/src/pages/SecretsPage.module.css
@@ -1,4 +1,5 @@
 .workspace {
+  position: relative;
   display: grid;
   grid-template-columns: minmax(240px, 310px) minmax(360px, 1fr) minmax(220px, 280px);
   height: 100%;
diff --git a/webui/src/pages/SecretsPage.tsx b/webui/src/pages/SecretsPage.tsx
index 5c24e8d1..388eef20 100644
--- a/webui/src/pages/SecretsPage.tsx
+++ b/webui/src/pages/SecretsPage.tsx
@@ -13,31 +13,18 @@ type Data = { items: SecretItem[]; agents: WorldAgent[]; contextError: string |
 
 export default function SecretsPage({ worldId }: { worldId: string }) {
   const resource = useResource(`secrets:${worldId}`, async () => {
-    const [secrets, agents] = await Promise.allSettled([
-      api.listSecrets(worldId),
-      api.listAgents(worldId),
-    ]);
+    const [secrets, agents] = await Promise.allSettled([api.listSecrets(worldId), api.listAgents(worldId)]);
     if (secrets.status === 'rejected') throw secrets.reason;
-    const failures = [agents].filter(
-      (result) => result.status === 'rejected',
-    ) as PromiseRejectedResult[];
+    const failures = [agents].filter((result) => result.status === 'rejected') as PromiseRejectedResult[];
     return {
       items: secrets.value.secrets ?? secrets.value.items ?? [],
       agents: agents.status === 'fulfilled' ? agents.value.agents : [],
-      contextError: failures.length
-        ? failures
-            .map((result) =>
-              result.reason instanceof Error ? result.reason.message : String(result.reason),
-            )
-            .join(' ')
-        : null,
+      contextError: failures.length ? failures.map((result) => result.reason instanceof Error ? result.reason.message : String(result.reason)).join(' ') : null,
     };
   });
   const [selectedId, setSelectedId] = useState<string | null>(null);
   const [filter, setFilter] = useState('all');
-  const [revealedTruth, setRevealedTruth] = useState<{ secretId: string; truth: string } | null>(
-    null,
-  );
+  const [revealedTruth, setRevealedTruth] = useState<{ secretId: string; truth: string } | null>(null);
   const [createOpen, setCreateOpen] = useState(false);
   const [editing, setEditing] = useState(false);
   const [publicVersion, setPublicVersion] = useState('');
@@ -49,318 +36,70 @@ export default function SecretsPage({ worldId }: { worldId: string }) {
   const committedWorldRef = useRef(worldId);
   const mountedRef = useRef(false);
   const data: Data | null = resource.data;
-  const items = useMemo(
-    () => (data?.items ?? []).filter((item) => !removed.includes(item.id)),
-    [data, removed],
-  );
+  const items = useMemo(() => (data?.items ?? []).filter((item) => !removed.includes(item.id)), [data, removed]);
   const filtered = filter === 'all' ? items : items.filter((item) => item.status === filter);
   const selected = filtered.find((item) => item.id === selectedId) ?? null;
 
-  useEffect(() => {
-    setSelectedId(null);
-    setRemoved([]);
-    setRevealedTruth(null);
-    setEditing(false);
-    setCreateOpen(false);
-    setPendingMutation(null);
-    pendingMutationRef.current = false;
-    setMutationError(null);
-  }, [worldId]);
+  useEffect(() => { setSelectedId(null); setRemoved([]); setRevealedTruth(null); setEditing(false); setCreateOpen(false); setPendingMutation(null); pendingMutationRef.current = false; setMutationError(null); }, [worldId]);
   useEffect(() => {
     mountedRef.current = true;
     if (committedWorldRef.current !== worldId) {
       committedWorldRef.current = worldId;
       generationRef.current += 1;
     }
-    return () => {
-      mountedRef.current = false;
-      generationRef.current += 1;
-    };
+    return () => { mountedRef.current = false; generationRef.current += 1; };
   }, [worldId]);
-  useEffect(() => {
-    setRevealedTruth(null);
-    setEditing(false);
-    setPublicVersion(selected?.public_version ?? '');
-  }, [selected?.id]);
-  useEffect(() => {
-    if (selectedId && !filtered.some((item) => item.id === selectedId))
-      setSelectedId(filtered[0]?.id ?? null);
-  }, [filtered, selectedId]);
+  useEffect(() => { setRevealedTruth(null); setEditing(false); setPublicVersion(selected?.public_version ?? ''); }, [selected?.id]);
+  useEffect(() => { if (selectedId && !filtered.some((item) => item.id === selectedId)) setSelectedId(filtered[0]?.id ?? null); }, [filtered, selectedId]);
 
   async function save() {
     if (!selected || pendingMutationRef.current || !window.confirm('Update this secret?')) return;
     const operationWorld = worldId;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
-    setPendingMutation('update');
-    setMutationError(null);
-    try {
-      await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion });
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        setEditing(false);
-        resource.retry();
-      }
-    } catch (error) {
-      if (mountedRef.current && generationRef.current === operationGeneration)
-        setMutationError((error as Error).message);
-    } finally {
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        pendingMutationRef.current = false;
-        setPendingMutation(null);
-      }
-    }
+    setPendingMutation('update'); setMutationError(null);
+    try { await api.patchSecret(operationWorld, selected.id, { public_version: publicVersion }); if (mountedRef.current && generationRef.current === operationGeneration) { setEditing(false); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
   async function remove() {
     if (!selected || pendingMutationRef.current || !window.confirm('Delete this secret?')) return;
-    const operationWorld = worldId;
-    const id = selected.id;
+    const operationWorld = worldId; const id = selected.id;
     const operationGeneration = generationRef.current;
     pendingMutationRef.current = true;
-    setPendingMutation('delete');
-    setMutationError(null);
-    try {
-      await api.deleteSecret(operationWorld, id);
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        setRemoved((ids) => [...ids, id]);
-        setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null);
-        setRevealedTruth(null);
-        resource.retry();
-      }
-    } catch (error) {
-      if (mountedRef.current && generationRef.current === operationGeneration)
-        setMutationError((error as Error).message);
-    } finally {
-      if (mountedRef.current && generationRef.current === operationGeneration) {
-        pendingMutationRef.current = false;
-        setPendingMutation(null);
-      }
-    }
+    setPendingMutation('delete'); setMutationError(null);
+    try { await api.deleteSecret(operationWorld, id); if (mountedRef.current && generationRef.current === operationGeneration) { setRemoved((ids) => [...ids, id]); setSelectedId(filtered.find((item) => item.id !== id)?.id ?? null); setRevealedTruth(null); resource.retry(); } }
+    catch (error) { if (mountedRef.current && generationRef.current === operationGeneration) setMutationError((error as Error).message); }
+    finally { if (mountedRef.current && generationRef.current === operationGeneration) { pendingMutationRef.current = false; setPendingMutation(null); } }
   }
   function changeFilter(nextFilter: string) {
     setFilter(nextFilter);
-    const visible =
-      nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
+    const visible = nextFilter === 'all' ? items : items.filter((item) => item.status === nextFilter);
     setSelectedId(visible[0]?.id ?? null);
     setRevealedTruth(null);
   }
 
-  if (!data)
-    return (
-      <PageState
-        loading={resource.status === 'loading'}
-        loadingLabel="Loading secrets"
-        error={resource.error}
-        onRetry={resource.retry}
-      />
-    );
-  return (
-    <main className={styles.workspace}>
-      <ResponsivePane label="Secrets" className={styles.listPane} closeOnSelect>
-        <header>
-          <div>
-            <span>Knowledge boundaries</span>
-            <h1>Secrets</h1>
-          </div>
-          <div className={styles.tools}>
-            <button aria-label="Refresh secrets" onClick={resource.retry}>
-              <RefreshCw />
-            </button>
-            <button
-              aria-label="Create secret"
-              disabled={Boolean(pendingMutation)}
-              onClick={() => setCreateOpen(true)}
-            >
-              <Plus />
-            </button>
-          </div>
-        </header>
-        <label className={styles.filter}>
-          <Filter />
-          <span>Status</span>
-          <select value={filter} onChange={(event) => changeFilter(event.target.value)}>
-            <option value="all">All</option>
-            <option value="active">Active</option>
-            <option value="exposed">Exposed</option>
-            <option value="abandoned">Abandoned</option>
-          </select>
-        </label>
-        {(resource.error || mutationError || data.contextError) && (
-          <div role="alert" className={styles.warning}>
-            {mutationError ?? resource.error?.message ?? data.contextError}
-          </div>
-        )}
-        {filtered.length ? (
-          <ResourceList
-            items={filtered}
-            selectedId={selectedId}
-            getId={(item) => item.id}
-            onSelect={setSelectedId}
-            ariaLabel="Secrets"
-            renderItem={(item) => (
-              <div className={styles.listItem}>
-                <KeyRound />
-                <div>
-                  <strong>{item.title || item.public_version || 'Untitled secret'}</strong>
-                  <span>{item.status ?? 'No status'}</span>
-                </div>
-              </div>
-            )}
-          />
-        ) : (
-          <p className={styles.empty}>No secrets match this filter.</p>
-        )}
-        <footer>
-          {filtered.length} {filtered.length === 1 ? 'secret' : 'secrets'}
-        </footer>
-      </ResponsivePane>
-      <section className={styles.detail} aria-label="Secret detail">
-        {selected ? (
-          <>
-            <header className={styles.detailHeader}>
-              <div>
-                <span>Secret detail</span>
-                <h2>{selected.title || selected.public_version || 'Untitled secret'}</h2>
-              </div>
-              <div className={styles.actions}>
-                <button
-                  aria-label="Edit secret"
-                  disabled={Boolean(pendingMutation)}
-                  onClick={() => setEditing(true)}
-                >
-                  <Pencil /> Edit
-                </button>
-                <button
-                  aria-label="Delete secret"
-                  disabled={Boolean(pendingMutation)}
-                  onClick={remove}
-                >
-                  <Trash2 /> Delete
-                </button>
-              </div>
-            </header>
-            <div className={styles.cards}>
-              <Fact label="Status" value={selected.status} />
-              <Fact label="Stakes" value={selected.stakes} />
-            </div>
-            <section className={styles.block}>
-              <h3>Public version</h3>
-              {editing ? (
-                <>
-                  <textarea
-                    aria-label="Public version"
-                    disabled={Boolean(pendingMutation)}
-                    value={publicVersion}
-                    onChange={(event) => setPublicVersion(event.target.value)}
-                  />
-                  <button
-                    className={styles.primary}
-                    disabled={Boolean(pendingMutation)}
-                    onClick={save}
-                  >
-                    Save changes
-                  </button>
-                </>
-              ) : (
-                <p>{selected.public_version || 'No public version recorded.'}</p>
-              )}
-            </section>
-            <section className={styles.truth}>
-              <h3>Truth</h3>
-              {revealedTruth?.secretId === selected.id ? (
-                <p>{revealedTruth.truth || 'No truth recorded.'}</p>
-              ) : (
-                <div>
-                  <KeyRound />
-                  <p>Hidden until you explicitly reveal it.</p>
-                  <button
-                    aria-label="Reveal truth"
-                    onClick={() =>
-                      setRevealedTruth({
-                        secretId: selected.id,
-                        truth: selected.truth ?? selected.content ?? '',
-                      })
-                    }
-                  >
-                    <Eye /> Reveal truth
-                  </button>
-                </div>
-              )}
-            </section>
-          </>
-        ) : (
-          <div className={styles.pick}>
-            <KeyRound />
-            <h2>Select a secret</h2>
-            <p>Choose a secret to inspect its public details.</p>
-          </div>
-        )}
-      </section>
-      <aside className={styles.contextPane}>
-        <h2>Real context</h2>
-        {selected ? (
-          <Context item={selected} data={data} />
-        ) : (
-          <p>Select a secret to see resolved relationships.</p>
-        )}
-      </aside>
-      {createOpen ? (
-        <CreateSecretModal
-          worldId={worldId}
-          onClose={() => setCreateOpen(false)}
-          onCreated={resource.retry}
-        />
-      ) : null}
-    </main>
-  );
+  if (!data) return <PageState loading={resource.status === 'loading'} loadingLabel="Loading secrets" error={resource.error} onRetry={resource.retry} />;
+  return <main className={styles.workspace}>
+    <ResponsivePane label="Secrets" className={styles.listPane} closeOnSelect><header><div><span>Knowledge boundaries</span><h1>Secrets</h1></div><div className={styles.tools}><button aria-label="Refresh secrets" onClick={resource.retry}><RefreshCw /></button><button aria-label="Create secret" disabled={Boolean(pendingMutation)} onClick={() => setCreateOpen(true)}><Plus /></button></div></header>
+      <label className={styles.filter}><Filter /><span>Status</span><select value={filter} onChange={(event) => changeFilter(event.target.value)}><option value="all">All</option><option value="active">Active</option><option value="exposed">Exposed</option><option value="abandoned">Abandoned</option></select></label>
+      {(resource.error || mutationError || data.contextError) && <div role="alert" className={styles.warning}>{mutationError ?? resource.error?.message ?? data.contextError}</div>}
+      {filtered.length ? <ResourceList items={filtered} selectedId={selectedId} getId={(item) => item.id} onSelect={setSelectedId} ariaLabel="Secrets" renderItem={(item) => <div className={styles.listItem}><KeyRound /><div><strong>{item.title || item.public_version || 'Untitled secret'}</strong><span>{item.status ?? 'No status'}</span></div></div>} /> : <p className={styles.empty}>No secrets match this filter.</p>}
+      <footer>{filtered.length} {filtered.length === 1 ? 'secret' : 'secrets'}</footer></ResponsivePane>
+    <section className={styles.detail} aria-label="Secret detail">{selected ? <><header className={styles.detailHeader}><div><span>Secret detail</span><h2>{selected.title || selected.public_version || 'Untitled secret'}</h2></div><div className={styles.actions}><button aria-label="Edit secret" disabled={Boolean(pendingMutation)} onClick={() => setEditing(true)}><Pencil /> Edit</button><button aria-label="Delete secret" disabled={Boolean(pendingMutation)} onClick={remove}><Trash2 /> Delete</button></div></header>
+      <div className={styles.cards}><Fact label="Status" value={selected.status} /><Fact label="Stakes" value={selected.stakes} /></div>
+      <section className={styles.block}><h3>Public version</h3>{editing ? <><textarea aria-label="Public version" disabled={Boolean(pendingMutation)} value={publicVersion} onChange={(event) => setPublicVersion(event.target.value)} /><button className={styles.primary} disabled={Boolean(pendingMutation)} onClick={save}>Save changes</button></> : <p>{selected.public_version || 'No public version recorded.'}</p>}</section>
+      <section className={styles.truth}><h3>Truth</h3>{revealedTruth?.secretId === selected.id ? <p>{revealedTruth.truth || 'No truth recorded.'}</p> : <div><KeyRound /><p>Hidden until you explicitly reveal it.</p><button aria-label="Reveal truth" onClick={() => setRevealedTruth({ secretId: selected.id, truth: selected.truth ?? selected.content ?? '' })}><Eye /> Reveal truth</button></div>}</section>
+    </> : <div className={styles.pick}><KeyRound /><h2>Select a secret</h2><p>Choose a secret to inspect its public details.</p></div>}</section>
+    <aside className={styles.contextPane}><h2>Real context</h2>{selected ? <Context item={selected} data={data} /> : <p>Select a secret to see resolved relationships.</p>}</aside>
+    {createOpen ? <CreateSecretModal worldId={worldId} onClose={() => setCreateOpen(false)} onCreated={resource.retry} /> : null}
+  </main>;
 }
 
-function Fact({ label, value }: { label: string; value?: string }) {
-  return (
-    <div className={styles.fact}>
-      <span>{label}</span>
-      <strong>{value || 'Not set'}</strong>
-    </div>
-  );
-}
+function Fact({ label, value }: { label: string; value?: string }) { return <div className={styles.fact}><span>{label}</span><strong>{value || 'Not set'}</strong></div>; }
 function Context({ item, data }: { item: SecretItem; data: Data }) {
-  const resolveAgents = (ids: string[] | undefined) =>
-    (ids ?? [])
-      .map((id) => data.agents.find((agent) => agent.id === id))
-      .filter(Boolean) as WorldAgent[];
-  const aware = resolveAgents(item.aware_character_ids);
-  const suspicious = resolveAgents(item.suspicious_character_ids);
-  return (
-    <div className={styles.context}>
-      {aware.length ? (
-        <ChipGroup
-          title="Aware"
-          values={aware.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))}
-        />
-      ) : null}
-      {suspicious.length ? (
-        <ChipGroup
-          title="Suspicious"
-          values={suspicious.map((agent) => ({
-            id: agent.id,
-            label: agent.display_name || agent.name,
-          }))}
-        />
-      ) : null}
-      {!aware.length && !suspicious.length ? (
-        <p>No resolvable character relationships recorded.</p>
-      ) : null}
-    </div>
-  );
-}
-function ChipGroup({ title, values }: { title: string; values: { id: string; label: string }[] }) {
-  return (
-    <div>
-      <h3>{title}</h3>
-      <div className={styles.chips}>
-        {values.map((value) => (
-          <span key={value.id}>{value.label}</span>
-        ))}
-      </div>
-    </div>
-  );
+  const resolveAgents = (ids: string[] | undefined) => (ids ?? []).map((id) => data.agents.find((agent) => agent.id === id)).filter(Boolean) as WorldAgent[];
+  const aware = resolveAgents(item.aware_character_ids); const suspicious = resolveAgents(item.suspicious_character_ids);
+  return <div className={styles.context}>{aware.length ? <ChipGroup title="Aware" values={aware.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{suspicious.length ? <ChipGroup title="Suspicious" values={suspicious.map((agent) => ({ id: agent.id, label: agent.display_name || agent.name }))} /> : null}{!aware.length && !suspicious.length ? <p>No resolvable character relationships recorded.</p> : null}</div>;
 }
+function ChipGroup({ title, values }: { title: string; values: { id: string; label: string }[] }) { return <div><h3>{title}</h3><div className={styles.chips}>{values.map((value) => <span key={value.id}>{value.label}</span>)}</div></div>; }
diff --git a/webui/src/shell/DesktopShell.tsx b/webui/src/shell/DesktopShell.tsx
index 5e2ecdb0..2f4255cb 100644
--- a/webui/src/shell/DesktopShell.tsx
+++ b/webui/src/shell/DesktopShell.tsx
@@ -3,6 +3,7 @@ import { ChevronDown, Globe2, Menu, Search, X } from 'lucide-react';
 import type { AppPage } from '../AppState';
 import { useAppState } from '../AppState';
 import merakLogo from '../assets/merak-logo.svg';
+import { useModalFocusTrap } from '../hooks/useModalFocusTrap';
 import { useSafeNavigation } from '../hooks/useSafePageNavigation';
 import { useI18n } from '../i18n';
 import styles from './DesktopShell.module.css';
@@ -24,21 +25,14 @@ export default function DesktopShell({ page, onNavigate, children, overlays }: D
   const [navigationOpen, setNavigationOpen] = useState(false);
   const navigationTriggerRef = useRef<HTMLButtonElement>(null);
   const navigationCloseRef = useRef<HTMLButtonElement>(null);
+  const navigationRef = useRef<HTMLElement>(null);
   const closeNavigation = (restoreFocus = true) => {
     setNavigationOpen(false);
     if (restoreFocus) navigationTriggerRef.current?.focus();
   };
 
   useEffect(() => setNavigationOpen(false), [page]);
-  useEffect(() => {
-    if (!navigationOpen) return;
-    navigationCloseRef.current?.focus();
-    const escape = (event: KeyboardEvent) => {
-      if (event.key === 'Escape') closeNavigation();
-    };
-    document.addEventListener('keydown', escape);
-    return () => document.removeEventListener('keydown', escape);
-  }, [navigationOpen]);
+  useModalFocusTrap(navigationRef, navigationOpen, closeNavigation);
 
   return (
     <div className={styles.shell}>
@@ -61,6 +55,7 @@ export default function DesktopShell({ page, onNavigate, children, overlays }: D
         />
       ) : null}
       <aside
+        ref={navigationRef}
         className={styles.sidebar}
         data-open={navigationOpen}
         role={navigationOpen ? 'dialog' : undefined}
@@ -111,7 +106,7 @@ export default function DesktopShell({ page, onNavigate, children, overlays }: D
         </nav>
       </aside>
 
-      <div className={styles.stage}>
+      <div className={styles.stage} inert={navigationOpen}>
         <header className={styles.topbar}>
           <label className={styles.worldSelector}>
             <Globe2 size={16} aria-hidden="true" />

From 5d5bc3ec1b8aa51a8c0c651e5dbfa816599b1a0e Mon Sep 17 00:00:00 2001
From: IcePop <CHBuLookup@outlook.com>
Date: Sun, 21 Jun 2026 13:44:14 +0800
Subject: [PATCH 49/49] fix(webui): restore focus after compact navigation

---
 webui/src/__tests__/shell.test.tsx | 24 ++++++++++++++++++++++++
 webui/src/shell/DesktopShell.tsx   |  2 +-
 2 files changed, 25 insertions(+), 1 deletion(-)

diff --git a/webui/src/__tests__/shell.test.tsx b/webui/src/__tests__/shell.test.tsx
index 469d82f2..5ed929f1 100644
--- a/webui/src/__tests__/shell.test.tsx
+++ b/webui/src/__tests__/shell.test.tsx
@@ -376,6 +376,30 @@ describe('desktop shell', () => {
     expect(controls.at(-1)).toHaveFocus();
   });
 
+  it('returns focus to the menu trigger after a compact navigation item succeeds', () => {
+    const navigate = vi.fn();
+    renderShell('overview', navigate);
+    const trigger = screen.getByRole('button', { name: 'Open navigation' });
+    fireEvent.click(trigger);
+    fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: /Characters/ }));
+    expect(navigate).toHaveBeenCalledWith('characters');
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(trigger).toHaveFocus();
+  });
+
+  it('returns focus to the menu trigger when dirty navigation is cancelled', () => {
+    vi.spyOn(window, 'confirm').mockReturnValue(false);
+    renderSafeNavigation();
+    fireEvent.click(screen.getByRole('button', { name: 'Start chapters' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Make dirty' }));
+    const trigger = screen.getByRole('button', { name: 'Open navigation' });
+    fireEvent.click(trigger);
+    fireEvent.click(within(screen.getByRole('dialog')).getByRole('button', { name: /Scenes/ }));
+    expect(screen.getByLabelText('Current page')).toHaveTextContent('chapters');
+    expect(screen.queryByRole('dialog')).toBeNull();
+    expect(trigger).toHaveFocus();
+  });
+
   it('defines the approved shared visual tokens and responsive shell contracts', () => {
     const globalCss = readFileSync('src/styles/global.css', 'utf8');
     const shellCss = readFileSync('src/shell/DesktopShell.module.css', 'utf8');
diff --git a/webui/src/shell/DesktopShell.tsx b/webui/src/shell/DesktopShell.tsx
index 2f4255cb..971d9a0a 100644
--- a/webui/src/shell/DesktopShell.tsx
+++ b/webui/src/shell/DesktopShell.tsx
@@ -96,7 +96,7 @@ export default function DesktopShell({ page, onNavigate, children, overlays }: D
               aria-current={page === pageId ? 'page' : undefined}
               onClick={() => {
                 onNavigate(pageId);
-                closeNavigation(false);
+                closeNavigation();
               }}
             >
               <Icon size={16} aria-hidden="true" strokeWidth={2} />