@waterwx/dsh-novel-forge 2.1.2-alpha → 2.1.3

package/lib/types/client/panel/outline-markdown.d.ts

@@ -0,0 +1,112 @@
+/**
+ * 大纲 / 正文的轻量 Markdown 解析（零依赖、可离线单测）。
+ *
+ * ## 为什么不用现成的库
+ *
+ * 插件不引第三方依赖（`package.json` 只有宿主 peer），而大纲是**受控文本**：
+ * 内容由本插件自己的 prompt 产出或作者手写，不是任意的用户 markdown。
+ * 拉一个 markdown 库进来（marked / markdown-it ≈ 100KB+）只为一个只读预览，
+ * 不划算；而自己写又必须**只实现真实用到的语法**，否则就是自造半吊子。
+ *
+ * ## 实际要支持什么（由真实产物倒推，不是凭想象）
+ *
+ * 看 `H:/novels/还债疯了/_outline.md` 的真实形态：
+ *  - 大量**中文序号小标题**独立成行：「一、书名与题材定位」「二、金手指与核心机制」。
+ *    旧解析器只认 `#`，这些全被塞进一个 `<p>`，整份大纲在页面上是一堵墙。
+ *  - 顶格书名独占一行（《还债疯了》）后接空行。
+ *  - 冒号开头的**定义式条目**：「人情债与识海：救人即触发…」。
+ *  - LLM 被明确要求**不输出换行符**，所以段落内会挤很长的句子
+ *    （实测最长 700+ 字），必须靠标点断句才读得下去。
+ *
+ * 加上作者手写时会用的：`- / * / 1.` 列表、`**加粗**`、`*斜体*`、`` `代码` ``、
+ * `> 引用`、`|` 表格、`---` 分隔、` ``` ` 代码块。
+ *
+ * ## 设计约束
+ *
+ * 1. **永不抛错**：任何看不懂的输入都退化为普通段落，渲染器不能因为一个畸形
+ *    字符整页白屏。
+ * 2. **纯函数、无 React**：解析结果只含数据，渲染交给调用方。这样解析规则可以
+ *    完全离线验证，不必拉起整个面板。
+ * 3. **行内标记只做切分，不生成 HTML**：返回「片段数组」（普通文本 / 加粗 /
+ *    斜体 / 行内代码），由 React 渲染成元素——绝不用 dangerouslySetInnerHTML。
+ */
+/** 行内片段：把一段文本按 `**粗**` / `*斜*` / `` `码` `` 切分。 */
+export type InlineSpan = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'strong';
+    text: string;
+} | {
+    kind: 'em';
+    text: string;
+} | {
+    kind: 'code';
+    text: string;
+};
+/** 块级节点类型。 */
+export type MdBlock = {
+    type: 'heading';
+    level: 1 | 2 | 3 | 4;
+    spans: InlineSpan[];
+    id: string;
+} | {
+    type: 'para';
+    spans: InlineSpan[];
+    id: string;
+} | {
+    type: 'list';
+    ordered: boolean;
+    items: MdListItem[];
+    id: string;
+} | {
+    type: 'quote';
+    spans: InlineSpan[];
+    id: string;
+} | {
+    type: 'code';
+    lang: string;
+    text: string;
+    id: string;
+} | {
+    type: 'table';
+    header: string[];
+    rows: string[][];
+    id: string;
+} | {
+    type: 'hr';
+    id: string;
+};
+/** 列表项：支持一层嵌套（`- 外层` / `  - 内层`），再深就压平。 */
+export interface MdListItem {
+    /** 主行内容（已解析行内标记）。 */
+    spans: InlineSpan[];
+    /** 嵌套子项。 */
+    children: MdListItem[];
+}
+/** 解析结果。 */
+export interface MdDoc {
+    blocks: MdBlock[];
+    /** 目录项（heading level<=3）。 */
+    toc: Array<{
+        level: number;
+        text: string;
+        id: string;
+    }>;
+}
+/** 去掉 markdown 标记后的纯文本（用于生成目录文字与 slug）。 */
+export declare function stripInline(text: string): string;
+/**
+ * 解析行内标记为片段数组。
+ *
+ * 顺序有讲究：先剥行内代码（其内容不该再被解析），再剥加粗，最后剥斜体。
+ * 未闭合的标记按普通文本处理——宁可少强调，不可渲染出残缺标签。
+ */
+export declare function parseInline(text: string): InlineSpan[];
+/**
+ * 解析一段 Markdown 为块序列。
+ *
+ * @param text - 原始文本。
+ * @returns 块序列 + 目录。
+ */
+export declare function parseMarkdown(text: string): MdDoc;

package/lib/types/client/panel/status-badge.d.ts

@@ -0,0 +1,13 @@
+/** 徽章的语义色调——决定颜色，与具体 CSS 类名解耦。 */
+export type StatusTone = 'pending' | 'active' | 'written' | 'done' | 'rejected' | 'error';
+/** 色调 → CSS module 类名（两处界面共用同一份，不再各写一遍）。 */
+export declare const BADGE_CLASS: Record<StatusTone, string>;
+/**
+ * 取某章状态的色调。
+ *
+ * 未知状态一律按 `error` 处理：显式失败优于静默伪装成"正常/待写"。
+ * 状态集合由 protocol 定义并可能扩展，所以这里不能写死穷尽分支。
+ */
+export declare function statusTone(status: string): StatusTone;
+/** 取某章状态的徽章类名。 */
+export declare function statusBadgeClass(status: string): string;

package/lib/types/client/panel/storage-parse.d.ts

@@ -0,0 +1,46 @@
+/**
+ * localStorage 值的解析 / 校验（纯函数，零依赖，可离线单测）。
+ *
+ * ## 为什么单独成文件
+ *
+ * `usePersistentState.ts` 需要 React，而本插件的测试环境是 node
+ * （vitest.config.ts `environment: 'node'`，无 jsdom），import React 会直接失败。
+ * 但这个模块真正容易出错的地方**不在 hook 本身**（`useState` + `useCallback`
+ * 是标准写法），而在**校验逻辑**：一旦校验写漏，脏数据会被写进 localStorage，
+ * 之后每次启动都读到它，且没有恢复路径——作者只能手动清缓存。
+ *
+ * 所以把校验做成零依赖的纯函数，让「最容易错的部分」可以完整验证。
+ */
+/**
+ * 受枚举约束的字符串。
+ *
+ * @param raw - localStorage 里的原始字符串。
+ * @param allowed - 合法值集合。
+ * @returns 合法则返回该值；否则 undefined（调用方应回落默认值）。
+ */
+export declare function parseEnum<T extends string>(raw: string, allowed: readonly T[]): T | undefined;
+/**
+ * 受上下界约束的整数。
+ *
+ * 先 `Number.isFinite` 再四舍五入——顺序很关键：先取整的话
+ * `NaN` 会被 `Math.round` 变成 `NaN` 之外的怪值，或被 `||` 当成 0 误收。
+ *
+ * @param raw - localStorage 里的原始字符串。
+ * @param min - 下界（含）。
+ * @param max - 上界（含）。
+ * @returns 合法则返回整数；否则 undefined。
+ */
+export declare function parseIntInRange(raw: string, min: number, max: number): number | undefined;
+/**
+ * 解析一个 JSON 对象，字段逐个校验，缺失/错类型回落默认值。
+ *
+ * 用于悬浮窗位置尺寸这类**结构固定但字段可能残缺**的数据。之所以不直接
+ * `JSON.parse` 后强转（`as {x?: unknown}`），是因为那样 `NaN` / 字符串 / `null`
+ * 都会被放过去，最终变成一个 `left: NaNpx` 的悬浮窗——不报错，只是不见了。
+ *
+ * @param raw - localStorage 里的原始字符串。
+ * @param keys - 需要的字段名。
+ * @param fallback - 各字段的默认值（与 keys 一一对应）。
+ * @returns 校验通过的完整对象；解析失败返回 undefined。
+ */
+export declare function parseNumberRecord<K extends string>(raw: string, keys: readonly K[], fallback: Record<K, number>): Record<K, number> | undefined;

package/lib/types/client/panel/toast.d.ts

@@ -0,0 +1,2 @@
+/** 弹一条 toast。kind: 'done'（翡翠勾）/ 'error'（红叉）/ 'info'（中性）。 */
+export declare function showToast(text: string, kind?: 'done' | 'error' | 'info'): void;

package/lib/types/client/panel/usePersistentState.d.ts

@@ -0,0 +1,17 @@
+export interface PersistentStateOptions<T> {
+    /** localStorage 键。 */
+    key: string;
+    /** 读取时的解析与校验；返回 undefined 表示「数据不可用」，用默认值。 */
+    parse: (raw: string) => T | undefined;
+    /** 写入时的序列化。 */
+    serialize: (value: T) => string;
+    /** 读取失败 / 无数据 / 校验不过时的默认值。 */
+    fallback: T;
+}
+/**
+ * 一个与 localStorage 同步的 state。
+ *
+ * @returns `[当前值, 设置函数]`。设置函数会同步写回 localStorage。
+ */
+export declare function usePersistentState<T>(options: PersistentStateOptions<T>): [T, (next: T | ((prev: T) => T)) => void];
+export { parseEnum, parseIntInRange } from './storage-parse.ts';

package/lib/types/client/panel/views.d.ts

@@ -1,36 +1,15 @@
-/**
- * 纯展示组件（views）：所有状态与事件处理器都留在 NovelPanel，
- * 这里只接收 props 渲染。便于单独维护与复用。
- */
 import type { ReactElement } from 'react';
-import type { AuditIssue, Plotline, PlotlineHealthReport, PlotlinePlan, RoleRecord, RoleStatusCard } from '../../protocol.ts';
-/** 统计格：状态摘要条 / 资产健康通用。 */
-export declare function StatCell(props: {
-    label: string;
-    value: string;
-    detail: string;
-    /** 值颜色（可选）。 */
-    valueColor?: string;
-    /** 值字号覆盖（如长文本用 13）。 */
-    valueFontSize?: number;
-    /** detail 悬浮提示（可选）。 */
-    detailTitle?: string;
-}): ReactElement;
-/** 待办队列行。 */
-export declare function TodoRow(props: {
-    tone: 'danger' | 'warning' | 'info' | 'success';
-    title: string;
-    description: string;
-    actionLabel: string;
-    disabled: boolean;
-    onAction: () => void;
-}): ReactElement;
-/** 全书质检问题行。 */
-export declare function AuditIssueRow(props: {
-    issue: AuditIssue;
-    disabled: boolean;
-    onFix: () => void;
-}): ReactElement;
+import type { Plotline, PlotlineHealthReport, PlotlinePlan, RoleRecord, RoleStatusCard } from '../../protocol.ts';
+/** 滑轨胶囊导航（B5-5）：active 高亮为滑动指示块，随选中项平移。 */
+export declare function SlideNav<T extends string>(props: {
+    ariaLabel: string;
+    items: ReadonlyArray<{
+        id: T;
+        label: ReactElement | string;
+    }>;
+    active: T;
+    onSelect: (id: T) => void;
+}): JSX.Element;
 /** 剧情线卡片（列表主体）。 */
 export declare function PlotlineCard(props: {
     line: Plotline;
@@ -54,24 +33,31 @@ export declare function RoleCard(props: {
     onEdit: () => void;
     onRemove: () => void;
 }): ReactElement;
-/** 🩺 剧情健康检查报告面板。 */
+/**  剧情健康检查报告面板。 */
 export declare function PlotlineHealthPanel(props: {
     report: PlotlineHealthReport;
     disabled: boolean;
     onPlan: () => void;
     onClose: () => void;
 }): ReactElement;
-/** ✨ AI 剧情方案面板。 */
+/**  剧情方案面板。 */
 export declare function PlotlinePlanPanel(props: {
     plan: PlotlinePlan;
     disabled: boolean;
     onAdopt: (suggestion: Plotline) => void;
     onClose: () => void;
 }): ReactElement;
-/** ✨ AI 建议剧情线面板。 */
+/**  建议剧情线面板。 */
 export declare function PlotlineSuggestionPanel(props: {
     suggestions: Plotline[];
     disabled: boolean;
     onAdopt: (suggestion: Plotline) => void;
     onClose: () => void;
 }): ReactElement;
+/** 空状态基元：图标 + 标题 + 可选提示。compact 变体用于列表/卡片内嵌场景。 */
+export declare function EmptyState(props: {
+    icon?: string;
+    title: string;
+    hint?: string;
+    compact?: boolean;
+}): ReactElement;

package/lib/types/client/run-status.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 运行状态芯片：固定在页面顶部的「小说工坊生成状态」小徽标。
+ * 轮询 /run/status，实时显示 生成中/暂停/完成/停止/出错 + 当前章号；
+ * 点击可打开/关闭小说工坊面板。独立 DOM 注入，不触碰主面板逻辑，挂载失败静默降级。
+ * 显示偏好（关 / 仅生成中暂停时 / 总是）存在 localStorage，见 chip-prefs.ts：
+ * 书架页「设置 · 全局 → 外观与主题」里有对应下拉，选择即时生效（跨标签页也同步）。
+ *
+ * P0 重写说明（原实现的三个问题）：
+ *   1. 整块背景染状态色 + 固定白字 → 浅色主题下「白字配亮底」对比度崩坏。
+ *      现在改为「玻璃底 + 主题前景色文字 + 左侧状态色点」，状态只由色点承载，
+ *      文字永远跟随主题，任何深浅色下都可读。
+ *   2. 样式写死在 JS 的 inline style 里，切主题纹丝不动。
+ *      现在改用 CSS Module class，配色走 --nf-chip-* 令牌，
+ *      由 body[data-ds-dark-theme] 跟随宿主深浅色。
+ *   3. role="button" 却没有 tabindex、没有键盘处理，键盘用户完全用不了。
+ *      现在补 tabindex + Enter/Space 激活 + aria-label/live。
+ */
+import type { NovelApi } from './api.ts';
+import type { PanelController } from './panel/controller.ts';
+/** 生成一个固定顶部的状态芯片并开始轮询。返回 dispose。 */
+export declare function mountRunStatus(controller: PanelController, api: NovelApi): () => void;

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

@@ -4,8 +4,6 @@
  * sibling plugin entries and self-heals via MutationObserver.
  */
 import type { PanelController } from './panel/controller.ts';
-/** Stable data attribute identifying the injected entry row. */
-export declare const ENTRY_SELECTOR = "[data-dsh-novelforge-entry]";
 /**
  * Mount the sidebar entry, waiting for the shell and self-healing on
  * re-renders.

package/lib/types/digest-parse.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 章节「摘要 + 事实 + 时间线」合并抽取的**解析收敛层**。
+ *
+ * ## 为什么独立成文件
+ *
+ * 合并后一次 LLM 调用要parse 三个字段，最容易出错的地方不是「怎么调模型」，
+ * 而是**「模型返回畸形 JSON 时怎么收敛」**：字段缺失、类型不对、数组里混null、
+ * runaway 长文本。任何一项坏掉都不该拖垮另外两项。
+ *
+ * 这层逻辑必须能被离线验证，而 engine.ts 依赖宿主包 `@deepseek-ai/dsh-llm`
+ * （脱离 dsh 环境直接import 失败）。所以规则层放这里，保持零依赖。
+ */
+/** 把 LLM 返回的原始 facts 收敛为合法事实条目（过滤过短项、截断超长项）。 */
+export declare function parseFactLines(raw: unknown): string[];
+/** 把 LLM 返回的原始 timeline 收敛为对象数组（剔除非对象成员）。 */
+export declare function parseTimelineItems(raw: unknown): Record<string, unknown>[];
+/**
+ * timeline 单项的字段映射：缺失/错类型一律回落到安全默认，绝不产出 undefined 字段。
+ *
+ * @param item - 模型给出的原始项。
+ * @param index - 该项在数组中的下标；模型没给 `order` 时用它兜底，保证章内序号连续。
+ */
+export declare function mapTimelineItem(item: Record<string, unknown>, index: number): {
+    time: string;
+    order: number;
+    place: string;
+    characters: string[];
+    event: string;
+};

package/lib/types/docx-core.d.ts

@@ -0,0 +1,16 @@
+/**
+ * docx 文本提取共享核心：服务端（src/docx.ts）与浏览器端（src/client/docx.ts）
+ * 共用 XML → 纯文本的解析逻辑，避免两份实现漂移。
+ * zip 解压入口因运行时不同（fflate vs fflate/browser，浏览器端必须走 browser
+ * 入口以避开 node:module 的 require 探测）留在两端各自处理。
+ */
+/** 解码 docx 正文实际会用到的少量 XML 实体。 */
+export declare function decodeEntities(text: string): string;
+/**
+ * 从 word/document.xml 的 XML 字符串提取纯文本：每个 <w:p> 段落一行，
+ * <w:tab>/<w:br> 保留为空白符；表格与嵌套结构按文档顺序拍平
+ * （它们的段落同样是 <w:p>）。
+ * @param xml - document.xml 解码后的字符串。
+ * @returns 正文文本（空文本时抛错）。
+ */
+export declare function extractDocxTextFromXml(xml: string): string;

package/lib/types/docx.d.ts

@@ -2,11 +2,10 @@
  * docx outline extraction: a .docx is a zip whose word/document.xml holds the
  * body text in <w:t> runs inside <w:p> paragraphs. We unzip with fflate and
  * walk the XML with a tiny tokenizer — no heavyweight XML/DOM dependency.
+ * XML 解析共享核心在 ./docx-core.ts（与浏览器端同源）。
  */
 /**
- * Extract plain text from a docx buffer: one line per <w:p> paragraph, with
- * <w:tab>/<w:br> preserved as whitespace. Tables and nested structures are
- * flattened in document order (their paragraphs are just <w:p> too).
+ * Extract plain text from a docx buffer: one line per <w:p> paragraph.
  * @param buffer - the raw .docx bytes.
  * @returns the body text.
  */