@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.
- package/LICENSE +202 -0
- package/README.md +354 -2
- package/dist/bts/data.d.ts +1 -0
- package/dist/bts/data.js +28 -0
- package/dist/bts/events.d.ts +1 -0
- package/dist/bts/events.js +57 -0
- package/dist/bts/scope.d.ts +1 -0
- package/dist/bts/scope.js +129 -0
- package/dist/bts/services.d.ts +1 -0
- package/dist/bts/services.js +34 -0
- package/dist/bts.d.ts +14 -0
- package/dist/bts.js +30 -0
- package/dist/common/host-types.d.ts +1 -0
- package/dist/common/host-types.js +1 -0
- package/dist/common/messages.d.ts +1 -0
- package/dist/common/messages.js +69 -0
- package/dist/common/performance.d.ts +1 -0
- package/dist/common/performance.js +26 -0
- package/dist/common/protocol.d.ts +20 -0
- package/dist/common/protocol.js +53 -0
- package/dist/common/types.d.ts +203 -0
- package/dist/common/types.js +1 -0
- package/dist/iife/bts.js +1 -0
- package/dist/iife/mts.js +1 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +1 -0
- package/dist/mts/data.d.ts +71 -0
- package/dist/mts/data.js +46 -0
- package/dist/mts/flush.d.ts +11 -0
- package/dist/mts/flush.js +16 -0
- package/dist/mts/host.d.ts +35 -0
- package/dist/mts/host.js +124 -0
- package/dist/mts/services.d.ts +21 -0
- package/dist/mts/services.js +46 -0
- package/dist/mts.d.ts +5 -0
- package/dist/mts.js +4 -0
- package/package.json +57 -3
- package/skills/lynx-runtime/SKILL.md +67 -0
- package/src/bts/data.ts +94 -0
- package/src/bts/events.ts +100 -0
- package/src/bts/scope.ts +279 -0
- package/src/bts/services.ts +88 -0
- package/src/bts.ts +110 -0
- package/src/common/host-types.ts +161 -0
- package/src/common/messages.ts +129 -0
- package/src/common/performance.ts +65 -0
- package/src/common/protocol.ts +98 -0
- package/src/common/types.ts +259 -0
- package/src/index.ts +35 -0
- package/src/mts/data.ts +200 -0
- package/src/mts/flush.ts +50 -0
- package/src/mts/host.ts +297 -0
- package/src/mts/services.ts +102 -0
- package/src/mts.ts +36 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Shared TypeScript types for `@lynx-js/lynx-runtime`.
|
|
3
|
+
*
|
|
4
|
+
* @remarks
|
|
5
|
+
* **Preview (`0.0.x`):** This package is in early preview prior to formal RFC
|
|
6
|
+
* stabilization and does not yet guarantee public API stability across `0.x` releases.
|
|
7
|
+
*
|
|
8
|
+
* Import shared types from `@lynx-js/lynx-runtime`, main-thread runtime functions
|
|
9
|
+
* from `@lynx-js/lynx-runtime/mts`, and background-thread page binding from
|
|
10
|
+
* `@lynx-js/lynx-runtime/bts`. In dual-thread shared modules, guard `/mts` and
|
|
11
|
+
* `/bts` runtime calls behind compile-time thread constants (such as `__LEPUS__`
|
|
12
|
+
* and `__JS__`) so bundler dead-code elimination strips cross-thread imports.
|
|
13
|
+
*
|
|
14
|
+
* @packageDocumentation
|
|
15
|
+
*/
|
|
16
|
+
export type { BTSEventHandler, BTSPageRuntime, BTSReloadOptions, BTSUpdateOptions, CreatedPipelineOptions, CreatePipelineOptions, LynxSystemInfo, MTSFlushContext, MTSFlushOptions, MTSReloadOptions, MTSRenderOptions, MTSUpdateOptions, PipelineOptions, Unsubscribe, } from './common/types.js';
|
package/dist/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export { };
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
import type { MTSFlushContext, MTSReloadOptions, MTSRenderOptions, MTSUpdateOptions, Unsubscribe } from '../common/types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Read a detached copy of the initial page data records and arrays on MTS.
|
|
4
|
+
* Opaque objects remain shared by reference.
|
|
5
|
+
* Updated on first-screen `renderPage` and on `reloadTemplate` updates,
|
|
6
|
+
* and isolated from runtime mutations to `lynx.__initData`.
|
|
7
|
+
* Ensure the MTS runtime is initialized during synchronous bootstrap before the
|
|
8
|
+
* first host input arrives; incremental updates do not change this baseline.
|
|
9
|
+
* Remains readable after destruction.
|
|
10
|
+
*/
|
|
11
|
+
export declare function getInitData<T = Record<string, unknown>>(): T;
|
|
12
|
+
/**
|
|
13
|
+
* Borrow the current host `GlobalProps` without copying (defaults to `{}` when unset).
|
|
14
|
+
* Treat the entire value as read-only, including nested objects; Readonly is shallow
|
|
15
|
+
* and no freeze is applied. If a DSL mutates its own root `GlobalProps` object in place
|
|
16
|
+
* (e.g. `Object.assign`), shallow-copy `{ ...getGlobalProps() }` at startup.
|
|
17
|
+
* During and after destruction, read the captured final properties.
|
|
18
|
+
*/
|
|
19
|
+
export declare function getGlobalProps<T = Record<string, unknown>>(): Readonly<T>;
|
|
20
|
+
/**
|
|
21
|
+
* Subscribe to first-screen render on MTS.
|
|
22
|
+
* Register synchronously before the first host input.
|
|
23
|
+
* Input is read-only and not replayed. The host submits the first screen on return.
|
|
24
|
+
*/
|
|
25
|
+
export declare function onRenderPage<T = Record<string, unknown>>(listener: (data: Readonly<T>, options: Readonly<MTSRenderOptions>) => void): Unsubscribe;
|
|
26
|
+
/**
|
|
27
|
+
* Subscribe to host page data updates and resets on MTS (`!options.reloadTemplate`).
|
|
28
|
+
* `resetPageData` replaces current data rather than merging an incremental update.
|
|
29
|
+
* Preserve these options with the work and pass them to `flushElementTree` when
|
|
30
|
+
* submitting its changes.
|
|
31
|
+
* Register before host input; input is read-only, not replayed, and not automatically merged into DSL state.
|
|
32
|
+
*/
|
|
33
|
+
export declare function onUpdateData<T = Record<string, unknown>>(listener: (data: Readonly<T>, options: Readonly<MTSUpdateOptions>) => void): Unsubscribe;
|
|
34
|
+
/**
|
|
35
|
+
* Subscribe to host template reloads on MTS (`options.reloadTemplate === true`).
|
|
36
|
+
* Runtime refreshes `getInitData()` before invoking reload listeners. Preserve
|
|
37
|
+
* these options with the work and pass them to `flushElementTree` when submitting
|
|
38
|
+
* its changes.
|
|
39
|
+
* Reload does not imply page destruction or cleanup of the previous DSL entry.
|
|
40
|
+
*/
|
|
41
|
+
export declare function onReload<T = Record<string, unknown>>(listener: (data: Readonly<T>, options: Readonly<MTSReloadOptions>) => void): Unsubscribe;
|
|
42
|
+
/**
|
|
43
|
+
* Subscribe to host `GlobalProps` updates on MTS.
|
|
44
|
+
* Treat the delivered object as read-only; mutating it affects shared host state.
|
|
45
|
+
* Notifications are not replayed. Pass options to flushElementTree after applying
|
|
46
|
+
* the update, including updates that leave the element tree unchanged.
|
|
47
|
+
*/
|
|
48
|
+
export declare function onGlobalPropsChanged<T = Record<string, unknown>>(listener: (globalProps: Readonly<T>, options?: Readonly<MTSFlushContext>) => void): Unsubscribe;
|
|
49
|
+
/**
|
|
50
|
+
* Register the synchronous single-owner MTS host `processData` hook.
|
|
51
|
+
* Native consumes its return value immediately; PromiseLike results are rejected.
|
|
52
|
+
* Normalizes Native's absent `TemplateData` (`undefined` / `null`) to `{}` and
|
|
53
|
+
* empty default `processorName` (`""`) to `undefined` across Native and Web.
|
|
54
|
+
* Registering a new processor replaces the previous active processor; unsubscribing
|
|
55
|
+
* the active processor or destroying the page restores the identity processor.
|
|
56
|
+
* Install before the host processes its first input; it cannot retroactively process
|
|
57
|
+
* earlier data. Disposing a replaced registration does not affect the current owner.
|
|
58
|
+
*/
|
|
59
|
+
export declare function setDataProcessor<TInput = Record<string, unknown>, TOutput = Record<string, unknown>>(processor: (data: TInput, processorName?: string) => TOutput & ({
|
|
60
|
+
then?: never;
|
|
61
|
+
} | null | undefined)): Unsubscribe;
|
|
62
|
+
/**
|
|
63
|
+
* Register the synchronous single-owner MTS `getPageData` hook
|
|
64
|
+
* (PromiseLike results are rejected),
|
|
65
|
+
* invoked by Native `GetCurrentData` / `GetPageDataByKey` to query the DSL's current state.
|
|
66
|
+
* Install before host queries. Latest registration wins; disposing the active getter
|
|
67
|
+
* restores null, not the previous getter. Does not create or maintain DSL state.
|
|
68
|
+
*/
|
|
69
|
+
export declare function setPageDataGetter<T = Record<string, unknown>>(getter: (keys?: string[]) => (T & {
|
|
70
|
+
then?: never;
|
|
71
|
+
}) | null): Unsubscribe;
|
package/dist/mts/data.js
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { defaultGetPageData, defaultProcessData, getAliveMTSState, initMTSHostState } from "./host.js";
|
|
2
|
+
import { copyHostData, subscribeListener } from "../common/protocol.js";
|
|
3
|
+
function registerSingleOwnerSlot(slotKey, defaultFn, handler) {
|
|
4
|
+
const host = globalThis;
|
|
5
|
+
const state = getAliveMTSState(host);
|
|
6
|
+
state.slots[slotKey] = handler;
|
|
7
|
+
host[slotKey] = handler;
|
|
8
|
+
return ()=>{
|
|
9
|
+
if (state.slots[slotKey] !== handler) return;
|
|
10
|
+
state.slots[slotKey] = void 0;
|
|
11
|
+
if (host[slotKey] === handler) host[slotKey] = defaultFn;
|
|
12
|
+
};
|
|
13
|
+
}
|
|
14
|
+
function getInitData() {
|
|
15
|
+
const state = initMTSHostState(globalThis);
|
|
16
|
+
return copyHostData(state.initData);
|
|
17
|
+
}
|
|
18
|
+
function getGlobalProps() {
|
|
19
|
+
const host = globalThis;
|
|
20
|
+
const state = initMTSHostState(host);
|
|
21
|
+
if (state.destroyed) return state.globalProps;
|
|
22
|
+
return host.lynx?.__globalProps ?? state.globalProps;
|
|
23
|
+
}
|
|
24
|
+
function onRenderPage(listener) {
|
|
25
|
+
const state = getAliveMTSState(globalThis);
|
|
26
|
+
return subscribeListener(state.renderListeners, listener);
|
|
27
|
+
}
|
|
28
|
+
function onUpdateData(listener) {
|
|
29
|
+
const state = getAliveMTSState(globalThis);
|
|
30
|
+
return subscribeListener(state.updateListeners, listener);
|
|
31
|
+
}
|
|
32
|
+
function onReload(listener) {
|
|
33
|
+
const state = getAliveMTSState(globalThis);
|
|
34
|
+
return subscribeListener(state.reloadListeners, listener);
|
|
35
|
+
}
|
|
36
|
+
function onGlobalPropsChanged(listener) {
|
|
37
|
+
const state = getAliveMTSState(globalThis);
|
|
38
|
+
return subscribeListener(state.globalPropsListeners, listener);
|
|
39
|
+
}
|
|
40
|
+
function setDataProcessor(processor) {
|
|
41
|
+
return registerSingleOwnerSlot('processData', defaultProcessData, (data, processorName)=>processor(data ?? {}, '' === processorName ? void 0 : processorName));
|
|
42
|
+
}
|
|
43
|
+
function setPageDataGetter(getter) {
|
|
44
|
+
return registerSingleOwnerSlot('getPageData', defaultGetPageData, (keys)=>getter(keys));
|
|
45
|
+
}
|
|
46
|
+
export { getGlobalProps, getInitData, onGlobalPropsChanged, onReload, onRenderPage, onUpdateData, setDataProcessor, setPageDataGetter };
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { MTSFlushOptions } from '../common/types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Submit the page root element tree (`__FlushElementTree`); returning does not imply layout or paint completion.
|
|
4
|
+
* Unlike the 2-arg PAPI `__FlushElementTree(target, options)`, `flushElementTree(options)`
|
|
5
|
+
* flushes the page root only and accepts `MTSFlushOptions` as its first argument.
|
|
6
|
+
* Preserve the originating update/reload/GlobalProps options, even for an empty
|
|
7
|
+
* update. First-screen render is submitted by the host when its callback returns.
|
|
8
|
+
* Requires a live MTS host with __FlushElementTree; throws if unavailable, destroyed,
|
|
9
|
+
* or passed options that are not a plain object. There is no completion Promise.
|
|
10
|
+
*/
|
|
11
|
+
export declare function flushElementTree(options?: Readonly<MTSFlushOptions>): void;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { getAliveMTSState } from "./host.js";
|
|
2
|
+
import { isPlainRecord } from "../common/protocol.js";
|
|
3
|
+
function flushElementTree(options) {
|
|
4
|
+
const host = globalThis;
|
|
5
|
+
getAliveMTSState(host);
|
|
6
|
+
const flush = host.__FlushElementTree;
|
|
7
|
+
if (!flush) throw new Error('[@lynx-js/lynx-runtime/mts] Page flush requires __FlushElementTree(). Ensure flushElementTree() is called on the main thread (MTS).');
|
|
8
|
+
if (void 0 === options) return void flush();
|
|
9
|
+
if (!isPlainRecord(options)) throw new TypeError('[@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).');
|
|
10
|
+
const rawOptions = options;
|
|
11
|
+
flush(void 0, void 0 !== rawOptions.timingFlag && void 0 === rawOptions.__lynx_timing_flag ? {
|
|
12
|
+
...rawOptions,
|
|
13
|
+
__lynx_timing_flag: rawOptions.timingFlag
|
|
14
|
+
} : rawOptions);
|
|
15
|
+
}
|
|
16
|
+
export { flushElementTree };
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { Unsubscribe } from '../common/types.js';
|
|
2
|
+
/**
|
|
3
|
+
* True once the MTS host destruction signal (`lynx.getNative()` `__DestroyLifetime`)
|
|
4
|
+
* is observed, before DSL teardown callbacks run.
|
|
5
|
+
*
|
|
6
|
+
* @remarks
|
|
7
|
+
* Observing MTS destruction requires `lynx.getNative()` (**Lynx SDK 3.4+** on Native
|
|
8
|
+
* and Web). On older hosts without `lynx.getNative()` (**Lynx SDK 2.14–3.3** or
|
|
9
|
+
* earlier `web-core`), `isDestroyed()` remains `false`; a `false` return value means
|
|
10
|
+
* destruction has not been observed rather than guaranteeing host liveness.
|
|
11
|
+
*
|
|
12
|
+
* @since Lynx 3.4 (always `false` when host lacks `lynx.getNative()`)
|
|
13
|
+
*/
|
|
14
|
+
export declare function isDestroyed(): boolean;
|
|
15
|
+
/**
|
|
16
|
+
* Subscribe to MTS page destruction (`__DestroyLifetime` on `lynx.getNative()`).
|
|
17
|
+
*
|
|
18
|
+
* @remarks
|
|
19
|
+
* Host destruction notifications on MTS require `lynx.getNative()` (**Lynx SDK 3.4+**
|
|
20
|
+
* on Native and Web). On **Lynx SDK 2.14–3.3** or earlier `web-core` without
|
|
21
|
+
* `lynx.getNative()`, calling `onDestroy` safely degrades to a no-op and returns an
|
|
22
|
+
* idempotent `Unsubscribe` function without throwing, because the single-page context
|
|
23
|
+
* is torn down as a whole without an MTS destroy event.
|
|
24
|
+
*
|
|
25
|
+
* Note: `ReloadTemplate` / `ReloadFromJS` (`globalThis.removeComponents` + `onReload`)
|
|
26
|
+
* reuses the same MTS context and does **not** dispatch `__DestroyLifetime`.
|
|
27
|
+
* Runtime objects recreated across reloads or entry re-evaluations must invoke
|
|
28
|
+
* the returned `Unsubscribe` disposer when retiring so listeners do not accumulate
|
|
29
|
+
* until page teardown.
|
|
30
|
+
*
|
|
31
|
+
* @param listener - Callback invoked synchronously when MTS destruction begins.
|
|
32
|
+
* @returns An idempotent disposer that unsubscribes `listener` (no-op when the host does not emit MTS destroy notifications).
|
|
33
|
+
* @since Lynx 3.4 (safe no-op when host lacks `lynx.getNative()`)
|
|
34
|
+
*/
|
|
35
|
+
export declare function onDestroy(listener: () => void): Unsubscribe;
|
package/dist/mts/host.js
ADDED
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
import { clearMultiplexed } from "../common/messages.js";
|
|
2
|
+
import { NATIVE_EVENT_DESTROY_LIFETIME, NATIVE_EVENT_RENDER_PAGE, NATIVE_EVENT_UPDATE_GLOBAL_PROPS, NATIVE_EVENT_UPDATE_PAGE, copyHostData, dispatchListeners, invokeAll, subscribeListener } from "../common/protocol.js";
|
|
3
|
+
const mtsStateMap = new WeakMap();
|
|
4
|
+
const defaultProcessData = (data)=>data;
|
|
5
|
+
const defaultGetPageData = ()=>null;
|
|
6
|
+
const noop = ()=>{};
|
|
7
|
+
function isMTSHostDestroyed(host) {
|
|
8
|
+
return mtsStateMap.get(host.lynx ?? host)?.destroyed === true;
|
|
9
|
+
}
|
|
10
|
+
function initMTSHostState(host) {
|
|
11
|
+
const key = host.lynx ?? host;
|
|
12
|
+
const existing = mtsStateMap.get(key);
|
|
13
|
+
if (existing) return existing;
|
|
14
|
+
const nativeProxy = host.lynx?.getNative?.();
|
|
15
|
+
const state = {
|
|
16
|
+
destroyed: false,
|
|
17
|
+
hasDestroyProxy: void 0 !== nativeProxy,
|
|
18
|
+
destroyListeners: new Map(),
|
|
19
|
+
globalProps: {},
|
|
20
|
+
initData: {},
|
|
21
|
+
renderListeners: new Map(),
|
|
22
|
+
updateListeners: new Map(),
|
|
23
|
+
reloadListeners: new Map(),
|
|
24
|
+
globalPropsListeners: new Map(),
|
|
25
|
+
slots: {}
|
|
26
|
+
};
|
|
27
|
+
mtsStateMap.set(key, state);
|
|
28
|
+
const onRenderInput = (data, options)=>{
|
|
29
|
+
if (state.destroyed) return;
|
|
30
|
+
const normalizedData = data ?? {};
|
|
31
|
+
state.initData = copyHostData(normalizedData);
|
|
32
|
+
const normalizedOptions = options ?? {};
|
|
33
|
+
dispatchListeners(state.renderListeners, (listener)=>{
|
|
34
|
+
listener(normalizedData, normalizedOptions);
|
|
35
|
+
});
|
|
36
|
+
};
|
|
37
|
+
const onUpdateInput = (data, options)=>{
|
|
38
|
+
if (state.destroyed) return;
|
|
39
|
+
const normalizedData = data ?? {};
|
|
40
|
+
const normalizedOptions = options ?? {};
|
|
41
|
+
if (normalizedOptions.reloadTemplate) {
|
|
42
|
+
state.initData = copyHostData(normalizedData);
|
|
43
|
+
dispatchListeners(state.reloadListeners, (listener)=>{
|
|
44
|
+
listener(normalizedData, normalizedOptions);
|
|
45
|
+
});
|
|
46
|
+
} else dispatchListeners(state.updateListeners, (listener)=>{
|
|
47
|
+
listener(normalizedData, normalizedOptions);
|
|
48
|
+
});
|
|
49
|
+
};
|
|
50
|
+
const onGlobalPropsInput = (data, options)=>{
|
|
51
|
+
if (state.destroyed) return;
|
|
52
|
+
const normalizedData = data ?? {};
|
|
53
|
+
dispatchListeners(state.globalPropsListeners, (listener)=>{
|
|
54
|
+
listener(normalizedData, options);
|
|
55
|
+
});
|
|
56
|
+
};
|
|
57
|
+
host.renderPage = onRenderInput;
|
|
58
|
+
host.updatePage = onUpdateInput;
|
|
59
|
+
host.updateGlobalProps = onGlobalPropsInput;
|
|
60
|
+
host.processData ??= defaultProcessData;
|
|
61
|
+
host.removeComponents ??= noop;
|
|
62
|
+
host.getPageData ??= defaultGetPageData;
|
|
63
|
+
if (host.lynx?.SystemInfo && !host.SystemInfo) host.SystemInfo = host.lynx.SystemInfo;
|
|
64
|
+
const engine = host.lynx?.getEngine?.();
|
|
65
|
+
if (engine) {
|
|
66
|
+
engine.addEventListener(NATIVE_EVENT_RENDER_PAGE, (event)=>{
|
|
67
|
+
const [data, options] = event.data;
|
|
68
|
+
onRenderInput(data, options);
|
|
69
|
+
});
|
|
70
|
+
engine.addEventListener(NATIVE_EVENT_UPDATE_PAGE, (event)=>{
|
|
71
|
+
const [data, options] = event.data;
|
|
72
|
+
onUpdateInput(data, options);
|
|
73
|
+
});
|
|
74
|
+
engine.addEventListener(NATIVE_EVENT_UPDATE_GLOBAL_PROPS, (event)=>{
|
|
75
|
+
const [data, options] = event.data;
|
|
76
|
+
onGlobalPropsInput(data, options);
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
if (nativeProxy) {
|
|
80
|
+
const onNativeDestroy = ()=>{
|
|
81
|
+
if (state.destroyed) return;
|
|
82
|
+
state.globalProps = host.lynx?.__globalProps ?? state.globalProps;
|
|
83
|
+
state.destroyed = true;
|
|
84
|
+
try {
|
|
85
|
+
if (state.messages) {
|
|
86
|
+
clearMultiplexed(state.messages);
|
|
87
|
+
state.messages = void 0;
|
|
88
|
+
}
|
|
89
|
+
invokeAll([
|
|
90
|
+
...state.destroyListeners
|
|
91
|
+
].map(([listener, reg])=>()=>{
|
|
92
|
+
if (state.destroyListeners.get(listener) === reg) listener();
|
|
93
|
+
}));
|
|
94
|
+
} finally{
|
|
95
|
+
state.renderListeners.clear();
|
|
96
|
+
state.updateListeners.clear();
|
|
97
|
+
state.reloadListeners.clear();
|
|
98
|
+
state.globalPropsListeners.clear();
|
|
99
|
+
state.destroyListeners.clear();
|
|
100
|
+
if (state.slots.processData && host.processData === state.slots.processData) host.processData = defaultProcessData;
|
|
101
|
+
state.slots.processData = void 0;
|
|
102
|
+
if (state.slots.getPageData && host.getPageData === state.slots.getPageData) host.getPageData = defaultGetPageData;
|
|
103
|
+
state.slots.getPageData = void 0;
|
|
104
|
+
nativeProxy.removeEventListener(NATIVE_EVENT_DESTROY_LIFETIME, onNativeDestroy);
|
|
105
|
+
}
|
|
106
|
+
};
|
|
107
|
+
nativeProxy.addEventListener(NATIVE_EVENT_DESTROY_LIFETIME, onNativeDestroy);
|
|
108
|
+
}
|
|
109
|
+
return state;
|
|
110
|
+
}
|
|
111
|
+
function getAliveMTSState(host) {
|
|
112
|
+
const state = initMTSHostState(host);
|
|
113
|
+
if (state.destroyed) throw new Error('[@lynx-js/lynx-runtime/mts] Cannot register or activate a capability on a destroying or destroyed host. Check isDestroyed() before registering in async callbacks.');
|
|
114
|
+
return state;
|
|
115
|
+
}
|
|
116
|
+
function isDestroyed() {
|
|
117
|
+
return isMTSHostDestroyed(globalThis);
|
|
118
|
+
}
|
|
119
|
+
function onDestroy(listener) {
|
|
120
|
+
const state = getAliveMTSState(globalThis);
|
|
121
|
+
if (!state.hasDestroyProxy) return noop;
|
|
122
|
+
return subscribeListener(state.destroyListeners, listener);
|
|
123
|
+
}
|
|
124
|
+
export { defaultGetPageData, defaultProcessData, getAliveMTSState, initMTSHostState, isDestroyed, isMTSHostDestroyed, onDestroy };
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
import type { CreatePipelineOptions, CreatedPipelineOptions, LynxSystemInfo, PipelineOptions, Unsubscribe } from '../common/types.js';
|
|
2
|
+
/** Read live host environment information without initializing MTS input bindings. */
|
|
3
|
+
export declare function getSystemInfo(): Readonly<LynxSystemInfo>;
|
|
4
|
+
/** Create a host performance pipeline without imposing DSL timing stages. */
|
|
5
|
+
export declare function createPipeline(options?: CreatePipelineOptions): CreatedPipelineOptions | undefined;
|
|
6
|
+
/** Mark a host timing key; the DSL decides whether a key needs timestamps. */
|
|
7
|
+
export declare function markTiming(pipeline: string | PipelineOptions | undefined, timingKey: string): void;
|
|
8
|
+
/**
|
|
9
|
+
* Send a named message to this page's BTS without a completion receipt.
|
|
10
|
+
* Requires a live MTS host and peer proxy. Install the receiver first: there is
|
|
11
|
+
* no startup queue, retry, RPC, or cross-type ordering guarantee. Awaiting this
|
|
12
|
+
* void return does not wait for the peer. T does not validate the payload at runtime.
|
|
13
|
+
*/
|
|
14
|
+
export declare function sendMessage<T = undefined>(type: string, ...args: undefined extends T ? [data?: T] : [data: T]): void;
|
|
15
|
+
/**
|
|
16
|
+
* Subscribe to named messages from this page's BTS, preserving the raw payload.
|
|
17
|
+
* Requires a live host and peer proxy; missed messages are not replayed. Identical
|
|
18
|
+
* callbacks for a type share a registration. Dispose when the owning entry retires;
|
|
19
|
+
* observed page destruction also removes listeners. T is not runtime validation.
|
|
20
|
+
*/
|
|
21
|
+
export declare function onMessage<T = unknown>(type: string, listener: (this: void, data: T) => void): Unsubscribe;
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { getAliveMTSState, isMTSHostDestroyed } from "./host.js";
|
|
2
|
+
import { subscribeMessage } from "../common/messages.js";
|
|
3
|
+
import { createHostPipeline, markHostTiming } from "../common/performance.js";
|
|
4
|
+
function resolveSystemInfo(host) {
|
|
5
|
+
return host.lynx?.SystemInfo ?? host.SystemInfo ?? {};
|
|
6
|
+
}
|
|
7
|
+
function getJSContext(host, state) {
|
|
8
|
+
let proxy = state.jsContext;
|
|
9
|
+
if (!proxy) {
|
|
10
|
+
proxy = host.lynx?.getJSContext?.();
|
|
11
|
+
if (!proxy) throw new Error('[@lynx-js/lynx-runtime/mts] Message communication requires lynx.getJSContext(). Ensure the MTS host context is initialized before calling sendMessage() or onMessage().');
|
|
12
|
+
state.jsContext = proxy;
|
|
13
|
+
}
|
|
14
|
+
return proxy;
|
|
15
|
+
}
|
|
16
|
+
function getSystemInfo() {
|
|
17
|
+
const host = globalThis;
|
|
18
|
+
if (!isMTSHostDestroyed(host) && host.lynx?.SystemInfo && !host.SystemInfo) host.SystemInfo = host.lynx.SystemInfo;
|
|
19
|
+
return resolveSystemInfo(host);
|
|
20
|
+
}
|
|
21
|
+
function createPipeline(options) {
|
|
22
|
+
const host = globalThis;
|
|
23
|
+
if (isMTSHostDestroyed(host)) return;
|
|
24
|
+
return createHostPipeline(host.lynx?.performance, options, 'mts');
|
|
25
|
+
}
|
|
26
|
+
function markTiming(pipeline, timingKey) {
|
|
27
|
+
const host = globalThis;
|
|
28
|
+
if (isMTSHostDestroyed(host)) return;
|
|
29
|
+
markHostTiming(host.lynx?.performance, pipeline, timingKey);
|
|
30
|
+
}
|
|
31
|
+
function sendMessage(type, data) {
|
|
32
|
+
const host = globalThis;
|
|
33
|
+
const state = getAliveMTSState(host);
|
|
34
|
+
getJSContext(host, state).dispatchEvent({
|
|
35
|
+
type,
|
|
36
|
+
data
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
function onMessage(type, listener) {
|
|
40
|
+
const host = globalThis;
|
|
41
|
+
const state = getAliveMTSState(host);
|
|
42
|
+
const proxy = getJSContext(host, state);
|
|
43
|
+
state.messages ??= new Map();
|
|
44
|
+
return subscribeMessage(state.messages, proxy, type, listener);
|
|
45
|
+
}
|
|
46
|
+
export { createPipeline, getSystemInfo, markTiming, onMessage, sendMessage };
|
package/dist/mts.d.ts
ADDED
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
export type { CreatedPipelineOptions, CreatePipelineOptions, LynxSystemInfo, MTSFlushContext, MTSFlushOptions, MTSReloadOptions, MTSRenderOptions, MTSUpdateOptions, PipelineOptions, Unsubscribe, } from './common/types.js';
|
|
2
|
+
export { getGlobalProps, getInitData, onGlobalPropsChanged, onReload, onRenderPage, onUpdateData, setDataProcessor, setPageDataGetter, } from './mts/data.js';
|
|
3
|
+
export { flushElementTree } from './mts/flush.js';
|
|
4
|
+
export { isDestroyed, onDestroy } from './mts/host.js';
|
|
5
|
+
export { createPipeline, getSystemInfo, markTiming, onMessage, sendMessage, } from './mts/services.js';
|
package/dist/mts.js
ADDED
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { getGlobalProps, getInitData, onGlobalPropsChanged, onReload, onRenderPage, onUpdateData, setDataProcessor, setPageDataGetter } from "./mts/data.js";
|
|
2
|
+
export { flushElementTree } from "./mts/flush.js";
|
|
3
|
+
export { isDestroyed, onDestroy } from "./mts/host.js";
|
|
4
|
+
export { createPipeline, getSystemInfo, markTiming, onMessage, sendMessage } from "./mts/services.js";
|
package/package.json
CHANGED
|
@@ -1,6 +1,60 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lynx-js/lynx-runtime",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "0.0.1",
|
|
4
|
+
"description": "DSL-neutral Lynx host runtime primitives for main thread (MTS) and background thread (BTS) (Preview).",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"lynx",
|
|
7
|
+
"runtime",
|
|
8
|
+
"mts",
|
|
9
|
+
"bts"
|
|
10
|
+
],
|
|
11
|
+
"repository": {
|
|
12
|
+
"type": "git",
|
|
13
|
+
"url": "git+https://github.com/lynx-family/lynx-stack.git",
|
|
14
|
+
"directory": "packages/lynx/lynx-runtime"
|
|
15
|
+
},
|
|
16
|
+
"license": "Apache-2.0",
|
|
17
|
+
"sideEffects": false,
|
|
18
|
+
"type": "module",
|
|
19
|
+
"exports": {
|
|
20
|
+
".": {
|
|
21
|
+
"types": "./dist/index.d.ts",
|
|
22
|
+
"default": "./dist/index.js"
|
|
23
|
+
},
|
|
24
|
+
"./mts": {
|
|
25
|
+
"types": "./dist/mts.d.ts",
|
|
26
|
+
"default": "./dist/mts.js"
|
|
27
|
+
},
|
|
28
|
+
"./bts": {
|
|
29
|
+
"types": "./dist/bts.d.ts",
|
|
30
|
+
"default": "./dist/bts.js"
|
|
31
|
+
},
|
|
32
|
+
"./iife/mts": "./dist/iife/mts.js",
|
|
33
|
+
"./iife/bts": "./dist/iife/bts.js",
|
|
34
|
+
"./skill": "./skills/lynx-runtime/SKILL.md",
|
|
35
|
+
"./package.json": "./package.json"
|
|
36
|
+
},
|
|
37
|
+
"main": "./dist/index.js",
|
|
38
|
+
"module": "./dist/index.js",
|
|
39
|
+
"types": "./dist/index.d.ts",
|
|
40
|
+
"files": [
|
|
41
|
+
"README.md",
|
|
42
|
+
"dist",
|
|
43
|
+
"skills",
|
|
44
|
+
"src"
|
|
45
|
+
],
|
|
46
|
+
"devDependencies": {
|
|
47
|
+
"@rslib/core": "1.0.7",
|
|
48
|
+
"rsbuild-plugin-publint": "1.0.0",
|
|
49
|
+
"typescript": "6.0.3"
|
|
50
|
+
},
|
|
51
|
+
"engines": {
|
|
52
|
+
"node": "^20 || ^22 || ^24"
|
|
53
|
+
},
|
|
54
|
+
"scripts": {
|
|
55
|
+
"build": "rslib",
|
|
56
|
+
"dev": "rslib --watch",
|
|
57
|
+
"test": "vitest run",
|
|
58
|
+
"test:type": "tsc --noEmit -p tsconfig.test.json"
|
|
59
|
+
}
|
|
6
60
|
}
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lynx-runtime
|
|
3
|
+
description: Use @lynx-js/lynx-runtime in bundled Lynx projects (ESM /mts & /bts) and build-free .lynxml documents (inline ES2017 IIFE /iife/mts & /iife/bts), including inlining IIFE scripts and testing in node:vm.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Using `@lynx-js/lynx-runtime`
|
|
7
|
+
|
|
8
|
+
Use this skill when authoring Lynx pages, DSL adapters, or build-free `.lynxml` documents with `@lynx-js/lynx-runtime`.
|
|
9
|
+
|
|
10
|
+
> **Source of truth (`0.0.x`)**: Read the installed package's `dist/*.d.ts` for exact API signatures and contracts, and `README.md` for host SDK compatibility boundaries.
|
|
11
|
+
|
|
12
|
+
## 1. Choose an Entrypoint
|
|
13
|
+
|
|
14
|
+
| Project type | Entrypoint | How to load |
|
|
15
|
+
| ----------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
|
|
16
|
+
| Bundled Rspeedy / ESM project | `@lynx-js/lynx-runtime/mts`, `@lynx-js/lynx-runtime/bts`, types from `@lynx-js/lynx-runtime` | Standard `import` (`sideEffects: false`) |
|
|
17
|
+
| Build-free `.lynxml` document | `@lynx-js/lynx-runtime/iife/mts`, `@lynx-js/lynx-runtime/iife/bts` | Inline verbatim from `dist/iife/{mts,bts}.js`; exposes script-scoped `var LynxRuntime` |
|
|
18
|
+
|
|
19
|
+
For `.lynxml`, always inline the prebuilt ES2017 IIFE instead of loading via blocking `lynx.fetchBundle(...).wait(...)` (which blocks the OS UI thread on cache misses under `ALL_ON_UI` / `PART_ON_LAYOUT`).
|
|
20
|
+
|
|
21
|
+
## 2. Quick Start for Build-Free `.lynxml`
|
|
22
|
+
|
|
23
|
+
Read the exact contents of `node_modules/@lynx-js/lynx-runtime/dist/iife/mts.js` and `dist/iife/bts.js` (never retype or hand-edit the minified line) and inline them at the top of `<script thread="main">` and `<script thread="background">`—after any `"use strict";` directive prologue and before any executable code. Wrap each inlined line with `BEGIN`/`END` version comments so future upgrades are easy to spot and replace:
|
|
24
|
+
|
|
25
|
+
```xml
|
|
26
|
+
<!doctype lynx>
|
|
27
|
+
<lynx engine-version="4.2">
|
|
28
|
+
<script thread="main">
|
|
29
|
+
// BEGIN @lynx-js/lynx-runtime iife/mts (<version>)
|
|
30
|
+
/* verbatim contents of @lynx-js/lynx-runtime/iife/mts */
|
|
31
|
+
// END @lynx-js/lynx-runtime iife/mts
|
|
32
|
+
const mts = LynxRuntime;
|
|
33
|
+
function mountPage(data) { /* create elements */ }
|
|
34
|
+
function onPageUpdate(data, options) { /* update elements */ mts.flushElementTree(options); }
|
|
35
|
+
mts.onRenderPage(mountPage);
|
|
36
|
+
mts.onUpdateData(onPageUpdate);
|
|
37
|
+
</script>
|
|
38
|
+
<script thread="background">
|
|
39
|
+
// BEGIN @lynx-js/lynx-runtime iife/bts (<version>)
|
|
40
|
+
/* verbatim contents of @lynx-js/lynx-runtime/iife/bts */
|
|
41
|
+
// END @lynx-js/lynx-runtime iife/bts
|
|
42
|
+
const bts = LynxRuntime.bindPage();
|
|
43
|
+
bts.onMessage('ready', (payload) => { /* handle MTS message */ });
|
|
44
|
+
bts.onDestroy(() => { /* release timers / listeners */ });
|
|
45
|
+
</script>
|
|
46
|
+
</lynx>
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## 3. Essential Usage Rules
|
|
50
|
+
|
|
51
|
+
1. **Avoid reserved top-level `var`/`function` names in classic `<script thread="main">`**: Lazy MTS activation overwrites `globalThis.renderPage`, `updatePage`, and `updateGlobalProps`, and claims `processData`, `getPageData`, and `removeComponents` (installing defaults when missing, or replacing them via `setDataProcessor` / `setPageDataGetter`). Top-level `function` or `var` declarations with those names share `globalThis` (for example, once Runtime is activated by an earlier call, `renderPage` resolves to Runtime's dispatcher and `mts.onRenderPage(renderPage)` recurses). Name page callbacks distinctly (e.g. `mountPage`, `onPageUpdate`).
|
|
52
|
+
2. **Keep Runtime as the sole host bridge**: Use `@lynx-js/lynx-runtime` consistently for lifecycle, messaging, `GlobalProps`, global events, and flushing rather than mixing raw `lynx.getEngine()`, `lynx.getJSContext()`, `lynx.getCoreContext()`, `GlobalEventEmitter`, or `__FlushElementTree()` calls on the same page.
|
|
53
|
+
3. **Read `onMessage` payloads directly**: `onMessage(type, (data) => ...)` delivers the message `data` directly (not wrapped in `{ type, data }`).
|
|
54
|
+
4. **Use `isDestroyed()` in async callbacks, not inside `onDestroy`**: When `onDestroy` callbacks run, `isDestroyed()` is already `true`—run cleanup unconditionally inside `onDestroy`, and guard async callbacks (timers, network, JSB) with `if (isDestroyed()) return;` before calling Runtime APIs.
|
|
55
|
+
5. **Check host SDK boundaries for MTS `onDestroy` and BTS `onUpdateData`**: Before relying on MTS teardown hooks or direct BTS `onUpdateData()` delivery on older hosts, verify your target SDK / bundle DSL against `README.md`.
|
|
56
|
+
|
|
57
|
+
## 4. Unit Testing `.lynxml` in `node:vm`
|
|
58
|
+
|
|
59
|
+
When executing `.lynxml` scripts in `node:vm` against the inlined IIFE scripts:
|
|
60
|
+
|
|
61
|
+
- **MTS mock**:
|
|
62
|
+
- Provide `lynx.getNative()` (for `__DestroyLifetime`) alongside `lynx.getEngine()` and `lynx.getJSContext()`.
|
|
63
|
+
- Dispatch engine inputs as `{ data: [payload, options] }`. Construct `options` **inside the VM realm** (for example, `vm.runInContext('({ data: [{}, { timingFlag: "t" }] })', ctx)`) so cross-realm `Object.prototype` checks in `flushElementTree(options)` pass.
|
|
64
|
+
- **BTS mock**:
|
|
65
|
+
- Provide `lynx.getApp()` returning an app object with `callDestroyLifetimeFun()`, plus `removeEventListener` on `getCoreContext()` and `removeListener` on `getJSModule()`.
|
|
66
|
+
- Trigger teardown by dispatching `'__DestroyLifetime'` on the `lynx.getNative()` proxy (MTS) and calling `app.callDestroyLifetimeFun()` (BTS).
|
|
67
|
+
- `onMessage` and `onGlobalEvent` return an `Unsubscribe` disposer, and their host-invoked listener wrappers return `undefined` (ignoring async listener Promises), so flush microtasks/turns (`await new Promise(r => setImmediate(r))`) when asserting async handler completion.
|
package/src/bts/data.ts
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
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 { subscribeBTSSlot } from './scope.js';
|
|
6
|
+
import type { BTSPageScope } from './scope.js';
|
|
7
|
+
import type {
|
|
8
|
+
BTSReloadOptions,
|
|
9
|
+
BTSUpdateOptions,
|
|
10
|
+
Unsubscribe,
|
|
11
|
+
} from '../common/types.js';
|
|
12
|
+
|
|
13
|
+
/** @internal */
|
|
14
|
+
export function scopeOnGlobalPropsChanged<T = Record<string, unknown>>(
|
|
15
|
+
scope: BTSPageScope,
|
|
16
|
+
listener: (globalProps: Readonly<T>) => void,
|
|
17
|
+
): Unsubscribe {
|
|
18
|
+
return subscribeBTSSlot<[Record<string, unknown> | undefined]>(
|
|
19
|
+
scope,
|
|
20
|
+
'updateGlobalProps',
|
|
21
|
+
() => {
|
|
22
|
+
listener(scope.globalProps as Readonly<T>);
|
|
23
|
+
},
|
|
24
|
+
listener,
|
|
25
|
+
);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** @internal */
|
|
29
|
+
export function scopeOnUpdateData<T = Record<string, unknown>>(
|
|
30
|
+
scope: BTSPageScope,
|
|
31
|
+
listener: (data: Readonly<T>, options: Readonly<BTSUpdateOptions>) => void,
|
|
32
|
+
): Unsubscribe {
|
|
33
|
+
return subscribeBTSSlot<
|
|
34
|
+
[
|
|
35
|
+
Record<string, unknown> | undefined,
|
|
36
|
+
| { type?: number | undefined; processorName?: string | undefined }
|
|
37
|
+
| undefined,
|
|
38
|
+
]
|
|
39
|
+
>(
|
|
40
|
+
scope,
|
|
41
|
+
'updateCardData',
|
|
42
|
+
(data, rawOptions) => {
|
|
43
|
+
listener((data ?? {}) as Readonly<T>, {
|
|
44
|
+
resetPageData: rawOptions?.type === 1,
|
|
45
|
+
processorName: rawOptions?.processorName === ''
|
|
46
|
+
? undefined
|
|
47
|
+
: rawOptions?.processorName,
|
|
48
|
+
});
|
|
49
|
+
},
|
|
50
|
+
listener,
|
|
51
|
+
);
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** @internal */
|
|
55
|
+
export function scopeOnReload<T = Record<string, unknown>>(
|
|
56
|
+
scope: BTSPageScope,
|
|
57
|
+
listener: (data: Readonly<T>, options: Readonly<BTSReloadOptions>) => void,
|
|
58
|
+
): Unsubscribe {
|
|
59
|
+
return subscribeBTSSlot<
|
|
60
|
+
[Record<string, unknown> | undefined, BTSReloadOptions | undefined]
|
|
61
|
+
>(
|
|
62
|
+
scope,
|
|
63
|
+
'onAppReload',
|
|
64
|
+
(data, options) => {
|
|
65
|
+
listener(
|
|
66
|
+
(data ?? {}) as Readonly<T>,
|
|
67
|
+
options
|
|
68
|
+
? {
|
|
69
|
+
...options,
|
|
70
|
+
processorName: options.processorName === ''
|
|
71
|
+
? undefined
|
|
72
|
+
: options.processorName,
|
|
73
|
+
}
|
|
74
|
+
: {},
|
|
75
|
+
);
|
|
76
|
+
},
|
|
77
|
+
listener,
|
|
78
|
+
);
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** @internal */
|
|
82
|
+
export function scopeOnConfigChanged<T = Record<string, unknown>>(
|
|
83
|
+
scope: BTSPageScope,
|
|
84
|
+
listener: (config: Readonly<T>) => void,
|
|
85
|
+
): Unsubscribe {
|
|
86
|
+
return subscribeBTSSlot<[Record<string, unknown> | undefined]>(
|
|
87
|
+
scope,
|
|
88
|
+
'processCardConfig',
|
|
89
|
+
(config) => {
|
|
90
|
+
listener((config ?? {}) as Readonly<T>);
|
|
91
|
+
},
|
|
92
|
+
listener,
|
|
93
|
+
);
|
|
94
|
+
}
|