@caperjs/core 0.1.2 → 0.2.1

package/README.md

@@ -18,7 +18,7 @@ This package is **not yet published to npm**. The recommended way to use it is t
 - **Per-bundle asset types** generated from your AssetPack manifest
 - **Plugin `requires: [...]`** declarations + topological sort at bootstrap
 - **Build-time validation** for asset bundles, plugin IDs, dependency cycles, duplicate IDs
-- **Exported Vite + AssetPack config** (`@caperjs/core/config/vite`, `@caperjs/core/config/assetpack`)
+- **A Vite preset** (`@caperjs/core/vite`) — `plugins: [caper()]`, then plain `vite` / `vite build`
 - **`caper add` CLI** for scaffolding scenes, plugins, entities, popups
 - **Signals** via `typed-signals`
 - **Tested** — Vitest covers `Plugin`, `Store`, `Scene`, `SignalRegistry`

package/{config → build}/assetpack.mjs

@@ -1,36 +1,8 @@
 import { AssetPack, Logger } from '@assetpack/core';
 import { pixiPipes } from '@assetpack/core/pixi';
-import fs from 'node:fs';
 import process from 'node:process';
 import path from 'path';
 
-// Check if user config exists (synchronously)
-function hasUserAssetpackConfig() {
-  const configPath = path.join(process.cwd(), '.assetpack.mjs');
-  try {
-    return fs.existsSync(configPath);
-  } catch {
-    return false;
-  }
-}
-
-// Async function to load user config
-async function loadUserAssetpackConfig() {
-  if (!hasUserAssetpackConfig()) {
-    return null;
-  }
-
-  try {
-    const configPath = path.join(process.cwd(), '.assetpack.mjs');
-    const userConfig = await import(configPath);
-    Logger.info('Caper assetpack plugin:: Using user assetpack config from .assetpack.mjs');
-    return userConfig.default || userConfig;
-  } catch (error) {
-    Logger.error('Caper assetpack plugin:: Error loading user assetpack config:', error);
-    return null;
-  }
-}
-
 const cwd = process.cwd();
 
 /**
@@ -67,7 +39,8 @@ const defaultPixiPipesConfig = {
   // Retina-first: raw art is authored at 2x native game pixels. AssetPack
   // treats the source as the largest resolution listed, so this emits @2x
   // plus downscaled 1x and 0.5x. Apps whose art is authored at 1x override
-  // `resolutions` in their .assetpack.mjs (or tag individual assets {fix}).
+  // `resolutions` via `caper({ assets: { resolutions } })` (or tag individual
+  // assets {fix}).
   resolutions: { high: 2, default: 1, low: 0.5 },
   // Quality-first compression: the upstream webp default (quality 80, lossy
   // alpha) rings on anti-aliased UI edges, and browsers load .webp over .png.
@@ -85,7 +58,27 @@ const defaultPixiPipesConfig = {
     removeFileExtension: true,
     texturePacker: { nameStyle: 'relative', removeFileExtension: true },
   },
-  audio: {},
+  // AssetPack's audio defaults are a trap: the mp3 output has
+  // `recompress: false`, so an mp3 source is *copied* — a 320kbps master ships
+  // untouched, cover art included — while the ogg twin is re-encoded down to
+  // 32kbps mono. Since pixi's resolver prefers ogg, desktop ends up playing the
+  // worst copy of a file the project also ships at ten times the size. Both
+  // outputs get the same music-grade target instead, and `noVideo` drops the
+  // embedded cover art ffmpeg would otherwise copy into every output.
+  audio: {
+    outputs: [
+      {
+        formats: ['.mp3'],
+        recompress: true,
+        options: { audioBitrate: 128, audioChannels: 2, audioFrequency: 44100, noVideo: true },
+      },
+      {
+        formats: ['.ogg'],
+        recompress: true,
+        options: { audioBitrate: 128, audioChannels: 2, audioFrequency: 44100, noVideo: true },
+      },
+    ],
+  },
   webfont: {},
   manifest: { trimExtensions: true, createShortcuts: true, output: defaultManifestUrl },
 };
@@ -108,22 +101,84 @@ function devCompression(compression) {
   return result;
 }
 
-export const assetpackConfig = (manifestUrl = defaultManifestUrl, pixiPipesConfig = {}, cacheBust) => {
-  pixiPipesConfig = { ...defaultPixiPipesConfig, ...pixiPipesConfig };
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * Keys whose value is one whole decision rather than a bag of options, so an
+ * override replaces it outright instead of merging into it.
+ *
+ * `resolutions` is the important one, and AssetPack's own `pixiPipes()` makes the
+ * same exception ("don't merge the resolutions, just overwrite them"): the object
+ * is a *set of tiers*, so merging `{ default: 1, low: 0.5 }` into caper's
+ * retina-first default would silently put `high: 2` back and render 1x art at
+ * half size.
+ */
+const REPLACE_WHOLE = new Set(['resolutions']);
+
+/**
+ * Deep-merge `overrides` over `base`: plain objects recurse, everything else
+ * (arrays, scalars, `false`) replaces. Deep so that overriding one knob keeps
+ * its siblings — `{ compression: { png: false } }` must not silently discard
+ * caper's webp settings. Arrays replace rather than merge because the arrays
+ * here are whole specifications (an audio `outputs` list), not sets to extend.
+ */
+function deepMerge(base, overrides) {
+  if (!isPlainObject(overrides)) return overrides === undefined ? base : overrides;
+  const out = { ...base };
+  for (const [key, value] of Object.entries(overrides)) {
+    const mergeable = isPlainObject(value) && isPlainObject(base?.[key]) && !REPLACE_WHOLE.has(key);
+    out[key] = mergeable ? deepMerge(base[key], value) : value;
+  }
+  return out;
+}
+
+/**
+ * Whether this is a production build.
+ *
+ * Vite is the authority here, not `process.env.NODE_ENV`: nothing guarantees
+ * vite sets that variable, and depending on it silently shipped a kitchen-sink
+ * build with no cache-busting hashes and dev-effort compression. Callers pass
+ * `resolvedConfig.isProduction` from `configResolved`; the NODE_ENV read is only
+ * a fallback for direct callers outside a vite build.
+ */
+function resolveIsProduction(isProduction) {
+  return isProduction ?? process.env.NODE_ENV === 'production';
+}
+
+/**
+ * Caper's pixi-pipes defaults with a project's overrides merged in, plus the two
+ * environment-dependent adjustments: cache-busting in production, and cheaper
+ * compression effort in dev.
+ *
+ * Exported for tests — the merged pipes themselves are opaque, so this plain
+ * object is the only place the merge is observable.
+ */
+export function resolvePixiPipesConfig(overrides = {}, { cacheBust, isProduction } = {}) {
+  const config = deepMerge(defaultPixiPipesConfig, overrides);
+  const production = resolveIsProduction(isProduction);
 
   if (cacheBust !== undefined) {
-    pixiPipesConfig.cacheBust = cacheBust;
+    config.cacheBust = cacheBust;
   }
-  // NODE_ENV is read at call time, not module load: under the caper CLI this
-  // module is imported before vite's resolveConfig sets NODE_ENV, whereas
-  // assetpackConfig runs after (configResolved / user .assetpack.mjs import).
-  if (pixiPipesConfig.cacheBust === undefined) {
-    pixiPipesConfig.cacheBust = process.env.NODE_ENV === 'production';
+  if (config.cacheBust === undefined) {
+    config.cacheBust = production;
   }
-  if (process.env.NODE_ENV !== 'production') {
-    pixiPipesConfig.compression = devCompression(pixiPipesConfig.compression);
+  if (!production) {
+    config.compression = devCompression(config.compression);
+  }
+  return config;
+}
+
+export const assetpackConfig = (manifestUrl = defaultManifestUrl, pixiPipesConfig = {}, env = {}) => {
+  const resolved = resolvePixiPipesConfig(pixiPipesConfig, env);
+
+  // A custom manifest filename has to reach the manifest pipe too, or the file
+  // gets written as assets.json while everything else looks for the new name.
+  if (!pixiPipesConfig?.manifest?.output) {
+    resolved.manifest = { ...resolved.manifest, output: manifestUrl };
   }
-  const pipes = pixiPipes({ ...pixiPipesConfig });
+
+  const pipes = pixiPipes({ ...resolved });
 
   // Insert fontWeights before the webfont pipe so that the {weight} tag
   // is converted to a weights[] array before webfont processes the asset.
@@ -140,17 +195,18 @@ export const assetpackConfig = (manifestUrl = defaultManifestUrl, pixiPipesConfi
 
 export default assetpackConfig;
 
-export function assetpackPlugin(manifestUrl = defaultManifestUrl, pixiPipesConfig = defaultPixiPipesConfig) {
+export function assetpackPlugin(manifestUrl = defaultManifestUrl, pixiPipesConfig = {}) {
   let mode;
   let ap;
   let apConfig;
   let isBuilding = false;
   let server;
 
+  let isProduction;
+
   async function getConfig() {
     if (!apConfig) {
-      const userConfig = await loadUserAssetpackConfig();
-      apConfig = userConfig || assetpackConfig(manifestUrl, pixiPipesConfig);
+      apConfig = assetpackConfig(manifestUrl, pixiPipesConfig, { isProduction });
     }
   }
 
@@ -158,10 +214,12 @@ export function assetpackPlugin(manifestUrl = defaultManifestUrl, pixiPipesConfi
     name: 'vite-plugin-assetpack',
     async configResolved(resolvedConfig) {
       mode = resolvedConfig.command;
+      // Captured before getConfig() below, which is what consumes it.
+      isProduction = resolvedConfig.isProduction;
       if (!resolvedConfig.publicDir) return;
       await getConfig();
       if (apConfig.output) return;
-      const publicDir = resolvedConfig.publicDir.replace(cwd, '');
+      const publicDir = resolvedConfig.publicDir.replace(resolvedConfig.root, '');
       const outputPath = path.join(publicDir, 'assets');
       apConfig.output = path.isAbsolute(publicDir)
         ? path.join('.', outputPath).replace(/\\/g, '/')

package/build/defaults.mjs

@@ -0,0 +1,180 @@
+/**
+ * The Vite settings caper contributes, expressed as *defaults* rather than
+ * overrides.
+ *
+ * `caperDefaults(userConfig, env)` returns a partial config containing only what
+ * the project left unset. That shape matters: Vite deep-merges a plugin's
+ * returned partial *over* the existing config, so returning values
+ * unconditionally would silently beat the project's own. Filling only the gaps
+ * means the project always wins, which is the whole point of the preset.
+ *
+ * Three merge rules, applied by `fillMissing`:
+ *
+ *  - **Plain objects recurse.** A project that sets `server.port` keeps its port
+ *    and still gets `host` and `open`.
+ *  - **Arrays are always contributed.** Vite concatenates them, which is what we
+ *    want: a project adding to `resolve.dedupe` must not silently drop pixi from
+ *    it, or two copies of pixi split its global registries.
+ *  - **Everything else fills only when absent**, including functions like
+ *    `manualChunks`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { APP_ENTRY_FILE, CAPER_CONFIG_FILE, SOURCE_DIRS } from './internal/paths.mjs';
+
+/**
+ * App identity for the `__CAPER_APP_*` defines and the PWA manifest skeleton.
+ *
+ * `npm_package_*` is only set when a package manager runs the script, so a bare
+ * `vite build` from a shell used to bake `undefined` into the bundle. Fall back
+ * to reading package.json, which is where the env vars came from anyway.
+ */
+export function readAppIdentity(root = process.cwd()) {
+  const fromEnv = {
+    name: process.env.npm_package_name,
+    version: process.env.npm_package_version,
+    description: process.env.npm_package_description,
+  };
+  if (fromEnv.name && fromEnv.version && fromEnv.description) return fromEnv;
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+    return {
+      name: fromEnv.name ?? pkg.name,
+      version: fromEnv.version ?? pkg.version,
+      description: fromEnv.description ?? pkg.description,
+    };
+  } catch {
+    return fromEnv;
+  }
+}
+
+const isPlainObject = (value) =>
+  value !== null && typeof value === 'object' && !Array.isArray(value);
+
+/**
+ * The subset of `defaults` that `target` does not already specify. Returns
+ * `undefined` when there is nothing to contribute, so callers can omit the key
+ * entirely rather than merging an empty object.
+ */
+export function fillMissing(target, defaults) {
+  const out = {};
+
+  for (const [key, value] of Object.entries(defaults)) {
+    if (value === undefined) continue;
+
+    const current = target?.[key];
+
+    if (Array.isArray(value)) {
+      // Vite concatenates arrays on merge — always contribute.
+      out[key] = value;
+      continue;
+    }
+
+    if (isPlainObject(value)) {
+      const nested = fillMissing(isPlainObject(current) ? current : undefined, value);
+      if (nested !== undefined) out[key] = nested;
+      continue;
+    }
+
+    if (current === undefined) out[key] = value;
+  }
+
+  return Object.keys(out).length ? out : undefined;
+}
+
+/**
+ * Caper's own values, before any gap-filling.
+ *
+ * `root` is the project root vite will use — taken from the project's own config
+ * when it sets one, so the `@` alias follows `vite --root somewhere/else`. It is
+ * resolved here rather than at module load, which is what a module-level
+ * `process.cwd()` would have baked in.
+ */
+export function caperDefaultValues(env, userConfig = {}) {
+  const isServe = env.command === 'serve';
+  const root = userConfig.root ? path.resolve(userConfig.root) : process.cwd();
+  const app = readAppIdentity(root);
+
+  return {
+    cacheDir: '.cache',
+    logLevel: 'info',
+    publicDir: './public',
+    // Dev serves from root; builds emit relative URLs so a bundle can be hosted
+    // from a subdirectory.
+    base: isServe ? '/' : './',
+    server: {
+      port: 3000,
+      host: true,
+      open: true,
+    },
+    preview: {
+      host: true,
+      port: 8080,
+    },
+    build: {
+      sourcemap: env.mode === 'development',
+      rolldownOptions: {
+        external: ['caper-globals'],
+        output: {
+          // Rolldown requires manualChunks as a function (Rollup allowed an object).
+          manualChunks(id) {
+            if (id.includes('node_modules/gsap/')) return 'gsap';
+          },
+          chunkFileNames: 'assets/[name]-[hash].js',
+          entryFileNames: 'assets/[name]-[hash].js',
+          assetFileNames: 'assets/[name]-[hash][extname]',
+        },
+      },
+    },
+    resolve: {
+      alias: {
+        '@': path.resolve(root, './src'),
+      },
+      // Force a single instance of each singleton lib. pixi keeps global
+      // registries (extensions, TextureSource cache, Ticker.shared) and relies on
+      // instanceof; two copies (via linked/transitive installs) split its state.
+      dedupe: ['pixi.js', 'gsap', '@pixi/sound'],
+    },
+    // Don't prebundle @pixi/ui: esbuild inlines its own copy of pixi.js into the
+    // dep chunk, giving two pixi instances — every cross-boundary
+    // `instanceof Texture/Sprite` then fails. Served as source, its
+    // `import "pixi.js"` resolves to the same optimized pixi as the app. Its
+    // nested typed-signals dep (CJS) still needs prebundling for interop.
+    optimizeDeps: {
+      exclude: ['@pixi/ui'],
+      include: ['@pixi/ui > typed-signals'],
+      // Every root of a caper app's module graph, because none of them are
+      // reachable from the default scan. Vite's cold-start dep scan reads the
+      // RAW index.html for <script> tags, and the runtime entry is injected by
+      // plugins/runtime.mjs at transformIndexHtml time — so the scan starts
+      // from nothing and prebundles nothing. Scenes, popups and `autoLoad:
+      // false` plugins then arrive through the virtual lists as dynamic
+      // imports the scanner cannot follow either. The first scene that pulls a
+      // new dep (physics, filters, gsap plugins) makes vite re-optimize
+      // mid-session and hard-reload the page. Scanning these roots up front
+      // prebundles the same deps at startup instead of on a click.
+      //
+      // The paths are SOURCE_DIRS, the same contract discovery crawls, so a
+      // project can't have code here that discovery misses or vice versa. A
+      // glob that matches nothing (no src/entities, say) is simply skipped.
+      entries: [
+        // Kept first so an app with a hand-written <script> keeps its entry:
+        // setting `entries` replaces the default html scan.
+        'index.html',
+        CAPER_CONFIG_FILE,
+        APP_ENTRY_FILE,
+        ...Object.values(SOURCE_DIRS).map((dir) => `${dir}/**/*.{ts,tsx,js,jsx}`),
+      ],
+    },
+    define: {
+      __CAPER_APP_NAME: JSON.stringify(app.name),
+      __CAPER_APP_VERSION: JSON.stringify(app.version),
+    },
+  };
+}
+
+/** The partial config caper contributes for this project and command. */
+export function caperDefaults(userConfig, env) {
+  return fillMissing(userConfig, caperDefaultValues(env, userConfig)) ?? {};
+}

package/build/index.mjs

@@ -0,0 +1,96 @@
+/**
+ * `caper()` — the Vite preset. This is caper's whole build-time surface:
+ *
+ *     import { defineConfig } from 'vite';
+ *     import { caper } from '@caperjs/core/vite';
+ *
+ *     export default defineConfig({ plugins: [caper()] });
+ *
+ * and then plain `vite` / `vite build`. Caper contributes nothing except through
+ * Vite's own mechanisms, so plugin ordering, config merging and precedence are
+ * Vite's rules rather than caper's. The project's config is the only config.
+ *
+ * See `plan/vite-preset-rework.md` for why this replaced the old
+ * `defaultConfig` + `caper build` arrangement.
+ */
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+import wasm from 'vite-plugin-wasm';
+import { assetpackPlugin } from './assetpack.mjs';
+import { caperDefaults } from './defaults.mjs';
+import { readCaperBuildFlags } from './internal/buildFlags.mjs';
+import { assetTypesPlugin } from './plugins/assetTypes.mjs';
+import { caperConfigPlugin } from './plugins/caperConfig.mjs';
+import { caperDevHelperPlugin } from './plugins/devHelper.mjs';
+import { entityListPlugin, pluginListPlugin, popupListPlugin, sceneListPlugin, uiListPlugin } from './plugins/lists.mjs';
+import { pngFallbackPrunePlugin } from './plugins/pruneFallbacks.mjs';
+import { caperPwaPlugins } from './plugins/pwa.mjs';
+import { createCaperRuntimePlugin } from './plugins/runtime.mjs';
+
+const buildFlags = readCaperBuildFlags();
+
+function caperPluginList({ assets = {}, pwa } = {}) {
+  // `assets: false` opts out of the asset pipeline entirely — no assetpack run,
+  // no generated asset types. Replaces the old `noAssetpackConfig` export.
+  const { manifestUrl = 'assets.json', pngFallback = false, ...pipes } = assets === false ? {} : assets;
+  const assetPlugins =
+    assets === false
+      ? []
+      : [
+          assetpackPlugin(manifestUrl, pipes),
+          assetTypesPlugin(manifestUrl),
+          // Production ships webp only unless the project asks for the fallback.
+          ...(pngFallback ? [] : [pngFallbackPrunePlugin({ manifestUrl })]),
+        ];
+
+  return [
+    ...(buildFlags.useWasm ? [wasm()] : []),
+    createCaperRuntimePlugin({ pwa }),
+    viteStaticCopy({
+      // The captions plugin's bitmap font. `silent` matters: without it,
+      // vite-plugin-static-copy *throws* when the glob matches nothing, so any
+      // install layout that doesn't put caper's source at exactly this path
+      // fails the whole build over an optional font.
+      silent: true,
+      targets: [
+        {
+          src: './node_modules/@caperjs/core/src/plugins/captions/font/*.*',
+          dest: './assets/caper/font',
+        },
+      ],
+    }),
+    pluginListPlugin(),
+    sceneListPlugin(),
+    popupListPlugin(),
+    entityListPlugin(),
+    uiListPlugin(),
+    ...assetPlugins,
+    caperConfigPlugin(),
+    caperDevHelperPlugin(),
+    ...(pwa ? caperPwaPlugins(pwa) : []),
+  ];
+}
+
+/**
+ * @typedef {object} CaperOptions
+ * @property {object|false} [assets] AssetPack pixi-pipes overrides, deep-merged
+ *   over caper's defaults. `false` omits the asset plugins entirely. Set
+ *   `pngFallback: true` to keep the png twins a production build otherwise prunes.
+ * @property {object} [pwa] vite-plugin-pwa options, merged over caper's PWA
+ *   defaults. Absent means no service worker and no web manifest.
+ */
+
+/**
+ * @param {CaperOptions} [options]
+ * @returns {import('vite').PluginOption[]}
+ */
+export function caper(options = {}) {
+  return [
+    {
+      name: 'caper:defaults',
+      config: (userConfig, env) => caperDefaults(userConfig, env),
+    },
+    ...caperPluginList(options),
+  ];
+}
+
+export default caper;