castle-web-cli 0.4.94 → 0.4.96

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

@@ -1,3 +1,4 @@
+import { resolveDeckFile } from 'castle-web-sdk';
 import React from 'react';
 import { frameCount, renderSpriteFrame } from '../engine/pxart';
 import { renderSmoothSpriteFrame } from '../engine/pxartSmooth';
@@ -37,7 +38,11 @@ export class Sprite {
   }
 
   resolveSprite(scene) {
-    return scene.sprites?.[this.props.file] ?? scene.sprites?.[FALLBACK_FILE] ?? null;
+    // `drawings/x.pxart` is this deck's; `@imports/<alias>/drawings/x.pxart` is
+    // an import's. (A value inherited from an imported blueprint arrives already
+    // resolved against that blueprint's deck -- see engine/blueprint.js.)
+    const file = resolveDeckFile(this.props.file);
+    return scene.sprites?.[file] ?? scene.sprites?.[FALLBACK_FILE] ?? null;
   }
 
   update(actor, scene, dt) {

package/kits/physics-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": "ckRZGFW4iPrx",
+  "cardId": "_oBFbAW6DxsO",
+  "title": "physics-2d",
+  "publishedVersion": "2026-07-28T17:50:39.741Z"
 }

package/kits/physics-2d/drawings/joint-rope.pxart

@@ -0,0 +1,26 @@
+{
+  "format": "compact",
+  "palette": {
+    "a": "#8a4836",
+    "b": "#bf6f4a",
+    "c": "#e69c69"
+  },
+  "grid": [
+    "................",
+    "................",
+    "................",
+    "..cc........cc..",
+    ".b..b......b..b.",
+    "a....a....a....a",
+    "......a..a......",
+    ".......aa.......",
+    ".......aa.......",
+    "......a..a......",
+    "a....a....a....a",
+    ".b..b......b..b.",
+    "..cc........cc..",
+    "................",
+    "................",
+    "................"
+  ]
+}

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

@@ -161,6 +161,27 @@ export function SceneEditor({
   const editCameraRef = useRef(reloadStash?.editCamera ?? { x: 0, y: 0, zoom: 1 });
   const selectedActorIdsRef = useRef(selectedActorIds);
   selectedActorIdsRef.current = selectedActorIds;
+  // Transient "click an actor to pick it" mode, triggered by an inspector field
+  // (e.g. Joint's target picker). Holds `{ onPick }`; the next edit-canvas click
+  // resolves it with the clicked actor's id instead of selecting. A ref mirror
+  // lets the pointer gesture read it live without re-creating handlers.
+  const [pickRequest, setPickRequest] = useState(null);
+  const pickRequestRef = useRef(null);
+  pickRequestRef.current = pickRequest;
+  const beginPick = useCallback((onPick) => setPickRequest(onPick ? { onPick } : null), []);
+  useEffect(() => {
+    if (!pickRequest) return undefined;
+    const onKey = (e) => e.key === 'Escape' && setPickRequest(null);
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [pickRequest]);
+  // Which Collider shape the inspector has selected, so the on-canvas overlay can
+  // highlight it. The Collider inspector reports its index up via onSelectShape.
+  // A ref mirror feeds the draw loop (blueprint-lit instances highlight via the
+  // canvas draw); the SelectionOverlay reads the state directly.
+  const [colliderShapeSel, setColliderShapeSel] = useState(0);
+  const colliderShapeSelRef = useRef(colliderShapeSel);
+  colliderShapeSelRef.current = colliderShapeSel;
   const [isPlaying, setIsPlaying] = useState(reloadStash?.isPlaying ?? false);
   // Hotbar blueprint selection (tap a slot -> inspect/edit the blueprint in
   // the sidebar; drag remains the placement gesture). Mutually exclusive with
@@ -239,9 +260,19 @@ export function SceneEditor({
     marqueeRef,
     selectedActorIdsRef,
     selectedBlueprintPathRef,
+    colliderShapeSelRef,
   });
   const panGesture = usePanGesture({ canvasRef, editCameraRef, isPlaying });
   useScenePlayKeys(runtimeRef);
+  // Resolve an in-progress target pick: a click on the owner itself is ignored
+  // (a self-joint is meaningless); a click on empty space cancels.
+  const onPickTarget = (actorId) => {
+    const req = pickRequestRef.current;
+    if (!req) return;
+    if (actorId && actorId === selectedActorIdsRef.current[0]) return;
+    setPickRequest(null);
+    if (actorId) req.onPick(actorId);
+  };
   const gesture = useSelectionGesture({
     canvasRef,
     sceneData,
@@ -254,6 +285,8 @@ export function SceneEditor({
     onSetMultiSelectMode,
     marqueeRef,
     editCameraRef,
+    pickRequestRef,
+    onPickTarget,
     applyScene: (next) => onChange(serialize(next)),
     recordSceneSnapshot: history.recordSnapshot,
   });
@@ -549,6 +582,7 @@ export function SceneEditor({
                   previewSceneData={previewSceneData}
                   sprites={sprites}
                   selectedActorIds={selectedActorIds}
+                  selectedColliderShape={colliderShapeSel}
                   snap={snapSettings}
                   onArrange={isBlueprintFile ? undefined : actions.arrangeSelection}
                   onClone={isBlueprintFile ? undefined : actions.duplicateSelection}
@@ -594,6 +628,7 @@ export function SceneEditor({
                   onSetComponent={blueprintActions.setComponent}
                   onAddBehavior={blueprintActions.addBehavior}
                   onRemoveBehavior={blueprintActions.removeBehavior}
+                  onSelectShape={setColliderShapeSel}
                 />
               ) : showMulti ? (
                 <MultiSelectInspector
@@ -622,6 +657,9 @@ export function SceneEditor({
                       ? undefined
                       : () => onSelectBlueprint(rawSelectedActor.blueprint)
                   }
+                  onBeginPick={beginPick}
+                  pickActive={Boolean(pickRequest)}
+                  onSelectShape={setColliderShapeSel}
                 />
               ) : (
                 <SceneInspector
@@ -800,6 +838,13 @@ function useSelectionGesture(args) {
     const stack = scene.actorsAt(point.x, point.y);
     const stackIds = stack.map((a) => a.id);
     const actor = stack[0] ?? null;
+    // Target-pick mode swallows this click: resolve the pick with the clicked
+    // actor (or cancel on empty space) instead of selecting/dragging.
+    if (current.pickRequestRef?.current) {
+      current.canvasRef.current.releasePointerCapture?.(event.pointerId);
+      current.onPickTarget(actor?.id ?? null);
+      return;
+    }
     const drag = {
       pointerId: event.pointerId,
       startPoint: point,
@@ -1339,6 +1384,7 @@ function useScenePlayLoop({
   marqueeRef,
   selectedActorIdsRef,
   selectedBlueprintPathRef,
+  colliderShapeSelRef,
 }) {
   // Spin up / tear down the play-mode runtime as the user toggles play. `text`
   // is the stable identity for `sceneData` (which is re-parsed every render);
@@ -1398,6 +1444,9 @@ function useScenePlayLoop({
           useCamera: true,
           editPlaceholders: !isPlaying,
           dimBlueprintPath: isPlaying ? null : selectedBlueprintPathRef.current,
+          // Highlight the collider shape the blueprint inspector has selected on
+          // its lit instances.
+          colliderShapeSel: isPlaying ? -1 : colliderShapeSelRef?.current ?? -1,
         });
       }
       raf = requestAnimationFrame(frame);
@@ -1415,6 +1464,7 @@ function useScenePlayLoop({
     marqueeRef,
     selectedActorIdsRef,
     selectedBlueprintPathRef,
+    colliderShapeSelRef,
   ]);
 }
 function useScenePlayKeys(runtimeRef) {
@@ -1523,6 +1573,7 @@ function BlueprintInspector({
   onSetComponent,
   onAddBehavior,
   onRemoveBehavior,
+  onSelectShape,
 }) {
   const templateActor = { id: '__blueprint__', components: template.components };
   const instanceCount = countBlueprintInstances(files, blueprintPath);
@@ -1552,6 +1603,7 @@ function BlueprintInspector({
         onSetComponent={(actorId, behaviorName, nextProps) => onSetComponent(behaviorName, nextProps)}
         onAddBehavior={(actorId, behaviorName) => onAddBehavior(behaviorName)}
         onRemoveBehavior={(actorId, behaviorName) => onRemoveBehavior(behaviorName)}
+        onSelectShape={onSelectShape}
       />
     </>
   );
@@ -1593,6 +1645,9 @@ function ActorInspector({
   onRemoveBehavior,
   onFork,
   onEditBlueprint,
+  onBeginPick,
+  pickActive,
+  onSelectShape,
 }) {
   const isInstance = Boolean(rawActor?.blueprint);
   const presentNames = new Set(
@@ -1687,6 +1742,9 @@ function ActorInspector({
             sprites={sprites}
             setComponent={setComponent}
             override={override}
+            beginPick={onBeginPick}
+            pickActive={pickActive}
+            onSelectShape={onSelectShape}
           />
         ) : (
           <AutoInspector

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

@@ -68,6 +68,7 @@ export function SelectionOverlay({
   previewSceneData,
   sprites,
   selectedActorIds,
+  selectedColliderShape,
   snap,
   onArrange,
   onClone,
@@ -198,6 +199,9 @@ export function SelectionOverlay({
 
   const geometry = getOverlayGeometry(frame, box, camera);
   const colliderFrames = getSelectedColliderFrames(previewSceneData, selectedActorIds, sprites);
+  // The collider inspector edits one shape of a single-selected actor; highlight
+  // that shape's box so you can see which one you're editing at a glance.
+  const editedColliderActor = selectedActorIds.length === 1 ? selectedActorIds[0] : null;
 
   return (
     <div ref={rootRef} className={styles.selOverlayRoot}>
@@ -211,24 +215,34 @@ export function SelectionOverlay({
         <div
           className={styles.selChromeWorld}
           style={{ transform: `translate(${-geometry.camX}px, ${-geometry.camY}px)` }}>
-          {colliderFrames.map((collider, i) => (
-            <div
-              key={`${collider.actorId}:${i}`}
-              className={cx(
-                styles.selColliderBox,
-                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)`,
-              }}
-            />
-          ))}
+          {colliderFrames.map((collider, i) => {
+            const highlighted =
+              collider.actorId === editedColliderActor && collider.shapeIndex === selectedColliderShape;
+            return (
+              <div
+                key={`${collider.actorId}:${i}`}
+                className={cx(
+                  styles.selColliderBox,
+                  collider.isTrigger && styles.selColliderPickup
+                )}
+                style={{
+                  left: collider.x,
+                  top: collider.y,
+                  width: collider.width,
+                  height: collider.height,
+                  borderRadius: collider.shape === 'circle' ? '50%' : undefined,
+                  transformOrigin: '0 0',
+                  transform: colliderTransform(collider),
+                  // The shape being edited: a bright border + tint, lifted above
+                  // the others so an overlapping (e.g. skateboard) shape reads clearly.
+                  borderColor: highlighted ? '#ffd24a' : undefined,
+                  borderWidth: highlighted ? 3 : undefined,
+                  background: highlighted ? 'rgba(255, 210, 74, 0.14)' : undefined,
+                  zIndex: highlighted ? 1 : 0,
+                }}
+              />
+            );
+          })}
         </div>
       </div>
 
@@ -456,6 +470,19 @@ function getActionAnchor({ centerX, centerY, halfH, rotateAnchor }) {
   };
 }
 
+// Compose the collider box's on-screen transform (origin = box top-left): rotate
+// by the shape's own `angle` about its center, then by the actor's Layout.rotation
+// about the actor center. Both pivots explicit since they differ.
+function colliderTransform(c) {
+  const ax = c.originX;
+  const ay = c.originY;
+  const layout = `translate(${ax}px, ${ay}px) rotate(${c.rotation}deg) translate(${-ax}px, ${-ay}px)`;
+  if (!c.shapeAngle) return layout;
+  const cx = c.width / 2;
+  const cy = c.height / 2;
+  return `${layout} translate(${cx}px, ${cy}px) rotate(${c.shapeAngle}deg) translate(${-cx}px, ${-cy}px)`;
+}
+
 function getSelectedColliderFrames(sceneData, actorIds, sprites) {
   if (!sceneData || !actorIds || actorIds.length === 0) return [];
   const wanted = new Set(actorIds);
@@ -470,7 +497,7 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
       // One preview box per collider shape, from the shared geometry so the
       // preview matches the physics body. A circle renders as a radius-sized
       // square with border-radius; a triangle/polygon as its AABB (v1).
-      return shapes.map((s) => {
+      return shapes.map((s, shapeIndex) => {
         let kind = 'box';
         let x;
         let y;
@@ -505,6 +532,7 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
         }
         return {
           actorId: actor.id,
+          shapeIndex,
           shape: kind,
           isTrigger,
           x,
@@ -512,6 +540,7 @@ function getSelectedColliderFrames(sceneData, actorIds, sprites) {
           width,
           height,
           rotation: layout.rotation ?? 0,
+          shapeAngle: s.type === 'box' ? s.angle ?? 0 : 0,
           originX: layout.x + layout.width / 2 - x,
           originY: layout.y + layout.height / 2 - y,
         };

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

@@ -3,9 +3,15 @@
 // 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.
+// Root-anchored so the kit finds the DECK's behaviors even when the kit is
+// itself an import (see engine/files.js). Imports are swept first and the deck's
+// own behaviors last: collectBehaviors keys by behaviorName, so a behavior the
+// deck defines wins over one of the same name from a dependency.
 const modules = {
-  ...import.meta.glob('../behaviors/*.jsx', { eager: true }),
-  ...import.meta.glob('../physics/behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('/imports/*/behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('/imports/*/physics/behaviors/*.jsx', { eager: true }),
+  ...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/physics-2d/engine/blueprint.js

@@ -6,6 +6,7 @@
 // panel propagates to every scene that places it. Shared by the runtime
 // (`scene.js`, so play mode and `PlayOnly` resolve blueprints too) and the
 // editors (which also mint/fork/migrate/cascade-delete blueprint files).
+import { resolveDeckFile } from 'castle-web-sdk';
 import { formatJson } from './files';
 import { DEFAULT_RESOLUTION, TRANSPARENT, serializeCompact } from './pxart';
 import { cardSize, dedupeActorId } from './scene';
@@ -13,8 +14,19 @@ import { cardSize, dedupeActorId } from './scene';
 export const BLUEPRINTS_DIR = 'blueprints';
 export const DRAWINGS_DIR = 'drawings';
 
+// A blueprint of this deck (`blueprints/x.scene`) OR of one it imports
+// (`imports/<alias>/blueprints/x.scene`) -- an imported deck's blueprints are
+// placeable like any other, which is most of the point of importing one.
+const BLUEPRINT_PATH_RE = new RegExp(`^(imports/[^/]+/)?${BLUEPRINTS_DIR}/`);
+
 export function isBlueprintPath(path) {
-  return typeof path === 'string' && path.startsWith(`${BLUEPRINTS_DIR}/`) && path.endsWith('.scene');
+  return typeof path === 'string' && path.endsWith('.scene') && BLUEPRINT_PATH_RE.test(path);
+}
+
+// Blueprints an import owns: placeable, but not editable or deletable from here
+// (they belong to the deck they came from).
+export function isImportedPath(path) {
+  return typeof path === 'string' && path.startsWith('imports/');
 }
 
 // Per-property inherit metadata for a behavior prop. Behaviors opt a prop out
@@ -49,12 +61,33 @@ function parseBlueprintText(text) {
   return { name, components: actor.components };
 }
 
+// A reference names a file the way its own deck sees it -- `drawings/rock.pxart`
+// for one of its own, `@imports/<alias>/...` for one of a deck it imports (the
+// SDK's resolveDeckFile is the single definition of that rule). Templates are
+// resolved against the file they were written in, so a kit's blueprint keeps
+// meaning the kit's drawing after the kit is imported by somebody else.
+function resolveTemplateRefs(template, files, fromPath) {
+  if (!template) return template;
+  for (const props of Object.values(template.components ?? {})) {
+    for (const [key, value] of Object.entries(props ?? {})) {
+      if (typeof value !== 'string' || !value) continue;
+      const resolved = resolveDeckFile(value, fromPath);
+      if (resolved !== value && files?.[resolved] !== undefined) props[key] = resolved;
+    }
+  }
+  return template;
+}
+
 // Resolve a blueprint's template from the LIVE files map -- the load-bearing
 // call for live propagation. Returns null when the file is missing, deleted,
 // or malformed (a dangling `blueprint` ref degrades to "no template" rather
 // than throwing).
 export function getBlueprintTemplate(files, blueprintPath) {
-  return parseBlueprintText(files?.[blueprintPath]);
+  // The ref may name this deck's blueprint or an import's; the template's own
+  // refs then resolve against whichever deck the blueprint turned out to be in.
+  const key = resolveDeckFile(blueprintPath);
+  const template = parseBlueprintText(files?.[key]);
+  return resolveTemplateRefs(template, files, key);
 }
 
 // Every blueprint currently in the deck, for the library/hotbar. Skips
@@ -63,7 +96,10 @@ export function listBlueprints(files) {
   const out = [];
   for (const path of Object.keys(files ?? {})) {
     if (!isBlueprintPath(path)) continue;
-    const template = parseBlueprintText(files[path]);
+    // Same origin resolution getBlueprintTemplate does: an imported blueprint's
+    // `drawings/x.pxart` means the import's drawing, and the library previews
+    // these templates -- unresolved, the slot renders with no art.
+    const template = resolveTemplateRefs(parseBlueprintText(files[path]), files, path);
     if (!template) continue;
     out.push({ path, name: template.name, components: template.components });
   }

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

@@ -5,7 +5,7 @@
 // A Collider is a LIST of shapes (`Collider.shapes`), each stored as a FRACTION
 // of the actor's Layout box -- so a collider keeps its relative size and position
 // when the box is resized (blueprint default OR per-instance override). Shapes:
-//   box:      { type:'box',      x, y, w, h }        center + size, fractions of box
+//   box:      { type:'box',      x, y, w, h, angle? } center + size (frac); angle deg
 //   circle:   { type:'circle',   x, y, r }           center frac; r = frac of min(box side)
 //   triangle: { type:'triangle', points:[{x,y}×3] }  fractions of box
 //   polygon:  { type:'polygon',  points:[{x,y}×N] }
@@ -140,7 +140,10 @@ function resolveShape(shape, layout) {
   const h = (shape.h ?? 1) * bh;
   const cx = wx(shape.x ?? 0.5);
   const cy = wy(shape.y ?? 0.5);
-  return { type: 'box', cx, cy, width: w, height: h, x: cx - w / 2, y: cy - h / 2 };
+  // `angle` (deg) rotates the box about its own center, within the unrotated box
+  // frame; Layout.rotation composes on top (matter body + draw ctx). `x`/`y` are
+  // the UNROTATED top-left -- shapeAabb widens them when angled.
+  return { type: 'box', cx, cy, width: w, height: h, x: cx - w / 2, y: cy - h / 2, angle: shape.angle ?? 0 };
 }
 
 // World-space shapes for an actor's collider (list), or null if no Layout/Collider.
@@ -172,7 +175,14 @@ function shapeAabb(s) {
     }
     return [x0, y0, x1, y1];
   }
-  return [s.x, s.y, s.x + s.width, s.y + s.height];
+  const ang = ((s.angle ?? 0) * Math.PI) / 180;
+  if (!ang) return [s.x, s.y, s.x + s.width, s.y + s.height];
+  // AABB of a box rotated about its center: project the half-extents onto the axes.
+  const c = Math.abs(Math.cos(ang));
+  const sn = Math.abs(Math.sin(ang));
+  const ex = (s.width / 2) * c + (s.height / 2) * sn;
+  const ey = (s.width / 2) * sn + (s.height / 2) * c;
+  return [s.cx - ex, s.cy - ey, s.cx + ex, s.cy + ey];
 }
 
 // AABB of the whole collider (union of all shapes), world units -- for

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

@@ -1,12 +1,33 @@
 // Seed the file map by scanning the deck dir. Vite module-cache is invalidated
 // on restart, so a newly-created file just shows up on the next reload.
-const rawModules = import.meta.glob(
-  ['../scenes/*.scene', '../blueprints/*.scene', '../drawings/*.pxart', '../behaviors/*.jsx'],
-  { query: '?raw', import: 'default', eager: true }
-);
+// Anchored at the DECK ROOT (`/scenes/...`) rather than relative to this module,
+// because the kit itself may be an import: living at `imports/<alias>/`, a
+// `../scenes/*.scene` would find the KIT's scenes instead of the deck's. Anchored
+// at the root, one pattern works whether the kit is the deck or a dependency.
+//
+// The first glob adds every import's content, keyed by its full path
+// (`imports/<alias>/drawings/rock.pxart`) -- which is exactly how a scene or
+// blueprint refers to a dependency's file, so no lookup elsewhere changes.
+// (Patterns and options must be literals: import.meta.glob is a compile-time
+// transform, so these can't be hoisted into shared constants.)
+const rawModules = {
+  ...import.meta.glob(
+    [
+      '/imports/*/scenes/*.scene',
+      '/imports/*/blueprints/*.scene',
+      '/imports/*/drawings/*.pxart',
+      '/imports/*/behaviors/*.jsx',
+    ],
+    { query: '?raw', import: 'default', eager: true }
+  ),
+  ...import.meta.glob(
+    ['/scenes/*.scene', '/blueprints/*.scene', '/drawings/*.pxart', '/behaviors/*.jsx'],
+    { query: '?raw', import: 'default', eager: true }
+  ),
+};
 export const initialFiles = Object.fromEntries(
   Object.entries(rawModules)
-    .map(([globPath, text]) => [globPath.replace(/^\.\.\//, ''), text])
+    .map(([globPath, text]) => [globPath.replace(/^\//, ''), text])
     .sort(([a], [b]) => a.localeCompare(b))
 );
 export function getFileKind(path) {

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

@@ -1,3 +1,4 @@
+import { resolveDeckFile } from 'castle-web-sdk';
 import { initialFiles, parseJsonFile } from './files';
 import { getBlueprintTemplate, mergeComponents } from './blueprint';
 import { getColliderRect, intersects, spriteIsEmpty } from './collider';
@@ -18,7 +19,9 @@ export const cardSize = { width: CARD_WIDTH, height: CARD_HEIGHT };
 // 'main.scene', 'scenes/main.scene', './scenes/main.scene', or 'main' -- the
 // `.scene` extension and a leading `scenes/` are both optional.
 function resolveSceneFileKey(name) {
-  const key = String(name).replace(/^\.?\//, '');
+  // `@imports/<alias>/scenes/x.scene` names an import's scene; anything else is
+  // this deck's, with the `scenes/` folder and `.scene` suffix both optional.
+  const key = resolveDeckFile(String(name));
   const candidates = [key];
   if (!key.endsWith('.scene')) candidates.push(`${key}.scene`);
   for (const candidate of [...candidates]) {
@@ -59,6 +62,11 @@ export class SceneRuntime {
   }
 
   load(sceneData) {
+    // Reset registered systems (e.g. physics) so a reload/restart/scene
+    // transition starts from the authored layout -- otherwise a system holding
+    // simulation state (body positions, joints) would carry it across the load.
+    // No-op on the constructor's first load, before any system is registered.
+    for (const system of this.systems) system.reset?.(this);
     this.data = structuredClone(sceneData);
     this.actors = new Map();
     for (const actor of this.data.actors ?? []) {

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

@@ -6,7 +6,11 @@
 // 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 });
+// Root-anchored, deck + imports (see engine/files.js).
+const modules = {
+  ...import.meta.glob('/imports/*/systems/*.js', { eager: true }),
+  ...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/package-lock.json

@@ -1,10 +1,10 @@
 {
-  "name": "basic-2d-js",
+  "name": "physics-2d",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "basic-2d-js",
+      "name": "physics-2d",
       "dependencies": {
         "@codemirror/commands": "^6.10.3",
         "@codemirror/lang-javascript": "^6.2.5",
@@ -15,6 +15,7 @@
         "@lezer/highlight": "^1.2.3",
         "castle-web-sdk": "file:../../sdk",
         "codemirror": "^6.0.2",
+        "matter-js": "^0.20.0",
         "react": "^19.2.4",
         "react-dom": "^19.2.4"
       },
@@ -27,7 +28,7 @@
     },
     "../../sdk": {
       "name": "castle-web-sdk",
-      "version": "0.4.1",
+      "version": "0.4.11",
       "devDependencies": {
         "eslint": "^9.0.0",
         "jscpd": "^4.0.5",
@@ -1899,6 +1900,12 @@
         "node": ">= 0.4"
       }
     },
+    "node_modules/matter-js": {
+      "version": "0.20.0",
+      "resolved": "https://registry.npmjs.org/matter-js/-/matter-js-0.20.0.tgz",
+      "integrity": "sha512-iC9fYR7zVT3HppNnsFsp9XOoQdQN2tUyfaKg4CHLH8bN+j6GT4Gw7IH2rP0tflAebrHFw730RR3DkVSZRX8hwA==",
+      "license": "MIT"
+    },
     "node_modules/merge-stream": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",