remons-render-markdown 2.0.1-beta.2 → 2.0.1-beta.4

package/dist/components/ImagePreview/index.d.ts

@@ -1,14 +1,23 @@
 /**
- * 向图片预览排除名单中添加选择器
- * 外部自定义渲染器若包含图片，需调用此方法避免 Viewer.js 冲突
+ * 向图片预览全局排除名单中添加选择器
+ * 外部自定义渲染器若包含图片，需调用此方法避免与本库预览冲突
  * @param selectors - CSS 选择器或选择器数组，如 '.copy-password-container' 或 ['.a', '.b']
  */
 export declare function addExcludedSelector(selectors: string | string[]): void;
+/** 从全局排除名单移除选择器（与 addExcludedSelector 配对，支持撤销） */
+export declare function removeExcludedSelector(selectors: string | string[]): void;
 /**
- * 初始化图片工具栏和预览功能
+ * 初始化图片预览：绑定容器内的图片点击委托，并刷新可预览列表
+ * @param container - 渲染容器（.markdown-html），只处理其内部图片
+ * @param options.instanceSelectors - 实例级排除名单（excludedSelectors prop）
+ * @param options.isPrintPreview - 打印模式：跳过交互，仅展开图片样式
  */
-export declare function initImageToolbars(containerRef: React.MutableRefObject<HTMLDivElement | null>, isPrintPreview?: boolean): void;
+export declare function initImageToolbars(container: HTMLDivElement | null, options?: {
+    instanceSelectors?: string[];
+    isPrintPreview?: boolean;
+}): void;
 /**
- * 清理所有图片工具栏和 Viewer 实例
+ * 销毁指定容器的预览状态（容器卸载/隐藏前调用）
+ * 遮罩是挂在 body 上的独立节点，不属于容器子树，必须显式关掉
  */
-export declare function cleanupImageToolbars(): void;
+export declare function cleanupImageToolbars(container?: HTMLElement | null): void;

package/dist/components/MermaidRenderer/index.d.ts

@@ -45,16 +45,40 @@ interface MermaidRendererProps {
      */
     isPrintPreview?: boolean;
     /**
-     * 自定义配置函数，对渲染前 text 进行修改
-     * @returns
+     * 渲染前对图表源码进行改写（初始化语义：仅首次传入生效）
+     */
+    transformSource?: (text: string) => string;
+    /**
+     * @deprecated 旧名，等价于 transformSource
      */
     chartConfig?: (text: string) => string;
     /**
-     * 自定义 CDN 配置，如 { mermaid: 'https://...' }
+     * mermaid 安全级别，默认 'strict'（禁用图内点击事件/原始 HTML）。
+     * 仅当完全信任图表来源时才设为 'loose'。
+     */
+    securityLevel?: 'strict' | 'loose';
+    /**
+     * 自定义 CDN 配置，如 { mermaid: 'https://...' }（初始化语义：全局仅加载一次）
      */
     cdn?: Record<string, string>;
+    /**
+     * 新手引导是否每个元素只触发一次（默认 true）。
+     * 流式重渲染场景下设为 false 会反复弹引导。
+     */
+    driverGuideOnce?: boolean;
 }
 declare const MermaidRenderer: import('react').ForwardRefExoticComponent<MermaidRendererProps & import('react').RefAttributes<null>>;
 export default MermaidRenderer;
+/**
+ * 带主题容器的图表组件（推荐直接使用）：
+ * 作为 JSX 元素类型稳定，父组件重渲染不会导致子树卸载重建；自带 ThemeProvider，
+ * 应用未包主题上下文时也能直接渲染。
+ * 旧用法 renderMermaid({...}) 返回 JSX 的方式每次调用都生成新元素类型，
+ * 会造成重渲染时完整卸载重建，已标废。
+ */
+export declare const MermaidChart: React.FC<MermaidRendererProps>;
+/**
+ * @deprecated 请改用组件形式 <MermaidChart {...} />；函数调用返回 JSX 会在父组件重渲染时重置子树状态
+ */
 declare const renderMermaid: (props: MermaidRendererProps) => import("react").JSX.Element;
 export { renderMermaidWithControls, renderMermaid };

package/dist/components/MermaidRenderer/mermaidRootRegistry.d.ts

@@ -0,0 +1,25 @@
+import { Root } from 'react-dom/client';
+/** 注册一个挂载点与其 React Root */
+export declare function registerMermaidRoot(el: Element, root: Root): void;
+/** 卸载并清空指定元素上挂载过的图表 root */
+export declare function unmountMermaidRootsAt(el: Element): void;
+/** 取挂载点上的 React Root：源码变化时用它原地更新 props，避免卸载重建 */
+export declare function getMermaidRoot(el: Element): Root | undefined;
+/**
+ * 回收已脱离文档的挂载点。
+ * 非增量模式整块重建、内容为空时 React 直接移除子树，这些节点
+ * 不在任何作用域内、扫描再也找不到，不主动回收就是永久泄漏的 Root。
+ */
+export declare function pruneDetachedMermaidRoots(): void;
+/**
+ * 源码指纹（FNV-1a 32 位 + 长度）：用于判断图表源码是否真的变了。
+ * 长度入摘要以降低碰撞概率；只用于“是否相等”判定，不用于还原源码。
+ */
+export declare function hashMermaidSource(text: string): string;
+/** 是否由扫描挂载的图表节点（兼作锚点定位与孤儿回收的判据） */
+export declare function isMermaidChartRoot(el: Element | null | undefined): el is HTMLElement;
+/**
+ * 回收某棵子树内所有图表 root 并移除挂载点节点。
+ * 组件卸载 / 增量 diff 丢弃节点时调用，防止 React Root 泄漏。
+ */
+export declare function cleanupMermaidRoots(scope: ParentNode | null): void;

package/dist/components/MermaidRenderer/renderMermaidWithControls.d.ts

@@ -1,11 +1,27 @@
-/**
- * DOM 扫描入口（文档页使用）
- * 扫描页面中所有 code.language-mermaid 元素，替换为 MermaidRenderer 组件
- */
-export default function renderMermaidWithControls(props: {
+import { cleanupMermaidRoots } from './mermaidRootRegistry';
+export { cleanupMermaidRoots };
+interface ScanProps {
     showDriverGuide?: boolean;
     isPrintPreview?: boolean;
+    transformSource?: (text: string) => string;
+    /** @deprecated 旧名，等价于 transformSource（初始化语义） */
     chartConfig?: (text: string) => string;
     defaultCollapsed?: boolean;
     cdn?: Record<string, string>;
-}): Promise<void>;
+    /** 扫描作用域，默认为 document；传入容器可实现多实例隔离 */
+    rootElement?: ParentNode;
+}
+/**
+ * DOM 扫描入口（文档页使用）
+ * 扫描容器内所有已闭合的 code.language-mermaid 代码块，在其**后面**插入图表挂载点。
+ *
+ * 关键约定：`<pre>` 保留在 DOM 中（由 CSS 隐藏源码），图表作为它的兄弟节点存在。
+ * 这样增量渲染时 morphdom 仍能按 <pre> 自身的语义 key 匹配到原节点、原地无变化，
+ * 而挂载点靠 MD_PERSIST_ATTR 免于被移除；两边都不会被销毁重建。
+ * 早先的 `pre.replaceWith(container)` 写法会让每次 patch 都命中"签名不匹配"，
+ * 图表被移除→重挂→整图重新 mermaid.render，表现为流式中反复闪白并丢失交互状态。
+ *
+ * 可重复调用：源码未变的块直接复用现有挂载点（不重渲染）；源码变了走 props 更新；
+ * 块被删除/围栏重开的挂载点会被卸载移除，不会累积泄漏。
+ */
+export default function renderMermaidWithControls(props?: ScanProps): Promise<void>;

package/dist/components/MermaidRenderer/useMermaidRender.d.ts

@@ -10,16 +10,25 @@ interface UseMermaidRenderParams {
     debounceMs?: number;
     isDark: boolean;
     /**
-     * 自定义配置函数，对渲染前 text 进行修改
-     * @returns
+     * 渲染前对图表源码进行改写（初始化语义：仅首次传入时确定，后续变更不生效，
+     * 避免内联函数引用变化导致每轮重渲染重置防抖）
+     */
+    transformSource?: (text: string) => string;
+    /**
+     * @deprecated 旧名，等价于 transformSource（初始化语义）
      */
     chartConfig?: (text: string) => string;
     /**
-     * 自定义 CDN 配置，如 { mermaid: 'https://...' }
+     * 自定义 CDN 配置，如 { mermaid: 'https://...' }（初始化语义：全局仅加载一次，以首次调用为准）
      */
     cdn?: Record<string, string>;
+    /**
+     * mermaid 安全级别，默认 'strict'（禁用图内点击事件/原始 HTML）。
+     * 仅当完全信任图表来源时才设为 'loose'。
+     */
+    securityLevel?: 'strict' | 'loose';
 }
-export default function useMermaidRender({ source, debounceMs, isDark, chartConfig, cdn }: UseMermaidRenderParams): {
+export default function useMermaidRender({ source, debounceMs, isDark, transformSource, chartConfig, cdn, securityLevel, }: UseMermaidRenderParams): {
     svg: string;
     error: string;
     loading: boolean;

package/dist/components/MermaidRenderer/usePanzoom.d.ts

@@ -9,9 +9,23 @@ interface PanzoomRefType {
 interface UsePanzoomParams {
     contentRef: RefObject<HTMLElement | null>;
     wrapperRef: RefObject<HTMLElement | null>;
-    enabled: boolean;
-    svg: string;
+    /**
+     * 是否具备缩放能力（图表已渲染且开启 enablePanzoom）。
+     * 实例只跟随它创建/销毁，因此图表重渲染不会重置用户的缩放/平移位姿。
+     */
+    canUse: boolean;
+    /** 是否响应交互（拖拽、滚轮缩放）。关闭时只解绑事件，保留已有 transform */
+    active: boolean;
+    /** 全屏切换会大幅改变可视区域，需要重建实例以重新计算边界 */
     isFullscreen: boolean;
 }
-export default function usePanzoom({ contentRef, wrapperRef, enabled, svg, isFullscreen }: UsePanzoomParams): import('react').MutableRefObject<PanzoomRefType | null>;
+/**
+ * Panzoom 实例管理。
+ *
+ * 修复前：依赖里含 svg 字符串，每次重渲染（流式输出、主题切换）都 destroy + 重建，
+ * 用户刚缩放/平移好的视图被反复清零；折叠再展开同样清零。
+ * 现在：实例只由 canUse 决定生死（承载 transform 的容器节点始终不变，替换其内部 <svg> 不影响它），
+ * 交互开关用 bind/destroy 解绑事件实现，位姿得以保留。
+ */
+export default function usePanzoom({ contentRef, wrapperRef, canUse, active, isFullscreen }: UsePanzoomParams): import('react').MutableRefObject<PanzoomRefType | null>;
 export {};

package/dist/components/RenderMarkdown/index.d.ts

@@ -10,11 +10,19 @@ export interface RenderMarkdownProps {
     */
     showBackTop?: boolean;
     /**
-    * 是否使用 Mermaid 插件
+    * 是否将 mermaid 代码块渲染为图表
+    */
+    enableMermaid?: boolean;
+    /**
+    * @deprecated 旧名，等价于 enableMermaid
     */
     isSlotMermaid?: boolean;
     /**
-    * 是否显示代码折叠
+    * 是否显示代码折叠按钮
+    */
+    showCollapseButton?: boolean;
+    /**
+    * @deprecated 旧名，等价于 showCollapseButton
     */
     isShowCollapsed?: boolean;
     /**
@@ -26,10 +34,9 @@ export interface RenderMarkdownProps {
     */
     footer?: React.ReactNode;
     /**
-     * 返回顶部所依赖的容器
-     * HTMLElement
+     * 返回顶部所依赖的容器，默认 document.body（仅在首次渲染时读取）
      */
-    backTopTarget?: HTMLElement;
+    backTopTarget?: HTMLElement | null;
     /**
     * 是否显示新手引导
     */
@@ -39,30 +46,68 @@ export interface RenderMarkdownProps {
      */
     isPrintPreview?: boolean;
     /**
-   * 自定义配置函数，对渲染前 text 进行修改
-   * @returns
-   */
+     * 渲染前对 mermaid 源码进行改写（初始化语义：仅首次传入生效）
+     */
+    transformSource?: (text: string) => string;
+    /**
+     * @deprecated 旧名，等价于 transformSource
+     */
     chartConfig?: (text: string) => string;
     /**
-    * 默认是否折叠代码
+    * 代码块默认是否折叠
     */
     defaultCollapsed?: boolean;
     /**
-    * Mermaid 渲染防抖延迟（ms），默认 10ms
-    */
+     * content 变化后工具栏/mermaid 扫描的防抖延迟（ms），默认 100（初始化语义）
+     */
+    toolbarDebounceMs?: number;
+    /**
+     * @deprecated 旧名，等价于 toolbarDebounceMs
+     */
     mermaidDebounce?: number;
     /**
-     * 自定义 CDN 配置，如 { mermaid: 'https://...' }
+     * 自定义 CDN 配置，如 { mermaid: 'https://...' }（初始化语义：mermaid 库全局仅加载一次）
      */
     cdn?: Record<string, string>;
     /**
-     * 自定义 markdown-it 渲染器插件列表，在内部渲染器之后按序执行
+     * 自定义 markdown-it 渲染器插件列表，在内部渲染器之后按序执行（初始化语义）
      */
     customRenderers?: MarkdownPlugin[];
     /**
-     * 图片预览排除名单，自定义渲染器容器内的图片不会被 Viewer.js 处理
-     * 如：['.copy-password-container']
+     * 图片预览排除名单（实例级）：位于这些容器内的图片不会进入预览列表，
+     * 如：['.copy-password-container']。全局名单请用 addExcludedSelector/removeExcludedSelector
      */
     excludedSelectors?: string[];
+    /**
+     * 是否显示目录（TOC）按钮和侧边栏
+     */
+    showToc?: boolean;
+    /**
+     * 是否启用增量渲染（使用 morphdom 进行 DOM 差异化更新）
+     * 适用于流式输出或编辑器场景，避免全量重绘导致的状态丢失。
+     * 初始化语义：渲染途中变更不生效
+     */
+    incremental?: boolean;
+    /**
+     * @deprecated 旧名，等价于 incremental
+     */
+    useIncremental?: boolean;
+    /**
+     * 增量渲染节流时间（ms），默认 16（初始化语义）
+     */
+    incrementalThrottleMs?: number;
+    /**
+     * 是否渲染源码中的原生 HTML。默认 true（历史行为）；
+     * 渲染不可信内容（AI 输出/用户上传）时建议设为 false
+     */
+    html?: boolean;
+    /**
+     * 覆盖链接校验（初始化语义）。不传则用本库默认 `defaultValidateLink`：
+     * markdown-it 原生名单（拒 javascript:/vbscript:/file: 与绝大多数 data: URI，仅放行
+     * `data:image/(gif|png|jpeg|webp);`）+ 额外放行无脚本特征的 `data:image/svg+xml` 内联图。
+     * 传入则整体接管，要保留库默认可写
+     * `validateLink={(url) => myRule(url) || defaultValidateLink(url)}`
+     */
+    validateLink?: (url: string) => boolean;
 }
 export default function RenderMarkdown(props: RenderMarkdownProps): React.JSX.Element;

package/dist/components/RenderMarkdown/utils/render-markdown/empty-task-lists.d.ts

@@ -0,0 +1,2 @@
+export declare function emptyTaskLists(md: any): void;
+export default emptyTaskLists;

package/dist/components/RenderMarkdown/utils/render-markdown/fence-state.d.ts

@@ -0,0 +1,16 @@
+import { Token } from 'markdown-it';
+/** 未闭合围栏的 <code> 上追加的标记 class（无样式，仅供上层判断"这段还没写完"） */
+export declare const FENCE_OPEN_CLASS = "md-fence-open";
+/**
+ * 给「源码末尾尚未闭合」的围栏代码块打标记。
+ *
+ * 为什么需要：流式（打字机/SSE）输出时，最后一个 ``` 围栏常常只有开头没有结尾，
+ * 而 markdown-it 的 fence 规则在找不到闭合行时会吞到输入末尾、照常产出一个 code token
+ * （见其源码：haveEndMarker 只用于推进 state.line，**不会记录到 token 上**）。
+ * 于是残缺的 Mermaid 源码被当成完整图表送去 mermaid.render()，
+ * 每个增量片段都必然抛 Parse error（实测 67 个前缀里 31 个失败），表现为控制台刷屏 + 红框闪现。
+ *
+ * 判定规则按 CommonMark：只有最后一个 fence token 可能未闭合（未闭合围栏会吞掉其后全部内容），
+ * 闭合行需与起始行同种标记、长度不小于起始行、且该行之后只有空白。
+ */
+export declare function markUnclosedFence(tokens: Token[], src: string): void;

package/dist/components/RenderMarkdown/utils/render-markdown/index.d.ts

@@ -5,14 +5,35 @@ export type AnchorItem = {
     nodeName: string;
     children: AnchorItem[];
 };
+export interface RenderMarkdownOptions {
+    /**
+     * 是否渲染源码中的原生 HTML 标签。
+     * 默认 true（历史行为）。渲染不可信内容（AI 输出、用户上传）时建议设为 false。
+     */
+    html?: boolean;
+    /**
+     * 覆盖链接校验。
+     * 缺省用本库默认（`defaultValidateLink`）：markdown-it 原生名单 + 额外放行无脚本特征的
+     * `data:image/svg+xml` 内联图（原生不认 svg，`![](data:image/svg+xml,...)` 会退化成源码）。
+     * 传入本项则**整体接管**：要保留库默认可用
+     * `validateLink={(url) => myRule(url) || defaultValidateLink(url)}`。
+     * 不要把“方便”写成 `() => true` —— 那会连带放行 javascript:/vbscript:/file: 等危险协议。
+     * 初始化语义：随本次渲染调用生效，不保留上一例的覆盖。
+     */
+    validateLink?: (url: string) => boolean;
+}
 /** markdown-it 插件函数类型 */
 export type MarkdownPlugin = (md: any) => void;
-declare function renderMarkdown(content: string, customPlugins?: MarkdownPlugin[]): Promise<{
+/**
+ * 渲染 Markdown 为 HTML，并返回自动采集的标题锚点树。
+ * KaTeX 为 CDN 懒加载：加载失败不抛错，公式降级为原文并 console.warn。
+ */
+declare function renderMarkdown(content: string, customPlugins?: MarkdownPlugin[], options?: RenderMarkdownOptions): Promise<{
     anchor: AnchorItem[];
     info: string;
 }>;
 /**
- * 初始化高亮语言包
+ * 初始化高亮语言包（hljs 为 external 依赖，需由使用方注册语言后才会高亮）
  * @param {Object} languages - 语言包对象，如 { javascript: javascriptModule, css: cssModule }
  */
 export declare function initHighlighter(languages: Record<string, any> | null | undefined): void;

package/dist/components/RenderMarkdown/utils/render-markdown/render-tab.d.ts

@@ -1,6 +1,7 @@
 /**
  * 初始化 Tab 逻辑
- * 使用递归思想：只处理当前容器下的直接子元素，互不干扰
+ * 交互统一挂在 document 上做事件委托：天然覆盖所有 RenderMarkdown 实例，
+ * 多实例不再互相抢占第一个 .markdown 容器；增量渲染重建 DOM 后也无需重绑。
  */
 export declare const tabsName = "markdown-tabs";
 declare function renderTab(): void;

package/dist/components/RenderMarkdown/utils/render-markdown/validate-link.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 本库默认的链接校验（覆盖 markdown-it 的 validateLink）
+ *
+ * markdown-it 原生只放行 `data:image/(gif|png|jpeg|webp);`，`data:image/svg+xml` 会被判为不安全链接，
+ * 结果是 `![](data:image/svg+xml,...)` 整行退化成源码文本 —— 图标、图表、AI 产出的内联 svg 全中招。
+ * 这里在原生名单之上**只额外**放行内联 svg，其余协议（javascript:/vbscript:/file: 与其它 data:）
+ * 一律照旧拒绝。
+ *
+ * 为什么放行 svg 还需要额外过滤：validateLink 同时作用于图片语法和链接语法，
+ * `<img src="data:image/svg+xml,...">` 本身是惰性的（规范里 SVG 作为图片不执行脚本、不加载外部资源），
+ * 但 `<a href="data:image/svg+xml,...">` 被导航时 SVG 会作为**文档**渲染，脚本可执行。
+ * 因此对 svg 载荷做一次可执行特征检查，命中就拒。这是纵深防御的启发式过滤，不是沙箱；
+ * 渲染真正不可信的内容仍应把 `html={false}` 打开，必要时传入更严的 validateLink。
+ */
+/** 本库默认链接校验：markdown-it 名单 + 无脚本特征的内联 svg */
+export declare function defaultValidateLink(url: string): boolean;

package/dist/components/TocSidebar/index.d.ts

@@ -0,0 +1,15 @@
+export interface AnchorItem {
+    href: string;
+    title: string;
+    children: AnchorItem[];
+    nodeName: string;
+    nodeTitle: string;
+}
+interface TocSidebarProps {
+    anchors: AnchorItem[];
+    activeId: string;
+    visible: boolean;
+    onClose: () => void;
+}
+declare function TocSidebar({ anchors, activeId, visible, onClose }: TocSidebarProps): import("react").JSX.Element | null;
+export default TocSidebar;

package/dist/hooks/useIncrementalRender.d.ts

@@ -0,0 +1,64 @@
+import { MarkdownPlugin, AnchorItem, RenderMarkdownOptions } from '../components/RenderMarkdown/utils/render-markdown';
+import { MD_PERSIST_ATTR } from '../utils/dom-contract';
+export { MD_PERSIST_ATTR };
+interface UseIncrementalRenderOptions {
+    /** Markdown 内容 */
+    content: string;
+    /**
+     * 代码类型包装
+     * 初始化语义：仅在挂载时读取，渲染途中变更不生效
+     */
+    codeType?: string;
+    /**
+     * 自定义 markdown-it 插件
+     * 初始化语义：仅在挂载时读取，渲染途中变更不生效
+     */
+    customRenderers?: MarkdownPlugin[];
+    /**
+     * 增量渲染节流时间（ms），默认 16（~60fps）
+     * 初始化语义：仅在挂载时读取
+     * 真节流语义：首个内容变化立即渲染，期间的新变化最多每 throttleMs 渲染一次（含收尾）
+     */
+    throttleMs?: number;
+    /**
+     * 是否渲染源码中的原生 HTML（安全开关）。
+     * 初始化语义：仅在挂载时读取；缺省 true。
+     * 修复前增量模式没把该开关透传给 renderMarkdown，导致 html=false 只在非增量模式下生效。
+     */
+    html?: RenderMarkdownOptions['html'];
+    /**
+     * 覆盖链接校验（缺省不传则用本库默认 defaultValidateLink：markdown-it 名单 + 放行内联 svg 图）。
+     * 初始化语义：仅在挂载时读取；传入则整体接管，只对可信内容放宽
+     */
+    validateLink?: RenderMarkdownOptions['validateLink'];
+    /**
+     * 节点被 morphdom diff 移除后触发（含被移除子树的递归子节点）。
+     * 用于清理挂在被移除节点上的 React Root、监听器等状态。
+     */
+    onNodeDiscarded?: (el: HTMLElement) => void;
+    /**
+     * 每次 DOM patch 完成后同步触发（浏览器绘制前）。
+     * 用于恢复被 diff 丢弃的运行时标记（如代码块工具栏的动态 class / 语言标签）。
+     */
+    onPatched?: () => void;
+}
+/**
+ * 增量渲染 hook，使用 morphdom 进行部分 DOM 更新。
+ *
+ * - 首次渲染：使用 innerHTML 设置初始内容
+ * - 后续渲染：渲染为字符串，然后通过 morphdom patch 容器
+ * - 节流 patch 调用（真节流：首次立即执行 + 周期收尾），避免流式输出期间过多 DOM 操作
+ * - 渲染序号保证内容变化后，飞行中的渲染结果不会污染新状态
+ * - 按"标签 + className"语义 key 匹配节点，保护 customRenderers（插件）产出的容器状态
+ * - 保留节点上 JS 添加的 data-* 属性（初始化守卫位），避免 patch 后被重复初始化
+ * - 返回 inner 内容 <div> 的 ref 回调
+ *
+ * 注意：除 content 外的所有选项均为**初始化语义**——仅在挂载时读取一次，
+ * 渲染途中变更不生效（customRenderers / codeType / throttleMs 等）。
+ */
+export declare function useIncrementalRender({ content, codeType, customRenderers, throttleMs, html, validateLink, onNodeDiscarded, onPatched, }: UseIncrementalRenderOptions): {
+    anchors: AnchorItem[];
+    hasContent: boolean;
+    setInnerRef: (node: HTMLDivElement | null) => void;
+};
+export default useIncrementalRender;

package/dist/hooks/useTheme.d.ts

@@ -1,9 +1,10 @@
 import { default as React } from 'react';
+export type ThemeMode = "light" | "dark" | "system";
 export interface UseThemeReturn {
     theme: string;
-    mode: string;
+    mode: ThemeMode;
     isDark: boolean;
-    setMode: (mode: string) => void;
+    setMode: (mode: ThemeMode) => void;
 }
 export interface ThemeProviderProps {
     children: React.ReactNode;
@@ -11,6 +12,11 @@ export interface ThemeProviderProps {
 declare const THEME_LIGHT = "light";
 declare const THEME_DARK = "dark";
 declare const THEME_SYSTEM = "system";
+/**
+ * 同步应用已存储的主题（防 FOUC）。
+ * 库不再在 import 时产生全局副作用；使用方需在应用入口（或 index.html 内联脚本）主动调用。
+ */
+export declare function initTheme(): void;
 export declare function ThemeProvider({ children }: ThemeProviderProps): React.FunctionComponentElement<React.ProviderProps<UseThemeReturn | null>>;
 export declare function useTheme(): UseThemeReturn;
 export { THEME_LIGHT, THEME_DARK, THEME_SYSTEM };