@kurot/core 2.5.5 → 2.7.0

package/docs/bitmap-fonts.md

@@ -1,10 +1,5 @@
 # Bitmap fonts
 
-Available in Core 2.2.0 with the published `@kurot/bitmap-font ^0.1.0` dependency.
-Package installs and local builds resolve the font kernel from npm. Installed
-Core 2.1.1 does not include FontAnalyzer or BitmapText rendering; update Core and
-the lockfile to receive them. Source versions alone do not confirm publication.
-
 A bitmap font is a descriptor plus a full image page. Core owns image loading and
 rendering; @kurot/bitmap-font owns validation, parsing, serialization and layout.
 See [the shared format](../../bitmap-font/docs/format.md).
@@ -55,7 +50,7 @@ layout caches assume data does not mutate. Glyph subtextures are borrowed views.
 
 BitmapText has text/font, lineSpacing/letterSpacing, smoothing, multiline,
 left/center/right textAlign and top/middle/bottom verticalAlign. The default is
-multiline=true. Published Core 2.5.3 defaults verticalAlign to middle; published
+multiline=true. Core >= 2.5.3 defaults verticalAlign to middle; Core
 2.5.2 and earlier default to top. BitmapLabel inherits its host BitmapText default.
 Explicit top/bottom remain effective in either line mode. Core passes the selected
 alignment into the unchanged headless kernel, whose standalone layout default
@@ -70,8 +65,7 @@ Width and height are constraints, not scales; set scaleX/scaleY to resize font
 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:
+font assets. Texture density 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,
@@ -81,14 +75,11 @@ use that Canvas path. Both honor font offsets without allocating child nodes.
 Changing text/font/metrics invalidates layout and rendering, including an
 existing WebGL instruction without a scene rebuild.
 
-Core 2.2.0 fixes BitmapText's previous setter-only width/height accessors.
 BitmapText.EMPTY_FACTOR is retained as a deprecated field; per-font spaceAdvance
-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.
+controls fallback spaces. Line-height, trailing-advance and complete-line
+clipping follow the shared format contract.
 
-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.
+UI BitmapLabel adds native constraints and asynchronous configured-font loading.
+CLI and semantic runtime integrations use registered font resources; see
+[BitmapLabel](../../ui/docs/bitmap-label.md) and the
+[authoring contract](../../ui-document/docs/text-components.md).

package/docs/centered-flips.md

@@ -1,6 +1,6 @@
-# Centered display flips (Core 2.4.0)
+# Centered display flips
 
-Core 2.4.0 is published, verified on npm on 2026-10-09. `flipX` and `flipY` are boolean DisplayObject
+`flipX` and `flipY` are boolean DisplayObject
 properties, defaulting to false and inherited by all display subclasses.
 
 ```ts
@@ -9,7 +9,7 @@ sprite.scaleX = 0.5;
 ```
 
 Reflection uses the local content bounds center, including nonzero origins.
-UI 3.4 supplies the actual unscaled layout frame instead. A scrollRect uses its
+UI supplies the actual unscaled layout frame instead. A scrollRect uses its
 visible viewport. Authored position, scale, rotation, skew and anchors are
 preserved. Negative scale continues to act around the authored anchor; combining
 negative scale and a centered flag applies both. Resizing/content changes update
@@ -23,12 +23,6 @@ only when a display subclass owns a different local reflection frame.
 
 Canvas/WebGL rendering, local/global coordinate conversion, hits, clips,
 display-list caches and render groups use that effective transform. External
-masks retain their independent coordinates. No existing negative-scale skin or
-application is converted automatically. Core keeps bitmap-font ^0.1.0 and needs
-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. 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.
+masks retain their independent coordinates. Negative scale and centered flags remain separate authored operations. See the
+[shared flip contract](../../../docs/centered-flips.md) for authoring, runtime
+integration and current verification scope.

package/docs/game-authoring.md

@@ -1,9 +1,7 @@
 # Make a game with Kurot
 
-This guide is for game authors and models using the public SDK. It is an
-unreleased documentation addition, verified against registry Core 2.5.4; that
-published artifact does not yet include this file. Read installed declarations
-for APIs, then open only the topic guides needed by the current task.
+Use the public SDK and the consumer project's own README, declarations and
+bundled topic guides. This workflow needs no engine source in the game project.
 
 ## 1. Establish the project and its baseline
 
@@ -23,6 +21,12 @@ reproduction and preserve the chosen SDK versions while developing gameplay.
 CLI-compiled skins run through UI without ui-runtime. ui-document is headless;
 the game starter uses it for project styles, not as a rendering engine.
 
+For authored game UI, use the repository's
+[standard UI workflow](../../ui/docs/ui-authoring.md), including its directory
+map and paired ScoreHUD example. Those new guides postdate UI 3.6.1; use the
+repository copy until a later package includes them. The installed UI API
+reference remains the source for exact methods and properties.
+
 For a complete reference in an engine checkout, read
 [Star Catcher](../../../examples/star-catcher/README.md) and run its `pnpm check`.
 It demonstrates input → score → three misses → end → restart → cleanup with
@@ -43,6 +47,9 @@ app.start(root);
 ```
 
 `createPlayer` initializes capabilities, rendering, input and screen adaptation.
+CLI pages can use `createPlayer({ canvas })` with the defaults described in
+[stage configuration](stage-configuration.md). This requires Core >= 2.6.0
+within 2.x; keep explicit options with older installations.
 When customizing CLI-authored HTML, retain its import-map, stage and entry-script
 placeholders; the CLI validates all of them before generating the page.
 One Player owns the page's runtime hooks. Keep its canvas parent sized: the

package/docs/resource.md

@@ -190,7 +190,7 @@ Load a plain-text file through `HttpRequest`.
 const text = resource.get<string>('readme');
 ```
 
-### FontAnalyzer (2.2.0)
+### FontAnalyzer
 
 Load a font descriptor and its image page, resolved relative to the descriptor,
 and return a `BitmapFont`. Supported formats are Egret JSON `.fnt`, native JSON
@@ -227,7 +227,7 @@ Load a sprite sheet in TexturePacker JSON format in two steps:
 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.
+logical.
 
 Resources can be retrieved in three ways:
 
@@ -291,7 +291,7 @@ Applications normally use `Resource.loadGroup()` instead of accessing
 
 ## Configuration format
 
-### Standard format (2.0.0)
+### Standard format
 
 ```json
 {
@@ -322,6 +322,16 @@ Core does not apply it automatically to arbitrary Bitmap objects. See the
 - URLs containing `://` are treated as absolute and left unchanged.
 - Other URLs receive the `folder` prefix passed to `loadConfig()`.
 
+Core >= 2.7.0 within 2.x with CLI >= 3.8.1 within 3.x uses release metadata that Core
+transports use to append `?v=<release-build-number>` to same-origin resource/
+files. Resource keys and authored descriptors stay unchanged; atlas/font pages
+are versioned independently when loaded. JS retains its filename hash.
+Use `resolveResourceUrl` for native fetch/FontFace and UI Theme config URLs before
+Player startup. Without metadata, URLs stay unchanged. Remote URLs and APIs
+outside resource/ retain their original URLs. See the
+[CLI release protocol](../../cli/docs/release-assets.md) for examples and caching
+requirements.
+
 ### Creating groups dynamically
 
 ```typescript
@@ -339,7 +349,7 @@ import { resource, ResourceConfig } from '@kurot/core';
 | Modules              | Global `RES.xxx`          | ES module imports                    |
 | Events               | `egret.EventDispatcher`   | Lightweight `on/off` API             |
 | Type safety          | Extensive `any`           | Generic `get<T>()`                   |
-| Versioning           | `VersionController`       | Handled by build tools               |
+| Versioning           | `VersionController`       | CLI build metadata + Core URL resolution |
 | XML parsing          | Built in                  | Handled by the KUI XML compiler      |
 | Internationalization | Built in                  | Outside the resource loader's scope  |
 | Analyzer types       | 8                         | 6 (Image/Json/Text/Sound/Sheet/Font) |
@@ -349,8 +359,8 @@ import { resource, ResourceConfig } from '@kurot/core';
 
 The following legacy features are intentionally omitted:
 
-- **VersionController** — modern build tools such as Vite/Webpack handle CDN
-  versioning.
+- **VersionController class** — release metadata and `resolveResourceUrl` provide
+  resource query versioning without an application-supplied controller.
 - **i18n** — internationalization is outside the resource loader's scope.
 - **XML/Bin analyzers** — the compiler preprocesses KUI XML; a built-in binary
   analyzer is not included.

package/docs/stage-configuration.md

@@ -0,0 +1,75 @@
+# Canvas stage configuration
+
+`createPlayer()` resolves each startup stage setting independently:
+
+1. An explicitly supplied option.
+2. Its corresponding canvas attribute.
+3. The existing default shown below.
+
+| Option | Canvas attribute | Default without either |
+| --- | --- | --- |
+| `contentWidth` | `data-content-width` | `canvas.width`, or 640 when zero |
+| `contentHeight` | `data-content-height` | `canvas.height`, or 1136 when zero |
+| `scaleMode` | `data-scale-mode` | `showAll` |
+| `orientation` | `data-orientation` | `auto` |
+| `frameRate` | `data-frame-rate` | 60 |
+
+This behavior requires Core >= 2.6.0 within 2.x. CLI 3.8.0's game and empty
+templates use canvas-only startup and require that runtime. Older installations
+keep explicit stage options until adopting that Core release.
+
+For CLI-authored pages, put the defaults in `kurot.config.ts` or `.js`:
+
+```ts
+export default {
+  stage: {
+    width: 1136,
+    height: 640,
+    scaleMode: 'showAll',
+    orientation: 'landscape',
+    frameRate: 60,
+  },
+};
+```
+
+The CLI writes these values into the HTML canvas. The browser entry only needs:
+
+```ts
+import { createPlayer, Sprite } from '@kurot/core';
+
+const canvas = document.getElementById('gameCanvas');
+if (!(canvas instanceof HTMLCanvasElement)) {
+  throw new Error('Missing gameCanvas.');
+}
+const app = createPlayer({ canvas });
+app.start(new Sprite());
+```
+
+An explicit `createPlayer({ canvas, frameRate: 30 })` overrides only the frame
+rate. It also bypasses validation of that attribute. Consumed width/height
+attributes must be finite and positive; frame rate must be a positive integer.
+Scale modes use `StageScaleMode`; orientations use `OrientationMode`, including
+`landscapeFlipped`. Invalid consumed attributes throw before Player allocation.
+
+Attributes are read once. Editing them does not reconfigure a live Player.
+With CLI stage watching, save configuration, wait for its successful update,
+then manually refresh the browser. A new Player reads the new page defaults.
+Existing ScreenAdapter sizing, logical coordinate rounding and DPR behavior
+remain unchanged; these are design dimensions, not backing-store pixel sizes.
+
+Core does not load the CLI or import project configuration. Non-CLI applications
+can supply explicit options or author the same canvas attributes themselves.
+
+## Verification
+
+After building both `packages/core` and `packages/cli`, run from Core:
+
+```sh
+pnpm test:stage-config
+pnpm test:stage-config --canvas
+```
+
+The real CLI/browser check uses the empty template, edits stage defaults on the
+same dev process, manually reloads the page and inspects the resulting Stage.
+It also covers invalid-config retention/recovery, explicit overrides and release
+startup, using built Core/CLI without modifying consumer locks.