@caperjs/solid 0.7.0

package/README.md

@@ -0,0 +1,191 @@
+# @caperjs/solid
+
+A declarative [SolidJS](https://www.solidjs.com/) view layer for Caper. Any
+`Container` subclass may declare its members by returning JSX from a `compose()`
+method; Solid's universal renderer mounts that tree into the container **once**,
+and signals do every update after that — fine-grained, no VDOM, no re-render.
+It is purely additive: imperative Caper (`this.add.*`, `added()`, `update()`)
+keeps working exactly as before.
+
+## Install
+
+```sh
+pnpm add @caperjs/solid solid-js
+```
+
+## tsconfig contract
+
+Three settings, and all three are required:
+
+```jsonc
+{
+  "compilerOptions": {
+    // Leave the JSX alone — vite-plugin-solid does the real compilation.
+    "jsx": "preserve",
+    // Names the *type* lookup root for JSX. Nothing called `CaperJSX.h` ever
+    // runs; it exists because a transitive `@types/react` shadows any global
+    // `JSX` namespace, and `jsxImportSource` only applies in `react-jsx` mode.
+    "jsxFactory": "CaperJSX.h",
+    // Ships that `CaperJSX` namespace: the intrinsic elements and their props.
+    "types": ["@caperjs/core/client", "@caperjs/solid/jsx"]
+  }
+}
+```
+
+`caper doctor` checks all three whenever the app depends on `@caperjs/solid`,
+and prints the exact keys that are missing. It walks the `extends` chain, so
+these three can live in a shared base config instead of the app's own file.
+
+## Compose
+
+```tsx
+import { ComposableContainer, type Composes } from '@caperjs/solid';
+import { createSignal } from 'solid-js';
+
+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];
+    return (
+      <container>
+        <graphics draw={BAR_BG} />
+        <graphics draw={BAR_FILL} scale={{ x: hp() / 100, y: 1 }} />
+        <text text={`${hp()} HP`} anchor={0.5} x={WIDTH / 2} y={HEIGHT / 2} />
+      </container>
+    );
+  }
+}
+```
+
+`compose()` runs the first time the container hits the stage, and the Solid root
+is disposed in `destroy()`. Re-adding does not remount. The rule of thumb:
+**`compose()` declares what exists, signals say when state changed, `update()`
+moves things every frame.**
+
+Intrinsic elements are `container`, `sprite`, `text`, `graphics` and
+`flexContainer`. For anything else, `asComponent(Ctor, defaults?)` lifts an
+existing display class into JSX — it constructs the instance once and applies
+props reactively:
+
+```tsx
+const Orbiter$ = asComponent(Orbiter);
+<Orbiter$ x={40} y={80} ref={(el: Orbiter) => (this.orbiter = el)} />;
+```
+
+`useTick(fn)` runs `fn` every frame for the lifetime of the owning component —
+`update()` for function components.
+
+## Animation
+
+`animated(source, opts?)` returns a **gliding** accessor: it reads like any other
+signal, but eases toward its source instead of snapping to it. The binding stays
+declarative — nothing in the view knows an animation is running.
+
+```tsx
+const width = animated(() => hp() / 100); // opts: { duration, ease }
+<graphics draw={BAR_FILL} scale={{ x: width(), y: 1 }} />;
+```
+
+`<AnimatedShow>` is `<Show>` that holds its children on stage until the exit
+animation finishes, so popups and panels can leave gracefully:
+
+```tsx
+<AnimatedShow when={open} exit={{ pixi: { alpha: 0, y: 20 }, duration: 0.3 }}>
+  <container>…</container>
+</AnimatedShow>
+```
+
+`enter` / `exit` are plain GSAP vars; target properties live in a `pixi: {...}`
+block, which is GSAP's PixiPlugin — caper's `GSAPPlugin` registers it at app
+bootstrap, so inside a running app there is nothing to wire up. Both APIs must be
+called inside a reactive owner (a component body or a `compose()`).
+
+One-shot effects (shake, pulse) stay imperative through a ref: every Caper
+container carries the `Animated` mixin already.
+
+## Authoring rules
+
+Six rules. The first is the mental model; the rest are the edges that bite.
+
+1. **Signals for event-rate state, `update()` for per-frame bulk motion.**
+   `text={purse()}` on a value that changes when the player does something is
+   free. Hundreds of per-frame bindings are fine too, but moving a crowd of
+   objects every frame still belongs in an imperative `update()` — or in
+   `useTick(fn)` + a `ref` when the code lives in a function component. Per-frame
+   signals are the seasoning, not the meal.
+
+2. **`draw` functions must be stable references.** Solid batches an element's
+   dynamic props into one `!==`-guarded effect, so an inline
+   `draw={dot(3, color)}` allocates a fresh closure on every change of *any* prop
+   in that batch and forces a full `clear()` + redraw. Hoist the factory result
+   to a module constant (or a `createMemo`) and pass the same function every
+   time.
+
+3. **Never imperatively remove or reparent a child JSX created.** Solid owns
+   those nodes and will try to move or dispose them later. Imperative work
+   alongside a composed tree is fine — `initialize()`, `this.add.*`, `update()`
+   all keep working, and `compose()` appends rather than taking over — it just
+   must not reach into the declarative half.
+
+4. **Each `compose()` is its own reactive root.** Signals cross roots fine, so
+   instance fields are the bridge between a class's imperative API and its view.
+   Solid **context** does not cross the class boundary — pass props or read an
+   instance field instead.
+
+5. **`text` elements default to `eventMode: 'none'`.** A hit-testable but
+   non-interactive label sitting over a button would otherwise swallow the tap.
+   Attaching an `on*` prop flips the element to `'static'` automatically, and an
+   explicit `eventMode` prop overrides the default.
+
+6. **One-shot effects stay imperative.** Shake, pulse and friends are a `ref`
+   away: a Caper container mounted from JSX still carries the `Animated` mixin,
+   so `bar.shake()` works unchanged. Reserve `animated()` / `<AnimatedShow>` for
+   motion that is a function of state.
+
+## Testing your components
+
+Vitest resolves `solid-js` to its **server** build by default, where signals set
+once and never update again. Force the reactive build in your app's
+`vitest.config.ts` (this package's own config does the same):
+
+```ts
+export default defineConfig({
+  // Externalized deps are resolved by node, so the conditions only take effect
+  // once solid is inlined — both halves are needed.
+  resolve: { conditions: ['development', 'browser'] },
+  test: { server: { deps: { inline: [/solid-js/] } } },
+});
+```
+
+## Build wiring
+
+One flag in the app's vite config:
+
+```ts
+import { caper } from '@caperjs/core/vite';
+
+export default defineConfig({
+  plugins: [caper({ solid: true })],
+});
+```
+
+The preset resolves `@caperjs/solid/vite` from the **app's** `node_modules`, so
+the app needs `@caperjs/solid` and `solid-js` installed; `vite-plugin-solid`
+comes with this package and never has to be installed by hand. Pass an object to
+narrow what gets compiled as JSX: `caper({ solid: { include: ['src/ui/**/*.tsx'] } })`
+(default `['**/*.tsx']`).
+
+Outside the preset — a bare vite config, or a vitest config that has to compile
+JSX — use the plugin directly:
+
+```ts
+import { caperSolid } from '@caperjs/solid/vite';
+
+export default defineConfig({ plugins: [caperSolid()] });
+```

package/jsx.d.ts

@@ -0,0 +1,39 @@
+/**
+ * JSX types for `@caperjs/solid`. Add "@caperjs/solid/jsx" to the "types" array
+ * of your tsconfig, alongside `"jsx": "preserve"` and
+ * `"jsxFactory": "CaperJSX.h"`.
+ *
+ * The namespace hangs off `CaperJSX` rather than the global `JSX` namespace
+ * because `@types/react` is routinely in an app's program (pulled in
+ * transitively) and its `declare global { namespace JSX }` shadows any global
+ * one we add. `jsxFactory` names the type-lookup root instead; under
+ * `jsx: "preserve"` it is *only* a type lookup — vite-plugin-solid still does
+ * the real compilation, so nothing named `CaperJSX.h` is ever called.
+ * (`jsxImportSource` would be the modern answer, but it only applies in
+ * `react-jsx` mode.)
+ *
+ * Element props are deliberately loose for v1; a later release types each
+ * intrinsic against its Pixi class.
+ */
+
+declare namespace CaperJSX {
+  function h(type: any, props?: any, ...children: any[]): any;
+
+  /** The v1 prop bag for every intrinsic element: anything the class accepts. */
+  type ElementProps = Record<string, any> & { children?: any };
+
+  namespace JSX {
+    interface IntrinsicElements {
+      container: ElementProps;
+      sprite: ElementProps;
+      text: ElementProps;
+      graphics: ElementProps;
+      flexContainer: ElementProps;
+    }
+    type Element = any;
+    type ElementType = any;
+    interface ElementChildrenAttribute {
+      children: {};
+    }
+  }
+}

package/lib/AnimatedShow.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Conditional UI with enter / exit animations.
+ *
+ * ```tsx
+ * <AnimatedShow when={open}>
+ *   <container>…</container>
+ * </AnimatedShow>
+ * ```
+ *
+ * Custom `enter` / `exit` are plain GSAP vars — put target properties in a
+ * `pixi: {...}` block (`{ pixi: { y: 20, alpha: 0 }, duration: 0.3 }`).
+ * There is no `fallback` — the whole point is that the node outlives the flag.
+ *
+ * Requires GSAP's PixiPlugin, which caper's `GSAPPlugin` registers during app
+ * bootstrap. This package deliberately does not register it itself; outside a
+ * booted `Application` (tests, standalone use) call
+ * `gsap.registerPlugin(PixiPlugin)` yourself first.
+ */
+export declare function AnimatedShow(props: {
+    when: boolean | (() => boolean);
+    children: any;
+    enter?: gsap.TweenVars;
+    exit?: gsap.TweenVars;
+}): any;
+//# sourceMappingURL=AnimatedShow.d.ts.map

package/lib/AnimatedShow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimatedShow.d.ts","sourceRoot":"","sources":["../src/AnimatedShow.tsx"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAClC,IAAI,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IAChC,QAAQ,EAAE,GAAG,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC;IACvB,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC;CACvB,OAiDA"}

package/lib/AnimatedShow.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AnimatedShow.test.d.ts.map

package/lib/AnimatedShow.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimatedShow.test.d.ts","sourceRoot":"","sources":["../src/AnimatedShow.test.tsx"],"names":[],"mappings":""}

package/lib/Composable.d.ts

@@ -0,0 +1,39 @@
+import { Container, Constructor, Scene } from '@caperjs/core';
+/**
+ * What `compose()` hands back. `unknown` for now so this file stays JSX-free;
+ * it becomes the real element type when `jsx.d.ts` lands.
+ */
+export type Composed = unknown;
+/**
+ * The optional contract a `Composable` subclass opts into. Declared separately
+ * from the mixin (rather than merged onto it) so the mixin never claims a
+ * `compose` member of its own — the runtime just checks for one.
+ *
+ * @example
+ * ```tsx
+ * class HealthBar extends ComposableContainer implements Composes {
+ *   compose() {
+ *     return <text text="100 HP" />;
+ *   }
+ * }
+ * ```
+ */
+export interface Composes {
+    compose(): Composed;
+}
+/**
+ * Give a display class the `compose()` contract.
+ *
+ * The mixin adds no public members, so the returned constructor keeps `Base`'s
+ * own type — `compose()` is declared by the subclass via {@link Composes}.
+ *
+ * @param Base - The display class to make composable.
+ */
+export declare function Composable<TBase extends Constructor<any>>(Base: TBase): TBase;
+/** A caper {@link Container} that can declare its members with JSX. */
+export declare const ComposableContainer: typeof Container;
+export type ComposableContainer = InstanceType<typeof ComposableContainer>;
+/** A caper {@link Scene} that can declare its members with JSX. */
+export declare const ComposableScene: typeof Scene;
+export type ComposableScene = InstanceType<typeof ComposableScene>;
+//# sourceMappingURL=Composable.d.ts.map

package/lib/Composable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composable.d.ts","sourceRoot":"","sources":["../src/Composable.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,eAAe,CAAC;AAM9D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,QAAQ;IACvB,OAAO,IAAI,QAAQ,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,SAAS,WAAW,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,KAAK,GAAG,KAAK,CAiC7E;AAED,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,kBAAwB,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAE3E,mEAAmE;AACnE,eAAO,MAAM,eAAe,cAAoB,CAAC;AACjD,MAAM,MAAM,eAAe,GAAG,YAAY,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/lib/Composable.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Composable.test.d.ts.map

package/lib/Composable.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composable.test.d.ts","sourceRoot":"","sources":["../src/Composable.test.ts"],"names":[],"mappings":""}

package/lib/animated.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Follow `source` smoothly.
+ *
+ * Must be called inside a reactive owner (a component body or a `compose()`),
+ * because it registers an `onCleanup` to kill its animation.
+ *
+ * ```ts
+ * const barWidth = animated(() => hp() / 100);
+ * <graphics scale={{ x: barWidth(), y: 1 }} />
+ * ```
+ */
+export declare function animated(source: () => number, opts?: {
+    duration?: number;
+    ease?: string;
+}): () => number;
+//# sourceMappingURL=animated.d.ts.map

package/lib/animated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animated.d.ts","sourceRoot":"","sources":["../src/animated.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,MAAM,CAoBxG"}

package/lib/animated.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=animated.test.d.ts.map

package/lib/animated.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animated.test.d.ts","sourceRoot":"","sources":["../src/animated.test.ts"],"names":[],"mappings":""}

package/lib/asComponent.d.ts

@@ -0,0 +1,19 @@
+import { PixiNode } from './renderer';
+/**
+ * Lift an existing imperative display class into a JSX component.
+ *
+ * The instance is constructed once (untracked, so constructor reads don't
+ * subscribe to anything) and every prop is then applied through the renderer's
+ * own `spread`, which gives them the same reactivity as an intrinsic element —
+ * including `ref`.
+ *
+ * ```tsx
+ * const Orbiter$ = asComponent(Orbiter);
+ * <Orbiter$ x={40} y={80} />
+ * ```
+ *
+ * @param Ctor - The display class to lift. Called as `new Ctor(defaults)`.
+ * @param defaults - Config handed to the constructor on every mount.
+ */
+export declare function asComponent<TNode extends PixiNode, TConfig>(Ctor: new (config?: TConfig) => TNode, defaults?: TConfig): (props: Record<string, any>) => TNode;
+//# sourceMappingURL=asComponent.d.ts.map

package/lib/asComponent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asComponent.d.ts","sourceRoot":"","sources":["../src/asComponent.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAG3C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CAAC,KAAK,SAAS,QAAQ,EAAE,OAAO,EACzD,IAAI,EAAE,KAAK,MAAM,CAAC,EAAE,OAAO,KAAK,KAAK,EACrC,QAAQ,CAAC,EAAE,OAAO,GACjB,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,KAAK,CASvC"}

package/lib/asComponent.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=asComponent.test.d.ts.map

package/lib/asComponent.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asComponent.test.d.ts","sourceRoot":"","sources":["../src/asComponent.test.ts"],"names":[],"mappings":""}