@backmatter/next 0.0.6 → 0.0.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
@@ -38,7 +38,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@backmatter/core": "^0.0.6",
+    "@backmatter/core": "^0.0.9",
     "@mdx-js/mdx": "^3.1.1",
     "remark-gfm": "^4.0.1"
   },

package/src/devbar-client.tsx

@@ -0,0 +1,280 @@
+// packages/next/src/devbar-client.tsx
+"use client";
+
+import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
+import {
+  clearHostPreviewSession,
+  fetchCmsSession,
+  fetchHostPreviewSession,
+  resolveDevMode,
+  type CmsSessionUser,
+} from "@backmatter/core/preview";
+
+export type { CmsSessionUser };
+
+export type DevModeState =
+  | { status: "hidden" }
+  | {
+      status: "ready";
+      user: CmsSessionUser;
+      mode: "preview" | "live";
+      branch?: string;
+      tree?: string;
+    };
+
+export function devModeState(
+  user: CmsSessionUser | null,
+  session: { enabled: boolean; branch?: string; tree?: string },
+): DevModeState {
+  if (!user) return { status: "hidden" };
+  const resolved = resolveDevMode(session);
+  return {
+    status: "ready",
+    user,
+    ...resolved,
+  };
+}
+
+export function useDevMode(options: { apiUrl: string }): DevModeState {
+  const [state, setState] = useState<DevModeState>({ status: "hidden" });
+
+  useEffect(() => {
+    const apiUrl = options.apiUrl.trim();
+    if (!apiUrl) return;
+    let cancelled = false;
+    void Promise.all([fetchCmsSession(apiUrl), fetchHostPreviewSession("")]).then(
+      ([user, session]) => {
+        if (cancelled) return;
+        setState(devModeState(user, session));
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [options.apiUrl]);
+
+  return state;
+}
+
+/** Above typical host sticky headers/modals; below max 32-bit int so a host can still overlay. */
+const DEVBAR_Z_INDEX = 2147483000;
+
+const barStyle: CSSProperties = {
+  position: "fixed",
+  bottom: 0,
+  left: "50%",
+  transform: "translateX(-50%)",
+  zIndex: DEVBAR_Z_INDEX,
+  isolation: "isolate",
+  pointerEvents: "auto",
+  display: "flex",
+  alignItems: "center",
+  gap: 10,
+  minHeight: 32,
+  maxWidth: "min(360px, calc(100vw - 24px))",
+  padding: "0 12px",
+  paddingBottom: "env(safe-area-inset-bottom, 0px)",
+  background: "#f4f4f5",
+  color: "#71717a",
+  border: "1px solid #e4e4e7",
+  borderBottom: "none",
+  borderTopLeftRadius: 8,
+  borderTopRightRadius: 8,
+  borderBottomLeftRadius: 0,
+  borderBottomRightRadius: 0,
+  fontFamily:
+    'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+  fontSize: 11,
+  fontWeight: 500,
+  lineHeight: "32px",
+  WebkitFontSmoothing: "antialiased",
+  fontVariantNumeric: "tabular-nums",
+  boxSizing: "border-box",
+};
+
+const brandStyle: CSSProperties = {
+  color: "#18181b",
+  letterSpacing: "-0.02em",
+};
+
+const itemStyle: CSSProperties = {
+  display: "inline-flex",
+  alignItems: "center",
+  gap: 6,
+  minWidth: 0,
+};
+
+const dividerStyle: CSSProperties = {
+  width: 1,
+  height: 12,
+  flexShrink: 0,
+  background: "#e4e4e7",
+};
+
+const branchTextStyle: CSSProperties = {
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+  maxWidth: 140,
+  color: "#18181b",
+};
+
+const exitButtonStyle: CSSProperties = {
+  appearance: "none",
+  border: "none",
+  background: "transparent",
+  padding: "0 2px",
+  margin: 0,
+  cursor: "pointer",
+  color: "#18181b",
+  fontFamily: "inherit",
+  fontSize: 11,
+  fontWeight: 500,
+  lineHeight: "32px",
+  minHeight: 32,
+  touchAction: "manipulation",
+  WebkitFontSmoothing: "antialiased",
+};
+
+function Dot({ color }: { color: string }) {
+  return (
+    <span
+      aria-hidden
+      style={{
+        width: 6,
+        height: 6,
+        borderRadius: 999,
+        background: color,
+        flexShrink: 0,
+      }}
+    />
+  );
+}
+
+function BranchIcon() {
+  return (
+    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden>
+      <circle cx="4.5" cy="4" r="1.75" stroke="currentColor" strokeWidth="1.25" />
+      <circle cx="11.5" cy="12" r="1.75" stroke="currentColor" strokeWidth="1.25" />
+      <circle cx="4.5" cy="12" r="1.75" stroke="currentColor" strokeWidth="1.25" />
+      <path
+        d="M4.5 5.75v4.5M4.5 8.5h4.2a3 3 0 0 1 3 3"
+        stroke="currentColor"
+        strokeWidth="1.25"
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}
+
+function Segment({ children }: { children: ReactNode }) {
+  return <span style={itemStyle}>{children}</span>;
+}
+
+function Divider() {
+  return <span aria-hidden style={dividerStyle} />;
+}
+
+export function DevBarView({
+  state,
+  onExit,
+  exiting,
+}: {
+  state: DevModeState;
+  onExit?: () => void;
+  exiting?: boolean;
+}) {
+  if (state.status !== "ready") return null;
+  const live = state.mode === "live";
+  const modeLabel = live ? "Live" : "Preview";
+  const draft = Boolean(state.tree);
+  const parts = ["backmatter", modeLabel];
+  if (state.branch) parts.push(state.branch);
+  if (draft) parts.push("draft");
+  const ariaLabel = parts.join(", ");
+
+  return (
+    <div role="status" aria-label={ariaLabel} style={barStyle}>
+      <style>{`
+        @media (hover: hover) {
+          button.backmatter-devbar-exit:hover:not(:disabled) { color: #71717a; }
+        }
+        button.backmatter-devbar-exit:focus-visible {
+          outline: 2px solid #18181b;
+          outline-offset: 2px;
+        }
+        button.backmatter-devbar-exit:disabled {
+          cursor: default;
+          opacity: 0.5;
+        }
+      `}</style>
+      <Segment>
+        <span style={brandStyle}>backmatter</span>
+      </Segment>
+      <Divider />
+      <Segment>
+        <Dot color={live ? "#059669" : "#2563eb"} />
+        <span style={{ color: "#18181b" }}>{modeLabel}</span>
+      </Segment>
+      {state.branch ? (
+        <>
+          <Divider />
+          <Segment>
+            <BranchIcon />
+            <span style={branchTextStyle}>{state.branch}</span>
+          </Segment>
+        </>
+      ) : null}
+      {draft ? (
+        <>
+          <Divider />
+          <Segment>draft</Segment>
+        </>
+      ) : null}
+      {!live ? (
+        <>
+          <Divider />
+          <button
+            type="button"
+            className="backmatter-devbar-exit"
+            aria-label="Exit preview"
+            disabled={exiting}
+            onClick={() => onExit?.()}
+            style={exitButtonStyle}
+          >
+            Exit
+          </button>
+        </>
+      ) : null}
+    </div>
+  );
+}
+
+export function DevBarClient({ apiUrl }: { apiUrl: string }) {
+  const state = useDevMode({ apiUrl });
+  const [exiting, setExiting] = useState(false);
+  return (
+    <DevBarView
+      state={state}
+      exiting={exiting}
+      onExit={() => {
+        if (exiting) return;
+        setExiting(true);
+        void exitHostPreview().then((ok) => {
+          if (!ok) setExiting(false);
+        });
+      }}
+    />
+  );
+}
+
+export async function exitHostPreview(
+  clear: (origin?: string) => Promise<boolean> = clearHostPreviewSession,
+  reload: () => void = () => {
+    location.reload();
+  },
+): Promise<boolean> {
+  const ok = await clear("");
+  if (ok) reload();
+  return ok;
+}

package/src/devbar.tsx

@@ -1,280 +1,18 @@
 // packages/next/src/devbar.tsx
-"use client";
-
-import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
-import {
-  clearHostPreviewSession,
-  fetchCmsSession,
-  fetchHostPreviewSession,
-  resolveDevMode,
+import { resolveDevBarApiUrl } from "@backmatter/core";
+import { DevBarClient } from "./devbar-client";
+
+export {
+  DevBarClient,
+  DevBarView,
+  devModeState,
+  exitHostPreview,
+  useDevMode,
   type CmsSessionUser,
-} from "@backmatter/core/preview";
-
-export type { CmsSessionUser };
-
-export type DevModeState =
-  | { status: "hidden" }
-  | {
-      status: "ready";
-      user: CmsSessionUser;
-      mode: "preview" | "live";
-      branch?: string;
-      tree?: string;
-    };
-
-export function devModeState(
-  user: CmsSessionUser | null,
-  session: { enabled: boolean; branch?: string; tree?: string },
-): DevModeState {
-  if (!user) return { status: "hidden" };
-  const resolved = resolveDevMode(session);
-  return {
-    status: "ready",
-    user,
-    ...resolved,
-  };
-}
-
-export function useDevMode(options: { apiUrl: string }): DevModeState {
-  const [state, setState] = useState<DevModeState>({ status: "hidden" });
-
-  useEffect(() => {
-    const apiUrl = options.apiUrl.trim();
-    if (!apiUrl) return;
-    let cancelled = false;
-    void Promise.all([fetchCmsSession(apiUrl), fetchHostPreviewSession("")]).then(
-      ([user, session]) => {
-        if (cancelled) return;
-        setState(devModeState(user, session));
-      },
-    );
-    return () => {
-      cancelled = true;
-    };
-  }, [options.apiUrl]);
-
-  return state;
-}
-
-/** Above typical host sticky headers/modals; below max 32-bit int so a host can still overlay. */
-const DEVBAR_Z_INDEX = 2147483000;
-
-const barStyle: CSSProperties = {
-  position: "fixed",
-  bottom: 0,
-  left: "50%",
-  transform: "translateX(-50%)",
-  zIndex: DEVBAR_Z_INDEX,
-  isolation: "isolate",
-  pointerEvents: "auto",
-  display: "flex",
-  alignItems: "center",
-  gap: 10,
-  minHeight: 32,
-  maxWidth: "min(360px, calc(100vw - 24px))",
-  padding: "0 12px",
-  paddingBottom: "env(safe-area-inset-bottom, 0px)",
-  background: "#f4f4f5",
-  color: "#71717a",
-  border: "1px solid #e4e4e7",
-  borderBottom: "none",
-  borderTopLeftRadius: 8,
-  borderTopRightRadius: 8,
-  borderBottomLeftRadius: 0,
-  borderBottomRightRadius: 0,
-  fontFamily:
-    'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
-  fontSize: 11,
-  fontWeight: 500,
-  lineHeight: "32px",
-  WebkitFontSmoothing: "antialiased",
-  fontVariantNumeric: "tabular-nums",
-  boxSizing: "border-box",
-};
-
-const brandStyle: CSSProperties = {
-  color: "#18181b",
-  letterSpacing: "-0.02em",
-};
-
-const itemStyle: CSSProperties = {
-  display: "inline-flex",
-  alignItems: "center",
-  gap: 6,
-  minWidth: 0,
-};
-
-const dividerStyle: CSSProperties = {
-  width: 1,
-  height: 12,
-  flexShrink: 0,
-  background: "#e4e4e7",
-};
-
-const branchTextStyle: CSSProperties = {
-  overflow: "hidden",
-  textOverflow: "ellipsis",
-  whiteSpace: "nowrap",
-  maxWidth: 140,
-  color: "#18181b",
-};
-
-const exitButtonStyle: CSSProperties = {
-  appearance: "none",
-  border: "none",
-  background: "transparent",
-  padding: "0 2px",
-  margin: 0,
-  cursor: "pointer",
-  color: "#18181b",
-  fontFamily: "inherit",
-  fontSize: 11,
-  fontWeight: 500,
-  lineHeight: "32px",
-  minHeight: 32,
-  touchAction: "manipulation",
-  WebkitFontSmoothing: "antialiased",
-};
-
-function Dot({ color }: { color: string }) {
-  return (
-    <span
-      aria-hidden
-      style={{
-        width: 6,
-        height: 6,
-        borderRadius: 999,
-        background: color,
-        flexShrink: 0,
-      }}
-    />
-  );
-}
-
-function BranchIcon() {
-  return (
-    <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden>
-      <circle cx="4.5" cy="4" r="1.75" stroke="currentColor" strokeWidth="1.25" />
-      <circle cx="11.5" cy="12" r="1.75" stroke="currentColor" strokeWidth="1.25" />
-      <circle cx="4.5" cy="12" r="1.75" stroke="currentColor" strokeWidth="1.25" />
-      <path
-        d="M4.5 5.75v4.5M4.5 8.5h4.2a3 3 0 0 1 3 3"
-        stroke="currentColor"
-        strokeWidth="1.25"
-        strokeLinecap="round"
-      />
-    </svg>
-  );
-}
-
-function Segment({ children }: { children: ReactNode }) {
-  return <span style={itemStyle}>{children}</span>;
-}
-
-function Divider() {
-  return <span aria-hidden style={dividerStyle} />;
-}
-
-export function DevBarView({
-  state,
-  onExit,
-  exiting,
-}: {
-  state: DevModeState;
-  onExit?: () => void;
-  exiting?: boolean;
-}) {
-  if (state.status !== "ready") return null;
-  const live = state.mode === "live";
-  const modeLabel = live ? "Live" : "Preview";
-  const draft = Boolean(state.tree);
-  const parts = ["backmatter", modeLabel];
-  if (state.branch) parts.push(state.branch);
-  if (draft) parts.push("draft");
-  const ariaLabel = parts.join(", ");
-
-  return (
-    <div role="status" aria-label={ariaLabel} style={barStyle}>
-      <style>{`
-        @media (hover: hover) {
-          button.backmatter-devbar-exit:hover:not(:disabled) { color: #71717a; }
-        }
-        button.backmatter-devbar-exit:focus-visible {
-          outline: 2px solid #18181b;
-          outline-offset: 2px;
-        }
-        button.backmatter-devbar-exit:disabled {
-          cursor: default;
-          opacity: 0.5;
-        }
-      `}</style>
-      <Segment>
-        <span style={brandStyle}>backmatter</span>
-      </Segment>
-      <Divider />
-      <Segment>
-        <Dot color={live ? "#059669" : "#2563eb"} />
-        <span style={{ color: "#18181b" }}>{modeLabel}</span>
-      </Segment>
-      {state.branch ? (
-        <>
-          <Divider />
-          <Segment>
-            <BranchIcon />
-            <span style={branchTextStyle}>{state.branch}</span>
-          </Segment>
-        </>
-      ) : null}
-      {draft ? (
-        <>
-          <Divider />
-          <Segment>draft</Segment>
-        </>
-      ) : null}
-      {!live ? (
-        <>
-          <Divider />
-          <button
-            type="button"
-            className="backmatter-devbar-exit"
-            aria-label="Exit preview"
-            disabled={exiting}
-            onClick={() => onExit?.()}
-            style={exitButtonStyle}
-          >
-            Exit
-          </button>
-        </>
-      ) : null}
-    </div>
-  );
-}
-
-export function DevBar({ apiUrl }: { apiUrl: string }) {
-  const state = useDevMode({ apiUrl });
-  const [exiting, setExiting] = useState(false);
-  return (
-    <DevBarView
-      state={state}
-      exiting={exiting}
-      onExit={() => {
-        if (exiting) return;
-        setExiting(true);
-        void exitHostPreview().then((ok) => {
-          if (!ok) setExiting(false);
-        });
-      }}
-    />
-  );
-}
+  type DevModeState,
+} from "./devbar-client";
 
-export async function exitHostPreview(
-  clear: (origin?: string) => Promise<boolean> = clearHostPreviewSession,
-  reload: () => void = () => {
-    location.reload();
-  },
-): Promise<boolean> {
-  const ok = await clear("");
-  if (ok) reload();
-  return ok;
+/** Host layout: `<DevBar />`. Optional apiUrl for local/self-hosted CMS. */
+export function DevBar({ apiUrl }: { apiUrl?: string } = {}) {
+  return <DevBarClient apiUrl={resolveDevBarApiUrl(apiUrl)} />;
 }

package/src/page-render.ts

@@ -1,5 +1,5 @@
 // packages/next/src/page-render.ts
-import { Suspense, createElement, type ComponentType, type ReactNode } from "react";
+import { createElement, type ComponentType, type ReactNode } from "react";
 import { imageUrlFromUnknown, type BackmatterDoc } from "@backmatter/core";
 
 export type BlockModule = Record<string, unknown>;
@@ -50,17 +50,24 @@ export function asBlockLoader(type: string, value: ComponentType<any> | BlockLoa
 
 const resolvedBlocks = new WeakMap<BlockLoader, Promise<ComponentType<any> | undefined>>();
 
+async function loadBlockComponent(
+  type: string,
+  loader: BlockLoader,
+): Promise<ComponentType<any> | undefined> {
+  let pending = resolvedBlocks.get(loader);
+  if (!pending) {
+    pending = loader().then((mod) => resolveBlockComponent(mod, type));
+    resolvedBlocks.set(loader, pending);
+  }
+  return pending;
+}
+
 export async function LazyBlock(props: {
   type: string;
   loader: BlockLoader;
   blockProps: Record<string, unknown>;
 }) {
-  let pending = resolvedBlocks.get(props.loader);
-  if (!pending) {
-    pending = props.loader().then((mod) => resolveBlockComponent(mod, props.type));
-    resolvedBlocks.set(props.loader, pending);
-  }
-  const Cmp = await pending;
+  const Cmp = await loadBlockComponent(props.type, props.loader);
   if (!Cmp) {
     console.warn(`[backmatter] skipping unknown block type "${props.type}"`);
     return null;
@@ -69,43 +76,37 @@ export async function LazyBlock(props: {
 }
 
 /** Render a page document's `blocks` array. Unknown types are skipped. */
-export function renderPage(
+export async function renderPage(
   doc: Pick<BackmatterDoc, "frontmatter">,
   components?: BlockComponents,
-  fallbacks?: BlockFallbacks,
-): ReactNode {
+  _fallbacks?: BlockFallbacks,
+): Promise<ReactNode> {
   const blocks = asBlocks(doc.frontmatter.blocks);
-  const children: ReactNode[] = [];
-  for (const block of blocks) {
-    if (typeof block.type !== "string") continue;
-    const entry = components?.[block.type];
-    if (!entry) {
-      console.warn(`[backmatter] skipping unknown block type "${block.type}"`);
-      continue;
-    }
-    const raw =
-      block.props && typeof block.props === "object" && !Array.isArray(block.props)
-        ? (block.props as Record<string, unknown>)
-        : {};
-    const props: Record<string, unknown> = {};
-    for (const [name, value] of Object.entries(raw)) {
-      props[name] = imageUrlFromUnknown(value);
-    }
-    const key = typeof block.id === "string" ? block.id : undefined;
-    children.push(
-      createElement(
-        Suspense,
-        {
-          key,
-          fallback: createElement(fallbacks?.[block.type] ?? BlockSkeleton),
-        },
-        createElement(LazyBlock, {
-          type: block.type,
-          loader: asBlockLoader(block.type, entry),
-          blockProps: props,
-        }),
-      ),
-    );
-  }
-  return children.length === 0 ? null : children;
+  const children = await Promise.all(
+    blocks.map(async (block) => {
+      if (typeof block.type !== "string") return null;
+      const entry = components?.[block.type];
+      if (!entry) {
+        console.warn(`[backmatter] skipping unknown block type "${block.type}"`);
+        return null;
+      }
+      const raw =
+        block.props && typeof block.props === "object" && !Array.isArray(block.props)
+          ? (block.props as Record<string, unknown>)
+          : {};
+      const props: Record<string, unknown> = {};
+      for (const [name, value] of Object.entries(raw)) {
+        props[name] = imageUrlFromUnknown(value);
+      }
+      const Cmp = await loadBlockComponent(block.type, asBlockLoader(block.type, entry));
+      if (!Cmp) {
+        console.warn(`[backmatter] skipping unknown block type "${block.type}"`);
+        return null;
+      }
+      const key = typeof block.id === "string" ? block.id : undefined;
+      return createElement(Cmp, { key, ...props });
+    }),
+  );
+  const rendered = children.filter((child) => child != null);
+  return rendered.length === 0 ? null : rendered;
 }

package/src/preview-live.tsx

@@ -2,7 +2,7 @@
 "use client";
 
 import { useEffect, useState, type ReactNode } from "react";
-import type { BackmatterDoc } from "@backmatter/core";
+import { PREVIEW_CHECKOUT_QUERY, type BackmatterDoc } from "@backmatter/core";
 import type { PreviewChangeEvent } from "@backmatter/core/preview";
 import { MdxBody, type MdxComponents } from "./mdx-client";
 
@@ -22,6 +22,8 @@ function streamUrl(ref: { locale: string; type: string; slug: string }) {
     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);
   return `/api/backmatter/preview?${params}`;
 }
 

package/src/preview-route.ts

@@ -1,7 +1,9 @@
 // packages/next/src/preview-route.ts
 import {
+  PREVIEW_CHECKOUT_QUERY,
   PREVIEW_COOKIE,
   PREVIEW_COOKIE_TTL_MS,
+  previewLocationWithCheckout,
   readPreviewCookie,
   readPreviewTicket,
   writePreviewCookie,
@@ -17,14 +19,20 @@ export type PreviewRouteDeps = {
 };
 
 function cookieBase(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}`,
     "Path=/",
     "HttpOnly",
-    "SameSite=Lax",
     `Max-Age=${maxAge}`,
   ];
-  if (secure) parts.push("Secure");
+  if (secure) {
+    parts.push("SameSite=None", "Secure", "Partitioned");
+  } else {
+    parts.push("SameSite=Lax");
+  }
   return parts.join("; ");
 }
 
@@ -47,6 +55,13 @@ function cookieFrom(req: Request): string | undefined {
   return undefined;
 }
 
+async function checkoutFrom(req: Request, secret: string, url: URL): Promise<PreviewCheckout | null> {
+  return (
+    (await readPreviewCookie(secret, cookieFrom(req))) ??
+    (await readPreviewCookie(secret, url.searchParams.get(PREVIEW_CHECKOUT_QUERY)?.trim()))
+  );
+}
+
 export function createPreviewRoute(
   cms: Pick<BackmatterClient, "config">,
   deps: PreviewRouteDeps = {},
@@ -59,7 +74,7 @@ export function createPreviewRoute(
     const secure = url.protocol === "https:";
 
     if (url.searchParams.get("session") === "1") {
-      const checkout = secret ? await readPreviewCookie(secret, cookieFrom(req)) : null;
+      const checkout = secret ? await checkoutFrom(req, secret, url) : null;
       if (!checkout) return Response.json({ mode: "live" });
       return Response.json({
         mode: "preview",
@@ -71,7 +86,7 @@ export function createPreviewRoute(
       if (!secret || !cms.config.apiUrl || !cms.config.workspaceId) {
         return new Response("preview not configured", { status: 503 });
       }
-      const checkout = await readPreviewCookie(secret, cookieFrom(req));
+      const checkout = await checkoutFrom(req, secret, url);
       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") ?? "";
@@ -104,7 +119,7 @@ export function createPreviewRoute(
       exp: now() + PREVIEW_COOKIE_TTL_MS,
     });
     await (deps.enableDraft ?? (() => nextDraft(true)))();
-    const location = new URL(payload.redirect, url.origin).toString();
+    const location = previewLocationWithCheckout(url.origin, payload.redirect, value);
     return new Response(null, {
       status: 302,
       headers: {

package/src/revalidate.ts

@@ -12,7 +12,7 @@ import type { BackmatterClient } from "@backmatter/core/node/create-backmatter";
 
 export type RevalidateCache = {
   revalidatePath: (path: string, type?: "layout" | "page") => void;
-  revalidateTag: (tag: string) => void;
+  revalidateTag: (tag: string, profile?: string | { expire?: number }) => void;
 };
 
 function extractBearer(header: string | null): string | null {
@@ -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);
+    revalidateTag(BACKMATTER_CACHE_TAG, { expire: 0 });
     if (body.full) revalidatePath("/", "layout");
     return Response.json({ ok: true, paths });
   };

package/src/routes.ts

@@ -3,15 +3,13 @@
 // 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 { Fragment, Suspense, createElement, type ReactNode } from "react";
+import { matchRoute, modelFormat, PREVIEW_CHECKOUT_QUERY, 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 { renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
 import { previewUnavailable } from "./preview-ui";
 
 export const CATCH_ALL_PARAM = "backmatter";
@@ -25,7 +23,7 @@ export type CatchAllOptions = {
   components?: MdxComponents;
   /** Composer map, usually the generated `blocks`. */
   blocks?: BlockComponents;
-  /** Per-block Suspense fallbacks for page-format documents. */
+  /** Kept for host compatibility. Published pages resolve blocks before paint. */
   fallbacks?: BlockFallbacks;
   /** Per-type wrappers, usually the generated `layouts`. */
   layouts?: Record<string, DocLayout>;
@@ -58,9 +56,17 @@ export type CatchAllOptions = {
 
 export type CatchAllMetadata = { title?: string };
 
+export type CatchAllSearchParams = Record<string, string | string[] | undefined>;
+
 export type CatchAllRoute = {
-  Page: (props: { params: Promise<CatchAllParams> }) => ReactNode;
-  CmsRoute: (props: { params: Promise<CatchAllParams> | CatchAllParams }) => Promise<ReactNode>;
+  Page: (props: {
+    params: Promise<CatchAllParams>;
+    searchParams?: Promise<CatchAllSearchParams>;
+  }) => ReactNode;
+  CmsRoute: (props: {
+    params: Promise<CatchAllParams> | CatchAllParams;
+    searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
+  }) => Promise<ReactNode>;
   generateStaticParams: () => Promise<CatchAllParams[]>;
   generateMetadata: (props: {
     params: Promise<CatchAllParams>;
@@ -81,9 +87,23 @@ type PreviewState =
   | { enabled: false }
   | { enabled: true; checkout: { branch?: string; tree?: string }; error?: string };
 
+type RouteHit = { locale: string; type: string; slug: string };
+
+async function checkoutQueryToken(
+  searchParams: Promise<CatchAllSearchParams> | CatchAllSearchParams | undefined,
+): Promise<string | undefined> {
+  if (!searchParams) return undefined;
+  const query = await searchParams;
+  const raw = query[PREVIEW_CHECKOUT_QUERY];
+  const value = Array.isArray(raw) ? raw[0] : raw;
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
 async function resolvePreviewState(
   cms: Pick<BackmatterClient, "config">,
   injected: CatchAllOptions["preview"],
+  searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams,
 ): Promise<PreviewState> {
   if (injected) {
     if (!injected.enabled) return { enabled: false };
@@ -99,7 +119,9 @@ async function resolvePreviewState(
     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);
+    const checkout =
+      (await readPreviewCookie(secret, raw)) ??
+      (await readPreviewCookie(secret, await checkoutQueryToken(searchParams)));
     if (!checkout) return { enabled: true, checkout: {}, error: "invalid_session" };
     return { enabled: true, checkout };
   } catch {
@@ -135,81 +157,128 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     return params;
   };
 
-  const PageFallback = BlockSkeleton;
+  const failFor = options.notFound ?? nextNotFound;
 
-  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);
+  async function layoutDoc(doc: BackmatterDoc, previewEnabled: boolean): Promise<ReactNode> {
+    const model = byType.get(doc.type);
     const isPage = Boolean(model && modelFormat(model) === "page");
     const rendered = isPage
-      ? renderPage(doc, options.blocks, options.fallbacks)
+      ? await 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;
+    let body = rendered;
+    if (!isPage && previewEnabled) {
+      const { PreviewBody } = await import("./preview-live");
+      body = createElement(PreviewBody, { doc, components: options.components }, rendered);
+    }
+    if (previewEnabled && isPage) {
+      const { PreviewPageReloader } = await import("./preview-refresh");
+      body = createElement(
+        "div",
+        null,
+        createElement(PreviewPageReloader, {
+          locale: doc.locale,
+          type: doc.type,
+          slug: doc.slug,
+        }),
+        body,
+      );
+    }
+    const layout = options.layouts?.[doc.type];
+    const laidOut = layout ? layout(doc, body) : body;
     if (options.render) return options.render(doc, laidOut);
     if (layout || isPage) return laidOut;
     return createElement("article", null, laidOut);
+  }
+
+  async function loadPreviewDoc(
+    hit: RouteHit,
+    preview: Extract<PreviewState, { enabled: true }>,
+  ): Promise<ReactNode> {
+    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,
+          ));
+      const doc = await getDoc({
+        locale: hit.locale,
+        type: hit.type,
+        slug: hit.slug,
+        ...preview.checkout,
+      });
+      if (!doc) return previewUnavailable("Document not found");
+      return layoutDoc(doc, true);
+    } catch (err) {
+      return previewUnavailable(err instanceof Error ? err.message : "Failed to load");
+    }
+  }
+
+  const CmsRoute: CatchAllRoute["CmsRoute"] = async ({ params, searchParams }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    if (!hit) return failFor();
+    const preview = await resolvePreviewState(cms, options.preview, searchParams);
+    if (preview.enabled) return loadPreviewDoc(hit, preview);
+    const doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    if (!doc) return failFor();
+    return layoutDoc(doc, false);
+  };
+
+  const PublishedRoute = async ({
+    params,
+  }: {
+    params: Promise<CatchAllParams> | CatchAllParams;
+    searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
+  }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    if (!hit) return failFor();
+    const doc = await getCachedDoc(hit.locale, hit.type, hit.slug);
+    if (!doc) return failFor();
+    return createElement(
+      "div",
+      { "data-backmatter-published": "", style: { display: "contents" } },
+      await layoutDoc(doc, false),
+    );
+  };
+
+  const PreviewBranch = async ({
+    params,
+    searchParams,
+  }: {
+    params: Promise<CatchAllParams> | CatchAllParams;
+    searchParams?: Promise<CatchAllSearchParams> | CatchAllSearchParams;
+  }) => {
+    const resolved = await params;
+    const hit = resolve(resolved[CATCH_ALL_PARAM]);
+    if (!hit) return null;
+    const preview = await resolvePreviewState(cms, options.preview, searchParams);
+    if (!preview.enabled) return null;
+    return createElement(
+      Fragment,
+      null,
+      createElement("style", {
+        dangerouslySetInnerHTML: {
+          __html: "[data-backmatter-published]{display:none!important}",
+        },
+      }),
+      await loadPreviewDoc(hit, preview),
+    );
   };
 
   const Page: CatchAllRoute["Page"] = (props) =>
     createElement(
-      Suspense,
-      { fallback: createElement(PageFallback) },
-      createElement(CmsRoute, props),
+      Fragment,
+      null,
+      createElement(PublishedRoute, props),
+      createElement(Suspense, { fallback: null }, createElement(PreviewBranch, props)),
     );
 
   const generateMetadata: CatchAllRoute["generateMetadata"] = async ({ params }) => {