castle-web-cli 0.4.113 → 0.4.115

package/kits/physics-2d/castle.json

@@ -22,7 +22,8 @@
       "drawings/**",
       "scenes/**",
       "blueprints/**",
-      "behaviors/**"
+      "behaviors/**",
+      "assets/**"
     ],
     "fileTypes": [
       {
@@ -46,12 +47,73 @@
         "label": "Behavior",
         "new": "New behavior",
         "icon": "code"
+      },
+      {
+        "ext": ".png",
+        "label": "Image",
+        "icon": "image",
+        "editor": "kit"
+      },
+      {
+        "ext": ".jpg",
+        "label": "Image",
+        "icon": "image",
+        "editor": "kit"
+      },
+      {
+        "ext": ".jpeg",
+        "label": "Image",
+        "icon": "image",
+        "editor": "kit"
+      },
+      {
+        "ext": ".gif",
+        "label": "Image",
+        "icon": "image",
+        "editor": "kit"
+      },
+      {
+        "ext": ".webp",
+        "label": "Image",
+        "icon": "image",
+        "editor": "kit"
+      },
+      {
+        "ext": ".svg",
+        "label": "Image",
+        "icon": "image",
+        "editor": "kit"
+      },
+      {
+        "ext": ".mp3",
+        "label": "Audio",
+        "icon": "music",
+        "editor": "kit"
+      },
+      {
+        "ext": ".wav",
+        "label": "Audio",
+        "icon": "music",
+        "editor": "kit"
+      },
+      {
+        "ext": ".m4a",
+        "label": "Audio",
+        "icon": "music",
+        "editor": "kit"
+      },
+      {
+        "ext": ".mp4",
+        "label": "Video",
+        "icon": "film",
+        "editor": "kit"
       }
     ],
     "defaultPlayFile": "scenes/main.scene"
   },
   "deckId": "ckRZGFW4iPrx",
   "cardId": "_oBFbAW6DxsO",
+  "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-08-04T21:36:03.351Z"
+  "publishedVersion": "2026-08-06T19:53:55.080Z"
 }

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

@@ -1,5 +1,5 @@
 import React, { useEffect, useRef, useState } from 'react';
-import { renderSpriteFrame } from '../engine/pxart';
+import { onArtLoaded, renderArtFrame } from '../engine/art';
 import { screenToCard } from '../engine/scene';
 import { countBlueprintInstances, listBlueprints } from '../engine/blueprint';
 import { ConfirmDialog, ContextMenu, cx, Icon, styles } from '../engine/ui';
@@ -222,11 +222,15 @@ export function BlueprintThumbnail({ blueprint, sprites, preview = false }) {
   const canvasRef = useRef(null);
   const spritePath = blueprint.components?.Sprite?.file;
   const sprite = spritePath ? sprites?.[spritePath] : null;
+  // Thumbnails draw on change, not on a frame loop, so an image that finishes
+  // decoding after this rendered has to say so or the slot stays blank.
+  const [loadTick, setLoadTick] = useState(0);
+  useEffect(() => onArtLoaded(() => setLoadTick((tick) => tick + 1)), []);
   useEffect(() => {
     const canvas = canvasRef.current;
     if (!canvas || !sprite) return;
-    renderSpriteFrame(sprite, 0, canvas);
-  }, [sprite]);
+    renderArtFrame(sprite, 0, canvas);
+  }, [sprite, loadTick]);
   if (!sprite) {
     return (
       <span className={styles.bpSlotFallback}>

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

@@ -0,0 +1,206 @@
+// Read-only image viewer. Opened for the image extensions the deck declares as
+// kit-edited (castle.json `fileTypes`), so an uploaded .png/.jpg/.svg opens as a
+// picture instead of a wall of binary in the code editor.
+//
+// It VIEWS: fit / zoom / pan, at 1:1 when you want to count pixels. Nothing here
+// writes -- editing an image is the pixel editor's job (.pxart), and a photo the
+// user uploaded is not something this kit knows how to modify.
+
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { EditorBody, IconButton, styles as uiStyles } from '../engine/ui';
+import { useTwoFingerZoomPan } from '../engine/gestureZoomPan';
+import { basename } from '../engine/files';
+import { useMediaUrl } from './mediaFile';
+import styles from './mediaViewer.module.css';
+
+const MIN_SCALE = 0.05;
+const MAX_SCALE = 64;
+// Past this the image is being inspected, not previewed: drop smoothing so
+// pixels read as pixels.
+const PIXELATE_ABOVE = 2.5;
+const WHEEL_ZOOM_PER_PX = 0.0016;
+
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+
+// Zoom `view` by `factor` about a point in STAGE coordinates measured from the
+// stage centre (the transform's origin), holding whatever is under that point
+// still. `x`/`y` are the image centre's offset from the stage centre.
+function zoomAbout(view, factor, px, py) {
+  const scale = clamp(view.scale * factor, MIN_SCALE, MAX_SCALE);
+  const k = scale / view.scale;
+  return { scale, x: px - (px - view.x) * k, y: py - (py - view.y) * k };
+}
+
+// Scale that fits the whole image in the stage, with a little breathing room.
+// Small images are scaled UP to fill: at 16x16 a "true size" preview is a speck.
+function fitScale(stage, natural) {
+  if (!stage.width || !stage.height || !natural.width || !natural.height) return 1;
+  const margin = 24;
+  const sx = (stage.width - margin) / natural.width;
+  const sy = (stage.height - margin) / natural.height;
+  return clamp(Math.min(sx, sy), MIN_SCALE, MAX_SCALE);
+}
+
+// The pan/zoom state for the stage, plus the input handlers that drive it:
+// wheel to zoom about the cursor, drag to pan, two-finger pinch/pan on touch.
+// Refits whenever the stage resizes or a different image loads, until the user
+// takes over (`touched`) -- then their framing is theirs to keep.
+function useImageView(stageRef, natural) {
+  const [view, setView] = useState({ scale: 1, x: 0, y: 0 });
+  const [dragging, setDragging] = useState(false);
+  const touched = useRef(false);
+  const stageSize = useRef({ width: 0, height: 0 });
+
+  const fit = useCallback(() => {
+    touched.current = false;
+    setView({ scale: fitScale(stageSize.current, natural), x: 0, y: 0 });
+  }, [natural]);
+
+  useLayoutEffect(() => {
+    const stage = stageRef.current;
+    if (!stage || typeof ResizeObserver === 'undefined') return undefined;
+    const measure = () => {
+      stageSize.current = { width: stage.clientWidth, height: stage.clientHeight };
+      if (!touched.current) fit();
+    };
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(stage);
+    return () => observer.disconnect();
+  }, [stageRef, fit]);
+
+  // Zoom about a client-space point (cursor, pinch centroid).
+  const zoomAt = useCallback((factor, clientX, clientY) => {
+    const rect = stageRef.current?.getBoundingClientRect();
+    if (!rect) return;
+    touched.current = true;
+    const px = clientX - rect.left - rect.width / 2;
+    const py = clientY - rect.top - rect.height / 2;
+    setView((current) => zoomAbout(current, factor, px, py));
+  }, [stageRef]);
+
+  // Zoom about the stage centre, for the toolbar buttons.
+  const zoomBy = useCallback((factor) => {
+    touched.current = true;
+    setView((current) => zoomAbout(current, factor, 0, 0));
+  }, []);
+
+  const setScale = useCallback((scale) => {
+    touched.current = true;
+    setView((current) => zoomAbout(current, scale / current.scale, 0, 0));
+  }, []);
+
+  const panBy = useCallback((dx, dy) => {
+    touched.current = true;
+    setView((current) => ({ ...current, x: current.x + dx, y: current.y + dy }));
+  }, []);
+
+  useEffect(() => {
+    const stage = stageRef.current;
+    if (!stage) return undefined;
+    const onWheel = (event) => {
+      event.preventDefault();
+      zoomAt(Math.exp(-event.deltaY * WHEEL_ZOOM_PER_PX), event.clientX, event.clientY);
+    };
+    stage.addEventListener('wheel', onWheel, { passive: false });
+    return () => stage.removeEventListener('wheel', onWheel);
+  }, [stageRef, zoomAt]);
+
+  // Mouse/pen drag to pan. Touch drags belong to the pinch gesture below, which
+  // stops their propagation before they reach this.
+  const onPointerDown = (event) => {
+    if (event.pointerType === 'touch' || event.button !== 0) return;
+    event.currentTarget.setPointerCapture(event.pointerId);
+    setDragging(true);
+  };
+  const onPointerMove = (event) => {
+    if (!dragging) return;
+    panBy(event.movementX, event.movementY);
+  };
+  const endDrag = () => setDragging(false);
+
+  useTwoFingerZoomPan({
+    targetRef: stageRef,
+    onGestureStart: endDrag,
+    onGestureMove: ({ factor, cx, cy, dx, dy }) => {
+      zoomAt(factor, cx, cy);
+      panBy(dx, dy);
+    },
+  });
+
+  return {
+    view,
+    dragging,
+    fit,
+    zoomBy,
+    setScale,
+    stageProps: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp: endDrag,
+      onPointerCancel: endDrag,
+      onDoubleClick: fit,
+    },
+  };
+}
+
+export function ImageViewer({ path }) {
+  const url = useMediaUrl(path);
+  const stageRef = useRef(null);
+  const [natural, setNatural] = useState({ width: 0, height: 0 });
+  const [status, setStatus] = useState('loading');
+  const { view, dragging, fit, zoomBy, setScale, stageProps } = useImageView(stageRef, natural);
+
+  // A new URL (different file, or the same one re-uploaded) starts over.
+  useEffect(() => setStatus('loading'), [url]);
+
+  const onLoad = (event) => {
+    const image = event.currentTarget;
+    // SVGs without intrinsic dimensions report 0; fall back so fit has numbers.
+    setNatural({ width: image.naturalWidth || 300, height: image.naturalHeight || 300 });
+    setStatus('ready');
+  };
+
+  const percent = Math.round(view.scale * 100);
+  return (
+    <EditorBody>
+      <div className={styles.viewer}>
+        <div className={styles.toolbar}>
+          <IconButton icon="zoom-out" label="Zoom out" onClick={() => zoomBy(1 / 1.4)} />
+          <IconButton icon="zoom-in" label="Zoom in" onClick={() => zoomBy(1.4)} />
+          <IconButton icon="fit" label="Fit to panel" onClick={fit} />
+          <button type="button" className={uiStyles.button} onClick={() => setScale(1)}>
+            1:1
+          </button>
+          <span className={styles.readout}>
+            {status === 'ready' ? `${natural.width}×${natural.height} · ${percent}%` : ''}
+          </span>
+        </div>
+        <div
+          ref={stageRef}
+          className={`${styles.stage}${dragging ? ` ${styles.dragging}` : ''}`}
+          {...stageProps}>
+          <img
+            src={url}
+            alt={basename(path)}
+            className={`${styles.image}${view.scale >= PIXELATE_ABOVE ? ` ${styles.pixelated}` : ''}`}
+            style={{
+              width: natural.width || undefined,
+              height: natural.height || undefined,
+              transform: `translate(-50%, -50%) translate(${view.x}px, ${view.y}px) scale(${view.scale})`,
+              visibility: status === 'ready' ? 'visible' : 'hidden',
+            }}
+            onLoad={onLoad}
+            onError={() => setStatus('error')}
+          />
+          {status === 'error' ? (
+            <div className={`${styles.message} ${styles.messageError}`}>
+              Could not load {basename(path)}.
+            </div>
+          ) : null}
+          {status === 'loading' ? <div className={styles.message}>Loading…</div> : null}
+        </div>
+      </div>
+    </EditorBody>
+  );
+}

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

@@ -0,0 +1,57 @@
+// Read-only audio / video player. Opened for the sound and video extensions the
+// deck declares as kit-edited (castle.json `fileTypes`), so an uploaded .mp3 or
+// .mp4 can be played in place instead of being a file you can only guess at from
+// its name.
+//
+// The transport is the BROWSER'S: `<audio controls>` / `<video controls>`. Play,
+// pause, scrub, volume, fullscreen, and picture-in-picture all come with it,
+// they match what the platform's users already know, and they stay accessible
+// and touch-sized without us reimplementing any of it. This file is the frame
+// around that element, not a player.
+//
+// Nothing here writes: trimming or converting a media file is not something this
+// kit does, and a viewer that can't damage the file needs no save state.
+
+import { useEffect, useState } from 'react';
+import { EditorBody } from '../engine/ui';
+import { basename } from '../engine/files';
+import { useMediaUrl } from './mediaFile';
+import styles from './mediaViewer.module.css';
+
+export function MediaPlayer({ path, kind }) {
+  const url = useMediaUrl(path);
+  const [failed, setFailed] = useState(false);
+  // A new file (or a re-upload of this one) starts over.
+  useEffect(() => setFailed(false), [url]);
+
+  const isVideo = kind === 'video';
+  const Media = isVideo ? 'video' : 'audio';
+  return (
+    <EditorBody>
+      <div className={styles.viewer}>
+        <div className={styles.mediaStage}>
+          <div className={isVideo ? styles.videoPanel : styles.audioPanel}>
+            <div className={styles.fileName}>{basename(path)}</div>
+            <Media
+              key={url}
+              className={isVideo ? styles.video : styles.audio}
+              src={url}
+              controls
+              // Metadata only: opening a file shouldn't pull the whole thing
+              // down until someone presses play. Video shows its first frame as
+              // the poster so the panel isn't a black box.
+              preload={isVideo ? 'auto' : 'metadata'}
+              playsInline
+              onError={() => setFailed(true)}
+            />
+            {failed ? (
+              <div className={styles.inlineError}>
+                Could not play {basename(path)} — this browser may not support its format.
+              </div>
+            ) : null}
+          </div>
+        </div>
+      </div>
+    </EditorBody>
+  );
+}

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

@@ -1464,10 +1464,14 @@ function useScenePlayLoop({
   useEffect(() => {
     if (!isPlaying) {
       runtimeRef.current = null;
-      return;
+      return undefined;
     }
-    if (!sceneData) return;
-    runtimeRef.current = makeScene(sceneData, behaviorClasses, sprites, files).clone();
+    if (!sceneData) return undefined;
+    const runtime = makeScene(sceneData, behaviorClasses, sprites, files).clone();
+    runtimeRef.current = runtime;
+    // Pressing Stop has to stop what the runtime started -- a sound keeps
+    // playing on its own otherwise, with no scene left to stop it.
+    return () => runtime.dispose();
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [sprites, isPlaying, text, runtimeRef]);
   // Animation loop -- draws edit-mode previews and ticks the play-mode runtime.

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

@@ -10,6 +10,8 @@ import { getFileKind } from '../engine/files';
 import { useLiveDeckFiles } from '../engine/liveReload';
 import { collectAssets } from '../engine/assets';
 import { MainEditor, styles } from '../engine/ui';
+import { ImageViewer } from './ImageViewer';
+import { MediaPlayer } from './MediaPlayer';
 import { PxArtEditor } from './PxArtEditor';
 import { SceneEditor } from './SceneEditor';
 
@@ -111,6 +113,12 @@ export function SingleEditor({ path, editor }) {
     );
   } else if (kind === 'pxart') {
     body = <PxArtEditor path={path} text={text} onChange={onChange} />;
+  } else if (kind === 'image') {
+    // Viewers read their file's BYTES over the serve, not the text file map --
+    // `files` holds source, and an image decoded as utf-8 is nothing.
+    body = <ImageViewer path={path} />;
+  } else if (kind === 'audio' || kind === 'video') {
+    body = <MediaPlayer path={path} kind={kind} />;
   }
   // 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.

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

@@ -1,17 +1,15 @@
-// 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.
+// Discover every behavior class from `behaviors/**/*.jsx`. Vite HMR is off, so a
+// newly-added behavior file is picked up on the next reload/restart.
 // Root-anchored so the kit finds the DECK's behaviors even when the kit is
 // itself an import (see engine/files.js). Imports are swept first and the deck's
 // own behaviors last: collectBehaviors keys by behaviorName, so a behavior the
 // deck defines wins over one of the same name from a dependency.
+// `behaviors/` is the ONE place behaviors live -- the rest of the system (the
+// deck file map, the editor's visible paths, lint, the duplicate gate) keys off
+// that directory, so a behavior kept anywhere else is invisible to all of it.
 const modules = {
   ...import.meta.glob('/imports/*/behaviors/**/*.jsx', { eager: true }),
-  ...import.meta.glob('/imports/*/physics/behaviors/**/*.jsx', { eager: true }),
   ...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';

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

@@ -0,0 +1,20 @@
+import { useEffect, useState } from 'react';
+import { fileUrl, onFilesChanged } from 'castle-web-sdk';
+
+// The URL a media viewer points at, re-minted whenever the file itself changes
+// on disk (a re-upload over the same name, an agent regenerating an asset). The
+// serve sends the bytes `no-store`, but an <img>/<audio> already showing the old
+// ones won't re-request on its own -- a changed URL is what makes it.
+export function useMediaUrl(path) {
+  const [version, setVersion] = useState(0);
+  useEffect(
+    () =>
+      onFilesChanged((event) => {
+        if (event.changes.some((change) => change.path === path)) {
+          setVersion((current) => current + 1);
+        }
+      }),
+    [path]
+  );
+  return version === 0 ? fileUrl(path) : `${fileUrl(path)}&v=${version}`;
+}

package/kits/physics-2d/editors/mediaViewer.module.css

@@ -0,0 +1,128 @@
+/* Shared chrome for the read-only media viewers (image, audio): a toolbar row
+   over a stage that fills the panel. Neither viewer edits anything, so there is
+   no inspector column and no save state -- just controls and the file. */
+
+/* `.editorBody` is a flex row, so claim the whole panel rather than sizing to
+   the toolbar's content width. */
+.viewer {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+  min-height: 0;
+  width: 100%;
+  height: 100%;
+  color: var(--castle-inspector-text, #e6e6ea);
+}
+
+.toolbar {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 10px;
+  border-bottom: 1px solid var(--castle-border, #2a2a33);
+}
+
+/* Pushed-right readout: dimensions / zoom / time. Tabular figures so a ticking
+   clock or a changing zoom doesn't jitter the row. */
+.readout {
+  margin-left: auto;
+  font-size: 12px;
+  opacity: 0.7;
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+.stage {
+  position: relative;
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow: hidden;
+  background:
+    repeating-conic-gradient(#1b1b21 0% 25%, #23232b 0% 50%) 50% / 20px 20px;
+  /* The pan/pinch gestures own this surface. */
+  touch-action: none;
+  cursor: grab;
+}
+.stage.dragging {
+  cursor: grabbing;
+}
+
+.image {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform-origin: center;
+  /* No smoothing at high zoom: this is a pixel inspector as much as a preview. */
+  user-select: none;
+  -webkit-user-drag: none;
+  pointer-events: none;
+}
+.pixelated {
+  image-rendering: pixelated;
+}
+
+.message {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  text-align: center;
+  font-size: 13px;
+  opacity: 0.7;
+}
+.messageError {
+  color: #e86a73;
+  opacity: 1;
+}
+
+/* Audio / video: the native element, centered, with the filename above it. The
+   browser draws the transport, so this only has to give it room. */
+.mediaStage {
+  display: flex;
+  flex: 1 1 auto;
+  min-height: 0;
+  align-items: center;
+  justify-content: center;
+  padding: 20px;
+}
+.audioPanel,
+.videoPanel {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  min-width: 0;
+  width: 100%;
+}
+.audioPanel {
+  max-width: 420px;
+}
+/* Video takes the panel it's given, capped so the controls stay a sane size. */
+.videoPanel {
+  max-width: 100%;
+  max-height: 100%;
+  min-height: 0;
+}
+.audio {
+  width: 100%;
+}
+.video {
+  min-height: 0;
+  max-width: 100%;
+  max-height: 100%;
+  background: #000;
+  border-radius: 4px;
+}
+.inlineError {
+  font-size: 12px;
+  color: #e86a73;
+}
+.fileName {
+  font-size: 13px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}

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

@@ -74,6 +74,7 @@ export function ScenePlayer({ sceneData, sprites, files, behaviorClasses, onFirs
     const stopLoop = startPlayerLoop(canvas, ctx, runtime, onFirstFrame, onLoopError);
     return () => {
       stopLoop();
+      runtime.dispose();
       window.removeEventListener('keydown', onKeyDown);
       window.removeEventListener('keyup', onKeyUp);
       canvas.removeEventListener('pointerdown', onPointerDown);