castle-web-cli 0.4.83 → 0.4.85

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

@@ -0,0 +1,752 @@
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { faEye, faEyeSlash, faLink, faStopwatch } from '@fortawesome/free-solid-svg-icons';
+import { colorForKeyV2, paletteLookup, resolveCell, resolveCellGrid } from '../engine/pxart';
+import { Icon, IconButton, styles as ui } from '../engine/ui';
+import { cellKind, forEachGridCell, setupSpriteCanvas } from './pxArtEditorModel';
+import tl from './pxArtTimeline.module.css';
+
+// Tags and per-frame duration are intentionally hidden for now — we plan to
+// bring these UIs back later. Flip a flag to true to restore its rendering; the
+// underlying SDK semantics and model actions (setFrameDuration, tag ops, …)
+// stay fully wired either way, so this is a small, easily-revertible toggle.
+const SHOW_TAGS = false;
+const SHOW_PER_FRAME_DURATION = false;
+
+// The onion-skin look-ahead/behind range input is hidden for now; onion renders
+// a single neighbouring frame using ONION_RANGE. The capability and model action
+// (setOnionRange) stay fully wired — flipping SHOW_ONION_RANGE back to true
+// re-renders the count input, so this is a trivial, easily-revertible toggle.
+const SHOW_ONION_RANGE = false;
+const ONION_RANGE = 1;
+
+// 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
+// headers stay usable (min) and the artboard isn't crushed (max fraction).
+const TIMELINE_HEIGHT_KEY = 'castle-pxart-timeline-height';
+const MIN_TIMELINE_HEIGHT = 120;
+const DEFAULT_TIMELINE_HEIGHT = 320;
+const MAX_TIMELINE_FRACTION = 0.7;
+
+function readStoredTimelineHeight() {
+  try {
+    const raw = localStorage.getItem(TIMELINE_HEIGHT_KEY);
+    if (raw === null) return DEFAULT_TIMELINE_HEIGHT;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) ? parsed : DEFAULT_TIMELINE_HEIGHT;
+  } catch {
+    return DEFAULT_TIMELINE_HEIGHT;
+  }
+}
+
+// Owns the timeline's drag-to-resize height. Mirrors the CLI dev shell's
+// docked-panel resize model (pointer capture via window listeners, clamp on
+// drag, persist on release, re-clamp on container resize) but on the vertical
+// axis. Returns the section ref, the current height, a dragging flag, and the
+// pointer-down starter to wire onto the top handle.
+function useResizableTimelineHeight() {
+  const sectionRef = useRef(null);
+  const [height, setHeight] = useState(readStoredTimelineHeight);
+  const [dragging, setDragging] = useState(false);
+
+  const clamp = useCallback((next) => {
+    const parent = sectionRef.current?.parentElement;
+    const available = parent ? parent.clientHeight : Number.POSITIVE_INFINITY;
+    const max = Math.max(MIN_TIMELINE_HEIGHT, available * MAX_TIMELINE_FRACTION);
+    const value = Number.isFinite(next) ? next : MIN_TIMELINE_HEIGHT;
+    return Math.max(MIN_TIMELINE_HEIGHT, Math.min(value, max));
+  }, []);
+
+  // Clamp against the live container on mount and whenever it resizes, so a
+  // stored height never exceeds the current max fraction.
+  useEffect(() => {
+    const reclamp = () => setHeight((current) => clamp(current));
+    reclamp();
+    window.addEventListener('resize', reclamp);
+    return () => window.removeEventListener('resize', reclamp);
+  }, [clamp]);
+
+  // Drag session: listeners live on window (not the handle) so the pointer can
+  // leave the thin handle mid-drag. Re-registered only when `dragging` flips,
+  // so the cleanup always removes the exact handlers it added (no stale
+  // closures). The timeline's bottom edge is fixed, so height = bottom - y.
+  useEffect(() => {
+    if (!dragging) return undefined;
+    const onMove = (event) => {
+      const section = sectionRef.current;
+      if (!section) return;
+      const bottom = section.getBoundingClientRect().bottom;
+      setHeight(clamp(bottom - event.clientY));
+      event.preventDefault();
+    };
+    const stop = () => setDragging(false);
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', stop);
+    window.addEventListener('pointercancel', stop);
+    document.body.style.cursor = 'row-resize';
+    document.body.style.userSelect = 'none';
+    return () => {
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', stop);
+      window.removeEventListener('pointercancel', stop);
+      document.body.style.cursor = '';
+      document.body.style.userSelect = '';
+    };
+  }, [dragging, clamp]);
+
+  // Persist the final height once a drag settles (and once on mount, harmless).
+  useEffect(() => {
+    if (dragging) return;
+    try {
+      localStorage.setItem(TIMELINE_HEIGHT_KEY, String(Math.round(height)));
+    } catch {
+      /* storage disabled -- height just won't persist */
+    }
+  }, [dragging, height]);
+
+  const startDrag = (event) => {
+    setDragging(true);
+    event.preventDefault();
+  };
+
+  return { sectionRef, height, dragging, startDrag };
+}
+
+// The layers x frames timeline below the artboard. Layer ROWS (topmost layer at
+// 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, selection, playing, onion, actions }) {
+  const { sectionRef, height, dragging, startDrag } = useResizableTimelineHeight();
+  return (
+    <section ref={sectionRef} className={tl.timeline} style={{ height: `${height}px` }}>
+      <div
+        className={dragging ? tl.resizeHandle + ' ' + tl.resizeHandleActive : tl.resizeHandle}
+        role="separator"
+        aria-orientation="horizontal"
+        aria-label="Resize timeline"
+        onPointerDown={startDrag}
+      />
+      <TimelineBar
+        sprite={sprite}
+        selection={selection}
+        playing={playing}
+        onion={onion}
+        actions={actions}
+      />
+      <div className={tl.scroll}>
+        <TimelineGrid sprite={sprite} selection={selection} actions={actions} />
+      </div>
+      {SHOW_TAGS ? <TagsPanel sprite={sprite} actions={actions} /> : null}
+    </section>
+  );
+}
+
+// Slimmed toolbar. Left group: new layer, new frame. A spacer pushes the
+// right-anchored controls together in order: global duration input, onion-skin
+// toggle, then play/pause at the far right. Every other per-item action
+// (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 }) {
+  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
+  // having more than one frame.
+  const isAnimated = sprite.frames.length > 1;
+  // If frames were deleted down to one while a preview was playing, the
+  // play/pause button is now hidden, so stop playback to avoid being stuck in a
+  // (no-op) playing state with no visible control. togglePlay flips the flag, so
+  // calling it once while `playing` settles it to paused.
+  useEffect(() => {
+    if (playing && !isAnimated) actions.togglePlay();
+  }, [playing, isAnimated, actions]);
+  return (
+    <div className={tl.bar}>
+      <div className={tl.barGroup}>
+        <IconButton icon="layer-group" label="Layer" onClick={() => actions.addLayer(layerIndex)} />
+        <span className={tl.barLabel}>Layer</span>
+      </div>
+      <div className={tl.barGroup}>
+        <IconButton icon="film" label="Frame" onClick={() => actions.addFrame(frameIndex)} />
+        <span className={tl.barLabel}>Frame</span>
+      </div>
+      <div className={tl.barSpacer} />
+      {isAnimated ? (
+        <>
+          <div className={tl.barGroup}>
+            <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} />
+          </div>
+          <OnionControls onion={onion} actions={actions} />
+          <div className={tl.barGroup}>
+            <IconButton
+              icon={playing ? 'stop' : 'play'}
+              label={playing ? 'Pause preview' : 'Play preview'}
+              active={playing}
+              onClick={actions.togglePlay}
+            />
+          </div>
+        </>
+      ) : null}
+    </div>
+  );
+}
+
+// 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 }) {
+  return (
+    <CommitInput
+      text={String(value)}
+      className={tl.globalDuration}
+      title="Global frame duration (ms) — inherited by every frame without its own override"
+      onCommit={(draft) => {
+        const ms = Number(draft);
+        if (Number.isFinite(ms) && ms > 0) onCommit(ms);
+      }}
+    />
+  );
+}
+
+// Onion skin as a single icon toggle (clapperboard), 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
+// revert.
+function OnionControls({ onion, actions }) {
+  const onionClass = onion.enabled
+    ? ui.iconButton + ' ' + ui.button + ' ' + ui.buttonActive
+    : ui.iconButton + ' ' + ui.button;
+  const toggleOnion = () => {
+    const next = !onion.enabled;
+    actions.setOnionEnabled(next);
+    if (next) actions.setOnionRange(ONION_RANGE);
+  };
+  return (
+    <div className={tl.barGroup}>
+      <button
+        type="button"
+        className={onionClass}
+        aria-label={onion.enabled ? 'Onion skin on' : 'Onion skin off'}
+        aria-pressed={onion.enabled}
+        title={onion.enabled ? 'Onion skin on' : 'Onion skin off'}
+        onClick={toggleOnion}>
+        <FaGlyph icon={faClapperboard} />
+      </button>
+      {SHOW_ONION_RANGE ? (
+        <input
+          className={tl.miniInput}
+          type="number"
+          min="1"
+          max="8"
+          value={onion.range}
+          disabled={!onion.enabled}
+          onChange={(event) => actions.setOnionRange(Number(event.target.value))}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function TimelineGrid({ sprite, selection, actions }) {
+  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();
+  const [menu, setMenu] = useState(null);
+  const closeMenu = useCallback(() => setMenu(null), []);
+
+  // Each opener stops the browser's native menu, anchors at the cursor, and
+  // stashes just enough to rebuild items from the latest props at render time
+  // (so relocated actions always run against current sprite/selection state).
+  const openLayerMenu = (event, layerIndex) => {
+    event.preventDefault();
+    event.stopPropagation();
+    setMenu({ kind: 'layer', x: event.clientX, y: event.clientY, layerIndex });
+  };
+  const openFrameMenu = (event, frameIndex) => {
+    event.preventDefault();
+    event.stopPropagation();
+    setMenu({ kind: 'frame', x: event.clientX, y: event.clientY, frameIndex });
+  };
+  const openCellMenu = (event, layerIndex, frameIndex) => {
+    event.preventDefault();
+    event.stopPropagation();
+    // Link/Unlink are bound to the active cell, so select this one first; the
+    // menu re-renders with rebuilt actions that target (layerIndex, frameIndex).
+    actions.selectCell(layerIndex, frameIndex);
+    setMenu({ kind: 'cell', x: event.clientX, y: event.clientY, layerIndex, frameIndex });
+  };
+
+  return (
+    <div className={tl.grid}>
+      <div className={tl.row}>
+        <div className={tl.corner} />
+        {frames.map((frame, f) => (
+          <FrameHeader
+            key={f}
+            frame={frame}
+            index={f}
+            globalMs={sprite.defaultDurationMs}
+            active={f === selection.frameIndex}
+            onSelect={() => actions.selectCell(selection.layerIndex, f)}
+            onDuration={(ms) => actions.setFrameDuration(f, ms)}
+            onContextMenu={(event) => openFrameMenu(event, f)}
+          />
+        ))}
+      </div>
+      {rows.map((li) => (
+        <div className={tl.row} key={sprite.layers[li].id}>
+          <LayerHeader
+            layer={sprite.layers[li]}
+            index={li}
+            active={li === selection.layerIndex}
+            onSelect={() => actions.selectCell(li, selection.frameIndex)}
+            actions={actions}
+            onContextMenu={openLayerMenu}
+          />
+          {frames.map((_, f) => (
+            <CellThumb
+              key={f}
+              sprite={sprite}
+              layerIndex={li}
+              frameIndex={f}
+              active={li === selection.layerIndex && f === selection.frameIndex}
+              onSelect={() => actions.selectCell(li, f)}
+              onContextMenu={(event) => openCellMenu(event, li, f)}
+            />
+          ))}
+        </div>
+      ))}
+      {menu ? (
+        <ContextMenu
+          x={menu.x}
+          y={menu.y}
+          items={buildMenuItems(menu, sprite, actions)}
+          onClose={closeMenu}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+// Cursor-anchored right-click menu. Reuses the scene editor's "Arrange" menu
+// chrome (the shared `selArrangeMenu`/`selArrangeItem` classes from
+// engine/ui.module.css) for visual consistency, switching to fixed positioning
+// at the click point and closing on outside-click or Escape. Items are plain
+// `{ key, label, disabled?, onClick }` descriptors built by buildMenuItems.
+function ContextMenu({ x, y, items, onClose }) {
+  const ref = useRef(null);
+  const [pos, setPos] = useState({ left: x, top: y });
+
+  // Clamp into the viewport once measured so a menu opened near the bottom/right
+  // edge (the timeline is bottom-anchored) doesn't spill off-screen.
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    const margin = 8;
+    const maxLeft = Math.max(margin, window.innerWidth - rect.width - margin);
+    const maxTop = Math.max(margin, window.innerHeight - rect.height - margin);
+    setPos({ left: Math.min(x, maxLeft), top: Math.min(y, maxTop) });
+  }, [x, y]);
+
+  useEffect(() => {
+    const onPointerDown = (event) => {
+      if (!ref.current?.contains(event.target)) onClose();
+    };
+    const onKeyDown = (event) => {
+      if (event.key === 'Escape') onClose();
+    };
+    window.addEventListener('pointerdown', onPointerDown);
+    window.addEventListener('keydown', onKeyDown);
+    return () => {
+      window.removeEventListener('pointerdown', onPointerDown);
+      window.removeEventListener('keydown', onKeyDown);
+    };
+  }, [onClose]);
+
+  return (
+    <div
+      ref={ref}
+      className={ui.selArrangeMenu}
+      role="menu"
+      style={{ position: 'fixed', left: pos.left, top: pos.top, transform: 'none' }}
+      onContextMenu={(event) => event.preventDefault()}>
+      {items.map((item) => (
+        <button
+          key={item.key}
+          type="button"
+          role="menuitem"
+          disabled={item.disabled}
+          className={item.disabled ? ui.selArrangeItem + ' ' + tl.menuItemDisabled : ui.selArrangeItem}
+          onClick={() => {
+            item.onClick();
+            onClose();
+          }}>
+          {item.label}
+        </button>
+      ))}
+    </div>
+  );
+}
+
+function buildMenuItems(menu, sprite, actions) {
+  if (menu.kind === 'layer') return layerMenuItems(menu, sprite, actions);
+  if (menu.kind === 'frame') return frameMenuItems(menu, sprite, actions);
+  return cellMenuItems(menu, sprite, actions);
+}
+
+function layerMenuItems(menu, sprite, actions) {
+  const { layerIndex } = menu;
+  return [
+    { key: 'duplicate', label: 'Duplicate', onClick: () => actions.duplicateLayer(layerIndex) },
+    {
+      key: 'up',
+      label: 'Move up',
+      disabled: layerIndex >= sprite.layers.length - 1,
+      onClick: () => actions.moveLayer(layerIndex, 1),
+    },
+    {
+      key: 'down',
+      label: 'Move down',
+      disabled: layerIndex <= 0,
+      onClick: () => actions.moveLayer(layerIndex, -1),
+    },
+    {
+      key: 'delete',
+      label: 'Delete',
+      disabled: sprite.layers.length <= 1,
+      onClick: () => actions.deleteLayer(layerIndex),
+    },
+  ];
+}
+
+function frameMenuItems(menu, sprite, actions) {
+  const { frameIndex } = menu;
+  const overridden = Number.isFinite(sprite.frames[frameIndex]?.durationMs);
+  return [
+    { key: 'duplicate', label: 'Duplicate', onClick: () => actions.duplicateFrame(frameIndex) },
+    {
+      key: 'left',
+      label: 'Move left',
+      disabled: frameIndex <= 0,
+      onClick: () => actions.moveFrame(frameIndex, -1),
+    },
+    {
+      key: 'right',
+      label: 'Move right',
+      disabled: frameIndex >= sprite.frames.length - 1,
+      onClick: () => actions.moveFrame(frameIndex, 1),
+    },
+    ...(SHOW_PER_FRAME_DURATION
+      ? [
+          {
+            key: 'reset-duration',
+            label: 'Reset duration to global',
+            disabled: !overridden,
+            onClick: () => actions.setFrameDuration(frameIndex, null),
+          },
+        ]
+      : []),
+    {
+      key: 'delete',
+      label: 'Delete',
+      disabled: sprite.frames.length <= 1,
+      onClick: () => actions.deleteFrame(frameIndex),
+    },
+  ];
+}
+
+// Linking is a single bit: a cell is linked to the PREVIOUS frame (sharing its
+// image, chain-aware) or standalone. So the menu offers ONE toggle — "Unlink"
+// when linked, "Link to previous frame" otherwise. The link item is disabled on
+// frame 0 (no previous) and when the previous frame is empty (nothing to share).
+function cellMenuItems(menu, sprite, actions) {
+  const { layerIndex, frameIndex } = menu;
+  const layer = sprite.layers[layerIndex];
+  const isLinked = layer ? cellKind(layer, frameIndex) === 'link' : false;
+  if (isLinked) {
+    return [{ key: 'unlink', label: 'Unlink', onClick: () => actions.unlinkCell() }];
+  }
+  const canLink = !!layer && frameIndex > 0 && !!resolveCellGrid(layer, frameIndex - 1);
+  return [
+    {
+      key: 'link-prev',
+      label: 'Link to previous frame',
+      disabled: !canLink,
+      onClick: () => actions.linkCell(),
+    },
+  ];
+}
+
+function FrameHeader({ frame, index, globalMs, active, onSelect, onDuration, onContextMenu }) {
+  return (
+    <div
+      className={active ? tl.frameHead + ' ' + tl.frameHeadActive : tl.frameHead}
+      onContextMenu={onContextMenu}>
+      <button type="button" className={tl.frameNum} onClick={onSelect} style={btnReset}>
+        {index + 1}
+      </button>
+      {SHOW_PER_FRAME_DURATION ? (
+        <DurationInput value={frame.durationMs} globalMs={globalMs} onCommit={onDuration} />
+      ) : null}
+    </div>
+  );
+}
+
+const btnReset = { background: 'none', border: 0, color: 'inherit', cursor: 'pointer', padding: 0 };
+
+// A free-form text input that holds a local draft while focused and commits it
+// 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 }) {
+  const [draft, setDraft] = useState(text);
+  const editing = useRef(false);
+  if (!editing.current && draft !== text) setDraft(text);
+  function commit() {
+    editing.current = false;
+    onCommit(draft);
+  }
+  return (
+    <input
+      className={className}
+      value={draft}
+      placeholder={placeholder}
+      title={title}
+      inputMode="numeric"
+      onFocus={() => (editing.current = true)}
+      onChange={(event) => setDraft(event.target.value)}
+      onBlur={commit}
+      onKeyDown={(event) => {
+        if (event.key === 'Enter') event.currentTarget.blur();
+      }}
+    />
+  );
+}
+
+// Per-frame duration. When the frame OVERRIDES the global it shows the explicit
+// value (accented); when it INHERITS, the field is empty and shows the global
+// value as a greyed placeholder. Typing a value sets an override; clearing the
+// field (empty) reverts to inherit.
+function DurationInput({ value, globalMs, onCommit }) {
+  const overridden = Number.isFinite(value);
+  return (
+    <CommitInput
+      text={overridden ? String(value) : ''}
+      className={overridden ? tl.durationInput + ' ' + tl.durationOverride : tl.durationInput}
+      placeholder={String(globalMs)}
+      title={
+        overridden
+          ? 'Frame duration override (ms) — clear to inherit the global'
+          : `Inheriting global duration (${globalMs} ms)`
+      }
+      onCommit={(draft) => {
+        const trimmed = draft.trim();
+        if (trimmed === '') return onCommit(null);
+        const ms = Number(trimmed);
+        onCommit(Number.isFinite(ms) ? ms : null);
+      }}
+    />
+  );
+}
+
+// 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, onSelect, actions, onContextMenu }) {
+  return (
+    <div
+      className={active ? tl.layerHead + ' ' + tl.layerHeadActive : tl.layerHead}
+      onClick={onSelect}
+      onContextMenu={(event) => onContextMenu(event, index)}>
+      <div className={tl.layerTopRow}>
+        <button
+          type="button"
+          className={layer.visible ? tl.visBtn : tl.visBtn + ' ' + tl.visOff}
+          title={layer.visible ? 'Hide layer' : 'Show layer'}
+          onClick={(event) => {
+            event.stopPropagation();
+            actions.patchLayer(index, { visible: !layer.visible });
+          }}>
+          <FaGlyph icon={layer.visible ? faEye : faEyeSlash} />
+        </button>
+        <span className={tl.name} title={layer.name}>
+          {layer.name}
+        </span>
+      </div>
+      <input
+        className={tl.opacity}
+        type="range"
+        min="0"
+        max="100"
+        value={Math.round(layer.opacity * 100)}
+        title={`Opacity ${Math.round(layer.opacity * 100)}%`}
+        onClick={(event) => event.stopPropagation()}
+        onChange={(event) => actions.patchLayer(index, { opacity: Number(event.target.value) / 100 })}
+      />
+    </div>
+  );
+}
+
+function CellThumb({ sprite, layerIndex, frameIndex, active, onSelect, onContextMenu }) {
+  const canvasRef = useRef(null);
+  const layer = sprite.layers[layerIndex];
+  const kind = cellKind(layer, frameIndex);
+  useEffect(() => {
+    if (canvasRef.current && kind !== 'empty') drawCellThumb(canvasRef.current, sprite, layerIndex, frameIndex);
+  });
+  return (
+    <button
+      type="button"
+      className={active ? tl.cell + ' ' + tl.cellActive : tl.cell}
+      title={`Layer ${layerIndex + 1}, frame ${frameIndex + 1} (${kind})`}
+      onClick={onSelect}
+      onContextMenu={onContextMenu}>
+      {kind === 'empty' ? (
+        <span className={tl.empty} />
+      ) : (
+        <span className={kind === 'link' ? tl.thumb + ' ' + tl.linkRing : tl.thumb}>
+          <canvas ref={canvasRef} className={tl.thumbCanvas} />
+        </span>
+      )}
+      {kind === 'link' ? (
+        <span className={tl.linkBadge}>
+          <FaGlyph icon={faLink} />
+        </span>
+      ) : null}
+    </button>
+  );
+}
+
+// Paint a single (layer, frame) cell's resolved image onto a native-resolution
+// canvas (1px/cell), following links. Used for timeline thumbnails. Offset-aware
+// and clipping to match renderSpriteFrame: a cel resolves to { grid, x, y } (a
+// link shares its source's image AND offset), and a source pixel (gx, gy) lands
+// at canvas (gx + x, gy + y), skipped when outside [0, width) x [0, height).
+// (Iterating the full grid via Infinity bounds, then clipping per pixel — the
+// canvas window, not the source extent, is the clip.)
+function drawCellThumb(canvas, sprite, layerIndex, frameIndex) {
+  const ctx = setupSpriteCanvas(canvas, sprite.resolution);
+  if (!ctx) return;
+  const resolved = resolveCell(sprite.layers[layerIndex], frameIndex);
+  if (!resolved) return;
+  const { width, height } = sprite.resolution;
+  const { grid, x: offsetX, y: offsetY } = resolved;
+  const lookup = paletteLookup(sprite.palette);
+  forEachGridCell(grid, Infinity, Infinity, (gx, gy, key) => {
+    const cx = gx + offsetX;
+    const cy = gy + offsetY;
+    if (cx < 0 || cx >= width || cy < 0 || cy >= height) return;
+    const color = colorForKeyV2(lookup, key);
+    if (color) {
+      ctx.fillStyle = color;
+      ctx.fillRect(cx, cy, 1, 1);
+    }
+  });
+}
+
+function TagsPanel({ sprite, actions }) {
+  return (
+    <div className={tl.tags}>
+      <div className={tl.tagsHead}>
+        <span className={tl.barLabel}>Tags</span>
+        <IconButton icon="plus" label="Add tag" onClick={actions.addTag} />
+      </div>
+      {sprite.tags.length === 0 ? <div className={tl.muted}>No tags.</div> : null}
+      {sprite.tags.map((tag, i) => (
+        <TagRow
+          key={i}
+          tag={tag}
+          index={i}
+          isDefault={sprite.defaultTag === tag.name}
+          actions={actions}
+        />
+      ))}
+    </div>
+  );
+}
+
+function TagRow({ tag, index, isDefault, actions }) {
+  return (
+    <div className={tl.tagRow}>
+      <button
+        type="button"
+        className={isDefault ? tl.tagDefault + ' ' + tl.tagDefaultOn : tl.tagDefault}
+        title={isDefault ? 'Default tag' : 'Make default tag'}
+        onClick={() => actions.setDefaultTag(isDefault ? '' : tag.name)}>
+        <Icon name="play" />
+      </button>
+      <input
+        className={tl.tagName}
+        value={tag.name}
+        onChange={(event) => actions.patchTag(index, { name: event.target.value })}
+      />
+      <input
+        className={tl.tagNum}
+        type="number"
+        min="1"
+        value={tag.from + 1}
+        title="From frame"
+        onChange={(event) => actions.patchTag(index, { from: Number(event.target.value) - 1 })}
+      />
+      <input
+        className={tl.tagNum}
+        type="number"
+        min="1"
+        value={tag.to + 1}
+        title="To frame"
+        onChange={(event) => actions.patchTag(index, { to: Number(event.target.value) - 1 })}
+      />
+      <select
+        className={tl.tagSelect}
+        value={tag.direction}
+        onChange={(event) => actions.patchTag(index, { direction: event.target.value })}>
+        <option value="forward">forward</option>
+        <option value="reverse">reverse</option>
+        <option value="pingpong">pingpong</option>
+      </select>
+      <input
+        className={tl.tagNum}
+        type="number"
+        min="0"
+        value={tag.repeat}
+        title="Repeat (0 = loop)"
+        onChange={(event) => actions.patchTag(index, { repeat: Number(event.target.value) })}
+      />
+      <IconButton
+        icon="trash"
+        label="Delete tag"
+        variant="danger"
+        onClick={() => actions.deleteTag(index)}
+      />
+    </div>
+  );
+}