castle-web-cli 0.4.169 → 0.4.171

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

@@ -1,5 +1,4 @@
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
-import { faEye, faEyeSlash, faLink, faStopwatch } from '@fortawesome/free-solid-svg-icons';
 import { colorForKeyV2, displayFinish, paletteLookup, resolveCell, resolveCellGrid } from '../engine/pxart';
 import { renderSmoothLayerCell } from '../engine/pxartSmooth';
 import {
@@ -34,21 +33,6 @@ const ONION_RANGE = 1;
 const TIMELINE_LONG_PRESS_MS = 500;
 const TIMELINE_LONG_PRESS_MOVE_TOLERANCE = 10;
 
-// faClapperboard ships in Font Awesome 6, but this kit is pinned to FA5 (see
-// package.json), which doesn't export it. Rather than silently swap in a
-// different-meaning icon, inline the exact FA6 solid clapperboard glyph
-// (viewBox 0 0 512 512) in the same shape <FaGlyph> consumes (an FA icon
-// tuple: [w, h, ligatures, unicode, path]). Drop-in once the kit moves to FA6.
-const faClapperboard = {
-  icon: [
-    512,
-    512,
-    [],
-    '',
-    'M448 32l-86.1 0-1 1-127 127 92.1 0 1-1L453.8 32.3c-1.9-.2-3.8-.3-5.8-.3zm64 128l0-64c0-15.1-5.3-29.1-14-40l-104 104L512 160zM294.1 32l-92.1 0-1 1L73.9 160l92.1 0 1-1 127-127zM64 32C28.7 32 0 60.7 0 96l0 64 6.1 0 1-1 127-127L64 32zM512 192L0 192 0 416c0 35.3 28.7 64 64 64l384 0c35.3 0 64-28.7 64-64l0-224z',
-  ],
-};
-
 // User-resizable timeline height (persisted per-`.pxart`-editor). The panel is
 // bottom-anchored in the editor's left column, so dragging the top handle up
 // makes the timeline taller and the artboard shorter. Clamped so the timeline
@@ -235,12 +219,12 @@ function TimelineBar({ sprite, selection, playing, onion, actions, readOnly = fa
   return (
     <div className={tl.bar}>
       <div className={tl.barGroup}>
-        <IconButton icon="grid" label="Pixel" disabled={readOnly} onClick={() => actions.addLayer(layerIndex)} />
+        <IconButton icon="checkerboard" label="Pixel" disabled={readOnly} onClick={() => actions.addLayer(layerIndex)} />
         <span className={tl.barLabel}>Pixel</span>
       </div>
       <div className={tl.barGroup}>
         <IconButton
-          icon="draw-polygon"
+          icon="bounding-box"
           label="Path"
           disabled={readOnly}
           onClick={() => actions.addLayer(layerIndex, 'path')}
@@ -256,7 +240,7 @@ function TimelineBar({ sprite, selection, playing, onion, actions, readOnly = fa
         <>
           <div className={tl.barGroup}>
             <span className={tl.durationIcon} title="Default frame duration (ms) — applies to all frames">
-              <FaGlyph icon={faStopwatch} className={tl.durationGlyph} />
+              <Icon name="stopwatch" />
             </span>
             <GlobalDurationInput
               value={sprite.defaultDurationMs}
@@ -296,7 +280,7 @@ function GlobalDurationInput({ value, onCommit, disabled = false }) {
   );
 }
 
-// Onion skin as a single icon toggle (clapperboard), styled like the toolbar's
+// Onion skin as a single icon toggle, styled like the toolbar's
 // other IconButtons with an active state when enabled. Enabling pins the range
 // to ONION_RANGE so the (hidden) count is always 1; the range input is gated
 // behind SHOW_ONION_RANGE and the setOnionRange action stays wired for an easy
@@ -319,7 +303,7 @@ function OnionControls({ onion, actions }) {
         aria-pressed={onion.enabled}
         title={onion.enabled ? 'Onion skin on' : 'Onion skin off'}
         onClick={toggleOnion}>
-        <FaGlyph icon={faClapperboard} />
+        <Icon name="subtract" />
       </button>
       {SHOW_ONION_RANGE ? (
         <input
@@ -812,18 +796,6 @@ function DurationInput({ value, globalMs, onCommit }) {
   );
 }
 
-// Inline Font Awesome glyph. engine/ui's <Icon> registry has no eye/eye-slash
-// and lives outside this editor (which we shouldn't edit), so the layer
-// visibility toggle renders the FA path directly here.
-function FaGlyph({ icon, className = tl.visGlyph }) {
-  const [w, h, , , path] = icon.icon;
-  return (
-    <svg className={className} viewBox={`0 0 ${w} ${h}`} aria-hidden="true">
-      <path d={path} />
-    </svg>
-  );
-}
-
 function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions, onContextMenu, readOnly = false }) {
   return (
     <div
@@ -835,7 +807,7 @@ function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions,
         <span
           style={kindBadgeStyle}
           title={layer.kind === 'path' ? 'Path layer' : 'Pixel layer'}>
-          <Icon name={layer.kind === 'path' ? 'draw-polygon' : 'grid'} />
+          <Icon name={layer.kind === 'path' ? 'bounding-box' : 'checkerboard'} />
         </span>
         <span className={tl.name} title={layer.name}>
           {layer.name}
@@ -862,7 +834,7 @@ function LayerHeader({ layer, index, active, onActivate, onPointerDown, actions,
             event.stopPropagation();
             actions.patchLayer(index, { visible: !layer.visible });
           }}>
-          <FaGlyph icon={layer.visible ? faEye : faEyeSlash} />
+          <Icon name={layer.visible ? 'eye' : 'eye-closed'} />
         </button>
       </div>
     </div>
@@ -904,7 +876,7 @@ function CellThumb({ sprite, text, layerIndex, frameIndex, active, onActivate, o
       )}
       {kind === 'link' ? (
         <span className={tl.linkBadge}>
-          <FaGlyph icon={faLink} />
+          <Icon name="link" />
         </span>
       ) : null}
     </button>

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

@@ -120,12 +120,7 @@
   display: inline-flex;
   align-items: center;
   color: var(--castle-inspector-muted);
-}
-
-.durationGlyph {
-  width: 14px;
-  height: 14px;
-  fill: currentColor;
+  font-size: 14px;
 }
 
 .miniInput {
@@ -285,24 +280,13 @@
   color: var(--castle-inspector-text);
   cursor: pointer;
   padding: 0;
+  font-size: 12px;
 }
 
 .visBtn:hover {
   background: var(--castle-inspector-input-bg);
 }
 
-.visBtn svg {
-  width: 12px;
-  height: 12px;
-}
-
-/* Inline FA eye / eye-slash glyph for the visibility toggle (see FaGlyph). */
-.visGlyph {
-  width: 12px;
-  height: 12px;
-  fill: currentColor;
-}
-
 /* Hidden layer: the visibility toggle borrows the standard disabled LOOK
    (0.35 dimming, matching the undo button) without being disabled -- this
    button stays interactive and toggles default <-> disabled-look. */
@@ -448,11 +432,7 @@
   border-radius: 2px;
   background: var(--castle-blue);
   color: var(--castle-selected-ink);
-}
-
-.linkBadge svg {
-  width: 9px;
-  height: 9px;
+  font-size: 9px;
 }
 
 .linkRing {
@@ -531,6 +511,7 @@
   color: var(--castle-inspector-muted);
   cursor: pointer;
   padding: 0;
+  font-size: 12px;
 }
 
 .tagDefault:hover {
@@ -544,11 +525,6 @@
   color: var(--castle-selected-ink);
 }
 
-.tagDefault svg {
-  width: 12px;
-  height: 12px;
-}
-
 .muted {
   color: var(--castle-inspector-muted);
   font-size: 12px;

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

@@ -38,6 +38,8 @@
    whatever the face's width. Falls back to the panel font until the specimen
    has been fetched (see editors/fontPreview.js). */
 .specimen {
+  width: 100%;
+  min-width: 0;
   overflow: hidden;
   font-size: 26px;
   line-height: 1.25;
@@ -53,9 +55,13 @@
 }
 
 .card {
-  display: flex;
-  flex-direction: column;
-  gap: 8px;
+  /* Block, not flex: WebKit's button anonymous box shrink-wraps flex
+     children (style editor palette strips on some iOS). appearance wipe
+     matches other kit buttons. */
+  display: block;
+  box-sizing: border-box;
+  appearance: none;
+  -webkit-appearance: none;
   width: 100%;
   margin: 0;
   padding: 12px;
@@ -63,10 +69,19 @@
   border-radius: var(--castle-radius, 4px);
   background: var(--castle-card, #121213);
   color: inherit;
+  font: inherit;
   text-align: left;
   cursor: pointer;
 }
 
+.cardBody {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  width: 100%;
+  min-width: 0;
+}
+
 .card:hover {
   background: var(--castle-panel-raised, #101010);
 }
@@ -94,6 +109,8 @@
   align-items: baseline;
   justify-content: space-between;
   gap: 12px;
+  width: 100%;
+  min-width: 0;
 }
 
 .cardName {
@@ -119,6 +136,8 @@
 
 .strip {
   display: flex;
+  width: 100%;
+  min-width: 0;
   height: 18px;
   overflow: hidden;
   border: 1px solid var(--castle-inspector-border, #2a2a2a);
@@ -126,7 +145,7 @@
 }
 
 .chip {
-  flex: 1 1 0;
+  flex: 1 1 0%;
   min-width: 2px;
   height: 100%;
 }

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

@@ -0,0 +1,322 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+// Artboard zoom + pan for the pixel editors.
+//
+// zoom 1 = fit (the artboard fills its region); above that the canvas overflows
+// the viewport and the viewport scrolls to pan. Scrolling is entirely
+// PROGRAMMATIC -- `touch-action: none` hands the pinch to us and the wheel is
+// preventDefault'd for zoom -- so the viewport is `overflow: hidden` and shows
+// no scrollbars.
+// Below fit the artboard just gets smaller inside the viewport, which is worth
+// having: it is how you see a sprite whole with room around it rather than
+// edge-to-edge under your thumbs.
+const MIN_ART_ZOOM = 0.25;
+const MAX_ART_ZOOM = 12;
+const ART_ZOOM_WHEEL_SPEED = 0.01;
+// A chunky mouse notch should be one sane step while trackpad deltas stay smooth.
+const MAX_WHEEL_DELTA = 50;
+// A pinch step this close to 1 is finger jitter during a pure pan rather than a
+// scale change -- but see applyZoomPan: it is accumulated, not discarded.
+const ZOOM_EPSILON = 0.002;
+// Fit is the one zoom worth landing on exactly: a hair above it the artboard is
+// wider than the viewport and the last pixel column sits under the edge, and a
+// pinch cannot realistically stop on 1.000 by hand. So a gesture that SETTLES
+// within this band of fit finishes on exactly fit. Snapping mid-pinch instead
+// would make the view stick and fight the fingers on the way past.
+const ZOOM_SNAP_BAND = 0.08;
+// How long after the last wheel notch counts as the wheel having settled.
+const WHEEL_SETTLE_MS = 180;
+
+// Empty room around the artboard inside the viewport, as a fraction of the
+// viewport. Half a viewport on every side is exactly what it takes to bring ANY
+// point of the sprite to the middle of the screen -- corners included, which is
+// the whole point: without it the corner of a deeply zoomed sprite can only ever
+// sit in the corner of the viewport, where a thumb covers it.
+const MAX_OVERSCROLL = 0.5;
+
+function clamp(value, lo, hi) {
+  return Math.min(hi, Math.max(lo, value));
+}
+
+// Ramped in over the first octave rather than applied flat, because at fit there
+// is nothing to pan TO: the artboard already fills the viewport, so slack there
+// would just let a two-finger drag slide the whole sprite off-centre with nothing
+// asking it to come back. 0 at fit (pinned, as before), full half-viewport from
+// 2x up -- well below any zoom at which you would be picking at a corner.
+function overscrollPad(displaySize, zoom, axis) {
+  return Math.round(displaySize[axis] * MAX_OVERSCROLL * clamp(zoom - 1, 0, 1));
+}
+
+// How close to the sprite's edge the viewport centre may sit, as a fraction of
+// the artboard. The overscroll pad is what buys this range, so it is derived from
+// the same number the layout uses: `m` and `1 - m` are the scroll limits
+// expressed in centre terms, and m == 0 means any point including a corner can be
+// centred. Falls back to dead centre when the artboard cannot fill the viewport.
+function centreLimit(displaySize, zoom, axis, viewportSize) {
+  const canvas = displaySize[axis] * zoom;
+  const margin = (viewportSize / 2 - overscrollPad(displaySize, zoom, axis)) / canvas;
+  return margin >= 0.5 ? 0.5 : Math.max(0, margin);
+}
+
+// The view is stored as the SPRITE-relative point under the viewport centre
+// (`cx`, `cy`, across the artboard) plus `zoom` -- not as a scroll offset. Two
+// things fall out of that: clamping the centre to `centreLimit` IS the pan
+// limit, so there is no second set of bounds math to keep in step with the
+// layout; and a viewport resize keeps looking at the same part of the sprite for
+// free, because nothing in the stored view is in pixels.
+function centreOf(view, displaySize, viewport) {
+  const canvasW = displaySize.width * view.zoom;
+  const canvasH = displaySize.height * view.zoom;
+  const padX = overscrollPad(displaySize, view.zoom, 'width');
+  const padY = overscrollPad(displaySize, view.zoom, 'height');
+  return {
+    left: clamp(
+      padX + view.cx * canvasW - viewport.clientWidth / 2,
+      0,
+      Math.max(0, canvasW + padX * 2 - viewport.clientWidth)
+    ),
+    top: clamp(
+      padY + view.cy * canvasH - viewport.clientHeight / 2,
+      0,
+      Math.max(0, canvasH + padY * 2 - viewport.clientHeight)
+    ),
+  };
+}
+
+export function useArtboardZoomPan({ viewportRef, displaySize }) {
+  const [zoom, setZoom] = useState(1);
+  // The authoritative view, updated SYNCHRONOUSLY by every gesture step. `zoom`
+  // state only mirrors it to drive layout: a pinch emits several steps per
+  // frame, and reading the committed state instead would make each step of the
+  // burst compose against a zoom two steps stale.
+  const viewRef = useRef({ zoom: 1, cx: 0.5, cy: 0.5 });
+  const panRef = useRef(null);
+  // Pinch scale seen since the last step big enough to apply -- see applyZoomPan.
+  const pendingFactorRef = useRef(1);
+  const wheelSettleRef = useRef(null);
+
+  const writeScroll = useCallback(() => {
+    const vp = viewportRef.current;
+    if (!vp || !displaySize) return;
+    const { left, top } = centreOf(viewRef.current, displaySize, vp);
+    vp.scrollLeft = left;
+    vp.scrollTop = top;
+  }, [displaySize, viewportRef]);
+
+  // A LAYOUT effect, not a rAF: the scroll that re-centres a zoom step has to be
+  // written after the canvas has been laid out at its new size and before the
+  // frame is painted. Writing it from a rAF raced the React commit -- the scroll
+  // clamped against the canvas's OLD width, so the anchor slid a little on every
+  // step and a pinch drifted away from the fingers.
+  useLayoutEffect(writeScroll, [writeScroll, zoom]);
+
+  // Clamp the stored centre to what the current zoom's overscroll actually
+  // allows. Both the pan and the zoom go through here, so neither can leave the
+  // view somewhere the scroll cannot express.
+  const clampCentre = useCallback(
+    (view, vp) => {
+      const mx = centreLimit(displaySize, view.zoom, 'width', vp.clientWidth);
+      const my = centreLimit(displaySize, view.zoom, 'height', vp.clientHeight);
+      view.cx = clamp(view.cx, mx, 1 - mx);
+      view.cy = clamp(view.cy, my, 1 - my);
+    },
+    [displaySize]
+  );
+
+  const panBy = useCallback(
+    (dx, dy) => {
+      const vp = viewportRef.current;
+      if (!vp || !displaySize || (!dx && !dy)) return;
+      const view = viewRef.current;
+      view.cx -= dx / (displaySize.width * view.zoom);
+      view.cy -= dy / (displaySize.height * view.zoom);
+      clampCentre(view, vp);
+      writeScroll();
+    },
+    [displaySize, writeScroll, clampCentre, viewportRef]
+  );
+
+  // Zoom to `nextRaw` (clamped) while pinning the sprite point under (anchorX,
+  // anchorY) client coords -- defaulting to the viewport centre.
+  const applyZoom = useCallback(
+    (nextRaw, anchorX, anchorY) => {
+      const vp = viewportRef.current;
+      if (!vp || !displaySize) return;
+      const view = viewRef.current;
+      const z1 = clamp(nextRaw, MIN_ART_ZOOM, MAX_ART_ZOOM);
+      if (z1 === view.zoom) return;
+      const rect = vp.getBoundingClientRect();
+      const offX = (Number.isFinite(anchorX) ? anchorX : rect.left + rect.width / 2) - rect.left
+        - vp.clientWidth / 2;
+      const offY = (Number.isFinite(anchorY) ? anchorY : rect.top + rect.height / 2) - rect.top
+        - vp.clientHeight / 2;
+      // Sprite point under the anchor, held fixed across the step.
+      const spriteX = view.cx + offX / (displaySize.width * view.zoom);
+      const spriteY = view.cy + offY / (displaySize.height * view.zoom);
+      view.zoom = z1;
+      view.cx = spriteX - offX / (displaySize.width * z1);
+      view.cy = spriteY - offY / (displaySize.height * z1);
+      clampCentre(view, vp);
+      setZoom(z1);
+    },
+    [displaySize, viewportRef, clampCentre]
+  );
+
+  // A button step that would cross fit stops on it instead. Stepping straight
+  // past 100% and having to hunt back for it is the worse trade.
+  const zoomBy = useCallback(
+    (factor) => {
+      const from = viewRef.current.zoom;
+      const to = from * factor;
+      applyZoom((from - 1) * (to - 1) < 0 ? 1 : to);
+    },
+    [applyZoom]
+  );
+
+  // Land on exactly fit when a gesture ends near it. Anchorless, so it settles
+  // about the viewport centre.
+  const settleZoom = useCallback(() => {
+    const { zoom: z } = viewRef.current;
+    if (z !== 1 && z < 1 + ZOOM_SNAP_BAND && z > 1 / (1 + ZOOM_SNAP_BAND)) applyZoom(1);
+  }, [applyZoom]);
+
+  const resetZoom = useCallback(() => {
+    viewRef.current = { zoom: 1, cx: 0.5, cy: 0.5 };
+    setZoom(1);
+    // setZoom is a no-op when we were already at fit, so the layout effect will
+    // not run -- re-centre here for that case.
+    writeScroll();
+  }, [writeScroll]);
+
+  // One two-finger step: pan by the centroid's movement, then zoom about it.
+  const applyZoomPan = useCallback(
+    ({ factor, cx, cy, dx, dy }) => {
+      panBy(dx, dy);
+      // Sub-threshold steps ACCUMULATE rather than being thrown away. A slow,
+      // deliberate pinch -- which is exactly how you close the last few percent
+      // onto fit -- emits per-frame factors under the jitter threshold, and
+      // dropping each one outright is what made those last percent unreachable.
+      // Real jitter cancels in the running product; a pinch does not.
+      const pending = pendingFactorRef.current * factor;
+      if (Math.abs(pending - 1) <= ZOOM_EPSILON) {
+        pendingFactorRef.current = pending;
+        return;
+      }
+      pendingFactorRef.current = 1;
+      applyZoom(viewRef.current.zoom * pending, cx, cy);
+    },
+    [panBy, applyZoom]
+  );
+
+  // A pinch begins: drop any factor left over from the previous one.
+  const beginGesture = useCallback(() => {
+    pendingFactorRef.current = 1;
+  }, []);
+  const endGesture = useCallback(() => {
+    pendingFactorRef.current = 1;
+    settleZoom();
+  }, [settleZoom]);
+
+  // Wheel zoom as a NATIVE non-passive listener so preventDefault stops the
+  // page/browser zoom underneath.
+  useEffect(() => {
+    const vp = viewportRef.current;
+    if (!vp) return undefined;
+    const onWheel = (event) => {
+      event.preventDefault();
+      const delta = clamp(event.deltaY, -MAX_WHEEL_DELTA, MAX_WHEEL_DELTA);
+      applyZoom(
+        viewRef.current.zoom * Math.exp(-delta * ART_ZOOM_WHEEL_SPEED),
+        event.clientX,
+        event.clientY
+      );
+      clearTimeout(wheelSettleRef.current);
+      wheelSettleRef.current = setTimeout(settleZoom, WHEEL_SETTLE_MS);
+    };
+    vp.addEventListener('wheel', onWheel, { passive: false });
+    return () => {
+      clearTimeout(wheelSettleRef.current);
+      vp.removeEventListener('wheel', onWheel, { passive: false });
+    };
+  }, [applyZoom, settleZoom, viewportRef]);
+
+  // Middle-button drag (or ⌘+left-drag) pans. Caught in the capture phase so the
+  // press never reaches the canvas's own draw handler.
+  const viewportHandlers = {
+    onPointerDownCapture: (event) => {
+      if (!(event.button === 1 || (event.button === 0 && event.metaKey))) return;
+      event.preventDefault();
+      event.stopPropagation();
+      viewportRef.current?.setPointerCapture(event.pointerId);
+      panRef.current = { id: event.pointerId, x: event.clientX, y: event.clientY };
+    },
+    onPointerMove: (event) => {
+      const pan = panRef.current;
+      if (!pan || pan.id !== event.pointerId) return;
+      panBy(event.clientX - pan.x, event.clientY - pan.y);
+      pan.x = event.clientX;
+      pan.y = event.clientY;
+    },
+    onPointerUp: (event) => {
+      const pan = panRef.current;
+      if (!pan || pan.id !== event.pointerId) return;
+      try {
+        viewportRef.current?.releasePointerCapture(event.pointerId);
+      } catch {
+        // pointer capture may already be gone
+      }
+      panRef.current = null;
+    },
+  };
+  viewportHandlers.onPointerCancel = viewportHandlers.onPointerUp;
+
+  // The viewport is the fit baseline; the scroll content is the zoomed canvas
+  // plus half a viewport of overscroll on every side.
+  const viewportStyle = displaySize
+    ? {
+        width: displaySize.width,
+        height: displaySize.height,
+        maxWidth: '100%',
+        maxHeight: '100%',
+        overflow: 'hidden',
+        touchAction: 'none',
+      }
+    : { overflow: 'hidden' };
+  const padX = displaySize ? overscrollPad(displaySize, zoom, 'width') : 0;
+  const padY = displaySize ? overscrollPad(displaySize, zoom, 'height') : 0;
+  // Sized to the artboard plus its overscroll, but never smaller than the
+  // viewport: below fit the artboard no longer fills the viewport, and without
+  // the minimum the scroll content would shrink around it and strand it in the
+  // top-left corner. Centring is flex rather than padding so the same rule
+  // covers both cases -- the extra room is the overscroll above fit and the
+  // empty surround below it.
+  const contentStyle = displaySize
+    ? {
+        boxSizing: 'border-box',
+        width: displaySize.width * zoom + padX * 2,
+        height: displaySize.height * zoom + padY * 2,
+        minWidth: '100%',
+        minHeight: '100%',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+      }
+    : undefined;
+  const canvasSize = displaySize
+    ? { width: displaySize.width * zoom, height: displaySize.height * zoom }
+    : null;
+
+  return {
+    zoom,
+    applyZoom,
+    zoomBy,
+    resetZoom,
+    applyZoomPan,
+    beginGesture,
+    endGesture,
+    viewportHandlers,
+    viewportStyle,
+    contentStyle,
+    canvasSize,
+  };
+}

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

@@ -3,19 +3,13 @@ import styles from './ui.module.css';
 import { useElementSize } from './ui';
 import { cardSize, isBehaviorEnabled } from './scene';
 import { deckFontFamily } from './fonts';
-// Game-time UI overlay.
+// Game-time React UI overlay -- deprecated.
 //
-// Behaviors expose a `ui(actor, scene)` handler -- the React counterpart of
-// `draw`. `SceneUI` collects every behavior's UI output each frame and renders
-// it into a deck-sized layer that sits exactly over the canvas. The layer is
-// `cardSize` units wide/tall and scaled onto the canvas box, so behaviors lay
-// out in the same card units as `Layout`. The root clips with `overflow:
-// hidden`, so deck UI can never render outside the card.
-//
-// The layer also carries the deck's font, so a behavior returning React gets it
-// with no extra work, and `--castle-deck-font` is there for deck CSS that wants
-// to name it. Canvas text can't inherit anything -- `draw` hooks read
-// `scene.font` instead.
+// Prefer behavior `drawUi(actor, scene, ctx)` for HUD. `ui(actor, scene)` still
+// works: this layer collects every behavior's React output each frame and
+// renders it over the canvas in card units (`cardSize`, scaled onto the canvas
+// box, clipped). Kept so existing decks keep rendering; new HUD should use
+// `drawUi` and `scene.font` instead.
 export function SceneUI({ getRuntime }) {
   const rootRef = useRef(null);
   // Track the canvas-sized overlay box so the card-unit layer scales onto it.