@gct-paas/excel 0.1.36 → 0.1.37-beta.1

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 {};

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

@@ -0,0 +1,296 @@
+import { RuntimeFieldInitializer } from './runtime-field-initializer';
+import { RuntimeValidationService } from './runtime-validation-service';
+import { RuntimeInstanceContext } from './runtime-context';
+import { RuntimeInstanceController } from './runtime-instance-controller';
+import { RuntimeRuleCompiler } from './runtime-rule-compiler';
+import { RuntimeFormStateStore } from './runtime-form-state-store';
+import { CodeRunner } from '../interface/code-runner';
+import { RuntimeAsyncTaskCoordinator } from './async-task-coordinator';
+import { RuntimeDependencyService } from './runtime-dependency-service';
+import { RuntimeFieldRegistry, RuntimeFieldMetadata } from './runtime-field-registry';
+import { RuntimeSheetService } from './runtime-sheet-service';
+import { RuntimePersistenceCoordinator } from './runtime-persistence-coordinator';
+import { RuntimeInstanceEventBus } from './runtime-instance-event-bus';
+export interface RuntimeInstanceRecord {
+    /** 实例配置、业务索引和各 Sheet 的响应式状态；数据只由下方 Store 持有 */
+    context: RuntimeInstanceContext;
+    /** 负责切换 Sheet、收口编辑器和发起原子提交；上下文注册后再挂载 */
+    controller?: RuntimeInstanceController;
+    /**
+     * 【库内接入】正式填报宿主提供模式/权限信息后挂载 RuntimeRuleCompiler，常规工厂已接通。
+     * 编译全部 Sheet 的联动与校验规则；校验前通过 prepareValidation 准备，由本注册表负责销毁。
+     */
+    ruleCompiler?: RuntimeRuleCompiler;
+    /** 业务默认值随实例及动态行初始化，不依赖控件挂载。 */
+    fieldInitializer?: RuntimeFieldInitializer;
+    /** 实例唯一的数据写入口，生成 revision、dirty 和字段变更路径 */
+    formState: RuntimeFormStateStore;
+    /** 整份表单共享的脚本执行器，字段通过运行时记录调用，销毁由注册表负责。 */
+    scriptRunner?: CodeRunner;
+    /** 跟踪上传、扫码、远程回填等任务，提交前等待必要任务完成 */
+    asyncTasks: RuntimeAsyncTaskCoordinator;
+    /** 与组件挂载无关的实例级公式、赋值和条件属性调度器 */
+    dependencies: RuntimeDependencyService;
+    /** 汇总全部 Sheet 的字段位置，供校验、分页失效和导航查询 */
+    fields: RuntimeFieldRegistry;
+    /** 统一管理各 Sheet 的分页失效、重新分页及错误/批注定位。 */
+    sheetService: RuntimeSheetService;
+    /** 暂存响应版本保护、稳定提交快照及销毁保护统一由这一实例服务管理。 */
+    persistence: RuntimePersistenceCoordinator;
+    /** 只在当前实例内分发批注等 UI 事件 */
+    events: RuntimeInstanceEventBus;
+    /** 当前实例独占规则、校验任务和错误合并。 */
+    validation: RuntimeValidationService;
+}
+export interface RegisterRuntimeInstanceOptions {
+    /** 初始化脚本、子表和字段组件共同使用的唯一数据 Store。 */
+    formStateStore: RuntimeFormStateStore;
+    /**
+     * 【库内接入】独立注册实例时传入字段扫描结果的 fieldMetadata；常规工厂已接通。
+     * 包含真实控件引用、组合子字段和 value_ 位置，Registry 不再回头扫描节点。
+     */
+    fieldMetadata: RuntimeFieldMetadata;
+    /** 打印副本恢复当前条件输出，不携带规则执行器、脚本或正在运行的任务。 */
+    dependencyOutputs?: Readonly<Record<string, unknown>>;
+    /** 初始化阶段创建并绑定同一 Store 的脚本执行器；无脚本时为空。 */
+    scriptRunner?: CodeRunner;
+}
+/**
+ * 渲染宿主的实例注册表，多 Sheet 运行端的唯一实例入口
+ *
+ * 每个 `uniqueId` 对应一份 `RuntimeInstanceRecord`
+ * 一条记录中包含：
+ * - 整份表单共享的 formState、表单配置和业务索引
+ * - 每个 Sheet 独立的 dataCenter、分页和滚动状态
+ * - 联动、校验、保存、提交、导航等实例级服务
+ *
+ */
+export declare class RuntimeInstanceRegistry {
+    /** 当前渲染入口的加载状态，由工厂更新；PreviewContainer 直接读取，无需宿主额外传参。 */
+    readonly loadState: import('vue').ShallowReactive<{
+        loading: boolean;
+        error: Error | undefined;
+    }>;
+    /**
+     * 顶层对象使用浅响应式：实例新增、删除需要驱动 Vue 更新；record 内的服务类
+     * 不需要被 Vue 深度代理，各自内部负责自己的响应式状态和生命周期
+     */
+    private readonly records;
+    /**
+     * 统一托管订阅、watch 和编译结果的取消函数
+     * 删除实例时先执行这些函数，避免已销毁实例继续响应数据或事件
+     */
+    private readonly disposables;
+    /**
+     * 注册一个已经完成 v1/v2 归一化和业务初始化的表单实例
+     *
+     * 此方法只创建实例级基础设施，不负责请求模板和业务数据。相同 uniqueId
+     * 再次注册时会先完整销毁旧记录，确保不会残留订阅或异步任务
+     */
+    register(context: RuntimeInstanceContext, options: RegisterRuntimeInstanceOptions): RuntimeInstanceRecord;
+    /**
+     * 在页面回调准备完成后挂载实例控制器
+     * Sheet 服务的导航入口依赖控制器切换 Sheet，所以两者必须在这里建立连接
+     */
+    attachController(uniqueId: string, controller: RuntimeInstanceController): RuntimeInstanceController;
+    /** 可选查询：实例尚未完成注册或已卸载时返回 undefined，供页面生命周期读取 */
+    get(uniqueId: string): RuntimeInstanceRecord | undefined;
+    /** 强制查询：核心业务链路缺少实例时立即报错，避免继续产生不完整状态 */
+    require(uniqueId: string): RuntimeInstanceRecord;
+    /** 返回当前宿主已注册的全部实例记录 */
+    values(): RuntimeInstanceRecord[];
+    /** 实例列表只取概要，控制台列举实例时不复制整份填报数据和节点。 */
+    getDebugSummaries(): {
+        uniqueId: string;
+        instanceId: string;
+        templateId: string;
+        schemaVersion: 2 | 1;
+        activeSheetId: string;
+        sheetCount: number;
+        revision: number;
+        dirty: boolean;
+        taskCount: number;
+    }[];
+    /**
+     * 取得查看时刻的调试快照，不暴露 Store 或服务实例的可写引用。
+     * 不执行联动、分页或提交；省略 ID 仅在当前注册表恰好有一份实例时生效。
+     */
+    getDebugSnapshot(uniqueId?: string): {
+        capturedAt: string;
+        uniqueId: string;
+        instanceId: string;
+        templateId: string;
+        schemaVersion: 2 | 1;
+        activeSheetId: string;
+        revision: number;
+        dirty: boolean;
+        controllerAttached: boolean;
+        ruleCompilerAttached: boolean;
+        scriptRunnerAttached: boolean;
+        formState: Record<string, any>;
+        formConfig: Record<string, any>;
+        defaultData: Record<string, any>;
+        businessIndex: import('./runtime-context').RuntimeBusinessIndex;
+        fieldRegistry: {
+            fields: Array<import('./runtime-context').RuntimeFieldLocation & {
+                widget?: import("..").BaseCoreComponent.BasicSchema;
+            }>;
+            widgets: import('./runtime-field-registry').RuntimeWidgetMetadata[];
+            fieldCount: number;
+            businessFieldCount: number;
+            widgetCount: number;
+            compiledWidgetCount: number;
+        };
+        sheets: {
+            sheetId: string;
+            title: string;
+            status: import('./runtime-context').RuntimeSheetStatus;
+            errorMessage: string | undefined;
+            pageCount: number;
+            nodeCount: number;
+            scrollTop: number;
+            paginationDirty: boolean;
+            paginationRevision: number;
+            paginationError: string | undefined;
+            paper: any;
+        }[];
+        asyncTasks: import('./async-task-coordinator').RuntimeAsyncTaskSnapshot[];
+        dependencies: {
+            scheduled: boolean;
+            pendingChangeCount: number;
+            runningRuleIds: string[];
+            rules: {
+                id: string;
+                targetField?: import('./runtime-dependency-service').RuntimeDependencyFieldReference;
+                sheetId?: string;
+                sourceFields?: import('./runtime-dependency-service').RuntimeDependencyFieldReference[];
+                structureFields?: string[];
+            }[];
+            outputs: Record<string, unknown>;
+        };
+        validation: {
+            ruleCount: number;
+            livePending: boolean;
+            displayPending: boolean;
+            bound: boolean;
+        };
+    };
+    /** 详细节点和分页按需复制，避免列举十个 Sheet 时就复制全部模板节点。 */
+    getSheetDebugSnapshot(sheetId?: string, uniqueId?: string): import('./runtime-context').RuntimeSheetContext;
+    /** 字段专项查询直接读取真实注册表，包含业务索引中没有的内部字段和引用位置。 */
+    getFieldDebugSnapshot(uniqueId?: string): {
+        fields: Array<import('./runtime-context').RuntimeFieldLocation & {
+            widget?: import("..").BaseCoreComponent.BasicSchema;
+        }>;
+        widgets: import('./runtime-field-registry').RuntimeWidgetMetadata[];
+        fieldCount: number;
+        businessFieldCount: number;
+        widgetCount: number;
+        compiledWidgetCount: number;
+    };
+    /** 分组打印一份快照并返回它；后续输入不会改变已经展开的日志内容。 */
+    debug(uniqueId?: string): {
+        capturedAt: string;
+        uniqueId: string;
+        instanceId: string;
+        templateId: string;
+        schemaVersion: 2 | 1;
+        activeSheetId: string;
+        revision: number;
+        dirty: boolean;
+        controllerAttached: boolean;
+        ruleCompilerAttached: boolean;
+        scriptRunnerAttached: boolean;
+        formState: Record<string, any>;
+        formConfig: Record<string, any>;
+        defaultData: Record<string, any>;
+        businessIndex: import('./runtime-context').RuntimeBusinessIndex;
+        fieldRegistry: {
+            fields: Array<import('./runtime-context').RuntimeFieldLocation & {
+                widget?: import("..").BaseCoreComponent.BasicSchema;
+            }>;
+            widgets: import('./runtime-field-registry').RuntimeWidgetMetadata[];
+            fieldCount: number;
+            businessFieldCount: number;
+            widgetCount: number;
+            compiledWidgetCount: number;
+        };
+        sheets: {
+            sheetId: string;
+            title: string;
+            status: import('./runtime-context').RuntimeSheetStatus;
+            errorMessage: string | undefined;
+            pageCount: number;
+            nodeCount: number;
+            scrollTop: number;
+            paginationDirty: boolean;
+            paginationRevision: number;
+            paginationError: string | undefined;
+            paper: any;
+        }[];
+        asyncTasks: import('./async-task-coordinator').RuntimeAsyncTaskSnapshot[];
+        dependencies: {
+            scheduled: boolean;
+            pendingChangeCount: number;
+            runningRuleIds: string[];
+            rules: {
+                id: string;
+                targetField?: import('./runtime-dependency-service').RuntimeDependencyFieldReference;
+                sheetId?: string;
+                sourceFields?: import('./runtime-dependency-service').RuntimeDependencyFieldReference[];
+                structureFields?: string[];
+            }[];
+            outputs: Record<string, unknown>;
+        };
+        validation: {
+            ruleCount: number;
+            livePending: boolean;
+            displayPending: boolean;
+            bound: boolean;
+        };
+    };
+    /**
+     * 默认只预览提交前数据，不校验；显式 validate=true 才执行正式提交准备与错误导航。
+     * 两种模式都收口编辑器、等待异步任务并刷新分页，不发送保存或提交请求。
+     * 返回值深拷贝，并用 validated 区分模式，未校验的预览不标记 isValid=true。
+     */
+    debugSubmitData(uniqueId?: string, validate?: boolean): Promise<{
+        isValid: false;
+        revision: number;
+        validation: import('./runtime-persistence-coordinator').RuntimeSubmissionValidationResult;
+        validated: true;
+        uniqueId: string;
+        capturedAt: string;
+    } | {
+        isValid: true;
+        validation: import('./runtime-persistence-coordinator').RuntimeSubmissionValidationResult;
+        revision: number;
+        formState: Readonly<Record<string, any>>;
+        payload: Record<string, any>;
+        validated: true;
+        uniqueId: string;
+        capturedAt: string;
+    } | {
+        revision: number;
+        formState: Readonly<Record<string, any>>;
+        payload: Record<string, any>;
+        validated: false;
+        uniqueId: string;
+        capturedAt: string;
+    }>;
+    private requireDebugRecord;
+    /**
+     * 登记随实例销毁的清理函数，例如 Store 订阅、规则编译结果和 watch
+     * 返回值只撤销本次登记，便于调用方提前停止订阅
+     */
+    registerDisposable(uniqueId: string, dispose: () => void): () => boolean;
+    /**
+     * 销毁单个实例以及它拥有的全部服务
+     * Sheet 切换不会调用这里；只有实例刷新、替换或宿主卸载才会销毁
+     */
+    delete(uniqueId: string): void;
+    /**
+     * useRenderPageFactory 和打印副本容器在卸载时调用，关闭全部脚本、订阅和异步任务。
+     */
+    clear(): void;
+}