@anthusai/papyrus 1.0.0-next.4 → 1.0.0-next.41

package/lib/relevance-decisions.ts

@@ -0,0 +1,103 @@
+import type { SemanticRelationRecord } from "./category-repository";
+
+export const RELEVANCE_RELATION = "relevance_decision_is";
+
+/** The relevance cyclotron's current decision about one reference, as the References tab shows it. */
+export type RelevanceDecisionView = {
+  decisionRelationId: string;
+  decisionId: string;
+  label: string;
+  confidence: number | null;
+  version: number | null;
+  /** True when the cyclotron sent this decision to review. */
+  reviewRecommended: boolean;
+  reviewReason: "program" | "audit" | null;
+  reviewDetail: string | null;
+  classes: string[];
+  positiveLabel: string | null;
+  question: string | null;
+  /** Thumbs for a two-class decision with a positive label; per-class buttons otherwise. */
+  reviewControl: "thumbs" | "labels";
+  cyclotronId: string | null;
+};
+
+/** What an editor submits from the review control. */
+export type RelevanceReview = {
+  label: string | null;
+  reasonCode: string | null;
+  explanation: string | null;
+  shareable: boolean;
+};
+
+/** The existing curation action an editor's review becomes. */
+export type RelevanceCuration = {
+  action: "accept" | "reject";
+  reasonCode: string | null;
+  note: string | null;
+  decisionRelationId: string;
+  shareable: boolean;
+};
+
+function parseMetadata(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object" && !Array.isArray(value)) return value as Record<string, unknown>;
+  if (typeof value !== "string") return {};
+  try {
+    const parsed = JSON.parse(value);
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Current decisions keyed by reference lineage, from relations the Newsroom
+ * already loads: no extra request per row.
+ */
+export function currentRelevanceDecisions(relations: SemanticRelationRecord[]): Map<string, RelevanceDecisionView> {
+  const decisions = new Map<string, RelevanceDecisionView>();
+  for (const relation of relations) {
+    if (relation.predicate !== RELEVANCE_RELATION || relation.relationState !== "current") continue;
+    const metadata = parseMetadata(relation.metadata);
+    const probabilities = parseMetadata(metadata.probabilities);
+    const reason = metadata.reviewReason === "program" || metadata.reviewReason === "audit" ? metadata.reviewReason : null;
+    const version = Number(relation.modelVersion ?? metadata.version);
+    decisions.set(relation.subjectLineageId, {
+      decisionRelationId: relation.id,
+      decisionId: String(metadata.decisionId ?? ""),
+      label: String(metadata.label ?? ""),
+      confidence: typeof relation.confidence === "number" ? relation.confidence : null,
+      version: Number.isFinite(version) ? version : null,
+      reviewRecommended: Boolean(relation.reviewRecommended),
+      reviewReason: reason,
+      reviewDetail: typeof metadata.reviewDetail === "string" ? metadata.reviewDetail : null,
+      classes: Array.isArray(metadata.labels) && metadata.labels.length
+        ? metadata.labels.map(String)
+        : Object.keys(probabilities),
+      positiveLabel: typeof metadata.positiveLabel === "string" ? metadata.positiveLabel : null,
+      question: typeof metadata.question === "string" ? metadata.question : null,
+      reviewControl: metadata.reviewControl === "thumbs" ? "thumbs" : "labels",
+      cyclotronId: typeof metadata.cyclotronId === "string" ? metadata.cyclotronId : null,
+    });
+  }
+  return decisions;
+}
+
+/**
+ * Map a review to the existing curation mutation. The positive label accepts;
+ * any other label, or a review without a label, rejects with the reason code,
+ * which the existing scope-training rule turns back into a cyclotron label
+ * (out_of_scope and policy_exclusion) or none.
+ */
+export function curationForRelevanceReview(decision: RelevanceDecisionView, review: RelevanceReview): RelevanceCuration {
+  const accepted = review.label !== null && review.label === decision.positiveLabel;
+  if (!accepted && !review.reasonCode) {
+    throw new Error("A review that does not accept the reference needs a reason code.");
+  }
+  return {
+    action: accepted ? "accept" : "reject",
+    reasonCode: accepted ? null : review.reasonCode,
+    note: review.explanation?.trim() || null,
+    decisionRelationId: decision.decisionRelationId,
+    shareable: review.shareable,
+  };
+}

package/lib/relevance-status.ts

@@ -0,0 +1,63 @@
+import type { CyclotronStatus } from "cyclotron/cyclotron-status";
+import { isCyclotronStatus } from "cyclotron/cyclotron-status";
+
+/** The KnowledgeRawPayload the decide-relevance sweep writes the status snapshot to. */
+export function cyclotronStatusPayloadId(cyclotronId: string): string {
+  return `knowledge-raw-payload-cyclotron-status-${safeId(cyclotronId)}`;
+}
+
+/** The KnowledgeRawPayload an editor writes to ask for a manual review rate. */
+export function reviewRateRequestPayloadId(cyclotronId: string): string {
+  return `knowledge-raw-payload-cyclotron-review-rate-request-${safeId(cyclotronId)}`;
+}
+
+/** Mirrors Python's ids.safe_id so both sides name the same record. */
+export function safeId(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 140);
+}
+
+export type ReviewRateRequest =
+  | { rate: number; expiresAt: string; setBy: string; requestedAt: string }
+  | { clear: true; setBy: string; requestedAt: string };
+
+export function buildReviewRateRequest(
+  choice: { rate: number; days: number } | { clear: true },
+  setBy: string,
+  now: Date = new Date(),
+): ReviewRateRequest {
+  const requestedAt = now.toISOString();
+  if ("clear" in choice) return { clear: true, setBy, requestedAt };
+  if (!(choice.rate >= 0 && choice.rate <= 1)) throw new Error("A review rate is between 0% and 100%.");
+  if (!(choice.days >= 1)) throw new Error("A manual rate lasts at least one day.");
+  const expiresAt = new Date(now.getTime() + choice.days * 24 * 60 * 60 * 1000).toISOString();
+  return { rate: choice.rate, expiresAt, setBy, requestedAt };
+}
+
+/** The newest valid snapshot among a payload's attachments. */
+export function latestCyclotronStatus(payloads: Array<{ json: unknown; updatedAt?: string | null }>): CyclotronStatus | null {
+  const valid = payloads
+    .filter((payload) => isCyclotronStatus(payload.json))
+    .sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")));
+  return valid.length ? (valid[0].json as CyclotronStatus) : null;
+}
+
+/** What demo mode shows: an onboarding cyclotron that has made one decision. */
+export const DEMO_CYCLOTRON_STATUS: CyclotronStatus = {
+  schema: "cyclotron-status/v1",
+  cyclotron: { id: "papyrus-relevance", classifier: "relevant", version: 1, refits: 0, fingerprint: "demo" },
+  asOf: "2026-05-16T12:00:00.000Z",
+  alignment: {
+    window: 200, labels: 0, accuracy: null, precision: null, recall: null,
+    positiveLabel: "include", measuredOn: "reviews selected by the cyclotron",
+  },
+  calibration: { saysSure: null, isRight: null, gapPoints: null, curve: [] },
+  reviewRate: {
+    state: "onboarding", rate: 1, reason: "Onboarding: every decision is reviewed until the cyclotron earns a lower rate.",
+    auditFloor: 0.05, confidenceThreshold: 0.7, override: null,
+    nextCheckAfterDecisions: 99,
+    nextStep: "Steps down to 50% after 2 more windows of 100 decisions with accuracy on confident decisions of at least 85% (at least 20 reviewed) and a calibration gap under 5 points. Next check in 99 decisions.",
+    expectedReviewsPerWeek: 1,
+  },
+  lastChange: null,
+  pending: { decisionsAwaitingReview: 1, staleSince: null },
+};

package/lib/renderer.ts

@@ -4,6 +4,7 @@ import type { EditionContent } from "./content-types";
 import type { PretextLayout } from "./renderer-config";
 import type { PresentationFooterEntry } from "./presentation-footer";
 import type { PublicationItem } from "./publication-items";
+import type { VideoScriptRef } from "./video-script";
 
 /**
  * Renderer is the swappable render pipeline that turns standard content
@@ -36,6 +37,8 @@ export type RenderEditionProps = {
 export type ArticlePageEditionFooter = {
   editionBasePath: string;
   entries: PresentationFooterEntry[];
+  /** Section links for the rhythm blog layout's page header. Ignored by the classic layout. */
+  sections?: Array<{ key: string; label: string }>;
   subtitle: string;
   title?: string;
 };
@@ -46,6 +49,8 @@ export type RenderArticleProps = {
   backLabel?: string;
   editionFooter?: ArticlePageEditionFooter;
   editionDate?: string;
+  /** VideoML script for the preview player. */
+  videoScript?: VideoScriptRef | null;
 };
 
 export type RenderItemProps = {
@@ -54,6 +59,8 @@ export type RenderItemProps = {
   backLabel?: string;
   editionFooter?: ArticlePageEditionFooter;
   editionDate?: string;
+  /** VideoML script for the preview player. */
+  videoScript?: VideoScriptRef | null;
 };
 
 /**

package/lib/revalidate-secret.ts

@@ -0,0 +1,59 @@
+import { timingSafeEqual } from "node:crypto";
+import { GetParameterCommand, SSMClient } from "@aws-sdk/client-ssm";
+
+export const REVALIDATE_SECRET_PARAMETER_ENV = "PAPYRUS_REVALIDATE_SECRET_PARAMETER";
+export const REVALIDATE_SECRET_CACHE_MILLISECONDS = 5 * 60 * 1000;
+
+export type RevalidateSecretReader = (parameterName: string) => Promise<string | null>;
+
+type CachedSecret = { parameterName: string; value: string; expiresAt: number };
+
+let cachedSecret: CachedSecret | null = null;
+let defaultSsmClient: SSMClient | null = null;
+
+export function resetRevalidateSecretCache(): void {
+  cachedSecret = null;
+}
+
+async function readSecretFromSsm(parameterName: string): Promise<string | null> {
+  defaultSsmClient ??= new SSMClient({});
+  const response = await defaultSsmClient.send(new GetParameterCommand({ Name: parameterName, WithDecryption: true }));
+  const value = response.Parameter?.Value?.trim();
+  return value ? value : null;
+}
+
+export async function loadRevalidateSecret(
+  options: { environment?: Record<string, string | undefined>; readSecret?: RevalidateSecretReader; now?: number } = {},
+): Promise<string | null> {
+  const environment = options.environment ?? process.env;
+  const parameterName = environment[REVALIDATE_SECRET_PARAMETER_ENV]?.trim();
+  if (!parameterName) return null;
+  const now = options.now ?? Date.now();
+  if (cachedSecret && cachedSecret.parameterName === parameterName && cachedSecret.expiresAt > now) {
+    return cachedSecret.value;
+  }
+  try {
+    const value = (await (options.readSecret ?? readSecretFromSsm)(parameterName))?.trim();
+    if (!value) return null;
+    cachedSecret = { parameterName, value, expiresAt: now + REVALIDATE_SECRET_CACHE_MILLISECONDS };
+    return value;
+  } catch (error) {
+    console.error(`Revalidate secret parameter could not be read (${error instanceof Error ? error.name : "error"}).`);
+    return null;
+  }
+}
+
+export function secretsMatch(provided: string | null | undefined, expected: string): boolean {
+  const providedBytes = Buffer.from((provided ?? "").trim());
+  const expectedBytes = Buffer.from(expected);
+  return providedBytes.length === expectedBytes.length && timingSafeEqual(providedBytes, expectedBytes);
+}
+
+export async function isAuthorizedRevalidateRequest(
+  providedSecret: string | null | undefined,
+  options: Parameters<typeof loadRevalidateSecret>[0] = {},
+): Promise<boolean> {
+  const expected = await loadRevalidateSecret(options);
+  if (!expected) return false;
+  return secretsMatch(providedSecret, expected);
+}

package/lib/robots-policy.ts

@@ -0,0 +1,14 @@
+import type { MetadataRoute } from "next";
+import { getRootRoute, getSiteBrand } from "./site-brand";
+import { isIndexable } from "./site-env";
+
+const DISALLOW_ALL: MetadataRoute.Robots = { rules: { userAgent: "*", disallow: "/" } };
+const ALLOW_ALL: MetadataRoute.Robots = { rules: { userAgent: "*", allow: "/" } };
+
+export function buildRobots(
+  environment: Record<string, string | undefined> = process.env,
+  brand = getSiteBrand(),
+): MetadataRoute.Robots {
+  if (getRootRoute(brand).kind === "newsroom") return DISALLOW_ALL;
+  return isIndexable(environment) ? ALLOW_ALL : DISALLOW_ALL;
+}

package/lib/root-route-redirect.ts

@@ -0,0 +1,16 @@
+export type RootSearchParams = Record<string, string | string[] | undefined>;
+
+export function buildRootRedirectTarget(destination: string, searchParams: RootSearchParams | undefined): string {
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(searchParams ?? {})) {
+    if (Array.isArray(value)) {
+      for (const entry of value) query.append(name, entry);
+    } else if (value !== undefined) {
+      query.append(name, value);
+    }
+  }
+  const serialized = query.toString();
+  if (!serialized) return destination;
+  const separator = destination.includes("?") ? "&" : "?";
+  return `${destination}${separator}${serialized}`;
+}

package/lib/semantic-graph.ts

@@ -1,3 +1,4 @@
+import { toPublicNewsroomPath } from "./newsroom-base-path";
 import type {
   AssignmentRecord,
   CategorySteeringCategory,
@@ -31,6 +32,7 @@ export type SemanticObjectKind = typeof SEMANTIC_OBJECT_KINDS[number];
 export type SemanticPredicateId =
   | "classified_as"
   | "quality_rating_is"
+  | "relevance_decision_is"
   | "reference_summary_100_tokens"
   | "reference_summary_200_tokens"
   | "reference_summary_500_tokens"
@@ -79,6 +81,7 @@ export const SEMANTIC_PREDICATES: SemanticPredicateDefinition[] = [
   { id: "about", label: "about", group: "commentary", inverseLabel: "commentary" },
   { id: "comment", label: "comments on", group: "commentary", inverseLabel: "commented on by", contextPackTags: ["reference_curation", "editing", "research", "assignment_context"] },
   { id: "ingestion_rationale", label: "ingestion rationale for", group: "commentary", inverseLabel: "ingestion rationale", contextPackTags: ["reference_curation", "editing", "research", "assignment_context"] },
+  { id: "relevance_decision_is", label: "relevance decision is", group: "workflow", inverseLabel: "relevance decision for", contextPackTags: ["reference_curation"] },
   { id: "requests_work_on", label: "requests work on", group: "workflow", inverseLabel: "requested work", contextPackTags: ["assignment_context", "editing"] },
   { id: "uses_evidence", label: "uses evidence", group: "evidence", inverseLabel: "used as evidence by", contextPackTags: ["assignment_context", "research", "reference_graph"] },
   { id: "uses_signal", label: "uses signal", group: "evidence", inverseLabel: "signal for", contextPackTags: ["assignment_context", "research", "reference_graph"] },
@@ -175,6 +178,10 @@ export function predicateLabel(predicate: string, direction: "outgoing" | "incom
 }
 
 export function newsDeskHrefForSemanticObject(kind: string, lineageId: string): string {
+  return toPublicNewsroomPath(internalNewsDeskHrefForSemanticObject(kind, lineageId));
+}
+
+function internalNewsDeskHrefForSemanticObject(kind: string, lineageId: string): string {
   const encoded = encodeURIComponent(lineageId);
   if (kind === "reference") return `/newsroom/references/${encoded}`;
   if (kind === "category") return `/newsroom/topics?category=${encoded}`;

package/lib/site-brand.ts

@@ -2,6 +2,7 @@ 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 { SiteBrandFont } from "./brand-fonts";
 import type { PictogramFigureProps } from "../components/pictogram-figure";
 import papyrusSite from "papyrus-site";
 import {
@@ -24,6 +25,23 @@ export type SiteBrandComponents = {
   BlogPageBackground?: ComponentType<BlogPageBackgroundProps>;
 };
 
+/**
+ * One line of a brand's header tagline: an emphasized lead and a plain tail,
+ * e.g. `{ emphasis: "Practical advice", tail: "for staying secure" }`.
+ */
+export type SiteBrandTaglineLine = {
+  emphasis: string;
+  tail: string;
+};
+
+/**
+ * Blog presentation layout. `"classic"` (the default) is the original blog
+ * layout. `"rhythm"` snaps every height and gap to the vertical rhythm grid,
+ * floats featured images on the grid, draws rhythm rules between items, adds
+ * the eyebrow/tagline header and the rhythm overlay hotkey (Ctrl+=).
+ */
+export type SiteBrandBlogLayout = "classic" | "rhythm";
+
 /** Default scenario content a brand supplies for the layout lab. */
 export type SiteBrandDemoEdition = {
   title: string;
@@ -34,6 +52,18 @@ export type SiteBrandDemoEdition = {
   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;
@@ -41,6 +71,10 @@ export type SiteBrand = {
   mastheadTitle: string;
   mastheadSubtitle: string;
   mastheadTagline?: string;
+  /** Rhythm blog layout only: small line above the masthead title, e.g. "Acme Research". The first word is emphasized. */
+  mastheadEyebrow?: string;
+  /** Rhythm blog layout only: structured tagline; `mastheadTagline` stays the plain-text fallback. */
+  mastheadTaglineLines?: SiteBrandTaglineLine[];
   backToHomeLabel: string;
   articleTitleSuffix: string;
   placeholderByline: string;
@@ -68,6 +102,8 @@ export type SiteBrand = {
   rootRoute?: RootRouteConfig;
   /** Public URL prefix for newsroom routes. Default `/newsroom`; use `""` on a CMS-only subdomain. */
   newsroomBasePath?: string;
+  /** Public URL prefix for the Pretext reader (home, editions, articles, archive, settings). Default `""`; e.g. `/information`. */
+  readerBasePath?: string;
   opsChrome: OpsChrome;
   corpusKey: string;
   steeringConfigPath: string;
@@ -75,7 +111,22 @@ export type SiteBrand = {
   analysisProfilesPath: string;
   publicationName: string;
   components?: SiteBrandComponents;
+  /**
+   * Video player chrome. `"native"` (default) is the browser's controls;
+   * `"framed"` wraps the media in `.article-video__media` and renders a
+   * "Play Video" button with a seek bar (`.article-video__cta*`), styled by the publication CSS.
+   */
+  videoPlayer?: "native" | "framed";
+  /** Blog presentation layout. Default `"classic"`. See `SiteBrandBlogLayout`. */
+  blogLayout?: SiteBrandBlogLayout;
+  /**
+   * Brand font slot: families the root layout loads (Google Fonts stylesheet
+   * or self-hosted files) and exposes as CSS custom properties. See
+   * `lib/brand-fonts.ts` and docs/brand-slots.md.
+   */
+  fonts?: SiteBrandFont[];
   demoEdition?: SiteBrandDemoEdition;
+  video?: SiteBrandVideo;
 };
 
 const SERIF_TEXT_FONT = 'Georgia, "Times New Roman", serif';

package/lib/staging-gated-path.ts

@@ -0,0 +1,23 @@
+import { normalizeReaderBasePath } from "./reader-base-path";
+
+function isStaticOrApiPath(pathname: string): boolean {
+  return (
+    pathname.startsWith("/_next")
+    || pathname.startsWith("/api")
+    || pathname === "/favicon.ico"
+    || pathname.startsWith("/icon")
+    || /\.[a-zA-Z0-9]+$/.test(pathname)
+  );
+}
+
+export { isStaticOrApiPath };
+
+export function isStagingGatedPath(pathname: string, readerBasePath: string = "", newsroomAtRoot: boolean = false): boolean {
+  if (newsroomAtRoot) return false;
+  if (isStaticOrApiPath(pathname)) return false;
+  if (pathname === "/robots.txt") return false;
+  if (pathname === "/newsroom" || pathname.startsWith("/newsroom/")) return false;
+  const base = normalizeReaderBasePath(readerBasePath);
+  if (base) return pathname === base || pathname.startsWith(`${base}/`);
+  return true;
+}

package/lib/staging-preview-object.ts

@@ -0,0 +1,114 @@
+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 FORBIDDEN_ERROR_NAMES = ["Forbidden", "AccessDenied"];
+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, newsroomAtRoot: boolean = false): boolean {
+  if (pathname === "/favicon.ico" || pathname === "/robots.txt" || pathname.startsWith("/icon")) return false;
+  if (PREVIEW_EXCLUDED_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`))) return false;
+  return !newsroomAtRoot || pathname.endsWith(".html");
+}
+
+export function isPreviewGatedPath(pathname: string, newsroomAtRoot: boolean = false): boolean {
+  return shouldRewriteToPreview(pathname, newsroomAtRoot) || 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);
+}
+
+function isForbiddenError(error: unknown): boolean {
+  const candidate = error as { name?: string; $metadata?: { httpStatusCode?: number }; metadata?: { httpStatusCode?: number } } | null;
+  const status = candidate?.$metadata?.httpStatusCode ?? candidate?.metadata?.httpStatusCode;
+  return status === 403 || FORBIDDEN_ERROR_NAMES.includes(candidate?.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();
+  let presigned: URL | null;
+  try {
+    presigned = await presignFirstExistingKey(candidateKeys);
+  } catch (error) {
+    if (isForbiddenError(error)) {
+      return new Response("Staging preview is limited to editors and admins.", { status: 403, headers: { "Cache-Control": "private, no-store" } });
+    }
+    throw error;
+  }
+  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/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";
+}