castle-web-cli 0.4.128 → 0.4.130

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

@@ -1,11 +1,10 @@
 # physics-2d kit
 
-This is the `basic-2d` actor/behavior/scene framework plus a built-in 2D
-**physics** system (matter-js). Everything in `basic-2d` works the same; physics
-adds `RigidBody`, physics fields on `Collider`, a world-gravity scene setting,
-collision callbacks, `Joints` that link actors (spring/rod/pin/weld/rope, several
-per actor), and ready-made touch-first controls (`Draggable`, `Slingshot`, `AnalogStick`).
-See `## Physics` below.
+An actor / behavior / scene framework for 2D games, with a built-in
+**physics** system (matter-js): `RigidBody`, physics fields on `Collider`, a
+world-gravity scene setting, collision callbacks, `Joints` that link actors
+(spring/rod/pin/weld/rope, several per actor), and ready-made touch-first
+controls (`Draggable`, `Slingshot`, `AnalogStick`). See `## Physics` below.
 
 ## Welcome message
 
@@ -22,10 +21,10 @@ Do you already know what you want to make, or do you want to figure it out toget
 - Editable screens live in `scenes/*.scene` files (plain JSON). Use a separate scene file per distinct screen, and switch with `scene.loadFromFile('name.scene')`.
 - Every actor is an instance of a **blueprint** (`blueprints/*.scene`) — see `## Blueprints` below. Always author the blueprint file yourself and reference it via `"blueprint"`. Don't write inline actors (full `components`, no `blueprint` field): the editor auto-migrates each one into its own new blueprint file on open, one per actor with no dedup, which litters the deck with junk blueprints.
 - Real game objects and scenery should usually be editable sprites: generate `.sprite` with `npm run draw -- name`, then place it via a `Sprite` component pointing at `drawings/name.sprite`. Dynamic UI/effects stay procedural.
-- A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, `Sound` and `Video` play audio and video files, and `Tone` synthesizes a note with no file at all. Point their `file` at the deck path (`assets/logo.png`).
+- A deck can also hold uploaded media (the Files panel's Upload button): `Sprite` draws image files as well as `.sprite`, and `Video` plays video files. Point their `file` at the deck path (`assets/logo.png`). For audio see `## Sound` below -- sound effects need no component at all.
 - **Supported media formats are exactly**: `.png` `.jpg` `.jpeg` `.gif` `.webp` `.svg` images, `.mp3` `.wav` `.m4a` audio, `.mp4` (H.264) video. Nothing else — a published deck inlines every asset as a `data:` URI, where the browser trusts the declared type instead of sniffing the bytes, so a format that merely works while serving (`.mov` is the classic case) can be dead once published. Convert, don't improvise.
 - This kit is plain JavaScript. Use `.jsx` for files with JSX, `.js` otherwise; do not add TypeScript files or a new build step.
-- After any code, scene, or drawing edit, run `npm run restart`.
+- Do not reload the deck after an edit. Nothing auto-reloads any more: the person applies your changes when they are ready, from the Play panel's restart button or a panel's own reload control.
 - Space is reserved by the editor for play/stop; do not bind Space to gameplay.
 - Do not read `engine/`, `editors/`, or built-in behaviors (`Layout.jsx`, `Sprite.jsx`, `Collider.jsx`, `Camera.jsx`, and the physics ones — `RigidBody.jsx`, `Joints.jsx`, `Draggable.jsx`, `Slingshot.jsx`, `AnalogStick.jsx`) to build a game. Their public API is documented below.
 - Details below: `## Behavior shape`, `## Scene file`, `## Blueprints`, `## Built-in behaviors`, `## Creating pixel art`, `## SceneRuntime API`, and `## Input shortcuts`.
@@ -57,8 +56,8 @@ Write the smallest game that satisfies what the user asked for. No sound, partic
 
 The deck is already serving when you start (`castle-web init` set that up; see `.castle/serve.json` for the URL). The user is watching that page right now. Your job is to make it interesting incrementally:
 
-1. **Build incrementally.** Start with the smallest playable thing (one mechanic, one scene change), `npm run restart`, then add the next piece. Do NOT write the whole game in one shot.
-2. **After every edit:** `npm run restart` (no hot reload). The served page refreshes and the user sees the change.
+1. **Build incrementally.** Start with the smallest playable thing (one mechanic, one scene change), then add the next piece. Do NOT write the whole game in one shot.
+2. **Do not reload.** Data edits (scenes, drawings, sprites) appear in the open editors on their own. Code edits wait for the person to apply them -- reloading a panel someone is working in loses their place.
 3. **Prefer real, editable assets.** For game objects, characters, and scenery, make actual pixel-art sprites and place them as real actors in `scenes/*.scene` — not shapes drawn in code. Real assets let the creator move and re-skin things in the editor and let other creators remix the deck. Make art as `.sprite` via the `draw` command (see **Creating pixel art** below). Data-driven UI (health bars, score/text, HUD gauges) and dynamic things (bullets, particles, effects) are correctly procedural/code — don't force those into sprites.
 4. **Separate scenes per screen.** Use a separate `scenes/*.scene` file for each distinct screen — menu/title, each level, game-over, etc. — not one mega-scene. Each stays independently editable in the editor. Switch at runtime with `scene.loadFromFile('gameover.scene')` (reads the file and transitions) on play / win / level change. NEVER `import` a `.scene` file as a module — scene files are data, not modules; use `scene.readFromFile` / `scene.loadFromFile`.
 
@@ -174,25 +173,42 @@ Template `components` keys are behavior names (the `static behaviorName`); add a
   ```
 
 - **Camera** — `{ target: actorId, followX, followY, roomWidth, roomHeight }`. Place on a dedicated actor; sets `scene.camera` clamped to the room. Omit entirely for a fixed view (no camera = no translation).
-- **Sound** — `{ file: "assets/hit.mp3", volume?: 1, playbackRate?: 1, pan?: 0, loop?: false, polyphonic?: false, playOnStart?: true }`. Plays an audio file (`.mp3`/`.wav`/`.m4a`) from an actor. `playbackRate` retunes it (2 = an octave up and twice as fast, 0.5 = an octave down); `pan` places it left (−1) to right (+1); `polyphonic` overlaps copies instead of cutting the last one off, which is what a sound effect fired twice in a row should do (leave it off for music). With `playOnStart` it starts with the scene; otherwise trigger it from code through the handle it puts on the actor:
+- **SoundPlayer** — `{ file: "assets/music/theme.mp3", stream?: false, volume?: 1, playbackRate?: 1, pan?: 0, loop?: false, playOnStart?: true }`. Plays one audio file from an actor. `stream: false` (the default) fires it from memory — instant and overlapping, for effects; `stream: true` streams it from an `<audio>` element — for music and long ambience, whose decoded audio would be far too big to hold. `loop` applies to `stream: true` only. `playbackRate` retunes it (2 = an octave up and twice as fast, 0.5 = an octave down); `pan` places it left (−1) to right (+1). With `playOnStart` it starts with the scene; otherwise trigger it through the handle it puts on the actor:
 
   ```jsx
-  scene.getActor('sfx').runtime.sound.play();   // restarts from the beginning
-  await actor.runtime.sound.play();             // ...and wait for it to finish
-  actor.runtime.sound.stop();                   // also: pause(), resume(), .playing
-  scene.sound.stopAll();                        // everything the scene is playing, off
+  scene.getActor('music').runtime.soundPlayer.play();
+  await actor.runtime.soundPlayer.play();      // ...and wait for it to finish
+  actor.runtime.soundPlayer.stop();            // stream also: pause(), resume(), .playing
   ```
 
-  Sound only plays during play, never in the editor, and everything stops on Stop / a scene change. Browsers refuse audio until the player has touched the page; a sound that starts before that is queued and begins on the first tap or key, so don't work around it.
-- **Tone** — `{ note?: 60, waveform?: 'square'|'sawtooth'|'sine'|'triangle'|'noise', attack?: 0, release?: 0.3, volume?: 0.5, pan?: 0, playOnStart?: false }`. Plays a synthesized note — no audio file, nothing downloaded, nothing stored. Reach for this before an audio file for blips, thuds and pickups. `note` is MIDI (60 = middle C, +12 an octave, +1 a semitone), and the note lasts `attack + release` seconds.
+  **For a one-off sound effect, don't place one of these** — `scene.sound.play('hit')` needs no actor and no component. See `## Sound` below.
 
-  ```jsx
-  actor.runtime.tone.play();                 // the note as configured
-  actor.runtime.tone.play({ note: 72 });     // ...or override per play, e.g. a rising scale
-  await actor.runtime.tone.play({ note: 48, waveform: 'noise' });
-  ```
+  Sound only plays during play, never in the editor, and everything stops on Stop / a scene change. Browsers refuse audio until the player has touched the page; a sound that starts before that is queued and begins on the first tap or key, so don't work around it.
 - **Video** — `{ file: "assets/clip.mp4", mode?: 'cover'|'fit'|'stretch', playing?: true, loop?: true, muted?: true, volume?: 1 }`. Plays an `.mp4` (H.264) video inside the Layout box, drawn into the scene like a sprite: it moves with Layout, draws in `z` order, and can carry a Collider. `mode` frames it exactly as Sprite's does. In the editor it holds its first frame so you can place it. Leave `muted: true` unless the player has already interacted — an unmuted autoplaying video is blocked by browsers, a muted one isn't.
 
+## Sound
+
+Two ways to make a noise. The choice is about LENGTH, not importance.
+
+**Sound effects — `scene.sound.play(name)`.** No actor, no component, no import:
+
+```jsx
+scene.sound.play('jump');                     // by filename, without the extension
+scene.sound.play('assets/sounds/hit.wav');    // ...or by full path
+scene.sound.play('hit', { volume: 0.5, pan: -0.8, playbackRate: 1.2 });
+scene.sound.stopAll();                        // everything the scene is playing, off
+```
+
+Effects are decoded into memory before the deck starts, so they fire instantly and overlap. **Put them in `assets/sounds/`** — that directory, and only that one, is preloaded. A sound kept elsewhere still plays, but its FIRST play is silent while it loads.
+
+`play` returns `{ stop, finished }`, or `null` when nothing played (an unknown name, or a sound still loading — an effect that arrives late is worse than one that never arrives, so it is dropped rather than deferred). Also on `scene.sound`: `isLoaded`, `whenLoaded`, `has(name)`, `voiceCount`.
+
+Name a sound by its filename without the extension, or by its full deck path. Two files sharing a filename (`assets/sounds/click.wav` and `assets/sounds/ui/click.wav`) make the bare name ambiguous, so it resolves to NEITHER — use the full path for those.
+
+**Music and long ambience — a `SoundPlayer` component with `stream: true`.** Decoded audio is ~21MB per minute, so a track is streamed from an `<audio>` element instead of held in memory. Keep those in `assets/music/`, outside the preload directory.
+
+128 effects can sound at once; past that the oldest is cut off to make room.
+
 ## Physics
 
 This kit simulates 2D physics with matter-js. You get gravity, collisions,
@@ -460,7 +476,7 @@ Don't hand-write pixel grids. Generate sprites with the `draw` command: **emit a
   ```
 
   writes `drawings/ship.sprite`. You can also pass `--from file.svg` instead of stdin. An undecodable svg (no usable rects) errors with a nonzero exit and writes nothing.
-- **After writing, `npm run restart`.** Newly created files aren't in the kit's static glob until a restart; until then the missing-sprite fallback renders the placeholder (so an actor pointing at a not-yet-drawn `.sprite` is still playable).
+- **A newly created file is not in the kit's static glob until the panel reloads**, so until then the missing-sprite fallback renders the placeholder -- an actor pointing at a not-yet-drawn `.sprite` is still playable. Do not force a reload to fix it.
 
 Point a `Sprite` component's `file` at the generated `drawings/<name>.sprite` to put the art on an actor.
 
@@ -491,6 +507,7 @@ To generate path art, emit an svg of **shapes** rather than per-pixel rects and
 - `scene.spawnActor({ components: { Layout: {...}, MyBehavior: {...} } })` — add a new actor at runtime with fully-specified components (no blueprint). Returns the actor (with auto-minted `id` and `runtime = {}`). Use this; don't push to `scene.data.actors` by hand.
 - `scene.spawnFromBlueprint('blueprints/enemy.scene', { components: { Layout: { x, y } } })` — spawn an instance of a blueprint, same merge semantics as a placed instance. Prefer this over `spawnActor` when you're spawning copies of something that has (or should have) a blueprint, e.g. `scene.spawnFromBlueprint(actor.blueprint, { components: { Layout: { x: actor.components.Layout.x, y: actor.components.Layout.y } } })` to spawn another of the same kind as an existing actor.
 - `scene.despawnActor(id)` — remove an actor at runtime. Use this; don't `splice` + `delete` by hand.
+- `scene.sound` — the deck's sound library: `play(name, opts)`, `stopAll()`, `isLoaded`, `whenLoaded`, `has(name)`, `voiceCount`. See `## Sound`.
 - `scene.status` — string you can set/read for game-state ('playing', 'gameover', ...).
 - `scene.load(sceneData)` — replace the running scene with the given scene data object.
 - `scene.readFromFile(name)` — read and parse a scene file (`'gameover.scene'`, `'levels/2.scene'`), returning its scene data. Use this instead of importing a `.scene` file.

package/kits/physics-2d/behaviors/Joints.jsx

@@ -1,5 +1,5 @@
 import React, { useState } from 'react';
-import { Panel, SelectField, NumberField, CheckboxField, Button } from '../engine/ui';
+import { Panel, SelectField, NumberField, CheckboxField, Button, FileField } from '../engine/ui';
 import { centerOf, inActorWorldSpace } from '../engine/physics/controls';
 import { JOINT_TYPES } from '../engine/physics/joints';
 import { drawJointArt } from '../engine/physics/jointArt';
@@ -180,11 +180,12 @@ function JointEntry({ index, joint, spriteFiles, active, onPickToggle, onPatch,
       <SelectField label="Show in play" value={render} onChange={(v) => onPatch({ render: v })} options={RENDER_MODES} />
       {render === 'sprite' ? (
         <>
-          <SelectField
+          <FileField
             label="Art"
             value={joint.sprite || ''}
             onChange={(v) => onPatch({ sprite: v })}
-            options={['', ...spriteFiles]}
+            files={spriteFiles}
+            allowEmpty
           />
           <NumberField label="Thickness" value={joint.thickness ?? 12} min={1} onChange={(v) => onPatch({ thickness: v })} />
           <SelectField

package/kits/physics-2d/behaviors/SoundPlayer.jsx

@@ -0,0 +1,266 @@
+import { resolveDeckFile } from 'castle-web-sdk';
+import React from 'react';
+import { mediaElement, playMedia, setMediaPan, setMediaPlaybackRate, stopMedia } from '../engine/media';
+import { isPreloadedPath, playSound } from '../engine/sound';
+import { mediaFilesOfKind } from '../engine/files';
+import { FileField, Panel } from '../engine/ui';
+import { AutoFields, overrideProps } from '../engine/autoInspector';
+import { PAN, UNIT } from '../engine/propertyRanges';
+
+// Plays one audio file (.mp3 / .wav / .m4a) from an actor.
+//
+// `stream` picks HOW it plays, which is the only real decision here:
+//
+//   stream: false  the sound is already decoded in memory, and plays instantly.
+//                  Copies overlap. This is what a sound effect wants, and it is
+//                  the default. Preloaded only if the file lives in
+//                  `assets/sounds/` -- see engine/sound.js.
+//   stream: true   an <audio> element, decoded as it plays. Nothing is held in
+//                  memory, so this is what a music track or a long ambience
+//                  wants -- a minute of audio is ~21MB decoded. One at a time:
+//                  playing again restarts it rather than overlapping.
+//
+// Set `playOnStart` and it plays when the scene starts. Either way you can
+// trigger it from a behavior, through the handle this puts on the actor:
+//
+//   scene.getActor('music').runtime.soundPlayer.play();
+//   await actor.runtime.soundPlayer.play();   // ...and wait for it to end
+//   actor.runtime.soundPlayer.stop();
+//
+// To fire a sound effect that no actor owns -- most of them -- don't place one of
+// these at all. `scene.sound.play('hit')` needs no actor and no import.
+//
+// Sound only plays during play, never in the editor: `update` is what wires it
+// up, and the editor doesn't run it. Pressing Stop silences everything, as does
+// `scene.sound.stopAll()` (see systems/media.js).
+//
+// Browsers refuse to play audio until the player has touched the page. A sound
+// that starts before that isn't lost -- it's queued and starts on the first tap
+// or key, which for a game is usually the first input anyway.
+export class SoundPlayer {
+  static behaviorName = 'SoundPlayer';
+
+  static defaultProps = {
+    file: '',
+    stream: false,
+    volume: 1,
+    playbackRate: 1,
+    pan: 0,
+    loop: false,
+    playOnStart: true,
+  };
+
+  // Mirrors the clamps `readSettings` already applies at runtime, so the
+  // inspector can't author a value the sound would silently ignore -- including
+  // playbackRate's 0.01..10, where the classic editor's ceiling lives.
+  static propertyMeta = {
+    stream: { hint: streamHint },
+    volume: UNIT,
+    playbackRate: { min: 0.01, max: 10, step: 0.05 },
+    pan: PAN,
+  };
+
+  constructor(props) {
+    this.props = props;
+  }
+
+  update(actor) {
+    if (!actor.runtime || actor.runtime.collected) return;
+    const file = resolveDeckFile(this.props.file);
+    const settings = readSettings(this.props);
+    const previous = actor.runtime.soundPlayer;
+    const handle = settings.stream
+      ? streamHandleFor(actor.id, file, settings, previous)
+      : bufferHandleFor(file, settings, previous);
+    actor.runtime.soundPlayer = handle;
+    // Only a NEW handle starts itself: this runs every frame, and `playOnStart`
+    // means the start of the scene, not the start of each one.
+    if (handle && handle !== previous && this.props.playOnStart) void handle.play();
+  }
+
+  static Inspector({ component, setComponent, override }) {
+    // `loop` is an element's, not a buffer's -- a decoded one-shot has no loop
+    // in v0. Hiding it rather than showing a dead control is the difference
+    // between a prop that doesn't apply and one that looks broken.
+    const streaming = Boolean(component.stream ?? SoundPlayer.defaultProps.stream);
+    const fields = ['stream', 'volume', 'playbackRate', 'pan', 'loop', 'playOnStart'];
+    return (
+      <Panel title="SoundPlayer" overridden={override?.anyOverridden()}>
+        <FileField
+          label="File"
+          value={component.file}
+          onChange={(file) => setComponent({ file })}
+          files={mediaFilesOfKind('audio')}
+          allowEmpty
+          {...overrideProps(override, 'file')}
+        />
+        <AutoFields
+          defaultProps={SoundPlayer.defaultProps}
+          meta={SoundPlayer.propertyMeta}
+          component={component}
+          setComponent={setComponent}
+          only={streaming ? fields : fields.filter((key) => key !== 'loop')}
+          override={override}
+        />
+      </Panel>
+    );
+  }
+}
+
+// What `stream` means, in the inspector, for the setting it is actually on --
+// a note describing both halves of the toggle at once would say less than the
+// prop's own name does. The third case is the one that bites: a sound outside
+// assets/sounds/ plays, but not the first time it is asked for, and nothing else
+// in the editor would ever tell you that.
+function streamHint(on, component) {
+  if (on) return 'Music and long sounds. Streamed, so nothing is held in memory.';
+  const file = resolveDeckFile(component?.file ?? '');
+  if (file && !isPreloadedPath(file)) {
+    return 'Short sfx. Move this file into assets/sounds/ to preload before first play, otherwise first play is silent.';
+  }
+  return 'Short sfx. Preloaded, so they fire instantly and overlap.';
+}
+
+function clamp(value, min, max, fallback) {
+  return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+
+function readSettings(props) {
+  return {
+    stream: Boolean(props.stream),
+    volume: clamp(props.volume, 0, 1, 1),
+    // The same ceiling the classic editor used: past 10x a sound is a click.
+    playbackRate: clamp(props.playbackRate, 0.01, 10, 1),
+    pan: clamp(props.pan, -1, 1, 0),
+    loop: Boolean(props.loop),
+  };
+}
+
+function applyStreamSettings(element, settings) {
+  element.volume = settings.volume;
+  // Not a plain assignment: an element time-stretches by default, so this is
+  // what makes `playbackRate` mean the same retune on both paths. See
+  // engine/media.js.
+  setMediaPlaybackRate(element, settings.playbackRate);
+  element.loop = settings.loop;
+  if (settings.pan !== 0) setMediaPan(element, settings.pan);
+}
+
+const warnedStreamOnly = new Set();
+function streamOnly(method) {
+  if (warnedStreamOnly.has(method)) return;
+  warnedStreamOnly.add(method);
+  console.warn(
+    `[SoundPlayer] ${method}() needs "stream" on -- a decoded sound has no playhead to hold. Ignored.`
+  );
+}
+
+// Asking the pool for this actor's element EVERY frame is what keeps it alive:
+// an entry nobody asks for is reaped as a despawned actor's leftovers (see
+// engine/media.js). Skipping the ask on frames where the handle already matched
+// meant a track went on sounding while its entry was reaped out from under the
+// pool, past the reach of `stopAll`.
+//
+// A different file is a different pool entry, so comparing elements is also how
+// a changed `file` prop gets a new handle.
+function streamHandleFor(actorId, file, settings, previous) {
+  const element = mediaElement(actorId, 'audio', file);
+  if (!element) return null;
+  // Props are live: turning the volume down or the pitch up in the inspector
+  // takes effect on the sound already playing.
+  applyStreamSettings(element, settings);
+  if (previous && previous.element === element) {
+    previous.settings = settings;
+    return previous;
+  }
+  return makeStreamHandle(file, element, settings);
+}
+
+function bufferHandleFor(file, settings, previous) {
+  if (previous && !previous.stream && previous.file === file) {
+    previous.settings = settings;
+    return previous;
+  }
+  return makeBufferHandle(file, settings);
+}
+
+// The <audio> handle: one element, reused. `play()` resolves when the sound ends,
+// so a behavior can `await` one before doing the next thing. A looping sound
+// resolves right away rather than never -- awaiting something that by definition
+// doesn't end would hang the caller forever, and that is never what was meant.
+function makeStreamHandle(file, element, settings) {
+  const handle = {
+    file,
+    stream: true,
+    settings,
+    element,
+    play() {
+      applyStreamSettings(element, handle.settings);
+      try {
+        element.currentTime = 0;
+      } catch {
+        // Not seekable yet (still loading) -- it plays from the start anyway.
+      }
+      playMedia(element);
+      if (handle.settings.loop) return Promise.resolve();
+      return new Promise((resolve) => {
+        const done = () => resolve();
+        element.addEventListener('ended', done, { once: true });
+        element.addEventListener('error', done, { once: true });
+      });
+    },
+    resume() {
+      playMedia(element);
+    },
+    pause() {
+      element.pause();
+    },
+    stop() {
+      stopMedia(element);
+    },
+    get playing() {
+      return !element.paused;
+    },
+  };
+  return handle;
+}
+
+// The decoded handle: every `play()` is its own voice, so they overlap. `stop()`
+// stops the one most recently started -- the others are already on their way out,
+// and `scene.sound.stopAll()` is the blunt instrument for all of them at once.
+//
+// `play()` resolves immediately when nothing played: an unknown file, or a sound
+// still decoding. Never hanging is the point -- see playSound in engine/sound.js.
+function makeBufferHandle(file, settings) {
+  const handle = {
+    file,
+    stream: false,
+    settings,
+    element: null,
+    voice: null,
+    play() {
+      const s = handle.settings;
+      const voice = playSound(file, { volume: s.volume, pan: s.pan, playbackRate: s.playbackRate });
+      handle.voice = voice;
+      if (!voice) return Promise.resolve();
+      void voice.finished.then(() => {
+        if (handle.voice === voice) handle.voice = null;
+      });
+      return voice.finished;
+    },
+    resume() {
+      streamOnly('resume');
+    },
+    pause() {
+      streamOnly('pause');
+    },
+    stop() {
+      handle.voice?.stop();
+      handle.voice = null;
+    },
+    get playing() {
+      return handle.voice !== null;
+    },
+  };
+  return handle;
+}

package/kits/physics-2d/behaviors/Sprite.jsx

@@ -4,7 +4,7 @@ import { artFrameCount, isImageArt, renderArtFrame } from '../engine/art';
 import { isVectorRenderer } from '../engine/pxart';
 import { renderSmoothCompositeFrame, renderSmoothSpriteFrame } from '../engine/pxartSmooth';
 import { spriteDestRect } from '../engine/spriteGeometry';
-import { Panel, SelectField } from '../engine/ui';
+import { FileField, Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
 import { parseTint, tintCanvas } from './tint';
 
@@ -163,11 +163,11 @@ export class Sprite {
     const spriteFiles = getSpriteFiles(sprites);
     return (
       <Panel title="Sprite" overridden={override?.anyOverridden()}>
-        <SelectField
+        <FileField
           label="File"
           value={component.file}
           onChange={(file) => setComponent({ file })}
-          options={spriteFiles}
+          files={spriteFiles}
           {...overrideProps(override, 'file')}
         />
         <SelectField

package/kits/physics-2d/behaviors/Video.jsx

@@ -3,7 +3,7 @@ import React from 'react';
 import { mediaElement, playMedia, stopMedia } from '../engine/media';
 import { mediaFilesOfKind } from '../engine/files';
 import { spriteDestRect } from '../engine/spriteGeometry';
-import { Panel, SelectField } from '../engine/ui';
+import { FileField, Panel, SelectField } from '../engine/ui';
 import { AutoFields, overrideProps } from '../engine/autoInspector';
 import { UNIT } from '../engine/propertyRanges';
 
@@ -89,11 +89,12 @@ export class Video {
   static Inspector({ component, setComponent, override }) {
     return (
       <Panel title="Video" overridden={override?.anyOverridden()}>
-        <SelectField
+        <FileField
           label="File"
           value={component.file}
           onChange={(file) => setComponent({ file })}
-          options={mediaFilesOfKind('video')}
+          files={mediaFilesOfKind('video')}
+          allowEmpty
           {...overrideProps(override, 'file')}
         />
         <SelectField

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

@@ -131,5 +131,5 @@
   "main": "main.jsx",
   "autoUpdateWhenImported": true,
   "title": "physics-2d",
-  "publishedVersion": "2026-08-18T21:05:46.663Z"
+  "publishedVersion": "2026-08-21T22:11:52.086Z"
 }

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

@@ -1,26 +1,35 @@
 import React from 'react';
 import { Lifecycle } from 'castle-web-sdk';
-import { parseJsonFile } from '../engine/files';
-import { useLiveDeckFiles } from '../engine/liveReload';
+import { initialFiles, parseJsonFile } from '../engine/files';
 import { collectAssets } from '../engine/assets';
 import { ScenePlayer } from '../engine/ScenePlayer';
 import { behaviorClasses } from './behaviorRegistry';
 // Play-mode entry point. Plays the scene named by `?scene=<path>` (the shell's
 // Play panel sets this), defaulting to `scenes/main.scene`. It renders ONLY the
 // game — the scene picker lives in the Play panel chrome (the shell), not here,
-// so nothing floats over the game surface and steals input. Files are live:
-// scene/drawing edits re-key the player against fresh data.
+// so nothing floats over the game surface and steals input.
+//
+// Nothing is folded into a run in progress -- not a drawing, not a scene. A
+// file changing on disk can always have altered how the run would have gone up
+// to this point, so applying one mid-run shows a state the deck could never
+// have reached.
+//
+// Getting current is therefore always a whole-panel reload, and the shell owns
+// when: it reloads Play on arrival if changes landed while it was hidden, and
+// offers the restart button when it is the panel you are looking at. A reload
+// remounts this and re-runs the build-time glob, so code and data arrive
+// together.
 const DEFAULT_SCENE = 'scenes/main.scene';
 
 export function PlayOnly({ initialScene } = {}) {
-  const { files, dataVersion } = useLiveDeckFiles();
+  const files = initialFiles;
   const scenePath = initialScene && files[initialScene] !== undefined ? initialScene : DEFAULT_SCENE;
   const { value: sceneData } = parseJsonFile(scenePath, files[scenePath] ?? '');
   if (!sceneData) return null;
   const { sprites } = collectAssets(files);
   return (
     <ScenePlayer
-      key={`${scenePath}:${dataVersion}`}
+      key={scenePath}
       sceneData={sceneData}
       sprites={sprites}
       files={files}