uxml-preview 0.5.0 → 0.6.0

package/dist/layout/yoga.d.ts

@@ -1,5 +1,6 @@
 import { ElementNode, NodeId, Warning } from '../model/types';
-import { ComputedStyle } from '../style/resolve';
+import { ComputedStyle, DeclarationLocator } from '../style/resolve';
+import { FaceInfo } from '../render/measure';
 /**
  * Purpose:      load the Yoga WebAssembly module.
  * Deps/Effects: caches the module; awaiting it more than once is harmless.
@@ -26,9 +27,19 @@ export interface TextContext {
     /** `normal` | `bold` | `italic` | `bold-and-italic`. */
     fontStyle: string;
     whiteSpace: string;
+    fontFamily?: string;
+    faceInfo?: FaceInfo;
+    letterSpacing?: number;
+    wordSpacing?: number;
+    paragraphSpacing?: number;
+    textGenerator?: 'standard' | 'advanced';
 }
 export type MeasureText = (text: string, context: TextContext, availableWidth: number) => TextMetrics;
 export interface LayoutOptions {
+    fonts?: ReadonlyMap<ComputedStyle, {
+        family: string;
+        faceInfo?: FaceInfo;
+    }>;
     size: {
         width: number;
         height: number;
@@ -41,6 +52,8 @@ export interface LayoutOptions {
      * accuracy if the measurement shifts underneath it.
      */
     measureText: MeasureText;
+    /** Points a value-level warning at the declaration it came from. */
+    locate?: DeclarationLocator;
 }
 /**
  * A laid-out element the file never mentioned, built by a control.

package/dist/model/types.d.ts

@@ -1,3 +1,4 @@
+import { UssVersion } from '../style/registry';
 /**
  * uxml-preview — in-memory document model.
  *
@@ -32,6 +33,8 @@ export type SourceRef = {
     in: 'uss';
     sheet: number;
     span: Span;
+    url?: string | null;
+    from?: string | null;
 };
 /**
  * Opaque handle to a node, stable for the lifetime of the document.
@@ -235,6 +238,91 @@ export type WarningKind = 'unsupported-control' | 'unsupported-property' | 'unsu
 export type WarningKindMap<T> = {
     [K in WarningKind]: T;
 };
+/**
+ * Why a support warning was raised — what a consumer acts on instead of the
+ * message text.
+ *
+ *   - `not-uss`           the author wrote something USS does not have
+ *   - `not-rendered`      valid USS/UXML this preview does not draw or apply
+ *   - `font-fallback`     drawn, but Unity draws some glyphs with a fallback font, so text size can differ
+ *   - `invalid-value`     a valid name with a value or target that cannot work
+ *   - `version-dependent` the result depends on the Unity version
+ *   - `matches-unity`     ignored, and Unity ignores it too; not a defect
+ *
+ * **An open set.** New reasons may be added in a minor release, so a consumer
+ * must give unknown values a default branch rather than an exhaustive switch.
+ * Absent when none applies, e.g. malformed text or a file the host could not
+ * resolve.
+ */
+export type WarningReason = 'not-uss' | 'not-rendered' | 'font-fallback' | 'invalid-value' | 'version-dependent' | 'matches-unity';
+/**
+ * What a warning is about, as data, so a consumer never has to parse it back
+ * out of `message`.
+ *
+ * **An open set**, like `WarningReason`: new variants may be added in a minor
+ * release, so switch on `kind` with a default branch.
+ */
+export type WarningSubject = {
+    kind: 'property';
+    property: string;
+    /** As written, before `var()` substitution where the warning is about the declaration. */
+    value?: string;
+    /** First Unity version whose USS reference lists the property, e.g. `"6000.3"`. */
+    since?: string;
+    /** USS properties to write instead, for a CSS name USS spells differently. */
+    replacements?: readonly string[];
+    /**
+     * On a `not-rendered` or `font-fallback` warning: whether the property can change a box's size
+     * or position in Unity. When true, this preview's coordinates may differ
+     * from Unity's — do not treat a coordinate-based finding (zero size,
+     * overflow) as settled.
+     */
+    affectsLayout?: boolean;
+    /**
+     * On a `not-rendered` warning: the part this preview did apply, when it
+     * applied some. Reserved for a property drawn but not laid out as Unity
+     * would; no registry row currently uses this field.
+     */
+    applied?: 'paint';
+    /** On a `font-fallback` warning: the script the editor default font (Inter) has no glyphs for. */
+    missingGlyphs?: 'hangul' | 'han' | 'kana';
+    unityEffect?: {
+        kind: 'unstyled-from-here' | 'file-inline-dropped';
+        versions: readonly UssVersion[];
+    };
+} | {
+    kind: 'selector';
+    /** The selector text as written. */
+    selector: string;
+    /** The part of it the warning is about, when narrower than the whole. */
+    fragment?: string;
+} | {
+    kind: 'states-key';
+    key: string;
+    problem?: 'matches-nothing' | 'state-in-key' | 'unknown-state';
+    state?: string;
+} | {
+    kind: 'asset';
+    path: string;
+    form: 'url' | 'resource';
+    role?: 'font';
+} | {
+    kind: 'import';
+    /** Exactly the string the resolver hook was (or would have been) called with. */
+    url: string;
+    from: string | null;
+} | {
+    kind: 'control';
+    type: string;
+} | {
+    kind: 'name';
+    name: string;
+}
+/** An at-rule block, without the `@`. */
+ | {
+    kind: 'at-rule';
+    name: string;
+};
 /**
  * Never a thrown error. One unsupported property must not take down the render
  * (see CLAUDE.md rule 6).
@@ -244,6 +332,10 @@ export type WarningKindMap<T> = {
  */
 export interface Warning {
     kind: WarningKind;
+    /**
+     * For people. Read `reason` and `subject` instead; the text may be
+     * reworded in any release.
+     */
     message: string;
     /** Document URL for a warning originating outside the entry UXML. */
     sourceDocument?: string | null;
@@ -251,6 +343,9 @@ export interface Warning {
     at?: SourceRef;
     /** Element the warning is about, when it has one. Lets the UI highlight it. */
     node?: NodeId;
+    nodes?: NodeId[];
+    reason?: WarningReason;
+    subject?: WarningSubject;
 }
 export interface UxmlDocument {
     /** The exact UXML text every tree span indexes into. */

package/dist/render/css-map.d.ts

@@ -1,5 +1,5 @@
 import { NodeId, Warning } from '../model/types';
-import { ComputedStyle } from '../style/resolve';
+import { ComputedStyle, DeclarationLocator } from '../style/resolve';
 export interface CssMapOptions {
     /**
      * `form` tells `url("...")` apart from `resource("...")` — Unity resolves
@@ -11,11 +11,28 @@ export interface CssMapOptions {
      * file happens to sit alongside it — or resolves nothing at all.
      */
     resolveAsset?: ((path: string, form: 'url' | 'resource') => string | null) | undefined;
+    /** Points a value-level warning at the declaration it came from. */
+    locate?: DeclarationLocator | undefined;
 }
 export interface CssMapResult {
     declarations: Record<string, string>;
     warnings: Warning[];
 }
+/**
+ * `url("project://...")` or `resource("...")` to its form and bare path.
+ *
+ * Deps/Effects: decodes XML entities before parsing the wrapper. A value from
+ * a `<Style src>`-loaded .uss file never has any (that file was never XML),
+ * but a value from an inline `style="…"` attribute is parsed straight from
+ * the raw XML source (`inlineDeclarations` in style/resolve.ts) and can still
+ * carry `&apos;`/`&amp;`/`&quot;`. Decoding after the regex would be too late:
+ * `&apos;` doesn't match `(["']?)`, so the quote wrapper would be read as part
+ * of the path instead of stripped from it.
+ */
+export declare function assetPath(value: string): {
+    form: 'url' | 'resource';
+    path: string;
+} | null;
 /**
  * Purpose:      one element's computed style -> CSS declarations.
  * Deps/Effects: calls `resolveAsset` for background images; warnings are

package/dist/render/fonts.d.ts

@@ -0,0 +1,21 @@
+import { NodeId, Warning } from '../model/types';
+import { ComputedStyle, DeclarationLocator } from '../style/resolve';
+import { FaceInfo } from './measure';
+export type ResolvedFont = {
+    family: string;
+    faceInfo?: FaceInfo;
+};
+export type ResolveFont = (path: string, form: 'url' | 'resource') => string | ResolvedFont | null;
+/**
+ * Purpose:      resolve font assets for measurement and painting, applying Unity's
+ *               documented but unmeasured -unity-font-definition precedence.
+ * Deps/Effects: calls the host hook once per distinct (path, form) per invocation.
+ * Ensures:      filters only not-rendered property warnings for processed font
+ *               declarations, keyed by property, source document and offset
+ *               (or node when no offset exists). Unresolved assets replace those
+ *               warnings with one asset-unresolved warning per declaration.
+ */
+export declare function resolveFonts(styles: ReadonlyMap<NodeId, ComputedStyle>, warnings: readonly Warning[], locate: DeclarationLocator, resolve?: ResolveFont): {
+    fonts: Map<ComputedStyle, ResolvedFont>;
+    warnings: Warning[];
+};

package/dist/render/measure.d.ts

@@ -1,4 +1,13 @@
 import { MeasureText } from '../layout/yoga';
+export interface FaceInfo {
+    pointSize: number;
+    ascentLine: number;
+    descentLine: number;
+    lineHeight?: number;
+}
+export declare const EDITOR_DEFAULT_FACE_INFO: FaceInfo;
+export declare function textHeight(lines: number, fontSize: number, face: FaceInfo, paragraphBreaks?: number, paragraphSpacing?: number): number;
+export declare function fontList(family?: string): string;
 /**
  * Purpose:      measure text with a canvas when one is available.
  * Deps/Effects: creates one offscreen canvas and reuses it.

package/dist/render/paint.d.ts

@@ -1,3 +1,4 @@
+import { FaceInfo } from './measure';
 import { ElementNode, NodeId, Warning } from '../model/types';
 import { ComputedStyle } from '../style/resolve';
 import { LayoutBox, LayoutPart } from '../layout/yoga';
@@ -22,6 +23,10 @@ export interface PaintResult {
 }
 export interface PaintOptions extends CssMapOptions {
     document: Document;
+    fonts?: ReadonlyMap<ComputedStyle, {
+        family: string;
+        faceInfo?: FaceInfo;
+    }>;
 }
 /**
  * Purpose:      build the DOM for one laid-out document under `container`.

package/dist/render/values.d.ts

@@ -36,6 +36,10 @@ export interface LengthResult {
     length: Length | null;
     /** Set when the text names a unit USS does not support, or uses calc(). */
     problem?: string;
+    /** Structured marker for a recognised but unsupported USS unit. */
+    code?: 'unsupported-unit';
+    /** Set with `problem`: USS lacks the syntax, or the value is simply unreadable. */
+    reason?: 'not-uss' | 'invalid-value';
 }
 /**
  * Purpose:      `"6px"` / `"50%"` / `"auto"` / `"0"` -> a number with a unit.

package/dist/render/visibility.d.ts

@@ -0,0 +1,20 @@
+import { RenderResult } from '../index';
+import { NodeId, StyleOrigin } from '../model/types';
+export type Visibility = {
+    kind: 'shown';
+} | {
+    kind: 'hidden';
+    by: NodeId;
+    origin: StyleOrigin;
+} | {
+    kind: 'emptied';
+} | {
+    kind: 'collapsed';
+    explicitZero: boolean;
+};
+/**
+ * Purpose:      classify layout absence using the uxml-author 0.2.1 rules.
+ * Deps/Effects: pure; reads the expanded tree and computed styles from render.
+ * Ensures:      every box has a verdict; opacity and visibility do not affect it.
+ */
+export declare function classifyVisibility(result: RenderResult): ReadonlyMap<NodeId, Visibility>;

package/dist/style/registry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Every USS property Unity documents, and what this renderer does with it.
+ *
+ * Transcribed from Unity's USS property reference, not reasoned from CSS. The
+ * renderer's first failure mode is assuming a CSS name or default carries over,
+ * and a hand-kept list per concern (inherited, unsupported, version-dependent)
+ * had already drifted three ways: `text-shadow` missing from inheritance,
+ * `filter` reported as non-USS after 6.3 added it, `gap` reported as
+ * version-dependent although no reference table up to 6.6 has it.
+ *
+ * Source (checked 2026-10-13, see `USS_PROPERTY_SOURCE`):
+ *   https://docs.unity.com/en-us/engine/6000.0/manual/uitoolkits/uielements/uie-uss/properties/reference  (95 rows)
+ *   https://docs.unity.com/en-us/engine/6000.3/manual/uitoolkits/uielements/uie-uss/properties/reference  (99 rows)
+ *   https://docs.unity.com/en-us/engine/6000.6/manual/uitoolkits/uielements/uie-uss/properties/reference (102 rows)
+ *
+ * `since` and `inherited` are Unity's facts and come from those tables alone.
+ * `handling` is this renderer's fact, observed rather than declared: `layout`
+ * means it can move a box (src/layout/yoga.ts), `paint` means it changes what
+ * is drawn and never where (src/render/css-map.ts), `none` means nothing
+ * reads it. A row's handling may only change together with the code —
+ * tests/style/registry.test.ts renders every row and fails when the two
+ * disagree.
+ */
+/** The first Unity release whose reference table lists the property. */
+export type UssVersion = '6000.0' | '6000.3' | '6000.6';
+export type Handling = 'layout' | 'paint' | 'none';
+/** What a property can change in Unity: a box's size or position, only pixels, or nothing in a settled frame. */
+export type UnityEffect = 'layout' | 'paint' | 'none';
+export interface UssProperty {
+    readonly name: string;
+    readonly since: UssVersion;
+    /** Unity's "Inherited" column. */
+    readonly inherited: boolean;
+    /** What THIS renderer does with it. Observed; see the header. */
+    readonly handling: Handling;
+    /**
+     * What it can do IN UNITY — a different question from `handling`, and the
+     * two must not be read for each other. Where they disagree (`unity: 'layout'`
+     * with `handling` other than `'layout'`), this preview's coordinates can
+     * differ from Unity's whenever the property is written.
+     */
+    readonly unity: UnityEffect;
+    /** Why `unity` is what it is, in one line. */
+    readonly basis: string;
+    /** True when `basis` is reasoning rather than a Unity statement or a measurement. */
+    readonly inferred: boolean;
+}
+export declare const USS_PROPERTY_SOURCE: {
+    readonly checked: "2026-10-13";
+    readonly tables: {
+        readonly '6000.0': "https://docs.unity.com/en-us/engine/6000.0/manual/uitoolkits/uielements/uie-uss/properties/reference";
+        readonly '6000.3': "https://docs.unity.com/en-us/engine/6000.3/manual/uitoolkits/uielements/uie-uss/properties/reference";
+        readonly '6000.6': "https://docs.unity.com/en-us/engine/6000.6/manual/uitoolkits/uielements/uie-uss/properties/reference";
+    };
+    /** Row count of each table on the date above. A test holds the data to these. */
+    readonly counts: {
+        readonly '6000.0': 95;
+        readonly '6000.3': 99;
+        readonly '6000.6': 102;
+    };
+};
+export declare const USS_PROPERTIES: readonly UssProperty[];
+/** Undefined for anything Unity does not document, custom properties included. */
+export declare function ussProperty(name: string): UssProperty | undefined;
+/**
+ * CSS names an author porting a stylesheet reaches for, and the USS
+ * properties that do the same job.
+ *
+ * Chosen, not exhaustive. The first six are the renamed rows of CLAUDE.md's
+ * "이름이 다른 속성" table and docs/uss-reference.md; the rest are CSS
+ * shorthands or per-axis splits whose every part USS has under another name.
+ * A CSS property with no USS counterpart up to Unity 6.6 (`z-index`, `box-shadow`, `gap`) is
+ * deliberately absent — offering a replacement there would invent one.
+ */
+export declare const CSS_REPLACEMENTS: Readonly<Record<string, readonly string[]>>;
+export interface PropertyWarning {
+    message: string;
+    reason: 'not-uss' | 'not-rendered' | 'invalid-value';
+    subject: {
+        kind: 'property';
+        property: string;
+        value: string;
+        since?: string;
+        replacements?: readonly string[];
+        affectsLayout?: boolean;
+        applied?: 'paint';
+        unityEffect?: {
+            kind: 'unstyled-from-here';
+            versions: readonly UssVersion[];
+        };
+    };
+}
+/**
+ * Purpose:      what a declaration warrants by its property name alone.
+ * Ensures:      null for custom properties and for anything this renderer
+ *               reads; a value-level problem is the reader's to report.
+ *
+ * Judged per declaration rather than per element, so a rule matching a
+ * hundred elements — or matching none — says it once, and an inherited value
+ * never says it again on every descendant.
+ */
+export declare function propertyWarning(property: string, value: string): PropertyWarning | null;
+/**
+ * The pseudo-class states a Unity element can be in — what `states` and
+ * `activeStates` accept and what a USS state selector can match.
+ *
+ * From Unity's "USS selectors: Pseudo-classes" page (checked 2026-10-13):
+ * https://docs.unity3d.com/Manual/UIE-USS-Selectors-Pseudo-Classes.html
+ * `:root` is excluded because it names a place in the tree, not a state.
+ * `:selected` is excluded because that page says USS does not support it
+ * ("Use :checked instead"). Exported so consumers stop keeping their own copy.
+ */
+export declare const USS_STATES: readonly ["hover", "active", "inactive", "focus", "disabled", "enabled", "checked"];
+export type UssState = (typeof USS_STATES)[number];

package/dist/style/resolve.d.ts

@@ -30,6 +30,8 @@ export interface ResolveOptions {
     states?: Readonly<Record<string, readonly string[]>>;
 }
 export interface ResolveResult {
+    /** @internal Element matches collected during this cascade, keyed by sheet and item. */
+    matchedNodes: ReadonlyMap<string, readonly NodeId[]>;
     styles: ReadonlyMap<NodeId, ComputedStyle>;
     /**
      * Style per control part, keyed by the owning element and then Unity's name
@@ -72,6 +74,21 @@ export interface Candidate {
     order: number;
     winner: boolean;
 }
+/** Derives the resolver request without adding importer state to the model. */
+export declare function sheetLocation(doc: UxmlDocument, index: number): {
+    url: string | null;
+    from: string | null;
+};
+/** Where a computed value was written, as warning fields. */
+export type DeclarationLocator = (origin: StyleOrigin) => Pick<Warning, 'at' | 'sourceDocument' | 'nodes'>;
+/**
+ * Purpose:      turn a computed value's origin back into the text it came from,
+ *               so a value-level warning points at one declaration.
+ * Ensures:      empty for inherited and built-in values — an inherited value is
+ *               reported where it was declared, not on every descendant — and
+ *               for a template's inline style, which names its file instead.
+ */
+export declare function declarationLocator(doc: UxmlDocument, nodes: ReadonlyMap<string, readonly NodeId[]>): DeclarationLocator;
 /**
  * Purpose:      compute the style of every element in the document.
  * Deps/Effects: reads `doc` only; nothing on the model is mutated.

package/dist/template/expand.d.ts

@@ -16,6 +16,16 @@ export interface TemplateExpansion {
     document: UxmlDocument;
     warnings: readonly Warning[];
 }
+/**
+ * How deeply `<ui:Instance>` may nest before expansion stops with
+ * `template-depth-exceeded`.
+ *
+ * Exported so a host that prefetches template files can walk exactly as deep
+ * as the core will expand, instead of copying the number and drifting (the
+ * VS Code extension's prefetch used 16 while the core went to 32). Not a
+ * Unity limit — a bound on this renderer's work.
+ */
+export declare const TEMPLATE_DEPTH_LIMIT = 32;
 /**
  * Expand all instances in a document into a derived tree.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "uxml-preview",
-  "version": "0.5.0",
-  "description": "Preview Unity UI Toolkit UXML/USS in a browser without the Unity Editor. Uses Yoga (WebAssembly), the same layout engine UI Toolkit uses: 660 of 676 element coordinates identical to Unity 6. Parses and writes files back byte-for-byte.",
+  "version": "0.6.0",
+  "description": "Render Unity UI Toolkit UXML/USS in a browser without the Unity Editor. Laid out by Yoga, the engine UI Toolkit uses; reference Unity 6.3 LTS, measured against real Unity. Byte-exact round trips.",
   "keywords": [
     "unity",
     "unity3d",
@@ -46,7 +46,7 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
@@ -67,6 +67,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:roundtrip": "vitest run tests/roundtrip",
+    "test:text": "node tests/text-cohort/run.mjs && node tests/text-cohort/paint.mjs",
     "test:golden": "vitest run tests/golden --passWithNoTests",
     "golden:emit": "node --experimental-strip-types --no-warnings scripts/emit-golden-cases.mjs",
     "template:emit": "node --experimental-strip-types --no-warnings scripts/emit-template-cases.mjs",
@@ -82,6 +83,7 @@
     "@types/node": "^22.0.0",
     "jsdom": "^30.0.1",
     "pixelmatch": "^6.0.0",
+    "playwright-core": "1.48.2",
     "pngjs": "^7.0.0",
     "typescript": "^5.6.0",
     "vite": "^6.0.0",