castle-web-cli 0.4.73 → 0.4.75

package/dist/commonInstructions.d.ts

@@ -1 +1 @@
-export declare const COMMON_INSTRUCTIONS = "## Touch controls (every deck)\n\n- **Build for touch from the start.** Every deck must be fully playable on a touchscreen with no physical keyboard \u2014 design the touch controls first, not as an afterthought. Keyboard input is still fine on top, for shortcuts or typing. A touch control that only mirrors keys (e.g. a d-pad over the arrow keys) may hide itself when a hardware keyboard is present. Use good judgement.\n";
+export declare const COMMON_INSTRUCTIONS = "## Touch controls (every deck)\n\n- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch \u2014 direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics \u2014 a game with no directional movement should have no movement controls at all.\n";

package/dist/commonInstructions.js

@@ -4,5 +4,5 @@
 // (e.g. Space being reserved for play/stop) live in each kit's own CLAUDE.md.
 export const COMMON_INSTRUCTIONS = `## Touch controls (every deck)
 
-- **Build for touch from the start.** Every deck must be fully playable on a touchscreen with no physical keyboard — design the touch controls first, not as an afterthought. Keyboard input is still fine on top, for shortcuts or typing. A touch control that only mirrors keys (e.g. a d-pad over the arrow keys) may hide itself when a hardware keyboard is present. Use good judgement.
+- **Playable on a touchscreen, with only the controls the game actually needs.** Castle decks are played on phones, so whatever input a game does use must work by touch — direct tap/drag on the game itself wherever possible, and on-screen buttons only where the mechanics genuinely call for them. Do NOT add controls a game doesn't need: never drop in a generic d-pad or movement overlay by default. Prefer touching the game directly over an overlay that just mirrors keyboard keys. Keyboard input is fine to support on top for desktop play. Match the controls to the actual mechanics — a game with no directional movement should have no movement controls at all.
 `;

package/kits/basic-2d/CLAUDE.md

@@ -144,7 +144,7 @@ if (scene.keys.has('KeyX')) /* launch ball */ ;
 
 **Space is reserved** — the editor binds it to the play/stop toggle, so don't bind Space to a gameplay action (jump / shoot / launch / ...). Use arrows, WASD, letter keys, or on-screen buttons instead.
 
-For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`. The deck has TouchControls overlay support out of the box for mobile play (arrow keys + a button); no setup needed.
+For HUD text use a behavior's `ui` hook (returns React); for in-world text or shapes, draw with `ctx` from `draw`.
 
 ## Common breakout-shaped recipe (sketch)
 

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

@@ -1,7 +1,6 @@
 import React, { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { renderSpriteFrame } from '../engine/pxart';
 import { basename, formatJson, parseJsonFile } from '../engine/files';
-import { TouchControls } from '../engine/TouchControls';
 import {
   addActor,
   arrangeActors,
@@ -43,6 +42,27 @@ const EDIT_VIEWPORT = {
   originX: cardSize.width,
   originY: cardSize.height,
 };
+// Edit-camera zoom bounds. zoom > 1 magnifies (the visible viewport shrinks);
+// zoom < 1 pulls back to show more around the card.
+const MIN_EDIT_ZOOM = 0.4;
+const MAX_EDIT_ZOOM = 6;
+// Wheel-delta -> zoom-factor sensitivity for trackpad pinch (ctrl+wheel).
+const ZOOM_WHEEL_SPEED = 0.01;
+const clampZoom = (zoom) =>
+  Math.min(MAX_EDIT_ZOOM, Math.max(MIN_EDIT_ZOOM, Number(zoom) || 1));
+// Derive the effective edit viewport for a zoom level. Both extent and origin
+// scale by 1/zoom, which keeps the canvas draw path, `screenToCard`, and the
+// SelectionOverlay's `sx = box/card` projection mutually consistent (the overlay
+// just multiplies its scale by the same zoom).
+function editViewportForZoom(zoom) {
+  const z = clampZoom(zoom);
+  return {
+    width: EDIT_VIEWPORT.width / z,
+    height: EDIT_VIEWPORT.height / z,
+    originX: EDIT_VIEWPORT.originX / z,
+    originY: EDIT_VIEWPORT.originY / z,
+  };
+}
 export function SceneEditor({
   path,
   text,
@@ -60,7 +80,7 @@ export function SceneEditor({
   const canvasRef = useRef(null);
   const runtimeRef = useRef(null);
   const marqueeRef = useRef(null);
-  const editCameraRef = useRef({ x: 0, y: 0 });
+  const editCameraRef = useRef({ x: 0, y: 0, zoom: 1 });
   const selectedActorIdsRef = useRef(selectedActorIds);
   selectedActorIdsRef.current = selectedActorIds;
   const [isPlaying, setIsPlaying] = useState(false);
@@ -69,7 +89,6 @@ export function SceneEditor({
   const showMulti = selectedActorIds.length > 1 || multiSelectMode;
   const inspectorSheet = useSelectionInspectorSheet(true);
   const { value: sceneData, error } = parseJsonFile(path, text);
-  const getRuntimeKeys = useCallback(() => runtimeRef.current?.keys ?? null, []);
   const getRuntime = useCallback(() => runtimeRef.current, []);
   useScenePlayLoop({
     sceneData,
@@ -215,7 +234,6 @@ export function SceneEditor({
                         ? panGesture.onPointerUp(event)
                         : gesture.onPointerUp(event)
                   }
-                  onWheel={panGesture.onWheel}
                 />
                 {isPlaying && <SceneUI getRuntime={getRuntime} />}
               </div>
@@ -268,7 +286,6 @@ export function SceneEditor({
           </aside>
         </div>
       </EditorBody>
-      <TouchControls getKeys={getRuntimeKeys} visible={isPlaying} />
     </>
   );
 }
@@ -923,6 +940,10 @@ function usePlayPointerGesture({ canvasRef, runtimeRef }) {
 function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
   const dragRef = useRef(null);
   const spaceDownRef = useRef(false);
+  // Native wheel/gesture listeners (below) read play state through a ref so they
+  // never need to detach/reattach when play toggles.
+  const isPlayingRef = useRef(isPlaying);
+  isPlayingRef.current = isPlaying;
   useEffect(() => {
     function onKeyDown(event) {
       if (event.key !== ' ' || isEditableTarget(event.target)) return;
@@ -950,12 +971,104 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
       const viewportWidth = Number(canvas.dataset.viewportWidth) || cardSize.width;
       const viewportHeight = Number(canvas.dataset.viewportHeight) || cardSize.height;
       editCameraRef.current = {
+        ...editCameraRef.current,
         x: editCameraRef.current.x + (dx * viewportWidth) / rect.width,
         y: editCameraRef.current.y + (dy * viewportHeight) / rect.height,
       };
     },
     [canvasRef, editCameraRef]
   );
+  // Zoom about the pointer by a multiplicative factor: keep the world point
+  // under the cursor pinned while the zoom level changes. Because the effective
+  // origin scales as EDIT_VIEWPORT.origin / zoom, the camera shift to re-pin the
+  // cursor is (1/z0 - 1/z1) * (frac * EDIT_VIEWPORT.extent - EDIT_VIEWPORT.origin).
+  const zoomByFactorAtPointer = useCallback(
+    (clientX, clientY, factor) => {
+      const canvas = canvasRef.current;
+      if (!canvas || !Number.isFinite(factor) || factor <= 0) return;
+      const cam = editCameraRef.current;
+      const z0 = cam.zoom ?? 1;
+      const z1 = clampZoom(z0 * factor);
+      if (z1 === z0) return;
+      const rect = canvas.getBoundingClientRect();
+      const fracX = (clientX - rect.left) / rect.width;
+      const fracY = (clientY - rect.top) / rect.height;
+      const k = 1 / z0 - 1 / z1;
+      editCameraRef.current = {
+        x: cam.x + k * (fracX * EDIT_VIEWPORT.width - EDIT_VIEWPORT.originX),
+        y: cam.y + k * (fracY * EDIT_VIEWPORT.height - EDIT_VIEWPORT.originY),
+        zoom: z1,
+      };
+    },
+    [canvasRef, editCameraRef]
+  );
+  // Wheel + pinch are bound as NATIVE, non-passive listeners (not React props):
+  // React attaches `wheel` passively at its root, so a React onWheel can't call
+  // preventDefault and the browser's own page-zoom wins. We also need Safari's
+  // proprietary `gesture*` events, which is how it reports trackpad pinch (it
+  // does not emit ctrl+wheel like Chromium). Both paths preventDefault to stop
+  // the browser from zooming the page underneath the editor.
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    if (!canvas) return undefined;
+    let gestureScale = 1;
+    // Set while a Safari pinch gesture is in flight, so we don't double-apply
+    // zoom if Safari also emits ctrl+wheel for the same pinch.
+    let gestureActive = false;
+    const onWheel = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      // Trackpad pinch (and Ctrl+wheel) surface as wheel events with ctrlKey set
+      // in Chromium; route those to zoom and leave plain scroll as pan.
+      if (event.ctrlKey) {
+        if (gestureActive) return;
+        zoomByFactorAtPointer(
+          event.clientX,
+          event.clientY,
+          Math.exp(-event.deltaY * ZOOM_WHEEL_SPEED)
+        );
+      } else {
+        panByScreenDelta(event.deltaX, event.deltaY);
+      }
+    };
+    const onGestureStart = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      gestureActive = true;
+      gestureScale = event.scale || 1;
+    };
+    const onGestureChange = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      // Safari reports `scale` cumulatively from gesturestart (1.0 at start), so
+      // zoom by the ratio against the last reading.
+      const prev = gestureScale || 1;
+      const next = event.scale || prev;
+      gestureScale = next;
+      // GestureEvent carries clientX/clientY (the pinch centroid); fall back to
+      // the canvas center if a browser omits them.
+      const rect = canvas.getBoundingClientRect();
+      const px = Number.isFinite(event.clientX) ? event.clientX : rect.left + rect.width / 2;
+      const py = Number.isFinite(event.clientY) ? event.clientY : rect.top + rect.height / 2;
+      zoomByFactorAtPointer(px, py, next / prev);
+    };
+    const onGestureEnd = (event) => {
+      if (isPlayingRef.current) return;
+      event.preventDefault();
+      gestureActive = false;
+    };
+    const opts = { passive: false };
+    canvas.addEventListener('wheel', onWheel, opts);
+    canvas.addEventListener('gesturestart', onGestureStart, opts);
+    canvas.addEventListener('gesturechange', onGestureChange, opts);
+    canvas.addEventListener('gestureend', onGestureEnd, opts);
+    return () => {
+      canvas.removeEventListener('wheel', onWheel, opts);
+      canvas.removeEventListener('gesturestart', onGestureStart, opts);
+      canvas.removeEventListener('gesturechange', onGestureChange, opts);
+      canvas.removeEventListener('gestureend', onGestureEnd, opts);
+    };
+  }, [canvasRef, panByScreenDelta, zoomByFactorAtPointer]);
   const onPointerDown = useCallback((event) => {
     if (isPlaying || !spaceDownRef.current) return;
     event.preventDefault();
@@ -984,17 +1097,9 @@ function usePanGesture({ canvasRef, editCameraRef, isPlaying }) {
     }
     dragRef.current = null;
   }, []);
-  const onWheel = useCallback(
-    (event) => {
-      if (isPlaying) return;
-      event.preventDefault();
-      panByScreenDelta(event.deltaX, event.deltaY);
-    },
-    [isPlaying, panByScreenDelta]
-  );
   const isSpacePanning = useCallback(() => spaceDownRef.current, []);
   const isActive = useCallback(() => Boolean(dragRef.current), []);
-  return { onPointerDown, onPointerMove, onPointerUp, onWheel, isSpacePanning, isActive };
+  return { onPointerDown, onPointerMove, onPointerUp, isSpacePanning, isActive };
 }
 function handleShiftPointerDown(drag, actor, current) {
   if (actor) {
@@ -1149,13 +1254,20 @@ function useScenePlayLoop({
     const canvas = canvasRef.current;
     const ctx = canvas.getContext('2d');
     if (!ctx) return undefined;
-    const viewport = isPlaying ? undefined : EDIT_VIEWPORT;
+    const viewport = isPlaying
+      ? undefined
+      : editViewportForZoom(editCameraRef.current.zoom);
     configureSceneCanvas(canvas, ctx, viewport);
     let raf = 0;
     let last = performance.now();
     const frame = (now) => {
       const dt = Math.min(0.033, (now - last) / 1000);
       last = now;
+      // Recompute each frame so the edit zoom (mutated on the camera ref by the
+      // pinch gesture) takes effect without restarting the loop.
+      const frameViewport = isPlaying
+        ? undefined
+        : editViewportForZoom(editCameraRef.current.zoom);
       const scene = isPlaying
         ? runtimeRef.current
         : makeScene(sceneData, behaviorClasses, sprites);
@@ -1163,7 +1275,7 @@ function useScenePlayLoop({
         const snap = getSnapSettings(sceneData);
         if (isPlaying) scene.update(dt);
         if (!isPlaying) scene.camera = { ...editCameraRef.current };
-        configureSceneCanvas(canvas, ctx, viewport);
+        configureSceneCanvas(canvas, ctx, frameViewport);
         // Read selection from the ref each frame so the grid/box gating tracks
         // the current selection without resetting this loop.
         const editSelectedActorIds = isPlaying ? [] : selectedActorIdsRef.current ?? [];
@@ -1174,7 +1286,7 @@ function useScenePlayLoop({
           gridSize: snap.gridSize,
           showDebugColliders: false,
           showCropOutline: !isPlaying,
-          viewport,
+          viewport: frameViewport,
           useCamera: true,
           editPlaceholders: !isPlaying,
           editSelectedActorIds,

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

@@ -63,7 +63,7 @@ export function SelectionOverlay({
   const rootRef = useRef(null);
   // Track the canvas-sized overlay box so the card-unit layer scales onto it.
   const box = useElementSize(rootRef);
-  const [camera, setCamera] = useState({ x: 0, y: 0 });
+  const [camera, setCamera] = useState({ x: 0, y: 0, zoom: 1 });
   const [groupFrameRotation, setGroupFrameRotation] = useState(null);
   const [arrangeOpen, setArrangeOpen] = useState(false);
   const selectionKey = [...selectedActorIds].sort().join('|');
@@ -73,8 +73,13 @@ export function SelectionOverlay({
   useEffect(() => {
     let raf = 0;
     const tick = () => {
-      const cam = editCameraRef.current ?? { x: 0, y: 0 };
-      setCamera((prev) => (prev.x === cam.x && prev.y === cam.y ? prev : { x: cam.x, y: cam.y }));
+      const cam = editCameraRef.current ?? { x: 0, y: 0, zoom: 1 };
+      const zoom = cam.zoom ?? 1;
+      setCamera((prev) =>
+        prev.x === cam.x && prev.y === cam.y && prev.zoom === zoom
+          ? prev
+          : { x: cam.x, y: cam.y, zoom }
+      );
       raf = requestAnimationFrame(tick);
     };
     raf = requestAnimationFrame(tick);
@@ -334,8 +339,13 @@ function getSelectionFrame(sceneData, actorIds, preferredRotation = null) {
 }
 
 function getOverlayGeometry(frame, box, camera) {
-  const sx = box.width / cardSize.width;
-  const sy = box.height / cardSize.height;
+  // Fold the edit zoom into the card-unit -> screen-px scale. The canvas draws
+  // the card at (box / card) * zoom px-per-unit (the effective viewport extent
+  // and origin both scale by 1/zoom), and the chrome layer's `transform-origin:
+  // 0 0` projection from world (0,0) matches once sx/sy carry the same zoom.
+  const zoom = camera.zoom ?? 1;
+  const sx = (box.width / cardSize.width) * zoom;
+  const sy = (box.height / cardSize.height) * zoom;
   const camX = Math.round(camera.x);
   const camY = Math.round(camera.y);
   const rotation = frame.rotation;

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

@@ -1,7 +1,9 @@
-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
@@ -9,8 +11,11 @@ import { TouchControls } from './TouchControls';
 export function ScenePlayer({ sceneData, sprites, behaviorClasses, onFirstFrame }) {
   const canvasRef = useRef(null);
   const runtimeRef = useRef(null);
-  const getKeys = useCallback(() => runtimeRef.current?.keys ?? 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 getRuntime = useCallback(() => runtimeRef.current, []);
+  const restart = useCallback(() => setRunToken((token) => token + 1), []);
   useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas) return undefined;
@@ -56,7 +61,9 @@ export function ScenePlayer({ sceneData, sprites, behaviorClasses, onFirstFrame
     canvas.addEventListener('pointerup', onPointerUp);
     canvas.addEventListener('pointercancel', onPointerUp);
     canvas.focus();
-    const stopLoop = startPlayerLoop(canvas, ctx, runtime, onFirstFrame);
+    // 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,16 +75,156 @@ export function ScenePlayer({ sceneData, sprites, behaviorClasses, onFirstFrame
       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} />
+      </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>
   );
 }

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 };
+}

package/kits/basic-2d/engine/ui.module.css

@@ -1901,3 +1901,120 @@
     display: flex;
   }
 }
+
+/* On-panel play console: a collapsible log drawer pinned to the bottom of the
+   play panel (portaled to <body> so it sits outside the SDK's card wrapper).
+   Houses the restart control plus copy/clear log affordances. */
+.playConsole {
+  position: fixed;
+  left: 0;
+  right: 0;
+  bottom: 0;
+  z-index: 60;
+  display: flex;
+  flex-direction: column;
+  border-top: 1px solid rgba(255, 255, 255, 0.12);
+  background: rgba(13, 13, 13, 0.94);
+  color: #e6e6e6;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono',
+    'Courier New', monospace;
+  padding-bottom: env(safe-area-inset-bottom, 0px);
+  overflow: hidden;
+}
+.playConsoleHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  padding: 7px 8px 7px 10px;
+  cursor: pointer;
+}
+.playConsoleHeader:hover {
+  background: rgba(255, 255, 255, 0.04);
+}
+.playConsoleToggle {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.playConsoleCaret {
+  display: inline-flex;
+  font-size: 11px;
+  color: #8a8a8a;
+}
+.playConsoleTitle {
+  font-size: 11px;
+  font-weight: 700;
+  letter-spacing: 1px;
+  text-transform: uppercase;
+  color: #b3b3b3;
+}
+.playConsoleActions {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+}
+.playConsoleBtn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 28px;
+  padding: 0;
+  font-size: 13px;
+  color: #cfcfcf;
+  background: transparent;
+  border: 1px solid rgba(255, 255, 255, 0.14);
+  border-radius: 6px;
+  cursor: pointer;
+}
+.playConsoleBtn:hover {
+  background: rgba(255, 255, 255, 0.08);
+  color: #fff;
+}
+.playConsoleBtn:disabled {
+  opacity: 0.38;
+  cursor: default;
+}
+.playConsoleBtn:disabled:hover {
+  background: transparent;
+  color: #cfcfcf;
+}
+.playConsoleBody {
+  border-top: 1px solid rgba(255, 255, 255, 0.08);
+  height: 165px;
+  overflow-y: auto;
+  padding: 8px 10px;
+  font-size: 12px;
+  line-height: 1.5;
+}
+.playConsoleEmpty {
+  color: #6a6a6a;
+}
+.playConsoleLine {
+  white-space: pre-wrap;
+  word-break: break-word;
+  color: #c8c8c8;
+}
+.playConsoleLineWarn {
+  color: #e0af68;
+}
+.playConsoleLineError {
+  color: #ff7a93;
+}
+
+/* While the logs drawer is mounted, scale the deck card to fit ABOVE the drawer
+   (rather than sitting behind it) so play stays fully visible and interactive.
+   The SDK's initPlayCard() pins `#root > *` as a viewport-centered card with
+   !important; this higher-specificity (attribute + id) rule overrides its size
+   and vertical offset. The three custom properties are driven from JS in
+   PlayConsole using the live drawer height + the SDK's natural card size. */
+:global(html[data-castle-logs] #root > *) {
+  width: var(--castle-logs-card-w, var(--castle-card-w, 100vw)) !important;
+  height: var(--castle-logs-card-h, var(--castle-card-h, 100vh)) !important;
+  transform: translate(-50%, calc(-50% - var(--castle-logs-shift, 0px))) !important;
+  transition:
+    transform 0.18s ease,
+    width 0.18s ease,
+    height 0.18s ease;
+}

package/kits/basic-2d/pnpm-workspace.yaml

@@ -0,0 +1,3 @@
+allowBuilds:
+  '@fortawesome/fontawesome-common-types': set this to true or false
+  '@fortawesome/free-solid-svg-icons': set this to true or false

package/kits/basic-3d/CLAUDE.md

@@ -142,7 +142,7 @@ if (scene.keys.has('KeyJ')) /* jump */ ;
 
 **Space is reserved** — the editor binds it to the play/stop toggle, so don't bind Space to a gameplay action (jump / shoot / launch / ...). Use arrows, WASD, letter keys, or on-screen buttons instead.
 
-For HUD text use a behavior's `ui` hook (returns React, 500x700 design space); for in-world visuals, use Mesh/Model components or a custom `sync`. The deck has TouchControls overlay support out of the box for mobile play (arrow keys d-pad); no setup needed.
+For HUD text use a behavior's `ui` hook (returns React, 500x700 design space); for in-world visuals, use Mesh/Model components or a custom `sync`.
 
 ## Common exploration-shaped recipe (sketch)
 

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

@@ -1,7 +1,6 @@
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import * as THREE from 'three';
 import { basename, formatJson, parseJsonFile } from '../engine/files';
-import { TouchControls } from '../engine/TouchControls';
 import {
   addActor,
   defaultCameraSpec,
@@ -83,10 +82,6 @@ export function SceneEditor({
     applyScene,
     recordSnapshot: history.recordSnapshot,
   });
-  const getRuntimeKeys = useCallback(
-    () => viewport.playRuntimeRef.current?.keys ?? null,
-    [viewport.playRuntimeRef]
-  );
   const getPlayRuntime = useCallback(
     () => viewport.playRuntimeRef.current,
     [viewport.playRuntimeRef]
@@ -240,7 +235,6 @@ export function SceneEditor({
           </aside>
         </div>
       </EditorBody>
-      <TouchControls getKeys={getRuntimeKeys} visible={isPlaying} />
     </>
   );
 }

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

@@ -4,7 +4,6 @@ import { makeScene, defaultCameraSpec } from './scene';
 import { applyCameraSpec, fitRendererToCanvas } from './threeUtil';
 import { attachSceneKeys, makePlayPointerHandlers, ThreeCanvas } from './SceneViewport';
 import { SceneUI } from './SceneUI';
-import { TouchControls } from './TouchControls';
 // Engine-level scene player: mount a `SceneRuntime` against a WebGL canvas,
 // wire keyboard / pointer input, run the update+sync+render loop, and render
 // the behavior-driven UI overlay. No game logic lives here -- behaviors and
@@ -13,7 +12,6 @@ export function ScenePlayer({ sceneData, models, behaviorClasses, onFirstFrame }
   const runtimeRef = useRef(null);
   const cameraRef = useRef(null);
   const firstFrameRef = useRef(false);
-  const getKeys = useCallback(() => runtimeRef.current?.keys ?? null, []);
   const getRuntime = useCallback(() => runtimeRef.current, []);
   const pointerHandlers = useMemo(() => makePlayPointerHandlers(getRuntime), [getRuntime]);
   useEffect(() => {
@@ -55,7 +53,6 @@ export function ScenePlayer({ sceneData, models, behaviorClasses, onFirstFrame }
         {...pointerHandlers}
       />
       <SceneUI getRuntime={getRuntime} />
-      <TouchControls getKeys={getKeys} />
     </div>
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.73",
+  "version": "0.4.75",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"

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

@@ -1,136 +0,0 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
-// On-screen movement controls: a 4-way d-pad feeds arrow keys onto
-// `scene.keys` -- the exact same keyboard keys behaviors consume, no separate
-// input path.
-const KEYS = {
-  up: 'ArrowUp',
-  down: 'ArrowDown',
-  left: 'ArrowLeft',
-  right: 'ArrowRight',
-};
-export function TouchControls({ getKeys, visible = true }) {
-  const [isTouch, setIsTouch] = useState(false);
-  const heldRef = useRef(new Set());
-  useEffect(() => {
-    const params = new URLSearchParams(window.location.search);
-    const override = params.get('touch');
-    if (override === '1' || override === 'true') {
-      setIsTouch(true);
-      return undefined;
-    }
-    if (override === '0' || override === 'false') {
-      setIsTouch(false);
-      return undefined;
-    }
-    const mq = window.matchMedia('(pointer: coarse)');
-    const update = () => {
-      setIsTouch(mq.matches || 'ontouchstart' in window || navigator.maxTouchPoints > 0);
-    };
-    update();
-    mq.addEventListener?.('change', update);
-    return () => mq.removeEventListener?.('change', update);
-  }, []);
-  const release = useCallback(
-    (id) => {
-      if (!heldRef.current.has(id)) return;
-      heldRef.current.delete(id);
-      getKeys()?.delete(KEYS[id]);
-    },
-    [getKeys]
-  );
-  useEffect(() => {
-    if (!visible || !isTouch) {
-      // Drop any keys we were holding when controls hide.
-      const keys = getKeys();
-      if (keys) for (const id of heldRef.current) keys.delete(KEYS[id]);
-      heldRef.current.clear();
-    }
-  }, [visible, isTouch, getKeys]);
-  if (!visible || !isTouch) return null;
-  const press = (id) => {
-    heldRef.current.add(id);
-    getKeys()?.add(KEYS[id]);
-  };
-  const button = (id, label, extra) => (
-    <button
-      key={id}
-      type="button"
-      tabIndex={-1}
-      aria-label={id}
-      onTouchStart={(event) => {
-        event.preventDefault();
-        press(id);
-      }}
-      onTouchEnd={(event) => {
-        event.preventDefault();
-        release(id);
-      }}
-      onTouchCancel={(event) => {
-        event.preventDefault();
-        release(id);
-      }}
-      onMouseDown={(event) => {
-        event.preventDefault();
-        press(id);
-      }}
-      onMouseUp={() => release(id)}
-      onMouseLeave={() => release(id)}
-      onContextMenu={(event) => event.preventDefault()}
-      style={{ ...buttonStyle, ...extra }}>
-      {label}
-    </button>
-  );
-  return (
-    <div style={containerStyle}>
-      <div style={dpadStyle}>
-        {button('up', '▲', dpadUpStyle)}
-        {button('left', '◀', dpadLeftStyle)}
-        {button('right', '▶', dpadRightStyle)}
-        {button('down', '▼', dpadDownStyle)}
-      </div>
-    </div>
-  );
-}
-const containerStyle = {
-  position: 'fixed',
-  left: 0,
-  right: 0,
-  bottom: 0,
-  display: 'flex',
-  justifyContent: 'flex-start',
-  alignItems: 'flex-end',
-  padding: '12px 16px calc(env(safe-area-inset-bottom, 0px) + 12px)',
-  pointerEvents: 'none',
-  zIndex: 50,
-};
-// 3x3 grid -- the d-pad arms occupy the cross cells, corners stay empty.
-const dpadStyle = {
-  display: 'grid',
-  gridTemplateColumns: 'repeat(3, 64px)',
-  gridTemplateRows: 'repeat(3, 64px)',
-  gap: 6,
-  pointerEvents: 'auto',
-};
-const dpadUpStyle = { gridColumn: 2, gridRow: 1 };
-const dpadLeftStyle = { gridColumn: 1, gridRow: 2 };
-const dpadRightStyle = { gridColumn: 3, gridRow: 2 };
-const dpadDownStyle = { gridColumn: 2, gridRow: 3 };
-const buttonStyle = {
-  width: 64,
-  height: 64,
-  borderRadius: 12,
-  border: '1px solid rgba(255, 255, 255, 0.35)',
-  background: 'rgba(0, 0, 0, 0.35)',
-  color: 'rgba(255, 255, 255, 0.92)',
-  fontSize: 24,
-  fontWeight: 600,
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  userSelect: 'none',
-  WebkitUserSelect: 'none',
-  WebkitTouchCallout: 'none',
-  WebkitTapHighlightColor: 'transparent',
-  touchAction: 'none',
-  cursor: 'pointer',
-};

package/kits/basic-3d/engine/TouchControls.jsx

@@ -1,136 +0,0 @@
-import React, { useCallback, useEffect, useRef, useState } from 'react';
-// On-screen movement controls: a 4-way d-pad feeds arrow keys onto
-// `scene.keys` -- the exact same keyboard keys behaviors consume, no separate
-// input path.
-const KEYS = {
-  up: 'ArrowUp',
-  down: 'ArrowDown',
-  left: 'ArrowLeft',
-  right: 'ArrowRight',
-};
-export function TouchControls({ getKeys, visible = true }) {
-  const [isTouch, setIsTouch] = useState(false);
-  const heldRef = useRef(new Set());
-  useEffect(() => {
-    const params = new URLSearchParams(window.location.search);
-    const override = params.get('touch');
-    if (override === '1' || override === 'true') {
-      setIsTouch(true);
-      return undefined;
-    }
-    if (override === '0' || override === 'false') {
-      setIsTouch(false);
-      return undefined;
-    }
-    const mq = window.matchMedia('(pointer: coarse)');
-    const update = () => {
-      setIsTouch(mq.matches || 'ontouchstart' in window || navigator.maxTouchPoints > 0);
-    };
-    update();
-    mq.addEventListener?.('change', update);
-    return () => mq.removeEventListener?.('change', update);
-  }, []);
-  const release = useCallback(
-    (id) => {
-      if (!heldRef.current.has(id)) return;
-      heldRef.current.delete(id);
-      getKeys()?.delete(KEYS[id]);
-    },
-    [getKeys]
-  );
-  useEffect(() => {
-    if (!visible || !isTouch) {
-      // Drop any keys we were holding when controls hide.
-      const keys = getKeys();
-      if (keys) for (const id of heldRef.current) keys.delete(KEYS[id]);
-      heldRef.current.clear();
-    }
-  }, [visible, isTouch, getKeys]);
-  if (!visible || !isTouch) return null;
-  const press = (id) => {
-    heldRef.current.add(id);
-    getKeys()?.add(KEYS[id]);
-  };
-  const button = (id, label, extra) => (
-    <button
-      key={id}
-      type="button"
-      tabIndex={-1}
-      aria-label={id}
-      onTouchStart={(event) => {
-        event.preventDefault();
-        press(id);
-      }}
-      onTouchEnd={(event) => {
-        event.preventDefault();
-        release(id);
-      }}
-      onTouchCancel={(event) => {
-        event.preventDefault();
-        release(id);
-      }}
-      onMouseDown={(event) => {
-        event.preventDefault();
-        press(id);
-      }}
-      onMouseUp={() => release(id)}
-      onMouseLeave={() => release(id)}
-      onContextMenu={(event) => event.preventDefault()}
-      style={{ ...buttonStyle, ...extra }}>
-      {label}
-    </button>
-  );
-  return (
-    <div style={containerStyle}>
-      <div style={dpadStyle}>
-        {button('up', '▲', dpadUpStyle)}
-        {button('left', '◀', dpadLeftStyle)}
-        {button('right', '▶', dpadRightStyle)}
-        {button('down', '▼', dpadDownStyle)}
-      </div>
-    </div>
-  );
-}
-const containerStyle = {
-  position: 'fixed',
-  left: 0,
-  right: 0,
-  bottom: 0,
-  display: 'flex',
-  justifyContent: 'flex-start',
-  alignItems: 'flex-end',
-  padding: '12px 16px calc(env(safe-area-inset-bottom, 0px) + 12px)',
-  pointerEvents: 'none',
-  zIndex: 50,
-};
-// 3x3 grid -- the d-pad arms occupy the cross cells, corners stay empty.
-const dpadStyle = {
-  display: 'grid',
-  gridTemplateColumns: 'repeat(3, 64px)',
-  gridTemplateRows: 'repeat(3, 64px)',
-  gap: 6,
-  pointerEvents: 'auto',
-};
-const dpadUpStyle = { gridColumn: 2, gridRow: 1 };
-const dpadLeftStyle = { gridColumn: 1, gridRow: 2 };
-const dpadRightStyle = { gridColumn: 3, gridRow: 2 };
-const dpadDownStyle = { gridColumn: 2, gridRow: 3 };
-const buttonStyle = {
-  width: 64,
-  height: 64,
-  borderRadius: 12,
-  border: '1px solid rgba(255, 255, 255, 0.35)',
-  background: 'rgba(0, 0, 0, 0.35)',
-  color: 'rgba(255, 255, 255, 0.92)',
-  fontSize: 24,
-  fontWeight: 600,
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'center',
-  userSelect: 'none',
-  WebkitUserSelect: 'none',
-  WebkitTouchCallout: 'none',
-  WebkitTapHighlightColor: 'transparent',
-  touchAction: 'none',
-  cursor: 'pointer',
-};