@caperjs/core 0.6.1 → 0.7.0

package/build/index.d.mts

@@ -19,6 +19,12 @@ export interface CaperOptions {
     autoRegister?: boolean;
     update?: 'prompt' | 'auto' | 'manual';
   };
+  /**
+   * Compile `.tsx` with `@caperjs/solid`'s Solid JSX plugin, resolved from the
+   * app's own `node_modules`. Absent or `false` imports nothing. An object
+   * forwards `include` (default `['**\/*.tsx']`).
+   */
+  solid?: boolean | { include?: string[] };
 }
 
 /**

package/build/index.mjs

@@ -25,6 +25,7 @@ import { entityListPlugin, pluginListPlugin, popupListPlugin, sceneListPlugin, u
 import { pngFallbackPrunePlugin } from './plugins/pruneFallbacks.mjs';
 import { caperPwaPlugins } from './plugins/pwa.mjs';
 import { createCaperRuntimePlugin } from './plugins/runtime.mjs';
+import { caperSolidPlugin } from './plugins/solid.mjs';
 import { createCaperViewportPlugin } from './plugins/viewport.mjs';
 
 const buildFlags = readCaperBuildFlags();
@@ -96,6 +97,9 @@ function caperPluginList({ assets = {}, pwa } = {}) {
  *   DOM update banner; 'auto' reloads the page as soon as a new build lands;
  *   'manual' installs no UI at all and leaves it to the game, which listens to
  *   `app.onPwaUpdateAvailable`).
+ * @property {boolean|{include?: string[]}} [solid] Compile `.tsx` with
+ *   `@caperjs/solid`'s Solid JSX plugin. Absent or `false` imports nothing.
+ *   An object forwards `include` (default `['**\/*.tsx']`).
  */
 
 /**
@@ -108,6 +112,9 @@ export function caper(options = {}) {
       name: 'caper:defaults',
       config: (userConfig, env) => caperDefaults(userConfig, env),
     },
+    // Vite awaits promises in the plugins array, so the lazy import stays off
+    // `caper()`'s own signature — projects keep writing `plugins: [caper()]`.
+    ...(options.solid ? [caperSolidPlugin(options.solid)] : []),
     ...caperPluginList(options),
   ];
 }

package/build/plugins/solid.mjs

@@ -0,0 +1,30 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * `caper({ solid: true })` — pull `@caperjs/solid`'s Vite plugin into the preset.
+ *
+ * The dependency arrow only ever points from the app: core knows the specifier,
+ * never the package. Nothing is imported unless the app opts in.
+ *
+ * Resolution starts at the app root, not at this file. Under pnpm (and any other
+ * non-hoisted layout) `@caperjs/solid` is not a sibling of `@caperjs/core`, so a
+ * bare `import('@caperjs/solid/vite')` from here would fail even when the app has
+ * the package installed.
+ *
+ * @param {true|{ include?: string[] }} solid The preset's `solid` option.
+ * @param {string} [from] Directory to resolve from; the app root by default.
+ * @returns {Promise<import('vite').PluginOption>}
+ */
+export async function caperSolidPlugin(solid, from = process.cwd()) {
+  const req = createRequire(path.join(from, 'package.json'));
+  let entry;
+  try {
+    entry = req.resolve('@caperjs/solid/vite');
+  } catch {
+    throw new Error('[caper] solid: true requires @caperjs/solid to be installed (pnpm add @caperjs/solid solid-js)');
+  }
+  const { caperSolid } = await import(pathToFileURL(entry).href);
+  return caperSolid(typeof solid === 'object' ? solid : undefined);
+}

package/cli/doctor.mjs

@@ -2,6 +2,7 @@ import { dim, green, red, yellow } from 'kleur/colors';
 
 import { execFile } from 'node:child_process';
 import fs from 'node:fs';
+import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -61,10 +62,110 @@ const npmLatestVersion = (pkg, timeoutMs = 5000) =>
     });
   });
 
+const readJson = (file) => {
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+};
+
+/** tsconfig.json is JSON with comments and trailing commas often enough to matter. */
+const readJsonc = (file) => {
+  if (!fs.existsSync(file)) return null;
+  try {
+    const raw = fs
+      .readFileSync(file, 'utf-8')
+      .replace(/\/\*[\s\S]*?\*\//g, '')
+      .replace(/(^|[^:"'\\])\/\/.*$/gm, '$1')
+      .replace(/,(\s*[}\]])/g, '$1');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+
 const push = (checks, id, status, label, hint) => {
   checks.push({ id, status, label, ...(hint ? { hint } : {}) });
 };
 
+/**
+ * Resolve a tsconfig `extends` entry to an absolute config file path,
+ * TypeScript-style: relative specs resolve against the extending config's
+ * directory, everything else resolves node-module-style (bare package name,
+ * `+ .json`, `+ /tsconfig.json`) rooted at that same config file so an app's
+ * own node_modules is used. Returns null (never throws) when nothing resolves.
+ */
+const resolveExtendsSpec = (spec, fromConfigFile) => {
+  const fromDir = path.dirname(fromConfigFile);
+  const isRelative = spec.startsWith('./') || spec.startsWith('../') || path.isAbsolute(spec);
+
+  if (isRelative) {
+    const base = path.isAbsolute(spec) ? spec : path.resolve(fromDir, spec);
+    if (fs.existsSync(base) && fs.statSync(base).isFile()) return base;
+    const withJson = base.endsWith('.json') ? base : `${base}.json`;
+    return fs.existsSync(withJson) ? withJson : null;
+  }
+
+  const require = createRequire(fromConfigFile);
+  const candidates = [spec, `${spec}.json`, `${spec}/tsconfig.json`];
+  for (const candidate of candidates) {
+    try {
+      return require.resolve(candidate);
+    } catch {
+      // try the next candidate
+    }
+  }
+  // Some bare specs are effectively relative paths, or node-module resolution
+  // fails for other plausible reasons — fall back to filesystem paths relative
+  // to the extending config's directory before giving up.
+  for (const candidate of candidates) {
+    const asPath = path.resolve(fromDir, candidate);
+    if (fs.existsSync(asPath) && fs.statSync(asPath).isFile()) return asPath;
+  }
+  return null;
+};
+
+/**
+ * Effective `compilerOptions` for a tsconfig, walking `extends` (string or
+ * array, TS 5 style) like `tsc` does: the own config's fields override
+ * wholesale, later array entries beat earlier ones, and each base can itself
+ * extend further (recursion). Cycle-guarded per ancestor chain and depth
+ * capped; unreadable/unresolvable bases are silently skipped so doctor never
+ * crashes on a weird config.
+ */
+const resolveEffectiveCompilerOptions = (configFile, ancestors = new Set(), depth = 0) => {
+  if (depth > 10) return {};
+
+  let real;
+  try {
+    real = fs.realpathSync(configFile);
+  } catch {
+    real = configFile;
+  }
+  if (ancestors.has(real)) return {};
+
+  const config = readJsonc(configFile);
+  if (!config) return {};
+
+  const nextAncestors = new Set(ancestors);
+  nextAncestors.add(real);
+
+  let inherited = {};
+  if (config.extends) {
+    const specs = Array.isArray(config.extends) ? config.extends : [config.extends];
+    for (const spec of specs) {
+      const resolved = resolveExtendsSpec(spec, configFile);
+      if (!resolved) continue;
+      const baseOptions = resolveEffectiveCompilerOptions(resolved, nextAncestors, depth + 1);
+      inherited = { ...inherited, ...baseOptions };
+    }
+  }
+
+  return { ...inherited, ...(config.compilerOptions ?? {}) };
+};
+
 export async function runChecks(cwd, { online = true } = {}) {
   const checks = [];
   const installedVersion = readInstalledVersion();
@@ -169,6 +270,33 @@ export async function runChecks(cwd, { online = true } = {}) {
   });
   push(checks, 'peers', peerStatus, `peer deps: ${peerResults.join(', ')}`, peerStatus !== 'ok' ? 'pnpm install' : undefined);
 
+  // Solid JSX only typechecks with three tsconfig settings, and none of them can
+  // be defaulted from caper's base config: `jsxFactory` is a type-lookup root
+  // that exists because a transitive @types/react would otherwise shadow the
+  // global JSX namespace. Apps without @caperjs/solid never see this check.
+  const appPkg = readJson(path.join(cwd, 'package.json'));
+  const appDeps = { ...appPkg?.dependencies, ...appPkg?.devDependencies };
+  if (appDeps['@caperjs/solid']) {
+    const tsconfigPath = path.join(cwd, 'tsconfig.json');
+    const tsconfig = readJsonc(tsconfigPath);
+    if (!tsconfig) {
+      push(checks, 'solid-tsconfig', 'fail', 'solid tsconfig unreadable', 'tsconfig.json is missing or not parseable');
+    } else {
+      const compilerOptions = resolveEffectiveCompilerOptions(tsconfigPath);
+      const missing = [];
+      if (compilerOptions.jsx !== 'preserve') missing.push('"jsx": "preserve"');
+      if (compilerOptions.jsxFactory !== 'CaperJSX.h') missing.push('"jsxFactory": "CaperJSX.h"');
+      if (!compilerOptions.types?.includes('@caperjs/solid/jsx')) missing.push('"@caperjs/solid/jsx" in types');
+      push(
+        checks,
+        'solid-tsconfig',
+        missing.length ? 'fail' : 'ok',
+        missing.length ? 'solid tsconfig incomplete' : 'solid tsconfig',
+        missing.length ? `add ${missing.join(', ')} to tsconfig.json compilerOptions` : undefined,
+      );
+    }
+  }
+
   const caches = ['.assetpack', '.cache', 'dist'].filter((name) => fs.existsSync(path.join(cwd, name)));
   push(checks, 'caches', 'ok', `caches${caches.length ? `: ${caches.join(', ')}` : ' clean'}`, caches.length ? 'rm -rf them on weird asset/name mismatches' : undefined);
 

package/cli/doctor.test.mjs

@@ -99,6 +99,160 @@ ${END_MARKER}`;
     expect(find(checks, 'agent').status).toBe('ok');
   });
 
+  it('skips the solid tsconfig check when the app does not use @caperjs/solid', async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/core': '^1' } }), 'utf-8');
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'solid-tsconfig')).toBeUndefined();
+  });
+
+  it('names every tsconfig setting a solid app is missing', async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(path.join(cwd, 'tsconfig.json'), '{\n  // solid needs more than this\n  "compilerOptions": { "jsx": "preserve" }\n}\n', 'utf-8');
+
+    const checks = await runChecks(cwd, { online: false });
+    const solid = find(checks, 'solid-tsconfig');
+
+    expect(solid.status).toBe('fail');
+    expect(solid.hint).toContain('"jsxFactory": "CaperJSX.h"');
+    expect(solid.hint).toContain('"@caperjs/solid/jsx" in types');
+    expect(solid.hint).not.toContain('"jsx": "preserve"');
+  });
+
+  it('passes a solid app whose tsconfig has all three settings', async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ devDependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(
+      path.join(cwd, 'tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: { jsx: 'preserve', jsxFactory: 'CaperJSX.h', types: ['@caperjs/core/client', '@caperjs/solid/jsx'] },
+      }),
+      'utf-8',
+    );
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'solid-tsconfig').status).toBe('ok');
+  });
+
+  it('resolves solid tsconfig settings inherited through a relative extends', async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(
+      path.join(cwd, 'base.tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: { jsx: 'preserve', jsxFactory: 'CaperJSX.h', types: ['@caperjs/core/client', '@caperjs/solid/jsx'] },
+      }),
+      'utf-8',
+    );
+    fs.writeFileSync(path.join(cwd, 'tsconfig.json'), JSON.stringify({ extends: './base.tsconfig.json' }), 'utf-8');
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'solid-tsconfig').status).toBe('ok');
+  });
+
+  it("lets the app's own tsconfig override a bad base setting", async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(
+      path.join(cwd, 'base.tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: { jsx: 'preserve', jsxFactory: 'Wrong.h', types: ['@caperjs/core/client', '@caperjs/solid/jsx'] },
+      }),
+      'utf-8',
+    );
+    fs.writeFileSync(
+      path.join(cwd, 'tsconfig.json'),
+      JSON.stringify({ extends: './base.tsconfig.json', compilerOptions: { jsxFactory: 'CaperJSX.h' } }),
+      'utf-8',
+    );
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'solid-tsconfig').status).toBe('ok');
+  });
+
+  it("fails when the app's own tsconfig overrides a good base setting with a bad one", async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(
+      path.join(cwd, 'base.tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: { jsx: 'preserve', jsxFactory: 'CaperJSX.h', types: ['@caperjs/core/client', '@caperjs/solid/jsx'] },
+      }),
+      'utf-8',
+    );
+    fs.writeFileSync(
+      path.join(cwd, 'tsconfig.json'),
+      JSON.stringify({ extends: './base.tsconfig.json', compilerOptions: { jsxFactory: 'Wrong.h' } }),
+      'utf-8',
+    );
+
+    const checks = await runChecks(cwd, { online: false });
+    const solid = find(checks, 'solid-tsconfig');
+
+    expect(solid.status).toBe('fail');
+    expect(solid.hint).toContain('"jsxFactory": "CaperJSX.h"');
+  });
+
+  it('resolves solid tsconfig settings from a later entry in an extends array', async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(path.join(cwd, 'first.tsconfig.json'), JSON.stringify({ compilerOptions: { strict: true } }), 'utf-8');
+    fs.writeFileSync(
+      path.join(cwd, 'second.tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: { jsx: 'preserve', jsxFactory: 'CaperJSX.h', types: ['@caperjs/core/client', '@caperjs/solid/jsx'] },
+      }),
+      'utf-8',
+    );
+    fs.writeFileSync(path.join(cwd, 'tsconfig.json'), JSON.stringify({ extends: ['./first.tsconfig.json', './second.tsconfig.json'] }), 'utf-8');
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'solid-tsconfig').status).toBe('ok');
+  });
+
+  it('resolves solid tsconfig settings through a chained extends', async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(
+      path.join(cwd, 'grandparent.tsconfig.json'),
+      JSON.stringify({
+        compilerOptions: { jsx: 'preserve', jsxFactory: 'CaperJSX.h', types: ['@caperjs/core/client', '@caperjs/solid/jsx'] },
+      }),
+      'utf-8',
+    );
+    fs.writeFileSync(path.join(cwd, 'parent.tsconfig.json'), JSON.stringify({ extends: './grandparent.tsconfig.json' }), 'utf-8');
+    fs.writeFileSync(path.join(cwd, 'tsconfig.json'), JSON.stringify({ extends: './parent.tsconfig.json' }), 'utf-8');
+
+    const checks = await runChecks(cwd, { online: false });
+
+    expect(find(checks, 'solid-tsconfig').status).toBe('ok');
+  });
+
+  it('does not throw on a broken extends path and falls back to the own tsconfig', async () => {
+    const cwd = makeTempDir();
+    fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ dependencies: { '@caperjs/solid': '^1' } }), 'utf-8');
+    fs.writeFileSync(
+      path.join(cwd, 'tsconfig.json'),
+      JSON.stringify({ extends: './does-not-exist.json', compilerOptions: { jsx: 'preserve' } }),
+      'utf-8',
+    );
+
+    const checks = await runChecks(cwd, { online: false });
+    const solid = find(checks, 'solid-tsconfig');
+
+    expect(solid.status).toBe('fail');
+    expect(solid.hint).toContain('"jsxFactory": "CaperJSX.h"');
+    expect(solid.hint).toContain('"@caperjs/solid/jsx" in types');
+    expect(solid.hint).not.toContain('"jsx": "preserve"');
+  });
+
   it('reports a linked package missing its build', async () => {
     const cwd = makeTempDir();
     const checkout = path.join(cwd, 'checkout');

package/extras/llms.txt

@@ -40,7 +40,8 @@ produce working code.
 15. [Common recipes](#15-common-recipes)
 16. [Gotchas & verification loop](#16-gotchas--verification-loop)
 17. [Automation bridge — drive the running app](#17-automation-bridge--drive-the-running-app)
-18. [API reference index](#18-api-reference-index)
+18. [Declarative layer — `@caperjs/solid`](#18-declarative-layer--caperjssolid)
+19. [API reference index](#19-api-reference-index)
 
 ---
 
@@ -464,6 +465,12 @@ Every allowed key in `caper.config.ts`. Defer shape details to
 
 Plus all standard PixiJS `ApplicationOptions` (`antialias`, `width`, `height`, etc.).
 
+Screen viewport debugging is available through the built-in `screenDebug` overlay.
+Open the game URL in a normal browser tab with `?caper-screen-debug=1` to enable it.
+Then relaunch the installed PWA; the same-origin setting persists without an address bar.
+Use `?caper-screen-debug=0` in a browser tab to disable it.
+A screenshot containing the overlay and marker lines is the diagnostic artifact.
+
 **Scene/plugin/popup/entity registrations are NOT in this table** — they're
 discovered from disk. Plugins list above is the one exception.
 
@@ -1213,6 +1220,9 @@ Each is a separate npm package. Install → list in `plugins: [...]` → use via
 Install via pnpm/npm, then register in `caper.config.ts plugins: [...]`.
 Deep API lives in each plugin's own README on npm.
 
+`@caperjs/solid` is first-party too but is **not** a plugin — it is the optional
+declarative view layer and never appears in `plugins: [...]`. See §18.
+
 Canonical registration shape:
 
 ```ts
@@ -1638,7 +1648,180 @@ Rules of thumb:
 
 ---
 
-## 18. API reference index
+## 18. Declarative layer — `@caperjs/solid`
+
+**Optional and purely additive.** `@caperjs/solid` is a separate package (npm
+`@caperjs/solid`, source `packages/plugin-solid/`) that lets a display object
+declare its members with SolidJS JSX instead of building them by hand. It is
+**not** an `IPlugin` — nothing goes in `plugins: [...]`, there is no `app.solid`.
+Core stays Solid-free; imperative Caper (§6) is unchanged and always available.
+
+Reach for it when a screen is **UI-shaped**: state→view plumbing, lists that
+insert/remove, panels that show and hide. Keep gameplay (`update()` loops,
+physics, entity simulation) imperative — this layer does nothing for it.
+
+### 18.1 The `compose()` contract
+
+A `Container` (or `Scene`) subclass extends `ComposableContainer` /
+`ComposableScene` and returns JSX from `compose()`:
+
+- **Mount once.** The tree mounts the first time the object hits the stage,
+  driven by Pixi's native `'added'` event — so a subclass that overrides
+  `added()` without calling `super.added()` cannot break it.
+- **Dispose on `destroy()`.** The Solid root is torn down there; re-adding the
+  object does **not** remount.
+- **Signals do every update after that.** Fine-grained, no VDOM, no re-render,
+  no diff.
+
+> `compose()` declares what exists, signals say when state changed, `update()`
+> moves things every frame.
+
+### 18.2 Install + build wiring
+
+```sh
+pnpm add @caperjs/solid solid-js
+```
+
+```ts
+// vite.config.ts
+import { caper } from '@caperjs/core/vite';
+
+export default defineConfig({ plugins: [caper({ solid: true })] });
+```
+
+`solid: true` makes the preset resolve `@caperjs/solid/vite` from the **app's**
+`node_modules` and add its Solid JSX plugin (universal renderer, `moduleName:
+'@caperjs/solid'`, `hot: false`). `vite-plugin-solid` ships as a dependency of
+`@caperjs/solid` — never install it directly. `{ solid: { include: [...] } }`
+narrows which files compile as JSX (default `['**/*.tsx']`). For a bare vite or
+vitest config, import `caperSolid()` from `@caperjs/solid/vite` instead.
+
+### 18.3 tsconfig contract (all three required)
+
+```jsonc
+{
+  "compilerOptions": {
+    "jsx": "preserve",              // vite-plugin-solid does the real compile
+    "jsxFactory": "CaperJSX.h",     // type-lookup root only; nothing calls it
+    "types": ["@caperjs/core/client", "@caperjs/solid/jsx"]
+  }
+}
+```
+
+`jsxFactory` exists because a transitive `@types/react` shadows the global `JSX`
+namespace and `jsxImportSource` only applies in `react-jsx` mode. `caper doctor`
+reports a `solid-tsconfig` check with the exact missing keys whenever the app
+depends on `@caperjs/solid`; it walks the `extends` chain, so the three keys can
+live in a shared base config.
+
+### 18.4 Minimal example
+
+```tsx
+import { animated, ComposableContainer, type Composes } from '@caperjs/solid';
+import type { Graphics } from 'pixi.js';
+import { createSignal } from 'solid-js';
+
+const WIDTH = 220;
+const HEIGHT = 22;
+
+// Module-level so the reference is stable — see rule 2 in §18.6.
+const bg = (g: Graphics) => g.roundRect(0, 0, WIDTH, HEIGHT, 4).fill({ color: 0x22252a });
+const fill = (g: Graphics) => g.roundRect(0, 0, WIDTH, HEIGHT, 4).fill({ color: 0x9aa96b });
+
+export class HealthBar extends ComposableContainer implements Composes {
+  private health = createSignal(100);
+
+  /** Imperative API — an ordinary method that happens to write a signal. */
+  public damage(amount: number) {
+    this.health[1]((hp) => Math.max(0, hp - amount));
+  }
+
+  public compose() {
+    const hp = this.health[0];
+    const hpA = animated(() => hp() / 100); // glides instead of snapping
+
+    return (
+      <container>
+        <graphics draw={bg} />
+        <graphics draw={fill} scale={{ x: hpA(), y: 1 }} />
+        <text text={`${hp()} HP`} anchor={{ x: 0.5, y: 0.5 }} x={WIDTH / 2} y={HEIGHT / 2} />
+      </container>
+    );
+  }
+}
+```
+
+### 18.5 Surface
+
+| Name | One-line |
+| --- | --- |
+| `Composable(Base)` | Mixin adding the `compose()` contract to any display class. |
+| `ComposableContainer` / `ComposableScene` | Prebuilt `Composable(Container)` / `Composable(Scene)`. |
+| `Composes` | The interface a subclass `implements` to declare `compose()`. |
+| `asComponent(Ctor, defaults?)` | Lift an existing display class into JSX; constructs once, applies props reactively (incl. `ref`). |
+| `useTick(fn)` | `app.ticker.add` + `onCleanup` — `update()` for function components. |
+| `animated(source, opts?)` | Gliding accessor: reads like a signal, eases toward its source. `opts: { duration, ease }`. |
+| `<AnimatedShow when enter exit>` | `<Show>` that holds children on stage until the exit animation ends. |
+
+Intrinsic elements: `container`, `sprite`, `text`, `graphics`, `flexContainer`.
+Anything else goes through `asComponent`. Props use the same resolvers as
+`this.add.*`, so `scale={2}`, `scale={{ x, y }}` and `scale={[x, y]}` all behave
+as in factory config; `on*` props attach Pixi listeners and flip `eventMode` to
+`'static'`; `draw` is `<graphics>`-only.
+
+`enter` / `exit` on `<AnimatedShow>` are plain GSAP vars with target properties
+in a `pixi: {...}` block (GSAP's PixiPlugin, which core's `GSAPPlugin` registers
+at bootstrap). `animated()` and `<AnimatedShow>` must be called inside a
+reactive owner — a component body or a `compose()`.
+
+### 18.6 Authoring rules
+
+1. **Signals for event-rate state; `update()` / `useTick` + refs for per-frame
+   bulk motion.** Hundreds of per-frame bindings are fine; moving a crowd every
+   frame still belongs in an imperative loop.
+2. **`draw` functions must be stable references.** Solid batches an element's
+   dynamic props into one `!==`-guarded effect, so an inline `draw={dot(3)}`
+   allocates a new closure whenever any prop in that batch changes and forces a
+   full `clear()` + redraw. Hoist it.
+3. **Never imperatively remove or reparent a child JSX created.** Solid owns
+   those nodes. Building extra things alongside the composed tree is fine.
+4. **Each `compose()` is its own reactive root.** Signals cross roots; Solid
+   *context* does not cross the class boundary — pass props or instance fields.
+5. **`text` elements default to `eventMode: 'none'`** so a label cannot swallow
+   a sibling button's tap. An `on*` prop or an explicit `eventMode` overrides it.
+6. **One-shot effects stay imperative via refs** — a JSX-mounted Caper container
+   still carries the `Animated` mixin, so `bar.shake()` works (§12.3).
+
+### 18.7 Scene constraint — keep `src/scenes/` JSX-free
+
+Discovery parses `src/scenes/**` with `jsx: false`. **Scene files must contain
+no JSX.** Put the view in a sibling directory and have `compose()` return a
+plain function call:
+
+```ts
+// src/scenes/HudScene.ts — plain .ts, no JSX
+import { SceneView } from '@/solid-demo/View';
+import { defineScene } from '@caperjs/core';
+import { ComposableScene, type Composes } from '@caperjs/solid';
+
+export const scene = defineScene({ id: 'hud' });
+
+export default class HudScene extends ComposableScene implements Composes {
+  public compose() {
+    return SceneView(this); // the JSX lives on the other side of this call
+  }
+}
+```
+
+Canonical working example in the caper repo:
+`apps/kitchen-sink/src/scenes/SolidJsxScene.ts` (the JSX-free scene) plus
+`apps/kitchen-sink/src/solid-demo/View.tsx`, `HealthBar.tsx` (nested
+`compose()`) and `Orbiter.ts` (an imperative `update()` class mounted via
+`asComponent`). Deeper API notes live in the package's own README.
+
+---
+
+## 19. API reference index
 
 Flat jump table. Name → section → one-line.
 
@@ -1646,8 +1829,12 @@ Flat jump table. Name → section → one-line.
 | --- | --- | --- |
 | `Application` | §3.4 | Base app class; subclass for typed plugin getters. |
 | `AnimatedSprite` | §6.1, §10 | Pixi AnimatedSprite wrapper (`animations`, `animation`, `autoPlay`). |
+| `animated(source, opts?)` | §18.5 | `@caperjs/solid` — gliding accessor; eases toward its source. |
+| `<AnimatedShow>` | §18.5 | `@caperjs/solid` — `<Show>` that holds children until the exit ends. |
+| `asComponent(Ctor, defaults?)` | §18.5 | `@caperjs/solid` — lift a display class into JSX. |
 | `Button` | §7.2 | Four-state interactive button with sounds + actions. |
 | `Camera` | §10 | Camera controller for scene-level follow/constrain. |
+| `Composable(Base)` / `ComposableContainer` / `ComposableScene` | §18.1 | `@caperjs/solid` — the `compose()` contract. |
 | `Container` | §6, §10 | Caper base container (Animated + WithSignals + Factory). |
 | `create(config, el?, speak?)` | §3.3 | Programmatic app bootstrap. |
 | `defineActions(contexts, map)` | §4.3 | Typed action registry. |
@@ -1675,6 +1862,7 @@ Flat jump table. Name → section → one-line.
 | `Store` | §12.2 | Unified storage-adapter facade. |
 | `Toast` / `Toaster` | §7.4 | Toast notifications. |
 | `UICanvas` | §7.5 | HUD root layer. |
+| `useTick(fn)` | §18.5 | `@caperjs/solid` — per-frame callback inside a Solid component. |
 | `app.actions(id)` | §8 | Returns the action's signal. |
 | `app.assets.loadBundles(ids)` | §8, §11.5 | Load named bundles. |
 | `app.assets.loadSceneAssets(scene)` | §8 | Load a scene's declared bundles. |
@@ -1693,11 +1881,11 @@ Flat jump table. Name → section → one-line.
 | `app.store.save(adapter, key, data)` | §12.2 | Persist via storage adapter. |
 | `app.store.load(adapter, key)` | §12.2 | Read via storage adapter. |
 | `app.timers.delay(ms)` | §8 | Scene-scoped timer. |
-| `Animated.animate(props)` | §12.3 | GSAP tween. |
+| `Animated.animate(props)` | §12.3 | GSAP animation. |
 | `Animated.shake()` / `.pulse()` / `.bob()` | §12.3 | Preset animations. |
 | `this.add.*` / `this.make.*` | §6 | Factory methods on any Container subclass. |
 
 ---
 
-**Last updated:** with `@caperjs/core@0.5.x` (PixiJS 8.x); version in `../package.json`. When in doubt, read the
+**Last updated:** with `@caperjs/core@0.6.x` (PixiJS 8.x); version in `../package.json`. When in doubt, read the
 cited framework source file — signatures and defaults are authoritative there.