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

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/globals.css

@@ -2282,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/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,6 +1,7 @@
 #!/usr/bin/env node
 /**
  * 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
@@ -14,6 +15,7 @@ import { parseSiteConfig } 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");
 
@@ -28,6 +30,30 @@ if (command !== "synth" && command !== "print-buildspec") {
   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")));

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

package/infra/amplify-app-shell.js

@@ -1,6 +1,7 @@
-import { ArnFormat, CfnOutput, Stack } from "aws-cdk-lib";
+import { ArnFormat, CfnOutput, Duration, Stack } from "aws-cdk-lib";
 import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
+import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider.js";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs.js";
 import { resolveStagingDomainName } from "./site-config.js";
 function environmentVariables(variables) {
@@ -100,6 +101,60 @@ export class AmplifyAppShellStack extends Stack {
         if (config.reader) {
             this.readerAppId = this.addReaderApp(config, config.reader, cmsApp.attrAppId);
         }
+        if (config.github) {
+            this.addGithubCiRole(config, config.github, [cmsApp.attrAppId, ...(this.readerAppId ? [this.readerAppId] : [])]);
+        }
+    }
+    addGithubCiRole(config, github, amplifyAppIds) {
+        const provider = iam.OpenIdConnectProvider.fromOpenIdConnectProviderArn(this, "GithubOidcProvider", this.formatArn({
+            service: "iam",
+            region: "",
+            resource: "oidc-provider",
+            resourceName: GITHUB_OIDC_PROVIDER_HOST,
+            arnFormat: ArnFormat.SLASH_RESOURCE_NAME,
+        }));
+        const ciRole = new iam.Role(this, "GithubCiRole", {
+            roleName: `${config.siteId}-github-ci`,
+            description: `GitHub Actions role for ${github.owner}/${github.repo} (OIDC, least privilege, no admin policy)`,
+            maxSessionDuration: Duration.hours(1),
+            assumedBy: new iam.OpenIdConnectPrincipal(provider, {
+                StringEquals: { [`${GITHUB_OIDC_PROVIDER_HOST}:aud`]: "sts.amazonaws.com" },
+                StringLike: {
+                    [`${GITHUB_OIDC_PROVIDER_HOST}:sub`]: github.branches.map((branch) => `repo:${github.owner}/${github.repo}:ref:refs/heads/${branch}`),
+                },
+            }),
+        });
+        ciRole.addToPolicy(new iam.PolicyStatement({
+            sid: "StartAndInspectAmplifyJobs",
+            actions: ["amplify:StartJob", "amplify:ListJobs", "amplify:GetJob", "amplify:ListBranches"],
+            resources: amplifyAppIds.flatMap((appId) => [
+                this.formatArn({ service: "amplify", resource: "apps", resourceName: appId, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+                this.formatArn({ service: "amplify", resource: "apps", resourceName: `${appId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+            ]),
+        }));
+        ciRole.addToPolicy(new iam.PolicyStatement({
+            sid: "ReadSiteSecretsForJwtMinting",
+            actions: ["ssm:GetParameter", "ssm:GetParameters"],
+            resources: [
+                this.formatArn({ service: "ssm", resource: "parameter", resourceName: `amplify/${this.cmsAppId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+                this.formatArn({ service: "ssm", resource: "parameter", resourceName: `amplify/shared/${this.cmsAppId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+            ],
+        }));
+        ciRole.addToPolicy(new iam.PolicyStatement({
+            sid: "WhoAmI",
+            actions: ["sts:GetCallerIdentity"],
+            resources: ["*"],
+        }));
+        if (github.ciCanDeployInfra) {
+            ciRole.addToPolicy(new iam.PolicyStatement({
+                sid: "DeployThisSitesAppShellStack",
+                actions: ["cloudformation:*"],
+                resources: [
+                    this.formatArn({ service: "cloudformation", resource: "stack", resourceName: `amplify-app-shell-${config.siteId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+                ],
+            }));
+        }
+        new CfnOutput(this, "GithubCiRoleArn", { value: ciRole.roleArn, description: `Role for GitHub Actions in ${github.owner}/${github.repo}` });
     }
     addReaderApp(config, reader, cmsAppId) {
         const readerAppName = reader.appName ?? `${config.siteId}-reader`;

package/infra/amplify-app-shell.ts

@@ -1,7 +1,8 @@
 import { Construct } from "constructs";
-import { ArnFormat, CfnOutput, Stack, StackProps } from "aws-cdk-lib";
+import { ArnFormat, CfnOutput, Duration, Stack, StackProps } from "aws-cdk-lib";
 import * as iam from "aws-cdk-lib/aws-iam";
 import * as amplify from "aws-cdk-lib/aws-amplify";
+import { GITHUB_OIDC_PROVIDER_HOST } from "./github-oidc-provider";
 import { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec } from "./build-specs";
 import { AmplifyAppShellSiteConfig, resolveStagingDomainName } from "./site-config";
 
@@ -115,6 +116,83 @@ export class AmplifyAppShellStack extends Stack {
     if (config.reader) {
       this.readerAppId = this.addReaderApp(config, config.reader, cmsApp.attrAppId);
     }
+
+    if (config.github) {
+      this.addGithubCiRole(config, config.github, [cmsApp.attrAppId, ...(this.readerAppId ? [this.readerAppId] : [])]);
+    }
+  }
+
+  private addGithubCiRole(
+    config: AmplifyAppShellSiteConfig,
+    github: NonNullable<AmplifyAppShellSiteConfig["github"]>,
+    amplifyAppIds: string[],
+  ): void {
+    const provider = iam.OpenIdConnectProvider.fromOpenIdConnectProviderArn(
+      this,
+      "GithubOidcProvider",
+      this.formatArn({
+        service: "iam",
+        region: "",
+        resource: "oidc-provider",
+        resourceName: GITHUB_OIDC_PROVIDER_HOST,
+        arnFormat: ArnFormat.SLASH_RESOURCE_NAME,
+      }),
+    );
+
+    const ciRole = new iam.Role(this, "GithubCiRole", {
+      roleName: `${config.siteId}-github-ci`,
+      description: `GitHub Actions role for ${github.owner}/${github.repo} (OIDC, least privilege, no admin policy)`,
+      maxSessionDuration: Duration.hours(1),
+      assumedBy: new iam.OpenIdConnectPrincipal(provider, {
+        StringEquals: { [`${GITHUB_OIDC_PROVIDER_HOST}:aud`]: "sts.amazonaws.com" },
+        StringLike: {
+          [`${GITHUB_OIDC_PROVIDER_HOST}:sub`]: github.branches.map(
+            (branch) => `repo:${github.owner}/${github.repo}:ref:refs/heads/${branch}`,
+          ),
+        },
+      }),
+    });
+
+    ciRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "StartAndInspectAmplifyJobs",
+        actions: ["amplify:StartJob", "amplify:ListJobs", "amplify:GetJob", "amplify:ListBranches"],
+        resources: amplifyAppIds.flatMap((appId) => [
+          this.formatArn({ service: "amplify", resource: "apps", resourceName: appId, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+          this.formatArn({ service: "amplify", resource: "apps", resourceName: `${appId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+        ]),
+      }),
+    );
+    ciRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "ReadSiteSecretsForJwtMinting",
+        actions: ["ssm:GetParameter", "ssm:GetParameters"],
+        resources: [
+          this.formatArn({ service: "ssm", resource: "parameter", resourceName: `amplify/${this.cmsAppId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+          this.formatArn({ service: "ssm", resource: "parameter", resourceName: `amplify/shared/${this.cmsAppId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+        ],
+      }),
+    );
+    ciRole.addToPolicy(
+      new iam.PolicyStatement({
+        sid: "WhoAmI",
+        actions: ["sts:GetCallerIdentity"],
+        resources: ["*"],
+      }),
+    );
+    if (github.ciCanDeployInfra) {
+      ciRole.addToPolicy(
+        new iam.PolicyStatement({
+          sid: "DeployThisSitesAppShellStack",
+          actions: ["cloudformation:*"],
+          resources: [
+            this.formatArn({ service: "cloudformation", resource: "stack", resourceName: `amplify-app-shell-${config.siteId}/*`, arnFormat: ArnFormat.SLASH_RESOURCE_NAME }),
+          ],
+        }),
+      );
+    }
+
+    new CfnOutput(this, "GithubCiRoleArn", { value: ciRole.roleArn, description: `Role for GitHub Actions in ${github.owner}/${github.repo}` });
   }
 
   private addReaderApp(

package/infra/github-oidc-provider.js

@@ -0,0 +1,24 @@
+import { CfnOutput, Stack } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+export const GITHUB_OIDC_PROVIDER_HOST = "token.actions.githubusercontent.com";
+/**
+ * Account-global singleton: AWS allows one IAM OIDC provider per issuer URL per
+ * account, so this never belongs in a per-site stack. Deploy it once per
+ * account, and only after `aws iam list-open-id-connect-providers` shows no
+ * provider for token.actions.githubusercontent.com. When one already exists,
+ * do not deploy this stack: per-site CI roles only reference the provider by
+ * its ARN (arn:aws:iam::<account>:oidc-provider/token.actions.githubusercontent.com)
+ * and work against an existing provider unchanged.
+ */
+export class GithubOidcProviderStack extends Stack {
+    providerArn;
+    constructor(scope, id, props) {
+        super(scope, id, props);
+        const provider = new iam.OpenIdConnectProvider(this, "GithubOidc", {
+            url: `https://${GITHUB_OIDC_PROVIDER_HOST}`,
+            clientIds: ["sts.amazonaws.com"],
+        });
+        this.providerArn = provider.openIdConnectProviderArn;
+        new CfnOutput(this, "GithubOidcProviderArn", { value: provider.openIdConnectProviderArn });
+    }
+}

package/infra/github-oidc-provider.ts

@@ -0,0 +1,30 @@
+import { Construct } from "constructs";
+import { CfnOutput, Stack, StackProps } from "aws-cdk-lib";
+import * as iam from "aws-cdk-lib/aws-iam";
+
+export const GITHUB_OIDC_PROVIDER_HOST = "token.actions.githubusercontent.com";
+
+/**
+ * Account-global singleton: AWS allows one IAM OIDC provider per issuer URL per
+ * account, so this never belongs in a per-site stack. Deploy it once per
+ * account, and only after `aws iam list-open-id-connect-providers` shows no
+ * provider for token.actions.githubusercontent.com. When one already exists,
+ * do not deploy this stack: per-site CI roles only reference the provider by
+ * its ARN (arn:aws:iam::<account>:oidc-provider/token.actions.githubusercontent.com)
+ * and work against an existing provider unchanged.
+ */
+export class GithubOidcProviderStack extends Stack {
+  public readonly providerArn: string;
+
+  constructor(scope: Construct, id: string, props?: StackProps) {
+    super(scope, id, props);
+
+    const provider = new iam.OpenIdConnectProvider(this, "GithubOidc", {
+      url: `https://${GITHUB_OIDC_PROVIDER_HOST}`,
+      clientIds: ["sts.amazonaws.com"],
+    });
+
+    this.providerArn = provider.openIdConnectProviderArn;
+    new CfnOutput(this, "GithubOidcProviderArn", { value: provider.openIdConnectProviderArn });
+  }
+}

package/infra/index.js

@@ -10,5 +10,6 @@ try {
   );
 }
 export const { AmplifyAppShellStack } = await import("./amplify-app-shell.js");
+export const { GithubOidcProviderStack } = await import("./github-oidc-provider.js");
 export { parseSiteConfig } from "./site-config.js";
 export { cmsProductionBuildSpec, cmsStagingBuildSpec, readerBuildSpec, buildSpecFor } from "./build-specs.js";

package/infra/site-config.js

@@ -1,3 +1,4 @@
+export const DEFAULT_CI_BRANCHES = ["main", "staging"];
 const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
@@ -5,6 +6,8 @@ const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
 const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
+const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const LOCAL_DEVELOPMENT_ORIGIN = "http://localhost:3001/";
 function fail(field, problem) {
     throw new Error(`site.json: ${field} ${problem}`);
@@ -54,7 +57,7 @@ export function resolveStoragePreviewPrefix(config) {
 }
 export function parseSiteConfig(raw) {
     const record = requireObject(raw, "site");
-    rejectUnknownKeys(record, ["siteId", "repository", "brand", "frontend", "hostedZoneId", "cms", "reader", "papyrusVersion", "storagePreviewPrefix"], "site");
+    rejectUnknownKeys(record, ["siteId", "repository", "brand", "frontend", "hostedZoneId", "cms", "reader", "papyrusVersion", "storagePreviewPrefix", "github"], "site");
     const siteId = requireString(record.siteId, "siteId", SITE_ID_PATTERN, "kebab-case");
     const repository = requireString(record.repository, "repository", REPOSITORY_PATTERN, "https://github.com/<org>/<repo>");
     const brand = requireString(record.brand, "brand");
@@ -96,6 +99,32 @@ export function parseSiteConfig(raw) {
     else if (frontend === "markus-static") {
         fail("reader", `is required when frontend is "markus-static"`);
     }
+    let github;
+    if (record.github !== undefined) {
+        const githubRecord = requireObject(record.github, "github");
+        rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra"], "github");
+        const owner = requireString(githubRecord.owner, "github.owner", GITHUB_OWNER_PATTERN, "plain GitHub login");
+        const repo = requireString(githubRecord.repo, "github.repo", GITHUB_REPO_PATTERN);
+        if (repository !== `https://github.com/${owner}/${repo}`) {
+            fail("github", `owner/repo must match repository ${repository}`);
+        }
+        let branches = DEFAULT_CI_BRANCHES;
+        if (githubRecord.branches !== undefined) {
+            if (!Array.isArray(githubRecord.branches) || githubRecord.branches.length === 0) {
+                fail("github.branches", "must be a non-empty array of branch names");
+            }
+            branches = githubRecord.branches.map((branch, index) => {
+                if (typeof branch === "string" && /[*?]/.test(branch)) {
+                    fail(`github.branches[${index}]`, `must not contain wildcards: ${JSON.stringify(branch)}`);
+                }
+                return requireString(branch, `github.branches[${index}]`, BRANCH_NAME_PATTERN);
+            });
+        }
+        const ciCanDeployInfra = githubRecord.ciCanDeployInfra ?? false;
+        if (typeof ciCanDeployInfra !== "boolean")
+            fail("github.ciCanDeployInfra", "must be a boolean");
+        github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra };
+    }
     const config = {
         siteId,
         repository,
@@ -106,6 +135,7 @@ export function parseSiteConfig(raw) {
         reader,
         papyrusVersion,
         storagePreviewPrefix,
+        github,
     };
     const redirectValue = cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS;
     if (redirectValue === undefined)

package/infra/site-config.ts

@@ -21,8 +21,16 @@ export type AmplifyAppShellSiteConfig = {
   };
   papyrusVersion: string;
   storagePreviewPrefix?: string;
+  github?: {
+    owner: string;
+    repo: string;
+    branches: string[];
+    ciCanDeployInfra: boolean;
+  };
 };
 
+export const DEFAULT_CI_BRANCHES = ["main", "staging"];
+
 const SITE_ID_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const REPOSITORY_PATTERN = /^https:\/\/github\.com\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
 const HOSTED_ZONE_ID_PATTERN = /^Z[A-Z0-9]+$/;
@@ -30,6 +38,8 @@ const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
 const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
+const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+const GITHUB_REPO_PATTERN = /^[A-Za-z0-9_.-]+$/;
 const LOCAL_DEVELOPMENT_ORIGIN = "http://localhost:3001/";
 
 function fail(field: string, problem: string): never {
@@ -87,7 +97,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   const record = requireObject(raw, "site");
   rejectUnknownKeys(
     record,
-    ["siteId", "repository", "brand", "frontend", "hostedZoneId", "cms", "reader", "papyrusVersion", "storagePreviewPrefix"],
+    ["siteId", "repository", "brand", "frontend", "hostedZoneId", "cms", "reader", "papyrusVersion", "storagePreviewPrefix", "github"],
     "site",
   );
 
@@ -133,6 +143,32 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     fail("reader", `is required when frontend is "markus-static"`);
   }
 
+  let github: AmplifyAppShellSiteConfig["github"];
+  if (record.github !== undefined) {
+    const githubRecord = requireObject(record.github, "github");
+    rejectUnknownKeys(githubRecord, ["owner", "repo", "branches", "ciCanDeployInfra"], "github");
+    const owner = requireString(githubRecord.owner, "github.owner", GITHUB_OWNER_PATTERN, "plain GitHub login");
+    const repo = requireString(githubRecord.repo, "github.repo", GITHUB_REPO_PATTERN);
+    if (repository !== `https://github.com/${owner}/${repo}`) {
+      fail("github", `owner/repo must match repository ${repository}`);
+    }
+    let branches = DEFAULT_CI_BRANCHES;
+    if (githubRecord.branches !== undefined) {
+      if (!Array.isArray(githubRecord.branches) || githubRecord.branches.length === 0) {
+        fail("github.branches", "must be a non-empty array of branch names");
+      }
+      branches = (githubRecord.branches as unknown[]).map((branch, index) => {
+        if (typeof branch === "string" && /[*?]/.test(branch)) {
+          fail(`github.branches[${index}]`, `must not contain wildcards: ${JSON.stringify(branch)}`);
+        }
+        return requireString(branch, `github.branches[${index}]`, BRANCH_NAME_PATTERN);
+      });
+    }
+    const ciCanDeployInfra = githubRecord.ciCanDeployInfra ?? false;
+    if (typeof ciCanDeployInfra !== "boolean") fail("github.ciCanDeployInfra", "must be a boolean");
+    github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra as boolean };
+  }
+
   const config: AmplifyAppShellSiteConfig = {
     siteId,
     repository,
@@ -143,6 +179,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     reader,
     papyrusVersion,
     storagePreviewPrefix,
+    github,
   };
 
   const redirectValue = cms.environment.PAPYRUS_OAUTH_REDIRECT_URLS;

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';