castle-web-cli 0.4.84 → 0.4.85

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

@@ -0,0 +1,122 @@
+// Single-editor mount for the panel system. The shell (dockview) opens this as
+// its own iframe via the deck route in main.jsx:
+//   ?file=<path>[&editor=<id>]  -> <SingleEditor> (one editor for one file)
+// The shell only routes the kit's RICH file types here (scene / pxart); file
+// browsing and the code/text editor are now builtin shell panels.
+
+import React, { useEffect, useRef, useState } from 'react';
+import { onBeforeRestart, onSaveReloadState, takeReloadState, writeFile } from 'castle-web-sdk';
+import { getFileKind } from '../engine/files';
+import { useLiveDeckFiles } from '../engine/liveReload';
+import { collectAssets } from '../engine/assets';
+import { MainEditor, styles } from '../engine/ui';
+import { PxArtEditor } from './PxArtEditor';
+import { SceneEditor } from './SceneEditor';
+
+// Debounced writeFile per path, flushed on reload -- the same save behavior the
+// combined editor (App.jsx) uses, factored for a single-editor mount.
+function useFileSaver() {
+  const timers = useRef({});
+  const versions = useRef({});
+  const pending = useRef({});
+  function commit(path, text, version) {
+    return writeFile(path, text)
+      .then(() => {
+        if (versions.current[path] === version && pending.current[path] === text) {
+          delete pending.current[path];
+        }
+      })
+      .catch((error) => {
+        if (versions.current[path] !== version) return;
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`Failed to save ${path}: ${message}`);
+      });
+  }
+  function schedule(path, text) {
+    const version = (versions.current[path] ?? 0) + 1;
+    versions.current[path] = version;
+    pending.current[path] = text;
+    if (timers.current[path]) window.clearTimeout(timers.current[path]);
+    // Short-ish debounce: writes now drive the live play/panel updates, so a
+    // drag should reflect soon after the user pauses.
+    timers.current[path] = window.setTimeout(() => {
+      delete timers.current[path];
+      void commit(path, text, version);
+    }, 800);
+  }
+  useEffect(
+    () =>
+      onBeforeRestart(async () => {
+        for (const timer of Object.values(timers.current)) window.clearTimeout(timer);
+        timers.current = {};
+        await Promise.all(
+          Object.entries(pending.current).map(([path, text]) =>
+            commit(path, text, versions.current[path] ?? 0)
+          )
+        );
+      }),
+    []
+  );
+  function hasPending(path) {
+    return pending.current[path] !== undefined;
+  }
+  return { schedule, hasPending };
+}
+
+export function SingleEditor({ path, editor }) {
+  // Selection survives a code-change reload: stashed via the SDK's save-state
+  // hook right before the reload, picked back up here on boot.
+  const stashKey = `single-editor:${path}`;
+  const [stash] = useState(() => takeReloadState(stashKey));
+  const { schedule, hasPending } = useFileSaver();
+  // Live deck files; our own in-flight (debounced, unsaved) edits win over the
+  // fs echo of a stale write, so a drag in progress isn't clobbered.
+  const { files, setFiles } = useLiveDeckFiles({ shouldSkipPath: hasPending });
+  const [selectedActorIds, setSelectedActorIds] = useState(stash?.selectedActorIds ?? []);
+  const [multiSelectMode, setMultiSelectMode] = useState(stash?.multiSelectMode ?? false);
+  useEffect(
+    () => onSaveReloadState(stashKey, () => ({ selectedActorIds, multiSelectMode })),
+    [stashKey, selectedActorIds, multiSelectMode]
+  );
+  const { sprites } = collectAssets(files);
+  // Optimistic cross-file edit: fold the new text into live files state NOW
+  // (so merged previews update this frame) and debounce the real write; the
+  // fs echo of our own write is skipped while pending (shouldSkipPath above).
+  // Used for this editor's own file AND for blueprint-file edits made from a
+  // scene panel's blueprint inspector.
+  function onChangeFile(targetPath, nextText) {
+    setFiles((current) => ({ ...current, [targetPath]: nextText }));
+    schedule(targetPath, nextText);
+  }
+  function onChange(nextText) {
+    onChangeFile(path, nextText);
+  }
+  const kind = editor || getFileKind(path);
+  const text = files[path] ?? '';
+  let body = null;
+  if (kind === 'scene') {
+    body = (
+      <SceneEditor
+        path={path}
+        text={text}
+        files={files}
+        sprites={sprites}
+        onChange={onChange}
+        onChangeFile={onChangeFile}
+        selectedActorIds={selectedActorIds}
+        onSelectActorIds={setSelectedActorIds}
+        multiSelectMode={multiSelectMode}
+        onSetMultiSelectMode={setMultiSelectMode}
+      />
+    );
+  } else if (kind === 'pxart') {
+    body = <PxArtEditor path={path} text={text} onChange={onChange} />;
+  }
+  // No `else`: code/text files are handled by the builtin shell code editor, so
+  // the shell never routes them here. `body` stays null for any other kind.
+  return (
+    <div className={styles.panelBare}>
+      <MainEditor>{body}</MainEditor>
+    </div>
+  );
+}

package/kits/physics-2d/editors/behaviorRegistry.js

@@ -0,0 +1,30 @@
+// Discover every behavior class from `behaviors/*.jsx` and the physics module's
+// `physics/behaviors/*.jsx`. Vite HMR is off, so a newly-added behavior file is
+// picked up on the next reload/restart. The physics glob is what lets the
+// self-contained physics module ship its behaviors without polluting the core
+// `behaviors/` folder — a kit adopts physics by copying `physics/` in.
+const modules = {
+  ...import.meta.glob('../behaviors/*.jsx', { eager: true }),
+  ...import.meta.glob('../physics/behaviors/*.jsx', { eager: true }),
+};
+function isBehaviorClass(value) {
+  return typeof value === 'function' && typeof value.behaviorName === 'string';
+}
+function collectBehaviors() {
+  const found = new Map();
+  for (const mod of Object.values(modules)) {
+    for (const exported of Object.values(mod)) {
+      if (isBehaviorClass(exported)) found.set(exported.behaviorName, exported);
+    }
+  }
+  // Layout first (every actor needs it), then alphabetical.
+  return [...found.values()].sort((a, b) => {
+    if (a.behaviorName === 'Layout') return -1;
+    if (b.behaviorName === 'Layout') return 1;
+    return a.behaviorName.localeCompare(b.behaviorName);
+  });
+}
+export const behaviorClasses = collectBehaviors();
+export function findBehaviorClass(behaviorName) {
+  return behaviorClasses.find((candidate) => candidate.behaviorName === behaviorName);
+}

package/kits/physics-2d/editors/editorHistory.js

@@ -0,0 +1,157 @@
+import { useEffect, useRef, useState } from 'react';
+const HISTORY_LIMIT = 50;
+// Time window (ms) within which consecutive commits sharing the same
+// coalesceKey collapse into a single undo entry (e.g. dragging a color
+// picker or repeatedly clicking a number stepper). Sliding: each coalesced
+// commit refreshes the window.
+const COALESCE_WINDOW_MS = 800;
+
+function historyStorageKey(path) {
+  return `castle-edit-history:${path}`;
+}
+// Best-effort sessionStorage read/write so undo/redo survives the editor
+// iframe reloading (e.g. after `npm run restart`). Quota errors or disabled
+// storage (private browsing, etc.) degrade silently to in-memory-only history.
+function loadStoredHistory(path) {
+  if (!path) return null;
+  try {
+    const raw = sessionStorage.getItem(historyStorageKey(path));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.undo) || !Array.isArray(parsed.redo)) return null;
+    return {
+      undo: parsed.undo.slice(-HISTORY_LIMIT),
+      redo: parsed.redo.slice(0, HISTORY_LIMIT),
+    };
+  } catch {
+    return null;
+  }
+}
+function saveStoredHistory(path, history) {
+  if (!path) return;
+  try {
+    sessionStorage.setItem(historyStorageKey(path), JSON.stringify(history));
+  } catch {
+    // Storage full or unavailable -- history still works in-memory this session.
+  }
+}
+// Drop entries at the end of `stack` equal to `text`: snapshots recorded at
+// gesture start (recordSnapshot) that the gesture never actually changed.
+function trimTrailingNoOps(stack, text) {
+  let end = stack.length;
+  while (end > 0 && stack[end - 1] === text) end--;
+  return end === stack.length ? stack : stack.slice(0, end);
+}
+// Same idea for the redo stack, which is read from the front.
+function trimLeadingNoOps(stack, text) {
+  let start = 0;
+  while (start < stack.length && stack[start] === text) start++;
+  return start === 0 ? stack : stack.slice(start);
+}
+// Text-undo/redo for file-backed editors. `text` is the canonical current
+// value; `onChange` writes the new value back. The hook owns the undo/redo
+// stacks; it never mutates `text` directly. `path`, when given, persists the
+// stacks to sessionStorage keyed by file path.
+export function useEditHistory(text, onChange, path) {
+  const [history, setHistory] = useState(() => loadStoredHistory(path) ?? { undo: [], redo: [] });
+  // Mirror the latest stacks so undo/redo can read them synchronously in the
+  // event handler. onChange writes the PARENT's state, so it must never run
+  // inside a setHistory updater -- updaters execute in React's render phase,
+  // which would update the parent while this editor renders (setState-in-render).
+  const historyRef = useRef(history);
+  historyRef.current = history;
+  useEffect(() => {
+    saveStoredHistory(path, history);
+  }, [path, history]);
+  // { key, time } of the most recent coalescable commit. Undo/redo/
+  // recordSnapshot null this out so a later commit never coalesces across them.
+  const coalesceRef = useRef({ key: null, time: 0 });
+  function commit(nextText, { coalesceKey } = {}) {
+    if (nextText === text) return;
+    const now = Date.now();
+    const last = coalesceRef.current;
+    const coalescing =
+      coalesceKey != null && last.key === coalesceKey && now - last.time <= COALESCE_WINDOW_MS;
+    coalesceRef.current = { key: coalesceKey ?? null, time: now };
+    if (coalescing) {
+      setHistory((current) => ({ ...current, redo: [] }));
+    } else {
+      setHistory((current) => ({
+        undo: [...current.undo, text].slice(-HISTORY_LIMIT),
+        redo: [],
+      }));
+    }
+    onChange(nextText);
+  }
+  function recordSnapshot() {
+    coalesceRef.current = { key: null, time: 0 };
+    setHistory((current) => ({
+      undo: [...current.undo, text].slice(-HISTORY_LIMIT),
+      redo: [],
+    }));
+  }
+  function undo() {
+    coalesceRef.current = { key: null, time: 0 };
+    const current = historyRef.current;
+    const stack = trimTrailingNoOps(current.undo, text);
+    const previous = stack.at(-1);
+    if (previous === undefined) return;
+    setHistory({
+      undo: stack.slice(0, -1),
+      redo: [text, ...current.redo].slice(0, HISTORY_LIMIT),
+    });
+    onChange(previous);
+  }
+  function redo() {
+    coalesceRef.current = { key: null, time: 0 };
+    const current = historyRef.current;
+    const stack = trimLeadingNoOps(current.redo, text);
+    const next = stack[0];
+    if (next === undefined) return;
+    setHistory({
+      undo: [...current.undo, text].slice(-HISTORY_LIMIT),
+      redo: stack.slice(1),
+    });
+    onChange(next);
+  }
+  return {
+    commit,
+    undo,
+    redo,
+    canUndo: trimTrailingNoOps(history.undo, text).length > 0,
+    canRedo: trimLeadingNoOps(history.redo, text).length > 0,
+    recordSnapshot,
+  };
+}
+
+export function useUndoRedoShortcuts(history, enabled = true) {
+  const historyRef = useRef(history);
+  historyRef.current = history;
+  const enabledRef = useRef(enabled);
+  enabledRef.current = enabled;
+  useEffect(() => {
+    function onKeyDown(event) {
+      if (!enabledRef.current) return;
+      if (event.defaultPrevented || isEditableTarget(event.target)) return;
+      if (!(event.metaKey || event.ctrlKey) || event.key.toLowerCase() !== 'z') return;
+      event.preventDefault();
+      if (event.shiftKey) historyRef.current.redo();
+      else historyRef.current.undo();
+    }
+    // Capture phase, not bubble: this must win Cmd+Z/Cmd+Shift+Z before it can
+    // fall through to the browser's own undo, and before any other listener
+    // further down the tree (e.g. a widget that stops propagation on its own
+    // keydown) can swallow it first. This only matters once this iframe
+    // actually HAS keyboard focus (see EditorBody's pointer-down focus claim)
+    // -- capture order can't help if the event never reaches this window.
+    window.addEventListener('keydown', onKeyDown, true);
+    return () => window.removeEventListener('keydown', onKeyDown, true);
+  }, []);
+}
+
+function isEditableTarget(target) {
+  return (
+    target instanceof Element &&
+    !!target.closest('input, textarea, select, [contenteditable="true"]')
+  );
+}

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

@@ -0,0 +1,13 @@
+import { styles, useMobileSheet } from '../engine/ui';
+
+// Inspector panel as a drag-resizable bottom sheet on compact viewports, docked
+// on desktop. Used by the pixel-art (PxArt) editor. `inspectorOpen` drives
+// 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,
+    storageKey: 'pxart-inspector',
+  });
+}

package/kits/physics-2d/editors/pixelCanvas.js

@@ -0,0 +1,11 @@
+// Map a pointer event over a pixel-art canvas element to integer cell
+// coordinates within a `width x height` raster, or null when the pointer is
+// outside the raster. Used by the PxArt editor, whose artboard stretches a
+// native-resolution canvas to fit via CSS.
+export function eventToCell(event, width, height) {
+  const rect = event.currentTarget.getBoundingClientRect();
+  const x = Math.floor(((event.clientX - rect.left) / rect.width) * width);
+  const y = Math.floor(((event.clientY - rect.top) / rect.height) * height);
+  if (x < 0 || y < 0 || x >= width || y >= height) return null;
+  return { x, y };
+}

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

@@ -0,0 +1,74 @@
+import React from 'react';
+import { EditorHeader, IconButton, styles } from '../engine/ui';
+import { useEditHistory, useUndoRedoShortcuts } from './editorHistory';
+
+// Shared shell state for the pixel editors: text undo/redo history and undo/redo
+// keyboard shortcuts. Returns the `history` controller and `headerShell` for the
+// header (undo/redo only — paint controls live in the artboard layout).
+export function usePixelEditorShell(text, onChange, path) {
+  const history = useEditHistory(text, onChange, path);
+  useUndoRedoShortcuts(history);
+  const headerShell = { history };
+  return { history, headerShell };
+}
+
+function PixelEditorTools({ history }) {
+  return (
+    <>
+      <IconButton icon="undo" label="Undo" onClick={history.undo} disabled={!history.canUndo} />
+      <IconButton icon="redo" label="Redo" onClick={history.redo} disabled={!history.canRedo} />
+    </>
+  );
+}
+
+// The full editor header shared by the pixel editors: title/subtitle plus undo/redo.
+export function PixelEditorHeader({ title, subtitle, shell, chrome }) {
+  return (
+    <EditorHeader
+      title={title}
+      subtitle={subtitle}
+      right={<PixelEditorTools history={shell.history} />}
+      onToggleFiles={chrome.onToggleFiles}
+      filesOpen={chrome.filesOpen}
+      headerHost={chrome.headerHost}
+    />
+  );
+}
+
+// The native-resolution canvas inside its artboard frame. `style` sets the fitted
+// display size, and is applied ONLY to the frame: all three canvases inside are
+// absolutely positioned with `width/height: 100%`, so they fill the frame's
+// content box identically. (Passing `style` to a canvas too would size it to the
+// frame's BORDER box — the frame is border-box with a 1px border — leaving the
+// canvas ~2px larger than its siblings and anchored top-left, which shifts the
+// smooth-preview vs. pixel render out of alignment.) `handlers` are the pointer
+// callbacks the editor wires for tools. `overlayRef` is a sibling canvas at
+// display resolution used for crisp overlays (marching-ants selection) that would
+// otherwise render sub-pixel on the upscaled native canvas. `smoothRef` is a
+// sibling canvas BEHIND the main one, holding the corner-rounded render for
+// "smooth"-mode sprites (empty/unused in "pixel" mode) so the interactive canvas
+// above it can stay at native resolution — pointer math and tool-preview overlays
+// are unaffected by the render mode.
+export function PixelArtboard({ canvasRef, smoothRef, overlayRef, style, handlers }) {
+  return (
+    <div className={styles.drawingArtboard}>
+      <div className={styles.drawingArtboardFrame} style={style}>
+        <canvas ref={smoothRef} className={styles.drawingSmooth} aria-hidden="true" />
+        <canvas
+          ref={canvasRef}
+          className={styles.drawingCanvas}
+          // Focusable so a pointer-down can pull keyboard focus into this editor
+          // iframe (see startTool). Without it, Safari often leaves keyboard focus
+          // on the top document and Cmd+Z falls through to the browser's own undo.
+          tabIndex={-1}
+          onPointerDown={handlers.onPointerDown}
+          onPointerMove={handlers.onPointerMove}
+          onPointerUp={handlers.onPointerUp}
+          onPointerCancel={handlers.onPointerCancel}
+          onPointerLeave={handlers.onPointerLeave}
+        />
+        <canvas ref={overlayRef} className={styles.drawingOverlay} aria-hidden="true" />
+      </div>
+    </div>
+  );
+}

package/kits/physics-2d/editors/pixelGeometry.js

@@ -0,0 +1,140 @@
+// Pure pixel-raster geometry for the PxArt tools. These helpers know nothing
+// about pixel storage (flat array vs cell matrix) — they only emit integer
+// coordinates, so the editor can apply its own write.
+
+// Visit the integer offsets covering one brush "dab" of `size`, relative to the
+// dab center. A diameter < 4 paints a solid square; 4+ uses a circular mask so
+// larger brushes round off. `visit(dx, dy)` receives signed offsets.
+export function forEachDab(size, visit) {
+  const diameter = Math.max(1, Math.round(size));
+  const offset = Math.floor(diameter / 2);
+  const useCircle = diameter >= 4;
+  const radius = diameter * 0.5;
+  const radiusSquared = radius * radius;
+  const centerOffset = (diameter - 1) * 0.5;
+  for (let ly = 0; ly < diameter; ly++) {
+    for (let lx = 0; lx < diameter; lx++) {
+      if (useCircle) {
+        const dx = lx - centerOffset;
+        const dy = ly - centerOffset;
+        if (dx * dx + dy * dy > radiusSquared) continue;
+      }
+      visit(lx - offset, ly - offset);
+    }
+  }
+}
+
+// Visit the deduped integer points along the segment from `from` to `to`,
+// supersampled so a fast drag paints a continuous run. `visit(x, y)` receives
+// rounded cell coordinates.
+export function forEachLinePoint(from, to, visit) {
+  const dx = to.x - from.x;
+  const dy = to.y - from.y;
+  const distance = Math.hypot(dx, dy);
+  const steps = Math.max(1, Math.ceil(distance * 2));
+  let lastKey = '';
+  for (let step = 0; step <= steps; step++) {
+    const t = step / steps;
+    const x = Math.round(from.x + dx * t);
+    const y = Math.round(from.y + dy * t);
+    const key = `${x},${y}`;
+    if (key === lastKey) continue;
+    lastKey = key;
+    visit(x, y);
+  }
+}
+
+// The shape tools (square/circle/triangle) are bounded by the axis-aligned box
+// the drag sweeps out, so they share this normalized corner unpacking.
+function shapeBounds(from, to) {
+  return {
+    x0: Math.min(from.x, to.x),
+    x1: Math.max(from.x, to.x),
+    y0: Math.min(from.y, to.y),
+    y1: Math.max(from.y, to.y),
+  };
+}
+
+// Visit the cells of the rectangle bounded by `from`/`to`. `filled` paints the
+// solid box; otherwise only the 1px border. `visit(x, y)` receives cell coords.
+export function forEachRectCells(from, to, filled, visit) {
+  const { x0, x1, y0, y1 } = shapeBounds(from, to);
+  for (let y = y0; y <= y1; y++) {
+    for (let x = x0; x <= x1; x++) {
+      if (filled || x === x0 || x === x1 || y === y0 || y === y1) visit(x, y);
+    }
+  }
+}
+
+// Visit the cells of the ellipse inscribed in the `from`/`to` box. A cell is
+// "inside" when its center falls within the normalized ellipse; the half-cell
+// radius padding lets tiny drags still fill their box. The outline keeps only
+// inside cells with at least one 4-neighbor outside, so it reads as a closed
+// ring with no gaps.
+export function forEachEllipseCells(from, to, filled, visit) {
+  const { x0, x1, y0, y1 } = shapeBounds(from, to);
+  const cx = (x0 + x1) / 2;
+  const cy = (y0 + y1) / 2;
+  const rx = (x1 - x0) / 2 + 0.5;
+  const ry = (y1 - y0) / 2 + 0.5;
+  const inside = (x, y) => {
+    const nx = (x - cx) / rx;
+    const ny = (y - cy) / ry;
+    return nx * nx + ny * ny <= 1;
+  };
+  for (let y = y0; y <= y1; y++) {
+    for (let x = x0; x <= x1; x++) {
+      if (!inside(x, y)) continue;
+      if (filled) {
+        visit(x, y);
+      } else if (
+        !inside(x - 1, y) ||
+        !inside(x + 1, y) ||
+        !inside(x, y - 1) ||
+        !inside(x, y + 1)
+      ) {
+        visit(x, y);
+      }
+    }
+  }
+}
+
+// Cross-product sign of point c relative to the directed edge a->b. Used both
+// to build the triangle outline and to test point containment for the fill.
+function edgeCross(a, b, cx, cy) {
+  return (b.x - a.x) * (cy - a.y) - (b.y - a.y) * (cx - a.x);
+}
+
+// Visit the cells of an isosceles triangle inscribed in the `from`/`to` box:
+// apex centered on the top edge, base spanning the bottom edge. `filled` uses a
+// barycentric point-in-triangle test over the box; the outline walks the three
+// edges. A shared `seen` set dedups cells shared by adjacent edges/scanlines.
+export function forEachTriangleCells(from, to, filled, visit) {
+  const { x0, x1, y0, y1 } = shapeBounds(from, to);
+  const apex = { x: Math.round((x0 + x1) / 2), y: y0 };
+  const left = { x: x0, y: y1 };
+  const right = { x: x1, y: y1 };
+  const seen = new Set();
+  const emit = (x, y) => {
+    const key = `${x},${y}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    visit(x, y);
+  };
+  if (filled) {
+    for (let y = y0; y <= y1; y++) {
+      for (let x = x0; x <= x1; x++) {
+        const w0 = edgeCross(left, right, x, y);
+        const w1 = edgeCross(right, apex, x, y);
+        const w2 = edgeCross(apex, left, x, y);
+        const hasNeg = w0 < 0 || w1 < 0 || w2 < 0;
+        const hasPos = w0 > 0 || w1 > 0 || w2 > 0;
+        if (!(hasNeg && hasPos)) emit(x, y);
+      }
+    }
+    return;
+  }
+  forEachLinePoint(apex, left, emit);
+  forEachLinePoint(left, right, emit);
+  forEachLinePoint(right, apex, emit);
+}