castle-web-cli 0.4.130 → 0.4.132

package/dist/agent-prompts.js

@@ -889,7 +889,7 @@ export function buildTaskPrompt(opts) {
             ? `\n- Before you finish, write these lines to ${opts.handoffPath} -- they are the ONLY record of this task once the task itself is forgotten:\n  - \`what: <what now exists, and where>\` -- an existence fact, not a report of activity: "a shop panel in ui/shop.js the bag button opens", never "updated the shop logic". This is what the plan shows as already built, so a later agent extends it instead of rebuilding it.\n  - \`files: <the files you created or changed, comma-separated>\`\n  - \`knobs: <the values worth tuning, comma-separated>\` -- names only, and only if there are real ones.\n  - \`durable: <fact>\` -- the single thing worth remembering that is NOT covered by the three above (a preference the user expressed, a constraint you ran into, an approach that did not work). At most 200 characters. Leave it out only if nothing genuinely qualifies.`
             : "",
     ].join("");
-    // Claude-only: collapsing the wrap-up (progress 90 + restart + notes) into
+    // Claude-only: collapsing the wrap-up (progress 90 + notes) into
     // one shell call reliably saves 1-2 serial ~7s turns there. Cursor's
     // composer sometimes reacts to the same rule with MORE calls, so it stays
     // on the plain instructions.
@@ -900,7 +900,7 @@ export function buildTaskPrompt(opts) {
         ? "the 90-progress write, the `castle-web save-version` for your paths, writing the notes file, and the handoff lines"
         : "the 90-progress write, the `castle-web save-version` for your paths, and writing the notes file";
     const wrapUp = opts.backend === "claude" || opts.backend === "smith"
-        ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine ${wrapUpList} into a single shell command (\`;\`-separated so the notes land even if the restart hiccups). Then stop -- no extra turns after it.`
+        ? `\n- Wrap up in ONE tool call, not several: once your last file edit is done, combine ${wrapUpList} into a single shell command (\`;\`-separated so the notes land even if an earlier part hiccups). Then stop -- no extra turns after it.`
         : "";
     return `You are a background build agent for the Castle deck "${opts.deckLabel}" (current directory). A separate conversation agent dispatched you with one task. Follow the deck's CLAUDE.md / AGENTS.md conventions. Do not reload the served deck -- the person applies your changes when they are ready. \`npm run restart\` exists, but it is HIGHLY flow breaking: it reloads every panel they have open, including the one they are working in. Use it only when a change clearly requires restarting their whole experience.${quickReference}${layout}${deckSource}
 

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

@@ -131,5 +131,5 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-08-21T22:11:52.086Z"
+  "publishedVersion": "2026-08-21T22:39:24.016Z"
 }

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

@@ -34,6 +34,7 @@ export function PlayOnly({ initialScene } = {}) {
       sprites={sprites}
       files={files}
       behaviorClasses={behaviorClasses}
+      scenePath={scenePath}
       onFirstFrame={Lifecycle.ready}
     />
   );

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

@@ -254,7 +254,7 @@ export function SceneEditor({
   // Sparse per-instance overrides merged with each actor's blueprint template
   // -- what hit-testing, drag-start snapshots, and the inspector should read.
   // Never the basis for a write (see engine/blueprint.js).
-  const previewSceneData = sceneData ? makeScene(sceneData, behaviorClasses, sprites, files).data : null;
+  const previewSceneData = sceneData ? makeScene(sceneData, behaviorClasses, sprites, files, path).data : null;
   const serialize = useCallback(
     (next) => formatJson(isBlueprintFile ? stripTemplateId(next) : next),
     [isBlueprintFile]
@@ -928,7 +928,7 @@ function useSelectionGesture(args) {
     const cam = current.editCameraRef.current;
     const point = { x: raw.x + cam.x, y: raw.y + cam.y };
     current.canvasRef.current.setPointerCapture(event.pointerId);
-    const scene = makeScene(current.sceneData, behaviorClasses, current.sprites, current.files);
+    const scene = makeScene(current.sceneData, behaviorClasses, current.sprites, current.files, current.path);
     const stack = scene.actorsAt(point.x, point.y);
     const stackIds = stack.map((a) => a.id);
     const actor = stack[0] ?? null;
@@ -1408,7 +1408,7 @@ function finalizeMarquee(drag, current) {
   const m = current.marqueeRef.current;
   if (!m || !current.sceneData) return;
   if (m.width === 0 && m.height === 0) return;
-  const scene = makeScene(current.sceneData, behaviorClasses, current.sprites, current.files);
+  const scene = makeScene(current.sceneData, behaviorClasses, current.sprites, current.files, current.path);
   const hits = scene.actorIdsInRect(m);
   const merged = new Set(drag.selectionBeforeMarquee);
   for (const id of hits) merged.add(id);
@@ -1511,7 +1511,7 @@ function useScenePlayLoop({
       return undefined;
     }
     if (!sceneData) return undefined;
-    const runtime = makeScene(sceneData, behaviorClasses, sprites, files).clone();
+    const runtime = makeScene(sceneData, behaviorClasses, sprites, files, path).clone();
     runtimeRef.current = runtime;
     // Pressing Stop has to stop what the runtime started -- a sound keeps
     // playing on its own otherwise, with no scene left to stop it.
@@ -1540,7 +1540,7 @@ function useScenePlayLoop({
         : editViewportForZoom(editCameraRef.current.zoom);
       const scene = isPlaying
         ? runtimeRef.current
-        : makeScene(sceneData, behaviorClasses, sprites, files);
+        : makeScene(sceneData, behaviorClasses, sprites, files, path);
       if (scene) {
         const snap = getSnapSettings(sceneData);
         if (isPlaying) scene.update(dt);

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

@@ -6,7 +6,7 @@ import { SceneUI } from './SceneUI';
 // behavior-driven UI overlay. No game logic lives here -- behaviors and
 // scenes are the place for that. The dev logs drawer is a builtin shell panel
 // now (cli/src/shell), not rendered here.
-export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirstFrame }) {
+export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, scenePath, onFirstFrame }) {
   const canvasRef = useRef(null);
   const runtimeRef = useRef(null);
   // An error thrown from a behavior's update/draw kills the raf loop (it can't
@@ -22,7 +22,7 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
     const ctx = canvas.getContext('2d');
     if (!ctx) return undefined;
     configureSceneCanvas(canvas, ctx);
-    const runtime = makeScene(sceneData, behaviorClasses, sprites, files).clone();
+    const runtime = makeScene(sceneData, behaviorClasses, sprites, files, scenePath).clone();
     runtimeRef.current = runtime;
     // Store BOTH the physical code ('KeyX', 'ArrowLeft', 'Space') and the
     // logical key ('x', 'ArrowLeft', ' ') so behaviors can match either. Codes

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

@@ -94,10 +94,16 @@ function resolveRefsIn(props, files, fromPath) {
 // 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) {
+export function getBlueprintTemplate(files, blueprintPath, fromPath) {
   // 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);
+  //
+  // `fromPath` is the file the ref was WRITTEN in, and it matters as soon as a
+  // kit is opened as an import: a scene at `imports/<alias>/scenes/main.scene`
+  // says `blueprints/wall.scene` meaning its own deck's, and resolving that
+  // against the deck root finds nothing -- every actor silently loses its
+  // template and renders as an untextured default.
+  const key = resolveDeckFile(blueprintPath, fromPath);
   const template = parseBlueprintText(files?.[key]);
   return resolveTemplateRefs(template, files, key);
 }

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

@@ -35,7 +35,12 @@ export class SceneRuntime {
   // actor's `blueprint` ref against the CURRENT blueprint file content -- not
   // a load-time snapshot -- so a blueprint edit propagates to every scene that
   // places it, in both the editor and play mode / `PlayOnly`.
-  constructor(sceneData, behaviors, sprites, files) {
+  constructor(sceneData, behaviors, sprites, files, scenePath) {
+    // The file this scene was read from, so blueprint refs in it resolve the
+    // way its own deck writes them. Undefined when a caller hands over scene
+    // data with no file behind it; refs then resolve against the deck root,
+    // which is what they meant before this existed.
+    this.scenePath = scenePath;
     this.behaviors = new Map(behaviors.map((Behavior) => [Behavior.behaviorName, Behavior]));
     this.sprites = sprites ?? {};
     this.files = files ?? {};
@@ -87,7 +92,7 @@ export class SceneRuntime {
     for (const actor of this.data.actors ?? []) {
       actor.runtime = {};
       if (actor.blueprint) {
-        const template = getBlueprintTemplate(this.files, actor.blueprint);
+        const template = getBlueprintTemplate(this.files, actor.blueprint, this.scenePath);
         actor.components = mergeComponents(template?.components, actor.components);
       }
       this.actors.set(actor.id, actor);
@@ -120,13 +125,20 @@ export class SceneRuntime {
   // Transition the running scene to the scene stored in the named file (read it
   // fresh, then load it). The building block for "go to scene" / restart.
   loadFromFile(name) {
+    this.scenePath = resolveSceneFileKey(name);
     this.load(this.readFromFile(name));
   }
 
   clone() {
     // Route through makeScene so the clone gets the same registered systems as a
     // freshly-made runtime.
-    return makeScene(this.serialize(), [...this.behaviors.values()], this.sprites, this.files);
+    return makeScene(
+      this.serialize(),
+      [...this.behaviors.values()],
+      this.sprites,
+      this.files,
+      this.scenePath
+    );
   }
 
   serialize() {
@@ -426,8 +438,8 @@ export class SceneRuntime {
   }
 }
 
-export function makeScene(sceneData, behaviors, sprites, files) {
-  const runtime = new SceneRuntime(sceneData, behaviors, sprites, files);
+export function makeScene(sceneData, behaviors, sprites, files, scenePath) {
+  const runtime = new SceneRuntime(sceneData, behaviors, sprites, files, scenePath);
   // Install any runtime systems the kit provides (systems/*.js) -- no-op in a kit
   // with none. A system's engine is created lazily on first use, so draw-only
   // editor previews (which never call update) stay free.

package/kits/physics-2d/scripts/svg-emission-guide.md

@@ -90,5 +90,6 @@ A curvy silhouette with an overlay accent (later shape covers earlier stroke):
 </svg>
 ```
 
-**After writing new sprites referenced by the scene, `npm run restart`** so the
-deck's file glob picks them up.
+A newly written sprite is not in the deck's file glob until the panel reloads,
+so an actor pointing at one renders the placeholder until then. That is fine --
+the person reloads when they are ready; do not force it.

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

@@ -43,9 +43,8 @@ bottom }`; any ref can pick a frame of a multi-frame pxart with
   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
+- Scene switching: 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
@@ -75,8 +74,11 @@ bottom }`; any ref can pick a frame of a multi-frame pxart with
 - 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.
+- Do not reload. Data edits (scenes, drawings, models) appear in the open
+  editors on their own. Code edits wait for the person to apply them --
+  reloading a panel someone is working in loses their place.
+- After a coherent change: `npm run check` (lint + duplicate gate +
+  single-file bundle) must pass.
 
 ## What lives where
 

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

@@ -3,7 +3,7 @@
 // instead of blocking, which is what fires onCollisionEnter here.
 //
 // Collection is remembered in the persistent store keyed by scene + actor id,
-// so walking back through a portal doesn't respawn (and double-count) shards
+// so re-entering a scene doesn't respawn (and double-count) shards
 // -- scene loads otherwise reset the world to its authored state.
 function pickupKey(scene, actor) {
   return `${scene.currentScenePath ?? ''}:${actor.id}`;

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

@@ -71,5 +71,5 @@
   "autoUpdateWhenImported": true,
   "deckId": "JH0SclbPVP0y",
   "cardId": "eXfAaUdbSU5A",
-  "publishedVersion": "2026-08-21T22:11:54.424Z"
+  "publishedVersion": "2026-08-21T22:39:26.451Z"
 }

package/kits/physics-3d/engine3d/PlayOnly3D.jsx

@@ -1,10 +1,14 @@
 // Play-mode entry point, the 3d counterpart of the imported kit's PlayOnly.
-// Files, assets, live reload, and the behavior registry all come from the
-// physics-2d import (they're renderer-agnostic); only the player is 3d.
+// Files, assets and the behavior registry all come from the physics-2d import
+// (they're renderer-agnostic); only the player is 3d.
+//
+// Nothing is folded into a run in progress: a file changing on disk can always
+// have altered how the run would have gone up to this point. Getting current is
+// a whole-panel reload, and the shell decides when.
 import React from 'react';
 import { Lifecycle } from 'castle-web-sdk';
 import { parseJsonFile } from '@imports/castle.physics-2d/engine/files';
-import { useLiveDeckFiles3D } from './modelFiles';
+import { initialFiles3D } from './modelFiles';
 import { collectAssets } from '@imports/castle.physics-2d/engine/assets';
 import { behaviorClasses } from '@imports/castle.physics-2d/editors/behaviorRegistry';
 import { Scene3DPlayer } from './Scene3DPlayer';
@@ -12,7 +16,7 @@ import { Scene3DPlayer } from './Scene3DPlayer';
 const DEFAULT_SCENE = 'scenes/main.scene';
 
 export function PlayOnly3D({ initialScene } = {}) {
-  const { files, dataVersion } = useLiveDeckFiles3D();
+  const files = initialFiles3D;
   const scenePath =
     initialScene && files[initialScene] !== undefined ? initialScene : DEFAULT_SCENE;
   const { value: sceneData } = parseJsonFile(scenePath, files[scenePath] ?? '');
@@ -20,7 +24,7 @@ export function PlayOnly3D({ initialScene } = {}) {
   const { sprites } = collectAssets(files);
   return (
     <Scene3DPlayer
-      key={`${scenePath}:${dataVersion}`}
+      key={scenePath}
       sceneData={sceneData}
       sprites={sprites}
       files={files}

package/kits/physics-3d/engine3d/Scene3DEditor.jsx

@@ -112,7 +112,7 @@ export function Scene3DEditor({ path }) {
   const sceneData = withTemplateId(parsed, isBlueprintFile);
   const sprites = useStableSprites(files);
   const previewSceneData = sceneData
-    ? makeScene(sceneData, behaviorClasses, sprites, files).data
+    ? makeScene(sceneData, behaviorClasses, sprites, files, path).data
     : null;
   const serialize = (next) => formatJson(isBlueprintFile ? stripTemplateId(next) : next);
   const commitScene = (next, options) => history.commit(serialize(next), options);
@@ -168,7 +168,7 @@ export function Scene3DEditor({ path }) {
     if (ed.lastAppliedText === text && ed.lastDataVersion === dataVersion) return;
     ed.lastAppliedText = text;
     ed.lastDataVersion = dataVersion;
-    setEditorScene(ed, sceneData, behaviorClasses, sprites, files);
+    setEditorScene(ed, sceneData, behaviorClasses, sprites, files, path);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [text, dataVersion]);
   useEffect(() => {

package/kits/physics-3d/engine3d/Scene3DPlayer.jsx

@@ -30,7 +30,7 @@ export function Scene3DPlayer({
   useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return undefined;
-    const runtime = makeScene(sceneData, behaviorClasses, sprites, files);
+    const runtime = makeScene(sceneData, behaviorClasses, sprites, files, scenePath);
     const world = makeWorld3D(canvas);
     runtime.three = world;
     runtime.hud = {};
@@ -200,8 +200,8 @@ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
     previousTime = now;
     try {
       runtime.update(dt);
-      // A Portal (or any behavior) may have requested a scene switch; apply
-      // it here, between frames, never mid physics dispatch. The load resets
+      // A behavior may have requested a scene switch; apply it here, between
+      // frames, never mid physics dispatch. The load resets
       // registered systems -- the rapier world frees and lazily rebuilds --
       // while `runtime.persistent` carries the player's cross-scene state.
       if (runtime.requestedScene) {
@@ -209,7 +209,7 @@ function startLoop(runtime, world, sprites, hudRefs, onFirstFrame, onError) {
         runtime.requestedScene = null;
         runtime.loadFromFile(next);
         runtime.currentScenePath = next;
-        runtime.persistent.portalGraceUntil = runtime.time + 1;
+        runtime.persistent.sceneChangeGraceUntil = runtime.time + 1;
       }
       syncActors(world, runtime, sprites, dt);
       if (world.debugLines.visible) updatePhysicsDebug(world, runtime.physics3d?.debugRender());

package/kits/physics-3d/engine3d/editorWorld.js

@@ -50,9 +50,9 @@ export function createEditorWorld(canvas, callbacks) {
 // Swap in fresh scene data (parsed file JSON). The display runtime is never
 // stepped -- actors sit at their authored Transforms; blueprints and default
 // props merge exactly as in play.
-export function setEditorScene(ed, sceneData, behaviors, sprites, files) {
+export function setEditorScene(ed, sceneData, behaviors, sprites, files, scenePath) {
   ed.runtime?.dispose();
-  ed.runtime = makeScene(sceneData, behaviors, sprites, files);
+  ed.runtime = makeScene(sceneData, behaviors, sprites, files, scenePath);
   ed.sprites = sprites;
 }
 

package/kits/physics-3d/engine3d/modelFiles.js

@@ -6,7 +6,7 @@
 // the files API instead of forcing a context reload (the glob puts models in
 // vite's module graph, which the imported hook would read as "code changed").
 import { useEffect, useRef, useState } from 'react';
-import { onFilesChanged, requestReload } from 'castle-web-sdk';
+import { onFilesChanged } from 'castle-web-sdk';
 import { initialFiles, initialMedia, isImageFile } from '@imports/castle.physics-2d/engine/files';
 import { parseFull } from '@imports/castle.physics-2d/engine/pxart';
 import { imageArt } from '@imports/castle.physics-2d/engine/art';
@@ -50,7 +50,7 @@ async function readDeckFile(path) {
   return typeof data.contents === 'string' ? data.contents : '';
 }
 
-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 };
@@ -71,36 +71,33 @@ async function applyDataChanges(changes, setFiles, setDataVersion) {
     }
     return next;
   });
-  setDataVersion((version) => version + 1);
 }
 
 // Live deck files including models. Same contract as the imported
 // useLiveDeckFiles: `shouldSkipPath` keeps an editor's in-flight writes from
-// being clobbered by their own fs echo; `dataVersion` bumps on applied data
-// changes.
+// being clobbered by their own fs echo.
+//
+// A code change does nothing here, matching the imported hook: only a page
+// reload picks up new code, and throwing one at a panel someone is working in
+// loses their place, so the panel header offers it instead.
 export function useLiveDeckFiles3D({ shouldSkipPath } = {}) {
   const [files, setFiles] = useState(initialFiles3D);
-  const [dataVersion, setDataVersion] = useState(0);
   const skipRef = useRef(shouldSkipPath);
   skipRef.current = shouldSkipPath;
 
   useEffect(
     () =>
       onFilesChanged((event) => {
-        if (event.changes.some(needsContextReload)) {
-          requestReload();
-          return;
-        }
         const dataChanges = event.changes.filter(
           (change) => isDataFile3D(change.path) && !skipRef.current?.(change.path)
         );
         if (dataChanges.length === 0) return;
-        void applyDataChanges(dataChanges, setFiles, setDataVersion);
+        void applyDataChanges(dataChanges, setFiles);
       }),
     []
   );
 
-  return { files, setFiles, dataVersion };
+  return { files, setFiles };
 }
 
 // The sprites map with parsed pxarts CACHED BY TEXT: re-parsing every file on

package/kits/physics-3d/scenes/main.scene

@@ -372,22 +372,6 @@
         }
       }
     },
-    {
-      "id": "portal-lab",
-      "blueprint": "blueprints/portal.scene",
-      "components": {
-        "Transform": {
-          "x": -8,
-          "z": 2
-        },
-        "Portal": {
-          "scene": "scenes/model-lab.scene"
-        },
-        "Lookable": {
-          "text": "a portal to the model lab."
-        }
-      }
-    },
     {
       "id": "crate",
       "blueprint": "blueprints/crate.scene",

package/kits/physics-3d/scenes/model-lab.scene

@@ -106,22 +106,6 @@
           "rotationY": 140
         }
       }
-    },
-    {
-      "id": "portal-courtyard",
-      "blueprint": "blueprints/portal.scene",
-      "components": {
-        "Transform": {
-          "x": -2,
-          "z": 8.6
-        },
-        "Portal": {
-          "scene": "scenes/main.scene"
-        },
-        "Lookable": {
-          "text": "a portal back to the courtyard."
-        }
-      }
     }
   ]
 }

package/package.json

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

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

@@ -1,19 +0,0 @@
-// Walk-through scene switching: a sensor actor (a glowing ring works well)
-// that asks the runtime to load another scene when the player touches it.
-// The request is applied by the player loop BETWEEN frames -- never mid
-// physics dispatch -- and a short grace after each switch keeps a portal from
-// instantly bouncing the player back where they came from.
-export class Portal {
-  static behaviorName = 'Portal';
-  static defaultProps = { scene: '' };
-
-  constructor(props) {
-    this.props = props;
-  }
-
-  onCollisionEnter(actor, scene, other) {
-    if (!other.components.Player || !this.props.scene) return;
-    if (scene.time < (scene.persistent?.portalGraceUntil ?? 0)) return;
-    scene.requestedScene = this.props.scene;
-  }
-}

package/kits/physics-3d/blueprints/portal.scene

@@ -1,21 +0,0 @@
-{
-  "name": "Portal",
-  "actors": [
-    {
-      "components": {
-        "Transform": { "y": 1.05, "rotationX": 90 },
-        "Shape": {
-          "kind": "cylinder",
-          "radius": 0.9,
-          "height": 0.16,
-          "color": "#0cf1ff",
-          "emissive": "#0cf1ff",
-          "emissiveIntensity": 0.65,
-          "roughness": 0.3
-        },
-        "Portal": {},
-        "Lookable": { "text": "a portal.", "range": 4.5 }
-      }
-    }
-  ]
-}