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

package/components/newsroom-articles-view.tsx

@@ -0,0 +1,129 @@
+"use client";
+
+import { PlusIcon } from "lucide-react";
+import Link from "next/link";
+import { useEffect, useMemo, useState } from "react";
+import { Badge } from "./ui/badge";
+import { buttonVariants } from "./ui/button";
+import { Spinner } from "./ui/spinner";
+import { Tabs, TabsList, TabsTrigger } from "./ui/tabs";
+import { SITE_BRAND } from "../lib/site-brand";
+import { getNewsroomNavHref } from "../lib/newsroom-nav";
+import { newsroomHref } from "../lib/newsroom-base-path";
+import {
+  resolveArticlesBackend,
+  rowStatusLabel,
+  type NewsroomArticleRow,
+} from "../lib/newsroom-articles";
+import { cn } from "../lib/utils";
+import { useOptionalNewsDeskClient } from "./news-desk-client-provider";
+import { NewsDeskAccessGate } from "./newsroom-access-gate";
+import { NewsroomOpsShell, NewsroomOpsStatusBanner } from "./newsroom-ops-shell";
+
+type ArticleFilter = "all" | "drafts" | "published";
+
+export function articlesAccessBlocked(phase: string | undefined): boolean {
+  return phase === undefined || phase === "checkingAccess" || phase === "signedOut" || phase === "forbidden" || phase === "error";
+}
+
+export function NewsroomArticlesView({ demo }: { demo: boolean }) {
+  const session = useOptionalNewsDeskClient();
+  const blocked = !demo && articlesAccessBlocked(session?.shell.phase);
+  const [rows, setRows] = useState<NewsroomArticleRow[] | null>(null);
+  const [loadError, setLoadError] = useState<string | null>(null);
+  const [filter, setFilter] = useState<ArticleFilter>("all");
+
+  useEffect(() => {
+    if (blocked) return;
+    let cancelled = false;
+    resolveArticlesBackend(demo)
+      .listRows()
+      .then((loaded) => {
+        if (!cancelled) setRows(loaded);
+      })
+      .catch((error: unknown) => {
+        if (!cancelled) setLoadError(error instanceof Error ? error.message : "Could not load articles.");
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [blocked, demo]);
+
+  const visibleRows = useMemo(() => {
+    if (!rows) return [];
+    if (filter === "drafts") return rows.filter((row) => row.status === "draft");
+    if (filter === "published") return rows.filter((row) => row.status === "published");
+    return rows;
+  }, [filter, rows]);
+
+  if (blocked) return <NewsDeskAccessGate shell={session?.shell ?? null} />;
+
+  return (
+    <NewsroomOpsShell
+      activeTab="articles"
+      appTitle={SITE_BRAND.appTitle}
+      backHref="/"
+      backLabel={SITE_BRAND.backToHomeLabel}
+      demo={demo}
+      headerActions={(
+        <>
+          {demo ? <Badge variant="outline">Demo</Badge> : null}
+          <Link
+            className={cn(buttonVariants({ size: "sm" }))}
+            data-newsroom-article-new
+            href={getNewsroomNavHref(newsroomHref("articles", "new"), demo)}
+          >
+            <PlusIcon aria-hidden="true" />
+            New article
+          </Link>
+        </>
+      )}
+      pageTitle="Articles"
+    >
+      <div className="space-y-4" data-newsroom-articles>
+        <Tabs defaultValue="all" onValueChange={(value) => setFilter(value as ArticleFilter)} value={filter}>
+          <TabsList>
+            <TabsTrigger className="min-w-[5.5rem]" value="all">All</TabsTrigger>
+            <TabsTrigger className="min-w-[5.5rem]" value="drafts">Drafts</TabsTrigger>
+            <TabsTrigger className="min-w-[5.5rem]" value="published">Published</TabsTrigger>
+          </TabsList>
+        </Tabs>
+        {loadError ? <NewsroomOpsStatusBanner tone="error">{loadError}</NewsroomOpsStatusBanner> : null}
+        {rows === null && !loadError ? (
+          <div className="flex items-center gap-2 text-sm text-muted-foreground">
+            <Spinner /> Loading articles…
+          </div>
+        ) : null}
+        {rows !== null && visibleRows.length === 0 ? (
+          <p className="text-sm text-muted-foreground">Nothing here yet.</p>
+        ) : null}
+        <ul className="divide-y divide-border rounded-xl border border-border bg-card" data-newsroom-articles-list>
+          {visibleRows.map((row) => (
+            <li key={row.id}>
+              <Link
+                className="flex flex-col gap-1 px-4 py-3 hover:bg-muted/40 sm:flex-row sm:items-center sm:justify-between sm:gap-4"
+                data-newsroom-article-row={row.slug}
+                href={getNewsroomNavHref(newsroomHref("articles", row.id), demo)}
+              >
+                <span className="min-w-0">
+                  <span className="block truncate text-sm font-medium">{row.title}</span>
+                  <span className="block truncate text-xs text-muted-foreground">
+                    {row.slug}
+                    {row.section ? ` · ${row.section}` : ""}
+                    {row.type !== "article" ? ` · ${row.type}` : ""}
+                  </span>
+                </span>
+                <Badge
+                  data-newsroom-article-status
+                  variant={row.status === "draft" ? "muted" : row.pending ? "outline" : "secondary"}
+                >
+                  {rowStatusLabel(row)}
+                </Badge>
+              </Link>
+            </li>
+          ))}
+        </ul>
+      </div>
+    </NewsroomOpsShell>
+  );
+}

package/components/newsroom-ops-overview.tsx

@@ -3,8 +3,13 @@
 import {
   BookOpenIcon,
   ClipboardListIcon,
+  FileTextIcon,
   LayersIcon,
+  LightbulbIcon,
   MessageSquareIcon,
+  NetworkIcon,
+  SearchIcon,
+  SettingsIcon,
 } from "lucide-react";
 import Link from "next/link";
 import { usePathname } from "next/navigation";
@@ -12,7 +17,7 @@ import { useMemo } from "react";
 import { Badge } from "./ui/badge";
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "./ui/card";
 import type { AssignmentRecord, MessageRecord, NewsroomSectionRecord, ReferenceRecord } from "../lib/category-repository";
-import { getNewsroomNavHref } from "../lib/newsroom-nav";
+import { getNewsroomNavHref, NEWSROOM_OPS_NAV, type NewsroomNavTabId } from "../lib/newsroom-nav";
 import {
   countReferencesByStatus,
   filterReferencesByStatus,
@@ -37,15 +42,28 @@ type NewsroomOpsOverviewProps = {
   references: ReferenceRecord[];
 };
 
-type DestinationKey = "references" | "assignments" | "messages" | "topics";
+type DestinationKey = Exclude<NewsroomNavTabId, "overview" | "desks">;
 
-const DESTINATION_META: Record<DestinationKey, { label: string; detail: string; href: string; icon: typeof BookOpenIcon }> = {
-  references: { label: "References", detail: "Source intake", href: "/newsroom/references", icon: BookOpenIcon },
-  assignments: { label: "Assignments", detail: "Work queue", href: "/newsroom/assignments", icon: ClipboardListIcon },
-  messages: { label: "Messages", detail: "Team threads", href: "/newsroom/messages", icon: MessageSquareIcon },
-  topics: { label: "Topics", detail: "Taxonomy", href: "/newsroom/topics", icon: LayersIcon },
+const DESTINATION_ICONS: Record<DestinationKey, typeof BookOpenIcon> = {
+  articles: FileTextIcon,
+  assignments: ClipboardListIcon,
+  references: BookOpenIcon,
+  messages: MessageSquareIcon,
+  insights: LightbulbIcon,
+  topics: LayersIcon,
+  concepts: NetworkIcon,
+  administration: SettingsIcon,
+  search: SearchIcon,
 };
 
+const DESTINATIONS = NEWSROOM_OPS_NAV.filter((item) => item.id !== "overview").map((item) => ({
+  key: item.id as DestinationKey,
+  label: item.label,
+  detail: item.detail,
+  href: item.href,
+  icon: DESTINATION_ICONS[item.id as DestinationKey],
+}));
+
 function openAssignmentCount(assignments: AssignmentRecord[]): number {
   return assignments.filter((assignment) => {
     const status = assignment.status?.trim().toLowerCase() ?? "";
@@ -85,11 +103,10 @@ export function NewsroomOpsOverview({
     [newsroomSections],
   );
 
-  const destinationCounts: Record<DestinationKey, number | null> = {
+  const destinationCounts: Partial<Record<DestinationKey, number | null>> = {
     references: referenceCounts.pending ?? 0,
     assignments: openAssignmentCount(assignments),
     messages: recentMessageCount(messages),
-    topics: null,
   };
 
   return (
@@ -102,8 +119,8 @@ export function NewsroomOpsOverview({
         <section aria-label="Destinations" className="space-y-3">
           <h2 className="text-sm font-medium text-muted-foreground">Go to</h2>
           <div className="grid grid-cols-2 gap-3 sm:grid-cols-4">
-            {(Object.keys(DESTINATION_META) as DestinationKey[]).map((key) => {
-              const meta = DESTINATION_META[key];
+            {DESTINATIONS.map((meta) => {
+              const key = meta.key;
               const Icon = meta.icon;
               const count = destinationCounts[key];
               const href = getNewsroomNavHref(meta.href, demo);

package/components/newsroom-ops-shell.tsx

@@ -3,6 +3,7 @@
 import {
   BookOpenIcon,
   ClipboardListIcon,
+  FileTextIcon,
   LayoutGridIcon,
   MenuIcon,
   SearchIcon,
@@ -55,6 +56,7 @@ type NewsroomOpsShellProps = {
 
 const MOBILE_TAB_ICONS: Record<string, typeof LayoutGridIcon> = {
   overview: LayoutGridIcon,
+  articles: FileTextIcon,
   assignments: ClipboardListIcon,
   references: BookOpenIcon,
   topics: TagsIcon,
@@ -198,7 +200,7 @@ export function NewsroomOpsShell({
           className="shrink-0 border-t border-border bg-card/95 pb-[max(env(safe-area-inset-bottom),0.35rem)] pt-1 md:hidden"
           data-newsroom-ops-bottom-nav
         >
-          <ul className="grid grid-cols-5 gap-1 px-2">
+          <ul className="grid grid-cols-6 gap-1 px-1">
             {mobilePrimary.map((item) => {
               const Icon = MOBILE_TAB_ICONS[item.id] ?? LayoutGridIcon;
               const active = resolvedActiveTab === item.id;

package/components/pictogram-figure.tsx

@@ -12,6 +12,9 @@ export type PictogramFigureProps = {
   credit: string;
   figureClassName: string;
   height: number;
+  /** Rhythm blog layout: solved frame size in CSS pixels; wins over `height`/`width` when set. */
+  frameHeight?: number;
+  frameWidth?: number;
   layout?: ArticleImageLayout;
   priority?: boolean;
   sizes: string;
@@ -34,6 +37,8 @@ export function PictogramFigure({
   caption,
   credit,
   figureClassName,
+  frameHeight,
+  frameWidth,
   height,
   priority = false,
   sizes,
@@ -41,6 +46,8 @@ export function PictogramFigure({
   themeVariants,
   width,
 }: PictogramFigureProps) {
+  const imageHeight = frameHeight ?? height;
+  const imageWidth = frameWidth ?? width;
   const resolvedTheme = useResolvedPapyrusTheme();
   const themedImageSrc = resolveThemedImageSrc(src, themeVariants, resolvedTheme);
 
@@ -53,8 +60,8 @@ export function PictogramFigure({
       <Image
         src={themedImageSrc}
         alt={alt}
-        width={width}
-        height={height}
+        width={imageWidth}
+        height={imageHeight}
         sizes={sizes}
         priority={priority}
         unoptimized={shouldBypassImageOptimization(themedImageSrc)}

package/components/presentation-header.tsx

@@ -0,0 +1,135 @@
+"use client";
+
+import Link from "next/link";
+import { getEditionSectionPath } from "../lib/edition-routes";
+import { SITE_BRAND } from "../lib/site-brand";
+
+export type PresentationHeaderSection = {
+  key: string;
+  label: string;
+};
+
+export type PresentationHeaderProps = {
+  editionDate?: string;
+  title?: string;
+  description?: string;
+  sections?: PresentationHeaderSection[];
+  editionBasePath?: string;
+};
+
+export function PresentationHeader({
+  editionDate,
+  title: contentTitle,
+  description,
+  sections,
+  editionBasePath,
+}: PresentationHeaderProps) {
+  const title = SITE_BRAND.mastheadSource === "brand" ? SITE_BRAND.mastheadTitle : contentTitle;
+  const subtitle = SITE_BRAND.mastheadSource === "brand" ? SITE_BRAND.mastheadSubtitle : description;
+  const eyebrow = SITE_BRAND.mastheadEyebrow ?? null;
+  const tagline = SITE_BRAND.mastheadTagline ?? null;
+  const taglineLines = SITE_BRAND.mastheadTaglineLines ?? null;
+  const displayDate = editionDate
+    ? SITE_BRAND.mastheadDateFormat === "formatted"
+      ? formatMastheadDate(editionDate)
+      : editionDate
+    : null;
+
+  const eyebrowParts = eyebrow ? splitEyebrow(eyebrow) : null;
+
+  return (
+    <>
+      <header className="presentation-header">
+        <div className="presentation-header__copy-stack">
+          {eyebrowParts ? (
+            <span className="presentation-header__eyebrow">
+              <span className="presentation-header__eyebrow-strong">{eyebrowParts.lead}</span>
+              {eyebrowParts.rest ? (
+                <span className="presentation-header__eyebrow-muted">{eyebrowParts.rest}</span>
+              ) : null}
+            </span>
+          ) : null}
+          <h1>
+            {SITE_BRAND.mastheadWordSplit && title
+              ? title.split(/\s+/).map((word) => (
+                  <span className="presentation-header__word" key={word}>
+                    <span className="presentation-header__word-text">{word}</span>
+                  </span>
+                ))
+              : title}
+          </h1>
+          <div className="presentation-header__meta">
+            {subtitle && !eyebrow ? <span className="presentation-header__subtitle">{subtitle}</span> : null}
+            {displayDate ? <p className="presentation-header__date">{displayDate}</p> : null}
+          </div>
+        </div>
+        {tagline ? (
+          <span className="presentation-header__tagline">
+            {taglineLines && taglineLines.length > 0
+              ? taglineLines.map((line, index) => (
+                  <span className="presentation-header__tagline-line" key={index}>
+                    <span className="presentation-header__tagline-emphasis">{line.emphasis}</span>
+                    <span className="presentation-header__tagline-tail">{line.tail}</span>
+                    {index < taglineLines.length - 1 ? " " : null}
+                  </span>
+                ))
+              : tagline}
+          </span>
+        ) : null}
+      </header>
+      {sections && sections.length > 0 ? (
+        <nav className="presentation-section-nav" aria-label="Edition sections">
+          {sections.map((section) => (
+            <Link
+              href={getSectionHref(section, { editionBasePath, editionDate })}
+              key={section.key}
+            >
+              {section.label}
+            </Link>
+          ))}
+        </nav>
+      ) : null}
+    </>
+  );
+}
+
+function getSectionHref(
+  section: PresentationHeaderSection,
+  options: { editionBasePath?: string; editionDate?: string },
+): string {
+  if (SITE_BRAND.sectionLinkStrategy === "anchor") {
+    const anchor = `#${getSectionAnchorId(section.key)}`;
+    return options.editionBasePath ? `${options.editionBasePath}${anchor}` : anchor;
+  }
+  if (options.editionBasePath) {
+    return `${options.editionBasePath}/section/${encodeURIComponent(section.key)}`;
+  }
+  if (options.editionDate) {
+    const datedPath = getEditionSectionPath(options.editionDate, section.key);
+    return datedPath.startsWith("//") ? `#${getSectionAnchorId(section.key)}` : datedPath;
+  }
+  return `#${getSectionAnchorId(section.key)}`;
+}
+
+export function getSectionAnchorId(sectionKey: string): string {
+  return `section-${sectionKey}`;
+}
+
+function splitEyebrow(text: string): { lead: string; rest: string } {
+  const trimmed = text.trim();
+  const firstSpace = trimmed.indexOf(" ");
+  if (firstSpace === -1) return { lead: trimmed, rest: "" };
+  return { lead: trimmed.slice(0, firstSpace), rest: trimmed.slice(firstSpace + 1) };
+}
+
+export function formatMastheadDate(value: string): string {
+  const normalized = value?.trim();
+  if (!normalized) return value;
+  const date = new Date(`${normalized}T00:00:00`);
+  if (Number.isNaN(date.getTime())) return value;
+  return new Intl.DateTimeFormat("en-US", {
+    month: "long",
+    day: "numeric",
+    year: "numeric",
+  }).format(date);
+}

package/components/presentation-rhythm-hrule.tsx

@@ -0,0 +1,17 @@
+type PresentationRhythmHRuleProps = {
+  /** Hide in wide 2-column secondary pairs (items 1+2 side-by-side). */
+  hideInSecondaryPair?: boolean;
+};
+
+export function PresentationRhythmHRule({ hideInSecondaryPair = false }: PresentationRhythmHRuleProps) {
+  return (
+    <div
+      aria-hidden="true"
+      className="presentation-rhythm-hrule"
+      data-hide-in-secondary-pair={hideInSecondaryPair ? "true" : undefined}
+      role="presentation"
+    >
+      <div className="presentation-rhythm-hrule__line" />
+    </div>
+  );
+}

package/components/settings-page.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { toPublicReaderPath } from "../lib/reader-base-path";
 import { signOut } from "aws-amplify/auth";
 import Link from "next/link";
 import { useCallback, useEffect, useRef, useState } from "react";
@@ -114,7 +115,7 @@ export function SettingsPage() {
   return (
     <main className="settings-page">
       <nav className="edition-progress edition-progress--newsroom settings-progress" aria-label="Settings navigation">
-        <Link className="edition-progress__button edition-progress__button--previous" href="/">
+        <Link className="edition-progress__button edition-progress__button--previous" href={toPublicReaderPath("/")}>
           <svg aria-hidden="true" className="edition-progress__icon" focusable="false" viewBox="0 0 10 10">
             <path d="M7.5 1 2.5 5 7.5 9Z" fill="currentColor" />
           </svg>

package/components/staging-banner.tsx

@@ -0,0 +1,11 @@
+export function StagingBanner() {
+  return (
+    <div
+      data-staging-banner
+      role="status"
+      className="sticky top-0 z-50 bg-amber-300 px-3 py-1 text-center text-xs font-semibold uppercase tracking-wide text-black"
+    >
+      STAGING: drafts shown as published
+    </div>
+  );
+}

package/components/topic-steering-workspace.tsx

@@ -81,7 +81,7 @@ import { cn } from "../lib/utils";
 import { useOptionalNewsDeskClient } from "./news-desk-client-provider";
 import { ReferenceSourcePreview } from "./reference-source-preview";
 import type { ReaderAuthSnapshot } from "./reader-auth-state";
-import { ReaderAuthControl } from "./reader-auth-control";
+import { NewsDeskAccessGate } from "./newsroom-access-gate";
 import { NewsroomOpsOverview } from "./newsroom-ops-overview";
 import { NewsroomReferencesView } from "./newsroom-references-view";
 import { NewsroomAssignmentsView } from "./newsroom-assignments-view";
@@ -169,7 +169,6 @@ import {
   uniqueNeighborGroupsForCategoryContext,
   type CategoryDrilldownContext,
 } from "../lib/newsroom-category-drilldown";
-import type { NewsDeskShellState } from "../lib/news-desk-session";
 import {
   resolveNewsroomCardTemplate,
   type NewsroomCardSpan,
@@ -15399,63 +15398,6 @@ function readTextClaim(value: unknown): string | null {
   return typeof value === "string" && value.trim() ? value.trim() : null;
 }
 
-function NewsDeskAccessGate({ shell, showSectionTabs = false }: { shell: NewsDeskShellState | null; showSectionTabs?: boolean }) {
-  const accessPhase = shell?.phase ?? "checkingAccess";
-
-  return (
-    <NewsroomOpsShell
-      activeTab="overview"
-      appTitle={SITE_BRAND.appTitle}
-      backHref="/"
-      backLabel={SITE_BRAND.backToHomeLabel}
-      headerActions={(
-        <Link className={cn(buttonVariants({ variant: "ghost", size: "sm" }))} href="/settings">Settings</Link>
-      )}
-      pageTitle="Newsroom"
-      showNavigation={showSectionTabs}
-    >
-      <section aria-live="polite" data-news-desk-access={accessPhase} data-news-desk-access-phase={accessPhase}>
-        <div className="space-y-3 rounded-xl border border-border bg-card p-6">
-          <p className="m-0 text-[0.7rem] font-semibold uppercase tracking-[0.08em] text-muted-foreground">Access</p>
-          <h2 className="m-0 font-sans text-xl font-semibold tracking-tight">{formatAccessTitle(shell)}</h2>
-          <p className="m-0 text-sm text-muted-foreground">{formatAccessDetail(shell)}</p>
-          {shell?.error ? <p className="text-sm text-destructive">{shell.error}</p> : null}
-          <p className="m-0 text-sm text-foreground">{formatAccessActionDetail(shell)}</p>
-          {shell?.phase === "signedOut" || shell?.phase === "error" ? (
-            <div className="news-desk-access-panel__auth">
-              <ReaderAuthControl postAuthPath="/newsroom" showIdentity />
-            </div>
-          ) : null}
-        </div>
-      </section>
-    </NewsroomOpsShell>
-  );
-}
-
-function formatAccessTitle(state: NewsDeskShellState | null): string {
-  if (!state || state.phase === "checkingAccess") return "Checking Desk Credentials";
-  if (state.phase === "loadingDesk") return "Loading Newsroom Records";
-  if (state.phase === "forbidden") return "Editor Role Required";
-  if (state.phase === "error") return "Newsroom Unavailable";
-  return "Editor Sign-In Required";
-}
-
-function formatAccessDetail(state: NewsDeskShellState | null): string {
-  if (!state || state.phase === "checkingAccess") return `${SITE_BRAND.appTitle} is checking the current browser session before loading steering state.`;
-  if (state.phase === "loadingDesk") return `${SITE_BRAND.appTitle} verified the browser session and is loading private Newsroom records.`;
-  if (state.phase === "forbidden") return "This account is signed in, but the Cognito session does not include the editor or admin group.";
-  if (state.phase === "error") return `${SITE_BRAND.appTitle} could not verify this editor session or load the private Newsroom data.`;
-  return "Sign in with an editor or admin account to inspect category, category tree, ontology, and graph steering.";
-}
-
-function formatAccessActionDetail(state: NewsDeskShellState | null): string {
-  if (!state || state.phase === "checkingAccess") return "This should only take a moment. If it hangs, reload the page.";
-  if (state.phase === "loadingDesk") return "Private records are loading from GraphQL. Large reference queues may take several seconds.";
-  if (state.phase === "forbidden") return "Ask an admin to add this account to the editor or admin group, then sign out and back in.";
-  if (state.phase === "error") return "Reload the page or check the local development console for the GraphQL error.";
-  return "Use the login button above to authenticate with an editor or admin account.";
-}
-
 function SectionHeader({ title, detail }: { title: string; detail: string }) {
   const id = title.toLowerCase().replace(/[^a-z0-9]+/g, "-");
   return (

package/components/use-blog-header-obstacles.ts

@@ -0,0 +1,81 @@
+"use client";
+
+import { useEffect, useState, type RefObject } from "react";
+import type { BlogHeaderObstacle } from "./blog-page-background";
+
+const HEADER_OBSTACLE_SELECTORS = [
+  ".presentation-header__eyebrow",
+  ".presentation-header__word",
+  ".presentation-header__meta",
+  ".presentation-header__subtitle",
+  ".presentation-header__date",
+  ".presentation-header__tagline",
+  ".presentation-section-nav a",
+];
+
+function measureObstacleRect(element: HTMLElement): DOMRect {
+  const range = document.createRange();
+  range.selectNodeContents(element);
+  const contentRect = range.getBoundingClientRect();
+  range.detach();
+  if (contentRect.width > 0 && contentRect.height > 0) return contentRect;
+  return element.getBoundingClientRect();
+}
+
+/**
+ * Measures the rendered header text (eyebrow, masthead words, meta, tagline,
+ * section links) as rectangles in the coordinates of `.blog-page-background`,
+ * so a brand's background artwork can keep clear of them. Block-level header
+ * elements span the full page width even when their text ends mid-line, so
+ * the text range is measured instead of the element box.
+ */
+export function useBlogHeaderObstacles(
+  pageRef: RefObject<HTMLElement | null>,
+  paintBuffer: number,
+): BlogHeaderObstacle[] {
+  const [obstacles, setObstacles] = useState<BlogHeaderObstacle[]>([]);
+
+  useEffect(() => {
+    const page = pageRef.current;
+    if (!page) return;
+
+    const update = () => {
+      const background = page.querySelector<HTMLElement>(".blog-page-background");
+      const backgroundRect = background?.getBoundingClientRect();
+      if (!backgroundRect) return;
+
+      const next: BlogHeaderObstacle[] = [];
+      for (const selector of HEADER_OBSTACLE_SELECTORS) {
+        for (const element of Array.from(page.querySelectorAll<HTMLElement>(selector))) {
+          const rect = measureObstacleRect(element);
+          const intersectionTop = Math.max(rect.top, backgroundRect.top);
+          const intersectionBottom = Math.min(rect.bottom, backgroundRect.bottom);
+          const intersectionLeft = Math.max(rect.left, backgroundRect.left);
+          const intersectionRight = Math.min(rect.right, backgroundRect.right);
+          const width = intersectionRight - intersectionLeft;
+          const height = intersectionBottom - intersectionTop;
+          if (width <= 0 || height <= 0) continue;
+          next.push({
+            x: intersectionLeft - backgroundRect.left,
+            y: intersectionTop - backgroundRect.top,
+            width,
+            height: height + paintBuffer * 2,
+          });
+        }
+      }
+      setObstacles(next);
+    };
+
+    update();
+    const observer = new ResizeObserver(update);
+    observer.observe(page);
+    window.addEventListener("resize", update);
+    void document.fonts?.ready.then(update);
+    return () => {
+      observer.disconnect();
+      window.removeEventListener("resize", update);
+    };
+  }, [pageRef, paintBuffer]);
+
+  return obstacles;
+}

package/components/use-brand-fonts-ready.ts

@@ -0,0 +1,28 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { listBrandFontFamilies } from "../lib/brand-fonts";
+import { watchBrandFontsLoaded } from "../lib/brand-fonts-watch";
+import { clearPretextMeasurementCache } from "../lib/pretext-layout";
+import { SITE_BRAND } from "../lib/site-brand";
+
+/**
+ * Returns a number that increments each time the brand's declared font
+ * families finish loading. Pretext's width cache is cleared first, so
+ * measurements taken with fallback metrics are re-run with the real glyph
+ * widths. Stays 0 for brands without a font slot, and on the server.
+ */
+export function useBrandFontsReadyVersion(): number {
+  const [version, setVersion] = useState(0);
+
+  useEffect(() => {
+    return watchBrandFontsLoaded({
+      fontFaceSet: typeof document === "undefined" ? undefined : document.fonts,
+      families: listBrandFontFamilies(SITE_BRAND.fonts),
+      clearMeasurementCaches: clearPretextMeasurementCache,
+      onFontsSettled: () => setVersion((current) => current + 1),
+    });
+  }, []);
+
+  return version;
+}