castle-web-cli 0.4.81 → 0.4.83

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

@@ -7,7 +7,7 @@ import { cx, Icon, styles, useElementSize } from '../engine/ui';
 // as a sibling of the `<canvas>` and mirrors the `SceneUI` overlay approach:
 //
 // - A ResizeObserver measures the canvas-sized box so a card-unit (500x700)
-//   layer can be `scale()`d onto it -- the chrome (dashed box, corner dots,
+//   layer can be `scale()`d onto it -- the chrome (solid box, corner dots,
 //   center pivot) lives in card units inside that scaled layer and is
 //   translated by -camera so it tracks the edit camera exactly like the canvas
 //   draw path (`ctx.translate(-camera.x, -camera.y)`).
@@ -27,6 +27,11 @@ const ACTION_GAP_PX = 22; // px from a box edge to clone/delete buttons
 const ROTATE_STEP = 15; // degrees -- rotation snaps to this increment when grid snap is on
 const ROTATE_MAGNET = 7; // degrees -- within this band of the pre-drag angle, snap back to it exactly
 const MIN_LAYOUT_SIZE = 4; // card units; prevents inverted / zero-size Layout boxes
+// Below this on-screen box extent (px) along an axis, the mid-edge scale handle
+// for that axis would collide with the corner handles, so we drop it and keep
+// only the corners. Gated per-axis: n/s depend on the box's px width, e/w on its
+// px height (a wide, short box can keep n/s while dropping e/w, and vice versa).
+const EDGE_HANDLE_MIN_PX = 40;
 // Move/grab handle is intentionally hidden for now (its drag logic + helpers
 // stay wired below so it can be re-enabled later); flip this to render it.
 const SHOW_MOVE_HANDLE = false;
@@ -61,6 +66,7 @@ export function SelectionOverlay({
   editCameraRef,
   sceneData,
   previewSceneData,
+  sprites,
   selectedActorIds,
   snap,
   onArrange,
@@ -107,14 +113,14 @@ export function SelectionOverlay({
     if (!canvas || !sceneData || selectedActorIds.length === 0) return null;
     const startPoint = screenToCard(canvas, event.clientX, event.clientY);
     const starts = collectLayoutStarts(previewSceneData, selectedActorIds);
-    const state = { recorded: false };
+    const state = { recorded: false, lastKey: '0,0' };
     return {
       onMove: (moveEvent) => {
         const point = screenToCard(canvas, moveEvent.clientX, moveEvent.clientY);
         const dx = snapDelta(point.x - startPoint.x, snap);
         const dy = snapDelta(point.y - startPoint.y, snap);
         const next = moveSelected(sceneData, previewSceneData, selectedActorIds, starts, dx, dy);
-        applyDragResult(next, sceneData, state, recordSnapshot, applyScene);
+        applyDragResult(next, sceneData, `${dx},${dy}`, state, recordSnapshot, applyScene);
       },
     };
   });
@@ -139,11 +145,11 @@ export function SelectionOverlay({
         // pointer-down snapshot. `onMove` closes over the `sceneData` captured at
         // drag-start, where the actor still sits at its original angle, so when
         // the magnet pulls `delta` back to 0 `rotateSelected` returns that
-        // unchanged snapshot. `applyDragResult`'s `next === sceneData` guard
-        // would treat that as a no-op and skip it, stranding the actor on the
-        // last grid step -- the reason returning to the original angle felt
-        // impossible. Re-applying whenever the delta changes lets delta 0
-        // actually restore the start angle.
+        // unchanged snapshot; an identity guard would treat that as a no-op and
+        // skip it, stranding the actor on the last grid step -- the reason
+        // returning to the original angle felt impossible. Re-applying whenever
+        // the delta changes lets delta 0 actually restore the start angle.
+        // (Scale/move share this contract via `applyDragResult`'s `key` param.)
         if (delta === state.lastDelta) return;
         state.lastDelta = delta;
         setGroupFrameRotation(normalizeAngle(startFrameRotation + delta));
@@ -165,7 +171,7 @@ export function SelectionOverlay({
     const startTransform = makeBoundsTransform(frame, frame.rotation);
     const startPointer = pointerLocal(canvas, editCameraRef, event, startTransform);
     const starts = collectLayoutStarts(previewSceneData, selectedActorIds);
-    const state = { recorded: false };
+    const state = { recorded: false, lastKey: '0,0,0' };
     return {
       onMove: (moveEvent) => {
         const point = pointerLocal(canvas, editCameraRef, moveEvent, startTransform);
@@ -179,7 +185,8 @@ export function SelectionOverlay({
           moveEvent.shiftKey
         );
         const next = scaleSelected(sceneData, previewSceneData, selectedActorIds, starts, startTransform, nextBounds);
-        applyDragResult(next, sceneData, state, recordSnapshot, applyScene);
+        // Include shift (uniform) in the key so toggling it without moving still re-applies.
+        applyDragResult(next, sceneData, `${dx},${dy},${moveEvent.shiftKey ? 1 : 0}`, state, recordSnapshot, applyScene);
       },
     };
   });
@@ -190,7 +197,7 @@ export function SelectionOverlay({
   }
 
   const geometry = getOverlayGeometry(frame, box, camera);
-  const colliderFrames = getSelectedColliderFrames(previewSceneData, selectedActorIds);
+  const colliderFrames = getSelectedColliderFrames(previewSceneData, selectedActorIds, sprites);
 
   return (
     <div ref={rootRef} className={styles.selOverlayRoot}>
@@ -221,17 +228,6 @@ export function SelectionOverlay({
               }}
             />
           ))}
-          {/* Rotate about the actor center, in card units, exactly like the
-              canvas. Sits between the scale + camera-translate layers and the
-              card-unit chrome. */}
-          <div
-            className={styles.selChromeRotate}
-            style={{
-              transformOrigin: `${geometry.centerCardX}px ${geometry.centerCardY}px`,
-              transform: `rotate(${geometry.rotation}deg)`,
-            }}>
-            <SelectionChrome frame={frame} stemLength={geometry.stemLength} />
-          </div>
         </div>
       </div>
 
@@ -239,11 +235,21 @@ export function SelectionOverlay({
           readable. The rotate handle orbits via its anchor; clone/delete flip
           above/below to stay clear of it. */}
       <div className={styles.selButtonLayer}>
-        {/* Dashed bounding box + center pivot render here (un-scaled px layer)
-            rather than the chrome layer, so their stroke width, dash pattern,
-            and pivot size stay constant with zoom. Their px dimensions are
-            projected from the box's screen extents, so the box still traces the
-            actual bounds. */}
+        {/* Solid bounding box, connector stem, and center pivot render here
+            (un-scaled px layer) rather than the chrome layer, so their stroke
+            width and pivot size stay constant with zoom. Their px dimensions
+            are projected from the box's screen extents, so the box still traces
+            the actual bounds. The stem is anchored at the box's rotated
+            right-center edge and rotates about that point out to the handle. */}
+        <div
+          className={styles.selStem}
+          style={{
+            left: geometry.stemStart.x,
+            top: geometry.stemStart.y,
+            width: geometry.stemLengthPx,
+            transform: `translateY(-50%) rotate(${geometry.rotation}deg)`,
+          }}
+        />
         <div
           className={styles.selBox}
           style={{
@@ -332,22 +338,6 @@ export function SelectionOverlay({
   );
 }
 
-// Chrome in card units: dashed bounding box, scale handles, connector stem, and
-// center pivot dot. The layer itself ignores pointer events; only the handles
-// opt back in so the canvas still receives ordinary selection gestures.
-function SelectionChrome({ frame, stemLength }) {
-  const left = frame.x;
-  const top = frame.y;
-  const width = frame.width;
-  const height = frame.height;
-  const centerY = top + height / 2;
-  if (stemLength <= 0) return null;
-  // Connector stem from the right-center edge out to the rotate handle. Lives in
-  // the rotated chrome so it swings with the actor. (The box + pivot render in
-  // the un-scaled px layer so their stroke/size stay constant with zoom.)
-  return <div className={styles.selStem} style={{ left: left + width, top: centerY, width: stemLength }} />;
-}
-
 // `sceneData` here is always the MERGED preview scene (see the note on
 // `SelectionOverlay` above) -- every Layout read in this file is.
 function getSelectionFrame(sceneData, actorIds, preferredRotation = null) {
@@ -381,20 +371,28 @@ function getOverlayGeometry(frame, box, camera) {
   const halfW = (frame.width / 2 + HANDLE_OFFSET) * sx;
   const halfH = (frame.height / 2 + HANDLE_OFFSET) * sy;
   const rotateAnchor = getRotateAnchor({ centerX, centerY, halfW, rotation });
+  // Stem starts at the box's rotated right-center edge and runs out to the
+  // rotate handle. Projected to screen px (like the box + handles) so its
+  // thickness stays constant with zoom instead of scaling with the chrome layer.
+  const rad = (rotation * Math.PI) / 180;
+  const halfWpx = (frame.width / 2) * sx;
+  const stemStart = {
+    x: centerX + halfWpx * Math.cos(rad),
+    y: centerY + halfWpx * Math.sin(rad),
+  };
   return {
     sx,
     sy,
     camX,
     camY,
     rotation,
-    centerCardX,
-    centerCardY,
     centerX,
     centerY,
     halfH,
     rotateAnchor,
     cloneAnchor: getActionAnchor({ centerX, centerY, halfH, rotateAnchor }),
-    stemLength: HANDLE_OFFSET + GAP_PX / sx,
+    stemStart,
+    stemLengthPx: Math.hypot(rotateAnchor.x - stemStart.x, rotateAnchor.y - stemStart.y),
     boxWidthPx: frame.width * sx,
     boxHeightPx: frame.height * sy,
     scaleHandles: getScaleHandleAnchors({
@@ -407,13 +405,23 @@ function getOverlayGeometry(frame, box, camera) {
   };
 }
 
-// Project the 8 scale handles from the box's rotated corners/edges into screen
-// px so they can render in the un-scaled button layer at a constant size.
+// Project the scale handles from the box's rotated corners/edges into screen px
+// so they can render in the un-scaled button layer at a constant size. Corners
+// are always shown; mid-edge handles are dropped once the box is too small along
+// their axis (see EDGE_HANDLE_MIN_PX) so they don't overlap the corners.
 function getScaleHandleAnchors({ centerX, centerY, halfWpx, halfHpx, rotation }) {
   const rad = (rotation * Math.PI) / 180;
   const cosR = Math.cos(rad);
   const sinR = Math.sin(rad);
-  return SCALE_HANDLES.map((handle) => {
+  const boxWidthPx = halfWpx * 2;
+  const boxHeightPx = halfHpx * 2;
+  return SCALE_HANDLES.filter((handle) => {
+    if (handle.corner) return true;
+    // n/s run along the box's width; e/w run along its height.
+    return handle.x === 0
+      ? boxWidthPx >= EDGE_HANDLE_MIN_PX
+      : boxHeightPx >= EDGE_HANDLE_MIN_PX;
+  }).map((handle) => {
     const lx = handle.x * halfWpx;
     const ly = handle.y * halfHpx;
     return {
@@ -447,7 +455,7 @@ function getActionAnchor({ centerX, centerY, halfH, rotateAnchor }) {
   };
 }
 
-function getSelectedColliderFrames(sceneData, actorIds) {
+function getSelectedColliderFrames(sceneData, actorIds, sprites) {
   if (!sceneData || !actorIds || actorIds.length === 0) return [];
   const wanted = new Set(actorIds);
   return sceneData.actors
@@ -455,7 +463,7 @@ function getSelectedColliderFrames(sceneData, actorIds) {
     .map((actor) => {
       const layout = actor.components.Layout;
       const collider = actor.components.Collider;
-      const rect = getColliderRect(actor);
+      const rect = getColliderRect(actor, sprites);
       if (!layout || !collider || !rect) return null;
       return {
         actorId: actor.id,
@@ -598,9 +606,20 @@ function usePointerDragHandle(begin) {
   }, []);
 }
 
-function applyDragResult(next, sceneData, state, recordSnapshot, applyScene) {
-  if (next === sceneData) return;
-  if (!state.recorded) {
+// Gate the commit on the gesture's snapped input (`key`), not on
+// `next === sceneData`. During a drag the handlers compute `next` relative to
+// the pointer-down `sceneData`, so returning the handle to its start value
+// makes `next` identity-equal to that snapshot -- an identity guard would treat
+// that as a no-op and skip `applyScene`, stranding the actor on the last grid
+// step (the reason handles couldn't be dragged back to their origin). Keying on
+// the snapped input re-applies whenever it changes, including back to the start
+// key, so the origin is reachable. The identity check now only decides whether
+// to record the undo snapshot, so a pure no-op drag never touches history. This
+// mirrors the rotate handle's delta-keyed commit.
+function applyDragResult(next, sceneData, key, state, recordSnapshot, applyScene) {
+  if (key === state.lastKey) return;
+  state.lastKey = key;
+  if (next !== sceneData && !state.recorded) {
     recordSnapshot();
     state.recorded = true;
   }

package/kits/basic-2d/editors/inspectorSheet.js

@@ -5,5 +5,9 @@ import { styles, useMobileSheet } from '../engine/ui';
 // visibility; the sheet hook owns the resize height and the settle-on-release
 // behavior (drag the grab handle to resize, tap it to toggle peek / expanded).
 export function useInspectorSheet(inspectorOpen) {
-  return useMobileSheet({ open: inspectorOpen, baseClassName: styles.inspector });
+  return useMobileSheet({
+    open: inspectorOpen,
+    baseClassName: styles.inspector,
+    storageKey: 'pxart-inspector',
+  });
 }

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

@@ -1,4 +1,4 @@
-import React, { useCallback, useEffect, useRef } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { configureSceneCanvas, makeScene } from './scene';
 import { SceneUI } from './SceneUI';
 // Engine-level scene player: mount a `SceneRuntime` against a canvas, wire
@@ -9,6 +9,12 @@ import { SceneUI } from './SceneUI';
 export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirstFrame }) {
   const canvasRef = useRef(null);
   const runtimeRef = useRef(null);
+  // An error thrown from a behavior's update/draw kills the raf loop (it can't
+  // schedule the next frame), which otherwise just black-screens the preview
+  // with the throw buried in the console. Capture it here and show a redbox
+  // overlay instead. `runId` bumps to remount the loop on Restart.
+  const [error, setError] = useState(null);
+  const [runId, setRunId] = useState(0);
   const getRuntime = useCallback(() => runtimeRef.current, []);
   useEffect(() => {
     const canvas = canvasRef.current;
@@ -54,8 +60,18 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
     canvas.addEventListener('pointermove', onPointerMove);
     canvas.addEventListener('pointerup', onPointerUp);
     canvas.addEventListener('pointercancel', onPointerUp);
-    canvas.focus();
-    const stopLoop = startPlayerLoop(canvas, ctx, runtime, onFirstFrame);
+    // Don't steal focus from the embedding shell (e.g. the chat composer) on
+    // reload/remount. A real standalone/play, or an iframe that's
+    // already focused, still auto-focuses; a click into the game always
+    // focuses via onPointerDown above.
+    if (document.hasFocus() || window.parent === window) canvas.focus();
+    const onLoopError = (err) => {
+      // Forward to the console (the serve log picks it up) and surface it.
+      // eslint-disable-next-line no-console
+      console.error(err);
+      setError(err);
+    };
+    const stopLoop = startPlayerLoop(canvas, ctx, runtime, onFirstFrame, onLoopError);
     return () => {
       stopLoop();
       window.removeEventListener('keydown', onKeyDown);
@@ -67,6 +83,10 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
       runtimeRef.current = null;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [runId]);
+  const onRestart = useCallback(() => {
+    setError(null);
+    setRunId((n) => n + 1);
   }, []);
   return (
     <div style={{ position: 'fixed', inset: 0, background: '#000' }}>
@@ -76,19 +96,28 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
         style={{ width: '100%', height: '100%', display: 'block', outline: 'none' }}
       />
       <SceneUI getRuntime={getRuntime} />
+      {error ? <PlayErrorOverlay error={error} onRestart={onRestart} /> : null}
     </div>
   );
 }
-function startPlayerLoop(canvas, ctx, runtime, onFirstFrame) {
+function startPlayerLoop(canvas, ctx, runtime, onFirstFrame, onError) {
   let raf = 0;
   let previousTime = performance.now();
   let firstFrameSignaled = false;
   const tick = (now) => {
     const dt = Math.min(0.033, (now - previousTime) / 1000);
     previousTime = now;
-    runtime.update(dt);
-    configureSceneCanvas(canvas, ctx);
-    runtime.draw(ctx, { useCamera: true });
+    // A throw in a behavior's update/draw must not abort the loop silently:
+    // catch it, surface it via onError, and stop scheduling frames (so it
+    // doesn't rethrow 60x/second). Restart remounts a fresh loop.
+    try {
+      runtime.update(dt);
+      configureSceneCanvas(canvas, ctx);
+      runtime.draw(ctx, { useCamera: true });
+    } catch (err) {
+      onError?.(err);
+      return;
+    }
     if (!firstFrameSignaled) {
       firstFrameSignaled = true;
       // Wait one frame so the draw composites before reveal, avoiding a blank flash.
@@ -99,3 +128,69 @@ function startPlayerLoop(canvas, ctx, runtime, onFirstFrame) {
   raf = requestAnimationFrame(tick);
   return () => cancelAnimationFrame(raf);
 }
+// Redbox overlay shown when the play loop throws. Covers the canvas with the
+// error name/message and stack so a broken behavior is legible instead of a
+// black screen. Restart remounts the loop; fixing the code and restarting the
+// serve reloads the whole preview fresh.
+function PlayErrorOverlay({ error, onRestart }) {
+  const name = error?.name ?? 'Error';
+  const message = error?.message ?? String(error);
+  const stack = typeof error?.stack === 'string' ? error.stack : '';
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        inset: 0,
+        zIndex: 2147483000,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 12,
+        padding: '20px 22px',
+        background: 'rgba(20, 8, 8, 0.94)',
+        color: '#ffd9dc',
+        font: "13px/1.5 'SFMono-Regular', Consolas, 'Liberation Mono', monospace",
+        overflow: 'auto',
+        boxSizing: 'border-box',
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+        <span style={{ fontSize: 15, fontWeight: 700, color: '#ff6b74' }}>Play error</span>
+        <button
+          type="button"
+          onClick={onRestart}
+          style={{
+            marginLeft: 'auto',
+            padding: '4px 12px',
+            border: '1px solid #a02828',
+            borderRadius: 4,
+            background: '#a02828',
+            color: '#fff',
+            font: 'inherit',
+            cursor: 'pointer',
+          }}
+        >
+          Restart
+        </button>
+      </div>
+      <div style={{ color: '#fff', fontWeight: 600, wordBreak: 'break-word' }}>
+        {name}: {message}
+      </div>
+      {stack ? (
+        <pre
+          style={{
+            margin: 0,
+            whiteSpace: 'pre-wrap',
+            wordBreak: 'break-word',
+            color: '#e79aa0',
+            fontSize: 12,
+          }}
+        >
+          {stack}
+        </pre>
+      ) : null}
+      <div style={{ color: '#c98a8f', fontSize: 12 }}>
+        The preview stopped. Fix the code and restart the serve to reload, or press Restart to retry.
+      </div>
+    </div>
+  );
+}

package/kits/basic-2d/engine/autoInspector.jsx

@@ -1,6 +1,18 @@
 import React from 'react';
 import { CheckboxField, ColorField, NumberField, Panel, TextField, isHexColor } from './ui';
-export function AutoFields({ defaultProps, component, setComponent, only, exclude }) {
+// Build the override-indicator field props (purple tint + "Default: X [Reset]")
+// for a single property from a behavior panel's override context. Returns an
+// empty object when there's no context (blueprint template editing) or the
+// property isn't overridden on this instance, so fields render normally.
+export function overrideProps(override, prop) {
+  if (!override || !override.isOverridden(prop)) return {};
+  return {
+    overridden: true,
+    defaultValue: override.baseline(prop),
+    onReset: () => override.reset(prop),
+  };
+}
+export function AutoFields({ defaultProps, component, setComponent, only, exclude, override }) {
   const keys = Object.keys(defaultProps).filter((key) => {
     if (only) return only.includes(key);
     if (exclude) return !exclude.includes(key);
@@ -14,14 +26,15 @@ export function AutoFields({ defaultProps, component, setComponent, only, exclud
         const set = (value) => setComponent({ [key]: value });
         const label = humanizeKey(key);
         const sample = fallback ?? current;
+        const ov = overrideProps(override, key);
         if (typeof sample === 'number') {
-          return <NumberField key={key} label={label} value={current} onChange={set} />;
+          return <NumberField key={key} label={label} value={current} onChange={set} {...ov} />;
         }
         if (typeof sample === 'boolean') {
-          return <CheckboxField key={key} label={label} checked={current} onChange={set} />;
+          return <CheckboxField key={key} label={label} checked={current} onChange={set} {...ov} />;
         }
         if (isHexColor(sample)) {
-          return <ColorField key={key} label={label} value={current} onChange={set} />;
+          return <ColorField key={key} label={label} value={current} onChange={set} {...ov} />;
         }
         return (
           <TextField
@@ -29,16 +42,22 @@ export function AutoFields({ defaultProps, component, setComponent, only, exclud
             label={label}
             value={current == null ? '' : String(current)}
             onChange={set}
+            {...ov}
           />
         );
       })}
     </>
   );
 }
-export function AutoInspector({ behaviorName, defaultProps, component, setComponent }) {
+export function AutoInspector({ behaviorName, defaultProps, component, setComponent, override }) {
   return (
-    <Panel title={humanizeKey(behaviorName)}>
-      <AutoFields defaultProps={defaultProps} component={component} setComponent={setComponent} />
+    <Panel title={humanizeKey(behaviorName)} overridden={override?.anyOverridden()}>
+      <AutoFields
+        defaultProps={defaultProps}
+        component={component}
+        setComponent={setComponent}
+        override={override}
+      />
     </Panel>
   );
 }

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

@@ -8,7 +8,7 @@
 // editors (which also mint/fork/migrate/cascade-delete blueprint files).
 import { formatJson } from './files';
 import { DEFAULT_RESOLUTION, TRANSPARENT, serializeCompact } from './pxart';
-import { cardSize, mintActorId } from './scene';
+import { cardSize, dedupeActorId } from './scene';
 
 export const BLUEPRINTS_DIR = 'blueprints';
 export const DRAWINGS_DIR = 'drawings';
@@ -126,6 +126,79 @@ function mintBlueprintPath(existingPaths) {
   return `${BLUEPRINTS_DIR}/blueprint-${max + 1}.scene`;
 }
 
+// "auto-tetris" -> "Auto Tetris". Splits on non-alphanumeric runs (covers the
+// hyphen/underscore ids actors typically use) and title-cases each word.
+function humanizeActorId(id) {
+  return id
+    .split(/[^a-zA-Z0-9]+/)
+    .filter(Boolean)
+    .map((word) => word[0].toUpperCase() + word.slice(1))
+    .join(' ');
+}
+
+// "Auto Tetris" -> "auto-tetris" for the filename slug. Kept independent of
+// the actor id's own formatting (an id could already be any casing/shape).
+function slugifyActorId(id) {
+  return id
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
+// Mint a readable, unique actor id from a display name (a blueprint's `name`):
+// slugified and slug-suffix-deduped against `existing` (`cauldron`,
+// `cauldron-2`, ...). This is the editor's placement/creation default, so a
+// freshly placed actor reads as `cauldron` rather than an opaque hex id.
+// `mintActorId` (hex) still backs runtime spawns and the dedup fallback.
+export function mintActorIdFromName(existing, name) {
+  const base = slugifyActorId(typeof name === 'string' ? name : '');
+  return dedupeActorId(existing, base);
+}
+
+// Derive a migration blueprint's { name, path } from the orphan actor's own
+// `id` -- the one meaningful signal available at migration time (vs. the
+// anonymous "Blueprint N" counter), so e.g. an actor `id: "logo"` mints
+// `blueprints/logo.scene` named "Logo" instead of "Blueprint 1". Returns null
+// when the id doesn't yield a usable name/slug, so the caller falls back to
+// the counter-based mint functions.
+//
+// Collision safety is load-bearing: `knownBlueprints` includes every
+// already-migrated blueprint in this same run (see the caller's loop), so two
+// orphan actors that humanize to the same name, or that collide with a
+// pre-existing blueprint, must never mint the same path or duplicate name.
+// Deterministically disambiguate with a numeric suffix instead.
+function deriveBlueprintName(actorId, knownBlueprints) {
+  if (typeof actorId !== 'string') return null;
+  const baseSlug = slugifyActorId(actorId);
+  const baseName = humanizeActorId(actorId.trim());
+  if (!baseSlug || !baseName) return null;
+  const existingNames = new Set(knownBlueprints.map((blueprint) => blueprint.name));
+  const existingPaths = new Set(knownBlueprints.map((blueprint) => blueprint.path));
+  const MAX_ATTEMPTS = 1000;
+  for (let suffix = 1; suffix <= MAX_ATTEMPTS; suffix += 1) {
+    const name = suffix === 1 ? baseName : `${baseName} ${suffix}`;
+    const path = suffix === 1 ? `${BLUEPRINTS_DIR}/${baseSlug}.scene` : `${BLUEPRINTS_DIR}/${baseSlug}-${suffix}.scene`;
+    if (!existingNames.has(name) && !existingPaths.has(path)) return { name, path };
+  }
+  // Pathological: 1000 colliding suffixes. Let the caller fall back to the
+  // counter-based mint functions rather than looping forever.
+  return null;
+}
+
+// { name, path } for a freshly minted migration blueprint: the actor id's
+// derived name/slug when usable and collision-free, else the anonymous
+// counter (see `deriveBlueprintName`). Factored out so the branching here
+// doesn't add to `migrateOrphanActors`'s own complexity.
+function mintMigrationBlueprintName(actorId, knownBlueprints) {
+  const derived = deriveBlueprintName(actorId, knownBlueprints);
+  if (derived) return derived;
+  return {
+    name: mintBlueprintName(knownBlueprints.map((blueprint) => blueprint.name)),
+    path: mintBlueprintPath(knownBlueprints.map((blueprint) => blueprint.path)),
+  };
+}
+
 export function formatBlueprintFileText(name, components) {
   return formatJson({ name, actors: [{ components }] });
 }
@@ -260,9 +333,23 @@ function mintDrawingPath(files) {
   return `${DRAWINGS_DIR}/drawing-${max + 1}.pxart`;
 }
 
+// The z that draws on top of every current actor: max effective z + 1 (0 for
+// an empty scene). An actor's effective z resolves its own Layout override
+// first, then its blueprint template, then 0 -- so this beats instances that
+// only inherit z from their blueprint.
+function topZ(actors, files) {
+  let max = -Infinity;
+  for (const actor of actors ?? []) {
+    const template = actor.blueprint ? getBlueprintTemplate(files, actor.blueprint) : null;
+    const z = actor.components?.Layout?.z ?? template?.components?.Layout?.z ?? 0;
+    if (z > max) max = z;
+  }
+  return max === -Infinity ? 0 : max + 1;
+}
+
 export function addActorWithBlueprint(sceneData, files) {
-  const width = 64;
-  const height = 64;
+  const width = 50;
+  const height = 50;
   const drawingFile = { path: mintDrawingPath(files), text: blankPxArtText() };
   const components = {
     Layout: { width, height, z: 0 },
@@ -271,10 +358,12 @@ export function addActorWithBlueprint(sceneData, files) {
   const blueprintFile = mintBlueprintFile(files, components);
   const next = structuredClone(sceneData);
   const existingIds = new Set(next.actors.map((actor) => actor.id));
-  const newId = mintActorId(existingIds);
+  const newId = mintActorIdFromName(existingIds, blueprintFile.name);
   const x = Math.round((cardSize.width - width) / 2);
   const y = Math.round((cardSize.height - height) / 2);
-  next.actors.push({ id: newId, blueprint: blueprintFile.path, components: { Layout: { x, y } } });
+  // Guarantee the new actor renders on top of whatever's already there.
+  const z = topZ(next.actors, files);
+  next.actors.push({ id: newId, blueprint: blueprintFile.path, components: { Layout: { x, y, z } } });
   return { sceneData: next, newId, blueprintFile, drawingFile };
 }
 
@@ -284,8 +373,8 @@ export function addActorWithBlueprint(sceneData, files) {
 export function blueprintDropXY(files, blueprintPath, position, snap) {
   const template = getBlueprintTemplate(files, blueprintPath);
   const layout = template?.components?.Layout ?? {};
-  const width = layout.width ?? 64;
-  const height = layout.height ?? 64;
+  const width = layout.width ?? 50;
+  const height = layout.height ?? 50;
   const dropX = position?.x ?? cardSize.width / 2;
   const dropY = position?.y ?? cardSize.height / 2;
   return {
@@ -301,7 +390,8 @@ export function blueprintDropXY(files, blueprintPath, position, snap) {
 export function placeBlueprintInstance(sceneData, files, blueprintPath, position, snap) {
   const next = structuredClone(sceneData);
   const existingIds = new Set(next.actors.map((actor) => actor.id));
-  const newId = mintActorId(existingIds);
+  const template = getBlueprintTemplate(files, blueprintPath);
+  const newId = mintActorIdFromName(existingIds, template?.name);
   const { x, y } = blueprintDropXY(files, blueprintPath, position, snap);
   next.actors.push({ id: newId, blueprint: blueprintPath, components: { Layout: { x, y } } });
   return { sceneData: next, newId };
@@ -408,11 +498,19 @@ export function migrateOrphanActors(files, behaviors, sceneData) {
       if (!props) continue;
       const Behavior = findBehavior(behaviors, behaviorName);
       const { inherited, overridden } = splitByInherit(Behavior, props);
-      if (Object.keys(inherited).length > 0) templateComponents[behaviorName] = inherited;
+      // A behavior attached with no props at all (e.g. `AutoTetris: {}`) has
+      // both `inherited` and `overridden` empty. It must still land somewhere,
+      // or the attachment itself -- not just some prop of it -- silently
+      // vanishes from the resolved actor. Fall back to the template side (as
+      // `{}`) so the instance keeps referencing the behavior exactly once.
+      if (Object.keys(inherited).length > 0 || Object.keys(overridden).length === 0) {
+        templateComponents[behaviorName] = inherited;
+      }
       if (Object.keys(overridden).length > 0) instanceOverrides[behaviorName] = overridden;
     }
-    const name = mintBlueprintName(knownBlueprints.map((blueprint) => blueprint.name));
-    const path = mintBlueprintPath(knownBlueprints.map((blueprint) => blueprint.path));
+    // The actor's own id is the one meaningful signal available here (vs. an
+    // anonymous "Blueprint N") -- see `mintMigrationBlueprintName`.
+    const { name, path } = mintMigrationBlueprintName(actor.id, knownBlueprints);
     const text = formatBlueprintFileText(name, templateComponents);
     newBlueprintFiles.push({ path, text });
     knownBlueprints = [...knownBlueprints, { path, name, components: templateComponents }];