@anthusai/papyrus 5.43.0-next.4 → 5.43.0-next.41

package/lib/needs-me-ranking.ts

@@ -0,0 +1,315 @@
+/**
+ * How the "What needs me" feed is ordered, and which items the Cyclotron is confident enough about to decide on its own.
+ *
+ * The feed holds several kinds of item (a Reference, an AI draft, a story review, a held email, a capture that may be cut off, a flag).
+ * What they share is one question: where would a person's answer change the most? In plain words, as the page says them:
+ *   1. Hard gates first. Nothing continues until a person decides one, so it leads, oldest first.
+ *   2. Then the interim "value of your input" score:
+ *        value = uncertainty x importance x freshness
+ *      - uncertainty is 1 - |2P - 1|, where P is the Cyclotron's probability that you would Accept. A coin toss (P = 0.5) is 1, a
+ *        certainty is 0. An item with no prediction is 0.5: we do not know how unsure we are.
+ *      - importance is the item's own priority (a relevance score, or a story or section priority). It is 1 until a source gives one.
+ *      - freshness is exp(-age / tau), the weight the References feed already uses; tau is learned from how old the References you
+ *        accepted were when you accepted them (reference-feed-ranking.ts). With too few examples there is no decay.
+ *   3. Types are interleaved, never more than two of one type in a row while another type is waiting, so a long run of References
+ *      does not bury the drafts and emails behind it.
+ *   4. Confident items do not ask for you. An item whose uncertainty is below the threshold goes to "Decided automatically", where it
+ *      can be overruled. The threshold is the median uncertainty of the predictions you have historically confirmed; with fewer than
+ *      10 such examples there is no threshold and nothing is skipped. A hard gate, an item the Cyclotron itself sent to review, and
+ *      an item with no prediction are never skipped.
+ *
+ * The scoring sits behind one interface, `AttentionModel`. A future Cyclotron "attention" decision (a model that predicts the value of
+ * an editor's input directly) replaces `interimAttention` and nothing else in the page changes.
+ */
+import type { ReferenceRecord } from "./category-repository";
+import { referenceLineageId } from "./newsroom-references";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+import type { RelevanceDecisionView } from "./relevance-decisions";
+import { acceptProbability, MINIMUM_FRESHNESS_EXAMPLES, type FeedFreshness } from "./reference-feed-ranking";
+
+export type NeedsMeType = "reference" | "draft" | "stage_review" | "held_email" | "incomplete_capture" | "concept_proposal" | "flag";
+
+export const NEEDS_ME_TYPES: readonly NeedsMeType[] = ["reference", "draft", "stage_review", "held_email", "incomplete_capture", "concept_proposal", "flag"];
+
+/** The pills above the feed. */
+export type NeedsMeFilter = "all" | "references" | "drafts" | "stories" | "email" | "captures" | "other";
+export const NEEDS_ME_FILTERS: readonly NeedsMeFilter[] = ["all", "references", "drafts", "stories", "email", "captures", "other"];
+export const NEEDS_ME_FILTER_LABELS: Record<NeedsMeFilter, string> = {
+  all: "All", references: "References", drafts: "Drafts", stories: "Stories", email: "Email", captures: "Captures", other: "Other",
+};
+
+const FILTER_OF: Record<NeedsMeType, Exclude<NeedsMeFilter, "all">> = {
+  reference: "references", draft: "drafts", stage_review: "stories", held_email: "email", incomplete_capture: "captures", concept_proposal: "other", flag: "other",
+};
+
+export function filterOfType(type: NeedsMeType): Exclude<NeedsMeFilter, "all"> {
+  return FILTER_OF[type];
+}
+
+export function matchesFilter(item: Pick<NeedsMeItem, "type">, filter: NeedsMeFilter): boolean {
+  return filter === "all" || FILTER_OF[item.type] === filter;
+}
+
+/** The words for a type, used on the card and in the detail pane. */
+export const NEEDS_ME_TYPE_LABELS: Record<NeedsMeType, string> = {
+  reference: "Reference", draft: "AI draft", stage_review: "Story review", held_email: "Held email", incomplete_capture: "Capture check", concept_proposal: "Concept proposal", flag: "For your information",
+};
+
+export type NeedsMePrediction = {
+  label: "accept" | "reject";
+  /** P(the editor accepts). */
+  pAccept: number;
+  /** The confidence the Cyclotron recorded, when it did. */
+  confidence: number | null;
+};
+
+/** Open until a person decides; the three answers are the page's one vocabulary (a flag is acknowledged). */
+export type NeedsMeDecisionState = "open" | "accepted" | "rejected" | "acknowledged";
+
+export type NeedsMeItem<Payload = unknown> = {
+  type: NeedsMeType;
+  /** Unique across types. */
+  id: string;
+  title: string;
+  dek: string | null;
+  /** The picture for the card, or null for the source's fallback tile. */
+  image: string | null;
+  source: string;
+  host: string | null;
+  /** When it reached the newsroom, in milliseconds; null when unknown. */
+  createdAt: number | null;
+  prediction?: NeedsMePrediction;
+  /** The item's own priority. 1 until a source supplies one (a relevance score, a story or section priority). */
+  importance: number;
+  /** 1 - |2P - 1| with a prediction, 0.5 without. */
+  uncertainty: number;
+  decisionState: NeedsMeDecisionState;
+  /** What happens if the editor ignores it, in words. */
+  defaultOutcome: string;
+  /** Nothing continues until a person decides it. */
+  hardGate: boolean;
+  /** The Cyclotron or the step that raised it asked for a person: never decided automatically. */
+  askedForReview: boolean;
+  payload: Payload;
+};
+
+// --- the scoring --------------------------------------------------------------------------------------------------------
+
+export const UNKNOWN_UNCERTAINTY = 0.5;
+
+/** 1 - |2P - 1|: 1 at a coin toss, 0 at a certainty. 0.5 when there is no prediction. */
+export function uncertaintyOf(pAccept: number | undefined): number {
+  if (pAccept === undefined || !Number.isFinite(pAccept)) return UNKNOWN_UNCERTAINTY;
+  return 1 - Math.abs(2 * Math.min(1, Math.max(0, pAccept)) - 1);
+}
+
+export function predictionOf(decision: RelevanceDecisionView | undefined): NeedsMePrediction | undefined {
+  if (!decision) return undefined;
+  const pAccept = acceptProbability(decision);
+  return { label: decision.label === (decision.positiveLabel ?? "include") ? "accept" : "reject", pAccept, confidence: decision.confidence };
+}
+
+const DAY_MILLISECONDS = 86_400_000;
+
+/** exp(-age / tau) at `now`; 1 without a learned tau or an unknown arrival. The References feed's own weight. */
+export function freshnessAt(createdAt: number | null, freshness: FeedFreshness, now: number): number {
+  if (freshness.tauDays === null || createdAt === null) return 1;
+  return Math.exp(-Math.max(now - createdAt, 0) / DAY_MILLISECONDS / freshness.tauDays);
+}
+
+export type AttentionContext = { now: number; freshness: FeedFreshness };
+
+/**
+ * The value of this editor's input on one item. Higher is earlier. The interim model below is a formula; a Cyclotron "attention"
+ * decision implements the same interface and is passed to `rankNeedsMe` in its place.
+ */
+export interface AttentionModel {
+  readonly id: string;
+  value(item: NeedsMeItem, context: AttentionContext): number;
+}
+
+export const interimAttention: AttentionModel = {
+  id: "interim-value-of-input",
+  value: (item, { now, freshness }) => item.uncertainty * item.importance * freshnessAt(item.createdAt, freshness, now),
+};
+
+// --- confident items ----------------------------------------------------------------------------------------------------
+
+export const MINIMUM_CONFIRMED_EXAMPLES = MINIMUM_FRESHNESS_EXAMPLES;
+
+export type ConfidenceThreshold = {
+  /** Null with fewer than MINIMUM_CONFIRMED_EXAMPLES confirmed predictions: nothing is guessed, nothing is skipped. */
+  threshold: number | null;
+  /** How many predictions the editor has confirmed. */
+  examples: number;
+};
+
+/**
+ * Uncertainty below which the Cyclotron decides without you: the median uncertainty of the predictions you confirmed (the Reference you
+ * accepted or rejected agrees with what the Cyclotron said). Half of what you tend to confirm is then confident enough to skip.
+ * `ignore` keeps the item an editor just rated from moving the very feed they are looking at.
+ */
+export function learnConfidenceThreshold(
+  references: ReferenceRecord[],
+  decisions: ReadonlyMap<string, RelevanceDecisionView> | undefined,
+  ignore: ReadonlySet<string> = new Set(),
+): ConfidenceThreshold {
+  const confirmed: number[] = [];
+  for (const reference of references) {
+    const lineageId = referenceLineageId(reference);
+    const decision = decisions?.get(lineageId);
+    const status = normalizeReferenceCurationStatus(reference.curationStatus);
+    if (!decision || ignore.has(lineageId) || (status !== "accepted" && status !== "rejected")) continue;
+    const prediction = predictionOf(decision);
+    if (prediction && prediction.label === (status === "accepted" ? "accept" : "reject")) confirmed.push(uncertaintyOf(prediction.pAccept));
+  }
+  if (confirmed.length < MINIMUM_CONFIRMED_EXAMPLES) return { threshold: null, examples: confirmed.length };
+  confirmed.sort((left, right) => left - right);
+  const middle = Math.floor(confirmed.length / 2);
+  return { threshold: confirmed.length % 2 ? confirmed[middle] : (confirmed[middle - 1] + confirmed[middle]) / 2, examples: confirmed.length };
+}
+
+/** True when the Cyclotron is sure enough that the item does not need a person. */
+export function isConfident(item: NeedsMeItem, threshold: number | null): boolean {
+  return threshold !== null && item.decisionState === "open" && !item.hardGate && !item.askedForReview && item.prediction !== undefined && item.uncertainty < threshold;
+}
+
+// --- the order ----------------------------------------------------------------------------------------------------------
+
+export const MAXIMUM_RUN = 2;
+
+/**
+ * Apple-News-style mixing: keep the order, but never more than `maxRun` of one type in a row while another type is waiting. When a run
+ * is full, the highest-ranked item of a different type goes next. `prior` is what already sits in front of this list.
+ */
+export function interleaveByType<T extends { type: NeedsMeType }>(ordered: readonly T[], maxRun = MAXIMUM_RUN, prior: readonly NeedsMeType[] = []): T[] {
+  const remaining = [...ordered];
+  const placed: T[] = [];
+  const history = [...prior];
+  while (remaining.length) {
+    const last = history[history.length - 1];
+    let run = 0;
+    for (let index = history.length - 1; index >= 0 && history[index] === last; index -= 1) run += 1;
+    let pick = 0;
+    if (last !== undefined && run >= maxRun) {
+      const alternative = remaining.findIndex((item) => item.type !== last);
+      if (alternative >= 0) pick = alternative;
+    }
+    const [next] = remaining.splice(pick, 1);
+    placed.push(next);
+    history.push(next.type);
+  }
+  return placed;
+}
+
+export type NeedsMeRanking<P = unknown> = {
+  /** Hard gates first, then everything that asks for a person, interleaved. */
+  feed: NeedsMeItem<P>[];
+  /** Confident items: decided by the Cyclotron unless overruled. Newest first. */
+  auto: NeedsMeItem<P>[];
+  scores: ReadonlyMap<string, number>;
+  threshold: ConfidenceThreshold;
+};
+
+function newestFirst(left: NeedsMeItem, right: NeedsMeItem): number {
+  return (right.createdAt ?? 0) - (left.createdAt ?? 0) || left.id.localeCompare(right.id);
+}
+
+export function rankNeedsMe<P>(
+  items: readonly NeedsMeItem<P>[],
+  options: { now: number; freshness: FeedFreshness; threshold: ConfidenceThreshold; attention?: AttentionModel },
+): NeedsMeRanking<P> {
+  const attention = options.attention ?? interimAttention;
+  const context: AttentionContext = { now: options.now, freshness: options.freshness };
+  const scores = new Map(items.map((item) => [item.id, attention.value(item, context)]));
+  const score = (item: NeedsMeItem) => scores.get(item.id) ?? 0;
+  const gates = items.filter((item) => item.hardGate).sort((left, right) => (left.createdAt ?? 0) - (right.createdAt ?? 0) || left.id.localeCompare(right.id));
+  const rest = items.filter((item) => !item.hardGate);
+  const auto = rest.filter((item) => isConfident(item, options.threshold.threshold)).sort(newestFirst);
+  const autoIds = new Set(auto.map((item) => item.id));
+  const asking = rest.filter((item) => !autoIds.has(item.id)).sort((left, right) => score(right) - score(left) || newestFirst(left, right));
+  const mixed = interleaveByType(asking, MAXIMUM_RUN, gates.map((item) => item.type));
+  return { feed: [...gates, ...mixed], auto, scores, threshold: options.threshold };
+}
+
+// --- one order per visit ------------------------------------------------------------------------------------------------
+
+/**
+ * The order of the feed, taken once per visit when it has loaded and then left alone: selecting, deciding, a background refresh and a
+ * cache revalidation never re-rank it. Items that arrive later are counted as new and wait behind an "N new items: show" pill.
+ * The same rule as the References feed.
+ */
+export type NeedsMeSnapshot = { known: ReadonlySet<string>; feed: string[]; auto: string[] };
+
+export function takeNeedsMeSnapshot(ranking: Pick<NeedsMeRanking, "feed" | "auto">): NeedsMeSnapshot {
+  return {
+    known: new Set([...ranking.feed, ...ranking.auto].map((item) => item.id)),
+    feed: ranking.feed.map((item) => item.id),
+    auto: ranking.auto.map((item) => item.id),
+  };
+}
+
+/** The live items placed where the snapshot put them. Their content stays current; their places do not. */
+export function applyNeedsMeSnapshot<P>(snapshot: NeedsMeSnapshot, live: Pick<NeedsMeRanking<P>, "feed" | "auto">): { feed: NeedsMeItem<P>[]; auto: NeedsMeItem<P>[]; newCount: number } {
+  const byId = new Map<string, NeedsMeItem<P>>();
+  for (const item of [...live.auto, ...live.feed]) byId.set(item.id, item);
+  const pick = (ids: string[]) => ids.flatMap((id) => { const item = byId.get(id); return item ? [item] : []; });
+  const newCount = [...live.feed, ...live.auto].filter((item) => !snapshot.known.has(item.id) && item.decisionState === "open").length;
+  return { feed: pick(snapshot.feed), auto: pick(snapshot.auto), newCount };
+}
+
+// --- counts and "you're shaping this" -----------------------------------------------------------------------------------
+
+export type NeedsMeCounts = Record<NeedsMeFilter, number>;
+
+/** What waits for a person, by pill: only open items count. */
+export function countNeedsMe(items: readonly Pick<NeedsMeItem, "type" | "decisionState">[]): NeedsMeCounts {
+  const counts: NeedsMeCounts = { all: 0, references: 0, drafts: 0, stories: 0, email: 0, captures: 0, other: 0 };
+  for (const item of items) {
+    if (item.decisionState !== "open") continue;
+    counts.all += 1;
+    counts[FILTER_OF[item.type]] += 1;
+  }
+  return counts;
+}
+
+/** Monday 00:00 UTC of the week that contains `now`: "this week" is a calendar week, not a rolling window. */
+export function weekStartUtc(now: number): number {
+  const date = new Date(now);
+  const day = (date.getUTCDay() + 6) % 7; // Monday = 0
+  return Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() - day);
+}
+
+export type ShapingStats = {
+  /** Everything you decided this week, of any type. */
+  decisions: number;
+  /** Of the References you rated this week that had a prediction: you agreed with the Cyclotron. */
+  agreed: number;
+  /** ... and you overruled it. */
+  overruled: number;
+};
+
+/** The "You're shaping this" strip. `decidedAt` lists when each decision was made (see recentDecisions in notification-feed.ts). */
+export function shapingThisWeek(input: {
+  decidedAt: readonly string[];
+  references: ReferenceRecord[];
+  decisions: ReadonlyMap<string, RelevanceDecisionView> | undefined;
+  now: number;
+}): ShapingStats {
+  const since = weekStartUtc(input.now);
+  const thisWeek = (iso: string | null | undefined) => {
+    const time = iso ? Date.parse(iso) : NaN;
+    return Number.isFinite(time) && time >= since && time <= input.now;
+  };
+  let agreed = 0;
+  let overruled = 0;
+  for (const reference of input.references) {
+    const status = normalizeReferenceCurationStatus(reference.curationStatus);
+    if ((status !== "accepted" && status !== "rejected") || !thisWeek(reference.curationStatusUpdatedAt)) continue;
+    const prediction = predictionOf(input.decisions?.get(referenceLineageId(reference)));
+    if (!prediction) continue;
+    if (prediction.label === (status === "accepted" ? "accept" : "reject")) agreed += 1;
+    else overruled += 1;
+  }
+  return { decisions: input.decidedAt.filter(thisWeek).length, agreed, overruled };
+}

package/lib/newsroom-all-pages.ts

@@ -0,0 +1,21 @@
+/** Every row a paged newsroom read returns, following `nextToken` to the end; rows repeated across pages are kept once. */
+export async function loadAllPages<T extends { id?: string | null }>(
+  loadPage: (nextToken: string | null) => Promise<{ items: T[]; nextToken?: string | null; hasMore: boolean }>,
+): Promise<T[]> {
+  const rows: T[] = [];
+  const seenIds = new Set<string>();
+  const seenTokens = new Set<string>();
+  let nextToken: string | null = null;
+  do {
+    const page = await loadPage(nextToken);
+    for (const row of page.items) {
+      if (!row?.id || seenIds.has(row.id)) continue;
+      seenIds.add(row.id);
+      rows.push(row);
+    }
+    nextToken = page.hasMore ? page.nextToken ?? null : null;
+    if (nextToken && seenTokens.has(nextToken)) throw new Error("The list repeated a page; reload to try again.");
+    if (nextToken) seenTokens.add(nextToken);
+  } while (nextToken);
+  return rows;
+}

package/lib/newsroom-chat-identity.ts

@@ -2,6 +2,7 @@ import { CognitoJwtVerifier } from "aws-jwt-verify";
 import type { JwksCache } from "aws-jwt-verify/jwk";
 import type { NextRequest } from "next/server";
 import { readAmplifyOutputsFile } from "./amplify-outputs-path";
+import { STAFF_GROUPS } from "./staff-groups";
 
 export type NewsroomChatIdentity = { subject: string; issuer: string; clientId: string; expiresAt: number };
 export type NewsroomChatIdentityResolver = (request: NextRequest) => Promise<NewsroomChatIdentity | null>;
@@ -14,7 +15,7 @@ export function newsroomChatIdentityResolver(
     userPoolId: auth.user_pool_id,
     clientId: auth.user_pool_client_id,
     tokenUse: "access",
-    groups: ["editor", "admin"],
+    groups: [...STAFF_GROUPS],
   }, jwksCache ? { jwksCache } : undefined);
   return async (request) => {
     const token = request.headers.get("authorization")?.match(/^Bearer ([^\s]+)$/i)?.[1];

package/lib/newsroom-index-filters.ts

@@ -167,3 +167,21 @@ export function parseAssignmentIdFromNewsroomPathname(pathname: string | null |
     return segment;
   }
 }
+
+/** The Notification Center's deep link to one item: `/newsroom/needs-me/<id>` (public `/needs-me/<id>` on a root-path newsroom). */
+export function buildNeedsMeItemPath(itemId: string): string {
+  return toPublicNewsroomPath(`/newsroom/needs-me/${encodeURIComponent(itemId)}`);
+}
+
+/** Item id from `/newsroom/needs-me/<id>`, else null. */
+export function parseNeedsMeItemIdFromNewsroomPathname(pathname: string | null | undefined): string | null {
+  const internalPathname = pathname ? browserPathToInternalNewsroomPath(pathname) : null;
+  if (!internalPathname?.startsWith("/newsroom/needs-me/")) return null;
+  const segment = internalPathname.slice("/newsroom/needs-me/".length).split("/")[0]?.trim() ?? "";
+  if (!segment) return null;
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}

package/lib/newsroom-nav.ts

@@ -21,7 +21,7 @@ export type NewsroomNavItem = {
 };
 
 export const NEWSROOM_OPS_NAV: NewsroomNavItem[] = [
-  { id: "overview", label: "Overview", detail: "Newsroom home", href: newsroomHref() },
+  { id: "overview", label: "Needs me", detail: "Newsroom home", href: newsroomHref() },
   { id: "articles", label: getContentItemName().plural, detail: "Drafts & published", href: newsroomHref("articles") },
   { id: "assignments", label: "Assignments", detail: "Work queue", href: newsroomHref("assignments") },
   { id: "references", label: "References", detail: "Knowledge base", href: newsroomHref("references") },

package/lib/newsroom-organizer-nav.ts

@@ -8,9 +8,10 @@ export type OrganizerDestination = {
 };
 export const ORGANIZER_NAV_GROUPS: readonly { title: string; items: readonly OrganizerDestination[] }[] = [
   { title: "Editorial work", items: [
-    { key: "overview", label: "Overview", description: "See notifications and work needing attention.", path: "/newsroom", primary: true },
+    { key: "overview", label: "Needs me", description: "See what needs you: drafts, references and reviews.", path: "/newsroom", primary: true },
     { key: "articles", label: getContentItemName().plural, description: `Follow ${contentItemPluralLowercase} across their stages and open one to write or revise it.`, path: `/newsroom/${contentItemBoardPathSegment()}`, alsoActiveOnPaths: ["/newsroom/articles"], primary: true },
     { key: "assignments", label: "Assignments", description: "Follow research and reporting work across its statuses and claim it.", path: "/newsroom/assignments" },
+    { key: "drafts", label: "Drafts", description: "Read the story drafts that AI proposes, then accept or reject them.", path: "/newsroom/administration/proposals" },
     { key: "messages", label: "Messages", description: "Read and reply to newsroom conversations.", path: "/newsroom/messages", primary: true },
   ] },
   { title: "Research & knowledge", items: [

package/lib/newsroom-references.ts

@@ -96,7 +96,31 @@ export function formatReferenceListDate(reference: ReferenceRecord): string {
 }
 
 export function referenceDisplayTitle(reference: ReferenceRecord): string {
-  return reference.title?.trim() || reference.externalItemId;
+  const title = reference.title?.trim();
+  if (!title) return reference.externalItemId;
+  let host: string | null = null;
+  try { host = reference.sourceUri ? new URL(reference.sourceUri).hostname : null; } catch { host = null; }
+  return withoutSiteName(title, host);
+}
+
+const TITLE_SEPARATORS = [" | ", " – ", " — ", " - "] as const;
+
+/**
+ * A page title without the site's name tacked on: "Auditing employment algorithms | Brookings" reads "Auditing employment
+ * algorithms". Only a last segment that names the site (its host's name, such as "brookings" in brookings.edu) is dropped,
+ * and with a pipe, which sites use for furniture, the section names before it go too ("… | Poverty and Development | Al Jazeera").
+ */
+export function withoutSiteName(title: string, host: string | null): string {
+  const label = (host ?? "").toLowerCase().replace(/^www\./, "").split(".").slice(0, -1).filter((part) => part.length >= 4).at(-1);
+  if (!label) return title;
+  const plain = (text: string) => text.toLowerCase().replace(/[^a-z0-9]/g, "");
+  // The separator whose last segment is shortest wins, so "… groups – report - Amnesty International" keeps "– report".
+  const match = TITLE_SEPARATORS.map((separator) => ({ separator, parts: title.split(separator) }))
+    .filter(({ parts }) => parts.length > 1 && plain(parts.at(-1)!).includes(label))
+    .sort((left, right) => left.parts.at(-1)!.length - right.parts.at(-1)!.length)[0];
+  if (!match) return title;
+  const kept = match.separator === " | " ? match.parts[0] : match.parts.slice(0, -1).join(match.separator);
+  return kept.trim() || title;
 }
 
 export function referenceStatusLabel(status: string): string {

package/lib/notification-feed.ts

@@ -0,0 +1,212 @@
+/**
+ * The Notification Center as a feed of cards ("What needs me?"): which cards there are, how they are counted, filtered and
+ * worded. Pure functions, so the page and its tests share them. A review request that covers several AI drafts is not shown as a
+ * batch: each draft is its own card, with a small caption saying which run it came from. The request still closes itself when
+ * its last draft is decided (components/notification-center.tsx).
+ */
+import type { ReferenceRecord } from "./category-repository";
+import { referenceDisplayTitle, referenceLineageId } from "./newsroom-references";
+import { normalizeReferenceCurationStatus } from "./reference-policy";
+import type { ReferencePreview } from "./reference-preview";
+import { draftDecisionOf, type DraftView } from "./review-drafts";
+import { draftIdsOf, isDraftReview, proposalHref, sectionReviews, type DraftDecision, type ReviewRequest } from "./review-requests";
+import { getNewsroomNavHref } from "./newsroom-nav";
+
+export type DraftItem = {
+  kind: "draft";
+  /** `<request id>#<draft id>`. */
+  key: string;
+  request: ReviewRequest;
+  draftId: string;
+  /** Undefined while the Proposal is still loading. */
+  view: DraftView | undefined;
+  decision: DraftDecision | null;
+};
+
+/** A request that is decided as a whole: a hard gate, a soft review of something that is not a draft, or a flag. */
+export type RequestItem = { kind: "request"; key: string; request: ReviewRequest };
+
+export type NotificationItems = {
+  drafts: DraftItem[];
+  /** Hard gates first, then the other soft reviews, soonest deadline first. */
+  reviews: RequestItem[];
+  /** For your information: flags. */
+  flags: RequestItem[];
+};
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"] as const;
+
+/** "Oct 27", in UTC so the words do not change with the reader's time zone. */
+export function shortDate(iso: string | null | undefined): string {
+  if (!iso) return "";
+  const date = new Date(iso);
+  if (Number.isNaN(date.getTime())) return "";
+  return `${MONTHS[date.getUTCMonth()]} ${date.getUTCDate()}`;
+}
+
+function sentenceCase(slug: string): string {
+  const spaced = slug.replace(/[-_.]+/g, " ").trim();
+  return spaced ? spaced[0].toUpperCase() + spaced.slice(1) : "";
+}
+
+/** Where a request came from, in words: the run its batch names ("Monitor stories run"), else the step that raised it. */
+export function requestSource(request: Pick<ReviewRequest, "subject" | "raisedBy">): string {
+  if (request.subject.type === "batch") {
+    const named = request.subject.id.replace(/-\d{8}t\d{6}z.*$/i, "").replace(/-[0-9a-f]{6,}$/i, "");
+    if (/[a-z]{3,}/i.test(named)) return sentenceCase(named);
+  }
+  return sentenceCase(request.raisedBy) || "An automated step";
+}
+
+/** The small caption on a card that came out of a request: "from Monitor stories run · Oct 27". */
+export function requestCaption(request: Pick<ReviewRequest, "subject" | "raisedBy" | "raisedAt">): string {
+  const when = shortDate(request.raisedAt);
+  return `from ${requestSource(request)}${when ? ` · ${when}` : ""}`;
+}
+
+const NO_FALLBACK = { by: "", at: "" } as const;
+
+/**
+ * The cards for review requests. A draft review becomes one card per draft: undecided drafts of open requests, plus drafts decided in
+ * this visit (`stay`, keyed `<request id>#<draft id>`) so a card does not vanish under the editor's thumb. Drafts that are not Proposals
+ * on this site cannot be opened here; when none can, the request itself is one card that takes Accept or Reject.
+ */
+export function buildNotificationItems(input: {
+  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>;
+}): NotificationItems {
+  const sections = sectionReviews(input.requests);
+  const closedHere = input.requests.filter((request) => request.state !== "open" && input.stay.has(request.id));
+  const draftItems: DraftItem[] = [];
+  const requestLevel: ReviewRequest[] = [];
+  const draftRequests = [...sections.draftBatches, ...input.requests.filter((request) => request.state !== "open" && isDraftReview(request) && draftIdsOf(request).some((id) => input.stay.has(`${request.id}#${id}`)))];
+  for (const request of draftRequests) {
+    const available = draftIdsOf(request).filter((id) => !input.missingDrafts.has(id));
+    if (request.state === "open" && input.draftsState === "ready" && available.length === 0) {
+      requestLevel.push(request);
+      continue;
+    }
+    for (const draftId of available) {
+      const key = `${request.id}#${draftId}`;
+      const view = input.drafts[draftId];
+      const decision = draftDecisionOf(request.links.find((link) => link.id === draftId), view, NO_FALLBACK);
+      const waiting = request.state === "open" && !decision;
+      if (waiting || input.stay.has(key)) draftItems.push({ kind: "draft", key, request, draftId, view, decision });
+    }
+  }
+  const asItem = (request: ReviewRequest): RequestItem => ({ kind: "request", key: request.id, request });
+  const standing = (request: ReviewRequest) => request.state === "open" || input.stay.has(request.id);
+  const reviews = [
+    ...sections.hardGates,
+    ...sections.softReviews,
+    ...requestLevel,
+    ...closedHere.filter((request) => request.mode !== "flag" && !isDraftReview(request)),
+  ].filter(standing).map(asItem);
+  const flags = [...sections.flags, ...closedHere.filter((request) => request.mode === "flag")].filter(standing).map(asItem);
+  return {
+    drafts: draftItems,
+    reviews: [...new Map(reviews.map((item) => [item.key, item])).values()],
+    flags: [...new Map(flags.map((item) => [item.key, item])).values()],
+  };
+}
+
+// --- sources, pictures ----------------------------------------------------------------------------------------
+
+function normalizedAddress(address: string): string {
+  try {
+    const url = new URL(address);
+    return `${url.hostname.replace(/^www\./i, "").toLowerCase()}${url.pathname.replace(/\/+$/, "")}${url.search}`;
+  } catch {
+    return address.trim().toLowerCase();
+  }
+}
+
+/** The previews of References by the address they were saved from, so a draft's cited source finds its picture. */
+export function previewsBySourceAddress(references: ReferenceRecord[], previews: ReadonlyMap<string, ReferencePreview>): Map<string, ReferencePreview> {
+  const found = new Map<string, ReferencePreview>();
+  for (const reference of references) {
+    const preview = previews.get(referenceLineageId(reference));
+    if (preview && reference.sourceUri) found.set(normalizedAddress(reference.sourceUri), preview);
+  }
+  return found;
+}
+
+/** The first cited source that has a picture, with the site name its preview gives. */
+export function draftPicture(view: DraftView | undefined, bySource: ReadonlyMap<string, ReferencePreview>): { imageUrl: string | null; siteName: string | null; host: string | null } {
+  const sources = view?.sources ?? [];
+  const host = sources.find((source) => source.url)?.url ? sourceHost(sources.find((source) => source.url)!.url!) : null;
+  for (const source of sources) {
+    const preview = source.url ? bySource.get(normalizedAddress(source.url)) : undefined;
+    if (preview?.imageUrl) return { imageUrl: preview.imageUrl, siteName: preview.siteName, host: source.url ? sourceHost(source.url) : host };
+  }
+  return { imageUrl: null, siteName: null, host };
+}
+
+export function sourceHost(address: string): string | null {
+  try {
+    return new URL(address).hostname.replace(/^www\./i, "") || null;
+  } catch {
+    return null;
+  }
+}
+
+// --- what you decided ------------------------------------------------------------------------------------------
+
+export type RecentDecision = {
+  key: string;
+  kind: "draft" | "reference" | "request";
+  word: "Accepted" | "Rejected" | "Acknowledged" | "Answered";
+  choice: "accept" | "reject" | "acknowledge" | "answer";
+  title: string;
+  at: string;
+  href: string | null;
+  /** The editor's why, when there is one. */
+  note: string | null;
+};
+
+function requestDecision(request: ReviewRequest): Pick<RecentDecision, "word" | "choice"> | null {
+  const answer = request.answer;
+  if (request.state !== "answered" || !answer) return null;
+  if (answer.decision === "acknowledge" || (answer.decision === "approve" && request.mode === "flag")) return { word: "Acknowledged", choice: "acknowledge" };
+  if (answer.decision === "approve") return { word: "Accepted", choice: "accept" };
+  if (answer.decision === "reject") return { word: "Rejected", choice: "reject" };
+  return { word: "Answered", choice: "answer" };
+}
+
+/** What the editor decided most recently, newest first: drafts, other requests and References. "Last few", so a small default. */
+export function recentDecisions(requests: ReviewRequest[], references: ReferenceRecord[], demo = false, limit = 5): RecentDecision[] {
+  const found = new Map<string, RecentDecision>();
+  for (const request of requests) {
+    for (const link of request.links) {
+      if (!link.decision || !link.id) continue;
+      found.set(`${request.id}#${link.id}`, {
+        key: `${request.id}#${link.id}`, kind: "draft", word: link.decision.choice === "accept" ? "Accepted" : "Rejected", choice: link.decision.choice,
+        title: link.decision.title ?? link.label ?? link.id, at: link.decision.at, href: proposalHref(link.id, demo), note: link.decision.why ?? null,
+      });
+    }
+    for (const entry of request.answer?.drafts ?? []) {
+      found.set(`${request.id}#${entry.id}`, {
+        key: `${request.id}#${entry.id}`, kind: "draft", word: entry.choice === "accept" ? "Accepted" : "Rejected", choice: entry.choice,
+        title: entry.title ?? entry.id, at: entry.at, href: proposalHref(entry.id, demo), note: entry.why ?? null,
+      });
+    }
+    const whole = requestDecision(request);
+    if (whole && !request.answer?.drafts?.length) {
+      found.set(request.id, { key: request.id, kind: "request", ...whole, title: request.reason, at: request.answer!.at, href: null, note: request.answer!.feedback });
+    }
+  }
+  for (const reference of references) {
+    const status = normalizeReferenceCurationStatus(reference.curationStatus);
+    if ((status !== "accepted" && status !== "rejected") || !reference.curationStatusUpdatedAt) continue;
+    const lineageId = referenceLineageId(reference);
+    found.set(`reference#${lineageId}`, {
+      key: `reference#${lineageId}`, kind: "reference", word: status === "accepted" ? "Accepted" : "Rejected", choice: status === "accepted" ? "accept" : "reject",
+      title: referenceDisplayTitle(reference), at: reference.curationStatusUpdatedAt, href: getNewsroomNavHref(`/newsroom/references/${encodeURIComponent(lineageId)}`, demo), note: null,
+    });
+  }
+  return [...found.values()].filter((entry) => entry.at).sort((a, b) => b.at.localeCompare(a.at)).slice(0, limit);
+}