@backmatter/next 0.0.6

package/src/preview-route.ts

@@ -0,0 +1,138 @@
+// packages/next/src/preview-route.ts
+import {
+  PREVIEW_COOKIE,
+  PREVIEW_COOKIE_TTL_MS,
+  readPreviewCookie,
+  readPreviewTicket,
+  writePreviewCookie,
+  type PreviewCheckout,
+} from "@backmatter/core";
+import { previewStreamUrl } from "@backmatter/core/preview";
+import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+
+export type PreviewRouteDeps = {
+  enableDraft?: () => void | Promise<void>;
+  disableDraft?: () => void | Promise<void>;
+  now?: () => number;
+};
+
+function cookieBase(secure: boolean, maxAge: number, value: string) {
+  const parts = [
+    `${PREVIEW_COOKIE}=${value}`,
+    "Path=/",
+    "HttpOnly",
+    "SameSite=Lax",
+    `Max-Age=${maxAge}`,
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+async function nextDraft(enable: boolean): Promise<void> {
+  const mod = (await import("next/headers" as string)) as {
+    draftMode: () => Promise<{ enable: () => void; disable: () => void }>;
+  };
+  const draft = await mod.draftMode();
+  if (enable) draft.enable();
+  else draft.disable();
+}
+
+function cookieFrom(req: Request): string | undefined {
+  const header = req.headers.get("cookie");
+  if (!header) return undefined;
+  for (const part of header.split(";")) {
+    const [name, ...rest] = part.trim().split("=");
+    if (name === PREVIEW_COOKIE) return rest.join("=");
+  }
+  return undefined;
+}
+
+export function createPreviewRoute(
+  cms: Pick<BackmatterClient, "config">,
+  deps: PreviewRouteDeps = {},
+) {
+  const secret = cms.config.previewToken;
+  const now = deps.now ?? Date.now;
+
+  const GET = async (req: Request): Promise<Response> => {
+    const url = new URL(req.url);
+    const secure = url.protocol === "https:";
+
+    if (url.searchParams.get("session") === "1") {
+      const checkout = secret ? await readPreviewCookie(secret, cookieFrom(req)) : null;
+      if (!checkout) return Response.json({ mode: "live" });
+      return Response.json({
+        mode: "preview",
+        ...checkout,
+      });
+    }
+
+    if (url.searchParams.get("stream") === "1") {
+      if (!secret || !cms.config.apiUrl || !cms.config.workspaceId) {
+        return new Response("preview not configured", { status: 503 });
+      }
+      const checkout = await readPreviewCookie(secret, cookieFrom(req));
+      if (!checkout) return new Response("preview session missing", { status: 401 });
+      const locale = url.searchParams.get("locale") ?? cms.config.defaultLocale;
+      const type = url.searchParams.get("type") ?? "";
+      const slug = url.searchParams.get("slug") ?? "";
+      if (!type || !slug) return new Response("missing type or slug", { status: 400 });
+      const upstream = previewStreamUrl(
+        { apiUrl: cms.config.apiUrl, workspaceId: cms.config.workspaceId, previewToken: secret },
+        { locale, type, slug, ...checkout },
+      );
+      const res = await fetch(upstream);
+      return new Response(res.body, {
+        status: res.status,
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-store",
+        },
+      });
+    }
+
+    const ticket = url.searchParams.get("ticket")?.trim();
+    if (!ticket) return Response.json({ error: "missing_ticket" }, { status: 400 });
+    if (!secret) return Response.json({ error: "preview_not_configured" }, { status: 503 });
+    const payload = await readPreviewTicket(secret, ticket);
+    if (!payload || payload.workspaceId !== cms.config.workspaceId) {
+      return Response.json({ error: "invalid_ticket" }, { status: 401 });
+    }
+    const value = await writePreviewCookie(secret, {
+      branch: payload.branch,
+      tree: payload.tree,
+      exp: now() + PREVIEW_COOKIE_TTL_MS,
+    });
+    await (deps.enableDraft ?? (() => nextDraft(true)))();
+    const location = new URL(payload.redirect, url.origin).toString();
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: location,
+        "Set-Cookie": cookieBase(secure, Math.floor(PREVIEW_COOKIE_TTL_MS / 1000), value),
+      },
+    });
+  };
+
+  const POST = async (req: Request): Promise<Response> => {
+    await (deps.disableDraft ?? (() => nextDraft(false)))();
+    const secure = new URL(req.url).protocol === "https:";
+    return new Response(null, {
+      status: 204,
+      headers: {
+        "Set-Cookie": cookieBase(secure, 0, ""),
+      },
+    });
+  };
+
+  return { GET, POST };
+}
+
+export async function loadPreviewCheckout(
+  secret: string | undefined,
+  cookieHeader: string | undefined,
+): Promise<PreviewCheckout | null> {
+  if (!secret) return null;
+  const fake = new Request("http://local", { headers: cookieHeader ? { cookie: cookieHeader } : {} });
+  return readPreviewCookie(secret, cookieFrom(fake));
+}

package/src/preview-ui.ts

@@ -0,0 +1,15 @@
+// packages/next/src/preview-ui.ts
+import { createElement, type ReactNode } from "react";
+
+export function previewUnavailable(message?: string): ReactNode {
+  return createElement(
+    "section",
+    null,
+    createElement("h1", null, "Preview unavailable"),
+    createElement(
+      "p",
+      null,
+      message ?? "This preview session expired or could not load.",
+    ),
+  );
+}

package/src/preview.ts

@@ -0,0 +1,4 @@
+// packages/next/src/preview.ts
+// Client-safe re-export of the preview client (`fetchPreviewDoc`,
+// `subscribePreview`, hotkeys). Implementation lives in `@backmatter/core/preview`.
+export * from "@backmatter/core/preview";

package/src/proxy.ts

@@ -0,0 +1,24 @@
+// packages/next/src/proxy.ts
+// Next 16 file convention is `proxy.ts` exporting `proxy` (was `middleware.ts`).
+import { NextResponse, type NextRequest } from "next/server";
+import { PREVIEW_COOKIE, previewMiddlewareDecision } from "@backmatter/core";
+
+export function backmatterProxy(request: NextRequest): NextResponse | null {
+  const draft = Boolean(request.cookies.get(PREVIEW_COOKIE)?.value);
+  const decision = previewMiddlewareDecision(request.nextUrl, draft);
+  if (decision.type === "redirect") {
+    return NextResponse.redirect(new URL(decision.location, request.url));
+  }
+  if (decision.type === "headers") {
+    const res = NextResponse.next();
+    for (const [name, value] of Object.entries(decision.headers)) {
+      res.headers.set(name, value);
+    }
+    return res;
+  }
+  return null;
+}
+
+export function proxy(request: NextRequest) {
+  return backmatterProxy(request) ?? NextResponse.next();
+}

package/src/revalidate.ts

@@ -0,0 +1,64 @@
+// packages/next/src/revalidate.ts
+// POST /api/backmatter/revalidate — the only Next-specific piece of content.committed.
+// The central server POSTs here after S3 head/ is updated; we never talk to GitHub.
+import { timingSafeEqual } from "node:crypto";
+import {
+  CONTENT_COMMITTED_EVENT,
+  BACKMATTER_CACHE_TAG,
+  pathsForCommittedDocs,
+  type ContentCommittedEvent,
+} from "@backmatter/core";
+import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+
+export type RevalidateCache = {
+  revalidatePath: (path: string, type?: "layout" | "page") => void;
+  revalidateTag: (tag: string) => void;
+};
+
+function extractBearer(header: string | null): string | null {
+  if (!header?.startsWith("Bearer ")) return null;
+  const token = header.slice("Bearer ".length).trim();
+  return token.length > 0 ? token : null;
+}
+
+function tokensEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return timingSafeEqual(ab, bb);
+}
+
+async function loadNextCache(): Promise<RevalidateCache> {
+  const mod = (await import("next/cache" as string)) as RevalidateCache;
+  return { revalidatePath: mod.revalidatePath, revalidateTag: mod.revalidateTag };
+}
+
+export function createRevalidateRoute(
+  cms: Pick<BackmatterClient, "models" | "config">,
+  cache?: RevalidateCache,
+) {
+  return async (req: Request): Promise<Response> => {
+    const expected = cms.config.hostToken;
+    const token = extractBearer(req.headers.get("authorization"));
+    if (!expected || !token || !tokensEqual(token, expected)) {
+      return Response.json({ error: "unauthorized" }, { status: 401 });
+    }
+
+    let body: ContentCommittedEvent;
+    try {
+      body = (await req.json()) as ContentCommittedEvent;
+    } catch {
+      return Response.json({ error: "invalid_json" }, { status: 400 });
+    }
+    if (body?.event !== CONTENT_COMMITTED_EVENT) {
+      return Response.json({ error: "invalid_event" }, { status: 400 });
+    }
+
+    const { revalidatePath, revalidateTag } = cache ?? (await loadNextCache());
+    const paths = pathsForCommittedDocs(cms.models, body.docs ?? []);
+    for (const path of paths) revalidatePath(path);
+    revalidateTag(BACKMATTER_CACHE_TAG);
+    if (body.full) revalidatePath("/", "layout");
+    return Response.json({ ok: true, paths });
+  };
+}

package/src/routes.ts

@@ -0,0 +1,226 @@
+// packages/next/src/routes.ts
+// `createCatchAll(cms)` powers the one route file a host adds:
+// app/[[...backmatter]]/page.tsx. It maps the URL to a document via each model's
+// `route` template (including `/` via indexSlug), loads it and renders MDX
+// or JSON pages. An optional catch-all is required so `/` is a CMS route.
+import { Suspense, createElement, type ReactNode } from "react";
+import { matchRoute, modelFormat, PREVIEW_COOKIE, readPreviewCookie, routeSegments, type BackmatterDoc, type ModelDef } from "@backmatter/core";
+import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+import { fetchPreviewDoc } from "@backmatter/core/preview";
+import { renderDoc, type MdxComponents } from "./mdx-compile";
+import { getCachedDoc, registerCachedDocGet } from "./cached-doc";
+import { BlockSkeleton, renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
+import { PreviewBody } from "./preview-live";
+import { PreviewPageReloader } from "./preview-refresh";
+import { previewUnavailable } from "./preview-ui";
+
+export const CATCH_ALL_PARAM = "backmatter";
+
+export type CatchAllParams = { [CATCH_ALL_PARAM]?: string[] };
+
+export type DocLayout = (doc: BackmatterDoc, body: ReactNode) => ReactNode;
+
+export type CatchAllOptions = {
+  /** MDX component map, usually the generated `components`. */
+  components?: MdxComponents;
+  /** Composer map, usually the generated `blocks`. */
+  blocks?: BlockComponents;
+  /** Per-block Suspense fallbacks for page-format documents. */
+  fallbacks?: BlockFallbacks;
+  /** Per-type wrappers, usually the generated `layouts`. */
+  layouts?: Record<string, DocLayout>;
+  /** Overrides `cms.config.locales`. */
+  locales?: readonly string[];
+  /** Overrides `cms.config.defaultLocale`. */
+  defaultLocale?: string;
+  /**
+   * Wrap the rendered body (layout, title, metadata). Default: the body only.
+   */
+  render?: (doc: BackmatterDoc, body: ReactNode) => ReactNode;
+  /** Hook for tests; defaults to Next's `notFound()`. */
+  notFound?: () => never;
+  /**
+   * Test/host injection. When omitted, the catch-all reads Next draftMode
+   * and the signed preview cookie. Never call cookies() on the live path.
+   */
+  preview?: {
+    enabled: boolean;
+    checkout?: { branch?: string; tree?: string };
+    getDoc?: (ref: {
+      locale: string;
+      type: string;
+      slug: string;
+      branch?: string;
+      tree?: string;
+    }) => Promise<BackmatterDoc | null>;
+  };
+};
+
+export type CatchAllMetadata = { title?: string };
+
+export type CatchAllRoute = {
+  Page: (props: { params: Promise<CatchAllParams> }) => ReactNode;
+  CmsRoute: (props: { params: Promise<CatchAllParams> | CatchAllParams }) => Promise<ReactNode>;
+  generateStaticParams: () => Promise<CatchAllParams[]>;
+  generateMetadata: (props: {
+    params: Promise<CatchAllParams>;
+  }) => Promise<CatchAllMetadata>;
+  /** Resolve URL segments to a document identity (null → 404). */
+  resolve: (segments: readonly string[] | undefined) => ReturnType<typeof matchRoute>;
+};
+
+// `next` is an optional peer: the `as string` keeps tsc from resolving the
+// module (so this package type-checks with or without `next`, including when
+// symlinked into a host), while SWC/webpack still see a literal specifier.
+async function nextNotFound(): Promise<never> {
+  const mod = (await import("next/navigation" as string)) as { notFound: () => never };
+  return mod.notFound();
+}
+
+type PreviewState =
+  | { enabled: false }
+  | { enabled: true; checkout: { branch?: string; tree?: string }; error?: string };
+
+async function resolvePreviewState(
+  cms: Pick<BackmatterClient, "config">,
+  injected: CatchAllOptions["preview"],
+): Promise<PreviewState> {
+  if (injected) {
+    if (!injected.enabled) return { enabled: false };
+    return { enabled: true, checkout: injected.checkout ?? {} };
+  }
+  try {
+    const mod = (await import("next/headers" as string)) as {
+      draftMode: () => Promise<{ isEnabled: boolean }>;
+      cookies: () => Promise<{ get: (name: string) => { value: string } | undefined }>;
+    };
+    const { isEnabled } = await mod.draftMode();
+    if (!isEnabled) return { enabled: false };
+    const secret = cms.config.previewToken;
+    if (!secret) return { enabled: true, checkout: {}, error: "preview_not_configured" };
+    const raw = (await mod.cookies()).get(PREVIEW_COOKIE)?.value;
+    const checkout = await readPreviewCookie(secret, raw);
+    if (!checkout) return { enabled: true, checkout: {}, error: "invalid_session" };
+    return { enabled: true, checkout };
+  } catch {
+    return { enabled: false };
+  }
+}
+
+export function createCatchAll<Models extends readonly ModelDef[]>(
+  cms: BackmatterClient<Models>,
+  options: CatchAllOptions = {},
+): CatchAllRoute {
+  registerCachedDocGet((locale, type, slug) => cms.getDoc(locale, type, slug));
+  const models = cms.models as readonly ModelDef[];
+  const byType = new Map(models.map((m) => [m.type, m]));
+  const matchOptions = {
+    defaultLocale: options.defaultLocale ?? cms.config.defaultLocale,
+    locales: options.locales ?? cms.config.locales,
+  };
+
+  const resolve: CatchAllRoute["resolve"] = (segments) => {
+    const pathname = `/${(segments ?? []).join("/")}`;
+    return matchRoute(models, pathname, matchOptions);
+  };
+
+  const generateStaticParams: CatchAllRoute["generateStaticParams"] = async () => {
+    const docs = await cms.listDocs();
+    const params: CatchAllParams[] = [];
+    for (const doc of docs) {
+      const model = byType.get(doc.type);
+      if (!model) continue;
+      params.push({ [CATCH_ALL_PARAM]: routeSegments(model, doc.locale, doc.slug) });
+    }
+    return params;
+  };
+
+  const PageFallback = BlockSkeleton;
+
+  const CmsRoute: CatchAllRoute["CmsRoute"] = async ({ params }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    const fail = options.notFound ?? nextNotFound;
+    if (!hit) return fail();
+    const preview = await resolvePreviewState(cms, options.preview);
+    let doc: BackmatterDoc | null;
+    if (preview.enabled) {
+      if (preview.error) return previewUnavailable(preview.error);
+      try {
+        const getDoc =
+          options.preview?.getDoc ??
+          ((ref) =>
+            fetchPreviewDoc(
+              {
+                apiUrl: cms.config.apiUrl ?? "",
+                workspaceId: cms.config.workspaceId ?? "",
+                previewToken: cms.config.previewToken ?? "",
+              },
+              ref,
+            ));
+        doc = await getDoc({
+          locale: hit.locale,
+          type: hit.type,
+          slug: hit.slug,
+          ...preview.checkout,
+        });
+      } catch (err) {
+        return previewUnavailable(err instanceof Error ? err.message : "Failed to load");
+      }
+    } else {
+      doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    }
+    if (!doc) return fail();
+    const model = byType.get(hit.type);
+    const isPage = Boolean(model && modelFormat(model) === "page");
+    const rendered = isPage
+      ? renderPage(doc, options.blocks, options.fallbacks)
+      : await renderDoc(doc, { components: options.components });
+    const body = isPage
+      ? rendered
+      : preview.enabled
+        ? createElement(
+            PreviewBody,
+            { doc, components: options.components },
+            rendered,
+          )
+        : rendered;
+    const withLive =
+      preview.enabled && isPage
+        ? createElement(
+            "div",
+            null,
+            createElement(PreviewPageReloader, {
+              locale: doc.locale,
+              type: doc.type,
+              slug: doc.slug,
+            }),
+            body,
+          )
+        : body;
+    const layout = options.layouts?.[hit.type];
+    const laidOut = layout ? layout(doc, withLive) : withLive;
+    if (options.render) return options.render(doc, laidOut);
+    if (layout || isPage) return laidOut;
+    return createElement("article", null, laidOut);
+  };
+
+  const Page: CatchAllRoute["Page"] = (props) =>
+    createElement(
+      Suspense,
+      { fallback: createElement(PageFallback) },
+      createElement(CmsRoute, props),
+    );
+
+  const generateMetadata: CatchAllRoute["generateMetadata"] = async ({ params }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    if (!hit) return {};
+    const doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    if (!doc) return {};
+    const title = doc.frontmatter.title;
+    return { title: typeof title === "string" ? title : hit.slug };
+  };
+
+  return { Page, CmsRoute, generateStaticParams, generateMetadata, resolve };
+}