vrtalk-web-sdk 0.1.598 → 0.1.600

package/dist/src/api-catalog/catalog-domain-classes.d.ts

@@ -0,0 +1,20 @@
+import type { XrApiClassMeta } from './xr-api-catalog';
+/**
+ * ============================================================
+ * 标准库目录 —— B. 领域/系统静态类（plan §5B）
+ * ============================================================
+ *
+ * 全部 kind:'static'、groupKey:'system'。承接现有「无目标 / 系统级」老动作
+ * （vr-action.ts 各 VrActionParams*），legacyActionType 一一对应，供：
+ *   - console 迁移器（老 VrAction → XrObjectCallAction）
+ *   - 运行时向后兼容归一（plan §1.23）
+ *
+ * 约定（勿改）：
+ *   - 老动作在 vr-action-platform-capability 里登记为 VR_ONLY 的
+ *     （camera_* / sweep_* / tag模拟点击 / system_color_space_*），对应方法 platform='vr_only'
+ *   - 耗时操作 supportsAsync=true（TTS/AI/网络/运镜/导航/相机移动等，plan §1.17）
+ *   - pure=true 仅限真正无副作用查询（可进条件槽，plan §4.1 红线）
+ *
+ * 本文件只导出 buildDomainClasses()，无 import 副作用、不自行 register（plan §1.34/§1.37）。
+ */
+export declare function buildDomainClasses(): XrApiClassMeta[];

package/dist/src/api-catalog/catalog-entity-components.d.ts

@@ -0,0 +1,25 @@
+import { type XrApiClassMeta } from './xr-api-catalog';
+/**
+ * ============================================================
+ * 标准库目录 —— 装修组件实体类树（groupKey='decorate'）
+ * ============================================================
+ *
+ * 来源（老体系映射）：
+ *   - 方法 = vr-action.ts 的 component_* 动作族（component_general_* / component_2d_* / component_3d_* / component_tag_*），
+ *     参数字段逐一对照各 VrActionParams* 类抄写（legacyActionType 一对一）。
+ *     老 params 里的 componentId 在新体系由接收者（receiver）承担，不再作为方法参数。
+ *   - 事件 = vr-signal.ts 的组件相关信号（VrSignalTypeSourceMapping 中 component_* 各 source）。
+ *   - 继承树 = vr-component-data.ts 现实类树：
+ *       VrComponentData（抽象）
+ *         ├─ VrComponentData2d（抽象）→ 2d_text / 2d_image / 2d_video / 2d_panel / 2d_advertisement
+ *         ├─ VrComponentData3d（抽象）→ 3d_box / 3d_model
+ *         └─ tag（VrComponentTagData 直接继承 VrComponentData，跳过 2d/3d 层）
+ *   - 子件实体：panel_button / panel_scene（vr-component-2d-panel-data.ts 的
+ *     VrComponent2dPanelButtonItemData / VrComponent2dPanelSceneData），复合寻址走 parentPathSpec。
+ *
+ * 约定：
+ *   - 本文件只构造元数据、无 import 副作用，不自行 register（由目录装配入口统一注册）。
+ *   - 方法分组名（groupKey→显示名）沿继承链解析：子类方法可复用父类 methodGroups 里定义的 groupKey。
+ */
+/** 构造装修组件实体类树的全部类元数据 */
+export declare function buildComponentEntityClasses(): XrApiClassMeta[];

package/dist/src/api-catalog/catalog-entity-space.d.ts

@@ -0,0 +1,20 @@
+import { XrApiClassMeta } from './xr-api-catalog';
+/**
+ * ============================================================
+ * 标准库目录 —— 空间 / 逻辑 / AI / 内容 实体类（plan §5C / §5「实例方法」）
+ * ============================================================
+ *
+ * 本文件收录四组实体类（kind='entity'）：
+ *   - groupKey='space'  ：贴纸 / 空间围栏(+组) / 射线命中器 / 扫描点位 / 标记
+ *   - groupKey='logic'  ：后台线程 / 能力(@deprecated) / 运镜路径 / 广播频道
+ *   - groupKey='ai'     ：AI智能体
+ *   - groupKey='content'：音频列表 / 音频 / 目标点 / 虫洞 / 阻隔器
+ *
+ * 老体系映射来源：
+ *   - 方法 → vr-action.ts 的 VrActionTypeDefine（legacyActionType 一对一）
+ *   - 事件 → vr-signal.ts 的 VrSignalSource / VrSignalType（legacySignalSource/Type）
+ *   - pure 查询 → player xr-condition-function-registry 的判断函数（legacyConditionFunc）
+ *
+ * 约定：仅导出 buildSpaceEntityClasses()，无 import 副作用、不自行 register（由汇总入口统一注册）。
+ */
+export declare function buildSpaceEntityClasses(): XrApiClassMeta[];

package/dist/src/api-catalog/catalog-entity-ui.d.ts

@@ -0,0 +1,23 @@
+import { XrApiClassMeta } from './xr-api-catalog';
+/**
+ * ============================================================
+ * 标准库目录 —— UI 实体类（groupKey='ui'）
+ * ============================================================
+ *
+ * 覆盖老动作族：
+ *   - monitor_*                     监控面板 / 监控组件 / 监控视频组件
+ *   - hamburger_menu_*              汉堡菜单 / 汉堡节点 / 汉堡分组
+ *   - canvas_component_*            汉堡画布节点内的画布组件
+ *   - message_card_*                消息卡（含临时消息卡静态类 MessageCardCenter）
+ *   - information_content_card_*    内容卡
+ *   - visualization_controller_*    可视化控制器（静态类）
+ *   - layer_change_visibility       图层
+ *
+ * 老实体来源：xr-monitor.ts / xr-hamburger-menu.ts / xr-message-card.ts / vr-content-card.ts / vr-layer.ts
+ * 老判断函数来源：player xr-condition-function-registry（monitor_enabled / layer_visible / …）
+ *
+ * 约定（plan §1.34/§1.37）：
+ *   - 老动作里的 *IdList 批量字段一律收敛为「接收者=单个实体」；批量需求走 列表.遍历（forEach）
+ *   - 本文件只构造不注册（无 import 副作用），由目录入口统一 registerApiClasses
+ */
+export declare function buildUiEntityClasses(): XrApiClassMeta[];

package/dist/src/api-catalog/catalog-value-classes.d.ts

@@ -0,0 +1,3 @@
+import type { XrApiClassMeta } from './xr-api-catalog';
+/** A. 值/工具类 全目录（plan §5A；由目录装配入口统一注册） */
+export declare function buildValueClasses(): XrApiClassMeta[];

package/dist/src/api-catalog/index.d.ts

@@ -0,0 +1,8 @@
+export * from './xr-api-catalog';
+export { buildValueClasses } from './catalog-value-classes';
+export { buildDomainClasses } from './catalog-domain-classes';
+export { buildComponentEntityClasses } from './catalog-entity-components';
+export { buildUiEntityClasses } from './catalog-entity-ui';
+export { buildSpaceEntityClasses } from './catalog-entity-space';
+/** 注册全部标准库/实体类元数据（幂等；重复调用直接跳过） */
+export declare function registerAllApiCatalog(): void;

package/dist/src/api-catalog/xr-api-catalog.d.ts

@@ -0,0 +1,167 @@
+import type { XrVariableType } from '../model/vr/xr-logic';
+/**
+ * ============================================================
+ * 可视化编程系统 —— 标准库 / 对象方法 元数据表（plan §5 / §11.1）
+ * ============================================================
+ *
+ * 这是「对象.方法」体系的唯一真源（SSOT），供五处共同消费：
+ *   1. 运行时方法分派表（player TS / Unity C#）：按 (classKey, methodKey) 找处理器
+ *   2. console 编辑器：选完接收者后，右侧 select 列该类型的方法（多则按 groupKey 分组）
+ *   3. 条件脱糖：纯查询方法（pure=true）在条件槽被编辑期编译成表达式字符串（legacyConditionFunc）
+ *   4. 「类型 → 选择器」注册表（selectorKey）
+ *   5. C# / Swift 代码生成
+ *
+ * 约定（plan §1.34/§1.37）：
+ *   - classKey / methodKey / paramKey 一律英文小驼峰或既有类型键；UI 显示走 name 三语
+ *   - 实体类 classKey 沿用现有类型键（'2d_video' / 'tag' / 'monitor' …），静态类用大驼峰（'Camera'/'String'）
+ *   - 老 actionType / 老判断函数 通过 legacyActionType / legacyConditionFunc 建立映射，
+ *     供 迁移器（console）与 运行时向后兼容归一（plan §1.23）使用
+ */
+/** 目录用三语文本（静态元数据，非用户内容，不用 MultiLanguageStr） */
+export declare class XrApiText {
+    cn: string;
+    en: string;
+    jp: string;
+    constructor(cn?: string, en?: string, jp?: string);
+}
+/** 便捷构造 */
+export declare function apiText(cn: string, en: string, jp: string): XrApiText;
+/**
+ * 参数/返回值的值类型：
+ * - 复用 XrVariableType 全集（string/number/boolean/color/css_color/image/entity_ref/list/custom_class/closure/句柄类…）
+ * - 追加结构值：vector3 / vector2 / multilang_str（用户可见多语言文本）/ enum（固定选项）/ any
+ */
+export declare type XrApiValueType = XrVariableType | 'vector3' | 'vector2' | 'multilang_str' | 'enum' | 'any' | 'void';
+/** enum 型参数的固定选项 */
+export declare class XrApiEnumOption {
+    value: string;
+    name: XrApiText;
+}
+/** 方法参数元数据 */
+export declare class XrApiParamMeta {
+    key: string;
+    name: XrApiText;
+    desc?: XrApiText;
+    type: XrApiValueType;
+    refTypeKey?: string;
+    listElementType?: XrApiValueType;
+    listElementRefTypeKey?: string;
+    enumOptions?: XrApiEnumOption[];
+    closurePayloadFields?: XrApiParamMeta[];
+    optional: boolean;
+    defaultValue?: any;
+}
+/** 返回值元数据 */
+export declare class XrApiReturnMeta {
+    type: XrApiValueType;
+    refTypeKey?: string;
+    customClassId?: string;
+    listElementType?: XrApiValueType;
+    listElementRefTypeKey?: string;
+    desc?: XrApiText;
+}
+/** 平台可用性（沿用 vr-action-platform-capability 的语义；缺省 vr_and_ar） */
+export declare type XrApiPlatform = 'vr_and_ar' | 'vr_only' | 'ar_only';
+/** 方法元数据 */
+export declare class XrApiMethodMeta {
+    key: string;
+    name: XrApiText;
+    desc?: XrApiText;
+    params: XrApiParamMeta[];
+    returns: XrApiReturnMeta;
+    platform: XrApiPlatform;
+    supportsAsync: boolean;
+    pure: boolean;
+    groupKey: string;
+    legacyActionType?: string;
+    legacyConditionFunc?: string;
+}
+/** 事件元数据（实体类的「帽子」；监听器可订阅） */
+export declare class XrApiEventMeta {
+    key: string;
+    name: XrApiText;
+    desc?: XrApiText;
+    payloadFields: XrApiParamMeta[];
+    aggregate: boolean;
+    platform: XrApiPlatform;
+    legacySignalSource?: string;
+    legacySignalType?: string;
+}
+/** 类的种类：静态类（无实例、全静态方法）/ 实体类（空间实体或其子件，可作 entity_ref 变量类型） */
+export declare type XrApiClassKind = 'static' | 'entity';
+/** 类分组（编辑器目录/工具箱的顶层分组） */
+export declare class XrApiGroupMeta {
+    key: string;
+    name: XrApiText;
+}
+/** 实体类的补充信息 */
+export declare class XrApiEntityInfo {
+    extendsClassKey: string;
+    isAbstract: boolean;
+    listPath: string;
+    parentPathSpec: string[];
+    selectorKey: string;
+    usableAsVariableType: boolean;
+}
+/** 类元数据 */
+export declare class XrApiClassMeta {
+    classKey: string;
+    name: XrApiText;
+    desc?: XrApiText;
+    kind: XrApiClassKind;
+    groupKey: string;
+    entityInfo?: XrApiEntityInfo;
+    methods: XrApiMethodMeta[];
+    events: XrApiEventMeta[];
+    methodGroups: XrApiGroupMeta[];
+}
+export declare function apiParam(p: Partial<XrApiParamMeta> & {
+    key: string;
+    name: XrApiText;
+    type: XrApiValueType;
+}): XrApiParamMeta;
+export declare function apiReturn(r: Partial<XrApiReturnMeta> & {
+    type: XrApiValueType;
+}): XrApiReturnMeta;
+export declare function apiMethod(m: Partial<XrApiMethodMeta> & {
+    key: string;
+    name: XrApiText;
+}): XrApiMethodMeta;
+export declare function apiEvent(e: Partial<XrApiEventMeta> & {
+    key: string;
+    name: XrApiText;
+}): XrApiEventMeta;
+export declare function apiEnumOption(value: string, name: XrApiText): XrApiEnumOption;
+export declare function apiEntityInfo(i: Partial<XrApiEntityInfo>): XrApiEntityInfo;
+export declare function apiGroup(key: string, name: XrApiText): XrApiGroupMeta;
+export declare function apiClass(c: Partial<XrApiClassMeta> & {
+    classKey: string;
+    name: XrApiText;
+    kind: XrApiClassKind;
+}): XrApiClassMeta;
+/**
+ * 为一个「带事件的实体类」构造通用 `addListener` 实例方法（plan §4.5 动态监听）。
+ * 万物监听同一机制：动态监听 = 动作里 `句柄 = 实体.添加监听器(事件, 回调)`；
+ * 声明式监听器 / VB 快捷编辑 handler 只是系统在场景启动时替用户走同一条注册路径。
+ * 事件参数的可选值 = 该类（含继承）全部事件；回调闭包内 _事件.$ 为该事件载荷。
+ */
+export declare function buildAddListenerMethod(classMeta: XrApiClassMeta, inheritedEvents: XrApiEventMeta[]): XrApiMethodMeta;
+/** 注册一个类（重复 classKey 直接覆盖并告警——目录应保证唯一） */
+export declare function registerApiClass(meta: XrApiClassMeta): void;
+/** 批量注册 */
+export declare function registerApiClasses(metas: XrApiClassMeta[]): void;
+export declare function getApiClass(classKey: string): XrApiClassMeta | undefined;
+export declare function getAllApiClasses(): XrApiClassMeta[];
+/** 取一个类的全部方法（含沿 extendsClassKey 链上溯的父类方法；子类同名覆盖父类） */
+export declare function getApiMethodsWithInherited(classKey: string): XrApiMethodMeta[];
+/** 取一个类的全部事件（含继承） */
+export declare function getApiEventsWithInherited(classKey: string): XrApiEventMeta[];
+/** 按 (classKey, methodKey) 找方法（含继承） */
+export declare function findApiMethod(classKey: string, methodKey: string): XrApiMethodMeta | undefined;
+/** 按老 actionType 反查 (classKey, method)——迁移器 / 运行时兼容归一用 */
+export declare function findByLegacyActionType(actionType: string): {
+    classMeta: XrApiClassMeta;
+    method: XrApiMethodMeta;
+} | undefined;
+/** 判断某方法是否允许进条件槽/值槽（plan §4.1 红线） */
+export declare function isPureQuery(classKey: string, methodKey: string): boolean;

package/dist/src/index.d.ts

@@ -1,6 +1,7 @@
 export * from './model';
 export * from './player';
 export * from './parent';
+export * from './api-catalog';
 export { migrateTriggersToCentralized } from './utils/trigger-migration';
 export { resolveVrMainBarItems, resolveVrInfoBarItems, resolveArBottomItems, resolveArInfoItems, ensureIconLayoutMaterialized, ensureLegacyVrPlayerUiSettingsInitialized, } from './utils/ui-icon-layout-migrate';
 export { migrateXrVariableTypeEnum } from './utils/xr-variable-type-enum-migration';
@@ -8,4 +9,4 @@ export { migrateXrMonitorMultiScene } from './utils/xr-monitor-multi-scene-migra
 export { buildExpressionFromTree, extractConditionTreeDependencies, EXPRESSION_FUNC_NAME, type ConditionFunctionDependency, type ConditionFunctionDepSpec, type ConditionTreeDependencies, } from './utils/xr-condition-tree-builder';
 export { pickMultiLanguageStr, normalizeMultiLanguageStr, createMultiLanguageStr, normalizeBrowserLanguage, pickCurrentLanguage, } from './utils/multi-language-str-util';
 export { computeProgressBarFillStyle, PROGRESS_BAR_KEYFRAMES_CSS, type ProgressBarFillOptions, } from './utils/progress-bar-style';
-export { generatePathKeyframes, samplePathDesign, buildKeyframesFromSampling, suggestedPlayCompleteProcessType, simplifyPathPoints, composePathPoseEuler, composePathPoseEulerCalibrated, resolvePathCalibration, rotateVecAroundAxis, extractYawTwistDeg, type PathGroundSnapFn, type PathSample, type PathSamplingResult, type PathGenerateStats, type PathGenerateResult, } from './utils/path-keyframe-generator';
+export { generatePathKeyframes, samplePathDesign, buildKeyframesFromSampling, suggestedPlayCompleteProcessType, simplifyPathPoints, composePathPoseEuler, composePathPoseEulerCalibrated, computeGroundPose, resolvePathCalibration, rotateVecAroundAxis, extractYawTwistDeg, type PathGroundSnapFn, type PathSample, type PathSamplingResult, type PathGenerateStats, type PathGenerateResult, } from './utils/path-keyframe-generator';

package/dist/src/model/vr/index.d.ts

@@ -32,6 +32,7 @@ export * from './vr-ui-icon-layout';
 export * from './vr-render-settings';
 export * from './vr-color-space-settings';
 export * from './vr-signal';
+export * from './xr-ray-hitter';
 export * from './xr-space-fence';
 export * from './xr-space-fence-group';
 export * from './vr-sticker';
@@ -55,3 +56,4 @@ export * from './xr-camera-dolly-path';
 export * from './xr-prepare';
 export * from './xr-ability';
 export * from './xr-hamburger-menu';
+export * from './xr-program';

package/dist/src/model/vr/vr-action.d.ts

@@ -1,18 +1,20 @@
 import { Color, type MediaLoopMode, Vector2, Vector3, VrCameraMoveTransitionType } from '../general';
 import { XrMessageCard } from './xr-message-card';
 import { VrComponent2dDeformationSettings } from '../vr-component/vr-component-data';
-import { XrTypedValue, XrVariableScopeType, XrVariableTarget } from './xr-logic';
+import { XrTypedValue, XrVariable, XrVariableScopeType, XrVariableTarget } from './xr-logic';
 import { MultiLanguageStr } from '../general/multi-language-str';
 import { FreeButton } from '../general/free-button';
 import { VrAppearanceStyle } from './vr-appearance-style';
 import { XrInteractionControlConfig, XrInteractionDataType } from './xr-interaction-control';
-export declare type XrActionCategory = 'basic' | 'condition' | 'count_loop' | 'expression_loop' | 'switch';
+export declare type XrActionCategory = 'basic' | 'condition' | 'count_loop' | 'expression_loop' | 'switch' | 'object_call' | 'foreach_loop';
 export declare class XrActionCategoryDefine {
     static readonly BASIC: XrActionCategory;
     static readonly CONDITION: XrActionCategory;
     static readonly COUNT_LOOP: XrActionCategory;
     static readonly EXPRESSION_LOOP: XrActionCategory;
     static readonly SWITCH: XrActionCategory;
+    static readonly OBJECT_CALL: XrActionCategory;
+    static readonly FOREACH_LOOP: XrActionCategory;
 }
 export declare type XrPlatform = 'VR' | 'AR';
 export declare class XrPlatformDefine {
@@ -23,7 +25,7 @@ export declare class XrBaseAction {
     actionCategory: XrActionCategory;
     backgroundColorMark: string;
 }
-export declare type XrAnyAction = XrConditionAction | XrCountLoopAction | XrExpressionLoopAction | XrSwitchAction | VrAction;
+export declare type XrAnyAction = XrConditionAction | XrCountLoopAction | XrExpressionLoopAction | XrSwitchAction | VrAction | XrObjectCallAction | XrForEachLoopAction;
 /**
  * VR动作
  */
@@ -143,7 +145,76 @@ export declare class XrSwitchAction {
     caseList: XrSwitchCase[];
     defaultActionList: XrAnyAction[];
 }
-export declare type VrActionType = 'system_common_wait' | 'system_set_interactive_state' | 'system_ui_settings_change' | 'system_color_space_scene_tint' | 'system_color_space_display_brightness' | 'component_general_change_visibility' | 'component_general_change_transform' | 'component_general_play_transition_animation' | 'component_general_stop_transition_animation' | 'component_2d_general_change_deformation_settings' | 'component_general_audio_source_play_control' | 'component_general_audio_source_pause' | 'component_general_audio_source_change_loop_mode' | 'component_2d_image_change_source' | 'component_2d_video_change_source' | 'component_2d_video_change_play_state' | 'component_2d_video_change_mute_state' | 'component_2d_text_change_source' | 'component_2d_panel_change_scene' | 'component_2d_panel_button_change_enabled' | 'component_tag_simulate_click' | 'component_3d_box_change_color' | 'component_3d_model_play_animation_clip' | 'component_3d_model_stop_animation_clip' | 'information_content_card_show' | 'information_content_card_close' | 'information_link_open' | 'information_link_close' | 'audio_center_play_list' | 'audio_center_pause' | 'audio_center_set_volume' | 'sweep_change_enabled' | 'sweep_change_panorama' | 'sweep_marker_change_enabled' | 'sweep_reset_to_default' | 'sweep_only_enable_current' | 'camera_move_to' | 'camera_dolly_move' | 'camera_dolly_stop' | 'navigation_start' | 'navigation_stop' | 'logic_variable_modify' | 'logic_variable_number_add' | 'logic_variable_number_subtract' | 'logic_variable_string_append' | 'logic_variable_string_trim_end' | 'logic_variable_string_advanced' | 'logic_variable_boolean_toggle' | 'flow_enter' | 'flow_exit' | 'send_broadcast' | 'system_state_scope_create' | 'system_state_scope_switch' | 'system_state_scope_destroy' | 'monitor_change_enabled' | 'monitor_switch_active_tab' | 'monitor_component_change_visibility' | 'monitor_video_change_play_state' | 'monitor_video_change_mute_state' | 'monitor_change_badge_text' | 'monitor_change_badge_style' | 'monitor_switch_active_scene' | 'monitor_change_popup_visible' | 'layer_change_visibility' | 'hamburger_menu_node_change_visibility' | 'hamburger_menu_change_open_state' | 'hamburger_menu_group_change_expanded' | 'canvas_component_change_visibility' | 'message_card_change_show_state' | 'message_card_show' | 'message_card_hide' | 'message_card_create_temporary' | 'message_card_destroy_temporary' | 'tts_play_voice' | 'tts_realtime_stream' | 'background_thread_start' | 'background_thread_pause' | 'background_thread_stop' | 'ai_agent_activate' | 'ai_agent_hide' | 'ai_agent_wake' | 'ai_agent_activate_and_send_user_message' | 'ai_agent_activate_and_inject_dialogue' | 'ai_agent_inject_hidden_state_message' | 'ai_agent_activate_and_inject_assistant_message' | 'system_open_webpage' | 'ability_enable' | 'ability_stop' | 'cloud_form_show_dialog' | 'cloud_form_collect_field' | 'cloud_form_submit' | 'cloud_form_reset' | 'hit_analytics_event' | 'popup_user_form_show_dialog' | 'logic_random_number' | 'logic_random_color' | 'logic_current_time' | 'logic_random_pick_string' | 'logic_random_pick_number' | 'logic_random_pick_boolean' | 'logic_random_pick_enum' | 'logic_random_pick_color' | 'logic_random_pick_css_color' | 'logic_random_pick_from_recommend_options' | 'visualization_controller_pop' | 'visualization_controller_hide' | 'visualization_controller_close_all';
+export declare type XrReceiverFrom = 'picker' | 'variable' | 'static_class';
+export declare class XrReceiverFromDefine {
+    static readonly PICKER: XrReceiverFrom;
+    static readonly VARIABLE: XrReceiverFrom;
+    static readonly STATIC_CLASS: XrReceiverFrom;
+}
+/**
+ * 接收者引用——「对象.方法」里的对象。
+ * typeKey 是类型键（实体类型如 'component'/'2d_video'/'monitor'，或静态类如 'Camera'/'Thread'/'String'），
+ * 与 xr-api-catalog 元数据表的 classKey 对应，用于：编辑器列方法菜单、运行时查分派表。
+ */
+export declare class XrReceiverRef {
+    from: XrReceiverFrom;
+    typeKey: string;
+    entityId: string;
+    entityParentPath: string[];
+    variableScope?: XrVariableScopeType;
+    variableKey?: string;
+}
+export declare type XrCallArgKind = 'literal' | 'var_ref' | 'call' | 'closure';
+export declare class XrCallArgKindDefine {
+    static readonly LITERAL: XrCallArgKind;
+    static readonly VAR_REF: XrCallArgKind;
+    static readonly CALL: XrCallArgKind;
+    static readonly CLOSURE: XrCallArgKind;
+}
+/**
+ * 闭包值——一段动作块作为值传递（plan §4.3⑤）。
+ * 用于：监听器回调、后台线程/定时器循环体、列表.遍历、函数回调参数、异步完成回调。
+ * 运行期以「块 AST 片段」形式存续（可序列化）；执行时压入一个 func 帧承载 localVariableList。
+ */
+export declare class XrClosureValue {
+    localVariableList: XrVariable[];
+    actionList: XrAnyAction[];
+}
+/** 单个实参（按方法元数据的 paramKey 对位） */
+export declare class XrCallArg {
+    key: string;
+    argKind: XrCallArgKind;
+    literal?: any;
+    variableScope?: XrVariableScopeType;
+    variableKey?: string;
+    call?: XrObjectCallAction;
+    closure?: XrClosureValue;
+}
+/**
+ * 对象.方法 调用块（新体系核心；actionCategory='object_call'）
+ */
+export declare class XrObjectCallAction extends XrBaseAction {
+    actionCategory: XrActionCategory;
+    id: string;
+    receiver: XrReceiverRef;
+    method: string;
+    args: XrCallArg[];
+    returnTo?: XrVariableTarget;
+    runAsync: boolean;
+    onCompleteActionList: XrAnyAction[];
+}
+/**
+ * 遍历循环块（actionCategory='foreach_loop'）：对列表逐元素执行循环体。
+ * 元素/下标以 _函数.$ 帧变量形式注入循环体（itemVarKey / indexVarKey）。
+ */
+export declare class XrForEachLoopAction {
+    actionCategory: XrActionCategory;
+    collection: XrCallArg;
+    itemVarKey: string;
+    indexVarKey: string;
+    actionList: XrAnyAction[];
+}
+export declare type VrActionType = 'system_common_wait' | 'system_set_interactive_state' | 'system_ui_settings_change' | 'system_color_space_scene_tint' | 'system_color_space_display_brightness' | 'component_general_change_visibility' | 'component_general_change_transform' | 'component_general_play_transition_animation' | 'component_general_stop_transition_animation' | 'component_2d_general_change_deformation_settings' | 'component_general_audio_source_play_control' | 'component_general_audio_source_pause' | 'component_general_audio_source_change_loop_mode' | 'component_2d_image_change_source' | 'component_2d_video_change_source' | 'component_2d_video_change_play_state' | 'component_2d_video_change_mute_state' | 'component_2d_text_change_source' | 'component_2d_panel_change_scene' | 'component_2d_panel_button_change_enabled' | 'component_tag_simulate_click' | 'component_3d_box_change_color' | 'component_3d_model_play_animation_clip' | 'component_3d_model_stop_animation_clip' | 'information_content_card_show' | 'information_content_card_close' | 'information_link_open' | 'information_link_close' | 'audio_center_play_list' | 'audio_center_pause' | 'audio_center_set_volume' | 'sweep_change_enabled' | 'sweep_change_panorama' | 'sweep_marker_change_enabled' | 'sweep_reset_to_default' | 'sweep_only_enable_current' | 'camera_move_to' | 'camera_dolly_move' | 'camera_dolly_stop' | 'navigation_start' | 'navigation_stop' | 'logic_variable_modify' | 'logic_variable_number_add' | 'logic_variable_number_subtract' | 'logic_variable_string_append' | 'logic_variable_string_trim_end' | 'logic_variable_string_advanced' | 'logic_variable_boolean_toggle' | 'flow_enter' | 'flow_exit' | 'send_broadcast' | 'system_state_scope_create' | 'system_state_scope_switch' | 'system_state_scope_destroy' | 'monitor_change_enabled' | 'monitor_switch_active_tab' | 'monitor_component_change_visibility' | 'monitor_video_change_play_state' | 'monitor_video_change_mute_state' | 'monitor_change_badge_text' | 'monitor_change_badge_style' | 'monitor_switch_active_scene' | 'monitor_change_popup_visible' | 'layer_change_visibility' | 'hamburger_menu_node_change_visibility' | 'hamburger_menu_change_open_state' | 'hamburger_menu_group_change_expanded' | 'canvas_component_change_visibility' | 'message_card_change_show_state' | 'message_card_show' | 'message_card_hide' | 'message_card_create_temporary' | 'message_card_destroy_temporary' | 'tts_play_voice' | 'tts_realtime_stream' | 'background_thread_start' | 'background_thread_pause' | 'background_thread_stop' | 'ai_agent_activate' | 'ai_agent_hide' | 'ai_agent_wake' | 'ai_agent_activate_and_send_user_message' | 'ai_agent_activate_and_inject_dialogue' | 'ai_agent_inject_hidden_state_message' | 'ai_agent_activate_and_inject_assistant_message' | 'system_open_webpage' | 'ability_enable' | 'ability_stop' | 'cloud_form_show_dialog' | 'cloud_form_collect_field' | 'cloud_form_submit' | 'cloud_form_reset' | 'hit_analytics_event' | 'popup_user_form_show_dialog' | 'logic_random_number' | 'logic_random_color' | 'logic_current_time' | 'logic_random_pick_string' | 'logic_random_pick_number' | 'logic_random_pick_boolean' | 'logic_random_pick_enum' | 'logic_random_pick_color' | 'logic_random_pick_css_color' | 'logic_random_pick_from_recommend_options' | 'visualization_controller_pop' | 'visualization_controller_hide' | 'visualization_controller_close_all' | 'ai_check_take_photo' | 'ai_check_run' | 'ray_hitter_activate' | 'ray_hitter_deactivate';
 export declare class VrActionTypeDefine {
     static readonly SYSTEM_COMMON_WAIT: VrActionType;
     static readonly COMPONENT_GENERAL_CHANGE_VISIBILITY: VrActionType;
@@ -191,8 +262,12 @@ export declare class VrActionTypeDefine {
     static readonly FLOW_ENTER: VrActionType;
     static readonly FLOW_EXIT: VrActionType;
     static readonly SEND_BROADCAST: VrActionType;
+    /** @deprecated 状态胶囊已退役（plan §1.19），统一改用 运行态.快照/恢复快照（State.snapshot/restoreSnapshot 静态方法）。
+     * 保留仅为向后兼容运行老数据（plan §1.23）：新编辑器不再露出，迁移器静默尽力转（plan §1.41）。 */
     static readonly SYSTEM_STATE_SCOPE_CREATE: VrActionType;
+    /** @deprecated 同上，改用 运行态.快照/恢复快照。 */
     static readonly SYSTEM_STATE_SCOPE_SWITCH: VrActionType;
+    /** @deprecated 同上，改用 运行态.快照/恢复快照。 */
     static readonly SYSTEM_STATE_SCOPE_DESTROY: VrActionType;
     static readonly MONITOR_CHANGE_ENABLED: VrActionType;
     static readonly MONITOR_SWITCH_ACTIVE_TAB: VrActionType;
@@ -251,6 +326,10 @@ export declare class VrActionTypeDefine {
     static readonly VISUALIZATION_CONTROLLER_POP: VrActionType;
     static readonly VISUALIZATION_CONTROLLER_HIDE: VrActionType;
     static readonly VISUALIZATION_CONTROLLER_CLOSE_ALL: VrActionType;
+    static readonly AI_CHECK_TAKE_PHOTO: VrActionType;
+    static readonly AI_CHECK_RUN: VrActionType;
+    static readonly RAY_HITTER_ACTIVATE: VrActionType;
+    static readonly RAY_HITTER_DEACTIVATE: VrActionType;
 }
 export declare class VrActionParamsAbilityEnable {
     abilityId: string;
@@ -862,6 +941,54 @@ export declare class VrActionParamsLogicRandomPickCssColor {
 export declare class VrActionParamsLogicRandomPickFromRecommendOptions {
     target: XrVariableTarget;
 }
+/**
+ * 相机拍摄模式
+ * - raw: 原始帧——不含装修组件等空间叠加物。
+ *        AR = 纯物理摄像头帧；VR = 隐藏全部装修组件后的渲染画面（场景本体保留）
+ * - with_overlay: 含叠加物帧——装修组件真实显示在照片里
+ */
+export declare type CameraCaptureMode = 'raw' | 'with_overlay';
+export declare class CameraCaptureModeDefine {
+    static readonly RAW: CameraCaptureMode;
+    static readonly WITH_OVERLAY: CameraCaptureMode;
+}
+export declare class VrActionParamsAiCheckTakePhoto {
+    target: XrVariableTarget;
+    captureMode: CameraCaptureMode;
+}
+/**
+ * AI 检查的图片来源
+ * - camera: 执行时即时截取相机画面（可配 cameraCaptureMode）
+ * - album: 弹出相册/文件选择器由用户选一张（建议挂在点击类触发器下，浏览器要求用户手势链）
+ * - image_variable: 读取图片变量中的值（由「拍照」action 提前写入，可一照多检）
+ */
+export declare type AiCheckImageSourceKind = 'camera' | 'album' | 'image_variable';
+export declare class AiCheckImageSourceKindDefine {
+    static readonly CAMERA: AiCheckImageSourceKind;
+    static readonly ALBUM: AiCheckImageSourceKind;
+    static readonly IMAGE_VARIABLE: AiCheckImageSourceKind;
+}
+/**
+ * AI 检查 - AI图像检查（同步阻塞：拿到结果才继续执行剩余 actionList）
+ * 按 ruleId 从 vrContentData.aiCheckRuleList 取规则，把规则内容随请求带给后端检查端点。
+ * 结果写入最多三个变量目标（key 为空 = 不写该项）。
+ * 错误语义：网络/服务失败 → passed=false / score=0 / reason='检查失败：…'；相册取消 → 不写任何变量。
+ */
+export declare class VrActionParamsAiCheckRun {
+    ruleId: string;
+    imageSource: AiCheckImageSourceKind;
+    cameraCaptureMode: CameraCaptureMode;
+    sourceVariable: XrVariableTarget;
+    passedTarget: XrVariableTarget;
+    scoreTarget: XrVariableTarget;
+    reasonTarget: XrVariableTarget;
+}
+export declare class VrActionParamsRayHitterActivate {
+    rayHitterId: string;
+}
+export declare class VrActionParamsRayHitterDeactivate {
+    rayHitterId: string;
+}
 /**
  * 弹出可视化控制器：内容内联在 action 里（图标+标题+正文+多个按钮）。
  * 再次执行同一 action = 再加一个实例（除非 keepOnlyLatestForKey）。

package/dist/src/model/vr/vr-content-data.d.ts

@@ -25,6 +25,7 @@ import { XrVirtualFloor } from './xr-virtual-floor';
 import { VrNavigationAdConfig } from '../../model/vr/vr-navigation-ad-config';
 import { VrAdChannel } from '../../model/vr/vr-ad-channel';
 import { XrAiAgent } from '../../model/vr/xr-ai-agent';
+import { XrRayHitter } from './xr-ray-hitter';
 import { XrBackgroundThread } from '../../model/vr/xr-background-thread';
 import { XrBroadcastChannel } from '../../model/vr/xr-broadcast-channel';
 import { XrCameraDollyPath } from '../../model/vr/xr-camera-dolly-path';
@@ -32,6 +33,7 @@ import { XrPrepareSettings } from '../../model/vr/xr-prepare';
 import { XrAbility, XrAbilityGroup } from '@/model/vr/xr-ability';
 import { XrHamburgerMenu } from './xr-hamburger-menu';
 import { LanguageType } from '../general/multi-language-str';
+import { XrProgramScene, XrCustomClass, XrProgramFunction, XrEntityHandlerBinding } from './xr-program';
 /**
  * VR内容数据构建器
  */
@@ -191,6 +193,7 @@ export declare class VrContentData {
     trimmerList: VrTrimmerData[];
     spaceFenceList: XrSpaceFence[];
     spaceFenceGroupList: XrSpaceFenceGroup[];
+    rayHitterList: XrRayHitter[];
     abilityList: XrAbility[];
     abilityGroupList: XrAbilityGroup[];
     vrFlowList: VrFlow[];
@@ -221,5 +224,9 @@ export declare class VrContentData {
     unityNavigationParams: UnityNavigationParams;
     xrVirtualFloorList: XrVirtualFloor[];
     navigationAdConfigList: VrNavigationAdConfig[];
+    programSceneList: XrProgramScene[];
+    customClassList: XrCustomClass[];
+    sharedFunctionList: XrProgramFunction[];
+    entityHandlerBindingList: XrEntityHandlerBinding[];
     constructor(mpModelId: string, vrUnicode: string);
 }

package/dist/src/model/vr/vr-signal.d.ts

@@ -1,7 +1,7 @@
 import { XrAnyAction } from './vr-action';
 import { VRTalkBaseData } from '../general/vrtalk-base-data';
 import { XrVariable } from './xr-logic';
-export declare type VrSignalType = 'component_created' | 'component_show' | 'component_hide' | 'click' | 'mouse_enter' | 'mouse_leave' | 'play_start' | 'play_finish' | 'enter' | 'leave' | 'panel_button_click' | 'panel_answer_correct' | 'panel_answer_wrong' | 'variable_modified' | 'expression_watcher_triggered' | 'monitor_component_click' | 'sticker_activated' | 'sticker_deactivated' | 'vr_started' | 'all_components_created' | 'broadcast_channel_message';
+export declare type VrSignalType = 'component_created' | 'component_show' | 'component_hide' | 'click' | 'mouse_enter' | 'mouse_leave' | 'play_start' | 'play_finish' | 'enter' | 'leave' | 'panel_button_click' | 'panel_answer_correct' | 'panel_answer_wrong' | 'variable_modified' | 'expression_watcher_triggered' | 'monitor_component_click' | 'sticker_activated' | 'sticker_deactivated' | 'vr_started' | 'all_components_created' | 'broadcast_channel_message' | 'ray_hitter_top_triggered' | 'ray_hitter_bottom_triggered';
 export declare class VrSignalTypeDefine {
     static readonly COMPONENT_CREATED: VrSignalType;
     static readonly COMPONENT_SHOW: VrSignalType;
@@ -24,8 +24,10 @@ export declare class VrSignalTypeDefine {
     static readonly VR_STARTED: VrSignalType;
     static readonly ALL_COMPONENTS_CREATED: VrSignalType;
     static readonly BROADCAST_CHANNEL_MESSAGE: VrSignalType;
+    static readonly RAY_HITTER_TOP_TRIGGERED: VrSignalType;
+    static readonly RAY_HITTER_BOTTOM_TRIGGERED: VrSignalType;
 }
-export declare type VrSignalSource = 'component_tag' | 'component_2d_text' | 'component_2d_advertisement' | 'component_2d_video' | 'component_2d_image' | 'component_2d_panel' | 'component_3d_box' | 'component_3d_model' | 'logic_variable' | 'logic_expression_watcher' | 'space_fence' | 'space_fence_group' | 'monitor_component' | 'sticker' | 'broadcast' | 'ai_agent' | 'system';
+export declare type VrSignalSource = 'component_tag' | 'component_2d_text' | 'component_2d_advertisement' | 'component_2d_video' | 'component_2d_image' | 'component_2d_panel' | 'component_3d_box' | 'component_3d_model' | 'ray_hitter' | 'logic_variable' | 'logic_expression_watcher' | 'space_fence' | 'space_fence_group' | 'monitor_component' | 'sticker' | 'broadcast' | 'ai_agent' | 'system';
 export declare class VrSignalSourceDefine {
     static readonly COMPONENT_TAG: VrSignalSource;
     static readonly COMPONENT_2D_TEXT: VrSignalSource;
@@ -35,6 +37,7 @@ export declare class VrSignalSourceDefine {
     static readonly COMPONENT_2D_PANEL: VrSignalSource;
     static readonly COMPONENT_3D_BOX: VrSignalSource;
     static readonly COMPONENT_3D_MODEL: VrSignalSource;
+    static readonly RAY_HITTER: VrSignalSource;
     static readonly LOGIC_VARIABLE: VrSignalSource;
     static readonly LOGIC_CONDITION_WATCHER: VrSignalSource;
     static readonly SPACE_FENCE: VrSignalSource;

package/dist/src/model/vr/vr-ui-icon-layout.d.ts

@@ -37,11 +37,18 @@ export declare const VR_MAIN_BAR_DEFAULT: VrUiIconItem[];
  * 登录入口已挪到 main-bar 的 account） */
 export declare const VR_INFO_BAR_DEFAULT: VrUiIconItem[];
 /**
- * AR 主栏默认目录（AR = player 手机端去掉相机类：无 fov/d3/floorplan/floor）。
- * AR 无默认胶囊成员（capsule 默认空，用户可自行拖入）。
+ * AR 主栏默认目录 = **竖向导轨**（AR 专属功能，player 手机端没有的才独立设计成图标+小字导轨）。
+ *  - graffiti/discover/capture：AR 专属功能；
+ *  - monitors：展开为各「悬浮式」监控面板贴底 tab（弹出式监控入口另在 info 栏 popupInfoBarMonitors）。
+ * 共有的 flow / 消息中心 / AI 由**底部栈**自动呈现（flow 步骤栏、消息横滑、AI orb），不占栏位；
+ * 相机类(fov/d3/floorplan/floor) AR 无；本轮不含 measure。placement 对导轨仅表达显隐/顺序。
  */
 export declare const AR_MAIN_BAR_DEFAULT: VrUiIconItem[];
-/** AR info 栏默认目录（监控移到 info 栏；AR 本就全屏，无 fullscreen；staff 已废弃移除） */
+/**
+ * AR info 栏默认目录（右上角工具切换）：小地图 / 音频中心 / 全局静音 / 汉堡 / 账户。
+ * 对齐 player 顶部/主栏的工具位；AR 全屏无 fullscreen；staff 已废弃移除。
+ * 弹出式监控面板入口由 popupInfoBarMonitors 独立呈现，不占本目录。
+ */
 export declare const AR_INFO_BAR_DEFAULT: VrUiIconItem[];
 /** 兼容导出：派生 key 数组（旧消费方若按 key 列表使用仍可用） */
 export declare const VR_MAIN_BAR_ICON_KEYS: string[];

package/dist/src/model/vr/xr-ai-agent-tool-catalog.d.ts

@@ -16,7 +16,7 @@ import type { XrAiAgent } from './xr-ai-agent';
  *   - 其余值 = agent 上对应 useXxxList / skillPromptList 非空
  * 资源未就绪时：该工具在后端本就不会暴露，编辑器里开关置灰（开了也无意义）。
  */
-export declare type XrAiAgentToolRequireKey = 'useComponentList' | 'useTargetList' | 'useFovList' | 'useVariableList' | 'useStickerList' | 'useSpaceFenceList' | 'useSpaceFenceGroupList' | 'useBackgroundThreadList' | 'useCameraDollyPathList' | 'useAbilityList' | 'useKnowledgeBaseList' | 'useContentCardList' | 'useCloudFormList' | 'useMessageCardList' | 'useMonitorList' | 'useAssetPointMarkList' | 'useAssetVolumeMarkList' | 'skillPromptList' | 'enableVoiceOutput' | 'associateAllAssetPointMarks' | 'associateAllAssetVolumeMarks' | 'positionXConnected';
+export declare type XrAiAgentToolRequireKey = 'useComponentList' | 'useTargetList' | 'useFovList' | 'useVariableList' | 'useStickerList' | 'useSpaceFenceList' | 'useSpaceFenceGroupList' | 'useBackgroundThreadList' | 'useCameraDollyPathList' | 'useAbilityList' | 'useKnowledgeBaseList' | 'useContentCardList' | 'useCloudFormList' | 'useMessageCardList' | 'useMonitorList' | 'useAssetPointMarkList' | 'useAssetVolumeMarkList' | 'useRayHitterList' | 'useAiCheckRuleList' | 'skillPromptList' | 'enableVoiceOutput' | 'associateAllAssetPointMarks' | 'associateAllAssetVolumeMarks' | 'positionXConnected';
 export interface XrAiAgentToolDef {
     key: string;
     requires?: XrAiAgentToolRequireKey[];

package/dist/src/model/vr/xr-ai-agent.d.ts

@@ -73,6 +73,14 @@ export declare class XrAiAgentUseAssetPointMark {
     assetPointMarkId: string;
     description: string;
 }
+export declare class XrAiAgentUseRayHitter {
+    rayHitterId: string;
+    description: string;
+}
+export declare class XrAiAgentUseAiCheckRule {
+    aiCheckRuleDataKey: string;
+    description: string;
+}
 export declare class XrAiAgentUseAssetVolumeMark {
     assetVolumeMarkId: string;
     description: string;
@@ -138,6 +146,8 @@ export declare class XrAiAgent extends VRTalkBaseData {
     useMonitorList: XrAiAgentUseMonitor[];
     useAssetPointMarkList: XrAiAgentUseAssetPointMark[];
     useAssetVolumeMarkList: XrAiAgentUseAssetVolumeMark[];
+    useRayHitterList: XrAiAgentUseRayHitter[];
+    useAiCheckRuleList: XrAiAgentUseAiCheckRule[];
     associateAllAssetPointMarks: boolean;
     associateAllAssetVolumeMarks: boolean;
 }