@kurot/cli 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.ht
 
 ## Unreleased
 
+## 2.0.0 — 2026-09-21
+
+This release is scoped to the Kurot Editor toolchain. Existing EXML game
+projects remain supported by the 1.3.x line and are not expected to upgrade or
+change their project configuration.
+
+### Added
+
+- Canonical KUI XML Skin compilation through `@kurot/ui-document`.
+- Generated default theme mappings derived from Skin `target` and `default`
+  metadata, including duplicate-default diagnostics.
+- KUI XML project templates for all 21 built-in UI skins.
+
+### Changed
+
+- Replaced the `exml` project configuration with `ui.sourceDir`,
+  `ui.namespaces`, and `ui.components`.
+- Simplified SkinIR to the runtime operations produced by semantic KUI
+  documents and removed syntax-specific compatibility branches.
+- The theme JSON is generated at the fixed `resource/default.thm.json` output
+  path rather than configured or supplied as an authored input.
+
+### Removed
+
+- EXML parsing, theme-input discovery, `.exml` templates, and compatibility
+  diagnostics.
+
+## 1.3.0 — 2026-09-20
+
+### Added
+
+- Generated declarations now narrow each exported project class's public
+  `skinParts` accessor from an explicit string-literal `skinName`, a configured
+  reusable-component pair, or a unique `<ClassName>Skin` naming match.
+- Added ambiguity protection: convention inference is omitted when multiple
+  compiled skins share the same short `<ClassName>Skin` name.
+
+### Changed
+
+- Project classes no longer need to repeat their skin as a base-class generic
+  when the CLI can establish an unambiguous host-to-skin relationship.
+
+### Tests
+
+- Added regression coverage for explicit assignment, reusable-component,
+  unique naming-convention, and ambiguous naming-convention host inference.
+
 ## 1.2.0 — 2026-09-20
 
 ### Added

package/README.md

@@ -1,371 +1,183 @@
 # @kurot/cli
 
-CLI tool for the Kurot game engine — a modern replacement for the legacy Egret CLI. Powered by esbuild for fast compilation, with a built-in EXML skin parser and code generator.
+Build tooling for the Kurot UI Editor workflow. It uses esbuild, emits ES2022
+ESM, and compiles canonical KUI XML skins into runtime theme modules.
 
-> **Current release: 1.2.0.** Requires Node.js 20 or later and emits ES2022 ESM projects.
+> **Current release: 2.0.0.** Node.js 20 or later is required.
 
-> Migrating from Egret? See [egret-migration.md](../../docs/egret-migration.md)
->
-> Release history: [CHANGELOG.md](CHANGELOG.md)
+> **Release scope:** 2.0.0 is currently dedicated to Kurot Editor integration.
+> Existing game projects that use EXML, including CrashMaster, should remain on
+> `@kurot/cli@1.3.x`. Version 2.0.0 is not an in-place project upgrade and does
+> not require those projects to change their configuration or UI assets.
 
-## Usage
-
-`@kurot/cli` does **not** require a global install.
+See [CHANGELOG.md](CHANGELOG.md) for release history.
 
-### Creating a project
+## Usage
 
-Use `npx` to scaffold a new project — no installation needed:
+The CLI does not require a global install.
 
 ```bash
 npx @kurot/cli create my-game
-npx @kurot/cli create my-lib --template empty
-```
-
-### In-project commands
-
-Scaffolded projects include `@kurot/cli` as a devDependency and expose commands via npm scripts:
-
-```bash
 cd my-game
 pnpm install
-pnpm build    # build
-pnpm dev      # dev server
-pnpm clean    # clean output
+pnpm dev
 ```
 
-You can also add it to an existing project manually:
-
-```bash
-pnpm add -D @kurot/cli
-```
+Scaffolded projects expose `build`, `dev`, and `clean` scripts. For an
+Editor-managed KUI XML project, install the package with
+`pnpm add -D @kurot/cli@2`. Existing EXML projects should keep their current
+1.3.x dependency.
 
 ## Commands
 
 ### `kurot create`
 
-Scaffold a new project from a template.
-
 ```bash
-kurot create <name> [options]
+kurot create <name> [--template game|empty]
 ```
 
-| Option                  | Description                 | Default |
-| ----------------------- | --------------------------- | ------- |
-| `--template <template>` | Template: `game` \| `empty` | `game`  |
-
-**Templates:**
-
-| Template | Extends   | Dependencies                                      | Description                                                                      |
-| -------- | --------- | ------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `game`   | `UILayer` | `@kurot/core` + `@kurot/game` + `@kurot/ui` | Full-featured project with resource loading, scene building, and Tween animation |
-| `empty`  | `Sprite`  | `@kurot/core`                                   | Minimal project — pure Canvas rendering, no extra dependencies                   |
-
-**Lifecycle:**
-
-| Template | Entry class            | Lifecycle                                                                                         |
-| -------- | ---------------------- | ------------------------------------------------------------------------------------------------- |
-| `game`   | `Main extends UILayer` | `createChildren` → `runGame` → `loadResource` → `loadTheme` → `createGameScene` → `startAnimation` |
-| `empty`  | `Main extends Sprite`  | constructor → `ADDED_TO_STAGE` → `onAddToStage`                                           |
+The `game` template includes `@kurot/core`, `@kurot/game`, `@kurot/ui`, KUI
+skins, resource loading, and an editable HTML template. The `empty` template
+contains a minimal `Sprite` application.
 
 ### `kurot build`
 
-Compile the project into ESM application, engine, namespace, and theme bundles.
-
-```bash
-kurot build [options]
-```
-
-| Option                   | Description                                            | Default |
-| ------------------------ | ------------------------------------------------------ | ------- |
-| `-r, --release`          | Minified, content-hashed release build (→ bin-release) | `false` |
-| `--sourcemap`            | Generate sourcemaps                                    | `false` |
-| `--watch`                | Rebuild source on file changes                         | `false` |
-| `--analyze`              | Print bundle size analysis (esbuild metafile)          | `false` |
-| `--strict`               | Promote supported warnings to build errors             | `false` |
-| `--diagnostics <format>` | Diagnostic output: `human` or `json`                   | `human` |
-
-`--diagnostics json` writes exactly one JSON result to stdout. It includes
-`success`, `mode`, `durationMs`, the output directory on success, and all
-structured diagnostics. Release builds use strict diagnostic policy by default.
-
 ```bash
-kurot build --strict --diagnostics json
+kurot build [--release] [--sourcemap] [--watch] [--analyze]
+            [--strict] [--diagnostics human|json]
 ```
 
-**Output (Egret-aligned shape, ESM under the hood):**
-
-| Mode           | Layout                                                                                                    |
-| -------------- | --------------------------------------------------------------------------------------------------------- |
-| development    | `bin-debug/` — per-file `.js` mirroring `src/` (`Main.js`, `com/.../X.js`) + engine chunks in `js/`       |
-| release (`-r`) | `bin-release/web/<timestamp>/` — `js/main.min_<hash>.js` + `js/kurot.*.min_<hash>.js` + `manifest.json` |
+Development output is written to `bin-debug/`. Release output is written to
+`bin-release/web/<timestamp>/` with minified, content-hashed files. Engine,
+project namespace, theme, and application code are separate ESM chunks joined
+by the generated HTML import map.
 
-Engine packages (`@kurot/*`) are bundled into separate `js/kurot.<name>.js`
-chunks and wired up through an HTML **import map**, so the app bundle and engine
-resolve bare specifiers (`import { Sprite } from '@kurot/core'`) in the browser
-without duplicating engine code. `resource/` (including the compiled
-`default.thm.json`) is copied with fixed names, since user code references those
-paths directly. The entry script bootstraps via your own `createPlayer()` call.
+`--diagnostics json` reserves stdout for one machine-readable build result.
+Release builds apply strict diagnostic policy by default.
 
 ### `kurot dev`
 
-Start a development server with auto-recompilation on file changes (manual browser refresh required).
-
-```bash
-kurot dev [options]
-```
-
-| Option                   | Description                                | Default |
-| ------------------------ | ------------------------------------------ | ------- |
-| `-p, --port <port>`      | Port to listen                             | `3000`  |
-| `--sourcemap`            | Generate sourcemaps                        | `false` |
-| `--strict`               | Promote supported warnings to build errors | `false` |
-| `--diagnostics <format>` | Diagnostic output: `human` or `jsonl`      | `human` |
-
-Unlike build's single JSON result, `kurot dev --diagnostics jsonl` writes one
-JSON event per line so an agent can follow initial builds, diagnostics,
-rebuilds, and server readiness incrementally.
-
 ```bash
-kurot dev --strict --diagnostics jsonl
+kurot dev [--port 3000] [--sourcemap] [--strict]
+          [--diagnostics human|jsonl]
 ```
 
-Machine-readable modes reserve stdout for their JSON protocol and never include
-ANSI color sequences. Failures set a non-zero process exit code.
+The development server rebuilds TypeScript, KUI XML, custom namespaces, and
+the component catalog as their sources change. Browser refresh is currently
+manual. JSONL mode reserves stdout for incremental build and server events.
 
 ### `kurot clean`
 
-Remove the build output directories (`bin-debug` and `bin-release`).
-
-```bash
-kurot clean
-```
+Removes `bin-debug` and `bin-release`.
 
 ## Configuration
 
-Create a `kurot.config.ts` in your project root:
+Create `kurot.config.ts` in the project root:
 
 ```ts
 export default {
-	target: 'html5',
-	entry: 'src/Main.ts',
-	output: { dir: 'bin-debug' },
-	html: { template: 'template/web/index.html' },
-	stage: {
-		width: 640,
-		height: 1136,
-		scaleMode: 'showAll',
-		orientation: 'auto',
-		frameRate: 60,
-	},
-	// Optional: enable EXML skin compilation
-	exml: {
-		themeFile: 'resource/default.thm.json',
-		// Optional: discover reusable component source/Skin pairs
-		components: {
-			namespace: 'game',
-			sourceDir: 'src/components',
-			skinDir: 'resource/skins/components',
-		},
-	},
+    target: 'html5',
+    entry: 'src/Main.ts',
+    output: { dir: 'bin-debug' },
+    html: { template: 'template/web/index.html' },
+    stage: {
+        width: 640,
+        height: 1136,
+        scaleMode: 'showAll',
+        orientation: 'auto',
+        frameRate: 60,
+    },
+    ui: {
+        sourceDir: 'resource/ui',
+        components: {
+            namespace: 'game',
+            sourceDir: 'src/components',
+            skinDir: 'resource/ui/components',
+        },
+    },
 };
 ```
 
-**Options:**
-
-| Field               | Type     | Description                                                                                                              |
-| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `target`            | `string` | Build target — currently only `'html5'`                                                                                  |
-| `entry`             | `string` | Entry file path, default `'src/Main.ts'`                                                                                 |
-| `output.dir`        | `string` | Output directory, default `'bin-debug'`                                                                                  |
-| `html.template`     | `string` | Optional project-owned HTML template; the CLI default page is used when omitted                                          |
-| `stage.width`       | `number` | Stage width                                                                                                              |
-| `stage.height`      | `number` | Stage height                                                                                                             |
-| `stage.scaleMode`   | `string` | Scale mode: `showAll` / `noScale` / `exactFit` / `noBorder` / `fixedHeight` / `fixedWidth` / `fixedNarrow` / `fixedWide` |
-| `stage.orientation` | `string` | Orientation: `auto` / `portrait` / `landscape`                                                                           |
-| `stage.frameRate`   | `number` | Frame rate — must be a positive integer                                                                                  |
-| `exml.themeFile`    | `string` | Theme JSON file path                                                                                                     |
-| `exml.components`   | `ComponentsConfig` | Optional reusable-component convention: namespace, TypeScript source directory, and Skin directory        |
-| `exml.namespaces`   | `Record<string, string>` | Optional EXML prefix → source barrel-file mapping                                                          |
-
-## HTML Template
-
-New projects include an editable `template/web/index.html`. The build reads
-this file and writes the rendered page to the active output directory. Existing
-projects that do not configure `html.template` continue to use the CLI's
-built-in default page.
-
-The following placeholders are required in a configured project template:
-
-| Placeholder | Generated value |
-| --- | --- |
-| `{{KUROT_IMPORT_MAP}}` | Engine and custom namespace import map |
-| `{{KUROT_STAGE_WIDTH}}` | Configured stage width |
-| `{{KUROT_STAGE_HEIGHT}}` | Configured stage height |
-| `{{KUROT_SCALE_MODE}}` | Configured scale mode |
-| `{{KUROT_ORIENTATION}}` | Configured orientation |
-| `{{KUROT_FRAME_RATE}}` | Configured frame rate |
-| `{{KUROT_ENTRY_SCRIPT}}` | Compiled application entry script |
-
-The template may otherwise contain any project-specific HTML, styles, loading
-screen, platform SDK, analytics, fonts, or additional containers. A build fails
-with a clear error when a configured template is missing a required placeholder.
-
-## EXML Skin Compiler
-
-The CLI includes a complete EXML skin parsing and code generation pipeline (XML → SkinIR → ESM JavaScript). `.exml` files placed in the `resource/` directory are compiled automatically during `kurot build`.
-
-### Features
-
-- **XML Parsing** — lightweight parser with namespace, CDATA, and comment support
-- **AST / IR Generation** — converts to an intermediate representation (SkinIR)
-- **Code Generation** — outputs ESM factory functions
-- **Component Registry** — built-in `eui:*` / `egret:*` namespace mapping to `@kurot/ui` / `@kurot/core`
-- **Reusable Components** — pairs `src/components/<Name>.ts` with `resource/skins/components/<Name>Skin.exml`, then exposes `<game:Name>` without a hand-written barrel
-- **Custom Namespaces** — retains `exml.namespaces` for advanced manually maintained source barrels
-- **View States** — supports `<eui:states>`, shorthand `states="up,down"`, state properties, `includeIn`, and `excludeFrom`
-- **Skin Properties** — preserves root properties such as `minWidth`, `minHeight`, and state-specific values
-- **Percent Layout** — auto-detects `width="100%"` and converts to `percentWidth`
-- **Data Binding** — parses `{expression}` binding syntax and generates `Binding.bindProperty` calls
-- **Structured Diagnostics** — stable codes, source locations, suggestions, and strict warning promotion
-
-Unknown tags remain warnings in normal development builds and are omitted from
-the generated visual tree. Under `--strict` (and in release builds), those
-warnings become errors. Syntax errors, invalid theme JSON, and other genuine
-Skin compilation failures always stop the build; the compiler never substitutes
-an empty Skin factory.
-
-The standard declarations `xmlns:eui="http://ns.egret.com/eui"` and
-`xmlns:egret="http://ns.egret.com/egret"` are namespace identifiers. The CLI
-resolves their prefixes internally and does not access those URLs over the
-network, so the original Egret namespace pages do not need to be hosted.
-
-### Reusable components
-
-The game template keeps reusable component logic and white-Egret-compatible
-skins in parallel directories:
-
-```text
-src/components/<path>/<Name>.ts
-resource/skins/components/<path>/<Name>Skin.exml
-```
+`ui.sourceDir` contains `.kui.xml` documents. The build always generates the
+runtime theme manifest at `resource/default.thm.json`; it is not an authored
+input. `ui.namespaces` can map additional XML prefixes to project barrel files.
 
-The TypeScript file must export a class named `<Name>`, and the paired EXML
-must use a standard `eui:Skin` root with a `class` attribute. The CLI validates
-the pair, generates the shared `#ns/game` entry, adds the default Theme mapping,
-and accepts `<game:Name />` in other skins. Components are globally unique by
-class name within the configured namespace.
+The HTML template must contain these placeholders:
 
-Development builds also emit `.kurot/component-catalog.json` for editor and
-agent tooling. The catalog is intentionally omitted from release output.
+- `{{KUROT_IMPORT_MAP}}`
+- `{{KUROT_STAGE_WIDTH}}`
+- `{{KUROT_STAGE_HEIGHT}}`
+- `{{KUROT_SCALE_MODE}}`
+- `{{KUROT_ORIENTATION}}`
+- `{{KUROT_FRAME_RATE}}`
+- `{{KUROT_ENTRY_SCRIPT}}`
 
-Every successful EXML compilation also writes `.kurot/skin-parts.d.ts`. It
-augments `@kurot/ui`'s `SkinPartsMap` with the exact named parts and runtime
-types found in each compiled skin. The generated file is included by the
-template `tsconfig.json`, ignored by git, and never enters browser or release
-bundles.
+## KUI XML compilation
 
-`exml.namespaces` remains available for advanced manual namespace barrels, but
-its prefix must not conflict with `exml.components.namespace`.
+KUI XML is the only authored UI format. A skin declares its runtime target and
+whether it is the default skin directly on the document root:
 
-### Custom component lifecycle
-
-Select the generated part shape through the skin class name and initialize
-skin-dependent behavior in `onSkinReady()`:
-
-```ts
-import { Component } from '@kurot/ui';
-
-export class BattlePanel extends Component<'game.ui.BattlePanelSkin'> {
-	protected override onSkinReady(): void {
-		super.onSkinReady();
-		this.skinParts.groupField.visible = true;
-	}
-}
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<Skin xmlns="https://kurot.dev/ui/1"
+      id="skins.ButtonSkin"
+      version="2"
+      target="kui.Button"
+      default="true">
+    <Group id="root" minWidth="100" minHeight="50">
+        <Label id="labelDisplay" horizontalCenter="0" verticalCenter="0" />
+    </Group>
+</Skin>
 ```
 
-The event-based equivalent is useful when initialization is composed externally:
+The pipeline is:
 
-```ts
-import { UIEvent } from '@kurot/ui';
-
-this.once(UIEvent.CREATION_COMPLETE, this.onCreationComplete);
+```text
+.kui.xml → UIDocument → SkinIR → ESM skin factory → theme bundle
 ```
 
-Use `onSkinReady()` to initialize logic that depends on skin parts and
-`onSkinRemoved()` to release listeners or other bindings before replacement.
-`childrenCreated()` and `UIEvent.CREATION_COMPLETE` run once for the component's
-initial creation and are not skin-replacement hooks.
-
-UI 2.0 no longer copies part names onto component instances and no longer
-supports `setSkinPart()`, `partAdded()`, or `partRemoved()`. Read parts through
-`this.skinParts` only while the skin-ready lifecycle is active.
+Default skin mappings are derived from `target` and `default`; the build writes
+`default.thm.json` with the mappings and the generated `skinsJs` module path.
+Duplicate defaults are errors. Unknown tags are warnings in normal development
+and errors under strict or release builds.
 
-EXML skins compiled by the CLI are registered under their complete `class`
-attribute, so an Egret-style value such as
-`skinName = "game.ui.BattlePanelSkin"` works when that EXML is included in the
-loaded theme bundle. A component covered by the theme's `skins` mapping normally
-does not need to assign `skinName` itself. Hand-written `Skin` subclasses may be
-imported and assigned directly instead of using a string.
+Successful compilation also writes `.kurot/skin-parts.d.ts`. It augments the UI
+runtime with the exact named parts and types declared by each skin. This file is
+editor-only, ignored by git, and never enters browser bundles.
 
-### Compilation Pipeline
+## Reusable components
 
-All `.exml` skins compile into a single ESM module — `js/default.thm.js` (dev)
-or `js/default.thm.min_<hash>.js` (release) — that registers each skin factory.
-`default.thm.json` keeps only the component→skin mapping plus a `skinsJs`
-pointer to that module, which the runtime `Theme` imports. No `.exml` is shipped.
+Convention-based reusable components pair:
 
-```
-resource/skins/**/*.exml
-        ↓ parseXML()
-    XML Element Tree
-        ↓ parseEXML()
-       SkinIR
-        ↓ generateCode({ format: 'esm' })
-    per-skin ESM factories
-        ↓ esbuild bundle (+ minify in release)
-    js/default.thm[.min_<hash>].js   (skins register on globalThis)
+```text
+src/components/<path>/<Name>.ts
+resource/ui/components/<path>/<Name>Skin.kui.xml
 ```
 
-## Project Structure
+The TypeScript module must export `<Name>`. The paired skin must target
+`<namespace>.<Name>`. The CLI exposes the component as `<namespace>:<Name>` in
+KUI XML, refreshes the namespace bundle, and emits development catalog data at
+`.kurot/component-catalog.json`.
 
-A project created with the default template (`game`) has the following structure:
+Use `onSkinReady()` for logic that needs skin parts and `onSkinRemoved()` for
+cleanup before a skin replacement. Access generated parts through
+`this.skinParts`.
 
-```
+## Generated project shape
+
+```text
 my-game/
-├── .kurot/
-│   └── skin-parts.d.ts        # Generated typed EXML part declarations
-├── .gitignore                 # Excludes .kurot and build/dependency output
-├── kurot.config.ts          # Project config (includes exml options)
-├── package.json               # Dependencies & scripts
-├── tsconfig.json              # TypeScript config
-├── template/
-│   └── web/
-│       └── index.html            # Editable output page template
+├── .kurot/skin-parts.d.ts
+├── kurot.config.ts
 ├── resource/
-│   ├── default.res.json       # Resource config
-│   ├── default.thm.json       # Theme file: component → skin mapping
-│   └── skins/                 # EXML skin directory
-│       ├── components/        # Reusable component skins (standard eui:Skin)
-│       └── eui/               # 21 built-in EUI component skins
-│           ├── ButtonSkin.exml
-│           ├── ...
-│           └── ViewStackSkin.exml
-└── src/
-    ├── components/            # Reusable component TypeScript classes
-    ├── Main.ts                # Entry: class Main extends Sprite
-    └── LoadingUI.ts           # Loading progress display
-```
-
-## Quick Start
-
-```bash
-# Full-featured game project (default)
-npx @kurot/cli create my-game
-cd my-game && pnpm install
-pnpm dev
-
-# Minimal project
-npx @kurot/cli create my-lib --template empty
-cd my-lib && pnpm install
-pnpm dev
+│   ├── default.res.json
+│   ├── assets/
+│   └── ui/
+│       ├── components/
+│       └── skins/*.kui.xml
+├── src/
+│   ├── components/
+│   ├── LoadingUI.ts
+│   └── Main.ts
+└── template/web/index.html
 ```

package/dist/core/components/discover-components.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"discover-components.d.ts","sourceRoot":"","sources":["../../../src/core/components/discover-components.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,mBAAmB,GAAG,SAAS,GACzC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAqF7B;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,gBAAgB,EAAE,CAAC;CACxC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhB"}
+{"version":3,"file":"discover-components.d.ts","sourceRoot":"","sources":["../../../src/core/components/discover-components.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE3E;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,mBAAmB,GAAG,SAAS,GACzC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAsF7B;AAED;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,gBAAgB,EAAE,CAAC;CACxC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGhB"}

package/dist/core/components/discover-components.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
+import { parseUIDocument } from '@kurot/ui-document';
 import { ConfigError } from '../errors.js';
-import { localName, parseXML } from '../exml/index.js';
 /**
  * Discovers reusable component source/skin pairs using the configured
  * directory convention.
@@ -11,7 +11,7 @@ export async function discoverComponents(root, convention) {
         return [];
     const [sourceFiles, skinFiles] = await Promise.all([
         collectFiles(convention.sourceDir, file => file.endsWith('.ts') && !file.endsWith('.d.ts')),
-        collectFiles(convention.skinDir, file => file.endsWith('Skin.exml')),
+        collectFiles(convention.skinDir, file => file.endsWith('Skin.kui.xml')),
     ]);
     const sourceByPair = new Map(sourceFiles.map(file => [sourcePairKey(convention.sourceDir, file), file]));
     const skinByPair = new Map(skinFiles.map(file => [skinPairKey(convention.skinDir, file), file]));
@@ -29,7 +29,7 @@ export async function discoverComponents(root, convention) {
             continue;
         }
         if (!skin) {
-            errors.push(`Component source '${relative(root, source)}' has no matching skin '${pairKey}Skin.exml'.`);
+            errors.push(`Component source '${relative(root, source)}' has no matching skin '${pairKey}Skin.kui.xml'.`);
             continue;
         }
         const name = path.basename(source, '.ts');
@@ -54,20 +54,21 @@ export async function discoverComponents(root, convention) {
         }
         let skinClass;
         try {
-            const skinRoot = parseXML(await fs.readFile(skin, 'utf-8'));
-            if (localName(skinRoot.name) !== 'Skin') {
-                errors.push(`Component skin '${relative(root, skin)}' must use an eui:Skin root.`);
+            const skinDocument = parseUIDocument(await fs.readFile(skin, 'utf-8'));
+            if (skinDocument.assetKind !== 'appearance') {
+                errors.push(`Component skin '${relative(root, skin)}' must be a KUI Skin document.`);
                 continue;
             }
-            skinClass = skinRoot.attributes.find(attribute => attribute.name === 'class')?.value ?? '';
-            if (!skinClass) {
-                errors.push(`Component skin '${relative(root, skin)}' must declare a class attribute.`);
+            const targetType = `${convention.prefix}.${name}`;
+            if (skinDocument.contract.targetType !== targetType) {
+                errors.push(`Component skin '${relative(root, skin)}' must target '${targetType}'.`);
                 continue;
             }
+            skinClass = skinDocument.id;
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            errors.push(`Component skin '${relative(root, skin)}' is invalid EXML: ${message}`);
+            errors.push(`Component skin '${relative(root, skin)}' is invalid KUI XML: ${message}`);
             continue;
         }
         components.push({
@@ -124,7 +125,7 @@ function sourcePairKey(sourceDir, file) {
     return toPosix(path.relative(sourceDir, file).slice(0, -'.ts'.length));
 }
 function skinPairKey(skinDir, file) {
-    return toPosix(path.relative(skinDir, file).slice(0, -'Skin.exml'.length));
+    return toPosix(path.relative(skinDir, file).slice(0, -'Skin.kui.xml'.length));
 }
 function hasNamedClassExport(source, name) {
     source = stripComments(source);