@anthusai/papyrus 1.0.0-next.3 → 1.0.0-next.5

package/lib/graphql-content-repository.ts

@@ -17,11 +17,13 @@ import {
 } from "./publication-items";
 import { BodyIrError, matchBodyImages, projectBodyIr, type BodyProjection, type BodyProjectionImage } from "./markus-body";
 import { SITE_BRAND } from "./site-brand";
+import { currentContentSource, runWithContentSource } from "./content-source-context";
+import { getContentSource } from "./site-env";
 
-const AUTH_MODE = "identityPool";
 const DEFAULT_EDITION_SLUG = "current";
 const PUBLISHED_STATUS = "published";
-const ARTICLE_TYPE_STATUS = "article#published";
+const DRAFT_STATUS = "draft";
+const ARTICLE_TYPE = "article";
 
 type DataClient = ReturnType<typeof generateClient<Schema>>;
 type EditionPublishedAtIndexQuery = (
@@ -64,8 +66,6 @@ type GraphQLEditionItem = {
 
 type GraphQLItem = {
   id: string;
-  sourceItemId?: string | null;
-  itemLineageId?: string | null;
   versionNumber?: number | null;
   type: string;
   status: string;
@@ -133,19 +133,32 @@ const IMAGE_ROLES: NonNullable<ArticleImageAsset["roles"]> = [
 let readerContextClient: DataClient | null = null;
 let buildTimeClient: DataClient | null = null;
 
+function authMode(): "userPool" | "identityPool" {
+  return currentContentSource() === "drafts" ? "userPool" : "identityPool";
+}
+
+function isVisibleItemStatus(status: string): boolean {
+  if (status === PUBLISHED_STATUS) return true;
+  return currentContentSource() === "drafts" && status === DRAFT_STATUS;
+}
+
 async function withReaderGraphQLContext<T>(operation: () => Promise<T>): Promise<T> {
   const { runWithAmplifyServerContext } = getAmplifyServerRuntime();
-  return runWithAmplifyServerContext({
-    nextServerContext: null,
-    operation: async () => {
-      readerContextClient = generateClient<Schema>({ authMode: AUTH_MODE });
-      try {
-        return await operation();
-      } finally {
-        readerContextClient = null;
-      }
-    },
-  });
+  const source = getContentSource();
+  const nextServerContext = source === "drafts" ? { cookies: (await import("next/headers")).cookies } : null;
+  return runWithContentSource(source, () =>
+    runWithAmplifyServerContext({
+      nextServerContext,
+      operation: async () => {
+        readerContextClient = generateClient<Schema>({ authMode: authMode() });
+        try {
+          return await operation();
+        } finally {
+          readerContextClient = null;
+        }
+      },
+    }),
+  );
 }
 
 export const graphqlContentRepository: ContentRepository = {
@@ -200,7 +213,7 @@ export const graphqlContentRepository: ContentRepository = {
   getArticle(slug) {
     return withReaderGraphQLContext(async () => {
       const item = await getItemBySlug(slug);
-      if (!item || item.type !== "article" || item.status !== "published") return undefined;
+      if (!item || item.type !== ARTICLE_TYPE || !isVisibleItemStatus(item.status)) return undefined;
       return normalizeArticle(item, await listMediaAssets(item.id));
     });
   },
@@ -218,9 +231,9 @@ export const graphqlContentRepository: ContentRepository = {
 
   listArticleSlugs() {
     return withReaderGraphQLContext(async () => {
-      const items = await listItemsByTypeStatus(ARTICLE_TYPE_STATUS);
+      const items = await listItemsByTypeStatus(`${ARTICLE_TYPE}#${PUBLISHED_STATUS}`);
       return items
-        .filter((item) => item.type === "article" && item.status === "published")
+        .filter((item) => item.type === ARTICLE_TYPE && isVisibleItemStatus(item.status))
         .map((item) => item.slug)
         .sort();
     });
@@ -232,7 +245,7 @@ function getClient(): DataClient {
 
   if (!buildTimeClient) {
     getAmplifyServerRuntime();
-    buildTimeClient = generateClient<Schema>({ authMode: AUTH_MODE });
+    buildTimeClient = generateClient<Schema>({ authMode: authMode() });
   }
   return buildTimeClient;
 }
@@ -331,7 +344,7 @@ async function loadEditionContentFromEdition(edition: GraphQLEdition): Promise<E
     await Promise.all(
       editionItems.map(async (editionItem) => {
         const item = await getItemById(editionItem.publishedItemId);
-        if (!item || item.status !== PUBLISHED_STATUS) return null;
+        if (!item || !isVisibleItemStatus(item.status)) return null;
         return normalizePublicationItem(item, await listMediaAssets(item.id));
       }),
     )
@@ -344,7 +357,7 @@ async function loadEditionContentFromEdition(edition: GraphQLEdition): Promise<E
       await Promise.all(
         missingLayoutItems.map(async (itemId) => {
           const item = await getItemBySlug(itemId);
-          if (!item || item.status !== PUBLISHED_STATUS) return null;
+          if (!item || !isVisibleItemStatus(item.status)) return null;
           return normalizePublicationItem(item, await listMediaAssets(item.id));
         }),
       )
@@ -461,7 +474,7 @@ async function loadEditionItem(editionDate: string, itemSlug: string): Promise<P
   const editionItems = await listEditionItems(edition.id);
   for (const editionItem of editionItems) {
     const item = await getItemById(editionItem.publishedItemId);
-    if (!item || item.slug !== itemSlug || item.status !== PUBLISHED_STATUS) continue;
+    if (!item || item.slug !== itemSlug || !isVisibleItemStatus(item.status)) continue;
     return (await normalizePublicationItem(item, await listMediaAssets(item.id))) ?? undefined;
   }
   return undefined;
@@ -505,36 +518,168 @@ function isMissingReaderBackendError(error: unknown): boolean {
 }
 
 function getEditionPublishedAtIndexQuery(): EditionPublishedAtIndexQuery | null {
-  const editionModel = getPublishedEditionModel() as unknown as {
-    listPublishedEditionsByStatusAndPublishedAt?: EditionPublishedAtIndexQuery;
-  };
+  const editionModel = getPublishedEditionModel();
   return typeof editionModel.listPublishedEditionsByStatusAndPublishedAt === "function"
     ? editionModel.listPublishedEditionsByStatusAndPublishedAt
     : null;
 }
 
-function getPublishedEditionModel() {
+type ListOptions = Record<string, unknown>;
+type ListResponse<T> = Promise<GraphQLListResponse<T>>;
+
+type EditionSourceModel = {
+  publishedEditionBySlug: (input: { slug: string }, options: ListOptions) => ListResponse<GraphQLEdition>;
+  listPublishedEditionsByStatusAndEditionDate: (
+    input: { status: string; editionDate?: { eq: string } },
+    options: ListOptions,
+  ) => ListResponse<GraphQLEdition>;
+  listPublishedEditionsByStatusAndPublishedAt?: EditionPublishedAtIndexQuery;
+};
+
+type EditionItemSourceModel = {
+  listPublishedEditionItemsByEditionAndSortKey: (
+    input: { publishedEditionId: string },
+    options: ListOptions,
+  ) => ListResponse<GraphQLEditionItem>;
+};
+
+type ItemSourceModel = {
+  get: (input: { id: string }, options: ListOptions) => Promise<GraphQLGetResponse<GraphQLItem>>;
+  publishedItemBySlug: (input: { slug: string }, options: ListOptions) => ListResponse<GraphQLItem>;
+  listPublishedItemsByTypeStatusAndPublishedAt: (input: { typeStatus: string }, options: ListOptions) => ListResponse<GraphQLItem>;
+};
+
+type MediaAssetSourceModel = {
+  listPublishedMediaAssetsByItemAndSortKey: (
+    input: { publishedItemId: string },
+    options: ListOptions,
+  ) => ListResponse<GraphQLMediaAsset>;
+};
+
+const DRAFTS_EDITION_STATUSES = [PUBLISHED_STATUS, DRAFT_STATUS];
+
+async function listMergedAcrossStatuses<T>(
+  statuses: string[],
+  runForStatus: (status: string, pageOptions: ListOptions) => ListResponse<T>,
+  sortValue: (row: T) => string,
+  options: ListOptions,
+): ListResponse<T> {
+  const rows: T[] = [];
+  for (const status of statuses) {
+    let pageToken: string | null | undefined;
+    do {
+      const response = await runForStatus(status, { authMode: options.authMode, limit: 100, nextToken: pageToken });
+      if (response.errors?.length) return { data: [], errors: response.errors };
+      rows.push(...((response.data ?? []).filter(Boolean) as T[]));
+      pageToken = response.nextToken;
+    } while (pageToken);
+  }
+  const direction = options.sortDirection === "DESC" ? -1 : 1;
+  rows.sort((left, right) => direction * sortValue(left).localeCompare(sortValue(right)));
+  const offset = Number(options.nextToken ?? 0) || 0;
+  const limit = typeof options.limit === "number" ? options.limit : undefined;
+  const end = limit === undefined ? rows.length : offset + limit;
+  return {
+    data: rows.slice(offset, end),
+    nextToken: end < rows.length ? String(end) : undefined,
+  };
+}
+
+function getPublishedEditionModel(): EditionSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.Edition;
+    if (!model) throw missingProjectionModelError("Edition");
+    return {
+      publishedEditionBySlug: (input, options) => model.editionBySlug(input, options) as ListResponse<GraphQLEdition>,
+      listPublishedEditionsByStatusAndEditionDate: (input, options) =>
+        listMergedAcrossStatuses<GraphQLEdition>(
+          DRAFTS_EDITION_STATUSES,
+          (status, pageOptions) =>
+            model.listEditionsByStatusAndEditionDate({ ...input, status }, pageOptions) as ListResponse<GraphQLEdition>,
+          (edition) => edition.editionDate,
+          options,
+        ),
+    };
+  }
   const model = getClient().models.PublishedEdition;
   if (!model) throw missingProjectionModelError("PublishedEdition");
-  return model;
+  return model as unknown as EditionSourceModel;
 }
 
-function getPublishedEditionItemModel() {
+function getPublishedEditionItemModel(): EditionItemSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.EditionItem;
+    if (!model) throw missingProjectionModelError("EditionItem");
+    return {
+      listPublishedEditionItemsByEditionAndSortKey: async ({ publishedEditionId }, options) => {
+        const response = (await model.listEditionItemsByEditionAndSortKey(
+          { editionId: publishedEditionId },
+          options,
+        )) as unknown as GraphQLListResponse<{ id: string; editionId: string; itemId: string; sortKey: string }>;
+        return {
+          ...response,
+          data: (response.data ?? []).filter(Boolean).map((row) => ({
+            id: row.id,
+            publishedEditionId: row.editionId,
+            publishedItemId: row.itemId,
+            sortKey: row.sortKey,
+          })),
+        };
+      },
+    };
+  }
   const model = getClient().models.PublishedEditionItem;
   if (!model) throw missingProjectionModelError("PublishedEditionItem");
-  return model;
+  return model as unknown as EditionItemSourceModel;
 }
 
-function getPublishedItemModel() {
+function getPublishedItemModel(): ItemSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.Item;
+    if (!model) throw missingProjectionModelError("Item");
+    return {
+      get: (input, options) => model.get(input, options) as Promise<GraphQLGetResponse<GraphQLItem>>,
+      publishedItemBySlug: (input, options) => model.itemBySlug(input, options) as ListResponse<GraphQLItem>,
+      listPublishedItemsByTypeStatusAndPublishedAt: ({ typeStatus }, options) => {
+        const itemType = typeStatus.split("#")[0];
+        return listMergedAcrossStatuses<GraphQLItem>(
+          [DRAFT_STATUS, PUBLISHED_STATUS],
+          (status, pageOptions) =>
+            model.listItemsByTypeStatusAndPublishedAt(
+              { typeStatus: `${itemType}#${status}` },
+              pageOptions,
+            ) as ListResponse<GraphQLItem>,
+          (item) => item.publishedAt ?? "",
+          options,
+        );
+      },
+    };
+  }
   const model = getClient().models.PublishedItem;
   if (!model) throw missingProjectionModelError("PublishedItem");
-  return model;
+  return model as unknown as ItemSourceModel;
 }
 
-function getPublishedMediaAssetModel() {
+function getPublishedMediaAssetModel(): MediaAssetSourceModel {
+  if (currentContentSource() === "drafts") {
+    const model = getClient().models.MediaAsset;
+    if (!model) throw missingProjectionModelError("MediaAsset");
+    return {
+      listPublishedMediaAssetsByItemAndSortKey: async ({ publishedItemId }, options) => {
+        const response = (await model.listMediaAssetsByItemAndSortKey(
+          { itemId: publishedItemId },
+          options,
+        )) as unknown as GraphQLListResponse<Omit<GraphQLMediaAsset, "publishedItemId"> & { itemId: string }>;
+        return {
+          ...response,
+          data: (response.data ?? []).filter(Boolean).map((row) => ({ ...row, publishedItemId: row.itemId })),
+        };
+      },
+    };
+  }
   const model = getClient().models.PublishedMediaAsset;
   if (!model) throw missingProjectionModelError("PublishedMediaAsset");
-  return model;
+  return model as unknown as MediaAssetSourceModel;
 }
 
 function missingProjectionModelError(modelName: string): Error {
@@ -561,7 +706,7 @@ async function listItemsByTypeStatus(typeStatus: string): Promise<GraphQLItem[]>
 }
 
 async function getItemById(id: string): Promise<GraphQLItem | null> {
-  const response = await getPublishedItemModel().get({ id }, { authMode: AUTH_MODE });
+  const response = await getPublishedItemModel().get({ id }, { authMode: authMode() });
   return readGetResponse<GraphQLItem>(response);
 }
 
@@ -583,7 +728,7 @@ async function listAll<T>(operation: (options: Record<string, unknown>) => Promi
 
   do {
     const response = await operation({
-      authMode: AUTH_MODE,
+      authMode: authMode(),
       limit: 100,
       nextToken,
     });
@@ -597,7 +742,7 @@ async function listAll<T>(operation: (options: Record<string, unknown>) => Promi
 
 async function listFirst<T>(operation: (options: Record<string, unknown>) => Promise<GraphQLListResponse<T>>): Promise<T[]> {
   const response = await operation({
-    authMode: AUTH_MODE,
+    authMode: authMode(),
     limit: 1,
     sortDirection: "DESC",
   });
@@ -611,7 +756,7 @@ async function listPage<T>(
   nextToken?: string | null,
 ): Promise<{ editions: T[]; nextToken?: string | null }> {
   const response = await operation({
-    authMode: AUTH_MODE,
+    authMode: authMode(),
     limit,
     nextToken,
     sortDirection: "DESC",

package/lib/site-brand.ts

@@ -34,6 +34,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;
@@ -76,6 +88,7 @@ export type SiteBrand = {
   publicationName: string;
   components?: SiteBrandComponents;
   demoEdition?: SiteBrandDemoEdition;
+  video?: SiteBrandVideo;
 };
 
 const SERIF_TEXT_FONT = 'Georgia, "Times New Roman", serif';

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

package/lib/video-script.ts

@@ -0,0 +1,63 @@
+export type VideoElementAliases = Record<string, string>;
+
+/**
+ * Rewrites generic VideoML element names in a stored script to the publication's
+ * own scene components, e.g. `{ "quote-card": "acme-quote-card" }`.
+ */
+export function normalizeDevPreviewDsl(dsl: string, elementAliases: VideoElementAliases = {}): string {
+  let normalized = dsl;
+  for (const [generic, branded] of Object.entries(elementAliases)) {
+    const escaped = generic.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    normalized = normalized.replace(new RegExp(`(</?)${escaped}(?=[\\s/>])`, "g"), `$1${branded}`);
+  }
+  return normalized;
+}
+
+export type VideoScriptTargetKind = "article" | "edition";
+
+export type VideoScriptRef = {
+  slug: string;
+  dsl: string;
+  targetKind: VideoScriptTargetKind;
+};
+
+export function videomlItemSlug(targetSlug: string): string {
+  return `${targetSlug}--videoml`;
+}
+
+export function parseVideoScriptRef(item: {
+  slug: string;
+  editorial?: unknown;
+}): VideoScriptRef | null {
+  const editorial = parseEditorial(item.editorial);
+  const videoScript = editorial?.videoScript;
+  if (!videoScript || typeof videoScript !== "object" || Array.isArray(videoScript)) return null;
+
+  const scriptRecord = videoScript as Record<string, unknown>;
+  const dsl = typeof scriptRecord.dsl === "string" ? scriptRecord.dsl.trim() : "";
+  if (!dsl) return null;
+
+  const target = scriptRecord.target;
+  const targetKind: VideoScriptTargetKind =
+    target && typeof target === "object" && !Array.isArray(target) && (target as Record<string, unknown>).kind === "edition"
+      ? "edition"
+      : "article";
+
+  return { slug: item.slug, dsl, targetKind };
+}
+
+function parseEditorial(editorial: unknown): Record<string, unknown> | null {
+  if (!editorial) return null;
+  if (typeof editorial === "string") {
+    try {
+      const parsed = JSON.parse(editorial) as unknown;
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+    } catch {
+      return null;
+    }
+  }
+  if (typeof editorial === "object" && !Array.isArray(editorial)) {
+    return editorial as Record<string, unknown>;
+  }
+  return null;
+}