@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/storyboard/PlanPanel.tsx

@@ -0,0 +1,617 @@
+// THE PLAN OF ONE PLANNED SHOT (Paper SB1 and SB2): the right panel of the
+// shot board, and of the board when one shot card is selected.
+//
+//   head      SB2 "Plan" and "Shot 02" on the shot board, whose bar names the
+//             shot; SB1 the number, the name and the status badge on the
+//             board (`variant`). The name renames in place (`PartName`).
+//   words     What we see (`part.notes`), How it moves (`part.motion`, the
+//             numbered beats: add, edit, remove, drag or Alt+arrow to
+//             reorder, at most `STORYBOARD_BEATS_MAX`), Voice (`part.voice`).
+//   timing    Length (`part.durationFrames`, typed and shown in seconds,
+//             "2.00s") and Cut to next: the Shot's transition, edited with the
+//             Studio's own rows (`TransitionRows`) once the shot has a Shot.
+//   ground    Paper, Dark or Brand for the sketch the panel follows (`sketchId`,
+//             else Sketch 1). Hidden while the shot has no sketch.
+//   pinned    the cards pinned to this shot: Must or Optional for a
+//             requirement, "on sketch" when the sketch draws it. Each row drags
+//             as a board card (`STORYBOARD_MIME`), so it drops on a sketch.
+//   style     how many Style cards apply to every shot.
+//   footer    the caller's (`footer`), else on the shot board the agent line.
+//
+// THE BLOCKS KEEP THEIR CAPS LABELS (`.caps` is the design system's label for
+// a form), and every control in them is a house widget at its standard
+// geometry: TextFields, a NumberField, the select trigger, the segmented
+// control. EVERY WRITE IS ONE UNDO STEP through `store.edit` and the pure
+// part and sketch ops, so this panel needs no store verb of its own, and a
+// value written back unchanged is no step at all (the ops return the same
+// document). A VIEWER reads it all with the writes off (`LockedControls`).
+import { useEffect, useId, useRef, useState } from "react";
+import type { DragEvent as ReactDragEvent, KeyboardEvent as ReactKeyboardEvent, ReactNode } from "react";
+import { framesToSeconds } from "@dailies-studio/engine";
+import { FieldBox, IconChevronDown, IconClose, LockedControls, NumberField, SegmentedControl, TextField, useLocked } from "@dailies-studio/ui";
+import {
+  STORYBOARD_BEATS_MAX,
+  STORYBOARD_VOICE_MAX,
+  isRequirement,
+  referenceImportanceOf,
+  updatePart,
+  updateSketch,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, ReferenceItem3D, StoryboardBeat3D, StoryboardPart3D, StoryboardSketch3D } from "@dailies-studio/shot/doc";
+import { useShotEditor, useStore } from "../../state/context.js";
+import {
+  SHOT_STATUS_LABEL,
+  boardShots,
+  cardKindOf,
+  cutLabel,
+  shotStatusOf,
+  storyEntries,
+  styleItemsOf,
+} from "../../state/storyboardModel.js";
+import type { ShotStatus } from "../../state/storyboardModel.js";
+import { useImageThumb } from "../../state/imageThumbs.js";
+import { brandBackdrop } from "../../bridgeTypes.js";
+import { ADD_ICON, SPARKLES_ICON } from "../../icons.js";
+import { TransitionRows } from "../inspector/scene/TransitionSection.js";
+import { useScrub } from "../inspector/useDocWrite.js";
+import { formatDuration } from "../timeline/model.js";
+import { assetUrl, pinGlyph } from "./ReferencePreview.js";
+import { writeDrag } from "./storyboardDrop.js";
+import "./plan.css";
+import { useBuildingParts } from "../agent/AgentDots.js";
+
+/** A beat row's own drag type: a reorder inside one list, never a board card. */
+const BEAT_MIME = "application/x-dailies-plan-beat";
+
+/** The badge tone each status reads in (G1 `.badge`). */
+const STATUS_TONE: Record<ShotStatus, string> = { planned: "", building: " is-building", built: " is-success" };
+
+/** "02": a planned shot's place in playing order, or null when it has none. */
+export function partNumberOf(doc: Doc3D, partId: string): string | null {
+  const at = storyEntries(doc).findIndex((e) => (e.kind === "shot" ? e.shot.part?.id : e.part.id) === partId);
+  return at < 0 ? null : String(at + 1).padStart(2, "0");
+}
+
+/** Typed seconds ("2", "2.5s") or frames ("48f") back to frames, or null. */
+export function parseLength(text: string, fps: number): number | null {
+  const m = /^\s*(\d+(?:\.\d+)?|\.\d+)\s*(s|f)?\s*$/i.exec(text);
+  if (m === null) return null;
+  const n = Number(m[1]);
+  const frames = m[2]?.toLowerCase() === "f" ? n : n * fps;
+  return Number.isFinite(frames) && frames > 0 ? frames / fps : null;
+}
+
+/** The beats with `at` moved to `to`, both clamped. */
+export function moveBeat(beats: readonly StoryboardBeat3D[], at: number, to: number): StoryboardBeat3D[] {
+  const next = [...beats];
+  const target = Math.max(0, Math.min(next.length - 1, to));
+  if (at < 0 || at >= next.length || target === at) return next;
+  const [beat] = next.splice(at, 1);
+  next.splice(target, 0, beat!);
+  return next;
+}
+
+/** A trimmed text field's value as a patch: null drops the key. */
+const textPatch = (text: string, max?: number): string | null => {
+  const trimmed = text.trim();
+  if (trimmed === "") return null;
+  return max === undefined ? trimmed : trimmed.slice(0, max).trim();
+};
+
+/**
+ * A PLANNED SHOT'S NAME, AND ITS RENAME, wherever the shot is named: the head
+ * of its Plan panel on the board, and the shot board's bar. The name is a
+ * button and the rename is the store's (`storyboardRenaming`), so F2 (on the
+ * board with the shot picked, or on its shot board), a double-click on the
+ * name, and Enter or F2 on the name with the keyboard all open the one field.
+ * A single press does nothing: it is a name, read far more than renamed. A
+ * viewer cannot rename, so for them it is plain words: a focusable button
+ * that did nothing and never said why was a dead stop on every Tab.
+ */
+export function PartName(props: { part: StoryboardPart3D; className: string; testId?: string }) {
+  const store = useStore();
+  const readOnly = useShotEditor((s) => s.readOnly);
+  const renaming = useShotEditor((s) => s.storyboardRenaming === props.part.id);
+  const name = useRef<HTMLButtonElement>(null);
+  // A RENAME CLOSED FROM THE KEYBOARD HANDS THE FOCUS BACK TO THE NAME. Enter
+  // and Escape blur the field, which then unmounts with nothing focused, so
+  // the focus fell to the page and the next Tab started from its top. A click
+  // away keeps the focus where the click put it.
+  const refocus = useRef(false);
+  useEffect(() => {
+    if (renaming || !refocus.current) return;
+    refocus.current = false;
+    name.current?.focus();
+  }, [renaming]);
+  if (renaming && !readOnly) {
+    return (
+      <PartRename
+        key={props.part.id}
+        part={props.part}
+        onKeyClose={() => {
+          refocus.current = true;
+        }}
+      />
+    );
+  }
+  if (readOnly) {
+    return (
+      <span
+        className={props.className}
+        {...(props.testId === undefined ? {} : { "data-testid": props.testId })}
+        title={props.part.label}
+      >
+        {props.part.label}
+      </span>
+    );
+  }
+  const open = (): void => store.beginStoryboardRename(props.part.id);
+  return (
+    <button
+      ref={name}
+      type="button"
+      className={props.className}
+      {...(props.testId === undefined ? {} : { "data-testid": props.testId })}
+      title={`${props.part.label}: double-click or F2 to rename`}
+      onDoubleClick={open}
+      // A press with no pointer behind it (`detail` 0) is assistive tech's,
+      // which has no double press to give: it opens the rename too.
+      onClick={(event) => {
+        if (event.detail === 0) open();
+      }}
+      onKeyDown={(event) => {
+        if (event.key !== "F2" && event.key !== "Enter") return;
+        event.preventDefault();
+        event.stopPropagation();
+        open();
+      }}
+    >
+      {props.part.label}
+    </button>
+  );
+}
+
+/**
+ * The open rename. It commits on Enter or on a blur that changed the name,
+ * and it CLOSES on every blur and on Escape: TextField commits only a change,
+ * so the field used to stay open under a click away or an Escape, with
+ * nothing else to close it (the window's keys pass a focused field by).
+ * `onKeyClose` hears Enter and Escape in the CAPTURE phase, before the field
+ * blurs itself on them, so the name knows to take the focus back.
+ */
+function PartRename({ part, onKeyClose }: { part: StoryboardPart3D; onKeyClose(): void }) {
+  const store = useStore();
+  const close = (): void => {
+    if (store.getState().storyboardRenaming === part.id) store.beginStoryboardRename(null);
+  };
+  return (
+    <span
+      className="plan-rename"
+      onBlur={close}
+      onKeyDownCapture={(event) => {
+        if (event.key === "Enter" || event.key === "Escape") onKeyClose();
+      }}
+    >
+      <TextField
+        autoFocus
+        value={part.label}
+        ariaLabel="Shot name"
+        onCommit={(text) => {
+          const label = text.trim();
+          if (label !== "" && label !== part.label) store.updateStoryboardPart(part.id, { label });
+        }}
+      />
+    </span>
+  );
+}
+
+export function PlanPanel(props: {
+  partId: string;
+  /** "shot" is the shot board's head (SB2), "board" the board's (SB1). */
+  variant?: "shot" | "board";
+  /** The sketch Ground writes and "on sketch" reads. Default: Sketch 1. */
+  sketchId?: string;
+  /** Replaces the default footer. */
+  footer?: ReactNode;
+}) {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const readOnly = useShotEditor((s) => s.readOnly);
+  const building = useBuildingParts();
+  const variant = props.variant ?? "shot";
+  const part = doc?.storyboard?.parts.find((p) => p.id === props.partId);
+  if (doc === null || part === undefined) return null;
+
+  const write = (patch: Parameters<typeof updatePart>[2]): void => {
+    store.edit((base) => updatePart(base, part.id, patch));
+  };
+  const number = partNumberOf(doc, part.id);
+  const sketch = part.sketches?.find((s) => s.id === props.sketchId) ?? part.sketches?.[0];
+  const footer =
+    props.footer !== undefined ? (
+      <footer className="panel-foot">{props.footer}</footer>
+    ) : variant === "shot" ? (
+      <footer className="panel-foot is-note">
+        {SPARKLES_ICON}
+        The agent reads the plan and sketches.
+      </footer>
+    ) : null;
+
+  return (
+    <section className="plan-panel" data-testid="plan-panel" aria-label="Plan">
+      {variant === "shot" ? (
+        <header className="panel-head plan-head">
+          <h3 className="caps">Plan</h3>
+          {number === null ? null : <span className="plan-head-shot">{`Shot ${number}`}</span>}
+        </header>
+      ) : (
+        <header className="panel-head plan-head">
+          {number === null ? null : <span className="plan-head-number">{number}</span>}
+          <h3 className="plan-head-title">
+            <PartName part={part} className="plan-head-name" />
+          </h3>
+          <StatusBadge status={shotStatusOf(part, building)} />
+        </header>
+      )}
+      <LockedControls value={readOnly}>
+        {/* KEYED ON THE PART: another shot starts with no beat draft and the
+            cut rows closed, never the last shot's. */}
+        <div className="plan-body" key={part.id}>
+          <div className="plan-field">
+            <h4 className="caps">What we see</h4>
+            <TextField
+              multiline
+              value={part.notes ?? ""}
+              placeholder="What the viewer sees in this shot"
+              ariaLabel="What we see"
+              onCommit={(text) => write({ notes: textPatch(text) })}
+            />
+          </div>
+          <Beats part={part} onWrite={(motion) => write({ motion })} />
+          <div className="plan-field">
+            <h4 className="caps">Voice</h4>
+            <TextField
+              value={part.voice ?? ""}
+              placeholder="The line we hear"
+              ariaLabel="Voice"
+              onCommit={(text) => write({ voice: textPatch(text, STORYBOARD_VOICE_MAX) })}
+            />
+          </div>
+          <Timing doc={doc} part={part} onLength={(durationFrames) => write({ durationFrames })} />
+          {sketch === undefined ? null : <Ground doc={doc} sketch={sketch} />}
+          <Pinned doc={doc} part={part} sketch={sketch} />
+          <StyleRow count={styleItemsOf(doc).length} />
+        </div>
+      </LockedControls>
+      {footer}
+    </section>
+  );
+}
+
+function StatusBadge({ status }: { status: ShotStatus }) {
+  return (
+    <span className={`badge${STATUS_TONE[status]}`} data-testid="plan-status">
+      {SHOT_STATUS_LABEL[status]}
+    </span>
+  );
+}
+
+// ── HOW IT MOVES ────────────────────────────────────────────────────────
+
+function Beats(props: { part: StoryboardPart3D; onWrite(motion: StoryboardBeat3D[] | null): void }) {
+  const beats = props.part.motion ?? [];
+  const readOnly = useShotEditor((s) => s.readOnly);
+  // The remove buttons write, so the panel's lock takes them with the fields.
+  const locked = useLocked();
+  const [adding, setAdding] = useState(false);
+  const dragFrom = useRef<number | null>(null);
+  const focusAt = useRef<number | null>(null);
+  const list = useRef<HTMLOListElement>(null);
+  const full = beats.length >= STORYBOARD_BEATS_MAX;
+  const write = (next: StoryboardBeat3D[]): void => props.onWrite(next.length === 0 ? null : next);
+
+  // An emptied beat is removed: a beat's text is never stored empty.
+  const setText = (at: number, text: string): void => {
+    const trimmed = text.trim();
+    if (trimmed === beats[at]?.text) return;
+    write(trimmed === "" ? beats.filter((_, i) => i !== at) : beats.map((b, i) => (i === at ? { ...b, text: trimmed } : b)));
+  };
+  const move = (at: number, to: number): void => {
+    if (to < 0 || to >= beats.length || to === at) return;
+    write(moveBeat(beats, at, to));
+  };
+  const onKey = (at: number) => (event: ReactKeyboardEvent) => {
+    if (!event.altKey || readOnly || (event.key !== "ArrowUp" && event.key !== "ArrowDown")) return;
+    event.preventDefault();
+    const to = at + (event.key === "ArrowUp" ? -1 : 1);
+    if (to < 0 || to >= beats.length) return;
+    focusAt.current = to;
+    move(at, to);
+  };
+  // THE FOCUS FOLLOWS THE MOVED BEAT: the move re-keys its row, so a second
+  // Alt+arrow would otherwise press nothing.
+  useEffect(() => {
+    const to = focusAt.current;
+    if (to === null) return;
+    focusAt.current = null;
+    list.current?.querySelector<HTMLElement>(`[aria-label="Beat ${to + 1}"]`)?.focus();
+  });
+  const onDrop = (at: number) => (event: ReactDragEvent) => {
+    const from = dragFrom.current;
+    dragFrom.current = null;
+    if (from === null || !event.dataTransfer.types.includes(BEAT_MIME)) return;
+    event.preventDefault();
+    move(from, at);
+  };
+
+  return (
+    <div className="plan-field">
+      <div className="plan-field-head">
+        <h4 className="caps">How it moves</h4>
+        <span className="plan-count">{beats.length === 1 ? "1 beat" : `${beats.length} beats`}</span>
+      </div>
+      <ol ref={list} className="plan-beats" aria-label="How it moves">
+        {beats.map((beat, at) => (
+          <li
+            // Text, then place: a reorder re-keys the moved rows, so a draft
+            // never follows the wrong beat.
+            key={`${at}:${beat.text}`}
+            className="plan-beat"
+            data-testid="plan-beat"
+            draggable={!readOnly}
+            title="Drag, or Alt+arrow, to reorder"
+            onDragStart={(event) => {
+              dragFrom.current = at;
+              event.dataTransfer.setData(BEAT_MIME, String(at));
+              event.dataTransfer.effectAllowed = "move";
+            }}
+            onDragOver={(event) => {
+              if (dragFrom.current === null) return;
+              event.preventDefault();
+              event.dataTransfer.dropEffect = "move";
+            }}
+            onDrop={onDrop(at)}
+            onDragEnd={() => {
+              dragFrom.current = null;
+            }}
+            onKeyDown={onKey(at)}
+          >
+            <span className="plan-beat-number">{at + 1}</span>
+            {/* THE ROW'S VERB IS INSIDE THE BEAT'S BOX, the house accessory
+                lane (`FieldBox`): a 16px key with the remove glyph that turns
+                to the danger ink under the pointer. So every beat's box ends
+                on one right edge, the open draft's too, which has no verb. */}
+            <FieldBox
+              trailing={
+                <button
+                  type="button"
+                  className="insp-key is-danger"
+                  aria-label={`Remove beat ${at + 1}`}
+                  title="Remove beat"
+                  disabled={locked}
+                  onClick={() => write(beats.filter((_, i) => i !== at))}
+                >
+                  <IconClose />
+                </button>
+              }
+            >
+              <TextField value={beat.text} ariaLabel={`Beat ${at + 1}`} onCommit={(text) => setText(at, text)} />
+            </FieldBox>
+          </li>
+        ))}
+        {adding ? (
+          // Any blur ends the draft (Enter, Escape, a click away); the field's
+          // own blur commits first, and an empty draft writes nothing.
+          <li className="plan-beat is-draft" onBlur={() => setAdding(false)}>
+            <span className="plan-beat-number">{beats.length + 1}</span>
+            <FieldBox>
+              <TextField
+                value=""
+                autoFocus
+                placeholder="What moves next"
+                ariaLabel={`Beat ${beats.length + 1}`}
+                onCommit={(text) => {
+                  const trimmed = text.trim();
+                  if (trimmed !== "" && !full) write([...beats, { text: trimmed }]);
+                }}
+              />
+            </FieldBox>
+          </li>
+        ) : null}
+      </ol>
+      {adding ? null : (
+        <button
+          type="button"
+          className="plan-add-beat"
+          data-testid="plan-add-beat"
+          disabled={locked || full}
+          title={full ? `A shot holds at most ${STORYBOARD_BEATS_MAX} beats` : undefined}
+          onClick={() => setAdding(true)}
+        >
+          <span className="plan-add-beat-icon" aria-hidden="true">
+            {ADD_ICON}
+          </span>
+          Add beat
+        </button>
+      )}
+    </div>
+  );
+}
+
+// ── LENGTH AND CUT TO NEXT ──────────────────────────────────────────────
+
+function Timing(props: { doc: Doc3D; part: StoryboardPart3D; onLength(frames: number): void }) {
+  const { doc, part } = props;
+  const [open, setOpen] = useState(false);
+  const rowsId = useId();
+  const fps = doc.fps.num / doc.fps.den;
+  const seconds = framesToSeconds(part.durationFrames, doc.fps);
+  const sceneId = part.scene !== undefined && doc.scenes.includes(part.scene) ? part.scene : null;
+  const shot = sceneId === null ? undefined : boardShots(doc).find((s) => s.sceneId === sceneId);
+  const label = shot === undefined ? "Cut" : cutLabel(doc, shot);
+  // "Wipe 0.40s": the name, then the played length in the numeric face.
+  const split = /^(.*?)\s(\d+\.\d{2}s)$/.exec(label);
+  /** Seconds on the field to whole frames, never below one. */
+  const framesOf = (next: number): number => Math.max(1, Math.round(next * fps));
+  // A DRAG ON THE LENGTH writes live, in one undo step, so the shot card's
+  // length and the board's total move with the pointer.
+  const lengthScrub = useScrub((base, raw) =>
+    typeof raw === "number" && Number.isFinite(raw) ? updatePart(base, part.id, { durationFrames: framesOf(raw) }) : base,
+  );
+  return (
+    <>
+      <div className="plan-timing">
+        <div className="plan-field plan-length">
+          <h4 className="caps">Length</h4>
+          <NumberField
+            value={seconds}
+            min={1 / fps}
+            step={1 / fps}
+            format={formatDuration}
+            parse={(text) => parseLength(text, fps)}
+            ariaLabel="Length"
+            onCommit={(next) => props.onLength(framesOf(next))}
+            onScrubStart={lengthScrub.start}
+            onScrub={lengthScrub.move}
+            onScrubEnd={lengthScrub.end}
+          />
+        </div>
+        <div className="plan-field plan-cut">
+          <h4 className="caps">Cut to next</h4>
+          {/* THE HOUSE SELECT TRIGGER, the Combobox's own anatomy (the value
+              ellipsized, its caret), on a button that discloses the cut's
+              rows under it rather than a list: the cut is edited with the
+              Studio's own transition rows, not picked from a menu. */}
+          <button
+            type="button"
+            className="select combobox-trigger plan-cut-select"
+            data-testid="plan-cut"
+            // NAMED BY ITS LABEL, then by what it shows: the caps label over it
+            // is a heading, so the button alone read "Wipe 0.40s".
+            aria-label={`Cut to next: ${label}`}
+            {...(sceneId === null ? {} : { "aria-expanded": open, "aria-controls": rowsId })}
+            disabled={sceneId === null}
+            title={sceneId === null ? "Set once this shot has a Shot in Studio" : "Edit the cut into the next shot"}
+            onClick={() => setOpen((was) => !was)}
+          >
+            <span className="combobox-value">{split?.[1] ?? label}</span>
+            {split === null ? null : <span className="plan-cut-length">{split[2]}</span>}
+            <IconChevronDown className="combobox-caret field-caret" />
+          </button>
+        </div>
+      </div>
+      {open && sceneId !== null ? (
+        <div className="plan-cut-rows" id={rowsId} data-testid="plan-cut-rows">
+          <TransitionRows sceneId={sceneId} lengthLabel="Length" />
+        </div>
+      ) : null}
+    </>
+  );
+}
+
+// ── GROUND ──────────────────────────────────────────────────────────────
+
+function Ground(props: { doc: Doc3D; sketch: StoryboardSketch3D }) {
+  const store = useStore();
+  const { sketch } = props;
+  const brand = brandBackdrop(props.doc);
+  const swatch = (tone: string, colour?: string): ReactNode => (
+    <span className={`plan-swatch is-${tone}`} aria-hidden="true" style={colour === undefined ? undefined : { background: colour }} />
+  );
+  return (
+    <div className="plan-field">
+      <h4 className="caps">Ground</h4>
+      <SegmentedControl
+        ariaLabel="Ground"
+        value={sketch.ground ?? "paper"}
+        options={[
+          { value: "paper", label: <>{swatch("paper")}Paper</> },
+          { value: "dark", label: <>{swatch("dark")}Dark</> },
+          // The Project's brand colour when it has one (Paper Q10).
+          { value: "brand", label: <>{swatch("brand", brand ?? undefined)}Brand</> },
+        ]}
+        // Paper is the absent key; the lit chip pressed again writes nothing
+        // (`updateSketch` returns the same document).
+        onChange={(value) => store.edit((base) => updateSketch(base, sketch.id, { ground: value === "dark" || value === "brand" ? value : null }))}
+      />
+    </div>
+  );
+}
+
+// ── PINNED TO THIS SHOT ─────────────────────────────────────────────────
+
+/** A card kind as the row says it: "Image", "Component". */
+const kindWord = (item: ReferenceItem3D, assets: Doc3D["assets"]): string => {
+  const kind = cardKindOf(item, assets);
+  return kind.charAt(0).toUpperCase() + kind.slice(1);
+};
+
+function Pinned(props: { doc: Doc3D; part: StoryboardPart3D; sketch: StoryboardSketch3D | undefined }) {
+  const { doc, part, sketch } = props;
+  const readOnly = useShotEditor((s) => s.readOnly);
+  const pins = (doc.resources?.references ?? []).filter((r) => r.part === part.id);
+  const onSketch = new Set((sketch?.items ?? []).flatMap((item) => (item.kind === "ref" ? [item.ref] : [])));
+  return (
+    <div className="plan-field">
+      <div className="plan-field-head">
+        <h4 className="caps">Pinned to this shot</h4>
+        <span className="plan-count is-numeric">{pins.length}</span>
+      </div>
+      {pins.length === 0 ? (
+        <p className="plan-none">Nothing pinned yet. Drop cards on this shot.</p>
+      ) : (
+        <ul className="plan-pins" aria-label="Pinned to this shot">
+          {pins.map((item) => (
+            <PinRow key={item.id} doc={doc} item={item} onSketch={onSketch.has(item.id)} readOnly={readOnly} />
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+function PinRow(props: { doc: Doc3D; item: ReferenceItem3D; onSketch: boolean; readOnly: boolean }) {
+  const { doc, item } = props;
+  const asset = item.type === "asset" ? doc.assets[item.asset] : undefined;
+  const image = asset?.kind === "image" ? asset : undefined;
+  const thumb = useImageThumb(image === undefined ? "" : assetUrl(image.path), image?.hash ?? "", 20);
+  const name = item.label.trim() || "Untitled card";
+  const must = referenceImportanceOf(item) === "must";
+  return (
+    <li
+      className="plan-pin"
+      data-testid={`plan-pin-${item.id}`}
+      draggable={!props.readOnly}
+      title={props.readOnly ? undefined : "Drag onto the sketch"}
+      onDragStart={(event) => writeDrag(event.dataTransfer, { kind: "reference", id: item.id })}
+    >
+      <span className="plan-pin-thumb" aria-hidden="true">
+        {image === undefined ? pinGlyph(item) : thumb === null ? null : <img src={thumb} alt="" draggable={false} />}
+      </span>
+      <span className="plan-pin-name">{name}</span>
+      {props.onSketch ? (
+        <span className="plan-pin-on" data-testid="plan-pin-on-sketch">
+          on sketch
+        </span>
+      ) : null}
+      {isRequirement(item) ? <span className={`badge${must ? " is-accent" : ""}`}>{must ? "Must" : "Optional"}</span> : null}
+      <span className="plan-pin-kind">{kindWord(item, doc.assets)}</span>
+    </li>
+  );
+}
+
+// ── STYLE ───────────────────────────────────────────────────────────────
+
+/** How many Style cards every shot reads. The Style wall sits on the board's
+ *  desk itself, so the row says the count and links nowhere. */
+function StyleRow(props: { count: number }) {
+  const { count } = props;
+  return (
+    <div className="plan-style" data-testid="plan-style">
+      <h4 className="caps">Style</h4>
+      <p className="plan-style-text">
+        {count === 0 ? "No Style cards yet" : `${count} ${count === 1 ? "item applies" : "items apply"} to every shot`}
+      </p>
+    </div>
+  );
+}