castle-web-cli 0.4.128 → 0.4.130

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

@@ -0,0 +1,316 @@
+// The deck's sound effects: audio files decoded into WebAudio buffers ahead of
+// time, then fired as overlapping one-shots from anywhere.
+//
+// This is the SFX half of the kit's audio. The other half is `engine/media.js`,
+// which plays an `<audio>` element -- the right thing for a long track, whose
+// decoded PCM would be tens of megabytes held in memory for as long as the deck
+// runs (a minute of 44.1kHz stereo is ~21MB). Short sounds go here, long ones
+// stream there, and `behaviors/SoundPlayer.jsx` is where a deck chooses.
+//
+// Deliberately decoupled from the rest of the kit: the file map arrives through
+// `initSounds` rather than being imported, and nothing here knows about actors,
+// scenes or blueprints. The one kit import is the shared AudioContext, which has
+// to be shared -- a second context could not mix with the element path. So
+// moving this into the SDK or a package other kits can use is a file move, not a
+// rewrite.
+//
+// A context starts SUSPENDED until the page has been interacted with, but
+// decoding does not need a running one, so preloading begins at load and only
+// playback waits for the unlock (see engine/audioContext.js).
+
+import { bindAudioResume, getAudioContext, resumeAudioContext } from './audioContext';
+
+// Generous on purpose: a voice is ~3 nodes, so this is a backstop against a
+// runaway loop, not a mixing decision. Sounds stack and clip if a deck asks them
+// to -- that is the deck's business.
+const MAX_VOICES = 128;
+
+// Preloaded sounds live here, in the deck's own tree or an import's (so a kit
+// can ship its own effects). Everything else in the deck is still playable and
+// still listed in the inspector -- this decides what is held in memory, not what
+// exists. Keeping it a DIRECTORY rather than a size cutoff means the answer is
+// visible in the file tree instead of buried in a constant here.
+const PRELOAD_DIR = /^(?:imports\/[^/]+\/)?assets\/sounds\//;
+
+// Where an import's files live at the deck root, mirroring castle-web-sdk's
+// IMPORTS_DIR. Spelled out rather than imported so this module keeps depending on
+// nothing but the shared AudioContext.
+const IMPORTS_PREFIX = 'imports/';
+const isImported = (path) => path.startsWith(IMPORTS_PREFIX);
+
+// A preloaded sound longer than this is probably meant to stream. Warned about,
+// never excluded: what preloads is the file tree's business, and a rule that
+// silently dropped a file would be exactly the hidden internal the directory
+// convention exists to avoid.
+const LONG_SOUND_SECONDS = 15;
+
+const DEV = Boolean(import.meta.env?.DEV);
+
+let media = {};
+let stems = new Map();
+const buffers = new Map();
+const loading = new Map();
+// Insertion-ordered, which is what makes the cap's "steal the oldest" a lookup
+// rather than a search.
+const voices = new Set();
+const preloadSet = new Set();
+const warned = new Set();
+let master = null;
+let ready = null;
+let preloaded = false;
+
+function warnOnce(key, message) {
+  if (!DEV || warned.has(key)) return;
+  warned.add(key);
+  console.warn(`[sound] ${message}`);
+}
+
+function clamp(value, min, max, fallback) {
+  return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : fallback;
+}
+
+// Stems within one deck: `hit` for `assets/sounds/hit.wav`. A stem shared by two
+// of that deck's files resolves to NEITHER -- picking one arbitrarily would make
+// the winner a function of sort order, which the deck author cannot see. The full
+// path always works and is how such a pair is told apart.
+function uniqueStems(paths, ambiguous) {
+  const found = new Map();
+  for (const path of paths) {
+    const stem = path.slice(path.lastIndexOf('/') + 1).replace(/\.[^.]+$/, '');
+    if (found.has(stem)) ambiguous.add(stem);
+    else found.set(stem, path);
+  }
+  for (const stem of ambiguous) found.delete(stem);
+  return found;
+}
+
+// Short names for sounds, resolved deck-first: a sound the deck owns beats one of
+// the same name from an import, the same precedence editors/behaviorRegistry.js
+// gives a deck's behaviors over a dependency's. Without that, a kit that shipped
+// its own `click.wav` would make every importing deck's `play('click')` ambiguous
+// -- a kit could break decks by adding a file.
+function buildStems(paths) {
+  const ownAmbiguous = new Set();
+  const importAmbiguous = new Set();
+  const imported = uniqueStems(paths.filter(isImported), importAmbiguous);
+  const own = uniqueStems(paths.filter((path) => !isImported(path)), ownAmbiguous);
+  const merged = new Map([...imported, ...own]);
+  for (const stem of ownAmbiguous) {
+    merged.delete(stem);
+    warnOnce(`stem:${stem}`, `This deck has more than one sound named "${stem}" -- play it by full path instead.`);
+  }
+  for (const stem of importAmbiguous) {
+    if (own.has(stem)) continue;
+    merged.delete(stem);
+    warnOnce(`stem:${stem}`, `An import has more than one sound named "${stem}" -- play it by full path instead.`);
+  }
+  return merged;
+}
+
+function resolvePath(name) {
+  const key = typeof name === 'string' ? name.replace(/^\.\//, '') : '';
+  if (media[key]) return key;
+  return stems.get(key) ?? null;
+}
+
+// Everything is mixed through one gain node, so a master volume and a fade on
+// stop have somewhere to live later. Unity, and no compressor: a deck that
+// stacks forty copies of one sample is meant to clip.
+function masterGain() {
+  const ctx = getAudioContext();
+  if (!ctx) return null;
+  if (!master || master.context !== ctx) {
+    master = ctx.createGain();
+    master.gain.value = 1;
+    master.connect(ctx.destination);
+  }
+  return master;
+}
+
+async function decode(path) {
+  const url = media[path];
+  const ctx = getAudioContext();
+  if (!url || !ctx) return null;
+  try {
+    const response = await fetch(url);
+    const buffer = await ctx.decodeAudioData(await response.arrayBuffer());
+    buffers.set(path, buffer);
+    return buffer;
+  } catch (error) {
+    warnOnce(`decode:${path}`, `Could not decode ${path}: ${error?.message ?? error}`);
+    return null;
+  }
+}
+
+// One decode per file, however many callers ask at once -- two `play`s of an
+// unloaded sound in the same frame must not decode it twice.
+function load(path) {
+  if (buffers.has(path)) return Promise.resolve(buffers.get(path));
+  const inFlight = loading.get(path);
+  if (inFlight) return inFlight;
+  const started = decode(path).finally(() => loading.delete(path));
+  loading.set(path, started);
+  return started;
+}
+
+async function preload(path) {
+  const buffer = await load(path);
+  if (buffer && buffer.duration > LONG_SOUND_SECONDS) {
+    warnOnce(
+      `long:${path}`,
+      `${path} is ${Math.round(buffer.duration)}s and is held decoded in memory. ` +
+        `Long tracks belong outside assets/sounds/, played by a SoundPlayer with stream on.`
+    );
+  }
+}
+
+/** Whether a deck path is one this library preloads. */
+export function isPreloadedPath(path) {
+  return PRELOAD_DIR.test(String(path ?? ''));
+}
+
+/**
+ * Point the library at the deck's audio files and start preloading.
+ *
+ * @param audioFiles path -> URL, every audio file in the deck (see
+ *   engine/files.js -- URLs, not paths, so this keeps working once the deck is
+ *   bundled into a single file and the assets are `data:` URIs).
+ */
+export function initSounds(audioFiles) {
+  media = { ...audioFiles };
+  stems = buildStems(Object.keys(media));
+  preloadSet.clear();
+  for (const path of Object.keys(media)) {
+    if (PRELOAD_DIR.test(path)) preloadSet.add(path);
+  }
+  // No sounds to preload means no AudioContext either: a deck that makes no
+  // sound should not build an audio graph just by loading the kit.
+  if (preloadSet.size === 0) {
+    preloaded = true;
+    ready = Promise.resolve();
+    return ready;
+  }
+  ready = Promise.all([...preloadSet].map(preload)).then(() => {
+    preloaded = true;
+  });
+  return ready;
+}
+
+function stopVoice(voice) {
+  voices.delete(voice);
+  try {
+    voice.source.stop();
+  } catch {
+    // Already ended -- `ended` has fired or the source never started.
+  }
+}
+
+function startVoice(buffer, { volume, pan, playbackRate }) {
+  const ctx = getAudioContext();
+  const out = masterGain();
+  if (!ctx || !out) return null;
+  // The context starts suspended until the page has been interacted with. This
+  // asks now, and binds a listener so the next gesture asks again -- a deck with
+  // no streaming sound has nothing else that would.
+  bindAudioResume();
+  resumeAudioContext();
+  if (voices.size >= MAX_VOICES) stopVoice(voices.values().next().value);
+
+  const source = ctx.createBufferSource();
+  source.buffer = buffer;
+  source.playbackRate.value = clamp(playbackRate, 0.01, 10, 1);
+  const gain = ctx.createGain();
+  gain.gain.value = clamp(volume, 0, 1, 1);
+  source.connect(gain);
+  let tail = gain;
+  const wanted = clamp(pan, -1, 1, 0);
+  if (wanted !== 0 && ctx.createStereoPanner) {
+    const panner = ctx.createStereoPanner();
+    panner.pan.value = wanted;
+    gain.connect(panner);
+    tail = panner;
+  }
+  tail.connect(out);
+
+  const voice = { source };
+  voices.add(voice);
+  const finished = new Promise((resolve) => {
+    source.addEventListener('ended', () => {
+      voices.delete(voice);
+      resolve();
+    });
+  });
+  source.start();
+  return {
+    stop() {
+      stopVoice(voice);
+    },
+    finished,
+  };
+}
+
+/**
+ * Play a sound, overlapping whatever else is playing.
+ *
+ * `name` is a deck-relative path (`assets/sounds/hit.wav`) or the bare filename
+ * without its extension (`hit`).
+ *
+ * Returns `{ stop, finished }`, or null when nothing played -- an unknown name,
+ * or a sound whose buffer is not decoded yet. A play that lands before its sound
+ * is ready is DROPPED rather than deferred: a sound effect that arrives late is
+ * worse than one that never arrives, and deferring it would fire it at a moment
+ * that has already passed.
+ */
+export function playSound(name, { volume = 1, pan = 0, playbackRate = 1 } = {}) {
+  const path = resolvePath(name);
+  if (!path) {
+    warnOnce(`unknown:${name}`, `No sound named "${name}".`);
+    return null;
+  }
+  const buffer = buffers.get(path);
+  if (buffer) return startVoice(buffer, { volume, pan, playbackRate });
+  // Not decoded. Start it now so the NEXT play works -- which for a sound
+  // outside assets/sounds/ is what makes the first play the only silent one.
+  void load(path);
+  if (!preloadSet.has(path)) {
+    warnOnce(
+      `cold:${path}`,
+      `${path} is not preloaded, so this first play is silent. ` +
+        `Move it under assets/sounds/ to have it ready before the deck starts.`
+    );
+  }
+  return null;
+}
+
+/** Every sound effect, off. Long tracks are the element path's to stop. */
+export function stopAllSounds() {
+  for (const voice of [...voices]) stopVoice(voice);
+  voices.clear();
+}
+
+// The deck-facing library, also reachable as `scene.sound` (see systems/media.js)
+// so a behavior needs no import to make a noise.
+export const Sound = {
+  /** True once every preloaded sound has been decoded (or failed to). */
+  get isLoaded() {
+    return preloaded;
+  },
+  /** Resolves when preloading settles, so a caller need not poll `isLoaded`. */
+  get whenLoaded() {
+    return ready ?? Promise.resolve();
+  },
+  /** Whether a name resolves to a sound this deck has. */
+  has(name) {
+    return resolvePath(name) !== null;
+  },
+  /**
+   * How many voices are sounding right now. Worth watching if effects seem to
+   * cut each other off: at MAX_VOICES the oldest is stolen to make room, and
+   * nothing else says so.
+   */
+  get voiceCount() {
+    return voices.size;
+  },
+  play: playSound,
+  stopAll: stopAllSounds,
+};

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

@@ -3,7 +3,7 @@
 // SceneRuntime (see engine/scene.js `makeScene`) to register itself via
 // `runtime.registerSystem(...)`. A system is a plain object with an optional
 // `afterBehaviors(scene, dt)` hook, run once per frame after all behavior
-// updates. Empty in a kit with no `systems/` dir (e.g. basic-2d); a kit adds a
+// updates. Empty in a kit with no `systems/` dir; a kit adds a
 // system by dropping a file here -- no edits to the engine required. Symmetric
 // with editors/behaviorRegistry.js.
 // Root-anchored, deck + imports (see engine/files.js).

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

@@ -627,15 +627,35 @@ export function CheckboxField({ label, checked, onChange, overridden, defaultVal
     <FieldRow label={label} overridden={overridden} defaultValue={defaultValue} onReset={onReset}>
       <button
         type="button"
-        className={cx(styles.toggle, checked && styles.toggleOn)}
-        role="switch"
+        className={cx(styles.checkbox, checked && styles.checkboxOn)}
+        role="checkbox"
         aria-checked={!!checked}
         onClick={() => onChange(!checked)}>
-        <span className={styles.toggleKnob} />
+        <svg className={styles.checkboxMark} viewBox="0 0 12 12" aria-hidden="true">
+          <path
+            d="M2 6.2L4.8 9 10 3"
+            fill="none"
+            stroke="currentColor"
+            strokeWidth="1.8"
+            strokeLinecap="round"
+            strokeLinejoin="round"
+          />
+        </svg>
       </button>
     </FieldRow>
   );
 }
+// Explanatory text under a field, for a prop whose name doesn't carry its
+// meaning. Rendered inside the panel's field grid, so it lands under the control
+// rather than under the label.
+export function FieldNote({ children }) {
+  if (!children) return null;
+  return (
+    <div className={styles.fieldNote}>
+      <div className={styles.fieldNoteInner}>{children}</div>
+    </div>
+  );
+}
 export function ColorField({ label, value, onChange, overridden, defaultValue, onReset }) {
   const hex = normalizeHex(value);
   const alpha = hex.length === 9 ? hex.slice(7) : '';
@@ -720,8 +740,8 @@ function settleSheet(drag, setHeight, expandedRef) {
   const settled = setHeight(drag.startHeight - (drag.lastY - drag.startY));
   if (settled > peek + 2) expandedRef.current = settled;
 }
-// Persist a sheet's resting height across reloads (an agent's CODE edit
-// triggers requestReload, which would otherwise reset every sheet to the
+// Persist a sheet's resting height across reloads (picking up a code change
+// means reloading the panel, which would otherwise reset every sheet to the
 // default size). Keyed per sheet via `storageKey`; sessionStorage-scoped and
 // best-effort, the same degrade-to-memory-only contract as editorHistory.
 function sheetHeightStorageKey(key) {
@@ -947,3 +967,252 @@ export function SelectField({ label, value, onChange, options, overridden, defau
     </FieldRow>
   );
 }
+
+function basenameOf(path) {
+  if (!path) return '';
+  return path.slice(path.lastIndexOf('/') + 1);
+}
+
+let measureCanvasCtx;
+function measureTextWidth(text, font) {
+  if (!measureCanvasCtx) {
+    measureCanvasCtx = document.createElement('canvas').getContext('2d');
+  }
+  measureCanvasCtx.font = font;
+  return measureCanvasCtx.measureText(text).width;
+}
+
+// Keep the filename intact; the directory is what yields. Binary-search the
+// prefix of the directory until `{prefix}…/{basename}` fits `maxWidth`.
+function fitPathKeepBasename(path, maxWidth, font) {
+  const measure = (text) => measureTextWidth(text, font);
+  if (maxWidth <= 0 || measure(path) <= maxWidth) return path;
+  const slash = path.lastIndexOf('/');
+  const dir = slash > 0 ? path.slice(0, slash) : '';
+  const base = slash > 0 ? path.slice(slash + 1) : path;
+  const ellipsed = `…/${base}`;
+  if (!dir || measure(ellipsed) > maxWidth) return fitKeepEnd(base, maxWidth, measure);
+  let lo = 0;
+  let hi = dir.length;
+  let best = ellipsed;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const candidate = `${dir.slice(0, mid)}…/${base}`;
+    if (measure(candidate) <= maxWidth) {
+      best = candidate;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return best;
+}
+
+function fitKeepEnd(text, maxWidth, measure) {
+  if (measure(text) <= maxWidth) return text;
+  if (measure('…') > maxWidth) return '';
+  let lo = 0;
+  let hi = text.length;
+  let best = '…';
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const candidate = `…${text.slice(text.length - mid)}`;
+    if (measure(candidate) <= maxWidth) {
+      best = candidate;
+      lo = mid + 1;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  return best;
+}
+
+function FilePathLabel({ path }) {
+  const ref = useRef(null);
+  const [shown, setShown] = useState(path);
+  useLayoutEffect(() => {
+    const node = ref.current;
+    if (!node) return undefined;
+    function fit() {
+      const max = node.clientWidth;
+      if (max <= 0) return;
+      const cs = getComputedStyle(node);
+      const font = cs.font && cs.font !== '0px' ? cs.font : `${cs.fontWeight} ${cs.fontSize} ${cs.fontFamily}`;
+      setShown(fitPathKeepBasename(path, max, font));
+    }
+    fit();
+    const observer = new ResizeObserver(fit);
+    observer.observe(node);
+    return () => observer.disconnect();
+  }, [path]);
+  return (
+    <span ref={ref} className={styles.filePickerPath} title={path}>
+      {shown}
+    </span>
+  );
+}
+
+function pickerRowChrome(list) {
+  if (!list) return 26;
+  const box = getComputedStyle(list);
+  const opt = list.querySelector('button');
+  const op = opt ? getComputedStyle(opt) : null;
+  return (
+    (parseFloat(box.paddingLeft) || 0) +
+    (parseFloat(box.paddingRight) || 0) +
+    (parseFloat(box.borderLeftWidth) || 0) +
+    (parseFloat(box.borderRightWidth) || 0) +
+    (op ? (parseFloat(op.paddingLeft) || 0) + (parseFloat(op.paddingRight) || 0) : 16)
+  );
+}
+
+function longestPathWidth(list, paths) {
+  if (!list || !paths.length) return 0;
+  const probe = document.createElement('span');
+  probe.style.cssText = 'position:absolute;left:-9999px;white-space:nowrap;pointer-events:none;';
+  const opt = list.querySelector('button');
+  if (opt) {
+    const s = getComputedStyle(opt);
+    probe.style.font = s.font && s.font !== '0px' ? s.font : `${s.fontWeight} ${s.fontSize} ${s.fontFamily}`;
+  }
+  list.appendChild(probe);
+  let max = 0;
+  for (const path of paths) {
+    probe.textContent = path || 'None';
+    max = Math.max(max, probe.offsetWidth);
+  }
+  probe.remove();
+  return max;
+}
+
+// File path field. Closed chrome shows the basename; the open list shows full
+// paths. Callers pass the candidate paths — this does not decide what a sprite
+// or sound is. `allowEmpty` adds a None row that writes ''.
+export function FileField({
+  label,
+  value,
+  onChange,
+  files = [],
+  allowEmpty = false,
+  overridden,
+  defaultValue,
+  onReset,
+}) {
+  const current = value ?? '';
+  const [open, setOpen] = useState(false);
+  const buttonRef = useRef(null);
+  const listRef = useRef(null);
+  const [pos, setPos] = useState(null);
+
+  const paths = [];
+  if (allowEmpty) paths.push('');
+  for (const path of files) {
+    if (path && !paths.includes(path)) paths.push(path);
+  }
+  if (current && !paths.includes(current)) paths.splice(allowEmpty ? 1 : 0, 0, current);
+
+  useLayoutEffect(() => {
+    if (!open || !buttonRef.current) return undefined;
+    function place() {
+      const anchor = buttonRef.current.getBoundingClientRect();
+      const list = listRef.current;
+      const margin = 8;
+      const maxWidth = window.innerWidth - margin * 2;
+      const needed = longestPathWidth(list, paths) + pickerRowChrome(list) + 4;
+      const width = Math.min(Math.max(needed, anchor.width), maxWidth);
+      // Grow left from the field if the paths need more than the control width.
+      let left = anchor.right - width;
+      if (left < margin) left = margin;
+      if (left + width > window.innerWidth - margin) {
+        left = Math.max(margin, window.innerWidth - width - margin);
+      }
+      const gap = 4;
+      const height = list?.getBoundingClientRect().height ?? 0;
+      let top = anchor.bottom + gap;
+      if (height && top + height > window.innerHeight - margin) {
+        top = Math.max(margin, anchor.top - gap - height);
+      }
+      setPos({ top, left, width });
+    }
+    place();
+    window.addEventListener('resize', place);
+    window.addEventListener('scroll', place, true);
+    return () => {
+      window.removeEventListener('resize', place);
+      window.removeEventListener('scroll', place, true);
+    };
+  }, [open, paths.length]);
+
+  useEffect(() => {
+    if (!open) return undefined;
+    function onKeyDown(event) {
+      if (event.key === 'Escape') setOpen(false);
+    }
+    function onPointerDown(event) {
+      if (listRef.current?.contains(event.target) || buttonRef.current?.contains(event.target)) {
+        return;
+      }
+      setOpen(false);
+    }
+    window.addEventListener('keydown', onKeyDown);
+    window.addEventListener('pointerdown', onPointerDown);
+    return () => {
+      window.removeEventListener('keydown', onKeyDown);
+      window.removeEventListener('pointerdown', onPointerDown);
+    };
+  }, [open]);
+
+  return (
+    <FieldRow
+      label={label}
+      overridden={overridden}
+      defaultValue={defaultValue ? basenameOf(defaultValue) : defaultValue}
+      onReset={onReset}>
+      <button
+        ref={buttonRef}
+        type="button"
+        className={cx(styles.select, styles.fileField)}
+        aria-haspopup="listbox"
+        aria-expanded={open}
+        onClick={() => setOpen((next) => !next)}>
+        <span className={cx(styles.fileFieldLabel, !current && styles.fileFieldEmpty)}>
+          {current ? basenameOf(current) : 'None'}
+        </span>
+      </button>
+      {open
+        ? createPortal(
+            <div
+              ref={listRef}
+              className={styles.filePicker}
+              role="listbox"
+              aria-label={label}
+              style={pos ?? { visibility: 'hidden' }}>
+              {paths.map((path) => {
+                const selected = path === current;
+                return (
+                  <button
+                    key={path || '__none'}
+                    type="button"
+                    role="option"
+                    aria-selected={selected}
+                    className={cx(
+                      styles.filePickerOption,
+                      selected && styles.filePickerOptionSelected,
+                      !path && styles.fileFieldEmpty
+                    )}
+                    title={path || 'None'}
+                    onClick={() => {
+                      onChange(path);
+                      setOpen(false);
+                    }}>
+                    {path ? <FilePathLabel path={path} /> : 'None'}
+                  </button>
+                );
+              })}
+            </div>,
+            document.body
+          )
+        : null}
+    </FieldRow>
+  );
+}