@backmatter/next 0.0.6

package/src/devbar.tsx

@@ -0,0 +1,280 @@
+// packages/next/src/devbar.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 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);
+        });
+      }}
+    />
+  );
+}
+
+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/index.ts

@@ -0,0 +1,9 @@
+// packages/next/src/index.ts
+// Isomorphic re-export of `@backmatter/core`, plus the Next `createBackmatter` wrapper.
+// Do not import this entry from `"use client"` files (blocks, preview):
+// `createBackmatter` loads `@backmatter/core/node/create-backmatter`. Client code uses
+// `@backmatter/core` (defineBlock, field) or `@backmatter/next/preview` /
+// `@backmatter/next/page`.
+export * from "@backmatter/core";
+export type { CreateBackmatterOptions, BackmatterClient } from "@backmatter/core/node/create-backmatter";
+export { createBackmatter } from "./create-backmatter";

package/src/loader.ts

@@ -0,0 +1,59 @@
+// packages/next/src/loader.ts
+// Bundler loader for `.backmatter/index.ts`, `.backmatter/blocks.ts`, `.backmatter/mdx.ts`,
+// and `.backmatter/layouts.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/`,
+// `mdx/`, and `layouts/` 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";
+import { generate } from "@backmatter/core/generate";
+
+export type BackmatterLoaderOptions = {
+  root: string;
+  outDir: string;
+  modelsDir: string;
+  blocksDir: string;
+  mdxDir: string;
+  layoutsDir: string;
+  sdk: string;
+};
+
+/** The subset of webpack's LoaderContext this loader uses (Turbopack implements it too). */
+export type BackmatterLoaderContext = {
+  resourcePath: string;
+  getOptions(): BackmatterLoaderOptions;
+  addContextDependency(directory: string): void;
+  addDependency(file: string): void;
+  cacheable?(flag?: boolean): void;
+};
+
+export default function backmatterLoader(this: BackmatterLoaderContext, source: string): string {
+  const options = this.getOptions();
+  const root = path.resolve(options.root);
+  const modelsDir = path.resolve(root, options.modelsDir);
+  const blocksDir = path.resolve(root, options.blocksDir);
+  const mdxDir = path.resolve(root, options.mdxDir);
+  const layoutsDir = path.resolve(root, options.layoutsDir);
+
+  this.addContextDependency(modelsDir);
+  this.addContextDependency(blocksDir);
+  this.addContextDependency(mdxDir);
+  this.addContextDependency(layoutsDir);
+  this.cacheable?.(true);
+
+  const result = generate({
+    root,
+    outDir: options.outDir,
+    modelsDir: options.modelsDir,
+    blocksDir: options.blocksDir,
+    mdxDir: options.mdxDir,
+    layoutsDir: options.layoutsDir,
+    sdk: options.sdk,
+  });
+  if (result.configFile) this.addDependency(result.configFile);
+
+  const output = result.outputs.find((o) => path.resolve(o.file) === path.resolve(this.resourcePath));
+  return output ? output.content : source;
+}

package/src/mdx-client.tsx

@@ -0,0 +1,29 @@
+// packages/next/src/mdx-client.tsx
+"use client";
+
+import { useEffect, useState, type ReactNode } from "react";
+import { compileMdx, type MdxComponents } from "./mdx-compile";
+
+export type { MdxComponents };
+
+export function MdxBody({
+  source,
+  components,
+}: {
+  source: string;
+  components?: MdxComponents;
+}) {
+  const [node, setNode] = useState<ReactNode>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    void compileMdx(source, components).then((tree) => {
+      if (!cancelled) setNode(tree);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [source, components]);
+
+  return node;
+}

package/src/mdx-compile.ts

@@ -0,0 +1,37 @@
+// packages/next/src/mdx-compile.ts
+import { evaluate } from "@mdx-js/mdx";
+import {
+  createElement,
+  type ComponentType,
+  type ReactNode,
+} from "react";
+import * as runtime from "react/jsx-runtime";
+import remarkGfm from "remark-gfm";
+
+export type MdxComponents = Record<string, ComponentType<any>>;
+
+export async function compileMdx(
+  source: string,
+  components?: MdxComponents,
+): Promise<ReactNode> {
+  if (!source.trim()) return null;
+
+  try {
+    const { default: Content } = await evaluate(source, {
+      ...runtime,
+      remarkPlugins: [remarkGfm],
+      baseUrl: import.meta.url,
+    });
+    return createElement(Content, { components });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "MDX compile failed";
+    return createElement("pre", { role: "alert" }, message);
+  }
+}
+
+export async function renderDoc(
+  doc: { body: string },
+  options?: { components?: MdxComponents },
+): Promise<ReactNode> {
+  return compileMdx(doc.body, options?.components);
+}

package/src/mdx.ts

@@ -0,0 +1,13 @@
+// packages/next/src/mdx.ts
+export { compileMdx, renderDoc } from "./mdx-compile";
+export type { MdxComponents } from "./mdx-compile";
+export {
+  BlockSkeleton,
+  LazyBlock,
+  renderPage,
+} from "./page-render";
+export type {
+  BlockComponents,
+  BlockFallbacks,
+  BlockLoader,
+} from "./page-render";

package/src/middleware.ts

@@ -0,0 +1,4 @@
+// packages/next/src/middleware.ts
+// Compose helper for hosts that still wrap the preview gate themselves.
+// New hosts should use `@backmatter/next/proxy` from `proxy.ts`.
+export { backmatterProxy as backmatterMiddleware, proxy as middleware } from "./proxy";

package/src/page-render.ts

@@ -0,0 +1,111 @@
+// packages/next/src/page-render.ts
+import { Suspense, createElement, type ComponentType, type ReactNode } from "react";
+import { imageUrlFromUnknown, type BackmatterDoc } from "@backmatter/core";
+
+export type BlockModule = Record<string, unknown>;
+export type BlockLoader = (() => Promise<BlockModule>) & { $$backmatterLoader?: boolean };
+export type BlockComponents = Record<string, ComponentType<any> | BlockLoader>;
+export type BlockFallbacks = Record<string, ComponentType<any>>;
+
+type BlockInstance = {
+  id?: unknown;
+  type?: unknown;
+  props?: unknown;
+};
+
+function asBlocks(value: unknown): BlockInstance[] {
+  return Array.isArray(value) ? (value as BlockInstance[]) : [];
+}
+
+export function BlockSkeleton() {
+  return createElement("div", {
+    "aria-busy": true,
+    "aria-hidden": true,
+    style: { minHeight: 1 },
+  });
+}
+
+export function resolveBlockComponent(mod: BlockModule, type: string): ComponentType<any> | undefined {
+  const named = mod[type];
+  if (named) return named as ComponentType<any>;
+  const def = mod.default;
+  if (typeof def === "function") return def as ComponentType<any>;
+  if (def && typeof def === "object" && "component" in def && typeof (def as { component?: unknown }).component !== "undefined") {
+    return (def as { component?: ComponentType<any> }).component;
+  }
+  return undefined;
+}
+
+function isGeneratedBlockLoader(fn: ComponentType<any> | BlockLoader): boolean {
+  return (
+    fn.name === "" ||
+    (fn as ComponentType<any> & { $$backmatterLoader?: boolean }).$$backmatterLoader === true
+  );
+}
+
+export function asBlockLoader(type: string, value: ComponentType<any> | BlockLoader): BlockLoader {
+  if (isGeneratedBlockLoader(value)) return value as BlockLoader;
+  return () => Promise.resolve({ [type]: value as ComponentType<any> });
+}
+
+const resolvedBlocks = new WeakMap<BlockLoader, Promise<ComponentType<any> | undefined>>();
+
+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;
+  if (!Cmp) {
+    console.warn(`[backmatter] skipping unknown block type "${props.type}"`);
+    return null;
+  }
+  return createElement(Cmp, props.blockProps);
+}
+
+/** Render a page document's `blocks` array. Unknown types are skipped. */
+export function renderPage(
+  doc: Pick<BackmatterDoc, "frontmatter">,
+  components?: BlockComponents,
+  fallbacks?: BlockFallbacks,
+): 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;
+}

package/src/preview-live.tsx

@@ -0,0 +1,108 @@
+// packages/next/src/preview-live.tsx
+"use client";
+
+import { useEffect, useState, type ReactNode } from "react";
+import type { BackmatterDoc } from "@backmatter/core";
+import type { PreviewChangeEvent } from "@backmatter/core/preview";
+import { MdxBody, type MdxComponents } from "./mdx-client";
+
+export function PreviewUnavailable({ message }: { message?: string }) {
+  return (
+    <section>
+      <h1>Preview unavailable</h1>
+      {message ? <p>{message}</p> : <p>This preview session expired or could not load.</p>}
+    </section>
+  );
+}
+
+function streamUrl(ref: { locale: string; type: string; slug: string }) {
+  const params = new URLSearchParams({
+    stream: "1",
+    locale: ref.locale,
+    type: ref.type,
+    slug: ref.slug,
+  });
+  return `/api/backmatter/preview?${params}`;
+}
+
+export function listenForPreviewChanges(
+  ref: { locale: string; type: string; slug: string },
+  onChange: () => void,
+  options?: { debounceMs?: number },
+): () => void {
+  const debounceMs = options?.debounceMs ?? 250;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const source = new EventSource(streamUrl(ref));
+  const handle = () => {
+    clearTimeout(timer);
+    timer = setTimeout(onChange, debounceMs);
+  };
+  source.addEventListener("change", handle);
+  return () => {
+    clearTimeout(timer);
+    source.removeEventListener("change", handle);
+    source.close();
+  };
+}
+
+export function PreviewBody({
+  doc,
+  components,
+  children,
+}: {
+  doc: Pick<BackmatterDoc, "locale" | "type" | "slug" | "frontmatter" | "body">;
+  components?: MdxComponents;
+  /** RSC first paint. Replaced in place when SSE sends a new body. */
+  children?: ReactNode;
+}) {
+  const [body, setBody] = useState<string | null>(null);
+  const [, setFrontmatter] = useState(doc.frontmatter);
+
+  useEffect(() => {
+    const source = new EventSource(streamUrl(doc));
+    const onMessage = (ev: MessageEvent) => {
+      try {
+        const data = JSON.parse(String(ev.data)) as PreviewChangeEvent;
+        if (data.frontmatter !== undefined) setFrontmatter(data.frontmatter);
+        if (data.body !== undefined) setBody(data.body);
+      } catch {
+        // ignore malformed
+      }
+    };
+    source.addEventListener("change", onMessage as EventListener);
+    return () => {
+      source.removeEventListener("change", onMessage as EventListener);
+      source.close();
+    };
+  }, [doc.locale, doc.type, doc.slug]);
+
+  if (body === null) return children ?? <MdxBody source={doc.body} components={components} />;
+  return <MdxBody source={body} components={components} />;
+}
+
+export function PreviewPageReloader({
+  locale,
+  type,
+  slug,
+  refresh,
+}: {
+  locale: string;
+  type: string;
+  slug: string;
+  /** Hosts omit this; the Next wrapper passes `router.refresh` in a transition. */
+  refresh?: () => void;
+}) {
+  useEffect(
+    () =>
+      listenForPreviewChanges({ locale, type, slug }, () => {
+        if (refresh) refresh();
+        else window.location.reload();
+      }),
+    [locale, type, slug, refresh],
+  );
+  return null;
+}
+
+export function PreviewLiveSlot({ children }: { children?: ReactNode }) {
+  return children ?? null;
+}

package/src/preview-refresh.tsx

@@ -0,0 +1,17 @@
+// packages/next/src/preview-refresh.tsx
+"use client";
+
+import { createElement, useCallback, startTransition } from "react";
+import { useRouter } from "next/navigation";
+import { PreviewPageReloader as PreviewStreamReloader } from "./preview-live";
+
+/** Keeps the current page visible while preview content is refetched. */
+export function PreviewPageReloader(props: { locale: string; type: string; slug: string }) {
+  const router = useRouter();
+  const refresh = useCallback(() => {
+    startTransition(() => {
+      router.refresh();
+    });
+  }, [router]);
+  return createElement(PreviewStreamReloader, { ...props, refresh });
+}