uxml-preview 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.5.0 — 2026-08-26
+
+### Known limitations
+
+- Slots are deliberately unsupported this release. **Slots — measured alive in
+  6000.0.40f1. Out of this release scope and reported with
+  `template-slot-unsupported`.** Slot children are not placed in an arbitrary
+  location.
+- A `style` AttributeOverride is reported as `override-style-ignored` and is not
+  applied, matching Unity's import behavior.
+- Runtime `binding-path`, C# `makeItem`-selected `ListView`/`TreeView` item
+  templates, per-instance pseudo-state control, cyclic-graph truncation,
+  template editing, automatic extraction, and UI Builder reproduction remain
+  outside the viewer-core scope.
+- The external 14-document sample is not broad template validation: only **1
+  document uses `<ui:Template>`**. Its former **31 → 0** figure counted
+  diagnostic lines — 1 Template declaration + 15 Instances + 15
+  AttributeOverrides — not 31 opened subtrees.
+- An embedded package UXML physically present at
+  `<projectRoot>/Packages/<name>/` resolves through
+  `project://database/Packages/...`, as measured in Unity 6000.0.40f1. The core
+  and host still do not search `Library/PackageCache`; a registry-package
+  template available only there reports `package-path-not-searched`.
+
+### Added
+
+- **Template / Instance expansion.** `<ui:Template>` declarations are resolved
+  through the existing `resolveImport(url, from)` host hook, and
+  `<ui:Instance>` expands to an opaque `TemplateContainer`. Instance `name`,
+  `class`, and inline `style` attach to that container; nested expansion is
+  capped at 32 levels.
+- `collectDependencies(source)` returns template `src` URLs in source order so a
+  synchronous host can prefetch the transitive input before rendering.
+- `WarningKindMap<T>` is exported so consumers can make their diagnostic
+  classifier exhaustive.
+- `AttributeOverrides` reaches every duplicate `element-name` target and reports
+  `override-target-missing` with the requested and available names when it finds
+  none. A `style` override reports `override-style-ignored` with the target name
+  and value; Unity ignores it during import, so it is not applied. Template source
+  provenance is kept separate from the derived render tree.
+- The public `WarningKind` union grows from **8 to 17**. Consumers must update
+  their warning classifiers. The nine new template diagnostics are:
+  `template-src-unresolved`, `template-not-declared`, `template-cycle`,
+  `template-depth-exceeded`, `override-target-missing`,
+  `duplicate-name-in-tree`, `package-path-not-searched`,
+  `template-slot-unsupported`, and `override-style-ignored`.
+
+### Changed
+
+- Template stylesheet attachments remain scoped to the generated
+  `TemplateContainer` subtree. `Packages/...` is declaring-document-relative;
+  an embedded package UXML physically present at
+  `<projectRoot>/Packages/<name>/` resolves through the project-root-fixed
+  `project://database/Packages/...` form, as measured in Unity 6000.0.40f1.
+  `Library/PackageCache` is not searched, so a registry-package template
+  available only there reports `package-path-not-searched`.
+- Cyclic templates fail closed with the complete cycle path. The source AST is
+  still round-tripped unchanged; expansion exists only in the render tree.
+
+### Verified
+
+- Unity 6000.0.40f1 template cohort: **200 / 220 coordinate values**, 55
+  elements, and 11 rendered cases with 11/11 rendered baselines. The 20
+  mismatches classify as (a) known font/text metrics 20, (b) 1px 0, and (c) new
+  cause 0; axes are height 14, width 4, x 1, y 1.
+- G3-11 has no layout baseline because Unity `CloneTree` overflows the stack on
+  the cyclic input; the preview reports `template-cycle` and fails closed.
+- This cohort is separate from the v0.4.0 base-control figure of **660 / 676**
+  for 169 elements. The figures are not combined.
+
 ## 0.4.0 — 2026-08-12
 
 ### Added

package/README.md

@@ -25,12 +25,12 @@ stylesheet comes out wrong.</sub>
 npm install uxml-preview
 ```
 
-> **v0.2.0 — early release.** Five controls (`VisualElement`, `Label`, `Button`,
+> **v0.5.0.** 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`,
+> **v0.5.0.** 컨트롤 5종(`VisualElement`, `Label`, `Button`,
 > `Image`, `ScrollView`)이고, 나머지는 경고와 함께 일반 박스로 그립니다.
 > 검증되지 않은 부분은 지원 범위표에 그대로 적어뒀습니다. 쓰시기 전에
 > [아직 검증되지 않은 것](#아직-검증되지-않은-것)을 먼저 봐주세요.
@@ -53,6 +53,20 @@ 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).
 
+This changes what you can open: **you can now open real screens made by someone
+else**, including screens assembled from reusable UXML parts rather than one
+self-contained file. `<ui:Template>` declarations and `<ui:Instance>` elements
+are expanded for rendering. The template cohort is measured separately:
+**200 / 220 coordinate values across 55 elements and 11 rendered cases**; it is
+not added to the base 660/676 figure. Cycles fail closed with a diagnostic, and
+slots are measured as alive in Unity 6000.0.40f1 but remain out of scope and
+report `template-slot-unsupported`.
+
+This is not a claim that every external sample exercises templates: only **1 of
+14** external documents uses `<ui:Template>`. The reported 31 → 0 improvement
+there counts diagnostic lines (1 declaration + 15 instances + 15 overrides),
+not 31 opened subtrees.
+
 ```
 .uxml + .uss  →  parse  →  style resolve  →  Yoga layout  →  DOM paint
                                                                   ↓
@@ -99,7 +113,9 @@ That broken feedback loop is what this library fixes.
 | 5 | Golden tests against Unity | ✅ |
 | 6 | **v0.1 release** | ✅ |
 | 7 | **v0.2 — ScrollView, Image, states, a measured screen** | ✅ |
-| 8+ | Editing layer, tool integration | ⬜ |
+| 8 | **v0.3–0.4 — asset/import resolution semantics, Unity CLI measurement** | ✅ |
+| 9 | **v0.5 — Template / Instance expansion and diagnostics** | ✅ |
+| 10+ | Editing layer, tool integration | ⬜ |
 
 Full plan: [`docs/ROADMAP.md`](docs/ROADMAP.md)
 
@@ -108,6 +124,18 @@ 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.
 
+- **Slots are not supported in v0.5.0.** They were measured alive in Unity
+  6000.0.40f1; slot children are not placed and `template-slot-unsupported` is
+  reported.
+- **A `style` AttributeOverride is not applied.** Unity ignores it during import,
+  and the preview reports `override-style-ignored` instead of drawing a plausible
+  but wrong result.
+- **`Library/PackageCache` is not searched.** Embedded package UXML physically
+  present under `<projectRoot>/Packages/<name>/` resolves through
+  `project://database/Packages/...`; a registry-package template available only
+  in the cache reports `package-path-not-searched`.
+- **The external 14-document sample contains only 1 template document.** Its
+  31 → 0 result counts diagnostic lines, not rendered template subtrees.
 - **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
@@ -143,7 +171,8 @@ const doc = parse(uxmlText, ussText);
 
 // model → screen
 const view = render(doc, document.getElementById('preview'), {
-  resolveAsset: (path) => myAssetUrlFor(path),
+  resolveAsset: (path, form) =>
+    form === 'url' ? myAssetUrlFor(path) : myResourcesAssetUrlFor(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.
@@ -158,6 +187,20 @@ view.dispose();
 const { uxml, uss } = serialize(doc);
 ```
 
+`form` keeps `url()` and `resource()` distinct. `url()` is a host-defined asset
+path; `resource()` is Unity's Resources lookup, where the extension is optional
+and the folder may occur anywhere under `Assets`. Unity can also resolve editor
+built-ins that a disk-only host cannot, so return `null` rather than treating a
+resource name as an ordinary project path.
+
+For external stylesheets and template `src` files,
+`parse(uxml, uss, { resolveImport: (url, from) => ... })` passes the immediate
+containing URL as `from`. Entry-UXML references receive `null`; nested stylesheet
+imports receive the containing stylesheet URL, and nested template dependencies
+receive the containing UXML URL. Existing one-argument callbacks remain valid; a future third hook
+argument will use an options object instead. `collectDependencies(source)` lists
+template dependency URLs in source order for host prefetching.
+
 ### Playground
 
 **[reuhomi.github.io/uxml-preview](https://reuhomi.github.io/uxml-preview/)** —
@@ -210,12 +253,14 @@ 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-12, over 40 cases and 169 elements:
+Coordinates measured against Unity on 2026-08-12, over 40 layout cases and 169
+elements:
 
 | | |
 |---|---|
 | Cases matching exactly | **38 / 40** |
 | Values within 0.5px | **660 / 676 (97.6%)** |
+| Unity baselines recorded | **41 / 41** (40 coordinate cases + 1 resource observation) |
 
 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
@@ -264,6 +309,14 @@ 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.
 
+**Are templates and instances rendered?**
+Yes. Template declarations resolve through the host import hook, instances become
+opaque `TemplateContainer` elements, and `AttributeOverrides` reach every
+duplicate target for ordinary attributes. A `style` AttributeOverride is reported
+as `override-style-ignored` because Unity ignores it during import. Slot children
+are intentionally not placed; the measured Unity slot behavior is reported as
+`template-slot-unsupported` in this release.
+
 ### License
 
 Apache-2.0
@@ -285,6 +338,18 @@ Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아
 폰트 메트릭** 차이입니다 — 브라우저는 유니티 폰트 에셋을 잴 수 없습니다.
 16개 전부 [`docs/accuracy.md`](docs/accuracy.md)에 이름과 사유를 적어뒀습니다.
 
+이제 **남이 만든 실제 화면을 열 수 있게 됩니다.** 한 파일에 모든 내용을 넣은
+화면뿐 아니라 재사용 가능한 UXML 조각을 조립한 화면도 `<ui:Template>`과
+`<ui:Instance>`를 전개해 렌더링합니다. 템플릿 코호트는 기본 수치와 분리해
+**55 elements, 11개 렌더 케이스의 좌표 220개 중 200개**로 측정했으며
+660/676에 합산하지 않습니다. 순환은 진단과 함께 fail-closed로 막고, 슬롯은
+Unity 6000.0.40f1에서 살아 있음을 실측했지만 이번 범위 밖이라
+`template-slot-unsupported`로 보고합니다.
+
+외부 14개 표본 전체가 템플릿을 검증한 것은 아닙니다. 그중 `<ui:Template>`을
+쓰는 문서는 **1개**뿐이고, 보고된 31 → 0은 열린 서브트리 수가 아니라 진단
+줄 수(선언 1 + Instance 15 + override 15)입니다.
+
 ```
 .uxml + .uss  →  파싱  →  스타일 계산  →  Yoga 레이아웃  →  DOM 페인팅
                                                                   ↓
@@ -330,7 +395,9 @@ Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아
 | 5 | 유니티 대조 골든 테스트 | ✅ |
 | 6 | **v0.1 공개** | ✅ |
 | 7 | **v0.2 — ScrollView·Image·상태, 대표 화면 대조** | ✅ |
-| 8+ | 편집 레이어, 도구 통합 | ⬜ |
+| 8 | **v0.3–0.4 — 에셋·import 해석 의미론, Unity CLI 계측** | ✅ |
+| 9 | **v0.5 — Template / Instance 전개와 진단** | ✅ |
+| 10+ | 편집 레이어, 도구 통합 | ⬜ |
 
 전체 계획: [`docs/ROADMAP.md`](docs/ROADMAP.md)
 
@@ -339,6 +406,17 @@ Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아
 지원 범위는 일부러 보수적으로 적었습니다. 전체 표는
 [`docs/supported.md`](docs/supported.md)에 있습니다.
 
+- **v0.5.0은 슬롯을 지원하지 않습니다.** Unity 6000.0.40f1에서 살아 있음을
+  실측했지만 슬롯 자식은 배치하지 않고 `template-slot-unsupported`로 보고합니다
+- **`style` AttributeOverride는 적용하지 않습니다.** Unity가 import 과정에서
+  무시하는 동작을 따르며, 그럴듯하지만 틀린 결과 대신
+  `override-style-ignored`를 보고합니다
+- **`Library/PackageCache`는 탐색하지 않습니다.**
+  `<projectRoot>/Packages/<name>/`에 실물이 있는 embedded package UXML은
+  `project://database/Packages/...`로 해석하지만, 캐시에만 있는 레지스트리 패키지
+  템플릿은 `package-path-not-searched`로 보고합니다
+- **외부 14개 표본 중 템플릿 문서는 1개뿐입니다.** 31 → 0은 렌더된 템플릿
+  서브트리가 아니라 진단 줄 수입니다
 - **자동 대조는 좌표만, 그것도 Yoga 층까지입니다.** 위 수치는 레이아웃 엔진이 낸
   좌표를 잰 것입니다. 그려진 DOM이 그 좌표를 재현하는지는 유니티가 아니라 자체
   불변식 검사로 봅니다
@@ -396,6 +474,19 @@ pnpm build
 정확도 수치를 재현하려면 유니티가 필요합니다. 절차는
 [`docs/accuracy.md`](docs/accuracy.md)에 있습니다.
 
+### API
+
+`render` 옵션의 `resolveAsset(path, form)`에서 `form`은 `'url' | 'resource'`입니다.
+`url()`은 호스트의 에셋 경로이고 `resource()`는 Unity Resources 검색입니다. 후자는
+확장자 없이 쓸 수 있고 Resources 폴더가 `Assets` 아래 어디에나 있을 수 있으며, 에디터
+내장 리소스처럼 프로젝트 디스크만 보는 호스트가 풀 수 없는 값도 있으므로 그때는 `null`을
+반환해야 합니다. 외부 스타일시트와 템플릿 `src`는
+`parse(uxml, uss, { resolveImport: (url, from) => ... })`로 읽습니다. 엔트리 UXML의
+참조는 `from: null`, 중첩 stylesheet import는 부모 stylesheet URL, 중첩 템플릿
+의존성은 부모 UXML URL을 받습니다. 기존 한 인자 콜백은 계속 동작합니다.
+`collectDependencies(source)`는 호스트가
+미리 가져올 템플릿 의존 URL을 소스 순서대로 돌려줍니다.
+
 ### 이런 질문에 답합니다
 
 **유니티를 켜지 않고 UXML을 미리 볼 수 있나요?**
@@ -430,6 +521,13 @@ Unity 6000.0.40f1 기준, 인벤토리 화면 전체를 포함한 레이아웃
 자기 스타일과 자식은 정상적으로 나오며 그 컨트롤 고유의 모양만 빠집니다. 모르는 태그
 하나 때문에 화면 전체가 죽지 않고, 조용히 사라지는 것도 없습니다.
 
+**템플릿과 인스턴스도 렌더링하나요?**
+네. 템플릿 선언은 호스트 import 훅으로 해석하고, 인스턴스는 불투명한
+`TemplateContainer`로 전개하며, `AttributeOverrides`는 같은 이름의 모든 대상에
+일반 속성을 적용합니다. `style` AttributeOverride는 Unity가 import에서 무시하므로
+`override-style-ignored`로 보고하고 적용하지 않습니다. 슬롯 자식은 이번 릴리스에서
+배치하지 않고 `template-slot-unsupported` 진단으로 보고합니다.
+
 ### 라이선스
 
 Apache-2.0

package/dist/index.d.ts

@@ -7,7 +7,9 @@ import { LayoutBox, MeasureText } from './layout/yoga';
  * below are still signatures only; implementations land in Phases 2–4.
  * See docs/ROADMAP.md.
  */
-export type { Span, SourceRef, NodeId, ElementName, Attribute, ElementSpans, ElementNode, Combinator, SimpleSelector, SelectorPart, Selector, Declaration, Rule, SheetItem, StyleSheet, WarningKind, Warning, UxmlDocument, StyleOrigin, } from './model/types';
+export type { Span, SourceRef, NodeId, ElementName, Attribute, ElementSpans, ElementNode, Combinator, SimpleSelector, SelectorPart, Selector, Declaration, Rule, SheetItem, StyleSheet, WarningKind, WarningKindMap, Warning, UxmlDocument, StyleOrigin, } from './model/types';
+export { collectDependencies, expandTemplates } from './template/expand';
+export type { TemplateExpansion, TemplateResolver } from './template/expand';
 export { loadLayoutEngine, isLayoutEngineReady, liveNodeCount } from './layout/yoga';
 export type { LayoutBox, MeasureText, TextContext, TextMetrics } from './layout/yoga';
 export { createDefaultMeasureText } from './render/measure';