@moku-labs/game 0.8.0 → 0.9.0

package/dist/assets.mjs

@@ -1894,9 +1894,10 @@ function keyOf(feature, relative, file) {
 //#endregion
 //#region src/plugins/assets/scan/scan.ts
 /**
-* @file assets plugin, build time — the walk. `features/*` with an `assets/` folder becomes the
-* manifest: one bundle per feature, split by the optional `assets.ts` that feature exports.
-* Node and Bun only. Nothing under `src/` outside `scan/` imports it, so no game bundles it.
+* @file assets plugin, build time — the walk. `features/*` with an `assets/` folder, and every
+* layer the options map (a folder under the root read like one more feature), becomes the manifest:
+* one bundle per feature or layer, split by the optional `assets.ts` it exports. Node and Bun only.
+* Nothing under `src/` outside `scan/` imports it, so no game bundles it.
 */
 const TIERS = [
 	"boot",
@@ -1982,6 +1983,75 @@ async function listFeatures(dir) {
 	return (await readdir(dir, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory()).map((entry) => entry.name).toSorted(byName$1);
 }
 /**
+* Tells whether a path is a folder.
+*
+* @param dir - The path to look at.
+* @returns True for a folder; false for a file or nothing.
+*/
+async function isFolder(dir) {
+	return await stat(dir).then((entry) => entry.isDirectory(), () => false);
+}
+/**
+* Says why one layer cannot be read, by its own folder and name alone.
+*
+* @param folder - The layer folder under the root.
+* @param name - The name its keys and bundles take.
+* @param features - Name of the features folder.
+* @param featureNames - The feature folders found under it.
+* @returns The problem, or `undefined` when the layer is fine on its own.
+* @example
+* ```ts
+* layerRefusal("shared", "u.i", "features", []);
+* // 'the layer "shared" is mapped to "u.i", which is empty or has a "." that would fake a folder.'
+* ```
+*/
+function layerRefusal(folder, name, features, featureNames) {
+	if (folder === "" || /[/\\.]/.test(folder)) return `the layer "${folder}" is not a folder name: ` + String.raw`use a name without "/", "\" or ".".`;
+	if (folder === features) return `the layer "${folder}" is the features folder "${features}"; the features are scanned already.`;
+	if (name === "" || name.includes(".")) return `the layer "${folder}" is mapped to "${name}", which is empty or has a "." that would fake a folder.`;
+	if (featureNames.includes(name)) return `the layer "${folder}" is mapped to "${name}", which is also a feature folder: their keys and bundles would merge.`;
+}
+/**
+* Says that a layer is mapped to a name an earlier layer took.
+*
+* @param first - The folder of the earlier layer with that name, if one took it.
+* @param folder - The layer folder.
+* @param name - The name it is mapped to.
+* @returns The refusal, or `undefined` when no earlier layer took the name.
+* @example
+* ```ts
+* nameTakenRefusal("common", "shared", "ui"); // 'the layers "common" and "shared" are both mapped to "ui".'
+* ```
+*/
+function nameTakenRefusal(first, folder, name) {
+	if (first === void 0) return void 0;
+	return `the layers "${first}" and "${folder}" are both mapped to "${name}".`;
+}
+/**
+* Checks every layer of a map, sorted by folder: one refusal at most per layer, and a name that an
+* earlier layer took is a refusal of the later one.
+*
+* @param layers - Folder to name.
+* @param features - Name of the features folder.
+* @param featureNames - The feature folders found under it.
+* @returns Every layer with its refusal, in the order of the sorted folders.
+*/
+function checkLayers(layers, features, featureNames) {
+	const taken = /* @__PURE__ */ new Map();
+	const checks = [];
+	const sorted = Object.entries(layers).toSorted((left, right) => byName$1(left[0], right[0]));
+	for (const [folder, name] of sorted) {
+		const refusal = layerRefusal(folder, name, features, featureNames) ?? nameTakenRefusal(taken.get(name), folder, name);
+		if (refusal === void 0) taken.set(name, folder);
+		checks.push({
+			folder,
+			name,
+			refusal
+		});
+	}
+	return checks;
+}
+/**
 * Walks one `assets/` folder.
 *
 * @param dir - The folder to read.
@@ -2064,20 +2134,21 @@ function readSpec(scan, feature, name, raw, specs) {
 	});
 }
 /**
-* Reads the bundles a feature declares. Every export that is a `defineBundles` result counts.
+* Reads the bundles a feature or a layer declares. Every export that is a `defineBundles` result
+* counts.
 *
 * @param scan - State of the scan.
-* @param feature - Name of the feature.
-* @returns The declared bundles, empty when the feature brought no description.
+* @param owner - The feature or layer: its folder and the name its bundles take.
+* @returns The declared bundles, empty when the owner brought no description.
 */
-async function readBundleSpecs(scan, feature) {
+async function readBundleSpecs(scan, owner) {
 	const specs = /* @__PURE__ */ new Map();
-	const file = path.join(scan.featuresFolder, feature, "assets.ts");
+	const file = path.join(owner.dir, "assets.ts");
 	try {
 		const loaded = await importDescription(file);
 		for (const value of Object.values(loaded ?? {})) {
 			if (!isRecord(value) || value.kind !== "bundles" || !isRecord(value.map)) continue;
-			for (const [name, raw] of Object.entries(value.map)) readSpec(scan, feature, name, raw, specs);
+			for (const [name, raw] of Object.entries(value.map)) readSpec(scan, owner.name, name, raw, specs);
 		}
 	} catch (error) {
 		const relative = toPosix(path.relative(scan.root, file));
@@ -2351,14 +2422,16 @@ async function addFile(scan, pass, relative) {
 	}
 }
 /**
-* Reads one feature: its description first, then its fonts, then every file of its `assets/`.
+* Reads one feature or layer: its description first, then its fonts, then every file of its
+* `assets/`.
 *
 * @param scan - State of the scan.
-* @param feature - Name of the feature folder.
+* @param owner - The feature or layer: its folder and the name its keys and bundles take.
 */
-async function scanFeature(scan, feature) {
-	const specs = await readBundleSpecs(scan, feature);
-	const assetsFolder = path.join(scan.featuresFolder, feature, "assets");
+async function scanOwner(scan, owner) {
+	const feature = owner.name;
+	const specs = await readBundleSpecs(scan, owner);
+	const assetsFolder = path.join(owner.dir, "assets");
 	for (const [name, spec] of specs) draftOf(scan, name, feature, spec.tier);
 	const files = await walkAssets(assetsFolder, "");
 	const fonts = await readFonts(scan, assetsFolder, files);
@@ -2457,26 +2530,57 @@ async function applyOutputs(outputs, write) {
 	return changed;
 }
 /**
-* Walks the features of a game and writes its two generated files: one bundle per feature, split
-* by the optional `assets.ts` of that feature, every file keyed by the key rule. A check run
+* Reads the layers that passed their checks, sorted by folder. A layer without its folder is a
+* note, not a problem: a typo in `--layer` would otherwise drop its keys without a word.
+*
+* @param scan - State of the scan.
+* @param checks - Every layer with its refusal; a refused layer is not read.
+*/
+async function scanLayers(scan, checks) {
+	for (const { folder, name, refusal } of checks) {
+		if (refusal !== void 0) continue;
+		const dir = path.join(scan.root, folder);
+		if (!await isFolder(dir)) {
+			scan.notes.push(`the layer "${folder}" has no folder "${folder}/" under the root; nothing was read for it.`);
+			continue;
+		}
+		await scanOwner(scan, {
+			name,
+			dir
+		});
+	}
+}
+/**
+* Walks the features and the layers of a game and writes its two generated files: one bundle per
+* feature or layer, split by its optional `assets.ts`, every file keyed by the key rule. A layer is
+* read like one more feature under its mapped name, after the features. A check run
 * (`write: false`) writes nothing and only reports whether something would change.
 *
-* @param options - The game source root, the two output paths and whether to write.
+* @param options - The game source root, the layers, the two output paths and whether to write.
 * @returns The manifest, the text of the key module and whether an output differed.
-* @throws {Error} One error that lists every problem the scan found.
+* @throws {Error} One error that lists every problem the scan found, the layer problems first.
 * @example
 * ```ts
 * const { manifest, changed } = await scanAssets({
 *   root: "src",
 *   manifest: "public/assets/manifest.json",
-*   keys: "src/generated/assets.ts"
+*   keys: "src/generated/assets.ts",
+*   layers: { shared: "ui" } // shared/assets/button/primary.png keeps the key "ui.button.primary"
 * });
 * // manifest.bundles.ui.files[0].key: "ui.button.primary", changed: true on the first run
 * ```
 */
 async function scanAssets(options) {
-	const scan = createState(options.root, options.features ?? "features");
-	for (const feature of await listFeatures(scan.featuresFolder)) await scanFeature(scan, feature);
+	const features = options.features ?? "features";
+	const scan = createState(options.root, features);
+	const featureNames = await listFeatures(scan.featuresFolder);
+	const checks = checkLayers(options.layers ?? {}, features, featureNames);
+	for (const check of checks) if (check.refusal !== void 0) scan.problems.push(check.refusal);
+	for (const feature of featureNames) await scanOwner(scan, {
+		name: feature,
+		dir: path.join(scan.featuresFolder, feature)
+	});
+	await scanLayers(scan, checks);
 	if (scan.problems.length > 0) throw collected(scan.problems);
 	const manifest = toManifest(scan);
 	const manifestSource = emitManifest(manifest);
@@ -2510,6 +2614,8 @@ const KEYS_FILE = path.join("generated", "assets.ts");
 const DEFAULT_SOURCE$1 = "en";
 /** The extension of an exchange file: the export writes `<dir>/<locale>.json`. */
 const EXCHANGE_EXTENSION = ".json";
+/** The flag that maps a folder under the root to the name its keys take. It repeats. */
+const LAYER_FLAG = "--layer";
 /**
 * Wraps a command line problem in the message shape of the framework.
 *
@@ -2547,15 +2653,35 @@ function isSwitch(flag) {
 	return flag === "--check" || flag === "--no-cache" || flag === "--pseudo";
 }
 /**
+* Reads the value after a flag that takes one: the next argument, unless it is missing or is
+* another flag.
+*
+* @param argv - The arguments after the script name.
+* @param at - Where the flag is.
+* @param what - What the value is, as the refusal names it: `a path`, `a locale`.
+* @returns The value.
+* @throws {Error} When the value is missing or is another flag.
+* @example
+* ```ts
+* valueAt(["--root", "src"], 0, "a path"); // "src"
+* ```
+*/
+function valueAt(argv, at, what) {
+	const value = argv[at + 1];
+	if (value === void 0 || value.startsWith("--")) throw problem$1(`"${String(argv[at])}" needs ${what}.`);
+	return value;
+}
+/**
 * Reads the flags as they were given.
 *
 * @param argv - The arguments after the script name.
-* @returns The value of each flag that takes one, and the switches.
+* @returns The value of each flag that takes one, the switches and the `--layer` values.
 * @throws {Error} When an option is unknown or misses its value.
 */
 function readFlags(argv) {
 	const values = {};
 	const switches = /* @__PURE__ */ new Set();
+	const layers = [];
 	let index = 0;
 	while (index < argv.length) {
 		const flag = argv[index];
@@ -2564,18 +2690,62 @@ function readFlags(argv) {
 			index += 1;
 			continue;
 		}
+		if (flag === LAYER_FLAG) {
+			layers.push(valueAt(argv, index, "\"<folder>[=<name>]\""));
+			index += 2;
+			continue;
+		}
 		if (!isValueFlag(flag)) throw problem$1(`unknown option "${String(flag)}".`);
-		const value = argv[index + 1];
-		if (value === void 0 || value.startsWith("--")) throw problem$1(`"${flag}" needs ${flag === "--source" ? "a locale" : "a path"}.`);
-		values[flag] = value;
+		values[flag] = valueAt(argv, index, flag === "--source" ? "a locale" : "a path");
 		index += 2;
 	}
 	return {
 		values,
-		switches
+		switches,
+		layers
 	};
 }
 /**
+* Reads the `--layer` values into the layer map. `shared=ui` maps the folder to the name,
+* `shared` alone maps it to itself. Only the syntax is checked here; the scan refuses a folder or
+* a name that cannot be a layer.
+*
+* @param raw - The values as given, in order.
+* @returns Folder to name.
+* @throws {Error} When a value has an empty side or a folder repeats.
+* @example
+* ```ts
+* parseLayers(["shared=ui", "common"]); // { shared: "ui", common: "common" }
+* ```
+*/
+function parseLayers(raw) {
+	const layers = /* @__PURE__ */ new Map();
+	for (const value of raw) {
+		const cut = value.indexOf("=");
+		const folder = cut === -1 ? value : value.slice(0, cut);
+		const name = cut === -1 ? value : value.slice(cut + 1);
+		if (folder === "" || name === "" || name.includes("=")) throw problem$1(`"--layer ${value}" needs a folder and a name: "<folder>[=<name>]".`);
+		if (layers.has(folder)) throw problem$1(`"--layer" names the folder "${folder}" twice.`);
+		layers.set(folder, name);
+	}
+	return Object.fromEntries(layers);
+}
+/**
+* The layer member of the options a tool is handed: none for a run without `--layer`, so such a
+* run calls every tool exactly as before layers existed.
+*
+* @param layers - The layers of the run.
+* @returns `{ layers }`, or an empty object when there is no layer.
+* @example
+* ```ts
+* withLayers({}); // {}
+* withLayers({ shared: "ui" }); // { layers: { shared: "ui" } }
+* ```
+*/
+function withLayers(layers) {
+	return Object.keys(layers).length === 0 ? {} : { layers };
+}
+/**
 * Refuses the flags that do not go together, before anything is read or written. An exchange
 * with the translators runs alone; only `--pseudo` may join an import, because the compile after
 * it writes the pseudo-locale too.
@@ -2610,8 +2780,9 @@ function resolveGiven(given) {
 * `manifest.json` inside the root, or inside the pack folder with `--pack`; `--source` to `"en"`.
 *
 * @param argv - The arguments after the script name.
-* @returns The resolved paths, the folders of the three modes and the switches.
-* @throws {Error} When an option is unknown, misses its value or does not go with another.
+* @returns The resolved paths, the folders of the three modes, the switches and the layers.
+* @throws {Error} When an option is unknown, misses its value, does not go with another, or a
+*   `--layer` value is not `<folder>[=<name>]`.
 */
 function parseArgv(argv) {
 	const flags = readFlags(argv);
@@ -2629,7 +2800,8 @@ function parseArgv(argv) {
 		pseudo: switches.has("--pseudo"),
 		source: values["--source"] ?? DEFAULT_SOURCE$1,
 		exportDir: resolveGiven(values["--export"]),
-		importDir: resolveGiven(values["--import"])
+		importDir: resolveGiven(values["--import"]),
+		layers: parseLayers(flags.layers)
 	};
 }
 /**
@@ -2747,9 +2919,9 @@ function packSummary(file, result, cache) {
 	return `wrote "${file}": ${plural(result.pages, "page")}, ${plural(result.loose, "loose file")}, ${plural(fonts, "font")}, ${plural(sounds, "sound")}, ${Math.round(result.bytes / 1024)} KB. cache: ${hits}.`;
 }
 /**
-* The dev run of `bun run assets:keys`: walk the features, write the manifest and the key module, then compile the
-* feature strings next to the key module (the pseudo-locale too with `--pseudo`). With `--check`
-* nothing is written and a difference fails the run.
+* The dev run of `bun run assets:keys`: walk the features and the layers, write the manifest and
+* the key module, then compile the strings next to the key module (the pseudo-locale too with
+* `--pseudo`). With `--check` nothing is written and a difference fails the run.
 *
 * @param options - The parsed flags.
 * @param compile - The strings compiler.
@@ -2762,11 +2934,13 @@ async function runKeys(options, compile, ui) {
 		root: options.root,
 		manifest: options.manifest,
 		keys: options.keys,
-		write: !options.check
+		write: !options.check,
+		...withLayers(options.layers)
 	});
 	const strings = await compile(options.root, path.dirname(options.keys), {
 		check: options.check,
-		pseudo: options.pseudo
+		pseudo: options.pseudo,
+		...withLayers(options.layers)
 	});
 	for (const note of [...notes, ...strings.notes]) ui.warn(note);
 	if ((changed || strings.changed) && options.check) {
@@ -2795,7 +2969,8 @@ async function runPack(options, pack, compile, ui) {
 		root: options.root,
 		manifest: options.manifest,
 		keys: options.keys,
-		write: false
+		write: false,
+		...withLayers(options.layers)
 	});
 	await applyOutputs([{
 		file: options.keys,
@@ -2803,7 +2978,8 @@ async function runPack(options, pack, compile, ui) {
 	}], true);
 	const strings = await compile(options.root, path.dirname(options.keys), {
 		check: false,
-		pseudo: false
+		pseudo: false,
+		...withLayers(options.layers)
 	});
 	for (const note of [...scan.notes, ...strings.notes]) ui.warn(note);
 	const result = await packAssets({
@@ -2829,7 +3005,10 @@ async function runPack(options, pack, compile, ui) {
 * @throws {Error} When the export fails.
 */
 async function runExport(options, dir, exportStrings, ui) {
-	const report = await exportStrings(options.root, dir, { source: options.source });
+	const report = await exportStrings(options.root, dir, {
+		source: options.source,
+		...withLayers(options.layers)
+	});
 	for (const locale of report.locales) ui.info(exportLine(dir, locale, report.missing[locale] ?? 0));
 	return 0;
 }
@@ -2848,7 +3027,8 @@ async function runImport(options, dir, importStrings, ui) {
 	const report = await importStrings(options.root, dir, {
 		source: options.source,
 		pseudo: options.pseudo,
-		out: path.dirname(options.keys)
+		out: path.dirname(options.keys),
+		...withLayers(options.layers)
 	});
 	ui.info(importLine(dir, report));
 	return 0;
@@ -2858,8 +3038,10 @@ async function runImport(options, dir, importStrings, ui) {
 * compile the feature strings next to the key module, or check that all of it is current. With
 * `--pack <dir>` it packs the art for production on the same scan (`--no-cache` for a cold run);
 * `--pseudo` adds the pseudo-locale to a dev run. `--export <dir>` and `--import <dir>` exchange
-* the strings with translators and run alone, from the locale of `--source`. Nothing here calls
-* `process.exit`; the caller does.
+* the strings with translators and run alone, from the locale of `--source`.
+* `--layer <folder>[=<name>]` (repeatable) scans a folder under the root like one more feature,
+* its keys and bundles under `<name>` (`<folder>` by default); it goes with every mode. Nothing
+* here calls `process.exit`; the caller does.
 *
 * @param argv - The arguments after the script name.
 * @param strings - The string tools of i18n: compile, export and import.
@@ -2873,6 +3055,8 @@ async function runImport(options, dir, importStrings, ui) {
 * // 0, and dist/assets holds the pages, the loose files and the packed manifest.json
 * await runCli(["--root", "src", "--export", "translations"], strings);
 * // 0, and translations/ holds one <locale>.json per locale for the translators
+* await runCli(["--root", "src", "--layer", "shared=ui"], strings);
+* // 0, shared/assets/* keyed ui.*, shared/strings/* compiled
 * ```
 */
 async function runCli(argv, strings, ui = createBrandConsole()) {
@@ -6309,13 +6493,16 @@ function pseudoMessage(elements) {
 //#endregion
 //#region src/plugins/i18n/compile/walk.ts
 /**
-* @file i18n plugin, build time — the walk over `features/*​/strings/<locale>.json`: every file
-* read, every key claimed by one feature, every message compiled once and every problem collected,
-* with the text and the translator note of each key kept aside. `compileStrings`, `exportStrings`
-* and `importStrings` all start from it. Node and Bun only.
+* @file i18n plugin, build time — the walk over `features/*​/strings/<locale>.json` and the
+* `strings/` of every layer: every file read, every key claimed by one feature or layer, every
+* message compiled once and every problem collected, with the text and the translator note of each
+* key kept aside. `compileStrings`, `exportStrings` and `importStrings` all start from it. Node and
+* Bun only.
 */
 /** How every problem of the string compiler is prefixed. */
 const PREFIX = "[game] i18n: ";
+/** What a layer folder may not hold: a separator or a ".", which would lead out of the root. */
+const NOT_ONE_FOLDER = /[/\\.]/;
 /**
 * Creates the table of compiled messages per locale. Its own function because lint rule L5
 * refuses a collection built inside an exported declaration.
@@ -6459,24 +6646,53 @@ async function listLocales(folder) {
 	}
 }
 /**
-* Lists every string file of a game: features sorted, then locales sorted.
+* Lists the string files of one feature or layer, locales sorted. A folder without `strings/`
+* yields nothing.
+*
+* @param root - Game source root.
+* @param feature - The label: the feature folder name, or the mapped name of a layer.
+* @param folder - Root-relative POSIX path of the owner folder.
+* @returns The files of that folder.
+*/
+async function listOwnerFiles(root, feature, folder) {
+	const stringsFolder = path.join(root, ...folder.split("/"), "strings");
+	return (await listLocales(stringsFolder)).map((locale) => ({
+		feature,
+		folder,
+		locale,
+		file: path.join(stringsFolder, `${locale}.json`),
+		relative: `${folder}/strings/${locale}.json`
+	}));
+}
+/**
+* The error for a layer folder that is not one folder name under the root: empty, or with a
+* separator or a "." that would read and write outside it.
+*
+* @param folder - The layer folder as given.
+* @returns The error to throw.
+*/
+function notAFolderName(folder) {
+	return /* @__PURE__ */ new Error(`${PREFIX}the layer "${folder}" is not a folder name.\n` + String.raw`  Use a name without "/", "\" or ".".`);
+}
+/**
+* Lists every string file of a game: features sorted, then the layers sorted by folder; inside
+* each, locales sorted. Every layer folder is checked before anything is read.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param features - Name of the folder that holds the features.
+* @param layers - Folder under the root to the name its keys take. Default `{}`: features only.
 * @returns The files, in walk order.
+* @throws {Error} When a layer folder is empty or holds "/", "\" or ".".
 */
-async function listStringFiles(root, features) {
+async function listStringFiles(root, features, layers = {}) {
+	const sortedLayers = Object.entries(layers).toSorted((left, right) => left[0] < right[0] ? -1 : 1);
+	const outside = sortedLayers.find(([folder]) => folder === "" || NOT_ONE_FOLDER.test(folder));
+	if (outside !== void 0) throw notAFolderName(outside[0]);
 	const files = [];
 	const featuresFolder = path.join(root, features);
-	for (const feature of await listFolders(featuresFolder)) {
-		const stringsFolder = path.join(featuresFolder, feature, "strings");
-		for (const locale of await listLocales(stringsFolder)) files.push({
-			feature,
-			locale,
-			file: path.join(stringsFolder, `${locale}.json`),
-			relative: `features/${feature}/strings/${locale}.json`
-		});
-	}
+	const featuresPath = features.split(path.sep).join("/");
+	for (const feature of await listFolders(featuresFolder)) files.push(...await listOwnerFiles(root, feature, `${featuresPath}/${feature}`));
+	for (const [folder, name] of sortedLayers) files.push(...await listOwnerFiles(root, name, folder));
 	return files;
 }
 /**
@@ -6501,12 +6717,13 @@ async function readTable(file, relative, walk) {
 	}
 }
 /**
-* Records which feature owns a key, refusing the same key in two features.
+* Records which feature or layer owns a key, refusing the same key in two folders. Folders are
+* compared, not labels: a layer mapped to `ui` and the feature folder `features/ui` are two owners.
 *
 * @param walk - What the walk collects.
 * @param key - The message key.
 * @param source - Where this message came from.
-* @returns True when the key belongs to this feature.
+* @returns True when the key belongs to this folder.
 */
 function claim(walk, key, source) {
 	const known = walk.owner.get(key);
@@ -6514,7 +6731,7 @@ function claim(walk, key, source) {
 		walk.owner.set(key, source);
 		return true;
 	}
-	if (known.feature === source.feature) return true;
+	if (known.folder === source.folder) return true;
 	walk.problems.push(`the key "${key}" is in ${known.relative} and ${source.relative}.`);
 	return false;
 }
@@ -6608,15 +6825,17 @@ function compileOne(walk, key, value, source) {
 	}
 }
 /**
-* Walks every string file of a game and compiles every message once. Problems are collected, not
-* thrown, so the caller reports them all in one error.
+* Walks every string file of a game, features first and then the layers, and compiles every
+* message once. Problems are collected, not thrown, so the caller reports them all in one error.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param features - Name of the folder that holds the features.
+* @param layers - Folder under the root to the name its keys take. Default `{}`: features only.
 * @returns The compiled messages per locale, the owner and parameters of each key, the texts and
 *   notes of each key per locale, and every problem.
+* @throws {Error} When a layer folder is empty or holds "/", "\" or ".": nothing is read.
 */
-async function walkStrings(root, features) {
+async function walkStrings(root, features, layers = {}) {
 	const walk = {
 		byLocale: emptyLocales(),
 		owner: emptyOwners(),
@@ -6625,11 +6844,12 @@ async function walkStrings(root, features) {
 		texts: emptyTexts(),
 		notes: emptyTexts()
 	};
-	for (const file of await listStringFiles(root, features)) {
+	for (const file of await listStringFiles(root, features, layers)) {
 		const table = await readTable(file.file, file.relative, walk);
 		if (table === void 0) continue;
 		const source = {
 			feature: file.feature,
+			folder: file.folder,
 			locale: file.locale,
 			relative: file.relative
 		};
@@ -6641,10 +6861,10 @@ async function walkStrings(root, features) {
 //#region src/plugins/i18n/compile/compile.ts
 /**
 * @file i18n plugin, build time — `compileStrings`: the walk over `features/*​/strings/<locale>.json`
-* turned into the generated modules, and on request the pseudo-locale `en-XA` derived from English.
-* Every problem of a run is collected and reported in one error, so a game fixes its messages in
-* one round. Node and Bun only: nothing under `src/` outside this folder and `src/assets.ts`
-* imports it, so no game bundles the ICU parser.
+* and the `strings/` of every layer turned into the generated modules, and on request the
+* pseudo-locale `en-XA` derived from English. Every problem of a run is collected and reported in
+* one error, so a game fixes its messages in one round. Node and Bun only: nothing under `src/`
+* outside this folder and `src/assets.ts` imports it, so no game bundles the ICU parser.
 */
 /** The locale the pseudo-locale is derived from. */
 const PSEUDO_SOURCE = "en";
@@ -6659,15 +6879,16 @@ function pseudoNeedsEnglish() {
 	return /* @__PURE__ */ new Error(`${PREFIX}"--pseudo" needs an "en" string file in at least one feature.\n  Add features/<feature>/strings/en.json or drop "--pseudo".`);
 }
 /**
-* Tells whether at least one feature brings a string file for a locale.
+* Tells whether at least one feature or layer brings a string file for a locale.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param features - Name of the folder that holds the features.
+* @param layers - Folder under the root to the name its keys take.
 * @param locale - The locale to look for.
-* @returns True when a feature has `strings/<locale>.json`.
+* @returns True when a feature or a layer has `strings/<locale>.json`.
 */
-async function bringsLocale(root, features, locale) {
-	return (await listStringFiles(root, features)).some((file) => file.locale === locale);
+async function bringsLocale(root, features, layers, locale) {
+	return (await listStringFiles(root, features, layers)).some((file) => file.locale === locale);
 }
 /**
 * Derives the pseudo message of every English message. Each one compiled already in the walk, so
@@ -6712,7 +6933,7 @@ function missingNotes(walk, locales) {
 	const notes = [];
 	for (const [key, source] of [...walk.owner].toSorted((left, right) => left[0] < right[0] ? -1 : 1)) for (const locale of locales) {
 		if ((walk.byLocale.get(locale) ?? []).some((entry) => entry.key === key)) continue;
-		notes.push(`the key "${key}" is missing from features/${source.feature}/strings/${locale}.json.`);
+		notes.push(`the key "${key}" is missing from ${source.folder}/strings/${locale}.json.`);
 	}
 	return notes;
 }
@@ -6735,30 +6956,37 @@ function typeEntries(walk) {
 	return entries;
 }
 /**
-* Walks `features/*​/strings/<locale>.json` of a game, compiles every message and writes the
-* generated modules: the types module `strings.ts` and one `strings.<locale>.ts` per locale, plus
-* `strings.en-XA.ts` with `pseudo`. A check run writes nothing and only reports whether something
-* would change; it checks `strings.en-XA.ts` only with `pseudo`.
+* Walks `features/*​/strings/<locale>.json` of a game and the `strings/` of every layer, compiles
+* every message and writes the generated modules: the types module `strings.ts` and one
+* `strings.<locale>.ts` per locale, plus `strings.en-XA.ts` with `pseudo`. A check run writes
+* nothing and only reports whether something would change; it checks `strings.en-XA.ts` only with
+* `pseudo`.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param out - The generated directory the modules are written into.
-* @param options - Whether this is a check run, what the features folder is called, and whether
-*   the pseudo-locale is written.
+* @param options - Whether this is a check run, what the features folder is called, whether the
+*   pseudo-locale is written, and the layers.
 * @returns Whether an output differed, the locales, the keys and the notes.
-* @throws {Error} One error that lists every problem the compile found, or the pseudo error when
-*   no feature brings an `en` string file.
+* @throws {Error} One error that lists every problem the compile found, the pseudo error when
+*   no feature or layer brings an `en` string file, or the layer error when a layer folder is not
+*   one folder name: nothing is read then.
 * @example
 * ```ts
 * // A dev build also writes the pseudo-locale, derived from the English messages.
 * const report = await compileStrings("src", "src/generated", { pseudo: true });
 * // report.locales: ["en", "en-XA", "ru"], report.changed: true on the first run
+* // A v15 game: features/board/strings/en.json { "board.full": "Full" } and the layer file
+* // shared/strings/en.json { "ui.ok": "OK" } compile together.
+* const layered = await compileStrings("src", "src/generated", { layers: { shared: "ui" } });
+* // layered.keys: ["board.full", "ui.ok"]
 * ```
 */
 async function compileStrings(root, out, options = {}) {
 	const features = options.features ?? "features";
+	const layers = options.layers ?? {};
 	const pseudo = options.pseudo === true;
-	if (pseudo && !await bringsLocale(root, features, PSEUDO_SOURCE)) throw pseudoNeedsEnglish();
-	const walk = await walkStrings(root, features);
+	if (pseudo && !await bringsLocale(root, features, layers, PSEUDO_SOURCE)) throw pseudoNeedsEnglish();
+	const walk = await walkStrings(root, features, layers);
 	if (walk.problems.length > 0) throw compileFailure(walk.problems);
 	const brought = [...walk.byLocale.keys()].toSorted();
 	const keys = [...walk.owner.keys()].toSorted();
@@ -6789,7 +7017,8 @@ async function compileStrings(root, out, options = {}) {
 }
 /**
 * Tells whether the generated modules of a game are current, without writing anything. The
-* `--check` run of `bun run assets:keys` covers the strings with it.
+* `--check` run of `bun run assets:keys` covers the strings with it. It walks the features only: a
+* game with layers checks through `runCli` with `--check --layer …`.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param out - The generated directory the modules live in.
@@ -6808,8 +7037,8 @@ async function checkStrings(root, out) {
 /**
 * @file i18n plugin, build time — the exchange with translators. `exportStrings` writes one JSON
 * file per locale with every key, the source text and the note beside it; `importStrings` checks
-* the translated files against the game, writes them into the string files of the features that
-* own the keys, and compiles. Node and Bun only, reached through `src/assets.ts`.
+* the translated files against the game, writes them into the string files of the features and
+* layers that own the keys, and compiles. Node and Bun only, reached through `src/assets.ts`.
 */
 /** The locale translators read from when none is named. */
 const DEFAULT_SOURCE = "en";
@@ -6858,11 +7087,13 @@ function importFailure(problems) {
 *
 * @param root - Game source root, the folder that holds the features.
 * @param features - Name of the folder that holds the features.
+* @param layers - Folder under the root to the name its keys take.
 * @returns What the walk collected.
-* @throws {Error} One error that lists every problem the compile found.
+* @throws {Error} One error that lists every problem the compile found, or the layer error when a
+*   layer folder is not one folder name.
 */
-async function readGame(root, features) {
-	const walk = await walkStrings(root, features);
+async function readGame(root, features, layers) {
+	const walk = await walkStrings(root, features, layers);
 	if (walk.problems.length > 0) throw compileFailure(walk.problems);
 	return walk;
 }
@@ -6890,16 +7121,17 @@ function exchangeEntry(walk, key, locale, source) {
 	};
 }
 /**
-* Writes the files translators work in: one `<dir>/<locale>.json` per locale the features bring,
-* the source locale included, so a new language starts as a copy of `en.json`. Every key of the
-* game is in every file, sorted: `{ text, source, note? }`, with `text: ""` where the locale has no
-* message yet. The game tree is not touched, and a second run writes the same bytes.
+* Writes the files translators work in: one `<dir>/<locale>.json` per locale the features and
+* layers bring, the source locale included, so a new language starts as a copy of `en.json`. Every
+* key of the game is in every file, sorted: `{ text, source, note? }`, with `text: ""` where the
+* locale has no message yet. The game tree is not touched, and a second run writes the same bytes.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param dir - The folder the exchange files are written into; created when missing.
-* @param options - The source locale and the name of the features folder.
+* @param options - The source locale, the name of the features folder and the layers.
 * @returns The exported locales and how many keys each one lacks.
-* @throws {Error} When the game's strings do not compile, or no feature brings the source locale.
+* @throws {Error} When the game's strings do not compile, a layer folder is not one folder name,
+*   or no feature brings the source locale.
 * @example
 * ```ts
 * // Before a release, the game hands its strings to the translators.
@@ -6909,7 +7141,7 @@ function exchangeEntry(walk, key, locale, source) {
 */
 async function exportStrings(root, dir, options = {}) {
 	const source = options.source ?? DEFAULT_SOURCE;
-	const walk = await readGame(root, options.features ?? DEFAULT_FEATURES);
+	const walk = await readGame(root, options.features ?? DEFAULT_FEATURES, options.layers ?? {});
 	const locales = [...walk.byLocale.keys()].toSorted();
 	if (!locales.includes(source)) throw sourceMissing(source);
 	const keys = [...walk.owner.keys()].toSorted();
@@ -7007,7 +7239,7 @@ function reviewEntry(walk, review, exchange, key) {
 	try {
 		compileMessage(text);
 		review.changes.push({
-			feature: owner.feature,
+			folder: owner.folder,
 			locale: exchange.locale,
 			key,
 			text
@@ -7076,19 +7308,20 @@ async function rewriteStrings(file, texts) {
 	await writeFile(file, jsonText(table));
 }
 /**
-* Groups the changes of an import by the string file they land in.
+* Groups the changes of an import by the string file they land in: the `strings/` of the feature
+* or layer folder that owns each key.
 *
 * @param changes - Every text the import writes.
-* @param folder - Path of the folder that holds the features.
-* @returns The path and the new texts of each file, by its path relative to the root.
+* @param root - Game source root.
+* @returns The path and the new texts of each file, by its POSIX path relative to the root.
 */
-function groupByFile(changes, folder) {
+function groupByFile(changes, root) {
 	const files = /* @__PURE__ */ new Map();
 	for (const change of changes) {
 		const name = `${change.locale}${JSON_EXTENSION}`;
-		const relative = `features/${change.feature}/strings/${name}`;
+		const relative = `${change.folder}/strings/${name}`;
 		const group = files.get(relative) ?? {
-			file: path.join(folder, change.feature, "strings", name),
+			file: path.join(root, ...change.folder.split("/"), "strings", name),
 			texts: /* @__PURE__ */ new Map()
 		};
 		group.texts.set(change.key, change.text);
@@ -7098,32 +7331,39 @@ function groupByFile(changes, folder) {
 }
 /**
 * Takes translated exchange files back into the game: every `<dir>/<locale>.json` is checked
-* against the game first, then each new text is written into the string file of the feature that
-* owns its key, and the strings are compiled into `out` as a dev run does. An empty text and a
-* text equal to the current message are skipped. With any problem nothing is written.
+* against the game first, then each new text is written into the string file of the feature or
+* layer that owns its key, and the strings are compiled into `out` as a dev run does. An empty text
+* and a text equal to the current message are skipped. With any problem nothing is written.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param dir - The folder the translators handed back.
-* @param options - The features folder, where the compile writes, and whether it writes `en-XA`.
+* @param options - The features folder, the layers, where the compile writes, and whether it
+*   writes `en-XA`.
 * @returns The locales read, how many keys were written and the files rewritten.
-* @throws {Error} One error that lists every problem of the exchange files, or the compile's own
-*   error after the files are written (a parameter kind that differs across locales).
+* @throws {Error} One error that lists every problem of the exchange files, the layer error
+*   before anything is read when a layer folder is not one folder name, or the compile's own error
+*   after the files are written (a parameter kind that differs across locales).
 * @example
 * ```ts
 * // The translators handed back translations/ru.json with two hud texts filled in.
 * await importStrings("src", "translations", { out: "src/generated" });
 * // { locales: ["ru"], keys: 2, files: ["features/hud/strings/ru.json"] }
+* // A v15 game: the translated ui.ok lands in the layer's own file.
+* await importStrings("src", "translations", { out: "src/generated", layers: { shared: "ui" } });
+* // { locales: ["ru"], keys: 1, files: ["shared/strings/ru.json"] }
 * ```
 */
 async function importStrings(root, dir, options = {}) {
 	const features = options.features ?? DEFAULT_FEATURES;
-	const review = await reviewImport(await readGame(root, features), dir);
+	const layers = options.layers ?? {};
+	const review = await reviewImport(await readGame(root, features, layers), dir);
 	if (review.problems.length > 0) throw importFailure(review.problems);
-	const byFile = groupByFile(review.changes, path.join(root, features));
+	const byFile = groupByFile(review.changes, root);
 	for (const group of byFile.values()) await rewriteStrings(group.file, group.texts);
 	await compileStrings(root, options.out ?? path.join(root, "generated"), {
 		features,
-		pseudo: options.pseudo === true
+		pseudo: options.pseudo === true,
+		layers
 	});
 	return {
 		locales: review.locales.toSorted(),