@moku-labs/game 0.14.11 → 0.14.13

package/dist/{assets-BrKSg1O6.mjs → assets-CEMfBogh.mjs}

@@ -1,9 +1,10 @@
+import { t as findFeatureOwners } from "./features-DowEilZm.mjs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { createBrandConsole } from "@moku-labs/common/cli";
 import { pathToFileURL } from "node:url";
-import { mkdir, open, readFile, readdir, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
+import { mkdir, open, readFile, readdir, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import { MaxRectsBin, MaxRectsPacker } from "maxrects-packer";
 /** Bytes per pixel of the decoded images: RGBA, 8 bits each. */
 const CHANNELS = 4;
@@ -334,7 +335,7 @@ function byName$2(left, right) {
 }
 /**
 * Writes one file entry in the field order of the manifest: `key`, `path`, `kind`, `width`,
-* `height`, `mb`, `pages`, `nine`, `atlas`. A field the file does not carry is left out: a
+* `height`, `mb`, `mips`, `pages`, `nine`, `atlas`. A field the file does not carry is left out: a
 * texture says nothing about its kind, which keeps a manifest written before fonts and audio
 * readable, and a texture packed in an atlas has no `path`. A font and a sound carry no size.
 *
@@ -357,6 +358,7 @@ function plainFile(file) {
 		width: file.width,
 		height: file.height,
 		mb: file.mb,
+		...file.mips === true ? { mips: true } : {},
 		...file.nine === void 0 ? {} : { nine: file.nine },
 		...file.atlas === void 0 ? {} : { atlas: { ...file.atlas } }
 	};
@@ -377,8 +379,9 @@ function plainPage(page) {
 	};
 }
 /**
-* Writes one bundle with a fixed field order, its pages sorted by id when it has any and its
-* files sorted by key.
+* Writes one bundle with a fixed field order (`feature`, `parent`, `dir`, `tier`, `release`, `mb`,
+* `pages`, `files`), its pages sorted by id when it has any and its files sorted by key. A field
+* the bundle does not carry is left out, so the bundle of a flat feature keeps its old bytes.
 *
 * @param bundle - The bundle.
 * @returns The bundle as JSON data.
@@ -387,7 +390,10 @@ function plainBundle(bundle) {
 	const pages = bundle.pages?.toSorted((left, right) => byName$2(left.id, right.id)).map((page) => plainPage(page));
 	return {
 		feature: bundle.feature,
+		...bundle.parent === void 0 ? {} : { parent: bundle.parent },
+		...bundle.dir === void 0 ? {} : { dir: bundle.dir },
 		tier: bundle.tier,
+		...bundle.release === void 0 ? {} : { release: bundle.release },
 		mb: bundle.mb,
 		...pages === void 0 ? {} : { pages },
 		files: bundle.files.toSorted((left, right) => byName$2(left.key, right.key)).map((file) => plainFile(file))
@@ -646,19 +652,50 @@ function readImageSize(head, file) {
 	throw problem$5(`"${file}" is not a PNG or a WebP file.`);
 }
 /**
-* Estimates what one image costs on the GPU: four bytes per pixel, no mipmaps, rounded to three
-* decimals so two scans of the same tree write the same bytes.
+* Counts the pixels of an image on the GPU: one level, or with `mips` every level of the full
+* chain Pixi builds once `autoGenerateMipmaps` is set (`floor(log2(max(width, height))) + 1`
+* levels, each side halved and floored, never below 1 px).
 *
 * @param width - Width in pixels.
 * @param height - Height in pixels.
+* @param mips - True for the full mip chain.
+* @returns The pixels of every level.
+* @example
+* ```ts
+* chainPixels(4, 4, true); // 21: 16 + 4 + 1
+* ```
+*/
+function chainPixels(width, height, mips) {
+	if (!mips) return width * height;
+	const levels = Math.floor(Math.log2(Math.max(width, height))) + 1;
+	let pixels = 0;
+	let levelWidth = width;
+	let levelHeight = height;
+	for (let level = 0; level < levels; level += 1) {
+		pixels += levelWidth * levelHeight;
+		levelWidth = Math.max(1, Math.floor(levelWidth / 2));
+		levelHeight = Math.max(1, Math.floor(levelHeight / 2));
+	}
+	return pixels;
+}
+/**
+* Estimates what one image costs on the GPU: four bytes per pixel, every level of the mip chain
+* with `mips`, rounded to three decimals so two scans of the same tree write the same bytes. Its
+* twin is `textureMb` of `manifest.ts`, which the plugin reads: a change edits both.
+*
+* @param width - Width in pixels.
+* @param height - Height in pixels.
+* @param mips - True for a texture uploaded with its full mip chain.
 * @returns The estimated texture memory in MB.
 * @example
 * ```ts
 * textureMb(256, 128); // 0.125
+* textureMb(256, 128, true); // 0.167
 * ```
 */
-function textureMb(width, height) {
-	return Math.round(width * height * BYTES_PER_PIXEL / BYTES_PER_MB * 1e3) / 1e3;
+function textureMb(width, height, mips = false) {
+	const bytes = chainPixels(width, height, mips) * BYTES_PER_PIXEL;
+	return Math.round(bytes / BYTES_PER_MB * 1e3) / 1e3;
 }
 /**
 * What a file costs in memory when it is kept as it is: an audio file is held undecoded, so its
@@ -1064,21 +1101,24 @@ const FX_FOLDER = "fx";
 /** The groups in the order a bundle packs them. */
 const GROUP_ORDER = ["fx", "main"];
 /**
-* Picks the atlas group of one texture. A key whose last segment starts with `fx-`, or with a
-* folder segment `fx` between the bundle name and the stem, goes to `fx` whatever its size: the
-* frames of an animation in `fx/` too. Any other texture goes to `main` when no side is above
-* 512 px.
+* Picks the atlas group of one texture. A mipmapped texture stays loose whatever its key: Pixi
+* builds its full chain, and from the second level on the neighbours on a page would bleed into
+* it. A key whose last segment starts with `fx-`, or with a folder segment `fx` between the bundle
+* name and the stem, goes to `fx` whatever its size: the frames of an animation in `fx/` too. Any
+* other texture goes to `main` when no side is above 512 px.
 *
-* @param texture - The key and the size of the texture.
-* @returns The group, or `undefined` when the texture stays loose by its size.
+* @param texture - The key, the size and the mipmaps of the texture.
+* @returns The group, or `undefined` when the texture stays loose.
 * @example
 * ```ts
 * groupOf({ key: "ui.fx-rays", width: 504, height: 512 }); // "fx"
 * groupOf({ key: "ui.fx.leaf", width: 64, height: 64 }); // "fx", from assets/fx/leaf.webp of ui
 * groupOf({ key: "ui.fx", width: 64, height: 64 }); // "main": a stem, no folder
+* groupOf({ key: "ep01.items.cup", width: 336, height: 288, mips: true }); // undefined: loose
 * ```
 */
 function groupOf(texture) {
+	if (texture.mips === true) return void 0;
 	const segments = texture.key.split(".");
 	const name = segments.at(-1) ?? "";
 	const folders = segments.slice(1, -1);
@@ -1222,6 +1262,7 @@ async function readTextures(run, bundle) {
 				key: file.key,
 				width: file.width,
 				height: file.height,
+				...file.mips === true ? { mips: true } : {},
 				file,
 				bytes,
 				sha: sha256(bytes)
@@ -1474,7 +1515,10 @@ async function packBundle(run, name, bundle) {
 	const mb = sumMb$1([...packed.pages, ...files.filter((file) => file.atlas === void 0)]);
 	return {
 		feature: bundle.feature,
+		...bundle.parent === void 0 ? {} : { parent: bundle.parent },
+		...bundle.dir === void 0 ? {} : { dir: bundle.dir },
 		tier: bundle.tier,
+		...bundle.release === void 0 ? {} : { release: bundle.release },
 		mb,
 		...packed.pages.length === 0 ? {} : { pages: packed.pages.toSorted((left, right) => left.id.localeCompare(right.id)) },
 		files: files.toSorted((left, right) => left.key.localeCompare(right.key))
@@ -1493,6 +1537,7 @@ function checkTexture(bundle, entry, file, source) {
 	const atlas = file.atlas;
 	if (atlas === void 0 === (file.path === void 0)) return [`the texture "${file.key}" must have either a path or an atlas frame.`];
 	if (atlas === void 0) return [];
+	if (file.mips === true) return [`the texture "${file.key}" has mipmaps, so it must stay loose, but lies on page "${atlas.page}".`];
 	const page = entry.pages?.find((candidate) => candidate.id === atlas.page);
 	if (page === void 0) return [`the texture "${file.key}" names page "${atlas.page}", which bundle "${bundle}" does not list.`];
 	const problems = [];
@@ -1503,7 +1548,7 @@ function checkTexture(bundle, entry, file, source) {
 /**
 * Checks a packed manifest against the scan it came from: every key landed exactly once, as a
 * page frame or a file; every frame names a page of its own bundle, lies inside it and has the
-* size of its source, so `nine` stays valid as it is.
+* size of its source, so `nine` stays valid as it is; a mipmapped texture is never a frame.
 *
 * @param source - The manifest of the scan.
 * @param packed - The packed manifest.
@@ -1903,10 +1948,11 @@ 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, 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.
+* @file assets plugin, build time — the walk. Every feature owner (a folder of `features/`, and a
+* sub-feature with a door and resources of its own at any depth, found by `findFeatureOwners`), and
+* every layer the options map (a folder under the root read like one more feature), becomes the
+* manifest: one bundle per owner 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",
@@ -1915,6 +1961,8 @@ const TIERS = [
 	"feature",
 	"lazy"
 ];
+/** The name of the folder of an owner the scanner reads. */
+const ASSETS = "assets";
 const PREFIX$1 = "[game] assets: ";
 const ESCAPE = /[.+^${}()|[\]\\]/g;
 /**
@@ -1950,13 +1998,11 @@ function detailOf$2(failure) {
 * built inside an exported declaration.
 *
 * @param root - Absolute or relative path of the game source root.
-* @param features - Name of the features folder.
 * @returns The empty state.
 */
-function createState(root, features) {
+function createState(root) {
 	return {
 		root,
-		featuresFolder: path.join(root, features),
 		drafts: /* @__PURE__ */ new Map(),
 		keyOwner: /* @__PURE__ */ new Map(),
 		problems: [],
@@ -1983,13 +2029,37 @@ function byName$1(left, right) {
 	return left.localeCompare(right);
 }
 /**
-* Lists the feature folders, sorted. A missing features folder is an empty game, not a problem.
+* Reads the feature owners of the game, at any depth, in the order `findFeatureOwners` returns
+* them. A missing features folder is an empty game, not a problem. One name taken by two folders
+* is one problem of the scan, and the walk goes on with no feature owner, so the layer refusals
+* are still collected and the scan fails with every problem at once.
+*
+* @param scan - State of the scan.
+* @param features - Name of the features folder.
+* @returns The owners, each with its folder on disk.
+*/
+function readOwners(scan, features) {
+	try {
+		return findFeatureOwners(scan.root, features).map((owner) => ({
+			name: owner.name,
+			dir: path.join(scan.root, ...owner.dir.split("/")),
+			folder: owner.dir,
+			parent: owner.parent,
+			resources: { ...owner.resources }
+		}));
+	} catch (error) {
+		scan.problems.push(detailOf$2(error));
+		return [];
+	}
+}
+/**
+* Tells whether a path is a file.
 *
-* @param dir - The features folder.
-* @returns The folder names.
+* @param file - The path to look at.
+* @returns True for a file; false for a folder or nothing.
 */
-async function listFeatures(dir) {
-	return (await readdir(dir, { withFileTypes: true }).catch(() => [])).filter((entry) => entry.isDirectory()).map((entry) => entry.name).toSorted(byName$1);
+async function isFile(file) {
+	return await stat(file).then((entry) => entry.isFile(), () => false);
 }
 /**
 * Tells whether a path is a folder.
@@ -2042,7 +2112,7 @@ function nameTakenRefusal(first, folder, name) {
 *
 * @param layers - Folder to name.
 * @param features - Name of the features folder.
-* @param featureNames - The feature folders found under it.
+* @param featureNames - Every feature owner name, at any depth.
 * @returns Every layer with its refusal, in the order of the sorted folders.
 */
 function checkLayers(layers, features, featureNames) {
@@ -2118,10 +2188,66 @@ async function importDescription(file) {
 );
 }
 /**
-* Reads one declared bundle into the specs of its feature.
+* Says why the release of a declared bundle is refused: a value that is neither `"budget"` nor
+* `"leave"`, or `"leave"` on a tier that stays for the whole session.
+*
+* @param name - Name of the bundle.
+* @param tier - Its tier, already checked.
+* @param release - What the description carried as `release`.
+* @returns The problem, or `undefined` when the release is fine.
+* @example
+* ```ts
+* releaseProblem("ep01", "lazy", "later");
+* // 'the bundle "ep01" has the unknown release "later". Use budget or leave.'
+* ```
+*/
+function releaseProblem(name, tier, release) {
+	if (release !== void 0 && release !== "budget" && release !== "leave") return `the bundle "${name}" has the unknown release "${String(release)}". Use budget or leave.`;
+	if (release !== "leave" || tier !== "boot" && tier !== "core") return void 0;
+	return `the bundle "${name}" is tier "${tier}", which stays for the whole session: release "leave" needs scene, feature or lazy.`;
+}
+/**
+* Tells whether a `mipmaps` value is one the scanner reads: absent, `false`, `true` or a list of
+* globs. `false` and `[]` are read as absent: a JavaScript or a cast description may carry them.
+*
+* @param mipmaps - What the description carried as `mipmaps`.
+* @returns True when the value can be read.
+* @example
+* ```ts
+* isMipmapsValue("items/**"); // false: a glob needs a list
+* ```
+*/
+function isMipmapsValue(mipmaps) {
+	if (mipmaps === void 0 || typeof mipmaps === "boolean") return true;
+	return Array.isArray(mipmaps) && mipmaps.every((glob) => typeof glob === "string");
+}
+/**
+* Builds the stored spec of a declared bundle: `release` only when it is `"leave"`, `mipmaps`
+* only when it is `true` or a non-empty list (copied).
+*
+* @param tier - The checked tier.
+* @param raw - The checked description of the bundle.
+* @returns The spec.
+*/
+function specOf(tier, raw) {
+	const files = Array.isArray(raw.files) ? raw.files.map(String) : void 0;
+	const mipmaps = raw.mipmaps;
+	const globs = Array.isArray(mipmaps) && mipmaps.length > 0 ? mipmaps.map(String) : void 0;
+	return {
+		tier,
+		...files === void 0 ? {} : { files },
+		...raw.release === "leave" ? { release: "leave" } : {},
+		...mipmaps === true ? { mipmaps: true } : {},
+		...globs === void 0 ? {} : { mipmaps: globs }
+	};
+}
+/**
+* Reads one declared bundle into the specs of its feature: the bundle-name rule against the owner,
+* the tier, the release and the mipmaps. Each failure is one problem, and the bundle is then not
+* recorded.
 *
 * @param scan - State of the scan.
-* @param feature - Name of the feature.
+* @param feature - Name of the feature: the inner folder name, or the mapped name of a layer.
 * @param name - Name of the bundle.
 * @param raw - What the description carried under that name.
 * @param specs - Where a valid bundle goes.
@@ -2132,15 +2258,20 @@ function readSpec(scan, feature, name, raw, specs) {
 		return;
 	}
 	const tier = isRecord(raw) ? raw.tier : void 0;
-	if (typeof tier !== "string" || !TIERS.includes(tier)) {
+	if (!isRecord(raw) || typeof tier !== "string" || !TIERS.includes(tier)) {
 		scan.problems.push(`the bundle "${name}" has the unknown tier "${String(tier)}". Use one of ${TIERS.join(", ")}.`);
 		return;
 	}
-	const files = isRecord(raw) && Array.isArray(raw.files) ? raw.files.map(String) : void 0;
-	specs.set(name, files === void 0 ? { tier } : {
-		tier,
-		files
-	});
+	const refusal = releaseProblem(name, tier, raw.release);
+	if (refusal !== void 0) {
+		scan.problems.push(refusal);
+		return;
+	}
+	if (!isMipmapsValue(raw.mipmaps)) {
+		scan.problems.push(`the bundle "${name}" has mipmaps ${JSON.stringify(raw.mipmaps)}: use true or a list of globs relative to assets/.`);
+		return;
+	}
+	specs.set(name, specOf(tier, raw));
 }
 /**
 * Reads the bundles a feature or a layer declares. Every export that is a `defineBundles` result
@@ -2213,6 +2344,61 @@ function splitsOf(specs) {
 	return splits;
 }
 /**
+* Builds the mipmaps rules of the declared bundles, sorted by bundle name.
+*
+* @param specs - The declared bundles of one owner.
+* @returns Bundle name to its rule, for every bundle that declares mipmaps.
+*/
+function mipRulesOf(specs) {
+	const rules = /* @__PURE__ */ new Map();
+	for (const [name, spec] of [...specs].toSorted((left, right) => byName$1(left[0], right[0]))) {
+		const mipmaps = spec.mipmaps;
+		if (mipmaps === true) rules.set(name, { all: true });
+		else if (mipmaps !== void 0) rules.set(name, { globs: mipmaps.map((glob) => ({
+			glob,
+			pattern: globToRegExp(glob)
+		})) });
+	}
+	return rules;
+}
+/**
+* Tells whether a texture is mipmapped by the bundle that claims it, and notes every glob of that
+* bundle it matched. A glob of one bundle never marks a file of another.
+*
+* @param pass - What this owner is read with.
+* @param bundle - The bundle that claims the texture.
+* @param relative - POSIX path of the texture inside `assets/`.
+* @returns True when the texture carries mipmaps.
+*/
+function wantsMips(pass, bundle, relative) {
+	const rule = pass.mips.get(bundle);
+	if (rule === void 0) return false;
+	if ("all" in rule) return true;
+	let wanted = false;
+	for (const { glob, pattern } of rule.globs) {
+		if (!pattern.test(relative)) continue;
+		pass.matched.add(`${bundle}\n${glob}`);
+		wanted = true;
+	}
+	return wanted;
+}
+/**
+* Notes every mipmaps glob of an owner that matched no texture of its bundle: a typo would
+* otherwise leave the art without its chain in silence.
+*
+* @param scan - State of the scan.
+* @param pass - What the owner was read with, after its files.
+*/
+function noteUnmatchedGlobs(scan, pass) {
+	for (const [bundle, rule] of pass.mips) {
+		if ("all" in rule) continue;
+		for (const { glob } of rule.globs) {
+			if (pass.matched.has(`${bundle}\n${glob}`)) continue;
+			scan.notes.push(`the mipmaps glob "${glob}" of the bundle "${bundle}" matches no texture of it.`);
+		}
+	}
+}
+/**
 * Works out which declared bundle claims a file.
 *
 * @param splits - The splits of the feature.
@@ -2245,20 +2431,24 @@ function checkNine(nine, size, file) {
 	throw problem$2(`the nine-slice ${left === top && top === right && right === bottom ? `${left} of "${file}" must be smaller than half of` : `${left},${top},${right},${bottom} of "${file}" must leave a centre inside`} ${size.width}×${size.height}.`);
 }
 /**
-* Finds or starts the draft of one bundle.
+* Finds or starts the draft of one bundle: its owner, and the tier and release its spec declares
+* (the tier `feature` and no release without one).
 *
 * @param scan - State of the scan.
 * @param name - Name of the bundle.
-* @param feature - Feature that owns it.
-* @param tier - When it loads.
+* @param owner - The feature or layer that owns it.
+* @param spec - What the owner's `assets.ts` declared for it, if anything.
 * @returns The draft.
 */
-function draftOf(scan, name, feature, tier) {
+function draftOf(scan, name, owner, spec) {
 	const found = scan.drafts.get(name);
 	if (found !== void 0) return found;
 	const draft = {
-		feature,
-		tier,
+		feature: owner.name,
+		parent: owner.parent,
+		folder: owner.folder,
+		tier: spec?.tier ?? "feature",
+		release: spec?.release === "leave" ? "leave" : void 0,
 		files: []
 	};
 	scan.drafts.set(name, draft);
@@ -2352,20 +2542,21 @@ async function describePages(scan, pass, relative) {
 	return pages;
 }
 /**
-* Reads one asset file into a manifest entry: a texture by its pixels, a font with its pages, an
-* audio file by its bytes.
+* Reads one asset file into a manifest entry: a texture by its pixels (every level of its chain
+* when it carries mipmaps), a font with its pages, an audio file by its bytes.
 *
 * @param scan - State of the scan.
 * @param pass - What this feature is read with.
 * @param relative - POSIX path of the file inside `assets/`.
+* @param bundle - The bundle that claims the file, whose mipmaps rule a texture follows.
 * @returns The entry.
 * @throws {Error} When the key, the tags, the header bytes or the nine-slice are wrong.
 */
-async function describeFile(scan, pass, relative) {
+async function describeFile(scan, pass, relative, bundle) {
 	const absolute = path.join(pass.assetsFolder, ...relative.split("/"));
 	const file = toPosix(path.relative(scan.root, absolute));
 	const fileName = relative.slice(relative.lastIndexOf("/") + 1);
-	const key = keyOf(pass.feature, relative, file);
+	const key = keyOf(pass.owner.name, relative, file);
 	const owner = scan.keyOwner.get(key);
 	if (owner !== void 0) throw problem$2(`key "${key}" comes from two files: ${owner} and ${file}.`);
 	const kind = assetKindOf(fileName);
@@ -2399,12 +2590,14 @@ async function describeFile(scan, pass, relative) {
 	const size = readImageSize(await readHead(absolute), file);
 	checkNine(nine, size, file);
 	scan.keyOwner.set(key, file);
+	const mips = wantsMips(pass, bundle, relative);
 	return {
 		key,
 		path: file,
 		width: size.width,
 		height: size.height,
-		mb: textureMb(size.width, size.height),
+		mb: textureMb(size.width, size.height, mips),
+		...mips ? { mips: true } : {},
 		...nine === void 0 ? {} : { nine }
 	};
 }
@@ -2423,39 +2616,71 @@ async function addFile(scan, pass, relative) {
 		return;
 	}
 	try {
-		const name = ownerOf(pass.splits, relative, file) ?? pass.feature;
-		const entry = await describeFile(scan, pass, relative);
-		draftOf(scan, name, pass.feature, pass.defaultTier).files.push(entry);
+		const name = ownerOf(pass.splits, relative, file) ?? pass.owner.name;
+		const entry = await describeFile(scan, pass, relative, name);
+		draftOf(scan, name, pass.owner, pass.specs.get(name)).files.push(entry);
 	} catch (error) {
 		scan.problems.push(detailOf$2(error));
 	}
 }
 /**
 * Reads one feature or layer: its description first, then its fonts, then every file of its
-* `assets/`.
+* `assets/` (never a child owner's), then the notes of its unmatched mipmaps globs. A sub-feature
+* with resources has its default bundle even with no file, so its lazy strings travel with it.
 *
 * @param scan - State of the scan.
-* @param owner - The feature or layer: its folder and the name its keys and bundles take.
+* @param owner - The feature or layer: its folders and the name its keys and bundles take.
 */
 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 assetsFolder = path.join(owner.dir, ASSETS);
+	for (const [name, spec] of specs) draftOf(scan, name, owner, spec);
+	if (owner.parent !== void 0 && (owner.resources.assets || owner.resources.strings)) draftOf(scan, owner.name, owner, specs.get(owner.name));
 	const files = await walkAssets(assetsFolder, "");
 	const fonts = await readFonts(scan, assetsFolder, files);
 	const pages = new Set([...fonts.values()].flat());
 	const pass = {
-		feature,
+		owner,
 		assetsFolder,
 		splits: splitsOf(specs),
-		defaultTier: specs.get(feature)?.tier ?? "feature",
-		fonts
+		specs,
+		fonts,
+		mips: mipRulesOf(specs),
+		matched: /* @__PURE__ */ new Set()
 	};
 	for (const relative of files) {
 		if (pages.has(relative)) continue;
 		await addFile(scan, pass, relative);
 	}
+	noteUnmatchedGlobs(scan, pass);
+}
+/**
+* Tells whether a folder brings assets of its own: an `assets/` folder or an `assets.ts` file.
+*
+* @param dir - The folder on disk.
+* @returns True when it has either.
+*/
+async function hasAssets(dir) {
+	return await isFolder(path.join(dir, ASSETS)) || await isFile(path.join(dir, "assets.ts"));
+}
+/**
+* Notes every near miss: a direct child folder of a feature owner that has assets but is no owner
+* itself (it has no door), so none of its files are in the manifest. Notes never stop a build.
+*
+* @param scan - State of the scan.
+* @param owners - The feature owners, in walk order.
+*/
+async function noteStrayFolders(scan, owners) {
+	const folders = new Set(owners.map((owner) => owner.folder));
+	for (const owner of owners) {
+		const entries = await readdir(owner.dir, { withFileTypes: true }).catch(() => []);
+		for (const entry of entries.toSorted((left, right) => byName$1(left.name, right.name))) {
+			const folder = `${owner.folder}/${entry.name}`;
+			if (!entry.isDirectory() || entry.name === ASSETS || folders.has(folder)) continue;
+			if (!await hasAssets(path.join(owner.dir, entry.name))) continue;
+			scan.notes.push(`the folder "${folder}" has assets but is no feature: its files are not in the manifest. A sub-feature needs a door index.ts.`);
+		}
+	}
 }
 /**
 * Adds up what a list of files costs: the files of a bundle, or the pages of a font.
@@ -2480,7 +2705,12 @@ function toManifest(scan) {
 		const files = draft.files.toSorted((left, right) => byName$1(left.key, right.key));
 		bundles[name] = {
 			feature: draft.feature,
+			...draft.parent === void 0 ? {} : {
+				parent: draft.parent,
+				dir: draft.folder
+			},
 			tier: draft.tier,
+			...draft.release === void 0 ? {} : { release: draft.release },
 			mb: sumMb(files),
 			files
 		};
@@ -2555,19 +2785,29 @@ async function scanLayers(scan, checks) {
 		}
 		await scanOwner(scan, {
 			name,
-			dir
+			dir,
+			folder,
+			parent: void 0,
+			resources: {
+				assets: true,
+				strings: false
+			}
 		});
 	}
 }
 /**
 * 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.
+* feature owner or layer, split by its optional `assets.ts`, every file keyed by the key rule. A
+* sub-feature (a folder with a door and resources inside a feature, at any depth) is an owner of
+* its own: its keys and its bundle take the inner folder name, and only its bundle carries
+* `parent` and `dir`. 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 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, the layer problems first.
+* @throws {Error} One error that lists every problem the scan found, the owner and layer problems
+*   first.
 * @example
 * ```ts
 * const { manifest, changed } = await scanAssets({
@@ -2577,18 +2817,17 @@ async function scanLayers(scan, checks) {
 *   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
+* // features/episodes/ep01/assets/ward/room.png keeps the key "ep01.ward.room" in the bundle "ep01"
 * ```
 */
 async function scanAssets(options) {
 	const features = options.features ?? "features";
-	const scan = createState(options.root, features);
-	const featureNames = await listFeatures(scan.featuresFolder);
-	const checks = checkLayers(options.layers ?? {}, features, featureNames);
+	const scan = createState(options.root);
+	const owners = readOwners(scan, features);
+	const checks = checkLayers(options.layers ?? {}, features, owners.map((owner) => owner.name));
 	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)
-	});
+	for (const owner of owners) await scanOwner(scan, owner);
+	await noteStrayFolders(scan, owners);
 	await scanLayers(scan, checks);
 	if (scan.problems.length > 0) throw collected(scan.problems);
 	const manifest = toManifest(scan);
@@ -6457,16 +6696,18 @@ function pseudoMessage(elements) {
 //#endregion
 //#region src/plugins/i18n/compile/walk.ts
 /**
-* @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.
+* @file i18n plugin, build time — the walk over every feature owner of `findFeatureOwners` (a
+* top-level folder of `features/`, or a sub-feature at any depth) 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 = /[/\\.]/;
+/** What a sub-feature name may hold: it sits between two dots of `strings.<name>.<locale>.ts`. */
+const MODULE_NAME = /^[\w-]+$/;
 /**
 * Creates the table of compiled messages per locale. Its own function because lint rule L5
 * refuses a collection built inside an exported declaration.
@@ -6501,6 +6742,14 @@ function emptyTexts() {
 	return /* @__PURE__ */ new Map();
 }
 /**
+* Creates the table of the sub-features that brought string files.
+*
+* @returns An empty table.
+*/
+function emptySubFeatures() {
+	return /* @__PURE__ */ new Map();
+}
+/**
 * Creates the parameter table of one key.
 *
 * @returns An empty table.
@@ -6584,17 +6833,16 @@ function isMessageEntry(value) {
 	return isNoted(value);
 }
 /**
-* Lists the sub-folders of a folder that may not exist.
+* Compares two texts by code unit, the order `.toSorted()` gives strings.
 *
-* @param folder - Path of the folder.
-* @returns The names, sorted.
+* @param left - One text.
+* @param right - The other text.
+* @returns A negative number, zero or a positive number.
+* @example compareText("features/Board", "features/apple"); // -1
 */
-async function listFolders(folder) {
-	try {
-		return (await readdir(folder, { withFileTypes: true })).filter((entry) => entry.isDirectory()).map((entry) => entry.name).toSorted();
-	} catch {
-		return [];
-	}
+function compareText(left, right) {
+	if (left === right) return 0;
+	return left < right ? -1 : 1;
 }
 /**
 * Lists the locales one feature brought, by the names of its string files.
@@ -6614,21 +6862,39 @@ async function listLocales(folder) {
 * 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.
+* @param owner - The label (the feature folder name, or the mapped name of a layer), the
+*   root-relative POSIX folder, and the parent of a sub-feature.
 * @returns The files of that folder.
 */
-async function listOwnerFiles(root, feature, folder) {
+async function listOwnerFiles(root, owner) {
+	const folder = owner.dir;
 	const stringsFolder = path.join(root, ...folder.split("/"), "strings");
-	return (await listLocales(stringsFolder)).map((locale) => ({
-		feature,
+	const locales = await listLocales(stringsFolder);
+	const parent = owner.parent === void 0 ? {} : { parent: owner.parent };
+	return locales.map((locale) => ({
+		feature: owner.name,
 		folder,
 		locale,
 		file: path.join(stringsFolder, `${locale}.json`),
-		relative: `${folder}/strings/${locale}.json`
+		relative: `${folder}/strings/${locale}.json`,
+		...parent
 	}));
 }
 /**
+* The owner record of a layer: no parent, so its keys take no prefix.
+*
+* @param folder - The layer folder under the root.
+* @param name - The name its keys take.
+* @returns The record `listOwnerFiles` reads.
+* @example layerOwner("shared", "ui"); // { name: "ui", dir: "shared" }
+*/
+function layerOwner(folder, name) {
+	return {
+		name,
+		dir: folder
+	};
+}
+/**
 * 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.
 *
@@ -6639,24 +6905,25 @@ 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.
+* Lists every string file of a game: the feature owners of `findFeatureOwners` (top-level features
+* and sub-features at any depth) sorted by folder in code-unit order, 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 ".".
+* @throws {Error} When a layer folder is empty or holds "/", "\" or ".", or when one feature name
+*   belongs to two folders (the error of `findFeatureOwners`): nothing is read then.
 */
 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);
-	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));
+	const owners = [...findFeatureOwners(root, features)].toSorted((left, right) => compareText(left.dir, right.dir));
+	for (const owner of owners) files.push(...await listOwnerFiles(root, owner));
+	for (const [folder, name] of sortedLayers) files.push(...await listOwnerFiles(root, layerOwner(folder, name)));
 	return files;
 }
 /**
@@ -6759,6 +7026,31 @@ function remember(table, key, locale, text) {
 	table.set(key, byLocale);
 }
 /**
+* Tells whether a key may live in the file it came from: any key of a top-level feature or a
+* layer, and for a sub-feature a key that starts with `<name>.` and goes on after it.
+*
+* @param key - The message key.
+* @param source - Where this message came from.
+* @returns True when the key belongs there.
+*/
+function isOwnKey(key, source) {
+	if (source.parent === void 0) return true;
+	const prefix = `${source.feature}.`;
+	return key.startsWith(prefix) && key.length > prefix.length;
+}
+/**
+* Records a sub-feature that brought a string file, checking its name once: the name sits between
+* two dots of its module's file name.
+*
+* @param walk - What the walk collects.
+* @param file - One string file of the walk.
+*/
+function noteSubFeature(walk, file) {
+	if (file.parent === void 0 || walk.subFeatures.has(file.feature)) return;
+	walk.subFeatures.set(file.feature, file.folder);
+	if (!MODULE_NAME.test(file.feature)) walk.problems.push(`${file.folder}: a sub-feature name is letters, digits, "_" and "-", so generated/strings.<name>.<locale>.ts can be read back.`);
+}
+/**
 * Reads one value of a string file and compiles its message into the locale it belongs to.
 *
 * @param walk - What the walk collects.
@@ -6771,6 +7063,10 @@ function compileOne(walk, key, value, source) {
 		walk.problems.push(`"${key}" in ${source.relative}: a message is a string or { "text": string, "note": string }.`);
 		return;
 	}
+	if (!isOwnKey(key, source)) {
+		walk.problems.push(`"${key}" in ${source.relative}: a key of the sub-feature "${source.feature}" starts with "${source.feature}.".`);
+		return;
+	}
 	if (!claim(walk, key, source)) return;
 	const text = typeof value === "string" ? value : value.text;
 	remember(walk.texts, key, source.locale, text);
@@ -6789,15 +7085,17 @@ function compileOne(walk, key, value, source) {
 	}
 }
 /**
-* 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.
+* Walks every string file of a game, the feature owners first (sub-features at any depth) 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.
+* @throws {Error} When a layer folder is empty or holds "/", "\" or ".", or when one feature name
+*   belongs to two folders: nothing is read.
 */
 async function walkStrings(root, features, layers = {}) {
 	const walk = {
@@ -6806,16 +7104,19 @@ async function walkStrings(root, features, layers = {}) {
 		params: emptyParameters(),
 		problems: [],
 		texts: emptyTexts(),
-		notes: emptyTexts()
+		notes: emptyTexts(),
+		subFeatures: emptySubFeatures()
 	};
 	for (const file of await listStringFiles(root, features, layers)) {
+		noteSubFeature(walk, file);
 		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
+			relative: file.relative,
+			...file.parent === void 0 ? {} : { parent: file.parent }
 		};
 		for (const [key, value] of Object.entries(table)) compileOne(walk, key, value, source);
 	}
@@ -6824,8 +7125,9 @@ async function walkStrings(root, features, layers = {}) {
 //#endregion
 //#region src/plugins/i18n/compile/compile.ts
 /**
-* @file i18n plugin, build time — `compileStrings`: the walk over `features/*​/strings/<locale>.json`
-* and the `strings/` of every layer turned into the generated modules, and on request the
+* @file i18n plugin, build time — `compileStrings`: the walk over the `strings/` of every feature
+* owner (top-level features and sub-features at any depth) and of every layer turned into the
+* generated modules (a sub-feature's keys into a module of its own), 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.
@@ -6837,19 +7139,20 @@ const PSEUDO_LOCALE = "en-XA";
 /**
 * Wraps a pseudo run without English in the message shape of the framework.
 *
+* @param features - Name of the folder that holds the features.
 * @returns The error to reject with.
 */
-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".`);
+function pseudoNeedsEnglish(features) {
+	return /* @__PURE__ */ new Error(`${PREFIX}"--pseudo" needs an "en" string file in at least one feature.\n  Add ${features}/<feature>/strings/en.json (a sub-feature's own strings/en.json counts too) or drop "--pseudo".`);
 }
 /**
-* Tells whether at least one feature or layer brings a string file for a locale.
+* Tells whether at least one feature, sub-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 or a layer has `strings/<locale>.json`.
+* @returns True when a feature, a sub-feature or a layer has `strings/<locale>.json`.
 */
 async function bringsLocale(root, features, layers, locale) {
 	return (await listStringFiles(root, features, layers)).some((file) => file.locale === locale);
@@ -6887,6 +7190,53 @@ function localeModules(walk, pseudo) {
 	return modules;
 }
 /**
+* Splits the entries of one locale by the owner of each key: a sub-feature's keys go to its own
+* module, every other key to the whole-game module.
+*
+* @param walk - What the walk collected.
+* @param entries - The entries of one locale, the pseudo-locale included.
+* @returns The whole-game entries and the entries of each sub-feature that has some.
+*/
+function splitLocale(walk, entries) {
+	const split = {
+		game: [],
+		byFeature: /* @__PURE__ */ new Map()
+	};
+	for (const entry of entries) {
+		const owner = walk.owner.get(entry.key);
+		if (owner?.parent === void 0) {
+			split.game.push(entry);
+			continue;
+		}
+		const own = split.byFeature.get(owner.feature) ?? [];
+		own.push(entry);
+		split.byFeature.set(owner.feature, own);
+	}
+	return split;
+}
+/**
+* The locale outputs of one compile: per locale the whole-game module `strings.<locale>.ts`, then
+* for every sub-feature with string files (sorted by name) and every locale its
+* `strings.<feature>.<locale>.ts`, an empty table where it brought nothing for that locale.
+*
+* @param walk - What the walk collected.
+* @param modules - The compiled messages per locale, the pseudo-locale included.
+* @param out - The generated directory.
+* @returns The file and the text of each locale output.
+*/
+function localeOutputs(walk, modules, out) {
+	const locales = [...modules.keys()].toSorted();
+	const split = new Map(locales.map((locale) => [locale, splitLocale(walk, modules.get(locale) ?? [])]));
+	const subFeatures = [...walk.subFeatures.keys()].toSorted();
+	return [...locales.map((locale) => ({
+		file: path.join(out, `strings.${locale}.ts`),
+		text: emitLocale(split.get(locale)?.game ?? [])
+	})), ...subFeatures.flatMap((feature) => locales.map((locale) => ({
+		file: path.join(out, `strings.${feature}.${locale}.ts`),
+		text: emitLocale(split.get(locale)?.byFeature.get(feature) ?? [])
+	})))];
+}
+/**
 * Lists the keys a locale is missing, so a translator sees the gap without the build stopping.
 *
 * @param walk - What the compile collects.
@@ -6920,11 +7270,14 @@ function typeEntries(walk) {
 	return entries;
 }
 /**
-* 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`.
+* Walks the `strings/<locale>.json` of every feature of a game, sub-features at any depth
+* included, and the `strings/` of every layer, compiles every message and writes the generated
+* modules: the types module `strings.ts` with every key; one `strings.<locale>.ts` per locale with
+* the keys of the top-level features and the layers; and for every sub-feature that brings string
+* files one `strings.<feature>.<locale>.ts` per locale with its own keys (an empty table where it
+* lacks the locale). `strings.en-XA.ts` and its per-feature twins come with `pseudo`. A game
+* without sub-features writes exactly the modules 0.14.12 wrote. A check run writes nothing and
+* only reports whether something would change; it checks the `en-XA` modules only with `pseudo`.
 *
 * @param root - Game source root, the folder that holds the features.
 * @param out - The generated directory the modules are written into.
@@ -6943,13 +7296,14 @@ function typeEntries(walk) {
 * // 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"]
+* // features/episodes/ep01/strings/en.json { "ep01.title": "Ward" } also writes generated/strings.ep01.en.ts
 * ```
 */
 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, layers, PSEUDO_SOURCE)) throw pseudoNeedsEnglish();
+	if (pseudo && !await bringsLocale(root, features, layers, PSEUDO_SOURCE)) throw pseudoNeedsEnglish(features);
 	const walk = await walkStrings(root, features, layers);
 	if (walk.problems.length > 0) throw compileFailure(walk.problems);
 	const brought = [...walk.byLocale.keys()].toSorted();
@@ -6966,10 +7320,7 @@ async function compileStrings(root, out, options = {}) {
 	const outputs = [{
 		file: path.join(out, "strings.ts"),
 		text: emitTypes(typeEntries(walk))
-	}, ...locales.map((locale) => ({
-		file: path.join(out, `strings.${locale}.ts`),
-		text: emitLocale(modules.get(locale) ?? [])
-	}))];
+	}, ...localeOutputs(walk, modules, out)];
 	let changed = false;
 	for (const output of outputs) changed = await writeIfChanged(output.file, output.text, write) || changed;
 	return {
@@ -7001,8 +7352,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 and
-* layers 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,
+* sub-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";