@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/storyboard/board.ts

@@ -0,0 +1,12 @@
+// THE STORYBOARD'S CHUNK: the board, the shot board, the drop dialog, and the
+// panels the board puts in the right column, the inspector's card section
+// among them. Loaded on demand through app/lazySurfaces.tsx and nowhere else,
+// so all of it, its stylesheet included, leaves the /scene entry. Studio's
+// Brief (ShotBrief) is not here: it is a Studio panel.
+import "./board.css";
+
+export { StoryboardView } from "./StoryboardView.js";
+export { ComponentSheet } from "./ComponentSheet.js";
+export { PlanOccupant } from "./BoardPlan.js";
+export { SketchInspector } from "./shotboard/SketchInspector.js";
+export { StoryboardReferenceSection } from "../inspector/storyboard/StoryboardReferenceSection.js";

package/src/panels/storyboard/boardClipboard.ts

@@ -0,0 +1,111 @@
+// THE BOARD'S CLIPBOARD: copy, cut and paste of cards and sketch items.
+//
+// Its own file because TWO documents bind it, the chrome's (StoryboardView)
+// and the stage iframe's (StagePanel), and the stage panel loads with the
+// shell while the board is a chunk of its own.
+import type { ShotEditorStore } from "../../state/store.js";
+import { isReferenceId } from "../../state/storyboardModel.js";
+import { shotBoardOf, workspaceOf } from "../../state/workspace.js";
+import { CLIP_MARKER, STORYBOARD_MIME, urlFromTransfer } from "./storyboardDrop.js";
+
+/** What a copy of sketch items marks the clipboard with. Its own type, not
+ *  `STORYBOARD_MIME`, so a card paste never takes it, nor it a card clip. */
+export const SKETCH_MIME = "application/x-dailies-sketch";
+
+/**
+ * The board's copy, cut and paste, bound on one document until `signal`
+ * aborts. TWO DOCUMENTS bind it: the chrome's (StoryboardView) and the stage
+ * iframe's (StagePanel). The pointer on the frame focuses the stage, and the native
+ * event then fires in ITS document, so a chrome-only binding left ⌘C ⌘V on a
+ * layer dead. Each event checks the board is the workspace, because the stage
+ * document outlives the board.
+ */
+export function bindBoardClipboard(doc: Document, store: ShotEditorStore, signal: AbortSignal): void {
+  const on = (): boolean => workspaceOf(store.getState()) === "storyboard";
+  /** Is this event aimed at something an author is typing into? A note card's
+   *  own text, or the stage's text editor, must still copy and paste as text.
+   *  Duck-typed: a stage element is not this realm's `HTMLElement`. */
+  const isField = (target: EventTarget | null): boolean => {
+    const el = target as Partial<HTMLElement> | null;
+    return el?.tagName === "INPUT" || el?.tagName === "TEXTAREA" || el?.isContentEditable === true;
+  };
+  /** A RANGE OF TEXT BEATS THE BOARD. Without this, selecting a timecode or a
+   *  label anywhere in the chrome and pressing ⌘C would copy the board's cards
+   *  instead of the words under the cursor. */
+  const hasTextSelection = (): boolean => doc.getSelection()?.isCollapsed === false;
+
+  const onPaste = (event: ClipboardEvent): void => {
+    if (!on() || isField(event.target)) return;
+    const sketching = shotBoardOf(store.getState()) !== null;
+    const all = Array.from(event.clipboardData?.files ?? []);
+    if (all.length > 0) {
+      // FILES open the drop dialog (S2), which asks where they count. Never a
+      // fall-through to the board clip, which would paste a copy of whatever
+      // was copied last. On a shot board they are the sketch's: each lands as
+      // a pinned card and its item, with no dialog.
+      event.preventDefault();
+      if (sketching) void store.addSketchItemsFromFiles(all);
+      else store.openBoardDrop(all);
+      return;
+    }
+    // THE BOARD'S OWN CLIPS go back as they were copied, and a stale clip is
+    // never pasted: only under its marker.
+    const data = event.clipboardData;
+    const types = Array.from(data?.types ?? []);
+    if (sketching && types.includes(SKETCH_MIME)) {
+      event.preventDefault();
+      store.pasteSketchItems();
+      return;
+    }
+    if (types.includes(STORYBOARD_MIME)) {
+      event.preventDefault();
+      store.pasteStoryboardItems();
+      return;
+    }
+    // A LINK OR WORDS from anywhere else land on the Style wall: a link card,
+    // else a note.
+    if (data === null) return;
+    const url = urlFromTransfer(data);
+    if (url !== null) {
+      event.preventDefault();
+      store.addLinkReference(url, null, { select: false });
+      return;
+    }
+    const text = data.getData("text/plain").trim();
+    if (text === "") return;
+    event.preventDefault();
+    store.addStoryboardNote(null, { select: false, text });
+  };
+
+  /** A copy, or a cut that also deletes. Both write the clip's marker, so a
+   *  paste, which takes the clip only under it, takes cards copied anywhere
+   *  on the board. */
+  const clip = (event: ClipboardEvent, cut: boolean): void => {
+    if (!on() || isField(event.target) || hasTextSelection()) return;
+    // ON A SHOT BOARD, the sketch items selected: onto the shot board's own
+    // clip, which a paste on any sketch takes back.
+    const state = store.getState();
+    if (shotBoardOf(state) !== null) {
+      const items = state.sketchSelection;
+      if (items.length === 0) return;
+      event.preventDefault();
+      event.clipboardData?.setData(SKETCH_MIME, CLIP_MARKER);
+      store.copySketchItems(items);
+      if (cut) store.removeSketchItems(items);
+      return;
+    }
+    // The CARDS in the selection. A press on a lane head selects the planned
+    // shot, and a cut of that would copy nothing and then delete the lane, its
+    // cards thrown to Global. Nothing to copy leaves the event alone.
+    const ids = store.getState().storyboardSelection.filter(isReferenceId);
+    if (ids.length === 0) return;
+    event.preventDefault();
+    event.clipboardData?.setData(STORYBOARD_MIME, CLIP_MARKER);
+    store.copyStoryboardItems(ids);
+    if (cut) store.deleteStoryboardItems(ids);
+  };
+
+  doc.addEventListener("copy", (event) => clip(event, false), { signal });
+  doc.addEventListener("cut", (event) => clip(event, true), { signal });
+  doc.addEventListener("paste", onPaste, { signal });
+}

package/src/panels/storyboard/boardOrder.ts

@@ -0,0 +1,68 @@
+// THE BOARD'S ORDER, MOVED BY A DRAG (Paper SB1): a shot card dropped between
+// two others. Pure, so the drop and the tests read one answer.
+//
+// TWO ARRAYS SAY THE ORDER. A planned shot's place is its index in
+// `storyboard.parts` (`movePart`); a Shot's place is its index in the playing
+// order `doc.scenes` (`reorderScene`), and `storyEntries` places the planned
+// shots with no Shot around the Shots by part order. So a move writes both:
+// the parts in the new reading order, and the Shots in it too. Moving a built
+// shot on the board moves it in the film, which is the point: one order.
+//
+// A SHOT NO PLAN LINKS has no index in the parts, so a planned shot with no
+// Shot could not be placed beside it: `storyEntries` would put it by the
+// nearest linked Shot instead, and the drop would land somewhere else. Only
+// then does the move give each such Shot its planned shot first
+// (`pinPartFor`, as a drop on its card does), in the same edit; a move the
+// two arrays can say as they are adds no part.
+import { movePart, pinPartFor, reorderScene } from "@dailies-studio/shot/doc";
+import type { Doc3D } from "@dailies-studio/shot/doc";
+import { storyEntries } from "../../state/storyboardModel.js";
+import type { StoryEntry } from "../../state/storyboardModel.js";
+
+/** The id a card selects and drags under: its planned shot, else its Shot. */
+export function entryIdOf(entry: StoryEntry): string {
+  return entry.kind === "shot" ? (entry.shot.part?.id ?? entry.shot.sceneId) : entry.part.id;
+}
+
+/**
+ * `doc` with the card `id` moved to `slot`: the gap before the card now at
+ * `slot` in `entries` (`entries.length` is the end). The same document when
+ * nothing moves.
+ */
+export function moveBoardEntry(doc: Doc3D, entries: readonly StoryEntry[], id: string, slot: number): Doc3D {
+  const from = entries.findIndex((entry) => entryIdOf(entry) === id);
+  if (from < 0) return doc;
+  const at = Math.max(0, Math.min(entries.length, Math.trunc(slot)));
+  const to = at > from ? at - 1 : at;
+  if (to === from) return doc;
+  const next = [...entries];
+  const [moved] = next.splice(from, 1);
+  next.splice(to, 0, moved!);
+  const plain = placeInOrder(doc, next, false);
+  const want = next.map(entryIdOf).join(" ");
+  return storyEntries(plain).map(entryIdOf).join(" ") === want ? plain : placeInOrder(doc, next, true);
+}
+
+/** Both arrays in `order`, each placed at its index in turn: everything
+ *  before it is already in place, so they end in exactly that order. With
+ *  `pin`, a Shot no plan links gets its planned shot first. */
+function placeInOrder(doc: Doc3D, order: readonly StoryEntry[], pin: boolean): Doc3D {
+  let out = doc;
+  const partIds = order.flatMap((entry): string[] => {
+    if (entry.kind === "placeholder") return [entry.part.id];
+    if (entry.shot.part !== null) return [entry.shot.part.id];
+    const pinned = pin ? pinPartFor(out, entry.shot.sceneId) : null;
+    if (pinned === null) return [];
+    out = pinned.doc;
+    return [pinned.part];
+  });
+  partIds.forEach((partId, index) => {
+    out = movePart(out, partId, index);
+  });
+  order
+    .flatMap((entry) => (entry.kind === "shot" ? [entry.shot.sceneId] : []))
+    .forEach((sceneId, index) => {
+      out = reorderScene(out, sceneId, index);
+    });
+  return out;
+}

package/src/panels/storyboard/boardRows.tsx

@@ -0,0 +1,425 @@
+// THE BOARD'S SHARED PARTS, one home for what the board and its panels all
+// draw: the press policy, the requirement's rows and action slot, the card-use
+// block and the read-only row.
+import { useRef, useState } from "react";
+import type { ReactNode } from "react";
+import {
+  REFERENCE_IMPORTANCES,
+  REFERENCE_IMPORTANCE_SPECS,
+  REFERENCE_USES,
+  REFERENCE_USE_SPECS,
+  REQUIREMENT_STATUS_SPECS,
+  referenceImportanceOf,
+  referenceUseOf,
+  requirementStatus,
+  updateReference,
+} from "@dailies-studio/shot/doc";
+import type { Doc3D, ReferenceItem3D } from "@dailies-studio/shot/doc";
+import { IconUndo, InspectorRow, NumberField, SegmentedControl, TextField, useContextMenu, useLocked } from "@dailies-studio/ui";
+import type { MenuEntry } from "@dailies-studio/ui";
+import { useShotEditor, useStore } from "../../state/context.js";
+import { instanceHostRefusal } from "../../state/storyboardModel.js";
+import { useScrub } from "../inspector/useDocWrite.js";
+import { AUDIO_ACCEPT_ATTRIBUTE } from "./storyboardDrop.js";
+
+/** A press's modifiers, all a selection policy reads, and its click count
+ *  (`detail`: 2 on a double press's second press, 0 from a key). */
+export type Press = { shiftKey: boolean; ctrlKey: boolean; metaKey: boolean; detail?: number };
+
+/**
+ * THE SELECTION A PRESS LEAVES, over a list in its visible `order`: Shift
+ * takes the range from the anchor (which stays), Ctrl or Cmd toggles the one
+ * pressed, a plain press selects it alone. Both move the anchor to it. Pure,
+ * so every board list presses one way.
+ */
+export function pressSelection(
+  current: readonly string[],
+  order: readonly string[],
+  anchor: string | null,
+  id: string,
+  event: Press,
+): { selection: string[]; anchor: string | null } {
+  if (event.shiftKey && anchor !== null) {
+    const a = order.indexOf(anchor);
+    const b = order.indexOf(id);
+    if (a !== -1 && b !== -1) return { selection: order.slice(Math.min(a, b), Math.max(a, b) + 1), anchor };
+  }
+  if (event.ctrlKey || event.metaKey) {
+    return { selection: current.includes(id) ? current.filter((x) => x !== id) : [...current, id], anchor: id };
+  }
+  return { selection: [id], anchor: id };
+}
+
+/**
+ * WHAT A REQUIREMENT'S ACTION SLOT OFFERS, and the reason when it offers
+ * nothing. Read straight off `requirementStatus` and the card's planned shot:
+ *
+ *   place       the requirement is missing and Place can write it here
+ *   place-in    a Style card that makes a layer: Place asks which Shot
+ *   in          satisfied: names where, and opens it
+ *   choose-file a sound with no file yet
+ *   none        nothing to do from the row (done, unchecked library, or a
+ *               refusal Place would make anyway), with `reason` as the title
+ */
+export type PlaceActionKind =
+  | { kind: "place"; title: string }
+  | { kind: "place-in"; title: string }
+  | { kind: "in"; sceneId: string; layerId: string | null; label: string }
+  | { kind: "choose-file" }
+  | { kind: "none"; reason: string };
+
+export function placeActionOf(doc: Doc3D, item: ReferenceItem3D, componentHost: (id: string) => string | null): PlaceActionKind {
+  const report = requirementStatus(doc, item);
+  if (report === null) return { kind: "none", reason: "" };
+  const part = item.part === undefined ? undefined : doc.storyboard?.parts.find((p) => p.id === item.part);
+  const linked = part?.scene === undefined ? undefined : doc.scenesById[part.scene];
+  if (report.state === "satisfied") {
+    const sceneId = report.evidence?.scene ?? linked?.id ?? null;
+    const scene = sceneId === null ? undefined : doc.scenesById[sceneId];
+    if (scene !== undefined && sceneId !== null) {
+      return { kind: "in", sceneId, layerId: report.evidence?.layer ?? null, label: `In ${scene.name}` };
+    }
+    return { kind: "none", reason: report.reason };
+  }
+  if (report.state === "done") return { kind: "none", reason: report.reason };
+  if (item.type === "sound" && item.asset === undefined) return { kind: "choose-file" };
+  if (item.type === "library" || item.type === "note") return { kind: "none", reason: report.reason };
+  if (part !== undefined && part.scene === undefined) return { kind: "none", reason: `Create a Shot for ${part.label} first.` };
+  if (part !== undefined && linked === undefined) return { kind: "none", reason: `The Shot ${part.label} was linked to is gone. Link another.` };
+  if (item.type === "component") {
+    const host = item.component === undefined ? null : componentHost(item.component);
+    if (host === null) return { kind: "none", reason: `${item.component ?? item.label} is not in the registry.` };
+    if (host !== "three") return { kind: "none", reason: instanceHostRefusal(host) };
+  }
+  if (part === undefined && item.type !== "transition" && item.type !== "sound") {
+    return { kind: "place-in", title: "Choose the Shot to place it in" };
+  }
+  return { kind: "place", title: linked === undefined ? "Place it in the video" : `Place it in ${linked.name}` };
+}
+
+/**
+ * THE ACTION SLOT, from `placeActionOf`: Place, Place in…
+ * (a menu of Shots), In <Shot> (opens it on the evidence), Choose file… (a
+ * sound that names a need), or a dimmed Place whose title is the reason.
+ * The row and the inspector both draw this, so the two cannot disagree.
+ *
+ * WITH A SHOT (`sceneId`), the slot is that Shot's: a card that would ask
+ * "Place in…" places straight into it, because the author is already in it.
+ */
+export function PlaceAction({ doc, item, sceneId }: { doc: Doc3D; item: ReferenceItem3D; sceneId?: string }) {
+  const store = useStore();
+  const library = useShotEditor((s) => s.library);
+  const report = requirementStatus(doc, item);
+  const action = placeActionOf(doc, item, (id) => library.find((row) => row.id === id)?.host ?? null);
+  const fileRef = useRef<HTMLInputElement | null>(null);
+  const placeIn = useContextMenu();
+  const [busy, setBusy] = useState(false);
+  // A viewer's panel locks the verbs that write (Place, Place in, Choose
+  // file); "In <Shot>" only navigates, so it stays live.
+  const locked = useLocked();
+  const inert = busy || locked;
+  const shot = sceneId === undefined ? undefined : doc.scenesById[sceneId];
+
+  const run = (work: Promise<void>): void => {
+    setBusy(true);
+    void work
+      .catch((e: unknown) => store.reportError(e instanceof Error ? e.message : String(e)))
+      .finally(() => setBusy(false));
+  };
+
+  const openPlaceIn = (at: { x: number; y: number }): void => {
+    const entries: MenuEntry[] = doc.scenes.map((id) => ({
+      kind: "action",
+      id: `ledger-place-in-${id}`,
+      label: doc.scenesById[id]?.name ?? id,
+      onSelect: () => run(store.placeStoryboardItem(item.id, id)),
+    }));
+    if (entries.length === 0) {
+      store.reportError("This Project has no Shot yet. Create one from a planned shot first.");
+      return;
+    }
+    placeIn.open(at, entries);
+  };
+
+  return (
+    <>
+        {action.kind === "place" ? (
+          <button type="button" className="btn" title={action.title} disabled={inert} onClick={() => run(store.placeStoryboardItem(item.id))}>
+            Place
+          </button>
+        ) : action.kind === "place-in" && sceneId !== undefined && shot !== undefined ? (
+          <button
+            type="button"
+            className="btn"
+            title={`Place it in ${shot.name}`}
+            disabled={inert}
+            onClick={() => run(store.placeStoryboardItem(item.id, sceneId))}
+          >
+            Place
+          </button>
+        ) : action.kind === "place-in" ? (
+          <button
+            type="button"
+            className="btn"
+            title={action.title}
+            aria-haspopup="menu"
+            disabled={inert}
+            onClick={(event) => {
+              const r = event.currentTarget.getBoundingClientRect();
+              openPlaceIn({ x: r.left, y: r.bottom + 6 });
+            }}
+          >
+            Place in…
+          </button>
+        ) : action.kind === "in" ? (
+          <button
+            type="button"
+            className="btn ledger-in"
+            title="Open the Shot on what satisfies this"
+            onClick={() => store.openStoryboardShot(action.sceneId, action.layerId)}
+          >
+            {action.label}
+          </button>
+        ) : action.kind === "choose-file" ? (
+          <>
+            <button type="button" className="btn" disabled={inert} onClick={() => fileRef.current?.click()}>
+              Choose file…
+            </button>
+            <input
+              ref={fileRef}
+              type="file"
+              hidden
+              accept={AUDIO_ACCEPT_ATTRIBUTE}
+              data-testid="ledger-sound-file"
+              onChange={(event) => {
+                const file = event.currentTarget.files?.[0];
+                event.currentTarget.value = "";
+                if (file !== undefined) run(store.setSoundFile(item.id, file));
+              }}
+            />
+          </>
+        ) : report?.state === "missing" ? (
+          // A REFUSAL SAYS WHY: dimmed, with Place's own sentence as the title.
+          <button
+            type="button"
+            className="btn"
+            aria-disabled="true"
+            title={action.reason}
+            onClick={() => store.reportError(action.reason)}
+          >
+            Place
+          </button>
+        ) : (
+          <span className="ledger-note" title={action.reason}>
+            {report?.state === "done" ? "Ticked by hand" : action.reason}
+          </span>
+        )}
+      {placeIn.menu}
+    </>
+  );
+}
+
+/**
+ * A READ-ONLY ROW, the house readout (`insp-readout`, widgets.css), the one
+ * the Studio's Time section wears: the field's box on the control ground with
+ * no hover, its value in the numeric face and the second ink. `prose` is a
+ * sentence rather than a measurement (what an item is for, where a still came
+ * from): the body face, wrapping, the row aligned to its first line. It never
+ * wears `inert`, which dimmed the row to 0.55 and set its numbers in the 10px
+ * sans.
+ */
+export function ReadoutRow(props: { label: string; prose?: boolean; title?: string; children: ReactNode }) {
+  return (
+    <InspectorRow label={props.label} className="insp-readout" {...(props.prose === true ? { align: "start" as const } : {})}>
+      <span className={`insp-dim${props.prose === true ? " is-text" : ""}`} {...(props.title === undefined ? {} : { title: props.title })}>
+        {props.children}
+      </span>
+    </InspectorRow>
+  );
+}
+
+/** A requirement's standing as a badge tone (G1 `.badge`): met reads as
+ *  success, Missing in the accent because it asks for work, Unchecked quiet. */
+const REQUIREMENT_TONE: Record<keyof typeof REQUIREMENT_STATUS_SPECS, string> = {
+  satisfied: " is-success",
+  done: " is-success",
+  missing: " is-accent",
+  unchecked: "",
+};
+
+/**
+ * A REQUIREMENT'S STANDING: whether the video has it (derived on this render,
+ * never stored), why, and the two things to do about it: Place and the Done
+ * tick. `PlaceAction` above is the one slot for those verbs, so no two
+ * surfaces offer different verbs for one card. The board inspector and the
+ * component sheet both draw these rows.
+ */
+export function RequirementRows({ doc, item }: { doc: Doc3D; item: ReferenceItem3D }) {
+  const store = useStore();
+  const locked = useLocked();
+  const report = requirementStatus(doc, item);
+  if (report === null) return null;
+  const spec = REQUIREMENT_STATUS_SPECS[report.state];
+  const done = item.done === true;
+  const where = [report.evidence?.scene, report.evidence?.layer, report.evidence?.clip].filter((x) => x !== undefined);
+  return (
+    <>
+      {/* A readout row holding the house badge and the reason, which wraps:
+          the house readout stands the badge 2px short, so a one-line Status
+          row is still 28px tall. */}
+      <InspectorRow label="Status" align="start" className="insp-readout">
+        <span className={`badge${REQUIREMENT_TONE[report.state]}`} data-testid="requirement-status">
+          {spec.label}
+        </span>
+        <span className="insp-dim is-text">
+          {report.reason || spec.title}
+          {where.length === 0 ? "" : ` (${where.map((x) => `#${x}`).join(" ")})`}
+        </span>
+      </InspectorRow>
+      <InspectorRow>
+        <PlaceAction doc={doc} item={item} />
+        <button
+          type="button"
+          className={`btn${done ? " is-active" : ""}`}
+          aria-pressed={done}
+          disabled={locked}
+          title={done ? "Clear the tick: the status goes back to what the video holds" : "Tick it by hand, whatever the video holds"}
+          onClick={() => store.setStoryboardDone(item.id, !done)}
+        >
+          {done ? "Clear done" : "Mark done"}
+        </button>
+      </InspectorRow>
+    </>
+  );
+}
+
+// Both option lists come off the schema's own spec tables, so the control's
+// words, the card's hover text and the agent brief's legend cannot drift.
+const USES = REFERENCE_USES.map((value) => ({
+  value,
+  label: REFERENCE_USE_SPECS[value].label,
+  title: REFERENCE_USE_SPECS[value].title,
+}));
+const IMPORTANCES = REFERENCE_IMPORTANCES.map((value) => ({
+  value,
+  label: REFERENCE_IMPORTANCE_SPECS[value].label,
+  title: REFERENCE_IMPORTANCE_SPECS[value].title,
+}));
+
+/** A typed or dragged frame as the card stores it: a whole, non-negative
+ *  frame, or null for a value that is no number at all. */
+function cardFrameOf(raw: unknown): number | null {
+  return typeof raw === "number" && Number.isFinite(raw) ? Math.max(0, Math.round(raw)) : null;
+}
+
+/**
+ * THE CARD-USE BLOCK, one for every panel a card is picked in: the board
+ * inspector, the component sheet and the shot board's item inspector. It was
+ * three copies in three vocabularies ("Asset | Inspiration" in one, "In the
+ * shot | Look like this" in another, and nothing at all for a component card
+ * on the board, whose one panel is the sheet).
+ *
+ *   Frame       a component card's moment (`frame`): the preview holds it
+ *               instead of looping. Unset reads the dash; the accessory in its
+ *               box clears it, and the preview loops again.
+ *   Use         Asset (a requirement the video must hold) or Inspiration.
+ *   Importance  Must or Optional.
+ *
+ * Each writes null for its own default, so a card nobody has judged carries
+ * no keys, and a press on the lit chip writes nothing (`updateReference`
+ * returns the same document).
+ */
+export function CardUseRows({ card }: { card: ReferenceItem3D }) {
+  const store = useStore();
+  const locked = useLocked();
+  const frameScrub = useScrub((doc, raw) => {
+    const frame = cardFrameOf(raw);
+    return frame === null ? doc : updateReference(doc, card.id, { frame });
+  });
+  const held = card.type === "component" ? card.frame : undefined;
+  return (
+    <>
+      {card.type === "component" ? (
+        <InspectorRow>
+          <NumberField
+            // No frame is the loop, not frame 0: the field says so with its dash.
+            value={held ?? Number.NaN}
+            label="Frame"
+            ariaLabel="Frame, component"
+            min={0}
+            step={1}
+            title="The moment of the component this card means. The preview holds it."
+            onCommit={(next) => {
+              const frame = cardFrameOf(next);
+              if (frame !== null) store.updateReference(card.id, { frame });
+            }}
+            onScrubStart={frameScrub.start}
+            onScrub={frameScrub.move}
+            onScrubEnd={frameScrub.end}
+            trailing={
+              held === undefined ? null : (
+                <button
+                  type="button"
+                  className="insp-key"
+                  aria-label="Clear the component frame"
+                  title="Loop the preview again"
+                  disabled={locked}
+                  onClick={(e) => {
+                    // The clear goes with the frame it clears, and the focus
+                    // fell to <body> with it: it goes to the Frame field the
+                    // clear sat in, which stays.
+                    const field = e.currentTarget.closest(".numfield")?.querySelector<HTMLElement>(".numfield-input");
+                    store.updateReference(card.id, { frame: null });
+                    field?.focus();
+                  }}
+                >
+                  <IconUndo />
+                </button>
+              )
+            }
+          />
+        </InspectorRow>
+      ) : null}
+      <InspectorRow label="Use">
+        <SegmentedControl
+          options={USES}
+          value={referenceUseOf(card)}
+          ariaLabel="Use"
+          onChange={(value) => store.updateReference(card.id, { use: value === "asset" ? "asset" : null })}
+        />
+      </InspectorRow>
+      <InspectorRow label="Importance">
+        <SegmentedControl
+          options={IMPORTANCES}
+          value={referenceImportanceOf(card)}
+          ariaLabel="Importance"
+          onChange={(value) => store.updateReference(card.id, { importance: value === "optional" ? "optional" : null })}
+        />
+      </InspectorRow>
+    </>
+  );
+}
+
+/**
+ * THE CARD'S NOTE TO THE AGENT, the same row wherever the card is picked (the
+ * board inspector, the component sheet, the item inspector): multiline,
+ * trimmed, and dropped when emptied, so a card nobody annotated carries no
+ * key. A note card's own words are its `text`, edited where it is drawn.
+ */
+export function CardNoteRow({ card }: { card: Exclude<ReferenceItem3D, { type: "note" }> }) {
+  const store = useStore();
+  return (
+    <InspectorRow label="Note" align="start">
+      <TextField
+        multiline
+        value={card.note ?? ""}
+        placeholder="What should the agent notice?"
+        ariaLabel="Note"
+        onCommit={(text) => {
+          const note = text.trim();
+          if (note !== (card.note ?? "")) store.updateReference(card.id, { note: note === "" ? null : note });
+        }}
+      />
+    </InspectorRow>
+  );
+}