@anthusai/papyrus 2.0.0-next.2 → 2.0.0-next.21

package/lib/editorial-checks-demo.ts

@@ -0,0 +1,147 @@
+/**
+ * Demo-mode editorial checks: no backend, a few stock phrases, canned rewrites.
+ * The shapes match Humanus results so the editor, the preview marks and the
+ * rewrite flow behave as they do against the real backend.
+ */
+import type { EditorialCheckResult, EditorialFinding, EditorialSegment, RewriteResult, Span } from "./editorial-checks";
+import type { EditorialChecksBackend } from "./editorial-checks-backend";
+import { DEFAULT_EDITORIAL_SETTINGS } from "./editorial-checks-settings";
+
+type DemoRule = { policyId: string; phrase: RegExp; severity: EditorialFinding["severity"]; message: string; replacement?: string };
+
+const RULES: DemoRule[] = [
+  { policyId: "promotional-language", phrase: /\bgame[- ]changing\b/gi, severity: "warn", message: "Say what changed instead of calling it game-changing." },
+  { policyId: "plain-words", phrase: /\butilize\b/gi, severity: "info", message: "Prefer the plain word.", replacement: "use" },
+  { policyId: "formulaic-openers", phrase: /\bIn today's [a-z-]+ world\b/gi, severity: "info", message: "Formulaic opener: start with the point." },
+];
+
+/** Demo rewrites keyed by a phrase in the target; anything else gets a clearly labelled placeholder. */
+const CANNED: Record<string, string[]> = {
+  "game-changing": ["Our caching layer cuts build times for teams.", "Teams get faster builds from our caching layer."],
+  "Builds finish in 4 minutes": ["Builds now take 4 minutes, down from 9.", "A build takes 4 minutes instead of 9."],
+};
+
+export function demoPlainText(source: string): string {
+  return source
+    .replace(/^#{1,6}\s+/, "")
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/\s?\[@[^\]]+\]/g, "")
+    .replace(/(\*\*|__|\*|_|~~|`)/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function hash(text: string): string {
+  let value = 0;
+  for (let i = 0; i < text.length; i += 1) value = (value * 31 + text.charCodeAt(i)) >>> 0;
+  return value.toString(16).padStart(8, "0");
+}
+
+/** Paragraph and sentence segments of a body, by blank lines and sentence-ending punctuation. */
+export function demoSegments(body: string): EditorialSegment[] {
+  const segments: EditorialSegment[] = [{ id: "doc", kind: "document", start: 0, end: body.length, textHash: hash(body) }];
+  const fence = /^(```|~~~)/;
+  let inFence = false;
+  for (const match of body.matchAll(/[^\n]+(?:\n[^\n]+)*/g)) {
+    const raw = match[0];
+    const start = match.index ?? 0;
+    if (fence.test(raw.trim())) inFence = !inFence;
+    if (inFence || fence.test(raw.trim()) || /^(:::|::|>|\||---)/.test(raw.trim())) continue;
+    const block = raw.trim().startsWith("#") ? "heading" : /^([-*+]|\d+\.)\s/.test(raw.trim()) ? "listItem" : "paragraph";
+    const sourceStart = start + raw.length - raw.replace(/^(#{1,6}|[-*+]|\d+\.)\s+/, "").length;
+    const text = demoPlainText(raw);
+    const paragraphId = `p-${hash(text)}`;
+    segments.push({ id: paragraphId, kind: "paragraph", block, start: sourceStart, end: start + raw.length, textHash: hash(text), text });
+    const sentencePattern = /[^.!?]+[.!?]+(?=\s|$)|[^.!?]+$/g;
+    for (const sentence of body.slice(sourceStart, start + raw.length).matchAll(sentencePattern)) {
+      const leading = sentence[0].length - sentence[0].trimStart().length;
+      const sStart = sourceStart + (sentence.index ?? 0) + leading;
+      const sText = sentence[0].trim();
+      if (!sText) continue;
+      segments.push({
+        id: `s-${hash(sText)}`,
+        kind: "sentence",
+        block,
+        parentId: paragraphId,
+        start: sStart,
+        end: sStart + sText.length,
+        textHash: hash(sText),
+        text: demoPlainText(sText),
+      });
+    }
+  }
+  return segments;
+}
+
+export function demoCheck(body: string): EditorialCheckResult {
+  const segments = demoSegments(body);
+  const sentences = segments.filter((segment) => segment.kind === "sentence");
+  const findings: EditorialFinding[] = [];
+  for (const rule of RULES) {
+    for (const match of body.matchAll(rule.phrase)) {
+      const start = match.index ?? 0;
+      const end = start + match[0].length;
+      const sentence = sentences.find((segment) => segment.start <= start && end <= segment.end);
+      if (!sentence) continue;
+      findings.push({
+        id: `f-${hash(`${rule.policyId}|${sentence.text}|${match[0]}`)}${hash(String(start)).slice(0, 8)}`,
+        policyId: rule.policyId,
+        policyVersion: 1,
+        detectorId: `${rule.policyId}-demo`,
+        lane: "rules",
+        severity: rule.severity,
+        status: "violation",
+        segmentId: sentence.id,
+        span: { start, end },
+        excerpt: match[0],
+        excerptText: match[0],
+        message: rule.message,
+        ...(rule.replacement ? { replacement: rule.replacement } : {}),
+      });
+    }
+  }
+  return {
+    schemaVersion: 1,
+    offsetUnit: "utf16",
+    document: { hash: `demo:${hash(body)}`, length: body.length },
+    pack: { packId: "demo", version: "1" },
+    segments,
+    protected: [],
+    findings: findings.sort((a, b) => a.span.start - b.span.start),
+    coverage: [],
+    lanes: { rules: { status: "ran", detectors: RULES.length }, classifier: { status: "disabled" } },
+  };
+}
+
+export function demoSuggest(body: string, target: { finding: EditorialFinding } | { selection: Span }): RewriteResult {
+  let span: Span;
+  if ("finding" in target) {
+    const sentence = demoSegments(body).find((s) => s.kind === "sentence" && s.start <= target.finding.span.start && target.finding.span.end <= s.end);
+    span = sentence ? { start: sentence.start, end: sentence.end } : target.finding.span;
+  } else {
+    span = target.selection;
+  }
+  const excerpt = body.slice(span.start, span.end);
+  const replacements = Object.entries(CANNED).find(([phrase]) => excerpt.includes(phrase))?.[1] ?? [`${demoPlainText(excerpt)} (demo rewrite)`];
+  return {
+    target: { ...("finding" in target ? { findingId: target.finding.id } : {}), span, excerpt },
+    model: "demo",
+    options: replacements.map((replacement, index) => ({
+      id: `o-demo-${index}`,
+      span,
+      replacement,
+      rationale: index === 0 ? "Says what changed, plainly." : "An alternative phrasing.",
+      factVerificationRequired: false,
+      unresolvedQuestions: [],
+    })),
+  };
+}
+
+export const demoEditorialBackend: EditorialChecksBackend = {
+  loadSettings: async () => ({ settings: DEFAULT_EDITORIAL_SETTINGS, exists: false }),
+  dismissedFindingIds: async () => new Set(),
+  check: async (body) => demoCheck(body),
+  suggest: async (body, _section, target) => demoSuggest(body, target),
+  recordFeedback: async () => undefined,
+};

package/lib/editorial-checks-settings.ts

@@ -0,0 +1,27 @@
+/** Runtime settings for editorial checks, stored in EditorialCheckSettings (id "settings"). */
+export type EditorialSettings = {
+  /** Core to every site and on by default; a publication turns its checks off here. */
+  enabled: boolean;
+  lanes: { rules: boolean; classifier: boolean };
+  classifierModel: string;
+  rewriteModel: string;
+  deadlineSeconds: number;
+  maxInputTokens: number;
+  maxExamplesPerQuestion: number;
+  guidance: string;
+  publishWarning: boolean;
+  checkWhileTyping: boolean;
+};
+
+export const DEFAULT_EDITORIAL_SETTINGS: EditorialSettings = {
+  enabled: true,
+  lanes: { rules: true, classifier: true },
+  classifierModel: "jev-latest",
+  rewriteModel: "gpt-6-luna",
+  deadlineSeconds: 20,
+  maxInputTokens: 500000,
+  maxExamplesPerQuestion: 4,
+  guidance: "",
+  publishWarning: true,
+  checkWhileTyping: true,
+};

package/lib/editorial-checks.ts

@@ -0,0 +1,171 @@
+/**
+ * Editorial checks: the Humanus result shapes the newsroom uses, and pure helpers
+ * over them. Humanus counts offsets in UTF-16 code units, which is exactly how
+ * JavaScript indexes strings, so spans apply to the body text as they are.
+ */
+
+export type Span = { start: number; end: number };
+export type Severity = "info" | "warn" | "error";
+
+export type EditorialFinding = {
+  id: string;
+  policyId: string;
+  policyVersion: number;
+  detectorId: string;
+  lane: "rules" | "classifier";
+  severity: Severity;
+  status: "violation" | "review";
+  segmentId: string;
+  span: Span;
+  excerpt: string;
+  /** The excerpt as a reader sees it (inline markup removed). */
+  excerptText?: string;
+  message: string;
+  probability?: number;
+  rawProbability?: number;
+  replacement?: string;
+};
+
+export type EditorialSegment = {
+  id: string;
+  kind: "document" | "paragraph" | "sentence";
+  block?: "paragraph" | "heading" | "listItem";
+  parentId?: string;
+  start: number;
+  end: number;
+  textHash: string;
+  /** Plain prose of a paragraph or sentence segment. */
+  text?: string;
+};
+
+export type LaneStatus = { status: "ran" | "disabled" | "unavailable" | "failed" | "partial"; reason?: string; detectors?: number };
+
+export type EditorialCheckResult = {
+  schemaVersion: 1;
+  offsetUnit: "utf16";
+  document: { hash: string; length: number };
+  pack: { packId: string; version: string };
+  segments: EditorialSegment[];
+  protected: { kind: string; start: number; end: number }[];
+  findings: EditorialFinding[];
+  coverage: unknown[];
+  lanes: { rules: LaneStatus; classifier: LaneStatus };
+  usage?: Record<string, number>;
+};
+
+export type RewriteOption = {
+  id: string;
+  span: Span;
+  replacement: string;
+  rationale: string;
+  factVerificationRequired: boolean;
+  unresolvedQuestions: string[];
+};
+
+export type RewriteResult = {
+  target: { findingId?: string; span: Span; excerpt: string };
+  model: string;
+  options: RewriteOption[];
+  dropped?: { replacement: string; reason: string }[];
+};
+
+export type FeedbackDecision = "accepted" | "fixed" | "dismissed";
+
+export type EditorialFeedbackInput = {
+  itemId: string;
+  findingId: string;
+  policyId: string;
+  detectorId: string;
+  lane: EditorialFinding["lane"];
+  probability: number | null;
+  decision: FeedbackDecision;
+  reason: string | null;
+  text: string | null;
+};
+
+/** Decisions on an article that has never been saved are kept under this id. */
+export const UNSAVED_ITEM_ID = "unsaved";
+
+const SEVERITY_ORDER: Record<Severity, number> = { error: 0, warn: 1, info: 2 };
+
+/** Findings worth showing: not dismissed, not covering the whole document, most severe first, then in reading order. */
+export function visibleFindings(findings: EditorialFinding[], dismissed: ReadonlySet<string>): EditorialFinding[] {
+  return findings
+    .filter((finding) => !dismissed.has(finding.id))
+    .sort(
+      (a, b) =>
+        SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] ||
+        a.span.start - b.span.start ||
+        a.policyId.localeCompare(b.policyId),
+    );
+}
+
+/** Findings that can be marked in the text (document-level ones have no excerpt). */
+export function inlineFindings(findings: EditorialFinding[]): EditorialFinding[] {
+  return findings.filter((finding) => finding.excerpt.length > 0 && finding.span.end > finding.span.start);
+}
+
+export type FindingGroup = { policyId: string; severity: Severity; findings: EditorialFinding[] };
+
+export function groupByPolicy(findings: EditorialFinding[]): FindingGroup[] {
+  const groups = new Map<string, FindingGroup>();
+  for (const finding of findings) {
+    const group = groups.get(finding.policyId) ?? { policyId: finding.policyId, severity: finding.severity, findings: [] };
+    group.findings.push(finding);
+    if (SEVERITY_ORDER[finding.severity] < SEVERITY_ORDER[group.severity]) group.severity = finding.severity;
+    groups.set(finding.policyId, group);
+  }
+  return [...groups.values()].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || a.policyId.localeCompare(b.policyId));
+}
+
+/** Open findings that should make an editor pause before publishing (never a block). */
+export function publishWarnings(findings: EditorialFinding[], dismissed: ReadonlySet<string>): EditorialFinding[] {
+  return visibleFindings(findings, dismissed).filter((finding) => finding.severity !== "info" && finding.status === "violation");
+}
+
+/** The text of the segment a finding sits in, which becomes a few-shot example for the classifier. */
+export function findingSegmentText(result: EditorialCheckResult, body: string, finding: EditorialFinding): string | null {
+  const segment = result.segments.find((candidate) => candidate.id === finding.segmentId);
+  if (!segment || segment.kind === "document") return null;
+  return body.slice(segment.start, segment.end);
+}
+
+export function feedbackFor(
+  result: EditorialCheckResult,
+  body: string,
+  finding: EditorialFinding,
+  decision: FeedbackDecision,
+  itemId: string | null,
+  reason: string | null = null,
+): EditorialFeedbackInput {
+  return {
+    itemId: itemId ?? UNSAVED_ITEM_ID,
+    findingId: finding.id,
+    policyId: finding.policyId,
+    detectorId: finding.detectorId,
+    lane: finding.lane,
+    probability: finding.rawProbability ?? finding.probability ?? null,
+    decision,
+    reason: reason?.trim() ? reason.trim() : null,
+    text: finding.lane === "classifier" ? findingSegmentText(result, body, finding) : null,
+  };
+}
+
+/** Replace one span of the body; the span must still hold the text it was computed for. */
+export function applyReplacement(body: string, span: Span, expected: string, replacement: string): string | null {
+  if (body.slice(span.start, span.end) !== expected) return null;
+  return body.slice(0, span.start) + replacement + body.slice(span.end);
+}
+
+export function describeProbability(finding: EditorialFinding): string | null {
+  if (finding.probability === undefined) return null;
+  return `${Math.round(finding.probability * 100)}% sure`;
+}
+
+export function laneNotice(result: EditorialCheckResult): string | null {
+  const classifier = result.lanes.classifier;
+  if (classifier.status === "partial") return `Some sentences were not judged: ${classifier.reason ?? "the check ran out of time"}.`;
+  if (classifier.status === "failed") return `The judgment checks failed: ${classifier.reason ?? "unknown error"}. Rule checks still ran.`;
+  if (classifier.status === "unavailable" && (classifier.detectors ?? 0) === 0 && classifier.reason) return `Judgment checks are not configured: ${classifier.reason}.`;
+  return null;
+}

package/lib/editorial-preview.ts

@@ -0,0 +1,228 @@
+/**
+ * Places Humanus findings on the rendered Markus preview.
+ *
+ * Humanus reports spans in the markup; the preview renders an IR tree with no
+ * character offsets. Both sides agree on the words a reader sees, so findings
+ * are placed by text: each Humanus paragraph is matched, in document order, to
+ * the rendered prose block with the same words, and each finding's plain
+ * excerpt is located inside that block. Whitespace is ignored while matching,
+ * because rendering and Humanus collapse it differently (citations, breaks).
+ *
+ * "Rendered text" is defined by `inlineLeaves`, which the preview renderer also
+ * uses, so offsets computed here are offsets the renderer can split on.
+ */
+import type { EditorialCheckResult, EditorialFinding, Severity, Span } from "./editorial-checks";
+import type { MarkusBlock, MarkusDocument, MarkusInline, MarkusNode } from "./markus-ir";
+
+export const CITATION_TOKEN = /PAPYRUSMARKUP\d{5}END/g;
+
+export type InlineLeaf =
+  | { kind: "text"; node: MarkusInline & { type: "text" }; start: number; pieces: { raw: string; start: number; isToken: boolean }[] }
+  | { kind: "code"; node: MarkusInline & { type: "code_span" }; start: number; text: string }
+  | { kind: "break"; start: number; text: string }
+  | { kind: "opaque"; start: number };
+
+/** The reader-visible text of a run of inlines; citation tokens and images take no width. */
+export function inlineLeaves(inlines: MarkusInline[], offset = 0): { leaves: InlineLeaf[]; text: string } {
+  const leaves: InlineLeaf[] = [];
+  let text = "";
+  const walk = (nodes: MarkusInline[]) => {
+    for (const node of nodes) {
+      const start = offset + text.length;
+      switch (node.type) {
+        case "text": {
+          const pieces: { raw: string; start: number; isToken: boolean }[] = [];
+          let cursor = 0;
+          let plainLength = 0;
+          for (const match of node.text.matchAll(CITATION_TOKEN)) {
+            const index = match.index ?? 0;
+            if (index > cursor) {
+              pieces.push({ raw: node.text.slice(cursor, index), start: start + plainLength, isToken: false });
+              plainLength += index - cursor;
+            }
+            pieces.push({ raw: match[0], start: start + plainLength, isToken: true });
+            cursor = index + match[0].length;
+          }
+          if (cursor < node.text.length) {
+            pieces.push({ raw: node.text.slice(cursor), start: start + plainLength, isToken: false });
+            plainLength += node.text.length - cursor;
+          }
+          leaves.push({ kind: "text", node, start, pieces });
+          text += pieces.filter((piece) => !piece.isToken).map((piece) => piece.raw).join("");
+          break;
+        }
+        case "code_span":
+          leaves.push({ kind: "code", node, start, text: node.code });
+          text += node.code;
+          break;
+        case "soft_break":
+        case "hard_break":
+          leaves.push({ kind: "break", start, text: " " });
+          text += " ";
+          break;
+        case "emphasis":
+        case "strong":
+        case "strikethrough":
+        case "link":
+          walk(node.children);
+          break;
+        default:
+          leaves.push({ kind: "opaque", start });
+      }
+    }
+  };
+  walk(inlines);
+  return { leaves, text };
+}
+
+/** Prose blocks (paragraphs and headings, including those inside lists, quotes and directives) in reading order. */
+export function proseBlocks(document: MarkusDocument): (MarkusBlock & { inline: MarkusInline[] })[] {
+  const blocks: (MarkusBlock & { inline: MarkusInline[] })[] = [];
+  const visit = (nodes: MarkusNode[]) => {
+    for (const node of nodes) {
+      if (node.type === "directive") visit(node.children);
+      else if (node.type === "paragraph" || node.type === "heading") blocks.push(node);
+      else if (node.type === "list") for (const item of node.items) visit(item.children);
+      else if (node.type === "blockquote") visit(node.children);
+    }
+  };
+  visit(document.children);
+  return blocks;
+}
+
+export type PreviewMark = Span & { findingIds: string[]; severity: Severity; status: EditorialFinding["status"] };
+export type PreviewSentence = Span & { segmentId: string; source: Span };
+
+/** What the preview needs for one rendered block, in that block's rendered-text offsets. */
+export type BlockAnnotation = { marks: PreviewMark[]; sentences: PreviewSentence[] };
+
+export type PreviewPlan = WeakMap<object, BlockAnnotation>;
+
+const SEVERITY_RANK: Record<Severity, number> = { error: 0, warn: 1, info: 2 };
+
+/** Text without whitespace, with a map from each kept character back to its index in the original. */
+function compact(text: string): { value: string; index: number[] } {
+  let value = "";
+  const index: number[] = [];
+  for (let i = 0; i < text.length; i += 1) {
+    if (!/\s/.test(text[i])) {
+      value += text[i];
+      index.push(i);
+    }
+  }
+  return { value, index };
+}
+
+/** Locate `needle` in `haystack` ignoring whitespace; the occurrence nearest `near` (a 0..1 position) wins. */
+export function locate(haystack: string, needle: string, near = 0): Span | null {
+  const hay = compact(haystack);
+  const want = compact(needle).value;
+  if (!want) return null;
+  let best: number | null = null;
+  for (let at = hay.value.indexOf(want); at !== -1; at = hay.value.indexOf(want, at + 1)) {
+    if (best === null || Math.abs(at / Math.max(hay.value.length, 1) - near) < Math.abs(best / Math.max(hay.value.length, 1) - near)) best = at;
+  }
+  if (best === null) return null;
+  return { start: hay.index[best], end: hay.index[best + want.length - 1] + 1 };
+}
+
+/** The identity of a block's words: no whitespace, no stray emphasis or code markers. */
+function blockKey(text: string): string {
+  return compact(text).value.replace(/[*_`~]/g, "");
+}
+
+/** Match every Humanus paragraph to a rendered block and place its findings and sentences there. */
+export function planPreview(
+  document: MarkusDocument,
+  result: EditorialCheckResult,
+  findings: EditorialFinding[],
+): PreviewPlan {
+  const plan: PreviewPlan = new WeakMap();
+  const blocks = proseBlocks(document).map((block) => ({ block, text: inlineLeaves(block.inline).text }));
+  const paragraphs = result.segments.filter((segment) => segment.kind === "paragraph" && segment.text);
+  let cursor = 0;
+  for (const paragraph of paragraphs) {
+    const wanted = blockKey(paragraph.text ?? "");
+    let matched = -1;
+    for (let candidate = cursor; candidate < blocks.length; candidate += 1) {
+      if (blockKey(blocks[candidate].text) === wanted) {
+        matched = candidate;
+        break;
+      }
+    }
+    if (matched === -1) continue;
+    cursor = matched + 1;
+    const { block, text } = blocks[matched];
+    const sentences: PreviewSentence[] = [];
+    for (const sentence of result.segments.filter((s) => s.kind === "sentence" && s.parentId === paragraph.id)) {
+      const near = (sentence.start - paragraph.start) / Math.max(paragraph.end - paragraph.start, 1);
+      const span = locate(text, sentence.text ?? "", near);
+      if (span) sentences.push({ ...span, segmentId: sentence.id, source: { start: sentence.start, end: sentence.end } });
+    }
+    const ranges: (Span & { finding: EditorialFinding })[] = [];
+    for (const finding of findings) {
+      const inParagraph =
+        finding.segmentId === paragraph.id ||
+        result.segments.some((s) => s.id === finding.segmentId && s.parentId === paragraph.id);
+      if (!inParagraph || !finding.excerptText) continue;
+      const near = (finding.span.start - paragraph.start) / Math.max(paragraph.end - paragraph.start, 1);
+      const span = locate(text, finding.excerptText, near);
+      if (span) ranges.push({ ...span, finding });
+    }
+    plan.set(block, { marks: flatten(ranges), sentences });
+  }
+  return plan;
+}
+
+/** Overlapping finding ranges become non-overlapping marks, each listing every finding it belongs to. */
+function flatten(ranges: (Span & { finding: EditorialFinding })[]): PreviewMark[] {
+  const cuts = [...new Set(ranges.flatMap((range) => [range.start, range.end]))].sort((a, b) => a - b);
+  const marks: PreviewMark[] = [];
+  for (let i = 0; i < cuts.length - 1; i += 1) {
+    const start = cuts[i];
+    const end = cuts[i + 1];
+    const covering = ranges.filter((range) => range.start <= start && end <= range.end).map((range) => range.finding);
+    if (covering.length === 0) continue;
+    const strongest = [...covering].sort((a, b) => SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity])[0];
+    const previous = marks[marks.length - 1];
+    const ids = covering.map((finding) => finding.id).sort();
+    if (previous && previous.end === start && previous.findingIds.join() === ids.join()) {
+      previous.end = end;
+      continue;
+    }
+    marks.push({
+      start,
+      end,
+      findingIds: ids,
+      severity: strongest.severity,
+      status: covering.every((finding) => finding.status === "review") ? "review" : "violation",
+    });
+  }
+  return marks;
+}
+
+/** A selection on the preview, as the source span of the whole sentences it touches. */
+export function selectionToSource(annotation: BlockAnnotation | undefined, selection: Span): Span | null {
+  if (!annotation) return null;
+  const touched = annotation.sentences.filter((sentence) => sentence.start < selection.end && selection.start < sentence.end);
+  if (touched.length === 0) return null;
+  return {
+    start: Math.min(...touched.map((sentence) => sentence.source.start)),
+    end: Math.max(...touched.map((sentence) => sentence.source.end)),
+  };
+}
+
+/** Split [start, end) of rendered text at mark boundaries; each piece says which mark (if any) covers it. */
+export function splitByMarks(start: number, end: number, marks: PreviewMark[]): { start: number; end: number; mark: PreviewMark | null }[] {
+  const pieces: { start: number; end: number; mark: PreviewMark | null }[] = [];
+  let cursor = start;
+  for (const mark of marks) {
+    if (mark.end <= cursor || mark.start >= end) continue;
+    if (mark.start > cursor) pieces.push({ start: cursor, end: mark.start, mark: null });
+    const pieceEnd = Math.min(mark.end, end);
+    pieces.push({ start: Math.max(mark.start, cursor), end: pieceEnd, mark });
+    cursor = pieceEnd;
+  }
+  if (cursor < end) pieces.push({ start: cursor, end, mark: null });
+  return pieces;
+}

package/lib/monitoring-client.ts

@@ -0,0 +1,29 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import type { MonitoringResult } from "./monitoring-overview";
+
+type GraphQLResult = { data?: { monitoringOverview?: unknown }; errors?: { message?: string; errorType?: string }[] };
+
+/**
+ * Reads the monitoring overview through the site's own authenticated API (user pool, editor or admin).
+ * The browser holds no table name, key or secret: the function behind the query does the read.
+ */
+export async function loadMonitoringOverview(scope: "publication" | "all"): Promise<MonitoringResult> {
+  const client = generateClient({ authMode: "userPool" });
+  let result: GraphQLResult;
+  try {
+    result = (await client.graphql({
+      query: `query MonitoringOverview($scope: String) { monitoringOverview(scope: $scope) }`,
+      variables: { scope },
+    })) as GraphQLResult;
+  } catch (error) {
+    // Amplify throws the response when AppSync returns errors.
+    result = (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
+  }
+  const refused = result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`));
+  if (refused) return { error: "forbidden" };
+  if (result.errors?.length || result.data?.monitoringOverview === undefined || result.data.monitoringOverview === null) return { state: "unavailable" };
+  const raw = result.data.monitoringOverview;
+  return (typeof raw === "string" ? JSON.parse(raw) : raw) as MonitoringResult;
+}

package/lib/monitoring-overview-fixture.ts

@@ -0,0 +1,51 @@
+import type { MonitoringOverview } from "./monitoring-overview";
+
+/** A realistic overview for tests and the `?demo=1` newsroom. Public Hacker News titles only. */
+export const FIXTURE_MONITORING_OVERVIEW: MonitoringOverview = {
+  state: "ready",
+  asOf: "2026-10-21T02:40:00Z",
+  scope: { mode: "publication", publicationId: "desk-a", site: "a.example.test", canViewAll: true },
+  feeds: [{ id: "hn", sourceUrl: "https://news.ycombinator.com/rss", intervalSeconds: 900, limit: 30, enabled: true,
+    lastStatus: "complete", lastFinishedAt: "2026-10-21T02:33:00Z", nextDueAt: "2026-10-21T02:50:00Z" }],
+  runs: [
+    { runId: "r3", startedAt: "2026-10-21T02:33:00.000000Z", status: "complete", new: 2, revised: 1, unchanged: 27, itemCount: 30, errorCount: 0, errors: [] },
+    { runId: "r1", startedAt: "2026-10-21T02:18:00.000000Z", status: "complete", new: 0, revised: 0, unchanged: 30, itemCount: 30, errorCount: 0, errors: [] },
+    { runId: "r0", startedAt: "2026-10-21T02:03:00.000000Z", status: "partial", new: 1, revised: 0, unchanged: 28, itemCount: 30, errorCount: 1, errors: ["ConnectionError: timeout"] },
+  ],
+  routerRuns: [{ runId: "q2", startedAt: "2026-10-21T02:37:00.000000Z", mode: "live", status: "stopped", stoppedBy: "request_ceiling_reached",
+    counts: { examined: 3, decided: 1, delivered: 1, deliveryFailed: 1, routed: 1 }, errorCount: 0 }],
+  router: { mode: "live", feedback: true, enabled: true, maxItemsPerRun: 5 },
+  usage: { day: "2026-10-21", decisionsToday: 2, decisionsTotal: 3, ceilings: { decisionsTotal: 300, decisionsPerDay: 100, items: 300 } },
+  hiddenNotRelevant: 1,
+  items: [
+    { sourceId: "104", revision: 1, title: "Fresh Show HN", url: "https://example.org/104", discussionUrl: "https://news.ycombinator.com/item?id=104",
+      observedAt: "2026-10-21T02:30:00.000000Z", routing: "collected", routingNote: null, decidedAt: null,
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: null, label: null, confidence: null, delivery: { state: null } }] },
+    { sourceId: "105", revision: 1, title: "Broken request", url: "https://example.org/105", discussionUrl: "https://news.ycombinator.com/item?id=105",
+      observedAt: "2026-10-21T01:30:00.000000Z", routing: "error", routingNote: "invalid request: bad title", decidedAt: null,
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: null, label: null, confidence: null, delivery: { state: null } }] },
+    { sourceId: "101", revision: 1, title: "Quantum paper on arXiv", url: "https://example.org/101", discussionUrl: "https://news.ycombinator.com/item?id=101",
+      observedAt: "2026-10-21T00:10:00.000000Z", routing: "routed", routingNote: null, decidedAt: "2026-10-21T01:00:00Z",
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: true, label: "include", confidence: 0.91,
+        delivery: { state: "delivered", referenceId: "ref-1", referenceLineageId: "lin-1", deliveredAt: "2026-10-21T01:00:05Z" } }] },
+    { sourceId: "103", revision: 1, title: "Phishing kit leaks", url: "https://example.org/103", discussionUrl: "https://news.ycombinator.com/item?id=103",
+      observedAt: "2026-10-20T23:00:00.000000Z", routing: "decided", routingNote: null, decidedAt: "2026-10-20T23:10:00Z",
+      relevance: [{ publicationId: "desk-a", site: "a.example.test", relevant: true, label: "include", confidence: 0.7,
+        delivery: { state: "failed", error: "ClientError: throttled", attempts: 2 } }] },
+  ],
+};
+
+export const FIXTURE_ALL_PIPELINE_OVERVIEW: MonitoringOverview = {
+  ...FIXTURE_MONITORING_OVERVIEW,
+  scope: { mode: "all", publicationId: "desk-a", site: "a.example.test", canViewAll: true },
+  hiddenNotRelevant: 0,
+  items: FIXTURE_MONITORING_OVERVIEW.items.map((item) => item.sourceId !== "101" ? item : {
+    ...item,
+    relevance: [
+      ...item.relevance,
+      { publicationId: "desk-b", site: "b.example.test", relevant: false, label: "exclude", confidence: 0.8, delivery: { state: "not_applicable" } },
+      { publicationId: "desk-c", site: "desk-c", relevant: true, label: "include", confidence: null,
+        delivery: { state: "delivered", referenceId: "ref-2", referenceLineageId: "lin-2" } },
+    ],
+  }),
+};