@waterwx/dsh-novel-forge 2.1.1-alpha → 2.1.1

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

@@ -2,4 +2,4 @@ import type { NovelApi } from '../api.ts';
 export declare function AdaptModeView({ api, onOpenBook }: {
     api: NovelApi;
     onOpenBook?: (id: string) => void;
-}): any;
+}): import("react").JSX.Element;

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

@@ -0,0 +1 @@
+export declare function AiTag(): JSX.Element;

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

@@ -8,5 +8,5 @@ export interface AssetsTabProps {
 /** 写作资产子页签。 */
 type AssetSubTab = 'genre' | 'progression' | 'templates' | 'rules' | 'style';
 /** 写作资产页签。 */
-export declare function AssetsTab({ api, initialTab }: AssetsTabProps): any;
+export declare function AssetsTab({ api, initialTab }: AssetsTabProps): import("react").JSX.Element;
 export {};

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

@@ -1,7 +1,10 @@
 import type { NovelApi } from '../api.ts';
+import type { StageInfo } from '../../protocol.ts';
 /** Props. */
 export interface AssistantTabProps {
     api: NovelApi;
+    /** 宿主算出的创作阶段（/status.stage）：让作者在同一屏看到「现在该做什么」。 */
+    stage?: StageInfo | null;
 }
 /** The assistant conversation tab. */
-export declare function AssistantTab({ api }: AssistantTabProps): any;
+export declare function AssistantTab({ api, stage }: AssistantTabProps): import("react").JSX.Element;

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

@@ -1,4 +1,4 @@
 import type { NovelApi } from '../api.ts';
 export declare function AuthorAssetsView({ api }: {
     api: NovelApi;
-}): any;
+}): import("react").JSX.Element;

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

@@ -1,7 +1,17 @@
 import type { NovelApi } from '../api.ts';
 import type { BookshelfSnapshot } from '../../protocol.ts';
 import { type ProgressLine } from './ProgressConsole.tsx';
-export declare function AuthorHome({ api, shelf, onOpenBook, onReadBook, onAddBook, onImportBook, onOpenSettings, onTheme, onBackground, onOpacity, onEndfieldAccent, adaptEnabled, progress, busy, busyLabel, liveBar, onClearProgress, onUseIdea }: {
+export declare function AuthorHome({ api, shelf, onOpenBook, onReadBook, onAddBook, onImportBook, onBackground, progress, busy, busyLabel, liveBar, onClearProgress, onUseIdea, themeMode, themeDensity, onToggleMode, onChangeThemeMode, onChangeThemeDensity }: {
+    /** 当前显示模式（顶栏「墨纸 / 纸白」切换用）。 */
+    themeMode?: 'system' | 'light' | 'dark';
+    /** 当前界面密度。 */
+    themeDensity?: 'comfort' | 'compact' | 'spacious';
+    /** 切换墨纸 / 纸白（由 NovelPanel 落 localStorage）。 */
+    onToggleMode?: () => void;
+    /** 改变全局显示模式（联动整个面板）。 */
+    onChangeThemeMode: (m: 'system' | 'light' | 'dark') => void;
+    /** 改变全局界面密度（联动整个面板）。 */
+    onChangeThemeDensity: (d: 'comfort' | 'compact' | 'spacious') => void;
     api: NovelApi;
     shelf: BookshelfSnapshot;
     onOpenBook: (id: string) => void;
@@ -10,18 +20,8 @@ export declare function AuthorHome({ api, shelf, onOpenBook, onReadBook, onAddBo
     onImportBook: () => void;
     /** 创意灵感 → 采纳某个灵感带入开书向导。 */
     onUseIdea?: (idea: import('../../protocol.ts').IdeaInspirationResult['ideas'][number]) => void;
-    /** 兼容旧入口：首页设置现为独立设置页，此回调保留但不再使用。 */
-    onOpenSettings?: () => void;
-    /** 主题/模式/密度变化回调（供面板根容器实时生效）。 */
-    onTheme?: (theme: 'liquid' | 'neumorph' | 'macos' | 'clay' | 'endfield', mode: 'system' | 'light' | 'dark', density: 'comfort' | 'compact' | 'spacious') => void;
     /** 自定义背景变化回调。 */
     onBackground?: (bg: string | undefined, blur: number) => void;
-    /** 玻璃透明度变化回调。 */
-    onOpacity?: (n: number) => void;
-    /** 终末地强调色变化回调。 */
-    onEndfieldAccent?: (accent: 'valley' | 'wuling') => void;
-    /** 是否启用改编模式（默认 false=隐藏入口）。 */
-    adaptEnabled?: boolean;
     /** AI 进度实时状态（与书内共享同一份）。 */
     progress?: ProgressLine[];
     busy?: boolean;
@@ -31,4 +31,4 @@ export declare function AuthorHome({ api, shelf, onOpenBook, onReadBook, onAddBo
         ratio?: number;
     } | null;
     onClearProgress?: () => void;
-}): any;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import type { ReactElement } from 'react';
+export interface CmdAction {
+    icon: string;
+    label: string;
+    hint?: string;
+    run: () => void;
+}
+export declare function CmdPalette({ open, onClose, actions }: {
+    open: boolean;
+    onClose: () => void;
+    actions: CmdAction[];
+}): ReactElement | null;

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

@@ -10,4 +10,4 @@ export declare function CreateBookView({ api, onBack, onCreated, initialIdea, in
     initialIdea?: string;
     /** 从「创意灵感」带过来的初始书名。 */
     initialName?: string;
-}): any;
+}): import("react").JSX.Element;

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

@@ -1,4 +1,4 @@
 import type { NovelApi } from '../api.ts';
 export declare function GlobalAssetLibraryView({ api }: {
     api: NovelApi;
-}): any;
+}): import("react").JSX.Element;

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

@@ -4,4 +4,4 @@ export declare function ImportModal({ api, onClose, onImported, }: {
     onClose: () => void;
     /** 导入成功并已激活该书后回调（刷新书架）。 */
     onImported: () => void | Promise<void>;
-}): any;
+}): import("react").JSX.Element;

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

@@ -1,5 +1,13 @@
 /**
  * 「实时调用 / LIVE」—— 内嵌到 AI 进度窗的下半区（详情层），不再独立浮窗。
  * 连接 /llm-live/stream，按 LLM 调用分组展示模型实时输出。
+ *
+ * 除实时输出外，这里还承担两件与「花了多少」有关的事：
+ *   1) 每次调用显示 token 用量（输入↑ / 输出↓ / 思考）与耗时、首字耗时；
+ *   2) 「查看 Prompt」按 sessionId 拉取这次调用**实际发送**的 system / user。
+ * 顶部另有一条「本次运行」累计条（进程内，重启归零）。
+ *
+ * 状态色全部走 panel.module.css 的 .lfPill / .lfDot（主题令牌 + --nf-streaming），
+ * 不再内联硬编码色；布局性 inline style 保留（均为令牌引用或动态值）。
  */
 export default function LiveFeedLog(): JSX.Element;

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

@@ -1,7 +1,7 @@
 import type { NovelApi } from '../api.ts';
 import type { SavedModel } from '../../protocol.ts';
-/** 目录不可用时回退的内置预设（历史行为）。 */
-export declare const FALLBACK_MODEL_PRESETS: readonly ["deepseek-v4-flash", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner"];
+/** 目录不可用时回退的内置预设（对齐当前模型目录）。 */
+export declare const FALLBACK_MODEL_PRESETS: readonly ["deepseek-flash", "deepseek-v4-pro", "deepseek-chat", "deepseek-reasoner"];
 export interface ModelManagerProps {
     api: NovelApi;
     provider: string;

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

@@ -1,7 +1,12 @@
 import type { NovelApi } from '../api.ts';
 import type { PanelController } from './controller.ts';
+/**
+ * 面板宽度低于此值时自动折叠左侧导航。
+ * 依据：.panelNav 占 216px，内容区留到 ~680px 才不至于把正文挤成竖排。
+ * 宿主中列宽度 ≠ 视口宽度（用户可拖拽侧边栏），所以必须用实测宽度而非媒体查询。
+ */
 /** The panel's tab identifiers. */
-export type NovelTab = 'workflow' | 'overview' | 'blurb' | 'plan' | 'bible' | 'world' | 'foreshadow' | 'assistant' | 'settings' | 'characters' | 'roles' | 'facts' | 'plotlines' | 'reviews' | 'progress' | 'breakdown' | 'director' | 'knowledge' | 'assetsGenre' | 'assetsProgression' | 'assetsTemplates' | 'assetsRules' | 'assetsStyle' | 'run' | 'manhua' | 'book' | 'assets';
+export type NovelTab = 'workflow' | 'overview' | 'blurb' | 'plan' | 'bible' | 'world' | 'foreshadow' | 'assistant' | 'settings' | 'characters' | 'roles' | 'facts' | 'plotlines' | 'reviews' | 'progress' | 'breakdown' | 'director' | 'knowledge' | 'assetsGenre' | 'assetsProgression' | 'assetsTemplates' | 'assetsRules' | 'assetsStyle' | 'run' | 'book' | 'assets';
 /** Panel shell props. */
 export interface NovelPanelProps {
     /** The panel state owner (open/close/toggle). */
@@ -10,4 +15,4 @@ export interface NovelPanelProps {
     api: NovelApi;
 }
 /** The novel-forge panel. */
-export declare function NovelPanel({ controller, api }: NovelPanelProps): any;
+export declare function NovelPanel({ controller, api }: NovelPanelProps): import("react").JSX.Element;

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

@@ -0,0 +1,18 @@
+/** 墨案统一页头：eyebrow(11 大写窄) + 衬线大标题 + 一句说明 + 主/次动作。
+ *  每个视图只用一个 PageHeader，消灭"各自为政"的页面标题。
+ *  图标用 lucide 16 (单色)，标题旁禁止 emoji；标题用衬线 Display（书卷感）。 */
+import type { ReactNode } from 'react';
+export declare function PageHeader({ eyebrow, title, icon, sub, actions, right }: {
+    /** 页眉小标（大写窄，可选，如 "BOOKSHELF"）。 */
+    eyebrow?: string;
+    /** 页面大标题（衬线 Display）。 */
+    title: string;
+    /** lucide 图标（单色，16px），可选。 */
+    icon?: ReactNode;
+    /** 一句话辅助说明（meta）。 */
+    sub?: string;
+    /** 右侧主/次按钮组。 */
+    actions?: ReactNode;
+    /** 标题右上（如 AI 微签）。 */
+    right?: ReactNode;
+}): JSX.Element;

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

@@ -14,4 +14,4 @@ export declare function ProgressConsole({ progress, busy, busyLabel, liveBar, on
         ratio?: number;
     } | null;
     onClear: () => void;
-}): any;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,11 @@
+/**
+ * 提示词槽位：给作者留几个**安全可改**的位置来微调本书表达偏好。
+ *
+ * 边界写在界面上：槽位只**追加偏好**，不能覆盖道藏、写作红线、九条内容合规红线、
+ * 反 AI 规则与阶段契约 —— 这些由宿主锁定。清空即恢复默认。
+ */
+import type { NovelApi } from '../api.ts';
+export interface PromptSlotsViewProps {
+    api: NovelApi;
+}
+export default function PromptSlotsView({ api }: PromptSlotsViewProps): JSX.Element;

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

@@ -5,4 +5,4 @@ export declare function ReaderView({ api, project, onBack, onOpenWorkspace, }: {
     project: ProjectState;
     onBack: () => void;
     onOpenWorkspace: () => void;
-}): any;
+}): import("react").JSX.Element;

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

@@ -2,4 +2,4 @@ import type { NovelApi } from '../api.ts';
 export declare function RunPanel({ api, totalChapters }: {
     api: NovelApi;
     totalChapters: number;
-}): any;
+}): import("react").JSX.Element;

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

@@ -1,16 +1,19 @@
 import type { NovelApi } from '../api.ts';
-type SettingsTab = 'model' | 'writing' | 'image' | 'files' | 'appearance';
-type ThemeMode = 'system' | 'light' | 'dark';
-type ThemeName = 'liquid' | 'neumorph' | 'macos' | 'clay' | 'endfield';
-type EndfieldAccent = 'valley' | 'wuling';
-type ThemeDensity = 'comfort' | 'compact' | 'spacious';
-export declare function SettingsView({ api, onTheme, onSettingsTab, onEditorFontSize, onBackground, onOpacity, onEndfieldAccent }: {
+type SettingsTab = 'model' | 'files' | 'appearance';
+export declare function SettingsView({ api, variant, onSettingsTab, onEditorFontSize, onBackground, themeMode, themeDensity, onChangeThemeMode, onChangeThemeDensity }: {
     api: NovelApi;
-    onTheme?: (theme: ThemeName, mode: ThemeMode, density: ThemeDensity) => void;
+    /** page = 全屏 SubPage（保留给旧入口）；drawer = 右滑抽屉内容（无壳）。 */
+    variant?: 'page' | 'drawer';
     onSettingsTab?: (tab: SettingsTab) => void;
     onEditorFontSize?: (n: number) => void;
     onBackground?: (bg: string | undefined, blur: number) => void;
-    onOpacity?: (n: number) => void;
-    onEndfieldAccent?: (accent: EndfieldAccent) => void;
-}): any;
+    /** 全局显示模式（联动整个面板，NovelPanel 落 localStorage）。 */
+    themeMode: 'system' | 'light' | 'dark';
+    /** 全局界面密度。 */
+    themeDensity: 'comfort' | 'compact' | 'spacious';
+    /** 改变全局显示模式。 */
+    onChangeThemeMode: (m: 'system' | 'light' | 'dark') => void;
+    /** 改变全局界面密度。 */
+    onChangeThemeDensity: (d: 'comfort' | 'compact' | 'spacious') => void;
+}): import("react").JSX.Element;
 export {};

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

@@ -1,9 +1,16 @@
+/**
+ * 书架首页视图：书卡网格（封面/书名/简介/进度）+ 搜索筛选 + 开书入口。
+ * 进入小说工坊默认展示；点击书卡进入该书工作台，＋ 进入开书向导页。
+ */
+import { type ReactNode } from 'react';
 import type { NovelApi } from '../api.ts';
 import type { BookshelfSnapshot } from '../../protocol.ts';
 /** 书架首页。 */
-export declare function ShelfView({ api, shelf, onOpenBook, onReadBook, onAddBook, onImportBook, }: {
+export declare function ShelfView({ api, shelf, onOpenBook, onReadBook, onAddBook, onImportBook, onOpenAdapt, toolbarExtra, }: {
     api: NovelApi;
     shelf: BookshelfSnapshot;
+    /** 书架工具行右端插槽：组入口按钮由 AuthorHome 下放（创作 / 灵感策划 / 资产）。 */
+    toolbarExtra?: ReactNode;
     /** 点击书卡：激活该书并进入工作台。 */
     onOpenBook: (id: string) => void;
     /** 点击「阅读」：激活该书并进入沉浸式阅读页。 */
@@ -12,4 +19,6 @@ export declare function ShelfView({ api, shelf, onOpenBook, onReadBook, onAddBoo
     onAddBook: () => void;
     /** 点击「导入」：打开导入弹窗（已有项目目录 / txt/md 全本）。 */
     onImportBook: () => void;
-}): any;
+    /** 点击「改编模式」：进入改编六步向导（入口收在书架页头，与导入并排）。 */
+    onOpenAdapt?: () => void;
+}): import("react").JSX.Element;

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

@@ -0,0 +1,27 @@
+/**
+ * 统一子页骨架（1:1 对齐 demo-subpages.html 的 .subpage / .subpage-head / .subpage-body）。
+ *
+ * 所有作者级与书内子页都应套这层壳：
+ *   - head：返回钮（可选）+ 大标题 + meta + 右侧操作区
+ *   - body：页面内容（内部按 demo 用 .card / .box / .grid / .row 等块）
+ * 业务逻辑继续留在各自的 View 组件里，这里只负责「壳」。
+ */
+import type { ReactNode } from 'react';
+export declare function SubPage(props: {
+    /** 页面大标题（衬线 display 档）。 */
+    title: string;
+    /** 标题右侧的说明行（如「4 本书 · 当前书《X》」）。 */
+    meta?: ReactNode;
+    /** 返回钮：作者级返回书架，书内返回总编台。 */
+    back?: {
+        label: string;
+        onClick: () => void;
+    };
+    /** 页头右侧操作区（主 CTA 放最右）。 */
+    actions?: ReactNode;
+    /** 主题系统局部模式（透传到根 div 的 data-nf-mode，供设置页等预览明暗）。 */
+    dataNfMode?: 'light' | 'dark';
+    /** 主题系统局部密度（透传到根 div 的 data-nf-density）。 */
+    dataNfDensity?: 'comfort' | 'compact' | 'spacious';
+    children: ReactNode;
+}): JSX.Element;

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

@@ -0,0 +1,18 @@
+/**
+ * 张力曲线：把「每章该有多紧」画出来并可逐章调整。
+ *
+ * 图上是三条线：
+ *   参考（虚线，形状预设） / 目标（实线，作者或规划设定） / 实际（散点，审稿打分）。
+ * 下方列出规则核对发现的曲线级问题（连续同值、高位不回落、长期低位、实际偏离目标）。
+ *
+ * 张力只影响写作提示词里的"松紧"指引，不改变任何校验规则。
+ */
+import type { NovelApi } from '../api.ts';
+export interface TensionViewProps {
+    api: NovelApi;
+    /** 一键按建议修订（合并审稿/张力/时间线后改这一章；由父级统一发起）。 */
+    onRevise?: (chapterNo: number) => void;
+    /** 外部忙碌态（修订进行中时禁用按钮）。 */
+    busy?: boolean;
+}
+export default function TensionView({ api, onRevise, busy: outerBusy }: TensionViewProps): JSX.Element;

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

@@ -0,0 +1,18 @@
+/**
+ * 故事时间线：把逐章抽取的「时间点 / 地点 / 在场角色 / 事件」按章节顺序排开，
+ * 带规则初筛 + AI 复核的矛盾清单，并支持就地修正（手改后标记为 manual）。
+ *
+ * 与「编年录」的分工：编年录记事实状态，这里记**顺序**——专门抓时间倒流、
+ * 地点瞬移、跨度不合理这类长篇最容易崩的地方。
+ */
+import type { NovelApi } from '../api.ts';
+export interface TimelineViewProps {
+    api: NovelApi;
+    /** 章节号列表（用于「抽取本章」下拉）。 */
+    chapters: number[];
+    /** 一键按建议修订（合并审稿/时间线/张力后改这一章；由父级统一发起）。 */
+    onRevise?: (chapterNo: number) => void;
+    /** 外部忙碌态（修订进行中时禁用按钮）。 */
+    busy?: boolean;
+}
+export default function TimelineView({ api, chapters, onRevise, busy: outerBusy }: TimelineViewProps): JSX.Element;

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

@@ -7,4 +7,4 @@ export declare function WorldTab({ api, world, onChanged, }: {
     world: WorldState | undefined;
     /** 保存/提炼成功后由父组件刷新项目状态。 */
     onChanged: (world: WorldState) => void;
-}): any;
+}): import("react").JSX.Element;

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

@@ -1,7 +1,9 @@
 /**
- * Tiny translation helper for the panel: reads the zh dict with the en dict
- * as fallback (the family plugins use a full locale registry; the panel keeps
- * a dependency-free helper so the client bundle stays self-contained).
+ * Tiny translation helper for the panel.
+ *
+ * 面板是中文单语界面：文案只在 `locales.ts` 定义一次，这里按类型化键位取值
+ * （键位不匹配会在编译期报错），保持客户端 bundle 自包含、不引入运行时语言服务。
+ * 需要多语言时再接入 DSH 的 locale 服务，届时只需替换本函数实现。
  */
 import { type NovelKey } from '../locales.ts';
 /** Translate one key with optional {placeholder} substitution. */

package/lib/types/client/panel/market-radar-state.d.ts

@@ -0,0 +1,56 @@
+/**
+ * 热门题材雷达的界面状态规则。
+ *
+ * 职责边界：本文件只回答「界面上此刻能不能点」，不持有任何数据。抽成纯函数的
+ * 理由是它可以离线测——组件渲染不好测，判定逻辑好测。
+ *
+ * 下面先用**独立表述的验收条件**写清楚要什么，再由两个函数实现；这样即使日后
+ * 需求变化，改动方向也是照着条件走，而不是照着某个外部实现的形状走。
+ *
+ *  R1 扫榜或分析进行中，不得改动作品勾选（否则分析输入与界面不一致）；
+ *  R2 未勾选任何作品时不能开始分析；
+ *  R3 已经有报告之后，仍允许改选作品并**再次**分析 —— 不得退化成"只能查看"；
+ *  R4 信号勾选只在确实换了一份报告时复位；同一份报告的重渲染不得冲掉作者手选。
+ */
+/** 雷达三个入口此刻的可用性，以及分析按钮该显示哪种文案。 */
+export interface RadarControls {
+    /** 扫榜按钮是否可点。 */
+    canScan: boolean;
+    /** 作品勾选（含全选 / 清空）是否可改。 */
+    canSelectCandidates: boolean;
+    /** 分析按钮是否可点。 */
+    canAnalyze: boolean;
+    /**
+     * 分析按钮的文案标识：
+     *  - `wait`：还在扫榜，先等榜单；
+     *  - `pick`：还没勾选作品；
+     *  - `first`：首次分析；
+     *  - `again`：已有报告，这次是再出一份。
+     */
+    analyzeLabel: 'wait' | 'pick' | 'first' | 'again';
+}
+/**
+ * 实现 R1-R3：判定三个入口的可用性。
+ * @param state - 当前界面状态。
+ * @returns 各入口可用性与分析按钮文案标识。
+ */
+export declare function radarControls(state: {
+    /** 正在抓榜单。 */
+    scanning: boolean;
+    /** 正在做 AI 分析。 */
+    analyzing: boolean;
+    /** 已勾选的作品数。 */
+    pickedCount: number;
+    /** 界面上是否已有可查看的报告。 */
+    hasReport: boolean;
+}): RadarControls;
+/**
+ * 实现 R4：本次报告是否**不是**勾选当前所依据的那一份。
+ *
+ * 传入的是上一次已经据以复位过的报告标识：相同 → 不动作者勾选；不同 → 勾选所依据
+ * 的信号集合已经变了，需要按新报告重新给出推荐勾选。
+ * @param selectionBasis - 勾选当前依据的报告标识（空串表示尚未复位过）。
+ * @param incoming - 本次拿到的报告标识（空串表示旧版产物没有该标识）。
+ * @returns 需要按新报告重置勾选时为 true。
+ */
+export declare function isDifferentReport(selectionBasis: string, incoming: string): boolean;

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';