castle-web-cli 0.4.1 → 0.4.2

package/dist/serve.js

@@ -1,8 +1,11 @@
 import * as fs from 'fs';
 import * as net from 'net';
 import * as path from 'path';
+import { spawn } from 'child_process';
 import { createServer } from 'vite';
 import { WebSocketServer, WebSocket } from 'ws';
+import { createIdeServer, DECK_FOCUS_SCRIPT } from './ide.js';
+import * as config from './config.js';
 function isPortFree(port) {
     return new Promise((resolve) => {
         const srv = net.createServer();
@@ -18,21 +21,59 @@ async function findFreePorts(startPort) {
     }
     throw new Error(`No free port pair found starting from ${startPort}`);
 }
-function castlePlugin(wsPort) {
+function castlePlugin(wsPort, ideServer) {
     return {
         name: 'castle-dev',
+        transformIndexHtml: {
+            order: 'pre',
+            handler(html) {
+                return html.replace(/<head(\s[^>]*)?>/i, (match) => `${match}\n    <script>window.CastleEmbed={edit:true};</script>\n    ${DECK_FOCUS_SCRIPT}`);
+            },
+        },
         configureServer(server) {
             server.middlewares.use((req, res, next) => {
                 if (req.url === '/__castle/ws-port') {
                     res.writeHead(200, { 'Content-Type': 'application/json' });
-                    res.end(JSON.stringify({ port: wsPort }));
+                    res.end(JSON.stringify({ port: wsPort, path: '/__castle/ws' }));
                     return;
                 }
+                if (req.url === '/__castle/auth') {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ token: config.getToken(), userId: config.getUserId() }));
+                    return;
+                }
+                if (req.url === '/__castle/context') {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(readDeckContext(server.config.root)));
+                    return;
+                }
+                // The split-view shell (`/`) + its static assets are served outside
+                // Vite's module pipeline; the deck itself loads in the iframe via
+                // `/index.html`, which Vite still serves normally.
+                if (req.url) {
+                    const reqPath = req.url.split('?')[0];
+                    if (ideServer.handleHttpRequest(req, res, reqPath))
+                        return;
+                }
                 next();
             });
         },
     };
 }
+function readDeckContext(projectDir) {
+    try {
+        const raw = fs.readFileSync(path.join(projectDir, 'castle.json'), 'utf8');
+        const data = JSON.parse(raw);
+        const deckId = typeof data.deckId === 'string' ? data.deckId : undefined;
+        const cardId = typeof data.cardId === 'string' ? data.cardId : undefined;
+        return { deckId, cardId };
+    }
+    catch {
+        return {};
+    }
+}
+const DEFAULT_PORT = 5757;
+const SCREENSHOT_REQUEST_TTL_MS = 15_000;
 export async function serve(dir, options = {}) {
     const projectDir = path.resolve(dir);
     if (!fs.existsSync(projectDir)) {
@@ -43,7 +84,21 @@ export async function serve(dir, options = {}) {
         console.error(`No index.html found in ${projectDir}`);
         process.exit(1);
     }
-    const startPort = parseInt(options.port ?? '3737', 10);
+    if (options.detach) {
+        await serveDetached(projectDir, options);
+        return;
+    }
+    // Close stdin when not attached to a TTY so the process can be cleanly
+    // backgrounded with `&` (otherwise stdin reads can block or hold the parent).
+    if (!process.stdin.isTTY) {
+        try {
+            process.stdin.destroy();
+        }
+        catch {
+            // already destroyed / inaccessible
+        }
+    }
+    const startPort = parseInt(options.port ?? String(DEFAULT_PORT), 10);
     const { port, wsPort } = options.port
         ? { port: startPort, wsPort: startPort + 1 }
         : await findFreePorts(startPort);
@@ -54,38 +109,173 @@ export async function serve(dir, options = {}) {
     const logFile = path.join(castleDir, 'logs.txt');
     const screenshotsDir = path.join(castleDir, 'screenshots');
     const serveJsonPath = path.join(castleDir, 'serve.json');
-    fs.writeFileSync(serveJsonPath, JSON.stringify({ port, wsPort }) + '\n');
-    process.on('exit', () => { try {
-        fs.unlinkSync(serveJsonPath);
-    }
-    catch { } });
+    fs.writeFileSync(serveJsonPath, JSON.stringify({ port, wsPort, pid: process.pid }) + '\n');
+    process.on('exit', () => {
+        try {
+            fs.unlinkSync(serveJsonPath);
+        }
+        catch {
+            // already removed / never written
+        }
+    });
     process.on('SIGINT', () => process.exit());
     process.on('SIGTERM', () => process.exit());
-    startWSServer(wsPort, logFile, screenshotsDir);
+    // The WS server forwards `restart` to the browser, but it also needs the
+    // Vite instance so it can drop transform caches first (see invalidateModuleCaches).
+    const viteHolder = { vite: null };
+    startWSServer(wsPort, projectDir, logFile, screenshotsDir, viteHolder);
+    // The deck root `/` serves a split-view shell: the deck in an iframe plus a
+    // toggle button for an xterm.js terminal. The terminal's PTY is lazy -- it
+    // spawns only when a browser first opens the PTY WebSocket.
+    const ideServer = createIdeServer({
+        deckDir: projectDir,
+        deckLabel: path.basename(projectDir),
+    });
+    process.on('exit', () => ideServer.shutdown());
     const vite = await createServer({
         root: projectDir,
-        plugins: [castlePlugin(wsPort)],
+        plugins: [castlePlugin(wsPort, ideServer)],
         server: {
             port,
             strictPort: true,
+            host: options.host,
             open: options.open ? true : undefined,
             hmr: false,
+            proxy: {
+                '/__castle/ws': {
+                    target: `ws://localhost:${wsPort}`,
+                    ws: true,
+                },
+            },
             fs: { strict: false },
         },
         logLevel: 'info',
     });
+    viteHolder.vite = vite;
     await vite.listen();
+    // The PTY WebSocket upgrade is handled directly on Vite's HTTP server rather
+    // than through Vite's proxy (Vite's ws proxy didn't forward this path).
+    if (vite.httpServer) {
+        vite.httpServer.on('upgrade', (req, socket, head) => {
+            ideServer.handleUpgrade(req, socket, head);
+        });
+    }
     vite.printUrls();
 }
-function startWSServer(port, logFile, screenshotsDir) {
+// `restart` does a full browser reload, but Vite keeps transformed modules
+// cached in its module graph. Newly-added files picked up by `import.meta.glob`
+// (e.g. a new behavior in `behaviors/`) would otherwise be missed because the
+// cached glob importer is re-served as-is. Invalidating the graph forces every
+// module to re-transform on the next request, so the glob is rescanned.
+function invalidateModuleCaches(vite) {
+    if (!vite)
+        return;
+    try {
+        const clientGraph = vite.environments?.client?.moduleGraph;
+        if (clientGraph)
+            clientGraph.invalidateAll();
+        else
+            vite.moduleGraph.invalidateAll();
+    }
+    catch {
+        // Vite changed its graph shape between minor versions — best-effort
+    }
+}
+async function serveDetached(projectDir, options) {
+    const castleDir = path.join(projectDir, '.castle');
+    if (!fs.existsSync(castleDir))
+        fs.mkdirSync(castleDir, { recursive: true });
+    const serveJsonPath = path.join(castleDir, 'serve.json');
+    // Clear stale serve.json before spawning so we wait for the new one.
+    try {
+        fs.unlinkSync(serveJsonPath);
+    }
+    catch {
+        // no stale serve.json — fine
+    }
+    const logPath = path.join(castleDir, 'serve.log');
+    const logFd = fs.openSync(logPath, 'a');
+    // Re-exec this CLI with the same args minus --detach. process.argv[0] is
+    // node, process.argv[1] is the cli entry.
+    const entry = process.argv[1];
+    if (!entry)
+        throw new Error('cannot find cli entrypoint for detached serve');
+    const args = ['serve', projectDir];
+    if (options.port)
+        args.push('--port', options.port);
+    if (options.host)
+        args.push('--host', options.host);
+    if (options.open)
+        args.push('--open');
+    const child = spawn(process.execPath, [entry, ...args], {
+        cwd: projectDir,
+        detached: true,
+        stdio: ['ignore', logFd, logFd],
+        env: process.env,
+    });
+    child.unref();
+    fs.closeSync(logFd);
+    // Wait up to 15s for serve.json to appear so we can print the URL.
+    const deadline = Date.now() + 15_000;
+    while (Date.now() < deadline) {
+        if (fs.existsSync(serveJsonPath)) {
+            try {
+                const info = JSON.parse(fs.readFileSync(serveJsonPath, 'utf8'));
+                console.log(`Started serve in background: http://localhost:${info.port}`);
+                console.log(`PID: ${child.pid}`);
+                console.log(`Logs: ${logPath}`);
+                return;
+            }
+            catch {
+                // serve.json written but not yet fully flushed — try again
+            }
+        }
+        await new Promise((r) => setTimeout(r, 200));
+    }
+    throw new Error(`Detached serve did not write ${serveJsonPath} within 15s; check ${logPath} for startup errors.`);
+}
+function startWSServer(port, projectDir, logFile, screenshotsDir, viteHolder) {
     const wss = new WebSocketServer({ port });
     const clients = new Set();
+    // For round-trip requests (e.g. screenshot), remember which socket issued a
+    // given requestId so the matching response is routed back to just that
+    // client instead of broadcast to every tab/CLI. Mirrors how `write_file`
+    // replies only to its sender.
+    const requestOrigins = new Map();
+    const forgetRequest = (requestId) => {
+        const pending = requestOrigins.get(requestId);
+        if (pending)
+            clearTimeout(pending.timeout);
+        requestOrigins.delete(requestId);
+    };
     wss.on('connection', (ws) => {
         clients.add(ws);
         ws.on('message', (raw) => {
             try {
-                const msg = JSON.parse(raw.toString());
-                if (msg.type === 'restart' || msg.type === 'screenshot_request') {
+                const text = Array.isArray(raw)
+                    ? Buffer.concat(raw).toString('utf8')
+                    : Buffer.isBuffer(raw)
+                        ? raw.toString('utf8')
+                        : Buffer.from(raw).toString('utf8');
+                const msg = JSON.parse(text);
+                if (msg.type === 'restart') {
+                    // Fire-and-forget: reload every open tab.
+                    invalidateModuleCaches(viteHolder.vite);
+                    const fwd = JSON.stringify(msg);
+                    for (const c of clients) {
+                        if (c !== ws && c.readyState === WebSocket.OPEN)
+                            c.send(fwd);
+                    }
+                }
+                if (msg.type === 'screenshot_request') {
+                    // Record the requester, then forward to the other clients (the tab).
+                    if (typeof msg.requestId === 'string') {
+                        forgetRequest(msg.requestId);
+                        const timeout = setTimeout(() => {
+                            requestOrigins.delete(msg.requestId);
+                        }, SCREENSHOT_REQUEST_TTL_MS);
+                        requestOrigins.set(msg.requestId, { origin: ws, timeout });
+                    }
                     const fwd = JSON.stringify(msg);
                     for (const c of clients) {
                         if (c !== ws && c.readyState === WebSocket.OPEN)
@@ -100,24 +290,97 @@ function startWSServer(port, logFile, screenshotsDir) {
                     else
                         process.stdout.write(line);
                 }
-                if (msg.type === 'screenshot_response') {
-                    if (!fs.existsSync(screenshotsDir))
-                        fs.mkdirSync(screenshotsDir, { recursive: true });
-                    const filename = `screenshot-${Date.now()}.png`;
-                    const filepath = path.join(screenshotsDir, filename);
-                    const base64 = msg.data.replace(/^data:image\/png;base64,/, '');
-                    fs.writeFileSync(filepath, Buffer.from(base64, 'base64'));
-                    console.log(`Screenshot saved: ${filepath}`);
-                    const fwd = JSON.stringify(msg);
-                    for (const c of clients) {
-                        if (c !== ws && c.readyState === WebSocket.OPEN)
-                            c.send(fwd);
+                if (msg.type === 'screenshot_response' &&
+                    (typeof msg.data === 'string' || msg.ok === false)) {
+                    const hasId = typeof msg.requestId === 'string';
+                    const pending = hasId ? requestOrigins.get(msg.requestId) : undefined;
+                    const origin = pending?.origin;
+                    // A response whose requestId is no longer tracked is a duplicate from
+                    // another tab for an already-served request -> drop it (otherwise we'd
+                    // write the file and reply twice).
+                    if (!hasId || origin) {
+                        if (hasId)
+                            forgetRequest(msg.requestId);
+                        if (typeof msg.data === 'string') {
+                            if (!fs.existsSync(screenshotsDir))
+                                fs.mkdirSync(screenshotsDir, { recursive: true });
+                            const filename = `screenshot-${Date.now()}.png`;
+                            const filepath = path.join(screenshotsDir, filename);
+                            const base64 = msg.data.replace(/^data:image\/png;base64,/, '');
+                            fs.writeFileSync(filepath, Buffer.from(base64, 'base64'));
+                            console.log(`Screenshot saved: ${filepath}`);
+                        }
+                        const fwd = JSON.stringify(msg);
+                        if (origin) {
+                            // Route back to just the requester.
+                            if (origin !== ws && origin.readyState === WebSocket.OPEN)
+                                origin.send(fwd);
+                        }
+                        else {
+                            // Legacy path (response without a requestId): broadcast as before.
+                            for (const c of clients) {
+                                if (c !== ws && c.readyState === WebSocket.OPEN)
+                                    c.send(fwd);
+                            }
+                        }
                     }
                 }
+                if (msg.type === 'write_file') {
+                    const response = writeProjectFile(projectDir, msg.path, msg.contents);
+                    ws.send(JSON.stringify({
+                        type: 'write_file_response',
+                        requestId: msg.requestId,
+                        ...response,
+                    }));
+                }
+            }
+            catch {
+                // ignore malformed frames
+            }
+        });
+        ws.on('close', () => {
+            clients.delete(ws);
+            // Drop any in-flight requests this socket issued so the map can't leak.
+            for (const [id, pending] of requestOrigins) {
+                if (pending.origin === ws)
+                    forgetRequest(id);
             }
-            catch { }
         });
-        ws.on('close', () => { clients.delete(ws); });
     });
     return wss;
 }
+function writeProjectFile(projectDir, requestedPath, contents) {
+    if (typeof requestedPath !== 'string' || requestedPath.trim() === '') {
+        return { ok: false, error: 'Missing file path.' };
+    }
+    if (typeof contents !== 'string') {
+        return { ok: false, error: 'File contents must be a string.' };
+    }
+    const normalized = path.normalize(requestedPath.replace(/\\/g, '/'));
+    if (normalized === '.') {
+        return { ok: false, error: 'Missing file path.' };
+    }
+    if (path.isAbsolute(normalized) ||
+        normalized === '..' ||
+        normalized.startsWith(`..${path.sep}`)) {
+        return { ok: false, error: `Refusing to write outside the deck: ${requestedPath}` };
+    }
+    const parts = normalized.split(path.sep);
+    if (parts.includes('.git') || parts.includes('.castle') || parts.includes('node_modules')) {
+        return { ok: false, error: `Refusing to write protected deck path: ${requestedPath}` };
+    }
+    const filepath = path.resolve(projectDir, normalized);
+    const relative = path.relative(projectDir, filepath);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+        return { ok: false, error: `Refusing to write outside the deck: ${requestedPath}` };
+    }
+    try {
+        fs.mkdirSync(path.dirname(filepath), { recursive: true });
+        fs.writeFileSync(filepath, contents, 'utf-8');
+        return { ok: true, path: normalized };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: `Could not write ${requestedPath}: ${message}` };
+    }
+}

package/kits/basic-2d/.prettierrc

@@ -0,0 +1,8 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "bracketSameLine": true,
+  "trailingComma": "es5",
+  "arrowParens": "always"
+}

package/kits/basic-2d/CLAUDE.md

@@ -0,0 +1,131 @@
+# basic-2d kit
+
+Actor / behavior / scene framework on a 500×700 canvas ("card"). To build a game you (a) write behaviors in `behaviors/*.jsx`, (b) place actors that use them in `scenes/*.scene` (plain JSON). Behaviors auto-register via file glob — drop a new file and it's picked up on next reload.
+
+This kit is plain JavaScript (no TypeScript). Use `.jsx` for files that contain JSX, `.js` otherwise. Don't add types or `.ts`/`.tsx` files.
+
+DO NOT READ `engine/`, `editors/`, OR the built-in `behaviors/` files (`Layout.jsx`, `Drawing.jsx`, `Collider.jsx`, `Camera.jsx`) to build a game. Those are the framework itself; their complete public API (props, helpers, calling conventions) is documented inline below. Read framework source only if you are explicitly modifying the framework.
+
+## Scope
+
+Write the smallest game that satisfies what the user asked for. No sound, particles, menus, multi-level progression, or visual polish unless they specifically asked for it. A typical behavior is 30–80 lines — if yours is hitting 200, you're over-engineering: cut feel-good extras, fewer fields on props, fewer edge cases, fewer comments. Ship the core loop first; the user can ask for more.
+
+## Workflow
+
+1. Edit `behaviors/*.jsx` and `scenes/main.scene`.
+2. `castle-web serve . --detach` (returns the URL, default port 5757). Curl once to confirm.
+3. After every edit: `npm run restart` (no hot reload). Then re-check.
+
+Card size is **500 wide × 700 tall** (origin top-left, +y is down).
+
+## Behavior shape
+
+A behavior is a class. Minimal contract:
+
+```jsx
+// behaviors/MyThing.jsx
+export class MyThing {
+  static behaviorName = 'MyThing'; // must match the key used in .scene
+  static defaultProps = { speed: 200 };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  // Called every frame in play mode. dt is seconds.
+  update(actor, scene, dt) {
+    const layout = actor.components.Layout;
+    layout.x += this.props.speed * dt; // mutate component in place
+  }
+
+  // Optional. Custom drawing (you usually don't need this; use a Drawing
+  // component instead). ctx is in card units already.
+  draw(actor, scene, ctx) {}
+
+  // Optional. Return React nodes for game-time HUD. Coordinates are card
+  // units. Read state your `update` set; do not start your own loops.
+  ui(actor, scene) {
+    return null;
+  }
+}
+```
+
+A fresh `Behavior` instance is constructed per actor per frame from the actor's component props — DO NOT store per-actor state on `this`. Persist transient state on `actor.runtime` (a free-form object the framework will not serialize) or on the component props themselves.
+
+## Scene file (`scenes/main.scene`, plain JSON)
+
+```json
+{
+  "background": "#1b2030",
+  "actors": [
+    {
+      "id": "paddle",
+      "components": {
+        "Layout": { "x": 210, "y": 640, "width": 80, "height": 12 },
+        "Drawing": { "file": "drawings/floor.drawing" },
+        "Collider": { "kind": "solid", "width": 80, "height": 12 },
+        "Paddle": { "speed": 360 }
+      }
+    }
+  ]
+}
+```
+
+Rules: every actor needs a unique `id` (any string) and almost always a `Layout`. `components` keys are behavior names (the `static behaviorName`). Unspecified props fall back to that behavior's `defaultProps` — omit optional fields (`z`, `rotation`, actor `name`, `tint: '#ffffffff'`, scene `name`) to keep scenes compact, especially when generating many actors. Add a behavior to an actor by adding its key to `components`; remove it by deleting the key.
+
+## Built-in behaviors
+
+- **Layout** — `{ x, y, width, height, z?, rotation? }`. Every actor needs one. `z` orders draw (low first). `rotation` is degrees about the center.
+- **Drawing** — `{ file: "drawings/foo.drawing", tint?: "#rrggbbaa" }`. Renders the pixel-art file scaled into the Layout box. `tint` multiplies; use white (`#ffffffff`) or omit for the original colors. For a solid-color rectangle, point `file` at `drawings/floor.drawing` (an 8×8 white pixel sprite) and set `tint` to your color.
+- **Collider** — `{ kind: 'solid'|'pickup', width, height, offsetX?, offsetY?, debug? }`. Just a rect; the framework does NOT auto-resolve collisions for you. Use it as data:
+
+  ```jsx
+  for (const other of scene.getActors()) {
+    if (other.id === actor.id) continue;
+    if (scene.overlaps(actor, other)) {
+      /* react */
+    }
+  }
+  ```
+
+- **Camera** — `{ target: actorId, followX, followY, roomWidth, roomHeight }`. Place on a dedicated actor; sets `scene.camera` clamped to the room. Omit entirely for a fixed view (no camera = no translation).
+
+## SceneRuntime API (what `scene` exposes to behaviors)
+
+- `scene.time` — seconds since start.
+- `scene.keys` — `Set` of currently-held KeyboardEvent codes (e.g. `'ArrowLeft'`, `'KeyA'`, `'Space'`). Read in `update`.
+- `scene.pointer` — `{ x, y, down }` in world (card) coordinates, camera-adjusted.
+- `scene.getActor(id)` / `scene.getActors()` (sorted by Layout.z) / `scene.getComponent(actor, name)`.
+- `scene.actorWith('GameController')` / `scene.actorsWith('Brick')` — find one / all actors carrying a given behavior. Prefer these to `getActors().find(a => a.components.X)`.
+- `scene.colliderRect(actorOrId)` — rect from Layout + Collider, or null.
+- `scene.overlaps(a, b)` — true when two actors/ids with Collider overlap.
+- `scene.data` — the live scene data. Mutate `actor.components.X = {...}` to change props.
+- `scene.spawnActor({ components: { Layout: {...}, MyBehavior: {...} } })` — add a new actor at runtime. Returns the actor (with auto-minted `id` and `runtime = {}`). Use this; don't push to `scene.data.actors` by hand.
+- `scene.despawnActor(id)` — remove an actor at runtime. Use this; don't `splice` + `delete` by hand.
+- `scene.status` — string you can set/read for game-state ('playing', 'gameover', ...).
+- `actor.runtime` — per-instance scratchpad for transient state across frames (e.g. velocity, trail history). Not serialized.
+
+## Input shortcuts
+
+```jsx
+if (scene.keys.has('ArrowLeft')) layout.x -= speed * dt;
+if (scene.keys.has('ArrowRight')) layout.x += speed * dt;
+if (scene.keys.has('Space')) /* launch ball */ ;
+```
+
+For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`. The deck has TouchControls overlay support out of the box for mobile play (arrow keys + a button); no setup needed.
+
+## Common breakout-shaped recipe (sketch)
+
+- `Paddle` behavior: read keys, clamp x to `[0, 500 - layout.width]`.
+- `Ball` behavior: store `vx, vy` on `actor.runtime`; integrate; bounce off wall edges (`x<0`, `x+w>500`, `y<0`); on `scene.overlaps(actor, paddle)`, flip `vy`; for each `brick` in `scene.actorsWith('Brick')` check `scene.overlaps(actor, brick)` → flip `vy` and `scene.despawnActor(brick.id)`; if `y > 700` lose a life.
+- `Brick` behavior: typically just a marker — `kind: 'solid'` collider is enough. State (hit count) goes on `actor.runtime` or the brick's own props.
+- `GameController` (no Layout needed if you don't draw it): tracks score / lives / status; expose HUD via `ui()`.
+
+## Don't
+
+- Don't `console.log` in tight loops — flood the serve log.
+- Don't keep per-actor state on the behavior class instance; it's recreated each frame. Use `actor.runtime` or component props.
+- Don't try to import from `editors/`; behaviors run in the play runtime too.
+- Don't add types or `.ts`/`.tsx` files. This kit is JavaScript.
+- Don't add a build step or change `vite.config.js` for a game — it's configured for you.

package/kits/basic-2d/behaviors/Camera.jsx

@@ -0,0 +1,43 @@
+import { cardSize } from '../engine/scene';
+
+// Follow camera: keeps the target actor centered in the viewport, clamped to
+// the room bounds so the empty area past the room edges never scrolls in.
+export class Camera {
+  static behaviorName = 'Camera';
+
+  static defaultProps = {
+    target: '',
+    followX: true,
+    followY: true,
+    roomWidth: 900,
+    roomHeight: 1100,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(_actor, scene) {
+    const target = this.props.target ? scene.getActor(this.props.target) : undefined;
+    const targetLayout = target?.components.Layout;
+    if (!targetLayout) return;
+
+    const centerX = targetLayout.x + targetLayout.width / 2;
+    const centerY = targetLayout.y + targetLayout.height / 2;
+    const desiredX = centerX - cardSize.width / 2;
+    const desiredY = centerY - cardSize.height / 2;
+
+    scene.camera = {
+      x: this.props.followX
+        ? clamp(desiredX, 0, this.props.roomWidth - cardSize.width)
+        : 0,
+      y: this.props.followY
+        ? clamp(desiredY, 0, this.props.roomHeight - cardSize.height)
+        : 0,
+    };
+  }
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(Math.max(min, max), value));
+}

package/kits/basic-2d/behaviors/Collider.jsx

@@ -0,0 +1,71 @@
+import React from 'react';
+import { Panel, SelectField } from '../engine/ui';
+import { AutoFields } from '../engine/autoInspector';
+
+export class Collider {
+  static behaviorName = 'Collider';
+
+  static defaultProps = {
+    kind: 'solid',
+    width: 32,
+    height: 32,
+    offsetX: 0,
+    offsetY: 0,
+    debug: false,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  draw(actor, _scene, ctx, options) {
+    if (!options.showDebugColliders && !this.props.debug) return;
+    const rect = getColliderRect(actor);
+    if (!rect) return;
+    ctx.save();
+    ctx.strokeStyle = this.props.kind === 'pickup' ? '#ffe17a' : '#8db7ff';
+    ctx.lineWidth = 2;
+    ctx.strokeRect(rect.x + 1, rect.y + 1, rect.width - 2, rect.height - 2);
+    ctx.restore();
+  }
+
+  static Inspector({ component, setComponent }) {
+    return (
+      <Panel title="Collider">
+        <SelectField
+          label="Kind"
+          value={component.kind}
+          onChange={(kind) => setComponent({ kind: kind })}
+          options={['solid', 'pickup']}
+        />
+        <AutoFields
+          defaultProps={Collider.defaultProps}
+          component={component}
+          setComponent={setComponent}
+          exclude={['kind']}
+        />
+      </Panel>
+    );
+  }
+}
+
+export function getColliderRect(actor) {
+  const layout = actor.components.Layout;
+  const collider = actor.components.Collider;
+  if (!layout || !collider) return null;
+  return {
+    x: layout.x + (collider.offsetX ?? 0),
+    y: layout.y + (collider.offsetY ?? 0),
+    width: collider.width ?? layout.width,
+    height: collider.height ?? layout.height,
+  };
+}
+
+export function intersects(a, b) {
+  return (
+    a.x < b.x + b.width &&
+    a.x + a.width > b.x &&
+    a.y < b.y + b.height &&
+    a.y + a.height > b.y
+  );
+}