next-flow-interface 0.27.7 → 0.27.11

package/index.d.ts

@@ -42,14 +42,12 @@ import { Material } from '@babylonjs/core';
 import { Mesh } from '@babylonjs/core';
 import { MouseEvent as MouseEvent_2 } from 'react';
 import { MouseEventHandler } from 'react';
-import { MultipartUploadResult } from 'ali-oss';
 import { NavigateOptions } from 'next/dist/shared/lib/app-router-context.shared-runtime';
 import { Node as Node_2 } from '@babylonjs/core';
 import { NodeMaterial } from '@babylonjs/core';
 import { NodeMaterialBlock } from '@babylonjs/core';
 import { NodeMaterialBlockConnectionPointTypes } from '@babylonjs/core';
 import { Observable } from '@babylonjs/core/Misc/observable';
-import OSS from 'ali-oss';
 import { PBRMaterial } from '@babylonjs/core';
 import { PointerEventHandler } from 'react';
 import { PrefetchOptions } from 'next/dist/shared/lib/app-router-context.shared-runtime';
@@ -66,6 +64,8 @@ import { RecursiveObject } from 'rhine-var';
 import { RedirectType } from 'next/navigation';
 import { Ref } from 'react';
 import { RefAttributes } from 'react';
+import type { Resource } from 'rhine-base/network';
+import type { ResourceFileInfo } from 'rhine-base/network';
 import { RhineVarArray } from 'rhine-var';
 import { RhineVarMap } from 'rhine-var';
 import { Root } from 'react-dom/client';
@@ -230,11 +230,10 @@ declare function approximatelyEqual(n1: number, n2: number, bias?: number): bool
 
 
 
-
 /**
  * @public
  */
-export declare type Attribute<T extends object = any> = NodeAttribute<T> | StepAttribute<T> | GlobalAttribute<T>;
+export declare type Attribute<T extends object = object> = NodeAttribute<T> | StepAttribute<T> | GlobalAttribute<T>;
 
 /**
  * @public
@@ -252,15 +251,15 @@ export declare class AttributeService {
     stepAttributes: StepAttribute[];
     globalAttributes: GlobalAttribute[];
     /** 注册属性 */
-    register<T extends object = any>(attribute: Attribute<T>): void;
+    register<T extends object = object>(attribute: Attribute<T>): void;
     /** 通过路径精确匹配获取属性 */
-    get<T extends object = any>(type: AttributeType, path: RvPath | string): Attribute<T> | undefined;
+    get<T extends object = object>(type: AttributeType, path: RvPath | string): Attribute<T> | undefined;
     /** 通过路径获取 NodeAttribute */
-    getNodeAttribute<T extends object = any>(path: RvPath | string): NodeAttribute<T> | undefined;
+    getNodeAttribute<T extends object = object>(path: RvPath | string): NodeAttribute<T> | undefined;
     /** 通过路径获取 StepAttribute */
-    getStepAttribute<T extends object = any>(path: RvPath | string): StepAttribute<T> | undefined;
+    getStepAttribute<T extends object = object>(path: RvPath | string): StepAttribute<T> | undefined;
     /** 通过路径获取 GlobalAttribute */
-    getGlobalAttribute<T extends object = any>(path: RvPath | string): GlobalAttribute<T> | undefined;
+    getGlobalAttribute<T extends object = object>(path: RvPath | string): GlobalAttribute<T> | undefined;
     /** 根据类型获取属性列表，不传入类型的时候返回所有 */
     getList(type?: AttributeType): Attribute[];
     isPathConflict(type: AttributeType, path: RvPath): boolean;
@@ -424,7 +423,7 @@ export declare class AwarenessService {
 /**
  * @public
  */
-export declare abstract class BaseAttribute<T extends object = any> {
+export declare abstract class BaseAttribute<T extends object = object> {
     abstract type: AttributeType;
     abstract path: RvPath;
     defaultValue: T;
@@ -826,6 +825,7 @@ export declare const ClipboardUtils: {
 declare function computeSHA256(buffer: BufferSource): Promise<string>;
 
 
+
 /**
  * @public
  */
@@ -2232,7 +2232,7 @@ declare function isAttach(mime?: string): boolean;
 
 declare function isBabylon(mime?: string): boolean;
 
-declare function isChangeEventType(type: EventType | string): type is EventType.ADD | EventType.UPDATE | EventType.DELETE;
+declare function isChangeEventType(type: EventType | string): boolean;
 
 /**
  * @public
@@ -2492,17 +2492,15 @@ export declare class LocalDataService {
     /**
      * 加载一个文件到本地
      *
-     * 根据提供的 URL 类型（blob、http/https、oss）下载文件到本地。
+     * 通过 fileId 从后端获取签名下载 URL，然后下载文件到本地。
      * 支持下载进度跟踪，下载完成后会自动处理文件内容（JSON、文本等）。
-     * 如果文件已存在且已加载完成，则直接返回已存在的本地数据。
      *
-     * @param fid - 文件在 RhineVar 中的文件ID
-     * @param url - 文件的直接下载链接、Blob URL 或 OSS 链接
+     * @param fileId - 后端文件 ID
      * @param mime - 文件 MIME 类型，默认为 UNKNOWN
      * @returns Promise<LocalData> - 返回本地数据对象的 Promise
      * @public
      */
-    load(fid: string, url: string, mime?: string): Promise<LocalData>;
+    load(fileId: string, mime?: string): Promise<LocalData>;
     /**
      * 通过 File 对象加载文件到本地
      *
@@ -2539,35 +2537,6 @@ export declare class LocalDataService {
      */
     remove(fid: string): boolean;
     /**
-     * 暂停文件下载
-     *
-     * @param fid - 文件ID
-     * @returns 是否成功暂停
-     * @public
-     * @throws 该方法尚未实现
-     */
-    pause(fid: string): boolean;
-    /**
-     * 恢复文件下载
-     *
-     * @param fid - 文件ID
-     * @returns 是否成功恢复
-     * @public
-     * @throws 该方法尚未实现
-     */
-    resume(fid: string): boolean;
-    /**
-     * 取消文件下载
-     *
-     * @param fid - 文件ID
-     * @returns 是否成功取消
-     * @public
-     * @throws 该方法尚未实现
-     */
-    cancel(fid: string): boolean;
-    /**
-     * 获取本地文件的 Blob URL
-     *
      * 将本地数据转换为浏览器可用的 Blob URL，用于在浏览器中显示或下载文件。
      * 如果数据类型是 BLOB，则创建 Blob URL；如果是 OBJECT，则创建 MediaSource URL。
      *
@@ -2644,9 +2613,33 @@ export declare class LocalDataService {
      * @public
      */
     unsubscribeSingle(fid: string, subscriber: LocalDataServiceSubscriber): void;
-    publish(fid: string, type: LocalDataServiceEventType, localData: LocalData): void;
+    /**
+     * 文件加载完成后执行回调
+     *
+     * 如果文件已加载完成，立即执行回调；否则订阅 LOADED 事件，触发后自动取消订阅。
+     *
+     * @param fid - 文件 ID
+     * @param subscriber - 加载完成后的回调函数
+     * @public
+     */
     afterLoaded(fid: string, subscriber: (localData: LocalData) => void): void;
+    /**
+     * 等待文件加载完成
+     *
+     * 返回一个 Promise，在文件加载完成时 resolve。
+     *
+     * @param fid - 文件 ID
+     * @returns 加载完成的本地数据对象
+     * @public
+     */
     waitLoaded(fid: string): Promise<LocalData>;
+    /**
+     * 检查文件是否已加载完成
+     *
+     * @param fid - 文件 ID
+     * @returns true 已加载，false 未加载，undefined 文件不存在
+     * @public
+     */
     isLoaded(fid: string): boolean | undefined;
 }
 
@@ -3259,8 +3252,6 @@ export declare const NumberUtils: {
     isValidNumber: typeof isValidNumber;
 };
 
-
-
 /**
  * @public
  */
@@ -3285,245 +3276,78 @@ export declare enum OssUploadInstanceStatus {
 }
 
 /**
- * OSS 上传服务
+ * 上传服务
  *
- * @remarks
- * 该服务负责管理所有 OSS 上传任务队列，提供文件上传、取消、状态监听等功能。
- * 所有上传任务都会创建对应的 RvFile 记录，并在协同数据中标记 `uploading: true`。
- * 上传完成后会自动更新 RvFile 的 URL 并移除上传标记。
- *
- * @example
- * ```typescript
- * // 上传文件
- * const fid = await OssUploadService.instance.upload(file)
- *
- * // 监听上传进度
- * OssUploadService.instance.subscribe((type, instance) => {
- *   if (type === OssUploadServiceEventType.PROGRESS) {
- *     console.log(`上传进度: ${instance.progress}%`)
- *   }
- * })
- * ```
+ * 委托 rhine-base UploadService 完成文件上传，
+ * 上传完成后将 fileId / resourceId 写入协同数据。
  *
  * @public
  */
 export declare class OssUploadService {
-    /**
-     * 获取 OssUploadService 单例实例
-     *
-     * @returns OssUploadService 单例实例
-     *
-     * @public
-     */
+    private static _instance;
     static get instance(): OssUploadService;
-    /**
-     * 当前所有上传实例的集合
-     *
-     * @remarks
-     * 使用 Map 结构存储，key 为文件 ID (fid)，value 为上传实例对象。
-     * 上传完成后，实例会从集合中自动移除。
-     *
-     * @public
-     */
+    private constructor();
+    private initialize;
+    /** 正在上传的实例 Map（fid -> OssUploadInstance） */
     instances: Map<string, OssUploadInstance>;
     /**
-     * 根据文件 ID 获取上传实例
+     * 根据 fid 获取上传实例
      *
      * @param fid - 文件 ID
-     * @returns 上传实例对象，如果不存在则返回 undefined
-     *
-     * @public
+     * @returns 上传实例，不存在则返回 undefined
      */
     get(fid: string): OssUploadInstance | undefined;
     /**
-     * 检查是否存在指定 ID 的上传任务
+     * 检查是否存在指定 fid 的上传实例
      *
      * @param fid - 文件 ID
-     * @returns 如果存在返回 true，否则返回 false
-     *
-     * @public
      */
     has(fid: string): boolean;
     /**
-     * 检查指定的 File 对象是否已经在上传队列中
-     *
-     * @param file - 要检查的 File 对象
-     * @returns 如果该文件已在上传队列中返回 true，否则返回 false
+     * 检查指定 File 对象是否正在上传中
      *
-     * @remarks
-     * 该方法通过遍历所有上传实例来比较 File 对象引用
-     *
-     * @public
+     * @param file - 浏览器 File 对象
      */
     hasFile(file: File): boolean;
     /**
-     * 上传完成后从队列中移除的延迟时间（毫秒）
-     *
-     * @defaultValue 100
-     *
-     * @public
-     */
-    REMOVE_INTERVAL_AFTER_COMPLETED: number;
-    /**
-     * 上传文件到 OSS
-     *
-     * @param file - 要上传的文件对象
-     * @param fid - 文件 ID，如果不提供则自动生成
-     * @param mime - 文件 MIME 类型，如果不提供则自动检测
-     * @param hash - 文件哈希值（可选）
-     * @returns Promise，上传任务启动后返回
-     *
-     * @remarks
-     * 该方法会执行以下操作：
-     * 1. 创建 RvFile 记录，标记 `uploading: true`
-     * 2. 创建上传实例并加入队列
-     * 3. 开始上传并触发相关事件（START、PROGRESS、UPLOADED/FAILED）
-     * 4. 上传成功后更新 RvFile 的 URL 并移除 uploading 标记
-     * 5. 上传失败后自动删除 RvFile 记录
-     * 6. 将文件添加到本地数据服务
-     *
-     * @throws 如果创建 RvFile 失败，抛出 Error
-     *
-     * @example
-     * ```typescript
-     * // 基本用法
-     * await OssUploadService.instance.upload(file)
-     *
-     * // 指定文件 ID
-     * await OssUploadService.instance.upload(file, 'custom-fid')
-     *
-     * // 指定 MIME 类型和哈希值
-     * await OssUploadService.instance.upload(file, 'custom-fid', 'image/png', 'sha256-hash')
-     * ```
-     *
-     * @public
-     */
-    upload(file: File, fid?: string, mime?: string, hash?: string): Promise<void>;
-    /**
-     * 暂停指定的上传任务
+     * 上传文件
      *
-     * @param fid - 文件 ID
-     * @returns 暂停操作是否成功
-     *
-     * @remarks
-     * 该方法尚未实现，调用会抛出异常
-     *
-     * @throws 方法未实现错误
-     *
-     * @public
+     * 委托 rhine-base UploadService 完成完整上传流程。
+     * 上传完成后自动将 fileId 和 resourceId 写入协同数据。
      */
-    pause(fid: string): boolean;
+    upload(file: File, fid?: string, mime?: string): Promise<void>;
     /**
-     * 恢复指定的上传任务
+     * 取消指定文件的上传
      *
      * @param fid - 文件 ID
-     * @returns 恢复操作是否成功
-     *
-     * @remarks
-     * 该方法尚未实现，调用会抛出异常
-     *
-     * @throws 方法未实现错误
-     *
-     * @public
-     */
-    resume(fid: string): boolean;
-    /**
-     * 取消指定的上传任务
-     *
-     * @param fid - 文件 ID
-     * @returns 取消操作是否成功
-     *
-     * @remarks
-     * 取消上传后会发布 CANCELED 事件，无论取消是否成功都会发布该事件。
-     * 取消后上传实例仍会保留在队列中，直到超时或手动移除。
-     *
-     * @example
-     * ```typescript
-     * const fid = 'file-id'
-     * if (OssUploadService.instance.cancel(fid)) {
-     *   console.log('上传已取消')
-     * }
-     * ```
-     *
-     * @public
+     * @returns 是否成功取消
      */
     cancel(fid: string): boolean;
+    private subscribers;
+    private singleSubscribers;
     /**
-     * 订阅所有文件的上传事件
+     * 订阅所有上传事件
      *
-     * @param subscriber - 订阅回调函数，当任何文件的上传状态改变时会被调用
+     * @param subscriber - 事件回调函数
      * @returns 取消订阅的函数
-     *
-     * @remarks
-     * 该方法会监听所有文件的上传事件，包括：
-     * - START: 上传开始
-     * - PROGRESS: 上传进度更新
-     * - UPLOADED: 上传成功
-     * - FAILED: 上传失败
-     * - CANCELED: 上传取消
-     *
-     * @example
-     * ```typescript
-     * const unsubscribe = OssUploadService.instance.subscribe((type, instance) => {
-     *   console.log(`文件 ${instance.fid} 状态: ${type}, 进度: ${instance.progress}%`)
-     * })
-     *
-     * // 取消订阅
-     * unsubscribe()
-     * ```
-     *
-     * @public
      */
     subscribe(subscriber: OssUploadServiceSubscriber): () => void;
     /**
-     * 取消订阅所有文件的上传事件
+     * 取消订阅所有上传事件
      *
-     * @param subscriber - 要取消的订阅回调函数
-     *
-     * @remarks
-     * 从订阅列表中移除指定的订阅者
-     *
-     * @public
+     * @param subscriber - 要取消的回调函数
      */
     unsubscribe(subscriber: OssUploadServiceSubscriber): void;
     /**
-     * 订阅指定文件的上传事件
+     * 订阅单个文件的上传事件
      *
-     * @param fid - 要订阅的文件 ID
-     * @param subscriber - 订阅回调函数，当该文件的上传状态改变时会被调用
+     * @param fid - 文件 ID
+     * @param subscriber - 事件回调函数
      * @returns 取消订阅的函数
-     *
-     * @remarks
-     * 该方法只监听指定文件的上传事件。相比 {@link subscribe}，这个方法更适合只关注单个文件的场景。
-     * 事件类型包括：START、PROGRESS、UPLOADED、FAILED、CANCELED
-     *
-     * @example
-     * ```typescript
-     * const unsubscribe = OssUploadService.instance.subscribeSingle('file-id', (type, instance) => {
-     *   if (type === OssUploadServiceEventType.UPLOADED) {
-     *     console.log('文件上传完成')
-     *   }
-     * })
-     *
-     * // 取消订阅
-     * unsubscribe()
-     * ```
-     *
-     * @public
      */
     subscribeSingle(fid: string, subscriber: OssUploadServiceSubscriber): () => void;
-    /**
-     * 取消订阅指定文件的上传事件
-     *
-     * @param fid - 文件 ID
-     * @param subscriber - 要取消的订阅回调函数
-     *
-     * @remarks
-     * 从指定文件的订阅列表中移除订阅者
-     *
-     * @public
-     */
     unsubscribeSingle(fid: string, subscriber: OssUploadServiceSubscriber): void;
+    publish(fid: string, type: OssUploadServiceEventType, uploadInstance: OssUploadInstance): void;
 }
 
 /**
@@ -3715,38 +3539,479 @@ export declare interface PluginInformation {
 
 
 /**
+ * 插件系统核心服务
+ *
+ * 本服务是整个插件系统的核心入口，负责插件的完整生命周期管理，包括添加、安装、启用、禁用、卸载等操作。
+ * 插件系统采用插件化架构设计，所有侧边栏、弹窗、功能按钮等都以插件形式存在，可按需装配。
+ *
+ * ## 插件系统架构概览
+ *
+ * 插件系统由以下核心模块组成:
+ *
+ * 1. PluginService (本文件) - 插件生命周期管理核心
+ * 2. PluginConnector - 插件与主项目的桥接器，向window注入全局API
+ * 3. PluginApiProvider - 向插件暴露的主项目服务和组件集合
+ * 4. PluginContainerService - 插件UI容器管理，处理插件的DOM渲染
+ * 5. RvPluginService - 插件协同数据管理，存储插件配置到RhineVar
+ *
+ * ## 插件分类
+ *
+ * 插件按类型(PluginType)分为以下几类:
+ *
+ * - BUTTON: 按钮插件，点击触发动作，无展开内容
+ * - SWITCH: 开关插件，点击切换状态
+ * - DRAWER: 抽屉插件，点击展开侧边栏面板
+ * - DIALOG: 对话框插件，点击弹出模态框
+ * - CONTENT: 内容插件，固定显示在内容区域
+ * - WINDOW: 窗口插件，浮动显示在画布上层
+ * - SERVICE: 服务插件，无UI，仅提供后台服务
+ *
+ * ## 插件来源
+ *
+ * 插件按来源分为两类:
+ *
+ * - 内置插件(BuiltIn): URL以`nfp://`开头，代码打包在主项目中，通过builtInPluginFactory创建实例
+ * - 外部插件(External): URL为http(s)地址，运行时动态加载JS/CSS文件
+ *
+ * ## 插件生命周期
+ *
+ * 插件的完整生命周期如下:
+ *
+ * ```
+ * add -> install -> enable -> open/close -> disable -> uninstall
+ * ```
+ *
+ * 各阶段说明:
+ *
+ * - add: 添加插件配置，创建PluginState，加载外部资源(JS/CSS/国际化文件)
+ * - install: 执行插件的onInstall回调，标记installed=true
+ * - enable: 将插件添加到UI容器，执行onEnable回调，标记enabled=true
+ * - open: 打开可展开的插件(DRAWER/DIALOG/SWITCH)
+ * - close: 关闭已打开的插件
+ * - disable: 从UI容器移除，执行onDisable回调，标记enabled=false
+ * - uninstall: 执行onUninstall回调，移除DOM元素，从plugins Map中删除
+ *
+ * ## 启用级别(EnableLevel)
+ *
+ * 协同数据中定义了插件的启用级别，决定插件在页面加载时的初始状态:
+ *
+ * - NONE: 不加载
+ * - INSTALL: 仅安装，不启用
+ * - ENABLE: 安装并启用，但不打开
+ * - OPEN: 安装、启用并打开
+ *
+ * ## 调试模式
+ *
+ * 支持插件热更新调试:
+ *
+ * - 通过URL参数`?plugin=id:urlPort:hmrPort`快速启动调试
+ * - 通过协同数据`plugin.debug`配置调试插件
+ * - WebSocket监听HMR消息，自动重载插件
+ *
+ * ## 初始化流程
+ *
+ * 1. 等待SyncInitialized状态
+ * 2. 解析URL中的调试插件参数
+ * 3. 并行处理所有配置中的插件(根据EnableLevel执行add/install/enable/open)
+ * 4. 并行启动所有调试插件
+ * 5. 设置PluginEnabled状态
+ * 6. 订阅调试插件配置变化
+ * 7. 检查PreLoaded和PreRendered钩子
+ *
+ * ## 事件订阅
+ *
+ * 通过subscribe/unsubscribe方法订阅插件事件:
+ *
+ * - ADD: 插件添加完成
+ * - INSTALL: 插件安装完成
+ * - ENABLE: 插件启用完成
+ * - DISABLE: 插件禁用完成
+ * - UNINSTALL: 插件卸载完成
+ *
+ * ## 相关文件索引
+ *
+ * 核心服务:
+ * - ./plugin-connector.ts - 插件桥接器，向window注入全局对象供外部插件访问
+ * - ./plugin-api-provider.ts - API提供器，汇总所有向插件暴露的服务、组件、工具函数
+ * - ./plugin-list.tsx - 插件列表，定义所有可用插件的配置信息和内置插件工厂
+ *
+ * 类型定义:
+ * - ./dto/plugin-config.type.ts - 插件配置类型，定义插件的基本信息结构
+ * - ./dto/plugin-state.interface.ts - 插件状态接口，记录插件运行时状态
+ * - ./dto/plugin-event-type.enum.ts - 插件事件类型枚举
+ * - ./dto/plugin-service-subscriber.type.ts - 事件订阅者类型定义
+ *
+ * 插件实例接口:
+ * - ./instance/base-plugin.ts - 插件基础接口，所有插件类型的公共属性
+ * - ./instance/icon-plugin.ts - 图标插件接口，带侧边栏按钮的插件基类
+ * - ./instance/drawer-plugin.ts - 抽屉插件接口，可展开侧边栏面板
+ * - ./instance/dialog-plugin.ts - 对话框插件接口，点击弹出模态框
+ * - ./instance/view-plugin.ts - 视图插件接口，CONTENT和WINDOW类型的基类
+ * - ./instance/dto/plugin-type.enum.ts - 插件类型枚举
+ * - ./instance/dto/icon-plugin-position.enum.ts - 图标插件位置枚举
+ * - ./instance/dto/icon-view-props.interface.ts - 图标视图Props接口
+ * - ./instance/dto/plugin-view-props.interface.ts - 插件视图Props接口
+ *
+ * UI容器管理:
+ * - ./view/plugin-container/plugin-container-service.ts - 容器服务，管理插件的DOM渲染和布局
+ * - ./view/plugin-container/dynamic/icon-button-manager.ts - 图标按钮管理器，创建和管理侧边栏按钮
+ * - ./view/plugin-container/dynamic/plugin-ordering-manager.ts - 排序管理器，处理按钮排序和分割线
+ * - ./view/plugin-container/dynamic/hover-manager.ts - 悬停管理器，处理按钮容器的悬停效果
+ *
+ * 协同数据:
+ * - ../sync/plugin/rv-plugin-service.ts - 插件协同数据服务，管理plugin配置的CRUD
+ * - ../sync/plugin/default-plugin-config.ts - 默认插件配置，定义初始插件列表和启用级别
+ * - ../sync/interface/plugin/rv-plugin.ts - 插件协同数据结构
+ * - ../sync/interface/plugin/rv-plugin-config.interface.ts - 插件配置接口，含EnableLevel和VersionPoint
+ * - ../sync/interface/plugin/rv-plugin-debug.ts - 调试插件配置接口
+ *
+ * 内置插件示例:
+ * - ../nfp/drawer/debug/debug-drawer-plugin.tsx - 调试抽屉插件，DrawerPlugin实现示例
+ * - ../nfp/button/home-button/home-button-plugin.tsx - 主页按钮插件，IconPlugin(BUTTON)实现示例
+ * - ../nfp/switch/select-switch/select-switch-plugin.tsx - 选择开关插件，IconPlugin(SWITCH)实现示例
+ * - ../nfp/dialog/plugin-manage-dialog/plugin-manage-dialog-plugin.tsx - 插件管理对话框，DialogPlugin实现示例
+ * - ../nfp/content/message-display/message-display-plugin.tsx - 消息显示插件，ViewPlugin(CONTENT)实现示例
+ * - ../nfp/window/context-menu-display/context-menu-display-plugin.tsx - 右键菜单插件，ViewPlugin(WINDOW)实现示例
+ *
+ * 工具函数:
+ * - ../../utils/render-mix-view.tsx - 混合视图渲染，支持字符串HTML或React组件
+ * - ../../types/view/mix-view.ts - MixView类型定义
+ *
  * @public
  */
 export declare class PluginService {
+    /**
+     * 获取 PluginService 单例实例
+     *
+     * 首次访问时会自动创建实例并触发初始化流程。
+     *
+     * @returns PluginService 单例实例
+     *
+     * @example
+     * ```typescript
+     * const pluginService = PluginService.instance
+     * await pluginService.add(config)
+     * ```
+     */
     static get instance(): PluginService;
+    /**
+     * 私有构造函数，确保单例模式
+     *
+     * 构造时自动触发异步初始化流程。
+     */
     private constructor();
+    /**
+     * 已注册插件的状态映射表
+     *
+     * 以插件 ID 为键，存储每个插件的运行时状态信息。
+     * 包含插件实例、DOM 元素引用、安装/启用状态等。
+     *
+     * @see PluginState
+     */
     plugins: Map<string, PluginState>;
+    /**
+     * 详细日志模式开关
+     *
+     * 开启后会在控制台输出更多插件操作的调试信息。
+     * 默认关闭，仅在开发调试时启用。
+     */
     DETAILED_LOG_MODE: boolean;
+    /**
+     * 普通插件安装超时时间(毫秒)
+     *
+     * 等待插件安装完成的最大时间，超时后会抛出错误。
+     * @default 3000
+     */
     INSTALL_TIMEOUT: number;
+    /**
+     * 调试插件安装超时时间(毫秒)
+     *
+     * 等待调试插件安装完成的最大时间，超时后会抛出错误。
+     * @default 3000
+     */
     DEBUG_INSTALL_TIMEOUT: number;
+    /**
+     * 创建预加载钩子
+     *
+     * 插件可在启用时调用此方法注册预加载任务。
+     * 注册后需调用 {@link completePreLoadedHook} 标记完成。
+     *
+     * @param id - 插件 ID
+     *
+     * @example
+     * ```typescript
+     * // 在插件 onEnable 中
+     * PluginService.instance.createPreLoadedHook(this.id)
+     * // 异步任务完成后
+     * PluginService.instance.completePreLoadedHook(this.id)
+     * ```
+     */
     createPreLoadedHook(id: string): void;
+    /**
+     * 完成预加载钩子
+     *
+     * 标记指定插件的预加载任务已完成。
+     * 所有预加载任务完成后会触发 PluginPreLoaded 状态。
+     *
+     * @param id - 插件 ID
+     */
     completePreLoadedHook(id: string): void;
+    /**
+     * 创建预渲染钩子
+     *
+     * 插件可在启用时调用此方法注册预渲染任务。
+     * 注册后需调用 {@link completePreRenderedHook} 标记完成。
+     *
+     * @param id - 插件 ID
+     *
+     * @example
+     * ```typescript
+     * // 在插件 onEnable 中
+     * PluginService.instance.createPreRenderedHook(this.id)
+     * // 渲染准备完成后
+     * PluginService.instance.completePreRenderedHook(this.id)
+     * ```
+     */
     createPreRenderedHook(id: string): void;
+    /**
+     * 完成预渲染钩子
+     *
+     * 标记指定插件的预渲染任务已完成。
+     * 所有预渲染任务完成后会触发 PluginPreRendered 状态。
+     *
+     * @param id - 插件 ID
+     */
     completePreRenderedHook(id: string): void;
-    protected checkPreLoaded(): void;
-    protected checkPreRendered(): void;
+    /**
+     * 订阅插件事件
+     *
+     * 注册一个回调函数，在插件生命周期事件发生时被调用。
+     *
+     * @param subscriber - 事件订阅回调函数
+     * @returns 取消订阅的函数
+     *
+     * @example
+     * ```typescript
+     * const unsubscribe = PluginService.instance.subscribe((id, type) => {
+     *   console.log(`Plugin ${id} event: ${type}`)
+     * })
+     * // 取消订阅
+     * unsubscribe()
+     * ```
+     */
     subscribe(subscriber: PluginServiceSubscriber): () => void;
+    /**
+     * 取消订阅插件事件
+     *
+     * @param subscriber - 要取消的订阅回调函数
+     */
     unsubscribe(subscriber: PluginServiceSubscriber): void;
+    /**
+     * 获取插件状态
+     *
+     * 根据插件 ID 获取其运行时状态信息。
+     *
+     * @param id - 插件 ID
+     * @returns 插件状态对象，若不存在则返回 undefined
+     *
+     * @example
+     * ```typescript
+     * const state = PluginService.instance.get('my-plugin')
+     * if (state?.enabled) {
+     *   console.log('Plugin is enabled')
+     * }
+     * ```
+     */
     get(id: string): PluginState | undefined;
+    /**
+     * 添加插件
+     *
+     * 根据插件配置添加插件到系统中。
+     * 自动识别内置插件(nfp://)和外部插件(http)并分别处理。
+     *
+     * 对于外部插件:
+     * - 创建 script 和 link 元素加载 JS/CSS
+     * - 加载国际化资源文件
+     * - 将元素添加到 document.body
+     *
+     * 对于内置插件:
+     * - 从 builtInPluginFactory 创建实例
+     * - 自动触发安装流程
+     *
+     * @param config - 插件配置对象
+     * @returns 是否添加成功
+     *
+     * @example
+     * ```typescript
+     * const success = await PluginService.instance.add({
+     *   id: 'my-plugin',
+     *   url: 'https://cdn.example.com/plugins/my-plugin',
+     *   entry: 'index.js',
+     *   css: 'index.css',
+     *   information: { name: 'My Plugin' }
+     * })
+     * ```
+     */
     add(config: PluginConfig): Promise<boolean>;
+    /**
+     * 启动插件调试模式
+     *
+     * 加载调试插件并建立 WebSocket 连接监听 HMR 消息。
+     * 当收到编译完成消息时自动重新加载插件实现热更新。
+     *
+     * @param debug - 调试插件配置(RhineVar 存储)
+     *
+     * @example
+     * ```typescript
+     * await PluginService.instance.debug(rvPluginDebug)
+     * ```
+     */
     debug(debug: StoredRhineVar<RvPluginDebug>): Promise<void>;
+    /**
+     * 停止插件调试
+     *
+     * 关闭 HMR WebSocket 连接并卸载调试插件。
+     *
+     * @param id - 插件 ID
+     */
     stopDebug(id: string): Promise<void>;
+    /**
+     * 加载插件国际化消息
+     *
+     * 从插件的 messages 属性中加载当前语言的翻译资源。
+     * 内置插件可通过此方式提供多语言支持。
+     *
+     * @param plugin - 插件实例
+     */
     loadPluginMessages(plugin: BasePlugin): Promise<void>;
+    /**
+     * 安装插件
+     *
+     * 执行插件的安装流程:
+     * 1. 将插件实例存入 PluginState
+     * 2. 加载插件国际化消息
+     * 3. 调用插件的 onInstall 生命周期钩子
+     * 4. 标记 installed = true
+     * 5. 发布 INSTALL 事件
+     *
+     * 注意: 外部插件的 install 由插件 JS 加载完成后自动调用 PluginConnector.install 触发。
+     *
+     * @param plugin - 插件实例
+     */
     install(plugin: BasePlugin): Promise<void>;
+    /**
+     * 启用插件
+     *
+     * 执行插件的启用流程:
+     * 1. 将插件添加到 UI 容器(创建按钮或渲染视图)
+     * 2. 调用插件的 onEnable 生命周期钩子
+     * 3. 标记 enabled = true
+     * 4. 发布 ENABLE 事件
+     *
+     * @param id - 插件 ID
+     */
     enable(id: string): Promise<void>;
+    /**
+     * 打开插件
+     *
+     * 打开可展开的插件(DRAWER/DIALOG/SWITCH 类型)。
+     * 对于 DRAWER 类型会展开侧边栏面板，对于 DIALOG 类型会弹出对话框。
+     *
+     * @param id - 插件 ID
+     * @throws 若插件未安装则抛出错误
+     */
     open(id: string): Promise<void>;
+    /**
+     * 关闭插件
+     *
+     * 关闭已打开的插件(DRAWER/DIALOG/SWITCH 类型)。
+     *
+     * @param id - 插件 ID
+     * @throws 若插件未安装则抛出错误
+     */
     close(id: string): Promise<void>;
+    /**
+     * 禁用插件
+     *
+     * 执行插件的禁用流程:
+     * 1. 从 UI 容器移除插件
+     * 2. 调用插件的 onDisable 生命周期钩子
+     * 3. 标记 enabled = false
+     * 4. 发布 DISABLE 事件
+     *
+     * @param id - 插件 ID
+     */
     disable(id: string): Promise<void>;
+    /**
+     * 卸载插件
+     *
+     * 执行插件的完整卸载流程:
+     * 1. 若已启用则先禁用
+     * 2. 调用插件的 onUninstall 生命周期钩子
+     * 3. 标记 installed = false
+     * 4. 移除 script 和 style DOM 元素
+     * 5. 从 plugins Map 中删除
+     * 6. 发布 UNINSTALL 事件
+     *
+     * @param id - 插件 ID
+     */
     uninstall(id: string): Promise<void>;
+    /**
+     * 等待插件安装完成
+     *
+     * 返回一个 Promise，在指定插件安装完成时 resolve。
+     * 若插件已安装则立即 resolve。
+     *
+     * @param id - 插件 ID
+     * @param timeoutMs - 超时时间(毫秒)，超时后 reject
+     * @returns Promise，安装完成时 resolve
+     *
+     * @example
+     * ```typescript
+     * await PluginService.instance.waitInstall('my-plugin', 5000)
+     * console.log('Plugin installed')
+     * ```
+     */
     waitInstall(id: string, timeoutMs?: number): Promise<void>;
+    /**
+     * 等待插件启用完成
+     *
+     * 返回一个 Promise，在指定插件启用完成时 resolve。
+     * 若插件已启用则立即 resolve。
+     *
+     * @param id - 插件 ID
+     * @param timeoutMs - 超时时间(毫秒)，超时后 reject
+     * @returns Promise，启用完成时 resolve
+     */
     waitEnable(id: string, timeoutMs?: number): Promise<void>;
+    /**
+     * 判断是否为可打开的插件类型
+     *
+     * 可打开的插件类型包括: DRAWER, DIALOG, SWITCH
+     *
+     * @param type - 插件类型
+     * @returns 是否可打开
+     */
     isOpenablePlugin(type: PluginType): boolean;
+    /**
+     * 判断是否为侧边栏插件类型
+     *
+     * 侧边栏插件会在左右两侧显示图标按钮。
+     * 包括: DRAWER, DIALOG, BUTTON, SWITCH
+     *
+     * @param type - 插件类型
+     * @returns 是否为侧边栏插件
+     */
     isSideBarPlugin(type: PluginType): boolean;
+    /**
+     * 判断是否为视图插件类型
+     *
+     * 视图插件直接渲染在内容区域或浮动窗口中。
+     * 包括: WINDOW, CONTENT
+     *
+     * @param type - 插件类型
+     * @returns 是否为视图插件
+     */
     isViewPlugin(type: PluginType): boolean;
 }
 
@@ -3857,7 +4122,10 @@ export declare interface ResourcePreviewProps extends DivProps {
 }
 
 /**
- * ResourceService
+ * 资源管理服务
+ *
+ * 负责资源的上传、批量上传、重复检测、纹理预览图生成等功能。
+ * 上传操作委托 OssUploadService 完成，最终由 rhine-base UploadService 执行。
  *
  * @public
  */
@@ -3867,6 +4135,7 @@ export declare class ResourceService {
      */
     static get instance(): ResourceService;
     private constructor();
+    /** 资源拖拽状态（Valtio 响应式） */
     dragState: {
         fid: string;
         data: null;
@@ -3875,15 +4144,52 @@ export declare class ResourceService {
         offsetX: number;
         offsetY: number;
     };
+    /**
+     * 上传单个文件为资源
+     *
+     * @param file - 浏览器 File 对象
+     * @param fid - 可选的文件 ID，不传则由上传服务自动生成
+     * @param check - 是否标记历史记录
+     * @returns 文件 ID
+     */
     upload(file: File, fid?: string, check?: boolean): Promise<string>;
+    /**
+     * 批量上传文件为资源
+     *
+     * 自动检测重复文件并提示用户。fidList 长度需与 fileList 一致或为空。
+     *
+     * @param fileList - 文件列表，支持 FileList、File[]、单个 File 或 null
+     * @param check - 是否标记历史记录
+     * @param fidList - 可选的文件 ID 列表，与 fileList 一一对应
+     */
     uploadMulti(fileList: FileList | File[] | File | null | undefined, check?: boolean, fidList?: string[]): Promise<void>;
-    addByOssUrl(ossUrl: string, name?: string, fid?: string, check?: boolean): Promise<string>;
+    /** 预览图宽度（像素） */
     PREVIEW_IMAGE_WIDTH: number;
+    /** 预览图高度（像素） */
     PREVIEW_IMAGE_HEIGHT: number;
-    generateDescribeAndPreview(file: File): Promise<[string, File | null]>;
-    generatePreviewFile(img: HTMLImageElement | HTMLVideoElement, name: string): Promise<File>;
-    generateDescribeForTexture(texture: BaseTexture, fromFid: string): string;
+    /**
+     * 生成纹理的描述信息
+     *
+     * @param texture - BabylonJS 纹理对象
+     * @param fromFileId - 纹理来源的文件 ID
+     * @returns 包含分辨率和来源文件名的描述字符串
+     */
+    generateDescribeForTexture(texture: BaseTexture, fromFileId: string): string;
+    /**
+     * 生成纹理的预览图文件
+     *
+     * 将 BabylonJS 纹理渲染为 256x256 的 PNG 预览图，保持宽高比居中绘制。
+     *
+     * @param texture - BabylonJS 纹理对象
+     * @param filename - 输出文件名，默认 'texture.png'
+     * @returns PNG 格式的 File 对象，失败返回 null
+     */
     generatePreviewForTexture(texture: BaseTexture, filename?: string): Promise<File | null>;
+    /**
+     * 生成资源/文件 ID
+     *
+     * @returns 以 'F' 为前缀的唯一 ID
+     */
     generateId(): string;
 }
 
@@ -4379,7 +4685,6 @@ export declare enum RsModelStatus {
     CANCELED = "CANCELED"
 }
 
-
 /**
  * @public
  */
@@ -5050,20 +5355,37 @@ export declare interface RvAwarenessWindow {
 }
 
 /**
+ * 全局协同数据总变量
+ *
+ * 所有项目数据的根结构，通过 RhineVar 实现多人实时同步。
+ * files 和 resources 仅存储 ID 列表，元数据通过对应 Service 从后端获取并缓存在本地。
+ *
  * @public
  */
 export declare interface RvBase {
+    /** 项目全局配置 */
     project: RvProject;
+    /** 场景展示顺序（sid 列表） */
     order: RhineVarArray<string>;
+    /** 场景 Map（sid -> RvStep） */
     steps: RhineVarMap<RvStep>;
+    /** 插件信息 */
     plugin: RvPlugin;
-    files: RhineVarMap<RvFile>;
-    resources: RhineVarMap<RvResource>;
+    /** 文件 ID 列表，元数据通过 RvFileService.getMetadata() 获取 */
+    files: RhineVarArray<string>;
+    /** 资源 ID 列表，元数据通过 RvResourceService.getMetadata() 获取 */
+    resources: RhineVarArray<string>;
+    /** 场景节点树 */
     scene: RhineVarMap<RvSceneNode>;
+    /** 模型列表 */
     models: RhineVarMap<RvModel>;
+    /** 材质分离数据 */
     separate: RvSeparate;
+    /** 历史记录 */
     history: RvHistory;
+    /** 会议信息 */
     meetings: RhineVarMap<RvMeeting>;
+    /** 版本信息 */
     version: RvVersion;
 }
 
@@ -5201,42 +5523,97 @@ export declare interface RvEnvironment {
 }
 
 /**
+ * 文件元数据接口
+ *
+ * 描述项目中一个文件的完整元信息。
+ * 协同数据中仅存储 fid，完整元数据通过 RvFileService.getMetadata() 从后端获取并缓存。
+ *
  * @public
  */
 export declare interface RvFile {
+    /** 文件唯一标识 */
     fid: string;
+    /** 文件存储类型 */
     type: RvFileType;
+    /** 文件名 */
     name: string;
+    /** 文件大小（字节） */
     size: number;
+    /** MIME 类型 */
     mime: string;
+    /** 文件内容哈希值，用于去重 */
     hash?: string;
+    /** 文件地址。格式: https://xxx | oss://{bucket}/{path} | attach://{fid} */
     url: string;
+    /** 创建时间戳（毫秒） */
     createdAt: number;
+    /** 更新时间戳（毫秒） */
     updatedAt: number;
+    /** 是否正在上传中 */
     uploading?: boolean;
+    /** 扩展数据 */
     extra?: Record<string, unknown>;
 }
 
 /**
+ * 文件协同数据服务
+ *
+ * 管理协同数据中的 fileId 列表，以及本地文件元数据缓存。
+ * fileId 列表存储在协同数据中，元数据从后端获取并缓存在本地。
+ *
  * @public
  */
 export declare class RvFileService {
     static get instance(): RvFileService;
     private constructor();
-    files: RecursiveMap<RvFile>;
-    get(fid: string): RecursiveObject<RvFile> | undefined;
-    getByUrl(url: string): RecursiveObject<RvFile> | undefined;
-    has(fid: string): boolean;
-    hasUrl(url: string): boolean;
-    add(fileData: RvFile): Promise<StoredRhineVar<RvFile> | null>;
-    addByUrl(url: string): Promise<StoredRhineVar<RvFile> | null>;
-    remove(fid: string): boolean;
+    files: RhineVarArray<string>;
+    private metadataCache;
+    /**
+     * 添加 fileId 到协同数据
+     */
+    add(fileId: string): void;
+    /**
+     * 从协同数据移除 fileId
+     */
+    remove(fileId: string): boolean;
+    /**
+     * 检查 fileId 是否在列表中
+     */
+    has(fileId: string): boolean;
+    /**
+     * 获取缓存的文件元数据
+     */
+    getMetadata(fileId: string): ResourceFileInfo | undefined;
+    /**
+     * 设置文件元数据缓存
+     */
+    setMetadata(fileId: string, metadata: ResourceFileInfo): void;
+    /**
+     * 获取文件下载 URL（通过后端签名）
+     */
+    getDownloadUrl(fileId: string): Promise<string>;
+    /**
+     * 订阅文件列表变化事件（ADD/REMOVE）
+     *
+     * @param subscriber - 事件回调函数
+     * @returns 取消订阅的函数
+     */
     subscribe(subscriber: RvFileServiceSubscriber): () => void;
+    /**
+     * 取消订阅文件列表变化事件
+     *
+     * @param subscriber - 要取消的回调函数
+     */
     unsubscribe(subscriber: RvFileServiceSubscriber): void;
-    subscribeSingle(fid: string, subscriber: RvFileServiceSubscriber): () => void;
-    unsubscribeSingle(fid: string, subscriber: RvFileServiceSubscriber): void;
-    generateId(): string;
-    findSame(file: File): Promise<string | null>;
+    /**
+     * 订阅单个文件的变化事件
+     *
+     * @param fileId - 文件 ID
+     * @param subscriber - 事件回调函数
+     * @returns 取消订阅的函数
+     */
+    subscribeSingle(fileId: string, subscriber: RvFileServiceSubscriber): () => void;
+    unsubscribeSingle(fileId: string, subscriber: RvFileServiceSubscriber): void;
 }
 
 /**
@@ -5250,7 +5627,7 @@ export declare enum RvFileServiceEventType {
 /**
  * @public
  */
-export declare type RvFileServiceSubscriber = (type: RvFileServiceEventType, fid: string, rvFile?: RecursiveObject<RvFile>) => void;
+export declare type RvFileServiceSubscriber = (type: RvFileServiceEventType, fileId: string) => void;
 
 /**
  * @public
@@ -5682,42 +6059,107 @@ export declare class RvProjectService {
 }
 
 /**
+ * 资源元数据接口
+ *
+ * 描述项目中一个资源的完整元信息。资源是用户可见的文件或程序资源（如材质、贴图）。
+ * 协同数据中仅存储资源 ID，完整元数据通过 RvResourceService.getMetadata() 从后端获取并缓存。
+ *
+ * 一个资源可能对应多个文件（如图片资源 + 缩略图文件），
+ * 一个文件也可能对应多个资源（如模型文件内部的多个贴图为 Attach 型资源）。
+ *
  * @public
  */
 export declare interface RvResource {
+    /** 关联的文件 ID */
     fid: string;
+    /** 资源名称 */
     name: string;
+    /** 资源类型: FILE（独立文件资源）或 ATTACH（主资源的内置子资源） */
     type: RvResourceType;
+    /** MIME 类型 */
     mime: string;
+    /** 预览图 URL */
     preview?: string;
+    /** 资源描述信息 */
     description?: string;
+    /** Attach 型资源的来源信息，仅当 type 为 ATTACH 时存在 */
     from?: {
+        /** 来源文件 ID */
         fid: string;
+        /** Attach 类型: TEXTURE | MATERIAL | UV */
         type: RvAttachType;
+        /** 资源在文件内部的路径 */
         path: string;
     };
+    /** 创建时间戳（毫秒） */
     createdAt: number;
+    /** 更新时间戳（毫秒） */
     updatedAt: number;
+    /** 扩展数据 */
     extra?: Record<string, unknown>;
 }
 
 /**
+ * 资源协同数据服务
+ *
+ * 管理协同数据中的 resourceId 列表，以及本地资源元数据缓存。
+ * resourceId 列表存储在协同数据中，元数据从后端获取并缓存在本地。
+ *
  * @public
  */
 export declare class RvResourceService {
     static get instance(): RvResourceService;
     private constructor();
-    resources: RecursiveMap<RvResource>;
-    get(fid: string): RecursiveObject<RvResource> | undefined;
-    has(fid: string): boolean;
-    add(file: RvResource): void;
-    remove(fid: string): boolean;
+    resources: StoredRhineVar<string[]>;
+    private metadataCache;
+    /**
+     * 添加 resourceId 到协同数据
+     */
+    add(resourceId: string): void;
+    /**
+     * 从协同数据移除 resourceId
+     */
+    remove(resourceId: string): boolean;
+    /**
+     * 检查 resourceId 是否在列表中
+     */
+    has(resourceId: string): boolean;
+    /**
+     * 获取缓存的资源元数据
+     */
+    getMetadata(resourceId: string): Resource | undefined;
+    /**
+     * 设置资源元数据缓存
+     */
+    setMetadata(resourceId: string, metadata: Resource): void;
+    /**
+     * 批量获取所有资源元数据（项目初始化时调用）
+     *
+     * 同时从 Resource.contentFile 提取文件元数据，写入 RvFileService.metadataCache
+     */
+    fetchAllMetadata(): Promise<void>;
+    /**
+     * 订阅资源列表变化事件（ADD/REMOVE）
+     *
+     * @param subscriber - 事件回调函数
+     * @returns 取消订阅的函数
+     */
     subscribe(subscriber: RvResourceServiceSubscriber): () => void;
+    /**
+     * 取消订阅资源列表变化事件
+     *
+     * @param subscriber - 要取消的回调函数
+     */
     unsubscribe(subscriber: RvResourceServiceSubscriber): void;
-    subscribeSingle(fid: string, subscriber: RvResourceServiceSubscriber): () => void;
-    unsubscribeSingle(fid: string, subscriber: RvResourceServiceSubscriber): void;
-    generateId(): string;
-    findSame(file: File): Promise<string | null>;
+    /**
+     * 订阅单个资源的变化事件
+     *
+     * @param resourceId - 资源 ID
+     * @param subscriber - 事件回调函数
+     * @returns 取消订阅的函数
+     */
+    subscribeSingle(resourceId: string, subscriber: RvResourceServiceSubscriber): () => void;
+    unsubscribeSingle(resourceId: string, subscriber: RvResourceServiceSubscriber): void;
 }
 
 /**
@@ -5731,7 +6173,7 @@ export declare enum RvResourceServiceEventType {
 /**
  * @public
  */
-export declare type RvResourceServiceSubscriber = (type: RvResourceServiceEventType, fid: string, rvResource?: RecursiveObject<RvResource>) => void;
+export declare type RvResourceServiceSubscriber = (type: RvResourceServiceEventType, resourceId: string) => void;
 
 /**
  * @public
@@ -6467,7 +6909,8 @@ export declare class SyncService {
      *
      * @public
      */
-    url: string;
+    private getUrl;
+    private getToken;
     /**
      * RhineVar 协同状态对象
      *
@@ -6758,7 +7201,6 @@ declare function toEulerDegrees(v: V4): V3;
 
 declare function toEulerRadians(v: V4): V3;
 
-
 /**
  * 360度制欧拉角转四元数
  * @public
@@ -6823,7 +7265,7 @@ export declare function useAllSelectedInfo(): {
 /**
  * @public
  */
-export declare function useGlobalAttribute<T extends object = any>(path?: string | RvPath): {
+export declare function useGlobalAttribute<T extends object = object>(path?: string | RvPath): {
     state: T | StoredRhineVar<T>;
     path: string | RvPath;
     targetGlobalAttribute: GlobalAttribute<T>;
@@ -6903,7 +7345,7 @@ export declare function useStepOptions(withDisable?: boolean): StepOptions;
 /**
  * @public
  */
-export declare function useTargetNodeAttribute<T extends object = any>(path?: string | RvPath): {
+export declare function useTargetNodeAttribute<T extends object = object>(path?: string | RvPath): {
     state: T | StoredRhineVar<T>;
     path: string | RvPath;
     sid: string;
@@ -6939,7 +7381,7 @@ export declare function useTargetNodeAttribute<T extends object = any>(path?: st
 /**
  * @public
  */
-export declare function useTargetStepAttribute<T extends object = any>(path?: string | RvPath): {
+export declare function useTargetStepAttribute<T extends object = object>(path?: string | RvPath): {
     state: T | StoredRhineVar<T>;
     path: string | RvPath;
     sid: string;

package/package.json

@@ -34,9 +34,9 @@
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "valtio": "2.1.7",
-    "rhine-var": "^2.1.0"
+    "rhine-var": "2.4.3"
   },
-  "version": "0.27.7",
+  "version": "0.27.11",
   "author": "NextFlow",
   "license": "Apache-2.0",
   "keywords": [