@backmatter/next 0.0.26 → 0.0.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/next",
-  "version": "0.0.26",
+  "version": "0.0.28",
   "description": "Experimental Next.js adapter for Backmatter. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {
@@ -47,10 +47,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@backmatter/core": "^0.0.21",
+    "@backmatter/core": "^0.0.22",
     "@mdx-js/mdx": "^3.1.1",
     "remark-gfm": "^4.0.1",
-    "@backmatter/studio": "^0.0.4"
+    "@backmatter/studio": "^0.0.6"
   },
   "peerDependencies": {
     "next": ">=16.3.0",

package/src/devbar-client.tsx

@@ -6,6 +6,8 @@ import {
   clearHostPreviewSession,
   fetchCmsSession,
   fetchHostPreviewSession,
+  setHostSiteLive,
+  setHostSitePreview,
   resolveDevMode,
   type CmsSessionUser,
   type HostSessionReason,
@@ -47,6 +49,7 @@ export type SessionGateAction = "show" | "bounce" | "quiet" | "wait";
  */
 export function sessionGateAction(input: {
   explicit: boolean;
+  /** Host session verified (preview or signed-in live). */
   enabled: boolean;
   reason: HostSessionReason;
   recentAttempt: boolean;
@@ -59,9 +62,15 @@ export function sessionGateAction(input: {
 
 export function devModeState(
   user: CmsSessionUser | null,
-  session: { enabled: boolean; branch?: string; tree?: string; reason?: HostSessionReason },
+  session: {
+    enabled: boolean;
+    signedIn?: boolean;
+    branch?: string;
+    tree?: string;
+    reason?: HostSessionReason;
+  },
 ): DevModeState {
-  if (!user && !session.enabled) {
+  if (!user && !session.enabled && !session.signedIn) {
     return session.reason ? { status: "hidden", reason: session.reason } : { status: "hidden" };
   }
   const resolved = resolveDevMode(session);
@@ -339,11 +348,11 @@ function useSiteSession(gate: Gate, previewEntryPath: string): DevModeState {
     let cancelled = false;
     void loadDevModeState("").then((next) => {
       if (cancelled) return;
-      const enabled = next.status === "ready" && next.mode === "preview";
+      const showBar = next.status === "ready";
       const reason = next.status === "hidden" ? (next.reason ?? "anonymous") : "anonymous";
       const action = sessionGateAction({
         explicit: gate === "enter",
-        enabled,
+        enabled: showBar,
         reason,
         recentAttempt: recentEnterAttempt(sessionStorage.getItem(ENTER_ATTEMPT_KEY), Date.now()),
       });
@@ -376,38 +385,48 @@ function useSiteSession(gate: Gate, previewEntryPath: string): DevModeState {
 export function DevBarClient({
   studioPath,
   previewEntryPath = DEFAULT_PREVIEW_ENTRY_PATH,
+  previewFrame,
 }: {
   /** Unused since the bar stopped calling the CMS origin; kept for host layouts that still pass it. */
   apiUrl?: string;
   studioPath?: string;
   previewEntryPath?: string;
+  previewFrame?: boolean;
 }) {
   const gate = useGate();
   const state = useSiteSession(gate, previewEntryPath);
   const [exiting, setExiting] = useState(false);
-  const exit = () => {
+  const [entering, setEntering] = useState(false);
+  const goLive = () => {
     if (exiting) return;
     setExiting(true);
-    void exitHostPreview().then((ok) => {
+    void goHostSiteLive().then((ok) => {
       if (!ok) setExiting(false);
     });
   };
+  const goPreview = () => {
+    if (entering) return;
+    setEntering(true);
+    void enterHostPreview().then((ok) => {
+      if (!ok) setEntering(false);
+    });
+  };
   if (state.status !== "ready") return null;
-  if (state.mode === "preview") {
-    return (
-      <Suspense fallback={null}>
-        <SiteChrome
-          branch={state.branch}
-          tree={state.tree}
-          exiting={exiting}
-          onExit={exit}
-          studioPath={studioPath}
-          previewEntryPath={previewEntryPath}
-        />
-      </Suspense>
-    );
-  }
-  return <DevBarView state={state} exiting={exiting} onExit={exit} />;
+  return (
+    <Suspense fallback={null}>
+      <SiteChrome
+        branch={state.branch}
+        tree={state.tree}
+        siteMode={state.mode}
+        exiting={exiting || entering}
+        onExit={goLive}
+        onEnterPreview={goPreview}
+        studioPath={studioPath}
+        previewEntryPath={previewEntryPath}
+        previewFrame={state.mode === "preview" ? previewFrame : false}
+      />
+    </Suspense>
+  );
 }
 
 export async function exitHostPreview(
@@ -420,3 +439,25 @@ export async function exitHostPreview(
   if (ok) reload();
   return ok;
 }
+
+export async function goHostSiteLive(
+  live: (origin?: string) => Promise<boolean> = setHostSiteLive,
+  reload: () => void = () => {
+    location.reload();
+  },
+): Promise<boolean> {
+  const ok = await live("");
+  if (ok) reload();
+  return ok;
+}
+
+export async function enterHostPreview(
+  preview: (origin?: string) => Promise<boolean> = setHostSitePreview,
+  reload: () => void = () => {
+    location.reload();
+  },
+): Promise<boolean> {
+  const ok = await preview("");
+  if (ok) reload();
+  return ok;
+}

package/src/devbar.tsx

@@ -18,23 +18,31 @@ export {
 /**
  * Host layout: `<DevBar />`. Public visitors get a gate of a few hundred
  * bytes that makes no request. The bar appears only when the site session
- * verifies. `?backmatter=1` or ⌘⇧E with no session sends the whole window to
+ * verifies (preview or signed-in live). `?backmatter=1` or ⌘⇧E with no session sends the whole window to
  * the dashboard; a leftover `bm_ui` marker stays on the public page.
  * `studioPath` is where `@backmatter/studio` is mounted on this site
  * (default `/backmatter`); the bar's panels are frames of that route.
  * `previewEntryPath` is the ticket route (default `/api/backmatter/preview`).
+ * `previewFrame` draws a viewport ring and top pill while preview is active.
  * `apiUrl` is accepted for older layouts and no longer used.
  */
 export function DevBar({
   apiUrl,
   studioPath,
   previewEntryPath,
-}: { apiUrl?: string; studioPath?: string; previewEntryPath?: string } = {}) {
+  previewFrame,
+}: {
+  apiUrl?: string;
+  studioPath?: string;
+  previewEntryPath?: string;
+  previewFrame?: boolean;
+} = {}) {
   return (
     <DevBarClient
       apiUrl={resolveDevBarApiUrl(apiUrl)}
       studioPath={studioPath}
       previewEntryPath={previewEntryPath}
+      previewFrame={previewFrame}
     />
   );
 }

package/src/preview-hold.tsx

@@ -0,0 +1,39 @@
+// packages/next/src/preview-hold.tsx
+"use client";
+
+// A route refresh suspends the preview branch. Its Suspense fallback would
+// otherwise be empty for the whole fetch. The last painted preview is kept
+// here, outside that branch, and shown until the next one is ready.
+import { useEffect, useSyncExternalStore, type ReactNode } from "react";
+
+let held: ReactNode = null;
+const listeners = new Set<() => void>();
+
+function emit() {
+  for (const listener of listeners) listener();
+}
+
+function subscribe(listener: () => void) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function clearHeldPreview() {
+  if (held === null) return;
+  held = null;
+  emit();
+}
+
+/** Remember the preview that just painted, so a later refresh can keep it. */
+export function HoldPreview({ children }: { children: ReactNode }) {
+  useEffect(() => {
+    held = children;
+    emit();
+  }, [children]);
+  return children;
+}
+
+/** Suspense fallback: the previous preview, or nothing on the first load. */
+export function HeldPreview() {
+  return useSyncExternalStore(subscribe, () => held, () => null);
+}

package/src/preview-route.ts

@@ -179,8 +179,25 @@ export function createPreviewRoute(
         );
       }
       if (verdict !== "ok") return clearLogin();
+      const draftOn = await (deps.isDraftEnabled ?? nextDraftEnabled)();
+      const checkout = secret ? await checkoutFrom(req, secret, url) : null;
+      if (draftOn && checkout) {
+        return Response.json(
+          {
+            mode: "preview",
+            branch: checkout.branch ?? claims.branch,
+            tree: checkout.tree ?? claims.tree,
+          },
+          { headers: { "Cache-Control": "no-store" } },
+        );
+      }
       return Response.json(
-        { mode: "preview", branch: claims.branch, tree: claims.tree },
+        {
+          mode: "live",
+          signedIn: true,
+          branch: claims.branch,
+          tree: claims.tree,
+        },
         { headers: { "Cache-Control": "no-store" } },
       );
     }
@@ -310,8 +327,43 @@ export function createPreviewRoute(
       return new Response(null, { status: 204, headers });
     }
 
+    const secure = url.protocol === "https:";
+
+    if (url.searchParams.get("live") === "1") {
+      await (deps.disableDraft ?? (() => nextDraft(false)))();
+      const headers = new Headers();
+      headers.append("Set-Cookie", cookieBase(PREVIEW_COOKIE, secure, 0, ""));
+      return new Response(null, { status: 204, headers });
+    }
+
+    if (url.searchParams.get("preview") === "1") {
+      const token = cookieFrom(req, PREVIEW_SESSION_COOKIE);
+      const claims = secret && token ? await readPreviewSession(secret, token) : null;
+      const workspaceOk = !cms.config.workspaceId || claims?.workspaceId === cms.config.workspaceId;
+      if (!claims || !token || !workspaceOk) {
+        return Response.json({ error: "unauthorized" }, { status: 401 });
+      }
+      const confirm = deps.confirmSession ?? ((current: string) => confirmSessionOnApi(cms.config.apiUrl, current));
+      const verdict = await confirm(token);
+      if (verdict !== "ok") {
+        return Response.json({ error: "unauthorized" }, { status: 401 });
+      }
+      const value = await writePreviewCookie(secret, {
+        branch: claims.branch,
+        tree: claims.tree,
+        exp: now() + PREVIEW_COOKIE_TTL_MS,
+      });
+      await (deps.enableDraft ?? (() => nextDraft(true)))();
+      const headers = new Headers();
+      headers.append(
+        "Set-Cookie",
+        cookieBase(PREVIEW_COOKIE, secure, Math.floor(PREVIEW_COOKIE_TTL_MS / 1000), value),
+      );
+      headers.append("Set-Cookie", markerCookieHeader(secure, true));
+      return new Response(null, { status: 204, headers });
+    }
+
     await (deps.disableDraft ?? (() => nextDraft(false)))();
-    const secure = new URL(req.url).protocol === "https:";
     const headers = new Headers();
     headers.append("Set-Cookie", cookieBase(PREVIEW_COOKIE, secure, 0, ""));
     headers.append("Set-Cookie", cookieBase(PREVIEW_SESSION_COOKIE, secure, 0, ""));

package/src/routes.ts

@@ -4,6 +4,7 @@
 // `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 { Fragment, Suspense, createElement, type ReactNode } from "react";
+import { HeldPreview, HoldPreview } from "./preview-hold";
 import {
   DEFAULT_TEMPLATE_SLUG,
   isRoutable,
@@ -425,15 +426,19 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     const preview = await resolvePreviewState(cms, options.preview, searchParams);
     if (!previewReplacesPublished(preview)) return null;
     return createElement(
-      Fragment,
+      HoldPreview,
       null,
-      createElement("style", {
-        dangerouslySetInnerHTML: {
-          __html: "[data-backmatter-published]{display:none!important}",
-        },
-      }),
-      docBridge(hit),
-      await loadPreviewDoc(hit, preview),
+      createElement(
+        Fragment,
+        null,
+        createElement("style", {
+          dangerouslySetInnerHTML: {
+            __html: "[data-backmatter-published]{display:none!important}",
+          },
+        }),
+        docBridge(hit),
+        await loadPreviewDoc(hit, preview),
+      ),
     );
   };
 
@@ -454,7 +459,7 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
       Fragment,
       null,
       createElement(PublishedRoute, props),
-      createElement(Suspense, { fallback: null }, createElement(PreviewBranch, props)),
+      createElement(Suspense, { fallback: createElement(HeldPreview) }, createElement(PreviewBranch, props)),
     );
 
   const generateMetadata: CatchAllRoute["generateMetadata"] = async ({ params }) => {

package/src/site-editor.tsx

@@ -9,6 +9,7 @@ import "@backmatter/studio/studio.css";
 import studioPkg from "@backmatter/studio/package.json";
 import { SiteWidget } from "@backmatter/studio/widget";
 import { markerCookie } from "./gate";
+import { clearHeldPreview } from "./preview-hold";
 import { subscribeSiteDoc } from "./site-doc-bridge";
 import { readSiteDoc, sameSiteDoc, type SiteDocRef } from "./site-doc";
 
@@ -19,10 +20,23 @@ const SESSION_RENEW_MS = 30 * 60 * 1000;
 function useSiteDoc(): SiteDocRef | null {
   const pathname = usePathname();
   const [doc, setDoc] = useState<SiteDocRef | null>(null);
+  const pathRef = useRef(pathname);
+
+  useEffect(() => {
+    if (pathRef.current === pathname) return;
+    pathRef.current = pathname;
+    clearHeldPreview();
+    setDoc(null);
+  }, [pathname]);
 
   useEffect(() => {
     const apply = (next: SiteDocRef | null) => {
-      setDoc((prev) => (sameSiteDoc(prev, next) ? prev : next));
+      setDoc((prev) => {
+        // A refresh unmounts the doc marker for a moment. Keep the document
+        // the bar already has so the chat stays mounted across that gap.
+        if (!next) return prev;
+        return sameSiteDoc(prev, next) ? prev : next;
+      });
     };
     apply(readSiteDoc());
     const stop = subscribeSiteDoc(apply);
@@ -48,18 +62,24 @@ export const DEFAULT_STUDIO_PATH = "/backmatter";
 export function SiteChrome({
   branch,
   tree,
+  siteMode = "preview",
   exiting,
   onExit,
+  onEnterPreview,
   previewEntryPath = DEFAULT_PREVIEW_ENTRY_PATH,
+  previewFrame,
 }: {
   branch?: string;
   tree?: string;
+  siteMode?: "preview" | "live";
   exiting?: boolean;
   onExit: () => void;
+  onEnterPreview?: () => void;
   /** Kept so existing hosts can still pass it. The bar does not open the document editor. */
   studioPath?: string;
   /** Ticket route. `POST ?renew=1` slides the site session. A 401 drops the bar. */
   previewEntryPath?: string;
+  previewFrame?: boolean;
 }) {
   const router = useRouter();
   const doc = useSiteDoc();
@@ -111,10 +131,14 @@ export function SiteChrome({
       doc={doc}
       branch={branch}
       tree={tree}
+      siteMode={siteMode}
       exiting={exiting}
       onExit={onExit}
+      onEnterPreview={onEnterPreview}
       onDocChanged={() => startTransition(() => router.refresh())}
       onSessionExpired={leave}
+      previewEntryPath={previewEntryPath}
+      previewFrame={previewFrame}
       version={studioPkg.version}
     />
   );