content-query 0.2.0 → 0.4.0

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

@@ -1,8 +1,9 @@
-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 { c as normalizeSnapshot, d as builtinLoader, f as builtinPath, l as renderedPayload, n as loadGlob, s as isRecord, u as validate } from "./glob-BXJuwy_p.mjs";
+import { i as groupDiagnostics, n as contentError, o as payloadIdentity, r as describeCause, s as withContext, t as ContentError } from "./errors-Bfd0R4_P.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 { n as loadFile } from "./file-DSOcdFj0.mjs";
+import { a as isRelationship, i as variantKey, n as createRuntime, o as prepareRelationships, r as isQueryStyle, s as CODEC_VERSION } from "./content-BXrgP7nL.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";
@@ -35,7 +36,8 @@ async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 	const manifest = {
 		version: 2,
 		codec: CODEC_VERSION,
-		collections: revision.registry
+		collections: revision.registry,
+		...revision.queryStyle ? { queryStyle: revision.queryStyle } : {}
 	};
 	const imports = [];
 	const names = [];
@@ -82,12 +84,34 @@ async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 			payloads.push(`[${JSON.stringify(id)}]: () => import(${JSON.stringify(`./entries/${key}.js`)})`);
 		}
 		flushBatch();
+		const custom = [];
+		for (const [payload, entries] of collection.payloads ?? []) {
+			const payloadDirectory = `payloads/${directoryName(payload)}`;
+			const rows = [];
+			for (const [id, variants] of entries) {
+				const loaders = [];
+				for (const [variant, load] of variants) {
+					const encoded = load.encoded ?? encode(await load());
+					const key = digest([
+						name,
+						payload,
+						id,
+						variant,
+						encoded
+					]);
+					publishPayload(`${directory}/${payloadDirectory}/${key}.js`, `export default ${JSON.stringify(encoded)};\n`);
+					loaders.push(`${JSON.stringify(variant)}: () => import(${JSON.stringify(`./${payloadDirectory}/${key}.js`)})`);
+				}
+				rows.push(`${JSON.stringify(id)}: { ${loaders.join(", ")} }`);
+			}
+			custom.push(`${JSON.stringify(payload)}: {\n${rows.join(",\n")}\n}`);
+		}
 		const recordSource = JSON.stringify(collection.records.map(encode));
 		const compressedRecords = compactJson(recordSource);
 		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}, builtins: ${loading} };\n`;
+		const code = `${loaders}export default { records: ${compressedRecords ? `decodeCompressed(${compressedRecords})` : recordSource}, builtins: ${loading}${custom.length ? `, payloads: {\n${custom.join(",\n")}\n}` : ""} };\n`;
 		const index = `index-${digest(code)}.js`;
 		modules.set(`${directory}/${index}`, code);
 		modules.set(`${directory}/index.js`, `export { default } from ${JSON.stringify(`./${index}`)};\n`);
@@ -102,13 +126,39 @@ async function revisionModules(revision, { payloadChunkBytes = 0 } = {}) {
 }
 //#endregion
 //#region src/artifacts/declarations.ts
-/** Generates type-only consumer bindings without loading schemas or adding runtime imports. */
+/**
+* Generates type-only consumer bindings without loading schemas or adding runtime imports.
+*
+* The registry and the optional `queryStyle` both come from the config module's types, so a
+* literal `export const queryStyle = "relational"` narrows `content` without a rebuild. A missing
+* export, or one typed as the whole `QueryStyle` union, allows both query styles.
+*
+* @param directory - Directory that will contain the declaration file.
+* @param config - Absolute path of content-query.config.
+* @returns Declaration source for `server.d.ts`.
+*/
 function contentDeclarations(directory, config) {
 	let relative = path.relative(directory, config).replace(/\\/g, "/");
 	if (!relative.startsWith(".")) relative = `./${relative}`;
-	return `type Registry = typeof import(${JSON.stringify(relative)}).collections;\nexport type CollectionKey = keyof Registry & string;\nexport type CollectionData<Name extends CollectionKey> = import("content-query").QueryData<Registry[Name]>;\nexport type Collections = { [Name in CollectionKey]: CollectionData<Name> };\nexport declare const content: import("content-query/runtime").Content<Registry>;\n`;
+	const source = JSON.stringify(relative);
+	return [
+		`type Registry = typeof import(${source}).collections;`,
+		`type ConfiguredQueryStyle = typeof import(${source}) extends { queryStyle: infer Style extends import("content-query/runtime").QueryStyle } ? Style : import("content-query/runtime").QueryStyle;`,
+		`export type CollectionKey = keyof Registry & string;`,
+		`export type CollectionData<Name extends CollectionKey> = import("content-query").QueryData<Registry[Name]>;`,
+		`export type Collections = { [Name in CollectionKey]: CollectionData<Name> };`,
+		`export type CollectionPayload<Name extends CollectionKey, Payload extends keyof import("content-query").PayloadsOf<Registry[Name]>> = import("content-query").PayloadData<Registry[Name], Payload>;`,
+		`export declare const content: import("content-query/runtime").Content<Registry, ConfiguredQueryStyle>;`,
+		``
+	].join("\n");
 }
-/** Declares project-bound virtual server types and the framework-neutral development bridge. */
+/**
+* Declares project-bound virtual server types and the framework-neutral development bridge.
+*
+* @param directory - Directory that will contain the declaration file.
+* @param config - Absolute path of content-query.config.
+* @returns Declaration source for the `content-query:server` and `content-query:client` modules.
+*/
 function virtualDeclarations(directory, config) {
 	return `declare module "content-query:server" {\n${contentDeclarations(directory, config).replace("export declare const", "export const")}\n}\ndeclare module "content-query:client" {\n  export function onContentUpdate(callback: () => void | Promise<void>): () => void;\n}\n`;
 }
@@ -162,7 +212,7 @@ async function writeImmutable(filename, source) {
 		await rm(temporary, { force: true });
 	}
 }
-const immutableModule = /\/(?:entries\/[a-f0-9]{64}|index-[a-f0-9]{64})\.js$/;
+const immutableModule = /\/(?:entries\/[a-f0-9]{64}|payloads\/[^/]+\/[a-f0-9]{64}|index-[a-f0-9]{64})\.js$/;
 /** Lists one directory's entries, treating a missing directory or a file as empty. */
 async function entriesOf(directory) {
 	try {
@@ -196,9 +246,14 @@ async function pruneArtifacts(outDir, modules) {
 	for (const directory of await entriesOf(collections)) {
 		const owned = path.join(collections, directory);
 		const entries = path.join(owned, "entries");
+		const payloads = path.join(owned, "payloads");
+		const payloadDirectories = await entriesOf(payloads);
 		const candidates = [...(await entriesOf(owned)).map((name) => `collections/${directory}/${name}`), ...(await entriesOf(entries)).map((name) => `collections/${directory}/entries/${name}`)];
+		for (const payload of payloadDirectories) candidates.push(...(await entriesOf(path.join(payloads, payload))).map((name) => `collections/${directory}/payloads/${payload}/${name}`));
 		for (const filename of candidates) if ((immutableModule.test(`/${filename}`) || filename.endsWith(`/${directory}/index.js`)) && !modules.has(filename)) await rm(path.join(outDir, filename), { force: true });
 		await removeIfEmpty(entries);
+		for (const payload of payloadDirectories) await removeIfEmpty(path.join(payloads, payload));
+		await removeIfEmpty(payloads);
 		await removeIfEmpty(owned);
 	}
 }
@@ -243,21 +298,195 @@ function hasBuiltinPayloads(definition) {
 	return builtinLoader(definition.loader)?.kind !== "file";
 }
 /**
+* Describes a collection's custom payloads by their sorted variant keys. Underscore names belong
+* to built-ins, so an invalid declaration never shadows them; preparation reports it instead.
+*
+* @param definition - A collection definition.
+* @returns Payload descriptors keyed by custom payload name.
+*/
+function customPayloads(definition) {
+	return Object.fromEntries(Object.entries(definition.payloads ?? {}).filter(([name]) => !name.startsWith("_")).map(([name, payload]) => [name, { variants: Object.keys(payload?.variants ?? {}).sort() }]));
+}
+/**
 * 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.
+* @returns Relationship and payload descriptors for each collection, built-in and custom.
 */
 function queryRegistry(registry) {
 	return Object.fromEntries(Object.entries(registry).map(([name, definition]) => [name, {
 		relationships: definition.relationships ?? {},
-		payloads: hasBuiltinPayloads(definition) ? { ...builtinPayloads } : {}
+		payloads: {
+			...hasBuiltinPayloads(definition) ? builtinPayloads : {},
+			...customPayloads(definition)
+		}
 	}]));
 }
 //#endregion
+//#region src/shared/paths.ts
+/** Checks containment without confusing sibling prefixes, drive roots, or trailing separators. */
+function withinDirectory(directory, filename) {
+	const relative = path.relative(directory, filename);
+	return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+/** Resolves existing symlink ancestors even when the output directory does not exist yet. */
+async function canonicalPath(filename) {
+	try {
+		return await realpath(filename);
+	} catch (cause) {
+		if (!cause || typeof cause !== "object" || !("code" in cause) || cause.code !== "ENOENT") throw cause;
+		const parent = path.dirname(filename);
+		if (parent === filename) throw cause;
+		return path.join(await canonicalPath(parent), path.basename(filename));
+	}
+}
+//#endregion
+//#region src/preparation/files.ts
+/**
+* Finds the folder an entry's `files` helpers read from: the loader's `source.directory`, or the
+* folder of its `source.filePath`. Both are relative to the project root.
+*
+* @param root - The project root.
+* @param source - The entry's loader-supplied source metadata.
+* @returns The absolute folder, or undefined when the source names neither.
+*/
+function entryFolder(root, source) {
+	if (!source || typeof source !== "object") return;
+	const { directory, filePath } = source;
+	if (typeof directory === "string" && directory) return path.resolve(root, directory);
+	if (typeof filePath === "string" && filePath) return path.resolve(root, path.dirname(filePath));
+}
+/**
+* Creates tracked file helpers for one resolver call. Reads are scoped to the entry's folder and
+* the collection's shared directories, and each read is recorded as a dependency.
+*
+* @param options - The entry's roots, cancellation, and the dependency list to record into.
+* @returns The `files` object resolvers receive.
+*/
+function createEntryFiles(options) {
+	const { root, folder, shared, entry, signal, dependencies } = options;
+	const roots = [...folder ? [folder] : [], ...shared];
+	/** Resolves a path from the entry's folder and rejects one outside every allowed root. */
+	function resolve(filePath) {
+		if (typeof filePath !== "string" || !filePath) throw new ContentError({
+			code: "source-error",
+			message: "files helpers require a nonempty path."
+		});
+		if (!folder && !path.isAbsolute(filePath)) throw new ContentError({
+			code: "source-error",
+			message: `Entry "${entry}" has no folder for files helpers. glob() and file() entries use their file's folder, and custom loaders can set source.directory.`
+		});
+		const resolved = path.resolve(folder ?? root, filePath);
+		if (!roots.some((allowed) => withinDirectory(allowed, resolved))) throw new ContentError({
+			code: "source-error",
+			source: resolved,
+			message: `"${filePath}" is outside entry "${entry}"'s folder and the collection's sharedFiles directories.`
+		});
+		return resolved;
+	}
+	/** Reads a file and records it, reporting a missing or unreadable file as a source error. */
+	async function read(filePath, reader) {
+		const resolved = resolve(filePath);
+		dependencies.push({
+			kind: "file",
+			path: resolved
+		});
+		try {
+			return await reader(resolved);
+		} catch (cause) {
+			signal.throwIfAborted();
+			throw contentError(cause, {
+				code: "source-error",
+				source: resolved,
+				message: `Could not read "${filePath}": ${describeCause(cause)}`
+			});
+		}
+	}
+	/** Validates one helper entry's data, reporting failures against that file. */
+	async function entryOf(schema, value, filePath) {
+		const data = await validate(schema, value.data, { source: value.source });
+		return {
+			id: value.id,
+			data,
+			...value.body === void 0 ? {} : { body: value.body },
+			filePath
+		};
+	}
+	return {
+		async glob(globOptions) {
+			const { schema, base, ...loaderOptions } = globOptions ?? {};
+			const patterns = typeof loaderOptions.pattern === "string" ? [loaderOptions.pattern] : loaderOptions.pattern;
+			if (!Array.isArray(patterns) || patterns.some((pattern) => typeof pattern !== "string" || path.posix.isAbsolute(pattern.replace(/^!/, "")) || pattern.replace(/^!/, "").split("/").includes(".."))) throw new ContentError({
+				code: "source-error",
+				message: "files.glob() requires relative patterns that stay inside their base."
+			});
+			const directory = resolve(base ?? ".");
+			const options = {
+				...loaderOptions,
+				base: directory
+			};
+			dependencies.push({
+				kind: "glob",
+				base: directory,
+				options
+			});
+			const entries = await loadGlob({
+				kind: "glob",
+				options
+			}, root, signal, { warnEmpty: false });
+			const retained = loaderOptions.retainBody !== false;
+			return Promise.all(entries.map((value) => {
+				dependencies.push({
+					kind: "file",
+					path: value.source
+				});
+				return entryOf(schema, {
+					...value,
+					body: retained ? value.body : void 0
+				}, value.sourceData.filePath);
+			}));
+		},
+		async file(filePath, fileOptions = {}) {
+			const { schema, ...loaderOptions } = fileOptions;
+			const resolved = resolve(filePath);
+			dependencies.push({
+				kind: "file",
+				path: resolved
+			});
+			const descriptor = {
+				kind: "file",
+				filename: resolved,
+				options: loaderOptions
+			};
+			const entries = await loadFile(descriptor, root, signal);
+			const relative = path.relative(root, builtinPath(descriptor, root)).split(path.sep).join("/");
+			return Promise.all(entries.map((value) => entryOf(schema, value, relative)));
+		},
+		text(filePath) {
+			return read(filePath, (resolved) => readFile(resolved, {
+				encoding: "utf8",
+				signal
+			}));
+		},
+		bytes(filePath) {
+			return read(filePath, async (resolved) => new Uint8Array(await readFile(resolved, { signal })));
+		},
+		async renderMarkdown(body) {
+			const { html, headings } = await renderMarkdown(body);
+			return {
+				html,
+				metadata: { headings }
+			};
+		}
+	};
+}
+//#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) {
+/**
+* Prepares one immutable revision with loader-defined source metadata, aggregating failures.
+* `root` is the project root that entry folders and `sharedFiles` resolve against.
+*/
+async function prepareRevision(registry, sources, cache, signal, development, sourceDiagnostics = [], parsedData, { root = process.cwd() } = {}) {
 	const diagnostics = [...sourceDiagnostics];
 	const collections = Object.create(null);
 	for (const [collectionName, definition] of Object.entries(registry)) {
@@ -279,7 +508,18 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 			});
 			continue;
 		}
+		const payloadProblem = invalidPayloads(definition.payloads, declarationNames) ?? invalidSharedFiles(definition.sharedFiles);
+		if (payloadProblem) {
+			diagnostics.push({
+				code: "validation-error",
+				operation: "build",
+				collection: collectionName,
+				message: payloadProblem
+			});
+			continue;
+		}
 		const descriptor = builtinLoader(definition.loader);
+		const shared = (definition.sharedFiles ?? []).map((directory) => path.resolve(root, directory));
 		for (const entry of sources.get(collectionName)?.values() ?? []) {
 			signal.throwIfAborted();
 			const context = {
@@ -308,6 +548,15 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 				const metadata = detach(validated);
 				const values = Object.create(null);
 				const before = diagnostics.length;
+				const dependencies = [];
+				const files = createEntryFiles({
+					root,
+					folder: entryFolder(root, entry.sourceData),
+					shared,
+					entry: entry.id,
+					signal,
+					dependencies
+				});
 				for (const [field, computedField] of Object.entries(computed)) try {
 					const result = await computedField.resolve({
 						collection: collectionName,
@@ -315,6 +564,7 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 						source: detach(entry.sourceData),
 						data: detach(metadata),
 						readBody: async () => entry.body,
+						files,
 						signal
 					});
 					values[field] = await validate(computedField.schema, result, {
@@ -322,7 +572,7 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 						path: [field]
 					});
 				} catch (cause) {
-					diagnostics.push(...contentError(cause, {
+					diagnostics.push(...located(cause, {
 						...context,
 						path: [field],
 						code: "validation-error",
@@ -359,7 +609,8 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 					definition,
 					signature,
 					record,
-					payload
+					payload,
+					dependencies
 				});
 				records.push(record);
 				if (Object.keys(payload).length) builtins.set(entry.id, async () => payload);
@@ -393,9 +644,207 @@ async function prepareRevision(registry, sources, cache, signal, development, so
 	};
 	const failed = diagnostics.map((diagnostic) => diagnostic.collection);
 	if (!failed.includes(void 0)) diagnostics.push(...prepareRelationships(revision, new Set(failed)).flatMap((error) => error.diagnostics));
+	const unresolved = new Set(diagnostics.map((diagnostic) => diagnostic.collection));
+	if (!unresolved.has(void 0)) {
+		for (const [collectionName, definition] of Object.entries(registry)) if (!unresolved.has(collectionName) && Object.keys(definition.payloads ?? {}).length) collections[collectionName].payloads = await preparePayloads(collectionName, definition.payloads, collections[collectionName].records, sources.get(collectionName), cache, signal, diagnostics, {
+			root,
+			shared: (definition.sharedFiles ?? []).map((directory) => path.resolve(root, directory))
+		});
+	}
 	if (diagnostics.length) throw groupDiagnostics(diagnostics);
 	return revision;
 }
+/**
+* Checks custom payload declarations before any entry is prepared.
+*
+* @param payloads - The collection's payload declarations.
+* @param declarationNames - Computed field and relationship names the payloads must not repeat.
+* @returns A diagnostic message, or undefined when every declaration is valid.
+*/
+function invalidPayloads(payloads, declarationNames) {
+	if (payloads === void 0) return;
+	if (!payloads || typeof payloads !== "object" || Array.isArray(payloads)) return "Payloads must be an object of named payload declarations.";
+	for (const [name, declaration] of Object.entries(payloads)) {
+		if (!name || name.startsWith("_") || declarationNames.includes(name)) return `Custom payload "${name}" must be named without a leading "_" and must not repeat a computed field or relationship.`;
+		const { schema, resolve, variants, combinations, cache } = declaration ?? {};
+		if (!schema || typeof schema !== "object" || !("~standard" in schema) || typeof resolve !== "function") return `Payload "${name}" requires a schema and a resolve() function.`;
+		if (variants !== void 0 && (!variants || typeof variants !== "object" || Array.isArray(variants) || Object.entries(variants).some(([key, values]) => !key || (typeof values === "string" ? !values : !Array.isArray(values) || !values.every((value) => typeof value === "string" && value))))) return `Payload "${name}" variants must map each key to a data field name or a list of values.`;
+		if (combinations !== void 0 && (typeof combinations !== "function" || !Object.keys(variants ?? {}).length)) return `Payload "${name}" combinations() must be a function and requires declared variants.`;
+		if (cache !== void 0 && typeof cache !== "boolean") return `Payload "${name}" cache must be a boolean.`;
+	}
+}
+/**
+* Lists an entry's variant combinations: the cross product of each key's values, or the
+* declaration's validated `combinations()` override. A key's values come from a named string-array
+* field of the entry's data, where a missing value means none, or from a fixed list.
+* Combinations have sorted keys.
+*
+* @param name - The payload name, for error messages.
+* @param payload - The payload declaration.
+* @param context - The enumerator context for one entry.
+* @returns Distinct combinations; a payload without variants has exactly one, `{}`.
+*/
+async function variantCombinations(name, payload, context) {
+	const keys = Object.keys(payload.variants ?? {}).sort();
+	const values = Object.create(null);
+	for (const key of keys) {
+		const source = payload.variants[key];
+		const listed = typeof source === "string" ? context.data[source] ?? [] : source;
+		if (!Array.isArray(listed) || !listed.every((value) => typeof value === "string" && value)) {
+			const field = typeof source === "string" ? ` in field "${String(source)}"` : "";
+			throw new Error(`Variant "${key}" of payload "${name}" must list non-empty strings${field}.`);
+		}
+		values[key] = [...new Set(listed)];
+	}
+	let combinations;
+	if (payload.combinations) {
+		const listed = await payload.combinations({
+			...context,
+			variants: values
+		});
+		if (!listed || typeof listed !== "object" || !(Symbol.iterator in listed)) throw new Error(`Payload "${name}" combinations() must return an iterable of variants.`);
+		combinations = [...listed].map((combination) => {
+			const variant = combination;
+			if (!variant || typeof variant !== "object" || Object.keys(variant).length !== keys.length || keys.some((key) => !values[key].includes(variant[key]))) throw new Error(`Each combination of payload "${name}" must give every variant key (${keys.join(", ")}) one enumerated value.`);
+			return Object.fromEntries(keys.map((key) => [key, variant[key]]));
+		});
+	} else combinations = keys.reduce((partial, key) => partial.flatMap((variant) => values[key].map((value) => ({
+		...variant,
+		[key]: value
+	}))), [{}]);
+	return [...new Map(combinations.map((variant) => [variantKey(variant), variant])).values()];
+}
+/**
+* Adds the location of a resolver failure to every diagnostic that lacks it. A `files` helper error
+* keeps its own source file and field path; the entry, payload, and variant come from `location`.
+*
+* @param cause - The resolver failure.
+* @param location - The entry, and the payload and variant when resolving one.
+* @returns A contextual error whose diagnostics all name the location.
+*/
+function located(cause, location) {
+	if (!(cause instanceof ContentError)) return contentError(cause, location);
+	return groupDiagnostics(cause.diagnostics.map((diagnostic) => ({
+		...location,
+		...Object.fromEntries(Object.entries(diagnostic).filter(([, value]) => value !== void 0))
+	})));
+}
+/**
+* Checks a collection's `sharedFiles` directories.
+*
+* @param sharedFiles - The declared shared directories.
+* @returns A diagnostic message, or undefined when the declaration is valid.
+*/
+function invalidSharedFiles(sharedFiles) {
+	if (sharedFiles !== void 0 && (!Array.isArray(sharedFiles) || !sharedFiles.every((directory) => typeof directory === "string" && directory))) return "sharedFiles must list directories as nonempty strings.";
+}
+/**
+* Resolves, validates, and encodes a collection's custom payloads for every entry and variant.
+* Each variant is cached on its own with the files it read, so unchanged entries reuse every
+* variant and an invalidated variant re-resolves alone.
+*
+* @returns Lazy loaders by payload name, entry ID, and canonical variant key.
+*/
+async function preparePayloads(collection, payloads, records, sources, cache, signal, diagnostics, roots) {
+	const table = new Map(Object.keys(payloads).map((name) => [name, /* @__PURE__ */ new Map()]));
+	for (const record of records) {
+		const entry = sources?.get(record.id);
+		const cached = cache.get(JSON.stringify([collection, record.id]));
+		const data = Object.fromEntries(Object.entries(record).filter(([field]) => field !== "id"));
+		const folder = entryFolder(roots.root, entry?.sourceData);
+		/** Each resolver receives its own copies, so it cannot change another's inputs. */
+		const context = () => ({
+			collection,
+			id: record.id,
+			source: detach(entry?.sourceData),
+			data: detach(data),
+			signal
+		});
+		for (const [name, payload] of Object.entries(payloads)) {
+			signal.throwIfAborted();
+			const reuse = payload.cache !== false;
+			const previous = reuse ? cached?.payloads?.get(name) : void 0;
+			const base = {
+				code: "validation-error",
+				operation: "build",
+				collection,
+				id: record.id,
+				source: entry?.source,
+				payload: name,
+				message: ""
+			};
+			let combinations = previous?.combinations;
+			if (!combinations) try {
+				combinations = await variantCombinations(name, payload, {
+					...context(),
+					variants: {}
+				});
+			} catch (cause) {
+				diagnostics.push(...contentError(cause, {
+					...base,
+					message: cause instanceof Error ? cause.message : `Payload "${name}" variants failed.`
+				}).diagnostics);
+				continue;
+			}
+			const nodes = /* @__PURE__ */ new Map();
+			let complete = true;
+			for (const variant of combinations) {
+				signal.throwIfAborted();
+				const key = variantKey(variant);
+				const reused = previous?.nodes.get(key);
+				if (reused) {
+					nodes.set(key, reused);
+					continue;
+				}
+				const location = {
+					...base,
+					variant
+				};
+				const dependencies = [];
+				try {
+					const result = await payload.resolve({
+						...context(),
+						variant: { ...variant },
+						readBody: async () => entry?.body,
+						files: createEntryFiles({
+							root: roots.root,
+							folder,
+							shared: roots.shared,
+							entry: record.id,
+							signal,
+							dependencies
+						})
+					});
+					const value = detach(await validate(payload.schema, result, location));
+					nodes.set(key, {
+						value,
+						encoded: encode(value),
+						dependencies
+					});
+				} catch (cause) {
+					complete = false;
+					const formatted = cause && typeof cause === "object" && "path" in cause && typeof cause.path === "string" ? cause.path : "";
+					diagnostics.push(...located(cause, {
+						...location,
+						path: formatted ? valuePath(formatted) : void 0,
+						message: `Payload ${payloadIdentity(name, variant)} failed: ${cause instanceof Error ? cause.message : String(cause)}${formatted ? ` (at ${formatted})` : ""}`
+					}).diagnostics);
+				}
+			}
+			signal.throwIfAborted();
+			if (cached && reuse) {
+				cached.payloads ??= /* @__PURE__ */ new Map();
+				cached.payloads.set(name, {
+					combinations,
+					nodes
+				});
+			}
+			if (!complete) continue;
+			table.get(name).set(record.id, new Map([...nodes].map(([key, node]) => [key, Object.assign(async () => node.value, { encoded: node.encoded })])));
+		}
+	}
+	return table;
+}
 //#endregion
 //#region src/preparation/config.ts
 /** Loads build-only configuration without retaining a previous config module value. */
@@ -418,6 +867,7 @@ async function loadRegistry(config) {
 		async: true,
 		forceTranspile: true
 	});
+	if (imported.queryStyle !== void 0 && !isQueryStyle(imported.queryStyle)) throw new Error("content-query.config queryStyle must be \"fluent\" or \"relational\".");
 	if (imported.loaderConfig !== void 0 && (!imported.loaderConfig || typeof imported.loaderConfig !== "object" || Array.isArray(imported.loaderConfig))) throw new Error("content-query.config loaderConfig must be an object.");
 	const registry = imported.collections;
 	if (!registry || typeof registry !== "object" || Array.isArray(registry)) throw new Error("content-query.config must export a collections registry.");
@@ -425,28 +875,11 @@ async function loadRegistry(config) {
 	return {
 		registry,
 		dependencies,
-		loaderConfig: imported.loaderConfig
+		loaderConfig: imported.loaderConfig,
+		queryStyle: imported.queryStyle
 	};
 }
 //#endregion
-//#region src/shared/paths.ts
-/** Checks containment without confusing sibling prefixes, drive roots, or trailing separators. */
-function withinDirectory(directory, filename) {
-	const relative = path.relative(directory, filename);
-	return relative === "" || relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
-}
-/** Resolves existing symlink ancestors even when the output directory does not exist yet. */
-async function canonicalPath(filename) {
-	try {
-		return await realpath(filename);
-	} catch (cause) {
-		if (!cause || typeof cause !== "object" || !("code" in cause) || cause.code !== "ENOENT") throw cause;
-		const parent = path.dirname(filename);
-		if (parent === filename) throw cause;
-		return path.join(await canonicalPath(parent), path.basename(filename));
-	}
-}
-//#endregion
 //#region src/loaders/match.ts
 const matchers = /* @__PURE__ */ new WeakMap();
 /**
@@ -491,6 +924,7 @@ const awaitWriteFinish = {
 	stabilityThreshold: 50,
 	pollInterval: 10
 };
+const NEW_DIRECTORY_RECHECKS_MS = [100, 1e3];
 /** Finds an existing ancestor so watching also detects a missing base directory's creation. */
 async function watchAncestor(filename) {
 	let ancestor = filename;
@@ -552,6 +986,7 @@ async function watchProject(options, register) {
 	});
 	register(watcher);
 	watcher.on("all", (event, filename) => {
+		options.dependencyChanged?.(event, filename);
 		if (event === "addDir") return;
 		if (configDependency(options, filename)) {
 			options.configChanged();
@@ -615,12 +1050,188 @@ async function watchSources(options, register) {
 			}
 			if (dedicated) {
 				external.on("all", changed);
+				if (external !== shared) external.on("all", (event, filename) => options.dependencyChanged?.(event, filename));
 				external.on("error", (cause) => options.failed(cause));
+				if (builtin.kind === "glob") recheckNewDirectories(external, shared, (filename) => affectsSnapshot(builtin, target, "add", filename), () => options.invalidated(name), register);
 				await ready(external);
 			}
 		}
 	}
 }
+/**
+* Invalidates a glob collection when a new directory holds matching files that no watcher event
+* reported. Chokidar subscribes to a new directory only after reading it, so a file created in
+* that gap is otherwise missed until something else reloads the collection.
+*
+* @param directories - The watcher that reports new directories under the glob base.
+* @param shared - The project watcher, which reports ordinary files when it covers the base.
+* @param matches - Whether a file belongs to the collection's snapshot.
+* @param invalidate - Reloads the collection from disk.
+* @param register - Registers cleanup for pending rechecks and listeners.
+*/
+function recheckNewDirectories(directories, shared, matches, invalidate, register) {
+	const pending = /* @__PURE__ */ new Set();
+	const reported = /* @__PURE__ */ new Set();
+	let closed = false;
+	/** Records added or changed files while a recheck could otherwise report them twice. */
+	function track(event, filename) {
+		if (pending.size && (event === "add" || event === "change")) reported.add(path.resolve(filename));
+	}
+	/** Reloads only when the directory holds a matching file that no event reported. */
+	async function recheck(directory) {
+		let files;
+		try {
+			files = (await readdir(directory, {
+				recursive: true,
+				withFileTypes: true
+			})).filter((entry) => entry.isFile()).map((entry) => path.resolve(entry.parentPath, entry.name));
+		} catch {
+			return;
+		}
+		if (!closed && files.some((filename) => matches(filename) && !reported.has(filename))) invalidate();
+	}
+	/** Schedules rechecks for a newly created directory. */
+	function added(directory) {
+		for (const delay of NEW_DIRECTORY_RECHECKS_MS) {
+			const timer = setTimeout(() => {
+				recheck(directory).finally(() => {
+					pending.delete(timer);
+					if (!pending.size) reported.clear();
+				});
+			}, delay);
+			timer.unref();
+			pending.add(timer);
+		}
+	}
+	directories.on("all", track);
+	directories.on("addDir", added);
+	shared?.on("all", track);
+	register(() => {
+		closed = true;
+		directories.off("all", track);
+		directories.off("addDir", added);
+		shared?.off("all", track);
+		pending.forEach(clearTimeout);
+		pending.clear();
+		reported.clear();
+	});
+}
+/**
+* Watches files and directories that resolvers read when no other watcher reports them: paths
+* outside the project root or below a directory the project watcher ignores, such as `dist/`.
+*
+* @param options - Watch options with the project root and the dependency callback.
+* @returns `add()` to watch further dependency paths, and `close()` to stop watching.
+*/
+function watchDependencies(options) {
+	const ignoredByProject = projectIgnored(options);
+	const watched = /* @__PURE__ */ new Set();
+	let watcher;
+	return {
+		add(paths) {
+			const uncovered = [...paths].filter((filename) => !watched.has(filename) && (ignoredByProject(filename) || !(withinDirectory(options.root, filename) || withinDirectory(path.dirname(options.config), filename))));
+			if (!uncovered.length) return;
+			uncovered.forEach((filename) => watched.add(filename));
+			if (watcher) {
+				watcher.add(uncovered);
+				return;
+			}
+			watcher = watch(uncovered, {
+				ignoreInitial: true,
+				awaitWriteFinish
+			});
+			watcher.on("all", (event, filename) => options.dependencyChanged?.(event, filename));
+			watcher.on("error", (cause) => options.failed(cause));
+		},
+		async close() {
+			await watcher?.close();
+		}
+	};
+}
+//#endregion
+//#region src/preparation/dependencies.ts
+/**
+* Indexes every file and glob that cached entries and payload variants read.
+*
+* @param cache - The preparation cache, whose nodes record their dependencies.
+* @returns A reverse index from files and globs to nodes.
+*/
+function dependencyIndex(cache) {
+	const index = {
+		files: /* @__PURE__ */ new Map(),
+		globs: []
+	};
+	/** Records one node's dependencies. */
+	function add(node, dependencies) {
+		for (const dependency of dependencies) if (dependency.kind === "file") {
+			const nodes = index.files.get(dependency.path);
+			if (nodes) nodes.push(node);
+			else index.files.set(dependency.path, [node]);
+		} else index.globs.push({
+			base: dependency.base,
+			options: dependency.options,
+			node
+		});
+	}
+	for (const [key, entry] of cache) {
+		add({ key }, entry.dependencies);
+		for (const [payload, cached] of entry.payloads ?? []) for (const [variant, node] of cached.nodes) add({
+			key,
+			payload,
+			variant
+		}, node.dependencies);
+	}
+	return index;
+}
+/**
+* Finds the nodes a file event affects: nodes that read the file, nodes whose glob gains or loses
+* a match, nodes whose glob base gains a directory, and, for a removed directory, nodes that read
+* anything inside it.
+*
+* @param index - The dependency index.
+* @param event - The watcher event, such as `add`, `change`, `unlink`, or `unlinkDir`.
+* @param filename - The affected path.
+* @returns Distinct affected nodes.
+*/
+function dependents(index, event, filename) {
+	const resolved = path.resolve(filename);
+	const found = /* @__PURE__ */ new Map();
+	/** Adds a node once. */
+	const include = (node) => found.set(JSON.stringify([
+		node.key,
+		node.payload,
+		node.variant
+	]), node);
+	for (const node of index.files.get(resolved) ?? []) include(node);
+	if (event === "unlinkDir") {
+		for (const [file, nodes] of index.files) if (withinDirectory(resolved, file)) nodes.forEach(include);
+	}
+	for (const glob of index.globs) if (event === "addDir" ? resolved !== glob.base && withinDirectory(glob.base, resolved) : affectsSnapshot({
+		kind: "glob",
+		options: glob.options
+	}, glob.base, event, resolved)) include(glob.node);
+	return [...found.values()];
+}
+/**
+* Drops affected nodes from the cache, so the next preparation resolves them again. An entry node
+* drops the entry's whole cache record; a payload node drops only that variant.
+*
+* @param cache - The preparation cache.
+* @param nodes - The nodes to invalidate.
+*/
+function invalidateNodes(cache, nodes) {
+	for (const node of nodes) if (node.payload === void 0) cache.delete(node.key);
+	else cache.get(node.key)?.payloads?.get(node.payload)?.nodes.delete(node.variant);
+}
+/**
+* Lists the paths that dependencies need watched: each read file and each glob base.
+*
+* @param index - The dependency index.
+* @returns Distinct absolute paths.
+*/
+function dependencyPaths(index) {
+	return [.../* @__PURE__ */ new Set([...index.files.keys(), ...index.globs.map((glob) => glob.base)])];
+}
 //#endregion
 //#region src/preparation/loaders/context.ts
 /** Supplies portable filesystem defaults and fails explicitly for unavailable Astro settings. */
@@ -1011,7 +1622,13 @@ function sessionInternals(session) {
 	if (!internal) throw new Error("Unknown ContentQuery session.");
 	return internal;
 }
-/** Creates a preparation session with ordered source commands and atomic revision publication. */
+/**
+* Creates a preparation session with ordered source commands and atomic revision publication.
+*
+* @param options - Root, configuration, watch, and publication settings.
+* @returns A session whose `content` is typed by `Style`; each published revision carries the
+* configured `queryStyle`, which the runtime enforces.
+*/
 async function createSession(options) {
 	options = {
 		...options,
@@ -1020,9 +1637,47 @@ async function createSession(options) {
 		outDir: path.resolve(options.root, options.outDir)
 	};
 	const state = {};
+	const sourceListeners = /* @__PURE__ */ new Set();
+	const sourceSnapshots = /* @__PURE__ */ new WeakMap();
+	const sourceOwner = randomUUID();
+	let sourceVersion = 0;
+	/** Detaches and freezes integration metadata without exposing prepared payloads or schemas. */
+	function sources() {
+		if (state.error) throw state.error;
+		if (!state.revision) throw new ContentError({
+			code: "artifact-error",
+			message: "No prepared source revision is available."
+		});
+		let snapshot = sourceSnapshots.get(state.revision);
+		if (!snapshot) {
+			snapshot = Object.freeze({
+				revision: `${sourceOwner}:${++sourceVersion}`,
+				entries: Object.freeze(Object.entries(state.revision.collections).flatMap(([collection, prepared]) => prepared.records.map(({ id }) => {
+					const filePath = prepared.sources?.get(id);
+					return Object.freeze({
+						collection,
+						id,
+						...filePath === void 0 ? {} : { filePath }
+					});
+				})))
+			});
+			sourceSnapshots.set(state.revision, snapshot);
+		}
+		return snapshot;
+	}
+	/** Keeps a consumer notification failure from corrupting successfully prepared content. */
+	function notifySources(event) {
+		const listeners = [...sourceListeners];
+		for (const listener of listeners) try {
+			listener(event);
+		} catch (cause) {
+			console.error("[content-query] Source subscriber failed", cause);
+		}
+	}
 	let registry = {};
 	let loaders = /* @__PURE__ */ new Map();
 	let configDependencies;
+	let queryStyle;
 	let configurationError;
 	const candidates = /* @__PURE__ */ new Map();
 	const cache = /* @__PURE__ */ new Map();
@@ -1049,11 +1704,26 @@ async function createSession(options) {
 			kind: "invalidate",
 			collection
 		}),
+		dependencyChanged: (event, filename) => dependencyChanged(event, filename),
 		failed: (cause) => enqueue({
 			kind: "error",
 			cause
 		})
 	};
+	let index;
+	let preparing = false;
+	const recentEvents = [];
+	const dependencyWatcher = options.watch ? watchDependencies(watchOptions) : void 0;
+	/** Invalidates only the cached nodes that read a changed file. */
+	function dependencyChanged(event, filename) {
+		if (preparing) recentEvents.push([event, filename]);
+		index ??= dependencyIndex(cache);
+		const nodes = dependents(index, event, filename);
+		if (nodes.length) enqueue({
+			kind: "payloads",
+			nodes
+		});
+	}
 	/** Queues ordered notifications and makes any in-flight preparation obsolete. */
 	function enqueue(command) {
 		if (disposed) return;
@@ -1084,6 +1754,10 @@ async function createSession(options) {
 			message: cause instanceof Error ? cause.message : "Content preparation failed."
 		});
 		options.change?.(state);
+		notifySources({
+			type: "error",
+			error: state.error
+		});
 	}
 	/** Aborts an owned subscription group and attempts every cleanup even when one fails. */
 	async function releaseResources(controller, handlers) {
@@ -1103,7 +1777,8 @@ async function createSession(options) {
 		const loaded = options.registry ? {
 			registry: options.registry,
 			dependencies: /* @__PURE__ */ new Set(),
-			loaderConfig: void 0
+			loaderConfig: void 0,
+			queryStyle: options.queryStyle
 		} : await loadRegistry(options.config);
 		const nextSubscriptions = new AbortController();
 		const nextCleanups = [];
@@ -1188,9 +1863,11 @@ async function createSession(options) {
 		registry = nextRegistry;
 		loaders = nextLoaders;
 		configDependencies = loaded.dependencies;
+		queryStyle = loaded.queryStyle;
 		state.registry = queryRegistry(registry);
 		candidates.clear();
 		cache.clear();
+		index = void 0;
 		loadFailures.clear();
 		configurationError = void 0;
 		installed = true;
@@ -1198,6 +1875,17 @@ async function createSession(options) {
 	}
 	/** Acquires invalidated snapshots and publishes only the complete current attempt. */
 	async function prepare(names) {
+		preparing = true;
+		try {
+			await prepareAttempt(names);
+		} finally {
+			preparing = false;
+			index = void 0;
+			for (const [event, filename] of recentEvents.splice(0)) dependencyChanged(event, filename);
+		}
+	}
+	/** Acquires snapshots, prepares, and publishes one attempt. */
+	async function prepareAttempt(names) {
 		const currentGeneration = generation;
 		attempt = new AbortController();
 		const signal = attempt.signal;
@@ -1222,13 +1910,20 @@ async function createSession(options) {
 		});
 		try {
 			const failures = [...loadFailures.values()];
-			const revision = await prepareRevision(registry, candidates, cache, signal, options.watch, failures.flatMap((error) => error.diagnostics), new Map([...loaders].map(([name, loader]) => [name, loader.parsed])));
+			const style = queryStyle;
+			const revision = await prepareRevision(registry, candidates, cache, signal, options.watch, failures.flatMap((error) => error.diagnostics), new Map([...loaders].map(([name, loader]) => [name, loader.parsed])), { root: options.root });
 			if (disposed || currentGeneration !== generation) return;
+			if (style) revision.queryStyle = style;
 			await options.publish?.(revision, registry, signal);
 			if (disposed || currentGeneration !== generation) return;
 			state.revision = revision;
 			state.error = void 0;
+			dependencyWatcher?.add(dependencyPaths(index = dependencyIndex(cache)));
 			options.change?.(state);
+			notifySources({
+				type: "ready",
+				snapshot: sources()
+			});
 		} catch (cause) {
 			if (!disposed && currentGeneration === generation) fail(cause);
 		}
@@ -1261,6 +1956,10 @@ async function createSession(options) {
 					await configure(false);
 					for (const name of Object.keys(registry)) stale.add(name);
 				} else if (command.kind === "invalidate") stale.add(command.collection);
+				else if (command.kind === "payloads") {
+					invalidateNodes(cache, command.nodes);
+					index = void 0;
+				}
 			} catch (cause) {
 				if (command.kind === "config") configurationError = contentError(cause, {
 					code: "source-error",
@@ -1282,9 +1981,14 @@ async function createSession(options) {
 	async function dispose() {
 		if (disposed) return;
 		disposed = true;
+		sourceListeners.clear();
 		generation++;
 		attempt?.abort();
-		const failed = (await Promise.allSettled([watcher?.close() ?? Promise.resolve(), releaseSubscriptions()])).find((result) => result.status === "rejected");
+		const failed = (await Promise.allSettled([
+			watcher?.close() ?? Promise.resolve(),
+			dependencyWatcher?.close() ?? Promise.resolve(),
+			releaseSubscriptions()
+		])).find((result) => result.status === "rejected");
 		if (failed?.status === "rejected") throw contentError(failed.reason, {
 			code: "source-error",
 			operation: "dispose",
@@ -1293,6 +1997,14 @@ async function createSession(options) {
 	}
 	const session = {
 		content: createRuntime(state),
+		sources,
+		subscribe(listener) {
+			if (disposed) throw new Error("Content session has been disposed.");
+			sourceListeners.add(listener);
+			return () => {
+				sourceListeners.delete(listener);
+			};
+		},
 		dispose
 	};
 	internals.set(session, {
@@ -1386,11 +2098,23 @@ assertServerOnly();
 /**
 * Builds content independently of a bundler; bind the registry through an erased type import.
 * Generated watch sessions prune previous-run artifacts after their first successful publication.
+*
+* @param arguments_ - Optional build options.
+* @returns A session whose `content` exposes the root query APIs allowed by `Style`. Pass
+* `typeof queryStyle` from the config to type it; the configured `queryStyle` is always enforced
+* at runtime.
 */
 async function buildContent(...arguments_) {
 	return buildAtRoot(process.cwd(), arguments_[0] ?? {});
 }
-/** Resolves host paths and prunes previous-run artifacts on the first successful publication. */
+/**
+* Resolves host paths and prunes previous-run artifacts on the first successful publication.
+*
+* @param root - Application root that relative config and output paths resolve against.
+* @param options - Build options.
+* @param change - Optional state observer for host integrations.
+* @returns A session typed by `Registry` and `Style`.
+*/
 async function buildAtRoot(root, options, change) {
 	const { backend = "generated", watch = false } = options;
 	if (!["generated", "in-memory"].includes(backend) || typeof watch !== "boolean" || options.config !== void 0 && typeof options.config !== "string" || options.outDir !== void 0 && typeof options.outDir !== "string") throw new ContentError({