castle-web-cli 0.4.84 → 0.4.85

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

@@ -0,0 +1,1681 @@
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { onSaveReloadState, takeReloadState, writeFile } from 'castle-web-sdk';
+import { basename, formatJson, parseJsonFile } from '../engine/files';
+import {
+  arrangeActors,
+  cardSize,
+  configureSceneCanvas,
+  duplicateActors,
+  makeScene,
+  mintActorId,
+  removeActorComponent,
+  removeActors,
+  screenToCard,
+  setActorComponent,
+} from '../engine/scene';
+import {
+  addActorWithBlueprint,
+  blueprintDropXY,
+  cascadeDeleteBlueprint,
+  countBlueprintInstances,
+  forkActorToBlueprint,
+  getBlueprintTemplate,
+  isBlueprintPath,
+  isInheritedProp,
+  migrateOrphanActors,
+  placeBlueprintInstance,
+  setBlueprintName,
+  setBlueprintTemplateComponents,
+  setInstanceComponent,
+} from '../engine/blueprint';
+import {
+  cx,
+  CheckboxField,
+  ColorField,
+  ConfirmDialog,
+  EditorBody,
+  EditorHeader,
+  Icon,
+  IconButton,
+  NumberField,
+  Panel,
+  SheetGrabHandle,
+  styles,
+  TextField,
+  useMobileSheet,
+} from '../engine/ui';
+import { AutoInspector } from '../engine/autoInspector';
+import { SceneUI } from '../engine/SceneUI';
+import { SelectionOverlay } from './SelectionOverlay';
+import { BlueprintLibrary, BlueprintThumbnail } from './BlueprintLibrary';
+import { behaviorClasses, findBehaviorClass } from './behaviorRegistry';
+import { useEditHistory, useUndoRedoShortcuts } from './editorHistory';
+// A blueprint file's `actors[0]` has no `id` (it's the template, not an
+// instance) -- injected/stripped at the read/write boundary below so the rest
+// of this editor (selection, drag, inspector) can keep treating it like any
+// other single-actor scene.
+const BLUEPRINT_TEMPLATE_ACTOR_ID = '__template__';
+const LONG_PRESS_MS = 500;
+const DRAG_THRESHOLD = 4;
+const DEFAULT_GRID_SIZE = 25;
+const EDIT_VIEWPORT = {
+  width: cardSize.width * 3,
+  height: cardSize.height * 3,
+  originX: cardSize.width,
+  originY: cardSize.height,
+};
+// Edit-camera zoom bounds. zoom > 1 magnifies (the visible viewport shrinks);
+// zoom < 1 pulls back to show more around the card.
+const MIN_EDIT_ZOOM = 0.4;
+const MAX_EDIT_ZOOM = 6;
+// Wheel-delta -> zoom-factor sensitivity for trackpad pinch (ctrl+wheel).
+const ZOOM_WHEEL_SPEED = 0.01;
+const clampZoom = (zoom) =>
+  Math.min(MAX_EDIT_ZOOM, Math.max(MIN_EDIT_ZOOM, Number(zoom) || 1));
+// Derive the effective edit viewport for a zoom level. Both extent and origin
+// scale by 1/zoom, which keeps the canvas draw path, `screenToCard`, and the
+// SelectionOverlay's `sx = box/card` projection mutually consistent (the overlay
+// just multiplies its scale by the same zoom).
+function editViewportForZoom(zoom) {
+  const z = clampZoom(zoom);
+  return {
+    width: EDIT_VIEWPORT.width / z,
+    height: EDIT_VIEWPORT.height / z,
+    originX: EDIT_VIEWPORT.originX / z,
+    originY: EDIT_VIEWPORT.originY / z,
+  };
+}
+// A blueprint file on disk has no `id` on its template actor -- inject a
+// synthetic one so every other piece of editor code that expects `actor.id`
+// (selection, drag, inspector lookups) keeps working unmodified. Stripped
+// again by `stripTemplateId` right before a write (see `serialize` below).
+function withTemplateId(sceneData, isBlueprintFile) {
+  if (!sceneData || !isBlueprintFile) return sceneData;
+  const next = structuredClone(sceneData);
+  next.actors = next.actors ?? [];
+  if (next.actors[0]) next.actors[0].id = BLUEPRINT_TEMPLATE_ACTOR_ID;
+  return next;
+}
+function stripTemplateId(sceneData) {
+  const next = structuredClone(sceneData);
+  if (next.actors?.[0]) delete next.actors[0].id;
+  return next;
+}
+// On opening a scene with orphan actors (no `blueprint` field -- the
+// pre-blueprint shape), mint one blueprint per orphan and rewrite the scene
+// in place. Runs once per distinct file text; the blueprint-file writes are
+// fire-and-forget (they're brand new files, nothing else references them
+// yet) while the scene rewrite goes through this file's own `onChange` so it
+// picks up the normal history/live-reload path.
+function useMigrateOrphanActors({ isBlueprintFile, sceneData, files, text, onChange }) {
+  useEffect(() => {
+    if (isBlueprintFile || !sceneData) return;
+    const hasOrphans = (sceneData.actors ?? []).some((actor) => !actor.blueprint);
+    if (!hasOrphans) return;
+    const { sceneData: migrated, newBlueprintFiles } = migrateOrphanActors(files, behaviorClasses, sceneData);
+    for (const blueprintFile of newBlueprintFiles) void writeFile(blueprintFile.path, blueprintFile.text);
+    onChange(formatJson(migrated));
+    // Re-run only when this file's own text changes (e.g. after the migration
+    // write lands, or the user opens a different orphaned file) -- `files`
+    // changes on every keystroke elsewhere and would otherwise loop.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [text, isBlueprintFile]);
+}
+export function SceneEditor({
+  path,
+  text,
+  files,
+  sprites,
+  onChange,
+  onChangeFile,
+  onToggleFiles,
+  filesOpen,
+  headerHost,
+  selectedActorIds,
+  onSelectActorIds: onSelectActorIdsRaw,
+  multiSelectMode,
+  onSetMultiSelectMode,
+}) {
+  const canvasRef = useRef(null);
+  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.
+  const reloadStashKey = `scene-editor:${path}`;
+  const [reloadStash] = useState(() => takeReloadState(reloadStashKey));
+  const editCameraRef = useRef(reloadStash?.editCamera ?? { x: 0, y: 0, zoom: 1 });
+  const selectedActorIdsRef = useRef(selectedActorIds);
+  selectedActorIdsRef.current = selectedActorIds;
+  const [isPlaying, setIsPlaying] = useState(reloadStash?.isPlaying ?? false);
+  // Hotbar blueprint selection (tap a slot -> inspect/edit the blueprint in
+  // the sidebar; drag remains the placement gesture). Mutually exclusive with
+  // actor selection: ANY actor-selection change -- including clearing it via
+  // empty-canvas click or Escape -- also drops the blueprint selection, which
+  // is why every internal caller goes through the wrapper below.
+  const [selectedBlueprintPath, setSelectedBlueprintPath] = useState(
+    reloadStash?.selectedBlueprintPath ?? null
+  );
+  // Read live in the render loop (a ref so changing it doesn't restart the
+  // loop): while a blueprint is selected, its instances stay lit and every
+  // other actor dims. Assigned below once `hotbarBlueprint` resolves, so a
+  // stale/deleted selection (file vanished) doesn't dim the scene with nothing
+  // to highlight.
+  const selectedBlueprintPathRef = useRef(selectedBlueprintPath);
+  const onSelectActorIds = useCallback(
+    (ids) => {
+      setSelectedBlueprintPath(null);
+      onSelectActorIdsRaw(ids);
+    },
+    [onSelectActorIdsRaw]
+  );
+  const onSelectBlueprint = useCallback(
+    (blueprintPath) => {
+      onSelectActorIdsRaw([]);
+      onSetMultiSelectMode(false);
+      setSelectedBlueprintPath(blueprintPath);
+    },
+    [onSelectActorIdsRaw, onSetMultiSelectMode]
+  );
+  const isBlueprintFile = isBlueprintPath(path);
+  // Working state for an in-progress hotbar drag-placement (see `dragPlace`
+  // below). A ref, not state: pointer moves can outpace re-renders.
+  const dragPlaceRef = useRef(null);
+  const history = useEditHistory(text, onChange, path);
+  // Disabled during play: the header undo/redo buttons are already disabled
+  // then, but without this the keyboard shortcut could still rewrite the
+  // scene file out from under the running play-mode runtime.
+  useUndoRedoShortcuts(history, !isPlaying);
+  // Stash ephemeral editor state right before a reload so it survives an agent
+  // code edit. `editCamera` is read live from the ref at save time (a reload is
+  // imminent, so the latest value is what matters); isPlaying / blueprint
+  // selection re-register whenever they change.
+  useEffect(
+    () =>
+      onSaveReloadState(reloadStashKey, () => ({
+        isPlaying,
+        selectedBlueprintPath,
+        editCamera: editCameraRef.current,
+      })),
+    [reloadStashKey, isPlaying, selectedBlueprintPath]
+  );
+  const showMulti = !isBlueprintFile && (selectedActorIds.length > 1 || multiSelectMode);
+  const inspectorSheet = useSelectionInspectorSheet(true);
+  const { value: parsedSceneData, error } = parseJsonFile(path, text);
+  const sceneData = withTemplateId(parsedSceneData, isBlueprintFile);
+  // 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 serialize = useCallback(
+    (next) => formatJson(isBlueprintFile ? stripTemplateId(next) : next),
+    [isBlueprintFile]
+  );
+  const getRuntime = useCallback(() => runtimeRef.current, []);
+  useMigrateOrphanActors({ isBlueprintFile, sceneData, files, text, onChange });
+  useScenePlayLoop({
+    sceneData,
+    sprites,
+    files,
+    isPlaying,
+    text,
+    canvasRef,
+    runtimeRef,
+    editCameraRef,
+    marqueeRef,
+    selectedActorIdsRef,
+    selectedBlueprintPathRef,
+  });
+  const panGesture = usePanGesture({ canvasRef, editCameraRef, isPlaying });
+  useScenePlayKeys(runtimeRef);
+  const gesture = useSelectionGesture({
+    canvasRef,
+    sceneData,
+    sprites,
+    files,
+    isPlaying,
+    selectedActorIds,
+    onSelectActorIds,
+    multiSelectMode: showMulti && multiSelectMode,
+    onSetMultiSelectMode,
+    marqueeRef,
+    editCameraRef,
+    applyScene: (next) => onChange(serialize(next)),
+    recordSceneSnapshot: history.recordSnapshot,
+  });
+  const playPointer = usePlayPointerGesture({ canvasRef, runtimeRef });
+  useSelectionKeyboard({
+    sceneData,
+    selectedActorIds,
+    selectedBlueprintPath,
+    onSelectActorIds,
+    multiSelectMode,
+    onSetMultiSelectMode,
+    isPlaying,
+    isBlueprintFile,
+    commitScene: (next) => history.commit(serialize(next)),
+  });
+  if (!sceneData) {
+    return (
+      <>
+        <EditorHeader
+          title={basename(path)}
+          onToggleFiles={onToggleFiles}
+          filesOpen={filesOpen}
+          headerHost={headerHost}
+        />
+        <EditorBody>
+          <div className={styles.inspector}>{error}</div>
+        </EditorBody>
+      </>
+    );
+  }
+  const rawSelectedActor =
+    selectedActorIds.length === 1
+      ? sceneData.actors.find((actor) => actor.id === selectedActorIds[0])
+      : undefined;
+  const selectedActor =
+    selectedActorIds.length === 1
+      ? previewSceneData.actors.find((actor) => actor.id === selectedActorIds[0])
+      : undefined;
+  const selectedBlueprintTemplate = rawSelectedActor?.blueprint
+    ? getBlueprintTemplate(files, rawSelectedActor.blueprint)
+    : undefined;
+  const selectedBlueprintName = rawSelectedActor?.blueprint
+    ? selectedBlueprintTemplate?.name ?? basename(rawSelectedActor.blueprint)
+    : undefined;
+  // Hotbar-selected blueprint, resolved fresh from live files each render. A
+  // selection whose file vanished (cascade delete, external edit) degrades to
+  // "nothing selected" rather than a broken inspector.
+  const hotbarBlueprint =
+    !isBlueprintFile && selectedBlueprintPath
+      ? getBlueprintTemplate(files, selectedBlueprintPath)
+      : null;
+  // Only dim for a blueprint that actually resolves to an inspectable template
+  // (mirrors the sidebar): a vanished/stale selection highlights nothing.
+  selectedBlueprintPathRef.current = hotbarBlueprint ? selectedBlueprintPath : null;
+  // Template edits from the sidebar write the BLUEPRINT file, not this scene:
+  // optimistic fold into live files state (instant merged-instance updates
+  // here) + debounced writeFile via SingleEditor's saver, which also makes
+  // `shouldSkipPath` ignore the fs echo of our own write. Same plain
+  // per-property merge semantics as editing the blueprint's own file. Outside
+  // this scene file's undo history (accepted v1 cross-file gap, like fork).
+  const updateBlueprintTemplate = (mutate) => {
+    if (!selectedBlueprintPath || !hotbarBlueprint) return;
+    const components = structuredClone(hotbarBlueprint.components);
+    mutate(components);
+    const nextText = setBlueprintTemplateComponents(files, selectedBlueprintPath, components);
+    if (nextText == null) return;
+    if (onChangeFile) onChangeFile(selectedBlueprintPath, nextText);
+    else void writeFile(selectedBlueprintPath, nextText);
+  };
+  const blueprintActions = {
+    setComponent: (behaviorName, nextProps) =>
+      updateBlueprintTemplate((components) => {
+        components[behaviorName] = { ...(components[behaviorName] ?? {}), ...nextProps };
+      }),
+    addBehavior: (behaviorName) => {
+      const Behavior = findBehaviorClass(behaviorName);
+      if (!Behavior) return;
+      updateBlueprintTemplate((components) => {
+        components[behaviorName] = { ...Behavior.defaultProps };
+      });
+    },
+    removeBehavior: (behaviorName) =>
+      updateBlueprintTemplate((components) => {
+        delete components[behaviorName];
+      }),
+    // Renaming writes only the blueprint file's top-level `name` (not this
+    // scene), so it flows through the same optimistic files update + debounced
+    // writeFile path as template edits above.
+    rename: (name) => {
+      if (!selectedBlueprintPath) return;
+      const nextText = setBlueprintName(files, selectedBlueprintPath, name);
+      if (nextText == null) return;
+      if (onChangeFile) onChangeFile(selectedBlueprintPath, nextText);
+      else void writeFile(selectedBlueprintPath, nextText);
+    },
+  };
+  const actions = makeSceneActions({
+    sceneData,
+    files,
+    serialize,
+    commit: history.commit,
+    selectedActorIds,
+    onSelectActorIds,
+    isBlueprintFile,
+  });
+  const snapSettings = getSnapSettings(sceneData);
+  const stageWrapStyle = {
+    backgroundColor: darkenSceneBackground(sceneData.background),
+  };
+  const updateSceneSettings = (nextScene) => {
+    history.commit(serialize(setSceneSettings(sceneData, nextScene)));
+  };
+  const updateSceneEditorSettings = (nextEditor) => {
+    history.commit(serialize(setSceneEditorSettings(sceneData, nextEditor)));
+  };
+  const onAddActor = () => {
+    const { sceneData: next, newId, blueprintFile, drawingFile } = addActorWithBlueprint(
+      sceneData,
+      files
+    );
+    void writeFile(drawingFile.path, drawingFile.text);
+    void writeFile(blueprintFile.path, blueprintFile.text);
+    history.commit(serialize(next));
+    onSelectActorIds([newId]);
+  };
+  // Drag-out from the hotbar places a REAL instance the moment the pointer
+  // enters the stage, so the rest of the drag is a normal grid-snapped actor
+  // move and the drop is just "let go" (castle-client belt behavior). One
+  // undo entry per gesture: a snapshot at entry, then plain onChange while
+  // the drag is live. Leaving the stage removes the actor again (back to the
+  // floating preview), which lands the text back at the snapshot -- the
+  // history's no-op trimming keeps undo clean. `dragPlaceRef` carries the
+  // working scene between pointer events so a move never applies to a parse
+  // that predates the placement.
+  const dragPlace = {
+    enter: (blueprintPath, position) => {
+      history.recordSnapshot();
+      const { sceneData: next, newId } = placeBlueprintInstance(sceneData, files, blueprintPath, position, snapSettings);
+      const layout = next.actors.find((actor) => actor.id === newId)?.components?.Layout ?? {};
+      dragPlaceRef.current = { actorId: newId, blueprintPath, sceneData: next, x: layout.x, y: layout.y };
+      onChange(serialize(next));
+      onSelectActorIds([newId]);
+    },
+    move: (position) => {
+      const drag = dragPlaceRef.current;
+      if (!drag) return;
+      const { x, y } = blueprintDropXY(files, drag.blueprintPath, position, snapSettings);
+      if (x === drag.x && y === drag.y) return;
+      const next = structuredClone(drag.sceneData);
+      const actor = next.actors.find((candidate) => candidate.id === drag.actorId);
+      if (!actor) return;
+      actor.components.Layout = { ...actor.components.Layout, x, y };
+      Object.assign(drag, { sceneData: next, x, y });
+      onChange(serialize(next));
+    },
+    leave: () => {
+      const drag = dragPlaceRef.current;
+      if (!drag) return;
+      dragPlaceRef.current = null;
+      onChange(serialize(removeActors(drag.sceneData, [drag.actorId])));
+      onSelectActorIds([]);
+    },
+    drop: () => {
+      const drag = dragPlaceRef.current;
+      if (!drag) return;
+      dragPlaceRef.current = null;
+      onSelectActorIds([drag.actorId]);
+    },
+  };
+  const onDeleteBlueprint = (blueprintPath) => {
+    // Every write here targets a plain `scenes/*.scene` (cascaded instance
+    // removal) or the blueprint file itself (tombstoned) -- never a
+    // blueprint's own template id, so no `serialize`/strip step is needed.
+    for (const write of cascadeDeleteBlueprint(files, blueprintPath)) {
+      if (write.path === path) history.commit(write.text);
+      else void writeFile(write.path, write.text);
+    }
+    onSelectActorIds([]);
+  };
+  const onForkSelection = () => {
+    if (isBlueprintFile || !rawSelectedActor?.blueprint) return;
+    const result = forkActorToBlueprint(files, behaviorClasses, sceneData, rawSelectedActor.id);
+    if (!result) return;
+    void writeFile(result.blueprintFile.path, result.blueprintFile.text);
+    history.commit(serialize(result.sceneData));
+  };
+  return (
+    <>
+      <EditorHeader
+        title={
+          isBlueprintFile ? (
+            <span className={styles.editorHeaderTitleRow}>
+              <span className={styles.blueprintBadge}>Blueprint</span>
+              {sceneData.name ?? basename(path)}
+            </span>
+          ) : (
+            sceneData.name ?? basename(path)
+          )
+        }
+        subtitle={
+          isPlaying
+            ? 'WASD / arrows'
+            : isBlueprintFile
+              ? 'editing template -- changes apply to every placed instance'
+              : `${sceneData.actors.length} actors`
+        }
+        right={
+          <HeaderPlaybackButtons
+            isPlaying={isPlaying}
+            setIsPlaying={setIsPlaying}
+            history={history}
+          />
+        }
+        onToggleFiles={onToggleFiles}
+        filesOpen={filesOpen}
+        headerHost={headerHost}
+      />
+      <EditorBody>
+        <div className={styles.sceneWorkspace}>
+          <div className={styles.sceneTools}>
+            {isBlueprintFile ? null : (
+              <>
+                {/* Open (or focus) a Play panel in the shell for this scene.
+                    Lives here in the visible toolbar because the scene editor's
+                    header only renders in the combined editor, not the shell. */}
+                <IconButton
+                  icon="external"
+                  label="Open play preview"
+                  onClick={(event) => {
+                    event.currentTarget.blur();
+                    window.parent.postMessage({ type: 'castle-open-playtest', scene: path }, '*');
+                  }}
+                />
+                <BlueprintLibrary
+                  files={files}
+                  sprites={sprites}
+                  canvasRef={canvasRef}
+                  editCameraRef={editCameraRef}
+                  isPlaying={isPlaying}
+                  selectedBlueprintPath={selectedBlueprintPath}
+                  instanceBlueprintPath={rawSelectedActor?.blueprint ?? null}
+                  onSelectBlueprint={onSelectBlueprint}
+                  onAddActor={onAddActor}
+                  dragPlace={dragPlace}
+                  onDeleteBlueprint={onDeleteBlueprint}
+                />
+              </>
+            )}
+          </div>
+          <div className={styles.stageWrap} style={stageWrapStyle}>
+            <div className={styles.stageCard} data-castle-card>
+              <div className={cx(styles.stageCardClip, !isPlaying && styles.stageCardEditSurface)}>
+                <canvas
+                  ref={canvasRef}
+                  className={cx(styles.stageCanvas, !isPlaying && styles.stageCanvasEdit)}
+                  // Focusable so pointer-down pulls keyboard focus into this
+                  // editor iframe and Cmd+Z reaches our undo handler instead of
+                  // the browser's (see PxArtEditor startTool for the full
+                  // rationale -- Safari won't keep focus on a clicked
+                  // non-focusable canvas).
+                  tabIndex={-1}
+                  onPointerDown={(event) => {
+                    event.currentTarget.focus({ preventScroll: true });
+                    if (isPlaying) return playPointer.onPointerDown(event);
+                    if (panGesture.isSpacePanning()) return panGesture.onPointerDown(event);
+                    return gesture.onPointerDown(event);
+                  }}
+                  onPointerMove={(event) =>
+                    isPlaying
+                      ? playPointer.onPointerMove(event)
+                      : panGesture.isActive()
+                        ? panGesture.onPointerMove(event)
+                        : gesture.onPointerMove(event)
+                  }
+                  onPointerUp={(event) =>
+                    isPlaying
+                      ? playPointer.onPointerUp(event)
+                      : panGesture.isActive()
+                        ? panGesture.onPointerUp(event)
+                        : gesture.onPointerUp(event)
+                  }
+                  onPointerCancel={(event) =>
+                    isPlaying
+                      ? playPointer.onPointerUp(event)
+                      : panGesture.isActive()
+                        ? panGesture.onPointerUp(event)
+                        : gesture.onPointerUp(event)
+                  }
+                />
+                {isPlaying && <SceneUI getRuntime={getRuntime} />}
+              </div>
+              {!isPlaying && selectedActorIds.length >= 1 && (
+                <SelectionOverlay
+                  canvasRef={canvasRef}
+                  editCameraRef={editCameraRef}
+                  sceneData={sceneData}
+                  previewSceneData={previewSceneData}
+                  sprites={sprites}
+                  selectedActorIds={selectedActorIds}
+                  snap={snapSettings}
+                  onArrange={isBlueprintFile ? undefined : actions.arrangeSelection}
+                  onClone={isBlueprintFile ? undefined : actions.duplicateSelection}
+                  onDelete={isBlueprintFile ? undefined : actions.deleteSelection}
+                  applyScene={(next) => onChange(serialize(next))}
+                  recordSnapshot={history.recordSnapshot}
+                />
+              )}
+            </div>
+          </div>
+          <aside {...inspectorSheet.rootProps}>
+            <div {...inspectorSheet.grabProps}>
+              <SheetGrabHandle />
+            </div>
+            <div className={cx(styles.sheetBody, styles.inspectorBody)}>
+              {hotbarBlueprint ? (
+                <BlueprintInspector
+                  name={hotbarBlueprint.name}
+                  template={hotbarBlueprint}
+                  sprites={sprites}
+                  blueprintPath={selectedBlueprintPath}
+                  files={files}
+                  onRename={blueprintActions.rename}
+                  onSetComponent={blueprintActions.setComponent}
+                  onAddBehavior={blueprintActions.addBehavior}
+                  onRemoveBehavior={blueprintActions.removeBehavior}
+                />
+              ) : showMulti ? (
+                <MultiSelectInspector
+                  count={selectedActorIds.length}
+                  onDeselectAll={() => {
+                    onSelectActorIds([]);
+                    onSetMultiSelectMode(false);
+                  }}
+                />
+              ) : selectedActor ? (
+                <ActorInspector
+                  key={selectedActor.id}
+                  selectedActor={selectedActor}
+                  rawActor={rawSelectedActor}
+                  blueprintName={selectedBlueprintName}
+                  blueprintTemplate={selectedBlueprintTemplate}
+                  sprites={sprites}
+                  files={files}
+                  showAddBehavior={isBlueprintFile}
+                  onSetComponent={actions.updateComponent}
+                  onAddBehavior={actions.addBehavior}
+                  onRemoveBehavior={actions.removeBehavior}
+                  onFork={isBlueprintFile ? undefined : onForkSelection}
+                  onEditBlueprint={
+                    isBlueprintFile || !rawSelectedActor?.blueprint
+                      ? undefined
+                      : () => onSelectBlueprint(rawSelectedActor.blueprint)
+                  }
+                />
+              ) : (
+                <SceneInspector
+                  sceneData={sceneData}
+                  snapSettings={snapSettings}
+                  onChangeScene={updateSceneSettings}
+                  onChangeEditor={updateSceneEditorSettings}
+                />
+              )}
+            </div>
+          </aside>
+        </div>
+      </EditorBody>
+    </>
+  );
+}
+// Header-right playback controls, in the mockup's order: Undo, Redo, Play.
+// Play stays a play/stop toggle. Duplicate/remove live on the on-canvas toolbar.
+// "Open preview" asks the shell (parent window) to open/focus a Play panel for
+// THIS scene -- a separate, persistent preview alongside the editor (vs the
+// in-panel play toggle). Defaults to an already-open preview for this scene,
+// else opens a new one (handled shell-side, keyed by scene).
+function HeaderPlaybackButtons({ isPlaying, setIsPlaying, history }) {
+  return (
+    <>
+      <IconButton
+        icon="undo"
+        label="Undo"
+        onClick={history.undo}
+        disabled={!history.canUndo || isPlaying}
+      />
+      <IconButton
+        icon="redo"
+        label="Redo"
+        onClick={history.redo}
+        disabled={!history.canRedo || isPlaying}
+      />
+      <IconButton
+        icon={isPlaying ? 'stop' : 'play'}
+        label={isPlaying ? 'Stop' : 'Play'}
+        active={isPlaying}
+        onClick={(event) => {
+          // Drop focus so a subsequent Space (a game input / pan modifier)
+          // doesn't re-activate this button and toggle play.
+          event.currentTarget.blur();
+          setIsPlaying(!isPlaying);
+        }}
+      />
+    </>
+  );
+}
+// `updateComponent` goes through `setInstanceComponent`, which already
+// branches on whether the target actor has a `blueprint` ref: for a
+// blueprint's own template actor (no ref) it's a plain merge; for a normal
+// instance it diffs each patched prop against the blueprint and records only
+// what actually differs, dropping an override that becomes redundant. Add/
+// remove-behavior stay whole-component operations straight against the
+// instance's own sparse `components` -- there's no per-property baseline to
+// diff when a component doesn't exist on one side at all.
+function makeSceneActions({ sceneData, files, serialize, commit, selectedActorIds, onSelectActorIds, isBlueprintFile }) {
+  function commitScene(next, options) {
+    commit(serialize(next), options);
+  }
+  return {
+    updateComponent: (actorId, behaviorName, nextProps) =>
+      commitScene(setInstanceComponent(files, behaviorClasses, sceneData, actorId, behaviorName, nextProps), {
+        coalesceKey: componentCoalesceKey(actorId, behaviorName, nextProps),
+      }),
+    addBehavior: (actorId, behaviorName) => {
+      const Behavior = findBehaviorClass(behaviorName);
+      if (!Behavior) return;
+      commitScene(
+        setActorComponent(sceneData, actorId, behaviorName, { ...Behavior.defaultProps })
+      );
+    },
+    removeBehavior: (actorId, behaviorName) =>
+      commitScene(removeActorComponent(sceneData, actorId, behaviorName)),
+    deleteSelection: () => {
+      if (isBlueprintFile || selectedActorIds.length === 0) return;
+      commitScene(removeActors(sceneData, selectedActorIds));
+      onSelectActorIds([]);
+    },
+    duplicateSelection: () => {
+      if (isBlueprintFile || selectedActorIds.length === 0) return;
+      const { sceneData: next, newIds } = duplicateActors(sceneData, selectedActorIds);
+      commitScene(next);
+      if (newIds.length) onSelectActorIds(newIds);
+    },
+    arrangeSelection: (action) => {
+      if (isBlueprintFile || selectedActorIds.length === 0) return;
+      const next = arrangeActors(sceneData, selectedActorIds, action);
+      if (next !== sceneData) commitScene(next);
+    },
+  };
+}
+// setActorComponent merges nextProps into the actor's existing component, so
+// its keys ARE the fields this call actually changed.
+function componentCoalesceKey(actorId, behaviorName, nextProps) {
+  return `${actorId}:${behaviorName}:${Object.keys(nextProps).sort().join(',')}`;
+}
+function setSceneSettings(sceneData, nextScene) {
+  return {
+    ...sceneData,
+    ...nextScene,
+  };
+}
+function setSceneEditorSettings(sceneData, nextEditor) {
+  return {
+    ...sceneData,
+    editor: {
+      ...(sceneData.editor ?? {}),
+      ...nextEditor,
+    },
+  };
+}
+function darkenSceneBackground(background) {
+  const parsed = parseHexColor(background ?? '#121213');
+  if (!parsed) return 'var(--castle-stage-workspace-bg)';
+  const amount = 0.42;
+  const darken = (channel) => Math.max(0, Math.round(channel * (1 - amount)));
+  return `rgb(${darken(parsed.r)}, ${darken(parsed.g)}, ${darken(parsed.b)})`;
+}
+function parseHexColor(value) {
+  if (typeof value !== 'string') return null;
+  const hex = value.trim().replace(/^#/, '');
+  const expand = (text) =>
+    text
+      .split('')
+      .map((char) => `${char}${char}`)
+      .join('');
+  const normalized =
+    hex.length === 3 || hex.length === 4
+      ? expand(hex.slice(0, 3))
+      : hex.length === 6 || hex.length === 8
+        ? hex.slice(0, 6)
+        : null;
+  if (!normalized || !/^[0-9a-f]{6}$/i.test(normalized)) return null;
+  return {
+    r: parseInt(normalized.slice(0, 2), 16),
+    g: parseInt(normalized.slice(2, 4), 16),
+    b: parseInt(normalized.slice(4, 6), 16),
+  };
+}
+function useSelectionInspectorSheet(open) {
+  // Inspector visibility is driven by selection / multi-mode; the sheet hook
+  // owns the drag-resize height and remembers it across selections while
+  // mounted (and restores it when the sheet reopens), plus persists it across
+  // reloads via `storageKey`.
+  return useMobileSheet({ open, baseClassName: styles.inspector, storageKey: 'scene-inspector' });
+}
+function useSelectionGesture(args) {
+  const dragRef = useRef(null);
+  // Pin args in a ref so the timer callback reads the latest values without
+  // re-creating the handlers each render.
+  const argsRef = useRef(args);
+  argsRef.current = args;
+  const onPointerDown = useCallback((event) => {
+    const current = argsRef.current;
+    if (current.isPlaying || !current.canvasRef.current || !current.sceneData) return;
+    const raw = screenToCard(current.canvasRef.current, event.clientX, event.clientY);
+    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 actor = scene.actorAt(point.x, point.y);
+    const drag = {
+      pointerId: event.pointerId,
+      startPoint: point,
+      lastPoint: point,
+      startedOnActorId: actor?.id ?? null,
+      modeAtStart: current.multiSelectMode,
+      movedFar: false,
+      longPressTimer: null,
+      longPressFired: false,
+      kind: 'idle',
+      pendingMarquee: false,
+      movingActorIds: [],
+      moveStarts: {},
+      recordedMoveSnapshot: false,
+      lastMoveKey: '0,0',
+      selectionBeforeMarquee: [...current.selectedActorIds],
+    };
+    if (event.shiftKey) {
+      handleShiftPointerDown(drag, actor, current);
+    } else if (current.multiSelectMode) {
+      handleModePointerDown(drag, actor, current);
+    } else {
+      handleDefaultPointerDown(drag, actor, point, current);
+    }
+    drag.moveStarts = collectMoveStarts(current.sceneData, drag.movingActorIds);
+    dragRef.current = drag;
+  }, []);
+  const onPointerMove = useCallback((event) => {
+    const drag = dragRef.current;
+    const current = argsRef.current;
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    if (!current.canvasRef.current || !current.sceneData) return;
+    const raw = screenToCard(current.canvasRef.current, event.clientX, event.clientY);
+    const cam = current.editCameraRef.current;
+    const point = { x: raw.x + cam.x, y: raw.y + cam.y };
+    const dxTotal = point.x - drag.startPoint.x;
+    const dyTotal = point.y - drag.startPoint.y;
+    if (!drag.movedFar && Math.hypot(dxTotal, dyTotal) > DRAG_THRESHOLD) {
+      drag.movedFar = true;
+      if (drag.longPressTimer !== null) {
+        window.clearTimeout(drag.longPressTimer);
+        drag.longPressTimer = null;
+      }
+      if (drag.pendingMarquee && drag.kind === 'idle') drag.kind = 'marquee';
+    }
+    if (drag.kind === 'move' && drag.movedFar) {
+      const snap = getSnapSettings(current.sceneData);
+      const dx = snapDelta(dxTotal, snap.gridSize, snap.enabled);
+      const dy = snapDelta(dyTotal, snap.gridSize, snap.enabled);
+      drag.lastPoint = point;
+      // Key the commit on the snapped delta, not on `nextScene === sceneData`.
+      // `moveActorsFromStarts` returns the pointer-down scene unchanged when the
+      // delta lands back on the start, and an identity guard would skip applying
+      // it -- stranding the actors on the last grid step instead of letting them
+      // return to origin. Re-apply whenever the snapped delta changes; the
+      // identity check now only gates recording the undo snapshot.
+      const moveKey = `${dx},${dy}`;
+      if (moveKey === drag.lastMoveKey) return;
+      drag.lastMoveKey = moveKey;
+      const nextScene = moveActorsFromStarts(
+        current.sceneData,
+        drag.movingActorIds,
+        drag.moveStarts,
+        dx,
+        dy
+      );
+      if (nextScene !== current.sceneData && !drag.recordedMoveSnapshot) {
+        current.recordSceneSnapshot();
+        drag.recordedMoveSnapshot = true;
+      }
+      current.applyScene(nextScene);
+    } else if (drag.kind === 'marquee') {
+      drag.lastPoint = point;
+      current.marqueeRef.current = {
+        x: Math.min(drag.startPoint.x, point.x),
+        y: Math.min(drag.startPoint.y, point.y),
+        width: Math.abs(point.x - drag.startPoint.x),
+        height: Math.abs(point.y - drag.startPoint.y),
+      };
+    }
+  }, []);
+  const onPointerUp = useCallback((event) => {
+    const drag = dragRef.current;
+    const current = argsRef.current;
+    if (!drag || drag.pointerId !== event.pointerId) return;
+    if (drag.longPressTimer !== null) {
+      window.clearTimeout(drag.longPressTimer);
+      drag.longPressTimer = null;
+    }
+    if (drag.kind === 'marquee') {
+      finalizeMarquee(drag, current);
+    } else if (drag.kind === 'idle' && !drag.movedFar && !drag.longPressFired) {
+      handleTap(drag, current);
+    }
+    current.marqueeRef.current = null;
+    dragRef.current = null;
+  }, []);
+  return { onPointerDown, onPointerMove, onPointerUp };
+}
+function getSnapSettings(sceneData) {
+  const rawSize = sceneData.editor?.gridSize;
+  return {
+    enabled: sceneData.editor?.snapToGrid ?? true,
+    gridSize: Number.isFinite(rawSize) && rawSize && rawSize > 0 ? rawSize : DEFAULT_GRID_SIZE,
+  };
+}
+function snapDelta(delta, gridSize, enabled) {
+  if (!enabled) return delta;
+  return Math.round(delta / gridSize) * gridSize;
+}
+function collectMoveStarts(sceneData, actorIds) {
+  const starts = {};
+  const movingIds = new Set(actorIds);
+  for (const actor of sceneData.actors) {
+    if (!movingIds.has(actor.id)) continue;
+    const layout = actor.components.Layout;
+    if (!layout) continue;
+    starts[actor.id] = { x: layout.x, y: layout.y };
+  }
+  return starts;
+}
+function moveActorsFromStarts(sceneData, actorIds, starts, dx, dy) {
+  if (actorIds.length === 0) return sceneData;
+  const movingIds = new Set(actorIds);
+  const next = structuredClone(sceneData);
+  let changed = false;
+  for (const actor of next.actors) {
+    if (!movingIds.has(actor.id)) continue;
+    const start = starts[actor.id];
+    const layout = actor.components.Layout;
+    if (!start || !layout) continue;
+    const nextX = Math.round(start.x + dx);
+    const nextY = Math.round(start.y + dy);
+    if (layout.x === nextX && layout.y === nextY) continue;
+    actor.components.Layout = {
+      ...layout,
+      x: nextX,
+      y: nextY,
+    };
+    changed = true;
+  }
+  return changed ? next : sceneData;
+}
+function usePlayPointerGesture({ canvasRef, runtimeRef }) {
+  const setPointer = useCallback(
+    (event, down) => {
+      const canvas = canvasRef.current;
+      const runtime = runtimeRef.current;
+      if (!canvas || !runtime) return;
+      runtime.setPointerFromScreen(canvas, event.clientX, event.clientY, down);
+    },
+    [canvasRef, runtimeRef]
+  );
+  const onPointerDown = useCallback(
+    (event) => {
+      event.currentTarget.setPointerCapture(event.pointerId);
+      setPointer(event, true);
+    },
+    [setPointer]
+  );
+  const onPointerMove = useCallback(
+    (event) => {
+      setPointer(event);
+    },
+    [setPointer]
+  );
+  const onPointerUp = useCallback(
+    (event) => {
+      setPointer(event, false);
+      try {
+        event.currentTarget.releasePointerCapture(event.pointerId);
+      } catch {
+        // Pointer capture may already be gone after cancel/blur.
+      }
+    },
+    [setPointer]
+  );
+  return { onPointerDown, onPointerMove, onPointerUp };
+}
+function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
+  const dragRef = useRef(null);
+  const spaceDownRef = useRef(false);
+  // Native wheel/gesture listeners (below) read play state through a ref so they
+  // never need to detach/reattach when play toggles.
+  const isPlayingRef = useRef(isPlaying);
+  isPlayingRef.current = isPlaying;
+  useEffect(() => {
+    function onKeyDown(event) {
+      if (event.key !== ' ' || isEditableTarget(event.target)) return;
+      // Swallow Space's default: it would scroll the panel and re-activate a
+      // focused button (e.g. the Play/Stop toggle that keeps focus after a
+      // click), so Space only ever arms the pan modifier here.
+      event.preventDefault();
+      spaceDownRef.current = true;
+    }
+    function onKeyUp(event) {
+      if (event.key === ' ') spaceDownRef.current = false;
+    }
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('keyup', onKeyUp);
+    return () => {
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('keyup', onKeyUp);
+    };
+  }, []);
+  const panByScreenDelta = useCallback(
+    (dx, dy) => {
+      const canvas = canvasRef.current;
+      if (!canvas) return;
+      const rect = canvas.getBoundingClientRect();
+      const viewportWidth = Number(canvas.dataset.viewportWidth) || cardSize.width;
+      const viewportHeight = Number(canvas.dataset.viewportHeight) || cardSize.height;
+      editCameraRef.current = {
+        ...editCameraRef.current,
+        x: editCameraRef.current.x + (dx * viewportWidth) / rect.width,
+        y: editCameraRef.current.y + (dy * viewportHeight) / rect.height,
+      };
+    },
+    [canvasRef, editCameraRef]
+  );
+  // Zoom about the pointer by a multiplicative factor: keep the world point
+  // under the cursor pinned while the zoom level changes. Because the effective
+  // origin scales as EDIT_VIEWPORT.origin / zoom, the camera shift to re-pin the
+  // cursor is (1/z0 - 1/z1) * (frac * EDIT_VIEWPORT.extent - EDIT_VIEWPORT.origin).
+  const zoomByFactorAtPointer = useCallback(
+    (clientX, clientY, factor) => {
+      const canvas = canvasRef.current;
+      if (!canvas || !Number.isFinite(factor) || factor <= 0) return;
+      const cam = editCameraRef.current;
+      const z0 = cam.zoom ?? 1;
+      const z1 = clampZoom(z0 * factor);
+      if (z1 === z0) return;
+      const rect = canvas.getBoundingClientRect();
+      const fracX = (clientX - rect.left) / rect.width;
+      const fracY = (clientY - rect.top) / rect.height;
+      const k = 1 / z0 - 1 / z1;
+      editCameraRef.current = {
+        x: cam.x + k * (fracX * EDIT_VIEWPORT.width - EDIT_VIEWPORT.originX),
+        y: cam.y + k * (fracY * EDIT_VIEWPORT.height - EDIT_VIEWPORT.originY),
+        zoom: z1,
+      };
+    },
+    [canvasRef, editCameraRef]
+  );
+  // Wheel + pinch are bound as NATIVE, non-passive listeners (not React props):
+  // React attaches `wheel` passively at its root, so a React onWheel can't call
+  // preventDefault and the browser's own page-zoom wins. We also need Safari's
+  // proprietary `gesture*` events, which is how it reports trackpad pinch (it
+  // does not emit ctrl+wheel like Chromium). Both paths preventDefault to stop
+  // the browser from zooming the page underneath the editor.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return undefined;
+    let gestureScale = 1;
+    // Set while a Safari pinch gesture is in flight, so we don't double-apply
+    // zoom if Safari also emits ctrl+wheel for the same pinch.
+    let gestureActive = false;
+    const onWheel = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      // Trackpad pinch (and Ctrl+wheel) surface as wheel events with ctrlKey set
+      // in Chromium; route those to zoom and leave plain scroll as pan.
+      if (event.ctrlKey) {
+        if (gestureActive) return;
+        zoomByFactorAtPointer(
+          event.clientX,
+          event.clientY,
+          Math.exp(-event.deltaY * ZOOM_WHEEL_SPEED)
+        );
+      } else {
+        panByScreenDelta(event.deltaX, event.deltaY);
+      }
+    };
+    const onGestureStart = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      gestureActive = true;
+      gestureScale = event.scale || 1;
+    };
+    const onGestureChange = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      // Safari reports `scale` cumulatively from gesturestart (1.0 at start), so
+      // zoom by the ratio against the last reading.
+      const prev = gestureScale || 1;
+      const next = event.scale || prev;
+      gestureScale = next;
+      // GestureEvent carries clientX/clientY (the pinch centroid); fall back to
+      // the canvas center if a browser omits them.
+      const rect = canvas.getBoundingClientRect();
+      const px = Number.isFinite(event.clientX) ? event.clientX : rect.left + rect.width / 2;
+      const py = Number.isFinite(event.clientY) ? event.clientY : rect.top + rect.height / 2;
+      zoomByFactorAtPointer(px, py, next / prev);
+    };
+    const onGestureEnd = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      gestureActive = false;
+    };
+    const opts = { passive: false };
+    canvas.addEventListener('wheel', onWheel, opts);
+    canvas.addEventListener('gesturestart', onGestureStart, opts);
+    canvas.addEventListener('gesturechange', onGestureChange, opts);
+    canvas.addEventListener('gestureend', onGestureEnd, opts);
+    return () => {
+      canvas.removeEventListener('wheel', onWheel, opts);
+      canvas.removeEventListener('gesturestart', onGestureStart, opts);
+      canvas.removeEventListener('gesturechange', onGestureChange, opts);
+      canvas.removeEventListener('gestureend', onGestureEnd, opts);
+    };
+  }, [canvasRef, panByScreenDelta, zoomByFactorAtPointer]);
+  const onPointerDown = useCallback((event) => {
+    if (isPlaying || !spaceDownRef.current) return;
+    event.preventDefault();
+    event.currentTarget.setPointerCapture(event.pointerId);
+    dragRef.current = { id: event.pointerId, lastX: event.clientX, lastY: event.clientY };
+  }, [isPlaying]);
+  const onPointerMove = useCallback(
+    (event) => {
+      const drag = dragRef.current;
+      if (!drag || drag.id !== event.pointerId) return;
+      const dx = event.clientX - drag.lastX;
+      const dy = event.clientY - drag.lastY;
+      drag.lastX = event.clientX;
+      drag.lastY = event.clientY;
+      panByScreenDelta(-dx, -dy);
+    },
+    [panByScreenDelta]
+  );
+  const onPointerUp = useCallback((event) => {
+    const drag = dragRef.current;
+    if (!drag || drag.id !== event.pointerId) return;
+    try {
+      event.currentTarget.releasePointerCapture(event.pointerId);
+    } catch {
+      // pointer capture may already be gone
+    }
+    dragRef.current = null;
+  }, []);
+  const isSpacePanning = useCallback(() => spaceDownRef.current, []);
+  const isActive = useCallback(() => Boolean(dragRef.current), []);
+  return { onPointerDown, onPointerMove, onPointerUp, isSpacePanning, isActive };
+}
+function handleShiftPointerDown(drag, actor, current) {
+  if (actor) {
+    const wasSelected = current.selectedActorIds.includes(actor.id);
+    const nextIds = wasSelected
+      ? current.selectedActorIds.filter((id) => id !== actor.id)
+      : [...current.selectedActorIds, actor.id];
+    current.onSelectActorIds(nextIds);
+    if (!wasSelected) {
+      drag.kind = 'move';
+      drag.movingActorIds = nextIds;
+    }
+  } else {
+    drag.pendingMarquee = true;
+  }
+}
+function handleModePointerDown(drag, actor, current) {
+  if (actor) {
+    if (current.selectedActorIds.includes(actor.id)) {
+      drag.kind = 'move';
+      drag.movingActorIds = [...current.selectedActorIds];
+    }
+    // else: leave kind='idle' so pointerup triggers the tap-toggle path.
+  } else {
+    // Defer marquee until movement, so a stationary press/release reaches
+    // the tap handler (which exits multi mode on empty tap).
+    drag.pendingMarquee = true;
+  }
+}
+function handleDefaultPointerDown(drag, actor, point, current) {
+  if (actor) {
+    if (!current.selectedActorIds.includes(actor.id)) {
+      current.onSelectActorIds([actor.id]);
+      drag.movingActorIds = [actor.id];
+    } else {
+      drag.movingActorIds = [...current.selectedActorIds];
+    }
+    drag.kind = 'move';
+    drag.longPressTimer = window.setTimeout(() => {
+      if (drag.movedFar) return;
+      drag.longPressFired = true;
+      current.onSetMultiSelectMode(true);
+    }, LONG_PRESS_MS);
+  } else {
+    current.onSelectActorIds([]);
+    drag.selectionBeforeMarquee = [];
+    drag.pendingMarquee = true;
+    drag.longPressTimer = window.setTimeout(() => {
+      if (drag.movedFar) return;
+      drag.longPressFired = true;
+      current.onSetMultiSelectMode(true);
+      drag.kind = 'marquee';
+      current.marqueeRef.current = { x: point.x, y: point.y, width: 0, height: 0 };
+    }, LONG_PRESS_MS);
+  }
+}
+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 hits = scene.actorIdsInRect(m);
+  const merged = new Set(drag.selectionBeforeMarquee);
+  for (const id of hits) merged.add(id);
+  current.onSelectActorIds([...merged]);
+}
+function handleTap(drag, current) {
+  if (!drag.modeAtStart) return;
+  if (drag.startedOnActorId !== null) {
+    const id = drag.startedOnActorId;
+    const wasSelected = current.selectedActorIds.includes(id);
+    current.onSelectActorIds(
+      wasSelected
+        ? current.selectedActorIds.filter((x) => x !== id)
+        : [...current.selectedActorIds, id]
+    );
+  } else {
+    current.onSetMultiSelectMode(false);
+    current.onSelectActorIds([]);
+  }
+}
+function useSelectionKeyboard(args) {
+  const ref = useRef(args);
+  ref.current = args;
+  useEffect(() => {
+    function onKeyDown(event) {
+      const current = ref.current;
+      if (current.isPlaying || isEditableTarget(event.target)) return;
+      if (event.key === 'Escape') {
+        if (current.selectedActorIds.length || current.multiSelectMode || current.selectedBlueprintPath) {
+          event.preventDefault();
+          // The wrapped setter also clears any hotbar blueprint selection.
+          current.onSelectActorIds([]);
+          current.onSetMultiSelectMode(false);
+        }
+        return;
+      }
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'a') {
+        if (!current.sceneData || current.isBlueprintFile) return;
+        event.preventDefault();
+        current.onSelectActorIds(current.sceneData.actors.map((actor) => actor.id));
+        return;
+      }
+      if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'd') {
+        if (!current.sceneData || current.isBlueprintFile || current.selectedActorIds.length === 0) return;
+        event.preventDefault();
+        const { sceneData: next, newIds } = duplicateActors(
+          current.sceneData,
+          current.selectedActorIds
+        );
+        current.commitScene(next);
+        if (newIds.length) current.onSelectActorIds(newIds);
+        return;
+      }
+      if (event.key === 'Delete' || event.key === 'Backspace') {
+        if (!current.sceneData || current.isBlueprintFile || current.selectedActorIds.length === 0) return;
+        event.preventDefault();
+        current.commitScene(removeActors(current.sceneData, current.selectedActorIds));
+        current.onSelectActorIds([]);
+      }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, []);
+}
+function useScenePlayLoop({
+  sceneData,
+  sprites,
+  files,
+  isPlaying,
+  text,
+  canvasRef,
+  runtimeRef,
+  editCameraRef,
+  marqueeRef,
+  selectedActorIdsRef,
+  selectedBlueprintPathRef,
+}) {
+  // Spin up / tear down the play-mode runtime as the user toggles play. `text`
+  // is the stable identity for `sceneData` (which is re-parsed every render);
+  // depending on `sceneData` here would reset the runtime — and any
+  // behavior-mutated state like Layout.rotation — on every parent re-render.
+  useEffect(() => {
+    if (!isPlaying) {
+      runtimeRef.current = null;
+      return;
+    }
+    if (!sceneData) return;
+    runtimeRef.current = makeScene(sceneData, behaviorClasses, sprites, files).clone();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sprites, isPlaying, text, runtimeRef]);
+  // Animation loop -- draws edit-mode previews and ticks the play-mode runtime.
+  useEffect(() => {
+    if (!sceneData || !canvasRef.current) return undefined;
+    const canvas = canvasRef.current;
+    const ctx = canvas.getContext('2d');
+    if (!ctx) return undefined;
+    const viewport = isPlaying
+      ? undefined
+      : editViewportForZoom(editCameraRef.current.zoom);
+    configureSceneCanvas(canvas, ctx, viewport);
+    let raf = 0;
+    let last = performance.now();
+    const frame = (now) => {
+      const dt = Math.min(0.033, (now - last) / 1000);
+      last = now;
+      // Recompute each frame so the edit zoom (mutated on the camera ref by the
+      // pinch gesture) takes effect without restarting the loop.
+      const frameViewport = isPlaying
+        ? undefined
+        : editViewportForZoom(editCameraRef.current.zoom);
+      const scene = isPlaying
+        ? runtimeRef.current
+        : makeScene(sceneData, behaviorClasses, sprites, files);
+      if (scene) {
+        const snap = getSnapSettings(sceneData);
+        if (isPlaying) scene.update(dt);
+        if (!isPlaying) scene.camera = { ...editCameraRef.current };
+        configureSceneCanvas(canvas, ctx, frameViewport);
+        // Read selection from the ref each frame so the grid/box gating tracks
+        // the current selection without resetting this loop.
+        const editSelectedActorIds = isPlaying ? [] : selectedActorIdsRef.current ?? [];
+        scene.draw(ctx, {
+          selectedActorIds: [],
+          marquee: isPlaying ? null : marqueeRef.current,
+          showGrid: !isPlaying && snap.enabled && editSelectedActorIds.length > 0,
+          gridSize: snap.gridSize,
+          showDebugColliders: false,
+          showCropOutline: !isPlaying,
+          viewport: frameViewport,
+          useCamera: true,
+          editPlaceholders: !isPlaying,
+          dimBlueprintPath: isPlaying ? null : selectedBlueprintPathRef.current,
+        });
+      }
+      raf = requestAnimationFrame(frame);
+    };
+    raf = requestAnimationFrame(frame);
+    return () => cancelAnimationFrame(raf);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- `text` proxies `sceneData` identity; resetting on every parse churns the loop and wipes runtime state.
+  }, [
+    sprites,
+    files,
+    isPlaying,
+    text,
+    canvasRef,
+    runtimeRef,
+    marqueeRef,
+    selectedActorIdsRef,
+    selectedBlueprintPathRef,
+  ]);
+}
+function useScenePlayKeys(runtimeRef) {
+  useEffect(() => {
+    const down = (event) => {
+      if (!runtimeRef.current) return;
+      // Space is a game input while playing — stop the browser from scrolling
+      // the panel or re-triggering a focused button (the Play/Stop toggle keeps
+      // focus after a click) instead of reaching gameplay.
+      if (event.key === ' ') event.preventDefault();
+      runtimeRef.current.keys.add(event.key);
+    };
+    const up = (event) => {
+      if (!runtimeRef.current) return;
+      runtimeRef.current.keys.delete(event.key);
+    };
+    window.addEventListener('keydown', down);
+    window.addEventListener('keyup', up);
+    return () => {
+      window.removeEventListener('keydown', down);
+      window.removeEventListener('keyup', up);
+    };
+  }, [runtimeRef]);
+}
+function isEditableTarget(target) {
+  return (
+    target instanceof Element &&
+    !!target.closest('input, textarea, select, [contenteditable="true"]')
+  );
+}
+// Clone/Delete moved to the on-canvas SelectionOverlay toolbar; this inspector
+// now only carries the multi-select status text and "Deselect all".
+function MultiSelectInspector({ count, onDeselectAll }) {
+  return (
+    <div style={{ padding: '14px 16px', display: 'flex', flexDirection: 'column', gap: 12 }}>
+      <div style={{ fontSize: 13, opacity: 0.8 }}>
+        {count === 0
+          ? 'Multi-select mode -- tap actors to add'
+          : `${count} actor${count === 1 ? '' : 's'} selected`}
+      </div>
+      <div style={{ display: 'flex', gap: 8, flexWrap: 'wrap' }}>
+        <button type="button" onClick={onDeselectAll} style={inspectorActionStyle(false)}>
+          <Icon name="times" /> Deselect all
+        </button>
+      </div>
+    </div>
+  );
+}
+function inspectorActionStyle(disabled) {
+  return {
+    display: 'inline-flex',
+    alignItems: 'center',
+    gap: 6,
+    padding: '6px 10px',
+    background: 'transparent',
+    color: 'inherit',
+    border: '1px solid var(--castle-inspector-divider)',
+    borderRadius: 6,
+    cursor: disabled ? 'default' : 'pointer',
+    opacity: disabled ? 0.5 : 1,
+    fontSize: 13,
+  };
+}
+function SceneInspector({ sceneData, snapSettings, onChangeScene, onChangeEditor }) {
+  return (
+    <Panel title="Scene">
+      <TextField
+        label="Name"
+        value={sceneData.name ?? ''}
+        onChange={(name) => onChangeScene({ name })}
+      />
+      <ColorField
+        label="Background"
+        value={sceneData.background ?? '#121213'}
+        onChange={(background) => onChangeScene({ background })}
+      />
+      <CheckboxField
+        label="Snap to grid"
+        checked={snapSettings.enabled}
+        onChange={(snapToGrid) => onChangeEditor({ snapToGrid })}
+      />
+      <NumberField
+        label="Grid size"
+        value={snapSettings.gridSize}
+        min={1}
+        step={1}
+        onChange={(gridSize) => onChangeEditor({ gridSize: Math.round(gridSize) })}
+      />
+    </Panel>
+  );
+}
+// Sidebar inspector for a hotbar-selected blueprint: badge + name header, then
+// the template's components through the same ActorInspector panels used for
+// actors -- the template is presented as a synthetic actor with no `blueprint`
+// ref, so ActorInspector treats it exactly like a blueprint file's template
+// (plain edits, no instance hint, Layout not removable). The action callbacks
+// drop the synthetic actor id and write the blueprint FILE (see
+// `updateBlueprintTemplate` in SceneEditor).
+function BlueprintInspector({
+  name,
+  template,
+  sprites,
+  blueprintPath,
+  files,
+  onRename,
+  onSetComponent,
+  onAddBehavior,
+  onRemoveBehavior,
+}) {
+  const templateActor = { id: '__blueprint__', components: template.components };
+  const instanceCount = countBlueprintInstances(files, blueprintPath);
+  return (
+    <>
+      <div className={styles.instanceHeader}>
+        <div className={styles.instanceHeaderName}>
+          <BlueprintThumbnail blueprint={template} sprites={sprites} />
+          <div className={styles.instanceHeaderNameCol}>
+            <input
+              className={styles.blueprintNameInput}
+              value={name}
+              onChange={(event) => onRename?.(event.target.value)}
+              aria-label="Blueprint name"
+              spellCheck={false}
+            />
+            <span className={styles.instanceHeaderId}>
+              {instanceCount} {instanceCount === 1 ? 'actor' : 'actors'}
+            </span>
+          </div>
+        </div>
+      </div>
+      <ActorInspector
+        selectedActor={templateActor}
+        rawActor={templateActor}
+        files={files}
+        onSetComponent={(actorId, behaviorName, nextProps) => onSetComponent(behaviorName, nextProps)}
+        onAddBehavior={(actorId, behaviorName) => onAddBehavior(behaviorName)}
+        onRemoveBehavior={(actorId, behaviorName) => onRemoveBehavior(behaviorName)}
+      />
+    </>
+  );
+}
+// Per-behavior helper the inspector fields use to render instance overrides.
+// `isOverridden` is true only for inherited props the instance has its own
+// value for (position/rotation are `inherit: false` and always instance-local,
+// so they never read as "overriding" a blueprint default). `baseline` is what
+// the prop falls back to when reset -- the blueprint template value if present,
+// else the behavior's default. `reset` writes that baseline; for inherited
+// props `applyComponentPatch` then drops the now-redundant override.
+function makeOverrideContext({ Behavior, rawComponent, templateProps, setComponent }) {
+  const baselineOf = (prop) =>
+    templateProps && prop in templateProps ? templateProps[prop] : Behavior?.defaultProps?.[prop];
+  return {
+    isOverridden: (prop) =>
+      isInheritedProp(Behavior, prop) && !!rawComponent && prop in rawComponent,
+    // True when the behavior overrides at least one inherited prop -- i.e. it
+    // has a field that renders with the purple override tint. Drives the
+    // matching tint on the panel's title. Position/rotation are inherit:false,
+    // so a position-only instance override doesn't count (nor does it tint any
+    // field), matching isOverridden's semantics.
+    anyOverridden: () =>
+      !!rawComponent && Object.keys(rawComponent).some((prop) => isInheritedProp(Behavior, prop)),
+    baseline: baselineOf,
+    reset: (prop) => setComponent({ [prop]: baselineOf(prop) }),
+  };
+}
+function ActorInspector({
+  selectedActor,
+  rawActor,
+  blueprintName,
+  blueprintTemplate,
+  sprites,
+  showAddBehavior = true,
+  files,
+  onSetComponent,
+  onAddBehavior,
+  onRemoveBehavior,
+  onFork,
+  onEditBlueprint,
+}) {
+  const isInstance = Boolean(rawActor?.blueprint);
+  const presentNames = new Set(
+    Object.entries(selectedActor.components)
+      .filter(([, component]) => !!component)
+      .map(([behaviorName]) => behaviorName)
+  );
+  const availableBehaviors = behaviorClasses.filter(
+    (candidate) => !presentNames.has(candidate.behaviorName)
+  );
+  const behaviorEntries = Object.entries(selectedActor.components).filter((entry) => !!entry[1]);
+  // For an instance, behaviors it doesn't already override are collapsed behind
+  // a reveal button; Layout and any behavior with an instance override stay
+  // visible below the header. Revealing is a pure view toggle -- it never
+  // touches the actor, it just exposes the inherited behaviors' fields so they
+  // can be overridden. Keyed by actor id at the call site, so the collapsed
+  // state resets when a different actor is selected.
+  const [showAllBehaviors, setShowAllBehaviors] = useState(false);
+  const isPinnedBehavior = (behaviorName) =>
+    behaviorName === 'Layout' || Boolean(rawActor?.components?.[behaviorName]);
+  const collapsed = isInstance && !showAllBehaviors;
+  const visibleEntries = collapsed
+    ? behaviorEntries.filter(([behaviorName]) => isPinnedBehavior(behaviorName))
+    : behaviorEntries;
+  const showReveal = collapsed && visibleEntries.length < behaviorEntries.length;
+  return (
+    <>
+      {isInstance ? (
+        <div className={styles.instanceHeader}>
+          <div className={styles.instanceHeaderName}>
+            <BlueprintThumbnail
+              blueprint={blueprintTemplate ?? { components: selectedActor.components }}
+              sprites={sprites}
+            />
+            <div className={styles.instanceHeaderNameCol}>
+              <span className={styles.instanceHeaderNameText}>
+                <strong className={styles.instanceHeaderNameStrong}>{blueprintName}</strong> Actor
+              </span>
+              <span className={styles.instanceHeaderId}>id: {selectedActor.id}</span>
+            </div>
+          </div>
+          {onEditBlueprint ? (
+            <button
+              type="button"
+              className={styles.instanceForkButton}
+              onClick={onEditBlueprint}
+              title="Select this blueprint in the hotbar">
+              <Icon name="pencil" />
+              <span>Edit blueprint</span>
+            </button>
+          ) : null}
+          {onFork ? (
+            <button
+              type="button"
+              className={styles.instanceForkButton}
+              onClick={onFork}
+              title="New blueprint from this actor">
+              <Icon name="code-fork" />
+              <span>Fork new blueprint</span>
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+      {showAddBehavior ? (
+        <AddBehaviorPicker
+          available={availableBehaviors}
+          onAdd={(behaviorName) => onAddBehavior(selectedActor.id, behaviorName)}
+        />
+      ) : null}
+      {visibleEntries.map(([behaviorName, component], index) => {
+        const Behavior = behaviorClasses.find(
+          (candidate) => candidate.behaviorName === behaviorName
+        );
+        const Inspector = Behavior?.Inspector;
+        const setComponent = (nextProps) =>
+          onSetComponent(selectedActor.id, behaviorName, nextProps);
+        // Instance overrides get a purple tint + "Default: X [Reset]" sub-line.
+        // Null when editing a blueprint template (nothing to override against).
+        const override = isInstance
+          ? makeOverrideContext({
+              Behavior,
+              rawComponent: rawActor?.components?.[behaviorName],
+              templateProps: blueprintTemplate?.components?.[behaviorName],
+              setComponent,
+            })
+          : null;
+        const body = Inspector ? (
+          <Inspector
+            actor={selectedActor}
+            component={component}
+            files={files}
+            sprites={sprites}
+            setComponent={setComponent}
+            override={override}
+          />
+        ) : (
+          <AutoInspector
+            behaviorName={behaviorName}
+            defaultProps={Behavior?.defaultProps ?? component}
+            component={component}
+            setComponent={setComponent}
+            override={override}
+          />
+        );
+        // Layout is core to every actor -- it cannot be removed. A component
+        // an instance only has via its blueprint (no override of its own yet)
+        // has nothing to remove either -- v1 has no per-instance "hide this
+        // inherited component" concept (see propertyMeta punt list).
+        const removable =
+          behaviorName !== 'Layout' && (!isInstance || Boolean(rawActor.components?.[behaviorName]));
+        // When the reveal button follows, keep the last visible panel's divider
+        // so it doesn't merge into the button row.
+        const isLast = index === visibleEntries.length - 1 && !showReveal;
+        // Trash renders before the panel so the panel stays the wrapper's
+        // last child -- the panel's own `:last-child` border zeroes out, and
+        // this wrapper owns the divider between panels deterministically.
+        return (
+          <div
+            key={behaviorName}
+            style={{
+              position: 'relative',
+              borderBottom: isLast ? undefined : '1px solid var(--castle-inspector-divider)',
+            }}>
+            {removable ? (
+              <button
+                type="button"
+                aria-label={`Remove ${behaviorName}`}
+                title={`Remove ${behaviorName}`}
+                onClick={() => onRemoveBehavior(selectedActor.id, behaviorName)}
+                style={{
+                  position: 'absolute',
+                  top: 14,
+                  right: 16,
+                  border: 'none',
+                  background: 'transparent',
+                  padding: 0,
+                  margin: 0,
+                  cursor: 'pointer',
+                  color: 'inherit',
+                  fontSize: 16,
+                  lineHeight: 1,
+                }}>
+                <Icon name="trash" />
+              </button>
+            ) : null}
+            {body}
+          </div>
+        );
+      })}
+      {showReveal ? (
+        <button
+          type="button"
+          className={styles.revealOverridesButton}
+          onClick={() => setShowAllBehaviors(true)}>
+          <Icon name="chevron-down" />
+          <span>Override behavior properties</span>
+        </button>
+      ) : null}
+    </>
+  );
+}
+function AddBehaviorPicker({ available, onAdd }) {
+  if (!available.length) return null;
+  return (
+    <div
+      style={{
+        height: 'var(--castle-hotbar-row-full)',
+        padding: '0 16px',
+        display: 'flex',
+        alignItems: 'center',
+        borderBottom: '1px solid var(--castle-inspector-divider)',
+      }}>
+      <select
+        className={styles.select}
+        value=""
+        onChange={(event) => {
+          if (event.target.value) onAdd(event.target.value);
+        }}>
+        <option value="">+ Add behavior</option>
+        {available.map((behavior) => (
+          <option key={behavior.behaviorName} value={behavior.behaviorName}>
+            {behavior.behaviorName}
+          </option>
+        ))}
+      </select>
+    </div>
+  );
+}