@kurot/cli 3.6.0 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/cli",
-	"version": "3.6.0",
+	"version": "3.7.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/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.

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()));
 	}