@anthusai/papyrus 0.0.0 → 1.0.0-next.10

package/lib/newsroom-category-drilldown.ts

@@ -0,0 +1,133 @@
+import type {
+  CategorySteeringCategory,
+  SemanticRelationRecord,
+} from "./category-repository";
+import type {
+  SemanticNeighborGroup,
+  SemanticObjectSummary,
+} from "./semantic-graph";
+
+export type CategoryDrilldownContext = {
+  aliases: string[];
+  categories: CategorySteeringCategory[];
+  includeDescendants: boolean;
+  primary: CategorySteeringCategory | null;
+};
+
+type CategoryGraph = {
+  neighbors(kind: string, lineageId: string): SemanticNeighborGroup[];
+  referencesForCategory(categoryLineageId: string): SemanticObjectSummary[];
+};
+
+export function categoryLineageId(category: CategorySteeringCategory): string {
+  return category.lineageId ?? category.id;
+}
+
+export function buildCategoryDrilldownContext(categories: CategorySteeringCategory[], selection?: string | null): CategoryDrilldownContext {
+  if (!selection) return { aliases: [], categories: [], includeDescendants: false, primary: null };
+  const directMatches = uniqueCategoryRecords(categories.filter((category) => matchesCategorySelection(category, selection)));
+  const primary = directMatches[0] ?? null;
+  const selectedCategoryKey = primary?.categoryKey ?? selection;
+  const matchingCategoryKeyRecords = uniqueCategoryRecords(categories.filter((category) => category.categoryKey === selectedCategoryKey));
+  const directRecords = uniqueCategoryRecords([...directMatches, ...matchingCategoryKeyRecords]);
+  const includeDescendants = directRecords.some((category) => !category.parentCategoryKey);
+  const childRecords = includeDescendants
+    ? categories.filter((category) => category.parentCategoryKey === selectedCategoryKey)
+    : [];
+  const records = uniqueCategoryRecords([...directRecords, ...childRecords]);
+  return {
+    aliases: categoryAliasValues(records),
+    categories: records,
+    includeDescendants,
+    primary: primary ?? records[0] ?? null,
+  };
+}
+
+export function buildTopicDrilldownContext(
+  root: { category: CategorySteeringCategory; subcategorys: CategorySteeringCategory[] },
+  selected: CategorySteeringCategory,
+  categoryByUid: Map<string, CategorySteeringCategory>,
+): CategoryDrilldownContext {
+  const selectedFlatCategory = categoryByUid.get(selected.categoryKey) ?? null;
+  const directRecords = uniqueCategoryRecords([selected, selectedFlatCategory].filter((category): category is CategorySteeringCategory => Boolean(category)));
+  const includeDescendants = selected.categoryKey === root.category.categoryKey;
+  const childRecords = includeDescendants ? root.subcategorys : [];
+  const records = uniqueCategoryRecords([...directRecords, ...childRecords]);
+  return {
+    aliases: categoryAliasValues(records),
+    categories: records,
+    includeDescendants,
+    primary: directRecords[0] ?? records[0] ?? null,
+  };
+}
+
+export function referencesForCategoryContext(graph: CategoryGraph, context: CategoryDrilldownContext): SemanticObjectSummary[] {
+  return uniqueSemanticSummaries(context.aliases.flatMap((alias) => graph.referencesForCategory(alias)));
+}
+
+export function semanticNodesForCategoryContext(graph: CategoryGraph, context: CategoryDrilldownContext): SemanticObjectSummary[] {
+  return uniqueSemanticSummaries(
+    context.aliases.flatMap((alias) => graph.neighbors("category", alias))
+      .flatMap((group) => group.objects)
+      .filter((object) => object.kind === "semanticNode"),
+  );
+}
+
+export function uniqueNeighborGroupsForCategoryContext(graph: CategoryGraph, context: CategoryDrilldownContext): SemanticNeighborGroup[] {
+  const groups = new Map<string, SemanticNeighborGroup>();
+  for (const alias of context.aliases) {
+    for (const group of graph.neighbors("category", alias)) {
+      const key = `${group.direction}#${group.predicate}`;
+      const current = groups.get(key);
+      if (!current) {
+        groups.set(key, { ...group, relations: [...group.relations], objects: [...group.objects] });
+      } else {
+        current.relations = uniqueRelations([...current.relations, ...group.relations]);
+        current.objects = uniqueSemanticSummaries([...current.objects, ...group.objects]);
+      }
+    }
+  }
+  return Array.from(groups.values());
+}
+
+export function topicHref(rootCategoryKey: string, selectedCategoryKey?: string | null): string {
+  const encodedRoot = encodeURIComponent(rootCategoryKey);
+  const encodedSelected = selectedCategoryKey && selectedCategoryKey !== rootCategoryKey ? `/${encodeURIComponent(selectedCategoryKey)}` : "";
+  return `/newsroom/topics/${encodedRoot}${encodedSelected}`;
+}
+
+export function categoryDrilldownHref(section: "references" | "concepts", categoryKey: string): string {
+  return `/newsroom/${section}/${encodeURIComponent(categoryKey)}`;
+}
+
+function matchesCategorySelection(category: CategorySteeringCategory, selection: string): boolean {
+  return category.id === selection || category.lineageId === selection || category.categoryKey === selection;
+}
+
+function uniqueCategoryRecords(categories: CategorySteeringCategory[]): CategorySteeringCategory[] {
+  const records = new Map<string, CategorySteeringCategory>();
+  for (const category of categories) {
+    records.set(category.id, category);
+  }
+  return Array.from(records.values());
+}
+
+function categoryAliasValues(categories: CategorySteeringCategory[]): string[] {
+  const aliases = new Set<string>();
+  for (const category of categories) {
+    aliases.add(category.id);
+    aliases.add(category.categoryKey);
+    if (category.lineageId) aliases.add(category.lineageId);
+  }
+  return Array.from(aliases).filter(Boolean);
+}
+
+function uniqueRelations(relations: SemanticRelationRecord[]): SemanticRelationRecord[] {
+  return Array.from(new Map(relations.map((relation) => [relation.id, relation])).values());
+}
+
+function uniqueSemanticSummaries(objects: SemanticObjectSummary[]): SemanticObjectSummary[] {
+  const map = new Map<string, SemanticObjectSummary>();
+  for (const object of objects) map.set(`${object.kind}#${object.lineageId}`, object);
+  return Array.from(map.values()).sort((left, right) => left.label.localeCompare(right.label));
+}

package/lib/newsroom-demo-articles.ts

@@ -0,0 +1,90 @@
+export type DemoArticleRecord = {
+  id: string;
+  type: string;
+  slug: string;
+  section: string | null;
+  title: string;
+  status: "draft" | "published";
+  frontMatterYaml: string;
+  bodyMarkus: string;
+  contentHash: string;
+  publishedContentHash: string | null;
+  versionNumber: number | null;
+  everPublished: boolean;
+  updatedAt: string;
+};
+
+export function demoContentHash(frontMatterYaml: string, bodyMarkus: string): string {
+  let hash = 5381;
+  const text = `${frontMatterYaml}\u0000${bodyMarkus}`;
+  for (let index = 0; index < text.length; index += 1) {
+    hash = ((hash << 5) + hash + text.charCodeAt(index)) >>> 0;
+  }
+  return `demo:${hash.toString(16)}`;
+}
+
+function demoRecord(
+  fields: Pick<DemoArticleRecord, "id" | "slug" | "section" | "title" | "bodyMarkus" | "updatedAt"> & {
+    type?: string;
+    status: "draft" | "published";
+    publishedBody?: string;
+    versionNumber: number | null;
+  },
+): DemoArticleRecord {
+  const frontMatterYaml = `title: ${fields.title}\n`;
+  const contentHash = demoContentHash(frontMatterYaml, fields.bodyMarkus);
+  const publishedContentHash = fields.status === "published"
+    ? demoContentHash(frontMatterYaml, fields.publishedBody ?? fields.bodyMarkus)
+    : null;
+  return {
+    id: fields.id,
+    type: fields.type ?? "article",
+    slug: fields.slug,
+    section: fields.section,
+    title: fields.title,
+    status: fields.status,
+    frontMatterYaml,
+    bodyMarkus: fields.bodyMarkus,
+    contentHash,
+    publishedContentHash,
+    versionNumber: fields.versionNumber,
+    everPublished: fields.status === "published",
+    updatedAt: fields.updatedAt,
+  };
+}
+
+export function createDemoArticleRecords(): DemoArticleRecord[] {
+  return [
+    demoRecord({
+      id: "demo-article-changed",
+      slug: "forty-billion-dollars",
+      section: "business",
+      title: "Forty Billion Dollars",
+      bodyMarkus: "The raise doubled again this quarter.\n\nAnalysts expect the pace to slow.\n",
+      publishedBody: "The raise doubled this quarter.\n",
+      status: "published",
+      versionNumber: 2,
+      updatedAt: "2026-10-05T16:00:00.000Z",
+    }),
+    demoRecord({
+      id: "demo-article-published",
+      slug: "harbor-cranes-return",
+      section: "local",
+      title: "Harbor Cranes Return",
+      bodyMarkus: "# Harbor Cranes Return\n\nThe cranes were lifted back into place on Monday.\n",
+      status: "published",
+      versionNumber: 1,
+      updatedAt: "2026-10-04T12:00:00.000Z",
+    }),
+    demoRecord({
+      id: "demo-article-draft",
+      slug: "council-budget-notes",
+      section: "politics",
+      title: "Council Budget Notes",
+      bodyMarkus: "Notes from the budget session.\n",
+      status: "draft",
+      versionNumber: null,
+      updatedAt: "2026-10-03T09:00:00.000Z",
+    }),
+  ];
+}

package/lib/newsroom-demo-dashboard.ts

@@ -0,0 +1,267 @@
+import type { CategorySteeringDashboard } from "./category-repository";
+import { getNewsroomDemoProfile, type NewsroomDemoProfile } from "./newsroom-demo-profile";
+import type { SiteBrandId } from "./site-brand";
+
+const PILOBOLUS_CATEGORY_LABELS: Record<string, { displayName: string; subtitle: string; description: string }> = {
+  "category.foundation-model-scaling": {
+    displayName: "Strangler-Fig Control Loops",
+    subtitle: "Host encirclement, canopy pressure, and takeover timing",
+    description: "Field notes on how strangler-fig encirclement reshapes access paths and control timing in Pilobolus research.",
+  },
+  "category.agent-memory": {
+    displayName: "Mycelial Signal Routing",
+    subtitle: "Network timing, propagation failure, and recovery paths",
+    description: "Accepted subcategory for signal routing, persistence, and coordination across fungal network observations.",
+  },
+  "category.benchmark-saturation": {
+    displayName: "Canopy Competition Metrics",
+    subtitle: "Light capture, host stress, and encirclement saturation signals",
+    description: "Metrics for when a host canopy loses effective control under sustained strangler pressure.",
+  },
+  "category.symbolic-connectionist-history": {
+    displayName: "Fungal Network Field Logs",
+    subtitle: "Seasonal intake logs and annotated field observations",
+    description: "Historical field logs and intake notes that anchor Pilobolus fungus-among-us coverage.",
+  },
+};
+
+export function applyPilobolusDemoDashboardContent(
+  dashboard: CategorySteeringDashboard,
+  profile: NewsroomDemoProfile = getNewsroomDemoProfile("pilobol-us"),
+): CategorySteeringDashboard {
+  const localized = structuredClone(dashboard);
+  localized.canonicalCorpusId = profile.corpusId;
+  localized.canonicalCategorySetId = profile.categorySetId;
+
+  for (const corpus of localized.corpora) {
+    if (corpus.role === "canonical") {
+      corpus.id = profile.corpusId;
+      corpus.name = profile.canonicalCorpusName;
+    }
+    if (corpus.role === "source") {
+      corpus.id = profile.sourceCorpusId;
+      corpus.name = profile.sourceCorpusName;
+    }
+  }
+
+  for (const run of localized.importRuns) {
+    run.classifierId = profile.classifierId;
+    if (run.corpusId.includes("demo-canonical")) run.corpusId = profile.corpusId;
+    if (run.corpusId.includes("demo-source")) run.corpusId = profile.sourceCorpusId;
+  }
+
+  for (const set of localized.categorySets) {
+    set.classifierId = profile.classifierId;
+    if (set.id === "category-set-demo-canonical") {
+      set.id = profile.categorySetId;
+      set.lineageId = profile.categorySetId;
+      set.corpusId = profile.corpusId;
+      set.displayName = profile.categorySetLabel;
+      set.description = "Accepted Pilobolus steering tree for fungus-among-us field coverage.";
+    }
+    if (set.id === "category-set-demo-source") {
+      set.id = profile.sourceCategorySetId;
+      set.lineageId = profile.sourceCategorySetId;
+      set.corpusId = profile.sourceCorpusId;
+      set.displayName = "Pilobolus Source Intake Tree";
+      set.description = "Source intake categories for Pilobolus field material.";
+    }
+  }
+
+  for (const tree of localized.categoryTrees) {
+    tree.classifierId = profile.classifierId;
+    tree.corpusId = profile.corpusId;
+    tree.displayName = `${profile.brandLabel} Steering Tree`;
+    tree.description = "Accepted topic tree for Pilobolus field-notes coverage.";
+  }
+
+  const relabelCategory = <T extends { categoryKey?: string | null; displayName?: string | null; subtitle?: string | null; description?: string | null }>(
+    row: T,
+  ): T => {
+    const labels = row.categoryKey ? PILOBOLUS_CATEGORY_LABELS[row.categoryKey] : undefined;
+    if (!labels) return row;
+    return {
+      ...row,
+      displayName: labels.displayName,
+      subtitle: labels.subtitle,
+      description: labels.description,
+    };
+  };
+
+  localized.categorys = localized.categorys.map(relabelCategory);
+  localized.categoryNodes = localized.categoryNodes.map(relabelCategory);
+
+  localized.categoryKeywords = localized.categoryKeywords.map((keyword) => {
+    if (keyword.categoryKey === "category.foundation-model-scaling") {
+      return { ...keyword, keyword: "strangler fig", normalizedKeyword: "strangler fig" };
+    }
+    if (keyword.categoryKey === "category.agent-memory") {
+      return { ...keyword, keyword: "mycelial routing", normalizedKeyword: "mycelial routing" };
+    }
+    return keyword;
+  });
+
+  localized.proposals = localized.proposals.map((proposal) => {
+    const relabeled = relabelCategory(proposal);
+    if (proposal.proposalKind === "rename-category") {
+      return {
+        ...relabeled,
+        title: "Rename strangler-fig control category",
+        summary: "Field intake consistently uses strangler-fig encirclement language instead of generic scaling terminology.",
+      };
+    }
+    if (proposal.proposalKind === "create-category") {
+      return {
+        ...relabeled,
+        title: "Create mycelial routing subcategory",
+        summary: "Discovery found a child topic under strangler-fig control loops for signal routing evidence.",
+        displayName: "Mycelial Signal Routing",
+        description: "Candidate subcategory covering routing, persistence, and propagation across fungal networks.",
+      };
+    }
+    if (proposal.proposalKind === "relationship-proposal") {
+      return {
+        ...relabeled,
+        title: "Link control loop category to canopy metrics entity",
+        summary: "Evidence suggests strangler-fig control loops relate to canopy competition metrics.",
+      };
+    }
+    return relabeled;
+  });
+
+  localized.references = localized.references.map((reference, index) => ({
+    ...reference,
+    corpusId: profile.sourceCorpusId,
+    title: index === 0
+      ? "Strangler Fig Host Encirclement Field Notes"
+      : "Mycelial Coordination Under Canopy Stress",
+    sourceUri: index === 0
+      ? "s3://pilobol-us-demo/corpora/pilobol-us-source/strangler-fig-field-notes-001.md"
+      : "s3://pilobol-us-demo/corpora/pilobol-us-source/mycelial-canopy-stress-002.md",
+    storagePath: index === 0
+      ? "corpora/pilobol-us-source/strangler-fig-field-notes-001.md"
+      : "corpora/pilobol-us-source/mycelial-canopy-stress-002.md",
+  }));
+
+  localized.referenceAttachments = localized.referenceAttachments.map((attachment, index) => ({
+    ...attachment,
+    sourceUri: index % 2 === 0
+      ? "s3://pilobol-us-demo/corpora/pilobol-us-source/strangler-fig-field-notes-001.md"
+      : "s3://pilobol-us-demo/corpora/pilobol-us-source/mycelial-canopy-stress-002.md",
+    storagePath: index % 2 === 0
+      ? "corpora/pilobol-us-source/strangler-fig-field-notes-001.md"
+      : "corpora/pilobol-us-source/mycelial-canopy-stress-002.md",
+    filename: index % 2 === 0 ? "strangler-fig-field-notes-001.md" : "mycelial-canopy-stress-002.md",
+  }));
+
+  localized.semanticNodes = localized.semanticNodes.map((node, index) => ({
+    ...node,
+    corpusId: index === 0 ? profile.corpusId : profile.sourceCorpusId,
+    displayName: index === 0 ? "Canopy Competition Metrics" : "Intake Rationale",
+  }));
+
+  localized.messages = localized.messages.map((message) => {
+    if (message.messageKind === "ingestion_rationale") {
+      return {
+        ...message,
+        body: "Imported as a useful holdout against generic platform demo intake.",
+        summary: "Pilobolus intake rationale",
+      };
+    }
+    if (message.messageKind === "reporting_context_packet") {
+      const metadata = message.metadata && typeof message.metadata === "object" && !Array.isArray(message.metadata)
+        ? message.metadata as Record<string, unknown>
+        : {};
+      const reporting = metadata.reporting && typeof metadata.reporting === "object" && !Array.isArray(metadata.reporting)
+        ? metadata.reporting as Record<string, unknown>
+        : {};
+      return {
+        ...message,
+        body: "Context packet for a Pilobolus field-notes candidate. Editors can select, merge, brief, hold, or kill this packet without creating reader copy.",
+        summary: "Reporting context packet: strangler-fig control-loop angle",
+        metadata: {
+          ...metadata,
+          reporting: {
+            ...reporting,
+            sectionKey: "field-notes",
+            recommendedAngle: "Focus on host encirclement timing and mycelial routing evidence.",
+            copywriterBrief: "Use accepted Pilobolus field-note evidence before drafting.",
+          },
+        },
+      };
+    }
+    return message;
+  });
+
+  localized.assignments = localized.assignments.map((assignment, index) => {
+    if (assignment.assignmentTypeKey === "reporting.edition-candidate") {
+      return {
+        ...assignment,
+        title: "Field-notes reporting candidate 1: Strangler-fig control-loop shift",
+        summary: "Create reporting context for a Pilobolus field-notes candidate; do not create a draft Item until editor selection.",
+        brief: "Report a section-ready candidate for Field Notes, option 1.",
+        primaryFocusCategoryKey: "category.foundation-model-scaling",
+        topicScopeCategoryKeys: ["category.foundation-model-scaling"],
+      };
+    }
+    if (index === 0) {
+      return {
+        ...assignment,
+        title: "Reference intake: strangler-fig field notes",
+        summary: "Review and curate Pilobolus source intake for strangler-fig encirclement field notes.",
+      };
+    }
+    return {
+      ...assignment,
+      title: "Reference intake: mycelial canopy stress log",
+      summary: "Review Pilobolus source intake for mycelial coordination under canopy stress.",
+    };
+  });
+
+  localized.doctrineRecords = localized.doctrineRecords.map((record) => {
+    const editorial = record.editorial && typeof record.editorial === "object" && !Array.isArray(record.editorial)
+      ? record.editorial as Record<string, unknown>
+      : null;
+    if (editorial?.kind === "mission") {
+      return {
+        ...record,
+        title: "Pilobolus Editorial Mission",
+        body: [
+          "Pilobolus publishes field notes that help readers see fungus-among-us coordination, strangler-fig control loops, and mycelial signal routing with inspectable evidence.",
+          "Coverage should stay source-disciplined, canopy-aware, and explicit about what remains uncertain in the field record.",
+        ],
+      };
+    }
+    if (editorial?.kind === "policy") {
+      return {
+        ...record,
+        title: "Pilobolus Editorial Policy",
+        body: [
+          "Publication doctrine is the global inclusion standard for Pilobol.us; desk doctrine sets local intake priorities for field notes and source intake.",
+          "Field-notes reporting should prioritize accepted Pilobolus references and annotated intake artifacts—not the Papyrus platform knowledge base.",
+          "High-risk claims about host takeover or network control require explicit uncertainty handling and accepted source linkage.",
+        ],
+      };
+    }
+    return record;
+  });
+
+  localized.artifacts = localized.artifacts.map((artifact) => ({
+    ...artifact,
+    corpusId: profile.corpusId,
+    artifactId: "s3://pilobol-us-demo/accepted-category-set.json",
+    displayName: "Pilobolus Accepted Steering Tree JSON",
+  }));
+
+  localized.lexicalSteeringRules = localized.lexicalSteeringRules.map((rule) => ({
+    ...rule,
+    source: "pilobol-us-lexical-steering.yml",
+    createdBy: "pilobol-us-config",
+  }));
+
+  return localized;
+}
+
+export function shouldUsePilobolusDemoDashboard(brandId: SiteBrandId): boolean {
+  return brandId === "pilobol-us";
+}

package/lib/newsroom-demo-profile.ts

@@ -0,0 +1,46 @@
+import { resolveSiteBrandId, type SiteBrandId } from "./site-brand";
+
+export type NewsroomDemoProfile = {
+  brandLabel: string;
+  canonicalCorpusName: string;
+  sourceCorpusName: string;
+  categorySetLabel: string;
+  classifierId: string;
+  corpusId: string;
+  sourceCorpusId: string;
+  categorySetId: string;
+  sourceCategorySetId: string;
+};
+
+const PAPYRUS_DEMO_PROFILE: NewsroomDemoProfile = {
+  brandLabel: "Papyrus",
+  canonicalCorpusName: "Canonical Demo Corpus",
+  sourceCorpusName: "Source Demo Corpus",
+  categorySetLabel: "Demo Canonical Category Set",
+  classifierId: "demo-canonical-classifier",
+  corpusId: "knowledge-corpus-demo-canonical",
+  sourceCorpusId: "knowledge-corpus-demo-source",
+  categorySetId: "category-set-demo-canonical",
+  sourceCategorySetId: "category-set-demo-source",
+};
+
+const PILOBOLUS_DEMO_PROFILE: NewsroomDemoProfile = {
+  brandLabel: "Pilobolus",
+  canonicalCorpusName: "Pilobolus Field Notes Corpus",
+  sourceCorpusName: "Pilobolus Source Intake",
+  categorySetLabel: "Pilobolus Steering Tree",
+  classifierId: "pilobolus-demo-classifier",
+  corpusId: "knowledge-corpus-pilobolus-demo-canonical",
+  sourceCorpusId: "knowledge-corpus-pilobolus-demo-source",
+  categorySetId: "category-set-pilobolus-demo-canonical",
+  sourceCategorySetId: "category-set-pilobolus-demo-source",
+};
+
+export function getNewsroomDemoProfile(brandId: SiteBrandId = resolveSiteBrandId()): NewsroomDemoProfile {
+  if (brandId === "pilobol-us") return PILOBOLUS_DEMO_PROFILE;
+  return PAPYRUS_DEMO_PROFILE;
+}
+
+export function isPilobolusDemoBrand(brandId: SiteBrandId = resolveSiteBrandId()): boolean {
+  return brandId === "pilobol-us";
+}

package/lib/newsroom-forum-routes.ts

@@ -0,0 +1,153 @@
+export const FORUM_THREAD_ROUTE_PREFIX = "/newsroom/forum/";
+export const INSIGHT_THREAD_ROUTE_PREFIX = "/newsroom/insights/";
+export const FORUM_MESSAGE_HASH_PREFIX = "message-";
+
+export function isForumThreadId(id: string | null | undefined): boolean {
+  const value = String(id ?? "").trim();
+  return value.startsWith("message-thread-");
+}
+
+export function isInsightThreadId(id: string | null | undefined): boolean {
+  const value = String(id ?? "").trim();
+  return Boolean(value) && !isForumThreadId(value);
+}
+
+export function getForumMessageAnchorId(messageId: string): string {
+  return `${FORUM_MESSAGE_HASH_PREFIX}${encodeURIComponent(messageId.trim())}`;
+}
+
+export function parseForumMessageAnchorFromHash(hash: string | null | undefined): string | null {
+  const raw = String(hash ?? "").replace(/^#/, "").trim();
+  if (!raw.startsWith(FORUM_MESSAGE_HASH_PREFIX)) return null;
+  const encoded = raw.slice(FORUM_MESSAGE_HASH_PREFIX.length);
+  if (!encoded) return null;
+  try {
+    return decodeURIComponent(encoded);
+  } catch {
+    return encoded;
+  }
+}
+
+export type ParsedNewsroomForumRoute = {
+  threadId: string | null;
+  messageId: string | null;
+  surface: "edition_forum" | "insight_forum" | null;
+};
+
+export function parseNewsroomForumRoute(pathname: string, hash?: string | null): ParsedNewsroomForumRoute {
+  const segments = pathname.split("/").filter(Boolean);
+  const newsroomIndex = segments.indexOf("newsroom");
+  if (newsroomIndex < 0) {
+    return { threadId: null, messageId: parseForumMessageAnchorFromHash(hash), surface: null };
+  }
+  const tail = segments.slice(newsroomIndex + 1);
+  if (tail[0] === "insights" && tail[1]) {
+    return {
+      threadId: decodeURIComponent(tail[1]),
+      messageId: parseForumMessageAnchorFromHash(hash),
+      surface: "insight_forum",
+    };
+  }
+  if (tail[0] === "forum" && tail[1]) {
+    return {
+      threadId: decodeURIComponent(tail[1]),
+      messageId: parseForumMessageAnchorFromHash(hash),
+      surface: "edition_forum",
+    };
+  }
+  if (tail[0] === "messages" && tail[1] === "forum" && tail[2]) {
+    return {
+      threadId: decodeURIComponent(tail[2]),
+      messageId: parseForumMessageAnchorFromHash(hash),
+      surface: "edition_forum",
+    };
+  }
+  if (tail[0] === "messages" && tail[1] && isForumThreadId(tail[1])) {
+    return {
+      threadId: decodeURIComponent(tail[1]),
+      messageId: parseForumMessageAnchorFromHash(hash),
+      surface: "edition_forum",
+    };
+  }
+  return { threadId: null, messageId: parseForumMessageAnchorFromHash(hash), surface: null };
+}
+
+export function buildForumThreadUrl(
+  threadId: string,
+  options?: { messageId?: string | null; demo?: boolean },
+): string {
+  const encodedThreadId = encodeURIComponent(threadId.trim());
+  const params = new URLSearchParams();
+  if (options?.demo) params.set("demo", "1");
+  const query = params.toString();
+  const hash = options?.messageId ? getForumMessageAnchorId(options.messageId) : "";
+  return `/newsroom/forum/${encodedThreadId}${query ? `?${query}` : ""}${hash ? `#${hash}` : ""}`;
+}
+
+export function buildInsightThreadUrl(
+  threadId: string,
+  options?: { messageId?: string | null; demo?: boolean },
+): string {
+  const encodedThreadId = encodeURIComponent(threadId.trim());
+  const params = new URLSearchParams();
+  if (options?.demo) params.set("demo", "1");
+  const query = params.toString();
+  const hash = options?.messageId ? getForumMessageAnchorId(options.messageId) : "";
+  return `${INSIGHT_THREAD_ROUTE_PREFIX}${encodedThreadId}${query ? `?${query}` : ""}${hash ? `#${hash}` : ""}`;
+}
+
+export function buildThreadUrlForSurface(
+  surface: ParsedNewsroomForumRoute["surface"],
+  threadId: string,
+  options?: { messageId?: string | null; demo?: boolean },
+): string {
+  if (surface === "insight_forum") return buildInsightThreadUrl(threadId, options);
+  return buildForumThreadUrl(threadId, options);
+}
+
+export function readCurrentForumRoute(): ParsedNewsroomForumRoute {
+  if (typeof window === "undefined") {
+    return { threadId: null, messageId: null, surface: null };
+  }
+  return parseNewsroomForumRoute(window.location.pathname, window.location.hash);
+}
+
+export function pushForumThreadUrl(
+  threadId: string | null,
+  options?: { messageId?: string | null; demo?: boolean; replace?: boolean; surface?: ParsedNewsroomForumRoute["surface"] },
+) {
+  if (typeof window === "undefined") return;
+  const surface = options?.surface ?? readCurrentForumRoute().surface;
+  const url = threadId
+    ? buildThreadUrlForSurface(surface, threadId, options)
+    : (surface === "insight_forum" ? buildNewsroomInsightsIndexUrl(options?.demo) : buildNewsroomForumIndexUrl(options?.demo));
+  const current = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+  if (current === url) return;
+  if (options?.replace) {
+    window.history.replaceState(null, "", url);
+  } else {
+    window.history.pushState(null, "", url);
+  }
+}
+
+export function pushInsightThreadUrl(
+  threadId: string | null,
+  options?: { messageId?: string | null; demo?: boolean; replace?: boolean },
+) {
+  pushForumThreadUrl(threadId, { ...options, surface: "insight_forum" });
+}
+
+export function buildNewsroomForumIndexUrl(demo?: boolean): string {
+  const params = new URLSearchParams();
+  if (demo) params.set("demo", "1");
+  const query = params.toString();
+  return query ? `/newsroom?${query}` : "/newsroom";
+}
+
+export function buildNewsroomInsightsIndexUrl(demo?: boolean, domain?: string): string {
+  const params = new URLSearchParams();
+  if (demo) params.set("demo", "1");
+  if (domain?.trim()) params.set("domain", domain.trim());
+  const query = params.toString();
+  return query ? `/newsroom/insights?${query}` : "/newsroom/insights";
+}