@kurot/cli 3.3.0 → 3.4.0

package/dist/utils/logger.js

@@ -6,6 +6,9 @@ const cyan = '\x1b[36m';
 const dim = '\x1b[2m';
 const tag = `${cyan}[kurot]${reset}`;
 let enabled = true;
+/**
+ * Writes human-readable logs only when logging is enabled.
+ */
 function write(method, message) {
     if (!enabled)
         return;
@@ -22,10 +25,25 @@ export function setLoggerEnabled(value) {
  * Human-readable CLI logger with a consistent Kurot prefix and severity color.
  */
 export const logger = {
+    /**
+     * Writes an informational message.
+     */
     info: (msg) => write('log', `${tag} ${msg}`),
+    /**
+     * Writes a successful-operation message.
+     */
     success: (msg) => write('log', `${tag} ${green}${msg}${reset}`),
+    /**
+     * Writes a warning message.
+     */
     warn: (msg) => write('warn', `${tag} ${yellow}${msg}${reset}`),
+    /**
+     * Writes an error message.
+     */
     error: (msg) => write('error', `${tag} ${red}${msg}${reset}`),
+    /**
+     * Writes a build-stage message.
+     */
     step: (msg) => write('log', `${tag} ${dim}›${reset} ${msg}`),
 };
 //# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,MAAM,KAAK,GAAG,SAAS,CAAC;AACxB,MAAM,KAAK,GAAG,UAAU,CAAC;AACzB,MAAM,MAAM,GAAG,UAAU,CAAC;AAC1B,MAAM,GAAG,GAAG,UAAU,CAAC;AACvB,MAAM,IAAI,GAAG,UAAU,CAAC;AACxB,MAAM,GAAG,GAAG,SAAS,CAAC;AAEtB,MAAM,GAAG,GAAG,GAAG,IAAI,UAAU,KAAK,EAAE,CAAC;AAErC,IAAI,OAAO,GAAG,IAAI,CAAC;AAEnB,SAAS,KAAK,CAAC,MAAgC,EAAE,OAAe;IAC/D,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC9C,OAAO,GAAG,KAAK,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACrB,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IAC1D,OAAO,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,KAAK,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC;IAC7E,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC;IAC5E,KAAK,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC;IAC3E,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;CAC1E,CAAC"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,MAAM,KAAK,GAAG,SAAS,CAAC;AACxB,MAAM,KAAK,GAAG,UAAU,CAAC;AACzB,MAAM,MAAM,GAAG,UAAU,CAAC;AAC1B,MAAM,GAAG,GAAG,UAAU,CAAC;AACvB,MAAM,IAAI,GAAG,UAAU,CAAC;AACxB,MAAM,GAAG,GAAG,SAAS,CAAC;AAEtB,MAAM,GAAG,GAAG,GAAG,IAAI,UAAU,KAAK,EAAE,CAAC;AAErC,IAAI,OAAO,GAAG,IAAI,CAAC;AAEnB;;GAEG;AACH,SAAS,KAAK,CAAC,MAAgC,EAAE,OAAe;IAC/D,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,OAAO,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC;AAC1B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAc;IAC9C,OAAO,GAAG,KAAK,CAAC;AACjB,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG;IACrB;;OAEG;IACH,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,GAAG,EAAE,CAAC;IAE1D;;OAEG;IACH,OAAO,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,KAAK,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC;IAE7E;;OAEG;IACH,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC;IAE5E;;OAEG;IACH,KAAK,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,KAAK,EAAE,CAAC;IAE3E;;OAEG;IACH,IAAI,EAAE,CAAC,GAAW,EAAQ,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;CAC1E,CAAC"}

package/docs/ai-context.md

@@ -1,8 +1,8 @@
 # @kurot/cli — AI context map
 
 Read this before exploring `src/`. [`architecture.md`](./architecture.md)
-explains the plugin pipeline. The package is `@kurot/cli@3.3.0`, runs on
-Node.js 20+, and is installed as a project dev dependency.
+explains the plugin pipeline. Version `@kurot/cli@3.4.0` is prepared (not yet published), runs on Node.js 20+,
+and is installed as a project dev dependency.
 
 ## Directory map
 
@@ -16,6 +16,8 @@ src/
 │   ├── project.ts                 resolved paths, dependencies, namespaces
 │   ├── pipeline.ts                BuildContext and ordered plugin runner
 │   ├── dev-server.ts              static server and watchers
+│   ├── resource-watcher.ts        recursive resource + shallow parent watch/reconnect
+│   ├── resource-asset-sync.ts     content comparison, staged writes and deletion reconciliation
 │   ├── diagnostics/               stable codes and JSON/JSONL output
 │   ├── components/                reusable component discovery
 │   ├── kui/                       UIDocument → SkinIR → ESM compiler
@@ -28,8 +30,21 @@ 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 prepared for publication with Label preset compilation and
+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
+
+The prepared release registers BitmapLabel and RichLabel from published UI
+3.3.0 and consumes document 0.12.0. `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.
+See [text-components.md](text-components.md). Apps need Core ^2.3.0/UI ^3.3.0
+when using the new tags; other controls need no incidental engine upgrade.
 
 ## KUI compilation
 
@@ -45,7 +60,7 @@ and layout apply to the runtime Skin, and its direct visual children become
 `property.state` attributes. Storage IDs and runtime mapping metadata are not
 authored XML fields.
 
-CLI 3.3.0 requires `@kurot/ui-document@^0.11.0`. Schema-defined strings, including
+CLI 3.4.0 requires published `@kurot/ui-document@^0.12.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
@@ -88,6 +103,11 @@ 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
+  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.
+  Read [dev resource watching](dev-resource-watching.md) for the exact boundaries.
 - `compileCustomNamespaces` must precede `compileSource`. Application-relative
   imports and generated `#ns/<prefix>` imports must resolve to one bundled class
   identity.

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.3.0 consumes ui-document 0.11.x, retaining Label text-fitting metadata. The
+CLI 3.4.0 consumes ui-document 0.12.x, 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
@@ -78,8 +78,14 @@ 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.
-The resource watcher includes the fixed style.json path, rebuilding skins when
-its palette or Label presets change; font loading remains an application responsibility.
+Since 3.3.1, 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.
+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).
 
 ## Diagnostics
 

package/docs/dev-resource-watching.md

@@ -0,0 +1,88 @@
+# 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.
+
+## Inputs and rebuilds
+
+`kurot dev` watches the entire `resource/` subtree regardless of whether `ui` is
+enabled. Runtime files do not need an extension allowlist or a special atlas
+directory. This includes JSON configurations, PNG/JPEG/WebP, fonts, audio,
+translations and other project-owned files.
+
+| Input change | Action |
+| --- | --- |
+| KUI source, default.res.json or config/style.json in a UI project | Compile KUI and synchronize runtime assets |
+| Runtime JSON, including config/locale.json and sheet JSON | Synchronize assets |
+| 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
+not introduce a locale parser or mutate authored skins. A style edit may change
+compiled skin assignments while its XML remains untouched.
+
+The resource watcher uses recursive `fs.watch` on the resource directory plus a
+shallow parent watcher, so it can reconnect when a missing root is created or an
+existing root is replaced. It does not recursively watch dependencies or build
+output. Native recursive watch support is required; setup failures are logged.
+
+## Batches and synchronization
+
+Events are debounced for 100 ms. A batch retains its need for KUI compilation even
+when a later event concerns only a runtime resource. Resource updates and
+component rebuilds share a serialized queue. Failed KUI batches are retried on
+subsequent resource edits before any resource synchronization can succeed.
+
+Synchronization scans source assets, compares SHA-256 content hashes and writes
+only changed files. It stages every changed file on the output filesystem before
+publishing. Each changed file is renamed into place; source-owned deleted files
+and empty parent directories are removed. Directory renames and file/directory
+replacements are reconciled. Generated theme files, compiled bundles and catalogs
+are not treated as source-owned assets. Identical contents are not rewritten.
+
+Source renames during a scan are retried at most twice after an initial ENOENT
+failure. Other errors are reported through a failed build-complete event; dev
+stays running for the next edit. A failed scan leaves staged bytes unpublished.
+Publication itself can fail after some files have been renamed: this is not a
+rollback transaction.
+
+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.
+
+## Preview and atlas boundaries
+
+Browser refresh remains manual. Successful HTTP responses use
+`Cache-Control: no-store`, so a reloaded preview requests current output files.
+The CLI does not invalidate resources inside a running game's Core cache.
+Reskin's existing reload-preview button can load synchronized assets without
+restarting the dev process.
+
+Atlas PNG and JSON can be saved together and handled in the same debounce batch.
+The CLI copies bytes; it does not parse or validate atlas geometry, discover
+source images, pack atlases or require an atlas dependency. It does not infer
+when an external packer has finished a job.
+
+**Debouncing and per-file atomic renames are not an atomic PNG/JSON transaction.**
+Files saved farther apart can produce separate successful batches, and a request
+during publication can observe different generations. For now, save both files
+before refreshing. A tool requiring strict cross-process group consistency needs
+a separate commit notification/version protocol; that is outside this change.
+
+Every resource batch currently scans and hashes the complete source asset tree,
+reading one file at a time and staging changed files on disk. This avoids retaining
+all decoded assets in memory and avoids rewriting unchanged output, but scan I/O
+still grows with total resource size. Path-based scan caches can be evaluated
+separately for large projects.
+
+## Verification
+
+`test/resource-watch.test.ts` starts actual CLI processes and verifies HTTP bytes,
+cache headers, runtime-only updates without changed skin output, atlas atomic-save
+events, locale/properties/fonts, rename/deletion, Core-only root creation/recreation,
+mixed style/runtime changes, failure retention and recovery. Existing CLI KUI,
+manifest, component and Label preset watch tests cover their respective rebuilds.

package/docs/label-text-layout.md

@@ -1,6 +1,6 @@
 # Label text compilation
 
-CLI 3.3.0 consumes ui-document 0.11.x and compiles KUI text-fitting properties
+CLI 3.4.0 consumes ui-document 0.12.x and compiles KUI text-fitting properties
 through the existing UIDocument → SkinIR → ESM factory pipeline. The semantic
 document format remains version 2.
 

package/docs/text-components.md

@@ -0,0 +1,45 @@
+# BitmapLabel and RichLabel compilation
+
+CLI 3.4.0 uses published ui-document 0.12.0. 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.
+
+```xml
+<Skin xmlns="https://kurot.dev/ui/1" class="TextSkin" states="disabled">
+    <BitmapLabel id="score" text="100.80" font="score_font" />
+    <RichLabel id="notice" width="240">
+        <textFlow>
+            <Span text="Balance: " size="20" />
+            <Span text="100.80" size="20" bold="true" textColor="#FFCC00" />
+        </textFlow>
+        <textFlow.disabled />
+    </RichLabel>
+</Skin>
+```
+
+Register `score_font` as a `font` in default.res.json. Core's font analyzer loads
+the descriptor and its image page; `style.json.fonts` describes vector fonts
+and is a separate contract. BitmapLabel uses glyph metrics, not Label size,
+colors or text presets. Scale the component when bitmap glyph scaling is needed.
+
+RichLabel inherits Component, not Label. Its only content property is textFlow.
+Supported Span styles are fontFamily, size, bold, italic, textColor, strokeColor
+and stroke. Runs share continuous wrapping; omitted styles use native defaults
+independently. Text, including spaces, backslashes and numeric-looking strings,
+is literal. Use `&#10;` for explicit hard line breaks.
+
+A state flow replaces the complete run array. `<textFlow.disabled />` clears
+content, while an omitted state flow inherits it. Generated native SetProperty
+overrides restore the prior array when removed. Span elements are not component
+nodes; `.kurot/skin-parts.d.ts` exposes only the identified text components.
+
+New text components reject unsupported properties and malformed base/state
+values before emitting output. Existing CLI-only controls and project classes
+retain their separate registration rules. Authored XML is never rewritten, and
+failed builds retain the last good theme bundle and part declarations.
+
+See the [shared authoring contract](../../ui-document/docs/text-components.md)
+and [native RichLabel](../../ui/docs/rich-label.md). Existing apps that do not
+use the new tags need no UI/Core upgrade just to update the CLI. Editor adoption
+is separate; an old Editor does not acquire new authoring controls from a CLI upgrade.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@kurot/cli",
-	"version": "3.3.0",
+	"version": "3.4.0",
 	"description": "Kurot CLI - build tool for Kurot Editor KUI XML workflows",
 	"author": "Kelvin <kyia.x52@gmail.com>",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"kurot": "tsx src/index.ts"
 	},
 	"dependencies": {
-		"@kurot/ui-document": "^0.11.0",
+		"@kurot/ui-document": "^0.12.0",
 		"commander": "^13.0.0",
 		"esbuild": "^0.25.0"
 	},