castle-web-cli 0.4.94 → 0.4.96

package/dist/agent.js

@@ -24,7 +24,7 @@ import { rawDataToString } from "./ide.js";
 import { buildRouterPrompt, buildTaskPrompt, userTurnInstruction, CLAUDE_TASK_SYSTEM_REMINDER, } from "./agent-prompts.js";
 import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from "./openrouter-catalog.js";
 import { classifyProviderError, failureCopy, } from "./agent-failures.js";
-import { meteringHeaders, newAgentSessionId, withCustomHeaders, } from "./metering.js";
+import { meteringHeaders, newAgentSessionId, reportCursorRun, withCustomHeaders, } from "./metering.js";
 import { runAgentNative } from "./native/loop.js";
 import { createPlaytestBrowserManager } from "./native/playtest-browser.js";
 import { createPlaywrightPlaytestExecutor } from "./native/playtest-executor.js";
@@ -356,6 +356,9 @@ function handleModelCaps(req, res) {
 // Single `=` token because --allowedTools is variadic and would otherwise
 // swallow the trailing prompt positional.
 const OPENROUTER_ALLOWED_TOOLS = "--allowedTools=Edit,Write,NotebookEdit,Bash";
+// Cursor's proprietary model. Also the slug reported to the metering ledger, so
+// the two can never drift into disagreeing about what a cursor row ran on.
+const CURSOR_MODEL = "composer-2.5-fast";
 function buildAgentInvocation(backend, role, prompt, claudeModel, 
 // Already resolved for this role by the caller (router turns pass
 // settings.routerOpenrouterModel, task spawns settings.tasksOpenrouterModel).
@@ -426,7 +429,7 @@ metering) {
             "--stream-partial-output",
             "--trust",
             "--model",
-            "composer-2.5-fast",
+            CURSOR_MODEL,
             ...(role === "router" ? ["--mode", "ask"] : ["--force"]),
             prompt,
         ],
@@ -1226,67 +1229,6 @@ function logAgentUsage(label, backend, usage) {
     const output = formatTokenCount(usage.output_tokens);
     console.error(`[agent usage] ${label} ${backend}: input=${input} cache_read=${read} cache_created=${created} output=${output}`);
 }
-// Per-deck machine-readable usage ledger, appended to <deckDir>/.castle/agent/,
-// harvested out-of-band (by the cloud launcher) for rough per-user token
-// metering. Distinct from logAgentUsage's stderr line, which is lossy
-// (rounds to "3.2k") and gets truncated when the serve restarts.
-const USAGE_LEDGER_FILE = "usage.jsonl";
-// The ledger is only useful where the cloud launcher harvests it, so the managed
-// sandbox environments set CASTLE_USAGE_LEDGER=1 (E2B via cloudSandbox.serveOnPort,
-// castle-sandboxes via its image). A local `castle-web serve` leaves it unset, so
-// dev deck dirs don't accumulate a ledger nothing reads.
-const USAGE_LEDGER_ENABLED = process.env.CASTLE_USAGE_LEDGER === "1";
-// Concrete model behind a finished run: smith and claude-via-OpenRouter both
-// bill the OpenRouter slug; plain claude bills its own slug; cursor has no
-// per-model split tracked here.
-function resolveRunModel(backend, claudeModel, openrouterModel) {
-    if (backend === "smith")
-        return openrouterModel;
-    if (backend === "claude") {
-        return claudeModel === "openrouter" ? openrouterModel : claudeModel;
-    }
-    return backend;
-}
-// One record per finished run: the human-readable stderr line PLUS a precise
-// append-only JSONL line in the deck's usage ledger. Precise counts (not the
-// stderr line's rounded values) and self-describing (id/role/backend/model) so
-// the harvester can attribute and de-dup. Best-effort: a metering write must
-// never fail an agent run.
-function reportRunUsage(agentDir, role, backend, claudeModel, openrouterModel, result, taskId) {
-    const usage = result.usage;
-    logAgentUsage(taskId ? `task ${taskId}` : "router", backend, usage);
-    if (!USAGE_LEDGER_ENABLED)
-        return;
-    // cursor-agent's stream-json doesn't report token usage, so a cursor run has no
-    // `usage`; still record it (zero counts, tokens_reported:false) for run-count
-    // visibility. Other backends only write once they actually produced usage.
-    if (!usage && backend !== "cursor")
-        return;
-    try {
-        const line = JSON.stringify({
-            at: nowIso(),
-            id: nanoid(),
-            role,
-            backend,
-            model: resolveRunModel(backend, claudeModel, openrouterModel),
-            ...(taskId ? { taskId } : {}),
-            // A failed run still resolves with a usage object of all zeros (an auth
-            // error emits a result event with zeroed counts), so its zeros would
-            // otherwise be indistinguishable downstream from a real "measured zero".
-            ...(result.ok ? {} : { failed: true }),
-            tokens_reported: usage !== undefined,
-            input_tokens: usage?.input_tokens ?? 0,
-            output_tokens: usage?.output_tokens ?? 0,
-            cache_read_input_tokens: usage?.cache_read_input_tokens ?? 0,
-            cache_creation_input_tokens: usage?.cache_creation_input_tokens ?? 0,
-        });
-        fs.mkdirSync(agentDir, { recursive: true });
-        fs.appendFileSync(path.join(agentDir, USAGE_LEDGER_FILE), line + "\n");
-    }
-    catch {
-        /* best-effort: a metering write must never fail an agent run */
-    }
-}
 // Build the per-run stdout event handler over a shared mutable parser state.
 // Splitting the cursor + claude stream decoding out of runAgentCli keeps each
 // within the max-lines budget; behavior is identical (same delta/activity/
@@ -1735,7 +1677,8 @@ async function runAgentTurn(opts) {
         });
     }
     const invocation = buildAgentInvocation(opts.backend, opts.role, opts.prompt, opts.claudeModel, opts.openrouterModel, { sessionId, deckDir: opts.cwd });
-    return runAgentCli({
+    const startedMs = Date.now();
+    const run = runAgentCli({
         cwd: opts.cwd,
         command: invocation.command,
         args: invocation.args,
@@ -1753,6 +1696,21 @@ async function runAgentTurn(opts) {
             ? opts.openrouterModel
             : undefined,
     });
+    // Cursor is the only backend whose traffic never reaches the llm-proxy, so its
+    // run is reported from here. Every other backend is already recorded upstream,
+    // and reporting them here too would double-count them in the same table.
+    if (opts.backend !== "cursor")
+        return run;
+    return run.then((result) => {
+        reportCursorRun({
+            deckDir: opts.cwd,
+            sessionId,
+            model: CURSOR_MODEL,
+            durationMs: Date.now() - startedMs,
+            ok: result.ok,
+        });
+        return result;
+    });
 }
 // -- task store ---------------------------------------------------------------
 function persistTaskFile(tasksDir, task) {
@@ -1999,7 +1957,7 @@ async function runTaskAgentIn(ctx, task) {
                     ctx.onFeed(`[${activity}]`);
             },
         });
-        reportRunUsage(path.dirname(ctx.tasksDir), "task", ctx.backend, ctx.claudeModel, ctx.openrouterModel, result, task.id);
+        logAgentUsage(`task ${task.id}`, ctx.backend, result.usage);
         if (ctx.stopRequested.has(task.id))
             return result;
         if (!result.crashed)
@@ -2794,7 +2752,7 @@ function runRouterTurnIn(ctx, instruction, attachments = []) {
         },
     })
         .then((result) => {
-        reportRunUsage(ctx.agentDir, "router", backend, ctx.claudeModel(), ctx.openrouterModel(), result);
+        logAgentUsage("router", backend, result.usage);
         // Signals the finally -> onSettled(retryable): the turn failed cleanly
         // enough (transient, nothing salvaged) that the queue may re-run it.
         let retryable = false;

package/dist/init.js

@@ -36,7 +36,7 @@ const DEFAULT_KIT = "basic-2d";
 // Registry version of castle-web-sdk to inject when scaffolding from a
 // globally-installed castle-web (not from inside the workspace). Bumped
 // alongside cli/sdk version bumps.
-const PUBLISHED_SDK_VERSION = "0.4.10";
+const PUBLISHED_SDK_VERSION = "0.4.11";
 // Never copied into a fresh deck: build/dependency junk. castle.json IS copied
 // (the kit ships a config-only one with the editor layout / file filters), but
 // `scaffoldFromKit` strips any identity fields off it first -- a fresh deck has
@@ -145,6 +145,23 @@ function tryMakeAgentsSymlink(agentsPath) {
         // symlink already exists / unsupported FS — non-fatal
     }
 }
+// Scripts for a deck whose kit is an import. The same deck commands every
+// scaffold gets, plus the kit's own authoring commands re-pointed at where the
+// kit now lives -- a kit's CLAUDE.md tells the agent to run `npm run draw` and
+// `npm run restart`, and those have to exist in the deck for that to be true.
+function makeKitDeckScripts(kitDir, alias, cliCommand) {
+    const scripts = {
+        restart: `${cliCommand} restart .`,
+        screenshot: `${cliCommand} screenshot .`,
+        "save-deck": `${cliCommand} save-deck .`,
+    };
+    // `draw` is a kit script, not a CLI one, so it only exists if this kit ships
+    // it -- and it runs from the deck root, where the sprites belong.
+    if (fs.existsSync(path.join(kitDir, "scripts", "draw.mjs"))) {
+        scripts.draw = `node ${IMPORTS_DIR}/${alias}/scripts/draw.mjs`;
+    }
+    return scripts;
+}
 function makePackageJson(projectDir) {
     const { sdkRef, cliCommand } = resolveScaffoldRefs();
     return {
@@ -291,6 +308,23 @@ something in the kit behaves, define your own behavior of the same name in
 \`behaviors/\` -- the deck's own files win over an import's.
 `;
 }
+// How the deck names the kit it was built on. `scripts/publish-kits.mjs` stamps
+// a published kit's castle.json with the deckId it lives at and the version it
+// was published as, and both have to be present to pin it that way: a deckId
+// with no version would read as "you have some unknown version", which the
+// update check would report as an update available forever.
+//
+// Falling back to the CLI's copy is what makes a kit usable before it is ever
+// published -- a new kit works from the day it exists, and starts offering
+// updates the day it is published, with nothing in between to migrate.
+function makeKitPin(kitConfig, kit) {
+    const deckId = kitConfig.deckId;
+    const version = kitConfig.publishedVersion;
+    if (typeof deckId === "string" && typeof version === "string") {
+        return { deckId, version };
+    }
+    return { source: "builtin", kit, version: getCliVersion() };
+}
 // Scaffold a deck that IMPORTS its kit instead of copying it. The kit's files
 // land in `imports/<kit>/` (read-only, like any dependency) and the deck itself
 // holds only what is genuinely its own: an entry point, its config, and its
@@ -298,10 +332,11 @@ something in the kit behaves, define your own behavior of the same name in
 // rather than being frozen into the deck at scaffold time -- which is what
 // copying the kit in meant.
 //
-// The kit comes from the copy shipped with this CLI, so `init` works offline and
-// needs no account. The pin records that origin; once kits are published as
-// decks it becomes a deckId + version and the files are fetched instead, with
-// the same deck shape either way.
+// The files always come from the copy shipped with this CLI, so `init` works
+// offline and needs no account. What the pin SAYS depends on whether the kit has
+// been published: an unpublished one can only be named as the CLI's own copy,
+// while a published one is pinned by deckId so the deck can be told about kit
+// releases and take them, without waiting for a CLI release.
 function scaffoldFromKitImport(kit, projectDir) {
     const kitDir = requireKitDir(kit);
     // Qualified like any other import (`<author>.<deck>`), and qualified NOW even
@@ -326,12 +361,12 @@ function scaffoldFromKitImport(kit, projectDir) {
     // the import pin.
     writeJsonFile(path.join(projectDir, "castle.json"), {
         ...(kitConfig.editor ? { editor: kitConfig.editor } : {}),
-        imports: { [alias]: { source: "builtin", kit, version: getCliVersion() } },
+        imports: { [alias]: makeKitPin(kitConfig, kit) },
     });
     // The kit's code runs from THIS deck's node_modules, so its dependencies are
     // declared here (see syncImportDependencies, which does the same for imports
     // added later).
-    const { sdkRef } = resolveScaffoldRefs();
+    const { sdkRef, cliCommand } = resolveScaffoldRefs();
     const dependencies = {};
     for (const [name, range] of Object.entries(kitPkg.dependencies ?? {})) {
         dependencies[name] =
@@ -343,6 +378,7 @@ function scaffoldFromKitImport(kit, projectDir) {
         name: path.basename(projectDir),
         private: true,
         type: "module",
+        scripts: makeKitDeckScripts(kitDir, alias, cliCommand),
         dependencies,
     });
     fs.writeFileSync(path.join(projectDir, "CLAUDE.md"), makeImportedKitClaudeMd(alias));

package/dist/metering.d.ts

@@ -7,6 +7,29 @@ export type MeteringRoute = "anthropic" | "openrouter";
  * background-task spend" a prefix match with no extra column.
  */
 export declare function newAgentSessionId(role: "router" | "task"): string;
+/**
+ * Report a cursor run to the llm-proxy, which stamps the user + sandbox from
+ * our token and forwards it to the ledger alongside the anthropic/openrouter
+ * rows the proxy records itself.
+ *
+ * Cursor needs this because it is the one backend the proxy cannot see:
+ * cursor-agent has no base-URL override, so it talks to Cursor directly on its
+ * own key. There are no token counts to send -- cursor-agent's stream-json
+ * reports none -- so a row is a run count with its deck, agent run, model, and
+ * outcome, and the ledger's NULL tokens read as "not measured".
+ *
+ * Fire-and-forget by contract: the run is already over and its output already
+ * reached the user, so every failure here is swallowed. A dropped post loses
+ * one row rather than retrying, which is the right trade for a signal whose
+ * value is aggregate.
+ */
+export declare function reportCursorRun(opts: {
+    deckDir: string;
+    sessionId: string;
+    model: string;
+    durationMs: number;
+    ok: boolean;
+}): void;
 export declare function meteringHeaders(opts: {
     deckDir: string;
     sessionId: string;

package/dist/metering.js

@@ -48,6 +48,58 @@ function deckIdFor(deckDir) {
         return null;
     return parsed.deckId.replace(/[\r\n]/g, "") || null;
 }
+// Path on the proxy that accepts a run the proxy never routed. Must match
+// CASTLE_USAGE_PATH in castle-sandboxes/shared/src/index.ts.
+const CASTLE_USAGE_PATH = "/castle/usage";
+// A metering post must never delay a turn that has already finished, and its
+// result is never awaited -- so a proxy that has gone away costs one socket
+// timeout in the background, not a hung run.
+const USAGE_POST_TIMEOUT_MS = 5_000;
+/**
+ * Report a cursor run to the llm-proxy, which stamps the user + sandbox from
+ * our token and forwards it to the ledger alongside the anthropic/openrouter
+ * rows the proxy records itself.
+ *
+ * Cursor needs this because it is the one backend the proxy cannot see:
+ * cursor-agent has no base-URL override, so it talks to Cursor directly on its
+ * own key. There are no token counts to send -- cursor-agent's stream-json
+ * reports none -- so a row is a run count with its deck, agent run, model, and
+ * outcome, and the ledger's NULL tokens read as "not measured".
+ *
+ * Fire-and-forget by contract: the run is already over and its output already
+ * reached the user, so every failure here is swallowed. A dropped post loses
+ * one row rather than retrying, which is the right trade for a signal whose
+ * value is aggregate.
+ */
+export function reportCursorRun(opts) {
+    const base = process.env.CASTLE_LLM_PROXY_URL;
+    const token = process.env.CASTLE_LLM_PROXY_TOKEN;
+    // Absent outside a sandbox, and on a host whose proxy predates this route --
+    // both cases correctly report nothing rather than posting into the void.
+    if (!base || !token)
+        return;
+    const deckId = deckIdFor(opts.deckDir);
+    void fetch(`${base}${CASTLE_USAGE_PATH}`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify({
+            provider: "cursor",
+            model: opts.model,
+            ...(deckId ? { deckId } : {}),
+            agentSessionId: opts.sessionId,
+            durationMs: opts.durationMs,
+            // A cursor run has no HTTP status; the ledger's column is one, and
+            // `>= 400 means it failed` is the reading every other row already gets.
+            status: opts.ok ? 200 : 500,
+        }),
+        signal: AbortSignal.timeout(USAGE_POST_TIMEOUT_MS),
+    }).catch(() => {
+        /* best-effort: metering must never surface in a finished run */
+    });
+}
 export function meteringHeaders(opts) {
     if (opts.direct || !proxyInjected(opts.route))
         return {};

package/kits/basic-2d/castle.json

@@ -3,11 +3,30 @@
     "initialPanels": [
       {
         "width": 400,
-        "column": [{ "type": "playtest" }, { "type": "files" }]
+        "column": [
+          {
+            "type": "playtest"
+          },
+          {
+            "type": "files"
+          }
+        ]
       },
-      { "type": "editor", "file": "scenes/main.scene" }
+      {
+        "type": "editor",
+        "file": "scenes/main.scene"
+      }
     ],
     "hiddenPaths": [],
-    "visiblePaths": ["drawings/**", "scenes/**", "blueprints/**", "behaviors/**"]
-  }
+    "visiblePaths": [
+      "drawings/**",
+      "scenes/**",
+      "blueprints/**",
+      "behaviors/**"
+    ]
+  },
+  "deckId": "5R39TxaRfLLQ",
+  "cardId": "AZk0PWHTrFcT",
+  "title": "basic-2d",
+  "publishedVersion": "2026-07-28T17:52:37.298Z"
 }

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

@@ -3,8 +3,9 @@
 This is the `basic-2d` actor/behavior/scene framework plus a built-in 2D
 **physics** system (matter-js). Everything in `basic-2d` works the same; physics
 adds `RigidBody`, physics fields on `Collider`, a world-gravity scene setting,
-collision callbacks, and ready-made touch-first controls (`Draggable`,
-`Slingshot`, `AnalogStick`). See `## Physics` below.
+collision callbacks, `Joints` that link actors (spring/rod/pin/weld/rope, several
+per actor), and ready-made touch-first controls (`Draggable`, `Slingshot`, `AnalogStick`).
+See `## Physics` below.
 
 ## Welcome message
 
@@ -27,6 +28,25 @@ Do you already know what you want to make, or do you want to figure it out toget
 - Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`) to build a game. Their public API is documented below.
 - Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
 
+## Files and imports
+
+One rule wherever a file is named -- JS imports, `"blueprint"` refs, `Sprite.file`,
+a joint's `sprite`, anything a behavior invents:
+
+- `drawings/ship.pxart` -- a file of the deck the reference is WRITTEN IN. In this
+  deck's own files that means this deck; in a file belonging to an import, that
+  import. So a kit's blueprint saying `drawings/cauldron.pxart` keeps meaning the
+  kit's drawing once the kit is imported by someone else.
+- `@imports/<alias>/drawings/ship.pxart` -- a file of the deck imported under
+  `<alias>`. This is the only way to name another deck's file, so cross-deck
+  references are visible as such, and it means the same thing from any file at
+  any depth.
+
+Imports are read-only: their files belong to the deck they came from. Use them,
+don't edit them. `castle-web add-import <deckId>` adds one, `update-import`
+re-fetches it. `resolveDeckFile` from `castle-web-sdk` is the rule itself, if a
+behavior needs to resolve a path it was handed.
+
 ## 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.
@@ -152,6 +172,10 @@ make it move.**
   (`mode`, `width`/`height`, `offsetX`/`offsetY`, `debug`) it has:
   - `shape: 'box' | 'circle'` — the physics shape (default `box`). A circle uses
     `radius`, or half the smaller collider dimension if `radius` is 0.
+  - A collider can hold **multiple shapes** (a compound body) — edit them in the
+    inspector's shape list. A **box shape takes an `angle`** (degrees), so one
+    actor can have an angled collider (e.g. a skateboard: a flat deck box plus an
+    upturned nose and tail box) instead of gluing separate actors together.
   - `isTrigger` — a **sensor**: detects overlaps (fires collision callbacks) but
     does **not** block. Use for pickups, goals, zones.
   - `bounciness` — restitution, 0 (dead) to ~1 (very bouncy), can exceed 1.
@@ -228,6 +252,83 @@ on-screen control -- never be the only way to play.
   `onCollisionEnter` that scores when `other` is the ball.
 - Scene: set `"physics": { "gravity": 1 }`, place one ball, walls, a goal.
 
+### Joints (link actors together)
+
+Add a **`Joints`** behavior to connect an actor to one or more `target` actors
+with physics links. The component holds a **list**, so one actor can carry
+several links at once (a ragdoll pelvis pinned to both thighs, a ball slung
+between two anchors, a body both sprung and roped). Both actors of a link need a
+`Collider` (to have a body); the owner is usually a dynamic `RigidBody` and each
+target either dynamic or a static anchor (a lone `Collider`). Each list entry:
+
+- `type` — the link's feel:
+  - `spring` — soft elastic tether (`springiness` 0..1 + `damping`).
+  - `rod` — rigid fixed-distance stick; the ends still rotate freely. This is also
+    your **hinge**: a `rod` to a static anchor is a pendulum / swinging door.
+  - `weld` — fused rigid: a pivot link plus frozen rotation, so the two bodies
+    can't move or turn relative to each other. Place them slightly apart.
+  - `rope` — slack, taut only at `length` (max); the bob free-falls then catches.
+  - (`pin`, a free-rotating coincident-pivot hinge, was removed — a length-0
+    revolute between two dynamic bodies is matter's most unstable case. Use `rod`.)
+- `target` — the other actor's id. **Author it per instance** (pick it on the
+  canvas — see below), not on a blueprint, unless every instance really should
+  link to the same actor (e.g. many things roped to one anchor).
+- `length` — rest length (spring/rod) or max length (rope) in px. In the
+  inspector, turn **Auto length** on to lock it to the actors' distance when play
+  starts (stored as `-1`). Not used by `pin`/`weld`.
+- `springiness` (0..1) — for `spring`, how bouncy the tether is; for `rope`, how
+  it behaves *when taut*: `0` = a dead rope (holds firm at max length), `1` = a
+  bungee (stretches well past and springs back).
+- `damping` (0..1, spring only) — how fast the spring's oscillation settles.
+- `anchorX/anchorY` (+ `targetAnchorX/targetAnchorY` for spring/rod/rope) —
+  attach-point offsets in px, under the inspector's **Anchor offsets** toggle. For
+  `pin`/`weld` the owner offset moves the shared pivot.
+
+**Author a joint:** add the `Joints` behavior to the owner, then in the inspector
+click **Pick target** and click the other actor on the canvas (Esc / empty click
+cancels). **+ Add joint** appends another link; each has its own Remove. Links
+draw as colored overlays (coil = spring, dashed = rope, double line = weld, ring =
+pin, plain line = rod) so you can see what's connected. In the scene file it's a
+list: `"Joints": { "list": [ { "type": "rod", "target": "anchor" }, … ] }`.
+
+`target` is instance-local (a blueprint-level target points every instance at the
+same actor — only what you want for a shared anchor). You rarely need multiple
+entries: a chain A–B–C just puts one link on B→A and one on C→B. Reach for a
+multi-entry list when an actor genuinely connects to two+ others at once.
+
+Recipe — pendulum: a static `anchor` actor (Collider, no RigidBody) at top, a
+dynamic ball below with `Joints { list: [{ type: 'rod', target: 'anchor' }] }`.
+The ball swings at a fixed radius. Swap `rod`→`rope` for a slack tether,
+`rod`→`spring` for a bouncy one; add a second entry to sling it between two
+anchors.
+
+**How a joint looks in play** — each entry has a `render`:
+
+- `line` (default) — the schematic overlay (coil/dashed/etc.). Good for
+  prototyping; you see your joints working.
+- `hidden` — nothing drawn in play (the joint is pure mechanics). It still shows
+  as a faint line in the *editor* so you don't lose track of it.
+- `sprite` — draw art along the joint. Set `sprite` to a `.pxart`
+  (defaults to a built-in rope), `thickness` (px), and `fit`: `tile` (repeat a
+  segment — rope, chain) or `stretch` (one image end-to-end — stick, beam). The
+  art rotates to the joint's angle and scales to its live length, so a rope
+  visibly stretches. The editor previews it WYSIWYG.
+
+**Custom joint visuals (draw your own):** for anything beyond the built-in art,
+set the joint's `render: 'hidden'` and draw it yourself from a behavior's
+`draw()` using `scene.physics.getJoints()`. It returns one entry per link with
+world-space endpoints so your art lines up with the sprites:
+
+```jsx
+draw(actor, scene, ctx) {
+  for (const j of scene.physics.getJoints()) {
+    // j = { ownerId, targetId, type, a:{x,y}, b:{x,y}, length, angle }
+    ctx.strokeStyle = '#0cf1ff';
+    ctx.beginPath(); ctx.moveTo(j.a.x, j.a.y); ctx.lineTo(j.b.x, j.b.y); ctx.stroke();
+  }
+}
+```
+
 ### Gotchas
 
 - **Fast bodies + thin walls tunnel.** A small body moving faster than a static
@@ -241,6 +342,12 @@ on-screen control -- never be the only way to play.
   directly is only for `static`/`kinematic` bodies.
 - **Editor vs play.** Physics only steps during play; in the editor actors sit
   where you place them. `RigidBody.velocityX/Y` apply once when play starts.
+- **A joint binds only when both actors have a body.** If a `Joints` entry's
+  owner or `target` has no `Collider` (or the target id is wrong/missing), that
+  link is silently skipped until both bodies exist. `weld`/`pin` want the two
+  actors placed a little apart, not overlapping.
+- **A global max-speed clamp (`MAX_SPEED` in matterBridge)** backstops any joint
+  blow-up so a body can't be flung off screen — normal motion never reaches it.
 
 ## Adding physics to another kit
 
@@ -250,10 +357,13 @@ different kit:
 1. Copy the `physics/` folder into the kit.
 2. Add `matter-js` to the kit's `package.json` dependencies.
 3. In the kit's `engine/scene.js`: add a systems registry to `SceneRuntime`
-   (`this.systems = []`, a `registerSystem(system)` method, and, at the end of
-   `update(dt)`, `for (const s of this.systems) s.afterBehaviors?.(this, dt);`),
-   then call `installPhysics(runtime)` from `makeScene` (and route `clone()`
-   through `makeScene` so clones get it too).
+   (`this.systems = []`, a `registerSystem(system)` method, at the end of
+   `update(dt)` a `for (const s of this.systems) s.afterBehaviors?.(this, dt);`,
+   and at the START of `load(sceneData)` a
+   `for (const s of this.systems) s.reset?.(this);` so a reload/restart/scene
+   transition resets the simulation to the authored layout instead of carrying
+   over body positions + joints), then call `installPhysics(runtime)` from
+   `makeScene` (and route `clone()` through `makeScene` so clones get it too).
 4. In the kit's `editors/behaviorRegistry`, also glob
    `../physics/behaviors/*.jsx` so the physics behaviors auto-register.
 

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

@@ -1,4 +1,4 @@
-import React, { useState } from 'react';
+import React, { useEffect, useState } from 'react';
 import { NumberField, Panel, SelectField } from '../engine/ui';
 import { AutoFields } from '../engine/autoInspector';
 import { computeAutoFit, getColliderRect, getColliderShapes, intersects } from '../engine/collider';
@@ -61,6 +61,13 @@ function drawShape(ctx, s) {
     for (let k = 1; k < s.points.length; k++) ctx.lineTo(s.points[k].x, s.points[k].y);
     ctx.closePath();
     ctx.stroke();
+  } else if (s.angle) {
+    // Rotate the outline about the box center to match the (angled) matter part.
+    ctx.save();
+    ctx.translate(s.cx, s.cy);
+    ctx.rotate((s.angle * Math.PI) / 180);
+    ctx.strokeRect(-s.width / 2 + 1, -s.height / 2 + 1, s.width - 2, s.height - 2);
+    ctx.restore();
   } else {
     ctx.strokeRect(s.x + 1, s.y + 1, s.width - 2, s.height - 2);
   }
@@ -113,14 +120,21 @@ export class Collider {
     const shapes = getColliderShapes(actor);
     if (!shapes) return;
     const isSensor = Boolean(this.props.isTrigger) || this.props.kind === 'pickup';
+    // When editing this blueprint (hotbar), highlight the shape the inspector has
+    // selected so you can tell which chip is which on its lit instances -- the
+    // selected-instance path does this via the SelectionOverlay instead.
+    const highlight = blueprintSelected ? options.colliderShapeSel ?? -1 : -1;
     ctx.save();
-    ctx.strokeStyle = isSensor ? '#ffe17a' : '#8db7ff';
-    ctx.lineWidth = 2;
-    for (const s of shapes) drawShape(ctx, s);
+    shapes.forEach((s, k) => {
+      const on = k === highlight;
+      ctx.strokeStyle = on ? '#ffd24a' : isSensor ? '#ffe17a' : '#8db7ff';
+      ctx.lineWidth = on ? 3.5 : 2;
+      drawShape(ctx, s);
+    });
     ctx.restore();
   }
 
-  static Inspector({ actor, component, sprites, setComponent, override }) {
+  static Inspector({ actor, component, sprites, setComponent, override, onSelectShape }) {
     const [sel, setSel] = useState(0);
     const [addOpen, setAddOpen] = useState(false);
     const layout = actor?.components?.Layout ?? {};
@@ -129,6 +143,9 @@ export class Collider {
 
     const shapes = currentShapes(component);
     const i = Math.min(sel, shapes.length - 1);
+    // Report the selected shape index up so the on-canvas overlay can highlight
+    // it (fires on mount with 0, and on every chip click / add / remove).
+    useEffect(() => onSelectShape?.(i), [i, onSelectShape]);
     const shape = shapes[i];
     const isCircle = shape.type === 'circle';
     const isPoly = shape.type === 'triangle' || shape.type === 'polygon';
@@ -160,6 +177,22 @@ export class Collider {
     const offXPx = Math.round(((shape.x ?? 0.5) - 0.5) * bw);
     const offYPx = Math.round(((shape.y ?? 0.5) - 0.5) * bh);
 
+    // Per-subfield override state vs the blueprint's version of THIS shape. The
+    // shape fields don't go through AutoFields, so without this an instance that
+    // changed e.g. box 3's offset X wouldn't show the tint / Default / Reset.
+    // Null override (editing the blueprint template itself) shows nothing.
+    const bpShapes = override?.baseline?.('shapes');
+    const bShape = Array.isArray(bpShapes) ? bpShapes[i] : null;
+    const shapeOv = (key, dflt, toPx) => {
+      if (!bShape || bShape.type !== shape.type) return {};
+      const bv = bShape[key] ?? dflt;
+      return {
+        overridden: Math.abs((shape[key] ?? dflt) - bv) > 1e-4,
+        defaultValue: toPx(bv),
+        onReset: () => patchSel({ [key]: bv }),
+      };
+    };
+
     const density = component.density > 0 ? component.density : 0.001;
 
     // Auto-fit (box/circle) for the selected shape.
@@ -205,17 +238,50 @@ export class Collider {
           <>
             <SelectField label="Shape" value={shape.type} onChange={setType} options={['box', 'circle']} />
             {isCircle ? (
-              <NumberField label="Radius" value={radiusPx} onChange={(v) => patchSel({ r: v / Math.min(bw, bh) })} />
+              <NumberField
+                label="Radius"
+                value={radiusPx}
+                onChange={(v) => patchSel({ r: v / Math.min(bw, bh) })}
+                {...shapeOv('r', 0.5, (f) => Math.round(f * Math.min(bw, bh)))}
+              />
             ) : (
               <>
-                <NumberField label="Width" value={widthPx} onChange={(v) => patchSel({ w: v / bw })} />
-                <NumberField label="Height" value={heightPx} onChange={(v) => patchSel({ h: v / bh })} />
+                <NumberField
+                  label="Width"
+                  value={widthPx}
+                  onChange={(v) => patchSel({ w: v / bw })}
+                  {...shapeOv('w', 1, (f) => Math.round(f * bw))}
+                />
+                <NumberField
+                  label="Height"
+                  value={heightPx}
+                  onChange={(v) => patchSel({ h: v / bh })}
+                  {...shapeOv('h', 1, (f) => Math.round(f * bh))}
+                />
+                <NumberField
+                  label="Angle"
+                  value={Math.round(shape.angle ?? 0)}
+                  min={-180}
+                  max={180}
+                  onChange={(v) => patchSel({ angle: v })}
+                  {...shapeOv('angle', 0, (f) => Math.round(f))}
+                />
               </>
             )}
           </>
         )}
-        <NumberField label="Offset X" value={offXPx} onChange={(v) => patchSel({ x: 0.5 + v / bw })} />
-        <NumberField label="Offset Y" value={offYPx} onChange={(v) => patchSel({ y: 0.5 + v / bh })} />
+        <NumberField
+          label="Offset X"
+          value={offXPx}
+          onChange={(v) => patchSel({ x: 0.5 + v / bw })}
+          {...shapeOv('x', 0.5, (f) => Math.round((f - 0.5) * bw))}
+        />
+        <NumberField
+          label="Offset Y"
+          value={offYPx}
+          onChange={(v) => patchSel({ y: 0.5 + v / bh })}
+          {...shapeOv('y', 0.5, (f) => Math.round((f - 0.5) * bh))}
+        />
         <div style={actionRow}>
           {autoFit && !fitted ? (
             <button type="button" onClick={() => writeShapes(shapes.map((s, k) => (k === i ? autoFit : s)))} style={linkBtn}>