@kurot/cli 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -3,7 +3,52 @@
 All notable changes to `@kurot/cli` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+and CLI command/configuration APIs follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+The early KUI XML contract follows the pre-1.0 `ui-document` kernel; authored
+format changes are documented explicitly in each release.
+
+## 3.1.0 — 2026-10-05
+
+### Added
+
+- Compile shared-catalog Label textFit/minFontSize properties and state sizes
+  unchanged. Drawing size remains a UI runtime derivation, never generated data.
+- Include public documentation in the npm package, including the compilation
+  contract, architecture and package context.
+
+### Dependencies
+
+- Require `@kurot/ui-document@^0.9.0` for the Label authoring catalog. KUI
+  rendering with shrinking requires UI 3.1.x and Core 2.1.x or later within
+  their respective majors; native engine packages remain project dependencies.
+- Keep semantic format version 2, literal string handling and resource defaults.
+  Existing EXML projects stay on CLI 1.3.x; no files are migrated automatically.
+
+### Tests
+
+- Verify fitting policy, minimum font size, authored size and state-size
+  assignments through KUI parsing and code generation.
+
+## 3.0.1 — 2026-10-04
+
+### XML Authoring Change
+
+- Require `@kurot/ui-document@^0.8.0`. Schema-defined string attributes,
+  including `text`, `label` and state text, now compile as literal strings.
+  `text="100.80"` preserves its decimal formatting; `text="false"` stays text.
+  Old synthetic backslash type escapes are now literal characters and must be
+  removed explicitly. No automatic source migration is performed.
+
+### Changed
+
+- Align the compiler dependency and lockfile with the published document kernel.
+  Numeric/boolean properties, references, XML entities and schema-free collection
+  scalar inference retain their existing rules. Generated Skin APIs are unchanged.
+
+### Tests
+
+- Verify literal text, state text, real backslashes and typed properties through
+  parsing, code generation and the emitted theme bundle.
 
 ## 3.0.0 — 2026-10-03
 
@@ -204,13 +249,13 @@ change their project configuration.
 - `kurot dev --diagnostics jsonl`, which reserves stdout for independent
   `build-start`, `diagnostic`, `build-complete` and `server-ready` events.
 - Stable diagnostics for the following cases:
-  - `KUROT_EXML_UNKNOWN_TAG`
-  - `KUROT_EXML_COMPILE_FAILED`
-  - `KUROT_EXML_DECLARED_FILE_NOT_FOUND`
-  - `KUROT_THEME_FILE_NOT_FOUND`
-  - `KUROT_THEME_INVALID_JSON`
-  - `KUROT_THEME_SKIN_NOT_FOUND`
-  - `KUROT_WATCH_RELEASE_IGNORED`
+    - `KUROT_EXML_UNKNOWN_TAG`
+    - `KUROT_EXML_COMPILE_FAILED`
+    - `KUROT_EXML_DECLARED_FILE_NOT_FOUND`
+    - `KUROT_THEME_FILE_NOT_FOUND`
+    - `KUROT_THEME_INVALID_JSON`
+    - `KUROT_THEME_SKIN_NOT_FOUND`
+    - `KUROT_WATCH_RELEASE_IGNORED`
 
 ### Changed
 

package/README.md

@@ -3,15 +3,35 @@
 Build tooling for the Kurot UI Editor workflow. It uses esbuild, emits ES2022
 ESM, and compiles canonical KUI XML skins into runtime theme modules.
 
-> **Prepared release: 3.0.0.** Node.js 20 or later is required.
+> **Current release: 3.1.0.** Node.js 20 or later is required.
 
 > **Release scope:** The 3.x line is dedicated to Kurot Editor integration.
-> Existing game projects that use EXML, including CrashMaster, should remain on
+> Existing game projects that use EXML should remain on
 > `@kurot/cli@1.3.x`. The KUI toolchain is not an in-place project upgrade and does
 > not require those projects to change their configuration or UI assets.
 
 See [CHANGELOG.md](CHANGELOG.md) for release history.
 
+## Label text fitting in 3.1.0
+
+The shared ui-document 0.9.x catalog supports Label `textFit` and `minFontSize`
+in KUI XML:
+
+```xml
+<Skin xmlns="https://kurot.dev/ui/1" class="skins.AmountSkin" states="down">
+    <Label id="labelDisplay" text="KZT 10 000,00" width="140" size="24"
+           multiline="false" textFit="shrink" minFontSize="16" size.down="20" />
+</Skin>
+```
+
+The compiler emits the policy, base size and state overrides unchanged. UI
+derives the drawing size after layout validation. Rendering this capability
+requires `@kurot/ui@^3.1.0` and `@kurot/core@^2.1.0` in the application.
+Explicit `multiline="false"` means one unwrapped first line; remove it or set
+it to true for text intended to wrap. Files are not migrated automatically.
+See the [compilation contract](docs/label-text-layout.md) and
+[native Label contract](../ui/docs/label-text-layout.md).
+
 ## Usage
 
 The CLI does not require a global install.
@@ -25,7 +45,7 @@ pnpm dev
 
 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
+`pnpm add -D @kurot/cli@^3.1.0`. Existing EXML projects should keep their current
 1.3.x dependency.
 
 ## Commands
@@ -76,25 +96,25 @@ 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,
-    },
-    ui: {
-        sourceDir: 'resource/ui',
-        components: {
-            namespace: 'game',
-            sourceDir: 'src/components',
-            skinDir: 'resource/ui/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',
+		},
+	},
 };
 ```
 
@@ -133,6 +153,15 @@ use `property.state` on the affected node, so internal graphics remain unnamed.
 Image sources use their resource key directly, for example
 `source="button_up_png"`.
 
+Version 3.1.0 uses `@kurot/ui-document@^0.9.0` and its literal-string XML rules.
+For example, `<Label text="100.80" text.down="false" size="48" />` compiles
+the exact strings `100.80` and `false`, while the font size stays numeric.
+String properties no longer add or remove backslash type escapes. Remove old
+synthetic prefixes such as the one in `text="\100.80"` explicitly; real
+backslashes remain text. XML entities and typed collection data retain their
+existing rules. Source files are not migrated automatically. Editor and CLI
+must adopt the same [XML value contract](../ui-document/docs/kui-xml.md#values).
+
 The pipeline is:
 
 ```text
@@ -159,8 +188,9 @@ src/components/<path>/<Name>.ts
 resource/ui/components/<path>/<Name>Skin.kui.xml
 ```
 
-The TypeScript module must export `<Name>`. The paired skin must target
-`<namespace>.<Name>`. The CLI exposes the component as `<namespace>:<Name>` in
+The TypeScript module must export `<Name>`. The paired skin declares its generated
+class with `class`, for example `class="skins.ActionCardSkin"`; the source/skin
+pair supplies the host association. 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`.
 
@@ -193,7 +223,7 @@ KUI builds validate `resource/default.res.json` and inherit image or sheet-frame
 `scale9grid` values into compiled `Image.scale9Grid` when XML does not set one.
 Local grids and `scale9Grid="false"` take priority. Development mode rebuilds
 skins after manifest edits; a malformed manifest leaves the last good Skin
-bundle in place. This release requires `@kurot/ui-document@^0.7.0`.
+bundle in place. The current CLI requires `@kurot/ui-document@^0.9.0`.
 
 Sheet `subkeys` must be an object-valued frame map. Refresh old sheets in the
 Editor before upgrading a KUI project; string-valued subkeys now fail the build.

package/docs/ai-context.md

@@ -0,0 +1,160 @@
+# @kurot/cli — AI context map
+
+Read this before exploring `src/`. [`architecture.md`](./architecture.md)
+explains the plugin pipeline. The package is `@kurot/cli@3.1.0`, runs on
+Node.js 20+, and is installed as a project dev dependency.
+
+## Directory map
+
+```text
+src/
+├── index.ts                       Commander entry
+├── define.ts                      public configuration type exports
+├── commands/                      build, dev, create, clean
+├── core/
+│   ├── config.ts                  configuration loading and validation
+│   ├── project.ts                 resolved paths, dependencies, namespaces
+│   ├── pipeline.ts                BuildContext and ordered plugin runner
+│   ├── dev-server.ts              static server and watchers
+│   ├── diagnostics/               stable codes and JSON/JSONL output
+│   ├── components/                reusable component discovery
+│   ├── kui/                       UIDocument → SkinIR → ESM compiler
+│   └── plugins/                   build stages
+└── utils/
+```
+
+Project templates are under `templates/game` and `templates/empty`.
+
+## KUI compilation
+
+`.kui.xml` is the only authored UI format. `compile-kui.ts` recursively scans
+`ui.sourceDir` and parses every document with `@kurot/ui-document`. Appearance
+assets are adapted by `kui/kui-parser.ts` to the compiler-private `SkinIR`,
+then `skin-module-builder.ts` bundles generated factories.
+
+A Skin document root declares `class`, the generated skin registration name,
+and may declare `states`. The Skin is the visual root container: its properties
+and layout apply to the runtime Skin, and its direct visual children become
+`skin.elementsContent` without an extra Group. Overrides use local
+`property.state` attributes. Storage IDs and runtime mapping metadata are not
+authored XML fields.
+
+CLI 3.1.0 requires `@kurot/ui-document@^0.9.0`. Schema-defined strings, including
+numeric/boolean-looking text and state text, are literal attributes without
+backslash type escaping. Old synthetic prefixes become literal characters;
+do not migrate them silently. Numeric/boolean properties and schema-free
+collection fields retain their existing rules.
+
+The theme JSON at `resource/default.thm.json` is fixed generated output. It is
+derived from built-in naming conventions and configured project component
+pairs, and contains `skins` plus `skinsJs`; it is never read as an authored
+input. Duplicate conventional mappings are errors.
+
+`SkinIR` is intentionally smaller than `UIDocument`. It contains resolved
+runtime classes, assignments, visual children, layout descriptor children,
+and state `SetProperty` overrides. Reuse, data contracts, actions, and editor
+transactions stay in `@kurot/ui-document` and `@kurot/ui-runtime`.
+
+Successful compilation writes `.kurot/skin-parts.d.ts` from the same IR. Every
+explicitly identified node inside the Skin is a skin part, with its `id`
+as the part name. Internal nodes can omit `id`; the declaration augments
+`SkinPartsMap` and narrows matching exported
+component classes. The file is development metadata and is excluded from
+runtime output.
+
+## Reusable components
+
+With `ui.components`, `<Name>.ts` under `sourceDir` pairs with
+`<Name>Skin.kui.xml` at the same relative path under `skinDir`. The source must
+export `<Name>`; the paired Skin supplies its own `class`. Discovery creates the
+namespace entry, skin association, and development component catalog. Component
+names must be unique inside the configured namespace.
+
+Manual `ui.namespaces` entries remain available for project barrel files. A
+manual prefix cannot conflict with `ui.components.namespace`.
+
+## Non-obvious behavior
+
+- `--watch` uses development mode even when `--release` is also supplied.
+- Real KUI parse or code-generation failures abort the current build. Dev watch
+  keeps the last successful bundle and retries on the next edit.
+- Unknown KUI tags are warnings in normal development, and errors under
+  `--strict` or release policy.
+- Machine diagnostic modes own stdout: build emits one JSON result; dev emits
+  JSONL lifecycle events.
+- `compileCustomNamespaces` must precede `compileSource`. Application-relative
+  imports and generated `#ns/<prefix>` imports must resolve to one bundled class
+  identity.
+- Engine and custom namespace chunks share `ctx.outputs.engine` because the
+  import-map writer treats both as external specifier mappings.
+- Release bundles preserve class names. UI theme fallback uses constructor
+  names, so normal identifier minification would break skin lookup.
+- The Skin module builder stages output in a temporary directory and installs a
+  bundle only after every Skin succeeds.
+- `cleanOutput` wipes the active output directory at the start of each build.
+  The standalone `clean` command removes both development and release output.
+- `create` queries the npm registry for current Kurot package versions and falls
+  back to `latest` if the request fails.
+- Release output is timestamped and `manifest.json` exists only in release.
+
+## Plugin order
+
+`defaultPlugins()` currently runs:
+
+1. clean output;
+2. compile KUI;
+3. compile engine packages;
+4. compile project namespaces;
+5. write the development component catalog;
+6. compile application source;
+7. generate HTML;
+8. write the release manifest;
+9. copy runtime assets.
+
+Do not reorder namespace or source compilation without reviewing externalization
+in `namespace-external-plugin.ts`.
+
+## Configuration lookup
+
+| Task                             | File                                         |
+| -------------------------------- | -------------------------------------------- |
+| Add or validate a config field   | `src/core/config.ts`                         |
+| Resolve an absolute project path | `src/core/project.ts`                        |
+| Change KUI scanning/theme output | `src/core/plugins/compile-kui.ts`            |
+| Change KUI node code generation  | `src/core/kui/kui-parser.ts`, `codegen.ts`   |
+| Add a built-in component tag     | `src/core/kui/registry.ts`                   |
+| Change generated part types      | `src/core/kui/skin-parts-declaration.ts`     |
+| Change component pairing         | `src/core/components/discover-components.ts` |
+| Change watch behavior            | `src/core/dev-server.ts`                     |
+| Change output HTML/import maps   | `src/core/plugins/generate-html.ts`          |
+| Change scaffolding               | `src/core/template.ts`, `templates/`         |
+| Add a diagnostic code            | `src/core/diagnostics/codes.ts`              |
+
+## Verification
+
+Run commands from this package directory:
+
+```bash
+pnpm build
+pnpm test
+```
+
+CLI end-to-end tests bind localhost and may require permission in a restricted
+execution environment.
+
+## Resource configuration change in 3.0.0
+
+KUI builds validate object subkeys, resolve resource nine-slice defaults, and
+watch the manifest during development. See
+[the resource-default contract](../../ui-document/docs/resource-nine-slice.md)
+for conversion and compilation boundaries.
+
+## Label text compilation in 3.1.0
+
+The compiler consumes the ui-document 0.9.x catalog and emits Label `textFit`,
+`minFontSize`, authored `size` and state-size overrides unchanged. Runtime
+observations are not authoring inputs, and fitting never becomes a build-time
+measurement. Rendering uses the application's UI >= 3.1.0 and Core >= 2.1.0
+within their respective majors. Neither engine is a CLI runtime dependency.
+See [text compilation](label-text-layout.md) and
+[native Label text layout](../../ui/docs/label-text-layout.md) for the boundary.

package/docs/architecture.md

@@ -0,0 +1,92 @@
+# CLI architecture
+
+`@kurot/cli` is a project-local Node.js tool. Commander owns the command layer,
+esbuild owns TypeScript and bundle output, and ordered `BuildPlugin` instances
+share a `BuildContext` through `core/pipeline.ts`.
+
+## Build pipeline
+
+`defaultPlugins()` runs these stages:
+
+```text
+clean output
+  → compile KUI
+  → compile engine packages
+  → compile custom namespaces
+  → write development component catalog
+  → compile application source
+  → generate HTML
+  → write release manifest
+  → copy runtime assets
+```
+
+KUI compilation runs first because skin factories can import project namespace
+components. Namespace and engine chunks are externalized consistently so the
+application, UI runtime, and generated skins share one class identity.
+
+## KUI boundary
+
+The CLI does not define a second UI document format. It parses `.kui.xml`
+through `@kurot/ui-document`, then adapts appearance documents to the private
+`SkinIR` used by the ESM code generator:
+
+```text
+KUI XML → UIDocument → SkinIR → skin factory → theme bundle
+```
+
+`SkinIR` contains runtime code-generation details only: resolved imports,
+factory variables, property assignments, semantic layout children, and state
+property overrides. Document contracts, reusable instances, data bindings, and
+actions remain `UIDocument` concepts.
+
+CLI 3.1.0 consumes ui-document 0.9.x for Label text-fitting metadata. The
+compiler emits `textFit`, `minFontSize`, base font sizes and state overrides;
+native UI owns measurement and derives drawing sizes after layout validation.
+See [Label compilation](label-text-layout.md). The application supplies UI
+3.1.x and Core 2.1.x or later within their respective majors.
+
+The authored `Skin` root supplies its generated `class` and optional state
+names. State values live on their target nodes as `property.state`. The compiler
+derives the theme map from built-in naming conventions and configured project
+component pairs, and rejects duplicate conventional mappings. The generated
+theme JSON is an output artifact, never an authored source.
+
+## Output ownership
+
+`BuildContext.outputs` carries generated filenames between plugins. Important
+entries include the application entry, theme script, namespace chunks, engine
+chunks, and `.kurot/skin-parts.d.ts`.
+
+Development builds preserve application source module structure under
+`bin-debug/`. Release builds create a timestamped directory under
+`bin-release/web/`, minify bundles, add content hashes, and write
+`manifest.json`. Static resources retain stable paths because application code
+addresses them by key or URL.
+
+## Development watchers
+
+The dev server has separate rebuild paths for application source, KUI XML, and
+convention-based reusable components. A component change can affect its source
+namespace, paired skin, generated type declaration, and editor catalog, so that
+path refreshes all four outputs as one operation. The server preserves the last
+successful output after an invalid edit.
+
+## Diagnostics
+
+Plugins report stable diagnostics to the collector rather than throwing on the
+first recoverable problem. Strict policy promotes supported warnings. Build
+JSON emits one final result; dev JSONL emits lifecycle events suitable for a
+long-running editor or agent process.
+
+## Main source areas
+
+```text
+src/core/config.ts                 project configuration
+src/core/project.ts                resolved project paths and namespaces
+src/core/pipeline.ts               build context and plugin runner
+src/core/kui/                      UIDocument-to-SkinIR compiler
+src/core/components/               reusable component discovery
+src/core/plugins/compile-kui.ts    KUI scan, theme derivation, bundle output
+src/core/plugins/                  remaining ordered build stages
+src/core/dev-server.ts             file watching and static server
+```

package/docs/label-text-layout.md

@@ -0,0 +1,59 @@
+# Label text compilation
+
+CLI 3.1.0 consumes ui-document 0.9.x and compiles KUI text-fitting properties
+through the existing UIDocument → SkinIR → ESM factory pipeline. The semantic
+document format remains version 2.
+
+## Example
+
+```xml
+<Skin xmlns="https://kurot.dev/ui/1" class="skins.AmountSkin" states="down">
+    <Label id="amount" text="100.80" width="60" size="24"
+           multiline="false" textFit="shrink" minFontSize="16" size.down="20" />
+</Skin>
+```
+
+The generated factory assigns the authored values:
+
+```js
+amount.multiline = false;
+amount.textFit = 'shrink';
+amount.minFontSize = 16;
+amount.size = 24;
+```
+
+The down-state size becomes a native `SetProperty('amount', 'size', 20)` override.
+The compiler does not measure fonts or change `size` based on text length,
+currency, locale or display bounds. Source XML remains authored data; neither
+derived sizes nor fitting diagnostics are persisted by compilation.
+
+## Runtime boundary
+
+- The application must install UI `^3.1.0` and Core `^2.1.0` for shrinking.
+  They remain application dependencies; CLI depends on the headless document
+  package rather than importing the engine into the build process.
+- `textFit` is `none` by default or `shrink` for ordinary single-line Labels.
+  Put a Button's policy on its `labelDisplay` skin part.
+- `minFontSize` defaults to 12 logical pixels and must be finite and >= 1.
+  A minimum greater than the authored size does not enlarge the text.
+- UI keeps `size` authored and derives `renderedSize` after layout validation.
+  State removal restores the authored base size before fitting again.
+- `renderedSize` and `textFitOverflow` are runtime observations; do not author
+  them in KUI XML.
+- Multiline Labels keep their base size; EditableText rejects shrinking.
+- Load fonts before measuring text. For late loading, native UI callers use
+  `label.invalidateSize()` after the font becomes ready.
+
+UI 3.1's public Label contract owns the full fitting, overflow, layout and
+font-readiness rules. ui-document 0.9's catalog describes the authoring fields.
+The build does not rewrite existing skins or apply project translation rules.
+
+## Migration
+
+In Core 2.1.0, explicit `multiline="false"` means one unwrapped first line.
+Remove that flag or set it to true where wrapping is intended. The literal-string
+XML contract is retained: a backslash followed by `n` stays literal text rather
+than becoming a hard separator.
+
+Existing EXML projects remain on CLI 1.3.x. The KUI release does not introduce
+an EXML migration or resource-format change.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/cli",
-	"version": "3.0.0",
+	"version": "3.1.0",
 	"description": "Kurot CLI - build tool for Kurot Editor KUI XML workflows",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",
@@ -12,6 +12,7 @@
 	},
 	"files": [
 		"dist",
+		"docs/**/*",
 		"templates",
 		"README.md",
 		"CHANGELOG.md",
@@ -27,7 +28,7 @@
 		"kurot": "tsx src/index.ts"
 	},
 	"dependencies": {
-		"@kurot/ui-document": "^0.7.0",
+		"@kurot/ui-document": "^0.9.0",
 		"commander": "^13.0.0",
 		"esbuild": "^0.25.0"
 	},