@kurot/cli 3.7.0 → 3.8.1

package/dist/core/plugins/index.js

@@ -7,7 +7,7 @@ import { compileSource } from './compile-source.js';
 import { generateHtml } from './generate-html.js';
 import { writeManifest } from './manifest.js';
 import { copyAssets } from './copy-assets.js';
-import { versionAssets } from './version-assets.js';
+import { versionResources } from './version-resources.js';
 export { cleanOutput } from './clean-output.js';
 export { compileKUI } from './compile-kui.js';
 export { compileEngine } from './compile-engine.js';
@@ -17,7 +17,7 @@ export { compileSource } from './compile-source.js';
 export { generateHtml } from './generate-html.js';
 export { writeManifest } from './manifest.js';
 export { copyAssets } from './copy-assets.js';
-export { versionAssets } from './version-assets.js';
+export { versionResources } from './version-resources.js';
 /**
  * The standard build sequence.
  *
@@ -39,7 +39,7 @@ export function defaultPlugins() {
         generateHtml(),
         writeManifest(),
         copyAssets(),
-        versionAssets(),
+        versionResources(),
     ];
 }
 //# sourceMappingURL=index.js.map

package/dist/core/plugins/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/plugins/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc;IAC7B,OAAO;QACN,WAAW,EAAE;QACb,UAAU,EAAE;QACZ,aAAa,EAAE;QACf,uBAAuB,EAAE;QACzB,qBAAqB,EAAE;QACvB,aAAa,EAAE;QACf,YAAY,EAAE;QACd,aAAa,EAAE;QACf,UAAU,EAAE;QACZ,aAAa,EAAE;KACf,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/plugins/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc;IAC7B,OAAO;QACN,WAAW,EAAE;QACb,UAAU,EAAE;QACZ,aAAa,EAAE;QACf,uBAAuB,EAAE;QACzB,qBAAqB,EAAE;QACvB,aAAa,EAAE;QACf,YAAY,EAAE;QACd,aAAa,EAAE;QACf,UAAU,EAAE;QACZ,gBAAgB,EAAE;KAClB,CAAC;AACH,CAAC"}

package/dist/core/plugins/resource-version-css.d.ts

@@ -0,0 +1,7 @@
+export type ResourceUrlVersioner = (source: string, baseFile: string) => string;
+/**
+ * Version CSS url() and string @import references, preserving comments and
+ * ordinary strings. CSS escaping is decoded for lookup and retained on output.
+ */
+export declare function versionCssResources(css: string, file: string, versionUrl: ResourceUrlVersioner): string;
+//# sourceMappingURL=resource-version-css.d.ts.map

package/dist/core/plugins/resource-version-css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-version-css.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/resource-version-css.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;AAEhF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,MAAM,CAmCvG"}

package/dist/core/plugins/resource-version-css.js

@@ -0,0 +1,41 @@
+import valueParser from 'postcss-value-parser';
+/**
+ * Version CSS url() and string @import references, preserving comments and
+ * ordinary strings. CSS escaping is decoded for lookup and retained on output.
+ */
+export function versionCssResources(css, file, versionUrl) {
+    const parsed = valueParser(css);
+    parsed.walk((node, index, nodes) => {
+        if (node.type === 'function' && node.value.toLowerCase() === 'url') {
+            const value = node.nodes.find(child => child.type !== 'space' && child.type !== 'comment');
+            if (value?.type === 'string' || value?.type === 'word') {
+                update(value);
+            }
+            return false;
+        }
+        if (node.type === 'word' && node.value.toLowerCase() === '@import') {
+            const next = nodes.slice(index + 1).find(child => child.type !== 'space' && child.type !== 'comment');
+            if (next?.type === 'string') {
+                update(next);
+            }
+        }
+    });
+    return parsed.toString();
+    function update(node) {
+        const decoded = node.value.replace(/\\(?:([a-f0-9]{1,6})\s?|([\s\S]))/gi, (_match, hex, character) => {
+            if (hex) {
+                const point = Number.parseInt(hex, 16);
+                return point > 0 && point <= 0x10ffff ? String.fromCodePoint(point) : '\uFFFD';
+            }
+            return character && !/[\r\n\f]/.test(character) ? character : '';
+        });
+        const next = versionUrl(decoded, file);
+        if (next === decoded) {
+            return;
+        }
+        node.value = node.type === 'word'
+            ? next.replace(/[\\\s"'()]/g, character => '\\' + character)
+            : next.replace(/\\/g, '\\\\').split(node.quote).join('\\' + node.quote);
+    }
+}
+//# sourceMappingURL=resource-version-css.js.map

package/dist/core/plugins/resource-version-css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-version-css.js","sourceRoot":"","sources":["../../../src/core/plugins/resource-version-css.ts"],"names":[],"mappings":"AAAA,OAAO,WAAW,MAAM,sBAAsB,CAAC;AAI/C;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,IAAY,EAAE,UAAgC;IAC9F,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;QAClC,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,KAAK,EAAE,CAAC;YACpE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;YAC3F,IAAI,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,KAAK,EAAE,IAAI,KAAK,MAAM,EAAE,CAAC;gBACxD,MAAM,CAAC,KAAK,CAAC,CAAC;YACf,CAAC;YACD,OAAO,KAAK,CAAC;QACd,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,SAAS,EAAE,CAAC;YACpE,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;YACtG,IAAI,IAAI,EAAE,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC7B,MAAM,CAAC,IAAI,CAAC,CAAC;YACd,CAAC;QACF,CAAC;IACF,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;IAEzB,SAAS,MAAM,CAAC,IAAmD;QAClE,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,qCAAqC,EAAE,CAAC,MAAc,EAAE,GAAuB,EAAE,SAA6B,EAAE,EAAE;YACpJ,IAAI,GAAG,EAAE,CAAC;gBACT,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;gBACvC,OAAO,KAAK,GAAG,CAAC,IAAI,KAAK,IAAI,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;YAChF,CAAC;YACD,OAAO,SAAS,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACvC,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;YACtB,OAAO;QACR,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,IAAI,KAAK,MAAM;YAChC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,EAAE,CAAC,IAAI,GAAG,SAAS,CAAC;YAC5D,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1E,CAAC;AACF,CAAC"}

package/dist/core/plugins/resource-version-html.d.ts

@@ -0,0 +1,7 @@
+import type { ResourceUrlVersioner } from './resource-version-css.js';
+/**
+ * Write build metadata and static resource versions without serializing scripts
+ * or moving files. Navigation destinations and generated JS URLs remain intact.
+ */
+export declare function versionHtmlResources(html: string, file: string, version: string, versionUrl: ResourceUrlVersioner): string;
+//# sourceMappingURL=resource-version-html.d.ts.map

package/dist/core/plugins/resource-version-html.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-version-html.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/resource-version-html.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAQtE;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,oBAAoB,GAAG,MAAM,CAsD1H"}

package/dist/core/plugins/resource-version-html.js

@@ -0,0 +1,66 @@
+import { defaultTreeAdapter, parse } from 'parse5';
+import { BuildError } from '../errors.js';
+import { versionCssResources } from './resource-version-css.js';
+/**
+ * Write build metadata and static resource versions without serializing scripts
+ * or moving files. Navigation destinations and generated JS URLs remain intact.
+ */
+export function versionHtmlResources(html, file, version, versionUrl) {
+    const document = parse(html, { sourceCodeLocationInfo: true });
+    const pending = [document];
+    const edits = [];
+    let headEnd;
+    while (pending.length > 0) {
+        const parent = pending.pop();
+        for (const element of parent.childNodes.filter(defaultTreeAdapter.isElementNode)) {
+            pending.push(element);
+            if (element.tagName === 'base') {
+                throw new BuildError('output.versionedAssets requires document-relative resources; remove the authored base element.');
+            }
+            if (element.tagName === 'head') {
+                headEnd = element.sourceCodeLocation?.startTag?.endOffset;
+            }
+            if (element.tagName === 'meta' && element.attrs.some(attr => attr.name === 'name' && attr.value === 'kurot-resource-version')) {
+                throw new BuildError('output.versionedAssets owns the kurot-resource-version metadata; remove the authored value.');
+            }
+            for (const attr of element.attrs) {
+                const attributeName = attr.prefix ? `${attr.prefix}:${attr.name}` : attr.name;
+                const location = element.sourceCodeLocation?.attrs?.[attributeName];
+                if (!location) {
+                    continue;
+                }
+                const asset = attr.name === 'src' || attr.name === 'poster' ||
+                    (attr.name === 'href' && ['link', 'image', 'use'].includes(element.tagName)) ||
+                    (attr.name === 'data' && element.tagName === 'object');
+                const next = attr.name === 'style'
+                    ? versionCssResources(attr.value, file, versionUrl)
+                    : asset ? versionUrl(attr.value, file) : attr.value;
+                if (next !== attr.value) {
+                    edits.push({ start: location.startOffset, end: location.endOffset, text: `${attributeName}="${escapeAttribute(next)}"` });
+                }
+            }
+            if (element.tagName === 'style') {
+                for (const text of element.childNodes.filter(defaultTreeAdapter.isTextNode)) {
+                    const location = text.sourceCodeLocation;
+                    const next = versionCssResources(text.value, file, versionUrl);
+                    if (location && next !== text.value) {
+                        edits.push({ start: location.startOffset, end: location.endOffset, text: next });
+                    }
+                }
+            }
+        }
+    }
+    if (headEnd === undefined) {
+        throw new BuildError('output.versionedAssets requires an explicit HTML head element.');
+    }
+    edits.push({ start: headEnd, end: headEnd, text: `\n\t<meta name="kurot-resource-version" content="${escapeAttribute(version)}">` });
+    let result = html;
+    for (const edit of edits.sort((left, right) => right.start - left.start)) {
+        result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+    }
+    return result;
+}
+function escapeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+//# sourceMappingURL=resource-version-html.js.map

package/dist/core/plugins/resource-version-html.js.map

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

package/dist/core/plugins/version-resources.d.ts

@@ -0,0 +1,7 @@
+import type { BuildPlugin } from '../pipeline.js';
+/**
+ * Stamp resource requests with the release build number. Generated JavaScript
+ * keeps its content-hashed names and original paths; no document base is changed.
+ */
+export declare function versionResources(): BuildPlugin;
+//# sourceMappingURL=version-resources.d.ts.map

package/dist/core/plugins/version-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-resources.d.ts","sourceRoot":"","sources":["../../../src/core/plugins/version-resources.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAgB,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAKhE;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,WAAW,CA2B9C"}

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

@@ -0,0 +1,89 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { BuildError } from '../errors.js';
+import { versionCssResources } from './resource-version-css.js';
+import { versionHtmlResources } from './resource-version-html.js';
+/**
+ * Stamp resource requests with the release build number. Generated JavaScript
+ * keeps its content-hashed names and original paths; no document base is changed.
+ */
+export function versionResources() {
+    return {
+        name: 'version release resources',
+        async apply(ctx) {
+            if (ctx.project.mode !== 'release' || !ctx.project.config.output.versionedAssets) {
+                return;
+            }
+            const files = await listFiles(ctx.project.outputDir);
+            const version = path.basename(ctx.project.outputDir);
+            const versionUrl = createVersioner(new Set(files), version);
+            const updates = [];
+            for (const file of files) {
+                if (!/\.(?:html|css)$/i.test(file)) {
+                    continue;
+                }
+                const source = await fs.readFile(path.join(ctx.project.outputDir, file), 'utf8');
+                const contents = /\.html$/i.test(file)
+                    ? versionHtmlResources(source, file, version, versionUrl)
+                    : versionCssResources(source, file, versionUrl);
+                updates.push({ file, contents });
+            }
+            // Validate every page before replacing any generated HTML/CSS.
+            for (const update of updates) {
+                await fs.writeFile(path.join(ctx.project.outputDir, update.file), update.contents);
+            }
+        },
+    };
+}
+function createVersioner(files, version) {
+    return (source, baseFile) => {
+        if (!source || source.startsWith('#')) {
+            return source;
+        }
+        let target;
+        try {
+            target = new URL(source, `https://kurot.invalid/${baseFile}`);
+        }
+        catch {
+            return source;
+        }
+        if (target.origin !== 'https://kurot.invalid') {
+            return source;
+        }
+        let file;
+        try {
+            file = decodeURIComponent(target.pathname).slice(1);
+        }
+        catch {
+            return source;
+        }
+        if (!files.has(file) || file.startsWith('js/') || /\.html?$/i.test(file)) {
+            return source;
+        }
+        const hash = source.indexOf('#');
+        const fragment = hash < 0 ? '' : source.slice(hash);
+        const reference = hash < 0 ? source : source.slice(0, hash);
+        const query = reference.indexOf('?');
+        const pathname = query < 0 ? reference : reference.slice(0, query);
+        const parameters = new URLSearchParams(query < 0 ? '' : reference.slice(query + 1));
+        parameters.set('v', version);
+        return `${pathname}?${parameters}${fragment}`;
+    };
+}
+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 resources require regular output files: ${relative}`);
+        }
+    }
+    return files;
+}
+//# sourceMappingURL=version-resources.js.map

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

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

package/docs/ai-context.md

@@ -1,6 +1,6 @@
 # @kurot/cli — AI context map
 
-`@kurot/cli@3.7.0` is build-time tooling on Node.js >= 20, with ordinary
+`@kurot/cli@3.8.1` (prepared for publication) 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.
@@ -150,12 +150,20 @@ manual prefix cannot conflict with `ui.components.namespace`.
 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.
+CLI >= 3.8.1 within 3.x with Core >= 2.7.0 within 2.x supports resource
+queries. `version-resources.ts` runs last and
+stamps each HTML page with the release directory's timestamp. HTML/CSS local
+assets receive a `v` query; Core transports version local resource/ requests.
+Generated JS, import maps, manifest paths and output directories stay unchanged.
+`resource-version-html.ts` preserves script bytes and owns metadata validation;
+`resource-version-css.ts` owns CSS URL parsing. Native fetch/FontFace/Theme calls
+use Core's resolveResourceUrl; new starters enable the flag explicitly. See
+[release resources](release-assets.md) for the protocol and deployment limits.
+
+Since CLI 3.8.0, root ESM config stage changes regenerate HTML in `kurot dev` without
+restarting dev; `core/config-watcher.ts` owns this path. See
+[development watching](dev-resource-watching.md). Core canvas-attribute startup
+requires Core >= 2.6.0 within 2.x; explicit overrides remain supported.
 
 ## Configuration lookup
 

package/docs/architecture.md

@@ -40,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.7.0 consumes ui-document ^0.13.0, retaining Label text-fitting metadata. The
+CLI 3.8.1 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
@@ -72,12 +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.
+With CLI >= 3.8.1 within 3.x and Core >= 2.7.0 within 2.x,
+`output.versionedAssets: true` writes the release directory timestamp to HTML
+metadata and appends it as `v` to static HTML/CSS assets. Core transports use that
+metadata for local resource/ files, including secondary atlas/font pages. Native
+fetch/FontFace/Theme callers use Core's resolveResourceUrl. Generated JS hashes,
+manifest paths and BuildContext outputs remain unchanged. No files move and no
+HTML base is inserted. See [release resources](release-assets.md).
 
 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,
@@ -97,6 +98,10 @@ 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

@@ -81,19 +81,18 @@ 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.
 
-Use the checkout CLI with the example's installed SDKs. From the repository root:
+Use the example's installed registry CLI and SDKs. From the repository root:
 
 ```sh
-pnpm --dir packages/cli build
-cd examples/game
-node ../../packages/cli/dist/index.js dev
+pnpm --dir examples/game install --frozen-lockfile
+pnpm --dir examples/game 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.
+directory, `pnpm build --strict` and `pnpm release --strict` run 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.
 

package/docs/dev-resource-watching.md

@@ -17,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.
 
@@ -52,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

@@ -31,6 +31,23 @@ 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.
 
+## Stage defaults
+
+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.
+
+## Release resources
+
+Both starters enable output.versionedAssets. Resource queries use the release
+build number with Core >= 2.7.0 within 2.x and CLI >= 3.8.1 within 3.x. The game
+starter resolves native style/font and Theme requests through resolveResourceUrl
+before Player creation. See [release resources](release-assets.md).
+
 ## HTML brand splash
 
 The game template's `web/index.html` presents `web/logo.png` beneath a small

package/docs/release-assets.md

@@ -1,76 +1,85 @@
-# Versioned release assets
+# Release resource versions
 
-Enable content-addressed release packaging in `kurot.config.ts`:
+The query-based protocol requires **CLI >= 3.8.1 within 3.x and Core >= 2.7.0
+within 2.x**. These source versions are prepared for publication. It replaces
+the earlier whole-build directory packaging.
+
+Enable it in `kurot.config.ts`:
 
 ```ts
 export default {
-	output: { dir: 'bin-debug', versionedAssets: true },
-	// Keep the project's other settings.
+    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.
+The configuration field defaults to false for existing configurations. New game
+and empty starters explicitly enable it. Development/watch builds are unchanged.
 
-## Output and URLs
+## Output and build number
 
 ```text
-bin-release/web/<timestamp>/
+bin-release/web/261030123456/
 ├── index.html
 ├── manifest.json
-└── assets/<hash>/
-    ├── js/
-    ├── resource/
-    └── <files copied beside the HTML template>
+├── js/main.min_<content-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:
+The existing release directory timestamp (`YYMMDDHHmmss`) is the resource build
+number. The CLI inserts `<meta name="kurot-resource-version" content="261030123456">`
+into each generated HTML page. It creates no asset hash directory or HTML base.
+The release manifest, import map, generated JS filenames, source maps and JS
+imports retain their original paths. Identical JS can retain its filename hash
+across releases even when the resource build number changes.
+
+Core reads the metadata before Player creation. Its GET HttpRequest, ImageLoader,
+Sound, Video and sound-resource transports append `v` to same-origin files below
+the page's `resource/` directory. Resource manifests, atlas and bitmap-font pages,
+and adapters using these transports receive the same version. Authored resource
+keys and descriptors remain unchanged. Existing query fields/fragments survive;
+an existing `v` is replaced once.
+
+Native browser callers must opt in through the public Core helper:
 
 ```ts
-const theme = new Theme(new URL('resource/default.thm.json', document.baseURI).href);
+import { resolveResourceUrl } from '@kurot/core';
+
+const response = await fetch(resolveResourceUrl('resource/config/style.json'));
+const font = new FontFace('ProjectFont', `url("${resolveResourceUrl('resource/font.ttf')}")`);
+const theme = new Theme(resolveResourceUrl(new URL('resource/default.thm.json', document.baseURI)));
 ```
 
-Use the same pattern in existing projects. This keeps the theme's `skinsJs`
-import inside the version directory without requiring a UI runtime update.
+The game starter includes this wiring for startup fonts/styles and Theme. Theme
+config is versioned, while its generated `skinsJs` continues using the JS filename
+hash. Core does not replace global fetch or XMLHttpRequest. API requests outside
+`resource/`, POST requests, remote/CDN URLs, data/blob URLs and JS modules retain
+their original URLs. Remote or signed resources need their own version policy.
+
+## Static HTML and CSS
+
+The CLI also versions existing local files referenced by HTML `src`, `poster`,
+link/SVG `href`, object `data`, inline styles, style blocks, CSS `url()` and string
+`@import`. This includes page logos, fonts, stylesheets and startup configuration
+scripts outside `js/`. It preserves scripts and ordinary strings. Navigation
+links, form destinations, HTML pages and generated files under `js/` are unchanged.
+Native URLs constructed inside scripts must use the helper or read the generated
+metadata in a standalone page without Core. `srcset` rewriting is not provided.
 
-## Deployment
+Custom HTML pages need an explicit `<head>` and no authored `<base>` or
+`kurot-resource-version` metadata. The build validates every page before rewriting
+HTML/CSS. Symbolic links and other nonregular output files are rejected.
+Use document-relative paths to support deployment under a subdirectory.
 
-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.
+## Deployment and caching
 
-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.
+Deploy the entire generated release directory. Revalidate entry HTML and
+manifest.json (for example `Cache-Control: no-cache`). Configure CDN/cache keys to
+include `v`; otherwise different builds can still share stale resource responses.
+Generated content-hashed JS can retain long-lived immutable caching. Resource
+URLs may be cached by their version query, but replacing a same-path file does
+not retain older bytes for an uncached old URL. This is cache busting, not release
+snapshot storage. Use separate deployment directories if old sessions must lazily
+load their exact previous files after deployment. Server headers and atomic
+publishing remain deployment responsibilities.