@backmatter/core 0.0.18 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.18",
+  "version": "0.0.19",
   "description": "Experimental Backmatter SDK. APIs will break. Not ready for production.",
   "type": "module",
   "publishConfig": {

package/src/block.ts

@@ -39,9 +39,17 @@ export function defineBlock<const D extends BlockDef>(def: D): D {
   if (def.component === undefined) {
     throw new Error("block.component is required");
   }
+  if (RESERVED_BLOCK_PROP in def.fields) {
+    throw new Error(
+      `block.fields.${RESERVED_BLOCK_PROP} is reserved: it carries the external source record`,
+    );
+  }
   return def;
 }
 
+/** Prop name the renderer uses for an external model's record. */
+export const RESERVED_BLOCK_PROP = "data";
+
 type Simplify<T> = { -readonly [K in keyof T]: T[K] } & {};
 
 type ScalarOf<K extends FieldKind> = K extends "number"
@@ -58,8 +66,11 @@ type IsRequired<F> = F extends { required?: infer R }
     : false
   : false;
 
-/** TypeScript shape of a block's props, derived from `field.*` calls. */
-export type InferBlockProps<Fields extends Record<string, FieldDef>> = Simplify<
+/**
+ * TypeScript shape of a block's props, derived from `field.*` calls. Pass the
+ * record type as `Data` for blocks on an `external` model to type `props.data`.
+ */
+export type InferBlockProps<Fields extends Record<string, FieldDef>, Data = undefined> = Simplify<
   {
     [N in keyof Fields as IsRequired<Fields[N]> extends true ? N : never]: ScalarOf<
       Fields[N]["kind"]
@@ -68,7 +79,7 @@ export type InferBlockProps<Fields extends Record<string, FieldDef>> = Simplify<
     [N in keyof Fields as IsRequired<Fields[N]> extends true ? never : N]?: ScalarOf<
       Fields[N]["kind"]
     >;
-  }
+  } & ([Data] extends [undefined] ? {} : { data: Data })
 >;
 
 export function serializeBlock(block: BlockDef): BlockSnapshot {

package/src/config.ts

@@ -16,6 +16,8 @@ export type BackmatterDirs = {
   layouts?: string;
   /** Folder with one `defineObject` default export per file. Default: "objects". */
   objects?: string;
+  /** Folder with one `defineSource` default export per external model type. Default: "sources". */
+  sources?: string;
 };
 
 export type BackmatterConfig = {
@@ -57,6 +59,7 @@ export const DEFAULT_DIRS: Required<BackmatterDirs> = {
   mdx: "mdx",
   layouts: "layouts",
   objects: "objects",
+  sources: "sources",
 };
 export const DEFAULT_LOCALE = "en";
 export const CLOUD_API_URL = "https://api.backmatter.app";
@@ -190,6 +193,7 @@ export function resolveConfig(
       mdx: config.dirs?.mdx ?? DEFAULT_DIRS.mdx,
       layouts: config.dirs?.layouts ?? DEFAULT_DIRS.layouts,
       objects: config.dirs?.objects ?? DEFAULT_DIRS.objects,
+      sources: config.dirs?.sources ?? DEFAULT_DIRS.sources,
     },
   };
 }

package/src/content-committed.ts

@@ -40,6 +40,22 @@ export function listCacheTags(type?: string): string[] {
   return type ? [BACKMATTER_CACHE_TAG, `backmatter:${type}`] : [BACKMATTER_CACHE_TAG];
 }
 
+/**
+ * Cache tags a commit should expire. A normal commit expires the touched
+ * documents and their type lists. A full rebuild expires the global tag,
+ * which every cached entry carries.
+ */
+export function revalidateTagsForCommit(event: Pick<ContentCommittedEvent, "docs" | "full">): string[] {
+  if (event.full) return [BACKMATTER_CACHE_TAG];
+  const tags = new Set<string>();
+  for (const doc of event.docs ?? []) {
+    for (const tag of contentCacheTags(doc.locale, doc.type, doc.slug)) {
+      if (tag !== BACKMATTER_CACHE_TAG) tags.add(tag);
+    }
+  }
+  return [...tags];
+}
+
 /** Site paths the host should `revalidatePath` for these docs. */
 export function pathsForCommittedDocs(
   models: readonly RouteModel[],

package/src/index.ts

@@ -24,7 +24,9 @@ export {
   defaultModelPath,
   DEFAULT_MODEL_PATH,
   DEFAULT_PAGE_PATH,
+  DEFAULT_TEMPLATE_SLUG,
   IMPLICIT_SINGLETON_SLUG,
+  isTemplateSlug,
   serializeModel,
   serializeSchema,
   parseSchemaSnapshot,
@@ -40,8 +42,12 @@ export {
   defineBlock,
   serializeBlock,
   parseBlockSnapshot,
+  RESERVED_BLOCK_PROP,
 } from "./block";
 
+export type { SourceDef, SourceRef } from "./source";
+export { defineSource } from "./source";
+
 export type { DocFormat } from "./doc-format";
 export { modelFormat, parseDoc, serializeDoc } from "./doc-format";
 
@@ -118,21 +124,30 @@ export {
 export type { BackmatterDoc, BackmatterDocSummary } from "./doc";
 export { createQuery } from "./query";
 export type { Query, ModelQuery, TypedDoc, Where, Include, DocLoader } from "./query";
-export type { PreviewCheckout, PreviewTicket } from "./preview-session";
+export type { PreviewCheckout, PreviewSessionClaims, PreviewTicket } from "./preview-session";
 export {
   PREVIEW_COOKIE,
+  PREVIEW_SESSION_COOKIE,
+  PREVIEW_SESSION_QUERY,
+  PREVIEW_SESSION_STORAGE_KEY,
   PREVIEW_ENABLE_PATH,
   PREVIEW_QUERY,
   PREVIEW_CHECKOUT_QUERY,
   previewLocationWithCheckout,
   isSafeRedirectPath,
+  mintPreviewSession,
   mintPreviewTicket,
+  peekPreviewSessionWorkspace,
   previewMiddlewareDecision,
   readPreviewCookie,
+  readPreviewSession,
   readPreviewTicket,
+  scopePreviewAccess,
+  takePreviewSessionFromSearch,
   writePreviewCookie,
   PREVIEW_TICKET_TTL_MS,
   PREVIEW_COOKIE_TTL_MS,
+  PREVIEW_SESSION_TTL_MS,
 } from "./preview-session";
 export { signPayload, verifyPayload } from "./signed-token";
 export { getDocFromApi, listDocsFromApi } from "./api-loader";
@@ -147,5 +162,6 @@ export {
   contentCacheTags,
   listCacheTags,
   pathsForCommittedDocs,
+  revalidateTagsForCommit,
   revalidateUrl,
 } from "./content-committed";

package/src/model.ts

@@ -33,12 +33,51 @@ export type ModelDef = {
    * in a schema may set this.
    */
   indexSlug?: string;
+  /**
+   * Slugs belong to an outside system (a catalog). The host provides
+   * `sources/{type}.ts`; a record that does not exist there is a 404. A
+   * document at the `template` slug renders every record without its own file.
+   */
+  external?: boolean;
+  /** Reserved slug of the template document. Default `_template` when `external`. */
+  template?: string;
   fields: Record<string, FieldDef>;
 };
 
 /** What `defineModel` accepts: `path` falls back to the folder convention. */
 export type ModelInput = Omit<ModelDef, "path"> & { path?: string };
 
+export const DEFAULT_TEMPLATE_SLUG = "_template";
+
+/** True when `slug` is the template document of an external model. */
+export function isTemplateSlug(
+  model: Pick<ModelDef, "type" | "external" | "template"> | null | undefined,
+  slug: string,
+): boolean {
+  if (!model?.external) return false;
+  return slug === (model.template ?? DEFAULT_TEMPLATE_SLUG);
+}
+
+/** Validate `external` / `template` and return the template slug to store, if any. */
+export function resolveTemplateSlug(
+  def: { external?: boolean; template?: string; singleton?: boolean; indexSlug?: string },
+  label = "model",
+): string | undefined {
+  if (def.template !== undefined && !def.external) {
+    throw new Error(`${label}.template requires external: true`);
+  }
+  if (!def.external) return undefined;
+  if (def.singleton) throw new Error(`${label}.external cannot be combined with singleton`);
+  if (def.indexSlug !== undefined) {
+    throw new Error(`${label}.external cannot be combined with indexSlug`);
+  }
+  if (def.template === undefined) return DEFAULT_TEMPLATE_SLUG;
+  if (typeof def.template !== "string" || !def.template.trim()) {
+    throw new Error(`${label}.template must be a non-empty string`);
+  }
+  return def.template.trim();
+}
+
 /** Default repo path when a model does not declare one. */
 export const DEFAULT_MODEL_PATH = "content/{locale}/{type}/{slug}.mdx";
 export const DEFAULT_PAGE_PATH = "content/{locale}/{type}/{slug}.json";
@@ -55,6 +94,8 @@ export type ModelSnapshot = {
   singleton?: boolean;
   format?: DocFormat;
   indexSlug?: string;
+  external?: boolean;
+  template?: string;
   fields: Record<string, FieldSnapshot>;
 };
 
@@ -91,12 +132,17 @@ export type SchemaSnapshot = {
 };
 
 type WithPath<D extends ModelInput> = D extends { path: string } ? D : D & { path: string };
+type WithTemplate<D extends ModelInput> = D extends { external: true }
+  ? D extends { template: string }
+    ? D
+    : D & { template: string }
+  : D;
 
 /**
  * Validates the definition at runtime and preserves its literal types.
  * `path` defaults to `content/{locale}/{type}/{slug}.mdx`.
  */
-export function defineModel<const D extends ModelInput>(def: D): WithPath<D> {
+export function defineModel<const D extends ModelInput>(def: D): WithTemplate<WithPath<D>> {
   if (!def.type || typeof def.type !== "string") {
     throw new Error("model.type is required");
   }
@@ -123,7 +169,11 @@ export function defineModel<const D extends ModelInput>(def: D): WithPath<D> {
   if (!def.fields || typeof def.fields !== "object") {
     throw new Error("model.fields is required");
   }
-  const withPath = (def.path === undefined ? { ...def, path } : { ...def }) as WithPath<D>;
+  const template = resolveTemplateSlug(def);
+  const withPath = (def.path === undefined ? { ...def, path } : { ...def }) as WithTemplate<
+    WithPath<D>
+  >;
+  if (template !== undefined) (withPath as { template?: string }).template = template;
   if (singleton && def.route === undefined) {
     return { ...withPath, route: false };
   }
@@ -173,6 +223,10 @@ export function serializeModel(model: ModelDef): ModelSnapshot {
   if (model.singleton) snapshot.singleton = true;
   if (model.format === "page") snapshot.format = "page";
   if (model.indexSlug !== undefined) snapshot.indexSlug = model.indexSlug.trim();
+  if (model.external) {
+    snapshot.external = true;
+    snapshot.template = model.template ?? DEFAULT_TEMPLATE_SLUG;
+  }
   return snapshot;
 }
 
@@ -264,6 +318,22 @@ export function parseSchemaSnapshot(input: unknown): SchemaSnapshot {
       }
       snapshot.indexSlug = m.indexSlug.trim();
     }
+    if (m.external !== undefined && typeof m.external !== "boolean") {
+      throw new Error(`schema.models[${i}].external must be a boolean`);
+    }
+    const template = resolveTemplateSlug(
+      {
+        external: m.external === true,
+        template: m.template as string | undefined,
+        singleton,
+        indexSlug: snapshot.indexSlug,
+      },
+      `schema.models[${i}]`,
+    );
+    if (template !== undefined) {
+      snapshot.external = true;
+      snapshot.template = template;
+    }
     return snapshot;
   });
 

package/src/node/cli.ts

@@ -30,7 +30,7 @@ export type CliArgs = {
 
 const USAGE = `Usage:
   backmatter init                          scaffold backmatter.config.ts, the catch-all route and .backmatter/
-  backmatter generate  [--root <dir>]      write .backmatter/index.ts (typed cms), blocks.ts, mdx.ts and layouts.ts
+  backmatter generate  [--root <dir>]      write .backmatter/index.ts (typed cms), blocks.ts, mdx.ts, layouts.ts and sources.ts
   backmatter validate  [--root <dir>] [--models <file>] [--json]
   backmatter schema    [--root <dir>] [--models <file>] [--out <dir>]
 
@@ -239,6 +239,7 @@ export async function runGenerate(args: CliArgs): Promise<GenerateResult> {
     mdxDir: config.dirs.mdx,
     layoutsDir: config.dirs.layouts,
     objectsDir: config.dirs.objects,
+    sourcesDir: config.dirs.sources,
   });
 }
 
@@ -272,9 +273,10 @@ import { richtextComponents } from "${REGISTRY_SPECIFIER}/richtext";
 import { blockLoaders } from "${REGISTRY_SPECIFIER}/blocks";
 import { blockFallbacks } from "${REGISTRY_SPECIFIER}/block-fallbacks";
 import { layouts } from "${REGISTRY_SPECIFIER}/layouts";
+import { sources } from "${REGISTRY_SPECIFIER}/sources";
 
 const components = { ...richtextComponents, ...mdxComponents };
-const route = createCatchAll(cms, { components, blocks: blockLoaders, fallbacks: blockFallbacks, layouts });
+const route = createCatchAll(cms, { components, blocks: blockLoaders, fallbacks: blockFallbacks, layouts, sources });
 
 export const generateStaticParams = route.generateStaticParams;
 
@@ -348,6 +350,15 @@ export const config = {
 `;
 }
 
+function renderCmsProxyRoute(): string {
+  return `// api/backmatter/cms/[...path]/route.ts — same-origin proxy for the preview session.
+import { createCmsProxy } from "@backmatter/next/cms-proxy";
+import { cms } from "${REGISTRY_SPECIFIER}";
+
+export const { GET, POST, PUT, DELETE } = createCmsProxy(cms);
+`;
+}
+
 function renderRevalidateRoute(): string {
   return `// api/backmatter/revalidate/route.ts — content.committed from the BACKMATTER server.
 import { createRevalidateRoute } from "@backmatter/next/revalidate";
@@ -402,6 +413,16 @@ export async function runInit(args: CliArgs): Promise<string[]> {
       notes.push(`kept existing ${path.join(appDir, "api/backmatter/revalidate/route.ts")}`);
     }
 
+    const cmsDir = path.join(root, appDir, "api", "backmatter", "cms", "[...path]");
+    const cmsFile = path.join(cmsDir, "route.ts");
+    if (!existsSync(cmsFile)) {
+      await mkdir(cmsDir, { recursive: true });
+      await writeFile(cmsFile, renderCmsProxyRoute());
+      notes.push(`wrote ${path.join(appDir, "api/backmatter/cms/[...path]/route.ts")}`);
+    } else {
+      notes.push(`kept existing ${path.join(appDir, "api/backmatter/cms/[...path]/route.ts")}`);
+    }
+
     const previewDir = path.join(root, appDir, "api", "backmatter", "preview");
     const previewFile = path.join(previewDir, "route.ts");
     if (!existsSync(previewFile)) {
@@ -450,7 +471,7 @@ export async function runInit(args: CliArgs): Promise<string[]> {
     notes.push("no @backmatter/next dependency: skipped the catch-all route");
   }
 
-  for (const dir of ["models", "content", "blocks", "richtext", "mdx", "layouts"]) {
+  for (const dir of ["models", "content", "blocks", "richtext", "mdx", "layouts", "sources"]) {
     await mkdir(path.join(root, dir), { recursive: true });
   }
 

package/src/node/discover.ts

@@ -101,6 +101,11 @@ export function listLayoutFiles(root: string, layoutsDir = "layouts"): ModelFile
 export function listObjectFiles(root: string, objectsDir = "objects"): ModelFile[] {
   return listModelFiles(root, objectsDir);
 }
+
+/** `sources/{type}.ts`: one `defineSource` default export per external model type. */
+export function listSourceDefFiles(root: string, sourcesDir = "sources"): ModelFile[] {
+  return listModelFiles(root, sourcesDir);
+}
 export function listBlockFiles(
   root: string,
   blocksDir = "blocks",

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();
+    },
+  };
+}

package/src/preview-session.ts

@@ -2,11 +2,15 @@
 import { signPayload, verifyPayload } from "./signed-token";
 
 export const PREVIEW_COOKIE = "backmatter_preview";
+export const PREVIEW_SESSION_COOKIE = "backmatter_preview_session";
+export const PREVIEW_SESSION_QUERY = "backmatter_session";
+export const PREVIEW_SESSION_STORAGE_KEY = "backmatter_preview_session";
 export const PREVIEW_QUERY = "backmatter_preview";
 export const PREVIEW_CHECKOUT_QUERY = "backmatter_checkout";
 export const PREVIEW_ENABLE_PATH = "/api/backmatter/preview";
 export const PREVIEW_TICKET_TTL_MS = 10 * 60 * 1000;
 export const PREVIEW_COOKIE_TTL_MS = 12 * 60 * 60 * 1000;
+export const PREVIEW_SESSION_TTL_MS = 12 * 60 * 60 * 1000;
 
 export type PreviewCheckout = {
   branch?: string;
@@ -19,6 +23,21 @@ export type PreviewTicket = {
   redirect: string;
   branch?: string;
   tree?: string;
+  /** Preview session token. The host stores it and drops it from the URL. */
+  session?: string;
+  exp: number;
+};
+
+/** One user, one workspace, one branch, one working tree. */
+export type PreviewSessionClaims = {
+  v: 1;
+  kind: "preview-session";
+  userId: string;
+  workspaceId: string;
+  branch: string;
+  tree: string;
+  role: string;
+  epoch: number;
   exp: number;
 };
 
@@ -42,6 +61,7 @@ export async function mintPreviewTicket(
     redirect: string;
     branch?: string;
     tree?: string;
+    session?: string;
     exp: number;
   },
 ): Promise<string> {
@@ -55,10 +75,25 @@ export async function mintPreviewTicket(
     exp: input.exp,
     ...(input.branch ? { branch: input.branch } : {}),
     ...(input.tree ? { tree: input.tree } : {}),
+    ...(input.session ? { session: input.session } : {}),
   };
   return signPayload(secret, payload);
 }
 
+export async function mintPreviewSession(
+  secret: string,
+  input: Omit<PreviewSessionClaims, "v" | "kind">,
+): Promise<string> {
+  if (input.tree !== input.userId) {
+    throw new Error("preview session tree must be the user");
+  }
+  if (!input.branch || !input.workspaceId || !input.userId) {
+    throw new Error("preview session is missing scope");
+  }
+  const payload: PreviewSessionClaims = { v: 1, kind: "preview-session", ...input };
+  return signPayload(secret, payload);
+}
+
 function asTicket(value: unknown): PreviewTicket | null {
   if (!value || typeof value !== "object") return null;
   const v = value as Record<string, unknown>;
@@ -74,13 +109,85 @@ function asTicket(value: unknown): PreviewTicket | null {
     exp: v.exp,
     ...(typeof v.branch === "string" && v.branch ? { branch: v.branch } : {}),
     ...(typeof v.tree === "string" && v.tree ? { tree: v.tree } : {}),
+    ...(typeof v.session === "string" && v.session ? { session: v.session } : {}),
+  };
+}
+
+function asSession(value: unknown): PreviewSessionClaims | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+  if (v.v !== 1 || v.kind !== "preview-session") return null;
+  if (typeof v.userId !== "string" || typeof v.workspaceId !== "string") return null;
+  if (typeof v.branch !== "string" || typeof v.tree !== "string" || typeof v.role !== "string") {
+    return null;
+  }
+  if (v.tree !== v.userId) return null;
+  if (typeof v.epoch !== "number" || typeof v.exp !== "number" || v.exp <= Date.now()) return null;
+  return {
+    v: 1,
+    kind: "preview-session",
+    userId: v.userId,
+    workspaceId: v.workspaceId,
+    branch: v.branch,
+    tree: v.tree,
+    role: v.role,
+    epoch: v.epoch,
+    exp: v.exp,
   };
 }
 
+/** Workspace id from an unverified body, so the server can load the signing secret. */
+export function peekPreviewSessionWorkspace(token: string): string | null {
+  const dot = token.lastIndexOf(".");
+  if (dot <= 0) return null;
+  try {
+    const padded = token.slice(0, dot).replace(/-/g, "+").replace(/_/g, "/");
+    const pad = padded.length % 4 === 0 ? "" : "=".repeat(4 - (padded.length % 4));
+    const json = JSON.parse(atob(padded + pad)) as Record<string, unknown>;
+    return json.kind === "preview-session" && typeof json.workspaceId === "string"
+      ? json.workspaceId
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export async function readPreviewTicket(secret: string, token: string): Promise<PreviewTicket | null> {
   return asTicket(await verifyPayload(secret, token));
 }
 
+export async function readPreviewSession(
+  secret: string,
+  token: string | undefined,
+): Promise<PreviewSessionClaims | null> {
+  if (!token) return null;
+  return asSession(await verifyPayload(secret, token));
+}
+
+/**
+ * A session token may read and write only its own tree. A workspace preview
+ * token keeps the caller's query.
+ */
+export function scopePreviewAccess(
+  auth: { mode: "workspace" } | { mode: "session"; branch: string; tree: string },
+  query: { branch: string; tree: string | null },
+): { branch: string; tree: string | null } | null {
+  if (auth.mode === "workspace") return query;
+  if (query.tree && query.tree !== auth.tree) return null;
+  if (query.branch && query.branch !== auth.branch) return null;
+  return { branch: auth.branch, tree: auth.tree };
+}
+
+/** Pull a session token out of the URL. The returned search no longer contains it. */
+export function takePreviewSessionFromSearch(search: string): { token: string | null; search: string } {
+  const params = new URLSearchParams(search.startsWith("?") ? search.slice(1) : search);
+  const token = params.get(PREVIEW_SESSION_QUERY)?.trim() || null;
+  if (!token) return { token: null, search };
+  params.delete(PREVIEW_SESSION_QUERY);
+  const next = params.toString();
+  return { token, search: next ? `?${next}` : "" };
+}
+
 export function previewLocationWithCheckout(
   origin: string,
   redirect: string,

package/src/preview.ts

@@ -1,5 +1,5 @@
 // packages/core/src/preview.ts
-import type { BackmatterDoc } from "./doc";
+import type { BackmatterDoc, BackmatterDocSummary } from "./doc";
 
 export type PreviewDocRef = {
   locale: string;
@@ -164,6 +164,14 @@ export function previewStreamUrl(
   return `${docPath(options, ref)}/stream?${previewParams(options, ref)}`;
 }
 
+/** Tree-wide stream: added, modified, removed, and HEAD moves for one checkout. */
+export function previewTreeStreamUrl(
+  options: PreviewClientOptions,
+  checkout: { branch?: string; tree?: string },
+): string {
+  return `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/tree/stream?${previewParams(options, { locale: "", type: "", slug: "", ...checkout })}`;
+}
+
 export async function fetchPreviewDoc(
   options: PreviewClientOptions,
   ref: PreviewDocRef,
@@ -176,6 +184,38 @@ export async function fetchPreviewDoc(
   return data.doc;
 }
 
+/**
+ * HEAD overlaid with the checkout's working tree. Follows cursors so a list
+ * page sees every document of the type, not just the first page.
+ */
+export async function fetchPreviewDocs(
+  options: PreviewClientOptions,
+  query: { branch?: string; tree?: string; type?: string; locale?: string },
+): Promise<BackmatterDocSummary[]> {
+  const docs: BackmatterDocSummary[] = [];
+  let cursor: string | undefined;
+  for (let page = 0; page < 100; page++) {
+    const params = previewParams(options, {
+      locale: query.locale ?? "",
+      type: "",
+      slug: "",
+      branch: query.branch,
+      tree: query.tree,
+    });
+    if (query.type) params.set("type", query.type);
+    if (query.locale) params.set("locale", query.locale);
+    if (cursor) params.set("cursor", cursor);
+    const url = `${baseUrl(options.apiUrl)}/preview/workspaces/${options.workspaceId}/docs?${params}`;
+    const res = await fetch(url, { cache: "no-store" });
+    if (!res.ok) throw new Error(`preview listDocs failed: ${res.status}`);
+    const data = (await res.json()) as { docs: BackmatterDocSummary[]; nextCursor: string | null };
+    docs.push(...data.docs);
+    if (!data.nextCursor) break;
+    cursor = data.nextCursor;
+  }
+  return docs;
+}
+
 /** Browser EventSource subscribe to one working tree's saves; returns unsubscribe. */
 export function subscribePreview(
   options: PreviewClientOptions,
@@ -203,3 +243,38 @@ export function subscribePreview(
     source.close();
   };
 }
+
+export {
+  createLocalPreviewTransport,
+  createPostMessageTransport,
+  createWindowPreviewTransport,
+  isAllowedPreviewOrigin,
+  normalizePreviewOrigin,
+  parsePreviewMessage,
+  PREVIEW_CHANNEL_VERSION,
+  samePreviewRef,
+} from "./preview-channel";
+export type {
+  PostMessageTransportOptions,
+  PreviewChannelMessage,
+  PreviewChannelRef,
+  PreviewDocMessage,
+  PreviewHelloMessage,
+  PreviewMessageEvent,
+  PreviewNavigateMessage,
+  PreviewRemovedMessage,
+  PreviewStatusMessage,
+  PreviewTransport,
+  PreviewWindowLike,
+} from "./preview-channel";
+export { createPreviewEditor, createPreviewPage } from "./preview-client";
+export type {
+  PreviewEditorSession,
+  PreviewPageHandlers,
+  PreviewPageSession,
+  PreviewRenderDoc,
+  PreviewRenderResult,
+  PreviewRenderer,
+  PreviewSchedule,
+  PreviewSseEvent,
+} from "./preview-client";

package/src/source.ts

@@ -0,0 +1,24 @@
+// packages/core/src/source.ts
+// A source resolves the outside record behind an `external` model's route.
+// Host code only (`sources/{type}.ts`); never serialized into the schema.
+
+export type SourceRef = { locale: string; slug: string };
+
+export type SourceDef<T = unknown> = {
+  /** The outside record for a route hit. `null` means the record does not exist (404). */
+  load: (ref: SourceRef) => Promise<T | null>;
+  /** Slugs to prerender, per locale. Omit to prerender only slugs that have a CMS file. */
+  list?: (locale: string) => Promise<readonly string[]>;
+  /** One representative record for template preview. Omit to preview the template with `data: null`. */
+  sample?: (locale: string) => Promise<T | null>;
+  /** Metadata when the document has no `title`. */
+  metadata?: (record: T) => { title?: string };
+};
+
+/** Identity helper that validates the definition and keeps the record type. */
+export function defineSource<T>(def: SourceDef<T>): SourceDef<T> {
+  if (!def || typeof def !== "object" || typeof def.load !== "function") {
+    throw new Error("source.load is required and must be a function");
+  }
+  return def;
+}