castle-web-cli 0.4.128 → 0.4.130

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

@@ -146,7 +146,7 @@ function useResizableTimelineHeight() {
 // the top, Aseprite-style) by frame COLUMNS, with thumbnails per cell, layer +
 // frame controls, linked-cell affordances, onion-skin toggles, playback, and a
 // tags editor. All mutation flows through `actions` (wired in PxArtEditor).
-export function PxArtTimeline({ sprite, text, selection, playing, onion, actions }) {
+export function PxArtTimeline({ sprite, text, selection, playing, onion, actions, readOnly = false }) {
   // Hooks run unconditionally (order-stable); only the render branches on viewport.
   const compact = useCompactViewport();
   const resizable = useResizableTimelineHeight();
@@ -159,7 +159,13 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
   });
   const grid = (
     <div className={tl.scroll}>
-      <TimelineGrid sprite={sprite} text={text} selection={selection} actions={actions} />
+      <TimelineGrid
+        sprite={sprite}
+        text={text}
+        selection={selection}
+        actions={actions}
+        readOnly={readOnly}
+      />
     </div>
   );
   if (compact) {
@@ -178,6 +184,7 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
           playing={playing}
           onion={onion}
           actions={actions}
+          readOnly={readOnly}
         />
         {grid}
       </section>
@@ -198,6 +205,7 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
         playing={playing}
         onion={onion}
         actions={actions}
+        readOnly={readOnly}
       />
       {grid}
       {SHOW_TAGS ? <TagsPanel sprite={sprite} actions={actions} /> : null}
@@ -211,7 +219,7 @@ export function PxArtTimeline({ sprite, text, selection, playing, onion, actions
 // (duplicate/move/delete/rename/link/unlink/visibility) lives in the right-click
 // context menus on the grid's layer rows, frame headers, and cells (see
 // TimelineGrid + ContextMenu).
-function TimelineBar({ sprite, selection, playing, onion, actions }) {
+function TimelineBar({ sprite, selection, playing, onion, actions, readOnly = false }) {
   const { layerIndex, frameIndex } = selection;
   // A single-frame sprite has no animation, so the three animation controls
   // (global duration, onion skin, play/pause) are meaningless — gate them on
@@ -227,19 +235,20 @@ function TimelineBar({ sprite, selection, playing, onion, actions }) {
   return (
     <div className={tl.bar}>
       <div className={tl.barGroup}>
-        <IconButton icon="grid" label="Pixel" onClick={() => actions.addLayer(layerIndex)} />
+        <IconButton icon="grid" label="Pixel" disabled={readOnly} onClick={() => actions.addLayer(layerIndex)} />
         <span className={tl.barLabel}>Pixel</span>
       </div>
       <div className={tl.barGroup}>
         <IconButton
           icon="draw-polygon"
           label="Path"
+          disabled={readOnly}
           onClick={() => actions.addLayer(layerIndex, 'path')}
         />
         <span className={tl.barLabel}>Path</span>
       </div>
       <div className={tl.barGroup}>
-        <IconButton icon="film" label="Frame" onClick={() => actions.addFrame(frameIndex)} />
+        <IconButton icon="film" label="Frame" disabled={readOnly} onClick={() => actions.addFrame(frameIndex)} />
         <span className={tl.barLabel}>Frame</span>
       </div>
       <div className={tl.barSpacer} />
@@ -249,7 +258,11 @@ function TimelineBar({ sprite, selection, playing, onion, actions }) {
             <span className={tl.durationIcon} title="Default frame duration (ms) — applies to all frames">
               <FaGlyph icon={faStopwatch} className={tl.durationGlyph} />
             </span>
-            <GlobalDurationInput value={sprite.defaultDurationMs} onCommit={actions.setDefaultDuration} />
+            <GlobalDurationInput
+              value={sprite.defaultDurationMs}
+              onCommit={actions.setDefaultDuration}
+              disabled={readOnly}
+            />
           </div>
           <OnionControls onion={onion} actions={actions} />
           <div className={tl.barGroup}>
@@ -268,12 +281,13 @@ function TimelineBar({ sprite, selection, playing, onion, actions }) {
 
 // The sprite's GLOBAL duration. Commits a finite, positive value on blur/Enter;
 // an empty/invalid entry snaps back to the current value (see CommitInput).
-function GlobalDurationInput({ value, onCommit }) {
+function GlobalDurationInput({ value, onCommit, disabled = false }) {
   return (
     <CommitInput
       text={String(value)}
       className={tl.globalDuration}
       title="Global frame duration (ms) — inherited by every frame without its own override"
+      disabled={disabled}
       onCommit={(draft) => {
         const ms = Number(draft);
         if (Number.isFinite(ms) && ms > 0) onCommit(ms);
@@ -322,7 +336,7 @@ function OnionControls({ onion, actions }) {
   );
 }
 
-function TimelineGrid({ sprite, text, selection, actions }) {
+function TimelineGrid({ sprite, text, selection, actions, readOnly = false }) {
   const frames = sprite.frames;
   // Render rows top-down: the last layer (top of the composite stack) first.
   const rows = sprite.layers.map((_, i) => i).reverse();
@@ -353,12 +367,13 @@ function TimelineGrid({ sprite, text, selection, actions }) {
   const openMenu = useCallback(
     (target, event) => {
       selectTarget(target);
+      if (readOnly) return;
       const rect = event.currentTarget?.getBoundingClientRect?.();
       const x = Number.isFinite(event.clientX) ? event.clientX : rect?.left + rect?.width / 2;
       const y = Number.isFinite(event.clientY) ? event.clientY : rect?.top + rect?.height / 2;
       setMenu({ ...target, x: x ?? 0, y: y ?? 0 });
     },
-    [selectTarget]
+    [selectTarget, readOnly]
   );
   const press = useTimelineItemPress(openMenu);
   const activateTarget = (target, event) => {
@@ -412,6 +427,7 @@ function TimelineGrid({ sprite, text, selection, actions }) {
             onPointerDown={(event) => press.onPointerDown(event, { kind: 'layer', layerIndex: li })}
             actions={actions}
             onContextMenu={openLayerMenu}
+            readOnly={readOnly}
           />
           {frames.map((_, f) => (
             <CellThumb
@@ -744,7 +760,7 @@ const kindBadgeStyle = {
 // on blur/Enter, re-syncing to `text` when idle. The caller's `onCommit(draft)`
 // interprets the raw string (set / clear / revert). Shared by the per-frame and
 // global duration fields so their edit/commit behavior stays identical.
-function CommitInput({ text, className, placeholder, title, onCommit }) {
+function CommitInput({ text, className, placeholder, title, onCommit, disabled = false }) {
   const [draft, setDraft] = useState(text);
   const editing = useRef(false);
   if (!editing.current && draft !== text) setDraft(text);
@@ -759,6 +775,7 @@ function CommitInput({ text, className, placeholder, title, onCommit }) {
       placeholder={placeholder}
       title={title}
       inputMode="numeric"
+      disabled={disabled}
       onFocus={() => (editing.current = true)}
       onChange={(event) => setDraft(event.target.value)}
       onBlur={commit}
@@ -807,7 +824,7 @@ function FaGlyph({ icon, className = tl.visGlyph }) {
   );
 }
 
-function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions, onContextMenu }) {
+function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions, onContextMenu, readOnly = false }) {
   return (
     <div
       className={active ? tl.layerHead + ' ' + tl.layerHeadActive : tl.layerHead}
@@ -832,6 +849,7 @@ function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions,
           max="100"
           value={Math.round(layer.opacity * 100)}
           title={`Opacity ${Math.round(layer.opacity * 100)}%`}
+          disabled={readOnly}
           onClick={(event) => event.stopPropagation()}
           onChange={(event) => actions.patchLayer(index, { opacity: Number(event.target.value) / 100 })}
         />

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

@@ -108,6 +108,12 @@
   text-align: center;
 }
 
+.globalDuration:disabled {
+  opacity: 0.55;
+  cursor: default;
+  color: var(--castle-inspector-muted);
+}
+
 /* Icon-only label (stopwatch) sitting next to the global duration input, in
    place of the old "Duration … ms · all frames" text. */
 .durationIcon {
@@ -333,6 +339,11 @@
   accent-color: var(--castle-selected);
 }
 
+.opacity:disabled {
+  opacity: 0.4;
+  cursor: default;
+}
+
 .opacity::-webkit-slider-runnable-track {
   height: 3px;
   border-radius: 2px;

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>
         );
       })}
     </>

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

@@ -69,13 +69,25 @@ function parseBlueprintText(text) {
 function resolveTemplateRefs(template, files, fromPath) {
   if (!template) return template;
   for (const props of Object.values(template.components ?? {})) {
-    for (const [key, value] of Object.entries(props ?? {})) {
-      if (typeof value !== 'string' || !value) continue;
+    resolveRefsIn(props, files, fromPath);
+  }
+  return template;
+}
+
+// Nested because a ref is not always a bare prop: `Shape.art` can be one string
+// for the whole shape OR an object naming a file per face, and an unresolved
+// face ref means an untextured surface with no error anywhere. Rewriting only
+// when the resolved path is actually in the file map is what keeps this from
+// mangling strings that were never refs.
+function resolveRefsIn(props, files, fromPath) {
+  for (const [key, value] of Object.entries(props ?? {})) {
+    if (typeof value === 'string' && value) {
       const resolved = resolveDeckFile(value, fromPath);
       if (resolved !== value && files?.[resolved] !== undefined) props[key] = resolved;
+    } else if (value && typeof value === 'object' && !Array.isArray(value)) {
+      resolveRefsIn(value, files, fromPath);
     }
   }
-  return template;
 }
 
 // Resolve a blueprint's template from the LIVE files map -- the load-bearing

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

@@ -1,13 +1,13 @@
-// Consumer side of the serve's `files_changed` broadcast. The engine decides
-// what a change means for this bundle:
-//   - data files (.scene / .pxart / .sprite / .style / .drawing) are re-read
-//     over the serve's files API and folded into React state — live re-render,
-//     no reload.
-//   - code the bundle imports (per the event's module-graph closure), html,
-//     or added/deleted code files (import.meta.glob may pick them up) mean
-//     this context is stale — requestReload() (save-state hooks run first).
+// Consumer side of the serve's `files_changed` broadcast. Data files are
+// re-read over the serve's files API and folded into React state, so an editor
+// shows a drawing someone else just changed without reloading anything.
+//
+// A CODE change does nothing here. Only a page reload picks up new code, and a
+// reload thrown at a panel someone is working in loses their place, so the
+// decision belongs to the person: every panel header carries a reload control,
+// and the shell offers the Play panel a restart when it has fallen behind.
 import { useEffect, useRef, useState } from 'react';
-import { onFilesChanged, requestReload } from 'castle-web-sdk';
+import { onFilesChanged } from 'castle-web-sdk';
 import { initialFiles } from './files';
 
 const DATA_EXTS = ['.scene', '.pxart', '.sprite', '.style', '.drawing'];
@@ -17,7 +17,20 @@ export function isDataFile(path) {
   return DATA_EXTS.some((ext) => path.endsWith(ext));
 }
 
-function needsContextReload(change) {
+// Which iframe is speaking -- every panel runs its own copy of this.
+function panelTag() {
+  try {
+    const q = new URLSearchParams(location.search);
+    return q.get('panel') || q.get('file') || 'deck';
+  } catch {
+    return 'deck';
+  }
+}
+
+// Whether a change means this bundle's code is stale. Only used for the log
+// line -- nothing acts on it -- but knowing a panel went stale and when is what
+// makes a vague "it looked wrong" report checkable against `.castle/serve.log`.
+function isCodeChange(change) {
   if (isDataFile(change.path)) return false;
   if (change.path.endsWith('.html')) return true;
   // In the module graph (directly or as someone's import) -> our code changed.
@@ -37,34 +50,34 @@ async function readDeckFile(path) {
 // Deck files as live state: starts from the build-time glob snapshot and stays
 // current as files change on disk from any source (editors, agents, terminal).
 // `shouldSkipPath` lets an editor keep its own in-flight edits from being
-// clobbered by the fs echo of a stale write. `dataVersion` bumps on every
-// applied data change — key a player on it to rebuild from fresh data.
+// clobbered by the fs echo of a stale write.
 export function useLiveDeckFiles({ shouldSkipPath } = {}) {
   const [files, setFiles] = useState(initialFiles);
-  const [dataVersion, setDataVersion] = useState(0);
   const skipRef = useRef(shouldSkipPath);
   skipRef.current = shouldSkipPath;
 
   useEffect(
     () =>
       onFilesChanged((event) => {
-        if (event.changes.some(needsContextReload)) {
-          requestReload();
-          return;
-        }
+        const stale = event.changes.find(isCodeChange);
+        if (stale) console.log(`[reload] ${panelTag()} code stale <- ${stale.path}`);
+        // Data still applies in the same event: a change that carries both is
+        // one edit, and holding the data back would leave the panel showing
+        // neither the old state nor the new one.
         const dataChanges = event.changes.filter(
           (change) => isDataFile(change.path) && !skipRef.current?.(change.path)
         );
         if (dataChanges.length === 0) return;
-        void applyDataChanges(dataChanges, setFiles, setDataVersion);
+        console.log(`[reload] ${panelTag()} data <- ${dataChanges.map((c) => c.path).join(', ')}`);
+        void applyDataChanges(dataChanges, setFiles);
       }),
     []
   );
 
-  return { files, setFiles, dataVersion };
+  return { files, setFiles };
 }
 
-async function applyDataChanges(changes, setFiles, setDataVersion) {
+async function applyDataChanges(changes, setFiles) {
   const updates = await Promise.all(
     changes.map(async (change) => {
       if (change.event === 'delete') return { path: change.path, text: null };
@@ -85,5 +98,4 @@ async function applyDataChanges(changes, setFiles, setDataVersion) {
     }
     return next;
   });
-  setDataVersion((version) => version + 1);
 }

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

@@ -1,6 +1,8 @@
 // The pool of playing media elements: one `<audio>` / `<video>` per actor per
-// file. Behaviors (Sound, Video) ask for theirs each frame and set the state
-// they want on it; this module owns creating, reusing, and reaping them.
+// file. Behaviors (SoundPlayer with `stream` on, Video) ask for theirs each frame
+// and set the state they want on it; this module owns creating, reusing, and
+// reaping them. Short sound effects don't come through here at all -- they are
+// decoded buffers, in engine/sound.js.
 //
 // The pool is MODULE-level, not per-SceneRuntime, because the editor builds a
 // throwaway runtime every frame to draw the edit preview -- a per-runtime pool
@@ -15,7 +17,7 @@
 // editor's video preview draws a paused element's first frame.
 
 import { initialMedia } from './files';
-import { getAudioContext, resumeAudioContext } from './audioContext';
+import { getAudioContext, resumeAudioContext, unlockTargets } from './audioContext';
 
 // Reaped after this long without being asked for. Long enough to survive a
 // scene's worth of frames where an actor is briefly not drawn (offscreen,
@@ -24,10 +26,6 @@ import { getAudioContext, resumeAudioContext } from './audioContext';
 const IDLE_REAP_MS = 1500;
 
 const entries = new Map();
-// One-shot plays: copies of an element that overlap the original instead of
-// cutting it off (a sound effect fired again before the last one finished).
-// They are not keyed by anything -- they exist until they end.
-const oneShots = new Set();
 // Elements routed through WebAudio for panning, and their panner nodes. An
 // element can only be connected to the graph ONCE, so this is also the record
 // of which ones already are.
@@ -63,8 +61,10 @@ function bindUnlock() {
       );
     }
   };
-  window.addEventListener('pointerdown', retry, { passive: true });
-  window.addEventListener('keydown', retry, { passive: true });
+  for (const target of unlockTargets()) {
+    target.addEventListener('pointerdown', retry, { passive: true });
+    target.addEventListener('keydown', retry, { passive: true });
+  }
 }
 
 // Play, tolerating the autoplay policy: a refused play is queued for the next
@@ -81,6 +81,26 @@ export function playMedia(element) {
   }
 }
 
+// Retune a sound along with its speed, the way a tape does -- and the way the
+// buffer path's playbackRate already does.
+//
+// An element does the OPPOSITE by default. `preservesPitch` starts TRUE, so it
+// time-stretches to hold the pitch steady while the speed changes: right for a
+// podcast at 1.5x, wrong for a game sound, and audibly a phase vocoder rather
+// than a clean retune. Measured on a 110Hz tone at rate 2: 111Hz with the
+// default, 220Hz with this off -- the latter matching an AudioBufferSourceNode
+// exactly, which is what makes one `playbackRate` prop mean one thing across
+// both of this kit's playback paths.
+//
+// The prefixed spellings are for browsers older than the standard property;
+// assigning one that doesn't exist is harmless.
+export function setMediaPlaybackRate(element, rate) {
+  element.preservesPitch = false;
+  element.webkitPreservesPitch = false;
+  element.mozPreservesPitch = false;
+  element.playbackRate = rate;
+}
+
 // Pan a sound left/right (-1..1). The element has no panning of its own, so the
 // first non-zero pan routes it through a WebAudio graph -- permanently, since a
 // media element can only be connected once. Which is why pan 0 (the default)
@@ -107,31 +127,6 @@ export function setMediaPan(element, pan) {
   resumeAudioContext();
 }
 
-// Play a copy of this sound, overlapping whatever is already playing. Returns a
-// promise that resolves when the copy finishes, so a caller can wait for it.
-// Copies are never reused: a one-shot is done when it's done.
-export function playOneShot(path, { volume = 1, playbackRate = 1, pan = 0 } = {}) {
-  const url = mediaUrl(path);
-  if (!url) return Promise.resolve();
-  const element = document.createElement('audio');
-  element.src = url;
-  element.volume = volume;
-  element.playbackRate = playbackRate;
-  oneShots.add(element);
-  const finished = new Promise((resolve) => {
-    const done = () => {
-      oneShots.delete(element);
-      element.removeAttribute('src');
-      resolve();
-    };
-    element.addEventListener('ended', done, { once: true });
-    element.addEventListener('error', done, { once: true });
-  });
-  if (pan !== 0) setMediaPan(element, pan);
-  playMedia(element);
-  return finished;
-}
-
 export function stopMedia(element) {
   blocked.delete(element);
   element.pause();
@@ -202,11 +197,6 @@ export function stopAllMedia() {
     stopMedia(entry.element);
     entry.element.removeAttribute('src');
   }
-  for (const element of oneShots) {
-    stopMedia(element);
-    element.removeAttribute('src');
-  }
   entries.clear();
-  oneShots.clear();
   blocked.clear();
 }