@anchrd/intel-ui 0.16.0 → 0.17.0

package/src/board/board-detail/board-detail.tsx

@@ -0,0 +1,629 @@
+import { ArchivedBoardStatusId, type BoardTask } from "@anchrd/intel-contract";
+import { useNavigate } from "@tanstack/react-router";
+import { ExternalLink, Plus, Trash2, X } from "lucide-react";
+import { useId, useState } from "react";
+import { useEntryTitle } from "@/agent/agent-entry-title/agent-entry-title.ts";
+import type { BoardHandle } from "@/board/board-data/board-data.types.ts";
+import { labelOf, toneOf } from "@/board/board-status/board-status.ts";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import { EntryPicker } from "@/entry-picker/entry-picker.tsx";
+import { useI18n } from "@/i18n/i18n-context.tsx";
+import { useSessionUser } from "@/user-name/user-name.ts";
+
+// The task and everything under it — the number a delete has to name BEFORE it is confirmed.
+// ⚠️ The same rule the server applies, read off the same field: deleting cascades down `parentId`
+// and answers with a count (#285). That count arrives only WITH the answer, which is too late to
+// ask with — so the question is asked with this, and the server's own number is reported afterwards
+// by the screen (`board.tsx`), which is still there when it arrives.
+export function subtreeSize(taskId: string, childrenOf: Map<string, BoardTask[]>): number {
+  let total = 1;
+  for (const child of childrenOf.get(taskId) ?? []) total += subtreeSize(child.id, childrenOf);
+  return total;
+}
+
+/**
+ * The one detail panel (anchrd/intel#286).
+ *
+ * ⚠️ One panel for every view. A card in a lane, a row in the table, an entry in the month and
+ * a node in the graph open THIS — not four panels that agree today. Every field is a control
+ * rather than a form with a save button, because a board is edited one field at a time and each of
+ * these is one operation on the server (#285).
+ *
+ * ⚠️ Where a task SITS is a move and everything else is an update, and that split is the server's,
+ * not a style choice here: a move mints an order key and re-checks two cycle rules, and folding it
+ * into the field editor would make every typed character pay for them.
+ */
+export function BoardDetail({
+  board,
+  task,
+  close,
+  select,
+}: {
+  board: BoardHandle;
+  task: BoardTask;
+  close(): void;
+  select(taskId: string): void;
+}) {
+  const i18n = useI18n();
+  const navigate = useNavigate();
+  const me = useSessionUser();
+  const headingId = useId();
+  // ⚠️ Four drafts, seeded ONCE. The panel is keyed on the task id (`board.tsx`), so pointing it at
+  // another card remounts it and re-seeds them — an effect on the server's values would do nothing
+  // for that and one thing besides: reset every draft whenever ANY of them round-trips, throwing
+  // away the description somebody was halfway through because the title above it saved.
+  const [title, setTitle] = useState(task.title);
+  const [description, setDescription] = useState(task.description);
+  const [startDate, setStartDate] = useState(task.startDate ?? "");
+  const [dueDate, setDueDate] = useState(task.dueDate ?? "");
+  const [newLabel, setNewLabel] = useState("");
+  const [newSubtask, setNewSubtask] = useState("");
+  /**
+   * Which drafts the reader has actually typed in.
+   *
+   * ⚠️ Without this, leaving a field is enough to write it back. The blur guard compares the draft
+   * against the CURRENT server value, and that value moves underneath an open panel — TanStack
+   * refetches on window focus, and a refused write invalidates. So: an agent renames the task over
+   * MCP, the reader tabs through the title field without touching it, and the blur sees "draft ≠
+   * server" and puts the old title back. The draft has to say whether it is a change at all.
+   */
+  const [edited, setEdited] = useState<Record<string, boolean>>({});
+  const edit = (field: string) => setEdited((current) => ({ ...current, [field]: true }));
+  const settle = (field: string) => setEdited((current) => ({ ...current, [field]: false }));
+  const [addingReference, setAddingReference] = useState(false);
+  const [confirmDelete, setConfirmDelete] = useState(false);
+
+  const children = board.childrenOf.get(task.id) ?? [];
+  /**
+   * ⚠️ Only a refusal about THIS task.
+   *
+   * The mutations live in `useBoard` and are shared by the whole screen — the top bar's create form
+   * is `board.add`, and a drag in a lane is `board.move`. Read as a plain `isError`, a failed
+   * "new task" up there would pin a red `role="alert"` inside every detail panel opened afterwards,
+   * about something that never concerned the task being looked at. `variables` is what the last
+   * call was made with, so the refusal can be attributed instead of assumed.
+   */
+  const failed =
+    [board.update, board.move, board.remove].some(
+      (mutation) => mutation.isError && mutation.variables?.taskId === task.id,
+    ) ||
+    // ⚠️ `add` belongs here too, and it is the one that needed reporting most. The subtask form
+    // below is the only place in the product that can hit `BoardMaxTaskDepth` — a fifth level is
+    // refused — and the form used to clear its field either way, so the refusal looked like a
+    // subtask that had been created and then vanished. Attributed by `parentId`, which is what
+    // separates this form's writes from the "new task" box in the screen's own bar.
+    (board.add.isError && board.add.variables?.parentId === task.id);
+
+  return (
+    <aside
+      aria-labelledby={headingId}
+      className="absolute top-0 right-0 bottom-0 z-20 flex w-96 flex-col overflow-y-auto border-l bg-card shadow-xl"
+    >
+      <div className="flex items-start justify-between gap-3 border-b p-4">
+        <h3 id={headingId} className="text-sm font-semibold">
+          {i18n.t("board.detail")}
+        </h3>
+        <button
+          type="button"
+          onClick={close}
+          aria-label={i18n.t("common.close")}
+          className="rounded-md px-2 py-1 text-muted-foreground outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <X aria-hidden="true" className="size-4" />
+        </button>
+      </div>
+
+      {failed ? (
+        <p role="alert" className="mx-4 mt-4 text-sm text-destructive">
+          {i18n.t("node.operationFailed")}
+        </p>
+      ) : null}
+
+      <div className="flex flex-col gap-5 p-4">
+        <Field label={i18n.t("common.title")}>
+          <input
+            value={title}
+            aria-label={i18n.t("common.title")}
+            onChange={(event) => {
+              setTitle(event.currentTarget.value);
+              edit("title");
+            }}
+            onBlur={() => {
+              if (!edited.title) return;
+              settle("title");
+              const next = title.trim();
+              // Empty is not a title the contract accepts, so the field goes back to what it was
+              // instead of sending a write that is refused.
+              if (next === "") return setTitle(task.title);
+              if (next !== task.title) board.update.mutate({ taskId: task.id, title: next });
+            }}
+            className="w-full rounded-md border bg-background px-2 py-1.5 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          />
+        </Field>
+
+        <Field label={i18n.t("board.column.status")}>
+          <div className="flex items-center gap-2">
+            <span
+              aria-hidden="true"
+              className={`size-2.5 shrink-0 rounded-full ${toneOf(task.status, board.statuses).dot}`}
+            />
+            <select
+              value={task.status}
+              aria-label={i18n.t("board.column.status")}
+              // ⚠️ A move, not an update. Archiving is this same control with `archived` chosen —
+              // there is no separate verb on the server and there is none here either, because it
+              // is not a separate act (#285).
+              // Both neighbours null on purpose: changing the column from here puts the task at the
+              // end of the one it lands in. A position is something a drag names; a select does not
+              // have one to name.
+              onChange={(event) =>
+                board.move.mutate({
+                  taskId: task.id,
+                  status: event.currentTarget.value,
+                  afterTaskId: null,
+                  beforeTaskId: null,
+                })
+              }
+              className="h-8 w-full rounded-md border bg-background px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              {board.statuses.map((status) => (
+                <option key={status.id} value={status.id}>
+                  {status.label}
+                </option>
+              ))}
+            </select>
+          </div>
+        </Field>
+
+        <Field label={i18n.t("board.column.assignee")}>
+          {/* ⚠️ Three choices and no name search, because Intel has no user directory: `/session`
+              answers about the signed-in person and nothing else (`useUserName`). Offering a search
+              box that can only ever find one person would be a worse lie than offering the one
+              person by name. An agent is a node, so it is picked the way every node is. */}
+          <select
+            aria-label={i18n.t("board.column.assignee")}
+            value={
+              task.assignee === null
+                ? ""
+                : task.assignee.type === "agent"
+                  ? `agent:${task.assignee.nodeId}`
+                  : `user:${task.assignee.id}`
+            }
+            onChange={(event) => {
+              const value = event.currentTarget.value;
+              board.update.mutate({
+                taskId: task.id,
+                assignee:
+                  value === ""
+                    ? null
+                    : value.startsWith("agent:")
+                      ? { type: "agent", nodeId: value.slice("agent:".length) }
+                      : { type: "user", id: value.slice("user:".length) },
+              });
+            }}
+            className="h-8 w-full rounded-md border bg-background px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            <option value="">{i18n.t("board.unassigned")}</option>
+            {me ? <option value={`user:${me.id}`}>{i18n.t("board.assignee.me")}</option> : null}
+            {/* An assignee this browser cannot offer again — somebody else's id, or an agent that
+                is gone — stays selectable so that opening the panel does not silently reassign it. */}
+            {task.assignee !== null &&
+            task.assignee.type === "user" &&
+            task.assignee.id !== me?.id ? (
+              <option value={`user:${task.assignee.id}`}>{i18n.t("board.assignee.unnamed")}</option>
+            ) : null}
+            {task.assignee !== null && task.assignee.type === "agent" ? (
+              <AgentOption nodeId={task.assignee.nodeId} />
+            ) : null}
+          </select>
+        </Field>
+
+        <div className="grid grid-cols-2 gap-3">
+          <Field label={i18n.t("board.column.startDate")}>
+            {/* ⚠️ On blur, not on change, and this is not a preference. A native date input fires
+                `change` on EVERY keystroke once its three segments are filled, so typing the year
+                of an existing date walks through 0002, 0020, 0202, 2026 — four writes, four
+                idempotency keys, four versions and four audit entries for one gesture, every one of
+                them a valid `z.iso.date()` the server has no reason to refuse. */}
+            <input
+              type="date"
+              aria-label={i18n.t("board.column.startDate")}
+              value={startDate}
+              onChange={(event) => {
+                setStartDate(event.currentTarget.value);
+                edit("startDate");
+              }}
+              onBlur={() => {
+                if (!edited.startDate) return;
+                settle("startDate");
+                if (startDate === (task.startDate ?? "")) return;
+                board.update.mutate({ taskId: task.id, startDate: startDate || null });
+              }}
+              className="h-8 w-full rounded-md border bg-background px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            />
+          </Field>
+          <Field label={i18n.t("board.column.dueDate")}>
+            <input
+              type="date"
+              aria-label={i18n.t("board.column.dueDate")}
+              value={dueDate}
+              onChange={(event) => {
+                setDueDate(event.currentTarget.value);
+                edit("dueDate");
+              }}
+              onBlur={() => {
+                if (!edited.dueDate) return;
+                settle("dueDate");
+                if (dueDate === (task.dueDate ?? "")) return;
+                board.update.mutate({ taskId: task.id, dueDate: dueDate || null });
+              }}
+              className="h-8 w-full rounded-md border bg-background px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            />
+          </Field>
+        </div>
+
+        <Field label={i18n.t("board.column.labels")}>
+          <ul className="flex flex-wrap gap-1">
+            {[...new Set(task.labels)].map((label) => (
+              <li
+                key={label}
+                className="inline-flex items-center gap-1 rounded-md border bg-muted px-1.5 py-0.5 text-xs"
+              >
+                {label}
+                <button
+                  type="button"
+                  aria-label={i18n.t("board.removeLabel", { label })}
+                  onClick={() =>
+                    board.update.mutate({
+                      taskId: task.id,
+                      labels: task.labels.filter((existing) => existing !== label),
+                    })
+                  }
+                  className="rounded text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <X aria-hidden="true" className="size-3" />
+                </button>
+              </li>
+            ))}
+          </ul>
+          <form
+            className="mt-2 flex gap-2"
+            onSubmit={(event) => {
+              event.preventDefault();
+              const value = newLabel.trim();
+              // A label already on the task is not added twice. The contract refuses one now
+              // (anchrd/intel#318); refusing it here as well keeps the answer to a repeated word a
+              // no-op rather than an error message about something nobody meant to do.
+              if (value === "" || task.labels.includes(value)) return;
+              board.update.mutate({ taskId: task.id, labels: [...task.labels, value] });
+              setNewLabel("");
+            }}
+          >
+            <input
+              value={newLabel}
+              onChange={(event) => setNewLabel(event.currentTarget.value)}
+              placeholder={i18n.t("board.addLabel")}
+              aria-label={i18n.t("board.addLabel")}
+              className="h-8 min-w-0 flex-1 rounded-md border bg-background px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            />
+            <SmallButton type="submit" label={i18n.t("common.create")} />
+          </form>
+        </Field>
+
+        <Field label={i18n.t("board.description")}>
+          <textarea
+            value={description}
+            aria-label={i18n.t("board.description")}
+            rows={5}
+            onChange={(event) => {
+              setDescription(event.currentTarget.value);
+              edit("description");
+            }}
+            onBlur={() => {
+              if (!edited.description) return;
+              settle("description");
+              if (description !== task.description) {
+                board.update.mutate({ taskId: task.id, description });
+              }
+            }}
+            className="w-full rounded-md border bg-background px-2 py-1.5 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          />
+        </Field>
+
+        <Field label={i18n.t("board.subtasks")}>
+          <ul className="flex flex-col gap-1">
+            {children.map((child) => (
+              <li key={child.id}>
+                <button
+                  type="button"
+                  onClick={() => select(child.id)}
+                  className="flex w-full items-center gap-2 rounded-md px-1 py-1 text-left text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <span
+                    aria-hidden="true"
+                    className={`size-2 shrink-0 rounded-full ${toneOf(child.status, board.statuses).dot}`}
+                  />
+                  <span className="min-w-0 truncate">{child.title}</span>
+                  <span className="ml-auto shrink-0 text-xs text-muted-foreground">
+                    {labelOf(child.status, board.statuses)}
+                  </span>
+                </button>
+              </li>
+            ))}
+          </ul>
+          <form
+            className="mt-2 flex gap-2"
+            onSubmit={(event) => {
+              event.preventDefault();
+              const value = newSubtask.trim();
+              if (value === "") return;
+              // A new subtask starts in its parent's column: it is part of the same piece of work,
+              // and a board where every added subtask lands in the backlog reads as a backlog that
+              // grows whenever somebody breaks a task down.
+              // ⚠️ Cleared on SUCCESS only. `BoardMaxTaskDepth` makes a fifth level a refusal, and
+              // a field emptied before the answer arrives turns that refusal into a subtask that
+              // appeared to be created and then was not there — with the typed title gone too.
+              board.add.mutate(
+                {
+                  title: value,
+                  parentId: task.id,
+                  status: task.status,
+                  assignee: null,
+                  labels: [],
+                  startDate: null,
+                  dueDate: null,
+                  dependsOn: [],
+                  description: "",
+                  references: [],
+                  afterTaskId: null,
+                  beforeTaskId: null,
+                },
+                { onSuccess: () => setNewSubtask("") },
+              );
+            }}
+          >
+            <input
+              value={newSubtask}
+              onChange={(event) => setNewSubtask(event.currentTarget.value)}
+              placeholder={i18n.t("board.addSubtask")}
+              aria-label={i18n.t("board.addSubtask")}
+              className="h-8 min-w-0 flex-1 rounded-md border bg-background px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            />
+            <SmallButton type="submit" label={i18n.t("common.create")} />
+          </form>
+        </Field>
+
+        <Field label={i18n.t("board.dependencies")}>
+          <ul className="flex flex-col gap-1">
+            {/* ⚠️ Once per task waited for, which is what makes `key={id}` unique BY CONSTRUCTION
+                rather than by decoration (anchrd/intel#318). Two rows under one key is a React
+                warning nobody reads plus two identical lines whose two remove buttons each take
+                both away — and waiting twice for a task is waiting for it once. The write path
+                refuses a repeat now and a stored one is folded on read, so nothing arriving through
+                Intel carries one; a view still may not be what mangles odd data. */}
+            {[...new Set(task.dependsOn)].map((id) => {
+              const other = board.byId.get(id);
+              return (
+                <li key={id} className="flex items-center gap-2 text-sm">
+                  <button
+                    type="button"
+                    onClick={() => select(id)}
+                    disabled={other === undefined}
+                    className="min-w-0 flex-1 truncate rounded text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring disabled:text-muted-foreground"
+                  >
+                    {other?.title ?? i18n.t("board.unknownTask")}
+                  </button>
+                  {other && !board.settled(other) ? (
+                    <span className="shrink-0 rounded border border-destructive px-1 text-xs text-destructive">
+                      {i18n.t("board.open")}
+                    </span>
+                  ) : null}
+                  <button
+                    type="button"
+                    aria-label={i18n.t("board.removeDependency")}
+                    onClick={() =>
+                      board.update.mutate({
+                        taskId: task.id,
+                        dependsOn: task.dependsOn.filter((existing) => existing !== id),
+                      })
+                    }
+                    className="shrink-0 rounded text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+                  >
+                    <X aria-hidden="true" className="size-3.5" />
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+          {/* ⚠️ Only tasks of THIS board are offered, because only they can be one: a dependency on
+              a task in another board is refused on the write path, and across boards the link is a
+              reference to the board node instead (#285). A picker that offered them would be a
+              picker whose choices are rejected. */}
+          <select
+            value=""
+            aria-label={i18n.t("board.addDependency")}
+            onChange={(event) => {
+              const id = event.currentTarget.value;
+              if (id === "") return;
+              board.update.mutate({ taskId: task.id, dependsOn: [...task.dependsOn, id] });
+            }}
+            className="mt-2 h-8 w-full rounded-md border bg-background px-2 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            <option value="">{i18n.t("board.addDependency")}</option>
+            {board.tasks
+              .filter((other) => other.id !== task.id && !task.dependsOn.includes(other.id))
+              .map((other) => (
+                <option key={other.id} value={other.id}>
+                  {other.title}
+                </option>
+              ))}
+          </select>
+        </Field>
+
+        <Field label={i18n.t("board.references")}>
+          <ul className="flex flex-col gap-1">
+            {[...new Set(task.references)].map((id) => (
+              <li key={id} className="flex items-center gap-2 text-sm">
+                <ReferenceLink
+                  nodeId={id}
+                  open={() => void navigate({ to: "/nodes", search: { select: id } })}
+                />
+                <button
+                  type="button"
+                  aria-label={i18n.t("board.removeReference")}
+                  onClick={() =>
+                    board.update.mutate({
+                      taskId: task.id,
+                      references: task.references.filter((existing) => existing !== id),
+                    })
+                  }
+                  className="shrink-0 rounded text-muted-foreground outline-none hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring"
+                >
+                  <X aria-hidden="true" className="size-3.5" />
+                </button>
+              </li>
+            ))}
+          </ul>
+          {addingReference ? (
+            <div className="mt-2">
+              <EntryPicker
+                kind={null}
+                value=""
+                label={i18n.t("board.addReference")}
+                onSelect={(entryId) => {
+                  setAddingReference(false);
+                  if (task.references.includes(entryId)) return;
+                  board.update.mutate({
+                    taskId: task.id,
+                    references: [...task.references, entryId],
+                  });
+                }}
+              />
+            </div>
+          ) : (
+            <button
+              type="button"
+              onClick={() => setAddingReference(true)}
+              className="mt-2 inline-flex h-8 items-center gap-1.5 rounded-md border px-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              <Plus aria-hidden="true" className="size-4" />
+              {i18n.t("board.addReference")}
+            </button>
+          )}
+        </Field>
+
+        <button
+          type="button"
+          onClick={() => setConfirmDelete(true)}
+          className="inline-flex h-8 items-center justify-center gap-2 rounded-md border border-destructive px-3 text-sm text-destructive outline-none hover:bg-destructive/10 focus-visible:ring-2 focus-visible:ring-ring"
+        >
+          <Trash2 aria-hidden="true" className="size-4" />
+          {i18n.t("board.deleteTask")}
+        </button>
+      </div>
+
+      <Dialog open={confirmDelete} onOpenChange={setConfirmDelete}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>{i18n.t("board.deleteTask")}</DialogTitle>
+            {/* ⚠️ The COUNT, always, and not only when there are descendants. Deleting cascades
+                (#285), and "delete this task?" in front of a delete that takes four is a question
+                that was answered about something else. */}
+            <DialogDescription>
+              {i18n.t("board.deleteConfirm", {
+                task: task.title,
+                count: subtreeSize(task.id, board.childrenOf),
+              })}
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <button
+              type="button"
+              onClick={() => setConfirmDelete(false)}
+              className="h-9 rounded-md border px-3 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              {i18n.t("common.close")}
+            </button>
+            <button
+              type="button"
+              onClick={() => {
+                board.remove.mutate({ taskId: task.id }, { onSuccess: () => close() });
+                setConfirmDelete(false);
+              }}
+              className="h-9 rounded-md bg-destructive px-3 text-sm text-destructive-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring"
+            >
+              {i18n.t("board.deleteTask")}
+            </button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+      {/* ⚠️ The server's own count is NOT reported here, and cannot be: a successful delete closes
+          this panel in the same commit, so a line under it would never be read for the task it is
+          about — and would then greet whoever opened the next card, announcing a number about a
+          task nobody touched. It belongs to the screen, which outlives the delete (`board.tsx`). */}
+      {task.status === ArchivedBoardStatusId ? (
+        <p className="px-4 pb-4 text-xs text-muted-foreground">{i18n.t("board.archivedHint")}</p>
+      ) : null}
+    </aside>
+  );
+}
+
+/**
+ * One labelled block of the panel.
+ *
+ * ⚠️ A `<fieldset>`, deliberately NOT a `<label>`. Half of these hold a list and a form rather than
+ * one control — subtasks, dependencies, references — and a `<label>` around several controls names
+ * none of them. The legend announces the section on entry, and the control inside carries its own
+ * accessible name.
+ */
+function Field({ label, children }: { label: string; children: React.ReactNode }) {
+  return (
+    <fieldset className="flex min-w-0 flex-col gap-1.5">
+      <legend className="mb-1.5 text-xs font-medium tracking-wide text-muted-foreground uppercase">
+        {label}
+      </legend>
+      {children}
+    </fieldset>
+  );
+}
+
+function SmallButton({ type, label }: { type: "submit" | "button"; label: string }) {
+  return (
+    <button
+      type={type}
+      className="h-8 shrink-0 rounded-md border px-2 text-sm outline-none hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      {label}
+    </button>
+  );
+}
+
+function AgentOption({ nodeId }: { nodeId: string }) {
+  const entry = useEntryTitle(nodeId);
+  return <option value={`agent:${nodeId}`}>{entry.title}</option>;
+}
+
+// A reference is a node id; what a reader needs is its name, and clicking it has to lead there.
+// ⚠️ A target the reader may not see is absent from the graph `useEntryTitle` reads, and it says
+// so rather than naming it — the same answer a deleted one gets, on purpose (#41).
+function ReferenceLink({ nodeId, open }: { nodeId: string; open(): void }) {
+  const entry = useEntryTitle(nodeId);
+  return (
+    <button
+      type="button"
+      onClick={open}
+      disabled={!entry.known}
+      className="inline-flex min-w-0 flex-1 items-center gap-1.5 rounded text-left outline-none hover:underline focus-visible:ring-2 focus-visible:ring-ring disabled:text-muted-foreground disabled:hover:no-underline"
+    >
+      <ExternalLink aria-hidden="true" className="size-3.5 shrink-0" />
+      <span className="min-w-0 truncate">{entry.title}</span>
+    </button>
+  );
+}