@backmatter/next 0.0.21 → 0.0.23

package/src/routes.ts

@@ -4,19 +4,35 @@
 // `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 { isRoutable, matchRoute, modelFormat, PREVIEW_CHECKOUT_QUERY, PREVIEW_COOKIE, readPreviewCookie, routeSegments, type BackmatterDoc, type ModelDef } from "@backmatter/core";
+import {
+  DEFAULT_TEMPLATE_SLUG,
+  isRoutable,
+  isTemplateSlug,
+  matchRoute,
+  PREVIEW_CHECKOUT_QUERY,
+  PREVIEW_COOKIE,
+  readPreviewCookie,
+  routeSegments,
+  type BackmatterDoc,
+  type ModelDef,
+  type SourceDef,
+} 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 type { MdxComponents } from "./mdx-compile";
 import { cachedRouteParams, getCachedPublished, registerPublishedRender } from "./cached-doc";
-import { renderPage, type BlockComponents, type BlockFallbacks } from "./page-render";
+import type { BlockComponents, BlockFallbacks } from "./page-render";
+import { renderLayoutDoc, type DocLayout } from "./layout-doc";
+import { previewContentForCheckout, runWithPreviewContent } from "./preview-content";
 import { previewUnavailable } from "./preview-ui";
+import { SiteDocBridge } from "./site-doc-bridge";
+import { requireSource, resolveSourceData } from "./source-data";
 
 export const CATCH_ALL_PARAM = "backmatter";
 
 export type CatchAllParams = { [CATCH_ALL_PARAM]?: string[] };
 
-export type DocLayout = (doc: BackmatterDoc, body: ReactNode) => ReactNode;
+export type { DocLayout };
 
 export type CatchAllOptions = {
   /** MDX component map, usually the generated `components`. */
@@ -27,6 +43,12 @@ export type CatchAllOptions = {
   fallbacks?: BlockFallbacks;
   /** Per-type wrappers, usually the generated `layouts`. */
   layouts?: Record<string, DocLayout>;
+  /**
+   * External record loaders for `external` models, usually the generated
+   * `sources`. The record reaches blocks as `props.data` and layouts as the
+   * third argument. A missing record is a 404.
+   */
+  sources?: Record<string, SourceDef>;
   /** Overrides `cms.config.locales`. */
   locales?: readonly string[];
   /** Overrides `cms.config.defaultLocale`. */
@@ -37,6 +59,23 @@ export type CatchAllOptions = {
   render?: (doc: BackmatterDoc, body: ReactNode) => ReactNode;
   /** Hook for tests; defaults to Next's `notFound()`. */
   notFound?: () => never;
+  /**
+   * Generated server action (`.backmatter/preview-action`). When set, preview
+   * swaps the body from editor messages instead of refreshing the route.
+   */
+  renderPreview?: (
+    ref: {
+      locale: string;
+      type: string;
+      slug: string;
+      branch?: string;
+      tree?: string;
+    },
+    doc: { frontmatter: Record<string, unknown>; body: string },
+    checkoutToken?: string,
+  ) => Promise<{ ok: true; node: ReactNode } | { ok: false; error: string }>;
+  /** Origins allowed to push preview messages. Defaults to the embedding page's referrer. */
+  dashboardOrigins?: readonly string[];
   /**
    * Test/host injection. When omitted, the catch-all reads Next draftMode
    * and the signed preview cookie. Never call cookies() on the live path.
@@ -160,43 +199,127 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
   const generateStaticParams: CatchAllRoute["generateStaticParams"] = async () => {
     const docs = await cms.listDocs();
     const params: CatchAllParams[] = [];
+    const seen = new Set<string>();
+    // Keyed on the URL: a route without `{locale}` yields one page per slug.
+    const push = (model: ModelDef, locale: string, slug: string) => {
+      const segments = routeSegments(model, locale, slug);
+      const key = segments.join("/");
+      if (seen.has(key)) return;
+      seen.add(key);
+      params.push({ [CATCH_ALL_PARAM]: segments });
+    };
     for (const doc of docs) {
       const model = byType.get(doc.type);
       if (!model || !isRoutable(model)) continue;
-      params.push({ [CATCH_ALL_PARAM]: routeSegments(model, doc.locale, doc.slug) });
+      // The template document has no page of its own.
+      if (isTemplateSlug(model, doc.slug)) continue;
+      push(model, doc.locale, doc.slug);
+    }
+    // Catalog records that never got a CMS file still prerender through the template.
+    const locales = matchOptions.locales ?? [matchOptions.defaultLocale];
+    for (const model of models) {
+      if (!isRoutable(model)) continue;
+      const list = options.sources?.[model.type]?.list;
+      if (!list) continue;
+      for (const locale of locales) {
+        for (const slug of await list(locale)) push(model, locale, slug);
+      }
     }
     return params;
   };
 
   const failFor = options.notFound ?? nextNotFound;
 
-  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
-      ? await renderPage(doc, options.blocks, options.fallbacks)
-      : await renderDoc(doc, { components: options.components });
-    let body = rendered;
-    if (previewEnabled) {
-      // Refresh on the server. Passing the host component map into the client
-      // preview wrapper is not serializable and crashes the page.
-      const { PreviewPageReloader } = await import("./preview-refresh");
-      body = createElement(
-        "div",
-        null,
-        createElement(PreviewPageReloader, {
+  type GetDocFn = (locale: string, type: string, slug: string) => Promise<BackmatterDoc | null>;
+
+  /**
+   * Document plus external record for a route hit, or null for a 404.
+   * External types: no record → null; no per-slug doc → the template doc.
+   * The template slug itself only renders when `allowTemplate` (preview).
+   */
+  async function loadRouteDoc(
+    hit: RouteHit,
+    getDoc: GetDocFn,
+    allowTemplate: boolean,
+  ): Promise<{ doc: BackmatterDoc; data: unknown } | null> {
+    const model = byType.get(hit.type);
+    if (!model) return null;
+    const source = requireSource(options.sources, model);
+    const onTemplate = isTemplateSlug(model, hit.slug);
+    if (onTemplate && !allowTemplate) return null;
+    const resolved = await resolveSourceData(source, model, hit);
+    if (!resolved.ok) return null;
+    let doc = await getDoc(hit.locale, hit.type, hit.slug);
+    if (!doc && model.external && !onTemplate) {
+      const template = model.template ?? DEFAULT_TEMPLATE_SLUG;
+      doc = await getDoc(hit.locale, hit.type, template);
+      if (!doc) {
+        console.warn(
+          `[backmatter] ${hit.type}/${hit.slug} has a record but no document; add content/${hit.locale}/${hit.type}/${template} to render every ${hit.type}`,
+        );
+      }
+    }
+    if (!doc) return null;
+    return { doc, data: resolved.data };
+  }
+
+  async function layoutDoc(
+    doc: BackmatterDoc,
+    preview: { enabled: boolean; branch?: string; tree?: string },
+    data?: unknown,
+  ): Promise<ReactNode> {
+    const { apiUrl, workspaceId, previewToken } = cms.config;
+    const content =
+      preview.enabled && apiUrl && workspaceId && previewToken
+        ? previewContentForCheckout(
+            { apiUrl, workspaceId, previewToken },
+            { branch: preview.branch, tree: preview.tree },
+          )
+        : null;
+    const inner = await runWithPreviewContent(content, () =>
+      renderLayoutDoc(
+        doc,
+        {
+          models,
+          components: options.components,
+          blocks: options.blocks,
+          fallbacks: options.fallbacks,
+          layouts: options.layouts,
+          sources: options.sources,
+          render: options.render,
+        },
+        data,
+      ),
+    );
+    if (!preview.enabled) return inner;
+    if (options.renderPreview) {
+      const { PreviewClient } = await import("./preview-refresh");
+      return createElement(
+        PreviewClient,
+        {
           locale: doc.locale,
           type: doc.type,
           slug: doc.slug,
-        }),
-        rendered,
+          branch: preview.branch,
+          tree: preview.tree,
+          dashboardOrigins: options.dashboardOrigins ? [...options.dashboardOrigins] : [],
+          renderPreview: options.renderPreview,
+        },
+        inner,
       );
     }
-    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);
+    // Hosts that have not generated `preview-action` keep the refresh fallback.
+    const { PreviewPageReloader } = await import("./preview-refresh");
+    return createElement(
+      "div",
+      null,
+      createElement(PreviewPageReloader, {
+        locale: doc.locale,
+        type: doc.type,
+        slug: doc.slug,
+      }),
+      inner,
+    );
   }
 
   async function loadPreviewDoc(
@@ -216,34 +339,54 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
             },
             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);
+      const loaded = await loadRouteDoc(
+        hit,
+        (locale, type, slug) => getDoc({ locale, type, slug, ...preview.checkout }),
+        true,
+      );
+      if (!loaded) return previewUnavailable("Document not found");
+      return layoutDoc(loaded.doc, { enabled: true, ...preview.checkout }, loaded.data);
     } catch (err) {
       return previewUnavailable(err instanceof Error ? err.message : "Failed to load");
     }
   }
 
   async function renderPublished(locale: string, type: string, slug: string): Promise<ReactNode> {
-    const doc = await cms.getDoc(locale, type, slug);
-    if (!doc) return null;
+    const loaded = await loadRouteDoc({ locale, type, slug }, cms.getDoc, false);
+    if (!loaded) return null;
     return createElement(
       "div",
       { "data-backmatter-published": "", style: { display: "contents" } },
-      await layoutDoc(doc, false),
+      await layoutDoc(loaded.doc, { enabled: false }, loaded.data),
     );
   }
 
   async function publishedBody(locale: string, type: string, slug: string): Promise<ReactNode> {
     registerPublishedRender(renderPublished);
     const body = await getCachedPublished(locale, type, slug);
-    if (body == null) return failFor();
-    return body;
+    if (body != null) return body;
+    // A tree-only document has no published body. 404 only when preview is off,
+    // so the preview branch can still render it. The dynamic read is on the miss path.
+    if (options.preview) {
+      const state: PreviewState = options.preview.enabled
+        ? {
+            enabled: true,
+            checkout: options.preview.checkout ?? {},
+            ...(options.preview.error ? { error: options.preview.error } : {}),
+          }
+        : { enabled: false };
+      if (previewReplacesPublished(state)) return null;
+      return failFor();
+    }
+    try {
+      const mod = (await import("next/headers" as string)) as {
+        draftMode: () => Promise<{ isEnabled: boolean }>;
+      };
+      if ((await mod.draftMode()).isEnabled) return null;
+    } catch {
+      // No Next runtime (tests, static analysis): a miss is a 404.
+    }
+    return failFor();
   }
 
   const CmsRoute: CatchAllRoute["CmsRoute"] = async ({ params, searchParams }) => {
@@ -264,7 +407,9 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     const resolved = await params;
     const hit = resolve(resolved[CATCH_ALL_PARAM]);
     if (!hit) return failFor();
-    return publishedBody(hit.locale, hit.type, hit.slug);
+    const body = await publishedBody(hit.locale, hit.type, hit.slug);
+    if (body == null) return body;
+    return createElement(Fragment, null, docBridge(hit), body);
   };
 
   const PreviewBranch = async ({
@@ -287,10 +432,23 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
           __html: "[data-backmatter-published]{display:none!important}",
         },
       }),
+      docBridge(hit),
       await loadPreviewDoc(hit, preview),
     );
   };
 
+  function docBridge(hit: { locale: string; type: string; slug: string }) {
+    if (!cms.config.workspaceId) return null;
+    return createElement(SiteDocBridge, {
+      doc: {
+        locale: hit.locale,
+        type: hit.type,
+        slug: hit.slug,
+        workspaceId: cms.config.workspaceId,
+      },
+    });
+  }
+
   const Page: CatchAllRoute["Page"] = (props) =>
     createElement(
       Fragment,
@@ -303,10 +461,14 @@ export function createCatchAll<Models extends readonly ModelDef[]>(
     const resolved = await cachedRouteParams(params);
     const hit = resolve(resolved[CATCH_ALL_PARAM]);
     if (!hit) return {};
-    const doc = await cms.getDoc(hit.locale, hit.type, hit.slug);
-    if (!doc) return {};
-    const title = doc.frontmatter.title;
-    return { title: typeof title === "string" ? title : hit.slug };
+    const loaded = await loadRouteDoc(hit, cms.getDoc, false);
+    if (!loaded) return {};
+    const title = loaded.doc.frontmatter.title;
+    if (typeof title === "string" && title.trim()) return { title };
+    const source = options.sources?.[hit.type];
+    const fromSource =
+      source?.metadata && loaded.data != null ? source.metadata(loaded.data).title : undefined;
+    return { title: fromSource ?? hit.slug };
   };
 
   return { Page, CmsRoute, generateStaticParams, generateMetadata, resolve };

package/src/site-channel.ts

@@ -0,0 +1,37 @@
+// packages/next/src/site-channel.ts
+// One in-memory preview channel for the on-site editor and the page it edits.
+// The pair lives for the lifetime of the tab. Do not close it.
+import { createLocalPreviewTransport, type PreviewTransport } from "@backmatter/core/preview";
+
+const CHANNEL_KEY = "__backmatterSitePreview";
+
+type ChannelPair = { editor: PreviewTransport; page: PreviewTransport };
+
+function channel(): ChannelPair {
+  const host = globalThis as typeof globalThis & { [CHANNEL_KEY]?: ChannelPair };
+  if (!host[CHANNEL_KEY]) host[CHANNEL_KEY] = createLocalPreviewTransport();
+  return host[CHANNEL_KEY];
+}
+
+export function sitePageTransport(): PreviewTransport {
+  return channel().page;
+}
+
+export function siteEditorTransport(): PreviewTransport {
+  return channel().editor;
+}
+
+export function fanInPreviewTransports(parts: readonly PreviewTransport[]): PreviewTransport {
+  return {
+    send(message) {
+      for (const part of parts) part.send(message);
+    },
+    subscribe(listener) {
+      const stops = parts.map((part) => part.subscribe(listener));
+      return () => {
+        for (const stop of stops) stop();
+      };
+    },
+    close() {},
+  };
+}

package/src/site-doc-bridge.tsx

@@ -0,0 +1,50 @@
+// packages/next/src/site-doc-bridge.tsx
+"use client";
+
+import { useEffect } from "react";
+import { sameSiteDoc, type SiteDocRef } from "./site-doc";
+
+type Bus = {
+  current: SiteDocRef | null;
+  listeners: Set<(doc: SiteDocRef) => void>;
+};
+
+const BUS_KEY = "__backmatterSiteDoc";
+
+function bus(): Bus {
+  const host = globalThis as typeof globalThis & { [BUS_KEY]?: Bus };
+  if (!host[BUS_KEY]) host[BUS_KEY] = { current: null, listeners: new Set() };
+  return host[BUS_KEY];
+}
+
+export function publishSiteDoc(doc: SiteDocRef) {
+  const channel = bus();
+  if (sameSiteDoc(channel.current, doc)) return;
+  channel.current = doc;
+  for (const listener of channel.listeners) listener(doc);
+}
+
+export function subscribeSiteDoc(listener: (doc: SiteDocRef) => void): () => void {
+  const channel = bus();
+  channel.listeners.add(listener);
+  if (channel.current) listener(channel.current);
+  return () => channel.listeners.delete(listener);
+}
+
+/** Rendered by the CMS page so the bar hears the document for the current route. */
+export function SiteDocBridge({ doc }: { doc: SiteDocRef }) {
+  useEffect(() => {
+    publishSiteDoc(doc);
+  }, [doc.locale, doc.type, doc.slug, doc.workspaceId]);
+
+  return (
+    <span
+      hidden
+      data-backmatter-doc=""
+      data-locale={doc.locale}
+      data-type={doc.type}
+      data-slug={doc.slug}
+      data-workspace={doc.workspaceId}
+    />
+  );
+}

package/src/site-doc.ts

@@ -0,0 +1,123 @@
+// packages/next/src/site-doc.ts
+export type SiteDocRef = {
+  locale: string;
+  type: string;
+  slug: string;
+  workspaceId: string;
+};
+
+export function parseSiteDoc(content: string | null | undefined): SiteDocRef | null {
+  if (!content) return null;
+  try {
+    const value = JSON.parse(content) as Record<string, unknown>;
+    if (
+      typeof value.locale !== "string" ||
+      typeof value.type !== "string" ||
+      typeof value.slug !== "string" ||
+      typeof value.workspaceId !== "string" ||
+      !value.locale ||
+      !value.type ||
+      !value.slug ||
+      !value.workspaceId
+    ) {
+      return null;
+    }
+    return {
+      locale: value.locale,
+      type: value.type,
+      slug: value.slug,
+      workspaceId: value.workspaceId,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function readSiteDoc(): SiteDocRef | null {
+  if (typeof document === "undefined") return null;
+  const marked = document.querySelector("[data-backmatter-doc]");
+  if (marked) {
+    const doc = {
+      locale: marked.getAttribute("data-locale") ?? "",
+      type: marked.getAttribute("data-type") ?? "",
+      slug: marked.getAttribute("data-slug") ?? "",
+      workspaceId: marked.getAttribute("data-workspace") ?? "",
+    };
+    if (doc.locale && doc.type && doc.slug && doc.workspaceId) return doc;
+  }
+  return parseSiteDoc(document.querySelector('meta[name="backmatter:doc"]')?.getAttribute("content"));
+}
+
+export function sameSiteDoc(a: SiteDocRef | null, b: SiteDocRef | null): boolean {
+  if (a === b) return true;
+  if (!a || !b) return false;
+  return (
+    a.locale === b.locale &&
+    a.type === b.type &&
+    a.slug === b.slug &&
+    a.workspaceId === b.workspaceId
+  );
+}
+
+export type SiteBlock = {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+};
+
+export function siteBlocks(value: unknown): SiteBlock[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((row): row is SiteBlock => {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return false;
+    const block = row as Record<string, unknown>;
+    return (
+      typeof block.id === "string" &&
+      typeof block.type === "string" &&
+      !!block.props &&
+      typeof block.props === "object" &&
+      !Array.isArray(block.props)
+    );
+  });
+}
+
+export function moveSiteBlock(blocks: SiteBlock[], id: string, direction: -1 | 1): SiteBlock[] {
+  const at = blocks.findIndex((block) => block.id === id);
+  const next = at + direction;
+  if (at < 0 || next < 0 || next >= blocks.length) return blocks;
+  const copy = [...blocks];
+  const [row] = copy.splice(at, 1);
+  copy.splice(next, 0, row!);
+  return copy;
+}
+
+export function patchSiteBlock(
+  blocks: SiteBlock[],
+  id: string,
+  prop: string,
+  value: unknown,
+): SiteBlock[] {
+  return blocks.map((block) =>
+    block.id === id ? { ...block, props: { ...block.props, [prop]: value } } : block,
+  );
+}
+
+/** Append text from an AI SDK UI message stream chunk. Incomplete lines stay buffered. */
+export function takeChatDeltas(buffer: string, chunk: string): { text: string; rest: string } {
+  const combined = buffer + chunk;
+  const lines = combined.split("\n");
+  const rest = lines.pop() ?? "";
+  let text = "";
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("data:")) continue;
+    const payload = trimmed.slice(5).trim();
+    if (!payload || payload === "[DONE]") continue;
+    try {
+      const event = JSON.parse(payload) as { type?: string; delta?: string };
+      if (event.type === "text-delta" && typeof event.delta === "string") text += event.delta;
+    } catch {
+      // a non-JSON event is not assistant text
+    }
+  }
+  return { text, rest };
+}