@kurot/core 2.1.1 → 2.2.0

package/docs/bitmap-fonts.md

@@ -0,0 +1,85 @@
+# 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).
+
+```ts
+import { BitmapFont, BitmapText, resource } from '@kurot/core';
+
+resource.addResource({
+  name: 'number_font_fnt',
+  type: 'font',
+  url: 'resource/assets/font/number_font.fnt',
+});
+const font = await resource.load<BitmapFont>('number_font_fnt');
+const text = new BitmapText();
+text.font = font;
+text.multiline = false;
+text.text = '1,234.56';
+stage.addChild(text);
+```
+
+`font` is a built-in ResourceType and FontAnalyzer. The descriptor's file is
+resolved relative to the descriptor URL, including URLs with queries. Loading
+resolves only after both descriptor and page are ready. Concurrent requests for
+one font share the pending load. A separately configured PNG resource has
+independent ownership; loading it is not required for the font.
+
+Supported descriptors: native version-1 JSON, Egret frames JSON, single-page
+unpacked BMFont text. XML/binary/multi-page/channel-packed fonts are unsupported.
+Glyph coordinates must fit a complete, unrotated page texture.
+
+## Direct texture injection and ownership
+
+```ts
+const font = new BitmapFont(pageTexture, descriptor, { ownsTexture: false });
+```
+
+Direct construction owns the page by default, retaining the SpriteSheet lifecycle
+contract. Set ownsTexture=false for a page owned by a project asset cache. Font
+dispose is idempotent, invalidates subsequent getTexture calls, and disposes only
+owned page data. BitmapText borrows the font; removing text never disposes it.
+FontAnalyzer owns its internal page cache and frees it on resource.destroy(name).
+Do not destroy a font while text using it remains displayed.
+
+Parsed `font.data` is a deeply frozen snapshot. Changes require a new font; render
+layout caches assume data does not mutate. Glyph subtextures are borrowed views.
+
+## Text metrics and rendering
+
+BitmapText has text/font, lineSpacing/letterSpacing, smoothing, multiline,
+left/center/right textAlign and top/middle/bottom verticalAlign. The default is
+multiline=true. Font metrics, fallback spaces, kerning, wrapping and bounds come
+from layoutBitmapText. `getLayout()` and `getGlyphs()` expose borrowed readonly
+layout data, while textWidth/textHeight report admitted line metrics.
+measureText(width?, height?) measures independently without mutating rendered
+constraints or invalidating its cached layout. UI uses it for measurement.
+
+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.
+
+WebGL's BitmapTextPipe submits cropped glyph quads to ordinary texture batching,
+with current transforms, alpha, tint, blend, clipping and filters. Canvas uses the
+same layout and glyph geometry, including tint; cacheAsTexture and RenderTexture
+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.
+
+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.

package/docs/resource.md

@@ -1,39 +1,43 @@
-# 资源管理器 (Resource Manager)
+# Resource Manager
 
-## 概述
+## Overview
 
-Kurot 资源管理器是从 Egret RES 模块现代化迁移而来的异步资源加载与缓存系统。它提供：
+Kurot's resource manager is an asynchronous loading and caching system adapted
+from Egret RES. It provides:
 
-- **async/await API** — 所有加载操作返回 Promise
-- **类型安全** — `ResourceType` 枚举 + 泛型 `get<T>()`
-- **配置驱动** — 兼容 Egret `resource.json` 格式
-- **按组加载** — 并发控制（默认 2 线程）、自动重试（默认 3 次）
-- **可扩展** — 自定义 Analyzer 支持新资源类型
-- **零外部依赖** — 仅依赖 core 内部的 `net/` 和 `events/`
+- **async/await API** — loading operations return promises.
+- **Type safety** — the `ResourceType` enum and generic `get<T>()` API.
+- **Configuration-driven loading** — support for Egret `resource.json` files.
+- **Group loading** — concurrency control (2 concurrent loads by default) and
+  automatic retries (3 retries by default).
+- **Extensibility** — custom analyzers for additional resource types.
+- **Shared font kernel** — FontAnalyzer parses descriptors through
+  `@kurot/bitmap-font`; loading uses Core's `net/` and `events/` modules.
 
-## 目录结构
+## Directory structure
 
 ```
 packages/core/src/kurot/resource/
-├── index.ts              — 统一导出
-├── Resource.ts           — 资源管理器主类（单例 + 便捷实例）
-├── ResourceConfig.ts     — 配置文件解析
-├── ResourceLoader.ts     — 队列加载器（并发 + 重试）
-├── ResourceItem.ts       — 资源项定义 + ResourceType 枚举
-├── ResourceEvent.ts      — 事件类型定义
+├── index.ts              — public exports
+├── Resource.ts           — resource manager and shared instance
+├── ResourceConfig.ts     — resource configuration parsing
+├── ResourceLoader.ts     — queued loading, concurrency and retries
+├── ResourceItem.ts       — resource items and the ResourceType enum
+├── ResourceEvent.ts      — resource event types
 └── analyzers/
     ├── index.ts
-    ├── AnalyzerBase.ts   — 解析器抽象基类
-    ├── ImageAnalyzer.ts  — 图片 → Texture
-    ├── JsonAnalyzer.ts   — JSON 文件 → object
-    ├── TextAnalyzer.ts   — 纯文本 → string
-    ├── SoundAnalyzer.ts  — 音频 → HTMLAudioElement
-    └── SheetAnalyzer.ts  — 精灵表 JSON + 图片 → SpriteSheet
+    ├── AnalyzerBase.ts   — analyzer base class
+    ├── ImageAnalyzer.ts  — image → Texture
+    ├── JsonAnalyzer.ts   — JSON file → object
+    ├── TextAnalyzer.ts   — plain text → string
+    ├── SoundAnalyzer.ts  — audio → HTMLAudioElement
+    ├── FontAnalyzer.ts   — font descriptor + image → BitmapFont
+    └── SheetAnalyzer.ts  — sprite-sheet JSON + image → SpriteSheet
 ```
 
-## 快速开始
+## Quick start
 
-### 1. 准备配置文件
+### 1. Prepare a configuration file
 
 ```json
 // resource.json
@@ -50,100 +54,101 @@ packages/core/src/kurot/resource/
 }
 ```
 
-### 2. 加载与使用
+### 2. Load and use resources
 
 ```typescript
 import { resource, ResourceType } from '@kurot/core';
 
-// 加载配置
+// Load the configuration.
 await resource.loadConfig('resource.json', 'assets/');
 
-// 按组加载
+// Load a resource group.
 await resource.loadGroup('preload');
 
-// 获取缓存的资源（泛型）
+// Read a cached resource with a generic result type.
 const texture = resource.get<Texture>('bg');
 
-// 异步加载单个资源
+// Load a single resource asynchronously.
 const data = await resource.load<object>('config');
 
-// 监听加载进度
+// Track this group's loading progress.
 await resource.loadGroup('game', 0, (loaded, total) => {
-	console.log(`进度: ${loaded}/${total}`);
+	console.log(`Progress: ${loaded}/${total}`);
 });
 ```
 
-## API 参考
+## API reference
 
-### Resource 主类
+### Resource
 
-#### 配置
+#### Configuration
 
-| 方法                       | 说明                                               |
-| -------------------------- | -------------------------------------------------- |
-| `loadConfig(url, folder?)` | 加载并解析 resource.json，`folder` 为资源 URL 前缀 |
-| `addResource(def)`         | 动态添加资源定义 `{ name, url, type }`             |
+| Method                     | Description                                                    |
+| -------------------------- | -------------------------------------------------------------- |
+| `loadConfig(url, folder?)` | Load and parse resource.json; `folder` prefixes resource URLs. |
+| `addResource(def)`         | Add a resource definition `{ name, url, type }` dynamically.   |
 
-#### 加载
+#### Loading
 
-| 方法                                      | 说明                                         |
-| ----------------------------------------- | -------------------------------------------- |
-| `loadGroup(name, priority?, onProgress?)` | 按组加载，返回 Promise。已加载的资源自动跳过 |
-| `load<T>(name)`                           | 异步加载单个资源，返回缓存数据               |
+| Method                                    | Description                                                       |
+| ----------------------------------------- | ----------------------------------------------------------------- |
+| `loadGroup(name, priority?, onProgress?)` | Load a group and return a promise; skip resources already loaded. |
+| `load<T>(name)`                           | Load a single resource and return its cached data.                |
 
-#### 缓存
+#### Cache and lookup
 
-| 方法              | 说明                                     |
-| ----------------- | ---------------------------------------- |
-| `get<T>(name)`    | 同步获取缓存资源，未加载返回 `undefined` |
-| `hasRes(name)`    | 检查资源是否已缓存                       |
-| `hasGroup(name)`  | 检查组是否存在                           |
-| `getGroupNames()` | 获取所有组名                             |
+| Method            | Description                                                              |
+| ----------------- | ------------------------------------------------------------------------ |
+| `get<T>(name)`    | Read a cached resource synchronously; return `undefined` if unavailable. |
+| `hasRes(name)`    | Check whether a resource is cached by an analyzer.                       |
+| `hasGroup(name)`  | Check whether a group exists.                                            |
+| `getGroupNames()` | Return all group names.                                                  |
 
-#### 销毁
+#### Destruction
 
-| 方法                 | 说明                   |
-| -------------------- | ---------------------- |
-| `destroy(name)`      | 销毁单个资源，释放缓存 |
-| `destroyGroup(name)` | 销毁整组资源           |
-| `destroyAll()`       | 销毁所有已加载资源     |
+| Method               | Description                                     |
+| -------------------- | ----------------------------------------------- |
+| `destroy(name)`      | Destroy a resource and release its cached data. |
+| `destroyGroup(name)` | Destroy all resources in a group.               |
+| `destroyAll()`       | Destroy all loaded resources.                   |
 
-#### 事件
+#### Events
 
-| 方法                   | 说明                                   |
-| ---------------------- | -------------------------------------- |
-| `on(type, listener)`   | 监听资源事件                           |
-| `off(type, listener)`  | 移除事件监听                           |
-| `onProgress(callback)` | 便捷进度监听 `(loaded, total) => void` |
+| Method                 | Description                                             |
+| ---------------------- | ------------------------------------------------------- |
+| `on(type, listener)`   | Listen for a resource event.                            |
+| `off(type, listener)`  | Remove an event listener.                               |
+| `onProgress(callback)` | Register a progress listener `(loaded, total) => void`. |
 
-#### 扩展
+#### Extension
 
-| 方法                               | 说明                     |
-| ---------------------------------- | ------------------------ |
-| `registerAnalyzer(type, analyzer)` | 注册自定义资源类型解析器 |
+| Method                             | Description                                      |
+| ---------------------------------- | ------------------------------------------------ |
+| `registerAnalyzer(type, analyzer)` | Register an analyzer for a custom resource type. |
 
-### ResourceType 枚举
+### ResourceType
 
-| 值        | 说明                              |
-| --------- | --------------------------------- |
-| `'image'` | 图片资源，生成 `Texture`          |
-| `'json'`  | JSON 文件，解析为 `object`        |
-| `'text'`  | 纯文本文件，返回 `string`         |
-| `'sound'` | 音频文件，返回 `HTMLAudioElement` |
-| `'sheet'` | 精灵表，返回 `SpriteSheet`        |
+| Value     | Description                                   |
+| --------- | --------------------------------------------- |
+| `'image'` | Image resource producing a `Texture`.         |
+| `'json'`  | JSON file parsed as an `object`.              |
+| `'text'`  | Plain-text file returned as a `string`.       |
+| `'sound'` | Audio file returned as an `HTMLAudioElement`. |
+| `'sheet'` | Sprite sheet returned as a `SpriteSheet`.     |
+| `'font'`  | Bitmap font returned as a `BitmapFont`.       |
 
-### ResourceEventType 事件类型
+### ResourceEventType
 
-| 事件                | 触发时机                 |
-| ------------------- | ------------------------ |
-| `CONFIG_COMPLETE`   | 配置文件加载完成         |
-| `CONFIG_LOAD_ERROR` | 配置文件加载失败         |
-| `GROUP_COMPLETE`    | 资源组全部加载完成       |
-| `GROUP_PROGRESS`    | 资源组中单个资源加载完成 |
-| `GROUP_LOAD_ERROR`  | 资源组中有资源加载失败   |
-| `ITEM_LOAD_ERROR`   | 单个资源加载失败         |
+| Event               | Trigger                                   |
+| ------------------- | ----------------------------------------- |
+| `CONFIG_COMPLETE`   | Configuration loading completes.          |
+| `CONFIG_LOAD_ERROR` | Configuration loading fails.              |
+| `GROUP_COMPLETE`    | All resources in a group finish loading.  |
+| `GROUP_PROGRESS`    | A resource in the group finishes loading. |
+| `GROUP_LOAD_ERROR`  | A resource in the group fails to load.    |
+| `ITEM_LOAD_ERROR`   | A single resource fails to load.          |
 
-### ResourceEvent 接口
+### ResourceEvent
 
 ```typescript
 interface ResourceEvent {
@@ -155,20 +160,20 @@ interface ResourceEvent {
 }
 ```
 
-## 内置解析器
+## Built-in analyzers
 
 ### ImageAnalyzer
 
-加载图片并创建 `Texture` 对象。销毁时自动调用 `texture.dispose()`。
+Load an image and create a `Texture`. Destruction calls `texture.dispose()`.
 
 ```typescript
 const texture = resource.get<Texture>('bg');
-// texture 可直接用于 Bitmap 显示对象
+// Use the texture with a Bitmap display object.
 ```
 
 ### JsonAnalyzer
 
-通过 `HttpRequest` 加载 JSON 文件并解析为对象。
+Load a JSON file through `HttpRequest` and parse it into an object.
 
 ```typescript
 const config = resource.get<Record<string, unknown>>('config');
@@ -176,15 +181,33 @@ const config = resource.get<Record<string, unknown>>('config');
 
 ### TextAnalyzer
 
-通过 `HttpRequest` 加载纯文本文件。
+Load a plain-text file through `HttpRequest`.
 
 ```typescript
 const text = resource.get<string>('readme');
 ```
 
+### FontAnalyzer (2.2.0)
+
+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
+and single-page, unpacked BMFont text. Concurrent requests for the same font share
+one load. Destroying the font releases its internal page; a separately configured
+PNG resource retains independent ownership. Display objects borrow the font, so
+removing text does not destroy it. See [bitmap fonts](bitmap-fonts.md) for formats,
+texture restrictions and lifecycle contracts.
+
+```typescript
+import { BitmapFont, resource } from '@kurot/core';
+
+resource.addResource({ name: 'numbers', type: 'font', url: 'assets/number_font.fnt' });
+const font = await resource.load<BitmapFont>('numbers');
+```
+
 ### SoundAnalyzer
 
-加载音频文件，返回 `HTMLAudioElement`。销毁时自动 `pause()` 并释放 `src`。
+Load an audio file and return an `HTMLAudioElement`. Destruction calls `pause()`
+and releases `src`.
 
 ```typescript
 const audio = resource.get<HTMLAudioElement>('bgm');
@@ -193,27 +216,27 @@ audio.play();
 
 ### SheetAnalyzer
 
-加载精灵表（TexturePacker JSON 格式），两步加载：
+Load a sprite sheet in TexturePacker JSON format in two steps:
 
-1. 加载 JSON 配置获取帧信息和图片路径
-2. 加载关联图片，切割为子纹理
+1. Load the JSON descriptor to obtain frame data and the image path.
+2. Load the image and create subtextures.
 
-支持三种获取方式：
+Resources can be retrieved in three ways:
 
 ```typescript
-// 获取整个 SpriteSheet
+// Retrieve the complete SpriteSheet.
 const sheet = resource.get<SpriteSheet>('hero');
 
-// 通过子键名直接获取子纹理
+// Retrieve a subtexture directly by its subkey name.
 const frame = resource.get<Texture>('hero_idle_01');
 
-// 通过点号语法获取
+// Retrieve a subtexture with dot notation.
 const frame2 = resource.get<Texture>('hero.idle_01');
 ```
 
-## 自定义解析器
+## Custom analyzers
 
-继承 `AnalyzerBase` 实现自定义资源类型：
+Extend `AnalyzerBase` to implement a custom resource type:
 
 ```typescript
 import { AnalyzerBase } from '@kurot/core';
@@ -242,92 +265,98 @@ class XmlAnalyzer extends AnalyzerBase {
 	}
 }
 
-// 注册
+// Register the analyzer.
 resource.registerAnalyzer('xml', new XmlAnalyzer());
 ```
 
-## 队列加载器 (ResourceLoader)
+## Queued loading (ResourceLoader)
 
-`ResourceLoader` 是内部使用的队列加载器，支持：
+`ResourceLoader` is the internal queue loader. It supports:
 
-- **并发控制** — `threadCount`（默认 2）限制同时加载数
-- **自动重试** — `retryCount`（默认 3）次重试后报告失败
-- **回调通知** — `onComplete` / `onError` / `onProgress`
+- **Concurrency control** — `threadCount` limits simultaneous loads (default 2).
+- **Automatic retries** — `retryCount` controls retries before reporting failure
+  (default 3).
+- **Notifications** — `onComplete`, `onError` and `onProgress` callbacks.
 
-通常不需要直接使用 `ResourceLoader`，通过 `Resource.loadGroup()` 即可间接使用。
+Applications normally use `Resource.loadGroup()` instead of accessing
+`ResourceLoader` directly.
 
-## 配置文件格式
+## Configuration format
 
-### 标准格式（2.0.0）
+### Standard format (2.0.0)
 
 ```json
 {
 	"resources": [
 		{
-			"name": "资源唯一标识",
-			"type": "image|json|text|sound|sheet",
-			"url": "相对或绝对路径",
+			"name": "uniqueResourceName",
+			"type": "image|json|text|sound|sheet|font",
+			"url": "relative-or-absolute-path",
 			"subkeys": { "frameName": { "scale9grid": "1,1,2,2" }, "ordinaryFrame": {} }
 		}
 	],
 	"groups": [
 		{
-			"name": "组名",
-			"keys": "逗号分隔的资源名称"
+			"name": "groupName",
+			"keys": "resource1,resource2"
 		}
 	]
 }
 ```
 
-当前源码的 `subkeys` 为对象，旧字符串需要在 Editor 中显式刷新图集后再使用。
-`scale9grid` 是 Image 编译默认值，Core 不会自动把它应用到任意 Bitmap。
-参见 [资源默认九宫格契约](../../ui-document/docs/resource-nine-slice.md)。
+`subkeys` is an object map. Refresh legacy sheets explicitly in the Editor before
+using old string-based manifests. `scale9grid` supplies Image compilation defaults;
+Core does not apply it automatically to arbitrary Bitmap objects. See the
+[resource nine-slice defaults contract](../../ui-document/docs/resource-nine-slice.md).
 
-### URL 解析规则
+### URL resolution
 
-- 包含 `://` 的 URL 视为绝对路径，不做处理
-- 其他 URL 会在前面拼接 `loadConfig()` 的 `folder` 参数
+- URLs containing `://` are treated as absolute and left unchanged.
+- Other URLs receive the `folder` prefix passed to `loadConfig()`.
 
-### 动态创建组
+### Creating groups dynamically
 
 ```typescript
 import { resource, ResourceConfig } from '@kurot/core';
 
-// 通过 ResourceConfig 的 createGroup 方法
-// 注意：这是底层 API，通常通过配置文件定义组
+// Use ResourceConfig.createGroup for low-level group creation.
+// Applications usually define groups in configuration files.
 ```
 
-## 与 Egret RES 的对比
-
-| 维度       | Egret RES               | Kurot Resource                      |
-| ---------- | ----------------------- | ----------------------------------- |
-| API 风格   | 回调 `compFunc(data)`   | `async/await` + Promise             |
-| 模块化     | 全局 `RES.xxx`          | ES Module 导入                      |
-| 事件系统   | `egret.EventDispatcher` | 轻量 `on/off` 模式                  |
-| 类型安全   | 大量 `any`              | 泛型 `get<T>()`                     |
-| 版本控制   | `VersionController`     | 剔除（构建工具处理）                |
-| XML 解析   | 内置                    | 剔除（KUI XML compiler 处理）          |
-| 国际化     | 内置                    | 剔除（不属于资源加载器职责）        |
-| 解析器类型 | 8 种                    | 5 种（Image/Json/Text/Sound/Sheet） |
-| 代码量     | ~3,000 行               | ~1,400 行                           |
-
-### 剔除的功能
-
-以下旧版功能被有意剔除：
-
-- **VersionController** — CDN 版本控制由现代构建工具（Vite/Webpack）处理
-- **i18n 国际化** — 不属于资源加载器的职责
-- **XML/Bin 分析器** — KUI XML 由 compiler 预处理，Binary 格式初期不需要
-- **AnimationAnalyzer** — 初期不需要，后续按需添加
-- **FontAnalyzer** — 初期不需要，后续按需添加
-- **同步 getRes() 的复杂 sheet 子键查找** — 简化为点号语法
-
-## 注意事项
-
-1. **并发 `loadGroup` 调用会排队串行执行** — 内部共享一个 `ResourceLoader` 实例，同时调用多个 `loadGroup`（同组或不同组）不会互相覆盖回调或丢失进度；每次调用仍各自独立 resolve/reject，只是底层批次按调用顺序依次执行，不会真正并行加载。
-
-2. **`onProgress` 监听器不会自动移除** — 每次 `onProgress()` 调用会添加一个永久监听器。如需一次性监听，请使用 `loadGroup` 的 `onProgress` 参数。
-
-3. **Sheet 子键冲突** — 不同精灵表的子纹理名称不应重复，后加载的不会覆盖先加载的同名子键。
-
-4. **资源 URL 需要同源或 CORS** — 图片和音频加载受浏览器同源策略限制。
+## Comparison with Egret RES
+
+| Aspect               | Egret RES                 | Kurot Resource                       |
+| -------------------- | ------------------------- | ------------------------------------ |
+| API style            | Callback `compFunc(data)` | `async/await` and promises           |
+| 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               |
+| 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) |
+| Code size            | Approximately 3,000 lines | Approximately 1,400 lines            |
+
+### Omitted features
+
+The following legacy features are intentionally omitted:
+
+- **VersionController** — modern build tools such as Vite/Webpack handle CDN
+  versioning.
+- **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.
+- **AnimationAnalyzer** — not included; a custom analyzer can provide it if needed.
+- **Complex synchronous getRes() sheet-subkey lookup** — replaced by dot notation.
+
+## Usage notes
+
+1. **Concurrent `loadGroup` calls are queued serially.** They share one internal
+   `ResourceLoader`. Calls for the same or different groups retain their own
+   callbacks and promise results, but the underlying batches run sequentially.
+2. **`onProgress` listeners are permanent.** For tracking a single load operation,
+   use the callback parameter of `loadGroup`.
+3. **Sheet subkey collisions.** Avoid duplicate subtexture names across sheets;
+   later sheets do not replace an earlier sheet's subkey registration.
+4. **Resource URLs require same-origin access or CORS.** Browser access rules
+   apply to images and audio.

package/docs/text-layout.md

@@ -65,13 +65,15 @@ regressions. No resource-manifest or CLI XML-format change is involved.
 
 ## Package dependencies
 
-UI 3.1.0 and ui-runtime 0.8.0 declare Core `^2.1.0` in their peer/development
-ranges; game 2.0.0 declares `^2.0.0`. Repository examples require Core `^2.1.0`.
-These ranges all accept 2.1.1, but installed lockfiles need updating to receive
-its nested scroll-clipping fix. CLI templates use `latest`.
+UI 3.1.0 and ui-runtime 0.8.2 declare Core `^2.1.0` in their peer ranges;
+game 2.0.0 declares `^2.0.0`. Their development dependencies and repository
+examples use Core `^2.1.1`, with lockfiles resolving 2.1.1 for its nested
+scroll-clipping fix. CLI templates use `latest`.
 Label font shrinking calls `invalidateTextMetrics()` and requires Core 2.1.0
-or later. Core 2.1.1 preserves that text contract and does not require another
-UI, game or ui-runtime release.
+or later. Core 2.2.0 preserves that TextField contract and remains accepted by
+these existing peer ranges. Bitmap-font rendering is separate from TextField;
+see [bitmap fonts](bitmap-fonts.md). The new UI BitmapLabel requires Core 2.2.0
+and its own UI release; published UI 3.1.0 does not contain it.
 
 References: [UAX #14 revision 55](https://www.unicode.org/reports/tr14/tr14-55.html),
 [official corpus](https://www.unicode.org/Public/17.0.0/ucd/auxiliary/LineBreakTest.txt),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/core",
-	"version": "2.1.1",
+	"version": "2.2.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",
@@ -68,6 +68,7 @@
 		"access": "public"
 	},
 	"dependencies": {
-		"@cto.af/linebreak": "4.0.3"
+		"@cto.af/linebreak": "4.0.3",
+		"@kurot/bitmap-font": "^0.1.0"
 	}
 }