uxml-preview 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,171 @@
 # Changelog
 
-## 0.1.0 — unreleased
+## 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
+against Unity, and two cascade defects that a synthetic case set could not have
+found.
+
+### Changed — this affects what you see on screen
+
+- **Controls with no renderer of their own are now drawn as plain boxes**
+  instead of being dropped along with everything inside them. One
+  `<ui:ScrollView>` used to empty a panel. Each still reports a warning, and
+  what is missing is only whatever makes that control look like itself.
+- **`Button` now carries Unity's default `margin: 1px 3px`.** Existing layouts
+  containing buttons will shift by a few pixels — toward Unity, not away from
+  it. Unity supplies this through a theme stylesheet and this library supplied
+  nothing, which is why the first `Button` ever compared missed on 18 of 48
+  values. Overridable from your own USS exactly as in Unity, and the values are
+  in `src/controls/theme.ts`.
+- **`Button` labels are now centred**, which is what Unity does. Found by the eye
+  check rather than by measurement: where a glyph sits inside a box does not move
+  the box, so all 548 compared coordinates agreed while the two screenshots
+  plainly did not.
+- **Control defaults now lose to your USS regardless of specificity.** They are a
+  lower origin, like a browser's user-agent sheet — measured, and the opposite of
+  what this library previously did and documented. `Button { margin: 0 }` in your
+  stylesheet now wins against the built-in `.unity-button` rule, as in Unity.
+- **`enabled="false"` puts an element and its subtree into `:disabled`**, without
+  anyone passing `states`. Both the state and its inheritance are measured.
+- **Disabled elements render at half opacity**, as Unity draws them. The value
+  came from sampling the screenshots rather than judging them: Unity paints the
+  disabled button rgb(41,50,67), which is its base colour composited at exactly
+  one half over the footer on all three channels.
+
+### Added
+
+- **`ScrollView`.** One tag becomes four elements in Unity, and the three it adds
+  decide where everything inside lands — reproducing the box alone put every
+  descendant in the wrong place and squeezed children that should have overflowed.
+  The hierarchy was observed from layout dumps rather than read from a source
+  mirror; the middle level, `unity-content-and-vertical-scroll-container`, appears
+  in no documentation. Scrollbar width is reserved but nothing is drawn: dragging,
+  wheeling and scroll position are outside a static render.
+- **`Image`**, and `-unity-background-scale-mode` with its three values. The
+  default is `stretch-to-fill`, confirmed by the eye check.
+- **Author USS reaches control parts.** `#unity-content-container { flex-direction: row }`
+  — how a real project lays out a scroll region's contents — previously reached
+  nothing at all, because parts were built after the cascade had run. A selector
+  naming any `unity-` element that matches nothing now warns and says why.
+- **`<Style src="…">` is read**, through the same `resolveImport` hook as
+  `@import`. UI Builder writes that element into a file whenever a stylesheet is
+  attached, so it is the ordinary shape of a real document — and ignoring it meant
+  a real project's UXML rendered unstyled with nothing said about why.
+
+- **Pseudo-class states, per element.** `render(doc, el, { states: { '#UseButton':
+  ['hover'], '#DropButton': ['disabled'] } })`. Keys are ordinary USS selectors.
+  States are explicit input rather than mouse events, so the same call always
+  draws the same picture — a screen you can compare against Unity, or against
+  yesterday. Per element rather than per document because real screens mix one
+  hovered button with a disabled one.
+  Unity's *own* state defaults are deliberately not included: a layout dump
+  measures geometry and a hover colour is not geometry, so there is no way to
+  prove them yet.
+- Style provenance now records which states a rule needed (`origin.states`), so
+  an editor can tell "this is the hover colour" from "this is the colour".
+
+### Verified
+
+**532 of 548 element coordinates identical** against Unity 6000.0.40f1 across 31
+layout cases, one of which is a complete inventory screen.
+
+The ratio is lower than 0.1.0's 242/244, and the reason is worth stating: that
+figure covered 18 cases of which 17 were `VisualElement` alone, and no `Button`
+had ever been compared. This one includes a text-heavy working screen, and **ten
+of the sixteen differences are font metrics rather than layout** — both engines
+shrink the same box for the same reason, and only the ruler differs. Three more
+are 1px, two are the `yoga-layout` version difference already known in 0.1.0, and
+**one is genuinely unresolved**. All sixteen are named in
+[`docs/accuracy.en.md`](docs/accuracy.en.md).
+
+Colour, borders and corners are held by a CSS-declaration regression baseline
+(`tests/render/visual.test.ts`), which detects our own drift and is not evidence
+of agreement with Unity. That comparison is a one-time eye check, recorded with
+both screenshots in [`docs/visual-check.md`](docs/visual-check.md).
+
+### Known limitations
+
+- **Text-driven layout will not match exactly.** A browser cannot measure Unity's
+  font asset, so any box sized by its text differs. This is the same fact that
+  makes screenshot diffing useless, and it is not fixable here.
+- **A wrapped ScrollView's content height diverges.** Unity clamps it to the
+  viewport; Yoga grows it to the content. Unity's rule is not yet identified —
+  the fix that matches one case breaks another, so nothing was guessed.
+- Scrollbars reserve space but are not drawn, and there is no scrolling.
+- `-unity-background-scale-mode`'s two non-default values are implemented from
+  Unity's documented semantics but have not been seen side by side.
+
+## 0.1.0 — 2026-08-03
 
 First release. Parses Unity UI Toolkit `.uxml` and `.uss`, lays them out through
 the same Yoga engine UI Toolkit uses, paints to the DOM, and writes the files

package/README.md

@@ -21,8 +21,19 @@ stylesheet comes out wrong.</sub>
 
 [English](#english) · [한국어](#한국어)
 
-> ⚠️ **Status: pre-alpha.** Under active development. Not yet published to npm.
-> 현재 개발 초기 단계입니다. 아직 npm에 배포되지 않았습니다.
+```bash
+npm install uxml-preview
+```
+
+> **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.2.0 — 초기 릴리스입니다.** 컨트롤 5종(`VisualElement`, `Label`, `Button`,
+> `Image`, `ScrollView`)이고, 나머지는 경고와 함께 일반 박스로 그립니다.
+> 검증되지 않은 부분은 지원 범위표에 그대로 적어뒀습니다. 쓰시기 전에
+> [아직 검증되지 않은 것](#아직-검증되지-않은-것)을 먼저 봐주세요.
 
 ---
 
@@ -36,8 +47,10 @@ 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: **242 of 244 element coordinates identical**
-across 18 layout cases. The two that differ are named and explained in
+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).
 
 ```
@@ -84,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)
 
@@ -94,16 +108,25 @@ Full plan: [`docs/ROADMAP.md`](docs/ROADMAP.md)
 The support matrix is deliberately conservative — see
 [`docs/supported.en.md`](docs/supported.en.md) for the full table.
 
-- **Only geometry was compared, and only as far as Yoga.** The figure above is
-  measured at the coordinates the layout engine produces. Whether the painted
-  DOM reproduces them is checked by an invariant of our own rather than against
-  Unity. Colours, borders, corner radii and fonts are implemented but were not
-  measured at all; coordinates say nothing about them.
+- **Only geometry is compared automatically, and only as far as Yoga.** The
+  figure above is measured at the coordinates the layout engine produces.
+  Whether the painted DOM reproduces them is checked by an invariant of our own
+  rather than against Unity.
+- **Colour, borders and corners rest on a single eye comparison.** One screen was
+  put side by side with Unity and checked item by item
+  ([`docs/visual-check.md`](docs/visual-check.md)); it found two real defects, so
+  it was worth doing, but it is one screen and not an automated diff. Everything
+  it did not contain is still unmeasured.
 - **Text measurement was not compared.** Unity renders text with its own font
-  asset. Layout that is driven by measured text will not match exactly, and the
-  line-height factor is still an estimate.
-- **`Button` has no golden case.** It renders through the same path as `Label`,
-  but "same path" is not a measurement.
+  asset, so any box sized by its text differs — this accounts for ten of the
+  sixteen coordinate divergences. The line-height factor is still an estimate.
+- **A wrapped `ScrollView`'s content height diverges.** Unity clamps it to the
+  viewport; Yoga grows it to the content. Unity's rule is not yet identified.
+- **Nested disabled elements dim twice.** `enabled="false"` disables a subtree
+  and each level takes the half opacity, so a disabled control inside a disabled
+  panel comes out at a quarter. Unity almost certainly dims once; this is not
+  measured yet.
+- Scrollbars reserve their width but are not drawn, and nothing scrolls.
 - `-unity-slice-*`, `-unity-background-image-tint-color` and `transition` are
   parsed and preserved, but not drawn.
 
@@ -121,6 +144,10 @@ const doc = parse(uxmlText, ussText);
 // model → screen
 const view = render(doc, document.getElementById('preview'), {
   resolveAsset: (path) => myAssetUrlFor(path),
+
+  // Pseudo-class states are explicit input, keyed by USS selector, so the same
+  // call always draws the same picture. Per element, because real screens mix.
+  states: { '#UseButton': ['hover'], '#DropButton': ['disabled'] },
 });
 console.log(view.warnings);
 
@@ -183,18 +210,21 @@ 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 | **17 / 18** |
-| Values within 0.5px | **242 / 244 (99.2%)** |
-
-The one divergence is a percentage sized against a parent that has no explicit
-size, where `yoga-layout` resolves the main axis and the Yoga inside UI Toolkit
-does not. It is recorded rather than smoothed over — see
-[`docs/accuracy.en.md`](docs/accuracy.en.md) for the numbers, the failed attempts to
-configure around it, and how to reproduce the measurement.
+| 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
+`yoga-layout` version difference, and **one is unresolved**. The ten are not a
+layout defect — both engines shrink the same box for the same reason and only
+the ruler differs, which is the same fact that makes pixel diffing useless.
+Every one is named in [`docs/accuracy.en.md`](docs/accuracy.en.md), along with
+the failed attempts to configure around the version difference and how to
+reproduce the measurement.
 
 ### Questions this answers
 
@@ -216,10 +246,11 @@ as nested flex, and computed values have to be resolved to fixed numbers or
 calculated in C#.
 
 **How close is the output to Unity?**
-242 of 244 element coordinates identical against Unity 6000.0.40f1, across 18
-layout cases. Geometry is compared rather than screenshots, because Unity draws
-text with its own font asset. The single divergence and the numbers behind this
-are in [`docs/accuracy.en.md`](docs/accuracy.en.md).
+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.
+Every divergence is named in [`docs/accuracy.en.md`](docs/accuracy.en.md).
 
 **Will it damage my files if I edit them?**
 Editing goes through a model that keeps the original text. An unedited document
@@ -228,9 +259,10 @@ CRLF endings included — and an edit rewrites only the region it touched. The
 playground shows this live as `round-trip: exact`.
 
 **What happens to controls it does not support?**
-They are kept in the tree, reported as a warning, excluded from rendering, and
-written back out unchanged. One unsupported control never takes down the rest of
-the screen, and nothing is silently dropped.
+They are drawn as a plain `VisualElement`, reported as a warning, and written
+back out unchanged. Their own styles and their children come out normally; only
+what makes that control look like itself is missing. One unfamiliar tag never
+takes down the rest of the screen, and nothing is silently dropped.
 
 ### License
 
@@ -248,9 +280,10 @@ Apache-2.0
 **Yoga**를 WebAssembly로 그대로 사용하기 때문에, 결과를 "비슷하게 흉내내는" 것이 아니라
 유니티 에디터와 일치시킵니다.
 
-Unity 6000.0.40f1과 대조한 결과, 레이아웃 케이스 18개에서
-**요소 좌표 244개 중 242개가 완전히 일치**합니다. 어긋난 2개는
-[`docs/accuracy.md`](docs/accuracy.md)에 사유까지 적어뒀습니다.
+Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아웃 케이스 33개에서
+**요소 좌표 564개 중 548개가 일치**합니다. 어긋난 16개 중 **10개는 레이아웃이 아니라
+폰트 메트릭** 차이입니다 — 브라우저는 유니티 폰트 에셋을 잴 수 없습니다.
+16개 전부 [`docs/accuracy.md`](docs/accuracy.md)에 이름과 사유를 적어뒀습니다.
 
 ```
 .uxml + .uss  →  파싱  →  스타일 계산  →  Yoga 레이아웃  →  DOM 페인팅
@@ -295,8 +328,9 @@ Unity 6000.0.40f1과 대조한 결과, 레이아웃 케이스 18개에서
 | 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)
 
@@ -305,15 +339,22 @@ Unity 6000.0.40f1과 대조한 결과, 레이아웃 케이스 18개에서
 지원 범위는 일부러 보수적으로 적었습니다. 전체 표는
 [`docs/supported.md`](docs/supported.md)에 있습니다.
 
-- **좌표만, 그것도 Yoga 층까지만 비교했습니다.** 위 수치는 레이아웃 엔진이 낸
+- **자동 대조는 좌표만, 그것도 Yoga 층까지입니다.** 위 수치는 레이아웃 엔진이 낸
   좌표를 잰 것입니다. 그려진 DOM이 그 좌표를 재현하는지는 유니티가 아니라 자체
-  불변식 검사로 봅니다. 색·테두리·모서리·폰트는 구현돼 있지만 아예 측정하지
-  않았습니다 — 좌표로는 알 수 없는 것들입니다
+  불변식 검사로 봅니다
+- **색·테두리·모서리는 육안 대조 1회에 기대고 있습니다.** 화면 하나를 유니티와
+  나란히 놓고 항목별로 확인했고([`docs/visual-check.md`](docs/visual-check.md)),
+  거기서 실제 결함 두 개가 나왔으니 할 값어치는 있었습니다. 다만 **화면 하나이고
+  자동 diff가 아닙니다.** 그 화면에 없던 것은 여전히 미측정입니다
 - **텍스트 측정은 대조하지 않았습니다.** 유니티는 자기 폰트 에셋으로 글자를
-  그립니다. 측정된 텍스트가 좌우하는 레이아웃은 정확히 맞지 않고, 행 높이
-  계수도 아직 추정치입니다
-- **`Button`은 골든 케이스가 없습니다.** `Label`과 같은 경로로 그려지지만,
-  "같은 경로"는 측정이 아닙니다
+  그리므로 텍스트가 크기를 좌우하는 박스는 어긋납니다 — 좌표 불일치 16건 중
+  10건이 이것입니다. 행 높이 계수도 아직 추정치입니다
+- **wrap된 `ScrollView`의 콘텐츠 높이가 어긋납니다.** 유니티는 뷰포트에 묶고
+  Yoga는 콘텐츠로 키웁니다. 유니티의 규칙을 아직 특정하지 못했습니다
+- **중첩된 비활성 요소가 두 번 흐려집니다.** `enabled="false"`가 하위 트리를
+  비활성으로 만들고 각 층이 0.5 불투명도를 받아 1/4이 됩니다. 유니티는 한 번만
+  흐리게 할 것이 거의 확실하지만 아직 측정하지 않았습니다
+- 스크롤바는 폭만 예약하고 그리지 않으며, 스크롤되지 않습니다
 - `-unity-slice-*`, `-unity-background-image-tint-color`, `transition`은
   파싱·보존은 되지만 그려지지 않습니다
 
@@ -340,7 +381,7 @@ pnpm dev
 
 예제는 예쁜 것보다 **함정을 보여주는 것**으로 골랐습니다 — `flex-direction`의 기본값이
 `column`이라는 것, 겹침 순서가 `z-index`가 아니라 마크업 순서로 정해진다는 것,
-미지원 컨트롤이 그려지지는 않지만 경고와 함께 왕복에서 살아남는다는 것.
+전용 렌더러가 없는 컨트롤도 일반 박스로 그려지고 경고와 함께 왕복에서 살아남는다는 것.
 
 ### 개발
 
@@ -373,10 +414,11 @@ pnpm build
 계산이 필요한 값은 고정값으로 풀거나 C#에서 계산해야 합니다.
 
 **유니티와 얼마나 같나요?**
-Unity 6000.0.40f1 기준, 레이아웃 케이스 18개에서 **요소 좌표 244개 중 242개 일치**
-입니다. 스크린샷이 아니라 좌표를 비교하는데, 유니티가 자기 폰트 에셋으로 글자를
-그리기 때문입니다. 유일한 불일치와 근거 수치는
-[`docs/accuracy.md`](docs/accuracy.md)에 있습니다.
+Unity 6000.0.40f1 기준, 인벤토리 화면 전체를 포함한 레이아웃 케이스 33개에서
+**요소 좌표 564개 중 548개 일치**입니다. 스크린샷이 아니라 좌표를 비교하는데,
+유니티가 자기 폰트 에셋으로 글자를 그리기 때문입니다 — 그리고 그 사실 때문에
+불일치 16개 중 **10개가 레이아웃이 아니라 폰트 메트릭**입니다. 전부
+[`docs/accuracy.md`](docs/accuracy.md)에 이름이 적혀 있습니다.
 
 **편집하면 파일이 망가지지 않나요?**
 편집은 원본 텍스트를 그대로 들고 있는 모델을 거칩니다. 고치지 않은 문서는 주석·속성
@@ -384,9 +426,9 @@ Unity 6000.0.40f1 기준, 레이아웃 케이스 18개에서 **요소 좌표 244
 영역만 바뀝니다. 놀이터의 `round-trip: exact` 표시가 이걸 실시간으로 보여줍니다.
 
 **지원하지 않는 컨트롤은 어떻게 되나요?**
-트리에 유지되고, 경고로 보고되고, 렌더링에서만 빠지고, 저장하면 그대로 다시
-나옵니다. 미지원 컨트롤 하나 때문에 화면 전체가 죽지 않고, 조용히 사라지는 것도
-없습니다.
+일반 `VisualElement`처럼 그려지고, 경고로 보고되고, 저장하면 그대로 다시 나옵니다.
+자기 스타일과 자식은 정상적으로 나오며 그 컨트롤 고유의 모양만 빠집니다. 모르는 태그
+하나 때문에 화면 전체가 죽지 않고, 조용히 사라지는 것도 없습니다.
 
 ### 라이선스
 

package/dist/controls/registry.d.ts

@@ -1,10 +1,67 @@
 import { ElementNode } from '../model/types';
+/**
+ * An element a control builds for itself, which the file never mentions.
+ *
+ * Unity's ScrollView is one tag that becomes four elements, and the three it
+ * adds are what decide where everything inside lands — a child of a ScrollView
+ * is not a child of the ScrollView. Reproducing the box without them puts every
+ * descendant in the wrong place, so they are modelled rather than approximated.
+ *
+ * `name` is Unity's own, and it is the key the layout dump joins on: these are
+ * observed in `tests/golden/unity/scrollview-*.json`, not invented.
+ */
+export interface ControlPart {
+    /** Unity's name, e.g. `unity-content-viewport`. */
+    name: string;
+    /**
+     * USS this part always carries, because the control fixes it.
+     *
+     * Written as USS rather than as CSS or Yoga calls so it goes through the same
+     * cascade output, Yoga mapping and CSS mapping as everything else. A second
+     * styling path for parts would be a second set of USS bugs.
+     */
+    style: Readonly<Record<string, string>>;
+}
 export interface ControlSpec {
-    /** Renders the `text` attribute as its content. */
+    /** Renders the `text` attribute as its own content. */
     hasText: boolean;
+    /**
+     * Elements the control inserts between itself and the file's children,
+     * outermost first. The file's children go inside the last one.
+     */
+    parts: readonly ControlPart[];
+    /**
+     * USS classes Unity's own constructor puts on this control, which the theme
+     * stylesheet then targets. Not in the `class` attribute and not in the model:
+     * the file says `<ui:Button />` and Unity adds the rest.
+     */
+    classes: readonly string[];
+}
+export interface ResolvedControl {
+    spec: ControlSpec;
+    /**
+     * No renderer of its own; drawn as a plain `VisualElement`. Callers report
+     * this once per element so the preview says what it did (CLAUDE.md rule 6).
+     */
+    fallback: boolean;
 }
 /** The document container. Not a control, but it is the panel's root box. */
 export declare const ROOT_LOCAL_NAME = "UXML";
-export declare function controlFor(node: ElementNode): ControlSpec | null;
+export declare function isNonVisual(node: ElementNode): boolean;
+/**
+ * Purpose:      the spec to draw `node` with, always.
+ * Ensures:      never null. `fallback` is true only for elements a caller
+ *               should report; the root is excluded because it is the panel
+ *               box rather than a control that failed to resolve.
+ */
+export declare function resolveControl(node: ElementNode): ResolvedControl;
 export declare function isRoot(node: ElementNode): boolean;
+/**
+ * Purpose:      the USS classes Unity would have added to this element.
+ * Ensures:      empty for anything with no renderer of its own — a fallback box
+ *               must not pick up theme styling meant for a control we do not
+ *               actually draw.
+ */
+export declare function implicitClassesOf(node: ElementNode): readonly string[];
+/** Controls with a renderer of their own. Everything else still draws. */
 export declare function supportedControlNames(): string[];

package/dist/controls/theme.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Unity's control defaults, as far as we have measured them.
+ *
+ * Unity ships a theme stylesheet that gives controls their own margin, padding
+ * and border before any author USS runs. This renderer supplied none of it, so
+ * every Button sat 3px left and 1px high of where Unity puts it — invisible on
+ * one button and compounding across a row.
+ *
+ * **Only measured values live here.** Every declaration below was derived from
+ * a Unity layout dump in tests/golden/unity/, and adding `Button`'s margin
+ * moved all five Button cases from 18 mismatched values to zero. Values read
+ * from Unity's source instead would look identical in this file while being
+ * wrong in a way no test could see: they would not appear in the unmeasured
+ * list, so they would quietly pass for ground truth.
+ *
+ * Two kinds of measurement feed this file, and the second was a long time
+ * coming. Geometry comes from the coordinate dumps. `-unity-text-align` cannot:
+ * where a glyph sits inside a box does not move the box, so no dump can ever
+ * see it. It came from the Step 6 eye check — Unity centres a Button's label
+ * and this renderer had it at the top left, which is visible the moment the two
+ * screenshots sit side by side and invisible in 368 compared numbers.
+ *
+ * `opacity` on `:disabled` came from the same screenshots, but by sampling
+ * pixels rather than looking. Unity's disabled Drop button is rgb(41,50,67);
+ * the base colour rgb(58,74,104) composited at half over the footer's
+ * rgb(24,26,31) is (41, 50, 67.5) — all three channels exact. That arithmetic
+ * is the evidence, and it is why the value is 0.5 and not a number that merely
+ * looked about right.
+ *
+ * Getting there took two wrong turns worth recording. First the author's
+ * `Button:disabled` rule was blamed for not applying — it genuinely does not,
+ * because `#DropButton` outranks it, in both engines. Then Unity was accused of
+ * ranking state rules above specificity, and `state-vs-id` and `state-vs-inline`
+ * refuted that: Unity answers 40 to both, exactly as this cascade already did.
+ * The dimming was never about the cascade at all.
+ *
+ * What is deliberately absent, and why:
+ *
+ *   - `Label` — measured, and it has no default margin. `inherit-vs-direct`
+ *     puts an explicitly-sized Label at the origin of a sized parent, and Unity
+ *     reports x=0 y=0. Nothing to add is a result, not an omission.
+ *   - padding, border, font — invisible to the cases we have. Every compared
+ *     element is explicitly sized, and USS is border-box, so padding and border
+ *     do not move the outer rectangle. They are unmeasured, so they are not here.
+ *   - `Label`'s text alignment — the eye check could not separate it from the
+ *     box at this size. Unmeasured, so absent.
+ *
+ * The class names were a separate claim from the values, and are now measured
+ * too. `unity-button` came from Unity's documented `Button.ussClassName`, which
+ * the margin dumps said nothing about — they proved the spacing, not the
+ * selector delivering it. The golden case `theme-class-hook` was written to
+ * settle exactly that, and Unity answered on 2026-08-05: a `.unity-button` rule
+ * in author USS reaches a bare `<ui:Button>`, sizing it 120×40 in both engines.
+ * The selector below is therefore measured, not assumed.
+ */
+/** Where every value in this file was measured. Theme values move between versions. */
+export declare const THEME_UNITY_VERSION = "6000.0.40f1";
+/**
+ * Parsed once and spliced in ahead of author sheets, so an author rule of equal
+ * specificity wins on order — which is how a theme stylesheet behaves in Unity.
+ *
+ * Class selectors rather than type selectors, also for Unity's reasons: a theme
+ * rule at `.unity-button` (0,1,0) beats an author's `Button { }` (0,0,1), and
+ * that is a real Unity gotcha worth reproducing rather than smoothing over.
+ */
+export declare const THEME_USS = ":disabled {\n  opacity: 0.5;\n}\n\n.unity-button {\n  margin: 1px 3px;\n  -unity-text-align: middle-center;\n}\n";
+/**
+ * **Unmeasured, and reachable: nested disabled elements.**
+ *
+ * `enabled="false"` puts a whole subtree into `:disabled` — measured, by
+ * `disabled-inherits`. The rule above therefore hands every level its own
+ * `opacity: 0.5`, and CSS multiplies them, so a disabled button inside a
+ * disabled panel comes out at a quarter. Unity almost certainly dims once.
+ *
+ * Not guessed at, because the fix has a choice inside it — dim only where
+ * `enabled="false"` was written, or suppress the inherited one — and picking
+ * without evidence is how the `.unity-button` selector became a hypothesis
+ * nobody noticed for a day. Opacity leaves no trace in a coordinate dump, so
+ * settling it needs a screenshot of a nested case. Recorded in
+ * `docs/backlog.md` and visible in `visual-nested-disabled`.
+ */
+/**
+ * Purpose:      how much width a vertical scrollbar claims, given whether it shows.
+ * Ensures:      0 when the content fits — Unity hides the scroller rather than
+ *               shrinking the viewport for a bar nobody can see.
+ */
+export declare function verticalScrollbarWidth(overflows: boolean): number;