castle-web-cli 0.4.129 → 0.4.130

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

@@ -132,14 +132,14 @@ export function PixelToolStrip({ tools, tool, onSelectTool, ariaLabel, disabled
 }
 
 // Compact W × H selects above the artboard (not a sidebar panel).
-export function CanvasSizeBar({ width, height, onResize }) {
+export function CanvasSizeBar({ width, height, onResize, disabled = false }) {
   return (
     <div className={styles.canvasSizeBar} aria-label="Canvas size">
-      <ResolutionSelect label="Width" value={width} onChange={(w) => onResize(w, height)} />
+      <ResolutionSelect label="Width" value={width} onChange={(w) => onResize(w, height)} disabled={disabled} />
       <span className={styles.canvasSizeSep} aria-hidden="true">
         ×
       </span>
-      <ResolutionSelect label="Height" value={height} onChange={(h) => onResize(width, h)} />
+      <ResolutionSelect label="Height" value={height} onChange={(h) => onResize(width, h)} disabled={disabled} />
     </div>
   );
 }
@@ -175,13 +175,13 @@ const FINISH_STEPS = [
 // (properties of the .pxart asset — see docs/pxart-format.md — not per-actor
 // Sprite props). Highlights whichever preset the pair exactly matches, or none
 // when it matches no preset.
-export function FinishBar({ renderer, cornerRadius, onChange }) {
+export function FinishBar({ renderer, cornerRadius, onChange, disabled = false }) {
   const isOn = (step) =>
     step.renderer === (renderer ?? GRID_RENDERER) && step.cornerRadius === (cornerRadius ?? 0);
   return (
     <div className={styles.finishBar} aria-label="Finish">
       <span>Finish</span>
-      <div className={styles.finishSegments} role="radiogroup" aria-label="Finish">
+      <div className={styles.finishSegments} role="radiogroup" aria-label="Finish" aria-disabled={disabled || undefined}>
         {FINISH_STEPS.map((step) => (
           <button
             key={step.id}
@@ -189,6 +189,7 @@ export function FinishBar({ renderer, cornerRadius, onChange }) {
             role="radio"
             aria-label={step.label}
             aria-checked={isOn(step) ? 'true' : 'false'}
+            disabled={disabled}
             className={cx(styles.finishSegment, isOn(step) && styles.finishSegmentOn)}
             title={step.title}
             onClick={() =>
@@ -202,7 +203,7 @@ export function FinishBar({ renderer, cornerRadius, onChange }) {
   );
 }
 
-function ResolutionSelect({ label, value, onChange }) {
+function ResolutionSelect({ label, value, onChange, disabled = false }) {
   const options = RESOLUTION_STEPS.includes(value)
     ? RESOLUTION_STEPS
     : [...RESOLUTION_STEPS, value].sort((a, b) => a - b);
@@ -211,6 +212,7 @@ function ResolutionSelect({ label, value, onChange }) {
       className={styles.canvasSizeSelect}
       aria-label={label}
       value={value}
+      disabled={disabled}
       onChange={(event) => onChange(Number(event.target.value))}>
       {options.map((step) => (
         <option key={step} value={step}>
@@ -940,10 +942,14 @@ export function PxArtInspectorDock({
   moveActions,
   selectActions,
   pathActions,
+  readOnly = false,
 }) {
   const { tool, picking, setPicking } = toolState;
   return (
-    <aside className={cx(styles.pxArtInspector, styles.drawingToolsPanel)}>
+    <aside
+      className={cx(styles.pxArtInspector, styles.drawingToolsPanel, readOnly && styles.drawingReadOnly)}
+      aria-disabled={readOnly || undefined}
+      inert={readOnly || undefined}>
       <div className={cx(styles.sheetBody, styles.inspectorBody, styles.drawingSettingsColumn)}>
         {PALETTE_TOOLS.has(tool) || picking ? (
           <Panel

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

@@ -146,7 +146,7 @@ function useResizableTimelineHeight() {
 // the top, Aseprite-style) by frame COLUMNS, with thumbnails per cell, layer +
 // frame controls, linked-cell affordances, onion-skin toggles, playback, and a
 // tags editor. All mutation flows through `actions` (wired in PxArtEditor).
-export function PxArtTimeline({ sprite, text, selection, playing, onion, actions }) {
+export function PxArtTimeline({ sprite, text, selection, playing, onion, actions, readOnly = false }) {
   // Hooks run unconditionally (order-stable); only the render branches on viewport.
   const compact = useCompactViewport();
   const resizable = useResizableTimelineHeight();
@@ -159,7 +159,13 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
   });
   const grid = (
     <div className={tl.scroll}>
-      <TimelineGrid sprite={sprite} text={text} selection={selection} actions={actions} />
+      <TimelineGrid
+        sprite={sprite}
+        text={text}
+        selection={selection}
+        actions={actions}
+        readOnly={readOnly}
+      />
     </div>
   );
   if (compact) {
@@ -178,6 +184,7 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
           playing={playing}
           onion={onion}
           actions={actions}
+          readOnly={readOnly}
         />
         {grid}
       </section>
@@ -198,6 +205,7 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
         playing={playing}
         onion={onion}
         actions={actions}
+        readOnly={readOnly}
       />
       {grid}
       {SHOW_TAGS ? <TagsPanel sprite={sprite} actions={actions} /> : null}
@@ -211,7 +219,7 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
 // (duplicate/move/delete/rename/link/unlink/visibility) lives in the right-click
 // context menus on the grid's layer rows, frame headers, and cells (see
 // TimelineGrid + ContextMenu).
-function TimelineBar({ sprite, selection, playing, onion, actions }) {
+function TimelineBar({ sprite, selection, playing, onion, actions, readOnly = false }) {
   const { layerIndex, frameIndex } = selection;
   // A single-frame sprite has no animation, so the three animation controls
   // (global duration, onion skin, play/pause) are meaningless — gate them on
@@ -227,19 +235,20 @@ function TimelineBar({ sprite, selection, playing, onion, actions }) {
   return (
     <div className={tl.bar}>
       <div className={tl.barGroup}>
-        <IconButton icon="grid" label="Pixel" onClick={() => actions.addLayer(layerIndex)} />
+        <IconButton icon="grid" label="Pixel" disabled={readOnly} onClick={() => actions.addLayer(layerIndex)} />
         <span className={tl.barLabel}>Pixel</span>
       </div>
       <div className={tl.barGroup}>
         <IconButton
           icon="draw-polygon"
           label="Path"
+          disabled={readOnly}
           onClick={() => actions.addLayer(layerIndex, 'path')}
         />
         <span className={tl.barLabel}>Path</span>
       </div>
       <div className={tl.barGroup}>
-        <IconButton icon="film" label="Frame" onClick={() => actions.addFrame(frameIndex)} />
+        <IconButton icon="film" label="Frame" disabled={readOnly} onClick={() => actions.addFrame(frameIndex)} />
         <span className={tl.barLabel}>Frame</span>
       </div>
       <div className={tl.barSpacer} />
@@ -249,7 +258,11 @@ function TimelineBar({ sprite, selection, playing, onion, actions }) {
             <span className={tl.durationIcon} title="Default frame duration (ms) — applies to all frames">
               <FaGlyph icon={faStopwatch} className={tl.durationGlyph} />
             </span>
-            <GlobalDurationInput value={sprite.defaultDurationMs} onCommit={actions.setDefaultDuration} />
+            <GlobalDurationInput
+              value={sprite.defaultDurationMs}
+              onCommit={actions.setDefaultDuration}
+              disabled={readOnly}
+            />
           </div>
           <OnionControls onion={onion} actions={actions} />
           <div className={tl.barGroup}>
@@ -268,12 +281,13 @@ function TimelineBar({ sprite, selection, playing, onion, actions }) {
 
 // The sprite's GLOBAL duration. Commits a finite, positive value on blur/Enter;
 // an empty/invalid entry snaps back to the current value (see CommitInput).
-function GlobalDurationInput({ value, onCommit }) {
+function GlobalDurationInput({ value, onCommit, disabled = false }) {
   return (
     <CommitInput
       text={String(value)}
       className={tl.globalDuration}
       title="Global frame duration (ms) — inherited by every frame without its own override"
+      disabled={disabled}
       onCommit={(draft) => {
         const ms = Number(draft);
         if (Number.isFinite(ms) && ms > 0) onCommit(ms);
@@ -322,7 +336,7 @@ function OnionControls({ onion, actions }) {
   );
 }
 
-function TimelineGrid({ sprite, text, selection, actions }) {
+function TimelineGrid({ sprite, text, selection, actions, readOnly = false }) {
   const frames = sprite.frames;
   // Render rows top-down: the last layer (top of the composite stack) first.
   const rows = sprite.layers.map((_, i) => i).reverse();
@@ -353,12 +367,13 @@ function TimelineGrid({ sprite, text, selection, actions }) {
   const openMenu = useCallback(
     (target, event) => {
       selectTarget(target);
+      if (readOnly) return;
       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]
+    [selectTarget, readOnly]
   );
   const press = useTimelineItemPress(openMenu);
   const activateTarget = (target, event) => {
@@ -412,6 +427,7 @@ function TimelineGrid({ sprite, text, selection, actions }) {
             onPointerDown={(event) => press.onPointerDown(event, { kind: 'layer', layerIndex: li })}
             actions={actions}
             onContextMenu={openLayerMenu}
+            readOnly={readOnly}
           />
           {frames.map((_, f) => (
             <CellThumb
@@ -744,7 +760,7 @@ const kindBadgeStyle = {
 // on blur/Enter, re-syncing to `text` when idle. The caller's `onCommit(draft)`
 // interprets the raw string (set / clear / revert). Shared by the per-frame and
 // global duration fields so their edit/commit behavior stays identical.
-function CommitInput({ text, className, placeholder, title, onCommit }) {
+function CommitInput({ text, className, placeholder, title, onCommit, disabled = false }) {
   const [draft, setDraft] = useState(text);
   const editing = useRef(false);
   if (!editing.current && draft !== text) setDraft(text);
@@ -759,6 +775,7 @@ function CommitInput({ text, className, placeholder, title, onCommit }) {
       placeholder={placeholder}
       title={title}
       inputMode="numeric"
+      disabled={disabled}
       onFocus={() => (editing.current = true)}
       onChange={(event) => setDraft(event.target.value)}
       onBlur={commit}
@@ -807,7 +824,7 @@ function FaGlyph({ icon, className = tl.visGlyph }) {
   );
 }
 
-function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions, onContextMenu }) {
+function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions, onContextMenu, readOnly = false }) {
   return (
     <div
       className={active ? tl.layerHead + ' ' + tl.layerHeadActive : tl.layerHead}
@@ -832,6 +849,7 @@ function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions,
           max="100"
           value={Math.round(layer.opacity * 100)}
           title={`Opacity ${Math.round(layer.opacity * 100)}%`}
+          disabled={readOnly}
           onClick={(event) => event.stopPropagation()}
           onChange={(event) => actions.patchLayer(index, { opacity: Number(event.target.value) / 100 })}
         />

package/kits/physics-2d/editors/pxArtTimeline.module.css

@@ -108,6 +108,12 @@
   text-align: center;
 }
 
+.globalDuration:disabled {
+  opacity: 0.55;
+  cursor: default;
+  color: var(--castle-inspector-muted);
+}
+
 /* Icon-only label (stopwatch) sitting next to the global duration input, in
    place of the old "Duration … ms · all frames" text. */
 .durationIcon {
@@ -333,6 +339,11 @@
   accent-color: var(--castle-selected);
 }
 
+.opacity:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .opacity::-webkit-slider-runnable-track {
   height: 3px;
   border-radius: 2px;

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

@@ -69,13 +69,25 @@ function parseBlueprintText(text) {
 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;
+    resolveRefsIn(props, files, fromPath);
+  }
+  return template;
+}
+
+// Nested because a ref is not always a bare prop: `Shape.art` can be one string
+// for the whole shape OR an object naming a file per face, and an unresolved
+// face ref means an untextured surface with no error anywhere. Rewriting only
+// when the resolved path is actually in the file map is what keeps this from
+// mangling strings that were never refs.
+function resolveRefsIn(props, files, fromPath) {
+  for (const [key, value] of Object.entries(props ?? {})) {
+    if (typeof value === 'string' && value) {
       const resolved = resolveDeckFile(value, fromPath);
       if (resolved !== value && files?.[resolved] !== undefined) props[key] = resolved;
+    } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+      resolveRefsIn(value, files, fromPath);
     }
   }
-  return template;
 }
 
 // Resolve a blueprint's template from the LIVE files map -- the load-bearing

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

@@ -1,13 +1,13 @@
-// Consumer side of the serve's `files_changed` broadcast. The engine decides
-// what a change means for this bundle:
-//   - data files (.scene / .pxart / .sprite / .style / .drawing) are re-read
-//     over the serve's files API and folded into React state — live re-render,
-//     no reload.
-//   - code the bundle imports (per the event's module-graph closure), html,
-//     or added/deleted code files (import.meta.glob may pick them up) mean
-//     this context is stale — requestReload() (save-state hooks run first).
+// Consumer side of the serve's `files_changed` broadcast. Data files are
+// re-read over the serve's files API and folded into React state, so an editor
+// shows a drawing someone else just changed without reloading anything.
+//
+// A CODE change does nothing here. Only a page reload picks up new code, and a
+// reload thrown at a panel someone is working in loses their place, so the
+// decision belongs to the person: every panel header carries a reload control,
+// and the shell offers the Play panel a restart when it has fallen behind.
 import { useEffect, useRef, useState } from 'react';
-import { onFilesChanged, requestReload } from 'castle-web-sdk';
+import { onFilesChanged } from 'castle-web-sdk';
 import { initialFiles } from './files';
 
 const DATA_EXTS = ['.scene', '.pxart', '.sprite', '.style', '.drawing'];
@@ -17,7 +17,20 @@ export function isDataFile(path) {
   return DATA_EXTS.some((ext) => path.endsWith(ext));
 }
 
-function needsContextReload(change) {
+// Which iframe is speaking -- every panel runs its own copy of this.
+function panelTag() {
+  try {
+    const q = new URLSearchParams(location.search);
+    return q.get('panel') || q.get('file') || 'deck';
+  } catch {
+    return 'deck';
+  }
+}
+
+// Whether a change means this bundle's code is stale. Only used for the log
+// line -- nothing acts on it -- but knowing a panel went stale and when is what
+// makes a vague "it looked wrong" report checkable against `.castle/serve.log`.
+function isCodeChange(change) {
   if (isDataFile(change.path)) return false;
   if (change.path.endsWith('.html')) return true;
   // In the module graph (directly or as someone's import) -> our code changed.
@@ -37,34 +50,34 @@ async function readDeckFile(path) {
 // Deck files as live state: starts from the build-time glob snapshot and stays
 // current as files change on disk from any source (editors, agents, terminal).
 // `shouldSkipPath` lets an editor keep its own in-flight edits from being
-// clobbered by the fs echo of a stale write. `dataVersion` bumps on every
-// applied data change — key a player on it to rebuild from fresh data.
+// clobbered by the fs echo of a stale write.
 export function useLiveDeckFiles({ shouldSkipPath } = {}) {
   const [files, setFiles] = useState(initialFiles);
-  const [dataVersion, setDataVersion] = useState(0);
   const skipRef = useRef(shouldSkipPath);
   skipRef.current = shouldSkipPath;
 
   useEffect(
     () =>
       onFilesChanged((event) => {
-        if (event.changes.some(needsContextReload)) {
-          requestReload();
-          return;
-        }
+        const stale = event.changes.find(isCodeChange);
+        if (stale) console.log(`[reload] ${panelTag()} code stale <- ${stale.path}`);
+        // Data still applies in the same event: a change that carries both is
+        // one edit, and holding the data back would leave the panel showing
+        // neither the old state nor the new one.
         const dataChanges = event.changes.filter(
           (change) => isDataFile(change.path) && !skipRef.current?.(change.path)
         );
         if (dataChanges.length === 0) return;
-        void applyDataChanges(dataChanges, setFiles, setDataVersion);
+        console.log(`[reload] ${panelTag()} data <- ${dataChanges.map((c) => c.path).join(', ')}`);
+        void applyDataChanges(dataChanges, setFiles);
       }),
     []
   );
 
-  return { files, setFiles, dataVersion };
+  return { files, setFiles };
 }
 
-async function applyDataChanges(changes, setFiles, setDataVersion) {
+async function applyDataChanges(changes, setFiles) {
   const updates = await Promise.all(
     changes.map(async (change) => {
       if (change.event === 'delete') return { path: change.path, text: null };
@@ -85,5 +98,4 @@ async function applyDataChanges(changes, setFiles, setDataVersion) {
     }
     return next;
   });
-  setDataVersion((version) => version + 1);
 }

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

@@ -3,7 +3,7 @@
 // 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
+// updates. Empty in a kit with no `systems/` dir; a kit adds a
 // system by dropping a file here -- no edits to the engine required. Symmetric
 // with editors/behaviorRegistry.js.
 // Root-anchored, deck + imports (see engine/files.js).

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

@@ -740,8 +740,8 @@ function settleSheet(drag, setHeight, expandedRef) {
   const settled = setHeight(drag.startHeight - (drag.lastY - drag.startY));
   if (settled > peek + 2) expandedRef.current = settled;
 }
-// Persist a sheet's resting height across reloads (an agent's CODE edit
-// triggers requestReload, which would otherwise reset every sheet to the
+// Persist a sheet's resting height across reloads (picking up a code change
+// means reloading the panel, which would otherwise reset every sheet to the
 // default size). Keyed per sheet via `storageKey`; sessionStorage-scoped and
 // best-effort, the same degrade-to-memory-only contract as editorHistory.
 function sheetHeightStorageKey(key) {

package/kits/physics-2d/engine/ui.module.css

@@ -1550,6 +1550,11 @@
   cursor: default;
 }
 
+.button:disabled:hover,
+.iconButton:disabled:hover {
+  background: var(--castle-inspector-button-bg);
+}
+
 .actorList {
   display: grid;
   gap: 4px;
@@ -1608,6 +1613,13 @@
   display: none;
 }
 
+/* Read-only paint/inspector chrome: still there so the layout doesn't jump,
+   but clearly not interactive. */
+.drawingReadOnly {
+  opacity: 0.45;
+  pointer-events: none;
+}
+
 /* Stack the tool rail and the undo/redo rail vertically (the shared rule above is
    a flex row, which pushed the second rail out of the 50px column). */
 .artboardToolColumn {
@@ -1721,6 +1733,22 @@
   color: var(--castle-selected-ink);
 }
 
+.finishSegment:disabled {
+  cursor: default;
+  opacity: 0.4;
+}
+
+.finishSegment:disabled:hover {
+  background: var(--castle-inspector-button-bg);
+}
+
+.finishSegment.finishSegmentOn:disabled,
+.finishSegment.finishSegmentOn:disabled:hover {
+  opacity: 0.85;
+  background: var(--castle-selected);
+  color: var(--castle-selected-ink);
+}
+
 .canvasSizeSep {
   color: var(--castle-inspector-muted);
   user-select: none;
@@ -1742,6 +1770,12 @@
   background-position: right 6px center;
 }
 
+.canvasSizeSelect:disabled {
+  opacity: 0.55;
+  cursor: default;
+  color: var(--castle-inspector-muted);
+}
+
 .pxArtInspector {
   min-width: 0;
   border-left: 1px solid var(--castle-inspector-divider);
@@ -2121,6 +2155,14 @@
   cursor: default;
 }
 
+.drawingToolButton.drawingToolSelected:disabled {
+  opacity: 0.7;
+}
+
+.drawingToolButton:disabled:hover {
+  background: var(--castle-inspector-button-bg);
+}
+
 /* Active / selected square icon button -- the eyedropper reference: a light
    fill with a dark glyph. The single selected/engaged look shared by the
    IconButton component (`active`), the onion-skin toggle, and the pixel

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

@@ -0,0 +1,109 @@
+# physics-3d kit
+
+A 3D actor/behavior kit: three.js rendering with PBR lighting and rapier
+physics, built ON TOP of the `physics-2d` kit as an import. The actor /
+behavior / scene / blueprint model, deck file map, live reload, and the
+`.pxart` pixel-art pipeline (including its editor) all come from
+`imports/castle.physics-2d/` and work exactly as that kit's CLAUDE.md
+describes. This file covers what is different in 3D.
+
+## Quick reference
+
+<!-- Injected into Castle's create assistant every turn; keep this compact and factual. -->
+
+- 3D actor / behavior / scene framework: three.js + rapier, 1 unit = 1 meter,
+  y up. Scenes are `scenes/*.scene` (blueprints too, under `blueprints/`),
+  behaviors `behaviors/*.jsx` -- same JSON shapes as physics-2d, but the
+  component vocabulary is 3D (`Transform`, `Shape`, `Body`, `Solid`, ...).
+- Every actor needs a `Transform` (`x/y/z`, `rotationX/Y/Z` in degrees).
+  Every Transform actor gets a rapier body automatically -- fixed by default,
+  `Body { type: 'dynamic' }` to be simulated, `'kinematic'` to be unpushable
+  but follow Transform edits (doors, platforms).
+- Colliders come from `Shape` and are **sensors unless solid**: add a
+  `Solid {}` behavior (or `Shape.solid: true`) to block; leave it off for
+  pickups / trigger zones. Behaviors get `onCollisionEnter(actor, scene,
+other)` / `onCollisionExit` for both contacts and sensor overlaps.
+- `Shape`: `kind` `'box' | 'sphere' | 'capsule' | 'cylinder'` with
+  `width/height/depth` or `radius`, PBR knobs (`color`, `roughness`,
+  `metalness`, `clearcoat`, `emissive`, `emissiveIntensity`), and `art` -- a
+  `.pxart`/image path baked as a nearest-filtered albedo map. On boxes `art`
+  may be a per-face object `{ all, sides, front, back, left, right, top,
+bottom }`; any ref can pick a frame of a multi-frame pxart with
+  `path#<frame>`. A flat `color` with no art is a fine look.
+- Motion goes through `scene.physics3d`, never by writing a dynamic actor's
+  Transform: `setVelocity(actor, {x,y,z})`, `applyImpulse`, `getVelocity`,
+  `mass`, `castRay(origin, dir, maxToi, excludeActor)` (rays skip sensors).
+  Fixed/kinematic actors ARE moved by writing their Transform.
+- The scene has the lighting rig built in (hemisphere + ambient + one
+  shadow-casting sun, ground plane at y=0); meshes cast and receive shadows
+  automatically. Don't add your own lights for a normal scene.
+- Built-in gameplay behaviors: `Player` (WASD/arrows move, space jumps,
+  drag orbits the camera, faux-isometric follow cam), `Pickup` (sensor
+  collectible -> player score), `Door` (kinematic slide-up when the player is
+  near), `Lookable { text }` (hud caption when the player faces it nearby).
+- Hud: behaviors write `scene.hud = { score, look }`; the player behavior
+  already does.
+- Scene switching: place a `Portal { scene: 'scenes/other.scene' }` actor (a
+  sensor -- the portal blueprint is a glowing ring), or set
+  `scene.requestedScene = 'scenes/other.scene'` from any behavior (applied
+  between frames; safer than calling `scene.loadFromFile` mid-callback). A
+  load rebuilds the physics world and resets the scene to its authored state;
+  `scene.persistent` survives loads -- the player's score, collected-pickup
+  memory, and camera angle live there, so they cross scenes.
+- A scene can dress the ground: `"ground": { "art": "drawings/floor.pxart",
+"tile": 2, "color": "#..." }` at the scene file's top level (`tile` = meters
+  per texture repeat). `Shape.artRepeat: [u, v]` tiles a texture across a
+  face so long walls don't stretch.
+- `.scene` files open in the kit's 3d scene editor (same chrome as the 2d
+  kit's): blueprint hotbar (tap to inspect/edit the template, drag onto the
+  stage to place), orbit camera (drag orbits, wheel zooms), click to select /
+  click again to cycle / shift to multi-select, move & rotate gizmos (keys
+  1/2/3 pick select/move/rotate), floating clone/delete toolbar on the
+  selection, behavior-panel inspector with instance-override tints, undo/redo
+  (cmd+z / cmd+shift+z), cmd+d duplicate, delete key removes. `.pxart` opens
+  in the imported pixel-art editor.
+- Blueprint thumbnails in the hotbar / inspector are live 3d corner-view
+  renders of each template (engine3d/thumbnails.js) -- no icon data needed on
+  the blueprint.
+- 3d models are `.pxmodel` files under `models/` -- part-based JSON (named
+  primitive parts with hierarchy, per-part material/art), spec in
+  docs/pxmodel-format.md. A `Model` behavior (`{ file, scale, yOffset }`)
+  renders one instead of the Shape mesh; part ids legL/legR/armL/armR/torso
+  walk-animate automatically from observed motion. `.pxmodel` opens in the
+  kit's model editor (parts list, gizmos, part inspector, walk preview);
+  `scenes/model-lab.scene` is an all-model scene for trying it.
+- Controls are tank-style: W/S (or up/down) walk forward/back along facing,
+  A/D (or left/right) turn; a pointer/touch drag is a virtual stick where the
+  drag angle blends walking and turning. Space jumps.
+- After any edit: `npm run restart`. After a coherent change: `npm run check`
+  (lint + duplicate gate + single-file bundle) must pass.
+
+## What lives where
+
+- `engine3d/` -- the renderer (`world3d.js`, vase-style rig: PCFSoft shadows,
+  EffectComposer RenderPass + OutputPass), `materials.js` (pxart -> albedo
+  textures, per-face box materials), `Scene3DPlayer.jsx` / `PlayOnly3D.jsx`
+  (the play mount). Internal; behaviors shouldn't import from here.
+- `systems/physics3d.js` -- the rapier system, auto-discovered by the imported
+  engine's `systems/*.js` seam. Fixed 1/60 step, body-per-actor reconcile,
+  collision/overlap events, `scene.physics3d` API.
+- `behaviors/` -- the 3D component vocabulary plus gameplay behaviors. Same
+  rules as physics-2d: `static behaviorName`, `defaultProps`, per-frame
+  instances (state on `actor.runtime`).
+- `imports/castle.physics-2d/` -- read-only. Its engine modules are imported
+  directly (scene runtime, files, live reload, pxart, art, behavior
+  registry); its 2D-only pieces (canvas ScenePlayer, matter physics, 2D
+  editors other than pxart) are present but unused here.
+
+## Known state / caveats
+
+- The 2D kit's behaviors (Layout, Sprite, Collider, RigidBody, ...) are still
+  in the behavior registry via the import's root-anchored globs, and its
+  matter-js system installs (idle) into every runtime. Harmless but present;
+  don't attach 2D components to 3D actors.
+- Transform is the source of truth: dynamic bodies write back position (and
+  rotation unless `lockRotations`), fixed/kinematic bodies follow Transform.
+  A locked-rotation dynamic actor (the player) keeps `rotationY` free for
+  facing.
+- Space is bound to jump in this kit (unlike physics-2d, where the editor
+  reserves it).

package/kits/physics-3d/behaviors/Body.jsx

@@ -0,0 +1,51 @@
+// Physics options. Every actor with a Transform gets a rapier body whether or
+// not it carries this behavior -- fixed by default. Add a Body to opt into
+// motion: 'dynamic' is simulated (gravity, pushes), 'kinematic' is unpushable
+// but follows Transform edits with proper contact resolution (moving doors,
+// platforms). `lockRotations` keeps a dynamic body upright (characters).
+import React from 'react';
+import { SelectField } from '@imports/castle.physics-2d/engine/ui';
+import { AutoFields, overrideProps } from '@imports/castle.physics-2d/engine/autoInspector';
+
+const TYPE_OPTIONS = [
+  { value: 'fixed', label: 'Fixed' },
+  { value: 'dynamic', label: 'Dynamic' },
+  { value: 'kinematic', label: 'Kinematic' },
+];
+
+function BodyInspector({ component, setComponent, override }) {
+  return (
+    <>
+      <SelectField
+        label="Type"
+        value={component.type}
+        options={TYPE_OPTIONS}
+        onChange={(type) => setComponent({ type })}
+        {...overrideProps(override, 'type')}
+      />
+      <AutoFields
+        defaultProps={Body.defaultProps}
+        component={component}
+        setComponent={setComponent}
+        exclude={['type']}
+        override={override}
+      />
+    </>
+  );
+}
+
+export class Body {
+  static Inspector = BodyInspector;
+  static behaviorName = 'Body';
+  static defaultProps = {
+    type: 'fixed', // 'fixed' | 'dynamic' | 'kinematic'
+    friction: 0.6,
+    restitution: 0,
+    gravityScale: 1,
+    lockRotations: false,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+}