@sendevia/pi-ask-author 1.0.1 → 1.0.3

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) 终端交互式请示扩展。
 

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;
+}

package/{src/format.ts → dist/format.d.ts}

@@ -8,10 +8,6 @@
  *
  * 依赖方向：format.ts → texts.ts（布局常量与文案字典）
  */
-
-import { truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import { LAYOUT_CONFIG, TEXTS } from "./texts.js";
-
 /**
  * 将数值收敛至闭区间 `[min, max]`
  * @param value - 待收敛数值
@@ -19,10 +15,7 @@ import { LAYOUT_CONFIG, TEXTS } from "./texts.js";
  * @param max - 区间上界
  * @returns 位于 `[min, max]` 区间内的数值；`min > max` 时恒返回 `min`
  */
-export function clamp(value: number, min: number, max: number): number {
-  return Math.max(min, Math.min(value, max));
-}
-
+export declare function clamp(value: number, min: number, max: number): number;
 /**
  * 将视口滚动位移收敛至合法区间，防止越界滚动造成空白视口
  * @param offset - 待收敛的 0-based 起始行位移
@@ -30,10 +23,7 @@ export function clamp(value: number, min: number, max: number): number {
  * @param viewHeight - 可视行数（调用方必须传入非负值）
  * @returns `[0, max(0, total - viewHeight)]` 内的位移；列表为空或内容不足一屏（`total <= viewHeight`）时恒为 0
  */
-export function clampWindowOffset(offset: number, total: number, viewHeight: number): number {
-  return clamp(offset, 0, Math.max(0, total - viewHeight));
-}
-
+export declare function clampWindowOffset(offset: number, total: number, viewHeight: number): number;
 /**
  * 截取视口可视行切片（仅复制可视区，不遍历非可视区数据）
  * @param lines - 完整内容行数组（只读，不修改入参）
@@ -41,33 +31,13 @@ export function clampWindowOffset(offset: number, total: number, viewHeight: num
  * @param viewHeight - 可视行数
  * @returns 至多 `viewHeight` 行的新数组；`lines` 为空、`viewHeight <= 0` 或 `offset` 越过末行时返回空数组
  */
-export function windowSlice<T>(lines: readonly T[], offset: number, viewHeight: number): T[] {
-  return lines.slice(offset, offset + viewHeight);
-}
-
+export declare function windowSlice<T>(lines: readonly T[], offset: number, viewHeight: number): T[];
 /**
  * 清除回车符并将制表符规整为双空格（纯文本规整，不剥离 ANSI 控制序列）
  * @param str - 原始文本；缺省时按空串处理
  * @returns 规整后的文本（入参为 undefined 时返回空串，永不返回 undefined）
  */
-export function cleanText(str: string | undefined): string {
-  return str ? str.replace(/\t/g, "  ").replace(/\r/g, "") : "";
-}
-
-/**
- * 剥离终端转义与控制字符（防止 ANSI 注入污染 TUI 渲染管线）
- * 覆盖 OSC（BEL/ST 终止）、CSI、双字符转义与残余 C0 控制字符；换行符保留，由调用方决定单行化时机
- * @param str - 已由 `cleanText` 规整的字符串（无回车与制表符）
- * @returns 剥离全部转义序列与残余 C0 控制字符（含 DEL `\x7f`）的字符串；换行符 `\n` 保留
- */
-function stripControlSequences(str: string): string {
-  return str
-    .replace(/\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)/g, "")
-    .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
-    .replace(/\x1b[@-_]/g, "")
-    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, "");
-}
-
+export declare function cleanText(str: string | undefined): string;
 /**
  * 裁剪空白并剥离终端控制序列；纯空白或剥离后为空的输入均返回 undefined
  * 约定：返回值要么是非空字符串，要么是 undefined——调用方的 `?? 兜底` 不会漏接空串
@@ -75,49 +45,13 @@ function stripControlSequences(str: string): string {
  * @param str - 原始不可信文本；缺省时返回 undefined
  * @returns 清洗后的非空字符串；纯空白或剥离控制序列后为空时返回 undefined
  */
-export function cleanOptional(str: string | undefined): string | undefined {
-  const t = str?.trim();
-  return t ? stripControlSequences(cleanText(t)) || undefined : undefined;
-}
-
+export declare function cleanOptional(str: string | undefined): string | undefined;
 /**
  * 尝试 `JSON.parse`；非字符串原样返回，解析失败返回 undefined
  * @param value - 待解析值
  * @returns 解析结果或原值；字符串长度（UTF-16 码元）超过 1_000_000 时直接返回 undefined
  */
-export function parseJson(value: unknown): unknown {
-  if (typeof value === "string") {
-    if (value.length > 1_000_000) return undefined;
-    try {
-      return JSON.parse(value);
-    } catch {
-      return undefined;
-    }
-  }
-  return value;
-}
-
-/**
- * 悬挂缩进折行：首行携带前缀，后续折行左缘与前缀可见宽度一致
- * 宽度按 CJK 全角与 ANSI 转义精确计算（`visibleWidth` / `wrapTextWithAnsi`）
- * @param prefix - 首行前缀（后续行以同宽空格悬挂缩进）
- * @param text - 待折行文本
- * @param width - 可视总宽度（列）；调用方必须传入 `>= 1`，`width <= 0` 时不截断前缀
- * @returns 折行后的行数组；`text` 无法产出任何行时返回 `[prefix]`（前缀非空）或空数组
- */
-function hangText(prefix: string, text: string, width: number): string[] {
-  let prefixW = visibleWidth(prefix);
-  if (prefixW >= width && width > 0) {
-    prefix = truncateToWidth(prefix, width - 1);
-    prefixW = visibleWidth(prefix);
-  }
-  const availableW = Math.max(1, width - prefixW);
-  const pad = " ".repeat(prefixW);
-  const wrapped = wrapTextWithAnsi(text, availableW);
-  if (wrapped.length === 0) return prefix ? [prefix] : [];
-  return wrapped.map((line, i) => (i === 0 ? prefix + line : pad + line));
-}
-
+export declare function parseJson(value: unknown): unknown;
 /**
  * 将悬挂折行结果原地追加至目标行数组
  * @param lines - 目标行数组（原地追加）
@@ -125,77 +59,37 @@ function hangText(prefix: string, text: string, width: number): string[] {
  * @param width - 可视总宽度
  * @param prefix - 首行前缀（后续折行等宽悬挂缩进）
  */
-export function pushWrapped(lines: string[], text: string, width: number, prefix = ""): void {
-  lines.push(...hangText(prefix, text, width));
-}
-
+export declare function pushWrapped(lines: string[], text: string, width: number, prefix?: string): void;
 /**
  * 单行安全截断，保证可见宽度不超过 `maxWidth`（超宽部分截断，并沿用 `truncateToWidth` 的默认省略号 `...`）
  * @param str - 原始文本（先经 `cleanText` 清除回车与制表符）
  * @param maxWidth - 最大可见宽度（列）；`<= 0` 时返回空串
  * @returns 可见宽度不超过 `maxWidth` 的单行文本（未超宽时原样返回，不做补齐）
  */
-export function safeLine(str: string, maxWidth: number): string {
-  if (maxWidth <= 0) return "";
-  const cleaned = cleanText(str);
-  return visibleWidth(cleaned) > maxWidth ? truncateToWidth(cleaned, maxWidth) : cleaned;
-}
-
+export declare function safeLine(str: string, maxWidth: number): string;
 /**
  * 按可见宽度填充至指定宽度（支持 CJK 与 ANSI）
  * @param str - 原始文本（先经 `cleanText` 清除回车与制表符）
  * @param targetWidth - 目标可见宽度（列）；`<= 0` 时返回空串
  * @returns 可见宽度不超过 `targetWidth` 的单行文本：不足则右补空格，超宽则截断并以默认省略号 `...` 收尾（含全角字符时结果可能略窄于 `targetWidth`）
  */
-export function padToVisibleWidth(str: string, targetWidth: number): string {
-  if (targetWidth <= 0) return "";
-  const cleaned = cleanText(str);
-  const w = visibleWidth(cleaned);
-  if (w >= targetWidth) return truncateToWidth(cleaned, targetWidth);
-  return cleaned + " ".repeat(targetWidth - w);
-}
-
+export declare function padToVisibleWidth(str: string, targetWidth: number): string;
 /**
  * 生成指定宽度的横向分隔线
  * @param width - 目标可见宽度（列）
  * @param char - 填充字符（默认 `LAYOUT_CONFIG.dividerThin`，每字符宽度按 1 列计）
  * @returns `width <= 0` 时返回空串，否则返回 `char` 重复 `width` 次
  */
-export function divider(width: number, char: string = LAYOUT_CONFIG.dividerThin): string {
-  return width > 0 ? char.repeat(width) : "";
-}
-
+export declare function divider(width: number, char?: string): string;
 /**
  * 极限压缩正文草稿/分镜头为高密度单行 LLM 指令：逐行剥离行首 Markdown 标题标识与引用符，折叠连续空白，各片段以 `TEXTS.markdown.draftSegmentSeparator` 连接
  * @param preview - 原始草稿/分镜头文本；缺省或全空白时返回 undefined
  * @returns 单行分镜头指令；无有效片段时返回 undefined
  */
-export function compressDraftPreview(preview: string | undefined): string | undefined {
-  if (!preview) return undefined;
-  const cleaned = cleanText(preview);
-  if (!cleaned.trim()) return undefined;
-
-  const segments = cleaned
-    .split("\n")
-    .map((line) => {
-      let l = line.trim();
-      if (!l) return "";
-      // 单次交替剥离行首任意层级的 Markdown 标题标识与引用符（`> # 标题` 需同时去除两类前缀，故不可分成两次行首替换）
-      l = l.replace(/^(?:[>#]+\s*)+/, "");
-      l = l.replace(/\s+/g, " ");
-      return l;
-    })
-    .filter(Boolean);
-
-  if (segments.length === 0) return undefined;
-  return segments.join(TEXTS.markdown.draftSegmentSeparator);
-}
-
+export declare function compressDraftPreview(preview: string | undefined): string | undefined;
 /**
  * 折叠不可信文本的换行与连续空白为单空格：LLM 生成的描述/批注含换行会破坏返回封套的行结构
  * @param text - 原始文本
  * @returns 单行文本（所有 `\s+` 折叠为一个空格并去除首尾空白；纯空白输入返回空串）
  */
-export function toSingleLine(text: string): string {
-  return text.replace(/\s+/g, " ").trim();
-}
+export declare function toSingleLine(text: string): string;

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @file index.ts
+ * @description 作者请示插件入口：注册 `ask_author` 工具与 `/ask-author` 命令
+ *
+ * 核心架构特性：
+ * - 四类出口（取消 / 结构化错误 / 运行期异常 / 正常完成）由四个结果工厂统一产出；其中取消、结构化错误与运行期异常三类共享 `ResultContext` 的缺省收敛，完成结果由表单模型直接供给
+ * - `prepareArguments` 防御性清洗兼容批量问卷与单题平铺双模式；返回文本恒以 `TEXTS.markdown` 的固定封套前缀开头（`[Author Decision Finalized]` / `[Author Decision Cancelled]` / `[Author Consultation Error]`），前缀字节稳定利于 Prompt Cache 命中
+ * - 性能与生命周期：调用卡片按 args 身份记忆化派生、结果卡片复用槽位 `lastComponent`；AbortSignal 经组件级联取消；本文件不注册任何监听器与定时器，`AskAuthorComponent.dispose()`（幂等）负责回收定时器、Abort 监听与全部缓存池
+ *
+ * 依赖方向：index.ts 为 11 模块单向依赖图（theme → texts → {format, schema} → {model, sanitize} → {novel-markdown, view-rows, view-summary} → component → index）的入口；旁支 `sanitize.ts` 仅由本文件装配（`prepareArguments` 与 `renderCall` 两处）
+ */
+import { type AgentToolResult, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type AskAuthorResult, type NormalizedQuestion } from "./model.js";
+/** `ask_author` 工具执行结果结构（基于 Pi 官方 `AgentToolResult` 结构特化） */
+export type AskAuthorToolResult = AgentToolResult<AskAuthorResult>;
+/** 结果构造上下文：题目快照与标题/描述的可选覆盖（缺省值统一由 {@link resolveResultContext} 收敛） */
+export interface ResultContext {
+    /** 题目快照（缺省空数组：取消/错误可能发生在模型构建前） */
+    questions?: NormalizedQuestion[];
+    /** 问卷总标题（缺省 `TEXTS.fallbacks.defaultFormTitle`） */
+    formTitle?: string;
+    /** 问卷全局描述（缺省 undefined，不携带该字段内容） */
+    formDescription?: string;
+}
+/** 调用卡片派生数据：与主题无关的纯计算结果（颜色合成每帧按当前主题现场计算） */
+export interface CallCardData {
+    /** 卡片标题（已清洗的 `formTitle`） */
+    title: string;
+    /** 计数标签（多题模式为 `2 题 • 6 选项`，单题模式仅 `6 选项`） */
+    countLabel: string;
+}
+/**
+ * `renderCall` 记忆化状态载荷：宿主按工具执行行创建一次、跨帧复用的可变对象（`ToolRenderContext.state`，同一行的 `renderCall` 与 `renderResult` 共享该实例）
+ * 以 **args 对象身份**为键（`cachedArgs` 记录身份、`cachedCard` 记录派生数据），依赖宿主「流式补全整体替换 `args` 引用」的不变量（宿主经 `ToolExecutionComponent.updateArgs` 赋入新对象）：身份变化即失效重新计算；若宿主原地改写同一对象，缓存将滞留旧数据
+ */
+export interface CallRenderState {
+    /** 上一次派生所用的 args 对象身份（仅作 `===` 引用比对，不读取任何属性） */
+    cachedArgs?: object;
+    /** 与 `cachedArgs` 配对的派生数据；两者身份同时命中时直接复用 */
+    cachedCard?: CallCardData;
+}
+/**
+ * `ask-author` 扩展插件主入口工厂（仅完成注册，启动期不执行任何交互）
+ * @param pi - Pi 扩展运行时 API 实例
+ */
+export default function askAuthorExtension(pi: ExtensionAPI): void;
+export { askAuthorExtension };
+export { AskAuthorFormModel, type AskAuthorResult, type AuthorAnswerItem, type NormalizedQuestion } from "./model.js";
+export { AskAuthorParams, type RawParams } from "./schema.js";
+export { sanitizeAskAuthorArgs } from "./sanitize.js";
+export { TEXTS, LAYOUT_CONFIG, ICONS } from "./texts.js";