@kurot/ui 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to `@kurot/ui` are documented here.
 
 ---
 
+## [3.2.0] — 2026-10-08
+
+### Added
+
+- Export BitmapLabel, a native UI component wrapping Core BitmapText with normal
+  measurement, parent layout constraints, alignment, spacing and text bindings.
+- Accept a caller-owned BitmapFont or a configured font-resource name. Resolve
+  preloaded fonts synchronously and load missing fonts through Core's resource
+  singleton, reporting completion and loading/type errors through events.
+- Ignore superseded asynchronous font results, including A-to-B-to-A changes.
+  Font ownership remains with the resource cache or caller.
+
+### Dependencies and migration
+
+- Require `@kurot/core ^2.2.0` in peer and development dependencies for rendered
+  BitmapText, FontAnalyzer and pure text measurement. Upgrade older Core installs
+  and lockfiles before adopting UI 3.2.0.
+- Remove the local Core dependency override and build against published Core.
+  UI continues to depend only on Core; bitmap-font is Core's dependency.
+- BitmapLabel supports native code and programmatic skins. The ui-document
+  catalog, CLI KUI tags, Editor and ui-runtime materializers do not yet adopt it.
+
+### Tests and documentation
+
+- Cover layout and measurement, alignment, binding notifications, cached and
+  asynchronous font resolution, stale requests, invalid resources and errors.
+- Translate architecture documentation to English and correct outdated Skin,
+  theme-adapter, validation and virtual-layout descriptions against source.
+
+## [3.1.0] — 2026-10-05
+
+### Added
+
+- Single-line Label `textFit="shrink"` and `minFontSize`, with derived
+  `renderedSize` and `textFitOverflow` observations after validation.
+- Export the `TextFitMode` type (`none` or `shrink`) from the public barrel.
+- Fit within actual label constraints, reserve outline allowance, restore the
+  authored size for shorter text, and refresh metrics after font readiness.
+- Include public documentation in the npm package, including the Label text
+  contract, architecture and package context.
+
+### Changed
+
+- Label defaults to multiline; explicit false means one unwrapped first line.
+  EditableText keeps its single-line default and rejects shrinking.
+- Preserve authored size through native state apply/remove and avoid feeding
+  automatic measured dimensions back into fitting.
+
+### Migration
+
+- Explicit `multiline="false"` now means one unwrapped first line. Remove the
+  flag or set it to true for text intended to wrap; files are not migrated.
+- Set fitting policy on a Button's `labelDisplay` skin part. Multiline Labels
+  retain their authored size, and EditableText rejects `textFit="shrink"`.
+- Load fonts before measurement where possible. After a font becomes ready
+  late, call `label.invalidateSize()` to refresh fitting and Core line metrics.
+
+### Dependencies
+
+- Require `@kurot/core@^2.1.0` in peer and development dependencies for
+  `TextField.invalidateTextMetrics()`. Core 2.0.x is no longer sufficient.
+- KUI authoring uses ui-document 0.9.x and matching CLI/ui-runtime releases;
+  native UI still depends only on Core.
+
+### Tests
+
+- Verify native Button label fitting uses the label region, preserves authored
+  sizes through disabled-state transitions, and follows active skin replacement.
+- Cover minimum overflow, fractional sizes, outlines, hard separators, password
+  display, late font readiness, automatic dimensions and parent layout changes.
+- Verify real regular/bold fonts and Chinese fallback with 16 browser checks
+  each on WebGL and Canvas, including Unicode wrapping and state restoration.
+
 ## [3.0.0] — 2026-10-03
 
 ### Breaking
@@ -337,7 +410,6 @@ protected override onSkinRemoved(): void {
 - **Button: remove dead `_autoRepeat` property** — getter/setter existed but no code consumed the value. Simplified `partAdded` to compare `partName` instead of `instance === this.labelDisplay` (eliminates non-null assertions).
 - **ListBase: clean up `adjustSelection` and `dataProviderRefreshed`** — removed identical if/else branches and premature `PropertyEvent` dispatch (silent adjustment per egret semantics, events deferred to `commitProperties`).
 
-
 ## [1.0.6] — 2026-08-05
 
 ### Fixed
@@ -354,10 +426,10 @@ protected override onSkinRemoved(): void {
 ### Fixed
 
 - **Component (`enabled` / `touchEnabled` cycle completely broken)**: Three interdependent issues in the `enabled` setter and `touchEnabled` accessor:
-  1. **`touchEnabled` getter always returned `undefined`**. Overriding only the setter on `Component.prototype` creates a JS accessor with `get: undefined`, which shadows the inherited `DisplayObject` getter. Every read of `.touchEnabled` on any Component subclass (Button, Label, TextInput, …) silently returned `undefined` instead of the real boolean.
-  2. **`enabled = false` never disabled hit-testing**. The setter delegated to `this.touchEnabled = false`, but `Component`'s own `touchEnabled` setter contains a guard (`if (this._enabled) super.touchEnabled = value`) that skips the display-level write when the component is already disabled. The result: a disabled button still captured touches and blocked elements behind it — unlike egret, where disabled components are excluded from hit-testing.
-  3. **disable → enable permanently broke touch**. The disable path clobbered `_explicitTouchEnabled` to `false`, and the re-enable path restored `$touchEnabled` from that corrupted value — leaving every Component subclass permanently non-touchable after a single disable/enable cycle.
-  The fix matches egret's `$setEnabled`: the `enabled` setter now writes `touchEnabled` / `touchChildren` directly at the display-object level via `super.touchEnabled` / `super.touchChildren`, bypassing the guarded setters. Additionally, `touchEnabled` and `touchChildren` getters are now explicitly overridden to delegate to `super`, un-shadowing the parent accessor.
+    1. **`touchEnabled` getter always returned `undefined`**. Overriding only the setter on `Component.prototype` creates a JS accessor with `get: undefined`, which shadows the inherited `DisplayObject` getter. Every read of `.touchEnabled` on any Component subclass (Button, Label, TextInput, …) silently returned `undefined` instead of the real boolean.
+    2. **`enabled = false` never disabled hit-testing**. The setter delegated to `this.touchEnabled = false`, but `Component`'s own `touchEnabled` setter contains a guard (`if (this._enabled) super.touchEnabled = value`) that skips the display-level write when the component is already disabled. The result: a disabled button still captured touches and blocked elements behind it — unlike egret, where disabled components are excluded from hit-testing.
+    3. **disable → enable permanently broke touch**. The disable path clobbered `_explicitTouchEnabled` to `false`, and the re-enable path restored `$touchEnabled` from that corrupted value — leaving every Component subclass permanently non-touchable after a single disable/enable cycle.
+       The fix matches egret's `$setEnabled`: the `enabled` setter now writes `touchEnabled` / `touchChildren` directly at the display-object level via `super.touchEnabled` / `super.touchChildren`, bypassing the guarded setters. Additionally, `touchEnabled` and `touchChildren` getters are now explicitly overridden to delegate to `super`, un-shadowing the parent accessor.
 - **Skin factory: ES class constructors crash via `.call(this)`**: 1.0.4 fixed the EXML binding `this` context by switching from `new factory()` to `factory.call(this)`, but `call()` throws `TypeError` on genuine ES class constructors (the documented `skinName: (new () => Skin)` path). Now detects class constructors via `Function.prototype.toString()` and falls back to `new`.
 - **Button: `selected` PropertyEvent never dispatched**: `selected` setter did not dispatch `PropertyEvent('selected')`, breaking data bindings (`{selected}`) on Buttons and ToggleButtons. Now dispatched after `_selected` is updated.
 - **Button: redundant `touchEnabled` override after `enabled` setter fix**: The now-fixed `Component.enabled` setter handles `touchEnabled`/`touchChildren` at the display-object level. Button's own `this.touchEnabled = value` line was overwriting that with the user's new value regardless of pre-disable intent, so it has been removed.
@@ -380,7 +452,7 @@ protected override onSkinRemoved(): void {
 - **Scroller (viewport orphaned on skin re-apply)**: Egret overrides `setSkin` to re-`addChildAt(viewport, 0)` after the skin (scroll bars) is applied so the viewport is never orphaned and sits beneath the bars. Kurot was missing this override; now added.
 - **Scroller (static-object field)**: `private static readonly _vpBounds = new Rectangle()` was converted to a module-level constant, applying the same remedy as the HSlider/VSlider class-name-corruption fix from 1.0.3.
 - **ItemRenderer (labelDisplay auto-sync)**: Added `partAdded`/`partRemoved`/`dataChanged` to auto-sync `labelDisplay.text = String(data)`, matching Egret's binding fallback. Previously the default ItemRenderer had no mechanism to push `data` into the label.
-- **Label (_widthConstraint)**: Added `_widthConstraint` mechanism (`setLayoutBoundsSize` override + `measure` update) so that when a parent layout constrains the Label's width, the measured height correctly accounts for text wrapping. Matches Egret's Label L695-710.
+- **Label (\_widthConstraint)**: Added `_widthConstraint` mechanism (`setLayoutBoundsSize` override + `measure` update) so that when a parent layout constrains the Label's width, the measured height correctly accounts for text wrapping. Matches Egret's Label L695-710.
 - **Label (text PropertyEvent)**: `text` setter now dispatches `PropertyEvent('text')` for data binding.
 - **Panel (elementsContent)**: Added missing `elementsContent` setter so that EXML-declared children of `<eui:Panel>` are added to the display list. Previously they were silently discarded because Panel (via Component) had no such setter.
 - **Panel (drag includeInLayout)**: Dragging the moveArea now sets `includeInLayout = false` to prevent the parent layout from snapping the panel back.

package/README.md

@@ -2,22 +2,75 @@
 
 UI component framework for [@kurot/core](https://github.com/kurot-engine/kurot/tree/main/packages/core). Migrated from Egret EUI, rewritten in modern TypeScript with clean class inheritance — no namespace hacks, no prototype manipulation.
 
-> **Prepared release: 3.0.0.** Requires `@kurot/core@^2.0.0`. Targets ES2022 + evergreen browsers, same as core.
+> **Package version: 3.2.0.** Requires `@kurot/core@^2.2.0`. Targets ES2022 + evergreen browsers, same as core.
 
 For the full list of changes in this release, see [CHANGELOG.md](./CHANGELOG.md).
 
+## Label text fitting in 3.1.0
+
+Single-line Labels can shrink their drawing size to fit the available region:
+
+```ts
+import { Label } from '@kurot/ui';
+
+const amount = new Label('KZT 10 000,00');
+amount.width = 140;
+amount.size = 24;
+amount.multiline = false;
+amount.textFit = 'shrink';
+amount.minFontSize = 16;
+```
+
+`size` stays authored; `renderedSize` and `textFitOverflow` are read-only results
+after layout validation. Shorter text or larger bounds restore the base size.
+Put a Button's fitting policy on its `labelDisplay` skin part, so icon spacing
+and state overrides are respected. EditableText rejects shrinking; multiline
+Labels retain their base size.
+
+Label defaults to multiline, while explicit `multiline = false` displays one
+unwrapped first line. Remove an old false flag or set it to true for text
+intended to wrap. Files are not migrated automatically. Load fonts before
+measurement; after late loading, call `label.invalidateSize()` to refresh
+metrics even if the family name is unchanged.
+
+See the [text layout and fitting contract](docs/label-text-layout.md). Fitting
+metadata was introduced in ui-document 0.9.0 and remains supported in 0.11.0.
+Current CLI-built KUI projects use published CLI 3.3.0 with ui-document `^0.11.0`;
+Published ui-runtime 0.8.2 uses the same kernel range. Programmatic UI depends
+only on Core.
+
 ## Installation
 
 ```bash
-pnpm add @kurot/ui @kurot/core
+pnpm add @kurot/ui@^3.2.0 @kurot/core@^2.2.0
 ```
 
 `@kurot/ui` declares `@kurot/core` as a peer dependency. Install both packages explicitly so the application controls the resolved core version.
 
-Upgrade Core to 2.x together with UI 3.x. Refresh old sheet manifests with
+UI 3.2 requires Core 2.2.0 or later within Core 2.x for BitmapText rendering and
+font resources. Core installs its published bitmap-font dependency automatically.
+Refresh older Core/UI lockfiles and old sheet manifests with
 string-valued `subkeys` in Kurot Editor before launching the application.
 See the [resource migration guide](../ui-document/docs/resource-nine-slice.md).
 
+## Project style colors
+
+CLI 3.3.0 resolves Label presets and named colors from the optional
+`resource/config/style.json` into native UI properties, including state overrides:
+
+```xml
+<Label id="labelDisplay" textColor="#FF9900"
+       textColor.disabled="@style:colors:disabled-text" />
+```
+
+The Label belongs to a Skin declaring the `disabled` state. Native Skin state
+handling applies the compiled numeric color and restores the base color on
+leaving that state. The same reference syntax works for base color properties.
+UI does not read style.json or evaluate XML references itself; programmatic
+components assign numeric colors. This release does not introduce complete
+typography presets or automatic live theme switching. See the
+[project style contract](../ui-document/docs/project-styles.md).
+
 ## Quick Start
 
 ```ts
@@ -98,11 +151,7 @@ class MyButtonSkin extends Skin {
 		this.bg = new Rect(120, 36, 0x6c5ce7);
 		this.skinParts = ['bg'];
 		this.elementsContent = [this.bg];
-		this.states = [
-			new State('up'),
-			new State('down', [new SetProperty('bg', 'fillColor', 0x5a4bd1)]),
-			new State('disabled', [new SetProperty('bg', 'fillColor', 0x636e72)]),
-		];
+		this.states = [new State('up'), new State('down', [new SetProperty('bg', 'fillColor', 0x5a4bd1)]), new State('disabled', [new SetProperty('bg', 'fillColor', 0x636e72)])];
 	}
 }
 
@@ -134,18 +183,12 @@ export class ConfirmPanel extends Component {
 
 	protected override onSkinReady(): void {
 		super.onSkinReady();
-		this.skinParts.btnConfirm.addEventListener(
-			TouchEvent.TOUCH_TAP,
-			this.onConfirm,
-		);
+		this.skinParts.btnConfirm.addEventListener(TouchEvent.TOUCH_TAP, this.onConfirm);
 		this.skinParts.lblMessage.text = 'Continue?';
 	}
 
 	protected override onSkinRemoved(): void {
-		this.skinParts.btnConfirm.removeEventListener(
-			TouchEvent.TOUCH_TAP,
-			this.onConfirm,
-		);
+		this.skinParts.btnConfirm.removeEventListener(TouchEvent.TOUCH_TAP, this.onConfirm);
 		super.onSkinRemoved();
 	}
 
@@ -179,19 +222,20 @@ dynamic properties; use `this.skinParts.<name>` during the ready lifecycle.
 
 ### Basic Controls
 
-| Component      | Description                                                                 |
-| -------------- | --------------------------------------------------------------------------- |
-| `Label`        | Text display. Wraps `TextField` in the UI lifecycle.                        |
-| `Button`       | Tappable button with `up`/`down`/`disabled` states and `labelDisplay` part. |
-| `CheckBox`     | Toggle button. Dispatches `Event.CHANGE` on selection change.               |
-| `RadioButton`  | Mutually exclusive toggle. Use `groupName` to link buttons.                 |
-| `ToggleButton` | Base for toggle-style buttons.                                              |
-| `ToggleSwitch` | Binary on/off switch (visual variant of `ToggleButton`).                    |
-| `ProgressBar`  | Value indicator. Inject `thumb` (a `Component`) as the fill part.           |
-| `HSlider`      | Horizontal slider. Inject `thumb` and `track` skin parts; default range 0–100. |
-| `VSlider`      | Vertical slider. Inject `thumb` and `track` skin parts; default range 0–100.   |
-| `Rect`         | Filled/stroked rectangle. Supports `fillColor`, `strokeColor`, `fillAlpha`. |
-| `Image`        | Bitmap display. Supports URL string or `Texture`, `scale9Grid`, `fillMode`. |
+| Component      | Description                                                                     |
+| -------------- | ------------------------------------------------------------------------------- |
+| `Label`        | Text display. Wraps `TextField` in the UI lifecycle.                            |
+| `BitmapLabel`  | Bitmap-font display. Wraps BitmapText with font resources, layout and bindings. |
+| `Button`       | Tappable button with `up`/`down`/`disabled` states and `labelDisplay` part.     |
+| `CheckBox`     | Toggle button. Dispatches `Event.CHANGE` on selection change.                   |
+| `RadioButton`  | Mutually exclusive toggle. Use `groupName` to link buttons.                     |
+| `ToggleButton` | Base for toggle-style buttons.                                                  |
+| `ToggleSwitch` | Binary on/off switch (visual variant of `ToggleButton`).                        |
+| `ProgressBar`  | Value indicator. Inject `thumb` (a `Component`) as the fill part.               |
+| `HSlider`      | Horizontal slider. Inject `thumb` and `track` skin parts; default range 0–100.  |
+| `VSlider`      | Vertical slider. Inject `thumb` and `track` skin parts; default range 0–100.    |
+| `Rect`         | Filled/stroked rectangle. Supports `fillColor`, `strokeColor`, `fillAlpha`.     |
+| `Image`        | Bitmap display. Supports URL string or `Texture`, `scale9Grid`, `fillMode`.     |
 
 Both sliders inherit Range's default `minimum = 0` and `maximum = 100`.
 Set either bound explicitly when a control needs a different range.
@@ -221,13 +265,13 @@ gesture. Set `visible="true" autoVisibility="false"` to keep a bar visible.
 
 ### Data-Driven
 
-| Component      | Description                                                                                 |
-| -------------- | ------------------------------------------------------------------------------------------- |
-| `DataGroup`    | Renders a data collection using item renderers. Supports virtual layout for large datasets. |
-| `List`         | `DataGroup` with tap-to-select. Dispatches `ItemTapEvent.ITEM_TAP`.                         |
-| `TabBar`       | Horizontal tab strip driven by `dataProvider`. Dispatches `ItemTapEvent.ITEM_TAP`.          |
+| Component      | Description                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------------------- |
+| `DataGroup`    | Renders a data collection using item renderers. Supports virtual layout for large datasets.     |
+| `List`         | `DataGroup` with tap-to-select. Dispatches `ItemTapEvent.ITEM_TAP`.                             |
+| `TabBar`       | Horizontal tab strip driven by `dataProvider`. Dispatches `ItemTapEvent.ITEM_TAP`.              |
 | `ComboBox`     | Drop-down selector. Tapping toggles a `list` skin part; dispatches `Event.CHANGE` on selection. |
-| `ItemRenderer` | Base class for custom item renderers. Override `dataChanged()` to update visuals.           |
+| `ItemRenderer` | Base class for custom item renderers. Override `dataChanged()` to update visuals.               |
 
 ### Scroll Bars
 
@@ -256,10 +300,12 @@ data.addItem('Durian');
 data.addItemAt('Elderberry', 1);
 data.removeItemAt(0);
 data.replaceItemAt('Fig', 0);
-data.sortOn('name'); // sort by field
-data.sort((a, b) => (a > b ? 1 : -1)); // custom sort
+data.sort((a, b) => String(a).localeCompare(String(b)));
 data.filterFunction(item => item !== 'Fig');
 data.refresh(); // notify view after manual source changes
+
+const records = new ArrayCollection([{ name: 'Pear' }, { name: 'Apple' }]);
+records.sortOn('name'); // sort records by field
 ```
 
 ## Virtual Layout
@@ -310,29 +356,43 @@ component.percentHeight = 100;
 ## View States
 
 ```ts
-import { State, SetProperty, AddItems } from '@kurot/ui';
+import { Label, Rect, Skin, State, SetProperty } from '@kurot/ui';
 
-class MyButtonSkin extends Skin {
-	states = [
-		new State('up'),
-		new State('down', [new SetProperty('bg', 'fillColor', 0x5a4bd1)]),
-		new State('disabled', [
-			new SetProperty('bg', 'fillColor', 0x636e72),
-			new SetProperty('lbl', 'textColor', 0xb2bec3),
-		]),
-	];
+class StatefulButtonSkin extends Skin {
+	constructor() {
+		super();
+		const bg = new Rect(120, 36, 0x6c5ce7);
+		const labelDisplay = new Label();
+		labelDisplay.textColor = 0xffffff;
+		labelDisplay.horizontalCenter = 0;
+		labelDisplay.verticalCenter = 0;
+		this.setPart('bg', bg);
+		this.setPart('labelDisplay', labelDisplay);
+		this.skinParts = ['labelDisplay'];
+		this.elementsContent = [bg, labelDisplay];
+		this.states = [
+			new State('up'),
+			new State('down', [new SetProperty('bg', 'fillColor', 0x5a4bd1)]),
+			new State('disabled', [new SetProperty('bg', 'fillColor', 0x636e72), new SetProperty('labelDisplay', 'textColor', 0xb2bec3)]),
+		];
+	}
 }
 ```
 
+Button selects `up`, `down` or `disabled` through its native behavior. Each
+state restores the previous property values before applying the next overrides.
+CLI-built skins generate the same `State`/`SetProperty` objects from XML
+attributes such as `textColor.disabled`.
+
 ## Events
 
-| Event                               | Dispatched by                   | Description                                          |
-| ----------------------------------- | ------------------------------- | ---------------------------------------------------- |
+| Event                               | Dispatched by                                                    | Description                                                        |
+| ----------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------ |
 | `Event.CHANGE`                      | `List`, `TabBar`, `ComboBox`, `CheckBox`, `RadioButton`, `Range` | Selection or value changed (user interaction only for List/TabBar) |
-| `ItemTapEvent.ITEM_TAP`             | `List`, `TabBar`                | Item tapped. Has `item`, `itemIndex`, `itemRenderer` |
-| `CollectionEvent.COLLECTION_CHANGE` | `ArrayCollection`               | Data added, removed, replaced, reset                 |
-| `UIEvent.CLOSING`                   | `Panel`                         | Close button tapped (cancelable)                     |
-| `UIEvent.CREATION_COMPLETE`         | Any `Component`                 | First `createChildren` completed                     |
+| `ItemTapEvent.ITEM_TAP`             | `List`, `TabBar`                                                 | Item tapped. Has `item`, `itemIndex`, `itemRenderer`               |
+| `CollectionEvent.COLLECTION_CHANGE` | `ArrayCollection`                                                | Data added, removed, replaced, reset                               |
+| `UIEvent.CLOSING`                   | `Panel`                                                          | Close button tapped (cancelable)                                   |
+| `UIEvent.CREATION_COMPLETE`         | Any `Component`                                                  | First `createChildren` completed                                   |
 
 ## UI Benchmark
 
@@ -347,11 +407,11 @@ report can distinguish a stable pool from per-frame renderer churn.
 
 The first complete Chromium run used 60 warmup frames and 300 measured frames:
 
-| Workload | Setup | Frame P95 | Render P95 | Draw calls | UI lifecycle result |
-| -------- | ----: | --------: | ---------: | ---------: | ------------------- |
-| 400-node static image UI | 8.50 ms | 10.20 ms | 0.20 ms | 1 | No repeated validation after stabilization |
-| 240-node transform/alpha animation | 3.90 ms | 10.00 ms | 0.30 ms | 1 | No measure or display-list validation |
-| 10,000-record virtual list | 6.90 ms | 9.90 ms | 0.50 ms | 5 | 19 renderers created and at most 19 live |
+| Workload                           |   Setup | Frame P95 | Render P95 | Draw calls | UI lifecycle result                        |
+| ---------------------------------- | ------: | --------: | ---------: | ---------: | ------------------------------------------ |
+| 400-node static image UI           | 8.50 ms |  10.20 ms |    0.20 ms |          1 | No repeated validation after stabilization |
+| 240-node transform/alpha animation | 3.90 ms |  10.00 ms |    0.30 ms |          1 | No measure or display-list validation      |
+| 10,000-record virtual list         | 6.90 ms |   9.90 ms |    0.50 ms |          5 | 19 renderers created and at most 19 live   |
 
 The transform workload recorded 72,000 `commitProperties` calls: 240 moving UI
 nodes × 300 measured frames. Multiple property changes on the same component
@@ -380,14 +440,39 @@ cross-framework ranking.
 
 ## Differences from Egret EUI
 
-|                | Egret EUI                   | @kurot/ui                          |
-| -------------- | --------------------------- | ------------------------------------ |
-| Namespace      | `eui.*` global              | ES Module named exports              |
-| Component base | `namespace` + `mixin`       | Standard class inheritance           |
-| Layout state   | Prototype-injected          | `UIState` delegation                 |
-| Authored skins | EXML runtime parser          | KUI XML compiled by `@kurot/cli`   |
-| Skin parts     | Incremental dynamic fields  | Atomic typed `skinParts`             |
-| Skin lifecycle | `partAdded` / `partRemoved` | `onSkinReady` / `onSkinRemoved`      |
-| `thisObject`   | Required in event listeners | Not needed — use arrow functions     |
-| Virtual layout | Default on                  | Opt-in via `useVirtualLayout = true` |
-| i18n           | Built-in                    | Not supported                        |
+|                | Egret EUI                   | @kurot/ui                                                   |
+| -------------- | --------------------------- | ----------------------------------------------------------- |
+| Namespace      | `eui.*` global              | ES Module named exports                                     |
+| Component base | `namespace` + `mixin`       | Standard class inheritance                                  |
+| Layout state   | Prototype-injected          | `UIState` delegation                                        |
+| Authored skins | EXML runtime parser         | KUI XML compiled by `@kurot/cli`                            |
+| Skin parts     | Incremental dynamic fields  | Atomic typed `skinParts`                                    |
+| Skin lifecycle | `partAdded` / `partRemoved` | `onSkinReady` / `onSkinRemoved`                             |
+| `thisObject`   | Required in event listeners | Not needed — use arrow functions                            |
+| Virtual layout | Default on                  | Opt-in via `useVirtualLayout = true`                        |
+| i18n           | Built-in                    | Project-managed translations; Core handles Unicode wrapping |
+
+## Bitmap labels in 3.2.0
+
+[BitmapLabel](docs/bitmap-label.md) wraps Core BitmapText with native UI layout,
+spacing, alignment and configured font-resource names:
+
+```ts
+import { BitmapLabel } from '@kurot/ui';
+
+const amount = new BitmapLabel('1,234.56');
+amount.font = 'number_font_fnt';
+amount.multiline = false;
+amount.height = 100;
+group.addChild(amount);
+```
+
+Register the font descriptor in Core's resource configuration before assigning
+its name, or assign a BitmapFont directly. The label borrows its font; the
+resource cache or caller retains ownership. Superseded async requests cannot
+replace a newer assignment. Successful named loads dispatch Event.COMPLETE;
+failed or incorrectly typed resources dispatch IOErrorEvent.IO_ERROR.
+
+The component supports native code and programmatic skins. Installed KUI
+compilers, the ui-document catalog, Editor and ui-runtime materializers do not
+yet adopt the BitmapLabel tag. Published UI 3.1.0 does not include the component.

package/dist/kurot/components/BitmapLabel.d.ts

@@ -0,0 +1,46 @@
+import { BitmapFont } from '@kurot/core';
+import { Component } from './Component.js';
+import type { IDisplayText } from '../core/IDisplayText.js';
+/**
+ * UI layout wrapper around BitmapText. String fonts are configured resource
+ * names; FontAnalyzer loads the descriptor and its page. Font ownership stays
+ * with the resource cache or the caller that supplied a BitmapFont.
+ */
+export declare class BitmapLabel extends Component implements IDisplayText {
+    private readonly _bitmapText;
+    private _font?;
+    private _fontChanged;
+    private _fontRequest;
+    private _widthConstraint;
+    constructor(text?: string);
+    get text(): string;
+    set text(value: string);
+    get font(): string | BitmapFont | undefined;
+    set font(value: string | BitmapFont | undefined);
+    get textAlign(): 'left' | 'center' | 'right';
+    set textAlign(value: 'left' | 'center' | 'right');
+    get verticalAlign(): 'top' | 'middle' | 'bottom';
+    set verticalAlign(value: 'top' | 'middle' | 'bottom');
+    get letterSpacing(): number;
+    set letterSpacing(value: number);
+    get lineSpacing(): number;
+    set lineSpacing(value: number);
+    get multiline(): boolean;
+    set multiline(value: boolean);
+    get smoothing(): boolean;
+    set smoothing(value: boolean);
+    /**
+     * Content metrics under the label's width constraint, before height clipping.
+     */
+    get textWidth(): number;
+    get textHeight(): number;
+    createChildren(): void;
+    commitProperties(): void;
+    measure(): void;
+    setLayoutBoundsSize(layoutWidth: number, layoutHeight: number): void;
+    updateDisplayList(unscaledWidth: number, unscaledHeight: number): void;
+    private _invalidateText;
+    private _measureText;
+    private _resolveFont;
+}
+//# sourceMappingURL=BitmapLabel.d.ts.map

package/dist/kurot/components/BitmapLabel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BitmapLabel.d.ts","sourceRoot":"","sources":["../../../src/kurot/components/BitmapLabel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA6C,MAAM,aAAa,CAAC;AACpF,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAG5D;;;;GAIG;AACH,qBAAa,WAAY,SAAQ,SAAU,YAAW,YAAY;IAEjE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAoB;IAChD,OAAO,CAAC,KAAK,CAAC,CAAsB;IACpC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,gBAAgB,CAAO;gBAGZ,IAAI,SAAK;IAO5B,IAAW,IAAI,IAAI,MAAM,CAExB;IACD,IAAW,IAAI,CAAC,KAAK,EAAE,MAAM,EAK5B;IACD,IAAW,IAAI,IAAI,MAAM,GAAG,UAAU,GAAG,SAAS,CAEjD;IACD,IAAW,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,EAQrD;IACD,IAAW,SAAS,IAAI,MAAM,GAAG,QAAQ,GAAG,OAAO,CAElD;IACD,IAAW,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,EAItD;IACD,IAAW,aAAa,IAAI,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAEtD;IACD,IAAW,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,EAI1D;IACD,IAAW,aAAa,IAAI,MAAM,CAEjC;IACD,IAAW,aAAa,CAAC,KAAK,EAAE,MAAM,EAIrC;IACD,IAAW,WAAW,IAAI,MAAM,CAE/B;IACD,IAAW,WAAW,CAAC,KAAK,EAAE,MAAM,EAInC;IACD,IAAW,SAAS,IAAI,OAAO,CAE9B;IACD,IAAW,SAAS,CAAC,KAAK,EAAE,OAAO,EAIlC;IACD,IAAW,SAAS,IAAI,OAAO,CAE9B;IACD,IAAW,SAAS,CAAC,KAAK,EAAE,OAAO,EAIlC;IACD;;OAEG;IACH,IAAW,SAAS,IAAI,MAAM,CAE7B;IACD,IAAW,UAAU,IAAI,MAAM,CAE9B;IAGe,cAAc,IAAI,IAAI;IAItB,gBAAgB,IAAI,IAAI;IAMxB,OAAO,IAAI,IAAI;IAIf,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI;IAOpE,iBAAiB,CAAC,aAAa,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI;IAOtF,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,YAAY;CA0BpB"}