@kurot/ui 3.3.0 → 3.5.0

package/docs/ai-context.md

@@ -1,15 +1,30 @@
 # @kurot/ui — AI context map
 
+UI 3.5.0 is prepared for publication, not yet published. It adds multiline
+Label fitting and stable alignment when fitting is toggled. UI 3.4.0 is the
+previous verified published release (2026-10-09). Development still installs
+published Core 2.4.0 with a matching registry lockfile, without local overrides. Read
+[centered flips](../../../docs/centered-flips.md) before changing transforms,
+reflection frames, authored flags or dependency adoption.
+
+Label/RichLabel/EditableText inherit TextField's vertical alignment;
+BitmapLabel inherits BitmapText's. Published Core 2.5.3 defaults both to middle;
+published Core 2.5.2 and earlier default to top. Explicit values remain effective
+and multiline only controls line generation. UI has no default override and needs
+no new release/peer minimum; its installed development Core remains 2.4.0.
+Published document 0.13.1 supplies matching authoring defaults.
+
 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.3.0`, EUI-compatible UI framework on top of
-`@kurot/core`. Peer-depends on `@kurot/core@^2.3.0`. Rewritten with standard class
+Package identity: `@kurot/ui@3.5.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.3.0 adds RichLabel and tests against published Core 2.3.1 through its
+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.
 
@@ -49,6 +64,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
@@ -94,6 +115,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.**
@@ -191,29 +219,45 @@ before patching core's transform code.
 | Understand validation/render scheduling order | `core/Validator.ts`, core `player/SystemTicker.ts`                                                                                                                        |
 | Measure UI validation/rendering performance   | `examples/benchmark/` for the visual runner, scenarios, Playwright automation, and local JSON/Markdown reports                                                            |
 
-## Label text layout contract in 3.1.0
+## Label text layout contract in 3.5.0
 
 Label defaults to multiline; explicit false draws only the first hard-separated
 line without wrapping. EditableText defaults to single-line and rejects
 shrinking. `wordWrap` chooses Unicode versus character boundaries only while
 multiline is enabled.
 
-`TextFitMode` is exported with Label. `textFit` is `none` by default or `shrink`
-for single-line Labels. `minFontSize` defaults to 12 and must be finite and >= 1.
+`TextFitMode` is exported with Label. `textFit` is `none` by default or `shrink`.
+UI 3.5.0 fits both line modes using complete Core measurement at each candidate
+size; UI 3.1.0–3.4.0 fit only single-line Labels.
+`multiline` stays authored and automatic axes stay unconstrained. Outline
+allowance affects fit checks and shared wrapping width, not the original alignment
+frame or nominal automatic dimensions. `minFontSize` defaults to
+12 and must be finite and >= 1.
 `size` stays authored; `renderedSize` and `textFitOverflow` are read-only results
 after validation. Fitting uses fixed axes, parent layout constraints or explicit
-maximums, reserves outline thickness and caches unchanged metrics. Measured
+maximums, reserves outline thickness and caches unchanged metrics, including
+multiline/wordWrap/lineSpacing. Measured
 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.3.0's package requirement is Core ^2.3.0.
+Core >= 2.1.0 for that API; current UI 3.5.0 requires Core ^2.4.0 for its
+centered-flip frame hook.
+
+Width/height setters refresh automatic text dimensions. Font readiness also
+invalidates fitting in fixed-size boxes. Fitting toggles preserve unchanged text
+positions, all nine alignments and nominal automatic dimensions.
 There is no global font-readiness listener.
 
+Existing multiline `shrink` policies begin fitting upon adoption; no XML format
+or authored-property migration is required. Runtime 0.10.0 accepts UI 3.5.0
+through its existing ^3.4.0 peer. CLI/document APIs are unchanged. Consumers
+update their own UI installations/locks and rebuild; no other SDK bump is needed.
+
 See [Label text layout](label-text-layout.md) for fit bounds, state restoration,
 font readiness and shared-schema boundaries. Native UI still depends only on
-Core; KUI authoring uses ui-document 0.11.x, published CLI 3.3.0 and
-published ui-runtime 0.8.2. Label presets expand in consumer-owned
+Core; current KUI authoring uses document 0.13.1, CLI 3.6.0 and runtime 0.10.0.
+Label presets expand in consumer-owned
 copies before native rendering; UI does not read style.json or consume textStyle.
 
 ## Bitmap labels in 3.2.0
@@ -237,4 +281,5 @@ 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.
+catalog is available in published ui-document 0.12.0+, CLI 3.4.0+ and
+ui-runtime 0.9.0+. Editor adoption remains an explicit application update.

package/docs/architecture.md

@@ -1,7 +1,8 @@
 # @kurot/ui architecture
 
-> Package version: 3.3.0, with peerDependency `@kurot/core: ^2.3.0`.
-> Core 2.3.1 is published and installed from npm without local overrides.
+> Package version: 3.5.0 (prepared, not yet published), 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
@@ -306,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

package/docs/bitmap-label.md

@@ -11,6 +11,9 @@ 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.
 
+Current UI 3.5.0 retains BitmapLabel and requires Core ^2.4.0 for centered flips.
+Its development installation and lock use published Core 2.4.0.
+
 ```ts
 import { BitmapLabel } from '@kurot/ui';
 
@@ -41,7 +44,15 @@ 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.
+Vertical alignment inherits BitmapText's default: middle with published Core 2.5.3,
+top with published 2.5.2 and earlier. Explicit top/bottom remain effective in either
+line mode. Bitmap-font metrics and glyph offsets are unchanged. UI 3.4.0 accepts
+the patch without another UI release; applications update their Core installation/
+lock and rebuild. Published document 0.13.1 supplies the matching
+catalog default.
+
+Authoring support was introduced in document 0.12.0, CLI 3.4.0 and runtime 0.9.0.
+Current document 0.13.1, CLI 3.6.0 and runtime 0.10.0 retain 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/label-text-layout.md

@@ -1,12 +1,14 @@
 # Label text layout and fitting
 
-Introduced in UI 3.1.0 with Core >= 2.1.0, this contract is unchanged in UI 3.2.0,
-which requires Core ^2.2.0. The public
+Introduced in UI 3.1.0 with Core >= 2.1.0, fitting is single-line in UI 3.1.0–3.4.0.
+UI 3.5.0 extends it to multiline Labels using Core's existing independent
+measurement API. Version 3.5.0 is prepared, not yet published. Its peer remains
+Core ^2.4.0 for centered flips. The public
 `TextFitMode` type is `none | shrink`. Native UI depends only on Core. KUI
 authoring introduced fitting metadata in ui-document 0.9.0 and retains it in
-0.11.0. Published CLI 3.3.0 and ui-runtime 0.8.2 use ui-document `^0.11.0`.
-Runtime 0.8.0's `^0.9.0` and runtime 0.8.1's `^0.10.0` peer ranges exclude
-the current kernel. Label presets are expanded into native properties before
+0.13.1. Current CLI 3.6.0 and runtime 0.10.0 use document `^0.13.0`; runtime
+also requires UI `^3.4.0` and Core `^2.4.0`. Older 0.x kernel ranges do not
+automatically accept 0.13.0. Label presets expand into native properties before
 rendering; their precedence does not change fitting behavior. See the
 [project style contract](../../ui-document/docs/project-styles.md).
 
@@ -33,6 +35,30 @@ Explicit `multiline="false"` in older skins now means a real single line.
 Remove it or set it to `true` for text intended to wrap. No files are migrated
 automatically; omitted Label flags continue to allow wrapping.
 
+## Vertical alignment and skin defaults
+
+Label, RichLabel and EditableText inherit TextField's default; BitmapLabel
+inherits BitmapText's. With published Core 2.5.3 they default to
+`verticalAlign="middle"`. Published Core 2.5.2 and earlier default to top. Button
+skins in the native KUI kit already set middle explicitly. Button does not
+overwrite an authored top/bottom or a skin state. Use explicit top for content
+intended to start at the top of a taller box. `verticalCenter` positions the
+Label box in its parent; it does not align text inside the Label.
+
+Published document 0.13.1 reports the new middle default without writing omitted
+properties into XML. Adopting editors need matching Core/catalog installations;
+UI 3.4.0 itself requires no release or higher peer minimum. Existing applications
+retain their installed behavior until they update their locks and rebuild.
+
+Published Core 2.5.2 makes dynamic top/middle/bottom use the same
+complete glyph-block boundaries in single-line and multiline modes. Blank rows
+retain their height. `multiline` controls only line generation. Input uses stable
+editing-row boundaries in all three modes; its caret and selection remain stable.
+Measurements and fitting stay nominal. Older Core installations retain their
+recorded text behavior; adopt the Core installation/lock and rebuild.
+UI 3.4.0's peer accepts 2.5.2; this correction needs no UI release.
+See [Core text layout](../../core/docs/text-layout.md#unified-vertical-alignment-core-252).
+
 ## Shrink to fit
 
 ```xml
@@ -41,10 +67,30 @@ automatically; omitted Label flags continue to allow wrapping.
 ```
 
 `textFit` accepts `none` (default) and `shrink`. Shrinking applies to ordinary
-single-line Labels. Multiline Labels retain their authored size; EditableText
-rejects `shrink`, including through the shared authoring schema. Put the policy
+Labels in either line mode. `multiline` always chooses line generation; fitting
+never changes it based on height or the selected size. EditableText rejects
+`shrink`, including through the shared authoring schema. Put the policy
 on a Button's `labelDisplay` skin part rather than on the Button itself.
 
+```xml
+<Label text="Доказуемая честность" width="120" height="44" size="20"
+       wordWrap="true" lineSpacing="2" textFit="shrink" minFontSize="14" />
+```
+
+This uses the default multiline mode. At each candidate size, Core lays out
+the complete displayed text under the effective content width. Measurement
+includes hard breaks, blank/trailing rows and line spacing, independently of
+height clipping. If the base size fits across several rows it is retained.
+Otherwise fitting searches smaller sizes, recalculating the row breaks each time.
+No maximum row count is implied by a fixed height, and no `maxLines` is added.
+
+| Available bounds | Multiline shrink behavior |
+| --- | --- |
+| Both automatic | Retain base size; soft wrapping has no width constraint. |
+| Width constrained, height automatic | Wrap and measure automatic height; shrink only if a protected sequence still exceeds width. |
+| Width automatic, height constrained | Measure hard-separated rows without soft wrapping, then fit their complete height. |
+| Both constrained | Wrap and shrink as needed to fit complete width and height. |
+
 - `size` is always the authored/base size. `renderedSize` is the derived drawing
   size after layout validation. State overrides capture and restore `size`.
 - Fit starts from that base size on every metric change. Shorter text or a
@@ -52,13 +98,21 @@ on a Button's `labelDisplay` skin part rather than on the Button itself.
 - `minFontSize` defaults to 12 logical pixels, must be finite and at least 1,
   and acts as a lower bound. A minimum above `size` never enlarges the text.
 - Measurement uses the displayed text, font family, bold and italic settings,
-  and reserves twice the outline thickness on each constrained axis. The
-  ordinary Core clipping and outline rendering rules remain in effect.
+  and reserves twice the outline thickness on each constrained axis. Search,
+  measurement and drawing use the same reserved wrapping width. Horizontal
+  alignment retains the original Label's left edge, center or right edge;
+  vertical alignment retains the full original height. Fitting adds no implicit
+  padding or outline inflation to automatic measured dimensions. A maximum
+  width reserves outline space once, even when the measured Label is narrower.
+  Toggling fitting leaves unchanged text at unchanged size in its original
+  position. Core's nominal measurement, clipping and outline rendering rules
+  remain in effect.
 - Available bounds come from fixed dimensions, parent layout constraints or
   explicit maximum dimensions. Icon spacing belongs to the skin's Label
   region. Automatic measured dimensions are not fed back as fit constraints.
 - A finite zero-sized region is constrained. An automatic axis is unconstrained.
-- Search performs at most 16 metric comparisons after the endpoint checks.
+- Search performs at most 16 metric comparisons after the endpoint checks,
+  followed by verification of the rounded result.
   Intermediate results are rounded down to tenths of a logical pixel while
   retaining the minimum. Base sizes and minimums may be fractional.
 - If text still cannot fit at the minimum, `textFitOverflow` is true after
@@ -72,6 +126,20 @@ These two read-only results are runtime observations, not authored KUI fields.
 CLI emits the policy and base size; ui-runtime uses the same native Label. Neither
 writes the derived size into XML, styles, semantic documents or history.
 
+Existing multiline Labels with an authored `shrink` policy begin fitting when
+they adopt UI 3.5.0; the published 3.4.0 runtime ignored that
+combination. Single-line hard-separator/password semantics remain effective.
+Finite zero content width reports overflow for nonempty displayed text; it is
+not mistaken for empty content by Core's zero-width measurement. Empty displayed
+content retains its base size without overflow.
+
+Core, KUI format and dependency minima require no change. CLI/runtime already
+pass the fields through; runtime 0.10.0's ^3.4.0 peer accepts UI 3.5.0.
+Applications adopt the UI installation/lock and rebuild explicitly. Editor
+0.28.1's local trial removes the old single-line Inspector restriction and binds
+built UI. Its exact registry 3.4.0 dependency must adopt 3.5.0 after publication
+for ordinary builds. Preview and compiled games use the native Label behavior.
+
 Load fonts before constructing or measuring text where possible. If a font
 becomes ready later, call `label.invalidateSize()` before the next validation;
 this clears both fitting and Core line metrics even when the family name stays
@@ -97,3 +165,12 @@ single-line fitting, Unicode wrapping without leading separator spaces, outline
 allowance, minimum overflow, native Button state restoration and invalidation
 after a font finishes loading. Fitted sizes are platform-dependent; these checks
 assert the layout contract rather than a universal numeric result.
+
+Multiline tests cover complete-height fitting, blank/trailing rows, line spacing,
+Unicode and grapheme boundaries, password text, minimum/zero-width overflow,
+outline allowance, automatic axes, font readiness and parent resize recovery.
+Minified browser tests validate native Russian/Chinese layouts in Canvas,
+WebGL 1 and WebGL 2 at 1x/2x, using independent Canvas width measurements.
+Pixel comparisons verify unchanged painting across fitting toggles for all nine
+horizontal/vertical alignments and automatic dimensions; icon-and-caption row
+tests retain parent geometry.

package/docs/rich-label.md

@@ -3,6 +3,9 @@
 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.
 
+Current UI 3.5.0 retains RichLabel and requires Core ^2.4.0 for centered flips.
+Its development installation and lock use published Core 2.4.0.
+
 ```ts
 import { RichLabel } from '@kurot/ui';
 
@@ -43,9 +46,15 @@ available, together with these text-layout properties:
 | 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.                                                    |
+| verticalAlign          | Host Core | top, middle or bottom.                                                    |
 | textWidth / textHeight | Read-only | Complete content metrics under the current width, before height clipping. |
 
+Vertical alignment inherits TextField's default: middle with published Core 2.5.3,
+top with published 2.5.2 and earlier. Explicit values remain effective in either
+line mode. UI 3.4.0 accepts the Core patch without another UI release; adopt the
+application installation/lock and rebuild. Published document
+0.13.1 supplies the matching catalog default.
+
 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
@@ -67,10 +76,11 @@ 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.
 
-This release supports native code and programmatic skins. The current
-ui-document catalog, CLI KUI registry, ui-runtime materializer and Editor do not
-yet provide RichLabel authoring or serialization. Their later integration must
-keep textFlow ownership and the separation from ordinary Label presets.
+Authoring support was introduced in document 0.12.0, CLI 3.4.0 and runtime 0.9.0.
+Current document 0.13.1, CLI 3.6.0 and runtime 0.10.0 retain 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`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/ui",
-	"version": "3.3.0",
+	"version": "3.5.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",
@@ -34,10 +34,10 @@
 		"test:text-labels": "playwright test test/browser --workers=1"
 	},
 	"peerDependencies": {
-		"@kurot/core": "^2.3.0"
+		"@kurot/core": "^2.4.0"
 	},
 	"devDependencies": {
-		"@kurot/core": "^2.3.1",
+		"@kurot/core": "^2.4.0",
 		"@playwright/test": "1.62.1",
 		"@types/node": "^22.0.0",
 		"esbuild": "^0.28.2",