@kimposoft/plugin-sdk 0.0.0-stage → 1.1.0-tp.20

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +9 -0
  3. package/README.md +48 -2
  4. package/package.json +141 -4
  5. package/src/action-designer.ts +250 -0
  6. package/src/attachment-url.ts +195 -0
  7. package/src/auth/index.ts +6 -0
  8. package/src/auth/qrcode.ts +519 -0
  9. package/src/auth/types.ts +261 -0
  10. package/src/display-style.ts +250 -0
  11. package/src/editor-frame.ts +623 -0
  12. package/src/editor-session.ts +1214 -0
  13. package/src/editor-testing.ts +838 -0
  14. package/src/editor.ts +1641 -0
  15. package/src/frame-transport.ts +491 -0
  16. package/src/frontend-routes.ts +99 -0
  17. package/src/hooks.ts +48 -0
  18. package/src/host-caps.ts +93 -0
  19. package/src/i18n.ts +238 -0
  20. package/src/im-panel.ts +132 -0
  21. package/src/image-tools.ts +91 -0
  22. package/src/index.ts +118 -0
  23. package/src/interactive-session.ts +94 -0
  24. package/src/nahida-im.ts +391 -0
  25. package/src/nahida-ws.ts +23 -0
  26. package/src/org-directory.ts +78 -0
  27. package/src/oz-realtime.ts +144 -0
  28. package/src/page.ts +404 -0
  29. package/src/print.ts +393 -0
  30. package/src/surface.ts +281 -0
  31. package/src/theme-mocks.ts +140 -0
  32. package/src/theme.ts +125 -0
  33. package/src/ui-fixtures/confirm.ts +16 -0
  34. package/src/ui-fixtures/entity-picker.ts +24 -0
  35. package/src/ui-fixtures/expression-editor.ts +52 -0
  36. package/src/ui-fixtures/image-cropper.ts +23 -0
  37. package/src/ui-fixtures/index.ts +16 -0
  38. package/src/ui-fixtures/org-tri-picker.ts +19 -0
  39. package/src/ui-fixtures/prompt.ts +19 -0
  40. package/src/ui-fixtures/record-picker.ts +17 -0
  41. package/src/ui-fixtures/template-picker.ts +13 -0
  42. package/src/ui-mocks.ts +250 -0
  43. package/src/ui.ts +479 -0
  44. package/src/workflow-designer.ts +475 -0
@@ -0,0 +1,1214 @@
1
+ /**
2
+ * editor-session.ts —— 编辑器前端 helper(SDK 1.1.0-tp.15 起):
3
+ * - createHostMirrorSession:host-mirror 填报态客户端(快照 → 本地视图、帧收发、ack / 回滚、缺口检测与重拉快照、
4
+ * 断线续帧、宿主驱动保存);
5
+ * - createEditorDesignClient:设计态桥 designData 的 typed 封装(信封保存前自检、退役数据类型拦截、结果解包);
6
+ * - normalize*:宿主打开应答(protojson 驼峰)与帧体(snake_case)两种写法统一成 SDK wire 形状(snake_case)。
7
+ *
8
+ * 链路:插件前端(编辑器 runtime / designer)↔ 宿主前端(持有 WS 与桥)↔ 宿主通用 editor transport ↔ 表单数据权威层 Mirror。
9
+ *
10
+ * 表单数据权威层(Mirror)纪律——本 helper 按此实现,编辑器照用即可:
11
+ * - 用户在编辑器里的编辑是「编辑器自身内部事务」:先在本地视图乐观显示,再经 edit.fields / edit.rows 投影进 Mirror;
12
+ * 宿主拒写(ack.rejected:查看态、隐藏 / 只读 / 派生只读字段、只读表)时本地回滚到 Mirror 的值;
13
+ * - 动作、取数、联动、流程写回只改 Mirror,宿主推 mirror.patch,本 helper 只把它合进视图(不回投、不再发 edit);
14
+ * patch 与在途编辑冲突时以 patch 为准(Mirror 是权威);
15
+ * - 保存 = 请宿主按 Mirror 保存(recordData.save 只带 mode / 幂等键 / 版本基线),前端载荷直存已退役。
16
+ *
17
+ * 两种帧通道:
18
+ * - 沙箱档(第三方编辑器的常态):传 `frames: hostBridge.editorFrames`。WS 由宿主页持有,断线续帧(?last_seq=)也由宿主页做;
19
+ * 本 helper 在收到新的 attached 时重发未确认的帧(宿主按 seq 去重)。需要快照时(缺口等不到 resync / snapshot、打开应答
20
+ * 没带快照、行结构拒写)调帧通道的 `resync()`,由宿主页带 `?snapshot=1` 重新附着、宿主补发 snapshot 帧(需支持编辑器重同步的宿主);
21
+ * 宿主帧通道没有 resync(旧宿主)或重同步后仍等不到快照时,进入 stale 并发 resync-needed 事件,编辑器应提示用户重新载入;
22
+ * - 直连(同源档或联调替身):传 `socket: { attachPath, connect }`,本 helper 自己连 WS,断线带 `?last_seq=` 退避重连,
23
+ * 需要快照时带 `?snapshot=1` 重连。
24
+ */
25
+ import { hostBridgeErrorFrom } from './frame-transport';
26
+ import {
27
+ createEditorFrameTransport,
28
+ type EditorAckBody,
29
+ type EditorClientFrame,
30
+ type EditorEditFieldsBody,
31
+ type EditorEditRowsBody,
32
+ type EditorFieldDelta,
33
+ type EditorFrameChannel,
34
+ type EditorFrameTransport,
35
+ type EditorMirrorPatch,
36
+ type EditorRowOp,
37
+ type EditorServerFrame
38
+ } from './editor-frame';
39
+ import type {
40
+ BoundEditorSessionSnapshot,
41
+ EditorDefineFieldsResult,
42
+ EditorDesignDocumentV1,
43
+ EditorDesignFile,
44
+ EditorEffectEnvelope,
45
+ EditorFieldChangeResult,
46
+ EditorFieldPropertyPatch,
47
+ EditorFieldValue,
48
+ EditorTemplateModel,
49
+ EditorRecordSnapshot,
50
+ EditorRowSnapshot,
51
+ EditorSessionMeta,
52
+ EditorTableSnapshot,
53
+ EditorTypedValue
54
+ } from './editor';
55
+
56
+ // ════════════════════════════ 一、wire 归一 ════════════════════════════
57
+
58
+ /** 主表唯一一行的 Mirror 行键。 */
59
+ export const MAIN_ROW_KEY = 'main:0';
60
+
61
+ function isObj(v: unknown): v is Record<string, unknown> {
62
+ return v !== null && typeof v === 'object' && !Array.isArray(v);
63
+ }
64
+
65
+ /** 按 snake_case 键取值,缺失时退到 lowerCamel 写法(宿主 HTTP 应答是 protojson 驼峰,帧体是 snake_case)。 */
66
+ function pick(o: Record<string, unknown>, snake: string): unknown {
67
+ if (snake in o) return o[snake];
68
+ const camel = snake.replace(/_([a-z])/g, (_m, c: string) => c.toUpperCase());
69
+ return o[camel];
70
+ }
71
+
72
+ function str(v: unknown): string | undefined {
73
+ return typeof v === 'string' ? v : typeof v === 'number' ? String(v) : undefined;
74
+ }
75
+
76
+ function num(v: unknown): number | undefined {
77
+ if (typeof v === 'number' && Number.isFinite(v)) return v;
78
+ if (typeof v === 'string' && v.trim() !== '' && Number.isFinite(Number(v))) return Number(v);
79
+ return undefined;
80
+ }
81
+
82
+ function strList(v: unknown): string[] | undefined {
83
+ return Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : undefined;
84
+ }
85
+
86
+ /** 归一一个字段值({raw, text})。 */
87
+ export function normalizeTypedValue(v: unknown): EditorTypedValue {
88
+ if (!isObj(v)) return {};
89
+ const out: EditorTypedValue = {};
90
+ if ('raw' in v && v.raw !== undefined) out.raw = v.raw;
91
+ const text = str(v.text);
92
+ if (text !== undefined) out.text = text;
93
+ return out;
94
+ }
95
+
96
+ /** 把宿主快照(snake_case 或 protojson 驼峰)归一成 EditorRecordSnapshot(snake_case)。 */
97
+ export function normalizeEditorRecordSnapshot(raw: unknown): EditorRecordSnapshot | undefined {
98
+ if (!isObj(raw)) return undefined;
99
+ const out: EditorRecordSnapshot = {};
100
+ const recordId = str(pick(raw, 'record_id'));
101
+ if (recordId) out.record_id = recordId;
102
+ const tv = str(pick(raw, 'template_version_no'));
103
+ if (tv) out.template_version_no = tv;
104
+ const rv = num(pick(raw, 'record_version_no'));
105
+ if (rv !== undefined) out.record_version_no = rv;
106
+ out.mirror_seq = num(pick(raw, 'mirror_seq')) ?? 0;
107
+ const tables = pick(raw, 'tables');
108
+ out.tables = (Array.isArray(tables) ? tables : []).filter(isObj).map(t => {
109
+ const rows = pick(t, 'rows');
110
+ const table: EditorTableSnapshot = {
111
+ data_table_id: str(pick(t, 'data_table_id')) ?? '',
112
+ role: str(pick(t, 'role')) ?? '',
113
+ rows: (Array.isArray(rows) ? rows : []).filter(isObj).map(r => {
114
+ const fields = pick(r, 'fields');
115
+ const row: EditorRowSnapshot = {
116
+ row_key: str(pick(r, 'row_key')) ?? '',
117
+ row_state: str(pick(r, 'row_state')),
118
+ display_order: num(pick(r, 'display_order')) ?? 0,
119
+ record_id: str(pick(r, 'record_id')),
120
+ fields: (Array.isArray(fields) ? fields : []).filter(isObj).map(
121
+ (f): EditorFieldValue => ({ field_id: str(pick(f, 'field_id')) ?? '', value: normalizeTypedValue(f.value) })
122
+ )
123
+ };
124
+ return row;
125
+ })
126
+ };
127
+ return table;
128
+ });
129
+ return out;
130
+ }
131
+
132
+ /** 把会话元数据(打开应答 meta 或 session.meta 帧体,两种写法)归一。 */
133
+ export function normalizeEditorSessionMeta(raw: unknown): EditorSessionMeta {
134
+ if (!isObj(raw)) return {};
135
+ const out: EditorSessionMeta = {};
136
+ if (pick(raw, 'readonly') === true) out.readonly = true;
137
+ if (pick(raw, 'record_locked') === true) out.record_locked = true;
138
+ for (const key of ['hidden_field_ids', 'readonly_field_ids', 'readonly_table_ids', 'derived_readonly_field_ids', 'required_field_ids'] as const) {
139
+ const list = strList(pick(raw, key));
140
+ if (list) out[key] = list;
141
+ }
142
+ const perms = pick(raw, 'permissions');
143
+ if (isObj(perms)) out.permissions = Object.fromEntries(Object.entries(perms).map(([k, v]) => [k, v === true]));
144
+ for (const key of ['locale', 'timezone', 'form_mode', 'scene'] as const) {
145
+ const v = str(pick(raw, key));
146
+ if (v) (out as Record<string, unknown>)[key] = v;
147
+ }
148
+ const ext = pick(raw, 'extensions');
149
+ if (isObj(ext)) out.extensions = ext;
150
+ return out;
151
+ }
152
+
153
+ /** 归一宿主下发的 bound session(顶层驼峰;meta / recordSnapshot 统一成 snake_case)。不合法返回 undefined。 */
154
+ export function normalizeBoundEditorSession(raw: unknown): BoundEditorSessionSnapshot | undefined {
155
+ if (!isObj(raw)) return undefined;
156
+ const id = str(pick(raw, 'editor_session_id')) ?? str(raw.sheetSessionId) ?? str(raw.sessionId);
157
+ if (!id) return undefined;
158
+ const out: BoundEditorSessionSnapshot = {
159
+ editorSessionId: id,
160
+ sheetSessionId: id,
161
+ credentialRevision: num(pick(raw, 'credential_revision')) ?? 0,
162
+ expiresAt: str(pick(raw, 'expires_at')) ?? '',
163
+ serverTime: str(pick(raw, 'server_time')) ?? '',
164
+ attachPath: str(pick(raw, 'attach_path')) ?? ''
165
+ };
166
+ const pluginId = str(pick(raw, 'plugin_id'));
167
+ if (pluginId) out.pluginId = pluginId;
168
+ const mode = str(pick(raw, 'session_mode'));
169
+ if (mode === 'host-mirror' || mode === 'sidecar') out.sessionMode = mode;
170
+ const fp = str(pick(raw, 'frame_protocol'));
171
+ if (fp) out.frameProtocol = fp;
172
+ if (pick(raw, 'meta') !== undefined) out.meta = normalizeEditorSessionMeta(pick(raw, 'meta'));
173
+ const snap = normalizeEditorRecordSnapshot(pick(raw, 'record_snapshot'));
174
+ if (snap) out.recordSnapshot = snap;
175
+ return out;
176
+ }
177
+
178
+ /** 构造字段值:字符串 / 数字 / null / 已是 {raw,text} 的对象。 */
179
+ export function toTypedValue(value: unknown): EditorTypedValue {
180
+ if (value === null || value === undefined) return {};
181
+ if (typeof value === 'string') return { raw: value, text: value };
182
+ if (typeof value === 'number') return { raw: value, text: String(value) };
183
+ if (typeof value === 'boolean') return { raw: value, text: String(value) };
184
+ if (isObj(value) && ('raw' in value || 'text' in value)) return normalizeTypedValue(value);
185
+ return { raw: value, text: JSON.stringify(value) };
186
+ }
187
+
188
+ /** 字段值的显示文本(text 优先,退到 raw)。 */
189
+ export function typedValueText(v: EditorTypedValue | undefined): string | undefined {
190
+ if (!v) return undefined;
191
+ if (typeof v.text === 'string') return v.text;
192
+ if (v.raw === undefined || v.raw === null) return undefined;
193
+ return typeof v.raw === 'string' ? v.raw : JSON.stringify(v.raw);
194
+ }
195
+
196
+ /** 宿主驱动保存的归一回执。 */
197
+ export interface HostMirrorSaveResult {
198
+ ok: boolean;
199
+ recordId: string;
200
+ versionNo: number;
201
+ statusCode: string;
202
+ fieldErrors: Array<{ fieldId: string; dataTableId?: string; rowKey?: string; code: string; message?: string }>;
203
+ mirrorSeq?: number;
204
+ }
205
+
206
+ /** 归一宿主驱动保存回执(ReportSaveResult 驼峰、HostDrivenSaveResult snake_case、{data, error} 信封都收)。 */
207
+ export function normalizeHostSaveResult(raw: unknown): HostMirrorSaveResult {
208
+ let v = raw;
209
+ if (isObj(v) && 'data' in v && ('error' in v || Object.keys(v).length <= 2)) {
210
+ // 信封里的 error 带 {code, message, params?},还原成带 .code / .params 的 HostBridgeCallError。
211
+ if (v.error) throw hostBridgeErrorFrom(v.error);
212
+ v = v.data;
213
+ }
214
+ const o = isObj(v) ? v : {};
215
+ const errors = pick(o, 'field_errors');
216
+ const fieldErrors = (Array.isArray(errors) ? errors : []).filter(isObj).map(e => ({
217
+ fieldId: str(pick(e, 'field_id')) ?? '',
218
+ ...(str(pick(e, 'data_table_id')) ? { dataTableId: str(pick(e, 'data_table_id')) } : {}),
219
+ ...(str(pick(e, 'row_key')) ? { rowKey: str(pick(e, 'row_key')) } : {}),
220
+ code: str(pick(e, 'code')) ?? '',
221
+ ...(str(pick(e, 'message')) ? { message: str(pick(e, 'message')) } : {})
222
+ }));
223
+ const mirrorSeq = num(pick(o, 'mirror_seq'));
224
+ return {
225
+ ok: fieldErrors.length === 0,
226
+ recordId: str(pick(o, 'record_id')) ?? '',
227
+ versionNo: num(pick(o, 'version_no')) ?? 0,
228
+ statusCode: str(pick(o, 'status_code')) ?? '',
229
+ fieldErrors,
230
+ ...(mirrorSeq !== undefined ? { mirrorSeq } : {})
231
+ };
232
+ }
233
+
234
+ // ════════════════════════════ 二、host-mirror 会话客户端 ════════════════════════════
235
+
236
+ /** 帧通道之外的最小 WebSocket 形状(直连模式)。 */
237
+ export interface EditorWebSocketLike {
238
+ readyState: number;
239
+ send(data: string): void;
240
+ close(code?: number, reason?: string): void;
241
+ onopen: ((ev: unknown) => void) | null;
242
+ onmessage: ((ev: { data: unknown }) => void) | null;
243
+ onclose: ((ev: { code?: number }) => void) | null;
244
+ }
245
+
246
+ /** 日志口(hostBridge.log 同形)。 */
247
+ export interface EditorSessionLog {
248
+ debug?(message: string, context?: unknown): unknown;
249
+ info?(message: string, context?: unknown): unknown;
250
+ warn?(message: string, context?: unknown): unknown;
251
+ error?(message: string, context?: unknown): unknown;
252
+ }
253
+
254
+ /** createHostMirrorSession 入参。 */
255
+ export interface HostMirrorSessionOptions {
256
+ /** 宿主下发的 bound session(props.boundSession;两种键写法都收)。 */
257
+ boundSession: unknown;
258
+ /** 沙箱档:宿主桥 editorFrames(与 socket 二选一)。 */
259
+ frames?: EditorFrameChannel;
260
+ /** 直连:自己连 attach WS(同源档 / 联调)。 */
261
+ socket?: {
262
+ /** 缺省取 boundSession.attachPath。 */
263
+ attachPath?: string;
264
+ /** 建 WebSocket(缺省用全局 WebSocket,URL 按 location 补 ws(s):// 与 host)。 */
265
+ connect?: (url: string) => EditorWebSocketLike;
266
+ /** 断线重连上限与退避基数(缺省 5 次 / 500ms)。 */
267
+ maxReconnects?: number;
268
+ reconnectBaseMs?: number;
269
+ };
270
+ /** 宿主桥 recordData(save 走宿主按 Mirror 保存)。 */
271
+ recordData?: { save(input: Record<string, unknown>): unknown };
272
+ /** 宿主桥 log:关键位置(拒写、缺口、重拉快照、保存)按级别上报。 */
273
+ log?: EditorSessionLog;
274
+ /** 缺口等宿主重放 / resync 的时限(缺省 3000ms),超时即重拉快照或进入 stale。 */
275
+ gapTimeoutMs?: number;
276
+ /** 保存前等待在途帧确认的时限(缺省 10000ms)。 */
277
+ flushTimeoutMs?: number;
278
+ /** 测试注入:定时器。 */
279
+ setTimer?: (fn: () => void, ms: number) => unknown;
280
+ clearTimer?: (handle: unknown) => void;
281
+ }
282
+
283
+ /** 会话状态:live 正常;resyncing 等待重放 / 快照;stale 视图可能过期(需重新载入);closed 已关闭。 */
284
+ export type HostMirrorSessionStatus = 'live' | 'resyncing' | 'stale' | 'closed';
285
+
286
+ /** 会话事件。 */
287
+ export type HostMirrorSessionEvent =
288
+ | { kind: 'change'; cause: 'local' | 'patch' | 'snapshot' | 'reject' | 'assign' | 'meta'; patch?: EditorMirrorPatch }
289
+ | { kind: 'rejected'; items: NonNullable<EditorAckBody['rejected']> }
290
+ | { kind: 'effects'; envelope: EditorEffectEnvelope }
291
+ | { kind: 'meta'; meta: EditorSessionMeta }
292
+ | { kind: 'status'; status: HostMirrorSessionStatus }
293
+ | { kind: 'error'; code: string; message?: string; refSeq?: number }
294
+ | { kind: 'resync-needed'; reason: string };
295
+
296
+ /** createHostMirrorSession 返回的会话。 */
297
+ export interface HostMirrorSession {
298
+ readonly editorSessionId: string;
299
+ status(): HostMirrorSessionStatus;
300
+ meta(): EditorSessionMeta;
301
+ /** 会话是否只读(查看态 / 只读打开 / 非填报场景)。 */
302
+ isReadonly(): boolean;
303
+ /** 字段是否可编辑(会话可写且不是隐藏 / 只读 / 派生只读字段)。 */
304
+ isFieldEditable(fieldId: string): boolean;
305
+ /** 字段是否必填(宿主 meta.required_field_ids ;旧宿主不下发时恒 false,以保存回执为准)。 */
306
+ isFieldRequired(fieldId: string): boolean;
307
+ /** 表能否增删行(会话可写且不是只读表)。 */
308
+ canEditRows(dataTableId: string): boolean;
309
+ tables(): Array<{ data_table_id: string; role: string }>;
310
+ /** 当前显示行键(显示顺序;本地新增未确认的行用客户端行键 c:N,确认后换成 Mirror 行键)。 */
311
+ rows(dataTableId: string): string[];
312
+ /** 当前显示值(在途编辑优先,其次 Mirror)。 */
313
+ getValue(dataTableId: string, rowKey: string, fieldId: string): EditorTypedValue | undefined;
314
+ getText(dataTableId: string, rowKey: string, fieldId: string): string | undefined;
315
+ /** 记录元信息(记录 ID、记录版本、Mirror 写序)。 */
316
+ record(): { recordId?: string; recordVersionNo?: number; mirrorSeq: number };
317
+ /** 用户编辑一个字段:本地乐观显示并投影进 Mirror(不可编辑的字段直接忽略并返回 false)。 */
318
+ setValue(dataTableId: string, rowKey: string, fieldId: string, value: unknown): boolean;
319
+ /** 追加明细行,返回客户端行键(ack 后 rows() 里换成 Mirror 行键,可用 resolveRowKey 换算)。 */
320
+ appendRows(dataTableId: string, count?: number): string[];
321
+ removeRows(dataTableId: string, rowKeys: string[]): void;
322
+ reorderRows(dataTableId: string, orderedRowKeys: string[]): void;
323
+ /** 客户端行键 → Mirror 行键(未确认返回自身)。 */
324
+ resolveRowKey(rowKey: string): string;
325
+ /** 未确认的编辑数:在途帧 + 等新行行键后才发出的字段编辑。 */
326
+ pendingCount(): number;
327
+ /** 等全部编辑确认(含未发出的;超时 reject,错误码 FLUSH_TIMEOUT,文案计数与 pendingCount() 同口径)。 */
328
+ flush(timeoutMs?: number): Promise<void>;
329
+ /** 宿主驱动保存:先 flush,再调 recordData.save(只带 mode / 幂等键 / 版本基线)。 */
330
+ save(input?: { mode?: 'create' | 'edit'; clientMutationId?: string; expectedVersionNo?: number; submitAction?: string }): Promise<HostMirrorSaveResult>;
331
+ /** 主动重拉快照(直连模式带 ?snapshot=1 重连;沙箱档请宿主页经 editorFrames.resync 带 ?snapshot=1 重新附着,宿主不支持时发 resync-needed)。 */
332
+ requestSnapshot(reason?: string): void;
333
+ on(listener: (event: HostMirrorSessionEvent) => void): () => void;
334
+ close(): void;
335
+ }
336
+
337
+ /** host-mirror 会话错误码。 */
338
+ export const HOST_MIRROR_ERRORS = {
339
+ NOT_HOST_MIRROR: 'EDITOR_SESSION_NOT_HOST_MIRROR',
340
+ HOST_SAVE_UNAVAILABLE: 'EDITOR_HOST_SAVE_UNAVAILABLE',
341
+ FLUSH_TIMEOUT: 'EDITOR_SAVE_FLUSH_TIMEOUT',
342
+ SESSION_CLOSED: 'EDITOR_SESSION_CLOSED'
343
+ } as const;
344
+
345
+ function codedError(code: string, message: string): Error & { code: string } {
346
+ return Object.assign(new Error(`${code}: ${message}`), { code });
347
+ }
348
+
349
+ interface MirrorRow {
350
+ key: string;
351
+ order: number;
352
+ state?: string;
353
+ fields: Map<string, EditorTypedValue>;
354
+ }
355
+
356
+ interface MirrorTable {
357
+ id: string;
358
+ role: string;
359
+ rows: MirrorRow[];
360
+ }
361
+
362
+ /** 一条在途帧(未被 ack)。 */
363
+ interface PendingFrame {
364
+ seq: number;
365
+ type: 'edit.fields' | 'edit.rows';
366
+ body: EditorEditFieldsBody | EditorEditRowsBody;
367
+ /** Mirror 整帧拒写(error EDITOR_MIRROR_REJECTED 先于 ack 到达)。 */
368
+ mirrorRejected?: boolean;
369
+ }
370
+
371
+ /** 本地乐观编辑(等 ack)。 */
372
+ interface Overlay {
373
+ table: string;
374
+ row: string;
375
+ field: string;
376
+ value: EditorTypedValue;
377
+ seq: number;
378
+ }
379
+
380
+ /** 本地行操作(等 ack)。 */
381
+ type LocalRowOp =
382
+ | { kind: 'append'; table: string; clientKeys: string[]; seq: number }
383
+ | { kind: 'remove'; table: string; rowKeys: string[]; seq: number }
384
+ | { kind: 'reorder'; table: string; ordered: string[]; seq: number };
385
+
386
+ const cellKey = (t: string, r: string, f: string) => `${t}\u0000${r}\u0000${f}`;
387
+
388
+ /**
389
+ * createHostMirrorSession —— host-mirror 填报态客户端。
390
+ *
391
+ * @example
392
+ * ```ts
393
+ * const session = createHostMirrorSession({
394
+ * boundSession: props.boundSession,
395
+ * frames: hostBridge.editorFrames, // 沙箱档
396
+ * recordData: hostBridge.recordData,
397
+ * log: hostBridge.log
398
+ * });
399
+ * session.on(e => { if (e.kind === 'change') rerender(); });
400
+ * session.setValue(mainTableId, MAIN_ROW_KEY, fieldId, '客户 A');
401
+ * await session.save();
402
+ * ```
403
+ */
404
+ export function createHostMirrorSession(options: HostMirrorSessionOptions): HostMirrorSession {
405
+ const bound = normalizeBoundEditorSession(options.boundSession);
406
+ if (!bound) throw codedError(HOST_MIRROR_ERRORS.NOT_HOST_MIRROR, 'boundSession is missing or has no editorSessionId');
407
+ if (bound.sessionMode && bound.sessionMode !== 'host-mirror') {
408
+ throw codedError(HOST_MIRROR_ERRORS.NOT_HOST_MIRROR, `session mode ${bound.sessionMode} does not use editor-frame/1`);
409
+ }
410
+ if (!options.frames && !options.socket) {
411
+ throw codedError(HOST_MIRROR_ERRORS.NOT_HOST_MIRROR, 'either frames (hostBridge.editorFrames) or socket is required');
412
+ }
413
+ const setTimer = options.setTimer ?? ((fn: () => void, ms: number) => setTimeout(fn, ms));
414
+ const clearTimer = options.clearTimer ?? ((h: unknown) => clearTimeout(h as ReturnType<typeof setTimeout>));
415
+ const gapTimeoutMs = options.gapTimeoutMs ?? 3000;
416
+ const log = options.log ?? {};
417
+ const report = (level: 'debug' | 'info' | 'warn' | 'error', message: string, context?: Record<string, unknown>) => {
418
+ try {
419
+ log[level]?.(`[editor-session] ${message}`, { editor_session_id: bound.editorSessionId, ...context });
420
+ } catch {
421
+ // 日志失败不影响会话。
422
+ }
423
+ };
424
+
425
+ // ---- 状态 ----
426
+ let meta: EditorSessionMeta = bound.meta ?? {};
427
+ let status: HostMirrorSessionStatus = 'live';
428
+ let closed = false;
429
+ let recordId: string | undefined;
430
+ let recordVersionNo: number | undefined;
431
+ let tables: MirrorTable[] = [];
432
+ const overlays = new Map<string, Overlay>();
433
+ let rowOps: LocalRowOp[] = [];
434
+ const pending = new Map<number, PendingFrame>();
435
+ /** 客户端行键 → Mirror 行键。 */
436
+ const assigned = new Map<string, string>();
437
+ /** 发给尚未分配 Mirror 行键的新行的编辑(分配后补发)。 */
438
+ let deferred: EditorFieldDelta[] = [];
439
+ let clientRowCounter = 0;
440
+ const listeners = new Set<(event: HostMirrorSessionEvent) => void>();
441
+ let gapTimer: unknown;
442
+ const flushWaiters = new Set<() => void>();
443
+
444
+ const emit = (event: HostMirrorSessionEvent) => {
445
+ for (const l of [...listeners]) {
446
+ try {
447
+ l(event);
448
+ } catch {
449
+ // 监听器异常不影响会话。
450
+ }
451
+ }
452
+ };
453
+ const setStatus = (next: HostMirrorSessionStatus) => {
454
+ if (status === next || status === 'closed') return;
455
+ status = next;
456
+ emit({ kind: 'status', status });
457
+ };
458
+
459
+ const applySnapshot = (snap: EditorRecordSnapshot) => {
460
+ recordId = snap.record_id || recordId;
461
+ recordVersionNo = snap.record_version_no ?? recordVersionNo;
462
+ tables = (snap.tables ?? []).map(t => ({
463
+ id: t.data_table_id,
464
+ role: t.role ?? '',
465
+ rows: (t.rows ?? []).map(r => ({
466
+ key: r.row_key,
467
+ order: r.display_order ?? 0,
468
+ state: r.row_state,
469
+ fields: new Map((r.fields ?? []).map(f => [f.field_id, normalizeTypedValue(f.value)]))
470
+ }))
471
+ }));
472
+ };
473
+ const table = (id: string) => tables.find(t => t.id === id);
474
+ const mirrorRow = (t: string, r: string) => table(t)?.rows.find(row => row.key === r);
475
+ const hidden = () => new Set(meta.hidden_field_ids ?? []);
476
+
477
+ const initial = bound.recordSnapshot;
478
+ if (initial) applySnapshot(initial);
479
+
480
+ // ---- 帧通道 ----
481
+ let transport: EditorFrameTransport | undefined;
482
+ let directSocket: ReturnType<typeof createDirectChannel> | undefined;
483
+ if (options.frames) {
484
+ transport = createEditorFrameTransport(options.frames, { initialServerSeq: initial?.mirror_seq ?? 0 });
485
+ } else {
486
+ directSocket = createDirectChannel({
487
+ attachPath: options.socket?.attachPath ?? bound.attachPath,
488
+ connect: options.socket?.connect,
489
+ maxReconnects: options.socket?.maxReconnects ?? 5,
490
+ reconnectBaseMs: options.socket?.reconnectBaseMs ?? 500,
491
+ setTimer,
492
+ initialSeq: initial?.mirror_seq ?? 0,
493
+ wantSnapshot: !initial,
494
+ onWarn: (m, c) => report('warn', m, c)
495
+ });
496
+ transport = createEditorFrameTransport(directSocket.channel, { initialServerSeq: initial?.mirror_seq ?? 0 });
497
+ }
498
+
499
+ const startGapTimer = (reason: string) => {
500
+ if (gapTimer !== undefined) return;
501
+ gapTimer = setTimer(() => {
502
+ gapTimer = undefined;
503
+ if (status === 'resyncing') requestSnapshot(`${reason}-timeout`);
504
+ }, gapTimeoutMs);
505
+ };
506
+ const stopGapTimer = () => {
507
+ if (gapTimer !== undefined) clearTimer(gapTimer);
508
+ gapTimer = undefined;
509
+ };
510
+
511
+ const requestSnapshot = (reason = 'requested') => {
512
+ if (closed) return;
513
+ if (directSocket) {
514
+ report('info', 'reconnect with ?snapshot=1', { reason });
515
+ setStatus('resyncing');
516
+ directSocket.reconnect(true);
517
+ startGapTimer('snapshot');
518
+ return;
519
+ }
520
+ // 沙箱档:请宿主页带 ?snapshot=1 重新附着(帧通道 resync)。重同步后仍等不到快照
521
+ // (snapshot-timeout)或宿主帧通道没有 resync(旧宿主)时,进入 stale 并发 resync-needed。
522
+ const resync = options.frames?.resync;
523
+ if (typeof resync === 'function' && reason !== 'snapshot-timeout') {
524
+ report('info', 'ask host page to reattach with ?snapshot=1', { reason });
525
+ setStatus('resyncing');
526
+ startGapTimer('snapshot');
527
+ const fallback = (err: unknown) => {
528
+ if (closed || status !== 'resyncing') return;
529
+ stopGapTimer();
530
+ report('warn', 'host frame channel resync failed; reload required', { reason, error: String(err) });
531
+ setStatus('stale');
532
+ emit({ kind: 'resync-needed', reason });
533
+ };
534
+ try {
535
+ const r = resync.call(options.frames, reason);
536
+ if (r && typeof (r as Promise<void>).then === 'function') (r as Promise<void>).catch(fallback);
537
+ } catch (err) {
538
+ fallback(err);
539
+ }
540
+ return;
541
+ }
542
+ report('warn', 'snapshot unavailable through host frame channel; reload required', { reason });
543
+ stopGapTimer();
544
+ setStatus('stale');
545
+ emit({ kind: 'resync-needed', reason });
546
+ };
547
+
548
+ const notifyFlush = () => {
549
+ if (pending.size === 0 && deferred.length === 0) for (const w of [...flushWaiters]) w();
550
+ };
551
+
552
+ /** 把一个已确认的帧落进 Mirror 视图并清掉对应的乐观状态。 */
553
+ const settleFrame = (frame: PendingFrame, ack: EditorAckBody) => {
554
+ const rejectedCells = new Set((ack.rejected ?? []).map(r => cellKey(r.data_table_id, r.row_key, r.field_id)));
555
+ if (frame.type === 'edit.fields') {
556
+ for (const d of (frame.body as EditorEditFieldsBody).deltas) {
557
+ const k = cellKey(d.data_table_id, d.row_key, d.field_id);
558
+ const o = overlays.get(k);
559
+ if (o && o.seq === frame.seq) overlays.delete(k);
560
+ if (frame.mirrorRejected || rejectedCells.has(k)) continue;
561
+ const row = mirrorRow(d.data_table_id, d.row_key);
562
+ if (row) row.fields.set(d.field_id, normalizeTypedValue(d.value));
563
+ }
564
+ } else {
565
+ const rejectedTables = new Set((ack.rejected ?? []).filter(r => !r.field_id).map(r => r.data_table_id));
566
+ for (const a of ack.assigned_rows ?? []) assigned.set(a.client_row_key, a.row_key);
567
+ const ops = rowOps.filter(op => op.seq === frame.seq);
568
+ rowOps = rowOps.filter(op => op.seq !== frame.seq);
569
+ for (const op of ops) {
570
+ const t = table(op.table);
571
+ if (!t || frame.mirrorRejected || rejectedTables.has(op.table)) continue;
572
+ if (op.kind === 'append') {
573
+ for (const ck of op.clientKeys) {
574
+ const key = assigned.get(ck);
575
+ if (key && !t.rows.some(r => r.key === key)) {
576
+ t.rows.push({ key, order: Math.max(0, ...t.rows.map(r => r.order)) + 1, state: 'new', fields: new Map() });
577
+ }
578
+ }
579
+ // 新行上的乐观编辑换成 Mirror 行键。
580
+ for (const [k, o] of [...overlays]) {
581
+ const key = assigned.get(o.row);
582
+ if (key) {
583
+ overlays.delete(k);
584
+ overlays.set(cellKey(o.table, key, o.field), { ...o, row: key });
585
+ }
586
+ }
587
+ } else if (op.kind === 'remove') {
588
+ t.rows = t.rows.filter(r => !op.rowKeys.includes(r.key));
589
+ t.rows.forEach((r, i) => (r.order = i + 1));
590
+ } else {
591
+ op.ordered.forEach((key, i) => {
592
+ const r = t.rows.find(x => x.key === key);
593
+ if (r) r.order = i + 1;
594
+ });
595
+ }
596
+ }
597
+ if (frame.mirrorRejected) {
598
+ // 行结构拒写时宿主可能已执行了前面的 op:以 Mirror 为准重拉快照。
599
+ requestSnapshot('row-mirror-rejected');
600
+ }
601
+ // 分配到 Mirror 行键后补发新行上的编辑。
602
+ const ready = deferred.filter(d => assigned.has(d.row_key));
603
+ deferred = deferred.filter(d => !assigned.has(d.row_key));
604
+ if (ready.length > 0) sendFields(ready.map(d => ({ ...d, row_key: assigned.get(d.row_key)! })));
605
+ }
606
+ if ((ack.rejected ?? []).length > 0) {
607
+ report('warn', 'edit rejected by host', { codes: [...new Set((ack.rejected ?? []).map(r => r.code))] });
608
+ emit({ kind: 'rejected', items: ack.rejected ?? [] });
609
+ emit({ kind: 'change', cause: 'reject' });
610
+ } else if (frame.type === 'edit.rows') {
611
+ emit({ kind: 'change', cause: 'assign' });
612
+ }
613
+ };
614
+
615
+ const applyPatch = (patch: EditorMirrorPatch) => {
616
+ const hide = hidden();
617
+ for (const d of patch.fields ?? []) {
618
+ if (hide.has(d.field_id)) continue;
619
+ const row = mirrorRow(d.data_table_id, d.row_key);
620
+ if (row) row.fields.set(d.field_id, normalizeTypedValue(d.value));
621
+ // patch 与在途编辑冲突:以 Mirror 为准。
622
+ overlays.delete(cellKey(d.data_table_id, d.row_key, d.field_id));
623
+ }
624
+ for (const rc of patch.rows ?? []) {
625
+ const t = table(rc.data_table_id);
626
+ if (!t) continue;
627
+ if (rc.kind === 'appended') {
628
+ for (const key of rc.row_keys ?? []) {
629
+ if (!t.rows.some(r => r.key === key)) {
630
+ t.rows.push({ key, order: Math.max(0, ...t.rows.map(r => r.order)) + 1, state: 'new', fields: new Map() });
631
+ }
632
+ }
633
+ } else if (rc.kind === 'removed') {
634
+ const gone = new Set(rc.row_keys ?? []);
635
+ t.rows = t.rows.filter(r => !gone.has(r.key));
636
+ t.rows.forEach((r, i) => (r.order = i + 1));
637
+ } else if (rc.kind === 'reordered') {
638
+ (rc.ordered_row_keys ?? []).forEach((key, i) => {
639
+ const r = t.rows.find(x => x.key === key);
640
+ if (r) r.order = i + 1;
641
+ });
642
+ }
643
+ }
644
+ emit({ kind: 'change', cause: 'patch', patch });
645
+ };
646
+
647
+ const onFrame = (frame: EditorServerFrame) => {
648
+ switch (frame.type) {
649
+ case 'attached': {
650
+ // 新附着(含宿主页断线重连):重发宿主还没确认的帧(宿主按 seq 去重)。
651
+ const clientAck = (frame.body as { client_ack?: number } | undefined)?.client_ack ?? 0;
652
+ for (const p of [...pending.values()].sort((a, b) => a.seq - b.seq)) {
653
+ if (p.seq <= clientAck) continue;
654
+ transportResend(p);
655
+ }
656
+ break;
657
+ }
658
+ case 'ack': {
659
+ const body = frame.body as EditorAckBody;
660
+ const p = pending.get(body.client_seq);
661
+ if (p) {
662
+ pending.delete(body.client_seq);
663
+ settleFrame(p, body);
664
+ }
665
+ notifyFlush();
666
+ break;
667
+ }
668
+ case 'mirror.patch':
669
+ if (status === 'resyncing' && gapTimer === undefined) setStatus('live');
670
+ applyPatch(frame.body as EditorMirrorPatch);
671
+ break;
672
+ case 'snapshot': {
673
+ const snap = normalizeEditorRecordSnapshot(frame.body);
674
+ if (snap) {
675
+ applySnapshot(snap);
676
+ stopGapTimer();
677
+ setStatus('live');
678
+ report('info', 'snapshot applied', { mirror_seq: snap.mirror_seq });
679
+ emit({ kind: 'change', cause: 'snapshot' });
680
+ }
681
+ break;
682
+ }
683
+ case 'resync.required':
684
+ report('warn', 'host requested resync', frame.body as Record<string, unknown>);
685
+ setStatus('resyncing');
686
+ startGapTimer('resync');
687
+ break;
688
+ case 'session.meta':
689
+ meta = normalizeEditorSessionMeta(frame.body);
690
+ emit({ kind: 'meta', meta });
691
+ emit({ kind: 'change', cause: 'meta' });
692
+ break;
693
+ case 'effects':
694
+ emit({ kind: 'effects', envelope: (frame.body as { envelope: EditorEffectEnvelope }).envelope });
695
+ break;
696
+ case 'error': {
697
+ const body = frame.body as { code: string; message?: string; ref_seq?: number };
698
+ report(body.code === 'EDITOR_MIRROR_REJECTED' ? 'warn' : 'error', 'host frame error', { code: body.code, ref_seq: body.ref_seq });
699
+ if (body.code === 'EDITOR_MIRROR_REJECTED' && body.ref_seq && pending.has(body.ref_seq)) {
700
+ pending.get(body.ref_seq)!.mirrorRejected = true;
701
+ } else if (body.code === 'EDITOR_FRAME_PROTOCOL' && body.ref_seq && pending.has(body.ref_seq)) {
702
+ // 协议错误的帧宿主不会再 ack:丢弃并回滚它的乐观状态。
703
+ const p = pending.get(body.ref_seq)!;
704
+ pending.delete(body.ref_seq);
705
+ p.mirrorRejected = true;
706
+ settleFrame(p, { client_seq: p.seq });
707
+ emit({ kind: 'change', cause: 'reject' });
708
+ notifyFlush();
709
+ } else if (body.code === 'EDITOR_RESYNC_REQUIRED') {
710
+ requestSnapshot('snapshot-unavailable');
711
+ }
712
+ emit({ kind: 'error', code: body.code, message: body.message, refSeq: body.ref_seq });
713
+ break;
714
+ }
715
+ default:
716
+ break;
717
+ }
718
+ };
719
+
720
+ const unsubscribe = transport.onEvent(event => {
721
+ if (event.kind === 'frame') onFrame(event.frame);
722
+ else if (event.kind === 'gap') {
723
+ report('warn', 'mirror patch gap detected', { expected: event.expected, received: event.received });
724
+ setStatus('resyncing');
725
+ startGapTimer('gap');
726
+ } else {
727
+ report('error', 'invalid server frame dropped', { error: event.error.message });
728
+ }
729
+ });
730
+ directSocket?.start();
731
+ if (!initial && !directSocket) {
732
+ // 打开应答没带快照(宿主读快照失败):沙箱档请宿主页带 ?snapshot=1 重新附着(宿主不支持时提示重新载入)。
733
+ requestSnapshot('open-without-snapshot');
734
+ }
735
+
736
+ // 发帧:本 helper 自己分配 client seq 并先登记在途,再写通道(同步投递的通道可能在 send 返回前就回 ack)。
737
+ // transport 只用于收帧(外形校验、patch 序号跟踪与缺口检测)。
738
+ const channel: EditorFrameChannel = options.frames ?? directSocket!.channel;
739
+ let clientSeq = 0;
740
+ const writeFrame = (p: PendingFrame) => {
741
+ try {
742
+ const r = channel.send({ v: 1, type: p.type, seq: p.seq, body: p.body } as EditorClientFrame);
743
+ if (r && typeof (r as Promise<void>).then === 'function') {
744
+ (r as Promise<void>).catch(err => report('error', `send ${p.type} failed`, { error: String(err) }));
745
+ }
746
+ } catch (err) {
747
+ report('error', `send ${p.type} failed`, { error: String(err) });
748
+ }
749
+ };
750
+ const transportResend = (p: PendingFrame) => writeFrame(p);
751
+
752
+ const sendFields = (deltas: EditorFieldDelta[]) => {
753
+ const seq = ++clientSeq;
754
+ for (const d of deltas) {
755
+ const k = cellKey(d.data_table_id, d.row_key, d.field_id);
756
+ const o = overlays.get(k);
757
+ if (o) overlays.set(k, { ...o, seq });
758
+ }
759
+ const frame: PendingFrame = { seq, type: 'edit.fields', body: { deltas } };
760
+ pending.set(seq, frame);
761
+ writeFrame(frame);
762
+ return seq;
763
+ };
764
+ const sendRows = (ops: EditorRowOp[], local: (seq: number) => LocalRowOp): number => {
765
+ const seq = ++clientSeq;
766
+ rowOps.push(local(seq));
767
+ const frame: PendingFrame = { seq, type: 'edit.rows', body: { ops } };
768
+ pending.set(seq, frame);
769
+ writeFrame(frame);
770
+ return seq;
771
+ };
772
+
773
+ const isReadonly = () => meta.readonly === true || meta.form_mode === 'view' || (meta.scene !== undefined && meta.scene !== 'form-runtime');
774
+ const isFieldEditable = (fieldId: string) =>
775
+ !isReadonly() &&
776
+ !(meta.hidden_field_ids ?? []).includes(fieldId) &&
777
+ !(meta.readonly_field_ids ?? []).includes(fieldId) &&
778
+ !(meta.derived_readonly_field_ids ?? []).includes(fieldId);
779
+ const canEditRows = (dataTableId: string) => !isReadonly() && !(meta.readonly_table_ids ?? []).includes(dataTableId);
780
+ // 必填只对本步可编辑的字段成立(宿主下发时已扣过一次,这里再按当前 meta 收一次,权限变化重发 meta 后即时生效)。
781
+ const isFieldRequired = (fieldId: string) => (meta.required_field_ids ?? []).includes(fieldId) && isFieldEditable(fieldId);
782
+
783
+ const rowsOf = (dataTableId: string): string[] => {
784
+ const t = table(dataTableId);
785
+ let keys = t ? [...t.rows].sort((a, b) => a.order - b.order).map(r => r.key) : [];
786
+ for (const op of rowOps) {
787
+ if (op.table !== dataTableId) continue;
788
+ if (op.kind === 'append') keys = keys.concat(op.clientKeys.filter(k => !keys.includes(assigned.get(k) ?? k)));
789
+ else if (op.kind === 'remove') keys = keys.filter(k => !op.rowKeys.includes(k));
790
+ else keys = op.ordered.filter(k => keys.includes(k)).concat(keys.filter(k => !op.ordered.includes(k)));
791
+ }
792
+ return keys;
793
+ };
794
+
795
+ const getValue = (t: string, r: string, f: string): EditorTypedValue | undefined => {
796
+ if (hidden().has(f)) return undefined;
797
+ const row = assigned.get(r) ?? r;
798
+ const o = overlays.get(cellKey(t, row, f)) ?? overlays.get(cellKey(t, r, f));
799
+ if (o) return o.value;
800
+ return mirrorRow(t, row)?.fields.get(f);
801
+ };
802
+
803
+ const session: HostMirrorSession = {
804
+ editorSessionId: bound.editorSessionId,
805
+ status: () => status,
806
+ meta: () => meta,
807
+ isReadonly,
808
+ isFieldEditable,
809
+ isFieldRequired,
810
+ canEditRows,
811
+ tables: () => tables.map(t => ({ data_table_id: t.id, role: t.role })),
812
+ rows: rowsOf,
813
+ getValue,
814
+ getText: (t, r, f) => typedValueText(getValue(t, r, f)),
815
+ record: () => ({ recordId, recordVersionNo, mirrorSeq: transport!.lastServerSeq() }),
816
+ setValue(t, r, f, value) {
817
+ if (closed) throw codedError(HOST_MIRROR_ERRORS.SESSION_CLOSED, 'session is closed');
818
+ if (!isFieldEditable(f)) {
819
+ report('debug', 'ignored edit on non-editable field', { field_id: f });
820
+ return false;
821
+ }
822
+ const v = toTypedValue(value);
823
+ const row = assigned.get(r) ?? r;
824
+ const isClientRow = row.startsWith('c:');
825
+ overlays.set(cellKey(t, row, f), { table: t, row, field: f, value: v, seq: 0 });
826
+ emit({ kind: 'change', cause: 'local' });
827
+ const delta: EditorFieldDelta = { data_table_id: t, row_key: row, field_id: f, value: v };
828
+ if (isClientRow) deferred.push(delta);
829
+ else sendFields([delta]);
830
+ return true;
831
+ },
832
+ appendRows(t, count = 1) {
833
+ if (closed) throw codedError(HOST_MIRROR_ERRORS.SESSION_CLOSED, 'session is closed');
834
+ if (!canEditRows(t)) return [];
835
+ const keys = Array.from({ length: Math.max(1, count) }, () => `c:${++clientRowCounter}`);
836
+ sendRows([{ op: 'append', data_table_id: t, client_row_keys: keys }], seq => ({ kind: 'append', table: t, clientKeys: keys, seq }));
837
+ emit({ kind: 'change', cause: 'local' });
838
+ return keys;
839
+ },
840
+ removeRows(t, rowKeys) {
841
+ if (closed || !canEditRows(t) || rowKeys.length === 0) return;
842
+ const keys = rowKeys.map(k => assigned.get(k) ?? k);
843
+ sendRows([{ op: 'remove', data_table_id: t, row_keys: keys }], seq => ({ kind: 'remove', table: t, rowKeys: keys, seq }));
844
+ emit({ kind: 'change', cause: 'local' });
845
+ },
846
+ reorderRows(t, ordered) {
847
+ if (closed || !canEditRows(t) || ordered.length === 0) return;
848
+ const keys = ordered.map(k => assigned.get(k) ?? k);
849
+ sendRows([{ op: 'reorder', data_table_id: t, ordered_row_keys: keys }], seq => ({ kind: 'reorder', table: t, ordered: keys, seq }));
850
+ emit({ kind: 'change', cause: 'local' });
851
+ },
852
+ resolveRowKey: k => assigned.get(k) ?? k,
853
+ pendingCount: () => pending.size + deferred.length,
854
+ flush(timeoutMs = options.flushTimeoutMs ?? 10000) {
855
+ if (pending.size === 0 && deferred.length === 0) return Promise.resolve();
856
+ return new Promise<void>((resolve, reject) => {
857
+ const done = () => {
858
+ flushWaiters.delete(done);
859
+ clearTimer(timer);
860
+ resolve();
861
+ };
862
+ const timer = setTimer(() => {
863
+ flushWaiters.delete(done);
864
+ // 计数含未发出的编辑(新行等宿主分配行键后才补发的字段编辑),与 pendingCount() 同口径。
865
+ const sent = pending.size;
866
+ const unsent = deferred.length;
867
+ reject(codedError(HOST_MIRROR_ERRORS.FLUSH_TIMEOUT, `${sent + unsent} edit(s) not acknowledged (${sent} frame(s) in flight, ${unsent} edit(s) waiting for row keys)`));
868
+ }, timeoutMs);
869
+ flushWaiters.add(done);
870
+ });
871
+ },
872
+ async save(input = {}) {
873
+ if (closed) throw codedError(HOST_MIRROR_ERRORS.SESSION_CLOSED, 'session is closed');
874
+ const recordData = options.recordData;
875
+ if (!recordData || typeof recordData.save !== 'function') {
876
+ throw codedError(HOST_MIRROR_ERRORS.HOST_SAVE_UNAVAILABLE, 'hostBridge.recordData.save is not available');
877
+ }
878
+ await session.flush();
879
+ const mode = input.mode ?? (meta.form_mode === 'edit' || recordId ? 'edit' : 'create');
880
+ const request: Record<string, unknown> = {
881
+ mode,
882
+ clientMutationId: input.clientMutationId ?? `hm-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
883
+ };
884
+ const expected = input.expectedVersionNo ?? (mode === 'edit' ? recordVersionNo : undefined);
885
+ if (typeof expected === 'number' && expected > 0) request.expectedVersionNo = expected;
886
+ if (input.submitAction) request.submitAction = input.submitAction;
887
+ report('info', 'host-driven save requested', { mode });
888
+ let result: HostMirrorSaveResult;
889
+ try {
890
+ result = normalizeHostSaveResult(await recordData.save(request));
891
+ } catch (error) {
892
+ report('error', 'host-driven save failed', { code: (error as { code?: unknown })?.code, error: String(error) });
893
+ throw error;
894
+ }
895
+ if (result.ok) {
896
+ recordId = result.recordId || recordId;
897
+ recordVersionNo = result.versionNo || recordVersionNo;
898
+ if (meta.form_mode === 'create') meta = { ...meta, form_mode: 'edit' };
899
+ report('info', 'host-driven save committed', { record_id: recordId, version_no: recordVersionNo });
900
+ } else {
901
+ report('warn', 'host-driven save rejected by field validation', { field_errors: result.fieldErrors.length });
902
+ }
903
+ return result;
904
+ },
905
+ requestSnapshot,
906
+ on(listener) {
907
+ listeners.add(listener);
908
+ return () => listeners.delete(listener);
909
+ },
910
+ close() {
911
+ if (closed) return;
912
+ stopGapTimer();
913
+ status = 'closed';
914
+ emit({ kind: 'status', status });
915
+ closed = true;
916
+ unsubscribe();
917
+ transport?.close();
918
+ directSocket?.close();
919
+ listeners.clear();
920
+ }
921
+ };
922
+ return session;
923
+ }
924
+
925
+ /** 直连模式的帧通道:自己持有 WS,断线带 ?last_seq= 退避重连,wantSnapshot 时带 ?snapshot=1。 */
926
+ function createDirectChannel(o: {
927
+ attachPath: string;
928
+ connect?: (url: string) => EditorWebSocketLike;
929
+ maxReconnects: number;
930
+ reconnectBaseMs: number;
931
+ setTimer: (fn: () => void, ms: number) => unknown;
932
+ initialSeq: number;
933
+ wantSnapshot: boolean;
934
+ onWarn: (message: string, context?: Record<string, unknown>) => void;
935
+ }) {
936
+ const listeners = new Set<(frame: unknown) => void>();
937
+ const queue: string[] = [];
938
+ let socket: EditorWebSocketLike | undefined;
939
+ let lastSeq = o.initialSeq;
940
+ let wantSnapshot = o.wantSnapshot;
941
+ let attempts = 0;
942
+ let disposed = false;
943
+ let manualReconnect = false;
944
+ const urlFor = () => {
945
+ const params: string[] = [];
946
+ if (wantSnapshot) params.push('snapshot=1');
947
+ else if (lastSeq > 0) params.push(`last_seq=${Math.trunc(lastSeq)}`);
948
+ const sep = o.attachPath.includes('?') ? '&' : '?';
949
+ const path = params.length ? `${o.attachPath}${sep}${params.join('&')}` : o.attachPath;
950
+ if (/^wss?:\/\//.test(path)) return path;
951
+ const loc = (globalThis as { location?: { protocol: string; host: string } }).location;
952
+ return loc ? `${loc.protocol === 'https:' ? 'wss:' : 'ws:'}//${loc.host}${path}` : path;
953
+ };
954
+ const open = () => {
955
+ if (disposed || socket) return;
956
+ const factory = o.connect ?? ((url: string) => new (globalThis as unknown as { WebSocket: new (u: string) => EditorWebSocketLike }).WebSocket(url));
957
+ const ws = factory(urlFor());
958
+ wantSnapshot = false;
959
+ socket = ws;
960
+ ws.onopen = () => {
961
+ attempts = 0;
962
+ for (const text of queue.splice(0)) ws.send(text);
963
+ };
964
+ ws.onmessage = ev => {
965
+ let frame: unknown;
966
+ try {
967
+ frame = typeof ev.data === 'string' ? JSON.parse(ev.data) : ev.data;
968
+ } catch {
969
+ o.onWarn('dropped a non-JSON server frame');
970
+ return;
971
+ }
972
+ const f = frame as { type?: string; body?: { seq?: number; mirror_seq?: number } };
973
+ const seq = f?.type === 'mirror.patch' ? f.body?.seq : f?.type === 'snapshot' ? f.body?.mirror_seq : undefined;
974
+ if (typeof seq === 'number' && seq > lastSeq) lastSeq = seq;
975
+ for (const l of [...listeners]) l(frame);
976
+ };
977
+ ws.onclose = ev => {
978
+ if (socket !== ws) return;
979
+ socket = undefined;
980
+ if (disposed) return;
981
+ if (manualReconnect) {
982
+ manualReconnect = false;
983
+ open();
984
+ return;
985
+ }
986
+ o.onWarn('editor frame socket closed', { code: ev?.code });
987
+ if (attempts < o.maxReconnects) {
988
+ attempts += 1;
989
+ o.setTimer(() => open(), o.reconnectBaseMs * 2 ** (attempts - 1));
990
+ }
991
+ };
992
+ };
993
+ const channel: EditorFrameChannel = {
994
+ send(frame) {
995
+ const text = JSON.stringify(frame);
996
+ if (socket && socket.readyState === 1) socket.send(text);
997
+ else {
998
+ queue.push(text);
999
+ open();
1000
+ }
1001
+ },
1002
+ subscribe(listener) {
1003
+ listeners.add(listener);
1004
+ return () => listeners.delete(listener);
1005
+ }
1006
+ };
1007
+ return {
1008
+ channel,
1009
+ start: open,
1010
+ /** 主动重连(snapshot=true 时带 ?snapshot=1)。 */
1011
+ reconnect(snapshot: boolean) {
1012
+ wantSnapshot = snapshot;
1013
+ if (socket) {
1014
+ manualReconnect = true;
1015
+ try {
1016
+ socket.close(4000, 'editor resync');
1017
+ } catch {
1018
+ manualReconnect = false;
1019
+ socket = undefined;
1020
+ open();
1021
+ }
1022
+ } else open();
1023
+ },
1024
+ close() {
1025
+ disposed = true;
1026
+ listeners.clear();
1027
+ try {
1028
+ socket?.close(1000, 'editor session closed');
1029
+ } catch {
1030
+ // 关闭失败不影响拆除。
1031
+ }
1032
+ socket = undefined;
1033
+ }
1034
+ };
1035
+ }
1036
+
1037
+ // ════════════════════════════ 三、设计态 typed 封装 ════════════════════════════
1038
+
1039
+ /** 设计文件信封自检问题。 */
1040
+ export interface EditorDesignFileProblem {
1041
+ path: string;
1042
+ message: string;
1043
+ }
1044
+
1045
+ /** 信封不合法(错误码 DESIGN_FILE_INVALID,宿主保存同样会 400 拒绝)。 */
1046
+ export class EditorDesignFileError extends Error {
1047
+ code = 'DESIGN_FILE_INVALID' as const;
1048
+ constructor(public readonly problems: EditorDesignFileProblem[]) {
1049
+ super(`DESIGN_FILE_INVALID: ${problems.map(p => `${p.path}: ${p.message}`).join('; ')}`);
1050
+ this.name = 'EditorDesignFileError';
1051
+ }
1052
+ }
1053
+
1054
+ /**
1055
+ * 按 design-file-envelope/1 与宿主保存口径自检信封(与 Go direction/editor.ValidateDesignFile 同规则)。
1056
+ * expectedFormat 给出时(manifest capabilities.editor.design_file_format)另核对 format 相等。
1057
+ */
1058
+ export function validateEditorDesignFile(file: unknown, expectedFormat?: string): EditorDesignFileProblem[] {
1059
+ const out: EditorDesignFileProblem[] = [];
1060
+ if (!isObj(file)) return [{ path: '', message: 'design file must be an object {format, format_version, bindings, payload}' }];
1061
+ const format = file.format;
1062
+ if (typeof format !== 'string' || !/^\S{1,128}$/.test(format)) out.push({ path: '/format', message: 'format must be 1-128 characters without whitespace' });
1063
+ else if (expectedFormat && format !== expectedFormat) out.push({ path: '/format', message: `format ${format} does not match design_file_format ${expectedFormat}` });
1064
+ const fv = file.format_version;
1065
+ if (typeof fv !== 'number' || !Number.isInteger(fv) || fv < 1) out.push({ path: '/format_version', message: 'format_version must be an integer >= 1' });
1066
+ if (!('payload' in file)) out.push({ path: '/payload', message: 'payload is required' });
1067
+ const b = file.bindings;
1068
+ if (!isObj(b) || !Array.isArray(b.tables) || !Array.isArray(b.fields)) {
1069
+ out.push({ path: '/bindings', message: 'bindings must be an object {tables: [], fields: []}' });
1070
+ return out;
1071
+ }
1072
+ const tableIds = new Set<string>();
1073
+ let mains = 0;
1074
+ b.tables.forEach((t, i) => {
1075
+ const at = `/bindings/tables/${i}`;
1076
+ if (!isObj(t)) return out.push({ path: at, message: 'table binding must be an object' });
1077
+ const id = t.data_table_id;
1078
+ if (typeof id !== 'string' || id.length < 1 || id.length > 128) out.push({ path: `${at}/data_table_id`, message: 'data_table_id must be 1-128 characters' });
1079
+ else if (tableIds.has(id)) out.push({ path: `${at}/data_table_id`, message: `data_table_id ${id} is duplicated` });
1080
+ else tableIds.add(id);
1081
+ if (t.role !== 'main' && t.role !== 'detail') out.push({ path: `${at}/role`, message: 'role must be main or detail' });
1082
+ if (t.role === 'main') mains += 1;
1083
+ if (t.anchor !== undefined && (typeof t.anchor !== 'string' || t.anchor.length > 512)) out.push({ path: `${at}/anchor`, message: 'anchor must be a string of at most 512 characters' });
1084
+ return undefined;
1085
+ });
1086
+ if (b.tables.length > 0 && mains !== 1) out.push({ path: '/bindings/tables', message: `exactly one table must have role=main, got ${mains}` });
1087
+ const fieldIds = new Set<string>();
1088
+ b.fields.forEach((f, i) => {
1089
+ const at = `/bindings/fields/${i}`;
1090
+ if (!isObj(f)) return out.push({ path: at, message: 'field binding must be an object' });
1091
+ if (typeof f.field_id !== 'string' || f.field_id.length < 1 || f.field_id.length > 128) out.push({ path: `${at}/field_id`, message: 'field_id must be 1-128 characters' });
1092
+ else if (fieldIds.has(f.field_id)) out.push({ path: `${at}/field_id`, message: `field_id ${f.field_id} is duplicated` });
1093
+ else fieldIds.add(f.field_id);
1094
+ if (typeof f.data_table_id !== 'string' || !tableIds.has(f.data_table_id)) out.push({ path: `${at}/data_table_id`, message: 'data_table_id must be listed in bindings.tables' });
1095
+ if (typeof f.anchor !== 'string' || f.anchor.trim() === '' || f.anchor.length > 512) out.push({ path: `${at}/anchor`, message: 'anchor must be 1-512 non-blank characters' });
1096
+ return undefined;
1097
+ });
1098
+ return out;
1099
+ }
1100
+
1101
+ /** 已退役、不能新建的字段数据类型(date 用 datetime,boolean 用 text 或 number)。 */
1102
+ export const RETIRED_FIELD_DATA_TYPES = ['boolean', 'date'] as const;
1103
+
1104
+ /** typed 设计态客户端。 */
1105
+ export interface EditorDesignClient {
1106
+ /** 打开设计文档:design_file 为信封(新建空文档为 null)。 */
1107
+ open(): Promise<EditorDesignDocumentV1>;
1108
+ /** 保存信封(先自检,不合法抛 EditorDesignFileError,不发请求)。 */
1109
+ save(input: { expectedVersionNo: number; designFile: EditorDesignFile }): Promise<EditorDesignDocumentV1>;
1110
+ defineMainTableFields(input: { fields: Array<Record<string, unknown>> }): Promise<EditorDefineFieldsResult>;
1111
+ defineExtensionTable(input: Record<string, unknown>): Promise<EditorDefineFieldsResult>;
1112
+ defineExtensionTableFields(input: { dataTableId: string; fields: Array<Record<string, unknown>> }): Promise<EditorDefineFieldsResult>;
1113
+ loadExpressionCatalog?(): Promise<unknown>;
1114
+ openActionDesigner?(): Promise<void>;
1115
+ /** 读模板已有表与字段(含未落位字段)。宿主没有该方法时不出现。 */
1116
+ listTemplateModel?(): Promise<EditorTemplateModel>;
1117
+ /** 写字段属性:先拦退役数据类型,再交宿主按字段模型校验。宿主没有该方法时不出现。 */
1118
+ updateFields?(input: { dataTableId: string; fields: EditorFieldPropertyPatch[] }): Promise<EditorFieldChangeResult>;
1119
+ /** 删字段:宿主预检有引用 / 有数据时抛 EDITOR_FIELD_DELETE_BLOCKED。宿主没有该方法时不出现。 */
1120
+ deleteFields?(input: { dataTableId: string; fields: Array<{ fieldId: string; expectedVersionNo: number }> }): Promise<EditorFieldChangeResult>;
1121
+ }
1122
+
1123
+ /** 解开宿主桥结果(沙箱档可能是 {data, error} 纯数据信封)。 */
1124
+ async function unwrap<T>(p: unknown, what: string): Promise<T> {
1125
+ const v = await p;
1126
+ if (isObj(v) && 'data' in v && 'error' in v && Object.keys(v).length === 2) {
1127
+ if (v.error) {
1128
+ const e = v.error as { message?: unknown };
1129
+ // 统一还原为带 .code / .params 的 HostBridgeCallError;宿主没给文案时用「<操作> failed」。
1130
+ throw hostBridgeErrorFrom(typeof e.message === 'string' && e.message ? v.error : { ...(v.error as object), message: `${what} failed` });
1131
+ }
1132
+ return v.data as T;
1133
+ }
1134
+ return v as T;
1135
+ }
1136
+
1137
+ /** 把宿主设计文档回包归一(design_file 优先,退到形如信封的 workbook 键)。 */
1138
+ export function normalizeEditorDesignDocument(raw: unknown): EditorDesignDocumentV1 {
1139
+ const o = isObj(raw) ? raw : {};
1140
+ const candidate = pick(o, 'design_file') ?? o.workbook;
1141
+ const envelope = isObj(candidate) && 'format' in candidate && 'bindings' in candidate ? (candidate as unknown as EditorDesignFile) : null;
1142
+ return {
1143
+ document_id: str(pick(o, 'document_id')) ?? '',
1144
+ template_id: str(pick(o, 'template_id')) ?? '',
1145
+ template_version_no: str(pick(o, 'template_version_no')) ?? '',
1146
+ designer_type: str(pick(o, 'designer_type')) ?? '',
1147
+ plugin_id: str(pick(o, 'plugin_id')) ?? '',
1148
+ document_status: str(pick(o, 'document_status')) ?? '',
1149
+ content_revision: num(pick(o, 'content_revision')) ?? 0,
1150
+ version_no: num(pick(o, 'version_no')) ?? 0,
1151
+ ...(pick(o, 'read_only') === true ? { read_only: true } : {}),
1152
+ design_file: envelope,
1153
+ ...(Array.isArray(pick(o, 'diagnostics')) ? { diagnostics: pick(o, 'diagnostics') as EditorDesignDocumentV1['diagnostics'] } : {})
1154
+ };
1155
+ }
1156
+
1157
+ function guardFieldTypes(fields: unknown): void {
1158
+ for (const f of Array.isArray(fields) ? fields : []) {
1159
+ const t = isObj(f) ? f.data_type : undefined;
1160
+ if (typeof t === 'string' && (RETIRED_FIELD_DATA_TYPES as readonly string[]).includes(t)) {
1161
+ throw Object.assign(new Error(`FIELD_DATA_TYPE_RETIRED: data_type ${t} is retired (use datetime / text / number)`), { code: 'FIELD_DATA_TYPE_RETIRED' });
1162
+ }
1163
+ }
1164
+ }
1165
+
1166
+ /**
1167
+ * createEditorDesignClient —— 设计态桥 hostBridge.designData 的 typed 封装。
1168
+ * @param designData 宿主桥 designData(同源档 / 沙箱档都可)
1169
+ * @param options.designFileFormat manifest capabilities.editor.design_file_format(保存前核对信封 format)
1170
+ */
1171
+ export function createEditorDesignClient(designData: unknown, options: { designFileFormat?: string } = {}): EditorDesignClient {
1172
+ const bridge = (designData ?? {}) as Record<string, ((...a: unknown[]) => unknown) | undefined>;
1173
+ const call = (method: string, ...args: unknown[]) => {
1174
+ const fn = bridge[method];
1175
+ if (typeof fn !== 'function') throw Object.assign(new Error(`designData.${method} is not available`), { code: 'EDITOR_DESIGN_BRIDGE_UNAVAILABLE' });
1176
+ return fn.apply(bridge, args);
1177
+ };
1178
+ const client: EditorDesignClient = {
1179
+ async open() {
1180
+ return normalizeEditorDesignDocument(await unwrap(call('open'), 'open design'));
1181
+ },
1182
+ async save(input) {
1183
+ const problems = validateEditorDesignFile(input.designFile, options.designFileFormat);
1184
+ if (problems.length > 0) throw new EditorDesignFileError(problems);
1185
+ return normalizeEditorDesignDocument(await unwrap(call('save', { expectedVersionNo: input.expectedVersionNo, designFile: input.designFile }), 'save design'));
1186
+ },
1187
+ async defineMainTableFields(input) {
1188
+ guardFieldTypes(input.fields);
1189
+ const method = typeof bridge.defineMainTableFields === 'function' ? 'defineMainTableFields' : 'defineFields';
1190
+ return unwrap<EditorDefineFieldsResult>(call(method, input), 'define fields');
1191
+ },
1192
+ async defineExtensionTable(input) {
1193
+ guardFieldTypes(input.fields);
1194
+ return unwrap<EditorDefineFieldsResult>(call('defineExtensionTable', input), 'define extension table');
1195
+ },
1196
+ async defineExtensionTableFields(input) {
1197
+ guardFieldTypes(input.fields);
1198
+ return unwrap<EditorDefineFieldsResult>(call('defineExtensionTableFields', input), 'define extension table fields');
1199
+ }
1200
+ };
1201
+ if (typeof bridge.loadExpressionCatalog === 'function') client.loadExpressionCatalog = () => unwrap(call('loadExpressionCatalog'), 'load expression catalog');
1202
+ if (typeof bridge.openActionDesigner === 'function') client.openActionDesigner = async () => void (await call('openActionDesigner'));
1203
+ // 模板模型读与字段属性写,只在宿主桥提供时出现(旧宿主不出现,编辑器按有无降级)。
1204
+ if (typeof bridge.listTemplateModel === 'function') client.listTemplateModel = () => unwrap<EditorTemplateModel>(call('listTemplateModel'), 'list template model');
1205
+ if (typeof bridge.updateFields === 'function') {
1206
+ client.updateFields = async input => {
1207
+ // 改数据类型同样不得指向已退役的 boolean / date(与建字段同一闸)。
1208
+ guardFieldTypes((input.fields ?? []).map(f => ({ data_type: f.dataType })));
1209
+ return unwrap<EditorFieldChangeResult>(call('updateFields', input), 'update fields');
1210
+ };
1211
+ }
1212
+ if (typeof bridge.deleteFields === 'function') client.deleteFields = input => unwrap<EditorFieldChangeResult>(call('deleteFields', input), 'delete fields');
1213
+ return client;
1214
+ }