@caperjs/core 0.1.2 → 0.2.1

package/build/plugins/runtime.mjs

@@ -0,0 +1,129 @@
+/**
+ * The `caper-runtime` virtual module: the entry the framework injects into
+ * index.html so an app needs no hand-written `src/index.ts` that only exists to
+ * import it.
+ *
+ * It installs the `Caper` global, hands the discovered scene/plugin/popup/entity
+ * /ui lists over, then boots the application from `virtual:caper-config`. When the
+ * preset was given a `pwa` option, the PWA runtime is appended here too — that is
+ * what makes `Caper.pwa` real, rather than the never-imported entry it used to
+ * live in.
+ */
+import { pwaRuntimeSnippet } from './pwa.mjs';
+
+export function createCaperRuntimePlugin({ pwa } = {}) {
+  const virtualModuleId = 'caper-runtime';
+  const resolvedVirtualModuleId = '\0' + virtualModuleId;
+
+  return {
+    name: 'vite-plugin-caper-runtime',
+    enforce: 'pre',
+    // Auto-inject the runtime entry so apps don't need a hand-written
+    // `src/index.ts` that just does `import('caper-runtime')`. Legacy HTML that
+    // already references the runtime (or a src/index.(ts|js) entry) is left
+    // untouched so existing apps keep working.
+    transformIndexHtml: {
+      order: 'pre',
+      handler(html) {
+        const referencesRuntime = html.includes('caper-runtime');
+        const referencesLegacyEntry = /<script[^>]*\bsrc=["'][^"']*src\/index\.(ts|js)["']/.test(html);
+        if (referencesRuntime || referencesLegacyEntry) {
+          return html;
+        }
+        return {
+          html,
+          tags: [
+            {
+              tag: 'script',
+              attrs: { type: 'module' },
+              children: 'import("caper-runtime");',
+              injectTo: 'body',
+            },
+          ],
+        };
+      },
+    },
+    resolveId(id) {
+      if (id === virtualModuleId) {
+        return resolvedVirtualModuleId;
+      }
+    },
+    load(id) {
+      if (id === resolvedVirtualModuleId) {
+        return `
+          import { pluginsList } from 'virtual:caper-plugins';
+          import { sceneList } from 'virtual:caper-scenes';
+          import { popupList } from 'virtual:caper-popups';
+          import { entityList } from 'virtual:caper-entities';
+          import { uiList } from 'virtual:caper-uis';
+          import { create, signalCaperReady, installCaperGlobal } from '@caperjs/core';
+
+          (globalThis).Caper = (globalThis).Caper || {};
+
+          // Install Caper.apps / Caper.ready() / Caper.automation immediately
+          // so automation drivers can await Caper.ready() before boot finishes.
+          installCaperGlobal();
+
+          try {
+            (globalThis).Caper.APP_NAME = __CAPER_APP_NAME;
+            (globalThis).Caper.APP_VERSION = __CAPER_APP_VERSION;
+          } catch (e) {
+            console.error('Failed to set app name and version', e);
+          }
+
+          (globalThis).Caper.sceneList = sceneList;
+          (globalThis).Caper.pluginsList = pluginsList;
+          (globalThis).Caper.popupList = popupList;
+          (globalThis).Caper.entityList = entityList;
+          (globalThis).Caper.uiList = uiList;
+
+          (globalThis).Caper.sceneIds = sceneList.map((scene) => scene.id);
+          (globalThis).Caper.pluginIds = pluginsList.map((plugin) => plugin.id);
+          (globalThis).Caper.popupIds = popupList.map((popup) => popup.id);
+          (globalThis).Caper.entityIds = entityList.map((entity) => entity.id);
+          (globalThis).Caper.uiIds = uiList.map((ui) => ui.id);
+
+          (globalThis).Caper.get = function (key) {
+            (globalThis).Caper = (globalThis).Caper || {};
+            return key ? (globalThis).Caper[key] : (globalThis).Caper;
+          };
+
+          async function bootstrap() {
+            const configModule = await import('virtual:caper-config');
+            const config = configModule.default;
+            (globalThis).Caper.config = config;
+            const app = await create(config);
+            const mains = import.meta.glob('/src/main.ts', { eager: true });
+            const mainPath = Object.keys(mains)[0];
+
+            if (mainPath) {
+              const mainModule = mains[mainPath];
+              if (mainModule && typeof mainModule.default === 'function') {
+                await mainModule.default(app);
+              }
+            }
+
+            signalCaperReady(app);
+          }
+
+          // Pass dev-ness through to the framework. This virtual module is
+          // transformed in the CONSUMER app's vite context, so import.meta.env
+          // is real here — inside the pre-built framework lib it has already
+          // been compiled away, so globals.ts reads Caper.__dev instead.
+          (globalThis).Caper.__dev = !!import.meta.env.DEV;
+
+          // Mark this app as managed by the vite runtime so create() does not
+          // double-signal readiness, then guard against a double bootstrap.
+          // (ES module caching already prevents re-evaluating this id; this is
+          // belt-and-braces.)
+          (globalThis).Caper.__runtimeManaged = true;
+          if (!(globalThis).__CAPER_BOOTSTRAPPED__) {
+            (globalThis).__CAPER_BOOTSTRAPPED__ = true;
+            bootstrap();
+          }
+${pwa ? pwaRuntimeSnippet(pwa) : ''}
+        `;
+      }
+    },
+  };
+}

package/cli.mjs

@@ -10,7 +10,6 @@ import { compress } from './cli/audio/index.mjs';
 import { create } from './cli/create.mjs';
 import { installPeerDeps } from './cli/install-peerdeps.mjs';
 import { update } from './cli/update.mjs';
-import { runBuild, runPreview, startDevServer } from './cli/vite.mjs';
 import { generateVoiceoverCSV } from './cli/voiceover/index.mjs';
 
 const currentVersion = process.versions.node;
@@ -48,15 +47,19 @@ switch (args[0]) {
     break;
   case 'version':
     break;
+  // `dev` / `build` / `preview` / `start` were removed in 0.2.0: a project runs
+  // vite directly now, with `caper()` in its own vite.config. Named here so the
+  // error says what to do rather than just "unknown subcommand".
   case 'dev':
   case 'start':
-    await startDevServer();
-    break;
   case 'build':
-    await runBuild();
-    break;
   case 'preview':
-    await runPreview();
+    console.error(
+      bold(bgRed(white(`Caper - "${args[0]}" was removed in 0.2.0.`))),
+      red(`Run vite directly: \`vite\` to develop, \`vite build\` to build.`),
+    );
+    console.error(red(`Your vite.config should contain: plugins: [caper()] — from '@caperjs/core/vite'.`));
+    process.exit(1);
     break;
   case 'add':
     await add(args.slice(1));

package/extras/llms.txt

@@ -163,10 +163,10 @@ test`) catches a lot, but UI/scene/asset behavior only shows up live.
 After any non-trivial change:
 
 1. Type-check the app (`pnpm types` or `tsc`).
-2. Build cleanly (`caper build` or the app's `build` script).
-3. **Ask the human to run `caper dev`** and eyeball the affected scene/feature.
+2. Build cleanly (`vite build`, or the app's `build` script).
+3. **Ask the human to run `vite`** (the app's `dev` script) and eyeball the affected scene/feature.
 
-Do **not** start `caper dev` yourself — it runs forever and will block. Ask the
+Do **not** start the dev server yourself — it runs forever and will block. Ask the
 user to verify visually and report back.
 
 ---
@@ -210,9 +210,9 @@ subcommands run from the app root.
 | --- | --- |
 | `caper create [path] [--use-pnpm\|--use-yarn]` | Interactive scaffolder for a new Caper app. Also exposed as `create-caper`. |
 | `caper add scene \| plugin \| popup \| entity <Name> [--dir path]` | **Primary scaffolding entry.** Emits `src/<kind>s/<Name>.ts` with `defineX` wrapper + default class + the correct import shape. |
-| `caper dev` (alias `caper start`) | Start Vite dev server with Caper plugin pre-wired. |
-| `caper build` | Production build. |
-| `caper preview` | Build then preview locally. |
+| `vite` | Start the dev server. Caper is wired in through `caper()` in the app's own `vite.config.ts`. |
+| `vite build` | Production build. |
+| `vite build && vite preview` | Build then preview locally. |
 | `caper update` | Update Caper to latest. |
 | `caper install` | Install peer deps (rarely needed; normally automatic). |
 | `caper vo generate [inputDir] [outputDir]` | Voiceover CSV generation from locales. Defaults: `./src/locales` → `./src/assets/audio/vo/csv`. |
@@ -230,9 +230,9 @@ required (plugins are the one exception — see §1.1).
 
 ```jsonc
 {
-  "dev":     "pnpm clean && caper dev",
-  "build":   "pnpm clean && caper build",
-  "preview": "pnpm clean && caper preview",
+  "dev":     "pnpm clean && vite",
+  "build":   "pnpm clean && vite build",
+  "preview": "pnpm clean && vite build && vite preview",
   "types":   "tsc",
   "clean":   "rimraf dist .assetpack .cache",
   "lint":    "eslint \"src/**/*.ts\""
@@ -915,7 +915,7 @@ export default class MyPlugin extends Plugin<MyPluginOptions> {
 - Listed dep IDs must exist in `caper.config.ts plugins: []` (see §1.1). Bootstrap
   throws with an actionable error if not.
 - Cycles fail bootstrap with the cycle path printed.
-- Build-time validation also warns at `caper dev`/`build` time.
+- Build-time validation also warns at dev/build time.
 
 ### 9.5 Exposing API
 
@@ -1077,9 +1077,15 @@ compression, spritesheets, webfonts, audio, Spine, Rive, and the custom
 **`fontWeights`** pipe that runs before the webfont pipe to convert
 `{weight=X}` to `weights: [X]` for PixiJS.
 
-### 11.4 Per-app override: `.assetpack.mjs`
+### 11.4 Per-app override: `caper({ assets })`
 
-If `.assetpack.mjs` exists at the app root, Caper's framework config loads it
+Pass `assets` to the preset in `vite.config.ts`. It is deep-merged over caper's
+defaults, so overriding one knob keeps its siblings; `resolutions` replaces
+outright because it is a whole set of tiers. `assets: false` turns the pipeline
+off, and `assets: { pngFallback: true }` keeps the png twins that a production
+build otherwise prunes.
+
+Removed in 0.2.0: `.assetpack.mjs`. If one exists at the app root, Caper
 via `import()` and merges it in. Only needed when injecting custom pipes.
 
 ### 11.5 Loading from code
@@ -1218,7 +1224,7 @@ plugins: [
 
 ## 14. Generated types & virtual modules
 
-The Vite plugin ([config/vite.mjs](../config/vite.mjs)) generates types on every
+The Vite plugin ([build/](../build)) generates types on every
 dev reload. **Do not hand-edit them** — delete stale copies after renames and let
 the next build regen.
 
@@ -1278,9 +1284,9 @@ implementation of the auto-wiring. Know they exist for debugging.
 
 Types regen on dev-server restart. After renaming a scene / plugin / popup /
 entity: delete the stale `caper-app.d.ts` / `caper-assets.d.ts`, then
-`caper dev` — they're re-emitted from scratch.
+the dev server — they're re-emitted from scratch.
 
-**Source references:** [config/vite.mjs](../config/vite.mjs).
+**Source references:** [build/plugins/assetTypes.mjs](../build/plugins/assetTypes.mjs).
 
 ---
 
@@ -1491,8 +1497,8 @@ Type-check and build don't catch UI/scene/asset regressions. After changes:
 
 ```bash
 pnpm types          # or tsc — compiles clean
-pnpm build          # or caper build — builds clean
-# then ask the human to run `pnpm dev` (or `caper dev`) and report visually
+pnpm build          # or vite build — builds clean
+# then ask the human to run `pnpm dev` and report visually
 ```
 
 Do not start the dev server yourself — it runs forever and blocks.

package/lib/caper.mjs

@@ -202,7 +202,7 @@ function B(e, t) {
 }
 //#endregion
 //#region src/version.ts
-var V = "0.1.2", H = "8.19.0", kn = "     ........        .....     ............    ............. ...........     \n  .............     .......   ................ ............. ..............  \n ..............    .........   ............... ............. ..............  \n .....            ...........   .............. ............  ..............  \n .....           ...... ......  .............. ............. .............   \n .............. ......   .....  ............   ............. .....  ......   \n  ...................     ..... .....          ............. .....   ....... \n    ................       ..........          ............. .....     ..... ";
+var V = "0.2.1", H = "8.19.0", kn = "     ........        .....     ............    ............. ...........     \n  .............     .......   ................ ............. ..............  \n ..............    .........   ............... ............. ..............  \n .....            ...........   .............. ............  ..............  \n .....           ...... ......  .............. ............. .............   \n .............. ......   .....  ............   ............. .....  ......   \n  ...................     ..... .....          ............. .....   ....... \n    ................       ..........          ............. .....     ..... ";
 function U() {
 	let e = `\n${kn}\n\n v${V} | %cPixi.js v${H} %c| %chttps://github.com/anthonysapp/caper\n\n`;
 	console.log(e, "color: #E91E63; font-weight: 600;", "color: inherit;", "color: #00BCD4; text-decoration: underline;");