uxml-preview 0.5.1 → 0.6.0

package/dist/layout/yoga.d.ts

@@ -1,5 +1,6 @@
 import { ElementNode, NodeId, Warning } from '../model/types';
 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;

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.
@@ -241,6 +244,7 @@ export type WarningKindMap<T> = {
  *
  *   - `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
@@ -250,7 +254,7 @@ export type WarningKindMap<T> = {
  * 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';
+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`.
@@ -268,7 +272,7 @@ export type WarningSubject = {
     /** 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
+     * 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.
@@ -276,10 +280,16 @@ export type WarningSubject = {
     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 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. */
@@ -289,10 +299,13 @@ export type WarningSubject = {
 } | {
     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. */
@@ -330,6 +343,7 @@ 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;
 }

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

@@ -18,6 +18,21 @@ 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,8 @@ 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';
 }

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

@@ -75,7 +75,7 @@ export declare function ussProperty(name: string): UssProperty | undefined;
 export declare const CSS_REPLACEMENTS: Readonly<Record<string, readonly string[]>>;
 export interface PropertyWarning {
     message: string;
-    reason: 'not-uss' | 'not-rendered';
+    reason: 'not-uss' | 'not-rendered' | 'invalid-value';
     subject: {
         kind: 'property';
         property: string;
@@ -84,6 +84,10 @@ export interface PropertyWarning {
         replacements?: readonly string[];
         affectsLayout?: boolean;
         applied?: 'paint';
+        unityEffect?: {
+            kind: 'unstyled-from-here';
+            versions: readonly UssVersion[];
+        };
     };
 }
 /**

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,8 +74,13 @@ 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'>;
+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.
@@ -81,7 +88,7 @@ export type DeclarationLocator = (origin: StyleOrigin) => Pick<Warning, 'at' | '
  *               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;
+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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "uxml-preview",
-  "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.",
+  "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",
@@ -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",