@replayablejs/assets 0.1.0-alpha.0

package/dist/index.mjs

@@ -0,0 +1,3932 @@
+import { z } from "zod";
+import { copyFile, lstat, mkdir, mkdtemp, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, matchesGlob, relative, resolve, sep } from "node:path";
+import { assetBundleNames, assetCategories, groupedAssetCategories, simpleAssetCategories } from "@replayablejs/runtime/assets";
+import { basename as basename$1, dirname as dirname$1, extname as extname$1, join as join$1 } from "node:path/posix";
+import { packAsync } from "free-tex-packer-core";
+import sharp from "sharp";
+import subsetFont from "subset-font";
+import { spawn } from "node:child_process";
+import ffmpeg from "@ffmpeg-installer/ffmpeg";
+import { AtlasAttachmentLoader, SkeletonBinary, SkeletonJson, TextureAtlas } from "@esotericsoftware/spine-core";
+import { glob } from "tinyglobby";
+import { parse, printParseErrorCode } from "jsonc-parser";
+//#region src/config/schemas/base.ts
+/** Trimmed configuration string that must contain at least one character. */
+const requiredStringSchema = z.string().trim().min(1);
+/**
+* Strict source-selection fields shared by every asset rule.
+*
+* Category schemas extend this base when they accept processor options. A
+* category without options can use it directly, causing an authored `options`
+* field to be rejected rather than accepted as unknown data.
+*/
+const assetRuleSchema = z.strictObject({
+	/**
+	* Category-relative source-file glob or grouped-asset directory.
+	*
+	* File categories such as sprites and sounds match paths below their category
+	* directory. Grouped categories match the directory that represents the
+	* complete asset, so a Spine export in `spines/raptor` uses `raptor`, not
+	* `raptor/**`. Omitted matches default to `**` and select every asset.
+	*/
+	match: requiredStringSchema.default("**"),
+	/** Optional glob patterns removed from the matched sources. */
+	exclude: z.array(requiredStringSchema).optional()
+});
+//#endregion
+//#region src/config/schemas/image.ts
+/** Image options that allow lossy format selection and encoder quality. */
+const lossyImageOptionsSchema = z.strictObject({
+	/** Width multiplier applied before encoding. */
+	scale: z.number().positive().default(1),
+	/** Selects the default lossy encoding policy. */
+	lossless: z.literal(false).default(false),
+	/** Shared lossy encoder quality; incompatible with lossless output. */
+	quality: z.number().int().min(1).max(100).optional()
+});
+/** Image options that preserve exact pixel values and reject lossy quality. */
+const losslessImageOptionsSchema = z.strictObject({
+	/** Width multiplier applied before encoding. */
+	scale: z.number().positive().default(1),
+	/** Restricts selection to encodings that preserve exact pixel values. */
+	lossless: z.literal(true)
+});
+/** Options shared by standalone images and Spine texture pages. */
+const imageOptionsSchema = z.union([lossyImageOptionsSchema, losslessImageOptionsSchema]);
+/** Rule for standalone sprites and 3D textures. */
+const imageRuleSchema = assetRuleSchema.extend({ options: imageOptionsSchema.prefault({}) });
+//#endregion
+//#region src/config/schemas/atlas.ts
+/** Texture-packing controls added to the shared image encoding policy. */
+const atlasPackingOptionFields = {
+	/** Removes transparent frame borders while preserving original bounds. */
+	allowTrim: z.boolean().default(true),
+	/** Allows frame rotation when it produces a tighter sheet. */
+	allowRotation: z.boolean().default(true),
+	/** Empty pixels placed between packed frames. */
+	padding: z.number().int().min(0).default(2),
+	/** Repeated edge pixels added around each packed frame. */
+	extrude: z.number().int().min(0).default(0),
+	/** Restricts generated sheet dimensions to powers of two. */
+	powerOfTwo: z.boolean().default(false)
+};
+/** Image encoding and texture-packing options for generated atlas sheets. */
+const atlasOptionsSchema = z.union([lossyImageOptionsSchema.extend(atlasPackingOptionFields), losslessImageOptionsSchema.extend(atlasPackingOptionFields)]);
+/** Rule for directories of images packed into Pixi atlas sheets. */
+const atlasRuleSchema = assetRuleSchema.extend({ options: atlasOptionsSchema.prefault({}) });
+//#endregion
+//#region src/config/schemas/font.ts
+/** Required runtime family name plus optional characters added to the subset. */
+const fontOptionsSchema = z.strictObject({
+	/** Runtime CSS font-family name. */
+	family: requiredStringSchema,
+	/** Literal characters added to printable ASCII and resolved locale text. */
+	extraCharacters: z.string().min(1).optional()
+});
+/**
+* Configuration for one matched font source.
+*
+* Every matched source is subset and converted to WOFF2. Output format is not
+* configurable because playable builds ship one compact web-font file.
+*/
+const fontRuleSchema = assetRuleSchema.extend({ options: fontOptionsSchema });
+//#endregion
+//#region src/config/schemas/locale.ts
+/** Rule selecting the project's single multilingual translation dictionary. */
+const localeRuleSchema = assetRuleSchema;
+//#endregion
+//#region src/config/schemas/shader.ts
+/**
+* Rule for directories containing paired vertex and fragment shader sources.
+*
+* Shader sources are copied unchanged and do not accept processor options. The
+* resolver only requires both `vert.glsl` and `frag.glsl`; Replayable does not
+* validate GLSL syntax, versions, entry points, or stage compatibility.
+*/
+const shaderRuleSchema = assetRuleSchema;
+//#endregion
+//#region src/config/schemas/sound.ts
+/** Encoding settings applied to every generated MP3 and M4A candidate. */
+const soundOptionsSchema = z.strictObject({
+	/** Target audio bitrate in kilobits per second. */
+	bitrate: z.number().int().min(8).max(512).default(96),
+	/** Output channel layout, or the source file's original channel count. */
+	channels: z.enum([
+		"mono",
+		"stereo",
+		"source"
+	]).default("mono"),
+	/** Output sample rate in hertz. */
+	sampleRate: z.number().int().min(8e3).max(192e3).default(32e3)
+});
+/**
+* Rule for producing the smallest MP3 or M4A runtime file.
+* Defaults favor compact playable delivery: 96 kbps, mono, and 32 kHz.
+*/
+const soundRuleSchema = assetRuleSchema.extend({ options: soundOptionsSchema.prefault({}) });
+//#endregion
+//#region src/config/schemas/spine.ts
+/** Image processing options applied independently to every Spine texture page. */
+const spineOptionsSchema = imageOptionsSchema;
+/**
+* Rule for directories containing a Spine skeleton, atlas, and texture pages.
+*
+* Image options apply independently to every texture page. Skeleton and atlas
+* files retain their source formats. The configured scale is also emitted as
+* runtime metadata so the application can align skeleton coordinates with
+* resized textures.
+*/
+const spineRuleSchema = assetRuleSchema.extend({ options: spineOptionsSchema.prefault({}) });
+//#endregion
+//#region src/config/schema.ts
+/** Complete category rule collection with omitted categories normalized to empty arrays. */
+const assetsSchema = z.strictObject({
+	atlases: z.array(atlasRuleSchema).default([]),
+	fonts: z.array(fontRuleSchema).default([]),
+	locales: z.array(localeRuleSchema).default([]),
+	shaders: z.array(shaderRuleSchema).default([]),
+	sounds: z.array(soundRuleSchema).default([]),
+	spines: z.array(spineRuleSchema).default([]),
+	sprites: z.array(imageRuleSchema).default([]),
+	textures: z.array(imageRuleSchema).default([])
+});
+/** Fixed build language and the language used for missing translations or assets. */
+const localizationSchema = z.strictObject({
+	fallback: requiredStringSchema,
+	language: requiredStringSchema
+});
+/** Selects assets moved from the always-present primary bundle into secondary. */
+const secondaryBundleSchema = z.strictObject({
+	exclude: z.array(requiredStringSchema).optional(),
+	include: z.array(requiredStringSchema).min(1)
+});
+/** Optional secondary selection; every unmatched asset remains in primary. */
+const bundlesSchema = z.strictObject({ secondary: secondaryBundleSchema.optional() }).prefault({});
+/** Generated TypeScript module destinations relative to the project root. */
+const emitSchema = z.strictObject({
+	assets: requiredStringSchema.default("src/assets/assets.gen.ts"),
+	registries: requiredStringSchema.optional()
+});
+/**
+* Complete runtime schema for `replayable.assets.ts`.
+*
+* `AssetConfigInput` describes author-written configuration where defaulted
+* values may be absent. Parsing produces `AssetConfig`, where defaults are
+* present and strings such as language codes have been trimmed.
+*
+* @remarks Most consumers should call `defineConfig()` instead of invoking
+* this schema directly. The schema is exported for integrations that need Zod
+* parsing, safe parsing, or introspection.
+*/
+const assetConfigSchema = z.strictObject({
+	sourceDir: requiredStringSchema,
+	outDir: requiredStringSchema,
+	localization: localizationSchema,
+	bundles: bundlesSchema,
+	assets: assetsSchema,
+	/** Source-relative glob patterns that veto otherwise selected logical assets. */
+	exclude: z.array(requiredStringSchema).default([]),
+	emit: emitSchema
+});
+//#endregion
+//#region src/emitters/utils/assets-module.ts
+/**
+* Registers one generated file and returns its unique local import identifier.
+*
+* Asset renderers serialize object property lines but do not write import
+* statements. They share one `AssetsModuleContext` and register every file
+* referenced by those lines. If three imports already exist, registering a
+* background image with the prefix `image` performs two related operations:
+*
+* 1. Append this description to `context.imports`:
+*
+*      { name: 'image_3', path: '../../assets/out/background.webp' }
+*
+* 2. Return `'image_3'` so the renderer can reference it:
+*
+*      "background": { src: image_3, scale: 1 },
+*
+* `emitAssetsModule` serializes all asset entries first, which registers every
+* required import. It then writes the accumulated imports above the generated
+* `assets` object:
+*
+*   import image_3 from "../../assets/out/background.webp";
+*
+* Numbering belongs to the complete generated module rather than an individual
+* category. An atlas import followed by an image import can therefore become
+* `atlas_0` and `image_1`. The emitter processes bundles, categories and assets
+* deterministically, so these identifiers remain stable across builds.
+*
+* Every file uses the same ordinary static-import shape. This context does not
+* attach loading instructions based on extensions or asset categories; the
+* playable's bundler owns those decisions. Every call registers a distinct
+* import. This function does not inspect files, emit source code or deduplicate
+* paths; each renderer decides which generated files its runtime entry
+* references.
+*
+* @returns The unique local identifier reserved for the generated import.
+*/
+function registerImport(context, prefix, absolutePath) {
+	const name = `${prefix}_${context.imports.length}`;
+	context.imports.push({
+		name,
+		path: resolveModulePath(context.fromDirectory, absolutePath)
+	});
+	return name;
+}
+/** Resolves one generated file relative to the module that references it. */
+function resolveModulePath(fromDirectory, toFile) {
+	const path = relative(fromDirectory, toFile).split(sep).join("/");
+	return path.startsWith(".") ? path : `./${path}`;
+}
+//#endregion
+//#region src/emitters/utils/object-literal.ts
+/** JSON quoting escapes text; a computed key also avoids JavaScript's prototype setter. */
+function renderPropertyKey(key) {
+	const quoted = JSON.stringify(key);
+	return key === "__proto__" ? `[${quoted}]` : quoted;
+}
+/**
+* Renders the registry's string/object-only shape as a typed JavaScript literal.
+* JSON is not interchangeable with an object literal: `"__proto__": value`
+* changes prototype semantics when parsed as JavaScript, including nested keys.
+* Strings still use JSON.stringify; only object framing and keys are emitted here.
+*/
+function renderRegistryObject(registry, depth = 0) {
+	const entries = Object.entries(registry);
+	if (entries.length === 0) return "{}";
+	const indent = "  ".repeat(depth + 1);
+	return `{\n${entries.map(([key, value]) => {
+		const source = typeof value === "string" ? JSON.stringify(value) : renderRegistryObject(value, depth + 1);
+		return `${indent}${renderPropertyKey(key)}: ${source}`;
+	}).join(",\n")}\n${"  ".repeat(depth)}}`;
+}
+//#endregion
+//#region src/emitters/categories/atlas.ts
+/**
+* Serializes one processed atlas sheet as one TypeScript property line inside
+* the generated `assets` object.
+*
+* Processing has already paired each sheet's JSON frame data with its selected
+* texture image. This renderer therefore receives one complete logical sheet,
+* not independent files that still need to be grouped.
+*
+* For example, a texture packer that splits `ui/menu` into two sheets produces
+* two processed records and invokes this function once for each record:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'atlases',
+*     id: 'ui/menu-0',
+*     files: {
+*       json: {
+*         format: 'json',
+*         path: '/project/assets/generated/atlases/ui/menu-0.json',
+*       },
+*       image: {
+*         format: 'webp',
+*         path: '/project/assets/generated/atlases/ui/menu-0.webp',
+*       },
+*     },
+*   },
+*   {
+*     bundle: 'primary',
+*     category: 'atlases',
+*     id: 'ui/menu-1',
+*     files: {
+*       json: {
+*         format: 'json',
+*         path: '/project/assets/generated/atlases/ui/menu-1.json',
+*       },
+*       image: {
+*         format: 'avif',
+*         path: '/project/assets/generated/atlases/ui/menu-1.avif',
+*       },
+*     },
+*   },
+* ]
+* ```
+*
+* With an initially empty module context, the two calls register imports in
+* semantic sheet order:
+*
+* ```ts
+* import atlas_0 from '../../assets/generated/atlases/ui/menu-0.json';
+* import image_1 from '../../assets/generated/atlases/ui/menu-0.webp';
+* import atlas_2 from '../../assets/generated/atlases/ui/menu-1.json';
+* import image_3 from '../../assets/generated/atlases/ui/menu-1.avif';
+* ```
+*
+* The first call returns the first line and the second call returns the second:
+*
+* ```ts
+* '      "ui/menu-0": { json: atlas_0, image: image_1 },'
+* '      "ui/menu-1": { json: atlas_2, image: image_3 },'
+* ```
+*
+* A source atlas that fits on one sheet reaches this renderer once with the
+* unsuffixed base ID `ui/menu`. Packing, sheet naming, image selection, and
+* runtime-ID uniqueness are handled before emission.
+*
+* Both files use ordinary static imports with their generated extensions. The
+* playable's bundler decides how JSON and image modules are loaded.
+*
+* @param asset - One complete processed atlas sheet containing JSON and texture files.
+* @param context - Module-wide state used to register both generated files.
+* @returns One indented TypeScript source line for the atlas sheet.
+*/
+function renderAtlasEntry(asset, context) {
+	const atlasDataImport = registerImport(context, "atlas", asset.files.json.path);
+	const textureImport = registerImport(context, "image", asset.files.image.path);
+	return `      ${renderPropertyKey(asset.id)}: { json: ${atlasDataImport}, image: ${textureImport} },`;
+}
+/**
+* Builds the registry value for every processed atlas sheet in the build.
+*
+* Unlike `renderAtlasEntry`, this function does not produce TypeScript source
+* or register file imports. It turns the frame names retained during atlas
+* processing into a plain nested object. `emitRegistries` later serializes that
+* object into the generated `atlases.ts` module.
+*
+* For example, this input contains two sheets from the build:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'atlases',
+*     id: 'ui/menu-0',
+*     files: {
+*       json: {
+*         format: 'json',
+*         path: '/project/assets/generated/atlases/ui/menu-0.json',
+*       },
+*       image: {
+*         format: 'webp',
+*         path: '/project/assets/generated/atlases/ui/menu-0.webp',
+*       },
+*     },
+*     frameNames: ['menu-0/buttons/play', 'menu-0/icons/close'],
+*   },
+*   {
+*     bundle: 'primary',
+*     category: 'atlases',
+*     id: 'ui/menu-1',
+*     files: {
+*       json: {
+*         format: 'json',
+*         path: '/project/assets/generated/atlases/ui/menu-1.json',
+*       },
+*       image: {
+*         format: 'avif',
+*         path: '/project/assets/generated/atlases/ui/menu-1.avif',
+*       },
+*     },
+*     frameNames: ['menu-1/panel'],
+*   },
+* ]
+* ```
+*
+* If `menu-0` retains the frames `menu-0/buttons/play` and
+* `menu-0/icons/close`, while `menu-1` retains `menu-1/panel`, this function
+* returns:
+*
+* ```ts
+* {
+*   'ui/menu-0': {
+*     'buttons/play': 'menu-0/buttons/play',
+*     'icons/close': 'menu-0/icons/close',
+*   },
+*   'ui/menu-1': {
+*     panel: 'menu-1/panel',
+*   },
+* }
+* ```
+*
+* Each outer key is the runtime ID of one generated sheet. Each inner key is
+* the convenient application-facing frame key, while its value remains the
+* exact frame name stored in the generated atlas JSON and expected by the
+* runtime texture-atlas loader.
+*
+* A generated sheet prefix is removed only from the registry key. For example,
+* `menu-0/buttons/play` becomes the key `buttons/play`, but its value remains
+* `menu-0/buttons/play`. A frame without that exact prefix is preserved on both
+* sides. This prevents a generated sheet name from leaking into application
+* code without changing the actual lookup value.
+*
+* Assets arrive in deterministic ID order from the shared emitter grouping
+* step. The processor retained frame names while the packer's JSON was already
+* in memory; this renderer therefore performs no filesystem reads or parsing.
+* Frame names are sorted here before serialization. Bundle membership does not
+* appear in the registry.
+*
+* @param assets - Complete processed atlas sheets across all bundles.
+* @returns A sheet-ID-to-frame-lookup object ready for registry serialization.
+*/
+function renderAtlasRegistry(assets) {
+	const entries = assets.map((asset) => {
+		const frameEntries = [...asset.frameNames].sort((left, right) => left.localeCompare(right)).map((frameName) => [stripSheetPrefix(asset.id, frameName), frameName]);
+		return [asset.id, Object.fromEntries(frameEntries)];
+	});
+	return Object.fromEntries(entries);
+}
+/**
+* Removes one generated sheet-name prefix from an application-facing frame key.
+*
+* For atlas ID `ui/menu-0`, `menu-0/buttons/play` becomes `buttons/play`.
+* `shared/logo` remains `shared/logo` because it does not begin with the exact
+* generated sheet name `menu-0/`.
+*/
+function stripSheetPrefix(atlasId, frameName) {
+	const sheetPrefix = `${atlasId.split("/").at(-1) ?? atlasId}/`;
+	return frameName.startsWith(sheetPrefix) ? frameName.slice(sheetPrefix.length) : frameName;
+}
+//#endregion
+//#region src/emitters/utils/registry.ts
+/** Creates a deterministic `{ value: value }` lookup table. */
+function createIdentityRegistry(values) {
+	const uniqueValues = [...new Set(values)].sort((left, right) => left.localeCompare(right));
+	return Object.fromEntries(uniqueValues.map((value) => [value, value]));
+}
+//#endregion
+//#region src/emitters/categories/font.ts
+/**
+* Serializes one processed font as one TypeScript property line inside the
+* generated `assets` object.
+*
+* Processing has already subset the source font and emitted its one runtime
+* WOFF2 file. This renderer receives that generated file together with the
+* required CSS family configured for the asset:
+*
+* ```ts
+* {
+*   bundle: 'primary',
+*   category: 'fonts',
+*   id: 'heading',
+*   file: {
+*     format: 'woff2',
+*     path: '/project/assets/generated/fonts/heading.woff2',
+*   },
+*   runtime: {
+*     family: 'Brand Display',
+*   },
+* }
+* ```
+*
+* With an initially empty module context, rendering this record registers:
+*
+* ```ts
+* import font_0 from '../../assets/generated/fonts/heading.woff2';
+* ```
+*
+* and returns exactly one property line:
+*
+* ```ts
+* '      "heading": { src: font_0, family: "Brand Display" },'
+* ```
+*
+* The runtime ID `heading` is the key used to retrieve this asset from the
+* generated object. `Brand Display` is the required family name used by CSS;
+* the two values serve different purposes and do not need to match.
+*
+* Charset construction, `extraCharacters`, and font subsetting are build-only
+* concerns completed before emission. They are intentionally absent from the
+* runtime entry. Application CSS owns descriptors such as style, weight,
+* stretch, and display; this renderer does not infer them from filenames or
+* font metadata.
+*
+* @param asset - One complete processed font containing its WOFF2 file and family.
+* @param context - Module-wide state used to register the generated font file.
+* @returns One indented TypeScript source line for the font.
+*/
+function renderFontEntry(asset, context) {
+	const fontFileImport = registerImport(context, "font", asset.file.path);
+	return `      ${renderPropertyKey(asset.id)}: { src: ${fontFileImport}, family: ${JSON.stringify(asset.runtime.family)} },`;
+}
+/**
+* Builds the font-family registry value for all processed fonts in the build.
+*
+* This function does not render TypeScript source or register WOFF2 imports.
+* It extracts the CSS family from each processed font and creates a plain
+* identity lookup. `emitRegistries` later serializes that value into the
+* generated `fonts.ts` module.
+*
+* For example, this input contains two font assets from the build:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'fonts',
+*     id: 'body',
+*     file: {
+*       format: 'woff2',
+*       path: '/project/assets/generated/fonts/body.woff2',
+*     },
+*     runtime: {
+*       family: 'Replayable Body',
+*     },
+*   },
+*   {
+*     bundle: 'primary',
+*     category: 'fonts',
+*     id: 'heading',
+*     file: {
+*       format: 'woff2',
+*       path: '/project/assets/generated/fonts/heading.woff2',
+*     },
+*     runtime: {
+*       family: 'Brand Display',
+*     },
+*   },
+* ]
+* ```
+*
+* The function returns:
+*
+* ```ts
+* {
+*   'Brand Display': 'Brand Display',
+*   'Replayable Body': 'Replayable Body',
+* }
+* ```
+*
+* Registry keys intentionally use configured CSS families rather than asset
+* IDs. Application code uses these values in CSS declarations such as
+* `font-family: fonts['Brand Display']`; the build-only IDs `body` and
+* `heading` address entries in the generated `assets` object instead.
+*
+* `createIdentityRegistry` deduplicates repeated families and sorts them
+* alphabetically, so two font assets configured with the same family produce
+* one registry entry and generated output remains deterministic. Font paths,
+* formats, charset information, and CSS descriptors do not belong in this
+* lookup.
+*
+* `emitRegistries` calls this function once with fonts from the complete build;
+* bundle membership is intentionally absent from the returned registry.
+*
+* @param assets - Complete processed fonts across all bundles.
+* @returns A deterministic CSS-family identity lookup ready for serialization.
+*/
+function renderFontRegistry(assets) {
+	return createIdentityRegistry(assets.map((asset) => asset.runtime.family));
+}
+//#endregion
+//#region src/emitters/categories/image.ts
+/**
+* Serializes one processed sprite or texture as one TypeScript property line
+* inside the generated `assets` object.
+*
+* Processing has already generated every applicable AVIF, WebP, PNG, or JPEG
+* candidate, compared their file sizes, retained the smallest, and deleted the
+* rejected candidates. This renderer receives exactly one selected image:
+*
+* ```ts
+* {
+*   bundle: 'primary',
+*   category: 'sprites',
+*   id: 'logo',
+*   file: {
+*     format: 'webp',
+*     path: '/project/assets/generated/sprites/logo.webp',
+*   },
+*   runtime: {
+*     scale: 0.5,
+*   },
+* }
+* ```
+*
+* With an initially empty module context, rendering this record registers:
+*
+* ```ts
+* import image_0 from '../../assets/generated/sprites/logo.webp';
+* ```
+*
+* and returns exactly one property line:
+*
+* ```ts
+* '      "logo": { src: image_0, scale: 0.5 },'
+* ```
+*
+* The selected encoding does not affect the runtime shape: `src` is always one
+* imported value rather than a format map. Sprites and textures use the same
+* entry shape, so their surrounding category block is the only distinction in
+* generated source; `asset.category` is not repeated inside the entry.
+*
+* Localized sprite selection belongs to resolution. A selected source such as
+* `logo.hy.png` therefore reaches this renderer with the stable runtime ID
+* `logo` and no language suffix. `scale` records the resize factor that
+* processing already applied to the generated image.
+*
+* @param asset - One complete processed sprite or texture with its selected image.
+* @param context - Module-wide state used to register the generated image file.
+* @returns One indented TypeScript source line for the image.
+*/
+function renderImageEntry(asset, context) {
+	const imageFileImport = registerImport(context, "image", asset.file.path);
+	return `      ${renderPropertyKey(asset.id)}: { src: ${imageFileImport}, scale: ${asset.runtime.scale} },`;
+}
+/**
+* Builds the runtime-ID registry for one image category across the build.
+*
+* This shared renderer is used for both `sprites` and `textures`, but one call
+* receives only one category. `emitRegistries` passes the complete category
+* bucket across all bundles.
+*
+* For example, one call for the `sprites` category can receive:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'sprites',
+*     id: 'logo',
+*     file: {
+*       format: 'webp',
+*       path: '/project/assets/generated/sprites/logo.webp',
+*     },
+*     runtime: {
+*       scale: 0.5,
+*     },
+*   },
+*   {
+*     bundle: 'primary',
+*     category: 'sprites',
+*     id: 'ui/play-button',
+*     file: {
+*       format: 'avif',
+*       path: '/project/assets/generated/sprites/ui/play-button.avif',
+*     },
+*     runtime: {
+*       scale: 1,
+*     },
+*   },
+* ]
+* ```
+*
+* and returns this plain registry value:
+*
+* ```ts
+* {
+*   logo: 'logo',
+*   'ui/play-button': 'ui/play-button',
+* }
+* ```
+*
+* Registry keys and values are the same stable runtime IDs used in the
+* generated `assets` object. File paths, selected encodings, and image scales
+* are deliberately excluded because the registry identifies assets; the
+* generated assets module contains their loadable runtime data.
+*
+* Localized sprite resolution has already removed language suffixes. If the
+* Armenian build selected `logo.hy.png`, its processed ID and registry entry
+* are still `logo`. Textures follow the same identity shape, although they are
+* emitted into a separate `textures` registry.
+*
+* `createIdentityRegistry` sorts IDs alphabetically, keeping generated output
+* deterministic. Asset identity has already been validated before emission,
+* so repeated IDs produce the same identity value. Bundle membership does not
+* appear in the registry.
+*
+* @param assets - Processed sprites or textures from one complete category.
+* @returns A deterministic runtime-ID identity lookup ready for serialization.
+*/
+function renderImageRegistry(assets) {
+	return createIdentityRegistry(assets.map((asset) => asset.id));
+}
+//#endregion
+//#region src/emitters/categories/locale.ts
+/**
+* Serializes one processed locale dictionary as one TypeScript property line
+* inside the generated `assets` object.
+*
+* One input item represents one compiled JSON dictionary. Locale resolution is
+* already complete: each phrase contains either the configured build language
+* or its fallback, never every authored language. For example, a source file
+* named `translations.jsonc` can arrive as:
+*
+*   {
+*     id: 'translations',
+*     file: { format: 'json', path: '/out/locales/translations.json' },
+*   }
+*
+* Its generated file contains the final value selected for every phrase:
+*
+*   {
+*     "play": "Խաղալ",
+*     "install": "Install"
+*   }
+*
+* The renderer does not inspect or transform that JSON. It registers one
+* ordinary static import and returns its property line:
+*
+*   import locale_0 from '../../assets/out/locales/translations.json';
+*
+*   '      "translations": locale_0,'
+*
+* Replayable's bundler decides whether that import becomes a parsed inline
+* dictionary or an emitted resource URL. No query suffix, URL constructor, or
+* bundler-specific loading instruction appears in the generated module.
+*
+* Language selection and JSON compilation belong to processing. Runtime-key
+* uniqueness and collection ordering are handled centrally. This renderer owns
+* one JSON import and one source line.
+*
+* @returns One indented TypeScript source line for the locale dictionary.
+*/
+function renderLocaleEntry(asset, context) {
+	const dictionaryImport = registerImport(context, "locale", asset.file.path);
+	return `      ${renderPropertyKey(asset.id)}: ${dictionaryImport},`;
+}
+/**
+* Builds the phrase-ID registry from the generated translation dictionary.
+*
+* This function does not render TypeScript source or register JSON imports. It
+* collects the top-level phrase IDs retained on each processed locale and
+* returns a plain identity lookup. `emitRegistries` later serializes that
+* lookup into the generated `locales.ts` module.
+*
+* For example, this input represents the processed dictionary:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'locales',
+*     id: 'translations',
+*     file: {
+*       format: 'json',
+*       path: '/project/assets/generated/locales/translations.json',
+*     },
+*     phraseIds: ['play', 'install'],
+*   },
+* ]
+* ```
+*
+* The function combines those phrase IDs and returns:
+*
+* ```ts
+* {
+*   install: 'install',
+*   play: 'play',
+* }
+* ```
+*
+* Translation values are irrelevant to registry generation: both
+* `{ play: 'Խաղալ' }` and `{ play: 'Play' }` contribute the same phrase ID,
+* `play`. Language selection, fallback resolution, and extraction of these
+* top-level IDs were completed before emission.
+*
+* `createIdentityRegistry` sorts the final keys alphabetically for
+* deterministic output. Bundle membership does not appear in the registry.
+*
+* @param assets - The processed primary translation dictionary, when present.
+* @returns The deterministic phrase-ID identity lookup.
+*/
+function renderLocaleRegistry(assets) {
+	return createIdentityRegistry(assets.flatMap((asset) => asset.phraseIds));
+}
+//#endregion
+//#region src/emitters/categories/shader.ts
+/**
+* Serializes one processed shader pair as one TypeScript property line inside
+* the generated `assets` object.
+*
+* Resolution has already required the authored `vert.glsl` and `frag.glsl`
+* pair, and processing has copied both files unchanged. This renderer receives
+* one complete logical shader:
+*
+* ```ts
+* {
+*   bundle: 'primary',
+*   category: 'shaders',
+*   id: 'glow',
+*   files: {
+*     vert: {
+*       format: 'glsl',
+*       path: '/project/assets/generated/shaders/glow/vert.glsl',
+*     },
+*     frag: {
+*       format: 'glsl',
+*       path: '/project/assets/generated/shaders/glow/frag.glsl',
+*     },
+*   },
+* }
+* ```
+*
+* With an initially empty module context, the vertex stage is registered first
+* and the fragment stage second:
+*
+* ```ts
+* import shader_0 from '../../assets/generated/shaders/glow/vert.glsl';
+* import shader_1 from '../../assets/generated/shaders/glow/frag.glsl';
+* ```
+*
+* The function then returns one property containing the same semantic stage
+* order:
+*
+* ```ts
+* '      "glow": { vert: shader_0, frag: shader_1 },'
+* ```
+*
+* `vert` and `frag` are explicit runtime fields rather than an order-dependent
+* source array. The renderer adds no `?raw`, `?url`, import attribute, or GLSL
+* interpretation. No build stage validates shader syntax or imposes a GLSL
+* version; the playable's bundler and runtime own how the imports are loaded
+* and compiled.
+*
+* @param asset - One complete processed shader containing both generated stages.
+* @param context - Module-wide state used to register the vertex and fragment files.
+* @returns One indented TypeScript source line for the shader pair.
+*/
+function renderShaderEntry(asset, context) {
+	const vertexShaderImport = registerImport(context, "shader", asset.files.vert.path);
+	const fragmentShaderImport = registerImport(context, "shader", asset.files.frag.path);
+	return `      ${renderPropertyKey(asset.id)}: { vert: ${vertexShaderImport}, frag: ${fragmentShaderImport} },`;
+}
+/**
+* Builds the logical shader-ID registry for all processed shaders in the build.
+*
+* A processed shader is one runtime asset containing both its vertex and
+* fragment stages. This function therefore registers the shader's logical ID,
+* not separate stage paths. It returns plain registry data; `emitRegistries`
+* later serializes that value into the generated `shaders.ts` module.
+*
+* For example, this input contains two complete shader programs:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'shaders',
+*     id: 'dissolve',
+*     files: {
+*       vert: {
+*         format: 'glsl',
+*         path: '/project/assets/generated/shaders/dissolve/vert.glsl',
+*       },
+*       frag: {
+*         format: 'glsl',
+*         path: '/project/assets/generated/shaders/dissolve/frag.glsl',
+*       },
+*     },
+*   },
+*   {
+*     bundle: 'primary',
+*     category: 'shaders',
+*     id: 'grayscale',
+*     files: {
+*       vert: {
+*         format: 'glsl',
+*         path: '/project/assets/generated/shaders/grayscale/vert.glsl',
+*       },
+*       frag: {
+*         format: 'glsl',
+*         path: '/project/assets/generated/shaders/grayscale/frag.glsl',
+*       },
+*     },
+*   },
+* ]
+* ```
+*
+* The function returns:
+*
+* ```ts
+* {
+*   dissolve: 'dissolve',
+*   grayscale: 'grayscale',
+* }
+* ```
+*
+* No `dissolve/vert` or `dissolve/frag` registry values are generated. Runtime
+* code selects the complete shader through `shaders.dissolve`; the
+* generated `assets` entry then provides its explicit `vert` and `frag`
+* imports. Stage paths, GLSL source, and formats belong to that assets module,
+* not to this identity registry.
+*
+* `createIdentityRegistry` sorts shader IDs alphabetically for deterministic
+* generated output. Shader identity has already been validated before
+* emission, and no generated files need to be read to build this lookup.
+* Bundle membership does not appear in the registry.
+*
+* @param assets - Complete processed shader programs across all bundles.
+* @returns A deterministic shader-ID identity lookup ready for serialization.
+*/
+function renderShaderRegistry(assets) {
+	return createIdentityRegistry(assets.map((asset) => asset.id));
+}
+//#endregion
+//#region src/emitters/categories/sound.ts
+/**
+* Serializes one processed sound as one TypeScript property line inside the
+* generated `assets` object.
+*
+* Processing has already transcoded the source as MP3 and M4A, measured both
+* generated files, retained the smaller candidate, and deleted the rejected
+* candidate. This renderer therefore receives only the selected runtime file:
+*
+* ```ts
+* {
+*   bundle: 'primary',
+*   category: 'sounds',
+*   id: 'click',
+*   file: {
+*     format: 'm4a',
+*     path: '/project/assets/generated/sounds/click.m4a',
+*   },
+* }
+* ```
+*
+* With an initially empty module context, rendering this record registers:
+*
+* ```ts
+* import sound_0 from '../../assets/generated/sounds/click.m4a';
+* ```
+*
+* and returns exactly one direct runtime reference:
+*
+* ```ts
+* '      "click": sound_0,'
+* ```
+*
+* The winning encoding does not change the runtime shape. There is no format
+* map, fallback field, or source array because a playable ships only the one
+* selected file. Bitrate, channels, and sample rate are build-only transcoding
+* controls and are intentionally absent from the runtime entry. The playable's
+* bundler decides how the ordinary static audio import becomes a runtime URL or
+* equivalent value.
+*
+* @param asset - One complete processed sound containing its selected audio file.
+* @param context - Module-wide state used to register the generated sound file.
+* @returns One indented TypeScript source line for the sound.
+*/
+function renderSoundEntry(asset, context) {
+	const soundFileImport = registerImport(context, "sound", asset.file.path);
+	return `      ${renderPropertyKey(asset.id)}: ${soundFileImport},`;
+}
+/**
+* Builds the runtime-ID registry for all processed sounds in the build.
+*
+* This function does not render TypeScript source or register audio imports. It
+* extracts each sound's stable runtime ID and returns a plain identity lookup.
+* `emitRegistries` later serializes that value into the generated `sounds.ts`
+* module.
+*
+* For example, this input contains two sounds whose automatic encoding
+* selection produced different winning formats:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'sounds',
+*     id: 'click',
+*     file: {
+*       format: 'm4a',
+*       path: '/project/assets/generated/sounds/click.m4a',
+*     },
+*   },
+*   {
+*     bundle: 'primary',
+*     category: 'sounds',
+*     id: 'music/theme',
+*     file: {
+*       format: 'mp3',
+*       path: '/project/assets/generated/sounds/music/theme.mp3',
+*     },
+*   },
+* ]
+* ```
+*
+* The function returns:
+*
+* ```ts
+* {
+*   click: 'click',
+*   'music/theme': 'music/theme',
+* }
+* ```
+*
+* Registry identity is independent of the selected MP3 or M4A encoding. Code
+* selects the sound through a stable value such as
+* `sounds['music/theme']`; the generated `assets` module owns the
+* corresponding imported file. Paths, formats, and transcoding options are
+* therefore intentionally absent from this registry.
+*
+* `createIdentityRegistry` sorts sound IDs alphabetically for deterministic
+* generated output. Sound identity has already been validated before emission,
+* and no generated audio files need to be read here. Bundle membership does
+* not appear in the registry.
+*
+* @param assets - Complete processed sounds across all bundles.
+* @returns A deterministic sound-ID identity lookup ready for serialization.
+*/
+function renderSoundRegistry(assets) {
+	return createIdentityRegistry(assets.map((asset) => asset.id));
+}
+//#endregion
+//#region src/emitters/categories/spine.ts
+/**
+* Serializes one processed Spine asset as one TypeScript property line inside
+* the generated `assets` object.
+*
+* Resolution and processing have already assembled every physical file into
+* one complete logical Spine asset. A two-page JSON Spine named `hero` arrives
+* as one processed record:
+*
+* ```ts
+* {
+*   bundle: 'primary',
+*   category: 'spines',
+*   id: 'hero',
+*   files: {
+*     skeleton: {
+*       format: 'json',
+*       path: '/project/assets/generated/spines/hero/skeleton.json',
+*     },
+*     atlas: {
+*       format: 'atlas',
+*       path: '/project/assets/generated/spines/hero/atlas.atlas',
+*     },
+*     images: [
+*       {
+*         format: 'webp',
+*         path: '/project/assets/generated/spines/hero/images/page0.webp',
+*       },
+*       {
+*         format: 'avif',
+*         path: '/project/assets/generated/spines/hero/images/page1.avif',
+*       },
+*     ],
+*   },
+*   metadata: {
+*     animationNames: ['idle', 'run'],
+*     skinNames: ['default', 'armored'],
+*   },
+*   runtime: { scale: 0.5 },
+* }
+* ```
+*
+* With an initially empty module context, rendering registers the skeleton,
+* atlas description, and texture pages in semantic order:
+*
+* ```ts
+* import spine_0 from '../../assets/generated/spines/hero/skeleton.json';
+* import spine_1 from '../../assets/generated/spines/hero/atlas.atlas';
+* import image_2 from '../../assets/generated/spines/hero/images/page0.webp';
+* import image_3 from '../../assets/generated/spines/hero/images/page1.avif';
+* ```
+*
+* The function then returns exactly one property line for the complete logical
+* asset:
+*
+* ```ts
+* '      "hero": { format: "json", skel: spine_0, atlas: spine_1, images: [image_2, image_3], scale: 0.5 },'
+* ```
+*
+* Each texture page has independently retained its smallest image encoding, so
+* page 0 can be WebP while page 1 is AVIF. Processing stores the selected files
+* in the order declared by the Spine atlas. Array mapping preserves that order
+* during import registration and in the generated runtime `images` array.
+*
+* The runtime field `skel` references either a JSON skeleton, as above, or a
+* binary `.skel` file. Every physical file retains its generated extension and
+* uses an ordinary static import without attributes or query suffixes. The
+* playable's bundler decides how each extension is loaded.
+*
+* `scale` comes from the shared image options used to resize texture pages. It
+* remains in the runtime entry so a rendering integration can restore each
+* texture page's authored logical dimensions. Quality and lossless controls
+* are build-only and are not emitted.
+*
+* Source completeness belongs to resolution. Processing keeps the required
+* files together, so this renderer only registers imports and serializes one
+* complete runtime entry.
+*
+* @param asset - One complete processed Spine asset with ordered texture pages.
+* @param context - Module-wide state used to register every generated Spine file.
+* @returns One indented TypeScript source line for the Spine asset.
+*/
+function renderSpineEntry(asset, context) {
+	const skeletonFileImport = registerImport(context, "spine", asset.files.skeleton.path);
+	const atlasFileImport = registerImport(context, "spine", asset.files.atlas.path);
+	const texturePageImports = asset.files.images.map((image) => registerImport(context, "image", image.path));
+	return `      ${renderPropertyKey(asset.id)}: { format: ${JSON.stringify(asset.files.skeleton.format)}, skel: ${skeletonFileImport}, atlas: ${atlasFileImport}, images: [${texturePageImports.join(", ")}], scale: ${asset.runtime.scale} },`;
+}
+/**
+* Builds skeleton, animation, and skin registry values for all Spine assets.
+*
+* Unlike `renderSpineEntry`, this function does not register file imports or
+* produce TypeScript source. It converts animation and skin names retained
+* during processing into a plain nested object. `emitRegistries` later
+* serializes that value into the generated `spines.ts` module.
+*
+* For example, this processed Spine asset can reach the function inside a
+* one-item array:
+*
+* ```ts
+* [
+*   {
+*     bundle: 'primary',
+*     category: 'spines',
+*     id: 'hero',
+*     files: {
+*       skeleton: {
+*         format: 'json',
+*         path: '/project/assets/generated/spines/hero/skeleton.json',
+*       },
+*       atlas: {
+*         format: 'atlas',
+*         path: '/project/assets/generated/spines/hero/atlas.atlas',
+*       },
+*       images: [
+*         {
+*           format: 'webp',
+*           path: '/project/assets/generated/spines/hero/images/page0.webp',
+*         },
+*         {
+*           format: 'avif',
+*           path: '/project/assets/generated/spines/hero/images/page1.avif',
+*         },
+*       ],
+*     },
+*     metadata: {
+*       animationNames: ['idle', 'run'],
+*       skinNames: ['default', 'armored'],
+*     },
+*     runtime: {
+*       scale: 0.5,
+*     },
+*   },
+* ]
+* ```
+*
+* If the generated skeleton declares the animations `idle` and `run` and the
+* skins `default` and `armored`, the function returns:
+*
+* ```ts
+* {
+*   hero: {
+*     skeleton: 'hero',
+*     animations: {
+*       idle: 'idle',
+*       run: 'run',
+*     },
+*     skins: {
+*       armored: 'armored',
+*       default: 'default',
+*     },
+*   },
+* }
+* ```
+*
+* The outer `hero` key groups metadata for one logical Spine asset.
+* `skeleton` repeats that stable asset ID as a directly consumable registry
+* value, while `animations` and `skins` provide typed identity lookups for the
+* names authored inside the skeleton.
+*
+* Metadata extraction already supported either JSON or binary SKEL through the
+* official Spine runtime during processing. Texture page files, selected image
+* encodings, and runtime scale are not registry metadata; they remain available
+* through the generated `assets` entry.
+*
+* Assets arrive in deterministic ID order from the shared emitter grouping
+* step. Each animation and skin collection is converted through
+* `createIdentityRegistry`, which keeps its keys unique and alphabetically
+* ordered. Bundle membership does not appear in the registry.
+*
+* @param assets - Complete processed Spine assets across all bundles.
+* @returns The deterministic Spine metadata registry.
+*/
+function renderSpineRegistry(assets) {
+	const entries = assets.map((asset) => [asset.id, {
+		skeleton: asset.id,
+		animations: createIdentityRegistry(asset.metadata.animationNames),
+		skins: createIdentityRegistry(asset.metadata.skinNames)
+	}]);
+	return Object.fromEntries(entries);
+}
+//#endregion
+//#region src/emitters/utils/generated-module.ts
+const GENERATED_MODULE_HEADER = [
+	"// AUTO-GENERATED FILE - DO NOT EDIT",
+	"// Generated by @replayablejs/assets",
+	""
+];
+/**
+* Wraps generated TypeScript body lines in the shared module framing.
+*
+* Every generated module receives the same warning header, one blank line
+* before its body, and exactly one final newline. Callers provide only their
+* module-specific lines and do not need to know how generated files are
+* framed.
+*
+* @example
+*
+* ```ts
+* renderGeneratedModule(['export const sounds = {} as const;']);
+* ```
+*
+* returns:
+*
+* ```ts
+* // AUTO-GENERATED FILE - DO NOT EDIT
+* // Generated by @replayablejs/assets
+*
+* export const sounds = {} as const;
+* ```
+*
+* @param bodyLines - Complete source lines belonging after the shared header.
+* @returns A complete generated TypeScript module with one final newline.
+*/
+function renderGeneratedModule(bodyLines) {
+	return [
+		...GENERATED_MODULE_HEADER,
+		...bodyLines,
+		""
+	].join("\n");
+}
+//#endregion
+//#region src/emitters/emit-assets-module.ts
+/**
+* Generates the TypeScript module consumed by a playable at runtime.
+*
+* Processed assets already represent complete runtime values. This emitter
+* renders those values into an in-memory module and then performs one
+* filesystem write. Category renderers never write files themselves.
+*
+* Every example in this file follows the same build: bundle `primary` contains
+* the sound `click` and the two-page Spine asset `hero`; bundle `secondary`
+* contains the sprite `logo`.
+*
+* @example
+*
+* ```ts
+* const assetGroups = groupAssets([
+*   {
+*     bundle: 'primary',
+*     category: 'sounds',
+*     id: 'click',
+*     file: {
+*       format: 'm4a',
+*       path: '/project/assets/generated/sounds/click.m4a',
+*     },
+*   },
+*   {
+*     bundle: 'primary',
+*     category: 'spines',
+*     id: 'hero',
+*     files: {
+*       skeleton: {
+*         format: 'json',
+*         path: '/project/assets/generated/spines/hero/skeleton.json',
+*       },
+*       atlas: {
+*         format: 'atlas',
+*         path: '/project/assets/generated/spines/hero/atlas.atlas',
+*       },
+*       images: [
+*         {
+*           format: 'webp',
+*           path: '/project/assets/generated/spines/hero/images/page0.webp',
+*         },
+*         {
+*           format: 'avif',
+*           path: '/project/assets/generated/spines/hero/images/page1.avif',
+*         },
+*       ],
+*     },
+*     runtime: { scale: 0.5 },
+*   },
+*   {
+*     bundle: 'secondary',
+*     category: 'sprites',
+*     id: 'logo',
+*     file: {
+*       format: 'webp',
+*       path: '/project/assets/generated/sprites/logo.webp',
+*     },
+*     runtime: { scale: 1 },
+*   },
+* ]);
+*
+* await emitAssetsModule('/project/src/assets/assets.gen.ts', assetGroups);
+* ```
+*
+* The call writes `/project/src/assets/assets.gen.ts` with the complete source
+* shown in the `renderAssetsModule` example below.
+*/
+async function emitAssetsModule(file, assetGroups) {
+	await writeAssetsModule(file, renderAssetsModule(assetGroups, dirname(file)));
+}
+/**
+* Renders every processed asset into the complete generated TypeScript module.
+*
+* `assetGroups` contains the canonical bundle, category, and asset hierarchy
+* prepared for all emitters. `fromDirectory` is the directory that will contain
+* the generated module; import registration uses it to turn absolute generated-
+* file paths into relative module specifiers.
+*
+* The function traverses every prepared bundle and renders its nested category
+* and asset entries. Rendering an entry registers its physical files in a
+* local `AssetsModuleContext`, so bundle lines must be rendered before import
+* statements can be assembled. The context never escapes this function.
+*
+* Given the three canonical processed records above and
+* `fromDirectory = '/project/src/assets'`, the function returns this complete
+* string. Bundle order, category order, asset order, and module-wide import
+* numbering are all visible in the result:
+*
+* ```ts
+* // AUTO-GENERATED FILE - DO NOT EDIT
+* // Generated by @replayablejs/assets
+*
+* import type { Assets } from '@replayablejs/assets';
+* import sound_0 from '../../assets/generated/sounds/click.m4a';
+* import spine_1 from '../../assets/generated/spines/hero/skeleton.json';
+* import spine_2 from '../../assets/generated/spines/hero/atlas.atlas';
+* import image_3 from '../../assets/generated/spines/hero/images/page0.webp';
+* import image_4 from '../../assets/generated/spines/hero/images/page1.avif';
+* import image_5 from '../../assets/generated/sprites/logo.webp';
+*
+* export const assets = {
+*   "primary": {
+*     sounds: {
+*       "click": sound_0,
+*     },
+*     spines: {
+*       "hero": { format: "json", skel: spine_1, atlas: spine_2, images: [image_3, image_4], scale: 0.5 },
+*     },
+*   },
+*   "secondary": {
+*     sprites: {
+*       "logo": { src: image_5, scale: 1 },
+*     },
+*   },
+* } satisfies Assets;
+* ```
+*
+* This function only returns source text. It does not create directories or
+* write the generated module.
+*
+* @param assetGroups - Processed assets organized once for all emitters.
+* @param fromDirectory - Absolute directory containing the generated module.
+* @returns The complete TypeScript module, including imports and final newline.
+*/
+function renderAssetsModule(assetGroups, fromDirectory) {
+	const imports = [];
+	const context = {
+		fromDirectory,
+		imports
+	};
+	const bundleLines = assetGroups.bundles.flatMap((bundle) => renderBundle(bundle, context));
+	return renderGeneratedModule([
+		"import type { Assets } from '@replayablejs/assets';",
+		...imports.map((generatedImport) => `import ${generatedImport.name} from ${JSON.stringify(generatedImport.path)};`),
+		"",
+		"export const assets = {",
+		...bundleLines,
+		"} satisfies Assets;"
+	]);
+}
+/**
+* Renders one bundle object containing each of its non-empty categories.
+*
+* The caller supplies one bundle whose assets are already separated by category
+* and sorted by ID. This function visits categories in the canonical
+* `assetCategories` order and delegates each non-empty block to
+* `renderCategory`. Entry rendering may register imports in `context`, but this
+* function returns only the lines belonging inside the top-level `assets`
+* object.
+*
+* In the canonical example, calling this function for `primary` with the
+* `click` and `hero` records returns the complete bundle block below. Because
+* the shared context is initially empty, rendering the block also registers
+* `sound_0`, `spine_1`, `spine_2`, `image_3`, and `image_4` in that order:
+*
+* ```ts
+* [
+*   '  "primary": {',
+*   '    sounds: {',
+*   '      "click": sound_0,',
+*   '    },',
+*   '    spines: {',
+*   '      "hero": { format: "json", skel: spine_1, atlas: spine_2, images: [image_3, image_4], scale: 0.5 },',
+*   '    },',
+*   '  },',
+* ]
+* ```
+*
+* @param bundle - Organized runtime bundle to render.
+* @param context - Module-wide state that receives imports from rendered entries.
+* @returns Source lines for one complete bundle object property.
+*/
+function renderBundle(bundle, context) {
+	const categoryLines = assetCategories.flatMap((category) => renderCategory(category, bundle.categories[category], context));
+	return [
+		`  ${JSON.stringify(bundle.name)}: {`,
+		...categoryLines,
+		"  },"
+	];
+}
+/**
+* Renders one category block from the matching assets in a bundle.
+*
+* `categoryAssets` contains only the requested category and is already sorted
+* by runtime ID. This function asks `renderAssetEntry` for one property line per
+* record and wraps those lines in the category object.
+*
+* In the canonical example, calling the function with `category = 'sounds'`
+* and the prepared `[click]` group registers its M4A file as `sound_0` and
+* returns:
+*
+* ```ts
+* [
+*   '    sounds: {',
+*   '      "click": sound_0,',
+*   '    },',
+* ]
+* ```
+*
+* A bundle without assets in the requested category returns `[]`, so no empty
+* category object is written to the generated module.
+*
+* @param category - Category to select and use as the generated object key.
+* @param categoryAssets - Prepared assets belonging to this exact category.
+* @param context - Module-wide state that receives imports from rendered entries.
+* @returns A complete category block, or an empty array when the category is absent.
+*/
+function renderCategory(category, categoryAssets, context) {
+	if (categoryAssets.length === 0) return [];
+	const entryLines = categoryAssets.map((asset) => renderAssetEntry(asset, context));
+	return [
+		`    ${category}: {`,
+		...entryLines,
+		"    },"
+	];
+}
+/**
+* Renders one processed asset as one property inside its category object.
+*
+* `ProcessedAsset` is a discriminated union. Switching on `asset.category`
+* narrows the record to the exact type required by its specialized renderer.
+* Those renderers register all physical files owned by the asset in `context`
+* and return one already-indented TypeScript property line.
+*
+* In the canonical example, the first call receives the complete `click`
+* record, including its bundle, runtime ID, and selected audio file:
+*
+* ```ts
+* {
+*   bundle: 'primary',
+*   category: 'sounds',
+*   id: 'click',
+*   file: {
+*     format: 'm4a',
+*     path: '/project/assets/generated/sounds/click.m4a',
+*   },
+* }
+* ```
+*
+* Rendering it registers the selected M4A file as `sound_0` and returns:
+*
+* ```ts
+* '      "click": sound_0,'
+* ```
+*
+* The next call receives the complete two-page `hero` record from the same
+* `primary` bundle:
+*
+* ```ts
+* {
+*   bundle: 'primary',
+*   category: 'spines',
+*   id: 'hero',
+*   files: {
+*     skeleton: {
+*       format: 'json',
+*       path: '/project/assets/generated/spines/hero/skeleton.json',
+*     },
+*     atlas: {
+*       format: 'atlas',
+*       path: '/project/assets/generated/spines/hero/atlas.atlas',
+*     },
+*     images: [
+*       {
+*         format: 'webp',
+*         path: '/project/assets/generated/spines/hero/images/page0.webp',
+*       },
+*       {
+*         format: 'avif',
+*         path: '/project/assets/generated/spines/hero/images/page1.avif',
+*       },
+*     ],
+*   },
+*   runtime: { scale: 0.5 },
+* }
+* ```
+*
+* Because `click` already registered `sound_0`, rendering `hero` registers
+* `spine_1`, `spine_2`, `image_3`, and `image_4`, then returns exactly one
+* property line:
+*
+* ```ts
+* '      "hero": { format: "json", skel: spine_1, atlas: spine_2, images: [image_3, image_4], scale: 0.5 },'
+* ```
+*
+* The renderer therefore returns one line per logical asset, not one line per
+* generated file.
+*
+* @param asset - One complete logical runtime asset from processing.
+* @param context - Module-wide state used to register the asset's files.
+* @returns One indented TypeScript property line for the asset.
+*/
+function renderAssetEntry(asset, context) {
+	switch (asset.category) {
+		case "atlases": return renderAtlasEntry(asset, context);
+		case "fonts": return renderFontEntry(asset, context);
+		case "locales": return renderLocaleEntry(asset, context);
+		case "shaders": return renderShaderEntry(asset, context);
+		case "sounds": return renderSoundEntry(asset, context);
+		case "spines": return renderSpineEntry(asset, context);
+		case "sprites":
+		case "textures": return renderImageEntry(asset, context);
+		default: return asset;
+	}
+}
+/**
+* Writes one fully rendered assets module to its final destination.
+*
+* In the canonical example, `file` is
+* `/project/src/assets/assets.gen.ts` and `source` is the complete module string
+* returned by `renderAssetsModule`. The function creates
+* `/project/src/assets` when necessary and writes that string unchanged to
+* `assets.gen.ts`. It performs no rendering, formatting, or additional import
+* discovery and resolves without a return value after the write completes.
+*
+* @param file - Absolute destination of the generated TypeScript module.
+* @param source - Complete module source returned by `renderAssetsModule`.
+* @returns A promise that resolves after the module has been written.
+*/
+async function writeAssetsModule(file, source) {
+	await mkdir(dirname(file), { recursive: true });
+	await writeFile(file, source);
+}
+//#endregion
+//#region src/emitters/emit-registries.ts
+/**
+* Emits one bundle-independent registry module per supported category and one index.
+*
+* Rendering first produces every complete module in memory. Writing then owns
+* directory creation and filesystem output. Keeping those phases separate
+* prevents partial rendering logic from being mixed with filesystem work.
+*
+* Every build with registry emission enabled creates the complete registry set:
+*
+* ```text
+* registries/
+*   atlases.ts
+*   fonts.ts
+*   locales.ts
+*   shaders.ts
+*   sounds.ts
+*   spines.ts
+*   sprites.ts
+*   textures.ts
+*   index.ts
+* ```
+*
+* Empty categories still receive an empty module, keeping generated imports
+* stable. The canonical `assetCategories` order determines file creation and
+* index exports.
+*
+* @param directory - Absolute directory that will contain generated registries.
+* @param assetGroups - Processed assets organized once for all emitters.
+*/
+async function emitRegistries(directory, assetGroups) {
+	await writeRegistryModules(directory, renderRegistryModules(assetGroups));
+}
+/**
+* Renders every category registry and the re-exporting index in memory.
+*
+* Every supported category reads its complete bundle-independent bucket and
+* produces one module, including categories with no assets. The index is added
+* last so the returned array mirrors the intended write order.
+*
+* For a build containing only the sound `click`, the returned array still
+* contains one module for every supported category plus `index.ts`. Its sound
+* item is:
+*
+* ```ts
+* {
+*   filename: 'sounds.ts',
+*   source: `// AUTO-GENERATED FILE - DO NOT EDIT
+* // Generated by @replayablejs/assets
+*
+* export const sounds = {
+*   "click": "click"
+* } as const;
+* `,
+* }
+* ```
+*
+* @param assetGroups - Processed assets organized once for all emitters.
+* @returns Complete registry modules ready to be written without further rendering.
+*/
+function renderRegistryModules(assetGroups) {
+	const categoryRegistryModules = assetCategories.map((category) => renderRegistryModule(category, assetGroups.categories));
+	const registryIndexModule = {
+		filename: "index.ts",
+		source: renderRegistryIndex()
+	};
+	return [...categoryRegistryModules, registryIndexModule];
+}
+/**
+* Writes already-rendered registry modules into one generated directory.
+*
+* This function performs no grouping, category dispatch, or serialization. It
+* creates the destination directory and writes modules in the order supplied
+* by `renderRegistryModules`.
+*
+* @param directory - Absolute directory that will contain generated registries.
+* @param modules - Complete filenames and sources produced during rendering.
+*/
+async function writeRegistryModules(directory, modules) {
+	await mkdir(directory, { recursive: true });
+	for (const module of modules) await writeFile(resolve(directory, module.filename), module.source);
+}
+/**
+* Renders one complete bundle-independent registry module for a category.
+*
+* Category buckets are already combined and ordered by the pipeline. This
+* function delegates the category-specific data shape to
+* `renderCategoryRegistry`, then owns the generated TypeScript module around
+* that value.
+*
+* For category `sounds` and rendered registry data
+* `{ click: 'click' }`, the complete return value is:
+*
+* ```ts
+* {
+*   filename: 'sounds.ts',
+*   source: `// AUTO-GENERATED FILE - DO NOT EDIT
+* // Generated by @replayablejs/assets
+*
+* export const sounds = {
+*   "click": "click"
+* } as const;
+* `,
+* }
+* ```
+*
+* @param category - Category used for bucket selection and the exported name.
+* @param assets - All processed assets grouped by category across the build.
+* @returns One complete generated category registry module.
+*/
+function renderRegistryModule(category, assets) {
+	const source = renderGeneratedModule([`export const ${category} = ${renderRegistryObject(renderCategoryRegistry(category, assets))} as const;`]);
+	return {
+		filename: `${category}.ts`,
+		source
+	};
+}
+/**
+* Selects the concrete registry renderer for one typed category bucket.
+*
+* `AssetsByCategory` preserves the relationship between every category name and
+* its processed asset type. The switch therefore passes atlas assets to the
+* atlas renderer, font assets to the font renderer, and so on without filtering
+* or type assertions. Sprites and textures intentionally share the image
+* registry representation.
+*
+* @param category - Category whose registry should be rendered.
+* @param assets - All typed category buckets across the complete build.
+* @returns The rendered registry for the populated category bucket.
+*/
+function renderCategoryRegistry(category, assets) {
+	switch (category) {
+		case "atlases": return renderAtlasRegistry(assets.atlases);
+		case "fonts": return renderFontRegistry(assets.fonts);
+		case "locales": return renderLocaleRegistry(assets.locales);
+		case "shaders": return renderShaderRegistry(assets.shaders);
+		case "sounds": return renderSoundRegistry(assets.sounds);
+		case "spines": return renderSpineRegistry(assets.spines);
+		case "sprites": return renderImageRegistry(assets.sprites);
+		case "textures": return renderImageRegistry(assets.textures);
+		default: return category;
+	}
+}
+/**
+* Serializes the index that re-exports every generated category registry.
+*
+* Given the canonical asset categories, the returned module contains the
+* complete registry set in canonical order:
+*
+* ```ts
+* // AUTO-GENERATED FILE - DO NOT EDIT
+* // Generated by @replayablejs/assets
+*
+* export { sprites } from './sprites.js';
+* export { textures } from './textures.js';
+* export { sounds } from './sounds.js';
+* export { fonts } from './fonts.js';
+* export { locales } from './locales.js';
+* export { atlases } from './atlases.js';
+* export { spines } from './spines.js';
+* export { shaders } from './shaders.js';
+* ```
+*
+* @returns The complete generated index source, including its final newline.
+*/
+function renderRegistryIndex() {
+	return renderGeneratedModule([...assetCategories.map((category) => `export { ${category} } from './${category}.js';`)]);
+}
+//#endregion
+//#region src/emitters/emit-build-outputs.ts
+/**
+* Coordinates every source-code output produced from processed assets.
+*
+* The runtime assets module is mandatory and is always emitted first. Developer
+* registries are optional: when registry configuration is absent from the
+* normalized build context, there is no registry work to perform.
+*
+* For example, one build may write:
+*
+* ```text
+* src/assets/assets.gen.ts
+* src/assets/registries/index.ts
+* src/assets/registries/atlases.ts
+* src/assets/registries/fonts.ts
+* src/assets/registries/locales.ts
+* src/assets/registries/shaders.ts
+* src/assets/registries/sounds.ts
+* src/assets/registries/spines.ts
+* src/assets/registries/sprites.ts
+* src/assets/registries/textures.ts
+* ```
+*
+* `BuildContext` already contains absolute, validated output paths, while
+* `AssetGroups` contains prepared bundle and bundle-independent category views.
+* This function therefore performs no processing, grouping, or sorting. Rendering and
+* filesystem writes remain owned by the specialized emitters. Keeping the
+* calls sequential also makes the output order and any partial failure
+* straightforward to follow.
+*
+* @param context - Validated absolute paths controlling generated outputs.
+* @param assetGroups - Processed assets organized for source-code emission.
+*/
+async function emitBuildOutputs(context, assetGroups) {
+	await emitAssetsModule(context.assetsFile, assetGroups);
+	if (context.registriesDirectory !== void 0) await emitRegistries(context.registriesDirectory, assetGroups);
+}
+//#endregion
+//#region src/pipeline/asset-groups.ts
+/**
+* Organizes the flat processing result before it enters the emitter layer.
+*
+* Processors intentionally return independent asset records. The assets module
+* needs bundles containing categories, while registries need categories across
+* the complete build. This transition constructs both views once so emitters
+* can render without regrouping or sorting.
+*
+* For these processed records:
+*
+* ```ts
+* [
+*   { bundle: 'secondary', category: 'sprites', id: 'logo', ... },
+*   { bundle: 'primary', category: 'sounds', id: 'click', ... },
+*   { bundle: 'primary', category: 'sprites', id: 'background', ... },
+* ]
+* ```
+*
+* the returned bundle hierarchy is equivalent to:
+*
+* ```text
+* primary
+*   sounds  -> [click]
+*   sprites -> [background]
+* secondary
+*   sprites -> [logo]
+* ```
+*
+* The parallel category view contains `sounds -> [click]` and
+* `sprites -> [background, logo]`, without bundle boundaries.
+*
+* Primary is always created, even when it contains no assets. Secondary is
+* included only when at least one processed asset belongs to it. Only references
+* are reorganized; processed asset records are not copied or changed.
+*
+* @param processedAssets - Flat logical runtime assets produced by processing.
+* @returns Assets grouped and ordered for deterministic source generation.
+*/
+function groupAssets(processedAssets) {
+	const allCategories = createEmptyCategories();
+	const mutableBundles = /* @__PURE__ */ new Map([["primary", createEmptyCategories()]]);
+	for (const asset of processedAssets) {
+		addAsset(allCategories, asset);
+		let categories = mutableBundles.get(asset.bundle);
+		if (categories === void 0) {
+			categories = createEmptyCategories();
+			mutableBundles.set(asset.bundle, categories);
+		}
+		addAsset(categories, asset);
+	}
+	const bundles = [];
+	for (const name of assetBundleNames) {
+		const categories = mutableBundles.get(name);
+		if (categories === void 0) continue;
+		sortCategoryAssets(categories);
+		bundles.push({
+			name,
+			categories
+		});
+	}
+	sortCategoryAssets(allCategories);
+	return {
+		bundles,
+		categories: allCategories
+	};
+}
+/** Sorts every category bucket by runtime ID for deterministic source output. */
+function sortCategoryAssets(categories) {
+	for (const category of assetCategories) categories[category].sort((left, right) => left.id.localeCompare(right.id));
+}
+/**
+* Creates the complete set of typed category buckets for one new bundle.
+* Keeping this object explicit makes TypeScript require a bucket whenever a
+* new asset category is added.
+*/
+function createEmptyCategories() {
+	return {
+		atlases: [],
+		fonts: [],
+		locales: [],
+		shaders: [],
+		sounds: [],
+		spines: [],
+		sprites: [],
+		textures: []
+	};
+}
+/**
+* Adds one discriminated processed asset to its matching typed bucket.
+*
+* The exhaustive switch narrows each union member before writing it. A dynamic
+* `categories[asset.category].push(asset)` loses that relationship in
+* TypeScript and requires an unsafe assertion.
+*/
+function addAsset(categories, asset) {
+	switch (asset.category) {
+		case "atlases":
+			categories.atlases.push(asset);
+			break;
+		case "fonts":
+			categories.fonts.push(asset);
+			break;
+		case "locales":
+			categories.locales.push(asset);
+			break;
+		case "shaders":
+			categories.shaders.push(asset);
+			break;
+		case "sounds":
+			categories.sounds.push(asset);
+			break;
+		case "spines":
+			categories.spines.push(asset);
+			break;
+		case "sprites":
+			categories.sprites.push(asset);
+			break;
+		case "textures":
+			categories.textures.push(asset);
+			break;
+		default: return asset;
+	}
+}
+//#endregion
+//#region src/pipeline/build-result.ts
+/** Summarizes the logical assets and physical files produced by a successful build. */
+function createBuildResult(context, assetGroups) {
+	let emittedAssets = 0;
+	let emittedFiles = 0;
+	for (const bundle of assetGroups.bundles) for (const category of assetCategories) for (const asset of bundle.categories[category]) {
+		emittedAssets += 1;
+		emittedFiles += countGeneratedFiles(asset);
+	}
+	return {
+		bundles: assetGroups.bundles.map((bundle) => bundle.name),
+		emittedAssets,
+		emittedFiles,
+		outputDirectory: context.outputRoot
+	};
+}
+/** Counts the physical files owned by one complete runtime asset. */
+function countGeneratedFiles(asset) {
+	switch (asset.category) {
+		case "atlases":
+		case "shaders": return 2;
+		case "spines": return asset.files.images.length + 2;
+		case "fonts":
+		case "locales":
+		case "sounds":
+		case "sprites":
+		case "textures": return 1;
+		default: return asset;
+	}
+}
+//#endregion
+//#region src/pipeline/context.ts
+/**
+* Resolves configured project-relative paths into validated absolute paths.
+*
+* All generated paths must stay inside the project, and authored sources must
+* remain separate from every generated tree. Registries may live inside
+* `outDir` when the complete output tree is owned by Replayable. These checks
+* protect authored files when the completed build replaces the previous output.
+* Filesystem symlink checks run separately before staging and publication.
+*/
+function createBuildContext(config, workingDirectory) {
+	const workspaceRoot = resolve(workingDirectory);
+	const sourceRoot = resolve(workspaceRoot, config.sourceDir);
+	const outputRoot = resolve(workspaceRoot, config.outDir);
+	const assetsFile = resolve(workspaceRoot, config.emit.assets);
+	const registriesDirectory = config.emit.registries === void 0 ? void 0 : resolve(workspaceRoot, config.emit.registries);
+	assertSafeProjectPath(workspaceRoot, sourceRoot, "sourceDir");
+	assertSafeProjectPath(workspaceRoot, outputRoot, "outDir");
+	assertSafeProjectPath(workspaceRoot, assetsFile, "emit.assets");
+	if (registriesDirectory !== void 0) assertSafeProjectPath(workspaceRoot, registriesDirectory, "emit.registries");
+	if (pathsOverlap(sourceRoot, outputRoot)) throw new Error("outDir and sourceDir must be separate, non-nested directories.");
+	if (pathsOverlap(assetsFile, sourceRoot)) throw new Error("emit.assets must be separate from sourceDir.");
+	if (pathsOverlap(assetsFile, outputRoot) && !isNestedInside(assetsFile, outputRoot)) throw new Error("emit.assets must be separate from or nested inside outDir.");
+	if (registriesDirectory !== void 0 && pathsOverlap(registriesDirectory, sourceRoot)) throw new Error("emit.registries must be separate from sourceDir.");
+	if (registriesDirectory !== void 0) {
+		const registriesNestedInsideOutput = isNestedInside(registriesDirectory, outputRoot);
+		if (pathsOverlap(registriesDirectory, outputRoot) && !registriesNestedInsideOutput) throw new Error("emit.registries must be separate from or nested inside outDir.");
+		if (pathsOverlap(assetsFile, registriesDirectory)) throw new Error("emit.assets must be separate from emit.registries.");
+	}
+	return {
+		assetsFile,
+		outputRoot,
+		registriesDirectory,
+		sourceRoot
+	};
+}
+/** Returns whether `target` is strictly nested beneath `directory`. */
+function isNestedInside(target, directory) {
+	return target.startsWith(`${directory}${sep}`);
+}
+function pathsOverlap(left, right) {
+	return left === right || left.startsWith(`${right}${sep}`) || right.startsWith(`${left}${sep}`);
+}
+function assertSafeProjectPath(workingDirectory, target, field) {
+	const pathFromWorkingDirectory = relative(workingDirectory, target);
+	if (pathFromWorkingDirectory === "" || isAbsolute(pathFromWorkingDirectory) || pathFromWorkingDirectory === ".." || pathFromWorkingDirectory.startsWith(`..${sep}`)) throw new Error(`${field} must resolve to a path inside the project directory.`);
+}
+//#endregion
+//#region src/pipeline/validate-build-paths.ts
+/**
+* Rejects symlinks below the project root before reading or replacing build trees.
+* Lexical containment alone cannot protect `linked-directory/generated`: an
+* existing parent may point outside the project or back into authored sources.
+* The project root itself may be a symlink; paths beneath it may not be.
+* This checks the current filesystem, not concurrent hostile filesystem changes.
+*/
+async function validateBuildPaths(context, projectRoot) {
+	const paths = [
+		context.sourceRoot,
+		context.outputRoot,
+		context.assetsFile
+	];
+	if (context.registriesDirectory !== void 0) paths.push(context.registriesDirectory);
+	for (const path of paths) {
+		let parent = resolve(projectRoot);
+		for (const segment of relative(parent, path).split(sep)) {
+			parent = resolve(parent, segment);
+			const entry = await lstat(parent).catch((error) => {
+				if (error instanceof Error && "code" in error && error.code === "ENOENT") return;
+				throw error;
+			});
+			if (entry === void 0) break;
+			if (entry.isSymbolicLink()) throw new Error(`Asset build paths must not contain symbolic links: ${parent}`);
+		}
+	}
+}
+//#endregion
+//#region src/pipeline/create-build-staging.ts
+/**
+* Keeps the last successful outputs untouched while a replacement is built.
+* The temporary `prepared` tree mirrors project-relative destinations, so
+* generated relative imports remain correct after publication. Sources still
+* point at the authored tree; only output paths are redirected.
+*
+* Output roots may be separate or contain generated modules. Only non-nested
+* roots are moved, preventing a module from being installed twice. Publication
+* backs up old roots and restores them on failure. Failed restoration retains
+* the recovery directory and reports its path instead of deleting the backup.
+* This is failure recovery, not a crash-safe transaction or a concurrent-build lock.
+*/
+async function createBuildStaging(context, workingDirectory) {
+	const projectRoot = resolve(workingDirectory);
+	await validateBuildPaths(context, projectRoot);
+	const directory = await mkdtemp(join(projectRoot, ".replayable-assets-"));
+	const preparedRoot = join(directory, "prepared");
+	let preserveBackup = false;
+	const stagedContext = {
+		sourceRoot: context.sourceRoot,
+		outputRoot: stagePath(context.outputRoot),
+		assetsFile: stagePath(context.assetsFile),
+		registriesDirectory: context.registriesDirectory === void 0 ? void 0 : stagePath(context.registriesDirectory)
+	};
+	const destinations = [context.outputRoot, context.assetsFile];
+	if (context.registriesDirectory !== void 0) destinations.push(context.registriesDirectory);
+	const replacements = destinations.filter((path) => !destinations.some((parent) => path.startsWith(`${parent}${sep}`))).map((destination, index) => ({
+		destination,
+		prepared: stagePath(destination),
+		backup: join(directory, "previous", String(index)),
+		backedUp: false,
+		installed: false
+	}));
+	return {
+		context: stagedContext,
+		commit,
+		dispose
+	};
+	/** Preserves the relative distance between every generated module and asset. */
+	function stagePath(path) {
+		return join(preparedRoot, relative(projectRoot, path));
+	}
+	/** Publishes completed outputs, undoing earlier replacements if a later one fails. */
+	async function commit() {
+		await validateBuildPaths(context, projectRoot);
+		await mkdir(stagedContext.outputRoot, { recursive: true });
+		await mkdir(join(directory, "previous"));
+		try {
+			for (const replacement of replacements) {
+				await mkdir(dirname(replacement.destination), { recursive: true });
+				replacement.backedUp = await backupOutput(replacement);
+				await rename(replacement.prepared, replacement.destination);
+				replacement.installed = true;
+			}
+		} catch (error) {
+			const restoreErrors = await restoreOutputs(replacements);
+			if (restoreErrors.length > 0) {
+				preserveBackup = true;
+				throw new AggregateError([error, ...restoreErrors], `Asset publication failed. Recovery files remain at ${directory}.`, { cause: error });
+			}
+			throw error;
+		}
+	}
+	/** Removes staged files and obsolete backups, never a required recovery copy. */
+	async function dispose() {
+		if (!preserveBackup) await rm(directory, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+/** Only a missing destination means there is no previous output to preserve. */
+async function backupOutput(replacement) {
+	try {
+		await rename(replacement.destination, replacement.backup);
+		return true;
+	} catch (error) {
+		if (error instanceof Error && "code" in error && error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+/** Attempts every rollback in reverse publication order, retaining all failures. */
+async function restoreOutputs(replacements) {
+	const errors = [];
+	for (const replacement of [...replacements].reverse()) try {
+		if (replacement.installed) await rm(replacement.destination, {
+			recursive: true,
+			force: true
+		});
+		if (replacement.backedUp) await rename(replacement.backup, replacement.destination);
+	} catch (error) {
+		errors.push(error);
+	}
+	return errors;
+}
+//#endregion
+//#region src/pipeline/validate-output-claims.ts
+/**
+* Reserves physical output identities before concurrent processors start.
+* Bundles are runtime groups, not separate filesystem trees. For example,
+* primary `textures/logo.png` and secondary `textures/logo.webp` would both
+* write candidates at `textures/logo.*`, so they must not share that basename.
+* Runtime-ID validation still runs after processing for expanded atlas sheets.
+*/
+function validateOutputClaims(assets) {
+	const owners = /* @__PURE__ */ new Map();
+	for (const asset of assets) {
+		const path = "outputBasePath" in asset ? asset.outputBasePath : asset.outputDirectory;
+		const owner = owners.get(path);
+		if (owner !== void 0) throw new Error(`Asset output collision: ${owner} and ${asset.relativePath} both write ${path}.`);
+		owners.set(path, asset.relativePath);
+	}
+}
+//#endregion
+//#region src/pipeline/source-path.ts
+/** Removes only the final extension from a source-relative POSIX path. */
+function removeExtension(path) {
+	const extension = extname$1(path);
+	return extension === "" ? path : path.slice(0, -extension.length);
+}
+//#endregion
+//#region src/pipeline/asset-identity.ts
+/**
+* Rejects logical assets that would use the same generated runtime property.
+*
+* An ID is scoped by both bundle and category. `primary.sprites.logo` and
+* `secondary.sprites.logo` are independent, as are `primary.sprites.logo` and
+* `primary.textures.logo`. Generated file formats and physical file counts do
+* not participate because every processed record now represents one complete
+* runtime asset.
+*/
+function assertUniqueRuntimeAssetIds(assets) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const asset of assets) {
+		const key = JSON.stringify([
+			asset.bundle,
+			asset.category,
+			asset.id
+		]);
+		if (seen.has(key)) throw new Error(`Duplicate runtime asset ID: ${asset.bundle}:${asset.category}:${asset.id}`);
+		seen.add(key);
+	}
+}
+/** Creates the final runtime ID used for one generated atlas sheet. */
+function createAtlasSheetId(atlasId, sheetName) {
+	return join$1(dirname$1(atlasId), sheetName);
+}
+/** Derives the runtime ID shared by source and generated forms of a simple asset. */
+function createSimpleAssetId(asset) {
+	const categoryPrefix = `${asset.category}/`;
+	return removeExtension(asset.relativePath.startsWith(categoryPrefix) ? asset.relativePath.slice(categoryPrefix.length) : asset.relativePath);
+}
+//#endregion
+//#region src/pipeline/settle-asset-tasks.ts
+/**
+* Waits for every started task before reporting a processing failure.
+* Promise.all rejects early: other encoders could still write after rollback
+* starts. Each concurrent writing layer must settle its own children first.
+* Results retain input order, and a single failure retains its original error.
+*/
+async function settleAssetTasks(tasks) {
+	const results = await Promise.allSettled(tasks);
+	const values = [];
+	const errors = [];
+	for (const result of results) if (result.status === "fulfilled") values.push(result.value);
+	else errors.push(result.reason);
+	if (errors.length === 1) throw errors[0];
+	if (errors.length > 1) throw new AggregateError(errors, "Multiple asset tasks failed.");
+	return values;
+}
+//#endregion
+//#region src/adapters/pixi-atlas-parser.ts
+const pixiAtlasLayoutSchema = z.object({ frames: z.union([z.record(z.string(), z.unknown()), z.array(z.object({ filename: z.string() }))]) });
+/**
+* Parses one third-party Pixi atlas layout while it is still in memory.
+*
+* Pixi atlas exporters support either an object keyed by frame name or an
+* array whose entries carry a `filename`. Replayable extracts those names for
+* registry generation and serializes the original object—not Zod's parsed
+* projection—so unrelated runtime fields such as `meta` remain intact.
+*
+* @param buffer - UTF-8 JSON bytes returned by the texture packer.
+* @returns Frame metadata and the complete minified JSON written at runtime.
+* @throws When the packer returns malformed JSON or an unsupported frame shape.
+*/
+function parsePixiAtlasLayout(buffer) {
+	const layout = JSON.parse(buffer.toString("utf8"));
+	const { frames } = pixiAtlasLayoutSchema.parse(layout);
+	return {
+		frameNames: Array.isArray(frames) ? frames.map((frame) => frame.filename) : Object.keys(frames),
+		serializedJson: JSON.stringify(layout)
+	};
+}
+//#endregion
+//#region src/adapters/texture-packer.ts
+/** Hard sheet boundary that limits generated texture dimensions and build memory. */
+const MAX_ATLAS_SIZE = 2048;
+const BASE_ATLAS_PACKER_OPTIONS = {
+	width: MAX_ATLAS_SIZE,
+	height: MAX_ATLAS_SIZE,
+	fixedSize: false,
+	packer: "OptimalPacker",
+	exporter: "Pixi",
+	filter: "none",
+	scaleMethod: "BILINEAR",
+	trimMode: "trim",
+	alphaThreshold: 0,
+	detectIdentical: true,
+	prependFolderName: false,
+	removeFileExtension: true
+};
+/**
+* Reads and packs one logical atlas into validated in-memory sheets.
+*
+* `free-tex-packer-core` returns a flat file list. A small atlas normally
+* yields `name.json` and `name.png`; a multi-sheet atlas yields
+* `name-0.{json,png}`, `name-1.{json,png}`, and so on. This adapter converts
+* that third-party representation into complete JSON/PNG sheet pairs.
+*
+* @param imagePaths - Absolute source-image paths belonging to one logical atlas.
+* @param atlasId - Stable logical ID used as the generated texture basename.
+* @param options - Validated packing, scaling, padding, and trimming settings.
+* @returns Complete in-memory sheets ordered by their generated names.
+*/
+async function packAtlasSources(imagePaths, atlasId, options) {
+	const images = await readAtlasSourceImages(imagePaths);
+	const packerOptions = createTexturePackerOptions(atlasId, options);
+	return collectPackedAtlasSheets(await packAsync(images, packerOptions), atlasId);
+}
+/** Reads source images into the in-memory shape required by the texture packer. */
+async function readAtlasSourceImages(paths) {
+	return Promise.all(paths.map(async (path) => ({
+		contents: await readFile(path),
+		path: basename(path)
+	})));
+}
+/** Combines fixed adapter behavior with options resolved for one atlas. */
+function createTexturePackerOptions(atlasId, options) {
+	return {
+		...BASE_ATLAS_PACKER_OPTIONS,
+		textureName: basename(atlasId),
+		powerOfTwo: options.powerOfTwo,
+		scale: options.scale,
+		padding: options.padding,
+		extrude: options.extrude,
+		allowRotation: options.allowRotation,
+		allowTrim: options.allowTrim
+	};
+}
+/**
+* Converts untrusted texture-packer output into complete atlas sheets.
+*
+* Replayable requires exactly one JSON layout and one PNG intermediate texture
+* with the same basename for every sheet. Validation happens before files are
+* written, so malformed packer output cannot leave a partially generated atlas
+* on disk.
+*
+* A single-sheet flat result:
+*
+* ```text
+* ui.json, ui.png
+* ```
+*
+* becomes one `{ name: 'ui', json, png }` value. A split result:
+*
+* ```text
+* ui-1.png, ui-0.json, ui-0.png, ui-1.json
+* ```
+*
+* becomes two complete values ordered as `ui-0`, then `ui-1`, regardless of
+* the third-party file order.
+*
+* @param files - Flat files returned by `free-tex-packer-core`.
+* @param atlasId - Logical atlas ID used in validation diagnostics.
+* @returns Complete sheets sorted by generated sheet name.
+* @throws When output is empty, has an unsupported extension, repeats a file
+* role, or omits either member of a JSON/PNG pair.
+*/
+function collectPackedAtlasSheets(files, atlasId) {
+	const partialSheets = /* @__PURE__ */ new Map();
+	for (const file of files) {
+		const extension = extname(file.name).slice(1).toLowerCase();
+		const sheetName = basename(file.name, extname(file.name));
+		const sheet = partialSheets.get(sheetName) ?? {};
+		switch (extension) {
+			case "json":
+				if (sheet.json !== void 0) throw new Error(`Atlas ${atlasId} sheet ${sheetName} has duplicate JSON layouts.`);
+				sheet.json = file;
+				break;
+			case "png":
+				if (sheet.png !== void 0) throw new Error(`Atlas ${atlasId} sheet ${sheetName} has duplicate PNG textures.`);
+				sheet.png = file;
+				break;
+			default: throw new Error(`Atlas ${atlasId} produced unsupported file ${file.name}.`);
+		}
+		partialSheets.set(sheetName, sheet);
+	}
+	if (partialSheets.size === 0) throw new Error(`Atlas ${atlasId} produced no sheets.`);
+	return [...partialSheets.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, sheet]) => {
+		if (sheet.json === void 0 || sheet.png === void 0) throw new Error(`Atlas ${atlasId} sheet ${name} must contain one JSON and one PNG file.`);
+		return {
+			json: sheet.json,
+			name,
+			png: sheet.png
+		};
+	});
+}
+//#endregion
+//#region src/processors/output-selection.ts
+/**
+* Selects the smallest file among equivalent generated candidates.
+*
+* The function measures the files on disk, deletes every larger candidate, and
+* returns the measured winner.
+* For example, `[hero.avif 8 KB, hero.webp 12 KB]` selects only `hero.avif`.
+* Equal sizes preserve input order, so the earlier automatic candidate wins a
+* tie. Callers must pass candidates for the same logical asset or texture page.
+*/
+async function selectSmallestOutput(outputs) {
+	const firstOutput = outputs[0];
+	if (firstOutput === void 0) throw new Error("Cannot select an output from an empty candidate list.");
+	if (outputs.length === 1) return firstOutput;
+	const smallestOutput = (await settleAssetTasks(outputs.map(async (output) => ({
+		output,
+		size: (await stat(output.path)).size
+	})))).reduce((selected, candidate) => candidate.size < selected.size ? candidate : selected).output;
+	await settleAssetTasks(outputs.filter((output) => output !== smallestOutput).map((output) => rm(output.path, { force: true })));
+	return smallestOutput;
+}
+//#endregion
+//#region src/processors/image-encoder.ts
+const DEFAULT_IMAGE_QUALITY = {
+	avif: 72,
+	jpg: 82,
+	webp: 80
+};
+/**
+* Selects the encodings worth comparing for an image.
+*
+* Lossless assets compare WebP with PNG. Lossy opaque assets can use JPEG,
+* while assets containing transparent pixels use PNG as their alpha-safe
+* conventional fallback. AVIF and WebP are considered in both lossy cases.
+*/
+function selectImageCandidateFormats(options, image) {
+	if (options.lossless) return ["webp", "png"];
+	return image.isOpaque ? [
+		"avif",
+		"webp",
+		"jpg"
+	] : [
+		"avif",
+		"webp",
+		"png"
+	];
+}
+/**
+* Scales an image once and inspects the resulting pixels for transparency.
+*
+* The inspection happens after resizing because interpolation can change alpha
+* values near transparent edges. A lossless intermediate guarantees that each
+* candidate encoder receives exactly the same transformed pixels.
+*/
+async function prepareImage(input, scale, sourcePath) {
+	let image = sharp(input);
+	if (scale !== 1) {
+		const metadata = await image.metadata();
+		if (metadata.width === void 0) throw new Error(`Cannot determine image width for scaling: ${sourcePath}`);
+		image = image.resize({ width: Math.max(1, Math.round(metadata.width * scale)) });
+	}
+	const buffer = await image.png().toBuffer();
+	const { isOpaque } = await sharp(buffer).stats();
+	return {
+		buffer,
+		isOpaque
+	};
+}
+/**
+* Writes every applicable image candidate and returns the smallest generated file.
+*
+* Standalone images, atlas sheets, and Spine pages all pass through this same
+* boundary, ensuring that they use identical preparation, encoding, comparison,
+* and cleanup behavior.
+*/
+async function writeSmallestImage(request) {
+	const prepared = await prepareImage(request.input, request.options.scale, request.sourcePath);
+	return selectSmallestOutput(await settleAssetTasks(selectImageCandidateFormats(request.options, prepared).map(async (format) => {
+		const path = `${request.outputBasePath}.${format}`;
+		await writeImageVariant(prepared.buffer, path, format, request.options);
+		return {
+			format,
+			path
+		};
+	})));
+}
+/** Writes one encoded image candidate from a prepared image buffer. */
+async function writeImageVariant(input, outputPath, format, options) {
+	await mkdir(dirname(outputPath), { recursive: true });
+	let image = sharp(input);
+	const quality = options.lossless ? void 0 : options.quality;
+	switch (format) {
+		case "avif":
+			image = image.avif({ quality: quality ?? DEFAULT_IMAGE_QUALITY.avif });
+			break;
+		case "jpg":
+			image = image.jpeg({ quality: quality ?? DEFAULT_IMAGE_QUALITY.jpg });
+			break;
+		case "png":
+			image = image.png();
+			break;
+		case "webp": image = options.lossless ? image.webp({ lossless: true }) : image.webp({ quality: quality ?? DEFAULT_IMAGE_QUALITY.webp });
+	}
+	await image.toFile(outputPath);
+}
+//#endregion
+//#region src/processors/categories/atlas.ts
+/**
+* Packs all source images in one logical atlas and writes its generated files.
+*
+* The texture-packer adapter returns validated PNG sheets with matching Pixi
+* layouts. Those PNGs are lossless intermediates rather than predetermined
+* runtime formats. Each one passes through the shared image encoder, which
+* keeps only the smallest applicable AVIF, WebP, JPEG, or PNG result.
+*
+* One packed sheet produces one processed runtime entry:
+*
+* ```text
+* ui -> [{ id: 'ui', files: { json, image } }]
+* ```
+*
+* When the source images exceed one sheet, the generated sheet names become
+* distinct runtime IDs while preserving their logical atlas directory:
+*
+* ```text
+* ui -> [
+*   { id: 'ui-0', files: { json, image } },
+*   { id: 'ui-1', files: { json, image } },
+* ]
+* ```
+*/
+async function processAtlas(asset) {
+	const { id, images } = asset.atlas;
+	return writeAtlasSheets(asset, await packAtlasSources(images, id, asset.options));
+}
+/** Writes validated sheets sequentially to limit peak image-encoding memory. */
+async function writeAtlasSheets(asset, sheets) {
+	const processedSheets = [];
+	for (const sheet of sheets) processedSheets.push(await writeAtlasSheet(asset, sheet));
+	return processedSheets;
+}
+/** Writes one validated sheet and returns its complete processed runtime value. */
+async function writeAtlasSheet(asset, sheet) {
+	const jsonOutputPath = join(asset.outputDirectory, `${sheet.name}.json`);
+	const imageOutputBasePath = join(asset.outputDirectory, sheet.name);
+	const layout = parsePixiAtlasLayout(sheet.json.buffer);
+	await writeAtlasLayout(layout.serializedJson, jsonOutputPath);
+	const image = await writeSmallestImage({
+		input: sheet.png.buffer,
+		options: {
+			...asset.options,
+			scale: 1
+		},
+		outputBasePath: imageOutputBasePath,
+		sourcePath: `${asset.relativePath} (${sheet.name})`
+	});
+	return {
+		bundle: asset.bundle,
+		category: "atlases",
+		files: {
+			image,
+			json: {
+				format: "json",
+				path: jsonOutputPath
+			}
+		},
+		frameNames: layout.frameNames,
+		id: createAtlasSheetId(asset.atlas.id, sheet.name)
+	};
+}
+/**
+* Writes the already-validated and minified Pixi layout for one atlas sheet.
+*/
+async function writeAtlasLayout(serializedJson, outputPath) {
+	await mkdir(dirname(outputPath), { recursive: true });
+	await writeFile(outputPath, serializedJson);
+}
+//#endregion
+//#region src/adapters/font-subsetter.ts
+/**
+* Loads one source font and returns WOFF2 bytes containing the required glyphs.
+*
+* `charset` is text rather than a list of glyph identifiers. The subsetting
+* engine reads its Unicode characters, keeps the glyphs needed to render them,
+* and may retain related glyphs required by the font's layout substitutions.
+* Duplicate characters do not produce duplicate glyphs.
+*
+* TTF, OTF, WOFF, and WOFF2 sources all cross this adapter boundary as raw
+* bytes and always return WOFF2 bytes. This function does not write a file;
+* the font processor owns the generated output path and filesystem write.
+* Source-read errors and invalid or unsupported font errors intentionally
+* propagate to that processor with their original diagnostics.
+*
+* @param sourcePath - Absolute path of the authored source font.
+* @param charset - Complete text whose characters must remain renderable.
+* @returns Encoded WOFF2 font bytes ready to be written by the processor.
+*
+* @example
+*
+* ```ts
+* const woff2 = await createWoff2Subset(
+*   '/project/raw-assets/fonts/interface.ttf',
+*   'ABCDEFGHIJKLMNOPQRSTUVWXYZԲարև',
+* );
+* ```
+*/
+async function createWoff2Subset(sourcePath, charset) {
+	const sourceFont = await readFile(sourcePath);
+	return subsetFont(sourceFont, charset, { targetFormat: "woff2" });
+}
+//#endregion
+//#region src/processors/categories/font.ts
+/**
+* Subsets and converts one source font into WOFF2.
+*
+* Resolution has already constructed the complete charset from printable
+* ASCII, fixed-language locale values, and font-specific extra characters.
+* TTF, OTF, WOFF, and WOFF2 sources all produce the same WOFF2 output shape.
+* The runtime family is authored configuration; Replayable does not infer or
+* rewrite it from the font's internal metadata.
+*
+* For example:
+*
+* ```text
+* Source:
+*   fonts/ui.ttf
+*   family: Replayable UI
+*   charset: printable ASCII + selected locale characters
+*
+* Generated:
+*   fonts/ui.woff2
+*
+* Processed entry:
+*   {
+*     id: 'ui',
+*     file: { format: 'woff2', path: '.../fonts/ui.woff2' },
+*     runtime: { family: 'Replayable UI' },
+*   }
+* ```
+*
+* The processor returns a one-entry array because the shared dispatcher uses
+* one batch shape for singleton assets and atlases that may generate several
+* sheets.
+*/
+async function processFont(asset) {
+	const { family } = asset.options;
+	const outputPath = `${asset.outputBasePath}.woff2`;
+	await writeFontFile(outputPath, await createWoff2Subset(asset.absolutePath, asset.charset));
+	return [{
+		bundle: asset.bundle,
+		category: "fonts",
+		file: {
+			format: "woff2",
+			path: outputPath
+		},
+		id: createSimpleAssetId(asset),
+		runtime: { family }
+	}];
+}
+/** Writes the generated WOFF2 file, creating its output directory when needed. */
+async function writeFontFile(outputPath, contents) {
+	await mkdir(dirname(outputPath), { recursive: true });
+	await writeFile(outputPath, contents);
+}
+//#endregion
+//#region src/processors/categories/image.ts
+/**
+* Processes one standalone sprite or texture into one selected runtime file.
+*
+* Asset rules configure intent (`lossless`, `quality`, and `scale`), not an
+* output extension. The shared image encoder generates every applicable
+* candidate and keeps only the smallest file, so the emitted runtime value
+* always references one URL.
+*
+* For example, `sprites/ui/button.png` may be encoded as AVIF, WebP, and PNG.
+* If WebP is smallest, only `sprites/ui/button.webp` remains and this function
+* returns one processed sprite containing that file.
+*
+* The absolute path is used to read the source, while the relative path is
+* retained for human-readable processing errors. The resolved category is
+* preserved because this processor serves both `sprites` and `textures`.
+* Runtime `scale` records the image transformation applied by the encoder. The
+* returned one-item array follows the common processor contract: one resolved
+* image produces one processed asset.
+*/
+async function processImage(asset) {
+	const selectedFile = await writeSmallestImage({
+		input: asset.absolutePath,
+		options: asset.options,
+		outputBasePath: asset.outputBasePath,
+		sourcePath: asset.relativePath
+	});
+	return [{
+		bundle: asset.bundle,
+		category: asset.category,
+		file: selectedFile,
+		id: createSimpleAssetId(asset),
+		runtime: { scale: asset.options.scale }
+	}];
+}
+//#endregion
+//#region src/processors/categories/locale.ts
+/**
+* Writes one locale dictionary that was fixed to the build language during resolution.
+*
+* This processor does not parse JSONC or choose translations. Locale resolution
+* has already performed those operations and supplied only the selected value
+* for each phrase. For example, an Armenian build may reach this processor as:
+*
+* ```ts
+* {
+*   play: 'Խաղալ',
+*   install: 'Install', // Armenian was absent, so English was selected.
+* }
+* ```
+*
+* A source named `translations.jsonc` is emitted as runtime-ready
+* `translations.json`. Its top-level phrase IDs are retained beside the file
+* descriptor so registry emission does not need to read and parse that
+* generated JSON again:
+*
+* ```ts
+* {
+*   id: 'translations',
+*   file: { format: 'json', path: '.../locales/translations.json' },
+*   phraseIds: ['play', 'install'],
+* }
+* ```
+*
+* The returned one-item array follows the common processor contract: one
+* resolved locale asset produces one processed file.
+*/
+async function processLocale(asset) {
+	const outputPath = `${asset.outputBasePath}.json`;
+	const serializedLocale = JSON.stringify(asset.resolvedLocale);
+	const phraseIds = Object.keys(asset.resolvedLocale);
+	await mkdir(dirname(outputPath), { recursive: true });
+	await writeFile(outputPath, serializedLocale);
+	return [{
+		bundle: asset.bundle,
+		category: "locales",
+		file: {
+			format: "json",
+			path: outputPath
+		},
+		id: createSimpleAssetId(asset),
+		phraseIds
+	}];
+}
+//#endregion
+//#region src/processors/categories/shader.ts
+/**
+* Copies a vertex/fragment pair without changing its authored GLSL.
+*
+* One resolved shader becomes one logical processed asset that owns its
+* generated vertex and fragment files. Keeping the pair together means every
+* later stage receives a complete runtime shader instead of reconstructing it
+* from unrelated records.
+*
+* For example, the resolved sources:
+*
+* ```text
+* assets/source/shaders/glow/vert.glsl
+* assets/source/shaders/glow/frag.glsl
+* ```
+*
+* are copied byte-for-byte to:
+*
+* ```text
+* assets/generated/shaders/glow/vert.glsl
+* assets/generated/shaders/glow/frag.glsl
+* ```
+*
+* and returned as one processed asset whose ID is `glow` and whose `files`
+* object contains both generated files. The emitter can therefore serialize a
+* complete shader program without pairing independent file records.
+*/
+async function processShader(asset) {
+	const vertexOutputPath = join(asset.outputDirectory, "vert.glsl");
+	const fragmentOutputPath = join(asset.outputDirectory, "frag.glsl");
+	await mkdir(asset.outputDirectory, { recursive: true });
+	const vertexFile = await copyShaderStage(asset.shader.vert, vertexOutputPath);
+	const fragmentFile = await copyShaderStage(asset.shader.frag, fragmentOutputPath);
+	return [{
+		bundle: asset.bundle,
+		category: "shaders",
+		files: {
+			frag: fragmentFile,
+			vert: vertexFile
+		},
+		id: asset.shader.id
+	}];
+}
+/**
+* Copies one shader stage byte-for-byte and describes the generated file.
+*
+* The returned value contains the file's format and path, not its GLSL source.
+* Emitters later use this metadata to create the runtime import.
+*/
+async function copyShaderStage(inputPath, outputPath) {
+	await copyFile(inputPath, outputPath);
+	return {
+		format: "glsl",
+		path: outputPath
+	};
+}
+//#endregion
+//#region src/adapters/audio-transcoder.ts
+/**
+* Runs the bundled FFmpeg executable to produce one encoded audio candidate.
+*
+* The executable is spawned directly rather than through a shell, so paths are
+* passed as literal arguments and require no quoting. Standard output is not
+* used. FFmpeg's standard error is retained because it contains both progress
+* information and the useful diagnostic when decoding or encoding fails.
+*
+* The promise resolves only after FFmpeg exits successfully. It rejects when
+* the executable cannot start or exits with a non-zero status.
+*
+* @example
+*
+* ```ts
+* await transcodeAudio({
+*   format: 'mp3',
+*   inputPath: '/project/raw-assets/sounds/click.wav',
+*   options: { bitrate: 96, channels: 'mono', sampleRate: 32000 },
+*   outputPath: '/project/assets/generated/sounds/click.mp3',
+* });
+* ```
+*/
+function transcodeAudio(request) {
+	const ffmpegArguments = createFfmpegArguments(request);
+	return new Promise((resolve, reject) => {
+		const childProcess = spawn(ffmpeg.path, ffmpegArguments, { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		let diagnostics = "";
+		childProcess.stderr.on("data", (chunk) => {
+			diagnostics += chunk.toString();
+		});
+		childProcess.on("error", reject);
+		childProcess.on("close", (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`FFmpeg failed for ${request.inputPath}: ${diagnostics}`));
+		});
+	});
+}
+/**
+* Converts a transcode request into a deterministic FFmpeg argument list.
+*
+* For an MP3 request using 96 kbps, 32 kHz, and mono audio, the returned
+* arguments represent this command:
+*
+* ```text
+* ffmpeg -y -i click.wav -map 0:a:0 -c:a libmp3lame -b:a 96k -ar 32000 -ac 1 click.mp3
+* ```
+*
+* M4A uses FFmpeg's AAC encoder instead. When `channels` is `source`, the
+* `-ac` pair is omitted and FFmpeg preserves the input stream's channel count.
+* The returned array excludes the executable path because `spawn` receives it
+* separately.
+*/
+function createFfmpegArguments(request) {
+	const { format, inputPath, options, outputPath } = request;
+	const codec = format === "m4a" ? "aac" : "libmp3lame";
+	const channelArguments = createChannelArguments(options.channels);
+	return [
+		"-y",
+		"-i",
+		inputPath,
+		"-map",
+		"0:a:0",
+		"-c:a",
+		codec,
+		"-b:a",
+		`${options.bitrate}k`,
+		"-ar",
+		String(options.sampleRate),
+		...channelArguments,
+		outputPath
+	];
+}
+/** Returns FFmpeg's optional output-channel arguments. */
+function createChannelArguments(channels) {
+	if (channels === "source") return [];
+	return ["-ac", channels === "mono" ? "1" : "2"];
+}
+//#endregion
+//#region src/processors/categories/sound.ts
+const SOUND_CANDIDATE_FORMATS = ["mp3", "m4a"];
+/**
+* Encodes one sound as MP3 and M4A, then keeps the smaller file.
+*
+* Both candidates pass through FFmpeg with the same bitrate, sample rate, and
+* channel configuration. Source files are never copied directly because that
+* would make their encoding settings incomparable with the other candidate.
+*
+* For example, `sounds/ui/click.wav` is encoded as temporary candidates
+* `click.mp3` and `click.m4a`. After their file sizes are measured, only the
+* smaller candidate remains on disk and becomes the file of the returned
+* runtime sound asset. The rejected candidate is deleted.
+*
+* Candidate order also provides deterministic tie-breaking: if both files
+* have exactly the same size, MP3 wins because it appears first. The returned
+* one-item array follows the common processor contract: one resolved sound
+* produces one processed asset.
+*/
+async function processSound(asset) {
+	const outputDirectory = dirname(asset.outputBasePath);
+	await mkdir(outputDirectory, { recursive: true });
+	const selectedFile = await selectSmallestOutput(await settleAssetTasks(SOUND_CANDIDATE_FORMATS.map((format) => encodeSoundCandidate(asset, format))));
+	return [{
+		bundle: asset.bundle,
+		category: "sounds",
+		file: selectedFile,
+		id: createSimpleAssetId(asset)
+	}];
+}
+/**
+* Encodes one candidate file and returns the metadata consumed by later stages.
+*
+* The generated-file descriptor identifies the candidate's format and path;
+* it does not contain audio data. After all candidates are encoded, their
+* descriptors allow smallest-file selection to measure and remove files.
+*/
+async function encodeSoundCandidate(asset, format) {
+	const outputPath = `${asset.outputBasePath}.${format}`;
+	await transcodeAudio({
+		format,
+		inputPath: asset.absolutePath,
+		options: asset.options,
+		outputPath
+	});
+	return {
+		format,
+		path: outputPath
+	};
+}
+//#endregion
+//#region src/adapters/spine-skeleton-parser.ts
+/**
+* Parses one authored Spine skeleton with the official runtime readers.
+*
+* Both JSON and binary SKEL readers require an `AtlasAttachmentLoader` while
+* resolving skeleton attachments. The companion `.atlas` file is therefore
+* parsed even though Replayable retains only animation and skin names. Texture
+* image pixels are not required for this metadata operation.
+*
+* Names remain in the order supplied by Spine. Registry generation owns
+* deduplication and alphabetical ordering because those are serialization
+* concerns rather than properties of the authored skeleton.
+*
+* The temporary `TextureAtlas` owns runtime objects and is always disposed
+* after skeleton parsing, whether parsing succeeds or throws.
+*
+* @param skeleton - Authored JSON or SKEL skeleton path and resolved format.
+* @param atlasPath - Absolute path of the companion authored `.atlas` file.
+* @returns Animation and skin names needed by the generated Spine registry.
+* @throws A source-specific error when the atlas or skeleton cannot be parsed.
+*/
+async function readSpineSkeletonMetadata(skeleton, atlasPath) {
+	const textureAtlas = await readTextureAtlas(atlasPath);
+	try {
+		const skeletonData = await readSkeletonData(skeleton, new AtlasAttachmentLoader(textureAtlas));
+		return {
+			animationNames: skeletonData.animations.map((animation) => animation.name),
+			skinNames: skeletonData.skins.map((skin) => skin.name)
+		};
+	} finally {
+		textureAtlas.dispose();
+	}
+}
+/** Reads and parses the companion atlas used to resolve skeleton attachments. */
+async function readTextureAtlas(atlasPath) {
+	const source = await readFile(atlasPath, "utf8");
+	try {
+		return new TextureAtlas(source);
+	} catch (cause) {
+		throw new Error(`Invalid Spine atlas: ${atlasPath}`, { cause });
+	}
+}
+/** Selects the official JSON or binary reader for the resolved source format. */
+async function readSkeletonData(skeleton, attachmentLoader) {
+	try {
+		switch (skeleton.format) {
+			case "json": {
+				const source = await readFile(skeleton.path, "utf8");
+				return new SkeletonJson(attachmentLoader).readSkeletonData(JSON.parse(source));
+			}
+			case "skel": {
+				const source = await readFile(skeleton.path);
+				return new SkeletonBinary(attachmentLoader).readSkeletonData(new Uint8Array(source));
+			}
+			default: return skeleton.format;
+		}
+	} catch (cause) {
+		throw new Error(`Invalid Spine ${skeleton.format.toUpperCase()} skeleton: ${skeleton.path}`, { cause });
+	}
+}
+//#endregion
+//#region src/processors/categories/spine.ts
+/**
+* Emits one self-contained Spine runtime asset.
+*
+* JSON skeletons are minified, binary skeletons and atlas descriptions are
+* copied byte-for-byte, and every texture page is optimized independently. A
+* two-page Spine therefore emits four files: skeleton, atlas, and one selected
+* image for each page.
+*
+* For example, these resolved source files:
+*
+* ```text
+* spines/hero/hero.json
+* spines/hero/hero.atlas  -> declares body.png, then effects.png
+* spines/hero/body.png
+* spines/hero/effects.png
+* ```
+*
+* may produce:
+*
+* ```text
+* spines/hero/skeleton.json
+* spines/hero/atlas.atlas
+* spines/hero/images/page0.webp
+* spines/hero/images/page1.avif
+* ```
+*
+* The returned processed asset contains the skeleton file, atlas file, and
+* `[page0, page1]` texture array. It also retains animation and skin names while
+* the authored skeleton is available, allowing registry emission to remain a
+* synchronous serialization step. Page order remains identical to the atlas
+* declaration even when different encodings win for different pages. The
+* returned one-item array follows the common processor contract: one resolved
+* Spine asset produces one complete processed asset.
+*/
+async function processSpine(asset) {
+	const spine = asset.spine;
+	const metadata = await readSpineSkeletonMetadata(spine.skeleton, spine.atlas);
+	await mkdir(asset.outputDirectory, { recursive: true });
+	const skeletonFile = await writeSpineSkeleton(spine.skeleton, asset.outputDirectory);
+	const atlasFile = await copySpineAtlas(spine.atlas, asset.outputDirectory);
+	const texturePages = await writeSpineTexturePages(spine.images, asset.outputDirectory, asset.options);
+	return [{
+		bundle: asset.bundle,
+		category: "spines",
+		files: {
+			atlas: atlasFile,
+			images: texturePages,
+			skeleton: skeletonFile
+		},
+		id: spine.id,
+		metadata,
+		runtime: { scale: asset.options.scale }
+	}];
+}
+/**
+* Writes the skeleton in the format selected during resolution.
+*
+* JSON must be parsed before it can be serialized without optional whitespace;
+* this verifies JSON syntax but does not validate the Spine data model. Binary
+* SKEL content cannot be interpreted here and is copied byte-for-byte.
+*/
+async function writeSpineSkeleton(skeleton, outputDirectory) {
+	const outputPath = join(outputDirectory, `skeleton.${skeleton.format}`);
+	switch (skeleton.format) {
+		case "json":
+			await writeJsonSkeleton(skeleton.path, outputPath);
+			break;
+		case "skel": await copyFile(skeleton.path, outputPath);
+	}
+	return {
+		format: skeleton.format,
+		path: outputPath
+	};
+}
+/**
+* Minifies a JSON skeleton and identifies its source when parsing fails.
+*
+* Parsing exists solely to remove insignificant JSON whitespace. The parsed
+* value remains unknown because this processor does not enforce a Spine schema.
+*/
+async function writeJsonSkeleton(inputPath, outputPath) {
+	const sourceText = await readFile(inputPath, "utf8");
+	let skeletonData;
+	try {
+		skeletonData = JSON.parse(sourceText);
+	} catch (cause) {
+		throw new Error(`Invalid Spine JSON skeleton: ${inputPath}`, { cause });
+	}
+	await writeFile(outputPath, JSON.stringify(skeletonData));
+}
+/** Copies the authored atlas description and returns its generated-file metadata. */
+async function copySpineAtlas(inputPath, outputDirectory) {
+	const outputPath = join(outputDirectory, "atlas.atlas");
+	await copyFile(inputPath, outputPath);
+	return {
+		format: "atlas",
+		path: outputPath
+	};
+}
+/**
+* Optimizes texture pages sequentially while preserving their atlas order.
+*
+* Every page independently generates the supported image candidates and keeps
+* its smallest result. A page may hold a large decoded bitmap plus multiple
+* encoded candidates, so sequential processing bounds peak build memory. The
+* loop appends each result in source order, preserving the positional mapping
+* between the returned array and the pages declared by the Spine atlas.
+*/
+async function writeSpineTexturePages(pageSourcePaths, outputDirectory, options) {
+	const generatedPages = [];
+	for (const [pageIndex, sourcePath] of pageSourcePaths.entries()) {
+		const generatedPage = await writeSmallestImage({
+			input: sourcePath,
+			options,
+			outputBasePath: join(outputDirectory, "images", `page${pageIndex}`),
+			sourcePath
+		});
+		generatedPages.push(generatedPage);
+	}
+	return generatedPages;
+}
+//#endregion
+//#region src/processors/process-assets.ts
+/**
+* Processes every fully resolved asset without category-specific scheduling.
+*
+* Every returned record represents one final runtime entry. Processor results
+* remain arrays because one source atlas may produce several logical sheets;
+* singleton categories return a one-element array through the same dispatcher.
+* The completed collection is guaranteed to contain unique runtime IDs.
+*/
+async function processAssets(assets) {
+	const processedAssets = (await settleAssetTasks(assets.map(processAsset))).flat();
+	assertUniqueRuntimeAssetIds(processedAssets);
+	return processedAssets;
+}
+/** Delegates one resolved asset to the processor for its discriminated category. */
+function processAsset(asset) {
+	const category = asset.category;
+	switch (category) {
+		case "atlases": return processAtlas(asset);
+		case "fonts": return processFont(asset);
+		case "locales": return processLocale(asset);
+		case "shaders": return processShader(asset);
+		case "sounds": return processSound(asset);
+		case "spines": return processSpine(asset);
+		case "sprites":
+		case "textures": return processImage(asset);
+		default: return unsupportedCategory(category);
+	}
+}
+/** Enforces exhaustive category dispatch when the ResolvedAsset union changes. */
+function unsupportedCategory(category) {
+	throw new Error(`Unsupported resolved asset category: ${String(category)}.`);
+}
+//#endregion
+//#region src/pipeline/discover-source-files.ts
+/**
+* Recursively discovers regular files beneath the configured source directory.
+*
+* Returned paths contain both an absolute filesystem location for reading and
+* a POSIX-style relative path for platform-independent matching and asset IDs.
+* Results are sorted so later resolution is deterministic on every filesystem.
+*/
+async function discoverSourceFiles(sourceRoot) {
+	await assertSourceDirectory(sourceRoot);
+	return (await glob("**/*", {
+		cwd: sourceRoot,
+		onlyFiles: true,
+		dot: true,
+		followSymbolicLinks: false
+	})).sort().map((relativePath) => ({
+		absolutePath: resolve(sourceRoot, relativePath),
+		relativePath
+	}));
+}
+/** Ensures discovery starts from an existing directory rather than a file. */
+async function assertSourceDirectory(sourceRoot) {
+	let sourceStats;
+	try {
+		sourceStats = await stat(sourceRoot);
+	} catch (error) {
+		if (hasCode(error, "ENOENT")) throw new Error(`Asset source directory does not exist: ${sourceRoot}`, { cause: error });
+		throw error;
+	}
+	if (!sourceStats.isDirectory()) throw new Error(`Asset source path is not a directory: ${sourceRoot}`);
+}
+function hasCode(error, code) {
+	return error instanceof Error && "code" in error && error.code === code;
+}
+//#endregion
+//#region src/resolvers/source-resolution.ts
+/**
+* Resolves the final configuration rule that claims one logical asset.
+*
+* Category ownership is checked first, so asset rules receive the physical
+* path relative to that directory. Final source-relative exclusions then veto
+* selection before the last matching rule supplies processor options. Most
+* assets use the same physical and logical path; localized sprites pass their
+* canonical path separately so every language variant shares one exclusion
+* identity.
+*/
+function resolveAssetRule(context, category, sourcePath, logicalPath = sourcePath) {
+	const categoryPath = getCategoryPath(sourcePath, category);
+	if (categoryPath === void 0) return;
+	if (matchesAnyGlob(logicalPath, context.config.exclude)) return;
+	return context.config.assets[category].findLast((rule) => matchesRule(rule, categoryPath));
+}
+/**
+* Chooses the runtime bundle that will contain one resolved asset.
+*
+* Every asset belongs to `primary` unless it matches the optional
+* `bundles.secondary` selection. This fixed contract mirrors playable loading:
+* primary assets are available at startup, while secondary assets may be loaded
+* later.
+*
+* For example, given:
+*
+* ```ts
+* bundles: {
+*   secondary: {
+*     include: ['sprites/deferred/**', 'sounds/deferred/**'],
+*     exclude: ['sprites/deferred/debug/**'],
+*   },
+* }
+* ```
+*
+* `sprites/player.png` and `sprites/deferred/debug/grid.png` resolve to
+* `primary`; `sprites/deferred/logo.png` resolves to `secondary`.
+*/
+function resolveBundle(config, relativePath) {
+	const secondary = config.bundles.secondary;
+	if (secondary !== void 0 && matchesSecondaryBundle(secondary, relativePath)) return "secondary";
+	return "primary";
+}
+/**
+* Removes the category directory from a path already claimed by that category.
+*
+* For example, `sprites/ui/button.png` becomes `ui/button.png` for the
+* `sprites` category. `resolveAssetRule` establishes this ownership before a
+* resolver constructs runtime identity or output paths.
+*/
+function stripCategoryDirectory(path, category) {
+	return path.slice(category.length + 1);
+}
+/**
+* Returns whether a source file uses a format supported by one asset category.
+*
+* Configuration rules select logical assets, not file encodings. Keeping the
+* format contract here lets a general sound rule omit `match` while accepting
+* authored audio and ignoring unrelated files in the same directory.
+*/
+function isSupportedSourceFile(category, path) {
+	switch (category) {
+		case "atlases":
+		case "sprites":
+		case "textures": return isImageFile(path);
+		case "fonts": return /\.(?:otf|ttf|woff2?)$/i.test(path);
+		case "locales": return /\.jsonc?$/i.test(path);
+		case "shaders": return isShaderSourceFile(path);
+		case "sounds": return /\.(?:m4a|mp3|ogg|wav)$/i.test(path);
+		case "spines": return isImageFile(path) || isSpineAtlasFile(path) || isSpineSkeletonFile(path);
+		default: return unsupportedSourceCategory(category);
+	}
+}
+/** Returns a path relative to its category directory, or undefined when outside it. */
+function getCategoryPath(path, category) {
+	const categoryDirectory = `${category}/`;
+	return path.startsWith(categoryDirectory) ? path.slice(categoryDirectory.length) : void 0;
+}
+function isImageFile(path) {
+	return /\.(?:avif|jpe?g|png|webp)$/i.test(path);
+}
+function isShaderSourceFile(path) {
+	return /\.glsl$/i.test(path);
+}
+function isSpineAtlasFile(path) {
+	return /\.atlas$/i.test(path);
+}
+function isSpineSkeletonFile(path) {
+	return /\.(?:json|skel)$/i.test(path);
+}
+function matchesRule(rule, relativePath) {
+	if (!matchesGlob(relativePath, rule.match)) return false;
+	if (rule.exclude !== void 0 && matchesAnyGlob(relativePath, rule.exclude)) return false;
+	return true;
+}
+/** Keeps source-format handling exhaustive when a new asset category is added. */
+function unsupportedSourceCategory(category) {
+	throw new Error(`Unsupported source asset category: ${String(category)}.`);
+}
+/**
+* Determines whether the secondary selection claims a source-relative path.
+*
+* Patterns in `include` use OR semantics: matching any one of them selects the
+* path as a candidate. Patterns in `exclude` are vetoes: matching any one of
+* them rejects the candidate even when an `include` pattern matched.
+*
+* For example:
+*
+* ```ts
+* {
+*   include: ['sprites/deferred/**', 'sounds/deferred/**'],
+*   exclude: ['sprites/deferred/debug/**'],
+* }
+* ```
+*
+* accepts `sprites/deferred/logo.png` and `sounds/deferred/music.wav`, but
+* rejects both `sprites/player.png` (not included) and
+* `sprites/deferred/debug/grid.png`
+* (explicitly excluded).
+*/
+function matchesSecondaryBundle(secondary, relativePath) {
+	if (!matchesAnyGlob(relativePath, secondary.include)) return false;
+	if (secondary.exclude !== void 0 && matchesAnyGlob(relativePath, secondary.exclude)) return false;
+	return true;
+}
+/** Returns whether a path matches at least one glob in a pattern collection. */
+function matchesAnyGlob(relativePath, patterns) {
+	return patterns.some((pattern) => matchesGlob(relativePath, pattern));
+}
+//#endregion
+//#region src/resolvers/categories/atlas.ts
+/**
+* Resolves each matched image directory into one logical atlas.
+*
+* For example, `atlases/ui/button.png` and `atlases/ui/icon.png` become one
+* `ui` atlas containing both absolute image paths. The processor later packs
+* that logical atlas into one or more generated sheets.
+*/
+function resolveAtlases(context) {
+	return groupAtlasImages(context).map((group) => createResolvedAtlas(context, group));
+}
+/** Creates the logical atlas value consumed by the texture-packing processor. */
+function createResolvedAtlas(context, group) {
+	const category = "atlases";
+	const id = stripCategoryDirectory(group.directory, category);
+	return {
+		atlas: {
+			id,
+			images: group.images.map((image) => image.absolutePath)
+		},
+		bundle: resolveBundle(context.config, group.directory),
+		category,
+		options: group.rule.options,
+		outputDirectory: resolve(context.outputRoot, category, id),
+		relativePath: group.directory
+	};
+}
+/** Groups image directories selected by an atlas rule. */
+function groupAtlasImages(context) {
+	const imageFiles = context.files.filter((file) => isSupportedSourceFile("atlases", file.relativePath));
+	return [...Map.groupBy(imageFiles, (file) => dirname$1(file.relativePath))].map(([directory, images]) => createAtlasSourceGroup(context, directory, images)).filter((group) => group !== void 0).sort((left, right) => left.directory.localeCompare(right.directory));
+}
+/** Creates one ordered source group when its directory matches an atlas rule. */
+function createAtlasSourceGroup(context, directory, images) {
+	const rule = resolveAssetRule(context, "atlases", directory);
+	if (rule === void 0) return;
+	return {
+		directory,
+		images: [...images].sort((left, right) => left.relativePath.localeCompare(right.relativePath)),
+		rule
+	};
+}
+//#endregion
+//#region src/resolvers/font-charset.ts
+const DEFAULT_FONT_CHARSET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789 !\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~";
+/**
+* Collects the unique Unicode characters used by resolved locale values.
+*
+* Locale keys are metadata, so they do not contribute to a font subset. The
+* resolver has already selected the build language or its fallback; this
+* function therefore sees only text that can appear in the current build.
+*
+* Characters retain their first-seen order across files and phrases. For
+* example, `{ play: 'Խաղալ' }` contributes `Խաղալ`, while `play` contributes
+* no characters.
+*/
+function collectLocaleCharacters(dictionaries) {
+	const characters = /* @__PURE__ */ new Set();
+	for (const dictionary of dictionaries) for (const translation of Object.values(dictionary)) for (const character of translation) characters.add(character);
+	return [...characters].join("");
+}
+/**
+* Creates the complete subset charset for one generated font.
+*
+* Every font starts with printable ASCII so common UI text, numbers, and
+* punctuation remain available even when they are absent from locale files.
+* Characters used by the selected locale come next, followed by characters
+* explicitly requested for this font. Duplicate code points retain the
+* position of their first occurrence.
+*/
+function createFontCharset(localeCharacters, extraCharacters) {
+	const characters = /* @__PURE__ */ new Set(DEFAULT_FONT_CHARSET);
+	for (const character of localeCharacters) characters.add(character);
+	for (const character of extraCharacters ?? "") characters.add(character);
+	return [...characters].join("");
+}
+//#endregion
+//#region src/resolvers/simple-sources.ts
+/**
+* Resolves physical files selected by one simple asset category.
+*
+* Every category receives the same discovered source inventory. Unsupported
+* formats are ignored first, so a rule without `match` can select every
+* supported source. A remaining file becomes a font, sound, sprite, or texture
+* only when one of that category's rules matches its path relative to that
+* category directory. When several rules match, the final rule supplies the
+* processing options.
+*
+* The returned output path has no extension because the category processor
+* decides the final format. For example, resolving `sounds/ui/click.wav` for
+* the `sounds` category beneath `/project/assets/generated` produces:
+*
+* ```ts
+* {
+*   relativePath: 'sounds/ui/click.wav',
+*   outputBasePath: '/project/assets/generated/sounds/ui/click',
+*   bundle: 'primary',
+*   options: { bitrate: 96, channels: 'mono', sampleRate: 32000 },
+* }
+* ```
+*
+* Removing the owned `sounds` directory prevents the generated path from
+* becoming `/project/assets/generated/sounds/sounds/ui/click`. Files outside
+* that directory cannot resolve as sounds.
+*/
+function resolveSimpleSources(context, category) {
+	const sources = [];
+	for (const file of context.files) {
+		if (!isSupportedSourceFile(category, file.relativePath)) continue;
+		const rule = resolveAssetRule(context, category, file.relativePath);
+		if (rule === void 0) continue;
+		const categoryPath = stripCategoryDirectory(file.relativePath, category);
+		sources.push({
+			...file,
+			bundle: resolveBundle(context.config, file.relativePath),
+			options: rule.options,
+			outputBasePath: resolve(context.outputRoot, category, removeExtension(categoryPath))
+		});
+	}
+	return sources;
+}
+//#endregion
+//#region src/resolvers/categories/font.ts
+/** Resolves matched fonts with the complete charset required by the locale build. */
+function resolveFonts(context, localeCharacters) {
+	return resolveSimpleSources(context, "fonts").map((source) => ({
+		...source,
+		category: "fonts",
+		charset: createFontCharset(localeCharacters, source.options.extraCharacters)
+	}));
+}
+//#endregion
+//#region src/resolvers/locale-dictionary.ts
+/**
+* Parses one locale source and selects the build language or its fallback.
+*
+* This function performs no filesystem work. Locale emission and automatic
+* font subsetting can therefore consume the same fixed-language dictionary
+* without parsing or resolving translations independently.
+*/
+function resolveLocaleDictionary(source, relativePath, localization) {
+	const { fallback, language } = localization;
+	const errors = [];
+	const parsed = parse(source, errors, { allowTrailingComma: true });
+	if (errors.length > 0) throw localeParseError(relativePath, source, errors[0]);
+	if (parsed === void 0) throw new Error(`Locale is empty: ${relativePath}`);
+	if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error(`Locale must be an object: ${relativePath}`);
+	return Object.fromEntries(Object.entries(parsed).map(([key, translations]) => {
+		if (typeof translations !== "object" || translations === null || Array.isArray(translations)) throw new Error(`Locale phrase ${JSON.stringify(key)} must contain language values.`);
+		const selectedLanguage = language in translations ? language : fallback;
+		if (!(selectedLanguage in translations)) throw new Error(`Locale phrase ${JSON.stringify(key)} is missing language ${JSON.stringify(language)} and fallback ${JSON.stringify(fallback)}.`);
+		const selectedTranslation = translations[selectedLanguage];
+		if (typeof selectedTranslation !== "string") throw new Error(`Locale phrase ${JSON.stringify(key)} language ${JSON.stringify(selectedLanguage)} must be a string.`);
+		return [key, selectedTranslation];
+	}));
+}
+function localeParseError(relativePath, source, error) {
+	if (error === void 0) return /* @__PURE__ */ new Error(`Invalid locale: ${relativePath}`);
+	const beforeError = source.slice(0, error.offset);
+	const line = beforeError.split("\n").length;
+	const lastNewline = beforeError.lastIndexOf("\n");
+	const column = error.offset - lastNewline;
+	return /* @__PURE__ */ new Error(`Invalid locale ${relativePath}:${line}:${column}: ${printParseErrorCode(error.error)}`);
+}
+//#endregion
+//#region src/resolvers/categories/locale.ts
+/** Resolves the one locale source selected by the project's locale rules. */
+async function resolveLocales(context) {
+	const sources = resolveLocaleSources(context);
+	const source = sources[0];
+	if (source === void 0) return [];
+	if (sources.length > 1) throw new Error(`Locale rules must match at most one translation file; received ${sources.length}.`);
+	return [await resolveLocaleSource(source, context.config.localization)];
+}
+/** Selects locale files without mixing singular locale behavior into simple-source resolution. */
+function resolveLocaleSources(context) {
+	const sources = [];
+	for (const file of context.files) {
+		if (!isSupportedSourceFile("locales", file.relativePath)) continue;
+		if (resolveAssetRule(context, "locales", file.relativePath) === void 0) continue;
+		const localePath = stripCategoryDirectory(file.relativePath, "locales");
+		sources.push({
+			...file,
+			bundle: resolveBundle(context.config, file.relativePath),
+			outputBasePath: resolve(context.outputRoot, "locales", removeExtension(localePath))
+		});
+	}
+	return sources;
+}
+/** Reads and resolves the selected locale into one fixed-language runtime asset. */
+async function resolveLocaleSource(source, localization) {
+	const resolvedLocale = resolveLocaleDictionary(await readFile(source.absolutePath, "utf8"), source.relativePath, localization);
+	return {
+		...source,
+		category: "locales",
+		resolvedLocale
+	};
+}
+//#endregion
+//#region src/resolvers/categories/shader.ts
+/**
+* Resolves each matched directory containing `vert.glsl` and `frag.glsl` into
+* one shader asset. For example, `shaders/glow/{vert,frag}.glsl` becomes the
+* runtime shader ID `glow`.
+*/
+function resolveShaders(context) {
+	return groupShaderSources(context).map((group) => createResolvedShader(context, group));
+}
+/** Creates the build instruction for one complete shader source pair. */
+function createResolvedShader(context, group) {
+	const category = "shaders";
+	const id = stripCategoryDirectory(group.directory, category);
+	return {
+		bundle: resolveBundle(context.config, group.directory),
+		category,
+		outputDirectory: resolve(context.outputRoot, category, id),
+		relativePath: group.directory,
+		shader: {
+			frag: group.frag.absolutePath,
+			id,
+			vert: group.vert.absolutePath
+		}
+	};
+}
+/** Finds complete shader directories selected by the configured rules. */
+function groupShaderSources(context) {
+	const shaderFiles = context.files.filter((file) => isSupportedSourceFile("shaders", file.relativePath));
+	return [...Map.groupBy(shaderFiles, (file) => dirname$1(file.relativePath))].map(([directory, directoryFiles]) => createShaderSourceGroup(context, directory, directoryFiles)).filter((group) => group !== void 0).sort((left, right) => left.directory.localeCompare(right.directory));
+}
+/** Creates one complete source pair when its directory matches a shader rule. */
+function createShaderSourceGroup(context, directory, files) {
+	if (resolveAssetRule(context, "shaders", directory) === void 0) return;
+	const vert = files.find((file) => basename$1(file.relativePath) === "vert.glsl");
+	const frag = files.find((file) => basename$1(file.relativePath) === "frag.glsl");
+	if (vert === void 0 || frag === void 0) throw new Error(`Shader ${directory} must contain vert.glsl and frag.glsl.`);
+	return {
+		directory,
+		frag,
+		vert
+	};
+}
+//#endregion
+//#region src/resolvers/categories/sound.ts
+/** Resolves matched sound sources and their normalized encoding options. */
+function resolveSounds(context) {
+	return resolveSimpleSources(context, "sounds").map((source) => ({
+		...source,
+		category: "sounds"
+	}));
+}
+//#endregion
+//#region src/adapters/spine-atlas-parser.ts
+/**
+* Parses the texture pages declared by an authored Spine atlas.
+*
+* Replayable uses Spine's official runtime parser so page boundaries and names
+* follow the same rules as the eventual runtime loader. Returned names preserve
+* declaration order because the processor emits its texture array in that exact
+* order: the first atlas page becomes `images[0]`, the second becomes
+* `images[1]`, and so on.
+*
+* `TextureAtlas` owns runtime objects even though Replayable only needs their
+* page names. The `finally` block releases those objects after names have been
+* copied, including when reading the pages unexpectedly throws.
+*
+* @param source - Complete text of the authored `.atlas` file.
+* @param sourcePath - Source-relative path used only in parse diagnostics.
+* @returns Texture page names in their authored declaration order.
+* @throws A source-specific error when the official Spine parser rejects the atlas.
+*
+* @example
+*
+* ```ts
+* const pageNames = parseSpineAtlasPageNames(atlasSource, 'spines/hero/hero.atlas');
+*
+* // hero.atlas declares body.png first and effects.png second.
+* console.log(pageNames); // ['body.png', 'effects.png']
+* ```
+*/
+function parseSpineAtlasPageNames(source, sourcePath) {
+	const atlas = createTextureAtlas(source, sourcePath);
+	try {
+		return atlas.pages.map((page) => page.name);
+	} finally {
+		atlas.dispose();
+	}
+}
+/** Creates the official runtime atlas and adds the source path to parse failures. */
+function createTextureAtlas(source, sourcePath) {
+	try {
+		return new TextureAtlas(source);
+	} catch (cause) {
+		throw new Error(`Invalid Spine atlas: ${sourcePath}`, { cause });
+	}
+}
+//#endregion
+//#region src/resolvers/categories/spine.ts
+/**
+* Resolves each matched Spine directory into one complete build instruction.
+*
+* Source grouping validates the skeleton and atlas structure first. Atlas page
+* declarations are then read concurrently because each Spine export is
+* independent, while `Promise.all` preserves the stable group order.
+*/
+async function resolveSpines(context) {
+	const groups = groupSpineSources(context);
+	return Promise.all(groups.map((group) => createResolvedSpine(context, group)));
+}
+/** Finds complete Spine directories selected by the configured rules. */
+function groupSpineSources(context) {
+	const spineFiles = context.files.filter((file) => isSupportedSourceFile("spines", file.relativePath));
+	return [...Map.groupBy(spineFiles, (file) => dirname$1(file.relativePath))].map(([directory, directoryFiles]) => createSpineSourceGroup(context, directory, directoryFiles)).filter((group) => group !== void 0).sort((left, right) => left.directory.localeCompare(right.directory));
+}
+/** Creates one complete source group when its directory matches a Spine rule. */
+function createSpineSourceGroup(context, directory, files) {
+	const rule = resolveAssetRule(context, "spines", directory);
+	if (rule === void 0) return;
+	const skeleton = selectOnlySkeleton(directory, files);
+	return {
+		atlas: selectOnlyAtlas(directory, files),
+		directory,
+		images: files.filter((file) => isImageFile(file.relativePath)),
+		options: rule.options,
+		skeleton
+	};
+}
+/** Reads one Spine atlas and constructs its processor-ready build instruction. */
+async function createResolvedSpine(context, group) {
+	const pageNames = parseSpineAtlasPageNames(await readFile(group.atlas.absolutePath, "utf8"), group.atlas.relativePath);
+	if (pageNames.length === 0) throw new Error(`Spine atlas ${group.atlas.relativePath} contains no texture pages.`);
+	const pageImages = resolveTexturePages(group.atlas, pageNames, group.images);
+	const id = stripCategoryDirectory(group.directory, "spines");
+	return {
+		bundle: resolveBundle(context.config, group.directory),
+		category: "spines",
+		options: group.options,
+		outputDirectory: resolve(context.outputRoot, "spines", id),
+		spine: {
+			atlas: group.atlas.absolutePath,
+			id,
+			images: pageImages.map((image) => image.absolutePath),
+			skeleton: {
+				format: group.skeleton.format,
+				path: group.skeleton.absolutePath
+			}
+		},
+		relativePath: group.directory
+	};
+}
+/** Requires exactly one JSON or SKEL skeleton in a selected Spine directory. */
+function selectOnlySkeleton(directory, files) {
+	const skeletons = files.filter((file) => isSpineSkeletonFile(file.relativePath));
+	const skeleton = skeletons[0];
+	if (skeleton === void 0 || skeletons.length > 1) throw new Error(`Spine ${directory} must contain exactly one matched JSON or SKEL skeleton; found ${skeletons.length}.`);
+	return {
+		...skeleton,
+		format: resolveSpineSkeletonFormat(skeleton.relativePath)
+	};
+}
+/** Converts a supported skeleton extension into its runtime loading format. */
+function resolveSpineSkeletonFormat(relativePath) {
+	switch (extname$1(relativePath).toLowerCase()) {
+		case ".json": return "json";
+		case ".skel": return "skel";
+		default: throw new Error(`Unsupported Spine skeleton: ${relativePath}`);
+	}
+}
+/** Requires exactly one atlas description in a selected Spine directory. */
+function selectOnlyAtlas(directory, files) {
+	const atlases = files.filter((file) => isSpineAtlasFile(file.relativePath));
+	const atlas = atlases[0];
+	if (atlas === void 0 || atlases.length > 1) throw new Error(`Spine ${directory} must contain exactly one .atlas file; found ${atlases.length}.`);
+	return atlas;
+}
+/** Resolves official atlas page declarations to sibling source images in order. */
+function resolveTexturePages(atlas, pageNames, images) {
+	const imageFilesByName = new Map(images.map((image) => [basename$1(image.relativePath), image]));
+	const resolvedImages = [];
+	const resolvedNames = /* @__PURE__ */ new Set();
+	for (const pageName of pageNames) {
+		const imageName = basename$1(pageName);
+		if (resolvedNames.has(imageName)) throw new Error(`Spine atlas ${atlas.relativePath} declares duplicate page ${pageName}.`);
+		const image = imageFilesByName.get(imageName);
+		if (image === void 0) throw new Error(`Spine atlas ${atlas.relativePath} references missing page ${pageName}.`);
+		resolvedNames.add(imageName);
+		resolvedImages.push(image);
+	}
+	return resolvedImages;
+}
+//#endregion
+//#region src/resolvers/categories/sprite.ts
+/**
+* Selects exactly one sprite source for the configured build language.
+*
+* Locale suffixes are removed from the logical asset path before variants are
+* grouped. For example, `logo.hy.png`, `logo.en.png`, and `logo.png` all map to
+* `logo.png`. Selection prefers the requested language, then the configured
+* fallback language, then the unlocalized file.
+*/
+function resolveSprites(context) {
+	return groupSpriteVariants(context).map((group) => {
+		return createResolvedSprite(context, group, selectSpriteVariant(group, context.config.localization));
+	});
+}
+/**
+* Groups matched physical images by the canonical path shared by their locale variants.
+*
+* For example, this source inventory:
+*
+* ```text
+* sprites/background.png
+* sprites/logo.hy.png
+* sprites/logo.en.png
+* sprites/logo.png
+* textures/normal.png
+* sprites/README.md
+* ```
+*
+* produces the equivalent of:
+*
+* ```ts
+* [
+*   {
+*     canonicalPath: 'sprites/background.png',
+*     variants: ['sprites/background.png'],
+*   },
+*   {
+*     canonicalPath: 'sprites/logo.png',
+*     variants: [
+*       'sprites/logo.en.png',
+*       'sprites/logo.hy.png',
+*       'sprites/logo.png',
+*     ],
+*   },
+* ]
+* ```
+*
+* `textures/normal.png` is discarded when no sprite rule selects it, and the
+* non-image README is ignored before rule matching. Both groups and variants
+* use stable path ordering. This function only forms the groups;
+* `selectSpriteVariant` later chooses the language-specific source included in
+* the fixed-language build.
+*/
+function groupSpriteVariants(context) {
+	const variants = context.files.filter((file) => isSupportedSourceFile("sprites", file.relativePath)).map((file) => matchSpriteVariant(context, file)).filter((variant) => variant !== void 0);
+	return [...Map.groupBy(variants, (variant) => variant.canonicalPath)].map(([canonicalPath, groupedVariants]) => ({
+		canonicalPath,
+		variants: [...groupedVariants].sort((left, right) => left.relativePath.localeCompare(right.relativePath))
+	})).sort((left, right) => left.canonicalPath.localeCompare(right.canonicalPath));
+}
+/**
+* Attempts to classify one discovered image as a configured sprite variant.
+*
+* The shared source inventory contains images belonging to atlases, Spine
+* exports, textures, and sprites. An image becomes a sprite variant only when
+* at least one sprite rule matches its physical source path. If several rules
+* match, `resolveAssetRule` supplies options from the final matching rule unless
+* the logical sprite is excluded.
+*
+* Locale parsing then separates physical identity from logical identity. For
+* example, `sprites/logo.hy.png` retains that physical `relativePath`, but its
+* `canonicalPath` becomes `sprites/logo.png` and its locale becomes `hy`.
+* Returning `undefined` tells the grouping stage to discard an image that no
+* sprite rule selected.
+*/
+function matchSpriteVariant(context, file) {
+	const parsedPath = parseSpritePath(file.relativePath);
+	const rule = resolveAssetRule(context, "sprites", file.relativePath, parsedPath.canonicalPath);
+	if (rule === void 0) return;
+	return {
+		...file,
+		canonicalPath: parsedPath.canonicalPath,
+		locale: parsedPath.locale,
+		options: rule.options
+	};
+}
+/**
+* Selects the one physical variant included in the fixed-language build.
+*
+* Selection follows the configured priority exactly:
+*
+* 1. A variant matching `localization.language`.
+* 2. A variant matching `localization.fallback`.
+* 3. An unlocalized variant without a locale suffix.
+*
+* Continuing the `groupSpriteVariants` example, its `sprites/logo.png` group
+* contains Armenian, English, and unlocalized variants. Given:
+*
+* ```ts
+* { language: 'hy', fallback: 'en' }
+* ```
+*
+* this function returns the equivalent of:
+*
+* ```ts
+* {
+*   canonicalPath: 'sprites/logo.png',
+*   relativePath: 'sprites/logo.hy.png',
+*   locale: 'hy',
+*   // absolutePath and processing options belong to this Armenian source.
+* }
+* ```
+*
+* If `logo.hy.png` is absent, the same group returns `logo.en.png`. If both
+* localized variants are absent, it returns `logo.png`. A group containing
+* only `logo.fr.png` fails because Replayable must not silently include an
+* unrelated language.
+*
+* The returned variant retains the processing options and physical path of
+* the rule that selected that specific localized source.
+*/
+function selectSpriteVariant(group, localization) {
+	const languageVariant = group.variants.find((variant) => variant.locale === localization.language);
+	if (languageVariant !== void 0) return languageVariant;
+	const fallbackVariant = group.variants.find((variant) => variant.locale === localization.fallback);
+	if (fallbackVariant !== void 0) return fallbackVariant;
+	const unlocalizedVariant = group.variants.find((variant) => variant.locale === void 0);
+	if (unlocalizedVariant !== void 0) return unlocalizedVariant;
+	throw new Error(`Localized sprite ${group.canonicalPath} has no ${localization.language}, ${localization.fallback}, or unlocalized variant.`);
+}
+/** Creates the single resolved sprite selected for the fixed-language build. */
+function createResolvedSprite(context, group, selectedVariant) {
+	const category = "sprites";
+	const categoryPath = stripCategoryDirectory(group.canonicalPath, category);
+	return {
+		absolutePath: selectedVariant.absolutePath,
+		bundle: resolveBundle(context.config, selectedVariant.relativePath),
+		category,
+		options: selectedVariant.options,
+		outputBasePath: resolve(context.outputRoot, category, removeExtension(categoryPath)),
+		relativePath: group.canonicalPath
+	};
+}
+/**
+* Removes an optional locale suffix while preserving the physical extension.
+*
+* `sprites/logo.hy.png` becomes `{ canonicalPath: 'sprites/logo.png', locale:
+* 'hy' }`, while `sprites/logo.png` keeps its path and has no locale. The
+* canonical path allows every localized source to join the same variant group.
+*/
+function parseSpritePath(path) {
+	const fileName = basename$1(path);
+	const match = /^(.*)\.([a-z]{2}(?:-[A-Z]{2})?)\.([^.]+)$/.exec(fileName);
+	if (match === null) return {
+		canonicalPath: path,
+		locale: void 0
+	};
+	const directory = dirname$1(path);
+	const canonicalName = `${match[1]}.${match[3]}`;
+	return {
+		canonicalPath: directory === "." ? canonicalName : `${directory}/${canonicalName}`,
+		locale: match[2]
+	};
+}
+//#endregion
+//#region src/resolvers/categories/texture.ts
+/** Resolves matched non-localized texture sources. */
+function resolveTextures(context) {
+	return resolveSimpleSources(context, "textures").map((source) => ({
+		...source,
+		category: "textures"
+	}));
+}
+//#endregion
+//#region src/resolvers/resolution-context.ts
+/** Narrows complete build state to the inputs available during source resolution. */
+function createResolutionContext(config, context, files) {
+	return {
+		config,
+		files,
+		outputRoot: context.outputRoot
+	};
+}
+//#endregion
+//#region src/resolvers/resolve-assets.ts
+/**
+* Discovers source files and converts them into self-contained build instructions.
+*
+* Locales resolve first because their selected text determines the characters
+* retained by every generated font. All other categories are independent.
+*/
+async function resolveAssets(config, context) {
+	const resolution = createResolutionContext(config, context, await discoverSourceFiles(context.sourceRoot));
+	const locales = await resolveLocales(resolution);
+	const localeCharacters = collectLocaleCharacters(locales.map((locale) => locale.resolvedLocale));
+	const atlases = resolveAtlases(resolution);
+	const fonts = resolveFonts(resolution, localeCharacters);
+	const shaders = resolveShaders(resolution);
+	const sounds = resolveSounds(resolution);
+	const spines = await resolveSpines(resolution);
+	const sprites = resolveSprites(resolution);
+	const textures = resolveTextures(resolution);
+	return [
+		...atlases,
+		...fonts,
+		...locales,
+		...shaders,
+		...sounds,
+		...spines,
+		...sprites,
+		...textures
+	];
+}
+//#endregion
+//#region src/build-assets.ts
+/**
+* Builds every configured asset and generates the runtime assets module.
+*
+* @param input - Author-written or previously normalized asset configuration.
+* @param workingDirectory - Project root used to resolve every configured path.
+* Defaults to the current process directory.
+* @returns Logical asset and physical file counts, populated bundles, and the
+* absolute output directory.
+* @throws When configuration is invalid, configured paths are unsafe, or an
+* asset cannot be resolved, processed, or emitted.
+*
+* @example
+*
+* ```ts
+* const result = await buildAssets(config, process.cwd());
+*
+* console.log(result.emittedAssets);
+* console.log(result.emittedFiles);
+* console.log(result.outputDirectory);
+* ```
+*/
+async function buildAssets(input, workingDirectory = process.cwd()) {
+	const config = assetConfigSchema.parse(input);
+	const context = createBuildContext(config, workingDirectory);
+	const staging = await createBuildStaging(context, workingDirectory);
+	try {
+		const resolved = await resolveAssets(config, staging.context);
+		validateOutputClaims(resolved);
+		const assetGroups = groupAssets(await processAssets(resolved));
+		await emitBuildOutputs(staging.context, assetGroups);
+		await staging.commit();
+		return createBuildResult(context, assetGroups);
+	} finally {
+		await staging.dispose();
+	}
+}
+//#endregion
+//#region src/config/define-config.ts
+/**
+* Validates an authored asset configuration and applies schema defaults.
+*
+* Invalid fields or values throw when the configuration module loads. Valid
+* input is returned with trimmed strings, normalized category arrays, and all
+* processor defaults applied.
+*
+* @param config - Author-written configuration to validate and normalize.
+* @returns A validated configuration with schema defaults applied.
+* @throws When any configuration value fails schema validation.
+*
+* @example
+*
+* ```ts
+* import { defineConfig } from '@replayablejs/assets';
+*
+* export default defineConfig({
+*   assets: {
+*     sounds: [{ match: '**' }],
+*   },
+*   emit: { assets: 'src/assets/assets.gen.ts' },
+*   localization: { language: 'en', fallback: 'en' },
+*   outDir: 'assets/out',
+*   sourceDir: 'assets/source',
+* });
+* ```
+*/
+function defineConfig(config) {
+	return assetConfigSchema.parse(config);
+}
+//#endregion
+export { assetBundleNames, assetCategories, assetConfigSchema, buildAssets, defineConfig, groupedAssetCategories, simpleAssetCategories };
+
+//# sourceMappingURL=index.mjs.map