castle-web-cli 0.4.85 → 0.4.86

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

@@ -99,7 +99,7 @@ A **blueprint** is a `.scene` file under `blueprints/` whose single actor (`acto
       "components": {
         "Layout": { "width": 50, "height": 25 },
         "Sprite": { "file": "drawings/brick.pxart" },
-        "Collider": { "kind": "solid" },
+        "Collider": {},
         "Brick": {}
       }
     }
@@ -120,7 +120,7 @@ Template `components` keys are behavior names (the `static behaviorName`); add a
 - **Sprite** — `{ file: "drawings/foo.pxart", tint?: "#rrggbbaa", playing?: true, tag?: "", mode?: 'cover'|'fit'|'stretch'|'tile', tileSize?: 50 }`. Renders a `.pxart` pixel-art sprite into the Layout box: scaled up preserving the art's aspect ratio to fill the whole box, cropping whatever overflows a mismatched box (`mode: 'cover'`, the default -- CSS object-fit: cover), scaled preserving the art's aspect ratio and centered so the whole sprite stays visible, letterboxing a mismatched box instead of cropping (`mode: 'fit'` -- CSS object-fit: contain), scaled to fill the box exactly and distorting the art when the aspect ratios don't match (`mode: 'stretch'`), or repeated (`mode: 'tile'`). `tint` multiplies; use white (`#ffffffff`) or omit for the original colors. Animated sprites play automatically; set `playing: false` to hold the first frame, or `tag` to play a named animation tag. Tile mode repeats the art at a fixed cell size (`tileSize` card units tall, width scaled by the art's aspect) instead of stretching it across the Layout box.
   - **Missing sprites fall back to a placeholder.** If `file` names a sprite that doesn't exist yet, it renders the fallback `drawings/cauldron.pxart` — so you can give an actor its REAL intended sprite name (`drawings/paddle.pxart`) right away and it shows the placeholder until that file is created. Reference real names from the start; don't wait for the art.
   - **Fill the box, don't distort.** The default `mode: 'cover'` fills the Layout box with the art undistorted, cropping whatever overflows when the box aspect doesn't match the art's — so treat the Layout box like an image frame in a design tool: size it to frame what matters and keep the sprite's important content toward the center, since the edges may be cropped. Keeping an actor's Layout aspect ratio close to its sprite's native aspect ratio minimizes how much gets cropped. When the whole sprite must stay visible (nothing is safe to crop), use `mode: 'fit'`, which preserves the art and letterboxes the mismatched box instead. Avoid `mode: 'stretch'` for pixel art — filling a long/tall box by distorting wrecks the pixels (a brick sprite stretched into a wall ruins the bricks). For long surfaces (walls, floors, platforms), use `mode: 'tile'` on one actor to repeat the art at a fixed cell size instead of stretching or cropping a single sprite.
-- **Collider** — `{ kind: 'solid'|'pickup', mode?: 'auto'|'manual', width, height, offsetX?, offsetY?, debug? }`. Just a rect; `offsetX`/`offsetY` nudge the collider from its default position (so `0,0` is the default). `mode: 'auto'` (the default) fits the rect to the actor's Sprite's opaque pixels, mapped through the Sprite's draw mode (`fit`'s letterboxed dest rect, `stretch`'s full Layout box, `cover`'s filled box clipped to the Layout box; `tile` mode and a missing/unresolved Sprite use the whole Layout box instead). `width`/`height` only apply in `mode: 'manual'` (a rect of that size, centered in the Layout box); they're ignored in `auto`. The framework does NOT auto-resolve collisions for you. Use it as data:
+- **Collider** — `{ shape?: 'box'|'circle', width, height, radius, offsetX?, offsetY?, isTrigger?, debug? }`. A box (default) or circle. **Size tracks the Layout box** unless you set an explicit `width`/`height` (box) or `radius` (circle); `offsetX`/`offsetY` nudge it from center (so `0,0` is centered). In the editor, the Collider panel's **"Auto-fit to sprite"** action snaps the dimensions/offset to the sprite's opaque-pixel bounds (only shown when it isn't already fitted) — a one-time computed value, not a live mode. `isTrigger: true` marks a **sensor** (draws yellow, reads as a pass-through zone for pickup/goal logic); a plain collider reads as a solid wall. Either way the framework does NOT auto-resolve collisions — the collider is data you act on. (Legacy decks carrying `mode: 'auto'` keep their old live sprite-fit for back-compat.) Use it:
 
   ```jsx
   for (const other of scene.getActors()) {
@@ -189,7 +189,7 @@ For HUD text use a behavior's `ui` hook (returns React); for in-world text or sh
 
 - `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.
+- `Brick` behavior: typically just a marker — a plain `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

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

@@ -1,58 +1,204 @@
-import React from 'react';
-import { Panel, SelectField } from '../engine/ui';
+import React, { useState } from 'react';
+import { Icon, NumberField, Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
-import { getColliderRect, intersects } from '../engine/collider';
+import { computeAutoFit, getColliderRect, getColliderShape, intersects } from '../engine/collider';
+import { extensionDefaultProps } from '../engine/behaviorExtensions';
+
+// Collapsible "Dimensions" section. The header row's label lines up exactly with
+// the field labels above/below (both start at the panel body's 16px left pad);
+// the open/closed caret floats in the left gutter without shifting the label.
+// `margin-bottom: 12px` matches a field row's `padding-bottom`, so the gap to
+// the next entry is the same whether the section is open or closed.
+const dimHeaderRowStyle = {
+  position: 'relative',
+  display: 'flex',
+  alignItems: 'center',
+  gap: 10,
+  minHeight: 28,
+  margin: '0 0 12px',
+};
+const dimToggleStyle = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  background: 'none',
+  border: 'none',
+  padding: 0,
+  margin: 0,
+  color: 'var(--castle-inspector-text)',
+  fontFamily: 'inherit',
+  fontSize: 14,
+  cursor: 'pointer',
+};
+// The caret sits in the panel's left gutter (label column starts at x=16).
+const dimCaretStyle = {
+  position: 'absolute',
+  left: -14,
+  top: '50%',
+  transform: 'translateY(-50%)',
+  display: 'inline-flex',
+  alignItems: 'center',
+  fontSize: 11,
+  opacity: 0.65,
+};
+const autoFitLinkStyle = {
+  background: 'none',
+  border: 'none',
+  padding: 0,
+  color: '#4aa3ff',
+  fontFamily: 'inherit',
+  fontSize: 13,
+  cursor: 'pointer',
+};
+const dimBodyStyle = { paddingLeft: 14 };
 
 export class Collider {
   static behaviorName = 'Collider';
 
   static defaultProps = {
-    kind: 'solid',
-    mode: 'auto',
-    width: 50,
-    height: 50,
+    shape: 'box',
+    // width/height/radius are intentionally NOT defaulted: an unset size means
+    // "match the actor's Layout box" (see engine/collider.js manualRect and the
+    // effective values in the inspector). Defaulting them to a fixed number made
+    // every collider shrink to that number instead of tracking the actor.
+    radius: 0,
     offsetX: 0,
     offsetY: 0,
+    // `isTrigger` marks a sensor: it still reports overlaps (draws yellow, reads
+    // as a pass-through zone for pickup/goal logic) but does not block on its
+    // own -- collisions are data you act on. Kit modules can register MORE
+    // Collider fields from outside this file (the physics module adds
+    // bounciness/friction material); see engine/behaviorExtensions.js. That's
+    // why this file is byte-identical across kits -- the physics-only fields
+    // live in physics/extensions/, not here.
+    isTrigger: false,
     debug: false,
+    ...extensionDefaultProps('Collider'),
   };
 
   constructor(props) {
     this.props = props;
   }
 
+  // Seed props when the collider is first added to an actor: snap it to the
+  // sprite's opaque-pixel bounds (what "Auto-fit to sprite" computes) so a new
+  // collider frames the art rather than the whole Layout box. Falls back to the
+  // unset (Layout-box) size when there's nothing to fit to -- no sprite, tile
+  // mode, or transparent art. The editor's addBehavior calls this (see
+  // editors/SceneEditor.jsx initialBehaviorProps).
+  static initialProps(actor, ctx) {
+    const fit = computeAutoFit(actor, ctx?.sprites);
+    return fit ? { ...Collider.defaultProps, ...fit } : { ...Collider.defaultProps };
+  }
+
   draw(actor, scene, ctx, options) {
     if (!options.showDebugColliders && !this.props.debug) return;
-    const rect = getColliderRect(actor, scene.sprites);
-    if (!rect) return;
+    const geom = getColliderShape(actor, scene.sprites);
+    if (!geom) return;
+    // A sensor (isTrigger) reads as a pass-through zone; a solid as a wall.
+    const isSensor = Boolean(this.props.isTrigger) || this.props.kind === 'pickup';
     ctx.save();
-    ctx.strokeStyle = this.props.kind === 'pickup' ? '#ffe17a' : '#8db7ff';
+    ctx.strokeStyle = isSensor ? '#ffe17a' : '#8db7ff';
     ctx.lineWidth = 2;
-    ctx.strokeRect(rect.x + 1, rect.y + 1, rect.width - 2, rect.height - 2);
+    if (geom.shape === 'circle') {
+      ctx.beginPath();
+      ctx.arc(geom.cx, geom.cy, geom.radius, 0, Math.PI * 2);
+      ctx.stroke();
+    } else {
+      ctx.strokeRect(geom.x + 1, geom.y + 1, geom.width - 2, geom.height - 2);
+    }
     ctx.restore();
   }
 
-  static Inspector({ component, setComponent, override }) {
+  static Inspector({ actor, component, sprites, setComponent, override }) {
+    const [dimOpen, setDimOpen] = useState(true);
+    const layout = actor?.components?.Layout ?? {};
+    const shape = component.shape ?? Collider.defaultProps.shape;
+    // Unset width/height/radius track the actor's Layout box; surface that
+    // effective value so a field never reads blank while the collider is sized.
+    const width = component.width ?? layout.width ?? 50;
+    const height = component.height ?? layout.height ?? 50;
+    const effectiveRadius = component.radius > 0 ? component.radius : Math.min(width, height) / 2;
+
+    // "Auto-fit to sprite": the explicit dims/offset that match the sprite's
+    // opaque-pixel bounds. Only offered when the collider isn't already fitted.
+    const autoFit = computeAutoFit(actor, sprites);
+    let autoFitPatch = null;
+    if (autoFit) {
+      autoFitPatch =
+        shape === 'circle'
+          ? { radius: Math.round(Math.min(autoFit.width, autoFit.height) / 2), offsetX: autoFit.offsetX, offsetY: autoFit.offsetY }
+          : { width: autoFit.width, height: autoFit.height, offsetX: autoFit.offsetX, offsetY: autoFit.offsetY };
+    }
+    const currentValue = (key) => {
+      if (key === 'radius') return effectiveRadius;
+      if (key === 'width') return width;
+      if (key === 'height') return height;
+      return component[key] ?? 0;
+    };
+    const alreadyFitted =
+      autoFitPatch && Object.entries(autoFitPatch).every(([key, value]) => Math.abs(currentValue(key) - value) < 0.6);
+
     return (
       <Panel title="Collider" overridden={override?.anyOverridden()}>
         <SelectField
-          label="Kind"
-          value={component.kind}
-          onChange={(kind) => setComponent({ kind: kind })}
-          options={['solid', 'pickup']}
-          {...overrideProps(override, 'kind')}
-        />
-        <SelectField
-          label="Mode"
-          value={component.mode}
-          onChange={(mode) => setComponent({ mode: mode })}
-          options={['auto', 'manual']}
-          {...overrideProps(override, 'mode')}
+          label="Shape"
+          value={component.shape}
+          onChange={(value) => setComponent({ shape: value })}
+          options={['box', 'circle']}
+          {...overrideProps(override, 'shape')}
         />
+        <div style={dimHeaderRowStyle}>
+          <span style={dimCaretStyle}>
+            <Icon name={dimOpen ? 'chevron-down' : 'chevron-right'} />
+          </span>
+          <button type="button" onClick={() => setDimOpen((open) => !open)} style={dimToggleStyle}>
+            Dimensions
+          </button>
+          {autoFitPatch && !alreadyFitted ? (
+            <button type="button" onClick={() => setComponent(autoFitPatch)} style={autoFitLinkStyle}>
+              Auto-fit to sprite
+            </button>
+          ) : null}
+        </div>
+        {dimOpen ? (
+          <div style={dimBodyStyle}>
+            {shape === 'circle' ? (
+              <NumberField
+                label="Radius"
+                value={effectiveRadius}
+                onChange={(value) => setComponent({ radius: value })}
+                {...overrideProps(override, 'radius')}
+              />
+            ) : (
+              <>
+                <NumberField
+                  label="Width"
+                  value={width}
+                  onChange={(value) => setComponent({ width: value })}
+                  {...overrideProps(override, 'width')}
+                />
+                <NumberField
+                  label="Height"
+                  value={height}
+                  onChange={(value) => setComponent({ height: value })}
+                  {...overrideProps(override, 'height')}
+                />
+              </>
+            )}
+            <AutoFields
+              defaultProps={Collider.defaultProps}
+              component={component}
+              setComponent={setComponent}
+              only={['offsetX', 'offsetY']}
+              override={override}
+            />
+          </div>
+        ) : null}
         <AutoFields
           defaultProps={Collider.defaultProps}
           component={component}
           setComponent={setComponent}
-          exclude={['kind', 'mode']}
+          exclude={['shape', 'width', 'height', 'radius', 'offsetX', 'offsetY']}
           override={override}
         />
       </Panel>
@@ -64,4 +210,4 @@ export class Collider {
 // scene (e.g. editors/SelectionOverlay.jsx, which passes the merged preview
 // actors plus the sprites map). See engine/collider.js for the single
 // implementation.
-export { getColliderRect, intersects };
+export { getColliderRect, getColliderShape, intersects };

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

@@ -8,6 +8,9 @@ export class Layout {
     rotation: 0,
     width: 50,
     height: 50,
+    // Show the Layout box (the invisible frame the sprite fills and the collider
+    // derives from) as a dashed outline, in editor and play. Per-actor toggle.
+    debug: false,
   };
 
   // Position/rotation/z never inherit from a blueprint: they're always written
@@ -16,6 +19,13 @@ export class Layout {
   // affects newly placed instances, never moves ones already placed. Because
   // they're always instance-local, they're also never surfaced as blueprint
   // "overrides" in the inspector. width/height default to inherited (absent).
+  //
+  // Size is width/height in card units -- the same space you compose in. A
+  // user-facing scaleX/scaleY (relative to the sprite's native pixels) was
+  // tried and reverted: it only pays off under pixel-perfect (integer scales),
+  // and in today's card-units model it just adds a conversion + couples Layout
+  // to the Sprite. Revisit scale fields when pixel-perfect mode lands. See
+  // ~/castle/cauldron-rendering-scale-model.md.
   static propertyMeta = {
     x: { inherit: false },
     y: { inherit: false },
@@ -26,4 +36,18 @@ export class Layout {
   constructor(props) {
     this.props = props;
   }
+
+  // Outline the Layout box when `debug` is on. Drawn in the actor's own rotated
+  // frame (so it rotates with the actor), with a distinct dashed lavender style
+  // so it reads separately from the solid collider debug and the selection box.
+  draw(actor, scene, ctx) {
+    if (!this.props.debug) return;
+    const { x, y, width, height } = this.props;
+    ctx.save();
+    ctx.strokeStyle = 'rgba(190, 178, 255, 0.75)';
+    ctx.setLineDash([4, 3]);
+    ctx.lineWidth = 1.5;
+    ctx.strokeRect(x + 0.5, y + 0.5, width - 1, height - 1);
+    ctx.restore();
+  }
 }

package/kits/basic-2d/editors/PlayOnly.jsx

@@ -5,20 +5,22 @@ import { useLiveDeckFiles } from '../engine/liveReload';
 import { collectAssets } from '../engine/assets';
 import { ScenePlayer } from '../engine/ScenePlayer';
 import { behaviorClasses } from './behaviorRegistry';
-// Play-mode entry point. Intentionally thin: it locates the start scene and
-// hands it to the engine's `ScenePlayer`, which owns the runtime and input.
-// Deck/game logic belongs in `scenes/` and `behaviors/`, not here.
-// Files are live: scene/drawing edits re-key the player against fresh data;
-// code changes reload this context (see engine/liveReload.js).
-export function PlayOnly() {
+// Play-mode entry point. Plays the scene named by `?scene=<path>` (the shell's
+// Play panel sets this), defaulting to `scenes/main.scene`. It renders ONLY the
+// game — the scene picker lives in the Play panel chrome (the shell), not here,
+// so nothing floats over the game surface and steals input. Files are live:
+// scene/drawing edits re-key the player against fresh data.
+const DEFAULT_SCENE = 'scenes/main.scene';
+
+export function PlayOnly({ initialScene } = {}) {
   const { files, dataVersion } = useLiveDeckFiles();
-  const sceneText = files['scenes/main.scene'] ?? '';
-  const { value: sceneData } = parseJsonFile('scenes/main.scene', sceneText);
+  const scenePath = initialScene && files[initialScene] !== undefined ? initialScene : DEFAULT_SCENE;
+  const { value: sceneData } = parseJsonFile(scenePath, files[scenePath] ?? '');
   if (!sceneData) return null;
   const { sprites } = collectAssets(files);
   return (
     <ScenePlayer
-      key={dataVersion}
+      key={`${scenePath}:${dataVersion}`}
       sceneData={sceneData}
       sprites={sprites}
       files={files}

package/kits/basic-2d/editors/SceneEditor.jsx

@@ -321,7 +321,9 @@ export function SceneEditor({
       const Behavior = findBehaviorClass(behaviorName);
       if (!Behavior) return;
       updateBlueprintTemplate((components) => {
-        components[behaviorName] = { ...Behavior.defaultProps };
+        // The template's own components (Layout/Sprite) are the actor context an
+        // initialProps hook (e.g. Collider auto-fit) reads from.
+        components[behaviorName] = initialBehaviorProps(Behavior, { components }, sprites);
       });
     },
     removeBehavior: (behaviorName) =>
@@ -347,6 +349,8 @@ export function SceneEditor({
     selectedActorIds,
     onSelectActorIds,
     isBlueprintFile,
+    sprites,
+    resolvedActors: previewSceneData?.actors,
   });
   const snapSettings = getSnapSettings(sceneData);
   const stageWrapStyle = {
@@ -464,19 +468,32 @@ export function SceneEditor({
         <div className={styles.sceneWorkspace}>
           <div className={styles.sceneTools}>
             {isBlueprintFile ? null : (
-              <BlueprintLibrary
-                files={files}
-                sprites={sprites}
-                canvasRef={canvasRef}
-                editCameraRef={editCameraRef}
-                isPlaying={isPlaying}
-                selectedBlueprintPath={selectedBlueprintPath}
-                instanceBlueprintPath={rawSelectedActor?.blueprint ?? null}
-                onSelectBlueprint={onSelectBlueprint}
-                onAddActor={onAddActor}
-                dragPlace={dragPlace}
-                onDeleteBlueprint={onDeleteBlueprint}
-              />
+              <>
+                {/* Open (or focus) a Play panel in the shell for this scene.
+                    Lives here in the visible toolbar because the scene editor's
+                    header only renders in the combined editor, not the shell. */}
+                <IconButton
+                  icon="external"
+                  label="Open play preview"
+                  onClick={(event) => {
+                    event.currentTarget.blur();
+                    window.parent.postMessage({ type: 'castle-open-playtest', scene: path }, '*');
+                  }}
+                />
+                <BlueprintLibrary
+                  files={files}
+                  sprites={sprites}
+                  canvasRef={canvasRef}
+                  editCameraRef={editCameraRef}
+                  isPlaying={isPlaying}
+                  selectedBlueprintPath={selectedBlueprintPath}
+                  instanceBlueprintPath={rawSelectedActor?.blueprint ?? null}
+                  onSelectBlueprint={onSelectBlueprint}
+                  onAddActor={onAddActor}
+                  dragPlace={dragPlace}
+                  onDeleteBlueprint={onDeleteBlueprint}
+                />
+              </>
             )}
           </div>
           <div className={styles.stageWrap} style={stageWrapStyle}>
@@ -601,6 +618,10 @@ export function SceneEditor({
 }
 // Header-right playback controls, in the mockup's order: Undo, Redo, Play.
 // Play stays a play/stop toggle. Duplicate/remove live on the on-canvas toolbar.
+// "Open preview" asks the shell (parent window) to open/focus a Play panel for
+// THIS scene -- a separate, persistent preview alongside the editor (vs the
+// in-panel play toggle). Defaults to an already-open preview for this scene,
+// else opens a new one (handled shell-side, keyed by scene).
 function HeaderPlaybackButtons({ isPlaying, setIsPlaying, history }) {
   return (
     <>
@@ -638,7 +659,17 @@ function HeaderPlaybackButtons({ isPlaying, setIsPlaying, history }) {
 // remove-behavior stay whole-component operations straight against the
 // instance's own sparse `components` -- there's no per-property baseline to
 // diff when a component doesn't exist on one side at all.
-function makeSceneActions({ sceneData, files, serialize, commit, selectedActorIds, onSelectActorIds, isBlueprintFile }) {
+// Props to seed a behavior with when it's freshly added to `actor`. A behavior
+// may define `static initialProps(actor, { sprites })` to derive props from the
+// actor it lands on (e.g. Collider snaps to the sprite's opaque-pixel bounds);
+// otherwise it starts from `defaultProps`. `actor` is the resolved actor
+// (Layout/Sprite merged) or, for a blueprint template, `{ components }`.
+function initialBehaviorProps(Behavior, actor, sprites) {
+  if (Behavior.initialProps && actor) return Behavior.initialProps(actor, { sprites });
+  return { ...Behavior.defaultProps };
+}
+
+function makeSceneActions({ sceneData, files, serialize, commit, selectedActorIds, onSelectActorIds, isBlueprintFile, sprites, resolvedActors }) {
   function commitScene(next, options) {
     commit(serialize(next), options);
   }
@@ -650,8 +681,9 @@ function makeSceneActions({ sceneData, files, serialize, commit, selectedActorId
     addBehavior: (actorId, behaviorName) => {
       const Behavior = findBehaviorClass(behaviorName);
       if (!Behavior) return;
+      const resolved = resolvedActors?.find((actor) => actor.id === actorId);
       commitScene(
-        setActorComponent(sceneData, actorId, behaviorName, { ...Behavior.defaultProps })
+        setActorComponent(sceneData, actorId, behaviorName, initialBehaviorProps(Behavior, resolved, sprites))
       );
     },
     removeBehavior: (actorId, behaviorName) =>
@@ -1565,6 +1597,7 @@ function ActorInspector({
             actor={selectedActor}
             component={component}
             files={files}
+            sprites={sprites}
             setComponent={setComponent}
             override={override}
           />

package/kits/basic-2d/editors/SelectionOverlay.jsx

@@ -1,5 +1,5 @@
 import React, { useCallback, useEffect, useRef, useState } from 'react';
-import { getColliderRect } from '../behaviors/Collider';
+import { getColliderShape } from '../behaviors/Collider';
 import { cardSize, screenToCard } from '../engine/scene';
 import { cx, Icon, styles, useElementSize } from '../engine/ui';
 
@@ -216,13 +216,14 @@ export function SelectionOverlay({
               key={collider.actorId}
               className={cx(
                 styles.selColliderBox,
-                collider.kind === 'pickup' && styles.selColliderPickup
+                collider.isTrigger && styles.selColliderPickup
               )}
               style={{
                 left: collider.x,
                 top: collider.y,
                 width: collider.width,
                 height: collider.height,
+                borderRadius: collider.shape === 'circle' ? '50%' : undefined,
                 transformOrigin: `${collider.originX}px ${collider.originY}px`,
                 transform: `rotate(${collider.rotation}deg)`,
               }}
@@ -463,18 +464,27 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
     .map((actor) => {
       const layout = actor.components.Layout;
       const collider = actor.components.Collider;
-      const rect = getColliderRect(actor, sprites);
-      if (!layout || !collider || !rect) return null;
+      const geom = getColliderShape(actor, sprites);
+      if (!layout || !collider || !geom) return null;
+      // For a circle we render a radius-sized square with border-radius; for a
+      // box, the rect itself. Both come from the shared geometry so the preview
+      // matches the physics body exactly (shape, radius, offset, auto/manual).
+      const isCircle = geom.shape === 'circle';
+      const x = isCircle ? geom.cx - geom.radius : geom.x;
+      const y = isCircle ? geom.cy - geom.radius : geom.y;
+      const width = isCircle ? geom.radius * 2 : geom.width;
+      const height = isCircle ? geom.radius * 2 : geom.height;
       return {
         actorId: actor.id,
-        kind: collider.kind,
-        x: rect.x,
-        y: rect.y,
-        width: rect.width,
-        height: rect.height,
+        shape: geom.shape,
+        isTrigger: Boolean(collider.isTrigger) || collider.kind === 'pickup',
+        x,
+        y,
+        width,
+        height,
         rotation: layout.rotation ?? 0,
-        originX: layout.x + layout.width / 2 - rect.x,
-        originY: layout.y + layout.height / 2 - rect.y,
+        originX: layout.x + layout.width / 2 - x,
+        originY: layout.y + layout.height / 2 - y,
       };
     })
     .filter(Boolean);

package/kits/basic-2d/editors/behaviorRegistry.js

@@ -1,6 +1,12 @@
-// Discover every behavior class from `behaviors/*.tsx`. Vite HMR is off, so a
-// newly-added behavior file is picked up on the next reload/restart.
-const modules = import.meta.glob('../behaviors/*.jsx', { eager: true });
+// Discover every behavior class from `behaviors/*.jsx` and the physics module's
+// `physics/behaviors/*.jsx`. Vite HMR is off, so a newly-added behavior file is
+// picked up on the next reload/restart. The physics glob is what lets the
+// self-contained physics module ship its behaviors without polluting the core
+// `behaviors/` folder — a kit adopts physics by copying `physics/` in.
+const modules = {
+  ...import.meta.glob('../behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('../physics/behaviors/*.jsx', { eager: true }),
+};
 function isBehaviorClass(value) {
   return typeof value === 'function' && typeof value.behaviorName === 'string';
 }

package/kits/basic-2d/engine/behaviorExtensions.js

@@ -0,0 +1,28 @@
+// Behavior field extensions. A self-contained kit module (like `physics/`) can
+// add fields to a behavior defined in the shared core WITHOUT editing that
+// behavior's file -- so the core behavior stays byte-identical across kits and
+// the module owns its own additions. Each extension module under any
+// `<module>/extensions/*.js` exports:
+//
+//   export const behaviorExtension = {
+//     behaviorName: 'Collider',
+//     defaultProps: { bounciness: 0, friction: 0.1 },
+//   };
+//
+// A behavior folds its registered extensions into its own `defaultProps` (see
+// behaviors/Collider.jsx `...extensionDefaultProps('Collider')`); the inspector
+// already renders leftover defaultProps generically, so registered fields show
+// up with no inspector change. Empty in a kit with no `*/extensions/` dir (e.g.
+// basic-2d). Symmetric with engine/systemRegistry.js and editors/behaviorRegistry.js.
+const modules = import.meta.glob('../*/extensions/*.js', { eager: true });
+const extensions = Object.values(modules)
+  .map((mod) => mod.behaviorExtension)
+  .filter(Boolean);
+
+// Merged defaultProps that registered extensions contribute to `behaviorName`
+// (empty object when none). Later extensions win on a key collision.
+export function extensionDefaultProps(behaviorName) {
+  return extensions
+    .filter((ext) => ext.behaviorName === behaviorName)
+    .reduce((acc, ext) => ({ ...acc, ...ext.defaultProps }), {});
+}

package/kits/basic-2d/engine/collider.js

@@ -113,13 +113,16 @@ function manualRect(layout, collider) {
 
 const fullLayoutRect = (layout) => ({ x: layout.x, y: layout.y, width: layout.width, height: layout.height });
 
-// The un-offset rect for whichever mode is active: `manualRect` for
-// `mode: 'manual'`, otherwise the auto sprite-bbox rect (or its Layout-box
-// fallback).
+// The un-offset rect. Colliders are sized by their explicit `width`/`height`
+// (the "auto vs manual" mode is gone -- use the inspector's "Auto-fit to sprite"
+// action to snap those to the sprite). Legacy decks that still carry
+// `mode: 'auto'` keep their dynamic sprite fit for back-compat.
 function modeRect(layout, collider, spriteProps, sprites) {
-  if ((collider.mode ?? 'auto') === 'manual') return manualRect(layout, collider);
-  const sprite = spriteProps ? sprites?.[spriteProps.file] : null;
-  return autoRect(layout, spriteProps, sprite) ?? fullLayoutRect(layout);
+  if (collider.mode === 'auto') {
+    const sprite = spriteProps ? sprites?.[spriteProps.file] : null;
+    return autoRect(layout, spriteProps, sprite) ?? fullLayoutRect(layout);
+  }
+  return manualRect(layout, collider);
 }
 
 // The Collider rect for an actor, from its Layout + Collider (+ Sprite, for
@@ -141,6 +144,57 @@ export function getColliderRect(actor, sprites) {
   };
 }
 
+// Full collider geometry: the AABB rect (`x/y/width/height`, offset-applied)
+// PLUS the shape and, for circles, the center + radius. This is the SINGLE
+// SOURCE OF TRUTH for collider shape -- the physics body (matterBridge), the
+// play-mode debug draw (Collider.draw), and the editor selection overlay all
+// derive their geometry from here, so the visual preview always matches the
+// simulated collider. `radius` of 0 means "derive from the rect" (min side / 2),
+// so a circle shows a real size even before you set an explicit radius.
+export function getColliderShape(actor, sprites) {
+  const rect = getColliderRect(actor, sprites);
+  if (!rect) return null;
+  const collider = actor.components.Collider;
+  const shape = collider.shape === 'circle' ? 'circle' : 'box';
+  const radius = collider.radius > 0 ? collider.radius : Math.min(rect.width, rect.height) / 2;
+  return {
+    shape,
+    x: rect.x,
+    y: rect.y,
+    width: rect.width,
+    height: rect.height,
+    cx: rect.x + rect.width / 2,
+    cy: rect.y + rect.height / 2,
+    radius,
+  };
+}
+
+// The explicit `width`/`height`/`offsetX`/`offsetY` a collider would need to
+// exactly match its sprite's opaque-pixel fit -- what "auto" used to compute
+// dynamically. Returns null when there's nothing to fit to (no Sprite, tile
+// mode, or fully transparent art). Powers the inspector's "Auto-fit to sprite".
+export function computeAutoFit(actor, sprites) {
+  const rawLayout = actor?.components?.Layout;
+  const spriteProps = actor?.components?.Sprite;
+  if (!rawLayout || !spriteProps) return null;
+  // Blueprint templates omit x/y (position is instance-local). x/y cancel out of
+  // the offset delta below, so default them to 0 -- otherwise an undefined x/y
+  // (auto-fitting a template, e.g. on add) turns the offsets into NaN.
+  const layout = { ...rawLayout, x: rawLayout.x ?? 0, y: rawLayout.y ?? 0 };
+  const rect = autoRect(layout, spriteProps, sprites?.[spriteProps.file]);
+  if (!rect || rect.width <= 0 || rect.height <= 0) return null;
+  // manualRect centers a width x height box in the Layout box; the offset is the
+  // delta from that centered position to the sprite-fit rect.
+  const centeredX = layout.x + (layout.width - rect.width) / 2;
+  const centeredY = layout.y + (layout.height - rect.height) / 2;
+  return {
+    width: Math.round(rect.width),
+    height: Math.round(rect.height),
+    offsetX: Math.round(rect.x - centeredX),
+    offsetY: Math.round(rect.y - centeredY),
+  };
+}
+
 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;
 }

package/kits/basic-2d/engine/scene.js

@@ -1,6 +1,7 @@
 import { initialFiles, parseJsonFile } from './files';
 import { getBlueprintTemplate, mergeComponents } from './blueprint';
 import { getColliderRect, intersects, spriteIsEmpty } from './collider';
+import { systemInstallers } from './systemRegistry';
 
 const CARD_WIDTH = 500;
 const CARD_HEIGHT = 700;
@@ -42,9 +43,21 @@ export class SceneRuntime {
     this.actors = new Map();
     this.camera = undefined;
     this.status = undefined;
+    // Registered systems run once per frame after all behavior `update`s (see
+    // `update`). A system is a plain object with an optional
+    // `afterBehaviors(scene, dt)` hook; kits register systems from `systems/*.js`
+    // (see makeScene), so the engine core stays decoupled from any specific one.
+    this.systems = [];
     this.load(sceneData);
   }
 
+  // Register a per-frame system (e.g. a physics simulation). Systems step in
+  // registration order, after behaviors, every `update`. Returns the system.
+  registerSystem(system) {
+    this.systems.push(system);
+    return system;
+  }
+
   load(sceneData) {
     this.data = structuredClone(sceneData);
     this.actors = new Map();
@@ -88,7 +101,9 @@ export class SceneRuntime {
   }
 
   clone() {
-    return new SceneRuntime(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
+    // Route through makeScene so the clone gets the same registered systems as a
+    // freshly-made runtime.
+    return makeScene(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
   }
 
   serialize() {
@@ -190,6 +205,12 @@ export class SceneRuntime {
     for (const actor of this.getActors()) {
       this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
     }
+    // Behaviors have expressed their intent (velocities, forces) for this frame;
+    // now let registered systems advance (e.g. physics integrates, writes results
+    // back to Layout, and dispatches collision callbacks).
+    for (const system of this.systems) {
+      system.afterBehaviors?.(this, dt);
+    }
   }
 
   forEachBehavior(actor, callback) {
@@ -299,7 +320,12 @@ export class SceneRuntime {
 }
 
 export function makeScene(sceneData, behaviors, sprites, files) {
-  return new SceneRuntime(sceneData, behaviors, sprites, files);
+  const runtime = new SceneRuntime(sceneData, behaviors, sprites, files);
+  // Install any runtime systems the kit provides (systems/*.js) -- no-op in a kit
+  // with none. A system's engine is created lazily on first use, so draw-only
+  // editor previews (which never call update) stay free.
+  for (const install of systemInstallers) install(runtime);
+  return runtime;
 }
 
 export function setActorComponent(sceneData, actorId, behaviorName, nextProps) {

package/kits/basic-2d/engine/systemRegistry.js

@@ -0,0 +1,12 @@
+// Discover per-frame runtime systems from `systems/*.js`. Each such module
+// exports `installSystem(runtime)`, which is called once for every created
+// SceneRuntime (see engine/scene.js `makeScene`) to register itself via
+// `runtime.registerSystem(...)`. A system is a plain object with an optional
+// `afterBehaviors(scene, dt)` hook, run once per frame after all behavior
+// updates. Empty in a kit with no `systems/` dir (e.g. basic-2d); a kit adds a
+// system by dropping a file here -- no edits to the engine required. Symmetric
+// with editors/behaviorRegistry.js.
+const modules = import.meta.glob('../systems/*.js', { eager: true });
+export const systemInstallers = Object.values(modules)
+  .map((mod) => mod.installSystem)
+  .filter((fn) => typeof fn === 'function');

package/kits/basic-2d/engine/ui.jsx

@@ -13,6 +13,7 @@ import {
   faCode,
   faCodeBranch,
   faEraser,
+  faExternalLinkAlt,
   faEyeDropper,
   faFile,
   faFilm,
@@ -179,6 +180,7 @@ const icons = {
   // FA5 has no faCodeFork (that's the FA6 name); faCodeBranch is the fork glyph.
   'code-fork': faCodeBranch,
   eraser: faEraser,
+  external: faExternalLinkAlt,
   eyedropper: faEyeDropper,
   fill: faFillDrip,
   'flip-h': faArrowsAltH,

package/kits/basic-2d/main.jsx

@@ -15,9 +15,10 @@ if (!root) throw new Error('Missing root element');
 //   ?file=<path>[&editor=<id>] -> a single rich editor for that file
 const params = new URLSearchParams(window.location.search);
 function pick() {
-  if (!isEdit()) return <PlayOnly />;
+  const initialScene = params.get('scene') ?? undefined;
+  if (!isEdit()) return <PlayOnly initialScene={initialScene} />;
   const file = params.get('file');
   if (file) return <SingleEditor path={file} editor={params.get('editor') ?? undefined} />;
-  return <PlayOnly />;
+  return <PlayOnly initialScene={initialScene} />;
 }
 createRoot(root).render(<ErrorBoundary>{pick()}</ErrorBoundary>);

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

@@ -2,6 +2,7 @@ import React, { useState } from 'react';
 import { Icon, NumberField, Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
 import { computeAutoFit, getColliderRect, getColliderShape, intersects } from '../engine/collider';
+import { extensionDefaultProps } from '../engine/behaviorExtensions';
 
 // Collapsible "Dimensions" section. The header row's label lines up exactly with
 // the field labels above/below (both start at the panel body's 16px left pad);
@@ -62,20 +63,33 @@ export class Collider {
     radius: 0,
     offsetX: 0,
     offsetY: 0,
-    // Physics material (used by the physics simulation; ignored by plain
-    // scene.overlaps checks). `isTrigger` = a sensor: detects overlaps but
-    // doesn't block. `bounciness` = restitution (0..1+). `friction` = surface
-    // friction.
+    // `isTrigger` marks a sensor: it still reports overlaps (draws yellow, reads
+    // as a pass-through zone for pickup/goal logic) but does not block on its
+    // own -- collisions are data you act on. Kit modules can register MORE
+    // Collider fields from outside this file (the physics module adds
+    // bounciness/friction material); see engine/behaviorExtensions.js. That's
+    // why this file is byte-identical across kits -- the physics-only fields
+    // live in physics/extensions/, not here.
     isTrigger: false,
-    bounciness: 0,
-    friction: 0.1,
     debug: false,
+    ...extensionDefaultProps('Collider'),
   };
 
   constructor(props) {
     this.props = props;
   }
 
+  // Seed props when the collider is first added to an actor: snap it to the
+  // sprite's opaque-pixel bounds (what "Auto-fit to sprite" computes) so a new
+  // collider frames the art rather than the whole Layout box. Falls back to the
+  // unset (Layout-box) size when there's nothing to fit to -- no sprite, tile
+  // mode, or transparent art. The editor's addBehavior calls this (see
+  // editors/SceneEditor.jsx initialBehaviorProps).
+  static initialProps(actor, ctx) {
+    const fit = computeAutoFit(actor, ctx?.sprites);
+    return fit ? { ...Collider.defaultProps, ...fit } : { ...Collider.defaultProps };
+  }
+
   draw(actor, scene, ctx, options) {
     if (!options.showDebugColliders && !this.props.debug) return;
     const geom = getColliderShape(actor, scene.sprites);

package/kits/physics-2d/editors/SceneEditor.jsx

@@ -321,7 +321,9 @@ export function SceneEditor({
       const Behavior = findBehaviorClass(behaviorName);
       if (!Behavior) return;
       updateBlueprintTemplate((components) => {
-        components[behaviorName] = { ...Behavior.defaultProps };
+        // The template's own components (Layout/Sprite) are the actor context an
+        // initialProps hook (e.g. Collider auto-fit) reads from.
+        components[behaviorName] = initialBehaviorProps(Behavior, { components }, sprites);
       });
     },
     removeBehavior: (behaviorName) =>
@@ -347,6 +349,8 @@ export function SceneEditor({
     selectedActorIds,
     onSelectActorIds,
     isBlueprintFile,
+    sprites,
+    resolvedActors: previewSceneData?.actors,
   });
   const snapSettings = getSnapSettings(sceneData);
   const stageWrapStyle = {
@@ -655,7 +659,17 @@ function HeaderPlaybackButtons({ isPlaying, setIsPlaying, history }) {
 // remove-behavior stay whole-component operations straight against the
 // instance's own sparse `components` -- there's no per-property baseline to
 // diff when a component doesn't exist on one side at all.
-function makeSceneActions({ sceneData, files, serialize, commit, selectedActorIds, onSelectActorIds, isBlueprintFile }) {
+// Props to seed a behavior with when it's freshly added to `actor`. A behavior
+// may define `static initialProps(actor, { sprites })` to derive props from the
+// actor it lands on (e.g. Collider snaps to the sprite's opaque-pixel bounds);
+// otherwise it starts from `defaultProps`. `actor` is the resolved actor
+// (Layout/Sprite merged) or, for a blueprint template, `{ components }`.
+function initialBehaviorProps(Behavior, actor, sprites) {
+  if (Behavior.initialProps && actor) return Behavior.initialProps(actor, { sprites });
+  return { ...Behavior.defaultProps };
+}
+
+function makeSceneActions({ sceneData, files, serialize, commit, selectedActorIds, onSelectActorIds, isBlueprintFile, sprites, resolvedActors }) {
   function commitScene(next, options) {
     commit(serialize(next), options);
   }
@@ -667,8 +681,9 @@ function makeSceneActions({ sceneData, files, serialize, commit, selectedActorId
     addBehavior: (actorId, behaviorName) => {
       const Behavior = findBehaviorClass(behaviorName);
       if (!Behavior) return;
+      const resolved = resolvedActors?.find((actor) => actor.id === actorId);
       commitScene(
-        setActorComponent(sceneData, actorId, behaviorName, { ...Behavior.defaultProps })
+        setActorComponent(sceneData, actorId, behaviorName, initialBehaviorProps(Behavior, resolved, sprites))
       );
     },
     removeBehavior: (actorId, behaviorName) =>

package/kits/physics-2d/engine/behaviorExtensions.js

@@ -0,0 +1,28 @@
+// Behavior field extensions. A self-contained kit module (like `physics/`) can
+// add fields to a behavior defined in the shared core WITHOUT editing that
+// behavior's file -- so the core behavior stays byte-identical across kits and
+// the module owns its own additions. Each extension module under any
+// `<module>/extensions/*.js` exports:
+//
+//   export const behaviorExtension = {
+//     behaviorName: 'Collider',
+//     defaultProps: { bounciness: 0, friction: 0.1 },
+//   };
+//
+// A behavior folds its registered extensions into its own `defaultProps` (see
+// behaviors/Collider.jsx `...extensionDefaultProps('Collider')`); the inspector
+// already renders leftover defaultProps generically, so registered fields show
+// up with no inspector change. Empty in a kit with no `*/extensions/` dir (e.g.
+// basic-2d). Symmetric with engine/systemRegistry.js and editors/behaviorRegistry.js.
+const modules = import.meta.glob('../*/extensions/*.js', { eager: true });
+const extensions = Object.values(modules)
+  .map((mod) => mod.behaviorExtension)
+  .filter(Boolean);
+
+// Merged defaultProps that registered extensions contribute to `behaviorName`
+// (empty object when none). Later extensions win on a key collision.
+export function extensionDefaultProps(behaviorName) {
+  return extensions
+    .filter((ext) => ext.behaviorName === behaviorName)
+    .reduce((acc, ext) => ({ ...acc, ...ext.defaultProps }), {});
+}

package/kits/physics-2d/engine/collider.js

@@ -174,9 +174,13 @@ export function getColliderShape(actor, sprites) {
 // dynamically. Returns null when there's nothing to fit to (no Sprite, tile
 // mode, or fully transparent art). Powers the inspector's "Auto-fit to sprite".
 export function computeAutoFit(actor, sprites) {
-  const layout = actor?.components?.Layout;
+  const rawLayout = actor?.components?.Layout;
   const spriteProps = actor?.components?.Sprite;
-  if (!layout || !spriteProps) return null;
+  if (!rawLayout || !spriteProps) return null;
+  // Blueprint templates omit x/y (position is instance-local). x/y cancel out of
+  // the offset delta below, so default them to 0 -- otherwise an undefined x/y
+  // (auto-fitting a template, e.g. on add) turns the offsets into NaN.
+  const layout = { ...rawLayout, x: rawLayout.x ?? 0, y: rawLayout.y ?? 0 };
   const rect = autoRect(layout, spriteProps, sprites?.[spriteProps.file]);
   if (!rect || rect.width <= 0 || rect.height <= 0) return null;
   // manualRect centers a width x height box in the Layout box; the offset is the

package/kits/physics-2d/engine/scene.js

@@ -1,7 +1,7 @@
 import { initialFiles, parseJsonFile } from './files';
 import { getBlueprintTemplate, mergeComponents } from './blueprint';
-import { installPhysics } from '../physics';
 import { getColliderRect, intersects, spriteIsEmpty } from './collider';
+import { systemInstallers } from './systemRegistry';
 
 const CARD_WIDTH = 500;
 const CARD_HEIGHT = 700;
@@ -45,14 +45,13 @@ export class SceneRuntime {
     this.status = undefined;
     // Registered systems run once per frame after all behavior `update`s (see
     // `update`). A system is a plain object with an optional
-    // `afterBehaviors(scene, dt)` hook; this is the seam the physics module
-    // plugs into so it stays decoupled from the core runtime and portable to
-    // other kits.
+    // `afterBehaviors(scene, dt)` hook; kits register systems from `systems/*.js`
+    // (see makeScene), so the engine core stays decoupled from any specific one.
     this.systems = [];
     this.load(sceneData);
   }
 
-  // Register a per-frame system (e.g. the physics simulation). Systems step in
+  // Register a per-frame system (e.g. a physics simulation). Systems step in
   // registration order, after behaviors, every `update`. Returns the system.
   registerSystem(system) {
     this.systems.push(system);
@@ -102,8 +101,8 @@ export class SceneRuntime {
   }
 
   clone() {
-    // Route through makeScene so the clone gets the same registered systems
-    // (physics) as a freshly-made runtime.
+    // Route through makeScene so the clone gets the same registered systems as a
+    // freshly-made runtime.
     return makeScene(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
   }
 
@@ -206,9 +205,9 @@ export class SceneRuntime {
     for (const actor of this.getActors()) {
       this.forEachBehavior(actor, (instance) => instance.update?.(actor, this, dt));
     }
-    // Behaviors have expressed their intent (velocities, forces) for this
-    // frame; now let registered systems advance (physics integrates, writes
-    // results back to Layout, and dispatches collision callbacks).
+    // Behaviors have expressed their intent (velocities, forces) for this frame;
+    // now let registered systems advance (e.g. physics integrates, writes results
+    // back to Layout, and dispatches collision callbacks).
     for (const system of this.systems) {
       system.afterBehaviors?.(this, dt);
     }
@@ -322,10 +321,10 @@ export class SceneRuntime {
 
 export function makeScene(sceneData, behaviors, sprites, files) {
   const runtime = new SceneRuntime(sceneData, behaviors, sprites, files);
-  // Physics is a self-contained module registered as a runtime system. The
-  // matter engine is created lazily on the first simulation step, so draw-only
+  // Install any runtime systems the kit provides (systems/*.js) -- no-op in a kit
+  // with none. A system's engine is created lazily on first use, so draw-only
   // editor previews (which never call update) stay free.
-  installPhysics(runtime);
+  for (const install of systemInstallers) install(runtime);
   return runtime;
 }
 

package/kits/physics-2d/engine/systemRegistry.js

@@ -0,0 +1,12 @@
+// Discover per-frame runtime systems from `systems/*.js`. Each such module
+// exports `installSystem(runtime)`, which is called once for every created
+// SceneRuntime (see engine/scene.js `makeScene`) to register itself via
+// `runtime.registerSystem(...)`. A system is a plain object with an optional
+// `afterBehaviors(scene, dt)` hook, run once per frame after all behavior
+// updates. Empty in a kit with no `systems/` dir (e.g. basic-2d); a kit adds a
+// system by dropping a file here -- no edits to the engine required. Symmetric
+// with editors/behaviorRegistry.js.
+const modules = import.meta.glob('../systems/*.js', { eager: true });
+export const systemInstallers = Object.values(modules)
+  .map((mod) => mod.installSystem)
+  .filter((fn) => typeof fn === 'function');

package/kits/physics-2d/physics/extensions/collider.js

@@ -0,0 +1,15 @@
+// Physics contributes material fields to the shared Collider behavior WITHOUT
+// editing behaviors/Collider.jsx -- that file stays identical to basic-2d's, so
+// the drift check treats it as a converged shared file. These fields are read
+// by the physics simulation (see physics/matterBridge.js); a kit without the
+// physics module never registers them, so its Collider has no material fields.
+// See engine/behaviorExtensions.js for how this is discovered.
+export const behaviorExtension = {
+  behaviorName: 'Collider',
+  defaultProps: {
+    // `bounciness` = restitution: 0 (dead) to ~1 (very bouncy); can exceed 1.
+    bounciness: 0,
+    // `friction` = surface friction.
+    friction: 0.1,
+  },
+};

package/kits/physics-2d/systems/physics.js

@@ -0,0 +1,8 @@
+// Registers the physics simulation as a runtime system. Auto-discovered by
+// engine/systemRegistry.js (`systems/*.js`) and invoked by makeScene, so the
+// physics module plugs in without the shared engine ever referencing it.
+import { installPhysics } from '../physics';
+
+export function installSystem(runtime) {
+  installPhysics(runtime);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.85",
+  "version": "0.4.86",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"