uxml-preview 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,149 @@
 # Changelog
 
-## 0.3.0 — Unreleased
+## 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
+
+- 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.

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`)이고, 나머지는 경고와 함께 일반 박스로 그립니다.
 > 검증되지 않은 부분은 지원 범위표에 그대로 적어뒀습니다. 쓰시기 전에
 > [아직 검증되지 않은 것](#아직-검증되지-않은-것)을 먼저 봐주세요.
@@ -47,12 +47,26 @@ 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: **548 of 564 element coordinates identical**
-across 33 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).
 
+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-06, over 33 cases and 141 elements:
+Coordinates measured against Unity on 2026-08-12, over 40 layout cases and 169
+elements:
 
 | | |
 |---|---|
-| Cases matching exactly | **31 / 33** |
-| Values within 0.5px | **548 / 564 (97.2%)** |
+| 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
@@ -246,7 +291,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?**
-548 of 564 element coordinates identical against Unity 6000.0.40f1, across 33
+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.
@@ -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
@@ -280,11 +333,23 @@ Apache-2.0
 **Yoga**를 WebAssembly로 그대로 사용하기 때문에, 결과를 "비슷하게 흉내내는" 것이 아니라
 유니티 에디터와 일치시킵니다.
 
-Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아웃 케이스 33개에서
-**요소 좌표 564개 중 548개가 일치**합니다. 어긋난 16개 중 **10개는 레이아웃이 아니라
+Unity 6000.0.40f1과 대조한 결과, 실무형 화면을 포함한 레이아웃 케이스 40개에서
+**요소 좌표 676개 중 660개가 일치**합니다. 어긋난 16개 중 **10개는 레이아웃이 아니라
 폰트 메트릭** 차이입니다 — 브라우저는 유니티 폰트 에셋을 잴 수 없습니다.
 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을 미리 볼 수 있나요?**
@@ -414,8 +505,8 @@ pnpm build
 계산이 필요한 값은 고정값으로 풀거나 C#에서 계산해야 합니다.
 
 **유니티와 얼마나 같나요?**
-Unity 6000.0.40f1 기준, 인벤토리 화면 전체를 포함한 레이아웃 케이스 33개에서
-**요소 좌표 564개 중 548개 일치**입니다. 스크린샷이 아니라 좌표를 비교하는데,
+Unity 6000.0.40f1 기준, 인벤토리 화면 전체를 포함한 레이아웃 케이스 40개에서
+**요소 좌표 676개 중 660개 일치**입니다. 스크린샷이 아니라 좌표를 비교하는데,
 유니티가 자기 폰트 에셋으로 글자를 그리기 때문입니다 — 그리고 그 사실 때문에
 불일치 16개 중 **10개가 레이아웃이 아니라 폰트 메트릭**입니다. 전부
 [`docs/accuracy.md`](docs/accuracy.md)에 이름이 적혀 있습니다.
@@ -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';
@@ -37,8 +39,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;
 /**