@sigx/lynx-plugin 0.4.1 → 0.4.3

package/README.md

@@ -11,10 +11,10 @@ npm install -D @sigx/lynx-plugin
 ```ts
 // rspeedy.config.ts (or rspack.config.ts)
 import { defineConfig } from '@lynx-js/rspeedy';
-import { sigxLynxPlugin } from '@sigx/lynx-plugin';
+import { pluginSigxLynx } from '@sigx/lynx-plugin';
 
 export default defineConfig({
-  plugins: [sigxLynxPlugin()],
+  plugins: [pluginSigxLynx()],
 });
 ```
 
@@ -37,7 +37,7 @@ export default defineConfig({
 
    Listing them as separate entries in webpack isn't sufficient because the chunk graph can evaluate user code before the bootstrap chain. Prepending side-effect imports per-file forces the dep-graph order.
 
-4. **Cross-package worklet pickup.** The worklet rules run on every JS/TS file in the BG / MT layers, including `node_modules` and pre-built `dist/`. The loaders use a cheap regex pre-filter to skip the SWC parse for files that obviously have no `'main thread'` directive (final correctness comes from SWC itself, not the regex). On the MT side, the loader also branches on the file's path: for files under `node_modules/` or `dist/` it preserves the original source — pass-through when no directive is present, source + appended `registerWorkletInternal(...)` calls when one is. That preservation matters because rspack shares module identity across the BG/MT layers, so stripping MT bodies would erase named exports for BG consumers too — daisyui couldn't resolve `useTabs` / `useScreenChrome` from `@sigx/lynx-navigation`, `@sigx/lynx-runtime-main`'s MT globals (`processData`, `updateGlobalProps`, `sigxRunOnMT`) would disappear, etc. The BG loader has no path branch; for any directive-bearing file (user or library) it returns the JS-target transform output, which preserves exports while replacing worklet bodies with `{ _wkltId }` placeholders. Net effect: any package shipping `'main thread'` directives in its dist (motion, navigation, gestures, future additions) is picked up automatically with no allowlist or opt-in flag.
+4. **Cross-package worklet pickup.** The worklet rules run on every JS/TS file in the BG / MT layers, including `node_modules` and pre-built `dist/`. Any package shipping `'main thread'` directives in its dist (`@sigx/lynx-motion`, `@sigx/lynx-navigation`, `@sigx/lynx-gestures`, future additions) is picked up automatically — no allowlist or opt-in flag. See [CONTRIBUTING.md](https://github.com/signalxjs/lynx/blob/main/CONTRIBUTING.md#lynx-plugin-internals-cross-package-worklet-pickup) for the loader-branching details.
 
 ## Worklet author quick reference
 
@@ -54,12 +54,12 @@ Mark an event handler as MT-thread by adding the directive as the first statemen
 
 The plugin handles the rest — the handler body lives in the MT bundle, the BG bundle keeps a `{_wkltId, _c}` placeholder, and Lynx native dispatches the touch event directly to the MT thread.
 
-For higher-level abstractions (drag, tap, swipe, animations), see [`@sigx/gestures`](../gestures).
+For higher-level abstractions (drag, tap, swipe, animations), see [`@sigx/lynx-gestures`](https://github.com/signalxjs/lynx/tree/main/packages/lynx-gestures).
 
 ## Limitations
 
 - **Custom worklet bodies require `'main thread'` directives.** Worklets aren't auto-detected from JSX shape; the directive is the marker.
-- **Variables declared inside a worklet body are MT-locals.** They can't cross the bridge via `runOnBackground` closure capture — pass them as arguments instead. See `@sigx/gestures` README, "Performance notes."
+- **Variables declared inside a worklet body are MT-locals.** They can't cross the bridge via `runOnBackground` closure capture — pass them as arguments instead. See `@sigx/lynx-gestures` README, "Performance notes."
 - **Mappers for `useAnimatedStyle` ship as MT-side code.** Custom mappers must be registered from a MT-side module via `registerMapper(name, fn)` — BG-side `useAnimatedStyle` only carries the *name* across the build pipeline.
 
 ## License

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;

package/dist/icons.js

@@ -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,7 +18,27 @@
  *
  * 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 { createRequire } from 'node:module';
 import { promises as fs, existsSync } from 'node:fs';
@@ -26,6 +46,39 @@ import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 const SCAN_REGEX_SET_FIRST = /<Icon\s+[^>]*?\bset\s*=\s*["']([\w-]+)["'][^>]*?\bname\s*=\s*["']([\w-]+)["']/g;
 const SCAN_REGEX_NAME_FIRST = /<Icon\s+[^>]*?\bname\s*=\s*["']([\w-]+)["'][^>]*?\bset\s*=\s*["']([\w-]+)["']/g;
+/**
+ * Known pinned per-set components exported by the workspace's adapter
+ * packages — `@sigx/lynx-icons-fa-free/components` and
+ * `@sigx/lynx-icons-lucide/components`. Each hardcodes its `set` id to
+ * the conventional value documented in the adapter's README; the
+ * scanner mirrors that mapping so `<FaSolidIcon name="user" />` is
+ * recognized as `set="fas", name="user"`.
+ *
+ * Consumers using non-conventional set ids in their config fall back
+ * to generic `<Icon>` (the pinned component wouldn't find its set at
+ * runtime either). New adapter packages adding pinned components add
+ * their entries here; the eventual SWC-AST loader replaces this with
+ * a per-package manifest.
+ */
+const PINNED_COMPONENTS = {
+    FaSolidIcon: 'fas',
+    FaRegularIcon: 'far',
+    FaBrandIcon: 'fab',
+    LucideIcon: 'lucide',
+};
+const PINNED_COMPONENT_NAMES = Object.keys(PINNED_COMPONENTS).join('|');
+const SCAN_REGEX_PINNED = new RegExp(`<(${PINNED_COMPONENT_NAMES})\\s+[^>]*?\\bname\\s*=\\s*["']([\\w-]+)["']`, 'g');
+/**
+ * `IconSpec` object literal matchers — `{ set: 'X', name: 'Y' }` in
+ * either key order. Used for `<Tabs.Screen icon={{…}}>`, `<NavHeader
+ * backIcon={{…}}>`, `const spec = {…}` const declarations, function
+ * arguments, etc. Word-boundary anchored on the *first* key to avoid
+ * matching mid-identifier (e.g. `someset:`). False positives — any
+ * code object with both `set` and `name` string-valued keys — are
+ * harmless: the extra glyph just ships in the bundle.
+ */
+const SCAN_REGEX_SPEC_SET_FIRST = /\bset\s*:\s*["']([\w-]+)["']\s*,\s*name\s*:\s*["']([\w-]+)["']/g;
+const SCAN_REGEX_SPEC_NAME_FIRST = /\bname\s*:\s*["']([\w-]+)["']\s*,\s*set\s*:\s*["']([\w-]+)["']/g;
 /** Directories to skip when walking the project. */
 const SKIP_DIRS = new Set(['node_modules', 'dist', 'ios', 'android', 'Pods', '.git', '.cache', '.rspeedy']);
 /** File extensions worth scanning. */
@@ -64,13 +117,23 @@ function addUsage(used, set, name) {
     bucket.add(name);
 }
 /**
- * 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 function scanContent(content) {
-    if (!content.includes('<Icon'))
+    // Fast-path skip: a file with none of these markers can't possibly
+    // contain an icon usage we'd match. `set:` covers both attribute and
+    // object-literal forms; the pinned-component prefixes are listed for
+    // the JSX form.
+    if (!content.includes('<Icon')
+        && !content.includes('<FaSolidIcon')
+        && !content.includes('<FaRegularIcon')
+        && !content.includes('<FaBrandIcon')
+        && !content.includes('<LucideIcon')
+        && !content.includes('set:')) {
         return [];
+    }
     const seen = new Set();
     const out = [];
     const push = (set, name) => {
@@ -80,10 +143,22 @@ export function scanContent(content) {
         seen.add(key);
         out.push({ set, name });
     };
+    // <Icon set="X" name="Y" /> — either attribute order.
     for (const m of content.matchAll(SCAN_REGEX_SET_FIRST))
         push(m[1], m[2]);
     for (const m of content.matchAll(SCAN_REGEX_NAME_FIRST))
         push(m[2], m[1]);
+    // <FaSolidIcon name="Y" /> etc. — set id resolved from PINNED_COMPONENTS.
+    for (const m of content.matchAll(SCAN_REGEX_PINNED)) {
+        const set = PINNED_COMPONENTS[m[1]];
+        if (set)
+            push(set, m[2]);
+    }
+    // { set: 'X', name: 'Y' } — IconSpec object literal, either key order.
+    for (const m of content.matchAll(SCAN_REGEX_SPEC_SET_FIRST))
+        push(m[1], m[2]);
+    for (const m of content.matchAll(SCAN_REGEX_SPEC_NAME_FIRST))
+        push(m[2], m[1]);
     return out;
 }
 async function scanProject(cwd) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigx/lynx-plugin",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Rspack/Rspeedy plugin for SignalX Lynx dual-thread rendering",
   "type": "module",
   "main": "./dist/index.js",
@@ -34,8 +34,8 @@
   },
   "dependencies": {
     "@lynx-js/react": "^0.121.0",
-    "ws": "^8.18.3",
-    "@sigx/lynx-runtime-internal": "0.4.1"
+    "ws": "^8.20.1",
+    "@sigx/lynx-runtime-internal": "0.4.3"
   },
   "peerDependencies": {
     "@rspack/core": ">=1.0.0",
@@ -44,8 +44,8 @@
     "@lynx-js/template-webpack-plugin": ">=0.1.0",
     "@lynx-js/runtime-wrapper-webpack-plugin": ">=0.1.0",
     "@lynx-js/webpack-dev-transport": ">=0.1.0",
-    "@sigx/lynx-cli": "^0.4.1",
-    "@sigx/lynx-icons": "^0.4.1"
+    "@sigx/lynx-cli": "^0.4.3",
+    "@sigx/lynx-icons": "^0.4.3"
   },
   "peerDependenciesMeta": {
     "@rspack/core": {
@@ -72,12 +72,12 @@
   },
   "devDependencies": {
     "@rsbuild/core": "^1.7.5",
-    "@types/node": "^25.7.0",
+    "@types/node": "^25.9.1",
     "@types/ws": "^8.5.13",
-    "@typescript/native-preview": "7.0.0-dev.20260511.1",
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
     "typescript": "^6.0.3",
-    "@sigx/lynx-icons": "0.4.1",
-    "@sigx/lynx-cli": "0.4.1"
+    "@sigx/lynx-icons": "0.4.3",
+    "@sigx/lynx-cli": "0.4.3"
   },
   "publishConfig": {
     "access": "public"