@kurot/cli 3.5.0 → 3.6.1

package/docs/architecture.md

@@ -39,7 +39,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.4.0 consumes ui-document 0.12.x, retaining Label text-fitting metadata. The
+CLI 3.6.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 +71,12 @@ Development builds preserve application source module structure under
 `manifest.json`. Static resources retain stable paths because application code
 addresses them by key or URL.
 
+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
+their runtime images/JSON and generated theme output is preserved. Template
+scaffolding keeps its separate empty-directory behavior.
+
 ## Development watchers
 
 The dev server has separate rebuild paths for application source, KUI XML, and

package/docs/default-ui-skins.md

@@ -0,0 +1,122 @@
+# 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 template owns the XML, textures and project colors; `@kurot/ui`
+does not ship a bitmap theme or load a stylesheet itself.
+
+## Visual language
+
+Rounded corners, bright blue actions, pale neutral surfaces and a small pressed
+button offset echo the Kurot mascot. The default is a light game interface:
+
+| Role | Value |
+| --- | --- |
+| Action / selected outline | `#1487E8` |
+| Action text / marks | `#071D30` |
+| Canvas / panel | `#EDF3FC` / `#FFFFFF` |
+| Input / neutral control | `#F1F5FC` |
+| Text / secondary text | `#18273E` / `#64748B` |
+| Disabled text | `#7C8799` |
+| Button / input minimum height | 48 logical pixels |
+| CheckBox / RadioButton / switch / slider minimum hit height | 44 logical pixels |
+
+Buttons use 14-pixel corner radii and panels use 22. XML single-line labels
+shrink within their allocated width, to a minimum of 14; editable text stays at
+18. Fonts inherit the application's configured family. No browser CSS is used
+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
+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.
+
+## Resources and XML
+
+- `resource/assets/ui/kui/kui.json` and `kui.png`: Kurot-owned 512×512 atlas,
+  generated at 2× with sheet `resolution: 2`. XML dimensions stay logical.
+- `resource/default.res.json`: preload group `kui` and object-valued frame
+  metadata. Qualified sources such as `kui.button_up` avoid bare-key collisions.
+- `resource/ui/skins/*.kui.xml`: 15 native default component skins and
+  `CloseButtonSkin`, used explicitly by Panel's `closeButton`.
+- `resource/config/style.json`: named colors used by Label/EditableText state
+  properties. Raster colors are baked into textures; changing text colors alone
+  does not recolor the atlas.
+
+Buttons provide up/down/disabled surfaces. CheckBox, RadioButton, ToggleButton
+and ToggleSwitch cover all six selected/pressed/disabled combinations.
+ItemRenderer supplies selected states for List and TabBar; ComboBox supplies
+normal/open/disabled states and TextInput handles both prompt states when
+enabled or disabled. Sliders supply a disabled thumb. Panel retains its drag
+area, title and close button.
+
+Skin part names and the native component APIs stay unchanged. The CLI compiles
+source changes with a paired nine-slice grid from resource metadata, including
+state transitions. Frames retain their full physical dimensions and never rotate
+or trim; extrusion stays outside the recorded frame. Core divides original frame
+dimensions/trim offsets by density; grids remain logical. Stretchable surfaces keep
+their corners while the interior expands. Icons and switch handles remain fixed
+size. Horizontal and vertical slider tracks have grids that fit their 8-pixel
+thickness.
+
+Scroller keeps `autoVisibility="false" visible="false"` on both bars. It retains
+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.
+
+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,
+and wrap the node with Group/Image/Scroller for its surface and viewport.
+
+## Native preview and maintenance
+
+`examples/game/resource/ui/DefaultUISkin.kui.xml` contains the native gallery.
+`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:
+
+```sh
+pnpm --dir packages/cli build
+cd examples/game
+node ../../packages/cli/dist/index.js dev
+```
+
+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 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
+engine/namespace bundles so Theme lookup also works for self-referencing
+classes such as Scroller. Published CLI 3.5.0 lacks the development correction.
+
+`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.

package/docs/game-template.md

@@ -1,12 +1,31 @@
 # Project styles and languages in the game template
 
-CLI 3.2.1 is published with this template update. It adds
-project-owned initialization without changing Core/UI APIs or migrating existing
-projects. The empty template stays minimal.
+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.
 
 ## Files
 
-- resource/config/style.json declares the primary font role and disabled-text color.
+- resource/config/style.json declares the primary font role and skin text colors.
 - resource/assets/fonts contains unmodified Chakra Petch regular (400) and bold (700)
   files, with OFL.txt. Source: [Google Fonts](https://github.com/google/fonts/tree/main/ofl/chakrapetch).
 - resource/config/locale.json enables English and selects en_US by default.
@@ -28,8 +47,32 @@ 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
+
+This splash is included in published CLI 3.6.0; 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
+blue glow follow the loop. The splash has no loading text or progress indicator;
+the application's Preloader owns resource progress. Animations stop when the
+browser requests reduced motion. The logo size follows both viewport width and
+height for small screens and landscape.
+
+The HTML overlay fades out after the entry module evaluates, without a minimum
+display time or a wait for the entrance animation to finish. It does not wait
+for project font or resource loading. Customize the branding directly in the
+project's HTML. This template update applies to newly scaffolded game projects;
+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
+project stylesheet; texture colors are baked into the PNG, without live palette
+switching. Templates inherit project fonts and retain the existing licensed files.
+
 Font keys such as primary produce stable aliases such as kurot-primary. Replace
 files and update style.json resource-relative paths, retaining weight 400 and
 unique weights. Default skins inherit the configured font; explicit Label fontFamily

package/docs/label-text-layout.md

@@ -1,6 +1,6 @@
 # Label text compilation
 
-CLI 3.4.0 consumes ui-document 0.12.x and compiles KUI text-fitting properties
+CLI 3.6.0 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.
 
@@ -35,6 +35,8 @@ 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.

package/docs/text-components.md

@@ -1,9 +1,12 @@
 # BitmapLabel and RichLabel compilation
 
-CLI 3.4.0 uses published ui-document 0.12.0. Applications rendering these tags
+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.
 
 ```xml
 <Skin xmlns="https://kurot.dev/ui/1" class="TextSkin" states="disabled">

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/cli",
-	"version": "3.5.0",
+	"version": "3.6.1",
 	"description": "Kurot CLI - build tool for Kurot Editor KUI XML workflows",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",

package/templates/empty/AGENTS.md

@@ -0,0 +1,25 @@
+# Game project agent entry
+
+Read [README.md](README.md) for commands, expected startup and project paths.
+For a complete game flow, follow its game-authoring/Star Catcher route when available.
+Use package.json, the lock and `pnpm list --depth 0` for the actual SDK baseline.
+
+- Start gameplay changes in `src/Main.ts` or the modules it imports. This is a
+  Core-only consumer project; engine internals are outside its normal scope.
+- Read installed Core's README first. For the API being changed, consult its
+  public `dist/index.d.ts`/re-exported types and the relevant installed guide.
+  When available, `docs/api/topics.md` routes to individual symbol/member pages.
+  The README links resources, audio and CLI usage; load other docs on demand.
+  When an older install lacks a guide, use its README/types before versioned
+  source. Engine-repository source paths may be absent from node_modules.
+- Use TypeScript, ESM and the project's strict settings. Use named exports,
+  explicit exported-function return types and `undefined` for missing values.
+  Use the installed public API and preserve the project's dependency baseline.
+- Keep one Player. Display/input coordinates are logical units. Retain listener
+  and tick callback identities so application cleanup can unregister them.
+  `app.stop()` stops this Player's rendering; manage gameplay activity separately.
+- Edit source/config/resource inputs; output directories and `.kurot/` are
+  generated. Read the authored HTML path from kurot.config.ts.
+- Before finishing, run `pnpm build` and check the browser console and intended
+  behavior. Run `pnpm release` when changing release behavior. Report executed
+  checks and any unverified behavior; build success alone is not gameplay proof.

package/templates/empty/README.md

@@ -0,0 +1,60 @@
+# Kurot empty project
+
+A minimal Core-only application. The initial canvas is blank; the browser
+console prints `Kurot game started`. Add your gameplay in `src/Main.ts`.
+
+## Run and build
+
+Use Node.js 20+ and pnpm from this project directory:
+
+```sh
+pnpm install
+pnpm dev
+```
+
+Open the URL printed by the server (default `http://localhost:3000`). Refresh
+the browser manually after a successful rebuild.
+
+```sh
+pnpm build
+pnpm release
+```
+
+Development output is `bin-debug/`; release output is
+`bin-release/web/<timestamp>/`. Serve the generated directory over HTTP for
+browser checks. `pnpm clean` removes both output trees.
+
+The CLI transpiles with esbuild; a successful build does not establish complete
+TypeScript type correctness or gameplay behavior. After changes, check the
+browser console, resource requests and intended interactions.
+
+## Project map
+
+- `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.
+- `template/web/index.html`: authored HTML and canvas.
+- `bin-debug/`, `bin-release/` and `.kurot/`: generated files; edit their inputs.
+
+## Read only what the task needs
+
+For gameplay, read Core's `docs/game-authoring.md` when the installed package
+includes it. In an engine checkout, that guide links `examples/star-catcher`,
+a complete game with `pnpm check`. The guide ships since Core 2.5.5; Star Catcher
+is repository content. Older installations can use their README/types instead.
+
+After installation, start with [Core usage](node_modules/@kurot/core/README.md).
+Use [resources](node_modules/@kurot/core/docs/resource.md),
+[audio](node_modules/@kurot/core/docs/audio-playback.md) or
+[CLI commands](node_modules/@kurot/cli/README.md) when relevant. These links are
+project-relative and become available after installation.
+
+Read `package.json`, `pnpm-lock.yaml` and `pnpm list --depth 0` for the declared,
+locked and installed versions. Public signatures are in each installed package's
+`dist/index.d.ts` and re-exported declarations. For an older package lacking a
+linked guide, use that installed version's README/types, then its exact version
+source if needed. Repository `src/` paths are not guaranteed inside npm packages.
+
+The project starts with Core only. Add further SDKs explicitly when gameplay
+requires them; keep dependency adoption separate from ordinary feature work.

package/templates/game/AGENTS.md

@@ -0,0 +1,30 @@
+# Game project agent entry
+
+Read [README.md](README.md) for commands, project paths and installed-doc links.
+For a complete game flow, follow its game-authoring/Star Catcher route when available.
+Check package.json, the lock and `pnpm list --depth 0` for the actual SDK baseline.
+
+- Start gameplay in `src/Main.ts` or its application modules. Consult startup
+  services only when changing fonts, resources, translations or lifecycle.
+  Preserve the startup order documented in README.
+- For UI, follow README's installed UI authoring/ScoreHUD route (UI >= 3.6.2). Pair discovered component
+  TS and Skin XML at matching relative paths; keep helpers outside the scanned
+  components directory. Edit appearance in XML and game decisions in controllers.
+- Read the relevant installed Core/Game/UI/CLI README and public declarations
+  before adding APIs. When installed, `docs/api/topics.md` routes to individual
+  symbol/member pages; read only those needed. Published Game 2.0.0 has no
+  docs/; use its README/types, then versioned source if needed. Source paths in
+  engine context maps may be absent from installed packages.
+- Use TypeScript, ESM and strict settings, named exports, explicit exported
+  function return types and `undefined` for missing values. Use public APIs
+  from the installed versions; keep dependency adoption explicit.
+- Keep one Player and use logical display/input coordinates. Manage cleanup
+  for gameplay ticks, listeners, timers, tweens and sound channels on restart
+  and exit. `app.stop()` stops rendering; it does not pause all gameplay work.
+- Edit source, KUI XML, manifests and project configuration. Build outputs,
+  generated theme JSON and `.kurot/` declarations come from those inputs.
+- Finish with `pnpm build`, `pnpm exec tsc --noEmit --skipLibCheck false`
+  (CLI >= 3.6.1) and browser checks for startup, resources and changed
+  interactions. Check restart/cleanup when affected and `pnpm release` for
+  release changes. Report checks actually run and remaining verification limits;
+  esbuild success alone is not type checking or proof of playability.

package/templates/game/README.md

@@ -0,0 +1,90 @@
+# Kurot game project
+
+This starter demonstrates resource loading, styled KUI controls, translations
+and Tween animation. Extend `src/Main.ts` with your game's rules and interaction.
+
+## Run and build
+
+Use Node.js 20+ and pnpm from this project directory:
+
+```sh
+pnpm install
+pnpm dev
+```
+
+Open the URL printed by the server (default `http://localhost:3000`). Expect the
+loading screen followed by the translated starter interface and animated text.
+Refresh the browser manually after a successful rebuild.
+
+```sh
+pnpm build
+pnpm exec tsc --noEmit --skipLibCheck false
+pnpm release
+```
+
+Development output is `bin-debug/`; release output is
+`bin-release/web/<timestamp>/`. Serve the generated directory over HTTP for
+browser checks. `pnpm clean` removes both output trees.
+
+The full declaration check requires CLI >= 3.6.1 for generated host skinParts;
+rebuild after adopting it. Use the project's installed TypeScript compiler.
+The CLI transpiles with esbuild; a successful build does not establish complete
+TypeScript type correctness or gameplay behavior. Check console errors, resource
+requests and the intended interactions in the browser.
+
+## Project map
+
+- `src/Main.ts`: application startup and gameplay/UI composition. Preserve the
+  existing font → Player → resources/theme → translations → scene ordering.
+- `src/StyleManager.ts`, `LocaleManager.ts`, `AssetAdapter.ts`, `Preloader.ts`
+  and `LifecycleHandler.ts`: startup services; consult them when changing their
+  responsibility rather than reading all of them for every gameplay task.
+- `resource/default.res.json`: resource manifest; `resource/config/`: fonts,
+  colors and language settings; `resource/lang/`: translation text.
+- `resource/ui/skins/`: editable default KUI skins. For reusable controls, pair
+  `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.
+- `bin-debug/`, `bin-release/`, `.kurot/` and generated theme JSON: build outputs.
+  Edit authored inputs; the CLI generates the Skin module and part declarations.
+
+## Read only what the task needs
+
+For UI creation, read [standard UI authoring](node_modules/@kurot/ui/docs/ui-authoring.md)
+and the [complete ScoreHUD pair](node_modules/@kurot/ui/docs/recipes/score-hud.md).
+They specify the project tree above, typed component/Skin pairing and caller-owned
+cleanup, and ship since UI 3.6.2. If an older installation lacks them, use that
+version's README/types or the engine checkout's `packages/ui/docs/` guides when
+available; verify APIs against the installed version.
+Keep any game-specific variations in this project's README/AGENTS rather than
+re-reading engine source for ordinary UI tasks.
+
+For gameplay, use Core's `docs/game-authoring.md` when available. In an engine
+checkout, it links `examples/star-catcher`, a complete game with `pnpm check`.
+The game guide ships since Core 2.5.5; Star Catcher is repository content.
+Older installed packages retain the README/type-declaration fallback.
+
+After installation, choose the relevant guide:
+
+| Task | Installed documentation |
+| --- | --- |
+| Startup, display and input APIs | [Core README](node_modules/@kurot/core/README.md) |
+| Resource loading | [Resource guide](node_modules/@kurot/core/docs/resource.md) |
+| Tween/MovieClip | [Game README](node_modules/@kurot/game/README.md) |
+| UI workflow, directories and cleanup | [UI authoring](node_modules/@kurot/ui/docs/ui-authoring.md) (UI >= 3.6.2) |
+| Complete TS/Skin pair | [ScoreHUD](node_modules/@kurot/ui/docs/recipes/score-hud.md) (UI >= 3.6.2) |
+| HUD, controls and skin lifecycle | [UI README](node_modules/@kurot/ui/README.md) |
+| KUI/build commands | [CLI README](node_modules/@kurot/cli/README.md) |
+| Fonts, colors and language startup | [Template guide](node_modules/@kurot/cli/docs/game-template.md) |
+
+These links are project-relative and become available after installation.
+Read package.json, pnpm-lock.yaml and `pnpm list --depth 0` for declared, locked
+and installed versions. Use public `dist/index.d.ts` and re-exported declarations
+to confirm APIs; older installations can lack newer guides. Published Game 2.0.0
+has README/types but omits docs/. Use those before consulting versioned source.
+
+The 2× default atlas needs Core >= 2.5.0 within 2.x; also satisfy the installed
+UI's Core peer. ui-document supports this starter's stylesheet parsing.
+CLI-compiled skins run through UI; add ui-runtime only for its materialization
+features. Existing project dependencies remain project-owned.