uxml-preview 0.5.1 → 0.6.1

package/README.zh-CN.md

@@ -0,0 +1,84 @@
+# uxml-preview
+
+*[English](https://github.com/ReuHomi/uxml-preview/blob/main/README.md) · [한국어](https://github.com/ReuHomi/uxml-preview/blob/main/README.ko.md) · [日本語](https://github.com/ReuHomi/uxml-preview/blob/main/README.ja.md) · 简体中文*
+
+**无需 Unity 编辑器，即可在浏览器中渲染 Unity UI Toolkit 的 UXML/USS——由 UI Toolkit 自身使用的
+Yoga 引擎负责布局，并与 Unity 实测结果进行了比对验证。**
+
+[![在线体验页面：上方为预览画面，下方列出每条警告的原因及 Unity 的实际处理方式](https://raw.githubusercontent.com/ReuHomi/uxml-preview/main/docs/media/playground.png)](https://reuhomi.github.io/uxml-preview/)
+
+### ▶ [打开在线体验 (Playground)](https://reuhomi.github.io/uxml-preview/)
+
+粘贴你自己的 `.uxml` 和 `.uss`，或直接打开示例。所有内容都不会上传，完全在页面本地
+运行。
+
+[![CI](https://github.com/ReuHomi/uxml-preview/actions/workflows/ci.yml/badge.svg)](https://github.com/ReuHomi/uxml-preview/actions/workflows/ci.yml)
+[![Pages](https://github.com/ReuHomi/uxml-preview/actions/workflows/pages.yml/badge.svg)](https://github.com/ReuHomi/uxml-preview/actions/workflows/pages.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/ReuHomi/uxml-preview/blob/main/LICENSE)
+
+## 验证方式
+
+- **坐标：** 在包含完整界面在内的 40 个布局用例中，660 / 676 个元素坐标值与 Unity 6000.0.40f1 完全一致。[查看全部差异明细 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md) 在 Unity 6.3（6000.3.25f1）中重新导出这批用例后，所有布局结果均与当天导出的 6000.0.40f1 结果一致。[6.3 重新测量结果 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md#unity-63-lts-re-measurement-2026-10-15)
+- **文本：** 在真实浏览器中绘制，并与 Unity 6000.3.25f1 逐个 Label 进行比对——行数 92 / 92、高度 84 / 92、宽度 92 / 92（误差在 1px 或 1% 以内）。所有高度存在差异的用例，均是使用了不含韩文字符的拉丁字体 Inter 来排版韩文或混排文本；此时 Unity 会改用回退字体绘制，而本预览工具会针对该情况发出明确警告。[文本测试集 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md#text-cohort-separate-set-measured-2026-10-16)
+- **Unity 版本：** 基准版本为 Unity 6.3 LTS。某项属性是否属于 USS，依据 Unity 官方属性表（截至 6.6）判定；6.7 在推出 LTS 版本之前暂不支持。[支持范围 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/supported.en.md)
+- **不一致之处会明确报告，绝不静默忽略。** 遇到不支持的控件、属性或值时，工具会返回警告并说明原因；对于已实测的情况，还会一并告知 Unity 的实际处理方式。[警告说明 →](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.en.md#warnings)
+
+## 三种使用方式
+
+| 使用场景 | 推荐方案 |
+|---|---|
+| **设计界面** | 使用浏览器中的[在线体验](https://reuhomi.github.io/uxml-preview/)，或在项目文件旁使用 [UXML Preview for VS Code](https://github.com/ReuHomi/vscode-uxml-preview) |
+| **让 AI 智能体编写 UI** | [uxml-author](https://github.com/ReuHomi/uxml-author) —— 编写 UXML/USS、调用本库渲染并先验证结果再交付的技能（Skill） |
+| **构建工具** | 直接使用本库：`npm install uxml-preview`，详见 [API 文档](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.en.md) |
+
+## 安装
+
+```bash
+npm install uxml-preview
+```
+
+工具链需要 Node 22 或更高版本；渲染需要 DOM 环境（浏览器，或在测试中使用 happy-dom /
+jsdom）。
+
+```ts
+import { loadLayoutEngine, parse, render, serialize } from 'uxml-preview';
+
+await loadLayoutEngine();                 // Yoga 基于 WebAssembly：预先加载一次即可
+
+const doc = parse(uxmlText, ussText);     // 文本 → 模型
+const view = render(doc, container, {     // 模型 → 画面
+  size: { width: 1280, height: 720 },     // 面板尺寸，而非窗口尺寸
+  resolveAsset: (path, form) => myAssetUrl(path, form),  // project://… → URL，不存在则返回 null
+});
+
+for (const w of view.warnings) console.log(w.reason ?? w.kind, w.message);
+
+view.dispose();                           // Yoga 节点不会被垃圾回收，需手动释放
+const { uxml, uss } = serialize(doc);     // 若未修改，输出与输入字节级完全一致
+```
+
+## 文档
+
+- [USS 不是 CSS](https://github.com/ReuHomi/uxml-preview/blob/main/docs/uss-vs-css.md)（英文） — 导致迁移过来的样式表显示异常的各项差异，均附有示例
+- [支持范围](https://github.com/ReuHomi/uxml-preview/blob/main/docs/supported.en.md)（英文） — 控件、属性、状态、版本，以及各项的验证程度
+- [精度说明](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md)（英文） — 所有数据、测量方法及全部已知差异
+- [API](https://github.com/ReuHomi/uxml-preview/blob/main/docs/api.en.md)（英文） — `parse`、`render`、`serialize`、钩子（Hooks）、警告、`classifyVisibility`
+- [更新日志](https://github.com/ReuHomi/uxml-preview/blob/main/CHANGELOG.md)（英文）
+- [视觉比对](https://github.com/ReuHomi/uxml-preview/blob/main/docs/visual-check.md)（韩文） — 将色彩与质感同 Unity 并排对比的单次记录（2026-08）
+
+## 开发
+
+```bash
+pnpm install
+pnpm dev            # 在本地启动在线体验页面（Playground）
+pnpm test           # 无需浏览器或 Unity 即可运行的全部测试
+pnpm test:text      # 文本测试集，在真实 Chromium 中运行（见 docs/accuracy.en.md）
+pnpm build
+```
+
+复现 Unity 侧的基准数据需要安装 Unity，具体步骤见
+[精度说明](https://github.com/ReuHomi/uxml-preview/blob/main/docs/accuracy.en.md#producing-the-ground-truth)。
+
+## 许可证
+
+Apache-2.0

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import { NodeId, UxmlDocument, Warning } from './model/types';
+import { ComputedStyle, ResolveResult } from './style/resolve';
 import { LayoutBox, MeasureText } from './layout/yoga';
+import { ResolveFont } from './render/fonts';
 /**
  * uxml-preview — public API surface.
  *
@@ -12,6 +14,8 @@ export { collectDependencies, expandTemplates, TEMPLATE_DEPTH_LIMIT } from './te
 export type { TemplateExpansion, TemplateResolver } from './template/expand';
 export { loadLayoutEngine, isLayoutEngineReady, liveNodeCount } from './layout/yoga';
 export type { LayoutBox, MeasureText, TextContext, TextMetrics } from './layout/yoga';
+export type { FaceInfo } from './render/measure';
+export { textHeight, EDITOR_DEFAULT_FACE_INFO } from './render/measure';
 export { createDefaultMeasureText } from './render/measure';
 export { NODE_ATTRIBUTE, PART_ATTRIBUTE, PART_OWNER_ATTRIBUTE } from './render/paint';
 export { supportedControlNames } from './controls/registry';
@@ -72,6 +76,8 @@ export declare function serialize(doc: UxmlDocument): {
     uss: string;
 };
 export interface RenderOptions {
+    /** Resolves font assets once per distinct path and form in each render. */
+    resolveFont?: ResolveFont;
     /**
      * Resolves Unity asset references to something a browser can load.
      *
@@ -118,7 +124,15 @@ export interface RenderOptions {
      */
     states?: Readonly<Record<string, readonly string[]>>;
 }
+export { classifyVisibility } from './render/visibility';
+export type { Visibility } from './render/visibility';
 export interface RenderResult {
+    /** Expanded document used for rendering, separate from the source AST. */
+    document?: UxmlDocument;
+    /** Computed styles keyed by rendered element id. */
+    styles?: ReadonlyMap<NodeId, ComputedStyle>;
+    /** Computed control part styles keyed by owner id and part name. */
+    partStyles?: ResolveResult['partStyles'];
     /**
      * Everything the renderer could not honour: unsupported controls, properties,
      * selectors and units, plus unresolved assets. Distinct from