@lynx-js/lynx-runtime 0.0.0-stage → 0.0.1

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 (54) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +354 -2
  3. package/dist/bts/data.d.ts +1 -0
  4. package/dist/bts/data.js +28 -0
  5. package/dist/bts/events.d.ts +1 -0
  6. package/dist/bts/events.js +57 -0
  7. package/dist/bts/scope.d.ts +1 -0
  8. package/dist/bts/scope.js +129 -0
  9. package/dist/bts/services.d.ts +1 -0
  10. package/dist/bts/services.js +34 -0
  11. package/dist/bts.d.ts +14 -0
  12. package/dist/bts.js +30 -0
  13. package/dist/common/host-types.d.ts +1 -0
  14. package/dist/common/host-types.js +1 -0
  15. package/dist/common/messages.d.ts +1 -0
  16. package/dist/common/messages.js +69 -0
  17. package/dist/common/performance.d.ts +1 -0
  18. package/dist/common/performance.js +26 -0
  19. package/dist/common/protocol.d.ts +20 -0
  20. package/dist/common/protocol.js +53 -0
  21. package/dist/common/types.d.ts +203 -0
  22. package/dist/common/types.js +1 -0
  23. package/dist/iife/bts.js +1 -0
  24. package/dist/iife/mts.js +1 -0
  25. package/dist/index.d.ts +16 -0
  26. package/dist/index.js +1 -0
  27. package/dist/mts/data.d.ts +71 -0
  28. package/dist/mts/data.js +46 -0
  29. package/dist/mts/flush.d.ts +11 -0
  30. package/dist/mts/flush.js +16 -0
  31. package/dist/mts/host.d.ts +35 -0
  32. package/dist/mts/host.js +124 -0
  33. package/dist/mts/services.d.ts +21 -0
  34. package/dist/mts/services.js +46 -0
  35. package/dist/mts.d.ts +5 -0
  36. package/dist/mts.js +4 -0
  37. package/package.json +57 -3
  38. package/skills/lynx-runtime/SKILL.md +67 -0
  39. package/src/bts/data.ts +94 -0
  40. package/src/bts/events.ts +100 -0
  41. package/src/bts/scope.ts +279 -0
  42. package/src/bts/services.ts +88 -0
  43. package/src/bts.ts +110 -0
  44. package/src/common/host-types.ts +161 -0
  45. package/src/common/messages.ts +129 -0
  46. package/src/common/performance.ts +65 -0
  47. package/src/common/protocol.ts +98 -0
  48. package/src/common/types.ts +259 -0
  49. package/src/index.ts +35 -0
  50. package/src/mts/data.ts +200 -0
  51. package/src/mts/flush.ts +50 -0
  52. package/src/mts/host.ts +297 -0
  53. package/src/mts/services.ts +102 -0
  54. package/src/mts.ts +36 -0
@@ -0,0 +1,259 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ /** Idempotently remove this registration; does not destroy its page or restore a previous owner. */
6
+ export type Unsubscribe = () => void;
7
+
8
+ export interface LynxSystemInfo {
9
+ platform?: string | undefined;
10
+ pixelRatio?: number | undefined;
11
+ pixelWidth?: number | undefined;
12
+ pixelHeight?: number | undefined;
13
+ lynxSdkVersion?: string | undefined;
14
+ engineVersion?: string | undefined;
15
+ osVersion?: string | undefined;
16
+ runtimeType?: string | undefined;
17
+ theme?: Record<string, unknown> | undefined;
18
+ [key: string]: unknown;
19
+ }
20
+
21
+ export interface CreatePipelineOptions {
22
+ pipelineOrigin?: string | undefined;
23
+ needTimestamps?: boolean | undefined;
24
+ timingFlag?: string | undefined;
25
+ dsl?: string | undefined;
26
+ stage?: string | undefined;
27
+ }
28
+
29
+ export interface PipelineOptions {
30
+ pipelineID?: string | undefined;
31
+ pipelineOrigin?: string | undefined;
32
+ needTimestamps?: boolean | undefined;
33
+ dsl?: string | undefined;
34
+ stage?: string | undefined;
35
+ [key: string]: unknown;
36
+ }
37
+
38
+ /** A successfully created host pipeline, with a usable identifier. */
39
+ export interface CreatedPipelineOptions extends PipelineOptions {
40
+ pipelineID: string;
41
+ }
42
+
43
+ export interface MTSRenderOptions {
44
+ processorName?: string | undefined;
45
+ preLoadTemplate?: boolean | undefined;
46
+ pipelineOptions?: PipelineOptions | undefined;
47
+ initPage?: unknown;
48
+ }
49
+
50
+ /**
51
+ * Host pass-through context carried from MTS lifecycle callbacks into `flushElementTree`.
52
+ * Keep this context with its work, including when submission is deferred.
53
+ */
54
+ export interface MTSFlushContext {
55
+ /** Preserve the originating host reload context when submitting its changes. */
56
+ reloadTemplate?: boolean | undefined;
57
+ /** Preserve the host update sequence when forwarding or deferring a flush. */
58
+ nativeUpdateDataOrder?: number | undefined;
59
+ pipelineOptions?: PipelineOptions | undefined;
60
+ }
61
+
62
+ /**
63
+ * Context for one host page data update or reset. Keep this context with its work
64
+ * and pass it to `flushElementTree`, including when submission is deferred.
65
+ */
66
+ export interface MTSUpdateOptions extends MTSFlushContext {
67
+ /** Replace current page data rather than merging an incremental update. */
68
+ resetPageData?: boolean | undefined;
69
+ processorName?: string | undefined;
70
+ triggerLifeCycle?: boolean | undefined;
71
+ }
72
+
73
+ /**
74
+ * Context for one host template reload on MTS. Keep this context with its work
75
+ * and pass it to `flushElementTree`, including when submission is deferred.
76
+ */
77
+ export interface MTSReloadOptions extends MTSUpdateOptions {
78
+ /** Reload the template and replace the initial-input baseline. */
79
+ reloadTemplate?: boolean | undefined;
80
+ /** The host reload originated from JS. */
81
+ reloadFromJS?: boolean | undefined;
82
+ }
83
+
84
+ export interface MTSFlushOptions extends MTSFlushContext {
85
+ /** Timing flag associated with the active performance pipeline. */
86
+ timingFlag?: string | undefined;
87
+ /** Request layout (Native default: true). */
88
+ triggerLayout?: boolean | undefined;
89
+ /** Request the client OnDataUpdated callback (Native default: false). */
90
+ triggerDataUpdated?: boolean | undefined;
91
+ /** Allow the unified pixel pipeline to skip resolving an empty patch. */
92
+ emptyPatch?: boolean | undefined;
93
+ }
94
+
95
+ export interface BTSUpdateOptions {
96
+ /** Replace current page data rather than merging an incremental update. */
97
+ resetPageData?: boolean | undefined;
98
+ processorName?: string | undefined;
99
+ }
100
+
101
+ export interface BTSReloadOptions {
102
+ processorName?: string | undefined;
103
+ }
104
+
105
+ export type BTSEventHandler<T = unknown> = (
106
+ this: void,
107
+ handlerName: string,
108
+ data: T,
109
+ componentId?: string,
110
+ ) => unknown;
111
+
112
+ /** Capabilities bound to one host App instance; retain this handle across asynchronous work. */
113
+ export interface BTSPageRuntime {
114
+ /**
115
+ * True from the start of BTS page destruction, including inside teardown callbacks.
116
+ *
117
+ * @since Lynx 2.14
118
+ */
119
+ isDestroyed(this: void): boolean;
120
+ getSystemInfo(this: void): Readonly<LynxSystemInfo>;
121
+ createPipeline(
122
+ this: void,
123
+ options?: CreatePipelineOptions,
124
+ ): CreatedPipelineOptions | undefined;
125
+ markTiming(
126
+ this: void,
127
+ pipeline: string | PipelineOptions | undefined,
128
+ timingKey: string,
129
+ ): void;
130
+ /** Host ID captured at binding; empty when the host provides no ID. */
131
+ getId(this: void): string;
132
+ /**
133
+ * Detached records and arrays for mutable DSL state; opaque values remain shared.
134
+ * Overlays the current round's processed initial or `onReload` `TemplateData`
135
+ * onto the template's static `_params.initData` (`encoded_data`), replacing
136
+ * previous dynamic keys across reloads while preserving static template keys.
137
+ * Incremental updates do not change this baseline. Remains readable after destruction.
138
+ */
139
+ getInitData<T = Record<string, unknown>>(this: void): T;
140
+ /**
141
+ * Borrow the bound page's current host GlobalProps without copying
142
+ * (defaults to `{}` when the host has not injected GlobalProps).
143
+ * Treat the entire value as read-only, including nested objects; Readonly is
144
+ * shallow and no freeze is applied. If a DSL mutates its own root GlobalProps
145
+ * object in place (e.g. via `Object.assign`), shallow-copy
146
+ * `{ ...page.getGlobalProps() }` during bootstrap.
147
+ * Tracked automatically from `bindPage()` and remains readable after destruction.
148
+ */
149
+ getGlobalProps<T = Record<string, unknown>>(this: void): Readonly<T>;
150
+ /** Subscribe to host GlobalProps updates without replaying earlier notifications. */
151
+ onGlobalPropsChanged<T = Record<string, unknown>>(
152
+ this: void,
153
+ listener: (globalProps: Readonly<T>) => void,
154
+ ): Unsubscribe;
155
+ /**
156
+ * Subscribe to host incremental data updates and `resetPageData` replacements on BTS.
157
+ *
158
+ * @remarks
159
+ * Subscribes directly to the page's `tt.updateCardData` callback without an
160
+ * MTS-to-BTS forwarding bridge (requires `REACT_NODIFF` bundle DSL on Native,
161
+ * used by standard Rspeedy/ReactLynx, `@lynx-js/rspeedy` Vanilla, and `.lynxml`
162
+ * on hosts that build LynxML bundles as `REACT_NODIFF`; legacy
163
+ * `PackageInstanceDSL::REACT` bundles skip BTS `updateCardData`).
164
+ * Payloads are read-only. The DSL owns merge/reset state and rendering;
165
+ * registering a listener does not replay earlier updates.
166
+ */
167
+ onUpdateData<T = Record<string, unknown>>(
168
+ this: void,
169
+ listener: (data: Readonly<T>, options: Readonly<BTSUpdateOptions>) => void,
170
+ ): Unsubscribe;
171
+ /**
172
+ * Subscribe to host template reloads on BTS (`tt.onAppReload`).
173
+ * Runtime refreshes `getInitData()` by overlaying the reload payload onto
174
+ * template static `_params.initData` before invoking listeners.
175
+ * A reload notification alone does not destroy the bound App or retire DSL resources.
176
+ */
177
+ onReload<T = Record<string, unknown>>(
178
+ this: void,
179
+ listener: (data: Readonly<T>, options: Readonly<BTSReloadOptions>) => void,
180
+ ): Unsubscribe;
181
+ onConfigChanged<T = Record<string, unknown>>(
182
+ this: void,
183
+ listener: (config: Readonly<T>) => void,
184
+ ): Unsubscribe;
185
+ onEnterForeground(this: void, listener: () => void): Unsubscribe;
186
+ onEnterBackground(this: void, listener: () => void): Unsubscribe;
187
+ /**
188
+ * Subscribe to host global events delivered to this page's `GlobalEventEmitter`
189
+ * (such as client `sendGlobalEvent`, `exposure` / `disexposure`, and
190
+ * `keyboardstatuschanged`) while the page and emitter are available.
191
+ *
192
+ * @remarks
193
+ * Resolves `GlobalEventEmitter` from the bound page so asynchronous subscriptions
194
+ * in a shared `LynxGroup` context remain isolated from peer pages. Shares one host
195
+ * listener per event `name` on this page, deduplicates identical `(name, listener)`
196
+ * callbacks, forwards all positional arguments with `undefined` `this`, and removes
197
+ * all listeners before DSL `onDestroy` callbacks run. Does not replay earlier events
198
+ * or validate `Args` at runtime; dispose when an owning entry retires across in-place
199
+ * reloads (`onReload`).
200
+ */
201
+ onGlobalEvent<Args extends unknown[] = unknown[]>(
202
+ this: void,
203
+ name: string,
204
+ listener: (this: void, ...args: Args) => void,
205
+ ): Unsubscribe;
206
+ /**
207
+ * Claim both raw page and component event slots with one synchronous handler.
208
+ * Latest registration wins; disposal clears the current handler without restoring
209
+ * an earlier owner. Page events have no componentId; component events retain it.
210
+ * Return values and exceptions pass through to the host (synchronous return values
211
+ * are consumed on Native; Web event RPC is one-way); Promises are not awaited
212
+ * and false is ordinary data, not cancellation. Register only while the page is alive.
213
+ */
214
+ setEventHandler<T = unknown>(
215
+ this: void,
216
+ handler: BTSEventHandler<T>,
217
+ ): Unsubscribe;
218
+ /**
219
+ * Send to this bound page's MTS; returns no receipt and does not wait for execution.
220
+ * Requires a live page and its host peer proxy. Install the receiver before sending:
221
+ * there is no startup queue, retry, RPC, or cross-type ordering guarantee.
222
+ * T constrains the caller only; it does not validate the peer's payload.
223
+ */
224
+ sendMessage<T = undefined>(
225
+ this: void,
226
+ type: string,
227
+ ...args: undefined extends T ? [data?: T] : [data: T]
228
+ ): void;
229
+ /**
230
+ * Subscribe to raw payloads from this page's MTS while the page and proxy are available.
231
+ * Identical callbacks for a type share a registration. Dispose when the owning entry
232
+ * retires; page destruction also removes listeners. No replay or payload validation.
233
+ */
234
+ onMessage<T = unknown>(
235
+ this: void,
236
+ type: string,
237
+ listener: (this: void, data: T) => void,
238
+ ): Unsubscribe;
239
+ /**
240
+ * Subscribe to BTS page destruction.
241
+ *
242
+ * @remarks
243
+ * Supported across **Lynx SDK 2.14+** on Native (`tt.callDestroyLifetimeFun`)
244
+ * and on Web. Do not also register a `lynx.getNative()` `__DestroyLifetime`
245
+ * listener on BTS, as Native skips `tt.callDestroyLifetimeFun` when one is present.
246
+ * Use this hook to deterministically release page-scoped timers, subscriptions,
247
+ * and shared `LynxGroup` background resources when a page instance is destroyed.
248
+ *
249
+ * Host template reload (`onReload`) does **not** trigger host destruction unless
250
+ * the DSL explicitly invokes `callDestroyLifetimeFun()` before `reloadCard()`.
251
+ * Runtime objects recreated across in-place reloads must invoke the returned
252
+ * `Unsubscribe` disposer when retiring so listeners do not accumulate.
253
+ *
254
+ * @param listener - Callback invoked synchronously when BTS page destruction begins.
255
+ * @returns An idempotent disposer that unsubscribes `listener`.
256
+ * @since Lynx 2.14
257
+ */
258
+ onDestroy(this: void, listener: () => void): Unsubscribe;
259
+ }
package/src/index.ts ADDED
@@ -0,0 +1,35 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ /**
6
+ * Shared TypeScript types for `@lynx-js/lynx-runtime`.
7
+ *
8
+ * @remarks
9
+ * **Preview (`0.0.x`):** This package is in early preview prior to formal RFC
10
+ * stabilization and does not yet guarantee public API stability across `0.x` releases.
11
+ *
12
+ * Import shared types from `@lynx-js/lynx-runtime`, main-thread runtime functions
13
+ * from `@lynx-js/lynx-runtime/mts`, and background-thread page binding from
14
+ * `@lynx-js/lynx-runtime/bts`. In dual-thread shared modules, guard `/mts` and
15
+ * `/bts` runtime calls behind compile-time thread constants (such as `__LEPUS__`
16
+ * and `__JS__`) so bundler dead-code elimination strips cross-thread imports.
17
+ *
18
+ * @packageDocumentation
19
+ */
20
+ export type {
21
+ BTSEventHandler,
22
+ BTSPageRuntime,
23
+ BTSReloadOptions,
24
+ BTSUpdateOptions,
25
+ CreatedPipelineOptions,
26
+ CreatePipelineOptions,
27
+ LynxSystemInfo,
28
+ MTSFlushContext,
29
+ MTSFlushOptions,
30
+ MTSReloadOptions,
31
+ MTSRenderOptions,
32
+ MTSUpdateOptions,
33
+ PipelineOptions,
34
+ Unsubscribe,
35
+ } from './common/types.js';
@@ -0,0 +1,200 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ import {
6
+ defaultGetPageData,
7
+ defaultProcessData,
8
+ getAliveMTSState,
9
+ initMTSHostState,
10
+ } from './host.js';
11
+ import type { MTSSingleOwnerKey } from './host.js';
12
+ import type { HostGlobalScope } from '../common/host-types.js';
13
+ import { copyHostData, subscribeListener } from '../common/protocol.js';
14
+ import type {
15
+ MTSFlushContext,
16
+ MTSReloadOptions,
17
+ MTSRenderOptions,
18
+ MTSUpdateOptions,
19
+ Unsubscribe,
20
+ } from '../common/types.js';
21
+
22
+ function registerSingleOwnerSlot<
23
+ K extends MTSSingleOwnerKey,
24
+ TFn extends NonNullable<HostGlobalScope[K]>,
25
+ >(
26
+ slotKey: K,
27
+ defaultFn: TFn,
28
+ handler: TFn,
29
+ ): Unsubscribe {
30
+ const host = globalThis as unknown as HostGlobalScope;
31
+ const state = getAliveMTSState(host);
32
+ state.slots[slotKey] = handler;
33
+ host[slotKey] = handler;
34
+ return () => {
35
+ if (state.slots[slotKey] !== handler) {
36
+ return;
37
+ }
38
+ state.slots[slotKey] = undefined;
39
+ if (host[slotKey] === handler) {
40
+ host[slotKey] = defaultFn;
41
+ }
42
+ };
43
+ }
44
+
45
+ /**
46
+ * Read a detached copy of the initial page data records and arrays on MTS.
47
+ * Opaque objects remain shared by reference.
48
+ * Updated on first-screen `renderPage` and on `reloadTemplate` updates,
49
+ * and isolated from runtime mutations to `lynx.__initData`.
50
+ * Ensure the MTS runtime is initialized during synchronous bootstrap before the
51
+ * first host input arrives; incremental updates do not change this baseline.
52
+ * Remains readable after destruction.
53
+ */
54
+ export function getInitData<T = Record<string, unknown>>(): T {
55
+ const state = initMTSHostState(globalThis as unknown as HostGlobalScope);
56
+ return copyHostData(state.initData) as T;
57
+ }
58
+
59
+ /**
60
+ * Borrow the current host `GlobalProps` without copying (defaults to `{}` when unset).
61
+ * Treat the entire value as read-only, including nested objects; Readonly is shallow
62
+ * and no freeze is applied. If a DSL mutates its own root `GlobalProps` object in place
63
+ * (e.g. `Object.assign`), shallow-copy `{ ...getGlobalProps() }` at startup.
64
+ * During and after destruction, read the captured final properties.
65
+ */
66
+ export function getGlobalProps<T = Record<string, unknown>>(): Readonly<T> {
67
+ const host = globalThis as unknown as HostGlobalScope;
68
+ const state = initMTSHostState(host);
69
+ if (state.destroyed) {
70
+ return state.globalProps as Readonly<T>;
71
+ }
72
+ return (host.lynx?.__globalProps ?? state.globalProps) as Readonly<T>;
73
+ }
74
+
75
+ /**
76
+ * Subscribe to first-screen render on MTS.
77
+ * Register synchronously before the first host input.
78
+ * Input is read-only and not replayed. The host submits the first screen on return.
79
+ */
80
+ export function onRenderPage<T = Record<string, unknown>>(
81
+ listener: (data: Readonly<T>, options: Readonly<MTSRenderOptions>) => void,
82
+ ): Unsubscribe {
83
+ const state = getAliveMTSState(globalThis as unknown as HostGlobalScope);
84
+ return subscribeListener(
85
+ state.renderListeners,
86
+ listener as (
87
+ data: Record<string, unknown>,
88
+ options: MTSRenderOptions,
89
+ ) => void,
90
+ );
91
+ }
92
+
93
+ /**
94
+ * Subscribe to host page data updates and resets on MTS (`!options.reloadTemplate`).
95
+ * `resetPageData` replaces current data rather than merging an incremental update.
96
+ * Preserve these options with the work and pass them to `flushElementTree` when
97
+ * submitting its changes.
98
+ * Register before host input; input is read-only, not replayed, and not automatically merged into DSL state.
99
+ */
100
+ export function onUpdateData<T = Record<string, unknown>>(
101
+ listener: (data: Readonly<T>, options: Readonly<MTSUpdateOptions>) => void,
102
+ ): Unsubscribe {
103
+ const state = getAliveMTSState(globalThis as unknown as HostGlobalScope);
104
+ return subscribeListener(
105
+ state.updateListeners,
106
+ listener as (
107
+ data: Record<string, unknown>,
108
+ options: MTSUpdateOptions,
109
+ ) => void,
110
+ );
111
+ }
112
+
113
+ /**
114
+ * Subscribe to host template reloads on MTS (`options.reloadTemplate === true`).
115
+ * Runtime refreshes `getInitData()` before invoking reload listeners. Preserve
116
+ * these options with the work and pass them to `flushElementTree` when submitting
117
+ * its changes.
118
+ * Reload does not imply page destruction or cleanup of the previous DSL entry.
119
+ */
120
+ export function onReload<T = Record<string, unknown>>(
121
+ listener: (data: Readonly<T>, options: Readonly<MTSReloadOptions>) => void,
122
+ ): Unsubscribe {
123
+ const state = getAliveMTSState(globalThis as unknown as HostGlobalScope);
124
+ return subscribeListener(
125
+ state.reloadListeners,
126
+ listener as (
127
+ data: Record<string, unknown>,
128
+ options: MTSReloadOptions,
129
+ ) => void,
130
+ );
131
+ }
132
+
133
+ /**
134
+ * Subscribe to host `GlobalProps` updates on MTS.
135
+ * Treat the delivered object as read-only; mutating it affects shared host state.
136
+ * Notifications are not replayed. Pass options to flushElementTree after applying
137
+ * the update, including updates that leave the element tree unchanged.
138
+ */
139
+ export function onGlobalPropsChanged<T = Record<string, unknown>>(
140
+ listener: (
141
+ globalProps: Readonly<T>,
142
+ options?: Readonly<MTSFlushContext>,
143
+ ) => void,
144
+ ): Unsubscribe {
145
+ const state = getAliveMTSState(globalThis as unknown as HostGlobalScope);
146
+ return subscribeListener(
147
+ state.globalPropsListeners,
148
+ listener as (
149
+ globalProps: Record<string, unknown>,
150
+ options?: MTSFlushContext,
151
+ ) => void,
152
+ );
153
+ }
154
+
155
+ /**
156
+ * Register the synchronous single-owner MTS host `processData` hook.
157
+ * Native consumes its return value immediately; PromiseLike results are rejected.
158
+ * Normalizes Native's absent `TemplateData` (`undefined` / `null`) to `{}` and
159
+ * empty default `processorName` (`""`) to `undefined` across Native and Web.
160
+ * Registering a new processor replaces the previous active processor; unsubscribing
161
+ * the active processor or destroying the page restores the identity processor.
162
+ * Install before the host processes its first input; it cannot retroactively process
163
+ * earlier data. Disposing a replaced registration does not affect the current owner.
164
+ */
165
+ export function setDataProcessor<
166
+ TInput = Record<string, unknown>,
167
+ TOutput = Record<string, unknown>,
168
+ >(
169
+ processor: (
170
+ data: TInput,
171
+ processorName?: string,
172
+ ) => TOutput & ({ then?: never } | null | undefined),
173
+ ): Unsubscribe {
174
+ return registerSingleOwnerSlot(
175
+ 'processData',
176
+ defaultProcessData,
177
+ (data: unknown, processorName?: string): unknown =>
178
+ processor(
179
+ (data ?? {}) as TInput,
180
+ processorName === '' ? undefined : processorName,
181
+ ),
182
+ );
183
+ }
184
+
185
+ /**
186
+ * Register the synchronous single-owner MTS `getPageData` hook
187
+ * (PromiseLike results are rejected),
188
+ * invoked by Native `GetCurrentData` / `GetPageDataByKey` to query the DSL's current state.
189
+ * Install before host queries. Latest registration wins; disposing the active getter
190
+ * restores null, not the previous getter. Does not create or maintain DSL state.
191
+ */
192
+ export function setPageDataGetter<T = Record<string, unknown>>(
193
+ getter: (keys?: string[]) => (T & { then?: never }) | null,
194
+ ): Unsubscribe {
195
+ return registerSingleOwnerSlot(
196
+ 'getPageData',
197
+ defaultGetPageData,
198
+ (keys?: string[]): unknown => getter(keys),
199
+ );
200
+ }
@@ -0,0 +1,50 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ import { getAliveMTSState } from './host.js';
6
+ import type { HostGlobalScope } from '../common/host-types.js';
7
+ import { isPlainRecord } from '../common/protocol.js';
8
+ import type { MTSFlushOptions } from '../common/types.js';
9
+
10
+ /**
11
+ * Submit the page root element tree (`__FlushElementTree`); returning does not imply layout or paint completion.
12
+ * Unlike the 2-arg PAPI `__FlushElementTree(target, options)`, `flushElementTree(options)`
13
+ * flushes the page root only and accepts `MTSFlushOptions` as its first argument.
14
+ * Preserve the originating update/reload/GlobalProps options, even for an empty
15
+ * update. First-screen render is submitted by the host when its callback returns.
16
+ * Requires a live MTS host with __FlushElementTree; throws if unavailable, destroyed,
17
+ * or passed options that are not a plain object. There is no completion Promise.
18
+ */
19
+ export function flushElementTree(options?: Readonly<MTSFlushOptions>): void {
20
+ const host = globalThis as unknown as HostGlobalScope;
21
+ getAliveMTSState(host);
22
+ const flush = host.__FlushElementTree;
23
+ if (!flush) {
24
+ throw new Error(
25
+ '[@lynx-js/lynx-runtime/mts] Page flush requires __FlushElementTree(). Ensure flushElementTree() is called on the main thread (MTS).',
26
+ );
27
+ }
28
+ if (options === undefined) {
29
+ // Call 0-arg __FlushElementTree() directly when no options are provided.
30
+ flush();
31
+ return;
32
+ }
33
+ if (!isPlainRecord(options as unknown)) {
34
+ throw new TypeError(
35
+ '[@lynx-js/lynx-runtime/mts] Flush options must be a plain object (flushElementTree(options) flushes the page root and does not take an element target).',
36
+ );
37
+ }
38
+ const rawOptions = options as Readonly<
39
+ MTSFlushOptions & {
40
+ __lynx_timing_flag?: string | undefined;
41
+ }
42
+ >;
43
+ flush(
44
+ undefined,
45
+ rawOptions.timingFlag !== undefined
46
+ && rawOptions.__lynx_timing_flag === undefined
47
+ ? { ...rawOptions, __lynx_timing_flag: rawOptions.timingFlag }
48
+ : rawOptions,
49
+ );
50
+ }