uxml-preview 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## 0.6.0 — 2026-10-16
+
+Diagnostics that say what Unity does instead, text measured the way Unity
+measures it, fonts, and `aspect-ratio`. A minor version in 0.x because drawn
+output changes (text height, `:enabled`, letter/word spacing, `aspect-ratio`)
+and the published accuracy figures move. No type is removed and no
+`WarningKind` is added; every new field is optional.
+
+### Accuracy — previous and new figures
+
+| Set | 0.5.1 | 0.6.0 | Why |
+|---|---:|---:|---|
+| Base coordinates (Unity 6000.0.40f1) | 660 / 676 | 660 / 676 | unchanged: the three text-measuring cases are excluded from it, and of its 16 mismatches the 9 caused by text are widths and x. `ItemDesc.height` has a fixed height and shrinks for a theme reason (Unity gives Labels `flex-shrink: 0`), so text height cannot reach it |
+| Template cohort (6000.0.40f1) | 200 / 220 | 215 / 220 | text height from FaceInfo removed 14 Label heights and the `y` they pushed |
+| Text cohort (new; Chromium vs Unity 6.3) | — | lines 60/60, height 52/60, width 60/60, boundary 79/80 | see `docs/accuracy.md`; none unexplained |
+| 6.3 re-dump of the golden set | — | 1012 / 1012 equal to a 6000.0 dump of the same day | every golden case lays out the same on 6000.3.25f1. Against the committed 2026-08-12 baselines nine values differ, all the known `inventory` footer 1px |
+
+### Behavior changes
+
+- **Text height follows Unity.** `ceil(lines × size × (ascent − descent) /
+  pointSize)`, from the FaceInfo Unity reports, plus paragraph spacing. The
+  default (editor Inter) gives 12px → 15, 20px → 25 where 0.5.1 gave
+  14.4 / 24. A multi-line block is rounded once, not per line.
+- **`letter-spacing` / `word-spacing` are not CSS px.** Unity widens by
+  value × font size / 100 per gap; measured and drawn that way.
+  `-unity-paragraph-spacing` is measured and drawn.
+- **`:enabled` applies automatically** to every element that is not disabled
+  (measured on 6000.0.40f1 and 6000.3.25f1). A screen with `:enabled` rules
+  draws differently.
+- **`aspect-ratio` is laid out** (Unity 6.3+); it matched Unity 52/52 on the
+  measured case.
+- A Label's text is measured decoded (`&`, `
`), as it is drawn.
+- **Spaces are measured the way Unity 6.3 LTS lays them out.** Under
+  `normal` and `nowrap`, a run of spaces measures as one and leading spaces
+  as none; `pre` and `pre-wrap` keep them. Measured at 20px
+  (`tests/layout/unity/<version>/probe-editor/spaces.json`,
+  `spaces-prewrap.json`). Unity 6000.0 does not collapse them; the preview
+  follows 6.3. Trailing spaces are not measured; they follow CSS, which is
+  what the browser paints. 0.5.1 measured every space as written.
+- Painted letter spacing matches measured spacing: no spacing beside a
+  space (advanced generator) and none after the last character.
+- `-unity-text-generator` (`standard` / `advanced`) is measured and painted,
+  and no longer raises a `not-rendered` warning with `affectsLayout`.
+- A border width in an unsupported unit is reported once, not twice.
+- New warnings, all `unsupported-property` with `reason: 'invalid-value'`
+  unless noted: `hsl()`, `cubic-bezier()`, `opacity` in `%`, `inherit`.
+  `linear-gradient()` keeps `not-uss` and says Unity shows its warning icon.
+- Text drawn with the default font (no `-unity-font-definition`) that
+  contains Hangul, Han or Kana warns: `unsupported-property` with the new
+  reason `font-fallback` and `subject.missingGlyphs`. Inter has no such
+  glyphs; Unity draws them with a fallback font, measured 1–4px taller.
+- `states` keys that match nothing, contain a state pseudo-class, or list a
+  state Unity never sets now warn: `unsupported-selector` with
+  `subject.problem`.
+
+### New, all optional
+
+- `Warning.nodes` — every element a declaration's rule matched.
+- `at.url` / `at.from` on USS locations — the arguments `resolveImport`
+  received for that sheet, so `at.sheet` can be mapped without the expanded
+  document.
+- `subject.unityEffect` — `unstyled-from-here` (Unity's style updater throws:
+  `hsl()` on 6000.3, `cubic-bezier()`,
+  `filter` on 6000.0 — measured: the element with the value and every element after it in the panel lose their style, elements before it keep theirs; hence `unstyled-from-here`) or `file-inline-dropped` (one bad inline value drops
+  every inline style in that UXML file), with the Unity versions measured.
+- `subject.problem` / `subject.state` on `states-key`; `subject.role: 'font'`
+  on `asset`.
+- `RenderResult.document`, `.styles`, `.partStyles` — the expanded tree and
+  the cascade `render()` drew with.
+- `classifyVisibility(result)` — hidden / emptied / collapsed / shown, ported
+  from uxml-author.
+- `RenderOptions.resolveFont(path, form)` → family, or `{ family, faceInfo }`,
+  or `null`. `TextContext` gains `fontFamily`, `faceInfo`, `letterSpacing`,
+  `wordSpacing`, `paragraphSpacing`, `textGenerator`.
+- `textHeight`, `EDITOR_DEFAULT_FACE_INFO`, `FaceInfo`.
+
+### For consumers
+
+- A `states-key` warning no longer always means "this key is unusable":
+  read `subject.problem` (absent = unusable selector). uxml-author master
+  assumes the 0.5.1 meaning.
+- `aspect-ratio`, `letter-spacing`, `word-spacing` and
+  `-unity-paragraph-spacing` are now laid out, so they no longer raise a
+  `not-rendered` warning with `affectsLayout`. Tests that used one of them as
+  the example of a layout gap need another; `-unity-text-auto-size` still is
+  one. Against this build, uxml-author master fails 16 tests (states keys,
+  the `aspect-ratio` layout-gap fixtures, its bundle-size note) and
+  vscode-uxml-preview main fails 1 (`letter-spacing` as the layout-gap
+  fixture); its typecheck is clean. All are consumer-side updates, none a
+  core regression. Neither consumer picks up 0.6.0 automatically
+  (uxml-author bundles its core; the extension depends on `^0.5.1`).
+- **A new `reason`, `font-fallback`.** `reason` is an open set and this is the
+  first value added to it. uxml-author master sends any `reason` it does not
+  know to `other`, which fails the run (exit 1), so a Korean UXML with no
+  font set would fail there until the skill learns it. It is not
+  `not-rendered`, so it never meets the skill's exit-3 condition
+  (`not-rendered` + `affectsLayout`). `docs/backlog.md` has the skill-side
+  note.
+- Messages changed for the inline unsupported unit and `linear-gradient()`;
+  match on `reason`/`subject`, not text.
+
+### Tools
+
+- `pnpm test:text` runs the text cohort in a real Chromium
+  (`UXML_TEXT_CHROMIUM`, `UXML_TEXT_FONTS`); it fails, never skips, when it
+  cannot run. `playwright-core` is a new devDependency.
+
+### Playground and documentation
+
+- The playground shows each warning's `reason` as a badge and what its
+  `subject` says — the Unity versions an `unityEffect` was measured on, the
+  missing script, the property to write instead, whether coordinates may
+  differ. New examples: Unity text height and spacing with a fallback-font
+  warning, `aspect-ratio`, and values Unity cannot apply.
+- README split into `README.md` and `README.ko.md`, plus Japanese
+  (`README.ja.md`) and Simplified Chinese (`README.zh-CN.md`), with absolute links (npm
+  shows the README without `docs/`). Its figures are checked against a live
+  recomputation, as `docs/accuracy.md`'s are.
+- New `docs/api.md` / `docs/api.en.md`; the warning contract moved there from
+  `docs/supported.md`. The Korean and English pages of `supported`,
+  `accuracy` and `uss-vs-css` now carry the same content.
+
 ## 0.5.1 — 2026-10-13
 
 A cleanup release: nothing drawn changes except where a Unity dump said it was
@@ -390,12 +512,12 @@ of the sixteen differences are font metrics rather than layout** — both engine
 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).
+[`docs/accuracy.en.md`](https://github.com/ReuHomi/uxml-preview/blob/main/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).
+both screenshots in [`docs/visual-check.md`](https://github.com/ReuHomi/uxml-preview/blob/main/docs/visual-check.md).
 
 ### Known limitations
 
@@ -420,7 +542,7 @@ back unchanged.
 Measured against **Unity 6000.0.40f1** across 18 layout cases and 61 elements:
 **242 of 244 element coordinates identical** (0.5px tolerance; the matching 17
 cases agree exactly, not merely within tolerance). Procedure and per-case
-figures in [`docs/accuracy.en.md`](docs/accuracy.en.md).
+figures in [`docs/accuracy.en.md`](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md).
 
 Round-trip is byte-exact on all 15 fixtures — comments, attribute order,
 entity encodings, CRLF line endings, mixed indentation, unsupported controls.
@@ -433,7 +555,7 @@ entity encodings, CRLF line endings, mixed indentation, unsupported controls.
 - Cascade: specificity, source order, inheritance, inline styles, `var()`
   custom properties, shorthand expansion
 - Layout: the flex family, sizing, box model, positioning
-- Full matrix: [`docs/supported.en.md`](docs/supported.en.md)
+- Full matrix: [`docs/supported.en.md`](https://github.com/ReuHomi/uxml-preview/blob/main/docs/supported.en.md)
 
 ### Known limitations
 

package/README.ja.md

@@ -0,0 +1,84 @@
+# uxml-preview
+
+*[English](https://github.com/ReuHomi/uxml-preview/blob/main/README.md) · [한국어](https://github.com/ReuHomi/uxml-preview/blob/main/README.ko.md) · 日本語 · [简体中文](https://github.com/ReuHomi/uxml-preview/blob/main/README.zh-CN.md)*
+
+**Unity UI Toolkit の UXML/USS を、Unity エディタなしでブラウザ上に描画します。レイアウトには
+UI Toolkit 自身が使用する Yoga エンジンを採用し、描画結果は実際の Unity と突き合わせて検証しています。**
+
+[![プレイグラウンド画面：上部にプレビュー画面、下部に各警告の理由と Unity 側の実際の挙動を表示](https://raw.githubusercontent.com/ReuHomi/uxml-preview/main/docs/media/playground.png)](https://reuhomi.github.io/uxml-preview/)
+
+### ▶ [プレイグラウンドを開く](https://reuhomi.github.io/uxml-preview/)
+
+手元の `.uxml` と `.uss` を貼り付けるか、サンプルを開いて試せます。ファイルはどこにも
+アップロードされず、すべてページ内で動作します。
+
+[![CI](https://github.com/ReuHomi/uxml-preview/actions/workflows/ci.yml/badge.svg)](https://github.com/ReuHomi/uxml-preview/actions/workflows/ci.yml)
+[![Pages](https://github.com/ReuHomi/uxml-preview/actions/workflows/pages.yml/badge.svg)](https://github.com/ReuHomi/uxml-preview/actions/workflows/pages.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/ReuHomi/uxml-preview/blob/main/LICENSE)
+
+## 検証方法
+
+- **座標：** 完成画面1件を含む40個のレイアウトケースにおいて、要素の座標値 660 / 676 が Unity 6000.0.40f1 と一致しています。[すべての差異とその内訳 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md) 同じケースを Unity 6.3（6000.3.25f1）で再ダンプしたところ、同日に取得した 6000.0.40f1 のダンプとすべての配置が一致しました。[6.3 での再測定 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md#unity-63-lts-re-measurement-2026-10-15)
+- **テキスト：** 実際のブラウザで描画し、Unity 6000.3.25f1 と Label 単位で比較しました。行数 60 / 60、高さ 52 / 60、幅 60 / 60（誤差 1px または 1% 以内）。高さが異なるケースはすべて、ハングルを含まない欧文フォント Inter で韓国語、または韓国語と欧文が混在するテキストを指定したものです。Unity はこれをフォールバックフォントで描画しますが、本プレビューではまさにその状況を警告として通知します。[テキスト検証セット →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md#text-cohort-separate-set-measured-2026-10-16)
+- **Unity バージョン：** 基準バージョンは Unity 6.3 LTS です。USS プロパティかどうかの判定は Unity 公式のプロパティ一覧（6.6 まで）に基づいており、6.7 は LTS になるまでサポート対象外です。[サポート範囲 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/supported.en.md)
+- **一致しない箇所は見過ごさず、警告として報告します。** 未サポートのコントロール・プロパティ・値は、その理由とともに（測定済みの場合は Unity 側が代わりにどう振る舞うかも含めて）警告として返されます。[警告について →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.en.md#warnings)
+
+## 3つの使い方
+
+| 用途 | 推奨ツール |
+|---|---|
+| **画面をデザインする** | ブラウザ上の[プレイグラウンド](https://reuhomi.github.io/uxml-preview/)、またはプロジェクトファイルの隣で使える [UXML Preview for VS Code](https://github.com/ReuHomi/vscode-uxml-preview) |
+| **AI エージェントに UI を書かせる** | [uxml-author](https://github.com/ReuHomi/uxml-author) — UXML/USS を記述し、本ライブラリで描画・結果確認まで行ってから出力するスキル |
+| **ツールを開発する** | 本ライブラリ：`npm install uxml-preview`、詳細は [API ドキュメント](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.en.md) |
+
+## インストール
+
+```bash
+npm install uxml-preview
+```
+
+ツール類には Node 22 以降が必要です。描画には DOM 環境（ブラウザ、またはテスト環境では
+happy-dom / jsdom）が必要です。
+
+```ts
+import { loadLayoutEngine, parse, render, serialize } from 'uxml-preview';
+
+await loadLayoutEngine();                 // Yoga は WebAssembly のため、最初に1回読み込む
+
+const doc = parse(uxmlText, ussText);     // テキスト → モデル
+const view = render(doc, container, {     // モデル → 画面
+  size: { width: 1280, height: 720 },     // ウィンドウではなくパネルのサイズ
+  resolveAsset: (path, form) => myAssetUrl(path, form),  // project://… → URL（なければ null）
+});
+
+for (const w of view.warnings) console.log(w.reason ?? w.kind, w.message);
+
+view.dispose();                           // Yoga ノードはガベージコレクションされないため明示的に解放
+const { uxml, uss } = serialize(doc);     // 未編集なら入力とバイト単位で一致
+```
+
+## ドキュメント
+
+- [USS は CSS ではない](https://github.com/ReuHomi/uxml-preview/blob/main/docs/uss-vs-css.md)（英語） — CSS から移植したスタイルシートが意図通りにならない違いを実例付きで解説
+- [サポート範囲](https://github.com/ReuHomi/uxml-preview/blob/main/docs/supported.en.md)（英語） — コントロール、プロパティ、ステート、バージョン、およびそれぞれの検証範囲
+- [精度](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md)（英語） — すべての数値、測定方法、既知の差異一覧
+- [API](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.en.md)（英語） — `parse`、`render`、`serialize`、各種フック、警告、`classifyVisibility`
+- [変更履歴](https://github.com/ReuHomi/uxml-preview/blob/main/CHANGELOG.md)（英語）
+- [目視比較](https://github.com/ReuHomi/uxml-preview/blob/main/docs/visual-check.md)（韓国語） — 色や質感を Unity と並べて比較した単発の検証記録（2026-08）
+
+## 開発
+
+```bash
+pnpm install
+pnpm dev            # プレイグラウンドを起動
+pnpm test           # ブラウザや Unity なしで動作する全テスト
+pnpm test:text      # テキスト検証セット（実際の Chromium 上で実行、docs/accuracy.en.md 参照）
+pnpm build
+```
+
+Unity 側のリファレンス値を再生成するには Unity のインストールが必要です。手順は
+[精度ドキュメント](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md#producing-the-ground-truth)にあります。
+
+## ライセンス
+
+Apache-2.0

package/README.ko.md

@@ -0,0 +1,84 @@
+# uxml-preview
+
+*[English](https://github.com/ReuHomi/uxml-preview/blob/main/README.md) · 한국어 · [日本語](https://github.com/ReuHomi/uxml-preview/blob/main/README.ja.md) · [简体中文](https://github.com/ReuHomi/uxml-preview/blob/main/README.zh-CN.md)*
+
+**Unity UI Toolkit의 UXML/USS를 Unity 에디터 없이 브라우저에서 그립니다. 배치는 UI Toolkit이
+쓰는 엔진인 Yoga가 하고, 결과는 Unity와 대조해 측정했습니다.**
+
+[![놀이터 화면: 위에는 화면, 아래에는 경고마다 이유와 Unity가 대신 하는 일](https://raw.githubusercontent.com/ReuHomi/uxml-preview/main/docs/media/playground.png)](https://reuhomi.github.io/uxml-preview/)
+
+### ▶ [놀이터 열기](https://reuhomi.github.io/uxml-preview/)
+
+`.uxml`과 `.uss`를 붙여 넣거나 예제를 여세요. 아무것도 업로드되지 않고 페이지 안에서만
+돕니다.
+
+[![CI](https://github.com/ReuHomi/uxml-preview/actions/workflows/ci.yml/badge.svg)](https://github.com/ReuHomi/uxml-preview/actions/workflows/ci.yml)
+[![Pages](https://github.com/ReuHomi/uxml-preview/actions/workflows/pages.yml/badge.svg)](https://github.com/ReuHomi/uxml-preview/actions/workflows/pages.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/ReuHomi/uxml-preview/blob/main/LICENSE)
+
+## 어떻게 확인했나
+
+- **좌표:** 완성된 화면 하나를 포함한 배치 케이스 40개에서, 요소 좌표 값 660 / 676이 Unity 6000.0.40f1과 같습니다. [다른 곳은 전부 이름을 붙여 적었습니다 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.md) 같은 케이스를 Unity 6.3(6000.3.25f1)에서 다시 덤프했더니, 같은 날 다시 뜬 6000.0.40f1 덤프와 배치가 모두 같았습니다. [6.3 재측정 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.md#unity-63-lts-재측정-2026-10-15)
+- **텍스트:** 실제 브라우저에서 그려 Unity 6000.3.25f1과 Label 단위로 대조했습니다. 줄 수 60 / 60, 높이 52 / 60, 너비 60 / 60(1px 또는 1% 이내). 높이가 다른 것은 모두 라틴 글꼴 Inter로 쓴 한글·혼합 문장입니다 — Inter에 한글이 없어 Unity가 대체 폰트로 그리고, 미리보기는 바로 그 경우에 경고합니다. [텍스트 코호트 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.md#텍스트-코호트-별도-검증-세트-2026-10-16-측정)
+- **Unity 버전:** 기준은 Unity 6.3 LTS입니다. USS 속성인지는 Unity 공식 속성표(6.6까지)로 판정하고, 6.7은 LTS가 나올 때까지 지원하지 않습니다. [지원 범위 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/supported.md)
+- **맞지 않는 곳은 조용히 넘기지 않고 경고로 알립니다.** 지원하지 않는 컨트롤·속성·값은 이유와 함께, 측정한 경우에는 Unity가 대신 어떻게 하는지까지 경고로 돌아옵니다. [경고 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.md#경고)
+
+## 쓰는 방법 세 가지
+
+| 이런 분이라면 | 이것을 |
+|---|---|
+| **화면을 디자인한다** | 브라우저의 [놀이터](https://reuhomi.github.io/uxml-preview/), 또는 프로젝트 파일 옆에서 [UXML Preview for VS Code](https://github.com/ReuHomi/vscode-uxml-preview) |
+| **AI 에이전트에게 UI를 맡긴다** | [uxml-author](https://github.com/ReuHomi/uxml-author) — UXML/USS를 쓰고, 이 라이브러리로 그려 결과를 확인한 뒤 넘겨주는 스킬 |
+| **도구를 만든다** | 이 라이브러리: `npm install uxml-preview`, 그다음 [API](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.md) |
+
+## 설치
+
+```bash
+npm install uxml-preview
+```
+
+도구 쪽은 Node 22 이상입니다. 그리려면 DOM이 필요합니다(브라우저, 또는 테스트에서는
+happy-dom·jsdom).
+
+```ts
+import { loadLayoutEngine, parse, render, serialize } from 'uxml-preview';
+
+await loadLayoutEngine();                 // Yoga는 WebAssembly라 처음에 한 번 불러온다
+
+const doc = parse(uxmlText, ussText);     // 텍스트 → 모델
+const view = render(doc, container, {     // 모델 → 화면
+  size: { width: 1280, height: 720 },     // 창이 아니라 패널 크기
+  resolveAsset: (path, form) => myAssetUrl(path, form),  // project://… → URL, 없으면 null
+});
+
+for (const w of view.warnings) console.log(w.reason ?? w.kind, w.message);
+
+view.dispose();                           // Yoga 노드는 가비지 컬렉션되지 않는다
+const { uxml, uss } = serialize(doc);     // 고치지 않았으면 입력과 바이트 단위로 같다
+```
+
+## 문서
+
+- [USS는 CSS가 아니다](https://github.com/ReuHomi/uxml-preview/blob/main/docs/uss-vs-css.ko.md) — 옮겨 온 스타일시트가 틀어지는 차이들, 예제와 함께
+- [지원 범위](https://github.com/ReuHomi/uxml-preview/blob/main/docs/supported.md) — 컨트롤·속성·상태·버전, 그리고 각각 어디까지 확인했는지
+- [정확도](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.md) — 모든 수치, 잰 방법, 알려진 차이 전부
+- [API](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.md) — `parse`, `render`, `serialize`, 훅, 경고, `classifyVisibility`
+- [변경 기록](https://github.com/ReuHomi/uxml-preview/blob/main/CHANGELOG.md) (영문)
+- [육안 대조](https://github.com/ReuHomi/uxml-preview/blob/main/docs/visual-check.md) — 색과 질감을 Unity와 나란히 놓고 본 1회 기록(2026-08)
+
+## 개발
+
+```bash
+pnpm install
+pnpm dev            # 놀이터
+pnpm test           # 브라우저·Unity 없이 도는 전부
+pnpm test:text      # 텍스트 코호트, 실제 Chromium에서 (docs/accuracy.md)
+pnpm build
+```
+
+Unity 쪽 기준값을 다시 만들려면 Unity가 필요합니다. 절차는
+[정확도](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.md#기준값-만드는-법)에 있습니다.
+
+## 라이선스
+
+Apache-2.0