@sigx/lynx-plugin 0.4.0 → 0.4.2

package/dist/css.js

@@ -0,0 +1,150 @@
+/**
+ * CSS extraction pipeline for SignalX Lynx.
+ *
+ * Mirrors the behaviour of `@lynx-js/react-rsbuild-plugin`'s `applyCSS()`:
+ *   1. Disables `style-loader` (forces CSS extraction via CssExtractPlugin).
+ *   2. Replaces the rsbuild-default CssExtract plugin with
+ *      `@lynx-js/css-extract-webpack-plugin` which emits Lynx-compatible CSS.
+ *   3. Removes `lightningcss-loader` (Lynx has its own CSS processor).
+ *   4. Configures the Main-Thread layer to ignore CSS entirely.
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { LAYERS } from './layers.js';
+const _dirname = path.dirname(fileURLToPath(import.meta.url));
+export function applyCSS(api, options) {
+    const { enableCSSSelector, enableCSSInvalidation } = options;
+    // ① Force CSS extraction (disable style-loader, enable CssExtractPlugin).
+    // Without this, rsbuild injects CSS via JS — useless in Lynx's native env.
+    api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
+        return mergeRsbuildConfig(config, {
+            output: { injectStyles: false },
+        });
+    });
+    // ② Replace the rsbuild-default CSS extraction plugin with the Lynx-aware
+    //    one, configure loaders per layer, and remove lightningcss.
+    api.modifyBundlerChain(async function handler(chain, { CHAIN_ID }) {
+        const { CssExtractRspackPlugin, CssExtractWebpackPlugin } = await import('@lynx-js/css-extract-webpack-plugin');
+        const CssExtractPlugin = api.context.bundlerType === 'rspack'
+            ? CssExtractRspackPlugin
+            : CssExtractWebpackPlugin;
+        const cssRules = [
+            CHAIN_ID.RULE.CSS,
+            CHAIN_ID.RULE.SASS,
+            CHAIN_ID.RULE.LESS,
+            CHAIN_ID.RULE.STYLUS,
+        ];
+        cssRules
+            .filter((rule) => chain.module.rules.has(rule))
+            .forEach((ruleName) => {
+            const rule = chain.module.rule(ruleName);
+            // Remove lightningcss-loader — Lynx processes CSS natively.
+            removeLightningCSS(rule, CHAIN_ID);
+            // Use the Lynx CssExtract loader for the Background layer.
+            rule
+                .issuerLayer(LAYERS.BACKGROUND)
+                .use(CHAIN_ID.USE.MINI_CSS_EXTRACT)
+                .loader(CssExtractPlugin.loader)
+                .end();
+            // Clone the existing CSS rule chain for the Main-Thread layer.
+            // Main-Thread bundles never contain user CSS — only the PAPI
+            // bootstrap code.  We replace all loaders with ignore-css + a
+            // css-loader configured for `exportOnlyLocals: true`.
+            const uses = rule.uses.entries();
+            const ruleEntries = rule.entries();
+            const cssLoaderRule = uses[CHAIN_ID.USE.CSS]?.entries();
+            chain.module
+                .rule(`${ruleName}:${LAYERS.MAIN_THREAD}`)
+                .merge(ruleEntries)
+                .issuerLayer(LAYERS.MAIN_THREAD)
+                .use(CHAIN_ID.USE.IGNORE_CSS)
+                .loader(path.resolve(_dirname, './loaders/ignore-css-loader'))
+                .end()
+                .uses.merge(uses)
+                .delete(CHAIN_ID.USE.MINI_CSS_EXTRACT)
+                .delete(CHAIN_ID.USE.LIGHTNINGCSS)
+                .delete(CHAIN_ID.USE.CSS)
+                .end();
+            // Re-add css-loader with exportOnlyLocals for main-thread
+            if (cssLoaderRule) {
+                chain.module
+                    .rule(`${ruleName}:${LAYERS.MAIN_THREAD}`)
+                    .use(CHAIN_ID.USE.CSS)
+                    .after(CHAIN_ID.USE.IGNORE_CSS)
+                    .merge(cssLoaderRule)
+                    .options(normalizeCssLoaderOptions(cssLoaderRule.options, true))
+                    .end();
+            }
+        });
+        // Also strip lightningcss from inline CSS rules (Rsbuild ≥1.3.0).
+        const RULE = CHAIN_ID.RULE;
+        const inlineCSSRuleNames = [
+            'CSS_INLINE',
+            'SASS_INLINE',
+            'LESS_INLINE',
+            'STYLUS_INLINE',
+        ];
+        inlineCSSRuleNames
+            .map((key) => RULE[key])
+            .filter((ruleName) => !!ruleName && chain.module.rules.has(ruleName))
+            .forEach((ruleName) => {
+            removeLightningCSS(chain.module.rule(ruleName), CHAIN_ID);
+        });
+        // ③ Replace the CssExtract plugin instance with the Lynx-aware one
+        //    and pass through the CSS selector / invalidation options.
+        chain
+            .plugin(CHAIN_ID.PLUGIN.MINI_CSS_EXTRACT)
+            .tap((args) => {
+            const [pluginOptions] = args;
+            return [
+                {
+                    ...pluginOptions,
+                    enableRemoveCSSScope: true,
+                    enableCSSSelector,
+                    enableCSSInvalidation,
+                    cssPlugins: [],
+                },
+            ];
+        })
+            .init((_, args) => {
+            return new CssExtractPlugin(...args);
+        })
+            .end()
+            .end();
+        function removeLightningCSS(rule, ids) {
+            if (rule.uses.has(ids.USE.LIGHTNINGCSS)) {
+                rule.uses.delete(ids.USE.LIGHTNINGCSS);
+            }
+        }
+    });
+}
+/**
+ * Force `exportOnlyLocals: true` on the css-loader modules config.
+ * Copied from rsbuild internals — required when the target is not `web`
+ * and CSS modules are enabled.
+ */
+const normalizeCssLoaderOptions = (options, exportOnlyLocals) => {
+    if (options.modules && exportOnlyLocals) {
+        let { modules } = options;
+        if (modules === true) {
+            modules = { exportOnlyLocals: true };
+        }
+        else if (typeof modules === 'string') {
+            modules = {
+                mode: modules,
+                exportOnlyLocals: true,
+            };
+        }
+        else {
+            modules = {
+                ...modules,
+                exportOnlyLocals: true,
+            };
+        }
+        return {
+            ...options,
+            modules,
+        };
+    }
+    return options;
+};

package/dist/entry.js

@@ -0,0 +1,443 @@
+/**
+ * Dual-thread entry splitting for SignalX Lynx.
+ *
+ * For each user-defined rsbuild entry, creates two webpack entries:
+ * - `<name>__main-thread` on the MAIN_THREAD layer (PAPI bootstrap via @sigx/lynx-runtime-main)
+ * - `<name>` on the BACKGROUND layer (sigx renderer + user app)
+ *
+ * Then registers @lynx-js/template-webpack-plugin to stitch both bundles
+ * into a single .lynx template.
+ */
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { LAYERS } from './layers.js';
+const PLUGIN_TEMPLATE = 'lynx:sigx-template';
+const PLUGIN_MARK_MAIN_THREAD = 'lynx:sigx-mark-main-thread';
+const PLUGIN_ENCODE = 'lynx:sigx-encode';
+const DEFAULT_INTERMEDIATE = '.rspeedy';
+const _dirname = path.dirname(fileURLToPath(import.meta.url));
+// sigx lynx-plugin package root — the plugin lives at <pkgRoot>/dist/,
+// so we resolve one level up from _dirname.
+const sigxLynxRoot = path.resolve(_dirname, '..');
+/**
+ * SigxMarkMainThreadPlugin forces webpack to generate startup code for MT
+ * entry chunks and marks their assets with `lynx:main-thread: true` so
+ * LynxTemplatePlugin routes them to lepusCode.root (Lepus bytecode).
+ */
+class SigxMarkMainThreadPlugin {
+    mainThreadFilenames;
+    constructor(mainThreadFilenames) {
+        this.mainThreadFilenames = mainThreadFilenames;
+    }
+    apply(compiler) {
+        const { RuntimeGlobals } = compiler.webpack;
+        compiler.hooks.thisCompilation.tap(PLUGIN_MARK_MAIN_THREAD, (compilation) => {
+            // Force startup code generation for MT entry chunks.
+            compilation.hooks.additionalTreeRuntimeRequirements.tap(PLUGIN_MARK_MAIN_THREAD, (chunk, set) => {
+                const entryOptions = chunk.getEntryOptions();
+                if (entryOptions?.layer === LAYERS.MAIN_THREAD) {
+                    set.add(RuntimeGlobals.startup);
+                    set.add(RuntimeGlobals.require);
+                }
+            });
+            // Mark MT assets with lynx:main-thread: true for LynxTemplatePlugin.
+            compilation.hooks.processAssets.tap({
+                name: PLUGIN_MARK_MAIN_THREAD,
+                stage: compiler.webpack.Compilation.PROCESS_ASSETS_STAGE_ADDITIONAL,
+            }, () => {
+                for (const filename of this.mainThreadFilenames) {
+                    const asset = compilation.getAsset(filename);
+                    if (asset) {
+                        compilation.updateAsset(filename, asset.source, {
+                            ...asset.info,
+                            'lynx:main-thread': true,
+                        });
+                    }
+                }
+            });
+        });
+    }
+}
+export async function applyEntry(api, opts = {}) {
+    // Preload @lynx-js/template-webpack-plugin via dynamic ESM import.
+    // rsbuild bundlerChain callbacks are sync, and template-webpack-plugin
+    // is pure-ESM (no "require" condition in its exports map), so createRequire
+    // fails. Stash the module in closure scope for the sync callback below.
+    let templateMod;
+    try {
+        templateMod = await import('@lynx-js/template-webpack-plugin');
+    }
+    catch {
+        // Optional peer — if missing, we'll still emit the two JS bundles.
+    }
+    // Preload @lynx-js/runtime-wrapper-webpack-plugin. This wraps the BG bundle
+    // in `__init_card_bundle__(lynxCoreInject, lynx, ...)` so user code inside
+    // can reference `lynx` and `lynxCoreInject` as bare identifiers — that's
+    // how the BG transport (lynx.getNativeApp().callLepusMethod) and the event
+    // dispatcher (lynxCoreInject.tt.publishEvent) get installed properly.
+    // Without this wrapper we'd be forced to spelunk through globalThis.multiApps.
+    let wrapperMod;
+    try {
+        wrapperMod = (await import('@lynx-js/runtime-wrapper-webpack-plugin'));
+    }
+    catch {
+        // Optional peer — if missing, lynx-runtime will still attempt the
+        // multiApps[appId]._nativeApp fallback, but proper hosts need the wrapper.
+    }
+    // Default to all-in-one chunk splitting to avoid async chunks that break
+    // Lynx's single-file bundle requirement.
+    api.modifyRsbuildConfig((config, { mergeRsbuildConfig }) => {
+        const userConfig = api.getRsbuildConfig('original');
+        if (!userConfig.performance?.chunkSplit?.strategy) {
+            return mergeRsbuildConfig(config, {
+                performance: { chunkSplit: { strategy: 'all-in-one' } },
+            });
+        }
+        return config;
+    });
+    // Exclude main-thread chunks from chunk splitting so each remains
+    // self-contained.
+    api.modifyRspackConfig((rspackConfig) => {
+        if (!rspackConfig.optimization)
+            return rspackConfig;
+        if (rspackConfig.optimization.splitChunks === false) {
+            rspackConfig.optimization.splitChunks = {};
+        }
+        if (rspackConfig.optimization.splitChunks) {
+            const prev = rspackConfig.optimization.splitChunks.chunks;
+            // biome-ignore lint/suspicious/noExplicitAny: rspack Chunk type not importable
+            rspackConfig.optimization.splitChunks.chunks = (chunk) => {
+                if (chunk.name?.includes('__main-thread'))
+                    return false;
+                if (typeof prev === 'function')
+                    return prev(chunk);
+                if (prev === 'all')
+                    return true;
+                if (prev === 'initial')
+                    return true;
+                return false;
+            };
+        }
+        return rspackConfig;
+    });
+    // Preload `@sigx/lynx-dev-client/install` — the JS-side console streamer.
+    // We resolve it eagerly (rather than relying on the bundler's resolver)
+    // so that:
+    //   * absence of the package is detected once at config time (consumer may
+    //     not depend on `@sigx/lynx-dev-client`), and
+    //   * we can pass an absolute path to rspack's entry, sidestepping any
+    //     subpath-export quirks.
+    //
+    // In linked / monorepo setups the plugin can live anywhere on disk, so we
+    // try multiple resolution bases — `api.context.rootPath`, the current
+    // process cwd, and finally the plugin's own location — and stop at the
+    // first one that finds it. This covers monorepo workspaces where the
+    // dev-client is hoisted to the workspace root as well as per-app installs.
+    //
+    // Returns `undefined` if the package isn't installed — the BG entry is
+    // then left alone and log streaming is a silent no-op for that project.
+    const resolveBases = [
+        path.join(api.context.rootPath, 'package.json'),
+        path.join(process.cwd(), 'package.json'),
+    ];
+    let devClientInstallPath;
+    for (const base of resolveBases) {
+        try {
+            devClientInstallPath = createRequire(base).resolve('@sigx/lynx-dev-client/install');
+            break;
+        }
+        catch {
+            // Subpath export may only declare `import` (Node CJS resolver wants
+            // `require`/`default`). Fall back to locating package.json and
+            // hand-constructing the path to dist/install.js.
+            try {
+                const pkgJson = createRequire(base).resolve('@sigx/lynx-dev-client/package.json');
+                const candidate = path.join(path.dirname(pkgJson), 'dist', 'install.js');
+                if (existsSync(candidate)) {
+                    devClientInstallPath = candidate;
+                    break;
+                }
+            }
+            catch {
+                // try next base
+            }
+        }
+    }
+    if (!devClientInstallPath) {
+        try {
+            devClientInstallPath = createRequire(import.meta.url).resolve('@sigx/lynx-dev-client/install');
+        }
+        catch {
+            devClientInstallPath = undefined;
+        }
+    }
+    if (devClientInstallPath) {
+        api.logger.info(`[sigx-lynx] device console log streaming → enabled`);
+    }
+    else {
+        api.logger.warn(`[sigx-lynx] device console log streaming → disabled (install @sigx/lynx-dev-client as a devDependency of this app). rootPath=${api.context.rootPath}, cwd=${process.cwd()}`);
+    }
+    api.modifyBundlerChain((chain, { environment, isProd }) => {
+        const isRspeedy = api.context.callerName === 'rspeedy';
+        if (!isRspeedy)
+            return;
+        const isDev = !isProd;
+        const isLynx = environment.name === 'lynx' || environment.name.startsWith('lynx-');
+        const isWeb = environment.name === 'web' || environment.name.startsWith('web-');
+        // HMR / Live Reload flags (same logic as vue-lynx / React plugin)
+        const { hmr, liveReload } = environment.config.dev ?? {};
+        const enabledHMR = isDev && !isWeb && hmr !== false;
+        const enabledLiveReload = isDev && !isWeb && liveReload !== false;
+        const entries = chain.entryPoints.entries() ?? {};
+        chain.entryPoints.clear();
+        // Collect all main-thread filenames to mark with lynx:main-thread
+        const mainThreadFilenames = [];
+        for (const [entryName, entryPoint] of Object.entries(entries)) {
+            // Collect user imports from the original entry
+            const imports = [];
+            const ep = entryPoint;
+            for (const val of ep.values()) {
+                if (typeof val === 'string') {
+                    imports.push(val);
+                }
+                else if (typeof val === 'object' && val !== null && 'import' in val) {
+                    const imp = val.import;
+                    if (Array.isArray(imp))
+                        imports.push(...imp);
+                    else if (imp)
+                        imports.push(imp);
+                }
+            }
+            // ----------------------------------------------------------------
+            // Filenames
+            // ----------------------------------------------------------------
+            const intermediate = isLynx ? DEFAULT_INTERMEDIATE : '';
+            const mainThreadEntry = `${entryName}__main-thread`;
+            const mainThreadName = path.posix.join(intermediate, `${entryName}/main-thread.js`);
+            const backgroundName = path.posix.join(intermediate, `${entryName}/background${isProd ? '.[contenthash:8]' : ''}.js`);
+            if (isLynx || isWeb) {
+                mainThreadFilenames.push(mainThreadName);
+            }
+            // ----------------------------------------------------------------
+            // Main Thread bundle – PAPI bootstrap only
+            // ----------------------------------------------------------------
+            // The MT entry ONLY imports @sigx/lynx-runtime-main, which registers
+            // globalThis.renderPage, processData, sigxPatchUpdate and bridges
+            // ops from the background thread.
+            //
+            // MT bundle evaluation order (critical):
+            //   The bootstrap (entry-main → worklet-runtime → install-hybrid-worklet)
+            //   is prepended to every user file by `worklet-loader-mt.ts` using
+            //   absolute paths resolved from the loader's install location. That
+            //   means we DON'T list those modules here as entry imports — the dep
+            //   graph that the loader-emitted preamble creates pulls them in, in
+            //   the right order, without forcing the user's app package.json to
+            //   declare @lynx-js/react as a direct dep.
+            //
+            //   So the MT entry list is just: user imports. (CSS HMR runtime in
+            //   dev mode only.) Worklet registrations land via the dep graph.
+            const mainThreadImports = !enabledHMR
+                ? [...imports]
+                : [
+                    '@lynx-js/css-extract-webpack-plugin/runtime/hotModuleReplacement.lepus.cjs',
+                    ...imports,
+                ];
+            chain
+                .entry(mainThreadEntry)
+                .add({
+                layer: LAYERS.MAIN_THREAD,
+                import: mainThreadImports,
+                filename: mainThreadName,
+            })
+                .end();
+            // ----------------------------------------------------------------
+            // Background bundle – sigx renderer + user app
+            // ----------------------------------------------------------------
+            const bgImports = [];
+            bgImports.push(...imports);
+            const bgEntry = chain
+                .entry(entryName)
+                .add({
+                layer: LAYERS.BACKGROUND,
+                import: bgImports,
+                filename: backgroundName,
+            });
+            // Inject standard rspack HMR client + Lynx WebSocket transport into
+            // the BG entry (matching vue-lynx's approach). These must be prepended
+            // so they initialise before user code.
+            if (enabledHMR) {
+                bgEntry.prepend({
+                    layer: LAYERS.BACKGROUND,
+                    import: '@rspack/core/hot/dev-server',
+                });
+                // BG → MT hot-update bridge. Subscribes to the same `webpackHotUpdate`
+                // emitter event as `@rspack/core/hot/dev-server`, fetches the matching
+                // `main__main-thread.<hash>.hot-update.js`, and forwards extracted
+                // `registerWorkletInternal` calls to MT via `callLepusMethod`. Without
+                // this, MT's `_workletMap` keeps the old worklet IDs from the static
+                // bundle while BG sends ops referencing new content-hash IDs after a
+                // save → bind-of-undefined on tap.
+                bgEntry.prepend({
+                    layer: LAYERS.BACKGROUND,
+                    import: '@sigx/lynx-runtime/mt-hmr-bridge',
+                });
+            }
+            if (enabledHMR || enabledLiveReload) {
+                bgEntry.prepend({
+                    layer: LAYERS.BACKGROUND,
+                    import: '@lynx-js/webpack-dev-transport/client',
+                });
+            }
+            // Auto-install the console log streamer in dev. Prepended LAST so
+            // it runs FIRST at runtime (after webpack-dev-transport so the
+            // dev URL is plumbed). Skipped if the dev-client package isn't
+            // installed in the consuming project.
+            if (isDev && !isWeb && devClientInstallPath) {
+                bgEntry.prepend({
+                    layer: LAYERS.BACKGROUND,
+                    import: devClientInstallPath,
+                });
+            }
+            bgEntry.end();
+            // ----------------------------------------------------------------
+            // LynxTemplatePlugin – packages both bundles into .lynx template
+            // ----------------------------------------------------------------
+            if ((isLynx || isWeb) && templateMod) {
+                {
+                    const { LynxTemplatePlugin } = templateMod;
+                    const templateFilename = (typeof environment.config.output.filename === 'object'
+                        ? environment.config.output.filename
+                            .bundle
+                        : environment.config.output.filename) ??
+                        '[name].[platform].bundle';
+                    chain
+                        .plugin(`${PLUGIN_TEMPLATE}-${entryName}`)
+                        .use(LynxTemplatePlugin, [
+                        {
+                            ...LynxTemplatePlugin.defaultOptions,
+                            dsl: 'react_nodiff',
+                            chunks: [mainThreadEntry, entryName],
+                            filename: templateFilename
+                                .replaceAll('[name]', entryName)
+                                .replaceAll('[platform]', environment.name),
+                            intermediate: path.posix.join(intermediate, entryName),
+                            debugInfoOutside: opts.debugInfoOutside ?? true,
+                            enableCSSSelector: opts.enableCSSSelector ?? true,
+                            enableCSSInvalidation: opts.enableCSSSelector ?? true,
+                            enableCSSInheritance: opts.enableCSSInheritance ?? false,
+                            customCSSInheritanceList: opts.customCSSInheritanceList,
+                            enableRemoveCSSScope: true,
+                            enableNewGesture: true,
+                            removeDescendantSelectorScope: true,
+                            cssPlugins: [],
+                        },
+                    ])
+                        .end();
+                }
+            }
+        }
+        // ------------------------------------------------------------------
+        // SigxMarkMainThreadPlugin – mark MT assets for LynxTemplatePlugin
+        // ------------------------------------------------------------------
+        if ((isLynx || isWeb) && mainThreadFilenames.length > 0) {
+            chain
+                .plugin(PLUGIN_MARK_MAIN_THREAD)
+                .use(SigxMarkMainThreadPlugin, [mainThreadFilenames])
+                .end();
+        }
+        // ------------------------------------------------------------------
+        // RuntimeWrapperWebpackPlugin – wrap BG bundle (NOT main-thread.js)
+        // in __init_card_bundle__(lynxCoreInject, lynx, ...). Inside the
+        // wrapper, lynx-runtime code can reference `lynx` and `lynxCoreInject`
+        // as bare identifiers, giving us the official BG → MT bridge and
+        // event dispatch hooks.
+        // ------------------------------------------------------------------
+        if (isLynx && wrapperMod) {
+            const { RuntimeWrapperWebpackPlugin } = wrapperMod;
+            chain
+                .plugin('lynx:sigx-runtime-wrapper')
+                .use(RuntimeWrapperWebpackPlugin, [
+                {
+                    // Wrap everything except main-thread.js (and main-thread.[hash].js).
+                    test: /^(?!.*main-thread(?:\.[A-Fa-f0-9]*)?\.js$).*\.js$/,
+                },
+            ])
+                .end();
+        }
+        // ------------------------------------------------------------------
+        // LynxEncodePlugin – binary-encode the .lynx template
+        // ------------------------------------------------------------------
+        if (isLynx && templateMod) {
+            const { LynxEncodePlugin } = templateMod;
+            chain
+                .plugin(PLUGIN_ENCODE)
+                .use(LynxEncodePlugin, [{}])
+                .end();
+        }
+        // ------------------------------------------------------------------
+        // HMR loader – inject registerHMRModule() + module.hot.accept()
+        // into component files on the BG layer so they self-accept hot
+        // updates and patch instances in-place (no structural tree ops).
+        // ------------------------------------------------------------------
+        if (enabledHMR) {
+            chain.module
+                .rule('sigx-hmr')
+                .test(/\.[jt]sx?$/)
+                .issuerLayer(LAYERS.BACKGROUND)
+                .exclude
+                .add(/node_modules/)
+                .add(/dist/)
+                .end()
+                .enforce('pre')
+                .use('sigx-hmr-loader')
+                .loader(path.resolve(_dirname, './loaders/hmr-loader'))
+                .end();
+        }
+        // ------------------------------------------------------------------
+        // Worklet loaders — both layers run @lynx-js/react/transform.
+        // BG layer: target='JS' replaces 'main thread' functions with
+        //           { _wkltId, _c? } placeholders shipped via SET_WORKLET_EVENT.
+        // MT layer: target='LEPUS' produces registerWorkletInternal(...) calls;
+        //           the loader extracts those + local-import edges.
+        //
+        // Rules run on every JS/TS file in their respective layer — no
+        // package allowlist and no `node_modules`/`dist` rule exclude. The
+        // loaders gate themselves on directive presence (cheap regex
+        // pre-filter, then SWC). The MT loader additionally branches on the
+        // file's path because rspack shares module identity across BG/MT
+        // layers — see the decision table in `worklet-loader-mt.ts` — so an
+        // MT-side body strip of a library file would wipe its named exports
+        // for BG consumers too. That MT-side preservation keeps
+        // `@sigx/lynx-runtime-main`'s MT globals (`processData`,
+        // `updateGlobalProps`, `sigxRunOnMT`) and lets cross-package
+        // consumers like `@sigx/lynx-daisyui` resolve named imports
+        // (`useTabs`, `useScreenChrome`) from worklet-shipping packages.
+        //
+        // The BG loader has no path branch; for directive-bearing files
+        // (user or library) it returns the JS-target transform output,
+        // which preserves exports while replacing worklet bodies with
+        // `{ _wkltId }` placeholders. New packages that ship `'main thread'`
+        // directives in their dist are picked up automatically — no
+        // manual opt-in.
+        chain.module
+            .rule('sigx-worklet')
+            .test(/\.[jt]sx?$/)
+            .issuerLayer(LAYERS.BACKGROUND)
+            .enforce('pre')
+            .use('sigx-worklet-loader')
+            .loader(path.resolve(_dirname, './loaders/worklet-loader'))
+            .end();
+        chain.module
+            .rule('sigx-worklet-mt')
+            .test(/\.[jt]sx?$/)
+            .issuerLayer(LAYERS.MAIN_THREAD)
+            .enforce('pre')
+            .use('sigx-worklet-mt-loader')
+            .loader(path.resolve(_dirname, './loaders/worklet-loader-mt'))
+            .end();
+        // Disable IIFE wrapping – Lynx handles module scoping itself
+        chain.output.set('iife', false);
+    });
+}

package/dist/icons.d.ts

@@ -5,7 +5,7 @@
  *
  * 1. Loads `signalx.config.ts` and reads the `iconSets: [...]` field.
  * 2. Statically scans every `.tsx` / `.jsx` / `.ts` / `.js` file under the
- *    project root for `<Icon set="…" name="…" />` usages.
+ *    project root for icon usages (see `scanContent` for the exact patterns).
  * 3. Dynamically imports each adapter package (e.g. `@sigx/lynx-icons-fa-free`)
  *    and resolves the used glyphs to `{ codepoint, svg }` records.
  * 4. Writes three generated files into `node_modules/.cache/sigx-lynx-icons/`
@@ -18,13 +18,33 @@
  *
  * The scanner is a one-shot regex pass at plugin start — adding a new icon
  * during `pnpm dev` requires a dev-server restart in v1. A real SWC-AST
- * Rspack loader is the planned upgrade.
+ * Rspack loader is the planned upgrade and would obviate the regex
+ * patterns by inspecting the JSX tree directly.
+ *
+ * **Patterns the scanner picks up (regex-based; not exhaustive):**
+ * - `<Icon set="X" name="Y" />` — both attribute orders
+ * - `<FaSolidIcon name="Y" />` / `<FaRegularIcon name="Y" />`
+ *   / `<FaBrandIcon name="Y" />` / `<LucideIcon name="Y" />` — pinned
+ *   components whose set id is hardcoded in their implementations. The
+ *   set id mapping is in `PINNED_COMPONENTS` below.
+ * - `{ set: 'X', name: 'Y' }` — `IconSpec` object literals anywhere
+ *   (prop value, const declaration, function argument). Both key orders.
+ *
+ * **What still needs `include: [...]` in signalx.config.ts:**
+ * - Dynamic names: `<Icon set="fas" name={someVar} />` or
+ *   `<FaSolidIcon name={someVar} />` — the scanner only matches literal
+ *   string attributes. JSON-driven UIs and runtime-computed icon names
+ *   need explicit force-includes (or `include: ['*']` for the whole catalog).
+ * - User-defined pinned components — only the four built-in adapter
+ *   pinned components are known to the scanner. A consumer who writes
+ *   their own `<MyIcon name="…">` wrapper needs `include`.
+ * - Spread props: `<Icon {...spec} />`. Niche; use `include` if needed.
  */
 import type { RsbuildPluginAPI } from '@rsbuild/core';
 /**
- * Extract `<Icon set="…" name="…" />` (and the name-first variant) usages
- * from a single source string. Exported for unit testing — the prod path
- * calls this once per file from {@link scanProject}.
+ * Extract icon usages from a single source string. See the file-level
+ * JSDoc for the complete pattern list. Exported for unit testing — the
+ * prod path calls this once per file from {@link scanProject}.
  */
 export declare function scanContent(content: string): Array<{
     set: string;