uxml-preview 0.4.0 → 0.5.1

package/dist/layout/yoga.d.ts

@@ -1,5 +1,5 @@
 import { ElementNode, NodeId, Warning } from '../model/types';
-import { ComputedStyle } from '../style/resolve';
+import { ComputedStyle, DeclarationLocator } from '../style/resolve';
 /**
  * Purpose:      load the Yoga WebAssembly module.
  * Deps/Effects: caches the module; awaiting it more than once is harmless.
@@ -41,6 +41,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

@@ -66,6 +66,8 @@ export interface Attribute {
      */
     value: string;
     span: Span;
+    /** Render-only provenance for a cloned/overridden attribute. */
+    sourceDocument?: string | null;
 }
 /**
  * Three spans rather than one, so that an edit stays local.
@@ -111,6 +113,21 @@ export interface ElementNode {
      * synthesized (copy a sibling's leading whitespace).
      */
     childrenDirty: boolean;
+    /**
+     * A render-only node synthesized while a template instance is expanded.
+     * Parsed nodes leave this absent; serialization never sees the derived tree.
+     */
+    derived?: {
+        kind: 'template-container';
+        /** The source `<ui:Instance>` that caused this container to exist. */
+        instance: NodeId;
+    };
+    /** URL of the UXML document that supplied a render-only clone. */
+    sourceDocument?: string | null;
+    /** URL that sourceDocument was resolved from, when it was relative. */
+    sourceDocumentFrom?: string | null;
+    /** Node id inside sourceDocument for a render-only clone. */
+    sourceNode?: NodeId;
 }
 export type Combinator = 'descendant' | 'child';
 /**
@@ -209,9 +226,90 @@ export interface StyleSheet {
      * passed directly to `parse()`. Used in warning messages only.
      */
     origin: string | null;
+    /** Containing URL used to resolve origin in a derived template document. */
+    sourceDocumentFrom?: string | null;
     items: SheetItem[];
 }
-export type WarningKind = 'unsupported-control' | 'unsupported-property' | 'unsupported-selector' | 'unsupported-unit' | 'version-dependent' | 'asset-unresolved' | 'import-unresolved' | 'malformed';
+export type WarningKind = 'unsupported-control' | 'unsupported-property' | 'unsupported-selector' | 'unsupported-unit' | 'version-dependent' | 'asset-unresolved' | 'import-unresolved' | 'malformed' | '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' | 'override-style-ignored';
+/** A mapped type consumers can use for exhaustive warning classification. */
+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
+ *   - `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' | '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` 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. `'paint'` means drawn, but not laid out as Unity would —
+     * `letter-spacing` is drawn and left out of text measurement.
+     */
+    applied?: 'paint';
+} | {
+    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;
+} | {
+    kind: 'asset';
+    path: string;
+    form: 'url' | 'resource';
+} | {
+    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).
@@ -221,11 +319,19 @@ export type WarningKind = 'unsupported-control' | 'unsupported-property' | 'unsu
  */
 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;
     /** Text location, when the warning has one. */
     at?: SourceRef;
     /** Element the warning is about, when it has one. Lets the UI highlight it. */
     node?: NodeId;
+    reason?: WarningReason;
+    subject?: WarningSubject;
 }
 export interface UxmlDocument {
     /** The exact UXML text every tree span indexes into. */
@@ -276,11 +382,17 @@ export type StyleOrigin = {
     kind: 'inline';
     node: NodeId;
     declIndex: number;
+    /** URL of the UXML/USS document that supplied this declaration. */
+    sourceDocument?: string | null;
+    sourceDocumentFrom?: string | null;
 } | {
     kind: 'rule';
     sheet: number;
     item: number;
     declIndex: number;
+    /** URL of the stylesheet containing the declaration, when external. */
+    sourceDocument?: string | null;
+    sourceDocumentFrom?: string | null;
     /**
      * Pseudo-class states the matched selector required, e.g. `['hover']`.
      *

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,6 +11,8 @@ 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>;

package/dist/render/values.d.ts

@@ -36,6 +36,8 @@ export interface LengthResult {
     length: Length | null;
     /** Set when the text names a unit USS does not support, or uses calc(). */
     problem?: string;
+    /** 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/style/registry.d.ts

@@ -0,0 +1,110 @@
+/**
+ * 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';
+    subject: {
+        kind: 'property';
+        property: string;
+        value: string;
+        since?: string;
+        replacements?: readonly string[];
+        affectsLayout?: boolean;
+        applied?: 'paint';
+    };
+}
+/**
+ * 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

@@ -72,6 +72,16 @@ export interface Candidate {
     order: number;
     winner: boolean;
 }
+/** Where a computed value was written, as warning fields. */
+export type DeclarationLocator = (origin: StyleOrigin) => Pick<Warning, 'at' | 'sourceDocument'>;
+/**
+ * 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): 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

@@ -0,0 +1,36 @@
+import { UxmlDocument, Warning } from '../model/types';
+export type TemplateResolver = (url: string, from: string | null) => string | null;
+type TemplateDocumentParser = (source: string, resolver: TemplateResolver | undefined) => UxmlDocument;
+/** Internal registration avoids making the template loader depend on index.ts. */
+export declare function registerTemplateParser(parser: TemplateDocumentParser): void;
+/** Called by parse() so expansion can reuse the exact resolver the host passed. */
+export declare function rememberTemplateResolver(document: UxmlDocument, resolver: TemplateResolver | undefined): void;
+/**
+ * Purpose:      collect direct template dependencies without a regex pass.
+ * Deps/Effects: parses `source`; no I/O and no model mutation.
+ * Ensures:      returns decoded `<Template src>` values in source order.
+ */
+export declare function collectDependencies(source: string): string[];
+export interface TemplateExpansion {
+    /** Render-only document. The caller must keep the original for serialization. */
+    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.
+ *
+ * The entry UXML is represented as a tiny loaded record so the same recursive
+ * path handles top-level and nested declarations. Its URL is null by contract.
+ */
+export declare function expandTemplates(document: UxmlDocument): TemplateExpansion;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uxml-preview",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "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.",
   "keywords": [
     "unity",
@@ -46,7 +46,7 @@
   ],
   "sideEffects": false,
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
@@ -69,9 +69,11 @@
     "test:roundtrip": "vitest run tests/roundtrip",
     "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",
     "golden:update": "node scripts/update-golden.mjs",
+    "check:self-reference": "node scripts/check-self-reference.mjs",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+    "prepublishOnly": "npm run check:self-reference && npm run typecheck && npm run test && npm run build"
   },
   "dependencies": {
     "yoga-layout": "^3.2.1"