@kurot/cli 3.6.0 → 3.7.0

package/dist/core/plugins/version-assets.js

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { defaultTreeAdapter, parse } from 'parse5';
+import { BuildError } from '../errors.js';
+/**
+ * Gives every relative release URL one content-addressed base, including
+ * secondary analyzer requests, fonts and assets owned by the HTML template.
+ */
+export function versionAssets() {
+    return {
+        name: 'version release assets',
+        async apply(ctx) {
+            if (ctx.project.mode !== 'release' || !ctx.project.config.output.versionedAssets) {
+                return;
+            }
+            const outputDir = ctx.project.outputDir;
+            const htmlPath = path.join(outputDir, 'index.html');
+            const html = await fs.readFile(htmlPath, 'utf8');
+            const headEnd = validateHtml(html);
+            const version = await hashDirectory(outputDir);
+            const prefix = `assets/${version}/`;
+            const entries = await fs.readdir(outputDir);
+            const staging = await fs.mkdtemp(path.join(outputDir, '.version-assets-'));
+            try {
+                for (const entry of entries) {
+                    if (entry === 'index.html' || entry === 'manifest.json') {
+                        continue;
+                    }
+                    await fs.rename(path.join(outputDir, entry), path.join(staging, entry));
+                }
+                await fs.mkdir(path.join(outputDir, 'assets'));
+                await fs.rename(staging, path.join(outputDir, prefix));
+            }
+            finally {
+                await fs.rm(staging, { recursive: true, force: true });
+            }
+            prefixOutputs(ctx, prefix);
+            const manifest = {
+                initial: Object.values(ctx.outputs.engine),
+                game: [ctx.outputs.skinsScript, ctx.outputs.entryScript].filter(Boolean),
+            };
+            await fs.writeFile(path.join(outputDir, 'manifest.json'), JSON.stringify(manifest, undefined, '\t') + '\n');
+            await fs.writeFile(htmlPath, `${html.slice(0, headEnd)}\n\t<base href="./${prefix}">${html.slice(headEnd)}`);
+        },
+    };
+}
+function validateHtml(html) {
+    const document = parse(html, { sourceCodeLocationInfo: true });
+    const root = document.childNodes.find(defaultTreeAdapter.isElementNode);
+    const head = root?.childNodes.filter(defaultTreeAdapter.isElementNode).find(node => node.tagName === 'head');
+    // HTML parsing can imply a head; insertion requires its authored start tag.
+    const headEnd = head?.sourceCodeLocation?.startTag?.endOffset;
+    if (headEnd === undefined) {
+        throw new BuildError('output.versionedAssets requires an HTML template with a <head> element.');
+    }
+    const elements = root ? [root] : [];
+    while (elements.length > 0) {
+        const element = elements.pop();
+        if (element.tagName === 'base') {
+            throw new BuildError("output.versionedAssets owns the HTML base URL; remove the template's <base> element.");
+        }
+        elements.push(...element.childNodes.filter(defaultTreeAdapter.isElementNode));
+    }
+    return headEnd;
+}
+async function hashDirectory(root) {
+    const hash = createHash('sha256');
+    const files = await listFiles(root);
+    for (const relative of files.sort()) {
+        const file = path.join(root, relative);
+        const stat = await fs.stat(file);
+        hash.update(JSON.stringify([relative, stat.size]) + '\n');
+        for await (const chunk of createReadStream(file)) {
+            hash.update(chunk);
+        }
+    }
+    return hash.digest('hex').slice(0, 32);
+}
+async function listFiles(root, directory = '') {
+    const files = [];
+    for (const entry of await fs.readdir(path.join(root, directory), { withFileTypes: true })) {
+        const relative = path.posix.join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...(await listFiles(root, relative)));
+        }
+        else if (entry.isFile()) {
+            files.push(relative);
+        }
+        else {
+            throw new BuildError(`Versioned assets require regular files or directories: ${relative}`);
+        }
+    }
+    return files;
+}
+function prefixOutputs(ctx, prefix) {
+    if (ctx.outputs.entryScript) {
+        ctx.outputs.entryScript = prefix + ctx.outputs.entryScript;
+    }
+    if (ctx.outputs.skinsScript) {
+        ctx.outputs.skinsScript = prefix + ctx.outputs.skinsScript;
+    }
+    for (const specifier of Object.keys(ctx.outputs.engine)) {
+        ctx.outputs.engine[specifier] = prefix + ctx.outputs.engine[specifier];
+    }
+}
+//# sourceMappingURL=version-assets.js.map

package/dist/core/plugins/version-assets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-assets.js","sourceRoot":"","sources":["../../../src/core/plugins/version-assets.ts"],"names":[],"mappings":"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"}

package/docs/ai-context.md

@@ -1,14 +1,9 @@
 # @kurot/cli — AI context map
 
-CLI 3.6.0 is prepared for publication, not yet published. Latest verified npm
-release is 3.5.0. Development installs
-published ui-document 0.13.0 with a matching
-registry lockfile, without local overrides. Read
-[centered flips](../../../docs/centered-flips.md) for transform and adoption contracts.
-
-Read this before exploring `src/`. [`architecture.md`](./architecture.md)
-explains the plugin pipeline. Version `@kurot/cli@3.6.0` is pending publication, runs on Node.js 20+,
-and is installed as a project dev dependency.
+`@kurot/cli@3.7.0` is build-time tooling on Node.js >= 20, with ordinary
+ui-document dependency **^0.13.0**. Projects supply their own Core/UI runtime.
+Read [architecture](architecture.md) for the plugin pipeline; the source and
+configuration exports establish current behavior.
 
 ## Directory map
 
@@ -31,32 +26,15 @@ src/
 └── utils/
 ```
 
-Project templates are under `templates/game` and `templates/empty`.
-The CLI 3.6.0 game template's default KUI skin refresh includes 16 native Skin files,
-a Kurot-owned 2× atlas with logical resource-default nine-slice grids, and project palette
-colors replace the old EUI assets. Group/List/TabBar and text/image nodes use
-native XML composition rather than unused default Skin placeholders. See
-[default KUI skins](default-ui-skins.md). Private tools/default-ui-assets generates
-the committed assets with registry Atlas; CLI gains no atlas runtime dependency.
-The 2× sheet requires Core ^2.5.0; published Core 2.4.0
-does not interpret it. Private preview tooling binds checkout Core in an isolated
-trial. Publish Core 2.5.0 before CLI 3.6.0.
-The CLI 3.6.0 game template includes the looping mascot brand splash; registry
-CLI 3.5.0 does not contain that HTML/logo refresh. See game-template.md.
-The 3.2.1 game template includes fixed style/locale configuration,
-English properties and licensed regular/bold font files. StyleManager finishes
-font loading before Main creates Player/Preloader; LocaleManager registers
-preload texts before creating the scene. See [game-template.md](game-template.md).
-Version 3.3.0 is published with Label preset compilation and
-published ui-document 0.11.0. It has no local document-kernel override.
-Published version 3.3.1 adds whole-resource dev synchronization, deletion/reconnect
-handling and no-store responses. Installed CLI 3.3.0 lacks these fixes; consumers
-must update their installed/locked version to receive them.
-
-## Native text adoption in 3.4.0
-
-Version 3.4.0 registers BitmapLabel and RichLabel from published UI
-3.3.0 and consumes document 0.12.0. `kui/validate-text-components.ts` applies
+Project templates are under `templates/game` and `templates/empty`, including
+README/AGENTS entries for installed SDK guides and project commands. The game
+template supplies paired KUI/TS components, default skins, a 2× atlas, palette,
+fonts, translations and splash HTML. See [template startup](game-template.md)
+and [default skins](default-ui-skins.md).
+
+## Native text compilation
+
+The compiler registers BitmapLabel and RichLabel through ui-document. `kui/validate-text-components.ts` applies
 strict shared property/state validation only to these new built-ins, preserving
 existing CLI-only and custom class contracts. Text flows remain literal arrays;
 Span data does not create nodes/parts. Only width/height use percent conversion.
@@ -78,11 +56,11 @@ transforms such as `flipX`/`flipY` belong on those children. Overrides use local
 `property.state` attributes. Storage IDs and runtime mapping metadata are not
 authored XML fields.
 
-CLI 3.5.0 validates centered-flip booleans on display nodes and named-state
+The compiler validates centered-flip booleans on display nodes and named-state
 overrides, including CLI-only controls. Malformed values and flags on the
 nonvisual Skin root fail compilation. Negative scales are preserved.
 
-CLI 3.6.0 requires `@kurot/ui-document@^0.13.0`. Schema-defined strings, including
+The CLI requires `@kurot/ui-document@^0.13.0`. Schema-defined strings, including
 numeric/boolean-looking text and state text, are literal attributes without
 backslash type escaping. Old synthetic prefixes become literal characters;
 do not migrate them silently. Numeric/boolean properties and schema-free
@@ -105,6 +83,10 @@ as the part name. Internal nodes can omit `id`; the declaration augments
 component classes. The file is development metadata and is excluded from
 runtime output.
 
+The generator narrows host `skinParts` through a getter signature,
+preserving Component's accessor kind under `skipLibCheck=false`. Regenerate after
+authored Skin changes; keep generated declarations out of manual edits.
+
 ## Reusable components
 
 With `ui.components`, `<Name>.ts` under `sourceDir` pairs with
@@ -125,7 +107,7 @@ manual prefix cannot conflict with `ui.components.namespace`.
   `--strict` or release policy.
 - Machine diagnostic modes own stdout: build emits one JSON result; dev emits
   JSONL lifecycle events.
-- Since 3.3.1, dev watches all resource assets even without UI, emits
+- Dev watches all resource assets even without UI, emits
   resource-change for copy-only batches, retains KUI requirements across mixed
   batches, and reconciles deletions. Browser refresh remains manual; HTTP is
   no-store. Per-file staging/rename is not an atomic atlas pair transaction.
@@ -136,9 +118,8 @@ manual prefix cannot conflict with `ui.components.namespace`.
 - Engine and custom namespace chunks share `ctx.outputs.engine` because the
   import-map writer treats both as external specifier mappings.
 - Engine and reusable namespace bundles preserve class names in both modes.
-  The CLI 3.6.0 development fix also protects self-referencing classes, which
-  esbuild can rename without minification. Registry CLI 3.5.0 protects release
-  names only. Theme fallback uses constructor names.
+  Self-referencing classes retain stable names in both modes because Theme
+  fallback uses constructor names.
 - The Skin module builder stages output in a temporary directory and installs a
   bundle only after every Skin succeeds.
 - `cleanOutput` wipes the active output directory at the start of each build.
@@ -146,11 +127,10 @@ manual prefix cannot conflict with `ui.components.namespace`.
 - `create` queries the npm registry for current Kurot package versions and falls
   back to `latest` if the request fails.
 - Release output is timestamped and `manifest.json` exists only in release.
-- The CLI 3.6.0 asset-copy correction omits empty runtime directory trees,
+- Asset copying omits empty runtime directory trees,
   including skin-only `resource/ui`. Runtime files under UI directories remain
   eligible; generated theme JSON and the compiled Skin module remain required.
-  Template copies still preserve empty directories. Registry CLI 3.5.0 does not
-  include this correction.
+  Template copies still preserve empty directories.
 
 ## Plugin order
 
@@ -164,11 +144,19 @@ manual prefix cannot conflict with `ui.components.namespace`.
 6. compile application source;
 7. generate HTML;
 8. write the release manifest;
-9. copy runtime assets.
+9. copy runtime assets;
+10. optionally version release assets with `output.versionedAssets`.
 
 Do not reorder namespace or source compilation without reviewing externalization
 in `namespace-external-plugin.ts`.
 
+Release versioning runs last so the digest covers generated themes, scripts,
+resource bytes and template assets. It keeps index.html/manifest.json at the
+output root and moves all other files under assets/<hash>/. The HTML base URL
+versions document-relative requests; callers that explicitly resolve URLs must
+use document.baseURI. Existing UI Theme must receive an absolute config URL.
+See [release assets](release-assets.md). This option requires CLI >= 3.7.0 within 3.x.
+
 ## Configuration lookup
 
 | Task                             | File                                                                |
@@ -198,14 +186,14 @@ pnpm test
 CLI end-to-end tests bind localhost and may require permission in a restricted
 execution environment.
 
-## Resource configuration change in 3.0.0
+## Resource configuration
 
 KUI builds validate object subkeys, resolve resource nine-slice defaults, and
 watch the manifest during development. See
 [the resource-default contract](../../ui-document/docs/resource-nine-slice.md)
 for conversion and compilation boundaries.
 
-## Label text compilation in 3.1.0
+## Label text compilation
 
 The compiler consumes the shared ui-document catalog and emits Label `textFit`,
 `minFontSize`, authored `size` and state-size overrides unchanged. Runtime
@@ -215,7 +203,7 @@ within their respective majors. Neither engine is a CLI runtime dependency.
 See [text compilation](label-text-layout.md) and
 [native Label text layout](../../ui/docs/label-text-layout.md) for the boundary.
 
-## Project styles in 3.2.0
+## Project styles
 
 Read [project styles](../../ui-document/docs/project-styles.md). buildSkinsModule
 reads the optional fixed config/style.json once per build and forwards its numeric
@@ -226,13 +214,11 @@ without migrating files. Fonts are validated but not loaded; the application own
 font loading and rendering. Build/preview copies resolve references while authored
 XML retains them. No live runtime palette switching is introduced.
 
-## Label presets in 3.3.0
+## Label presets
 
 skin-module-builder.ts reads the entire stylesheet once per build and passes it
 through parseToIR/parseKUISkin. Resolve resource defaults, then Label presets, then colors before
 native emission; retain XML references and local/state precedence. compileKUI
 accepts an optional styleSheet. style.json changes already trigger whole-Skin
-rebuilds. Invalid presets retain the last successful bundle. The 3.3.0 dependency and
-lockfile used published ui-document 0.11.0 without a local override. Current
-CLI 3.5.0 development uses published ui-document 0.13.0. textStyle is
+rebuilds. Invalid presets retain the last successful bundle. textStyle is
 Default-only; individual named-state fields can still override preset properties.

package/docs/architecture.md

@@ -18,6 +18,7 @@ clean output
   → generate HTML
   → write release manifest
   → copy runtime assets
+  → optionally version release assets
 ```
 
 KUI compilation runs first because skin factories can import project namespace
@@ -39,7 +40,7 @@ factory variables, property assignments, semantic layout children, and state
 property overrides. Document contracts, reusable instances, data bindings, and
 actions remain `UIDocument` concepts.
 
-CLI 3.6.0 consumes ui-document ^0.13.0, retaining Label text-fitting metadata. The
+CLI 3.7.0 consumes ui-document ^0.13.0, retaining Label text-fitting metadata. The
 compiler emits `textFit`, `minFontSize`, base font sizes and state overrides;
 native UI owns measurement and derives drawing sizes after layout validation.
 See [Label compilation](label-text-layout.md). The application supplies UI
@@ -71,6 +72,13 @@ Development builds preserve application source module structure under
 `manifest.json`. Static resources retain stable paths because application code
 addresses them by key or URL.
 
+With `output.versionedAssets: true`, the final stage hashes the complete output
+and moves runtime files into `assets/<hash>/`. The entry HTML receives a base URL;
+the root release manifest and BuildContext script paths receive the same prefix.
+Relative references inside resources and ESM modules remain intact. This is one
+version for the complete build, rather than independent hashes per resource.
+See [release deployment](release-assets.md) for URL and hosting requirements.
+
 Asset copying creates directories only when an accepted runtime file needs them.
 KUI source files and source theme JSON are excluded when UI compilation is enabled,
 so a skin-only `resource/ui` tree is absent from output. Mixed directories retain
@@ -84,7 +92,7 @@ convention-based reusable components. A component change can affect its source
 namespace, paired skin, generated type declaration, and editor catalog, so that
 path refreshes all four outputs as one operation. The server preserves the last
 successful output after an invalid edit.
-Since 3.3.1, the resource watcher synchronizes all runtime assets even without UI,
+The resource watcher synchronizes all runtime assets even without UI,
 and reconciles additions, deletions and directory replacement. Runtime-only
 changes do not recompile skins. The fixed style.json and default.res.json paths
 still trigger KUI compilation; font loading remains an application responsibility.

package/docs/default-ui-skins.md

@@ -1,8 +1,6 @@
 # Default KUI skins
 
-This game-template refresh is included in CLI 3.6.0, pending publication.
-Registry CLI 3.5.0 contains the older atlas. The 2× kit requires Core ^2.5.0;
-publish Core 2.5.0 before CLI 3.6.0.
+The 2× atlas needs Core >= 2.5.0 within 2.x for source-density metadata.
 The template owns the XML, textures and project colors; `@kurot/ui`
 does not ship a bitmap theme or load a stylesheet itself.
 
@@ -30,14 +28,12 @@ to draw the components, and no runtime light/dark switching is introduced.
 ## Text and spacing
 
 Single-line captions use `multiline="false" verticalAlign="middle"` with the
-Core 2.5.0 ink-centering correction. Button label padding is 10 pixels
+native dynamic-text ink centering. Button label padding is 10 pixels
 above/below; its down state uses 12/8 to retain a deliberate 2-pixel press offset.
 The icon has the same neutral/down centers. Panel titles also opt into middle
 alignment. Input text retains Core's stable font baseline while its placeholder
 uses dynamic visual centering. No language-specific skin offsets are required.
-See [Core text alignment](../../core/docs/text-layout.md#visual-centering-and-stable-baselines-core-250).
-Published Core 2.4.0 does not contain that correction; the isolated preview uses
-checkout Core for both text alignment and source density.
+See [Core text alignment](../../core/docs/text-layout.md#baselines-and-cached-metrics).
 
 ## Resources and XML
 
@@ -72,13 +68,11 @@ automatic scrolling policies and touch/trackpad scrolling. To display bars in a
 project, edit those parts explicitly.
 
 ItemRenderer backgrounds fit the allocated row width without extra horizontal
-padding. The checkout Core also fixes fractional WebGL scissor bounds so scaled
-Lists retain their right outline. Published Core 2.4.0 lacks that correction;
-shrinking the skin or changing its nine-slice grid is not required.
+padding. Core encloses fractional WebGL scissor bounds so scaled Lists retain their
+right outline; use the allocated row geometry without compensating skin offsets.
 
 Group, List, TabBar, ViewStack and text/image nodes are composed directly in XML;
-their old default-Skin placeholders were not conventional Theme mappings and
-are removed. Use `itemRendererSkinName` to choose a List/TabBar row appearance,
+they do not require placeholder default skins. Use `itemRendererSkinName` to choose a List/TabBar row appearance,
 and wrap the node with Group/Image/Scroller for its surface and viewport.
 
 ## Native preview and maintenance
@@ -87,37 +81,31 @@ and wrap the node with Group/Image/Scroller for its surface and viewport.
 `src/DefaultUI.ts` only connects data and events. The example installs its own
 project font loader and document dependency; other projects are unchanged.
 
-Core 2.5.0 is published. Until the example adopts it, build Core/CLI for an isolated
-source trial. The example's registry lock does not yet contain density support:
+Use the checkout CLI with the example's installed SDKs. From the repository root:
 
 ```sh
-pnpm --dir packages/core build
 pnpm --dir packages/cli build
-pnpm --dir tools/default-ui-assets preview
+cd examples/game
+node ../../packages/cli/dist/index.js dev
 ```
 
-The preview tool prints a new directory under docs-internal, with strict dev
-and minified release builds. It links the built checkout Core and the example's
-installed UI/Game/document packages; it does not edit application installations
-or locks. Run the repository CLI dev command in that printed directory and open
-the server URL with `?ui=1`. The ordinary game remains available without
+Open the server URL with `?ui=1`; the ordinary scene remains available without
 that parameter. Try the inputs, switches, ComboBox, tabs, sliders, panel close
-button and draggable List. The gallery is rendered by Core/UI from compiled
-KUI XML. After explicitly installing the Core 2.5.0 release in the
-example, ordinary repository-CLI builds can run directly from examples/game.
+button and draggable List. The gallery uses the example's installed Core/UI
+with compiled KUI XML, without modifying dependencies or locks. In that example
+directory, the same CLI accepts `build` and `build --release` for one-shot builds.
+The private asset tool's isolated source preview remains an optional maintenance
+tool for testing checkout engine changes; it is not required by the installed Core.
 
-CLI 3.6.0 preserves constructor names in development and release
+The CLI preserves constructor names in development and release
 engine/namespace bundles so Theme lookup also works for self-referencing
-classes such as Scroller. Published CLI 3.5.0 lacks the development correction.
+classes such as Scroller.
 
 `tools/default-ui-assets` contains editable SVG geometry and the reproducible
 PNG/atlas generator. It uses registry `@kurot/atlas@0.1.0` only as private
 repository tooling. CLI and runtime SDKs gain no atlas dependency. See its
 [maintenance instructions](../../../tools/default-ui-assets/README.md).
 
-Core 2.5.0 must be published before CLI 3.6.0.
-UI/Game/document/runtime need no incidental release; existing 1× consumers keep
-their behavior. See [density units and adoption](../../core/docs/texture-density.md).
-Existing projects keep their own skins, resource keys and startup code. New
-scaffolds receive this kit after the supporting Core and CLI publications;
-installing a new CLI does not rewrite an existing project's resources.
+Existing projects keep their own skins, resource keys and startup code. Updating
+the installed CLI does not rewrite authored resources. New scaffolds receive
+the template's current kit.

package/docs/dev-resource-watching.md

@@ -1,8 +1,7 @@
 # Development resource watching
 
-Available in published CLI 3.3.1. No configuration or
-dependency-range changes are required. Projects must install the new CLI to
-receive these behaviors; installed CLI 3.3.0 does not include them.
+`kurot dev` synchronizes runtime assets without additional watcher configuration.
+Browser refresh remains manual.
 
 ## Inputs and rebuilds
 

package/docs/game-template.md

@@ -1,8 +1,11 @@
-# Project styles and languages in the game template
+# Game template startup and project services
 
-Project-owned style/font/language initialization was introduced in CLI 3.2.1
-and remains in CLI 3.6.0 (pending publication). Existing projects keep their own startup
-code and HTML; the empty template stays minimal.
+The game template owns its style/font/language initialization, HTML, README and
+AGENTS entry. The empty template stays Core-only. New scaffolds receive these
+files; existing projects keep their own authored resources and instructions.
+For UI organization and component/Skin pairing use
+[standard authoring](../../ui/docs/ui-authoring.md) and the
+[ScoreHUD recipe](../../ui/docs/recipes/score-hud.md).
 
 ## Files
 
@@ -30,8 +33,6 @@ Templates do not implement live font/theme/language replacement.
 
 ## HTML brand splash
 
-This splash is included in CLI 3.6.0, pending publication; npm CLI 3.5.0 lacks it.
-
 The game template's `web/index.html` presents `web/logo.png` beneath a small
 "Made with" caption. The mascot makes a gentle entrance, then repeats a playful
 hop and sway every 3.2 seconds while the entry module loads. Sparkles and a soft
@@ -48,9 +49,8 @@ existing project HTML is project-owned.
 
 ## Change fonts and colors
 
-The CLI 3.6.0 [default KUI skins](default-ui-skins.md) use Kurot-owned textures
-under resource/assets/ui/kui and a matching color palette. Registry CLI 3.5.0
-does not include this skin refresh. Skin state text colors compile from the
+The [default KUI skins](default-ui-skins.md) use Kurot-owned textures under
+resource/assets/ui/kui and a matching color palette. Skin state text colors compile from the
 project stylesheet; texture colors are baked into the PNG, without live palette
 switching. Templates inherit project fonts and retain the existing licensed files.
 

package/docs/label-text-layout.md

@@ -1,6 +1,6 @@
 # Label text compilation
 
-CLI 3.6.0 consumes ui-document ^0.13.0 and compiles KUI text-fitting properties
+The CLI consumes ui-document ^0.13.0 and compiles KUI text-fitting properties
 through the existing UIDocument → SkinIR → ESM factory pipeline. The semantic
 document format remains version 2.
 
@@ -34,12 +34,10 @@ introduces build-time text measurement. See the
 
 ## Runtime boundary
 
-- The application must install UI `^3.1.0` and Core `^2.1.0` for shrinking.
-  These are the feature's original API minimums. Installing current UI 3.4.0
-  requires Core `^2.4.0` for that package's centered-flip contract.
-  They remain application dependencies; CLI depends on the headless document
-  package rather than importing the engine into the build process.
-- `textFit` is `none` by default or `shrink` for ordinary single-line Labels.
+- Applications supply an accepted Core/UI pair and satisfy the installed UI's
+  Core peer. The compiler depends on the headless document kernel.
+- `textFit` is `none` by default or `shrink` for ordinary Labels.
+  Supported fitting modes and bounds follow the installed native UI contract.
   Put a Button's policy on its `labelDisplay` skin part.
 - `minFontSize` defaults to 12 logical pixels and must be finite and >= 1.
   A minimum greater than the authored size does not enlarge the text.
@@ -47,20 +45,20 @@ introduces build-time text measurement. See the
   State removal restores the authored base size before fitting again.
 - `renderedSize` and `textFitOverflow` are runtime observations; do not author
   them in KUI XML.
-- Multiline Labels keep their base size; EditableText rejects shrinking.
+- EditableText rejects shrinking. Current native Label supports fitting in either
+  line mode; `multiline` continues to choose line generation.
 - Load fonts before measuring text. For late loading, native UI callers use
   `label.invalidateSize()` after the font becomes ready.
 
-UI 3.1's public Label contract owns the full fitting, overflow, layout and
-font-readiness rules. ui-document 0.9's catalog describes the authoring fields.
-The build does not rewrite existing skins or apply project translation rules.
+The [native Label contract](../../ui/docs/label-text-layout.md) owns fitting,
+overflow, layout and font-readiness rules. The compiler does not rewrite
+existing skins or apply project translation rules.
 
-## Migration
+## Authored line policy
 
-In Core 2.1.0, explicit `multiline="false"` means one unwrapped first line.
+Explicit `multiline="false"` means one unwrapped first line.
 Remove that flag or set it to true where wrapping is intended. The literal-string
 XML contract is retained: a backslash followed by `n` stays literal text rather
 than becoming a hard separator.
 
-Existing EXML projects remain on CLI 1.3.x. The KUI release does not introduce
-an EXML migration or resource-format change.
+EXML authoring uses the CLI 1.x line. This KUI compiler does not migrate EXML.

package/docs/release-assets.md

@@ -0,0 +1,76 @@
+# Versioned release assets
+
+Enable content-addressed release packaging in `kurot.config.ts`:
+
+```ts
+export default {
+	output: { dir: 'bin-debug', versionedAssets: true },
+	// Keep the project's other settings.
+};
+```
+
+The option requires CLI >= 3.7.0 within 3.x. It defaults to false and is ignored
+by development/watch builds.
+An index query string does not propagate to requests for resources.
+
+## Output and URLs
+
+```text
+bin-release/web/<timestamp>/
+├── index.html
+├── manifest.json
+└── assets/<hash>/
+    ├── js/
+    ├── resource/
+    └── <files copied beside the HTML template>
+```
+
+The hash is the first 32 hexadecimal characters of SHA-256 over sorted output
+paths, file sizes and bytes, including generated HTML, theme JSON and scripts.
+Any changed file changes the complete build's version. Identical builds retain
+their URL; unchanged individual files also get new URLs when another file changes.
+This trades granular cache reuse for one consistent release across all loaders.
+
+The CLI inserts `<base href="./assets/<hash>/">` first inside `<head>`. A request
+for `resource/assets/atlas.png` then resolves under the version directory, even
+when the entry is `/game/index.html?launch=...`. Atlas `file` references, bitmap
+font pages, stylesheet fonts, relative imports and direct browser requests use
+that directory without rewriting authored resources or keys. The release manifest
+stays at the root with prefixed script paths. Source maps move with their scripts.
+
+Custom templates must have an explicit `<head>` and no `<base>` element. The
+CLI inserts the base at the parsed start tag's source location without
+reserializing the template. Quoted attributes and script/style text are preserved.
+The build rejects symbolic links and other nonregular output files. Relative URLs
+must refer to files inside the build; root-relative URLs, remote URLs, and URLs
+explicitly based on location.href remain outside this mechanism. Applications
+that construct URLs should use document.baseURI for build assets. Relative links
+and forms also inherit the base; use explicit destinations for application navigation.
+If hosting has a CSP base-uri directive, it must allow this same-origin base.
+
+## Theme loading with existing UI
+
+UI runtimes that resolve a relative Theme config against location.href need an
+absolute config URL. The game starter uses:
+
+```ts
+const theme = new Theme(new URL('resource/default.thm.json', document.baseURI).href);
+```
+
+Use the same pattern in existing projects. This keeps the theme's `skinsJs`
+import inside the version directory without requiring a UI runtime update.
+
+## Deployment
+
+Upload the complete generated directory, including `assets/<hash>/`. Upload new
+asset directories first, then replace root manifest.json and index.html. Keep
+previous version directories available while older sessions may request assets;
+avoid deploy commands that delete those directories immediately. Publish the
+entry at a directory URL ending in `/` or at its actual `index.html` URL.
+
+Serve index.html with revalidation, for example `Cache-Control: no-cache`.
+Serve `assets/<hash>/**` with `Cache-Control: public, max-age=31536000, immutable`.
+If a launcher reads root manifest.json, give it revalidation too. These are server
+settings; the CLI writes static files and cannot set response headers. Never
+overwrite files inside an already published hash directory. Rollback replaces
+the root entry files with those of the previous complete release.

package/docs/text-components.md

@@ -1,12 +1,8 @@
 # BitmapLabel and RichLabel compilation
 
-Native text compilation was introduced in CLI 3.4.0 with document 0.12.0.
-Current CLI 3.6.0 requires published ui-document ^0.13.0 and retains these tags.
-Applications rendering these tags
-must install UI `^3.3.0` and Core `^2.3.0`; Core 2.3.1 fixes unstyled blank
-rich-text line metrics. The CLI does not install or bundle its own Core/UI.
-Document format version 2 and existing project configuration are unchanged.
-Installing UI 3.4.0 requires Core ^2.4.0 for that package's centered-flip contract.
+The compiler registers native text types through ui-document and generates Skin
+factories. Applications supply an accepted Core/UI pair; the CLI does not bundle
+its own engine. Semantic document format is 2.
 
 ```xml
 <Skin xmlns="https://kurot.dev/ui/1" class="TextSkin" states="disabled">