content-query 0.1.0 → 0.2.0

package/README.md

@@ -9,7 +9,7 @@ Use it with your existing framework. Your application owns its routes, layouts,
 - **Typed schemas.** Validate metadata with bundled schema builders or any Standard Schema V1 provider, with inferred TypeScript types.
 - **Flexible sources.** Load local files, use Astro-compatible content loaders, or write your own loader.
 - **Queries and relationships.** Select fields, filter, sort, paginate, and load related entries with validated references.
-- **Markdown rendering.** Get HTML, headings, and syntax highlighting separately from metadata queries.
+- **Markdown rendering.** Request HTML, headings, and syntax highlighting as query payloads, loaded only when a query asks for them.
 - **Framework integrations.** Use Vite, Next.js, or the standalone CLI, with content updates during development.
 
 ## Usage
@@ -54,10 +54,28 @@ const posts = await content
   .from("posts")
   .where((fields) => eq(fields.draft, false))
   .orderBy("title");
+
+const post = await content.query.posts.findFirst({
+  where: { id: posts[0]!.id },
+  payloads: { _rendered: true },
+});
+const { html, headings } = post!._payloads._rendered;
 ```
 
 Add `.content-query/` to `.gitignore`. Follow the quick start for a complete walkthrough, or choose a framework example below.
 
+## Migrating to 0.2
+
+Version 0.2.0 removes `content.readBody()` and `content.render()`. Request bodies and rendered output as payloads in the query that loads the entry:
+
+| 0.1                                   | 0.2                                                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `await content.readBody("posts", id)` | `(await content.query.posts.findFirst({ where: { id }, payloads: { _body: true } }))?._payloads._body`         |
+| `await content.render("posts", id)`   | `(await content.query.posts.findFirst({ where: { id }, payloads: { _rendered: true } }))?._payloads._rendered` |
+| Fluent queries                        | Add `.withPayload("_rendered")` or `.withPayload("_body")` before the terminal.                                |
+
+Built-in payload names start with an underscore: `_body` and `_rendered`. A query for a missing entry returns `undefined` instead of rejecting with `entry-not-found`, which no longer exists. JSON, YAML, and TOML sources and `file()` collections offer no payloads. Rebuild generated content after upgrading; 0.1 artifacts are rejected.
+
 ## Documentation
 
 - [Quick start](https://github.com/yangshun/content-query/blob/main/website/content/guides/quick-start.md)
@@ -67,4 +85,8 @@ Add `.content-query/` to `.gitignore`. Follow the quick start for a complete wal
 
 The Vite integration supports Vite 8, and the Next.js integration supports Next.js 16. Both integrations are optional; standalone builds and queries require neither framework.
 
+Pass `contentQuery()` directly to Vite or Vite+'s `plugins` array. No `Plugin` type cast is needed; workspace consumers share the pinned toolchain versions in the dependency catalog.
+
+Repository development checks package types and isolated consumers with [tsrs](https://github.com/oxc-project/tsrs). Run `vp run check` in the package directory for formatting, linting, and type checks; build tools use the shared TypeScript 6 compatibility package for its `6.0.3` JavaScript API. Native TypeScript `7.1.0-beta` is available at the repository root as `vp exec tsc`.
+
 Released under the [MIT license](https://github.com/yangshun/content-query/blob/main/LICENSE).

package/dist/{build-DSyoRxkZ.d.mts → build-DfKd2bpf.d.mts}

@@ -1,6 +1,5 @@
-import { n as CollectionRegistry } from "./types-BPh2cBPs.mjs";
-import { s as InvalidRelationships, t as Content } from "./content-Crag1Uch.mjs";
-
+import { i as CollectionRegistry } from "./types-C-kdMblM.mjs";
+import { s as InvalidRelationships, t as Content } from "./content-G69dPPuo.mjs";
 //#region src/preparation/session.d.ts
 type ContentSession<Registry extends CollectionRegistry = {}> = {
   content: Content<Registry>;
@@ -10,8 +9,10 @@ type ContentSession<Registry extends CollectionRegistry = {}> = {
 //#region src/preparation/build.d.ts
 /** Options shared by standalone content builds and host integrations. */
 type BuildContentOptions = {
-  /** Exact config path; omission discovers one content-query.config.{ts,mts,cts,js,mjs,cjs} file. */config?: string;
-  backend?: "in-memory" | "generated"; /** Generated backend output directory, relative to the application root; defaults to ./.content-query. */
+  /** Exact config path; omission discovers one content-query.config.{ts,mts,cts,js,mjs,cjs} file. */
+  config?: string;
+  backend?: "in-memory" | "generated";
+  /** Generated backend output directory, relative to the application root; defaults to ./.content-query. */
   outDir?: string;
   watch?: boolean;
 };

package/dist/{build-C5ef0kkR.mjs → build-Dxz7P1ur.mjs}

@@ -1,9 +1,9 @@
-import { a as builtinLoader, i as validate, n as normalizeSnapshot, o as builtinPath, r as renderedPayload, t as isRecord } from "./validation-BvvjSUFc.mjs";
-import { i as groupDiagnostics, n as contentError, o as withContext, t as ContentError } from "./errors-C8lWyiy2.mjs";
-import { i as detach, l as valuePath, o as encode } from "./values-B7lo_2_x.mjs";
-import { t as assertServerOnly } from "./server-only-CIE-FHx0.mjs";
-import { a as CODEC_VERSION, i as prepareRelationships, n as createRuntime, r as isRelationship } from "./content-Dj2fQCJ5.mjs";
-import { t as renderMarkdown } from "./markdown-CZBL4Ux_.mjs";
+import { a as builtinLoader, i as validate, n as normalizeSnapshot, o as builtinPath, r as renderedPayload, t as isRecord } from "./validation-D_XdE1pF.mjs";
+import { i as groupDiagnostics, n as contentError, o as withContext, t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { i as detach, l as valuePath, o as encode } from "./values-BbTV4QT-.mjs";
+import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
+import { a as CODEC_VERSION, i as prepareRelationships, n as createRuntime, r as isRelationship } from "./content-N1gYshjg.mjs";
+import { t as renderMarkdown } from "./markdown-CHvBBJNa.mjs";
 import { access, link, mkdir, readFile, readdir, realpath, rm, rmdir, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -33,7 +33,7 @@ function compactJson(source) {
 async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 	const modules = /* @__PURE__ */ new Map();
 	const manifest = {
-		version: 1,
+		version: 2,
 		codec: CODEC_VERSION,
 		collections: revision.registry
 	};
@@ -62,7 +62,7 @@ async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 			batch = [];
 			batchBytes = 0;
 		}
-		for (const [id, load] of collection.payloads) {
+		for (const [id, load] of collection.builtins) {
 			const payload = await load();
 			const encoded = encode(payload);
 			needsRenderer ||= payload.markdown !== void 0;
@@ -87,7 +87,7 @@ async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 		const helpers = [...chunks.length ? ["createPayloadLoaders"] : [], ...compressedRecords ? ["decodeCompressed"] : []];
 		const loaders = helpers.length ? `import { ${helpers.join(", ")} } from "content-query/internal";\n` : "";
 		const loading = chunks.length ? `createPayloadLoaders([${chunks.join(",\n")}])` : `{ ${payloads.join(",\n")} }`;
-		const code = `${loaders}export default { records: ${compressedRecords ? `decodeCompressed(${compressedRecords})` : recordSource}, payloads: ${loading} };\n`;
+		const code = `${loaders}export default { records: ${compressedRecords ? `decodeCompressed(${compressedRecords})` : recordSource}, builtins: ${loading} };\n`;
 		const index = `index-${digest(code)}.js`;
 		modules.set(`${directory}/${index}`, code);
 		modules.set(`${directory}/index.js`, `export { default } from ${JSON.stringify(`./${index}`)};\n`);
@@ -224,6 +224,37 @@ async function writeArtifacts(revision, outDir, config, { signal, prune = false
 	if (prune) await pruneArtifacts(outDir, modules);
 }
 //#endregion
+//#region src/collection/registry.ts
+/** Built-in payload names start with an underscore, which custom payload names cannot use. */
+const builtinPayloads = {
+	_body: { variants: [] },
+	_rendered: { variants: [] }
+};
+/**
+* Reports whether a collection can carry built-in `_body` and `_rendered` payloads.
+* This depends only on the declaration, never on the entries a source currently contains.
+*
+* @param definition - A collection definition, including the `source` shorthand when used.
+* @returns False for JSON, YAML, and TOML sources and `file()` loaders; true otherwise.
+*/
+function hasBuiltinPayloads(definition) {
+	const source = definition.source;
+	if (source !== void 0) return typeof source === "string" || source.type === "markdown";
+	return builtinLoader(definition.loader)?.kind !== "file";
+}
+/**
+* Builds the query registry that runtimes validate queries against, without resolvers or schemas.
+*
+* @param registry - The configured collection definitions.
+* @returns Relationship and payload descriptors for each collection.
+*/
+function queryRegistry(registry) {
+	return Object.fromEntries(Object.entries(registry).map(([name, definition]) => [name, {
+		relationships: definition.relationships ?? {},
+		payloads: hasBuiltinPayloads(definition) ? { ...builtinPayloads } : {}
+	}]));
+}
+//#endregion
 //#region src/preparation/prepare.ts
 /** Prepares one immutable revision with loader-defined source metadata, aggregating failures. */
 async function prepareRevision(registry, sources, cache, signal, development, sourceDiagnostics = [], parsedData) {
@@ -231,11 +262,15 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 	const collections = Object.create(null);
 	for (const [collectionName, definition] of Object.entries(registry)) {
 		const records = [];
-		const payloads = /* @__PURE__ */ new Map();
+		const builtins = /* @__PURE__ */ new Map();
 		const computed = definition.computed ?? {};
 		const relationships = definition.relationships ?? {};
 		const declarationNames = [...Object.keys(computed), ...Object.keys(relationships)];
-		if (declarationNames.some((name) => name === "id" || name === "_adjacent") || new Set(declarationNames).size !== declarationNames.length || Object.values(relationships).some((relation) => !isRelationship(relation))) {
+		if (declarationNames.some((name) => [
+			"id",
+			"_adjacent",
+			"_payloads"
+		].includes(name)) || new Set(declarationNames).size !== declarationNames.length || Object.values(relationships).some((relation) => !isRelationship(relation))) {
 			diagnostics.push({
 				code: "validation-error",
 				operation: "build",
@@ -261,7 +296,7 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 			const previous = cache.get(key);
 			if (signature !== void 0 && previous?.signature === signature && previous.definition === definition) {
 				records.push(previous.record);
-				if (Object.keys(previous.payload).length) payloads.set(entry.id, async () => previous.payload);
+				if (Object.keys(previous.payload).length) builtins.set(entry.id, async () => previous.payload);
 				continue;
 			}
 			try {
@@ -269,7 +304,7 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 				const validated = parsed?.has(entry.data) && parsed.get(entry.data) === definition.schema ? entry.data : await validate(definition.schema, entry.data, context);
 				signal.throwIfAborted();
 				if (!isRecord(validated)) throw new Error("Validated metadata must be a record of named fields.");
-				if (Object.hasOwn(validated, "id") || Object.hasOwn(validated, "_adjacent") || declarationNames.some((name) => Object.hasOwn(validated, name))) throw new Error("Metadata, computed fields, relationships, and reserved id/_adjacent must have distinct names.");
+				if (Object.hasOwn(validated, "id") || Object.hasOwn(validated, "_adjacent") || Object.hasOwn(validated, "_payloads") || declarationNames.some((name) => Object.hasOwn(validated, name))) throw new Error("Metadata, computed fields, relationships, and reserved id/_adjacent/_payloads must have distinct names.");
 				const metadata = detach(validated);
 				const values = Object.create(null);
 				const before = diagnostics.length;
@@ -306,16 +341,18 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 				if (entry.body !== void 0 && (!markdown || descriptor?.kind !== "glob" || descriptor.options.retainBody !== false)) payload.body = entry.body;
 				const supplied = renderedPayload(entry);
 				if (supplied) payload.rendered = supplied;
-				else if (markdown && entry.body !== void 0) if (development || descriptor.options.deferRender === true) payload.markdown = entry.body;
-				else try {
-					payload.rendered = await renderMarkdown(entry.body);
-				} catch (cause) {
-					throw new ContentError({
-						...context,
-						code: "render-error",
-						message: "Eager Markdown compilation failed.",
-						cause
-					});
+				else if (markdown && entry.body !== void 0) {
+					if (development || descriptor.options.deferRender === true) payload.markdown = entry.body;
+					else try {
+						payload.rendered = await renderMarkdown(entry.body);
+					} catch (cause) {
+						throw new ContentError({
+							...context,
+							code: "render-error",
+							message: "Eager Markdown compilation failed.",
+							cause
+						});
+					}
 				}
 				encode(payload);
 				cache.set(key, {
@@ -325,7 +362,7 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 					payload
 				});
 				records.push(record);
-				if (Object.keys(payload).length) payloads.set(entry.id, async () => payload);
+				if (Object.keys(payload).length) builtins.set(entry.id, async () => payload);
 			} catch (cause) {
 				const formatted = cause && typeof cause === "object" && "path" in cause && typeof cause.path === "string" ? cause.path : "";
 				const message = cause instanceof Error ? cause.message : "Entry preparation failed.";
@@ -340,14 +377,14 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 		collections[collectionName] = {
 			records,
 			relationships,
-			payloads,
+			builtins,
 			sources: new Map([...sources.get(collectionName)?.values() ?? []].map((entry) => [entry.id, entry.source]))
 		};
 	}
 	signal.throwIfAborted();
 	const revision = {
 		collections,
-		registry: Object.fromEntries(Object.entries(collections).map(([name, collection]) => [name, { relationships: collection.relationships }])),
+		registry: queryRegistry(Object.fromEntries(Object.keys(collections).map((name) => [name, registry[name]]))),
 		relations: /* @__PURE__ */ new Map(),
 		active: 0,
 		payloadCache: /* @__PURE__ */ new Map(),
@@ -364,7 +401,7 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 /** Loads build-only configuration without retaining a previous config module value. */
 async function loadRegistry(config) {
 	const filename = await realpath(config);
-	const dependencies = new Set([filename]);
+	const dependencies = /* @__PURE__ */ new Set([filename]);
 	const transpiler = createJiti(filename, {
 		moduleCache: false,
 		fsCache: false
@@ -707,7 +744,7 @@ function createStores(current, parsed, changed) {
 function guardedWatcher(watcher, run, failed) {
 	const listeners = [];
 	let running = Promise.resolve();
-	const registration = new Set([
+	const registration = /* @__PURE__ */ new Set([
 		"on",
 		"once",
 		"addListener",
@@ -1151,7 +1188,7 @@ async function createSession(options) {
 		registry = nextRegistry;
 		loaders = nextLoaders;
 		configDependencies = loaded.dependencies;
-		state.registry = Object.fromEntries(Object.entries(registry).map(([name, definition]) => [name, { relationships: definition.relationships ?? {} }]));
+		state.registry = queryRegistry(registry);
 		candidates.clear();
 		cache.clear();
 		loadFailures.clear();
@@ -1166,7 +1203,8 @@ async function createSession(options) {
 		const signal = attempt.signal;
 		loading = names;
 		const acquired = await Promise.allSettled([...names].map(async (name) => {
-			return [name, normalizeSnapshot(await loaders.get(name).load({ signal }), name)];
+			const entries = await loaders.get(name).load({ signal });
+			return [name, normalizeSnapshot(entries, name)];
 		}));
 		if (disposed || currentGeneration !== generation) return;
 		loading = /* @__PURE__ */ new Set();

package/dist/build.d.mts

@@ -1,2 +1,2 @@
-import { n as buildContent, r as ContentSession, t as BuildContentOptions } from "./build-DSyoRxkZ.mjs";
+import { n as buildContent, r as ContentSession, t as BuildContentOptions } from "./build-DfKd2bpf.mjs";
 export { type BuildContentOptions, type ContentSession, buildContent };

package/dist/build.mjs

@@ -1,2 +1 @@
-import { n as buildContent } from "./build-C5ef0kkR.mjs";
-export { buildContent };
+export { n as buildContent } from "./build-Dxz7P1ur.mjs";

package/dist/cli.d.mts

@@ -1 +1 @@
-export { };
+export {}

package/dist/cli.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { t as ContentError } from "./errors-C8lWyiy2.mjs";
-import { t as buildAtRoot } from "./build-C5ef0kkR.mjs";
+import { t as ContentError } from "./errors-C2iuBM0G.mjs";
+import { t as buildAtRoot } from "./build-Dxz7P1ur.mjs";
 import { cac } from "cac";
 //#region package.json
-var version = "0.1.0";
+var version = "0.2.0";
 //#endregion
 //#region src/integrations/cli/arguments.ts
 /** Validates one path option after CAC's automatic numeric conversion. */

package/dist/computed.d.mts

@@ -1,37 +1,43 @@
-import { f as MaybePromise } from "./types-hmDOw87q.mjs";
-import { r as ComputedContext } from "./types-BPh2cBPs.mjs";
+import { p as MaybePromise } from "./types-ChaNhj42.mjs";
+import { a as ComputedContext } from "./types-C-kdMblM.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
-
 //#region src/computed/text.d.ts
 /** The syntax removed before computing text-derived fields; literal text preserves all characters. */
 type TextFormat = "markdown" | "text" | "html";
 /** Selects text from validated entry data or loader metadata instead of the captured body. */
 type TextOptions<Data = Record<string, unknown>, Source = unknown> = {
-  /** Defaults to readBody(); undefined text is treated as an empty string. Async selectors are supported. */from?: (context: ComputedContext<Data, Source>) => MaybePromise<string | undefined>; /** Input syntax, defaulting to markdown. */
+  /** Defaults to readBody(); undefined text is treated as an empty string. Async selectors are supported. */
+  from?: (context: ComputedContext<Data, Source>) => MaybePromise<string | undefined>;
+  /** Input syntax, defaulting to markdown. */
   format?: TextFormat;
 };
 /** Controls the reading-speed estimate in addition to selecting its input text. */
 type ReadingTimeOptions<Data = Record<string, unknown>, Source = unknown> = TextOptions<Data, Source> & {
-  /** A finite positive reading speed, defaulting to 200 words per minute. */wordsPerMinute?: number;
+  /** A finite positive reading speed, defaulting to 200 words per minute. */
+  wordsPerMinute?: number;
 };
 /** Controls the maximum excerpt size in addition to selecting its input text. */
 type ExcerptOptions<Data = Record<string, unknown>, Source = unknown> = TextOptions<Data, Source> & {
-  /** A positive integer, defaulting to 160. Counts graphemes and includes the trailing ellipsis. */maxLength?: number;
+  /** A positive integer, defaulting to 160. Counts graphemes and includes the trailing ellipsis. */
+  maxLength?: number;
 };
 /** Creates a numeric computed field counting normalized text with reading-time's word boundaries. */
-declare function wordCount<Data = Record<string, unknown>, Source = unknown>(options?: TextOptions<Data, Source>): {
-  schema: StandardSchemaV1<unknown, number>; /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
+export declare function wordCount<Data = Record<string, unknown>, Source = unknown>(options?: TextOptions<Data, Source>): {
+  schema: StandardSchemaV1<unknown, number>;
+  /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
   resolve(context: ComputedContext<Data, Source>): Promise<number>;
 };
 /** Creates a numeric computed field estimating whole reading minutes, rounded up; empty text returns zero. */
-declare function readingTime<Data = Record<string, unknown>, Source = unknown>(options?: ReadingTimeOptions<Data, Source>): {
-  schema: StandardSchemaV1<unknown, number>; /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
+export declare function readingTime<Data = Record<string, unknown>, Source = unknown>(options?: ReadingTimeOptions<Data, Source>): {
+  schema: StandardSchemaV1<unknown, number>;
+  /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
   resolve(context: ComputedContext<Data, Source>): Promise<number>;
 };
 /** Creates a string computed field containing a normalized plain-text excerpt with a bounded length. */
-declare function excerpt<Data = Record<string, unknown>, Source = unknown>(options?: ExcerptOptions<Data, Source>): {
-  schema: StandardSchemaV1<unknown, string>; /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
+export declare function excerpt<Data = Record<string, unknown>, Source = unknown>(options?: ExcerptOptions<Data, Source>): {
+  schema: StandardSchemaV1<unknown, string>;
+  /** Resolves selected text during preparation and honors cancellation around asynchronous input. */
   resolve(context: ComputedContext<Data, Source>): Promise<string>;
 };
 //#endregion
-export { type ExcerptOptions, type ReadingTimeOptions, type TextFormat, type TextOptions, excerpt, readingTime, wordCount };
+export type { ExcerptOptions, ReadingTimeOptions, TextFormat, TextOptions };

package/dist/computed.mjs

@@ -1,18 +1,18 @@
-import { t as assertServerOnly } from "./server-only-CIE-FHx0.mjs";
-import { n as number, r as string } from "./schema-CnCbMosm.mjs";
-import { t as src_default } from "./dist-BQGVLZyl.mjs";
+import { t as assertServerOnly } from "./server-only-CIJUlyL-.mjs";
+import { n as number, r as string } from "./schema-C5Str-E8.mjs";
+import { t as src_default } from "./dist-C7_FOzY_.mjs";
 import getReadingTime from "reading-time";
 import { Parser } from "htmlparser2";
 //#region src/computed/plain-text.ts
 const markdown = new src_default({ html: true });
-const ignoredElements = new Set([
+const ignoredElements = /* @__PURE__ */ new Set([
 	"head",
 	"script",
 	"style",
 	"template",
 	"noscript"
 ]);
-const blockElements = new Set([
+const blockElements = /* @__PURE__ */ new Set([
 	"address",
 	"article",
 	"aside",
@@ -96,6 +96,7 @@ function textField(schema, options, compute) {
 	if (from !== void 0 && typeof from !== "function") throw new TypeError("Text from must be a function.");
 	return {
 		schema,
+		/** Resolves selected text during preparation and honors cancellation around asynchronous input. */
 		async resolve(context) {
 			context.signal.throwIfAborted();
 			const input = await (from ? from(context) : context.readBody());

package/dist/{content-Crag1Uch.d.mts → content-G69dPPuo.d.mts}

@@ -1,7 +1,6 @@
-import { n as ContentRenderResult } from "./types-DcvHRmxO.mjs";
-import { a as Relationship, i as QueryData, n as CollectionRegistry, o as RelationshipsOf } from "./types-BPh2cBPs.mjs";
-import { _ as QueryPlan, n as RelationalQueries, t as RelationalCountOptions, u as Query, v as QueryRegistry } from "./relational-types-DLniKi5S.mjs";
-
+import { n as ContentRenderResult } from "./types-Dh-Sydyw.mjs";
+import { c as Relationship, i as CollectionRegistry, l as RelationshipsOf, s as QueryData } from "./types-C-kdMblM.mjs";
+import { _ as QueryPlan, n as RelationalQueries, t as RelationalCountOptions, u as Query, v as QueryRegistry } from "./relational-types-DgK3rLuw.mjs";
 //#region src/collection/registry-types.d.ts
 type Scalar = string | number | bigint | boolean | Date;
 type Element<Value> = NonNullable<Value> extends readonly (infer Item)[] ? NonNullable<Item> : NonNullable<Value>;
@@ -9,16 +8,17 @@ type Compatible<Left, Right> = NonNullable<Left> extends readonly unknown[] ? No
 type ScalarCompatible<Left, Right> = [Element<Left> | Element<Right>] extends [Scalar] ? [Element<Left>] extends [never] ? true : [Element<Right>] extends [never] ? true : [Extract<Element<Left>, Element<Right>> | Extract<Element<Right>, Element<Left>>] extends [never] ? false : true : false;
 type CheckRelation<Registry extends CollectionRegistry, Name extends keyof Registry, Link extends Relationship> = Link["collection"] extends keyof Registry ? Link["from"] extends keyof QueryData<Registry[Name]> ? Link["to"] extends keyof QueryData<Registry[Link["collection"]]> ? Compatible<QueryData<Registry[Name]>[Link["from"]], QueryData<Registry[Link["collection"]]>[Link["to"]]> extends true ? never : "incompatible-relationship-fields" : "unknown-target-field" : "unknown-source-field" : "unknown-target-collection";
 /** Registry-level relationship checks require the complete inferred collection map. */
-type InvalidRelationships<Registry extends CollectionRegistry> = { [Name in keyof Registry]: { [Link in keyof RelationshipsOf<Registry[Name]>]: RelationshipsOf<Registry[Name]>[Link] extends Relationship ? CheckRelation<Registry, Name, RelationshipsOf<Registry[Name]>[Link]> : "invalid-relationship" }[keyof RelationshipsOf<Registry[Name]>] }[keyof Registry];
+type InvalidRelationships<Registry extends CollectionRegistry> = { [Name in keyof Registry]: { [Link in keyof RelationshipsOf<Registry[Name]>]: RelationshipsOf<Registry[Name]>[Link] extends Relationship ? CheckRelation<Registry, Name, RelationshipsOf<Registry[Name]>[Link]> : "invalid-relationship"; }[keyof RelationshipsOf<Registry[Name]>]; }[keyof Registry];
 //#endregion
 //#region src/query/select.d.ts
 /** A selection whose collection and selected result are inferred when from() is supplied. */
 type SelectFrom<Registry extends CollectionRegistry, Keys extends readonly string[]> = {
-  /** Binds the collection and rejects selected keys that are absent from its prepared data type. */from<Name extends keyof Registry & string>(collection: Name & (Exclude<Keys[number], keyof QueryData<Registry[NoInfer<Name>]>> extends never ? unknown : never)): Query<Registry, Name, Keys extends readonly [] ? QueryData<Registry[Name]> : { [Key in Keys[number]]-?: Key extends keyof QueryData<Registry[Name]> ? QueryData<Registry[Name]>[Key] : never }, true>;
+  /** Binds the collection and rejects selected keys that are absent from its prepared data type. */
+  from<Name extends keyof Registry & string>(collection: Name & (Exclude<Keys[number], keyof QueryData<Registry[NoInfer<Name>]>> extends never ? unknown : never)): Query<Registry, Name, Keys extends readonly [] ? QueryData<Registry[Name]> : { [Key in Keys[number]]-?: Key extends keyof QueryData<Registry[Name]> ? QueryData<Registry[Name]>[Key] : never; }, true>;
 };
 //#endregion
 //#region src/shared/errors.d.ts
-type ContentErrorCode = "entry-not-found" | "not-renderable" | "source-error" | "validation-error" | "duplicate-id" | "invalid-reference" | "invalid-query" | "artifact-error" | "render-error";
+type ContentErrorCode = "variant-not-found" | "not-renderable" | "source-error" | "validation-error" | "duplicate-id" | "invalid-reference" | "invalid-query" | "artifact-error" | "render-error";
 type ContentDiagnostic = {
   code: ContentErrorCode;
   message: string;
@@ -52,7 +52,8 @@ declare class ContentError extends Error {
 type QueryRecord = Record<string, unknown> & {
   id: string;
 };
-type ItemPayload = {
+/** The built-in side payload shared by an entry's `_body` and `_rendered` payloads. */
+type BuiltinPayload = {
   body?: string;
   rendered?: ContentRenderResult;
   markdown?: string;
@@ -60,7 +61,8 @@ type ItemPayload = {
 type PreparedCollection = {
   records: readonly QueryRecord[];
   relationships: Record<string, Relationship>;
-  payloads: ReadonlyMap<string, () => Promise<ItemPayload>>;
+  /** Lazy built-in payloads, present only for entries with a body or rendered output. */
+  builtins: ReadonlyMap<string, () => Promise<BuiltinPayload>>;
   sources?: ReadonlyMap<string, string | undefined>;
 };
 type PreparedRevision = {
@@ -68,10 +70,17 @@ type PreparedRevision = {
   collections: Record<string, PreparedCollection>;
   relations: Map<string, Map<string, readonly QueryRecord[]>>;
   active: number;
-  payloadCache: Map<string, Promise<ItemPayload>>;
+  payloadCache: Map<string, Promise<BuiltinPayload>>;
   renderCache: Map<string, Promise<ContentRenderResult>>;
   renderMarkdown?: (body: string) => Promise<ContentRenderResult>;
-  execute?: (plan: QueryPlan, terminal: "all" | "first" | "count") => Promise<unknown>;
+  execute?: (plan: QueryPlan, terminal: "all" | "first" | "count", requests: PayloadRequest[]) => Promise<unknown>;
+};
+/** A projected row awaiting the payloads its query scope requested. */
+type PayloadRequest = {
+  target: Record<string, unknown>;
+  collection: string;
+  id: string;
+  payloads: NonNullable<QueryPlan["payloads"]>;
 };
 type ContentState = {
   revision?: PreparedRevision;
@@ -81,11 +90,12 @@ type ContentState = {
 //#endregion
 //#region src/runtime/content.d.ts
 type ContentMethods<Registry extends CollectionRegistry = {}> = {
-  /** Starts a SQL-ordered fluent query; field names are checked against the collection in from(). */select<const Keys extends readonly string[]>(...fields: Keys): SelectFrom<Registry, Keys>; /** Collection-scoped relational queries with typed columns, relationships, and object filters. */
-  readonly query: RelationalQueries<Registry>; /** Counts matching entries before pagination, like the fluent count terminal. */
-  count<Name extends keyof Registry & string>(collection: Name, options?: RelationalCountOptions<Registry, Name>): Promise<number>; /** Reads retained raw text separately from prepared metadata; missing entries reject. */
-  readBody(collection: keyof Registry & string, id: string): Promise<string | undefined>; /** Loads supplied output or renders captured Markdown, returning detached HTML and headings. */
-  render(collection: keyof Registry & string, id: string): Promise<ContentRenderResult>;
+  /** Starts a SQL-ordered fluent query; field names are checked against the collection in from(). */
+  select<const Keys extends readonly string[]>(...fields: Keys): SelectFrom<Registry, Keys>;
+  /** Collection-scoped relational queries with typed columns, relationships, payloads, and filters. */
+  readonly query: RelationalQueries<Registry>;
+  /** Counts matching entries before pagination, like the fluent count terminal. */
+  count<Name extends keyof Registry & string>(collection: Name, options?: RelationalCountOptions<Registry, Name>): Promise<number>;
 };
 type Content<Registry extends CollectionRegistry = {}> = InvalidRelationships<Registry> extends never ? ContentMethods<Registry> : {
   readonly invalidRelationships: InvalidRelationships<Registry>;