@sendevia/pi-ask-author 1.0.0 → 1.0.2

package/README.md

@@ -1,8 +1,8 @@
 # pi-ask-author
 
-[![pi-package](https://img.shields.io/badge/pi--package-extension-blue.svg)](https://pi.dev/packages)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+![NPM Version](https://img.shields.io/npm/v/%40sendevia%2Fpi-ask-author?style=flat-square&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F%40sendevia%2Fpi-ask-author)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue.svg?style=flat-square)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
 专为作家、轻小说创作者与 AI 协同写作设计的 [Pi](https://github.com/earendil-works/pi-coding-agent) 终端交互式请示扩展。
 
@@ -15,7 +15,7 @@
 - 🖥️ **双栏响应式 TUI 交互**
   - **左栏选项决策**：直观展示单选/多选状态、完成度指示徽标、选项标签与专属批注标识。
   - **右栏实时预览**：光标移动时即时联动渲染当前选项的**剧情因果推导**与 **Markdown 正文草稿预览**。
-  - **自适应视口**：终端宽度不小于 72 列时启用双栏，窄屏下改为单栏内联展开与折叠。
+  - **自适应视口**：终端宽度不足时启用双栏，窄屏下改为单栏内联展开与折叠。
 - 📖 **小说级富文本与草稿高亮**
   - 内置紧凑轻量的终端 Markdown 渲染与小说语法高亮，完整支持 bold、italic、删除线、行内代码、引用区块。
   - 对中文小说台词（引号内对话高亮）与分段排版做了专门处理，作者可以在终端内直接检视行文节奏与语感。
@@ -26,11 +26,11 @@
   - **单题平铺模式**：快速发起单点决策（如重要剧情分歧、结局走向）。
   - **多题批量问卷模式**：支持在单次弹窗内汇集多个关联决策（如脱离路线 + 战利品搜刮 + 下章基调），配有顶部 Tab 标签栏与完成度总览页（Summary Tab），作者在一处完成全部确认。
 - 🎯 **确定性 LLM 封套与指令蒸馏 (Deterministic Envelopes)**
-  - 工具返回给 LLM 的文本采用固定的结构化 Markdown 封套（`[Author Decision Finalized]` / `[Author Decision Cancelled]` / `[Author Consultation Error]`），前缀稳定，便于 Prompt Cache 命中。
+  - 工具返回给 LLM 的文本采用固定的结构化 Markdown 封套（`[Author Decision Finalized]` / `[Author Decision Cancelled]` / `[Author Consultation Error]`），前缀稳定，便于缓存命中。
   - **草稿指令提取 (Draft Directives)**：选中的选项草稿预览会自动提炼为紧凑的单行 `[Draft directive: ...]` 指令，直接供 LLM 在后续正文执笔中原样复用或参考。
   - 尾部附带执行指令，要求模型不再寒暄，直接进入下一步正文写作。
 - ⚡ **高性能与极简依赖**
-  - 严格遵守 Pi 官方扩展生态规范，核心依赖 `@earendil-works/pi-coding-agent`、`@earendil-works/pi-tui` 与 `typebox` 均列为 `peerDependencies`，不引入其他第三方依赖。
+  - 严格遵守 Pi 官方扩展生态规范，不引入其他第三方依赖。
   - 资源回收：生命周期严格绑定 AbortSignal，定时器与事件监听幂等清理，渲染缓存按尺寸与状态键失效。
 
 ---
@@ -85,114 +85,6 @@ pi -e ./path/to/pi-ask-author
 
 ---
 
-## 🤖 智能体提示词与调用规范 (Agent Guidelines)
-
-在系统提示词或 Skill 中声明以下规则，可以引导 LLM 按预期调用该工具：
-
-```markdown
-Whenever plot branches, character decisions, scene atmosphere, or outline directions need confirmation:
-
-- Call `ask_author` directly without conversational preambles.
-- Always provide a concise `formTitle`.
-- Use the `questions` array to batch interrelated decisions into ONE invocation; avoid consecutive single calls.
-- Include causal plot deductions in `description` and scene draft excerpts in `preview`.
-- Omit optional default fields (`id`, `description`, `minSelect`, `maxSelect`, `allowEmpty`, `allowCustom`) to maximize token economy and prompt caching.
-```
-
-### 参数示例：多题批量问卷
-
-```json
-{
-  "formTitle": "第七幕逃生抉择与伏笔分配",
-  "questions": [
-    {
-      "title": "第一幕脱离路线选择",
-      "options": [
-        {
-          "label": "炸毁地下蒸汽管网断后",
-          "description": "引爆管网阻断追兵，代价是彻底暴露行踪并波及城区管线。",
-          "preview": "“听着，艾略特，”雷恩咬紧牙关按下阀门，“我数到三，你往排污井跳！”\n蒸汽在接缝处发出濒临极限的尖啸，暗红警示灯将二人面孔映得如同凝血。"
-        },
-        { "label": "遁入旧排水暗渠迂回脱离", "description": "周旋于暗渠迷宫，隐匿行踪但有遭遇感染体风险。" }
-      ]
-    },
-    {
-      "title": "主角搜刮战利品与剧情伏笔（多选）",
-      "multiSelect": true,
-      "options": [
-        { "label": "过载超频模块", "description": "战斗中可触发高热熔毁，但易过载自伤。" },
-        { "label": "加密军方识别铭牌", "description": "揭示军方秘密人体实验编号，引发信任危机。" }
-      ]
-    }
-  ]
-}
-```
-
-### 返回封套示例
-
-```text
-[Author Decision Finalized]
-1. [第一幕脱离路线选择]: 【炸毁地下蒸汽管网断后】引爆管网阻断追兵，代价是彻底暴露行踪并波及城区管线。 [Author note: 注意描写气压表的指针爆表碎裂细节] [Draft directive: '听着，艾略特，'雷恩咬紧牙关按下阀门，'我数到三，你往排污井跳！' / 蒸汽在接缝处发出濒临极限的尖啸，暗红警示灯将二人面孔映得如同凝血。]
-2. [主角搜刮战利品与剧情伏笔（多选）]: 【过载超频模块】战斗中可触发高热熔毁，但易过载自伤。; 【加密军方识别铭牌】揭示军方秘密人体实验编号，引发信任危机。
-Execute workflow and writing strictly according to the author decisions and draft directives above without conversational acknowledgments.
-```
-
----
-
-## 🏗️ 架构与模块设计 (Architecture)
-
-插件采用严格的单向无环依赖图分层构建，保证各个组件职责清晰、高内聚且易于测试：
-
-```mermaid
-flowchart LR
-  theme --> texts
-  theme --> novel-markdown
-  theme --> view-rows
-  theme --> view-summary
-  theme --> component
-  texts --> format
-  texts --> schema
-  texts --> model
-  texts --> novel-markdown
-  texts --> view-rows
-  texts --> view-summary
-  texts --> component
-  texts --> index
-  format --> sanitize
-  format --> model
-  format --> novel-markdown
-  format --> view-rows
-  format --> view-summary
-  format --> component
-  format --> index
-  schema --> sanitize
-  schema --> model
-  schema --> index
-  model --> novel-markdown
-  model --> view-rows
-  model --> view-summary
-  model --> component
-  model --> index
-  sanitize --> index
-  novel-markdown --> component
-  view-rows --> component
-  view-summary --> component
-  component --> index
-```
-
-箭头由被依赖模块指向依赖它的模块（`A --> B` 表示 `B` 导入 `A`）。
-
-- **`index.ts`**：扩展主入口，注册 `ask_author` 工具与 `/ask-author` 命令，负责结果工厂构造与卡片记忆化渲染。
-- **`component.ts`**：TUI 状态机核心组件，自行维护按键派生、光标记忆、视口滑动窗口与双栏排版。
-- **`model.ts`**：问卷表单数据模型，负责规范化题目前期推导、选项校验与答案序列化。
-- **`schema.ts`**：基于 TypeBox 构建的静态类型与运行时 Schema 单一数据源。
-- **`texts.ts`**：常量、终端图标、小说语法表与面向作者/LLM 双向文案的集中字典。
-- **`novel-markdown.ts`**：小说语法终端高亮层，在原生 Markdown 引擎解析前注入语义标记。
-- **`sanitize.ts`**：入参防御性清洗与别名兼容。
-- **`view-rows.ts` / `view-summary.ts`**：列表行与总览页的排版生成器。
-
----
-
 ## 🧪 开发与质量验证 (Development)
 
 本项目开启 TypeScript 严格模式：

package/dist/component.d.ts

@@ -0,0 +1,322 @@
+/**
+ * @file component.ts
+ * @description `ask_author` 交互式 TUI 主组件（双栏问卷视图与答卷总览）
+ *
+ * 核心架构特性：
+ * - 宽屏双栏 / 窄屏单栏自适应：`renderWidth >= LAYOUT_CONFIG.splitViewMinWidth` 且题目含富内容时走双栏，否则降级单栏紧凑列表；预览与总览视口行数随终端高度收缩
+ * - 多级缓存失效：整屏（尺寸键 + 状态突变清空）、总览 / Tab 栏 / 左栏 / 菜单项（`revision` 键）、预览池（内容键）；视口切片 O(1)；`render()` 无 I/O，Markdown 渲染仅发生在派生缓存未命中时
+ * - 逐题独立光标记忆与 `1~9` 跳转题目；内置编辑器透传 Focusable 以定位 IME 候选框
+ * - Esc / Ctrl+C 双通道取消（输入模式二次确认）；定时器、Abort 监听与缓存池全量回收
+ *
+ * 渲染纯度不变量：`render()` 及其可达被调函数禁止写入语义状态（`currentTab`、光标与各 `*ScrollOffset`、`inputMode`、`editTarget`、`editorEscArmed`、`statusMessage`、`isFinished`）；滚动位移归一化一律归属输入路径
+ * 可写入透明备忘：`cached*`、`previewCache`、`tabCache`、`leftColCache`、`summaryCachedLines`、`menuCache`、`previewViewportObservation` 均为「渲染输入的纯函数」缓存
+ *
+ * 依赖方向：component.ts → theme / texts / format / model / novel-markdown / view-rows / view-summary；本组件只做按键路由、视口切片与整屏缓存编排
+ */
+import { type Component, type Focusable, type TUI } from "@earendil-works/pi-tui";
+import { AskAuthorFormModel, type AskAuthorResult } from "./model.js";
+import type { Theme } from "./theme.js";
+/**
+ * `ask_author` 交互式 TUI 组件（问卷作答与答卷总览）
+ * 状态机：作答突变经 `AskAuthorFormModel`，`revision` 驱动两级缓存失效；`render()` 只写入透明备忘 / 观察缓存，绝不写回滚动位移等语义状态；`dispose()` 幂等且只设置 `disposed`，`finish()` 以 `isFinished` 保证 `done` 至多投递一次
+ */
+export declare class AskAuthorComponent implements Component, Focusable {
+    /** Focusable 接口要求：输入模式焦点指示 */
+    private _focused;
+    /** 当前焦点状态（仅 `true` 时透传内置 Editor 以定位 IME 候选框） */
+    get focused(): boolean;
+    /**
+     * 设置焦点状态并级联透传至内置 Editor（同值为无操作）
+     * @param value - 目标焦点状态；同时失效整屏 / Tab 栏 / 左栏缓存
+     */
+    set focused(value: boolean);
+    /** TUI 上下文 */
+    private readonly tui;
+    /** 主题 */
+    private readonly theme;
+    /** 问卷模型（作答状态唯一权威，mutation 自动推进 revision） */
+    private readonly model;
+    /** 结果达成回调 */
+    private readonly done;
+    /** 当前 Tab 索引（0-based；questionCount 为总览确认页） */
+    private currentTab;
+    /** 每道题独立的光标索引记忆表 */
+    private readonly cursorByTab;
+    /** 当前题目菜单内选中的条目索引 */
+    private currentOptionIndex;
+    /** 左侧菜单列表滚动位移（行） */
+    private listScrollOffset;
+    /** 详情预览区滚动位移（行） */
+    private previewScrollOffset;
+    /** 答卷总览页滚动位移（行） */
+    private summaryScrollOffset;
+    /** 是否处于补充说明文本输入模式 */
+    private inputMode;
+    /** Esc 丢弃确认武装标记：编辑器非空时首次 Esc 仅武装，再次 Esc 才丢弃内容 */
+    private editorEscArmed;
+    /** 底部临时状态通知文案 */
+    private statusMessage;
+    /** 状态通知定时器 */
+    private statusTimer;
+    /** 是否已终结（终结后忽略一切输入，且 `done` 不再投递） */
+    private isFinished;
+    /** 是否已卸载回收（幂等标记；卸载后忽略迟到输入且拒绝再绑定 Abort 监听；`done` 投递不受本标记阻断，见 {@link dispose}） */
+    private disposed;
+    /** AbortSignal 监听绑定对象 */
+    private abortBinding?;
+    /** 整屏缓存键：调用方真实列宽（输出截断依据） */
+    private cachedWidth?;
+    /** 整屏缓存键：布局列宽 `max(20, width)`（折行依据，20 列为窄终端宽度下限） */
+    private cachedLayoutWidth?;
+    /** 整屏缓存键：终端行数（视口行数随之自适应） */
+    private cachedHeight?;
+    /** 整屏已格式化终端行缓存 */
+    private cachedLines?;
+    /** 预览框完整渲染行缓存池（键：题号+条目身份+列宽+补充说明；超 {@link PREVIEW_CACHE_CAPACITY} 按插入序淘汰） */
+    private readonly previewCache;
+    /** 总览页未切片内容行缓存（键：列宽 + `revision`） */
+    private summaryCachedLines?;
+    /** Tab 栏行缓存（键：当前页 + `revision` + 列宽） */
+    private tabCache?;
+    /** 左栏菜单行缓存（键：题号 + 光标 + 位移 + `revision` + 左栏宽） */
+    private leftColCache?;
+    /** 菜单项派生缓存（键：题号 + `revision`，消除 render/输入路径重复构建） */
+    private menuCache?;
+    /** 上一帧预览视口的观察元数据（渲染写入、输入路径读取以归一化位移） */
+    private previewViewportObservation?;
+    /** 当前编辑器针对的目标（题目整体或指定选项） */
+    private editTarget?;
+    /** 内置补充说明编辑器实例 */
+    private readonly editor;
+    /**
+     * 构造交互式 TUI 主组件
+     * @param tui - TUI 上下文
+     * @param theme - 主题
+     * @param model - 问卷模型
+     * @param done - 结果回调
+     */
+    constructor(tui: TUI, theme: Theme, model: AskAuthorFormModel, done: (result: AskAuthorResult) => void);
+    /**
+     * 绑定中止信号（幂等，至多绑定一次）
+     * @param signal - 外层 AbortSignal；缺省 / 已绑定 / 已卸载时直接返回
+     */
+    bindAbortSignal(signal?: AbortSignal): void;
+    /**
+     * 清理定时器、Abort 监听与全部缓存池（幂等）
+     * 只设置 `disposed`、不设置 `isFinished`（资源回收 ≠ `done` 已投递），否则宿主先卸载而 `done` 未投递时挂起
+     */
+    dispose(): void;
+    /** 清空整屏帧缓存（列宽 / 行数键；不触发重绘） */
+    private clearFrameCaches;
+    /** 清空全部派生缓存（`revision` 键与内容键：预览池 / 总览 / Tab 栏 / 左栏 / 菜单项；不触发重绘） */
+    private clearDerivedCaches;
+    /** 状态突变时失效整屏缓存并请求重绘（保留派生缓存池复用） */
+    private touch;
+    /** 作答变更后的统一失效入口：模型已推进 revision，此处清空全部派生缓存 */
+    private touchDerived;
+    /**
+     * Component 接口约定：宿主重绘上下文（主题切换 / 需从头重绘）时清空全部渲染缓存
+     * 终端尺寸变化不调用本方法（宿主 resize 仅 `requestRender`），由整屏缓存键绑定列宽与行数自然失效
+     */
+    invalidate(): void;
+    /** 清理临时状态定时器（清空引用以便后续 setStatus 重新计时） */
+    private clearStatusTimer;
+    /**
+     * 触发底部临时状态通知
+     * @param msg - 提示文案（取自 `TEXTS.status`，不做控制字符清洗）
+     */
+    private setStatus;
+    /**
+     * 终结作答流程并触发 `done`（至多投递一次）
+     * `isFinished` 单守卫防止重复投递；不以 `disposed` 阻断（资源已回收但 `done` 未投递时仍须结算），跳转入 {@link dispose}
+     * @param cancelled - 是否用户主动取消
+     */
+    finish(cancelled: boolean): void;
+    /** Tab 总页数（题目页 + 总览提交页） */
+    private get totalTabs();
+    /** 当前 Tab 是否为答卷总览提交页 */
+    private get isSubmitTab();
+    /** 终端可视行数（`tui.terminal.rows` 不可用或非正数时兜底 24） */
+    private get terminalRows();
+    /** 总览页视口行数上限（随终端高度自适应；区间 `[4, LAYOUT_CONFIG.summaryPageSize]`） */
+    private get summaryPageSize();
+    /** 双栏右侧预览视口行数上限（区间 `[6, LAYOUT_CONFIG.splitPreviewHeight]`） */
+    private get splitPreviewHeight();
+    /** 单栏内联预览视口行数上限（区间 `[3, LAYOUT_CONFIG.singlePreviewHeight]`） */
+    private get singlePreviewHeight();
+    /**
+     * 当前题目的菜单项
+     * @returns 菜单项数组；按 `(题号, revision)` 记忆化，命中时零分配复用
+     */
+    private getMenuItems;
+    /**
+     * 当前聚焦菜单项
+     * @returns 越界安全查询结果；无菜单项或索引越界时为 undefined
+     */
+    private currentMenuItem;
+    /**
+     * 切换题目 / 总览页 Tab，重置滚动位移并按 `cursorByTab` 恢复光标记忆
+     * @param newTab - 目标 Tab 索引（0-based；questionCount 为总览页；同页为无操作）
+     */
+    private switchTab;
+    /** 收敛光标至合法区间并同步左栏滚动窗口，保证聚焦项可见（菜单项为空时直接返回） */
+    private adjustScrollForCurrentOption;
+    /**
+     * 移动菜单光标并同步滚动窗口，重置预览位移
+     * @param target - 绝对索引或 `{ delta }` 相对位移（越界由 clamp 收敛，菜单为空时无操作）
+     */
+    private moveCursor;
+    /**
+     * 当前光标默认的编辑目标
+     * @returns 聚焦预设选项时为该选项，否则为题目整体
+     */
+    private getEditTargetForCurrentSelection;
+    /**
+     * 打开补充说明编辑器（选项专属或题目整体）
+     * @param target - 编辑目标；缺省时按当前聚焦项推导（题目缺失或禁用补充说明时无操作）
+     */
+    private openCustomEditor;
+    /** 关闭编辑器并还原非输入模式状态（清空缓冲与焦点；幂等） */
+    private closeEditor;
+    /**
+     * 确认当前题并跳转下一题 / 总览页（聚焦预设选项时先经模型写入选中）
+     * @param currentItem - 聚焦菜单项
+     * @param q - 当前题目（未达提交下限时仅提示状态栏，不切页）
+     */
+    private confirmAndAdvance;
+    /**
+     * Component 接口约定：键盘事件三级路由（输入模式 → 全局键 → 分视图）
+     * Esc 与 Ctrl+C 同为取消键（宿主不会自行中止工具信号）：常规模式直接 `finish(true)`，输入模式下编辑器非空时首次仅武装丢弃确认
+     * @param data - 终端按键序列
+     */
+    handleInput(data: string): void;
+    /**
+     * 题目作答页常规键路由（移动 / 勾选 / 前进 / 补充说明；子路由均为先匹配先消费）
+     * @param data - 终端按键序列
+     */
+    private handleQuestionInput;
+    /**
+     * 补充说明快捷键路由（`n`/`e` 补充当前聚焦项、`N` 题目整体补充、`x`/Delete 清空）
+     * @param q - 当前题目
+     * @param data - 按键序列
+     * @returns 是否已消费该按键
+     */
+    private handleNoteShortcut;
+    /**
+     * 预览区垂直滚动键（PgUp / PgDn / 方括号 / Alt+上下）
+     * 滚动位移归一化归属输入路径：以渲染帧写入的 {@link previewViewportObservation} 为界经 `clampWindowOffset` 收敛（缺观察元数据时按单栏预览高度退化）
+     * @param data - 按键序列
+     * @returns 是否已消费该按键
+     */
+    private handlePreviewScroll;
+    /**
+     * 选项菜单光标移动键（↑↓ / jk / Home / End）
+     * @param data - 按键序列
+     * @returns 是否已消费该按键
+     */
+    private handleCursorNavigation;
+    /**
+     * 多选模式下 `a` 键全选 / 清空已选项
+     * @param q - 当前题目
+     * @param data - 按键序列
+     * @returns 是否已消费该按键
+     */
+    private handleSelectAllShortcut;
+    /**
+     * 触发聚焦条目主动作（唯一入口为空格键：选项勾选 / 打开补充说明 / 推进确认）
+     * @param currentItem - 聚焦菜单项
+     * @param q - 当前题目（选项命中上限时仅提示状态栏）
+     */
+    private activateMenuItem;
+    /**
+     * 总览页键路由（滚动与回车提交；`Ctrl+S` 同义提交）
+     * 空格更改为向下滚动（防止习惯性翻页误提交）；位移归一化归属本路径，上界获取自 `summaryCachedLines` 总行数与 `summaryPageSize`，`End` 仅设置超大值，由后续输入收敛
+     * @param data - 按键序列
+     */
+    private handleSummaryInput;
+    /**
+     * 计算总览页滚动步长
+     * @param data - 按键序列
+     * @returns 行位移（正下负上，0 为无动作）
+     */
+    private summaryScrollStep;
+    /**
+     * Component 接口约定：渲染整屏行（带整屏缓存）
+     * 缓存键绑定真实列宽、布局列宽与终端行数（窄于 20 列时二者截断范围不同，仅绑定 layoutWidth 会串帧；行数变化必须整体重新计算）；本方法及可达被调函数绝不写入语义状态，仅刷新透明备忘 / 观察缓存
+     * @param width - 终端真实可视宽度（布局宽度下限 20 列）
+     * @returns 不超过 width 的终端行数组（命中缓存时直接返回）
+     */
+    render(width: number): string[];
+    /**
+     * 原地追加底部状态通知行（无文案时不追加，仅包含通知行与前面的空行）
+     * @param lines - 输出行数组（原地追加）
+     */
+    private pushStatusMessage;
+    /**
+     * 渲染答卷总览与确认提交页（完成状态 / 已选项 / 补充说明 / 提交指引）
+     * 内容行由 `view-summary.ts` 构建并按 `(列宽, revision)` 缓存于 `summaryCachedLines`，本方法只做 O(1) 切片；位移在本地收敛，绝不写回 `summaryScrollOffset`（写入只发生在输入路径）
+     * @param lines - 输出行数组
+     * @param renderWidth - 终端布局列宽
+     */
+    private renderSubmitSummary;
+    /**
+     * 渲染补充说明编辑器全屏模式（标题 / 上下文背景 / 编辑框）
+     * @param lines - 输出行数组
+     * @param renderWidth - 终端可视宽度
+     */
+    private renderInputMode;
+    /**
+     * 渲染常规题目作答视图（自适应双栏分屏或单栏紧凑列表）
+     * @param lines - 输出行数组
+     * @param renderWidth - 终端可视宽度
+     */
+    private renderQuestionView;
+    /**
+     * 获取聚焦条目的预渲染完整内容行（`previewCache` 透明备忘缓存，跨条目 / 切换题目零重复解析）
+     * @param item - 目标菜单项
+     * @param customText - 题目整体补充说明
+     * @param optionNote - 选项专属补充说明
+     * @param targetWidth - 预览可用列宽
+     * @returns 未切片的完整内容行数组；`item` 缺省时返回空数组
+     */
+    private previewContentLines;
+    /**
+     * 计算并切片本帧预览框行（纯计算，不写回语义状态）
+     * 位移由 `previewScrollOffset` 与本帧总行数在本地收敛；本帧观察元数据写入 {@link previewViewportObservation} 供输入路径归一化位移
+     * @param item - 目标菜单项
+     * @param customText - 题目整体补充说明
+     * @param optionNote - 选项专属补充说明
+     * @param targetWidth - 预览可用列宽
+     * @param viewHeight - 视口最大行数
+     * @returns 本帧可视内容行（含底部滚动信息行）
+     */
+    private buildPreviewBox;
+    /**
+     * 对预渲染完整内容行做 O(1) 滑动窗口切片并附加底部行号信息
+     * @param fullLines - 已折行完整内容行
+     * @param scrollOffset - 已由 {@link clampWindowOffset} 收敛的起始行位移
+     * @param viewHeight - 视口最大行数
+     * @param targetWidth - 预览可用列宽
+     * @returns 视口内容行与滚动信息行
+     */
+    private slicePreviewBoxLines;
+    /**
+     * 渲染双栏视图（左选项菜单 + 右推演 / 分镜预览框）
+     * @param lines - 输出行数组
+     * @param q - 当前题目
+     * @param st - 作答状态
+     * @param items - 菜单项
+     * @param renderWidth - 终端可用宽度（不足侧补空行至两栏等高）
+     */
+    private renderSplitView;
+    /**
+     * 遍历输出菜单项行，单栏模式下在聚焦项下方内联展开预览
+     * @param lines - 输出行数组
+     * @param items - 菜单项
+     * @param q - 当前题目
+     * @param st - 作答状态
+     * @param rowWidth - 选项行可用列宽
+     * @param expandFocused - 是否展开聚焦项预览（窗口外条目不访问）
+     */
+    private pushListItems;
+}