@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,161 @@
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 type {
6
+ BTSReloadOptions,
7
+ LynxSystemInfo,
8
+ MTSFlushContext,
9
+ MTSFlushOptions,
10
+ MTSReloadOptions,
11
+ MTSRenderOptions,
12
+ PipelineOptions,
13
+ } from './types.js';
14
+
15
+ /**
16
+ * Minimal structural interfaces for Lynx host globals so `@lynx-js/lynx-runtime`
17
+ * does not rely on ambient TypeScript global declarations (`declare global`).
18
+ * @internal
19
+ */
20
+ export interface HostMessageEvent<T = unknown> {
21
+ type: string;
22
+ data: T;
23
+ origin?: string | undefined;
24
+ target?: string | undefined;
25
+ }
26
+
27
+ /**
28
+ * @internal
29
+ */
30
+ export interface HostContextProxy {
31
+ dispatchEvent(event: { type: string; data: unknown }): void;
32
+ addEventListener<T = unknown>(
33
+ type: string,
34
+ listener: (event: HostMessageEvent<T>) => void,
35
+ ): void;
36
+ removeEventListener<T = unknown>(
37
+ type: string,
38
+ listener: (event: HostMessageEvent<T>) => void,
39
+ ): void;
40
+ }
41
+
42
+ /**
43
+ * @internal
44
+ */
45
+ export interface HostGlobalEventEmitter {
46
+ addListener(
47
+ eventName: string,
48
+ listener: (...args: unknown[]) => void,
49
+ context?: unknown,
50
+ ): void;
51
+ removeListener(
52
+ eventName: string,
53
+ listener: (...args: unknown[]) => void,
54
+ ): void;
55
+ }
56
+
57
+ /**
58
+ * @internal
59
+ */
60
+ export interface HostBTSApp {
61
+ publishEvent?:
62
+ | ((handlerName: string, data: unknown, ...hostArgs: unknown[]) => unknown)
63
+ | undefined;
64
+ publicComponentEvent?:
65
+ | ((
66
+ componentId: string,
67
+ handlerName: string,
68
+ data: unknown,
69
+ ...hostArgs: unknown[]
70
+ ) => unknown)
71
+ | undefined;
72
+ nativeAppId?: string | undefined;
73
+ _params?: {
74
+ initData?: Record<string, unknown> | undefined;
75
+ updateData?: Record<string, unknown> | undefined;
76
+ cardType?: string | undefined;
77
+ appGUID?: string | undefined;
78
+ srcName?: string | undefined;
79
+ } | undefined;
80
+ lynx?: HostLynxObject | undefined;
81
+ GlobalEventEmitter?: HostGlobalEventEmitter | null | undefined;
82
+ getJSModule?: ((moduleName: string) => unknown) | undefined;
83
+ updateCardData?:
84
+ | ((
85
+ data: Record<string, unknown>,
86
+ options?: {
87
+ type?: number | undefined;
88
+ processorName?: string | undefined;
89
+ },
90
+ ) => void)
91
+ | undefined;
92
+ updateGlobalProps?: ((newData: Record<string, unknown>) => void) | undefined;
93
+ onAppReload?:
94
+ | ((data: Record<string, unknown>, options?: BTSReloadOptions) => void)
95
+ | undefined;
96
+ processCardConfig?: ((config: Record<string, unknown>) => void) | undefined;
97
+ onAppEnterForeground?: (() => void) | undefined;
98
+ onAppEnterBackground?: (() => void) | undefined;
99
+ callDestroyLifetimeFun?: (() => void) | undefined;
100
+ }
101
+
102
+ /**
103
+ * @internal
104
+ */
105
+ export interface HostPerformanceObject {
106
+ _generatePipelineOptions?:
107
+ | (() => PipelineOptions | null | undefined)
108
+ | undefined;
109
+ _onPipelineStart?:
110
+ | ((pipelineID: string, options?: string | PipelineOptions) => void)
111
+ | undefined;
112
+ _bindPipelineIDWithTimingFlag?:
113
+ | ((pipelineID: string, timingFlag: string) => void)
114
+ | undefined;
115
+ _bindPipelineIdWithTimingFlag?:
116
+ | ((pipelineID: string, timingFlag: string) => void)
117
+ | undefined;
118
+ _markTiming?: ((pipelineID: string, timingKey: string) => void) | undefined;
119
+ }
120
+
121
+ /** @internal */
122
+ export interface HostLynxObject {
123
+ SystemInfo?: LynxSystemInfo | undefined;
124
+ performance?: HostPerformanceObject | undefined;
125
+ __globalProps?: Record<string, unknown> | undefined;
126
+ __initData?: Record<string, unknown> | undefined;
127
+ getEngine?: (() => HostContextProxy | undefined) | undefined;
128
+ getNative?: (() => HostContextProxy | undefined) | undefined;
129
+ getCoreContext?: (() => HostContextProxy | undefined) | undefined;
130
+ getJSContext?: (() => HostContextProxy | undefined) | undefined;
131
+ getApp?: (() => HostBTSApp | undefined) | undefined;
132
+ getJSModule?: ((moduleName: string) => unknown) | undefined;
133
+ }
134
+
135
+ /**
136
+ * @internal
137
+ */
138
+ export interface HostGlobalScope {
139
+ __FlushElementTree?:
140
+ | ((page?: unknown, options?: Readonly<MTSFlushOptions>) => void)
141
+ | undefined;
142
+ SystemInfo?: LynxSystemInfo | undefined;
143
+ lynx?: HostLynxObject | undefined;
144
+ tt?: HostBTSApp | undefined;
145
+ currentAppId?: string | undefined;
146
+ multiApps?: Record<string, HostBTSApp | undefined> | undefined;
147
+ renderPage?:
148
+ | ((data: Record<string, unknown>, options?: MTSRenderOptions) => void)
149
+ | undefined;
150
+ updatePage?:
151
+ | ((data: Record<string, unknown>, options?: MTSReloadOptions) => void)
152
+ | undefined;
153
+ updateGlobalProps?:
154
+ | ((data: Record<string, unknown>, options?: MTSFlushContext) => void)
155
+ | undefined;
156
+ processData?:
157
+ | ((data: unknown, processorName?: string) => unknown)
158
+ | undefined;
159
+ getPageData?: ((keys?: string[]) => unknown) | undefined;
160
+ removeComponents?: (() => void) | undefined;
161
+ }
@@ -0,0 +1,129 @@
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 type { HostContextProxy, HostMessageEvent } from './host-types.js';
6
+ import { dispatchListeners } from './protocol.js';
7
+ import type { Unsubscribe } from './types.js';
8
+
9
+ /** @internal */
10
+ export interface MultiplexEntry<TCallback> {
11
+ listeners: Map<TCallback, Unsubscribe>;
12
+ unsubscribeHost: Unsubscribe;
13
+ releaseIfEmpty: () => void;
14
+ }
15
+
16
+ /** @internal */
17
+ export type MultiplexMap<TCallback> = Map<string, MultiplexEntry<TCallback>>;
18
+
19
+ /** @internal */
20
+ export type MessageSubscriptions = MultiplexMap<(data: unknown) => void>;
21
+
22
+ /**
23
+ * Share one underlying host listener per event key, deduplicating identical
24
+ * callbacks and unsubscribing from the host when the last listener leaves.
25
+ * Defer host unsubscription when the last listener leaves mid-dispatch so
26
+ * host emitters iterating live listener arrays do not skip sibling listeners.
27
+ * @internal
28
+ */
29
+ export function subscribeMultiplexed<
30
+ TCallback extends (...args: never[]) => void,
31
+ >(
32
+ subscriptions: MultiplexMap<TCallback>,
33
+ key: string,
34
+ callback: TCallback,
35
+ attachHost: (
36
+ dispatch: (invoke: (fn: TCallback) => void) => void,
37
+ ) => Unsubscribe,
38
+ ): Unsubscribe {
39
+ let entry = subscriptions.get(key);
40
+ if (!entry) {
41
+ const listeners = new Map<TCallback, Unsubscribe>();
42
+ let dispatching = 0;
43
+ let detachScheduled = false;
44
+ const unsubscribeHost = attachHost((invoke) => {
45
+ dispatching++;
46
+ try {
47
+ dispatchListeners(listeners, invoke);
48
+ } finally {
49
+ dispatching--;
50
+ }
51
+ });
52
+ const detachIfEmpty = (): void => {
53
+ if (listeners.size === 0 && subscriptions.get(key) === created) {
54
+ subscriptions.delete(key);
55
+ unsubscribeHost();
56
+ }
57
+ };
58
+ const created: MultiplexEntry<TCallback> = {
59
+ listeners,
60
+ unsubscribeHost,
61
+ releaseIfEmpty: () => {
62
+ if (dispatching === 0) {
63
+ detachIfEmpty();
64
+ return;
65
+ }
66
+ if (detachScheduled) return;
67
+ detachScheduled = true;
68
+ void Promise.resolve().then(() => {
69
+ detachScheduled = false;
70
+ detachIfEmpty();
71
+ });
72
+ },
73
+ };
74
+ entry = created;
75
+ subscriptions.set(key, created);
76
+ }
77
+ const current = entry;
78
+ const existing = current.listeners.get(callback);
79
+ if (existing) return existing;
80
+
81
+ const dispose = (): void => {
82
+ if (current.listeners.get(callback) !== dispose) return;
83
+ current.listeners.delete(callback);
84
+ if (current.listeners.size === 0) {
85
+ current.releaseIfEmpty();
86
+ }
87
+ };
88
+ current.listeners.set(callback, dispose);
89
+ return dispose;
90
+ }
91
+
92
+ /** @internal */
93
+ export function clearMultiplexed<TCallback>(
94
+ subscriptions: MultiplexMap<TCallback>,
95
+ ): void {
96
+ for (const entry of subscriptions.values()) {
97
+ entry.listeners.clear();
98
+ entry.unsubscribeHost();
99
+ }
100
+ subscriptions.clear();
101
+ }
102
+
103
+ /**
104
+ * Keep one host listener per message type without taking over the proxy's global hook.
105
+ * @internal
106
+ */
107
+ export function subscribeMessage<T>(
108
+ subscriptions: MessageSubscriptions,
109
+ proxy: HostContextProxy,
110
+ type: string,
111
+ listener: (this: void, data: T) => void,
112
+ ): Unsubscribe {
113
+ return subscribeMultiplexed(
114
+ subscriptions,
115
+ type,
116
+ listener as (data: unknown) => void,
117
+ (dispatch) => {
118
+ const onEvent = (event: HostMessageEvent): void => {
119
+ dispatch((fn) => {
120
+ fn(event.data);
121
+ });
122
+ };
123
+ proxy.addEventListener(type, onEvent);
124
+ return () => {
125
+ proxy.removeEventListener(type, onEvent);
126
+ };
127
+ },
128
+ );
129
+ }
@@ -0,0 +1,65 @@
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 type { HostPerformanceObject } from './host-types.js';
6
+ import type {
7
+ CreatePipelineOptions,
8
+ CreatedPipelineOptions,
9
+ PipelineOptions,
10
+ } from './types.js';
11
+
12
+ /** @internal */
13
+ export function createHostPipeline(
14
+ perf: HostPerformanceObject | undefined,
15
+ options: CreatePipelineOptions | undefined,
16
+ side: 'mts' | 'bts',
17
+ sdkVersion?: string,
18
+ ): CreatedPipelineOptions | undefined {
19
+ const pipeline = perf?._generatePipelineOptions?.();
20
+ const id = pipeline?.pipelineID;
21
+ if (!pipeline || !id) return undefined;
22
+
23
+ if (options?.needTimestamps !== undefined) {
24
+ pipeline.needTimestamps = options.needTimestamps;
25
+ }
26
+ if (options?.pipelineOrigin !== undefined) {
27
+ pipeline.pipelineOrigin = options.pipelineOrigin;
28
+ }
29
+ if (options?.dsl !== undefined) pipeline.dsl = options.dsl;
30
+ if (options?.stage !== undefined) pipeline.stage = options.stage;
31
+ if (side === 'mts') {
32
+ if (pipeline.pipelineOrigin) {
33
+ perf?._onPipelineStart?.(id, pipeline.pipelineOrigin);
34
+ } else {
35
+ perf?._onPipelineStart?.(id);
36
+ }
37
+ } else {
38
+ const [major = 0, minor = 0] = (sdkVersion ?? '1.0').split('.').map(Number);
39
+ if (major > 3 || (major === 3 && minor > 0)) {
40
+ perf?._onPipelineStart?.(id, pipeline);
41
+ } else {
42
+ perf?._onPipelineStart?.(id);
43
+ }
44
+ }
45
+ const flag = options?.timingFlag;
46
+ if (flag) {
47
+ if (side === 'mts') {
48
+ perf?._bindPipelineIDWithTimingFlag?.(id, flag);
49
+ } else {
50
+ perf?._bindPipelineIdWithTimingFlag?.(id, flag);
51
+ }
52
+ }
53
+ return pipeline as CreatedPipelineOptions;
54
+ }
55
+
56
+ /** @internal */
57
+ export function markHostTiming(
58
+ perf: HostPerformanceObject | undefined,
59
+ pipeline: string | PipelineOptions | undefined,
60
+ timingKey: string,
61
+ ): void {
62
+ const id = typeof pipeline === 'string' ? pipeline : pipeline?.pipelineID;
63
+ if (!id || !timingKey) return;
64
+ perf?._markTiming?.(id, timingKey);
65
+ }
@@ -0,0 +1,98 @@
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 type { Unsubscribe } from './types.js';
6
+
7
+ /**
8
+ * Native Engine / Native ContextProxy event names (Lynx SDK 3.4+).
9
+ */
10
+ export const NATIVE_EVENT_RENDER_PAGE = '__RenderPage';
11
+ export const NATIVE_EVENT_UPDATE_PAGE = '__UpdatePage';
12
+ export const NATIVE_EVENT_UPDATE_GLOBAL_PROPS = '__UpdateGlobalProps';
13
+ export const NATIVE_EVENT_DESTROY_LIFETIME = '__DestroyLifetime';
14
+
15
+ export function isPlainRecord(
16
+ value: unknown,
17
+ ): value is Record<string, unknown> {
18
+ if (!value || typeof value !== 'object' || Array.isArray(value)) {
19
+ return false;
20
+ }
21
+ const prototype: unknown = Object.getPrototypeOf(value);
22
+ return prototype === null || prototype === Object.prototype;
23
+ }
24
+
25
+ /**
26
+ * Run teardown/cleanup callbacks so an earlier failure never skips remaining
27
+ * destruction hooks or host listener cleanup, then rethrow the first error.
28
+ */
29
+ export function invokeAll(callbacks: Iterable<() => void>): void {
30
+ let firstError: unknown;
31
+ let hasError = false;
32
+ for (const fn of callbacks) {
33
+ try {
34
+ fn();
35
+ } catch (err) {
36
+ if (!hasError) {
37
+ hasError = true;
38
+ firstError = err;
39
+ }
40
+ }
41
+ }
42
+ if (hasError) {
43
+ throw firstError;
44
+ }
45
+ }
46
+
47
+ /** Each effective subscription has an identity that outlives its callback key. */
48
+ export function subscribeListener<T>(
49
+ listeners: Map<T, Unsubscribe>,
50
+ listener: T,
51
+ ): Unsubscribe {
52
+ const existing = listeners.get(listener);
53
+ if (existing) return existing;
54
+ const dispose = (): void => {
55
+ if (listeners.get(listener) === dispose) listeners.delete(listener);
56
+ };
57
+ listeners.set(listener, dispose);
58
+ return dispose;
59
+ }
60
+
61
+ /** Additions wait until the next dispatch; cancellations take effect immediately. */
62
+ export function dispatchListeners<T>(
63
+ listeners: Map<T, Unsubscribe>,
64
+ invoke: (listener: T) => void,
65
+ ): void {
66
+ for (const [listener, registration] of [...listeners]) {
67
+ if (listeners.get(listener) === registration) {
68
+ invoke(listener);
69
+ }
70
+ }
71
+ }
72
+
73
+ /** Copy plain records and arrays at an ownership boundary; retain opaque values by reference. */
74
+ export function copyHostData<T>(value: T): T {
75
+ if (Array.isArray(value)) {
76
+ return (value as unknown[]).map((item) => copyHostData(item)) as T;
77
+ }
78
+ if (!isPlainRecord(value)) {
79
+ return value;
80
+ }
81
+ const copy = (
82
+ Object.getPrototypeOf(value) === null ? Object.create(null) : {}
83
+ ) as Record<string, unknown>;
84
+ for (const key of Object.keys(value)) {
85
+ const copiedValue = copyHostData(value[key]);
86
+ if (key === '__proto__') {
87
+ Object.defineProperty(copy, key, {
88
+ value: copiedValue,
89
+ enumerable: true,
90
+ writable: true,
91
+ configurable: true,
92
+ });
93
+ } else {
94
+ copy[key] = copiedValue;
95
+ }
96
+ }
97
+ return copy as T;
98
+ }