refactor: move the debug metadata plugin into @lynx-js/rsbuild-plugin - #3596

Part of the series that moves the Lynx build engine out of
`@lynx-js/rspeedy` and into `pluginLynx`.

The point of the series is that an Rsbuild build with only
`pluginReactLynx()` produces the same bundle as an Rspeedy build. This
locks that in: the same fixture is built both ways, each in its own
process, in production and in development, and the two bundles are
compared.

The comparison ignores identifiers minted per build rather than derived
from the source. `chunk.hash` is not reproducible across builds, and
both the content hash in a filename and the debug metadata release are
keyed on it, so the filename hash is turned off and the release is
stripped.

That reproducibility problem is not ours: swc's `inline_globals` keeps
the span of the value it substitutes for a define, and those values come
from a process-wide cache, so their spans belong to a `SourceMap` from
an earlier call. The module's source map therefore moves between builds,
which moves `build_info.hash`, `chunk.hash` and the content hash. Fix
proposed upstream in swc-project/swc#12129; with it, 40 Rspeedy builds
of the same source produce one bundle instead of ten. Once that lands
the two allowances in this test can go away.

Stacked on #3596.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Tests**
* Added coverage to verify that development and production bundles
generated by Rsbuild and Rspeedy remain equivalent.
* Normalized build-specific metadata during comparisons for reliable
results.
  * Isolated builds and cleaned up temporary output after testing.

* **Chores**
* Added a parity build utility using consistent React, environment,
output, and deterministic build settings.
  * Documented the parity coverage in the upcoming patch release notes.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

This PR was opened by the [Changesets
release](https://github.com/changesets/action) GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to main, this PR will
be updated.


# Releases
## @lynx-js/react@0.125.0

### Minor Changes

- Add the `<background-only>` element, which renders its `fallback` on
the main thread first screen and its children on the background thread.
([#3551](#3551))

### Patch Changes

- Tag main-thread vnodes with `$$typeof: Symbol.for('react.element')` so
`isValidElement` recognizes them, matching the background thread.
([#3514](#3514))

- Release worklet refs when list items are logically removed while
preserving native element recycling.
([#3590](#3590))
## @lynx-js/web-core@0.25.0

### Minor Changes

- Support `lynx.createIntersectionObserver` in Lynx for Web.
([#3383](#3383))

- Load a hand-written Lynx XML markup card in the browser, by compiling
it into a ([#3404](#3404))
  `.web.bundle` there and then loading that.

A markup card is not a kind of artifact. The decode worker already
dispatches on
the eight header bytes it reads - `{` for a `.json` template, the magic
header for
a bundle - and a markup card is what neither of those claims, so it
costs the two
shapes that stream nothing to reach. From there it is handed to
`encodeLynxXML`,
the same function `@lynx-js/web-core/encode` gives a build, which
returns real
bundle bytes: magic header, version, and the five sections in the
encoder's order.
Those bytes go straight back to `handleStream`, so every section is read
by the
reader that already existed. There is no markup decoding anywhere - not
in the
worker, not on the main thread - and a markup card is not merely
equivalent to a
  built card, it _is_ one by the time anything decodes it.

Compiling in the browser is what #3589 made possible: `binary/encode`'s
glue used
  to load its wasm through `node:fs`, and is now generated with
`wasm-bindgen --target bundler`, which a bundler resolves on either
platform.

  **What this costs, measured**

Both sides rebuilt from source - `npm run build:wasm` then `rsbuild
build`, with
`--force` so neither figure is a cache replay - because `binary/` is
gitignored
and survives `git switch`, which has produced wrong numbers here before.
Raw /
  `gzip -9`.

| artifact | `origin/main` | this change | delta |
| ----------------------------------- | ---------------- |
---------------- | ------------- |
| `binary/client/client_bg.wasm` | 227,536 / 82,883 | _byte-identical_ |
0 |
| `binary/client_legacy/…_bg.wasm` | 183,444 / 74,949 | _byte-identical_
| 0 |
| eager `client.js` | 45,287 / 14,388 | _byte-identical_ | 0 |
| `web-core-main-chunk.js` | 159,621 / 33,074 | _byte-identical_ | 0 |
| `web-core-worker-chunk.js` | 15,135 / 6,001 | _byte-identical_ | 0 |
| worker chunk (`…-loader-thread.js`) | 33,257 / 9,912 | 34,755 / 10,357
| +1,498 / +445 |
| `web-core-markup-encoder.js` (new) | – | 227,811 / 64,809 | new, lazy
|
| encode wasm asset (new) | – | 167,689 / 55,689 | new, lazy |

So a card that was built ahead of time pays **+1,498 B raw / +445 B
gzip**, all of
it in the worker chunk, and nothing at all in the eager entry or the
main chunk.
The four byte-identical rows are sha256 comparisons, not size
comparisons.

The laziness is load bearing rather than tidy: `TemplateManager`
requests the
worker with `webpackPrefetch`, `webpackPreload` and `fetchPriority:
"high"`, so a
static import would eagerly fetch all 395 kB for _every_ card. Verified
positively
and with a negative control on `origin/main`, counting occurrences (a
minified
  chunk is one line, so a line count cannot tell 1 from 60):

| marker | eager `client.js` | worker chunk | main chunk | markup chunk
|
| ---------------------------- | ----------------- | ------------ |
---------- | ------------ |
| encode wasm asset name | 0 | 0 | 0 | 1 |
| `css-tree` token names | 0 / 0 | 0 / 0 | 0 / 0 | 2 / 2 |
| the XML parser's own message | 0 | 0 | 0 | 2 |

All of these are 0 everywhere on `origin/main`, including in the chunk
that does
not exist there. `encode_legacy_json_generated_raw_style_info` reads 2
in the
eager entry and 3 in the worker chunk on **both** sides - it is the
_client_ wasm's
own export, used by `cssLoader` for `.json` artifacts, and is not this
change.

Compiling itself is work that moved from a build into the browser,
medians of 41
interleaved rounds: a 72 B stylesheet takes 0.42 ms, 872 B takes 0.89
ms, 9.1 kB
  takes 7.4 ms and 26 kB takes 23.5 ms. Only markup cards pay it.

  **Reviewer decisions this change deliberately leaves open**

- **`encodeLynxXML` warns on the console unconditionally, and now does
so at
runtime.** It reports each at-rule the Lynx style format cannot carry.
That was
written when the only caller was a build, which has no production
runtime to
stay quiet for; the same code now runs in a browser. It is left exactly
as it is
on `origin/main` so that `ts/encode/` keeps a zero diff, but gating it
on a dev
build, or deduplicating it per at-rule name, are both reasonable and
neither is
    done here.
- **The published tarball grows by 397 kB**, being the new markup chunk
plus the
encode wasm, which rspack now also emits under
`dist/client_prod/static/wasm/`.
That wasm is consequently present three times in the package - there,
under
`dist/encode_prod/static/wasm/` since #3589, and under `binary/encode/`.
Nothing
here makes that worse than the pattern already in place for the client
wasm, and
reclaiming it is a `files` change that would alter what deep importers
can
    reach, so it is left out of this change.
- **If #3390 lands first, the two chunk figures above need
re-measuring.** It
    reaches `css-tree` directly where this change reaches it through
`@lynx-js/css-serializer`; the spec resolves to a single
`css-tree@3.2.1`, so
rspack would either duplicate it into both lazy chunks or hoist it into
a shared
one. Nobody has built the union yet, so no combined figure is quoted
here.

  **Other limits worth knowing**

- `@lynx-js/css-serializer` becomes a real `dependency` rather than the
optional
peer it was. `dist/client` ships as unbundled ESM, so the `import` the
compiler
chunk performs is resolved by the consumer, and an optional peer nobody
installs
would make a markup card fail to load in exactly the packaging that
looks fine
    on disk.
- **A corrupted bundle now reaches the markup path**, because markup is
what is
left when a response is neither a bundle nor JSON. Handing those bytes
to the XML
parser would answer `expected '<lynx version="...">' root element`,
which points
the reader at a markup bug in a file that is not markup, so the two are
told
apart first - before the compiler chunk is even fetched - on whether the
content
begins a tag at all. Bytes that do not keep the diagnosis they always
had,
`Invalid Magic Header`, now carrying the eight header bytes that failed
to match;
a document that does gets the XML parser's own message and offset. A
response
shorter than 8 bytes is still rejected by the header read, exactly as
before.
- `@media`, `@supports` and `@layer` are dropped, as they already were
when
building a markup card into a bundle: Lynx's style format has no rule
kind for a
conditional group, so they are not Lynx features on any platform. Same
for
    `@import` with a URL.
- The `handleMarkup` recursion is one level deep and cannot loop:
`encode` writes
the magic header at offset 0 unconditionally, so the second
`handleStream` takes
the binary branch. Were that untrue, the bytes would fail the "begins a
tag"
check and the recursion would end in a thrown error rather than a cycle.

### Patch Changes

- Build `binary/encode` with `wasm-bindgen --target bundler` and publish
`@lynx-js/web-core/encode` as an rslib bundle, so one set of artifacts
serves both Node and the browser.
([#3589](#3589))

  **Why**

`binary/encode` used to be generated with `--target
experimental-nodejs-module`, whose glue calls `readFileSync('node:fs')`
at module scope. That made `@lynx-js/web-core/encode` importable from
Node only. The `bundler` target instead emits an "async wasm module"
glue (`import * as wasm from './encode_bg.wasm'`), which a bundler can
resolve for either platform.

  **What changed in the published package**

- `./encode` now resolves to `dist/encode_prod/index.js` (bundled by
rslib, like `./server` already was) instead of the unbundled
`dist/encode/index.js` emitted by `tsc`. The wasm is emitted as a build
asset under `dist/encode_prod/static/wasm/`.
- Bundling is what keeps the import clean: consuming the `bundler` glue
directly from Node would work only on Node 22 or newer, and would print
`ExperimentalWarning: Importing WebAssembly module instances` on every
build. Letting rslib resolve the wasm at web-core build time avoids
both.
- `encode_bg.wasm` is byte-for-byte unchanged; only the JavaScript glue
differs. The `binary/encode/*.d.ts` type declarations are identical
under both targets.

  **Compatibility**

- No API change. `encode()` and `encodeCSS(cssMap): Uint8Array` keep
their synchronous signatures. The wasm initialization becomes a single
module-level `await` inside the bundle, which is already accommodated by
the `await import('@lynx-js/web-core/encode')` that consumers use.
Encoded output is byte-identical to the previous release.
- `@lynx-js/css-serializer` stays an external dependency of the bundle
and is not inlined.
- Note on Node versions: `@lynx-js/web-core/encode` does not work on
Node 20 and did not work there before this change either. The `encode`
wasm is optimized with `wasm-opt --all-features`, and Node 20's engine
rejects it with `CompileError: Unknown heap type -14` regardless of
which glue is used. This is a pre-existing limitation that this change
neither introduces nor fixes; the effective floor for this entry point
is Node 22.
- The tarball grows by roughly the size of the encode wasm, because
`binary/encode/encode_bg.wasm` is still shipped alongside the copy that
rslib emits into `dist/encode_prod/`.
- Prevent event dispatch failures from escaping through the WebAssembly
boundary. ([#3356](#3356))
- Updated dependencies
[[`9c2be3e`](9c2be3e),
[`d671851`](d671851),
[`d671851`](d671851)]:
  - @lynx-js/css-serializer@0.1.9
  - @lynx-js/web-elements@0.12.9
  - @lynx-js/web-worker-rpc@0.25.0
## @lynx-js/genui@0.3.1

### Patch Changes

- Make A2UI image prompt guidance provider-neutral so host agents can
generate ([#3537](#3537))
  image assets through their configured tools.
- Updated dependencies
[[`d8f80cd`](d8f80cd)]:
  - @lynx-js/react-signals@0.0.2
## @lynx-js/react-signals@0.0.2

### Patch Changes

- Widen the `@lynx-js/react` peer dependency range to include 0.125.
([#3551](#3551))
## @lynx-js/rspeedy@0.16.5

### Patch Changes

- Move the debug metadata plugin from `@lynx-js/rspeedy` into
`pluginLynx`.
([#3596](#3596))

- Move `pluginDev` into `pluginLynx()`.
([#3364](#3364))

- Move the cssnano-based CSS minimizer into `pluginLynx()`.
([#3364](#3364))

- Move the `tools.htmlPlugin` default into `pluginLynx()`.
([#3364](#3364))

- Move the `output.legalComments` default into `pluginLynx()`.
([#3364](#3364))

- Read the bundle filename from the Rsbuild config instead of the
Rspeedy API.
([#3570](#3570))
- Updated dependencies
[[`99ed745`](99ed745),
[`0d10b79`](0d10b79),
[`0d10b79`](0d10b79),
[`0d10b79`](0d10b79),
[`0d10b79`](0d10b79),
[`92b54ed`](92b54ed),
[`37497d5`](37497d5)]:
  - @lynx-js/rsbuild-plugin@0.0.3
## @lynx-js/lynx-bundle-rslib-config@0.7.1

### Patch Changes

- Updated dependencies
[[`9c2be3e`](9c2be3e),
[`cf98e14`](cf98e14),
[`3bf135c`](3bf135c),
[`ae25e93`](ae25e93),
[`9c2be3e`](9c2be3e)]:
  - @lynx-js/css-serializer@0.1.9
  - @lynx-js/web-core@0.25.0
## @lynx-js/rsbuild-plugin@0.0.3

### Patch Changes

- Move the debug metadata plugin from `@lynx-js/rspeedy` into
`pluginLynx`.
([#3596](#3596))

- Move `pluginDev` into `pluginLynx()`.
([#3364](#3364))

- Move the cssnano-based CSS minimizer into `pluginLynx()`.
([#3364](#3364))

- Move the `tools.htmlPlugin` default into `pluginLynx()`.
([#3364](#3364))

- Move the `output.legalComments` default into `pluginLynx()`.
([#3364](#3364))

- Add `PLUGIN_LYNX_NAME` so plugins can tell whether `pluginLynx` is
applied. ([#3576](#3576))

- Alias `@rspack/core/hot/log.js` and
`@rspack/core/hot/log-apply-result.js`, which
`@lynx-js/webpack-dev-transport` imports without declaring
`@rspack/core`. Development builds failed to resolve them on any package
manager that does not hoist `@rspack/core`, such as npm and Yarn.
([#3577](#3577))
- Updated dependencies []:
  - @lynx-js/web-rsbuild-server-middleware@0.25.0
## @lynx-js/react-rsbuild-plugin@0.19.1

### Patch Changes

- Apply the Lynx build engine automatically when it is not already
applied, so `pluginReactLynx` works with plain Rsbuild.
([#3578](#3578))

- Read the bundle filename from the Rsbuild config instead of the
Rspeedy API.
([#3570](#3570))

- Emit the Lynx template for callers other than `rslib` and `rstest`.
([#3572](#3572))

- Widen the `@lynx-js/react` peer dependency range to include 0.125.
([#3551](#3551))
- Updated dependencies
[[`1d08862`](1d08862),
[`99ed745`](99ed745),
[`0d10b79`](0d10b79),
[`0d10b79`](0d10b79),
[`0d10b79`](0d10b79),
[`0d10b79`](0d10b79),
[`92b54ed`](92b54ed),
[`37497d5`](37497d5)]:
  - @lynx-js/react-webpack-plugin@0.11.1
  - @lynx-js/rsbuild-plugin@0.0.3
  - @lynx-js/react-alias-rsbuild-plugin@0.19.1
  - @lynx-js/use-sync-external-store@1.5.0
  - @lynx-js/react-refresh-webpack-plugin@0.4.2
  - @lynx-js/css-extract-webpack-plugin@0.10.1
  - @lynx-js/template-webpack-plugin@0.15.2
## @lynx-js/vanilla-rsbuild-plugin@0.0.2

### Patch Changes

- Updated dependencies []:
  - @lynx-js/template-webpack-plugin@0.15.2
## @lynx-js/css-serializer@0.1.9

### Patch Changes

- Point `@lynx-js/source-field` at `src/index.ts`, so a bundler in this
repo can ([#3404](#3404))
  resolve the package without waiting for its `dist/`.

`@lynx-js/css-serializer` has no `build` script - its `dist/` is emitted
by the
repository's root `tsc --build`, which is a separate turbo task with no
ordering
relationship to any package's `build`. That was invisible while every
consumer
was itself type-checked rather than bundled, but `@lynx-js/web-core`
bundles its
client with rspack, and rspack resolving `main: dist/index.js` before
the root
  build has emitted it fails outright.

`@rsbuild/plugin-source-build` is already how this repository answers
that -
`@lynx-js/web-elements` and `@lynx-js/web-worker-rpc` declare the same
field and
are consumed straight from source. Declaring it here removes the
ordering
  question rather than scheduling around it.

The field is inert outside such a build: it is a plain, unknown
top-level
`package.json` key, so no `exports` map is introduced and no existing
entry point
  or deep import changes.
## @lynx-js/web-elements@0.12.9

### Patch Changes

- Clamp the `setFoldExpanded` offset of `<x-foldview-ng>` to the
scrollable length.
([#3290](#3290))

`setFoldExpanded` called the native `scrollTo`, bypassing the clamping
done by the
`scrollTop` setter. A page collapsing its header with a deliberately
large offset
(e.g. `offset: '99999px'`) scrolled past the end, which does not happen
on native.
- Give `<x-foldview-header-ng>` a `width: 100%`.
([#3290](#3290))

The element is laid out with `position: absolute` but had no width, so
it shrank to
  fit its content instead of filling the foldview.
## @lynx-js/react-webpack-plugin@0.11.1

### Patch Changes

- Collect element templates from the background build as well, so a
template the main-thread bundle does not reach is still registered for
it. ([#3563](#3563))
## @lynx-js/template-webpack-plugin@0.15.2

### Patch Changes

- Updated dependencies
[[`9c2be3e`](9c2be3e),
[`cf98e14`](cf98e14),
[`3bf135c`](3bf135c),
[`ae25e93`](ae25e93),
[`9c2be3e`](9c2be3e)]:
  - @lynx-js/css-serializer@0.1.9
  - @lynx-js/web-core@0.25.0
## @lynx-js/react-umd@0.125.0


## create-rspeedy@0.16.5


## @lynx-js/react-alias-rsbuild-plugin@0.19.1


## upgrade-rspeedy@0.16.5


## @lynx-js/web-rsbuild-server-middleware@0.25.0


## @lynx-js/web-worker-rpc@0.25.0

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Since #3596, `pluginLynx` registers `pluginLynxDebugMetadata`, but the
README and TSDoc still said Rspeedy core auto-registers it. They now say
`pluginLynx` registers it, which environments get `debug-metadata.json`,
and that a plugin driving `LynxTemplatePlugin` without the exposure is
skipped rather than failing. No runtime change.

## Checklist

<!--- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).
- [x] Changeset added, and when a BREAKING CHANGE occurs, it needs to be
clearly marked (or not required).


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Clarified that debug metadata is registered through `pluginLynx` and
related DSL plugins.
- Documented when `debug-metadata.json` is emitted, including Lynx
template builds, local production builds, and `DEBUG` settings.
- Updated guidance for custom integrations that use the template plugin
without `pluginLynx`.
- Added documentation for the `DEBUG_METADATA_ASSET_NAME` and
`rewriteSourceMappingURLs` exports.
- Updated README and API documentation to reflect the current behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

…y#3959)

Since lynx-family#3596, `pluginLynx` registers `pluginLynxDebugMetadata`, but the
README and TSDoc still said Rspeedy core auto-registers it. They now say
`pluginLynx` registers it, which environments get `debug-metadata.json`,
and that a plugin driving `LynxTemplatePlugin` without the exposure is
skipped rather than failing. No runtime change.

## Checklist

<!--- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).
- [x] Changeset added, and when a BREAKING CHANGE occurs, it needs to be
clearly marked (or not required).


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **Documentation**
- Clarified that debug metadata is registered through `pluginLynx` and
related DSL plugins.
- Documented when `debug-metadata.json` is emitted, including Lynx
template builds, local production builds, and `DEBUG` settings.
- Updated guidance for custom integrations that use the template plugin
without `pluginLynx`.
- Added documentation for the `DEBUG_METADATA_ASSET_NAME` and
`rewriteSourceMappingURLs` exports.
- Updated README and API documentation to reflect the current behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->