castle-web-cli 0.4.129 → 0.4.130

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

@@ -1,11 +1,10 @@
 # physics-2d kit
 
-This is the `basic-2d` actor/behavior/scene framework plus a built-in 2D
-**physics** system (matter-js). Everything in `basic-2d` works the same; physics
-adds `RigidBody`, physics fields on `Collider`, a world-gravity scene setting,
-collision callbacks, `Joints` that link actors (spring/rod/pin/weld/rope, several
-per actor), and ready-made touch-first controls (`Draggable`, `Slingshot`, `AnalogStick`).
-See `## Physics` below.
+An actor / behavior / scene framework for 2D games, with a built-in
+**physics** system (matter-js): `RigidBody`, physics fields on `Collider`, a
+world-gravity scene setting, collision callbacks, `Joints` that link actors
+(spring/rod/pin/weld/rope, several per actor), and ready-made touch-first
+controls (`Draggable`, `Slingshot`, `AnalogStick`). See `## Physics` below.
 
 ## Welcome message
 
@@ -25,7 +24,7 @@ Do you already know what you want to make, or do you want to figure it out toget
 - A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, and `Video` plays video files. Point their `file` at the deck path (`assets/logo.png`). For audio see `## Sound` below -- sound effects need no component at all.
 - **Supported media formats are exactly**: `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` images, `.mp3` `.wav` `.m4a` audio, `.mp4` (H.264) video. Nothing else — a published deck inlines every asset as a `data:` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (`.mov` is the classic case) can be dead once published. Convert, don't improvise.
 - This kit is plain JavaScript. Use `.jsx` for files with JSX, `.js` otherwise; do not add TypeScript files or a new build step.
-- After any code, scene, or drawing edit, run `npm run restart`.
+- Do not reload the deck after an edit. Nothing auto-reloads any more: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control.
 - Space is reserved by the editor for play/stop; do not bind Space to gameplay.
 - Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`, and the physics ones — `RigidBody.jsx`, `Joints.jsx`, `Draggable.jsx`, `Slingshot.jsx`, `AnalogStick.jsx`) to build a game. Their public API is documented below.
 - Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
@@ -57,8 +56,8 @@ Write the smallest game that satisfies what the user asked for. No sound, partic
 
 The deck is already serving when you start (`castle-web init` set that up; see `.castle/serve.json` for the URL). The user is watching that page right now. Your job is to make it interesting incrementally:
 
-1. **Build incrementally.** Start with the smallest playable thing (one mechanic, one scene change), `npm run restart`, then add the next piece. Do NOT write the whole game in one shot.
-2. **After every edit:** `npm run restart` (no hot reload). The served page refreshes and the user sees the change.
+1. **Build incrementally.** Start with the smallest playable thing (one mechanic, one scene change), then add the next piece. Do NOT write the whole game in one shot.
+2. **Do not reload.** Data edits (scenes, drawings, sprites) 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.
 3. **Prefer real, editable assets.** For game objects, characters, and scenery, make actual pixel-art sprites and place them as real actors in `scenes/*.scene` — not shapes drawn in code. Real assets let the creator move and re-skin things in the editor and let other creators remix the deck. Make art as `.sprite` via the `draw` command (see **Creating pixel art** below). Data-driven UI (health bars, score/text, HUD gauges) and dynamic things (bullets, particles, effects) are correctly procedural/code — don't force those into sprites.
 4. **Separate scenes per screen.** Use a separate `scenes/*.scene` file for each distinct screen — menu/title, each level, game-over, etc. — not one mega-scene. Each stays independently editable in the editor. Switch at runtime with `scene.loadFromFile('gameover.scene')` (reads the file and transitions) on play / win / level change. NEVER `import` a `.scene` file as a module — scene files are data, not modules; use `scene.readFromFile` / `scene.loadFromFile`.
 
@@ -477,7 +476,7 @@ Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a
   ```
 
   writes `drawings/ship.sprite`. You can also pass `--from file.svg` instead of stdin. An undecodable svg (no usable rects) errors with a nonzero exit and writes nothing.
-- **After writing, `npm run restart`.** Newly created files aren't in the kit's static glob until a restart; until then the missing-sprite fallback renders the placeholder (so an actor pointing at a not-yet-drawn `.sprite` is still playable).
+- **A newly created file is not in the kit's static glob until the panel reloads**, so until then the missing-sprite fallback renders the placeholder -- an actor pointing at a not-yet-drawn `.sprite` is still playable. Do not force a reload to fix it.
 
 Point a `Sprite` component's `file` at the generated `drawings/<name>.sprite` to put the art on an actor.
 

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

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

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

@@ -1,26 +1,35 @@
 import React from 'react';
 import { Lifecycle } from 'castle-web-sdk';
-import { parseJsonFile } from '../engine/files';
-import { useLiveDeckFiles } from '../engine/liveReload';
+import { initialFiles, parseJsonFile } from '../engine/files';
 import { collectAssets } from '../engine/assets';
 import { ScenePlayer } from '../engine/ScenePlayer';
 import { behaviorClasses } from './behaviorRegistry';
 // Play-mode entry point. Plays the scene named by `?scene=<path>` (the shell's
 // Play panel sets this), defaulting to `scenes/main.scene`. It renders ONLY the
 // game — the scene picker lives in the Play panel chrome (the shell), not here,
-// so nothing floats over the game surface and steals input. Files are live:
-// scene/drawing edits re-key the player against fresh data.
+// so nothing floats over the game surface and steals input.
+//
+// Nothing is folded into a run in progress -- not a drawing, not a scene. A
+// file changing on disk can always have altered how the run would have gone up
+// to this point, so applying one mid-run shows a state the deck could never
+// have reached.
+//
+// Getting current is therefore always a whole-panel reload, and the shell owns
+// when: it reloads Play on arrival if changes landed while it was hidden, and
+// offers the restart button when it is the panel you are looking at. A reload
+// remounts this and re-runs the build-time glob, so code and data arrive
+// together.
 const DEFAULT_SCENE = 'scenes/main.scene';
 
 export function PlayOnly({ initialScene } = {}) {
-  const { files, dataVersion } = useLiveDeckFiles();
+  const files = initialFiles;
   const scenePath = initialScene && files[initialScene] !== undefined ? initialScene : DEFAULT_SCENE;
   const { value: sceneData } = parseJsonFile(scenePath, files[scenePath] ?? '');
   if (!sceneData) return null;
   const { sprites } = collectAssets(files);
   return (
     <ScenePlayer
-      key={`${scenePath}:${dataVersion}`}
+      key={scenePath}
       sceneData={sceneData}
       sprites={sprites}
       files={files}

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

@@ -16,7 +16,7 @@ import {
   pickerPageIndexFor,
   pickerPagesFor,
 } from '../engine/palettes';
-import { EditorBody, Icon, IconButton, styles } from '../engine/ui';
+import { cx, EditorBody, Icon, IconButton, styles } from '../engine/ui';
 import { eventToCell, eventToPoint } from './pixelCanvas';
 import { forEachDab } from './pixelGeometry';
 import { drawPathOverlay } from './pathOverlay';
@@ -195,7 +195,22 @@ const PATH_ONLY_TOOL_IDS = new Set(
   )
 );
 
-export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
+// Layer-visibility overlay for a read-only file. The eye toggle stays live so
+// you can hide reference layers and read the sprite; it never writes.
+function applyLayerVisibility(sprite, overrides) {
+  if (!sprite || !overrides) return sprite;
+  let changed = false;
+  const layers = sprite.layers.map((layer, i) => {
+    if (!Object.prototype.hasOwnProperty.call(overrides, i) || overrides[i] === layer.visible) {
+      return layer;
+    }
+    changed = true;
+    return { ...layer, visible: overrides[i] };
+  });
+  return changed ? { ...sprite, layers } : sprite;
+}
+
+export function PxArtEditor({ path, text, onChange, files, readOnly = false, ...chrome }) {
   const canvasRef = useRef(null);
   const smoothRef = useRef(null);
   const overlayRef = useRef(null);
@@ -261,14 +276,22 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
     eraseSize,
     setEraseSize,
   } = toolState;
-  const { history, headerShell } = usePixelEditorShell(text, onChange, path);
+  const { history, headerShell } = usePixelEditorShell(text, onChange, path, { readOnly });
   const canvasWrapRef = useRef(null);
   const canvasSizeBarRef = useRef(null);
   const colorButtonRef = useRef(null);
   const editorBodyRef = useRef(null);
   const [paletteOpen, setPaletteOpen] = useState(false);
 
-  const sprite = deriveSprite(text);
+  const [visibilityOverrides, setVisibilityOverrides] = useState({});
+  // Drop browse-only hides when the file is replaced (import update, external
+  // edit). Eye toggles don't change `text`, so they survive. Indices would
+  // otherwise point at the wrong layer after a rewrite.
+  useEffect(() => {
+    setVisibilityOverrides({});
+  }, [path, text]);
+  const fileSprite = deriveSprite(text);
+  const sprite = readOnly ? applyLayerVisibility(fileSprite, visibilityOverrides) : fileSprite;
   const deckPalette = useMemo(() => deckPaletteFromFiles(files), [files]);
   const deckHexes = useMemo(() => pickerColorsFor(deckPalette.colors), [deckPalette]);
   const pages = useMemo(() => pickerPagesFor(deckPalette), [deckPalette]);
@@ -435,8 +458,8 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
     onGestureStart: abortStroke,
     onGestureMove: applyZoomPan,
     // Procreate convention: two-finger tap undoes, three-finger tap redoes.
-    onUndo: () => history.undo(),
-    onRedo: () => history.redo(),
+    onUndo: readOnly ? undefined : () => history.undo(),
+    onRedo: readOnly ? undefined : () => history.redo(),
   });
   // Middle-button drag pans by scrolling the viewport. Intercept in the capture
   // phase so the press never reaches the canvas's draw handler (startTool).
@@ -503,6 +526,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
     setEraseSize,
     setBrushMode,
     isPathLayer,
+    readOnly,
   });
   const isCompactLayout = useEditorCompactLayout(editorBodyRef);
   useEffect(() => {
@@ -680,7 +704,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
   // Escape deselects; Delete/Backspace clears the selected pixels. Both only
   // while the select tool is active and a marquee exists.
   useEffect(() => {
-    if (tool !== 'select' || !marquee) return undefined;
+    if (readOnly || tool !== 'select' || !marquee) return undefined;
     function onKeyDown(event) {
       if (event.metaKey || event.ctrlKey || event.altKey) return;
       if (isTypingTarget(event.target || document.activeElement)) return;
@@ -694,11 +718,11 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
     }
     window.addEventListener('keydown', onKeyDown);
     return () => window.removeEventListener('keydown', onKeyDown);
-  }, [tool, marquee, text, selection.layerIndex, selection.frameIndex]);
+  }, [readOnly, tool, marquee, text, selection.layerIndex, selection.frameIndex]);
   // Path-layer keyboard: pen close/open, shape/anchor delete / z-order / nudge / duplicate.
   // Plain [ / ] are free on path tools (brush-size adjust only binds on brush/erase).
   useEffect(() => {
-    if (!isPathLayer) return undefined;
+    if (readOnly || !isPathLayer) return undefined;
     function onKeyDown(event) {
       if (isTypingTarget(event.target || document.activeElement)) return;
       if (tool === 'brush') {
@@ -769,6 +793,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
     window.addEventListener('keydown', onKeyDown);
     return () => window.removeEventListener('keydown', onKeyDown);
   }, [
+    readOnly,
     isPathLayer,
     tool,
     brushMode,
@@ -810,13 +835,15 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
 
   const { width, height } = sprite.resolution;
   const overSelection = tool === 'select' && marquee && hoverCell && pointInRect(hoverCell, marquee);
-  const cursor = picking
-    ? 'crosshair'
-    : overSelection
-      ? 'move'
-      : isPathLayer && tool === 'brush'
-        ? 'crosshair'
-        : (TOOL_CURSORS[tool] ?? 'default');
+  const cursor = readOnly
+    ? 'default'
+    : picking
+      ? 'crosshair'
+      : overSelection
+        ? 'move'
+        : isPathLayer && tool === 'brush'
+          ? 'crosshair'
+          : (TOOL_CURSORS[tool] ?? 'default');
 
   function togglePalette(next) {
     setPaletteOpen((previous) => (typeof next === 'boolean' ? next : !previous));
@@ -1826,6 +1853,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
     // after clicking a non-focusable canvas, so we focus it explicitly. Done
     // before the early-return so even a click outside a cell claims focus.
     event.currentTarget.focus({ preventScroll: true });
+    if (readOnly) return;
     if (isPathLayer) {
       event.currentTarget.setPointerCapture(event.pointerId);
       const point = eventToPoint(event, width, height);
@@ -2212,6 +2240,8 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
     setPlaying,
     playing,
     setOnion,
+    readOnly,
+    setVisibilityOverrides,
   });
   function pickSampledKey(key) {
     if (key === TRANSPARENT) return;
@@ -2241,6 +2271,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
                   setTool(id);
                 }}
                 ariaLabel={isPathLayer ? 'Path tools' : 'Sprite tools'}
+                disabled={readOnly}
               />
               {/* Undo/redo in their own band below the tools (the flow mount shows
                   no editor header, so this is the on-screen affordance here). */}
@@ -2249,7 +2280,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
                   type="button"
                   title="Undo"
                   aria-label="Undo"
-                  disabled={!history.canUndo}
+                  disabled={readOnly || !history.canUndo}
                   className={styles.drawingToolButton}
                   onClick={history.undo}>
                   <Icon name="undo" />
@@ -2258,7 +2289,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
                   type="button"
                   title="Redo"
                   aria-label="Redo"
-                  disabled={!history.canRedo}
+                  disabled={readOnly || !history.canRedo}
                   className={styles.drawingToolButton}
                   onClick={history.redo}>
                   <Icon name="redo" />
@@ -2272,11 +2303,13 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
                     <CanvasSizeBar
                       width={width}
                       height={height}
+                      disabled={readOnly}
                       onResize={(w, h) => history.commit(serializeModel(resizeSprite(sprite, w, h)))}
                     />
                     <FinishBar
                       renderer={sprite.renderer}
                       cornerRadius={sprite.cornerRadius}
+                      disabled={readOnly}
                       onChange={(finish) => history.commit(serializeModel(setFinish(sprite, finish)))}
                     />
                   </div>
@@ -2299,18 +2332,25 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
                       ...latticeBackground(isPathLayer, artboardCanvasStyle, width, height),
                       cursor,
                     }}
-                    handlers={{
-                      onPointerDown: startTool,
-                      onPointerMove: handlePointerMove,
-                      onPointerUp: finishTool,
-                      onPointerCancel: finishTool,
-                      onPointerLeave: clearHover,
-                    }}
+                    handlers={
+                      readOnly
+                        ? {}
+                        : {
+                            onPointerDown: startTool,
+                            onPointerMove: handlePointerMove,
+                            onPointerUp: finishTool,
+                            onPointerCancel: finishTool,
+                            onPointerLeave: clearHover,
+                          }
+                    }
                   />
                 </div>
               </div>
             </div>
-            <div className={styles.paintColumn}>
+            <div
+              className={cx(styles.paintColumn, readOnly && styles.drawingReadOnly)}
+              aria-disabled={readOnly || undefined}
+              inert={readOnly || undefined}>
               <PaintStrip
                 toolState={toolState}
                 activeKey={paintKey}
@@ -2352,6 +2392,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
             playing={playing}
             onion={onion}
             actions={actions}
+            readOnly={readOnly}
           />
         </div>
         <PxArtInspectorDock
@@ -2369,6 +2410,7 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
           moveActions={moveActions}
           selectActions={selectActions}
           pathActions={isPathLayer ? pathActions : null}
+          readOnly={readOnly}
         />
       </div>
     </PxArtShell>
@@ -2378,9 +2420,22 @@ export function PxArtEditor({ path, text, onChange, files, ...chrome }) {
 // Build the timeline's mutation contract. Each action composes an immutable
 // model op with a history commit, updating the (layer, frame) selection where a
 // structural change moves it.
-function buildActions({ sprite, selection, history, setSelection, setPlaying, playing, setOnion }) {
+function buildActions({
+  sprite,
+  selection,
+  history,
+  setSelection,
+  setPlaying,
+  playing,
+  setOnion,
+  readOnly,
+  setVisibilityOverrides,
+}) {
   const { layerIndex, frameIndex } = selection;
-  const commit = (next) => history.commit(serializeModel(next));
+  const commit = (next) => {
+    if (readOnly) return;
+    history.commit(serializeModel(next));
+  };
   return {
     selectCell: (li, fi) => setSelection({ layerIndex: li, frameIndex: fi }),
     addLayer: (li, kind = 'pixel') => {
@@ -2399,7 +2454,15 @@ function buildActions({ sprite, selection, history, setSelection, setPlaying, pl
       commit(moveLayer(sprite, li, dir));
       setSelection({ layerIndex: li + dir, frameIndex });
     },
-    patchLayer: (li, patch) => commit(patchLayer(sprite, li, patch)),
+    patchLayer: (li, patch) => {
+      if (readOnly) {
+        if (typeof patch.visible === 'boolean') {
+          setVisibilityOverrides((prev) => ({ ...prev, [li]: patch.visible }));
+        }
+        return;
+      }
+      commit(patchLayer(sprite, li, patch));
+    },
     setLayerKind: (li, kind) => commit(setLayerKind(sprite, li, kind)),
     addFrame: (fi) => {
       commit(addFrame(sprite, fi));
@@ -2529,15 +2592,16 @@ function latticeBackground(isPathLayer, canvasStyle, gridWidth, gridHeight) {
 
 // Window-scoped tool keyboard shortcuts, mounted only while the editor is.
 function useToolShortcuts(ctx) {
-  const { tool, picking, brushMode, setTool, setPicking, setBrushSize, setEraseSize, setBrushMode, isPathLayer } =
+  const { tool, picking, brushMode, setTool, setPicking, setBrushSize, setEraseSize, setBrushMode, isPathLayer, readOnly } =
     ctx;
   useEffect(() => {
     function onKeyDown(event) {
+      if (readOnly) return;
       if (handleToolShortcut(event, ctx)) event.preventDefault();
     }
     window.addEventListener('keydown', onKeyDown);
     return () => window.removeEventListener('keydown', onKeyDown);
-  }, [tool, picking, brushMode, setTool, setPicking, setBrushSize, setEraseSize, setBrushMode, isPathLayer]);
+  }, [tool, picking, brushMode, setTool, setPicking, setBrushSize, setEraseSize, setBrushMode, isPathLayer, readOnly]);
 }
 
 function renderArtboard(canvas, sprite, frameIndex, onion, playing, preview) {

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

@@ -164,11 +164,11 @@ export function SceneEditor({
   const runtimeRef = useRef(null);
   const marqueeRef = useRef(null);
   // Ephemeral editor state (camera, play mode, inspected blueprint) restored
-  // across a reload: an agent's CODE edit triggers requestReload, which would
-  // otherwise reset the viewport/play state on every change. Data edits fold in
-  // live without a reload, so they never need this. `takeReloadState` is
-  // one-shot (clears on read), so read it once here. Selection is stashed
-  // separately by SingleEditor.
+  // across a reload: picking up a code change means reloading the panel, which
+  // would otherwise reset the viewport/play state. Data edits fold in live
+  // without a reload, so they never need this. `takeReloadState` is one-shot
+  // (clears on read), so read it once here. Selection is stashed separately by
+  // SingleEditor.
   const reloadStashKey = `scene-editor:${path}`;
   const [reloadStash] = useState(() => takeReloadState(reloadStashKey));
   const editCameraRef = useRef(reloadStash?.editCamera ?? { x: 0, y: 0, zoom: 1 });

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

@@ -5,7 +5,13 @@
 // file browsing and the code/text editor are now builtin shell panels.
 
 import React, { useEffect, useRef, useState } from 'react';
-import { onBeforeRestart, onSaveReloadState, takeReloadState, writeFile } from 'castle-web-sdk';
+import {
+  isImportedFile,
+  onBeforeRestart,
+  onSaveReloadState,
+  takeReloadState,
+  writeFile,
+} from 'castle-web-sdk';
 import { getFileKind } from '../engine/files';
 import { hasEditorModule, loadEditorModule } from './editorRegistry';
 import { useLiveDeckFiles } from '../engine/liveReload';
@@ -24,6 +30,9 @@ function useFileSaver() {
   const versions = useRef({});
   const pending = useRef({});
   function commit(path, text, version) {
+    // Imports are someone else's deck. The serve refuses these writes anyway;
+    // skip the request so a missed UI lock doesn't look like a save that failed.
+    if (isImportedFile(path)) return Promise.resolve();
     return writeFile(path, text)
       .then(() => {
         if (versions.current[path] === version && pending.current[path] === text) {
@@ -37,6 +46,7 @@ function useFileSaver() {
       });
   }
   function schedule(path, text) {
+    if (isImportedFile(path)) return;
     const version = (versions.current[path] ?? 0) + 1;
     versions.current[path] = version;
     pending.current[path] = text;
@@ -71,7 +81,7 @@ function useFileSaver() {
 // 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 }) {
+function DeclaredEditor({ path, module: modulePath, text, onChange, files, onChangeFile, readOnly }) {
   const [Editor, setEditor] = useState(null);
   const [error, setError] = useState(null);
   useEffect(() => {
@@ -89,7 +99,14 @@ function DeclaredEditor({ path, module: modulePath, text, onChange, files, onCha
   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} />
+    <Editor
+      path={path}
+      text={text}
+      onChange={onChange}
+      files={files}
+      onChangeFile={onChangeFile}
+      readOnly={readOnly}
+    />
   );
 }
 
@@ -101,7 +118,7 @@ export function SingleEditor({ path, editor, editorModule }) {
   const { schedule, hasPending } = useFileSaver();
   // Live deck files; our own in-flight (debounced, unsaved) edits win over the
   // fs echo of a stale write, so a drag in progress isn't clobbered.
-  const { files, setFiles } = useLiveDeckFiles({ shouldSkipPath: hasPending });
+  const { files, setFiles, hydrated } = useLiveDeckFiles({ shouldSkipPath: hasPending, ensurePath: path });
   const [selectedActorIds, setSelectedActorIds] = useState(stash?.selectedActorIds ?? []);
   const [multiSelectMode, setMultiSelectMode] = useState(stash?.multiSelectMode ?? false);
   useEffect(
@@ -109,12 +126,17 @@ export function SingleEditor({ path, editor, editorModule }) {
     [stashKey, selectedActorIds, multiSelectMode]
   );
   const { sprites } = collectAssets(files);
+  // The serve refuses writes under `imports/`. Lock the UI to match so an
+  // editor doesn't collect keystrokes / clicks that can never be saved.
+  const readOnly = isImportedFile(path);
   // Optimistic cross-file edit: fold the new text into live files state NOW
   // (so merged previews update this frame) and debounce the real write; the
   // fs echo of our own write is skipped while pending (shouldSkipPath above).
   // Used for this editor's own file AND for blueprint-file edits made from a
-  // scene panel's blueprint inspector.
+  // scene panel's blueprint inspector. An imported target is skipped entirely
+  // -- even the optimistic fold -- so a missed lock can't fake a local edit.
   function onChangeFile(targetPath, nextText) {
+    if (isImportedFile(targetPath)) return;
     setFiles((current) => ({ ...current, [targetPath]: nextText }));
     schedule(targetPath, nextText);
   }
@@ -128,7 +150,13 @@ export function SingleEditor({ path, editor, editorModule }) {
   // 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 = (
+    // A declared type is not in engine/files.js's glob, so its text arrives from
+    // the serve a moment after mount. Wait for it: an editor handed '' for a
+    // file that exists renders its empty state, and one edit there overwrites
+    // the real document.
+    body = !hydrated && files[path] === undefined ? (
+      <div className={styles.editorBody}>loading…</div>
+    ) : (
       <DeclaredEditor
         path={path}
         module={editorModule}
@@ -136,6 +164,7 @@ export function SingleEditor({ path, editor, editorModule }) {
         onChange={onChange}
         files={files}
         onChangeFile={onChangeFile}
+        readOnly={readOnly}
       />
     );
   } else if (kind === 'scene') {
@@ -154,9 +183,9 @@ export function SingleEditor({ path, editor, editorModule }) {
       />
     );
   } else if (kind === 'pxart') {
-    body = <PxArtEditor path={path} text={text} onChange={onChange} files={files} />;
+    body = <PxArtEditor path={path} text={text} onChange={onChange} files={files} readOnly={readOnly} />;
   } else if (kind === 'style') {
-    body = <StyleEditor path={path} text={text} onChange={onChange} />;
+    body = <StyleEditor path={path} text={text} onChange={onChange} readOnly={readOnly} />;
   } else if (kind === 'image') {
     // Viewers read their file's BYTES over the serve, not the text file map --
     // `files` holds source, and an image decoded as utf-8 is nothing.

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

@@ -1,7 +1,9 @@
 // Deck-palette picker for `theme.style`. Official entries come from
 // OFFICIAL_PALETTES; a custom `{ name, colors }` in the file shows as a
 // read-only selected card. Opening the editor never writes — only an
-// explicit official pick does.
+// explicit official pick does. An imported file is the same static-card
+// treatment applied to the whole catalog: still a viewer of what's selected,
+// never a picker.
 
 import { createElement } from 'react';
 import { OFFICIAL_PALETTES, parseThemeData, resolveDeckPalette } from '../engine/palettes';
@@ -58,10 +60,11 @@ function customCardName(palette) {
   return name && name !== 'custom' ? name : 'Custom';
 }
 
-export function StyleEditor({ text, onChange }) {
+export function StyleEditor({ text, onChange, readOnly = false }) {
   const current = resolveDeckPalette(parseThemeData(text));
   const isCustom = current.id == null;
   function pick(id) {
+    if (readOnly) return;
     onChange(applyOfficialPalette(text, id));
   }
   return createElement(
@@ -76,7 +79,7 @@ export function StyleEditor({ text, onChange }) {
             badge: 'Custom',
           })
         : null}
-      {isCustom ? (
+      {isCustom && !readOnly ? (
         <p className={styles.replaceNote}>Picking an official palette replaces this custom palette.</p>
       ) : null}
       <div className={styles.list}>
@@ -86,7 +89,7 @@ export function StyleEditor({ text, onChange }) {
             name: palette.name,
             colors: palette.colors,
             selected: current.id === palette.id,
-            onPick: () => pick(palette.id),
+            onPick: readOnly ? undefined : () => pick(palette.id),
           })
         )}
       </div>

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

@@ -5,18 +5,18 @@ import { useEditHistory, useUndoRedoShortcuts } from './editorHistory';
 // Shared shell state for the pixel editors: text undo/redo history and undo/redo
 // keyboard shortcuts. Returns the `history` controller and `headerShell` for the
 // header (undo/redo only — paint controls live in the artboard layout).
-export function usePixelEditorShell(text, onChange, path) {
+export function usePixelEditorShell(text, onChange, path, { readOnly = false } = {}) {
   const history = useEditHistory(text, onChange, path);
-  useUndoRedoShortcuts(history);
-  const headerShell = { history };
+  useUndoRedoShortcuts(history, !readOnly);
+  const headerShell = { history, readOnly };
   return { history, headerShell };
 }
 
-function PixelEditorTools({ history }) {
+function PixelEditorTools({ history, readOnly }) {
   return (
     <>
-      <IconButton icon="undo" label="Undo" onClick={history.undo} disabled={!history.canUndo} />
-      <IconButton icon="redo" label="Redo" onClick={history.redo} disabled={!history.canRedo} />
+      <IconButton icon="undo" label="Undo" onClick={history.undo} disabled={readOnly || !history.canUndo} />
+      <IconButton icon="redo" label="Redo" onClick={history.redo} disabled={readOnly || !history.canRedo} />
     </>
   );
 }
@@ -27,7 +27,7 @@ export function PixelEditorHeader({ title, subtitle, shell, chrome }) {
     <EditorHeader
       title={title}
       subtitle={subtitle}
-      right={<PixelEditorTools history={shell.history} />}
+      right={<PixelEditorTools history={shell.history} readOnly={shell.readOnly} />}
       onToggleFiles={chrome.onToggleFiles}
       filesOpen={chrome.filesOpen}
       headerHost={chrome.headerHost}