@incremark/svelte 0.2.3

package/dist/stores/useDevTools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file useDevTools Store - DevTools 集成
+ * @description Svelte 5 DevTools 一行接入
+ */
+import { type DevToolsOptions } from '@incremark/devtools';
+import type { UseIncremarkReturn } from './useIncremark';
+/**
+ * useDevTools 选项
+ */
+export interface UseDevToolsOptions extends DevToolsOptions {
+}
+/**
+ * Svelte 5 DevTools 一行接入
+ *
+ * @description
+ * 在组件中调用此函数以启用 DevTools
+ *
+ * @param incremark - useIncremark 返回的对象
+ * @param options - DevTools 选项
+ * @returns DevTools 实例
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useIncremark, useDevTools } from '@incremark/svelte'
+ *
+ *   const incremark = useIncremark()
+ *   useDevTools(incremark)  // 就这一行！
+ * </script>
+ * ```
+ */
+export declare function useDevTools(incremark: UseIncremarkReturn, options?: UseDevToolsOptions): import("@incremark/devtools").IncremarkDevTools;
+//# sourceMappingURL=useDevTools.d.ts.map

package/dist/stores/useDevTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDevTools.d.ts","sourceRoot":"","sources":["../../src/stores/useDevTools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC1E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAExD;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;CAAG;AAE9D;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CACzB,SAAS,EAAE,kBAAkB,EAC7B,OAAO,GAAE,kBAAuB,mDAgCjC"}

package/dist/stores/useDevTools.js

@@ -0,0 +1,53 @@
+/**
+ * @file useDevTools Store - DevTools 集成
+ * @description Svelte 5 DevTools 一行接入
+ */
+import { onMount, onDestroy } from 'svelte';
+import { createDevTools } from '@incremark/devtools';
+/**
+ * Svelte 5 DevTools 一行接入
+ *
+ * @description
+ * 在组件中调用此函数以启用 DevTools
+ *
+ * @param incremark - useIncremark 返回的对象
+ * @param options - DevTools 选项
+ * @returns DevTools 实例
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useIncremark, useDevTools } from '@incremark/svelte'
+ *
+ *   const incremark = useIncremark()
+ *   useDevTools(incremark)  // 就这一行！
+ * </script>
+ * ```
+ */
+export function useDevTools(incremark, options = {}) {
+    const devtools = createDevTools(options);
+    // 设置 parser 的 onChange 回调
+    incremark.parser.setOnChange((state) => {
+        const blocks = [
+            ...state.completedBlocks.map((b) => ({ ...b, stableId: b.id })),
+            ...state.pendingBlocks.map((b, i) => ({ ...b, stableId: `pending-${i}` }))
+        ];
+        devtools.update({
+            blocks,
+            completedBlocks: state.completedBlocks,
+            pendingBlocks: state.pendingBlocks,
+            markdown: state.markdown,
+            ast: state.ast,
+            isLoading: state.pendingBlocks.length > 0
+        });
+    });
+    onMount(() => {
+        devtools.mount();
+    });
+    onDestroy(() => {
+        devtools.unmount();
+        // 清理回调
+        incremark.parser.setOnChange(undefined);
+    });
+    return devtools;
+}

package/dist/stores/useIncremark.d.ts

@@ -0,0 +1,128 @@
+/**
+ * @file useIncremark Store - 核心 Store
+ * @description Svelte 5 Store: Incremark 流式 Markdown 解析器
+ */
+import { type Writable, type Readable } from 'svelte/store';
+import { createIncremarkParser, type ParserOptions, type ParsedBlock, type IncrementalUpdate, type Root, type TransformerPlugin, type AnimationEffect } from '@incremark/core';
+/**
+ * 打字机效果配置
+ */
+export interface TypewriterOptions {
+    /** 是否启用打字机效果（可响应式切换） */
+    enabled?: boolean;
+    /** 每次显示的字符数，可以是固定值或范围 [min, max] */
+    charsPerTick?: number | [number, number];
+    /** 更新间隔 (ms) */
+    tickInterval?: number;
+    /** 动画效果: 'none' | 'fade-in' | 'typing' */
+    effect?: AnimationEffect;
+    /** 光标字符（仅 typing 效果使用） */
+    cursor?: string;
+    /** 页面不可见时暂停 */
+    pauseOnHidden?: boolean;
+    /** 自定义插件 */
+    plugins?: TransformerPlugin[];
+}
+/**
+ * useIncremark 选项
+ */
+export interface UseIncremarkOptions extends ParserOptions {
+    /** 打字机配置，传入即创建 transformer（可通过 enabled 控制是否启用） */
+    typewriter?: TypewriterOptions;
+}
+/**
+ * 打字机控制对象
+ */
+export interface TypewriterControls {
+    /** 是否启用（只读） */
+    enabled: Readable<boolean>;
+    /** 设置是否启用 */
+    setEnabled: (enabled: boolean) => void;
+    /** 是否正在处理中 */
+    isProcessing: Readable<boolean>;
+    /** 是否已暂停 */
+    isPaused: Readable<boolean>;
+    /** 当前动画效果 */
+    effect: Readable<AnimationEffect>;
+    /** 跳过动画，直接显示全部 */
+    skip: () => void;
+    /** 暂停动画 */
+    pause: () => void;
+    /** 恢复动画 */
+    resume: () => void;
+    /** 动态更新配置 */
+    setOptions: (options: Partial<TypewriterOptions>) => void;
+}
+/**
+ * useIncremark 返回值
+ */
+export interface UseIncremarkReturn {
+    /** 已收集的完整 Markdown 字符串 */
+    markdown: Writable<string>;
+    /** 已完成的块列表 */
+    completedBlocks: Writable<ParsedBlock[]>;
+    /** 待处理的块列表 */
+    pendingBlocks: Writable<ParsedBlock[]>;
+    /** 当前完整的 AST */
+    ast: Readable<Root>;
+    /** 用于渲染的 blocks（根据打字机设置自动处理） */
+    blocks: Readable<Array<ParsedBlock & {
+        stableId: string;
+    }>>;
+    /** 是否正在加载 */
+    isLoading: Writable<boolean>;
+    /** 是否已完成（finalize） */
+    isFinalized: Writable<boolean>;
+    /** 脚注引用的出现顺序 */
+    footnoteReferenceOrder: Writable<string[]>;
+    /** 追加内容 */
+    append: (chunk: string) => IncrementalUpdate;
+    /** 完成解析 */
+    finalize: () => IncrementalUpdate;
+    /** 强制中断 */
+    abort: () => IncrementalUpdate;
+    /** 重置解析器和打字机 */
+    reset: () => void;
+    /** 一次性渲染（reset + append + finalize） */
+    render: (content: string) => IncrementalUpdate;
+    /** 解析器实例 */
+    parser: ReturnType<typeof createIncremarkParser>;
+    /** 打字机控制 */
+    typewriter: TypewriterControls;
+}
+/**
+ * Svelte 5 Store: Incremark 流式 Markdown 解析器
+ *
+ * @description
+ * 核心 store，管理解析器状态和操作
+ *
+ * @param options - 解析器选项
+ * @returns 解析器状态和控制对象
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useIncremark, Incremark } from '@incremark/svelte'
+ *
+ *   // 基础用法
+ *   const { blocks, append, finalize } = useIncremark()
+ *
+ *   // 启用打字机效果
+ *   const { blocks, append, finalize, typewriter } = useIncremark({
+ *     typewriter: {
+ *       enabled: true,
+ *       charsPerTick: [1, 3],
+ *       tickInterval: 30,
+ *       effect: 'typing',
+ *       cursor: '|'
+ *     }
+ *   })
+ * </script>
+ *
+ * <template>
+ *   <Incremark blocks={$blocks} />
+ * </template>
+ * ```
+ */
+export declare function useIncremark(options?: UseIncremarkOptions): UseIncremarkReturn;
+//# sourceMappingURL=useIncremark.d.ts.map

package/dist/stores/useIncremark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useIncremark.d.ts","sourceRoot":"","sources":["../../src/stores/useIncremark.ts"],"names":[],"mappings":"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"}

package/dist/stores/useIncremark.js

@@ -0,0 +1,177 @@
+/**
+ * @file useIncremark Store - 核心 Store
+ * @description Svelte 5 Store: Incremark 流式 Markdown 解析器
+ */
+import { writable, derived } from 'svelte/store';
+import { createIncremarkParser } from '@incremark/core';
+import { setDefinitionsContext } from '../context/definitionsContext';
+import { useTypewriter } from './useTypewriter';
+/**
+ * Svelte 5 Store: Incremark 流式 Markdown 解析器
+ *
+ * @description
+ * 核心 store，管理解析器状态和操作
+ *
+ * @param options - 解析器选项
+ * @returns 解析器状态和控制对象
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { useIncremark, Incremark } from '@incremark/svelte'
+ *
+ *   // 基础用法
+ *   const { blocks, append, finalize } = useIncremark()
+ *
+ *   // 启用打字机效果
+ *   const { blocks, append, finalize, typewriter } = useIncremark({
+ *     typewriter: {
+ *       enabled: true,
+ *       charsPerTick: [1, 3],
+ *       tickInterval: 30,
+ *       effect: 'typing',
+ *       cursor: '|'
+ *     }
+ *   })
+ * </script>
+ *
+ * <template>
+ *   <Incremark blocks={$blocks} />
+ * </template>
+ * ```
+ */
+export function useIncremark(options = {}) {
+    // 内部自动提供 definitions context
+    const { setDefinations, setFootnoteDefinitions, setFootnoteReferenceOrder } = setDefinitionsContext();
+    // 解析器
+    const parser = createIncremarkParser({
+        ...options,
+        onChange: (state) => {
+            setDefinations(state.definitions);
+            setFootnoteDefinitions(state.footnoteDefinitions);
+            // 调用用户提供的 onChange
+            options.onChange?.(state);
+        }
+    });
+    // 状态 stores
+    const completedBlocks = writable([]);
+    const pendingBlocks = writable([]);
+    const isLoading = writable(false);
+    const markdown = writable('');
+    const isFinalized = writable(false);
+    const footnoteReferenceOrder = writable([]);
+    // 使用 useTypewriter store 管理打字机效果
+    const { blocks, typewriter, transformer } = useTypewriter({
+        typewriter: options.typewriter,
+        completedBlocks,
+        pendingBlocks
+    });
+    // AST
+    const ast = derived([completedBlocks, pendingBlocks], ([$completedBlocks, $pendingBlocks]) => ({
+        type: 'root',
+        children: [
+            ...$completedBlocks.map((b) => b.node),
+            ...$pendingBlocks.map((b) => b.node)
+        ]
+    }));
+    /**
+     * 追加内容
+     *
+     * @param chunk - 要追加的 Markdown 文本块
+     * @returns 增量更新结果
+     */
+    function append(chunk) {
+        isLoading.set(true);
+        const update = parser.append(chunk);
+        markdown.set(parser.getBuffer());
+        if (update.completed.length > 0) {
+            completedBlocks.update((blocks) => [
+                ...blocks,
+                ...update.completed
+            ]);
+        }
+        pendingBlocks.set(update.pending);
+        // 更新脚注引用顺序
+        footnoteReferenceOrder.set(update.footnoteReferenceOrder);
+        setFootnoteReferenceOrder(update.footnoteReferenceOrder);
+        return update;
+    }
+    /**
+     * 完成解析
+     *
+     * @returns 增量更新结果
+     */
+    function finalize() {
+        const update = parser.finalize();
+        markdown.set(parser.getBuffer());
+        if (update.completed.length > 0) {
+            completedBlocks.update((blocks) => [
+                ...blocks,
+                ...update.completed
+            ]);
+        }
+        pendingBlocks.set([]);
+        isLoading.set(false);
+        isFinalized.set(true);
+        // 更新脚注引用顺序
+        footnoteReferenceOrder.set(update.footnoteReferenceOrder);
+        setFootnoteReferenceOrder(update.footnoteReferenceOrder);
+        return update;
+    }
+    /**
+     * 强制中断
+     *
+     * @returns 增量更新结果
+     */
+    function abort() {
+        return finalize();
+    }
+    /**
+     * 重置解析器和打字机
+     */
+    function reset() {
+        parser.reset();
+        completedBlocks.set([]);
+        pendingBlocks.set([]);
+        markdown.set('');
+        isLoading.set(false);
+        isFinalized.set(false);
+        footnoteReferenceOrder.set([]);
+        // 重置 transformer
+        transformer?.reset();
+    }
+    /**
+     * 一次性渲染（reset + append + finalize）
+     *
+     * @param content - 完整的 Markdown 内容
+     * @returns 增量更新结果
+     */
+    function render(content) {
+        const update = parser.render(content);
+        markdown.set(parser.getBuffer());
+        completedBlocks.set(parser.getCompletedBlocks());
+        pendingBlocks.set([]);
+        isLoading.set(false);
+        isFinalized.set(true);
+        footnoteReferenceOrder.set(update.footnoteReferenceOrder);
+        setFootnoteReferenceOrder(update.footnoteReferenceOrder);
+        return update;
+    }
+    return {
+        markdown,
+        completedBlocks,
+        pendingBlocks,
+        ast,
+        blocks,
+        isLoading,
+        isFinalized,
+        footnoteReferenceOrder,
+        append,
+        finalize,
+        abort,
+        reset,
+        render,
+        parser,
+        typewriter
+    };
+}

package/dist/stores/useTypewriter.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file useTypewriter Store - 打字机效果管理
+ * @description 管理打字机效果的状态和控制逻辑，从 useIncremark 中拆分出来以简化代码
+ */
+import { type Writable, type Readable } from 'svelte/store';
+import { type RootContent, type ParsedBlock, type BlockTransformer } from '@incremark/core';
+import type { TypewriterOptions, TypewriterControls } from './useIncremark';
+/**
+ * useTypewriter 选项
+ */
+export interface UseTypewriterOptions {
+    /** 打字机配置 */
+    typewriter?: TypewriterOptions;
+    /** 已完成的块列表 store */
+    completedBlocks: Writable<ParsedBlock[]>;
+    /** 待处理的块列表 store */
+    pendingBlocks: Writable<ParsedBlock[]>;
+}
+/**
+ * useTypewriter 返回值
+ */
+export interface UseTypewriterReturn {
+    /** 用于渲染的 blocks（经过打字机处理或原始blocks） */
+    blocks: Readable<Array<ParsedBlock & {
+        stableId: string;
+    }>>;
+    /** 打字机控制对象 */
+    typewriter: TypewriterControls;
+    /** transformer 实例 */
+    transformer: BlockTransformer<RootContent> | null;
+}
+/**
+ * useTypewriter Store
+ *
+ * @description
+ * 管理打字机效果的所有状态和逻辑
+ *
+ * @param options - 打字机配置和数据
+ * @returns 打字机状态和控制对象
+ */
+export declare function useTypewriter(options: UseTypewriterOptions): UseTypewriterReturn;
+//# sourceMappingURL=useTypewriter.d.ts.map

package/dist/stores/useTypewriter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTypewriter.d.ts","sourceRoot":"","sources":["../../src/stores/useTypewriter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAqB,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAA;AAC9E,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,WAAW,EAGhB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAA;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAG3E;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,YAAY;IACZ,UAAU,CAAC,EAAE,iBAAiB,CAAA;IAC9B,oBAAoB;IACpB,eAAe,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAA;IACxC,oBAAoB;IACpB,aAAa,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAA;CACvC;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAA;IAC3D,cAAc;IACd,UAAU,EAAE,kBAAkB,CAAA;IAC9B,qBAAqB;IACrB,WAAW,EAAE,gBAAgB,CAAC,WAAW,CAAC,GAAG,IAAI,CAAA;CAClD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,mBAAmB,CAkKhF"}

package/dist/stores/useTypewriter.js

@@ -0,0 +1,153 @@
+/**
+ * @file useTypewriter Store - 打字机效果管理
+ * @description 管理打字机效果的状态和控制逻辑，从 useIncremark 中拆分出来以简化代码
+ */
+import { writable, derived } from 'svelte/store';
+import { createBlockTransformer, defaultPlugins } from '@incremark/core';
+import { addCursorToNode } from '../utils/cursor';
+/**
+ * useTypewriter Store
+ *
+ * @description
+ * 管理打字机效果的所有状态和逻辑
+ *
+ * @param options - 打字机配置和数据
+ * @returns 打字机状态和控制对象
+ */
+export function useTypewriter(options) {
+    const { typewriter: typewriterConfig, completedBlocks, pendingBlocks } = options;
+    // 打字机状态 stores
+    const typewriterEnabled = writable(typewriterConfig?.enabled ?? !!typewriterConfig);
+    const displayBlocks = writable([]);
+    const isTypewriterProcessing = writable(false);
+    const isTypewriterPaused = writable(false);
+    const typewriterEffect = writable(typewriterConfig?.effect ?? 'none');
+    const typewriterCursor = writable(typewriterConfig?.cursor ?? '|');
+    // 创建 transformer（如果有 typewriter 配置）
+    let transformer = null;
+    if (typewriterConfig) {
+        const twOptions = typewriterConfig;
+        transformer = createBlockTransformer({
+            charsPerTick: twOptions.charsPerTick ?? [1, 3],
+            tickInterval: twOptions.tickInterval ?? 30,
+            effect: twOptions.effect ?? 'none',
+            pauseOnHidden: twOptions.pauseOnHidden ?? true,
+            plugins: twOptions.plugins ?? defaultPlugins,
+            onChange: (blocks) => {
+                displayBlocks.set(blocks);
+                isTypewriterProcessing.set(transformer?.isProcessing() ?? false);
+                isTypewriterPaused.set(transformer?.isPausedState() ?? false);
+            }
+        });
+    }
+    // 将 completedBlocks 转换为 SourceBlock 格式
+    const sourceBlocks = derived(completedBlocks, ($completedBlocks) => {
+        return $completedBlocks.map(block => ({
+            id: block.id,
+            node: block.node,
+            status: block.status
+        }));
+    });
+    // 监听 sourceBlocks 变化，推送给 transformer
+    if (transformer) {
+        let unsubscribe = null;
+        unsubscribe = sourceBlocks.subscribe((blocks) => {
+            transformer.push(blocks);
+            // 更新正在显示的 block
+            displayBlocks.update((displayBlocksValue) => {
+                const currentDisplaying = displayBlocksValue.find((b) => !b.isDisplayComplete);
+                if (currentDisplaying) {
+                    const updated = blocks.find((b) => b.id === currentDisplaying.id);
+                    if (updated) {
+                        transformer.update(updated);
+                    }
+                }
+                return displayBlocksValue;
+            });
+        });
+    }
+    // 原始 blocks（不经过打字机）
+    const rawBlocks = derived([completedBlocks, pendingBlocks], ([$completedBlocks, $pendingBlocks]) => {
+        const result = [];
+        for (const block of $completedBlocks) {
+            result.push({ ...block, stableId: block.id });
+        }
+        for (let i = 0; i < $pendingBlocks.length; i++) {
+            result.push({
+                ...$pendingBlocks[i],
+                stableId: `pending-${i}`
+            });
+        }
+        return result;
+    });
+    // 最终用于渲染的 blocks
+    const blocks = derived([typewriterEnabled, displayBlocks, rawBlocks, typewriterEffect, typewriterCursor], ([$enabled, $displayBlocks, $rawBlocks, $effect, $cursor]) => {
+        // 未启用打字机或没有 transformer：返回原始 blocks
+        if (!$enabled || !transformer) {
+            return $rawBlocks;
+        }
+        // 启用打字机：使用 displayBlocks
+        return $displayBlocks.map((db, index) => {
+            const isPending = !db.isDisplayComplete;
+            const isLastPending = isPending && index === $displayBlocks.length - 1;
+            // typing 效果时添加光标
+            let node = db.displayNode;
+            if ($effect === 'typing' && isLastPending) {
+                node = addCursorToNode(db.displayNode, $cursor);
+            }
+            return {
+                id: db.id,
+                stableId: db.id,
+                status: (db.isDisplayComplete ? 'completed' : 'pending'),
+                isLastPending,
+                node,
+                startOffset: 0,
+                endOffset: 0,
+                rawText: ''
+            };
+        });
+    });
+    // 打字机控制对象
+    const typewriterControls = {
+        enabled: derived(typewriterEnabled, ($enabled) => $enabled),
+        setEnabled: (value) => {
+            typewriterEnabled.set(value);
+        },
+        isProcessing: derived(isTypewriterProcessing, ($processing) => $processing),
+        isPaused: derived(isTypewriterPaused, ($paused) => $paused),
+        effect: derived(typewriterEffect, ($effect) => $effect),
+        skip: () => transformer?.skip(),
+        pause: () => {
+            transformer?.pause();
+            isTypewriterPaused.set(true);
+        },
+        resume: () => {
+            transformer?.resume();
+            isTypewriterPaused.set(false);
+        },
+        setOptions: (opts) => {
+            if (opts.enabled !== undefined) {
+                typewriterEnabled.set(opts.enabled);
+            }
+            if (opts.charsPerTick !== undefined || opts.tickInterval !== undefined || opts.effect !== undefined || opts.pauseOnHidden !== undefined) {
+                transformer?.setOptions({
+                    charsPerTick: opts.charsPerTick,
+                    tickInterval: opts.tickInterval,
+                    effect: opts.effect,
+                    pauseOnHidden: opts.pauseOnHidden
+                });
+            }
+            if (opts.effect !== undefined) {
+                typewriterEffect.set(opts.effect);
+            }
+            if (opts.cursor !== undefined) {
+                typewriterCursor.set(opts.cursor);
+            }
+        }
+    };
+    return {
+        blocks,
+        typewriter: typewriterControls,
+        transformer
+    };
+}

package/dist/svelte-runes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @file Svelte 5 Runes 类型声明
+ * @description 为 Svelte 5 的 runes 提供类型支持
+ */
+
+declare global {
+  /**
+   * $props rune - 定义组件 props
+   */
+  function $props<T extends Record<string, any> = {}>(): T
+
+  /**
+   * $derived rune - 定义派生状态
+   */
+  function $derived<T>(expression: T): T
+  namespace $derived {
+    function by<T>(fn: () => T): T
+  }
+
+  /**
+   * $state rune - 定义响应式状态
+   */
+  function $state<T>(initial: T): T
+
+  /**
+   * $effect rune - 定义副作用
+   */
+  function $effect(fn: () => void | (() => void)): void
+}
+
+export {}
+

package/dist/utils/cursor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file Cursor Utils - 光标工具函数
+ * @description 用于在 AST 节点末尾添加光标的工具函数
+ */
+import type { RootContent } from '@incremark/core';
+/**
+ * 在节点末尾添加光标
+ *
+ * @param node - 要添加光标的节点
+ * @param cursor - 光标字符
+ * @returns 添加了光标的新节点
+ */
+export declare function addCursorToNode(node: RootContent, cursor: string): RootContent;
+//# sourceMappingURL=cursor.d.ts.map

package/dist/utils/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/utils/cursor.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAElD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CA0B9E"}

package/dist/utils/cursor.js

@@ -0,0 +1,36 @@
+/**
+ * @file Cursor Utils - 光标工具函数
+ * @description 用于在 AST 节点末尾添加光标的工具函数
+ */
+/**
+ * 在节点末尾添加光标
+ *
+ * @param node - 要添加光标的节点
+ * @param cursor - 光标字符
+ * @returns 添加了光标的新节点
+ */
+export function addCursorToNode(node, cursor) {
+    const cloned = JSON.parse(JSON.stringify(node));
+    function addToLast(n) {
+        if (n.children && n.children.length > 0) {
+            for (let i = n.children.length - 1; i >= 0; i--) {
+                if (addToLast(n.children[i])) {
+                    return true;
+                }
+            }
+            n.children.push({ type: 'text', value: cursor });
+            return true;
+        }
+        if (n.type === 'text' && typeof n.value === 'string') {
+            n.value += cursor;
+            return true;
+        }
+        if (typeof n.value === 'string') {
+            n.value += cursor;
+            return true;
+        }
+        return false;
+    }
+    addToLast(cloned);
+    return cloned;
+}