@jxsuite/parser 2.0.0 → 3.0.0

package/src/content-loader.ts

@@ -19,15 +19,27 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, extname, relative, resolve } from "node:path";
-import { assetUrlFor } from "@jxsuite/schema/asset-paths";
+import {
+  assetUrlFor,
+  CONTENT_SECTION_KEY,
+  LOCALE_PLACEHOLDER,
+  SAFE_CONTENT_TYPE_NAME,
+} from "@jxsuite/schema/asset-paths";
 import { localeUrlPrefix, resolveI18n } from "@jxsuite/schema/locale";
 import type { AssetMount } from "@jxsuite/schema/asset-paths";
-import type { ExtensionRegistry } from "@jxsuite/schema/extension-registry";
-import type { FormatEntry, FormatHostIO, FormatRegistry } from "@jxsuite/schema/format-registry";
 import type {
+  FormatDiscoverOptions,
+  FormatEntry,
+  FormatRegistry,
+  ProjectDataContext,
+} from "@jxsuite/schema/format-registry";
+import { isBoolean, isNonNullObject, isNumber, isString } from "@jxsuite/schema/guards";
+import type {
+  ContentFieldValue,
   ContentTypeSchema,
+  JsonObject,
+  JsonValue,
   JxElement,
-  JxMutableNode,
   ProjectConfig,
 } from "@jxsuite/schema/types";
 import { normalizeAlerts } from "./alerts.ts";
@@ -49,29 +61,26 @@ import { coerceEntryDates, isCoercedDate, isDateFormat } from "./dates.ts";
 import type { ContentNodes } from "./inert.ts";
 import type { ContentLoaderEntry, ContentTypeDef } from "./types.ts";
 import { walkFiles } from "./walk.ts";
+import { entriesOf } from "./content-data.ts";
+import type { ContentSectionData } from "./content-data.ts";
 
 export type { ContentEntry, ContentLoaderEntry, TocEntry } from "./types.ts";
+export type { ContentSectionData } from "./content-data.ts";
 
 // ─── Context and section shapes ──────────────────────────────────────────────
 
 /** The value of the project.json `content` section: content type name → definition. */
 export type ContentSection = Record<string, ContentTypeDef>;
 
-/** Host context passed to `Content.projectData` (specs/extensions.md §8). */
-export interface ProjectDataContext {
-  projectConfig?: ProjectConfig;
-  /** Absolute project root directory. */
-  root: string;
-  /** The project's extension registry; format dispatch goes through its `formats` view. */
-  registry: ExtensionRegistry;
-  /** Injected host I/O (unused here — this loader is node-only by its declared timing). */
-  io?: FormatHostIO;
-}
+/* The host context passed to `Content.projectData` is the capability contract's own
+   (specs/extensions.md §8); its injected `io` goes unused here, as this loader is node-only by its
+   declared timing. */
+export type { ProjectDataContext } from "@jxsuite/schema/format-registry";
 
 /** Host context passed to `Content.resolvePaths` (specs/extensions.md §8). */
 export interface ResolvePathsContext {
   /** The loaded section data, as returned by `Content.projectData`. */
-  data: Map<string, ContentLoaderEntry[]>;
+  data: ContentSectionData;
   projectConfig?: ProjectConfig;
   /** Absolute project root directory. */
   root: string;
@@ -94,6 +103,18 @@ export interface ResolvePathsContext {
   patterns?: readonly string[];
 }
 
+/** An entry's `_meta`: where it came from, and the route and URL the loader gave it. */
+type ContentEntryMeta = NonNullable<ContentLoaderEntry["_meta"]>;
+
+/**
+ * One `$paths` result: route parameter → value, plus the entry's own `_meta` under that reserved
+ * name, which the host strips before substitution.
+ */
+export interface ContentPathParams {
+  _meta?: ContentEntryMeta;
+  [param: string]: ContentFieldValue | ContentEntryMeta | undefined;
+}
+
 /** The `$paths` value shape routed to this extension by its `contentType` discriminator. */
 export interface ContentPathsSource {
   contentType: string;
@@ -111,23 +132,24 @@ export interface ContentPathsSource {
  * @returns {ContentLoaderEntry[]} Array of ContentEntry shapes
  */
 function loadJSONEntries(filePath: string): ContentLoaderEntry[] {
-  const raw = JSON.parse(readFileSync(filePath, "utf8")) as unknown;
+  // SAFETY: JSON.parse only ever yields JSON values; its `any` return type says nothing more.
+  const raw = JSON.parse(readFileSync(filePath, "utf8")) as JsonValue;
   if (Array.isArray(raw)) {
-    return (raw as Record<string, unknown>[]).map((item: Record<string, unknown>, i: number) => ({
-      body: null,
-      data: item,
-      id: (item.id as string) ?? `${basename(filePath, ".json")}-${i}`,
-    }));
+    return raw.map((item, i) => jsonEntry(item, `${basename(filePath, ".json")}-${i}`));
   }
   // Single object file — filename is the id
-  const rawObj = raw as Record<string, unknown>;
-  return [
-    {
-      body: null,
-      data: rawObj,
-      id: (rawObj.id as string) ?? basename(filePath, ".json"),
-    },
-  ];
+  return [jsonEntry(raw, basename(filePath, ".json"))];
+}
+
+/** One entry of a JSON source: the object is its data, and its own `id` wins over `fallbackId`. */
+function jsonEntry(item: JsonValue, fallbackId: string): ContentLoaderEntry {
+  /* SAFETY: a JSON content file is documented (content-collections docs, "JSON files") as one
+     entry object or an array of entry objects, each optionally naming its `id`; the loader takes
+     the file at its word for that shape, as it always has, rather than checking each item. */
+  const data = item as JsonObject;
+  // SAFETY: by the same documented shape, an entry's own `id` is its text id; absent, the path names it.
+  const id = (data.id ?? fallbackId) as string;
+  return { body: null, data, id };
 }
 
 /** Discover .json entry files for a source (single file or directory), in sorted order. */
@@ -140,15 +162,9 @@ function discoverJSONFiles(resolvedSource: string, exclude: ExcludeMatcher): str
 
 // ─── Asset mounts and content-relative references ────────────────────────────
 
-/**
- * The placeholder a content type's `source` may carry to say "one directory per locale".
- *
- * `./blog/{locale}/` is one content type spread over N directories, not N content types. That
- * distinction is what keeps a translated post the same post: it keeps one schema, one set of
- * relationship targets, and one name in `$paths`, and differs only in which directory it was read
- * from — which is exactly the model `site-architecture.md` §13 uses for routes.
- */
-export const LOCALE_PLACEHOLDER = "{locale}";
+/* `LOCALE_PLACEHOLDER` lives in `@jxsuite/schema/asset-paths`, beside the mount math, so Studio's
+   browser-side canvas reads the same token; this module's public name for it stays available. */
+export { LOCALE_PLACEHOLDER } from "@jxsuite/schema/asset-paths";
 
 /**
  * The locales a `{locale}` source expands over, or `[]` when the project declares none.
@@ -204,12 +220,6 @@ export function localeSource(root: string, source: string, locale: string): stri
   return source.split(LOCALE_PLACEHOLDER).join(locale);
 }
 
-/** The project.json section key this class owns; also the URL namespace for its asset mounts. */
-const SECTION_KEY = "content";
-
-/** Content type names safe to place in a URL path segment unescaped. */
-const SAFE_TYPE_NAME = /^[\w.~-]+$/;
-
 /** Node keys whose value is a media reference the rewrite may remap. */
 const ASSET_KEYS = ["src", "poster"] as const;
 
@@ -273,7 +283,7 @@ function mountFilterFor(def: ContentTypeDef | undefined): ((path: string) => boo
  * @returns {AssetMount[]} One mount per eligible content type, in declaration order
  */
 export function contentAssetMounts(
-  section: ContentSection,
+  section: ContentSection | undefined,
   root: string,
   projectConfig?: ProjectConfig,
 ): AssetMount[] {
@@ -284,7 +294,11 @@ export function contentAssetMounts(
     return filter === undefined ? {} : { filter };
   };
   for (const [name, contentTypeDef] of Object.entries(section ?? {})) {
-    const source = contentTypeDef?.source;
+    // A definition is project.json data, and one still being written may not be an object yet.
+    if (!isNonNullObject(contentTypeDef)) {
+      continue;
+    }
+    const { source } = contentTypeDef;
     if (!source || source.startsWith("http://") || source.startsWith("https://")) {
       continue;
     }
@@ -295,26 +309,26 @@ export function contentAssetMounts(
      */
     if (source.includes(LOCALE_PLACEHOLDER)) {
       for (const locale of locales) {
-        if (!SAFE_TYPE_NAME.test(locale)) {
+        if (!SAFE_CONTENT_TYPE_NAME.test(locale)) {
           continue;
         }
         const dir = resolve(root, localeSource(root, source, locale))
           .split("\\")
           .join("/");
-        if (SAFE_TYPE_NAME.test(name) && existsSync(dir) && statSync(dir).isDirectory()) {
+        if (SAFE_CONTENT_TYPE_NAME.test(name) && existsSync(dir) && statSync(dir).isDirectory()) {
           mounts.push({
             dir,
-            urlPrefix: `/${SECTION_KEY}/${name}/${locale}`,
+            urlPrefix: `/${CONTENT_SECTION_KEY}/${name}/${locale}`,
             ...filterOf(contentTypeDef),
           });
         }
       }
       continue;
     }
-    if (!SAFE_TYPE_NAME.test(name)) {
+    if (!SAFE_CONTENT_TYPE_NAME.test(name)) {
       console.warn(
         `Content type "${name}": name is not URL-safe — its source directory is not published ` +
-          `at /${SECTION_KEY}/${name}, so content-relative asset references stay unresolved.`,
+          `at /${CONTENT_SECTION_KEY}/${name}, so content-relative asset references stay unresolved.`,
       );
       continue;
     }
@@ -324,7 +338,7 @@ export function contentAssetMounts(
     }
     mounts.push({
       dir: resolvedSource,
-      urlPrefix: `/${SECTION_KEY}/${name}`,
+      urlPrefix: `/${CONTENT_SECTION_KEY}/${name}`,
       ...filterOf(contentTypeDef),
     });
   }
@@ -386,26 +400,26 @@ function rewriteNodeAssets(
     }
     return;
   }
-  if (!node || typeof node !== "object") {
+  if (!isNonNullObject(node)) {
     return;
   }
-  const record = node as unknown as Record<string, unknown>;
-  const attributes = record.attributes as Record<string, unknown> | undefined;
+  const { attributes } = node;
   for (const key of ASSET_KEYS) {
-    for (const holder of [record, attributes]) {
+    // The node's own property first, then its attribute of the same name.
+    for (const holder of [node, attributes]) {
       const value = holder?.[key];
-      if (typeof value === "string") {
+      if (holder && isString(value)) {
         const rewritten = rewriteRef(value, entryDir, mount, onProblem);
         if (rewritten) {
-          holder![key] = rewritten;
+          holder[key] = rewritten;
         }
       }
     }
   }
-  const { children } = record;
+  const { children } = node;
   if (Array.isArray(children)) {
     for (const child of children) {
-      rewriteNodeAssets(child as JxElement | string | ContentNodes, entryDir, mount, onProblem);
+      rewriteNodeAssets(child, entryDir, mount, onProblem);
     }
   }
 }
@@ -433,37 +447,62 @@ export function rewriteEntryAssets(
   schema?: ContentTypeSchema,
 ) {
   const entryDir = dirname(filePath);
-  const uriFields = Object.entries(schema?.properties ?? {})
-    .filter(([, def]) => def?.format === "uri-reference" || def?.items?.format === "uri-reference")
-    .map(([field]) => field);
+  /* A field's schema is project.json data, so one that is not an object (a `null` left by an edit)
+     declares nothing rather than failing the load. */
+  const uriFields = Object.entries(schema?.properties ?? {}).flatMap(([field, def]) =>
+    isNonNullObject(def) &&
+    (def.format === "uri-reference" || def.items?.format === "uri-reference")
+      ? [field]
+      : [],
+  );
 
   for (const entry of entries) {
-    const onProblem = (value: string, problem: RefProblem) =>
-      console.warn(
-        problem === "missing"
-          ? `Content type "${typeName}": entry "${entry.id}" references missing asset "${value}"`
-          : `Content type "${typeName}": entry "${entry.id}" references "${value}", which the ` +
-              `collection does not publish (it is excluded, hidden or a document), so the ` +
-              `reference is left as written`,
-      );
-
-    for (const child of entry.$children ?? []) {
-      rewriteNodeAssets(child, entryDir, mount, onProblem);
-    }
+    const onProblem = assetProblemReporter(typeName, entry);
+    rewriteBodyAssets(entry, filePath, mount, typeName);
 
     for (const field of uriFields) {
       const value = entry.data[field];
-      if (typeof value === "string") {
+      if (isString(value)) {
         entry.data[field] = rewriteRef(value, entryDir, mount, onProblem) ?? value;
       } else if (Array.isArray(value)) {
         entry.data[field] = value.map((item) =>
-          typeof item === "string" ? (rewriteRef(item, entryDir, mount, onProblem) ?? item) : item,
+          isString(item) ? (rewriteRef(item, entryDir, mount, onProblem) ?? item) : item,
         );
       }
     }
   }
 }
 
+/** The warning for one asset reference an entry makes that its collection will not publish. */
+function assetProblemReporter(typeName: string, entry: ContentLoaderEntry) {
+  return (value: string, problem: RefProblem) =>
+    console.warn(
+      problem === "missing"
+        ? `Content type "${typeName}": entry "${entry.id}" references missing asset "${value}"`
+        : `Content type "${typeName}": entry "${entry.id}" references "${value}", which the ` +
+            `collection does not publish (it is excluded, hidden or a document), so the ` +
+            `reference is left as written`,
+    );
+}
+
+/**
+ * The body half of {@link rewriteEntryAssets}: remap the media references in an entry's `$children`
+ * onto the mount. Separate because a body loaded later (a lazily loaded collection's deferred
+ * entry) gets this pass on its own, after its frontmatter had the other half at load.
+ */
+function rewriteBodyAssets(
+  entry: ContentLoaderEntry,
+  filePath: string,
+  mount: AssetMount,
+  typeName: string,
+) {
+  const entryDir = dirname(filePath);
+  const onProblem = assetProblemReporter(typeName, entry);
+  for (const child of entry.$children ?? []) {
+    rewriteNodeAssets(child, entryDir, mount, onProblem);
+  }
+}
+
 // ─── Content Config ───────────────────────────────────────────────────────────
 
 /**
@@ -477,6 +516,9 @@ export function rewriteEntryAssets(
 export function loadContentConfig(projectRoot: string, projectConfig?: ProjectConfig) {
   const contentDir = resolve(projectRoot, "content");
 
+  /* SAFETY: `content` is the section this extension owns, and its project fragment schema defines
+     it as content type name → definition, which is what ContentSection spells; the options of a
+     definition are validated again by compileTypeRules when that type loads. */
   const config = { content: (projectConfig?.content as ContentSection | undefined) ?? {} };
 
   return { config, contentDir };
@@ -499,7 +541,23 @@ export async function loadContentSection(
   projectConfig?: ProjectConfig,
 ): Promise<Map<string, ContentLoaderEntry[]>> {
   const contentTypes = new Map<string, ContentLoaderEntry[]>();
-  const mounts = new Map(
+  const mounts = sectionMounts(section, root, projectConfig);
+  for (const name of Object.keys(section)) {
+    contentTypes.set(
+      name,
+      await loadSectionType(name, { formats, mounts, projectConfig, root, section }),
+    );
+  }
+  return contentTypes;
+}
+
+/** A section's asset mounts, keyed by the path below `/content/` a lookup builds. */
+export function sectionMounts(
+  section: ContentSection,
+  root: string,
+  projectConfig: ProjectConfig | undefined,
+): Map<string, AssetMount> {
+  return new Map(
     contentAssetMounts(section, root, projectConfig).map((mount) => [
       /*
        * The path below `/content/` — `<type>` for a plain source, `<type>/<locale>` for a
@@ -508,50 +566,77 @@ export async function loadContentSection(
        * translated entry's `./hero.png` was left unrewritten; and it collided any two types that
        * shared a locale.
        */
-      mount.urlPrefix.slice(`/${SECTION_KEY}/`.length),
+      mount.urlPrefix.slice(`/${CONTENT_SECTION_KEY}/`.length),
       mount,
     ]),
   );
+}
+
+/** What {@link loadSectionType} loads one content type of a section with. */
+export interface SectionTypeSource {
+  section: ContentSection;
+  root: string;
+  formats: FormatRegistry;
+  projectConfig: ProjectConfig | undefined;
+  /** The section's mounts, from {@link sectionMounts}. */
+  mounts: Map<string, AssetMount>;
+  /** Leave entry bodies for later, reporting each deferred entry here. */
+  onDeferred?: DeferredBodyHandler | undefined;
+}
+
+/**
+ * Load one content type of a section, expanding a `{locale}` source over the project's locales.
+ *
+ * @param {string} name - The content type's name in the section
+ * @param {SectionTypeSource} source - The section and what it is loaded with
+ * @returns {Promise<ContentLoaderEntry[]>} The type's entries
+ */
+export async function loadSectionType(
+  name: string,
+  source: SectionTypeSource,
+): Promise<ContentLoaderEntry[]> {
+  const { section, root, formats, projectConfig, mounts, onDeferred } = source;
+  const contentTypeDef = section[name];
+  if (!contentTypeDef) {
+    return [];
+  }
+  const deferral = onDeferred ? { deferBody: true, onDeferred } : {};
+  const typeSource = contentTypeDef.source;
+  if (!isString(typeSource) || !typeSource.includes(LOCALE_PLACEHOLDER)) {
+    return await loadContentType(name, contentTypeDef, root, formats, {
+      mount: mounts.get(name),
+      projectConfig,
+      ...deferral,
+    });
+  }
+  /*
+   * One content type, N directories. Each pass loads a real path and stamps the locale it came
+   * from onto every entry, which is the only thing distinguishing two translations that share an
+   * id — `resolvePaths` reads it back to expand the right ones under a locale-prefixed route.
+   */
   const locales = localesForExpansion(projectConfig);
-  for (const [name, contentTypeDef] of Object.entries(section)) {
-    const source = contentTypeDef?.source;
-    if (typeof source !== "string" || !source.includes(LOCALE_PLACEHOLDER)) {
-      const entries = await loadContentType(name, contentTypeDef, root, formats, {
-        mount: mounts.get(name),
-        projectConfig,
-      });
-      contentTypes.set(name, entries);
-      continue;
-    }
-    /*
-     * One content type, N directories. Each pass loads a real path and stamps the locale it came
-     * from onto every entry, which is the only thing distinguishing two translations that share an
-     * id — `resolvePaths` reads it back to expand the right ones under a locale-prefixed route.
-     */
-    if (locales.length === 0) {
-      console.warn(
-        `Content type "${name}": source "${source}" uses ${LOCALE_PLACEHOLDER}, but the project ` +
-          `declares no i18n locales — nothing to expand it over, so no entries were loaded.`,
-      );
-      contentTypes.set(name, []);
-      continue;
-    }
-    const all: ContentLoaderEntry[] = [];
-    for (const locale of locales) {
-      const localized = { ...contentTypeDef, source: localeSource(root, source, locale) };
-      const entries = await loadContentType(name, localized, root, formats, {
-        locale,
-        mount: mounts.get(`${name}/${locale}`),
-        projectConfig,
-      });
-      for (const entry of entries) {
-        entry._meta = { ...entry._meta, locale };
-      }
-      all.push(...entries);
+  if (locales.length === 0) {
+    console.warn(
+      `Content type "${name}": source "${typeSource}" uses ${LOCALE_PLACEHOLDER}, but the project ` +
+        `declares no i18n locales — nothing to expand it over, so no entries were loaded.`,
+    );
+    return [];
+  }
+  const all: ContentLoaderEntry[] = [];
+  for (const locale of locales) {
+    const localized = { ...contentTypeDef, source: localeSource(root, typeSource, locale) };
+    const entries = await loadContentType(name, localized, root, formats, {
+      locale,
+      mount: mounts.get(`${name}/${locale}`),
+      projectConfig,
+      ...deferral,
+    });
+    for (const entry of entries) {
+      entry._meta = { ...entry._meta, locale };
     }
-    contentTypes.set(name, all);
+    all.push(...entries);
   }
-  return contentTypes;
+  return all;
 }
 
 /**
@@ -585,7 +670,15 @@ interface TypeRules {
   idField: string | undefined;
   route: RouteSpec | null;
   links: LinkMode;
-  alerts: unknown;
+  alerts: ContentTypeDef["alerts"];
+}
+
+/** The values `links` accepts. */
+const LINK_MODES = ["warn", "error", "ignore"] as const;
+
+/** Whether a `links` option names one of the {@link LINK_MODES}; it is project.json data. */
+function isLinkMode(value: JsonValue): value is LinkMode {
+  return LINK_MODES.some((mode) => mode === value);
 }
 
 /** Every key a content type's definition means something by. */
@@ -651,7 +744,7 @@ function compileTypeRules(name: string, def: ContentTypeDef): TypeRules {
   const at = `Content type "${name}"`;
   try {
     for (const key of Object.keys(def)) {
-      if ((KNOWN_TYPE_KEYS as readonly string[]).includes(key) || key === "$comment") {
+      if (KNOWN_TYPE_KEYS.some((known) => known === key) || key === "$comment") {
         continue;
       }
       const suggestion = nearestOption(key);
@@ -662,11 +755,12 @@ function compileTypeRules(name: string, def: ContentTypeDef): TypeRules {
         `${at}: ignores the unknown option "${key}" (the options are ${KNOWN_TYPE_KEYS.join(", ")})`,
       );
     }
-    if (def.idField !== undefined && (typeof def.idField !== "string" || def.idField === "")) {
+    // `idField` and `links` are project.json data: checked here, whatever their declared types say.
+    if (def.idField !== undefined && (!isString(def.idField) || def.idField === "")) {
       throw new TypeError(`"idField" must be a field name`);
     }
     const links = def.links ?? "warn";
-    if (links !== "warn" && links !== "error" && links !== "ignore") {
+    if (!isLinkMode(links)) {
       throw new TypeError(
         `"links" must be "warn", "error" or "ignore", got ${JSON.stringify(links)}`,
       );
@@ -714,8 +808,21 @@ interface FinishContext {
   entryExtensions: Set<string>;
   /** The source directory, when there is one. */
   sourceRoot: string | undefined;
+  /** Set when the files were loaded without their bodies: loads one file again, body and all. */
+  reload?: ((filePath: string) => Promise<ContentLoaderEntry[]>) | undefined;
+  /** Told of each entry whose body was deferred, with what completes it. */
+  onDeferred?: DeferredBodyHandler | undefined;
 }
 
+/**
+ * Told of one entry loaded without its body, and handed what completes it: load the body, then give
+ * it the asset and link passes the rest of the collection's bodies got at load.
+ */
+export type DeferredBodyHandler = (
+  entry: ContentLoaderEntry,
+  completeBody: () => Promise<void>,
+) => void;
+
 /**
  * The collection-wide pass every source kind goes through once its files are loaded.
  *
@@ -778,7 +885,7 @@ function finishEntries(files: LoadedFile[], ctx: FinishContext): ContentLoaderEn
   if (rules.idField) {
     for (const entry of entries) {
       const value = entry.data[rules.idField];
-      if ((typeof value === "string" && value !== "") || typeof value === "number") {
+      if ((isString(value) && value !== "") || isNumber(value)) {
         /* An id becomes a directory name under the output (`$paths` hands it to a page), and a
            frontmatter value is not trusted to stay inside it. */
         const unsafe = traversalReason(String(value));
@@ -825,9 +932,8 @@ function finishEntries(files: LoadedFile[], ctx: FinishContext): ContentLoaderEn
   // 5. Routes, and links over the finished routes.
   if (rules.route) {
     assignRoutes(entries, unpublished, ctx, rules.route);
-    if (ctx.sourceRoot) {
-      resolveEntryLinks(kept, unpublished, ctx);
-    }
+    const links = ctx.sourceRoot ? resolveEntryLinks(kept, unpublished, ctx) : undefined;
+    deferBodies(kept, ctx, links);
     /* An entry the template could not route, or whose route another entry holds, has no page, and
        a collection is what every consumer (a listing, the search index, a feed) publishes from. Left
        in, each of them would invent a URL for it from its own idea of one and point readers at a
@@ -835,9 +941,59 @@ function finishEntries(files: LoadedFile[], ctx: FinishContext): ContentLoaderEn
        link index above already knows why it has no page; the collection does not carry it. */
     return entries.filter((entry) => entry._meta?.route !== undefined);
   }
+  deferBodies(kept, ctx);
   return entries;
 }
 
+/**
+ * Hand each entry that was loaded without its body to `onDeferred`, with what completes it.
+ *
+ * Completing one does for that entry exactly what {@link finishEntries} did for every body it was
+ * given: the full load supplies `$children` and the `_meta` fields read from the body, then the
+ * body's assets move onto the mount and its links resolve against the collection's own index. The
+ * frontmatter half is untouched; it was finished with the rest of the collection. Only a file that
+ * yielded one entry is deferred, since a reload answers per file.
+ */
+function deferBodies(kept: LoadedFile[], ctx: FinishContext, links?: LinkIndex): void {
+  const { reload, onDeferred } = ctx;
+  if (!reload || !onDeferred) {
+    return;
+  }
+  for (const file of kept) {
+    const [entry] = file.entries;
+    if (file.entries.length !== 1 || !entry || entry.$children !== undefined) {
+      continue;
+    }
+    onDeferred(entry, async () => {
+      const [full] = await reload(file.filePath);
+      if (!full) {
+        return;
+      }
+      /* Rebuilt in place, in the full load's key order: the entry is already referenced (by the
+         collection, and by any entry relating to it), and an entry whose body arrived late should
+         serialize exactly as one loaded whole. Everything the collection pass decided about it
+         (its id, data, route) is kept; the full load contributes only what came from the body. */
+      const completed: ContentLoaderEntry = {
+        ...full,
+        ...entry,
+        _meta: { ...full._meta, ...entry._meta },
+      };
+      for (const key of Object.keys(entry)) {
+        Reflect.deleteProperty(entry, key);
+      }
+      Object.assign(entry, completed);
+      if (ctx.mount) {
+        rewriteBodyAssets(entry, file.filePath, ctx.mount, ctx.name);
+      }
+      if (links && file.rel !== null) {
+        const broken: BrokenLink[] = [];
+        collectBrokenLinks(entry, file.rel, links, broken, new Set());
+        reportBrokenLinks(broken, ctx.name, ctx.rules.links);
+      }
+    });
+  }
+}
+
 /**
  * Keep a folder's id for its `index` file when its `README` would also claim it.
  *
@@ -874,7 +1030,7 @@ function settleIndexIds(name: string, entries: ContentLoaderEntry[]): void {
 /** The site's `build.trailingSlash`, defaulting to `"always"` exactly as the build does. */
 function trailingSlashOf(projectConfig: ProjectConfig | undefined): string {
   const value = projectConfig?.build?.trailingSlash;
-  return typeof value === "string" ? value : "always";
+  return isString(value) ? value : "always";
 }
 
 /** The URL prefix a collection's locale puts in front of its routes (`/fr`), or `""`. */
@@ -963,13 +1119,38 @@ interface BrokenLink {
  * which of them are published, which directory each README or index stands for), then reports each
  * link that has no page at the severity `links` asks for. In `error` mode all of them are gathered
  * and thrown together, so one build names every broken link instead of one per run.
+ *
+ * An entry whose body has not been loaded yet (a lazily loaded collection) has no links to rewrite
+ * here; the index is returned so its body is resolved against the same one when it loads.
+ *
+ * @returns {LinkIndex} The collection's link index
  */
 function resolveEntryLinks(
   kept: LoadedFile[],
   unpublished: Map<string, string>,
   ctx: FinishContext,
-): void {
-  const { name, rules, sourceRoot } = ctx;
+): LinkIndex {
+  const index = buildLinkIndex(kept, unpublished, ctx);
+  const broken: BrokenLink[] = [];
+  const seen = new Set<string>();
+  for (const file of kept) {
+    for (const entry of file.entries) {
+      if (entry.$children && file.rel !== null) {
+        collectBrokenLinks(entry, file.rel, index, broken, seen);
+      }
+    }
+  }
+  reportBrokenLinks(broken, ctx.name, ctx.rules.links);
+  return index;
+}
+
+/** The {@link LinkIndex} for one collection: every file it loaded and what became of each. */
+function buildLinkIndex(
+  kept: LoadedFile[],
+  unpublished: Map<string, string>,
+  ctx: FinishContext,
+): LinkIndex {
+  const { rules, sourceRoot } = ctx;
   const files = new Map<string, FileOutcome>();
   const indexes = new Map<string, string>();
   const isReadme = (rel: string) => /^readme\./i.test(rel.slice(rel.lastIndexOf("/") + 1));
@@ -1007,7 +1188,7 @@ function resolveEntryLinks(
   }
 
   const onDisk = (path: string) => resolve(sourceRoot!, path);
-  const index: LinkIndex = {
+  return {
     asset: (path) => {
       const absolute = onDisk(path);
       if (!ctx.mount || !existsSync(absolute) || statSync(absolute).isDirectory()) {
@@ -1036,30 +1217,34 @@ function resolveEntryLinks(
     localePrefix: localePrefixOf(ctx),
     trailingSlash: trailingSlashOf(ctx.projectConfig),
   };
+}
 
-  const broken: BrokenLink[] = [];
-  const seen = new Set<string>();
-  for (const file of kept) {
-    for (const entry of file.entries) {
-      if (!entry.$children || file.rel === null) {
-        continue;
-      }
-      rewriteLinks(entry.$children as ContentNodes, file.rel, index, (problem) => {
-        const key = `${file.rel}\0${problem.href}`;
-        if (!seen.has(key)) {
-          seen.add(key);
-          broken.push({ from: file.rel!, href: problem.href, reason: problem.reason });
-        }
-      });
+/** Rewrite one entry's links against the index, adding each link with no page to `broken`. */
+function collectBrokenLinks(
+  entry: ContentLoaderEntry,
+  rel: string,
+  index: LinkIndex,
+  broken: BrokenLink[],
+  seen: Set<string>,
+): void {
+  rewriteLinks(entry.$children ?? [], rel, index, (problem) => {
+    const key = `${rel}\0${problem.href}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      broken.push({ from: rel, href: problem.href, reason: problem.reason });
     }
-  }
-  if (rules.links === "ignore" || broken.length === 0) {
+  });
+}
+
+/** Report broken links at the severity the collection's `links` option asks for. */
+function reportBrokenLinks(broken: BrokenLink[], name: string, mode: LinkMode): void {
+  if (mode === "ignore" || broken.length === 0) {
     return;
   }
   const lines = broken.map(
     ({ from, href, reason }) => `"${from}" links to "${href}", which ${reason}`,
   );
-  if (rules.links === "error") {
+  if (mode === "error") {
     const plural = broken.length === 1 ? "" : "s";
     const list = lines.map((line) => `  - ${line}`).join("\n");
     throw new Error(`Content links: "${name}" has ${broken.length} broken link${plural}:\n${list}`);
@@ -1091,6 +1276,13 @@ interface LoadOptions {
   projectConfig?: ProjectConfig | undefined;
   /** The locale this load is for, when the source carried `{locale}`. */
   locale?: string | undefined;
+  /**
+   * Ask the format to leave entry bodies unparsed (`deferBody`), and report each deferred entry to
+   * `onDeferred`. A format that does not honor the option returns whole entries, and nothing is
+   * deferred.
+   */
+  deferBody?: boolean | undefined;
+  onDeferred?: DeferredBodyHandler | undefined;
 }
 
 /**
@@ -1114,8 +1306,8 @@ async function loadContentType(
   if (!source) {
     return [];
   }
-  const { mount, projectConfig, locale } = options;
-  const schema = contentTypeDef.schema as ContentTypeSchema | undefined;
+  const { mount, projectConfig, locale, deferBody, onDeferred } = options;
+  const { schema } = contentTypeDef;
   const rules = compileTypeRules(name, contentTypeDef);
   const finishContext = (extra: Partial<FinishContext>): FinishContext => ({
     coerceDates: false,
@@ -1133,11 +1325,10 @@ async function loadContentType(
   // Derive directive allowedNames from content type $elements (tag names from npm packages)
   const directiveOptions = contentTypeDef.$elements?.length
     ? {
-        allowedNames: contentTypeDef.$elements
-          .filter(
-            (e) => typeof e === "string" || (typeof e === "object" && (e as JxMutableNode)?.$ref),
-          )
-          .map((e) => (typeof e === "string" ? e : (e as JxMutableNode).$ref)),
+        // A tag name as written, or the `$ref` of an element reference; anything else names nothing.
+        allowedNames: contentTypeDef.$elements.flatMap((e) =>
+          isString(e) ? [e] : isNonNullObject(e) && e.$ref ? [e.$ref] : [],
+        ),
       }
     : undefined;
 
@@ -1170,11 +1361,11 @@ async function loadContentType(
     }
     let remote: ContentLoaderEntry[];
     try {
-      remote = (await entry.call("load", source, {
+      remote = await entry.call("load", source, {
         directiveOptions,
         schema,
         ...(rules.idField !== undefined && { idField: rules.idField }),
-      })) as ContentLoaderEntry[];
+      });
     } catch (error) {
       console.warn(`Content type "${name}": ${errorMessage(error)}`);
       return [];
@@ -1222,33 +1413,41 @@ async function loadContentType(
   }
 
   // Discover entry files via the class, then load each
+  const discoverOptions: FormatDiscoverOptions = { baseDir: projectRoot };
+  if (!rules.exclude.empty) {
+    discoverOptions.exclude = contentTypeDef.exclude;
+  }
   const discovered = entry.capabilities.discover
-    ? ((await entry.call("discover", source, {
-        baseDir: projectRoot,
-        ...(rules.exclude.empty ? {} : { exclude: contentTypeDef.exclude }),
-      })) as string[])
+    ? await entry.call("discover", source, discoverOptions)
     : [resolvedSource];
   const files = discovered.filter((file) => !isExcluded(file));
 
   const fileExtensions = files.map((file) => extname(file).toLowerCase());
+  const format = entry;
+  /** One file's load, with or without its body. */
+  const loadFile = (filePath: string, withoutBody: boolean) => {
+    const rel = relOf(filePath);
+    return format.call("load", filePath, {
+      directiveOptions,
+      schema,
+      ...(sourceRoot !== undefined && { sourceRoot }),
+      ...(rules.alerts !== undefined && { alerts: rules.alerts }),
+      ...(rules.idField !== undefined && { idField: rules.idField }),
+      ...(withoutBody && { deferBody: true }),
+      onUnknownAlert: (type: string) =>
+        console.warn(
+          `Content callouts: "${name}": "${rel ?? filePath}" has a [!${type}] callout, but ` +
+            `"${type.toLowerCase()}" is not an enabled type, so it stays a blockquote with the ` +
+            `marker showing. Add "alerts": { "${type.toUpperCase()}": true } to render it.`,
+        ),
+    });
+  };
   const loaded: LoadedFile[] = [];
   for (const filePath of files) {
     const rel = relOf(filePath);
     let fileEntries: ContentLoaderEntry[];
     try {
-      fileEntries = (await entry.call("load", filePath, {
-        directiveOptions,
-        schema,
-        ...(sourceRoot !== undefined && { sourceRoot }),
-        ...(rules.alerts !== undefined && { alerts: rules.alerts }),
-        ...(rules.idField !== undefined && { idField: rules.idField }),
-        onUnknownAlert: (type: string) =>
-          console.warn(
-            `Content callouts: "${name}": "${rel ?? filePath}" has a [!${type}] callout, but ` +
-              `"${type.toLowerCase()}" is not an enabled type, so it stays a blockquote with the ` +
-              `marker showing. Add "alerts": { "${type.toUpperCase()}": true } to render it.`,
-          ),
-      })) as ContentLoaderEntry[];
+      fileEntries = await loadFile(filePath, deferBody === true);
     } catch (error) {
       throw unreadableFile(name, rel ?? filePath, error);
     }
@@ -1272,6 +1471,10 @@ async function loadContentType(
       coerceDates: true,
       entryExtensions: new Set([...entry.extensions, ...fileExtensions]),
       sourceRoot,
+      ...(deferBody === true && {
+        onDeferred,
+        reload: async (filePath: string) => await loadFile(filePath, false),
+      }),
     }),
   );
 }
@@ -1280,11 +1483,11 @@ async function loadContentType(
  * The error for one file that would not load, with its path: a parse failure names a line and a
  * reason but never the file, and a vault is hundreds of them.
  */
-function unreadableFile(type: string, path: string, error: unknown): Error {
+function unreadableFile(type: string, path: string, cause: unknown): Error {
   return new Error(
-    `Content type "${type}": cannot read "${path}": ${errorMessage(error)}. Fix the file, or add it ` +
+    `Content type "${type}": cannot read "${path}": ${errorMessage(cause)}. Fix the file, or add it ` +
       `to "exclude" if it is not a document (a templates folder, for example).`,
-    { cause: error },
+    { cause },
   );
 }
 
@@ -1297,8 +1500,23 @@ function unknownFormatError(path: string, ext: string): Error {
   );
 }
 
-function errorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function errorMessage(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+/**
+ * The JavaScript type name of a field value, as `typeof` spells it, for a validation message. A
+ * date, a list, a nested object, a resolved entry and `null` are all `"object"`, as they are
+ * there.
+ */
+function jsTypeName(value: ContentFieldValue): string {
+  if (isString(value)) {
+    return "string";
+  }
+  if (isNumber(value)) {
+    return "number";
+  }
+  return isBoolean(value) ? "boolean" : "object";
 }
 
 // ─── Schema Validation ────────────────────────────────────────────────────────
@@ -1336,26 +1554,26 @@ function validateEntries(
         continue;
       }
 
-      if (isDateFormat(def.format) && typeof value === "string" && !isCoercedDate(value)) {
+      if (isDateFormat(def.format) && isString(value) && !isCoercedDate(value)) {
         console.warn(
           `Content validation: "${contentTypeName}/${entry.id}" field "${field}" is declared ` +
             `${def.format} but "${value}" was not coerced — it will sort and filter as plain text.`,
         );
-      } else if (def.type === "string" && typeof value !== "string") {
+      } else if (def.type === "string" && !isString(value)) {
         console.warn(
-          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected string, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected string, got ${jsTypeName(value)}`,
         );
-      } else if (def.type === "number" && typeof value !== "number") {
+      } else if (def.type === "number" && !isNumber(value)) {
         console.warn(
-          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected number, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected number, got ${jsTypeName(value)}`,
         );
-      } else if (def.type === "boolean" && typeof value !== "boolean") {
+      } else if (def.type === "boolean" && !isBoolean(value)) {
         console.warn(
-          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected boolean, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected boolean, got ${jsTypeName(value)}`,
         );
       } else if (def.type === "array" && !Array.isArray(value)) {
         console.warn(
-          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected array, got ${typeof value}`,
+          `Content validation: "${contentTypeName}/${entry.id}" field "${field}" expected array, got ${jsTypeName(value)}`,
         );
       }
     }
@@ -1375,6 +1593,25 @@ function refTargetName(ref: string | undefined): string | undefined {
   return ref.slice(CONTENT_REF_PREFIX.length);
 }
 
+/**
+ * The content types a content type's schema points into: each field whose `$ref` (to-one) or
+ * `items.$ref` (to-many) is a `#/content/<name>` pointer. What {@link resolveContentTypeRefs} will
+ * look up for this type, so a type can be loaded together with exactly what it relates to.
+ *
+ * @param {ContentTypeDef | undefined} def - The content type's definition
+ * @returns {string[]} The referenced type names, each once
+ */
+export function referencedContentTypes(def: ContentTypeDef | undefined): string[] {
+  const targets = new Set<string>();
+  for (const field of Object.values(def?.schema?.properties ?? {})) {
+    const target = refTargetName(field.$ref) ?? refTargetName(field.items?.$ref);
+    if (target !== undefined) {
+      targets.add(target);
+    }
+  }
+  return [...targets];
+}
+
 /**
  * Resolve cross-content-type relationship references in entry data (specs/relationships.md). A bare
  * field `$ref` is to-one: a blog post's `author: "jane-doe"` with a schema `$ref` of
@@ -1390,7 +1627,7 @@ export function resolveContentTypeRefs(
   section: ContentSection,
 ) {
   for (const [name, contentTypeDef] of Object.entries(section)) {
-    const schema = contentTypeDef.schema as ContentTypeSchema | undefined;
+    const { schema } = contentTypeDef;
     if (!schema?.properties) {
       continue;
     }
@@ -1417,7 +1654,7 @@ export function resolveContentTypeRefs(
 
       for (const entry of entries) {
         const value = entry.data[field];
-        if (toOne && typeof value === "string") {
+        if (toOne && isString(value)) {
           const resolved = refEntries.find((e) => e.id === value);
           if (resolved) {
             entry.data[field] = resolved;
@@ -1428,7 +1665,7 @@ export function resolveContentTypeRefs(
           }
         } else if (toMany && Array.isArray(value)) {
           entry.data[field] = value.map((id) => {
-            if (typeof id !== "string") {
+            if (!isString(id)) {
               return id;
             }
             const resolved = refEntries.find((e) => e.id === id);
@@ -1477,13 +1714,13 @@ function reportUnservedRoutes(
     return;
   }
   const patterns = ctx.patterns.map((pattern) => withoutLocalePrefix(pattern, prefix));
-  const unserved = entries
-    .map((entry) => entry._meta?.route)
-    .filter(
-      (route): route is string =>
-        route !== undefined &&
-        !patterns.some((pattern) => routeParams(route, pattern, []) !== null),
-    );
+  const unserved = entries.flatMap((entry) => {
+    const route = entry._meta?.route;
+    return route !== undefined &&
+      !patterns.some((pattern) => routeParams(route, pattern, []) !== null)
+      ? [route]
+      : [];
+  });
   if (unserved.length === 0) {
     return;
   }
@@ -1514,11 +1751,11 @@ function routedPaths(
   entries: ContentLoaderEntry[],
   ctx: ResolvePathsContext,
   urlPattern: string,
-): Record<string, unknown>[] {
+): ContentPathParams[] {
   const { i18n } = resolveI18n(ctx.projectConfig ?? {});
   const prefix = localeUrlPrefix(ctx.locale, i18n);
   const pattern = withoutLocalePrefix(urlPattern, prefix);
-  const paths: Record<string, unknown>[] = [];
+  const paths: ContentPathParams[] = [];
   let example: string | undefined;
   for (const entry of entries) {
     const route = entry._meta?.route;
@@ -1528,7 +1765,11 @@ function routedPaths(
     example ??= route;
     const params = routeParams(route, pattern, ctx.params ?? []);
     if (params) {
-      paths.push({ ...params, ...(entry._meta === undefined ? {} : { _meta: entry._meta }) });
+      const pathEntry: ContentPathParams = { ...params };
+      if (entry._meta !== undefined) {
+        pathEntry._meta = entry._meta;
+      }
+      paths.push(pathEntry);
     }
   }
   if (paths.length === 0 && example !== undefined) {
@@ -1541,6 +1782,225 @@ function routedPaths(
   return paths;
 }
 
+// ─── The section's loaded data ───────────────────────────────────────────────
+
+/*
+ * What `Content.projectData` answers, and what classes read as `_project.content`: a map of content
+ * type name → entries. A build reads every entry of every type, so it gets them all at once, as it
+ * always has. A host that serves one page at a time (the dev server, Studio) asks for the section
+ * lazily (`ProjectDataContext.lazy`, specs/extensions.md §8), and then a type loads the first
+ * time a class asks for it, with only its frontmatter, and an entry's body is parsed only once that
+ * entry is actually returned.
+ *
+ * Both are the same class, so a consumer reads either through `load` and `materialize`, which are
+ * no-ops on a store that is already whole; a consumer that reads the map directly (`get`) is a
+ * build-time one and sees exactly what it always did.
+ */
+
+/** What a store loads its section with. */
+export interface ContentStoreSource {
+  section: ContentSection;
+  root: string;
+  formats: FormatRegistry;
+  projectConfig: ProjectConfig | undefined;
+}
+
+export class ContentStore extends Map<string, ContentLoaderEntry[]> implements ContentSectionData {
+  readonly #source: ContentStoreSource;
+  readonly #mounts: Map<string, AssetMount>;
+  /** Each type's load in flight or done, so concurrent asks share one. */
+  readonly #loads = new Map<string, Promise<void>>();
+  /** Types whose relationship fields have been resolved (it mutates entries, so exactly once). */
+  readonly #linked = new Set<string>();
+  /** Every entry this store loaded, to tell a related entry inside `data` from ordinary data. */
+  readonly #entries = new WeakSet<object>();
+  /** Entries loaded without their body, and what completes each. */
+  readonly #deferred = new WeakMap<ContentLoaderEntry, () => Promise<void>>();
+  /** Bodies being completed, so two requests for one entry share the work. */
+  readonly #completing = new WeakMap<ContentLoaderEntry, Promise<void>>();
+
+  private constructor(source: ContentStoreSource) {
+    super();
+    this.#source = source;
+    this.#mounts = sectionMounts(source.section, source.root, source.projectConfig);
+  }
+
+  /** A store holding every type, bodies and relationships included: what a build reads. */
+  static async whole(source: ContentStoreSource): Promise<ContentStore> {
+    const store = new ContentStore(source);
+    const loaded = await loadContentSection(
+      source.section,
+      source.root,
+      source.formats,
+      source.projectConfig,
+    );
+    for (const [name, entries] of loaded) {
+      store.#adopt(name, entries);
+      store.#loads.set(name, Promise.resolve());
+    }
+    resolveContentTypeRefs(store, source.section);
+    for (const name of loaded.keys()) {
+      store.#linked.add(name);
+    }
+    return store;
+  }
+
+  /** An empty store that loads each type when it is first asked for. */
+  static lazy(source: ContentStoreSource): ContentStore {
+    return new ContentStore(source);
+  }
+
+  /**
+   * One type's entries, loading it (and every type its schema relates it to) on first use.
+   *
+   * @param {string} name - Content type name
+   * @returns {Promise<ContentLoaderEntry[] | undefined>} The entries, or undefined when the section
+   *   declares no such type
+   */
+  async load(name: string): Promise<ContentLoaderEntry[] | undefined> {
+    if (!Object.hasOwn(this.#source.section, name)) {
+      return undefined;
+    }
+    const related = this.#relatedTypes(name);
+    await Promise.all(related.map(async (type) => await this.#loadType(type)));
+    /* Resolved only once everything a type points into is loaded, and synchronously, so two loads
+       finishing together cannot both resolve one type: its fields would be looked up twice, the
+       second time with entries where the ids were. */
+    const unlinked = related.filter((type) => !this.#linked.has(type));
+    for (const type of unlinked) {
+      this.#linked.add(type);
+    }
+    if (unlinked.length > 0) {
+      const { section } = this.#source;
+      resolveContentTypeRefs(
+        this,
+        Object.fromEntries(
+          unlinked.flatMap((type) => (section[type] ? [[type, section[type]]] : [])),
+        ),
+      );
+    }
+    return this.get(name);
+  }
+
+  /**
+   * Give every entry in `entries` its body, and every entry they relate to through a relationship
+   * field, before they are handed out. An entry that already has one is left as it is.
+   *
+   * @param {readonly (ContentLoaderEntry | null | undefined)[]} entries - Entries about to be
+   *   returned
+   */
+  async materialize(entries: readonly (ContentLoaderEntry | null | undefined)[]): Promise<void> {
+    const seen = new Set<ContentLoaderEntry>();
+    const pending: Promise<void>[] = [];
+    const visit = (entry: ContentLoaderEntry) => {
+      if (seen.has(entry)) {
+        return;
+      }
+      seen.add(entry);
+      pending.push(this.#complete(entry));
+      for (const value of Object.values(entry.data)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+          if (this.#isEntry(item)) {
+            visit(item);
+          }
+        }
+      }
+    };
+    for (const entry of entries) {
+      if (entry) {
+        visit(entry);
+      }
+    }
+    await Promise.all(pending);
+  }
+
+  /**
+   * Load every type and give every entry its body: the store becomes exactly what
+   * {@link ContentStore.whole} builds. A host does this before handing `_project` to a class that
+   * reads it synchronously (one that does not declare `projectOnDemand`, specs/extensions.md §8).
+   */
+  async complete(): Promise<void> {
+    const lists = await Promise.all(
+      Object.keys(this.#source.section).map(async (name) => (await this.load(name)) ?? []),
+    );
+    await this.materialize(lists.flat());
+  }
+
+  /** The type and every type reachable through its schema's relationship fields. */
+  #relatedTypes(name: string): string[] {
+    const { section } = this.#source;
+    const found = new Set<string>([name]);
+    const queue = [name];
+    for (let type = queue.shift(); type !== undefined; type = queue.shift()) {
+      for (const target of referencedContentTypes(section[type])) {
+        if (Object.hasOwn(section, target) && !found.has(target)) {
+          found.add(target);
+          queue.push(target);
+        }
+      }
+    }
+    return [...found];
+  }
+
+  #loadType(name: string): Promise<void> {
+    let load = this.#loads.get(name);
+    if (!load) {
+      const { section, root, formats, projectConfig } = this.#source;
+      load = loadSectionType(name, {
+        formats,
+        mounts: this.#mounts,
+        onDeferred: (entry, completeBody) => {
+          this.#deferred.set(entry, completeBody);
+        },
+        projectConfig,
+        root,
+        section,
+      }).then((entries) => {
+        this.#adopt(name, entries);
+      });
+      /* A failed load is not kept: the error reaches this ask, and the next one tries again (the
+         file may have been fixed in between). */
+      load.catch(() => {
+        this.#loads.delete(name);
+      });
+      this.#loads.set(name, load);
+    }
+    return load;
+  }
+
+  #adopt(name: string, entries: ContentLoaderEntry[]): void {
+    for (const entry of entries) {
+      this.#entries.add(entry);
+    }
+    this.set(name, entries);
+  }
+
+  /* A related entry is placed into `data` by `resolveContentTypeRefs`, so membership in the set of
+     entries this store loaded is exactly the test, and it never mistakes an object field for one. */
+  #isEntry(value: ContentLoaderEntry["data"][string]): value is ContentLoaderEntry {
+    return isNonNullObject(value) && this.#entries.has(value);
+  }
+
+  #complete(entry: ContentLoaderEntry): Promise<void> {
+    let completing = this.#completing.get(entry);
+    if (!completing) {
+      const completeBody = this.#deferred.get(entry);
+      if (!completeBody) {
+        return Promise.resolve();
+      }
+      completing = completeBody().then(() => {
+        this.#deferred.delete(entry);
+      });
+      // A failed body is retried by the next ask, as a failed type load is.
+      completing.catch(() => {
+        this.#completing.delete(entry);
+      });
+      this.#completing.set(entry, completing);
+    }
+    return completing;
+  }
+}
+
 // ─── The Content project-section class ───────────────────────────────────────
 
 /**
@@ -1552,25 +2012,25 @@ function routedPaths(
 export class Content {
   /**
    * Load the `content` section: every content type's entries, with relationship references already
-   * resolved.
+   * resolved. A host that asks for it `lazy` gets a {@link ContentStore} that loads each type the
+   * first time a class asks for it and each entry's body only once that entry is returned
+   * (specs/extensions.md §8); either way the answer is a map of type name to entries.
    *
-   * @param {unknown} sectionValue - The project.json `content` section value
-   * @param {ProjectDataContext} ctx - Host context ({ projectConfig, root, registry, io })
-   * @returns {Promise<Map<string, ContentLoaderEntry[]>>} Content type name → entries
+   * @param {ContentSection | undefined} sectionValue - The project.json `content` section value
+   * @param {ProjectDataContext} ctx - Host context ({ projectConfig, root, registry, io, lazy })
+   * @returns {Promise<ContentStore>} Content type name → entries
    */
   static async projectData(
-    sectionValue: unknown,
+    sectionValue: ContentSection | undefined,
     ctx: ProjectDataContext,
-  ): Promise<Map<string, ContentLoaderEntry[]>> {
-    const section = (sectionValue ?? {}) as ContentSection;
-    const data = await loadContentSection(
-      section,
-      ctx.root,
-      ctx.registry.formats,
-      ctx.projectConfig,
-    );
-    resolveContentTypeRefs(data, section);
-    return data;
+  ): Promise<ContentStore> {
+    const source = {
+      formats: ctx.registry.formats,
+      projectConfig: ctx.projectConfig,
+      root: ctx.root,
+      section: sectionValue ?? {},
+    };
+    return ctx.lazy === true ? ContentStore.lazy(source) : await ContentStore.whole(source);
   }
 
   /**
@@ -1578,15 +2038,15 @@ export class Content {
    * Hosts serve, resolve, and copy files through the returned mounts, which is what lets an entry
    * reference `../images/hero.png` and still resolve in a built site, the dev server, and Studio.
    *
-   * @param {unknown} sectionValue - The project.json `content` section value
+   * @param {ContentSection | undefined} sectionValue - The project.json `content` section value
    * @param {{ projectConfig?: ProjectConfig; root: string }} ctx - Host context
    * @returns {AssetMount[]} One mount per content type with a local directory source
    */
   static assets(
-    sectionValue: unknown,
+    sectionValue: ContentSection | undefined,
     ctx: { root: string; projectConfig?: ProjectConfig },
   ): AssetMount[] {
-    return contentAssetMounts((sectionValue ?? {}) as ContentSection, ctx.root, ctx.projectConfig);
+    return contentAssetMounts(sectionValue ?? {}, ctx.root, ctx.projectConfig);
   }
 
   /**
@@ -1611,13 +2071,13 @@ export class Content {
    *
    * @param {ContentPathsSource} pathsDef - The `$paths` value ({ contentType, param?, field? })
    * @param {ResolvePathsContext} ctx - Host context ({ data, projectConfig, root, urlPattern })
-   * @returns {Promise<Record<string, unknown>[]>} Array of route-param objects
+   * @returns {Promise<ContentPathParams[]>} Array of route-param objects
    */
   static async resolvePaths(
     pathsDef: ContentPathsSource,
     ctx: ResolvePathsContext,
-  ): Promise<Record<string, unknown>[]> {
-    const entries = ctx.data.get(pathsDef.contentType);
+  ): Promise<ContentPathParams[]> {
+    const entries = await entriesOf(ctx.data, pathsDef.contentType);
     if (!entries || entries.length === 0) {
       console.warn(
         `Warning: $paths references content type "${pathsDef.contentType}" but it has no entries`,
@@ -1635,7 +2095,7 @@ export class Content {
     const localized = entries.some((entry) => entry._meta?.locale !== undefined);
     const wanted = ctx.locale;
     const scoped =
-      localized && typeof wanted === "string"
+      localized && isString(wanted)
         ? entries.filter((entry) => entry._meta?.locale === wanted)
         : entries;
     if (
@@ -1646,7 +2106,7 @@ export class Content {
     ) {
       return routedPaths(pathsDef.contentType, scoped, ctx, ctx.urlPattern);
     }
-    const paths: Record<string, unknown>[] = [];
+    const paths: ContentPathParams[] = [];
     for (const entry of scoped) {
       const value = field === "id" ? entry.id : (entry.data[field] ?? entry.id);
       if (!value) {
@@ -1663,7 +2123,7 @@ export class Content {
         );
         continue;
       }
-      const pathEntry: Record<string, unknown> = { [param]: value };
+      const pathEntry: ContentPathParams = { [param]: value };
       if (entry._meta !== undefined) {
         pathEntry._meta = entry._meta;
       }