refactor: align Lynx terminology with official specification

.changeset/align-lynx-terminology.md

@@ -0,0 +1,9 @@
+---
+"@lynx-js/web-constants": patch
+"@lynx-js/web-core": patch
+"@lynx-js/react-webpack-plugin": patch
+"@lynx-js/template-webpack-plugin": patch
+"@lynx-js/react-rsbuild-plugin": patch
+---
+
+Align codebase terminology with the official Lynx specification. Add new preferred type aliases (`LynxBundle`, `BundleLoader`, `DecodedBundle`, `BundleSectionLabel`, `BundleHooks`, `LynxBundlePlugin`, `LynxBundlePluginOptions`) and deprecate legacy names.

packages/rspeedy/plugin-react/etc/react-rsbuild-plugin.api.md

@@ -4,16 +4,19 @@
 
 ```ts
 
+import type { BundleHooks } from '@lynx-js/template-webpack-plugin';
 import { LAYERS } from '@lynx-js/react-webpack-plugin';
 import type { LynxTemplatePlugin as LynxTemplatePlugin_2 } from '@lynx-js/template-webpack-plugin';
 import type { RsbuildPlugin } from '@rsbuild/core';
-import type { TemplateHooks } from '@lynx-js/template-webpack-plugin';
 
 // @public
 export interface AddComponentElementConfig {
     compilerOnly: boolean
 }
 
+export { BundleHooks }
+export { BundleHooks as TemplateHooks }
+
 // @public
 export interface CompatVisitorConfig {
     addComponentElement: boolean | AddComponentElementConfig
@@ -48,13 +51,15 @@ export interface ExtractStrConfig {
 
 export { LAYERS }
 
-// Warning: (ae-missing-release-tag) "LynxTemplatePlugin" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+// Warning: (ae-missing-release-tag) "LynxBundlePlugin" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
-export interface LynxTemplatePlugin {
+interface LynxBundlePlugin {
     // (undocumented)
     getLynxTemplatePluginHooks: typeof LynxTemplatePlugin_2.getLynxTemplatePluginHooks;
 }
+export { LynxBundlePlugin }
+export { LynxBundlePlugin as LynxTemplatePlugin }
 
 // @public
 export function pluginReactLynx(userOptions?: PluginReactLynxOptions): RsbuildPlugin[];
@@ -93,6 +98,4 @@ export interface ShakeVisitorConfig {
     retainProp: Array<string>
 }
 
-export { TemplateHooks }
-
 ```

packages/rspeedy/plugin-react/src/index.ts

@@ -9,8 +9,8 @@
  */
 
 import type {
+  BundleHooks,
   LynxTemplatePlugin as InnerLynxTemplatePlugin,
-  TemplateHooks,
 } from '@lynx-js/template-webpack-plugin'
 
 export { pluginReactLynx } from './pluginReactLynx.js'
@@ -24,14 +24,19 @@ export type {
   ShakeVisitorConfig,
 } from '@lynx-js/react-transform'
 
-interface LynxTemplatePlugin {
+interface LynxBundlePlugin {
   getLynxTemplatePluginHooks:
     typeof InnerLynxTemplatePlugin.getLynxTemplatePluginHooks
 }
 
 // We only export types here
 // It is encouraged to use `api.useExposed(Symbol.for('LynxTemplatePlugin'))`
 // to access the actual API
-export type { LynxTemplatePlugin, TemplateHooks }
+export type { LynxBundlePlugin }
+export type { BundleHooks }
+/** @deprecated Use {@link LynxBundlePlugin} instead. */
+export type { LynxBundlePlugin as LynxTemplatePlugin }
+/** @deprecated Use {@link BundleHooks} instead. */
+export type { BundleHooks as TemplateHooks }
 
 export { LAYERS } from '@lynx-js/react-webpack-plugin'

packages/rspeedy/plugin-react/src/pluginReactLynx.ts

@@ -197,16 +197,17 @@ export interface PluginReactLynxOptions {
   enableRemoveCSSScope?: boolean | undefined
 
   /**
-   * This flag controls when MainThread (Lepus) transfers control to Background after the first screen
+   * This flag controls when Main Thread Script (MTS) transfers
+   * control to Background Thread Script (BTS) after the first screen.
    *
    * This flag has two options:
    *
    * `"immediately"`: Transfer immediately
    *
    * `"jsReady"`: Transfer when background (JS Runtime) is ready
    *
-   * After handing over control, MainThread (Lepus) runtime can no longer respond to data updates,
-   * and data updates will be forwarded to background (JS Runtime) and processed __asynchronously__
+   * After handing over control, Main Thread Script (MTS) runtime can no longer respond to data updates,
+   * and data updates will be forwarded to Background Thread Script (BTS) and processed __asynchronously__
    *
    * @defaultValue "immediately"
    */
@@ -252,8 +253,8 @@ export interface PluginReactLynxOptions {
   targetSdkVersion?: string
 
   /**
-   * Merge same string literals in JS and Lepus to reduce output bundle size.
-   * Set to `false` to disable.
+   * Merge same string literals in JS and Main Thread Script (MTS)
+   * to reduce output bundle size. Set to `false` to disable.
    *
    * @defaultValue false
    */

packages/rspeedy/plugin-react/test/config.test.ts

@@ -1925,6 +1925,7 @@ describe('Config', () => {
             lynx: {},
           },
           plugins: [
+            pluginStubRspeedyAPI(),
             pluginReactLynx({
               defineDCE: { define: { __SOME_MACRO__: 'false' } },
             }),
@@ -1957,6 +1958,7 @@ describe('Config', () => {
             lynx: {},
           },
           plugins: [
+            pluginStubRspeedyAPI(),
             pluginReactLynx({
               defineDCE: {
                 define: {

packages/web-platform/web-constants/src/endpoints.ts

@@ -95,6 +95,13 @@ export const flushElementTreeEndpoint = createRpcEndpoint<
   void
 >('flushElementTree', false, true);
 
+/**
+ * Calls a method on the Main Thread Script (MTS) runtime.
+ *
+ * @remarks
+ * `callLepusMethod` is a legacy endpoint name. "Lepus" is the legacy term
+ * for Main Thread Script (MTS) in the Lynx specification.
+ */
 export const callLepusMethodEndpoint = createRpcEndpoint<
   [name: string, data: unknown],
   void

packages/web-platform/web-constants/src/types/LynxModule.ts

@@ -18,7 +18,16 @@ export type ElementTemplateData = {
   dataset?: Record<string, string>;
 };
 
-export interface LynxTemplate {
+/**
+ * Represents a Lynx Bundle — the compiled artifact containing all necessary
+ * resources (stylesheet, scripts, serialized element tree) for a Lynx
+ * application to run.
+ *
+ * @remarks
+ * This interface corresponds to the "Bundle" concept in the official Lynx
+ * specification.
+ */
+export interface LynxBundle {
   styleInfo: StyleInfo;
   pageConfig: PageConfig;
   customSections: {
@@ -28,10 +37,27 @@ export interface LynxTemplate {
     };
   };
   cardType?: string;
+  /**
+   * Main Thread Script (MTS) — code that runs on the main thread (UI thread).
+   *
+   * @remarks
+   * In the official Lynx specification this is called "Main Thread Script"
+   * (MTS). The field name `lepusCode` is a legacy artifact that cannot be
+   * renamed as it is part of the wire format.
+   */
   lepusCode: {
     root: string;
     [key: string]: string;
   };
+  /**
+   * Background Thread Script (BTS) — code that runs on the background thread.
+   *
+   * @remarks
+   * In the official Lynx specification this is called "Background Thread
+   * Script" (BTS). The field name `manifest` is a legacy artifact that cannot
+   * be renamed as it is part of the wire format. The key `'/app-service.js'`
+   * is a conventional entry point name for BTS.
+   */
   manifest: {
     '/app-service.js': string;
     [key: string]: string;
@@ -41,6 +67,11 @@ export interface LynxTemplate {
   appType: 'card' | 'lazy';
 }
 
+/**
+ * @deprecated Use {@link LynxBundle} instead.
+ */
+export type LynxTemplate = LynxBundle;
+
 export type BTSChunkEntry = (
   postMessage: undefined,
   module: { exports: unknown },

packages/web-platform/web-constants/src/types/TemplateLoader.ts

@@ -1,3 +1,11 @@
-import type { LynxTemplate } from './LynxModule.js';
+import type { LynxBundle } from './LynxModule.js';
 
-export type TemplateLoader = (url: string) => Promise<LynxTemplate>;
+/**
+ * Loads a Lynx Bundle from the given URL.
+ */
+export type BundleLoader = (url: string) => Promise<LynxBundle>;
+
+/**
+ * @deprecated Use {@link BundleLoader} instead.
+ */
+export type TemplateLoader = BundleLoader;

packages/web-platform/web-core-wasm/ts/constants.ts

@@ -51,19 +51,60 @@
 export const MagicHeader0 = /*#__PURE__*/ 0x41524453; // 'SDRA'
 export const MagicHeader1 = /*#__PURE__*/ 0x464F5257; // 'WROF'
 
+/**
+ * Section labels used in the binary Lynx Bundle encoding format.
+ *
+ * @remarks
+ * `BackgroundThreadScript` corresponds to "Manifest" in legacy code.
+ * `MainThreadScript` corresponds to "LepusCode" in legacy code.
+ * Wire values are unchanged.
+ */
+export const BundleSectionLabel = /*#__PURE__*/ {
+  /** Background Thread Script (BTS). Legacy name: "Manifest". */
+  BackgroundThreadScript: 1,
+  StyleInfo: 2,
+  /** Main Thread Script (MTS). Legacy name: "LepusCode". */
+  MainThreadScript: 3,
+  CustomSections: 4,
+  ElementTemplates: 5,
+  Configurations: 6,
+} as const;
+
+/**
+ * @deprecated Use {@link BundleSectionLabel} instead.
+ */
 export const TemplateSectionLabel = /*#__PURE__*/ {
+  /** @deprecated Use {@link BundleSectionLabel.BackgroundThreadScript} instead. */
   Manifest: 1,
   StyleInfo: 2,
+  /** @deprecated Use {@link BundleSectionLabel.MainThreadScript} instead. */
   LepusCode: 3,
   CustomSections: 4,
   ElementTemplates: 5,
   Configurations: 6,
+/**
+ * Section labels used in the binary Lynx Bundle encoding format.
+ *
+ * @remarks
+ * `BackgroundThreadScript` corresponds to "Manifest" in legacy code.
+ * `MainThreadScript` corresponds to "LepusCode" in legacy code.
+ * Wire values are unchanged.
+ */
+export const BundleSectionLabel = /*#__PURE__*/ {
+  /** Background Thread Script (BTS). Legacy name: "Manifest". */
+  BackgroundThreadScript: 1,
+  StyleInfo: 2,
+  /** Main Thread Script (MTS). Legacy name: "LepusCode". */
+  MainThreadScript: 3,
+  CustomSections: 4,
+  ElementTemplates: 5,
+  Configurations: 6,
 } as const;
 
 /**
  * const enum will be shakedown in Typescript Compiler
  */
 export const enum ErrorCode {
   SUCCESS = 0,
   UNKNOWN = 1,
   NODE_NOT_FOUND = 2,

packages/web-platform/web-core-wasm/ts/encode/webEncoder.ts

@@ -61,10 +61,18 @@ function encodeStringMap(map: Record<string, string>): Uint8Array {
 
 export type TasmJSONInfo = {
   styleInfo: Record<string, CSS.LynxStyleNode[]>;
+  /**
+   * Background Thread Script (BTS) chunks.
+   * @remarks The field name `manifest` is a legacy artifact.
+   */
   manifest: Record<string, string>;
   cardType: string;
   appType: string;
   pageConfig: Record<string, unknown>;
+  /**
+   * Main Thread Script (MTS) chunks.
+   * @remarks The field name `lepusCode` is a legacy artifact.
+   */
   lepusCode: Record<string, string>;
   customSections: Record<string, {
     type?: 'lazy';

packages/web-platform/web-core-wasm/ts/types/DecodedTemplate.ts

@@ -7,10 +7,29 @@
 import type { PageConfig } from './PageConfig.js';
 import type { StyleSheetResource } from '../../binary/client/client.js';
 
-export interface DecodedTemplate {
+/**
+ * A decoded Lynx Bundle with its sections parsed into JS objects / blob URLs.
+ *
+ * @remarks
+ * This interface corresponds to the "Bundle" concept in the official Lynx
+ * specification.
+ */
+export interface DecodedBundle {
   config?: PageConfig;
+  /**
+   * Main Thread Script (MTS) — code that runs on the main thread (UI thread).
+   *
+   * @remarks
+   * In the official Lynx specification this is called "Main Thread Script"
+   * (MTS). The field name `lepusCode` is a legacy artifact.
+   */
   lepusCode?: Record<string, string>;
   customSections?: Record<string, any>;
   backgroundCode?: Record<string, string>;
   styleSheet?: StyleSheetResource;
 }
+
+/**
+ * @deprecated Use {@link DecodedBundle} instead.
+ */
+export type DecodedTemplate = DecodedBundle;

packages/web-platform/web-core/src/index.ts

@@ -3,4 +3,6 @@
 // LICENSE file in the root directory of this source tree.
 export { createLynxView } from './apis/createLynxView.js';
 export { LynxView } from './apis/LynxView.js';
+/** @deprecated Use {@link LynxBundle} instead. `LynxTemplate` is a legacy name. */
 export type { LynxTemplate } from '@lynx-js/web-constants';
+export type { LynxBundle } from '@lynx-js/web-constants';

packages/web-platform/web-mainthread-apis/ts/createMainThreadGlobalThis.ts

@@ -147,6 +147,7 @@ export interface MainThreadRuntimeConfig {
   pageConfig: PageConfig;
   globalProps: unknown;
   callbacks: MainThreadRuntimeCallbacks;
+  /** The Lynx Bundle (legacy field name: `lynxTemplate`). */
   lynxTemplate: LynxTemplate;
   browserConfig: BrowserConfig;
   tagMap: Record<string, string>;
@@ -676,6 +677,13 @@ export function createMainThreadGlobalThis(
     );
   };
 
+  /**
+   * Loads a Main Thread Script (MTS) chunk by path.
+   *
+   * @remarks
+   * `__LoadLepusChunk` is a legacy function name. "Lepus" is the legacy term
+   * for Main Thread Script (MTS) in the Lynx specification.
+   */
   const __LoadLepusChunk: (path: string) => boolean = (path) => {
     try {
       path = lepusCode?.[path] ?? path;

packages/web-platform/web-mainthread-apis/ts/crossThreadHandlers/registerCallLepusMethodHandler.ts

@@ -7,6 +7,12 @@ import {
   type Rpc,
 } from '@lynx-js/web-constants';
 
+/**
+ * Registers a handler for calling Main Thread Script (MTS) methods.
+ *
+ * @remarks
+ * "Lepus" in the function name is a legacy term for Main Thread Script (MTS).
+ */
 export function registerCallLepusMethodHandler(
   rpc: Rpc,
   runtime: MainThreadGlobalThis,

packages/webpack/react-webpack-plugin/src/ReactWebpackPlugin.ts

@@ -44,8 +44,8 @@ interface ReactWebpackPluginOptions {
   mainThreadChunks?: string[] | undefined;
 
   /**
-   * Merge same string literals in JS and Lepus to reduce output bundle size.
-   * Set to `false` to disable.
+   * Merge same string literals in JS and Main Thread Script (MTS)
+   * to reduce output bundle size. Set to `false` to disable.
    *
    * @defaultValue false
    */

packages/webpack/react-webpack-plugin/src/loaders/options.ts

@@ -15,6 +15,7 @@ import type {
 
 const PLUGIN_NAME = 'react:webpack';
 const JSX_IMPORT_SOURCE = {
+  // `lepus` is a legacy path segment for Main Thread Script (MTS).
   MAIN_THREAD: '@lynx-js/react/lepus',
   BACKGROUND: '@lynx-js/react',
 };