@anthusai/papyrus 0.0.0 → 1.0.0-next.10

package/lib/site-brand.ts

@@ -0,0 +1,194 @@
+import type { ComponentType } from "react";
+import type { EditionPresentationFormat } from "./content-types";
+import type { Article, ArticleVideoAsset } from "./articles";
+import type { BlogPageBackgroundProps } from "../components/blog-page-background";
+import type { PictogramFigureProps } from "../components/pictogram-figure";
+import papyrusSite from "papyrus-site";
+import {
+  DEFAULT_THEME_PACK_TOKENS,
+  type HostingConfig,
+  type OpsChrome,
+  type ReaderDeployment,
+  type RendererConfig,
+  type RootRouteConfig,
+  type ThemePackId,
+  type ThemePackTokens,
+} from "./site-stack";
+
+/** Open string: a publication registers its own brand through `papyrus.config.ts` (`defineSite`). */
+export type SiteBrandId = string;
+
+/** Brand-specific replacements for generic Pretext components. */
+export type SiteBrandComponents = {
+  PictogramFigure?: ComponentType<PictogramFigureProps>;
+  BlogPageBackground?: ComponentType<BlogPageBackgroundProps>;
+};
+
+/** Default scenario content a brand supplies for the layout lab. */
+export type SiteBrandDemoEdition = {
+  title: string;
+  editionDate: string;
+  description: string;
+  articles: Article[];
+  suppressNewsDeskAppendix?: boolean;
+  editionVideo?: ArticleVideoAsset;
+};
+
+/**
+ * Video slot: how a publication supplies its own VideoML scene components.
+ * Paths are relative to the publication root.
+ */
+export type SiteBrandVideo = {
+  /** TSX module that registers the brand's `@videoml` scene components via `window.Babulus.registerComponent`. */
+  bundleEntry: string;
+  /** DSL element aliases for the browser preview, e.g. `{ "quote-card": "acme-quote-card" }`. */
+  sceneComponents?: Record<string, string>;
+  rhythm?: Record<string, unknown>;
+};
+
+export type SiteBrand = {
+  id: SiteBrandId;
+  appTitle: string;
+  appDescription: string;
+  mastheadTitle: string;
+  mastheadSubtitle: string;
+  mastheadTagline?: string;
+  backToHomeLabel: string;
+  articleTitleSuffix: string;
+  placeholderByline: string;
+  defaultPresentation: EditionPresentationFormat;
+  forcedPresentation?: EditionPresentationFormat;
+  textFont: string;
+  footerTitle?: string;
+  footerSubtitleOverride?: string;
+  mastheadWordSplit: boolean;
+  mastheadDateFormat: "raw" | "formatted";
+  mastheadSource: "edition" | "brand";
+  sectionLinkStrategy: "route" | "anchor";
+  defaultVideoCredit?: string;
+  themePack: ThemePackId;
+  themeTokens: ThemePackTokens;
+  renderer: RendererConfig;
+  hosting: HostingConfig;
+  /** Static reader app when it is not co-hosted with this Papyrus checkout. */
+  readerDeployment?: ReaderDeployment;
+  /**
+   * What the root route (`/`) does. Defaults to `{ kind: "reader" }` (render
+   * the publication home page). Set to `{ kind: "redirect", destination }`
+   * for a CMS-only deployment whose reader lives elsewhere.
+   */
+  rootRoute?: RootRouteConfig;
+  /** Public URL prefix for newsroom routes. Default `/newsroom`; use `""` on a CMS-only subdomain. */
+  newsroomBasePath?: string;
+  opsChrome: OpsChrome;
+  corpusKey: string;
+  steeringConfigPath: string;
+  newsroomSectionsConfigPath: string;
+  analysisProfilesPath: string;
+  publicationName: string;
+  components?: SiteBrandComponents;
+  demoEdition?: SiteBrandDemoEdition;
+  video?: SiteBrandVideo;
+};
+
+const SERIF_TEXT_FONT = 'Georgia, "Times New Roman", serif';
+
+const REFERENCE_SITE_BRANDS: Record<SiteBrandId, SiteBrand> = {
+  papyrus: {
+    id: "papyrus",
+    appTitle: "Papyrus",
+    appDescription: "A Pretext-powered responsive newspaper layout lab.",
+    mastheadTitle: "PAPYRUS",
+    mastheadSubtitle: "Inside Papyrus",
+    backToHomeLabel: "Back to Papyrus",
+    articleTitleSuffix: "Papyrus",
+    placeholderByline: "Papyrus",
+    defaultPresentation: "newsprint",
+    textFont: SERIF_TEXT_FONT,
+    mastheadWordSplit: false,
+    mastheadDateFormat: "raw",
+    mastheadSource: "edition",
+    sectionLinkStrategy: "route",
+    themePack: "papyrus",
+    themeTokens: DEFAULT_THEME_PACK_TOKENS,
+    renderer: { kind: "pretext" },
+    hosting: { kind: "amplify-ssr" },
+    opsChrome: "app",
+    corpusKey: "threat-intelligence",
+    steeringConfigPath: "corpora/papyrus-steering.yml",
+    newsroomSectionsConfigPath: "corpora/papyrus-newsroom-sections.yml",
+    analysisProfilesPath: "corpora/papyrus-analysis-profiles.yml",
+    publicationName: "Anthus Threat Intelligence",
+  },
+};
+
+/**
+ * The Papyrus reference brand plus whatever the publication registered in its
+ * own `papyrus.config.ts` (resolved through the `papyrus-site` alias).
+ */
+const SITE_BRANDS: Record<SiteBrandId, SiteBrand> = {
+  ...REFERENCE_SITE_BRANDS,
+  ...Object.fromEntries((papyrusSite.brands ?? []).map((brand) => [brand.id, brand])),
+};
+
+export function normalizeSiteBrandId(value: string | undefined | null): SiteBrandId | null {
+  if (!value) return null;
+  const trimmed = value.trim();
+  return Object.prototype.hasOwnProperty.call(SITE_BRANDS, trimmed) ? trimmed : null;
+}
+
+function unknownBrandError(value: string): Error {
+  return new Error(`Unknown brand '${value}'. Registered: ${Object.keys(SITE_BRANDS).join(", ")}`);
+}
+
+export function resolveSiteBrandId(
+  raw: string | undefined | null = process.env.NEXT_PUBLIC_PAPYRUS_SITE_BRAND ?? process.env.PAPYRUS_SITE_BRAND,
+): SiteBrandId {
+  const requested = raw?.trim();
+  if (requested) {
+    const normalized = normalizeSiteBrandId(requested);
+    if (normalized === null) throw unknownBrandError(requested);
+    return normalized;
+  }
+  const fallback = papyrusSite.defaultBrand ?? "papyrus";
+  const normalizedFallback = normalizeSiteBrandId(fallback);
+  if (normalizedFallback === null) throw unknownBrandError(fallback);
+  return normalizedFallback;
+}
+
+export function getSiteBrand(id: SiteBrandId = resolveSiteBrandId()): SiteBrand {
+  const brand = Object.prototype.hasOwnProperty.call(SITE_BRANDS, id) ? SITE_BRANDS[id] : undefined;
+  if (!brand) throw unknownBrandError(id);
+  return brand;
+}
+
+export const SITE_BRAND = getSiteBrand();
+
+/** Root-route config for a brand, defaulting to `{ kind: "reader" }`. */
+export function getRootRoute(brand: SiteBrand = SITE_BRAND): RootRouteConfig {
+  return brand.rootRoute ?? { kind: "reader" };
+}
+
+export const rootRoute = getRootRoute();
+
+export function enforcePresentation(presentation: EditionPresentationFormat): EditionPresentationFormat {
+  return SITE_BRAND.forcedPresentation ?? presentation;
+}
+
+export function getPresentationChoices(brand: SiteBrand = SITE_BRAND): EditionPresentationFormat[] {
+  return brand.forcedPresentation
+    ? [brand.forcedPresentation]
+    : ["newsprint", "blog", "magazine"];
+}
+
+export function getForcedPresentation(): EditionPresentationFormat | undefined {
+  return SITE_BRAND.forcedPresentation;
+}
+
+export function getDefaultPretextLayout(): EditionPresentationFormat {
+  return SITE_BRAND.defaultPresentation;
+}
+
+export function getRendererKind(): RendererConfig["kind"] {
+  return SITE_BRAND.renderer.kind;
+}

package/lib/site-env.ts

@@ -0,0 +1,52 @@
+export type SiteEnv = "production" | "staging" | "development";
+export type ContentSource = "published" | "drafts";
+
+type EnvironmentVariables = Record<string, string | undefined>;
+
+const SITE_ENVIRONMENTS: readonly SiteEnv[] = ["production", "staging", "development"];
+const CONTENT_SOURCES: readonly ContentSource[] = ["published", "drafts"];
+const PRODUCTION_BRANCH = "main";
+
+export function getSiteEnv(environment: EnvironmentVariables = process.env): SiteEnv {
+  const configured = (environment.SITE_ENV ?? "").trim();
+  if (!configured) return "development";
+  if (!SITE_ENVIRONMENTS.includes(configured as SiteEnv)) {
+    throw new Error(`SITE_ENV must be one of ${SITE_ENVIRONMENTS.join(", ")}; received "${configured}".`);
+  }
+  if (configured === "production") {
+    const branch = (environment.AWS_BRANCH ?? "").trim();
+    if (branch && branch !== PRODUCTION_BRANCH) return "staging";
+  }
+  return configured as SiteEnv;
+}
+
+export function getContentSource(environment: EnvironmentVariables = process.env): ContentSource {
+  const configured = (environment.PAPYRUS_CONTENT_SOURCE ?? "").trim();
+  if (!configured) return "published";
+  if (!CONTENT_SOURCES.includes(configured as ContentSource)) {
+    throw new Error(`PAPYRUS_CONTENT_SOURCE must be one of ${CONTENT_SOURCES.join(", ")}; received "${configured}".`);
+  }
+  return configured as ContentSource;
+}
+
+export function isIndexable(environment: EnvironmentVariables = process.env): boolean {
+  return getSiteEnv(environment) === "production";
+}
+
+export function showStagingBanner(environment: EnvironmentVariables = process.env): boolean {
+  return getSiteEnv(environment) === "staging";
+}
+
+export function analyticsAllowed(environment: EnvironmentVariables = process.env): boolean {
+  return getSiteEnv(environment) === "production";
+}
+
+export function assertContentSourceMatchesEnv(environment: EnvironmentVariables = process.env): void {
+  if (getContentSource(environment) !== "drafts") return;
+  const siteEnv = getSiteEnv(environment);
+  if (siteEnv !== "staging") {
+    throw new Error(
+      `PAPYRUS_CONTENT_SOURCE=drafts requires SITE_ENV=staging; the resolved site environment is "${siteEnv}". Drafts must never be served from production or development.`,
+    );
+  }
+}

package/lib/site-renderer.ts

@@ -0,0 +1,17 @@
+import { MarkusSiteRendererError } from "./renderer-config";
+import { SITE_BRAND } from "./site-brand";
+import type { Renderer } from "./renderer";
+import { pretextRenderer } from "../renderers/pretext";
+
+export { MarkusSiteRendererError } from "./renderer-config";
+
+export function assertPretextSite(): void {
+  if (SITE_BRAND.renderer.kind === "markus") {
+    throw new MarkusSiteRendererError("hackerman", SITE_BRAND.id);
+  }
+}
+
+export function getSiteRenderer(): Renderer {
+  assertPretextSite();
+  return pretextRenderer;
+}

package/lib/site-stack.ts

@@ -0,0 +1,195 @@
+/**
+ * Independent site-stack axes. Do not collapse these into one "brand mode".
+ * - themePack / themeTokens: ops + shared Shadcn colors
+ * - opsChrome: newsroom shell (app vs newsprint)
+ * - renderer: publication / reader output (pretext vs markus)
+ * - hosting: where the built site is served
+ *
+ * Shared ops components consume CSS variables only. Pilobolus is the first
+ * extra pack, not the platform default (that remains `papyrus`).
+ */
+/** Open string: publications register their own pack id (see lib/define-site.ts). */
+export type ThemePackId = string;
+
+export type RendererConfig = {
+  kind: "pretext" | "markus";
+};
+
+export type HostingConfig =
+  | { kind: "amplify-ssr" }
+  | { kind: "amplify-static" };
+
+/**
+ * What the root route (`/`) of a Papyrus app does. Independent of hosting and
+ * of where the public reader lives — a site configures this explicitly.
+ *
+ * - `reader`: render the publication home page here (the single-app reader+Cms
+ *   model used by p.apyr.us and Threat Intelligence). Default when omitted.
+ * - `redirect`: redirect `/` to `destination` (a path or absolute URL). Use
+ *   this for CMS-only deployments whose public reader lives on another app.
+ * - `newsroom`: render the newsroom desk at `/` (for a CMS-only subdomain).
+ */
+export type RootRouteConfig =
+  | { kind: "reader" }
+  | { kind: "redirect"; destination: string; permanent?: boolean }
+  | { kind: "newsroom" };
+
+/**
+ * Optional reader deployment when CMS and public reader ship separately
+ * (Pilobolus, Anth.us).
+ *
+ * `domain` and `amplifyAppId` are optional because a reader can legitimately
+ * exist before either is known: a staging port runs on the Amplify-provided
+ * hostname with no custom domain attached, and the app id does not exist until
+ * someone creates the app. Leave them unset rather than writing down a
+ * hostname that is not actually serving this build — a wrong canonical host is
+ * worse than an absent one.
+ */
+export type ReaderDeployment = {
+  kind: "amplify-static";
+  repository: string;
+  domain?: string;
+  amplifyAppId?: string;
+};
+
+export type OpsChrome = "newsprint" | "app";
+
+export type SiteOpsStack = {
+  chrome: OpsChrome;
+  themePack: ThemePackId;
+  themeTokens: ThemePackTokens;
+};
+
+export type SitePublicationStack = {
+  renderer: RendererConfig;
+};
+
+/** Ops UI and publication/reader are independently pluggable. */
+export type SiteStack = {
+  ops: SiteOpsStack;
+  publication: SitePublicationStack;
+  hosting: HostingConfig;
+};
+
+export type SiteStackSource = {
+  themePack: ThemePackId;
+  themeTokens: ThemePackTokens;
+  opsChrome: OpsChrome;
+  renderer: RendererConfig;
+  hosting: HostingConfig;
+};
+
+export function getSiteStack(source: SiteStackSource): SiteStack {
+  return {
+    ops: {
+      chrome: source.opsChrome,
+      themePack: source.themePack,
+      themeTokens: source.themeTokens,
+    },
+    publication: { renderer: source.renderer },
+    hosting: source.hosting,
+  };
+}
+
+export type ThemePackPalette = {
+  paper: string;
+  moss: string;
+  ochre: string;
+  ink: string;
+  muted?: string;
+  card?: string;
+  line?: string;
+  quote?: string;
+  tip?: string;
+  caution?: string;
+  stage?: string;
+};
+
+export type ThemePackTokens = ThemePackPalette & {
+  dark?: ThemePackPalette;
+};
+
+export const DEFAULT_THEME_PACK_TOKENS: ThemePackTokens = {
+  paper: "#f4f4f5",
+  moss: "#18181b",
+  ochre: "#a1a1aa",
+  ink: "#3f3f46",
+};
+
+/**
+ * Pilobolus / fungus-among-us palette copied from AnthusAI/Pilobol.us
+ * `web/css/pilobil-theme-v10.css` (`:root` / `@media (prefers-color-scheme: dark)`).
+ * Colors only — Shadcn owns typography. Do not load that file at runtime.
+ */
+export const PILOBOL_US_THEME_PACK_TOKENS: ThemePackTokens = {
+  ink: "#211d17",
+  muted: "#6b6153",
+  paper: "#f1ead9",
+  card: "#fbf6ea",
+  line: "#d7cbb2",
+  moss: "#3f5d43",
+  ochre: "#a35a2a",
+  quote: "#4a3548",
+  tip: "#4f6b3a",
+  caution: "#8a3324",
+  stage: "#ddd4bf",
+  dark: {
+    ink: "#dfded0",
+    muted: "#8b9184",
+    paper: "#14170f",
+    card: "#1c2117",
+    line: "#333b2a",
+    moss: "#b7d18a",
+    ochre: "#d0895a",
+    quote: "#b7a3c4",
+    tip: "#9fce7a",
+    caution: "#d17e6e",
+    stage: "#0d0f0a",
+  },
+};
+
+/**
+ * Anthus palette, read off the live Gatsby site at `AnthusAI/Anth.us`
+ * (`src/styles/variables.scss` `:root`). Colors only — Shadcn owns typography.
+ * Mapping from that file's names to the pack's slots:
+ *
+ * | pack slot | Anth.us variable          | value     |
+ * | --------- | ------------------------- | --------- |
+ * | `paper`   | `--color-layout-bg`       | `#f1f9fe` |
+ * | `card`    | `--color-wrapper-bg`      | `#ffffff` |
+ * | `ink`     | `--color-text`            | `#333333` |
+ * | `moss`    | `--color-primary`         | `#dc5497` |
+ * | `ochre`   | `--color-active`          | `#ff57b4` |
+ * | `quote`   | `--color-gradient-mid`    | `#9b165d` |
+ * | `tip`     | `--color-gradient-end`    | `#0389d7` |
+ * | `stage`   | `--color-hamburger`       | `#fedded` |
+ *
+ * Two slots have no counterpart on the Gatsby site and are **derived**, which
+ * is called out here so nobody mistakes them for copied brand values:
+ *
+ * - `line`: the site's only rule color is `hr { background: hsla(0,0%,0%,0.2) }`
+ *   over white, flattened to `#cccccc`.
+ * - `muted`: the site has no muted-text token at all — it dims with
+ *   `opacity: 0.5` instead (and references an undefined `--color-text-light`).
+ *   `#5f6b73` is `--color-text` desaturated toward `paper`'s blue.
+ * - `caution`: `#e95800`, which the site uses for one of its `::marker`
+ *   colors; it has no dedicated danger color.
+ *
+ * There is deliberately **no `dark` palette**: the Gatsby site has no dark
+ * mode. Its only `prefers-color-scheme: dark` block overrides two
+ * code-highlight tints. Inventing a dark Anthus palette here would be making
+ * up a look rather than porting one, so `theme.css` pins `color-scheme: light`.
+ */
+export const ANTH_US_THEME_PACK_TOKENS: ThemePackTokens = {
+  ink: "#333333",
+  muted: "#5f6b73",
+  paper: "#f1f9fe",
+  card: "#ffffff",
+  line: "#cccccc",
+  moss: "#dc5497",
+  ochre: "#ff57b4",
+  quote: "#9b165d",
+  tip: "#0389d7",
+  caution: "#e95800",
+  stage: "#fedded",
+};

package/lib/staging-gate.ts

@@ -0,0 +1,37 @@
+import type { NextRequest, NextResponse } from "next/server";
+import { fetchAuthSession } from "aws-amplify/auth/server";
+import { getAmplifyServerRuntime } from "./amplify-server-runtime";
+
+export type StagingAccess = "anonymous" | "forbidden" | "ok";
+
+const STAGING_ALLOWED_GROUPS = ["editor", "admin"];
+
+export function groupsFromIdTokenPayload(payload: Record<string, unknown> | undefined): string[] {
+  const raw = payload?.["cognito:groups"];
+  if (Array.isArray(raw)) return raw.filter((group): group is string => typeof group === "string");
+  if (typeof raw === "string" && raw) return [raw];
+  return [];
+}
+
+export function accessForGroups(groups: string[] | null): StagingAccess {
+  if (groups === null) return "anonymous";
+  return groups.some((group) => STAGING_ALLOWED_GROUPS.includes(group)) ? "ok" : "forbidden";
+}
+
+export async function getStagingAccess(request: NextRequest, response: NextResponse): Promise<StagingAccess> {
+  const { runWithAmplifyServerContext } = getAmplifyServerRuntime();
+  const groups = await runWithAmplifyServerContext({
+    nextServerContext: { request, response },
+    operation: async (contextSpec) => {
+      try {
+        const session = await fetchAuthSession(contextSpec);
+        const idTokenPayload = session.tokens?.idToken?.payload as Record<string, unknown> | undefined;
+        if (!session.tokens?.idToken) return null;
+        return groupsFromIdTokenPayload(idTokenPayload);
+      } catch {
+        return null;
+      }
+    },
+  });
+  return accessForGroups(groups);
+}

package/lib/staging-preview-object.ts

@@ -0,0 +1,98 @@
+import { cookies } from "next/headers";
+import { getUrl } from "aws-amplify/storage/server";
+import { getAmplifyServerRuntime } from "./amplify-server-runtime";
+import { getSiteEnv } from "./site-env";
+
+export const PREVIEW_ROUTE_PREFIX = "/__preview";
+export const PREVIEW_KEY_PREFIX = "preview/";
+
+const PRESIGN_SECONDS = 60;
+const NOT_FOUND_ERROR_NAMES = ["NotFound", "NoSuchKey"];
+const PREVIEW_EXCLUDED_PREFIXES = ["/newsroom", "/api", "/_next", PREVIEW_ROUTE_PREFIX];
+
+export function isStaticPreviewEnabled(environment: Record<string, string | undefined> = process.env): boolean {
+  return getSiteEnv(environment) === "staging" && (environment.PAPYRUS_STAGING_PREVIEW ?? "").trim() === "static";
+}
+
+export function previewCandidateKeys(requestPath: string): string[] | null {
+  if (requestPath.includes("//")) return null;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(requestPath);
+  } catch {
+    return null;
+  }
+  if (decoded.includes("//") || decoded.includes("\\") || decoded.includes("\0")) return null;
+  const segments = decoded.split("/").filter((segment) => segment !== "");
+  if (segments.some((segment) => segment === ".." || segment === ".")) return null;
+  if (segments.length === 0) return [`${PREVIEW_KEY_PREFIX}index.html`];
+  const joined = segments.join("/");
+  if (decoded.endsWith("/")) return [`${PREVIEW_KEY_PREFIX}${joined}/index.html`];
+  const base = `${PREVIEW_KEY_PREFIX}${joined}`;
+  return [base, `${base}.html`, `${base}/index.html`];
+}
+
+export function shouldRewriteToPreview(pathname: string): boolean {
+  if (pathname === "/favicon.ico" || pathname === "/robots.txt" || pathname.startsWith("/icon")) return false;
+  return !PREVIEW_EXCLUDED_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+}
+
+export function isPreviewGatedPath(pathname: string): boolean {
+  return shouldRewriteToPreview(pathname) || pathname === PREVIEW_ROUTE_PREFIX || pathname.startsWith(`${PREVIEW_ROUTE_PREFIX}/`);
+}
+
+export function previewRewritePathname(pathname: string): string {
+  return `${PREVIEW_ROUTE_PREFIX}${pathname}`;
+}
+
+export function previewRequestPath(pathname: string): string {
+  return pathname.slice(PREVIEW_ROUTE_PREFIX.length) || "/";
+}
+
+function isNotFoundError(error: unknown): boolean {
+  const name = (error as { name?: string } | null)?.name ?? "";
+  return NOT_FOUND_ERROR_NAMES.includes(name);
+}
+
+async function presignFirstExistingKey(candidateKeys: string[]): Promise<URL | null> {
+  const { runWithAmplifyServerContext } = getAmplifyServerRuntime();
+  return runWithAmplifyServerContext({
+    nextServerContext: { cookies },
+    operation: async (contextSpec) => {
+      for (const key of candidateKeys) {
+        try {
+          const { url } = await getUrl(contextSpec, {
+            path: key,
+            options: { validateObjectExistence: true, expiresIn: PRESIGN_SECONDS },
+          });
+          return url;
+        } catch (error) {
+          if (!isNotFoundError(error)) throw error;
+        }
+      }
+      return null;
+    },
+  });
+}
+
+function notFound(): Response {
+  return new Response("Not found", { status: 404, headers: { "Cache-Control": "private, no-store" } });
+}
+
+export async function streamPreviewObject(pathname: string): Promise<Response> {
+  if (!isStaticPreviewEnabled()) return notFound();
+  const candidateKeys = previewCandidateKeys(previewRequestPath(pathname));
+  if (!candidateKeys) return notFound();
+  const presigned = await presignFirstExistingKey(candidateKeys);
+  if (!presigned) return notFound();
+  const upstream = await fetch(presigned);
+  if (!upstream.ok || !upstream.body) return notFound();
+  return new Response(upstream.body, {
+    status: 200,
+    headers: {
+      "Content-Type": upstream.headers.get("content-type") ?? "application/octet-stream",
+      "Cache-Control": "private, no-store",
+      "X-Robots-Tag": "noindex, nofollow",
+    },
+  });
+}

package/lib/themed-image.ts

@@ -0,0 +1,30 @@
+import type { ArticleImageThemeVariants, ArticleVideoThemeVariants } from "./articles";
+
+export type ResolvedTheme = "light" | "dark";
+
+export function resolveThemedImageSrc(
+  src: string,
+  themeVariants: ArticleImageThemeVariants | undefined,
+  theme: ResolvedTheme,
+): string {
+  if (theme === "dark" && themeVariants?.dark?.src) return themeVariants.dark.src;
+  if (theme === "dark") return resolveStaticDarkSvgFallback(src) ?? src;
+  return src;
+}
+
+export function resolveThemedVideoSrc(
+  src: string,
+  themeVariants: ArticleVideoThemeVariants | undefined,
+  theme: ResolvedTheme,
+): string {
+  if (theme === "light" && themeVariants?.light?.src) return themeVariants.light.src;
+  if (theme === "dark" && themeVariants?.dark?.src) return themeVariants.dark.src;
+  return src;
+}
+
+function resolveStaticDarkSvgFallback(src: string): string | null {
+  if (src.startsWith("/seed-art/threat-intelligence/") && !src.endsWith("-dark.svg") && /\.svg(?:\?.*)?$/i.test(src)) {
+    return src.replace(/\.svg(?:\?.*)?$/i, (suffix) => `-dark${suffix}`);
+  }
+  return null;
+}

package/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

package/lib/video-mode.ts

@@ -0,0 +1,42 @@
+export type VideoMode = "preview" | "mp4";
+
+function parseVideoMode(value: string | null | undefined): VideoMode | null {
+  if (value === "preview" || value === "mp4") return value;
+  return null;
+}
+
+/** Server-safe mode from env only. Production always returns `"mp4"`. */
+export function resolveVideoModeFromEnv(): VideoMode {
+  if (process.env.NODE_ENV === "production") return "mp4";
+  return parseVideoMode(process.env.NEXT_PUBLIC_PAPYRUS_VIDEO_MODE) ?? "preview";
+}
+
+/** Client-only `?video=` override. Returns null when absent or in production. */
+export function resolveVideoModeFromSearch(search: string): VideoMode | null {
+  if (process.env.NODE_ENV === "production") return null;
+  const query = search.startsWith("?") ? search.slice(1) : search;
+  return parseVideoMode(new URLSearchParams(query).get("video"));
+}
+
+/**
+ * Effective video mode for the reader.
+ * Production always uses `"mp4"`. In development, `?video=` overrides
+ * `NEXT_PUBLIC_PAPYRUS_VIDEO_MODE` (default `"preview"`).
+ */
+export function resolveVideoMode(): VideoMode {
+  if (process.env.NODE_ENV === "production") return "mp4";
+  if (typeof window !== "undefined") {
+    const fromSearch = resolveVideoModeFromSearch(window.location.search);
+    if (fromSearch) return fromSearch;
+  }
+  return resolveVideoModeFromEnv();
+}
+
+/**
+ * Server-safe gate for fetching VideoML DSL scripts.
+ * Always true in development so `?video=preview` and `?video=mp4` can both
+ * work without restarting the server. Production never fetches scripts.
+ */
+export function shouldFetchVideoScripts(): boolean {
+  return process.env.NODE_ENV === "development";
+}