@anthusai/papyrus 0.0.0 → 1.0.0-next.10

package/scripts/videoml/preview/preview-entry.tsx

@@ -0,0 +1,381 @@
+import React, { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ComposableRenderer, RendererProvider } from "@videoml/toolchain/renderer";
+import { dslToScriptData } from "@videoml/toolchain/shared";
+import { executeVomXml } from "@videoml/player";
+import { advanceScriptPreviewTime, computePreviewPlaybackState } from "./preview-timing";
+import { computePreviewStageFit } from "./preview-stage-fit";
+
+type PreviewTheme = "dark" | "light";
+type ScriptData = ReturnType<typeof dslToScriptData>;
+type PreviewRetheme = (xml: string, theme: PreviewTheme) => string;
+
+type PreviewMountOptions = {
+  xml: string;
+  theme?: PreviewTheme;
+  autoPlay?: boolean;
+  audioSrc?: string;
+};
+
+type PreviewPlayerProps = {
+  script: ScriptData;
+  width: number;
+  height: number;
+  autoPlay?: boolean;
+  audioSrc?: string;
+};
+
+let rethemeXml: PreviewRetheme = (xml) => xml;
+
+function registerPreviewRetheme(retheme: PreviewRetheme): void {
+  rethemeXml = retheme;
+}
+
+function scriptDuration(script: ScriptData): number {
+  const scenes = script.scenes ?? [];
+  if (!scenes.length) return 10;
+  const lastScene = scenes[scenes.length - 1];
+  return typeof lastScene.endSec === "number" && lastScene.endSec > 0 ? lastScene.endSec : 10;
+}
+
+function PreviewPlayer({ script, width, height, autoPlay = false, audioSrc }: PreviewPlayerProps) {
+  const [isPlaying, setIsPlaying] = useState(autoPlay);
+  const [currentTime, setCurrentTime] = useState(0);
+  const [audioDuration, setAudioDuration] = useState<number | null>(null);
+  const [audioBlocked, setAudioBlocked] = useState(false);
+  const [audioProgressObserved, setAudioProgressObserved] = useState(false);
+  const [viewportSize, setViewportSize] = useState({ width, height });
+  const animationFrameRef = useRef<number | undefined>(undefined);
+  const lastTimestampRef = useRef<number | undefined>(undefined);
+  const currentTimeRef = useRef(0);
+  const audioRef = useRef<HTMLAudioElement>(null);
+  const lastAudioTimeRef = useRef(0);
+  const viewportRef = useRef<HTMLDivElement>(null);
+  const usedAudioClockRef = useRef(false);
+
+  const fps = script.fps ?? 30;
+  const scriptDerivedDuration = useMemo(() => scriptDuration(script), [script]);
+  const playbackState = useMemo(
+    () =>
+      computePreviewPlaybackState({
+        audioBlocked,
+        audioDuration,
+        audioProgressObserved,
+        audioSrc,
+        currentTime,
+        isPlaying,
+        scriptDerivedDuration,
+      }),
+    [audioBlocked, audioDuration, audioProgressObserved, audioSrc, currentTime, isPlaying, scriptDerivedDuration],
+  );
+  const { duration, hasAudioSource, useAudioClock, visualTime } = playbackState;
+
+  const currentFrame = Math.floor(visualTime * fps);
+  const sceneBackground = script.scenes?.[0]?.styles?.background;
+  const backgroundColor = typeof sceneBackground === "string" ? sceneBackground : "#000";
+  const fittedStage = useMemo(
+    () =>
+      computePreviewStageFit({
+        containerHeight: viewportSize.height,
+        containerWidth: viewportSize.width,
+        stageHeight: height,
+        stageWidth: width,
+      }),
+    [height, viewportSize.height, viewportSize.width, width],
+  );
+
+  const applyTime = useCallback(
+    (nextTime: number) => {
+      const clamped = Math.max(0, Math.min(nextTime, duration));
+      currentTimeRef.current = clamped;
+      setCurrentTime(clamped);
+    },
+    [duration],
+  );
+
+  const playAudio = useCallback(async () => {
+    const audio = audioRef.current;
+    if (!audio || !hasAudioSource) return true;
+    try {
+      await audio.play();
+      setAudioBlocked(false);
+      return true;
+    } catch {
+      setAudioBlocked(true);
+      return false;
+    }
+  }, [hasAudioSource]);
+
+  const pauseAudio = useCallback(() => {
+    const audio = audioRef.current;
+    if (!audio || !hasAudioSource) return;
+    audio.pause();
+  }, [hasAudioSource]);
+
+  const seekAudio = useCallback(
+    (nextTime: number) => {
+      const audio = audioRef.current;
+      if (!audio || !hasAudioSource) return;
+      try {
+        audio.currentTime = nextTime;
+      } catch {
+        return;
+      }
+    },
+    [hasAudioSource],
+  );
+
+  useEffect(() => {
+    const audio = audioRef.current;
+    setAudioDuration(null);
+    setAudioProgressObserved(false);
+    setAudioBlocked(false);
+    lastAudioTimeRef.current = 0;
+    if (!audio || !hasAudioSource) return;
+
+    const onLoadedMetadata = () => {
+      if (Number.isFinite(audio.duration) && audio.duration > 0) {
+        setAudioDuration(audio.duration);
+      }
+    };
+    const markAudioProgress = () => {
+      if (!Number.isFinite(audio.currentTime)) return;
+      if (audio.currentTime > 0 || audio.currentTime !== lastAudioTimeRef.current) {
+        setAudioProgressObserved(true);
+        setAudioBlocked(false);
+      }
+      lastAudioTimeRef.current = audio.currentTime;
+    };
+    const onEnded = () => setIsPlaying(false);
+    const onError = () => {
+      setAudioBlocked(true);
+      setAudioProgressObserved(false);
+    };
+
+    audio.addEventListener("loadedmetadata", onLoadedMetadata);
+    audio.addEventListener("timeupdate", markAudioProgress);
+    audio.addEventListener("seeked", markAudioProgress);
+    audio.addEventListener("ended", onEnded);
+    audio.addEventListener("error", onError);
+    if (audio.readyState >= 1) onLoadedMetadata();
+
+    return () => {
+      audio.removeEventListener("loadedmetadata", onLoadedMetadata);
+      audio.removeEventListener("timeupdate", markAudioProgress);
+      audio.removeEventListener("seeked", markAudioProgress);
+      audio.removeEventListener("ended", onEnded);
+      audio.removeEventListener("error", onError);
+    };
+  }, [audioSrc, hasAudioSource]);
+
+  useEffect(() => {
+    if (!autoPlay || !hasAudioSource) return;
+    void playAudio();
+  }, [audioSrc, autoPlay, hasAudioSource, playAudio]);
+
+  useEffect(() => {
+    const viewport = viewportRef.current;
+    if (!viewport || typeof ResizeObserver === "undefined") return;
+    const updateViewport = () => {
+      const rect = viewport.getBoundingClientRect();
+      const nextWidth = Math.round(rect.width);
+      const nextHeight = Math.round(rect.height);
+      setViewportSize((current) => {
+        if (current.width === nextWidth && current.height === nextHeight) return current;
+        return { width: nextWidth > 0 ? nextWidth : width, height: nextHeight > 0 ? nextHeight : height };
+      });
+    };
+    updateViewport();
+    const observer = new ResizeObserver(updateViewport);
+    observer.observe(viewport);
+    return () => observer.disconnect();
+  }, [height, width]);
+
+  useEffect(() => {
+    if (usedAudioClockRef.current && !useAudioClock) {
+      currentTimeRef.current = visualTime;
+      setCurrentTime(visualTime);
+    }
+    usedAudioClockRef.current = useAudioClock;
+  }, [useAudioClock, visualTime]);
+
+  useEffect(() => {
+    if (!isPlaying) {
+      if (animationFrameRef.current) cancelAnimationFrame(animationFrameRef.current);
+      pauseAudio();
+      return;
+    }
+    if (hasAudioSource) void playAudio();
+
+    const tick = (timestamp: number) => {
+      if (!isPlaying) return;
+      if (useAudioClock) {
+        const audio = audioRef.current;
+        if (audio && Number.isFinite(audio.currentTime)) {
+          let nextTime = audio.currentTime;
+          if (nextTime >= duration && duration > 0) {
+            nextTime = 0;
+            audio.currentTime = 0;
+          }
+          applyTime(nextTime);
+        }
+      } else if (lastTimestampRef.current !== undefined) {
+        const delta = (timestamp - lastTimestampRef.current) / 1000;
+        applyTime(advanceScriptPreviewTime(currentTimeRef.current, delta, duration));
+      }
+      lastTimestampRef.current = timestamp;
+      animationFrameRef.current = requestAnimationFrame(tick);
+    };
+
+    lastTimestampRef.current = undefined;
+    animationFrameRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (animationFrameRef.current) cancelAnimationFrame(animationFrameRef.current);
+    };
+  }, [applyTime, duration, hasAudioSource, isPlaying, pauseAudio, playAudio, useAudioClock]);
+
+  const startPlayback = useCallback(async () => {
+    if (hasAudioSource) await playAudio();
+    setIsPlaying(true);
+    lastTimestampRef.current = undefined;
+  }, [hasAudioSource, playAudio]);
+
+  const stopPlayback = useCallback(() => {
+    setIsPlaying(false);
+    lastTimestampRef.current = undefined;
+  }, []);
+
+  const handleSeek = useCallback(
+    (nextTime: number) => {
+      applyTime(nextTime);
+      seekAudio(nextTime);
+      lastTimestampRef.current = undefined;
+    },
+    [applyTime, seekAudio],
+  );
+
+  const lastBroadcastRef = useRef<{ currentTime: number; duration: number } | null>(null);
+  useEffect(() => {
+    if (typeof window === "undefined" || window.parent === window) return;
+    const roundedTime = Math.round(currentTime * 10) / 10;
+    const roundedDuration = Math.round(duration * 10) / 10;
+    const previous = lastBroadcastRef.current;
+    if (previous && previous.currentTime === roundedTime && previous.duration === roundedDuration) return;
+    lastBroadcastRef.current = { currentTime: roundedTime, duration: roundedDuration };
+    window.parent.postMessage({ kind: "papyrus-video-time", currentTime: roundedTime, duration: roundedDuration }, "*");
+  }, [currentTime, duration]);
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      const payload = event.data;
+      if (!payload || typeof payload !== "object") return;
+      if (payload.kind === "papyrus-video-play") {
+        void startPlayback();
+        return;
+      }
+      if (payload.kind === "papyrus-video-pause") {
+        stopPlayback();
+        return;
+      }
+      if (payload.kind === "papyrus-video-seek" && typeof payload.time === "number") {
+        handleSeek(payload.time);
+      }
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, [handleSeek, startPlayback, stopPlayback]);
+
+  return (
+    <div style={{ background: "#000", height: "100%", overflow: "hidden", position: "relative", width: "100%" }}>
+      {hasAudioSource ? <audio ref={audioRef} preload="auto" src={audioSrc} style={{ display: "none" }} /> : null}
+      <div
+        ref={viewportRef}
+        style={{
+          alignItems: "center",
+          background: backgroundColor,
+          display: "flex",
+          inset: 0,
+          justifyContent: "center",
+          overflow: "hidden",
+          position: "absolute",
+        }}
+      >
+        <div
+          style={{
+            height,
+            left: "50%",
+            position: "absolute",
+            top: "50%",
+            transform: `translate(-50%, -50%) scale(${fittedStage.scale})`,
+            transformOrigin: "center center",
+            width,
+          }}
+        >
+          <RendererProvider
+            frame={currentFrame}
+            config={{ fps, width, height, durationFrames: Math.max(1, Math.floor(duration * fps)) }}
+          >
+            <ComposableRenderer script={script} />
+          </RendererProvider>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function parsePreviewScript(xml: string): ScriptData {
+  const result = executeVomXml(xml);
+  const composition = Array.isArray(result?.compositions) && result.compositions[0] ? result.compositions[0] : result;
+  const script = dslToScriptData(composition, { type: "cue-count", secondsPerCue: 3 });
+
+  const timeline: unknown[] = [];
+  const scenes = script.scenes ?? [];
+  let sceneIndex = 0;
+
+  const doc = new DOMParser().parseFromString(xml, "text/xml");
+  for (const element of Array.from(doc.documentElement.children)) {
+    if (element.tagName === "scene") {
+      const scene = scenes[sceneIndex];
+      if (scene) {
+        timeline.push(scene);
+        sceneIndex += 1;
+      }
+    } else if (element.tagName === "transition") {
+      const previousScene = sceneIndex > 0 ? scenes[sceneIndex - 1] : null;
+      const nextScene = sceneIndex < scenes.length ? scenes[sceneIndex] : null;
+      const durationAttribute = element.getAttribute("duration");
+      const durationFrames = durationAttribute ? parseFloat(durationAttribute.replace("f", "")) : 16;
+      const startSec = nextScene ? (nextScene.startSec ?? 0) : 0;
+      const propsAttribute = element.getAttribute("props");
+      timeline.push({
+        kind: "transition",
+        id: element.getAttribute("id") || `trans-${sceneIndex}`,
+        effect: element.getAttribute("effect") || "push",
+        durationFrames,
+        ease: element.getAttribute("ease"),
+        props: propsAttribute ? JSON.parse(propsAttribute) : undefined,
+        startSec,
+        endSec: startSec + durationFrames / (script.fps ?? 30),
+        fromSceneId: previousScene?.id,
+        toSceneId: nextScene?.id,
+      });
+    }
+  }
+
+  (script as { timeline?: unknown[] }).timeline = timeline;
+  return script;
+}
+
+function mountPreview(container: HTMLElement, options: PreviewMountOptions): () => void {
+  const theme = options.theme ?? "light";
+  const script = parsePreviewScript(rethemeXml(options.xml, theme));
+  const width = script.meta?.width && script.meta.width > 0 ? script.meta.width : 1280;
+  const height = script.meta?.height && script.meta.height > 0 ? script.meta.height : 720;
+  const root = (window as unknown as { ReactDOM: { createRoot: (el: HTMLElement) => { render: (node: React.ReactNode) => void; unmount: () => void } } }).ReactDOM.createRoot(container);
+  root.render(
+    <PreviewPlayer audioSrc={options.audioSrc} autoPlay={options.autoPlay ?? false} height={height} script={script} width={width} />,
+  );
+  return () => root.unmount();
+}
+
+(window as unknown as Record<string, unknown>).PapyrusVideo = { registerPreviewRetheme };
+(window as unknown as Record<string, unknown>).mountPapyrusVideoPreview = mountPreview;

package/scripts/videoml/preview/preview-stage-fit.ts

@@ -0,0 +1,28 @@
+export type PreviewStageFitInput = {
+  containerHeight: number;
+  containerWidth: number;
+  stageHeight: number;
+  stageWidth: number;
+};
+
+export type PreviewStageFit = {
+  height: number;
+  scale: number;
+  width: number;
+};
+
+export function computePreviewStageFit(input: PreviewStageFitInput): PreviewStageFit {
+  const stageWidth = input.stageWidth > 0 ? input.stageWidth : 1280;
+  const stageHeight = input.stageHeight > 0 ? input.stageHeight : 720;
+  const containerWidth = input.containerWidth > 0 ? input.containerWidth : stageWidth;
+  const containerHeight = input.containerHeight > 0 ? input.containerHeight : stageHeight;
+
+  const scale = Math.min(containerWidth / stageWidth, containerHeight / stageHeight);
+  const safeScale = Number.isFinite(scale) && scale > 0 ? scale : 1;
+
+  return {
+    height: stageHeight * safeScale,
+    scale: safeScale,
+    width: stageWidth * safeScale,
+  };
+}

package/scripts/videoml/preview/preview-timing.ts

@@ -0,0 +1,42 @@
+export type PreviewPlaybackStateInput = {
+  audioBlocked: boolean;
+  audioDuration: number | null;
+  audioProgressObserved: boolean;
+  audioSrc?: string | null;
+  currentTime: number;
+  isPlaying: boolean;
+  scriptDerivedDuration: number;
+};
+
+export type PreviewPlaybackState = {
+  audioReady: boolean;
+  controlLabel: string;
+  duration: number;
+  hasAudioSource: boolean;
+  useAudioClock: boolean;
+  visualTime: number;
+};
+
+export function computePreviewPlaybackState(input: PreviewPlaybackStateInput): PreviewPlaybackState {
+  const hasAudioSource = Boolean(input.audioSrc);
+  const audioReady =
+    input.audioDuration != null && Number.isFinite(input.audioDuration) && input.audioDuration > 0;
+  const useAudioClock = hasAudioSource && audioReady && input.audioProgressObserved && !input.audioBlocked;
+  const duration = useAudioClock && input.audioDuration != null ? input.audioDuration : input.scriptDerivedDuration;
+  const visualTime =
+    useAudioClock && duration > 0 && input.scriptDerivedDuration > 0
+      ? (input.currentTime / duration) * input.scriptDerivedDuration
+      : input.currentTime;
+  const controlLabel = input.isPlaying ? "Pause" : hasAudioSource && input.audioBlocked ? "Play (audio)" : "Play";
+
+  return { audioReady, controlLabel, duration, hasAudioSource, useAudioClock, visualTime };
+}
+
+export function advanceScriptPreviewTime(currentTime: number, deltaSeconds: number, duration: number): number {
+  if (!(duration > 0)) return 0;
+  let nextTime = currentTime + Math.max(0, deltaSeconds);
+  if (nextTime >= duration) {
+    nextTime = 0;
+  }
+  return Math.max(0, Math.min(nextTime, duration));
+}

package/scripts/videoml/preview.html

@@ -0,0 +1,77 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Video preview</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        width: 100%;
+        height: 100%;
+        background: #000;
+        overflow: hidden;
+      }
+
+      #preview-root {
+        width: 100%;
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="preview-root"></div>
+    <script src="./vendor/react.production.min.js"></script>
+    <script src="./vendor/react-dom.production.min.js"></script>
+    <script src="./preview-bundle.js"></script>
+    <script>
+      const root = document.getElementById("preview-root");
+      const params = new URLSearchParams(window.location.search);
+      let cleanup = null;
+
+      function showMessage(text) {
+        root.textContent = text;
+        root.style.cssText = "color:#eee;font:14px/1.4 system-ui,sans-serif;padding:24px;";
+      }
+
+      function readPayload(overrides) {
+        const target = (overrides && overrides.target) || params.get("target") || "";
+        const theme = (overrides && overrides.theme) || params.get("theme") || "light";
+        const audioSrc = (overrides && overrides.audio) || params.get("audio") || "";
+        const xml = target ? sessionStorage.getItem("papyrus-video-preview:" + target) : null;
+        return { theme, xml, audioSrc };
+      }
+
+      function mountPreview(payload) {
+        if (!payload || typeof payload.xml !== "string" || !payload.xml.trim()) {
+          showMessage("No VideoML DSL available for preview.");
+          return;
+        }
+        if (typeof cleanup === "function") {
+          cleanup();
+          cleanup = null;
+        }
+        root.textContent = "";
+        root.removeAttribute("style");
+        cleanup = window.mountPapyrusVideoPreview(root, {
+          xml: payload.xml,
+          theme: payload.theme || "light",
+          audioSrc: payload.audioSrc || undefined,
+          autoPlay: false,
+        });
+      }
+
+      window.addEventListener("message", (event) => {
+        const payload = event.data;
+        if (payload && payload.kind === "papyrus-video-refresh") mountPreview(readPayload(payload));
+      });
+
+      mountPreview(readPayload());
+
+      if (window.parent !== window) {
+        window.parent.postMessage({ kind: "papyrus-video-ready" }, "*");
+      }
+    </script>
+  </body>
+</html>

package/scripts/videoml/standard-entry.tsx

@@ -0,0 +1,46 @@
+import React from "react";
+import { createRoot } from "react-dom/client";
+import {
+  ComposableRenderer,
+  RendererProvider,
+  interpolate,
+  spring,
+  useCurrentFrame,
+  useVideoConfig,
+} from "@videoml/toolchain/renderer";
+import { getComponent, listComponents, registerComponent } from "@videoml/toolchain/renderer/components/registry";
+
+type RenderFrameRequest = {
+  script: unknown;
+  frame: number;
+  config: { fps: number; width: number; height: number; durationFrames: number };
+  inputProps?: Record<string, unknown>;
+};
+
+const root = document.getElementById("root");
+let reactRoot: ReturnType<typeof createRoot> | null = null;
+
+const videoApi = {
+  registerComponent,
+  getComponent,
+  listComponents,
+  ComposableRenderer,
+  RendererProvider,
+  useCurrentFrame,
+  useVideoConfig,
+  interpolate,
+  spring,
+};
+
+(window as unknown as { Babulus: typeof videoApi }).Babulus = videoApi;
+
+(window as unknown as { renderFrame: (request: RenderFrameRequest) => Promise<void> }).renderFrame = (request) => {
+  if (!root) throw new Error("VideoML render shell has no #root element.");
+  reactRoot ??= createRoot(root);
+  reactRoot.render(
+    <RendererProvider frame={request.frame} config={request.config}>
+      <ComposableRenderer script={request.script as never} {...(request.inputProps ?? {})} />
+    </RendererProvider>,
+  );
+  return new Promise((resolve) => setTimeout(resolve, 100));
+};

package/src/backend.js

@@ -0,0 +1 @@
+export { defineSiteBackend } from "../amplify/site-backend.js";

package/src/backend.ts

@@ -0,0 +1,3 @@
+export { defineSiteBackend } from "../amplify/site-backend";
+export type { PapyrusSite } from "../lib/define-site";
+export type { PapyrusSiteBackendConfig, PapyrusAuthConfig } from "../amplify/site-backend-config";

package/src/sync.mjs

@@ -0,0 +1,87 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+/**
+ * `papyrus-app sync`: write one-line route shims for Papyrus's routes into the
+ * publication repo (SPIKE, PPY-82be6c). Output is generated and gitignored;
+ * a site-owned file at the same path (no GENERATED header) always wins.
+ */
+const MARKER = "// GENERATED by `papyrus-app sync` from @anthusai/papyrus. Do not edit; add a site-owned file at this path to override.";
+const NEXT_EXPORTS = new Set([
+  "generateMetadata", "metadata", "generateStaticParams", "generateViewport", "viewport",
+  "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS",
+]);
+const GITIGNORE_BEGIN = "# >>> papyrus-app sync (generated route shims)";
+const GITIGNORE_END = "# <<< papyrus-app sync";
+
+const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const PKG = "@anthusai/papyrus";
+
+function isGenerated(file) {
+  try {
+    return fs.readFileSync(file, "utf8").startsWith(MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function shimFor(route) {
+  const spec = `${PKG}/${route.file.replace(/\.(tsx|ts)$/, "")}`;
+  const lines = [MARKER];
+  const named = route.exports.filter((n) => NEXT_EXPORTS.has(n));
+  if (route.hasDefault) lines.push(`export { default${named.length ? ", " + named.join(", ") : ""} } from "${spec}";`);
+  else if (named.length) lines.push(`export { ${named.join(", ")} } from "${spec}";`);
+  // Route-segment config must be a literal in the route file itself.
+  for (const [name, literal] of Object.entries(route.config)) lines.push(`export const ${name} = ${literal};`);
+  return lines.join("\n") + "\n";
+}
+
+function middlewareShim(manifest) {
+  const matcher = manifest.middleware.matcher ?? '["/((?!_next/static|_next/image|favicon.ico|icon).*)"]';
+  return [
+    MARKER,
+    `export { middleware } from "${PKG}/middleware";`,
+    `export const config = { matcher: ${matcher} };`,
+    "",
+  ].join("\n");
+}
+
+export function sync({ root = process.cwd(), log = console.log } = {}) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(pkgRoot, "routes.manifest.json"), "utf8"));
+  const generated = [];
+  const skipped = [];
+  const write = (relPath, content) => {
+    const dest = path.join(root, relPath);
+    if (fs.existsSync(dest) && !isGenerated(dest)) {
+      skipped.push(relPath);
+      return;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, content);
+    generated.push(relPath);
+  };
+  for (const route of manifest.routes) write(route.file, shimFor(route));
+  write("middleware.ts", middlewareShim(manifest));
+
+  // Remove shims that are no longer in the manifest (e.g. after an upgrade).
+  const stateFile = path.join(root, ".papyrus", "generated.json");
+  let previous = [];
+  try { previous = JSON.parse(fs.readFileSync(stateFile, "utf8")); } catch { /* first run */ }
+  for (const rel of previous) {
+    if (!generated.includes(rel) && isGenerated(path.join(root, rel))) fs.rmSync(path.join(root, rel));
+  }
+  fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+  fs.writeFileSync(stateFile, JSON.stringify(generated, null, 2) + "\n");
+
+  // Keep generated shims out of git.
+  const giFile = path.join(root, ".gitignore");
+  const gi = fs.existsSync(giFile) ? fs.readFileSync(giFile, "utf8") : "";
+  const block = [GITIGNORE_BEGIN, ...generated.map((g) => "/" + g), "/.papyrus/", GITIGNORE_END].join("\n");
+  const re = new RegExp(`${GITIGNORE_BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${GITIGNORE_END}`);
+  fs.writeFileSync(giFile, re.test(gi) ? gi.replace(re, block) : `${gi}${gi.endsWith("\n") || !gi ? "" : "\n"}${block}\n`);
+
+  log(`papyrus-app sync: ${generated.length} shim(s) written, ${skipped.length} site-owned file(s) kept (${PKG}@${manifest.version})`);
+  for (const rel of skipped) log(`  site-owned: ${rel}`);
+  return { generated, skipped };
+}

package/src/with-papyrus.d.mts

@@ -0,0 +1,2 @@
+import type { NextConfig } from "next";
+export function withPapyrus(nextConfig?: NextConfig, options?: { root?: string }): NextConfig;