@backmatter/next 0.0.21 → 0.0.23

package/src/preview-refresh.tsx

@@ -1,9 +1,18 @@
 // packages/next/src/preview-refresh.tsx
 "use client";
 
-import { createElement, useCallback, startTransition } from "react";
+import { useCallback, useEffect, useState, startTransition, type ReactNode } from "react";
 import { useRouter } from "next/navigation";
-import { PreviewPageReloader as PreviewStreamReloader } from "./preview-live";
+import { PREVIEW_CHECKOUT_QUERY } from "@backmatter/core";
+import {
+  createPreviewPage,
+  createWindowPreviewTransport,
+  type PreviewChannelRef,
+  type PreviewRenderDoc,
+  type PreviewTransport,
+} from "@backmatter/core/preview";
+import { fanInPreviewTransports, sitePageTransport } from "./site-channel";
+import { PreviewPageReloader as PreviewStreamReloader, PreviewRemoved } from "./preview-live";
 
 /** Keeps the current page visible while preview content is refetched. */
 export function PreviewPageReloader(props: { locale: string; type: string; slug: string }) {
@@ -13,5 +22,204 @@ export function PreviewPageReloader(props: { locale: string; type: string; slug:
       router.refresh();
     });
   }, [router]);
-  return createElement(PreviewStreamReloader, { ...props, refresh });
+  return <PreviewStreamReloader {...props} refresh={refresh} />;
+}
+
+export type PreviewRenderAction = (
+  ref: PreviewChannelRef,
+  doc: PreviewRenderDoc,
+  checkoutToken?: string,
+) => Promise<{ ok: true; node: ReactNode } | { ok: false; error: string }>;
+
+function referrerOrigin(): string {
+  try {
+    return document.referrer ? new URL(document.referrer).origin : "";
+  } catch {
+    return "";
+  }
+}
+
+function subscribeDocStream(
+  ref: { locale: string; type: string; slug: string },
+  onEvent: (event: { raw?: string; body?: string; frontmatter?: Record<string, unknown> }) => void,
+): () => void {
+  const params = new URLSearchParams({
+    stream: "1",
+    locale: ref.locale,
+    type: ref.type,
+    slug: ref.slug,
+  });
+  const checkout = new URLSearchParams(globalThis.location?.search ?? "").get(PREVIEW_CHECKOUT_QUERY);
+  if (checkout) params.set(PREVIEW_CHECKOUT_QUERY, checkout);
+  const source = new EventSource(`/api/backmatter/preview?${params}`);
+  const onChange = (ev: MessageEvent) => {
+    try {
+      const data = JSON.parse(String(ev.data)) as {
+        raw?: unknown;
+        body?: unknown;
+        frontmatter?: unknown;
+      };
+      onEvent({
+        ...(typeof data.raw === "string" ? { raw: data.raw } : {}),
+        ...(typeof data.body === "string" ? { body: data.body } : {}),
+        ...(data.frontmatter && typeof data.frontmatter === "object" && !Array.isArray(data.frontmatter)
+          ? { frontmatter: data.frontmatter as Record<string, unknown> }
+          : {}),
+      });
+    } catch {
+      // ignore malformed
+    }
+  };
+  source.addEventListener("change", onChange as EventListener);
+  return () => {
+    source.removeEventListener("change", onChange as EventListener);
+    source.close();
+  };
+}
+
+/** Refresh when some other document in this checkout changes, or HEAD moves. */
+function subscribeTreeStream(
+  ref: { locale: string; type: string; slug: string },
+  refresh: () => void,
+): () => void {
+  const params = new URLSearchParams({ stream: "tree" });
+  const checkout = new URLSearchParams(globalThis.location?.search ?? "").get(PREVIEW_CHECKOUT_QUERY);
+  if (checkout) params.set(PREVIEW_CHECKOUT_QUERY, checkout);
+  const source = new EventSource(`/api/backmatter/preview?${params}`);
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const schedule = () => {
+    if (timer) return;
+    timer = setTimeout(() => {
+      timer = null;
+      refresh();
+    }, 50);
+  };
+  const onChange = (ev: MessageEvent) => {
+    try {
+      const data = JSON.parse(String(ev.data)) as { ref?: { locale?: string; type?: string; slug?: string } };
+      const changed = data.ref;
+      if (
+        changed &&
+        changed.locale === ref.locale &&
+        changed.type === ref.type &&
+        changed.slug === ref.slug
+      ) {
+        return;
+      }
+    } catch {
+      // a malformed payload still means something in the tree moved
+    }
+    schedule();
+  };
+  source.addEventListener("change", onChange as EventListener);
+  source.addEventListener("head", schedule as EventListener);
+  return () => {
+    if (timer) clearTimeout(timer);
+    source.removeEventListener("change", onChange as EventListener);
+    source.removeEventListener("head", schedule as EventListener);
+    source.close();
+  };
+}
+
+/**
+ * Applies editor `doc` messages and SSE payloads through `renderPreview`
+ * and swaps the body. First paint is `children`.
+ */
+export function PreviewClient({
+  locale,
+  type,
+  slug,
+  branch,
+  tree,
+  dashboardOrigins = [],
+  renderPreview,
+  children,
+}: {
+  locale: string;
+  type: string;
+  slug: string;
+  branch?: string;
+  tree?: string;
+  dashboardOrigins?: string[];
+  renderPreview: PreviewRenderAction;
+  children?: ReactNode;
+}) {
+  const router = useRouter();
+  const [node, setNode] = useState<ReactNode>(null);
+  const [removed, setRemoved] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const originsKey = dashboardOrigins.join("\0");
+
+  useEffect(() => {
+    const ref: PreviewChannelRef = {
+      locale,
+      type,
+      slug,
+      ...(branch ? { branch } : {}),
+      ...(tree ? { tree } : {}),
+    };
+    // Framed by the dashboard's split view: the parent is the dashboard.
+    // Otherwise the Studio mounted on this site posts from same-origin frames.
+    const parentOrigin = referrerOrigin();
+    const selfOrigin = window.location.origin;
+    const allowed = [...originsKey.split("\0"), parentOrigin, selfOrigin].filter(
+      (origin) => origin.length > 0,
+    );
+    const framed = window.parent !== window;
+    const targetOrigin = framed ? parentOrigin || allowed[0] || "" : selfOrigin;
+    const windowTransport: PreviewTransport | null = targetOrigin
+      ? createWindowPreviewTransport({
+          target: framed ? window.parent : { postMessage() {} },
+          targetOrigin,
+          allowedOrigins: allowed,
+        })
+      : null;
+    const transport = fanInPreviewTransports(
+      windowTransport ? [windowTransport, sitePageTransport()] : [sitePageTransport()],
+    );
+    const checkoutToken =
+      new URLSearchParams(window.location.search).get(PREVIEW_CHECKOUT_QUERY) ?? undefined;
+    const refreshOthers = () => {
+      startTransition(() => router.refresh());
+    };
+    const unsubscribeTree = subscribeTreeStream(ref, refreshOthers);
+    const session = createPreviewPage({
+      ref,
+      transport,
+      subscribeSse: (onEvent) => subscribeDocStream(ref, onEvent),
+      renderer: async (_ref, doc) => {
+        const result = await renderPreview(ref, doc, checkoutToken);
+        if (!result.ok) return result;
+        return { ok: true, value: result.node };
+      },
+      handlers: {
+        onApplied: (_doc, value) => {
+          setError(null);
+          setRemoved(false);
+          setNode(value as ReactNode);
+        },
+        onError: (message) => setError(message),
+        onRemoved: () => {
+          setRemoved(true);
+          setError(null);
+        },
+        onNavigate: (path) => {
+          startTransition(() => router.push(path));
+        },
+      },
+    });
+    return () => {
+      unsubscribeTree();
+      session.close();
+      windowTransport?.close();
+    };
+  }, [locale, type, slug, branch, tree, renderPreview, router, originsKey]);
+
+  if (removed) return <PreviewRemoved />;
+  return (
+    <div data-backmatter-preview="">
+      {error ? <p role="alert">{error}</p> : null}
+      {node ?? children}
+    </div>
+  );
 }

package/src/preview-route.ts

@@ -3,28 +3,48 @@ import {
   PREVIEW_CHECKOUT_QUERY,
   PREVIEW_COOKIE,
   PREVIEW_COOKIE_TTL_MS,
+  PREVIEW_SESSION_COOKIE,
+  PREVIEW_SESSION_TTL_MS,
   previewLocationWithCheckout,
   readPreviewCookie,
   readPreviewTicket,
+  resolveDashboardUrl,
+  studioEnterUrl,
   writePreviewCookie,
   type PreviewCheckout,
 } from "@backmatter/core";
-import { previewStreamUrl } from "@backmatter/core/preview";
+import { previewStreamUrl, previewTreeStreamUrl } from "@backmatter/core/preview";
 import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
+import { MARKER_COOKIE, MARKER_TTL_S, safeReturnPath } from "./gate";
+import { requestUrlFrom } from "./request-url";
 
 export type PreviewRouteDeps = {
   enableDraft?: () => void | Promise<void>;
   disableDraft?: () => void | Promise<void>;
   isDraftEnabled?: () => boolean | Promise<boolean>;
   now?: () => number;
+  /** Dashboard that holds the login, for `?enter=1`. Default: `resolveDashboardUrl()`. */
+  dashboardUrl?: string;
 };
 
-function cookieBase(secure: boolean, maxAge: number, value: string) {
+/** The gate's marker: readable by the page script, so never HttpOnly. */
+function markerCookieHeader(secure: boolean, on: boolean): string {
+  const parts = [
+    `${MARKER_COOKIE}=${on ? "1" : ""}`,
+    "Path=/",
+    `Max-Age=${on ? MARKER_TTL_S : 0}`,
+    "SameSite=Lax",
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+function cookieBase(name: string, secure: boolean, maxAge: number, value: string) {
   // HTTPS is cross-site from the CMS iframe (dash → customer origin). Lax is
   // not sent there, so draftMode can be on while the checkout cookie is missing
   // (`invalid_session`). Partitioned (CHIPS) keeps the cookie in that embed.
   const parts = [
-    `${PREVIEW_COOKIE}=${value}`,
+    `${name}=${value}`,
     "Path=/",
     "HttpOnly",
     `Max-Age=${maxAge}`,
@@ -53,19 +73,19 @@ async function nextDraftEnabled(): Promise<boolean> {
   return (await mod.draftMode()).isEnabled;
 }
 
-function cookieFrom(req: Request): string | undefined {
+function cookieFrom(req: Request, name: string): 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("=");
+    const [key, ...rest] = part.trim().split("=");
+    if (key === name) return rest.join("=");
   }
   return undefined;
 }
 
 async function checkoutFrom(req: Request, secret: string, url: URL): Promise<PreviewCheckout | null> {
   return (
-    (await readPreviewCookie(secret, cookieFrom(req))) ??
+    (await readPreviewCookie(secret, cookieFrom(req, PREVIEW_COOKIE))) ??
     (await readPreviewCookie(secret, url.searchParams.get(PREVIEW_CHECKOUT_QUERY)?.trim()))
   );
 }
@@ -93,6 +113,23 @@ export function createPreviewRoute(
       return Response.json({ mode: draftOn ? "preview" : "live" });
     }
 
+    // The bar found the marker but no session: go top-level to the dashboard,
+    // which mints a ticket after login and returns to this page.
+    if (url.searchParams.get("enter") === "1") {
+      if (!cms.config.workspaceId) {
+        return Response.json({ error: "preview_not_configured" }, { status: 503 });
+      }
+      const returnUrl = requestUrlFrom(
+        (name) => req.headers.get(name),
+        safeReturnPath(url.searchParams.get("return")),
+      );
+      const dashboardUrl = resolveDashboardUrl(deps.dashboardUrl);
+      return Response.redirect(
+        studioEnterUrl(dashboardUrl, { workspaceId: cms.config.workspaceId, returnUrl }),
+        302,
+      );
+    }
+
     if (url.searchParams.get("stream") === "1") {
       if (!secret || !cms.config.apiUrl || !cms.config.workspaceId) {
         return new Response("preview not configured", { status: 503 });
@@ -117,6 +154,26 @@ export function createPreviewRoute(
       });
     }
 
+    if (url.searchParams.get("stream") === "tree") {
+      if (!secret || !cms.config.apiUrl || !cms.config.workspaceId) {
+        return new Response("preview not configured", { status: 503 });
+      }
+      const checkout = await checkoutFrom(req, secret, url);
+      if (!checkout) return new Response("preview session missing", { status: 401 });
+      const upstream = previewTreeStreamUrl(
+        { apiUrl: cms.config.apiUrl, workspaceId: cms.config.workspaceId, previewToken: secret },
+        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 });
@@ -131,24 +188,36 @@ export function createPreviewRoute(
     });
     await (deps.enableDraft ?? (() => nextDraft(true)))();
     const location = previewLocationWithCheckout(url.origin, payload.redirect, value);
-    return new Response(null, {
-      status: 302,
-      headers: {
-        Location: location,
-        "Set-Cookie": cookieBase(secure, Math.floor(PREVIEW_COOKIE_TTL_MS / 1000), value),
-      },
-    });
+    const headers = new Headers({ Location: location });
+    headers.append(
+      "Set-Cookie",
+      cookieBase(PREVIEW_COOKIE, secure, Math.floor(PREVIEW_COOKIE_TTL_MS / 1000), value),
+    );
+    if (payload.session) {
+      headers.append(
+        "Set-Cookie",
+        cookieBase(
+          PREVIEW_SESSION_COOKIE,
+          secure,
+          Math.floor(PREVIEW_SESSION_TTL_MS / 1000),
+          payload.session,
+        ),
+      );
+    }
+    // Entry opts the visitor in, so the bar shows on later pages without a param.
+    headers.append("Set-Cookie", markerCookieHeader(secure, true));
+    return new Response(null, { status: 302, headers });
   };
 
   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, ""),
-      },
-    });
+    const headers = new Headers();
+    headers.append("Set-Cookie", cookieBase(PREVIEW_COOKIE, secure, 0, ""));
+    headers.append("Set-Cookie", cookieBase(PREVIEW_SESSION_COOKIE, secure, 0, ""));
+    // Exit also drops the marker; otherwise the next page would bounce straight back in.
+    headers.append("Set-Cookie", markerCookieHeader(secure, false));
+    return new Response(null, { status: 204, headers });
   };
 
   return { GET, POST };
@@ -160,5 +229,5 @@ export async function loadPreviewCheckout(
 ): Promise<PreviewCheckout | null> {
   if (!secret) return null;
   const fake = new Request("http://local", { headers: cookieHeader ? { cookie: cookieHeader } : {} });
-  return readPreviewCookie(secret, cookieFrom(fake));
+  return readPreviewCookie(secret, cookieFrom(fake, PREVIEW_COOKIE));
 }

package/src/render-preview.ts

@@ -0,0 +1,186 @@
+// packages/next/src/render-preview.ts
+// Server action factory. Renders the editor's document with the host's
+// components. Refuses unless draft mode is on and the checkout tree matches.
+import {
+  PREVIEW_COOKIE,
+  PREVIEW_SESSION_COOKIE,
+  readPreviewCookie,
+  readPreviewSession,
+  type ModelDef,
+  type PreviewSessionClaims,
+} from "@backmatter/core";
+import type { ReactNode } from "react";
+import { renderLayoutDoc, type LayoutDocOptions } from "./layout-doc";
+import { previewContentForCheckout, runWithPreviewContent } from "./preview-content";
+import { requireSource, resolveSourceData } from "./source-data";
+
+export const RENDER_PREVIEW_PER_SECOND = 20;
+
+export type RenderPreviewRef = {
+  locale: string;
+  type: string;
+  slug: string;
+  branch?: string;
+  tree?: string;
+};
+
+export type RenderPreviewDoc = {
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
+export type RenderPreviewResult =
+  | { ok: true; node: ReactNode }
+  | { ok: false; error: string };
+
+export type RenderPreviewDeps = {
+  draftEnabled?: () => Promise<boolean> | boolean;
+  /** Checkout cookie value. The action argument is used when this is missing. */
+  readCheckoutToken?: () => Promise<string | undefined> | string | undefined;
+  /** Preview session cookie. Required. */
+  readSessionToken?: () => Promise<string | undefined> | string | undefined;
+  /** Epoch check. Default asks the CMS when apiUrl is set, and trusts the signature otherwise. */
+  sessionFresh?: (token: string, claims: PreviewSessionClaims) => Promise<boolean>;
+  now?: () => number;
+  limitPerSecond?: number;
+};
+
+type CmsLike = {
+  config: { previewToken?: string; apiUrl?: string; workspaceId?: string };
+  models: readonly ModelDef[];
+};
+
+const freshUntil = new Map<string, number>();
+
+async function defaultSessionFresh(apiUrl: string, token: string): Promise<boolean> {
+  const until = freshUntil.get(token);
+  if (until && until > Date.now()) return true;
+  const res = await fetch(`${apiUrl.replace(/\/$/, "")}/preview/session`, {
+    headers: { Authorization: `Bearer ${token}` },
+    cache: "no-store",
+  });
+  if (!res.ok) return false;
+  freshUntil.set(token, Date.now() + 30_000);
+  return true;
+}
+
+const hits = new Map<string, number[]>();
+
+export function resetRenderPreviewLimits(): void {
+  hits.clear();
+}
+
+function allowRender(key: string, now: number, limit: number): boolean {
+  const recent = (hits.get(key) ?? []).filter((at) => now - at < 1000);
+  if (recent.length >= limit) {
+    hits.set(key, recent);
+    return false;
+  }
+  recent.push(now);
+  hits.set(key, recent);
+  return true;
+}
+
+async function defaultDraftEnabled(): Promise<boolean> {
+  const mod = (await import("next/headers" as string)) as {
+    draftMode: () => Promise<{ isEnabled: boolean }>;
+  };
+  return (await mod.draftMode()).isEnabled;
+}
+
+async function cookieValue(name: string): Promise<string | undefined> {
+  const mod = (await import("next/headers" as string)) as {
+    cookies: () => Promise<{ get: (cookieName: string) => { value: string } | undefined }>;
+  };
+  return (await mod.cookies()).get(name)?.value;
+}
+
+async function defaultCheckoutToken(): Promise<string | undefined> {
+  return cookieValue(PREVIEW_COOKIE);
+}
+
+async function defaultSessionToken(): Promise<string | undefined> {
+  return cookieValue(PREVIEW_SESSION_COOKIE);
+}
+
+export function createRenderPreview(
+  cms: CmsLike,
+  options: Omit<LayoutDocOptions, "models"> = {},
+  deps: RenderPreviewDeps = {},
+) {
+  const draftEnabled = deps.draftEnabled ?? defaultDraftEnabled;
+  const readCheckoutToken = deps.readCheckoutToken ?? defaultCheckoutToken;
+  const readSessionToken = deps.readSessionToken ?? defaultSessionToken;
+  const now = deps.now ?? Date.now;
+  const limit = deps.limitPerSecond ?? RENDER_PREVIEW_PER_SECOND;
+  const secret = cms.config.previewToken ?? "";
+
+  return async function renderPreview(
+    ref: RenderPreviewRef,
+    doc: RenderPreviewDoc,
+    checkoutToken?: string,
+  ): Promise<RenderPreviewResult> {
+    if (!secret) return { ok: false, error: "unauthorized" };
+    if (!(await draftEnabled())) return { ok: false, error: "unauthorized" };
+    const token = (await readCheckoutToken()) || checkoutToken;
+    const checkout = await readPreviewCookie(secret, token);
+    if (!checkout?.tree || !ref.tree || checkout.tree !== ref.tree) {
+      return { ok: false, error: "unauthorized" };
+    }
+    if (checkout.branch && ref.branch && checkout.branch !== ref.branch) {
+      return { ok: false, error: "unauthorized" };
+    }
+    const sessionToken = await readSessionToken();
+    const session = await readPreviewSession(secret, sessionToken);
+    if (!session || session.tree !== ref.tree) return { ok: false, error: "unauthorized" };
+    if (cms.config.workspaceId && session.workspaceId !== cms.config.workspaceId) {
+      return { ok: false, error: "unauthorized" };
+    }
+    if (session.branch && ref.branch && session.branch !== ref.branch) {
+      return { ok: false, error: "unauthorized" };
+    }
+    const fresh =
+      deps.sessionFresh ??
+      (cms.config.apiUrl ? (value: string) => defaultSessionFresh(cms.config.apiUrl!, value) : null);
+    if (fresh && sessionToken && !(await fresh(sessionToken, session))) {
+      return { ok: false, error: "unauthorized" };
+    }
+    const key = `${checkout.branch ?? ""}:${checkout.tree}`;
+    if (!allowRender(key, now(), limit)) return { ok: false, error: "rate_limited" };
+    try {
+      const { apiUrl, workspaceId } = cms.config;
+      const content =
+        apiUrl && workspaceId
+          ? previewContentForCheckout({ apiUrl, workspaceId, previewToken: secret }, checkout)
+          : null;
+      // The editor's draft is the document; the outside record still comes from the source,
+      // so prices and images stay live while blocks change.
+      const model = cms.models.find((m) => m.type === ref.type);
+      let data: unknown;
+      if (model) {
+        const resolved = await resolveSourceData(requireSource(options.sources, model), model, ref);
+        if (!resolved.ok) return { ok: false, error: "record_not_found" };
+        data = resolved.data;
+      }
+      const node = await runWithPreviewContent(content, () =>
+        renderLayoutDoc(
+          {
+            locale: ref.locale,
+            type: ref.type,
+            slug: ref.slug,
+            source: "tree",
+            frontmatter: doc.frontmatter,
+            body: doc.body,
+            raw: doc.body,
+          },
+          { ...options, models: cms.models },
+          data,
+        ),
+      );
+      return { ok: true, node };
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Preview render failed";
+      return { ok: false, error: message };
+    }
+  };
+}

package/src/request-url.ts

@@ -0,0 +1,13 @@
+// packages/next/src/request-url.ts
+
+/** Absolute URL of the current request, from forwarded headers when behind a proxy. */
+export function requestUrlFrom(
+  get: (name: string) => string | null,
+  pathWithSearch: string,
+): string {
+  const host = get("x-forwarded-host") ?? get("host") ?? "localhost:3000";
+  const proto =
+    get("x-forwarded-proto") ??
+    (host.startsWith("localhost") || host.startsWith("127.0.0.1") ? "http" : "https");
+  return `${proto}://${host}${pathWithSearch}`;
+}

package/src/revalidate.ts

@@ -4,8 +4,8 @@
 import { timingSafeEqual } from "node:crypto";
 import {
   CONTENT_COMMITTED_EVENT,
-  BACKMATTER_CACHE_TAG,
   pathsForCommittedDocs,
+  revalidateTagsForCommit,
   type ContentCommittedEvent,
 } from "@backmatter/core";
 import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
@@ -57,7 +57,7 @@ export function createRevalidateRoute(
     const { revalidatePath, revalidateTag } = cache ?? (await loadNextCache());
     const paths = pathsForCommittedDocs(cms.models, body.docs ?? []);
     for (const path of paths) revalidatePath(path);
-    revalidateTag(BACKMATTER_CACHE_TAG, { expire: 0 });
+    for (const tag of revalidateTagsForCommit(body)) revalidateTag(tag, { expire: 0 });
     if (body.full) revalidatePath("/", "layout");
     return Response.json({ ok: true, paths });
   };