castle-web-cli 0.4.128 → 0.4.129

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

@@ -22,7 +22,7 @@ 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`.
@@ -174,25 +174,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,
@@ -491,6 +508,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-20T22:15:34.812Z"
 }

package/kits/physics-2d/engine/audioContext.js

@@ -32,3 +32,44 @@ export function resumeAudioContext() {
     });
   }
 }
+
+// Where a gesture that could unlock audio might land. This deck's own window
+// always -- plus the EDITOR's, because there the deck runs inside a panel iframe
+// and a click on the editor's own chrome (its Play button, a file, an inspector
+// field) is a gesture the browser grants this frame but that this frame never
+// hears about. Without the parent, a deck's first sound stays queued until the
+// player happens to click the game itself, which in the editor reads as sound
+// being broken.
+//
+// Measured rather than assumed: a same-origin parent's pointerdown both fires
+// here AND satisfies the autoplay policy, so the queued sound really does start.
+//
+// A published deck's parent is a Castle host on another origin. Touching it
+// throws, there is nothing to listen to, and the deck's own window is the whole
+// answer -- which is why this is a try/catch rather than a capability check.
+export function unlockTargets() {
+  const targets = [window];
+  try {
+    const parent = window.parent;
+    if (parent && parent !== window && parent.document) targets.push(parent);
+  } catch {
+    // Cross-origin parent: embedded by a host rather than open in the editor.
+  }
+  return targets;
+}
+
+let resumeBound = false;
+
+// Resume the context on the first gesture, wherever it lands. A deck that only
+// plays buffers never goes through engine/media.js, so this is what makes its
+// sound audible after the player finally taps: without it the context stays
+// suspended until some later play happens to call resume again, losing the one
+// in between. Idempotent, so callers need not track whether it ran.
+export function bindAudioResume() {
+  if (resumeBound || typeof window === 'undefined') return;
+  resumeBound = true;
+  for (const target of unlockTargets()) {
+    target.addEventListener('pointerdown', resumeAudioContext, { passive: true });
+    target.addEventListener('keydown', resumeAudioContext, { passive: true });
+  }
+}

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { CheckboxField, ColorField, NumberField, Panel, TextField, isHexColor } from './ui';
+import { CheckboxField, ColorField, FieldNote, NumberField, Panel, TextField, isHexColor } from './ui';
 // Build the override-indicator field props (purple tint + "Default: X [Reset]")
 // for a single property from a behavior panel's override context. Returns an
 // empty object when there's no context (blueprint template editing) or the
@@ -17,6 +17,43 @@ export function overrideProps(override, prop) {
 // defaults -- which are an unbounded scrubber stepping by whole numbers, wrong
 // for anything that lives in 0..1. Declaring BOTH min and max makes it a true
 // slider (fill + thumb). Props that declare nothing are unchanged.
+//
+// Any prop can also declare `hint`, a line of explanation shown under the field.
+// As a function it receives the prop's current value and the whole component, so
+// a hint can say what the CURRENT setting means rather than describing both
+// halves of a toggle at once -- which is the only way a one-line note beats the
+// prop's own name.
+function fieldFor({ label, current, set, sample, entry, ov }) {
+  if (typeof sample === 'number') {
+    const { min, max, step } = entry ?? {};
+    return (
+      <NumberField
+        label={label}
+        value={current}
+        onChange={set}
+        {...(min == null ? {} : { min })}
+        {...(max == null ? {} : { max })}
+        {...(step == null ? {} : { step })}
+        {...ov}
+      />
+    );
+  }
+  if (typeof sample === 'boolean') {
+    return <CheckboxField label={label} checked={current} onChange={set} {...ov} />;
+  }
+  if (isHexColor(sample)) {
+    return <ColorField label={label} value={current} onChange={set} {...ov} />;
+  }
+  return (
+    <TextField label={label} value={current == null ? '' : String(current)} onChange={set} {...ov} />
+  );
+}
+
+function hintFor(entry, current, component) {
+  if (typeof entry?.hint === 'function') return entry.hint(current, component);
+  return entry?.hint ?? null;
+}
+
 export function AutoFields({ defaultProps, component, setComponent, only, exclude, override, meta }) {
   const keys = Object.keys(defaultProps).filter((key) => {
     if (only) return only.includes(key);
@@ -28,39 +65,19 @@ export function AutoFields({ defaultProps, component, setComponent, only, exclud
       {keys.map((key) => {
         const fallback = defaultProps[key];
         const current = key in component ? component[key] : fallback;
-        const set = (value) => setComponent({ [key]: value });
-        const label = humanizeKey(key);
-        const sample = fallback ?? current;
-        const ov = overrideProps(override, key);
-        if (typeof sample === 'number') {
-          const { min, max, step } = meta?.[key] ?? {};
-          return (
-            <NumberField
-              key={key}
-              label={label}
-              value={current}
-              onChange={set}
-              {...(min == null ? {} : { min })}
-              {...(max == null ? {} : { max })}
-              {...(step == null ? {} : { step })}
-              {...ov}
-            />
-          );
-        }
-        if (typeof sample === 'boolean') {
-          return <CheckboxField key={key} label={label} checked={current} onChange={set} {...ov} />;
-        }
-        if (isHexColor(sample)) {
-          return <ColorField key={key} label={label} value={current} onChange={set} {...ov} />;
-        }
+        const entry = meta?.[key];
         return (
-          <TextField
-            key={key}
-            label={label}
-            value={current == null ? '' : String(current)}
-            onChange={set}
-            {...ov}
-          />
+          <React.Fragment key={key}>
+            {fieldFor({
+              label: humanizeKey(key),
+              current,
+              set: (value) => setComponent({ [key]: value }),
+              sample: fallback ?? current,
+              entry,
+              ov: overrideProps(override, key),
+            })}
+            <FieldNote>{hintFor(entry, current, component)}</FieldNote>
+          </React.Fragment>
         );
       })}
     </>