castle-web-cli 0.4.77 → 0.4.79

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

@@ -1,22 +1,36 @@
-import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { renderSpriteFrame } from '../engine/pxart';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { writeFile } from 'castle-web-sdk';
 import { basename, formatJson, parseJsonFile } from '../engine/files';
 import {
-  addActor,
   arrangeActors,
   cardSize,
   configureSceneCanvas,
   duplicateActors,
   makeScene,
+  mintActorId,
   removeActorComponent,
   removeActors,
   screenToCard,
   setActorComponent,
 } from '../engine/scene';
+import {
+  addActorWithBlueprint,
+  blueprintDropXY,
+  cascadeDeleteBlueprint,
+  forkActorToBlueprint,
+  getBlueprintTemplate,
+  isBlueprintPath,
+  migrateOrphanActors,
+  placeBlueprintInstance,
+  setBlueprintName,
+  setBlueprintTemplateComponents,
+  setInstanceComponent,
+} from '../engine/blueprint';
 import {
   cx,
   CheckboxField,
   ColorField,
+  ConfirmDialog,
   EditorBody,
   EditorHeader,
   Icon,
@@ -31,8 +45,14 @@ import {
 import { AutoInspector } from '../engine/autoInspector';
 import { SceneUI } from '../engine/SceneUI';
 import { SelectionOverlay } from './SelectionOverlay';
+import { BlueprintLibrary } 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;
@@ -63,17 +83,54 @@ function editViewportForZoom(zoom) {
     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,
+  onSelectActorIds: onSelectActorIdsRaw,
   multiSelectMode,
   onSetMultiSelectMode,
 }) {
@@ -84,15 +141,54 @@ export function SceneEditor({
   const selectedActorIdsRef = useRef(selectedActorIds);
   selectedActorIdsRef.current = selectedActorIds;
   const [isPlaying, setIsPlaying] = useState(false);
-  const history = useEditHistory(text, onChange);
-  useUndoRedoShortcuts(history);
-  const showMulti = selectedActorIds.length > 1 || multiSelectMode;
+  // 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(null);
+  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);
+  const showMulti = !isBlueprintFile && (selectedActorIds.length > 1 || multiSelectMode);
   const inspectorSheet = useSelectionInspectorSheet(true);
-  const { value: sceneData, error } = parseJsonFile(path, text);
+  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,
@@ -107,25 +203,28 @@ export function SceneEditor({
     canvasRef,
     sceneData,
     sprites,
+    files,
     isPlaying,
     selectedActorIds,
     onSelectActorIds,
-    multiSelectMode,
+    multiSelectMode: showMulti && multiSelectMode,
     onSetMultiSelectMode,
     marqueeRef,
     editCameraRef,
-    applyScene: (next) => onChange(formatJson(next)),
+    applyScene: (next) => onChange(serialize(next)),
     recordSceneSnapshot: history.recordSnapshot,
   });
   const playPointer = usePlayPointerGesture({ canvasRef, runtimeRef });
   useSelectionKeyboard({
     sceneData,
     selectedActorIds,
+    selectedBlueprintPath,
     onSelectActorIds,
     multiSelectMode,
     onSetMultiSelectMode,
     isPlaying,
-    commitScene: (next) => history.commit(formatJson(next)),
+    isBlueprintFile,
+    commitScene: (next) => history.commit(serialize(next)),
   });
   if (!sceneData) {
     return (
@@ -142,37 +241,194 @@ export function SceneEditor({
       </>
     );
   }
-  const selectedActor =
+  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 selectedBlueprintName = rawSelectedActor?.blueprint
+    ? getBlueprintTemplate(files, rawSelectedActor.blueprint)?.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;
+  // 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(formatJson(setSceneSettings(sceneData, nextScene)));
+    history.commit(serialize(setSceneSettings(sceneData, nextScene)));
   };
   const updateSceneEditorSettings = (nextEditor) => {
-    history.commit(formatJson(setSceneEditorSettings(sceneData, nextEditor)));
+    history.commit(serialize(setSceneEditorSettings(sceneData, nextEditor)));
   };
-  const inspectorLabel = showMulti ? 'Multi-select' : selectedActor ? 'Inspector' : 'Scene';
-  const inspectorHint = showMulti
-    ? `${selectedActorIds.length} actor${selectedActorIds.length === 1 ? '' : 's'} selected`
-    : selectedActor
-      ? `actor ${selectedActor.id}`
-      : 'scene settings';
+  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));
+  };
+  const inspectorLabel = isBlueprintFile
+    ? 'Blueprint'
+    : hotbarBlueprint
+      ? 'Blueprint'
+      : showMulti
+        ? 'Multi-select'
+        : selectedActor
+          ? 'Inspector'
+          : 'Scene';
+  const inspectorHint = isBlueprintFile
+    ? sceneData.name ?? basename(path)
+    : hotbarBlueprint
+      ? hotbarBlueprint.name
+      : showMulti
+        ? `${selectedActorIds.length} actor${selectedActorIds.length === 1 ? '' : 's'} selected`
+        : selectedActor
+          ? `actor ${selectedActor.id}`
+          : 'scene settings';
   return (
     <>
       <EditorHeader
-        title={sceneData.name ?? basename(path)}
-        subtitle={isPlaying ? 'WASD / arrows' : `${sceneData.actors.length} actors`}
+        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}
@@ -187,18 +443,20 @@ export function SceneEditor({
       <EditorBody>
         <div className={styles.sceneWorkspace}>
           <div className={styles.sceneTools}>
-            <BlueprintHotbar
-              sceneData={sceneData}
-              files={files}
-              sprites={sprites}
-              canvasRef={canvasRef}
-              editCameraRef={editCameraRef}
-              selectedActorIds={selectedActorIds}
-              onSelectActorIds={onSelectActorIds}
-              isPlaying={isPlaying}
-              onChange={onChange}
-              history={history}
-            />
+            {isBlueprintFile ? null : (
+              <BlueprintLibrary
+                files={files}
+                sprites={sprites}
+                canvasRef={canvasRef}
+                editCameraRef={editCameraRef}
+                isPlaying={isPlaying}
+                selectedBlueprintPath={selectedBlueprintPath}
+                onSelectBlueprint={onSelectBlueprint}
+                onAddActor={onAddActor}
+                dragPlace={dragPlace}
+                onDeleteBlueprint={onDeleteBlueprint}
+              />
+            )}
           </div>
           <div className={styles.stageWrap} style={stageWrapStyle}>
             <div className={styles.stageCard} data-castle-card>
@@ -206,13 +464,18 @@ export function SceneEditor({
                 <canvas
                   ref={canvasRef}
                   className={cx(styles.stageCanvas, !isPlaying && styles.stageCanvasEdit)}
-                  onPointerDown={(event) =>
-                    isPlaying
-                      ? playPointer.onPointerDown(event)
-                      : panGesture.isSpacePanning()
-                        ? panGesture.onPointerDown(event)
-                        : gesture.onPointerDown(event)
-                  }
+                  // 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)
@@ -242,12 +505,13 @@ export function SceneEditor({
                   canvasRef={canvasRef}
                   editCameraRef={editCameraRef}
                   sceneData={sceneData}
+                  previewSceneData={previewSceneData}
                   selectedActorIds={selectedActorIds}
                   snap={snapSettings}
-                  onArrange={actions.arrangeSelection}
-                  onClone={actions.duplicateSelection}
-                  onDelete={actions.deleteSelection}
-                  applyScene={(next) => onChange(formatJson(next))}
+                  onArrange={isBlueprintFile ? undefined : actions.arrangeSelection}
+                  onClone={isBlueprintFile ? undefined : actions.duplicateSelection}
+                  onDelete={isBlueprintFile ? undefined : actions.deleteSelection}
+                  applyScene={(next) => onChange(serialize(next))}
                   recordSnapshot={history.recordSnapshot}
                 />
               )}
@@ -258,7 +522,17 @@ export function SceneEditor({
               <SheetGrabHandle label={inspectorLabel} hint={inspectorHint} />
             </div>
             <div className={cx(styles.sheetBody, styles.inspectorBody)}>
-              {showMulti ? (
+              {hotbarBlueprint ? (
+                <BlueprintInspector
+                  name={hotbarBlueprint.name}
+                  template={hotbarBlueprint}
+                  files={files}
+                  onRename={blueprintActions.rename}
+                  onSetComponent={blueprintActions.setComponent}
+                  onAddBehavior={blueprintActions.addBehavior}
+                  onRemoveBehavior={blueprintActions.removeBehavior}
+                />
+              ) : showMulti ? (
                 <MultiSelectInspector
                   count={selectedActorIds.length}
                   onDeselectAll={() => {
@@ -269,10 +543,13 @@ export function SceneEditor({
               ) : selectedActor ? (
                 <ActorInspector
                   selectedActor={selectedActor}
+                  rawActor={rawSelectedActor}
+                  blueprintName={selectedBlueprintName}
                   files={files}
                   onSetComponent={actions.updateComponent}
                   onAddBehavior={actions.addBehavior}
                   onRemoveBehavior={actions.removeBehavior}
+                  onFork={isBlueprintFile ? undefined : onForkSelection}
                 />
               ) : (
                 <SceneInspector
@@ -320,352 +597,23 @@ function HeaderPlaybackButtons({ isPlaying, setIsPlaying, history }) {
     </>
   );
 }
-// Blueprint hotbar -- lightweight actor stamps saved in scene.editor.blueprints.
-function BlueprintHotbar({
-  sceneData,
-  files,
-  sprites,
-  canvasRef,
-  editCameraRef,
-  selectedActorIds,
-  onSelectActorIds,
-  isPlaying,
-  onChange,
-  history,
-}) {
-  const blueprints = sceneData.editor?.blueprints ?? [];
-  const dragRef = useRef(null);
-  const suppressClickRef = useRef(false);
-  const [dragPreview, setDragPreview] = useState(null);
-  // Right-click context menu anchored at the cursor: { blueprint, x, y }.
-  const [contextMenu, setContextMenu] = useState(null);
-  const closeContextMenu = useCallback(() => setContextMenu(null), []);
-  const onAdd = () => {
-    const { sceneData: next, newId } = addActor(sceneData, files, sprites);
-    history.recordSnapshot();
-    onChange(formatJson(next));
-    onSelectActorIds([newId]);
-  };
-  const onSaveSelection = () => {
-    const next = addSelectedActorBlueprint(sceneData, selectedActorIds);
-    if (next === sceneData) return;
-    history.commit(formatJson(next));
-  };
-  const onStamp = (blueprint, position) => {
-    const { sceneData: next, newId } = stampActorBlueprint(sceneData, blueprint, position);
-    if (next === sceneData) return;
-    history.commit(formatJson(next));
-    onSelectActorIds([newId]);
-  };
-  const onRemoveBlueprint = (blueprintId) => {
-    const next = removeActorBlueprint(sceneData, blueprintId);
-    if (next === sceneData) return;
-    history.commit(formatJson(next));
-  };
-  const onBlueprintContextMenu = (event, blueprint) => {
-    if (isPlaying) return;
-    event.preventDefault();
-    event.stopPropagation();
-    setContextMenu({ blueprint, x: event.clientX, y: event.clientY });
-  };
-  const onBlueprintPointerDown = (event, blueprint) => {
-    if (isPlaying || event.button !== 0) return;
-    event.preventDefault();
-    const drag = {
-      blueprint,
-      pointerId: event.pointerId,
-      startX: event.clientX,
-      startY: event.clientY,
-      moved: false,
-    };
-    dragRef.current = drag;
-    try {
-      event.currentTarget.setPointerCapture(event.pointerId);
-    } catch {
-      // Window listeners still finish the drag if capture is unavailable.
-    }
-    const onMove = (moveEvent) => {
-      if (moveEvent.pointerId !== drag.pointerId) return;
-      if (!drag.moved && Math.hypot(moveEvent.clientX - drag.startX, moveEvent.clientY - drag.startY) > DRAG_THRESHOLD) {
-        drag.moved = true;
-      }
-      if (drag.moved) {
-        setDragPreview({
-          blueprint,
-          x: moveEvent.clientX,
-          y: moveEvent.clientY,
-          overStage: Boolean(eventToStagePoint(moveEvent, canvasRef, editCameraRef)),
-        });
-      }
-    };
-    const onUp = (upEvent) => {
-      if (upEvent.pointerId !== drag.pointerId) return;
-      window.removeEventListener('pointermove', onMove);
-      window.removeEventListener('pointerup', onUp);
-      window.removeEventListener('pointercancel', onUp);
-      dragRef.current = null;
-      setDragPreview(null);
-      if (!drag.moved) return;
-      suppressClickRef.current = true;
-      const position = eventToStagePoint(upEvent, canvasRef, editCameraRef);
-      if (position) onStamp(blueprint, position);
-    };
-    window.addEventListener('pointermove', onMove);
-    window.addEventListener('pointerup', onUp);
-    window.addEventListener('pointercancel', onUp);
-  };
-  return (
-    <div className={styles.bpHotbar} aria-label="Blueprints">
-      <button
-        type="button"
-        className={styles.bpActionSlot}
-        aria-label="Save selected actor as blueprint"
-        title="Save selected actor as blueprint"
-        onClick={onSaveSelection}
-        disabled={isPlaying || selectedActorIds.length !== 1}>
-        <Icon name="stamp" />
-      </button>
-      <button
-        type="button"
-        className={styles.bpActionSlot}
-        aria-label="Add actor"
-        title="Add actor"
-        onClick={onAdd}
-        disabled={isPlaying}>
-        <span className={styles.dashedSquareIcon} aria-hidden="true" />
-      </button>
-      {blueprints.map((blueprint) => (
-        <button
-          key={blueprint.id}
-          type="button"
-          className={styles.bpSlot}
-          title={`Add ${blueprint.name}`}
-          disabled={isPlaying}
-          onPointerDown={(event) => onBlueprintPointerDown(event, blueprint)}
-          onContextMenu={(event) => onBlueprintContextMenu(event, blueprint)}
-          onClick={() => {
-            if (suppressClickRef.current) {
-              suppressClickRef.current = false;
-              return;
-            }
-            onStamp(blueprint);
-          }}>
-          <BlueprintThumbnail blueprint={blueprint} sprites={sprites} />
-        </button>
-      ))}
-      {dragPreview ? (
-        <BlueprintDragPreview preview={dragPreview} sprites={sprites} />
-      ) : null}
-      {contextMenu ? (
-        <BlueprintContextMenu
-          x={contextMenu.x}
-          y={contextMenu.y}
-          onRemove={() => onRemoveBlueprint(contextMenu.blueprint.id)}
-          onClose={closeContextMenu}
-        />
-      ) : null}
-    </div>
-  );
-}
-// Cursor-anchored right-click menu for a hotbar blueprint. Mirrors the
-// pxArtTimeline ContextMenu: reuses the shared `selArrangeMenu`/`selArrangeItem`
-// chrome, fixed-positions at the click point with viewport clamping, and closes
-// on outside pointerdown or Escape.
-function BlueprintContextMenu({ x, y, onRemove, onClose }) {
-  const ref = useRef(null);
-  const [pos, setPos] = useState({ left: x, top: y });
-  useLayoutEffect(() => {
-    const el = ref.current;
-    if (!el) return;
-    const rect = el.getBoundingClientRect();
-    const margin = 8;
-    const maxLeft = Math.max(margin, window.innerWidth - rect.width - margin);
-    const maxTop = Math.max(margin, window.innerHeight - rect.height - margin);
-    setPos({ left: Math.min(x, maxLeft), top: Math.min(y, maxTop) });
-  }, [x, y]);
-  useEffect(() => {
-    const onPointerDown = (event) => {
-      if (!ref.current?.contains(event.target)) onClose();
-    };
-    const onKeyDown = (event) => {
-      if (event.key === 'Escape') onClose();
-    };
-    window.addEventListener('pointerdown', onPointerDown);
-    window.addEventListener('keydown', onKeyDown);
-    return () => {
-      window.removeEventListener('pointerdown', onPointerDown);
-      window.removeEventListener('keydown', onKeyDown);
-    };
-  }, [onClose]);
-  return (
-    <div
-      ref={ref}
-      className={styles.selArrangeMenu}
-      role="menu"
-      aria-label="Blueprint"
-      style={{ position: 'fixed', left: pos.left, top: pos.top, transform: 'none' }}
-      onPointerDown={(event) => event.stopPropagation()}
-      onContextMenu={(event) => event.preventDefault()}>
-      <button
-        type="button"
-        role="menuitem"
-        className={styles.selArrangeItem}
-        onClick={() => {
-          onRemove();
-          onClose();
-        }}>
-        Remove blueprint
-      </button>
-    </div>
-  );
-}
-function BlueprintDragPreview({ preview, sprites }) {
-  const layout = preview.blueprint.actor?.components?.Layout;
-  const width = Math.max(24, Math.min(80, layout?.width ?? 48));
-  const height = Math.max(24, Math.min(80, layout?.height ?? 48));
-  return (
-    <div
-      className={cx(styles.bpDragPreview, preview.overStage && styles.bpDragPreviewOverStage)}
-      style={{
-        left: preview.x,
-        top: preview.y,
-        width,
-        height,
-        transform: `translate(-50%, -50%) rotate(${layout?.rotation ?? 0}deg)`,
-      }}>
-      <BlueprintThumbnail blueprint={preview.blueprint} sprites={sprites} preview />
-    </div>
-  );
-}
-function BlueprintThumbnail({ blueprint, sprites, preview = false }) {
-  const canvasRef = useRef(null);
-  const spritePath = blueprint.actor?.components?.Sprite?.file;
-  const sprite = spritePath ? sprites?.[spritePath] : null;
-  useEffect(() => {
-    const canvas = canvasRef.current;
-    if (!canvas || !sprite) return;
-    // A .pxart blueprint renders its first frame via the SDK.
-    renderSpriteFrame(sprite, 0, canvas);
-  }, [sprite]);
-  if (!sprite) {
-    return (
-      <span className={styles.bpSlotFallback}>
-        <Icon name="clone" />
-      </span>
-    );
-  }
-  return (
-    <canvas
-      ref={canvasRef}
-      className={cx(styles.bpSlotThumb, preview && styles.bpPreviewThumb)}
-      aria-hidden="true"
-    />
-  );
-}
-function addSelectedActorBlueprint(sceneData, selectedActorIds) {
-  if (selectedActorIds.length !== 1) return sceneData;
-  const actor = sceneData.actors.find((candidate) => candidate.id === selectedActorIds[0]);
-  if (!actor) return sceneData;
-  const next = structuredClone(sceneData);
-  const copy = structuredClone(actor);
-  delete copy.id;
-  if (copy.components?.Layout) {
-    copy.components.Layout = {
-      ...copy.components.Layout,
-      x: 0,
-      y: 0,
-    };
-  }
-  const blueprints = [...(next.editor?.blueprints ?? [])];
-  const name = makeBlueprintName(actor, blueprints.length);
-  blueprints.push({
-    id: makeBlueprintId(blueprints),
-    name,
-    actor: copy,
-  });
-  next.editor = {
-    ...(next.editor ?? {}),
-    blueprints,
-  };
-  return next;
-}
-function stampActorBlueprint(sceneData, blueprint, position) {
-  if (!blueprint?.actor) return { sceneData, newId: null };
-  const next = structuredClone(sceneData);
-  const existingIds = new Set(next.actors.map((actor) => actor.id));
-  const actor = structuredClone(blueprint.actor);
-  const newId = makeActorId(existingIds);
-  actor.id = newId;
-  actor.components = actor.components ?? {};
-  const layout = actor.components.Layout ?? { width: 64, height: 64, z: 0, rotation: 0 };
-  actor.components.Layout = {
-    ...layout,
-    x: Math.round((position?.x ?? cardSize.width / 2) - layout.width / 2),
-    y: Math.round((position?.y ?? cardSize.height / 2) - layout.height / 2),
-  };
-  next.actors.push(actor);
-  return { sceneData: next, newId };
-}
-function removeActorBlueprint(sceneData, blueprintId) {
-  const blueprints = sceneData.editor?.blueprints ?? [];
-  if (!blueprints.some((blueprint) => blueprint.id === blueprintId)) return sceneData;
-  const next = structuredClone(sceneData);
-  next.editor = {
-    ...(next.editor ?? {}),
-    blueprints: (next.editor?.blueprints ?? []).filter(
-      (blueprint) => blueprint.id !== blueprintId
-    ),
-  };
-  return next;
-}
-function eventToStagePoint(event, canvasRef, editCameraRef) {
-  const canvas = canvasRef.current;
-  if (!canvas) return null;
-  const rect = canvas.getBoundingClientRect();
-  if (
-    event.clientX < rect.left ||
-    event.clientX > rect.right ||
-    event.clientY < rect.top ||
-    event.clientY > rect.bottom
-  ) {
-    return null;
-  }
-  const raw = screenToCard(canvas, event.clientX, event.clientY);
-  const camera = editCameraRef.current ?? { x: 0, y: 0 };
-  return {
-    x: raw.x + camera.x,
-    y: raw.y + camera.y,
-  };
-}
-function makeBlueprintName(actor, index) {
-  const spriteFile = actor.components?.Sprite?.file;
-  if (spriteFile) return basename(spriteFile).replace(/\.pxart$/i, '');
-  return `Actor ${index + 1}`;
-}
-function makeBlueprintId(blueprints) {
-  const existing = new Set(blueprints.map((blueprint) => blueprint.id));
-  for (let index = 1; index < 1000; index++) {
-    const candidate = `blueprint-${index}`;
-    if (!existing.has(candidate)) return candidate;
-  }
-  return `blueprint-${Date.now()}`;
-}
-function makeActorId(existingIds) {
-  for (let attempt = 0; attempt < 64; attempt++) {
-    const candidate = Math.floor(Math.random() * 0xffffffff)
-      .toString(16)
-      .padStart(8, '0');
-    if (!existingIds.has(candidate)) return candidate;
-  }
-  return `actor-${Date.now()}`;
-}
-function makeSceneActions({ sceneData, commit, selectedActorIds, onSelectActorIds }) {
-  function commitScene(next) {
-    commit(formatJson(next));
+// `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(setActorComponent(sceneData, 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;
@@ -676,23 +624,28 @@ function makeSceneActions({ sceneData, commit, selectedActorIds, onSelectActorId
     removeBehavior: (actorId, behaviorName) =>
       commitScene(removeActorComponent(sceneData, actorId, behaviorName)),
     deleteSelection: () => {
-      if (selectedActorIds.length === 0) return;
+      if (isBlueprintFile || selectedActorIds.length === 0) return;
       commitScene(removeActors(sceneData, selectedActorIds));
       onSelectActorIds([]);
     },
     duplicateSelection: () => {
-      if (selectedActorIds.length === 0) return;
+      if (isBlueprintFile || selectedActorIds.length === 0) return;
       const { sceneData: next, newIds } = duplicateActors(sceneData, selectedActorIds);
       commitScene(next);
       if (newIds.length) onSelectActorIds(newIds);
     },
     arrangeSelection: (action) => {
-      if (selectedActorIds.length === 0) return;
+      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,
@@ -737,20 +690,10 @@ function parseHexColor(value) {
   };
 }
 function useSelectionInspectorSheet(open) {
-  const [snap, setSnap] = useState('high');
-  // Inspector visibility is driven by selection / multi-mode. Snap state
-  // persists across selections so switching keeps the user's chosen snap.
-  const effectiveSnap = open ? snap : 'hidden';
-  return useMobileSheet({
-    snap: effectiveSnap,
-    baseClassName: styles.inspector,
-    onTransition: (direction) => {
-      if (!open) return;
-      if (direction === 'tap') setSnap((prev) => (prev === 'high' ? 'low' : 'high'));
-      else if (direction === 'down') setSnap('low');
-      else if (direction === 'up') setSnap('high');
-    },
-  });
+  // 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).
+  return useMobileSheet({ open, baseClassName: styles.inspector });
 }
 function useSelectionGesture(args) {
   const dragRef = useRef(null);
@@ -765,7 +708,7 @@ function useSelectionGesture(args) {
     const cam = current.editCameraRef.current;
     const point = { x: raw.x + cam.x, y: raw.y + cam.y };
     current.canvasRef.current.setPointerCapture(event.pointerId);
-    const scene = makeScene(current.sceneData, behaviorClasses, current.sprites);
+    const scene = makeScene(current.sceneData, behaviorClasses, current.sprites, current.files);
     const actor = scene.actorAt(point.x, point.y);
     const drag = {
       pointerId: event.pointerId,
@@ -1160,7 +1103,7 @@ function finalizeMarquee(drag, current) {
   const m = current.marqueeRef.current;
   if (!m || !current.sceneData) return;
   if (m.width === 0 && m.height === 0) return;
-  const scene = makeScene(current.sceneData, behaviorClasses, current.sprites);
+  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);
@@ -1189,21 +1132,22 @@ function useSelectionKeyboard(args) {
       const current = ref.current;
       if (current.isPlaying || isEditableTarget(event.target)) return;
       if (event.key === 'Escape') {
-        if (current.selectedActorIds.length || current.multiSelectMode) {
+        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) return;
+        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.selectedActorIds.length === 0) return;
+        if (!current.sceneData || current.isBlueprintFile || current.selectedActorIds.length === 0) return;
         event.preventDefault();
         const { sceneData: next, newIds } = duplicateActors(
           current.sceneData,
@@ -1214,7 +1158,7 @@ function useSelectionKeyboard(args) {
         return;
       }
       if (event.key === 'Delete' || event.key === 'Backspace') {
-        if (!current.sceneData || current.selectedActorIds.length === 0) return;
+        if (!current.sceneData || current.isBlueprintFile || current.selectedActorIds.length === 0) return;
         event.preventDefault();
         current.commitScene(removeActors(current.sceneData, current.selectedActorIds));
         current.onSelectActorIds([]);
@@ -1227,6 +1171,7 @@ function useSelectionKeyboard(args) {
 function useScenePlayLoop({
   sceneData,
   sprites,
+  files,
   isPlaying,
   text,
   canvasRef,
@@ -1245,7 +1190,7 @@ function useScenePlayLoop({
       return;
     }
     if (!sceneData) return;
-    runtimeRef.current = makeScene(sceneData, behaviorClasses, sprites).clone();
+    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.
@@ -1270,7 +1215,7 @@ function useScenePlayLoop({
         : editViewportForZoom(editCameraRef.current.zoom);
       const scene = isPlaying
         ? runtimeRef.current
-        : makeScene(sceneData, behaviorClasses, sprites);
+        : makeScene(sceneData, behaviorClasses, sprites, files);
       if (scene) {
         const snap = getSnapSettings(sceneData);
         if (isPlaying) scene.update(dt);
@@ -1297,7 +1242,7 @@ function useScenePlayLoop({
     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, isPlaying, text, canvasRef, runtimeRef, marqueeRef, selectedActorIdsRef]);
+  }, [sprites, files, isPlaying, text, canvasRef, runtimeRef, marqueeRef, selectedActorIdsRef]);
 }
 function useScenePlayKeys(runtimeRef) {
   useEffect(() => {
@@ -1388,7 +1333,56 @@ function SceneInspector({ sceneData, snapSettings, onChangeScene, onChangeEditor
     </Panel>
   );
 }
-function ActorInspector({ selectedActor, files, onSetComponent, onAddBehavior, onRemoveBehavior }) {
+// 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,
+  files,
+  onRename,
+  onSetComponent,
+  onAddBehavior,
+  onRemoveBehavior,
+}) {
+  const templateActor = { id: '__blueprint__', components: template.components };
+  return (
+    <>
+      <div className={styles.instanceHint}>
+        <input
+          className={styles.blueprintNameInput}
+          value={name}
+          onChange={(event) => onRename?.(event.target.value)}
+          aria-label="Blueprint name"
+          spellCheck={false}
+        />
+      </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)}
+      />
+    </>
+  );
+}
+function ActorInspector({
+  selectedActor,
+  rawActor,
+  blueprintName,
+  files,
+  onSetComponent,
+  onAddBehavior,
+  onRemoveBehavior,
+  onFork,
+}) {
+  const isInstance = Boolean(rawActor?.blueprint);
   const presentNames = new Set(
     Object.entries(selectedActor.components)
       .filter(([, component]) => !!component)
@@ -1400,6 +1394,14 @@ function ActorInspector({ selectedActor, files, onSetComponent, onAddBehavior, o
   const behaviorEntries = Object.entries(selectedActor.components).filter((entry) => !!entry[1]);
   return (
     <>
+      {isInstance ? (
+        <div className={styles.instanceHint}>
+          <span className={styles.instanceHintLabel}>Instance of {blueprintName}</span>
+          {onFork ? (
+            <IconButton icon="code-fork" label="New blueprint from this actor" onClick={onFork} />
+          ) : null}
+        </div>
+      ) : null}
       <AddBehaviorPicker
         available={availableBehaviors}
         onAdd={(behaviorName) => onAddBehavior(selectedActor.id, behaviorName)}
@@ -1424,8 +1426,12 @@ function ActorInspector({ selectedActor, files, onSetComponent, onAddBehavior, o
             setComponent={(nextProps) => onSetComponent(selectedActor.id, behaviorName, nextProps)}
           />
         );
-        // Layout is core to every actor -- it cannot be removed.
-        const removable = behaviorName !== 'Layout';
+        // 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]));
         const isLast = index === behaviorEntries.length - 1;
         // Trash renders before the panel so the panel stays the wrapper's
         // last child -- the panel's own `:last-child` border zeroes out, and