@anthusai/papyrus 1.0.0-next.1 → 1.0.0-next.10

package/amplify/site-backend.js

@@ -12,12 +12,14 @@ import { CfnEventSourceMapping, FunctionUrlAuthType } from "aws-cdk-lib/aws-lamb
 import { CfnIndex, CfnVectorBucket, CfnVectorBucketPolicy } from "aws-cdk-lib/aws-s3vectors";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { rebuildTriggerSettings } from "./rebuild-trigger-settings.js";
 import { authConfigFromEnv, defineSiteAuth } from "./auth/resource.js";
 import { data } from "./data/resource.js";
 import { assignmentAction } from "./functions/assignment-action/resource.js";
 import { categoryAction } from "./functions/category-action/resource.js";
 import { ConsoleChatResponderStack } from "./functions/console-chat-responder/resource.js";
 import { graphqlJwtAuthorizer } from "./functions/graphql-jwt-authorizer/resource.js";
+import { contentActions } from "./functions/content-actions/resource.js";
 import { knowledgeQuery } from "./functions/knowledge-query/resource.js";
 import { manageUserRole } from "./functions/manage-user-role/resource.js";
 import { modelAttachmentUpload } from "./functions/model-attachment-upload/resource.js";
@@ -79,6 +81,7 @@ export function defineSiteBackend(papyrusSite) {
         assignmentAction,
         auth: defineSiteAuth(site.auth ?? authConfigFromEnv()),
         categoryAction,
+        contentActions,
         data,
         graphqlJwtAuthorizer,
         knowledgeQuery,
@@ -310,6 +313,7 @@ export function defineSiteBackend(papyrusSite) {
     for (const resource of [
         backend.assignmentAction,
         backend.categoryAction,
+        backend.contentActions,
         backend.emailSubmissionProcessor,
         backend.knowledgeQuery,
         backend.modelAttachmentUpload,
@@ -323,6 +327,30 @@ export function defineSiteBackend(papyrusSite) {
     grantNewsroomReadWrite(backend.assignmentAction.resources.lambda);
     grantNewsroomReadWrite(backend.categoryAction.resources.lambda);
     grantNewsroomReadWrite(backend.newsroomSummary.resources.lambda);
+    const contentActionsLambda = backend.contentActions.resources.lambda;
+    grantNewsroomReadWriteDelete(contentActionsLambda);
+    contentActionsLambda.addEnvironment("PAPYRUS_GRAPHQL_ENDPOINT", backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl);
+    contentActionsLambda.addToRolePolicy(new PolicyStatement({
+        actions: ["appsync:GraphQL"],
+        resources: ["*"],
+    }));
+    const rebuildSettings = rebuildTriggerSettings({
+        reader: site.reader,
+        stagingBuildEnabled: site.stagingBuild?.enabled === true,
+        cmsAppId: amplifyAppId,
+        region: Stack.of(contentActionsLambda).region,
+        account: Stack.of(contentActionsLambda).account,
+    });
+    for (const [name, value] of Object.entries(rebuildSettings.environment)) {
+        contentActionsLambda.addEnvironment(name, value);
+    }
+    if (rebuildSettings.resources.length > 0) {
+        contentActionsLambda.addToRolePolicy(new PolicyStatement({ actions: rebuildSettings.actions, resources: rebuildSettings.resources }));
+    }
+    if ((site.revalidateBaseUrl ?? "").trim() !== "") {
+        backend.contentActions.addEnvironment("PAPYRUS_REVALIDATE_BASE_URL", (site.revalidateBaseUrl ?? "").trim());
+        backend.contentActions.addEnvironment("PAPYRUS_REVALIDATE_SECRET", secret("PAPYRUS_REVALIDATE_SECRET"));
+    }
     grantNewsroomReadWriteDelete(backend.modelAttachmentUpload.resources.lambda);
     grantMediaReadWriteDelete(backend.modelAttachmentUpload.resources.lambda);
     if (backend.sesInboundReceive) {

package/amplify/site-backend.ts

@@ -13,12 +13,14 @@ import * as s3 from "aws-cdk-lib/aws-s3";
 import { CfnIndex, CfnVectorBucket, CfnVectorBucketPolicy } from "aws-cdk-lib/aws-s3vectors";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { rebuildTriggerSettings } from "./rebuild-trigger-settings";
 import { authConfigFromEnv, defineSiteAuth } from "./auth/resource";
 import { data } from "./data/resource";
 import { assignmentAction } from "./functions/assignment-action/resource";
 import { categoryAction } from "./functions/category-action/resource";
 import { ConsoleChatResponderStack } from "./functions/console-chat-responder/resource";
 import { graphqlJwtAuthorizer } from "./functions/graphql-jwt-authorizer/resource";
+import { contentActions } from "./functions/content-actions/resource";
 import { knowledgeQuery } from "./functions/knowledge-query/resource";
 import { manageUserRole } from "./functions/manage-user-role/resource";
 import { modelAttachmentUpload } from "./functions/model-attachment-upload/resource";
@@ -90,6 +92,7 @@ export function defineSiteBackend(papyrusSite: PapyrusSite) {
     assignmentAction,
     auth: defineSiteAuth(site.auth ?? authConfigFromEnv()),
     categoryAction,
+    contentActions,
     data,
     graphqlJwtAuthorizer,
     knowledgeQuery,
@@ -386,6 +389,7 @@ export function defineSiteBackend(papyrusSite: PapyrusSite) {
   for (const resource of [
     backend.assignmentAction,
     backend.categoryAction,
+    backend.contentActions,
     backend.emailSubmissionProcessor,
     backend.knowledgeQuery,
     backend.modelAttachmentUpload,
@@ -399,6 +403,37 @@ export function defineSiteBackend(papyrusSite: PapyrusSite) {
   grantNewsroomReadWrite(backend.assignmentAction.resources.lambda as LambdaFunction);
   grantNewsroomReadWrite(backend.categoryAction.resources.lambda as LambdaFunction);
   grantNewsroomReadWrite(backend.newsroomSummary.resources.lambda as LambdaFunction);
+  const contentActionsLambda = backend.contentActions.resources.lambda as LambdaFunction;
+  grantNewsroomReadWriteDelete(contentActionsLambda);
+  contentActionsLambda.addEnvironment(
+    "PAPYRUS_GRAPHQL_ENDPOINT",
+    backend.data.resources.cfnResources.cfnGraphqlApi.attrGraphQlUrl,
+  );
+  contentActionsLambda.addToRolePolicy(
+    new PolicyStatement({
+      actions: ["appsync:GraphQL"],
+      resources: ["*"],
+    }),
+  );
+  const rebuildSettings = rebuildTriggerSettings({
+    reader: site.reader,
+    stagingBuildEnabled: site.stagingBuild?.enabled === true,
+    cmsAppId: amplifyAppId,
+    region: Stack.of(contentActionsLambda).region,
+    account: Stack.of(contentActionsLambda).account,
+  });
+  for (const [name, value] of Object.entries(rebuildSettings.environment)) {
+    contentActionsLambda.addEnvironment(name, value);
+  }
+  if (rebuildSettings.resources.length > 0) {
+    contentActionsLambda.addToRolePolicy(
+      new PolicyStatement({ actions: rebuildSettings.actions, resources: rebuildSettings.resources }),
+    );
+  }
+  if ((site.revalidateBaseUrl ?? "").trim() !== "") {
+    backend.contentActions.addEnvironment("PAPYRUS_REVALIDATE_BASE_URL", (site.revalidateBaseUrl ?? "").trim());
+    backend.contentActions.addEnvironment("PAPYRUS_REVALIDATE_SECRET", secret("PAPYRUS_REVALIDATE_SECRET"));
+  }
   grantNewsroomReadWriteDelete(backend.modelAttachmentUpload.resources.lambda as LambdaFunction);
   grantMediaReadWriteDelete(backend.modelAttachmentUpload.resources.lambda as LambdaFunction);
   if (backend.sesInboundReceive) {

package/amplify/storage/resource.js

@@ -11,6 +11,9 @@ export const storage = defineStorage({
         "corpora/*": [
             allow.groups(["editor", "admin"]).to(["read"]),
         ],
+        "preview/*": [
+            allow.groups(["editor", "admin"]).to(["read"]),
+        ],
         "newsroom/*": [
             allow.groups(["editor", "admin"]).to(["read", "write", "delete"]),
         ],

package/amplify/storage/resource.ts

@@ -12,6 +12,9 @@ export const storage = defineStorage({
     "corpora/*": [
       allow.groups(["editor", "admin"]).to(["read"]),
     ],
+    "preview/*": [
+      allow.groups(["editor", "admin"]).to(["read"]),
+    ],
     "newsroom/*": [
       allow.groups(["editor", "admin"]).to(["read", "write", "delete"]),
     ],

package/app/%5F_preview/[[...path]]/route.ts

@@ -0,0 +1,8 @@
+import type { NextRequest } from "next/server";
+import { streamPreviewObject } from "../../../lib/staging-preview-object";
+
+export const dynamic = "force-dynamic";
+
+export async function GET(request: NextRequest): Promise<Response> {
+  return streamPreviewObject(request.nextUrl.pathname);
+}

package/app/[year]/[month]/[day]/[articleSlug]/page.tsx

@@ -52,8 +52,8 @@ export default async function DateScopedArticlePage({ params }: DateScopedArticl
       editionFooter={{
         editionBasePath,
         entries: buildPresentationFooterEntries(content),
-        subtitle: SITE_BRAND.id === "threat-intelligence" ? "" : (content.description?.trim() || "Inside Papyrus"),
-        title: SITE_BRAND.id === "threat-intelligence" ? "ANTHUS THREAT INTELLIGENCE" : undefined,
+        subtitle: SITE_BRAND.footerSubtitleOverride ?? (content.description?.trim() || "Inside Papyrus"),
+        title: SITE_BRAND.footerTitle,
       }}
       item={item}
       backHref={`${editionBasePath}#${item.slug}`}

package/app/globals.css

@@ -1,7 +1,4 @@
-@import "../publications/threat_intelligence/theme.css";
-@import "../publications/papyrus/theme.css";
-@import "../publications/pilobol_us/theme.css";
-@import "../publications/anth_us/theme.css";
+@import "./papyrus-theme.css";
 
 @import "tailwindcss";
 @import "tw-animate-css";
@@ -2285,6 +2282,25 @@ img {
   width: 100%;
 }
 
+.article-video__preview-frame {
+  aspect-ratio: 16 / 9;
+  background: #000;
+  border: 0;
+  display: block;
+  width: 100%;
+}
+
+.article-video__preview-controls {
+  align-items: center;
+  display: flex;
+  gap: 0.75rem;
+  margin-top: 0.5rem;
+}
+
+.article-video__preview-controls input[type="range"] {
+  flex: 1;
+}
+
 .article-video__credit {
   color: rgb(var(--ink-solid-rgb) / 0.62);
   font-size: 0.82rem;

package/app/layout.tsx

@@ -1,14 +1,16 @@
 import type { Metadata } from "next";
 import { Playfair_Display, Plus_Jakarta_Sans } from "next/font/google";
-import { cookies } from "next/headers";
 import Script from "next/script";
 import { AmplifyClientProvider } from "../components/amplify-client-provider";
 import { PapyrusConsoleShell } from "../components/papyrus-console-shell";
 import { TooltipProvider } from "../components/ui/tooltip";
-import { getPresentationChoices, getSiteBrand, resolveRuntimeSiteBrandId } from "../lib/site-brand";
+import { getPresentationChoices, getSiteBrand } from "../lib/site-brand";
 import { getSiteStack } from "../lib/site-stack";
+import { isIndexable, showStagingBanner } from "../lib/site-env";
+import { StagingBanner } from "../components/staging-banner";
 import "./tailwind.css";
 import "./globals.css";
+import "papyrus-site-theme";
 
 const playfairDisplay = Playfair_Display({
   subsets: ["latin"],
@@ -22,19 +24,12 @@ const plusJakartaSans = Plus_Jakarta_Sans({
 
 const faviconVersion = "20260517-1";
 const defaultTheme = "system";
-const BRAND_OVERRIDE_COOKIE = "papyrus-site-brand-override";
-
-async function resolveLayoutSiteBrand() {
-  const cookieStore = await cookies();
-  const brandId = resolveRuntimeSiteBrandId(cookieStore.get(BRAND_OVERRIDE_COOKIE)?.value ?? null);
-  return getSiteBrand(brandId);
-}
-
 export async function generateMetadata(): Promise<Metadata> {
-  const siteBrand = await resolveLayoutSiteBrand();
+  const siteBrand = getSiteBrand();
   return {
     title: siteBrand.appTitle,
     description: siteBrand.appDescription,
+    ...(isIndexable() ? {} : { robots: { index: false, follow: false } }),
     icons: {
       icon: [
         { url: `/icon-light.png?v=${faviconVersion}`, type: "image/png" },
@@ -45,7 +40,7 @@ export async function generateMetadata(): Promise<Metadata> {
 }
 
 export default async function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {
-  const siteBrand = await resolveLayoutSiteBrand();
+  const siteBrand = getSiteBrand();
   const presentationChoices = getPresentationChoices(siteBrand);
   const siteStack = getSiteStack(siteBrand);
 
@@ -135,6 +130,7 @@ export default async function RootLayout({ children }: Readonly<{ children: Reac
   window.addEventListener("papyrus:settings-changed", apply);
 })();`}
         </Script>
+        {showStagingBanner() ? <StagingBanner /> : null}
         <AmplifyClientProvider>
           <TooltipProvider>
             <PapyrusConsoleShell>{children}</PapyrusConsoleShell>

package/app/newsroom/articles/[id]/page.tsx

@@ -0,0 +1,15 @@
+import { NewsroomArticleEditor } from "../../../../components/newsroom-article-editor";
+
+export const dynamic = "force-dynamic";
+
+type NewsroomArticleEditorPageProps = {
+  params: Promise<{ id: string }>;
+  searchParams?: Promise<{ demo?: string | string[] }>;
+};
+
+export default async function NewsroomArticleEditorPage({ params, searchParams }: NewsroomArticleEditorPageProps) {
+  const { id } = await params;
+  const resolved = await searchParams;
+  const demoValue = Array.isArray(resolved?.demo) ? resolved?.demo[0] : resolved?.demo;
+  return <NewsroomArticleEditor articleId={decodeURIComponent(id)} demo={demoValue === "1"} />;
+}

package/app/newsroom/articles/page.tsx

@@ -0,0 +1,13 @@
+import { NewsroomArticlesView } from "../../../components/newsroom-articles-view";
+
+export const dynamic = "force-dynamic";
+
+type NewsroomArticlesPageProps = {
+  searchParams?: Promise<{ demo?: string | string[] }>;
+};
+
+export default async function NewsroomArticlesPage({ searchParams }: NewsroomArticlesPageProps) {
+  const resolved = await searchParams;
+  const demoValue = Array.isArray(resolved?.demo) ? resolved?.demo[0] : resolved?.demo;
+  return <NewsroomArticlesView demo={demoValue === "1"} />;
+}

package/app/robots.ts

@@ -0,0 +1,11 @@
+import type { MetadataRoute } from "next";
+import { isIndexable } from "../lib/site-env";
+
+export const dynamic = "force-dynamic";
+
+export default function robots(): MetadataRoute.Robots {
+  if (isIndexable()) {
+    return { rules: { userAgent: "*", allow: "/" } };
+  }
+  return { rules: { userAgent: "*", disallow: "/" } };
+}

package/bin/papyrus-app.mjs

@@ -1,10 +1,20 @@
 #!/usr/bin/env node
 import { sync } from "../src/sync.mjs";
 
-const [command] = process.argv.slice(2);
+const [command, ...rest] = process.argv.slice(2);
 if (command === "sync") {
   sync();
+} else if (command === "videoml-bundle") {
+  const preview = rest.includes("--preview");
+  const { buildBrowserBundle } = await import("../scripts/videoml/build-browser-bundle.mjs");
+  const { buildPreviewBundle } = await import("../scripts/videoml/build-preview-bundle.mjs");
+  try {
+    await (preview ? buildPreviewBundle() : buildBrowserBundle());
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
 } else {
-  console.error("Usage: papyrus-app sync");
+  console.error("Usage: papyrus-app sync | papyrus-app videoml-bundle [--preview]");
   process.exit(command ? 1 : 0);
 }

package/bin/papyrus-infra.mjs

@@ -1,39 +1,95 @@
 #!/usr/bin/env node
 /**
- * papyrus-infra synth --site infra/site.json [--out cdk.out]
- * Synthesizes the app-shell stack for a publication from its own site.json
- * (SPIKE, PPY-82be6c). Synth only: deploying is a separate, reviewed step.
+ * papyrus-infra synth --site infra/site.json [--out cdk.out] [--account A] [--region R]
+ * papyrus-infra synth --account-stack github-oidc [--out cdk.out] [--account A] [--region R]
+ * papyrus-infra print-buildspec --site infra/site.json --app cms-production|cms-staging|reader
+ * Synthesizes the app-shell stack for a publication from its own site.json, or
+ * prints one of the generated Amplify build specs. Synth only: deploying is a
+ * separate, reviewed step.
  */
 import fs from "node:fs";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { buildSpecFor } from "../infra/build-specs.js";
+import { parseSiteConfig, resolveStackName } from "../infra/site-config.js";
+
+const USAGE = [
+  "Usage: papyrus-infra synth --site infra/site.json [--out cdk.out] [--account A] [--region R]",
+  "       papyrus-infra synth --account-stack github-oidc [--out cdk.out] [--account A] [--region R]",
+  "       papyrus-infra print-buildspec --site infra/site.json --app cms-production|cms-staging|reader",
+].join("\n");
+
+const args = process.argv.slice(2);
+const opt = (name, fallback) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : fallback;
+};
+const command = args[0];
+if (command !== "synth" && command !== "print-buildspec") {
+  console.error(USAGE);
+  process.exit(command ? 1 : 0);
+}
+
+const accountStack = opt("account-stack");
+if (accountStack !== undefined) {
+  if (command !== "synth" || accountStack !== "github-oidc") {
+    console.error(USAGE);
+    process.exit(1);
+  }
+  let GithubOidcProviderStack;
+  try {
+    ({ GithubOidcProviderStack } = await import("../infra/index.js"));
+  } catch (error) {
+    console.error(`papyrus-infra: ${error instanceof Error ? error.message : error}`);
+    process.exit(1);
+  }
+  const { App } = createRequire(path.join(process.cwd(), "noop.js"))("aws-cdk-lib");
+  const app = new App({ outdir: path.resolve(opt("out", "cdk.out")) });
+  new GithubOidcProviderStack(app, "GithubOidcProviderStack", {
+    env: { account: opt("account", "335163751677"), region: opt("region", "us-east-1") },
+    stackName: "github-oidc-provider",
+  });
+  app.synth();
+  console.log(`synthesized github-oidc-provider -> ${path.resolve(opt("out", "cdk.out"))}`);
+  process.exit(0);
+}
+
+let config;
+try {
+  config = parseSiteConfig(JSON.parse(fs.readFileSync(path.resolve(opt("site", "infra/site.json")), "utf8")));
+} catch (error) {
+  console.error(`papyrus-infra: ${error instanceof Error ? error.message : error}`);
+  process.exit(1);
+}
+
+if (command === "print-buildspec") {
+  const app = opt("app");
+  if (!["cms-production", "cms-staging", "reader"].includes(app)) {
+    console.error(USAGE);
+    process.exit(1);
+  }
+  try {
+    process.stdout.write(buildSpecFor(config, app));
+  } catch (error) {
+    console.error(`papyrus-infra: ${error instanceof Error ? error.message : error}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
 
 let AmplifyAppShellStack;
 try {
   ({ AmplifyAppShellStack } = await import("../infra/index.js"));
 } catch (error) {
-  // infra/index.js explains the missing optional peers; print it without a stack trace.
   console.error(`papyrus-infra: ${error instanceof Error ? error.message : error}`);
   process.exit(1);
 }
 
-// aws-cdk-lib is an optional peer: resolve it from the publication's infra/ package (cwd).
 const { App } = createRequire(path.join(process.cwd(), "noop.js"))("aws-cdk-lib");
-
-const args = process.argv.slice(2);
-const opt = (name, fallback) => {
-  const i = args.indexOf(`--${name}`);
-  return i >= 0 ? args[i + 1] : fallback;
-};
-if (args[0] !== "synth") {
-  console.error("Usage: papyrus-infra synth --site infra/site.json [--out cdk.out]");
-  process.exit(args[0] ? 1 : 0);
-}
-const config = JSON.parse(fs.readFileSync(path.resolve(opt("site", "infra/site.json")), "utf8"));
 const app = new App({ outdir: path.resolve(opt("out", "cdk.out")) });
 new AmplifyAppShellStack(app, `AmplifyAppShell-${config.siteId}`, config, {
   env: { account: opt("account", "335163751677"), region: opt("region", "us-east-1") },
-  stackName: `amplify-app-shell-${config.siteId}`,
+  stackName: resolveStackName(config),
 });
 app.synth();
-console.log(`synthesized amplify-app-shell-${config.siteId} -> ${path.resolve(opt("out", "cdk.out"))}`);
+console.log(`synthesized ${resolveStackName(config)} -> ${path.resolve(opt("out", "cdk.out"))}`);

package/components/article-video.tsx

@@ -1,31 +1,140 @@
 "use client";
 
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useRef, useState } from "react";
 import type { ArticleVideoAsset } from "../lib/articles";
 import { resolveThemedVideoSrc } from "../lib/themed-image";
 import { useResolvedPapyrusTheme } from "./use-resolved-papyrus-theme";
+import { getSiteBrand } from "../lib/site-brand";
+import { normalizeDevPreviewDsl, type VideoScriptRef } from "../lib/video-script";
+import { resolveVideoMode, resolveVideoModeFromEnv, type VideoMode } from "../lib/video-mode";
 
 type ArticleVideoFigureProps = {
   video: ArticleVideoAsset;
   slug: string;
   figureClassName?: string;
   priority?: boolean;
+  videoScript?: VideoScriptRef | null;
 };
 
-export function ArticleVideoFigure({ video, slug, figureClassName = "article-photo article-video" }: ArticleVideoFigureProps) {
+const PREVIEW_STORAGE_PREFIX = "papyrus-video-preview:";
+
+export function ArticleVideoFigure({
+  video,
+  slug,
+  figureClassName = "article-photo article-video",
+  videoScript = null,
+}: ArticleVideoFigureProps) {
   const theme = useResolvedPapyrusTheme();
   const [hasHydrated, setHasHydrated] = useState(false);
+  const [videoMode, setVideoMode] = useState<VideoMode>(() => resolveVideoModeFromEnv());
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [duration, setDuration] = useState(0);
+  const [previewReady, setPreviewReady] = useState(false);
+  const iframeRef = useRef<HTMLIFrameElement>(null);
 
   useEffect(() => {
     setHasHydrated(true);
+    setVideoMode(resolveVideoMode());
   }, []);
 
   // Match SSR to the default dark MP4 in `video.src` until after hydration.
   const resolvedTheme = hasHydrated ? theme : "dark";
   const src = resolveThemedVideoSrc(video.src, video.themeVariants, resolvedTheme);
+  const usePreview = videoMode === "preview" && Boolean(videoScript?.dsl);
+  const previewDsl = videoScript?.dsl
+    ? normalizeDevPreviewDsl(videoScript.dsl, getSiteBrand().video?.sceneComponents)
+    : null;
+  const previewSrc = `/videoml/preview.html?target=${encodeURIComponent(slug)}&theme=${resolvedTheme}${
+    src ? `&audio=${encodeURIComponent(src)}` : ""
+  }`;
+
+  if (usePreview && previewDsl && typeof window !== "undefined") {
+    sessionStorage.setItem(`${PREVIEW_STORAGE_PREFIX}${slug}`, previewDsl);
+  }
+
+  useEffect(() => {
+    setPreviewReady(false);
+    setIsPlaying(false);
+    setCurrentTime(0);
+    setDuration(0);
+  }, [previewSrc, usePreview]);
+
+  useEffect(() => {
+    if (!usePreview || !previewReady) return;
+    iframeRef.current?.contentWindow?.postMessage(
+      { kind: "papyrus-video-refresh", target: slug, theme: resolvedTheme, audio: src || undefined },
+      "*",
+    );
+  }, [previewReady, resolvedTheme, slug, src, usePreview]);
+
+  useEffect(() => {
+    if (!usePreview) return;
+    const onMessage = (event: MessageEvent) => {
+      const payload = event.data;
+      if (!payload || typeof payload !== "object" || payload.kind !== "papyrus-video-time") return;
+      if (typeof payload.currentTime === "number") setCurrentTime(payload.currentTime);
+      if (typeof payload.duration === "number") setDuration(payload.duration);
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [usePreview]);
+
+  const togglePreviewPlayback = useCallback(() => {
+    iframeRef.current?.contentWindow?.postMessage({ kind: isPlaying ? "papyrus-video-pause" : "papyrus-video-play" }, "*");
+    setIsPlaying(!isPlaying);
+  }, [isPlaying]);
+
+  const seekPreview = useCallback((nextTime: number) => {
+    const clamped = Math.max(0, Number.isFinite(nextTime) ? nextTime : 0);
+    iframeRef.current?.contentWindow?.postMessage({ kind: "papyrus-video-seek", time: clamped }, "*");
+    setCurrentTime(clamped);
+  }, []);
+
+  if (usePreview) {
+    return (
+      <figure
+        className={`${figureClassName} article-video--preview`}
+        data-media-type="videoml-preview"
+        data-video-theme={resolvedTheme}
+        data-video-mode={videoMode}
+      >
+        {hasHydrated ? (
+          <iframe
+            key={`${slug}-${resolvedTheme}-${src}`}
+            ref={iframeRef}
+            className="article-video__preview-frame"
+            src={previewSrc}
+            title={video.alt}
+            onLoad={() => setPreviewReady(true)}
+          />
+        ) : null}
+        <div className="article-video__preview-controls">
+          <button type="button" onClick={togglePreviewPlayback} aria-pressed={isPlaying}>
+            {isPlaying ? "Pause video" : "Play video"}
+          </button>
+          <input
+            type="range"
+            min={0}
+            max={duration || 0}
+            step={0.1}
+            value={Math.min(currentTime, duration || 0)}
+            onChange={(event) => seekPreview(Number(event.target.value))}
+            aria-label="Seek video"
+            disabled={!duration}
+          />
+        </div>
+        {video.caption ? <figcaption>{video.caption}</figcaption> : null}
+        {video.credit ? <p className="article-video__credit">{video.credit}</p> : null}
+        <span className="sr-only" data-video-slug={slug}>
+          {video.alt}
+        </span>
+      </figure>
+    );
+  }
 
   return (
-    <figure className={figureClassName} data-media-type="video" data-video-theme={resolvedTheme}>
+    <figure className={figureClassName} data-media-type="video" data-video-theme={resolvedTheme} data-video-mode={videoMode}>
       <video
         controls
         playsInline