castle-web-cli 0.4.120 → 0.4.122

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

@@ -2,6 +2,7 @@ import React from 'react';
 import { playTone, WAVEFORMS } from '../engine/tone';
 import { Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { PAN, POSITIVE, UNIT } from '../engine/propertyRanges';
 
 // Plays a synthesized note -- no audio file involved. This is the cheapest sound
 // a deck can make: a blip on a pickup, a thud on a miss, a rising scale as a
@@ -27,6 +28,16 @@ export class Tone {
     playOnStart: false,
   };
 
+  // `note` is MIDI, which is genuinely 0..127. `attack`/`release` are seconds,
+  // so they get a floor but no ceiling.
+  static propertyMeta = {
+    note: { min: 0, max: 127, step: 1 },
+    attack: POSITIVE,
+    release: POSITIVE,
+    volume: UNIT,
+    pan: PAN,
+  };
+
   constructor(props) {
     this.props = props;
   }
@@ -54,6 +65,7 @@ export class Tone {
         />
         <AutoFields
           defaultProps={Tone.defaultProps}
+          meta={Tone.propertyMeta}
           component={component}
           setComponent={setComponent}
           only={['note', 'attack', 'release', 'volume', 'pan', 'playOnStart']}

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-12T18:15:12.718Z"
+  "publishedVersion": "2026-08-16T04:02:06.732Z"
 }

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

@@ -787,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);
@@ -797,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)),
@@ -1072,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]
   );

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

@@ -7,6 +7,7 @@
 import React, { useEffect, useRef, useState } from 'react';
 import { onBeforeRestart, onSaveReloadState, takeReloadState, writeFile } from 'castle-web-sdk';
 import { getFileKind } from '../engine/files';
+import { hasEditorModule, loadEditorModule } from './editorRegistry';
 import { useLiveDeckFiles } from '../engine/liveReload';
 import { collectAssets } from '../engine/assets';
 import { MainEditor, styles } from '../engine/ui';
@@ -65,7 +66,33 @@ function useFileSaver() {
   return { schedule, hasPending };
 }
 
-export function SingleEditor({ path, editor }) {
+// A file type whose declaring deck named an editor module: load that module and
+// render it, rather than matching the path against this kit's own list. This is
+// what lets a deck hold two kits -- each type reaches its own declarer's editor,
+// and neither kit has to know the other exists.
+function DeclaredEditor({ path, module: modulePath, text, onChange, files, onChangeFile }) {
+  const [Editor, setEditor] = useState(null);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    let alive = true;
+    setEditor(null);
+    setError(null);
+    loadEditorModule(modulePath).then(
+      (loaded) => alive && setEditor(() => loaded),
+      (e) => alive && setError(e instanceof Error ? e.message : String(e)),
+    );
+    return () => {
+      alive = false;
+    };
+  }, [modulePath]);
+  if (error) return <div className={styles.editorBody}>{error}</div>;
+  if (!Editor) return <div className={styles.editorBody}>loading editor…</div>;
+  return (
+    <Editor path={path} text={text} onChange={onChange} files={files} onChangeFile={onChangeFile} />
+  );
+}
+
+export function SingleEditor({ path, editor, editorModule }) {
   // Selection survives a code-change reload: stashed via the SDK's save-state
   // hook right before the reload, picked back up here on boot.
   const stashKey = `single-editor:${path}`;
@@ -96,7 +123,21 @@ export function SingleEditor({ path, editor }) {
   const kind = editor || getFileKind(path);
   const text = files[path] ?? '';
   let body = null;
-  if (kind === 'scene') {
+  // A declared module wins over this kit's own extension matching -- including
+  // over its own types, so the kit's editors are reachable the same way anyone
+  // else's are once physics-2d names them in castle.json.
+  if (editorModule && hasEditorModule(editorModule)) {
+    body = (
+      <DeclaredEditor
+        path={path}
+        module={editorModule}
+        text={text}
+        onChange={onChange}
+        files={files}
+        onChangeFile={onChangeFile}
+      />
+    );
+  } else if (kind === 'scene') {
     body = (
       <SceneEditor
         path={path}

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

@@ -0,0 +1,34 @@
+// Every editor module any deck here declares -- this deck's own and each
+// import's -- keyed by its path from the deck root, which is exactly what
+// `castle.json` `editor` resolves to (see resolveFileTypes in the CLI).
+//
+// A glob rather than a dynamic `import(path)`: the specifier has to be static
+// for the module to survive bundling into a deck's single published file, the
+// same reason behaviorRegistry and files.js glob. NOT eager, so an editor is a
+// separate chunk that the play route never evaluates.
+//
+// Editors live under `editors/` by convention; that is what makes a third
+// party's editor reachable from here without this kit knowing it exists.
+const modules = {
+  ...import.meta.glob('/imports/*/editors/**/*.{jsx,js}'),
+  ...import.meta.glob('/editors/**/*.{jsx,js}'),
+};
+
+export function hasEditorModule(path) {
+  return Boolean(path && modules[`/${path}`]);
+}
+
+// Load one, returning its default export. Throws a legible error rather than
+// letting the caller see `undefined is not a function` three frames later.
+export async function loadEditorModule(path) {
+  const load = modules[`/${path}`];
+  if (!load) {
+    throw new Error(
+      `No editor module at "${path}". Editors must live under editors/ so the registry glob can reach them.`,
+    );
+  }
+  const mod = await load();
+  const Editor = mod.default ?? mod.Editor;
+  if (!Editor) throw new Error(`"${path}" has no default export to render as an editor.`);
+  return Editor;
+}

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

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

@@ -5,6 +5,21 @@
 // through scene.physics. (Controls are touch/pointer-first; keyboard, when
 // added, should only DUPLICATE an on-screen control, never be the only input.)
 
+// Authored Draggable `stiffness` (0..1, 0 = floppy .. 1 = rigid) -> the matter
+// constraint values that hold the object. Geometric, like joints.js's rope map
+// and for the same reason: matter's useful range here is ~0.001 (slack) to ~0.4
+// (tight), and everything above that is indistinguishably rigid -- so a linear
+// prop spends nearly all of its travel in "stiff" and never reaches the loose
+// end at all.
+//
+// Damping rides along rather than being its own knob: a slack band should be
+// free to oscillate and a tight one shouldn't, so one control moves the whole
+// feel together.
+export function dragHold(stiffness) {
+  const s = Math.min(1, Math.max(0, stiffness ?? 0.3));
+  return { stiffness: 0.001 * Math.pow(400, s), damping: 0.02 + 0.25 * s };
+}
+
 export function centerOf(layout) {
   return { x: layout.x + layout.width / 2, y: layout.y + layout.height / 2 };
 }
@@ -21,26 +36,35 @@ export function clampLength(v, max) {
   return { x: v.x * s, y: v.y * s };
 }
 
-// Springy chase velocity toward a target point (Draggable): a fraction of the
-// gap per step, so the body accelerates toward the pointer and still collides.
-export function chaseVelocity(target, layout, props = {}) {
-  const stiffness = props.stiffness ?? 0.5;
-  const c = centerOf(layout);
-  return { x: (target.x - c.x) * stiffness, y: (target.y - c.y) * stiffness };
-}
-
 // --- Touch ownership -------------------------------------------------------
-// Hierarchy: a press that lands ON a Draggable object is CONSUMED by that drag,
-// so Slingshot/AnalogStick ignore it. A press anywhere else is shared -- both
-// Slingshot and AnalogStick act (no fair way to rank them). So the only gate the
-// non-drag controls need is this: did the current press land on a draggable?
-// Stateless -- a pure per-press query (the controls only ask on their press
-// edge), so there's no owner to latch and nothing to reset.
-export function pressOnDraggable(scene) {
-  const p = scene.pointer;
-  if (!p.down) return false;
-  const hit = scene.actorAt(p.x, p.y);
-  return !!hit && !!hit.components.Draggable;
+// Each control claims the pointer it started on (scene.claimPointer), so a
+// finger drives exactly one thing and the others leave it alone. Two priorities
+// are all this needs:
+//
+//   TARGETED  the press landed on THIS actor's collider, so the intent is
+//             unambiguous -- a Draggable being grabbed, a Slingshot pressed on
+//             its own body.
+//   GREEDY    the control takes any press anywhere (a Slingshot with
+//             grabAnywhere, an AnalogStick), so it must yield to a targeted one.
+//
+// Ranking them explicitly is what makes the outcome independent of actor order.
+// Previously this was a `pressOnDraggable` query that hardcoded one behavior's
+// name into shared code and had no answer at all once two fingers were down.
+export const TARGETED_CLAIM = 10;
+export const GREEDY_CLAIM = 0;
+
+// Take the first fresh press this frame that `actorId` is allowed to have, and
+// claim it. `priorityFor(pointer)` returns the claim priority to bid, or null to
+// pass on that pointer -- which is the only part that differs between controls.
+// Returns the claimed pointer, or null if there was nothing to take.
+export function acquirePress(scene, actorId, priorityFor) {
+  for (const p of scene.pointers.values()) {
+    if (!p.justPressed) continue;
+    const priority = priorityFor(p);
+    if (priority == null) continue;
+    if (scene.claimPointer(p.id, actorId, priority)) return p;
+  }
+  return null;
 }
 
 // Run `draw(ctx)` in world space, undoing the actor's Layout rotation that the

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

@@ -0,0 +1,27 @@
+// Named inspector ranges for behaviors' `static propertyMeta`.
+//
+// A numeric prop with no meta renders as an unbounded scrubber stepping by whole
+// numbers, which is wrong for anything living in 0..1. The recurring shapes get a
+// name here so "a normalized level" is defined once instead of restated in every
+// behavior -- and so a range change lands everywhere at once.
+//
+// A `max` is a hard authoring ceiling, not just a slider bound: typed entry is
+// clamped to it too (see NumberField's `commit`). So only give something a max
+// when exceeding it is meaningless or actively breaks the simulation.
+
+// A normalized 0..1 level: volume, and anything else expressed as a fraction.
+export const UNIT = { min: 0, max: 1, step: 0.05 };
+
+// Stereo position, -1 (left) .. +1 (right). Hard-bounded by definition.
+export const PAN = { min: -1, max: 1, step: 0.05 };
+
+// Open-ended and non-negative -- a floor, but no ceiling, for quantities matter
+// or the browser treats as unbounded (restitution, friction, seconds).
+export const POSITIVE = { min: 0, step: 0.05 };
+
+// Matter's air/angular friction. Above 1 it flips the velocity sign and the body
+// destabilizes, so 1 is a real ceiling. Finer step: the useful values are small.
+export const DAMPING = { min: 0, max: 1, step: 0.01 };
+
+// A distance in card units (px).
+export const PIXELS = { min: 0, step: 5 };