@caperjs/core 0.5.0 → 0.5.2

package/README.md

@@ -8,7 +8,13 @@ It sits on top of PixiJS — a renderer, not a game engine — and adds the part
 
 ## Status
 
-This package is **not yet published to npm**. The recommended way to use it is to clone the [Caper monorepo](https://github.com/anthonysapp/caper), run the kitchen-sink, and either fork it as a starter or vendor `packages/core` into your own project. First publish lands in Phase 7.
+Published on npm as `@caperjs/core`.
+
+## For AI agents
+
+- `npx caper agent init` installs the `caper` skill + `AGENTS.md` pointers for this project.
+- The reference is `node_modules/@caperjs/core/extras/llms.txt` — read it by section (`grep -n '^## '`), not whole.
+- Engine source ships in the package under `src/`.
 
 ## Highlights
 

package/build/plugins/assetTypes.mjs

@@ -69,29 +69,39 @@ async function generateAssetTypes(manifest, assetsDir) {
           addToBundle('spritesheets', bundle.name, alias);
         });
 
-        // Extract frame names from TPS JSON files
+        // Extract frame names from TPS JSON files, following the multipack
+        // chain. A sheet too big for one page is split, and only page 0 reaches
+        // the manifest — the rest hang off its `meta.related_multi_packs`, which
+        // is how PixiJS finds them too. Reading page 0 alone would type only the
+        // frames the packer happened to fit there, so a frame's alias would
+        // appear and vanish as unrelated art shifted the packing.
         if (asset.data?.tags?.tps) {
-          try {
-            // Find the first .json file in the src array
-            const jsonSrc = srcs.find((src) => src.endsWith('.json'));
-            if (jsonSrc) {
-              // Construct the full path to the JSON file
+          const queue = srcs.filter((src) => src.endsWith('.json')).slice(0, 1);
+          const seen = new Set(queue);
+          while (queue.length) {
+            const jsonSrc = queue.shift();
+            try {
               const jsonPath = path.join(assetsDir, jsonSrc);
+              const tpsData = JSON.parse(await fs.promises.readFile(jsonPath, 'utf8'));
 
-              // Read and parse the JSON file
-              const jsonContent = await fs.promises.readFile(jsonPath, 'utf8');
-              const tpsData = JSON.parse(jsonContent);
+              for (const frameName of Object.keys(tpsData.frames || {})) {
+                assetsByType.tpsFrames.add(frameName);
+                addToBundle('tpsFrames', bundle.name, frameName);
+              }
 
-              // Extract frame names from the "frames" object
-              if (tpsData.frames) {
-                Object.keys(tpsData.frames).forEach((frameName) => {
-                  assetsByType.tpsFrames.add(frameName);
-                  addToBundle('tpsFrames', bundle.name, frameName);
-                });
+              // Related pages are named relative to the page that lists them.
+              // `seen` keeps a self- or cross-referencing chain from looping.
+              const dir = path.dirname(jsonSrc);
+              for (const related of tpsData.meta?.related_multi_packs || []) {
+                const next = path.join(dir, related);
+                if (!seen.has(next)) {
+                  seen.add(next);
+                  queue.push(next);
+                }
               }
+            } catch (error) {
+              logger.warn(`Failed to load TPS frames from ${jsonSrc}:`, error.message);
             }
-          } catch (error) {
-            logger.warn(`Failed to load TPS frames from ${firstSrc}:`, error.message);
           }
         }
       } else if (ext === '.json' && !firstSrc.includes('atlas')) {

package/cli/agent.mjs

@@ -0,0 +1,106 @@
+import { bgRed, bold, cyan, green, white } from 'kleur/colors';
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * `caper agent init` — installs the shipped `caper` agent skill into the
+ * current app and upserts a marker-delimited pointer block into the app's
+ * agent context file (`AGENTS.md` or `CLAUDE.md`).
+ */
+
+const START_MARKER = '<!-- caper:agent-start -->';
+const END_MARKER = '<!-- caper:agent-end -->';
+
+// `.href` so this also works where the global URL is a DOM polyfill (vitest + happy-dom).
+function resolveModuleRelative(rel) {
+  return fileURLToPath(new URL(rel, import.meta.url).href);
+}
+
+function readVersion() {
+  return JSON.parse(fs.readFileSync(resolveModuleRelative('../package.json'), 'utf-8')).version;
+}
+
+function makeBlock(skillPath, version) {
+  return `${START_MARKER}
+## Caper (engine) — agent pointers
+
+This app runs on the Caper engine (\`@caperjs/core@${version}\`). Generated by \`caper agent init\`; re-run it after upgrading caper. Do not edit between these markers.
+
+- Before engine-facing work (scenes, entities, popups, UI, plugins, \`caper.config.ts\`, assets, generated types), load the \`caper\` skill at \`${skillPath}\`.
+- Read the reference by section, not whole: \`node_modules/@caperjs/core/extras/llms.txt\` (\`grep -n '^## '\` for the outline). Engine source ships at \`node_modules/@caperjs/core/src/\`.
+- Verify: typecheck → build → drive the running app through \`window.Caper\` / \`Caper.automation[appId]\` (llms.txt §17). Never leave a dev server running in the foreground.
+${END_MARKER}`;
+}
+
+function upsertContext(cwd, dir) {
+  const candidates = ['AGENTS.md', 'CLAUDE.md'];
+  let contextFile = candidates.find((name) => fs.existsSync(path.join(cwd, name)));
+
+  if (!contextFile) {
+    contextFile = 'AGENTS.md';
+  }
+
+  const contextPath = path.resolve(cwd, contextFile);
+  const existing = fs.existsSync(contextPath) ? fs.readFileSync(contextPath, 'utf-8') : '';
+  const skillPath = path.posix.join(dir, 'caper/SKILL.md');
+  const version = readVersion();
+  const block = makeBlock(skillPath, version);
+
+  const startIndex = existing.indexOf(START_MARKER);
+  const endIndex = existing.indexOf(END_MARKER);
+
+  let contents;
+  if (startIndex !== -1 && endIndex !== -1 && endIndex > startIndex) {
+    const before = existing.slice(0, startIndex);
+    const after = existing.slice(endIndex + END_MARKER.length);
+    const trimmedBefore = before.replace(/\s+$/, '');
+    const trimmedAfter = after.replace(/^\s+/, '');
+    const spacerBefore = trimmedBefore ? '\n\n' : '';
+    const spacerAfter = trimmedAfter ? '\n\n' : '';
+    contents = `${trimmedBefore}${spacerBefore}${block}${spacerAfter}${trimmedAfter}`;
+  } else if (existing) {
+    const spacer = existing.endsWith('\n\n') ? '' : '\n\n';
+    contents = `${existing.replace(/\s+$/, '')}${spacer}${block}\n`;
+  } else {
+    contents = `${block}\n`;
+  }
+
+  fs.writeFileSync(contextPath, contents, 'utf-8');
+  return contextPath;
+}
+
+export async function agentInit(cwd, { dir = '.claude/skills' } = {}) {
+  const skillSource = resolveModuleRelative('../extras/skills/caper/SKILL.md');
+  const skillDir = path.resolve(cwd, dir, 'caper');
+  const skillFile = path.join(skillDir, 'SKILL.md');
+
+  fs.mkdirSync(skillDir, { recursive: true });
+  fs.copyFileSync(skillSource, skillFile);
+
+  const contextFile = upsertContext(cwd, dir);
+
+  console.log(green(bold('✓ Created caper skill')) + ` ${cyan(path.relative(cwd, skillFile).replace(/\\/g, '/'))}`);
+  console.log(green(bold('✓ Updated agent context')) + ` ${cyan(path.relative(cwd, contextFile).replace(/\\/g, '/'))}`);
+
+  return { skillFile, contextFile };
+}
+
+export async function agent(args) {
+  if (args[0] === 'init') {
+    let dir = '.claude/skills';
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === '--dir' && args[i + 1]) {
+        dir = args[i + 1];
+        i++;
+      }
+    }
+    await agentInit(process.cwd(), { dir });
+    return;
+  }
+
+  const subcommand = args[0] ?? '(none)';
+  console.error(bold(bgRed(white(`Unknown agent command: "${subcommand}". Please use "init".`))));
+  process.exit(1);
+}

package/cli/agent.test.mjs

@@ -0,0 +1,104 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { agentInit } from './agent.mjs';
+
+const shippedSkill = path.resolve(process.cwd(), 'extras/skills/caper/SKILL.md');
+
+const START_MARKER = '<!-- caper:agent-start -->';
+
+let tempDir = null;
+
+afterEach(() => {
+  if (tempDir && fs.existsSync(tempDir)) {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  }
+  tempDir = null;
+});
+
+function makeTempDir() {
+  tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'caper-agent-'));
+  return tempDir;
+}
+
+function countMarkers(contents) {
+  return {
+    start: (contents.match(/<!-- caper:agent-start -->/g) || []).length,
+    end: (contents.match(/<!-- caper:agent-end -->/g) || []).length,
+  };
+}
+
+describe('agentInit', () => {
+  it('creates the default skill copy and AGENTS.md when no context file exists', async () => {
+    const cwd = makeTempDir();
+
+    const { skillFile, contextFile } = await agentInit(cwd);
+
+    expect(fs.existsSync(skillFile)).toBe(true);
+    expect(fs.readFileSync(skillFile, 'utf-8')).toBe(fs.readFileSync(shippedSkill, 'utf-8'));
+    expect(path.basename(contextFile)).toBe('AGENTS.md');
+
+    const context = fs.readFileSync(contextFile, 'utf-8');
+    expect(context).toContain('<!-- caper:agent-start -->');
+    expect(context).toContain('<!-- caper:agent-end -->');
+    expect(context).toContain('.claude/skills/caper/SKILL.md');
+  });
+
+  it('respects --dir and references the custom skill path', async () => {
+    const cwd = makeTempDir();
+
+    const { skillFile, contextFile } = await agentInit(cwd, { dir: 'skills' });
+
+    expect(skillFile).toBe(path.join(cwd, 'skills/caper/SKILL.md'));
+    expect(fs.existsSync(skillFile)).toBe(true);
+
+    const context = fs.readFileSync(contextFile, 'utf-8');
+    expect(context).toContain('skills/caper/SKILL.md');
+    expect(context).not.toContain('.claude/skills/caper/SKILL.md');
+  });
+
+  it('appends the block to CLAUDE.md when only CLAUDE.md exists', async () => {
+    const cwd = makeTempDir();
+    const original = '# Project CLAUDE.md\n\nSome existing guidance.\n';
+    fs.writeFileSync(path.join(cwd, 'CLAUDE.md'), original, 'utf-8');
+
+    const { skillFile, contextFile } = await agentInit(cwd);
+
+    expect(path.basename(contextFile)).toBe('CLAUDE.md');
+    expect(fs.existsSync(path.join(cwd, 'AGENTS.md'))).toBe(false);
+
+    const context = fs.readFileSync(contextFile, 'utf-8');
+    expect(context).toContain('Some existing guidance.');
+    expect(context).toContain('<!-- caper:agent-start -->');
+    expect(context).toContain('<!-- caper:agent-end -->');
+    expect(context.indexOf('Some existing guidance.')).toBeLessThan(context.indexOf(START_MARKER));
+  });
+
+  it('is idempotent and preserves user edits outside the markers', async () => {
+    const cwd = makeTempDir();
+
+    await agentInit(cwd);
+    const first = fs.readFileSync(path.join(cwd, 'AGENTS.md'), 'utf-8');
+
+    // User edits outside the markers
+    const edited = `# App pointers\n\n${first}\n\n## Custom section\n\nKeep me.\n`;
+    fs.writeFileSync(path.join(cwd, 'AGENTS.md'), edited, 'utf-8');
+
+    await agentInit(cwd);
+    const second = fs.readFileSync(path.join(cwd, 'AGENTS.md'), 'utf-8');
+
+    const markers = countMarkers(second);
+    expect(markers.start).toBe(1);
+    expect(markers.end).toBe(1);
+    expect(second).toContain('# App pointers');
+    expect(second).toContain('## Custom section');
+    expect(second).toContain('Keep me.');
+
+    // Replace the block with the freshly generated one so we can compare the rest
+    const start = second.indexOf('<!-- caper:agent-start -->');
+    const end = second.indexOf('<!-- caper:agent-end -->') + '<!-- caper:agent-end -->'.length;
+    const regenerated = second.slice(start, end);
+    expect(regenerated).toBe(first.trimEnd());
+  });
+});

package/cli/create.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { promisify } from 'node:util';
 import shell from 'shelljs';
+import { agentInit } from './agent.mjs';
 import { copy, dist, mkdirp, package_manager } from './utils.mjs';
 
 let packageManager = package_manager;
@@ -150,7 +151,7 @@ export function injectPluginsIntoConfig(configContents, pluginConfigs) {
  * @param {string} cwd
  * @param {string[]} plugins
  */
-function write_template_files(cwd, template, applicationNameForPkg, applicationName, defaultName, plugins) {
+async function write_template_files(cwd, template, applicationNameForPkg, applicationName, defaultName, plugins) {
   const dir = dist(`templates/${template}`);
   copy(`${dir}/package.template.json`, `${cwd}/package.json`);
 
@@ -209,6 +210,14 @@ function write_template_files(cwd, template, applicationNameForPkg, applicationN
   readme_contents = readme_contents.replace(/~PACKAGE_MANAGER~/g, mgr);
   fs.writeFileSync(readme_file, readme_contents, 'utf-8');
 
+  // Install the shipped caper agent skill and upsert pointers into AGENTS.md/CLAUDE.md.
+  // This is best-effort: scaffolding must not fail because the agent init step failed.
+  try {
+    await agentInit(cwd);
+  } catch (e) {
+    console.warn('Warning: failed to install the caper agent skill:', e.message);
+  }
+
   // find __APPLICATION_NAME__.ts and replace it with the application name, then delete ~Application.ts
   const app_file = `${cwd}/src/__APPLICATION_NAME__.ts`;
   const app_contents = fs.readFileSync(app_file, 'utf-8');

package/cli.mjs

@@ -5,6 +5,7 @@ import { bgRed, bold, green, red, white } from 'kleur/colors';
 import fs from 'node:fs';
 import process from 'node:process';
 import { add } from './cli/add.mjs';
+import { agent } from './cli/agent.mjs';
 import { generateCaptions } from './cli/audio/cc.mjs';
 import { compress } from './cli/audio/index.mjs';
 import { create } from './cli/create.mjs';
@@ -64,6 +65,9 @@ switch (args[0]) {
   case 'add':
     await add(args.slice(1));
     break;
+  case 'agent':
+    await agent(args.slice(1));
+    break;
   case 'create': {
     let packageManager = 'npm'; // Default to npm
     let projectPath = '.'; // Default to current directory

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)
 
 ---
 
@@ -1543,7 +1544,87 @@ 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.
+
+```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 +1685,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,103 @@
+---
+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
+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`): from Playwright or a browser
+  tool, `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
+  actions / context changes / state pushes). 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** on dev
+  server start. Never hand-edit. Missing or stale → delete them and have the
+  dev server run once. They are usually gitignored, so a fresh clone has no
+  typed ids until then.
+- 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/`.

package/lib/caper.mjs

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