@flowgram.ai/variable-core 0.5.5 → 0.5.7

package/dist/index.d.mts

@@ -3,13 +3,17 @@ import * as _flowgram_ai_utils from '@flowgram.ai/utils';
 import { Disposable, Emitter, DisposableCollection, Event } from '@flowgram.ai/utils';
 import { Subject, Observable, BehaviorSubject, Observer as Observer$1 } from 'rxjs';
 export { Observer } from 'rxjs';
-import * as react from 'react';
+import React from 'react';
 
 /**
  * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * An InversifyJS container module that binds all the necessary services for the variable engine.
+ * This module sets up the dependency injection for the core components of the variable engine.
+ */
 declare const VariableContainerModule: ContainerModule;
 
 /**
@@ -17,11 +21,15 @@ declare const VariableContainerModule: ContainerModule;
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * A provider for dynamically obtaining the `VariableEngine` instance.
+ * This is used to prevent circular dependencies when injecting `VariableEngine`.
+ */
 declare const VariableEngineProvider: unique symbol;
 type VariableEngineProvider = () => VariableEngine;
 
 /**
- * 作用域输出
+ * Manages the output variables of a scope.
  */
 declare class ScopeOutputData {
     readonly scope: Scope;
@@ -30,46 +38,60 @@ declare class ScopeOutputData {
         <T>(key: string | symbol, fn: () => T): T;
         clear: (key?: string | symbol) => void;
     };
+    /**
+     * The variable engine instance.
+     */
     get variableEngine(): VariableEngine;
+    /**
+     * The global variable table from the variable engine.
+     */
     get globalVariableTable(): IVariableTable;
+    /**
+     * The current version of the output data, which increments on each change.
+     */
     get version(): number;
     /**
      * @deprecated use onListOrAnyVarChange instead
      */
     get onDataChange(): _flowgram_ai_utils.Event<void>;
     /**
-     * listen to variable list change
+     * An event that fires when the list of output variables changes.
      */
     get onVariableListChange(): (observer: (variables: VariableDeclaration[]) => void) => _flowgram_ai_utils.Disposable;
     /**
-     * listen to any variable update in list
+     * An event that fires when any output variable's value changes.
      */
     get onAnyVariableChange(): (observer: (changedVariable: VariableDeclaration) => void) => _flowgram_ai_utils.Disposable;
     /**
-     * listen to variable list change + any variable update in list
+     * An event that fires when the output variable list changes or any variable's value is updated.
      */
     get onListOrAnyVarChange(): (observer: () => void) => _flowgram_ai_utils.Disposable;
     protected _hasChanges: boolean;
     constructor(scope: Scope);
     /**
-     * Scope Output Variable Declarations
+     * The output variable declarations of the scope, sorted by order.
      */
     get variables(): VariableDeclaration[];
     /**
-     * Output Variable Keys
+     * The keys of the output variables.
      */
     get variableKeys(): string[];
-    addVariableToTable(variable: VariableDeclaration): void;
-    removeVariableFromTable(key: string): void;
+    protected addVariableToTable(variable: VariableDeclaration): void;
+    protected removeVariableFromTable(key: string): void;
+    /**
+     * Retrieves a variable declaration by its key.
+     * @param key The key of the variable.
+     * @returns The `VariableDeclaration` or `undefined` if not found.
+     */
     getVariableByKey(key: string): VariableDeclaration<any> | undefined;
     /**
-     *
+     * Notifies the covering scopes that the available variables have changed.
      */
     notifyCoversChange(): void;
 }
 
 /**
- * 作用域可用变量
+ * Manages the available variables within a scope.
  */
 declare class ScopeAvailableData {
     readonly scope: Scope;
@@ -77,28 +99,41 @@ declare class ScopeAvailableData {
         <T>(key: string | symbol, fn: () => T): T;
         clear: (key?: string | symbol) => void;
     };
+    /**
+     * The global variable table from the variable engine.
+     */
     get globalVariableTable(): IVariableTable;
     protected _version: number;
     protected refresh$: Subject<void>;
     protected _variables: VariableDeclaration[];
+    /**
+     * The current version of the available data, which increments on each change.
+     */
     get version(): number;
     protected bumpVersion(): void;
+    /**
+     * Refreshes the list of available variables.
+     * This should be called when the dependencies of the scope change.
+     */
     refresh(): void;
     /**
-     * 监听
+     * An observable that emits when the list of available variables changes.
      */
     protected variables$: Observable<VariableDeclaration[]>;
+    /**
+     * An observable that emits when any variable in the available list changes its value.
+     */
     protected anyVariableChange$: Observable<VariableDeclaration>;
     /**
-     * listen to any variable update in list
-     * @param observer
-     * @returns
+     * Subscribes to changes in any variable's value in the available list.
+     * @param observer A function to be called with the changed variable.
+     * @returns A disposable to unsubscribe from the changes.
      */
     onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
     /**
-     * listen to variable list change
-     * @param observer
-     * @returns
+     * Subscribes to changes in the list of available variables.
+     * @param observer A function to be called with the new list of variables.
+     * @returns A disposable to unsubscribe from the changes.
      */
     onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
     /**
@@ -111,31 +146,35 @@ declare class ScopeAvailableData {
      */
     onDataChange: _flowgram_ai_utils.Event<VariableDeclaration<any>[]>;
     /**
-     * listen to variable list change + any variable drilldown change
+     * An event that fires when the variable list changes or any variable's value is updated.
      */
     onListOrAnyVarChange: _flowgram_ai_utils.Event<VariableDeclaration<any>[]>;
     constructor(scope: Scope);
     /**
-     * 获取可消费变量
+     * Gets the list of available variables.
      */
     get variables(): VariableDeclaration[];
     /**
-     * 获取可访问的变量 keys
+     * Gets the keys of the available variables.
      */
     get variableKeys(): string[];
     /**
-     * 返回依赖的作用域
+     * Gets the dependency scopes.
      */
     get depScopes(): Scope[];
     /**
-     * 通过 keyPath 找到可用变量
-     * @param keyPath
-     * @returns
+     * Retrieves a variable field by its key path from the available variables.
+     * @param keyPath The key path to the variable field.
+     * @returns The found `BaseVariableField` or `undefined`.
      */
     getByKeyPath(keyPath?: string[]): BaseVariableField | undefined;
     /**
-     * Track Variable Change (Includes type update and children update) By KeyPath
-     * @returns
+     * Tracks changes to a variable field by its key path.
+     * This includes changes to its type, value, or any nested properties.
+     * @param keyPath The key path to the variable field to track.
+     * @param cb The callback to execute when the variable changes.
+     * @param opts Configuration options for the subscription.
+     * @returns A disposable to unsubscribe from the tracking.
      */
     trackByKeyPath<Data = BaseVariableField | undefined>(keyPath: string[] | undefined, cb: (variable?: Data) => void, opts?: SubscribeConfig<BaseVariableField | undefined, Data>): Disposable;
 }
@@ -146,15 +185,36 @@ declare class ScopeAvailableData {
  */
 
 type Observer<ActionType extends GlobalEventActionType = GlobalEventActionType> = (action: ActionType) => void;
+/**
+ * Manages global events within a scope.
+ */
 declare class ScopeEventData {
     readonly scope: Scope;
     event$: Subject<GlobalEventActionType>;
+    /**
+     * Dispatches a global event.
+     * @param action The event action to dispatch.
+     */
     dispatch<ActionType extends GlobalEventActionType = GlobalEventActionType>(action: ActionType): void;
+    /**
+     * Subscribes to all global events.
+     * @param observer The observer function to call with the event action.
+     * @returns A disposable to unsubscribe from the events.
+     */
     subscribe<ActionType extends GlobalEventActionType = GlobalEventActionType>(observer: Observer<ActionType>): Disposable;
+    /**
+     * Subscribes to a specific type of global event.
+     * @param type The type of the event to subscribe to.
+     * @param observer The observer function to call with the event action.
+     * @returns A disposable to unsubscribe from the event.
+     */
     on<ActionType extends GlobalEventActionType = GlobalEventActionType>(type: ActionType['type'], observer: Observer<ActionType>): Disposable;
     constructor(scope: Scope);
 }
 
+/**
+ * Interface for the Scope constructor.
+ */
 interface IScopeConstructor {
     new (options: {
         id: string | symbol;
@@ -162,38 +222,43 @@ interface IScopeConstructor {
         meta?: Record<string, any>;
     }): Scope;
 }
+/**
+ * Represents a variable scope, which manages its own set of variables and their lifecycle.
+ * - `scope.output` represents the variables declared within this scope.
+ * - `scope.available` represents all variables accessible from this scope, including those from parent scopes.
+ */
 declare class Scope<ScopeMeta extends Record<string, any> = Record<string, any>> {
     /**
-     * Scope 唯一索引
+     * A unique identifier for the scope.
      */
     readonly id: string | symbol;
     /**
-     * Scope 依赖变量引擎
+     * The variable engine instance this scope belongs to.
      */
     readonly variableEngine: VariableEngine;
     /**
-     * 作用域的基本元信息，包括作用域所在节点及一些 flag 信息，上层业务可以额外扩展
+     * Metadata associated with the scope, which can be extended by higher-level business logic.
      */
     readonly meta: ScopeMeta;
     /**
-     * 作用域 AST 根节点
-     * - Map<formItemKey, formItemValue>
+     * The root AST node for this scope, which is a MapNode.
+     * It stores various data related to the scope, such as `outputs`.
      */
     readonly ast: MapNode;
     /**
-     * 可用变量数据管理
+     * Manages the available variables for this scope.
      */
     readonly available: ScopeAvailableData;
     /**
-     * 输出变量数据管理
+     * Manages the output variables for this scope.
      */
     readonly output: ScopeOutputData;
     /**
-     * 作用域事件管理
+     * Manages event dispatching and handling for this scope.
      */
     readonly event: ScopeEventData;
     /**
-     * 数据缓存
+     * A memoization utility for caching computed values.
      */
     protected memo: {
         <T>(key: string | symbol, fn: () => T): T;
@@ -205,47 +270,62 @@ declare class Scope<ScopeMeta extends Record<string, any> = Record<string, any>>
         variableEngine: VariableEngine;
         meta?: ScopeMeta;
     });
+    /**
+     * Refreshes the covering scopes.
+     */
     refreshCovers(): void;
+    /**
+     * Refreshes the dependency scopes and the available variables.
+     */
     refreshDeps(): void;
+    /**
+     * Gets the scopes that this scope depends on.
+     */
     get depScopes(): Scope[];
+    /**
+     * Gets the scopes that are covered by this scope.
+     */
     get coverScopes(): Scope[];
+    /**
+     * Disposes of the scope and its resources.
+     * This will also trigger updates in dependent and covering scopes.
+     */
     dispose(): void;
     onDispose: _flowgram_ai_utils.Event<void>;
     get disposed(): boolean;
     /**
-     * Sets a variable in the Scope with the default key 'outputs'.
+     * Sets a variable in the scope with the default key 'outputs'.
      *
-     * @param json - The JSON value to store.
-     * @returns The updated AST node.
+     * @param json The JSON representation of the AST node to set.
+     * @returns The created or updated AST node.
      */
-    setVar(json: ASTNodeJSON): ASTNode;
+    setVar<Node extends ASTNode = ASTNode>(json: ASTNodeJSON): Node;
     /**
-     * Sets a variable in the Scope by key.
+     * Sets a variable in the scope with a specified key.
      *
-     * @param key - The key of the variable to set.
-     * @param json - The JSON value to store.
-     * @returns The updated AST node.
+     * @param key The key of the variable to set.
+     * @param json The JSON representation of the AST node to set.
+     * @returns The created or updated AST node.
      */
-    setVar(key: string, json: ASTNodeJSON): ASTNode;
+    setVar<Node extends ASTNode = ASTNode>(key: string, json: ASTNodeJSON): Node;
     /**
-     * Retrieves a variable from the Scope by key.
+     * Retrieves a variable from the scope by its key.
      *
-     * @param key - The key of the variable to retrieve. Defaults to 'outputs'.
-     * @returns The value of the variable, or undefined if not found.
+     * @param key The key of the variable to retrieve. Defaults to 'outputs'.
+     * @returns The AST node for the variable, or `undefined` if not found.
      */
-    getVar(key?: string): ASTNode<any, any> | undefined;
+    getVar<Node extends ASTNode = ASTNode>(key?: string): Node | undefined;
     /**
-     * Clears a variable from the Scope by key.
+     * Clears a variable from the scope by its key.
      *
-     * @param key - The key of the variable to clear. Defaults to 'outputs'.
-     * @returns The updated AST node.
+     * @param key The key of the variable to clear. Defaults to 'outputs'.
      */
     clearVar(key?: string): void;
 }
 
 /**
- * 作用域依赖关系管理数据结构
- * - ScopeOrder 可能存在多种实现方式，因此采取抽象类的方式，具体的实现由子类实现
+ * Manages the dependency relationships between scopes.
+ * This is an abstract class, and specific implementations determine how the scope order is managed.
  */
 declare abstract class ScopeChain {
     readonly toDispose: DisposableCollection;
@@ -253,11 +333,25 @@ declare abstract class ScopeChain {
     get variableEngine(): VariableEngine;
     constructor();
     /**
-     * 所有作用域依赖关系刷新
+     * Refreshes the dependency and coverage relationships for all scopes.
      */
     refreshAllChange(): void;
+    /**
+     * Gets the dependency scopes for a given scope.
+     * @param scope The scope to get dependencies for.
+     * @returns An array of dependency scopes.
+     */
     abstract getDeps(scope: Scope): Scope[];
+    /**
+     * Gets the covering scopes for a given scope.
+     * @param scope The scope to get covers for.
+     * @returns An array of covering scopes.
+     */
     abstract getCovers(scope: Scope): Scope[];
+    /**
+     * Sorts all scopes based on their dependency relationships.
+     * @returns A sorted array of all scopes.
+     */
     abstract sortAll(): Scope[];
     dispose(): void;
     get disposed(): boolean;
@@ -268,133 +362,157 @@ interface ASTNodeRegistry<JSON extends ASTNodeJSON = any, InjectOpts = any> {
     kind: string;
     new (params: CreateASTParams, injectOpts: InjectOpts): ASTNode<JSON>;
 }
+/**
+ * An `ASTNode` represents a fundamental unit of variable information within the system's Abstract Syntax Tree.
+ * It can model various constructs, for example:
+ * - **Declarations**: `const a = 1`
+ * - **Expressions**: `a.b.c`
+ * - **Types**: `number`, `string`, `boolean`
+ *
+ * Here is some characteristic of ASTNode:
+ * - **Tree-like Structure**: ASTNodes can be nested to form a tree, representing complex variable structures.
+ * - **Extendable**: New features can be added by extending the base ASTNode class.
+ * - **Reactive**: Changes in an ASTNode's value trigger events, enabling reactive programming patterns.
+ * - **Serializable**: ASTNodes can be converted to and from a JSON format (ASTNodeJSON) for storage or transmission.
+ */
 declare abstract class ASTNode<JSON extends ASTNodeJSON = any, InjectOpts = any> implements Disposable {
     /**
      * @deprecated
-     * 获取 ASTNode 注入的 opts
+     * Get the injected options for the ASTNode.
      *
-     * 请使用 @injectToAst(XXXService) declare xxxService: XXXService 实现外部依赖注入
+     * Please use `@injectToAst(XXXService) declare xxxService: XXXService` to achieve external dependency injection.
      */
     readonly opts?: InjectOpts;
     /**
-     * 节点的唯一标识符，节点不指定则默认由 nanoid 生成，不可更改
-     * - 如需要生成新 key，则销毁当前节点并生成新的节点
+     * The unique identifier of the ASTNode, which is **immutable**.
+     * - Immutable: Once assigned, the key cannot be changed.
+     * - Automatically generated if not specified, and cannot be changed as well.
+     * - If a new key needs to be generated, the current ASTNode should be destroyed and a new ASTNode should be generated.
      */
     readonly key: Identifier;
     /**
-     * 节点类型
+     * The kind of the ASTNode.
      */
     static readonly kind: ASTKindType;
     /**
-     * 节点 Flags，记录一些 Flag 信息
+     * Node flags, used to record some flag information.
      */
     readonly flags: number;
     /**
-     * 节点所处的作用域
+     * The scope in which the ASTNode is located.
      */
     readonly scope: Scope;
     /**
-     * 父节点
+     * The parent ASTNode.
      */
     readonly parent: ASTNode | undefined;
     /**
-     * 节点的版本号，每 fireChange 一次 version + 1
+     * The version number of the ASTNode, which increments by 1 each time `fireChange` is called.
      */
     protected _version: number;
     /**
-     * 更新锁
+     * Update lock.
+     * - When set to `true`, `fireChange` will not trigger any events.
+     * - This is useful when multiple updates are needed, and you want to avoid multiple triggers.
      */
     changeLocked: boolean;
     /**
-     * Batch Update 相关参数
+     * Parameters related to batch updates.
      */
     private _batch;
     /**
-     * AST 节点变化事件，基于 Rxjs 实现
-     * - 使用了 BehaviorSubject, 在订阅时会自动触发一次事件，事件为当前值
+     * AST node change Observable events, implemented based on RxJS.
+     * - Emits the current ASTNode value upon subscription.
+     * - Emits a new value whenever `fireChange` is called.
      */
     readonly value$: BehaviorSubject<ASTNode>;
     /**
-     * 子节点
+     * Child ASTNodes.
      */
     protected _children: Set<ASTNode<any, any>>;
     /**
-     * 删除节点处理事件列表
+     * List of disposal handlers for the ASTNode.
      */
     readonly toDispose: DisposableCollection;
     /**
-     * 销毁时触发的回调
+     * Callback triggered upon disposal.
      */
     onDispose: _flowgram_ai_utils.Event<void>;
     /**
-     * 构造函数
-     * @param createParams 创建 ASTNode 的必要参数
-     * @param injectOptions 依赖注入各种模块
+     * Constructor.
+     * @param createParams Necessary parameters for creating an ASTNode.
+     * @param injectOptions Dependency injection for various modules.
      */
     constructor({ key, parent, scope }: CreateASTParams, opts?: InjectOpts);
     /**
-     * AST 节点的类型
+     * The type of the ASTNode.
      */
     get kind(): string;
     /**
-     * 解析 AST JSON 数据
-     * @param json AST JSON 数据
+     * Parses AST JSON data.
+     * @param json AST JSON data.
      */
     abstract fromJSON(json: JSON): void;
     /**
-     * 获取当前节点所有子节点
+     * Gets all child ASTNodes of the current ASTNode.
      */
     get children(): ASTNode[];
     /**
-     * 转化为 ASTNodeJSON
+     * Serializes the current ASTNode to ASTNodeJSON.
      * @returns
      */
     toJSON(): ASTNodeJSON;
     /**
-     * 创建子节点
-     * @param json 子节点的 AST JSON
+     * Creates a child ASTNode.
+     * @param json The AST JSON of the child ASTNode.
      * @returns
      */
     protected createChildNode<ChildNode extends ASTNode = ASTNode>(json: ASTNodeJSON): ChildNode;
     /**
-     * 更新子节点，快速实现子节点更新消费逻辑
-     * @param keyInThis 当前对象上的指定 key
+     * Updates a child ASTNode, quickly implementing the consumption logic for child ASTNode updates.
+     * @param keyInThis The specified key on the current object.
      */
     protected updateChildNodeByKey(keyInThis: keyof this, nextJSON?: ASTNodeJSON): void;
     /**
-     * 批处理更新，批处理函数内所有的 fireChange 都合并成一个
-     * @param updater 批处理函数
+     * Batch updates the ASTNode, merging all `fireChange` calls within the batch function into one.
+     * @param updater The batch function.
      * @returns
      */
     protected withBatchUpdate<ParamTypes extends any[], ReturnType>(updater: (...args: ParamTypes) => ReturnType): (...args: ParamTypes) => ReturnType;
     /**
-     * 触发当前节点更新
+     * Triggers an update for the current node.
      */
     fireChange(): void;
     /**
-     * 节点的版本值
-     * - 通过 NodeA === NodeB && versionA === versionB 可以比较两者是否相等
+     * The version value of the ASTNode.
+     * - You can used to check whether ASTNode are updated.
      */
     get version(): number;
     /**
-     * 节点唯一 hash 值
+     * The unique hash value of the ASTNode.
+     * - It will update when the ASTNode is updated.
+     * - You can used to check two ASTNode are equal.
      */
     get hash(): string;
     /**
-     * 监听 AST 节点的变化
-     * @param observer 监听回调
-     * @param selector 监听指定数据
+     * Listens for changes to the ASTNode.
+     * @param observer The listener callback.
+     * @param selector Listens for specified data.
      * @returns
      */
     subscribe<Data = this>(observer: ObserverOrNext<Data>, { selector, debounceAnimation, triggerOnInit }?: SubscribeConfig<this, Data>): Disposable;
+    /**
+     * Dispatches a global event for the current ASTNode.
+     * @param event The global event.
+     */
     dispatchGlobalEvent<ActionType extends GlobalEventActionType = GlobalEventActionType>(event: Omit<ActionType, 'ast'>): void;
     /**
-     * 销毁
+     * Disposes the ASTNode.
      */
     dispose(): void;
     get disposed(): boolean;
     /**
-     * 节点扩展信息
+     * Extended information of the ASTNode.
      */
     [key: string]: unknown;
 }
@@ -406,46 +524,116 @@ declare abstract class ASTNode<JSON extends ASTNodeJSON = any, InjectOpts = any>
 
 type ASTKindType = string;
 type Identifier = string;
+/**
+ * ASTNodeJSON is the JSON representation of an ASTNode.
+ */
 interface ASTNodeJSON {
+    /**
+     * Kind is the type of the AST node.
+     */
     kind?: ASTKindType;
+    /**
+     * Key is the unique identifier of the node.
+     * If not provided, the node will generate a default key value.
+     */
     key?: Identifier;
     [key: string]: any;
 }
 /**
- * 核心 AST 节点类型
+ * Core AST node types.
  */
 declare enum ASTKind {
     /**
-     * 类型相关
-     * - 内部默认实现一套基于 JSON 类型的类型 AST 节点
+     * # Type-related.
+     * - A set of type AST nodes based on JSON types is implemented internally by default.
+     */
+    /**
+     * String type.
+     */
+    String = "String",
+    /**
+     * Number type.
+     */
+    Number = "Number",
+    /**
+     * Integer type.
+     */
+    Integer = "Integer",
+    /**
+     * Boolean type.
+     */
+    Boolean = "Boolean",
+    /**
+     * Object type.
+     */
+    Object = "Object",
+    /**
+     * Array type.
+     */
+    Array = "Array",
+    /**
+     * Map type.
+     */
+    Map = "Map",
+    /**
+     * Union type.
+     * Commonly used for type checking, generally not exposed to the business.
+     */
+    Union = "Union",
+    /**
+     * Any type.
+     * Commonly used for business logic.
+     */
+    Any = "Any",
+    /**
+     * Custom type.
+     * For business-defined types.
+     */
+    CustomType = "CustomType",
+    /**
+     * # Declaration-related.
+     */
+    /**
+     * Field definition for Object drill-down.
+     */
+    Property = "Property",
+    /**
+     * Variable declaration.
+     */
+    VariableDeclaration = "VariableDeclaration",
+    /**
+     * Variable declaration list.
+     */
+    VariableDeclarationList = "VariableDeclarationList",
+    /**
+     * # Expression-related.
      */
-    String = "String",// 字符串
-    Number = "Number",// 数字
-    Integer = "Integer",// 整数
-    Boolean = "Boolean",// 布尔值
-    Object = "Object",// Object
-    Array = "Array",// Array
-    Map = "Map",// Map
-    Union = "Union",// 联合类型，常用于类型判断，一般不对业务透出
-    Any = "Any",// 任意类型，常用于业务判断
-    CustomType = "CustomType",// 自定义类型，用于业务自定义类型
     /**
-     * 声明
+     * Access fields on variables through the path system.
      */
-    Property = "Property",// Object 下钻的字段定义
-    VariableDeclaration = "VariableDeclaration",// 变量声明
-    VariableDeclarationList = "VariableDeclarationList",// 变量声明
+    KeyPathExpression = "KeyPathExpression",
     /**
-     * 表达式
+     * Iterate over specified data.
      */
-    KeyPathExpression = "KeyPathExpression",// 通过路径系统访问变量上的字段
-    EnumerateExpression = "EnumerateExpression",// 对指定的数据进行遍历
-    WrapArrayExpression = "WrapArrayExpression",// Wrap with Array Type
+    EnumerateExpression = "EnumerateExpression",
     /**
-     * 通用 AST 节点
+     * Wrap with Array Type.
+     */
+    WrapArrayExpression = "WrapArrayExpression",
+    /**
+     * # General-purpose AST nodes.
+     */
+    /**
+     * General-purpose List<ASTNode> storage node.
+     */
+    ListNode = "ListNode",
+    /**
+     * General-purpose data storage node.
+     */
+    DataNode = "DataNode",
+    /**
+     * General-purpose Map<string, ASTNode> storage node.
      */
-    ListNode = "ListNode",// 通用 List<ASTNode> 存储节点
-    DataNode = "DataNode",// 通用的数据存储节点
     MapNode = "MapNode"
 }
 interface CreateASTParams {
@@ -460,14 +648,24 @@ interface SubscribeConfig<This, Data> {
     triggerOnInit?: boolean;
     selector?: (curr: This) => Data;
 }
+/**
+ * TypeUtils to get the JSON representation of an AST node with a specific kind.
+ */
 type GetKindJSON<KindType extends string, JSON extends ASTNodeJSON> = {
     kind: KindType;
     key?: Identifier;
 } & JSON;
+/**
+ * TypeUtils to get the JSON representation of an AST node with a specific kind or just the kind string.
+ */
 type GetKindJSONOrKind<KindType extends string, JSON extends ASTNodeJSON> = ({
     kind: KindType;
     key?: Identifier;
 } & JSON) | KindType;
+/**
+ * Global event action type.
+ * - Global event might be dispatched from `ASTNode` or `Scope`.
+ */
 interface GlobalEventActionType<Type = string, Payload = any, AST extends ASTNode = ASTNode> {
     type: Type;
     payload?: Payload;
@@ -480,27 +678,30 @@ interface GlobalEventActionType<Type = string, Payload = any, AST extends ASTNod
  */
 
 type DataInjector = () => Record<string, any>;
+/**
+ * Register the AST node to the engine.
+ */
 declare class ASTRegisters {
     protected injectors: Map<ASTKindType, DataInjector>;
     protected astMap: Map<ASTKindType, ASTNodeRegistry>;
     /**
-     * 核心 AST 节点注册
+     * Core AST node registration.
      */
     constructor();
     /**
-     * 创建 AST 节点
-     * @param param 创建参数
+     * Creates an AST node.
+     * @param param Creation parameters.
      * @returns
      */
     createAST<ReturnNode extends ASTNode = ASTNode>(json: ASTNodeJSON, { parent, scope }: CreateASTParams): ReturnNode;
     /**
-     * 根据 AST 节点类型获取节点 Registry
+     * Gets the node Registry by AST node type.
      * @param kind
      * @returns
      */
     getASTRegistryByKind(kind: ASTKindType): ASTNodeRegistry<any, any> | undefined;
     /**
-     * 注册 AST 节点
+     * Registers an AST node.
      * @param ASTNode
      * @param injector
      */
@@ -511,23 +712,44 @@ declare class ASTRegisters {
  * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
  * SPDX-License-Identifier: MIT
  */
+/**
+ * ASTNode flags. Stored in the `flags` property of the `ASTNode`.
+ */
 declare enum ASTNodeFlags {
+    /**
+     * None.
+     */
     None = 0,
     /**
-     * 变量字段
+     * Variable Field.
      */
     VariableField = 1,
     /**
-     * 表达式
+     * Expression.
      */
     Expression = 4,
     /**
-     * 变量类型
+     * # Variable Type Flags
+     */
+    /**
+     *  Basic type.
+     */
+    BasicType = 8,
+    /**
+     * Drillable variable type.
+     */
+    DrilldownType = 16,
+    /**
+     * Enumerable variable type.
+     */
+    EnumerateType = 32,
+    /**
+     * Composite type, currently not in use.
+     */
+    UnionType = 64,
+    /**
+     * Variable type.
      */
-    BasicType = 8,// 基础类型
-    DrilldownType = 16,// 可下钻的变量类型
-    EnumerateType = 32,// 可遍历的变量类型
-    UnionType = 64,// 复合类型，暂时不存在
     VariableType = 120
 }
 
@@ -537,16 +759,31 @@ declare enum ASTNodeFlags {
  */
 
 /**
- * 通用数据 AST 节点，无子节点
+ * Represents a general data node with no child nodes.
  */
 declare class DataNode<Data = any> extends ASTNode {
     static kind: string;
     protected _data: Data;
+    /**
+     * The data of the node.
+     */
     get data(): Data;
+    /**
+     * Deserializes the `DataNodeJSON` to the `DataNode`.
+     * @param json The `DataNodeJSON` to deserialize.
+     */
     fromJSON(json: Data): void;
+    /**
+     * Serialize the `DataNode` to `DataNodeJSON`.
+     * @returns The JSON representation of `DataNode`.
+     */
     toJSON(): {
         kind: ASTKind;
     } & Data;
+    /**
+     * Partially update the data of the node.
+     * @param nextData The data to be updated.
+     */
     partialUpdate(nextData: Data): void;
 }
 
@@ -555,14 +792,34 @@ declare class DataNode<Data = any> extends ASTNode {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `ListNode`
+ */
 interface ListNodeJSON {
+    /**
+     * The list of nodes.
+     */
     list: ASTNodeJSON[];
 }
+/**
+ * Represents a list of nodes.
+ */
 declare class ListNode extends ASTNode<ListNodeJSON> {
     static kind: string;
     protected _list: ASTNode[];
+    /**
+     * The list of nodes.
+     */
     get list(): ASTNode[];
+    /**
+     * Deserializes the `ListNodeJSON` to the `ListNode`.
+     * @param json The `ListNodeJSON` to deserialize.
+     */
     fromJSON({ list }: ListNodeJSON): void;
+    /**
+     * Serialize the `ListNode` to `ListNodeJSON`.
+     * @returns The JSON representation of `ListNode`.
+     */
     toJSON(): ASTNodeJSON;
 }
 
@@ -571,31 +828,49 @@ declare class ListNode extends ASTNode<ListNodeJSON> {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `MapNode`
+ */
 interface MapNodeJSON {
+    /**
+     * The map of nodes.
+     */
     map: [string, ASTNodeJSON][];
 }
+/**
+ * Represents a map of nodes.
+ */
 declare class MapNode extends ASTNode<MapNodeJSON> {
     static kind: string;
     protected map: Map<string, ASTNode>;
+    /**
+     * Deserializes the `MapNodeJSON` to the `MapNode`.
+     * @param json The `MapNodeJSON` to deserialize.
+     */
     fromJSON({ map }: MapNodeJSON): void;
+    /**
+     * Serialize the `MapNode` to `MapNodeJSON`.
+     * @returns The JSON representation of `MapNode`.
+     */
     toJSON(): ASTNodeJSON;
     /**
-     * 往 Map 中设置 ASTNode
-     * @param key ASTNode 的索引，
-     * @param json
+     * Set a node in the map.
+     * @param key The key of the node.
+     * @param nextJSON The JSON representation of the node.
+     * @returns The node instance.
      */
     set<Node extends ASTNode = ASTNode>(key: string, nextJSON: ASTNodeJSON): Node;
     /**
-     * 移除指定 ASTNode
-     * @param key
+     * Remove a node from the map.
+     * @param key The key of the node.
      */
     remove(key: string): void;
     /**
-     * 获取 ASTNode
-     * @param key
-     * @returns
+     * Get a node from the map.
+     * @param key The key of the node.
+     * @returns The node instance if found, otherwise `undefined`.
      */
-    get(key: string): ASTNode | undefined;
+    get<Node extends ASTNode = ASTNode>(key: string): Node | undefined;
 }
 
 /**
@@ -603,21 +878,30 @@ declare class MapNode extends ASTNode<MapNodeJSON> {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * Base class for all types.
+ *
+ * All other types should extend this class.
+ */
 declare abstract class BaseType<JSON extends ASTNodeJSON = any, InjectOpts = any> extends ASTNode<JSON, InjectOpts> {
     flags: number;
     /**
-     * 类型是否一致
-     * @param targetTypeJSON
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * 可下钻类型需实现
-     * @param keyPath
+     * Get a variable field by key path.
+     *
+     * This method should be implemented by drillable types.
+     * @param keyPath The key path to search for.
+     * @returns The variable field if found, otherwise `undefined`.
      */
     getByKeyPath(keyPath?: string[]): BaseVariableField | undefined;
     /**
-     * Get AST JSON for current base type
-     * @returns
+     * Serialize the node to a JSON object.
+     * @returns The JSON representation of the node.
      */
     toJSON(): ASTNodeJSON;
 }
@@ -627,9 +911,12 @@ declare abstract class BaseType<JSON extends ASTNodeJSON = any, InjectOpts = any
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of the `StringType`.
+ */
 interface StringJSON {
     /**
-     * https://json-schema.org/understanding-json-schema/reference/type#format
+     * see https://json-schema.org/understanding-json-schema/reference/type#format
      */
     format?: string;
 }
@@ -638,9 +925,14 @@ declare class StringType extends BaseType {
     static kind: string;
     protected _format?: string;
     /**
-     * https://json-schema.org/understanding-json-schema/reference/type#format
+     * see https://json-schema.org/understanding-json-schema/reference/string#format
      */
     get format(): string | undefined;
+    /**
+     * Deserialize the `StringJSON` to the `StringType`.
+     *
+     * @param json StringJSON representation of the `StringType`.
+     */
     fromJSON(json?: StringJSON): void;
 }
 
@@ -649,9 +941,16 @@ declare class StringType extends BaseType {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * Represents an integer type.
+ */
 declare class IntegerType extends BaseType {
     flags: ASTNodeFlags;
     static kind: string;
+    /**
+     * Deserializes the `IntegerJSON` to the `IntegerType`.
+     * @param json The `IntegerJSON` to deserialize.
+     */
     fromJSON(): void;
 }
 
@@ -660,8 +959,15 @@ declare class IntegerType extends BaseType {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * Represents a boolean type.
+ */
 declare class BooleanType extends BaseType {
     static kind: string;
+    /**
+     * Deserializes the `BooleanJSON` to the `BooleanType`.
+     * @param json The `BooleanJSON` to deserialize.
+     */
     fromJSON(): void;
 }
 
@@ -670,8 +976,15 @@ declare class BooleanType extends BaseType {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * Represents a number type.
+ */
 declare class NumberType extends BaseType {
     static kind: string;
+    /**
+     * Deserializes the `NumberJSON` to the `NumberType`.
+     * @param json The `NumberJSON` to deserialize.
+     */
     fromJSON(): void;
 }
 
@@ -680,23 +993,56 @@ declare class NumberType extends BaseType {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `ArrayType`
+ */
 interface ArrayJSON {
+    /**
+     * The type of the items in the array.
+     */
     items?: ASTNodeJSONOrKind;
 }
+/**
+ * Represents an array type.
+ */
 declare class ArrayType extends BaseType<ArrayJSON> {
     flags: ASTNodeFlags;
     static kind: string;
+    /**
+     * The type of the items in the array.
+     */
     items: BaseType;
+    /**
+     * Deserializes the `ArrayJSON` to the `ArrayType`.
+     * @param json The `ArrayJSON` to deserialize.
+     */
     fromJSON({ items }: ArrayJSON): void;
+    /**
+     * Whether the items type can be drilled down.
+     */
     get canDrilldownItems(): boolean;
+    /**
+     * Get a variable field by key path.
+     * @param keyPath The key path to search for.
+     * @returns The variable field if found, otherwise `undefined`.
+     */
     getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * Array 强比较
-     * @param targetTypeJSON
-     * @returns
+     * Array strong comparison.
+     * @param targetTypeJSON The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
+    /**
+     * Serialize the `ArrayType` to `ArrayJSON`
+     * @returns The JSON representation of `ArrayType`.
+     */
     toJSON(): ASTNodeJSON;
 }
 
@@ -705,22 +1051,53 @@ declare class ArrayType extends BaseType<ArrayJSON> {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `MapType`
+ */
 interface MapJSON {
+    /**
+     * The type of the keys in the map.
+     */
     keyType?: ASTNodeJSONOrKind;
+    /**
+     * The type of the values in the map.
+     */
     valueType?: ASTNodeJSONOrKind;
 }
+/**
+ * Represents a map type.
+ */
 declare class MapType extends BaseType<MapJSON> {
     static kind: string;
+    /**
+     * The type of the keys in the map.
+     */
     keyType: BaseType;
+    /**
+     * The type of the values in the map.
+     */
     valueType: BaseType;
+    /**
+     * Deserializes the `MapJSON` to the `MapType`.
+     * @param json The `MapJSON` to deserialize.
+     */
     fromJSON({ keyType, valueType }: MapJSON): void;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * Map 强比较
-     * @param targetTypeJSON
-     * @returns
+     * Map strong comparison.
+     * @param targetTypeJSON The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
+    /**
+     * Serialize the node to a JSON object.
+     * @returns The JSON representation of the node.
+     */
     toJSON(): ASTNodeJSON;
 }
 
@@ -729,9 +1106,15 @@ declare class MapType extends BaseType<MapJSON> {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of the `Property`.
+ */
 type PropertyJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
     key: string;
 };
+/**
+ * `Property` is a variable field that represents a property of a `ObjectType`.
+ */
 declare class Property<VariableMeta = any> extends BaseVariableField<VariableMeta> {
     static kind: string;
 }
@@ -741,34 +1124,64 @@ declare class Property<VariableMeta = any> extends BaseVariableField<VariableMet
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `ObjectType`
+ */
 interface ObjectJSON<VariableMeta = any> {
     /**
-     *  Object 的 properties 一定是 Property 类型，因此业务可以不用填 kind
+     * The properties of the object.
+     *
+     * The `properties` of an Object must be of type `Property`, so the business can omit the `kind` field.
      */
     properties?: PropertyJSON<VariableMeta>[];
 }
+/**
+ * Action type for object properties change.
+ */
 type ObjectPropertiesChangeAction = GlobalEventActionType<'ObjectPropertiesChange', {
     prev: Property[];
     next: Property[];
 }, ObjectType>;
+/**
+ * Represents an object type.
+ */
 declare class ObjectType extends BaseType<ObjectJSON> {
     flags: ASTNodeFlags;
     static kind: string;
+    /**
+     * A map of property keys to `Property` instances.
+     */
     propertyTable: Map<string, Property>;
+    /**
+     * An array of `Property` instances.
+     */
     properties: Property[];
+    /**
+     * Deserializes the `ObjectJSON` to the `ObjectType`.
+     * @param json The `ObjectJSON` to deserialize.
+     */
     fromJSON({ properties }: ObjectJSON): void;
+    /**
+     * Serialize the `ObjectType` to `ObjectJSON`.
+     * @returns The JSON representation of `ObjectType`.
+     */
     toJSON(): ASTNodeJSON;
     /**
-     * 根据 KeyPath 找到对应的变量
-     * @param keyPath 变量路径
-     * @returns
+     * Get a variable field by key path.
+     * @param keyPath The key path to search for.
+     * @returns The variable field if found, otherwise `undefined`.
      */
     getByKeyPath(keyPath: string[]): Property | undefined;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
     /**
-     * Object 类型强比较
-     * @param targetTypeJSON
-     * @returns
+     * Object type strong comparison.
+     * @param targetTypeJSON The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
      */
     protected customStrongEqual(targetTypeJSON: ASTNodeJSON): boolean;
 }
@@ -778,6 +1191,9 @@ declare class ObjectType extends BaseType<ObjectJSON> {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `UnionType`, which union multiple `BaseType`.
+ */
 interface UnionJSON {
     types?: ASTNodeJSONOrKind[];
 }
@@ -787,14 +1203,35 @@ interface UnionJSON {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `CustomType`
+ */
 interface CustomTypeJSON {
+    /**
+     * The name of the custom type.
+     */
     typeName: string;
 }
+/**
+ * Represents a custom type.
+ */
 declare class CustomType extends BaseType<CustomTypeJSON> {
     static kind: string;
     protected _typeName: string;
+    /**
+     * The name of the custom type.
+     */
     get typeName(): string;
+    /**
+     * Deserializes the `CustomTypeJSON` to the `CustomType`.
+     * @param json The `CustomTypeJSON` to deserialize.
+     */
     fromJSON(json: CustomTypeJSON): void;
+    /**
+     * Check if the current type is equal to the target type.
+     * @param targetTypeJSONOrKind The type to compare with.
+     * @returns `true` if the types are equal, `false` otherwise.
+     */
     isTypeEqual(targetTypeJSONOrKind?: ASTNodeJSONOrKind): boolean;
 }
 
@@ -804,38 +1241,47 @@ declare class CustomType extends BaseType<CustomTypeJSON> {
  */
 
 type ExpressionRefs = (BaseVariableField | undefined)[];
+/**
+ * Base class for all expressions.
+ *
+ * All other expressions should extend this class.
+ */
 declare abstract class BaseExpression<JSON extends ASTNodeJSON = any, InjectOpts = any> extends ASTNode<JSON, InjectOpts> {
     flags: ASTNodeFlags;
     /**
-     * 获取全局变量表，方便表达式获取引用变量
+     * Get the global variable table, which is used to access referenced variables.
      */
     get globalVariableTable(): IVariableTable;
     /**
-     * 父变量字段，通过由近而远的方式进行排序
+     * Parent variable fields, sorted from closest to farthest.
      */
     get parentFields(): BaseVariableField[];
     /**
-     * 获取表达式引用的变量字段
-     * - 通常是 变量 VariableDeclaration，或者 属性 Property 节点
+     * Get the variable fields referenced by the expression.
+     *
+     * This method should be implemented by subclasses.
+     * @returns An array of referenced variable fields.
      */
     abstract getRefFields(): ExpressionRefs;
     /**
-     * 表达式返回的数据类型
+     * The return type of the expression.
      */
     abstract returnType: BaseType | undefined;
     /**
-     * 引用变量
+     * The variable fields referenced by the expression.
      */
     protected _refs: ExpressionRefs;
+    /**
+     * The variable fields referenced by the expression.
+     */
     get refs(): ExpressionRefs;
     protected refreshRefs$: Subject<void>;
     /**
-     * 刷新变量引用
+     * Refresh the variable references.
      */
     refreshRefs(): void;
     /**
-     * 监听引用变量变化
-     * 监听 [a.b.c] -> [a.b]
+     * An observable that emits the referenced variable fields when they change.
      */
     refs$: Observable<ExpressionRefs>;
     constructor(params: CreateASTParams, opts?: InjectOpts);
@@ -846,45 +1292,43 @@ declare abstract class BaseExpression<JSON extends ASTNodeJSON = any, InjectOpts
  * SPDX-License-Identifier: MIT
  */
 
-interface KeyPathExpressionJSON$1 {
-    keyPath: string[];
-}
-declare class KeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON$1> extends BaseExpression<CustomPathJSON> {
-    static kind: string;
-    protected _keyPath: string[];
-    get keyPath(): string[];
-    getRefFields(): BaseVariableField[];
-    get returnType(): BaseType | undefined;
-    /**
-     * 业务重改该方法可快速定制自己的 Path 表达式
-     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-     * @param json 业务定义的 Path 表达式
-     * @returns
-     */
-    protected parseToKeyPath(json: CustomPathJSON): string[];
-    fromJSON(json: CustomPathJSON): void;
-    constructor(params: CreateASTParams, opts: any);
-    toJSON(): ASTNodeJSON;
-}
-
 /**
- * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
- * SPDX-License-Identifier: MIT
+ * ASTNodeJSON representation of `EnumerateExpression`
  */
-
 interface EnumerateExpressionJSON {
+    /**
+     * The expression to be enumerated.
+     */
     enumerateFor: ASTNodeJSON;
 }
 /**
- * 遍历表达式，对列表进行遍历，获取遍历后的变量类型
+ * Represents an enumeration expression, which iterates over a list and returns the type of the enumerated variable.
  */
 declare class EnumerateExpression extends BaseExpression<EnumerateExpressionJSON> {
     static kind: string;
     protected _enumerateFor: BaseExpression | undefined;
+    /**
+     * The expression to be enumerated.
+     */
     get enumerateFor(): BaseExpression<any, any> | undefined;
+    /**
+     * The return type of the expression.
+     */
     get returnType(): BaseType | undefined;
+    /**
+     * Get the variable fields referenced by the expression.
+     * @returns An empty array, as this expression does not reference any variables.
+     */
     getRefFields(): [];
+    /**
+     * Deserializes the `EnumerateExpressionJSON` to the `EnumerateExpression`.
+     * @param json The `EnumerateExpressionJSON` to deserialize.
+     */
     fromJSON({ enumerateFor: expression }: EnumerateExpressionJSON): void;
+    /**
+     * Serialize the `EnumerateExpression` to `EnumerateExpressionJSON`.
+     * @returns The JSON representation of `EnumerateExpression`.
+     */
     toJSON(): ASTNodeJSON;
 }
 
@@ -893,32 +1337,69 @@ declare class EnumerateExpression extends BaseExpression<EnumerateExpressionJSON
  * SPDX-License-Identifier: MIT
  */
 
-interface KeyPathExpressionJSON {
+/**
+ * ASTNodeJSON representation of `KeyPathExpression`
+ */
+interface KeyPathExpressionJSON$1 {
+    /**
+     * The key path of the variable.
+     */
     keyPath: string[];
 }
 /**
- * 新版 KeyPathExpressionV2，相比旧版：
- * - returnType 拷贝新一份，避免引用问题
- * - 引入成环检测
+ * Represents a key path expression, which is used to reference a variable by its key path.
+ *
+ * This is the V2 of `KeyPathExpression`, with the following improvements:
+ * - `returnType` is copied to a new instance to avoid reference issues.
+ * - Circular reference detection is introduced.
  */
-declare class KeyPathExpressionV2<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON> extends BaseExpression<CustomPathJSON> {
+declare class KeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON$1> extends BaseExpression<CustomPathJSON> {
     static kind: string;
     protected _keyPath: string[];
+    /**
+     * The key path of the variable.
+     */
     get keyPath(): string[];
+    /**
+     * Get the variable fields referenced by the expression.
+     * @returns An array of referenced variable fields.
+     */
     getRefFields(): BaseVariableField[];
+    /**
+     * The return type of the expression.
+     *
+     * A new `returnType` node is generated directly, instead of reusing the existing one, to ensure that different key paths do not point to the same field.
+     */
     _returnType: BaseType;
+    /**
+     * The return type of the expression.
+     */
     get returnType(): BaseType<any, any>;
     /**
-     * 业务重改该方法可快速定制自己的 Path 表达式
-     * - 只需要将业务的 Path 解析为变量系统的 KeyPath 即可
-     * @param json 业务定义的 Path 表达式
-     * @returns
+     * Parse the business-defined path expression into a key path.
+     *
+     * Businesses can quickly customize their own path expressions by modifying this method.
+     * @param json The path expression defined by the business.
+     * @returns The key path.
      */
     protected parseToKeyPath(json: CustomPathJSON): string[];
+    /**
+     * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+     * @param json The `KeyPathExpressionJSON` to deserialize.
+     */
     fromJSON(json: CustomPathJSON): void;
+    /**
+     * Get the return type JSON by reference.
+     * @param _ref The referenced variable field.
+     * @returns The JSON representation of the return type.
+     */
     getReturnTypeJSONByRef(_ref: BaseVariableField | undefined): ASTNodeJSON | undefined;
     protected prevRefTypeHash: string | undefined;
     constructor(params: CreateASTParams, opts: any);
+    /**
+     * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+     * @returns The JSON representation of `KeyPathExpression`.
+     */
     toJSON(): ASTNodeJSON;
 }
 
@@ -927,70 +1408,209 @@ declare class KeyPathExpressionV2<CustomPathJSON extends ASTNodeJSON = KeyPathEx
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * ASTNodeJSON representation of `KeyPathExpression`
+ */
+interface KeyPathExpressionJSON {
+    /**
+     * The key path of the variable.
+     */
+    keyPath: string[];
+}
+/**
+ * @deprecated Use `KeyPathExpression` instead.
+ * Represents a key path expression, which is used to reference a variable by its key path.
+ */
+declare class LegacyKeyPathExpression<CustomPathJSON extends ASTNodeJSON = KeyPathExpressionJSON> extends BaseExpression<CustomPathJSON> {
+    static kind: string;
+    protected _keyPath: string[];
+    /**
+     * The key path of the variable.
+     */
+    get keyPath(): string[];
+    /**
+     * Get the variable fields referenced by the expression.
+     * @returns An array of referenced variable fields.
+     */
+    getRefFields(): BaseVariableField[];
+    /**
+     * The return type of the expression.
+     */
+    get returnType(): BaseType | undefined;
+    /**
+     * Parse the business-defined path expression into a key path.
+     *
+     * Businesses can quickly customize their own path expressions by modifying this method.
+     * @param json The path expression defined by the business.
+     * @returns The key path.
+     */
+    protected parseToKeyPath(json: CustomPathJSON): string[];
+    /**
+     * Deserializes the `KeyPathExpressionJSON` to the `KeyPathExpression`.
+     * @param json The `KeyPathExpressionJSON` to deserialize.
+     */
+    fromJSON(json: CustomPathJSON): void;
+    constructor(params: CreateASTParams, opts: any);
+    /**
+     * Serialize the `KeyPathExpression` to `KeyPathExpressionJSON`.
+     * @returns The JSON representation of `KeyPathExpression`.
+     */
+    toJSON(): ASTNodeJSON;
+}
+
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of `WrapArrayExpression`
+ */
 interface WrapArrayExpressionJSON {
+    /**
+     * The expression to be wrapped.
+     */
     wrapFor: ASTNodeJSON;
 }
 /**
- * 遍历表达式，对列表进行遍历，获取遍历后的变量类型
+ * Represents a wrap expression, which wraps an expression with an array.
  */
 declare class WrapArrayExpression extends BaseExpression<WrapArrayExpressionJSON> {
     static kind: string;
     protected _wrapFor: BaseExpression | undefined;
     protected _returnType: BaseType | undefined;
+    /**
+     * The expression to be wrapped.
+     */
     get wrapFor(): BaseExpression<any, any> | undefined;
+    /**
+     * The return type of the expression.
+     */
     get returnType(): BaseType | undefined;
+    /**
+     * Refresh the return type of the expression.
+     */
     refreshReturnType(): void;
+    /**
+     * Get the variable fields referenced by the expression.
+     * @returns An empty array, as this expression does not reference any variables.
+     */
     getRefFields(): [];
+    /**
+     * Deserializes the `WrapArrayExpressionJSON` to the `WrapArrayExpression`.
+     * @param json The `WrapArrayExpressionJSON` to deserialize.
+     */
     fromJSON({ wrapFor: expression }: WrapArrayExpressionJSON): void;
+    /**
+     * Serialize the `WrapArrayExpression` to `WrapArrayExpressionJSON`.
+     * @returns The JSON representation of `WrapArrayExpression`.
+     */
     toJSON(): ASTNodeJSON;
     protected init(): void;
 }
 
 /**
- * 声明类 AST 节点
+ * ASTNodeJSON representation of `BaseVariableField`
  */
 type BaseVariableFieldJSON<VariableMeta = any> = {
+    /**
+     * key of the variable field
+     * - For `VariableDeclaration`, the key should be global unique.
+     * - For `Property`, the key is the property name.
+     */
     key?: Identifier;
+    /**
+     * type of the variable field, similar to js code:
+     * `const v: string`
+     */
     type?: ASTNodeJSONOrKind;
+    /**
+     * initializer of the variable field, similar to js code:
+     * `const v = 'hello'`
+     *
+     * with initializer, the type of field will be inferred from the initializer.
+     */
     initializer?: ASTNodeJSON;
+    /**
+     * meta data of the variable field, you cans store information like `title`, `icon`, etc.
+     */
     meta?: VariableMeta;
 };
+/**
+ * Variable Field abstract class, which is the base class for `VariableDeclaration` and `Property`
+ *
+ * - `VariableDeclaration` is used to declare a variable in a block scope.
+ * - `Property` is used to declare a property in an object.
+ */
 declare abstract class BaseVariableField<VariableMeta = any> extends ASTNode<BaseVariableFieldJSON<VariableMeta>> {
     flags: ASTNodeFlags;
     protected _type?: BaseType;
     protected _meta: VariableMeta;
     protected _initializer?: BaseExpression;
     /**
-     * 父变量字段，通过由近而远的方式进行排序
+     * Parent variable fields, sorted from closest to farthest
      */
     get parentFields(): BaseVariableField[];
+    /**
+     * KeyPath of the variable field, sorted from farthest to closest
+     */
     get keyPath(): string[];
+    /**
+     * Metadata of the variable field, you cans store information like `title`, `icon`, etc.
+     */
     get meta(): VariableMeta;
+    /**
+     * Type of the variable field, similar to js code:
+     * `const v: string`
+     */
     get type(): BaseType;
+    /**
+     * Initializer of the variable field, similar to js code:
+     * `const v = 'hello'`
+     *
+     * with initializer, the type of field will be inferred from the initializer.
+     */
     get initializer(): BaseExpression | undefined;
+    /**
+     * The global unique hash of the field, and will be changed when the field is updated.
+     */
     get hash(): string;
     /**
-     * 解析 VariableDeclarationJSON 从而生成变量声明节点
+     * Deserialize the `BaseVariableFieldJSON` to the `BaseVariableField`.
+     * @param json ASTJSON representation of `BaseVariableField`
      */
     fromJSON({ type, initializer, meta }: BaseVariableFieldJSON<VariableMeta>): void;
+    /**
+     * Update the type of the variable field
+     * @param type type ASTJSON representation of Type
+     */
     updateType(type: BaseVariableFieldJSON['type']): void;
+    /**
+     * Update the initializer of the variable field
+     * @param nextInitializer initializer ASTJSON representation of Expression
+     */
     updateInitializer(nextInitializer?: BaseVariableFieldJSON['initializer']): void;
+    /**
+     * Update the meta data of the variable field
+     * @param nextMeta meta data of the variable field
+     */
     updateMeta(nextMeta: VariableMeta): void;
     /**
-     * 根据 keyPath 去找下钻的变量字段
+     * Get the variable field by keyPath, similar to js code:
+     * `v.a.b`
      * @param keyPath
      * @returns
      */
     getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
     /**
-     * 监听类型变化
+     * Subscribe to type change of the variable field
      * @param observer
      * @returns
      */
     onTypeChange(observer: (type: ASTNode | undefined) => void): _flowgram_ai_utils.Disposable;
     /**
-     * 转换为 JSON
-     * @returns
+     * Serialize the variable field to JSON
+     * @returns ASTNodeJSON representation of `BaseVariableField`
      */
     toJSON(): BaseVariableFieldJSON<VariableMeta> & {
         kind: string;
@@ -998,22 +1618,39 @@ declare abstract class BaseVariableField<VariableMeta = any> extends ASTNode<Bas
 }
 
 /**
- * 声明类 AST 节点
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * ASTNodeJSON representation of the `VariableDeclaration`.
  */
 type VariableDeclarationJSON<VariableMeta = any> = BaseVariableFieldJSON<VariableMeta> & {
+    /**
+     * Variable sorting order, which is used to sort variables in `scope.outputs.variables`
+     */
     order?: number;
 };
+/**
+ * `VariableDeclaration` is a variable field that represents a variable declaration.
+ */
 declare class VariableDeclaration<VariableMeta = any> extends BaseVariableField<VariableMeta> {
     static kind: string;
     protected _order: number;
+    /**
+     * Variable sorting order, which is used to sort variables in `scope.outputs.variables`
+     */
     get order(): number;
     constructor(params: CreateASTParams);
     /**
-     * 解析 VariableDeclarationJSON 从而生成变量声明节点
+     * Deserialize the `VariableDeclarationJSON` to the `VariableDeclaration`.
      */
     fromJSON({ order, ...rest }: VariableDeclarationJSON<VariableMeta>): void;
+    /**
+     * Update the sorting order of the variable declaration.
+     * @param order Variable sorting order. Default is 0.
+     */
     updateOrder(order?: number): void;
-    onTypeChange(observer: (type: ASTNode | undefined) => void): _flowgram_ai_utils.Disposable;
 }
 
 /**
@@ -1023,9 +1660,12 @@ declare class VariableDeclaration<VariableMeta = any> extends BaseVariableField<
 
 interface VariableDeclarationListJSON<VariableMeta = any> {
     /**
-     *  declarations 一定是 VariableDeclaration 类型，因此业务可以不用填 kind
+     * `declarations` must be of type `VariableDeclaration`, so the business can omit the `kind` field.
      */
     declarations?: VariableDeclarationJSON<VariableMeta>[];
+    /**
+     * The starting order number for variables.
+     */
     startOrder?: number;
 }
 type VariableDeclarationListChangeAction = GlobalEventActionType<'VariableListChange', {
@@ -1034,53 +1674,102 @@ type VariableDeclarationListChangeAction = GlobalEventActionType<'VariableListCh
 }, VariableDeclarationList>;
 declare class VariableDeclarationList extends ASTNode<VariableDeclarationListJSON> {
     static kind: string;
+    /**
+     * Map of variable declarations, keyed by variable name.
+     */
     declarationTable: Map<string, VariableDeclaration>;
+    /**
+     * Variable declarations, sorted by `order`.
+     */
     declarations: VariableDeclaration[];
+    /**
+     * Deserialize the `VariableDeclarationListJSON` to the `VariableDeclarationList`.
+     * - VariableDeclarationListChangeAction will be dispatched after deserialization.
+     *
+     * @param declarations Variable declarations.
+     * @param startOrder The starting order number for variables. Default is 0.
+     */
     fromJSON({ declarations, startOrder }: VariableDeclarationListJSON): void;
+    /**
+     * Serialize the `VariableDeclarationList` to the `VariableDeclarationListJSON`.
+     * @returns ASTJSON representation of `VariableDeclarationList`
+     */
     toJSON(): ASTNodeJSON;
 }
 
+/**
+ * Variable-core ASTNode factories.
+ */
 declare namespace ASTFactory {
     /**
-     * 类型相关
-     * @returns
+     * Type-related factories.
+     */
+    /**
+     * Creates a `String` type node.
      */
     const createString: (json?: StringJSON) => {
         format?: string;
         kind: ASTKind;
     };
+    /**
+     * Creates a `Number` type node.
+     */
     const createNumber: () => {
         kind: ASTKind;
     };
+    /**
+     * Creates a `Boolean` type node.
+     */
     const createBoolean: () => {
         kind: ASTKind;
     };
+    /**
+     * Creates an `Integer` type node.
+     */
     const createInteger: () => {
         kind: ASTKind;
     };
+    /**
+     * Creates an `Object` type node.
+     */
     const createObject: (json: ObjectJSON) => {
         properties?: PropertyJSON<any>[] | undefined;
         kind: ASTKind;
     };
+    /**
+     * Creates an `Array` type node.
+     */
     const createArray: (json: ArrayJSON) => {
         items?: ASTNodeJSONOrKind;
         kind: ASTKind;
     };
+    /**
+     * Creates a `Map` type node.
+     */
     const createMap: (json: MapJSON) => {
         keyType?: ASTNodeJSONOrKind;
         valueType?: ASTNodeJSONOrKind;
         kind: ASTKind;
     };
+    /**
+     * Creates a `Union` type node.
+     */
     const createUnion: (json: UnionJSON) => {
         types?: ASTNodeJSONOrKind[];
         kind: ASTKind;
     };
+    /**
+     * Creates a `CustomType` node.
+     */
     const createCustomType: (json: CustomTypeJSON) => {
         typeName: string;
         kind: ASTKind;
     };
     /**
-     * 声明相关
+     * Declaration-related factories.
+     */
+    /**
+     * Creates a `VariableDeclaration` node.
      */
     const createVariableDeclaration: <VariableMeta = any>(json: VariableDeclarationJSON<VariableMeta>) => {
         key?: Identifier;
@@ -1090,6 +1779,9 @@ declare namespace ASTFactory {
         order?: number;
         kind: ASTKind;
     };
+    /**
+     * Creates a `Property` node.
+     */
     const createProperty: <VariableMeta = any>(json: PropertyJSON<VariableMeta>) => {
         key: Identifier;
         type?: ASTNodeJSONOrKind;
@@ -1097,28 +1789,47 @@ declare namespace ASTFactory {
         meta?: VariableMeta | undefined;
         kind: ASTKind;
     };
+    /**
+     * Creates a `VariableDeclarationList` node.
+     */
     const createVariableDeclarationList: (json: VariableDeclarationListJSON) => {
         declarations?: VariableDeclarationJSON<any>[] | undefined;
         startOrder?: number;
         kind: ASTKind;
     };
     /**
-     * 表达式相关
+     * Expression-related factories.
+     */
+    /**
+     * Creates an `EnumerateExpression` node.
      */
     const createEnumerateExpression: (json: EnumerateExpressionJSON) => {
         enumerateFor: ASTNodeJSON;
         kind: ASTKind;
     };
+    /**
+     * Creates a `KeyPathExpression` node.
+     */
     const createKeyPathExpression: (json: KeyPathExpressionJSON$1) => {
         keyPath: string[];
         kind: ASTKind;
     };
+    /**
+     * Creates a `WrapArrayExpression` node.
+     */
     const createWrapArrayExpression: (json: WrapArrayExpressionJSON) => {
         wrapFor: ASTNodeJSON;
         kind: ASTKind;
     };
     /**
-     * 通过 AST Class 创建
+     * Create by AST Class.
+     */
+    /**
+     * Creates Type-Safe ASTNodeJSON object based on the provided AST class.
+     *
+     * @param targetType Target ASTNode class.
+     * @param json The JSON data for the node.
+     * @returns The ASTNode JSON object.
      */
     const create: <JSON extends ASTNodeJSON>(targetType: {
         kind: string;
@@ -1133,32 +1844,87 @@ declare namespace ASTFactory {
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * Variable-core ASTNode matchers.
+ *
+ * - Typescript code inside if statement will be type guarded.
+ */
 declare namespace ASTMatch {
     /**
-     * 类型相关
-     * @returns
+     * # Type-related matchers.
+     */
+    /**
+     * Check if the node is a `StringType`.
      */
     const isString: (node?: ASTNode) => node is StringType;
+    /**
+     * Check if the node is a `NumberType`.
+     */
     const isNumber: (node?: ASTNode) => node is NumberType;
+    /**
+     * Check if the node is a `BooleanType`.
+     */
     const isBoolean: (node?: ASTNode) => node is BooleanType;
+    /**
+     * Check if the node is a `IntegerType`.
+     */
     const isInteger: (node?: ASTNode) => node is IntegerType;
+    /**
+     * Check if the node is a `ObjectType`.
+     */
     const isObject: (node?: ASTNode) => node is ObjectType;
+    /**
+     * Check if the node is a `ArrayType`.
+     */
     const isArray: (node?: ASTNode) => node is ArrayType;
+    /**
+     * Check if the node is a `MapType`.
+     */
     const isMap: (node?: ASTNode) => node is MapType;
+    /**
+     * Check if the node is a `CustomType`.
+     */
     const isCustomType: (node?: ASTNode) => node is CustomType;
     /**
-     * 声明相关
+     * # Declaration-related matchers.
+     */
+    /**
+     * Check if the node is a `VariableDeclaration`.
      */
     const isVariableDeclaration: <VariableMeta = any>(node?: ASTNode) => node is VariableDeclaration<VariableMeta>;
+    /**
+     * Check if the node is a `Property`.
+     */
     const isProperty: <VariableMeta = any>(node?: ASTNode) => node is Property<VariableMeta>;
+    /**
+     * Check if the node is a `BaseVariableField`.
+     */
+    const isBaseVariableField: (node?: ASTNode) => node is BaseVariableField;
+    /**
+     * Check if the node is a `VariableDeclarationList`.
+     */
     const isVariableDeclarationList: (node?: ASTNode) => node is VariableDeclarationList;
     /**
-     * 表达式相关
+     * # Expression-related matchers.
+     */
+    /**
+     * Check if the node is a `EnumerateExpression`.
      */
     const isEnumerateExpression: (node?: ASTNode) => node is EnumerateExpression;
+    /**
+     * Check if the node is a `WrapArrayExpression`.
+     */
+    const isWrapArrayExpression: (node?: ASTNode) => node is WrapArrayExpression;
+    /**
+     * Check if the node is a `KeyPathExpression`.
+     */
     const isKeyPathExpression: (node?: ASTNode) => node is KeyPathExpression;
     /**
-     * Check AST Match by ASTClass
+     * Check ASTNode Match by ASTClass
+     *
+     * @param node ASTNode to be checked.
+     * @param targetType Target ASTNode class.
+     * @returns Whether the node is of the target type.
      */
     function is<TargetASTNode extends ASTNode>(node?: ASTNode, targetType?: {
         kind: string;
@@ -1195,27 +1961,89 @@ declare function isMatchAST<TargetASTNode extends ASTNode>(node?: ASTNode, targe
  * SPDX-License-Identifier: MIT
  */
 
+/**
+ * Action type for scope changes.
+ */
 interface ScopeChangeAction {
     type: 'add' | 'delete' | 'update' | 'available';
     scope: Scope;
 }
+/**
+ * Interface for a variable table.
+ */
 interface IVariableTable extends Disposable {
+    /**
+     * The parent variable table.
+     */
     parentTable?: IVariableTable;
+    /**
+     * @deprecated Use `onVariableListChange` or `onAnyVariableChange` instead.
+     */
     onDataChange: Event<void>;
+    /**
+     * The current version of the variable table.
+     */
     version: number;
+    /**
+     * The list of variables in the table.
+     */
     variables: VariableDeclaration[];
+    /**
+     * The keys of the variables in the table.
+     */
     variableKeys: string[];
+    /**
+     * Fires a change event.
+     */
     fireChange(): void;
+    /**
+     * Gets a variable or property by its key path.
+     * @param keyPath The key path to the variable or property.
+     * @returns The found `BaseVariableField` or `undefined`.
+     */
     getByKeyPath(keyPath: string[]): BaseVariableField | undefined;
+    /**
+     * Gets a variable by its key.
+     * @param key The key of the variable.
+     * @returns The found `VariableDeclaration` or `undefined`.
+     */
     getVariableByKey(key: string): VariableDeclaration | undefined;
+    /**
+     * Disposes the variable table.
+     */
     dispose(): void;
+    /**
+     * Subscribes to changes in the variable list.
+     * @param observer The observer function.
+     * @returns A disposable to unsubscribe.
+     */
     onVariableListChange(observer: (variables: VariableDeclaration[]) => void): Disposable;
+    /**
+     * Subscribes to changes in any variable's value.
+     * @param observer The observer function.
+     * @returns A disposable to unsubscribe.
+     */
     onAnyVariableChange(observer: (changedVariable: VariableDeclaration) => void): Disposable;
+    /**
+     * Subscribes to both variable list changes and any variable's value changes.
+     * @param observer The observer function.
+     * @returns A disposable to unsubscribe.
+     */
     onListOrAnyVarChange(observer: () => void): Disposable;
 }
 
+/**
+ * The core of the variable engine system.
+ * It manages scopes, variables, and events within the system.
+ */
 declare class VariableEngine implements Disposable {
+    /**
+     * The scope chain, which manages the dependency relationships between scopes.
+     */
     readonly chain: ScopeChain;
+    /**
+     * The registry for all AST node types.
+     */
     readonly astRegisters: ASTRegisters;
     protected toDispose: DisposableCollection;
     protected memo: {
@@ -1223,40 +2051,113 @@ declare class VariableEngine implements Disposable {
         clear: (key?: string | symbol) => void;
     };
     protected scopeMap: Map<string | symbol, Scope<Record<string, any>>>;
+    /**
+     * A rxjs subject that emits global events occurring within the variable engine.
+     */
     globalEvent$: Subject<GlobalEventActionType>;
     protected onScopeChangeEmitter: Emitter<ScopeChangeAction>;
+    /**
+     * A table containing all global variables.
+     */
     globalVariableTable: IVariableTable;
+    /**
+     * An event that fires whenever a scope is added, updated, or deleted.
+     */
     onScopeChange: _flowgram_ai_utils.Event<ScopeChangeAction>;
     private readonly containerProvider;
+    /**
+     * The Inversify container instance.
+     */
     get container(): interfaces.Container;
-    constructor(chain: ScopeChain, // 作用域依赖关系偏序集
+    constructor(
+    /**
+     * The scope chain, which manages the dependency relationships between scopes.
+     */
+    chain: ScopeChain, 
+    /**
+     * The registry for all AST node types.
+     */
     astRegisters: ASTRegisters);
+    /**
+     * Disposes of all resources used by the variable engine.
+     */
     dispose(): void;
+    /**
+     * Retrieves a scope by its unique identifier.
+     * @param scopeId The ID of the scope to retrieve.
+     * @returns The scope if found, otherwise undefined.
+     */
     getScopeById(scopeId: string | symbol): Scope | undefined;
+    /**
+     * Removes a scope by its unique identifier and disposes of it.
+     * @param scopeId The ID of the scope to remove.
+     */
     removeScopeById(scopeId: string | symbol): void;
     /**
-     * Get Scope, if Scope exists and type is same, will use it directly
-     * @param id scope id
-     * @param meta scope meta, defined by user
-     * @param ScopeConstructor scope constructor, default is Scope. you can extends Scope to create your own scope
-     * @returns
+     * Creates a new scope or retrieves an existing one if the ID and type match.
+     * @param id The unique identifier for the scope.
+     * @param meta Optional metadata for the scope, defined by the user.
+     * @param options Options for creating the scope.
+     * @param options.ScopeConstructor The constructor to use for creating the scope. Defaults to `Scope`.
+     * @returns The created or existing scope.
      */
     createScope(id: string | symbol, meta?: Record<string, any>, options?: {
         ScopeConstructor?: IScopeConstructor;
     }): Scope;
+    /**
+     * Retrieves all scopes currently managed by the engine.
+     * @param options Options for retrieving the scopes.
+     * @param options.sort Whether to sort the scopes based on their dependency chain.
+     * @returns An array of all scopes.
+     */
     getAllScopes({ sort, }?: {
         sort?: boolean;
     }): Scope[];
+    /**
+     * Fires a global event to be broadcast to all listeners.
+     * @param event The global event to fire.
+     */
     fireGlobalEvent(event: GlobalEventActionType): void;
+    /**
+     * Subscribes to a specific type of global event.
+     * @param type The type of the event to listen for.
+     * @param observer A function to be called when the event is observed.
+     * @returns A disposable object to unsubscribe from the event.
+     */
     onGlobalEvent<ActionType extends GlobalEventActionType = GlobalEventActionType>(type: ActionType['type'], observer: (action: ActionType) => void): Disposable;
 }
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
 interface ScopeContextProps {
     scope: Scope;
 }
-declare const ScopeProvider: react.Provider<ScopeContextProps>;
-declare const useScopeContext: () => ScopeContextProps | null;
-declare const useCurrentScope: () => Scope<Record<string, any>>;
+/**
+ * ScopeProvider provides the scope to its children via context.
+ */
+declare const ScopeProvider: (props: React.PropsWithChildren<{
+    /**
+     * scope used in the context
+     */
+    scope?: Scope;
+    /**
+     * @deprecated use scope prop instead, this is kept for backward compatibility
+     */
+    value?: ScopeContextProps;
+}>) => React.JSX.Element;
+/**
+ * useCurrentScope returns the scope provided by ScopeProvider.
+ * @returns
+ */
+declare const useCurrentScope: <Strict extends boolean = false>(params?: {
+    /**
+     * whether to throw error when no scope in ScopeProvider is found
+     */
+    strict: Strict;
+}) => Strict extends true ? Scope : Scope | undefined;
 
 /**
  * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
@@ -1264,9 +2165,14 @@ declare const useCurrentScope: () => Scope<Record<string, any>>;
  */
 
 /**
+ * Get the available variables in the current scope.
  * 获取作用域的可访问变量
+ *
+ * @returns the available variables in the current scope
  */
-declare function useScopeAvailable(): ScopeAvailableData;
+declare function useScopeAvailable(params?: {
+    autoRefresh?: boolean;
+}): ScopeAvailableData;
 
 /**
  * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
@@ -1274,25 +2180,66 @@ declare function useScopeAvailable(): ScopeAvailableData;
  */
 
 /**
- * 获取作用域的可访问变量
+ * Get available variable list in the current scope.
+ *
+ * - If no scope, return global variable list.
+ * - The hook is reactive to variable list or any variables change.
  */
 declare function useAvailableVariables(): VariableDeclaration[];
 
+/**
+ * Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+ * SPDX-License-Identifier: MIT
+ */
+
+/**
+ * Get output variable list in the current scope.
+ *
+ * - The hook is reactive to variable list or any variables change.
+ */
+declare function useOutputVariables(): VariableDeclaration[];
+
 interface RenameInfo {
     before: BaseVariableField;
     after: BaseVariableField;
 }
+/**
+ * This service is responsible for detecting when a variable field's key is renamed.
+ * It listens for changes in variable declaration lists and object properties, and
+ * determines if a change constitutes a rename operation.
+ */
 declare class VariableFieldKeyRenameService {
     variableEngine: VariableEngine;
     toDispose: DisposableCollection;
     renameEmitter: Emitter<RenameInfo>;
+    /**
+     * Emits events for fields that are disposed of during a list change, but not renamed.
+     * This helps distinguish between a field that was truly removed and one that was renamed.
+     */
     disposeInListEmitter: Emitter<BaseVariableField<any>>;
+    /**
+     * An event that fires when a variable field key is successfully renamed.
+     */
     onRename: _flowgram_ai_utils.Event<RenameInfo>;
+    /**
+     * An event that fires when a field is removed from a list (and not part of a rename).
+     */
     onDisposeInList: _flowgram_ai_utils.Event<BaseVariableField<any>>;
+    /**
+     * Handles changes in a list of fields to detect rename operations.
+     * @param ast The AST node where the change occurred.
+     * @param prev The list of fields before the change.
+     * @param next The list of fields after the change.
+     */
     handleFieldListChange(ast?: ASTNode, prev?: BaseVariableField[], next?: BaseVariableField[]): void;
+    /**
+     * Notifies listeners about fields that were removed from a list.
+     * @param prev The list of fields before the change.
+     * @param next The list of fields after the change.
+     */
     notifyFieldsDispose(prev?: BaseVariableField[], next?: BaseVariableField[]): void;
     init(): void;
     dispose(): void;
 }
 
-export { ASTFactory, ASTKind, ASTMatch, ASTNode, ASTNodeFlags, type ASTNodeJSON, type ASTNodeRegistry, ASTRegisters, ArrayType, BaseExpression, BaseType, BaseVariableField, BooleanType, type CreateASTParams, CustomType, type CustomTypeJSON, DataNode, EnumerateExpression, type EnumerateExpressionJSON, type GetKindJSON, type GetKindJSONOrKind, type GlobalEventActionType, type IVariableTable, IntegerType, KeyPathExpression, type KeyPathExpressionJSON$1 as KeyPathExpressionJSON, KeyPathExpressionV2, ListNode, type ListNodeJSON, MapNode, type MapNodeJSON, MapType, NumberType, type ObjectJSON, type ObjectPropertiesChangeAction, ObjectType, Property, type PropertyJSON, Scope, ScopeChain, ScopeOutputData, ScopeProvider, StringType, type UnionJSON, VariableContainerModule, VariableDeclaration, type VariableDeclarationJSON, VariableDeclarationList, type VariableDeclarationListChangeAction, type VariableDeclarationListJSON, VariableEngine, VariableEngineProvider, VariableFieldKeyRenameService, WrapArrayExpression, type WrapArrayExpressionJSON, injectToAST, isMatchAST, postConstructAST, useAvailableVariables, useCurrentScope, useScopeAvailable, useScopeContext };
+export { ASTFactory, ASTKind, ASTMatch, ASTNode, ASTNodeFlags, type ASTNodeJSON, type ASTNodeRegistry, ASTRegisters, ArrayType, BaseExpression, BaseType, BaseVariableField, BooleanType, type CreateASTParams, CustomType, type CustomTypeJSON, DataNode, EnumerateExpression, type EnumerateExpressionJSON, type GetKindJSON, type GetKindJSONOrKind, type GlobalEventActionType, type IVariableTable, IntegerType, KeyPathExpression, type KeyPathExpressionJSON$1 as KeyPathExpressionJSON, LegacyKeyPathExpression, ListNode, type ListNodeJSON, MapNode, type MapNodeJSON, MapType, NumberType, type ObjectJSON, type ObjectPropertiesChangeAction, ObjectType, Property, type PropertyJSON, Scope, ScopeChain, ScopeOutputData, ScopeProvider, StringType, type UnionJSON, VariableContainerModule, VariableDeclaration, type VariableDeclarationJSON, VariableDeclarationList, type VariableDeclarationListChangeAction, type VariableDeclarationListJSON, VariableEngine, VariableEngineProvider, VariableFieldKeyRenameService, WrapArrayExpression, type WrapArrayExpressionJSON, injectToAST, isMatchAST, postConstructAST, useAvailableVariables, useCurrentScope, useOutputVariables, useScopeAvailable };