@replayablejs/assets 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Replayable contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @replayablejs/assets
+
+Build optimized resources and generated TypeScript asset modules.
+
+Part of [Replayable](https://github.com/replayablejs/replayable) **0.1.0-alpha.0**.
+APIs may change during the alpha series.
+
+## Install
+
+```sh
+pnpm add -D @replayablejs/assets@0.1.0-alpha.0
+```
+
+## Public surface
+
+`defineConfig`, `assetConfigSchema`, `buildAssets`; category and bundle constants; asset configuration, build-result and runtime asset types.
+
+[Usage and reference](https://github.com/replayablejs/replayable/blob/main/docs/reference/assets.md).
+The package manifest defines supported import paths; internal source files are not public APIs.
+
+## Development
+
+From the repository root, install with `pnpm install --frozen-lockfile` and build dependencies
+with `pnpm build`. Run `pnpm --filter @replayablejs/assets test` for this package's tests.
+
+## License
+
+Original code is [MIT licensed](https://github.com/replayablejs/replayable/blob/main/LICENSE). Bundled third-party resources retain
+their accompanying license terms.

package/dist/index.d.mts

@@ -0,0 +1,272 @@
+import { z } from "zod";
+import { AssetBundleName, AssetCategory, AssetMode, Assets, AssetsInBundle, AtlasAsset, FontAsset, GroupedAssetCategory, ImageAsset, JsonObject, JsonPrimitive, JsonValue, LocaleAsset, LocaleDictionary, ShaderAsset, SimpleAssetCategory, SpineAsset, assetBundleNames, assetCategories, groupedAssetCategories, simpleAssetCategories } from "@replayablejs/runtime/assets";
+//#region src/types/build.d.ts
+/** Summary returned after a successful assets build. */
+interface BuildAssetsResult {
+  /** Emitted runtime bundles in loading order; primary is always present. */
+  readonly bundles: readonly AssetBundleName[];
+  /** Number of logical entries emitted into the runtime assets object. */
+  readonly emittedAssets: number;
+  /** Number of physical asset files written to the output directory. */
+  readonly emittedFiles: number;
+  /** Absolute directory containing the processed asset files. */
+  readonly outputDirectory: string;
+}
+//#endregion
+//#region src/config/schema.d.ts
+/**
+ * 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.
+ */
+declare const assetConfigSchema: z.ZodObject<{
+  sourceDir: z.ZodString;
+  outDir: z.ZodString;
+  localization: z.ZodObject<{
+    fallback: z.ZodString;
+    language: z.ZodString;
+  }, z.core.$strict>;
+  bundles: z.ZodPrefault<z.ZodObject<{
+    secondary: z.ZodOptional<z.ZodObject<{
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      include: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
+  assets: z.ZodObject<{
+    atlases: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      options: z.ZodPrefault<z.ZodUnion<readonly [z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodDefault<z.ZodLiteral<false>>;
+        quality: z.ZodOptional<z.ZodNumber>;
+        allowTrim: z.ZodDefault<z.ZodBoolean>;
+        allowRotation: z.ZodDefault<z.ZodBoolean>;
+        padding: z.ZodDefault<z.ZodNumber>;
+        extrude: z.ZodDefault<z.ZodNumber>;
+        powerOfTwo: z.ZodDefault<z.ZodBoolean>;
+      }, z.core.$strict>, z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodLiteral<true>;
+        allowTrim: z.ZodDefault<z.ZodBoolean>;
+        allowRotation: z.ZodDefault<z.ZodBoolean>;
+        padding: z.ZodDefault<z.ZodNumber>;
+        extrude: z.ZodDefault<z.ZodNumber>;
+        powerOfTwo: z.ZodDefault<z.ZodBoolean>;
+      }, z.core.$strict>]>>;
+    }, z.core.$strict>>>;
+    fonts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      options: z.ZodObject<{
+        family: z.ZodString;
+        extraCharacters: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    locales: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    shaders: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+    sounds: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      options: z.ZodPrefault<z.ZodObject<{
+        bitrate: z.ZodDefault<z.ZodNumber>;
+        channels: z.ZodDefault<z.ZodEnum<{
+          mono: "mono";
+          source: "source";
+          stereo: "stereo";
+        }>>;
+        sampleRate: z.ZodDefault<z.ZodNumber>;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>>;
+    spines: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      options: z.ZodPrefault<z.ZodUnion<readonly [z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodDefault<z.ZodLiteral<false>>;
+        quality: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$strict>, z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodLiteral<true>;
+      }, z.core.$strict>]>>;
+    }, z.core.$strict>>>;
+    sprites: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      options: z.ZodPrefault<z.ZodUnion<readonly [z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodDefault<z.ZodLiteral<false>>;
+        quality: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$strict>, z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodLiteral<true>;
+      }, z.core.$strict>]>>;
+    }, z.core.$strict>>>;
+    textures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+      match: z.ZodDefault<z.ZodString>;
+      exclude: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      options: z.ZodPrefault<z.ZodUnion<readonly [z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodDefault<z.ZodLiteral<false>>;
+        quality: z.ZodOptional<z.ZodNumber>;
+      }, z.core.$strict>, z.ZodObject<{
+        scale: z.ZodDefault<z.ZodNumber>;
+        lossless: z.ZodLiteral<true>;
+      }, z.core.$strict>]>>;
+    }, z.core.$strict>>>;
+  }, z.core.$strict>;
+  exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  emit: z.ZodObject<{
+    assets: z.ZodDefault<z.ZodString>;
+    registries: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+//#endregion
+//#region src/types/config.d.ts
+/** Validated asset configuration with every schema default applied. */
+type AssetConfig = z.infer<typeof assetConfigSchema>;
+/** Author-written asset configuration accepted before defaults are applied. */
+type AssetConfigInput = z.input<typeof assetConfigSchema>;
+//#endregion
+//#region src/build-assets.d.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);
+ * ```
+ */
+declare function buildAssets(input: AssetConfigInput, workingDirectory?: string): Promise<BuildAssetsResult>;
+//#endregion
+//#region src/config/define-config.d.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',
+ * });
+ * ```
+ */
+declare function defineConfig(config: AssetConfigInput): AssetConfig;
+//#endregion
+//#region src/config/schemas/atlas.d.ts
+/** Image encoding and texture-packing options for generated atlas sheets. */
+declare const atlasOptionsSchema: z.ZodUnion<readonly [z.ZodObject<{
+  scale: z.ZodDefault<z.ZodNumber>;
+  lossless: z.ZodDefault<z.ZodLiteral<false>>;
+  quality: z.ZodOptional<z.ZodNumber>;
+  allowTrim: z.ZodDefault<z.ZodBoolean>;
+  allowRotation: z.ZodDefault<z.ZodBoolean>;
+  padding: z.ZodDefault<z.ZodNumber>;
+  extrude: z.ZodDefault<z.ZodNumber>;
+  powerOfTwo: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+  scale: z.ZodDefault<z.ZodNumber>;
+  lossless: z.ZodLiteral<true>;
+  allowTrim: z.ZodDefault<z.ZodBoolean>;
+  allowRotation: z.ZodDefault<z.ZodBoolean>;
+  padding: z.ZodDefault<z.ZodNumber>;
+  extrude: z.ZodDefault<z.ZodNumber>;
+  powerOfTwo: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>]>;
+//#endregion
+//#region src/config/schemas/font.d.ts
+/** Required runtime family name plus optional characters added to the subset. */
+declare const fontOptionsSchema: z.ZodObject<{
+  family: z.ZodString;
+  extraCharacters: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+//#endregion
+//#region src/config/schemas/image.d.ts
+/** Options shared by standalone images and Spine texture pages. */
+declare const imageOptionsSchema: z.ZodUnion<readonly [z.ZodObject<{
+  scale: z.ZodDefault<z.ZodNumber>;
+  lossless: z.ZodDefault<z.ZodLiteral<false>>;
+  quality: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+  scale: z.ZodDefault<z.ZodNumber>;
+  lossless: z.ZodLiteral<true>;
+}, z.core.$strict>]>;
+//#endregion
+//#region src/config/schemas/sound.d.ts
+/** Encoding settings applied to every generated MP3 and M4A candidate. */
+declare const soundOptionsSchema: z.ZodObject<{
+  bitrate: z.ZodDefault<z.ZodNumber>;
+  channels: z.ZodDefault<z.ZodEnum<{
+    mono: "mono";
+    source: "source";
+    stereo: "stereo";
+  }>>;
+  sampleRate: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+//#endregion
+//#region src/config/schemas/spine.d.ts
+/** Image processing options applied independently to every Spine texture page. */
+declare const spineOptionsSchema: import("zod").ZodUnion<readonly [import("zod").ZodObject<{
+  scale: import("zod").ZodDefault<import("zod").ZodNumber>;
+  lossless: import("zod").ZodDefault<import("zod").ZodLiteral<false>>;
+  quality: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strict>, import("zod").ZodObject<{
+  scale: import("zod").ZodDefault<import("zod").ZodNumber>;
+  lossless: import("zod").ZodLiteral<true>;
+}, import("zod/v4/core").$strict>]>;
+//#endregion
+//#region src/types/asset-options.d.ts
+/** Author-written atlas options accepted before defaults are applied. */
+type AtlasAssetOptions = z.input<typeof atlasOptionsSchema>;
+/** Author-written font options accepted before validation. */
+type FontAssetOptions = z.input<typeof fontOptionsSchema>;
+/** Author-written image options accepted before defaults are applied. */
+type ImageAssetOptions = z.input<typeof imageOptionsSchema>;
+/** Author-written sound options accepted before defaults are applied. */
+type SoundAssetOptions = z.input<typeof soundOptionsSchema>;
+/** Author-written image options applied to Spine texture pages. */
+type SpineAssetOptions = z.input<typeof spineOptionsSchema>;
+//#endregion
+export { type AssetBundleName, type AssetCategory, type AssetConfig, type AssetConfigInput, type AssetMode, type Assets, type AssetsInBundle, type AtlasAsset, type AtlasAssetOptions, type BuildAssetsResult, type FontAsset, type FontAssetOptions, type GroupedAssetCategory, type ImageAsset, type ImageAssetOptions, type JsonObject, type JsonPrimitive, type JsonValue, type LocaleAsset, type LocaleDictionary, type ShaderAsset, type SimpleAssetCategory, type SoundAssetOptions, type SpineAsset, type SpineAssetOptions, assetBundleNames, assetCategories, assetConfigSchema, buildAssets, defineConfig, groupedAssetCategories, simpleAssetCategories };
+//# sourceMappingURL=index.d.mts.map