@gct-paas/excel 0.1.35 → 0.1.37-beta.0

package/dist/src/nocode-base/src/runtime/runtime-dependency-service.d.ts

@@ -0,0 +1,82 @@
+import { FormStateChange, RuntimeFormStateStore } from './runtime-form-state-store';
+import { RuntimeAsyncTaskCoordinator } from './async-task-coordinator';
+/** 条件输出按设计控件 + 类型 + Store 稳定行路径区分；二维行也使用自己的稳定身份。 */
+export declare function getRuntimeDependencyOutputKey(widgetId: string, type: string, rowPath: string): string;
+/** 业务身份与数据路径分别保存：不同模型字段不能靠相同 fieldId 识别。 */
+export interface RuntimeDependencyFieldReference {
+    modelKey?: string;
+    subModelKey?: string;
+    fieldId?: string;
+    subFieldKey?: string;
+    /** 必须与 Store 变更路径一致；不能直接在旧路径前拼接模型名。 */
+    dataPath: string;
+}
+/** 异步规则在提交结果前必须检查有效性，任务返回后的检查无法撤销已经写入的数据。 */
+export interface RuntimeDependencyExecution {
+    signal: AbortSignal;
+    isCurrent(): boolean;
+    /** 原子替换本规则的全部条件输出，自动清除已经删除的行；过期执行不能发布。 */
+    replaceOutputs(values: ReadonlyMap<string, unknown>): boolean;
+}
+export interface RuntimeDependencyEffect {
+    id: string;
+    targetField?: RuntimeDependencyFieldReference;
+    sheetId?: string;
+    /** 普通字段依赖；空数组表示常量表达式，仅初始化和结构变化时执行。 */
+    sourceFields?: RuntimeDependencyFieldReference[];
+    /** 目标子表行/列结构依赖，只匹配该结构或其父路径，不匹配普通单元格写入。 */
+    structureFields?: string[];
+    run(change: FormStateChange, execution: RuntimeDependencyExecution): void | Promise<void>;
+}
+/**
+ * 实例级联动调度器，统一执行 formulaExpr、条件属性及赋值 effect。
+ * 按 Store 路径筛选规则，同一微任务合并变更，公式产生的新变更继续进入下一轮。
+ * 排队阶段就登记 required 任务，提交会等待整条联动链；过期与销毁的执行不可回写。
+ */
+export declare class RuntimeDependencyService {
+    private readonly formState;
+    private readonly asyncTasks;
+    private readonly effects;
+    private readonly pendingChanges;
+    private readonly executions;
+    /** 每条规则拥有自己的输出集合，替换和注销规则时同时释放。 */
+    private readonly outputKeys;
+    /** 条件输出只有本服务可写，组件与校验通过 getOutput 读取。 */
+    private readonly outputs;
+    private scheduled;
+    private disposed;
+    /** 不收敛的公式链不能无限占用微任务，也不能被提交当作成功。 */
+    private formulaRounds;
+    private readonly unsubscribe;
+    constructor(formState: RuntimeFormStateStore, asyncTasks: RuntimeAsyncTaskCoordinator, 
+    /** 打印副本只读取已计算的条件结果，不注册或重新执行业务规则。 */
+    initialOutputs?: Readonly<Record<string, unknown>>);
+    register(effect: RuntimeDependencyEffect): () => void;
+    private replaceOutputs;
+    private clearOutputs;
+    getOutput<T = unknown>(key: string): T | undefined;
+    /** 条件结果与数据一起进入打印快照，未访问的 Sheet 不依赖控件挂载重新计算。 */
+    getOutputSnapshot(): Record<string, unknown>;
+    /** 调试查询只描述调度状态，不返回规则执行函数或可写的条件结果引用。 */
+    getDebugSnapshot(): {
+        scheduled: boolean;
+        pendingChangeCount: number;
+        runningRuleIds: string[];
+        rules: {
+            id: string;
+            targetField?: RuntimeDependencyFieldReference;
+            sheetId?: string;
+            /** 普通字段依赖；空数组表示常量表达式，仅初始化和结构变化时执行。 */
+            sourceFields?: RuntimeDependencyFieldReference[];
+            /** 目标子表行/列结构依赖，只匹配该结构或其父路径，不匹配普通单元格写入。 */
+            structureFields?: string[];
+        }[];
+        outputs: Record<string, unknown>;
+    };
+    runAll(source?: FormStateChange['source']): Promise<void>;
+    dispose(): void;
+    private matches;
+    private cancelExecution;
+    private schedule;
+    private runEffects;
+}

package/dist/src/nocode-base/src/runtime/runtime-field-initializer.d.ts

@@ -0,0 +1,26 @@
+import { IBasicInfoItem } from '../types';
+import { RuntimeInstanceRecord } from './runtime-instance-registry';
+type InitializerMetadata = {
+    materialNo?: string;
+    params?: string;
+    instanceStatus?: string;
+};
+export declare class RuntimeFieldInitializer {
+    private readonly record;
+    private readonly info;
+    private readonly metadata;
+    private readonly initialized;
+    private readonly tasks;
+    private readonly requests;
+    private suite?;
+    private disposed;
+    private scheduled;
+    private readonly unsubscribe;
+    constructor(record: RuntimeInstanceRecord, info: IBasicInfoItem, metadata: InitializerMetadata);
+    /** 初次加载等待全部目标；失败保留在任务中心，不能把未完成的默认值当成可提交数据。 */
+    initialize(): Promise<void>;
+    private request;
+    private readDefault;
+    dispose(): void;
+}
+export {};

package/dist/src/nocode-base/src/runtime/runtime-field-registry.d.ts

@@ -0,0 +1,90 @@
+import { BaseCoreComponent } from '../types';
+import { BusinessFieldIdentity } from './field-identity';
+import { RuntimeFieldLocation } from './runtime-context';
+export interface RuntimeFieldDescriptor extends RuntimeFieldLocation {
+    businessKey: string;
+    /** 实际写入 Store 的字段键，关联字段可能不同于业务 fieldId。 */
+    dataFieldId: string;
+    pathPattern: string;
+    widget?: BaseCoreComponent.BasicSchema;
+}
+export interface RuntimeWidgetDescriptor {
+    sheetId: string;
+    nodeId: string;
+    widget: BaseCoreComponent.BasicSchema;
+    /** 布尔/枚举附属字段的启用条件；初始化扫描时收集，校验不等待父组件挂载。 */
+    referenceInfo?: RuntimeWidgetReferenceInfo;
+}
+export interface RuntimeWidgetReferenceInfo {
+    belongFieldId: string;
+    optionValue: any;
+    multiple?: boolean;
+    /** 最外层选择字段决定取普通行还是二维交叉子行，附属字段继承相同数据范围。 */
+    scopeFieldId?: string;
+    /** 嵌套引用字段须同时满足外层选项。 */
+    parent?: RuntimeWidgetReferenceInfo;
+}
+/** 元数据阶段输出控件归属与编译资格；展开单元格只查询，不重复编译规则。 */
+export interface RuntimeWidgetMetadata extends RuntimeWidgetDescriptor {
+    compile: boolean;
+}
+/** 初始化阶段扫描一次得到的完整位置元数据，包含检验表内部 value_ 字段。 */
+export interface RuntimeFieldMetadata {
+    fields: Array<RuntimeFieldLocation & {
+        widget?: BaseCoreComponent.BasicSchema;
+    }>;
+    widgets: RuntimeWidgetMetadata[];
+}
+/** 校验路径描述的是一个具体数据位置；动态行不重复注册静态字段。 */
+export interface RuntimeValidationLocation {
+    field: RuntimeFieldDescriptor;
+    rowKey?: string;
+}
+export interface RuntimeFieldQuery extends BusinessFieldIdentity {
+    subFieldKey?: string;
+    sheetId?: string;
+}
+/**
+ * 一个多 Sheet 实例只有一份字段注册表。
+ * 只持有模板字段/控件的位置索引，供校验、联动、分页失效和导航查询。
+ * 不保存填报数据、动态行实例或错误状态，也不负责操作 DOM。
+ */
+export declare class RuntimeFieldRegistry {
+    /** 主表真实数据字段（关联模型使用 fieldLink），与业务字段索引分别建立。 */
+    private readonly mainFieldsByDataKey;
+    private readonly byBusinessKey;
+    private readonly widgets;
+    private readonly widgetsById;
+    private readonly fieldsByNode;
+    /** 第一层是子表 key（主表为空串），第二层是完整字段 key，避免前缀匹配。 */
+    private readonly fieldsByTable;
+    /** 只消费已经生成的元数据并建立索引，不扫描 dataCenter 或补齐业务特例。 */
+    constructor(metadata: RuntimeFieldMetadata);
+    allWidgets(): readonly RuntimeWidgetDescriptor[];
+    /**
+     * 从已经建立的索引取得调试快照，不重新扫描 dataCenter，也不增加一份字段缓存。
+     * 保留内部 value_、引用位置以及真实 dataFieldId/pathPattern，便于核对模型与数据路径。
+     * 字段和控件配置均深拷贝，控制台修改快照不会影响注册表或正在渲染的控件。
+     */
+    getDebugSnapshot(): {
+        fields: Array<RuntimeFieldLocation & {
+            widget?: BaseCoreComponent.BasicSchema;
+        }>;
+        widgets: RuntimeWidgetMetadata[];
+        fieldCount: number;
+        businessFieldCount: number;
+        widgetCount: number;
+        compiledWidgetCount: number;
+    };
+    /** 打印消费现有位置索引的副本，不重新扫描节点，也不持有原实例的控件引用。 */
+    getMetadataSnapshot(): RuntimeFieldMetadata;
+    getByBusinessKey(businessKey: string): RuntimeFieldDescriptor | undefined;
+    findByPath(path: string): RuntimeFieldDescriptor[];
+    /** 节点/批注的业务字段查询；不向调用方暴露字段数组让其自行匹配。 */
+    findField(query: RuntimeFieldQuery): RuntimeFieldDescriptor | undefined;
+    getByNode(nodeId: string, sheetId?: string): RuntimeFieldDescriptor | undefined;
+    /** 校验与批注的位置统一包含模型、字段和稳定行键，不解析数字行列下标。 */
+    resolveValidationPath(path: string, sheetId?: string): RuntimeValidationLocation | undefined;
+    private findPlaced;
+    findWidgetById(widgetId: string): RuntimeWidgetDescriptor | undefined;
+}

package/dist/src/nocode-base/src/runtime/runtime-field-rows.d.ts

@@ -0,0 +1,7 @@
+import { RuntimeInstanceRecord } from './runtime-instance-registry';
+export interface RuntimeDataTarget {
+    row: Record<string, any>;
+    parentRow?: Record<string, any>;
+}
+/** 公式、赋值、条件和校验共用数据位置枚举，不依赖固定表展开控件是否挂载。 */
+export declare function listRuntimeFieldRows(record: RuntimeInstanceRecord, subFieldKey: string | undefined, targetFieldId: string): RuntimeDataTarget[];

package/dist/src/nocode-base/src/runtime/runtime-field-state.d.ts

@@ -0,0 +1,15 @@
+import { IBasicInfoItem } from '../types';
+import { RuntimeInstanceRecord } from './runtime-instance-registry';
+export type RuntimeFieldStateInfo = Pick<IBasicInfoItem, 'renderModeType' | 'modelKey' | 'formType' | 'bpmnType' | 'bpmnFieldAuthMap'> & Partial<Pick<IBasicInfoItem, 'annSwitchStatus' | 'renderPurpose'>>;
+/** Core 提供业务规则，这里统一合并到静态配置；二维交叉字段使用所属父行的业务状态。 */
+export declare function resolveRuntimeFieldProps(record: RuntimeInstanceRecord, props: Record<string, any>, widgetId: string, row?: Record<string, any>, parentRow?: Record<string, any>): {
+    [x: string]: any;
+};
+/** 只读展示方式、禁用和校验 blocked 由同一结果派生，UI 与未挂载字段使用相同权限语义。 */
+export declare function resolveRuntimeFieldState(props: Record<string, any>, info: RuntimeFieldStateInfo): {
+    displayStatus: string;
+    disabled: boolean;
+    blocked: boolean;
+    required: boolean;
+    keepExceptionHighlight: boolean | undefined;
+};

package/dist/src/nocode-base/src/runtime/runtime-form-state-store.d.ts

@@ -0,0 +1,132 @@
+import { RuntimeTableRelation } from './table-row-identity';
+/** 数据变更来源；订阅方可据此区分用户输入、计算结果和初始化恢复。 */
+export type FormStateMutationSource = 'user' | 'formula' | 'autofill' | 'async' | 'restore' | 'system';
+export interface FormStateChange {
+    /** 本次提交后的实例数据版本。 */
+    revision: number;
+    /** 本次事务修改的业务路径，已自动去重。 */
+    paths: string[];
+    /** 整个事务的变更来源。 */
+    source: FormStateMutationSource;
+}
+export type FormStateSubscriber = (change: FormStateChange) => void;
+/**
+ * 一个多 Sheet 实例只创建一个 FormStateStore。
+ *
+ * 对外暴露深层受控视图，字段赋值、对象属性修改和数组原地操作都会统一生成
+ * revision、dirty 状态和字段路径事件，供联动、分页和自动保存订阅。
+ * 字段组件通过 useRuntimeRowState 的显式写入口声明来源；Proxy 保留深层监听和数组操作能力。
+ */
+export declare class RuntimeFormStateStore {
+    private readonly tableRelations;
+    /**
+     * 提供给业务代码和字段组件的受控数据视图，由实例记录持有唯一 Store。
+     *
+     * 它是在 reactiveState 外再包的一层 Store Proxy。读取的数据与 reactiveState 完全相同，
+     * 写属性、删属性和修改数组时会额外生成字段路径、revision、dirty 和订阅事件。
+     */
+    readonly state: Record<string, any>;
+    /**
+     * Vue reactive() 创建的内部响应式对象，是整份实例数据的基础存储。
+     *
+     * Store 自己执行 patch/replace 时会直接修改它，并在 mutate() 中显式登记路径，避免再经过
+     * state Proxy 重复记录同一次变更。业务模块不应直接持有或修改该对象。
+     */
+    private readonly reactiveState;
+    /** 每次成功提交一批变更递增一次，保存和提交用它判断快照是否过期。 */
+    revision: number;
+    /** 是否存在尚未保存的变更；restore 来源不会把实例标记为脏。 */
+    dirty: boolean;
+    /** 当前嵌套事务深度；只有最外层事务结束时才递增 revision 并通知订阅方。 */
+    private mutationDepth;
+    /** 当前事务累计的变更路径，Set 保证同一路径只通知一次。 */
+    private pendingPaths;
+    /** 最外层事务的变更来源，嵌套写入沿用该来源。 */
+    private pendingSource;
+    /** 联动、分页失效、自动保存等实例服务登记的变更监听器。 */
+    private readonly subscribers;
+    /** 用户主动修改过的业务路径，供公式和自动填充执行“不覆盖用户输入”策略。 */
+    private readonly userModifiedPaths;
+    /**
+     * 同一个目标对象可以因为所在业务位置不同而拥有不同 basePath。
+     * 此缓存保证相同 target + basePath 始终复用同一个 Proxy，避免组件重复渲染时不断创建视图。
+     */
+    private readonly scopedViews;
+    /** 从 Store Proxy 反查它包装的 Vue 响应式目标，写入前用于去掉重复的 Store 代理层。 */
+    private readonly viewTargets;
+    /** 视图的业务路径；行组件、上传和自动填充复用它，避免各自拼接下标路径。 */
+    private readonly viewPaths;
+    /** Vue 代理和原始对象可能被不同业务模块持有，按原始对象记录同一个业务位置。 */
+    private readonly objectPaths;
+    /** 由实例业务索引提供的子表字段，只有这些数组和二维行数组需要补齐行身份。 */
+    private readonly subtableFields;
+    constructor(initialState: Record<string, any>, subtableFields?: Iterable<string>, tableRelations?: readonly RuntimeTableRelation[]);
+    /**
+     * 为主表或子表行创建受控数据视图。
+     * basePath 为空时 `field` 的变更路径就是 `field`；子表行为
+     * `subField.rowKey.field`，可直接匹配 RuntimeFieldRegistry 的路径规则。
+     *
+     * 读取嵌套对象时会按需继续创建 scoped view，所以任意深度的普通赋值都不会绕开 Store。
+     */
+    createScopedView(target: Record<string, any>, basePath?: string): Record<string, any>;
+    /** 返回当前对象的业务位置；空字符串表示主表，undefined 表示对象尚未绑定到 Store。 */
+    getObjectPath(target: Record<string, any>): string | undefined;
+    /** 所有组件使用同一入口生成字段路径，缺少受控上下文时立即报错。 */
+    getFieldPath(target: Record<string, any>, fieldKey: string): string;
+    /** 关联字段 _OPCT 容器沿用所属业务行身份，不在容器内重新生成一个行键。 */
+    getRowKey(target: Record<string, any>, subFieldKey: string): string;
+    /** 写入主表顶层字段。 */
+    setField(fieldKey: string, value: any, source?: FormStateMutationSource): void;
+    /**
+     * 写入任意行对象中的字段。
+     * target 决定真实写入对象，changePath 决定订阅方看到的业务位置，两者可以不同。
+     */
+    setObjectField(target: Record<string, any>, fieldKey: string, value: any, source?: FormStateMutationSource, changePath?: string): void;
+    /** 合并当前行的一组关联字段，累计稳定业务路径，只提交一次变更。 */
+    patchObjectFields(target: Record<string, any>, values: Record<string, any>, source: FormStateMutationSource): void;
+    /** 合并一组顶层字段，保留未出现在 values 中的现有字段。 */
+    patch(values: Record<string, any>, source?: FormStateMutationSource): void;
+    /**
+     * 用新对象整体替换实例数据，删除旧对象中多余的顶层字段。
+     * 草稿/接口恢复后会清空用户修改标记；restore 来源同时恢复为非脏状态。
+     */
+    replace(values: Record<string, any>, source?: FormStateMutationSource): void;
+    /**
+     * 将多次深层写入合并成一次变更提交。
+     * 嵌套事务只累计路径，最外层 finally 统一递增 revision 并通知订阅方。
+     */
+    transaction<T>(source: FormStateMutationSource, callback: (state: Record<string, any>) => T): T;
+    /** 登记路径和来源后执行底层修改，是所有显式 Store 写方法的统一入口。 */
+    mutate<T>(paths: string[], source: FormStateMutationSource, callback: () => T): T;
+    /** 查询某业务路径是否曾由用户主动修改。 */
+    isUserModified(path: string): boolean;
+    /** 将异步上传等最终由用户发起的写入补记为用户修改。 */
+    markUserModified(path: string): void;
+    /** 清除指定路径的用户修改标记，允许“不覆盖”策略重新赋值。 */
+    clearUserModified(path: string): void;
+    /**
+     * 只允许与保存快照相同的版本清除 dirty。
+     * 保存期间若又发生编辑，旧请求成功也不能把新修改标记为已保存。
+     */
+    markClean(expectedRevision?: number): boolean;
+    /**
+     * 订阅实例数据提交事件；返回的函数只注销当前订阅。
+     * 一次 transaction 无论修改多少字段，订阅方都只会收到一次回调。
+     */
+    subscribe(subscriber: FormStateSubscriber): () => boolean;
+    /** 实例销毁时释放订阅和临时状态；数据对象的生命周期由实例上下文结束。 */
+    dispose(): void;
+    /** 提交当前事务积累的路径，更新版本和脏状态，然后同步通知实例服务。 */
+    private commit;
+    /** 如果值是 Store 创建的 scoped view，返回它实际包装的 Vue 响应式目标。 */
+    private unwrap;
+    /** 内部批量赋值工具；调用方已经在 mutate() 中登记本批次路径。 */
+    private assignValues;
+    /**
+     * 所有写入口共用的表格身份边界：整表恢复/回填、数组插入、二维子行替换均在通知前补齐。
+     * 只处理业务索引声明的表格及 _2DTABLE_，不把多选值、上传文件等数组当作表格。
+     */
+    private ensureIncomingRowKeys;
+    /** 数组中的业务行使用稳定身份；普通嵌套对象仍按属性路径访问。 */
+    private getChildPath;
+}

package/dist/src/nocode-base/src/runtime/runtime-instance-controller.d.ts

@@ -0,0 +1,80 @@
+import { RuntimeInstanceContext } from './runtime-context';
+import { RuntimePersistenceCoordinator, RuntimeSubmissionResult, RuntimeSubmissionValidationResult } from './runtime-persistence-coordinator';
+import { RuntimeSheetService } from './runtime-sheet-service';
+export type RuntimeEditorFlusher = () => void | Promise<void>;
+export interface ActivateRuntimeSheetOptions {
+    /** 切换前记录的当前 Sheet 滚动位置。 */
+    scrollTop?: number;
+}
+export interface RuntimeInstanceControllerOptions {
+    context: RuntimeInstanceContext;
+    /** 服务均由实例记录显式注入，不通过 context 查找，也不重新创建。 */
+    sheetService: RuntimeSheetService;
+    persistenceCoordinator: RuntimePersistenceCoordinator;
+    /** 实例级业务校验和转换由工厂注入；缺少结果时提交失败，不能默认放行。 */
+    onValidate: () => RuntimeSubmissionValidationResult | undefined | Promise<RuntimeSubmissionValidationResult | undefined>;
+    /** 将共享 formState 转换为业务后端需要的提交结构。 */
+    onGetSubmitData: (formState: Record<string, any>) => Record<string, any>;
+    /** 校验失败后定位首个错误所属 Sheet。 */
+    onValidationFailed?: (result: RuntimeSubmissionValidationResult) => void | Promise<unknown>;
+}
+/**
+ * 一个表单实例对应一个控制器。
+ *
+ * 控制器统一查询 Sheet、收口编辑器、计算分页、切换活动 Sheet 和准备提交。
+ * 页面只处理 DOM 的失焦、滚动和聚焦；业务规则由工厂注入。
+ * 服务的创建及销毁仍归 Registry，Controller 只使用已有服务。
+ */
+export declare class RuntimeInstanceController {
+    readonly context: RuntimeInstanceContext;
+    private readonly persistenceCoordinator;
+    private readonly sheets;
+    private readonly viewState;
+    /** 初始化和模式切换的真实准备任务；不再用固定时间窗口推断准备是否结束。 */
+    private readonly viewPreparations;
+    private viewPreparationSequence;
+    private disposed;
+    private switchSequence;
+    private readonly editorFlushers;
+    private readonly onValidate;
+    private readonly onGetSubmitData;
+    private readonly onValidationFailed?;
+    /** 合并整个 UI 提交流程，避免并发点击重复执行错误导航。 */
+    private preparingSubmission?;
+    constructor(options: RuntimeInstanceControllerOptions);
+    get switching(): boolean;
+    get preparing(): boolean;
+    get preparationError(): Error | undefined;
+    /** 库内准备入口；异步回调按当前轮次判断是否还能更新展示，不让旧模式覆盖新模式。 */
+    prepareView<T>(prepare: (isCurrent: () => boolean) => Promise<T>): Promise<T>;
+    /** 提交、草稿、打印及初始化完成通知，都等待实际准备任务结束。 */
+    waitUntilPrepared(): Promise<void>;
+    /** 严格获取活动 Sheet，核心操作缺少活动 Sheet 时立即报错。 */
+    getActiveSheet(): import('./runtime-context').RuntimeSheetContext;
+    /** 查询指定 Sheet；省略 sheetId 时返回活动 Sheet，打印可明确指定其他 Sheet。 */
+    getSheet(sheetId?: string): import('./runtime-context').RuntimeSheetContext | undefined;
+    /**
+     * 字段通过 useRuntimeEditorFlusher 注册尚未写入 Store 的编辑状态提交函数，
+     * 卸载时调用返回的注销函数；已即时写入 Store 的控件无需额外注册。
+     */
+    registerEditorFlusher(flusher: RuntimeEditorFlusher): () => boolean;
+    private flushActiveEditor;
+    activateSheet(sheetId: string, options?: ActivateRuntimeSheetOptions): Promise<import('./runtime-context').RuntimeSheetContext | undefined>;
+    /** 统一记录 Sheet 滚动位置；无效数值归零，负值截断为零。 */
+    updateScrollTop(sheetId: string, scrollTop: number): void;
+    /** 暂存/变更业务取得稳定数据，不校验、不导航；不能把此结果当作已通过提交校验。 */
+    prepareDraft(): Promise<import('./runtime-persistence-coordinator').RuntimeSubmissionDataSnapshot<Record<string, any>>>;
+    /**
+     * 打印渲染器同步捕获同一 revision 的数据、节点和分页；不执行业务转换或校验。
+     * capture 只复制展示状态，不能请求数据或修改原实例；宿主通过 PreviewContainer 打印。
+     */
+    preparePrintSnapshot<T>(capture: (formState: Record<string, any>, revision: number) => T): Promise<T>;
+    /**
+     * 【宿主接入·已接通】业务按钮消费本次 result.validation/result.payload，不读取提交缓存。
+     * 网络异常由宿主处理；本方法仅生成稳定快照，不发送保存或提交请求。
+     */
+    prepareSubmission(): Promise<RuntimeSubmissionResult>;
+    private runSubmission;
+    dispose(): void;
+    private assertAlive;
+}

package/dist/src/nocode-base/src/runtime/runtime-instance-event-bus.d.ts

@@ -0,0 +1,17 @@
+export interface RuntimeAnnotationSelectEvent {
+    cellLocation: string | string[];
+    /** DOM 所属 Sheet；没有 DOM 时仍可通过稳定业务位置解析所属 Sheet。 */
+    sheetId?: string;
+}
+export interface RuntimeInstanceEvents {
+    annotationSelect: RuntimeAnnotationSelectEvent;
+}
+type RuntimeEventHandler<K extends keyof RuntimeInstanceEvents> = (event: RuntimeInstanceEvents[K]) => void | Promise<void>;
+/** 每个多 Sheet 表单实例独享事件总线，避免批注等 UI 事件串到同屏其他实例。 */
+export declare class RuntimeInstanceEventBus {
+    private readonly handlers;
+    on<K extends keyof RuntimeInstanceEvents>(type: K, handler: RuntimeEventHandler<K>): () => boolean;
+    emit<K extends keyof RuntimeInstanceEvents>(type: K, event: RuntimeInstanceEvents[K]): void;
+    dispose(): void;
+}
+export {};