castle-web-cli 0.4.119 → 0.4.121

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

@@ -5,6 +5,7 @@ import { mediaFilesOfKind } from '../engine/files';
 import { spriteDestRect } from '../engine/spriteGeometry';
 import { Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { UNIT } from '../engine/propertyRanges';
 
 // Plays a video file (.mp4 / .webm / .mov / .m4v) inside the actor's Layout box.
 //
@@ -29,6 +30,10 @@ export class Video {
     volume: 1,
   };
 
+  static propertyMeta = {
+    volume: UNIT,
+  };
+
   constructor(props) {
     this.props = props;
   }
@@ -100,6 +105,7 @@ export class Video {
         />
         <AutoFields
           defaultProps={Video.defaultProps}
+          meta={Video.propertyMeta}
           component={component}
           setComponent={setComponent}
           only={['playing', 'loop', 'muted', 'volume']}

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

@@ -123,5 +123,5 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-08-08T19:00:43.040Z"
+  "publishedVersion": "2026-08-14T21:20:31.152Z"
 }

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

@@ -442,8 +442,16 @@ export function SceneEditor({
       sceneData,
       files
     );
-    void writeFile(drawingFile.path, drawingFile.text);
-    void writeFile(blueprintFile.path, blueprintFile.text);
+    // Add both generated files to the live map before committing the instance.
+    // Otherwise another + click can mint the same numbered paths while the fs
+    // watcher's asynchronous echo of these direct writes is still pending.
+    if (onChangeFile) {
+      onChangeFile(drawingFile.path, drawingFile.text);
+      onChangeFile(blueprintFile.path, blueprintFile.text);
+    } else {
+      void writeFile(drawingFile.path, drawingFile.text);
+      void writeFile(blueprintFile.path, blueprintFile.text);
+    }
     history.commit(serialize(next));
     onSelectActorIds([newId]);
   };
@@ -779,6 +787,38 @@ function initialBehaviorProps(Behavior, actor, sprites) {
   return { ...Behavior.defaultProps };
 }
 
+// A behavior that can't work alone names the components it needs BESIDE IT on the
+// same actor: `static expectedSiblings = ['Collider', ...]`. Adding it brings any
+// that are missing along with it. Physics is the case that matters -- a body only
+// exists for an actor with a Collider (matterBridge's `isPhysicsActor`), so a lone
+// Draggable or RigidBody is silently inert: it looks added and does nothing.
+//
+// "Sibling" is the scope, and it is deliberately narrow. It means another
+// component on THIS actor, never another actor -- a Joints link also needs its
+// `target` actor to have a Collider, and that is not this, because the target is
+// the author's to pick.
+//
+// "Expected" is the strength, and also deliberate: this fires when the editor
+// adds a behavior and nowhere else. A blueprint hand-written (or agent-written)
+// without the siblings is not corrected, and removing a Collider later is not
+// blocked. It closes the common path, not every path.
+//
+// Depth-first, so a sibling's own siblings land first: Draggable expects
+// RigidBody, which expects Collider, so the order is Collider, RigidBody,
+// Draggable. Anything the actor already has is left exactly as authored, and
+// `seen` makes a cyclic declaration terminate rather than recurse forever.
+function behaviorsToAdd(behaviorName, actor, seen = new Set()) {
+  if (seen.has(behaviorName)) return [];
+  seen.add(behaviorName);
+  const out = [];
+  for (const sibling of findBehaviorClass(behaviorName)?.expectedSiblings ?? []) {
+    if (actor?.components?.[sibling]) continue;
+    out.push(...behaviorsToAdd(sibling, actor, seen));
+  }
+  out.push(behaviorName);
+  return out;
+}
+
 function makeSceneActions({ sceneData, files, serialize, commit, selectedActorIds, onSelectActorIds, isBlueprintFile, sprites, resolvedActors }) {
   function commitScene(next, options) {
     commit(serialize(next), options);
@@ -789,12 +829,16 @@ function makeSceneActions({ sceneData, files, serialize, commit, selectedActorId
         coalesceKey: componentCoalesceKey(actorId, behaviorName, nextProps),
       }),
     addBehavior: (actorId, behaviorName) => {
-      const Behavior = findBehaviorClass(behaviorName);
-      if (!Behavior) return;
+      if (!findBehaviorClass(behaviorName)) return;
       const resolved = resolvedActors?.find((actor) => actor.id === actorId);
-      commitScene(
-        setActorComponent(sceneData, actorId, behaviorName, initialBehaviorProps(Behavior, resolved, sprites))
-      );
+      // One commit for the whole set, so adding Draggable is a single undo.
+      let next = sceneData;
+      for (const name of behaviorsToAdd(behaviorName, resolved)) {
+        const Behavior = findBehaviorClass(name);
+        if (!Behavior) continue;
+        next = setActorComponent(next, actorId, name, initialBehaviorProps(Behavior, resolved, sprites));
+      }
+      if (next !== sceneData) commitScene(next);
     },
     removeBehavior: (actorId, behaviorName) =>
       commitScene(removeActorComponent(sceneData, actorId, behaviorName)),
@@ -1064,7 +1108,7 @@ function usePlayPointerGesture({ canvasRef, runtimeRef }) {
       const canvas = canvasRef.current;
       const runtime = runtimeRef.current;
       if (!canvas || !runtime) return;
-      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, down);
+      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, down, event.pointerId);
     },
     [canvasRef, runtimeRef]
   );
@@ -1675,6 +1719,7 @@ function BlueprintInspector({
         selectedActor={templateActor}
         rawActor={templateActor}
         files={files}
+        sprites={sprites}
         onSetComponent={(actorId, behaviorName, nextProps) => onSetComponent(behaviorName, nextProps)}
         onAddBehavior={(actorId, behaviorName) => onAddBehavior(behaviorName)}
         onRemoveBehavior={(actorId, behaviorName) => onRemoveBehavior(behaviorName)}

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

@@ -271,15 +271,36 @@ export function PalettePopover({ open, anchorRef, onClose, children }) {
 
   useLayoutEffect(() => {
     if (!open || !anchorRef.current) return;
-    const anchor = anchorRef.current.getBoundingClientRect();
-    const popoverWidth = 280;
-    const margin = 8;
-    let left = anchor.left - popoverWidth - margin;
-    if (left < margin) left = anchor.right + margin;
-    let top = anchor.top;
-    const maxTop = window.innerHeight - margin;
-    if (top + 320 > maxTop) top = Math.max(margin, maxTop - 320);
-    setPosition({ top, left });
+
+    function positionPopover() {
+      const anchor = anchorRef.current.getBoundingClientRect();
+      const rect = popoverRef.current?.getBoundingClientRect();
+      const margin = 8;
+      const width = rect?.width ?? 280;
+      const height = rect?.height ?? 320;
+      const maxLeft = Math.max(margin, window.innerWidth - width - margin);
+      const maxTop = Math.max(margin, window.innerHeight - height - margin);
+      const leftSide = anchor.left - width - margin;
+      const rightSide = anchor.right + margin;
+      // Prefer the side with room, then clamp a too-wide picker inside this
+      // iframe rather than sending it beyond either viewport edge.
+      const left =
+        leftSide >= margin
+          ? leftSide
+          : rightSide <= maxLeft
+            ? rightSide
+            : Math.min(maxLeft, Math.max(margin, anchor.left + anchor.width / 2 - width / 2));
+      const top = Math.min(maxTop, Math.max(margin, anchor.top));
+      setPosition({ top, left });
+    }
+
+    positionPopover();
+    window.addEventListener('resize', positionPopover);
+    window.addEventListener('scroll', positionPopover, true);
+    return () => {
+      window.removeEventListener('resize', positionPopover);
+      window.removeEventListener('scroll', positionPopover, true);
+    };
   }, [open, anchorRef]);
 
   useEffect(() => {

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

@@ -31,6 +31,8 @@ const SHOW_PER_FRAME_DURATION = false;
 // re-renders the count input, so this is a trivial, easily-revertible toggle.
 const SHOW_ONION_RANGE = false;
 const ONION_RANGE = 1;
+const TIMELINE_LONG_PRESS_MS = 500;
+const TIMELINE_LONG_PRESS_MOVE_TOLERANCE = 10;
 
 // faClapperboard ships in Font Awesome 6, but this kit is pinned to FA5 (see
 // package.json), which doesn't export it. Rather than silently swap in a
@@ -328,26 +330,58 @@ function TimelineGrid({ sprite, text, selection, actions }) {
   const [convertConfirm, setConvertConfirm] = useState(null);
   const closeMenu = useCallback(() => setMenu(null), []);
 
-  // Each opener stops the browser's native menu, anchors at the cursor, and
-  // stashes just enough to rebuild items from the latest props at render time
-  // (so relocated actions always run against current sprite/selection state).
+  // A timeline entity is selected independently by its relevant axis: a layer
+  // by layer index, a frame by frame index, and a cel by the complete pair.
+  // First tap selects; a second tap on that same entity opens its action menu.
+  // A touch long-press always selects its target and opens the same menu.
+  const selectTarget = useCallback(
+    (target) => {
+      if (target.kind === 'layer') actions.selectCell(target.layerIndex, selection.frameIndex);
+      else if (target.kind === 'frame') actions.selectCell(selection.layerIndex, target.frameIndex);
+      else actions.selectCell(target.layerIndex, target.frameIndex);
+    },
+    [actions, selection.frameIndex, selection.layerIndex]
+  );
+  const targetIsSelected = useCallback(
+    (target) => {
+      if (target.kind === 'layer') return selection.layerIndex === target.layerIndex;
+      if (target.kind === 'frame') return selection.frameIndex === target.frameIndex;
+      return selection.layerIndex === target.layerIndex && selection.frameIndex === target.frameIndex;
+    },
+    [selection.frameIndex, selection.layerIndex]
+  );
+  const openMenu = useCallback(
+    (target, event) => {
+      selectTarget(target);
+      const rect = event.currentTarget?.getBoundingClientRect?.();
+      const x = Number.isFinite(event.clientX) ? event.clientX : rect?.left + rect?.width / 2;
+      const y = Number.isFinite(event.clientY) ? event.clientY : rect?.top + rect?.height / 2;
+      setMenu({ ...target, x: x ?? 0, y: y ?? 0 });
+    },
+    [selectTarget]
+  );
+  const press = useTimelineItemPress(openMenu);
+  const activateTarget = (target, event) => {
+    if (isTimelineNestedControl(event) || press.consumeClick(target)) return;
+    if (targetIsSelected(target)) openMenu(target, event);
+    else selectTarget(target);
+  };
+  // Right-click keeps the desktop path and deliberately opens its target even
+  // when it was not already selected.
   const openLayerMenu = (event, layerIndex) => {
     event.preventDefault();
     event.stopPropagation();
-    setMenu({ kind: 'layer', x: event.clientX, y: event.clientY, layerIndex });
+    openMenu({ kind: 'layer', layerIndex }, event);
   };
   const openFrameMenu = (event, frameIndex) => {
     event.preventDefault();
     event.stopPropagation();
-    setMenu({ kind: 'frame', x: event.clientX, y: event.clientY, frameIndex });
+    openMenu({ kind: 'frame', frameIndex }, event);
   };
   const openCellMenu = (event, layerIndex, frameIndex) => {
     event.preventDefault();
     event.stopPropagation();
-    // Link/Unlink are bound to the active cell, so select this one first; the
-    // menu re-renders with rebuilt actions that target (layerIndex, frameIndex).
-    actions.selectCell(layerIndex, frameIndex);
-    setMenu({ kind: 'cell', x: event.clientX, y: event.clientY, layerIndex, frameIndex });
+    openMenu({ kind: 'cell', layerIndex, frameIndex }, event);
   };
 
   return (
@@ -361,7 +395,8 @@ function TimelineGrid({ sprite, text, selection, actions }) {
             index={f}
             globalMs={sprite.defaultDurationMs}
             active={f === selection.frameIndex}
-            onSelect={() => actions.selectCell(selection.layerIndex, f)}
+            onActivate={(event) => activateTarget({ kind: 'frame', frameIndex: f }, event)}
+            onPointerDown={(event) => press.onPointerDown(event, { kind: 'frame', frameIndex: f })}
             onDuration={(ms) => actions.setFrameDuration(f, ms)}
             onContextMenu={(event) => openFrameMenu(event, f)}
           />
@@ -373,7 +408,8 @@ function TimelineGrid({ sprite, text, selection, actions }) {
             layer={sprite.layers[li]}
             index={li}
             active={li === selection.layerIndex}
-            onSelect={() => actions.selectCell(li, selection.frameIndex)}
+            onActivate={(event) => activateTarget({ kind: 'layer', layerIndex: li }, event)}
+            onPointerDown={(event) => press.onPointerDown(event, { kind: 'layer', layerIndex: li })}
             actions={actions}
             onContextMenu={openLayerMenu}
           />
@@ -385,7 +421,8 @@ function TimelineGrid({ sprite, text, selection, actions }) {
               layerIndex={li}
               frameIndex={f}
               active={li === selection.layerIndex && f === selection.frameIndex}
-              onSelect={() => actions.selectCell(li, f)}
+              onActivate={(event) => activateTarget({ kind: 'cell', layerIndex: li, frameIndex: f }, event)}
+              onPointerDown={(event) => press.onPointerDown(event, { kind: 'cell', layerIndex: li, frameIndex: f })}
               onContextMenu={(event) => openCellMenu(event, li, f)}
             />
           ))}
@@ -425,6 +462,93 @@ function TimelineGrid({ sprite, text, selection, actions }) {
   );
 }
 
+function targetKey(target) {
+  if (target.kind === 'layer') return `layer:${target.layerIndex}`;
+  if (target.kind === 'frame') return `frame:${target.frameIndex}`;
+  return `cell:${target.layerIndex}:${target.frameIndex}`;
+}
+
+// Form controls inside a selectable timeline header keep their direct behavior;
+// pressing the layer visibility toggle or a duration input must not arm a menu.
+function isTimelineNestedControl(event) {
+  if (!(event.target instanceof Element) || event.target === event.currentTarget) return false;
+  return Boolean(event.target.closest('input, select, textarea, [data-timeline-control]'));
+}
+
+// Touch-only long press. Scroll intent cancels it after a small move threshold;
+// the subsequent synthetic click is consumed after a successful hold so it
+// doesn't immediately close/reopen the action menu.
+function useTimelineItemPress(openMenu) {
+  const openMenuRef = useRef(openMenu);
+  const pressRef = useRef(null);
+  const suppressClickRef = useRef(null);
+  openMenuRef.current = openMenu;
+
+  useEffect(() => {
+    const clearPress = () => {
+      const press = pressRef.current;
+      if (!press) return null;
+      window.clearTimeout(press.timer);
+      pressRef.current = null;
+      return press;
+    };
+    const onPointerMove = (event) => {
+      const press = pressRef.current;
+      if (!press || press.pointerId !== event.pointerId || press.opened) return;
+      if (Math.hypot(event.clientX - press.startX, event.clientY - press.startY) <= TIMELINE_LONG_PRESS_MOVE_TOLERANCE) return;
+      clearPress();
+    };
+    const onPointerEnd = (event) => {
+      const press = pressRef.current;
+      if (!press || press.pointerId !== event.pointerId) return;
+      const ended = clearPress();
+      if (ended?.opened) suppressClickRef.current = targetKey(ended.target);
+    };
+    window.addEventListener('pointermove', onPointerMove);
+    window.addEventListener('pointerup', onPointerEnd);
+    window.addEventListener('pointercancel', onPointerEnd);
+    return () => {
+      clearPress();
+      window.removeEventListener('pointermove', onPointerMove);
+      window.removeEventListener('pointerup', onPointerEnd);
+      window.removeEventListener('pointercancel', onPointerEnd);
+    };
+  }, []);
+
+  const onPointerDown = useCallback((event, target) => {
+    if (event.pointerType !== 'touch' || event.button !== 0 || isTimelineNestedControl(event)) return;
+    const prior = pressRef.current;
+    if (prior) window.clearTimeout(prior.timer);
+    const menuEvent = {
+      clientX: event.clientX,
+      clientY: event.clientY,
+      currentTarget: event.currentTarget,
+    };
+    const press = {
+      pointerId: event.pointerId,
+      target,
+      startX: event.clientX,
+      startY: event.clientY,
+      opened: false,
+      timer: 0,
+    };
+    press.timer = window.setTimeout(() => {
+      if (pressRef.current !== press) return;
+      press.opened = true;
+      openMenuRef.current(target, menuEvent);
+    }, TIMELINE_LONG_PRESS_MS);
+    pressRef.current = press;
+  }, []);
+
+  const consumeClick = useCallback((target) => {
+    if (suppressClickRef.current !== targetKey(target)) return false;
+    suppressClickRef.current = null;
+    return true;
+  }, []);
+
+  return { onPointerDown, consumeClick };
+}
+
 // Cursor-anchored right-click menu. Reuses the scene editor's "Arrange" menu
 // chrome (the shared `selArrangeMenu`/`selArrangeItem` classes from
 // engine/ui.module.css) for visual consistency, switching to fixed positioning
@@ -588,12 +712,14 @@ function cellMenuItems(menu, sprite, actions) {
   ];
 }
 
-function FrameHeader({ frame, index, globalMs, active, onSelect, onDuration, onContextMenu }) {
+function FrameHeader({ frame, index, globalMs, active, onActivate, onPointerDown, onDuration, onContextMenu }) {
   return (
     <div
       className={active ? tl.frameHead + ' ' + tl.frameHeadActive : tl.frameHead}
+      onPointerDown={onPointerDown}
+      onClick={onActivate}
       onContextMenu={onContextMenu}>
-      <button type="button" className={tl.frameNum} onClick={onSelect} style={btnReset}>
+      <button type="button" className={tl.frameNum} style={btnReset}>
         {index + 1}
       </button>
       {SHOW_PER_FRAME_DURATION ? (
@@ -681,11 +807,12 @@ function FaGlyph({ icon, className = tl.visGlyph }) {
   );
 }
 
-function LayerHeader({ layer, index, active, onSelect, actions, onContextMenu }) {
+function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions, onContextMenu }) {
   return (
     <div
       className={active ? tl.layerHead + ' ' + tl.layerHeadActive : tl.layerHead}
-      onClick={onSelect}
+      onPointerDown={onPointerDown}
+      onClick={onActivate}
       onContextMenu={(event) => onContextMenu(event, index)}>
       <div className={tl.layerTopRow}>
         <span
@@ -710,6 +837,7 @@ function LayerHeader({ layer, index, active, onSelect, actions, onContextMenu })
         />
         <button
           type="button"
+          data-timeline-control
           className={layer.visible ? tl.visBtn : tl.visBtn + ' ' + tl.visOff}
           title={layer.visible ? 'Hide layer' : 'Show layer'}
           onClick={(event) => {
@@ -723,7 +851,7 @@ function LayerHeader({ layer, index, active, onSelect, actions, onContextMenu })
   );
 }
 
-function CellThumb({ sprite, text, layerIndex, frameIndex, active, onSelect, onContextMenu }) {
+function CellThumb({ sprite, text, layerIndex, frameIndex, active, onActivate, onPointerDown, onContextMenu }) {
   const canvasRef = useRef(null);
   const layer = sprite.layers[layerIndex];
   const kind = cellKind(layer, frameIndex);
@@ -743,7 +871,8 @@ function CellThumb({ sprite, text, layerIndex, frameIndex, active, onSelect, onC
       type="button"
       className={active ? tl.cell + ' ' + tl.cellActive : tl.cell}
       title={`Layer ${layerIndex + 1}, frame ${frameIndex + 1} (${kind})`}
-      onClick={onSelect}
+      onPointerDown={onPointerDown}
+      onClick={onActivate}
       onContextMenu={onContextMenu}>
       {kind === 'empty' ? (
         <span className={tl.empty} />

package/kits/physics-2d/engine/ScenePlayer.jsx

@@ -40,14 +40,20 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
       // its document/iframe holds focus. Grab focus on any click into the game
       // (and on mount below) so the keyboard works inside the launcher embed.
       canvas.focus();
-      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, true);
+      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, true, event.pointerId);
       canvas.setPointerCapture(event.pointerId);
     };
     const onPointerMove = (event) => {
-      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY);
+      runtime.setPointerFromScreen(
+        canvas,
+        event.clientX,
+        event.clientY,
+        undefined,
+        event.pointerId
+      );
     };
     const onPointerUp = (event) => {
-      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, false);
+      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, false, event.pointerId);
       try {
         canvas.releasePointerCapture(event.pointerId);
       } catch {

package/kits/physics-2d/engine/autoInspector.jsx

@@ -12,7 +12,12 @@ export function overrideProps(override, prop) {
     onReset: () => override.reset(prop),
   };
 }
-export function AutoFields({ defaultProps, component, setComponent, only, exclude, override }) {
+// `meta` is the behavior's `static propertyMeta`. A numeric prop can declare
+// `{ min, max, step }` there to get a real range instead of NumberField's
+// defaults -- which are an unbounded scrubber stepping by whole numbers, wrong
+// for anything that lives in 0..1. Declaring BOTH min and max makes it a true
+// slider (fill + thumb). Props that declare nothing are unchanged.
+export function AutoFields({ defaultProps, component, setComponent, only, exclude, override, meta }) {
   const keys = Object.keys(defaultProps).filter((key) => {
     if (only) return only.includes(key);
     if (exclude) return !exclude.includes(key);
@@ -28,7 +33,19 @@ export function AutoFields({ defaultProps, component, setComponent, only, exclud
         const sample = fallback ?? current;
         const ov = overrideProps(override, key);
         if (typeof sample === 'number') {
-          return <NumberField key={key} label={label} value={current} onChange={set} {...ov} />;
+          const { min, max, step } = meta?.[key] ?? {};
+          return (
+            <NumberField
+              key={key}
+              label={label}
+              value={current}
+              onChange={set}
+              {...(min == null ? {} : { min })}
+              {...(max == null ? {} : { max })}
+              {...(step == null ? {} : { step })}
+              {...ov}
+            />
+          );
         }
         if (typeof sample === 'boolean') {
           return <CheckboxField key={key} label={label} checked={current} onChange={set} {...ov} />;
@@ -49,7 +66,14 @@ export function AutoFields({ defaultProps, component, setComponent, only, exclud
     </>
   );
 }
-export function AutoInspector({ behaviorName, defaultProps, component, setComponent, override }) {
+export function AutoInspector({
+  behaviorName,
+  defaultProps,
+  component,
+  setComponent,
+  override,
+  meta,
+}) {
   return (
     <Panel title={humanizeKey(behaviorName)} overridden={override?.anyOverridden()}>
       <AutoFields
@@ -57,6 +81,7 @@ export function AutoInspector({ behaviorName, defaultProps, component, setCompon
         component={component}
         setComponent={setComponent}
         override={override}
+        meta={meta}
       />
     </Panel>
   );

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

@@ -33,6 +33,7 @@ export class PhysicsSystem {
     this.bodies = new Map(); // actorId -> { body, sig, offset: {dx, dy} }
     this.joints = new Map(); // `${ownerId}#${listIndex}` -> { constraints, bodyA, bodyB, sig }
     this.intents = new Map(); // actorId -> { velocity?, impulse?, force? }
+    this.grabs = new Map(); // actorId -> { constraint, localPoint }
     this.gravity = { ...DEFAULT_GRAVITY };
     this.acc = 0;
     this.enterPairs = []; // [aId, bId] collected during this frame's steps
@@ -57,6 +58,7 @@ export class PhysicsSystem {
     this.engine = null;
     this.bodies.clear();
     this.joints.clear();
+    this.grabs.clear();
     this.intents.clear();
     this.active.clear();
     this.ndActive.clear();
@@ -189,6 +191,12 @@ export class PhysicsSystem {
   removeBody(id) {
     const entry = this.bodies.get(id);
     if (!entry) return;
+    // Drop any grab first: its constraint holds a direct reference to this body,
+    // and unlike joints (rebuilt every frame by reconcileJoints) nothing else
+    // revisits it -- so despawning a held actor, or editing its collider mid-play
+    // (a signature change removes and re-adds the body), would otherwise strand a
+    // constraint in the world pointing at a body that no longer exists.
+    this.release(id);
     Matter.Composite.remove(this.engine.world, entry.body);
     this.bodies.delete(id);
     // Drop live contacts involving this actor so isColliding doesn't go stale
@@ -314,6 +322,102 @@ export class PhysicsSystem {
     return this.bodies.get(id)?.body ?? null;
   }
 
+  // Exact point-in-collider test. The matter body is already positioned and
+  // rotated by the sim, so this respects the collider's real shape (circle,
+  // angled box, compound) at its CURRENT orientation for free -- no transform
+  // math here, and nothing to keep in sync with Layout.
+  //
+  // An actor with no body has no touch zone, which is the intended semantics: a
+  // thing with no collider is not grabbable.
+  containsPoint(actorOrId, x, y) {
+    const body = this.bodyOf(actorOrId);
+    if (!body) return false;
+    const point = { x, y };
+    if (!Matter.Bounds.contains(body.bounds, point)) return false;
+    // parts[0] is the parent's convex HULL when the body is compound, so testing
+    // it would report hits in a concave notch (the underside of a skateboard's
+    // deck-plus-nose-and-tail). Test the real parts instead.
+    const parts = body.parts.length > 1 ? body.parts.slice(1) : body.parts;
+    return parts.some((part) => Matter.Vertices.contains(part.vertices, point));
+  }
+
+  // Topmost actor whose COLLIDER contains the point, high z first to match draw
+  // order. This is the pick a touch control wants; `scene.actorAt` tests the
+  // Layout box instead, which is what the editor wants for click-to-select.
+  //
+  // Deliberately NOT via scene.getActors(): that copies and sorts the actor list
+  // on every call, and every Draggable and Slingshot in the scene calls this on
+  // the same press frame -- O(n log n) each, once per actor, plus an array per
+  // call. Tracking the best z in one pass is O(n) with no allocation, and the
+  // `z < bestZ` test skips the shape work for actors that cannot win anyway.
+  // Ties go to the later actor, matching the old reverse-iteration order.
+  actorAtPoint(scene, x, y) {
+    let best = null;
+    let bestZ = -Infinity;
+    for (const actor of scene.actors.values()) {
+      const z = actor.components?.Layout?.z ?? 0;
+      if (z < bestZ) continue;
+      if (!this.containsPoint(actor, x, y)) continue;
+      best = actor;
+      bestZ = z;
+    }
+    return best;
+  }
+
+  // Grab an actor AT a world point: a constraint from that exact spot on the
+  // body to the pointer, so an off-center grab induces torque and the object
+  // swings the way a real held object does. Matter rotates the anchor with the
+  // body from here on, so the grab stays welded to the spot that was touched.
+  //
+  // `pointA` is a world-axis offset from the body center at creation time
+  // (Constraint.create seeds `angleA` to the body's current angle), and matter
+  // mutates it in place each solve -- so never hand it an object we also keep.
+  grab(actorOrId, x, y, opts = {}) {
+    const body = this.bodyOf(actorOrId);
+    if (!body || !this.engine) return false;
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    this.release(id);
+    const constraint = Matter.Constraint.create({
+      bodyA: body,
+      pointA: { x: x - body.position.x, y: y - body.position.y },
+      pointB: { x, y },
+      length: 0,
+      // Modest stiffness + real damping on purpose: MAX_SPEED backstops a
+      // blow-up, but a near-1 stiffness on a heavy body is matter's classic
+      // energy-injection case and we would rather not lean on the clamp.
+      stiffness: opts.stiffness ?? 0.1,
+      damping: opts.damping ?? 0.2,
+    });
+    Matter.Composite.add(this.engine.world, constraint);
+    this.grabs.set(id, { constraint });
+    return true;
+  }
+
+  moveGrab(actorOrId, x, y) {
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    const entry = this.grabs.get(id);
+    if (!entry) return;
+    entry.constraint.pointB = { x, y };
+  }
+
+  release(actorOrId) {
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    const entry = this.grabs.get(id);
+    if (!entry) return;
+    if (this.engine) Matter.Composite.remove(this.engine.world, entry.constraint);
+    this.grabs.delete(id);
+  }
+
+  // Where the grab is holding the body right now, in world space -- read from
+  // the constraint matter is actually solving, so the drawn handle cannot drift
+  // away from the physics.
+  grabPoint(actorOrId) {
+    const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
+    const entry = this.grabs.get(id);
+    if (!entry) return null;
+    return Matter.Constraint.pointAWorld(entry.constraint);
+  }
+
   queue(actorOrId, key, value) {
     const id = typeof actorOrId === 'string' ? actorOrId : actorOrId?.id;
     if (!id) return;
@@ -350,6 +454,19 @@ export class PhysicsSystem {
         return this.active.has(pairKey(aId, bId));
       },
       bodyFor: (actor) => this.bodyOf(actor),
+      // Shape-accurate hit testing: does this actor's collider contain the
+      // point, and which actor is topmost at it. Respects rotation and compound
+      // shapes, unlike the Layout-box `scene.actorAt`.
+      containsPoint: (actor, x, y) => this.containsPoint(actor, x, y),
+      actorAtPoint: (x, y) =>
+        this.lastScene ? this.actorAtPoint(this.lastScene, x, y) : null,
+      // Hold an actor at a world point and drag it there; an off-center grab
+      // turns the body as well as moving it. `grabPoint` is where the hold sits
+      // now, for drawing.
+      grab: (actor, x, y, opts) => this.grab(actor, x, y, opts),
+      moveGrab: (actor, x, y) => this.moveGrab(actor, x, y),
+      release: (actor) => this.release(actor),
+      grabPoint: (actor) => this.grabPoint(actor),
       // Resolved joint geometry for custom rendering: each link's world-space
       // endpoints (Layout centers, so art lines up with the sprites), type,
       // length and angle. Draw your own art between `a` and `b` from a behavior's