@backmatter/next 0.0.21 → 0.0.23

package/src/devbar-client.tsx

@@ -1,7 +1,7 @@
 // packages/next/src/devbar-client.tsx
 "use client";
 
-import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
+import { Suspense, lazy, useEffect, useState, type CSSProperties, type ReactNode } from "react";
 import {
   clearHostPreviewSession,
   fetchCmsSession,
@@ -9,6 +9,18 @@ import {
   resolveDevMode,
   type CmsSessionUser,
 } from "@backmatter/core/preview";
+import {
+  ENTER_ATTEMPT_KEY,
+  enterPath,
+  gateOpen,
+  isGateShortcut,
+  markerCookie,
+  recentEnterAttempt,
+  stripOptInParam,
+} from "./gate";
+
+/** The bar and its panels load only after the gate opens. */
+const SiteChrome = lazy(() => import("./site-editor").then((m) => ({ default: m.SiteChrome })));
 
 export type { CmsSessionUser };
 
@@ -80,7 +92,7 @@ const barStyle: CSSProperties = {
   alignItems: "center",
   gap: 10,
   minHeight: 32,
-  maxWidth: "min(360px, calc(100vw - 24px))",
+  maxWidth: "min(520px, calc(100vw - 24px))",
   padding: "0 12px",
   paddingBottom: "env(safe-area-inset-bottom, 0px)",
   background: "#f4f4f5",
@@ -187,10 +199,12 @@ function Divider() {
 export function DevBarView({
   state,
   onExit,
+  onEdit,
   exiting,
 }: {
   state: DevModeState;
   onExit?: () => void;
+  onEdit?: () => void;
   exiting?: boolean;
 }) {
   if (state.status !== "ready") return null;
@@ -240,6 +254,20 @@ export function DevBarView({
           <Segment>draft</Segment>
         </>
       ) : null}
+      {!live && onEdit ? (
+        <>
+          <Divider />
+          <button
+            type="button"
+            className="backmatter-devbar-exit"
+            aria-label="Edit this page"
+            onClick={() => onEdit()}
+            style={exitButtonStyle}
+          >
+            Edit
+          </button>
+        </>
+      ) : null}
       {!live ? (
         <>
           <Divider />
@@ -259,22 +287,113 @@ export function DevBarView({
   );
 }
 
-export function DevBarClient({ apiUrl }: { apiUrl: string }) {
-  const state = useDevMode({ apiUrl });
+const DEFAULT_PREVIEW_ENTRY_PATH = "/api/backmatter/preview";
+
+type Gate = "closed" | "open";
+
+/**
+ * Opt-in check with no network: `?backmatter=1` (then stripped from the URL and
+ * remembered in the marker cookie), the marker itself, or the desktop
+ * shortcut. Public visitors stop here.
+ */
+function useGate(): Gate {
+  const [gate, setGate] = useState<Gate>("closed");
+
+  useEffect(() => {
+    // Framed by an editor (the Studio's split preview, the dashboard's split
+    // view): that editor is the chrome, so the page shows no bar of its own.
+    if (window.self !== window.top) return;
+    const secure = location.protocol === "https:";
+    if (gateOpen({ search: location.search, cookie: document.cookie })) {
+      document.cookie = markerCookie(true, secure);
+      const clean = stripOptInParam(location.href);
+      if (clean) history.replaceState(history.state, "", clean);
+      setGate("open");
+      return;
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (!isGateShortcut(e)) return;
+      e.preventDefault();
+      document.cookie = markerCookie(true, secure);
+      setGate("open");
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  return gate;
+}
+
+/**
+ * Past the gate: ask this origin for the session. None means a top-level
+ * bounce to the dashboard, which returns here with a ticket. A return without
+ * a session (login abandoned, site not in the workspace) clears the marker
+ * instead of bouncing again.
+ */
+function useSiteSession(gate: Gate, previewEntryPath: string): DevModeState {
+  const [state, setState] = useState<DevModeState>({ status: "hidden" });
+
+  useEffect(() => {
+    if (gate !== "open") return;
+    let cancelled = false;
+    void loadDevModeState("").then((next) => {
+      if (cancelled) return;
+      if (next.status === "ready" && next.mode === "preview") {
+        sessionStorage.removeItem(ENTER_ATTEMPT_KEY);
+        setState(next);
+        return;
+      }
+      if (recentEnterAttempt(sessionStorage.getItem(ENTER_ATTEMPT_KEY), Date.now())) {
+        sessionStorage.removeItem(ENTER_ATTEMPT_KEY);
+        document.cookie = markerCookie(false, location.protocol === "https:");
+        setState({ status: "hidden" });
+        return;
+      }
+      sessionStorage.setItem(ENTER_ATTEMPT_KEY, String(Date.now()));
+      location.assign(enterPath(previewEntryPath, location.pathname + location.search + location.hash));
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [gate, previewEntryPath]);
+
+  return state;
+}
+
+export function DevBarClient({
+  studioPath,
+  previewEntryPath = DEFAULT_PREVIEW_ENTRY_PATH,
+}: {
+  /** Unused since the bar stopped calling the CMS origin; kept for host layouts that still pass it. */
+  apiUrl?: string;
+  studioPath?: string;
+  previewEntryPath?: string;
+}) {
+  const gate = useGate();
+  const state = useSiteSession(gate, previewEntryPath);
   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);
-        });
-      }}
-    />
-  );
+  const exit = () => {
+    if (exiting) return;
+    setExiting(true);
+    void exitHostPreview().then((ok) => {
+      if (!ok) setExiting(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}
+        />
+      </Suspense>
+    );
+  }
+  return <DevBarView state={state} exiting={exiting} onExit={exit} />;
 }
 
 export async function exitHostPreview(

package/src/devbar.tsx

@@ -13,7 +13,24 @@ export {
   type DevModeState,
 } from "./devbar-client";
 
-/** Host layout: `<DevBar />`. Optional apiUrl for local/self-hosted CMS. */
-export function DevBar({ apiUrl }: { apiUrl?: string } = {}) {
-  return <DevBarClient apiUrl={resolveDevBarApiUrl(apiUrl)} />;
+/**
+ * Host layout: `<DevBar />`. Public visitors get a gate of a few hundred
+ * bytes that makes no request; `?backmatter=1`, the `bm_ui` marker cookie or
+ * ⌘⇧E opens it. `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`).
+ * `apiUrl` is accepted for older layouts and no longer used.
+ */
+export function DevBar({
+  apiUrl,
+  studioPath,
+  previewEntryPath,
+}: { apiUrl?: string; studioPath?: string; previewEntryPath?: string } = {}) {
+  return (
+    <DevBarClient
+      apiUrl={resolveDevBarApiUrl(apiUrl)}
+      studioPath={studioPath}
+      previewEntryPath={previewEntryPath}
+    />
+  );
 }

package/src/gate.ts

@@ -0,0 +1,85 @@
+// packages/next/src/gate.ts
+// The visitor gate in front of the editing bar. Pure helpers so the decision
+// is testable without a DOM: a page opens the bar only when the visitor opted
+// in through `?backmatter=1`, carries the marker cookie `bm_ui=1`, or presses
+// the desktop shortcut. Anyone else gets no fetch and no editor code.
+
+export const MARKER_COOKIE = "bm_ui";
+export const OPT_IN_PARAM = "backmatter";
+/** 30 days, per origin. Not HttpOnly: the gate reads it before any request. */
+export const MARKER_TTL_S = 30 * 24 * 60 * 60;
+/** Written when the gate bounces to the dashboard; read on return to stop a loop. */
+export const ENTER_ATTEMPT_KEY = "backmatter:enter";
+export const ENTER_ATTEMPT_WINDOW_MS = 60_000;
+
+export function hasMarker(cookieHeader: string | null | undefined): boolean {
+  if (!cookieHeader) return false;
+  for (const part of cookieHeader.split(";")) {
+    const [key, ...rest] = part.trim().split("=");
+    if (key === MARKER_COOKIE) return rest.join("=") === "1";
+  }
+  return false;
+}
+
+export function hasOptInParam(search: string): boolean {
+  return new URLSearchParams(search).get(OPT_IN_PARAM) === "1";
+}
+
+export function gateOpen(input: { search: string; cookie: string | null | undefined }): boolean {
+  return hasOptInParam(input.search) || hasMarker(input.cookie);
+}
+
+/** `document.cookie` assignment that sets or clears the marker. */
+export function markerCookie(on: boolean, secure = false): 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("; ");
+}
+
+/** The same href without `?backmatter=1`, or null when the param was absent. */
+export function stripOptInParam(href: string): string | null {
+  const url = new URL(href);
+  if (url.searchParams.get(OPT_IN_PARAM) !== "1") return null;
+  url.searchParams.delete(OPT_IN_PARAM);
+  return url.toString();
+}
+
+/** ⌘⇧E on macOS, Ctrl+Shift+E elsewhere. Not bound by the major browsers. */
+export function isGateShortcut(e: {
+  key: string;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+}): boolean {
+  if (!e.shiftKey || e.altKey) return false;
+  if (!(e.metaKey || e.ctrlKey)) return false;
+  return e.key === "E" || e.key === "e";
+}
+
+/** Same-origin path only: must start with one `/`. Anything else goes home. */
+export function safeReturnPath(raw: string | null | undefined): string {
+  const value = raw?.trim() ?? "";
+  if (!value.startsWith("/") || value.startsWith("//") || value.startsWith("/\\")) return "/";
+  return value;
+}
+
+/** The host route that bounces to the dashboard `enter` and comes back to `returnPath`. */
+export function enterPath(previewEntryPath: string, returnPath: string): string {
+  return `${previewEntryPath}?enter=1&return=${encodeURIComponent(safeReturnPath(returnPath))}`;
+}
+
+/**
+ * Loop guard: true when a bounce started within the window, meaning we came
+ * back from the dashboard without a session. The caller then gives up and
+ * clears the marker instead of bouncing again.
+ */
+export function recentEnterAttempt(stored: string | null, now: number): boolean {
+  const at = Number(stored);
+  return Number.isFinite(at) && at > 0 && now - at < ENTER_ATTEMPT_WINDOW_MS;
+}

package/src/layout-doc.ts

@@ -0,0 +1,38 @@
+// packages/next/src/layout-doc.ts
+// Shared body render for the catch-all and `renderPreview`. No preview chrome.
+// `data` is the external source record already resolved by the caller
+// (see source-data.ts); this module only threads it to blocks and the layout.
+import { createElement, type ReactNode } from "react";
+import { modelFormat, type BackmatterDoc, type ModelDef, type SourceDef } from "@backmatter/core";
+import { renderDoc, type MdxComponents } from "./mdx-compile";
+import { renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
+
+export type DocLayout = (doc: BackmatterDoc, body: ReactNode, data?: unknown) => ReactNode;
+
+export type LayoutDocOptions = {
+  models: readonly ModelDef[];
+  components?: MdxComponents;
+  blocks?: BlockComponents;
+  fallbacks?: BlockFallbacks;
+  layouts?: Record<string, DocLayout>;
+  /** `sources/{type}.ts` loaders, usually the generated `sources`. Resolved by the caller. */
+  sources?: Record<string, SourceDef>;
+  render?: (doc: BackmatterDoc, body: ReactNode) => ReactNode;
+};
+
+export async function renderLayoutDoc(
+  doc: BackmatterDoc,
+  options: LayoutDocOptions,
+  data?: unknown,
+): Promise<ReactNode> {
+  const model = options.models.find((item) => item.type === doc.type);
+  const isPage = Boolean(model && modelFormat(model) === "page");
+  const rendered = isPage
+    ? await renderPage(doc, options.blocks, options.fallbacks, data)
+    : await renderDoc(doc, { components: options.components });
+  const layout = options.layouts?.[doc.type];
+  const laidOut = layout ? layout(doc, rendered, data) : rendered;
+  if (options.render) return options.render(doc, laidOut);
+  if (layout || isPage) return laidOut;
+  return createElement("article", null, laidOut);
+}

package/src/loader.ts

@@ -1,10 +1,10 @@
 // packages/next/src/loader.ts
 // Bundler loader for `.backmatter/index.ts`, `.backmatter/blocks.ts`,
-// `.backmatter/mdx.ts`, `.backmatter/richtext.ts`, and `.backmatter/layouts.ts`.
+// `.backmatter/mdx.ts`, `.backmatter/richtext.ts`, `.backmatter/layouts.ts`, and `.backmatter/sources.ts`.
 //
 // This is the Tailwind-JIT mechanism: instead of running our own watcher we
 // tell the bundler that these modules depend on the `models/`, `blocks/`,
-// `richtext/`, `mdx/`, and `layouts/` directories. webpack and Turbopack already watch the filesystem;
+// `richtext/`, `mdx/`, `layouts/`, and `sources/` directories. webpack and Turbopack already watch the filesystem;
 // when a file is added, removed or renamed there they invalidate the module,
 // re-run this loader, and we regenerate the barrel from a fresh `readdir`.
 import path from "node:path";
@@ -19,6 +19,7 @@ export type BackmatterLoaderOptions = {
   mdxDir: string;
   layoutsDir: string;
   objectsDir: string;
+  sourcesDir: string;
   sdk: string;
 };
 
@@ -40,6 +41,7 @@ export default function backmatterLoader(this: BackmatterLoaderContext, source:
   const mdxDir = path.resolve(root, options.mdxDir);
   const layoutsDir = path.resolve(root, options.layoutsDir);
   const objectsDir = path.resolve(root, options.objectsDir);
+  const sourcesDir = path.resolve(root, options.sourcesDir);
 
   this.addContextDependency(modelsDir);
   this.addContextDependency(blocksDir);
@@ -47,6 +49,7 @@ export default function backmatterLoader(this: BackmatterLoaderContext, source:
   this.addContextDependency(mdxDir);
   this.addContextDependency(layoutsDir);
   this.addContextDependency(objectsDir);
+  this.addContextDependency(sourcesDir);
   this.cacheable?.(true);
 
   const result = generate({
@@ -58,6 +61,7 @@ export default function backmatterLoader(this: BackmatterLoaderContext, source:
     mdxDir: options.mdxDir,
     layoutsDir: options.layoutsDir,
     objectsDir: options.objectsDir,
+    sourcesDir: options.sourcesDir,
     sdk: options.sdk,
   });
   if (result.configFile) this.addDependency(result.configFile);

package/src/page-render.ts

@@ -1,6 +1,6 @@
 // packages/next/src/page-render.ts
 import { createElement, type ComponentType, type ReactNode } from "react";
-import { imageUrlFromUnknown, type BackmatterDoc } from "@backmatter/core";
+import { RESERVED_BLOCK_PROP, imageUrlFromUnknown, type BackmatterDoc } from "@backmatter/core";
 
 export type BlockModule = Record<string, unknown>;
 export type BlockLoader = (() => Promise<BlockModule>) & { $$backmatterLoader?: boolean };
@@ -75,11 +75,15 @@ export async function LazyBlock(props: {
   return createElement(Cmp, props.blockProps);
 }
 
-/** Render a page document's `blocks` array. Unknown types are skipped. */
+/**
+ * Render a page document's `blocks` array. Unknown types are skipped.
+ * `data` is the external source record; every block receives it as `props.data`.
+ */
 export async function renderPage(
   doc: Pick<BackmatterDoc, "frontmatter">,
   components?: BlockComponents,
   _fallbacks?: BlockFallbacks,
+  data?: unknown,
 ): Promise<ReactNode> {
   const blocks = asBlocks(doc.frontmatter.blocks);
   const children = await Promise.all(
@@ -104,7 +108,7 @@ export async function renderPage(
         return null;
       }
       const key = typeof block.id === "string" ? block.id : undefined;
-      return createElement(Cmp, { key, ...props });
+      return createElement(Cmp, { key, ...props, [RESERVED_BLOCK_PROP]: data });
     }),
   );
   const rendered = children.filter((child) => child != null);

package/src/preview-content.ts

@@ -0,0 +1,49 @@
+// packages/next/src/preview-content.ts
+//
+// While a preview render is on the stack, cms.getDoc and cms.listDocs read the
+// checkout (HEAD overlaid with that user's working tree). Published renders
+// never enter this store, so they stay on the cached client.
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { BackmatterDoc, BackmatterDocSummary } from "@backmatter/core";
+import { fetchPreviewDoc, fetchPreviewDocs } from "@backmatter/core/preview";
+
+export type PreviewContentConfig = {
+  apiUrl: string;
+  workspaceId: string;
+  previewToken: string;
+};
+
+export type PreviewContent = {
+  getDoc(locale: string, type: string, slug: string): Promise<BackmatterDoc | null>;
+  listDocs(filter?: { type?: string; locale?: string }): Promise<BackmatterDocSummary[]>;
+};
+
+const current = new AsyncLocalStorage<PreviewContent>();
+
+export function previewContentForCheckout(
+  config: PreviewContentConfig,
+  checkout: { branch?: string; tree?: string },
+): PreviewContent {
+  const options = {
+    apiUrl: config.apiUrl,
+    workspaceId: config.workspaceId,
+    previewToken: config.previewToken,
+  };
+  return {
+    getDoc(locale, type, slug) {
+      return fetchPreviewDoc(options, { locale, type, slug, ...checkout });
+    },
+    listDocs(filter) {
+      return fetchPreviewDocs(options, { ...checkout, ...filter });
+    },
+  };
+}
+
+export function currentPreviewContent(): PreviewContent | null {
+  return current.getStore() ?? null;
+}
+
+export function runWithPreviewContent<T>(content: PreviewContent | null, fn: () => T): T {
+  if (!content) return fn();
+  return current.run(content, fn);
+}

package/src/preview-live.tsx

@@ -105,6 +105,15 @@ export function PreviewPageReloader({
   return null;
 }
 
+export function PreviewRemoved() {
+  return (
+    <section>
+      <h1>Removed in your working tree</h1>
+      <p>This document is deleted until you commit or revert.</p>
+    </section>
+  );
+}
+
 export function PreviewLiveSlot({ children }: { children?: ReactNode }) {
   return children ?? null;
 }