castle-web-cli 0.4.82 → 0.4.83

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

@@ -0,0 +1,146 @@
+// Single source of truth for the Collider rect. Lives in engine/ (not
+// behaviors/) so SceneRuntime can use it directly, with behaviors/Collider.jsx
+// (its `draw`, and its `getColliderRect`/`intersects` re-exports) delegating
+// here instead of keeping a second, drifting copy.
+import { frameCount, renderSpriteFrame } from './pxart';
+import { spriteDestRect } from './spriteGeometry';
+
+// Union bounding box (fraction of native resolution, 0..1) of every opaque
+// (alpha > 0) pixel across ALL animation frames of a sprite, or null when the
+// art is fully transparent. Unioning across frames keeps an animated sprite's
+// collider from pulsing frame to frame. Cached in a WeakMap keyed by the
+// sprite object -- a sprite edit produces a fresh object (same invalidation
+// lifecycle as Sprite.jsx's rendered-canvas cache), so a stale entry never
+// outlives the art it was computed from.
+const opaqueBoundsCache = new WeakMap();
+
+// Expand `acc` (in pixel units) to cover every opaque pixel of the canvas's
+// current contents.
+function accumulateOpaquePixels(acc, ctx, canvas) {
+  if (!ctx || canvas.width === 0 || canvas.height === 0) return;
+  const { data } = ctx.getImageData(0, 0, canvas.width, canvas.height);
+  for (let y = 0; y < canvas.height; y++) {
+    for (let x = 0; x < canvas.width; x++) {
+      if (data[(y * canvas.width + x) * 4 + 3] === 0) continue;
+      if (x < acc.minX) acc.minX = x;
+      if (y < acc.minY) acc.minY = y;
+      if (x + 1 > acc.maxX) acc.maxX = x + 1;
+      if (y + 1 > acc.maxY) acc.maxY = y + 1;
+    }
+  }
+}
+
+function opaqueBoundsFraction(sprite) {
+  if (opaqueBoundsCache.has(sprite)) return opaqueBoundsCache.get(sprite);
+
+  const { width, height } = sprite.resolution;
+  const canvas = document.createElement('canvas');
+  const ctx = canvas.getContext('2d');
+  const acc = { minX: Infinity, minY: Infinity, maxX: -Infinity, maxY: -Infinity };
+  const total = frameCount(sprite);
+  for (let frame = 0; frame < total; frame++) {
+    renderSpriteFrame(sprite, frame, canvas);
+    accumulateOpaquePixels(acc, ctx, canvas);
+  }
+
+  const bounds =
+    acc.minX <= acc.maxX && acc.minY <= acc.maxY && width > 0 && height > 0
+      ? {
+          x: acc.minX / width,
+          y: acc.minY / height,
+          width: (acc.maxX - acc.minX) / width,
+          height: (acc.maxY - acc.minY) / height,
+        }
+      : null;
+  opaqueBoundsCache.set(sprite, bounds);
+  return bounds;
+}
+
+// True when a resolved sprite has no opaque pixels across any frame -- fully
+// transparent art (e.g. a brand-new blank drawing). The editor draws an
+// empty-actor placeholder for these so a blank actor isn't invisible. Shares
+// `opaqueBoundsFraction`'s per-sprite cache (a sprite edit yields a fresh
+// object, which invalidates it).
+export function spriteIsEmpty(sprite) {
+  return !sprite || opaqueBoundsFraction(sprite) === null;
+}
+
+// The `mode: 'auto'` rect (before offsets), in world units, or null when auto
+// falls back to the full Layout box: no Sprite, an unresolved sprite file,
+// `Sprite.mode === 'tile'` (tiled art fills its cell by definition, so a
+// per-cell bbox doesn't compose), or fully transparent art. Deliberately does
+// NOT follow Sprite.jsx's FALLBACK_FILE placeholder-art fallback -- an
+// unresolvable file means the Layout box, period.
+function autoRect(layout, spriteProps, sprite) {
+  if (!sprite || spriteProps.mode === 'tile') return null;
+  const bounds = opaqueBoundsFraction(sprite);
+  if (!bounds) return null;
+  const dest = spriteDestRect(spriteProps.mode, layout, sprite.resolution);
+  const rect = {
+    x: dest.x + bounds.x * dest.width,
+    y: dest.y + bounds.y * dest.height,
+    width: bounds.width * dest.width,
+    height: bounds.height * dest.height,
+  };
+  // `cover`'s dest overflows the Layout box and the draw clips to it, so the
+  // opaque-bounds rect can spill outside the actor -- clamp to the visible box.
+  // A no-op for `stretch`/`fit`, whose dest already sits inside the box.
+  if (spriteProps.mode === 'cover') return intersectRect(rect, layout);
+  return rect;
+}
+
+// Rect intersection in world units; zero-size (never negative) when disjoint.
+function intersectRect(rect, box) {
+  const x0 = Math.max(rect.x, box.x);
+  const y0 = Math.max(rect.y, box.y);
+  const x1 = Math.min(rect.x + rect.width, box.x + box.width);
+  const y1 = Math.min(rect.y + rect.height, box.y + box.height);
+  return { x: x0, y: y0, width: Math.max(0, x1 - x0), height: Math.max(0, y1 - y0) };
+}
+
+// `mode: 'manual'` rect (before offsets): `width`/`height`, centered in the
+// Layout box.
+function manualRect(layout, collider) {
+  const width = collider.width ?? layout.width;
+  const height = collider.height ?? layout.height;
+  return {
+    x: layout.x + (layout.width - width) / 2,
+    y: layout.y + (layout.height - height) / 2,
+    width,
+    height,
+  };
+}
+
+const fullLayoutRect = (layout) => ({ x: layout.x, y: layout.y, width: layout.width, height: layout.height });
+
+// The un-offset rect for whichever mode is active: `manualRect` for
+// `mode: 'manual'`, otherwise the auto sprite-bbox rect (or its Layout-box
+// fallback).
+function modeRect(layout, collider, spriteProps, sprites) {
+  if ((collider.mode ?? 'auto') === 'manual') return manualRect(layout, collider);
+  const sprite = spriteProps ? sprites?.[spriteProps.file] : null;
+  return autoRect(layout, spriteProps, sprite) ?? fullLayoutRect(layout);
+}
+
+// The Collider rect for an actor, from its Layout + Collider (+ Sprite, for
+// `mode: 'auto'`), or null if it lacks a Layout or Collider. `sprites` is the
+// scene's sprite map (file path -> parsed sprite); omit it (or pass a map
+// missing the actor's file) to force the Layout-box fallback, e.g. from a
+// caller that only has raw scene data and no loaded sprites.
+export function getColliderRect(actor, sprites) {
+  const layout = actor?.components?.Layout;
+  const collider = actor?.components?.Collider;
+  if (!layout || !collider) return null;
+
+  const rect = modeRect(layout, collider, actor.components.Sprite, sprites);
+  return {
+    x: rect.x + (collider.offsetX ?? 0),
+    y: rect.y + (collider.offsetY ?? 0),
+    width: rect.width,
+    height: rect.height,
+  };
+}
+
+export function intersects(a, b) {
+  return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
+}

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

@@ -1,5 +1,6 @@
 import { initialFiles, parseJsonFile } from './files';
 import { getBlueprintTemplate, mergeComponents } from './blueprint';
+import { getColliderRect, intersects, spriteIsEmpty } from './collider';
 
 const CARD_WIDTH = 500;
 const CARD_HEIGHT = 700;
@@ -127,7 +128,7 @@ export class SceneRuntime {
 
   colliderRect(actorOrId) {
     const actor = typeof actorOrId === 'string' ? this.getActor(actorOrId) : actorOrId;
-    return getColliderRect(actor);
+    return getColliderRect(actor, this.sprites);
   }
 
   overlaps(first, second) {
@@ -204,12 +205,24 @@ export class SceneRuntime {
     const viewport = options.viewport ?? DEFAULT_VIEWPORT;
     ctx.clearRect(0, 0, viewport.width, viewport.height);
     const camera = options.useCamera && this.camera ? this.camera : { x: 0, y: 0 };
+    // When a blueprint is selected in the editor, its instances stay at full
+    // opacity and everything else -- the background and every other actor --
+    // dims, so the selection stands out.
+    const dimBlueprintPath = options.dimBlueprintPath ?? null;
     if (options.showCropOutline) {
       ctx.fillStyle = this.data.background ?? '#0f2a1d';
       ctx.fillRect(0, 0, viewport.width, viewport.height);
+      if (dimBlueprintPath) {
+        ctx.fillStyle = 'rgba(0, 0, 0, 0.55)';
+        ctx.fillRect(0, 0, viewport.width, viewport.height);
+      }
     } else {
       ctx.fillStyle = this.data.background ?? '#0f2a1d';
       ctx.fillRect(0, 0, CARD_WIDTH, CARD_HEIGHT);
+      if (dimBlueprintPath) {
+        ctx.fillStyle = 'rgba(0, 0, 0, 0.55)';
+        ctx.fillRect(0, 0, CARD_WIDTH, CARD_HEIGHT);
+      }
     }
 
     ctx.save();
@@ -220,15 +233,15 @@ export class SceneRuntime {
       );
     }
     if (options.showGrid) drawDotGrid(ctx, options.gridSize, viewport, camera);
-    const editSelectedIds = options.editPlaceholders
-      ? new Set(options.editSelectedActorIds ?? [])
-      : null;
     for (const actor of this.getActors()) {
       // Per-actor transform: Layout's `rotation` (degrees) rotates every draw
       // behavior of the actor about its center.
       ctx.save();
+      if (dimBlueprintPath && actor.blueprint !== dimBlueprintPath) {
+        ctx.globalAlpha = 0.2;
+      }
       applyLayoutRotation(ctx, getLayout(actor));
-      if (options.editPlaceholders && shouldDrawEditPlaceholder(actor, editSelectedIds)) {
+      if (options.editPlaceholders && shouldDrawEditPlaceholder(actor, this.sprites)) {
         drawEditPlaceholder(ctx, actor);
       }
       this.forEachBehavior(actor, (instance) => instance.draw?.(actor, this, ctx, options));
@@ -344,7 +357,7 @@ export function duplicateActors(sceneData, actorIds) {
     const source = next.actors.find((candidate) => candidate.id === id);
     if (!source) continue;
     const copy = structuredClone(source);
-    copy.id = mintActorId(existingIds);
+    copy.id = dedupeActorId(existingIds, stripDupSuffix(source.id));
     existingIds.add(copy.id);
     const layout = copy.components.Layout;
     if (layout) {
@@ -471,6 +484,28 @@ export function mintActorId(existing) {
   return `${Date.now().toString(16)}${Math.floor(Math.random() * 0xffff).toString(16)}`;
 }
 
+// Slug-suffix dedup: return `base`, else `base-2`, `base-3`, ... -- the first
+// not already in `existing`. Callers pass an already-formed base (a blueprint
+// name's slug for fresh placements, an existing id for clones) so newly created
+// actors read as `cauldron` / `cauldron-2` instead of opaque hex. Falls back to
+// a random hex id in the pathological case (100k straight collisions) so the
+// caller always gets a unique id.
+export function dedupeActorId(existing, base) {
+  const safe = typeof base === 'string' && base.length ? base : 'actor';
+  if (!existing.has(safe)) return safe;
+  for (let attempt = 2; attempt < 100000; attempt += 1) {
+    const candidate = `${safe}-${attempt}`;
+    if (!existing.has(candidate)) return candidate;
+  }
+  return mintActorId(existing);
+}
+
+// Strip a trailing `-<n>` dedup suffix so a clone of `brick-3` bases off
+// `brick` (yielding the next free `brick-N`) instead of nesting `brick-3-2`.
+function stripDupSuffix(id) {
+  return typeof id === 'string' ? id.replace(/-\d+$/, '') : id;
+}
+
 export function screenToCard(canvas, clientX, clientY) {
   const rect = canvas.getBoundingClientRect();
   const viewport = readCanvasViewport(canvas);
@@ -529,13 +564,19 @@ function drawDotGrid(ctx, gridSize = 25, viewport = DEFAULT_VIEWPORT, camera = {
 }
 
 // Per-actor edit bounding box visibility: show it only when the actor lacks a
-// real sprite to look at (no Sprite behavior, or a Sprite with no .pxart file)
-// or when the actor is currently selected. A Sprite-backed, unselected actor
-// shows its art instead of the box.
-function shouldDrawEditPlaceholder(actor, selectedIds) {
-  if (selectedIds && selectedIds.has(actor.id)) return true;
+// real sprite to look at (no Sprite behavior, or a Sprite with no .pxart file).
+// This gray box is purely the "sprite-less actor" indicator -- selection is
+// represented separately by the DOM SelectionOverlay's solid white box, so a
+// Sprite-backed actor never shows this box, selected or not.
+function shouldDrawEditPlaceholder(actor, sprites) {
   const sprite = actor?.components?.Sprite;
-  return !sprite || !sprite.file;
+  if (!sprite || !sprite.file) return true;
+  const resolved = sprites?.[sprite.file];
+  // An unresolved file falls back to Sprite.jsx's own placeholder art, so it's
+  // not invisible -- only draw the editor placeholder when the file resolves
+  // to fully-transparent (empty) art.
+  if (!resolved) return false;
+  return spriteIsEmpty(resolved);
 }
 
 function drawEditPlaceholder(ctx, actor) {
@@ -616,21 +657,3 @@ function applyLayoutRotation(ctx, layout) {
 function getLayout(actor) {
   return actor?.components?.Layout;
 }
-
-function getColliderRect(actor) {
-  const layout = getLayout(actor);
-  const collider = actor?.components?.Collider;
-  if (!layout || !collider) return null;
-  const width = collider.width ?? layout.width;
-  const height = collider.height ?? layout.height;
-  return {
-    x: layout.x + (layout.width - width) / 2 + (collider.offsetX ?? 0),
-    y: layout.y + (layout.height - height) / 2 + (collider.offsetY ?? 0),
-    width,
-    height,
-  };
-}
-
-function intersects(a, b) {
-  return a.x < b.x + b.width && a.x + a.width > b.x && a.y < b.y + b.height && a.y + a.height > b.y;
-}

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

@@ -0,0 +1,32 @@
+// Shared sprite-to-Layout geometry. Lives in engine/ (not behaviors/) so both
+// Sprite.jsx (rendering) and the Collider rect logic (engine/collider.js) can
+// use the same math without behaviors/ <-> engine/ import cycles.
+
+// Destination rect for a draw mode: the Layout box for `stretch`/`tile`, or an
+// aspect-ratio-preserving centered rect for `fit` and `cover`:
+//   - `fit` (CSS object-fit: contain): the largest rect with the art's aspect
+//     ratio that fits INSIDE the box -- letterboxed sides just aren't drawn.
+//   - `cover` (CSS object-fit: cover): the smallest rect with the art's aspect
+//     ratio that fully COVERS the box -- the overflow is cropped by the caller
+//     clipping to the Layout box (see Sprite.draw).
+// `artSize` only needs `.width`/`.height` -- a rendered canvas or a sprite's
+// `.resolution` both work.
+export function spriteDestRect(mode, layout, artSize) {
+  if (mode !== 'fit' && mode !== 'cover') return layout;
+  const aspect = artSize.width / artSize.height;
+  let width = layout.width;
+  let height = width / aspect;
+  // `fit` shrinks until the art fits inside the box; `cover` grows until it
+  // fills the box. The comparison flips between the two.
+  const overflows = mode === 'fit' ? height > layout.height : height < layout.height;
+  if (overflows) {
+    height = layout.height;
+    width = height * aspect;
+  }
+  return {
+    x: layout.x + (layout.width - width) / 2,
+    y: layout.y + (layout.height - height) / 2,
+    width,
+    height,
+  };
+}

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

@@ -223,12 +223,12 @@ export function Icon({ name }) {
     </svg>
   );
 }
-export function Panel({ title, action, children }) {
+export function Panel({ title, action, children, overridden = false }) {
   return (
     <section className={styles.panel}>
       {title ? (
         <div className={styles.panelHeader}>
-          <span>{title}</span>
+          <span className={cx(overridden && styles.panelTitleOverridden)}>{title}</span>
           {action}
         </div>
       ) : null}
@@ -236,17 +236,39 @@ export function Panel({ title, action, children }) {
     </section>
   );
 }
-export function FieldRow({ label, children }) {
-  return (
-    <label className={styles.fieldRow}>
-      <span className={styles.fieldLabel}>{label}</span>
+// Render the "Default: X" value in an instance override's sub-line.
+function formatFieldDefault(value) {
+  if (typeof value === 'boolean') return value ? 'On' : 'Off';
+  if (value == null || value === '') return 'none';
+  return String(value);
+}
+export function FieldRow({ label, overridden, defaultValue, onReset, children }) {
+  const row = (
+    <label className={cx(styles.fieldRow, overridden && styles.fieldRowOverridden)}>
+      <span className={cx(styles.fieldLabel, overridden && styles.fieldLabelOverridden)}>{label}</span>
       {children}
     </label>
   );
+  if (!overridden) return row;
+  return (
+    <div className={styles.fieldOverride}>
+      {row}
+      <div className={styles.fieldDefault}>
+        <div className={styles.fieldDefaultInner}>
+          <span>Default: {formatFieldDefault(defaultValue)}</span>
+          {onReset ? (
+            <button type="button" className={styles.fieldResetBtn} onClick={onReset}>
+              Reset
+            </button>
+          ) : null}
+        </div>
+      </div>
+    </div>
+  );
 }
-export function TextField({ label, value, onChange }) {
+export function TextField({ label, value, onChange, overridden, defaultValue, onReset }) {
   return (
-    <FieldRow label={label}>
+    <FieldRow label={label} overridden={overridden} defaultValue={defaultValue} onReset={onReset}>
       <input
         className={styles.input}
         value={value ?? ''}
@@ -255,7 +277,7 @@ export function TextField({ label, value, onChange }) {
     </FieldRow>
   );
 }
-export function NumberField({ label, value, onChange, min, max, step = 1 }) {
+export function NumberField({ label, value, onChange, min, max, step = 1, overridden, defaultValue, onReset }) {
   const current = Number.isFinite(value) ? (value ?? 0) : 0;
   const [draft, setDraft] = useState(String(current));
   const editingRef = useRef(false);
@@ -280,7 +302,7 @@ export function NumberField({ label, value, onChange, min, max, step = 1 }) {
     onChange(next);
   }
   return (
-    <FieldRow label={label}>
+    <FieldRow label={label} overridden={overridden} defaultValue={defaultValue} onReset={onReset}>
       <div className={styles.numberField}>
         <input
           className={cx(styles.input, styles.numberInput)}
@@ -339,9 +361,9 @@ export function NumberField({ label, value, onChange, min, max, step = 1 }) {
     </FieldRow>
   );
 }
-export function CheckboxField({ label, checked, onChange }) {
+export function CheckboxField({ label, checked, onChange, overridden, defaultValue, onReset }) {
   return (
-    <FieldRow label={label}>
+    <FieldRow label={label} overridden={overridden} defaultValue={defaultValue} onReset={onReset}>
       <button
         type="button"
         className={cx(styles.toggle, checked && styles.toggleOn)}
@@ -353,12 +375,12 @@ export function CheckboxField({ label, checked, onChange }) {
     </FieldRow>
   );
 }
-export function ColorField({ label, value, onChange }) {
+export function ColorField({ label, value, onChange, overridden, defaultValue, onReset }) {
   const hex = normalizeHex(value);
   const alpha = hex.length === 9 ? hex.slice(7) : '';
   const rgb = hex.slice(0, 7);
   return (
-    <FieldRow label={label}>
+    <FieldRow label={label} overridden={overridden} defaultValue={defaultValue} onReset={onReset}>
       <input
         className={styles.colorInput}
         type="color"
@@ -437,12 +459,43 @@ function settleSheet(drag, setHeight, expandedRef) {
   const settled = setHeight(drag.startHeight - (drag.lastY - drag.startY));
   if (settled > peek + 2) expandedRef.current = settled;
 }
-export function useMobileSheet({ open = true, baseClassName }) {
-  const [height, setHeightState] = useState(() => sheetSizes().expanded);
+// Persist a sheet's resting height across reloads (an agent's CODE edit
+// triggers requestReload, which would otherwise reset every sheet to the
+// default size). Keyed per sheet via `storageKey`; sessionStorage-scoped and
+// best-effort, the same degrade-to-memory-only contract as editorHistory.
+function sheetHeightStorageKey(key) {
+  return `castle-sheet-height:${key}`;
+}
+function loadStoredSheetHeight(key) {
+  if (!key || typeof sessionStorage === 'undefined') return null;
+  try {
+    const raw = sessionStorage.getItem(sheetHeightStorageKey(key));
+    if (raw === null) return null;
+    const px = Number(raw);
+    return Number.isFinite(px) && px > 0 ? px : null;
+  } catch {
+    return null;
+  }
+}
+function saveStoredSheetHeight(key, px) {
+  if (!key || typeof sessionStorage === 'undefined') return;
+  try {
+    sessionStorage.setItem(sheetHeightStorageKey(key), String(Math.round(px)));
+  } catch {
+    // storage full/unavailable -- height still works in-memory this session
+  }
+}
+export function useMobileSheet({ open = true, baseClassName, storageKey }) {
+  const [height, setHeightState] = useState(() =>
+    clampSheetHeight(loadStoredSheetHeight(storageKey) ?? sheetSizes().expanded)
+  );
   const [dragging, setDragging] = useState(false);
   const heightRef = useRef(height);
-  const expandedRef = useRef(height); // last height above the peek, for tap-restore
+  // Last height above the peek, for tap-restore: seed from the restored height
+  // when it isn't collapsed, else the default expanded size.
+  const expandedRef = useRef(height > sheetSizes().peek + 2 ? height : sheetSizes().expanded);
   const dragRef = useRef(null);
+  const didOpenMountRef = useRef(false);
   const setHeight = (px) => {
     const next = clampSheetHeight(px);
     heightRef.current = next;
@@ -450,8 +503,14 @@ export function useMobileSheet({ open = true, baseClassName }) {
     return next;
   };
   // Restore the last expanded height whenever the sheet (re)opens, and keep the
-  // height in range across viewport resize / rotation.
+  // height in range across viewport resize / rotation. Skip the initial mount
+  // so a height restored from storage (including a collapsed peek) is kept
+  // rather than immediately overwritten by the default expanded size.
   useEffect(() => {
+    if (!didOpenMountRef.current) {
+      didOpenMountRef.current = true;
+      return;
+    }
     if (open) setHeight(expandedRef.current);
   }, [open]);
   useEffect(() => {
@@ -459,6 +518,11 @@ export function useMobileSheet({ open = true, baseClassName }) {
     window.addEventListener('resize', onResize);
     return () => window.removeEventListener('resize', onResize);
   }, []);
+  // Persist the resting height (never mid-drag, so a drag doesn't spam storage)
+  // so it survives a reload.
+  useEffect(() => {
+    if (!dragging) saveStoredSheetHeight(storageKey, height);
+  }, [dragging, height, storageKey]);
   function onPointerDown(event) {
     dragRef.current = {
       pointerId: event.pointerId,
@@ -510,16 +574,11 @@ export function useMobileSheet({ open = true, baseClassName }) {
     },
   };
 }
-export function SheetGrabHandle({ label, hint }) {
-  return (
-    <>
-      <div className={styles.sheetGrabBar} />
-      <div className={styles.sheetGrabLabelRow}>
-        <span className={styles.sheetGrabLabel}>{label}</span>
-        {hint ? <span className={styles.sheetGrabHint}>{hint}</span> : null}
-      </div>
-    </>
-  );
+// Just the drag-affordance pill for the mobile sheet. The label/hint header
+// this used to render was dropped -- it duplicated each inspector's own header
+// (blueprint name input, "<name> Actor", scene settings, etc.).
+export function SheetGrabHandle() {
+  return <div className={styles.sheetGrabBar} />;
 }
 // Cursor-anchored right-click menu reusing the scene editor's "Arrange" menu
 // chrome (the shared `selArrangeMenu`/`selArrangeItem` classes). Opens at the
@@ -605,9 +664,9 @@ export function ConfirmDialog({ title, message, confirmLabel = 'Delete', danger
     </div>
   );
 }
-export function SelectField({ label, value, onChange, options }) {
+export function SelectField({ label, value, onChange, options, overridden, defaultValue, onReset }) {
   return (
-    <FieldRow label={label}>
+    <FieldRow label={label} overridden={overridden} defaultValue={defaultValue} onReset={onReset}>
       <select
         className={styles.select}
         value={value ?? ''}