uxml-preview 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,147 @@
 # Changelog
 
+## 0.4.0 — 2026-08-12
+
+### Added
+
+- The Unity golden dumper can run from the command line, records the Unity
+  revision, editor scale, accessible font settings, and timestamp beside each
+  measurement, rejects `-nographics` and `-quit` up front, and exits non-zero
+  unless it writes exactly one JSON file per discovered case.
+
+### Changed
+
+- Relative `@import` requests are deduplicated by `(url, from)`, matching Unity's
+  parent-relative loading. Root-fixed imports (`project://…` or a path beginning
+  with `/`) are globally deduplicated, and nested `<Style>` attachments now keep
+  their Unity subtree scope. The rule comes from five Unity measurement cases,
+  including the otherwise surprising split between `Packages/...` (relative)
+  and `/Packages/...` (root-fixed).
+
+- **Issue #1: `resolveImport` now receives a second argument,
+  `from: string | null`** —
+  the URL of the stylesheet containing the import being resolved, `null` for
+  a `<Style src="…">` reference. Without it, a relative `@import` inside an
+  imported sheet was unresolvable in principle: `a.uss` importing `"b.uss"`
+  means a path relative to `a.uss`, and the host had no way to learn `a.uss`'s
+  own URL at the point it resolved `b.uss`. `from` is always the exact string
+  this hook received as `url` for the containing sheet, never reconstructed —
+  matters most for nested imports, where it is the immediate parent, not the
+  original sheet. **Non-breaking**: existing one-argument callbacks keep
+  working unchanged, same as `resolveAsset`'s `form` argument in 0.3.0.
+- With this, `resolveImport` joins `resolveAsset` at two positional arguments.
+  Per the "코어에 무언가를 더하기 전에" rule in CLAUDE.md, the next argument
+  either hook would need is the point to switch to an options object instead
+  of adding a third positional one.
+
+### Fixed
+
+- **Issue #2: inline `style="…"` asset URLs reach `resolveAsset`
+  XML-entity-decoded**,
+  matching what a `<Style src>`-loaded `.uss` file's URLs already got (that
+  file was never XML, so it never had entities to decode; an inline attribute
+  is XML text and did). `background-image: url('…&guid=…')` written inline
+  used to reach the hook as `&apos;…&amp;guid=…&apos;` — wrapper quotes and
+  ampersands both literal — because `inlineDeclarations` (style/resolve.ts)
+  parses straight from the raw XML source. Fixed at `assetPath()`
+  (render/css-map.ts), immediately before the `url()`/`resource()` wrapper is
+  parsed and right before the value leaves the model for the hook — the same
+  point `<Style src>` and painted text already decode at, not at parse time
+  (decoding then would corrupt the byte-exact round-trip source slices).
+  Confirmed against two real URLs from the external corpus in
+  `ReuHomi/vscode-uxml-preview` (`examples/external`, commit `dbda387`) where
+  this caused `asset-unresolved` for 7 URLs across 2 files. Scope: only the
+  asset-URL value reaching `resolveAsset`; other inline-style property values
+  still carry undecoded entities in the model (unaffected here, since no
+  other current consumer inspects their text — `-unity-font-definition`'s
+  `resource(...)` value is only checked for presence, never read).
+
+### Docs
+
+- **`docs/accuracy.md`'s "which controls this covers" table now has a stated,
+  computed rule** instead of being left unverified. It never added up on its
+  own terms (17+1+6+5+1 = 30, not the stated 31) and the original counting
+  rule was never written down, so it is now defined explicitly — classify
+  `inventory` as the representative screen, then each other case by the first
+  of `<ui:ScrollView`, `<ui:Button`, `<ui:Label` its UXML contains, else
+  `VisualElement` only — and computed from `tests/golden/cases.ts` rather than
+  hand-counted. Updated numbers: `Button` 6→10, `ScrollView` 5→4 (`VisualElement`
+  only, `Label`, and the representative screen are unchanged). Mirrored into
+  `docs/accuracy.en.md`, which is not machine-checked.
+- **The drift guard now covers this table's five numbers too**, in
+  `docs/accuracy.md` only. Same shape as the three headline figures: recomputed
+  live and failing (not skipping) if it can't find a row to check. Confirmed by
+  breaking a count and by removing a row's label, both on purpose.
+
+## 0.3.0 — 2026-08-09
+
+Four fixes the VSCode extension (`vscode-uxml-preview`) hit while consuming
+this package as a dependency — not speculative additions.
+
+### Added
+
+- **`KNOWN_DIVERGENCES`** gives a host something to tell apart "a limit we
+  know about" from "a bug". Three entries, and the kinds carry the
+  distinction that matters. Font metrics move with the platform, so the
+  difference cannot be reproduced here at all. Unity's rule for a wrap
+  container's height is simply not specified, so there is nothing to match
+  yet. And the Yoga vendored in UI Toolkit resolves a main-axis percentage
+  against an indefinite parent differently from the one this package depends
+  on — that one reproduces perfectly every time; it just cannot be fixed
+  from inside this repository. The 1px case is deliberately absent: that is
+  the golden tests' judgement parameter, not a limit of the renderer, and a
+  host showing it would read as a defect.
+- **`uxml-preview/unity-project`**, a Node-only subpath exporting
+  `buildGuidIndex(projectRoot)`. Builds a GUID → absolute-path index from a
+  Unity project's `.meta` files, for the case where an asset reference's path
+  has gone stale but its GUID is still good. Skips `Library/`, `Temp/`,
+  `obj/`, `.git/`, and any `.meta` file it cannot read. Kept out of the main
+  entry point because it uses `node:fs` and the main entry must stay
+  browser-safe.
+
+### Changed
+
+- **`resolveAsset` now receives a second argument, `form: 'url' | 'resource'`**,
+  telling `url("...")` and `resource("...")` background-image references
+  apart. They resolve differently — `url()` is a path, `resource()` is a
+  Unity Resources-folder name — and a host that resolved both the same way
+  before this had no way to know which one it was looking at.
+  **Non-breaking**: existing `(path) => ...` implementations keep working
+  unchanged: `form` is an additional argument, not a replacement one.
+
+### Fixed
+
+- `UxmlDocument.warnings` and `RenderResult.warnings` doc comments corrected.
+  The former said it covers "malformed input" only; it also carries
+  `'import-unresolved'` for an unreadable `<Style src="…">` or `@import`. The
+  latter said it is distinct from the former on that same wrong premise.
+  Comment-only — no behavior changed.
+
+### Docs
+
+- **`docs/accuracy.md`'s published figures were stale**: two comparable cases
+  (`state-vs-id`, `state-vs-inline`) were merged after the doc's numbers were
+  last written, and nothing caught it. Recomputed from a live run rather than
+  trusted: **548 / 564 values (97.2%)**, **31 / 33 cases matching**, **33 / 33**
+  Unity baseline coverage — up from the stale 532/548, 29/31, 31/31. Mirrored
+  into `README.md` (both languages) and `docs/uss-vs-css.md`/`.ko.md`.
+  `docs/accuracy.en.md` was updated too but is not machine-checked (see next).
+- **Added a regression guard**: `tests/golden/golden.test.ts` now has
+  `matches the figures published in docs/accuracy.md`, which recomputes the
+  three headline numbers from the actual case set and fails if
+  `docs/accuracy.md` says anything else — including failing (not skipping) if
+  it cannot find a row to check, so the guard can't be silently defeated by a
+  table-format change. This is the third time this specific number went stale
+  publicly (`docs/accuracy.md` itself already records the first two); the doc
+  fix alone would only prevent a third, not a fourth.
+- Left unfixed and flagged in `docs/accuracy.md`/`accuracy.en.md`: the
+  "which controls this covers" breakdown table (`Button`/`ScrollView`/etc.
+  row counts) was already internally inconsistent before this change
+  (17+1+6+5+1 = 30, not the stated 31) and is not machine-checked. Recomputing
+  it requires a counting rule that is not written down anywhere; a guess
+  risked swapping one wrong number for another, so it was left alone and
+  called out inline instead.
+
 ## 0.2.0 — 2026-08-06
 
 Five controls instead of three, a representative screen measured end to end

package/README.md

@@ -25,12 +25,14 @@ stylesheet comes out wrong.</sub>
 npm install uxml-preview
 ```
 
-> **v0.1.0 — early release.** Three controls (`VisualElement`, `Label`,
-> `Button`) and a support matrix that says plainly what has not been measured.
+> **v0.2.0 — early release.** Five controls (`VisualElement`, `Label`, `Button`,
+> `Image`, `ScrollView`), everything else drawn as a plain box with a warning,
+> and a support matrix that says plainly what has not been measured.
 > Read [what is not verified yet](#what-is-not-verified-yet) before relying on it.
 >
-> **v0.1.0 — 초기 릴리스입니다.** 컨트롤 3종(`VisualElement`, `Label`, `Button`)이고,
-> 검증되지 않은 부분을 지원 범위표에 그대로 적어뒀습니다. 쓰시기 전에
+> **v0.2.0 — 초기 릴리스입니다.** 컨트롤 5종(`VisualElement`, `Label`, `Button`,
+> `Image`, `ScrollView`)이고, 나머지는 경고와 함께 일반 박스로 그립니다.
+> 검증되지 않은 부분은 지원 범위표에 그대로 적어뒀습니다. 쓰시기 전에
 > [아직 검증되지 않은 것](#아직-검증되지-않은-것)을 먼저 봐주세요.
 
 ---
@@ -45,8 +47,8 @@ directly in a web browser. It uses **Yoga** — the same layout engine Unity UI
 itself uses — compiled to WebAssembly, so results match the Unity Editor rather than
 approximating it.
 
-Measured against Unity 6000.0.40f1: **532 of 548 element coordinates identical**
-across 31 layout cases, including a full working screen. Ten of the sixteen
+Measured against Unity 6000.0.40f1: **660 of 676 element coordinates identical**
+across 40 layout cases, including a full working screen. Ten of the sixteen
 differences are font metrics rather than layout — a browser cannot measure
 Unity's font asset. All sixteen are named in
 [`docs/accuracy.en.md`](docs/accuracy.en.md).
@@ -95,8 +97,9 @@ That broken feedback loop is what this library fixes.
 | 3 | USS style resolver | ✅ |
 | 4 | Yoga layout + DOM painting | ✅ |
 | 5 | Golden tests against Unity | ✅ |
-| 6 | **v0.1 release** | 🔨 |
-| 7+ | More controls, editing layer, tool integration | ⬜ |
+| 6 | **v0.1 release** | ✅ |
+| 7 | **v0.2 — ScrollView, Image, states, a measured screen** | ✅ |
+| 8+ | Editing layer, tool integration | ⬜ |
 
 Full plan: [`docs/ROADMAP.md`](docs/ROADMAP.md)
 
@@ -207,12 +210,12 @@ Checked by comparing element geometry against the Unity Editor, case by case.
 Geometry rather than pixels: Unity draws text with its own font asset and a
 browser does not, so a pixel diff would measure the font more than the layout.
 
-Measured against Unity on 2026-08-02, over 18 cases and 61 elements:
+Measured against Unity on 2026-08-12, over 40 cases and 169 elements:
 
 | | |
 |---|---|
-| Cases matching exactly | **29 / 31** |
-| Values within 0.5px | **532 / 548 (97.1%)** |
+| Cases matching exactly | **38 / 40** |
+| Values within 0.5px | **660 / 676 (97.6%)** |
 
 The sixteen divergences are four different things, and the distinction matters
 more than the ratio: **ten are text metrics**, three are 1px, two are a
@@ -243,7 +246,7 @@ as nested flex, and computed values have to be resolved to fixed numbers or
 calculated in C#.
 
 **How close is the output to Unity?**
-532 of 548 element coordinates identical against Unity 6000.0.40f1, across 31
+660 of 676 element coordinates identical against Unity 6000.0.40f1, across 40
 layout cases including a complete inventory screen. Geometry is compared rather
 than screenshots, because Unity draws text with its own font asset — which is
 also why ten of the sixteen differences are font metrics rather than layout.
@@ -277,8 +280,8 @@ Apache-2.0
 **Yoga**를 WebAssembly로 그대로 사용하기 때문에, 결과를 "비슷하게 흉내내는" 것이 아니라
 유니티 에디터와 일치시킵니다.
 
-Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아웃 케이스 31개에서
-**요소 좌표 548개 중 532개가 일치**합니다. 어긋난 16개 중 **10개는 레이아웃이 아니라
+Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아웃 케이스 40개에서
+**요소 좌표 676개 중 660개가 일치**합니다. 어긋난 16개 중 **10개는 레이아웃이 아니라
 폰트 메트릭** 차이입니다 — 브라우저는 유니티 폰트 에셋을 잴 수 없습니다.
 16개 전부 [`docs/accuracy.md`](docs/accuracy.md)에 이름과 사유를 적어뒀습니다.
 
@@ -325,8 +328,9 @@ Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아
 | 3 | USS 스타일 리졸버 | ✅ |
 | 4 | Yoga 레이아웃 + DOM 페인팅 | ✅ |
 | 5 | 유니티 대조 골든 테스트 | ✅ |
-| 6 | **v0.1 공개** | 🔨 |
-| 7+ | 컨트롤 확장, 편집 레이어, 도구 통합 | ⬜ |
+| 6 | **v0.1 공개** | ✅ |
+| 7 | **v0.2 — ScrollView·Image·상태, 대표 화면 대조** | ✅ |
+| 8+ | 편집 레이어, 도구 통합 | ⬜ |
 
 전체 계획: [`docs/ROADMAP.md`](docs/ROADMAP.md)
 
@@ -410,8 +414,8 @@ pnpm build
 계산이 필요한 값은 고정값으로 풀거나 C#에서 계산해야 합니다.
 
 **유니티와 얼마나 같나요?**
-Unity 6000.0.40f1 기준, 인벤토리 화면 전체를 포함한 레이아웃 케이스 31개에서
-**요소 좌표 548개 중 532개 일치**입니다. 스크린샷이 아니라 좌표를 비교하는데,
+Unity 6000.0.40f1 기준, 인벤토리 화면 전체를 포함한 레이아웃 케이스 40개에서
+**요소 좌표 676개 중 660개 일치**입니다. 스크린샷이 아니라 좌표를 비교하는데,
 유니티가 자기 폰트 에셋으로 글자를 그리기 때문입니다 — 그리고 그 사실 때문에
 불일치 16개 중 **10개가 레이아웃이 아니라 폰트 메트릭**입니다. 전부
 [`docs/accuracy.md`](docs/accuracy.md)에 이름이 적혀 있습니다.

package/dist/index.d.ts

@@ -17,6 +17,8 @@ export { resolveStyles, explainProperty } from './style/resolve';
 export type { Candidate, ComputedStyle, ComputedValue, ResolveOptions, ResolveResult, } from './style/resolve';
 export type { Specificity } from './style/specificity';
 export { isInherited } from './style/properties';
+export { KNOWN_DIVERGENCES } from './known-divergences';
+export type { KnownDivergence } from './known-divergences';
 /**
  * Parse UXML and USS text into a document model.
  *
@@ -35,8 +37,23 @@ export interface ParseOptions {
      * `project://database/Assets/UI/base.uss`, which only the host application
      * knows how to turn into file contents, and there is no reason for a host to
      * implement that lookup twice.
+     *
+     * `from` is the URL of the stylesheet containing this import — exactly the
+     * string this hook received as `url` when that containing sheet was itself
+     * resolved, unmodified. `null` for a `<Style src="…">` reference, which is
+     * not contained in any stylesheet. A relative `@import` cannot be resolved
+     * without this: `a.uss` importing `"b.uss"` means a path relative to `a.uss`,
+     * not to the UXML document, and there is no other way for the host to learn
+     * `a.uss`'s own URL at the point it resolves `b.uss`.
+     *
+     * Non-breaking: this is an added argument, not a replacement one, so an
+     * existing one-argument callback keeps working unchanged.
+     *
+     * Relative imports are deduplicated by `(url, from)`, so two parent sheets
+     * may resolve the same spelling to different files. Root-fixed URLs —
+     * `project://…` or a path beginning with `/` — are deduplicated by URL alone.
      */
-    resolveImport?: (url: string) => string | null;
+    resolveImport?: (url: string, from: string | null) => string | null;
 }
 export declare function parse(uxml: string, uss?: string, options?: ParseOptions): UxmlDocument;
 /**
@@ -57,8 +74,15 @@ export interface RenderOptions {
      * USS background images look like `url("project://database/Assets/foo.png")`
      * or `resource("foo")`. Browsers cannot load these, so the host application
      * must map them to real URLs. Return `null` to draw a placeholder instead.
+     *
+     * `form` says which of the two `path` came from — `'url'` is a path
+     * (project-relative or absolute), `'resource'` is a Unity Resources-folder
+     * name (no extension, resolved by Unity's own lookup rules). They are not
+     * interchangeable: a host that ignores `form` and resolves both as file
+     * paths will resolve `resource("foo")` against whatever happens to sit at
+     * that path — the wrong image, silently, if one exists there at all.
      */
-    resolveAsset?: (path: string) => string | null;
+    resolveAsset?: (path: string, form: 'url' | 'resource') => string | null;
     /** Panel size in pixels. Defaults to the container's client size. */
     size?: {
         width: number;
@@ -94,7 +118,8 @@ export interface RenderResult {
     /**
      * Everything the renderer could not honour: unsupported controls, properties,
      * selectors and units, plus unresolved assets. Distinct from
-     * `UxmlDocument.warnings`, which only covers malformed input.
+     * `UxmlDocument.warnings`, which covers malformed input and unresolved
+     * `<Style src="…">` / `@import` references rather than render-time support.
      */
     warnings: readonly Warning[];
     /** Painted element per model node. Lets a host map a click back to the tree. */