Latest Results
feat(debug-metadata): add UI sourcemap remap CLI and API (#2744)
## Summary
- Adds a `remap` CLI to `@lynx-js/debug-metadata`: `npx
@lynx-js/debug-metadata remap --ui input.json [--output out.json]`. It
reverse-resolves a Lynx UI node tree dumped by the engine — each node
carrying a `nodeIndex` and a `debugMetadataUrl` is annotated with its
source location (`repo`, `source`, `line`, `column`) read from the
embedded `uiSourceMap`; every other field, and any node that can't be
resolved, passes through unchanged.
- Exposes the same logic as an API (`remapUiTree`, plus
`buildUiSourceMapLookup` / `normalizeRepo` helpers). Input type `UiNode`
requires `nodeIndex` + `debugMetadataUrl` so API callers get a compile
error if they omit them; the output type `RemappedUiNode` adds the
optional location fields.
- Validates at trust boundaries: `assertUiNode` checks the parsed input
tree (located errors like `$.children[1]: "nodeIndex" must be a
number`), and `isUiSourceMapData` guards the loaded
`debug-metadata.json` so an old/wrong-format file fails with a clear
message instead of crashing.
- Wires up api-extractor for the package (new `api-extractor.json` +
report under `etc/`).
`line` and `column` are 1-based, matching the generator in
`swc_plugin_snapshot` (`loc.line`, `loc.col + 1`).
## Test plan
- [ ] `turbo api-extractor -- --local` produces no `etc/*.api.md` diff
- [ ] `pnpm changeset status` shows `@lynx-js/debug-metadata` bumping
minor
- [ ] `vitest run` — 19 tests in `ui-remap.test.ts` (lookup,
normalizeRepo, tree passthrough, caching, malformed-metadata guard,
assertUiNode)
- [ ] dprint check passes
- [ ] Manual: `remap --ui` on a dump with embedded `uiSourceMap`
annotates resolvable nodes; malformed input errors with a located
message
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added a remap CLI to reverse-resolve Lynx UI node trees and a
remapUiTree API that annotates nodes with repo/source/line/column when
available.
* Exports helpers for validation, source-map lookup, and repo
normalization.
* **Documentation**
* README updated with CLI/API usage, accepted input shapes, URL/path
handling, and memoization behavior.
* **Package**
* Package now declares a CLI executable and API extractor/report
artifacts.
* **Tests**
* Added tests covering remapping, lookup, normalization, caching, and
validation.
<!-- review_stack_entry_start -->
[](https://app.coderabbit.ai/change-stack/lynx-family/lynx-stack/pull/2744?utm_source=github_walkthrough&utm_medium=github&utm_campaign=change_stack)
<!-- review_stack_entry_end -->
<!-- end of auto-generated comment: release notes by coderabbit.ai --> Latest Branches
0%
hw/codex/midscene-android-ui-judge -15%
PupilTong:hw/codex/a2ui-docs -15%
PupilTong:hw/codex/fix-shadowroot-font-face © 2026 CodSpeed Technology