@backmatter/core 0.0.18 → 0.0.20

package/src/node/generate.ts

@@ -12,6 +12,7 @@ import {
   listMdxFiles,
   listModelFiles,
   listObjectFiles,
+  listSourceDefFiles,
   type BlockFile,
   type ModelFile,
 } from "./discover";
@@ -35,6 +36,7 @@ export type GenerateOptions = {
   mdxDir?: string;
   layoutsDir?: string;
   objectsDir?: string;
+  sourcesDir?: string;
   /** Module that exports `createBackmatter`. Auto-detected from package.json when omitted. */
   sdk?: string;
   /** Write to disk. Default: true. `false` only renders (used by the bundler loader). */
@@ -64,6 +66,7 @@ export type GenerateResult = {
   mdx: BlockFile[];
   layouts: ModelFile[];
   objects: ModelFile[];
+  sources: ModelFile[];
   skippedBlocks: string[];
   skippedMdx: string[];
   /** Absolute path of `backmatter.config.*` when present. */
@@ -102,20 +105,32 @@ function renderCachedCmsClient(): string[] {
   return [
     "const raw = createBackmatter({ ...config, models, sync: false });",
     "",
-    "async function getDoc(locale: string, type: string, slug: string) {",
+    "async function cachedGetDoc(locale: string, type: string, slug: string) {",
     '  "use cache";',
     '  cacheLife("hours");',
     "  cacheTag(...contentCacheTags(locale, type, slug));",
     "  return raw.getDoc(locale, type, slug);",
     "}",
     "",
-    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    "async function cachedListDocs(filter?: { type?: string; locale?: string }) {",
     '  "use cache";',
     '  cacheLife("hours");',
     "  cacheTag(...listCacheTags(filter?.type));",
     "  return raw.listDocs(filter);",
     "}",
     "",
+    "async function getDoc(locale: string, type: string, slug: string) {",
+    "  const preview = currentPreviewContent();",
+    "  if (preview) return preview.getDoc(locale, type, slug);",
+    "  return cachedGetDoc(locale, type, slug);",
+    "}",
+    "",
+    "async function listDocs(filter?: { type?: string; locale?: string }) {",
+    "  const preview = currentPreviewContent();",
+    "  if (preview) return preview.listDocs(filter);",
+    "  return cachedListDocs(filter);",
+    "}",
+    "",
     "/** Typed content client: cms.query.{type}, cms.getDoc, cms.listDocs. */",
     "export const cms = {",
     "  ...raw,",
@@ -136,6 +151,7 @@ export function renderModelsBarrel(input: {
   const lines = [GENERATED_HEADER, `import { createBackmatter } from "${input.sdk}";`];
   if (nextHost) {
     lines.push('import { contentCacheTags, createQuery, listCacheTags } from "@backmatter/core";');
+    lines.push('import { currentPreviewContent } from "@backmatter/next/preview-content";');
     lines.push('import { cacheLife, cacheTag } from "next/cache";');
   }
   if (input.configFile) {
@@ -258,6 +274,49 @@ export function renderBlockFallbacksBarrel(input: {
   return `${lines.join("\n")}\n`;
 }
 
+/** Server action the catch-all uses to paint editor keystrokes. Next hosts only. */
+export function renderPreviewAction(sdk: string): string {
+  if (sdk !== "@backmatter/next") {
+    return `${GENERATED_HEADER}
+/** Instant preview needs @backmatter/next. This host has no server action. */
+export const renderPreview = null;
+`;
+  }
+  return `"use server";
+${GENERATED_HEADER}
+import { createRenderPreview } from "@backmatter/next/render-preview";
+import { cms } from "./index";
+import { blockLoaders } from "./blocks";
+import { layouts } from "./layouts";
+import { sources } from "./sources";
+import { components as mdxComponents } from "./mdx";
+import { richtextComponents } from "./richtext";
+
+const components = { ...richtextComponents, ...mdxComponents };
+
+export const renderPreview = createRenderPreview(cms, {
+  components,
+  blocks: blockLoaders,
+  layouts,
+  sources,
+});
+`;
+}
+
+export function renderSourcesBarrel(input: { outDir: string; sources: ModelFile[] }): string {
+  const lines = [GENERATED_HEADER];
+  for (const source of input.sources) {
+    lines.push(`import ${source.importName} from "${importSpecifier(input.outDir, source.file)}";`);
+  }
+  lines.push("");
+  lines.push("/** External record loaders: sources/{type}.ts resolves that model's route data. */");
+  const entries = input.sources.map((s) =>
+    s.importName === s.stem ? s.stem : `${JSON.stringify(s.stem)}: ${s.importName}`,
+  );
+  lines.push(`export const sources = ${entries.length ? `{ ${entries.join(", ")} }` : "{}"};`);
+  return `${lines.join("\n")}\n`;
+}
+
 export function renderLayoutsBarrel(input: { outDir: string; layouts: ModelFile[] }): string {
   const lines = [GENERATED_HEADER];
   for (const layout of input.layouts) {
@@ -284,7 +343,9 @@ export const REGISTRY_FILES = [
   "mdx.ts",
   "richtext.ts",
   "layouts.ts",
+  "sources.ts",
   "sync.ts",
+  "preview-action.ts",
 ] as const;
 
 export function generate(options: GenerateOptions): GenerateResult {
@@ -306,6 +367,7 @@ export function generate(options: GenerateOptions): GenerateResult {
   );
   const layouts = listLayoutFiles(root, options.layoutsDir ?? DEFAULT_DIRS.layouts);
   const objects = listObjectFiles(root, options.objectsDir ?? DEFAULT_DIRS.objects);
+  const sources = listSourceDefFiles(root, options.sourcesDir ?? DEFAULT_DIRS.sources);
   const sdk = options.sdk ?? detectSdk(root);
   const configFile = findConfigFile(root);
   const write = options.write ?? true;
@@ -317,7 +379,9 @@ export function generate(options: GenerateOptions): GenerateResult {
     "mdx.ts": renderMdxBarrel({ outDir, mdx }),
     "richtext.ts": renderRichtextBarrel({ outDir, richtext }),
     "layouts.ts": renderLayoutsBarrel({ outDir, layouts }),
+    "sources.ts": renderSourcesBarrel({ outDir, sources }),
     "sync.ts": renderSyncBarrel({ outDir, models, blocks, richtext, objects, configFile, sdk }),
+    "preview-action.ts": renderPreviewAction(sdk),
   };
   const outputs: GeneratedFile[] = REGISTRY_FILES.map((name) => {
     const file = path.join(outDir, name);
@@ -339,6 +403,7 @@ export function generate(options: GenerateOptions): GenerateResult {
     mdx,
     layouts,
     objects,
+    sources,
     skippedBlocks: [...skippedBlocks, ...skippedRichtext],
     skippedMdx,
     configFile,

package/src/preview-channel.ts

@@ -0,0 +1,255 @@
+// packages/core/src/preview-channel.ts
+//
+// In-browser protocol between an editor and a preview page. postMessage when
+// they are different windows; an in-memory pair when they share one (on-site
+// overlay). No framework imports.
+
+import { parsePreviewHotkey, type PreviewHotkeyMessage } from "./preview-hotkeys";
+
+export const PREVIEW_CHANNEL_VERSION = 1 as const;
+
+export type PreviewChannelRef = {
+  locale: string;
+  type: string;
+  slug: string;
+  branch?: string;
+  tree?: string;
+};
+
+type Envelope = {
+  v: typeof PREVIEW_CHANNEL_VERSION;
+  ref: PreviewChannelRef;
+};
+
+export type PreviewHelloMessage = Envelope & {
+  type: "backmatter:hello";
+  capabilities?: string[];
+};
+
+export type PreviewDocMessage = Envelope & {
+  type: "backmatter:doc";
+  frontmatter: Record<string, unknown>;
+  body: string;
+  seq: number;
+};
+
+export type PreviewNavigateMessage = Envelope & {
+  type: "backmatter:navigate";
+  path: string;
+};
+
+export type PreviewRemovedMessage = Envelope & {
+  type: "backmatter:removed";
+};
+
+export type PreviewStatusMessage = Envelope & {
+  type: "backmatter:status";
+  seq: number;
+  state: "rendered" | "error";
+  message?: string;
+};
+
+export type PreviewChannelMessage =
+  | PreviewHelloMessage
+  | PreviewDocMessage
+  | PreviewNavigateMessage
+  | PreviewRemovedMessage
+  | PreviewStatusMessage
+  | PreviewHotkeyMessage;
+
+export type PreviewTransport = {
+  send(message: PreviewChannelMessage): void;
+  subscribe(listener: (message: PreviewChannelMessage) => void): () => void;
+  close(): void;
+};
+
+export function samePreviewRef(a: PreviewChannelRef, b: PreviewChannelRef): boolean {
+  if (a.locale !== b.locale || a.type !== b.type || a.slug !== b.slug) return false;
+  if (a.branch && b.branch && a.branch !== b.branch) return false;
+  if (a.tree && b.tree && a.tree !== b.tree) return false;
+  return true;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object";
+}
+
+function readRef(value: unknown): PreviewChannelRef | null {
+  if (!isRecord(value)) return null;
+  if (typeof value.locale !== "string" || !value.locale) return null;
+  if (typeof value.type !== "string" || !value.type) return null;
+  if (typeof value.slug !== "string" || !value.slug) return null;
+  const ref: PreviewChannelRef = {
+    locale: value.locale,
+    type: value.type,
+    slug: value.slug,
+  };
+  if (typeof value.branch === "string" && value.branch) ref.branch = value.branch;
+  if (typeof value.tree === "string" && value.tree) ref.tree = value.tree;
+  return ref;
+}
+
+function readEnvelope(value: Record<string, unknown>): Envelope | null {
+  if (value.v !== PREVIEW_CHANNEL_VERSION) return null;
+  const ref = readRef(value.ref);
+  if (!ref) return null;
+  return { v: PREVIEW_CHANNEL_VERSION, ref };
+}
+
+/** Parse a channel payload. Legacy hotkey messages (no `v`) still parse. */
+export function parsePreviewMessage(data: unknown): PreviewChannelMessage | null {
+  const hotkey = parsePreviewHotkey(data);
+  if (hotkey) return hotkey;
+  if (!isRecord(data) || typeof data.type !== "string") return null;
+  const envelope = readEnvelope(data);
+  if (!envelope) return null;
+  switch (data.type) {
+    case "backmatter:hello": {
+      const capabilities = Array.isArray(data.capabilities)
+        ? data.capabilities.filter((item): item is string => typeof item === "string")
+        : undefined;
+      return { type: "backmatter:hello", ...envelope, ...(capabilities ? { capabilities } : {}) };
+    }
+    case "backmatter:doc": {
+      if (!isRecord(data.frontmatter) || Array.isArray(data.frontmatter)) return null;
+      if (typeof data.body !== "string") return null;
+      if (typeof data.seq !== "number" || !Number.isFinite(data.seq)) return null;
+      return {
+        type: "backmatter:doc",
+        ...envelope,
+        frontmatter: data.frontmatter,
+        body: data.body,
+        seq: data.seq,
+      };
+    }
+    case "backmatter:navigate": {
+      if (typeof data.path !== "string" || !data.path.startsWith("/")) return null;
+      return { type: "backmatter:navigate", ...envelope, path: data.path };
+    }
+    case "backmatter:removed":
+      return { type: "backmatter:removed", ...envelope };
+    case "backmatter:status": {
+      if (data.state !== "rendered" && data.state !== "error") return null;
+      if (typeof data.seq !== "number" || !Number.isFinite(data.seq)) return null;
+      return {
+        type: "backmatter:status",
+        ...envelope,
+        seq: data.seq,
+        state: data.state,
+        ...(typeof data.message === "string" ? { message: data.message } : {}),
+      };
+    }
+    default:
+      return null;
+  }
+}
+
+export function normalizePreviewOrigin(origin: string): string {
+  return origin.trim().replace(/\/$/, "");
+}
+
+/** True when `origin` is one of the allowed origins. Empty allow-list rejects all. */
+export function isAllowedPreviewOrigin(origin: string, allowed: readonly string[]): boolean {
+  const needle = normalizePreviewOrigin(origin);
+  if (!needle) return false;
+  return allowed.some((item) => normalizePreviewOrigin(item) === needle);
+}
+
+export type PreviewMessageEvent = { origin: string; data: unknown };
+
+export type PostMessageTransportOptions = {
+  post(message: PreviewChannelMessage, targetOrigin: string): void;
+  targetOrigin: string;
+  allowedOrigins: readonly string[];
+  listen(handler: (event: PreviewMessageEvent) => void): () => void;
+};
+
+/** Cross-window transport. Inbound messages from other origins are dropped. */
+export function createPostMessageTransport(options: PostMessageTransportOptions): PreviewTransport {
+  const listeners = new Set<(message: PreviewChannelMessage) => void>();
+  let closed = false;
+  const stop = options.listen((event) => {
+    if (closed) return;
+    if (!isAllowedPreviewOrigin(event.origin, options.allowedOrigins)) return;
+    const message = parsePreviewMessage(event.data);
+    if (!message) return;
+    for (const listener of listeners) listener(message);
+  });
+  return {
+    send(message) {
+      if (closed) return;
+      options.post(message, normalizePreviewOrigin(options.targetOrigin));
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      listeners.clear();
+      stop();
+    },
+  };
+}
+
+export type PreviewWindowLike = {
+  postMessage(message: unknown, targetOrigin: string): void;
+  addEventListener(type: "message", handler: (event: MessageEvent) => void): void;
+  removeEventListener(type: "message", handler: (event: MessageEvent) => void): void;
+};
+
+/** Browser binding for `createPostMessageTransport`. */
+export function createWindowPreviewTransport(options: {
+  target: { postMessage(message: unknown, targetOrigin: string): void };
+  targetOrigin: string;
+  allowedOrigins: readonly string[];
+  host?: PreviewWindowLike;
+}): PreviewTransport {
+  const host = options.host ?? (globalThis as unknown as PreviewWindowLike);
+  return createPostMessageTransport({
+    targetOrigin: options.targetOrigin,
+    allowedOrigins: options.allowedOrigins,
+    post: (message, targetOrigin) => options.target.postMessage(message, targetOrigin),
+    listen: (handler) => {
+      const onMessage = (event: MessageEvent) => {
+        handler({ origin: event.origin, data: event.data });
+      };
+      host.addEventListener("message", onMessage);
+      return () => host.removeEventListener("message", onMessage);
+    },
+  });
+}
+
+/** Paired in-memory transports for an editor and a page in the same window. */
+export function createLocalPreviewTransport(): { editor: PreviewTransport; page: PreviewTransport } {
+  const editorListeners = new Set<(message: PreviewChannelMessage) => void>();
+  const pageListeners = new Set<(message: PreviewChannelMessage) => void>();
+  let closed = false;
+
+  function side(
+    mine: Set<(message: PreviewChannelMessage) => void>,
+    other: Set<(message: PreviewChannelMessage) => void>,
+  ): PreviewTransport {
+    return {
+      send(message) {
+        if (closed) return;
+        for (const listener of other) listener(message);
+      },
+      subscribe(listener) {
+        mine.add(listener);
+        return () => mine.delete(listener);
+      },
+      close() {
+        closed = true;
+        editorListeners.clear();
+        pageListeners.clear();
+      },
+    };
+  }
+
+  return {
+    editor: side(editorListeners, pageListeners),
+    page: side(pageListeners, editorListeners),
+  };
+}

package/src/preview-client.ts

@@ -0,0 +1,291 @@
+// packages/core/src/preview-client.ts
+//
+// Framework-free preview session. The page applies editor `doc` messages
+// through a renderer. SSE is the source until an editor attaches, and after
+// that only a tombstone (`raw: ""`) from SSE still wins.
+
+import {
+  samePreviewRef,
+  type PreviewChannelMessage,
+  type PreviewChannelRef,
+  type PreviewTransport,
+} from "./preview-channel";
+
+export type PreviewRenderDoc = {
+  frontmatter: Record<string, unknown>;
+  body: string;
+};
+
+export type PreviewRenderResult = { ok: true; value?: unknown } | { ok: false; error: string };
+
+export type PreviewRenderer = (
+  ref: PreviewChannelRef,
+  doc: PreviewRenderDoc,
+) => Promise<PreviewRenderResult>;
+
+/** Per-document SSE payload. `raw: ""` is a working-tree tombstone. */
+export type PreviewSseEvent = {
+  raw?: string;
+  body?: string;
+  frontmatter?: Record<string, unknown>;
+};
+
+export type PreviewPageHandlers = {
+  onApplied?: (doc: PreviewRenderDoc & { seq: number }, value?: unknown) => void;
+  onError?: (message: string) => void;
+  onRemoved?: () => void;
+  onNavigate?: (path: string) => void;
+};
+
+type Job = {
+  doc: PreviewRenderDoc;
+  source: "channel" | "sse";
+  seq: number;
+};
+
+export type PreviewPageSession = {
+  close(): void;
+  /** True after the first `doc` for this page's ref. */
+  editorAttached(): boolean;
+};
+
+/**
+ * Page side. Sends `hello` immediately. At most one render runs; a newer
+ * payload replaces a queued one and a finished render is dropped when a
+ * newer payload arrived during the call.
+ */
+export function createPreviewPage(options: {
+  ref: PreviewChannelRef;
+  transport: PreviewTransport;
+  subscribeSse: (onEvent: (event: PreviewSseEvent) => void) => () => void;
+  renderer: PreviewRenderer;
+  handlers?: PreviewPageHandlers;
+  capabilities?: string[];
+}): PreviewPageSession {
+  const handlers = options.handlers ?? {};
+  let attached = false;
+  let settledSeq = 0;
+  let inflightSeq = 0;
+  let closed = false;
+  let rendering = false;
+  let queued: Job | null = null;
+  let epoch = 0;
+
+  function send(message: PreviewChannelMessage) {
+    if (closed) return;
+    options.transport.send(message);
+  }
+
+  function settle(job: Job, result: PreviewRenderResult) {
+    if (job.source === "channel") {
+      settledSeq = job.seq;
+      send({
+        type: "backmatter:status",
+        v: 1,
+        ref: options.ref,
+        seq: job.seq,
+        state: result.ok ? "rendered" : "error",
+        ...(!result.ok ? { message: result.error } : {}),
+      });
+    }
+    if (result.ok) handlers.onApplied?.({ ...job.doc, seq: job.seq }, result.value);
+    else handlers.onError?.(result.error);
+  }
+
+  async function drain() {
+    if (rendering || closed) return;
+    rendering = true;
+    try {
+      while (queued && !closed) {
+        const job = queued;
+        queued = null;
+        inflightSeq = job.source === "channel" ? job.seq : 0;
+        const epochAtStart = epoch;
+        let result: PreviewRenderResult;
+        try {
+          result = await options.renderer(options.ref, job.doc);
+        } catch (err) {
+          result = {
+            ok: false,
+            error: err instanceof Error ? err.message : "Preview render failed",
+          };
+        }
+        if (closed || epoch !== epochAtStart) continue;
+        if (queued) continue;
+        settle(job, result);
+      }
+    } finally {
+      rendering = false;
+    }
+  }
+
+  function enqueue(job: Job) {
+    if (closed) return;
+    if (job.source === "channel") {
+      attached = true;
+      if (job.seq <= Math.max(settledSeq, inflightSeq)) return;
+      if (queued?.source === "channel" && job.seq <= queued.seq) return;
+    }
+    queued = job;
+    void drain();
+  }
+
+  function showRemoved() {
+    epoch += 1;
+    queued = null;
+    handlers.onRemoved?.();
+  }
+
+  const unsubscribe = options.transport.subscribe((message) => {
+    if (closed) return;
+    if (message.type === "backmatter:hotkey") return;
+    if (message.type !== "backmatter:navigate" && !samePreviewRef(message.ref, options.ref)) return;
+    switch (message.type) {
+      case "backmatter:doc":
+        enqueue({
+          source: "channel",
+          seq: message.seq,
+          doc: { frontmatter: message.frontmatter, body: message.body },
+        });
+        break;
+      case "backmatter:removed":
+        showRemoved();
+        break;
+      case "backmatter:navigate":
+        handlers.onNavigate?.(message.path);
+        break;
+      default:
+        break;
+    }
+  });
+
+  const unsubscribeSse = options.subscribeSse((event) => {
+    if (closed) return;
+    if (event.raw === "") {
+      showRemoved();
+      return;
+    }
+    if (attached) return;
+    if (event.body === undefined && event.frontmatter === undefined) return;
+    enqueue({
+      source: "sse",
+      seq: 0,
+      doc: {
+        frontmatter: event.frontmatter ?? {},
+        body: event.body ?? "",
+      },
+    });
+  });
+
+  send({
+    type: "backmatter:hello",
+    v: 1,
+    ref: options.ref,
+    ...(options.capabilities ? { capabilities: options.capabilities } : {}),
+  });
+
+  return {
+    editorAttached: () => attached,
+    close() {
+      if (closed) return;
+      closed = true;
+      epoch += 1;
+      queued = null;
+      unsubscribe();
+      unsubscribeSse();
+    },
+  };
+}
+
+export type PreviewSchedule = (run: () => void) => { cancel(): void };
+
+function animationFrameSchedule(): PreviewSchedule {
+  return (run) => {
+    if (typeof requestAnimationFrame === "function") {
+      const id = requestAnimationFrame(run);
+      return { cancel: () => cancelAnimationFrame(id) };
+    }
+    const id = setTimeout(run, 0);
+    return { cancel: () => clearTimeout(id) };
+  };
+}
+
+export type PreviewEditorSession = {
+  /** Coalesce to at most one `doc` per scheduled frame. `seq` starts at 1. */
+  setDoc(doc: PreviewRenderDoc): void;
+  navigate(path: string): void;
+  removed(): void;
+  close(): void;
+};
+
+/**
+ * Editor side. `onHello` receives every hello, including one for a different
+ * document (the host decides whether to offer "Edit this page").
+ */
+export function createPreviewEditor(options: {
+  transport: PreviewTransport;
+  ref: PreviewChannelRef | (() => PreviewChannelRef);
+  onHello?: (ref: PreviewChannelRef) => void;
+  onStatus?: (status: { seq: number; state: "rendered" | "error"; message?: string }) => void;
+  schedule?: PreviewSchedule;
+}): PreviewEditorSession {
+  const schedule = options.schedule ?? animationFrameSchedule();
+  const currentRef = () => (typeof options.ref === "function" ? options.ref() : options.ref);
+  let seq = 0;
+  let pending: PreviewRenderDoc | null = null;
+  let scheduled: { cancel(): void } | null = null;
+  let closed = false;
+
+  function flush() {
+    scheduled = null;
+    if (closed || !pending) return;
+    const doc = pending;
+    pending = null;
+    seq += 1;
+    options.transport.send({
+      type: "backmatter:doc",
+      v: 1,
+      ref: currentRef(),
+      frontmatter: doc.frontmatter,
+      body: doc.body,
+      seq,
+    });
+  }
+
+  const unsubscribe = options.transport.subscribe((message) => {
+    if (closed) return;
+    if (message.type === "backmatter:hello") options.onHello?.(message.ref);
+    if (message.type === "backmatter:status" && samePreviewRef(message.ref, currentRef())) {
+      options.onStatus?.({
+        seq: message.seq,
+        state: message.state,
+        ...(message.message ? { message: message.message } : {}),
+      });
+    }
+  });
+
+  return {
+    setDoc(doc) {
+      if (closed) return;
+      pending = doc;
+      if (scheduled) return;
+      scheduled = schedule(flush);
+    },
+    navigate(path) {
+      if (closed) return;
+      options.transport.send({ type: "backmatter:navigate", v: 1, ref: currentRef(), path });
+    },
+    removed() {
+      if (closed) return;
+      options.transport.send({ type: "backmatter:removed", v: 1, ref: currentRef() });
+    },
+    close() {
+      if (closed) return;
+      closed = true;
+      scheduled?.cancel();
+      scheduled = null;
+      pending = null;
+      unsubscribe();
+    },
+  };
+}