@anthusai/papyrus 5.43.0-next.16 → 5.43.0-next.18

package/components/reference-feed.tsx

@@ -21,6 +21,9 @@ import type { RelevanceDecisionView } from "../lib/relevance-decisions";
 import { cn } from "../lib/utils";
 import { predictionFromDecision, type ReviewChoice } from "./reference-review-card";
 import { RatingGrid } from "./review-rating-grid";
+import { CaptureBadge } from "./reference-capture-panel";
+import { useRatingStore, type RatingController } from "./use-reference-ratings";
+import type { CaptureStatus } from "../lib/reference-capture";
 
 /**
  * Flat surfaces, no borders: the page tone, a card tone one step away from it, a footer tone, and a control tone for chips and
@@ -62,20 +65,33 @@ export type ReferenceFeedProps = {
   predictionLoading?: boolean;
   previews: ReadonlyMap<string, ReferencePreview>;
   selectedLineageId?: string;
+  /** Capture status per Reference lineage, for the small badge on each card. Optional. */
+  captures?: ReadonlyMap<string, CaptureStatus>;
+  /** The sections and lead, when the caller keeps the order stable (a snapshot). Without them the feed groups its own partition. */
+  groups?: Array<{ key: FeedGroupKey; items: FeedItem[] }>;
+  leadId?: string;
+  /** Scrolls the grid to a card, deliberately (Previous / Next). A new nonce is a new request; selecting alone never scrolls. */
+  scrollTarget?: { id: string; nonce: number } | null;
+  /** A rating store shared with the detail pane, so a vote or reason in either shows in both. Optional. */
+  ratings?: RatingController;
   /** True when the cards are a saved copy that is being refreshed. */
   stale?: boolean;
   tab: ReferenceFeedTabKey;
   visitRated: ReadonlySet<string>;
 };
 
-export const FEED_GRID = "grid gap-5 sm:grid-cols-2 xl:grid-cols-3 2xl:grid-cols-4";
+/** Columns follow the width the feed has (a container query, not the screen), so they stay put while a detail pane holds its place beside it. */
+export const FEED_GRID = "grid grid-cols-[repeat(auto-fill,minmax(17rem,1fr))] gap-5";
+const GRID = FEED_GRID;
+/** The lead spans two columns only where there are at least two to span (two 17rem columns and the gap). */
+const LEAD_SPAN = "@[36rem]:col-span-2";
 
 /** Pulsing placeholder cards: the page shell is on screen at once, with no "checking" screen in front of it. */
 export function ReferenceFeedSkeleton({ count = 6 }: { count?: number }) {
   return (
-    <div aria-busy="true" aria-label="Loading references" className={FEED_GRID} data-reference-feed-skeleton role="status" {...FEED_SURFACE_PROPS}>
+    <div aria-busy="true" aria-label="Loading references" className={cn("@container", GRID)} data-reference-feed-skeleton role="status" {...FEED_SURFACE_PROPS}>
       {Array.from({ length: count }, (_, index) => (
-        <div className={cn("overflow-hidden rounded-[20px] bg-[var(--feed-card)]", index === 0 && "sm:col-span-2")} key={index}>
+        <div className={cn("overflow-hidden rounded-[20px] bg-[var(--feed-card)]", index === 0 && LEAD_SPAN)} key={index}>
           <div className={cn("animate-pulse bg-[var(--feed-control)]", index === 0 ? "aspect-[2/1]" : "aspect-[16/10]")} />
           <div className="space-y-3 p-5">
             <div className="h-3 w-1/3 animate-pulse rounded-full bg-[var(--feed-control)]" />
@@ -145,14 +161,17 @@ export function FeedImage({ host, lead, name, src }: { host: string | null; lead
     const element = ref.current;
     if (element?.complete && element.naturalWidth > 0) { setState("loaded"); measure(element); }
   }, [src]);
-  const card = isCardStyleImage(src, ratio);
+  // The frame is decided before the picture loads (from its address), so loading never moves the cards around. A picture found to be
+  // a 2:1 text card afterwards is contained inside the same frame instead of changing it.
+  const hostCard = isCardStyleImage(src, null);
+  const card = hostCard || isCardStyleImage(src, ratio);
   return (
     <div
-      className={cn("relative w-full overflow-hidden bg-[var(--feed-control)]", !card && (lead ? "aspect-[16/10] sm:aspect-[2/1] xl:aspect-[21/9]" : "aspect-[16/10]"))}
+      className={cn("relative w-full overflow-hidden bg-[var(--feed-control)]", !hostCard && (lead ? "aspect-[16/10] @[36rem]:aspect-[2/1] @[60rem]:aspect-[21/9]" : "aspect-[16/10]"))}
       data-feed-image
       data-feed-image-fit={card ? "contain" : "cover"}
       data-feed-image-state={state}
-      style={card ? { aspectRatio: String(ratio ?? 2) } : undefined}
+      style={hostCard ? { aspectRatio: "2" } : undefined}
     >
       {state === "loading" ? <div aria-hidden="true" className="absolute inset-0 animate-pulse bg-[var(--feed-footer)] blur-sm" data-feed-image-placeholder /> : null}
       {src && state !== "failed" ? (
@@ -175,9 +194,8 @@ export function FeedImage({ host, lead, name, src }: { host: string | null; lead
   );
 }
 
-type RateState = { phase: "idle" | "saving" | "saved" | "error" | "reason"; message?: string };
-
 export function FeedCard({
+  capture,
   decision,
   disabledReason,
   item,
@@ -187,9 +205,12 @@ export function FeedCard({
   onRate,
   predictionLoading,
   preview,
+  ratings,
   selected,
   visitRated,
 }: {
+  /** Optional: the capture badge. */
+  capture?: CaptureStatus | undefined;
   decision: RelevanceDecisionView | undefined;
   disabledReason: string | null;
   item: FeedItem;
@@ -199,6 +220,8 @@ export function FeedCard({
   onRate: ReferenceFeedProps["onRate"];
   predictionLoading: boolean;
   preview: ReferencePreview | undefined;
+  /** Optional: a shared rating store. Without it the card keeps its own. */
+  ratings?: RatingController | undefined;
   selected: boolean;
   visitRated: boolean;
 }) {
@@ -206,8 +229,15 @@ export function FeedCard({
   const titleId = useId();
   const status = normalizeReferenceCurationStatus(reference.curationStatus);
   const answer: ReviewChoice | null = status === "accepted" ? "accept" : status === "rejected" ? "reject" : null;
-  const [rate, setRate] = useState<RateState>({ phase: "idle" });
-  const inFlight = useRef(false);
+  // Rating state lives in a store: the shared one when given (so the detail pane and this card stay in step), else a private one.
+  const local = useRatingStore({
+    save: async (_id, choice, detail) => { await onRate(reference, choice, detail.reasonCode); },
+    saved: () => answer,
+    seed: () => ({ note: "", reasonCode: null }),
+  });
+  const store = ratings ?? local;
+  const rating = store.get(item.lineageId);
+  const chosen = rating.pending ?? answer;
   const host = referenceSourceHost(reference);
   const site = preview?.siteName ?? host ?? "Unknown source";
   const title = referenceDisplayTitle(reference);
@@ -215,42 +245,26 @@ export function FeedCard({
   const showDek = dekAddsInformation(title, dek, preview?.imageUrl ?? null);
   const time = referenceDisplayTime(reference);
   const age = formatFeedAge(time, now);
-
-  async function save(choice: ReviewChoice, reasonCode: ReferenceRejectionReasonCode | null) {
-    if (disabledReason || inFlight.current) return;
-    inFlight.current = true;
-    setRate({ phase: "saving" });
-    try {
-      await onRate(reference, choice, reasonCode);
-      setRate({ phase: "saved" });
-    } catch (failure) {
-      setRate({ phase: "error", message: failure instanceof Error ? failure.message : "Your answer could not be saved. Tap it again to retry." });
-    } finally {
-      inFlight.current = false;
-    }
-  }
-
-  function choose(choice: ReviewChoice) {
-    if (disabledReason) return;
-    if (answer === choice) return; // the chosen answer never unselects itself; the other choice is the undo
-    if (choice === "reject") { setRate({ phase: "reason" }); return; }
-    void save("accept", null);
-  }
+  const feedback = rating.feedback.phase === "idle" && visitRated && answer ? { phase: "saved" as const } : rating.feedback;
+  const reasonLabel = answer === "reject" && rating.reasonCode ? REASON_LABELS[rating.reasonCode] : null;
 
   return (
     <article
       aria-labelledby={titleId}
+      aria-current={selected ? "true" : undefined}
       className={cn(
-        "flex flex-col overflow-hidden rounded-[20px] text-card-foreground",
-        selected ? "bg-[var(--feed-control)]" : "bg-[var(--feed-card)]",
-        lead && "sm:col-span-2",
+        "relative flex flex-col overflow-hidden rounded-[20px] text-card-foreground transition-[background-color,box-shadow] duration-200",
+        selected ? "bg-[var(--feed-control)] shadow-xl" : "bg-[var(--feed-card)]",
+        lead && LEAD_SPAN,
       )}
       data-feed-card={item.lineageId}
       data-feed-lead={lead || undefined}
       data-feed-rated={answer ?? undefined}
+      data-feed-selected={selected || undefined}
       data-feed-visit-rated={visitRated || undefined}
       data-newsroom-card-id={item.lineageId}
     >
+      {selected ? <span aria-hidden="true" className="absolute inset-y-0 left-0 z-10 w-1.5 bg-[var(--primary)]" data-feed-selected-bar /> : null}
       <button
         aria-label={`Open: ${title}`}
         className="flex flex-1 flex-col text-left outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring"
@@ -259,42 +273,48 @@ export function FeedCard({
         type="button"
       >
         <FeedImage host={host} lead={lead} name={site} src={preview?.imageUrl ?? null} />
-        <span className={cn("flex flex-1 flex-col gap-2.5", lead ? "p-5 sm:p-7" : "p-5")}>
+        <span className={cn("flex flex-1 flex-col gap-2.5", lead ? "p-5 @[36rem]:p-7" : "p-5")}>
           <span className="flex items-center gap-2 text-xs font-medium text-muted-foreground" data-feed-source>
             <SourceMark host={host} />
             <span className="truncate">{site}</span>
           </span>
-          <span className={cn("font-bold leading-[1.15] tracking-tight text-foreground", lead ? "line-clamp-3 text-2xl sm:text-3xl xl:text-4xl" : "line-clamp-3 text-xl")} data-feed-title id={titleId}>
+          <span className={cn("font-bold leading-[1.15] tracking-tight text-foreground", lead ? "line-clamp-3 text-2xl @[36rem]:text-3xl @[60rem]:text-4xl" : "line-clamp-3 text-xl")} data-feed-title id={titleId}>
             {title}
           </span>
           {showDek ? <span className={cn("text-muted-foreground", lead ? "line-clamp-3 text-base" : "line-clamp-2 text-sm")} data-feed-dek>{dek}</span> : null}
-          <span className="mt-auto pt-1 text-xs text-muted-foreground">
-            {age ? <time dateTime={new Date(time ?? now).toISOString()} title={new Date(time ?? now).toLocaleString()}>{age}</time> : null}
-            {age && host ? <span aria-hidden="true"> · </span> : null}
-            {host}
+          <span className="mt-auto flex flex-wrap items-center gap-x-2 gap-y-1 pt-1 text-xs text-muted-foreground">
+            <span>
+              {age ? <time dateTime={new Date(time ?? now).toISOString()} title={new Date(time ?? now).toLocaleString()}>{age}</time> : null}
+              {age && host ? <span aria-hidden="true"> · </span> : null}
+              {host}
+            </span>
+            {capture ? <CaptureBadge status={capture} /> : null}
           </span>
         </span>
       </button>
 
-      <div className="space-y-2.5 bg-[var(--feed-footer)] p-3" data-feed-actions>
+      <div className="relative bg-[var(--feed-footer)] p-3" data-feed-actions>
         <RatingGrid
-          answer={answer}
+          answer={chosen}
+          decided={answer}
           disabled={Boolean(disabledReason)}
           disabledReason={disabledReason}
-          feedback={rate.phase === "saving" ? { phase: "saving" } : rate.phase === "error" ? { phase: "error", message: rate.message } : rate.phase === "saved" || (visitRated && rate.phase === "idle" && answer) ? { phase: "saved" } : { phase: "idle" }}
-          onChoose={choose}
+          feedback={feedback}
+          note={reasonLabel ? `Reason: ${reasonLabel}` : null}
+          onChoose={(choice) => { if (!disabledReason) store.choose(item.lineageId, choice); }}
           prediction={decision ? predictionFromDecision(decision) : predictionLoading ? { state: "loading" } : { state: "none" }}
         />
-        {rate.phase === "reason" ? (
-          <div className="space-y-2" data-review-reasons>
+        {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={() => void save("reject", code)} type="button">
+                <button className={cn(PILL, "min-h-8 bg-[var(--feed-control)] px-3 text-xs")} data-review-reason={code} key={code} onClick={() => store.setReason(item.lineageId, code)} type="button">
                   {REASON_LABELS[code]}
                 </button>
               ))}
-              <button className={cn(PILL, "min-h-8 px-3 text-xs text-muted-foreground")} onClick={() => setRate({ phase: "idle" })} type="button">Cancel</button>
+              <button className={cn(PILL, "min-h-8 px-3 text-xs text-muted-foreground")} onClick={() => store.cancelReason(item.lineageId)} type="button">Cancel</button>
             </div>
           </div>
         ) : null}
@@ -380,6 +400,11 @@ export function ReferenceFeed({
   predictionLoading = false,
   previews,
   selectedLineageId = "",
+  captures,
+  groups: stableGroups,
+  leadId: stableLeadId,
+  ratings,
+  scrollTarget = null,
   stale = false,
   tab,
   visitRated,
@@ -388,6 +413,7 @@ export function ReferenceFeed({
 
   const renderCard = (item: FeedItem, lead: boolean) => (
     <FeedCard
+      capture={captures?.get(item.lineageId)}
       decision={item.decision}
       disabledReason={disabledReason}
       item={item}
@@ -398,6 +424,7 @@ export function ReferenceFeed({
       onRate={async (reference, choice, reasonCode) => { onVisitRated(item.lineageId); await onRate(reference, choice, reasonCode); }}
       predictionLoading={predictionLoading}
       preview={previews.get(item.lineageId)}
+      ratings={ratings}
       selected={selectedLineageId === item.lineageId}
       visitRated={visitRated.has(item.lineageId)}
     />
@@ -407,12 +434,18 @@ export function ReferenceFeed({
     <div className="rounded-[20px] bg-[var(--feed-card)] p-10 text-center text-sm text-muted-foreground" data-feed-empty>{label}</div>
   );
 
-  const groups = groupFeedItems(partition.feed);
+  // Previous / Next in the detail pane scrolls the grid to the same card, smoothly. Selecting a card by clicking it never scrolls.
+  useEffect(() => {
+    if (!scrollTarget || typeof document === "undefined") return;
+    document.querySelector(`[data-feed-card="${CSS.escape(scrollTarget.id)}"]`)?.scrollIntoView({ behavior: "smooth", block: "nearest" });
+  }, [scrollTarget]);
+
+  const groups = stableGroups ?? groupFeedItems(partition.feed);
   const headings = groups.length > 1;
-  const leadId = groups[0]?.key !== "least" ? groups[0]?.items[0]?.lineageId : undefined;
+  const leadId = stableGroups ? stableLeadId : groups[0]?.key !== "least" ? groups[0]?.items[0]?.lineageId : undefined;
 
   return (
-    <div className="space-y-5" data-reference-feed data-feed-tab={tab} {...FEED_SURFACE_PROPS}>
+    <div className="@container space-y-5" data-reference-feed data-feed-tab={tab} {...FEED_SURFACE_PROPS}>
       <div className="flex items-center justify-between gap-2">
         <div aria-label="Feed sections" className="inline-flex rounded-full bg-[var(--feed-card)] p-1" role="tablist">
           {(Object.keys(TAB_LABELS) as ReferenceFeedTabKey[]).map((key) => (

package/components/reference-review-card.tsx

@@ -13,6 +13,7 @@ import { useEffect, useRef, useState, type ReactNode, type PointerEvent as React
 import { Button } from "./ui/button";
 import { cn } from "../lib/utils";
 import { RatingGrid } from "./review-rating-grid";
+import { useRatingStore, type RatingController } from "./use-reference-ratings";
 import { REFERENCE_REJECTION_REASON_CODES, type ReferenceRejectionReasonCode } from "../lib/reference-policy";
 
 export type ReviewChoice = "accept" | "reject";
@@ -141,8 +142,11 @@ export function ReviewCard({
   summary,
   title,
   titleHref,
+  ratings,
 }: {
   children?: ReactNode;
+  /** A shared rating store, so the grid card and this card stay in step. Optional: the card works alone without it. */
+  ratings?: RatingController;
   /** The saved human answer, or null while the item is undecided. */
   decided: ReviewChoice | null;
   /** When set, the controls explain in words why they cannot change anything. */
@@ -157,70 +161,21 @@ export function ReviewCard({
   title: string;
   titleHref?: string | null;
 }) {
-  const [draft, setDraft] = useState<ReviewChoice | null>(null);
-  const [note, setNote] = useState(initialNote);
-  const [reason, setReason] = useState<ReferenceRejectionReasonCode | null>(initialReason);
-  const [saving, setSaving] = useState(false);
-  const [saved, setSaved] = useState(false);
-  const [error, setError] = useState<string | null>(null);
-  const inFlight = useRef(false);
-  const noteTouched = useRef(false);
-  const reasonTouched = useRef(false);
-  const savedNote = useRef(initialNote);
-
-  // Saved values from outside (another editor, a reload) refresh whatever the human has not touched.
-  useEffect(() => {
-    savedNote.current = initialNote;
-    if (!noteTouched.current) setNote(initialNote);
-  }, [initialNote]);
-  useEffect(() => {
-    if (!reasonTouched.current) setReason(initialReason);
-  }, [initialReason]);
-
-  const chosen = draft ?? decided;
-
-  async function save(choice: ReviewChoice, nextReason: ReferenceRejectionReasonCode | null, nextNote: string) {
-    if (disabledReason || inFlight.current) return;
-    if (choice === "reject" && !nextReason) return;
-    inFlight.current = true;
-    setSaving(true);
-    setSaved(false);
-    setError(null);
-    try {
-      await onDecide(choice, { note: nextNote.trim(), reasonCode: choice === "reject" ? nextReason : null });
-      savedNote.current = nextNote.trim();
-      noteTouched.current = false;
-      reasonTouched.current = false;
-      setDraft(null);
-      setSaved(true);
-    } catch (failure) {
-      setDraft(null);
-      setError(failure instanceof Error ? failure.message : "Your answer could not be saved. Tap it again to retry.");
-    } finally {
-      inFlight.current = false;
-      setSaving(false);
-    }
-  }
-
-  function choose(choice: ReviewChoice) {
-    if (disabledReason) return;
-    if (chosen === choice && draft === null) return; // the selected answer never unselects itself
-    setError(null);
-    setDraft(choice);
-    void save(choice, reason, note);
-  }
-
-  function chooseReason(code: ReferenceRejectionReasonCode) {
-    if (disabledReason) return;
-    setReason(code);
-    reasonTouched.current = true;
-    if (chosen === "reject") void save("reject", code, note);
-  }
-
-  function commitNote() {
-    if (!decided || disabledReason || note.trim() === savedNote.current.trim()) return;
-    void save(decided, reason, note);
-  }
+  // The rating state lives in a store. Given one (`ratings`), the grid card and this card share it, so a vote or a reason typed in
+  // either shows in both at once; without one the card keeps a private store, exactly as before.
+  const local = useRatingStore({
+    save: (_id, choice, detail) => onDecide(choice, detail),
+    saved: () => decided,
+    seed: () => ({ note: initialNote, reasonCode: initialReason }),
+  });
+  const store = ratings ?? local;
+  const item = store.get(itemId);
+  const note = item.note ?? initialNote;
+  const reason = item.reasonCode !== undefined ? item.reasonCode : initialReason;
+  const chosen = item.pending ?? decided;
+  const choose = (choice: ReviewChoice) => { if (!disabledReason) store.choose(itemId, choice); };
+  const chooseReason = (code: ReferenceRejectionReasonCode) => { if (!disabledReason) store.setReason(itemId, code); };
+  const commitNote = () => { if (!disabledReason) store.commitNote(itemId); };
 
   // Desktop shortcuts: A accepts, R rejects. Never while typing.
   useEffect(() => {
@@ -253,7 +208,7 @@ export function ReviewCard({
         decided={decided}
         disabled={Boolean(disabledReason)}
         disabledReason={disabledReason}
-        feedback={saving ? { phase: "saving" } : error ? { phase: "error", message: error } : saved ? { phase: "saved" } : { phase: "idle" }}
+        feedback={item.feedback}
         onChoose={choose}
         prediction={prediction}
         size="large"
@@ -266,7 +221,7 @@ export function ReviewCard({
           aria-label="Why? (optional)"
           className="mt-1 block min-h-24 w-full rounded-md border bg-background p-3 text-base font-normal"
           onBlur={commitNote}
-          onChange={(event) => { setNote(event.target.value); noteTouched.current = true; setSaved(false); }}
+          onChange={(event) => store.setNote(itemId, event.target.value)}
           placeholder="Say what made this an easy yes or a clear no. Your note teaches the Cyclotron."
           value={note}
         />

package/components/review-rating-grid.tsx

@@ -42,6 +42,7 @@ export function RatingGrid({
   disabled = false,
   disabledReason = null,
   feedback = { phase: "idle" },
+  note = null,
   onChoose,
   prediction,
   showPrediction = true,
@@ -55,6 +56,8 @@ export function RatingGrid({
   disabled?: boolean;
   disabledReason?: string | null;
   feedback?: RatingFeedback;
+  /** A short line shown in the status row beside the Saved tick (for example the reason). It never adds a row. */
+  note?: string | null;
   onChoose: (choice: ReviewChoice) => void;
   prediction: CardPrediction;
   /** False for a card with nothing to predict (an AI draft): the Cyclotron row and the "You" label are left out and only the two buttons remain. */
@@ -128,11 +131,10 @@ export function RatingGrid({
             ) : 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>
-          {prediction.state === "ready" ? null : (
-            <small className="text-center text-xs text-muted-foreground" data-cyclotron-state={prediction.state}>
-              {prediction.state === "loading" ? "Loading…" : prediction.state === "error" ? "Prediction unavailable" : "No prediction"}
-            </small>
-          )}
+          {/* The line is always there, so a prediction arriving later never changes the card's height. */}
+          <small className="min-h-4 text-center text-xs text-muted-foreground" data-cyclotron-state={prediction.state === "ready" ? undefined : prediction.state}>
+            {prediction.state === "ready" ? "\u00a0" : prediction.state === "loading" ? "Loading…" : prediction.state === "error" ? "Prediction unavailable" : "No prediction"}
+          </small>
         </div>
       </div> : null}
 
@@ -163,7 +165,8 @@ export function RatingGrid({
         })}
       </div>
 
-      <div className={cn("min-h-5 text-xs text-muted-foreground", showPrediction ? "col-span-3" : "col-span-2")} data-feed-saved role="status">
+      <div className={cn("flex min-h-5 flex-wrap items-center gap-x-3 text-xs text-muted-foreground", showPrediction ? "col-span-3" : "col-span-2")} data-feed-saved role="status">
+        {note ? <span data-feed-reason>{note}</span> : null}
         {feedback.phase === "saving" ? <span className="inline-flex items-center gap-1"><Loader2Icon aria-hidden="true" className="size-3.5 animate-spin" />Saving…</span> : null}
         {feedback.phase === "saved" ? <span className="inline-flex items-center gap-1" data-review-saved><CheckIcon aria-hidden="true" className="size-3.5" />Saved</span> : null}
       </div>

package/components/topic-steering-workspace.tsx

@@ -94,6 +94,7 @@ import { useOptionalNewsDeskClient } from "./news-desk-client-provider";
 import { ReferenceSourcePreview } from "./reference-source-preview";
 import type { ReaderAuthSnapshot } from "./reader-auth-state";
 import { NewsDeskAccessGate } from "./newsroom-access-gate";
+import { correctReferenceCapture } from "../lib/content-actions-client";
 import { loadMessagesWithHeadStart, loadReferencesWithHeadStart, loadRelationsWithHeadStart } from "./references-prefetch";
 import { loadFeedSnapshot, saveFeedSnapshot, type FeedSnapshot } from "../lib/reference-feed-cache";
 import { referencePreviewsByLineage } from "../lib/reference-preview";
@@ -3213,6 +3214,7 @@ function NewsDeskDashboard({
             referenceAttachments={referenceAttachments}
             references={references}
             loading={!dashboard.isDemo && !hasHydratedReferences}
+            onCorrectCapture={dashboard.isDemo ? undefined : (input) => correctReferenceCapture(input)}
             savedCopy={savedFeedCopy}
           />
           </NewsroomCurationBootstrap>

package/components/use-reference-ratings.ts

@@ -0,0 +1,132 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { ReferenceRejectionReasonCode } from "../lib/reference-policy";
+import type { ReviewChoice } from "./reference-review-card";
+import type { RatingFeedback } from "./review-rating-grid";
+
+/** How long after the last keystroke a typed reason is saved on its own. */
+export const NOTE_AUTOSAVE_MS = 1200;
+
+export type ItemRating = {
+  /** The reason as typed, else as saved. In the store itself it stays undefined until touched, so an untouched field follows the record. */
+  note?: string;
+  reasonCode?: ReferenceRejectionReasonCode | null;
+  /** A vote that is waiting for a reason (Reject needs one) or is still saving. */
+  pending: ReviewChoice | null;
+  /** True while a Reject is waiting for its reason. */
+  askReason: boolean;
+  feedback: RatingFeedback;
+};
+
+const EMPTY: ItemRating = { pending: null, askReason: false, feedback: { phase: "idle" } };
+
+export type RatingSave = (id: string, choice: ReviewChoice, detail: { note: string; reasonCode: ReferenceRejectionReasonCode | null }) => Promise<void> | void;
+
+export type RatingController = {
+  get: (id: string) => ItemRating;
+  choose: (id: string, choice: ReviewChoice) => void;
+  setReason: (id: string, code: ReferenceRejectionReasonCode) => void;
+  setNote: (id: string, text: string) => void;
+  /** Save a typed reason now (on blur). */
+  commitNote: (id: string) => void;
+  cancelReason: (id: string) => void;
+};
+
+/**
+ * One store for the rating state of every item, shared by the grid card and the detail pane so a vote or a reason typed in either
+ * shows in both at once. `saved(id)` is the saved human answer; `seed(id)` the saved note and reason code.
+ *   vote, then reason  -> the reason is saved onto the existing decision (on blur, or after a short pause)
+ *   reason, then vote  -> the vote carries the reason
+ * A Reject needs a reason code (the backend refuses one without), so it waits as `pending` until one is chosen; a typed reason is
+ * kept in the store until it is saved and is never dropped by a failed save.
+ */
+export function useRatingStore({ save, saved, seed }: {
+  save: RatingSave;
+  saved: (id: string) => ReviewChoice | null;
+  seed: (id: string) => { note: string; reasonCode: ReferenceRejectionReasonCode | null };
+}): RatingController {
+  const [items, setItems] = useState<Record<string, ItemRating>>({});
+  const itemsRef = useRef(items);
+  const latest = useRef({ save, saved, seed });
+  latest.current = { save, saved, seed };
+  const timers = useRef<Record<string, ReturnType<typeof setTimeout>>>({});
+  const inFlight = useRef<Set<string>>(new Set());
+  const dirty = useRef<Set<string>>(new Set());
+
+  const patch = useCallback((id: string, change: Partial<ItemRating>) => {
+    const next = { ...itemsRef.current, [id]: { ...(itemsRef.current[id] ?? EMPTY), ...change } };
+    itemsRef.current = next;
+    setItems(next);
+  }, []);
+
+  // What a reader of the store sees: the touched value, else what is saved. (A saved reason therefore shows on the card too.)
+  const get = useCallback((id: string): ItemRating => {
+    const item = items[id] ?? EMPTY;
+    const seeded = latest.current.seed(id);
+    return { ...item, note: item.note ?? seeded.note, reasonCode: item.reasonCode !== undefined ? item.reasonCode : seeded.reasonCode };
+  }, [items]);
+
+  const values = (id: string) => {
+    const item = itemsRef.current[id] ?? EMPTY;
+    const seeded = latest.current.seed(id);
+    return { note: item.note ?? seeded.note, reasonCode: item.reasonCode !== undefined ? item.reasonCode : seeded.reasonCode };
+  };
+
+  const commit = useCallback(async (id: string, choice: ReviewChoice) => {
+    const { note, reasonCode } = values(id);
+    if (choice === "reject" && !reasonCode) { patch(id, { pending: "reject", askReason: true }); return; }
+    if (inFlight.current.has(id)) { dirty.current.add(id); return; }
+    inFlight.current.add(id);
+    dirty.current.delete(id);
+    const started = itemsRef.current[id] ?? EMPTY;
+    patch(id, { pending: choice, askReason: false, feedback: { phase: "saving" } });
+    try {
+      await latest.current.save(id, choice, { note: note.trim(), reasonCode: choice === "reject" ? reasonCode : null });
+      // What was saved now follows the record again (another editor's update shows); anything typed meanwhile is kept.
+      const now = itemsRef.current[id] ?? EMPTY;
+      patch(id, { pending: null, feedback: { phase: "saved" }, ...(now.note === started.note ? { note: undefined } : {}), ...(now.reasonCode === started.reasonCode ? { reasonCode: undefined } : {}) });
+    } catch (failure) {
+      // The typed reason stays in the store; only the vote is undone.
+      patch(id, { pending: null, feedback: { phase: "error", message: failure instanceof Error ? failure.message : "Your answer could not be saved. Tap it again to retry." } });
+    } finally {
+      inFlight.current.delete(id);
+    }
+    if (dirty.current.has(id)) { dirty.current.delete(id); const again = itemsRef.current[id]?.pending ?? latest.current.saved(id); if (again) void commit(id, again); }
+  }, [patch]);
+
+  const effective = (id: string): ReviewChoice | null => itemsRef.current[id]?.pending ?? latest.current.saved(id);
+
+  const choose = useCallback((id: string, choice: ReviewChoice) => {
+    if (effective(id) === choice && !itemsRef.current[id]?.askReason) return; // the chosen answer never unselects itself
+    void commit(id, choice);
+  }, [commit]);
+
+  const setReason = useCallback((id: string, code: ReferenceRejectionReasonCode) => {
+    patch(id, { reasonCode: code });
+    // Vote then reason: onto the existing (or waiting) decision. Reason then vote: stored, and the vote carries it.
+    if (effective(id) === "reject") void commit(id, "reject");
+  }, [commit, patch]);
+
+  const setNote = useCallback((id: string, text: string) => {
+    patch(id, { note: text, feedback: { phase: "idle" } });
+    dirty.current.add(`note:${id}`);
+    clearTimeout(timers.current[id]);
+    timers.current[id] = setTimeout(() => {
+      const choice = effective(id);
+      if (choice && dirty.current.delete(`note:${id}`)) void commit(id, choice);
+    }, NOTE_AUTOSAVE_MS);
+  }, [commit, patch]);
+
+  const commitNote = useCallback((id: string) => {
+    clearTimeout(timers.current[id]);
+    const choice = effective(id);
+    if (choice && dirty.current.delete(`note:${id}`)) void commit(id, choice);
+  }, [commit]);
+
+  const cancelReason = useCallback((id: string) => patch(id, { pending: null, askReason: false }), [patch]);
+
+  useEffect(() => () => { for (const timer of Object.values(timers.current)) clearTimeout(timer); }, []);
+
+  return { get, choose, setReason, setNote, commitNote, cancelReason };
+}

package/lib/content-actions-client.ts

@@ -30,6 +30,18 @@ export type SaveItemDraftResult = { ok: true; item: SavedItemSummary };
 export type PublishItemResult = { ok: true; changed: boolean; publishedId: string; versionNumber: number | null };
 export type UnpublishItemResult = { ok: true; changed: boolean };
 
+export type CaptureAssessment = "complete" | "incomplete" | "incorrect";
+export type CorrectReferenceCaptureInput = {
+  referenceId: string;
+  /** The full corrected or pasted text. */
+  text?: string;
+  grobid?: Record<string, unknown>;
+  /** Required with text; alone it is just a label on the capture. */
+  assessment?: CaptureAssessment;
+  note?: string;
+};
+export type CorrectReferenceCaptureResult = { ok: true; referenceId: string; status: string; edits: unknown[]; label: unknown; summaryStale: boolean };
+
 export class ContentActionFailure extends Error {
   readonly errors: ContentActionError[];
 
@@ -48,6 +60,7 @@ export type ContentActionsTransport = {
     saveItemDraft: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
     publishItem: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
     unpublishItem: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
+    correctReferenceCapture: (args: { input: string }, options: { authMode: "userPool" }) => Promise<GraphqlEnvelope>;
   };
 };
 
@@ -80,6 +93,9 @@ export function createContentActionsClient(transport: ContentActionsTransport) {
     async publishItem(id: string): Promise<PublishItemResult> {
       return parseActionResponse(await transport.mutations.publishItem({ input: JSON.stringify({ id }) }, USER_POOL));
     },
+    async correctReferenceCapture(input: CorrectReferenceCaptureInput): Promise<CorrectReferenceCaptureResult> {
+      return parseActionResponse(await transport.mutations.correctReferenceCapture({ input: JSON.stringify(input) }, USER_POOL));
+    },
     async unpublishItem(id: string): Promise<UnpublishItemResult> {
       return parseActionResponse(await transport.mutations.unpublishItem({ input: JSON.stringify({ id }) }, USER_POOL));
     },
@@ -99,3 +115,5 @@ export const deriveMarkus = (input: DeriveMarkusInput) => contentActionsClient()
 export const saveItemDraft = (input: SaveItemDraftInput) => contentActionsClient().saveItemDraft(input);
 export const publishItem = (id: string) => contentActionsClient().publishItem(id);
 export const unpublishItem = (id: string) => contentActionsClient().unpublishItem(id);
+
+export const correctReferenceCapture = (input: CorrectReferenceCaptureInput) => contentActionsClient().correctReferenceCapture(input);