@kurot/core 2.4.0 → 2.5.0

package/dist/kurot/text/types/ITextElement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ITextElement.d.ts","sourceRoot":"","sources":["../../../../src/kurot/text/types/ITextElement.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IAClD,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CACzB"}
+{"version":3,"file":"ITextElement.d.ts","sourceRoot":"","sources":["../../../../src/kurot/text/types/ITextElement.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IAClD,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;CACzB"}

package/docs/ai-context.md

@@ -1,15 +1,21 @@
 # @kurot/core — AI context map
 
-Source prepares 2.4.0; the released baseline below is historical. Read
+Core 2.5.0 is prepared for publication, not yet published. Latest verified npm
+release is 2.4.0. Read
 [centered flips](../../../docs/centered-flips.md) before changing transforms,
 reflection frames, authored flags or dependency adoption.
 
+Core 2.5.0 adds independent Texture/SpriteSheet source density. Read [texture density](texture-density.md) before changing texture
+dimensions or sheet loading. `resolution` defaults to 1 and is immutable;
+sampling and page coordinates are physical, frame bounds/trim/grid are logical.
+The default KUI kit uses 2× assets and requires this new Core implementation.
+
 Read this before exploring `src/`. It is a compressed map of the package so an
 agent unfamiliar with Kurot does not need to re-derive the architecture from
 scratch on every session. Treat the package source and its `src/index.ts`
 barrel as the authority for current behavior and exports.
 
-Package identity: `@kurot/core@2.4.0`, prepared in source and not published. It provides Kurot's scene graph,
+Package identity: `@kurot/core@2.5.0`, pending publication. It provides Kurot's scene graph,
 events, rendering, text, resource, network and media runtime. Rendering uses a
 flat `InstructionSet + RenderPipe` pipeline. ES2022 / evergreen browsers only
 with `strict: true`. Two
@@ -86,6 +92,10 @@ colocated under `examples/benchmark/`; none are exported from `index.ts`.
   content, not the clip. WebGL's nested/rotated stencil path must use the same
   viewport origin as its axis-aligned scissor path. Rectangle masks retain
   their own local x/y. See `player/pipes/MaskPipe.ts`.
+- The Core 2.5.0 axis-aligned WebGL scissor correction encloses fractional
+  physical bounds with floor(left/top) and ceil(right/bottom), then subtracts
+  those integer edges. Do not truncate position and size independently: this
+  cuts boundary pixels from scaled ItemRenderer skins. Stencil clips are unchanged.
 - `CanvasRenderer` is not purely a fallback. The WebGL backend depends on it
   internally to rasterize Graphics/Text to offscreen canvases before texture
   upload, and to snapshot `RenderTexture`. Don't reason about it as dead code
@@ -230,6 +240,18 @@ vertices, UVs, or indices, call updateVertices(). WebGL keeps Mesh indices
 separate from quad indices and splits oversized meshes into ordered batches
 with local index remapping (player/webgl/split-mesh.ts).
 
+## Text alignment in 2.5.0
+
+`TextLineLayout.ts` caches alphabetic `baseline` and visible `inkAscent` /
+`inkDescent` per line. `TextVerticalLayout.ts` centers ink only for dynamic,
+single-line middle alignment. Multiline/INPUT/top/bottom retain nominal rows
+with content-independent font frames, including blank lines. Canvas, WebGL
+rasterization and link hit testing share the offset. Render bounds add glyph
+margin without changing measurement, input or external clip boundaries. See
+[text layout](text-layout.md#visual-centering-and-stable-baselines-core-250).
+Core 2.4.0 on npm does not include this correction; existing consumer peer ranges
+accept 2.5.0 without SDK bumps. Adoption updates the Core installation/lock.
+
 ## Text layout in 2.0.1
 
 Word-wrapped text uses Unicode 17.0 UAX #14, dictionary tailoring for SA scripts

package/docs/architecture.md

@@ -1,6 +1,6 @@
 # @kurot/core architecture
 
-> Package version: 2.2.1. See [CHANGELOG.md](../CHANGELOG.md) for release notes.
+> Package version: 2.5.0 (pending publication; latest verified npm release: 2.4.0). See [CHANGELOG.md](../CHANGELOG.md) for release notes.
 > The [AI context map](./ai-context.md) covers directories, non-obvious behavior,
 > terminology and task-to-file references. This document explains design choices
 > and internal mechanisms for contributors; the two documents complement each other.
@@ -18,6 +18,13 @@ Since 2.2.0, Core uses published `@kurot/bitmap-font ^0.1.0` as the headless fon
 and layout kernel. Core manages font resources, image-page ownership and glyph
 drawing in both backends. UI components belong to the UI package.
 
+Since 2.4.0, `DisplayObject.flipX`/`flipY` reflect around a local frame center
+independently of authored scale and anchors. `matrix` exposes the authored
+transform; `$getMatrix()` supplies the effective reflection transform to
+rendering and coordinate conversion. UI provides its validated layout frame
+through `$getFlipBounds()`. See [centered flips](centered-flips.md) for frame,
+scrolling, caching and consumer requirements.
+
 TextField uses Unicode 17.0 line-break rules with dictionary and overflow
 tailoring. Since 2.2.1, tailoring uses imported rule identities, and layout
 filters optional break positions through `Intl.Segmenter` grapheme boundaries.

package/docs/bitmap-fill.md

@@ -35,9 +35,15 @@ invalid periods, fractional dimensions and nine-slice precedence. The minified
 native Canvas patterns on Canvas/WebGL 1/WebGL 2 at 1x/2x, including rotation,
 tint, cache updates and the existing scale path.
 
-There are no new APIs or dependencies. Existing UI, Game, DragonBones, Spine and
-ui-runtime Core peers accept this patch. Their SDK versions and minimum ranges
-do not change; optional development lock adoption is separate. Editor's local
+The Core 2.5.0 [texture density extension](texture-density.md) additionally
+tests source densities 1×/2×/3× at both output resolutions. Physical atlas sampling
+and logical repeat periods remain separate, including tinted cached images and
+nine-slice texture swaps. Published 2.4.0 does not interpret sheet density metadata.
+
+There are no new APIs or dependencies. UI 3.3.0/runtime 0.9.0 and
+Game/DragonBones/Spine peers accept this patch without SDK bumps. Current
+UI 3.4.0/runtime 0.10.0 require Core ^2.4.0 for centered flips; that release
+includes the fill correction. Optional development lock adoption is separate. Editor's local
 0.23.1 trial bound one built Core through `KUROT_CORE_PATH` while retaining its
 published 2.3.2 dependency lock. Editor 0.23.2 adopts registry Core 2.3.3 and
 updates its Bun lock; ordinary builds no longer require a local engine checkout.

package/docs/bitmap-fonts.md

@@ -66,6 +66,8 @@ art. NaN removes a dimension constraint. Height admits complete line boxes;
 multiline=false draws the first hard-separated line without width wrapping.
 Explicit zero height draws nothing. Default textureScaleFactor=1 is required for
 font assets in this initial implementation.
+The Core 2.5.0 texture-density extension keeps literal font metrics separate:
+BitmapFont page textures require resolution=1. See [texture density](texture-density.md).
 
 WebGL's BitmapTextPipe submits cropped glyph quads to ordinary texture batching,
 with current transforms, alpha, tint, blend, clipping and filters. Canvas uses the
@@ -80,6 +82,8 @@ now controls fallback spaces. Line-height, trailing-advance and complete-line
 clipping follow the shared
 format contract rather than the old unrendered class's approximate measurements.
 
-The matching UI release provides BitmapLabel for native/programmatic skins;
-published UI 3.1.0 does not include it. KUI catalog/CLI adoption is separate;
-existing installed compilers do not gain a new tag automatically.
+UI 3.2.0 introduced native BitmapLabel; UI 3.1.0 does not include it. Current
+UI 3.4.0 retains it and requires Core ^2.4.0. Published document 0.13.0, CLI
+3.5.0 and runtime 0.10.0 support font authoring, compilation and materialization;
+existing installed compilers do not gain a new tag automatically. See
+[BitmapLabel](../../ui/docs/bitmap-label.md) for the feature's introduction versions.

package/docs/centered-flips.md

@@ -1,6 +1,6 @@
 # Centered display flips (Core 2.4.0)
 
-Prepared in source, not published. `flipX` and `flipY` are boolean DisplayObject
+Core 2.4.0 is published, verified on npm on 2026-10-09. `flipX` and `flipY` are boolean DisplayObject
 properties, defaulting to false and inherited by all display subclasses.
 
 ```ts
@@ -29,6 +29,6 @@ no new runtime dependency. UI alone requires a new Core minimum when adopting
 its frame hook; other SDKs with Core 2.x peers can adopt Core optionally.
 
 The repository [adoption contract](../../../docs/centered-flips.md) records
-headless/compiler/runtime versions and publication order. Development checks
-use temporary local SDK bindings until the new versions exist on the registry;
-installed released locks remain the prior baseline until explicit adoption.
+headless/compiler/runtime versions and publication order. UI development now
+installs registry Core 2.4.0 without local overrides. UI 3.4.0 and document
+0.13.0, CLI 3.5.0 and runtime 0.10.0 are also published. Consumers adopt each installation/lock explicitly and rebuild.

package/docs/resource.md

@@ -221,6 +221,11 @@ Load a sprite sheet in TexturePacker JSON format in two steps:
 1. Load the JSON descriptor to obtain frame data and the image path.
 2. Load the image and create subtextures.
 
+The Core 2.5.0 [texture density extension](texture-density.md) accepts optional
+sheet JSON `resolution` (default 1). Frame coordinates and original dimensions
+in JSON remain physical pixels; loaded Texture dimensions and trim offsets are
+logical. Published Core 2.4.0 does not interpret this field.
+
 Resources can be retrieved in three ways:
 
 ```typescript

package/docs/text-layout.md

@@ -40,6 +40,47 @@ Dictionary and grapheme segmentation follow the browser's `Intl` data. The
 pinned Unicode 17.0 tables govern the line-break profile; they do not replace
 the browser's grapheme implementation.
 
+## Visual centering and stable baselines (Core 2.5.0)
+
+Canvas and WebGL use the same alphabetic baseline and logical-pixel Canvas
+`TextMetrics`. Each cached line records `baseline`, `inkAscent` and `inkDescent`;
+rich runs share that baseline, even when their sizes or font families differ.
+Visible bounds include fallback glyphs, accents and combining marks. No language
+or operating-system offset table is used.
+
+- Dynamic text with `multiline = false` and `verticalAlign = "middle"` centers
+  the union of visible run ink in the field. Empty/whitespace-only lines use
+  the nominal line box. Changing a button caption may change its baseline so
+  its visible glyphs remain centered.
+- Multiline text and INPUT retain font-based baselines. Font-frame bounds are
+  measured with an empty string per font configuration, independently of the
+  current caption and its fallback glyphs. Empty lines retain the same frame.
+  Input caret/selection use the nominal row; composition underlines stay inside
+  the viewport. Top/bottom alignment also uses nominal line boxes.
+- `textHeight`, `measureText()`, wrapping, row spacing and layout bounds retain
+  their nominal size contract. Dynamic glyph overhang is added only to render
+  captures, together with outlines; INPUT and external clips remain exact.
+- Measurements are reused with the TextField line cache. After loading/replacing
+  a font, call `invalidateTextMetrics()` through the existing readiness path.
+  Fonts and browser rasterization can differ across systems; centering follows
+  the actual selected glyphs rather than promising identical pixels.
+
+See the [Canvas TextMetrics contract](https://html.spec.whatwg.org/multipage/canvas.html#textmetrics).
+The correction is included in Core 2.5.0, pending publication; it is not in
+published Core 2.4.0. There is no new alignment
+property, runtime dependency or XML format. Default KUI single-line control
+labels use the existing flags with symmetric padding. Adopt Core 2.5.0 after
+publication and rebuild to receive this behavior; SDK peers need no
+incidental change.
+
+`test/TextVerticalLayout.test.ts` covers ink centering, mixed sizes, stable input
+and paragraph baselines, link hits, blank rows, overhang and font invalidation.
+The minified `text-alignment.spec.ts` compares 18 multilingual strings in regular
+and bold faces against an independent Canvas reference in Canvas/WebGL 1/2 at
+1×/2×, including rich runs, outlines, nested caches and tight Thai/Hindi rows.
+The continuous-frame checks also cover restoring the root WebGL target after
+its initial offscreen allocation.
+
 ## Independent measurement (Core 2.3.0)
 
 `textField.measureText(width = NaN)` measures complete content under a separate

package/docs/texture-density.md

@@ -0,0 +1,96 @@
+# Texture density
+
+This API is included in Core 2.5.0, prepared for publication but not yet
+published. Published Core 2.4.0 and earlier do not interpret sheet `resolution`.
+
+`new Texture(resolution)` describes source pixels per logical unit. The default
+is 1; the value must be finite and positive, is immutable, and is inherited by
+SpriteSheet views. Different densities can share one scene and GPU batch.
+Player/ScreenAdapter resolution controls the output canvas independently.
+
+```ts
+const texture = new Texture(2);
+texture.setBitmapData(new BitmapData(image));
+// A 56×56 image has textureWidth/textureHeight of 28×28.
+const icon = new Bitmap(texture);
+```
+
+## Units
+
+| Value | Unit |
+| --- | --- |
+| BitmapData width/height | Physical source pixels |
+| Texture bitmapX/Y and bitmapWidth/Height | Physical atlas sampling pixels |
+| Texture sourceWidth/Height | Physical atlas page pixels used for UV normalization |
+| Texture offsetX/Y and textureWidth/Height | Logical units |
+| Texture scaleBitmapWidth/Height | Logical size of the sampled upright region |
+| Texture pixelScale | Logical units per source pixel, including textureScaleFactor |
+| SpriteSheet.createTexture arguments and sheet frame geometry | Source pixels |
+| Bitmap/Image width/height, scale9Grid and XML layout | Logical units |
+
+At the normal textureScaleFactor of 1, logical frame sizes and trim offsets are
+source values divided by resolution. Atlas coordinates and page dimensions are
+never divided for sampling. A grid is relative to the original untrimmed logical
+frame; atlas placement and trimmed physical offsets do not change that frame.
+
+## Sheet resources
+
+The density lives in the atlas JSON, beside `file` and `frames`, rather than in
+the resource manifest or XML. Omitting it retains 1× behavior. Invalid values
+fail the sheet load before its image is requested.
+
+```json
+{
+  "file": "kui.png",
+  "resolution": 2,
+  "frames": {
+    "button_up": { "x": 8, "y": 8, "w": 96, "h": 96 }
+  }
+}
+```
+
+The original frame is 48×48 logical units. Its manifest default remains
+`"scale9grid": "16,16,16,16"`. Images keep their existing XML allocation and
+corner sizes. Crop/trim/sourceW/sourceH in the sheet are physical pixels;
+logical original dimensions are sourceW/resolution and sourceH/resolution.
+
+Scale, clip, repeat, tint, nine-slice and Canvas-backed caches use each texture's
+pixelScale. Repeat periods and fixed nine-slice borders stay logical. UVs and
+GPU uploads still address the physical page. Mesh vertices remain authored
+logical geometry; density does not rescale vertices.
+
+Standalone ImageAnalyzer resources retain 1×; use an explicitly constructed
+Texture for an independently loaded high-density image. No filename suffix is
+inferred. RenderTexture retains its capture API and does not accept source-density
+constructor arguments. BitmapFont's literal descriptor metrics still require a
+page with resolution=1; this feature does not reinterpret font metrics.
+
+## Adoption and verification
+
+The default KUI kit now generates 2× pixels from SVG geometry with two physical
+pixels of extrusion, preserving logical layout, hit targets and grids. It needs
+Core ^2.5.0. Existing 1× resources require no
+migration. UI/Game/DragonBones/Spine/ui-runtime peer ranges accepting Core 2.x
+can use that Core release without an SDK bump. CLI still has no Core dependency.
+
+The source trial lives in an isolated directory under docs-internal and binds
+the built checkout Core explicitly; it does not alter registry locks. Read
+[default KUI skins](../../cli/docs/default-ui-skins.md) for the preview command.
+Publish Core 2.5.0 before CLI 3.6.0 so new scaffolds resolve the required Core.
+Editor/Reskin resource authoring tools must adopt the new Core and divide physical
+frame dimensions by sheet resolution when validating logical grids or measuring
+previews; their current released installations do not understand this metadata.
+
+Unit regressions cover mixed densities, nested trimmed views, atlas loading,
+fixed borders, trim, clip/repeat and rotated edge crops. The minified browser
+fill tests compare Canvas/WebGL 1/WebGL 2 pixels at output resolution 1×/2×
+with source density 1×/2×/3×, including tint, texture swaps, cache updates and
+nine-slice invariance.
+
+Source verification on 2026-10-10: Core implementation/declaration builds and
+890 unit tests pass; CLI's 112 tests pass. All six minified pixel cases pass
+across the three backends and two output resolutions. The isolated native KUI
+gallery passes dev/release checks in all three backends at render resolution 2:
+640×1136 logical stage/CSS, 1280×2272 backing pixels, 48×48 logical button frames
+from 96×96 source regions, 28×28 logical icons from 56×56 source regions, unchanged
+16,16,16,16 grids, pressed-state restoration and correctly mapped button taps.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/core",
-	"version": "2.4.0",
+	"version": "2.5.0",
 	"description": "Modern rewrite of the Egret game engine — WebGL multi-texture batching, instruction-driven render pipeline, strict TypeScript, Egret-compatible API",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",