feat: emit debug metadata assets

.changeset/debug-metadata.md

@@ -0,0 +1,5 @@
+---
+'@lynx-js/template-webpack-plugin': patch
+---
+
+Introduce `LynxDebugMetadataPlugin` to emit debug-metadata assets.

.changeset/soft-pumas-push.md

@@ -0,0 +1,5 @@
+---
+"@lynx-js/react": patch
+---
+
+Add `nodeIndex` to generated FiberElement creation calls and expose React transform debug metadata as `uiSourceMapRecords`.

.changeset/ten-lions-accept.md

@@ -0,0 +1,6 @@
+---
+'@lynx-js/react-rsbuild-plugin': patch
+'@lynx-js/react-webpack-plugin': patch
+---
+
+Add `enableUiSourceMap` option to enable UI source map generation and debug-metadata asset emission.

.github/debug-metadata.instructions.md

@@ -0,0 +1,5 @@
+---
+applyTo: "packages/webpack/{react-webpack-plugin,template-webpack-plugin}/**/*"
+---
+
+Treat `debug-metadata.json` as the final unified debug asset, not as an early intermediate dump. Generate it only after every JS sourcemap that will be shipped or uploaded has already been finalized, including main-thread debug-info remapping and any late `processAssets` code transforms. When one template contains multiple runtimes, store JS sourcemaps as a `jsSourceMaps` collection rather than a single top-level map, and keep `sourceMapRelease` attached to each JS asset entry instead of the document root because Slardar matches sourcemaps per emitted JS file. Keep `uiSourceMap` and bytecode debug payloads as sibling debug documents inside the unified container instead of overloading the standard sourcemap top-level shape.

.github/react-transform.instructions.md

@@ -0,0 +1,10 @@
+---
+applyTo: "packages/react/transform/**/*"
+---
+
+When a crate exposes both core Rust structs and `napi` wrapper structs with the same semantic shape, keep internal transform pipelines and shared `Rc<RefCell<...>>` state on the core types and convert to the `napi` types only at the JS boundary. Do not mix `swc_plugin_*::napi::*` record types into internal plugin wiring such as `.with_*_records(...)`, or wasm builds can fail with mismatched type errors.
+When recording source locations from SWC spans, guard `SourceMap::lookup_char_pos` for synthetic spans such as `DUMMY_SP` (`span.lo == 0`). Compat and other transforms may synthesize JSX nodes with default spans, and wasm builds can surface panics from source map lookups on those spans as `RuntimeError: unreachable`.
+Expose recorded columns as 1-based values so `uiSourceMapRecords` can be fed directly into editor locations such as VS Code without an extra offset conversion.
+When compat wraps a component with a synthetic `<view>`, preserve the original component spans on the generated wrapper instead of using `DUMMY_SP` or `Default::default()`. Snapshot ui source map extraction reads `opening.span`, so preserved spans keep `uiSourceMapRecords` file, line, and column data intact.
+Keep `snapshot.filename` stable for snapshot hashing semantics, even when callers want absolute paths in exported debug metadata. If `uiSourceMapRecords.filename` needs to use the top-level transform filename, inject it at the `react/transform/src/lib.rs` boundary instead of changing the snapshot plugin's internal filename.
+If `swc_plugin_snapshot::JSXTransformer::new` gains a new constructor parameter, update every external callsite under `packages/react/transform/**` at the same time, including wrapper crates such as `swc-plugin-reactlynx`, not just the main `packages/react/transform/src/lib.rs` entrypoint.

.github/rspeedy-core.instructions.md

@@ -0,0 +1,5 @@
+---
+applyTo: "packages/rspeedy/core/test/**/*"
+---
+
+Some rspeedy core test fixtures intentionally keep git-tracked files under fixture `node_modules` directories. When cleaning caches or build outputs, avoid deleting tracked fixture files under `packages/rspeedy/core/test/**/node_modules`; only remove untracked/generated artifacts.

.github/webpack-node-index.instructions.md

@@ -0,0 +1,8 @@
+---
+applyTo: "packages/webpack/{react-webpack-plugin,template-webpack-plugin}/**/*"
+---
+
+When emitting React UI source map metadata during template generation, emit `debug-metadata.json` into the template plugin `intermediate` directory, not beside `template.js`. The file should keep the sourcemap payload under a top-level `uiSourceMap` field and place auxiliary data such as `templateDebug` and `git` under `meta`, instead of serializing raw `uiSourceMapRecords`.
+Keep UI source map generation opt-in behind `pluginReactLynx({ enableUiSourceMap: true })`. When the flag is off, do not collect `uiSourceMapRecords`, do not emit `debug-metadata.json`, and do not inject `debugMetadataUrl` into encode data.
+Collect `uiSourceMapRecords` from main-thread loader results by storing them on module `buildInfo`, then aggregate them per template entry group before emit. The emitted `uiSourceMap.sources` array should use project-root-relative POSIX paths, `uiSourceMap.mappings` should follow sourcemap-style source locations as `[sourceIndex, line, column]`, and `uiSourceMap.uiMaps` should be a parallel array where `uiMaps[i]` is the runtime `nodeIndex` for `mappings[i]`. Keep the emitted line and column values 0-based even if transform-time records are editor-friendly 1-based.
+If a webpack plugin emits extra intermediate assets during `beforeEncode` such as `debug-metadata.json`, register their asset names on `args.intermediateAssets` so `LynxEncodePlugin` / `WebEncodePlugin` can clean them with the rest of the intermediate encode artifacts after template generation.

examples/react-ui-sourcemap/lynx.config.ts

@@ -0,0 +1,214 @@
+import { execFileSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { pluginQRCode } from '@lynx-js/qrcode-rsbuild-plugin';
+import { pluginReactLynx } from '@lynx-js/react-rsbuild-plugin';
+import { defineConfig } from '@lynx-js/rspeedy';
+import type { RsbuildPlugin, Rspack } from '@lynx-js/rspeedy';
+import type { LynxTemplatePlugin } from '@lynx-js/template-webpack-plugin';
+
+const DEBUG_METADATA_ASSET = 'debug-metadata.json';
+const MOCK_UPLOAD_BASE_URL = 'https://mock-debug-metadata-upload.lynx.dev/';
+const projectRoot = path.dirname(fileURLToPath(import.meta.url));
+
+interface GitMetadata {
+  branch: string;
+  commit: string;
+  commitUrl: string | null;
+  remoteUrl: string | null;
+}
+
+function runGit(args: string[]): string | null {
+  try {
+    return execFileSync('git', args, {
+      cwd: projectRoot,
+      encoding: 'utf8',
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function normalizeRepositoryUrl(remoteUrl: string | null): string | null {
+  if (!remoteUrl) {
+    return null;
+  }
+
+  if (remoteUrl.startsWith('git@github.com:')) {
+    return `https://github.com/${
+      remoteUrl.slice('git@github.com:'.length).replace(/\.git$/, '')
+    }`;
+  }
+
+  if (remoteUrl.startsWith('https://github.com/')) {
+    return remoteUrl.replace(/\.git$/, '');
+  }
+
+  return remoteUrl;
+}
+
+function getGitMetadata(): GitMetadata {
+  const commit = runGit(['rev-parse', 'HEAD']) ?? 'unknown';
+  const branch = runGit(['rev-parse', '--abbrev-ref', 'HEAD']) ?? 'unknown';
+  const remoteUrl = normalizeRepositoryUrl(
+    runGit(['config', '--get', 'remote.origin.url']),
+  );
+
+  return {
+    branch,
+    commit,
+    remoteUrl,
+    commitUrl: remoteUrl ? `${remoteUrl}/commit/${commit}` : null,
+  };
+}
+
+function mockUploadDebugMetadata(
+  filenameTemplate: string,
+  intermediate: string,
+): string {
+  const normalizedTemplate = filenameTemplate.replaceAll(
+    path.win32.sep,
+    path.posix.sep,
+  );
+  const normalizedIntermediate = intermediate.replaceAll(
+    path.win32.sep,
+    path.posix.sep,
+  );
+  const assetPath = path.posix.join(
+    normalizedIntermediate.replace(/^\.\//, ''),
+    DEBUG_METADATA_ASSET,
+  );
+
+  return new URL(
+    `${assetPath}?template=${encodeURIComponent(normalizedTemplate)}`,
+    MOCK_UPLOAD_BASE_URL,
+  ).toString();
+}
+
+function pluginMockDebugMetadataUpload(): RsbuildPlugin {
+  return {
+    name: 'example:mock-debug-metadata-upload',
+    setup(api) {
+      const git = getGitMetadata();
+
+      api.modifyBundlerChain(chain => {
+        const exposed = api.useExposed<
+          { LynxTemplatePlugin: typeof LynxTemplatePlugin }
+        >(Symbol.for('LynxTemplatePlugin'));
+
+        if (!exposed) {
+          throw new Error(
+            '[example:mock-debug-metadata-upload] Missing exposed LynxTemplatePlugin',
+          );
+        }
+
+        chain.plugin('example:mock-debug-metadata-upload').use({
+          apply(compiler) {
+            compiler.hooks.thisCompilation.tap(
+              'example:mock-debug-metadata-upload',
+              compilation => {
+                const hooks = exposed.LynxTemplatePlugin
+                  .getLynxTemplatePluginHooks(
+                    compilation as unknown as Parameters<
+                      typeof LynxTemplatePlugin.getLynxTemplatePluginHooks
+                    >[0],
+                  );
+
+                hooks.beforeEncode.tapPromise(
+                  {
+                    name: 'example:mock-debug-metadata-upload',
+                    stage: 1000,
+                  },
+                  async args => {
+                    const assetName = path.posix.format({
+                      dir: args.intermediate,
+                      base: DEBUG_METADATA_ASSET,
+                    });
+                    const debugMetadataAsset = compilation.getAsset(assetName);
+
+                    if (debugMetadataAsset) {
+                      const currentContent = debugMetadataAsset.source
+                        .source()
+                        .toString();
+                      const debugMetadata = JSON.parse(
+                        currentContent,
+                      ) as Record<
+                        string,
+                        unknown
+                      >;
+                      const currentMeta =
+                        typeof debugMetadata['meta'] === 'object'
+                          && debugMetadata['meta'] !== null
+                          ? debugMetadata['meta'] as Record<string, unknown>
+                          : {};
+
+                      compilation.updateAsset(
+                        assetName,
+                        new compiler.webpack.sources.RawSource(
+                          JSON.stringify(
+                            {
+                              ...debugMetadata,
+                              meta: {
+                                ...currentMeta,
+                                git,
+                              },
+                            },
+                            null,
+                            2,
+                          ),
+                        ),
+                      );
+                    }
+
+                    const debugMetadataUrl = await Promise.resolve(
+                      mockUploadDebugMetadata(
+                        args.filenameTemplate,
+                        args.intermediate,
+                      ),
+                    );
+
+                    args.encodeData.sourceContent.config = {
+                      ...args.encodeData.sourceContent.config,
+                      debugMetadataUrl,
+                    };
+
+                    return args;
+                  },
+                );
+              },
+            );
+          },
+        } as Rspack.RspackPluginInstance);
+      });
+    },
+  };
+}
+
+export default defineConfig({
+  source: {
+    entry: {
+      main: path.join(projectRoot, 'src/index.tsx'),
+    },
+  },
+  output: {
+    distPath: {
+      root: path.join(projectRoot, 'dist'),
+    },
+  },
+  plugins: [
+    pluginReactLynx({
+      enableUiSourceMap: true,
+    }),
+    pluginMockDebugMetadataUpload(),
+    pluginQRCode({
+      schema(url) {
+        return `${url}?fullscreen=true`;
+      },
+    }),
+  ],
+  environments: {
+    web: {},
+    lynx: {},
+  },
+});

examples/react-ui-sourcemap/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@lynx-js/example-react-ui-sourcemap",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "rspeedy build",
+    "dev": "rspeedy dev"
+  },
+  "dependencies": {
+    "@lynx-js/react": "workspace:*"
+  },
+  "devDependencies": {
+    "@lynx-js/preact-devtools": "^5.0.1",
+    "@lynx-js/qrcode-rsbuild-plugin": "workspace:*",
+    "@lynx-js/react-rsbuild-plugin": "workspace:*",
+    "@lynx-js/rspeedy": "workspace:*",
+    "@lynx-js/template-webpack-plugin": "workspace:*",
+    "@lynx-js/types": "3.7.0",
+    "@types/react": "^18.3.28"
+  }
+}

examples/react-ui-sourcemap/src/App.css

@@ -0,0 +1,66 @@
+.Screen {
+  min-height: 100%;
+  padding: 32px 24px;
+  background: linear-gradient(180deg, #0c1222 0%, #172544 100%);
+}
+
+.Hero {
+  margin-bottom: 24px;
+}
+
+.Eyebrow {
+  margin-bottom: 8px;
+  color: #89b4ff;
+  font-size: 24px;
+}
+
+.Title {
+  margin-bottom: 12px;
+  color: #ffffff;
+  font-size: 42px;
+  font-weight: 700;
+}
+
+.Description {
+  color: rgba(255, 255, 255, 0.82);
+  font-size: 26px;
+  line-height: 36px;
+}
+
+.Button {
+  margin-bottom: 24px;
+  padding: 20px 24px;
+  border-radius: 999px;
+  background-color: #7ee787;
+}
+
+.ButtonLabel {
+  color: #08210d;
+  font-size: 24px;
+  font-weight: 600;
+}
+
+.Hint {
+  color: rgba(255, 255, 255, 0.7);
+  font-size: 24px;
+  line-height: 34px;
+}
+
+.Card {
+  padding: 24px;
+  border-radius: 24px;
+  background-color: rgba(255, 255, 255, 0.12);
+}
+
+.CardTitle {
+  margin-bottom: 12px;
+  color: #ffffff;
+  font-size: 30px;
+  font-weight: 600;
+}
+
+.CardBody {
+  color: rgba(255, 255, 255, 0.78);
+  font-size: 24px;
+  line-height: 34px;
+}