uxml-preview 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.5.1 — 2026-10-13
+
+A cleanup release: nothing drawn changes except where a Unity dump said it was
+wrong, and things that used to be dropped without a word are now said.
+
+### Behavior changes
+
+- **More warnings.** Raised where there used to be silence: undocumented property
+  names, documented properties this preview does not draw, state pseudo-classes
+  Unity's pseudo-class page does not list (`:selected`, `:first-child`, made-up names), `@media` and
+  `@keyframes` blocks, and `display` values other than `flex`/`none`. A screen
+  that passed silently in 0.5.0 may now list warnings; it is drawn the same.
+- **`reason` and `subject` on `Warning`.** Both optional, both **open sets** —
+  give unknown values a `default` branch. `WarningKind` does not grow and no
+  field was removed. See "For consumers" below.
+- **`engines.node` is `>=22`** (was `>=18`). CI and Pages already ran on 22.
+- A `background-image` that is not an asset reference (`linear-gradient()`)
+  is `unsupported-property` with `reason: 'not-uss'`, no longer
+  `asset-unresolved`, so a host stops looking for a file that cannot exist.
+- Warning text says what the renderer did; facts about Unity moved to
+  `reason`/`subject`. No message points at a source file any more.
+  `:root` keeps `kind: 'version-dependent'` but has `reason: 'matches-unity'`.
+
+- **Every USS property now has one handling path.** Whether a property exists,
+  inherits and is drawn is read from a registry transcribed from Unity's USS
+  property reference (95/99/102 rows for 6000.0/6.3/6.6, checked 2026-10-13).
+  New `unsupported-property` warnings where there used to be silence:
+  - 24 documented properties this preview does not draw (`text-shadow`,
+    `transition*`, `-unity-text-outline*`, `-unity-font`, `all`, ...) —
+    `reason: 'not-rendered'`; properties newer than 6000.0 say so
+    (`filter (Unity 6.3+)`).
+  - any name Unity does not document (`font-family`, `colour`, `transform`,
+    `-unity-foo`, ...) — `reason: 'not-uss'`, with the USS properties to
+    write instead in `subject.replacements` for eleven common CSS names.
+- **Corrected warnings.** `filter`/`backdrop-filter` are USS since 6.3/6.6
+  and are reported as not drawn rather than as non-USS. `gap`, `row-gap`,
+  `column-gap`, `overflow-wrap` and `word-break` are in no Unity USS reference
+  table up to 6.6 and are reported as not USS rather than version-dependent.
+  The reference version is Unity 6.3 LTS; Unity 6.7 (beta) adds some of these
+  and is not supported in this release.
+  `background-size`/`-position`/`-repeat` are in 6000.0 and no longer warn.
+  `aspect-ratio` is reported as a 6.3+ property this preview does not lay out.
+- **`<Bindings>` and `<ui:Columns>` are no longer laid out.** The only
+  change in this release that moves anything drawn, and it moves it to where
+  Unity puts it: dumps on 6000.0.40f1 and 6000.3.25f1 show neither element in
+  the visual hierarchy, while the preview drew each as a zero-height box that
+  shifted `space-between`/`space-around` siblings. Their two
+  `unsupported-control` warnings are replaced by one notice per document
+  that data bindings are not evaluated (`reason: 'not-rendered'`). A
+  `<ui:Column>`'s name still counts toward `duplicate-name-in-tree`, because
+  Unity gives it to the header column it builds.
+- **One warning per declaration.** Property warnings are raised once where
+  the declaration is written, with `at` — including in rules that match
+  nothing — instead of once per element the value reached. An inherited
+  value is never reported again on descendants. Value-level warnings
+  (`width: 2em`, an unresolved image) also collapse to one per declaration.
+  A consumer counting occurrences will count fewer.
+- Inheritance now follows Unity's USS reference table. Five properties that
+  Unity marks inherited and this package did not now inherit:
+  `text-shadow`, `-unity-editor-text-rendering-mode`, `-unity-text-generator`,
+  `-unity-material` (6.3+) and `-unity-text-auto-size` (6.3+).
+  `isInherited()` returns `true` for them, and `resolveStyles()` hands them to
+  descendants with an `inherited` origin. Nothing drawn changes: none of the
+  five is drawn by this preview.
+
+### Added
+
+- `WarningReason`, `WarningSubject` types.
+- `USS_STATES` (and `UssState`): the seven states Unity sets, from Unity's
+  pseudo-class page — without `:root` and `:selected`.
+- `TEMPLATE_DEPTH_LIMIT` (32): how deep template expansion goes, for hosts
+  that prefetch template files.
+
+### For consumers
+
+- **Read `subject`, not the message.** The failed URL is `subject.url`, the
+  asset path `subject.path` (with `form`), a refused states key `subject.key`,
+  a property `subject.property`/`value`. Seven message texts consumers match
+  on today are kept byte for byte in this release, but are not an API.
+- **Use `reason` to separate the author's mistakes from the tool's limits.**
+  `not-uss` and `invalid-value` are the author's; `not-rendered` is this
+  preview's; `version-dependent` needs checking; `matches-unity` is not a
+  defect. Failing a screen on every `unsupported-property` would now fail
+  valid USS this preview merely does not draw.
+- **A `not-rendered` warning with `subject.affectsLayout: true` means this
+  preview's coordinates may differ from Unity's.** In that case, do not treat
+  a coordinate-based finding (zero size, overflow) as settled. `affectsLayout`
+  comes from a new registry column judging what each property can do in Unity
+  (box or pixels), kept apart from what this preview does with it.
+  `subject.applied: 'paint'` marks a property drawn here but not laid out as
+  Unity would (`letter-spacing`, `word-spacing`: drawn, left out of text
+  measurement), which now raises a `not-rendered` warning of its own.
+- Replace copied constants with `USS_STATES` and `TEMPLATE_DEPTH_LIMIT`.
+
+### Deferred to 0.6.0
+
+`:enabled` applied automatically, `states` key warnings, the unused
+`unsupported-unit` kind, and value-level checks (`hsl()`, `cubic-bezier()`,
+`space-evenly`, `linear-gradient()` per Unity version, USS-only `cursor`
+values). Listed in `docs/backlog.md`.
+
 ## 0.5.0 — 2026-08-26
 
 ### Known limitations

package/README.md

@@ -25,12 +25,12 @@ stylesheet comes out wrong.</sub>
 npm install uxml-preview
 ```
 
-> **v0.5.0.** Five controls (`VisualElement`, `Label`, `Button`,
+> **v0.5.1.** 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.5.0.** 컨트롤 5종(`VisualElement`, `Label`, `Button`,
+> **v0.5.1.** 컨트롤 5종(`VisualElement`, `Label`, `Button`,
 > `Image`, `ScrollView`)이고, 나머지는 경고와 함께 일반 박스로 그립니다.
 > 검증되지 않은 부분은 지원 범위표에 그대로 적어뒀습니다. 쓰시기 전에
 > [아직 검증되지 않은 것](#아직-검증되지-않은-것)을 먼저 봐주세요.
@@ -124,7 +124,7 @@ 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
+- **Slots are not supported in v0.5.1.** 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,
@@ -406,7 +406,7 @@ Unity 6000.0.40f1에서 살아 있음을 실측했지만 이번 범위 밖이라
 지원 범위는 일부러 보수적으로 적었습니다. 전체 표는
 [`docs/supported.md`](docs/supported.md)에 있습니다.
 
-- **v0.5.0은 슬롯을 지원하지 않습니다.** Unity 6000.0.40f1에서 살아 있음을
+- **v0.5.1은 슬롯을 지원하지 않습니다.** Unity 6000.0.40f1에서 살아 있음을
   실측했지만 슬롯 자식은 배치하지 않고 `template-slot-unsupported`로 보고합니다
 - **`style` AttributeOverride는 적용하지 않습니다.** Unity가 import 과정에서
   무시하는 동작을 따르며, 그럴듯하지만 틀린 결과 대신

package/THIRD-PARTY-NOTICES.md

@@ -53,3 +53,10 @@ SOFTWARE.
 Vite, Vitest, TypeScript, jsdom, pixelmatch and pngjs are development
 dependencies. They are not redistributed in either artifact above, so they carry
 no notice obligation here.
+
+## Test fixtures in the source repository
+
+`tests/fixtures/external/` holds UXML and USS files from six open-source Unity
+projects (MIT, and one Unlicense), used only as test input. They are not in the
+npm package or the site. Each source's licence file sits in its folder, and
+`tests/fixtures/external/README.md` lists the origins.

package/dist/index.d.ts

@@ -7,8 +7,8 @@ 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, WarningKindMap, Warning, UxmlDocument, StyleOrigin, } from './model/types';
-export { collectDependencies, expandTemplates } from './template/expand';
+export type { Span, SourceRef, NodeId, ElementName, Attribute, ElementSpans, ElementNode, Combinator, SimpleSelector, SelectorPart, Selector, Declaration, Rule, SheetItem, StyleSheet, WarningKind, WarningKindMap, WarningReason, WarningSubject, Warning, UxmlDocument, StyleOrigin, } from './model/types';
+export { collectDependencies, expandTemplates, TEMPLATE_DEPTH_LIMIT } 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';
@@ -19,6 +19,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 { USS_STATES } from './style/registry';
+export type { UssState } from './style/registry';
 export { KNOWN_DIVERGENCES } from './known-divergences';
 export type { KnownDivergence } from './known-divergences';
 /**
@@ -143,13 +145,4 @@ export interface RenderResult {
      */
     dispose(): void;
 }
-/**
- * Purpose:      draw a document into a container element.
- * Deps/Effects: replaces the container's children and allocates Yoga nodes.
- *               Call `dispose()` on the result before rendering again.
- * Requires:     `await loadLayoutEngine()` once, first. Yoga is WebAssembly and
- *               cannot be loaded synchronously; keeping that await out here is
- *               what lets this function stay synchronous, which the playground
- *               and the golden tests both want.
- */
 export declare function render(doc: UxmlDocument, container: HTMLElement, options?: RenderOptions): RenderResult;