@caperjs/core 0.5.1 → 0.6.0

package/extras/llms.txt

@@ -7,7 +7,7 @@ on every `Container`, build-time auto-discovery of scenes/plugins/popups/entitie
 and generated TypeScript types for app IDs and assets. Caper is a personal fork
 of `dill-pixel` by Relish Studios.
 
-**Package version:** `@caperjs/core@6.2.2` · **Peer deps:** `pixi.js@8.x`, `@pixi/sound@^6`, `gsap@^3.13`.
+**Package version:** see `../package.json` (this file ships inside the package) · **Peer deps:** `pixi.js@8.x`, `@pixi/sound@^6`, `gsap@^3.13`.
 
 **File citations in this guide** point at the `@caperjs/core` package source
 (paths relative to this file, e.g. `../src/core/Application.ts`) — those ship
@@ -39,7 +39,8 @@ produce working code.
 14. [Generated types & virtual modules](#14-generated-types--virtual-modules)
 15. [Common recipes](#15-common-recipes)
 16. [Gotchas & verification loop](#16-gotchas--verification-loop)
-17. [API reference index](#17-api-reference-index)
+17. [Automation bridge — drive the running app](#17-automation-bridge--drive-the-running-app)
+18. [API reference index](#18-api-reference-index)
 
 ---
 
@@ -213,6 +214,10 @@ subcommands run from the app root.
 | `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 types [--no-assets]` | Regenerate `src/types/caper-app.d.ts` + `caper-assets.d.ts` **without a dev server** (runs AssetPack once unless `--no-assets`). Use after a fresh clone or a rename. |
+| `caper doctor [--offline] [--json]` | One-screen health check: installed vs latest caper, npm vs linked engine (and whether the linked build is stale), generated types present/fresh, asset manifest, agent pointers, peer deps, caches. Exit 1 on any ✗. |
+| `caper agent init [--dir <skillsDir>]` | Install the shipped `caper` agent skill (default `.claude/skills/caper/SKILL.md`) and upsert a pointer block into `AGENTS.md`/`CLAUDE.md`. Re-run after upgrading caper. |
+| `caper agent probe <url> [--action n[=json]]… [--until "<js predicate>"] [--wait ms] [--screenshot p] [--headed] [--json]` | Drive a **running** app headlessly through the automation bridge (§17) in a Chromium you own: boots, sends actions, waits on state, returns context/state/log/errors (+ screenshot). Needs `playwright` in the app's devDependencies. |
 | `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`. |
@@ -1282,9 +1287,9 @@ implementation of the auto-wiring. Know they exist for debugging.
 
 ### 14.4 Regenerating
 
-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
-the dev server — they're re-emitted from scratch.
+Types regen on dev-server restart, or on demand with `npx caper types`
+(no server; runs AssetPack once unless `--no-assets`). After renaming a scene /
+plugin / popup / entity, or on a fresh clone, run it before typechecking.
 
 **Source references:** [build/plugins/assetTypes.mjs](../build/plugins/assetTypes.mjs).
 
@@ -1505,10 +1510,11 @@ Do not start the dev server yourself — it runs forever and blocks.
 
 ### 16.3 Regenerate types after renames
 
-After renaming a scene/plugin/popup/entity, delete
-`src/types/caper-app.d.ts` and `src/types/caper-assets.d.ts` (they're
-generated), then run `pnpm dev`. Old IDs stuck in the union cause weird
-downstream type errors.
+After renaming a scene/plugin/popup/entity run `npx caper types` (regenerates
+`src/types/caper-app.d.ts` and `caper-assets.d.ts` from scratch, no dev server
+needed). Same fix for a fresh clone where the generated files are gitignored. Old
+IDs stuck in the union cause weird downstream type errors. `npx caper doctor`
+tells you when they are stale.
 
 ### 16.4 Fail loud in plugins (see §1.2)
 
@@ -1543,7 +1549,96 @@ cache produces confusing texture/name mismatches.
 
 ---
 
-## 17. API reference index
+## 17. Automation bridge — drive the running app
+
+Every app registers itself on `window.Caper` at boot (source:
+[`../src/core/globals.ts`](../src/core/globals.ts)). This is how an agent,
+Playwright script, or smoke test drives a Caper app without clicking around.
+
+### 17.1 What is always there
+
+```ts
+Caper.apps            // Map<appId, app>  (appId = caper.config.ts `id`, else 'CaperApplication')
+Caper.app             // last created app
+await Caper.ready()   // resolves when the first app has fully booted (safe to call early)
+await Caper.ready('my-app-id')
+```
+
+### 17.2 The automation facade (gated)
+
+Enabled when **any** of: dev server (`import.meta.env.DEV`), `automation: true`
+in `caper.config.ts`, or env `VITE_CAPER_AUTOMATION=true` at build time. When on,
+`Caper.automation[appId]` (also `app.automation`) exposes:
+
+| Member | What it does |
+| --- | --- |
+| `action(name, data?)` | `app.sendAction(name, data)`. Subject to the ActionsPlugin context rules — out-of-context actions are dropped, same as a real input. |
+| `getContext()` | Current action context as a string (e.g. `'game'`, `'popup'`). |
+| `getState()` | Whatever the app's registered state getter returns (`undefined` until registered). |
+| `registerStateGetter(fn)` | App code calls this once to expose a snapshot of game state. |
+| `notifyStateChanged(state)` | App code calls this on each meaningful change; re-runs pending `waitFor` predicates and logs a `state` entry. |
+| `waitFor(predicate, { timeoutMs? })` | Resolves with the state the first time `predicate(state)` is true (checked immediately, then on every `notifyStateChanged`). Rejects on timeout. |
+| `log` | Ring buffer of the last 200 entries: `{ t, kind: 'action' \| 'state' \| 'context', name?, data? }`. Only **dispatched** actions are logged (dropped ones are not). |
+
+### 17.3 App-side wiring (once per game)
+
+```ts
+// in the main scene's initialize(), or wherever the game state lives
+this.app.automation?.registerStateGetter(() => this.store.snapshot());
+this.store.onChanged.connect((s) => this.app.automation?.notifyStateChanged(s));
+```
+
+Keep the snapshot plain data (no display objects) so predicates stay cheap and
+serializable for drivers outside the page.
+
+### 17.4 Driving it
+
+Use a browser you own. Launch a separate Chromium with Playwright (isolated,
+throwaway profile) and point it at the dev server; do **not** attach to or drive the
+human's own browser session unless they ask you to look at one of their tabs.
+
+The shipped driver does the common case with no code:
+
+```bash
+npx caper agent probe http://localhost:3000/ --action fire --until "s => s && s.phase === 'resolved'" --screenshot scratch/after-fire.png --json
+# → { appId, automation, context, state, actions, log, pageErrors, consoleErrors, screenshot, durationMs }; exit 1 on boot/until timeout or page errors
+```
+
+Write your own only when you need more than actions + one predicate:
+
+```ts
+import { chromium } from 'playwright';
+const browser = await chromium.launch();   // headless; { headless: false } only when a human watches
+const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+page.on('pageerror', (e) => console.error('pageerror', e));
+await page.goto('http://localhost:3000/');
+await page.waitForFunction(() => window.Caper?.__readyApps?.size > 0);
+const result = await page.evaluate(async () => {
+  const app = await Caper.ready();
+  const a = Caper.automation[app.config.id];
+  a.action('fire');
+  const s = await a.waitFor((st) => st?.phase === 'resolved', { timeoutMs: 10_000 });
+  return { context: a.getContext(), state: s, actions: a.log.filter((e) => e.kind === 'action').map((e) => e.name) };
+});
+await page.screenshot({ path: 'scratch/after-fire.png' });
+await browser.close();
+```
+
+Rules of thumb:
+
+- Prefer `action()` over synthesising pointer events — it goes through the same
+  ActionsPlugin path as a real button, so context gating and action signals behave
+  identically.
+- If an action seems ignored, check `getContext()` first: it was probably dropped
+  as out-of-context. That is by design (see §1 / gotchas), not a bug.
+- `waitFor` only re-evaluates on `notifyStateChanged`; if it never resolves, the
+  app is not calling `notifyStateChanged` for that transition.
+- For a boot-only smoke test you need none of the facade: assert
+  `Caper.apps.size > 0` after `Caper.ready()` and that the page logged no errors.
+
+---
+
+## 18. API reference index
 
 Flat jump table. Name → section → one-line.
 
@@ -1604,5 +1699,5 @@ Flat jump table. Name → section → one-line.
 
 ---
 
-**Last updated:** `@caperjs/core@6.2.2` (PixiJS 8.x). When in doubt, read the
+**Last updated:** with `@caperjs/core@0.5.x` (PixiJS 8.x); version in `../package.json`. When in doubt, read the
 cited framework source file — signatures and defaults are authoritative there.

package/extras/skills/caper/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: caper
+description: Work on a game built with the Caper engine (@caperjs/core, PixiJS v8). Use before touching scenes, entities, popups, UI, plugins, caper.config.ts, assets, generated types, or the dev/verify loop in any app that depends on @caperjs/core. Routes you to the exact section of the shipped reference (llms.txt) instead of the whole engine, and gives the verify loop (typecheck, build, headless automation bridge). Trigger for "caper", "add a scene/entity/popup/plugin", "factory methods", "add.sprite", "defineScene", "actions", "UICanvas", "FlexContainer", "caper.config", "caper-app.d.ts", "assetpack", "window.Caper", or any error mentioning @caperjs.
+---
+
+# Caper — how to work in a Caper app
+
+This skill is shipped by `@caperjs/core` and copied here by `caper agent init`.
+Do not edit it; re-run `npx caper agent init` after upgrading caper.
+
+## 1. Read the reference by section, never whole
+
+The full consumer reference is `node_modules/@caperjs/core/extras/llms.txt`
+(~1,600 lines). Load only the section you need:
+
+```bash
+grep -n '^## ' node_modules/@caperjs/core/extras/llms.txt      # section line numbers
+sed -n '<start>,<end>p' node_modules/@caperjs/core/extras/llms.txt
+```
+
+| You need to…                                  | Read section                       |
+| --------------------------------------------- | ---------------------------------- |
+| know the rules before writing any code        | §1 Rules of engagement             |
+| scaffold a scene / entity / popup / plugin    | §2.2 CLI, §15 Recipes              |
+| boot, `create()`, custom `Application`        | §3                                 |
+| `caper.config.ts`, actions, contexts, data    | §4                                 |
+| scene lifecycle, assets per scene, transitions| §5                                 |
+| build a display tree (`add.*` / `make.*`)     | §6 (full catalog at §6.1)          |
+| buttons, flex layout, popups, toasts, HUD     | §7                                 |
+| `app.scenes / actions / popups / audio / …`   | §8                                 |
+| write or fix a plugin                         | §9                                 |
+| assets, bundles, AssetPack tags               | §11                                |
+| signals, store, mixins                        | §12                                |
+| generated types, virtual modules              | §14                                |
+| drive the running app headlessly              | §17 Automation bridge              |
+| look up one symbol                            | §18 API index (name → section)     |
+
+Engine source also ships: `node_modules/@caperjs/core/src/`. When the doc is
+not enough, open the one file the doc cites, not the whole tree.
+
+## 2. The rules (llms.txt §1, condensed)
+
+1. `caper.config.ts` `plugins: [...]` is authoritative; list every plugin,
+   including ones other plugins `require`.
+2. Fail loud. No silent fallbacks in plugins or config.
+3. Metadata goes on `defineScene / defineEntity / definePopup / definePlugin`
+   wrappers, not class statics. Default-export the class so discovery finds it.
+4. `this.add.*` / `this.make.*` over `new Sprite()` / `new Text()` /
+   `new Graphics()` / `new Container()`. Extend Caper's `Container`, not Pixi's.
+5. `npx caper add scene|entity|popup|plugin <Name>` before hand-authoring.
+6. Verify in the running app, not in isolation (see §3 below).
+
+## 3. Verify loop
+
+```bash
+npx caper doctor      # 10 lines: which caper, types fresh?, pointers, peers. Fix ✗/⚠ first
+npx caper types       # regenerate caper-app.d.ts + caper-assets.d.ts, no dev server (fresh clone, renames)
+pnpm typecheck        # or the app's tsc script; first gate after any .ts change
+pnpm build            # vite build; catches asset and discovery errors
+```
+
+Then check behaviour live, cheapest first:
+
+- **Use your own browser, never the human's.** Launch a separate Chromium with
+  Playwright (a script via `npx tsx`, or the Playwright MCP tools) pointed at the
+  dev-server URL. Do **not** attach to or drive the human's own Chrome (for
+  example claude-in-chrome tabs) unless they ask you to look at a tab of theirs.
+  Headless for checks; headed (`headless: false`) only when a human will watch.
+
+  ```ts
+  import { chromium } from 'playwright';
+  const browser = await chromium.launch();               // isolated, throwaway profile
+  const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+  page.on('pageerror', (e) => console.error('pageerror', e));
+  await page.goto('http://localhost:3000/');
+  await page.waitForFunction(() => window.Caper?.__readyApps?.size > 0);
+  await page.screenshot({ path: 'scratch/after-change.png' });
+  await browser.close();
+  ```
+
+- **Headless via the automation bridge** (dev server, or `automation: true`
+  in config, or `VITE_CAPER_AUTOMATION=true`). Shipped driver, no code:
+  `npx caper agent probe <url> [--action name[=json]]… [--until "s => …"] [--screenshot p] [--json]`
+  → context, state, action log, page/console errors, exit 1 on failure. For
+  anything richer, in Playwright: `const app = await Caper.ready(); const a =
+  Caper.automation[app.config.id];` then `a.action('name', data)`,
+  `a.getContext()`, `a.getState()`, `await a.waitFor(s => …, { timeoutMs })`,
+  and inspect `a.log` (last 200 entries). Details: llms.txt §17.
+- **Do not start the dev server yourself** and leave it running in the
+  foreground; it never exits. If the human has it running, use it. Otherwise
+  ask them to run `pnpm dev` and report.
+
+## 4. Gotchas that cost agents the most time
+
+- Out-of-context actions are **dropped by the ActionsPlugin**. That is the
+  phase guard; do not add `if (phase !== …)` checks around `sendAction`.
+- `src/types/caper-app.d.ts` and `caper-assets.d.ts` are **generated**. Never
+  hand-edit. Missing (fresh clone; they are usually gitignored) or stale after a
+  rename → `npx caper types`. No dev server needed.
+- Weird asset / name mismatches → `rm -rf .assetpack .cache dist` and rebuild.
+- Renamed a scene / popup / entity id? Regenerate types (above) or old ids
+  linger in the unions and cause confusing downstream errors.
+- If the engine is **linked from a local checkout**, consumer apps resolve the
+  built `lib/`; rebuild the engine (`pnpm framework:build` in the caper repo)
+  after editing engine source, unless the app's vite config aliases
+  `@caperjs/core` to the engine `src/`. `npx caper doctor` reports "linked from
+  …" and flags a stale build.

package/lib/caper.mjs

@@ -204,7 +204,7 @@ function B(e, t) {
 }
 //#endregion
 //#region src/version.ts
-var V = "0.5.1", H = "8.19.0", Mn = "     ........        .....     ............    ............. ...........     \n  .............     .......   ................ ............. ..............  \n ..............    .........   ............... ............. ..............  \n .....            ...........   .............. ............  ..............  \n .....           ...... ......  .............. ............. .............   \n .............. ......   .....  ............   ............. .....  ......   \n  ...................     ..... .....          ............. .....   ....... \n    ................       ..........          ............. .....     ..... ";
+var V = "0.6.0", H = "8.19.0", Mn = "     ........        .....     ............    ............. ...........     \n  .............     .......   ................ ............. ..............  \n ..............    .........   ............... ............. ..............  \n .....            ...........   .............. ............  ..............  \n .....           ...... ......  .............. ............. .............   \n .............. ......   .....  ............   ............. .....  ......   \n  ...................     ..... .....          ............. .....   ....... \n    ................       ..........          ............. .....     ..... ";
 function U() {
 	let e = `\n${Mn}\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;");