@anthusai/papyrus 0.0.0 → 1.0.0-next.1

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";
+}

package/lib/newsroom-index-filters.ts

@@ -0,0 +1,202 @@
+export type NewsroomIndexTab = "references" | "messages" | "assignments" | "insights";
+
+export type ReferenceIndexOrder = "published" | "imported";
+
+export type ReferencesIndexFilters = { status: string; processing: string; order: ReferenceIndexOrder };
+export type MessagesIndexFilters = { kind: string; domain: string };
+export type AssignmentsIndexFilters = { status: string; type: string; view: string };
+export type InsightsIndexFilters = { domain: string };
+
+export const DEFAULT_REFERENCES_INDEX_FILTERS: ReferencesIndexFilters = {
+  status: "exclude-pending",
+  processing: "",
+  order: "published",
+};
+
+export const DEFAULT_MESSAGES_INDEX_FILTERS: MessagesIndexFilters = {
+  kind: "",
+  domain: "",
+};
+
+export const DEFAULT_ASSIGNMENTS_INDEX_FILTERS: AssignmentsIndexFilters = {
+  status: "",
+  type: "",
+  view: "queue",
+};
+
+export const DEFAULT_INSIGHTS_INDEX_FILTERS: InsightsIndexFilters = {
+  domain: "",
+};
+
+export function referencesStatusFromUrl(value: string): string {
+  return value === "exclude-pending" ? "__exclude_pending" : value;
+}
+
+export function referencesStatusToUrl(value: string): string {
+  return value === "__exclude_pending" ? "exclude-pending" : value;
+}
+
+export function normalizeReferenceIndexOrder(value: string | null | undefined): ReferenceIndexOrder {
+  return value?.trim() === "imported" ? "imported" : "published";
+}
+
+export function effectiveReferencesIndexFilters(partial?: Partial<ReferencesIndexFilters>): ReferencesIndexFilters {
+  const order = normalizeReferenceIndexOrder(partial?.order);
+  const explicitStatus = partial?.status?.trim();
+  let status = explicitStatus || DEFAULT_REFERENCES_INDEX_FILTERS.status;
+  // Import-date sort is for intake triage; the default "reviewed only" filter hides
+  // pending references created by inbound email and other intake paths.
+  if (order === "imported" && !explicitStatus) {
+    status = "";
+  }
+  return {
+    status,
+    processing: partial?.processing?.trim() ?? DEFAULT_REFERENCES_INDEX_FILTERS.processing,
+    order,
+  };
+}
+
+export function effectiveMessagesIndexFilters(partial?: Partial<MessagesIndexFilters>): MessagesIndexFilters {
+  return {
+    kind: partial?.kind?.trim() ?? DEFAULT_MESSAGES_INDEX_FILTERS.kind,
+    domain: partial?.domain?.trim() ?? DEFAULT_MESSAGES_INDEX_FILTERS.domain,
+  };
+}
+
+export function effectiveAssignmentsIndexFilters(partial?: Partial<AssignmentsIndexFilters>): AssignmentsIndexFilters {
+  return {
+    status: partial?.status?.trim() ?? DEFAULT_ASSIGNMENTS_INDEX_FILTERS.status,
+    type: partial?.type?.trim() ?? DEFAULT_ASSIGNMENTS_INDEX_FILTERS.type,
+    view: partial?.view?.trim() || DEFAULT_ASSIGNMENTS_INDEX_FILTERS.view,
+  };
+}
+
+export function effectiveInsightsIndexFilters(partial?: Partial<InsightsIndexFilters>): InsightsIndexFilters {
+  return {
+    domain: partial?.domain?.trim() ?? DEFAULT_INSIGHTS_INDEX_FILTERS.domain,
+  };
+}
+
+export function readReferencesIndexFilters(searchParams: URLSearchParams): ReferencesIndexFilters {
+  const statusParam = searchParams.get("status")?.trim() ?? "";
+  const orderParam = searchParams.get("order")?.trim();
+  return effectiveReferencesIndexFilters({
+    status: statusParam ? referencesStatusFromUrl(statusParam) : undefined,
+    processing: searchParams.get("processing")?.trim() ?? undefined,
+    order: orderParam ? normalizeReferenceIndexOrder(orderParam) : undefined,
+  });
+}
+
+export function readMessagesIndexFilters(searchParams: URLSearchParams): MessagesIndexFilters {
+  return effectiveMessagesIndexFilters({
+    kind: searchParams.get("kind")?.trim() ?? undefined,
+    domain: searchParams.get("domain")?.trim() ?? undefined,
+  });
+}
+
+export function readAssignmentsIndexFilters(searchParams: URLSearchParams): AssignmentsIndexFilters {
+  return effectiveAssignmentsIndexFilters({
+    status: searchParams.get("status")?.trim() ?? undefined,
+    type: searchParams.get("type")?.trim() ?? undefined,
+    view: searchParams.get("view")?.trim() ?? undefined,
+  });
+}
+
+export function readInsightsIndexFilters(searchParams: URLSearchParams): InsightsIndexFilters {
+  return effectiveInsightsIndexFilters({
+    domain: searchParams.get("domain")?.trim() ?? undefined,
+  });
+}
+
+export function buildReferencesIndexQuery(filters: ReferencesIndexFilters): string {
+  const params = new URLSearchParams();
+  if (filters.status && filters.status !== DEFAULT_REFERENCES_INDEX_FILTERS.status) {
+    params.set("status", referencesStatusToUrl(filters.status));
+  }
+  if (filters.processing.trim()) params.set("processing", filters.processing.trim());
+  if (filters.order === "imported") params.set("order", "imported");
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+
+export function buildMessagesIndexQuery(filters: MessagesIndexFilters): string {
+  const params = new URLSearchParams();
+  if (filters.kind.trim()) params.set("kind", filters.kind.trim());
+  if (filters.domain.trim()) params.set("domain", filters.domain.trim());
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+
+export function buildAssignmentsIndexQuery(filters: AssignmentsIndexFilters): string {
+  const params = new URLSearchParams();
+  if (filters.status.trim()) params.set("status", filters.status.trim());
+  if (filters.type.trim()) params.set("type", filters.type.trim());
+  if (filters.view.trim() === "budget") params.set("view", "budget");
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+
+export function buildInsightsIndexQuery(filters: InsightsIndexFilters): string {
+  const params = new URLSearchParams();
+  if (filters.domain.trim()) params.set("domain", filters.domain.trim());
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+
+export function buildNewsroomIndexWebPath(
+  tab: NewsroomIndexTab,
+  filters: ReferencesIndexFilters | MessagesIndexFilters | AssignmentsIndexFilters | InsightsIndexFilters,
+): string {
+  if (tab === "references") return `/newsroom/references${buildReferencesIndexQuery(filters as ReferencesIndexFilters)}`;
+  if (tab === "messages") return `/newsroom/messages${buildMessagesIndexQuery(filters as MessagesIndexFilters)}`;
+  if (tab === "insights") return `/newsroom/insights${buildInsightsIndexQuery(filters as InsightsIndexFilters)}`;
+  return `/newsroom/assignments${buildAssignmentsIndexQuery(filters as AssignmentsIndexFilters)}`;
+}
+
+export function syncBrowserNewsroomIndexUrl(
+  tab: NewsroomIndexTab,
+  filters: ReferencesIndexFilters | MessagesIndexFilters | AssignmentsIndexFilters | InsightsIndexFilters,
+  options?: { replace?: boolean },
+) {
+  if (typeof window === "undefined") return;
+  const nextPath = buildNewsroomIndexWebPath(tab, filters);
+  const current = `${window.location.pathname}${window.location.search}`;
+  if (current === nextPath) return;
+  if (options?.replace) window.history.replaceState(null, "", nextPath);
+  else window.history.pushState(null, "", nextPath);
+}
+
+/** Lineage id from `/newsroom/references/<id>` (not index-only URLs). */
+export function parseReferenceLineageIdFromNewsroomPathname(pathname: string | null | undefined): string | null {
+  if (!pathname?.startsWith("/newsroom/references/")) return null;
+  const segment = pathname.slice("/newsroom/references/".length).split("/")[0]?.trim() ?? "";
+  if (!segment) return null;
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+/** Assignment id from `/newsroom/assignments/<id>` (not index-only URLs). */
+export function parseAssignmentIdFromNewsroomPathname(pathname: string | null | undefined): string | null {
+  if (!pathname?.startsWith("/newsroom/assignments/")) return null;
+  const segment = pathname.slice("/newsroom/assignments/".length).split("/")[0]?.trim() ?? "";
+  if (!segment) return null;
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+
+export function parseInsightThreadIdFromNewsroomPathname(pathname: string | null | undefined): string | null {
+  if (!pathname?.startsWith("/newsroom/insights/")) return null;
+  const segment = pathname.slice("/newsroom/insights/".length).split("/")[0]?.trim() ?? "";
+  if (!segment) return null;
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}