@anthusai/papyrus 5.47.0 → 5.49.0

package/components/reference-capture-panel.tsx

@@ -113,9 +113,9 @@ function CorrectionForm({ capture, onDone }: { capture: CaptureView; onDone: ()
 }
 
 /** Our captured record of a Reference: what we stored of its content, said plainly, above the live source preview. */
-export function ReferenceCapturePanel({ capture }: { capture: CaptureView }) {
+export function ReferenceCapturePanel({ capture, startEditing = false }: { capture: CaptureView; startEditing?: boolean }) {
   const [expanded, setExpanded] = useState(false);
-  const [editing, setEditing] = useState(false);
+  const [editing, setEditing] = useState(startEditing && Boolean(capture.correct));
   const [savedNote, setSavedNote] = useState(false);
   const line = captureLine(capture.status);
   const Icon = ICON[line.state];

package/components/reference-feed.tsx

@@ -35,7 +35,7 @@ export const FEED_SURFACE_STYLE = {} as CSSProperties;
 /** Spread on every feed surface: the tone variables, and the hook the newsroom stylesheet uses to allow round corners here. */
 export const FEED_SURFACE_PROPS = { "data-feed-surface": "", style: FEED_SURFACE_STYLE } as const;
 
-const REASON_LABELS: Record<ReferenceRejectionReasonCode, string> = {
+export const REASON_LABELS: Record<ReferenceRejectionReasonCode, string> = {
   out_of_scope: "Out of scope",
   policy_exclusion: "Policy exclusion",
   duplicate: "Duplicate",

package/components/reference-review-card.tsx

@@ -270,7 +270,10 @@ export function ReviewQueueBar({
   onPrevious,
   position,
   total,
+  anchored = false,
 }: {
+  /** On a wide screen, pin the bar to the bottom-right corner of the viewport (the detail column's width), whatever scrolls. A sheet's own bar is not anchored. */
+  anchored?: boolean;
   caughtUp?: boolean;
   onNext: () => void;
   onPrevious: () => void;
@@ -282,7 +285,8 @@ export function ReviewQueueBar({
   return (
     <nav
       aria-label="Review queue"
-      className="sticky bottom-0 z-10 flex shrink-0 items-center gap-2 border-t border-border bg-card px-3 py-2"
+      className={cn("sticky bottom-0 z-10 flex shrink-0 items-center gap-2 bg-[var(--feed-card)] px-3 py-2", anchored && "md:fixed md:bottom-0 md:right-0 md:w-[calc(24rem+1rem)] md:pr-7 lg:w-[calc(28rem+1rem)]")}
+      data-review-queue-anchored={anchored || undefined}
       data-review-queue-bar
     >
       <Button

package/components/topic-steering-workspace.tsx

@@ -3109,7 +3109,8 @@ function NewsDeskDashboard({
             loading={!dashboard.isDemo && !hasHydratedReferences}
             newsroomSections={newsroomSections}
             notificationFixture={dashboard.notificationFixture ?? null}
-            onReview={(reference, action, options) => runReferenceCurationAction(reference, action, undefined, options?.reasonCode,
+            onCorrectCapture={dashboard.isDemo ? undefined : (input) => correctReferenceCapture(input)}
+            onReview={(reference, action, options) => runReferenceCurationAction(reference, action, options?.note, options?.reasonCode,
               options?.decisionRelationId ? { decisionRelationId: options.decisionRelationId, shareable: options.shareable === true } : undefined)}
             predictionState={referenceReviewData.state}
             referenceAttachments={referenceAttachments}

package/components/use-media-query.ts

@@ -0,0 +1,16 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/** True while the media query matches. False on the server and before the first effect, so the first paint is the wide layout. */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState(false);
+  useEffect(() => {
+    const mediaQuery = window.matchMedia(query);
+    const update = () => setMatches(mediaQuery.matches);
+    update();
+    mediaQuery.addEventListener("change", update);
+    return () => mediaQuery.removeEventListener("change", update);
+  }, [query]);
+  return matches;
+}

package/components/use-reference-preview-attachments.ts

@@ -0,0 +1,101 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import type { ReferenceAttachmentRecord, ReferenceRecord } from "../lib/category-repository";
+import { referenceLineageId } from "../lib/newsroom-references";
+import { loadReferenceAttachmentsForLineageId, loadStoragePathUrl } from "./news-desk-taxonomy-client";
+
+function normalizeReferenceDetailHttpUri(value: string | null | undefined): string | null {
+  const trimmed = value?.trim();
+  if (!trimmed) return null;
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  return null;
+}
+
+/** The attachments of one Reference (seeded, else read), with stored files turned into links. Shared by the References detail pane and the Needs me detail pane. */
+export function useReferencePreviewAttachments(
+  reference: ReferenceRecord | null,
+  referenceAttachments: ReferenceAttachmentRecord[],
+) {
+  const lineageId = reference ? referenceLineageId(reference) : "";
+  const seededAttachments = useMemo(
+    () => referenceAttachments.filter((attachment) => attachment.referenceLineageId === lineageId),
+    [lineageId, referenceAttachments],
+  );
+  const [attachments, setAttachments] = useState<ReferenceAttachmentRecord[]>(seededAttachments);
+  const [attachmentLinksById, setAttachmentLinksById] = useState<Record<string, string>>({});
+
+  useEffect(() => {
+    setAttachments(seededAttachments);
+  }, [seededAttachments]);
+
+  useEffect(() => {
+    if (!lineageId) return;
+    if (seededAttachments.length > 0) return;
+    let active = true;
+    void loadReferenceAttachmentsForLineageId(lineageId)
+      .then((loaded) => {
+        if (!active || !loaded.length) return;
+        setAttachments(loaded);
+      })
+      .catch(() => undefined);
+    return () => {
+      active = false;
+    };
+  }, [lineageId, seededAttachments.length]);
+
+  useEffect(() => {
+    if (!attachments.length) {
+      setAttachmentLinksById({});
+      return;
+    }
+    let active = true;
+    const staticLinks = new Map<string, string>();
+    const storageLookups: Array<{ id: string; storagePath: string }> = [];
+
+    for (const attachment of attachments) {
+      if (attachment.storagePath) {
+        storageLookups.push({ id: attachment.id, storagePath: attachment.storagePath });
+        continue;
+      }
+      const sourceHref = normalizeReferenceDetailHttpUri(attachment.sourceUri);
+      if (sourceHref) staticLinks.set(attachment.id, sourceHref);
+    }
+
+    if (!storageLookups.length) {
+      setAttachmentLinksById(Object.fromEntries(staticLinks.entries()));
+      return () => {
+        active = false;
+      };
+    }
+
+    setAttachmentLinksById(Object.fromEntries(staticLinks.entries()));
+    void Promise.all(storageLookups.map(async (lookup) => {
+      const result = await loadStoragePathUrl(lookup.storagePath);
+      return { id: lookup.id, url: result.url };
+    }))
+      .then((resolved) => {
+        if (!active) return;
+        const nextLinks = Object.fromEntries(staticLinks.entries());
+        for (const entry of resolved) {
+          if (entry.url) nextLinks[entry.id] = entry.url;
+        }
+        setAttachmentLinksById(nextLinks);
+      })
+      .catch(() => undefined);
+
+    return () => {
+      active = false;
+    };
+  }, [attachments]);
+
+  const previewAttachments = useMemo(
+    () => attachments.map((attachment) => ({
+      ...attachment,
+      sourceUri: attachmentLinksById[attachment.id] ?? attachment.sourceUri,
+    })),
+    [attachmentLinksById, attachments],
+  );
+
+  return previewAttachments;
+}

package/components/use-reference-ratings.ts

@@ -41,18 +41,29 @@ export type RatingController = {
  * 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 }: {
+export function useRatingStore({ save, saved, seed, needsReason, sticky, saveNote }: {
   save: RatingSave;
   saved: (id: string) => ReviewChoice | null;
   seed: (id: string) => { note: string; reasonCode: ReferenceRejectionReasonCode | null };
+  /** Whether a Reject on this item must wait for a reason code. Default yes (a Reference); an AI draft or an email asks nothing. */
+  needsReason?: (id: string) => boolean;
+  /**
+   * True for an item whose decision, once made, cannot be sent again (an AI draft moves its Proposal, a review request closes, a held email is
+   * queued). A reason typed after such a decision goes to `saveNote` instead, onto the decision that exists.
+   */
+  sticky?: (id: string) => boolean;
+  /** Saves the reason of an item that is already decided and sticky. Throws a sentence when it cannot. */
+  saveNote?: (id: string, note: string) => Promise<void>;
 }): RatingController {
   const [items, setItems] = useState<Record<string, ItemRating>>({});
   const itemsRef = useRef(items);
-  const latest = useRef({ save, saved, seed });
-  latest.current = { save, saved, seed };
+  const latest = useRef({ save, saved, seed, needsReason, sticky, saveNote });
+  latest.current = { save, saved, seed, needsReason, sticky, saveNote };
   const timers = useRef<Record<string, ReturnType<typeof setTimeout>>>({});
   const inFlight = useRef<Set<string>>(new Set());
   const dirty = useRef<Set<string>>(new Set());
+  const decidedHere = useRef<Set<string>>(new Set());
+  const noteInFlight = useRef<Set<string>>(new Set());
 
   const patch = useCallback((id: string, change: Partial<ItemRating>) => {
     const next = { ...itemsRef.current, [id]: { ...(itemsRef.current[id] ?? EMPTY), ...change } };
@@ -73,9 +84,34 @@ export function useRatingStore({ save, saved, seed }: {
     return { note: item.note ?? seeded.note, reasonCode: item.reasonCode !== undefined ? item.reasonCode : seeded.reasonCode };
   };
 
+  /** True once a sticky item has its decision: from then on only its reason can change. */
+  const finalDecision = (id: string) => Boolean(latest.current.sticky?.(id) && latest.current.saveNote && (decidedHere.current.has(id) || latest.current.saved(id)));
+
+  /** A reason typed after the decision: saved onto it. The text stays in the store until it is saved, and a failed save never drops it. */
+  const saveNoteOnly = useCallback(async (id: string): Promise<void> => {
+    if (noteInFlight.current.has(id)) { dirty.current.add(`note:${id}`); return; }
+    noteInFlight.current.add(id);
+    dirty.current.delete(`note:${id}`);
+    const started = itemsRef.current[id]?.note;
+    const { note } = values(id);
+    patch(id, { feedback: { phase: "saving" } });
+    try {
+      await latest.current.saveNote!(id, note.trim());
+      const now = itemsRef.current[id];
+      patch(id, { feedback: { phase: "saved" }, ...(now?.note === started ? { note: undefined } : {}) });
+    } catch (failure) {
+      dirty.current.add(`note:${id}`); // still unsaved: tapping away, or the next pause, tries again
+      patch(id, { feedback: { phase: "error", message: failure instanceof Error ? failure.message : "Your note could not be saved. It is kept here; keep typing or tap away to try again." } });
+    } finally {
+      noteInFlight.current.delete(id);
+    }
+    if (itemsRef.current[id]?.feedback.phase !== "error" && dirty.current.delete(`note:${id}`)) void saveNoteOnly(id);
+  }, [patch]);
+
   const commit = useCallback(async (id: string, choice: ReviewChoice) => {
+    if (finalDecision(id)) { void saveNoteOnly(id); return; }
     const { note, reasonCode } = values(id);
-    if (choice === "reject" && !reasonCode) { patch(id, { pending: "reject", askReason: true }); return; }
+    if (choice === "reject" && !reasonCode && (latest.current.needsReason?.(id) ?? true)) { 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);
@@ -83,6 +119,7 @@ export function useRatingStore({ save, saved, seed }: {
     patch(id, { pending: choice, askReason: false, feedback: { phase: "saving" } });
     try {
       await latest.current.save(id, choice, { note: note.trim(), reasonCode: choice === "reject" ? reasonCode : null });
+      if (latest.current.sticky?.(id)) decidedHere.current.add(id);
       // 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 } : {}) });
@@ -93,11 +130,12 @@ export function useRatingStore({ save, saved, seed }: {
       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]);
+  }, [patch, saveNoteOnly]);
 
   const effective = (id: string): ReviewChoice | null => itemsRef.current[id]?.pending ?? latest.current.saved(id);
 
   const choose = useCallback((id: string, choice: ReviewChoice) => {
+    if (finalDecision(id)) return; // a decision that cannot be sent again is only ever given a reason, never a second vote
     if (effective(id) === choice && !itemsRef.current[id]?.askReason) return; // the chosen answer never unselects itself
     void commit(id, choice);
   }, [commit]);
@@ -126,7 +164,20 @@ export function useRatingStore({ save, saved, seed }: {
 
   const cancelReason = useCallback((id: string) => patch(id, { pending: null, askReason: false }), [patch]);
 
-  useEffect(() => () => { for (const timer of Object.values(timers.current)) clearTimeout(timer); }, []);
+  // Leaving the page (or closing the view) saves what was typed and not yet saved, rather than dropping it.
+  const leaving = useRef<() => void>(() => undefined);
+  leaving.current = () => {
+    for (const key of [...dirty.current]) {
+      if (!key.startsWith("note:")) continue;
+      const id = key.slice(5);
+      const choice = effective(id);
+      if (choice && dirty.current.delete(key)) void commit(id, choice);
+    }
+  };
+  useEffect(() => () => {
+    for (const timer of Object.values(timers.current)) clearTimeout(timer);
+    leaving.current();
+  }, []);
 
   return { get, choose, setReason, setNote, commitNote, cancelReason };
 }

package/lib/needs-me-items.ts

@@ -0,0 +1,289 @@
+/**
+ * The adapters that turn what already exists into `NeedsMeItem`s, the one model the "What needs me" feed ranks and renders.
+ * Each adapter only reads; deciding is routed back to the existing action for that source (see components/notification-center.tsx).
+ *
+ *   reference          a pending Reference                          reads the Reference, the Cyclotron's decision on it, its preview
+ *   incomplete_capture a pending Reference whose captured text is   reads the same, plus the Reference's capture status (the
+ *                      missing or cut off                            `curation` card, else the extracted-text attachments)
+ *   draft              one AI draft in an open draft review          reads the review request and the Proposal (headline, dek, sources)
+ *   stage_review       an open hard gate or soft review that is      reads the review request (reason, ask, deadline, subject) and the
+ *                      not about drafts                              subject story's title and excerpt
+ *   flag               an open flag                                  reads the review request
+ *   held_email         an email submission held for review           reads the monitoring email summary (subject, sender, verdicts)
+ *   concept_proposal   a proposed taxonomy concept or reader         STUB: typed, returns nothing until those sources reach the page
+ *                      proposal
+ */
+import type { ReferenceRecord } from "./category-repository";
+import type { MonitoringEmailSummary } from "./monitoring-overview";
+import { buildNotificationItems, draftPicture, requestSource, type DraftItem, type RequestItem } from "./notification-feed";
+import { referenceDisplayTitle, referenceLineageId } from "./newsroom-references";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+import { dekAddsInformation, referenceDek, referenceSourceHost, type ReferencePreview } from "./reference-preview";
+import { referenceArrivalTime, referenceDisplayTime } from "./reference-feed-ranking";
+import type { CaptureStatus } from "./reference-capture";
+import type { RelevanceDecisionView } from "./relevance-decisions";
+import type { DraftView } from "./review-drafts";
+import { nextText, type ReviewRequest } from "./review-requests";
+import { predictionOf, uncertaintyOf, type NeedsMeCounts, type NeedsMeDecisionState, type NeedsMeItem } from "./needs-me-ranking";
+
+export type NeedsMePayload =
+  | { kind: "reference"; reference: ReferenceRecord; lineageId: string; decision: RelevanceDecisionView | undefined; preview: ReferencePreview | undefined; capture: CaptureStatus | undefined; displayTime: number | null }
+  | { kind: "draft"; item: DraftItem; loading: boolean }
+  | { kind: "request"; request: ReviewRequest; storyTitle: string | null; excerpt: string | null; storyDeleted: boolean }
+  | { kind: "email"; summary: MonitoringEmailSummary }
+  | { kind: "concept"; row: ConceptProposalRow };
+
+export type NeedsMeEntry = NeedsMeItem<NeedsMePayload>;
+
+const ACCEPT_WORD = { accept: "Accept", reject: "Reject" } as const;
+
+function timeOf(value: string | null | undefined): number | null {
+  const parsed = value ? Date.parse(value) : NaN;
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function percent(confidence: number | null): string {
+  return confidence === null ? "" : ` ${Math.round(confidence * 100)}%`;
+}
+
+// --- references and captures ----------------------------------------------------------------------------------
+
+/**
+ * Whether a capture was attempted and came up short, and nobody has said otherwise: text that is thin (too short, or showing signs of
+ * being cut off or paywalled), or a curation card that records a failed capture. A Reference nobody has tried to capture yet (the
+ * address only, as monitoring discovers it) is not "incomplete": there is nothing to check.
+ */
+export function captureIsIncomplete(capture: CaptureStatus | undefined): boolean {
+  if (!capture || capture.assessment) return false;
+  return capture.state === "thin" || (capture.state === "none" && capture.source === "curation");
+}
+
+export function referenceDefaultOutcome(decision: RelevanceDecisionView | undefined): string {
+  const prediction = predictionOf(decision);
+  return prediction
+    ? `If you leave it, it stays pending with the Cyclotron's suggestion: ${ACCEPT_WORD[prediction.label]}${percent(prediction.confidence)}.`
+    : "If you leave it, it stays pending. Nothing uses it until someone rates it.";
+}
+
+export type ReferenceSources = {
+  references: ReferenceRecord[];
+  decisions: ReadonlyMap<string, RelevanceDecisionView> | undefined;
+  previews: ReadonlyMap<string, ReferencePreview>;
+  captures: ReadonlyMap<string, CaptureStatus> | undefined;
+  /** Lineage ids rated in this visit: they keep their place showing the answer. */
+  visitRated: ReadonlySet<string>;
+};
+
+/** Pending References (and the ones rated in this visit), as `reference` items, or `incomplete_capture` when the capture is cut off. */
+export function referenceItems(input: ReferenceSources): NeedsMeEntry[] {
+  const items: NeedsMeEntry[] = [];
+  for (const reference of input.references) {
+    const status = normalizeReferenceCurationStatus(reference.curationStatus);
+    const lineageId = referenceLineageId(reference);
+    if (status === "archived") continue;
+    const decided = status === "accepted" || status === "rejected";
+    if (decided && !input.visitRated.has(lineageId)) continue;
+    const decision = input.decisions?.get(lineageId);
+    const preview = input.previews.get(lineageId);
+    const capture = input.captures?.get(lineageId);
+    const prediction = predictionOf(decision);
+    const title = referenceDisplayTitle(reference);
+    const dek = referenceDek(reference, preview);
+    const host = referenceSourceHost(reference);
+    const incomplete = !decided && captureIsIncomplete(capture);
+    items.push({
+      type: incomplete ? "incomplete_capture" : "reference",
+      id: lineageId,
+      title,
+      dek: incomplete ? "The captured text looks cut off or missing, so the Cyclotron cannot judge it well." : dekAddsInformation(title, dek, preview?.imageUrl ?? null) ? dek : null,
+      image: preview?.imageUrl ?? null,
+      source: preview?.siteName ?? host ?? "Unknown source",
+      host,
+      createdAt: referenceArrivalTime(reference) ?? referenceDisplayTime(reference),
+      ...(prediction ? { prediction } : {}),
+      importance: 1,
+      uncertainty: uncertaintyOf(prediction?.pAccept),
+      decisionState: status === "accepted" ? "accepted" : status === "rejected" ? "rejected" : "open",
+      defaultOutcome: incomplete ? "If you leave it, the Reference stays pending with the text it has." : referenceDefaultOutcome(decision),
+      hardGate: false,
+      askedForReview: Boolean(decision?.reviewRecommended),
+      payload: { kind: "reference", reference, lineageId, decision, preview, capture, displayTime: referenceDisplayTime(reference) },
+    });
+  }
+  return items;
+}
+
+// --- drafts, stories, flags -------------------------------------------------------------------------------------
+
+function choiceState(choice: "accept" | "reject" | null | undefined): NeedsMeDecisionState {
+  return choice === "accept" ? "accepted" : choice === "reject" ? "rejected" : "open";
+}
+
+export function draftItem(item: DraftItem, bySource: ReadonlyMap<string, ReferencePreview>): NeedsMeEntry {
+  const { view, request } = item;
+  const picture = draftPicture(view, bySource);
+  const link = request.links.find((entry) => entry.id === item.draftId);
+  return {
+    type: "draft",
+    id: item.key,
+    title: view?.headline ?? link?.label ?? "Draft",
+    dek: view ? view.dek : "Loading the draft…",
+    image: picture.imageUrl,
+    source: picture.siteName ?? picture.host ?? (view ? `AI ${view.kindLabel.toLowerCase()}` : "AI draft"),
+    host: picture.host,
+    createdAt: timeOf(request.raisedAt),
+    importance: 1,
+    uncertainty: uncertaintyOf(undefined),
+    decisionState: choiceState(item.decision?.choice),
+    defaultOutcome: nextText(request),
+    hardGate: request.mode === "hard_gate",
+    askedForReview: true,
+    payload: { kind: "draft", item, loading: !view },
+  };
+}
+
+function requestDecisionState(request: ReviewRequest): NeedsMeDecisionState {
+  if (request.state === "open") return "open";
+  const answer = request.answer;
+  if (!answer) return "accepted";
+  if (answer.decision === "acknowledge" || (answer.decision === "approve" && request.mode === "flag")) return "acknowledged";
+  if (answer.decision === "reject" || (answer.decision === "feedback" && answer.steer === "not_this_kind")) return "rejected";
+  return "accepted";
+}
+
+export function requestItem(
+  item: RequestItem,
+  context: { titles: Readonly<Record<string, string>>; excerpts: Readonly<Record<string, string>>; deleted: ReadonlySet<string> },
+): NeedsMeEntry {
+  const { request } = item;
+  const storyId = request.subject.type === "story" ? request.subject.id : null;
+  const flag = request.mode === "flag";
+  return {
+    type: flag ? "flag" : "stage_review",
+    id: request.id,
+    title: request.reason,
+    dek: request.ask,
+    image: null,
+    source: requestSource(request),
+    host: null,
+    createdAt: timeOf(request.raisedAt),
+    importance: 1,
+    uncertainty: uncertaintyOf(undefined),
+    decisionState: requestDecisionState(request),
+    defaultOutcome: nextText(request),
+    hardGate: request.mode === "hard_gate",
+    askedForReview: true,
+    payload: {
+      kind: "request",
+      request,
+      storyTitle: storyId ? context.titles[storyId] ?? null : null,
+      excerpt: storyId ? context.excerpts[storyId] ?? null : null,
+      storyDeleted: storyId ? context.deleted.has(storyId) : false,
+    },
+  };
+}
+
+// --- held email --------------------------------------------------------------------------------------------------
+
+function senderDomain(summary: MonitoringEmailSummary): string | null {
+  const from = summary.headerFrom || summary.envelopeSender || "";
+  const address = from.match(/@([A-Za-z0-9.-]+\.[A-Za-z]{2,})/);
+  return address ? address[1].toLowerCase() : null;
+}
+
+/** The decision recorded on a receipt, else the one made in this visit. */
+export function emailDecisionState(summary: MonitoringEmailSummary, decided: ReadonlyMap<string, "accept" | "reject">): NeedsMeDecisionState {
+  const made = decided.get(summary.receiptId) ?? summary.quarantine?.decision?.action;
+  return choiceState(made);
+}
+
+/** Held email submissions: untrusted, so only the subject and sender facts are used; the body is read in the detail pane as inert text. */
+export function heldEmailItems(summaries: readonly MonitoringEmailSummary[], decided: ReadonlyMap<string, "accept" | "reject">): NeedsMeEntry[] {
+  const items: NeedsMeEntry[] = [];
+  for (const summary of summaries) {
+    const held = summary.quarantine?.state === "quarantined";
+    const decision = emailDecisionState(summary, decided);
+    if (!held && !decided.has(summary.receiptId)) continue;
+    const domain = senderDomain(summary);
+    items.push({
+      type: "held_email",
+      id: `email#${summary.receiptId}`,
+      title: summary.subject?.trim() || "(no subject)",
+      dek: summary.warnings.length ? `Held for review: ${summary.warnings.join(", ")}.` : `Held for review. ${summary.linkCount} candidate ${summary.linkCount === 1 ? "link" : "links"}.`,
+      image: null,
+      source: domain ?? "Email submission",
+      host: domain,
+      createdAt: timeOf(summary.observedAt),
+      importance: 1,
+      uncertainty: uncertaintyOf(undefined),
+      decisionState: decision,
+      defaultOutcome: "If you leave it, it stays held privately. Nothing is routed from it unless you accept it.",
+      hardGate: false,
+      askedForReview: true,
+      payload: { kind: "email", summary },
+    });
+  }
+  return items;
+}
+
+// --- stubs ---------------------------------------------------------------------------------------------------------
+
+/** A proposed taxonomy concept or a reader's proposal. Not on the page yet: the source is typed so the adapter has a place to land. */
+export type ConceptProposalRow = { id: string; title: string; summary: string | null; proposedBy: "cyclotron" | "reader"; createdAt: string | null };
+
+export function conceptProposalItems(_rows: readonly ConceptProposalRow[]): NeedsMeEntry[] {
+  return [];
+}
+
+// --- all of it -----------------------------------------------------------------------------------------------------
+
+export type NeedsMeSources = ReferenceSources & {
+  requests: ReviewRequest[];
+  drafts: Readonly<Record<string, DraftView | undefined>>;
+  missingDrafts: ReadonlySet<string>;
+  draftsState: "loading" | "ready" | "failed";
+  /** Draft keys and request ids decided in this visit. */
+  stay: ReadonlySet<string>;
+  bySource: ReadonlyMap<string, ReferencePreview>;
+  storyTitles: Readonly<Record<string, string>>;
+  storyExcerpts: Readonly<Record<string, string>>;
+  deletedStories: ReadonlySet<string>;
+  emails: readonly MonitoringEmailSummary[];
+  emailsDecided: ReadonlyMap<string, "accept" | "reject">;
+  concepts?: readonly ConceptProposalRow[];
+};
+
+/** Every source, as one list of items (unordered: `rankNeedsMe` orders it). */
+export function buildNeedsMeItems(sources: NeedsMeSources): NeedsMeEntry[] {
+  const fromRequests = buildNotificationItems({
+    requests: sources.requests, drafts: sources.drafts, missingDrafts: sources.missingDrafts, draftsState: sources.draftsState, stay: sources.stay,
+  });
+  const context = { titles: sources.storyTitles, excerpts: sources.storyExcerpts, deleted: sources.deletedStories };
+  return [
+    ...referenceItems(sources),
+    ...fromRequests.drafts.map((item) => draftItem(item, sources.bySource)),
+    ...fromRequests.reviews.map((item) => requestItem(item, context)),
+    ...fromRequests.flags.map((item) => requestItem(item, context)),
+    ...heldEmailItems(sources.emails, sources.emailsDecided),
+    ...conceptProposalItems(sources.concepts ?? []),
+  ];
+}
+
+function plural(count: number, one: string, many = `${one}s`): string {
+  return `${count} ${count === 1 ? one : many}`;
+}
+
+/** "3 drafts and 12 references waiting for you"; "All caught up" when nothing waits. */
+export function waitingTextFor(counts: NeedsMeCounts): string {
+  const parts = [
+    counts.drafts ? plural(counts.drafts, "draft") : null,
+    counts.references ? plural(counts.references, "reference") : null,
+    counts.stories ? plural(counts.stories, "story review") : null,
+    counts.email ? plural(counts.email, "held email", "held emails") : null,
+    counts.captures ? plural(counts.captures, "capture to check", "captures to check") : null,
+    counts.other ? plural(counts.other, "other item") : null,
+  ].filter((part): part is string => part !== null);
+  if (!parts.length) return "All caught up";
+  const list = parts.length === 1 ? parts[0] : `${parts.slice(0, -1).join(", ")} and ${parts[parts.length - 1]}`;
+  return `${list} waiting for you`;
+}