uxml-preview 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 0.3.0 — Unreleased
+
+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: **548 of 564 element coordinates identical**
+across 33 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-06, over 33 cases and 141 elements:
 
 | | |
 |---|---|
-| Cases matching exactly | **29 / 31** |
-| Values within 0.5px | **532 / 548 (97.1%)** |
+| Cases matching exactly | **31 / 33** |
+| Values within 0.5px | **548 / 564 (97.2%)** |
 
 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
+548 of 564 element coordinates identical against Unity 6000.0.40f1, across 33
 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과 대조한 결과, 실무형 화면을 포함한 레이아웃 케이스 33개에서
+**요소 좌표 564개 중 548개가 일치**합니다. 어긋난 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 기준, 인벤토리 화면 전체를 포함한 레이아웃 케이스 33개에서
+**요소 좌표 564개 중 548개 일치**입니다. 스크린샷이 아니라 좌표를 비교하는데,
 유니티가 자기 폰트 에셋으로 글자를 그리기 때문입니다 — 그리고 그 사실 때문에
 불일치 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.
  *
@@ -57,8 +59,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 +103,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. */