@kurot/core 2.0.0 → 2.0.1

package/docs/filters.md

@@ -0,0 +1,232 @@
+# GPU filters
+
+Kurot executes `displayObject.filters` in array order. Each filter reads the
+previous filter's image. WebGL 1 and WebGL 2 are supported; shader sources are
+compiled verbatim, with no automatic GLSL translation.
+
+## Built-in effects
+
+- `ColorMatrixFilter`: color-matrix transform with premultiplied-alpha handling.
+- `BlurFilter(x, y, quality)`: non-negative logical-pixel radii; `quality` is an
+  integer from 1 to 16. Each quality step adds one horizontal/vertical pair,
+  using radius / sqrt(quality) to approximately preserve variance. The kernel
+  remains the existing triangular kernel. Large radii use a reduced-resolution
+  image so the per-axis shader radius stays within 32 physical pixels, then
+  resample back. This trades fine detail for wider blur; it is not bokeh DoF.
+- `GlowFilter` / `DropShadowFilter`: the existing radial alpha-sampling shader.
+  `knockout=false` preserves the original. `hideObject` hides the original for
+  shadows. Their `quality` field remains serialized metadata; it does not
+  change this shader's fixed sample count.
+- `BloomFilter`: LDR brightness extraction, blur, and original-image composition.
+
+```ts
+import { BloomFilter, BlurFilter } from '@kurot/core';
+
+const blur = new BlurFilter(12, 12, 2);
+blur.resolution = 0.5;
+background.filters = [blur];
+
+const bloom = new BloomFilter({
+    threshold: 0.7,
+    intensity: 1,
+    blur: 12,
+    blurScale: 0.5,
+});
+world.filters = [bloom];
+bloom.intensity = 0.8;
+```
+
+`Filter.resolution` specifies physical pixels per logical unit. `undefined`
+inherits the parent. A filter chain uses the minimum of the parent resolution
+and its explicit filter resolutions, additionally limited by GPU texture size.
+`BloomFilter.blurScale` reduces only extraction/blur; the original is retained
+at the effect's full resolution.
+
+Filtering includes the rendered descendants. Padding from consecutive filters
+is added; descendant effect extents are included without changing layout bounds.
+A mask/scroll clip on the filtered object clips its final result. Layered
+containers provide control over whether a mask clips before or after another
+effect. A lone ColorMatrix on an unmasked leaf with inherited resolution retains
+its inline fast path; groups and combinations use offscreen composition.
+
+## CustomFilter
+
+Use `CustomFilter.from()` to provide explicit backend variants. Omit a vertex
+source to use Kurot's standard filter quad. A missing backend throws a descriptive
+error rather than silently drawing the unfiltered image.
+
+```ts
+import { CustomFilter } from '@kurot/core';
+
+const dissolve = CustomFilter.from({
+    webgl1: {
+        fragment: `precision mediump float;
+        varying vec2 vTextureCoord;
+        uniform sampler2D uSampler;
+        uniform float threshold;
+        void main() {
+            gl_FragColor = texture2D(uSampler, vTextureCoord)
+                * step(threshold, vTextureCoord.x);
+        }`,
+    },
+    webgl2: {
+        fragment: `#version 300 es
+        precision mediump float;
+        in vec2 vTextureCoord;
+        uniform sampler2D uSampler;
+        uniform float threshold;
+        out vec4 result;
+        void main() {
+            result = texture(uSampler, vTextureCoord)
+                * step(threshold, vTextureCoord.x);
+        }`,
+    },
+    uniforms: { threshold: 0 },
+    padding: 0,
+});
+actor.filters = [dissolve];
+dissolve.setUniform('threshold', 0.5);
+```
+
+The existing `new CustomFilter(vertex, fragment, uniforms)` constructor submits
+that exact source pair on either backend; the caller is responsible for source
+compatibility. An empty vertex source selects the backend's standard vertex.
+The source-pair key distinguishes vertex/fragment boundaries. Compiled programs
+are cached by context and actual source, so uniforms are never part of the key.
+Do not generate new shader text every frame; update uniforms instead.
+
+Supported uniforms: `float`, `int`, `bool`, floating/integer/boolean vectors,
+`mat2`, `mat3`, `mat4`, and their numeric arrays. Values are numbers, booleans,
+numeric arrays, `Float32Array`, or `Int32Array`. Matrices use column-major order.
+Active uniforms must be supplied with the correct component count; missing,
+non-finite, or incompatible values throw before drawing. Unsigned uniforms,
+non-square matrices, sampler arrays and uniform blocks are not part of this API.
+
+`setUniform()` / `setTexture()` invalidate attached objects. After direct edits
+to an array, `filter.uniforms`, or binding descriptor, call `filter.invalidate()`.
+Built-in effect setters invalidate their users as well.
+
+### Coordinates and automatic uniforms
+
+The default vertex accepts `aVertexPosition` (vec2), `aTextureCoord` (vec2), and
+`aColor` (vec4), with `projectionVector` (vec2). Custom vertex programs must use
+this attribute layout. Vertex displacement needs sufficient `padding` and does
+not change scene geometry, layout or hit testing.
+
+`vTextureCoord` uses **bottom-left framebuffer UVs**: the top is y=1. It spans
+the entire padded input, not just the unpadded object. Input/output colors are
+premultiplied RGBA. `vColor` is neutral in custom intermediate passes because
+subtree vertices have already received world alpha/tint. For effects that need
+straight RGB, divide by alpha only when alpha is positive, then premultiply the
+output again.
+
+| Reserved uniform | GLSL type | Value |
+| --- | --- | --- |
+| `uSampler` | sampler2D | Previous pass image, texture unit 0 |
+| `projectionVector` | vec2 | Quad projection, managed by the renderer |
+| `uTextureSize` | vec2 | Input width/height in physical pixels |
+| `uInputSize` | vec4 | Input width, height, inverse width, inverse height |
+| `uInputClamp` | vec4 | Input texel-center UV min/max |
+| `uOutputSize` | vec4 | Output width, height, inverse width, inverse height |
+| `uResolution` | float | Requested output pixels per logical unit for this pass |
+
+Only declare the uniforms needed by the shader. They cannot be overridden in
+`uniforms` or auxiliary bindings. Small textures may round to one physical pixel.
+Use actual `uInputSize` / `uOutputSize` when exact texel spacing matters.
+
+UV distortion should clamp to `uInputClamp`. A sample outside [0,1] otherwise
+uses clamp-to-edge sampling, not automatic transparent border behavior.
+
+## Auxiliary images
+
+`textures` maps sampler names to full-image `BitmapData` resources. The caller
+retains ownership. Cropped/rotated atlas `Texture` objects are not accepted.
+Auxiliary uploads have their own nearest/linear sampling state, so they do not
+change the same image's sprite sampling.
+
+```ts
+filter.setTexture('uMap', { source: mapBitmapData, smoothing: false });
+```
+
+Declare `uniform sampler2D uMap`. Optionally declare `uMapMatrix` (mat3) and
+`uMapClamp` (vec4). The default matrix converts bottom-left filter UV to top-left
+image UV. For example, in GLSL 1.00:
+
+```glsl
+vec2 mapUV = (uMapMatrix * vec3(vTextureCoord, 1.0)).xy;
+vec2 displacement = texture2D(uMap, clamp(mapUV, uMapClamp.xy, uMapClamp.zw)).rg * 2.0 - 1.0;
+vec2 uv = vTextureCoord + displacement * amplitude / uTextureSize;
+gl_FragColor = texture2D(uSampler, clamp(uv, uInputClamp.xy, uInputClamp.zw));
+```
+
+This maps the image across the padded input. `transform: [a,b,c,d,tx,ty]` can
+replace the affine mapping; it is expressed directly in normalized UV units.
+The default is `[1,0,0,-1,0,1]`.
+
+After editing canvas/video content, call `BitmapData.invalidate(source)` so the
+next pass uploads the new pixels. Call `filter.invalidate()` when application
+scheduling also needs an explicit invalidation. Disposed or unavailable sources
+throw instead of sampling stale pixels. Texture units are checked against the
+context's fragment-stage limit, including the primary input.
+
+## Multi-pass effects
+
+`MultiPassFilter` accepts 1–32 immutable pass descriptions. A pass reads the
+previous output by default. `input: 'original'` reads the input to this effect;
+`input: 0` reads the first pass output. Additional `textures` references use the
+same notation and are supported by CustomFilter passes only. Forward references,
+cycles and nested MultiPassFilter instances are rejected.
+
+```ts
+import { MultiPassFilter } from '@kurot/core';
+
+const effect = new MultiPassFilter([
+    { filter: extractHighlights, scale: 0.5 },
+    { filter: blurHighlights, scale: 0.5 },
+    { filter: combine, textures: { uOriginal: 'original' } },
+]);
+world.filters = [effect];
+```
+
+Here `combine` declares `uniform sampler2D uOriginal`. Borrowed framebuffer
+inputs share the primary input's bottom-left UV convention; their automatic
+`<name>Matrix` is identity. Primary and additional inputs may differ in pixel
+size but cover the same logical rectangle. `scale` is relative to the enclosing
+effect resolution, not the previous pass. Per-pass filter `resolution` can
+further reduce its output resolution. Update child filter uniforms to animate;
+replace the MultiPassFilter to change its pass graph.
+
+GPU targets are never exposed to application code. The renderer preserves inputs
+until their consumers finish, prohibits framebuffer feedback and recycles owned
+targets even after errors. The idle intermediate pool is limited to 16 targets
+and 64 MiB. Active pass images, subtree capture buffers and auxiliary images are
+not included in that idle limit. Player's framebuffer pool counters report this
+intermediate pool. `Player.destroy()` releases idle effect targets and auxiliary
+uploads; caller image objects remain intact. Context restoration recreates
+programs, intermediate targets and auxiliary uploads.
+
+## Backend and caching boundaries
+
+CustomFilter, MultiPassFilter and BloomFilter are GPU effects. Canvas 2D skips
+them; it continues to approximate supported built-in effects through its existing
+CSS/pixel paths. Its filter combinations and Blur quality are not pixel-equivalent
+to WebGL.
+
+`cacheAsTexture` and `RenderTexture` still rasterize through Canvas 2D. Do not use
+them to capture or cache these GPU effects. For post-processing use filter chains
+or MultiPassFilter, which retain GPU images.
+
+## Validation
+
+Run from the repository root:
+
+```sh
+pnpm --dir packages/core build
+pnpm --dir packages/core test
+pnpm --dir packages/core test:visual
+```
+
+The browser suite includes deterministic scene screenshots and explicit pixel
+assertions on both WebGL versions, resource restoration, error recovery, filter
+ordering, masks, high-resolution inputs, large-radius blur and Bloom. It is a
+Chromium baseline, not a guarantee for every physical GPU or mobile browser.

package/docs/resource.md

@@ -0,0 +1,333 @@
+# 资源管理器 (Resource Manager)
+
+## 概述
+
+Kurot 资源管理器是从 Egret RES 模块现代化迁移而来的异步资源加载与缓存系统。它提供：
+
+- **async/await API** — 所有加载操作返回 Promise
+- **类型安全** — `ResourceType` 枚举 + 泛型 `get<T>()`
+- **配置驱动** — 兼容 Egret `resource.json` 格式
+- **按组加载** — 并发控制（默认 2 线程）、自动重试（默认 3 次）
+- **可扩展** — 自定义 Analyzer 支持新资源类型
+- **零外部依赖** — 仅依赖 core 内部的 `net/` 和 `events/`
+
+## 目录结构
+
+```
+packages/core/src/kurot/resource/
+├── index.ts              — 统一导出
+├── Resource.ts           — 资源管理器主类（单例 + 便捷实例）
+├── ResourceConfig.ts     — 配置文件解析
+├── ResourceLoader.ts     — 队列加载器（并发 + 重试）
+├── ResourceItem.ts       — 资源项定义 + ResourceType 枚举
+├── ResourceEvent.ts      — 事件类型定义
+└── analyzers/
+    ├── index.ts
+    ├── AnalyzerBase.ts   — 解析器抽象基类
+    ├── ImageAnalyzer.ts  — 图片 → Texture
+    ├── JsonAnalyzer.ts   — JSON 文件 → object
+    ├── TextAnalyzer.ts   — 纯文本 → string
+    ├── SoundAnalyzer.ts  — 音频 → HTMLAudioElement
+    └── SheetAnalyzer.ts  — 精灵表 JSON + 图片 → SpriteSheet
+```
+
+## 快速开始
+
+### 1. 准备配置文件
+
+```json
+// resource.json
+{
+	"resources": [
+		{ "name": "bg", "type": "image", "url": "assets/bg.png" },
+		{ "name": "config", "type": "json", "url": "config.json" },
+		{ "name": "hero", "type": "sheet", "url": "hero.json" }
+	],
+	"groups": [
+		{ "name": "preload", "keys": "bg,config" },
+		{ "name": "game", "keys": "hero" }
+	]
+}
+```
+
+### 2. 加载与使用
+
+```typescript
+import { resource, ResourceType } from '@kurot/core';
+
+// 加载配置
+await resource.loadConfig('resource.json', 'assets/');
+
+// 按组加载
+await resource.loadGroup('preload');
+
+// 获取缓存的资源（泛型）
+const texture = resource.get<Texture>('bg');
+
+// 异步加载单个资源
+const data = await resource.load<object>('config');
+
+// 监听加载进度
+await resource.loadGroup('game', 0, (loaded, total) => {
+	console.log(`进度: ${loaded}/${total}`);
+});
+```
+
+## API 参考
+
+### Resource 主类
+
+#### 配置
+
+| 方法                       | 说明                                               |
+| -------------------------- | -------------------------------------------------- |
+| `loadConfig(url, folder?)` | 加载并解析 resource.json，`folder` 为资源 URL 前缀 |
+| `addResource(def)`         | 动态添加资源定义 `{ name, url, type }`             |
+
+#### 加载
+
+| 方法                                      | 说明                                         |
+| ----------------------------------------- | -------------------------------------------- |
+| `loadGroup(name, priority?, onProgress?)` | 按组加载，返回 Promise。已加载的资源自动跳过 |
+| `load<T>(name)`                           | 异步加载单个资源，返回缓存数据               |
+
+#### 缓存
+
+| 方法              | 说明                                     |
+| ----------------- | ---------------------------------------- |
+| `get<T>(name)`    | 同步获取缓存资源，未加载返回 `undefined` |
+| `hasRes(name)`    | 检查资源是否已缓存                       |
+| `hasGroup(name)`  | 检查组是否存在                           |
+| `getGroupNames()` | 获取所有组名                             |
+
+#### 销毁
+
+| 方法                 | 说明                   |
+| -------------------- | ---------------------- |
+| `destroy(name)`      | 销毁单个资源，释放缓存 |
+| `destroyGroup(name)` | 销毁整组资源           |
+| `destroyAll()`       | 销毁所有已加载资源     |
+
+#### 事件
+
+| 方法                   | 说明                                   |
+| ---------------------- | -------------------------------------- |
+| `on(type, listener)`   | 监听资源事件                           |
+| `off(type, listener)`  | 移除事件监听                           |
+| `onProgress(callback)` | 便捷进度监听 `(loaded, total) => void` |
+
+#### 扩展
+
+| 方法                               | 说明                     |
+| ---------------------------------- | ------------------------ |
+| `registerAnalyzer(type, analyzer)` | 注册自定义资源类型解析器 |
+
+### ResourceType 枚举
+
+| 值        | 说明                              |
+| --------- | --------------------------------- |
+| `'image'` | 图片资源，生成 `Texture`          |
+| `'json'`  | JSON 文件，解析为 `object`        |
+| `'text'`  | 纯文本文件，返回 `string`         |
+| `'sound'` | 音频文件，返回 `HTMLAudioElement` |
+| `'sheet'` | 精灵表，返回 `SpriteSheet`        |
+
+### ResourceEventType 事件类型
+
+| 事件                | 触发时机                 |
+| ------------------- | ------------------------ |
+| `CONFIG_COMPLETE`   | 配置文件加载完成         |
+| `CONFIG_LOAD_ERROR` | 配置文件加载失败         |
+| `GROUP_COMPLETE`    | 资源组全部加载完成       |
+| `GROUP_PROGRESS`    | 资源组中单个资源加载完成 |
+| `GROUP_LOAD_ERROR`  | 资源组中有资源加载失败   |
+| `ITEM_LOAD_ERROR`   | 单个资源加载失败         |
+
+### ResourceEvent 接口
+
+```typescript
+interface ResourceEvent {
+	type: ResourceEventType;
+	groupName: string;
+	item?: ResourceItem;
+	itemsLoaded: number;
+	itemsTotal: number;
+}
+```
+
+## 内置解析器
+
+### ImageAnalyzer
+
+加载图片并创建 `Texture` 对象。销毁时自动调用 `texture.dispose()`。
+
+```typescript
+const texture = resource.get<Texture>('bg');
+// texture 可直接用于 Bitmap 显示对象
+```
+
+### JsonAnalyzer
+
+通过 `HttpRequest` 加载 JSON 文件并解析为对象。
+
+```typescript
+const config = resource.get<Record<string, unknown>>('config');
+```
+
+### TextAnalyzer
+
+通过 `HttpRequest` 加载纯文本文件。
+
+```typescript
+const text = resource.get<string>('readme');
+```
+
+### SoundAnalyzer
+
+加载音频文件，返回 `HTMLAudioElement`。销毁时自动 `pause()` 并释放 `src`。
+
+```typescript
+const audio = resource.get<HTMLAudioElement>('bgm');
+audio.play();
+```
+
+### SheetAnalyzer
+
+加载精灵表（TexturePacker JSON 格式），两步加载：
+
+1. 加载 JSON 配置获取帧信息和图片路径
+2. 加载关联图片，切割为子纹理
+
+支持三种获取方式：
+
+```typescript
+// 获取整个 SpriteSheet
+const sheet = resource.get<SpriteSheet>('hero');
+
+// 通过子键名直接获取子纹理
+const frame = resource.get<Texture>('hero_idle_01');
+
+// 通过点号语法获取
+const frame2 = resource.get<Texture>('hero.idle_01');
+```
+
+## 自定义解析器
+
+继承 `AnalyzerBase` 实现自定义资源类型：
+
+```typescript
+import { AnalyzerBase } from '@kurot/core';
+import { ResourceItem } from '@kurot/core';
+
+class XmlAnalyzer extends AnalyzerBase {
+	public loadFile(item: ResourceItem): Promise<ResourceItem> {
+		if (this.fileDic.has(item.name)) {
+			item.loaded = true;
+			return Promise.resolve(item);
+		}
+
+		return fetch(item.url)
+			.then(res => res.text())
+			.then(text => {
+				const parser = new DOMParser();
+				const doc = parser.parseFromString(text, 'text/xml');
+				this.fileDic.set(item.name, doc);
+				item.loaded = true;
+				return item;
+			})
+			.catch(() => {
+				item.loaded = false;
+				return item;
+			});
+	}
+}
+
+// 注册
+resource.registerAnalyzer('xml', new XmlAnalyzer());
+```
+
+## 队列加载器 (ResourceLoader)
+
+`ResourceLoader` 是内部使用的队列加载器，支持：
+
+- **并发控制** — `threadCount`（默认 2）限制同时加载数
+- **自动重试** — `retryCount`（默认 3）次重试后报告失败
+- **回调通知** — `onComplete` / `onError` / `onProgress`
+
+通常不需要直接使用 `ResourceLoader`，通过 `Resource.loadGroup()` 即可间接使用。
+
+## 配置文件格式
+
+### 标准格式（2.0.0）
+
+```json
+{
+	"resources": [
+		{
+			"name": "资源唯一标识",
+			"type": "image|json|text|sound|sheet",
+			"url": "相对或绝对路径",
+			"subkeys": { "frameName": { "scale9grid": "1,1,2,2" }, "ordinaryFrame": {} }
+		}
+	],
+	"groups": [
+		{
+			"name": "组名",
+			"keys": "逗号分隔的资源名称"
+		}
+	]
+}
+```
+
+当前源码的 `subkeys` 为对象，旧字符串需要在 Editor 中显式刷新图集后再使用。
+`scale9grid` 是 Image 编译默认值，Core 不会自动把它应用到任意 Bitmap。
+参见 [资源默认九宫格契约](../../ui-document/docs/resource-nine-slice.md)。
+
+### URL 解析规则
+
+- 包含 `://` 的 URL 视为绝对路径，不做处理
+- 其他 URL 会在前面拼接 `loadConfig()` 的 `folder` 参数
+
+### 动态创建组
+
+```typescript
+import { resource, ResourceConfig } from '@kurot/core';
+
+// 通过 ResourceConfig 的 createGroup 方法
+// 注意：这是底层 API，通常通过配置文件定义组
+```
+
+## 与 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** — 图片和音频加载受浏览器同源策略限制。

package/docs/text-layout.md

@@ -0,0 +1,59 @@
+# Text layout
+
+`TextField.wordWrap = true` uses Unicode 17.0 UAX #14 line-break opportunities
+from `@cto.af/linebreak`. Available width determines which opportunity is used.
+Font family, size, bold and italic are measured through the same Canvas font
+configuration used for rendering. Rich-text style boundaries do not create
+additional wrap opportunities.
+
+- Latin and Cyrillic text prefer word boundaries. CJK text observes opening
+  and closing punctuation rules rather than treating dictionary words as units.
+- Thai, Lao and Khmer add dictionary boundaries through the browser's
+  `Intl.Segmenter`. The default Unicode rules remain independently testable.
+- When an alphabetic word is wider than the entire line, emergency wrapping
+  relaxes UAX #14's alphabetic rule LB28. Non-breaking spaces, narrow
+  non-breaking spaces, word joiners and punctuation protection remain in force.
+  Protected sequences can therefore exceed the field width.
+- Ordinary spaces and tabs at a wrapped line's end are omitted from drawing
+  and width measurement. They are consumed on that line, so they never become
+  indentation on the next automatic line. Explicit indentation after a hard
+  separator is retained. Other space characters keep their Unicode behavior.
+- The source string is unchanged. Line `charNum` counts consumed UTF-16 code
+  units, including unpainted spaces and both characters of CRLF. Painting,
+  input caret and hit testing use these source offsets.
+- CRLF, CR, LF, VT, FF, NEL, line separator and paragraph separator force line
+  breaks. A trailing hard separator retains a final empty line.
+
+`wordWrap = false` retains character-based wrapping. Single-line INPUT fields
+do not wrap to available width; multiline INPUT and dynamic text do. An
+unconstrained field measures its hard-separated lines without automatic wrapping.
+
+`WordWrap.tokenize()` remains a public word-segmentation utility; it is not the
+TextField line-break algorithm. `splitGraphemes()` is likewise independent.
+
+## Validation
+
+`test/LineBreaks.test.ts` verifies all 19,338 official Unicode 17.0 line-break
+cases against the untailored profile. The compressed fixture includes its
+source URL, SHA-256 and Unicode license. Dictionary and emergency tailoring,
+multilingual width fitting, rich text, input offsets and rendering are tested
+separately in `test/TextWrapping.test.ts`.
+
+The dependency bundles its Unicode property tables and uses no network or Node
+runtime APIs. Both WebGL text rasterization and Canvas rendering share this
+layout. Core 2.0.1 is sufficient for existing UI 3.x / ui-runtime 0.7 consumers;
+no CLI XML-format change is involved.
+
+## Consumer adoption for 2.0.1
+
+UI 3.0.0, game 2.0.0 and ui-runtime 0.7.0 already declare Core `^2.0.0` in their
+peer/development ranges. Repository examples and `kurot-project-kui` use the
+same compatible range; their lockfiles need an update to pick up this fix.
+CLI templates use `latest` and do not need a range change. Editor currently
+pins the published Core 2.0.0 and builds its 0.4.6 trial with local 2.0.1 through
+`KUROT_CORE_PATH`; update that pin and lockfile after Core 2.0.1 is published.
+No dependant package is automatically bumped by this Core release preparation.
+
+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),
+[@cto.af/linebreak](https://github.com/cto-af/linebreak).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/core",
-	"version": "2.0.0",
+	"version": "2.0.1",
 	"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",
@@ -16,6 +16,7 @@
 	},
 	"files": [
 		"dist/**/*",
+		"docs/**/*",
 		"CHANGELOG.md",
 		"LICENSE"
 	],
@@ -65,5 +66,8 @@
 	"packageManager": "pnpm@10.33.0",
 	"publishConfig": {
 		"access": "public"
+	},
+	"dependencies": {
+		"@cto.af/linebreak": "4.0.3"
 	}
 }