@backmatter/core 0.0.18 → 0.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backmatter/core",
-  "version": "0.0.18",
+  "version": "0.0.20",
   "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,9 +59,12 @@ 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";
+export const CLOUD_DASHBOARD_URL = "https://dash.backmatter.app";
+export const LOCAL_DASHBOARD_URL = "http://localhost:5173";
 
 function withHttps(url: string): string {
   if (url.startsWith("http://") || url.startsWith("https://")) return url;
@@ -85,6 +90,29 @@ export function isDeployedHost(env: Record<string, string | undefined>): boolean
   );
 }
 
+/**
+ * Dashboard origin the dev bar frames.
+ * Explicit URL, else `BACKMATTER_DASHBOARD_URL`, else the cloud dashboard on a
+ * deployed host, else the local Vite app. A loopback URL in `.env` is ignored
+ * during a local `next build`, so the built site does not keep pointing at the laptop.
+ */
+export function resolveDashboardUrl(
+  explicit?: string,
+  env: Record<string, string | undefined> = envOf(),
+): string {
+  const fromProp = explicit?.trim();
+  const fromEnv = fromProp ? undefined : env.BACKMATTER_DASHBOARD_URL?.trim();
+  const candidate = fromProp || fromEnv || "";
+  const ignoreDevLoopback =
+    !fromProp &&
+    Boolean(candidate && isLoopbackApiUrl(candidate)) &&
+    env.NEXT_PHASE === "phase-production-build" &&
+    !onPlatformDeploy(env);
+  if (candidate && !ignoreDevLoopback) return stripTrailingSlash(candidate);
+  if (isDeployedHost(env)) return CLOUD_DASHBOARD_URL;
+  return LOCAL_DASHBOARD_URL;
+}
+
 /** DevBar /me origin: explicit, else env, else cloud API on a deployed host. */
 export function resolveDevBarApiUrl(
   explicit: string | undefined,
@@ -190,6 +218,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/enter.ts

@@ -0,0 +1,68 @@
+// packages/core/src/enter.ts
+// The dashboard is the identity provider. A site that needs a session sends
+// the browser top-level to `{dashboard}/enter`, which mints a ticket from the
+// first-party cookie and returns to `{site}/api/backmatter/preview?ticket=`.
+
+export const ENTER_PATH = "/enter";
+export const PREVIEW_ENTRY_PATH = "/api/backmatter/preview";
+
+export type EnterRequest = {
+  workspaceId: string;
+  /** Absolute URL on the site to land on after the session is set. */
+  returnUrl: string;
+};
+
+export function studioEnterUrl(dashboardUrl: string, req: EnterRequest): string {
+  const url = new URL(ENTER_PATH, dashboardUrl.replace(/\/+$/, "") + "/");
+  url.searchParams.set("workspace", req.workspaceId);
+  url.searchParams.set("return", req.returnUrl);
+  return url.toString();
+}
+
+export function parseEnterSearch(search: string): EnterRequest | null {
+  const params = new URLSearchParams(search);
+  const workspaceId = params.get("workspace")?.trim() ?? "";
+  const returnUrl = params.get("return")?.trim() ?? "";
+  if (!workspaceId || !returnUrl) return null;
+  return { workspaceId, returnUrl };
+}
+
+export type EnterTarget = {
+  /** Site origin the ticket is for. Must be one of the workspace's `siteUrls`. */
+  origin: string;
+  /** Same-origin path, with search, the ticket redirects to. */
+  redirect: string;
+};
+
+/**
+ * Resolve where a return URL points, allowing only origins the workspace has
+ * declared. Returns null for a foreign origin, a bad URL, or a non-http scheme.
+ */
+export function resolveEnterTarget(returnUrl: string, siteUrls: readonly string[]): EnterTarget | null {
+  let url: URL;
+  try {
+    url = new URL(returnUrl);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return null;
+  const allowed = new Set(
+    siteUrls
+      .map((raw) => {
+        try {
+          return new URL(raw).origin;
+        } catch {
+          return null;
+        }
+      })
+      .filter((o): o is string => Boolean(o)),
+  );
+  if (!allowed.has(url.origin)) return null;
+  const redirect = `${url.pathname}${url.search}` || "/";
+  return { origin: url.origin, redirect };
+}
+
+/** The URL the dashboard sends the browser to once it holds a ticket. */
+export function previewEntryUrl(origin: string, ticket: string): string {
+  return `${origin}${PREVIEW_ENTRY_PATH}?ticket=${encodeURIComponent(ticket)}`;
+}

package/src/fields.ts

@@ -28,6 +28,12 @@ export type FieldDef<
   object?: string;
   /** Nested fields for object/array (inline or copied from defineObject). */
   fields?: Record<string, FieldDef>;
+  /**
+   * Name of the Studio input that edits this field, e.g. `"color"`. The site's
+   * `defineStudio({ fields })` maps names to components; unknown names fall
+   * back to the default input for the kind.
+   */
+  input?: string;
 };
 
 export type FieldSnapshot = {
@@ -36,20 +42,22 @@ export type FieldSnapshot = {
   relationTo?: string;
   object?: string;
   fields?: Record<string, FieldSnapshot>;
+  input?: string;
 };
 
 type ObjectLike = { name: string; fields: Record<string, FieldDef> };
 
-type Opts<R extends boolean> = { required?: R };
+type Opts<R extends boolean> = { required?: R; input?: string };
 
 function base<K extends FieldKind, R extends boolean, To extends string>(
   kind: K,
-  opts?: { required?: R; relationTo?: To },
+  opts?: { required?: R; relationTo?: To; input?: string },
 ): FieldDef<K, R, To> {
   return {
     kind,
     ...(opts?.required ? { required: opts.required } : {}),
     ...(opts?.relationTo ? { relationTo: opts.relationTo } : {}),
+    ...(opts?.input ? { input: opts.input } : {}),
   } as FieldDef<K, R, To>;
 }
 
@@ -59,10 +67,11 @@ function composite<K extends "object" | "array", R extends boolean>(
   opts?: Opts<R>,
 ): FieldDef<K, R> {
   const required = opts?.required ? { required: opts.required as R } : {};
+  const input = opts?.input ? { input: opts.input } : {};
   if (typeof def === "string") {
-    return { kind, object: def, ...required };
+    return { kind, object: def, ...required, ...input };
   }
-  return { kind, object: def.name, fields: def.fields, ...required };
+  return { kind, object: def.name, fields: def.fields, ...required, ...input };
 }
 
 export const field = {
@@ -86,6 +95,7 @@ export function serializeField(def: FieldDef): FieldSnapshot {
     ...(def.required ? { required: true } : {}),
     ...(def.relationTo ? { relationTo: def.relationTo } : {}),
     ...(def.object ? { object: def.object } : {}),
+    ...(def.input ? { input: def.input } : {}),
   };
   if (def.fields) {
     const fields: Record<string, FieldSnapshot> = {};
@@ -125,6 +135,9 @@ export function parseFieldSnapshot(input: unknown): FieldSnapshot {
   if (typeof value.object === "string" && value.object.length > 0) {
     snap.object = value.object;
   }
+  if (typeof value.input === "string" && value.input.length > 0) {
+    snap.input = value.input;
+  }
   if (value.fields && typeof value.fields === "object" && !Array.isArray(value.fields)) {
     const fields: Record<string, FieldSnapshot> = {};
     for (const [name, nested] of Object.entries(value.fields as Record<string, unknown>)) {

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";
 
@@ -52,9 +58,12 @@ export {
   detectSiteUrl,
   isDeployedHost,
   resolveDevBarApiUrl,
+  resolveDashboardUrl,
   DEFAULT_DIRS,
   DEFAULT_LOCALE,
   CLOUD_API_URL,
+  CLOUD_DASHBOARD_URL,
+  LOCAL_DASHBOARD_URL,
 } from "./config";
 
 export type { RouteMatch, RouteModel, MatchRouteOptions } from "./routes";
@@ -118,21 +127,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 +165,17 @@ export {
   contentCacheTags,
   listCacheTags,
   pathsForCommittedDocs,
+  revalidateTagsForCommit,
   revalidateUrl,
 } from "./content-committed";
+
+export {
+  ENTER_PATH,
+  PREVIEW_ENTRY_PATH,
+  parseEnterSearch,
+  previewEntryUrl,
+  resolveEnterTarget,
+  studioEnterUrl,
+  type EnterRequest,
+  type EnterTarget,
+} from "./enter";

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,53 @@ 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);
+`;
+}
+
+const STUDIO_DIR = path.join("(backmatter)", "backmatter");
+
+function renderStudioLayout(): string {
+  return `// app/(backmatter)/backmatter/layout.tsx — own root layout so the site's
+// header, footer, fonts and global CSS do not wrap the Studio.
+export { StudioLayout as default } from "@backmatter/next/studio";
+`;
+}
+
+function renderStudioPage(studioImport: string): string {
+  return `// app/(backmatter)/backmatter/[[...path]]/page.tsx — the Backmatter Studio,
+// mounted on this site. Editors sign in at the dashboard; the Studio talks to
+// /api/backmatter/cms on this origin with the site session cookie.
+import { createStudioPage } from "@backmatter/next/studio";
+import { cms } from "${REGISTRY_SPECIFIER}";
+import studio from "${studioImport}";
+
+export default createStudioPage(cms, { studio });
+`;
+}
+
+function renderStudioDefinition(): string {
+  return `// backmatter.studio.tsx — how the Studio looks and which inputs it uses on
+// this site. A "use client" module: field inputs and block previews are
+// ordinary React components bundled by the site.
+"use client";
+
+import { defineStudio } from "@backmatter/studio/define";
+
+export default defineStudio({
+  // theme: { accent: "#1d4ed8" },
+  // fields: { color: ColorInput },            // field.text({ input: "color" })
+  // blocks: { Hero: { preview: HeroPreview } },
+  menu: [{ label: "Open site", href: "/" }],
+});
+`;
+}
+
 function renderRevalidateRoute(): string {
   return `// api/backmatter/revalidate/route.ts — content.committed from the BACKMATTER server.
 import { createRevalidateRoute } from "@backmatter/next/revalidate";
@@ -402,6 +451,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)) {
@@ -412,6 +471,37 @@ export async function runInit(args: CliArgs): Promise<string[]> {
       notes.push(`kept existing ${path.join(appDir, "api/backmatter/preview/route.ts")}`);
     }
 
+    const studioDefinition = path.join(root, "backmatter.studio.tsx");
+    if (!existsSync(studioDefinition)) {
+      await writeFile(studioDefinition, renderStudioDefinition());
+      notes.push("wrote backmatter.studio.tsx");
+    } else {
+      notes.push("kept existing backmatter.studio.tsx");
+    }
+
+    const studioDir = path.join(root, appDir, STUDIO_DIR);
+    const studioLayout = path.join(studioDir, "layout.tsx");
+    if (!existsSync(studioLayout)) {
+      await mkdir(studioDir, { recursive: true });
+      await writeFile(studioLayout, renderStudioLayout());
+      notes.push(`wrote ${path.join(appDir, STUDIO_DIR, "layout.tsx")}`);
+    } else {
+      notes.push(`kept existing ${path.join(appDir, STUDIO_DIR, "layout.tsx")}`);
+    }
+    const studioPageDir = path.join(studioDir, "[[...path]]");
+    const studioPage = path.join(studioPageDir, "page.tsx");
+    if (!existsSync(studioPage)) {
+      await mkdir(studioPageDir, { recursive: true });
+      const studioImport = path
+        .relative(studioPageDir, path.join(root, "backmatter.studio"))
+        .split(path.sep)
+        .join("/");
+      await writeFile(studioPage, renderStudioPage(studioImport));
+      notes.push(`wrote ${path.join(appDir, STUDIO_DIR, "[[...path]]", "page.tsx")}`);
+    } else {
+      notes.push(`kept existing ${path.join(appDir, STUDIO_DIR, "[[...path]]", "page.tsx")}`);
+    }
+
     const proxyFile = path.join(root, "proxy.ts");
     const srcProxy = path.join(root, "src", "proxy.ts");
     const middlewareFile = path.join(root, "middleware.ts");
@@ -450,7 +540,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",