@meshflow/core 0.4.8 → 0.5.0

package/index.d.ts

@@ -1,9 +1,18 @@
+/**
+ * @internal
+ * */
 type Unwrap<T> = T extends ReadonlyArray<infer U> ? U : T;
+/**
+ * @internal
+ * */
 type InferLeafType<T> = Unwrap<T> extends infer Node ? Node extends {
     readonly name: any;
 } ? Node extends {
     readonly children: infer C;
 } ? InferLeafType<C> : Node : never : never;
+/**
+ * @internal
+ * */
 type InferLeafPath<T, Prefix extends string = ""> = Unwrap<T> extends infer Node ? Node extends {
     readonly name: infer N;
 } ? N extends string ? N extends "" ? Node extends {
@@ -16,8 +25,9 @@ type InferLeafPath<T, Prefix extends string = ""> = Unwrap<T> extends infer Node
 type KeysOfUnion<T> = T extends any ? keyof T : never;
 
 /**
- * 🚀 核心内部事件名枚举
- * 使用 const enum 确保编译后直接内联为字符串，零运行时开销
+ * @description 核心内部事件名枚举
+ * @group 类型管理
+ * @category 事件类型
  */
 declare const enum MeshFlowEventsName {
     FlowStart = 0,
@@ -40,7 +50,8 @@ declare const enum MeshFlowEventsName {
     EntangleBlocked = 17
 }
 /**
- * 🧱 基础事件负载定义
+ * @description 基础事件负载定义
+ * @internal
  */
 interface BaseMeshEvents {
     [MeshFlowEventsName.FlowStart]: {
@@ -106,8 +117,9 @@ interface BaseMeshEvents {
     };
 }
 /**
- * 🌟 完整事件扩展定义
- * 包含流程控制及“逆转未来”等特殊场景
+ * @description 完整事件扩展定义
+ * @group 类型管理
+ * @category 事件类型
  */
 interface MeshEvents extends BaseMeshEvents {
     [MeshFlowEventsName.FlowSuccess]: {
@@ -125,12 +137,28 @@ interface MeshEvents extends BaseMeshEvents {
         triggerPath: MeshPath;
     };
 }
+/**
+* @internal
+*/
 type MeshEventName = keyof MeshEvents;
+/**
+* @internal
+*/
 type MeshEmit = <K extends MeshEventName>(event: K, data: MeshEvents[K]) => void;
+/**
+ * @group 类型管理
+ * @category 历史类型
+ *
+*/
 type HistoryActionItem = {
     undoAction: () => void;
     redoAction: () => void;
 };
+/**
+ * @group 类型管理
+ * @category 历史类型
+ *
+*/
 type MeshFlowHistory = {
     Undo: () => void;
     Redo: () => void;
@@ -148,12 +176,37 @@ type MeshFlowHistory = {
         redoAction: () => any;
     };
 };
+/**
+ * @group 类型管理
+ * @category 错误类型
+ */
 interface MeshErrorContext {
     path: string;
     error: any;
 }
+/**
+ * MeshPath：多模态路径标识符
+ * @description
+ * 定义 MeshFlow 节点的唯一寻址路径。支持多种原始类型以适配不同的业务场景：
+ * - **string**: 💡 推荐。语义化最强，支持深度路径嵌套（如 `user.profile.id`）。
+ * - **number**: ✅ 稳定。常用于位操作、枚举 ID 或高性能数组索引节点，与引擎内部 UID 逻辑契合度高。
+ * - **symbol**: ⚠️ **实验性**。用于创建绝对私有的节点，防止意外覆盖。
+ * @note **关于 Symbol 的约束**：
+ * 目前版本下，Symbol 路径无法被标准 JSON 序列化，可能会出现意料之外的bug。
+ * @group 类型管理
+ * @category 路径类型
+ */
 type MeshPath = string | number | symbol;
+/**
+* @internal
+*/
 type MeshNodeProxy<Node, V, NM, Extra = {}> = Extra & V & Node & NM;
+/**
+*
+* @description task节点类型
+* @group 类型管理
+* @category 节点类型
+*/
 interface MeshFlowTaskNode<P extends MeshPath = MeshPath, V = any, NM = any> {
     path: P;
     uid: number;
@@ -168,6 +221,12 @@ interface MeshFlowTaskNode<P extends MeshPath = MeshPath, V = any, NM = any> {
     dependOn: (cb: (val: V) => V, key?: keyof NM) => void;
     createView: <E extends Record<string, any> = {}>(extraProps?: E) => MeshNodeProxy<MeshFlowTaskNode<P, V, NM>, V, NM, E>;
 }
+/**
+*
+* @description group节点类型
+* @group 类型管理
+* @category 节点类型
+*/
 interface MeshFlowGroupNode<P extends MeshPath = MeshPath> {
     path: P;
     uid: number;
@@ -177,33 +236,167 @@ interface MeshFlowGroupNode<P extends MeshPath = MeshPath> {
     meta: Record<string, any>;
     createView: (extraProps?: Record<string, any>) => any;
 }
+/**
+ * @internal
+ * */
 interface StandardUITrigger<T> {
     signalCreator: () => T;
     signalTrigger: (signal: T) => void;
 }
+/**
+* @group 参数类型
+* @category 依赖设置
+* @description 桶计算的逻辑块入参类型
+*/
 interface logicApi<TKeys extends MeshPath> {
     slot: {
         triggerTargets: Array<Record<TKeys | InternalKeys, any>>;
         affectedTatget: any;
     };
 }
+/**
+*
+* @description 节点开放的一些内部键值
+* @group 类型管理
+* @category 节点类型
+*/
 type InternalKeys = 'path' | 'uid' | 'type' | 'meta' | 'state';
+/**
+* 节点规则配置接口
+* @group 参数类型
+* @category 依赖设置
+* @typeParam NM - 状态大盘的类型定义
+* @typeParam TKeys - 当前节点关联的键集合
+* @params logic - 桶计算的逻辑块，一个桶里面可以装多个逻辑块，根据策略进行计算，逻辑块入参参考{}
+*/
 interface SetRuleOptions<NM, TKeys extends KeysOfUnion<NM>> {
+    /**
+       * 结果覆盖值 (静态产出)
+       * * @description
+       * 规则命中后的确定性结果。其行为在不同策略下表现如下：
+       * * - **【必备】OR 策略**：作为 If-Then 模型的成果。当 logic 返回真值时，此字段提供节点最终产出的数据。
+       * - **【可选】PRIORITY 策略**：作为静态覆盖。若配置此值，将无条件替换 logic 的计算结果；若不配置，则直接采用 logic 的返回值。
+       * - **【可选】MERGE 策略**：作为结构化补丁。用于在逻辑运算之外，额外合并一份静态的配置增量。
+       * * @note 💡 **最佳实践**：
+       * 在 `OR` 模式下，建议永远配合 `value` 使用以获得明确的业务状态。
+       */
     value?: any;
+    /**
+     * 逻辑优先级 (仅在 PRIORITY 策略下生效)
+     */
     priority?: number;
     forceNotify?: boolean;
+    /**
+     * 核心逻辑片段 (Logic Fragment)
+     * * @description
+     * 节点规则的执行体。它是碎片化的，允许针对同一节点注册多个逻辑片段。
+     * * **策略影响 (Strategy Impact)：**
+     * - **OR (逻辑或)**: 只要有一个逻辑片段返回真值，即终止计算并输出该值。
+     * - **PRIORITY (优先级)**: 按 `priority` 顺序执行，取第一个非 `undefined` 的返回值。
+     * - **MERGE (增量聚合)**: 执行所有逻辑片段，并将结果进行深度合并 (Object/Array)。
+     * * @param api 注入的运行上下文 {@link logicApi}
+     */
     logic: (api: logicApi<TKeys>) => any;
+    /**
+      * 后置副作用 (Post-Settlement Effect)
+      * * @description
+      * 节点计算完成后的回调钩子。
+      *
+      * * @param args 由 {@link effectArgs} 指定的实时数据快照。
+      */
     effect?: (args: any) => any;
+    /**
+    * 📥 副作用参数声明
+    * * @description
+    * 显式定义需要注入给 `effect` 函数的参数。
+    * 引擎会从全局状态大盘 (NM) 中摘取这些字段的最新值，打包传递给副作用函数。
+    */
     effectArgs?: Array<KeysOfUnion<NM>>;
+    /**
+     * 桶的缓存策略
+     * * @description
+     * 控制计算结果的记忆化 (Memoization) 行为。
+     * - `shallow` (默认): 基于依赖项进行浅比较，未变则直接复用缓存。
+     * - `none`: 彻底禁用缓存，每次唤醒必执行。
+     */
     cacheStrategy?: "none" | "shallow";
+    /**
+     *  触发键定义 (精准点火开关)
+     * * @description
+     * 定义该“法条”对源节点中哪些字段的变更敏感。
+     * * **触发行为：**
+     * - **已定义**：仅当列表中的 Key 发生变更时，才执行 `logic`。实现精准的按需计算。
+     * - **未定义 (Default)**：源节点（TriggerPath）内的**任意**字段变更都会唤醒本条逻辑。
+     */
     triggerKeys?: Array<TKeys | Exclude<InternalKeys, 'state'>>;
 }
+/**
+* @group 参数类型
+* @category 纠缠设置
+* @description 提案的update可选的参数，参考{@link GhostProposalApi}
+*/
 type EntangleOp = "add" | "intersect" | "union" | "merge" | "remove";
+/**
+ * 幽灵提案 API (Ghost Proposal API)
+ * * ### 架构思想：延迟决议 (Deferred Resolution)
+ * 在复杂的 DAG (有向无环图) 状态机中，如果在副作用函数中直接修改目标状态（如 `tgt.price = 100`），
+ * 极易引发不可控的竞态条件 (Race Condition)、级联重绘或死循环。
+ *   为了系统性地规避上述风险，MeshFlow 设计了 **“幽灵提案”** 机制。其核心交互模式借鉴了 **Git 的 Pull Request**：
+ * 1. **📝 提交提案 (Propose)**：引擎限制了对状态的直接修改。所有通过此 API 发起的操作（`set` / `update` / `patch`）
+ * 都不会立即生效，而是转化为数据对象并暂存于引擎的缓冲池 (`_ghostBuffer`) 中。
+ * 2. **🛡️ 统一清算 (Resolve)**：当当前批次的所有计算流执行完毕后，引擎会作为调度中心，统一收集并合并这些提案。
+ * 3. **⚖️ 权重裁决 (Weight)**：面对多源并发修改，引擎严格按照提案的**权重 (`weight`)** 和预设策略进行确定性计算，而非依赖执行的先后顺序。
+ * > **💡 总结**：幽灵提案机制将不可控的“时间依赖”转化为了安全的“逻辑依赖”，从而保证了每次状态计算的原子性与确定性。
+ * @example
+ * // 场景：多个规则并发更新购物车总价
+ * engine.config.useEntangle({
+ * // ...
+ * emit: (src, tgt, propose) => {
+ * // 提交增量修改提案，而非直接操作 tgt.totalPrice
+ * propose.update('totalPrice', src.price, 'add');
+ * }
+ * });
+ * @group 参数类型
+ * @category 纠缠设置
+ */
 interface GhostProposalApi<T> {
+    /**
+       * 提交【绝对值覆盖】提案
+       * @description 直接用新值覆盖目标节点的指定状态。
+       * @param key 目标节点的状态属性名
+       * @param value 期望设置的新值
+       * @param weight 提案权重 (默认: 1)。当同一批次内有多个规则试图 `set` 同一个 key 时，权重最高者获胜。
+       */
     set: (key: string, value: any, weight?: number) => void;
+    /**
+       * 提交【增量运算】提案
+       * @description 提交一个增量操作，引擎会在清算时将其与目标节点的旧值进行合并计算。
+       * @param key 目标节点的状态属性名
+       * @param delta 增量数据 (如累加的数值、需追加的数组元素)
+       * @param op 运算策略 (默认: 'add')。支持：累加(add)、移除(remove)、交集(intersect)、并集(union)、深度合并(merge)。
+       */
     update: (key: string, delta: any, op?: EntangleOp) => void;
+    /**
+       * 提交【函数式补丁】提案
+       * @description 基于目标节点的当前状态进行纯函数推导，适用于高度依赖旧值的复杂状态计算。
+       * @param key 目标节点的状态属性名
+       * @param patchFn 状态计算回调。接收该 key 的当前旧值 (`oldState`)，需返回计算后的新值。
+       ** @note ⚠️ **性能预警**：
+       * `patch` 模式虽然具备最高的自由度，在常规业务逻辑（如表单联动、状态切换）中可放心使用。
+       * 但由于其返回对象通常会触发堆内存分配，在高频纠缠的情况下会显著增加 GC压力。
+       * 为了追求极致的内存性能并减少 GC 压力，请优先考虑性能更优的update方法。
+       */
     patch: (key: string, patchFn: (oldState: T) => T) => void;
 }
+/**
+ * 幽灵提案数据载体 (Internal Ghost Payload)
+ * * @description
+ * 这是 {@link GhostProposalApi} 调用的内部物化结构。
+ * 当用户在 `emit` 中调用 `propose` 的相关方法时，引擎会实例化此对象并推入 `_ghostBuffer` 缓冲池，等待当前批次调度结束时由 `resolveGhosts` 统一清算。
+ * * @internal 引擎内部流转类型，普通开发者无需手动构造。
+ * @group Core Api
+ * @category Entanglement
+ */
 type EntangleGhost<T = any> = {
     key: string;
     value?: any;
@@ -212,29 +405,110 @@ type EntangleGhost<T = any> = {
     op?: EntangleOp;
     patch?: (oldState: T) => T;
 };
+/**
+ * 量子纠缠机制的配置选项
+ * @typeParam P - 路径标识类型
+ * @group 参数类型
+ * @category 纠缠设置
+ */
 type EntangleArgType<P extends MeshPath, IsProxy extends boolean = boolean> = {
     cause: P;
     impact: P;
     via: string[];
     isProxy?: IsProxy;
     filter?: (cause: IsProxy extends true ? any : MeshFlowTaskNode<P>, impact: IsProxy extends true ? any : MeshFlowTaskNode<P>) => boolean;
+    /**
+       * @params propose  提案调用参考{@link GhostProposalApi}
+      */
     emit: <T>(cause: IsProxy extends true ? any : MeshFlowTaskNode<P>, impact: IsProxy extends true ? any : MeshFlowTaskNode<P>, propose: GhostProposalApi<T>) => void | EntangleGhost<T> | undefined | Promise<void | EntangleGhost<T> | undefined>;
 };
+/**
+* 引擎点火溯源标识 (Trigger Cause)
+* * @description
+* 用于标识当前计算任务是被何种机制唤醒的。
+* 在复杂的 DAG 图与量子纠缠网络中，精准的溯源不仅有助于 DevTools 的可视化链路追踪，
+* 更是引擎底层防范“无间断递归”和“环路死锁”的核心判定依据。
+* @group 类型管理
+* @category 内部任务触发类型
+*/
 declare const enum TriggerCause {
+    /**
+     * **正向因果推导 (CAUSALITY)**
+     * @description 顺向的拓扑传播。即：上游依赖节点的值发生变更，导致当前节点按照标准的 DAG 边方向被触发重算。
+     * @note 这是引擎最基础、最常规的自然点火原因。
+     */
     CAUSALITY = 0,// 因果推导（正常）
+    /**
+       * **纠缠源头 (INVERSION)**
+       * @description 当前节点作为量子纠缠 (`useEntangle`) 的**“直接标的”**被唤醒。
+       * 即：它是被幽灵提案直接修改的那个节点。它打破了原有的触发链，成为了新一轮拓扑计算的“新源头”。
+       */
     INVERSION = 1,// 逆转回跳（纠缠）
+    /**
+     * **纠缠连锁余波 (REPERCUSSION)**
+     * @description 由 `INVERSION` 节点引发的下游连带更新。
+     * 即：当前节点本身并没有被纠缠直接修改，但因为它的上游节点是被纠缠修改的，它顺着 DAG 拓扑被“余波”唤醒。
+     */
     REPERCUSSION = 2
 }
-
-type ContractType = "boolean" | "scalar" | "array" | "object";
+/**
+ * 引擎预设的桶计算策略
+ * @description 决定了当一个节点绑定了多个规则时，引擎如何处理冲突、优先级以及最终值的推导。
+ * 所有策略均原生支持异步逻辑，并严格保障异步链条中的按序执行原则。
+ * @group 类型管理
+ * @category 桶计算策略类型
+ */
 declare enum DefaultStrategy {
+    /**
+      * **逻辑或 / 短路回退策略 (OR)**
+      * * @description
+      * 按序执行规则。当找到第一个满足条件（逻辑返回真值）的规则时，立即中断后续规则执行（短路机制）。
+      * * **核心行为：**
+      * 1. **短路匹配**：若 `rule.logic` 返回 truthy，将提取该规则的 `value` 作为最终结果并中断。
+      * 2. **异步原子性**：严格按照声明顺序 `await`，保证高优先级规则先被检验。
+      * 3. **底色回退**：若所有普通规则均未匹配（或返回 falsy），则回退使用 `__base__` 规则的值作为兜底保障。
+      */
     OR = "OR",
+    /**
+       * **绝对优先级策略 (PRIORITY)**
+       * * @description
+       * 严格遵循规则顺序的“首中制”策略，适用于互斥型逻辑判断。
+       * * **核心行为：**
+       * 1. **非空即中**：按序执行，首个返回 **非 `undefined`** 的规则直接获胜，立即中断后续计算。
+       * 2. **无视布尔值**：与 `OR` 策略不同，即使逻辑返回 `false`、`0` 或 `null`，只要不是 `undefined`，依然视为有效命中。
+       */
     PRIORITY = "PRIORITY",
+    /**
+       * **聚合策略 (MERGE)**
+       * * @description
+       * 收集桶内所有规则的产出，并按照规则定义的先后顺序进行**结构化合并**。
+       * * **核心特性：**
+       * 1. **有序覆盖**：后执行的规则结果具有更高优先级。
+       * - **对象**：执行浅层合并 `{ ...old, ...new }`，同名键值由后者覆盖。
+       * - **数组**：执行末尾追加 `[...old, ...new]`。
+       * 2. **异步原子性**：原生支持异步规则。即使存在 Promise，引擎也会通过异步链条严格保证合并顺序与规则声明顺序一致。
+       * 3. **底色机制 (__base__)**：支持 `entityId` 为 `__base__` 的特殊规则。其产出作为节点的“底色数据”，会被普通规则的非空产出所覆盖。
+       * * @example
+       * // 场景：多个规则共同定义一个配置对象
+       * // Rule A: { a: 1 }
+       * // Rule B (async): 返回 { b: 2 }
+       * // 最终结果: { a: 1, b: 2 }
+       */
     MERGE = "MERGE"
 }
+
+type ContractType = "boolean" | "scalar" | "array" | "object";
+/**
+ * @group Core Api
+ * @category 内部实现
+ *
+*/
 declare class SchemaBucket<P> {
     private path;
     private strategy;
+    /**
+     * @internal
+     * */
     contract: ContractType;
     private rules;
     private isValue;
@@ -248,11 +522,23 @@ declare class SchemaBucket<P> {
     useCache: boolean;
     private effectArray;
     constructor(baseValue: any, key: string | number | symbol, path: P);
+    /**
+     * @internal
+     * */
     setUseCache(val: boolean): void;
     forceNotify(): void;
+    /**
+     * @internal
+     * */
     isForceNotify(): boolean;
     setStrategy(type: DefaultStrategy): void;
+    /**
+     * @internal
+     * */
     setDefaultRule(value: any): void;
+    /**
+     * @internal
+     * */
     setRules<TKeys = any>(value: {
         value: any;
         targetUid: number;
@@ -265,11 +551,17 @@ declare class SchemaBucket<P> {
         Array<TKeys | Exclude<InternalKeys, "state">>,
         any
     ]>): () => void;
+    /**
+     * @internal
+     * */
     updateDeps<TKeys>(DepsArray: Array<[
         number,
         Array<TKeys | Exclude<InternalKeys, "state">>,
         any
     ]>): void;
+    /**
+     * @internal
+     * */
     setRule<TKeys = any>(value: {
         value: any;
         targetUid: number;
@@ -282,16 +574,28 @@ declare class SchemaBucket<P> {
         Array<TKeys | Exclude<InternalKeys, "state">>,
         any
     ]>): (() => void) | undefined;
+    /**
+     * @internal
+     * */
     setSideEffect(data: {
         fn: (args: any[]) => any;
         args: any[];
     }): void;
+    /**
+     * @internal
+     * */
     getSideEffect(): {
         fn: (args: any) => any;
         args: any[];
     }[];
     evaluate(api: any): any;
+    /**
+     * @internal
+     * */
     private finalizeSync;
+    /**
+     * @internal
+     * */
     private inferType;
 }
 
@@ -394,6 +698,11 @@ declare function useEngineInstance<T, P extends MeshPath, S = any, M extends Rec
     CancelTask: () => void;
 };
 
+/**
+ * @group Core Api
+ * @category 内部实现
+ *
+*/
 declare function useScheduler<T, //ui trigger中定义的类型
 P extends MeshPath, // 路径类型
 B extends Record<string, any> = StandardUITrigger<T>, NM = any>(config: {
@@ -435,7 +744,13 @@ B extends Record<string, any> = StandardUITrigger<T>, NM = any>(config: {
     UidToNodeMap: MeshFlowTaskNode<P, any, NM>[];
 };
 
+/**
+ * @internal
+*/
 type SchedulerType<T, P extends MeshPath, S, M extends Record<string, any>, NM> = ReturnType<typeof useEngineInstance<T, P, S, M, NM>>;
+/**
+ * @internal
+*/
 type BaseEngine<T> = {
     data: {
         SetValue: T extends {
@@ -497,21 +812,43 @@ type BaseEngine<T> = {
         } ? F : never;
     };
 };
+/**
+ * @internal
+*/
 type TransformModuleKey<T> = T extends "useMeshRenderGate" ? "render" : T extends `use${infer Rest}` ? Uncapitalize<Rest> : T;
+/**
+ * @internal
+*/
 type MapModuleToReturn<K, F, P extends MeshPath> = K extends "useSchemaValidators" | "schemaValidators" ? {
     SetValidators: (path: P, options: {
         logic: (val: any, GetByPath: (path: P) => any) => any;
         condition: (data: any) => boolean;
     }) => void;
 } : K extends "useHistory" | "history" | "useMeshRenderGate" | "meshRenderGate" ? F extends (...args: any) => infer R ? R extends (...args: any) => infer R2 ? R2 : R : any : F extends (...args: any) => infer R ? R : any;
+/**
+ * @internal
+*/
 type EngineModules<M extends Record<string, any>, P extends MeshPath> = {
     [K in keyof M as TransformModuleKey<string & K>]: M[K] extends (...args: any) => any ? MapModuleToReturn<K, M[K], P> : M[K] extends Record<string, any> ? EngineModules<M[K], P> : M[K];
 };
+/**
+ *@internal
+ */
 type Engine<T, M extends Record<string, any>, P extends MeshPath> = BaseEngine<T> & {
     modules: EngineModules<M, P>;
 };
-/** @deprecated 请使用新的 useMeshFlow 别名 */
-declare const useEngineManager: <const S extends Record<string, any> | any[], T, //UITrigger的类型
+/**
+* 初始化并获取 MeshFlow 引擎实例
+* * @description
+*
+* * **查看完整的引擎实例 API 文档，请点击这里：** {@link EngineCoreAPI}
+*  @group Core Api
+* @category 入口函数
+* @param id 引擎实例的唯一 ID
+* @param Schema 类型定义模板（仅用于 TS 类型约束，不参与运行逻辑）,注册节点通过模块的方式进行
+* @param options 引擎配置项与扩展模块 {@link MeshFlowOptions}
+*/
+declare const useMeshFlow: <const S extends Record<string, any> | any[], T, //UITrigger的类型
 M extends Record<string, any>, NM extends Record<string, any> = InferLeafType<S>, P extends MeshPath = [InferLeafPath<S>] extends [never] ? MeshPath : InferLeafPath<S> | (string & {})>(id: MeshPath, Schema: S, options: {
     metaType?: NM;
     config?: {
@@ -587,6 +924,20 @@ M extends Record<string, any>, NM extends Record<string, any> = InferLeafType<S>
     destroyPlugin: () => void;
     CancelTask: () => void;
 }, M, P>;
+/**
+ * 类型工厂：锁定全局路径与元数据类型，生成定制化的实例化函数。
+ * @description
+ * 这是一个高阶函数（Currying），旨在解决泛型冗余。通过预先注入 `MeshPath` (P) 和 `MetaType` (NM)，
+ * 你会得到一个“专属”的实例化工具，从而避免在业务代码中反复书写冗长的泛型尖括号。
+ * **工作流：**
+ * 1. 在项目初始化/配置文件中定义：`const defineMesh = useMeshFlowDefiner<MyPaths, MyMeta>();`
+ * 2. 在业务逻辑中实例化：`const engine = defineMesh('app-engine', schema, { ... });`
+ * @template P - 当前项目定义的路径字面量类型 (MeshPath)
+ * @template S - 初始 Schema 的结构定义
+ * @template NM - 节点元数据 (Node Metadata) 的类型定义
+ * @group Core Api
+ * @category 入口函数
+ */
 declare const useMeshFlowDefiner: <P extends MeshPath, S extends Record<string, any> | any[] = any, NM extends Record<string, any> = any>() => <T, M extends Record<string, any>>(id: MeshPath, schema: S, options: {
     metaType?: NM;
     UITrigger?: {
@@ -597,86 +948,26 @@ declare const useMeshFlowDefiner: <P extends MeshPath, S extends Record<string,
     config?: any;
 }) => Engine<SchedulerType<T, P, S, M, NM>, M, P>;
 /**
- * 获取 Engine 实例
- * @template M 手动注入的模块映射 (例如 { useHistory: typeof useHistory })
- * @template P ID 类型 (支持 string | number | symbol)
+ * 实例检索：跨文件/组件获取已激活的 Engine 实例
+ * @description
+ * 只要引擎通过 `useMeshFlow` 或 `defineMesh` 初始化过，你就可以在任何地方通过 ID 直接拿到它。
+ * 无需 Prop Drilling，它是跨组件通讯的核心桥梁。
+ * @template M - 动态插件类型 (可选)
+ * @template P - 路径类型标识 (可选)
+ * @param id - 引擎实例的唯一 ID
+ * @throws {MeshError.EngineNotFound} 如果 ID 对应实例不存在则抛错
+ * @group Core Api
+ * @category 实例管理
  */
 declare const useEngine: <M extends Record<string, any> = {}, P extends MeshPath = any, NM extends Record<string, any> = Record<string, any>, S = any, T = any>(id: MeshPath) => Engine<SchedulerType<T, P, S, M, NM>, M, P>;
+/**
+ * 🗑️ 实例销毁：从全局池中注销并释放引擎资源。
+ * * @description
+ * 彻底切断引擎与其所有插件、异步任务的联系，并从内存中移除引用。
+ * * @param id - 待销毁引擎的唯一标识符
+ * @group Core Api
+ * @category 实例管理
+ */
 declare const deleteEngine: (id: MeshPath) => void;
-declare const useMeshFlow: <const S extends Record<string, any> | any[], T, M extends Record<string, any>, NM extends Record<string, any> = InferLeafType<S>, P extends MeshPath = [InferLeafPath<S>] extends [never] ? MeshPath : (string & {}) | InferLeafPath<S>>(id: MeshPath, Schema: S, options: {
-    metaType?: NM;
-    config?: {
-        useGreedy: boolean;
-        useEntangleStep?: number;
-    };
-    modules?: M;
-    UITrigger?: {
-        signalCreator: () => T;
-        signalTrigger: (signal: T) => void;
-    };
-}) => Engine<{
-    SetRule: <TKeys extends KeysOfUnion<NM>>(outDegreePath: P, inDegreePath: P, key: (string & {}) | KeysOfUnion<NM>, options: SetRuleOptions<NM, TKeys>) => void;
-    SetRules: <TKeys extends KeysOfUnion<NM>>(outDegreePaths: P[], inDegreePath: P, key: (string & {}) | KeysOfUnion<NM>, options: SetRuleOptions<NM, TKeys>) => void;
-    SetStrategy: (path: P, key: KeysOfUnion<NM>, strategy: DefaultStrategy) => void;
-    useEntangle: (config: EntangleArgType<P>) => void;
-    SetTrace: (myPath: P, onUpdate: (newStatus: "idle" | "pending" | "calculating" | "calculated" | "error" | "canceled") => void) => {
-        cancel: () => void;
-    };
-    usePlugin: (plugin: {
-        apply: (api: {
-            on: (event: MeshEventName, cb: Function) => () => boolean | undefined;
-        }) => void;
-    }) => () => void;
-    SetValue: (path: P, key: (string & {}) | KeysOfUnion<NM>, value: any) => void;
-    GetValue: (path: P, key?: string) => any;
-    SetValues: (updates: {
-        path: P;
-        key: (string & {}) | KeysOfUnion<NM>;
-        value: any;
-    }[]) => void;
-    GetGroupByPath: (path: MeshPath) => MeshFlowGroupNode<MeshPath>;
-    notifyAll: () => Promise<void>;
-    GetAllDependency: () => number[][];
-    GetDependencyOrder: () => number[][];
-    historyExports: Partial<MeshFlowHistory>;
-    formExports: {};
-    validatorExports: {
-        SetValidators?: ((path: P, options: {
-            logic: (val: any, GetByPath: any) => any;
-            condition: (data: any) => boolean;
-        }) => void) | undefined;
-    };
-    batchRenderExport: {
-        init: any;
-    };
-    hasRenderGate: () => boolean;
-    onError: (cb: (error: MeshErrorContext) => void) => () => void;
-    onSuccess: (cb: (data: unknown) => void) => () => void;
-    onStart: (cb: (data: {
-        path: P;
-    }) => void) => () => void;
-    scheduler: {
-        registerNode: (nodeMeta: Omit<MeshFlowTaskNode<P, any, any>, "createView" | "proxy" | "dependOn" | "calledBy" | "uid" | "dirtySignal" | "nodeBucket">) => MeshFlowTaskNode<P, any, NM>;
-        registerGroupNode: (groupMeta: Omit<MeshFlowGroupNode<P>, "createView" | "calledBy" | "uid" | "dirtySignal">) => MeshFlowGroupNode<P>;
-        GetNodeByPath: (path: P) => MeshFlowTaskNode<P, any, NM>;
-        GetGroupByPath: (path: MeshPath) => MeshFlowGroupNode<MeshPath>;
-        notify: (path: P) => void;
-        notifyAll: () => Promise<void>;
-        batchNotify: (updates: {
-            path: P;
-            key: (string & {}) | KeysOfUnion<NM>;
-            value: any;
-        }[]) => void;
-        useEntangle: (config: EntangleArgType<P>) => void;
-        updateEntangleLevel: () => void;
-        SetBucket: (newBucket: SchemaBucket<P>) => number;
-        GetBucket: (bucketId: number) => SchemaBucket<P>;
-        CancelTask: () => void;
-        UITrigger: any;
-        UidToNodeMap: MeshFlowTaskNode<P, any, NM>[];
-    };
-    destroyPlugin: () => void;
-    CancelTask: () => void;
-}, M, P>;
 
-export { type BaseEngine, DefaultStrategy, type Engine, type EngineModules, type GhostProposalApi, type InferLeafPath, type InferLeafType, type MapModuleToReturn, type MeshEmit, type MeshErrorContext, type MeshEvents, MeshFlowEventsName, type MeshFlowGroupNode, type MeshFlowTaskNode, type MeshNodeProxy, type MeshPath, type SchedulerType, SchemaBucket, type SetRuleOptions, type TransformModuleKey, TriggerCause, deleteEngine, useEngine, useEngineManager, useMeshFlow, useMeshFlowDefiner, useScheduler };
+export { type BaseEngine, DefaultStrategy, type Engine, type EngineModules, type GhostProposalApi, type InferLeafPath, type InferLeafType, type MapModuleToReturn, type MeshEmit, type MeshErrorContext, type MeshEvents, MeshFlowEventsName, type MeshFlowGroupNode, type MeshFlowTaskNode, type MeshNodeProxy, type MeshPath, type SchedulerType, SchemaBucket, type SetRuleOptions, type TransformModuleKey, TriggerCause, deleteEngine, useEngine, useMeshFlow, useMeshFlowDefiner, useScheduler };