@anthusai/papyrus 5.43.0-next.37 → 5.43.0-next.39

package/components/conversation-context.tsx

@@ -0,0 +1,52 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+import type { ConversationAnchor, ConversationMessage } from "../lib/conversation";
+
+/**
+ * Where conversations are read and written. The newsroom provides the network one; a demo or a test provides the in-memory one. A
+ * component that finds no store shows no conversation at all.
+ */
+export type ConversationStore = {
+  /** Who the optimistic Message says wrote it, until the saved one replaces it. */
+  authorLabel: string;
+  load: (anchor: ConversationAnchor) => Promise<ConversationMessage[]>;
+  append: (input: { anchor: ConversationAnchor; body: string; parentMessageId: string | null }) => Promise<ConversationMessage>;
+  /** Message counts by Reference lineage, for the feed cards. */
+  counts: () => Promise<Map<string, number>>;
+};
+
+const ConversationStoreContext = createContext<ConversationStore | null>(null);
+
+export function ConversationStoreProvider({ store, children }: { store: ConversationStore; children: ReactNode }) {
+  return <ConversationStoreContext.Provider value={store}>{children}</ConversationStoreContext.Provider>;
+}
+
+export function useConversationStore(): ConversationStore | null {
+  return useContext(ConversationStoreContext);
+}
+
+/** A store that keeps everything in memory: the demo newsroom, and the tests. */
+export function createMemoryConversationStore(authorLabel: string, seed: Record<string, ConversationMessage[]> = {}): ConversationStore {
+  const byAnchor = new Map<string, ConversationMessage[]>(Object.entries(seed));
+  const keyOf = (anchor: ConversationAnchor) => `${anchor.kind}#${anchor.lineageId ?? ""}`;
+  return {
+    authorLabel,
+    load: async (anchor) => [...(byAnchor.get(keyOf(anchor)) ?? [])],
+    append: async ({ anchor, body, parentMessageId }) => {
+      const list = byAnchor.get(keyOf(anchor)) ?? [];
+      const sequenceNumber = Math.max(0, ...list.map((message) => message.sequenceNumber)) + 1;
+      const message: ConversationMessage = {
+        id: `message-memory-${sequenceNumber}-${list.length}`,
+        parentMessageId,
+        authorLabel,
+        content: body.trim(),
+        createdAt: new Date().toISOString(),
+        sequenceNumber,
+      };
+      byAnchor.set(keyOf(anchor), [...list, message]);
+      return message;
+    },
+    counts: async () => new Map([...byAnchor].filter(([key]) => key.startsWith("reference#")).map(([key, list]) => [key.slice("reference#".length), list.length])),
+  };
+}

package/components/conversation-provider.tsx

@@ -0,0 +1,20 @@
+"use client";
+
+import { useMemo, type ReactNode } from "react";
+import { ConversationStoreProvider, createMemoryConversationStore, type ConversationStore } from "./conversation-context";
+import { appendConversationMessage, loadConversationMessages, loadReferenceConversationCounts } from "./news-desk-taxonomy-client";
+
+function networkConversationStore(authorLabel: string): ConversationStore {
+  return {
+    authorLabel,
+    load: loadConversationMessages,
+    append: async ({ anchor, body, parentMessageId }) => (await appendConversationMessage({ anchor, body, parentMessageId })).message,
+    counts: loadReferenceConversationCounts,
+  };
+}
+
+/** Gives the newsroom its conversations: saved to the backend, or kept in memory in the demo. */
+export function ConversationProvider({ authorLabel, demo, children }: { authorLabel: string; demo: boolean; children: ReactNode }) {
+  const store = useMemo(() => (demo ? createMemoryConversationStore(authorLabel) : networkConversationStore(authorLabel)), [authorLabel, demo]);
+  return <ConversationStoreProvider store={store}>{children}</ConversationStoreProvider>;
+}

package/components/conversation-thread.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+import { Loader2Icon, MessageSquarePlusIcon, ReplyIcon, TriangleAlertIcon, CornerDownRightIcon } from "lucide-react";
+import { useMemo, useState } from "react";
+import { buildConversationTree, conversationAge, conversationAuthorName, type ConversationMessage } from "../lib/conversation";
+import { cn } from "../lib/utils";
+import { AutoGrowTextarea } from "./ui/auto-grow-textarea";
+import type { ConversationState } from "./use-conversation";
+
+/** Flat pill buttons, like the feed's: a tone, never an outline. */
+const PILL = "inline-flex min-h-9 items-center justify-center gap-1.5 rounded-full px-3.5 text-sm font-medium outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50";
+const PILL_PRIMARY = cn(PILL, "bg-[var(--primary)] text-[var(--primary-foreground)]");
+const PILL_QUIET = cn(PILL, "text-muted-foreground hover:text-foreground");
+
+/**
+ * A box for writing a Message. The text clears the moment you post, so the Message shows at once; if the save fails the text comes
+ * back (unless you have typed something new) with the reason, and nothing you wrote is lost.
+ */
+function Composer({ autoFocus = false, buttonLabel, disabledReason, icon, label, onCancel, onSubmit, placeholder }: {
+  autoFocus?: boolean;
+  buttonLabel: string;
+  disabledReason?: string | null;
+  icon: "post" | "reply";
+  label: string;
+  onCancel?: () => void;
+  onSubmit: (body: string) => Promise<void>;
+  placeholder: string;
+}) {
+  const [draft, setDraft] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const Icon = icon === "post" ? MessageSquarePlusIcon : ReplyIcon;
+  const canPost = !disabledReason && draft.trim().length > 0;
+
+  async function submit() {
+    const text = draft.trim();
+    if (!text || disabledReason) return;
+    setDraft("");
+    setError(null);
+    try {
+      await onSubmit(text);
+      onCancel?.();
+    } catch (failure) {
+      setDraft((current) => current || text);
+      setError(failure instanceof Error ? failure.message : "Your message could not be saved.");
+    }
+  }
+
+  return (
+    <div className="space-y-2" data-conversation-composer={icon}>
+      <AutoGrowTextarea
+        aria-label={label}
+        autoFocus={autoFocus}
+        className="block min-h-16 w-full rounded-[var(--feed-radius-lg,10px)] bg-[var(--feed-control)] p-3 text-base font-normal outline-none placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring"
+        disabled={Boolean(disabledReason)}
+        onChange={(event) => setDraft(event.target.value)}
+        onKeyDown={(event) => { if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) { event.preventDefault(); void submit(); } }}
+        placeholder={placeholder}
+        value={draft}
+      />
+      {error ? (
+        <p className="flex items-start gap-1.5 text-sm text-destructive" data-conversation-error role="alert">
+          <TriangleAlertIcon aria-hidden="true" className="mt-0.5 size-4 shrink-0" />
+          <span>Not posted: {error} Your text is kept here.</span>
+        </p>
+      ) : null}
+      {disabledReason ? <p className="text-sm text-muted-foreground">{disabledReason}</p> : null}
+      <div className="flex flex-wrap items-center gap-2">
+        <button className={PILL_PRIMARY} data-conversation-post={icon} disabled={!canPost} onClick={() => void submit()} type="button">
+          <Icon aria-hidden="true" className="size-4" />
+          {buttonLabel}
+        </button>
+        {onCancel ? <button className={PILL_QUIET} onClick={onCancel} type="button">Cancel</button> : null}
+      </div>
+    </div>
+  );
+}
+
+function MessageBody({ answers, message, now, onReply, replying, tone }: {
+  answers?: string | null;
+  message: ConversationMessage;
+  now: number;
+  onReply: () => void;
+  replying: boolean;
+  tone: "root" | "reply";
+}) {
+  return (
+    <div className={cn("space-y-1.5 rounded-[var(--feed-radius-lg,10px)] p-3", tone === "root" ? "bg-[var(--feed-control)]" : "bg-[var(--feed-footer)]")} data-conversation-message={message.id} data-conversation-pending={message.pending || undefined}>
+      <p className="flex flex-wrap items-center gap-x-2 text-sm">
+        <span className="font-semibold" data-conversation-author>{conversationAuthorName(message.authorLabel)}</span>
+        <span className="text-xs text-muted-foreground" data-conversation-age>
+          {message.pending ? (
+            <span className="inline-flex items-center gap-1"><Loader2Icon aria-hidden="true" className="size-3 animate-spin" />Sending</span>
+          ) : conversationAge(message.createdAt, now)}
+        </span>
+      </p>
+      {answers ? (
+        <p className="flex items-center gap-1 text-xs text-muted-foreground" data-conversation-answers>
+          <CornerDownRightIcon aria-hidden="true" className="size-3" />
+          In reply to {answers}
+        </p>
+      ) : null}
+      <p className="whitespace-pre-wrap break-words text-base" data-conversation-content>{message.content}</p>
+      {!message.pending ? (
+        <button aria-expanded={replying} className={cn(PILL_QUIET, "-ml-3")} data-conversation-reply={message.id} onClick={onReply} type="button">
+          <ReplyIcon aria-hidden="true" className="size-4" />
+          Reply
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * The Messages of one conversation, replies nested one level under their top-level Message, and a box to add another. It knows
+ * nothing about where the Messages come from: the caller loads them and saves a post.
+ */
+export function ConversationThread({ disabledReason = null, error = null, heading = "Messages", messages, now, onPost, onRetry, state = "ready" }: {
+  disabledReason?: string | null;
+  error?: string | null;
+  heading?: string;
+  messages: ReadonlyArray<ConversationMessage>;
+  now: number;
+  onPost: (body: string, parentMessageId: string | null) => Promise<void>;
+  onRetry?: () => void;
+  state?: ConversationState;
+}) {
+  const tree = useMemo(() => buildConversationTree(messages), [messages]);
+  const [replyingTo, setReplyingTo] = useState<string | null>(null);
+  const authorOf = (id: string) => conversationAuthorName(messages.find((message) => message.id === id)?.authorLabel);
+  const toggleReply = (id: string) => setReplyingTo((current) => (current === id ? null : id));
+
+  return (
+    <section aria-label={heading} className="space-y-3" data-conversation-thread>
+      <h3 className="text-sm font-medium">{heading}</h3>
+      {state === "loading" ? <p className="flex items-center gap-1.5 text-sm text-muted-foreground" data-conversation-loading><Loader2Icon aria-hidden="true" className="size-4 animate-spin" />Loading messages</p> : null}
+      {state === "error" ? (
+        <p className="flex flex-wrap items-center gap-2 text-sm text-destructive" role="alert">
+          <TriangleAlertIcon aria-hidden="true" className="size-4" />
+          Messages could not be loaded. {error}
+          {onRetry ? <button className={PILL_QUIET} onClick={onRetry} type="button">Try again</button> : null}
+        </p>
+      ) : null}
+      {state === "ready" && !tree.length ? <p className="text-sm text-muted-foreground" data-conversation-empty>No messages yet. Write down what this made you think.</p> : null}
+      <ul className="space-y-3">
+        {tree.map((root) => (
+          <li className="space-y-2" key={root.message.id}>
+            <MessageBody message={root.message} now={now} onReply={() => toggleReply(root.message.id)} replying={replyingTo === root.message.id} tone="root" />
+            {root.replies.length || replyingTo === root.message.id ? (
+              <ul className="ml-4 space-y-2" data-conversation-replies>
+                {root.replies.map((reply) => (
+                  <li key={reply.message.id}>
+                    <MessageBody answers={reply.answers} message={reply.message} now={now} onReply={() => toggleReply(reply.message.id)} replying={replyingTo === reply.message.id} tone="reply" />
+                    {replyingTo === reply.message.id ? (
+                      <div className="mt-2">
+                        <Composer autoFocus buttonLabel="Reply" disabledReason={disabledReason} icon="reply" label={`Reply to ${authorOf(reply.message.id)}`} onCancel={() => setReplyingTo(null)} onSubmit={(body) => onPost(body, reply.message.id)} placeholder={`Reply to ${authorOf(reply.message.id)}…`} />
+                      </div>
+                    ) : null}
+                  </li>
+                ))}
+                {replyingTo === root.message.id ? (
+                  <li>
+                    <Composer autoFocus buttonLabel="Reply" disabledReason={disabledReason} icon="reply" label={`Reply to ${authorOf(root.message.id)}`} onCancel={() => setReplyingTo(null)} onSubmit={(body) => onPost(body, root.message.id)} placeholder={`Reply to ${authorOf(root.message.id)}…`} />
+                  </li>
+                ) : null}
+              </ul>
+            ) : null}
+          </li>
+        ))}
+      </ul>
+      <Composer buttonLabel="Post" disabledReason={disabledReason} icon="post" label="Add a message" onSubmit={(body) => onPost(body, null)} placeholder="Add a message…" />
+    </section>
+  );
+}

package/components/decision-control.tsx

@@ -0,0 +1,306 @@
+"use client";
+
+import { useEffect, useId, useState } from "react";
+import { CheckIcon, Loader2Icon, XIcon } from "lucide-react";
+import { UNRECORDED_CONFIDENCE } from "../lib/reference-feed-ranking";
+import { cn } from "../lib/utils";
+import type { CardPrediction, ReviewChoice } from "./reference-review-card";
+
+/**
+ * One classification, in two stages: a model predicts it, a person decides it.
+ *
+ *   PREDICTED ACCEPT
+ *   [=========== 96% ==========|                ]   the prediction's own confidence, in its own bar
+ *   [ ✓ Accept  PREDICTED ]  [ ✕ Reject ]            one pair of segments; the predicted one is pre-filled, in its own tone
+ *   REASON · OPTIONAL
+ *   [ Why? In your own words… ]                      written, always in view, full width
+ *   ✓ Recorded · confirms the prediction             one status line for the whole block
+ *
+ * The prediction and the answer share one row of segments rather than a row each: they are not two
+ * voters, they are one decision before and after a person touched it. Once decided, a small marker
+ * stays on the segment the model picked — on the losing one if it was overturned — so the comparison
+ * survives the answer without a second row. The bar belongs to the model, so it never moves when the
+ * person answers; only its tone changes.
+ *
+ * The verdict never tints the person's own choice: a decided segment is always `--primary`, and
+ * `--feed-verdict-*` colours the marker and the bar. An overturned Reject painted red reads as "your
+ * answer is wrong" rather than "the model's was".
+ *
+ * No engine or product name appears in the copy: the component knows about predictions, not about
+ * what made them (AGENTS.md: a deployment publishes about any subject with any classifier behind it).
+ *
+ * Every tone, corner and opacity is a feed token from newsroom-organizer.css; the values after the
+ * comma are the last resort for a surface that declares none.
+ */
+
+export type RatingFeedback = { phase: "idle" | "saving" | "saved" | "error"; message?: string };
+
+/** P(accept) from a prediction: its confidence is in the side it chose; an unrecorded confidence is a mild lean. */
+export function predictionAcceptProbability(prediction: Extract<CardPrediction, { state: "ready" }>): number {
+  const confidence = prediction.confidence ?? UNRECORDED_CONFIDENCE;
+  return prediction.choice === "accept" ? confidence : 1 - confidence;
+}
+
+/** How far, in percent of the whole bar, the fill reaches from the centre: |P(accept) - 0.5| * 2, over the two halves. */
+export function confidenceFillPercent(probability: number): number {
+  return Math.min(100, Math.abs(probability - 0.5) * 100 * 2);
+}
+
+const WORD: Record<ReviewChoice, string> = { accept: "Accept", reject: "Reject" };
+const LABEL = "font-[family-name:var(--font-sans)] text-[10px] font-extrabold tracking-[0.07em] uppercase";
+/** A fill shorter than this cannot hold its own percentage, so the number sits beside it. */
+const NARROW_FILL = 14;
+
+export function DecisionControl({
+  answer,
+  decided = null,
+  disabled = false,
+  disabledReason = null,
+  feedback = { phase: "idle" },
+  needsReason = false,
+  note = null,
+  onChoose,
+  onReasonChange,
+  onReasonCommit,
+  prediction,
+  reason = "",
+  reasonRequiredFor = null,
+  showPrediction = true,
+  showReason = true,
+  size = "compact",
+  statusOverlay = false,
+  surface = "footer",
+}: {
+  /** The side shown as chosen. It may be an answer that is still saving. */
+  answer: ReviewChoice | null;
+  /** The saved answer, which the Confirmed / Overturned verdict compares against. */
+  decided?: ReviewChoice | null;
+  disabled?: boolean;
+  disabledReason?: string | null;
+  feedback?: RatingFeedback;
+  /** The answer is staged and waiting for a written reason before it can be recorded. */
+  needsReason?: boolean;
+  /** A short line shown in the status row beside the saved tick. It never adds a row. */
+  note?: string | null;
+  onChoose: (choice: ReviewChoice) => void;
+  onReasonChange?: (text: string) => void;
+  /** Save the reason on its own (on blur, or from the status row). */
+  onReasonCommit?: () => void;
+  prediction: CardPrediction;
+  /** The written reason, owned by the caller. */
+  reason?: string;
+  /** The side that cannot be recorded without a written reason. */
+  reasonRequiredFor?: ReviewChoice | null;
+  /** False for an item with nothing to predict: the bar and the caption are left out. */
+  showPrediction?: boolean;
+  /** False where the surrounding card owns the reason field. */
+  showReason?: boolean;
+  size?: "compact" | "large";
+  /** Lay the status line over the bottom padding of the nearest positioned ancestor, so it adds no height. */
+  statusOverlay?: boolean;
+  /** The tone the control sits on, so the bar's centre notch matches it. */
+  surface?: "footer" | "card";
+}) {
+  const fieldId = useId();
+  const ready = prediction.state === "ready" ? prediction : null;
+  const verdict = ready && decided ? (ready.choice === decided ? "match" : "miss") : null;
+  const saving = feedback.phase === "saving";
+  const [reasonDirty, setReasonDirty] = useState(false);
+  useEffect(() => { if (feedback.phase === "saved") setReasonDirty(false); }, [feedback.phase]);
+
+  const probability = ready ? predictionAcceptProbability(ready) : 0.5;
+  const half = confidenceFillPercent(probability) / 2; // percent of the full bar, one side of the centre
+  const leansAccept = probability >= 0.5;
+  const confidenceText = ready ? (ready.confidence !== null ? `${Math.round(ready.confidence * 100)}%` : "unrecorded") : null;
+  const narrow = half < NARROW_FILL;
+  const cell = size === "large" ? "min-h-14 text-base" : "min-h-12 text-sm";
+  const field = size === "large" ? "min-h-16" : "min-h-9";
+
+  const caption = ready
+    ? `Predicted ${WORD[ready.choice]}`
+    : prediction.state === "loading" ? "Reading the prediction…"
+      : prediction.state === "error" ? "Prediction unavailable" : "No prediction";
+
+  /* What the chosen segment says about itself while the answer is in flight or held back. A segment
+     never claims to be unrecorded while it is being recorded. */
+  const stagedWord = saving ? (decided ? "Updating…" : "Sending…") : needsReason ? "Needs a reason" : null;
+
+  return (
+    <div className="@container/decision grid gap-y-2" data-decision-control data-rating-grid>
+      {showPrediction ? (
+        <div className="grid gap-y-0.5" data-prediction>
+          <span className={cn(LABEL, "text-muted-foreground")} data-prediction-caption>{caption}</span>
+          <div
+            aria-label={ready ? `Prediction: ${WORD[ready.choice]}, ${confidenceText} confident` : caption}
+            className="relative h-4 w-full overflow-hidden rounded-full bg-[var(--feed-control)]"
+            data-confidence-bar
+            data-confidence-direction={ready ? (leansAccept ? "accept" : "reject") : "none"}
+            data-prediction-state={ready ? undefined : prediction.state}
+            role="img"
+          >
+            {ready ? (
+              <span
+                className={cn(
+                  "absolute inset-y-0 flex items-center rounded-full",
+                  leansAccept ? "justify-end" : "justify-start",
+                  verdict === "match" ? "bg-[var(--feed-verdict-match-fill,#059669)]"
+                    : verdict === "miss" ? "bg-[var(--feed-verdict-miss-fill,#dc2626)]"
+                      : "bg-[var(--foreground-muted)]",
+                )}
+                data-confidence-fill
+                data-fill-percent={Math.round(half * 2)}
+                style={{ left: leansAccept ? `${50 - half}%` : "50%", width: `${half}%` }}
+              >
+                {/* The confidence is printed in the bar and nowhere else, so no button has to carry a number. */}
+                {narrow ? null : <small className={cn(LABEL, "px-1.5 text-[var(--feed-card)] whitespace-nowrap")} data-confidence-value>{confidenceText}</small>}
+              </span>
+            ) : null}
+            {ready && narrow ? (
+              <small
+                className={cn(LABEL, "absolute top-0.5 text-muted-foreground whitespace-nowrap")}
+                data-confidence-value
+                style={leansAccept ? { left: `${50 - half}%`, transform: "translateX(-100%)" } : { left: `${50 + half}%` }}
+              >
+                {confidenceText}
+              </small>
+            ) : null}
+            <span aria-hidden="true" className={cn("absolute inset-y-0 left-1/2 w-1 -translate-x-1/2", surface === "footer" ? "bg-[var(--feed-footer)]" : "bg-[var(--feed-card)]")} />
+          </div>
+        </div>
+      ) : null}
+
+      <div aria-label="Classification" className="grid grid-cols-2 gap-x-1.5" data-review-row="you" role="group">
+        {(["accept", "reject"] as const).map((choice) => {
+          const on = answer === choice;
+          const predicted = ready?.choice === choice;
+          const proposed = predicted && !answer;
+          const Icon = choice === "accept" ? CheckIcon : XIcon;
+          const sub = proposed ? "Predicted"
+            : on ? (stagedWord ?? (verdict === "miss" ? "Overturned" : verdict === "match" ? "Confirmed" : decided === choice ? "Recorded" : null))
+              : null;
+          return (
+            <button
+              aria-disabled={disabled ? true : undefined}
+              aria-pressed={on}
+              className={cn(
+                "relative inline-flex min-w-0 flex-col items-center justify-center gap-px rounded-[var(--feed-radius-md,16px)] px-2 font-medium outline-none transition-colors focus-visible:ring-[3px] focus-visible:ring-ring @max-[17rem]/decision:px-1",
+                cell,
+                // Three degrees of finish, in tone alone: the feed register has no borders to spend
+                // (newsroom-organizer.css strips them), so a chosen answer is the solid fill, the
+                // predicted side is the control tone, and an untouched side is quieter still.
+                on ? "bg-[var(--primary)] font-semibold text-[var(--primary-foreground)]"
+                  : proposed ? "bg-[var(--feed-control)] text-foreground hover:bg-[var(--feed-control)]/70"
+                    : "bg-[var(--feed-control)]/45 text-muted-foreground hover:bg-[var(--feed-control)]/70",
+                disabled && !on && "opacity-[var(--feed-quiet,0.6)]",
+              )}
+              data-predicted={predicted || undefined}
+              data-review-choice={choice}
+              data-state={on ? (saving || needsReason ? "staged" : "decided") : proposed ? "predicted" : "idle"}
+              key={choice}
+              onClick={() => { if (!disabled) onChoose(choice); }}
+              type="button"
+            >
+              {/* The model's opinion survives the answer, on the segment it picked. */}
+              {predicted && answer ? (
+                <span
+                  className={cn(
+                    "absolute top-1.5 right-2 opacity-55",
+                    verdict === "match" && "text-[var(--feed-verdict-match-fill,#059669)] opacity-100",
+                    verdict === "miss" && "text-[var(--feed-verdict-miss-fill,#dc2626)] opacity-100",
+                  )}
+                  data-prediction-mark
+                  data-verdict={verdict ?? undefined}
+                  title="this is what was predicted"
+                >
+                  <svg aria-hidden="true" className="size-3" fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24">
+                    <circle cx="12" cy="12" r="8" />
+                    <circle cx="12" cy="12" fill="currentColor" r="2.6" stroke="none" />
+                  </svg>
+                </span>
+              ) : null}
+              <span className="flex items-center gap-1.5">
+                <Icon aria-hidden="true" className={cn("size-4", !on && "opacity-[var(--feed-quiet,0.6)]")} />
+                {WORD[choice]}
+              </span>
+              {sub ? <span className={cn(LABEL, "opacity-75")} data-choice-state>{sub}</span> : null}
+              {verdict && predicted ? <span className="sr-only">{verdict === "match" ? ", this is what was predicted" : ", the prediction was the other way"}</span> : null}
+            </button>
+          );
+        })}
+      </div>
+
+      {showReason ? (
+        <div className="grid gap-y-1.5" data-review-reason>
+          <label className={cn(LABEL, "text-muted-foreground")} htmlFor={fieldId}>
+            Reason{reasonRequiredFor ? ` · required to ${WORD[reasonRequiredFor].toLowerCase()}` : " · optional"}
+          </label>
+          {/* Written reasons only. A row of canned answers collects a label the model mostly has already;
+              what trains the next prediction is a sentence. */}
+          <textarea
+            className={cn(
+              "w-full rounded-[var(--feed-radius-md,16px)] border-0 bg-[var(--feed-control)] px-3 py-2 text-sm leading-5 text-foreground outline-none transition-[min-height] placeholder:text-muted-foreground focus-visible:ring-[3px] focus-visible:ring-ring",
+              field,
+            )}
+            disabled={disabled}
+            id={fieldId}
+            onBlur={() => { if (!disabled) onReasonCommit?.(); }}
+            onChange={(event) => { setReasonDirty(true); onReasonChange?.(event.target.value); }}
+            placeholder="Why? In your own words — this is what the next prediction learns from."
+            value={reason}
+          />
+        </div>
+      ) : null}
+
+      <div
+        className={cn(
+          "flex flex-wrap items-center gap-x-2 text-xs text-muted-foreground",
+          // The overlay strip is 16px tall: a question with a button, or an error, needs a row of its own.
+          statusOverlay && !needsReason && feedback.phase !== "error" ? "absolute inset-x-4 bottom-0 h-4 overflow-hidden leading-4" : "min-h-5",
+        )}
+        data-feed-saved
+        role="status"
+      >
+        {note ? <span data-feed-reason>{note}</span> : null}
+        {needsReason ? (
+          <>
+            <span className="font-semibold text-foreground">A reason is needed to record {WORD[answer ?? "reject"]}</span>
+            <button
+              className="rounded-[var(--feed-radius-md,16px)] bg-[var(--primary)] px-2.5 py-0.5 font-semibold text-[var(--primary-foreground)] outline-none focus-visible:ring-[3px] focus-visible:ring-ring disabled:opacity-[var(--feed-quiet,0.6)]"
+              disabled={!reason.trim()}
+              data-review-record
+              onClick={() => { if (answer) onChoose(answer); }}
+              type="button"
+            >
+              Record
+            </button>
+          </>
+        ) : null}
+        {saving ? <span className="inline-flex items-center gap-1"><Loader2Icon aria-hidden="true" className="size-3.5 animate-spin" />Recording…</span> : null}
+        {feedback.phase === "saved" && !needsReason ? (
+          <span className="inline-flex items-center gap-1 text-foreground" data-review-saved>
+            <CheckIcon aria-hidden="true" className="size-3.5" />
+            Recorded
+            {verdict ? <span className="text-muted-foreground">· {verdict === "match" ? "confirms" : "overturns"} the prediction</span> : null}
+            {showReason ? (
+              reasonDirty ? <span className="text-muted-foreground">· reason not saved yet</span>
+                : reason.trim() ? <span className="text-muted-foreground">· reason saved</span>
+                  : <span className="text-muted-foreground">· no reason given</span>
+            ) : null}
+          </span>
+        ) : null}
+        {feedback.phase === "saved" && reasonDirty && showReason ? (
+          <button
+            className="rounded-[var(--feed-radius-md,16px)] bg-[var(--primary)] px-2.5 py-0.5 font-semibold text-[var(--primary-foreground)] outline-none focus-visible:ring-[3px] focus-visible:ring-ring"
+            data-review-save-reason
+            onClick={() => onReasonCommit?.()}
+            type="button"
+          >
+            Save reason
+          </button>
+        ) : null}
+      </div>
+      {disabledReason ? <p className="text-xs text-muted-foreground" data-review-disabled-reason>{disabledReason}</p> : null}
+      {feedback.phase === "error" ? <p className="text-xs text-destructive" role="alert">{feedback.message}</p> : null}
+    </div>
+  );
+}

package/components/needs-me-bodies.tsx

@@ -13,7 +13,7 @@ import type { NeedsMeEntry } from "../lib/needs-me-items";
 import { answerWords, formatWhen, nextText, steeringText, subjectHref, subjectLabel } from "../lib/review-requests";
 import { DecidedLine } from "./notification-cards";
 import { SourceMark } from "./reference-feed";
-import { RatingGrid } from "./review-rating-grid";
+import { DecisionControl } from "./decision-control";
 import type { RatingController } from "./use-reference-ratings";
 import { FlagFooter, decidedChoiceOf, recordedAnswer } from "./needs-me-shared";
 
@@ -111,7 +111,7 @@ export function DecisionPanel({ item, ratings, extras, onExtras, disabledReason,
           {item.decisionState === "acknowledged"
             ? <p className="flex items-center gap-1.5 text-sm font-medium" data-flag-acknowledged><CircleCheckIcon aria-hidden="true" className="size-4" />Acknowledged</p>
             : <DecidedLine choice={decided ?? "accept"} notThisKind={recorded.notThisKind} />}
-          {flag ? null : <RatingGrid answer={decided} disabled feedback={{ phase: "idle" }} onChoose={() => undefined} prediction={{ state: "none" }} showPrediction={false} size="large" surface="footer" />}
+          {flag ? null : <DecisionControl answer={decided} disabled feedback={{ phase: "idle" }} onChoose={() => undefined} prediction={{ state: "none" }} showPrediction={false} showReason={false} size="large" surface="footer" />}
           {lockedNote ? <p className="text-xs text-muted-foreground" data-review-disabled-reason>{lockedNote}</p> : null}
         </>
       ) : (
@@ -134,7 +134,7 @@ export function DecisionPanel({ item, ratings, extras, onExtras, disabledReason,
           {flag ? (
             <FlagFooter busy={busy} disabledReason={disabledReason} done={false} error={rating.feedback.phase === "error" ? rating.feedback.message ?? null : null} onAcknowledge={() => ratings.choose(item.id, "accept")} />
           ) : (
-            <RatingGrid
+            <DecisionControl
               answer={rating.pending}
               disabled={Boolean(disabledReason)}
               disabledReason={disabledReason}
@@ -142,6 +142,7 @@ export function DecisionPanel({ item, ratings, extras, onExtras, disabledReason,
               onChoose={(choice) => { if (!disabledReason) ratings.choose(item.id, choice); }}
               prediction={{ state: "none" }}
               showPrediction={false}
+              showReason={false}
               size="large"
               surface="footer"
             />

package/components/needs-me-feed.tsx

@@ -32,7 +32,7 @@ import { NotificationSkeleton, RecentDecisions } from "./notification-cards";
 import { FEED_GRID, FEED_SURFACE_PROPS, FeedImage, PILL, REASON_LABELS, SELECTED_RING, SourceMark } from "./reference-feed";
 import { predictionFromDecision, ReviewQueueBar, useQueueGestures, type CardPrediction, type ReviewChoice } from "./reference-review-card";
 import type { CorrectCaptureAction } from "./reference-capture-client";
-import { RatingGrid } from "./review-rating-grid";
+import { DecisionControl } from "./decision-control";
 import { useMediaQuery } from "./use-media-query";
 import { useRatingStore, type RatingController } from "./use-reference-ratings";
 import { useResolvedPapyrusTheme } from "./use-resolved-papyrus-theme";
@@ -169,30 +169,24 @@ export function NeedsMeCard({ item, now, onOpen, predictionLoading, ratings, sel
         {flag ? (
           <FlagFooter busy={rating.feedback.phase === "saving"} disabledReason={disabledReason} done={item.decisionState === "acknowledged"} error={rating.feedback.phase === "error" ? rating.feedback.message ?? null : null} onAcknowledge={() => ratings.choose(item.id, "accept")} />
         ) : (
-          <RatingGrid
+          <DecisionControl
             answer={chosen}
             decided={decided}
             disabled={Boolean(disabledReason) || locked}
             disabledReason={disabledReason}
             feedback={feedback}
+            needsReason={refLike && rating.askReason}
             note={reasonLabel ? `Reason: ${reasonLabel}` : locked ? whyLine ?? "Decided here." : null}
             onChoose={(choice) => { if (!disabledReason && !locked) ratings.choose(item.id, choice); }}
+            onReasonChange={(text) => ratings.setNote(item.id, text)}
+            onReasonCommit={() => { if (!disabledReason && !locked) ratings.commitNote(item.id); }}
             prediction={cardPrediction(item, predictionLoading)}
+            reason={rating.note ?? ""}
+            reasonRequiredFor={refLike ? "reject" : null}
             showPrediction={refLike}
+            showReason={refLike}
           />
         )}
-        {refLike && rating.askReason ? (
-          // Covers the footer rather than adding to it, so asking for a reason never pushes the cards below it down.
-          <div className="absolute inset-0 z-10 flex flex-col justify-center space-y-2 bg-[var(--feed-footer)] p-3" data-review-reasons>
-            <p className="text-xs font-medium">Reason for rejecting. Choose one to save your Reject.</p>
-            <div className="flex flex-wrap gap-1.5">
-              {REFERENCE_REJECTION_REASON_CODES.map((code) => (
-                <button className={cn(PILL, "min-h-8 bg-[var(--feed-control)] px-3 text-xs")} data-review-reason={code} key={code} onClick={() => ratings.setReason(item.id, code)} type="button">{REASON_LABELS[code]}</button>
-              ))}
-              <button className={cn(PILL, "min-h-8 px-3 text-xs text-muted-foreground")} onClick={() => ratings.cancelReason(item.id)} type="button">Cancel</button>
-            </div>
-          </div>
-        ) : null}
       </div>
     </article>
   );

package/components/needs-me-reference-detail.tsx

@@ -11,6 +11,7 @@ import type { NeedsMeEntry } from "../lib/needs-me-items";
 import { DefaultOutcome, Heading, type DetailProps } from "./needs-me-bodies";
 import { decidedChoiceOf } from "./needs-me-shared";
 import { predictionFromDecision, ReviewCard, type CardPrediction } from "./reference-review-card";
+import { ReferenceConversation } from "./reference-conversation";
 import { ReferenceCapturePanel } from "./reference-capture-panel";
 import { useReferenceCapture } from "./reference-capture-client";
 import { ReferenceSourcePreview } from "./reference-source-preview";
@@ -57,6 +58,7 @@ export function ReferenceBody(props: DetailProps & { payload: Extract<NeedsMeEnt
         titleHref={url}
       >
         {payload.decision ? <div data-reference-relevance-decision={lineageId}><ReferenceSuggestionProvenance decision={payload.decision} /></div> : null}
+        <ReferenceConversation disabledReason={disabledReason ? "Editor access is required to write messages." : null} lineageId={lineageId} referenceId={reference.id} title={referenceDisplayTitle(reference)} />
       </ReviewCard>
       <DefaultOutcome item={item} />
       {incomplete ? <p className="text-sm text-muted-foreground" data-needs-me-capture-note>The captured text looks cut off or missing. Read it below. If it is incomplete, choose Paste or correct the text and say whether the capture was complete, or rate the Reference as it is.</p> : null}