uxml-preview 0.1.0 → 0.3.0

package/dist/known-divergences.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Differences from Unity that measurement has confirmed and that fixing the
+ * renderer cannot close. `docs/accuracy.md` describes 16 divergent values;
+ * all but one class of them are listed below.
+ *
+ * The 1px cases (3 values) are excluded on purpose: they sit inside the
+ * golden tests' own 0.5px-tighter-than-plan tolerance. That is a test
+ * judgement parameter, not a rendering limitation — listing it here would
+ * tell a host to worry about a difference the renderer did not actually make.
+ *
+ * If a fourth category is ever promoted here, extend this list and the
+ * pinned entry count in tests/known-divergences.test.ts together — do not
+ * let the list grow silently, since `id` is a contract hosts key off.
+ */
+export interface KnownDivergence {
+    /** Stable identifier. Hosts may key off this; do not rename. */
+    readonly id: string;
+    /**
+     * Why this cannot simply be fixed.
+     *
+     * 'unreproducible' — the difference comes from something we cannot
+     *   reproduce at all, such as font metrics that move with the platform.
+     * 'unspecified'    — Unity's own rule for this case is not specified,
+     *   so there is no target to match yet.
+     * 'upstream'       — the difference is fully reproducible and deterministic,
+     *   but it lives in something this renderer depends on rather than in this
+     *   renderer's own code — the place that would need to change is not this
+     *   repository.
+     */
+    readonly kind: 'unreproducible' | 'unspecified' | 'upstream';
+    /** One line, for a diagnostics list. */
+    readonly summary: string;
+    /** What is different and why, for someone deciding whether to care. */
+    readonly detail: string;
+}
+export declare const KNOWN_DIVERGENCES: readonly KnownDivergence[];

package/dist/layout/yoga.d.ts

@@ -42,9 +42,31 @@ export interface LayoutOptions {
      */
     measureText: MeasureText;
 }
+/**
+ * A laid-out element the file never mentioned, built by a control.
+ *
+ * Separate from `boxes` rather than sharing its keys: `NodeId` identifies
+ * something in the document, and these have no document to be in. Giving them
+ * borrowed ids would make "which node is this?" answerable with a lie, and an
+ * editor asking that question needs to hear "this one is not yours".
+ */
+export interface LayoutPart {
+    /** Unity's name, e.g. `unity-content-viewport`. */
+    name: string;
+    /** The element whose control built it. */
+    owner: NodeId;
+    box: LayoutBox;
+    /** Fixed styling, with `builtin-theme` provenance on every value. */
+    style: ComputedStyle;
+}
 export interface LayoutTree {
     /** Computed box per element, in panel coordinates. */
     boxes: ReadonlyMap<NodeId, LayoutBox>;
+    /**
+     * Parts each element's control built, outermost first. The element's own
+     * children were laid out inside the last one.
+     */
+    parts: ReadonlyMap<NodeId, readonly LayoutPart[]>;
     /** Elements that were laid out, parents before children. */
     painted: readonly ElementNode[];
     warnings: readonly Warning[];
@@ -60,4 +82,15 @@ export interface LayoutTree {
  * Deps/Effects: creates Yoga nodes; the returned tree owns them until disposed.
  * Requires:     `loadLayoutEngine()` must have resolved.
  */
-export declare function layoutDocument(root: ElementNode, styles: ReadonlyMap<NodeId, ComputedStyle>, options: LayoutOptions): LayoutTree;
+export declare function layoutDocument(root: ElementNode, styles: ReadonlyMap<NodeId, ComputedStyle>, 
+/**
+ * Style per control part, from the cascade.
+ *
+ * Taken rather than computed. This module used to build part styles itself
+ * from the registry's fixed declarations, which meant author USS could never
+ * reach them — `#unity-content-container { flex-direction: row }` had nowhere
+ * to land, because the part did not exist until after the cascade had run.
+ * Resolving parts alongside elements is what fixes that, and computing them
+ * in two places would put the second cascade back.
+ */
+partStyles: ReadonlyMap<NodeId, ReadonlyMap<string, ComputedStyle>>, options: LayoutOptions): LayoutTree;

package/dist/model/types.d.ts

@@ -244,15 +244,22 @@ export interface UxmlDocument {
      * own `source`, which is why the source text lives on the sheet.
      */
     sheets: StyleSheet[];
-    /** Parse-time only — malformed input. Support judgments happen downstream. */
+    /**
+     * Parse-time only — `'malformed'` (bad syntax) and `'import-unresolved'`
+     * (a `<Style src="…">` or `@import` that `resolveImport` could not read).
+     * Support judgments (unsupported controls/properties/selectors/units,
+     * unresolved assets) happen downstream, in `RenderResult.warnings`.
+     */
     warnings: Warning[];
 }
 /**
  * Where a computed value came from.
  *
  * Phase 8 needs this to answer "write to the inline style, or edit the rule?".
- * Every variant points into the model, so the editor can jump straight to the
- * declaration's span and rewrite exactly that text.
+ * Every variant *except `builtin-theme`* points into the model, so the editor
+ * can jump straight to the declaration's span and rewrite exactly that text.
+ * `builtin-theme` is the one that does not, and it says so rather than
+ * inventing a location — an editor must branch on it, not follow it.
  *
  * Note the inline variant indexes declarations parsed on demand from the
  * element's `style` attribute — those declarations are not stored on the node.
@@ -268,11 +275,40 @@ export type StyleOrigin = {
     sheet: number;
     item: number;
     declIndex: number;
+    /**
+     * Pseudo-class states the matched selector required, e.g. `['hover']`.
+     *
+     * Absent when the rule applies unconditionally. Present, it means the
+     * value is only true while those states hold — an editor showing "this
+     * came from line 12" without it would be telling half the truth, and a
+     * user would edit the base appearance while looking at the hover one.
+     */
+    states?: readonly string[];
 } | {
     kind: 'inherited';
     from: NodeId;
     origin: StyleOrigin;
 }
+/**
+ * A control default this renderer supplies, standing in for Unity's theme
+ * stylesheet. **There is no file and no span**: the declaration exists in this
+ * library, not in the user's project.
+ *
+ * Its own variant rather than a `rule` with an invented path, because an
+ * editor offering "jump to the declaration" must be able to tell that there
+ * is nowhere to jump — pointing at a file that does not exist is worse than
+ * saying the value is not editable.
+ *
+ * `unityVersion` records where the value was measured. Theme values move
+ * between Unity versions, and when one stops matching this is the first thing
+ * to check.
+ */
+ | {
+    kind: 'builtin-theme';
+    selector: string;
+    property: string;
+    unityVersion: string;
+}
 /** USS default, which is not always the CSS default — `flex-direction` is `column`. */
  | {
     kind: 'default';

package/dist/parser/entities.d.ts

@@ -0,0 +1,19 @@
+/**
+ * XML entity decoding, for the moment a stored attribute becomes a real value.
+ *
+ * The parser deliberately keeps attribute values exactly as written — that is
+ * what makes serialization byte-exact — so `&` survives in the model. Any
+ * consumer that means to *use* the value rather than re-emit it has to decode
+ * first, and there are two: painted text, and paths handed to the host's
+ * resolver hooks. A `<Style src="…?a=1&amp;b=2">` reaching `resolveImport`
+ * undecoded gives the host `amp;b=2` to parse, which is not a thing.
+ */
+/**
+ * Purpose:      turn stored attribute text into the value it stands for.
+ * Ensures:      never throws. A numeric reference outside the Unicode range
+ *               makes `String.fromCodePoint` raise a RangeError, and one bad
+ *               character must not take down a render (CLAUDE.md rule 6).
+ *               Unreadable references are left as written, which also
+ *               round-trips.
+ */
+export declare function decodeEntities(text: string): string;

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

@@ -1,7 +1,16 @@
 import { NodeId, Warning } from '../model/types';
 import { ComputedStyle } from '../style/resolve';
 export interface CssMapOptions {
-    resolveAsset?: ((path: string) => string | null) | undefined;
+    /**
+     * `form` tells `url("...")` apart from `resource("...")` — Unity resolves
+     * them differently: `url()` is a path (relative to the project or
+     * absolute), `resource()` names an asset inside a Resources folder by its
+     * Unity resource path (no extension). A host that ignores `form` and
+     * treats every path the same will resolve `resource("foo")` as a literal
+     * file path, which silently draws the wrong image whenever a same-named
+     * file happens to sit alongside it — or resolves nothing at all.
+     */
+    resolveAsset?: ((path: string, form: 'url' | 'resource') => string | null) | undefined;
 }
 export interface CssMapResult {
     declarations: Record<string, string>;

package/dist/render/paint.d.ts

@@ -1,8 +1,20 @@
 import { ElementNode, NodeId, Warning } from '../model/types';
 import { ComputedStyle } from '../style/resolve';
-import { LayoutBox } from '../layout/yoga';
+import { LayoutBox, LayoutPart } from '../layout/yoga';
 import { CssMapOptions } from './css-map';
 export declare const NODE_ATTRIBUTE = "data-uxml-node";
+/**
+ * Marks an element a control built rather than one the file asked for, and
+ * carries Unity's name for it.
+ *
+ * Deliberately not `data-uxml-node`: these have no node. An editor that traced
+ * a click back through the node attribute would get an id that belongs to
+ * something else, and would then offer to edit the wrong element. Here it finds
+ * a different attribute and can say "this part is not yours to change".
+ */
+export declare const PART_ATTRIBUTE = "data-uxml-part";
+/** The element whose control built a part. Lets a click land on its owner. */
+export declare const PART_OWNER_ATTRIBUTE = "data-uxml-part-owner";
 export interface PaintResult {
     warnings: Warning[];
     /** Painted element per model node, for hit-testing and for tests. */
@@ -16,4 +28,4 @@ export interface PaintOptions extends CssMapOptions {
  * Deps/Effects: replaces the container's children. The caller owns disposal.
  * Requires:     `boxes` must come from a layout of this same tree.
  */
-export declare function paint(root: ElementNode, boxes: ReadonlyMap<NodeId, LayoutBox>, styles: ReadonlyMap<NodeId, ComputedStyle>, container: HTMLElement, options: PaintOptions): PaintResult;
+export declare function paint(root: ElementNode, boxes: ReadonlyMap<NodeId, LayoutBox>, parts: ReadonlyMap<NodeId, readonly LayoutPart[]>, styles: ReadonlyMap<NodeId, ComputedStyle>, container: HTMLElement, options: PaintOptions): PaintResult;

package/dist/style/resolve.d.ts

@@ -7,20 +7,68 @@ export interface ComputedValue {
 }
 export type ComputedStyle = ReadonlyMap<string, ComputedValue>;
 export interface ResolveOptions {
-    /** Pseudo-classes to treat as active, e.g. `new Set(['hover'])`. */
+    /**
+     * Pseudo-classes to treat as active on every element, e.g. `new Set(['hover'])`.
+     *
+     * Blunt, and kept for the case where that is what you want. Per-element
+     * control is `states`.
+     */
     activeStates?: ReadonlySet<string>;
+    /**
+     * Pseudo-classes to activate per element, keyed by USS selector.
+     *
+     * ```ts
+     * { '#UseButton': ['hover'], '#DropButton': ['disabled'] }
+     * ```
+     *
+     * States are explicit input, never mouse events: a render that depends on
+     * where the pointer is cannot be compared to anything twice.
+     *
+     * Keys are matched against the tree **without** any state applied, so a key
+     * cannot switch itself on, and `:hover` in a key is meaningless.
+     */
+    states?: Readonly<Record<string, readonly string[]>>;
 }
 export interface ResolveResult {
     styles: ReadonlyMap<NodeId, ComputedStyle>;
+    /**
+     * Style per control part, keyed by the owning element and then Unity's name
+     * for the part.
+     *
+     * Parts are resolved here rather than in the layout, because that is what
+     * lets author USS reach them: `#unity-content-container { flex-direction: row }`
+     * is how a real project lays out a scroll region's contents, and a part built
+     * after the cascade had already run could never receive it.
+     */
+    partStyles: ReadonlyMap<NodeId, ReadonlyMap<string, ComputedStyle>>;
     warnings: readonly Warning[];
 }
+/**
+ * Where a declaration sits in the cascade's outermost comparison.
+ *
+ * Unity's control defaults are not "a stylesheet that loaded first" — they are
+ * a lower origin, the way a browser's user-agent sheet is, so **an author rule
+ * beats them regardless of specificity**. Measured, not reasoned: the
+ * `states-disabled` case writes `Button { margin: 0 }` (a type selector, 0,0,1)
+ * against the theme's `.unity-button` (a class, 0,1,0), and Unity puts the
+ * button at x=0. Specificity alone would have put it at x=3.
+ *
+ * This is the axis the cascade was missing. Without it the theme wins ties it
+ * should lose, and every value added to `theme.ts` spreads the error.
+ */
+export declare const enum Rank {
+    BuiltinTheme = 0,
+    Author = 1
+}
 /** One declaration that competed, winner or not. */
 export interface Candidate {
     property: string;
     value: string;
     origin: StyleOrigin;
+    /** Compared before specificity. A built-in default never beats author USS. */
+    rank: Rank;
     specificity: Specificity;
-    /** Position in cascade order; higher wins a specificity tie. */
+    /** Position in cascade order; higher wins a specificity tie within a rank. */
     order: number;
     winner: boolean;
 }

package/dist/style/selector.d.ts

@@ -1,7 +1,21 @@
-import { ElementNode, Selector } from '../model/types';
-export interface MatchContext {
-    /** Parent of every node, built once per document. */
-    parentOf: (node: ElementNode) => ElementNode | null;
+import { Selector } from '../model/types';
+/**
+ * How to interrogate whatever is being matched.
+ *
+ * Deps: every function here is read during matching, including for ancestors —
+ * `.panel:hover .item` asks the ancestor for its states, not the element's.
+ */
+export interface MatchContext<T> {
+    /**
+     * The style parent, which is not always the layout parent.
+     *
+     * Measured, and it decides the shape of this whole design: a slot inside a
+     * ScrollView sits physically inside `unity-content-container`, yet
+     * `#Grid > .slot` reaches it in Unity. So an element from the file keeps its
+     * file parent here, and the parts a control builds are transparent to it.
+     * See `child-combinator-through-parts` and the 2026-08-06 decision rows.
+     */
+    parentOf: (target: T) => T | null;
     /**
      * The element `:root` refers to.
      *
@@ -11,11 +25,38 @@ export interface MatchContext {
      * keeps the usual custom-property token pattern working, since values
      * declared there inherit down the whole tree.
      */
-    root: ElementNode;
-    /** Pseudo-classes currently active, e.g. `hover`. Empty in a static render. */
-    activeStates: ReadonlySet<string>;
+    isRoot: (target: T) => boolean;
+    /** Pseudo-classes active on this target, e.g. `hover`. */
+    statesOf: (target: T) => ReadonlySet<string>;
+    /** What a type selector compares against — the C# class name, not a tag. */
+    typeNameOf: (target: T) => string;
+    /** What `#name` compares against. */
+    idOf: (target: T) => string | undefined;
+    /** Written classes plus any the control adds, e.g. `unity-button`. */
+    classesOf: (target: T) => readonly string[];
 }
-export declare function matchesSelector(selector: Selector, node: ElementNode, ctx: MatchContext): boolean;
+export declare function matchesSelector<T>(selector: Selector, target: T, ctx: MatchContext<T>): boolean;
+/**
+ * Purpose:      the state pseudo-classes a selector depends on, in source order.
+ * Ensures:      `:root` is excluded — it names a position in the tree, not a
+ *               state, and cannot be switched on or off.
+ *
+ * Used for provenance: a value from `.unity-button:hover` is only true while
+ * hovering, and an editor that does not know this rewrites the wrong rule.
+ */
+export declare function statesRequiredBy(selector: Selector): string[];
+/**
+ * Purpose:      names and classes in a selector that belong to Unity, not the author.
+ * Ensures:      returns the `unity-` prefixed fragments only.
+ *
+ * An author writing `#unity-text-input` or `.unity-scroll-view__content-container`
+ * is aiming at a part a control builds. If nothing matches, that is not an
+ * unused rule — it is a rule that cannot work, and saying nothing about it is
+ * the silent loss CLAUDE.md rule 6 exists to prevent.
+ */
+export declare function unityFragmentsIn(selectors: readonly Selector[]): string[];
 /** The first unsupported fragment in a selector group, if any. */
 export declare function unsupportedFragment(selectors: readonly Selector[]): string | null;
-export declare function buildParentMap(root: ElementNode): Map<ElementNode, ElementNode | null>;
+export declare function buildParentMap<T extends {
+    children: readonly T[];
+}>(root: T): Map<T, T | null>;

package/dist/unity-project/index.d.ts

@@ -0,0 +1,14 @@
+export interface GuidIndex {
+    /** Absolute path of the asset with this GUID, or null. */
+    get(guid: string): string | null;
+    /** Number of entries. Lets a host report an empty scan. */
+    readonly size: number;
+}
+/**
+ * Purpose: resolve a `project://database/Assets/...` reference whose file has
+ * moved, by walking `.meta` files for their `guid:` line instead.
+ * Deps/Effects: reads the directory tree under `projectRoot`; unreadable
+ * `.meta` files are skipped rather than thrown, so one bad file cannot fail
+ * the whole scan.
+ */
+export declare function buildGuidIndex(projectRoot: string): Promise<GuidIndex>;

package/dist/unity-project/index.js

@@ -0,0 +1,41 @@
+import { readdir as c, readFile as u } from "node:fs/promises";
+import { join as s } from "node:path";
+const l = /* @__PURE__ */ new Set(["Library", "Temp", "obj", ".git"]), f = /^guid:\s*([0-9a-fA-F]+)/m;
+async function y(n) {
+  const t = /* @__PURE__ */ new Map();
+  return await o(n, t), {
+    get(e) {
+      return t.get(e) ?? null;
+    },
+    get size() {
+      return t.size;
+    }
+  };
+}
+async function o(n, t) {
+  const e = await c(n, { withFileTypes: !0 });
+  for (const i of e) {
+    const a = s(n, i.name);
+    if (i.isDirectory()) {
+      if (l.has(i.name)) continue;
+      await o(a, t);
+      continue;
+    }
+    if (!i.name.endsWith(".meta")) continue;
+    const r = await m(a);
+    r !== null && t.set(r, a.slice(0, -5));
+  }
+}
+async function m(n) {
+  var e;
+  let t;
+  try {
+    t = await u(n, "utf8");
+  } catch {
+    return null;
+  }
+  return ((e = f.exec(t)) == null ? void 0 : e[1]) ?? null;
+}
+export {
+  y as buildGuidIndex
+};

package/package.json

@@ -1,59 +1,90 @@
-{
-  "name": "uxml-preview",
-  "version": "0.1.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: 242 of 244 element coordinates identical to Unity 6. Parses and writes files back byte-for-byte.",
-  "keywords": [
-    "unity", "unity3d", "ui-toolkit", "uitk", "uielements", "uxml", "uss",
-    "yoga", "yoga-layout", "flexbox", "webassembly", "renderer", "preview",
-    "game-ui", "typescript", "editor-tooling", "unity-editor", "css-to-uss"
-  ],
-  "license": "Apache-2.0",
-  "type": "module",
-  "main": "./dist/index.js",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "files": ["dist", "README.md", "LICENSE", "THIRD-PARTY-NOTICES.md", "CHANGELOG.md"],
-  "sideEffects": false,
-  "engines": { "node": ">=18" },
-  "publishConfig": { "access": "public" },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ReuHomi/uxml-preview.git"
-  },
-  "homepage": "https://reuhomi.github.io/uxml-preview/",
-  "bugs": { "url": "https://github.com/ReuHomi/uxml-preview/issues" },
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc --noEmit && vite build",
-    "build:site": "vite build --config vite.playground.config.ts",
-    "preview:site": "vite preview --config vite.playground.config.ts",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "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",
-    "golden:update": "node scripts/update-golden.mjs",
-    "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
-  },
-  "dependencies": {
-    "yoga-layout": "^3.2.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "jsdom": "^30.0.1",
-    "pixelmatch": "^6.0.0",
-    "pngjs": "^7.0.0",
-    "typescript": "^5.6.0",
-    "vite": "^6.0.0",
-    "vite-plugin-dts": "^4.3.0",
-    "vitest": "^2.1.0"
-  },
-  "packageManager": "pnpm@9.12.0"
-}
+{
+  "name": "uxml-preview",
+  "version": "0.3.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: 548 of 564 element coordinates identical to Unity 6. Parses and writes files back byte-for-byte.",
+  "keywords": [
+    "unity",
+    "unity3d",
+    "ui-toolkit",
+    "uitk",
+    "uielements",
+    "uxml",
+    "uss",
+    "yoga",
+    "yoga-layout",
+    "flexbox",
+    "webassembly",
+    "renderer",
+    "preview",
+    "game-ui",
+    "typescript",
+    "editor-tooling",
+    "unity-editor",
+    "css-to-uss"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./unity-project": {
+      "types": "./dist/unity-project/index.d.ts",
+      "import": "./dist/unity-project/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ReuHomi/uxml-preview.git"
+  },
+  "homepage": "https://reuhomi.github.io/uxml-preview/",
+  "bugs": {
+    "url": "https://github.com/ReuHomi/uxml-preview/issues"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "build:site": "vite build --config vite.playground.config.ts",
+    "preview:site": "vite preview --config vite.playground.config.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "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",
+    "golden:update": "node scripts/update-golden.mjs",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run build"
+  },
+  "dependencies": {
+    "yoga-layout": "^3.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "jsdom": "^30.0.1",
+    "pixelmatch": "^6.0.0",
+    "pngjs": "^7.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.3.0",
+    "vitest": "^2.1.0"
+  },
+  "packageManager": "pnpm@9.12.0"
+}