lynx-family · Huxpro · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026 · Feb 28, 2026
diff --git a/.changeset/align-lynx-terminology.md b/.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.
@@ -113,9 +113,9 @@ export function pluginLynxConfig(
 
       api.modifyBundlerChain(chain => {
         const exposed = api.useExposed<
-          { LynxTemplatePlugin: typeof LynxTemplatePlugin }
+          { LynxBundlePlugin: typeof LynxTemplatePlugin }
         >(
-          Symbol.for('LynxTemplatePlugin'),
+          Symbol.for('LynxBundlePlugin'),
         )
 
         if (!exposed) {
@@ -131,7 +131,7 @@ export function pluginLynxConfig(
 
           throw new Error(
             `\
-[pluginLynxConfig] No \`LynxTemplatePlugin\` exposed to ${
+[pluginLynxConfig] No \`LynxBundlePlugin\` exposed to ${
               link(
                 'the plugin API',
                 'https://rsbuild.rs/plugins/dev/core#apiexpose',
@@ -150,7 +150,7 @@ See ${
           )
         }
 
-        const { LynxTemplatePlugin: LynxTemplatePluginClass } = exposed
+        const { LynxBundlePlugin: LynxTemplatePluginClass } = exposed
 
         chain.plugin('lynx:config').use(LynxConfigWebpackPlugin<Config>, [
           {

@@ -24,7 +24,7 @@ describe('pluginLynxConfig', () => {
 
     await expect(() => rspeedy.initConfigs()).rejects
       .toThrowErrorMatchingInlineSnapshot(`
-      [Error: [pluginLynxConfig] No \`LynxTemplatePlugin\` exposed to the plugin API (https://rsbuild.rs/plugins/dev/core#apiexpose).
+      [Error: [pluginLynxConfig] No \`LynxBundlePlugin\` exposed to the plugin API (https://rsbuild.rs/plugins/dev/core#apiexpose).
 
       Please upgrade Rspeedy and plugins to latest version.
 
@@ -50,7 +50,7 @@ describe('pluginLynxConfig', () => {
 
     await expect(() => rspeedy.initConfigs()).rejects
       .toThrowErrorMatchingInlineSnapshot(`
-      [Error: [pluginLynxConfig] No \`LynxTemplatePlugin\` exposed to the plugin API (https://rsbuild.rs/plugins/dev/core#apiexpose).
+      [Error: [pluginLynxConfig] No \`LynxBundlePlugin\` exposed to the plugin API (https://rsbuild.rs/plugins/dev/core#apiexpose).
 
       Please upgrade @lynx-js/react-rsbuild-plugin to latest version.
 
@@ -80,7 +80,7 @@ describe('pluginLynxConfig', () => {
 
     await expect(() => rspeedy.initConfigs()).rejects
       .toThrowErrorMatchingInlineSnapshot(`
-      [Error: [pluginLynxConfig] No \`LynxTemplatePlugin\` exposed to the plugin API (https://rsbuild.rs/plugins/dev/core#apiexpose).
+      [Error: [pluginLynxConfig] No \`LynxBundlePlugin\` exposed to the plugin API (https://rsbuild.rs/plugins/dev/core#apiexpose).
 
       Please upgrade @lynx-js/vue-rsbuild-plugin to latest version.
 
@@ -104,8 +104,8 @@ describe('pluginLynxConfig', () => {
           {
             name: 'test',
             setup(api: RsbuildPluginAPI) {
-              api.expose(Symbol.for('LynxTemplatePlugin'), {
-                LynxTemplatePlugin,
+              api.expose(Symbol.for('LynxBundlePlugin'), {
+                LynxBundlePlugin: LynxTemplatePlugin,
               })
             },
           },

@@ -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,13 @@ 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)
-//
-// @public (undocumented)
-export interface LynxTemplatePlugin {
+// @public
+interface LynxBundlePlugin {
     // (undocumented)
     getLynxTemplatePluginHooks: typeof LynxTemplatePlugin_2.getLynxTemplatePluginHooks;
 }
+export { LynxBundlePlugin }
+export { LynxBundlePlugin as LynxTemplatePlugin }
 
 // @public
 export function pluginReactLynx(userOptions?: PluginReactLynxOptions): RsbuildPlugin[];
@@ -93,6 +96,4 @@ export interface ShakeVisitorConfig {
     retainProp: Array<string>
 }
 
-export { TemplateHooks }
-
 ```
@@ -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,24 @@ export type {
   ShakeVisitorConfig,
 } from '@lynx-js/react-transform'
 
-interface LynxTemplatePlugin {
+/**
+ * The exposed Lynx Bundle Plugin API.
+ *
+ * @public
+ */
+interface LynxBundlePlugin {
   getLynxTemplatePluginHooks:
     typeof InnerLynxTemplatePlugin.getLynxTemplatePluginHooks
 }
 
 // We only export types here
-// It is encouraged to use `api.useExposed(Symbol.for('LynxTemplatePlugin'))`
+// It is encouraged to use `api.useExposed(Symbol.for('LynxBundlePlugin'))`
 // 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'
@@ -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
    */
@@ -389,15 +390,15 @@ export function pluginReactLynx(
         }
 
         api.expose(Symbol.for('LAYERS'), LAYERS)
-        // Only expose `LynxTemplatePlugin.getLynxTemplatePluginHooks` to avoid
-        // other breaking changes in `LynxTemplatePlugin`
-        // breaks `pluginReactLynx`
-        api.expose(Symbol.for('LynxTemplatePlugin'), {
-          LynxTemplatePlugin: {
+        const exposedLynxBundlePlugin = {
+          LynxBundlePlugin: {
             getLynxTemplatePluginHooks: LynxTemplatePlugin
               .getLynxTemplatePluginHooks.bind(LynxTemplatePlugin),
           },
-        })
+        }
+        api.expose(Symbol.for('LynxBundlePlugin'), exposedLynxBundlePlugin)
+        // Backward compat: expose under old symbol too
+        api.expose(Symbol.for('LynxTemplatePlugin'), exposedLynxBundlePlugin)
         const require = createRequire(import.meta.url)
 
         const { version } = require('../package.json') as { version: string }

@@ -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: {

@@ -12,7 +12,7 @@ describe('Expose', () => {
   test('LynxTemplatePlugin', async () => {
     const { pluginReactLynx } = await import('../src/index.js')
 
-    let expose: { LynxTemplatePlugin: LynxTemplatePlugin } | undefined
+    let expose: { LynxBundlePlugin: LynxTemplatePlugin } | undefined
     let beforeEncodeArgs:
       | Parameters<Parameters<TemplateHooks['beforeEncode']['tap']>[1]>[0]
       | undefined
@@ -31,16 +31,16 @@ describe('Expose', () => {
             name: 'pluginThatUsesTemplateHooks',
             setup(api) {
               expose = api.useExposed<
-                { LynxTemplatePlugin: LynxTemplatePlugin }
-              >(Symbol.for('LynxTemplatePlugin'))
+                { LynxBundlePlugin: LynxTemplatePlugin }
+              >(Symbol.for('LynxBundlePlugin'))
               api.modifyBundlerChain(chain => {
                 const PLUGIN_NAME = 'pluginThatUsesTemplateHooks'
                 chain.plugin(PLUGIN_NAME).use({
                   apply(compiler) {
                     compiler.hooks.compilation.tap(
                       PLUGIN_NAME,
                       compilation => {
-                        const templateHooks = expose!.LynxTemplatePlugin
+                        const templateHooks = expose!.LynxBundlePlugin
                           .getLynxTemplatePluginHooks(
                             compilation as unknown as Parameters<
                               LynxTemplatePlugin['getLynxTemplatePluginHooks']
@@ -67,7 +67,7 @@ describe('Expose', () => {
     await rsbuild.initConfigs()
     expect(expose).toMatchInlineSnapshot(`
       {
-        "LynxTemplatePlugin": {
+        "LynxBundlePlugin": {
           "getLynxTemplatePluginHooks": [Function],
         },
       }

@@ -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

@@ -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 },

@@ -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;