@kurot/ui 3.2.0 → 3.4.0

package/docs/ai-context.md

@@ -1,16 +1,24 @@
 # @kurot/ui — AI context map
 
+Source prepares UI 3.4.0 and installs published Core 2.4.0 with a matching
+registry lockfile, without local overrides. The released baseline below is
+historical. Read
+[centered flips](../../../docs/centered-flips.md) before changing transforms,
+reflection frames, authored flags or dependency adoption.
+
 Read this before exploring `src/`. It is a compressed map so an agent
 unfamiliar with Kurot does not need to re-derive the architecture from scratch
 each session. Treat the package source and its `src/index.ts` barrel as the
 authority for current behavior and exports; this file provides the compressed
 map, runtime contracts and task→file lookup.
 
-Package identity: `@kurot/ui@3.2.0`, EUI-compatible UI framework on top of
-`@kurot/core`. Peer-depends on `@kurot/core@^2.2.0`. Rewritten with standard class
+Package identity: `@kurot/ui@3.4.0`, EUI-compatible UI framework on top of
+`@kurot/core`. Peer-depends on `@kurot/core@^2.4.0`. Rewritten with standard class
 inheritance and delegation — no namespace mixins, no prototype copying.
-Version 3.2.0 is prepared for publication against published Core 2.2.0;
-source metadata alone does not confirm UI publication.
+Version 3.3.1 is preserved in commit 60e6404 and fixes transformed parent
+allocations. It has not been published; UI 3.4.0 includes the same correction. Version 3.3.0 adds RichLabel and tests against published Core 2.3.1 through its
+development installation and lockfile, without overrides. Version 3.2.0 is published with BitmapLabel against published Core 2.2.0,
+without local dependency overrides. Published UI 3.1.0 does not contain BitmapLabel.
 
 Source root: `src/kurot/`. Public API: `src/index.ts` is a flat re-export of
 7 barrels — `core`, `layouts`, `components`, `events`, `states`, `collections`,
@@ -26,7 +34,7 @@ src/kurot/
 │                   Validator/validator (render-preparation validation scheduler),
 │                   Theme/getTheme()/setTheme(), IViewport, IAssetAdapter/IThemeAdapter.
 ├── components/     Group, Component (delegation core — see §2), Skin, and
-│                   concrete widgets: Button, Label, BitmapLabel, CheckBox, RadioButton,
+│                   concrete widgets: Button, Label, BitmapLabel, RichLabel, CheckBox, RadioButton,
 │                   ToggleButton/ToggleSwitch, ProgressBar, HSlider/VSlider,
 │                   Rect, Image, EditableText, TextInput, Panel, ViewStack,
 │                   Scroller, UILayer, DataGroup, List, TabBar, ComboBox,
@@ -48,6 +56,12 @@ src/kurot/
 
 ## 2. Non-obvious current behavior
 
+- `flipX`/`flipY` are native Core booleans inherited by every UI display
+  component. Group and Component provide their validated, unscaled actual frame
+  through `$getFlipBounds()`. `UIState.getActualBounds()` reads this frame without
+  validating recursively. Layout uses the authored matrix, independent of flips;
+  negative scale remains anchor-based. Resizing moves the reflection center.
+
 - **`Skin` is NOT a `Group`/DisplayObject subclass.** `components/Skin.ts`
   defines `class Skin extends EventDispatcher<SkinEvents>` — a plain data
   holder, not a visual container. A skin's
@@ -93,6 +107,13 @@ skin)` signature, but `Group._commitCurrentState()` passes `this` cast
 - Anchor/percent constraints (`left`/`right`/`percentWidth`, etc.) have zero
   effect until the component is added to a `Group` that has a `layout`
   assigned. Setting them on a standalone/unparented component is a no-op.
+- **Since 3.3.1: transformed allocations use parent-space dimensions.**
+  `core/fit-transformed-bounds.ts` converts them to local sizes for negative scale,
+  rotation and skew. UIState tracks the allocated local axes so width/height
+  reads do not discard a rotated one-axis allocation. Anchor/translation affect
+  positioning, not size. Incompatible aspect ratios fit the largest contained
+  local rectangle; local minima win when containment is impossible. The published
+  UI 3.3.0 still falls back to preferred dimensions for non-identity transforms.
 - `isUIComponent()` is duck-typed (`'ui' in obj`) — any object with a `.ui`
   property passes, not necessarily a real `Group`/`Component`.
 - **Virtual layout defaults to OFF.**
@@ -143,7 +164,7 @@ Flat re-export of 7 barrels, in this order: `core`, `layouts`, `components`,
 
 - **core**: `IUIComponent`, `IUIOwner`, `UIState`, `isUIComponent`, `Validator`/`validator`, `Theme`/`getTheme`/`setTheme`, `IViewport`, `IAssetAdapter`/`DefaultAssetAdapter`, `setAssetAdapter`/`getAssetAdapter`, `IThemeAdapter`/`DefaultThemeAdapter`, `Direction`, `ScrollPolicy`, `IDisplayText`, `IItemRenderer`.
 - **layouts**: `ILayoutTarget`, `LayoutBase`, `BasicLayout`, `LinearLayoutBase`, `VerticalLayout`, `HorizontalLayout`, `TileLayout`, `ColumnAlign`, `RowAlign`, `JustifyAlign`, `TileOrientation`.
-- **components**: `Group`/`GroupEvents`, `Component`/`ComponentEvents`, `Skin`/`SkinEvents`; `Button`, `Label`/`TextFitMode` (type), `BitmapLabel`, `CheckBox`, `RadioButton`/`RadioButtonGroup`, `ToggleButton`, `ToggleSwitch`, `ProgressBar`, `HSlider`/`VSlider`/`SliderBase`, `Rect`, `Image`, `EditableText`, `TextInput`, `Panel`, `ViewStack`, `Scroller`, `TouchScroll`, `UILayer`, `DataGroup`, `List`/`ListBase`, `TabBar`, `ComboBox`, `ItemRenderer`, `HScrollBar`/`VScrollBar`/`ScrollBarBase`, `Animation`, `Range`.
+- **components**: `Group`/`GroupEvents`, `Component`/`ComponentEvents`, `Skin`/`SkinEvents`; `Button`, `Label`/`TextFitMode` (type), `BitmapLabel`, `RichLabel`, `CheckBox`, `RadioButton`/`RadioButtonGroup`, `ToggleButton`, `ToggleSwitch`, `ProgressBar`, `HSlider`/`VSlider`/`SliderBase`, `Rect`, `Image`, `EditableText`, `TextInput`, `Panel`, `ViewStack`, `Scroller`, `TouchScroll`, `UILayer`, `DataGroup`, `List`/`ListBase`, `TabBar`, `ComboBox`, `ItemRenderer`, `HScrollBar`/`VScrollBar`/`ScrollBarBase`, `Animation`, `Range`.
 - **events**: `UIEvent`, `ItemTapEvent`, `CollectionEvent`/`CollectionEventKind`, `PropertyEvent`, `ScrollerThrowEvent`.
 - **states**: `State`, `IOverride`, `SetProperty`, `SetStateProperty`, `AddItems`.
 - **collections**: `ICollection`, `ArrayCollection`.
@@ -206,7 +227,7 @@ automatic bounds are not fed back as fit constraints.
 
 `label.invalidateSize()` also invalidates Core line metrics. Call it after
 late font loading, even if the family name did not change. This requires
-Core >= 2.1.0 for that API; UI 3.2.0's package requirement is Core ^2.2.0.
+Core >= 2.1.0 for that API; UI 3.3.0's package requirement is Core ^2.3.0.
 There is no global font-readiness listener.
 
 See [Label text layout](label-text-layout.md) for fit bounds, state restoration,
@@ -222,3 +243,18 @@ using one BitmapText child and the configured Core resource singleton for string
 font names. Stale async results are guarded by request generation. Core ^2.2.0
 is required; local Core overrides have been removed. Published UI 3.1.0 does
 not contain it. KUI catalog, installed compilers and Editor adoption are separate.
+
+## Rich labels in 3.3.0
+
+[rich-label.md](rich-label.md) defines RichLabel, an independent Component using
+one native TextField. Only textFlow supplies content; no Label text/appearance
+properties, textFit or textStyle. Reads and assignments copy runs and styles;
+[] clears content. Wrapping is continuous across styles. Measurement uses Core
+2.3.0's pure measureText with parent width, explicit width or maxWidth; cached
+metrics clear on invalidateSize, including after fonts load. Geometry, multiline,
+wordWrap, lineSpacing, textAlign and verticalAlign remain component-level.
+
+Task → `components/RichLabel.ts`, `test/RichLabel.test.ts`,
+`test/browser/text-labels.spec.ts`. Run `pnpm test:text-labels` after building
+Core and UI. BitmapLabel automatic measurement now uses maxWidth too. The KUI
+catalog, CLI and Editor must adopt these native components in a later phase.

package/docs/architecture.md

@@ -1,12 +1,14 @@
 # @kurot/ui architecture
 
-> Package version: 3.2.0, with peerDependency `@kurot/core: ^2.2.0`.
-> This release is prepared against published Core 2.2.0; UI publication is not yet confirmed.
+> Package version: 3.4.0 (unpublished), with peerDependency `@kurot/core: ^2.4.0`.
+> Development installs published Core 2.4.0 with a matching registry lockfile.
+> No local Core override is needed for builds or centered-flip checks.
 > See [CHANGELOG.md](../CHANGELOG.md) for release-by-release changes.
 > The [AI context map](./ai-context.md) provides directory, behavior, terminology
 > and task-to-file references. This document explains design decisions and internal
 > mechanisms for human readers; the two documents complement each other.
-> Version 3.2.0 exports BitmapLabel for native code and programmatic skins.
+> Version 3.3.0 also exports independent [RichLabel](./rich-label.md).
+> Version 3.2.0 introduced BitmapLabel for native code and programmatic skins.
 > See [bitmap-label.md](./bitmap-label.md) for its resource and ownership contract.
 
 ---
@@ -305,6 +307,23 @@ A trailing percent sign selects percentage calculation; otherwise the value is
 converted to a number. There is no separate runtime type tag for percentages
 versus pixels.
 
+The 3.3.1 transform-allocation correction uses
+`core/fit-transformed-bounds.ts` from UIState. Allocated dimensions describe the
+parent-space rectangle, while explicit, preferred and minimum/maximum sizes stay
+local. The solver uses the absolute linear matrix coefficients to obtain that
+rectangle's width and height. Anchors and translation affect only its position.
+It fills both requested axes when possible, otherwise chooses the largest local
+rectangle contained by the allocation. Local minimum sizes take precedence if
+no contained rectangle can satisfy them. With one allocated axis, an authored
+single local dimension is retained when possible; the unconstrained parent extent
+is minimized otherwise. Unallocated transforms preserve local measurement.
+
+UIState also maps the allocation flags to the affected local axes. A quarter-turn
+width allocation controls local height, so reading height must retain the fitted
+value rather than restoring the authored height. A zero scale column keeps its
+natural local dimension without division by zero. Group and Component share
+this behavior, including Image, text, buttons and other component subclasses.
+
 LinearLayoutBase.flexChildrenProportionally(), shared by VerticalLayout and
 HorizontalLayout, iteratively allocates percentages with min/max constraints.
 A do...while loop identifies children whose proportional allocation exceeds a
@@ -371,6 +390,7 @@ including intermediate base classes.
 | `Image`                             | Displays bitmap data resolved through IAssetAdapter                                               |
 | `Label`                             | Text display wrapping one TextField                                                               |
 | `BitmapLabel`                       | Bitmap-font label wrapping one BitmapText; requires Core 2.2.0 or later                           |
+| `RichLabel`                         | Independent Component with textFlow content and pure, cached TextField measurement                |
 | `EditableText extends Label`        | Editable text with prompt support                                                                 |
 | `Button`                            | Clickable up/down/disabled states; toggle enables automatic selected changes                      |
 | `ToggleButton extends Button`       | Defaults toggle to true and toggles selection on click                                            |
@@ -449,7 +469,7 @@ file and case counts.
 | Skins and states                       | Skin, SkinAlignment (real CLI template skins), SkinMeasurement, AddItems                                                                       |
 | Data binding                           | Binding, Watcher                                                                                                                               |
 | Collections and data-driven components | ArrayCollection, DataGroup, ListBase, ItemRenderer, ComboBox, TabBar, ViewStack                                                                |
-| Individual components                  | RadioButton, Range, Slider, ProgressBar, Scroller, Label, BitmapLabel, TextInput                                                               |
+| Individual components                  | RadioButton, Range, Slider, ProgressBar, Scroller, Label, BitmapLabel, RichLabel, TextInput                                                    |
 | Text fitting                           | ButtonLabelTextFit, LabelTextFit, LabelTextFitBounds                                                                                           |
 | Cross-component behavior               | Enabled (EUI-aligned enabled/touchEnabled/touchChildren behavior), EventMapOverride, GestureLifecycle, TransformLayout, ScrollAndVirtualLayout |
 
@@ -465,3 +485,10 @@ static UI, 240-node transform/alpha animation and a virtual list with 10,000 rec
 It records frame/render time, draw calls, validation-phase calls and ItemRenderer
 creation/reuse. It is a regression baseline for this UI implementation, rather
 than a ranking across UI frameworks.
+
+### Text component browser validation
+
+Build Core and UI, then run `pnpm test:text-labels` from this package. The fixture
+bundles built ESM with minification and keepNames=false, verifies actual pixels
+through Canvas 2D, WebGL 1 and WebGL 2, and checks automatic bounds, edits and
+empty content. Browser screenshots go to ignored test-results, not the package.

package/docs/bitmap-label.md

@@ -1,10 +1,16 @@
 # BitmapLabel
 
 Available in UI 3.2.0 with `@kurot/core ^2.2.0`. Core resolves its published
-@kurot/bitmap-font dependency from npm. UI 3.2.0 is prepared for publication;
+@kurot/bitmap-font dependency from npm. UI 3.2.0 is published;
 published UI 3.1.0 does not contain this component. Core 2.1.1 does not contain
 its required BitmapText rendering.
 
+UI 3.3.0 retains this API and raises the package's Core minimum to ^2.3.0 for
+RichLabel. During automatic sizing it also uses maxWidth when neither a parent
+width nor an explicit width is present, so wrapped height matches rendering.
+Changing an authored width also invalidates automatic height after layout.
+UI 3.3.0 builds and tests against published Core 2.3.1 without local overrides.
+
 ```ts
 import { BitmapLabel } from '@kurot/ui';
 
@@ -35,7 +41,7 @@ DisplayObject tint. Alignments position glyphs without scaling them. Set scaleX
 and scaleY for decorative number sizing. Default multiline=true; explicit false
 keeps the first hard-separated line unwrapped.
 
-This initial change exposes a native UI component and supports programmatic
-skins. The ui-document built-in catalog, CLI KUI tag registry, Editor and
-ui-runtime materializers do not yet adopt BitmapLabel. Those require coordinated
-consumer releases; do not assume an installed compiler accepts the XML tag.
+Published ui-document 0.12.0, CLI 3.4.0 and ui-runtime 0.9.0 support BitmapLabel
+authoring, KUI compilation and materialization. Earlier compilers do not accept
+this built-in XML tag; update applications explicitly when adopting it. Editor
+controls are owned by the separate application.

package/docs/rich-label.md

@@ -0,0 +1,77 @@
+# RichLabel
+
+Native API introduced in UI 3.3.0, requiring Core ^2.3.0. Core 2.3.1 is
+published and installed from npm for this release's build and verification.
+
+```ts
+import { RichLabel } from '@kurot/ui';
+
+const label = new RichLabel([
+	{ text: 'Warning: ', style: { size: 20, bold: true, textColor: 0xff9900 } },
+	{ text: 'read this before continuing.', style: { size: 20, italic: true } },
+]);
+label.maxWidth = 240;
+group.addChild(label);
+```
+
+## Content and ownership
+
+RichLabel extends Component independently, not Label. Its only content interface
+is `textFlow: ITextElement[]`, using Core's text/style records. Whole-component
+`text`, `fontFamily`, `size`, `bold`, `italic`, `textColor`, `textFit`, `minFontSize`
+and `textStyle` are not exposed. Label presets do not apply to this component.
+
+Runs can specify font family, size, bold, italic, text color, stroke color and
+stroke width. Unspecified fields use the native TextField defaults captured at
+construction. In particular, an unstyled run does not inherit the previous run.
+All runs are laid out continuously; a style boundary does not introduce a word
+boundary or a new line. No HTML or markdown parsing is performed.
+
+The component copies runs and their styles on assignment and on reads. Mutating
+an input array or a returned snapshot does not change the component. Reassign
+an edited snapshot to apply it. Assigning [] clears content; assignment dispatches
+PropertyEvent.PROPERTY_CHANGE for `textFlow` after the new content is installed.
+
+## Layout
+
+Ordinary Component geometry, layout constraints, visibility and alpha remain
+available, together with these text-layout properties:
+
+| Property               | Default   | Contract                                                                  |
+| ---------------------- | --------- | ------------------------------------------------------------------------- |
+| multiline              | true      | False shows the first hard-separated line without width wrapping.         |
+| wordWrap               | true      | Unicode line-break opportunities; false wraps between graphemes.          |
+| lineSpacing            | 0         | Finite, nonnegative distance between lines.                               |
+| textAlign              | left      | left, center or right.                                                    |
+| verticalAlign          | top       | top, middle or bottom.                                                    |
+| textWidth / textHeight | Read-only | Complete content metrics under the current width, before height clipping. |
+
+Measurement uses parent-assigned width first, then explicit width, then a
+configured maxWidth, otherwise unconstrained width. Automatic height includes
+every wrapped line and inter-line spacing. Each line uses the largest font size
+of its runs, rather than imposing the TextField base size. Hard line separators
+and trailing blank lines follow the Core text contract. Core 2.3.1 corrects the
+base size of unstyled blank runs between styled runs; the API minimum stays 2.3.0. Empty content measures
+0 × 0; Component minWidth/minHeight can still enlarge its layout bounds.
+
+Fixed height clips drawing without discarding content. Alignment positions the
+continuous text block within the assigned bounds. One native TextField renders
+through Canvas 2D and WebGL; measurement never temporarily resizes that field.
+Unchanged content metrics are cached until size/content invalidation or a width
+change.
+
+## Font readiness and integration
+
+Load project fonts before measuring where possible. If fonts become ready later,
+call `label.invalidateSize()` to clear both component and native text metrics,
+then allow normal layout validation. RichLabel does not load font files or
+install global font-loading listeners.
+
+Published ui-document 0.12.0, CLI 3.4.0 and ui-runtime 0.9.0 provide RichLabel
+authoring, KUI compilation and materialization. Earlier versions lack these
+built-in registrations. Editor controls are owned by the separate application;
+all consumers retain textFlow ownership and separation from Label presets.
+
+See [Core text layout](../../core/docs/text-layout.md) for Unicode wrapping,
+single-line behavior and independent measurement. Run `pnpm test:text-labels`
+after building Core and UI for minified Canvas/WebGL browser verification.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@kurot/ui",
-	"version": "3.2.0",
-	"description": "EUI-compatible UI component framework for the Kurot game engine \u2014 skin-based components, layouts, data binding, view states",
+	"version": "3.4.0",
+	"description": "EUI-compatible UI component framework for the Kurot game engine — skin-based components, layouts, data binding, view states",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",
 	"type": "module",
@@ -30,15 +30,17 @@
 		"benchmark:compare": "playwright test --config examples/benchmark/playwright.config.ts",
 		"benchmark:smoke": "UI_BENCHMARK_PROFILE=smoke playwright test --config examples/benchmark/playwright.config.ts",
 		"build:benchmark": "vite --config vite.config.ts build",
-		"prepublishOnly": "npm run clean && npm run build"
+		"prepublishOnly": "npm run clean && npm run build",
+		"test:text-labels": "playwright test test/browser --workers=1"
 	},
 	"peerDependencies": {
-		"@kurot/core": "^2.2.0"
+		"@kurot/core": "^2.4.0"
 	},
 	"devDependencies": {
-		"@kurot/core": "^2.2.0",
+		"@kurot/core": "^2.4.0",
 		"@playwright/test": "1.62.1",
 		"@types/node": "^22.0.0",
+		"esbuild": "^0.28.2",
 		"happy-dom": "^20.8.9",
 		"typescript": "^5.6.0",
 		"vite": "^8.0.8",