@xrn1997/dsh-session-delete 0.4.0 → 0.6.0

package/lib/types/client/orphan-maintenance.d.ts

@@ -3,8 +3,9 @@
  *
  * 它先是回收站面板上的一块，2026-10-27 起搬进插件设置页的「维护」卡（面板不再自动扫孤儿，ADR-0021）。
  * 之所以仍收成一个 module：这三段与任何一面的清单渲染、选择、键盘、拖栏都毫无关系；改维护块的文案或
- * 确认框时，diff 不该与布局改动互相踩。它只吃一个窄接口 `OrphanMaintenanceQuery`——报告、三条提示与
- * 四个动作，实现方是设置页的 `use-maintenance.ts`。
+ * 确认框时，diff 不该与布局改动互相踩。它只吃泛型段 module 的一张视图 `MaintenanceSectionView`——
+ * 报告、三条提示、确认框与四个动作；实现方是 `use-maintenance-section.ts` 的状态机
+ * （设置页的 `use-maintenance.ts` 为孤儿会话段实例化它）。
  *
  * 三条界面规则（现状住 `docs/ui-spec.md`）：
  * - **报告非空才出警告条**：空报告与 `null` 都不出现——"检查过了，什么都没有"不是要给用户看的东西，
@@ -13,33 +14,17 @@
  *   （"没能回答有多少残留"与"没有残留"是两件事，不许折成空报告）。
  * - **「已经不在」不是失败**：别处清掉或父已回到清册时单独一条中性提示，不计入失败，下次检查时自然消失。
  *
- * 四个动作都由实现方给：警告条开预览（`openOrphanPreview`）、失败块重试（`scanOrphans`）、
- * 确认框清理（`cleanOrphans`）、取消（`setOrphanConfirm`）。`busy` 不归本 module 管——它是实现方
- * 那一段自己的忙碌读数，通过 props 传进来。
+ * 四个动作都从段上取：警告条开预览（`openPreview`，唯一开门、先清旧提示）、失败块重试（`scan`）、
+ * 确认框清理（`clean`）、取消（`cancel`，只收框）。`busy` 也不再是 prop——段自己给（在飞即忙），
+ * 本块只读它按住按钮。
  */
 import type { ReactElement } from 'react';
 import type { Translate } from './copy.js';
 import type { OrphanReportWire } from './remote.js';
-/**
- * 本块消费的那一面：一份报告、三条提示、四个动作。窄到只列它真读的成员——实现方多给（阶段、忙碌、
- * 附件回执…）都与本块无关，也不许本块去读。设置页的 `Maintenance` 结构上满足它。
- */
-export interface OrphanMaintenanceQuery {
-    /** `null` = 还没检查/读不到；本块只认"非空报告"那一档。 */
-    readonly orphanReport: OrphanReportWire | null;
-    readonly orphanFailure: string | null;
-    readonly orphanNotice: string | null;
-    readonly orphanConfirm: boolean;
-    setOrphanConfirm(open: boolean): void;
-    openOrphanPreview(): void;
-    cleanOrphans(): Promise<void>;
-    /** 检查（也是失败块那颗「重试」）：维护面上没有第二份扫描入口。 */
-    scanOrphans(): Promise<void>;
-}
+import type { MaintenanceSectionView } from './use-maintenance-section.js';
 export interface OrphanMaintenanceProps {
-    query: OrphanMaintenanceQuery;
-    /** 这一段自己的忙碌读数：在飞时按住本块里的每一颗按钮。 */
-    busy: boolean;
+    /** 段视图：读数、提示、确认框、忙碌与四个动作都在它上面，本块不多要也不少读。 */
+    section: MaintenanceSectionView<OrphanReportWire>;
     t: Translate;
 }
-export declare function OrphanMaintenance({ query, busy, t }: OrphanMaintenanceProps): ReactElement | null;
+export declare function OrphanMaintenance({ section, t }: OrphanMaintenanceProps): ReactElement | null;

package/lib/types/client/pending-open.d.ts

@@ -0,0 +1,17 @@
+export interface PendingOpenInput {
+    /** 订阅「清单变了」；返回退订。旧 store 可能没有——那时只有"已经出现"这一支能开。 */
+    readonly subscribe?: ((listener: () => void) => () => void) | undefined;
+    /** 目标是否已经出现在清单里。 */
+    readonly isReady: () => boolean;
+    /** 出现的这一拍还该不该抢焦点（用户可能已经选了别的会话）。 */
+    readonly canOpen: () => boolean;
+    /** 打开目标；调用方自己收宿主抛错。 */
+    readonly open: () => void;
+}
+export interface PendingOpen {
+    /** 取消在等的等待（没有也安全）；后一次 `schedule` 会先取消前一次。 */
+    cancel(): void;
+    /** 等目标出现再打开；已经在清单里就立即打开。 */
+    schedule(input: PendingOpenInput): void;
+}
+export declare function createPendingOpen(giveUpMs?: number): PendingOpen;

package/lib/types/client/receipt.d.ts

@@ -68,11 +68,13 @@ export declare function readSingleReceipt<A extends ApplyAction>(action: A, id:
 export interface ReceiptSummary {
     readonly successIds: readonly string[];
     readonly neutralIds: readonly string[];
-    /** failed + missing（通道没回）；neutral 单独在 `neutralIds`，部分计数只从 failed 的 details 取。 */
+    /** failed + missing（通道没回）；neutral 单独在 `neutralIds`。 */
     readonly failed: readonly {
         readonly id: string;
         readonly error: RemoteFailure;
     }[];
+    /** 部分计数的累加语义只住这里：只从 failed 的 `details` 取 `removed`/`freedBytes` 并按批相加
+     *  （"删了一半才炸"的那部分释放量）；neutral / missing 不带 details，不参与累加。 */
     readonly partial: {
         readonly removed: number;
         readonly freedBytes: number;

package/lib/types/client/remote.d.ts

@@ -1,9 +1,13 @@
 /**
- * 浏览器半的取数通道：同源 fetch /dsh-session-delete-api，并处理信封与失败原文。
+ * 浏览器半的取数通道：同源 fetch 宿主 `connection.fetch` 的 exact Fetch 路由（`/api` + 插件前缀）。
+ * 信封与失败原文在这一层收口。
  *
- * - 路由是宿主 web server 上的插件前缀；官方 remote.<namespace> 需要生成的 Typert 描述符，
- *   第三方无法动态挂载，因此走这条薄线（ADR-0009）。
- * - 九段：list / ping / orphans / detail / apply / empty / attachment / attachment-orphans / attachment-clean；
+ * - 九段注册在宿主 `connection.fetch.register` 上，鉴权归宿主 `/api` bridge（ADR-0033）；
+ *   没有旧前缀 fallback——支持面是 web UI 与桌面端，二者的标准组合都装 `client-connection`。
+ *   官方 remote.<namespace> 仍不可用（第三方拿不到 Typert 描述符的动态发现挂载点）。
+ * - 九段的**段名与方法**住 `src/shared/wire.ts` 的结构化段名表（`ROUTES` 每项 `{ path, method }`），
+ *   本文件只投影路径（`prefix + ROUTES.x.path`）与方法（GET 段直接取 `ROUTES.x.method`，写段把它
+ *   交给 `post()`）——方法字面量不在本文件出现第二份；
  *   写动作统一走 apply；`attachment` 是唯一二进制段，由 `src/client/attachment-view.tsx` 直接拼地址，
  *   不经过本文件的信封通道；`attachment-orphans`（纯读）与 `attachment-clean`（聚合写）是孤儿附件的两段。
  * - 信封与官方 unary 面同形：{ok:true,value} / {ok:false,error}。HTTP 往返本身失败才 reject；
@@ -25,6 +29,8 @@ export type PurgeResultLike = PurgeStatsWire;
  * **线上只有"日志里读出来的那几件"**：`deletedAt` / `sizeBytes` / `wasArchived` / 清册 `title` 这些
  * 清册已有的字段一律不过线——组件按 `entryId` 与自己手上那份清单配对，这样"清单里的大小"和
  * "详情里的大小"永远是同一个数，不会因为两次读数不同而各说各话。
+ * 例外只有一格：`subagents`（孩子摘要）。孩子不在客户端清单里、无从配对，
+ * 它们的清册事实只能随详情过线（issue #7，ADR-0029）。
  */
 export type TrashDetailLike = TrashDetailWire;
 /** 任意异常 → 失败面。非带标记的失败（网络层、TypeError…）也保留原文，绝不吞；带标记的失败把
@@ -63,7 +69,7 @@ export interface RawSessionDeleteRemote {
     attachmentOrphans(): Promise<RemoteResult<AttachmentOrphanReportWire>>;
     /** 聚合写：只删上一条报告那一刻无引用的图片对象，回 `AttachmentCleanupWire`。 */
     attachmentClean(): Promise<RemoteResult<AttachmentCleanupWire>>;
-    detail(entryId: string): Promise<RemoteResult<TrashDetailLike>>;
+    detail(entryId: string, before?: number): Promise<RemoteResult<TrashDetailLike>>;
     /** 一组 id 上的同一个动作。顶层信封的 `ok:false` 只表示**整次调用**没办成（路由自检、栅栏之外）；
      *  单条动作的成败住在 `ApplyOutcome` 里——这是批量接口的判据，别在信封层找它。 */
     apply(action: ApplyAction, ids: readonly string[]): Promise<RemoteResult<ApplyOutcome[]>>;
@@ -71,20 +77,17 @@ export interface RawSessionDeleteRemote {
     empty(): Promise<RemoteResult<PurgeResultLike>>;
 }
 /**
- * 前缀路由的 fetch 实现。**相对路径**：不拼 base、不认 origin——页面本身就是从宿主 web server
- * 加载的，同源是这条薄线的全部前提。本机（含转发落在回环的桌面壳）靠回环 + Origin/Referer 过栅栏；
- * 远程（LAN / 反代）客户端另由宿主 `connection` 判「已认证的 Web 身份」，所以这条通道**只对**
- * `dsh web` 打印的 URL 打开过的页面成立（凭据是那行 URL 换来的 cookie，不是插件自己的秘密）。
+ * exact Fetch 路由的 fetch 实现。**相对路径**：不拼 host、不认 origin——页面本身就是从宿主页面
+ * 加载的，同源是这条通道的全部前提；鉴权归宿主 `/api` bridge（ADR-0033）。所以这条通道**只对**
+ * 宿主页面打开过、带宿主身份的客户端成立（凭据是那次访问换来的 cookie，不是插件自己的秘密）。
  */
-export declare function createHttpRemote(prefix?: string): RawSessionDeleteRemote;
+export declare function createHttpRemote(): RawSessionDeleteRemote;
 /**
- * 取数通道探测：一次 `GET /ping` 走通（或走到）就是"通道在"。
+ * 探测唯一通道：一次 `GET /ping` 回成功信封（`pong`）才注册入口。
  *
- * 判据是**「拿到信封」而不是「操作成功」**：`{ok:false, error}` 也是一次成功的往返（路由在、依赖接上了、
- * 错误映射也生效了），那时该做的是把入口显示出来、让原文上屏；只有往返本身失败才算通道缺席 ⇒
- * 一个槽位贡献都不注册（docs/architecture.md §3「通道探测决定入口出现与否」）。
- *
- * 探测用一次零成本的 `GET /ping`，不读清单，避免每次页面加载都跑全表对账。
+ * - 401/403 是宿主 `/api` 的纯文本身份/归属失败：入口不出现，不装禁用态。
+ * - 失败信封 / 404 / 非信封同样按不可用处理：`/api` 网关对未知路径也可能回错误形状，
+ *   不能据此把入口摆出来让每个动作都失败。
  */
 export declare function probeChannel(raw: RawSessionDeleteRemote): Promise<boolean>;
 /** `shared/wire.ts` 的 `ApplyOutcome`、扫描报告与附件回执从这里转出去——浏览器半只认 `remote.js` 这一扇门。 */
@@ -113,11 +116,11 @@ export interface SessionDeleteRemote {
     /** 回收站之外的无主子会话报告（纯读）。读不到就是 throw —— 界面上那是**一次失败的检查**，
      *  不是"零条残留"（把 `io` 折成空报告等于把"不知道"说成"没有"）。 */
     scanOrphans(): Promise<OrphanReportWire>;
-    /** `.dsh` 内无引用图片对象的报告（纯读；含最多 200 条预览清单）。读不到就是 throw，同样不许折成 0。 */
+    /** `.dsh` 内无引用图片对象的报告（纯读；预览清单条数由 Node 半配置，默认 200）。读不到就是 throw，同样不许折成 0。 */
     scanAttachmentOrphans(): Promise<AttachmentOrphanReportWire>;
     /** 清掉报告那一刻无引用的图片副本（聚合回执）。 */
     cleanAttachmentOrphans(): Promise<AttachmentCleanupWire>;
-    detail(entryId: string): Promise<TrashDetailLike>;
+    detail(entryId: string, before?: number): Promise<TrashDetailLike>;
     /** 一段管所有写动作：一次调用把整批办完，逐条结果原样交回组件。 */
     applyOutcomes(action: ApplyAction, ids: readonly string[]): Promise<ApplyOutcome[]>;
     /** 清空回收站（聚合回执）。 */

package/lib/types/client/store.d.ts

@@ -17,18 +17,14 @@ export interface ClientStore<T> {
 export declare function createStore<T>(initial: T): ClientStore<T>;
 /** 懒读快照：`get()` 只在脏了时调用 `read()`，干净时回同一个引用（React snapshot 契约）。 */
 export interface LazyStore<T> {
-    get(): T;
+    /** 属性声明：`get` / `subscribe` 会被摘下来直接交给 `useSyncExternalStore`（宿主行快照），
+     *  实现不读 `this`。方法简写会给它隐式 `this: LazyStore<T>`，触发 `unbound-method` 误报。 */
+    get: () => T;
     /** 标脏并通告；下一次 `get()` 重读。 */
-    invalidate(): void;
-    subscribe(listener: () => void): () => void;
+    invalidate: () => void;
+    subscribe: (listener: () => void) => () => void;
 }
-export interface LazyStoreLifecycle {
-    /** 第一个订阅者到来时跑（观察者在这里接上）。 */
-    onFirstSubscribe?(): void;
-    /** 最后一个订阅者退订时跑（观察者在这里断开）。 */
-    onLastUnsubscribe?(): void;
-}
-export declare function createLazyStore<T>(initial: T, read: () => T, lifecycle?: LazyStoreLifecycle): LazyStore<T>;
+export declare function createLazyStore<T>(initial: T, read: () => T): LazyStore<T>;
 /**
  * 最新票句柄：每张票记着签发时的序号，只有序号仍等于当前的那张才 `current`。
  * 调用方在发起异步读时 `issue()` 一张票，落地前问 `ticket.current`——旧读因此不会盖掉新状态。
@@ -46,3 +42,12 @@ export interface LatestWins {
     invalidate(): void;
 }
 export declare function createLatestWins(): LatestWins;
+/**
+ * 引用归一：输入允许调用方逐渲染换新对象，回调只经这份 ref 读**最新**那一份，于是依赖它的回调
+ * 身份恒稳、调用方的 effect 可以放心把它们当依赖——「输入必须是稳定引用」的隐式契约就此不存在
+ * （issue #8 第 3 条）。写回在 effect 里（提交后），与 React 的渲染期只读约定一致。
+ * 这一形状的唯一实现：别在调用方再手写一份「useRef + 每渲染写回」。
+ */
+export declare function useLatest<T>(value: T): {
+    readonly current: T;
+};

package/lib/types/client/trash-detail.d.ts

@@ -1,27 +1,69 @@
+/**
+ * 回收站详情块：只画状态，不取数。选中、缓存、失败与重读都在面板控制器里。
+ *
+ * 三条界面约束：
+ * - 动作（恢复/彻底删除）留在清单行右侧；详情只负责看。
+ * - 标题优先用清册标题，空串才回落到日志的 session/title。
+ * - 正文是**块**：用户/助手文字常显；思考、工具、注入、系统消息、压缩摘要默认折叠，折叠头给
+ *   标签 + 首行摘要（工具另给状态）。注入也铺进正文——这是对宿主 Chat 的有意偏离（它隐藏普通注入，
+ *   而这里的目标是「删之前看全」）；条数另进元信息表。
+ *
+ * 助手正文与思考走 Markdown，用户提问保持原话；工具参数/结果走等宽纯文本（限高可滚）。
+ * 附件随块位置渲染：用户气泡之上、助手正文之后、工具展开体末尾。
+ */
+import { type RefObject } from 'react';
 import { type Translate } from './copy.js';
-import type { TrashDetailLike, TrashEntryLike } from './remote.js';
+import type { TrashEntryWire } from '../shared/wire.js';
+import type { TrashDetailLike } from './remote.js';
+/** 详情主体只承诺清册那一行：孩子视图看的那条不在客户端清单里，没有只读数可配对
+ *  （孩子摘要随父详情过线，那一格的判据住 `src/client/remote.ts` 的 `TrashDetailLike`）。 */
 export type TrashDetailState = {
     kind: 'idle';
 } | {
     kind: 'loading';
-    entry: TrashEntryLike;
+    entry: TrashEntryWire;
 } | {
     kind: 'failed';
-    entry: TrashEntryLike;
+    entry: TrashEntryWire;
     message: string;
 } | {
     kind: 'ready';
-    entry: TrashEntryLike;
+    entry: TrashEntryWire;
     detail: TrashDetailLike;
 };
+/** 「加载更早」这一块（在飞/失败 + 滚动容器）整体过手：`TrashDetail` 只转交，谁画正文谁拆开用。
+ *  四样东西是一个概念（分页读面）的四个格子，打包走一个名字，不再逐样穿透组件边界。 */
+export interface DetailPager {
+    /** 更早一页正在读。 */
+    loadingOlder: boolean;
+    /** 更早一页读失败的原文；正文本身仍是 ready。 */
+    olderFailure: string | null;
+    onLoadOlder: () => void;
+    /** 详情栏的滚动容器；prepend 更早一页后按高度差补偿滚动位置。 */
+    scrollRef?: RefObject<HTMLDivElement | null>;
+}
+/** 详情的导航面（孩子视图的开与回）：类型定义住在这里（视图定 prop 形状），
+ *  控制器 `import type` 它避免环。判据（谁在场、title 给什么）住控制器的 `detailNav` 派生。 */
+export interface DetailNav {
+    /** 只在主体是清单选中那条时交出（ADR-0029 单级判据的唯一实现）。 */
+    readonly onOpenChild?: (child: TrashEntryWire) => void;
+    /** 孩子视图的返回目标；title 是原文（未命名兜底由视图按 t 处理）。 */
+    readonly parentContext?: {
+        readonly title: string;
+        readonly onBack: () => void;
+    };
+}
 export interface TrashDetailProps {
     state: TrashDetailState;
     /** 有写操作在飞（动作按钮住在清单行里，这里只用来把「重试」按住）。 */
     busy: boolean;
-    /** 宽档不画返回——同屏就有清单，返回是多余的一步。 */
+    /** 宽档不画「返回清单」——同屏就有清单，那一步多余。孩子视图另有一颗返回，见 `detailNav.parentContext`。 */
     wide: boolean;
     onRetry: () => void;
     onBack: () => void;
+    /** 孩子视图的开与回（控制器派生，判据见 `DetailNav`）：缺席 = 不画入口/返回，组件只画状态，不自己造动作。 */
+    detailNav: DetailNav;
+    pager: DetailPager;
     t: Translate;
 }
-export declare function TrashDetail({ state, busy, wide, onRetry, onBack, t }: TrashDetailProps): import("react").JSX.Element;
+export declare function TrashDetail({ state, busy, wide, onRetry, onBack, detailNav, pager, t, }: TrashDetailProps): import("react").JSX.Element;

package/lib/types/client/trash-entry.d.ts

@@ -1,6 +1,6 @@
 /** 宿主 `SidebarPanelIconOwnerProps`：请求的方形边长；`active` 收了但不用（见头注）。 */
 export interface TrashPanelIconProps {
-    size?: number;
+    size?: number | undefined;
     active?: boolean;
 }
 export declare function TrashPanelIcon({ size }: TrashPanelIconProps): import("react").JSX.Element;

package/lib/types/client/trash-nav.d.ts

@@ -4,8 +4,8 @@ import type { TrashEntryLike } from './remote.js';
  * 导航要的面。`ordered` 是**屏幕上的顺序**（只含展开的组），由面板/选择面算好传进来——
  * 布局常量与本 module 无关。`drillEnabled` 是这一档支不支持整行下钻（窄档为真；宽档 Enter/Space
  * 只移动选中，与整行点击的 `{ drill: !split }` 同一条判据）。四个动作都由调用方注入：
- * `select` 只移动选中（带 `drill` 才下钻），`exitDrill` 是控制器那条「← 返回清单」的同一动作，
- * `focusRow` 把焦点交给某一行。
+ * `select` 只移动选中（带 `drill` 才下钻），`back` 是控制器的回退动作（两程：先收孩子视图、
+ * 再退下钻），`focusRow` 把焦点交给某一行。
  */
 export interface TrashNavInput {
     ordered: readonly TrashEntryLike[];
@@ -13,18 +13,22 @@ export interface TrashNavInput {
     selectMode: boolean;
     drillEnabled: boolean;
     drilled: boolean;
-    select(entry: TrashEntryLike, options?: {
+    /** 四个动作都是**属性声明**：它们被摘下来放进 `useTrashNav` 的输入或直接挂成事件处理器，
+     *  实现体一个都不读 `this`。方法简写会带上隐式 `this: TrashNavInput`，`unbound-method`
+     *  会把这种交接报成可疑；改属性只是让类型面说真话。 */
+    select: (entry: TrashEntryLike, options?: {
         drill?: boolean;
-    }): Promise<void>;
-    toggleCheck(entryId: string): void;
-    exitDrill(): void;
-    focusRow(entryId: string): void;
+    }) => Promise<void>;
+    toggleCheck: (entryId: string) => void;
+    back: () => void;
+    focusRow: (entryId: string) => void;
 }
 export interface TrashNav {
     /** `aria-activedescendant` 的那条 id：选中行不在 DOM 里时是 `null`。 */
     readonly activeDescendantId: string | null;
     /** 清单里唯一拿着 `tabIndex=0` 的那一行；清单空时是 `null`。 */
     readonly tabStopId: string | null;
-    onListKeyDown(event: ReactKeyboardEvent<HTMLElement>): void;
+    /** 直接挂到清单容器的 `onKeyDown`：属性声明（见上）让「摘下来挂事件」不被误报。 */
+    onListKeyDown: (event: ReactKeyboardEvent<HTMLElement>) => void;
 }
 export declare function useTrashNav(input: TrashNavInput): TrashNav;

package/lib/types/client/ui/Toast.d.ts

@@ -19,6 +19,8 @@ import './styles.js';
 export interface ToastAction {
     label: string;
     onClick: () => void;
+    /** 在飞/不可用时按灰并挡住点击（Toast 是本地配方，动作面按调用点的需要长）。 */
+    disabled?: boolean;
 }
 export interface ToastProps {
     /** 已解析好的横幅文案（本地化由调用面负责）。 */
@@ -29,7 +31,7 @@ export interface ToastProps {
     /** 全不透明停留时长；缺省 3000。 */
     holdMs?: number;
     /** 句尾的行内动作（照着句子的顺序排）。 */
-    actions?: readonly ToastAction[];
+    actions?: readonly ToastAction[] | undefined;
     /** 淡出完成时调用一次：在这里卸载。 */
     onDone: () => void;
 }

package/lib/types/client/ui/icons.d.ts

@@ -12,7 +12,7 @@
 import type { ReactElement } from 'react';
 /** 宿主图标组件的实际使用面：一个方形边长，色走 `currentColor`。 */
 export interface IconProps {
-    size?: number;
+    size?: number | undefined;
 }
 export declare function IconTrashOutlineRegular({ size }: IconProps): ReactElement;
 export declare function IconWarningOutlineRegular({ size }: IconProps): ReactElement;

package/lib/types/client/undo-toast.d.ts

@@ -1,7 +1,8 @@
 /**
  * 撤销提示（docs/ui-spec.md 状态 ③）：删除成功后一条可撤销的横幅。
  *
- * 现场与发布住在 `undo-notices.ts`；本文件只做组件，并把通知台与外部恢复座位组合起来。
+ * 现场与发布住在 `undo-notices.ts`；本文件只做组件：画通知台已有的事实，「撤销」整趟按下交给
+ * `write-seats.ts` 的 `restoreFromUndo`（编排归恢复座位，见 ADR-0018 的边界）。
  * 为什么组件要独立：宿主的菜单行随菜单**一起卸载**（真产物 Menu 的注释原文
  * "the rows unmount with the list"），而提示要在菜单关掉之后还活着。宿主的官方配方同形——
  * 会话行的动作把请求写进一个模块级 store，`shell.overlay` 里的 `workspace.row-toast` 读它。

package/lib/types/client/use-maintenance-section.d.ts

@@ -0,0 +1,52 @@
+import type { RemoteOutcome } from './remote.js';
+/** 一段在飞的动作：检查只读，清理会写。状态行靠它分开说「检查中…」与「清理中…」；`null` = 空闲。 */
+export type MaintenancePhase = 'scanning' | 'cleaning';
+/** 一段维护交给界面的全部：三份读数（报告 / 失败 / 中性提示）、一个确认框、一档忙碌，加四个动作。 */
+export interface MaintenanceSectionView<R> {
+    /** `null` = 还没检查（或上一次检查失败——失败在 `failure` 单独一格，不折成零条）。 */
+    readonly report: R | null;
+    readonly failure: string | null;
+    /** 「这一组已经不在」/ 上一趟清理的回执——不是失败：单独一条中性提示。 */
+    readonly notice: string | null;
+    readonly confirm: boolean;
+    readonly phase: MaintenancePhase | null;
+    /** 段自己给的忙碌（在飞即忙），不再作为 prop 传递。 */
+    readonly busy: boolean;
+    /** 手动检查（也是失败块的重试）。 */
+    scan: () => Promise<void>;
+    /** 唯一开门：先清旧失败与旧提示再开确认框。 */
+    openPreview: () => void;
+    /** 清完必重查；回执句子由 config 拼。 */
+    clean: () => Promise<void>;
+    /** 只收确认框，不碰提示 / 失败。 */
+    cancel: () => void;
+}
+/** `settle` 拼出的这一趟要摆的句子；**缺席的格子表示"不碰"**（重查刚摆上的状态保持原样）。 */
+export interface MaintenanceSettlePlan {
+    readonly notice?: string | null;
+    readonly failure?: string | null;
+}
+export interface MaintenanceSectionConfig<R, C> {
+    /** 手动检查（也是失败块的重试）。交回的已是落地面——glue 用 `callRemote` 包装、不会抛，module 不再包一层。 */
+    scan(): Promise<RemoteOutcome<R>>;
+    /** 清理写动作；入参是点击那一刻的报告（清理输入由各段自己从里面点名）。报告没活可干时
+     *  同步回 `null`：不发请求、只收确认框——"没活"的判据各段不同，是各段的业务。
+     *  同样交回落地面、不抛。`C` 是这一段的回执形状：状态机不认识它，只把它原样递给
+     *  `beforeRescan` / `settle`，段那边就不必把 `outcome.value` 擦回 `unknown` 再 `as` 一次。 */
+    clean(report: R): Promise<RemoteOutcome<C>> | null;
+    /** 清理落地后、必发的重查起飞前先摆的读数；`null` = 不动。附件段用它把"已清空"先收成 0：
+     *  旧报告不再可信，别让旧横幅在重查飞着时冒充"没清"。 */
+    beforeRescan?(outcome: RemoteOutcome<C>): R | null;
+    /** 检查读不到时的上屏句；本地化前缀各段自己给。 */
+    scanFailureText(message: string): string;
+    /** 这一趟检查**赢了**（没被更晚的检查顶掉）之后顺手收掉的东西；输家不调用。它在赢家的读数
+     *  落地**之前**触发，故只许写自己那份不属于读数的状态。孤儿会话段用它清上一趟清理的附件回执
+     *  ——「收掉旧回执」属于最新读数成立的一部分，放在发请求之前会让被顶掉的输家也清掉赢家的回执。 */
+    onScanWon?: () => void;
+    /** 清理回执（含顶层失败）→ 这一趟的句子。重查赢了才调用；段独有的第二回执（如孤儿会话段顺带
+     *  清掉的附件读数）由它顺手写自己的状态——那不是这台状态机的格子。
+     *  `report` 是**这一趟**点击那一刻的报告：回执要按请求名单逐条判读，名单只能随这一趟交下来；
+     *  段自己存一份"最近一次清理的名单"会在两趟交错时把上一趟的回执按后一趟的名单判读。 */
+    settle(outcome: RemoteOutcome<C>, report: R): MaintenanceSettlePlan;
+}
+export declare function useMaintenanceSection<R, C>(config: MaintenanceSectionConfig<R, C>): MaintenanceSectionView<R>;

package/lib/types/client/use-maintenance.d.ts

@@ -1,43 +1,15 @@
 import type { Translate } from './copy.js';
 import { type AttachmentOrphanReportWire, type OrphanReportWire, type SessionDeleteRemote } from './remote.js';
+import { type MaintenanceSectionView } from './use-maintenance-section.js';
 /** 维护卡只需要这四段：两份报告 + 孤儿会话的批量写 + 孤儿附件的聚合写。 */
 export type MaintenanceDeps = Pick<SessionDeleteRemote, 'scanOrphans' | 'applyOutcomes' | 'scanAttachmentOrphans' | 'cleanAttachmentOrphans'>;
-/** 一段在飞的动作：检查只读，清理会写。状态行靠它分开说「检查中…」与「清理中…」；`null` = 空闲。 */
-export type MaintenancePhase = 'scanning' | 'cleaning';
 export interface Maintenance {
-    readonly orphanReport: OrphanReportWire | null;
-    readonly orphanFailure: string | null;
-    /** 「这一组已经不在」不是失败：单独一条中性提示。 */
-    readonly orphanNotice: string | null;
-    /** 上一趟孤儿会话清理顺带清掉的附件读数（`.dsh` 内独占图片副本）。重查读不出来，和
-     *  `orphanNotice` 一样是过去那一趟的回执；下一次检查 / 清理会被收掉。 */
-    readonly orphanAttachmentNotice: string | null;
-    readonly orphanConfirm: boolean;
-    readonly orphanBusy: boolean;
-    /** 在飞的是检查还是清理；`null` = 空闲。写动作在飞时状态行据此说「清理中…」。 */
-    readonly orphanPhase: MaintenancePhase | null;
-    /** 手动检查（`GET /orphans`）。失败回 `null` + 原文，不折成零条。 */
-    scanOrphans(): Promise<void>;
-    /** 「查看并清理」：先收掉旧提示再开确认框。 */
-    openOrphanPreview(): void;
-    /** `/apply` 的 `orphan-clean`：清完必重查；中性 / 失败 / 部分计数按回执说。 */
-    cleanOrphans(): Promise<void>;
-    setOrphanConfirm(open: boolean): void;
-    readonly attachmentReport: AttachmentOrphanReportWire | null;
-    readonly attachmentFailure: string | null;
-    /** 上一趟清理的回执（已清 / 跳过 / 逐文件失败），重查读不出来。 */
-    readonly attachmentNotice: string | null;
-    readonly attachmentConfirm: boolean;
-    readonly attachmentBusy: boolean;
-    /** 在飞的是检查还是清理；`null` = 空闲。 */
-    readonly attachmentPhase: MaintenancePhase | null;
-    /** 手动检查（`GET /attachment-orphans`）。 */
-    scanAttachmentOrphans(): Promise<void>;
-    /** 「查看并清理」：先收掉旧提示再开确认框。 */
-    openAttachmentPreview(): void;
-    /** `POST /attachment-clean`：清完必重查；`removed` / `failed` / `skipped` 按回执说。 */
-    cleanAttachmentOrphans(): Promise<void>;
-    setAttachmentConfirm(open: boolean): void;
+    /** 孤儿会话段 + 它独有的第二回执：这一趟清理顺带清掉的附件读数（`.dsh` 内独占图片副本）。
+     *  重查读不出来，和段的 `notice` 一样是过去那一趟的回执；下一次检查 / 清理会被收掉。 */
+    readonly orphans: MaintenanceSectionView<OrphanReportWire> & {
+        readonly attachmentNotice: string | null;
+    };
+    readonly attachments: MaintenanceSectionView<AttachmentOrphanReportWire>;
 }
 export declare function useMaintenance({ deps, t }: {
     deps: MaintenanceDeps;

package/lib/types/client/use-trash-panel-controller.d.ts

@@ -1,6 +1,7 @@
 import type { BusyGate } from './busy-gate.js';
 import { type SessionDeleteRemote, type TrashEntryLike } from './remote.js';
-import type { TrashDetailState } from './trash-detail.js';
+import type { TrashEntryWire } from '../shared/wire.js';
+import type { DetailNav, TrashDetailState } from './trash-detail.js';
 import { type TrashQuery } from './use-trash-query.js';
 /** 待确认的动作：一条记录、整个回收站、或多选挑出来的一批（`ids` 已按清单顺序排好）。
  *  类型归状态机，视图只 import 它来渲染。 */
@@ -17,15 +18,16 @@ export type PendingAction = {
     ids: readonly string[];
 };
 /**
- * 控制器要的面。`query` 取五样：清单（选中从它里面找）、`refreshAll`（挂载与显式重试）、
- * `refreshAfterWrite`（失效与写后）、清空（面板的写动作那一半）、`noteAttachmentCleanup`（purge 回执里
+ * 控制器要的面。`query` 取四样：清单（选中从它里面找）、`reload`（挂载、显式重试、失效与写后
+ * 都是同一条读）、清空（面板的写动作那一半）、`noteAttachmentCleanup`（purge 回执里
  * 附件那半句交给查询侧拼句子上屏）。`ordered` 是键盘/自动选中用的"屏幕上的顺序"（只含展开的组），
- * 由面板算好传进来——布局常量不搬进控制器。
+ * 由面板算好传进来——布局常量不搬进控制器。输入的引用**不需稳定**：失效 effect 的判据只有
+ * `revision`，reload 回调经 `useLatest` 读最新那一份（判据住 `store.ts`）。
  */
 export interface TrashPanelControllerInput {
     deps: Pick<SessionDeleteRemote, 'detail' | 'applyOutcomes'>;
     gate: BusyGate;
-    query: Pick<TrashQuery, 'list' | 'refreshAll' | 'refreshAfterWrite' | 'emptyTrash' | 'noteAttachmentCleanup'>;
+    query: Pick<TrashQuery, 'list' | 'reload' | 'emptyTrash' | 'noteAttachmentCleanup'>;
     ordered: readonly TrashEntryLike[];
     canAutoSelect: boolean;
 }
@@ -33,27 +35,46 @@ export interface TrashPanelController {
     readonly busy: boolean;
     readonly selected: TrashEntryLike | null;
     readonly selectedId: string | null;
+    /** 正在看哪个孩子（离清单的详情导航态；null = 看清单选中那条）。单级是设计（ADR-0029）：
+     *  只有一个槽，`openChild` 换槽不叠栈，返回交还清单选中那条。 */
+    readonly childView: TrashEntryWire | null;
+    /** 详情的导航面（开孩子 / 回父）。ADR-0029 单级判据的**唯一实现**：面板只转交它，
+     *  不再自己拼 openChild / parentContext 两个派生块（判据有第二个家，视图与测试就得各自复述语义）。 */
+    readonly detailNav: DetailNav;
+    /** 打开一个孩子（父详情子会话段点进来）：读它的详情，但清单选中不动。 */
+    openChild(child: TrashEntryWire): Promise<void>;
+    /** 回到父详情（详情顶部那颗「返回父会话」；窄档 back/Esc 的第一程也走它）。 */
+    closeChild(): void;
     readonly drilled: boolean;
     readonly detail: TrashDetailState;
+    /** 更早一页正在读（只对当前详情主体有意义：孩子视图开着就是孩子）。 */
+    readonly loadingOlder: boolean;
+    /** 更早一页读失败的原文（只对当前详情主体有意义；正文本身仍是 ready）。 */
+    readonly olderFailure: string | null;
     /** 待确认的那一批（确认框的开合）；确认落地后由控制器收起。 */
     readonly pending: PendingAction | null;
     /** 恢复确认框要摆的这一批（按勾选顺序；清单里已找不到的 id 滤掉）。 */
     readonly pendingEntries: readonly TrashEntryLike[];
     /** 恢复/彻底删除/批量 的失败原文，按条目 id 存：切走再回来还在。 */
     readonly actionFailure: Readonly<Record<string, string>>;
-    select(entry: TrashEntryLike, options?: {
+    /** 下面是面板会**摘下来转交**的动作（导航的 `select`/`back`、确认框的 `cancelPending`）：
+     *  属性声明而不是方法简写，实现体都不读 `this`。方法简写的隐式 `this` 会让 `unbound-method`
+     *  把转交报成可疑；改形状是纯类型面，零运行时改动。 */
+    select: (entry: TrashEntryLike, options?: {
         drill?: boolean;
-    }): Promise<void>;
-    retry(): void;
-    back(): void;
+    }) => Promise<void>;
+    /** 按当前详情的 `olderCursor` 读更早一页，拼到现有块前面。 */
+    loadOlder: () => Promise<void>;
+    retry: () => void;
+    back: () => void;
     /** 构造待确认动作（唯一入口：新增一种确认只改 `PendingAction` 与确认框，不再加一串转调）。 */
-    request(action: PendingAction): void;
-    cancelPending(): void;
+    request: (action: PendingAction) => void;
+    cancelPending: () => void;
     /** 单条恢复（`/apply` 的 N=1）：成功后丢缓存，写完无论成败都重读清单，失败原文落回这一行。 */
-    restore(entry: TrashEntryLike): Promise<void>;
+    restore: (entry: TrashEntryLike) => Promise<void>;
     /** 确认框上的「确认」：按 `pending.kind` 分派到空清或 `confirmApply`。 */
-    confirmPurge(): Promise<void>;
+    confirmPurge: () => Promise<void>;
     /** 一组 id 上的同一个动作：逐条成败落成行上原文/缓存失效，整批只重读一次清单。 */
-    confirmApply(action: 'purge' | 'restore', ids: readonly string[]): Promise<void>;
+    confirmApply: (action: 'purge' | 'restore', ids: readonly string[]) => Promise<void>;
 }
 export declare function useTrashPanelController(input: TrashPanelControllerInput): TrashPanelController;

package/lib/types/client/use-trash-query.d.ts

@@ -29,14 +29,16 @@ export interface TrashQuery {
      *  读数冒充这一趟；删除与恢复不碰它。它是**过去那一趟的回执**、不是清单状态：清单重读读不出来。 */
     readonly attachmentNotice: string | null;
     /** 把一份附件读数摆上屏（`undefined` = 这一趟没有读数，旧提示收掉）；句子怎么拼归这里，调用方只管转交。 */
-    noteAttachmentCleanup(a: AttachmentCleanupWire | undefined): void;
-    /** 重读清单；挂载与显式「重试」用它。面板没有第二条扫描：孤儿检查是设置页维护卡的手动动作。 */
-    refreshAll(): Promise<void>;
-    /** 写后/失效通告：与 `refreshAll` 同一条读。两个名字留着是因为调用点问的是两件事
-     *  （"用户要看现在的"与"别处动过了，跟上"），不是两条路径。清单读失败时旧行进 `unknown`。 */
-    refreshAfterWrite(): Promise<void>;
-    /** 清空回收站（聚合回执）：成功就熄掉撤销横幅并重读，失败就把清单置为未知并摆上原文。交回是否成功。 */
-    emptyTrash(): Promise<boolean>;
+    noteAttachmentCleanup: (a: AttachmentCleanupWire | undefined) => void;
+    /** 重读清单：挂载、显式「重试」、写后与失效通告都走这一条读——问的是同一件事（"清单现在长什么样"）。
+     *  曾经分作 `refreshAll` / `refreshAfterWrite` 两个名字，那是调用点问的两件事（"用户要看现在的"与
+     *  "别处动过了，跟上"），不是两条路径，合一为 `reload`。面板没有第二条扫描：孤儿检查是设置页
+     *  维护卡的手动动作（ADR-0021）。清单读失败时旧行进 `unknown`。 */
+    reload: () => Promise<void>;
+    /** 清空回收站（聚合回执）：成功就熄掉撤销横幅并重读，失败就把清单置为未知并摆上原文。
+     *  三种形状各有意思：`true` = 清空落地了；`false` = 这一趟跑了但没清成（原文已在清单那块上屏）；
+     *  `undefined` = 闸把这一趟挡回来了、什么都没跑（调用方不收框，等在飞那一趟的结论）。 */
+    emptyTrash: () => Promise<boolean | undefined>;
 }
 export declare function useTrashQuery({ deps, t, gate, }: {
     deps: TrashQueryDeps;