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

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

package/middleware.ts

@@ -3,6 +3,12 @@ import { NextResponse } from "next/server";
 import { getSiteBrand } from "./lib/site-brand";
 import { getSiteEnv, isIndexable } from "./lib/site-env";
 import { getStagingAccess } from "./lib/staging-gate";
+import {
+  isPreviewGatedPath,
+  isStaticPreviewEnabled,
+  previewRewritePathname,
+  shouldRewriteToPreview,
+} from "./lib/staging-preview-object";
 
 function usesNewsroomRootPaths(): boolean {
   const brand = getSiteBrand();
@@ -27,6 +33,11 @@ function isStagingGatedPath(pathname: string): boolean {
 }
 
 function routeRequest(request: NextRequest): NextResponse {
+  if (isStaticPreviewEnabled() && shouldRewriteToPreview(request.nextUrl.pathname)) {
+    const rewriteUrl = request.nextUrl.clone();
+    rewriteUrl.pathname = previewRewritePathname(request.nextUrl.pathname);
+    return NextResponse.rewrite(rewriteUrl);
+  }
   if (!usesNewsroomRootPaths()) {
     return NextResponse.next();
   }
@@ -59,7 +70,9 @@ function routeRequest(request: NextRequest): NextResponse {
 
 export async function middleware(request: NextRequest): Promise<NextResponse> {
   let sessionResponse: NextResponse | null = null;
-  if (getSiteEnv() === "staging" && isStagingGatedPath(request.nextUrl.pathname)) {
+  const { pathname } = request.nextUrl;
+  const gated = isStaticPreviewEnabled() ? isPreviewGatedPath(pathname) : isStagingGatedPath(pathname);
+  if (getSiteEnv() === "staging" && gated) {
     sessionResponse = NextResponse.next();
     const access = await getStagingAccess(request, sessionResponse);
     if (access === "anonymous") {

package/package.json

@@ -187,14 +187,18 @@
     "./lib/site-renderer": "./lib/site-renderer.ts",
     "./lib/site-stack": "./lib/site-stack.ts",
     "./lib/staging-gate": "./lib/staging-gate.ts",
+    "./lib/staging-preview-object": "./lib/staging-preview-object.ts",
     "./lib/themed-image": "./lib/themed-image.ts",
     "./lib/utils": "./lib/utils.ts",
+    "./lib/video-mode": "./lib/video-mode.ts",
+    "./lib/video-script": "./lib/video-script.ts",
     "./renderers/markus/index": "./renderers/markus/index.ts",
     "./renderers/markus/stubs": "./renderers/markus/stubs.tsx",
     "./renderers/pretext/article-page": "./renderers/pretext/article-page.tsx",
     "./renderers/pretext/index": "./renderers/pretext/index.ts",
     "./renderers/pretext/layouts": "./renderers/pretext/layouts.ts",
     "./renderers/pretext/presentation-shell": "./renderers/pretext/presentation-shell.tsx",
+    "./app/%5F_preview/[[...path]]/route": "./app/%5F_preview/[[...path]]/route.ts",
     "./app/[year]/[month]/[day]/[articleSlug]/page": "./app/[year]/[month]/[day]/[articleSlug]/page.tsx",
     "./app/[year]/[month]/[day]/page": "./app/[year]/[month]/[day]/page.tsx",
     "./app/[year]/[month]/[day]/page/[pageNumber]/page": "./app/[year]/[month]/[day]/page/[pageNumber]/page.tsx",
@@ -261,7 +265,7 @@
       "optional": true
     }
   },
-  "version": "1.0.0-next.4",
+  "version": "1.0.0-next.5",
   "dependencies": {
     "@aws-amplify/adapter-nextjs": "^1.7.3",
     "@aws-sdk/client-cognito-identity-provider": "3.1045.0",
@@ -283,6 +287,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
+    "esbuild": "^0.28.2",
     "gray-matter": "^4.0.3",
     "gsap": "^3.15.0",
     "katex": "^0.17.0",
@@ -293,6 +298,7 @@
     "streamdown": "^2.5.0",
     "tailwind-merge": "^3.6.0",
     "tailwindcss": "^4.3.0",
+    "tsx": "^4.23.15",
     "tw-animate-css": "^1.4.0",
     "use-stick-to-bottom": "^1.1.4",
     "yaml": "^2.9.0",

package/routes.manifest.json

@@ -1,6 +1,16 @@
 {
-  "version": "1.0.0-next.4",
+  "version": "1.0.0-next.5",
   "routes": [
+    {
+      "file": "app/%5F_preview/[[...path]]/route.ts",
+      "hasDefault": false,
+      "exports": [
+        "GET"
+      ],
+      "config": {
+        "dynamic": "\"force-dynamic\""
+      }
+    },
     {
       "file": "app/[year]/[month]/[day]/[articleSlug]/page.tsx",
       "hasDefault": true,

package/scripts/videoml/build-browser-bundle.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { bundleVideoEntries, loadBrandVideoSlot, standardEntryPath } from "./bundle-common.mjs";
+
+export async function buildBrowserBundle(projectRoot = process.cwd(), env = process.env) {
+  const { brandId, bundleEntry } = await loadBrandVideoSlot(projectRoot, env);
+  const result = await bundleVideoEntries({
+    projectRoot,
+    entries: [standardEntryPath, bundleEntry],
+    outfile: path.join(projectRoot, "public/videoml/browser-bundle.js"),
+  });
+  console.error(`VideoML browser bundle for '${brandId}': ${result.outfile} (${result.size} bytes)`);
+  return result;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  buildBrowserBundle().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

package/scripts/videoml/build-preview-bundle.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  bundleVideoEntries,
+  loadBrandVideoSlot,
+  previewEntryPath,
+  previewHtmlTemplatePath,
+  standardEntryPath,
+} from "./bundle-common.mjs";
+
+const REACT_18_VERSION = "18.3.1";
+const VENDOR_FILES = {
+  "react.production.min.js": `https://unpkg.com/react@${REACT_18_VERSION}/umd/react.production.min.js`,
+  "react-dom.production.min.js": `https://unpkg.com/react-dom@${REACT_18_VERSION}/umd/react-dom.production.min.js`,
+};
+
+async function ensureReactVendor(outDirectory) {
+  const vendorDirectory = path.join(outDirectory, "vendor");
+  fs.mkdirSync(vendorDirectory, { recursive: true });
+  for (const [name, url] of Object.entries(VENDOR_FILES)) {
+    const target = path.join(vendorDirectory, name);
+    if (fs.existsSync(target)) continue;
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`Failed to download ${url}: ${response.status} ${response.statusText}`);
+    fs.writeFileSync(target, Buffer.from(await response.arrayBuffer()));
+  }
+}
+
+export async function buildPreviewBundle(projectRoot = process.cwd(), env = process.env) {
+  const { brandId, bundleEntry } = await loadBrandVideoSlot(projectRoot, env);
+  const outDirectory = path.join(projectRoot, "public/videoml");
+  await ensureReactVendor(outDirectory);
+  fs.copyFileSync(previewHtmlTemplatePath, path.join(outDirectory, "preview.html"));
+  const result = await bundleVideoEntries({
+    projectRoot,
+    entries: [standardEntryPath, previewEntryPath, bundleEntry],
+    outfile: path.join(outDirectory, "preview-bundle.js"),
+  });
+  console.error(`VideoML preview bundle for '${brandId}': ${result.outfile} (${result.size} bytes)`);
+  return result;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  buildPreviewBundle().catch((error) => {
+    console.error(error.message);
+    process.exit(1);
+  });
+}

package/scripts/videoml/bundle-common.mjs

@@ -0,0 +1,129 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+const scriptsDirectory = path.dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+const OPTIONAL_DYNAMIC_IMPORTS_OF_VIDEOML = ["p5", "lottie-web", "animejs"];
+
+const REACT_GLOBALS_JSX_RUNTIME = `
+var React = window.React;
+function jsx(type, config, maybeKey) {
+  var props = config || {};
+  var key = maybeKey !== undefined ? maybeKey : props.key;
+  if (key !== undefined) {
+    props = Object.assign({}, props, { key: key });
+  }
+  return React.createElement(type, props);
+}
+exports.Fragment = React.Fragment;
+exports.jsx = jsx;
+exports.jsxs = jsx;
+`;
+
+const reactGlobalsPlugin = {
+  name: "react-globals",
+  setup(build) {
+    const globals = {
+      react: "module.exports = window.React",
+      "react-dom": "module.exports = window.ReactDOM",
+      "react-dom/client": "module.exports = window.ReactDOM",
+      "react/jsx-runtime": REACT_GLOBALS_JSX_RUNTIME,
+      "react/jsx-dev-runtime": REACT_GLOBALS_JSX_RUNTIME,
+    };
+    build.onResolve({ filter: /^react(-dom)?(\/.*)?$/ }, (args) =>
+      args.path in globals ? { path: args.path, namespace: "react-globals" } : undefined,
+    );
+    build.onLoad({ filter: /.*/, namespace: "react-globals" }, (args) => ({
+      contents: globals[args.path],
+      loader: "js",
+    }));
+  },
+};
+
+export function resolveSelectedBrandId(site, env) {
+  const requested = (env.PAPYRUS_SITE_BRAND ?? "").trim();
+  return requested || site.defaultBrand || "papyrus";
+}
+
+/**
+ * Loads the publication's `papyrus.config.ts` from the project root and returns the
+ * selected brand's `video` slot. Fails with a message naming the missing piece.
+ */
+export async function loadBrandVideoSlot(projectRoot, env = process.env) {
+  const configPath = path.join(projectRoot, "papyrus.config.ts");
+  if (!fs.existsSync(configPath)) {
+    throw new Error(`No papyrus.config.ts in ${projectRoot}. Run the VideoML bundle builder from the publication root.`);
+  }
+  const { tsImport } = await import("tsx/esm/api");
+  // Inside a Papyrus checkout, brand components import lib/site-brand, which imports this
+  // config: load site-brand first so the cycle resolves in the same order as in the app.
+  const checkoutSiteBrand = path.join(projectRoot, "lib/site-brand.ts");
+  if (fs.existsSync(checkoutSiteBrand)) await tsImport(pathToFileURL(checkoutSiteBrand).href, import.meta.url);
+  const loaded = await tsImport(pathToFileURL(configPath).href, import.meta.url);
+  const exported = loaded.default ?? loaded;
+  const site = exported.brands === undefined && exported.default ? exported.default : exported;
+  const brandId = resolveSelectedBrandId(site, env);
+  const brand = (site.brands ?? []).find((candidate) => candidate.id === brandId);
+  if (!brand) {
+    const registered = (site.brands ?? []).map((candidate) => candidate.id).join(", ") || "none";
+    throw new Error(`Brand '${brandId}' is not registered in papyrus.config.ts (registered: ${registered}).`);
+  }
+  if (!brand.video || typeof brand.video.bundleEntry !== "string" || !brand.video.bundleEntry) {
+    throw new Error(
+      `Brand '${brandId}' has no brand.video.bundleEntry in papyrus.config.ts. ` +
+        "Set brand.video = { bundleEntry: \"<path to a TSX module that registers the brand's VideoML scene components>\" }.",
+    );
+  }
+  const bundleEntry = path.resolve(projectRoot, brand.video.bundleEntry);
+  if (!fs.existsSync(bundleEntry)) {
+    throw new Error(`brand.video.bundleEntry for '${brandId}' does not exist: ${bundleEntry}`);
+  }
+  return { brandId, bundleEntry, video: brand.video };
+}
+
+function resolveEsbuild(projectRoot) {
+  for (const base of [projectRoot, scriptsDirectory]) {
+    try {
+      return require(require.resolve("esbuild", { paths: [base] }));
+    } catch {
+      continue;
+    }
+  }
+  throw new Error("esbuild not found. Install it in the publication (npm install --save-dev esbuild).");
+}
+
+/**
+ * Bundles [standard entry, optional extra entries, brand entry] into one IIFE.
+ * React comes from `window.React` / `window.ReactDOM` (the render shell loads React 18 UMD).
+ */
+export async function bundleVideoEntries({ projectRoot, entries, outfile }) {
+  const esbuild = resolveEsbuild(projectRoot);
+  fs.mkdirSync(path.dirname(outfile), { recursive: true });
+  const importLines = entries.map((entry) => `import ${JSON.stringify(entry)};`).join("\n");
+  await esbuild.build({
+    stdin: { contents: importLines, resolveDir: projectRoot, sourcefile: "papyrus-videoml-entry.ts", loader: "ts" },
+    bundle: true,
+    format: "iife",
+    platform: "browser",
+    jsx: "automatic",
+    outfile,
+    absWorkingDir: projectRoot,
+    nodePaths: [path.join(projectRoot, "node_modules")],
+    external: OPTIONAL_DYNAMIC_IMPORTS_OF_VIDEOML,
+    plugins: [reactGlobalsPlugin],
+    loader: { ".tsx": "tsx", ".ts": "ts" },
+    define: { "process.env.NODE_ENV": '"production"' },
+    sourcemap: true,
+    logLevel: "warning",
+  });
+  const size = fs.statSync(outfile).size;
+  if (size === 0) throw new Error(`VideoML bundle is empty: ${outfile}`);
+  return { outfile, size };
+}
+
+export const standardEntryPath = path.join(scriptsDirectory, "standard-entry.tsx");
+export const previewEntryPath = path.join(scriptsDirectory, "preview/preview-entry.tsx");
+export const previewHtmlTemplatePath = path.join(scriptsDirectory, "preview.html");