castle-web-cli 0.4.72 → 0.4.74

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

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useLayoutEffect, useState } from 'react';
+
+const MAX_ART = 460;
+const STACK_GAP = 10;
+
+// Matches @container editor (max-width) in ui.module.css.
+export const PXART_COMPACT_MAX_WIDTH = 620;
+
+// True when .editorBody is at or below the compact-layout container threshold.
+export function useEditorCompactLayout(bodyRef, maxWidth = PXART_COMPACT_MAX_WIDTH) {
+  const [compact, setCompact] = useState(false);
+
+  useEffect(() => {
+    const body = bodyRef.current;
+    if (!body || typeof ResizeObserver === 'undefined') return undefined;
+
+    const update = () => setCompact(body.clientWidth <= maxWidth);
+    update();
+    const observer = new ResizeObserver(update);
+    observer.observe(body);
+    return () => observer.disconnect();
+  }, [bodyRef, maxWidth]);
+
+  return compact;
+}
+
+// Fit the artboard canvas inside its wrap region, accounting for padding, the
+// canvas-size bar above the art, and the sprite's aspect ratio. Re-runs when the
+// wrap resizes (timeline drag, window resize, compact layout flip).
+export function useArtboardFit({ wrapRef, sizeBarRef, resolution }) {
+  const { width, height } = resolution;
+  const isWide = width >= height;
+  const [displaySize, setDisplaySize] = useState(null);
+
+  const fit = useCallback(() => {
+    const wrap = wrapRef.current;
+    if (!wrap) return;
+    const wrapStyle = getComputedStyle(wrap);
+    const padX = parseFloat(wrapStyle.paddingLeft) + parseFloat(wrapStyle.paddingRight);
+    const padY = parseFloat(wrapStyle.paddingTop) + parseFloat(wrapStyle.paddingBottom);
+    const barHeight = sizeBarRef.current?.offsetHeight ?? 0;
+    const maxW = wrap.clientWidth - padX;
+    const maxH = wrap.clientHeight - padY - barHeight - (barHeight ? STACK_GAP : 0);
+    if (maxW <= 0 || maxH <= 0) {
+      setDisplaySize(null);
+      return;
+    }
+
+    let displayW;
+    let displayH;
+    if (width === height) {
+      const size = Math.floor(Math.min(maxW, maxH, MAX_ART));
+      displayW = size;
+      displayH = size;
+    } else if (isWide) {
+      displayW = Math.floor(Math.min(maxW, MAX_ART));
+      displayH = Math.floor((displayW * height) / width);
+      if (displayH > maxH) {
+        displayH = Math.floor(maxH);
+        displayW = Math.floor((displayH * width) / height);
+      }
+    } else {
+      displayH = Math.floor(Math.min(maxH, MAX_ART));
+      displayW = Math.floor((displayH * width) / height);
+      if (displayW > maxW) {
+        displayW = Math.floor(maxW);
+        displayH = Math.floor((displayW * height) / width);
+      }
+    }
+
+    if (!Number.isFinite(displayW) || !Number.isFinite(displayH) || displayW <= 0 || displayH <= 0) {
+      setDisplaySize(null);
+      return;
+    }
+    setDisplaySize({ width: displayW, height: displayH });
+  }, [width, height, isWide, wrapRef, sizeBarRef]);
+
+  useLayoutEffect(() => {
+    fit();
+  }, [fit]);
+
+  useEffect(() => {
+    const wrap = wrapRef.current;
+    if (!wrap) return undefined;
+    window.addEventListener('resize', fit);
+    if (typeof ResizeObserver === 'undefined') {
+      return () => window.removeEventListener('resize', fit);
+    }
+    const observer = new ResizeObserver(fit);
+    observer.observe(wrap);
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('resize', fit);
+    };
+  }, [fit, wrapRef]);
+
+  const canvasStyle = displaySize
+    ? { width: `${displaySize.width}px`, height: `${displaySize.height}px` }
+    : undefined;
+
+  return { canvasStyle, refit: fit };
+}

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

@@ -1,23 +1,30 @@
-import React, { useCallback, useEffect, useRef } from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { configureSceneCanvas, makeScene } from './scene';
 import { SceneUI } from './SceneUI';
 import { TouchControls } from './TouchControls';
+import { cx, Icon, styles } from './ui';
+import { usePlayLogs } from './playConsole';
 // Engine-level scene player: mount a `SceneRuntime` against a canvas, wire
 // keyboard / pointer input, run the update+draw loop, and render the
 // behavior-driven UI overlay. No game logic lives here -- behaviors and
 // scenes are the place for that.
-export function ScenePlayer({ sceneData, drawings, behaviorClasses }) {
+export function ScenePlayer({ sceneData, sprites, behaviorClasses, onFirstFrame }) {
   const canvasRef = useRef(null);
   const runtimeRef = useRef(null);
+  // Bumping this re-runs the mount effect below, which tears down the running
+  // loop/runtime and rebuilds a fresh scene from the same data -- a clean restart.
+  const [runToken, setRunToken] = useState(0);
   const getKeys = useCallback(() => runtimeRef.current?.keys ?? null, []);
   const getRuntime = useCallback(() => runtimeRef.current, []);
+  const restart = useCallback(() => setRunToken((token) => token + 1), []);
   useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return undefined;
     const ctx = canvas.getContext('2d');
     if (!ctx) return undefined;
     configureSceneCanvas(canvas, ctx);
-    const runtime = makeScene(sceneData, behaviorClasses, drawings).clone();
+    const runtime = makeScene(sceneData, behaviorClasses, sprites).clone();
     runtimeRef.current = runtime;
     // Store BOTH the physical code ('KeyX', 'ArrowLeft', 'Space') and the
     // logical key ('x', 'ArrowLeft', ' ') so behaviors can match either. Codes
@@ -56,7 +63,9 @@ export function ScenePlayer({ sceneData, drawings, behaviorClasses }) {
     canvas.addEventListener('pointerup', onPointerUp);
     canvas.addEventListener('pointercancel', onPointerUp);
     canvas.focus();
-    const stopLoop = startPlayerLoop(canvas, ctx, runtime);
+    // Only signal first-frame readiness on the initial run; a restart shouldn't
+    // re-fire the host launcher reveal.
+    const stopLoop = startPlayerLoop(canvas, ctx, runtime, runToken === 0 ? onFirstFrame : undefined);
     return () => {
       stopLoop();
       window.removeEventListener('keydown', onKeyDown);
@@ -68,28 +77,175 @@ export function ScenePlayer({ sceneData, drawings, behaviorClasses }) {
       runtimeRef.current = null;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [runToken]);
+  return (
+    <>
+      <div style={{ position: 'fixed', inset: 0, background: '#000' }}>
+        <canvas
+          ref={canvasRef}
+          tabIndex={0}
+          style={{ width: '100%', height: '100%', display: 'block', outline: 'none' }}
+        />
+        <SceneUI getRuntime={getRuntime} />
+        <TouchControls getKeys={getKeys} />
+      </div>
+      {/* Portal to <body> so the console drawer escapes the SDK's card-sized,
+          transformed `#root > *` wrapper and pins to the panel, outside the
+          play preview. */}
+      {createPortal(<PlayConsole onRestart={restart} />, document.body)}
+    </>
+  );
+}
+function PlayConsole({ onRestart }) {
+  const { logs, clearLogs } = usePlayLogs();
+  const [open, setOpen] = useState(false);
+  const rootRef = useRef(null);
+  const bodyRef = useRef(null);
+  // Reserve the drawer's footprint by shrinking + lifting the SDK deck card so it
+  // sits fully above the drawer (visible + interactive) instead of behind it.
+  // Driven by the live drawer height; recomputed on toggle (height change via the
+  // ResizeObserver) and on window/card resize.
+  useEffect(() => {
+    const el = rootRef.current;
+    if (!el) return undefined;
+    const docEl = document.documentElement;
+    docEl.dataset.castleLogs = '';
+    const TOP_MARGIN = 16;
+    const MIN_CARD_SCALE = 0.2;
+    const apply = () => {
+      const drawerHeight = el.offsetHeight;
+      const cs = getComputedStyle(docEl);
+      const fullW = parseFloat(cs.getPropertyValue('--castle-card-w'));
+      const fullH = parseFloat(cs.getPropertyValue('--castle-card-h'));
+      docEl.style.setProperty('--castle-logs-shift', `${drawerHeight / 2}px`);
+      // Only resize the card when we know its natural size; otherwise leave it to
+      // the SDK fallback (the rule's var() defaults handle this).
+      if (fullW > 0 && fullH > 0) {
+        const available = window.innerHeight - drawerHeight - TOP_MARGIN;
+        // Floor the scale so a very short panel (drawer taller than the area)
+        // can't drive the card to 0/negative and make the deck disappear.
+        const scale = Math.min(1, Math.max(MIN_CARD_SCALE, available / fullH));
+        docEl.style.setProperty('--castle-logs-card-w', `${fullW * scale}px`);
+        docEl.style.setProperty('--castle-logs-card-h', `${fullH * scale}px`);
+      } else {
+        docEl.style.removeProperty('--castle-logs-card-w');
+        docEl.style.removeProperty('--castle-logs-card-h');
+      }
+    };
+    apply();
+    const observer = new ResizeObserver(apply);
+    observer.observe(el);
+    window.addEventListener('resize', apply);
+    return () => {
+      observer.disconnect();
+      window.removeEventListener('resize', apply);
+      delete docEl.dataset.castleLogs;
+      docEl.style.removeProperty('--castle-logs-card-w');
+      docEl.style.removeProperty('--castle-logs-card-h');
+      docEl.style.removeProperty('--castle-logs-shift');
+    };
   }, []);
+  // Keep the newest line in view while expanded.
+  useEffect(() => {
+    if (open && bodyRef.current) bodyRef.current.scrollTop = bodyRef.current.scrollHeight;
+  }, [logs, open]);
+  const copy = useCallback(() => {
+    const text = logs.map((line) => line.text).join('\n');
+    navigator.clipboard?.writeText(text).catch(() => {});
+  }, [logs]);
+  const hasLogs = logs.length > 0;
   return (
-    <div style={{ position: 'fixed', inset: 0, background: '#000' }}>
-      <canvas
-        ref={canvasRef}
-        tabIndex={0}
-        style={{ width: '100%', height: '100%', display: 'block', outline: 'none' }}
-      />
-      <SceneUI getRuntime={getRuntime} />
-      <TouchControls getKeys={getKeys} />
+    <div ref={rootRef} className={styles.playConsole}>
+      {/* The whole header row toggles; the action buttons stopPropagation so
+          they don't also collapse/expand. */}
+      <div
+        className={styles.playConsoleHeader}
+        role="button"
+        tabIndex={-1}
+        aria-expanded={open}
+        aria-label={open ? 'Collapse logs' : 'Expand logs'}
+        onClick={() => setOpen((value) => !value)}>
+        <span className={styles.playConsoleToggle}>
+          <span className={styles.playConsoleCaret}>
+            <Icon name={open ? 'chevron-down' : 'chevron-right'} />
+          </span>
+          <span className={styles.playConsoleTitle}>Logs</span>
+        </span>
+        <div
+          className={styles.playConsoleActions}
+          onClick={(event) => event.stopPropagation()}>
+          {open ? (
+            <>
+              <button
+                type="button"
+                tabIndex={-1}
+                className={styles.playConsoleBtn}
+                aria-label="Copy logs"
+                title="Copy logs"
+                disabled={!hasLogs}
+                onClick={copy}>
+                <Icon name="clone" />
+              </button>
+              <button
+                type="button"
+                tabIndex={-1}
+                className={styles.playConsoleBtn}
+                aria-label="Clear logs"
+                title="Clear logs"
+                disabled={!hasLogs}
+                onClick={clearLogs}>
+                <Icon name="trash" />
+              </button>
+            </>
+          ) : null}
+          <button
+            type="button"
+            tabIndex={-1}
+            className={styles.playConsoleBtn}
+            aria-label="Restart"
+            title="Restart"
+            onClick={onRestart}>
+            <Icon name="rotate" />
+          </button>
+        </div>
+      </div>
+      {open ? (
+        <div ref={bodyRef} className={styles.playConsoleBody}>
+          {hasLogs ? (
+            logs.map((line) => (
+              <div
+                key={line.id}
+                className={cx(
+                  styles.playConsoleLine,
+                  line.level === 'warn' && styles.playConsoleLineWarn,
+                  line.level === 'error' && styles.playConsoleLineError
+                )}>
+                {line.text}
+              </div>
+            ))
+          ) : (
+            <div className={styles.playConsoleEmpty}>no output</div>
+          )}
+        </div>
+      ) : null}
     </div>
   );
 }
-function startPlayerLoop(canvas, ctx, runtime) {
+function startPlayerLoop(canvas, ctx, runtime, onFirstFrame) {
   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 });
+    if (!firstFrameSignaled) {
+      firstFrameSignaled = true;
+      // Wait one frame so the draw composites before reveal, avoiding a blank flash.
+      requestAnimationFrame(() => onFirstFrame?.());
+    }
     raf = requestAnimationFrame(tick);
   };
   raf = requestAnimationFrame(tick);

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

@@ -1,5 +1,6 @@
 import React, { useEffect, useRef, useState } from 'react';
 import styles from './ui.module.css';
+import { useElementSize } from './ui';
 import { cardSize } from './scene';
 // Game-time UI overlay.
 //
@@ -11,18 +12,9 @@ import { cardSize } from './scene';
 // hidden`, so deck UI can never render outside the card.
 export function SceneUI({ getRuntime }) {
   const rootRef = useRef(null);
-  const [box, setBox] = useState({ width: 0, height: 0 });
-  const [, forceRender] = useState(0);
   // Track the canvas-sized overlay box so the card-unit layer scales onto it.
-  useEffect(() => {
-    const root = rootRef.current;
-    if (!root) return undefined;
-    const measure = () => setBox({ width: root.clientWidth, height: root.clientHeight });
-    const observer = new ResizeObserver(measure);
-    observer.observe(root);
-    measure();
-    return () => observer.disconnect();
-  }, []);
+  const box = useElementSize(rootRef);
+  const [, forceRender] = useState(0);
   // Re-render every frame so behavior UI reflects live runtime state.
   useEffect(() => {
     let raf = 0;

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

@@ -0,0 +1,15 @@
+import { parseFull } from './pxart';
+
+// Build the runtime asset map from a path->text file map: parsed `.pxart`
+// Sprites keyed by file path (nulls skipped). Shared by the editor App and the
+// play-only entry point so both hand the SceneRuntime the same map.
+export function collectAssets(files) {
+  const sprites = {};
+  for (const [path, text] of Object.entries(files)) {
+    if (path.endsWith('.pxart')) {
+      const sprite = parseFull(text);
+      if (sprite) sprites[path] = sprite;
+    }
+  }
+  return { sprites };
+}

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

@@ -1,7 +1,7 @@
 // Seed the file map by scanning the deck dir. Vite module-cache is invalidated
 // on restart, so a newly-created file just shows up on the next reload.
 const rawModules = import.meta.glob(
-  ['../scenes/*.scene', '../drawings/*.drawing', '../behaviors/*.jsx'],
+  ['../scenes/*.scene', '../drawings/*.pxart', '../behaviors/*.jsx'],
   { query: '?raw', import: 'default', eager: true }
 );
 export const initialFiles = Object.fromEntries(
@@ -11,7 +11,7 @@ export const initialFiles = Object.fromEntries(
 );
 export function getFileKind(path) {
   if (path.endsWith('.scene')) return 'scene';
-  if (path.endsWith('.drawing')) return 'drawing';
+  if (path.endsWith('.pxart')) return 'pxart';
   if (path.endsWith('.js') || path.endsWith('.jsx')) return 'code';
   return 'text';
 }
@@ -29,6 +29,61 @@ export function formatJson(value) {
 export function basename(path) {
   return path.split('/').pop() ?? path;
 }
+// Parent directory of a path ('' for a root-level path).
+export function dirname(path) {
+  const index = path.lastIndexOf('/');
+  return index === -1 ? '' : path.slice(0, index);
+}
+// Join a directory and a name, tolerating a '' (root) directory.
+export function joinPath(dir, name) {
+  return dir ? `${dir}/${name}` : name;
+}
+// Split a filename into stem + extension (the extension includes the leading
+// dot). Leading-dot names (e.g. '.gitignore') count as all-stem.
+export function splitFileName(name) {
+  const dot = name.lastIndexOf('.');
+  if (dot <= 0) return { stem: name, ext: '' };
+  return { stem: name.slice(0, dot), ext: name.slice(dot) };
+}
+// A filename in `dir` that doesn't collide with any existing path. If
+// `desiredName` is free it's returned as-is; otherwise '-2', '-3', ... is
+// inserted before the extension until a free name is found.
+export function uniqueFileName(existingPaths, dir, desiredName) {
+  const taken = new Set(existingPaths);
+  if (!taken.has(joinPath(dir, desiredName))) return desiredName;
+  const { stem, ext } = splitFileName(desiredName);
+  for (let n = 2; ; n++) {
+    const candidate = `${stem}-${n}${ext}`;
+    if (!taken.has(joinPath(dir, candidate))) return candidate;
+  }
+}
+// Top-level child segment names (files and virtual folders) directly inside
+// `parentDir`. Used to keep new sibling folder names collision-free.
+export function childNamesIn(existingPaths, parentDir) {
+  const prefix = parentDir ? `${parentDir}/` : '';
+  const names = new Set();
+  for (const path of existingPaths) {
+    if (prefix && !path.startsWith(prefix)) continue;
+    const segment = path.slice(prefix.length).split('/')[0];
+    if (segment) names.add(segment);
+  }
+  return names;
+}
+// A folder name inside `parentDir` that doesn't collide with an existing
+// sibling file or folder. Appends '-2', '-3', ... until free.
+export function uniqueFolderName(existingPaths, parentDir, desiredName) {
+  const taken = childNamesIn(existingPaths, parentDir);
+  if (!taken.has(desiredName)) return desiredName;
+  for (let n = 2; ; n++) {
+    const candidate = `${desiredName}-${n}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+// All file paths under a virtual folder (paths prefixed with `dirPath/`).
+export function filesUnder(existingPaths, dirPath) {
+  const prefix = `${dirPath}/`;
+  return existingPaths.filter((path) => path.startsWith(prefix));
+}
 // Flat list of file paths in the order FileBrowser renders them: a
 // depth-first walk of the directory tree, mirroring buildFileTree there.
 export function flatFileOrder(paths) {

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

@@ -0,0 +1,66 @@
+import { useEffect, useState } from 'react';
+// Captures console output from the running deck into an in-memory ring buffer and
+// notifies subscribers, so the on-panel play console can display it.
+//
+// The SDK already wraps console (to forward logs to the dev server over its
+// websocket); this wraps ON TOP and always calls through, so that forwarding and
+// the real devtools output are preserved. Install is idempotent.
+const MAX_LINES = 500;
+let buffer = [];
+let nextId = 1;
+let installed = false;
+const subscribers = new Set();
+function formatArgs(args) {
+  return args
+    .map((arg) => {
+      if (typeof arg === 'string') return arg;
+      if (arg instanceof Error) return arg.stack || arg.message;
+      try {
+        const json = JSON.stringify(arg);
+        return json ?? String(arg);
+      } catch {
+        return String(arg);
+      }
+    })
+    .join(' ');
+}
+function emit(level, args) {
+  const entry = { id: nextId++, level, text: formatArgs(args) };
+  const next = buffer.concat(entry);
+  buffer = next.length > MAX_LINES ? next.slice(next.length - MAX_LINES) : next;
+  for (const cb of subscribers) cb(buffer);
+}
+export function installConsoleCapture() {
+  if (installed || typeof console === 'undefined') return;
+  installed = true;
+  for (const level of ['log', 'warn', 'error']) {
+    const original = typeof console[level] === 'function' ? console[level].bind(console) : null;
+    console[level] = (...args) => {
+      if (original) original(...args);
+      // Never let capture throw into the caller's logging path.
+      try {
+        emit(level, args);
+      } catch {
+        // ignore
+      }
+    };
+  }
+}
+export function subscribeLogs(callback) {
+  subscribers.add(callback);
+  callback(buffer);
+  return () => subscribers.delete(callback);
+}
+export function clearLogs() {
+  buffer = [];
+  for (const cb of subscribers) cb(buffer);
+}
+// React hook: install capture (idempotent) and track the live log buffer.
+export function usePlayLogs() {
+  const [logs, setLogs] = useState(buffer);
+  useEffect(() => {
+    installConsoleCapture();
+    return subscribeLogs(setLogs);
+  }, []);
+  return { logs, clearLogs };
+}