@kurot/cli 3.6.1 → 3.8.0

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.8.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,11 +92,15 @@ 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.
 Changes are debounced and queued, with changed bytes staged before publication.
+A shallow root configuration watcher re-evaluates ESM config after stage edits
+and publishes complete HTML through an atomic rename. Invalid values retain the
+last successful page; structural build changes require restarting dev. This path
+shares the resource build queue and does not mutate the immutable Project.
 Browser refresh remains manual and HTTP responses use no-store. Individual
 renames do not form an atomic multi-file transaction. See
 [resource watching](dev-resource-watching.md).

package/docs/default-ui-skins.md

@@ -1,8 +1,6 @@
 # Default KUI skins
 
-This game-template refresh is included in published CLI 3.6.0, verified on npm
-on 2026-10-10. CLI 3.5.0 contains the older atlas. The 2× kit requires published
-Core ^2.5.0; actual published CLI scaffolding resolves that dependency.
+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,9 +81,7 @@ 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.
 
-The example now locks registry Core 2.5.4, which supports sheet density. Its
-installed CLI remains 3.3.1, so use checkout CLI 3.6.0 for the current gallery's
-constructor-name preservation. From the repository root:
+Use the checkout CLI with the example's installed SDKs. From the repository root:
 
 ```sh
 pnpm --dir packages/cli build
@@ -105,18 +97,15 @@ directory, the same CLI accepts `build` and `build --release` for one-shot build
 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 and CLI 3.6.0 are published; Core was published first.
-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
 
@@ -18,9 +17,26 @@ translations and other project-owned files.
 | PNG, fonts, language properties and other runtime files | Synchronize assets |
 | Resource directory creation, replacement or deletion | Reconnect watcher and reconcile output; compile KUI when enabled |
 | Reusable component source or skin | Retain component discovery/namespace/catalog rebuild and synchronize assets |
-
-Changes to `kurot.config.ts`, dependencies or build configuration still require
-restarting dev. Locale configuration is consumed by project code; the CLI does
+| Root kurot.config.ts or .js stage defaults | Validate and atomically regenerate HTML; refresh manually |
+
+With CLI >= 3.8.0 within 3.x, stage defaults in `kurot.config.ts` / `.js` can be
+saved without restarting `kurot dev`. `kurot build --watch` retains its existing
+source-watch behavior and does not install the configuration watcher.
+After the successful configuration update, refresh the browser manually. The
+new Player consumes HTML canvas attributes with the Core behavior described in
+[stage configuration](../../core/docs/stage-configuration.md), requiring Core
+>= 2.6.0 within 2.x; explicit runtime options still take priority.
+
+The watcher handles ordinary and atomic editor saves of the root ESM config file,
+re-evaluates it with a fresh module URL, validates width/height, scale mode,
+orientation and frame rate, and atomically replaces only the generated HTML.
+Invalid edits keep the last successful page, report an error and allow correction
+without restarting. Imported configuration helpers and dependencies are not
+reloaded; edits to them still require restarting dev.
+
+Changes outside `stage`, including entry/output/UI paths, or dependencies still
+require restarting dev. A detected structural config change reports
+`KUROT_CONFIG_RESTART_REQUIRED` and leaves the active outputs intact. Locale configuration is consumed by project code; the CLI does
 not introduce a locale parser or mutate authored skins. A style edit may change
 compiled skin assignments while its XML remains untouched.
 
@@ -53,6 +69,9 @@ A resource-only batch emits JSONL build-start with reason `resource-change`,
 followed by build-complete after synchronization. Existing `kui-change` and
 `source-change` reasons retain their meaning. Consumers should tolerate the
 additional reason and refresh only after a successful build-complete event.
+Root configuration updates emit `config-change`; failures additionally emit
+`KUROT_CONFIG_RELOAD_FAILED` or `KUROT_CONFIG_RESTART_REQUIRED` diagnostics.
+The stage watcher shares this serialized queue with resource/component work.
 
 ## Preview and atlas boundaries
 

package/docs/game-template.md

@@ -1,27 +1,11 @@
-# Project styles and languages in the game template
-
-Project-owned style/font/language initialization was introduced in CLI 3.2.1
-and remains in published CLI 3.6.0. Existing projects keep their own startup
-code and HTML; the empty template stays minimal.
-
-## Project documentation in 3.6.1
-
-CLI 3.6.1 includes a project README and short AGENTS entry in both templates.
-This version is prepared locally and has not been published.
-They identify the gameplay entry, commands, expected startup, generated files
-and task-specific guides in installed SDK packages. Read the consumer project's
-manifest, lock and installation for its actual versions. These additions are
-not in the already published CLI 3.6.0 artifact and do not rewrite existing games.
-For gameplay, the entries point to Core's game-authoring guide when installed,
-or the Star Catcher reference in an engine checkout; older packages retain their
-README/type-declaration fallback.
-
-The [standard UI guide](../../ui/docs/ui-authoring.md), bundled in UI 3.6.2, adds
-directory, TS/Skin pairing and lifecycle rules above the API reference, with a
-complete HUD recipe. The game README points at its installed copy. UI 3.6.2 and
-CLI 3.6.1 are separate packages: installing UI supplies the guides, while using
-the new CLI for create supplies template entry docs. Existing projects keep
-their own instructions and can add the links explicitly.
+# Game template startup and project services
+
+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
 
@@ -47,9 +31,17 @@ This ordering includes loading-screen Labels in the project font. The loading
 screen's startup messages stay in English because translations are not loaded yet.
 Templates do not implement live font/theme/language replacement.
 
-## HTML brand splash
+## Stage defaults
 
-This splash is included in published CLI 3.6.0; npm CLI 3.5.0 lacks it.
+Both starters use `createPlayer({ canvas })`. Configure width, height, scale mode,
+orientation and frame rate in `kurot.config.ts`; the CLI writes canvas attributes.
+This requires Core >= 2.6.0 within 2.x, documented in
+[stage configuration](../../core/docs/stage-configuration.md). Explicit options
+remain available for intentional overrides. In dev, save stage settings, wait
+for the configuration update and refresh the browser with CLI >= 3.8.0 within
+3.x; no dev restart is needed.
+
+## HTML brand splash
 
 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
@@ -67,9 +59,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">

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/cli",
-	"version": "3.6.1",
+	"version": "3.8.0",
 	"description": "Kurot CLI - build tool for Kurot Editor KUI XML workflows",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",
@@ -30,7 +30,8 @@
 	"dependencies": {
 		"@kurot/ui-document": "^0.13.0",
 		"commander": "^13.0.0",
-		"esbuild": "^0.25.0"
+		"esbuild": "^0.25.0",
+		"parse5": "^7.3.0"
 	},
 	"devDependencies": {
 		"@types/node": "^22.0.0",

package/templates/empty/README.md

@@ -33,7 +33,10 @@ browser console, resource requests and intended interactions.
 - `src/Main.ts`: creates the single Player and root Sprite; add game objects
   and input/update logic here or in application modules it imports.
 - `kurot.config.ts`: build entry, stage settings and output paths. Keep explicit
-  createPlayer options in Main consistent with the intended stage settings.
+  stage defaults here; Main uses `createPlayer({ canvas })` to consume the generated
+  canvas attributes. This requires Core >= 2.6.0 within 2.x. With CLI >= 3.8.0
+  within 3.x, save stage edits, wait for the dev update, then refresh the browser;
+  structural build changes require restarting dev.
 - `template/web/index.html`: authored HTML and canvas.
 - `bin-debug/`, `bin-release/` and `.kurot/`: generated files; edit their inputs.
 

package/templates/empty/src/Main.ts

@@ -21,12 +21,10 @@ class Main extends Sprite {
 }
 
 // ── Bootstrap ─────────────────────────────────────────────────────────────
-const app = createPlayer({
-	canvas: document.getElementById('gameCanvas') as HTMLCanvasElement,
-	contentWidth: 640,
-	contentHeight: 1136,
-	scaleMode: 'showAll',
-	frameRate: 60,
-});
+const canvas = document.getElementById('gameCanvas');
+if (!(canvas instanceof HTMLCanvasElement)) {
+	throw new Error('Missing gameCanvas.');
+}
+const app = createPlayer({ canvas });
 
 app.start(new Main());

package/templates/game/README.md

@@ -45,7 +45,10 @@ requests and the intended interactions in the browser.
   `src/components/<Name>.ts` with
   `resource/ui/components/<Name>Skin.kui.xml`; export the matching class name.
 - `kurot.config.ts`: build/stage/component settings; `template/web/index.html`:
-  authored HTML. Keep explicit createPlayer options consistent with stage intent.
+  authored HTML. Main uses `createPlayer({ canvas })` with the generated canvas
+  attributes; edit stage defaults only in config. This requires Core >= 2.6.0
+  within 2.x. With CLI >= 3.8.0 within 3.x, save stage edits, wait for the update
+  and refresh the browser; structural build changes require restarting.
 - `bin-debug/`, `bin-release/`, `.kurot/` and generated theme JSON: build outputs.
   Edit authored inputs; the CLI generates the Skin module and part declarations.
 

package/templates/game/src/Main.ts

@@ -75,7 +75,7 @@ class Main extends UILayer {
 
 	private async _loadTheme(): Promise<void> {
 		// Load the theme and its default UI skin mappings.
-		const theme = new Theme('resource/default.thm.json');
+		const theme = new Theme(new URL('resource/default.thm.json', document.baseURI).href);
 		await new Promise<void>(resolve => theme.addEventListener(Event.COMPLETE, () => resolve()));
 	}
 
@@ -181,13 +181,7 @@ async function start(): Promise<void> {
 	if (!(canvas instanceof HTMLCanvasElement)) {
 		throw new Error('Missing gameCanvas.');
 	}
-	const app = createPlayer({
-		canvas,
-		contentWidth: 640,
-		contentHeight: 1136,
-		scaleMode: 'showAll',
-		frameRate: 60,
-	});
+	const app = createPlayer({ canvas });
 	app.start(new Main());
 }